specrails-core 5.0.0 → 5.1.0

package/integration-contract.json

@@ -1,44 +1,74 @@
 {
-  "schemaVersion": "3.2",
+  "schemaVersion": "4.0",
   "providers": {
     "claude": {
-      "enrichCommand": "/specrails:enrich",
-      "enrichArgs": ["--from-config"],
-      "updateCommand": "/specrails:enrich",
-      "updateArgs": ["--update"],
+      "updateCommand": "update",
       "cli": {
-        "initArgs": [],
-        "enrichArgs": ["--dangerously-skip-permissions", "--output-format", "stream-json", "-p", "/specrails:enrich"],
-        "enrichFromConfigArgs": ["--dangerously-skip-permissions", "--output-format", "stream-json", "-p", "/specrails:enrich --from-config"]
+        "initArgs": [
+          "init",
+          "--yes",
+          "--provider",
+          "claude"
+        ],
+        "updateArgs": [
+          "update",
+          "--provider",
+          "claude"
+        ]
+      },
+      "initCommand": "init",
+      "workflows": {
+        "implement": "/specrails:implement",
+        "batch-implement": "/specrails:batch-implement",
+        "retry": "/specrails:retry"
       }
     },
     "codex": {
-      "enrichCommand": "$enrich",
-      "enrichArgs": ["--from-config"],
-      "updateCommand": "$enrich",
-      "updateArgs": ["--update"],
+      "updateCommand": "update",
       "cli": {
-        "initArgs": [],
-        "enrichArgs": ["exec", "run enrich"],
-        "enrichFromConfigArgs": ["exec", "run enrich --from-config"]
+        "initArgs": [
+          "init",
+          "--yes",
+          "--provider",
+          "codex"
+        ],
+        "updateArgs": [
+          "update",
+          "--provider",
+          "codex"
+        ]
+      },
+      "initCommand": "init",
+      "workflows": {
+        "implement": "$implement",
+        "batch-implement": "$batch-implement",
+        "retry": "$retry"
       }
     },
     "gemini": {
-      "enrichCommand": "/specrails:enrich",
-      "enrichArgs": ["--from-config"],
-      "updateCommand": "/specrails:enrich",
-      "updateArgs": ["--update"],
+      "updateCommand": "update",
       "cli": {
-        "initArgs": [],
-        "enrichArgs": ["-p", "/specrails:enrich", "--output-format", "stream-json"],
-        "enrichFromConfigArgs": ["-p", "/specrails:enrich --from-config", "--output-format", "stream-json"]
+        "initArgs": [
+          "init",
+          "--yes",
+          "--provider",
+          "gemini"
+        ],
+        "updateArgs": [
+          "update",
+          "--provider",
+          "gemini"
+        ]
+      },
+      "initCommand": "init",
+      "workflows": {
+        "implement": "/specrails:implement",
+        "batch-implement": "/specrails:batch-implement",
+        "retry": "/specrails:retry"
       }
     },
     "kimi": {
-      "enrichCommand": "/skill:specrails-enrich",
-      "enrichArgs": ["--from-config"],
-      "updateCommand": "/skill:specrails-enrich",
-      "updateArgs": ["--update"],
+      "updateCommand": "update",
       "cli": {
         "binary": "node",
         "providerBinary": "kimi",
@@ -69,89 +99,172 @@
         "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`."
+        "initArgs": [
+          "init",
+          "--yes",
+          "--provider",
+          "kimi"
+        ],
+        "resumeArgs": [
+          "--session=<session-id>"
+        ],
+        "notes": "CLI-only provider execution. Installation/update uses the deterministic Core CLI above. Headless workflows use the managed Node skill runner, never literal /skill text in kimi -p. Role waves await every child and preserve frozen Core execution context. Authenticate once with kimi login.",
+        "updateArgs": [
+          "update",
+          "--provider",
+          "kimi"
+        ],
+        "workflowArgs": [
+          ".kimi-code/specrails/run-skill.mjs",
+          "--skill",
+          "<skill-id>",
+          "--model",
+          "<model-id>",
+          "--args",
+          "<arguments>"
+        ]
+      },
+      "initCommand": "init",
+      "workflows": {
+        "implement": "/skill:specrails-implement",
+        "batch-implement": "/skill:specrails-batch-implement",
+        "retry": "/skill:specrails-retry"
       }
     }
   },
   "tiers": {
-    "quick": {
-      "description": "Template-based install with minimal defaults. No AI codebase analysis. Agents are functional immediately.",
-      "enrichFlag": "--quick",
-      "checkpoints": ["base_install", "agent_selection", "agent_generation"],
+    "standard": {
+      "description": "Deterministic installation of the core agents, provider workflows and required skills. No model invocation or enrichment.",
+      "checkpoints": [
+        "base_install",
+        "agent_generation",
+        "command_generation"
+      ],
       "requiresEnrich": false
-    },
-    "full": {
-      "description": "Full AI-powered install. Analyzes codebase, generates VPC personas, creates personalized agents.",
-      "enrichFlag": "--from-config",
-      "checkpoints": ["codebase_analysis", "vpc_discovery", "persona_synthesis", "agent_generation", "command_generation"],
-      "requiresEnrich": true
     }
   },
   "configSchema": {
     "file": ".specrails/install-config.yaml",
     "version": 1,
     "fields": {
-      "version": "number — schema version, currently 1",
-      "provider": "string — claude | codex | gemini | kimi",
-      "tier": "string — full | quick",
-      "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)"
+      "version": "number \u2014 schema version, currently 1",
+      "provider": "string \u2014 claude | codex | gemini | kimi",
+      "tier": "Deprecated legacy string, tolerated and ignored; all installs use deterministic placement.",
+      "agents.selected": "string[] \u2014 unique lowercase kebab-case agent ids to install (1-64 characters)",
+      "agents.excluded": "string[] \u2014 unique lowercase kebab-case agent ids to skip; must not overlap agents.selected",
+      "models.preset": "string \u2014 balanced | budget | max; resolved within the selected provider catalog",
+      "models.defaults.model": "string \u2014 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> \u2014 exact per-agent provider model ids or configured aliases with the same provider-specific validation (highest priority)"
     }
   },
   "checkpoints": {
-    "base_install": "Templates and directory structure copied",
-    "agent_selection": "Agent list finalized from config or TUI",
-    "codebase_analysis": "Codebase language/framework/architecture detected",
-    "vpc_discovery": "VPC personas researched and drafted",
-    "persona_synthesis": "Final persona files written",
-    "agent_generation": "All selected agents generated with placeholders filled",
-    "command_generation": "All workflow commands installed and configured"
+    "base_install": "Runtime prerequisites and artifact workspace resolved",
+    "agent_generation": "Core agents and selected custom roles placed",
+    "command_generation": "Workflow commands, required skills and installation manifest verified"
   },
   "modelPresets": {
     "balanced": {
       "scope": "claude",
       "description": "Legacy Claude preset view retained for existing consumers. Other providers resolve this preset through providerModelCatalogs.",
-      "defaults": { "model": "sonnet" },
+      "defaults": {
+        "model": "sonnet"
+      },
       "overrides": {}
     },
     "budget": {
       "scope": "claude",
       "description": "Legacy Claude preset view retained for existing consumers. Other providers resolve this preset through providerModelCatalogs.",
-      "defaults": { "model": "haiku" },
+      "defaults": {
+        "model": "haiku"
+      },
       "overrides": {}
     },
     "max": {
       "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" }
+      "defaults": {
+        "model": "sonnet"
+      },
+      "overrides": {
+        "sr-architect": "opus",
+        "sr-product-manager": "opus"
+      }
     }
   },
   "providerModelCatalogs": {
     "kimi": {
       "default": "k3",
-      "models": ["k3", "kimi-for-coding", "kimi-for-coding-highspeed"],
+      "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": {} }
+        "balanced": {
+          "defaults": {
+            "model": "k3"
+          },
+          "overrides": {}
+        },
+        "budget": {
+          "defaults": {
+            "model": "k3"
+          },
+          "overrides": {}
+        },
+        "max": {
+          "defaults": {
+            "model": "k3"
+          },
+          "overrides": {}
+        }
       },
       "cliAliasPrefix": "kimi-code/",
       "reasoningEfforts": {
-        "k3": ["low", "high", "max"]
+        "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": {
     "setupCommandAlias": false,
-    "note": "The Node-native installer ships /specrails:enrich only. Existing repos should prune any leftover /specrails:setup alias during re-install or update."
+    "enrichCommand": false,
+    "note": "Core 5 installs directly. Legacy config tier is tolerated; enrich, --quick and --lite are removed. Hosts must negotiate schema 4 deterministic lifecycle."
+  },
+  "lifecycle": {
+    "mode": "deterministic",
+    "requiresEnrich": false,
+    "initCommand": "init",
+    "updateCommand": "update",
+    "minimumCoreMajor": 5,
+    "removedCommands": [
+      "enrich"
+    ],
+    "removedFlags": [
+      "--quick",
+      "--lite"
+    ]
+  },
+  "execution": {
+    "schemaVersion": 1,
+    "contextEnv": "SPECRAILS_EXECUTION_CONTEXT",
+    "context": "Absolute JSON file: runId, backlogRoot, backlogPath?, artifactRoot, artifactRepositoryId, repositories[{id,name,path,baseSha?}], ownership{git,backlog,worktrees:host|core}, specs[{id,title,description,repositoryIds?,acceptanceCriteria?}]",
+    "runtime": ".specrails/runtime/pipeline.mjs",
+    "operations": [
+      "init",
+      "status",
+      "phase",
+      "verify",
+      "archive-check",
+      "preview",
+      "apply-preview"
+    ],
+    "statePath": "<backlogRoot>/.specrails/pipeline/<runId>/state.json",
+    "verification": "Successful argv-based commands captured by the runtime, bound to frozen scope, candidate files and relevant execution environment. Unknown or stale evidence cannot pass archive.",
+    "hostOwnership": "Host worktrees are used directly; host git/backlog are not mutated by Core delivery."
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Provider-independent AI agent workflow system for Claude Code, Codex, Gemini CLI, and Kimi Code",
   "type": "module",
   "bin": {
@@ -61,7 +61,10 @@
     "test:watch": "vitest",
     "test:coverage": "npm run build && vitest run --coverage",
     "dogfood": "npm run build && node bin/specrails-core.mjs init --yes",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "test:scripts": "node --test scripts/release-utils.test.mjs",
+    "check:package": "npm run build && node scripts/verify-package.mjs",
+    "ci": "npm run typecheck && npm run test:scripts && npm run test:coverage && npm run check:package"
   },
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",

package/templates/agents/sr-developer.md

@@ -50,17 +50,15 @@ You are a polyglot engineer with extraordinary depth in:
 
 You don't just write code that works — you write code that is elegant, maintainable, testable, and performant.
 
-## Repository location (read first)
+## Frozen execution handoff
 
-Your working directory may NOT be the user's source repository. The user's source code, `openspec/**`, the project `CLAUDE.md`, `.claude/rules/`, and `.git` all live under **`${SPECRAILS_REPO_DIR:-.}`** (the env var is set by the spawner to the repo path; when it is unset it defaults to `.`, i.e. the current directory — byte-identical to a classic in-repo run).
+Read the supplied absolute SPECRAILS_EXECUTION_CONTEXT. Preserve frozen specs/acceptance, run/change and selected repository IDs. Every source path is resolved against its task's repository; only a single selected root has an implicit target. Never refetch scope or mutate host-owned Git, backlog or worktrees.
 
-Concretely:
-- **Every openspec read/write** targets `${SPECRAILS_REPO_DIR:-.}/openspec/...`.
-- **Every source-file edit** named in `tasks.md` uses repo-relative paths (e.g. `src/foo.ts`); resolve and edit them as `${SPECRAILS_REPO_DIR:-.}/<path>` so the change lands in the real repo, not the working directory.
-- **CI / build / test commands** run from inside the repo — `cd "${SPECRAILS_REPO_DIR:-.}"` (or run them with that as the working directory) before invoking them.
-- **Convention scans** of the project `CLAUDE.md` and `.claude/rules/` read from `${SPECRAILS_REPO_DIR:-.}`.
+SPECRAILS_REPO_DIR points to artifactRoot for `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<specName>/` and the official apply workflow. Source edits/test cwd use their own repository paths; framework workspace, backlogRoot and artifactRoot can differ.
 
-Run-state directories you write to during a run — `.claude/agent-memory/`, `.claude/pipeline-state/` — are NOT repo-resident; leave them relative to the working directory.
+Coordinator owns phase transitions. Keep workers foreground, collect terminal results and resume unchecked tasks without discarding completed implementation.
+
+Execute checks through `node "${SPECRAILS_PIPELINE_RUNTIME:-.specrails/runtime/pipeline.mjs}" verify --request <stateDir/checks.json>`. Requests contain kind (scoped/full) and commands with repositoryId, command, args, explicit cwd and optional env/timeoutMs. Use scoped repair requests, then one final full request covering every selected repo after aggregate task completion. Runtime captures actual evidence; never hand-write a PASS receipt. Requests/notes belong under stateDir.
 
 ## Your Mission
 
@@ -93,7 +91,7 @@ You MUST follow Test-Driven Development. This is non-negotiable. The cycle is: *
 - Read the OpenSpec change spec thoroughly
 - Read referenced base specs
 - Read layer-specific CLAUDE.md files ({{LAYER_CLAUDE_MD_PATHS}})
-- **Read recent failure records**: Check `.claude/agent-memory/failures/` for JSON records where `file_pattern` matches files you will create or modify. For each matching record, treat `prevention_rule` as an explicit guardrail in your implementation plan. If the directory does not exist or is empty, proceed normally — this is expected on fresh installs.
+- **Read recent failure records**: Check `<stateDir>/notes/failures/` for JSON records where `file_pattern` matches files you will create or modify. For each matching record, treat `prevention_rule` as an explicit guardrail in your implementation plan. If the directory does not exist or is empty, proceed normally — this is expected on fresh installs.
 - Identify all files that need to be created or modified
 - Understand the data flow through the architecture
 
@@ -220,7 +218,7 @@ You MUST run ALL of these checks after implementation — **once, at the Phase 4
 
 ## Explain Your Work
 
-When you make a significant implementation decision, write an explanation record to `.claude/agent-memory/explanations/`.
+When you make a significant implementation decision, write an explanation record to `<stateDir>/notes/explanations/`.
 
 **Write an explanation when you:**
 - Chose an implementation approach over a plausible alternative
@@ -236,7 +234,7 @@ When you make a significant implementation decision, write an explanation record
 **How to write an explanation record:**
 
 Create a file at:
-  `.claude/agent-memory/explanations/YYYY-MM-DD-developer-<slug>.md`
+  `<stateDir>/notes/explanations/YYYY-MM-DD-developer-<slug>.md`
 
 Use today's date. Use a kebab-case slug describing the decision topic (max 6 words).
 

package/templates/agents/sr-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: sr-reviewer
-description: "Use this agent as the final quality gate after developer agents complete implementation. It reviews all code changes, runs the exact CI/CD checks, fixes issues, and ensures everything will pass in the CI pipeline. Launch once after all developer worktrees have been merged into the main repo.\n\nExamples:\n\n- Example 1:\n  user: (orchestrator) All developers completed. Review the merged result.\n  assistant: \"Launching the reviewer agent to run CI-equivalent checks and fix any issues.\"\n\n- Example 2:\n  user: (orchestrator) Developer agent finished implementing. Verify before PR.\n  assistant: \"Let me launch the reviewer agent to validate the implementation matches CI requirements.\""
+description: "Use this agent as the final quality gate after developer agents complete implementation. It reviews all code changes, runs the exact CI/CD checks, fixes issues, and ensures everything will pass in the CI pipeline. Launch once on the complete candidate in the selected repository roots.\n\nExamples:\n\n- Example 1:\n  user: (orchestrator) All developers completed. Review the merged result.\n  assistant: \"Launching the reviewer agent to run CI-equivalent checks and fix any issues.\"\n\n- Example 2:\n  user: (orchestrator) Developer agent finished implementing. Verify before PR.\n  assistant: \"Let me launch the reviewer agent to validate the implementation matches CI requirements.\""
 model: sonnet
 color: red
 memory: project
@@ -43,9 +43,15 @@ Leave empty to review all areas with equal weight.
 
 Do not proceed with any review work until specName is confirmed.
 
-## Repository location (read first)
+## Frozen execution and receipt handoff
 
-Your working directory may NOT be the user's source repository. The user's source code, `openspec/**`, 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 the change spec from `${SPECRAILS_REPO_DIR:-.}/openspec/...`, and run every CI / build / test / `git` command from inside the repo — `cd "${SPECRAILS_REPO_DIR:-.}"` (or use it as the working directory) before invoking them. (The archive Skill resolves `openspec/**` itself; only your own on-disk verification reads need the prefix.)
+Read supplied immutable SPECRAILS_EXECUTION_CONTEXT and exact specName. Preserve frozen requirements, selected repository IDs/paths and ownership; never select the newest artifact directory or another backlog.
+
+SPECRAILS_REPO_DIR points to artifactRoot for `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<specName>/`. Source inspection, fixes and test cwd follow each task's repository ID. Do not mutate host-owned Git/backlog/worktrees.
+
+Inspect managed runtime status --json. Reuse the developer's full receipt only when verification.valid is true and its commands cover required checks. Execute scoped/full requests via `node "${SPECRAILS_PIPELINE_RUNTIME:-.specrails/runtime/pipeline.mjs}" verify --request <stateDir/checks.json>`. Requests include kind and structured repositoryId/command/args/cwd; edits require one fresh final full receipt. No baseline PASS proves missing acceptance.
+
+Coordinator owns phase transitions. Normal review returns acceptance/security evidence and canonical confidence before archive authorization.
 
 ## Your Mission
 
@@ -130,41 +136,30 @@ After running CI checks, also review for:
    - Search for any lines matching `- [ ]` (hyphen, space, open-bracket, space, close-bracket)
    - **If any `- [ ]` lines are found**: BLOCK archive. List every incomplete task title. Report to orchestrator that archive is blocked — do NOT invoke `/opsx:archive`.
    - **If no `- [ ]` lines remain** (all tasks are `- [x]`): gate passes — proceed to Step 6.
-6. **Archive — EXECUTE `opsx:archive` (NON-NEGOTIABLE).** Only reachable when the Step 5 gate passes.
+6. **Confidence before archive.** Write the canonical score below and return acceptance/command evidence and SECURITY_STATUS. Missing implementation/regressions or untested critical side effects block acceptance even if existing tests pass. Normal review stops here without archive.
 
-   > ⛔ **OpenSpec Skill Execution Contract.** You are the *executor* of the official OpenSpec skill `opsx:archive`. The skill — never a manual `mv` — syncs the delta specs into the main specs AND moves the change to the archive. You run **UNATTENDED** (background subagent, no human to answer prompts).
+### Explicit archive-only continuation
 
-   **1 — EXECUTE, never emulate.** Your archive action MUST be this literal tool call (a real Skill invocation in your transcript, not a `mv`, not an emulation):
-   ```
-   Skill("opsx:archive", "<specName>")
-   ```
-   `opsx:archive` **syncs the delta specs** from `openspec/changes/<specName>/specs/` into `openspec/specs/` AND moves the change to `openspec/changes/archive/YYYY-MM-DD-<specName>/`.
+Only continue with both ARCHIVE_ONLY=true and ARCHIVE_AUTHORIZED=true after coordinator runtime archive-check succeeds. Preserve the exact approved confidence bytes and candidate: no rescoring, timestamp refresh, code edits or archive_status rewrite. Repairs return to normal review and require new approval.
 
-   **You are EMULATING (a CRITICAL FAILURE) if you** run `mkdir`/`mv` to archive yourself, hand-copy delta specs into `openspec/specs/`, or print "Archive Complete" without the `Skill("opsx:archive")` call having actually run.
+Recheck the Task Completion Gate and strict official validation from `${SPECRAILS_REPO_DIR:-.}`. Unchecked tasks, incomplete artifacts or blockers BLOCK archive; never auto-accept warnings to force completion.
 
-   **2 — UNATTENDED pre-authorization.** `opsx:archive` prompts (`AskUserQuestion`) for human sessions. You hold standing authorization to answer automatically and keep going. **Never emit `AskUserQuestion`; never wait for input.** When it would prompt:
-   - Change selection → use `<specName>`.
-   - "Artifacts incomplete — proceed?" → YES, proceed.
-   - "Tasks incomplete — proceed?" → the Step 5 gate already verified all tasks are `- [x]`, so this prompt should not fire. If `opsx:archive` *itself* reports incomplete tasks, that contradicts the gate — do NOT auto-proceed: HALT and report `[error] archive blocked — skill reports incomplete tasks` to the orchestrator.
-   - "Delta specs: Sync now vs Archive without syncing?" → ALWAYS choose **Sync now** (canonical). NEVER skip the sync.
+Invoke the actual official Skill from `${SPECRAILS_REPO_DIR:-.}`:
 
-   **3 — PROOF-OF-EXECUTION gate.** After the skill returns, verify on disk:
-   - `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<specName>/` no longer exists (the change was moved), AND
-   - the delta-spec changes are now present under `${SPECRAILS_REPO_DIR:-.}/openspec/specs/` — open the affected `${SPECRAILS_REPO_DIR:-.}/openspec/specs/<capability>/spec.md` and confirm the change's added/modified requirements are there.
+```
+Skill("opsx:archive", "<specName>")
+```
 
-   If the move happened but the specs were NOT synced (the classic *simulated-archive* symptom), recover canonically — **never hand-copy**:
-   - a. Invoke `Skill("opsx:sync", "<specName>")` (the official sync skill) and re-verify.
-   - b. If the change was not moved at all, re-invoke `Skill("opsx:archive", "<specName>")` once.
-   - c. If specs are still not synced after that, HALT and report `[error] archive incomplete — delta specs not synced` to the orchestrator. Do NOT treat the change as done and do NOT fake it with manual file ops.
+Verify `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<specName>/` moved to its matching archive with unchanged confidence. Verify affected `${SPECRAILS_REPO_DIR:-.}/openspec/specs/<capability>/spec.md` contains synced requirements. Do not emulate with filesystem copies/moves. Official failure remains resumable.
 
-   **4 — Execution receipt.** Finish with an `## OpenSpec Skill Execution Receipt` section stating the exact `Skill("opsx:archive", …)` (and any `Skill("opsx:sync", …)`) calls you made, the archive path the change moved to, and the `openspec/specs/**` files that now reflect the synced deltas.
+Return exact Skill calls and resulting paths as the OpenSpec Skill Execution Receipt. Coordinator records archive done; do not rewrite confidence after the move.
 
 ## Write Failure Records
 
 After completing the review report, for each distinct failure category found (one record per class of failure, not per instance):
 
-1. Create a JSON file at `.claude/agent-memory/failures/<YYYY-MM-DD>-<error-type-slug>.json`.
-2. Populate all fields using the schema in `.claude/agent-memory/failures/README.md`.
+1. Create a JSON file at `<stateDir>/notes/failures/<YYYY-MM-DD>-<error-type-slug>.json`.
+2. Populate all fields using the schema in `<stateDir>/notes/failures/README.md`.
 3. Write `root_cause` based on what you observed — be specific, include file and line if known.
 4. Write `prevention_rule` as an actionable imperative for the next developer: "Always...", "Never...", "Before X, do Y".
 5. Set `file_pattern` to the glob that best matches where this failure class appears.
@@ -185,7 +180,7 @@ Do NOT write a record when:
 
 ### Idempotency
 
-Before writing a new record, scan `.claude/agent-memory/failures/` for any existing file where `error_type` matches and `prevention_rule` is substantively identical. If found, skip — do not create duplicates for the same known pattern.
+Before writing a new record, scan `<stateDir>/notes/failures/` for any existing file where `error_type` matches and `prevention_rule` is substantively identical. If found, skip — do not create duplicates for the same known pattern.
 
 ## Output Format
 
@@ -233,7 +228,7 @@ The `SECURITY_STATUS:` line is MANDATORY and machine-parsed by the orchestrator
 
 ## Explain Your Work
 
-When you make a non-trivial quality judgment, write an explanation record to `.claude/agent-memory/explanations/`.
+When you make a non-trivial quality judgment, write an explanation record to `<stateDir>/notes/explanations/`.
 
 **Write an explanation when you:**
 - Applied a lint rule fix that has non-obvious reasoning
@@ -249,7 +244,7 @@ When you make a non-trivial quality judgment, write an explanation record to `.c
 **How to write an explanation record:**
 
 Create a file at:
-  `.claude/agent-memory/explanations/YYYY-MM-DD-reviewer-<slug>.md`
+  `<stateDir>/notes/explanations/YYYY-MM-DD-reviewer-<slug>.md`
 
 Use today's date. Use a kebab-case slug describing the decision topic (max 6 words).
 
@@ -273,7 +268,7 @@ Optional sections: `## Why This Approach`, `## Alternatives Considered`, `## See
 
 ## Confidence Scoring
 
-After completing all CI checks and fixes, you MUST produce a confidence score. This is non-optional. Write the score file before reporting your results.
+During normal review, after checks/fixes and BEFORE archive, you MUST produce a confidence score. Write it before normal review returns. Archive-only continuations preserve it byte-for-byte.
 
 ### What to assess
 
@@ -295,9 +290,7 @@ Score semantics:
 
 ### How to derive the change name
 
-The change name is the kebab-case directory under `${SPECRAILS_REPO_DIR:-.}/openspec/changes/` that was active during this review. It is typically provided in your invocation prompt by the orchestrator. If not provided explicitly, find it by listing `${SPECRAILS_REPO_DIR:-.}/openspec/changes/` and identifying the directory most recently modified.
-
-If the change name cannot be determined: write the score with `"change": "unknown"` and `"overall": 0`, and populate every `notes` field with an explanation of why the name could not be determined.
+Use required specName and verify it matches the journal. Never infer identity by modification time or write an unknown score. Missing/mismatched identity blocks review.
 
 ### Output file