specrails-core 5.5.1 → 6.0.0

package/docs/agents.md

@@ -1,315 +0,0 @@
-# Agents
-
-SpecRails ships with **14 specialized agents**. Each has a clear role, a dedicated AI model, and knows exactly when to stay in its lane.
-
-## Why specialized agents?
-
-A single "do everything" prompt gets mediocre results. By splitting responsibilities, each agent:
-
-- Has a **focused system prompt** optimized for its task
-- Uses the **right model** for the job (Opus for creative work, Sonnet for implementation, Haiku for analysis)
-- Maintains **its own memory** across sessions
-- Loads only the **relevant conventions** for its scope
-
-The result: better quality at every stage, with clear accountability.
-
-## Agent roster
-
-### Product Manager
-
-| | |
-|-|-|
-| **Color** | Blue |
-| **Model** | Opus (creative reasoning) |
-| **Trigger** | `/opsx:explore`, `/specrails:auto-propose-backlog-specs` |
-| **Role** | Feature ideation and product strategy |
-
-The Product Manager is the **starting point** of the pipeline. It researches your competitive landscape (via web search), evaluates ideas against your user personas using the VPC framework, and produces prioritized feature recommendations.
-
-**Why Opus?** Product thinking requires creative reasoning and nuanced judgment — weighing user needs, market trends, and technical feasibility simultaneously. Opus excels at this kind of open-ended analysis.
-
-**What it produces:**
-- Feature ideas organized by area
-- VPC scores per persona (0–5)
-- Effort estimates
-- Competitive inspiration sources
-
----
-
-### Product Analyst
-
-| | |
-|-|-|
-| **Color** | Cyan |
-| **Model** | Haiku (fast, read-only) |
-| **Trigger** | `/specrails:get-backlog-specs` |
-| **Role** | Backlog analysis and reporting |
-
-The Product Analyst is a **read-only** agent. It reads your backlog, specs, and archived changes to produce structured reports. It never writes code or makes decisions — it just gives you the data.
-
-**Why Haiku?** Analysis tasks need speed, not deep reasoning. Haiku is fast and cheap, perfect for reading and summarizing large amounts of data.
-
-**What it produces:**
-- Prioritized backlog tables grouped by area
-- Top 3 recommendations ranked by VPC score / effort ratio
-- Spec gap analysis (what's specified vs. what's implemented)
-
----
-
-### Architect
-
-| | |
-|-|-|
-| **Color** | Green |
-| **Model** | Sonnet |
-| **Trigger** | `/opsx:ff`, `/opsx:continue`, `/specrails:implement` (Phase 3a) |
-| **Role** | System design and task breakdown |
-
-The Architect translates **what to build** into **how to build it**. It reads the relevant specs, analyzes the codebase, and produces a detailed implementation design with ordered tasks.
-
-**Why it matters:** Without architecture, developers write code that works locally but breaks the system. The Architect considers cross-cutting concerns, API contracts, data flows, and migration needs before a single line of code is written.
-
-**What it produces:**
-- Change summary and impact analysis
-- Implementation design (technical approach per layer)
-- Ordered task breakdown with dependencies
-- Risks and considerations
-- Backwards compatibility impact report (Phase 6 auto-check against API surface)
-
-The Architect also records decision rationale in `.claude/agent-memory/explanations/` — queryable later with `/specrails:why`.
-
----
-
-### Developer
-
-| | |
-|-|-|
-| **Color** | Purple |
-| **Model** | Sonnet |
-| **Trigger** | `/opsx:apply`, `/specrails:implement` (Phase 3b) |
-| **Role** | Full-stack implementation |
-
-The Developer is the **workhorse**. It reads the Architect's design, loads the relevant layer conventions, and writes production-quality code across all layers. It follows a strict process: understand, plan, implement, verify.
-
-Before starting implementation, the Developer reads any **failure records** from `.claude/agent-memory/failures/` that match the current task — using past mistakes as guardrails. After implementation, it records decision rationale in `.claude/agent-memory/explanations/`.
-
-**What it produces:**
-- Production code across all affected layers
-- Follows existing patterns and conventions
-- Runs CI-equivalent checks before declaring "done"
-
----
-
-### Backend Developer & Frontend Developer
-
-| | |
-|-|-|
-| **Colors** | Purple (backend), Blue (frontend) |
-| **Model** | Sonnet |
-| **Trigger** | `/specrails:implement` with parallel pipeline |
-| **Role** | Layer-specific implementation |
-
-For large full-stack features, SpecRails can split work between **Backend Developer** and **Frontend Developer** running in **parallel git worktrees**. Each has a lighter prompt focused on their stack and runs only the relevant CI checks.
-
-**Why split?** A backend API and a React component have nothing in common. Splitting them lets each developer focus on their domain, and the work happens concurrently instead of sequentially.
-
----
-
-### Test Writer
-
-| | |
-|-|-|
-| **Color** | Cyan |
-| **Model** | Sonnet |
-| **Trigger** | `/specrails:implement` (Phase 3c) |
-| **Role** | Automated test generation |
-
-After the Developer finishes, the Test Writer generates comprehensive tests for the new code. It auto-detects your test framework, reads 3 existing tests to learn your patterns, and targets >80% coverage of new code.
-
-**Why a separate agent?** Developers writing their own tests tend to test what they built, not what could break. A separate Test Writer approaches the code fresh, testing edge cases and failure modes the developer might miss.
-
-**What it produces:**
-- Test files following your project's conventions
-- Coverage targeting >80% of new code
-- Never modifies implementation files
-
-**Supported frameworks:** Jest, Vitest, Mocha, pytest, RSpec, Go test, cargo test, PHPUnit
-
----
-
-### Doc Sync
-
-| | |
-|-|-|
-| **Color** | Yellow |
-| **Model** | Sonnet |
-| **Trigger** | `/specrails:implement` (Phase 3d) |
-| **Role** | Keep documentation in sync with code |
-
-Doc Sync detects and updates your project's documentation after implementation:
-
-- **Changelog** — adds entries in Keep-a-Changelog format
-- **README** — updates feature lists, usage sections, API references
-- **API docs** — updates docs in `docs/` or `docs/api/`
-
-**Why automate docs?** Because nobody updates them manually. Docs drift from code within days. By running Doc Sync in the pipeline, documentation stays accurate by default.
-
----
-
-### Frontend Reviewer
-
-| | |
-|-|-|
-| **Color** | Cyan |
-| **Model** | Sonnet |
-| **Trigger** | `/specrails:implement` (Phase 4b, parallel) |
-| **Role** | Frontend-specific quality audit |
-
-The Frontend Reviewer runs in parallel with the Backend Reviewer during Phase 4b, specializing in client-side concerns that a generalist reviewer might miss.
-
-**What it scans for:**
-- **Bundle size** — detects imports that bloat the client bundle
-- **WCAG accessibility** — missing ARIA labels, keyboard navigation, contrast issues
-- **Render performance** — unnecessary re-renders, missing memoization, large lists without virtualization
-
----
-
-### Backend Reviewer
-
-| | |
-|-|-|
-| **Color** | Cyan |
-| **Model** | Sonnet |
-| **Trigger** | `/specrails:implement` (Phase 4b, parallel) |
-| **Role** | Backend-specific quality audit |
-
-The Backend Reviewer runs in parallel with the Frontend Reviewer during Phase 4b, specializing in server-side concerns.
-
-**What it scans for:**
-- **N+1 queries** — database calls inside loops without eager loading
-- **Connection pools** — missing pool configuration or pool exhaustion risks
-- **Pagination** — unbounded list queries that could return millions of rows
-- **Missing indexes** — foreign keys and filter columns without index coverage
-
----
-
-### Security Reviewer
-
-| | |
-|-|-|
-| **Color** | Orange |
-| **Model** | Sonnet |
-| **Trigger** | `/specrails:implement` (Phase 4) |
-| **Role** | Security audit |
-
-The Security Reviewer scans new code for:
-
-- **Secrets** — AWS keys, API tokens, database URLs, private keys, hardcoded passwords
-- **OWASP vulnerabilities** — SQL injection, XSS, insecure deserialization, command injection, path traversal
-
-Findings are graded by severity (Critical → High → Medium → Info). Critical findings **block the pipeline**.
-
-**Important:** This agent scans and reports only — it never fixes code. Fixes are the Developer's responsibility, triggered by the Reviewer if issues are found.
-
-You can suppress known false positives via `.claude/security-exemptions.yaml`.
-
----
-
-### Reviewer
-
-| | |
-|-|-|
-| **Color** | Red |
-| **Model** | Sonnet |
-| **Trigger** | `/specrails:implement` (Phase 4b), after all developers complete |
-| **Role** | Final quality gate |
-
-The Reviewer is the **last agent before ship**. It:
-
-1. Runs **every CI check** in the exact order your CI pipeline runs them
-2. **Fixes failures** autonomously (up to 3 retry cycles per issue)
-3. Reviews **code quality**, test quality, and consistency
-4. Produces a **confidence score** (0–100%) across 5 quality aspects
-5. Writes structured **failure records** to `.claude/agent-memory/failures/` for any non-trivial issues found
-6. Records decision rationale in `.claude/agent-memory/explanations/`
-
-**Why not just run CI?** Because the Reviewer can _fix_ what it finds. A lint error, a missing import, a flaky test setup — the Reviewer patches them and re-runs. By the time it creates the PR, CI will pass.
-
-**Confidence scoring:** After each review, the Reviewer outputs a score (0–100%) across five aspects: correctness, test coverage, security, performance, and maintainability. Scores below the configured threshold trigger a warning or block the pipeline entirely. See [Confidence thresholds](customization.md#confidence-thresholds) to configure this behavior.
-
-**What it produces:**
-- CI check results table (pass/fail per check)
-- List of issues found and fixed
-- Files modified during fixes
-- Confidence score report (Phase 4b-conf)
-
----
-
-### Merge Resolver
-
-| | |
-|-|-|
-| **Color** | Yellow |
-| **Model** | Sonnet |
-| **Trigger** | `/specrails:merge-resolve`, `/specrails:implement` (Phase 4a, after worktree merge) |
-| **Role** | AI-powered merge conflict resolution |
-
-When a multi-feature pipeline merges worktrees and produces conflict markers, the Merge Resolver analyzes each conflict block using the OpenSpec context bundles from both features. It applies resolutions where confidence is high enough and leaves clean markers for the conflicts it cannot safely resolve.
-
-**Configuration (in `.claude/agents/sr-merge-resolver.md`):**
-- `tone`: `terse` (default) or `verbose`
-- `risk_tolerance`: `conservative` (default) or `aggressive`
-- `confidence_threshold`: 0–100, default `70`
-
-**What it produces:**
-- Resolved conflict blocks written in place
-- Structured resolution report (file, block, confidence, resolution or left-as-marker)
-
----
-
-### Performance Reviewer
-
-| | |
-|-|-|
-| **Color** | Yellow |
-| **Model** | Sonnet |
-| **Trigger** | `/specrails:implement` (Phase 4, after Security Reviewer) |
-| **Role** | Performance regression detection |
-
-The Performance Reviewer benchmarks modified code paths after implementation, compares metrics against configured thresholds, and outputs a structured report. It never fixes code — findings above the threshold trigger the Developer to address them before the pipeline continues.
-
-**Configuration:** Create `.specrails/perf-thresholds.yml` to set custom thresholds per metric. The agent falls back to built-in defaults if the file is missing.
-
-**What it produces:**
-- Execution time, memory usage, and throughput metrics for modified paths
-- Pass/fail report against configured thresholds
-- `PERF_STATUS` result consumed by the pipeline orchestrator
-
----
-
-## Agent memory
-
-Every agent stores observations in `.claude/agent-memory/<agent>/MEMORY.md`. This memory persists across sessions, so agents get smarter over time:
-
-```
-.claude/agent-memory/
-├── sr-architect/MEMORY.md
-├── sr-developer/MEMORY.md
-├── sr-reviewer/MEMORY.md
-├── failures/           # Structured failure records (written by Reviewer)
-├── explanations/       # Decision rationale (written by Architect, Developer, Reviewer)
-└── ...
-```
-
-Memory is automatic — you don't need to manage it. Agents read relevant memories at the start of each task and write new observations as they work. Use `/specrails:why` to search the explanations directory in plain language.
-
-## What's next?
-
-See how agents work together in the pipeline:
-
-- [Workflows & Commands](workflows.md) — the commands that orchestrate agent collaboration
-- [Customization](customization.md) — tweak agent prompts, add new agents
-
----
-
-[← Core Concepts](concepts.md) · [Workflows & Commands →](workflows.md)

package/docs/changelog.md

@@ -1,168 +0,0 @@
-# Changelog
-
-All notable changes to SpecRails are listed here, newest first.
-
----
-
-## [Unreleased]
-
-### Breaking changes
-
-- **`/specrails:setup` renamed to `/specrails:enrich`** — The setup wizard is now invoked as `/specrails:enrich`. The `--lite` flag is now `--quick` (both are accepted during the transition period). Update any scripts or documentation that reference `/specrails:setup`.
-
-### New features
-
-- **TUI installer** — `npx specrails-core@latest init` now launches an interactive terminal UI before copying files. Select which agents to install and choose a model preset (balanced/budget/max). Results are saved to `.specrails/install-config.yaml`.
-- **`/specrails:enrich --from-config`** — Non-interactive enrichment mode. Reads `.specrails/install-config.yaml` (written by the TUI installer) and runs the full AI analysis without prompts.
-- **`/specrails:enrich --quick`** — Quick setup mode: three questions, sensible defaults, done in under a minute.
-- **`npx specrails-core enrich`** — New CLI subcommand that runs `/specrails:enrich` via Claude CLI directly from the terminal.
-- **`install-config.yaml` schema** — Declarative configuration file for reproducible installations. Supports agent selection, model presets, and per-agent model overrides.
-- **`integration-contract.json`** — Hub integration contract describing provider commands, tier configurations, checkpoint names, and model presets for hub integrations.
-
----
-
-## [1.7.0](https://github.com/fjpulidop/specrails-core/compare/v1.6.1...v1.7.0) — 2026-03-20
-
-### New commands
-
-- **`/specrails:merge-conflict`** — Smart merge conflict resolver. Analyzes conflict context, understands intent of both sides, and proposes the correct resolution with an explanation.
-- **`/specrails:refactor-recommender` (enhanced)** — Now includes VPC context-aware scoring: debt items are ranked against persona Jobs/Pains/Gains for product-aligned prioritization.
-
-### Agents
-
-- **Performance Regression Detector** — New agent with CI workflow integration. Automatically detects performance regressions across runs and annotates PRs with regression reports.
-
-### Pipeline Monitor
-
-- **Zombie job detection and auto-termination** — The web-manager now detects stalled jobs and terminates them automatically to keep the queue healthy.
-
----
-
-## [1.6.1](https://github.com/fjpulidop/specrails-core/compare/v1.6.0...v1.6.1) — 2026-03-20
-
-### Bug fixes
-
-- **Docs cleanup** — Removed DeckDex-contaminated documentation files that had been incorrectly included in the package.
-
----
-
-## [1.6.0](https://github.com/fjpulidop/specrails-core/compare/v1.5.0...v1.6.0) — 2026-03-20
-
-### Improvements
-
-- **`/specrails:setup --update` template checksums** — The update command now checks command template checksums before overwriting, so manual customizations are detected and preserved rather than silently clobbered.
-
----
-
-## [1.5.0](https://github.com/fjpulidop/specrails-core/compare/v1.4.0...v1.5.0) — 2026-03-20
-
-### New commands
-
-- **`/specrails:opsx-diff`** — Change diff visualizer. Shows a structured, human-readable diff of what changed between two points in time across agents, commands, and templates.
-- **`/specrails:telemetry`** — Agent telemetry and cost tracking. Reports per-agent token usage, run counts, and cost estimates with trend analysis.
-
-### Agents
-
-- **OSS Maintainer persona Kai** — Formalized the OSS Maintainer persona. Kai helps you think through open-source positioning, community management, and contributor onboarding.
-
----
-
-## [1.4.0](https://github.com/fjpulidop/specrails-core/compare/v1.3.0...v1.4.0) — 2026-03-20
-
-### New commands
-
-- **`/specrails:vpc-drift`** — Detects when your VPC personas have drifted from what your product actually delivers. Compares persona Jobs/Pains/Gains against the backlog and agent memory; produces per-persona alignment scores and concrete update recommendations.
-- **`/specrails:memory-inspect`** — Inspect and manage agent memory directories. Shows per-agent stats, recent entries, and stale file detection with optional pruning.
-
----
-
-## [1.3.0](https://github.com/fjpulidop/specrails-core/compare/v1.2.0...v1.3.0) — 2026-03-20
-
-### New commands
-
-- **`/specrails:retry`** — Smart failure recovery. Resumes a failed `/specrails:implement` pipeline from the last successful phase without restarting from scratch. Reads saved pipeline state to identify what completed, then re-executes only the remaining phases.
-
-### Agents
-
-- **Agent personality customization** — Edit agent prompts after installation to tune tone, priorities, and decision-making for your team's style. See [Customization](customization.md).
-
----
-
-## [1.2.0](https://github.com/fjpulidop/specrails-core/compare/v1.1.0...v1.2.0) — 2026-03-20
-
-### Improvements
-
-- **`/specrails:health-check` extended with static code analysis** — Now includes complexity metrics, dead code detection, and architectural pattern analysis in addition to test coverage and dependency health.
-
----
-
-## [1.1.0](https://github.com/fjpulidop/specrails-core/compare/v1.0.1...v1.1.0) — 2026-03-20
-
-### Agents
-
-- **Doc Sync agent enhanced** — Added drift detection with severity levels. The agent now classifies documentation drift as `critical`, `major`, or `minor` and prioritizes accordingly.
-- **Test Writer wired into `/specrails:setup`** — New installations now include the Test Writer agent by default.
-- **Security Reviewer wired into `/specrails:setup`** — New installations now include the Security Reviewer agent by default.
-
-### Onboarding
-
-- **Onboarding v1 (RFC-001)** — Formalized the setup wizard flow and agent installation sequence.
-
----
-
-## [1.0.1](https://github.com/fjpulidop/specrails-core/compare/v1.0.0...v1.0.1) — 2026-03-19
-
-### Bug fixes
-
-- Updated README and CLAUDE.md for the `specrails-core` rename.
-
----
-
-## [1.0.0](https://github.com/fjpulidop/specrails-core/releases/tag/v1.0.0) — 2026-03-19
-
-Initial stable release.
-
-### ⚠ Breaking changes
-
-All commands renamed from `/<name>` to `/specrails:<name>`. All agent files renamed from `<name>.md` to `sr-<name>.md`. Existing installations are auto-migrated by `update.sh`.
-
-### What shipped in 1.0
-
-**12 specialized agents**
-- Product Manager, Architect, Developer, Backend Developer, Frontend Developer
-- Test Writer, Reviewer, Backend Reviewer, Frontend Reviewer
-- Security Reviewer, Doc Sync, Product Analyst
-
-**11 commands**
-- `/specrails:implement` — full 8-phase pipeline (architecture → code → tests → docs → review → PR)
-- `/specrails:batch-implement` — parallel multi-feature orchestrator using git worktrees
-- `/specrails:health-check` — codebase quality dashboard with regression detection
-- `/specrails:compat-check` — backwards compatibility analyzer and migration guide generator
-- `/specrails:get-backlog-specs` — VPC-scored backlog view with safe implementation ordering
-- `/specrails:auto-propose-backlog-specs` — AI-powered product discovery via personas
-- `/specrails:refactor-recommender` — tech debt scanner ranked by impact/effort
-- `/specrails:why` — semantic search over agent decision records
-- `/specrails:retry` — smart failure recovery (added in 1.3)
-- `/specrails:vpc-drift` — persona drift detection (added in 1.4)
-- `/specrails:propose-spec` — structured feature proposal generator
-
-**Pipeline Monitor (web-manager)**
-- Real-time job queue dashboard
-- Live log streaming via WebSocket
-- Analytics: daily throughput, status breakdown, job history
-- Chat panel for in-context help
-
-**Update system**
-- Content-aware selective updates — only changed files are overwritten
-- Customizations (agent prompts, personas, layer rules) are preserved across updates
-- `update.sh` auto-migrates command namespace changes
-
-**Distribution**
-- `npx specrails-core@latest init`
-- `curl | bash` installer
-- `--root-dir` flag for monorepo support
-- `--yes` flag for non-interactive CI installs
-
----
-
-[← Updating](updating.md)

package/docs/ci-cd.md

@@ -1,60 +0,0 @@
-# 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 pushes to `main`, pull requests to `main`, and manual dispatches. Feature branches are checked through their PR, avoiding two complete matrix runs for every update. The post-merge main push still runs the entire release gate. 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**.
-- Windows distributes the two slow runtime integration suites across three jobs by collected test locations; a fourth job runs every other test file. Parameterized cases stay together. The partition runner checks its selected inventory against Vitest before running, failing if any assigned test is missing or extra. Linux/macOS and coverage run the complete suite without partitioning.
-- 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 and CI partition regressions
-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
-```
-
-To reproduce a Windows test partition locally, run `node scripts/ci-tests.mjs runtime-1` (or `runtime-2`, `runtime-3`, `general`). Add `--list-only` to a runtime partition to verify its inventory without executing tests.
-
-The package check reuses the npm dependency cache (including the cache populated by `npm ci` and setup-node) with `--prefer-offline`; it may download missing production dependencies from npm. The temporary consumer, user configuration and credential isolation remain in place. 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.