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

package/gsd-core/bin/lib/teams-status.cjs

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Teams Status Module — issue #1355
+ *
+ * Read-only detector for claude-code's experimental agent-teams feature.
+ * Exposes a PURE core function (env injected, no process.env/disk inside) and
+ * a thin CLI wrapper that reuses resolveRuntime from runtime-slash.cjs.
+ *
+ * Exports:
+ *   resolveTeamsStatus({ runtime, env }) → TeamsStatus
+ *   cmdTeamsStatus(cwd, opts)  — I/O entry point
+ *
+ * resolveTeamsStatus is PURE: env and runtime are injected, no process.env or
+ * disk access inside the function. Pass process.env explicitly at call sites.
+ *
+ * cmdTeamsStatus is the I/O handler. It reads process.env, resolves the
+ * runtime via resolveRuntime(cwd) from runtime-slash.cjs (GSD_RUNTIME →
+ * config.runtime → 'claude' precedence), then:
+ *   - default: prints JSON.stringify(status) to stdout via io.output, exits 0.
+ *   - --active: prints nothing, exits 0 if status.active, exit 1 otherwise.
+ *
+ * Strictly read-only — no config writes, no disk mutation.
+ *
+ * Dependencies:
+ *   - ./io.cjs             (output)
+ *   - ./runtime-slash.cjs  (resolveRuntime)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTeamsStatus = resolveTeamsStatus;
+exports.cmdTeamsStatus = cmdTeamsStatus;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const ioMod = require("./io.cjs");
+const { output: coreOutput } = ioMod;
+// ─── Pure core ────────────────────────────────────────────────────────────────
+/**
+ * Resolve the agent-teams status from injected runtime and env.
+ *
+ * Strict truthiness: only '1' and 'true' (case-insensitive, trimmed) are on.
+ * '0', 'false', '', and unset are all off.
+ *
+ * @param opts.runtime  The resolved runtime name (e.g. 'claude', 'codex')
+ * @param opts.env      The environment map to read from (typically process.env)
+ */
+function resolveTeamsStatus(opts) {
+    const raw = (opts.env['CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS'] ?? '').trim().toLowerCase();
+    const envOn = raw === '1' || raw === 'true'; // strict: never '0'/'false'/'' as on
+    const isClaude = opts.runtime === 'claude';
+    const source = !isClaude ? 'off: non-claude' : (envOn ? 'on: env' : 'off: flag absent');
+    return { active: envOn && isClaude, runtime: opts.runtime, env_present: envOn, source };
+}
+// ─── CLI command handler ──────────────────────────────────────────────────────
+/**
+ * Command entry point: resolve runtime via resolveRuntime(cwd), read process.env,
+ * call resolveTeamsStatus, and emit the result.
+ *
+ * @param cwd       Project root directory (used by resolveRuntime for config.json)
+ * @param opts      Command options
+ * @param opts.active  When true: print nothing, exit 0 if active, exit 1 otherwise
+ */
+function cmdTeamsStatus(cwd, opts) {
+    // Resolve runtime via the canonical precedence:
+    //   GSD_RUNTIME → config.runtime → 'claude'
+    // Reuses resolveRuntime from runtime-slash.cjs — no reimplementation.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const runtimeSlash = require('./runtime-slash.cjs');
+    const runtime = runtimeSlash.resolveRuntime(cwd);
+    const status = resolveTeamsStatus({ runtime, env: process.env });
+    if (opts.active) {
+        // --active mode: no output, exit code encodes the boolean
+        process.exit(status.active ? 0 : 1);
+    }
+    // Default: emit JSON to stdout via io.output, exit 0
+    coreOutput(status, false);
+}

package/gsd-core/bin/lib/uat.cjs

@@ -145,6 +145,13 @@ function parseCurrentTest(content) {
         || section.match(/^expected:\s*\|\n([\s\S]+)/m);
     const expectedInlineMatch = section.match(/^expected:\s*(.+)\s*$/m);
     if (!numberMatch || !nameMatch || (!expectedBlockMatch && !expectedInlineMatch)) {
+        if (!numberMatch && !nameMatch && !expectedBlockMatch && !expectedInlineMatch) {
+            const pendingTest = parseFirstPendingTest(content);
+            if (pendingTest) {
+                return pendingTest;
+            }
+            error('Current Test section is non-structured and no pending UAT test remains to resume');
+        }
         error('Current Test section is malformed');
     }
     let expected;
@@ -165,6 +172,55 @@ function parseCurrentTest(content) {
         expected: (0, security_cjs_1.sanitizeForDisplay)(expected),
     };
 }
+function parseFirstPendingTest(content) {
+    const testsMatch = content.match(/##\s*Tests\s*\n([\s\S]*?)(?=\n##\s|$)/i);
+    if (!testsMatch) {
+        return null;
+    }
+    const testsSection = testsMatch[1];
+    const headingPattern = /^###\s*(\d+)\.\s*([^\n]+)\s*$/gm;
+    const headings = [];
+    let headingMatch;
+    while ((headingMatch = headingPattern.exec(testsSection)) !== null) {
+        headings.push({
+            index: headingMatch.index,
+            number: parseInt(headingMatch[1], 10),
+            name: headingMatch[2].trim(),
+        });
+    }
+    for (let i = 0; i < headings.length; i += 1) {
+        const current = headings[i];
+        const next = headings[i + 1];
+        const block = testsSection.slice(current.index, next ? next.index : undefined);
+        if (!/^result:\s*\[?pending\]?\s*$/im.test(block)) {
+            continue;
+        }
+        const expected = parseExpectedFromTestBlock(block);
+        if (!expected) {
+            error(`Pending UAT test ${current.number} is missing an expected field`);
+        }
+        return {
+            complete: false,
+            number: current.number,
+            name: (0, security_cjs_1.sanitizeForDisplay)(current.name),
+            expected: (0, security_cjs_1.sanitizeForDisplay)(expected),
+        };
+    }
+    return null;
+}
+function parseExpectedFromTestBlock(block) {
+    const expectedBlockMatch = block.match(/^expected:\s*\|\n([\s\S]*?)(?=^\w[\w-]*:\s)/m)
+        || block.match(/^expected:\s*\|\n([\s\S]+)/m);
+    if (expectedBlockMatch) {
+        return expectedBlockMatch[1]
+            .split('\n')
+            .map((line) => line.replace(/^ {2}/, ''))
+            .join('\n')
+            .trim();
+    }
+    const expectedInlineMatch = block.match(/^expected:\s*(.+)\s*$/m);
+    return expectedInlineMatch ? expectedInlineMatch[1].trim() : null;
+}
 // ─── buildCheckpoint ──────────────────────────────────────────────────────────
 function buildCheckpoint(currentTest) {
     return [

package/gsd-core/bin/lib/worktree-safety.cjs

@@ -304,11 +304,14 @@ function normalizeCleanupManifestEntry(entry) {
         return null;
     if (!/^worktree-agent-[A-Za-z0-9._/-]+$/.test(branch))
         return null;
+    const rawAllowedBases = Array.isArray(e.allowed_bases) ? e.allowed_bases : [];
+    const allowedBases = Array.from(new Set([expectedBase, ...rawAllowedBases.filter((base) => typeof base === 'string' && base.length > 0)]));
     return {
         agent_id: typeof e.agent_id === 'string' ? e.agent_id : null,
         worktree_path: worktreePath,
         branch,
         expected_base: expectedBase,
+        allowed_bases: allowedBases,
     };
 }
 function normalizeCleanupManifest(manifest) {
@@ -529,7 +532,10 @@ function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
             break;
         }
         const mergeBase = execGit(['merge-base', 'HEAD', entry.branch], { cwd: plan.repoRoot });
-        if (!gitResultOk(mergeBase) || mergeBase.stdout.trim() !== entry.expected_base) {
+        const allowedBases = Array.isArray(entry.allowed_bases) && entry.allowed_bases.length > 0
+            ? entry.allowed_bases
+            : [entry.expected_base];
+        if (!gitResultOk(mergeBase) || !allowedBases.includes(mergeBase.stdout.trim())) {
             result.status = 'blocked';
             result.reason = 'base_mismatch';
             result.stderr = mergeBase?.stderr || '';

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

@@ -112,15 +112,38 @@ lifecycle is identical to the edge-probe, the verification tiers differ):
 
   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, ADR-550 D5d): it locates the wired
+    `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`), requires the caller-attested `failFirst`
-    marker, runs it for a genuine **non-vacuous** pass, and emits the
-    `dispositionForProhibition()` verdict. A passing wired check disposes **green** (satisfiable
-    → can reach `passed`); a missing, non-attested, or genuinely-non-passing check **hard-gates**
-    (flagged, never green → `gaps_found`) in BOTH interactive and autonomous modes — never a
-    silent pass. (`failFirst` is caller-attested, not yet machine-proven against a violation
-    fixture — a tracked follow-up; see ADR-550 D5d.)
+    `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).
 
@@ -128,33 +151,39 @@ Splitting these axes keeps the lifecycle enum free of a verification fact and le
 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, #1278)
+## 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
-**three flat scalar keys** on the `must_haves.prohibitions` item — never a nested `check: {}`
+**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), and
-verify-phase reads them back via `descriptorFromProjection` into the `CheckDescriptor` handed to
-`check prohibition-enforcement`. A wired, passing test then closes the gap with **zero manual
-descriptor authoring**.
+(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`, or an **absent** descriptor on a test-tier prohibition falls through to the
-producer's existing fail-closed locate — never a silent green. A prohibition with no descriptor
-parses and disposes byte-identically to today. `failFirst` is **not** sourced from the
-descriptor — it stays a verify-time caller attestation (machine-proven fail-first is tracked in
-#1279; the `dispositionForProhibition` policy is unchanged).
+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
 

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/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.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,7 +683,7 @@ 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.
 
    > **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.
 

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:

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

@@ -365,11 +365,16 @@ For each Requirement gathered so far, run the two-stage recall→precision pass:
        - `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 → `descriptorFromProjection` null/under-specified
-       → producer fail-closed locate, never green). Do NOT capture `failFirst` here — it is a
+       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.
@@ -390,8 +395,8 @@ For each Requirement gathered so far, run the two-stage recall→precision pass:
 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). On a `test`-tier auto-resolution, capture the `check_kind` /
-`check_target` / `check_rule` descriptor **only when a wired check is unambiguous**; otherwise
-leave it empty — `--auto` NEVER fabricates a check path (a wrong locate is re-validated and
+`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`.
 
@@ -402,8 +407,8 @@ 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). A
-`resolved`/`test` row ALSO carries its captured `check_kind` / `check_target` / `check_rule`
-descriptor when present (so the projection feeds `verify-phase`'s deterministic locate, #1278);
+`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.
 

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

@@ -70,17 +70,17 @@ Aggregate all must_haves across plans for phase-level verification.
 **Prohibitions (`must_haves.prohibitions`, ADR-550 D3 — the must-NOT sibling block):** When a plan carries `must_haves.prohibitions`, extract each `{ statement, status, verification }` item and route it by `verification` tier in verdict assembly (ADR-550 D4, "B-with-guard", 2026-06-12 maintainer decision). These are NEGATIVE checks (the must-NOT must NOT have happened), distinct from positive `truths`:
 
 - **judgment-tier → mode-dependent soft-gate.** Interactive verify defers each item to the end-of-phase human checkpoint (`human_verify_mode: end-of-phase`). Autonomous verify records a NON-AUTHORITATIVE LLM-judge verdict + a prominent `unverified-prohibition — human review recommended` flag (autonomous completion reads "complete with N flagged prohibitions"). NEVER a silent pass; NEVER a hard halt of an AFK run.
-- **test-tier → ENFORCED via `check prohibition-enforcement` (green on pass, hard-gate on miss/fail).** Accept the `verification: test` value (the SPEC↔must_haves.prohibitions projection contract holds — no forced schema change later). For each test-tier item, the verifier builds `request.check` **DETERMINISTICALLY from the projected descriptor** — it does NOT invent `{ kind, target, rule }`. Read the flat scalar keys `check_kind` / `check_target` / `check_rule` off the `must_haves.prohibitions` item and reconstruct the `CheckDescriptor` via the `descriptorFromProjection` adapter in `prohibition-enforcement` (`descriptorFromProjection(projectedItem)` → `{ kind: check_kind, target: check_target, rule?: check_rule }`). Then attest `failFirst: true` in the request — `failFirst` is the ONE field NOT sourced from the projection; it stays a verify-time caller attestation (#1279 machine-proves it against a violation fixture). Invoke the producer (CLI surface unchanged):
+- **test-tier → ENFORCED via `check prohibition-enforcement` (green on pass, hard-gate on miss/fail).** Accept the `verification: test` value (the SPEC↔must_haves.prohibitions projection contract holds — no forced schema change later). For each test-tier item, the verifier builds `request.check` **DETERMINISTICALLY from the projected descriptor** — it does NOT invent `{ kind, target, rule }`. Read the flat scalar keys `check_kind` / `check_target` / `check_rule` / `check_violation_fixture` off the `must_haves.prohibitions` item and reconstruct the `CheckDescriptor` via the `descriptorFromProjection` adapter in `prohibition-enforcement` (`descriptorFromProjection(projectedItem)` → `{ kind: check_kind, target: check_target, rule?: check_rule, violationFixture?: check_violation_fixture }`). The `violationFixture` (a path to a KNOWN-BAD subject) is the field that gates **green** and it is **now projected** (`check_violation_fixture`, #1346) — so a prohibition authored with all four scalars greens through the projection alone, **zero hand-authoring at verify time**. Do NOT rely on `failFirst`: it is DEMOTED (#1279) and greens nothing on its own; an item with no projected fixture hard-gates fail-closed. Invoke the producer (CLI surface unchanged):
 
   ```bash
   gsd_run check prohibition-enforcement <request.json>
   ```
 
-  where `<request.json>` carries `{ prohibition, check, mode }` — `check` being the wired mechanical-check descriptor `{ kind: 'node-test' | 'lint-rule', target, rule?, failFirst: true }`, with `kind`/`target`/`rule` now sourced from the projected `check_*` scalars (not author/verifier invention) and `failFirst` caller-attested. For `node-test`, `target` (from `check_target`) is the negative-test file path; for `lint-rule`, `target` is the PATH to lint and `rule` (from `check_rule`) is the eslint rule id (e.g. `local/no-source-grep`) — both required (a lint-rule without `rule` is not a valid wired check). The producer LOCATES the wired check, requires the caller-attested `failFirst` marker, RUNS it for a genuine non-vacuous pass, builds `enforcementEvidence`, and emits the `dispositionForProhibition()` verdict (#1259, ADR-550 D5d). Route the result by its typed fields:
+  where `<request.json>` carries `{ prohibition, check, mode }` — `check` being the wired mechanical-check descriptor `{ kind: 'node-test' | 'lint-rule', target, rule?, violationFixture, failFirst? }`, with `kind`/`target`/`rule`/`violationFixture` now sourced from the projected `check_*` scalars (not author/verifier invention — #1278 + #1346). For `node-test`, `target` (from `check_target`) is the negative-test file path; for `lint-rule`, `target` is the PATH to lint and `rule` (from `check_rule`) is the eslint rule id (e.g. `local/no-source-grep`) — both required (a lint-rule without `rule` is not a valid wired check). `violationFixture` (from `check_violation_fixture`) is the path to a KNOWN-BAD subject the producer runs the check against to **machine-prove fail-first** (for `node-test`, injected via the `GSD_PROHIB_SUBJECT` env convention — #1279); `failFirst` is a DEMOTED, non-authoritative hint kept only for backward route-JSON shape (no path greens on it alone — FF-08). The producer LOCATES the wired check from the projection, **machine-proves it is fail-first** by running it against the violation and confirming it goes RED, RUNS it for a genuine non-vacuous pass, builds `enforcementEvidence`, and emits the `dispositionForProhibition()` verdict (#1259 + #1278 + #1279, ADR-550 D5d). Fail-first is **machine-proven, not caller-attested** — absent a provable violation the producer fails closed, never falling back to attestation. Route the result by its typed fields:
   - **`status: 'green'`, `flagged: false`** (a genuinely-passing wired negative test / lint rule, `located: true`, non-empty `evidence`) → the item is satisfiable → it can reach **passed**.
   - **missing, non-attested, or genuinely-non-passing check** (`located: false` OR `status: 'unverified'`, `flagged: true`) → **hard-gate**: disposes flagged-unverified, NEVER green, routing to `gaps_found` in BOTH interactive and autonomous modes (a failing mechanical check blocks even AFK; ADR-550 D4 / D3). The deterministic fail-closed default backing every miss/fail is `dispositionForProhibition()` in probe-core (`status: 'unverified'`, `flagged: true` on empty `enforcementEvidence`).
 
-  > **Descriptor source — deterministic locate (#1278, DELIVERED).** The `check` descriptor's `{ kind, target, rule }` is now sourced **deterministically from the projected `check_kind` / `check_target` / `check_rule` scalars** on the `must_haves.prohibitions` item (authored at `/gsd:spec-phase`, projected by `projectProhibitions`, read back via the `descriptorFromProjection` adapter). So a wired passing test closes the gap with **zero manual descriptor authoring** — the verifier no longer invents the locate (removing the spoofable invent-at-verify-time surface; ADR-857 §147 exogenous grading). **Fail-closed is preserved:** an item with NO projected descriptor — or a PARTIAL one (e.g. a `lint-rule` missing `check_rule`) — makes `descriptorFromProjection` return `null` / an under-specified descriptor, which falls through to the producer's existing fail-closed LOCATE (`located: false`) → flagged-unverified, NEVER green, in BOTH modes. The only field still attested at verify time (not projected) is `failFirst`; machine-proving it against a violation fixture is the remaining **tracked follow-up: #1279**.
+  > **Descriptor source — deterministic locate + machine-proof compose (#1278 + #1346, DELIVERED).** The `check` descriptor's `{ kind, target, rule, violationFixture }` is now sourced **deterministically from the projected `check_kind` / `check_target` / `check_rule` / `check_violation_fixture` scalars** on the `must_haves.prohibitions` item (authored at `/gsd:spec-phase`, projected by `projectProhibitions`, read back via the `descriptorFromProjection` adapter). So both halves close with **zero manual descriptor authoring** — the verifier neither invents the locate (#1278) nor hand-supplies the violation fixture (#1346): a prohibition authored with all four scalars machine-proves fail-first and greens end-to-end through the projection alone (removing the spoofable invent-at-verify-time surface; ADR-857 §147 exogenous grading). **Fail-closed is preserved:** an item with NO projected descriptor, a PARTIAL one (e.g. a `lint-rule` missing `check_rule`), OR a descriptor with **no `check_violation_fixture`** makes `descriptorFromProjection` return `null` / an under-specified or fixture-less descriptor, which falls through to the producer's fail-closed paths (`located: false`, or located-but-unprovable) → flagged-unverified, NEVER green, in BOTH modes. `failFirst` is demoted and greens nothing on its own (#1279, FF-08). 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 vs the env merely being set.
 
 **Option B: Use Success Criteria from ROADMAP.md**