@opengsd/gsd-core 1.7.0-rc.3 → 1.7.0-rc.5

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

@@ -45,7 +45,7 @@ const configLoaderMod = require("./config-loader.cjs");
 const { loadConfig } = configLoaderMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const installProfilesMod = require("./install-profiles.cjs");
-const { readActiveProfile, loadSkillsManifest, resolveProfile, parseRequires } = installProfilesMod;
+const { readActiveProfile, loadSkillsManifest, resolveProfile, parseRequires, parseCallsAgents } = installProfilesMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const surfaceMod = require("./surface.cjs");
 const { resolveSurface } = surfaceMod;
@@ -282,22 +282,90 @@ function _loadInstalledSkillsManifest(configDir) {
     }
     return manifest;
 }
+/**
+ * #1858 — Build a skill dependency manifest from a FLAT commands/gsd-<stem>.md
+ * source layout (the Claude local project install shape, where the `gsd-`
+ * prefix is baked into each filename at the commands/ level and there is no
+ * commands/gsd/ subdir). Strips the `gsd-` prefix so stems match the nested
+ * loader's output (gsd-validate-phase.md → validate-phase, same as nested
+ * validate-phase.md).
+ *
+ * Map shape is identical to loadSkillsManifest: each stem maps to its
+ * `requires` deps (parsed via the same shared parseRequires) and carries a
+ * companion `_calls_agents_<stem>` key (parsed via parseCallsAgents) so the
+ * flat and nested paths cannot drift.
+ *
+ * Returns an empty Map when the parent directory does not exist or contains
+ * no gsd-*.md files (so _resolveManifest can use size>0 as the "flat layout
+ * present" signal and fall through to the installed-skills branch otherwise).
+ */
+function _loadFlatCommandsGsdManifest(commandsParentDir) {
+    const manifest = new Map();
+    let entries;
+    try {
+        entries = node_fs_1.default.readdirSync(commandsParentDir, { withFileTypes: true });
+    }
+    catch {
+        return manifest;
+    }
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.startsWith('gsd-'))
+            continue;
+        if (!entry.name.endsWith('.md'))
+            continue;
+        // Strip 'gsd-' prefix (4 chars) and '.md' suffix (3 chars) → stem.
+        const stem = entry.name.slice(4, -3);
+        if (!stem)
+            continue;
+        // Mirror loadSkillsManifest's try/catch structure exactly: wrap read +
+        // parse + set together so an unreadable file OR a thrown parser degrades
+        // both keys to [] (parity; closes the latent catch-scope drift a reviewer
+        // flagged — both parsers are non-throwing today, but the structural
+        // match future-proofs the "identical Map shape" contract).
+        try {
+            const content = node_fs_1.default.readFileSync(node_path_1.default.join(commandsParentDir, entry.name), 'utf8');
+            manifest.set(stem, parseRequires(content));
+            manifest.set(`_calls_agents_${stem}`, parseCallsAgents(content));
+        }
+        catch {
+            manifest.set(stem, []);
+            manifest.set(`_calls_agents_${stem}`, []);
+        }
+    }
+    return manifest;
+}
 /**
  * Resolve the skill dependency manifest for capability-state resolution.
  *
- * Resolution order (fixes #1160 — installed-runtime capability surface):
- *   1. If commandsGsdDir exists, load from source (repo-checkout behavior).
- *   2. Otherwise, fall back to installed skills at configDir/skills/gsd-[stem]/SKILL.md.
+ * Resolution order:
+ *   1. If commandsGsdDir exists, load from the nested source layout
+ *      (repo-checkout behavior: <repo>/commands/gsd/*.md).
+ *   2. #1858 — otherwise, if the flat source layout is present (gsd-<stem>.md
+ *      files in dirname(commandsGsdDir)), load from there. This is the Claude
+ *      local project install shape where commands/gsd/ does not exist but
+ *      commands/gsd-<stem>.md files do.
+ *   3. #1160 — otherwise, fall back to installed skills at
+ *      configDir/skills/gsd-[stem]/SKILL.md.
  *
- * In an installed runtime the commands/gsd source tree is absent; only the
- * skills/ layout exists. Returning an empty manifest caused resolveSurface to
- * materialise the full-sentinel to an empty Set, making every capability appear
- * unsurfaced even when the skill was physically installed.
+ * In an installed runtime both source trees are absent; only the skills/
+ * layout exists. Returning an empty manifest caused resolveSurface to
+ * materialise the full-sentinel to an empty Set, making every skill-bearing
+ * capability appear unsurfaced even when the skill was physically installed
+ * (#1160) or authored as a flat command file (#1858).
  */
 function _resolveManifest(commandsGsdDir, configDir) {
     if (node_fs_1.default.existsSync(commandsGsdDir)) {
         return loadSkillsManifest(commandsGsdDir);
     }
+    // #1858: flat source layout — gsd-<stem>.md files at dirname(commandsGsdDir).
+    // Only claim the flat branch when it actually has gsd-*.md files; otherwise
+    // fall through to the installed-skills branch (a commands/ dir with no gsd
+    // files must not shadow an installed skills/ tree).
+    const flat = _loadFlatCommandsGsdManifest(node_path_1.default.dirname(commandsGsdDir));
+    if (flat.size > 0)
+        return flat;
     return _loadInstalledSkillsManifest(configDir);
 }
 /**
@@ -334,7 +402,7 @@ function _resolveManifest(commandsGsdDir, configDir) {
  * @param raw              Whether to emit raw JSON (io.output raw mode)
  * @param _options         Reserved for future use
  */
-function resolveCapabilityRuntimeState(cwd, runtimeConfigDir, configOverride) {
+function resolveCapabilityRuntimeState(cwd, runtimeConfigDir, configOverride, runtimeOverride) {
     const warnings = [];
     // Resolve runtimeConfigDir using the canonical runtime-homes resolver.
     // When not provided, the active runtime is detected via the canonical
@@ -350,13 +418,40 @@ function resolveCapabilityRuntimeState(cwd, runtimeConfigDir, configOverride) {
         try {
             // eslint-disable-next-line @typescript-eslint/no-require-imports
             const runtimeHomes = require('./runtime-homes.cjs');
-            // eslint-disable-next-line @typescript-eslint/no-require-imports
-            const runtimeSlash = require('./runtime-slash.cjs');
-            // Detect the active runtime via GSD_RUNTIME → config.runtime → 'claude'.
-            // resolveRuntime reads config.json directly (no side effects) and returns
-            // a lowercased canonical runtime name.
-            const detectedRuntime = runtimeSlash.resolveRuntime(cwd);
-            resolvedConfigDir = runtimeHomes.getGlobalConfigDir(detectedRuntime);
+            // #2003: an explicit --runtime override bypasses the persisted-runtime
+            // fallback (GSD_RUNTIME → config.runtime → 'claude') so, e.g., a repo with
+            // persisted runtime:"codex" resolves the Claude config dir when the operator
+            // is driving from Claude Code. Canonicalize via runtime-name-policy (handles
+            // aliases like codex-app → codex); if canonicalization yields nothing, fall
+            // through to the persisted-runtime resolution below. Mirrors the update-
+            // context / effort sync precedent (read/diagnostic paths accepting both
+            // --config-dir and --runtime).
+            if (typeof runtimeOverride === 'string' && runtimeOverride.trim() !== '') {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports
+                const runtimeNamePolicy = require('./runtime-name-policy.cjs');
+                const canonical = runtimeNamePolicy.canonicalizeRuntimeName(runtimeOverride);
+                if (canonical) {
+                    resolvedConfigDir = runtimeHomes.getGlobalConfigDir(canonical);
+                }
+                else {
+                    // #2003: unknown runtime override — warn (don't silently ignore the
+                    // explicit input) and fall through to persisted-runtime resolution.
+                    // Avoids a silent-wrong-result on this diagnostic command for typos
+                    // (e.g. "cluade") or runtimes known to runtime-homes but not yet to
+                    // the alias manifest (e.g. "grok"). The warning surfaces via the
+                    // `warnings[]` channel consumed by cmdCapabilityState/cmdLoopRenderHooks.
+                    warnings.push(`--runtime "${runtimeOverride}" is not a known runtime; falling back to auto-detected/persisted runtime resolution`);
+                }
+            }
+            if (!resolvedConfigDir) {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports
+                const runtimeSlash = require('./runtime-slash.cjs');
+                // Detect the active runtime via GSD_RUNTIME → config.runtime → 'claude'.
+                // resolveRuntime reads config.json directly (no side effects) and returns
+                // a lowercased canonical runtime name.
+                const detectedRuntime = runtimeSlash.resolveRuntime(cwd);
+                resolvedConfigDir = runtimeHomes.getGlobalConfigDir(detectedRuntime);
+            }
         }
         catch {
             // Defensive fallback: use ~/.claude if the canonical resolver throws.
@@ -450,8 +545,11 @@ function resolveCapabilityRuntimeState(cwd, runtimeConfigDir, configOverride) {
         capabilities: result.capabilities,
     };
 }
-function cmdCapabilityState(cwd, runtimeConfigDir, raw, _options = {}) {
-    const result = resolveCapabilityRuntimeState(cwd, runtimeConfigDir);
+function cmdCapabilityState(cwd, runtimeConfigDir, raw, options = {}) {
+    // #2003: thread an explicit --runtime override so the config-dir resolution
+    // bypasses the persisted-runtime fallback (GSD_RUNTIME → config.runtime).
+    const runtimeOverride = typeof options['runtime'] === 'string' ? options['runtime'] : undefined;
+    const result = resolveCapabilityRuntimeState(cwd, runtimeConfigDir, undefined, runtimeOverride);
     for (const warning of result.warnings) {
         coreError(`capability state: ${warning}`);
     }
@@ -491,6 +589,7 @@ module.exports = {
     // Exported for tests
     _resolveCommandsGsdDir,
     _loadInstalledSkillsManifest,
+    _loadFlatCommandsGsdManifest,
     _resolveManifest,
     _isSafePropKey,
 };

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

@@ -709,7 +709,7 @@ const VALID_HOOK_EVENTS = new Set(['claude', 'gemini']);
 // DISTINCT from hookEvents (managed-hook dialect): extensionEvents describes the
 // plugin-owned event subset imperative hosts expose (opencode / pi); 'none' = the
 // host exposes no extension surface (engine owns the bus, e.g. VS Code).
-const VALID_EXTENSION_EVENTS = new Set(['opencode', 'pi', 'none']);
+const VALID_EXTENSION_EVENTS = new Set(['opencode', 'pi', 'hermes', 'none']);
 const VALID_SANDBOX_TIERS = new Set(['none', 'codex-agent-sandbox']);
 const VALID_ARTIFACT_KIND_NAMES = new Set(['commands', 'agents', 'skills', 'kimi-agents']);
 const VALID_ARTIFACT_NESTINGS = new Set(['flat', 'nested']);

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

@@ -77,8 +77,17 @@ function setCapabilityState(cwd, runtimeConfigDir, desired, opts) {
     const before = resolveCapabilityRuntimeState(cwd, runtimeConfigDir);
     const resolvedConfigDir = before.runtimeConfigDir;
     // ── Load registry ─────────────────────────────────────────────────────────
+    // Issue #2045 (DEFECT 2): validate against the COMPOSED overlay-aware registry
+    // (first-party ∪ accepted overlays), mirroring capability-state.cts:547-551.
+    // The frozen capability-registry.cjs only knows first-party ids, so a third-
+    // party cap failed the membership check below → "unknown capability" even
+    // though resolveCapabilityRuntimeState (the `before` snapshot, line 150) already
+    // knew about it. loadRegistry is non-throwing and first-party-wins, so a
+    // malformed overlay is skipped (never crashes the writer); a truly-unknown id
+    // is STILL rejected because it is absent from the composed capabilities map.
     // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const registry = require('./capability-registry.cjs');
+    const { loadRegistry } = require('./capability-loader.cjs');
+    const registry = loadRegistry({ includeInstalled: true, cwd, gsdHome: process.env['GSD_HOME'] });
     const capabilitiesMap = (registry['capabilities'] && typeof registry['capabilities'] === 'object' && !Array.isArray(registry['capabilities'])
         ? registry['capabilities']
         : {});
@@ -250,8 +259,18 @@ function setCapabilityState(cwd, runtimeConfigDir, desired, opts) {
             const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, resolvedConfigDir, scope);
             const commandsGsdDir = _resolveCommandsGsdDir();
             const manifest = _resolveManifest(commandsGsdDir, resolvedConfigDir);
+            // #1575: applySurface now accepts opts.resolveAttribution so surface-path
+            // agents get the same Co-Authored-By trailer as the install path. The
+            // resolver is not threaded here yet — the CLI command handler does not have
+            // 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).
             // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-            applySurface(resolvedConfigDir, layout, manifest, undefined, registry);
+            applySurface(resolvedConfigDir, layout, manifest, undefined, registry, opts?.materialize?.resolveAttribution
+                ? { resolveAttribution: opts.materialize.resolveAttribution }
+                : undefined);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);

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

@@ -37,6 +37,9 @@ const prohibition_enforcement_cjs_1 = require("./prohibition-enforcement.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const gatePredicateEval = require("./gate-predicate-evaluator.cjs");
 const { evaluatePredicate } = gatePredicateEval;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const apiCoverageMod = require("./api-coverage.cjs");
+const { detectApiIntegration, validateCoverageMatrix } = apiCoverageMod;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 function normalizePhrase(text) {
@@ -131,10 +134,13 @@ 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[^>]*)?>([\s\S]*?)<\/(?:objective|tasks?|action)>/gi;
+const XML_DECISION_TAGS_RE = /<(?:objective|tasks?|action)(?:\s[^>]{0,1000})?>((?:(?!<(?:objective|tasks?|action)[\s>])[\s\S])*?)<\/(?:objective|tasks?|action)>/gi;
 function stripCommentsAndFences(text) {
     // HTML-comment stripping stays caller-side (the seam does not strip HTML comments).
-    const htmlStripped = text.replace(/<!--[\s\S]*?-->/g, ' ');
+    // Stop-at-next-open body (ReDoS-safe, #2128); an UNCLOSED `<!--` does not match,
+    // so downstream tags are preserved (unlike a `(?:-->|$)` fallback, which would
+    // wipe to EOF and fail-close the decision-coverage gate).
+    const htmlStripped = text.replace(/<!--(?:(?!<!--)[\s\S])*?-->/g, ' ');
     // Fenced-code stripping: delegate to the canonical CommonMark-correct seam.
     // replaces the prior independent regex copy (```` ``` ``` ````  + `~~~ ~~~`).
     return (0, markdown_sectionizer_cjs_1.stripFencedCode)(htmlStripped).text;
@@ -876,6 +882,233 @@ function cmdCheckPredicate(projectDir, args, raw) {
     }
     output(result, raw, undefined);
 }
+// ─── api-coverage-verify-pre ──────────────────────────────────────────────────
+/**
+ * api-coverage.verify-pre: BLOCKING seal-time gate for the ai-integration
+ * capability (#1562). Enforces "Full API Coverage by Default — Opt Out, Never
+ * Opt In." A phase that integrates an external API/SDK/service may not seal
+ * until a COVERAGE.md matrix enumerates the surface and every non-integrated
+ * capability is an explicit, reasoned opt-out.
+ *
+ * Contract (two touch points composed into one check):
+ *   1. If COVERAGE.md exists in the phase dir → validate it (acceptance #2).
+ *      Block on any validation error (empty matrix, OPT-OUT without reason,
+ *      duplicate/empty capability).
+ *   2. If COVERAGE.md is absent → run detectApiIntegration over the phase scope
+ *      (PLAN.md body, then ROADMAP phase section as fallback). If a strong
+ *      external-API-integration signal is detected → BLOCK ("integration
+ *      detected without coverage matrix"). If no signal → PASS (treat as a
+ *      non-API phase; acceptance #4 — low false positives).
+ *
+ * The detector is the FALLBACK for the "nobody decided / forgot the matrix"
+ * case; the primary path is the plan:pre contribution prompting COVERAGE.md.
+ *
+ * Args: check api-coverage.verify-pre <phase-dir>
+ * Emits the uniform gate contract: { block, passed, message, ...details }.
+ */
+function cmdApiCoverageVerifyPre(projectDir, args, raw) {
+    const phaseArg = typeof args[2] === 'string' ? args[2] : '';
+    if (!phaseArg) {
+        error('api-coverage.verify-pre requires a phase argument: check api-coverage.verify-pre <phase-dir-or-token>', ERROR_REASON.SDK_MISSING_ARG);
+        return;
+    }
+    const pDir = planningDir(projectDir);
+    const phasesRoot = node_path_1.default.join(pDir, 'phases');
+    // SECURITY (path traversal): the phase argument is taken ONLY as a phase
+    // token — its basename — and resolved by findPhaseInternal strictly under
+    // .planning/phases/ (or a milestone archive). The raw arg is never used as a
+    // path, so `..`, absolute paths, and arbitrary directories cannot reach a
+    // file read. Mirrors cmdVerifySchemaDrift's token-match approach.
+    let token = phaseArg.replace(/\\/g, '/').split('/').filter(Boolean).pop() || '';
+    // A token like ".." or "." carries no phase identity → unresolvable.
+    if (token === '.' || token === '..')
+        token = '';
+    // Not a GSD project (no phases tree at all) → fail-open: nothing to gate.
+    if (!node_fs_1.default.existsSync(phasesRoot)) {
+        output({
+            block: false,
+            passed: true,
+            coverage_present: false,
+            detected: false,
+            message: 'api-coverage: no .planning/phases directory; gate skipped (not a GSD project layout)',
+        }, raw, undefined);
+        return;
+    }
+    // Resolve the phase dir under the contained phases root.
+    let resolvedDir = null;
+    let phaseNumber = '';
+    if (token) {
+        const found = findPhaseInternal(projectDir, token);
+        if (found && found.directory) {
+            resolvedDir = found.directory;
+            phaseNumber = found.phase_number || '';
+        }
+    }
+    if (!resolvedDir) {
+        // The phases tree EXISTS but THIS phase could not be resolved. For a
+        // BLOCKING gate, fail-closed: a missing phase dir must not silently bypass
+        // the coverage requirement. (Distinguished from "no .planning at all"
+        // above, which is a genuine non-GSD-project → pass.)
+        output({
+            block: true,
+            passed: false,
+            coverage_present: false,
+            detected: false,
+            phase_lookup_failed: true,
+            message: `api-coverage: could not resolve phase "${phaseArg}" under .planning/phases/. ` +
+                'Resolve the phase directory (or produce COVERAGE.md) before sealing.',
+        }, raw, undefined);
+        return;
+    }
+    // Defense-in-depth: the resolved dir must be inside the phases root (or a
+    // milestone archive under .planning/milestones).
+    const milestonesRoot = node_path_1.default.join(pDir, 'milestones');
+    if (!isInsideRoot(resolvedDir, phasesRoot) && !isInsideRoot(resolvedDir, milestonesRoot)) {
+        output({
+            block: true,
+            passed: false,
+            coverage_present: false,
+            detected: false,
+            message: 'api-coverage: resolved phase dir escapes .planning/ — refusing to evaluate',
+        }, raw, undefined);
+        return;
+    }
+    // (1) locate COVERAGE.md — prefer the exact name, then a single *-COVERAGE.md.
+    let coverageFile = '';
+    let suffixed = [];
+    try {
+        const entries = node_fs_1.default.readdirSync(resolvedDir, { withFileTypes: true });
+        const files = entries.filter((e) => e.isFile()).map((e) => e.name);
+        const exact = files.find((f) => /^COVERAGE\.md$/i.test(f));
+        if (exact) {
+            coverageFile = exact;
+        }
+        else {
+            suffixed = files.filter((f) => /-COVERAGE\.md$/i.test(f)).sort();
+            if (suffixed.length === 1)
+                coverageFile = suffixed[0];
+        }
+    }
+    catch {
+        // readdir failure → treat as no matrix readable; fall through to detection.
+    }
+    if (coverageFile) {
+        let matrixText;
+        try {
+            matrixText = node_fs_1.default.readFileSync(node_path_1.default.join(resolvedDir, coverageFile), 'utf8');
+        }
+        catch {
+            // COVERAGE.md exists but is unreadable (EACCES/EIO/encoding). Fail-closed
+            // with a useful message rather than a raw throw.
+            output({
+                block: true,
+                passed: false,
+                coverage_present: true,
+                message: `api-coverage: COVERAGE.md exists but is unreadable — fix file permissions/encoding before sealing`,
+            }, raw, undefined);
+            return;
+        }
+        const v = validateCoverageMatrix(matrixText);
+        if (v.valid) {
+            output({
+                block: false,
+                passed: true,
+                coverage_present: true,
+                matrix: coverageFile,
+                counts: v.counts,
+                message: `api-coverage: matrix present (${v.counts.surface} capabilities, ${v.counts.optout} opt-out)`,
+            }, raw, undefined);
+            return;
+        }
+        // Fixed-template message (no raw cell content echoed into the LLM-facing
+        // message). The structured `errors` array is safe (row-indexed, no cell
+        // values) and travels as data for tooling that wants detail.
+        output({
+            block: true,
+            passed: false,
+            coverage_present: true,
+            matrix: coverageFile,
+            error_count: v.errors.length,
+            errors: v.errors,
+            message: `api-coverage: COVERAGE.md has ${v.errors.length} problem(s) — fix the matrix (every capability INTEGRATE or OPT-OUT with a reason) before sealing`,
+        }, raw, undefined);
+        return;
+    }
+    if (suffixed.length > 1) {
+        output({
+            block: true,
+            passed: false,
+            coverage_present: false,
+            message: `api-coverage: multiple *-COVERAGE.md files found (${suffixed.length}) — consolidate into one COVERAGE.md before sealing`,
+        }, raw, undefined);
+        return;
+    }
+    // (2) no matrix — detect whether this phase integrates an external API.
+    const scopeText = readPhaseScope(projectDir, resolvedDir, phaseNumber);
+    const detection = detectApiIntegration(scopeText);
+    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.
+        const signals = detection.signals.map((s) => ({ verb: s.verb, noun: s.noun }));
+        output({
+            block: true,
+            passed: false,
+            coverage_present: false,
+            detected: true,
+            signals,
+            message: 'api-coverage: external-API integration detected without a coverage matrix. ' +
+                'Produce COVERAGE.md enumerating the API surface (every capability INTEGRATE or ' +
+                'OPT-OUT with a reason) before sealing. Full coverage is the default.',
+        }, raw, undefined);
+        return;
+    }
+    output({
+        block: false,
+        passed: true,
+        coverage_present: false,
+        detected: false,
+        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.
+ */
+function readPhaseScope(projectDir, phaseDir, phaseNumber) {
+    const chunks = [];
+    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();
+        for (const p of plans) {
+            chunks.push(node_fs_1.default.readFileSync(node_path_1.default.join(phaseDir, p), 'utf8'));
+        }
+    }
+    catch {
+        // ignore — fall through to roadmap
+    }
+    if (chunks.join('').trim().length > 0)
+        return chunks.join('\n\n');
+    // 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).
+    if (phaseNumber) {
+        try {
+            const section = getRoadmapPhaseWithFallback(projectDir, phaseNumber);
+            if (section)
+                return section;
+        }
+        catch {
+            // ignore
+        }
+    }
+    return '';
+}
 function routeCheckCommand({ args, cwd, raw }) {
     // Normalize dots to hyphens in the subcommand so both forms are accepted.
     // This makes `check.query = "ui.plan-gate"` (dotted form in capability.json gates)
@@ -905,6 +1138,12 @@ function routeCheckCommand({ args, cwd, raw }) {
         cmdGapAnalysisPlanPost(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.
+        cmdApiCoverageVerifyPre(cwd, args, raw);
+        return;
+    }
     if (subcommand === 'tdd-review-checkpoint') {
         cmdTddReviewCheckpoint(cwd, args, raw);
         return;
@@ -945,7 +1184,7 @@ function routeCheckCommand({ args, cwd, raw }) {
         (0, prohibition_enforcement_cjs_1.routeProhibitionEnforcement)(args, raw);
         return;
     }
-    error('Unknown check subcommand. Available: 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-schema-drift, verify-codebase-drift', ERROR_REASON.SDK_UNKNOWN_COMMAND);
 }
 module.exports = {
     routeCheckCommand,

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

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Claude orchestration command router — CLI dispatcher for
+ * `gsd-tools claude-orchestration <subcommand>`.
+ *
+ * #1143 — thin CLI adapter over the pure `claude-orchestration.cjs` module.
+ * Lets execute-phase (or any orchestrator) invoke the Workflow-backend
+ * detection and the Workflow-script emitter through the standard capability
+ * command surface (ADR-959) instead of a bare `require()`.
+ *
+ * Router signature: { args, cwd, raw, error } — identical to the other host
+ * routers; discovered by dispatchCapabilityCommand via the registry's
+ * commandFamilies index.
+ *
+ * Subcommands:
+ *   detect-backend [--runtime <id>] [--agent-sdk-version <ver>] [--no-nested-dispatch]
+ *       Resolves whether the Workflow backend should activate. `--runtime`
+ *       defaults to the GSD_RUNTIME env var (or 'unknown'). Reads the
+ *       `claude_orchestration.*` keys from .planning/config.json. Emits
+ *       { available, backend, reason }.
+ *
+ *   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[] }] }] }.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+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 CAPABLE_HOST = { dispatch: { nested: true, background: true } };
+function usage(error) {
+    error('Usage: gsd-tools claude-orchestration <detect-backend|emit-workflow> [...]\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>]');
+}
+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.
+ */
+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.
+    let claudeSlice = {};
+    try {
+        const loaded = configLoader.loadConfig(cwd);
+        const slice = loaded['claude_orchestration'];
+        if (slice && typeof slice === 'object' && !Array.isArray(slice)) {
+            claudeSlice = slice;
+        }
+    }
+    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];
+    }
+    const result = detectWorkflowBackend({ runtimeId, hostIntegration, config: flatConfig, agentSdkVersion });
+    output(result, raw);
+}
+/**
+ * Emit a Workflow script from a wave/plan manifest file.
+ */
+function cmdEmitWorkflow(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('emit-workflow requires --waves <path>');
+        return;
+    }
+    if (!runId) {
+        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 budgetTokens = budgetRaw !== undefined ? parseInt(budgetRaw, 10) : undefined;
+    const budget = (typeof budgetTokens === 'number' && !Number.isNaN(budgetTokens)) ? budgetTokens : undefined;
+    const result = emitWorkflowScript({
+        phaseDir,
+        runId,
+        waves: waves,
+        budgetTokens: budget,
+    });
+    if (!result.ok) {
+        error('emit-workflow: ' + result.reason);
+        return;
+    }
+    output({ script: result.script, summary: result.summary }, raw);
+}
+function routeClaudeOrchestrationCommand(opts) {
+    const { args, cwd, raw, error } = opts;
+    // args[0] is the family ('claude-orchestration'); the subcommand is args[1].
+    const subcommand = args[1];
+    if (subcommand === 'detect-backend') {
+        cmdDetectBackend(args, cwd, raw);
+    }
+    else if (subcommand === 'emit-workflow') {
+        cmdEmitWorkflow(args, cwd, raw, error);
+    }
+    else {
+        usage(error);
+    }
+}
+module.exports = { routeClaudeOrchestrationCommand };