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

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

@@ -16,6 +16,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
  */
 const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const installProfiles = require("./install-profiles.cjs");
 const { stageSkillsForProfile, stageAgentsForProfile, stageSkillsForRuntimeAsSkills, stageCommandsForRuntimeFlat, } = installProfiles;
@@ -129,7 +130,7 @@ function findAgentsSourceRoot(runtimeConfigDir) {
 const ALLOWED_RUNTIMES = new Set([
     'claude', 'cursor', 'gemini', 'codex', 'copilot', 'antigravity',
     'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy',
-    'cline', 'opencode', 'kilo',
+    'cline', 'kimi', 'opencode', 'kilo',
 ]);
 // ---------------------------------------------------------------------------
 // Layout table builders
@@ -150,6 +151,43 @@ function agentsKind(destSubpath, prefix, configDir) {
         stage: (resolved) => stageAgentsForProfile(findAgentsSourceRoot(configDir), resolved),
     };
 }
+function kimiAgentsKind(destSubpath, prefix, configDir) {
+    return {
+        kind: 'kimi-agents',
+        destSubpath,
+        prefix,
+        stage: (resolved) => {
+            const installExports = getInstallExports();
+            const buildKimiAgentArtifacts = installExports['buildKimiAgentArtifacts'];
+            const stagedAgents = stageAgentsForProfile(findAgentsSourceRoot(configDir), resolved);
+            const subagents = [];
+            if (node_fs_1.default.existsSync(stagedAgents)) {
+                for (const entry of node_fs_1.default.readdirSync(stagedAgents, { withFileTypes: true })) {
+                    if (!entry.isFile() || !entry.name.endsWith('.md'))
+                        continue;
+                    const agentPath = node_path_1.default.join(stagedAgents, entry.name);
+                    subagents.push({
+                        path: node_path_1.default.join('agents', entry.name).replace(/\\/g, '/'),
+                        content: node_fs_1.default.readFileSync(agentPath, 'utf8'),
+                    });
+                }
+            }
+            const rootAgent = `---\nname: gsd\ndescription: Run GSD workflows in Kimi CLI.\ntools: Agent\n---\n\n# GSD for Kimi CLI\n\nCoordinate installed /skill:gsd-* workflows and route work to generated GSD subagents when a workflow requires an agent handoff.\n`;
+            const artifacts = buildKimiAgentArtifacts({ rootAgent, subagents });
+            const stageDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd-kimi-agents-'));
+            installProfiles.STAGED_DIRS.add(stageDir);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(stageDir, 'gsd.yaml'), artifacts.root.yaml);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(stageDir, 'gsd.md'), artifacts.root.prompt);
+            const subagentsDir = node_path_1.default.join(stageDir, 'subagents');
+            node_fs_1.default.mkdirSync(subagentsDir, { recursive: true });
+            for (const artifact of artifacts.subagents) {
+                node_fs_1.default.writeFileSync(node_path_1.default.join(subagentsDir, `${artifact.name}.yaml`), artifact.yaml);
+                node_fs_1.default.writeFileSync(node_path_1.default.join(subagentsDir, `${artifact.name}.md`), artifact.prompt);
+            }
+            return stageDir;
+        },
+    };
+}
 /**
  * Build a skills kind descriptor.
  *
@@ -158,8 +196,9 @@ function agentsKind(destSubpath, prefix, configDir) {
  * @param converterName  name of converter function in bin/install.js exports
  * @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)
  */
-function skillsKind(destSubpath, prefix, converterName, runtime, configDir) {
+function skillsKind(destSubpath, prefix, converterName, runtime, configDir, nested = false) {
     return {
         kind: 'skills',
         destSubpath,
@@ -171,7 +210,7 @@ function skillsKind(destSubpath, prefix, converterName, runtime, configDir) {
             // Extra args are ignored by converters that don't need runtime/cmdNames.
             const cmdNames = installExports.readGsdCommandNames();
             const wrappedConverter = (content, skillName) => realConverter(content, skillName, runtime, cmdNames);
-            return stageSkillsForRuntimeAsSkills(findInstallSourceRoot(configDir), resolved, wrappedConverter, prefix);
+            return stageSkillsForRuntimeAsSkills(findInstallSourceRoot(configDir), resolved, wrappedConverter, prefix, nested);
         },
     };
 }
@@ -206,6 +245,42 @@ 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
 /**
  * Resolve the artifact layout for a given runtime and config directory.
  */
@@ -252,7 +327,7 @@ function resolveRuntimeArtifactLayout(runtime, configDir, scope = 'global') {
             kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToCopilotSkill', 'copilot', configDir)];
             break;
         case 'antigravity':
-            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToAntigravitySkill', 'antigravity', configDir)];
+            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToAntigravitySkill', 'antigravity', configDir, true /* #69 nested */)];
             break;
         case 'windsurf':
             kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToWindsurfSkill', 'windsurf', configDir)];
@@ -260,17 +335,21 @@ function resolveRuntimeArtifactLayout(runtime, configDir, scope = 'global') {
         case 'augment':
             kinds = [
                 commandsKind('commands', 'gsd-', configDir),
-                skillsKind('skills', 'gsd-', 'convertClaudeCommandToAugmentSkill', 'augment', configDir),
+                skillsKind('skills', 'gsd-', 'convertClaudeCommandToAugmentSkill', 'augment', configDir, true /* #69 nested */),
             ];
             break;
         case 'trae':
-            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToTraeSkill', 'trae', configDir)];
+            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToTraeSkill', 'trae', configDir, true /* #69 nested */)];
             break;
         case 'qwen':
-            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToClaudeSkill', 'qwen', configDir)];
+            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToClaudeSkill', 'qwen', configDir, true /* #69 nested */)];
             break;
         case 'hermes':
-            kinds = [skillsKind('skills/gsd', '', 'convertClaudeCommandToClaudeSkill', 'hermes', configDir)];
+            // #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):
@@ -286,7 +365,15 @@ function resolveRuntimeArtifactLayout(runtime, configDir, scope = 'global') {
             ];
             break;
         case 'cline':
-            kinds = scope === 'global' ? [skillsKind('skills', 'gsd-', 'convertClaudeCommandToClineSkill', 'cline', configDir)] : [];
+            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

package/gsd-core/bin/lib/runtime-config-adapter-registry.cjs

@@ -18,11 +18,12 @@ const REGISTRY = Object.freeze({
     cursor: Object.freeze({ installSurface: 'cursor-hooks-json', writesSharedSettings: false, finishPermissionWriter: null }),
     windsurf: Object.freeze({ installSurface: 'profile-marker-only', writesSharedSettings: false, finishPermissionWriter: null }),
     trae: Object.freeze({ installSurface: 'profile-marker-only', writesSharedSettings: false, finishPermissionWriter: null }),
+    kimi: Object.freeze({ installSurface: 'profile-marker-only', writesSharedSettings: false, finishPermissionWriter: null }),
 });
 // ---------------------------------------------------------------------------
 // Exports
 // ---------------------------------------------------------------------------
-/** The complete set of 15 supported runtimes for config-adapter dispatch. */
+/** The complete set of 16 supported runtimes for config-adapter dispatch. */
 const ALLOWED_CONFIG_RUNTIMES = new Set(Object.keys(REGISTRY));
 /** All valid installSurface values. */
 const INSTALL_SURFACES = Object.freeze([

package/gsd-core/bin/lib/runtime-homes.cjs

@@ -15,12 +15,18 @@
  *   cline   — Skills-capable since v3.48.0 (#782). SKILL.md files live at
  *             ~/.cline/skills/<skillName>/SKILL.md (same flat layout as cursor/codex).
  *             .clinerules is also emitted (rules-based compatibility layer).
+ *   kimi    — Agent Skills are discovered from Kimi's generic user roots:
+ *             ~/.config/agents/skills (recommended) then ~/.agents/skills,
+ *             with Kimi selecting the first existing generic skills directory.
+ *             ~/.kimi-code/skills is brand-specific and can be selected as a
+ *             GSD write target with --config-dir or KIMI_CONFIG_DIR.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveAntigravityGlobalDir = resolveAntigravityGlobalDir;
+exports.resolveKimiGlobalDir = resolveKimiGlobalDir;
 exports.getGlobalConfigDir = getGlobalConfigDir;
 exports.getGlobalSkillsBase = getGlobalSkillsBase;
 exports.getGlobalSkillDir = getGlobalSkillDir;
@@ -59,6 +65,36 @@ function resolveAntigravityGlobalDir(opts = {}) {
     }
     return node_path_1.default.join(base, 'antigravity');
 }
+/**
+ * Resolve Kimi's generic user root using Kimi CLI's documented first-existing
+ * generic skills directory policy:
+ *
+ *   1. ~/.config/agents/skills  (recommended)
+ *   2. ~/.agents/skills
+ *
+ * If neither generic skills directory exists yet, install to the recommended
+ * ~/.config/agents root so the generated skills become the first generic
+ * candidate Kimi discovers.
+ *
+ * KIMI_CONFIG_DIR is a GSD installer write-location override. It is not Kimi's
+ * upstream data-root variable, and arbitrary roots are discoverable by Kimi only
+ * when the user also configures Kimi --skills-dir or extra_skill_dirs.
+ */
+function resolveKimiGlobalDir(opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? node_os_1.default.homedir();
+    const existsSyncFn = opts.existsSync ?? node_fs_1.default.existsSync;
+    if (env['KIMI_CONFIG_DIR'])
+        return expandTilde(env['KIMI_CONFIG_DIR']);
+    const recommendedRoot = node_path_1.default.join(home, '.config', 'agents');
+    const fallbackRoot = node_path_1.default.join(home, '.agents');
+    const candidates = [recommendedRoot, fallbackRoot];
+    for (const candidate of candidates) {
+        if (existsSyncFn(node_path_1.default.join(candidate, 'skills')))
+            return candidate;
+    }
+    return recommendedRoot;
+}
 /**
  * Return the global config base directory for the given runtime.
  * Respects the same env-var overrides as bin/install.js getGlobalDir().
@@ -122,6 +158,10 @@ function getGlobalConfigDir(runtime, explicitDir) {
         // ── Cline ────────────────────────────────────────────────────────────────
         case 'cline':
             return env['CLINE_CONFIG_DIR'] ? expandTilde(env['CLINE_CONFIG_DIR']) : node_path_1.default.join(home, '.cline');
+        // ── Kimi CLI (generic agents user root) ────────────────────────────────
+        case 'kimi': {
+            return resolveKimiGlobalDir({ env, home });
+        }
         // ── OpenCode (XDG) ───────────────────────────────────────────────────────
         case 'opencode': {
             if (env['OPENCODE_CONFIG_DIR'])

package/gsd-core/bin/lib/runtime-name-policy.cjs

@@ -33,6 +33,7 @@ const FALLBACK_ALIASES = {
     trae: ['trae', 'trae-cli'],
     qwen: ['qwen', 'qwen-code', 'qwen-cli'],
     hermes: ['hermes', 'hermes-agent', 'hermes-cli'],
+    kimi: ['kimi'],
     codebuddy: ['codebuddy', 'codebuddy-cli'],
     cline: ['cline', 'cline-cli'],
 };

package/gsd-core/bin/lib/shell-command-projection.cjs

@@ -232,6 +232,19 @@ function isManagedHookCommand(commandText, opts = {}) {
     const managedBasenames = managedHookCommandSurfaceSet(surface, includeLegacyAliases);
     if (!managedBasenames || managedBasenames.size === 0)
         return false;
+    // args-form check: the managed hook filename may appear in args[] rather than
+    // in command when a windowless launcher wraps the Node invocation. (#976)
+    // Only treat as managed when an arg basename matches the managed hook set —
+    // prevents false-positives for non-GSD entries that happen to share a path segment.
+    if (Array.isArray(opts.args) && opts.args.length > 0) {
+        for (const arg of opts.args) {
+            if (typeof arg !== 'string')
+                continue;
+            const argBasename = arg.replace(/\\/g, '/').split('/').pop() || '';
+            if (isManagedHookBasename(argBasename, { surface }))
+                return true;
+        }
+    }
     const normalizedCommand = commandText.replace(/\\/g, '/');
     if (typeof opts.configDir === 'string' && opts.configDir.length > 0) {
         const normalizedHooksDir = `${node_path_1.default.join(opts.configDir, 'hooks').replace(/\\/g, '/')}/`;

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

@@ -607,6 +607,7 @@ function cmdStateRecordSession(cwd, options, raw) {
     }
     const now = clock_cjs_1.realClock.nowIso();
     const updated = [];
+    let sessionCreated = false;
     readModifyWriteStateMd(statePath, (content) => {
         // Update Last session / Last Date
         let result = (0, state_document_cjs_1.stateReplaceField)(content, 'Last session', now);
@@ -661,10 +662,80 @@ function cmdStateRecordSession(cwd, options, raw) {
                 }
             }
         }
+        // Bug #944: DWIM normalize/auto-create — when the caller supplied --stopped-at or
+        // --resume-file but the body lacks the canonical labels (in-place replace
+        // returned a miss), persist the values durably. Mirrors the DWIM pattern used
+        // by add-decision, add-blocker, and record-metric. Never silently drop
+        // caller-supplied values.
+        //
+        // Guard: only act when the caller actually supplied a value. When no
+        // --stopped-at / --resume-file are given and the body already had no session
+        // labels (nothing was updated), we return recorded:false — the existing
+        // behaviour for a no-op call that didn't supply any values.
+        //
+        // Correctness invariant: both buildStateFrontmatter and cmdStateSnapshot read
+        // only the FIRST `## Session` block (via a /##\s*Session\s*\n…/i regex).
+        // If we blindly append a second `## Session` block when one already exists, the
+        // newly-written Stopped at / Resume file end up in the second (invisible) block.
+        // Fix: when a `## Session` heading already exists, normalize THAT block in place
+        // (insert / replace canonical bold-label lines within the existing section).
+        // Only append a brand-new section when NO `## Session` heading exists at all.
+        const callerSuppliedValues = !!(options.stopped_at || (options.resume_file !== undefined && options.resume_file !== null));
+        const needsStoppedAt = options.stopped_at && !updated.includes('Stopped At');
+        const needsResumeFile = options.resume_file !== undefined && options.resume_file !== null && !updated.includes('Resume File');
+        const needsLastSession = !updated.includes('Last session') && !updated.includes('Last Date');
+        if (callerSuppliedValues && (needsStoppedAt || needsResumeFile || needsLastSession)) {
+            const resumeValue = (options.resume_file !== undefined && options.resume_file !== null)
+                ? options.resume_file
+                : 'None';
+            const stoppedAtValue = options.stopped_at || 'None';
+            // Determine whether a ## Session heading already exists in the body.
+            const existingSessionHeading = /^## Session\s*$/im.test(content);
+            if (existingSessionHeading) {
+                // Normalize in place: replace the ENTIRE BODY of the existing ## Session
+                // section (heading + all content up to the next ## heading or EOF) with
+                // canonical bold-label lines. The negative-lookahead per-line pattern
+                // `(?!^## )[\s\S]` consumes every line that doesn't start with "## ",
+                // which correctly stops at the next section boundary without consuming it.
+                // A trailing blank line is added so the next ## heading keeps its spacing.
+                content = content.replace(/^(## Session[ \t]*\n(?:(?!^## )[\s\S])*)/m, [
+                    '## Session',
+                    '',
+                    `**Last session:** ${now}`,
+                    `**Stopped at:** ${stoppedAtValue}`,
+                    `**Resume file:** ${resumeValue}`,
+                    '',
+                    '',
+                ].join('\n'));
+            }
+            else {
+                // No ## Session heading exists at all — append a new canonical section.
+                const scaffold = [
+                    '',
+                    '## Session',
+                    '',
+                    `**Last session:** ${now}`,
+                    `**Stopped at:** ${stoppedAtValue}`,
+                    `**Resume file:** ${resumeValue}`,
+                    '',
+                ].join('\n');
+                content = content.trimEnd() + '\n' + scaffold;
+            }
+            sessionCreated = true;
+            if (needsLastSession)
+                updated.push('Last session');
+            if (needsStoppedAt)
+                updated.push('Stopped At');
+            if (needsResumeFile)
+                updated.push('Resume File');
+        }
         return content;
     }, cwd);
     if (updated.length > 0) {
-        output({ recorded: true, updated }, raw, 'true');
+        const result = { recorded: true, updated };
+        if (sessionCreated)
+            result['created'] = true;
+        output(result, raw, 'true');
     }
     else {
         output({ recorded: false, reason: 'No session fields found in STATE.md' }, raw, 'false');
@@ -748,8 +819,12 @@ function cmdStateSnapshot(cwd, raw) {
     const sessionMatch = body.match(/##\s*Session\s*\n([\s\S]*?)(?=\n##|$)/i);
     if (sessionMatch) {
         const sessionSection = sessionMatch[1];
+        // Accept both `**Last Date:**` (canonical template form) and `**Last session:**`
+        // (the form written by the DWIM auto-create / normalize path added for #944).
         const lastDateMatch = sessionSection.match(/\*\*Last Date:\*\*\s*(.+)/i)
-            || sessionSection.match(/^Last Date:\s*(.+)/im);
+            || sessionSection.match(/^Last Date:\s*(.+)/im)
+            || sessionSection.match(/\*\*Last session:\*\*\s*(.+)/i)
+            || sessionSection.match(/^Last session:\s*(.+)/im);
         const stoppedAtMatch = sessionSection.match(/\*\*Stopped At:\*\*\s*(.+)/i)
             || sessionSection.match(/^Stopped At:\s*(.+)/im);
         const resumeFileMatch = sessionSection.match(/\*\*Resume File:\*\*\s*(.+)/i)
@@ -974,12 +1049,39 @@ function syncStateFrontmatter(content, cwd) {
     if (derivedFm['status'] === 'unknown' && existingFm['status'] && existingFm['status'] !== 'unknown') {
         derivedFm['status'] = existingFm['status'];
     }
+    // Bug #948: preserve `milestone_name` / `milestone` when the derived value
+    // is the template placeholder 'milestone'. getMilestoneInfo returns the
+    // literal string 'milestone' when it cannot match the version from the roadmap
+    // (e.g. no ROADMAP.md, roadmap lacks the heading for the stored version, or the
+    // milestone version read from STATE.md itself triggers the lookup before the
+    // file is fully written). A placeholder must never overwrite a real name that the
+    // existing frontmatter already holds; only an empty derived value falls through
+    // to this guard (the primary #905 preserve path below handles that).
+    const MILESTONE_NAME_PLACEHOLDER = 'milestone';
+    if (derivedFm['milestone_name'] === MILESTONE_NAME_PLACEHOLDER &&
+        existingFm['milestone_name'] &&
+        existingFm['milestone_name'] !== MILESTONE_NAME_PLACEHOLDER) {
+        derivedFm['milestone_name'] = existingFm['milestone_name'];
+        // Keep the stored milestone version consistent with the preserved name.
+        if (existingFm['milestone']) {
+            derivedFm['milestone'] = existingFm['milestone'];
+        }
+    }
     // Bug #905: preserve scalar fields that buildStateFrontmatter can only derive
     // from body annotations (Current Phase:, Current Plan:, etc.). When those
     // annotations are absent — e.g. after an agent or tool rewrites the body —
     // buildStateFrontmatter returns no value for those keys. Mirror the same
     // fallback pattern used in cmdStateJson so the existing frontmatter values
     // survive every writeStateMd call.
+    //
+    // For stopped_at / paused_at: the original #905 "fall back when derived is
+    // absent" rule is preserved here. The stale-body-overwrites-frontmatter
+    // scenario from #948 is prevented by the no-op guard in
+    // readModifyWriteStateMd: when the transform produces no change the file is
+    // never written, so syncStateFrontmatter never even runs. Attempting to
+    // "always prefer frontmatter" here breaks legitimate callers like phase.complete
+    // that intentionally write a new stopped_at value to the body and expect
+    // syncStateFrontmatter to pick it up.
     if (!derivedFm['stopped_at'] && existingFm['stopped_at']) {
         derivedFm['stopped_at'] = existingFm['stopped_at'];
     }
@@ -1155,6 +1257,16 @@ function readModifyWriteStateMd(statePath, transformFn, cwd, options, clock) {
         // restore it when resync is false.
         const preFm = resync ? null : extractFrontmatter(content);
         const modified = transformFn(content);
+        // Bug #948: no-op guard — if the transform produced no change, do NOT write
+        // the file. An unconditional write would bump `last_updated`, reset
+        // `milestone_name` to the template placeholder, and resurrect stale
+        // body-derived `stopped_at` values via syncStateFrontmatter. Skipping the
+        // write when content is unchanged is safe because every caller that mutates
+        // content already returns the mutated string, and callers that detect a
+        // no-op explicitly return the original content unchanged.
+        if (modified === content) {
+            return;
+        }
         let synced = syncStateFrontmatter(modified, cwd);
         if (!resync && preFm && preFm['progress']) {
             // Re-apply the curated progress block that syncStateFrontmatter just

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

@@ -12,11 +12,18 @@
  * Exports:
  *   readSurface(runtimeConfigDir)
  *   writeSurface(runtimeConfigDir, surfaceState)
- *   resolveSurface(runtimeConfigDir, manifest, clusterMap)
- *   applySurface(runtimeConfigDir, layout, manifest, clusterMap)
- *   listSurface(runtimeConfigDir, manifest, clusterMap)
+ *   resolveSurface(runtimeConfigDir, manifest, clusterMap?, registry?)
+ *   applySurface(runtimeConfigDir, layout, manifest, clusterMap?, registry?)
+ *   listSurface(runtimeConfigDir, manifest, clusterMap?, registry?)
  *   pruneSkillDirs(skillsDir, retainedNames, prefix, manifest)
  *
+ * The optional `registry` param (ADR-857 phase 4c) accepts the capability-registry
+ * object.  When present, capability clusters are merged into the effective cluster
+ * map and the registry is threaded into resolveProfile so capability-contributed
+ * skills participate in the base set and disable-ability.  Absent or undefined
+ * leaves behaviour identical to the pre-registry path (no-op for current registry
+ * where UI=full and the full profile returns '*' regardless).
+ *
  * ADR-457 build-at-publish: the hand-written bin/lib/surface.cjs collapsed
  * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
  * from the prior hand-written .cjs; only types are added.
@@ -86,10 +93,11 @@ function clustersToSkills(clusterNames, clusterMap) {
     const result = new Set();
     for (const name of clusterNames) {
         const members = clusterMap[name];
-        if (members) {
-            for (const s of members)
-                result.add(s);
-        }
+        // FIX 5: guard against non-iterable members — malformed registry must never throw
+        if (!Array.isArray(members))
+            continue;
+        for (const s of members)
+            result.add(s);
     }
     return result;
 }
@@ -132,19 +140,63 @@ function normalizeSkillManifest(runtimeConfigDir, manifest) {
  * 2. Remove skills in disabled clusters
  * 3. Add explicitAdds (and their transitive closure)
  * 4. Remove explicitRemoves (only the stem itself, no cascade)
+ *
+ * ADR-857 phase 4c: optional registry param.  When present:
+ *   - capability clusters are merged into the effective cluster map so
+ *     capability-owned skill groups are disable-able.
+ *   - registry is threaded into resolveProfile so capability skills
+ *     participate in the base skill set and their requires: chains expand.
  */
-function resolveSurface(runtimeConfigDir, manifest, clusterMap) {
-    const cm = clusterMap || clusters_cjs_1.CLUSTERS;
+function resolveSurface(runtimeConfigDir, manifest, clusterMap, registry) {
+    // Merge capability clusters into the cluster map when registry is provided.
+    // The ADR-857 phase 4a HARD gate guarantees that when a capId matches a CLUSTERS
+    // key, the values are EQUAL — so the spread is idempotent for matching names.
+    // Defense-in-depth: if a capId collides with a hand-authored CLUSTERS key AND
+    // the values DIFFER (future drift bypassing the gate), prefer the hand-authored
+    // value so disable behavior is never silently changed by a stale registry entry.
+    // Also guard: skip entries whose value is not a string[] (malformed registry).
+    let cm = clusterMap || clusters_cjs_1.CLUSTERS;
+    if (registry && registry.capabilityClusters && typeof registry.capabilityClusters === 'object') {
+        const baseCm = cm;
+        const capClusters = registry.capabilityClusters;
+        const merged = { ...baseCm };
+        for (const capId of Object.keys(capClusters)) {
+            const val = capClusters[capId];
+            // FIX 5: skip malformed (non-array) entries — never throw on bad registry
+            if (!Array.isArray(val))
+                continue;
+            // FIX 4: if the capId matches an existing cluster key, only override when
+            // the values are identical (guaranteed by 4a gate).  If they differ, the
+            // hand-authored value wins — prefer known-correct disable behavior over
+            // a potentially stale registry entry.
+            if (Object.prototype.hasOwnProperty.call(baseCm, capId)) {
+                const existing = baseCm[capId];
+                if (!Array.isArray(existing)) {
+                    merged[capId] = val;
+                    continue;
+                }
+                // Values differ → hand-authored wins (skip the override)
+                if (existing.length !== val.length || existing.some((v, i) => v !== val[i]))
+                    continue;
+            }
+            // Prototype-pollution guard (parity with _capabilitySkillsForMode in install-profiles.cts)
+            if (capId === '__proto__' || capId === 'constructor' || capId === 'prototype')
+                continue;
+            merged[capId] = val;
+        }
+        cm = merged;
+    }
     const skillManifest = normalizeSkillManifest(runtimeConfigDir, manifest);
     const surface = readSurface(runtimeConfigDir);
     // Determine base profile name: from surface state or from .gsd-profile marker
     const baseProfileName = (surface && surface.baseProfile)
         ? surface.baseProfile
         : (readActiveProfile(runtimeConfigDir) || 'full');
-    // Resolve base profile
+    // Resolve base profile — thread registry so capability skills are included.
     const baseResolved = resolveProfile({
         modes: baseProfileName.split(',').map((s) => s.trim()),
         manifest: skillManifest,
+        registry,
     });
     // If full, we need to enumerate all skills from the manifest
     let skills;
@@ -205,12 +257,12 @@ function resolveSurface(runtimeConfigDir, manifest, clusterMap) {
  * Re-stage the active surface using the resolved layout.
  * Iterates layout.kinds and syncs each artifact kind to its destination.
  */
-function applySurface(runtimeConfigDir, layout, manifest, clusterMap) {
+function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry) {
     if (node_path_1.default.resolve(runtimeConfigDir) !== node_path_1.default.resolve(layout.configDir)) {
         throw new TypeError('applySurface runtimeConfigDir must match layout.configDir');
     }
     const skillManifest = normalizeSkillManifest(layout.configDir, manifest);
-    const resolved = resolveSurface(layout.configDir, skillManifest, clusterMap);
+    const resolved = resolveSurface(layout.configDir, skillManifest, clusterMap, registry);
     // Mirror installRuntimeArtifacts: skills kinds get per-runtime path rewrites
     // so SKILL.md bodies reference the install target (pathPrefix), not the
     // converter's default ~/.claude paths (#813). Computed lazily so command-only
@@ -409,9 +461,9 @@ function _syncGsdDir(stagedDir, destDir, kind, manifest) {
  * Token cost = sum of description lengths ÷ 4 (mirrors audit script).
  * Descriptions are read from the install source (findInstallSourceRoot).
  */
-function listSurface(runtimeConfigDir, manifest, clusterMap) {
+function listSurface(runtimeConfigDir, manifest, clusterMap, registry) {
     const skillManifest = normalizeSkillManifest(runtimeConfigDir, manifest);
-    const resolved = resolveSurface(runtimeConfigDir, skillManifest, clusterMap);
+    const resolved = resolveSurface(runtimeConfigDir, skillManifest, clusterMap, registry);
     // All known stems from manifest (exclude _calls_agents_ meta keys)
     const allStems = [];
     for (const [key] of skillManifest) {

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

@@ -383,7 +383,7 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
         };
         const sourceContent = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(cwd, link['from'] || ''));
         if (!sourceContent) {
-            check['detail'] = 'Source file not found';
+            check['detail'] = 'Source file not found (from: must be a relative file path; describe components/endpoints in via:)';
         }
         else if (link['pattern']) {
             try {

package/gsd-core/bin/shared/model-catalog.json

@@ -52,6 +52,11 @@
       "sonnet": null,
       "haiku": null
     },
+    "kimi": {
+      "opus": null,
+      "sonnet": null,
+      "haiku": null
+    },
     "cursor": {
       "opus": null,
       "sonnet": null,

package/gsd-core/bin/shared/runtime-aliases.manifest.json

@@ -64,6 +64,9 @@
     "hermes-agent",
     "hermes-cli"
   ],
+  "kimi": [
+    "kimi"
+  ],
   "codebuddy": [
     "codebuddy",
     "codebuddy-cli"

package/gsd-core/references/planner-reviews.md

@@ -4,6 +4,8 @@ Triggered when orchestrator sets Mode to `reviews`. Replanning from scratch with
 
 **Mindset:** Fresh planner with review insights — not a surgeon making patches, but an architect who has read peer critiques.
 
+**Execution contract:** REVIEWS.md is audit trail and feedback input, not a second execution contract. /gsd:execute-phase primarily consumes PLAN.md plus the normal phase context. Every current actionable review finding must therefore be incorporated into the relevant PLAN.md or explicitly deferred/rejected in that PLAN.md.
+
 ### Step 1: Load REVIEWS.md
 Read the reviews file from `<files_to_read>`. Parse:
 - Per-reviewer feedback (strengths, concerns, suggestions)
@@ -13,13 +15,14 @@ Read the reviews file from `<files_to_read>`. Parse:
 ### Step 2: Categorize Feedback
 Group review feedback into:
 - **Must address**: HIGH severity consensus concerns
-- **Should address**: MEDIUM severity concerns from 2+ reviewers
+- **Must represent in PLAN.md**: actionable MEDIUM/LOW findings that require task, action, acceptance criteria, verify command, must_haves, threat-model, artifact, stale-path, or execution-contract changes
+- **Should address**: MEDIUM severity concerns from 2+ reviewers that improve quality but do not change the executable contract
 - **Consider**: Individual reviewer suggestions, LOW severity items
 
 ### Step 3: Plan Fresh with Review Context
 Create new plans following the standard planning process, but with review feedback as additional constraints:
 - Each HIGH severity consensus concern MUST have a task that addresses it
-- MEDIUM concerns should be addressed where feasible without over-engineering
+- Each current actionable MEDIUM/LOW finding MUST either appear in the relevant PLAN.md executable content or have a deferral/rejection rationale in that PLAN.md
 - Note in task actions: "Addresses review concern: {concern}" for traceability
 
 ### Step 4: Return