@opengsd/gsd-core 1.12.0 → 1.13.0

package/gsd-core/references/planner-revision.md

@@ -21,12 +21,43 @@ issues:
   - plan: "16-01"
     dimension: "task_completeness"
     severity: "blocker"
+    required_property: "Every `auto` task has a `<verify>` separating pass from fail"
     description: "Task 2 missing <verify> element"
     fix_hint: "Add verification command for build output"
 ```
 
 Group by plan, dimension, severity.
 
+**What binds and what does not.** `required_property` (the invariant that must hold),
+`description` (the evidence it does not) and `severity` are binding. `fix_hint` is **one
+example** of a route to that property — an illustration, never an instruction. You address an
+issue by making `required_property` true; the hint's own mechanism is optional.
+
+An older checker may return an issue with no `required_property`. Derive it from `dimension`
++ `description` and state the derived property in your revision summary. Never treat the
+absence of the field as licence to apply `fix_hint` literally.
+
+**Prefer the smallest sufficient mechanism.** If a smaller change than the hint makes
+`required_property` true, take it — that fully addresses the issue and must be reported as
+addressed, naming the property satisfied and the mechanism used.
+
+### Step 2.5: Constraint Re-check (before any edit)
+
+Before editing, re-read the constraints already in force:
+
+- Locked decisions in CONTEXT.md (`## Decisions`) and deferred ideas (`## Deferred Ideas`)
+- Active capability / project guidance (CLAUDE.md, `.claude/skills/`, `.agents/skills/`)
+- Constraints the existing plans already encode (chosen mechanism, scope boundary, must_haves)
+
+A `fix_hint` conflicts when applying it would contradict any of those. Applying it anyway is
+a contract violation, not a judgement call. When a hint conflicts — or when the property is
+unreachable without breaking a constraint — do NOT edit around it and do NOT burn a revision
+iteration on it: emit `## REVISION_CONFLICT` (Step 7) for that issue, apply every
+non-conflicting issue normally, and return.
+
+A hint that merely proposes a *bigger* mechanism than needed is not a conflict. Take the
+smaller route under Step 2 and report it as addressed.
+
 ### Step 3: Revision Strategy
 
 | Dimension | Strategy |
@@ -38,15 +69,25 @@ Group by plan, dimension, severity.
 | scope_sanity | Split into multiple plans |
 | must_haves_derivation | Derive and add must_haves to frontmatter |
 
+Each strategy is the usual route, not the only one. Any change that makes the issue's
+`required_property` true is a valid strategy.
+
 ### Step 4: Make Targeted Updates
 
 **DO:** Edit specific flagged sections, preserve working parts, update waves if dependencies change.
+Choose the smallest mechanism that makes each issue's `required_property` true — explicitly
+including a mechanism smaller than, or different from, the one its `fix_hint` names.
 
-**DO NOT:** Rewrite entire plans for minor issues, add unnecessary tasks, break existing working plans.
+**DO NOT:** Rewrite entire plans for minor issues, add unnecessary tasks, break existing working
+plans, or apply a `fix_hint` that contradicts a constraint from Step 2.5 — that one goes to
+`## REVISION_CONFLICT` instead.
 
 ### Step 5: Validate Changes
 
-- [ ] All flagged issues addressed
+- [ ] Every flagged issue's `required_property` now holds — reached by its `fix_hint` OR by a
+      smaller/different mechanism (both count as addressed), OR raised as `## REVISION_CONFLICT`
+- [ ] No `fix_hint` applied that contradicts a locked decision, capability guidance, or an
+      existing plan constraint (Step 2.5)
 - [ ] No new issues introduced
 - [ ] Wave numbers still valid
 - [ ] Dependencies still correct
@@ -85,3 +126,35 @@ gsd_run query commit "fix($PHASE): revise plans based on checker feedback" --fil
 |-------|--------|
 | {issue} | {why - needs user input, architectural change, etc.} |
 ```
+
+### Step 7b: Return Revision Conflict (when Step 2.5 found one)
+
+Emit this INSTEAD OF `## REVISION COMPLETE` when at least one issue could not be addressed
+without contradicting a constraint. Non-conflicting issues you already fixed stay listed under
+`### Changes Made` so the work is not lost. The orchestrator routes this to the user or to the
+configured plan-review convergence loop; it does not count as a failed revision iteration.
+
+```markdown
+## REVISION_CONFLICT
+
+**Conflicts:** {N}  |  **Issues addressed anyway:** {M}
+
+| Issue | required_property | Conflicts with | Why the hint cannot be applied |
+|-------|-------------------|----------------|-------------------------------|
+| {dimension}/{plan} | {property} | {locked decision D-nn / CLAUDE.md rule / plan constraint} | {one line} |
+
+### Alternatives Considered
+
+| Issue | Alternative | Satisfies required_property? | Cost of adopting |
+|-------|-------------|------------------------------|------------------|
+| {dimension}/{plan} | {smaller or different mechanism} | {yes / partially — how} | {what it changes} |
+
+### Changes Made
+
+{table of the non-conflicting issues you DID address, same shape as REVISION COMPLETE}
+```
+
+**Every field is one line of plain text.** No newlines inside a cell, and never begin a field with
+`#`, `-`, `|` or a code fence. These fields are appended to a shared markdown file that a later
+reader scans by heading; a field that starts a heading truncates that scan and hides conflicts
+below it.

package/gsd-core/references/planning-config.md

@@ -299,7 +299,7 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 | `workflow.build_command` | string\|null | `null` | Any shell command | Build gate command run by the post-merge gate. Unset → build step auto-detected/skipped. |
 | `workflow.mvp_mode` | boolean | `false` | `true`, `false` | Persist the MVP-mode flag in config so every phase defaults to MVP framing without requiring `--mvp` on the CLI. Resolved via the chain: `--mvp` CLI flag → ROADMAP.md `**Mode:** mvp` field → this config value → `false`. When `true`, the planner, executor, verifier, and discovery surfaces (progress, stats, graphify) all treat the phase as an MVP vertical slice (UI → API → DB) of one user-visible capability. |
 | `workflow.context_guard_mode` | string | `"warn"` | `"auto"`, `"warn"`, `"off"` | Context exhaustion guard mode for `execute-phase`. Before each wave, the orchestrator self-assesses context pressure using degradation signals from `context-budget.md`. `"warn"` (default): emit a warning and recommend `/gsd:pause-work` when POOR tier is detected. `"auto"`: automatically invoke `/gsd:pause-work` before the next wave when POOR tier is detected. `"off"`: disable the guard. The guard is heuristic — no programmatic context-% API exists. |
-| `workflow.plan_chunked` | boolean | `false` | `true`, `false` | Enable chunked planning mode. When `true`, the plan-phase orchestrator splits the single long-lived planner Task into a short outline Task followed by N short per-plan Tasks (~3–5 min each). Each plan is committed individually for crash resilience. Particularly useful on Windows where long-lived Tasks may hang on stdio. Also activated by the `--chunked` flag. |
+| `workflow.plan_chunked` | boolean | `false` | `true`, `false` | Enable chunked planning mode. When `true`, the plan-phase orchestrator splits the single long-lived planner Task into a short outline Task followed by N short per-plan Tasks (~3–5 min each). Each plan is committed individually for crash resilience. Particularly useful on Windows where long-lived Tasks may hang on stdio. Also activated by the `--chunked` flag. See `planning.chunked_parallel` below for concurrent per-plan dispatch. |
 | `workflow.specless_probe_fallback` | boolean | `true` | `true`, `false` | Gate the SPEC-less probe fallback in `plan-phase`. When `true` (default), a phase that did not supply a `## Edge Coverage` / `## Prohibitions` SPEC section (header absent or present-but-empty) runs the existing probe protocol — the deterministic `edge-probe.cjs` for edges and an in-planner LLM recall pass for prohibitions — and authors the resulting predicates into PLAN.md `must_haves` (section-level precedence: a SPEC-supplied section is never re-run or overwritten). When `false`, the fallback is skipped but the skip is recorded: plan-phase emits a visible "probe fallback disabled" marker, never a silent skip. |
 | `workflow.code_review_command` | string\|null | `null` | Any shell command | External code-review command integrated into `/gsd:ship`. The diff is piped to the command via stdin; the command must output JSON with a `verdict` field (`"APPROVED"` or `"REVISE"`). Non-zero exit or `"REVISE"` verdict blocks the ship workflow. When unset, the built-in review flow runs. Example: `my-review-tool --review`. |
 | `workflow.inline_plan_threshold` | number | `2` | `0`–`10` | Plans with ≤N tasks execute inline instead of spawning a subagent |
@@ -404,6 +404,7 @@ These can be set at top level or nested under `planning.*` (e.g., `"planning": {
 |-----|------|---------|----------------|-------------|
 | `planning.commit_docs` | boolean | `true` | `true`, `false` | Alias for top-level `commit_docs` |
 | `planning.search_gitignored` | boolean | `false` | `true`, `false` | Alias for top-level `search_gitignored` |
+| `planning.chunked_parallel` | boolean | `false` | `true`, `false` | Opt-in for `workflow.plan_chunked`'s per-plan loop (§8.5.2 of `chunked-planning-mode.md`, #3777). When `true`, the runnable per-plan planners within one outline Wave are dispatched concurrently (one message, `run_in_background=true` each) instead of one at a time, honoring the outline's Wave column as the schedule (`Depends On` is expected to name only an earlier Wave and is not separately parsed — batching strictly by Wave already respects it). Gated on the negotiated `dispatch-capacity` query (#3673): a host that declares no `maxConcurrency` (capacity resolves to `1`) stays serial regardless of this setting. Default `false` is byte-identical to the pre-#3777 serial loop. Trade-off: per-plan commits interleave within a batch instead of strictly one-at-a-time, and a stalled plan's retry no longer blocks sibling plans in the same batch from having already committed. |
 
 ---
 

package/gsd-core/references/response-language-directive.md

@@ -0,0 +1,9 @@
+# Response-Language Directive (#2529)
+
+**If `response_language` is set** (in the init JSON this workflow parses, or in `.planning/config.json`): ALL user-facing output of this workflow MUST be in that language — narration between tool calls, status updates, progress notes, findings, banners, report prose, questions (AskUserQuestion or plain text), and summaries. Technical terms, code, file paths, commands, and identifiers stay in English.
+
+Literal English report/banner templates embedded in a workflow are a structural SOURCE, not literal output to copy verbatim — render their prose translated into `{response_language}` while keeping headings' structural markers, table columns, IDs, commands, and file paths unchanged. Exception: blocks a workflow explicitly requires to be emitted byte-for-byte (e.g. pre-rendered checkpoints) are output exactly as rendered.
+
+Pass `response_language: {value}` into every spawned subagent prompt so any user-facing output they produce stays in the configured language.
+
+Workflows take this contract in one of three forms (REQ-LANG-03): an `@`-reference to this file; their own inline directive naming the same narration class; or, for a fragment loaded by a covered parent, inheritance from that parent. Coverage is enforced by `scripts/lint-response-language-coverage.cjs` — a new workflow cannot ship without one of the three, and the lint checks this file's own wording too, so a weakened directive here uncovers every workflow that imports it rather than passing silently. Workflow-specific directives (e.g. `execute-phase-response-language.md`) take precedence where present.

package/gsd-core/references/revision-loop.md

@@ -16,6 +16,8 @@ This pattern applies whenever:
 ```
 prev_issue_count = Infinity
 iteration = 0
+previous_conflict_property = null
+conflict_return_count = 0
 
 LOOP:
   1. Run checker/validator on current output
@@ -23,15 +25,30 @@ LOOP:
   3. If PASSED or only INFO-level issues:
      -> Accept output, exit loop
   4. If BLOCKER or WARNING issues found:
-     a. iteration += 1
-     b. If iteration > 3:
+     a. If iteration + 1 > 3:
         -> Escalate to user (see "After 3 Iterations" below)
-     c. Parse issue count from checker output
-     d. If issue_count >= prev_issue_count:
+     b. Parse issue count from checker output
+     c. If issue_count >= prev_issue_count:
         -> Escalate to user: "Revision loop stalled (issue count not decreasing)"
-     e. prev_issue_count = issue_count
-     f. Re-spawn the producing agent with checker feedback appended
-     g. After revision completes, go to LOOP
+     d. prev_issue_count = issue_count
+     e. Re-spawn the producing agent with checker feedback appended
+     f. If the agent returns REVISION_CONFLICT:
+        -> conflict_return_count += 1
+        -> If conflict_return_count >= 3:
+             escalate through the iteration-cap gate
+        -> If it names the same required_property as the previous conflict:
+             escalate as a stall (the resolution did not take)
+           Else: previous_conflict_property = current required_property
+             resolve it (see "Conflict Return" below) and go to step e.
+             Do NOT increment iteration -- the conflict was not a failed attempt.
+        Else: previous_conflict_property = null (a normal revision ends the conflict chain --
+             a LATER, unrelated conflict on the same property must not be misread as a repeat)
+     g. iteration += 1
+     h. After revision completes, go to LOOP
+
+The increment is step g, AFTER the producing agent returns. An iteration counted at step a is
+already spent by the time a REVISION_CONFLICT comes back, so it cannot then be withheld, and the
+cap would punish the agent for correctly refusing to apply incompatible advice.
 ```
 
 ### Issue Count Tracking
@@ -45,19 +62,38 @@ Display iteration progress before each revision spawn:
 
 When re-spawning the producing agent for revision, pass the checker's YAML-formatted issues. The checker's output contains a `## Issues` heading followed by a YAML block. Parse this block and pass it verbatim to the revision agent.
 
+The field names are the plan-checker's schema (`agents/gsd-plan-checker.md` → `<issue_structure>`):
+`plan`, `dimension`, `severity`, `required_property`, `description`, `task`, `fix_hint`. There is no
+`suggested_fix` field and no `finding` or `affected_field` field — those names were drift, and every
+producer now emits the schema above.
+
 ```
 <checker_issues>
-The issues below are in YAML format. Each has: dimension, severity, finding,
-affected_field, suggested_fix. Address ALL BLOCKER issues. Address WARNING
-issues where feasible.
+The issues below are in YAML format. Each has: dimension, severity,
+required_property, description, fix_hint.
+
+BINDING: required_property (the invariant that must hold), description (the
+evidence it does not), severity. NON-BINDING: fix_hint -- ONE example route to
+the property, never an instruction.
+
+Satisfy the required_property of ALL BLOCKER issues. Satisfy WARNING issues
+where feasible.
 
 {YAML issues block from checker output -- passed verbatim}
 </checker_issues>
 
 <revision_instructions>
 Address ALL BLOCKER and WARNING issues identified above.
-- For each BLOCKER: make the required change
+- For each BLOCKER: make required_property true. Its fix_hint is one example
+  route; a smaller or different mechanism that makes the same property true
+  addresses the issue in full -- report which mechanism you used.
 - For each WARNING: address or explain why it's acceptable
+- Before editing, re-check locked decisions, active capability guidance, and
+  constraints the existing output already encodes. If a fix_hint would
+  contradict one of those, or the property is unreachable without breaking one,
+  do NOT apply it and do NOT work around it: return REVISION_CONFLICT naming
+  the conflict and the alternatives considered, having addressed every
+  non-conflicting issue.
 - Do NOT introduce new issues while fixing existing ones
 - Preserve all content not flagged by the checker
 This is revision iteration {N} of max 3. Previous iteration had {prev_count}
@@ -65,6 +101,75 @@ issues. You must reduce the count or the loop will terminate.
 </revision_instructions>
 ```
 
+### Conflict Return (REVISION_CONFLICT)
+
+A revision agent that returns `REVISION_CONFLICT` has not failed and has not stalled. Handle it
+BEFORE the iteration counter and the stall check — a conflict is not resolvable by re-running the
+same loop, so spending retry budget on it only exhausts the cap:
+
+**This protocol is shared.** Every revision-bearing workflow follows it — `plan-phase`, `quick`,
+`ui-phase`, and `verify-work`'s gap-plan loop. `plan-phase` @-imports this reference and states
+only its own bindings (counter name, artifact path, next step). The other three do not import it,
+so they restate the operative rules inline; this section is the authority they must agree with.
+
+1. **Do not spend budget.** Do NOT increment the iteration counter and do NOT update
+   `prev_issue_count`. Do NOT re-spawn the checker yet — the conflict is not a revised output.
+2. **Record**, where the host has a channel an arbitration loop reads. `review.md` emits one
+   fixed writer-owned slot immediately after the artifact title, between
+   `<!-- gsd:plan-revision-conflicts:begin -->` and
+   `<!-- gsd:plan-revision-conflicts:end -->`. When `workflow.plan_review_convergence` is enabled
+   and the phase `*-REVIEWS.md` already exists, `plan-phase` appends one line per conflict under
+   `## Plan-Revision Conflicts` inside that slot:
+
+```markdown
+- [ ] REVISION_CONFLICT {dimension}/{plan} — required_property: {property} | conflicts with: {locked decision D-nn / CLAUDE.md rule / plan constraint} | alternatives: {the agent's alternatives}
+```
+
+   A checkbox, not a table row: `- [ ] REVISION_CONFLICT` is open and `- [x] REVISION_CONFLICT`
+   is resolved. The reader counts matching open lines only inside the first fixed slot after the
+   artifact title; an identical marker in reviewer output is not state. An open line in the owned
+   slot blocks convergence even if this run is abandoned.
+   A workflow with no such channel (`quick` has no phase and no REVIEWS.md) skips this step.
+
+   Before appending, reuse the existing open line instead of appending a duplicate when its
+   sanitized fields identify the same conflict. This makes persisted conflict state idempotent.
+
+   **Sanitize before writing — the conflict text is agent-authored.** Every field comes from the
+   producing agent. Before appending, for EACH field: collapse every newline and tab to a single
+   space, and strip any leading `#`, `-`, `|` or backtick-fence run. Otherwise an embedded
+   newline can forge an extra conflict-shaped record inside the owned slot. One conflict is exactly
+   one line beginning `- [ ]`. Never append agent text verbatim, and never append a fenced block.
+3. **Resolve** — present the conflict and its alternatives to the user and ask which to take
+   (pattern: `gsd-core/references/gate-prompts.md`): adopt a named alternative / override the
+   named constraint and apply the hint / amend the constraint itself. Each option resolves the
+   conflict. Accepting the output with the blocker still open is NOT offered here — the blocking
+   `required_property` still fails, and that choice belongs to the cap escalation.
+4. **Close** — the workflow that wrote the line owns flipping it to `- [x]` once the resolution
+   has been applied, appending ` | resolved: {chosen resolution}`. Readers only read. A line left
+   open is a live blocker, never a stale artifact.
+5. **Re-spawn** with the chosen resolution, then re-evaluate the return from the top of this
+   handler — never fall through to the checker spawn. A second conflict is still a conflict, not
+   a revised output, and handing it to the checker would check the conflict message.
+
+**Bounded — two ways, because one is evadable.** Not incrementing must not make this path
+unbounded:
+
+- **Repeat.** A conflict naming the SAME `required_property` twice in a row means the chosen
+  resolution did not take. Stop re-spawning; escalate as a stall.
+- **Total.** Count every conflict return in this revision loop, whatever property each names. On
+  the THIRD, stop and escalate — an agent that alternates property names never trips the repeat
+  rule, so the repeat rule alone leaves the loop unbounded. This total is what actually bounds the
+  path; the repeat rule just catches the common case sooner.
+
+Both escalate through the same gate the iteration cap uses. A conflict still never consumes a
+revision iteration — the cap on conflicts is separate from, and additional to, the cap on
+revisions.
+
+**No workflow hands a conflict to a loop and returns.** Asking the user is the route everywhere;
+recording is in addition to asking, never instead of it. `plan-phase` in particular never invokes
+`/gsd:plan-review-convergence` — it runs *inside* that loop, so invoking it would be a cycle, and
+"was I invoked by convergence?" is not a question the orchestrator can answer at runtime.
+
 ### After 3 Iterations
 
 If issues persist after 3 revision cycles:
@@ -95,3 +200,5 @@ If issues persist after 3 revision cycles:
 - **Each iteration gets a fresh agent spawn** -- don't try to continue in the same context
 - **Checker feedback must be inlined** -- the revision agent needs to see exactly what failed
 - **Don't silently swallow issues** -- always present the final state to the user after exiting the loop
+- **A remediation hint is an example, not an order** -- an issue satisfied through a smaller valid
+  mechanism is addressed, and counts as resolved for the issue-count and stall checks

package/gsd-core/references/tdd.md

@@ -94,9 +94,10 @@ After completion, create SUMMARY.md with:
 **RED - Write failing test:**
 1. Create test file following project conventions
 2. Write test describing expected behavior (from `<behavior>` element)
-3. Run test - it MUST fail
-4. If test passes: feature exists or test is wrong. Investigate.
-5. Commit: `test({phase}-{plan}): add failing test for [feature]`
+3. Run test - it MUST fail **intentionally** (#3770): the TARGET test you named must be the test that fails, on an assertion for the planned behavior. A nonzero exit alone is NOT RED — syntax errors, zero-test discovery, fixture crashes, parser errors, and unrelated assertions are INVALID_RED and must not authorize GREEN.
+4. Persist the RED evidence record (command, exit code, failing test, expected result, actual result) and verify it: `gsd_run check tdd-red-evidence <record.json>`. Only verdict `RED_EVIDENCE_OK` satisfies the RED gate; `INVALID_RED` blocks GREEN until the RED phase is fixed.
+5. If test passes: feature exists or test is wrong. Investigate.
+6. Commit: `test({phase}-{plan}): add failing test for [feature]`
 
 **GREEN - Implement to pass:**
 1. Write minimal code to make test pass
@@ -256,26 +257,30 @@ When `workflow.tdd_mode` is enabled in config, the RED/GREEN/REFACTOR gate seque
 
 | Gate | Required | Commit Pattern | Validation |
 |------|----------|---------------|------------|
-| RED | Yes | `test({phase}-{plan}): ...` | Test exists AND fails before implementation |
+| RED | Yes | `test({phase}-{plan}): ...` | Test exists AND fails before implementation — intentionally: `check tdd-red-evidence` returns `RED_EVIDENCE_OK` (target test failed on an assertion for the behavior; anything else is INVALID_RED) |
 | GREEN | Yes | `feat({phase}-{plan}): ...` | Test passes after implementation |
 | REFACTOR | No | `refactor({phase}-{plan}): ...` | Tests still pass after cleanup |
 
 ### Fail-Fast Rules
 
 1. **Unexpected GREEN in RED phase:** If the test passes before any implementation code is written, STOP. The feature may already exist or the test is wrong. Investigate before proceeding.
-2. **Missing RED commit:** If no `test(...)` commit precedes the `feat(...)` commit, the TDD discipline was violated. Flag in SUMMARY.md.
-3. **REFACTOR breaks tests:** Undo the refactor immediately. Commit was premature — refactor in smaller steps.
+2. **INVALID_RED in RED phase (#3770):** A nonzero exit is not RED by itself. Zero-test discovery, fixture/load crashes, nonzero exits with no failing test, unrelated failing tests, and unexpected greens all classify as INVALID_RED (`gsd_run check tdd-red-evidence`). STOP and fix the RED phase — do NOT proceed to GREEN.
+3. **Missing RED commit:** If no `test(...)` commit precedes the `feat(...)` commit, the TDD discipline was violated. Flag in SUMMARY.md.
+4. **REFACTOR breaks tests:** Undo the refactor immediately. Commit was premature — refactor in smaller steps.
 
 ### Executor Gate Validation
 
 After completing a `type: tdd` plan, the executor validates the git log:
 ```bash
+# The commit protocol promises no zero-padding for ${PHASE}/${PLAN} — strip both and
+# match the commit-scope position anchored (#4003).
+PHASE_N=$((10#${PHASE})); PLAN_N=$((10#${PLAN}))
 # Check for RED gate commit
-git log --oneline --grep="^test(${PHASE}-${PLAN})" | head -1
+git log --oneline -E --grep="^test\((0*${PHASE_N})-(0*${PLAN_N})\):" | head -1
 # Check for GREEN gate commit  
-git log --oneline --grep="^feat(${PHASE}-${PLAN})" | head -1
+git log --oneline -E --grep="^feat\((0*${PHASE_N})-(0*${PLAN_N})\):" | head -1
 # Check for optional REFACTOR gate commit
-git log --oneline --grep="^refactor(${PHASE}-${PLAN})" | head -1
+git log --oneline -E --grep="^refactor\((0*${PHASE_N})-(0*${PLAN_N})\):" | head -1
 ```
 
 If RED or GREEN gate commits are missing, add a `## TDD Gate Compliance` section to SUMMARY.md with the violation details.

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/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/verification-report.md

@@ -12,6 +12,11 @@ phase: XX-name
 verified: YYYY-MM-DDTHH:MM:SSZ
 status: passed | gaps_found | human_needed
 score: N/M must-haves verified
+covered_files: # #4155 — see agents/gsd-verifier.md's "Create VERIFICATION.md" step for what belongs here and how to compute it
+  - .planning/phases/XX-name/{phase_num}-{plan}-PLAN.md
+  - .planning/phases/XX-name/{phase_num}-{plan}-SUMMARY.md
+  - src/{changed-file}.cts
+covered_digest: "v1:sha256:{digest from verification.fingerprint}"
 behavior_unverified: 0 # Count of ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truths (present + wired, behavior not exercised)
 behavior_unverified_items: # Only if behavior_unverified > 0 — the truths above as structured items; emitted regardless of overall status
   - truth: "Observable truth whose state transition or cancellation/cleanup/ordering invariant no test exercises"

package/gsd-core/workflows/add-backlog.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 # Add Backlog Item Workflow
 
 Invoked by `/gsd:capture --backlog` (`commands/gsd/capture.md`).

package/gsd-core/workflows/add-phase.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Add a new integer phase to the end of the current milestone in the roadmap. Automatically calculates next phase number, creates phase directory, and updates roadmap structure.
 </purpose>

package/gsd-core/workflows/add-tests.md

@@ -40,7 +40,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 
 Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `response_language`.
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 Verify the phase directory exists. If not:
 ```

package/gsd-core/workflows/add-todo.md

@@ -19,7 +19,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 
 Extract from init JSON: `commit_docs`, `date`, `timestamp`, `todo_count`, `todos`, `pending_dir`, `todos_dir_exists`, `response_language`.
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 Ensure directories exist:
 ```bash

package/gsd-core/workflows/ai-integration-phase.md

@@ -27,7 +27,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 
 Parse JSON for: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_context`, `has_research`, `commit_docs`, `response_language`.
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 **File paths:** `state_path`, `roadmap_path`, `requirements_path`, `context_path`.
 

package/gsd-core/workflows/analyze-dependencies.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Analyze ROADMAP.md phases for dependency relationships before execution. Detect file overlap between phases, semantic API/data-flow dependencies, and suggest `Depends on` entries to prevent merge conflicts during parallel execution by `/gsd:manager`.
 </purpose>

package/gsd-core/workflows/audit-fix.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Autonomous audit-to-fix pipeline. Runs an audit, parses findings, classifies each as
 auto-fixable vs manual-only, spawns executor agents for fixable issues, runs tests

package/gsd-core/workflows/audit-milestone.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Verify milestone achieved its definition of done by aggregating phase verifications, checking cross-phase integration, and assessing requirements coverage. Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
 </purpose>

package/gsd-core/workflows/audit-uat.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Cross-phase audit of all UAT and verification files. Finds every outstanding item (pending, skipped, blocked, human_needed), optionally verifies against the codebase to detect stale docs, and produces a prioritized human test plan.
 </purpose>

package/gsd-core/workflows/autonomous.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 
 Drive milestone phases autonomously — all remaining phases, a range via `--from N`/`--to N`, or a single phase via `--only N`. For each incomplete phase: discuss → plan → execute using Skill() flat invocations. When `--converge` or `--cross-ai` is set, route the planning step through plan-review convergence before execution. Pauses only for explicit user decisions (grey area acceptance, blockers, validation requests). Re-reads ROADMAP.md after each phase to catch dynamically inserted phases.