specrails-core 6.2.1 → 6.3.0

package/dist/installer/commands/init.js

@@ -6,13 +6,13 @@ import { recordSuccessfulInstall } from '../util/registry.js';
 import { fileURLToPath } from 'node:url';
 import { InstallerError } from '../util/errors.js';
 import { runCommand } from '../util/exec.js';
-import { info, ok, step, warn } from '../util/logger.js';
+import { info, ok, step } from '../util/logger.js';
 import { isDir, isSymlink, listDir, pathExists, readTextFile, removePath, writeFileLf, } from '../util/fs.js';
 import { loadInstallConfig, resolveConfigPath, } from '../phases/install-config.js';
 import { checkPrerequisites } from '../phases/prereqs.js';
 import { derivedPaths } from '../phases/provider-detect.js';
 import { materializeFrameworkVersion } from '../phases/framework-lifecycle.js';
-import { CORE_AGENTS, assembleProjectWorkspace, installFramework, } from '../phases/scaffold.js';
+import { assembleProjectWorkspace, installFramework, } from '../phases/scaffold.js';
 import { frameworkRoot, resolveArtifacts } from '../util/registry.js';
 const WORKSPACE_PROVIDER_ORDER = [
     'claude',
@@ -21,12 +21,12 @@ const WORKSPACE_PROVIDER_ORDER = [
     'kimi',
 ];
 /**
- * Snapshot the provider/role inventory exposed by one live workspace before a
- * global framework version swap. This matters on Windows: directory junctions
- * resolve their target when they are created, so a workspace link made through
- * `framework/current` must be recreated after `current` moves. Keeping the
- * exact visible `sr-*` set also avoids widening or narrowing a project's
- * optional role selection during that refresh.
+ * Snapshot the providers exposed by one live workspace before a global
+ * framework version swap. This matters on Windows: directory junctions resolve
+ * their target when they are created, so a workspace link made through
+ * `framework/current` must be recreated after `current` moves. Roles are
+ * runtime-defined since Core 6.3, so every provider reports an empty selection;
+ * the keys are what drive the multi-provider reassembly.
  */
 export function snapshotWorkspaceProviderSelections(workspace) {
     const selections = {};
@@ -36,44 +36,25 @@ export function snapshotWorkspaceProviderSelections(workspace) {
         if (Array.isArray(manifest.providers))
             recorded = manifest.providers.filter((value) => typeof value === 'string');
     }
-    catch { /* Legacy manifests are recognized by the complete Core role trio. */ }
+    catch { /* Legacy manifests: a provider counts only through its managed links. */ }
     for (const provider of WORKSPACE_PROVIDER_ORDER) {
         const { providerDir } = derivedPaths(provider);
         const providerRoot = path.join(workspace, providerDir);
         if (!pathExists(providerRoot) ||
             (!workspaceHasManagedProviderLink(providerRoot, provider)
-                && !(recorded.includes(provider) && hasCopiedCoreArtifacts(providerRoot, provider))
-                && !hasCopiedCoreRoles(providerRoot, provider))) {
+                && !(recorded.includes(provider) && hasCopiedCoreArtifacts(providerRoot, provider)))) {
             continue;
         }
-        const roleRoot = provider === 'codex'
-            ? path.join(workspace, providerDir, 'skills', 'rails')
-            : provider === 'kimi'
-                ? path.join(workspace, providerDir, 'skills')
-                : path.join(workspace, providerDir, 'agents');
-        const ids = listDir(roleRoot)
-            .filter((entry) => provider === 'claude' || provider === 'gemini'
-            ? path.basename(entry).endsWith('.md')
-            : isDir(entry))
-            .map((entry) => {
-            const name = path.basename(entry);
-            return name.endsWith('.md') ? name.slice(0, -3) : name;
-        })
-            .filter((id) => /^sr-[a-z0-9-]+$/.test(id));
-        selections[provider] = [...new Set(ids)].sort();
+        selections[provider] = [];
     }
     return selections;
 }
+/** A copied (in-repo) install is recognised by its workflow commands or runtime, never by role files. */
 function hasCopiedCoreArtifacts(providerRoot, provider) {
-    return hasCopiedCoreRoles(providerRoot, provider) || pathExists(provider === 'codex' ? path.join(providerRoot, 'skills', 'implement', 'SKILL.md')
+    return pathExists(provider === 'codex' ? path.join(providerRoot, 'skills', 'implement', 'SKILL.md')
         : provider === 'kimi' ? path.join(providerRoot, 'specrails', 'run-skill.mjs')
             : path.join(providerRoot, 'commands', 'specrails', provider === 'gemini' ? 'implement.toml' : 'implement.md'));
 }
-function hasCopiedCoreRoles(providerRoot, provider) {
-    return [...CORE_AGENTS].every((id) => pathExists(provider === 'codex' ? path.join(providerRoot, 'skills', 'rails', id, 'SKILL.md')
-        : provider === 'kimi' ? path.join(providerRoot, 'skills', id, 'SKILL.md')
-            : path.join(providerRoot, 'agents', id + '.md')));
-}
 function workspaceHasManagedProviderLink(providerRoot, provider) {
     const directoryLinks = provider === 'claude'
         ? ['commands', 'skills', 'rules']
@@ -85,10 +66,11 @@ function workspaceHasManagedProviderLink(providerRoot, provider) {
     if (directoryLinks.some((relative) => isSymlink(path.join(providerRoot, relative)))) {
         return true;
     }
-    const granularRoot = provider === 'kimi'
-        ? path.join(providerRoot, 'skills')
-        : path.join(providerRoot, 'agents');
-    return listDir(granularRoot).some((entry) => isSymlink(entry));
+    // Kimi links its skills one directory at a time; claude/gemini have no
+    // granular region any more (role files are no longer linked per file).
+    if (provider !== 'kimi')
+        return false;
+    return listDir(path.join(providerRoot, 'skills')).some((entry) => isSymlink(entry));
 }
 /**
  * Refresh every provider already represented in the project plus the provider
@@ -110,9 +92,6 @@ function reassembleWorkspaceProviders(input) {
             version: input.version,
             codeRoot: input.codeRoot,
             scriptDir: input.scriptDir,
-            selectedAgents: provider === input.selectedProvider
-                ? input.selectedAgents ?? input.previousSelections[provider]
-                : input.previousSelections[provider],
             copyStatics: input.copyStatics,
         });
     }
@@ -142,10 +121,10 @@ export async function runInit(flags) {
         }
         explicitProvider = flags.provider;
     }
-    // --from-config: read provider + agents from yaml.
+    // --from-config: read the provider from yaml. The legacy `agents` section is
+    // validated (and warned about) by `loadInstallConfig`; roles are runtime-defined.
     const fromConfigFlag = flags['from-config'];
     let providerHint = explicitProvider;
-    let selectedAgentsHint;
     if (fromConfigFlag !== undefined) {
         const explicitPath = typeof fromConfigFlag === 'string' ? fromConfigFlag : undefined;
         const resolved = resolveConfigPath(repoRoot, explicitPath);
@@ -155,9 +134,7 @@ export async function runInit(flags) {
                 throw new InstallerError(`--provider '${explicitProvider}' conflicts with provider '${config.provider}' in ${resolved}`, 40);
             }
             providerHint = config.provider;
-            selectedAgentsHint = config.agents.selected;
             info(`Loaded install config from ${resolved}`);
-            warnUnknownSelectedAgents(selectedAgentsHint);
         }
         else {
             info(`install-config.yaml not found at ${resolved} — falling back to ${explicitProvider ? `explicit provider '${explicitProvider}'` : 'auto-detection'}`);
@@ -199,7 +176,7 @@ export async function runInit(flags) {
     // Bundled-framework flow: materialize the provider-INVARIANT framework ONCE
     // under `<home>/.specrails/framework/<version>/<providerDir>/`, point `current`
     // at it, then SYMLINK that copy into the workspace and seed the project layer
-    // (agent-memory, manifest, instruction files, gemini acks). The framework
+    // (manifest, instruction files). The framework
     // source for standalone npx is the package's templates/+commands/ (scriptDir).
     step('Phase 2 & 3: Installing specrails artifacts');
     const { providerDir } = derivedPaths(prereqs.provider);
@@ -228,7 +205,6 @@ export async function runInit(flags) {
                 provider: prereqs.provider,
                 providerDir,
                 version,
-                selectedAgents: selectedAgentsHint,
                 requiredProviders: Object.keys(previousSelections),
             });
             reassembleWorkspaceProviders({
@@ -238,7 +214,6 @@ export async function runInit(flags) {
                 codeRoot,
                 scriptDir,
                 selectedProvider: prereqs.provider,
-                selectedAgents: selectedAgentsHint,
                 previousSelections,
                 // In-repo: COPY the framework statics as real, committable files. Relocated:
                 // symlink from the framework store (O(1) update on a version swap).
@@ -255,7 +230,7 @@ export async function runInit(flags) {
             if (artifactRoot !== codeRoot)
                 recordSuccessfulInstall(repoRoot, { home: process.env.SPECRAILS_REGISTRY_HOME, providers: [prereqs.provider], coreVersion: version });
             step('Installation complete');
-            info('Agents, commands, and rules were placed directly — no follow-up step required.');
+            info('Commands and skills were placed directly — no follow-up step required.');
             // Terminal sentinel for programmatic consumers (specrails-desktop's setup
             // wizard matches this exact line via regex to mark the "init complete"
             // checkpoint). The sentinel line below is FROZEN — the downstream setup
@@ -268,22 +243,6 @@ export async function runInit(flags) {
         });
     });
 }
-/**
- * Warn (once per id) about `agents.selected` entries that have no shipped
- * template — typically a pre-v5 install-config.yaml still listing removed
- * agents. They are skipped at placement; the warning tells the user why and
- * points at the v5 extension path.
- */
-export function warnUnknownSelectedAgents(selected) {
-    if (!selected)
-        return;
-    for (const id of selected) {
-        if (!CORE_AGENTS.has(id)) {
-            warn(`install-config.yaml selects agent '${id}', which specrails-core no longer ships — ` +
-                `skipping (removed in v5).`);
-        }
-    }
-}
 /**
  * Materialize the framework for `(version, provider)` if absent and (by default)
  * point `<frameworkDir>/current` at that version. Idempotent — `installFramework`
@@ -304,7 +263,6 @@ export function ensureFramework(input) {
             provider: input.provider,
             providerDir: input.providerDir,
             version: input.version,
-            selectedAgents: input.selectedAgents,
         });
         return;
     }

package/dist/installer/phases/install-config.d.ts

@@ -20,7 +20,12 @@ interface InstallModelConfig {
 interface InstallConfig {
     version: 1;
     provider: Provider;
-    agents: {
+    /**
+     * Deprecated since Core 6.3: roles are runtime-defined, so the selection has
+     * no effect on the installed artifacts. Validated for shape when present and
+     * echoed back for consumers that still read it; absent when not supplied.
+     */
+    agents?: {
         selected: string[];
         excluded?: string[];
         /** Legacy pre-models-section location, accepted for backward compatibility. */
@@ -32,7 +37,8 @@ interface InstallConfig {
  * Resolve a preset into provider-native identifiers. Kimi currently exposes no
  * Core-defined cost/capability tier mapping, so every named preset resolves to
  * its explicit `k3` default. User-supplied exact identifiers are handled later
- * and are never interpreted as Claude aliases.
+ * and are never interpreted as Claude aliases. No preset carries per-role
+ * overrides: Core ships no role ids, so `models.overrides` is Desktop's to fill.
  */
 export declare function resolveProviderModelConfig(provider: Provider, preset?: ModelPreset): InstallModelConfig;
 export declare class InvalidConfigError extends InstallerError {

package/dist/installer/phases/install-config.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import yaml from 'js-yaml';
 import { FilesystemError, InstallerError } from '../util/errors.js';
 import { pathExists, readTextFile, writeFileLf } from '../util/fs.js';
+import { warn } from '../util/logger.js';
 const PROVIDER_DEFAULT_MODELS = {
     claude: 'sonnet',
     codex: 'gpt-5.5-mini',
@@ -25,7 +26,8 @@ const SAFE_KIMI_MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._/:-]{0,127}$/;
  * Resolve a preset into provider-native identifiers. Kimi currently exposes no
  * Core-defined cost/capability tier mapping, so every named preset resolves to
  * its explicit `k3` default. User-supplied exact identifiers are handled later
- * and are never interpreted as Claude aliases.
+ * and are never interpreted as Claude aliases. No preset carries per-role
+ * overrides: Core ships no role ids, so `models.overrides` is Desktop's to fill.
  */
 export function resolveProviderModelConfig(provider, preset = 'balanced') {
     if (provider === 'claude') {
@@ -33,11 +35,7 @@ export function resolveProviderModelConfig(provider, preset = 'balanced') {
             return { preset, defaults: { model: 'haiku' }, overrides: {} };
         }
         if (preset === 'max') {
-            return {
-                preset,
-                defaults: { model: 'sonnet' },
-                overrides: { 'sr-architect': 'opus' },
-            };
+            return { preset, defaults: { model: 'sonnet' }, overrides: {} };
         }
     }
     return {
@@ -109,13 +107,18 @@ export function validateInstallConfig(raw) {
     // NOTE: a legacy `tier` field (`full`/`quick`) may still be present in pre-v5
     // configs. It is intentionally ignored (not rejected and not carried forward)
     // — v5 has no install tiers.
+    // The `agents` section is OPTIONAL and deprecated: roles are runtime-defined
+    // since Core 6.3. When present it is still validated for shape (safe ids, no
+    // overlap, known preset) so a malformed file fails fast, and a non-empty
+    // selection logs one warning instead of being rejected — Desktop builds
+    // paired with an older Core still write it.
     const agents = doc.agents;
     let selectedAgents = [];
     let excludedAgents;
-    if (!agents || typeof agents !== 'object') {
-        errors.push(`missing required 'agents' section with 'selected' list`);
+    if (doc.agents !== undefined && (!agents || typeof agents !== 'object' || Array.isArray(agents))) {
+        errors.push(`'agents' must be a mapping`);
     }
-    else {
+    else if (agents) {
         if (!Array.isArray(agents.selected)) {
             errors.push(`'agents.selected' must be a list`);
         }
@@ -182,6 +185,10 @@ export function validateInstallConfig(raw) {
     if (errors.length > 0) {
         throw new InvalidConfigError(errors);
     }
+    if (selectedAgents.length > 0) {
+        warn(`install-config.yaml 'agents.selected' is ignored since Core 6.3: roles are ` +
+            `runtime-defined and no role file is installed (${selectedAgents.join(', ')}).`);
+    }
     const preset = (modelPreset ?? agents?.preset ?? 'balanced');
     const resolvedModels = resolveProviderModelConfig(provider, preset);
     if (typeof modelDefaults?.model === 'string') {
@@ -193,18 +200,18 @@ export function validateInstallConfig(raw) {
     const result = {
         version: 1,
         provider,
-        agents: {
-            selected: selectedAgents,
-        },
         models: resolvedModels,
     };
     // NOTE: a legacy `agent_teams` field may still be present in older configs.
     // It is intentionally ignored (not rejected) for backward compatibility.
-    if (agents?.preset !== undefined) {
-        result.agents.preset = agents.preset;
-    }
-    if (excludedAgents !== undefined) {
-        result.agents.excluded = excludedAgents;
+    if (agents) {
+        result.agents = { selected: selectedAgents };
+        if (agents.preset !== undefined) {
+            result.agents.preset = agents.preset;
+        }
+        if (excludedAgents !== undefined) {
+            result.agents.excluded = excludedAgents;
+        }
     }
     return result;
 }

package/dist/installer/phases/scaffold.d.ts

@@ -1,22 +1,4 @@
 import type { Provider } from './provider-detect.js';
-/**
- * The three baseline agents — the COMPLETE set of agents the installer
- * ships. The implement pipeline depends on all three. Any additional agent
- * comes from a user-authored profile (`custom-*`), never the installer.
- *
- * Mirrors the required built-in roles in schemas/agent-runtime.schema.json
- * (`agents`, with the sr- prefix in installed files); keep both in sync.
- */
-export declare const CORE_AGENTS: Set<string>;
-/**
- * Rewrite every literal `Skill("opsx:<id>"[, …])` call in a Claude-authored agent
- * body into the Gemini `activate_skill(name="…")` form. Positional skill input
- * (e.g. `"<specName>"`) is dropped because `activate_skill` takes only `name` and
- * the surrounding persona prose already carries the context. Unknown ids are left
- * untouched (better a visible stale ref than a silent `name="undefined"`). This
- * runs ONLY on the gemini render path; Claude/Codex keep the `Skill(...)` form.
- */
-export declare function translateOpsxSkillCallsForGemini(body: string): string;
 /**
  * Port shared Claude-authored prose to Kimi's directory-skill contract.
  *
@@ -28,7 +10,6 @@ export declare function translateOpsxSkillCallsForGemini(body: string): string;
  * This is render-only; canonical Claude/Codex/Gemini templates stay unchanged.
  */
 export declare function translateClaudeTextForKimi(body: string): string;
-export declare function geminiAgentLimitMetadata(env?: NodeJS.ProcessEnv): string[];
 /**
  * Phase 2 + Phase 3 of init:
  *   - Detect prior installation state (.claude/.codex/openspec already present).
@@ -37,9 +18,11 @@ export declare function geminiAgentLimitMetadata(env?: NodeJS.ProcessEnv): strin
  *     staging dir that placement copies from and `update` diffs against).
  *   - Ensure `.gitignore` excludes the runtime artefacts.
  *
- * Placement (`placeArtefacts`) then copies the staged templates directly into
- * the user's live `.claude/agents/` and `.claude/commands/specrails/` dirs so
- * the installer finishes in one pass — no follow-up wizard required.
+ * Placement (`placeArtefacts`) then renders the staged command templates
+ * directly into the user's live provider dir (`.claude/commands/specrails/`,
+ * `.codex/skills/`, …) so the installer finishes in one pass — no follow-up
+ * wizard required. Roles are never placed: the programmatic runtime defines
+ * them (`src/agent-runtime/prompts.ts`).
  */
 interface ScaffoldInput {
     /** Absolute path to the specrails-core package (installed via npx). */
@@ -60,25 +43,6 @@ interface ScaffoldInput {
     provider: Provider;
     /** Derived directory name (`.claude` or `.codex`). */
     providerDir: string;
-    /** Optional explicit allow-list used by config-driven installs. */
-    selectedAgents?: string[];
-    /**
-     * When false, the static-placement helpers do NOT create the per-workspace
-     * mutable seeds (agent-memory dirs, gemini headless acknowledgments). Used by
-     * `installFramework` so the SHARED framework copy stays purely provider-static
-     * — the project layer is seeded separately by `assembleProjectWorkspace`.
-     * Defaults to true (legacy in-place behaviour for `scaffoldInstallation`).
-     */
-    seedProjectDirs?: boolean;
-    /**
-     * When true, place EVERY agent template (the full superset) regardless of
-     * `selectedAgents`. Used by `installFramework` so
-     * the SHARED framework store is a superset that ANY project's selection can
-     * link from — per-project agent filtering then happens at the workspace LINK
-     * step (`linkAgentFiles`), not at materialization. Defaults to false (legacy
-     * selection-honouring placement for in-place `scaffoldInstallation`).
-     */
-    materializeAllAgents?: boolean;
 }
 interface ScaffoldResult {
     existingSetup: boolean;
@@ -106,8 +70,6 @@ interface InstallFrameworkInput {
     providerDir: string;
     /** Framework version (the `<version>/` segment). */
     version: string;
-    /** Optional explicit agent allow-list (kept for parity with scaffold). */
-    selectedAgents?: string[];
 }
 interface InstallFrameworkResult {
     /** `<frameworkDir>/<version>/<providerDir>` — root of the static subtree. */
@@ -130,8 +92,8 @@ export declare function frameworkMaterializationProblem(versionDir: string, vers
  * `<frameworkDir>/<version>/<providerDir>/` (+ `<version>/setup-templates/`).
  * Idempotent: when the providerDir already exists with a matching stamp it is a
  * no-op (the second workspace assemble re-uses the same copy). Writes NO
- * per-workspace state (no agent-memory, no acks, no project-named instruction
- * files) — those are seeded by `assembleProjectWorkspace`.
+ * per-workspace state (no project-named instruction files) — those are seeded
+ * by `assembleProjectWorkspace`.
  */
 export declare function installFramework(input: InstallFrameworkInput): InstallFrameworkResult;
 /**
@@ -150,26 +112,18 @@ interface AssembleProjectWorkspaceInput {
     providerDir: string;
     /** Framework version (used for the manifest record). */
     version: string;
-    /** The user's real repo (drives PROJECT_NAME + gemini ack keying). */
+    /** The user's real repo (drives PROJECT_NAME). */
     codeRoot: string;
     /** specrails-core package dir (for the manifest hash sources). */
     scriptDir: string;
     /**
-     * Optional agent allow-list. Drives BOTH which framework agents are LINKED
-     * into the workspace (`linkAgentFiles`) AND which agent-memory dirs are seeded.
-     * Undefined = the CORE trio only (the lean default). The SHARED framework store
-     * is always the full superset; this is where per-project filtering happens.
-     */
-    selectedAgents?: string[];
-    /**
-     * When true, the static provider subtrees (`agents`/`commands`/`skills`/`rules`)
+     * When true, the static provider subtrees (`commands`/`skills`/`specrails`)
      * and the settings file are COPIED as real files from the framework store into
      * the workspace instead of SYMLINKED. Used by the in-repo standalone install
      * (`init`/`update` with `artifactRoot === codeRoot`) so the repo gets real,
      * committable files — a symlink into `$HOME/.specrails/framework` would be
      * invisible to a standalone user's `claude`/`codex`/`gemini`/`kimi` running in the
-     * repo. The PROJECT layer (agent-memory, manifest, instruction files) is real
-     * either way. Defaults to false (relocated workspaces symlink — the desktop /
+     * repo. The PROJECT layer (manifest, instruction files) is real either way. Defaults to false (relocated workspaces symlink — the desktop /
      * `--relocate` path).
      */
     copyStatics?: boolean;
@@ -177,34 +131,28 @@ interface AssembleProjectWorkspaceInput {
 interface AssembleProjectWorkspaceResult {
     /** Per-linked-subtree mechanism, for diagnostics (copy-fallback loses O(1) swap). */
     links: Record<string, 'symlink' | 'junction' | 'copy'>;
-    /** Agent ids whose memory dirs were seeded as real writable dirs. */
-    seededMemoryAgents: string[];
 }
 /**
  * Assemble a project workspace with NO network and NO re-materialization: (a)
- * SYMLINK the static providerDir subtrees from `<frameworkDir>/current/
- * <providerDir>/` into `<workspace>/<providerDir>/`, then (b) seed the PROJECT
- * layer as real writable files (agent-memory dirs, the manifest, project-named
- * instruction/settings files, gemini headless acks re-hashed against the LINKED
- * files). `agent-memory/` is NEVER linked.
+ * prune the framework-owned `sr-*` role artifacts an older Core linked or
+ * copied into the workspace, (b) SYMLINK the static providerDir subtrees from
+ * `<frameworkDir>/current/<providerDir>/` into `<workspace>/<providerDir>/`,
+ * then (c) seed the PROJECT layer as real writable files (the manifest,
+ * project-named instruction/settings files). Reserved `custom-*` files are
+ * never touched.
  */
 export declare function assembleProjectWorkspace(input: AssembleProjectWorkspaceInput): AssembleProjectWorkspaceResult;
 /**
- * Pre-acknowledge the generated gemini subagents so they load in HEADLESS
- * (`gemini -p`) runs. gemini 0.46+ DISCOVERS `.gemini/agents/*.md` but only
- * ENABLES a project's custom agents after the interactive "New Agents Discovered
- * → Acknowledge and Enable" prompt — which never fires headless, so
- * `invoke_agent sr-architect` returns "Subagent not found" and the implement
- * orchestrator silently falls back to a generic agent (the specialised personas
- * never run, the pipeline degrades). The acknowledgment is a user-global file
- * `~/.gemini/acknowledgments/agents.json` shaped
- * `{ [projectRoot]: { [agentName]: <sha256-hex of the agent .md file> } }`
- * (hash algorithm verified empirically against gemini 0.47 = sha256 of the full
- * file). Writing it at install time makes the freshly-generated agents trusted
- * with no prompt, for both `gemini` CLI and the desktop's headless spawns. The
- * file is MERGED — other projects' and other agents' entries are preserved.
- * Best-effort: any failure is swallowed by the caller (agents still work once
- * acknowledged interactively).
+ * Remove the role artifacts an older Core linked or copied into a workspace:
+ *   - claude, gemini: `agents/sr-*.md` (symlink or copy-fallback regular file)
+ *   - codex:          `skills/rails/sr-*` and the `rails/` container once empty
+ *   - kimi:           `skills/sr-*`
+ *
+ * Keyed strictly by NAME, never by content: `custom-*` (the reserved
+ * user/Desktop region) and any unknown name are left byte-untouched. A
+ * subtree that is itself a symlink into the shared framework store is skipped —
+ * the store is Core-owned and rebuilt by `installFramework`, so pruning through
+ * the link would only reach into another version's files.
  */
-export declare function writeGeminiAgentAcknowledgments(repoRoot: string, agentIds: string[], agentsBaseDir?: string): void;
+export declare function pruneStaleRoleArtifacts(workspaceProviderDir: string, provider: Provider): void;
 export {};