@opengsd/gsd-core 1.10.0 → 1.12.0

package/gsd-core/bin/lib/capability-writer.cjs

@@ -270,8 +270,9 @@ function setCapabilityState(cwd, runtimeConfigDir, desired, opts) {
             // access to getCommitAttribution (which lives in bin/install.js). Until that
             // is refactored into a shared module, surface-path agents for descriptor-
             // driven runtimes will lack the Co-Authored-By trailer that install adds.
-            // Parity is proven when resolveAttribution IS provided (see
-            // tests/issue-1575-agent-descriptor-parity.test.cjs).
+            // Parity is proven when resolveAttribution IS provided (see the
+            // folded:issue-1575-agent-descriptor-parity describe block in
+            // tests/golden-parity-single-source.test.cjs).
             // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
             applySurface(resolvedConfigDir, layout, manifest, undefined, registry, opts?.materialize?.resolveAttribution
                 ? { resolveAttribution: opts.materialize.resolveAttribution }

package/gsd-core/bin/lib/check-command-router.cjs

@@ -28,6 +28,7 @@ const { extractFrontmatter } = frontmatterMod;
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const security_cjs_1 = require("./security.cjs");
 const ui_safety_gate_cjs_1 = require("./ui-safety-gate.cjs");
+const ui_frontend_evidence_cjs_1 = require("./ui-frontend-evidence.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const verifyModule = require("./verify.cjs");
 const { cmdVerifySchemaDrift, cmdVerifyCodebaseDrift } = verifyModule;
@@ -45,6 +46,15 @@ const { evaluatePredicate } = gatePredicateEval;
 const apiCoverageMod = require("./api-coverage.cjs");
 const { detectApiIntegration, validateCoverageMatrix } = apiCoverageMod;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planScanMod = require("./plan-scan.cjs");
+const { scanPhasePlans } = planScanMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const verifyCommandGroundingMod = require("./verify-command-grounding.cjs");
+const { probePhaseVerifyCommands, probePhaseFailingDirections } = verifyCommandGroundingMod;
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 function normalizePhrase(text) {
     // eslint-disable-next-line @typescript-eslint/no-base-to-string
@@ -128,14 +138,13 @@ function gateEnabled(projectDir) {
 function loadPlanContents(phaseDir) {
     if (!node_fs_1.default.existsSync(phaseDir))
         return [];
-    try {
-        return node_fs_1.default.readdirSync(phaseDir)
-            .filter((entry) => /-PLAN\.md$/.test(entry))
-            .map((entry) => readIfExists(node_path_1.default.join(phaseDir, entry)));
-    }
-    catch {
-        return [];
-    }
+    // #3183 (lint-plan-count-drift): source live plan files from the single
+    // owner (scanPhasePlans) instead of a local `-PLAN.md` readdirSync filter
+    // — picks up bare PLAN.md and nested plans/, and excludes plans marked
+    // `status: superseded`, which the prior root-only exact-suffix filter did
+    // neither for.
+    return scanPhasePlans(phaseDir).planFiles
+        .map((entry) => readIfExists(node_path_1.default.join(phaseDir, entry)));
 }
 const DESIGNATED_HEADINGS_RE = /^#{1,6}\s+(?:must[_ ]haves?|truths?|tasks?|objective)\b/i;
 // #2372: scanned-tag set must match the planner-canonical surfaces where a D-NN citation
@@ -337,6 +346,7 @@ function recentCommitMessages(projectDir) {
             encoding: 'utf-8',
             maxBuffer: 4 * 1024 * 1024,
             windowsHide: true,
+            timeout: 15_000,
         });
     }
     catch {
@@ -411,8 +421,11 @@ function cmdDecisionCoverageVerify(projectDir, args, raw) {
         return;
     }
     const planContents = loadPlanContents(phaseDir);
+    // #3183 (lint-plan-count-drift): same single-owner sourcing as
+    // loadPlanContents above — scanPhasePlans's summaryFiles instead of a
+    // local `-SUMMARY.md` readdirSync filter.
     const summaryParts = node_fs_1.default.existsSync(phaseDir)
-        ? node_fs_1.default.readdirSync(phaseDir).filter((entry) => /-SUMMARY\.md$/.test(entry)).map((entry) => readIfExists(node_path_1.default.join(phaseDir, entry)))
+        ? scanPhasePlans(phaseDir).summaryFiles.map((entry) => readIfExists(node_path_1.default.join(phaseDir, entry)))
         : [];
     const haystack = [
         planContents.join('\n\n'),
@@ -442,8 +455,9 @@ function cmdDecisionCoverageVerify(projectDir, args, raw) {
  * ui-plan-gate: given a phase number, checks whether the phase has frontend
  * indicators and whether a *-UI-SPEC.md already exists in the phase directory.
  *
- * Returns JSON: { frontend: boolean, hasUiSpec: boolean, block: boolean }
- *   block = frontend && !hasUiSpec (gate fires when UI work is detected but no spec exists)
+ * Returns JSON: { frontend, hasFrontendEvidence, hasUiSpec, block, uiSpecPath, matchedToken, matchedLine }
+ *   block = frontend && hasFrontendEvidence && !hasUiSpec (#3312: gate fires when
+ *   UI work is detected AND the repo has static frontend evidence but no spec exists)
  *
  * Invocable as: gsd_run check ui-plan-gate <phase>
  *
@@ -477,10 +491,21 @@ function findUiSpecInDir(phaseDir) {
  *   (b) Runs checkUiPresence (frontend detection) — no reimplementation.
  *   (c) Resolves the phase directory via findPhaseInternal (phase-locator.cjs); checks for *-UI-SPEC.md.
  *
- * Returns: { frontend, hasUiSpec, block, uiSpecPath, phaseLookupFailed }
- *   block = frontend && !hasUiSpec
+ * Returns: { frontend, hasFrontendEvidence, hasUiSpec, block, uiSpecPath, matchedToken, matchedLine, phaseLookupFailed }
+ *   block = frontend && hasFrontendEvidence && !hasUiSpec   (#3312)
  *   phaseLookupFailed = ROADMAP.md present but phase header not found (surfaced for
  *                       onError:halt gates so a missing phase doesn't silently bypass)
+ *
+ * #3312 — structural corroboration: `frontend` is a vocabulary signal only. A
+ * hyphen is a word boundary, so a phase naming the repo `dashboard-financeiro`
+ * matches the token `dashboard` exactly like the real compound `micro-frontend`
+ * (the boundary rule of #3718 is intentional and untouched). The gate therefore
+ * blocks only when the token match is corroborated by static frontend evidence
+ * in the repo tree (hasStaticFrontendEvidence: package.json UI-framework dep or
+ * a component-framework file). This mirrors the sibling post-wave gate
+ * computeUiSafetyGate, which requires `hasUiFiles` (git diff) before blocking.
+ * matchedToken/matchedLine surface what tripped the sniffer so an operator can
+ * judge the flag in one second instead of reaching for --skip-ui.
  */
 function computeUiPlanGate(projectDir, phase) {
     // (a) Read the phase section text using the same two-pass lookup as roadmap.get-phase.
@@ -509,6 +534,9 @@ function computeUiPlanGate(projectDir, phase) {
     // (b) Run checkUiPresence (frontend detection) — reuse existing helper; no reimplementation
     const presenceResult = (0, ui_safety_gate_cjs_1.checkUiPresence)(phaseSection);
     const frontend = presenceResult.hasUI;
+    // (b') #3312 — static structural corroboration. Only probed when the sniffer
+    // matched (evidence is irrelevant otherwise); failures degrade to false.
+    const hasFrontendEvidence = frontend ? (0, ui_frontend_evidence_cjs_1.hasStaticFrontendEvidence)(projectDir) : false;
     // (c) Resolve phase directory via findPhaseInternal and check for *-UI-SPEC.md
     let phaseDir = '';
     try {
@@ -528,10 +556,13 @@ function computeUiPlanGate(projectDir, phase) {
     catch { /* phase dir lookup failure → hasUiSpec=false */ }
     const uiSpecPath = findUiSpecInDir(phaseDir);
     const hasUiSpec = uiSpecPath !== '';
-    // block = frontend phase with no UI-SPEC
-    const block = frontend && !hasUiSpec;
+    // block = frontend phase with structural frontend evidence and no UI-SPEC (#3312)
+    const block = frontend && hasFrontendEvidence && !hasUiSpec;
     const result = {
-        frontend, hasUiSpec, block, uiSpecPath: hasUiSpec ? uiSpecPath : null,
+        frontend, hasFrontendEvidence, hasUiSpec, block,
+        uiSpecPath: hasUiSpec ? uiSpecPath : null,
+        matchedToken: presenceResult.matchedToken,
+        matchedLine: presenceResult.matchedLine,
     };
     if (phaseLookupFailed)
         result.phaseLookupFailed = true;
@@ -613,6 +644,7 @@ function computeUiSafetyGate(projectDir, phase) {
             encoding: 'utf-8',
             maxBuffer: 2 * 1024 * 1024,
             windowsHide: true,
+            timeout: 10_000,
         });
         hasUiFiles = changed.split('\n').some((f) => f.trim() && (UI_FILE_EXTENSIONS_RE.test(f) || UI_PATH_PATTERNS_RE.test(f)));
     }
@@ -679,7 +711,9 @@ function cmdTddReviewCheckpoint(projectDir, args, raw) {
     const tddPlanFiles = [];
     if (phaseDir) {
         try {
-            const files = node_fs_1.default.readdirSync(phaseDir).filter(f => f.endsWith('-PLAN.md'));
+            // #3183: canonical plan set (root+nested, superseded-excluded) from the
+            // single owner, rather than a root-only hand-rolled readdirSync filter.
+            const files = scanPhasePlans(phaseDir).planFiles;
             for (const file of files) {
                 const planPath = node_path_1.default.join(phaseDir, file);
                 const content = readIfExists(planPath);
@@ -728,17 +762,17 @@ function cmdTddReviewCheckpoint(projectDir, args, raw) {
         let green = false;
         let refactor = false;
         try {
-            const redCommit = (0, node_child_process_1.execFileSync)('git', ['log', '--oneline', `--grep=^test(${planId}):`, '--', '.'], { cwd: projectDir, encoding: 'utf-8', maxBuffer: 1024 * 1024, windowsHide: true });
+            const redCommit = (0, node_child_process_1.execFileSync)('git', ['log', '--oneline', `--grep=^test(${planId}):`, '--', '.'], { cwd: projectDir, encoding: 'utf-8', maxBuffer: 1024 * 1024, windowsHide: true, timeout: 10_000 });
             red = redCommit.trim().length > 0;
         }
         catch { /* git unavailable or no match */ }
         try {
-            const greenCommit = (0, node_child_process_1.execFileSync)('git', ['log', '--oneline', `--grep=^feat(${planId}):`, '--', '.'], { cwd: projectDir, encoding: 'utf-8', maxBuffer: 1024 * 1024, windowsHide: true });
+            const greenCommit = (0, node_child_process_1.execFileSync)('git', ['log', '--oneline', `--grep=^feat(${planId}):`, '--', '.'], { cwd: projectDir, encoding: 'utf-8', maxBuffer: 1024 * 1024, windowsHide: true, timeout: 10_000 });
             green = greenCommit.trim().length > 0;
         }
         catch { /* git unavailable or no match */ }
         try {
-            const refactorCommit = (0, node_child_process_1.execFileSync)('git', ['log', '--oneline', `--grep=^refactor(${planId}):`, '--', '.'], { cwd: projectDir, encoding: 'utf-8', maxBuffer: 1024 * 1024, windowsHide: true });
+            const refactorCommit = (0, node_child_process_1.execFileSync)('git', ['log', '--oneline', `--grep=^refactor(${planId}):`, '--', '.'], { cwd: projectDir, encoding: 'utf-8', maxBuffer: 1024 * 1024, windowsHide: true, timeout: 10_000 });
             refactor = refactorCommit.trim().length > 0;
         }
         catch { /* git unavailable or no match */ }
@@ -752,14 +786,11 @@ function cmdTddReviewCheckpoint(projectDir, args, raw) {
     }
     const violations = rows.filter(r => r.status === 'FAIL').length;
     // Build review table
-    const sep = '━'.repeat(53);
     const tableHeader = '| Plan | RED | GREEN | REFACTOR | Status |';
     const tableDivider = '|------|-----|-------|----------|--------|';
     const tableRows = rows.map(r => `| ${r.planId.padEnd(4)} | ${r.red ? ' ✓ ' : ' ✗ '} | ${r.green ? '  ✓  ' : '  ✗  '} | ${r.refactor ? '   ✓    ' : '   —    '} | ${r.status.padEnd(6)} |`);
     let table = [
-        sep,
-        ` TDD REVIEW — Phase ${phase}`,
-        sep,
+        `### TDD REVIEW — Phase ${phase}`,
         '',
         `TDD Plans: ${tddPlanFiles.length} | Gate violations: ${violations}`,
         '',
@@ -794,6 +825,111 @@ function cmdTddReviewCheckpoint(projectDir, args, raw) {
     // the host-loop dispatch's advisory branch can surface it.
     output(result, raw, undefined);
 }
+/**
+ * Resolve a phase argument to an absolute phase directory, or '' when it
+ * cannot be resolved. Shared by every `check` arm that probes a phase's
+ * PLAN.md files, so the two never drift (DEFECT.GENERATIVE-FIX-DIVERGENCE).
+ * Never throws — the callers emit a degraded JSON payload instead, because
+ * a consumer must be able to tell "nothing to report" from "could not look".
+ */
+function resolvePhaseDirOrEmpty(projectDir, phase) {
+    try {
+        const result = findPhaseInternal(projectDir, phase);
+        if (result && typeof result === 'object') {
+            // findPhaseInternal returns { directory: '<relative-posix-path>', ... }
+            // directory is relative to cwd — resolve it to absolute.
+            const relDir = typeof result['directory'] === 'string' ? result['directory'] : '';
+            if (relDir) {
+                return node_path_1.default.resolve(projectDir, relDir);
+            }
+        }
+        else if (typeof result === 'string') {
+            return result;
+        }
+    }
+    catch { /* phase dir lookup failure → caller emits degraded payload */ }
+    return '';
+}
+// ─── verify-command-paths (#2401) ──────────────────────────────────────────────
+/**
+ * verify-command-paths: probes every `<automated>` verify command declared in a
+ * phase's `-PLAN.md` files against the filesystem WITHOUT executing anything —
+ * see verify-command-grounding.cjs for the recognizer contract.
+ *
+ * Args: check verify-command-paths <phase>
+ * Invocable as: gsd_run check verify-command-paths <phase>
+ *
+ * When the phase cannot be resolved to a directory, this emits a non-throwing
+ * degraded JSON payload (status/commands/counts all zeroed, `readError`
+ * populated) rather than calling `error()` — the plan-checker parses this
+ * result and must be able to distinguish "nothing to report" from "could not
+ * look", which a non-zero exit / thrown error would collapse.
+ */
+function cmdVerifyCommandPaths(projectDir, args, raw) {
+    // args[0] = 'check', args[1] = 'verify-command-paths', args[2] = phase
+    const phase = args[2] || '';
+    if (!phase) {
+        output({
+            status: 'unresolvable',
+            commands: [],
+            counts: { blocker: 0, warning: 0, total: 0 },
+            readError: 'verify-command-paths requires a phase argument: check verify-command-paths <phase>',
+        }, raw, undefined);
+        return;
+    }
+    const phaseDir = resolvePhaseDirOrEmpty(projectDir, phase);
+    if (!phaseDir) {
+        output({
+            status: 'unresolvable',
+            commands: [],
+            counts: { blocker: 0, warning: 0, total: 0 },
+            readError: `could not resolve phase directory for phase ${phase}`,
+        }, raw, undefined);
+        return;
+    }
+    const probed = probePhaseVerifyCommands({ phaseDir, projectRoot: projectDir });
+    output(probed, raw, undefined);
+}
+// ─── verify-failure-directions (#3172) ─────────────────────────────────────────
+/**
+ * verify-failure-directions: probes every `<automated>` verify command
+ * declared in a phase's `-PLAN.md` files for a stated `<fails_when>` failing
+ * direction — see verify-command-grounding.cjs for the recognizer contract.
+ *
+ * Args: check verify-failure-directions <phase>
+ * Invocable as: gsd_run check verify-failure-directions <phase>
+ *
+ * When the phase cannot be resolved to a directory, this emits a non-throwing
+ * degraded JSON payload (status/commands/counts all zeroed, `readError`
+ * populated) rather than calling `error()` — the plan-checker parses this
+ * result and must be able to distinguish "nothing to report" from "could not
+ * look", which a non-zero exit / thrown error would collapse.
+ */
+function cmdVerifyFailureDirections(projectDir, args, raw) {
+    // args[0] = 'check', args[1] = 'verify-failure-directions', args[2] = phase
+    const phase = args[2] || '';
+    if (!phase) {
+        output({
+            status: 'unresolvable',
+            commands: [],
+            counts: { blocker: 0, warning: 0, total: 0 },
+            readError: 'verify-failure-directions requires a phase argument: check verify-failure-directions <phase>',
+        }, raw, undefined);
+        return;
+    }
+    const phaseDir = resolvePhaseDirOrEmpty(projectDir, phase);
+    if (!phaseDir) {
+        output({
+            status: 'unresolvable',
+            commands: [],
+            counts: { blocker: 0, warning: 0, total: 0 },
+            readError: `could not resolve phase directory for phase ${phase}`,
+        }, raw, undefined);
+        return;
+    }
+    const result = probePhaseFailingDirections({ phaseDir });
+    output(result, raw, undefined);
+}
 // ─── gap-analysis-plan-post ───────────────────────────────────────────────────
 /**
  * gap-analysis-plan-post: non-blocking advisory check that runs the post-planning
@@ -1172,6 +1308,27 @@ function cmdApiCoverageVerifyPre(projectDir, args, raw) {
         }, raw, undefined);
         return;
     }
+    // An EMPTY scope is not a negative verdict. This gate's neighbouring arms
+    // already fail closed (unresolvable phase → block; unreadable plan → block),
+    // but a phase with no plan body AND no roadmap section fell through to
+    // detection over zero bytes and CERTIFIED "no external-API integration" —
+    // clearing a blocking seal gate on a probe that examined nothing
+    // (ADR-3889 failure class (c), #3909). The discriminator is BYTES EXAMINED,
+    // never SIGNALS FOUND: a phase with real plans and no API vocabulary still
+    // reaches the pass below unchanged.
+    if (scope.text.trim() === '') {
+        output({
+            block: true,
+            passed: false,
+            coverage_present: false,
+            detected: false,
+            scope_unavailable: true,
+            message: 'api-coverage: the phase scope is empty — no plan body and no roadmap section were ' +
+                'found, so nothing was examined. Refusing to certify no external-API integration ' +
+                'from an unestablished scope. Add the phase plan, or add a COVERAGE.md declaration.',
+        }, raw, undefined);
+        return;
+    }
     const detection = detectApiIntegration(scope.text);
     if (detection.detected) {
         // Surface only verb/noun (typed, bounded) — NOT raw prose snippets — so the
@@ -1207,12 +1364,26 @@ function isRealReadFailure(err) {
 function readPhaseScope(projectDir, phaseDir, phaseNumber) {
     const chunks = [];
     let readError = null;
-    try {
-        const entries = node_fs_1.default.readdirSync(phaseDir, { withFileTypes: true });
-        const plans = entries
-            .filter((e) => e.isFile() && /-PLAN\.md$/i.test(e.name))
-            .map((e) => e.name)
-            .sort();
+    // A MISSING phase directory is fine (no plans yet → fall through to the
+    // roadmap). Checked up front (rather than via a readdirSync catch) because
+    // #3183 (lint-plan-count-drift) now sources the plan-file list from the
+    // single owner (scanPhasePlans) instead of a local `-PLAN\.md$` readdirSync
+    // filter — picks up bare PLAN.md and nested plans/, and excludes
+    // superseded plans, none of which the prior root-only exact-suffix filter
+    // did.
+    if (node_fs_1.default.existsSync(phaseDir)) {
+        const scan = scanPhasePlans(phaseDir);
+        if (scan.scope === SCOPE.UNREADABLE) {
+            // Directory exists but scanPhasePlans's own readdirSync(phaseDir) call
+            // failed (EACCES/EIO race) — a real read failure the gate must not
+            // silently pass (#2365 review), mirroring the prior isRealReadFailure
+            // branch below for the readdirSync-throws case.
+            return {
+                text: '',
+                readError: 'could not read the phase directory: scanPhasePlans reported scope UNREADABLE',
+            };
+        }
+        const plans = [...scan.planFiles].sort();
         for (const p of plans) {
             try {
                 chunks.push(node_fs_1.default.readFileSync(node_path_1.default.join(phaseDir, p), 'utf8'));
@@ -1226,17 +1397,6 @@ function readPhaseScope(projectDir, phaseDir, phaseNumber) {
             }
         }
     }
-    catch (err) {
-        // A MISSING phase directory is fine (no plans yet → fall through to the
-        // roadmap). A directory that exists but cannot be enumerated (EACCES/EIO)
-        // is a real read failure the gate must not silently pass (#2365 review).
-        if (isRealReadFailure(err)) {
-            return {
-                text: '',
-                readError: `could not read the phase directory: ${err instanceof Error ? err.message : String(err)}`,
-            };
-        }
-    }
     if (readError)
         return { text: chunks.join('\n\n'), readError };
     if (chunks.join('').trim().length > 0)
@@ -1290,6 +1450,18 @@ function routeCheckCommand({ args, cwd, raw }) {
         cmdGapAnalysisPlanPost(cwd, args, raw);
         return;
     }
+    if (subcommand === 'verify-command-paths') {
+        // Deterministic filesystem probe for <automated> verify commands (#2401) —
+        // never executes anything; see verify-command-grounding.cjs.
+        cmdVerifyCommandPaths(cwd, args, raw);
+        return;
+    }
+    if (subcommand === 'verify-failure-directions') {
+        // Presence probe for a stated <fails_when> per <automated> command
+        // (#3172) — never executes anything; see verify-command-grounding.cjs.
+        cmdVerifyFailureDirections(cwd, args, raw);
+        return;
+    }
     if (subcommand === 'api-coverage-verify-pre') {
         // ai-integration capability blocking gate at verify:pre (#1562). Dot-to-
         // hyphen normalization means query "api-coverage.verify-pre" routes here.
@@ -1336,7 +1508,7 @@ function routeCheckCommand({ args, cwd, raw }) {
         (0, prohibition_enforcement_cjs_1.routeProhibitionEnforcement)(args, raw);
         return;
     }
-    error('Unknown check subcommand. Available: api-coverage-verify-pre, auto-mode, decision-coverage-plan, decision-coverage-verify, gap-analysis-plan-post, predicate, prohibition-enforcement, tdd-review-checkpoint, ui-plan-gate, ui-safety-gate, verify-schema-drift, verify-codebase-drift', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+    error('Unknown check subcommand. Available: api-coverage-verify-pre, auto-mode, decision-coverage-plan, decision-coverage-verify, gap-analysis-plan-post, predicate, prohibition-enforcement, tdd-review-checkpoint, ui-plan-gate, ui-safety-gate, verify-command-paths, verify-failure-directions, verify-schema-drift, verify-codebase-drift', ERROR_REASON.SDK_UNKNOWN_COMMAND);
 }
 module.exports = {
     routeCheckCommand,
@@ -1345,6 +1517,8 @@ module.exports = {
     computeUiPlanGate,
     computeUiSafetyGate,
     cmdGapAnalysisPlanPost,
+    cmdVerifyCommandPaths,
+    cmdVerifyFailureDirections,
     cmdTddReviewCheckpoint,
     cmdCheckPredicate,
     buildPredicateDeps,

package/gsd-core/bin/lib/claude-orchestration.cjs

@@ -470,13 +470,43 @@ function emitWorkflowScript(input) {
         lines.push('// read-only in a Workflow script — set it via the caller\'s token directive.');
     }
     lines.push('');
+    // #3302: the generated script must hand the per-agent executor results back
+    // to the orchestrator so it can feed the wave merge chain. Emitted right
+    // after the header comments (meta stays the first statement): a helper that
+    // extracts the executor's <worktree_metadata> JSON (agents/gsd-executor.md
+    // <worktree_metadata_capture>) from one agent() result, plus the outcomes
+    // accumulator the stage barriers below push into. `metadata` is null when
+    // the result carried no parseable block — the LOUD-failure input the
+    // orchestrator halts on for expects_worktree plans (never a silent skip).
+    lines.push('// #3302: extract the executor-returned <worktree_metadata> JSON so the');
+    lines.push('// orchestrator can record it into WAVE_WORKTREE_MANIFEST after the run');
+    lines.push('// (worktree.record-agent -> worktree.cleanup-wave, the same manifest-scoped');
+    lines.push('// merge chain inline dispatch feeds). null = absent/unparseable/interrupted.');
+    lines.push('function gsdWorktreeMetadata(agentResult) {');
+    lines.push('  if (typeof agentResult !== \'string\') return null;');
+    lines.push('  const m = agentResult.match(/<worktree_metadata>([\\s\\S]*?)<\\/worktree_metadata>/);');
+    lines.push('  if (m === null) return null;');
+    lines.push('  try {');
+    lines.push('    const parsed = JSON.parse(m[1]);');
+    lines.push('    return (parsed !== null && typeof parsed === \'object\') ? parsed : null;');
+    lines.push('  } catch (e) {');
+    lines.push('    return null;');
+    lines.push('  }');
+    lines.push('}');
+    lines.push('const gsdAgentOutcomes = [];');
+    lines.push('');
     const stagesByWave = [];
     let totalPlans = 0;
+    let worktreePlans = 0;
     for (let wi = 0; wi < waves.length; wi++) {
         const wave = waves[wi];
         const stages = partitionStages(wave.plans);
         stagesByWave.push(stages);
         totalPlans += wave.plans.length;
+        for (const p of wave.plans) {
+            if (p.use_worktree !== false)
+                worktreePlans += 1;
+        }
         lines.push('// Wave ' + wave.id);
         // Title must match this wave's meta.phases entry EXACTLY.
         lines.push('phase(' + quoteString('Wave ' + wave.id) + ')');
@@ -491,17 +521,37 @@ function emitWorkflowScript(input) {
             // threw "parallel() expects an array of functions" (#2590). Passing
             // agent() results directly would also start every agent eagerly, before
             // parallel() could bound concurrency.
-            lines.push('await parallel([');
+            // #3302: capture the barrier's resolved results (one per thunk, in thunk
+            // order — the documented parallel() contract) so each plan's outcome can
+            // be tagged and returned below. Discarding them stranded every
+            // worktree-wf_* branch: the merge chain had no input (#3302).
+            lines.push('const gsdStage_' + wi + '_' + si + ' = await parallel([');
             for (const p of stagePlans) {
                 lines.push('  () => agent(' + quoteString(p.brief) + ', ' + agentOptions(p, executorModel) + '),');
             }
             lines.push('])');
+            // Positional tagging is decided at EMIT time from the validated manifest,
+            // so attribution survives out-of-order completion and needs no runtime
+            // introspection. expects_worktree mirrors agentOptions' own per-plan
+            // decision (use_worktree !== false).
+            lines.push('gsdAgentOutcomes.push(');
+            for (let pi = 0; pi < stagePlans.length; pi++) {
+                const p = stagePlans[pi];
+                const tail = pi < stagePlans.length - 1 ? ',' : '';
+                lines.push('  { plan: ' + quoteString(p.id) + ', expects_worktree: ' + (p.use_worktree !== false) + ', metadata: gsdWorktreeMetadata(gsdStage_' + wi + '_' + si + '[' + pi + ']) }' + tail);
+            }
+            lines.push(')');
         }
         if (wi < waves.length - 1)
             lines.push('');
     }
-    lines.push('// Each agent writes SUMMARY.md on its worktree branch; commits land there');
-    lines.push('// and are merged by the orchestrator exactly as in inline wave dispatch.');
+    // #3302: the script's top-level return value is what the Workflow tool hands
+    // back to the orchestrator. One { plan, expects_worktree, metadata } entry
+    // per dispatched plan; the orchestrator records every worktree entry via
+    // `gsd_run query worktree.record-agent` and HALTS on a null metadata entry
+    // for an expects_worktree plan (see the execute:wave:pre fragment) — a
+    // silently-empty manifest is the exact #3302 failure mode.
+    lines.push('return gsdAgentOutcomes');
     const script = lines.join('\n');
     return {
         ok: true,
@@ -509,6 +559,9 @@ function emitWorkflowScript(input) {
         summary: {
             waves: waves.length,
             plans: totalPlans,
+            // #3302: the number of record-agent entries the orchestrator must end up
+            // with in WAVE_WORKTREE_MANIFEST after the run — the loud count check.
+            worktreePlans,
             stagesByWave,
             resumeRunId: runId,
             budgetTokens,