brd-ground

Ground the BRD's requirement inventory against code and design: $ARGUMENTS

/brd-ground is the second command of the BRD-to-PRD flow (PA phase) — it takes the [BR#n] inventory /brd-intake wrote and checks its premises against real code and real design assets, at pinned commits, rather than letting a plausible-sounding claim stand unverified. Every finding is independently re-derived by a different agent before it counts as evidence (${CLAUDE_PLUGIN_ROOT}/references/grounding-format.md §8) — this command's whole job is to make that discipline happen, not to ground anything itself.

Usage: /brd-ground <BRD-KEY> [--depends-on <BRD-KEY>…] [--derivation-matrix|--no-derivation-matrix] [--no-design] [--no-docs] [--rebaseline]

Runs at either of the two levels <BRD-KEY> can name (${CLAUDE_PLUGIN_ROOT}/references/addressing.md §3) — a BRD that owns its source document, or one of its slices — grounding only the requirements that BRD claims. Unlike /brd-split, this command refuses neither: a slice is ground exactly as its parent is.

Standing rule, stated in full at Phase 4.5 and binding on every phase: documentation is a lead and a divergence finding — it is NEVER evidence for a [CG#n]. No finding this run writes may cite a documentation page in its evidence, under any verdict. A document is a claim about behaviour, not the behaviour.

Phase 0 — Resolve inputs and gate on main

1. <BRD-KEY> (mandatory). Parse the first non-flag token; validate with key-valid (${CLAUDE_PLUGIN_ROOT}/references/addressing.md §1). If absent or invalid, stop: BRD_GROUND_NEEDS_KEY: /brd-ground needs a BRD key (shape ^[A-Z][A-Z0-9_]*(-\d+)+$) — re-run '/dev-workflows:brd-ground <KEY>'.
2. Flags. --depends-on <BRD-KEY> — repeatable, each consuming the next token; validate each with key-valid and drop (warn, do not stop the run) any that fail shape. --no-design — boolean, skips Phase 5's design-grounder step. --no-docs — boolean, turns documentation grounding off for this run (Phase 1 step 0, Phase 4.5). --rebaseline — boolean, see Phase 3. --derivation-matrix / --no-derivation-matrix — mutually exclusive; absent means "let Phase 8 decide the default".
3. $SPECS_PATH (required). If unset, stop naming SPECS_PATH, per the Required path environment variable unset rule in ${CLAUDE_PLUGIN_ROOT}/references/escalation-rules.md:

   choices: ["Set SPECS_PATH (enter the path)", "Cancel"]
   

4. Specs-repo preflight. Cite ${CLAUDE_PLUGIN_ROOT}/references/specs-repo-git.md and execute its specs-preflight entry point (§3) inline, before the gate below — require-on-main performs no fetch of its own (phase-handoff.md §3.2) and relies on this step's best-effort one, the same ordering /design Phase 0 uses and for the same reason. Prompt-free and silent when the specs repo is clean and on its default branch. If it returns specs_git: blocked (§3.3 G0), carry that flag for the whole run.
5. Resolve the BRD folder. resolve-address <BRD-KEY> (addressing.md §3), which searches specifications/ and the levels below it that resolve-address searches (three, per addressing.md §3) — either level a <BRD-KEY> can name — a BRD folder directly under specifications/, or the PRD- folder of a slice inside it. Absent → stop, without asserting which command would create it: no folder exists, so no brd-link.md exists either, and nothing on disk says whether this key names a BRD with a source document or a slice of one. Naming /brd-intake unconditionally would be the wrong advice for half the cases, exactly as it is in step 6's absent branch below: BRD_GROUND_NOT_FOUND: no BRD folder found for <BRD-KEY> under $SPECS_PATH/specifications/ (both levels searched) — check the key. A BRD with a source document of its own is created by /dev-workflows:brd-intake <BRD-KEY> @<brd-file>; a slice is created by /dev-workflows:brd-split on its parent. Do not run /brd-intake on a slice; it has no source document of its own.
6. Gate this BRD's own inventory and ledger on main. Execute require-on-main (phase-handoff.md §3) against the resolved BRD folder's coverage-ledger.md. Whichever command wrote that ledger wrote the inventory beside it in the same handoff commit (coverage-ledger-format.md §3's creator table), so its presence on origin/<default> implies brd/brd-inventory.md landed with it: for a BRD with a source document of its own, that was /brd-intake, and brd/brd-defect-log.md landed too; for a slice, it was /brd-split running on the parent, and there is no defect log to land — a slice reads the parent's (brd-format.md §2.1). Map the §3.7 return by stopped first: any stopping row → stop, naming the concrete branch/PR state it reports; pass → proceed; pass_amending → proceed, printing the §3.3 row-B message; unmanaged → proceed as before this feature.