@opengsd/gsd-core 1.5.0-rc.1 → 1.5.0-rc.2

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

@@ -140,6 +140,26 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
                 phase.cmdPhaseComplete(cwd, args[2], raw);
                 return { ok: true, data: null };
             },
+            'uat-passed': (_ctx) => {
+                let requireVerification = false;
+                const positional = [];
+                for (const token of args.slice(2)) {
+                    if (token === '--require-verification') {
+                        requireVerification = true;
+                    }
+                    else if (token === '--raw') {
+                        // --raw is handled by the outer CLI layer; accepted here silently
+                    }
+                    else if (token.startsWith('--')) {
+                        return makeInvalidArgs(token, `phase uat-passed does not support ${token}`);
+                    }
+                    else {
+                        positional.push(token);
+                    }
+                }
+                phase.cmdPhaseUatPassed(cwd, positional[0], raw, { policy: { requireVerification } });
+                return { ok: true, data: null };
+            },
         },
     };
     // ── Build manifest (available subcommands for UnknownCommand detection) ─────

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

@@ -32,6 +32,9 @@ const stateMod = require("./state.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- uat-predicate.cjs is an export= CommonJS module
+const uatPredicate = require("./uat-predicate.cjs");
+const { evaluateUatPassed } = uatPredicate;
 const { escapeRegex, loadConfig, normalizePhaseName, phaseMarkdownRegexSource, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone, toPosixPath, output, error, readSubdirectories, phaseTokenMatches, ERROR_REASON, } = core;
 const { planningDir, withPlanningLock } = planningWorkspace;
 const { extractFrontmatter } = frontmatterMod;
@@ -1292,6 +1295,19 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
     };
     output(result, raw);
 }
+function cmdPhaseUatPassed(cwd, phaseNum, raw, opts = {}) {
+    if (!phaseNum) {
+        error('phase number required for phase uat-passed');
+    }
+    const phaseInfoRaw = findPhaseInternal(cwd, phaseNum);
+    if (!phaseInfoRaw) {
+        error(`Phase ${phaseNum} not found`);
+    }
+    const phaseInfo = phaseInfoRaw;
+    const phaseFullDir = node_path_1.default.join(cwd, phaseInfo['directory']);
+    const report = evaluateUatPassed(phaseFullDir, { policy: opts.policy });
+    output({ phase: phaseNum, ...report }, raw);
+}
 module.exports = {
     cmdPhasesList,
     cmdPhaseNextDecimal,
@@ -1303,5 +1319,6 @@ module.exports = {
     cmdPhaseInsert,
     cmdPhaseRemove,
     cmdPhaseComplete,
+    cmdPhaseUatPassed,
     computeDependencyLevels,
 };

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

@@ -0,0 +1,257 @@
+"use strict";
+/**
+ * probe-core — generic spec-phase probe resolution model (ADR-550 Decision 7).
+ *
+ * Extracted from the edge-probe (the first adapter) once the prohibition probe (#644)
+ * proved it the *second* adapter of the same model: one adapter is a hypothetical seam,
+ * two is a real one. This module owns everything generic — the resolution lifecycle,
+ * the status×verification re-cut, `validateResolution`/`validateRequirement`, the
+ * `analyzeCoverage(items, resolutions?, validators)` merge/rollup/orphan-reject engine,
+ * the `byVerification` rollup, and the `runProbeCli` I/O scaffold. Each probe is a thin
+ * adapter: it supplies the proposal logic (deterministic for edge, LLM-recall for
+ * prohibition) and its closed vocabularies via injected validators.
+ *
+ * Authored as strict TypeScript (`src/probe-core.cts`) and compiled by
+ * `tsc -p tsconfig.build.json` to the gitignored runtime artifact
+ * `gsd-core/bin/lib/probe-core.cjs`. Do NOT hand-write the `.cjs`; it is emitted.
+ *
+ * Two orthogonal axes (the re-cut):
+ *   - status: resolved | dismissed | unresolved   — the resolution LIFECYCLE (shared)
+ *   - verification: <probe-defined> | null          — HOW a resolved item is verified
+ * The edge adapter declares `verification: explicit | backstop`; the prohibition adapter
+ * (#644) will declare `test | judgment`. Splitting the axes keeps the lifecycle enum free
+ * of a verification fact and lets a sibling probe add its own tiers without a parallel enum.
+ *
+ * Typing is hybrid (ADR-550 #5): generic type params for adapter DX, but enforcement runs
+ * through injected runtime validators, because the CLI executes over JSON where TS types are
+ * erased. The contract test pins the validators, not the types.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALID_STATUS = void 0;
+exports.validateRequirement = validateRequirement;
+exports.validateResolution = validateResolution;
+exports.analyzeCoverage = analyzeCoverage;
+exports.runProbeCli = runProbeCli;
+const node_fs_1 = __importDefault(require("node:fs"));
+/** The LOCKED set of valid lifecycle statuses (the re-cut: no covered/backstop). */
+exports.VALID_STATUS = ['resolved', 'dismissed', 'unresolved'];
+function errMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/**
+ * Structural guard for the report an adapter's `analyze` returns. The scaffold types `analyze`
+ * loosely (it runs over JSON-parsed input the adapter `as`-casts), so a future adapter (#644)
+ * that forgets to validate inside its closure could hand back a malformed object. Rather than
+ * stringify garbage as green output, `runProbeCli` checks the report shape and fails closed.
+ */
+function isValidReport(report) {
+    if (report == null || typeof report !== 'object')
+        return false;
+    const r = report;
+    if (!Array.isArray(r.items))
+        return false;
+    const c = r.coverage;
+    if (c == null || typeof c !== 'object')
+        return false;
+    if (typeof c.applicable !== 'number' || typeof c.resolved !== 'number' || typeof c.unresolved !== 'number') {
+        return false;
+    }
+    if (c.byVerification == null || typeof c.byVerification !== 'object')
+        return false;
+    return true;
+}
+/**
+ * Validate a requirement's generic structural fields — fail closed on malformed input rather
+ * than coercing it. Probe-specific fields (e.g. the edge adapter's `shapes`) are validated by
+ * the adapter. Typed loosely because the CLI casts arbitrary parsed JSON to `Requirement`.
+ */
+function validateRequirement(requirement) {
+    const r = requirement;
+    if (typeof r.id !== 'string' || !r.id.trim()) {
+        throw new Error(`requirement id must be a non-empty string (got ${JSON.stringify(r.id)})`);
+    }
+    if (r.text != null && typeof r.text !== 'string') {
+        throw new Error(`requirement ${r.id} text must be a string when present`);
+    }
+}
+/**
+ * Validate a resolution against the probe's injected validators. Rejects an unknown status,
+ * a dismissal without a non-empty reason, a `resolved` item with a missing/unknown
+ * verification tier, and a `resolved` item missing any field its tier requires (per
+ * `requiredFieldsByVerification`). Returns true on success.
+ */
+function validateResolution(r, validators) {
+    const key = `${r.requirement_id}::${r.category}`;
+    if (!exports.VALID_STATUS.includes(r.status)) {
+        throw new Error(`invalid status "${r.status}" for ${key}`);
+    }
+    // Invariant (this module's header): `verification` is null unless `status` is `resolved`.
+    // Enforce it for EVERY status — a dismissed/unresolved resolution carrying a verification
+    // tier would otherwise merge verbatim (`analyzeCoverage` below) and silently break the
+    // model for the second adapter (#644) that inherits this seam. Fail closed across the full
+    // status×verification space, not just `resolved`.
+    if (r.status !== 'resolved' && r.verification != null) {
+        throw new Error(`verification must be null unless status is "resolved" (got "${r.verification}") for ${key}`);
+    }
+    // An `unresolved` resolution is an UNACTED item: it must carry no resolution/reason payload.
+    // A populated payload is an authoring mistake (the author meant resolved/dismissed) that
+    // would otherwise be silently dropped into the unresolved count with no error pointing at
+    // it. Reject it so the mistake surfaces.
+    if (r.status === 'unresolved') {
+        if (r.resolution != null && String(r.resolution).trim()) {
+            throw new Error(`unresolved must not carry a resolution (${key})`);
+        }
+        if (r.reason != null && String(r.reason).trim()) {
+            throw new Error(`unresolved must not carry a reason (${key})`);
+        }
+    }
+    if (r.status === 'dismissed' && !(r.reason && String(r.reason).trim())) {
+        throw new Error(`dismissed requires a reason (${key})`);
+    }
+    if (r.status === 'resolved') {
+        const tier = r.verification;
+        if (tier == null) {
+            throw new Error(`resolved requires a verification tier (one of: ${validators.verification.join(', ')}) for ${key}`);
+        }
+        if (!validators.verification.includes(tier)) {
+            throw new Error(`invalid verification "${tier}" for ${key} — must be one of: ${validators.verification.join(', ')}`);
+        }
+        const required = validators.requiredFieldsByVerification[tier] ?? [];
+        for (const field of required) {
+            // field is 'resolution' | 'reason'; both are `string | null | undefined` on Resolution,
+            // so the indexed access is string-typed (no unknown-to-string coercion).
+            const value = r[field];
+            if (!(value != null && String(value).trim())) {
+                throw new Error(`${tier} requires a ${field} (${key})`);
+            }
+        }
+    }
+    return true;
+}
+/**
+ * Merge author resolutions onto ALREADY-PROPOSED items and roll up coverage counts.
+ *
+ * Core operates on `items[]`, never a `proposeFn`: probes have different deterministic
+ * surfaces (edge = deterministic propose + LLM resolve; prohibition = LLM propose + deterministic
+ * validate/merge), so proposal stays in each adapter and core must not assume it is deterministic.
+ *
+ * `coverage.resolved` is the COUNT of CLOSED items (`resolved` + `dismissed` status) =
+ * `applicable - unresolved` — the pre-re-cut "covered + dismissed + backstop" set,
+ * count-preserved. `byVerification` breaks the `resolved`-status items down by tier (each tier
+ * initialized to 0). Throws on any invalid resolution, a duplicate, an orphan (a resolution
+ * matching no proposed item), or a proposed item whose category is outside `validators.categories`.
+ */
+function analyzeCoverage(items, resolutions = [], validators) {
+    if (!Array.isArray(items)) {
+        throw new Error('items must be an array');
+    }
+    const key = (r) => `${r.requirement_id}::${r.category}`;
+    const resMap = new Map();
+    for (const r of resolutions) {
+        validateResolution(r, validators);
+        if (resMap.has(key(r))) {
+            throw new Error(`duplicate resolution for ${key(r)}`);
+        }
+        resMap.set(key(r), r);
+    }
+    const validCategories = new Set(validators.categories);
+    const merged = [];
+    const itemKeys = new Set();
+    for (const item of items) {
+        if (!validCategories.has(item.category)) {
+            throw new Error(`item ${key(item)} has unknown category "${item.category}" — not one of: ${validators.categories.join(', ')}`);
+        }
+        itemKeys.add(key(item));
+        const o = resMap.get(key(item));
+        if (o) {
+            merged.push({ ...item, status: o.status, verification: o.verification ?? null, resolution: o.resolution ?? null, reason: o.reason ?? null });
+        }
+        else {
+            // No author resolution: the item is rolled up VERBATIM, so its own status/fields must be
+            // valid too. The edge adapter only proposes `unresolved` items, but the prohibition adapter
+            // (#644) proposes LLM-generated items that arrive already populated — one carrying an
+            // out-of-enum status (e.g. the dropped "covered") or `dismissed` with no reason would
+            // otherwise be counted closed without validation. An Item is structurally a superset of a
+            // Resolution, so the same fail-closed check guards both. (ADR-550 Decision 5 hardens this
+            // shared seam for the second adapter; m1.)
+            validateResolution(item, validators);
+            merged.push(item);
+        }
+    }
+    // Reject orphan resolutions — a resolution whose (requirement_id, category) matches no
+    // proposed item (typo'd category or a non-applicable one) would otherwise be silently
+    // dropped, leaving the author believing an item is resolved while the report shows it
+    // unresolved (adversarial-review HIGH; preserved from the edge-probe's original engine).
+    for (const k of resMap.keys()) {
+        if (!itemKeys.has(k)) {
+            throw new Error(`unknown resolution for ${k} — no matching proposed item (typo'd category or non-applicable shape?)`);
+        }
+    }
+    const unresolved = merged.filter((i) => i.status === 'unresolved').length;
+    const applicable = merged.length;
+    const resolved = applicable - unresolved; // closed set: resolved-status + dismissed
+    const byVerification = {};
+    for (const tier of validators.verification)
+        byVerification[tier] = 0;
+    for (const i of merged) {
+        if (i.status === 'resolved' && i.verification != null) {
+            byVerification[i.verification] = (byVerification[i.verification] ?? 0) + 1;
+        }
+    }
+    return { items: merged, coverage: { applicable, resolved, unresolved, byVerification } };
+}
+/**
+ * Read the requirements file (and optional resolutions file), run the adapter's `analyze`,
+ * and write the report as pretty JSON + newline. With no requirements path, writes the usage
+ * line to stderr and exits 2. A JSON-parse failure or any `analyze` throw is a handled error:
+ * stderr + exit 2, never an uncaught stack trace — so the engine's fail-closed validation
+ * surfaces at the workflow boundary rather than failing open.
+ */
+function runProbeCli(analyze, options) {
+    const argv = options.argv ?? process.argv;
+    const readFile = options.readFile ?? ((p) => node_fs_1.default.readFileSync(p, 'utf8'));
+    const write = options.write ?? ((s) => { process.stdout.write(s); });
+    const writeErr = options.writeErr ?? ((s) => { process.stderr.write(s); });
+    const exit = options.exit ?? ((code) => { process.exit(code); });
+    const reqPath = argv[2];
+    const resPath = argv[3];
+    if (!reqPath) {
+        writeErr(`usage: ${options.usage}\n`);
+        exit(2);
+        return;
+    }
+    let requirements;
+    try {
+        requirements = JSON.parse(readFile(reqPath));
+    }
+    catch (e) {
+        writeErr(`error: cannot parse JSON from ${reqPath}: ${errMessage(e)}\n`);
+        exit(2);
+        return;
+    }
+    let resolutions = [];
+    if (resPath) {
+        try {
+            resolutions = JSON.parse(readFile(resPath));
+        }
+        catch (e) {
+            writeErr(`error: cannot parse JSON from ${resPath}: ${errMessage(e)}\n`);
+            exit(2);
+            return;
+        }
+    }
+    try {
+        const report = analyze(requirements, resolutions);
+        if (!isValidReport(report)) {
+            throw new Error('adapter returned a structurally-invalid coverage report (expected { items[], coverage{ applicable, resolved, unresolved, byVerification } })');
+        }
+        write(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    catch (e) {
+        writeErr(`error: ${errMessage(e)}\n`);
+        exit(2);
+    }
+}

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

@@ -135,6 +135,45 @@ function searchPhaseInContent(content, escapedPhase, phaseNum) {
         section,
     };
 }
+// ─── getRoadmapPhaseWithFallback ──────────────────────────────────────────────
+/**
+ * Two-pass phase lookup that mirrors cmdRoadmapGetPhase's resolution strategy.
+ *
+ * Pass 1: current-milestone slice (extractCurrentMilestone).
+ * Pass 2: full roadmap content (stripShippedMilestones) — covers cross-milestone
+ *         and older frontend phases that are no longer in the current milestone slice.
+ *
+ * Returns the phase section string if found, null if ROADMAP.md is missing,
+ * or throws if ROADMAP.md read fails.
+ *
+ * Used by check-command-router (computeUiPlanGate) so ui-plan-gate uses the SAME
+ * phase resolution as `roadmap.get-phase` — not a milestone-only subset.
+ */
+function getRoadmapPhaseWithFallback(cwd, phaseNum) {
+    const roadmapPath = planningPaths(cwd).roadmap;
+    if (!node_fs_1.default.existsSync(roadmapPath))
+        return null;
+    const rawContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
+    const milestoneContent = extractCurrentMilestone(rawContent, cwd);
+    const fullContent = stripShippedMilestones(rawContent);
+    const exactSource = phaseMarkdownRegexSourceExact(phaseNum);
+    if (exactSource) {
+        const exactMilestone = searchPhaseInContent(milestoneContent, exactSource, phaseNum);
+        if (exactMilestone && !exactMilestone.error)
+            return exactMilestone.section ?? null;
+        const exactFull = searchPhaseInContent(fullContent, exactSource, phaseNum);
+        if (exactFull && !exactFull.error)
+            return exactFull.section ?? null;
+    }
+    const escapedPhase = phaseMarkdownRegexSource(phaseNum);
+    const milestoneResult = searchPhaseInContent(milestoneContent, escapedPhase, phaseNum);
+    const result = (milestoneResult && !milestoneResult.error)
+        ? milestoneResult
+        : searchPhaseInContent(fullContent, escapedPhase, phaseNum) || milestoneResult;
+    if (!result || result.error)
+        return null;
+    return result.section ?? null;
+}
 // ─── cmdRoadmapGetPhase ───────────────────────────────────────────────────────
 function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
     const roadmapPath = planningPaths(cwd).roadmap;
@@ -597,6 +636,7 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
 }
 module.exports = {
     cmdRoadmapGetPhase,
+    getRoadmapPhaseWithFallback,
     cmdRoadmapAnalyze,
     cmdRoadmapUpdatePlanProgress,
     cmdRoadmapAnnotateDependencies,

package/gsd-core/bin/lib/runtime-artifact-layout.cjs

@@ -197,8 +197,12 @@ function kimiAgentsKind(destSubpath, prefix, configDir) {
  * @param runtime        canonical runtime ID (gates Hermes/Qwen branding in converter)
  * @param configDir      runtime config dir (for .gsd-source marker resolution)
  * @param nested         if true, nest concrete skills under their ns-* routers (#69)
+ * @param scope          install scope; converted to isGlobal and passed as 5th positional
+ *                       arg so scope-aware converters (antigravity, copilot) can choose
+ *                       between global home paths and workspace-relative paths without
+ *                       colliding with the `runtime` string at position 3.
  */
-function skillsKind(destSubpath, prefix, converterName, runtime, configDir, nested = false) {
+function skillsKind(destSubpath, prefix, converterName, runtime, configDir, nested = false, scope = 'global') {
     return {
         kind: 'skills',
         destSubpath,
@@ -207,9 +211,14 @@ function skillsKind(destSubpath, prefix, converterName, runtime, configDir, nest
             const installExports = getInstallExports();
             const realConverter = installExports[converterName];
             // Compute cmdNames once per stage call for performance (#3583).
-            // Extra args are ignored by converters that don't need runtime/cmdNames.
+            // Extra trailing args are ignored by converters that don't need them. The
+            // isGlobal flag is the 5th positional (NOT the 3rd): the 3rd positional is
+            // `runtime` for the claude/kimi/cline converters, so the scope-aware
+            // converters (antigravity, copilot) read isGlobal from position 5 to avoid
+            // colliding with `runtime` and always taking the global branch.
             const cmdNames = installExports.readGsdCommandNames();
-            const wrappedConverter = (content, skillName) => realConverter(content, skillName, runtime, cmdNames);
+            const isGlobal = scope === 'global';
+            const wrappedConverter = (content, skillName) => realConverter(content, skillName, runtime, cmdNames, isGlobal);
             return stageSkillsForRuntimeAsSkills(findInstallSourceRoot(configDir), resolved, wrappedConverter, prefix, nested);
         },
     };
@@ -242,47 +251,41 @@ function convertedCommandsKind(destSubpath, prefix, converterName, configDir) {
         },
     };
 }
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-// ---------------------------------------------------------------------------
-// Nested skill-bundle support matrix (#69)
-// ---------------------------------------------------------------------------
-//
-// When a runtime's skill loader scans only one level deep (non-recursive), a
-// concrete skill nested at `<router>/skills/<name>/SKILL.md` drops out of the
-// eager top-level listing yet stays readable by file path — which is exactly
-// what namespace routing needs. Recursive loaders surface every nested SKILL.md
-// as a peer (zero token saving), so they stay flat. Unconfirmed loaders stay
-// flat conservatively. Verified June 2026:
-//
-//   NEST (confirmed non-recursive / one-level scan):
-//     cline      — cline/cline skills.ts scanSkillsDirectory uses flat fs.readdir
-//     qwen       — QwenLM/qwen-code skill-load.ts flat readdir ("depth 2 enough")
-//     hermes     — hermes-agent.nousresearch.com/docs/user-guide/features/skills
-//                  (single-level subdir probe of the tap path)
-//     augment    — https://docs.augmentcode.com/cli/skills (flat single-level)
-//     trae       — docs.trae.ai/ide/skills + Trae-AI/TRAE#2253 (flat; nesting errors)
-//     antigravity— discuss.ai.google.dev/t/more-antigravity-issues/145875 ("will not recursive scan")
-//
-//   FLAT (recursive loader → nesting gives no saving):
-//     cursor     — https://cursor.com/docs/skills (walks skills root recursively)
-//     opencode   — sst/opencode skill/index.ts glob "skills/**/SKILL.md"
-//     kilo       — Kilo-Org/kilocode (opencode fork, same ** glob)
-//
-//   FLAT (reverted from nested — nested skills not discoverable by Skill tool, #924):
-//     claude     — https://code.claude.com/docs/en/skills + anthropics/claude-code#28266
-//                  (one-level scan under ~/.claude/skills — but Skill-tool errors on unknown
-//                   names rather than re-routing via the router; concrete skills must be
-//                   at the top level so Skill(skill="gsd-plan-phase") succeeds)
-//
-//   FLAT (nested-scan behaviour unconfirmed → conservative):
-//     codex      — developers.openai.com/codex/skills/
-//     copilot    — docs.github.com/en/copilot/concepts/agents/about-agent-skills
-//     windsurf   — docs.devin.ai/desktop/cascade/skills
-//     codebuddy  — codebuddy.ai/docs/cli/skills
+/** Lazy registry accessor — mirrors pattern from 5b/5c (runtime-homes.cts). */
+function getRegistry() {
+    return _require('./capability-registry.cjs');
+}
+/**
+ * Map a single ArtifactKindDescriptor entry to an ArtifactKind using the
+ * matching builder function. Mirrors the hand-built calls in the old switch.
+ */
+function dispatchKindEntry(entry, runtime, configDir, scope) {
+    const { kind, destSubpath, prefix, nesting, converter } = entry;
+    const nested = nesting === 'nested';
+    switch (kind) {
+        case 'commands':
+            if (converter == null) {
+                return commandsKind(destSubpath, prefix, configDir);
+            }
+            return convertedCommandsKind(destSubpath, prefix, converter, configDir);
+        case 'agents':
+            return agentsKind(destSubpath, prefix, configDir);
+        case 'skills':
+            if (converter == null) {
+                throw new TypeError(`resolveRuntimeArtifactLayout: skills entry for '${runtime}' has converter=null (converter is required for skills)`);
+            }
+            return skillsKind(destSubpath, prefix, converter, runtime, configDir, nested, scope);
+        case 'kimi-agents':
+            return kimiAgentsKind(destSubpath, prefix, configDir);
+        default:
+            throw new TypeError(`resolveRuntimeArtifactLayout: unknown kind '${kind}' in descriptor for runtime '${runtime}'`);
+    }
+}
 /**
  * Resolve the artifact layout for a given runtime and config directory.
+ *
+ * ADR-857 phase 5d: driven by the capability-registry artifactLayout descriptor
+ * instead of a hardcoded switch statement.
  */
 function resolveRuntimeArtifactLayout(runtime, configDir, scope = 'global') {
     if (typeof configDir !== 'string' || configDir === '') {
@@ -294,106 +297,13 @@ function resolveRuntimeArtifactLayout(runtime, configDir, scope = 'global') {
     if (!ALLOWED_RUNTIMES.has(runtime)) {
         throw new TypeError(`Unknown runtime: '${runtime}' — add to runtime-artifact-layout.cjs table`);
     }
-    let kinds;
-    switch (runtime) {
-        case 'claude':
-            if (scope === 'local') {
-                kinds = [
-                    commandsKind('commands/gsd', 'gsd-', configDir),
-                    agentsKind('agents', 'gsd-', configDir),
-                ];
-            }
-            else {
-                kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToClaudeSkill', 'claude', configDir)];
-            }
-            break;
-        case 'cursor':
-            // Cursor 1.6+ supports two artifact surfaces:
-            //   1. skills/gsd-<name>/SKILL.md  — rich skills with frontmatter + adapter header
-            //   2. commands/gsd-<name>.md      — plain markdown slash commands (no frontmatter)
-            //      accessed via '/' in the Agent input (#785)
-            kinds = [
-                skillsKind('skills', 'gsd-', 'convertClaudeCommandToCursorSkill', 'cursor', configDir),
-                convertedCommandsKind('commands', 'gsd-', 'convertClaudeCommandToCursorCommand', configDir),
-            ];
-            break;
-        case 'gemini':
-            kinds = [commandsKind('commands/gsd', 'gsd-', configDir)];
-            break;
-        case 'codex':
-            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToCodexSkill', 'codex', configDir)];
-            break;
-        case 'copilot':
-            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToCopilotSkill', 'copilot', configDir)];
-            break;
-        case 'antigravity':
-            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToAntigravitySkill', 'antigravity', configDir, true /* #69 nested */)];
-            break;
-        case 'windsurf':
-            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToWindsurfSkill', 'windsurf', configDir)];
-            break;
-        case 'augment':
-            kinds = [
-                commandsKind('commands', 'gsd-', configDir),
-                skillsKind('skills', 'gsd-', 'convertClaudeCommandToAugmentSkill', 'augment', configDir, true /* #69 nested */),
-            ];
-            break;
-        case 'trae':
-            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToTraeSkill', 'trae', configDir, true /* #69 nested */)];
-            break;
-        case 'qwen':
-            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToClaudeSkill', 'qwen', configDir, true /* #69 nested */)];
-            break;
-        case 'hermes':
-            // #947: restore canonical gsd- prefix — skills land at skills/gsd/gsd-<stem>/SKILL.md
-            // and dispatch as /gsd-<stem>, consistent with every other runtime.
-            // The skills/gsd/ category bucket (introduced by #2841) is retained.
-            // Prior bare-stem layout (prefix='') used by #3664 is reversed here.
-            kinds = [skillsKind('skills/gsd', 'gsd-', 'convertClaudeCommandToClaudeSkill', 'hermes', configDir, true /* #69 nested */)];
-            break;
-        case 'codebuddy':
-            // CodeBuddy (Tencent) reads two user-level surfaces (codebuddy.ai/docs/cli):
-            //   1. commands/gsd-<name>.md      — slash commands shown in the '/' menu (#789)
-            //   2. skills/gsd-<name>/SKILL.md  — model-invocable skills, emitted with
-            //      user-invocable:false so they stay OUT of '/' (the commands surface is
-            //      the sole '/' entry point) — avoids a duplicated /gsd-* per workflow.
-            // Subagents (~/.codebuddy/agents/) are already emitted by the generic agents
-            // block in bin/install.js; MCP is excluded (gsd ships no MCP server).
-            kinds = [
-                convertedCommandsKind('commands', 'gsd-', 'convertClaudeCommandToCodebuddyCommand', configDir),
-                skillsKind('skills', 'gsd-', 'convertClaudeCommandToCodebuddySkill', 'codebuddy', configDir),
-            ];
-            break;
-        case 'cline':
-            kinds = scope === 'global' ? [skillsKind('skills', 'gsd-', 'convertClaudeCommandToClineSkill', 'cline', configDir, true /* #69 nested */)] : [];
-            break;
-        case 'kimi':
-            kinds = scope === 'global'
-                ? [
-                    skillsKind('skills', 'gsd-', 'convertClaudeCommandToKimiSkill', 'kimi', configDir),
-                    kimiAgentsKind('agents', 'gsd', configDir),
-                ]
-                : [];
-            break;
-        case 'opencode':
-            // OpenCode reads flat slash commands from command/ and on-demand skills
-            // from skills/<name>/SKILL.md (https://opencode.ai/docs/skills). Emit both.
-            kinds = [
-                commandsKind('command', 'gsd-', configDir),
-                skillsKind('skills', 'gsd-', 'convertClaudeCommandToOpencodeSkill', 'opencode', configDir),
-            ];
-            break;
-        case 'kilo':
-            // Kilo derives from OpenCode and shares the skills/<name>/SKILL.md layout
-            // (https://kilo.ai/docs/customize/skills). Emit flat commands + skills.
-            kinds = [
-                commandsKind('command', 'gsd-', configDir),
-                skillsKind('skills', 'gsd-', 'convertClaudeCommandToKiloSkill', 'kilo', configDir),
-            ];
-            break;
-        default:
-            throw new TypeError(`Unknown runtime: '${runtime}' — add to runtime-artifact-layout.cjs table`);
+    const desc = getRegistry().runtimes[runtime]?.runtime?.artifactLayout;
+    if (!desc) {
+        // Runtime is in ALLOWED_RUNTIMES but has no descriptor — reproduce old default: throw.
+        throw new TypeError(`Unknown runtime: '${runtime}' — add to runtime-artifact-layout.cjs table`);
     }
+    const entries = desc[scope] ?? [];
+    const kinds = entries.map((entry) => dispatchKindEntry(entry, runtime, configDir, scope));
     return { runtime, configDir, scope, kinds };
 }
 module.exports = { resolveRuntimeArtifactLayout, findInstallSourceRoot, getInstallExports };