specrails-core 4.12.1 → 5.1.0

package/dist/installer/phases/scaffold.js

@@ -1,15 +1,14 @@
-import { createHash } from 'node:crypto';
-import { renameSync, rmSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants, cpSync, mkdtempSync, renameSync, rmSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { atomicSymlinkSwap, copyDir, copyFile, isDir, isSymlink, listDir, mkdirp, pathExists, readBytes, readTextFile, removePath, symlinkOrCopy, writeFileLf, } from '../util/fs.js';
 import { info, ok, warn } from '../util/logger.js';
 import { buildManifest, writeManifestFiles } from './manifest.js';
 /**
- * The three baseline agents that every specrails install requires.
- * These are the only agents guaranteed to be present — the implement
- * pipeline depends on all three. sr-merge-resolver and every other
- * agent are optional add-ons selected at install time.
+ * 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 `allOf` baseline in schemas/profile.v1.json — update
  * both files together if this set ever changes.
@@ -19,11 +18,6 @@ export const CORE_AGENTS = new Set([
     'sr-developer',
     'sr-reviewer',
 ]);
-/**
- * Agents excluded from the quick tier because they require a full
- * /specrails:enrich persona pass to function correctly.
- */
-const QUICK_EXCLUDED_AGENTS = new Set(['sr-product-manager', 'sr-product-analyst']);
 /**
  * Gemini built-in tool ids granted to every `.gemini/agents/sr-*.md` subagent.
  * (Validated headless in the desktop spike — read/write/shell/glob/grep.) Because
@@ -132,23 +126,17 @@ const GEMINI_MODEL_BY_AGENT = {
     'sr-reviewer': 'gemini-3.5-flash',
 };
 const GEMINI_DEFAULT_MODEL = 'gemini-3.5-flash';
-// NOTE: do NOT emit a `max_turns` (or `maxTurns`/`runConfig`) key in the gemini
-// agent frontmatter. Although gemini's documented agent schema lists `max_turns`,
-// the 0.46 runtime loader REJECTS a `.gemini/agents/*.md` file that carries it —
-// the agent silently fails to register and `invoke_agent` reports "Subagent
-// '<name>' not found", so the orchestrator falls back to a generic agent and the
-// specialised personas never run. Verified empirically (two identical agents,
-// one with `max_turns: 40` → not found, one without → loads). The 30-turn default
-// cap is instead absorbed by the implement.toml MAX_TURNS → re-delegate/resume
-// contract. Re-introduce only if a future gemini build is reconfirmed to accept it.
-/**
- * Skills excluded from the quick tier because they depend on
- * VPC-only agents (sr-product-manager, sr-product-analyst).
- */
-const QUICK_EXCLUDED_SKILLS = new Set([
-    'sr-auto-propose-backlog-specs',
-    'sr-get-backlog-specs',
-]);
+// Older Gemini loaders reject optional agent-limit fields. Opt in only after
+// the caller verified the installed loader capability; never guess from a model.
+export function geminiAgentLimitMetadata(env = process.env) {
+    if (env.SPECRAILS_GEMINI_AGENT_LIMITS !== 'supported')
+        return [];
+    const value = Number(env.SPECRAILS_GEMINI_MAX_TURNS ?? '60');
+    if (!Number.isInteger(value) || value < 1 || value > 200) {
+        throw new Error('SPECRAILS_GEMINI_MAX_TURNS must be an integer from 1 to 200');
+    }
+    return [`max_turns: ${value}`];
+}
 /**
  * Claude top-level `sr-*` skills, GENERATED at install time from their
  * canonical slash-command body under `templates/commands/specrails/<command>.md`.
@@ -178,26 +166,7 @@ const SKILL_FROM_COMMAND = {
         command: 'why',
         description: 'sr:why — Search explanation records written by specrails agents during the OpenSpec implementation pipeline.',
     },
-    'sr-get-backlog-specs': {
-        command: 'get-backlog-specs',
-        description: 'sr:get-backlog-specs — View product-driven backlog from GitHub Issues and propose top 3 for implementation.',
-    },
-    'sr-auto-propose-backlog-specs': {
-        command: 'auto-propose-backlog-specs',
-        description: 'sr:auto-propose-backlog-specs — Generate new feature ideas through product discovery, create GitHub Issues.',
-    },
 };
-/**
- * Command → required agent dependency map. A command is excluded
- * from the quick tier when its required agent was excluded (i.e.
- * VPC-dependent) or when the feature flag (Agent Teams) is off.
- */
-const COMMAND_AGENT_DEPENDENCIES = [
-    { command: 'auto-propose-backlog-specs', requires: ['sr-product-manager'] },
-    { command: 'vpc-drift', requires: ['sr-product-manager', 'sr-product-analyst'] },
-    { command: 'get-backlog-specs', requires: ['sr-product-analyst'] },
-    { command: 'merge-resolve', requires: ['sr-merge-resolver'] },
-];
 /**
  * Agents that write "explanation" memory records. When any of them
  * ships we also need a shared `.claude/agent-memory/explanations/`
@@ -255,6 +224,7 @@ export function detectExistingSetup(input) {
  * .gitignore. Returns a summary for logging / tests.
  */
 export function scaffoldInstallation(input) {
+    assertPipelineRuntimeSource(input.scriptDir);
     const createdDirs = [];
     let copiedFiles = 0;
     const mk = (abs) => {
@@ -267,15 +237,15 @@ export function scaffoldInstallation(input) {
         // Codex skills live under <providerDir>/skills/ (e.g. .codex/skills/).
         // The pre-§18 code wrote to `.agents/skills/` which codex doesn't read;
         // that was a placeholder name from the gated state.
-        mk(path.join(input.artifactRoot, input.providerDir, 'skills', 'enrich'));
         mk(path.join(input.artifactRoot, input.providerDir, 'skills', 'doctor'));
         mk(path.join(input.artifactRoot, input.providerDir, 'skills', 'rails'));
     }
     else if (input.provider === 'gemini') {
         // Gemini: TOML commands under .gemini/commands/specrails/ + native
-        // subagents under .gemini/agents/. No skills/ tree.
+        // subagents and OpenSpec skills both live in the execution workspace.
         mk(path.join(input.artifactRoot, input.providerDir, 'commands', 'specrails'));
         mk(path.join(input.artifactRoot, input.providerDir, 'agents'));
+        mk(path.join(input.artifactRoot, input.providerDir, 'skills'));
     }
     else if (input.provider === 'kimi') {
         mk(path.join(input.artifactRoot, input.providerDir, 'skills'));
@@ -291,7 +261,6 @@ export function scaffoldInstallation(input) {
     mk(path.join(setupTemplates, 'commands'));
     mk(path.join(setupTemplates, 'skills'));
     mk(path.join(setupTemplates, 'rules'));
-    mk(path.join(setupTemplates, 'personas'));
     mk(path.join(setupTemplates, 'claude-md'));
     mk(path.join(setupTemplates, 'settings'));
     // --- .gitignore hygiene ---
@@ -327,19 +296,19 @@ export function scaffoldInstallation(input) {
     else {
         warn(`templates/ not found at ${templatesSrc} — skipping template copy`);
     }
-    // --- Write bundled commands (enrich.md + doctor.md) ---
+    // --- Write bundled commands (doctor.md) ---
     copyBundledCommands({ ...input, copiedIncrement: (n) => (copiedFiles += n) });
     pruneLegacyArtifacts(input);
+    copiedFiles += placePipelineRuntime(input);
     if (input.provider === 'kimi') {
         copiedFiles += placeKimiSkillRunner(input);
     }
-    // --- Quick tier: direct-placement short-circuit ---
-    if (input.tier === 'quick') {
-        const placed = placeQuickTierArtefacts({ ...input });
+    // --- Direct placement (the only path) ---
+    {
+        const placed = placeArtefacts({ ...input });
         copiedFiles += placed.agents + placed.commands + placed.rules;
-        const skippedNote = placed.skippedAgents > 0 ? ` (skipped ${placed.skippedAgents} VPC-dependent)` : '';
-        info(`Quick tier: placed ${placed.agents} agent(s) + ${placed.commands} command(s) + ` +
-            `${placed.rules} rule file(s) directly into ${input.providerDir}/${skippedNote}`);
+        info(`Placed ${placed.agents} agent(s) + ${placed.commands} command(s) + ` +
+            `${placed.rules} rule file(s) directly into ${input.providerDir}/`);
     }
     // --- Skills placement (both tiers, both providers) ---
     // Claude: top-level `sr-*` skills are generated from their canonical
@@ -349,10 +318,24 @@ export function scaffoldInstallation(input) {
     {
         const skills = placeSkills(input);
         copiedFiles += skills.filesCopied;
-        const skillSkipNote = skills.skipped > 0 ? ` (skipped ${skills.skipped} VPC-dependent)` : '';
         const skillsLabel = input.provider === 'gemini' ? 'agent' : 'skill';
         const skillsSubdir = input.provider === 'gemini' ? 'agents' : 'skills';
-        info(`Placed ${skills.placed} ${skillsLabel}(s) into ${input.providerDir}/${skillsSubdir}/${skillSkipNote}`);
+        info(`Placed ${skills.placed} ${skillsLabel}(s) into ${input.providerDir}/${skillsSubdir}/`);
+    }
+    const pipelineContract = providerPipelineContract(input.scriptDir);
+    if (input.provider === 'codex') {
+        for (const name of ['implement', 'batch-implement', 'retry']) {
+            prependSkillContract(path.join(input.artifactRoot, '.codex', 'skills', name, 'SKILL.md'), pipelineContract);
+        }
+    }
+    else if (input.provider === 'gemini') {
+        for (const name of ['implement', 'batch-implement', 'retry']) {
+            const file = path.join(input.artifactRoot, '.gemini', 'commands', 'specrails', `${name}.toml`);
+            if (pipelineContract && pathExists(file)) {
+                const source = readTextFile(file);
+                writeFileLf(file, source.replace("prompt = '''\n", "prompt = '''\n" + pipelineContract));
+            }
+        }
     }
     // --- Codex provider settings + AGENTS.md initial content ---
     if (input.provider === 'codex') {
@@ -376,20 +359,6 @@ export function scaffoldInstallation(input) {
             info(`Kimi provider: wrote ${written} setting file(s) (.kimi-code/AGENTS.md, mcp.json)`);
         }
     }
-    // --- Full-tier hint: enrich is required to generate VPC artefacts ---
-    if (input.tier === 'full') {
-        const cliName = input.provider === 'codex'
-            ? 'Codex CLI'
-            : input.provider === 'gemini'
-                ? 'Gemini CLI'
-                : input.provider === 'kimi'
-                    ? 'Kimi CLI'
-                    : 'Claude Code';
-        const enrichCommand = input.provider === 'kimi' ? '/skill:specrails-enrich' : '/specrails:enrich';
-        info(`Full tier staged. Run \`${enrichCommand}\` in ${cliName} to generate ` +
-            'VPC personas and adapt agents (including sr-product-manager and ' +
-            'sr-product-analyst) to this codebase.');
-    }
     ok(`Created ${createdDirs.length} directories, copied ${copiedFiles} files`);
     return {
         existingSetup: detectExistingSetup({
@@ -453,6 +422,8 @@ function frameworkSourceHash(scriptDir, provider) {
     const treeHash = hashFrameworkTrees([
         { label: 'templates', dir: path.join(scriptDir, 'templates') },
         { label: 'commands', dir: path.join(scriptDir, 'commands') },
+        { label: 'pipeline-runtime', dir: path.join(scriptDir, 'dist', 'installer', 'runtime') },
+        { label: 'installer-renderers', dir: path.join(scriptDir, 'dist', 'installer', 'phases') },
     ], { ignorePackageNoise: true });
     return `sha256:${createHash('sha256')
         .update(treeHash)
@@ -464,6 +435,7 @@ function frameworkSourceHash(scriptDir, provider) {
 function frameworkContentHash(providerFrameworkDir) {
     return hashFrameworkTrees([
         { label: 'provider', dir: providerFrameworkDir },
+        { label: 'pipeline-runtime', dir: path.join(path.dirname(providerFrameworkDir), '.specrails', 'runtime') },
     ]);
 }
 function readFrameworkStamp(stampPath) {
@@ -530,60 +502,91 @@ export function installFramework(input) {
         stamp.content_hash === frameworkContentHash(providerFrameworkDir)) {
         return { providerFrameworkDir, versionDir, materialized: false };
     }
-    // Framework provider trees are entirely Core-owned. Rebuilding from a clean
-    // destination removes stale files as well as repairing corrupt/missing ones,
-    // without touching sibling providers already materialized in this version.
-    removePath(providerFrameworkDir);
-    removePath(stampPath);
-    // Reuse scaffoldInstallation's static-placement helpers by pointing
-    // `artifactRoot` at the version dir. `seedProjectDirs: false` keeps the copy
-    // free of per-workspace mutable state. The `codeRoot` is irrelevant to the
-    // STATIC subtree (the project-named instruction files are skipped below), so
-    // we hand it the framework dir to satisfy the contract — and we DELETE any
-    // project-named instruction file the settings helpers wrote.
-    // The SHARED framework store is always the FULL SUPERSET — EVERY agent — so a
-    // SECOND project with a DIFFERENT agent selection links its specialists from
-    // the same materialized copy instead of inheriting the first project's
-    // narrower set. Per-project filtering moves to the workspace LINK step
-    // (`linkAgentFiles` via `assembleProjectWorkspace`). `selectedAgents` on the
-    // input is intentionally IGNORED here.
-    const staticInput = {
-        scriptDir: input.scriptDir,
-        artifactRoot: versionDir,
-        codeRoot: versionDir,
-        provider: input.provider,
-        providerDir: input.providerDir,
-        tier: 'quick',
-        selectedAgents: undefined,
-        materializeAllAgents: true,
-        seedProjectDirs: false,
-    };
-    scaffoldInstallation(staticInput);
-    // The settings helpers also emit a project-named root instruction file
-    // (AGENTS.md/GEMINI.md/CLAUDE.md) + (for codex) config.toml / (gemini)
-    // settings.json. The instruction file is per-project → strip it from the
-    // shared copy; the settings file IS provider-invariant and stays as a
-    // link target inside the providerDir.
-    for (const f of ['AGENTS.md', 'GEMINI.md', 'CLAUDE.md']) {
-        rmSync(path.join(versionDir, f), { force: true });
-    }
-    // Kimi's instruction and MCP files are provider-local rather than root-local,
-    // but both are project-specific and must be real files in each workspace.
-    // In particular, linking mcp.json would let Desktop mutate the shared
-    // framework and leak one project's MCP registry into every other project.
-    if (input.provider === 'kimi') {
-        rmSync(path.join(providerFrameworkDir, 'AGENTS.md'), { force: true });
-        rmSync(path.join(providerFrameworkDir, 'mcp.json'), { force: true });
+    mkdirp(input.frameworkDir);
+    const stageRoot = mkdtempSync(path.join(input.frameworkDir, '.materialize-'));
+    const stagedVersionDir = path.join(stageRoot, input.version);
+    const stagedProviderDir = path.join(stagedVersionDir, input.providerDir);
+    const stagedStampPath = frameworkStampPath(stagedVersionDir, input.providerDir);
+    try {
+        // Preserve all sibling providers while rebuilding the requested provider.
+        // The stage is new: JS traversal keeps these copies away from Node 22's
+        // native Unicode directory-copy defect on Windows (nodejs/node#61878).
+        if (isDir(versionDir))
+            cpSync(versionDir, stagedVersionDir, { recursive: true, dereference: false, verbatimSymlinks: true, filter: () => true, mode: constants.COPYFILE_FICLONE });
+        else
+            mkdirp(stagedVersionDir);
+        // Framework provider trees are entirely Core-owned. Rebuilding from a clean
+        // destination removes stale files as well as repairing corrupt/missing ones,
+        // without touching sibling providers already materialized in this version.
+        removePath(stagedProviderDir);
+        removePath(stagedStampPath);
+        // Reuse scaffoldInstallation's static-placement helpers by pointing
+        // `artifactRoot` at the version dir. `seedProjectDirs: false` keeps the copy
+        // free of per-workspace mutable state. The `codeRoot` is irrelevant to the
+        // STATIC subtree (the project-named instruction files are skipped below), so
+        // we hand it the framework dir to satisfy the contract — and we DELETE any
+        // project-named instruction file the settings helpers wrote.
+        // The SHARED framework store is always the FULL SUPERSET — EVERY agent — so a
+        // SECOND project with a DIFFERENT agent selection links its specialists from
+        // the same materialized copy instead of inheriting the first project's
+        // narrower set. Per-project filtering moves to the workspace LINK step
+        // (`linkAgentFiles` via `assembleProjectWorkspace`). `selectedAgents` on the
+        // input is intentionally IGNORED here.
+        const staticInput = {
+            scriptDir: input.scriptDir,
+            artifactRoot: stagedVersionDir,
+            codeRoot: versionDir,
+            provider: input.provider,
+            providerDir: input.providerDir,
+            selectedAgents: undefined,
+            materializeAllAgents: true,
+            seedProjectDirs: false,
+        };
+        scaffoldInstallation(staticInput);
+        // The settings helpers also emit a project-named root instruction file
+        // (AGENTS.md/GEMINI.md/CLAUDE.md) + (for codex) config.toml / (gemini)
+        // settings.json. The instruction file is per-project → strip it from the
+        // shared copy; the settings file IS provider-invariant and stays as a
+        // link target inside the providerDir.
+        for (const f of ['AGENTS.md', 'GEMINI.md', 'CLAUDE.md']) {
+            rmSync(path.join(stagedVersionDir, f), { force: true });
+        }
+        // Kimi's instruction and MCP files are provider-local rather than root-local,
+        // but both are project-specific and must be real files in each workspace.
+        // In particular, linking mcp.json would let Desktop mutate the shared
+        // framework and leak one project's MCP registry into every other project.
+        if (input.provider === 'kimi') {
+            rmSync(path.join(stagedProviderDir, 'AGENTS.md'), { force: true });
+            rmSync(path.join(stagedProviderDir, 'mcp.json'), { force: true });
+        }
+        const frameworkStamp = {
+            schema: 1,
+            version: input.version,
+            provider: input.provider,
+            source_hash: sourceHash,
+            content_hash: frameworkContentHash(stagedProviderDir),
+        };
+        writeFileLf(stagedStampPath, `${JSON.stringify(frameworkStamp, null, 2)}\n`);
+        // Keep the previous complete version outside the disposable staging root.
+        // It remains available for manual recovery even after successful publication.
+        const previous = path.join(input.frameworkDir, `.previous-${input.version}-${randomUUID()}`);
+        const hadPrevious = pathExists(versionDir);
+        if (hadPrevious)
+            renameSync(versionDir, previous);
+        try {
+            renameSync(stagedVersionDir, versionDir);
+        }
+        catch (error) {
+            if (hadPrevious)
+                renameSync(previous, versionDir);
+            throw error;
+        }
+        return { providerFrameworkDir, versionDir, materialized: true };
+    }
+    finally {
+        // This contains only newly generated candidate files, never the prior version.
+        rmSync(stageRoot, { recursive: true, force: true });
     }
-    const frameworkStamp = {
-        schema: 1,
-        version: input.version,
-        provider: input.provider,
-        source_hash: sourceHash,
-        content_hash: frameworkContentHash(providerFrameworkDir),
-    };
-    writeFileLf(stampPath, `${JSON.stringify(frameworkStamp, null, 2)}\n`);
-    return { providerFrameworkDir, versionDir, materialized: true };
 }
 /**
  * Atomically point `<frameworkDir>/current` at `<version>` so every workspace's
@@ -663,6 +666,10 @@ export function assembleProjectWorkspace(input) {
             links[settingsFile] = symlinkOrCopy(settingsTarget, settingsLink, preferCopy);
         }
     }
+    const runtimeTarget = path.join(input.frameworkDir, 'current', '.specrails', 'runtime');
+    if (pathExists(runtimeTarget)) {
+        links.pipelineRuntime = symlinkOrCopy(runtimeTarget, path.join(input.workspace, '.specrails', 'runtime'), preferCopy);
+    }
     // (b) Seed the PROJECT layer (real writable files / dirs).
     const seededMemoryAgents = seedProjectLayer(input, currentProviderDir);
     // Manifest: record the consumed framework version. `buildManifest` hashes the
@@ -697,7 +704,7 @@ function seedProjectLayer(input, currentProviderDir) {
             if (!name.endsWith('.md'))
                 continue;
             const id = name.slice(0, -3);
-            if (selected.has(id) && !QUICK_EXCLUDED_AGENTS.has(id))
+            if (selected.has(id))
                 placedAgentIds.push(id);
         }
     }
@@ -743,7 +750,6 @@ function seedProjectLayer(input, currentProviderDir) {
                 const id = path.basename(roleDir);
                 if (/^sr-[a-z0-9-]+$/.test(id) &&
                     selected.has(id) &&
-                    !QUICK_EXCLUDED_AGENTS.has(id) &&
                     pathExists(path.join(roleDir, 'SKILL.md'))) {
                     placedAgentIds.push(id);
                 }
@@ -799,10 +805,10 @@ function seedKimiMcpFile(mcpPath) {
  * every SELECTED framework-owned agent at the shared read-only copy.
  *
  * `selectedIds` is the per-project agent allow-list (already unioned with the
- * CORE trio by the caller). Only framework agents whose id is in it AND not in
- * `QUICK_EXCLUDED_AGENTS` are linked — the shared framework store is the full
- * superset, so this is where per-project filtering lands. `undefined` ⇒ link
- * every framework agent (used by the legacy callers / parity tests).
+ * CORE trio by the caller). Only framework agents whose id is in it are linked —
+ * the shared framework store is the full superset, so this is where per-project
+ * filtering lands. `undefined` ⇒ link every framework agent (used by the legacy
+ * callers / parity tests).
  *
  * When `preferCopy` is true each agent is COPIED as a real file rather than
  * symlinked (the in-repo standalone install — so a standalone user's CLI finds
@@ -826,7 +832,7 @@ function linkAgentFiles(frameworkAgentsDir, workspaceAgentsDir, selectedIds, pre
             continue;
         frameworkProvided.add(name);
         const id = name.slice(0, -3);
-        if (selectedIds && (!selectedIds.has(id) || QUICK_EXCLUDED_AGENTS.has(id)))
+        if (selectedIds && !selectedIds.has(id))
             continue;
         linkedNames.add(name);
         const m = symlinkOrCopy(src, path.join(workspaceAgentsDir, name), preferCopy);
@@ -886,8 +892,7 @@ function linkKimiSkillDirectories(frameworkSkillsDir, workspaceSkillsDir, select
             // it, but never expose nested roles if a caller supplies one directly.
             continue;
         }
-        if (/^sr-[a-z0-9-]+$/.test(name) &&
-            (!selectedRoleIds.has(name) || QUICK_EXCLUDED_AGENTS.has(name))) {
+        if (/^sr-[a-z0-9-]+$/.test(name) && !selectedRoleIds.has(name)) {
             continue;
         }
         linkedFrameworkNames.add(name);
@@ -1008,9 +1013,8 @@ function copyBundledCommands(input) {
             const destDir = path.join(input.artifactRoot, input.providerDir, 'skills', skillName);
             // A codex-native override (written for spawn_agent semantics + the
             // correct `.codex/skills/rails/` layout) wins over the claude port.
-            // This is the ONLY codex command-placement pass in full tier, so
-            // without the override check full-tier codex users get the claude
-            // body — e.g. enrich's obsolete `.codex/agents/*.toml` model.
+            // This is the ONLY codex command-placement pass, so without the override
+            // check codex users get the claude body with no codex-native semantics.
             const overrideSkill = path.join(codexOverrides, skillName, 'SKILL.md');
             if (pathExists(overrideSkill)) {
                 copyDir(path.join(codexOverrides, skillName), destDir);
@@ -1179,7 +1183,9 @@ const KIMI_ROLE_EXECUTION_CONTRACT = [
     'Every `key`, profile stem, and worktree id uses the same 1–64 character grammar as `run`.',
     'Use `"current"` for roles that target the orchestrator repository. The',
     'helper gives each such role a private execution directory while setting its',
-    '`SPECRAILS_REPO_DIR` to that repository, so nested calls and run-state do not',
+    '`SPECRAILS_REPO_DIR` to that repository. The child preserves the absolute',
+    '`SPECRAILS_EXECUTION_CONTEXT`, `SPECRAILS_BACKLOG_PATH` and pipeline helper.',
+    'Read the frozen specs there; never infer task scope from the child cwd. Nested calls do not',
     'collide. Where later instructions request `isolation: worktree`, use',
     '`"worktree:<feature-id>"`; reuse that exact value for the developer, test,',
     'documentation, and other sequential roles belonging to the same feature.',
@@ -1255,8 +1261,9 @@ const KIMI_RUNTIME_CONTEXT_CONTRACT = [
     'configured”, never fabricated rows or scores.',
     '',
     'For every `KIMI_BACKLOG_*` marker, first read and validate',
-    '`.specrails/backlog-config.json`. Route `local` through structured reads and',
-    'atomic writes of `.specrails/local-tickets.json`; route `github` through the',
+    '`${SPECRAILS_BACKLOG_ROOT}/.specrails/backlog-config.json` when configured.',
+    'The frozen execution context takes priority. Route `local` through',
+    '`${SPECRAILS_BACKLOG_PATH}` only when ownership allows writes; route `github` through the',
     'approved `gh issue` operation; route `jira` only through the configured',
     'project/base URL and credentials. Honour read-only mode and never perform a',
     'write operation when configuration is missing, invalid, or read-only.',
@@ -1346,7 +1353,7 @@ function writeKimiWorkflowSkill(args) {
         ...args.placeholders,
         MEMORY_PATH: '.kimi-code/agent-memory/',
     }).replaceAll('.specrails/profiles/project-default.json', '.specrails/profiles/kimi-default.json');
-    const rendered = translateClaudeTextForKimi(adaptKimiWorkflowBody(args.commandName, providerNeutral));
+    const rendered = translateClaudeTextForKimi(adaptKimiWorkflowBody(args.commandName, providerNeutral)).replaceAll('.specrails/local-tickets.json', '${SPECRAILS_BACKLOG_PATH}');
     const frontmatter = [
         '---',
         `name: ${skillName}`,
@@ -1359,6 +1366,8 @@ function writeKimiWorkflowSkill(args) {
         '',
     ].join('\n');
     writeFileLf(args.dest, frontmatter +
+        (pathExists(path.join(path.dirname(args.src), '..', '..', 'runtime', 'provider-pipeline.md'))
+            ? readTextFile(path.join(path.dirname(args.src), '..', '..', 'runtime', 'provider-pipeline.md')) + '\n' : '') +
         KIMI_NESTED_SKILL_CONTRACT +
         KIMI_ROLE_EXECUTION_CONTRACT +
         KIMI_RUNTIME_CONTEXT_CONTRACT +
@@ -1385,182 +1394,25 @@ function adaptKimiWorkflowBody(commandName, body) {
     }
     if (commandName !== 'implement')
         return body;
-    let adapted = replaceMarkdownSection(body, '##### Apply per-agent model overrides (profile mode only)', '##### Legacy mode — preserve current behavior', [
-        '##### Resolve per-role model overrides (profile mode only)',
-        '',
-        'Keep each `AGENT_MODEL[id]` value exactly as declared in the profile.',
-        'Do **not** rewrite role `SKILL.md` frontmatter: Kimi directory skills do',
-        'not carry per-role model configuration. In the orchestrator, resolve the',
-        'role id against the parsed `AGENT_MODEL` map, then write the exact result',
-        'into that role wave entry\'s JSON `model` field using WriteFile. Use',
-        'the provider default `k3` when absent; never depend on a shell array from',
-        'a previous tool call. Only the official short ids `k3`,',
-        '`kimi-for-coding`, and `kimi-for-coding-highspeed` gain the',
-        '`kimi-code/` prefix at the CLI boundary. Never map Claude aliases.',
-        '',
-    ].join('\n'));
-    adapted = replaceMarkdownSection(adapted, '##### Legacy mode — preserve current behavior', '##### Agent roles (both modes)', [
-        '##### Legacy mode — preserve current behavior',
-        '',
-        'If no profile is active, discover role directories without mutating them:',
-        '',
-        '```bash',
-        'AVAILABLE_AGENTS="$(find -L .kimi-code/skills -mindepth 2 -maxdepth 2 \\',
-        '  -type f -name SKILL.md -print 2>/dev/null | sed \'s|.*/skills/||;s|/SKILL.md$||\' \\',
-        '  | grep -E \'^(sr|custom)-\' | sort)"',
-        'PROFILE_MODE="legacy"',
-        'PROFILE_NAME=""',
-        '```',
-        '',
-        'Per-role model overrides are empty in legacy mode. External role',
-        'processes use the explicit Kimi default (`k3`, launched as',
-        '`kimi-code/k3`).',
-        '',
-    ].join('\n'));
-    adapted = replaceMarkdownSection(adapted, '#### Merge Algorithm', '**Step 4: Record outcomes**', [
-        '#### Kimi role-wave merge algorithm',
+    return body.replace('##### Invocation configuration', [
+        '##### Kimi invocation configuration',
         '',
-        'The role-wave contract above overrides the generic runtime-supplied',
-        'worktree assumptions. Use the stable run id chosen for this workflow.',
-        'First run this command (the run id grammar is validated before git):',
+        'Keep the parsed `AGENT_MODEL` map as structured orchestration data.',
+        'Resolve each role model from its exact profile value and put it in the',
+        'role-wave JSON `model` field; absent values use `k3`. Shell variables',
+        'from earlier tools are not persistent. Never rewrite role frontmatter',
+        'or translate a Claude model alias into a Kimi model.',
         '',
-        '```sh',
-        'node .kimi-code/specrails/run-skill.mjs --role-wave-status <stable-run-id>',
-        '```',
-        '',
-        'The single `specrails.merge.inventory` frame supplies `baseCommit`,',
-        '`manifestPath`, and each safe worktree id, `repoDir`, and complete',
-        '`changes` list. Every change is `{status:"A"|"M"|"D",path}`. This',
-        'inventory compares against the synthetic baseline snapshot, includes',
-        'committed/staged/unstaged and non-ignored untracked role output, and',
-        'excludes `.kimi-code` plus SpecRails run-state. Never discover changed',
-        'files with a shell loop, newline splitting, or a hard-coded `main` ref.',
-        '',
-        'Classify paths across all worktrees before applying anything:',
-        '- `exclusive_files`: appears in one worktree only.',
-        '- `shared_files`: appears in two or more worktrees.',
-        '- Preserve each A/M/D status; a D path has no source file to copy.',
-        '',
-        '**Exclusive A/M/D actions**',
-        '',
-        'For each feature in `MERGE_ORDER`, use structured WriteFile (never shell',
-        'interpolation) to write `.specrails/kimi-role-merge.json`:',
-        '',
-        '```json',
-        '{',
-        '  "run": "<stable-run-id>",',
-        '  "actions": [',
-        '    {"worktree":"<safe-id>","path":"<exact-git-path>","operation":"copy"},',
-        '    {"worktree":"<safe-id>","path":"<deleted-path>","operation":"delete"}',
-        '  ]',
-        '}',
-        '```',
-        '',
-        'Use `copy` for A/M and `delete` for D, then run exactly:',
-        '',
-        '```sh',
-        'node .kimi-code/specrails/run-skill.mjs \\',
-        '  --role-merge-file .specrails/kimi-role-merge.json',
-        '```',
-        '',
-        'The helper validates the one-shot file, manifest, registered worktree,',
-        'and path containment, then copies bytes/symlinks or deletes the target',
-        'without a shell. Filenames may contain spaces, Unicode, quotes, `$()`,',
-        'or leading dashes; never place them in a Bash command. It rejects',
-        'provider/run-state paths, traversal, duplicate targets, directories,',
-        'and symlinked target parents.',
-        '',
-        '**Shared paths**',
-        '',
-        'Process shared paths in `MERGE_ORDER`:',
-        '1. D in every contributor: submit one validated `delete` action.',
-        '2. D versus A/M: record a delete/modify conflict; do not silently copy',
-        '   or delete it.',
-        '3. A/M text: use structured ReadFile on each emitted `repoDir` + exact',
-        '   path and on the current merge target. Apply the existing Markdown',
-        '   section-aware strategy for `.md`; for other text perform a three-way',
-        '   semantic merge against the current target, writing through WriteFile.',
-        '4. Binary/type conflicts: record them for `sr-merge-resolver`; never',
-        '   decode or round-trip binary data through model text.',
-        '5. A resolved whole-file winner may be applied with one validated copy',
-        '   action. Any unresolved region receives the existing conflict markers',
-        '   and `MERGE_REPORT` entry.',
-        '',
-        'When `DRY_RUN=true`, do not invoke the repository merge-action helper.',
-        'Write resolved A/M outputs under `CACHE_DIR` with structured WriteFile',
-        'and record D paths as deletion operations in `.cache-manifest.json`.',
-        'Keep worktrees for inspection as the surrounding dry-run rule requires.',
+        'Every implementation role uses `workspace:"current"` and the same',
+        'aggregate execution context. Serialize writers within supplied roots;',
+        'no per-ticket full pipeline, nested worktree, copied-file merge or',
+        'replacement run. The runner preserves shared backlog and frozen specs',
+        'even though each role has a private execution cwd.',
         '',
     ].join('\n'));
-    adapted = adapted
-        .replace('  "implemented_files": [],', [
-        '  "implemented_files": [],',
-        '  "kimi_role_wave": {',
-        '    "run": "<stable-run-id>",',
-        '    "manifest_path": ".specrails/kimi-role-worktrees/<stable-run-id>.json",',
-        '    "base_commit": null,',
-        '    "workspaces": {}',
-        '  },',
-    ].join('\n'))
-        .replace('If the write succeeds: set `PIPELINE_STATE_AVAILABLE=true`.', [
-        'If the write succeeds: set `PIPELINE_STATE_AVAILABLE=true`.',
-        '',
-        '**Kimi retry state:** after every `specrails.role.workspace` frame,',
-        'atomically refresh `kimi_role_wave.manifest_path`, `base_commit`, and',
-        '`workspaces[<feature-id>]` from the helper output. Never synthesize',
-        'these values. Keep the same `run` and `worktree:<feature-id>` for that',
-        'feature through developer, test, docs, and review. On any failure keep',
-        'the manifest and worktrees. After every required change has been merged',
-        'successfully, run the static cleanup command from the Kimi role',
-        'contract and set `kimi_role_wave` to `null` in pipeline state.',
-    ].join('\n'))
-        .replaceAll('git -C <worktree-path> diff main --name-only', 'git -C <worktree-path> diff <base-commit> --name-only')
-        .replaceAll('git -C <worktree-path> diff main -- <file>', 'git -C <worktree-path> diff <base-commit> -- <file>')
-        .replace('(`<worktree-path>` is an absolute git-worktree path supplied by the runtime; `git -C <worktree-path>` already targets it directly.)', '(`<worktree-path>` is the `repoDir` emitted by the role-wave helper, and `<base-commit>` is read from its persisted manifest; `git -C <worktree-path>` already targets it directly.)');
-    return adapted;
 }
 function adaptKimiBatchImplement(body) {
-    return replaceMarkdownSection(body, '### Wave invocation', '### Failure isolation', [
-        '### Kimi wave invocation',
-        '',
-        'Nested `specrails-implement` executions are independent foreground Kimi',
-        'processes. Do not call multiple built-in `Skill` tools in one Kimi',
-        'session and do not share one checkout concurrently.',
-        '',
-        'Choose one safe `BATCH_RUN` id. For dependency wave `W`, derive the',
-        'deterministic safe run id `<BATCH_RUN>-w<W>`. Process waves sequentially:',
-        '',
-        '1. For a normal repository launch, partition each dependency wave into',
-        '   foreground batches of at most `min(CONCURRENCY,32)` entries. Each entry uses',
-        '   `skill:"specrails-implement"`, `workspace:"worktree:<feature-id>"`,',
-        '   the complete `<ref> [--dry-run]` arguments, the selected profile stem',
-        '   (or `"inherit"`), and that profile\'s exact `orchestrator.model` (or',
-        '   `k3`). Feature ids and keys must be collision-free safe ids.',
-        '2. Wait for all completion frames. A failed entry fails only that ticket;',
-        '   preserve its manifest/worktree for diagnosis and record the failure.',
-        '3. Before a downstream dependency wave, call `--role-wave-status` for',
-        '   the completed wave. Merge each successful worktree\'s A/M/D inventory',
-        '   into the batch repository with the same structured merge-file and',
-        '   shared-path rules defined by `specrails-implement`. Never interpolate',
-        '   a filename into Shell. If merge succeeds, run',
-        '   `node .kimi-code/specrails/run-skill.mjs --role-wave-cleanup <run>`.',
-        '   This makes predecessor output part of the next wave\'s newly captured',
-        '   synthetic baseline. Do not cleanup failed or unmerged worktrees.',
-        '4. Record `{ref,wave,status,profile,error_summary,run,manifest_path,',
-        '   workspace}` in `WAVE_RESULTS` before starting another batch.',
-        '',
-        'Inside a specrails-desktop isolated rail worktree, effective concurrency',
-        'is exactly 1. Submit a one-entry foreground role wave per ticket with',
-        '`workspace:"current"` and a deterministic unique run id; wait before the',
-        'next ticket. No sibling worktree, status merge, or cleanup is needed',
-        'because every nested implementation writes directly into the desktop',
-        'rail\'s current repository.',
-        '',
-        'Per-ticket profiles remain isolated: `profile` is either `inherit` or the',
-        'validated filename stem from `PROFILE_MAP`; `model` is resolved from the',
-        'same profile before writing JSON. Never export a profile globally.',
-        '',
-    ].join('\n'));
+    return body.replace('Delegate to implement once with all frozen specs and selected roots.', 'Activate `Skill(skill="specrails-implement", args="<all original arguments>")` once in this orchestrator with all frozen specs and selected roots. Do not launch a role wave of full implementations or one implementation per ticket.');
 }
 function adaptKimiAutoPropose(body) {
     return body
@@ -1579,36 +1431,19 @@ function adaptKimiAutoPropose(body) {
         .replaceAll('After the Explore agent completes:', 'After the sr-product-analyst role completes:');
 }
 function adaptKimiRetry(body) {
-    return body
-        .replace('- `PHASE_STATUSES` ← `phases` map (`architect`, `developer`, `test-writer`, `doc-sync`, `reviewer`, `ship`, `ci` → `"done"`, `"failed"`, `"skipped"`, or `"pending"`)', [
-        '- `PHASE_STATUSES` ← `phases` map (`architect`, `developer`, `test-writer`, `doc-sync`, `reviewer`, `ship`, `ci` → `"done"`, `"failed"`, `"skipped"`, or `"pending"`)',
-        '- `KIMI_ROLE_WAVE` ← `kimi_role_wave` (required when an isolated Kimi',
-        '  phase has already started): persisted `run`, `manifest_path`,',
-        '  `base_commit`, and feature→workspace mapping.',
-    ].join('\n'))
-        .replace('**Validation:**', [
-        '**Kimi workspace validation (before any phase):**',
+    return body + [
         '',
-        'If `KIMI_ROLE_WAVE` is non-null, validate its safe run id by invoking',
-        '`node .kimi-code/specrails/run-skill.mjs --role-wave-status <run>`.',
-        'The returned manifest path, base commit, and workspace ids must exactly',
-        'match pipeline state. Any mismatch/missing/unregistered worktree is a',
-        'hard stop: report recovery instructions and do not create a replacement',
-        'worktree. A retry must use the same run and exact',
-        '`worktree:<feature-id>` mapping so successful developer changes survive',
-        'a later test/docs/reviewer failure. Refresh state from emitted frames',
-        'after each resumed role. Never choose a new run while valid state',
-        'exists; never cleanup before every required phase and merge succeeds.',
+        '## Kimi direct-role continuation',
         '',
-        '**Validation:**',
-    ].join('\n'))
-        .replace('Include PR URL if ship ran successfully.', [
-        'Include PR URL if ship ran successfully.',
+        'Use the existing runtime status and exact absolute context. Invoke only',
+        'the required sr-* or profile role through a foreground role wave, using',
+        '`workspace:"current"`; do not activate a nested specrails-implement.',
+        'Pass the complete bounded handoff explicitly, including every frozen',
+        'criterion, selected roots, current phase and next action. Native session',
+        'memory is not a substitute. Preserve valid completed phases and source',
+        'work when a later reviewer or archive step is blocked.',
         '',
-        'After all required isolated outputs have been safely merged, invoke the',
-        'static `--role-wave-cleanup <run>` helper. Only after its cleanup frame',
-        'succeeds set `kimi_role_wave` to `null`. A failed retry retains state.',
-    ].join('\n'));
+    ].join('\n');
 }
 function renderKimiEnrichWorkflow() {
     return [
@@ -1780,15 +1615,6 @@ function renderKimiTelemetryWorkflow() {
         '',
     ].join('\n');
 }
-function replaceMarkdownSection(body, startHeading, endHeading, replacement) {
-    const start = body.indexOf(startHeading);
-    if (start < 0)
-        return body;
-    const end = body.indexOf(endHeading, start + startHeading.length);
-    if (end < 0)
-        return body;
-    return body.slice(0, start) + replacement + body.slice(end);
-}
 function writeKimiRoleSkill(args) {
     if (!pathExists(args.src))
         return;
@@ -1810,6 +1636,8 @@ function writeKimiRoleSkill(args) {
         '',
     ].join('\n');
     writeFileLf(args.dest, frontmatter +
+        (pathExists(path.join(path.dirname(args.src), '..', '..', 'runtime', 'provider-pipeline.md'))
+            ? readTextFile(path.join(path.dirname(args.src), '..', '..', 'runtime', 'provider-pipeline.md')) + '\n' : '') +
         KIMI_NESTED_SKILL_CONTRACT +
         KIMI_RUNTIME_CONTEXT_CONTRACT +
         rendered);
@@ -1882,6 +1710,7 @@ function writeGeminiAgentFromTemplate(args) {
         `description: ${JSON.stringify(description ?? args.agentId)}`,
         `model: ${model}`,
         `tools: [${GEMINI_AGENT_TOOLS.join(', ')}]`,
+        ...geminiAgentLimitMetadata(),
         '---',
         '',
     ].join('\n');
@@ -1910,7 +1739,6 @@ function placeGeminiAgents(input) {
     const placeholders = {
         PROJECT_NAME: path.basename(input.codeRoot),
         SECURITY_EXEMPTIONS_PATH: '.gemini/security-exemptions.yaml',
-        PERSONA_DIR: '.gemini/agents/personas/',
     };
     const placedIds = [];
     for (const src of listDir(agentsSrc)) {
@@ -1922,10 +1750,6 @@ function placeGeminiAgents(input) {
         // filtering happens at the workspace LINK step (linkAgentFiles).
         if (!input.materializeAllAgents && !selectedAgents.has(agentId))
             continue;
-        if (!input.materializeAllAgents && QUICK_EXCLUDED_AGENTS.has(agentId)) {
-            result.skipped++;
-            continue;
-        }
         writeGeminiAgentFromTemplate({
             artifactRoot: input.artifactRoot,
             src,
@@ -2148,6 +1972,38 @@ function renderInitialGeminiMd(repoRoot) {
         '',
     ].join('\n');
 }
+function providerPipelineContract(scriptDir) {
+    const source = path.join(scriptDir, 'templates', 'runtime', 'provider-pipeline.md');
+    return pathExists(source) ? readTextFile(source) + '\n\n' : '';
+}
+function prependSkillContract(file, contract) {
+    if (!contract || !pathExists(file))
+        return;
+    const source = readTextFile(file);
+    const end = source.startsWith('---\n') ? source.indexOf('\n---\n', 4) : -1;
+    const index = end < 0 ? 0 : end + 5;
+    writeFileLf(file, source.slice(0, index) + '\n' + contract + source.slice(index));
+}
+function assertPipelineRuntimeSource(scriptDir) {
+    const contractFile = path.join(scriptDir, 'integration-contract.json');
+    if (!pathExists(contractFile))
+        return;
+    const contract = JSON.parse(readTextFile(contractFile));
+    if (contract.execution?.runtime && !pathExists(path.join(scriptDir, 'dist', 'installer', 'runtime', 'pipeline-state.js'))) {
+        throw new Error('Core declares a pipeline runtime but its compiled module is missing; rebuild or reinstall this Core package before refreshing providers');
+    }
+}
+function placePipelineRuntime(input) {
+    const source = path.join(input.scriptDir, 'dist', 'installer', 'runtime', 'pipeline-state.js');
+    // Source-only fixture installations may not include a compiled runtime.
+    if (!pathExists(source))
+        return 0;
+    const dest = path.join(input.artifactRoot, '.specrails', 'runtime');
+    copyFile(source, path.join(dest, 'pipeline-state.mjs'));
+    writeFileLf(path.join(dest, 'pipeline.mjs'), "import { runPipelineCli } from './pipeline-state.mjs'\n" +
+        "process.exitCode = await runPipelineCli(process.argv.slice(2))\n");
+    return 2;
+}
 function pruneLegacyArtifacts(input) {
     const legacyPaths = [
         path.join(input.artifactRoot, '.specrails', 'bin', 'doctor.sh'),
@@ -2162,8 +2018,7 @@ function pruneLegacyArtifacts(input) {
         legacyPaths.push(path.join(input.artifactRoot, input.providerDir, 'skills', 'setup'));
     }
     else if (input.provider === 'gemini') {
-        // Prune a stale WIP skills/ tree + any setup command leftovers.
-        legacyPaths.push(path.join(input.artifactRoot, input.providerDir, 'skills'));
+        // OpenSpec and user skills survive updates; only retired setup commands are managed.
         legacyPaths.push(path.join(input.artifactRoot, input.providerDir, 'commands', 'setup.toml'));
         legacyPaths.push(path.join(input.artifactRoot, input.providerDir, 'commands', 'specrails', 'setup.toml'));
     }
@@ -2202,20 +2057,19 @@ function pruneLegacyArtifacts(input) {
     }
 }
 /**
- * Quick-tier placement: copy agents / commands / rules from the
+ * Direct placement: copy agents / commands / rules from the
  * .specrails/setup-templates/ staging directory into the live
- * provider directory, substituting template placeholders and
- * excluding agents + commands whose dependencies are not present.
+ * provider directory, substituting template placeholders. This is the
+ * only placement path — there are no install tiers.
  *
  * Source is setup-templates/ (not scriptDir/templates/) so the pipeline
  * is: scriptDir/templates/ → setup-templates/ (earlier scaffold step)
- * → <providerDir>/ (this function). The intermediate hop mirrors the
- * retired bash installer and lets downstream consumers (specrails-desktop's
- * deployTemplates, /specrails:enrich, update flow) read from a single
- * canonical staging dir.
+ * → <providerDir>/ (this function). The intermediate hop lets downstream
+ * consumers (specrails-desktop's deployTemplates, update flow) read from a
+ * single canonical staging dir.
  */
-function placeQuickTierArtefacts(input) {
-    // Codex projects: the quick-tier `agents/` + `rules/` placement is
+function placeArtefacts(input) {
+    // Codex projects: the `agents/` + `rules/` placement is
     // skipped (handled by `placeSkills` rail-skills + `applyCodexSettings`).
     // The slash-command catalogue under `setup-templates/commands/specrails/`
     // IS ported, but to `.codex/skills/<name>/SKILL.md` instead of
@@ -2322,18 +2176,16 @@ function placeQuickTierArtefacts(input) {
     const placeholders = {
         PROJECT_NAME: projectName,
         SECURITY_EXEMPTIONS_PATH: `${input.providerDir}/security-exemptions.yaml`,
-        PERSONA_DIR: `${input.providerDir}/agents/personas/`,
     };
     // --- Agents ---
     const agentsSrc = path.join(setupTemplates, 'agents');
     const agentsDest = path.join(providerDirAbs, 'agents');
     let agentsPlaced = 0;
-    let agentsSkipped = 0;
-    const installedAgentNames = new Set();
-    // When no agent selection is provided (fresh init with no install-config),
-    // default to placing only the three core agents. This keeps the default
-    // install lean — optional agents (sr-merge-resolver, layer specialists,
-    // product agents) are explicitly opt-in via the TUI or install-config.
+    const agentsSkipped = 0;
+    // The only shipped agents are the three core agents. A profile-driven
+    // install may pass a selection; anything outside CORE_AGENTS has no template
+    // to place, so the intersection is always the core trio (extension happens
+    // via user-owned custom-*.md agents, never through the installer).
     const selectedAgents = input.selectedAgents
         ? new Set([...input.selectedAgents, ...CORE_AGENTS])
         : new Set([...CORE_AGENTS]);
@@ -2349,10 +2201,6 @@ function placeQuickTierArtefacts(input) {
             // filtering happens at the workspace LINK step, not here.
             if (!input.materializeAllAgents && selectedAgents && !selectedAgents.has(agentId))
                 continue;
-            if (!input.materializeAllAgents && QUICK_EXCLUDED_AGENTS.has(agentId)) {
-                agentsSkipped++;
-                continue;
-            }
             const dest = path.join(agentsDest, name);
             const rendered = renderPlaceholders(readTextFile(src), {
                 ...placeholders,
@@ -2360,7 +2208,6 @@ function placeQuickTierArtefacts(input) {
             });
             writeFileLf(dest, rendered);
             agentsPlaced++;
-            installedAgentNames.add(agentId);
             // Per-agent memory directory. Created even when empty so the first run of
             // the agent doesn't error on ENOENT. Skipped when materializing the SHARED
             // framework (`seedProjectDirs === false`): agent-memory is per-workspace
@@ -2375,13 +2222,6 @@ function placeQuickTierArtefacts(input) {
         }
     }
     // --- Commands ---
-    // Skip commands whose required agents were excluded.
-    const excludedCommands = new Set();
-    for (const dep of COMMAND_AGENT_DEPENDENCIES) {
-        const hasAllRequired = dep.requires.every((a) => installedAgentNames.has(a));
-        if (!hasAllRequired)
-            excludedCommands.add(dep.command);
-    }
     const commandsSrc = path.join(setupTemplates, 'commands', 'specrails');
     const commandsDest = path.join(providerDirAbs, 'commands', 'specrails');
     let commandsPlaced = 0;
@@ -2391,9 +2231,6 @@ function placeQuickTierArtefacts(input) {
             const name = path.basename(src);
             if (!name.endsWith('.md'))
                 continue;
-            const cmdId = name.slice(0, -3);
-            if (excludedCommands.has(cmdId))
-                continue;
             const dest = path.join(commandsDest, name);
             const rendered = renderPlaceholders(readTextFile(src), {
                 ...placeholders,
@@ -2445,7 +2282,7 @@ function applyCodexSettings(input) {
         written++;
     }
     // AGENTS.md — top-level instructions file the codex CLI loads on startup.
-    // Written with a sentinel block so update + enrich passes can refresh the
+    // Written with a sentinel block so update passes can refresh the
     // managed content while preserving anything the user added outside it.
     const agentsMdPath = path.join(input.artifactRoot, 'AGENTS.md');
     const agentsMdContent = renderInitialAgentsMd(input.codeRoot);
@@ -2513,7 +2350,7 @@ function upsertAgentsMdManagedBlock(existing, managedBlock) {
 // CLAUDE: the top-level `sr-*` skills (sr-implement, sr-why, …) are GENERATED
 // from their canonical slash-command body (`templates/commands/specrails/
 // <command>.md`) — the command is the single source of truth, so the skill can
-// never drift from it. Quick tier excludes VPC-dependent ones.
+// never drift from it.
 //
 // CODEX: top-level skills are NOT placed — every one has a command counterpart
 // that the command path ports to `.codex/skills/<name>/` (with codex-native
@@ -2529,10 +2366,6 @@ function placeSkills(input) {
         const commandsSrc = path.join(input.artifactRoot, '.specrails', 'setup-templates', 'commands', 'specrails');
         const skillEntries = Object.entries(SKILL_FROM_COMMAND);
         for (const [skillName, spec] of skillEntries) {
-            if (input.tier === 'quick' && QUICK_EXCLUDED_SKILLS.has(skillName)) {
-                result.skipped++;
-                continue;
-            }
             const src = path.join(commandsSrc, `${spec.command}.md`);
             if (!pathExists(src))
                 continue;
@@ -2555,8 +2388,7 @@ function placeSkills(input) {
     // copies were vestigial — unused on Claude, always overridden on codex,
     // and shipped with unsubstituted placeholders — and were removed).
     //
-    // Only the three CORE_AGENTS are placed by default; sr-merge-resolver and
-    // every layer specialist are placed only when selectedAgents includes them.
+    // Only the three CORE_AGENTS ship, so only their rail skills exist to place.
     const codexRailsOverridesDir = input.provider === 'codex'
         ? path.join(input.scriptDir, 'templates', 'codex-skills', 'rails')
         : null;
@@ -2612,10 +2444,6 @@ function placeSkills(input) {
                 const roleId = name.slice(0, -3);
                 if (!input.materializeAllAgents && !selectedAgents.has(roleId))
                     continue;
-                if (!input.materializeAllAgents && QUICK_EXCLUDED_AGENTS.has(roleId)) {
-                    result.skipped++;
-                    continue;
-                }
                 writeKimiRoleSkill({
                     src,
                     dest: path.join(destBase, roleId, 'SKILL.md'),
@@ -2630,14 +2458,9 @@ function placeSkills(input) {
                 }
             }
         }
+        // v5 ships only the core trio; every bundled command's role dependencies
+        // are always satisfied, so no command exclusion set is needed.
         const excludedCommands = new Set();
-        if (!input.materializeAllAgents) {
-            for (const dep of COMMAND_AGENT_DEPENDENCIES) {
-                if (!dep.requires.every((role) => placedRoleIds.has(role))) {
-                    excludedCommands.add(dep.command);
-                }
-            }
-        }
         if (isDir(commandsSrc)) {
             for (const src of listDir(commandsSrc)) {
                 const name = path.basename(src);