@opengsd/gsd-core 1.7.0 → 1.9.0

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,53 @@ function partitionStages(plans) {
 function quoteString(s) {
     return JSON.stringify(s);
 }
+/**
+ * #2686 — the single decision of whether a resolved executor model is emittable,
+ * and what to emit. Shared by `agentOptions` (the emission) and the provenance
+ * comment (the claim about it) so the two can never disagree — a generated
+ * comment asserting something the generator does not actually do is the exact
+ * failure #2686 was filed for.
+ *
+ * Returns the model to emit, or `undefined` for "emit nothing":
+ *   - non-string        → malformed config; omit rather than throw, matching the
+ *                         defensive typeof guard `mapClaudeOverrideForRuntime`
+ *                         already carries in model-resolver for the same reason.
+ *   - empty/whitespace  → #2517: emitting `model: ""` 404s on runtimes without
+ *                         native tier aliases. Trimmed, so `" "` is also "none".
+ *   - "inherit"         → same rule; matched case-insensitively after trimming,
+ *                         since config is user-authored free text.
+ *
+ * NOTE it does NOT reject unscriptable characters — that is a hard input error,
+ * not a silent omission, and is rejected up front by `emitWorkflowScript` so the
+ * caller sees a reason instead of quietly losing their model routing.
+ */
+function emittableModel(executorModel) {
+    if (typeof executorModel !== 'string')
+        return undefined;
+    const trimmed = executorModel.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (trimmed.toLowerCase() === 'inherit')
+        return undefined;
+    return trimmed;
+}
+/**
+ * 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, executorModel) {
+    const parts = ['agentType: "gsd-executor"'];
+    if (p.use_worktree !== false)
+        parts.push('isolation: "worktree"');
+    // #2686: carry the resolved executor model so this backend honors
+    // model_overrides / model_policy / model_profile exactly as the inline path.
+    const model = emittableModel(executorModel);
+    if (model !== undefined)
+        parts.push('model: ' + quoteString(model));
+    return '{ ' + parts.join(', ') + ' }';
+}
 /**
  * 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
@@ -285,7 +337,7 @@ function emitWorkflowScript(input) {
     if (input === null || input === undefined || typeof input !== 'object') {
         return { ok: false, reason: 'invalid_input' };
     }
-    const { phaseDir, waves, runId } = input;
+    const { phaseDir, waves, runId, executorModel } = input;
     // Identifiers/paths interpolated into the generated script must be free of any
     // character that could terminate a comment, break out of a string literal, or
     // smuggle control bytes — reject up front (security: #1143 review Finding 1).
@@ -295,9 +347,28 @@ function emitWorkflowScript(input) {
     if (!isScriptableIdentifier(runId)) {
         return { ok: false, reason: 'runId must be a non-empty string without newlines/quotes/backslash/control chars' };
     }
+    // #2686 security: the resolved model is interpolated into BOTH an object
+    // literal (safe under quoteString) and a `//` provenance comment (NOT safe
+    // under quoteString — U+2028/U+2029 are LineTerminators that end a single-line
+    // comment in every engine, so a hostile model id would make the rest of the
+    // line live code). Reject the whole emission rather than silently dropping the
+    // model: an unscriptable id is malformed input, and `resolveWaveDispatch` maps
+    // an emit failure to the inline backend WITH a reason, so the user sees it.
+    // Only a STRING carrying such a character is rejected. A non-string is a
+    // malformed config rather than an injection attempt, and stays on the existing
+    // defensive path: `emittableModel` omits it and emission proceeds.
+    if (typeof executorModel === 'string' && UNSCRIPTABLE_CHAR_RE.test(executorModel)) {
+        return { ok: false, reason: 'executorModel must not contain newlines/quotes/backslash/control/line-separator chars' };
+    }
     if (!Array.isArray(waves) || waves.length === 0) {
         return { ok: false, reason: 'waves must be a non-empty array' };
     }
+    // Wave ids must be unique ACROSS waves, not just plan ids within one (#2590).
+    // Each wave emits a `phase("Wave <id>")` call plus a matching meta.phases
+    // entry, and the Workflow tool matches phase titles by exact string — two
+    // waves sharing an id would collapse into one progress group and misattribute
+    // every agent in the second wave to the first.
+    const seenWaveIds = new Set();
     for (let i = 0; i < waves.length; i++) {
         const w = waves[i];
         if (w === null || typeof w !== 'object' || typeof w.id !== 'string') {
@@ -306,6 +377,10 @@ function emitWorkflowScript(input) {
         if (!isScriptableIdentifier(w.id)) {
             return { ok: false, reason: 'waves[' + i + '].id must not contain newlines/quotes/backslash/control chars' };
         }
+        if (seenWaveIds.has(w.id)) {
+            return { ok: false, reason: 'duplicate wave id "' + w.id + '" — wave ids must be unique (phase titles must map 1:1)' };
+        }
+        seenWaveIds.add(w.id);
         if (!Array.isArray(w.plans) || w.plans.length === 0) {
             return { ok: false, reason: 'waves[' + i + '] must have a non-empty plans array' };
         }
@@ -318,6 +393,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 + '"' };
             }
@@ -333,14 +411,63 @@ function emitWorkflowScript(input) {
         ? Math.floor(input.budgetTokens)
         : null;
     const lines = [];
+    // `export const meta = {…}` MUST be the first statement in the script — the
+    // Workflow tool rejects the whole script otherwise (#2590). Leading comments
+    // are not statements, but the meta block is emitted first regardless so the
+    // contract holds under the strictest reading of "first statement".
+    //
+    // meta.phases must be a PURE LITERAL (no variables, calls, spreads, or
+    // template interpolation), and its titles are matched EXACTLY against the
+    // phase() calls emitted below.
+    lines.push('export const meta = {');
+    lines.push('  name: ' + quoteString('gsd-execute-' + runId) + ',');
+    lines.push('  description: ' + quoteString('GSD wave dispatch for ' + phaseDir) + ',');
+    lines.push('  phases: [');
+    for (const w of waves) {
+        lines.push('    { title: ' + quoteString('Wave ' + w.id) + ', detail: '
+            + quoteString(w.plans.length + ' plan(s)') + ' },');
+    }
+    lines.push('  ],');
+    lines.push('}');
+    lines.push('');
     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('resumeFromRunId(' + quoteString(runId) + ')');
+    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).');
+    // #2686 / ADR-1411: state which model was applied — or that none resolved —
+    // so an opted-in user can SEE the routing decision instead of having to read
+    // the emitted options. A fallback must be a visible value, never silent.
+    //
+    // SECURITY: this is a `//` comment, and U+2028/U+2029 are ECMAScript
+    // LineTerminators that END a single-line comment in every engine — the ES2019
+    // change legalized them inside string LITERALS only, so `quoteString` alone is
+    // NOT sufficient here even though it is sufficient in the object literal
+    // above. An unscriptable model id would otherwise close the comment and make
+    // the remainder live top-level code. `emitWorkflowScript` rejects such ids
+    // before reaching this point (see the validation above), which is what makes
+    // interpolating here safe.
+    const provenanceModel = emittableModel(executorModel);
+    if (provenanceModel !== undefined) {
+        lines.push('// model: ' + quoteString(provenanceModel) + ' (resolved for gsd-executor, same source as the inline path)');
+    }
+    else {
+        lines.push('// model: none applied — resolved to "inherit"/empty, so each agent inherits the');
+        lines.push('// orchestrator model (#2517: emitting an empty model 404s on some runtimes).');
+    }
+    lines.push('//');
+    // resumeFromRunId is a Workflow TOOL INPUT parameter, not a script function —
+    // calling it threw "resumeFromRunId is not defined" (#2590). The run id is
+    // carried in summary.resumeRunId for the caller to pass as that input.
+    lines.push('// resume: pass ' + quoteString(runId) + ' as the Workflow tool\'s resumeFromRunId input');
+    lines.push('// (it is a tool parameter, NOT a script function).');
     if (budgetTokens !== null) {
-        lines.push('budget(' + budgetTokens + ')');
+        // `budget` is a read-only object ({ total, spent(), remaining() }) supplied
+        // by the caller's token directive — a script cannot SET it, and `budget(n)`
+        // threw "budget is not a function" (#2590). Recorded as intent only.
+        lines.push('// budget: ' + budgetTokens + ' output tokens intended for this run; `budget` is');
+        lines.push('// read-only in a Workflow script — set it via the caller\'s token directive.');
     }
     lines.push('');
     const stagesByWave = [];
@@ -351,6 +478,8 @@ function emitWorkflowScript(input) {
         stagesByWave.push(stages);
         totalPlans += wave.plans.length;
         lines.push('// Wave ' + wave.id);
+        // Title must match this wave's meta.phases entry EXACTLY.
+        lines.push('phase(' + quoteString('Wave ' + wave.id) + ')');
         for (let si = 0; si < stages.length; si++) {
             const stagePlanIds = stages[si];
             // Resolve back to plan objects for briefs (ids are unique within a wave — validated above).
@@ -358,22 +487,15 @@ function emitWorkflowScript(input) {
             if (stages.length > 1) {
                 lines.push('// Stage ' + si + (si > 0 ? ' (sequential — files_modified overlap)' : ''));
             }
-            if (stagePlans.length === 1) {
-                const p = stagePlans[0];
-                lines.push('parallel(');
-                lines.push('  agent(' + quoteString(p.brief) + ', { agentType: "gsd-executor", isolation: "worktree" })');
-                lines.push(')');
-            }
-            else {
-                lines.push('parallel(');
-                for (const p of stagePlans) {
-                    lines.push('  agent(' + quoteString(p.brief) + ', { agentType: "gsd-executor", isolation: "worktree" }),');
-                }
-                // Replace trailing comma on the last agent line with nothing.
-                const lastIdx = lines.length - 1;
-                lines[lastIdx] = lines[lastIdx].replace(/,$/, '');
-                lines.push(')');
+            // parallel() takes an ARRAY OF THUNKS — `parallel(agent(…), agent(…))`
+            // 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([');
+            for (const p of stagePlans) {
+                lines.push('  () => agent(' + quoteString(p.brief) + ', ' + agentOptions(p, executorModel) + '),');
             }
+            lines.push('])');
         }
         if (wi < waves.length - 1)
             lines.push('');
@@ -393,9 +515,65 @@ 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,
+        executorModel: input.executorModel,
+    });
+    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": [