bf-clarify

specclaw bf-clarify

First, run specclaw-ensure-init .specclaw — idempotently creates .specclaw/ if it doesn't exist (silent if already initialized; auto-inits using the current directory's basename as the project name).

Turn the implicit uncertainty in .specclaw/analysis/*.md, plus the shaping questions no amount of code extraction can surface, into one explicit, numbered decision record. Read-only side-command — no specclaw-validate-change call, no <change> involved, matching the analyze/architecture/domain/rebuild-plan pattern.

Three question families share one clarifications.md and one --resolve pipeline — see templates/clarifications.md's HTML comment for the authoritative field-by-field breakdown:

• CQ-NNN — extracted from .specclaw/analysis/*.md by the extraction agent (unchanged from before this upgrade). Allocated per-repo, in extraction order.
• SQ-NNN — the standard bank (references/clarify-standard-questions.md, shipped with the plugin). IDs are fixed by the bank file itself, not allocated per-repo — SQ-001 means "target platform" in every project. Type/Blocking/Options/Proposed default are spliced in verbatim from the bank file by render, identical everywhere; only Finding/Why it matters/Source/Answer are project-specific.
• UQ-NNN — per-repo custom questions from .specclaw/analysis/custom-questions.md, ingested by render directly (no agent involved). Allocated per-repo, in file order. render scaffolds this file itself: the first time a Mode A run (default or --bank-only) finds nothing at .specclaw/analysis/custom-questions.md, it copies templates/custom-questions.md there verbatim, and the run summary reports the scaffold. Edit the scaffolded file and re-run to turn its questions into real UQ-NNNs. The invariant that matters most: once anything exists at that path — even an empty file, even a malformed one — it is never overwritten, re-rendered, or otherwise touched again, by any later run, no matter how it got there or what it contains. It becomes user-authored the moment it exists. De-duplicated by each question's original heading text, recorded in its Source field — editing an already-ingested heading's wording later does not retroactively rewrite the rendered UQ-NNN; it reads as a brand-new question with a new ID. Edit the rendered question in clarifications.md instead if you want to change it.

Three modes, chosen by which flag the user's invocation carries: --resolve selects Mode B, --options-pack selects Mode C, neither selects Mode A. Mode A additionally accepts --bank-only. The three flags are mutually exclusive — if an invocation carries more than one, say so and ask which was meant rather than picking one. Mode C runs no extraction, spawns no bank agent, and writes neither clarifications.md nor decisions.md: it is a read-and-package pass over what Modes A and B already wrote.