specrails-core 5.6.0 → 6.0.0

package/docs/user-docs/installation.md

@@ -1,237 +0,0 @@
-# Installation
-
-Install SpecRails into any git repository in two steps: install, then run the
-provider-native enrich workflow. The scaffold supports Claude Code, Codex CLI,
-Gemini CLI, and Kimi Code.
-
-> **Looking for the comprehensive reference?** See [Installation & Setup](../installation.md) for full wizard phase details and advanced configuration.
-
-## Requirements
-
-### Plugin method (recommended)
-
-| Tool | Version | Notes |
-|------|---------|-------|
-| **Claude Code** | Latest | [install guide](https://docs.anthropic.com/en/docs/claude-code) |
-| **Git** | Any | Your project must be a git repository |
-
-No Node.js required.
-
-### Scaffold method (npx / any provider)
-
-| Tool | Version | Notes |
-|------|---------|-------|
-| **Node.js** | 20.19.0+ | Required for the installer and pinned OpenSpec 1.4.1 CLI |
-| **Supported AI CLI** | Latest compatible version | Claude Code, Codex, Gemini, or Kimi 0.27.0+ |
-| **Git** | Any | Your project must be a git repository |
-
-Optional but recommended (both methods):
-
-| Tool | Why |
-|------|-----|
-| **GitHub CLI** (`gh`) | Automatic PR creation and Issue integration |
-
-## Install
-
-### Plugin method (Claude Code)
-
-```bash
-claude plugin install sr
-```
-
-No cloning, no npm, nothing else. The plugin is now ready in all your Claude Code sessions.
-
-To update later: `claude plugin update sr`
-
-### Scaffold method (Claude, Codex, Gemini, or Kimi)
-
-Run from inside your project directory:
-
-```bash
-cd your-project
-npx specrails-core@latest init --root-dir .
-```
-
-The installer copies provider-native artifacts into `.claude/`, `.codex/`,
-`.gemini/`, or `.kimi-code/`. It does not modify your application source.
-
-#### Flags
-
-| Flag | Effect |
-|------|--------|
-| `--root-dir <path>` | Target directory (default: current directory) |
-| `--yes` / `-y` | Skip confirmation prompts |
-| `--provider <claude\|codex\|gemini\|kimi>` | Force a specific AI CLI (default: auto-detect) |
-
-#### What gets installed (scaffold method)
-
-**Claude Code:**
-
-```
-your-project/
-└── .claude/
-    ├── commands/specrails/enrich.md     # The /specrails:enrich wizard
-    ├── skills/                   # Workflow skills (/specrails:*, /opsx:*)
-    ├── agents/                   # Agent definitions
-    ├── rules/                    # Per-layer coding conventions
-    └── settings.json             # Permissions
-```
-
-**Kimi Code:**
-
-```text
-your-project/
-└── .kimi-code/
-    ├── AGENTS.md
-    ├── mcp.json
-    ├── personas/
-    ├── rules/
-    ├── specrails/
-    │   ├── run-skill.mjs
-    │   └── vendor/js-yaml/       # Managed parser + MIT license/provenance
-    └── skills/
-        ├── specrails-*/SKILL.md
-        ├── openspec-*/SKILL.md
-        └── sr-*/SKILL.md
-```
-
-Kimi discovers only direct children of `.kimi-code/skills`, so workflows,
-OpenSpec skills, managed `sr-*` roles, and user `custom-*` roles all live at
-that level rather than inside a `rails/` grouping directory. Non-skill persona
-data and the managed headless runner live outside the scanner root.
-
-See [Getting Started with Kimi](getting-started-kimi.md) for installation,
-login, models, effort, sessions, and headless execution details.
-
-**Codex (beta):**
-
-```text
-your-project/
-├── AGENTS.md                     # SpecRails agent instructions for Codex
-└── .codex/
-    ├── skills/                   # Workflow skills (/specrails:*, /opsx:*)
-    ├── agents/                   # Agent definitions (TOML)
-    ├── rules/                    # Per-layer coding conventions
-    └── config.toml               # Permissions
-```
-
-The installer also writes `.specrails/specrails-version` and `.specrails/specrails-manifest.json` to track the installed version.
-
-## Configure with /specrails:enrich
-
-After either installation method, open your AI CLI in your project and run:
-
-```bash
-claude    # Claude Code
-# or
-codex     # Codex
-# or
-gemini    # Gemini CLI
-# or
-kimi      # Kimi Code
-```
-
-Claude and Gemini:
-
-```
-/specrails:enrich
-```
-
-Kimi:
-
-```text
-/skill:specrails-enrich
-```
-
-By default, `/specrails:enrich` runs the full 5-phase wizard:
-
-| Phase | What happens |
-|-------|-------------|
-| **1. Analyze** | Detects your tech stack, architecture layers, and CI commands |
-| **2. Personas** | Researches your domain and generates VPC user profiles |
-| **3. Configure** | Asks about your backlog provider, git workflow, and agent selection |
-| **4. Generate** | Generates project data files (`.specrails/` or `.claude/`) with your context |
-| **5. Cleanup** | Removes setup scaffolding, leaving only your tailored workflow |
-
-**In a hurry?** Run `/specrails:enrich --quick` instead — three questions, sensible defaults, done in under a minute.
-
-**Already ran the TUI installer?** If you used `npx specrails-core@latest init` and completed the TUI agent selection, run `/specrails:enrich --from-config` to apply your saved configuration without re-answering the prompts.
-
-## Verify
-
-Check that everything installed correctly:
-
-```bash
-# Plugin method: check project data was generated
-ls .specrails/
-
-# Scaffold method: list generated agents
-ls .claude/agents/
-
-# Scaffold method: check for unresolved placeholders (should return nothing)
-grep -r '{{[A-Z_]*}}' .claude/agents/ .claude/commands/ .claude/rules/
-
-# Scaffold method: check the installed version
-cat .specrails/specrails-version
-```
-
-## Troubleshooting
-
-### "This appears to be the specrails source repository"
-
-You ran the installer from inside the SpecRails source repo. Run it from your target project instead:
-
-```bash
-cd /path/to/your-project
-npx specrails-core@latest init --root-dir .
-```
-
-### Existing `.claude/` directory detected
-
-The installer warns if SpecRails artifacts already exist. You can merge (install alongside existing files) or abort to review manually.
-
-### Placeholders not resolved
-
-If you see `{{PLACEHOLDER}}` in generated files (scaffold method), the `/specrails:enrich` wizard did not complete. Re-run `/specrails:enrich` or fill the values manually.
-
-### "No Claude API key configured"
-
-Claude Code supports two authentication modes:
-
-- **OAuth** — the default for new installs (`claude auth login`). No API key appears in `claude config`.
-- **API key** — explicit key set via `claude config set api_key <key>` or `ANTHROPIC_API_KEY`.
-
-If you authenticated via OAuth, the installer's prerequisite check still fails even though Claude Code is working. Bypass it with:
-
-```bash
-SPECRAILS_SKIP_PREREQS=1 npx specrails-core@latest init --root-dir .
-```
-
-Or set an API key explicitly if you prefer:
-
-```bash
-export ANTHROPIC_API_KEY=sk-ant-...
-npx specrails-core@latest init --root-dir .
-```
-
-### Claude Code not found
-
-Install Claude Code following [Anthropic's guide](https://docs.anthropic.com/en/docs/claude-code), then re-run the installer.
-
-### Codex CLI not found
-
-Install Codex CLI and re-run:
-
-```bash
-npm i -g @openai/codex
-```
-
-Or force the provider if Codex is installed at a non-standard path:
-
-```bash
-npx specrails-core@latest init --root-dir . --provider codex
-```
-
----
-
-[← Getting Started](../getting-started.md) · [Quick Start →](quick-start.md) · [Getting Started (Codex) →](getting-started-codex.md) · [CLI Reference →](cli-reference.md)

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

@@ -1,96 +0,0 @@
-# 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.
-
-
-## Acceptance evidence and completion
-
-
-After development, normal review MUST write `stateDir/acceptance.json` and run
-`acceptance --request <absolute-path>` before `phase --phase reviewer --status done`.
-The request is `{criteria: [...], checks: [...], findings: [...]}`:
-- Each criterion has `specId` (string), `criterionIndex` (zero-based), `requirement`
-  (exact frozen text), `status` (`met`, `exception`, `blocked`, `pending`) and a
-  nonempty `evidence` array of concrete code/test/capture references and observations.
-  Cover every frozen acceptance criterion once. If a spec has no explicit criteria,
-  use its complete frozen description (or title if empty) at index 0.
-- An `exception` MUST include `{reason, impact, material, acceptedBy, approvalEvidence}`.
-  `acceptedBy` is `reviewer`, `user`, or `host`. Material scope changes require actual
-  user/host authorization; do not invent approval or label material changes minor.
-  Previously authorized decisions need no new confirmation. Unresolved requirements
-  remain `blocked` or `pending`, never `met` through a rewritten interpretation.
-- Each check has `{name, status, required, evidence, scope, limitations}`; status is
-  `passed`, `failed`, or `unavailable`. Include required and supplementary checks from
-  the design. Record the original required classification; never downgrade a failed
-  check to make the gate pass. For benchmarks state what is measured and excluded:
-  a Node microbenchmark does not establish browser Canvas/GPU/frame performance.
-- `findings` lists concrete review conclusions, risks and resolutions; use an empty
-  array only when no findings remain. Numeric confidence cannot replace this report.
-
-The runtime binds this evidence to frozen scope, source and design. Missing/stale
-acceptance or unresolved requirements/required checks block review and archive.
-Accepted exceptions and supplementary failures produce `with-exceptions` validation.
-Replacing the report requires review and archive authorization again; a green command
-receipt alone is insufficient. Evidence references and approval attribution remain
-reviewer assertions, not independently authenticated proof of human approval.
-
-Keep operational completion notes, check requests and reports in `stateDir` from
-start to finish. Run scoped checks for repairs and one final full verification after
-all edits. Reuse that full receipt while runtime status says it is valid and its
-commands cover required checks. New prose/phase handoffs alone do not warrant reruns.
-
-End with ONE concise summary from runtime `status.completion`: implementation,
-validation (including exceptions), archive, delivery, and evidence references.
-Host-owned delivery stays `pending-host`; do not call uncommitted files "landed".
-Report phase durations/attempts from `status.phases`; report per-phase cost only when
-provider telemetry attributes it, otherwise unavailable. Do not invent cost splits.

package/docs/user-docs/quick-start.md

@@ -1,161 +0,0 @@
-# Quick Start
-
-Get SpecRails running in your project in under 10 minutes.
-
-## Before you begin
-
-You need:
-- **One supported AI CLI** — Claude Code, Codex CLI, Gemini CLI, or Kimi Code
-- **A git repository** — your project must have a `.git` directory
-
-Optional:
-- **GitHub CLI** (`gh`) — enables automatic PR creation
-
-## Step 1: Install
-
-### Plugin method (recommended — no Node.js required)
-
-```bash
-claude plugin install sr
-```
-
-### Scaffold method (all providers; requires Node.js)
-
-```bash
-npx specrails-core@latest init --root-dir .
-```
-
-Your existing code is not touched by either method.
-
-## Step 2: Run the enrich wizard
-
-Open the selected provider in your project. For example:
-
-```bash
-kimi
-```
-
-Then activate enrich using that provider's syntax:
-
-```
-/specrails:enrich              # Claude or Gemini
-/skill:specrails-enrich        # Kimi interactive TUI
-```
-
-Codex activates the generated enrich skill from `.codex/skills/`. For provider
-details and headless Kimi usage, see the [installation guide](installation.md)
-and [Kimi guide](getting-started-kimi.md).
-
-The wizard runs the full 5-phase setup (about 5 minutes). It analyzes your codebase and configures SpecRails for your specific project:
-
-```
-Phase 1/5  Analyzing codebase...
-           → Detected: TypeScript, Express, PostgreSQL
-           → Found 3 architecture layers
-           → Identified CI commands: npm test, npm run lint
-
-Phase 2/5  Generating user personas...
-           → Researching your domain
-           → Created 3 VPC profiles
-
-Phase 3/5  Configuration...
-           → Backlog provider: local
-           → Git workflow: trunk-based
-
-Phase 4/5  Generating files...
-           → .specrails/config.yaml
-           → .specrails/personas/ (3 VPC profiles)
-           → .specrails/rules/ (per-layer conventions)
-
-Phase 5/5  Cleanup complete.
-
-✓ SpecRails is ready. Run /specrails:implement to start building.
-```
-
-**In a hurry?** Use `/specrails:enrich --quick` for a 3-question quick setup (under a minute). You can always run the full wizard later.
-
-**Used the TUI installer?** If the `npx specrails-core@latest init` TUI already collected your agent and model choices, run `/specrails:enrich --from-config` to apply them automatically.
-
-## Step 3: Implement your first feature
-
-Pick something small. Either reference a GitHub Issue or describe it in plain text:
-
-```
-/specrails:implement #42
-```
-
-or:
-
-```
-/specrails:implement "add a health check endpoint to the API"
-```
-
-The pipeline runs automatically:
-
-```
-Phase 3a  Architect designing...
-          → Design: GET /health endpoint + middleware
-          → Tasks: 3 steps
-
-Phase 3b  Developer implementing...
-          → src/routes/health.ts (created)
-          → src/middleware/health.ts (created)
-          → src/app.ts (modified)
-
-Phase 3c  Test Writer generating...
-          → tests/routes/health.test.ts (created)
-          → 5 tests, all passing
-
-Phase 3d  Doc Sync updating...
-          → CHANGELOG.md updated
-
-Phase 4   Security Reviewer scanning...
-          → No critical findings
-
-Phase 4b  Reviewer running CI...
-          → ✓ lint   ✓ typecheck   ✓ tests
-
-Phase 4b-conf  Confidence: 91% — threshold met
-
-PR #43 created: feat: add health check endpoint
-```
-
-One command. The PR is ready for human review.
-
-## What's next?
-
-**Explore the backlog:**
-
-```
-/specrails:get-backlog-specs
-```
-
-See your tickets ranked by persona fit and effort. The top 3 are safe to implement next. Uses local tickets by default.
-
-**Generate new feature ideas:**
-
-```
-/specrails:auto-propose-backlog-specs
-```
-
-The Product Manager researches your competitive landscape and creates new tickets (local by default, or GitHub Issues if configured).
-
-**Run multiple features in parallel:**
-
-```
-/specrails:implement #42, #43, #44
-```
-
-Each feature gets its own git worktree. Pipelines run concurrently and merge automatically.
-
-**Ask why a decision was made:**
-
-```
-/specrails:why "why did we choose this database schema"
-```
-
-Agents record their reasoning as they work. `/specrails:why` searches those records in plain language.
-
----
-
-[← Getting Started](../getting-started.md) · [← Installation](installation.md) · [CLI Reference →](cli-reference.md) · [FAQ →](faq.md)

package/docs/windows.md

@@ -1,78 +0,0 @@
-# Windows support
-
-specrails-core runs natively on Windows 10 (1809+) and Windows 11, on both x64 and ARM64 (via the built-in x64 emulation layer). There is **no dependency on `bash`, `python3`, or any POSIX-only tooling** — the installer is pure Node.
-
-## Requirements
-
-- **Windows 10 1809+** or **Windows 11** (x64 or ARM64)
-- **Node.js ≥ 20.19.0** — the minimum required by the pinned OpenSpec 1.4.1 CLI; install from [nodejs.org](https://nodejs.org/)
-- **git ≥ 2.25** — install from [git-scm.com](https://git-scm.com/)
-- One supported provider CLI: `claude.cmd`, `codex.cmd`, `gemini.cmd`, or
-  `kimi.cmd`
-
-`npm install -g @anthropic-ai/claude-code` installs the Claude CLI as `claude.cmd` into your global npm bin (`%APPDATA%\npm\`). Make sure that directory is on your PATH so `where claude` resolves it.
-
-For Kimi Code, use the official PowerShell installer:
-
-```powershell
-irm https://code.kimi.com/kimi-code/install.ps1 | iex
-kimi login
-```
-
-Then verify `where kimi` and `kimi --version`. SpecRails does not install or
-start Kimi Server. For headless skills, its managed Node runner resolves the
-external Kimi executable from `PATH`. A native executable is spawned directly.
-For a standard npm `kimi.cmd`/`kimi.bat` shim, the runner extracts Kimi's
-JavaScript entry point and launches it with Node using `shell: false`; it never
-passes user input through `cmd.exe`. A non-standard command shim fails closed.
-The vendored YAML parser is plain ESM and introduces no native dependency.
-
-Windows `CreateProcess` cannot carry SpecRails' largest materialized workflow
-as an argv value. For the standard npm shim, a fixed Node bootstrap therefore
-receives the full prompt over stdin, replaces only Core's fixed `-p` marker in
-`process.argv`, and imports Kimi's official entry. Kimi prompt mode does not
-need stdin after startup. The transported command line is capped at 30,000
-UTF-16 code units. Native executables cannot use this npm-entry bootstrap and
-fail with actionable guidance when their argv exceeds that budget.
-
-## Install
-
-From PowerShell or cmd.exe:
-
-```powershell
-cd C:\path\to\your\project
-npx specrails-core@latest init
-```
-
-The installer:
-- probes PATH with `where` (instead of the POSIX `which`),
-- spawns provider and package-manager `.cmd` shims with the repository's safe
-  Windows process wrapper,
-- writes all files with LF line endings regardless of `core.autocrlf` to keep the bundled templates portable.
-
-## PowerShell execution policy
-
-If `npm` errors with `npm.ps1 cannot be loaded because running scripts is disabled on this system`, relax the policy for your user:
-
-```powershell
-Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
-```
-
-`RemoteSigned` is the MSFT-recommended minimum for dev tooling.
-
-## Known limitations
-
-- **PATH refresh after installing new tools.** Windows GUI shells (Explorer, launcher-started apps) do not re-read PATH until logout/login. If you install `claude.cmd` and launch specrails-desktop immediately, the desktop app's sidecar may not see it. Restart the app after changes to the Env Vars dialog, or launch from a fresh PowerShell.
-- **CRLF checkouts.** If you clone specrails-core with `core.autocrlf=true`, the repo's `.gitattributes` forces LF on every text file at checkout so the Node installer writes byte-identical artefacts across platforms. Running `git add --renormalize .` once after cloning fixes any pre-existing CRLF contamination.
-- **ARM64.** The x64 Node binary runs under Windows 11's native x64 emulation. All native dependencies we use (`better-sqlite3`, `node-pty`, etc.) resolve to their x64 prebuilts; performance hit is ~10-20% vs native ARM64 but fully functional.
-
-## CI
-
-The specrails-core GitHub Actions workflow runs the vitest suite on `windows-latest` in a matrix with `ubuntu-latest` and `macos-latest`, on the exact Node 20.19.0 floor and Node 22. Any PR that regresses Windows behaviour fails CI immediately.
-
-## Reporting Windows-specific bugs
-
-[GitHub Issues](https://github.com/fjpulidop/specrails-core/issues). Include:
-- Windows version (`winver`)
-- Node version (`node --version`)
-- Full output of `npx specrails-core doctor` (run inside the affected project)