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

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-writer.cjs

@@ -250,8 +250,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/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 };