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

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

@@ -0,0 +1,404 @@
+"use strict";
+/**
+ * Claude Orchestration Capability — Workflow-tool backend detection + emitter
+ *
+ * #1143 — adopts Claude Code's Workflow tool (the engine behind `/effort ultracode`)
+ * as an optional, runtime-gated parallel-execution backend for the GSD loop.
+ *
+ * This module is the pure, testable core of the capability. It owns two seams:
+ *
+ *   detectWorkflowBackend({ runtimeId, hostIntegration, config, agentSdkVersion })
+ *     → { available: boolean, backend: 'workflow'|'inline', reason: string }
+ *     Fail-closed: every miss degrades to `inline` (today's behaviour), so the
+ *     core loop is byte-identical unless every gate opens. This is criteria 3 + 6.
+ *
+ *   emitWorkflowScript({ phaseDir, waves, runId, budgetTokens? })
+ *     → { 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' })`,
+ *       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.
+ *
+ * Design laws:
+ *   - Gall's Law: ship a small working slice that composes existing primitives
+ *     (gsd-executor + worktree isolation) rather than reinventing them.
+ *   - Greenspun's Tenth Rule (cited in #1143): adopt the Workflow tool's
+ *     barrier/pipeline/budget/resume semantics instead of hand-rolling them.
+ *   - Postel's Law: liberal in input (missing fields → inline), conservative in
+ *     output (workflow only when every gate opens).
+ *   - Fail-closed: an unknown version, a missing descriptor, or a disabled
+ *     toggle all resolve to `inline`, never to `workflow`.
+ *
+ * Zero external dependencies. Pure functions. Never throws on bad input.
+ */
+// ─── Constants ────────────────────────────────────────────────────────────────
+/**
+ * The Agent SDK version that introduced the Workflow tool (#1143 prior art).
+ * Used as the default floor when config does not override it. A runtime reporting
+ * an agentSdkVersion below this cannot host the Workflow backend.
+ */
+const WORKFLOW_TOOL_FLOOR_VERSION = '0.3.149';
+/** Closed enum for the `claude_orchestration.execution_backend` config key. */
+const BACKEND_VALUES = new Set(['auto', 'workflow', 'inline']);
+/** Only this runtime can host the Workflow tool (Claude Code / Agent SDK). */
+const WORKFLOW_RUNTIME = 'claude';
+// ─── Semver helpers ───────────────────────────────────────────────────────────
+/** Official-ish strict SemVer 2.0.0 numeric triple (+ optional pre/build). */
+const SEMVER_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+/** True for a syntactically valid semver string. */
+function isValidSemver(s) {
+    return typeof s === 'string' && SEMVER_RE.test(s);
+}
+/**
+ * Compare two semver strings.
+ * Returns -1/0/1 in the usual sense. Garbage in either position → -1 (fail-closed:
+ * an unparseable version is treated as "less than" any real floor, so detection
+ * never accidentally enables the preview backend on an unknown SDK).
+ *
+ * Pre-release/build metadata are ignored for the comparison — only the numeric
+ * major.minor.patch triple participates, matching how the Workflow-tool floor is
+ * specified (a plain "0.3.149").
+ */
+function compareSemver(a, b) {
+    if (!isValidSemver(a) || !isValidSemver(b))
+        return -1;
+    // Split numeric triple from pre-release/build metadata.
+    const parseTriple = (s) => {
+        const core = s.split('-')[0].split('+')[0].split('.');
+        return [parseInt(core[0], 10), parseInt(core[1], 10), parseInt(core[2], 10)];
+    };
+    const hasPre = (s) => s.indexOf('-') !== -1;
+    const preIdentifiers = (s) => (s.split('-')[1] || '').split('+')[0].split('.').filter((x) => x.length > 0);
+    const am = parseTriple(a);
+    const bm = parseTriple(b);
+    for (let i = 0; i < 3; i++) {
+        if (am[i] < bm[i])
+            return -1;
+        if (am[i] > bm[i])
+            return 1;
+    }
+    // Numeric triple is equal. SemVer 2.0.0 §11 precedence:
+    //   - a version WITH a pre-release tag is LOWER than the same triple WITHOUT one
+    //     (keeps the floor fail-closed for pre-release builds of the GA floor);
+    //   - two pre-releases of the same triple are ordered by their dot-separated
+    //     identifiers (numeric < alphanumeric; numeric compared numerically,
+    //     alphanumeric lexically; fewer identifiers < more).
+    const aPre = hasPre(a);
+    const bPre = hasPre(b);
+    if (aPre && !bPre)
+        return -1;
+    if (!aPre && bPre)
+        return 1;
+    if (aPre && bPre) {
+        const ai = preIdentifiers(a);
+        const bi = preIdentifiers(b);
+        const len = Math.min(ai.length, bi.length);
+        for (let i = 0; i < len; i++) {
+            const ax = ai[i];
+            const bx = bi[i];
+            const aNum = /^\d+$/.test(ax);
+            const bNum = /^\d+$/.test(bx);
+            if (aNum && bNum) {
+                const an = parseInt(ax, 10);
+                const bn = parseInt(bx, 10);
+                if (an < bn)
+                    return -1;
+                if (an > bn)
+                    return 1;
+            }
+            else if (aNum && !bNum) {
+                return -1; // numeric identifiers always lower than alphanumeric
+            }
+            else if (!aNum && bNum) {
+                return 1;
+            }
+            else {
+                if (ax < bx)
+                    return -1;
+                if (ax > bx)
+                    return 1;
+            }
+        }
+        if (ai.length < bi.length)
+            return -1;
+        if (ai.length > bi.length)
+            return 1;
+    }
+    return 0;
+}
+/** Inline result shorthand. */
+function inline(reason, available = false) {
+    return { available, backend: 'inline', reason };
+}
+/**
+ * Resolve whether the Workflow-tool backend should activate.
+ *
+ * Gate ladder (all must pass for `workflow`; first miss wins, fail-closed):
+ *   1. capability enabled (claude_orchestration.enabled truthy)
+ *   2. runtime is Claude (the only runtime that exposes the Workflow tool)
+ *   3. execution_backend !== 'inline'
+ *   4. host descriptor signals nested+background dispatch (Workflow-tool capable)
+ *   5. agentSdkVersion is a known, valid semver
+ *   6. agentSdkVersion >= the configured floor (default WORKFLOW_TOOL_FLOOR_VERSION)
+ *   7. execution_backend === 'workflow' OR 'auto' (both reach here; 'inline' exited at 3)
+ *
+ * Never throws. Destructures defensively.
+ */
+function detectWorkflowBackend(input) {
+    if (input === null || input === undefined || typeof input !== 'object') {
+        return inline('capability_disabled');
+    }
+    const cfg = (input.config !== null && input.config !== undefined && typeof input.config === 'object')
+        ? input.config
+        : {};
+    // 1. capability must be opted in (default-off — ships disabled).
+    if (!cfg['claude_orchestration.enabled']) {
+        return inline('capability_disabled');
+    }
+    // 2. only Claude can host the Workflow tool.
+    if (input.runtimeId !== WORKFLOW_RUNTIME) {
+        return inline('runtime_not_claude');
+    }
+    // 3. explicit inline opt-out short-circuits.
+    let backendRaw = cfg['claude_orchestration.execution_backend'];
+    if (typeof backendRaw !== 'string' || !BACKEND_VALUES.has(backendRaw)) {
+        backendRaw = 'auto';
+    }
+    if (backendRaw === 'inline') {
+        return inline('backend_inline');
+    }
+    // 4. the host dispatch descriptor must be the nesting-capable Claude-Code shape
+    //    (a proxy for Workflow-tool presence). This is Claude-specific and already
+    //    gated at step 2; `background:true` alone is true on several non-Claude hosts,
+    //    so the proxy is only meaningful after the runtime check above. Note: this is
+    //    NOT the canonical `shouldFlattenDispatch` rule (which keys on
+    //    `backgroundDispatch`); the Workflow backend works precisely because a single
+    //    tool-call orchestrates internally, sidestepping the backgroundDispatch:false
+    //    limitation. Missing/false/foreign descriptor → fail-closed.
+    const hi = input.hostIntegration;
+    if (hi === null || hi === undefined || typeof hi !== 'object' || Array.isArray(hi)) {
+        return inline('workflow_tool_unavailable');
+    }
+    const dispatch = hi.dispatch;
+    if (typeof dispatch !== 'object' || dispatch === null || Array.isArray(dispatch)) {
+        return inline('workflow_tool_unavailable');
+    }
+    const nested = dispatch['nested'];
+    const background = dispatch['background'];
+    if (nested !== true || background !== true) {
+        return inline('workflow_tool_unavailable');
+    }
+    // 5. an unknown agentSdkVersion cannot be trusted to meet the floor.
+    if (!isValidSemver(input.agentSdkVersion)) {
+        return inline('agent_sdk_version_unknown');
+    }
+    // 6. version floor (config override > default constant).
+    const floorRaw = cfg['claude_orchestration.min_agent_sdk_version'];
+    const floor = typeof floorRaw === 'string' && isValidSemver(floorRaw) ? floorRaw : WORKFLOW_TOOL_FLOOR_VERSION;
+    if (compareSemver(input.agentSdkVersion, floor) < 0) {
+        return inline('agent_sdk_version_below_floor');
+    }
+    // 7. auto/workflow both reach the workflow backend once every gate passes.
+    return { available: true, backend: 'workflow', reason: 'workflow_backend_active' };
+}
+/**
+ * Partition a wave's plans into a near-minimal number of sequential stages (via
+ * greedy first-fit — not guaranteed optimal for arbitrary overlap graphs, but
+ * correct: no two plans sharing a file ever cohabit a stage) such that no two
+ * plans in the same stage share a modified file. Each plan goes into the earliest
+ * stage where it does not overlap any plan already there.
+ *
+ * A plan with an EMPTY files_modified set declares no files; it overlaps nothing
+ * and coalesces into stage 0 (same behavior as the inline path, which also cannot
+ * guard against undeclared concurrent writes — declare filesModified accurately).
+ *
+ * This is the same overlap rule execute-phase applies inline — the only difference
+ * is the execution vehicle (Workflow `parallel()` vs one-agent-per-message).
+ */
+function partitionStages(plans) {
+    const stages = [];
+    for (const plan of plans) {
+        const fileSet = new Set(plan.files_modified);
+        let placed = false;
+        for (const stage of stages) {
+            let overlap = false;
+            for (const f of fileSet) {
+                if (stage.files.has(f)) {
+                    overlap = true;
+                    break;
+                }
+            }
+            if (!overlap) {
+                stage.plans.push(plan);
+                for (const f of fileSet)
+                    stage.files.add(f);
+                placed = true;
+                break;
+            }
+        }
+        if (!placed) {
+            stages.push({ plans: [plan], files: new Set(fileSet) });
+        }
+    }
+    return stages.map((s) => s.plans.map((p) => p.id));
+}
+/**
+ * Quote a free-text value for safe embedding as a JavaScript/Workflow double-quoted
+ * string literal. Uses JSON.stringify so every JS-relevant escape (backslash, quote,
+ * newline, tab, NUL, U+2028/U+2029, all control chars) is handled by the language
+ * itself — there is no hand-rolled escape table to drift. Returns the value already
+ * wrapped in its surrounding quotes.
+ */
+function quoteString(s) {
+    return JSON.stringify(s);
+}
+/**
+ * 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
+ * character that could terminate a comment line (`\n`/`\r`), break out of a
+ * string literal (`"` / `\`), or smuggle a NUL/control sequence. Used for
+ * `phaseDir`, `runId`, `wave.id`, and `plan.id`, which are identifiers/paths and
+ * must never legitimately contain such characters. Rejecting them at validation
+ * (rather than silently flattening) keeps the emitted script faithful to input.
+ */
+const UNSCRIPTABLE_CHAR_RE = /[\r\n"\\\x00-\x1f\x7f\u2028\u2029]/;
+function isScriptableIdentifier(s) {
+    if (typeof s !== 'string' || s.length === 0)
+        return false;
+    return !UNSCRIPTABLE_CHAR_RE.test(s);
+}
+/**
+ * Emit a Workflow script mapping the phase's wave/plan model onto Workflow
+ * primitives. Pure and deterministic: identical input yields an identical string.
+ *
+ * Returns ok:false (never throws) on invalid input — empty waves, missing runId,
+ * a wave with no plans, etc.
+ */
+function emitWorkflowScript(input) {
+    if (input === null || input === undefined || typeof input !== 'object') {
+        return { ok: false, reason: 'invalid_input' };
+    }
+    const { phaseDir, waves, runId } = 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).
+    if (!isScriptableIdentifier(phaseDir)) {
+        return { ok: false, reason: 'phaseDir must be a non-empty string without newlines/quotes/backslash/control chars' };
+    }
+    if (!isScriptableIdentifier(runId)) {
+        return { ok: false, reason: 'runId must be a non-empty string without newlines/quotes/backslash/control chars' };
+    }
+    if (!Array.isArray(waves) || waves.length === 0) {
+        return { ok: false, reason: 'waves must be a non-empty array' };
+    }
+    for (let i = 0; i < waves.length; i++) {
+        const w = waves[i];
+        if (w === null || typeof w !== 'object' || typeof w.id !== 'string') {
+            return { ok: false, reason: 'waves[' + i + '] must be { id, plans: non-empty[] }' };
+        }
+        if (!isScriptableIdentifier(w.id)) {
+            return { ok: false, reason: 'waves[' + i + '].id must not contain newlines/quotes/backslash/control chars' };
+        }
+        if (!Array.isArray(w.plans) || w.plans.length === 0) {
+            return { ok: false, reason: 'waves[' + i + '] must have a non-empty plans array' };
+        }
+        const seenIds = new Set();
+        for (let j = 0; j < w.plans.length; j++) {
+            const p = w.plans[j];
+            if (p === null || typeof p !== 'object' || typeof p.id !== 'string' || typeof p.brief !== 'string' || !Array.isArray(p.files_modified)) {
+                return { ok: false, reason: 'waves[' + i + '].plans[' + j + '] must be { id, brief, files_modified[] }' };
+            }
+            if (!isScriptableIdentifier(p.id)) {
+                return { ok: false, reason: 'waves[' + i + '].plans[' + j + '].id must not contain newlines/quotes/backslash/control chars' };
+            }
+            if (seenIds.has(p.id)) {
+                return { ok: false, reason: 'waves[' + i + '] has duplicate plan id "' + p.id + '"' };
+            }
+            seenIds.add(p.id);
+            for (const f of p.files_modified) {
+                if (typeof f !== 'string' || f.length === 0) {
+                    return { ok: false, reason: 'waves[' + i + '].plans[' + j + '].files_modified entries must be non-empty strings' };
+                }
+            }
+        }
+    }
+    const budgetTokens = (typeof input.budgetTokens === 'number' && Number.isFinite(input.budgetTokens) && input.budgetTokens > 0)
+        ? Math.floor(input.budgetTokens)
+        : null;
+    const lines = [];
+    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) + ')');
+    if (budgetTokens !== null) {
+        lines.push('budget(' + budgetTokens + ')');
+    }
+    lines.push('');
+    const stagesByWave = [];
+    let totalPlans = 0;
+    for (let wi = 0; wi < waves.length; wi++) {
+        const wave = waves[wi];
+        const stages = partitionStages(wave.plans);
+        stagesByWave.push(stages);
+        totalPlans += wave.plans.length;
+        lines.push('// 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).
+            const stagePlans = stagePlanIds.map((id) => wave.plans.find((p) => p.id === id));
+            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(')');
+            }
+        }
+        if (wi < waves.length - 1)
+            lines.push('');
+    }
+    lines.push('// Each agent writes SUMMARY.md on its worktree branch; commits land there');
+    lines.push('// and are merged by the orchestrator exactly as in inline wave dispatch.');
+    const script = lines.join('\n');
+    return {
+        ok: true,
+        script,
+        summary: {
+            waves: waves.length,
+            plans: totalPlans,
+            stagesByWave,
+            resumeRunId: runId,
+            budgetTokens,
+        },
+    };
+}
+module.exports = {
+    detectWorkflowBackend,
+    emitWorkflowScript,
+    compareSemver,
+    isValidSemver,
+    WORKFLOW_TOOL_FLOOR_VERSION,
+    BACKEND_VALUES,
+    WORKFLOW_RUNTIME,
+};

package/gsd-core/bin/lib/clusters.cjs

@@ -22,6 +22,7 @@ exports.CLUSTERS = Object.freeze({
     core_loop: Object.freeze([
         'next',
         'new-project',
+        'onboard',
         'discuss-phase',
         'plan-phase',
         'execute-phase',

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

@@ -283,6 +283,14 @@ exports.INIT_COMMAND_ALIASES = [
         "subcommand": "new-milestone",
         "mutation": false
     },
+    {
+        "canonical": "init.onboard",
+        "aliases": [
+            "init onboard"
+        ],
+        "subcommand": "onboard",
+        "mutation": false
+    },
     {
         "canonical": "init.quick",
         "aliases": [

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

@@ -39,6 +39,10 @@ function routeInitCommand({ init, args, cwd, raw, error }) {
             },
             'new-project': () => init.cmdInitNewProject(cwd, raw),
             'new-milestone': () => init.cmdInitNewMilestone(cwd, raw),
+            onboard: () => {
+                const namedArgs = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, [], ['fast', 'text']);
+                init.cmdInitOnboard(cwd, raw, { fast: namedArgs['fast'], text: namedArgs['text'] });
+            },
             quick: () => init.cmdInitQuick(cwd, args.slice(2).join(' '), raw),
             'ingest-docs': () => init.cmdInitIngestDocs(cwd, raw),
             resume: () => init.cmdInitResume(cwd, raw),

package/gsd-core/bin/lib/init.cjs

@@ -54,6 +54,9 @@ const { checkAgentsInstalled } = agentInstallCheck;
 const gitBaseBranch = require("./git-base-branch.cjs");
 const { gitWorktreeInfoInternal } = gitBaseBranch;
 const resolution_cjs_1 = require("./resolution.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- onboard-projection.cjs is an export= CommonJS module
+const onboardProjection = require("./onboard-projection.cjs");
+const { REQUIRED_CODEBASE_MAP_FILES, buildOnboardProjection, hasCodeFilesInternal, hasPackageFileInternal, listCodebaseMapFiles, } = onboardProjection;
 const { output, error } = io;
 const { loadConfig, loadConfigResolved } = configLoader;
 const { resolveModelInternal, resolveGranularityInternal, assertValidGranularityOverride } = modelResolver;
@@ -479,84 +482,23 @@ function cmdInitNewProject(cwd, raw) {
     const hasFirecrawl = !!(process.env['FIRECRAWL_API_KEY'] || node_fs_1.default.existsSync(firecrawlKeyFile));
     const exaKeyFile = node_path_1.default.join(homedir, '.gsd', 'exa_api_key');
     const hasExaSearch = !!(process.env['EXA_API_KEY'] || node_fs_1.default.existsSync(exaKeyFile));
-    let hasCode = false;
-    let hasPackageFile = false;
-    try {
-        const codeExtensions = new Set([
-            '.ts', '.js', '.py', '.go', '.rs', '.swift', '.java',
-            '.kt', '.kts',
-            '.c', '.cpp', '.h',
-            '.cs',
-            '.rb',
-            '.php',
-            '.dart',
-            '.m', '.mm',
-            '.scala',
-            '.groovy',
-            '.lua',
-            '.r', '.R',
-            '.zig',
-            '.ex', '.exs',
-            '.clj',
-        ]);
-        const skipDirs = new Set([
-            'node_modules', '.git', '.planning', '.claude', '.codex',
-            '__pycache__', 'target', 'dist', 'build',
-        ]);
-        function findCodeFiles(dir, depth) {
-            if (depth > 3)
-                return false;
-            let entries;
-            try {
-                entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
-            }
-            catch {
-                return false;
-            }
-            for (const entry of entries) {
-                if (entry.isFile() && codeExtensions.has(node_path_1.default.extname(entry.name)))
-                    return true;
-                if (entry.isDirectory() && !skipDirs.has(entry.name)) {
-                    if (findCodeFiles(node_path_1.default.join(dir, entry.name), depth + 1))
-                        return true;
-                }
-            }
-            return false;
-        }
-        hasCode = findCodeFiles(cwd, 0);
-    }
-    catch {
-        /* intentionally empty — best-effort detection */
-    }
-    hasPackageFile =
-        pathExistsInternal(cwd, 'package.json') ||
-            pathExistsInternal(cwd, 'requirements.txt') ||
-            pathExistsInternal(cwd, 'Cargo.toml') ||
-            pathExistsInternal(cwd, 'go.mod') ||
-            pathExistsInternal(cwd, 'Package.swift') ||
-            pathExistsInternal(cwd, 'build.gradle') ||
-            pathExistsInternal(cwd, 'build.gradle.kts') ||
-            pathExistsInternal(cwd, 'pom.xml') ||
-            pathExistsInternal(cwd, 'Gemfile') ||
-            pathExistsInternal(cwd, 'composer.json') ||
-            pathExistsInternal(cwd, 'pubspec.yaml') ||
-            pathExistsInternal(cwd, 'CMakeLists.txt') ||
-            pathExistsInternal(cwd, 'Makefile') ||
-            pathExistsInternal(cwd, 'build.zig') ||
-            pathExistsInternal(cwd, 'mix.exs') ||
-            pathExistsInternal(cwd, 'project.clj');
+    const hasCode = hasCodeFilesInternal(cwd);
+    const hasPackageFile = hasPackageFileInternal(cwd);
+    const isBrownfield = hasCode || hasPackageFile;
+    const codebaseMapFiles = listCodebaseMapFiles(cwd);
+    const hasCodebaseMap = codebaseMapFiles.length === REQUIRED_CODEBASE_MAP_FILES.length;
     const result = {
         researcher_model: resolveModelInternal(cwd, 'gsd-project-researcher'),
         synthesizer_model: resolveModelInternal(cwd, 'gsd-research-synthesizer'),
         roadmapper_model: resolveModelInternal(cwd, 'gsd-roadmapper'),
         commit_docs: config.commit_docs,
         project_exists: pathExistsInternal(cwd, '.planning/PROJECT.md'),
-        has_codebase_map: pathExistsInternal(cwd, '.planning/codebase'),
+        has_codebase_map: hasCodebaseMap,
         planning_exists: pathExistsInternal(cwd, '.planning'),
         has_existing_code: hasCode,
         has_package_file: hasPackageFile,
-        is_brownfield: hasCode || hasPackageFile,
-        needs_codebase_map: (hasCode || hasPackageFile) && !pathExistsInternal(cwd, '.planning/codebase'),
+        is_brownfield: isBrownfield,
+        needs_codebase_map: isBrownfield && !hasCodebaseMap,
         ...getInitGitState(cwd),
         brave_search_available: hasBraveSearch,
         firecrawl_available: hasFirecrawl,
@@ -656,6 +598,19 @@ function cmdInitIngestDocs(cwd, raw) {
     };
     output(withProjectRoot(cwd, result), raw);
 }
+function cmdInitOnboard(cwd, raw, options = {}) {
+    const config = loadConfig(cwd);
+    const workflowConfig = (config.workflow ?? {});
+    const result = {
+        ...buildOnboardProjection(cwd, {
+            commitDocs: !!config.commit_docs,
+            fast: options['fast'] === true,
+            textMode: options['text'] === true || !!config.text_mode || !!workflowConfig['text_mode'],
+        }),
+        ...getInitGitState(cwd),
+    };
+    output(withProjectRoot(cwd, result), raw);
+}
 function cmdInitResume(cwd, raw) {
     const config = loadConfig(cwd);
     let interruptedAgentId = null;
@@ -2099,6 +2054,7 @@ module.exports = {
     cmdInitNewMilestone,
     cmdInitQuick,
     cmdInitIngestDocs,
+    cmdInitOnboard,
     cmdInitResume,
     cmdInitVerifyWork,
     cmdInitPhaseOp,

package/gsd-core/bin/lib/install-engine.cjs

@@ -222,7 +222,7 @@ function migrateLegacyDevPreferencesToSkill(targetDir, saved, runtime, scope = '
  *   - agents: write as-is (files already carry their own `gsd-` prefix).
  * For kimi-agents kind: recursively copy generated YAML/prompt files.
  */
-function _copyStaged(stagedDir, destDir, kind, configDir) {
+function _copyStaged(stagedDir, destDir, kind, configDir, runtime) {
     // Defense-in-depth: verify destDir is within the install root even if the
     // upstream assertDestWithinConfigHome check was somehow bypassed. This guards
     // the actual write site against any future call-site drift.
@@ -275,8 +275,11 @@ function _copyStaged(stagedDir, destDir, kind, configDir) {
         const stem = entry.name.slice(0, -3); // strip .md
         let destName;
         if (kind.kind === 'agents') {
-            // Agent files already carry the gsd- prefix in the source dir
-            destName = entry.name;
+            // Agent files already carry the gsd- prefix in the source dir.
+            // #1575: copilot agents get .agent.md suffix (mirrors inline loop line ~9118).
+            destName = runtime === 'copilot'
+                ? entry.name.replace(/\.md$/, '.agent.md')
+                : entry.name;
         }
         else if (namespacedByDir) {
             // Directory is the namespace; don't double-prefix the filename
@@ -571,7 +574,7 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
                     }
                 }
                 _removeGsdEntries(dest, kind);
-                _copyStaged(item.sourceDir, dest, kind, configDir);
+                _copyStaged(item.sourceDir, dest, kind, configDir, runtime);
                 // Restore user-owned dirs after the prune+copy
                 for (const [dirName, snap] of toPreserve) {
                     _restoreDir(node_path_1.default.join(dest, dirName), snap);
@@ -581,7 +584,7 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
                 // For non-skills kinds (commands, agents): no user content to preserve;
                 // just prune stale gsd-* entries and copy new ones.
                 _removeGsdEntries(dest, kind);
-                _copyStaged(item.sourceDir, dest, kind, configDir);
+                _copyStaged(item.sourceDir, dest, kind, configDir, runtime);
             }
         }
     }

package/gsd-core/bin/lib/install-profiles.cjs

@@ -42,6 +42,7 @@ const PROFILES = Object.freeze({
     standard: Object.freeze([
         // Core loop
         'new-project',
+        'onboard',
         'discuss-phase',
         'plan-phase',
         'execute-phase',
@@ -819,6 +820,7 @@ module.exports = {
     writeActiveProfile,
     // Shared internals
     parseRequires,
+    parseCallsAgents,
     cleanupStagedSkills,
     // Back-compat / deprecated
     MINIMAL_SKILL_ALLOWLIST,

package/gsd-core/bin/lib/loop-resolver.cjs

@@ -415,6 +415,12 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
     const runtimeConfigDir = typeof options['configDir'] === 'string'
         ? options['configDir']
         : undefined;
+    // #2003: thread an explicit --runtime override into the capability-state
+    // resolver so the config-dir resolution bypasses the persisted-runtime
+    // fallback (GSD_RUNTIME → config.runtime). Without this, a repo with persisted
+    // runtime:"codex" resolves the config dir to ~/.codex and execute:post /
+    // verify:post hooks silently no-op when the operator drives from Claude Code.
+    const runtimeOverride = typeof options['runtime'] === 'string' ? options['runtime'] : undefined;
     // Load the config snapshot ONCE and share it with both the capability-state
     // resolver (via configOverride) and loop-hook resolution, so federated keys
     // present in loadConfig resolve identically for `active` and for hook when/
@@ -429,7 +435,7 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
     catch {
         config = {};
     }
-    const state = resolveCapabilityRuntimeState(cwd, runtimeConfigDir, config);
+    const state = resolveCapabilityRuntimeState(cwd, runtimeConfigDir, config, runtimeOverride);
     // Load overlay-aware registry (ADR-1244 D2 wiring) so installed third-party
     // capabilities are visible to loop rendering exactly like first-party ones.
     // eslint-disable-next-line @typescript-eslint/no-require-imports