@opengsd/gsd-core 1.7.0 → 1.8.0

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

@@ -255,8 +255,13 @@ function setCapabilityState(cwd, runtimeConfigDir, desired, opts) {
         try {
             // eslint-disable-next-line @typescript-eslint/no-require-imports
             const runtimeArtifactLayout = require('./runtime-artifact-layout.cjs');
+            // #2322: thread the SAME composed registry (loaded above, includeInstalled:true)
+            // into layout resolution so the skills kind's stage() closure can bind a
+            // third-party capability skill to its declaring capId at staging time —
+            // required for BOTH the '*' (full-profile) fill-in and the ownership binding
+            // (see resolveRuntimeArtifactLayout's #2322 doc comment).
             // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-            const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, resolvedConfigDir, scope);
+            const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, resolvedConfigDir, scope, registry);
             const commandsGsdDir = _resolveCommandsGsdDir();
             const manifest = _resolveManifest(commandsGsdDir, resolvedConfigDir);
             // #1575: applySurface now accepts opts.resolveAttribution so surface-path

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

@@ -134,7 +134,26 @@ function loadPlanContents(phaseDir) {
     }
 }
 const DESIGNATED_HEADINGS_RE = /^#{1,6}\s+(?:must[_ ]haves?|truths?|tasks?|objective)\b/i;
-const XML_DECISION_TAGS_RE = /<(?:objective|tasks?|action)(?:\s[^>]{0,1000})?>((?:(?!<(?:objective|tasks?|action)[\s>])[\s\S])*?)<\/(?:objective|tasks?|action)>/gi;
+// #2372: scanned-tag set must match the planner-canonical surfaces where a D-NN citation
+// is meaningful. `<objective>`/`<tasks>`/`<task>`/`<action>` are the historical core. The
+// planner is also explicitly told (plan-phase.md) to cite decisions in `<read_first>`,
+// `<behavior>`, `<verify>`, `<acceptance_criteria>`, and `<done>` — those are now scanned too,
+// so the gate no longer reports a false coverage gap when a decision is cited in any of them.
+//
+// Implementation: per-tag matching, NOT a single wide alternation. A single alternation
+// like `<(?:a|b|c)>...<\/(?:a|b|c)>` halts the outer tag's body capture at any inner tag
+// in the set, dropping any citation in the outer tag's prefix prose — e.g.
+// `<action>per D-05 <verify>npm test</verify></action>` would lose D-05 because `<verify>`
+// halts the `<action>` body before the citation. Per-tag matching avoids this: each tag's
+// body terminates only at its OWN closing tag, so `<verify>` inside `<action>` is absorbed
+// into `<action>`'s body (D-05 caught) AND `<verify>` is matched separately on its own pass.
+// Each per-tag regex keeps the ReDoS-safe negative-lookahead tempering (#2128).
+const XML_DECISION_TAG_NAMES = ['objective', 'tasks', 'task', 'action', 'read_first', 'behavior', 'verify', 'acceptance_criteria', 'done'];
+function buildXmlDecisionTagRegex(tagName) {
+    // Per-tag: body tempering stops only at the SAME tag's reopening or closing — other
+    // scanned tags pass through as text into this body. Non-greedy `*?` to first close.
+    return new RegExp(`<${tagName}(?:\\s[^>]{0,1000})?>((?:(?!<${tagName}[\\s>])[\\s\\S])*?)<\\/${tagName}>`, 'gi');
+}
 function stripCommentsAndFences(text) {
     // HTML-comment stripping stays caller-side (the seam does not strip HTML comments).
     // Stop-at-next-open body (ReDoS-safe, #2128); an UNCLOSED `<!--` does not match,
@@ -162,9 +181,12 @@ function extractYamlBlock(frontmatter, key) {
 }
 function extractXmlTagBodies(text) {
     const parts = [];
-    for (const match of text.matchAll(XML_DECISION_TAGS_RE)) {
-        if (match[1])
-            parts.push(match[1]);
+    for (const tagName of XML_DECISION_TAG_NAMES) {
+        const re = buildXmlDecisionTagRegex(tagName);
+        for (const match of text.matchAll(re)) {
+            if (match[1])
+                parts.push(match[1]);
+        }
     }
     return parts.join('\n');
 }
@@ -209,7 +231,10 @@ function buildPlanMessage(uncovered) {
         '',
         ...uncovered.map((item) => `- **${item.id}** (${item.category || 'uncategorized'}): ${item.text}`),
         '',
-        'Resolve by citing `D-NN:` in a relevant plan\'s `must_haves`/`truths` (or body),',
+        'Resolve by citing `D-NN:` in any of the scanned plan surfaces: front-matter',
+        '`must_haves`/`truths`/`objective`, a `## must_haves`/`truths`/`tasks`/`objective`',
+        'heading, or an `<objective>`/`<tasks>`/`<task>`/`<action>`/`<read_first>`/`<behavior>`/`<verify>`/`<acceptance_criteria>`/`<done>`',
+        'tag body. Other locations (prose outside those headings, comments, other XML tags) are not scanned.',
         'OR move the decision to `### Claude\'s Discretion` / tag it `[informational]` if it should not be tracked.',
     ].join('\n');
 }
@@ -645,7 +670,11 @@ function cmdTddReviewCheckpoint(projectDir, args, raw) {
                 const planPath = node_path_1.default.join(phaseDir, file);
                 const content = readIfExists(planPath);
                 // Check frontmatter for type: tdd
-                const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+                // CRLF-tolerant: a PLAN.md written with Windows line endings (---\r\n...---)
+                // must still match. The same CRLF-tolerant form is already used at line 205
+                // (extractPlanDesignatedSections); this is the same canonical pattern, applied
+                // here for the tdd-classification path. Fixes #2449.
+                const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
                 if (frontmatterMatch) {
                     const fm = frontmatterMatch[1];
                     if (/^type:\s*tdd\s*$/m.test(fm)) {
@@ -1010,6 +1039,38 @@ function cmdApiCoverageVerifyPre(projectDir, args, raw) {
         }
         const v = validateCoverageMatrix(matrixText);
         if (v.valid) {
+            if (v.none_declared) {
+                // The declaration is the human override for the detector — it PASSES
+                // even when detection fires (that is acceptance #5's point: the
+                // detector is fallible and the declaration is the reasoned overrule).
+                // But a contradiction must be VISIBLE, not silent: re-run detection
+                // over the phase scope and surface any signals it still finds
+                // (#2365 review S-1).
+                const declScope = readPhaseScope(projectDir, resolvedDir, phaseNumber);
+                const declDetection = detectApiIntegration(declScope.text);
+                const declSignals = declDetection.signals.map((s) => ({ verb: s.verb, noun: s.noun }));
+                // The declaration legitimately wins even over a read error (it is the
+                // human overrule), but if scope was incomplete we say so — the contract
+                // is that contradictions stay visible, not silent (#2365 review).
+                const baseMsg = declDetection.detected
+                    ? `api-coverage: COVERAGE.md declares no external API integration, overriding ${declSignals.length} detected signal(s) — confirm the declaration is accurate`
+                    : 'api-coverage: COVERAGE.md declares no external API integration — matrix not required';
+                output({
+                    block: false,
+                    passed: true,
+                    coverage_present: true,
+                    matrix: coverageFile,
+                    counts: v.counts,
+                    none_declared: true,
+                    detected: declDetection.detected,
+                    ...(declDetection.detected ? { signals: declSignals } : {}),
+                    ...(declScope.readError ? { scope_read_error: declScope.readError } : {}),
+                    message: declScope.readError
+                        ? `${baseMsg} (note: phase scope was incompletely read — ${declScope.readError})`
+                        : baseMsg,
+                }, raw, undefined);
+                return;
+            }
             output({
                 block: false,
                 passed: true,
@@ -1044,8 +1105,22 @@ function cmdApiCoverageVerifyPre(projectDir, args, raw) {
         return;
     }
     // (2) no matrix — detect whether this phase integrates an external API.
-    const scopeText = readPhaseScope(projectDir, resolvedDir, phaseNumber);
-    const detection = detectApiIntegration(scopeText);
+    const scope = readPhaseScope(projectDir, resolvedDir, phaseNumber);
+    if (scope.readError) {
+        // Fail-closed: an unreadable plan could be the one describing the
+        // integration, so we cannot certify "no integration" — block and surface it.
+        output({
+            block: true,
+            passed: false,
+            coverage_present: false,
+            detected: false,
+            message: `api-coverage: could not read the phase scope (${scope.readError}); ` +
+                'refusing to certify no external-API integration from incomplete scope. ' +
+                'Fix the unreadable plan file, 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
         // gate output cannot relay injected PLAN.md instructions to the orchestrator.
@@ -1070,15 +1145,16 @@ function cmdApiCoverageVerifyPre(projectDir, args, raw) {
         message: 'api-coverage: no external-API integration detected; coverage matrix not required',
     }, raw, undefined);
 }
-/**
- * Read the phase-scope text used for API-integration detection. Uses the
- * resolved plan files (PLAN.md bodies — the planner's own words about what the
- * phase does) and, as a fallback, ONLY THIS PHASE'S ROADMAP section (not the
- * whole roadmap, which would cross-contaminate sibling phases). Strips nothing
- * here — detectApiIntegration strips fenced code itself.
- */
+/** A filesystem error that is NOT "does not exist" — i.e. a real read failure
+ *  (EACCES/EIO/…) the gate must not swallow. `ENOENT` is a legitimate "not
+ *  there yet" and is treated as absence, not error. */
+function isRealReadFailure(err) {
+    const code = err?.code;
+    return err != null && code !== 'ENOENT';
+}
 function readPhaseScope(projectDir, phaseDir, phaseNumber) {
     const chunks = [];
+    let readError = null;
     try {
         const entries = node_fs_1.default.readdirSync(phaseDir, { withFileTypes: true });
         const plans = entries
@@ -1086,28 +1162,52 @@ function readPhaseScope(projectDir, phaseDir, phaseNumber) {
             .map((e) => e.name)
             .sort();
         for (const p of plans) {
-            chunks.push(node_fs_1.default.readFileSync(node_path_1.default.join(phaseDir, p), 'utf8'));
+            try {
+                chunks.push(node_fs_1.default.readFileSync(node_path_1.default.join(phaseDir, p), 'utf8'));
+            }
+            catch (err) {
+                // A plan file that exists but cannot be read — record it and keep
+                // reading the rest so the message names the first failure.
+                if (!readError) {
+                    readError = `could not read ${p}: ${err instanceof Error ? err.message : String(err)}`;
+                }
+            }
         }
     }
-    catch {
-        // ignore — fall through to roadmap
+    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)
-        return chunks.join('\n\n');
+        return { text: chunks.join('\n\n'), readError: null };
     // Fallback: ONLY this phase's ROADMAP section (not the whole file, which
-    // would pollute detection with sibling-phase prose). Best-effort; absence or
-    // an unresolvable section is non-fatal (detector returns not-detected).
+    // would pollute detection with sibling-phase prose). A MISSING roadmap/section
+    // is non-fatal; a roadmap that exists but cannot be read is a real failure.
     if (phaseNumber) {
         try {
             const section = getRoadmapPhaseWithFallback(projectDir, phaseNumber);
             if (section)
-                return section;
+                return { text: section, readError: null };
         }
-        catch {
-            // ignore
+        catch (err) {
+            if (isRealReadFailure(err)) {
+                return {
+                    text: '',
+                    readError: `could not read the roadmap fallback: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
         }
     }
-    return '';
+    return { text: '', readError: null };
 }
 function routeCheckCommand({ args, cwd, raw }) {
     // Normalize dots to hyphens in the subcommand so both forms are accepted.
@@ -1197,4 +1297,7 @@ module.exports = {
     cmdCheckPredicate,
     buildPredicateDeps,
     parsePredicateFlags,
+    // Fail-closed phase-scope reader for the api-coverage gate — exported for
+    // in-process failure-injection tests (#2365 review).
+    readPhaseScope,
 };

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

@@ -22,7 +22,20 @@
  *   emit-workflow --waves <path> --run-id <id> [--phase-dir <dir>] [--budget <n>]
  *       Reads a wave/plan manifest JSON file and emits the generated Workflow
  *       script + summary. The manifest shape matches emitWorkflowScript's input:
- *       { waves: [{ id, plans: [{ id, brief, files_modified: string[] }] }] }.
+ *       { waves: [{ id, plans: [{ id, brief, files_modified: string[], use_worktree?: boolean }] }] }.
+ *       `use_worktree` defaults to true; pass `false` for a plan the inline path
+ *       (execute-phase.md step 2.5) would also keep out of worktree isolation
+ *       (submodule-touching plans — #2772 / #2285 finding 1).
+ *
+ *   resolve-wave-dispatch --waves <path> --run-id <id> [--runtime <id>]
+ *       [--agent-sdk-version <ver>] [--no-nested-dispatch] [--phase-dir <dir>]
+ *       [--budget <n>]
+ *       #2285 — the single composed seam a PRE-wave dispatch-backend selector
+ *       (`execute:wave:pre`) uses: resolves detect-backend + emit-workflow in
+ *       ONE call. Emits { backend: 'inline'|'workflow', reason, script?, summary? }.
+ *       Fail-closed identically to detect-backend/emit-workflow individually —
+ *       any gate miss, or an emit failure on a malformed --waves manifest,
+ *       resolves to 'inline' with no script.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -36,30 +49,26 @@ const core = require("./claude-orchestration.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const configLoader = require("./config-loader.cjs");
 const { output } = io;
-const { detectWorkflowBackend, emitWorkflowScript } = core;
+const { detectWorkflowBackend, emitWorkflowScript, resolveWaveDispatch } = core;
 const CAPABLE_HOST = { dispatch: { nested: true, background: true } };
 function usage(error) {
-    error('Usage: gsd-tools claude-orchestration <detect-backend|emit-workflow> [...]\n' +
+    error('Usage: gsd-tools claude-orchestration <detect-backend|emit-workflow|resolve-wave-dispatch> [...]\n' +
         '  detect-backend [--runtime <id>] [--agent-sdk-version <ver>] [--no-nested-dispatch]\n' +
-        '  emit-workflow --waves <path> --run-id <id> [--phase-dir <dir>] [--budget <n>]');
+        '  emit-workflow --waves <path> --run-id <id> [--phase-dir <dir>] [--budget <n>]\n' +
+        '  resolve-wave-dispatch --waves <path> --run-id <id> [--runtime <id>] [--agent-sdk-version <ver>] [--no-nested-dispatch] [--phase-dir <dir>] [--budget <n>]');
 }
 function argValue(args, flag) {
     const i = args.indexOf(flag);
     return i !== -1 && i + 1 < args.length ? args[i + 1] : undefined;
 }
 /**
- * Detect whether the Workflow backend should activate for the current/given
- * runtime. Reads `claude_orchestration.*` from the project config; runtime and
- * SDK version come from flags (the orchestrator already knows these) or env.
+ * Resolve the `claude_orchestration.*` config slice from the project config
+ * (federated keys are merged by loadConfig as a nested object), flattened into
+ * the dotted-key shape `detectWorkflowBackend`/`resolveWaveDispatch` expect. A
+ * config read failure degrades to an empty slice — it must not break the core
+ * loop. Shared by `detect-backend` and `resolve-wave-dispatch`.
  */
-function cmdDetectBackend(args, cwd, raw) {
-    const runtimeId = argValue(args, '--runtime') || process.env['GSD_RUNTIME'] || 'unknown';
-    const agentSdkVersion = argValue(args, '--agent-sdk-version');
-    const noNested = args.includes('--no-nested-dispatch');
-    const hostIntegration = noNested ? { dispatch: { nested: false, background: true } } : CAPABLE_HOST;
-    // Resolve the claude_orchestration.* slice from the project config (federated
-    // keys are merged by loadConfig as a nested object). A config read failure
-    // degrades to inline — it must not break the core loop.
+function resolveFlatClaudeOrchestrationConfig(cwd) {
     let claudeSlice = {};
     try {
         const loaded = configLoader.loadConfig(cwd);
@@ -71,11 +80,56 @@ function cmdDetectBackend(args, cwd, raw) {
     catch {
         claudeSlice = {};
     }
-    // Flatten the nested slice into the dotted-key shape detectWorkflowBackend expects.
     const flatConfig = {};
     for (const k of Object.keys(claudeSlice)) {
         flatConfig['claude_orchestration.' + k] = claudeSlice[k];
     }
+    return flatConfig;
+}
+/**
+ * Resolve `--runtime`/`--agent-sdk-version`/`--no-nested-dispatch` into the
+ * `{ runtimeId, hostIntegration, agentSdkVersion }` triple both `detect-backend`
+ * and `resolve-wave-dispatch` pass to the pure detection seam.
+ */
+function resolveDetectionArgs(args) {
+    const runtimeId = argValue(args, '--runtime') || process.env['GSD_RUNTIME'] || 'unknown';
+    const agentSdkVersion = argValue(args, '--agent-sdk-version');
+    const noNested = args.includes('--no-nested-dispatch');
+    const hostIntegration = noNested ? { dispatch: { nested: false, background: true } } : CAPABLE_HOST;
+    return { runtimeId, hostIntegration, agentSdkVersion };
+}
+/**
+ * Read and parse a `--waves <path>` manifest file.
+ *
+ * #2285 finding 2: a real read/parse failure (`ok:false`) is DISTINCT from a
+ * manifest that parsed fine but has no top-level `waves` key (`ok:true, waves:
+ * undefined`) — collapsing both into the same sentinel made the missing-key
+ * case exit 0 with ZERO output (fail-silent), breaking the "exit 0 => parseable
+ * JSON verdict" contract callers rely on. Only the `ok:false` (read/parse threw)
+ * case calls `error(...)` and should short-circuit the caller; `ok:true` with a
+ * missing/malformed `waves` value must flow through to `emitWorkflowScript`'s
+ * own validation (matching how `{"waves": null}` already behaves) so the caller
+ * emits an explicit, non-empty verdict instead of silently doing nothing.
+ */
+function readWavesManifest(wavesPath, error) {
+    try {
+        const content = node_fs_1.default.readFileSync(node_path_1.default.resolve(wavesPath), 'utf8');
+        const parsed = JSON.parse(content);
+        return { ok: true, waves: parsed['waves'] };
+    }
+    catch (e) {
+        error('could not read/parse --waves file "' + wavesPath + '": ' + (e instanceof Error ? e.message : String(e)));
+        return { ok: false };
+    }
+}
+/**
+ * Detect whether the Workflow backend should activate for the current/given
+ * runtime. Reads `claude_orchestration.*` from the project config; runtime and
+ * SDK version come from flags (the orchestrator already knows these) or env.
+ */
+function cmdDetectBackend(args, cwd, raw) {
+    const { runtimeId, hostIntegration, agentSdkVersion } = resolveDetectionArgs(args);
+    const flatConfig = resolveFlatClaudeOrchestrationConfig(cwd);
     const result = detectWorkflowBackend({ runtimeId, hostIntegration, config: flatConfig, agentSdkVersion });
     output(result, raw);
 }
@@ -95,22 +149,15 @@ function cmdEmitWorkflow(args, _cwd, raw, error) {
         error('emit-workflow requires --run-id <id>');
         return;
     }
-    let waves;
-    try {
-        const content = node_fs_1.default.readFileSync(node_path_1.default.resolve(wavesPath), 'utf8');
-        const parsed = JSON.parse(content);
-        waves = parsed['waves'];
-    }
-    catch (e) {
-        error('emit-workflow: could not read/parse --waves file "' + wavesPath + '": ' + (e instanceof Error ? e.message : String(e)));
-        return;
-    }
+    const read = readWavesManifest(wavesPath, (msg) => error('emit-workflow: ' + msg));
+    if (!read.ok)
+        return; // read/parse failure — error() already surfaced it loudly above
     const budgetTokens = budgetRaw !== undefined ? parseInt(budgetRaw, 10) : undefined;
     const budget = (typeof budgetTokens === 'number' && !Number.isNaN(budgetTokens)) ? budgetTokens : undefined;
     const result = emitWorkflowScript({
         phaseDir,
         runId,
-        waves: waves,
+        waves: read.waves,
         budgetTokens: budget,
     });
     if (!result.ok) {
@@ -119,6 +166,44 @@ function cmdEmitWorkflow(args, _cwd, raw, error) {
     }
     output({ script: result.script, summary: result.summary }, raw);
 }
+/**
+ * #2285 — the single composed seam a PRE-wave dispatch-backend selector
+ * (`execute:wave:pre`) uses: resolves `detect-backend` + `emit-workflow` in
+ * ONE call via `resolveWaveDispatch`. Emits
+ * `{ backend: 'inline'|'workflow', reason, script?, summary? }`.
+ */
+function cmdResolveWaveDispatch(args, cwd, raw, error) {
+    const wavesPath = argValue(args, '--waves');
+    const runId = argValue(args, '--run-id');
+    const phaseDir = argValue(args, '--phase-dir') || '.planning/phases/current';
+    const budgetRaw = argValue(args, '--budget');
+    if (!wavesPath) {
+        error('resolve-wave-dispatch requires --waves <path>');
+        return;
+    }
+    if (!runId) {
+        error('resolve-wave-dispatch requires --run-id <id>');
+        return;
+    }
+    const read = readWavesManifest(wavesPath, (msg) => error('resolve-wave-dispatch: ' + msg));
+    if (!read.ok)
+        return; // read/parse failure — error() already surfaced it loudly above
+    const { runtimeId, hostIntegration, agentSdkVersion } = resolveDetectionArgs(args);
+    const flatConfig = resolveFlatClaudeOrchestrationConfig(cwd);
+    const budgetTokens = budgetRaw !== undefined ? parseInt(budgetRaw, 10) : undefined;
+    const budget = (typeof budgetTokens === 'number' && !Number.isNaN(budgetTokens)) ? budgetTokens : undefined;
+    const result = resolveWaveDispatch({
+        runtimeId,
+        hostIntegration,
+        config: flatConfig,
+        agentSdkVersion,
+        phaseDir,
+        runId,
+        waves: read.waves,
+        budgetTokens: budget,
+    });
+    output(result, raw);
+}
 function routeClaudeOrchestrationCommand(opts) {
     const { args, cwd, raw, error } = opts;
     // args[0] is the family ('claude-orchestration'); the subcommand is args[1].
@@ -129,6 +214,9 @@ function routeClaudeOrchestrationCommand(opts) {
     else if (subcommand === 'emit-workflow') {
         cmdEmitWorkflow(args, cwd, raw, error);
     }
+    else if (subcommand === 'resolve-wave-dispatch') {
+        cmdResolveWaveDispatch(args, cwd, raw, error);
+    }
     else {
         usage(error);
     }

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

@@ -16,15 +16,20 @@
  *     → { ok:true, script, summary } | { ok:false, reason }
  *     Maps GSD's wave/plan model 1:1 onto Workflow primitives:
  *       wave  → sequential `parallel()` stage barriers,
- *       plan  → `agent(brief, { agentType:'gsd-executor', isolation:'worktree' })`,
+ *       plan  → `agent(brief, { agentType:'gsd-executor', isolation:'worktree' })`
+ *         — UNLESS the plan's `use_worktree` is explicitly `false`, in which case
+ *         `isolation` is omitted entirely for that plan (#2772 / #2285 finding 1:
+ *         a submodule-touching plan must never be forced into worktree isolation
+ *         the inline path (execute-phase.md step 2.5) would keep it out of),
  *       files_modified overlap → forces plans into separate sequential stages
  *         (the same overlap rule execute-phase already applies inline),
  *       resumeFromRunId → wired to the phase run id,
  *       budgetTokens → a shared token pool.
- *     The emitted script composes the SAME gsd-executor agent and worktree
- *     isolation the inline path uses, so it produces the same artifacts/commits
- *     (criterion 2). It is a generated string consumed by the orchestrator; this
- *     module never invokes the Workflow tool itself.
+ *     The emitted script composes the SAME gsd-executor agent the inline path
+ *     uses, with per-plan worktree isolation mirroring the inline path's own
+ *     per-plan decision, so it produces the same artifacts/commits (criterion 2).
+ *     It is a generated string consumed by the orchestrator; this module never
+ *     invokes the Workflow tool itself.
  *
  * Design laws:
  *   - Gall's Law: ship a small working slice that composes existing primitives
@@ -259,6 +264,17 @@ function partitionStages(plans) {
 function quoteString(s) {
     return JSON.stringify(s);
 }
+/**
+ * Render the `agent()` options object for a single plan — `isolation: "worktree"`
+ * ONLY when the plan's `use_worktree` is not explicitly `false` (#2772 / #2285
+ * finding 1). This is the single place that decides worktree isolation for the
+ * Workflow backend; it must never diverge from the inline path's per-plan gate.
+ */
+function agentOptions(p) {
+    return p.use_worktree === false
+        ? '{ agentType: "gsd-executor" }'
+        : '{ agentType: "gsd-executor", isolation: "worktree" }';
+}
 /**
  * True if `s` is a safe identifier/path token to interpolate into the generated
  * script WITHOUT requiring a string-literal context — i.e. it contains no
@@ -318,6 +334,9 @@ function emitWorkflowScript(input) {
             if (!isScriptableIdentifier(p.id)) {
                 return { ok: false, reason: 'waves[' + i + '].plans[' + j + '].id must not contain newlines/quotes/backslash/control chars' };
             }
+            if (p.use_worktree !== undefined && typeof p.use_worktree !== 'boolean') {
+                return { ok: false, reason: 'waves[' + i + '].plans[' + j + '].use_worktree must be a boolean if present' };
+            }
             if (seenIds.has(p.id)) {
                 return { ok: false, reason: 'waves[' + i + '] has duplicate plan id "' + p.id + '"' };
             }
@@ -336,8 +355,9 @@ function emitWorkflowScript(input) {
     lines.push('// GSD Workflow script — generated by the claude-orchestration capability (#1143)');
     lines.push('// phase: ' + phaseDir);
     lines.push('// BETA: preview-grade; on any failure the orchestrator falls back to inline dispatch.');
-    lines.push('// Composes the SAME gsd-executor agent + worktree isolation as the inline path,');
-    lines.push('// so artifacts (SUMMARY.md) and commits are produced identically.');
+    lines.push('// Composes the SAME gsd-executor agent as the inline path, so artifacts (SUMMARY.md)');
+    lines.push('// and commits are produced identically. Worktree isolation is per-plan (use_worktree)');
+    lines.push('// and mirrors execute-phase.md step 2.5\'s submodule gate exactly (#2772 / #2285).');
     lines.push('resumeFromRunId(' + quoteString(runId) + ')');
     if (budgetTokens !== null) {
         lines.push('budget(' + budgetTokens + ')');
@@ -361,13 +381,13 @@ function emitWorkflowScript(input) {
             if (stagePlans.length === 1) {
                 const p = stagePlans[0];
                 lines.push('parallel(');
-                lines.push('  agent(' + quoteString(p.brief) + ', { agentType: "gsd-executor", isolation: "worktree" })');
+                lines.push('  agent(' + quoteString(p.brief) + ', ' + agentOptions(p) + ')');
                 lines.push(')');
             }
             else {
                 lines.push('parallel(');
                 for (const p of stagePlans) {
-                    lines.push('  agent(' + quoteString(p.brief) + ', { agentType: "gsd-executor", isolation: "worktree" }),');
+                    lines.push('  agent(' + quoteString(p.brief) + ', ' + agentOptions(p) + '),');
                 }
                 // Replace trailing comma on the last agent line with nothing.
                 const lastIdx = lines.length - 1;
@@ -393,9 +413,64 @@ function emitWorkflowScript(input) {
         },
     };
 }
+/**
+ * #2285 — single composed decision seam for a PRE-wave dispatch-backend selector
+ * (e.g. the `execute:wave:pre` claude-orchestration contribution). Composes
+ * `detectWorkflowBackend` (gate ladder) with `emitWorkflowScript` (wave→plan
+ * mapping) into ONE call so the orchestrator (and its CLI wrapper,
+ * `claude-orchestration resolve-wave-dispatch`) never has to re-implement the
+ * two-step "detect, then maybe emit" sequencing.
+ *
+ * Fail-closed at every layer, matching the two composed functions:
+ *   - `detectWorkflowBackend` resolving anything other than `'workflow'` →
+ *     `inline` immediately; `emitWorkflowScript` is never invoked (no wasted
+ *     work, no risk of a bad emit masking a correct inline fallback).
+ *   - `detectWorkflowBackend` resolves `'workflow'` but `emitWorkflowScript`
+ *     fails (`ok:false` — e.g. a malformed wave manifest) → `inline`, carrying
+ *     the emit failure reason so the caller can surface it. Never a partial or
+ *     broken script.
+ *
+ * This is the designated non-CLI-router, non-test caller of
+ * `detectWorkflowBackend` and `emitWorkflowScript` — the standalone CLI
+ * subcommands (`detect-backend`, `emit-workflow`) remain for inspection/
+ * debugging, but the orchestrator's real per-wave dispatch decision goes
+ * through this seam.
+ *
+ * Never throws on bad input.
+ */
+function resolveWaveDispatch(input) {
+    if (input === null || input === undefined || typeof input !== 'object') {
+        return { backend: 'inline', reason: 'invalid_input' };
+    }
+    const detected = detectWorkflowBackend({
+        runtimeId: input.runtimeId,
+        hostIntegration: input.hostIntegration,
+        config: input.config,
+        agentSdkVersion: input.agentSdkVersion,
+    });
+    if (detected.backend !== 'workflow') {
+        return { backend: 'inline', reason: detected.reason };
+    }
+    const emitted = emitWorkflowScript({
+        phaseDir: input.phaseDir,
+        waves: input.waves,
+        runId: input.runId,
+        budgetTokens: input.budgetTokens,
+    });
+    if (!emitted.ok) {
+        return { backend: 'inline', reason: 'emit_failed: ' + emitted.reason };
+    }
+    return {
+        backend: 'workflow',
+        reason: detected.reason,
+        script: emitted.script,
+        summary: emitted.summary,
+    };
+}
 module.exports = {
     detectWorkflowBackend,
     emitWorkflowScript,
+    resolveWaveDispatch,
     compareSemver,
     isValidSemver,
     WORKFLOW_TOOL_FLOOR_VERSION,

package/gsd-core/bin/lib/command-aliases.cjs

@@ -728,6 +728,20 @@ exports.NON_FAMILY_COMMAND_ALIASES = [
         ],
         "mutation": true
     },
+    {
+        "canonical": "requirements.ready-ids",
+        "aliases": [
+            "requirements ready-ids"
+        ],
+        "mutation": false
+    },
+    {
+        "canonical": "requirements.revert-phase",
+        "aliases": [
+            "requirements revert-phase"
+        ],
+        "mutation": true
+    },
     {
         "canonical": "stats.json",
         "aliases": [