specrails-core 4.11.3 → 5.0.0

package/integration-contract.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "3.0",
+  "schemaVersion": "3.2",
   "providers": {
     "claude": {
       "enrichCommand": "/specrails:enrich",
@@ -22,6 +22,59 @@
         "enrichArgs": ["exec", "run enrich"],
         "enrichFromConfigArgs": ["exec", "run enrich --from-config"]
       }
+    },
+    "gemini": {
+      "enrichCommand": "/specrails:enrich",
+      "enrichArgs": ["--from-config"],
+      "updateCommand": "/specrails:enrich",
+      "updateArgs": ["--update"],
+      "cli": {
+        "initArgs": [],
+        "enrichArgs": ["-p", "/specrails:enrich", "--output-format", "stream-json"],
+        "enrichFromConfigArgs": ["-p", "/specrails:enrich --from-config", "--output-format", "stream-json"]
+      }
+    },
+    "kimi": {
+      "enrichCommand": "/skill:specrails-enrich",
+      "enrichArgs": ["--from-config"],
+      "updateCommand": "/skill:specrails-enrich",
+      "updateArgs": ["--update"],
+      "cli": {
+        "binary": "node",
+        "providerBinary": "kimi",
+        "skillRunner": ".kimi-code/specrails/run-skill.mjs",
+        "skillMaterialization": "kimi-0.27-user-slash-prompt",
+        "nestedSkillInvocation": "Kimi built-in Skill tool with { skill, args }; never literal /skill text",
+        "modelIdPattern": "^[A-Za-z0-9][A-Za-z0-9._/:-]{0,127}$",
+        "sessionIdPattern": "^(?!\\.{1,2}$)[A-Za-z0-9._-]{1,128}$",
+        "roleWave": {
+          "path": ".specrails/kimi-role-wave.json",
+          "schema": "{ run: safe-id, roles: Array<{ key: safe-id, skill: direct-child-id, model: safe-model-id, profile: \"inherit\" | safe-id, args: string, workspace: \"current\" | \"worktree:<safe-id>\" }> } with no extra keys",
+          "maxBytes": 1048576,
+          "maxRoles": 32,
+          "transport": "structured WriteFile followed by one static foreground --role-wave-file command; the one-shot file is deleted before setup and every role is awaited. Inspection, merge, and cleanup use the separate static --role-wave-status, --role-merge-file, and --role-wave-cleanup modes",
+          "workspaces": "current roles receive unique execution directories with SPECRAILS_REPO_DIR set to the target repository; isolated roles create/reuse detached git worktrees from a synthetic baseline that includes the starting tracked/untracked overlay but excludes provider/runtime control files, with SPECRAILS_REPO_DIR set to that worktree",
+          "manifest": ".specrails/kimi-role-worktrees/<run>.json records the immutable synthetic base commit, source head, worktree ids, and role key to execution/repository paths",
+          "status": "--role-wave-status <run> validates the persisted manifest/ref/worktrees and emits one specrails.merge.inventory frame before any downstream merge",
+          "merge": ".specrails/kimi-role-merge.json is the only accepted merge request path; { run, actions: Array<{ worktree: safe-id, path: safe-relative-path, operation: \"copy\" | \"delete\" }> } applies an explicit A/M/D inventory through --role-merge-file without attributing the starting overlay or provider control files",
+          "cleanup": "--role-wave-cleanup <run> removes owned worktrees, temporary execution roots, persisted manifest, and synthetic baseline ref, then emits specrails.role.cleanup",
+          "output": "newline-delimited attributed specrails.role.workspace, specrails.role.event/output, specrails.role.completed, specrails.merge.inventory, specrails.merge.applied, and specrails.role.cleanup frames; aggregate role-wave exit is nonzero when any role fails"
+        },
+        "stableEngineEnv": {
+          "KIMI_CODE_EXPERIMENTAL_FLAG": null,
+          "KIMI_DISABLE_CRON": "1",
+          "KIMI_CODE_NO_AUTO_UPDATE": "1",
+          "KIMI_MODEL_THINKING_EFFORT": "low|high|max only for kimi-code/k3; omitted K3 effort preserves Kimi's documented high default; unset for every other model"
+        },
+        "windowsPromptTransport": "For the standard npm kimi.cmd/bat shim, prompt bytes travel over stdin to a fixed Node bootstrap which restores process.argv before importing Kimi; native executables fail above a 30000 UTF-16 command-line budget.",
+        "initialActivationTelemetry": "Visible prompt parity only; the external materializer cannot emit Kimi-private skill.activated/origin telemetry.",
+        "cancellation": "Single-skill mode forwards SIGINT/SIGTERM/SIGHUP to its direct Kimi child. Role-wave mode forwards each termination signal to every live Kimi child and waits for aggregate completion; the embedding host remains responsible for platform process-tree teardown.",
+        "initArgs": [],
+        "enrichArgs": [".kimi-code/specrails/run-skill.mjs", "--skill", "specrails-enrich", "--model", "k3"],
+        "enrichFromConfigArgs": [".kimi-code/specrails/run-skill.mjs", "--skill", "specrails-enrich", "--model", "k3", "--args", "--from-config"],
+        "resumeArgs": ["--session=<session-id>"],
+        "notes": "CLI-only integration. enrichCommand/updateCommand are interactive Kimi TUI syntax only. Headless callers must execute binary + enrichArgs; plain `kimi -p \"/skill:...\"` is literal prompt text in Kimi 0.27 and does not activate a skill. The managed Node runner materializes the upstream user-slash prompt, then launches external Kimi with stream-json and no shell. Generated multi-role workflows use one bounded role-wave file so context never enters shell source and parallel roles cannot race on request paths. Do not start kimi web/server; authenticate once with `kimi login`."
+      }
     }
   },
   "tiers": {
@@ -43,13 +96,13 @@
     "version": 1,
     "fields": {
       "version": "number — schema version, currently 1",
-      "provider": "string — claude | codex | gemini | auto",
+      "provider": "string — claude | codex | gemini | kimi",
       "tier": "string — full | quick",
-      "agents.selected": "string[] — agent names to install",
-      "agents.excluded": "string[] — agent names to skip",
-      "models.preset": "string — balanced | budget | max",
-      "models.defaults.model": "string — sonnet | opus | haiku (overrides preset)",
-      "models.overrides": "Record<string, string> — per-agent model (highest priority)"
+      "agents.selected": "string[] — unique lowercase kebab-case agent ids to install (1-64 characters)",
+      "agents.excluded": "string[] — unique lowercase kebab-case agent ids to skip; must not overlap agents.selected",
+      "models.preset": "string — balanced | budget | max; resolved within the selected provider catalog",
+      "models.defaults.model": "string — exact provider model id or configured alias (overrides preset; Kimi: 1-128 characters matching [A-Za-z0-9][A-Za-z0-9._/:-]*; default: k3)",
+      "models.overrides": "Record<safe-agent-id, string> — exact per-agent provider model ids or configured aliases with the same provider-specific validation (highest priority)"
     }
   },
   "checkpoints": {
@@ -63,19 +116,38 @@
   },
   "modelPresets": {
     "balanced": {
-      "description": "Flagship models for architects and PMs, efficient models for others",
+      "scope": "claude",
+      "description": "Legacy Claude preset view retained for existing consumers. Other providers resolve this preset through providerModelCatalogs.",
       "defaults": { "model": "sonnet" },
-      "overrides": { "sr-architect": "opus", "sr-product-manager": "opus" }
+      "overrides": {}
     },
     "budget": {
-      "description": "All agents use the most cost-efficient model",
+      "scope": "claude",
+      "description": "Legacy Claude preset view retained for existing consumers. Other providers resolve this preset through providerModelCatalogs.",
       "defaults": { "model": "haiku" },
       "overrides": {}
     },
     "max": {
-      "description": "All agents use the most capable model",
-      "defaults": { "model": "opus" },
-      "overrides": {}
+      "scope": "claude",
+      "description": "Legacy Claude preset view retained for existing consumers. Other providers resolve this preset through providerModelCatalogs.",
+      "defaults": { "model": "sonnet" },
+      "overrides": { "sr-architect": "opus", "sr-product-manager": "opus" }
+    }
+  },
+  "providerModelCatalogs": {
+    "kimi": {
+      "default": "k3",
+      "models": ["k3", "kimi-for-coding", "kimi-for-coding-highspeed"],
+      "presets": {
+        "balanced": { "defaults": { "model": "k3" }, "overrides": {} },
+        "budget": { "defaults": { "model": "k3" }, "overrides": {} },
+        "max": { "defaults": { "model": "k3" }, "overrides": {} }
+      },
+      "cliAliasPrefix": "kimi-code/",
+      "reasoningEfforts": {
+        "k3": ["low", "high", "max"]
+      },
+      "note": "Install config and profiles retain exact ids or safe custom aliases. Preset names do not imply Claude aliases for Kimi. Process launch prefixes only the three documented official short ids with kimi-code/; every custom alias that matches the published model grammar passes through unchanged."
     }
   },
   "legacyCompat": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "specrails-core",
-  "version": "4.11.3",
-  "description": "AI agent workflow system for Claude Code — installs 12 specialized agents, orchestration commands, and persona-driven product discovery into any repository",
+  "version": "5.0.0",
+  "description": "Provider-independent AI agent workflow system for Claude Code, Codex, Gemini CLI, and Kimi Code",
   "type": "module",
   "bin": {
     "specrails-core": "bin/specrails-core.mjs"
@@ -17,7 +17,7 @@
     "pinned-versions.json"
   ],
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.19.0"
   },
   "repository": {
     "type": "git",
@@ -30,6 +30,10 @@
     "workflow",
     "developer-tools",
     "anthropic",
+    "kimi",
+    "moonshot-ai",
+    "gemini",
+    "codex",
     "llm",
     "ai",
     "automation",
@@ -53,9 +57,9 @@
     "build": "tsc -p tsconfig.json",
     "build:watch": "tsc -p tsconfig.json --watch",
     "typecheck": "tsc -p tsconfig.test.json --noEmit",
-    "test": "npm run typecheck && vitest run",
+    "test": "npm run build && npm run typecheck && vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
+    "test:coverage": "npm run build && vitest run --coverage",
     "dogfood": "npm run build && node bin/specrails-core.mjs init --yes",
     "prepack": "npm run build"
   },

package/schemas/profile.v1.json

@@ -23,14 +23,19 @@
       "maxLength": 512,
       "description": "Optional short summary of when to use this profile."
     },
+    "provider": {
+      "type": "string",
+      "enum": ["claude", "codex", "gemini", "kimi"],
+      "description": "Optional provider binding. Omitted profiles retain the legacy Claude model-alias contract. Provider-bound profiles retain exact model identifiers; Kimi additionally enforces its safe process-boundary grammar."
+    },
     "orchestrator": {
       "type": "object",
       "required": ["model"],
       "additionalProperties": false,
       "properties": {
         "model": {
-          "$ref": "#/$defs/modelAlias",
-          "description": "Model used to run the top-level implement orchestrator."
+          "$ref": "#/$defs/providerModelId",
+          "description": "Provider model identifier used to run the top-level implement orchestrator."
         }
       }
     },
@@ -38,7 +43,7 @@
       "type": "array",
       "minItems": 1,
       "items": { "$ref": "#/$defs/agentEntry" },
-      "description": "Ordered chain of agents that participate in the pipeline when this profile is active. Every profile (default + custom) must include the baseline trio (sr-architect, sr-developer, sr-reviewer) — the pipeline depends on all three. sr-merge-resolver and every other agent are optional add-ons selected at install time. Custom profiles add optional agents on top of the baseline.",
+      "description": "Ordered chain of agents that participate in the pipeline when this profile is active. Every profile (default + custom) must include the baseline trio (sr-architect, sr-developer, sr-reviewer) — the pipeline depends on all three, and they are the only agents the installer ships. Additional agents are user-authored 'custom-*' agents added on top of the baseline; a profile entry whose agent file does not exist is warned and skipped at run time.",
       "allOf": [
         {
           "description": "Required baseline agent: sr-architect",
@@ -73,12 +78,69 @@
       "items": { "$ref": "#/$defs/routingRule" }
     }
   },
+  "allOf": [
+    {
+      "if": {
+        "anyOf": [
+          { "not": { "required": ["provider"] } },
+          {
+            "required": ["provider"],
+            "properties": { "provider": { "const": "claude" } }
+          }
+        ]
+      },
+      "then": {
+        "properties": {
+          "orchestrator": {
+            "properties": { "model": { "$ref": "#/$defs/modelAlias" } }
+          },
+          "agents": {
+            "items": {
+              "properties": { "model": { "$ref": "#/$defs/modelAlias" } }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "required": ["provider"],
+        "properties": { "provider": { "const": "kimi" } }
+      },
+      "then": {
+        "properties": {
+          "orchestrator": {
+            "properties": { "model": { "$ref": "#/$defs/kimiModelId" } }
+          },
+          "agents": {
+            "items": {
+              "properties": { "model": { "$ref": "#/$defs/kimiModelId" } }
+            }
+          }
+        }
+      }
+    }
+  ],
   "$defs": {
     "modelAlias": {
       "type": "string",
       "enum": ["sonnet", "opus", "haiku"],
       "description": "Accepted model alias. Resolved to the current concrete model ID by the pipeline."
     },
+    "providerModelId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "pattern": "^\\S(?:.*\\S)?$",
+      "description": "Exact provider model identifier or user-configured alias. Core retains this value verbatim and applies documented provider-specific validation/normalization."
+    },
+    "kimiModelId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._/:-]*$",
+      "description": "Kimi model identifier accepted at the shell-free process boundary."
+    },
     "agentEntry": {
       "type": "object",
       "required": ["id"],
@@ -87,11 +149,11 @@
         "id": {
           "type": "string",
           "pattern": "^(sr|custom)-[a-z0-9][a-z0-9-]*$",
-          "description": "Agent identifier. MUST correspond to a file at `.claude/agents/<id>.md`."
+          "description": "Agent identifier. MUST correspond to the selected provider's role artifact."
         },
         "model": {
-          "$ref": "#/$defs/modelAlias",
-          "description": "Model override for this agent when this profile is active. When omitted, the agent's frontmatter `model:` is used as a fallback."
+          "$ref": "#/$defs/providerModelId",
+          "description": "Exact provider model override for this agent. When omitted, the provider default is used."
         },
         "required": {
           "type": "boolean",

package/templates/agents/sr-architect.md

@@ -51,6 +51,10 @@ Do not proceed with any design work, file reading, or artifact creation until sp
 
 Your working directory may NOT be the user's source repository. The user's source code, `openspec/**`, `.claude/rules/`, and `.git` all live under **`${SPECRAILS_REPO_DIR:-.}`** (the spawner sets the env var to the repo path; unset defaults to `.`, i.e. byte-identical to a classic in-repo run). Read specs from `${SPECRAILS_REPO_DIR:-.}/openspec/...`, scan conventions under `${SPECRAILS_REPO_DIR:-.}/.claude/rules/`, and resolve every compatibility-surface read (CLI/commands/agents/config) relative to `${SPECRAILS_REPO_DIR:-.}`.
 
+## Deterministic repo map (read before exploring)
+
+If the environment variable `SPECRAILS_REPO_MAP_PATH` is set and points to a readable file, **Read that file FIRST**, before any codebase exploration. It is a deterministic map of the repository (packages, ecosystems, rough sizes, README excerpt) generated by the spawner at zero AI cost. Use it to orient your exploration — do NOT spend turns on top-level discovery (`ls` at the root, locating packages, reading the README for structure). When the variable is unset, explore as normal.
+
 ## Core Responsibilities
 
 When invoked by the orchestrator with a specName argument, you must execute the following steps in order:
@@ -158,6 +162,32 @@ After producing the task breakdown and before finalizing output:
 
 This phase is mandatory. Do not skip it even if the change appears purely internal.
 
+### 7. Emit Design Confidence (MANDATORY)
+
+Implementation is the expensive phase of this pipeline — it must only run on a design you actually trust. After completing the design and task breakdown, score your own confidence and write it to:
+
+```
+${SPECRAILS_REPO_DIR:-.}/openspec/changes/<name>/design-confidence.json
+```
+
+Required fields:
+
+- `schema_version`: always `"1"`
+- `change`: kebab-case change name
+- `agent`: always `"architect"`
+- `scored_at`: current ISO 8601 timestamp
+- `confidence`: `"high"` | `"medium"` | `"low"`
+- `reason`: 1–2 sentences justifying the level — concrete, not boilerplate
+- `blocking_question`: when `confidence` is `"low"`, the **single most blocking unknown** phrased as one focused question a human can answer — nothing else. Otherwise `null`.
+
+Rubric:
+
+- **high** — the code evidence is conclusive: you located the exact files/identifiers, the design is unambiguous, and the tasks follow directly from it.
+- **medium** — the design is likely correct but rests on one non-obvious assumption you could not fully verify. Name that assumption in `reason`.
+- **low** — multiple plausible interpretations or designs exist and you cannot choose between them without information you don't have (missing requirement, ambiguous intent, contradictory specs). Do NOT pad the design to look confident — a `low` with a sharp `blocking_question` is a SUCCESSFUL architect output: it saves the entire implementation cost of building the wrong thing.
+
+Never inflate the level. The orchestrator halts implementation on `low` and relays your `blocking_question` to the human — that is the designed outcome, not a failure.
+
 ## Output Format
 
 When analyzing spec changes, produce your output in this structure:

package/templates/agents/sr-developer.md

@@ -140,9 +140,19 @@ This gate is non-negotiable. Phase 4 is unreachable until every checkbox in task
 
 **For each unit of functionality within the apply cycle, follow this TDD cycle:**
 
-1. **RED** — Write a failing test that describes the expected behavior. Run the test. Confirm it fails for the right reason.
-2. **GREEN** — Write the minimum production code to make the test pass. Run the test. Confirm it passes.
-3. **REFACTOR** — Clean up the code while keeping all tests green. Run all tests after refactoring.
+1. **RED** — Write a failing test that describes the expected behavior. Run **only that test file** (scoped run). Confirm it fails for the right reason.
+2. **GREEN** — Write the minimum production code to make the test pass. Re-run **only that test file**. Confirm it passes.
+3. **REFACTOR** — Clean up the code while keeping tests green. Re-run **the test files covering the files you touched** — not the whole suite. The full suite runs exactly once, in Phase 4 — running it after every task multiplies wall-clock time without catching anything Phase 4 won't.
+
+## Test-Execution Economy (MANDATORY)
+
+Test runs are the single largest cost of this pipeline. The contract:
+
+- **Inside task cycles (Phase 3): scoped runs only.** Invoke the runner with an explicit path/filter — `npx vitest run <file>`, `npx jest <file>`, `pytest <file>`, `go test ./<pkg>`, `./gradlew :<module>:test --tests <Class>`, etc. Derive the scoped form from the project's full test command. **Never run the full suite inside a task cycle.**
+- **The full suite runs exactly ONCE** — at your Phase 4 validation gate, after every task is `- [x]`. It does not run per task, per file, or "just to be safe".
+- **When a scoped run fails**, extract only the failing test names and the relevant error excerpt (≤50 lines) into your reasoning. Never re-paste a full runner log.
+- **Loop detection**: if you run the same command 3 times without an intervening code change and results are inconsistent, STOP running it — state your hypothesis and change the code or the test instead.
+- **File re-read discipline**: a file you already read is in your context. Before reading any file a second time, write one sentence stating what you already learned from it — then only re-read if it changed since.
 
 **TDD rules:**
 - Never write production code without a corresponding test
@@ -170,11 +180,14 @@ Follow the project architecture strictly:
 
 **Prerequisite: Phase 4 is only reachable if the Phase 3 checkbox verification gate passed** — meaning every task in `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<specName>/tasks.md` is marked `- [x]`. If any `- [ ]` items remain, return to Phase 3.
 
-**All tests MUST pass before you hand off to the reviewer. This is a hard gate — do not proceed if any test fails.**
+**All tests MUST pass before you hand off to the reviewer. This is a hard gate — do not hand off with known failures.**
+
+This phase is the pipeline's **single full verification pass** — the inner TDD loop stayed scoped precisely so this one can be exhaustive.
 
-- Run the **full CI-equivalent verification suite** (see below)
-- If any test fails, fix the issue and re-run ALL tests
-- Repeat until all tests pass — there is no maximum number of attempts
+- Run the **full CI-equivalent verification suite** (see below) — this is the ONE full-suite run of your phase
+- If anything fails: fix it, then re-run **only the failing test files / failing check** — not the whole suite
+- You have a budget of **2 fix cycles**. After the fixes converge, run the full suite ONE final time to confirm
+- If failures persist after the budget: **HALT and report honestly** — list every failing test verbatim to the orchestrator. Do NOT keep looping, do NOT weaken or skip tests to force green, do NOT hand off silently
 - Review each file for adherence to conventions
 - Ensure all imports are correct and no circular dependencies exist
 - Verify type annotations are complete
@@ -183,7 +196,7 @@ Follow the project architecture strictly:
 
 ## CI-Equivalent Verification Suite
 
-You MUST run ALL of these checks after implementation. These match the CI pipeline exactly:
+You MUST run ALL of these checks after implementation — **once, at the Phase 4 gate** (see Test-Execution Economy). These match the CI pipeline exactly:
 
 {{CI_COMMANDS_FULL}}
 

package/templates/agents/sr-reviewer.md

@@ -52,42 +52,36 @@ Your working directory may NOT be the user's source repository. The user's sourc
 You are the last line of defense between developer output and a PR. You:
 1. **Verify TDD compliance** — every piece of production code must have corresponding tests
 2. **Verify spec completeness** — every requirement from the architect's spec must be implemented
-3. Run every check that CI runs — in the exact same way
+3. Verify the change is green — **scoped-first**: the developer's Phase 4 already ran the full CI-equivalent suite; you re-verify the changed surface, and run the full suite yourself only when your own fixes make it necessary (see Verification policy)
 4. Fix any failures you find (up to 3 attempts per issue)
 5. Verify code quality and consistency across all changes
 6. Report what you found and fixed
 
 ## CI/CD Pipeline Equivalence
 
-The CI pipeline runs these checks. You MUST run ALL of them in this exact order:
+The CI pipeline runs these checks, in this exact order:
 
 {{CI_COMMANDS_FULL}}
 
-## Known CI vs Local Gaps
-
-These are the most common reasons code passes locally but fails in CI:
-
-{{CI_KNOWN_GAPS}}
-
-## Layer Review Findings (injected at runtime by orchestrator)
+## Verification policy (scoped-first)
 
-The orchestrator runs specialized layer reviewers in parallel before you launch. Their reports are injected here. A value of `"SKIPPED"` means no files of that layer type were in the changeset.
+The developer hands off ONLY after a green full CI-equivalent pass (their Phase 4 hard gate). Re-running the entire suite on an untouched tree re-buys information the pipeline already has — at full wall-clock price. Your verification is therefore **scoped-first**:
 
-**These are NOT `/specrails:enrich` placeholders. They use `[injected]` notation, not `{{...}}` notation.** The `[injected]` markers below are replaced by the actual report text when the orchestrator launches you.
+1. **Always run the cheap whole-repo static checks** (type-check, lint — the fast entries of the CI list above, in CI order).
+2. **Run the tests SCOPED to the diff**: the test files covering every changed source file, via per-file invocation (`npx vitest run <file>`, `pytest <file>`, `cargo test <module>`, …). Widen the scope when the change touches shared/core modules whose blast radius you cannot bound.
+3. **Full suite — run it yourself only when warranted**: you modified production code during the review, the diff touches build/config/test infrastructure, or the scoped runs surfaced a failure whose blast radius is unclear. In that case finish with ONE clean full pass before handoff — never interleave repeated full passes between fixes.
+4. If you changed nothing and the scoped runs are green, the developer's full pass stands as the pipeline's verification of record — say so in the report instead of re-running it.
 
-FRONTEND_REVIEW_REPORT:
-[injected]
-
-BACKEND_REVIEW_REPORT:
-[injected]
+## Known CI vs Local Gaps
 
-SECURITY_REVIEW_REPORT:
-[injected]
+These are the most common reasons code passes locally but fails in CI:
 
----
+{{CI_KNOWN_GAPS}}
 
 ## Review Checklist
 
+You are the single reviewer for this change. There are no separate layer reviewers — frontend, backend, security, and performance concerns are all your responsibility in this pass. Weight each dimension by what the changeset actually touches.
+
 After running CI checks, also review for:
 
 ### TDD Compliance (mandatory)
@@ -114,11 +108,22 @@ After running CI checks, also review for:
 - Import style matches the rest of the codebase
 - Error handling patterns are consistent
 
+### Security (scale to what the change touches)
+- No secrets, tokens, or credentials committed
+- User-controlled input is validated and, where interpolated into queries/commands/paths, properly escaped or parameterized
+- No new injection, path-traversal, or SSRF surface introduced
+- AuthZ/authN checks are present on new endpoints or privileged operations
+
+### Performance (scale to what the change touches)
+- No obvious N+1 queries or unbounded loops over user-controlled input
+- Expensive work is not added to hot paths without justification
+- Large allocations, unbounded caches, and blocking I/O on async paths are flagged
+
 ## Workflow
 
-1. **Run all CI checks** (all layers, in the exact order CI runs them)
-2. **If anything fails**: Fix it, then re-run ALL checks from scratch (not just the failing one)
-3. **Repeat** up to 3 fix-and-verify cycles
+1. **Run the scoped-first verification** (see Verification policy: static checks + diff-scoped tests, in CI order)
+2. **If anything fails**: Fix it, then re-run **only the failed check, scoped to the failing files** where the runner supports it (`npx vitest run <file>`, `pytest <file>`, lint on the changed files) — never the entire ordered list after every individual fix — and escalate to a full pass per the policy
+3. **Repeat** up to 3 fix-and-verify cycles; when any cycle changed code, finish with ONE clean full CI-equivalent pass
 4. **Report** a summary of what passed, what failed, and what you fixed
 5. **Task Completion Gate** — Before archiving, verify all tasks are complete:
    - Read `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<specName>/tasks.md`
@@ -197,26 +202,34 @@ When done, produce this report:
 ### Issues Fixed
 - [list of issues found and how they were fixed]
 
-### Layer Review Summary
-| Layer | Status | Finding Count | Notable Issues |
-|-------|--------|--------------|----------------|
-| Frontend | CLEAN / ISSUES_FOUND / SKIPPED | N | ... |
-| Backend | CLEAN / ISSUES_FOUND / SKIPPED | N | ... |
-| Security | CLEAN / WARNINGS / BLOCKED / SKIPPED | N | ... |
+### Review Dimensions
+| Dimension | Status | Finding Count | Notable Issues |
+|-----------|--------|--------------|----------------|
+| Correctness / tests | CLEAN / ISSUES_FOUND | N | ... |
+| Security | CLEAN / WARNINGS / BLOCKED | N | ... |
+| Performance | CLEAN / WARNINGS | N | ... |
 
-[List any High or Critical findings from layer reviews that warrant attention]
+SECURITY_STATUS: <BLOCKED | WARNINGS | CLEAN>
+
+[List any High or Critical findings that warrant attention]
 
 ### Files Modified by Reviewer
 - [list of files the reviewer had to touch]
 ```
 
+The `SECURITY_STATUS:` line is MANDATORY and machine-parsed by the orchestrator — emit it exactly once, on its own line, with one of the three values. `BLOCKED` means you found a security issue severe enough that the change must not ship (committed secret, injection, missing auth on a privileged operation). `WARNINGS` means non-blocking security findings exist. `CLEAN` otherwise.
+
 ## Rules
 
 - Never ask for clarification. Fix issues autonomously.
-- Always run ALL checks, even if you think nothing changed in a layer.
+- Follow the Verification policy: scoped-first, one full pass only when your own changes (or an unbounded blast radius) warrant it. Never skip the cheap static checks.
+- In the CI Checks report table, mark suites you did not re-run as `covered by developer's full pass` — never as passed-by-you.
+- **Output economy**: when a check fails, carry forward only the failing test/rule names and the relevant error excerpt (≤50 lines) — never re-paste a full runner log into your reasoning.
+- **File re-read discipline**: a file you already read is in your context. Before reading it again, state in one sentence what you already learned from it — re-read only if it changed.
+- **Loop detection**: the same command run 3 times with no intervening code change and inconsistent results means STOP — reassess instead of re-running.
 - When fixing lint errors, understand the rule before applying a fix — don't just suppress with disable comments.
 - If a test fails, read the test AND the implementation to understand the root cause before fixing.
-- If a layer reviewer reports High severity findings, include them in your Issues Fixed or Issues Found section. Attempt to fix High-severity layer findings that are straightforward (e.g., adding a missing `alt` attribute, adding a missing `LIMIT` to a query). Flag Critical or architecturally complex findings for human review — do NOT attempt to fix them automatically.
+- Attempt to fix High-severity findings that are straightforward (e.g., adding a missing `alt` attribute, adding a missing `LIMIT` to a query). Flag Critical or architecturally complex findings for human review — do NOT attempt to fix them automatically.
 
 ## Explain Your Work
 

package/templates/codex-skills/batch-implement/SKILL.md

@@ -86,60 +86,37 @@ the pipeline yourself):
   > Read `jq '.tickets["<TICKET_ID>"]' .specrails/local-tickets.json`
   > for the full ticket. Follow the `$sr-architect` skill
   > instructions exactly.
-  >
-  > In `design.md`'s `## Context` section, include a
-  > `Scope: <labels>` line drawn from: `frontend`, `backend`,
-  > `both`, `security-sensitive`, `performance-sensitive`.
 
 - `wait_agent`. Parse reply for the plan path. `close_agent`.
-- Open the plan + design.md, parse the `Scope:` line.
+- Open the plan + design.md.
 - If the architect returned `BLOCKED: …`, mark this ticket
   as failed for the batch report and **continue to the next
   ticket** — do not stop the batch.
 
 #### 1.b Developer phase (per ticket)
 
-Routing matrix (mirrors `$implement`):
-
-| scope contains | rails available | spawn |
-|---|---|---|
-| `frontend` only | `sr-frontend-developer` | $sr-frontend-developer |
-| `backend` only | `sr-backend-developer` | $sr-backend-developer |
-| `frontend` only | (no fe specialist) | $sr-developer |
-| `backend` only | (no be specialist) | $sr-developer |
-| `both` + both specialists + tagged tasks.md | — | TWO devs parallel |
-| else | — | $sr-developer |
+One developer rail. Unless a profile routes the ticket to a
+listed `custom-*` developer, spawn `$sr-developer`.
 
 - `spawn_agent`. `send_message`:
 
-  > `$<developer-skill>`
+  > `$sr-developer`
   >
   > Ticket id: `<TICKET_ID>`
   > Plan: `<PLAN_PATH>`
-  > Scope: `<comma-separated labels>`
   >
-  > Follow the `$<developer-skill>` skill instructions exactly.
+  > Follow the `$sr-developer` skill instructions exactly.
 
 - `wait_agent`. Capture file list. `close_agent`.
 - If `BLOCKED: …` → mark ticket as failed in the batch report
   and move to next ticket.
 
-#### 1.c Reviewer phase (per ticket) — parallel where possible
-
-Always spawn `$sr-reviewer`. Additionally if installed AND
-scope matches:
-
-| scope flag | additional rail |
-|---|---|
-| `frontend` | `$sr-frontend-reviewer` |
-| `backend` | `$sr-backend-reviewer` |
-| `security-sensitive` | `$sr-security-reviewer` |
-| `performance-sensitive` | `$sr-performance-reviewer` |
+#### 1.c Reviewer phase (per ticket)
 
-Spawn ALL reviewers in parallel, then `wait_agent` on each.
-`close_agent` each.
+Spawn the single `$sr-reviewer` — it covers correctness, tests,
+security, and performance. `wait_agent`, then `close_agent`.
 
-Aggregate verdicts (same matrix as `$implement`):
+Verdict (same matrix as `$implement`):
 
 - `clean` — every reviewer ≥70, no fix/blocked verdicts.
 - `fix needed` — any "fix needed", OR score <70 with no