@opengsd/gsd-core 1.5.0-rc.4 → 1.5.0

package/gsd-core/references/prohibition-probe.md

@@ -110,20 +110,98 @@ lifecycle is identical to the edge-probe, the verification tiers differ):
     human/LLM judgment that the framing is not manipulative). It records intent and routes
     to a judgment-based review rather than a green/red test.
 
+  At verify time these tiers are routed differently (ADR-550 D4):
+  - A **test**-tier prohibition is enforced + hard-gates via the deterministic
+    `check prohibition-enforcement` sub-command (#1259 + #1279, ADR-550 D5d): it locates the wired
+    mechanical check (a `node --test` negative test OR a lint/AST rule run as
+    `eslint --format json` and filtered by `ruleId`), **machine-proves it is fail-first** against a
+    known violation, runs it for a genuine **non-vacuous** pass, and emits the
+    `dispositionForProhibition()` verdict. A passing, fail-first-proven wired check disposes **green**
+    (satisfiable → can reach `passed`); a missing, un-provable, or genuinely-non-passing check
+    **hard-gates** (flagged, never green → `gaps_found`) in BOTH interactive and autonomous modes —
+    never a silent pass.
+
+    **Machine-proven fail-first (#1279).** `failFirst` is now **machine-proven, not caller-attested**:
+    before a clean pass greens, the producer independently runs the wired check against a KNOWN
+    VIOLATION and confirms it goes RED (any other outcome — passes-on-violation, can't-prove, throws,
+    times out, no violation source — hard-gates). The violation is sourced from a descriptor field:
+    - **`violationFixture`** — an author-supplied path to a KNOWN-BAD subject. For `lint-rule`: a file
+      whose content violates `rule`; the prover lints it and requires the rule id to appear in the
+      JSON report (the rule must have teeth). For `node-test`: a subject the negative test exercises,
+      expected to drive it RED.
+    - **`GSD_PROHIB_SUBJECT`** — the node-test subject-injection convention: the producer spawns the
+      negative test with `GSD_PROHIB_SUBJECT=<violationFixture>` in the child env; the test reads that
+      env var to locate its subject-under-test and is expected to go red against the violating subject.
+    - **lint-fixture authoring gotcha** — the violating fixture must actually trigger the rule. For the
+      `local/no-source-grep` dogfood anchor specifically, use the `path.join('lib','foo.cjs')` form
+      (a standalone quoted dir token); a single string literal like `'src/x.cjs'` does NOT trigger the
+      rule, so a mis-authored fixture makes the prover report "not proven" and hard-gate a legitimately
+      wired check. (`no-source-grep` has no filename guard — any `.cjs` with the pattern fires.)
+
+    > **PROPOSED, renamable conventions (zero live consumers).** Both `GSD_PROHIB_SUBJECT` and
+    > `violationFixture` are net-new surface with **no live in-tree consumer yet** — there is no
+    > in-tree `node --test` prohibition; node-test fail-first proof is exercised only by SYNTHETIC
+    > temp fixtures in the tests, and the real dogfood remains the LINT-rule `local/no-source-grep`.
+    > They are therefore **open to maintainer adjustment (rename, or replacing the env var with an
+    > argv) at PR review with zero migration cost.** See the ADR-550 2026-06-15 addendum (#1279).
+  - A **judgment**-tier prohibition routes to a never-silent / never-hard-halt soft gate
+    (autonomous emits an `unverified-prohibition — human review recommended` flag).
+
 Splitting these axes keeps the lifecycle enum free of a verification fact and lets the
 prohibition adapter declare `test | judgment` without forking the shared lifecycle enum that
 the edge-probe's `explicit | backstop` also uses.
 
+## Optional wired-check descriptor (deterministic locate + machine-proof, #1278 + #1346)
+
+A `resolved`/`test`-tier prohibition MAY carry an **optional `check` descriptor** that names
+the wired mechanical check, so verify-phase locates it deterministically instead of inventing
+`{kind, target, rule}` each run. The descriptor is captured at spec-phase (soft / optional —
+the author wires it when the negative test or lint rule already exists) and is represented as
+**four flat scalar keys** on the `must_haves.prohibitions` item — never a nested `check: {}`
+object:
+
+- `check_kind` — `node-test` | `lint-rule` (which producer mechanism runs the check).
+- `check_target` — the test file (`node-test`) or the file the rule runs against (`lint-rule`).
+- `check_rule` — the `ruleId` to filter on, **lint-rule only** (absent for `node-test`).
+- `check_violation_fixture` — path to a KNOWN-BAD subject the #1279 prover runs the check against to
+  machine-prove fail-first (rides BOTH kinds; for `node-test` it is injected via `GSD_PROHIB_SUBJECT`).
+
+The flat-scalar shape is load-bearing: the shared `parseMustHavesBlock` is a flat parser and a
+nested object would flatten/mangle the round-trip (ADR-550 2026-06-15 addendum; #644 "no parser
+rewrite" precedent). `projectProhibitions` emits these keys **only for a well-formed descriptor**
+(valid `check_kind` + non-empty `check_target`; `check_rule` only on the lint-rule path;
+`check_violation_fixture` only when non-empty), and verify-phase reads them back via
+`descriptorFromProjection` into the `CheckDescriptor` handed to `check prohibition-enforcement`. This
+closes **both** the locate (#1278) and the machine-proof-fixture (#1346) halves with **zero manual
+descriptor authoring**: a prohibition authored with all four scalars greens end-to-end through the
+projection alone.
+
+**Fail-closed + backward-compat.** A partial descriptor (`lint-rule` missing `check_rule`), an
+unknown `check_kind`, an **absent** descriptor, OR a descriptor with **no `check_violation_fixture`**
+falls through to the producer's fail-closed paths (`located: false`, or located-but-unprovable) —
+never a silent green. A prohibition with no descriptor parses and disposes byte-identically to today.
+`failFirst` is **not** sourced from the descriptor and is **demoted** (machine-proven fail-first
+DELIVERED in #1279 — no path greens on attestation alone, FF-08); the `dispositionForProhibition`
+policy is unchanged. Residual (tracked **#1346**): the node-test proof confirms the fixture exists and
+the check goes RED, but cannot generically prove the red was *caused by* the subject's content.
+
 ## Output schema
 
 The probe emits, per kept prohibition, an item of the form:
 
 ```
-{ requirement_id, category, status, verification, resolution, reason, statement }
+{ requirement_id, category, status, verification, resolution, reason, statement,
+  check_kind?, check_target?, check_rule? }
 ```
 
 where `statement` is the must-NOT sentence and `category` is the values/safety/ethics class
-(`values`, `fairness`, `privacy`, `transparency`, `safety`, …), plus a coverage summary:
+(`values`, `fairness`, `privacy`, `transparency`, `safety`, …). The optional **flat-scalar
+`check_*` descriptor** (#1278) is present only on a resolved `test`-tier prohibition carrying a
+wired check: `check_kind` (`node-test` | `lint-rule`), `check_target`, and `check_rule` (lint-rule
+only). `projectProhibitions` emits these into `must_haves.prohibitions` and `descriptorFromProjection`
+reads them back into a `{ kind, target, rule? }` `CheckDescriptor`; they are flat scalars (never a
+nested `check:{}` object) so they round-trip through the unchanged `parseMustHavesBlock`. Plus a
+coverage summary:
 
 ```
 coverage: { applicable, resolved, unresolved, byVerification: { test, judgment } }

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

@@ -6,9 +6,13 @@ block — do not inline a copy elsewhere. History of coordinated edits: #2924, #
 
 **Contract for orchestrators:** before dispatch, capture `EXPECTED_BASE=$(git rev-parse HEAD)`,
 then embed the block below into the sub-agent prompt verbatim, substituting `{EXPECTED_BASE}`
-with that captured SHA. The sub-agent only *verifies* and fails closed; the orchestrator
-(the worktree lifecycle owner) performs any base recovery — the sub-agent never rewrites a
-worktree it did not create (#48).
+with that captured SHA. Orchestrators that intentionally create a docs-only pre-dispatch
+plan commit may also substitute `{EXPECTED_BASE_ALTERNATE}` with that commit's immediate
+parent so runtimes that fork from either side of the docs-only commit pass the same
+fail-closed guard (#1265). Otherwise substitute `{EXPECTED_BASE_ALTERNATE}` with an empty
+string. The sub-agent only *verifies* and fails closed; the orchestrator (the worktree
+lifecycle owner) performs any base recovery — the sub-agent never rewrites a worktree it
+did not create (#48).
 
 <worktree_branch_check>
 FIRST ACTION: HEAD assertion MUST run before anything else, and this block is
@@ -30,8 +34,10 @@ if ! echo "$ACTUAL_BRANCH" | grep -Eq '^worktree-agent-[A-Za-z0-9._/-]+$'; then
   echo "FATAL: worktree HEAD '$ACTUAL_BRANCH' is not in the worktree-agent-* namespace; refusing to commit (#2924)." >&2
   exit 42
 fi
-if [ "$(git rev-parse HEAD)" != "{EXPECTED_BASE}" ]; then
-  echo "FATAL: worktree base mismatch — HEAD is $(git rev-parse HEAD), expected {EXPECTED_BASE}. Orchestrator owns recovery; sub-agent refuses to rewrite the worktree (#48)." >&2
+ACTUAL_BASE=$(git rev-parse HEAD)
+EXPECTED_BASE_ALTERNATE="{EXPECTED_BASE_ALTERNATE}"
+if [ "$ACTUAL_BASE" != "{EXPECTED_BASE}" ] && { [ -z "$EXPECTED_BASE_ALTERNATE" ] || [ "$ACTUAL_BASE" != "$EXPECTED_BASE_ALTERNATE" ]; }; then
+  echo "FATAL: worktree base mismatch — HEAD is $ACTUAL_BASE, expected {EXPECTED_BASE}${EXPECTED_BASE_ALTERNATE:+ or $EXPECTED_BASE_ALTERNATE}. Orchestrator owns recovery; sub-agent refuses to rewrite the worktree (#48)." >&2
   exit 42
 fi
 ```

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

@@ -12,6 +12,12 @@ phase: XX-name
 verified: YYYY-MM-DDTHH:MM:SSZ
 status: passed | gaps_found | human_needed
 score: N/M must-haves verified
+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"
+    test: "What to trigger"
+    expected: "What state must hold afterward"
+    why_human: "Why presence checks can't see it"
 ---
 
 # Phase {X}: {Name} Verification Report
@@ -28,9 +34,10 @@ score: N/M must-haves verified
 |---|-------|--------|----------|
 | 1 | {truth from must_haves} | ✓ VERIFIED | {what confirmed it} |
 | 2 | {truth from must_haves} | ✗ FAILED | {what's wrong} |
-| 3 | {truth from must_haves} | ? UNCERTAIN | {why can't verify} |
+| 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} |
 
-**Score:** {N}/{M} truths verified
+**Score:** {N}/{M} truths verified ({P} present, behavior-unverified)
 
 ### Required Artifacts
 
@@ -161,11 +168,17 @@ None — all verifiable items checked programmatically.
 
 ## Guidelines
 
-**Status values:**
+**Status values (overall, frontmatter `status:`):**
 - `passed` — All must-haves verified, no blockers
 - `gaps_found` — One or more critical gaps found
 - `human_needed` — Automated checks pass but human verification required
 
+**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.
+- `✗ FAILED` — artifact missing, stub, or unwired
+- `? UNCERTAIN` — can't verify programmatically
+
 **Evidence types:**
 - For EXISTS: "File at path, exports X"
 - For SUBSTANTIVE: "N lines, has patterns X, Y, Z"

package/gsd-core/workflows/docs-update.md

@@ -457,27 +457,23 @@ Continue to collect_wave_1.
 <step name="collect_wave_1">
 **Read the work manifest first:** `Read .planning/tmp/docs-work-manifest.json` — update `status` to `"completed"` or `"failed"` for each Wave 1 item after collection. Write the updated manifest back to disk.
 
-Wait for all 3 Wave 1 agents to complete using the TaskOutput tool.
+Wait for all 3 Wave 1 background agents to finish, then read each agent's output file to collect confirmations.
 
-Call TaskOutput for all 3 agents in parallel (single message with 3 TaskOutput calls):
+Each `Agent(...)` call above with `run_in_background=true` returns an `async_launched` result that carries an `outputFile` path (and `canReadOutputFile: true`). Each agent's completion arrives as a message in this conversation when it finishes — do NOT issue a separate blocking call to wait. Once all 3 agents have reported completion, read their output files in parallel (single message with 3 Read calls):
 
 ```
-TaskOutput tool:
-  task_id: "{task_id from README agent result}"
-  block: true
-  timeout: 300000
+Read tool:
+  file_path: "{outputFile from README agent result}"
 
-TaskOutput tool:
-  task_id: "{task_id from ARCHITECTURE agent result}"
-  block: true
-  timeout: 300000
+Read tool:
+  file_path: "{outputFile from ARCHITECTURE agent result}"
 
-TaskOutput tool:
-  task_id: "{task_id from CONFIGURATION agent result}"
-  block: true
-  timeout: 300000
+Read tool:
+  file_path: "{outputFile from CONFIGURATION agent result}"
 ```
 
+> Allow up to 5 minutes (300000 ms) for the slowest agent to finish before treating it as failed.
+
 **Expected confirmation format from each agent:**
 ```
 ## Doc Generation Complete
@@ -676,29 +672,25 @@ Continue to collect_wave_2.
 <step name="collect_wave_2">
 **Read the work manifest first:** `Read .planning/tmp/docs-work-manifest.json` — update `status` to `"completed"` or `"failed"` for each Wave 2 item after collection. Write the updated manifest back to disk.
 
-Wait for all Wave 2 agents to complete using the TaskOutput tool.
+Wait for all Wave 2 background agents to finish, then read each agent's output file to collect confirmations.
 
-Call TaskOutput for all Wave 2 agents in parallel (single message with N TaskOutput calls — one per spawned Wave 2 agent):
+Each `Agent(...)` call above with `run_in_background=true` returns an `async_launched` result that carries an `outputFile` path (and `canReadOutputFile: true`). Each agent's completion arrives as a message in this conversation when it finishes — do NOT issue a separate blocking call to wait. Once all Wave 2 agents have reported completion, read their output files in parallel (single message with N Read calls — one per spawned Wave 2 agent):
 
 ```
-TaskOutput tool:
-  task_id: "{task_id from GETTING-STARTED agent result}"
-  block: true
-  timeout: 300000
+Read tool:
+  file_path: "{outputFile from GETTING-STARTED agent result}"
 
-TaskOutput tool:
-  task_id: "{task_id from DEVELOPMENT agent result}"
-  block: true
-  timeout: 300000
+Read tool:
+  file_path: "{outputFile from DEVELOPMENT agent result}"
 
-TaskOutput tool:
-  task_id: "{task_id from TESTING agent result}"
-  block: true
-  timeout: 300000
+Read tool:
+  file_path: "{outputFile from TESTING agent result}"
 
-# Add one TaskOutput call per conditional agent spawned (API, DEPLOYMENT, CONTRIBUTING)
+# Add one Read call per conditional agent spawned (API, DEPLOYMENT, CONTRIBUTING)
 ```
 
+> Allow up to 5 minutes (300000 ms) for the slowest agent to finish before treating it as failed.
+
 **After collection, verify all Wave 2 files exist on disk** using the `resolved_path` from each manifest entry:
 ```bash
 ls -la {resolved_path for each wave 2 item} 2>/dev/null
@@ -752,9 +744,9 @@ Write {package_dir}/README.md directly. Return confirmation only — do not retu
 )
 ```
 
-> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling all per-package Agent() calls above with `run_in_background=true`, do NOT generate any package READMEs independently while the subagents are active. Wait for all agents to complete via TaskOutput before proceeding. This prevents duplicate work and wasted context.
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling all per-package Agent() calls above with `run_in_background=true`, do NOT generate any package READMEs independently while the subagents are active. Wait for all agents to complete before proceeding. This prevents duplicate work and wasted context.
 
-Collect confirmations via TaskOutput for all package agents. Note failures in the final report.
+Collect confirmations by reading each package agent's `outputFile` once it reports completion — each `run_in_background=true` Agent call returns an `async_launched` result carrying an `outputFile` path (with `canReadOutputFile: true`). Note failures in the final report.
 
 **Fallback when Task tool is unavailable:** Generate per-package READMEs sequentially inline after the `sequential_generation` step. For each package directory with a `package.json`, construct the equivalent `doc_assignment` block and generate the README following gsd-doc-writer instructions.
 

package/gsd-core/workflows/execute-phase/steps/worktree-recovery-policy.md

@@ -0,0 +1,9 @@
+# Worktree Recovery Policy
+
+## ORCHESTRATOR FAIL-CLOSED RULE (#48)
+
+> **ORCHESTRATOR FAIL-CLOSED RULE (#48):** `worktree_branch_check` is verify-only — an executor that hits a base/HEAD-namespace mismatch prints `FATAL:` and exits **42** instead of self-recovering. If any executor result reports a `FATAL:`/`exit 42` (or its commits never appear because it halted at the check), mark that plan **blocked**: do NOT merge or clean up its worktree (preserve it for inspection), do NOT count the wave as successful, and surface the mismatch with recovery guidance to the user. The orchestrator — the worktree lifecycle owner — performs any base correction (e.g. recreate the worktree on `{EXPECTED_BASE}`); the sub-agent never does. Never proceed past a halted executor on the assumption it succeeded.
+
+## ISOLATED-RUN RECOVERY — FAIL SAFE (#1292)
+
+> **ISOLATED-RUN RECOVERY — FAIL SAFE (#1292):** When an isolated (worktree) run is *rejected* — the user declines to merge it, the orchestrator surfaces recovery guidance for a blocked/halted plan, or the run over-reached the requested scope — the worktree-isolation contract MUST hold through recovery. Do **NOT** propose continuing on `main`/the primary checkout as the default or recommended recovery path. Default to a **safe halt** and offer: (a) re-attempt in a **fresh, narrowly-scoped worktree**, or (b) inspect or discard the rejected worktree without merging. Any path that edits the primary checkout requires an **explicit, clearly-labeled confirmation** from the user first — editing `main` directly is never the proposed or default option for a run the user configured to be isolated.

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

@@ -635,6 +635,7 @@ increases monotonically across waves. `{status}` is `complete` (success),
        this commit — the orchestrator force-removes the worktree after you return, and
        any uncommitted SUMMARY.md will be permanently lost (#2070).
        REQUIRED ORDER: Write SUMMARY.md → commit → only then any narration. No text between Write and commit (truncation risk; #2070 rescue is not primary defense).
+
        </parallel_execution>
 
        <execution_context>
@@ -682,9 +683,9 @@ increases monotonically across waves. `{status}` is `complete` (success),
    )
    ```
 
-   Immediately after each worktree `Agent()` spawn returns metadata, atomically append `{agent_id, worktree_path, branch, expected_base}` to `WAVE_WORKTREE_MANIFEST`. If any field is missing, stop and ask for recovery instead of scanning all agent worktrees.
+   After each `Agent()` returns, parse executor-returned worktree metadata (`<worktree_metadata>`) before harness metadata, then atomically append `{agent_id, worktree_path, branch, expected_base}` to `WAVE_WORKTREE_MANIFEST`. Missing: stop and ask for recovery instead of scanning worktrees.
 
-   > **ORCHESTRATOR FAIL-CLOSED RULE (#48):** `worktree_branch_check` is verify-only — an executor that hits a base/HEAD-namespace mismatch prints `FATAL:` and exits **42** instead of self-recovering. If any executor result reports a `FATAL:`/`exit 42` (or its commits never appear because it halted at the check), mark that plan **blocked**: do NOT merge or clean up its worktree (preserve it for inspection), do NOT count the wave as successful, and surface the mismatch with recovery guidance to the user. The orchestrator — the worktree lifecycle owner — performs any base correction (e.g. recreate the worktree on `{EXPECTED_BASE}`); the sub-agent never does. Never proceed past a halted executor on the assumption it succeeded.
+   > **Worktree recovery policy (#48 + #1292):** See `execute-phase/steps/worktree-recovery-policy.md` — FAIL-CLOSED rule for base/HEAD-namespace mismatches AND isolated-run fail-safe recovery.
 
    > **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above to spawn executor agent(s), stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
 
@@ -753,6 +754,8 @@ increases monotonically across waves. `{status}` is `complete` (success),
    ask for one recovery path: `continue waiting`, `kill and retry`, or
    `kill and switch to inline execution`.
 
+   If the stalled executor ran in an isolated worktree, `kill and switch to inline execution` edits the primary checkout — see worktree recovery policy (`execute-phase/steps/worktree-recovery-policy.md`). Prefer `kill and retry` in a fresh worktree; inline execution requires explicit confirmation, never the default.
+
    **This fallback applies automatically to all runtimes.** Claude Code's Agent() normally
    returns synchronously, but the fallback ensures resilience if it doesn't.
 
@@ -855,6 +858,8 @@ increases monotonically across waves. `{status}` is `complete` (success),
 
    **If no worktrees found at runtime:** Skip silently — agents may have been spawned without worktree isolation, or the orchestrator already cleaned them up.
 
+   If the user declines to merge a worktree or a worktree over-reached scope, apply the worktree recovery policy (`execute-phase/steps/worktree-recovery-policy.md`) — never default to editing `main`.
+
 5.6. **Post-merge build & test gate:**
 
    After merging all worktrees in a wave (parallel mode), or after the last plan completes

package/gsd-core/workflows/map-codebase.md

@@ -255,21 +255,19 @@ Continue to collect_confirmations.
 </step>
 
 <step name="collect_confirmations">
-Wait for all 4 agents to complete using TaskOutput tool.
+Wait for all 4 background agents to finish, then read each agent's output file to collect confirmations.
 
-**For each agent task_id returned by the Agent tool calls above:**
+Each `Agent(...)` call above with `run_in_background=true` returns an `async_launched` result that carries an `outputFile` path (and `canReadOutputFile: true`). The 4 agents run concurrently and each one's completion arrives as a message in this conversation when it finishes — do NOT issue a separate blocking call to wait for them.
+
+**Once all 4 agents have reported completion, read each agent's output file (single message with 4 Read calls):**
 ```
-TaskOutput tool:
-  task_id: "{task_id from Agent result}"
-  block: true
-  timeout: {subagent_timeout from init context, default 300000}
+Read tool:
+  file_path: "{outputFile from that agent's async_launched result}"
 ```
 
-> The timeout is configurable via `workflow.subagent_timeout` in `.planning/config.json` (milliseconds). Default: 300000 (5 minutes). Increase for large codebases or slower models.
-
-Call TaskOutput for all 4 agents in parallel (single message with 4 TaskOutput calls).
+> Allow up to `workflow.subagent_timeout` for the slowest agent to finish before treating it as failed. The timeout is configurable via `workflow.subagent_timeout` in `.planning/config.json` (milliseconds). Default: 300000 (5 minutes). Increase for large codebases or slower models.
 
-Once all TaskOutput calls return, read each agent's output file to collect confirmations.
+Each output file contains that agent's completion confirmation. Parse the confirmation marker (see below) from the file contents.
 
 **Expected confirmation format from each agent:**
 ```

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

@@ -499,6 +499,12 @@ Display banner:
 
 ### Spawn gsd-phase-researcher
 
+```bash
+if gsd_run query teams-status --active >/dev/null 2>&1; then
+  echo "⚠️  CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS detected. GSD's multi-agent orchestration is not validated under claude-code agent-teams and may stall (a subagent's completion can fail to route to the orchestrator). Recommend disabling agent-teams for GSD workflows. See https://github.com/open-gsd/gsd-core/issues/1355" >&2
+fi
+```
+
 ```bash
 PHASE_DESC=$(gsd_run query roadmap.get-phase "${PHASE}" --pick section)
 if [ -z "${PLAN_PRE_HOOKS_JSON:-}" ]; then

package/gsd-core/workflows/quick.md

@@ -632,7 +632,10 @@ When `USE_WORKTREES !== "false"`, commit PLAN.md to the current branch **before*
 Skip this step entirely if `USE_WORKTREES === "false"` (non-worktree mode: PLAN.md is committed in Step 8 as usual).
 
 ```bash
+QUICK_PLAN_PARENT=""
+QUICK_PLAN_COMMIT=""
 if [ "${USE_WORKTREES}" != "false" ]; then
+  QUICK_PLAN_PARENT=$(git rev-parse HEAD)
   COMMIT_DOCS=$(gsd_run query config-get commit_docs 2>/dev/null || echo "true")
   if [ "$COMMIT_DOCS" != "false" ]; then
     git add "${QUICK_DIR}/${quick_id}-PLAN.md"
@@ -650,8 +653,12 @@ if [ "${USE_WORKTREES}" != "false" ]; then
         git commit -m "docs(${quick_id}): pre-dispatch plan for ${DESCRIPTION}" -- "${QUICK_DIR}/${quick_id}-PLAN.md" \
           || { echo "ERROR: pre-dispatch PLAN.md commit failed — likely a pre-commit hook failure. Fix the hook output above (or set workflow.worktree_skip_hooks=true to bypass) and re-run." >&2; exit 1; }
       fi
+      QUICK_PLAN_COMMIT=$(git rev-parse HEAD)
     fi
   fi
+  if [ -z "$QUICK_PLAN_COMMIT" ]; then
+    QUICK_PLAN_COMMIT=$(git rev-parse HEAD)
+  fi
 fi
 ```
 
@@ -678,8 +685,22 @@ Execute quick task ${quick_id}.
 
 ${USE_WORKTREES !== "false" ? `
 <worktree_branch_check>
-ORCHESTRATOR build-time embed (NOT a sub-agent runtime step): before this dispatch, read \`gsd-core/references/worktree-branch-check.md\`, substitute \`{EXPECTED_BASE}\` with the base SHA captured above (${EXPECTED_BASE}), and replace this note with that fragment's \`<worktree_branch_check>\` block so the dispatched prompt carries the runnable guard verbatim — do not pass this instruction through in its place.
+ORCHESTRATOR build-time embed (NOT a sub-agent runtime step): before this dispatch, read \`gsd-core/references/worktree-branch-check.md\`, substitute \`{EXPECTED_BASE}\` with the base SHA captured above (${EXPECTED_BASE}), substitute \`{EXPECTED_BASE_ALTERNATE}\` with \`${QUICK_PLAN_PARENT}\` when it differs from \`${EXPECTED_BASE}\` (otherwise empty), and replace this note with that fragment's \`<worktree_branch_check>\` block so the dispatched prompt carries the runnable guard verbatim — do not pass this instruction through in its place.
 </worktree_branch_check>
+
+FIRST ACTION after the worktree branch check: ensure the quick PLAN.md exists at a worktree-rooted relative path before any Read/Edit/Write path can be primed. If \`${QUICK_DIR}/${quick_id}-PLAN.md\` is absent, materialize it from the shared git object store:
+
+\`\`\`bash
+QUICK_PLAN_COMMIT="${QUICK_PLAN_COMMIT}"
+QUICK_PLAN_PATH="${QUICK_DIR}/${quick_id}-PLAN.md"
+if [ ! -f "$QUICK_PLAN_PATH" ]; then
+  mkdir -p "$(dirname "$QUICK_PLAN_PATH")"
+  git show "${QUICK_PLAN_COMMIT}:${QUICK_PLAN_PATH}" > "$QUICK_PLAN_PATH" || {
+    echo "FATAL: unable to materialize quick plan from ${QUICK_PLAN_COMMIT}:${QUICK_PLAN_PATH}; refusing to continue." >&2
+    exit 42
+  }
+fi
+\`\`\`
 ` : ''}
 
 <files_to_read>
@@ -743,7 +764,7 @@ SUMMARY.md and stop — the user must rerun with worktrees disabled.
 
 > **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
 
-If the executor ran with `isolation="worktree"`, append its returned `{agent_id, worktree_path, branch, expected_base}` metadata to `QUICK_WORKTREE_MANIFEST` before cleanup. If any field is unavailable, stop and ask for recovery; do not discover global worktrees.
+If the executor ran with `isolation="worktree"`, append its returned `{agent_id, worktree_path, branch, expected_base, allowed_bases}` metadata to `QUICK_WORKTREE_MANIFEST` before cleanup. Set `expected_base` to `${EXPECTED_BASE}` and `allowed_bases` to `["${EXPECTED_BASE}", "${QUICK_PLAN_PARENT}"]` with duplicates removed. If any required field is unavailable, stop and ask for recovery; do not discover global worktrees.
 
 After executor returns:
 1. **Worktree cleanup:** If the executor ran with `isolation="worktree"`, merge the worktree branch back and clean up:
@@ -761,6 +782,9 @@ After executor returns:
    gsd_run query worktree.cleanup-wave --manifest "$QUICK_WORKTREE_MANIFEST" || exit 1
    ```
    If `workflow.use_worktrees` is `false`, skip this step.
+
+   > **ISOLATED-RUN RECOVERY — FAIL SAFE (#1292):** When an isolated (worktree) run is *rejected* — the user declines to merge it, the orchestrator surfaces recovery guidance for a blocked/halted plan, or the run over-reached the requested scope — the worktree-isolation contract MUST hold through recovery. Do **NOT** propose continuing on `main`/the primary checkout as the default or recommended recovery path. Default to a **safe halt** and offer: (a) re-attempt in a **fresh, narrowly-scoped worktree**, or (b) inspect or discard the rejected worktree without merging. Any path that edits the primary checkout requires an **explicit, clearly-labeled confirmation** from the user first — editing `main` directly is never the proposed or default option for a run the user configured to be isolated.
+
 2. Verify summary exists at `${QUICK_DIR}/${quick_id}-SUMMARY.md`
 3. Extract commit hash from executor output
 4. Report completion status

package/gsd-core/workflows/settings-advanced.md

@@ -50,7 +50,7 @@ Planning Tuning:
 - `workflow.plan_bounce` (default: `false`)
 - `workflow.plan_bounce_passes` (default: `2`)
 - `workflow.plan_bounce_script` (default: `null`)
-- `workflow.subagent_timeout` (default: `600`)
+- `workflow.subagent_timeout` (default: `300000`)
 - `workflow.inline_plan_threshold` (default: `3`)
 
 Execution Tuning:
@@ -155,12 +155,12 @@ AskUserQuestion([
     ]
   },
   {
-    question: "Subagent timeout (seconds)? (current: <value or 600>)",
+    question: "Subagent timeout (milliseconds)? (current: <value or 300000>)",
     header: "Subagent Timeout",
     multiSelect: false,
     options: [
       { label: "Keep current", description: "Leave timeout unchanged." },
-      { label: "Enter seconds", description: "Integer number of seconds. Non-numeric rejected. Default: 600" }
+      { label: "Enter milliseconds", description: "Integer number of milliseconds. Non-numeric rejected. Default: 300000 (5 minutes)." }
     ]
   },
   {
@@ -498,7 +498,7 @@ keys and sibling sub-objects.
 ```bash
 # Example — only write keys the user changed. "Keep current" selections are skipped.
 gsd_run query config-set workflow.plan_bounce_passes 5
-gsd_run query config-set workflow.subagent_timeout 900
+gsd_run query config-set workflow.subagent_timeout 300000
 gsd_run query config-set git.base_branch main
 gsd_run query config-set context_window 1000000
 # Runtime model tier examples:
@@ -751,7 +751,7 @@ Display:
 | workflow.plan_bounce                       | {on/off} |
 | workflow.plan_bounce_passes                | {n} |
 | workflow.plan_bounce_script                | {path/null} |
-| workflow.subagent_timeout                  | {seconds} |
+| workflow.subagent_timeout                  | {milliseconds} |
 | workflow.inline_plan_threshold             | {n} |
 | workflow.node_repair                       | {on/off} |
 | workflow.node_repair_budget                | {n} |

package/gsd-core/workflows/settings-integrations.md

@@ -173,20 +173,20 @@ AskUserQuestion([
     multiSelect: false,
     options: [
       { label: "Claude", description: "review.models.claude — defaults to session model when unset" },
-      { label: "Codex", description: "review.models.codex — e.g. 'codex exec --model gpt-5'" },
-      { label: "Gemini", description: "review.models.gemini — e.g. 'gemini -m gemini-2.5-pro'" },
-      { label: "OpenCode", description: "review.models.opencode — e.g. 'opencode run --model claude-sonnet-4'" }
+      { label: "Codex", description: "review.models.codex — bare model id injected into --model, e.g. 'gpt-5'" },
+      { label: "Gemini", description: "review.models.gemini — bare model id injected into -m, e.g. 'gemini-2.5-pro'" },
+      { label: "OpenCode", description: "review.models.opencode — bare model id injected into --model, e.g. 'claude-sonnet-4'" }
     ]
   }
 ])
 ```
 
 For the selected CLI, show the current value (or `(unset)`) and offer
-Leave / Replace / Clear, followed by a text-input prompt for the new command
+Leave / Replace / Clear, followed by a text-input prompt for the model id
 string. Write via:
 
 ```bash
-gsd_run query config-set review.models.<cli> "<command string>"
+gsd_run query config-set review.models.<cli> "<model id>"
 ```
 
 After each update, return to the "Review model CLI mapping — what next?" question.

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

@@ -356,6 +356,26 @@ For each Requirement gathered so far, run the two-stage recall→precision pass:
      Criteria AND mark the prohibition `resolved` with a verification tier: `test` (a
      mechanical negative test/lint/assertion exists) or `judgment` (real but not mechanically
      checkable — routes to judgment review).
+     - **Capture the wired-check descriptor on `test`-tier (#1278, SOFT).** When a prohibition is
+       resolved `verification: test`, ALSO capture the descriptor of the wired check so
+       `verify-phase` can LOCATE it deterministically (no verifier invention at verify time).
+       Capture the flat scalars — persisted into SPEC and projected onto the
+       `must_haves.prohibitions` item by `projectProhibitions`:
+       - `check_kind` — `node-test` | `lint-rule`.
+       - `check_target` — the negative-test file path (for `node-test`), or the path to lint
+         (for `lint-rule`).
+       - `check_rule` — the eslint rule id (e.g. `local/no-source-grep`); `lint-rule` only.
+       - `check_violation_fixture` (#1346) — path to a KNOWN-BAD subject the wired check is run
+         against to **machine-prove fail-first**; rides BOTH kinds. Capture it to let the item green
+         end-to-end with zero hand-authoring at verify time; for `node-test` the negative test should
+         read its subject from the `GSD_PROHIB_SUBJECT` env var so the prover can inject this fixture.
+       This is a **SOFT capture (CHK-04): a `test`-tier prohibition WITHOUT a descriptor is still
+       allowed** — if the author cannot yet name the wired check, leave the descriptor empty and
+       proceed. It is NOT a hard authoring block; the item simply stays fail-closed/flagged
+       downstream (an absent/partial descriptor — or one with no `check_violation_fixture` —
+       → `descriptorFromProjection` null/under-specified/fixture-less → producer fail-closed
+       locate-or-unprovable, never green). Do NOT capture `failFirst` here — it is a
+       verify-time caller attestation, not a spec-authored field (#1279).
    - **Dismiss (reason)** → mark `dismissed` with a REQUIRED non-empty reason (PROB-05). The
      reason string is the audit trail; silence is not a valid dismissal.
    - **Defer** → leave `unresolved`.
@@ -374,7 +394,11 @@ For each Requirement gathered so far, run the two-stage recall→precision pass:
 **`--auto` mode:** auto-`resolved` where a defensible negative acceptance criterion can be
 written (test or judgment tier); otherwise leave `unresolved`. **`--auto` NEVER auto-dismisses
 a prohibition** — a wrong dismissal is the exact silent failure this probe eliminates (PROB-06,
-the load-bearing safety property). Log: `[auto] prohibitions: R resolved, U unresolved`.
+the load-bearing safety property). On a `test`-tier auto-resolution, capture the `check_kind` /
+`check_target` / `check_rule` / `check_violation_fixture` descriptor **only when a wired check is unambiguous**; otherwise
+leave it empty — `--auto` NEVER fabricates a check path or fixture (a wrong locate is re-validated and
+fails closed at the producer, but a fabricated path is still noise to avoid). Log:
+`[auto] prohibitions: R resolved, U unresolved`.
 
 **Text mode (PROB-09):** per Step 5's text-mode rule, replace the AskUserQuestion menus above
 with plain-text numbered lists — there is NO hard AskUserQuestion dependency, so the probe
@@ -382,7 +406,11 @@ runs identically for non-Claude / text-mode hosts.
 
 Populate the `## Prohibitions` section of SPEC.md from the resolved prohibitions (each
 `resolved`/`test` row is a checkable negative acceptance criterion; `resolved`/`judgment`
-rows route to judgment review; `⚠ UNRESOLVED` rows are flagged as assumptions).
+rows route to judgment review; `⚠ UNRESOLVED` rows are flagged as assumptions). A
+`resolved`/`test` row ALSO carries its captured `check_kind` / `check_target` / `check_rule` /
+`check_violation_fixture` descriptor when present (so the projection feeds `verify-phase`'s deterministic locate + machine-proof, #1278 + #1346);
+a `test` row with no captured descriptor is still valid — it stays fail-closed/flagged
+downstream rather than blocking authoring.
 
 ## Step 6: Generate SPEC.md