specrails-desktop 2.59.3 → 2.60.0

package/docs/internals/core-runtime-updates.md

@@ -68,6 +68,25 @@ all workspace refreshes and the final recovery-state write succeed.
 Core 6 registry updates and same-version runtime repairs are offered using the
 same supported-major policy as runtime selection.
 
+## Role definitions follow the engine
+
+Core owns how the implement roles think: `rolePromptDefaults()` returns the
+factory architect, developer, reviewer and fixer definitions (one shared senior
+engineer identity, blast-radius discipline, quality bar and the mandatory
+OpenSpec binding). Desktop owns the workflows that use those roles, and never
+keeps a copy of those definitions.
+
+- The Implement rail (engine 1) reads the defaults from the selected Core at
+  launch, merged with the user's global overrides from Settings.
+- Loop recipes store `inherit` for the built-in definitions (and
+  `inherit:<role>` for declared recipe roles such as `plan`/`build`). The
+  launch bridge resolves them to the same Core defaults plus global overrides
+  and freezes the result with the run, so every loop follows the installed
+  Core automatically. Text the user edits in the loop editor is stored verbatim
+  and stays frozen with the loop; "Use the Core definition" returns a role to
+  `inherit`. `/api/loop-agent-defaults` returns `rolePromptDefaults` so the
+  editor can preview what `inherit` resolves to today.
+
 ## Version reporting
 
 Global status distinguishes the selected runtime and its source, the active

package/docs/internals/profiles.md

@@ -21,20 +21,22 @@ Dashboard/Jobs/Analytics/Settings).
 - **Profiles** tab — create and edit profiles.
 - **Usage** tab — see which profiles are actually being used (backed by
   the `/analytics` endpoint covered in section 8).
-- **Catalog** tab — read the upstream `sr-*` agents or author custom
-  `custom-*` ones via the Studio.
+- **Catalog** tab — read the runtime-defined baseline roles (`sr-architect`,
+  `sr-developer`, `sr-reviewer`, shown read-only with the definition the Core
+  runtime executes) or author custom `custom-*` ones via the Studio.
 
 When the project has no profiles yet, the empty state offers two entry
 points:
 
-- **Migrate from current agents** — reads the primary provider's native role
-  catalog (`.claude/agents/` or `.kimi-code/skills/`) and creates a
-  `default` profile mirroring today's behavior. It requires the baseline trio
-  `sr-architect`, `sr-developer`, and `sr-reviewer` to be present — the
-  server rejects the migration if any is missing. Provider-specific model
-  identifiers are retained only when they are in that provider's catalog;
-  otherwise migration uses its default and stamps the provider into the saved
-  profile.
+- **Migrate from current agents** — seeds the baseline trio `sr-architect`,
+  `sr-developer` and `sr-reviewer` as role identifiers with the provider's
+  default model, reads the primary provider's native role catalog
+  (`.claude/agents/` or `.kimi-code/skills/`) for custom roles and creates a
+  `default` profile mirroring today's behavior. No `sr-*` file has to exist:
+  a `model:` is read only from role files an older install still carries.
+  Provider-specific model identifiers are retained only when they are in that
+  provider's catalog; otherwise migration uses its default and stamps the
+  provider into the saved profile.
 - **Blank profile** — start from scratch.
 
 ## 2. Saved profiles vs selection
@@ -128,6 +130,11 @@ template/duplicate/edit and rail execution remain available.
   `sr-developer`. Fix the listed issues and Save re-enables.
 - **"agent 'xyz' already exists" (409)** — the name collides with an
   existing provider role. Pick a different name.
+- **No `.claude/agents/sr-*.md` in the project** — expected. The baseline
+  roles are defined by the Core runtime, not installed as files; read them in
+  the Catalog tab and edit their definitions, provider and model in
+  **Settings → Agent runtime**. Files left behind by an older Core are
+  tolerated until Core prunes them.
 - **The whole Agents section is missing** — it can be disabled server-side
   with `SPECRAILS_AGENTS_SECTION=false`, which 404s the entire
   `/profiles` router. Unset it (or leave it at its default) to restore the

package/docs/internals/review-packet.md

@@ -140,7 +140,7 @@ one-active-generation-per-rail all come free from the shipped machinery.
 
 **The loop.** `factory:revision` is the fourth factory loop: `{{cmd:revise}}` (a
 distilled step that applies the one requested change on top of the branch and
-then runs `sr-reviewer` over the resulting diff, so packet v2 keeps its reviewer
+then runs the reviewer role (`sr-reviewer`) over the resulting diff, so packet v2 keeps its reviewer
 tier) followed by the standard `{{cmd:verify}}`. No Architect step — the plan and
 the code already exist. It is resolvable by id but deliberately NOT listed in the
 public catalog: its prompt consumes `{{const:REVISION_REQUEST}}`, which only a

package/docs/internals/source-map.md

@@ -79,7 +79,7 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 
 - [AgentRoleFields.tsx](../../client/src/features/agents/components/AgentRoleFields.tsx) · [test](../../client/src/features/agents/components/__tests__/AgentRoleFields.test.tsx)
 - [AgentStudio.tsx](../../client/src/features/agents/components/AgentStudio.tsx)
-- [AgentsCatalogTab.tsx](../../client/src/features/agents/components/AgentsCatalogTab.tsx)
+- [AgentsCatalogTab.tsx](../../client/src/features/agents/components/AgentsCatalogTab.tsx) · [test](../../client/src/features/agents/components/__tests__/AgentsCatalogTab.test.tsx)
 - [AiRefineOverlay.tsx](../../client/src/features/agents/components/AiRefineOverlay.tsx)
 - [ProfileAnalyticsCard.tsx](../../client/src/features/agents/components/ProfileAnalyticsCard.tsx)
 - [ProfileEditor.tsx](../../client/src/features/agents/components/ProfileEditor.tsx) · [test](../../client/src/features/agents/components/__tests__/ProfileEditor.test.tsx)

package/docs/running-pipelines.md

@@ -173,9 +173,9 @@ Without profiles, every rail uses the project's frontmatter-baked models. With p
 Open **Agents** in the project's right sidebar. Two sub-tabs:
 
 - **Profiles** — full CRUD over `.specrails/profiles/*.json`. The live validator enforces the baseline trio and routing ordering — Save is disabled with an "N issues to resolve" hint while the profile is broken.
-- **Agents Catalog** — read-only viewer of upstream `sr-*` agents and your `custom-*` agents.
+- **Agents Catalog** — read-only viewer of the runtime-defined baseline roles (`sr-architect`, `sr-developer`, `sr-reviewer`, shown with the definition the Core runtime actually executes) and your `custom-*` agents.
 
-The empty state offers **Migrate from current agents**: one click creates a `default` profile mirroring today's frontmatter.
+The empty state offers **Migrate from current agents**: one click creates a `default` profile from the baseline roles and your existing custom agents — no role file has to exist for it to work.
 
 Each profile gets a per-profile analytics card showing usage for the last 7 / 30 / 90 days: jobs, success rate, avg tokens, avg duration.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.59.3",
+  "version": "2.60.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/server/dist/core-compat.js

@@ -19,8 +19,8 @@ const bundled_core_1 = require("./bundled-core");
 const core_runtime_1 = require("./core-runtime");
 // Windows has no `which`; probe PATH via `where` instead.
 const WHICH_CMD = process.platform === 'win32' ? 'where' : 'which';
-/** Paired development target; older supported contracts remain compatible. */
-exports.EXPECTED_CORE_CONTRACT_SCHEMA_VERSION = '5.1';
+/** Paired development target; older supported contracts (5.1) remain compatible. */
+exports.EXPECTED_CORE_CONTRACT_SCHEMA_VERSION = '5.2';
 // These must mirror KNOWN_VERBS in cli/specrails-desktop.ts
 const DESKTOP_KNOWN_COMMANDS = new Set([
     'implement',
@@ -29,6 +29,10 @@ const DESKTOP_KNOWN_COMMANDS = new Set([
 // Commands older Cores still ship that Desktop no longer invokes. They are
 // tolerated (not drift) but never required: Batch was folded into implement.
 const DESKTOP_TOLERATED_LEGACY_COMMANDS = new Set(['batch-implement']);
+// Checkpoints that contract 5.1 still declares but Desktop retired: role agents
+// are runtime-defined since contract 5.2, so `agent_generation` is tolerated
+// (not drift) and never required.
+const DESKTOP_TOLERATED_LEGACY_CHECKPOINTS = new Set(['agent_generation']);
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -233,7 +237,7 @@ async function checkCoreCompat() {
         : (contract.checkpoints && typeof contract.checkpoints === 'object'
             ? Object.keys(contract.checkpoints)
             : []);
-    const missingCheckpoints = contractCheckpoints.filter((c) => !desktopCheckpointKeys.includes(c));
+    const missingCheckpoints = contractCheckpoints.filter((c) => !desktopCheckpointKeys.includes(c) && !DESKTOP_TOLERATED_LEGACY_CHECKPOINTS.has(c));
     const deterministic = contract.lifecycle?.mode === 'deterministic' && contract.lifecycle.requiresEnrich === false;
     // Supporting legacy installation checkpoints is compatible with Core 5;
     // demanding them from a deterministic installer would recreate enrich.

package/server/dist/mcp/guide.js

@@ -385,9 +385,10 @@ can run Contract Refine require AI-spawn, including Explore conversions.
 - **Plugins** (\`specrails_plugins\`): per-project MCP integrations; \`preview\`
   the diff before \`install\`; a degraded plugin never blocks rail launches.
 - **Profiles** (\`specrails_agents\`): per-project agent chains; the baseline
-  trio \`sr-architect\`/\`sr-developer\`/\`sr-reviewer\` is required; routing rules
-  end in a single terminal \`default: true\` rule; requires specrails-core
-  4.1.0 or newer.
+  trio \`sr-architect\`/\`sr-developer\`/\`sr-reviewer\` are role identifiers
+  defined by the specrails-core runtime (no installed files) and are required
+  in every chain; routing rules end in a single terminal \`default: true\` rule;
+  requires specrails-core 4.1.0 or newer.
 - **Setup** (\`specrails_setup\`): \`prerequisites\` → \`add_project\` →
   \`install_config\` per provider → ONE \`install\` (provisions all chosen
   providers; quick-only, offline) → poll \`checkpoints\` until

package/server/dist/modules/agent-runtime/runtime/agent-runtime-bridge.js

@@ -148,14 +148,18 @@ async function runAgentRuntimeInvocation(options) {
         if (!Array.isArray(admittedContext.repositories) || !admittedContext.repositories.length || admittedContext.repositories.some(repo => !repo || typeof repo.id !== 'string' || !repo.id))
             throw new Error('Core context is missing its repository scope');
         const source = (0, node_fs_1.existsSync)(options.configPath) ? 'project-role' : 'default';
-        const { config, origins } = (0, agent_runtime_effective_config_1.resolveEffectiveRuntimeConfig)(options.loopConfig ? (0, agent_runtime_settings_1.loadLoopRuntimeConfig)(options.configPath, options.loopConfig, options.providerOverride ?? { provider: options.defaultProvider ?? 'claude' }) : (0, agent_runtime_settings_1.loadRuntimeConfigFile)(options.configPath, options.defaultProvider), {
+        // The engine owns the factory role definitions; the user's global overrides sit on top. The Implement
+        // rail merges them under any project text, and loop recipes resolve their `inherit` definitions here.
+        const effectiveRolePrompts = { ...(await (0, agent_runtime_loader_1.loadCoreAgentRuntime)()).rolePromptDefaults(), ...(0, agent_runtime_settings_1.loadRuntimeRolePrompts)() };
+        const loopConfig = options.loopConfig && (0, agent_runtime_settings_1.resolveInheritedRolePrompts)(options.loopConfig, effectiveRolePrompts);
+        const { config, origins } = (0, agent_runtime_effective_config_1.resolveEffectiveRuntimeConfig)(loopConfig ? (0, agent_runtime_settings_1.loadLoopRuntimeConfig)(options.configPath, loopConfig, options.providerOverride ?? { provider: options.defaultProvider ?? 'claude' }) : (0, agent_runtime_settings_1.loadRuntimeConfigFile)(options.configPath, options.defaultProvider), {
             repositoryIds: admittedContext.repositories.map(repo => repo.id), source: options.loopConfig ? 'loop-role' : source, providerOverride: options.loopConfig ? undefined : options.providerOverride,
         });
         config.verification = scopedHostChecks(config.verification, admittedContext.repositories);
         if (definitionEngine)
             completeHostChecks(config, admittedContext.repositories);
-        if (!options.loopConfig)
-            config.rolePrompts = { ...(await (0, agent_runtime_loader_1.loadCoreAgentRuntime)()).rolePromptDefaults(), ...(0, agent_runtime_settings_1.loadRuntimeRolePrompts)(), ...config.rolePrompts };
+        if (!loopConfig)
+            config.rolePrompts = { ...effectiveRolePrompts, ...config.rolePrompts };
         // Core rejects unknown connection keys: drop the desktop-only local-engine
         // fields (label/defaultModel/rates/supportsReasoningEffort) before Core sees it.
         const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)();

package/server/dist/modules/agent-runtime/runtime/agent-runtime-settings.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentRuntimeConfigError = exports.REVIEW_THRESHOLD_FLOORS = exports.MAX_OUTPUT_TOKENS_MAX = exports.MAX_OUTPUT_TOKENS_MIN = exports.CONTEXT_WINDOW_TOKENS_MAX = exports.CONTEXT_WINDOW_TOKENS_MIN = exports.RUNTIME_ROLE_ID = void 0;
+exports.INHERIT_ROLE_PROMPT = exports.AgentRuntimeConfigError = exports.REVIEW_THRESHOLD_FLOORS = exports.MAX_OUTPUT_TOKENS_MAX = exports.MAX_OUTPUT_TOKENS_MIN = exports.CONTEXT_WINDOW_TOKENS_MAX = exports.CONTEXT_WINDOW_TOKENS_MIN = exports.RUNTIME_ROLE_ID = void 0;
 exports.stripDesktopConnectionFields = stripDesktopConnectionFields;
 exports.coreConnectionFieldGates = coreConnectionFieldGates;
 exports.validateLoopRuntimeSettings = validateLoopRuntimeSettings;
@@ -18,6 +18,8 @@ exports.saveRuntimeProviders = saveRuntimeProviders;
 exports.loadRuntimeConfigFile = loadRuntimeConfigFile;
 exports.loadAgentRuntimeConfig = loadAgentRuntimeConfig;
 exports.saveAgentRuntimeConfig = saveAgentRuntimeConfig;
+exports.inheritedRolePrompt = inheritedRolePrompt;
+exports.resolveInheritedRolePrompts = resolveInheritedRolePrompts;
 exports.validateRuntimeRolePrompts = validateRuntimeRolePrompts;
 exports.loadRuntimeRolePrompts = loadRuntimeRolePrompts;
 exports.saveRuntimeRolePrompts = saveRuntimeRolePrompts;
@@ -419,6 +421,27 @@ function saveAgentRuntimeConfig(project, input) {
     return config;
 }
 const PROMPT_ROLES = [...ROLES, 'fixer'];
+/** A loop recipe definition that follows the engine: resolved at launch to the selected Core's factory definition plus the user's global override. */
+exports.INHERIT_ROLE_PROMPT = 'inherit';
+const INHERITED_ROLE_PROMPT = /^inherit:(architect|developer|reviewer|fixer)$/;
+/** The prompt a declared recipe role carries when it follows a built-in definition (`inherit:<role>`), or the recipe's own text. */
+function inheritedRolePrompt(prompts, role) {
+    const value = prompts?.[role];
+    return value === undefined || value === exports.INHERIT_ROLE_PROMPT ? `${exports.INHERIT_ROLE_PROMPT}:${role}` : value;
+}
+/** Replace `inherit` definitions (built-in roles) and `inherit:<role>` prompts (declared roles) with the effective engine definitions. Explicit recipe text is kept verbatim. */
+function resolveInheritedRolePrompts(settings, effective) {
+    // A Core predating the fixer stance has no fixer default: the fixer then follows the developer definition.
+    const resolved = { ...effective, fixer: effective.fixer ?? effective.developer };
+    const lookup = (role) => resolved[role];
+    const rolePrompts = settings.rolePrompts && Object.fromEntries(Object.entries(settings.rolePrompts).map(([role, text]) => [role, text === exports.INHERIT_ROLE_PROMPT ? lookup(role) ?? text : text]));
+    const roles = settings.roles && Object.fromEntries(Object.entries(settings.roles).map(([id, role]) => {
+        const inherited = role.prompt?.match(INHERITED_ROLE_PROMPT);
+        const text = inherited ? lookup(inherited[1]) : undefined;
+        return [id, text ? { ...role, prompt: text } : role];
+    }));
+    return { ...settings, ...(rolePrompts ? { rolePrompts } : {}), ...(roles ? { roles } : {}) };
+}
 function validateRuntimeRolePrompts(input, extraRoles = []) {
     if (!input || typeof input !== 'object' || Array.isArray(input))
         throw new AgentRuntimeConfigError('Role prompts must be an object');

package/server/dist/modules/agents/runtime/profiles-router.js

@@ -18,6 +18,8 @@ const providers_1 = require("../../../providers");
 const kimi_skill_prompt_1 = require("../../../providers/kimi-skill-prompt");
 const profile_manager_1 = require("./profile-manager");
 const workspace_resolution_1 = require("../../../workspace-resolution");
+const agent_runtime_loader_1 = require("../../agent-runtime/runtime/agent-runtime-loader");
+const agent_runtime_settings_1 = require("../../agent-runtime/runtime/agent-runtime-settings");
 const project_router_helpers_1 = require("../../../project-router-helpers");
 /**
  * Relocate-artifacts gate: the dir whose `.specrails/{profiles,specrails-version}`
@@ -70,6 +72,30 @@ function agentsCatalogDir(project, provider) {
 function listAgentFiles(project, provider) {
     return (0, agent_catalog_1.listNativeAgentFiles)(specRoot(project), provider ?? project.provider ?? 'claude');
 }
+/**
+ * The baseline roles are identifiers of runtime-defined roles: specrails-core
+ * never reads an `sr-*` file for them. Their read-only catalog body is the Core
+ * runtime definition (defaults merged with the global Settings overrides).
+ */
+const BASELINE_RUNTIME_ROLES = {
+    'sr-architect': 'architect',
+    'sr-developer': 'developer',
+    'sr-reviewer': 'reviewer',
+};
+const RUNTIME_DEFINED_DESCRIPTION = 'Runtime-defined by specrails-core: the implement pipeline runs this role from the Core runtime definition below, not from an installed file.';
+async function loadRuntimeRoleDefinitions() {
+    try {
+        const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)();
+        return { prompts: { ...runtime.rolePromptDefaults(), ...(0, agent_runtime_settings_1.loadRuntimeRolePrompts)() } };
+    }
+    catch (error) {
+        return { prompts: {}, error: error instanceof Error ? error.message : 'Core role prompt catalog is unavailable' };
+    }
+}
+function runtimeRoleBody(definitions, agentId) {
+    const role = BASELINE_RUNTIME_ROLES[agentId];
+    return role ? definitions.prompts[role] : undefined;
+}
 const AGENTS_SECTION_ENABLED = process.env.SPECRAILS_AGENTS_SECTION !== 'false';
 function handleError(res, err) {
     if (err instanceof profile_manager_1.ProfileValidationError) {
@@ -175,12 +201,11 @@ function createProfilesRouter() {
                 ? new Map((0, project_router_helpers_1.readAgentModels)({ ...project, provider })
                     .map((entry) => [entry.name, entry.model]))
                 : null;
-            const agentsDir = agentsCatalogDir(project, provider);
-            if (!fs_1.default.existsSync(agentsDir)) {
-                res.status(400).json({ error: `no ${adapter.projectDirName} roles catalog found` });
-                return;
-            }
+            const baseline = [...adapter.baselineAgents()];
             const agents = [];
+            // Role files are optional: Core >= 6.3 defines the baseline roles in its
+            // runtime. Read `model:` only from `sr-*` files that still exist (older
+            // installs); every other baseline id is seeded with the adapter default.
             for (const entry of listAgentFiles(project, provider)) {
                 if (!entry.id.startsWith('sr-'))
                     continue;
@@ -202,13 +227,10 @@ function createProfilesRouter() {
                 }
                 agents.push({ id, model });
             }
-            const baseline = [...adapter.baselineAgents()];
-            const missing = baseline.filter((id) => !agents.some((a) => a.id === id));
-            if (missing.length > 0) {
-                res.status(400).json({
-                    error: `missing baseline agents in this project: ${missing.join(', ')}. Run 'npx specrails-core@latest update' first.`,
-                });
-                return;
+            for (const id of baseline) {
+                if (agents.some((a) => a.id === id))
+                    continue;
+                agents.push({ id, model: projectedKimiModels?.get(id) ?? adapter.defaultModel() });
             }
             // Order: baseline trio first (architect, developer, reviewer), optional
             // agents in the middle. sr-merge-resolver is no longer a baseline agent;
@@ -379,39 +401,44 @@ function createProfilesRouter() {
         }
     });
     // GET /api/projects/:projectId/profiles/catalog
-    // List all roles in the selected provider-native catalog (sr-* + custom-*).
-    router.get('/catalog', (req, res) => {
+    // List the selected provider's roles: the runtime-defined baseline (upstream,
+    // synthesized from the adapter) plus the native `custom-*` catalog.
+    router.get('/catalog', async (req, res) => {
         try {
             const { project } = ctx(req);
             const provider = requestedProvider(req, project);
-            const files = listAgentFiles(project, provider);
-            if (files.length === 0) {
-                res.json({ agents: [] });
-                return;
-            }
+            const adapter = projectAdapter(project, provider);
             const agents = [];
-            for (const entry of files) {
+            // Baseline roles never depend on `sr-*` files; a missing roles directory
+            // still yields the three runtime-defined entries.
+            const definitions = await loadRuntimeRoleDefinitions();
+            for (const id of adapter.baselineAgents()) {
+                agents.push({
+                    id,
+                    kind: 'upstream',
+                    description: RUNTIME_DEFINED_DESCRIPTION,
+                    body: runtimeRoleBody(definitions, id) ?? '',
+                    roleId: BASELINE_RUNTIME_ROLES[id],
+                    ...(definitions.error ? { runtimeRoleError: definitions.error } : {}),
+                });
+            }
+            for (const entry of listAgentFiles(project, provider)) {
                 const id = entry.id;
-                const kind = id.startsWith('sr-')
-                    ? 'upstream'
-                    : id.startsWith('custom-')
-                        ? 'custom'
-                        : null;
-                if (!kind)
+                // Stale `sr-*` files from older Cores are not catalog entries anymore.
+                if (!id.startsWith('custom-'))
                     continue;
+                const kind = 'custom';
                 let description;
                 let model;
                 let projected = {};
                 try {
                     const body = fs_1.default.readFileSync(entry.file, 'utf8');
-                    if (kind === 'custom') {
-                        try {
-                            const result = (0, agent_role_descriptor_1.projectCustomAgentRole)({ id, content: body }, { provider });
-                            projected = { roleId: result.id, runtimeRoleDefaults: result.role };
-                        }
-                        catch (error) {
-                            projected = { runtimeRoleError: error instanceof Error ? error.message : 'Invalid Core role descriptor' };
-                        }
+                    try {
+                        const result = (0, agent_role_descriptor_1.projectCustomAgentRole)({ id, content: body }, { provider });
+                        projected = { roleId: result.id, runtimeRoleDefaults: result.role };
+                    }
+                    catch (error) {
+                        projected = { runtimeRoleError: error instanceof Error ? error.message : 'Invalid Core role descriptor' };
                     }
                     if (provider === 'kimi') {
                         // Use the same js-yaml metadata parser as validation/execution so
@@ -468,8 +495,9 @@ function createProfilesRouter() {
         }
     });
     // GET /api/projects/:projectId/profiles/catalog/:agentId
-    // Return the full .md body of a single agent file (read-only for sr-*, editable for custom-*)
-    router.get('/catalog/:agentId', (req, res) => {
+    // Return the full body of a single agent: the Core runtime definition for a
+    // baseline role (read-only), the native file for custom-* (editable).
+    router.get('/catalog/:agentId', async (req, res) => {
         try {
             const { project } = ctx(req);
             const provider = requestedProvider(req, project);
@@ -480,6 +508,16 @@ function createProfilesRouter() {
             }
             const file = agentFile(project, agentId, provider);
             if (!fs_1.default.existsSync(file)) {
+                if (projectAdapter(project, provider).baselineAgents().includes(agentId)) {
+                    const definitions = await loadRuntimeRoleDefinitions();
+                    const body = runtimeRoleBody(definitions, agentId);
+                    if (body !== undefined) {
+                        res.json({ id: agentId, body, runtimeDefined: true });
+                        return;
+                    }
+                    res.status(503).json({ error: definitions.error ?? 'Core role prompt catalog is unavailable' });
+                    return;
+                }
                 res.status(404).json({ error: 'agent not found' });
                 return;
             }

package/server/dist/modules/execution/runtime/queue-manager.js

@@ -1935,17 +1935,15 @@ class QueueManager {
         const execution = this._resolveExecution();
         this._jobExecution.set(jobId, execution);
         const spawnCwd = execution.cwd;
-        // Windows repair: a relocated workspace whose `.claude/agents` was left empty
-        // by the broken `current`-junction read during assemble has no sr-* agents,
-        // so the implement pipeline can't delegate and runs inline. Self-heal here
-        // (per rail spawn) by copying the agents from the real version dir. NO-OP on
-        // POSIX (assemble's per-file symlinks already populate them).
+        // Windows repair: a relocated workspace whose dir-linked subtrees
+        // (commands/skills/rules) were left unreadable by the broken `current`
+        // junction during assemble has no `/specrails:*` commands → the CLI reports
+        // "Unknown command: /specrails:implement". Self-heal here (per rail spawn)
+        // from the real version dir. Role agents (architect/developer/reviewer) are
+        // defined by the Core runtime, not by workspace files, so nothing else is
+        // repaired. NO-OP on POSIX (assemble's symlinks already populate them).
         if (execution.relocated) {
             try {
-                (0, workspace_manager_1.ensureFrameworkAgents)(execution.cwd, adapter.projectDirName);
-                // AND the dir-linked subtrees (commands/skills/rules): a broken Windows
-                // `current` junction leaves the workspace with no `/specrails:*` commands
-                // → the CLI reports "Unknown command: /specrails:implement".
                 (0, workspace_manager_1.ensureFrameworkCommandSubtrees)(execution.cwd, adapter.projectDirName);
             }
             catch {

package/server/dist/modules/loops/runtime/loop-agents.js

@@ -1,16 +1,13 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defaultLoopAgents = defaultLoopAgents;
-const loop_agent_defaults_json_1 = __importDefault(require("./loop-agent-defaults.json"));
+const agent_runtime_settings_1 = require("../../agent-runtime/runtime/agent-runtime-settings");
 function defaultLoopAgents(mode = 'implementation') {
     return {
         schemaVersion: 1,
         agents: { architect: { provider: 'inherit' }, developer: { provider: 'inherit' }, reviewer: { provider: 'inherit' } },
         fixer: { provider: 'inherit' },
-        rolePrompts: mode === 'implementation' ? { ...loop_agent_defaults_json_1.default } : {
+        rolePrompts: mode === 'implementation' ? { architect: agent_runtime_settings_1.INHERIT_ROLE_PROMPT, developer: agent_runtime_settings_1.INHERIT_ROLE_PROMPT, reviewer: agent_runtime_settings_1.INHERIT_ROLE_PROMPT, fixer: agent_runtime_settings_1.INHERIT_ROLE_PROMPT } : {
             architect: 'Explore the repositories and plan the requested work from the supplied goal and acceptance criteria.',
             developer: 'Implement the supplied spec directly in the existing codebase. Explore relevant code, make the requested changes and add meaningful tests. Use the project verification commands. If a human decision is required, finish with LOOP_BLOCKED: followed by the specific question.',
             reviewer: 'Review actual code and verification evidence against the supplied acceptance criteria. Report correctness, security and regression issues.',

package/server/dist/modules/loops/runtime/loop-command-catalog.js

@@ -116,10 +116,10 @@ exports.LOOP_COMMANDS = [
     {
         name: 'revision-verify',
         label: 'revision verify',
-        description: 'Read-only independent Revision gate: run sr-reviewer, ensure one full-scope pass of record, write fresh confidence evidence when available, and emit VERIFICATION: PASS|FAIL.',
+        description: 'Read-only independent Revision gate: perform an independent senior review of the diff against the OpenSpec package, ensure one full-scope pass of record, write fresh confidence evidence when available, and emit VERIFICATION: PASS|FAIL.',
         ticketScope: 'all',
         // The Revision loop's SINGLE owner of review + verification. It exists because
-        // running sr-reviewer inside `revise` and then a generic `{{cmd:verify}}` made
+        // running a review inside `revise` and then a generic `{{cmd:verify}}` made
         // two independent full gates for one one-sentence change — the exact cost the
         // Architect-less revision path was created to avoid. Kept read-only so a failed
         // gate routes to the loop's separate `fix` step instead of the grader patching
@@ -133,14 +133,14 @@ exports.LOOP_COMMANDS = [
             '',
             'Treat that briefing and the files on disk as the complete source context. Do not depend on the mutating agent remembering or summarizing it for you.',
             '',
-            'Reviewer output-format reconciliation: the installed `sr-reviewer` may require its review phase to finish with only `Score:` and `Verdict:` lines and then end. In this OUTER verification gate those two lines are an intermediate reviewer result, not the end of your turn. Preserve every reviewer rule except that terminal response-format instruction; after recording its score/verdict, continue with any missing project gates and emit the outer `VERIFICATION` sentinel required below.',
+            'Reviewer output-format reconciliation: a senior review phase conventionally finishes with only `Score:` and `Verdict:` lines and then ends. In this OUTER verification gate those two lines are an intermediate reviewer result, not the end of your turn. Keep every review rule except that terminal response-format instruction; after recording the score/verdict, continue with any missing project gates and emit the outer `VERIFICATION` sentinel required below.',
             '',
             'Work in this order:',
-            '1. Load and follow the installed `sr-reviewer` role over the resulting diff and the governing OpenSpec package (use its archived package when that is the delivery context; do not archive or re-archive anything). Produce a fresh `confidence-score.json` for this pass when the reviewer is applicable.',
+            '1. Perform an independent senior review of the resulting diff against the governing OpenSpec package: proposal, design, delta specs and tasks (use its archived package when that is the delivery context; do not archive or re-archive anything). Check correctness, scope discipline, test coverage and alignment with the spec, and record a `Score:` and `Verdict:`. Produce a fresh `confidence-score.json` for this pass when an OpenSpec package governs the candidate.',
             '2. Establish exactly ONE full-scope project gate for this candidate: the complete configured test suite plus typecheck, lint, and build when present. Inspect what the reviewer actually ran. If it already ran that full gate, treat those commands as the pass of record and DO NOT repeat them. If it ran only scoped/focused checks, run only the missing full-scope commands once.',
             '3. Independently map the user revision request and frozen spec to the real diff. A clean command exit alone is not enough when required behavior is missing or out-of-scope work was introduced.',
             '',
-            'If the reviewer is unavailable or inapplicable, run the full-scope project gate yourself exactly once, continue the semantic diff review, and report reviewer confidence as unavailable. Never infer PASS from missing reviewer evidence.',
+            'If no OpenSpec package governs this candidate, review the diff against the frozen spec alone, run the full-scope project gate yourself exactly once, and report reviewer confidence as unavailable. Never infer PASS from missing review evidence.',
             '',
             'This gate is read-only: do NOT edit source, tests, configuration, or OpenSpec contract artifacts, and do NOT fix findings. The only permitted writes are reviewer/evidence artifacts. On any defect or failed/missing required gate, report FAIL so the loop routes to its separate fix step.',
             '',

package/server/dist/modules/loops/runtime/loop-definition.js

@@ -75,7 +75,7 @@ function compileLoopToDefinition(graph, launch) {
                 }
             }
             if (kind === 'prompt' && graph.config.agents) {
-                const definition = graph.config.agents.rolePrompts?.[promptRole]?.replaceAll('{{', '{{{{');
+                const definition = agents?.rolePrompts?.[promptRole]?.replaceAll('{{', '{{{{');
                 if (definition) {
                     if (object(params.nativeCommand))
                         params.nativeCommand = { ...params.nativeCommand, args: String(params.nativeCommand.args ?? '') + '\n\nLoop agent definition:\n' + definition };

package/server/dist/modules/loops/runtime/loop-executors.js

@@ -347,7 +347,6 @@ function createLoopExecutors(opts = {}) {
             };
             if (repoDir) {
                 try {
-                    (0, workspace_manager_1.ensureFrameworkAgents)(cwd, adapter.projectDirName);
                     (0, workspace_manager_1.ensureFrameworkCommandSubtrees)(cwd, adapter.projectDirName);
                 }
                 catch { /* best-effort */ }
@@ -556,7 +555,6 @@ function createLoopExecutors(opts = {}) {
             const extraArgs = aiStepExtraArgs(adapter, cwd, repoDir, executionManifest);
             if (repoDir) {
                 try {
-                    (0, workspace_manager_1.ensureFrameworkAgents)(cwd, adapter.projectDirName);
                     (0, workspace_manager_1.ensureFrameworkCommandSubtrees)(cwd, adapter.projectDirName);
                 }
                 catch { /* best-effort */ }

package/server/dist/modules/loops/runtime/loop-implement-recipe.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.configurableImplementGraph = configurableImplementGraph;
+const agent_runtime_settings_1 = require("../../agent-runtime/runtime/agent-runtime-settings");
 const loop_agents_1 = require("./loop-agents");
 const objectSchema = (properties, required = Object.keys(properties)) => ({ type: 'object', properties, required, additionalProperties: false });
 const string = { type: 'string' };
@@ -12,10 +13,10 @@ const reviewPolicy = 'approved == true; issues must be empty; score >= 70; ' + O
 function configurableImplementGraph() {
     const agents = (0, loop_agents_1.defaultLoopAgents)();
     agents.roles = {
-        plan: { ...agents.agents.architect, access: 'read', artifacts: 'all', openspecSkill: 'openspec-ff-change', prompt: agents.rolePrompts?.architect },
-        build: { ...agents.agents.developer, access: 'write', artifacts: 'tasks-checkboxes', openspecSkill: 'openspec-apply-change', prompt: agents.rolePrompts?.developer },
-        assess: { ...agents.agents.reviewer, access: 'read', artifacts: 'none', openspecSkill: 'openspec-verify-change', prompt: agents.rolePrompts?.reviewer },
-        correct: { ...agents.fixer, access: 'write', artifacts: 'tasks-checkboxes', openspecSkill: 'openspec-apply-change', prompt: agents.rolePrompts?.fixer },
+        plan: { ...agents.agents.architect, access: 'read', artifacts: 'all', openspecSkill: 'openspec-ff-change', prompt: (0, agent_runtime_settings_1.inheritedRolePrompt)(agents.rolePrompts, 'architect') },
+        build: { ...agents.agents.developer, access: 'write', artifacts: 'tasks-checkboxes', openspecSkill: 'openspec-apply-change', prompt: (0, agent_runtime_settings_1.inheritedRolePrompt)(agents.rolePrompts, 'developer') },
+        assess: { ...agents.agents.reviewer, access: 'read', artifacts: 'none', openspecSkill: 'openspec-verify-change', prompt: (0, agent_runtime_settings_1.inheritedRolePrompt)(agents.rolePrompts, 'reviewer') },
+        correct: { ...agents.fixer, access: 'write', artifacts: 'tasks-checkboxes', openspecSkill: 'openspec-apply-change', prompt: (0, agent_runtime_settings_1.inheritedRolePrompt)(agents.rolePrompts, 'fixer') },
     };
     const nodes = [{ id: 'start', type: 'start', position: { x: 0, y: 0 } }], edges = [];
     const node = (id, label, kind, params, outcomes) => {

package/server/dist/modules/loops/runtime/loops-router.js

@@ -63,7 +63,9 @@ function registerLoopsRoutes(router, deps) {
         if (!guard(res))
             return;
         const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)().catch(() => null);
-        res.json({ agents: (0, loop_agents_1.defaultLoopAgents)(), guardrails: { supported: runtime?.api?.capabilities?.configurableGuardrails === 1, catalog: runtime?.api?.guardrails ?? [] } });
+        // `inherit` definitions resolve at launch; the editor previews what they resolve to today.
+        const rolePromptDefaults = runtime ? { ...runtime.rolePromptDefaults(), ...(0, agent_runtime_settings_1.loadRuntimeRolePrompts)() } : null;
+        res.json({ agents: (0, loop_agents_1.defaultLoopAgents)(), rolePromptDefaults, guardrails: { supported: runtime?.api?.capabilities?.configurableGuardrails === 1, catalog: runtime?.api?.guardrails ?? [] } });
     });
     // ── Templates ──────────────────────────────────────────────────────────────
     router.get('/loop-templates', async (_req, res) => {

package/server/dist/providers/gemini-agent-ack.js

@@ -1,18 +1,20 @@
 "use strict";
-// Gemini headless subagent pre-acknowledgment.
+// Gemini headless subagent pre-acknowledgment (custom agents only).
 //
 // gemini 0.46+ DISCOVERS `<project>/.gemini/agents/*.md` but only ENABLES a
 // project's custom subagents after an interactive "New Agents Discovered →
 // Acknowledge and Enable" prompt. That prompt never fires in headless
 // (`gemini -p`) spawns — which is how the desktop runs every rail — so
-// `invoke_agent sr-architect` returns "Subagent not found" and the implement
-// orchestrator silently falls back to a generic agent (the specialised
-// architect/developer/reviewer personas never run in isolation).
+// `invoke_agent custom-<name>` returns "Subagent not found" and the role that
+// delegates to it silently falls back to inline work. The baseline roles
+// (architect/developer/reviewer) are defined by the specrails-core runtime and
+// are not `.gemini/agents` files, so only the project's `custom-*` agents need
+// this acknowledgment.
 //
 // specrails-core writes the acknowledgment file at install time; this is the
 // defence-in-depth copy the desktop runs right before a gemini rail spawn, so a
-// project installed with an older core (or whose agents changed since install)
-// is still trusted headless. The file gemini reads is
+// project whose custom agents changed since install is still trusted headless.
+// The file gemini reads is
 // `~/.gemini/acknowledgments/agents.json`, shaped
 //   { [projectRoot]: { [agentName]: <sha256-hex of the agent .md file> } }
 // where the hash is sha256 of the FULL agent markdown file (verified empirically
@@ -29,10 +31,11 @@ function ackFilePath() {
     return (0, path_1.join)((0, os_1.homedir)(), '.gemini', 'acknowledgments', 'agents.json');
 }
 /**
- * Pre-acknowledge every `<projectPath>/.gemini/agents/*.md` so gemini loads them
- * in headless mode. No-op when the project has no `.gemini/agents` dir or no
- * agent files. The `projectPath` is the key gemini uses (the spawn cwd / repo
- * root), matching what `specrails-core` writes at install.
+ * Pre-acknowledge every `<projectPath>/.gemini/agents/*.md` (the project's
+ * custom agents) so gemini loads them in headless mode. No-op when the project
+ * has no `.gemini/agents` dir or no agent files. The `projectPath` is the key
+ * gemini uses (the spawn cwd / repo root), matching what `specrails-core`
+ * writes at install.
  */
 function acknowledgeGeminiProjectAgents(projectPath) {
     const agentsDir = (0, path_1.join)(projectPath, '.gemini', 'agents');