@opengsd/gsd-core 1.9.1 → 1.11.0

package/gsd-core/references/verifier-phase-gates.md

@@ -0,0 +1,192 @@
+# Verifier Phase Gates
+
+> Loaded eagerly by `agents/gsd-verifier.md` (`<required_reading>`). Carries the three
+> verification-time gates that lived in the retired `verify-phase` workflow
+> (#1892 / epic #1891 F7): decision-coverage validation (#2492), the test-quality audit,
+> and infrastructure-phase human-verification scoping (#2504) — plus the backstop-abstention
+> reporting contract (#3206). Run each gate at its named
+> agent step; `gsd_run` is the launcher shim defined in the agent's own Step 1 block.
+
+## verify_decisions — Decision Coverage Gate (run after Step 6, requirements coverage)
+
+<step name="verify_decisions">
+**Decision coverage validation gate (issue #2492).**
+
+After requirements coverage, also check that each trackable CONTEXT.md
+`<decisions>` entry shows up somewhere in the shipped artifacts (plans,
+SUMMARY.md, files modified by the phase, or recent commit subjects on the
+phase branch).
+
+This gate is **non-blocking / warning only** by deliberate asymmetry with
+the plan-phase translation gate. The plan-phase gate already blocked at
+translation time, so by the time verification runs every decision has
+either been translated or explicitly deferred. This gate's job is to
+surface decisions that *were* translated but vanished during execution —
+that's a soft signal because "honors a decision" is a fuzzy substring
+heuristic, and we don't want a paraphrase miss to fail an otherwise good
+phase.
+
+**Skip if** `workflow.context_coverage_gate` is explicitly set to `false`
+(absent key = enabled). Also skip cleanly when CONTEXT.md is missing or has
+no `<decisions>` block.
+
+```bash
+GATE_CFG=$(gsd_run query config-get workflow.context_coverage_gate 2>/dev/null || echo "true")
+if [ "$GATE_CFG" != "false" ]; then
+  CONTEXT_PATH=$(ls "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null | head -1)  # #2962: not a for-glob (zsh aborts)
+  DECISION_RESULT=$(gsd_run query check.decision-coverage-verify "${PHASE_DIR}" "${CONTEXT_PATH}")
+fi
+```
+
+The handler returns JSON `{ skipped, blocking: false, total, honored,
+not_honored: [...], message }`.
+
+**Reporting:** Append the handler's `message` (a `### Decision Coverage`
+section) to VERIFICATION.md regardless of outcome — even when all
+decisions are honored, recording the count helps reviewers spot drift over
+time. Set `decision_coverage` in the verification result to
+`{honored, total, not_honored: [...]}` so downstream tooling can read it.
+
+**Status impact:** none. The decision gate does NOT influence the
+`gaps_found` / `human_needed` / `passed` decision tree in Step 9. Its
+findings are warnings the user reviews and may act on by re-opening the
+phase or by acknowledging the decision was abandoned intentionally.
+</step>
+
+## audit_test_quality (run after Step 7b, alongside anti-patterns)
+
+<step name="audit_test_quality">
+**Verify that tests PROVE what they claim to prove.**
+
+This step catches test-level deceptions that pass all prior checks: files exist, are substantive, are wired, and tests pass — but the tests don't actually validate the requirement.
+
+**1. Identify requirement-linked test files**
+
+From PLAN and SUMMARY files, map each requirement to the test files that are supposed to prove it.
+
+**2. Disabled test scan**
+
+For ALL test files linked to requirements, search for disabled/skipped patterns:
+
+```bash
+grep -rn -E "it\.skip|describe\.skip|test\.skip|xit\(|xdescribe\(|xtest\(|@pytest\.mark\.skip|@unittest\.skip|#\[ignore\]|\.pending|it\.todo|test\.todo" "$TEST_FILE"
+```
+
+**Rule:** A disabled test linked to a requirement = requirement NOT tested.
+- 🛑 BLOCKER if the disabled test is the only test proving that requirement
+- ⚠️ WARNING if other active tests also cover the requirement
+
+**3. Circular test detection**
+
+Search for scripts/utilities that generate expected values by running the system under test:
+
+```bash
+grep -rn -E "writeFileSync|writeFile|fs\.write|open\(.*w\)" "$TEST_DIRS"
+```
+
+For each match, check if it also imports the system/service/module being tested. If a script both imports the system-under-test AND writes expected output values → CIRCULAR.
+
+**Circular test indicators:**
+- Script imports a service AND writes to fixture files
+- Expected values have comments like "computed from engine", "captured from baseline"
+- Script filename contains "capture", "baseline", "generate", "snapshot" in test context
+- Expected values were added in the same commit as the test assertions
+
+**Rule:** A test comparing system output against values generated by the same system is circular. It proves consistency, not correctness.
+
+**4. Expected value provenance** (for comparison/parity/migration requirements)
+
+When a requirement demands comparison with an external source ("identical to X", "matches Y", "same output as Z"):
+
+- Is the external source actually invoked or referenced in the test pipeline?
+- Do fixture files contain data sourced from the external system?
+- Or do all expected values come from the new system itself or from mathematical formulas?
+
+**Provenance classification:**
+- VALID: Expected value from external/legacy system output, manual capture, or independent oracle
+- PARTIAL: Expected value from mathematical derivation (proves formula, not system match)
+- CIRCULAR: Expected value from the system being tested
+- UNKNOWN: No provenance information — treat as SUSPECT
+
+**5. Assertion strength**
+
+For each test linked to a requirement, classify the strongest assertion:
+
+| Level | Examples | Proves |
+|-------|---------|--------|
+| Existence | `toBeDefined()`, `!= null` | Something returned |
+| Type | `typeof x === 'number'` | Correct shape |
+| Status | `code === 200` | No error |
+| Value | `toEqual(expected)`, `toBeCloseTo(x)` | Specific value |
+| Behavioral | Multi-step workflow assertions | End-to-end correctness |
+
+If a requirement demands value-level or behavioral-level proof and the test only has existence/type/status assertions → INSUFFICIENT.
+
+**6. Coverage quantity**
+
+If a requirement specifies a quantity of test cases (e.g., "30 calculations"), check if the actual number of active (non-skipped) test cases meets the requirement.
+
+**Reporting — add to VERIFICATION.md:**
+
+```markdown
+### Test Quality Audit
+
+| Test File | Linked Req | Active | Skipped | Circular | Assertion Level | Verdict |
+|-----------|-----------|--------|---------|----------|-----------------|---------|
+
+**Disabled tests on requirements:** {N} → {BLOCKER if any req has ONLY disabled tests}
+**Circular patterns detected:** {N} → {BLOCKER if any}
+**Insufficient assertions:** {N} → {WARNING}
+```
+
+**Impact on status:** Any BLOCKER from test quality audit → overall status = `gaps_found` (Step 9 rule 1), regardless of other checks passing.
+</step>
+
+## identify_human_verification — infrastructure/foundation scoping (apply at Step 8)
+
+**First: determine if this is an infrastructure/foundation phase.**
+
+Infrastructure and foundation phases — code foundations, database schema, internal APIs, data models, build tooling, CI/CD, internal service integrations — have no user-facing elements by definition. For these phases:
+
+- Do NOT invent artificial manual steps (e.g., "manually run git commits", "manually invoke methods", "manually check database state").
+- Mark human verification as **N/A** with rationale: "Infrastructure/foundation phase — no user-facing elements to test manually."
+- Set `human_verification: []` and do **not** produce a `human_needed` status solely due to lack of user-facing features.
+- Only add human verification items if the phase goal or success criteria explicitly describe something a user would interact with (UI, CLI command output visible to end users, external service UX).
+- **Exception — behavior-unverified truths still count.** A truth marked ⚠️ PRESENT_BEHAVIOR_UNVERIFIED (a state transition or a cancellation/cleanup/ordering invariant with no test exercising it) is a behavioral-evidence gap, not an artificial user-facing step. Record it in `behavior_unverified_items` and emit a human-verification item for it **even on an infrastructure/foundation phase** — these invariants are exactly where infra phases hide runtime state leaks. Such a truth drives `human_needed`; the auto-pass-UAT shortcut applies only to the absence of user-facing UX, never to a behavior-unverified invariant. The same carve-out covers an **abstained non-inferable truth** (⚠️ `insufficient_spec`, § Backstop abstention below) — an insufficient-spec gap is an evidence gap, not a user-facing step, so it too still emits its human-verification item and drives `human_needed` on an infrastructure phase.
+
+**How to determine if a phase is infrastructure/foundation:**
+- Phase goal or name contains: "foundation", "infrastructure", "schema", "database", "internal API", "data model", "scaffolding", "pipeline", "tooling", "CI", "migrations", "service layer", "backend", "core library"
+- Phase success criteria describe only technical artifacts (files exist, tests pass, schema is valid) with no user interaction required
+- There is no UI, CLI output visible to end users, or real-time behavior to observe
+
+**If the phase IS infrastructure/foundation:** auto-pass UAT — skip the human verification items list entirely, **except any ⚠️ PRESENT_BEHAVIOR_UNVERIFIED or abstained ⚠️ `insufficient_spec` truth (see exception above), which still emits a human-verification item and drives `human_needed`.** Only when no such excepted truth exists, log:
+
+```markdown
+## Human Verification
+
+N/A — Infrastructure/foundation phase with no user-facing elements.
+All acceptance criteria are verifiable programmatically.
+```
+
+**If the phase IS user-facing:** only flag items that genuinely require a human — per the Step 8 always/uncertain lists already in the agent. Do not invent steps.
+
+## Backstop abstention — reporting contract (#3206, companion to agent Step 3 item 5b)
+
+When a non-inferable (`verification: backstop`) truth abstains for lack of explicit evidence:
+
+- **Never silent, never a hard halt.** *Interactive:* the abstained item routes to the end-of-phase
+  human checkpoint. *Autonomous (AFK):* it produces a prominent `unverified — held-out test
+  recommended` flag and the completion line reads "complete with N unverified non-inferable checks";
+  the run neither silently passes the blind spot nor hard-halts.
+- **Distinguishable reason.** The abstain disposition carries `reason: insufficient_spec` so its
+  `human_needed` outcome is never conflated with an ordinary manual-UAT `human_needed`.
+- **Infrastructure phases included.** This rides the same carve-out as ⚠️ PRESENT_BEHAVIOR_UNVERIFIED
+  in the infrastructure-phase gate above: an abstention is an evidence gap, not a user-facing step,
+  so the infra auto-pass-UAT shortcut never absorbs it.
+
+Full protocol and rationale: `gsd-core/references/honest-verifier.md`.
+
+## Lazy references
+
+- **Per-stack verification patterns:** before Step 4 (artifact verification) on an unfamiliar stack, Read `~/.claude/gsd-core/references/verification-patterns.md` — the grep catalog for React/Next.js components, API routes, database schema, and the universal stub patterns. Read it lazily (only the sections for the stack under verification); it is too large to load wholesale on every run.
+- **Canonical report shape:** the emitted VERIFICATION.md follows `@~/.claude/gsd-core/templates/verification-report.md` — the template whose Guidelines and row shapes `src/uat.cts` treats as canonical when consuming verification output.

package/gsd-core/references/verifier-wiring-patterns.md

@@ -0,0 +1,100 @@
+# Verifier wiring and data-flow patterns
+
+Full pattern bodies for `agents/gsd-verifier.md`, extracted per
+`DEFECT.AGENT-FILE-SIZE-CAP-BREACH` (issue #2995, epic #1671 Phase 6.4). The agent
+keeps the step and its checklist; the per-pattern detail and shell recipes live here.
+
+Artifacts that pass Levels 1-3 (exist, substantive, wired) can still be hollow if their data source produces empty or hardcoded values. Level 4 traces upstream from the artifact to verify real data flows through the wiring.
+
+**When to run:** For each artifact that passes Level 3 (WIRED) and renders dynamic data (components, pages, dashboards — not utilities or configs).
+
+**How:**
+
+1. **Identify the data variable** — what state/prop does the artifact render?
+
+```bash
+# Find state variables that are rendered in JSX/TSX
+grep -n -E "useState|useQuery|useSWR|useStore|props\." "$artifact" 2>/dev/null
+```
+
+2. **Trace the data source** — where does that variable get populated?
+
+```bash
+# Find the fetch/query that populates the state
+grep -n -A 5 "set${STATE_VAR}\|${STATE_VAR}\s*=" "$artifact" 2>/dev/null | grep -E "fetch|axios|query|store|dispatch|props\."
+```
+
+3. **Verify the source produces real data** — does the API/store return actual data or static/empty values?
+
+```bash
+# Check the API route or data source for real DB queries vs static returns
+grep -n -E "prisma\.|db\.|query\(|findMany|findOne|select|FROM" "$source_file" 2>/dev/null
+# Flag: static returns with no query
+grep -n -E "return.*json\(\s*\[\]|return.*json\(\s*\{\}" "$source_file" 2>/dev/null
+```
+
+4. **Check for disconnected props** — props passed to child components that are hardcoded empty at the call site
+
+```bash
+# Find where the component is used and check prop values
+grep -r -A 3 "<${COMPONENT_NAME}" "${search_path:-src/}" --include="*.tsx" 2>/dev/null | grep -E "=\{(\[\]|\{\}|null|''|\"\")\}"
+```
+
+> These two status tables are intentionally mirrored in `agents/gsd-verifier.md`.
+> The status vocabulary is load-bearing verifier output and must remain in the
+> agent body (#2995); this copy is here so the procedure below reads standalone.
+
+**Data-flow status:**
+
+| Data Source | Produces Real Data | Status |
+| ---------- | ------------------ | ------ |
+| DB query found | Yes | ✓ FLOWING |
+| Fetch exists, static fallback only | No | ⚠️ STATIC |
+| No data source found | N/A | ✗ DISCONNECTED |
+| Props hardcoded empty at call site | No | ✗ HOLLOW_PROP |
+
+**Final Artifact Status (updated with Level 4):**
+
+| Exists | Substantive | Wired | Data Flows | Status |
+| ------ | ----------- | ----- | ---------- | ------ |
+| ✓ | ✓ | ✓ | ✓ | ✓ VERIFIED |
+| ✓ | ✓ | ✓ | ✗ | ⚠️ HOLLOW — wired but data disconnected |
+| ✓ | ✓ | ✗ | - | ⚠️ ORPHANED |
+| ✓ | ✗ | - | - | ✗ STUB |
+| ✗ | - | - | - | ✗ MISSING |
+
+### Pattern: Component → API
+
+```bash
+grep -E "fetch\(['\"].*$api_path|axios\.(get|post).*$api_path" "$component" 2>/dev/null
+grep -A 5 "fetch\|axios" "$component" | grep -E "await|\.then|setData|setState" 2>/dev/null
+```
+
+Status: WIRED (call + response handling) | PARTIAL (call, no response use) | NOT_WIRED (no call)
+
+### Pattern: API → Database
+
+```bash
+grep -E "prisma\.$model|db\.$model|$model\.(find|create|update|delete)" "$route" 2>/dev/null
+grep -E "return.*json.*\w+|res\.json\(\w+" "$route" 2>/dev/null
+```
+
+Status: WIRED (query + result returned) | PARTIAL (query, static return) | NOT_WIRED (no query)
+
+### Pattern: Form → Handler
+
+```bash
+grep -E "onSubmit=\{|handleSubmit" "$component" 2>/dev/null
+grep -A 10 "onSubmit.*=" "$component" | grep -E "fetch|axios|mutate|dispatch" 2>/dev/null
+```
+
+Status: WIRED (handler + API call) | STUB (only logs/preventDefault) | NOT_WIRED (no handler)
+
+### Pattern: State → Render
+
+```bash
+grep -E "useState.*$state_var|\[$state_var," "$component" 2>/dev/null
+grep -E "\{.*$state_var.*\}|\{$state_var\." "$component" 2>/dev/null
+```
+
+Status: WIRED (state displayed) | NOT_WIRED (state exists, not rendered)

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

@@ -17,7 +17,7 @@ The framing fires when:
 - The phase under verification has `**Mode:** mvp` in ROADMAP.md (parsed via `gsd-tools 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 `references/planner-mvp-mode.md`).
+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`).
 
 ## Generated UAT script structure under MVP mode
 

package/gsd-core/references/workstream-flag.md

@@ -9,8 +9,12 @@ parallel milestone work by multiple Claude Code instances on the same codebase.
 
 1. `--ws <name>` flag (explicit, highest priority)
 2. `GSD_WORKSTREAM` environment variable (per-instance)
-3. Session-scoped active workstream pointer in temp storage (per runtime session / terminal)
-4. `.planning/active-workstream` file (legacy shared fallback when no session key exists)
+3. Session-scoped active workstream pointer in temp storage (per runtime session / terminal),
+   when that pointer exists and is non-blank
+4. `.planning/active-workstream` file — consulted whenever step 3 has nothing to say: either
+   there is no session identity at all, or there is one but it has never pointed at a
+   workstream. A session that already has its own pointer (step 3) is never overridden by
+   this step, even if that pointer is stale.
 5. `null` — flat mode (no workstreams)
 
 ## Why session-scoped pointers exist
@@ -20,16 +24,22 @@ Claude/Codex instances are active on the same repo at the same time. One session
 silently repoint another session's `STATE.md`, `ROADMAP.md`, and phase paths.
 
 GSD now prefers a session-scoped pointer keyed by runtime/session identity
-(`GSD_SESSION_KEY`, `CODEX_THREAD_ID`, `CLAUDE_CODE_SSE_PORT`, terminal session IDs,
+(`GSD_SESSION_KEY`, `CODEX_THREAD_ID`, `CLAUDE_CODE_SESSION_ID`,
+`CLAUDE_CODE_SSE_PORT`, terminal session IDs,
 or the controlling TTY). This keeps concurrent sessions isolated while preserving
 legacy compatibility for runtimes that do not expose a stable session key.
 
+A session that has never set its own pointer inherits `.planning/active-workstream`
+(step 4) rather than silently falling back to flat mode — this does not weaken the
+isolation guarantee above: inheritance only fires when a session's own pointer is
+absent, and a session that has ever set one is never repointed by the shared file.
+
 ## Session Identity Resolution
 
 When GSD resolves the session-scoped pointer in step 3 above, it uses this order:
 
 1. Explicit runtime/session env vars such as `GSD_SESSION_KEY`, `CODEX_THREAD_ID`,
-   `CLAUDE_SESSION_ID`, `CLAUDE_CODE_SSE_PORT`, `OPENCODE_SESSION_ID`,
+   `CLAUDE_SESSION_ID`, `CLAUDE_CODE_SESSION_ID`, `CLAUDE_CODE_SSE_PORT`, `OPENCODE_SESSION_ID`,
    `GEMINI_SESSION_ID`, `CURSOR_SESSION_ID`, `WINDSURF_SESSION_ID`,
    `TERM_SESSION_ID`, `WT_SESSION`, `TMUX_PANE`, and `ZELLIJ_SESSION_NAME`
 2. `TTY` or `SSH_TTY` if the shell/runtime already exposes the terminal path
@@ -47,7 +57,13 @@ routing hot path.
 
 Session-scoped pointers are intentionally lightweight and best-effort:
 
-- Clearing a workstream for one session removes only that session's pointer file
+- Clearing a workstream for one session removes only that session's pointer file.
+  This returns that session to step 4 of Resolution Priority above — it goes back
+  to **inheriting** `.planning/active-workstream` (if a marker exists there), not
+  to flat mode. A cleared session with no marker present resolves to `null`; a
+  cleared session with a marker present resolves to whatever that marker names.
+  To force flat mode for a cleared session, remove the shared marker file, or use
+  an explicit override such as `--ws` / `GSD_WORKSTREAM` on the command in question.
 - If that was the last pointer for the repo, GSD also removes the now-empty
   per-project temp directory
 - If sibling session pointers still exist, the temp directory is left in place
@@ -76,7 +92,7 @@ This ensures workstream scope chains automatically through the workflow:
 ├── config.json         # Shared
 ├── milestones/         # Shared
 ├── codebase/           # Shared
-├── active-workstream   # Legacy shared fallback only
+├── active-workstream   # Shared marker; inherited when a session has no pointer of its own
 └── workstreams/
     ├── feature-a/      # Workstream A
     │   ├── STATE.md

package/gsd-core/references/worktree-branch-check.md

@@ -30,8 +30,8 @@ if [ "$HEAD_REF" = "DETACHED" ] || echo "$ACTUAL_BRANCH" | grep -Eq '^(main|mast
   echo "FATAL: worktree HEAD on '$ACTUAL_BRANCH' (expected agent-* or worktree-agent-*); refusing to commit or self-recover via 'git update-ref' (#2924)." >&2
   exit 42
 fi
-if ! echo "$ACTUAL_BRANCH" | grep -Eq '^(worktree-)?agent-[A-Za-z0-9._/-]+$'; then
-  echo "FATAL: worktree HEAD '$ACTUAL_BRANCH' is not in the agent-* / worktree-agent-* namespace; refusing to commit (#2924)." >&2
+if ! echo "$ACTUAL_BRANCH" | grep -Eq '^((worktree-)?agent-|worktree-wf_)[A-Za-z0-9._/-]+$'; then
+  echo "FATAL: worktree HEAD '$ACTUAL_BRANCH' is not in the agent-* / worktree-agent-* / worktree-wf_* namespace; refusing to commit (#2924)." >&2
   exit 42
 fi
 ACTUAL_BASE=$(git rev-parse HEAD)

package/gsd-core/templates/discussion-log.md

@@ -4,7 +4,7 @@ Template for `.planning/phases/XX-name/{phase_num}-DISCUSSION-LOG.md` — audit
 
 **Purpose:** Software audit trail for decision-making. Captures all options considered, not just the selected one. Separate from CONTEXT.md which is the implementation artifact consumed by downstream agents.
 
-**NOT for LLM consumption.** This file should never be referenced in `<files_to_read>` blocks or agent prompts.
+**NOT for LLM consumption.** This file should never be referenced in `<required_reading>` blocks or agent prompts.
 
 ## Format
 

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

@@ -187,7 +187,7 @@ autonomous: true
 
 # Plan 02 - Protected features (needs auth)
 wave: 2
-depends_on: ["01"]
+depends_on: ["01-01"]
 files_modified: [src/features/dashboard.ts]
 autonomous: true
 ```
@@ -199,7 +199,7 @@ Plan 02 in Wave 2 waits for Plan 01 in Wave 1 - genuine dependency on auth types
 ```yaml
 # Plan 03 - UI with verification
 wave: 3
-depends_on: ["01", "02"]
+depends_on: ["01-01", "01-02"]
 files_modified: [src/components/Dashboard.tsx]
 autonomous: false  # Has checkpoint:human-verify
 ```
@@ -606,5 +606,3 @@ Task completion ≠ Goal achievement. A task "create chat component" can complet
 4. Verification subagent checks must_haves against codebase
 5. Gaps found → fix plans created → execute → re-verify
 6. All must_haves pass → phase complete
-
-See `~/.claude/gsd-core/workflows/verify-phase.md` for verification logic.

package/gsd-core/templates/state.md

@@ -79,11 +79,11 @@ None yet.
 
 ## Deferred Items
 
-Items acknowledged and carried forward from previous milestone close:
+Items acknowledged and deferred at milestone close, most recent first:
 
-| Category | Item | Status | Deferred At |
-|----------|------|--------|-------------|
-| *(none)* | | | |
+| Category | Item | Status | Deferred At | Milestone |
+|----------|------|--------|-------------|-----------|
+| *(none)* | | | | |
 
 ## Session Continuity
 

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

@@ -28,6 +28,8 @@ completed: YYYY-MM-DD
 status: complete
 ---
 
+**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.
+
 # Phase [X]: [Name] Summary (Complex)
 
 **[Substantive one-liner describing outcome]**

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

@@ -25,6 +25,8 @@ completed: YYYY-MM-DD
 status: complete
 ---
 
+**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.
+
 # Phase [X]: [Name] Summary (Minimal)
 
 **[Substantive one-liner describing outcome]**

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

@@ -27,6 +27,8 @@ completed: YYYY-MM-DD
 status: complete
 ---
 
+**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.
+
 # Phase [X]: [Name] Summary
 
 **[Substantive one-liner describing outcome]**

package/gsd-core/templates/summary.md

@@ -171,6 +171,8 @@ None - no external service configuration required.
 **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>

package/gsd-core/templates/verification-report.md

@@ -18,6 +18,10 @@ behavior_unverified_items: # Only if behavior_unverified > 0 — the truths abov
     test: "What to trigger"
     expected: "What state must hold afterward"
     why_human: "Why presence checks can't see it"
+coincidental_reliance_items: # Only if a ✓ VERIFIED truth holds incidentally — emitted regardless of overall status (survives gaps_found)
+  - truth: "Observable truth that holds incidentally"
+    reason: undeclared-precondition | incidental-ordering | fixture-only
+    harden: "Precondition/ordering to declare or enforce"
 ---
 
 # Phase {X}: {Name} Verification Report
@@ -35,7 +39,8 @@ behavior_unverified_items: # Only if behavior_unverified > 0 — the truths abov
 | 1 | {truth from must_haves} | ✓ VERIFIED | {what confirmed it} |
 | 2 | {truth from must_haves} | ✗ FAILED | {what's wrong} |
 | 3 | {truth from must_haves} | ⚠️ PRESENT_BEHAVIOR_UNVERIFIED | {present + wired; transition/invariant not exercised by a test — see Human Verification} |
-| 4 | {truth from must_haves} | ? UNCERTAIN | {why can't verify} |
+| 4 | {truth from must_haves} | ✓ VERIFIED (coincidental-reliance) | {holds, but incidentally — see coincidental_reliance_items} |
+| 5 | {truth from must_haves} | ? UNCERTAIN | {why can't verify} |
 
 **Score:** {N}/{M} truths verified ({P} present, behavior-unverified)
 
@@ -176,6 +181,9 @@ None — all verifiable items checked programmatically.
 **Per-truth states (Observable Truths `Status` column):**
 - `✓ VERIFIED` — supporting artifacts pass all checks; for a behavior-dependent truth, a behavioral test exercised the asserted behavior
 - `⚠️ PRESENT_BEHAVIOR_UNVERIFIED` — present + wired, but a state transition or cancellation/cleanup/ordering invariant was not exercised by any test. Counts toward `behavior_unverified`, routes to human verification, and is *excluded* from the verified score. Per-truth only — on its own the overall `status:` becomes `human_needed` (unless a higher-precedence `gaps_found` also applies); the item is preserved in `behavior_unverified_items` regardless.
+- `✓ VERIFIED (coincidental-reliance)` — an **advisory** qualifier on a truth that *is* verified but holds for an incidental reason rather than a guaranteed one (#1955): `undeclared-precondition` (state nothing in the phase's artifacts or a declared prerequisite guarantees), `incidental-ordering` (an order or side effect nothing in the code enforces), or `fixture-only` (the test's own setup establishes the precondition; the production path has no equivalent). The base `✓ VERIFIED` token is kept verbatim and leading, so it counts toward the verified score exactly as before — the advisory changes no score and no status, and never produces a human-verification item. Each flagged truth is listed in `coincidental_reliance_items` with the reason and what to harden. Not applied to a truth that never reached `✓ VERIFIED`, nor to a `PASSED (override)` truth.
+
+  **Filling this column — apply the reliance check to every `✓ VERIFIED` truth before writing the row.** Ask why the truth holds and classify the evidence you already recorded, not your confidence in it. Flag it when the evidence names one of the three reasons above. Do NOT flag: a precondition the code establishes or explicitly defaults; ordering the code enforces (await, explicit sequencing); a fixture merely supplying input the real caller also supplies; unease naming no specific state, ordering, or fixture. The check is endogenous and so weaker than an exogenous tag (`gsd-core/references/honest-verifier.md`) — which is why it is advisory and never a gate. The usual fix is to promote the hidden assumption into a declared precondition.
 - `✗ FAILED` — artifact missing, stub, or unwired
 - `? UNCERTAIN` — can't verify programmatically
 

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

@@ -112,10 +112,10 @@ Select the right AI framework for Phase {phase_number}: {phase_name}
 Goal: {phase_goal}
 </objective>
 
-<files_to_read>
+<required_reading>
 {context_path if exists}
 {requirements_path if exists}
-</files_to_read>
+</required_reading>
 
 <phase_context>
 Phase: {phase_number} — {phase_name}
@@ -161,10 +161,10 @@ Before editing, verify the section you are about to write is still a template pl
 <objective>
 </objective>
 
-<files_to_read>
+<required_reading>
 {ai_spec_path}
 {context_path if exists}
-</files_to_read>
+</required_reading>
 
 <input>
 framework: {primary_framework}
@@ -196,11 +196,11 @@ Before editing, verify the section you are about to write is still a template pl
 <objective>
 </objective>
 
-<files_to_read>
+<required_reading>
 {ai_spec_path}
 {context_path if exists}
 {requirements_path if exists}
-</files_to_read>
+</required_reading>
 
 <input>
 system_type: {system_type}
@@ -227,11 +227,11 @@ Write Sections 5, 6, and 7 of AI-SPEC.md
 AI-SPEC.md now contains domain context (Section 1b) — use it as your rubric starting point.
 </objective>
 
-<files_to_read>
+<required_reading>
 {ai_spec_path}
 {context_path if exists}
 {requirements_path if exists}
-</files_to_read>
+</required_reading>
 
 <input>
 system_type: {system_type}
@@ -258,10 +258,8 @@ Read the completed AI-SPEC.md. Check that:
 
 ## 11. Commit
 
-**If `commit_docs` is true:**
 ```bash
-git add "${AI_SPEC_FILE}"
-git commit -m "docs({phase_slug}): generate AI-SPEC.md — {primary_framework} + domain context + eval strategy"
+gsd_run query commit "docs({phase_slug}): generate AI-SPEC.md — {primary_framework} + domain context + eval strategy" --files "${AI_SPEC_FILE}"
 ```
 
 ## 12. Display Completion

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

@@ -124,6 +124,9 @@ For each phase's VERIFICATION.md, extract the expanded requirements table:
 
 For each phase's SUMMARY.md, extract `requirements-completed` from YAML frontmatter:
 ```bash
+# #2962: zsh aborts the block on an unmatched for-list glob (nomatch); bash passes it through. nullglob both.
+shopt -s nullglob 2>/dev/null; setopt NULL_GLOB 2>/dev/null
+
 for summary in .planning/phases/*-*/*-SUMMARY.md; do
   [ -e "$summary" ] || continue
   gsd_run query summary-extract "$summary" --fields requirements_completed --pick requirements_completed

package/gsd-core/workflows/autonomous/steps/converge-banner.md

@@ -0,0 +1 @@
+If `PLAN_STRATEGY` is `converge`, display: `Planning: Plan-review convergence enabled`

package/gsd-core/workflows/autonomous/steps/converge-dispatch-bg.md

@@ -0,0 +1,11 @@
+## Converge Dispatch (Background)
+
+If `PLAN_STRATEGY=converge`, print: `◆ Spawning background plan-convergence loop for phase ${PHASE_NUM}... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)`
+
+```
+Agent(
+  description="Plan convergence phase ${PHASE_NUM}: ${PHASE_NAME}",
+  run_in_background=true,
+  prompt="Run plan convergence for phase ${PHASE_NUM}: Skill(skill=\"gsd-plan-review-convergence\", args=\"${PHASE_NUM} ${CONVERGENCE_ARGS}\")"
+)
+```

package/gsd-core/workflows/autonomous/steps/converge-dispatch-inline.md

@@ -0,0 +1,7 @@
+## Converge Dispatch (Inline)
+
+If `PLAN_STRATEGY=converge`:
+
+```
+Skill(skill="gsd-plan-review-convergence", args="${PHASE_NUM} ${CONVERGENCE_ARGS}")
+```

package/gsd-core/workflows/autonomous/steps/converge-fail-fast.md

@@ -0,0 +1,21 @@
+## Converge Fail-Fast
+
+When `PLAN_STRATEGY` is `converge`, fail fast unless the existing convergence feature gate is enabled:
+
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+if [ "$PLAN_STRATEGY" = "converge" ]; then
+  CONVERGENCE_ENABLED=$(gsd_run query config-get workflow.plan_review_convergence 2>/dev/null || echo "false")
+  if [ "$CONVERGENCE_ENABLED" != "true" ]; then
+    printf '%s\n' \
+      'gsd-autonomous --converge is disabled (workflow.plan_review_convergence=false).' \
+      '' \
+      'Enable plan convergence with:' \
+      '' \
+      '  gsd config-set workflow.plan_review_convergence true' \
+      '' \
+      'Then re-run the autonomous command with --converge.'
+    exit 1
+  fi
+fi
+```