prd-ground

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

Core references. A citation of the form workflows-core:<name> names a shared reference in the workflows-core plugin. Load it with Skill(skill: "workflows-core:reference", args: "<name>") — never by path: ${CLAUDE_PLUGIN_ROOT} resolves to this plugin, which does not carry it.

/prd-ground is the BRD-to-PRD route's grounding step (PA phase), run once per slice /brd-split carves — and again on an already-ground slice a later re-cut gave a new row, the third of the three cases commands/brd-split.md Phase 7 distinguishes when it offers this command, because no [CG#n] on file was derived against a row that arrived after them — it takes the [BR#n] inventory that slice's own brd/brd-inventory.md holds 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 (workflows-core:grounding-format §8) — this command's whole job is to make that discipline happen, not to ground anything itself.

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

<BRD-KEY> still resolves through either of the two levels resolve-address searches (workflows-core:addressing §3) — a BRD that owns its source document, or one of its slices — because a root must be resolved before Phase 0 step 5a can refuse it by name. Only a slice is ground: a root BRD is refused, and grounding happens at the slice and nowhere else, over the requirements that slice's own inventory claims.

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.

--no-code is a run mode, not a step skip. It exists so a BRD whose code grounding is already verified can gain the design grounding it is missing — the state /brd-split's design-presence gate reports — without re-deriving what is already on file. Under it, <BRD-dir>/grounding/code-grounding.md is read-only for the whole run: this invocation produces no [CG#n] at all, its finding set is the new [DG#n] only, and every [CG#n] already on file keeps the verdict, evidence and verifier outcome it carries — never renumbered by Phase 5, never re-dispatched by Phase 7, never rewritten by Phase 8. Phases 1 and 3 still run in full, because a class-4 [DG#n] is pinned to the commit of the [CG#n] it cites and Phase 7 re-derives it against that repository. Documentation grounding is off for this run, and so is the derivation matrix: Phase 8 appends both into that same read-only file. Four flag states are refused rather than reconciled, all in Phase 0 step 2.

Phase 0 — Resolve inputs and gate on main

1. <BRD-KEY> (mandatory). Parse the first token that is neither a flag nor a flag's value — --depends-on and --docs each consume the token after them (step 2), and a value skipped as "non-flag" would be read as the key; validate with key-valid (workflows-core:addressing §1). If absent or invalid, stop: PRD_GROUND_NEEDS_KEY: /prd-ground needs a key (shape ^[A-Z][A-Z0-9_]*(-\d+)+$) — re-run '/product-workflows:prd-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. Refused outright on route: idea — deferred to immediately after step 5a resolves the route, for the same reason the fourth --no-code refusal below waits for the resolved folder: the route is not known until then. Phase 6 only ever sets horizon: will-change from a declared prerequisite's frozen status: decided record, and the idea route has no decision register anywhere to hold one, so every finding on it is current whatever this flag names. Accepting the flag there and quietly doing nothing with it would leave a documented flag with a stated effect that never happens — that shape is its own defect and is refused rather than silently degraded: PRD_GROUND_NO_PREREQUISITES: --depends-on names a prerequisite BRD whose frozen decisions set a finding's will-change horizon, and <KEY> is on the idea route, which has no decision register to read. Drop the flag and re-run; every finding on this route is horizon: current. --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). --docs <path> — points documentation grounding at that root for this run instead of ${DOCS_PATH:-/workspace/docs}; strip the flag and its value together before any remaining-argument classification, or the path is read as part of the address. Declared for every consumer by workflows-core:docs-grounding §1's Flags first rung, which resolves it; this command only has to recognise it and pass the invocation through. --rebaseline — boolean, see Phase 3. --derivation-matrix / --no-derivation-matrix — mutually exclusive; absent means "let Phase 8 decide the default". --no-code — boolean, the run mode stated above the phases. Its four refusals are checked here, before anything expensive runs:
   • With --no-design, nothing is left to ground: PRD_GROUND_NOTHING_TO_GROUND: --no-code and --no-design together leave this run nothing to ground — drop one and re-run '/product-workflows:prd-ground <KEY>'.
   • With --rebaseline, which supersedes [CG#n] findings by id — a write this mode forbids: PRD_GROUND_NO_CODE_REBASELINE: --rebaseline supersedes [CG#n] findings by id, which --no-code forbids — re-run '/product-workflows:prd-ground <KEY> --rebaseline' without --no-code to re-ground the moved code, or drop --rebaseline to add design grounding over what is already on file.
   • With an explicit --derivation-matrix, which Phase 8 appends into code-grounding.md: PRD_GROUND_NO_CODE_MATRIX: the derivation matrix is appended to grounding/code-grounding.md, which --no-code forbids writing — re-run '/product-workflows:prd-ground <KEY> --derivation-matrix' without --no-code. An explicit --no-derivation-matrix is redundant here but harmless; an unset default resolves off under this mode and is reported rather than left silent.
   • Where there is no verified code grounding to build on. This one needs the resolved folder, so take it immediately after step 5a rather than here — after, never before. Not only on a slice, though: step 5a refuses every root it can identify as one, but the interrupted-intake folder passes it unrefused (coverage-ledger-format.md §5.1) and reaches this check too, before step 6 would otherwise name it properly. It fails here the same way an under-grounded slice does, and the redirect it gives still lands on step 6's own stop for that folder on the next run. Stop when <BRD-dir>/grounding/code-grounding.md is absent, holds no [CG#n], or holds one carrying no verifier outcome. The third is the state /brd-split itself refuses (workflows-core:grounding-format §8), so reporting it now costs one read and saves a whole design pass that still could not split: PRD_GROUND_NO_CODE_UNGROUNDED: --no-code adds design grounding over an existing code grounding, and <KEY> has <no code grounding on file | no [CG#n] findings | N of M [CG#n] findings carrying no verifier outcome> — re-run '/product-workflows:prd-ground <KEY>' without --no-code.