@opengsd/gsd-core 1.11.0 → 1.13.0

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/runtime-aware-dispatch.md

@@ -19,7 +19,7 @@ preserves named-dispatch behavior on older GSD installs that lack the query.
 
 The persona rides `${AGENT_SKILLS_<ROLE>}` (Phase 3 / #2510) regardless of the
 resolved type — on non-Claude runtimes with no `agent_skills` config,
-`gsd-tools query agent-skills <role>` returns the installed agent prompt as
+`gsd_run query agent-skills <role>` returns the installed agent prompt as
 the block. So a coder dispatch with the planner persona injected gives kimi-code
 the planner's behavior in the coder built-in's process.
 

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.
@@ -289,9 +294,7 @@ When `workflow.tdd_mode` is enabled, the execute-phase orchestrator inserts a co
 ### Review Checkpoint Format
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- TDD REVIEW — Phase {X}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+### TDD REVIEW — Phase {X}
 
 TDD Plans: {count} | Gate violations: {count}
 

package/gsd-core/references/ui-brand.md

@@ -2,14 +2,51 @@
 
 Visual patterns for user-facing GSD output. Orchestrators @-reference this file.
 
+## Separators and Banners
+
+**Never emit a fixed-width run of box-drawing characters.** A run of `━`, `─` or
+`═` is ordinary text to the host that renders your output. In a narrower pane it
+wraps, leaving orphan glyphs on a second line and coming apart from the heading it
+was meant to frame. Markdown adapts to the available width; a 53-character rule
+does not.
+
+Three forms, and nothing else:
+
+| Need | Emit |
+|---|---|
+| A titled section — stage, phase, checkpoint, completion, error | `### {TITLE}` (ATX heading) |
+| A break between two sections | `---` on its own line, **with a blank line above it** |
+| A framed panel of rows | `### {TITLE}` followed by the rows as plain lines |
+
+**The blank line above `---` is load-bearing, not cosmetic.** A `---` placed
+directly under a line of text is parsed as a setext heading underline for that
+line, not as a thematic break — the rule silently swallows the line above it. A
+blank line is what makes it a thematic break. (A blank line *after* `---` is
+optional: a thematic break is a leaf block, so whatever follows starts a new
+block either way. Add one where it reads better.)
+
+**A stage banner is a heading alone — do not put a `---` above it.** An ATX
+heading already separates, and it cannot be misparsed the way a bare `---` can.
+
+### Why this is unconditional, not per-runtime
+
+The alternative considered was a `rendersMarkdown` capability key, keeping
+line-art for terminal-oriented runtimes and Markdown for Markdown hosts. It was
+rejected: it needs a new descriptor key across every runtime plus the resolver,
+and it leaves two output conventions to keep in sync forever — the divergence
+class this repo already has a defect entry for. A heading and a thematic break
+carry the same structure in a plain terminal that a rule pair did, without
+committing to a width, so the second convention buys nothing. If a runtime ever
+turns up that genuinely needs line-art, add the key then, against that evidence.
+
+---
+
 ## Stage Banners
 
 Use for major workflow transitions.
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- GSD ► {STAGE NAME}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+### GSD ► {STAGE NAME}
 ```
 
 **Stage names (uppercase):**
@@ -25,20 +62,18 @@ Use for major workflow transitions.
 
 ---
 
-## Checkpoint Boxes
+## Checkpoint Panels
 
-User action required. 62-character width.
+User action required.
 
 ```
-╔══════════════════════════════════════════════════════════════╗
-║  CHECKPOINT: {Type}                                          ║
-╚══════════════════════════════════════════════════════════════╝
+### CHECKPOINT: {Type}
 
 {Content}
 
-──────────────────────────────────────────────────────────────
-→ {ACTION PROMPT}
-──────────────────────────────────────────────────────────────
+---
+
+**→ {ACTION PROMPT}**
 ```
 
 **Types:**
@@ -60,6 +95,9 @@ User action required. 62-character width.
 🎉 Milestone complete (only in banner)
 ```
 
+Status symbols are single characters, not runs — they do not wrap and are
+unaffected by the separator rule above.
+
 ---
 
 ## Progress Display
@@ -79,6 +117,9 @@ Tasks: 2/4 complete
 Plans: 3/5 complete
 ```
 
+The bar itself is a fixed 10-cell gauge, not a separator; it is intentionally
+fixed-width and stays as it is.
+
 ---
 
 ## Spawning Indicators
@@ -104,7 +145,7 @@ Plans: 3/5 complete
 Always at end of major completions.
 
 ```
-───────────────────────────────────────────────────────────────
+---
 
 ## ▶ Next Up
 
@@ -114,23 +155,19 @@ Always at end of major completions.
 
 `{copy-paste command}`
 
-───────────────────────────────────────────────────────────────
+---
 
 **Also available:**
 - `/gsd-alternative-1` — description
 - `/gsd-alternative-2` — description
-
-───────────────────────────────────────────────────────────────
 ```
 
 ---
 
-## Error Box
+## Error Panel
 
 ```
-╔══════════════════════════════════════════════════════════════╗
-║  ERROR                                                       ║
-╚══════════════════════════════════════════════════════════════╝
+### ERROR
 
 {Error description}
 
@@ -149,14 +186,21 @@ Always at end of major completions.
 | 3     | ○      | 0/2   | 0%       |
 ```
 
+Table rules use ASCII `-`, never box-drawing characters.
+
 ---
 
 ## Anti-Patterns
 
-- Varying box/banner widths
-- Mixing banner styles (`===`, `---`, `***`)
+- Fixed-width runs of `━`, `─` or `═` as separators — they wrap in a narrow pane
+- Box panels drawn with double-line box characters (U+2554, U+2557, U+255A, U+255D, U+2551, U+2560, U+2563) — the borders wrap independently of their contents. They are named here by code point rather than shown, because the guard below rejects the characters themselves anywhere in shipped content.
+- A `---` directly under a line of text with no blank line between — that is a setext heading underline, not a break, and it swallows the line above
+- Boxing a heading between two rules — the heading is the separator
+- Mixing banner styles (`===`, `***`)
 - Skipping `GSD ►` prefix in banners
 - Random emoji (`🚀`, `✨`, `💫`)
 - Missing Next Up block after completions
 
+Enforced by `tests/responsive-separators.test.cjs`.
+
 </ui_patterns>

package/gsd-core/references/ui-consideration-probe.md

@@ -69,5 +69,5 @@ closed). The **open subset is prose-owned in [domain-probes.md](./domain-probes.
 real-time/offline/optimistic-UI, deep accessibility (WCAG breadth), i18n / RTL depth, and
 emerging interaction paradigms (gesture/voice/reduced-motion/print) are open-ended and
 cue-triggered — they do not belong in this closed taxonomy. This probe **complements** the
-`gsd-ui-checker` six quality dimensions (it adds a state-coverage axis); it does not change the
+`gsd-ui-checker` seven quality dimensions (it adds a state-coverage axis); it does not change the
 BLOCK/FLAG/PASS enum or the dimensions themselves.

package/gsd-core/references/universal-anti-patterns.md

@@ -34,7 +34,7 @@ Reference: `gsd-core/references/questioning.md` for the full anti-pattern list.
 
 ## State Management Anti-Patterns
 
-15. **No direct Write/Edit to STATE.md or ROADMAP.md for mutations.** Always use `gsd-tools query` for registered state/roadmap handlers (e.g. `state.update`, `state.advance-plan`, `roadmap.update-plan-progress`), or legacy `node …/gsd-tools.cjs` for CLI-only commands. Direct Write tool usage bypasses safe update logic and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template is allowed.
+15. **No direct Write/Edit to STATE.md or ROADMAP.md for mutations.** Always use `gsd_run query` for registered state/roadmap handlers (e.g. `state.update`, `state.advance-plan`, `roadmap.update-plan-progress`), or legacy `node …/gsd-tools.cjs` for CLI-only commands. Direct Write tool usage bypasses safe update logic and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template is allowed.
 
 ## Behavioral Rules
 
@@ -53,7 +53,7 @@ Reference: `gsd-core/references/questioning.md` for the full anti-pattern list.
 ## GSD-Specific Rules
 
 24. **Do not** check for `mode === 'auto'` or `mode === 'autonomous'` -- GSD uses `yolo` config flag. Check `yolo: true` for autonomous mode, absence or `false` for interactive mode.
-25. **Prefer `gsd-tools query`** for orchestration when a handler exists; when shelling out to the legacy CLI, use **`gsd-tools.cjs`** (not `gsd-tools.js` or any other filename) — GSD ships the programmatic API as CommonJS for Node.js CLI compatibility.
+25. **Prefer `gsd_run query`** for orchestration when a handler exists; when shelling out to the legacy CLI, go through the same `gsd_run` launcher rather than naming the shim file. The shim is not on PATH under any name ending in `.cjs`, and an agent that meets the bare filename falls back to searching the filesystem for it — on Git Bash for Windows that is a full-drive `find.exe` traversal (#3809). `gsd_run` resolves the CommonJS shim itself across every runtime home.
 26. **Plan files MUST follow `{padded_phase}-{NN}-PLAN.md` pattern** (e.g., `01-01-PLAN.md`). Never use `PLAN-01.md`, `plan-01.md`, or any other variation -- gsd-tools detection depends on this exact pattern.
 27. **Do not start executing the next plan before writing the SUMMARY.md for the current plan** -- downstream plans may reference it via `@` includes.
 

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/verify-command-path-resolvability.md

@@ -0,0 +1,42 @@
+# Verify Command Path Resolvability (#2401)
+
+> Reference file for gsd-plan-checker agent. Loaded on-demand via `@` reference.
+
+**Question:** Does each `<automated>` command's target directory actually resolve from the
+executor's cwd (the project root)? Format sanity above asks whether the *pattern* can match;
+this asks whether the command can *run at all*.
+
+**Do not hand-reason the filesystem.** #2401 is precisely the failure of doing so: this
+checker flagged a bad `cd ../../frontend` (correct), then prescribed two successively-wrong
+replacement paths — the second citing a `package.json` that did not exist. Consume the
+deterministic probe result, never re-derive it yourself.
+
+`gsd-core/workflows/plan-phase.md` already runs the probe **before** spawning this checker and
+interpolates the result into the verification prompt as `{VERIFY_PATHS}`, inside a
+`<verify_command_path_probe>` block. This dimension reads that already-supplied JSON — it never
+invokes `gsd_run check verify-command-paths` itself. If `{VERIFY_PATHS}` is absent from the
+prompt, treat this dimension as silent (nothing to check) rather than trying to run the probe.
+
+The probe never executes command text (PLAN.md is untrusted, LLM-authored). It recognizes two
+grounded forms — a leading `cd <literal>` chain and `npm --prefix <literal>` — and refuses to
+guess at anything else.
+
+**Process:** for each row in `.commands`, act on `severity` only:
+
+| `severity` | `reason` | Action |
+|---|---|---|
+| `blocker` | `missing_dir` / `no_manifest` | **BLOCKER** — quote `rawTarget` and `target` verbatim |
+| `warning` | `dynamic_path` / `outside_root` / `script_missing` / `manifest_unreadable` | **WARNING** |
+| `none` | — | silent |
+
+Rules:
+- **Report, never prescribe.** State the target that failed to resolve and what was missing.
+  Choosing the replacement is the planner's job — it now receives the prior phase's proven
+  commands (see `prior_verify_commands` in the planning context).
+- `status: pending_creation` means an earlier task in this phase creates that directory. **Not
+  a finding.** Say nothing.
+- `unresolvable` means the probe could not ground the path (a variable, glob, substitution, or
+  `~`). That is a WARNING, never a BLOCKER — and never a licence to guess the literal path.
+- A non-empty `readError` means the probe **could not look**. Report that as a WARNING in its
+  own words; it is not a clean bill of health.
+- `MISSING …` sentinels are Dimension 8's business — this dimension stays silent on them.

package/gsd-core/references/verify-mvp-mode.md

@@ -14,7 +14,7 @@ The user-flow form mirrors what a real user does: open, fill, click, see. No HTT
 ## When this framing applies
 
 The framing fires when:
-- The phase under verification has `**Mode:** mvp` in ROADMAP.md (parsed via `gsd-tools query roadmap.get-phase --pick mode`).
+- The phase under verification has `**Mode:** mvp` in ROADMAP.md (parsed via `gsd_run query roadmap.get-phase --pick mode`).
 - AND the phase has a user-story-formatted goal (set by `/gsd mvp-phase` per Phase 2): "As a [user role], I want to [capability], so that [outcome]."
 
 If the phase has `mode: mvp` but the goal is NOT in user-story format, the verifier surfaces this as a discrepancy and asks the user to run `/gsd mvp-phase` to reformat the goal — same pattern as the planner agent under MVP_MODE (per `gsd-core/references/planner-mvp-mode.md`).