specrails-core 4.12.1 → 5.1.0

package/docs/user-docs/codex-vs-claude-code.md

@@ -1,151 +1,23 @@
-# Codex vs Claude Code
-
-SpecRails supports both **Anthropic Claude Code** and **OpenAI Codex** as AI
-agent runtimes. Gemini CLI and Kimi Code are also supported; this page focuses
-only on the Claude/Codex comparison.
-
----
-
-## Summary
-
-| | Claude Code | Codex |
-|--|-------------|-------|
-| **Support status** | Supported | Supported |
-| **CLI** | `claude` | `codex` |
-| **Config directory** | `.claude/` | `.codex/` |
-| **Agent instructions** | `CLAUDE.md` | `AGENTS.md` |
-| **Skills (`/specrails:*`, `/opsx:*`)** | ✅ Full support | ✅ Full support |
-| **OpenSpec workflow** | ✅ Full support | ✅ Full support |
-| **Parallel worktrees** | ✅ Native | ⚠️ Limited |
-| **Agent definitions** | Markdown frontmatter | TOML |
-| **Permissions config** | `settings.json` | `config.toml` |
-| **Agent memory** | File-based | File-based (MEMORY.md) |
-| **MCP** | ✅ First-class | ✅ First-class |
-| **Codex Cloud (web)** | ✗ | ✅ |
-
----
-
-## What works the same
-
-### Skills
-
-SpecRails Skills use `SKILL.md` format, which is shared between Codex and Claude Code. All `/specrails:*` and `/opsx:*` skills run identically on both platforms:
-
-- `/specrails:implement` — full pipeline (design → code → review → PR)
-- `/specrails:get-backlog-specs` — VPC-ranked backlog view
-- `/opsx:ff` — OpenSpec fast-forward
-- All other workflow skills
-
-### OpenSpec
-
-The full OpenSpec design-to-code workflow works on both platforms. Artifacts (proposals, designs, task lists, context bundles) are plain Markdown files — no platform dependency.
-
-### Git and GitHub
-
-Both platforms use standard `git` and the `gh` CLI. PR creation, branch management, and issue integration work identically.
-
-### Agent memory
-
-Both platforms use file-based memory. Claude Code uses `.claude/agent-memory/`. Codex uses `.codex/agent-memory/`. The format is the same — only the location changes.
-
----
-
-## What is different
-
-### Parallel execution and worktrees
-
-`/specrails:batch-implement` (multiple issues in parallel) uses git worktree isolation. On Claude Code this runs locally with full isolation. On Codex:
-
-- **Codex CLI**: Parallel execution is supported but worktree isolation is limited in the current beta. Multiple issues may share a working directory.
-- **Codex Cloud**: Native async parallelism — each task gets an isolated cloud environment. Well-suited for batch work.
-
-### Agent definitions
-
-SpecRails generates agent definitions in the format required by each platform:
-
-| Platform | Format | Location |
-|----------|--------|----------|
-| Claude Code | Markdown with YAML frontmatter | `.claude/agents/sr-*.md` |
-| Codex | TOML | `.codex/agents/sr-*.toml` |
-
-The behavior of each agent (Architect, Developer, Reviewer, etc.) is identical — only the definition format differs.
-
-### Configuration and permissions
-
-| Platform | Format | Location |
-|----------|--------|----------|
-| Claude Code | JSON | `.claude/settings.json` |
-| Codex | TOML | `.codex/config.toml` |
-
-The installer generates the correct format automatically.
-
-### Non-interactive invocation
-
-Claude Code and Codex have different non-interactive modes:
-
-```bash
-# Claude Code
-claude --print "run /specrails:implement #42"
-
-# Codex
-codex exec "run /specrails:implement #42"
-```
-
-Skills themselves are the same — only the CLI invocation differs.
-
----
-
-## Choosing a platform
-
-**Choose Claude Code if:**
-- You want the most stable and fully tested SpecRails experience
-- You need reliable parallel worktree isolation for batch feature work
-- Your team is already in the Anthropic ecosystem
-
-**Choose Codex if:**
-- Your team is in the OpenAI ecosystem and prefers Codex
-- You want to use Codex Cloud for async, web-based agent runs
-- You are evaluating SpecRails and already have Codex installed
-
-**Use both if:**
-- Different team members use different tools
-- You want to benchmark agents across platforms
-
-When several CLIs are installed, pass `--provider` to choose explicitly:
-
-```bash
-npx specrails-core@latest init --provider codex
-```
-
----
-
-## Platform detection
-
-The installer detects your platform automatically:
-
-```
-Detected CLI: codex (1.2.0)
-Generating config in .codex/
-```
-
-To override:
-
-```bash
-npx specrails-core@latest init --provider codex --root-dir .
-npx specrails-core@latest init --provider claude --root-dir .
-```
-
----
-
-## Known limitations (Codex beta)
-
-| Limitation | Status |
-|-----------|--------|
-| Parallel worktree isolation | Partial — being improved |
-| Windows support | Experimental in Codex CLI |
-| Agent memory system maturity | Less mature than Claude Code; use MEMORY.md patterns |
-| Codex CLI version stability | Frequent updates; pin your version if needed |
-
----
-
-[← Getting Started (Codex)](getting-started-codex.md) · [← Installation](installation.md) · [CLI Reference →](cli-reference.md)
+# Codex and Claude Code execution
+
+Both providers support the SpecRails design, implementation, review and archive
+workflow. Their adapters differ; native role APIs and conversation memory are not
+interchangeable.
+
+| Concern | Claude Code | Codex |
+|---|---|---|
+| Role definitions | `.claude/agents/sr-*.md` | `.codex/skills/rails/sr-*/SKILL.md` |
+| Workflow entry | `/specrails:implement` | `$implement` |
+| Multiple tickets | Aggregate change and shared journal | Routes directly to `$batch-implement` |
+| Retry | Durable pipeline journal | Same journal, direct role calls; no nested coordinator |
+| Role models | Configured role/profile model | Inherited model on full-history forks; overrides require a compatible native transport |
+| Verification | Scoped development checks and candidate-bound full gate | Same evidence contract |
+| Hosted worktrees/delivery | Owned by the host | Owned by the host |
+
+The installed `.specrails/runtime/pipeline.mjs` helper coordinates both providers.
+Its execution context identifies the frozen specs, repositories, shared backlog,
+OpenSpec artifact root and ownership. Skills must not infer those roots from cwd.
+
+A completed process is not an implementation verdict. Design confidence, checked
+tasks, semantic review, fresh verification and an authorized archive are required
+before success. See [provider pipeline contracts](provider-pipelines.md).

package/docs/user-docs/core-updates.md

@@ -0,0 +1,70 @@
+# Core installation and update consistency
+
+`specrails-core init` and `specrails-core update` use the version of the package
+that actually provides the CLI. Updating an npm package and updating a workspace
+are separate operations: run the selected CLI's `update --root-dir <repository>`
+to refresh that project's managed artifacts. `--provider` selects the additional
+provider to include; existing managed provider selections are preserved and
+reassembled, including in-repository copies and Windows copy fallbacks. Provider
+inventory is checked against installed Core artifacts; an unrelated directory
+containing only user files is not enrolled automatically.
+
+Core 5 installation is deterministic. It installs the baseline roles, commands,
+OpenSpec integration and declared local execution helper without an AI enrichment
+phase. `integration-contract.json` describes the supported lifecycle and providers.
+
+## Version and rollback rules
+
+A CLI older than the workspace marker or shared active framework refuses ordinary
+init/update. This protects an updated installation from an old global executable.
+Use the intended Core package rather than editing a version marker to bypass the
+check. Low-level explicit pointer changes are administrative rollback operations;
+they do not imply that project copies have been restored.
+
+Managed framework bytes are generated in an isolated staging directory, validated
+and stamped before publication. The content/source hashes include the compiled
+pipeline helper, so a same-version development rebuild is repaired when runtime
+bytes change. The previous framework directory is retained as
+`.previous-<version>-<id>` for recovery. A failed generation leaves the active
+framework untouched.
+
+Init/update snapshot the managed workspace surfaces and framework pointer. Failure
+restores those snapshots, including symlinks, and does not publish a successful
+workspace version or Core-owned registry version. If restoration itself fails,
+the error identifies the retained backup for recovery. Reserved custom agents
+stay in place during rollback: edits, new custom files and deliberate deletions
+made while OpenSpec runs are preserved. Profiles remain outside the snapshot
+surfaces; provider configuration is restored with the managed workspace snapshot.
+
+A separate framework lifecycle lock covers admission, version revalidation,
+snapshots, asynchronous OpenSpec provisioning and final commit or rollback. The
+same lock protects Desktop's low-level install-framework, swap-current and
+assemble commands. A concurrent operation fails immediately with a retry message
+instead of waiting while holding another lock. This prevents a failed installer
+from rolling back a framework that a second installer already reported as ready.
+A positively dead process owner can be recovered; concurrent recovery attempts
+are serialized, and an unidentified or live owner is never taken over.
+
+`update --dry-run` reports the intended change without allocating or rewriting
+registry entries. Partial `--only rules` or `--only agents` refreshes do not claim
+that the entire framework has moved to the executing CLI's version. The returned
+`installedVersion` describes the actual workspace marker.
+
+The low-level `install-framework --version` command requires the requested label
+to match the package version supplying its bytes. `assemble --version` requires
+the matching complete active framework before recording that version in a project.
+
+## Desktop
+
+Desktop keeps the selected package and its dependencies after an update. Its
+Settings page reports runtime, framework, bundled and latest-known versions
+separately. Partial workspace migration remains pending across restart and can be
+retried using the retained package offline. A CLI installed outside Desktop can
+also be discovered through PATH; an explicit `SPECRAILS_CORE_BIN` takes precedence.
+
+Changes in this branch require a Core package build and distribution before an
+already installed Desktop can consume them. The source changes alone do not
+upgrade any user installation or publish a new package.
+
+See [Provider pipeline contracts](provider-pipelines.md) for the resumable
+implementation journal and verification behavior.

package/docs/user-docs/provider-pipelines.md

@@ -0,0 +1,53 @@
+# Provider pipeline contracts
+
+Core installs a local, self-contained Node helper at
+`.specrails/runtime/pipeline.mjs`. It uses no global Core lookup or network download.
+The shared contract is embedded in the installed Claude, Codex, Gemini and Kimi workflows.
+`SPECRAILS_PIPELINE_RUNTIME` can explicitly identify that helper for a child process.
+
+An absolute `SPECRAILS_EXECUTION_CONTEXT` JSON file supplies immutable specs, selected
+repositories, OpenSpec artifactRoot, backlogRoot (the workspace containing
+`.specrails/local-tickets.json`), optional backlogPath, and host/core ownership.
+Batch uses one aggregate OpenSpec change and journal; task groups retain ticket and
+repository identity. Final verification and semantic review cover the whole batch.
+
+Standalone invocation admits ticket IDs with `init --tickets "17,18"` or a structured
+`--scope-request` for free-form specs. Reuse the generated context on retry; explicit
+host context always takes precedence. Core-owned delivery requires explicit ownership.
+
+Use the helper's init/status/phase/verify/archive-check operations. Status identifies
+the first invalid phase. Retry reuses valid earlier work; blocked remains retriable.
+Explicit role handoffs contain frozen criteria and exact paths, not a promise that
+another provider conversation retained memory. Archive-only execution preserves the
+reviewed confidence file; the gate binds its exact bytes and the candidate.
+
+## Gemini
+
+OpenSpec is installed with an isolated complete workflow profile, then Gemini skills
+are placed in the actual execution workspace. Updates preserve custom skill folders.
+The adapter requires invoke_agent and role activate_skill availability. Turn limits
+are capability-dependent: older loaders reject optional metadata. By default Core
+omits it and uses progress-bound continuation handoffs. After verifying loader
+support, an installer may set SPECRAILS_GEMINI_AGENT_LIMITS=supported and
+SPECRAILS_GEMINI_MAX_TURNS (1–200, default 60). This does not confer native session
+continuity; every reinvocation still receives an explicit checkpoint.
+
+## Kimi
+
+The managed runner preserves the absolute execution context, shared backlog path,
+helper path and selected repository access across private role working directories.
+SPECRAILS_BACKLOG_PATH is the exact ticket-file path; SPECRAILS_BACKLOG_ROOT is its
+logical workspace. Host-owned contexts reject sibling worktree requests before any
+role process starts. Role models remain exact profile values. Standalone managed
+worktree manifests and their guarded merge/cleanup mechanism remain available.
+
+## Validation limits
+
+Local regression fixtures install the real provider artifacts and run the real
+helper against temporary repositories, including failed gates, review retry,
+archive authorization and unchanged frozen scope. Kimi process fixtures additionally
+exercise private cwd, shared-backlog access and host worktree rejection. They do not
+make paid model calls or claim identical behavior across every native CLI release.
+
+See [Core installation and update consistency](core-updates.md) for version
+selection, rollback and Desktop integration.

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": "4.12.1",
+  "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/schemas/profile.v1.json

@@ -43,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",