Add draftwise clarify [<feature>] — audit a product spec for gaps before drafting tech

[4nkur]

Summary

Adds a fourth drafting verb to the CLI that fits between new and tech. draftwise clarify reads an existing product-spec.md and prints an instruction for the host coding agent to audit it for gaps, walk the PM through them, and rewrite the spec in place.

The audit covers four categories:

• Ambiguities — vague acceptance criteria, terms used inconsistently, undefined scope boundaries.
• Untested assumptions — claims about user behavior, market, or technical feasibility that the spec hasn't validated.
• Internal contradictions — one section saying X, another saying not-X.
• Missing edge cases — empty data, errors, permissions, concurrency, large data.

Three-phase agent instruction: (1) read the spec end-to-end and surface 4-10 specific issues, each with a section/line pointer (skip the spec entirely if it's already tight); (2) walk the PM through them one-at-a-time, allowing defer / reject / answer; (3) rewrite the file in place — preserving YAML frontmatter and any sections the PM didn't touch. Hard rule built into the prompt: don't widen scope; if the PM's answer expands the feature, push back — that's a new spec, not a clarification.

Same auto-pick / multi-spec / unknown-slug ergonomics as tech and tasks. Errors when no .draftwise/ dir exists, when no product specs exist, or when the spec file is empty.

Why: drafted specs are uneven — some sections tight, others hand-wavy. Catching that before the technical spec gets drafted keeps the engineering plan from being built on a shaky foundation, and PMs don't have to re-litigate the same ambiguity in three files. Companion to a planned draftwise refine (different problem: re-synthesize after PM edits).

What changed

• New prompt src/ai/prompts/clarify.js with buildAgentInstruction(slug) returning the three-phase instruction.
• New command src/commands/clarify.js mirroring tech's shape (parseArgs, requireDraftwiseDir, listSpecs filter, auto-pick/positional/error paths).
• Routed via COMMANDS in src/index.js; help block now lists clarify [<feature>] between new and tech.
• 9 new tests in test/commands/clarify.test.js (missing .draftwise/, no specs, auto-pick single, slug arg, multi-spec error, unknown slug error, empty product spec error, four-category audit instruction content, parseArgs strict mode).
• CHANGELOG [Unreleased] ### Added entry; CLAUDE.md and README.md updated.

Test plan

• npm test — 250 passing
• npm run lint — clean
• Smoke: in a repo with one product spec, draftwise clarify auto-picks; with two specs and no slug, it errors with the available list; draftwise clarify <missing> errors with the available list.