@opengsd/gsd-core 1.12.0 → 1.14.0

package/gsd-core/references/verifier-evidence-gate.md

@@ -0,0 +1,160 @@
+# Convergence Evidence Gate (#3304)
+
+Bounds Step 7's anti-pattern scan so an approved gap-closure contract can
+actually close. Applies **only** when `is_re_verification = true` (Step 0) —
+a first pass has no prior contract to be out-of-contract from, so this gate
+is a pure no-op there.
+
+## The problem this closes
+
+Steps 4-7c re-verify at full, unbounded scope on every re-verification pass —
+that is documented, intended design, not the bug. The bug is narrower: Step
+7's `Categorize:` line lets the verifier's own free-form judgment label
+*anything* it believes "prevents goal" a 🛑 Blocker, and Step 9 Rule 1
+promotes any 🛑 Blocker straight into `status: gaps_found` — with no
+distinction between a blocker tied to what the gap-closure round was actually
+supposed to fix and a blocker that is simply a new opinion formed on this
+pass. Reported real-world instance: a re-verification cycle promoted four
+"architectural and security observations" to blockers, none backed by a
+failing test, none traceable to a requirement/decision/prior gap, reverting a
+completed, all-green gap-closure round and recommending another `--gaps`
+cycle — with no bound on how many times that could repeat.
+
+Truths, artifacts, and key links (Steps 3-6) can **never** produce this
+failure mode: Step 0 re-verification mode reuses the must-haves extracted in
+Step 2 verbatim ("Skip to Step 3") rather than re-establishing them, so
+whatever a truth/artifact/link *is* was fixed before this re-verification
+round started. Only Step 7's blanket per-file scan is unbounded by that
+must-haves contract — which is exactly the mechanism the issue's diagnosis
+names. This gate therefore touches Step 7 only.
+
+## Definitions
+
+**Self-evidencing blocker (unaffected by this gate).** The debt-marker gate
+(`TBD`/`FIXME`/`XXX` with no `issue #123`/`PR #123`/`#123`/`DEF-*` reference
+on the same line) is the *only* Step 7 category with zero judgment
+component — a regex match plus the absence of a follow-up reference, nothing
+inferred. Its own textual presence in the file is the deterministic evidence.
+It keeps blocking unconditionally, exactly as before. Do **not** extend this
+carve-out to any other Step 7 category (stub classification, hollow props,
+empty implementations, console-log-only): every one of those already
+requires judgment per Step 7's own "Stub classification" paragraph ("a grep
+match is a STUB only when the value flows to rendering... and no other code
+path populates it with real data") — that judgment is exactly what this gate
+exists to check.
+
+**New-scope finding.** Any Step 7 🛑 Blocker other than a self-evidencing one
+(above) is a new-scope finding **unless** either of the following holds, in
+which case it is in-contract and blocks unconditionally, evidence or not:
+
+1. **Carried-forward gap** — it matches an item in the previous
+   VERIFICATION.md's `gaps:` list, using the same 80%-token-overlap matching
+   algorithm Step 3b already uses for override matching (normalize to
+   lowercase, strip punctuation, collapse whitespace, tokenize, intersect).
+2. **Regression** — the flagged file was modified since the previous
+   VERIFICATION.md's `verified:` timestamp. Check file-level, not
+   line-level — an LLM agent re-deriving precise line provenance mid-pass is
+   unreliable; file-level modification is a single, robust command:
+
+   ```bash
+   git log --since="$PREV_VERIFIED_TS" --oneline -- "$file"
+   ```
+
+   A non-empty result means the file changed since the prior pass — the
+   gap-closure round could plausibly have introduced this finding, so it's
+   self-evidencing as a regression and blocks. **Fail closed**: if git
+   history is unavailable, ambiguous, or the timestamp can't be parsed,
+   treat the file as modified (blocks). The imprecision this trades away
+   (a big file with one unrelated hunk touched treats every pattern in it as
+   "new") only ever makes *more* things block, never fewer — consistent with
+   `<adversarial_stance>`.
+
+A finding that is neither a carried-forward gap nor on a file modified since
+the prior pass predates the gap-closure round entirely and was never flagged
+as a gap then — this is the literal "some findings predated the gap
+implementation and had previously been explicitly treated as non-blocking"
+case from the issue.
+
+**Deterministic evidence** — required for a new-scope finding to stay
+blocking. One of:
+
+- A **named test that FAILS when actually run** (red). Run exactly one test,
+  the same discipline Step 7b already uses for behavioral spot-checks —
+  never the full suite. Record the exact command and the failing output.
+- **Another concrete, reproducible artifact** — a command + output that
+  demonstrates the defect (a crash, a probe failure, a reproducible bad
+  response). An assertion, opinion, or architectural preference with no test
+  and no reproducible command output is not evidence, however well-reasoned.
+
+## The gate
+
+- New-scope finding **with** deterministic evidence → 🛑 Blocker, unchanged.
+  This includes evidenced security findings — they are preserved and still
+  block.
+- New-scope finding **without** deterministic evidence → downgrade out of
+  the blocker set. Record it in the `advisory:` frontmatter list (parallel to
+  the existing Step 9b `deferred:` list) with its reasoning intact. It does
+  **not** count toward Step 9 Rule 1's `gaps_found` trigger and does **not**
+  revert a completed must-have or, on its own, justify another
+  `/gsd:plan-phase --gaps` cycle.
+
+This changes nothing else: a carried-forward gap or a regression still
+blocks with or without a pre-existing requirement to point at, and every
+non-Step-7 trigger (FAILED truth, MISSING/STUB artifact, NOT_WIRED link) is
+untouched, since those can never be new-scope in the first place.
+
+## What this deliberately does NOT implement
+
+The issue as filed proposed a broader rule: a finding is advisory whenever
+it is untraceable to a requirement/decision/prior-gap (conditions A and B),
+regardless of evidence. The maintainer approved **condition C only** —
+evidence, not contract-traceability, is the bar. A finding with no
+pre-existing requirement to point at but with a real failing test still
+blocks. Do not implement A/B: that would demote a genuine, reproducible
+defect to advisory purely for being newly discovered, which is exactly the
+deferral this project's no-defer rule forbids. This gate narrows *when a
+blocker needs proof*, not *what counts as in scope*.
+
+## Advisory frontmatter
+
+```yaml
+advisory: # Only if new-scope findings lack deterministic evidence (Step 7)
+  - finding: "Short description of the new-scope concern"
+    category: architectural | security | other
+    reason: "Why this was raised; what would resolve it"
+    evidence_status: "none provided" # or cite what was attempted but inconclusive
+```
+
+## Report section
+
+```markdown
+### Advisory (New Scope, Unevidenced)
+
+New-scope findings from Step 7 with no deterministic evidence — reported,
+not blocking, do not revert a completed must-have.
+
+| # | Finding | Category | Why Advisory |
+|---|---------|----------|--------------|
+| 1 | {finding} | {category} | new-scope, no deterministic evidence |
+```
+
+Include this section (even if empty, stating "None") whenever
+`is_re_verification = true` ran — an omitted section reads as "not
+checked," not "checked and clean."
+
+## Worked example (from the issue's reported incident)
+
+Prior pass: `gaps_found`, 4 items — all closed by approved gap-closure plans,
+re-verification begins.
+
+- Finding: "the retry loop's backoff strategy is architecturally fragile
+  under sustained load." Not in the prior `gaps:` list. The flagged file was
+  last modified 3 weeks before this verification pass (before the
+  gap-closure plans even started) — not a regression. No test run, no
+  reproducible command demonstrating a failure. → **advisory**, does not
+  block, does not revert the 4 closed gaps.
+- Finding: `TBD: handle the timeout case` left in a file the gap-closure plan
+  edited this pass. → self-evidencing debt marker, unaffected by this gate,
+  blocks exactly as it always has.
+- Finding: a previously-closed gap's file now fails the SAME named test that
+  originally proved it broken. → carried-forward gap, blocks.

package/gsd-core/references/worktree-path-safety.md

@@ -1,7 +1,117 @@
 # Worktree Path Safety
 
-Guards for executor agents running inside Claude Code worktrees. Three checks
-must run before any staging, Edit, or Write operation in worktree mode.
+Guards for executor agents running inside Claude Code worktrees. The
+supplied-root pin (step 0p) runs in EVERY mode; the remaining checks run before
+any staging, Edit, or Write operation in worktree mode.
+
+---
+
+## Supplied-root pin — step 0p (#4254, EVERY mode)
+
+Sequential-mode dispatch (no `isolation="worktree"`) gives the executor no
+spawn-time cwd guarantee, and the worktree-only guards below do not apply — so
+a sequential executor whose process cwd resolved to a different checkout of
+the same repo would self-derive that checkout as its root and commit there,
+silently. Step 0p closes that hole by comparing the executor's actual root
+against a root the ORCHESTRATOR already validated — never against anything the
+executor derives itself.
+
+**Runtime contract (executor):** if your prompt contains a `<project_root_pin>`
+block, run its guard script verbatim before your first Edit/Write and again
+before every commit, in the same cwd as that write or commit. On FATAL, halt
+and report — recovery (moving commits between checkouts) is an
+orchestrator/human decision, never agent self-repair. If your prompt contains
+NO `<project_root_pin>` block (worktree/isolated dispatch, or a legacy
+orchestrator), emit one warning line and continue with steps 0a/0b below — do
+not fail closed on dispatches that never carried a pin. **Never bind
+`{PINNED_ROOT}` yourself**: if this template reaches you unbound it is
+reference prose, not your pin — only the orchestrator's build-time
+substitution produces a valid guard.
+
+**Composition contract (orchestrator — build time, NOT a sub-agent runtime
+step):** copy the guard below into the dispatched prompt inside a
+`<project_root_pin>` block, substituting `{PINNED_ROOT}` with the literal value
+of `$ORCHESTRATOR_WT` captured at execute_waves entry, shell-single-quoted:
+wrap the path in `'…'` and escape any embedded `'` as `'\''`. A path that
+cannot be quoted this way must halt the phase (surface a blocker) rather than
+ship a pin that could mis-parse. The comparison is git-vs-git on BOTH sides —
+`git -C` resolves the pinned path to its repo's canonical toplevel in git's
+own path representation, so symlink aliases, trailing slashes, `/var` vs
+`/private/var` spellings, and Windows drive-letter forms — forward- or
+backslash-separated, `RUNNER~1`-style short names included — compare equal by
+construction (shell `pwd -P` normalization does NOT match git's emission on
+Windows — do not re-introduce it).
+
+Two portability rules baked into the guard below, learned from the #4254 CI
+Windows legs: (1) a backslash comparator must be GENERATED at runtime
+(`printf '\134'`), because a backslash written twice in the script text does
+not survive the Windows command-line round-trip into bash — the doubled form
+arrives halved, which silently rewrites any escape pattern that relies on it;
+(2) every FATAL names its `Guard stage` and, where a git capture failed,
+git's own stderr in a `Diagnostic` line, so a platform failure self-describes
+instead of surfacing as a bare `Actual root: <none>`.
+
+```bash
+# gsd:guard=supplied-root-pin (#4254) — run before the first Edit/Write and before every commit.
+PINNED_ROOT='{PINNED_ROOT}'  # orchestrator build-time substitution — the only valid source of this value
+PIN_STAGE=''
+PIN_DIAG=''
+gsd_pin_fail() {
+  echo "FATAL: executor root does not match the orchestrator-supplied PROJECT_ROOT pin (#4254)." >&2
+  echo "  Pinned root: ${PINNED_ROOT:-<empty or unexpanded>}" >&2
+  echo "  Actual root: ${ACTUAL_ROOT:-<none>}" >&2
+  echo "  Guard stage: ${PIN_STAGE:-<unset>}" >&2
+  if [ -n "$PIN_DIAG" ]; then echo "  Diagnostic: $PIN_DIAG" >&2; fi
+  echo "  No writes or commits are permitted from this checkout. HALT and report; recovery is an" >&2
+  echo "  orchestrator/human decision. Only the IMMEDIATE submodule of the pinned checkout is a" >&2
+  echo "  legitimate other cwd — nested submodules must surface as a blocker, not self-route." >&2
+  exit 1
+}
+# Backslash comparator, generated at runtime: a backslash written twice in this
+# script does not survive the Windows spawn path into bash (the command-line
+# round-trip halves the doubled form), which rejected every C:\ pin at the form
+# gate on the #4254 CI Windows legs. printf's octal escape is a lone backslash,
+# which does survive; the quoted expansion below is literal in a case pattern.
+BS=$(printf '\134')
+# Fail closed if the comparator could not be generated: an empty BS would widen
+# the drive-form arm below to drive-RELATIVE pins (C:foo) — the one fail-open
+# seam in this construction, closed loudly rather than trusted to the shell.
+if [ -z "$BS" ]; then
+  PIN_STAGE=form-gate
+  PIN_DIAG='backslash comparator generation failed (printf octal escape returned empty)'
+  gsd_pin_fail
+fi
+case "$PINNED_ROOT" in
+  ''|'{PINNED_ROOT}') PIN_STAGE=pin-unbound; gsd_pin_fail ;;  # empty or unexpanded pin — fail closed, never warn-and-proceed
+  /*) ;;                                                     # absolute POSIX form
+  [A-Za-z]:/*|[A-Za-z]:"$BS"*) ;;                            # Windows drive form, forward- or backslash-separated
+  *) PIN_STAGE=form-gate; gsd_pin_fail ;;                    # relative pin — never trustworthy across cwds
+esac
+ACTUAL_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$ACTUAL_ROOT" ]; then
+  PIN_STAGE=actual-capture
+  PIN_DIAG="git rev-parse --show-toplevel from the cwd failed: $(git rev-parse --show-toplevel 2>&1 1>/dev/null)"
+  gsd_pin_fail
+fi
+PINNED_TL=$(git -C "$PINNED_ROOT" rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$PINNED_TL" ]; then
+  PIN_STAGE=pinned-capture
+  PIN_DIAG="git -C <pinned root> rev-parse --show-toplevel failed: $(git -C "$PINNED_ROOT" rev-parse --show-toplevel 2>&1 1>/dev/null)"
+  gsd_pin_fail
+fi
+if [ "$ACTUAL_ROOT" != "$PINNED_TL" ]; then
+  # Registered-submodule allowance: sub_repos plans legitimately commit inside an
+  # immediate submodule of the pinned checkout. The superproject working tree is
+  # git-emitted in the same representation as PINNED_TL, so the equality is
+  # representation-safe on every platform.
+  SUPER_TL=$(git rev-parse --show-superproject-working-tree 2>/dev/null)
+  if [ "$SUPER_TL" != "$PINNED_TL" ]; then
+    PIN_STAGE=root-mismatch
+    PIN_DIAG="actual=${ACTUAL_ROOT} pinned=${PINNED_TL} superproject=${SUPER_TL:-<none>}"
+    gsd_pin_fail
+  fi
+fi
+```
 
 ---
 

package/gsd-core/templates/README.md

@@ -21,8 +21,14 @@ These files live directly at `.planning/` — not inside phase subdirectories.
 | `LEARNINGS.md` | *(inline)* | `/gsd:extract-learnings`, `/gsd:execute-phase` (gated: `features.global_learnings`) | Phase retrospective learnings for future plans |
 | `THREADS.md` | *(inline)* | `/gsd:thread` | Persistent discussion threads |
 | `config.json` | `config.json` | `/gsd:new-project`, `/gsd:health --repair` | Project-specific GSD configuration |
-| `CLAUDE.md` | `claude-md.md` | `/gsd-profile` | Auto-assembled Claude Code context file |
+| `CLAUDE.md` | *(inline)* | `/gsd-profile` | Auto-assembled Claude Code context file |
 | `RETROSPECTIVE.md` | *(inline)* | `/gsd:complete-milestone` | Living milestone retrospective updated at each milestone close |
+| `WINDOWS.md` | *(none)* | broken-windows ledger (`src/broken-windows.cts`) | Tracked known-broken items pending resolution (#3224) |
+| `STATE-ARCHIVE.md` | *(none)* | `state.cts`'s `cmdStatePrune` | Pruned historical STATE.md entries |
+| `milestone.lock` | *(none)* | `src/milestone-lock.cts` | Persistent milestone (phase + session) claim, unlike the transient `STATE.md.lock`/`WAITING.json` (#3311) |
+| `state.json` | *(none)* | `src/state-contract.cts` | Machine-readable state contract published at step boundaries (#3227) |
+| `skill-manifest.json` | *(none)* | `init.cts`'s `cmdSkillManifest --write` | Project-scoped skill manifest (#3964) |
+| `PATTERNS.md` | *(inline)* | `/gsd:extract-learnings` (graduation, `workflows/graduation.md`, `patterns` target) | Graduated cross-phase patterns -- distinct from the per-phase `NN-PATTERNS.md` below (#4282) |
 
 ### Version-stamped artifacts (pattern: `vX.Y-*.md`)
 

package/gsd-core/templates/phase-prompt.md

@@ -22,6 +22,10 @@ files_modified: []          # Files this plan modifies.
 files_deleted: []           # OPTIONAL. Files this plan REMOVES. Declaring a path here is what
                             # lets worktree cleanup-wave merge the branch that deletes it; an
                             # undeclared deletion still blocks. Exact paths, not globs or dirs.
+coupling_justified: []      # OPTIONAL. Deliberate, order-independent same-wave couplings: one
+                            # "plan-id: reason" string per coupled peer, e.g.
+                            # ["03-02: both append independent config keys"]. Exempts the pair
+                            # from the plan-checker's Dimension 3b advisory (#3724).
 autonomous: true            # false if plan has checkpoints requiring user interaction
 requirements: []            # REQUIRED — Requirement IDs from ROADMAP this plan addresses. MUST NOT be empty.
 user_setup: []              # Human-required setup Claude cannot automate (see below)

package/gsd-core/templates/state.md

@@ -172,9 +172,12 @@ Updated after each plan completion.
 **Decisions:** Reference to PROJECT.md Key Decisions table, plus recent decisions summary for quick access. Full decision log lives in PROJECT.md.
 
 **Pending Todos:** Ideas captured via /gsd-add-todo
-- Count of pending todos
-- Reference to .planning/todos/pending/
-- Brief list if few, count if many (e.g., "5 pending todos — see /gsd:capture --list")
+- One bullet per pending todo, rendered by `init.todos`'s `pending_todos_markdown`
+  (each bullet capped at 240 characters: `- [date] [area] title — [todo file](path) — Needs ...`;
+  the todo-file link is repo-relative, so the cap does not depend on checkout path length)
+- `None yet.` when there are no pending todos
+- No collapse-by-count fallback — every pending todo gets its own line, always
+  (see #2618 design doc for why a "count if many" fallback was rejected)
 
 **Blockers/Concerns:** From "Next Phase Readiness" sections
 - Issues that affect future work

package/gsd-core/templates/summary.compact.md

@@ -0,0 +1,212 @@
+# Summary Template
+
+Template for `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md` - phase completion documentation.
+
+---
+
+## File Template
+
+```markdown
+---
+phase: XX-name
+plan: YY
+subsystem: [primary category: auth, payments, ui, api, database, infra, testing, etc.]
+tags: [searchable tech: jwt, stripe, react, postgres, prisma]
+
+# Dependency graph
+requires:
+  - phase: [prior phase this depends on]
+    provides: [what that phase built that this uses]
+provides:
+  - [bullet list of what this phase built/delivered]
+affects: [list of phase names or keywords that will need this context]
+
+# Actuals (#2632) — pairs with the plan's `estimate` to calibrate future estimates.
+# Same estimateTokens scale (chars/4 over the realized diff), never a harness token count.
+actuals:
+  tokens: [chars/4 over files actually changed]
+  tasks: [tasks completed]
+  commits: [commits made]
+
+# Tech tracking
+tech-stack:
+  added: [libraries/tools added in this phase]
+  patterns: [architectural/code patterns established]
+
+key-files:
+  created: [important files created]
+  modified: [important files modified]
+
+key-decisions:
+  - "Decision 1"
+  - "Decision 2"
+
+patterns-established:
+  - "Pattern 1: description"
+  - "Pattern 2: description"
+
+requirements-completed: []  # REQUIRED — Copy ALL requirement IDs from this plan's `requirements` frontmatter field.
+
+# Coverage metadata (#1602) — one entry per shipped deliverable. Drives DETERMINISTIC UAT routing in verify-work.
+# OMIT this whole block for legacy/prose-only SUMMARYs — verify-work then falls back to the ## Accomplishments bullets
+# (byte-identical behavior for un-migrated phases). See <coverage_guidance> below for the contract.
+coverage:
+  - id: D1
+    description: "[deliverable in human-readable form — what would have been a prose ## Accomplishments bullet]"
+    requirement: "[REQ-ID from this plan's `requirements`, or omit if none]"
+    verification:
+      - kind: unit            # unit | integration | e2e | automated_ui | manual_procedural | other
+        ref: "[tests/path.test.ts#test name | playwright:shot.png | command invocation]"
+        status: pass          # pass | fail | unknown — from the latest run
+    human_judgment: false     # REQUIRED boolean. false => may auto-pass IF every verification status is `pass`.
+  - id: D2
+    description: "[a deliverable that needs a human to sign off]"
+    verification: []
+    human_judgment: true
+    rationale: "[REQUIRED when human_judgment: true — why automation is insufficient]"
+
+# Metrics
+duration: Xmin
+completed: YYYY-MM-DD
+status: complete
+---
+
+# Phase [X]: [Name] Summary
+
+**[Substantive one-liner describing outcome - NOT "phase complete" or "implementation finished"]**
+
+## Performance
+
+- **Duration:** [time] (e.g., 23 min, 1h 15m)
+- **Started:** [ISO timestamp]
+- **Completed:** [ISO timestamp]
+- **Tasks:** [count completed]
+- **Files modified:** [count]
+
+## Accomplishments
+- [Most important outcome]
+- [Second key accomplishment]
+- [Third if applicable]
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: [task name]** - `abc123f` (feat/fix/test/refactor)
+2. **Task 2: [task name]** - `def456g` (feat/fix/test/refactor)
+3. **Task 3: [task name]** - `hij789k` (feat/fix/test/refactor)
+
+**Plan metadata:** `lmn012o` (docs: complete plan)
+
+_Note: TDD tasks may have multiple commits (test → feat → refactor)_
+
+## Files Created/Modified
+- `path/to/file.ts` - What it does
+- `path/to/another.ts` - What it does
+
+## Decisions Made
+[Key decisions with brief rationale, or "None - followed plan as specified"]
+
+## Deviations from Plan
+
+[If no deviations: "None - plan executed exactly as written"]
+
+[If deviations occurred:]
+
+### Auto-fixed Issues
+
+**1. [Rule X - Category] Brief description**
+- **Found during:** Task [N] ([task name])
+- **Issue:** [What was wrong]
+- **Fix:** [What was done]
+- **Files modified:** [file paths]
+- **Verification:** [How it was verified]
+- **Committed in:** [hash] (part of task commit)
+
+[... repeat for each auto-fix ...]
+
+---
+
+**Total deviations:** [N] auto-fixed ([breakdown by rule])
+**Impact on plan:** [Brief assessment - e.g., "All auto-fixes necessary for correctness/security. No scope creep."]
+
+## Issues Encountered
+[Problems and how they were resolved, or "None"]
+
+[Note: "Deviations from Plan" documents unplanned work that was handled automatically via deviation rules. "Issues Encountered" documents problems during planned work that required problem-solving.]
+
+## User Setup Required
+
+[If USER-SETUP.md was generated:]
+**External services require manual configuration.** See [{phase}-USER-SETUP.md](./{phase}-USER-SETUP.md) for:
+- Environment variables to add
+- Dashboard configuration steps
+- Verification commands
+
+[If no USER-SETUP.md:]
+None - no external service configuration required.
+
+## Next Phase Readiness
+[What's ready for next phase]
+[Any blockers or concerns]
+
+---
+*Phase: XX-name*
+*Completed: [date]*
+```
+
+<frontmatter_guidance>
+**Purpose:** Enable automatic context assembly via dependency graph. Frontmatter makes summary metadata machine-readable so plan-phase can scan all summaries quickly and select relevant ones based on dependencies (`requires`/`provides`/`affects` create the explicit links; transitive closure follows from them).
+
+**Subsystem/Tags:** Primary categorization + searchable technical keywords, for detecting related phases and tech-stack awareness. **Key-files:** important files for @context references in PLAN.md. **Patterns:** established conventions future phases should maintain.
+
+**Population:** Frontmatter is populated during summary creation in execute-plan.md. See `<step name="create_summary">` for field-by-field guidance.
+
+**Status (#2830):** `status: complete` is the default — the plan finished. Use `status: halted` instead when the plan reached a designed stop (a gate failure, a spike concluding without expanding into the full build, or any other intentional non-completion) and intentionally left tasks unfinished. `halted` is machine-read: any plan whose `depends_on` (directly or transitively) names a halted plan is reported as blocked, not offered to the executor, until the halt is resolved and re-summarized as `complete`.
+</frontmatter_guidance>
+
+<coverage_guidance>
+**Purpose (#1602):** The `coverage:` block is a per-deliverable Requirements Traceability Matrix. It lets `verify-work`'s `extract_tests` step route deliverables DETERMINISTICALLY — auto-passing those proven by passing tests and reserving human UAT for genuine judgment — instead of re-deriving coverage from prose. Consumed via `gsd-tools uat classify-coverage --summary <SUMMARY>`.
+
+**Field semantics:**
+
+| Field | Purpose |
+|---|---|
+| `id` | Stable identifier (`D1`, `D2`…) for cross-referencing from UAT.md and audit reports. Must be unique within the SUMMARY. |
+| `description` | The deliverable in human-readable form — what would have been a prose bullet. |
+| `requirement` | Links back to a REQUIREMENTS.md REQ-ID (joins `requirements-completed`). Optional. |
+| `verification[].kind` | Enum: `unit \| integration \| e2e \| automated_ui \| manual_procedural \| other`. |
+| `verification[].ref` | Test path + descriptor (`file#test name`), Playwright screenshot ref, or command invocation. Required per entry. |
+| `verification[].status` | `pass \| fail \| unknown` — populated from the latest test run. |
+| `human_judgment` | Explicit boolean; REQUIRED. `true` always routes to a human. |
+| `rationale` | REQUIRED when `human_judgment: true`. The audit trail for why automation is insufficient. |
+
+**Deterministic contract (what the classifier does):**
+- A deliverable auto-passes (no human prompt) **only** when `human_judgment: false` AND `verification` is non-empty AND every `verification[].status` is `pass`. This is the narrow, fully-proven case.
+- **Everything else is presented to a human** — `human_judgment: true`, an empty `verification:`, any non-`pass`/`unknown` status, or any schema error. A false-negative is a redundant prompt (the status quo); a false-positive ships a bug UAT existed to catch.
+- **Fail-safe default:** if you cannot determine coverage for a deliverable, you MUST set `human_judgment: true` with `rationale: "Coverage not determined at authoring time — verifier must classify"`. Never leave a deliverable's `human_judgment` empty, and never set it `false` just to skip the prompt — auto-pass additionally requires a passing `verification` entry, so the flag alone cannot skip the human.
+- `coverage: []` means "no deliverables to classify" (the single-confirmation path). OMITTING the block entirely means "legacy" — `verify-work` falls back to prose `## Accomplishments` extraction unchanged.
+</coverage_guidance>
+
+<one_liner_rules>
+The one-liner MUST be substantive:
+
+**Good:** "JWT auth with refresh rotation using jose library" · "Prisma schema with User, Session, and Product models" · "Dashboard with real-time metrics via Server-Sent Events"
+
+**Bad:** "Phase complete" · "Authentication implemented" · "Foundation finished" · "All tasks done"
+
+The one-liner should tell someone what actually shipped.
+</one_liner_rules>
+
+<guidelines>
+**Frontmatter:** MANDATORY - complete all fields. Enables automatic context assembly for future planning.
+
+**One-liner:** Must be substantive. "JWT auth with refresh rotation using jose library" not "Authentication implemented".
+
+**Decisions section:**
+- Key decisions made during execution with rationale
+- Extracted to STATE.md accumulated context
+- Use "None - followed plan as specified" if no deviations
+
+**After creation:** STATE.md updated with position, decisions, issues.
+</guidelines>