specrails-core 5.0.0 → 5.1.0

package/docs/ci-cd.md

@@ -0,0 +1,57 @@
+# Core CI and publishing
+
+Core's release workflow publishes the **same npm tarball that passed CI**. It does not rebuild a replacement package inside the publish step. These workflows do not run provider models or publish from pull requests.
+
+## Quality gates
+
+`CI` runs for branch pushes, pull requests to `main`, and manual dispatches. It has read-only repository permissions, cancels superseded runs on the same branch/PR, and has bounded job timeouts.
+
+- Typecheck/build on the exact supported Node minimum, **20.19.0**.
+- Full Vitest and release-guard tests on **Linux, macOS and Windows**, with **Node 20.19.0, 22 and 24**.
+- Coverage on Node 24 with the existing configured thresholds (not lowered).
+- A checksum-verified actionlint binary validates workflow syntax, expressions and action inputs (shellcheck is not included).
+- A checksum-verified Gitleaks binary scans Git history with redacted output.
+- On Node 24 on each OS, `scripts/verify-package.mjs` packs the built package, checks its file inventory, installs the tarball into an isolated temporary consumer with lifecycle scripts disabled, and executes both published CLI entry points. It materializes/assembles all four providers and runs the assembled pipeline helper against four frozen fixture scopes. No global install, real project registry, provider login or model call is used.
+
+The Linux package smoke uploads `core-package` for 14 days, containing the `.tgz` and `release-manifest.json` (package/version, Git SHA and SHA-512 integrity). The manifest is only written after the consumer smoke succeeds.
+
+Local checks, after installing dependencies:
+
+```sh
+npm run ci                 # typecheck, guard regressions, coverage, packaged-consumer smoke
+npm run test:scripts       # hermetic release regressions only
+npm run check:package      # build and consumer smoke; prints its temporary artifact directory
+# To choose where the verified tarball is kept:
+node scripts/verify-package.mjs /absolute/path/to/temporary-package-output
+```
+
+The package check may download the tarball's production dependencies from npm. Its generated output directory should be outside the checkout. Release-guard unit tests are hermetic and do not access npm or GitHub.
+
+## Automatic release
+
+1. A push to `main` starts `Release`. It waits for a successful `CI` **push run on the exact same main commit**, including the entire matrix, coverage, secret scan and package check. A success on an older commit or a PR does not qualify. Failed/cancelled CI fails the gate; waiting is bounded to 30 minutes.
+2. An additional current-main check skips obsolete pushes before changing release metadata. Release Please opens/updates the release PR, or creates the release/tag after that PR was merged. It has only the repository/PR write permissions it needs. The CI jobs do not receive those permissions.
+3. Before publishing, the workflow verifies that the stable `vX.Y.Z` tag points at the tested commit, that this commit is in `origin/main`, and that the tag, package.json, both root lockfile version fields and Release Please manifest agree. If main advanced while Release Please was working and it tagged a different SHA, publication fails closed.
+4. It downloads the tarball from that successful CI run and verifies its identity and integrity. It refuses to move npm `latest` backwards. An existing version is accepted only when its published integrity matches the verified artifact exactly.
+5. It publishes the `.tgz` with `--ignore-scripts --provenance --access public`, then sends downstream notifications. Only the publication job has `id-token: write`; the npm token is exposed only to the final publish step.
+
+All automatic and manual releases share one non-cancelling concurrency group, so simultaneous runs cannot race the stable dist-tag.
+
+## Credentials and notifications
+
+- `RELEASE_PAT` (recommended): a repository-scoped token with permission to maintain release branches, PRs and releases (Contents and Pull requests write). Release Please prefers this secret, allowing its generated PR events to start the normal required CI. A GitHub App installation token with equivalent permissions is also suitable if the workflow is configured to mint one; this workflow does not create an App or credentials.
+- `GITHUB_TOKEN` fallback: retained so existing installations can maintain release metadata without a new secret. GitHub currently creates runs for token-generated PR `opened`, `synchronize` and `reopened` events **in an approval-required state**. The workflow warns when using this fallback: a maintainer with write access must select **Approve workflows to run** on the release PR after bot updates. Configure `RELEASE_PAT` for automatic CI without that approval prompt; do not bypass required checks or branch protection. Other token-generated events, including tag pushes, remain suppressed. Repository settings must permit Actions to create PRs. Publication is in this same workflow and does not depend on a new tag-triggered run. See [GitHub's current event-triggering rules](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow#triggering-a-workflow-from-a-workflow). [Release Please also recommends a separate CI-capable credential](https://github.com/googleapis/release-please-action#other-actions-on-release-please-prs).
+- `NPM_TOKEN`: existing token authentication remains supported; use a narrowly scoped token that can publish `specrails-core`. Do not remove it until npm trusted publishing has been configured for this repository and **`release.yml`**. Publishing runs on Node 24 and enforces npm >=11.5.1. The workflow requests OIDC and provenance but does not change npm account settings. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+- `CROSS_REPO_TOKEN`: must permit repository dispatch to `fjpulidop/specrails-desktop` and `fjpulidop/specrails-web`. It is available only to the notification job.
+
+Both consumers receive `repository_dispatch` event `specrails-core-released`. Desktop receives `{"core_version":"X.Y.Z"}` and validates the exact released integration contract; the website retains its historical `{"core_version":"vX.Y.Z"}` convention. Notification failure leaves a visible failed workflow, even when npm publication already succeeded.
+
+## Recover a failed publication or notification
+
+Use **Actions → Release → Run workflow**, from the trusted main workflow, and provide an **existing** stable tag (`vX.Y.Z`). This path does not create a tag or bump versions. It checks main ancestry/version agreement, runs typecheck, release-guard tests and the full suite with coverage, then rebuilds, packs and consumer-tests that exact tag on Linux/Node 24 in a read-only preparation job. A separate publication job downloads those verified bytes; dependency installs and tests never have OIDC or npm credentials.
+
+Manual recovery deliberately works without an old CI artifact. It does not rerun the full historical OS/Node matrix; normal automatic releases require that matrix. Tags predating these validation scripts cannot use this recovery path. If an identical version is already on npm, publication is skipped and both notifications are retried. Different bytes at that version, an older version than `latest`, missing tags or incompatible versions stop the run. npm versions are immutable; do not force around a mismatch.
+
+For a failed initial CI gate, first repair/rerun CI for that commit, then rerun Release. Expired artifacts or a tag created at another main SHA can be recovered with the existing-tag manual path. If downstream notification failed, rerunning only its job is also sufficient and does not touch npm.
+
+The workflows and hermetic fixtures validate the release machinery locally; successful native Windows/macOS CI, token permissions, OIDC configuration and a real publication can only be confirmed by their respective hosted runs.

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.