scrumrun 1.5.2 → 2.0.0

package/DECISIONS.md

@@ -18,7 +18,7 @@ Date: YYYY-MM-DD
 ---
 
 ## ADR-001 — Markdown as the sole persistence format
-Status: accepted
+Status: superseded in part by ADR-017
 Date: 2026-07-17
 
 **Context** — ScrumRun needs a persistence layer for state that is (a) portable across AI agents, (b) diffable via git, (c) readable by humans without tooling, (d) editable by hand in an emergency.
@@ -39,7 +39,7 @@ Date: 2026-07-17
 
 **Decision** — Approval gates are synchronous checkpoints requiring explicit owner response. There is intentionally no config option to grant blanket implementation permission (see I-01, I-06).
 
-**Consequences** — Slower than fully autonomous execution. But every code change has a recorded owner decision. Cost: friction on trivial tasks — mitigated by the `Quick Tasks: allow` policy, which still cannot override golden rules.
+**Consequences** — Slower than fully autonomous execution. But every code change has a recorded owner decision. Cost: friction on trivial tasks — mitigated by concise quick-task planning, never by removing the approval gate or bypassing Guardrails.
 
 **Alternatives considered** — Async approval (approve later): breaks the "audit trail matches execution" property. Silent execution with rollback: rollback is not a substitute for consent.
 
@@ -74,7 +74,7 @@ Date: 2026-07-17
 ---
 
 ## ADR-005 — Main goal and feature lanes are physically separate
-Status: accepted
+Status: superseded by ADR-015
 Date: 2026-07-17
 
 **Context** — Feature ideas frequently arrive mid-sprint. Merging them into main sprint history dilutes the narrative of the main goal and makes historical audit harder.
@@ -88,12 +88,12 @@ Date: 2026-07-17
 ---
 
 ## ADR-006 — Golden rules cannot be silently bypassed
-Status: accepted
+Status: superseded by ADR-016
 Date: 2026-07-17
 
 **Context** — Configuration flags that disable safety features are the most common source of preventable damage in AI-assisted workflows.
 
-**Decision** — Active golden rules have highest precedence. There is no command flag, no config option, and no intake path that disables them. Retirement requires explicit owner action and is logged (see I-03, I-08).
+**Decision** — Active project rules have highest precedence. There is no command flag, no config option, and no intake path that disables them. Retirement requires explicit owner action and is logged. ADR-016 later renamed and consolidated this authority as canonical Guardrails.
 
 **Consequences** — Guarantees that "add rule X" produces durable behavior. Cost: cannot temporarily suspend a rule — must retire, act, re-add. Intentional friction.
 
@@ -102,7 +102,7 @@ Date: 2026-07-17
 ---
 
 ## ADR-007 — `context.md` is never authoritative
-Status: accepted
+Status: superseded by ADR-017
 Date: 2026-07-17
 
 **Context** — Token economy pressure encourages agents to trust cached summaries. A summary that is 90% accurate is a summary that will mislead 10% of the time on production decisions.
@@ -116,7 +116,7 @@ Date: 2026-07-17
 ---
 
 ## ADR-008 — Fixes and sprints coexist as distinct kinds
-Status: accepted
+Status: superseded by ADR-015
 Date: 2026-07-17
 
 **Context** — A production bug is not a full sprint. Forcing every corrective action through the sprint protocol (plan, review, complete) adds overhead disproportionate to the risk.
@@ -185,15 +185,15 @@ Date: 2026-07-17
 
 ---
 
-## ADR-013 — Six-command grammar (planned, not yet implemented)
-Status: proposed
+## ADR-013 — Root command with five domain nouns
+Status: accepted
 Date: 2026-07-17
 
 **Context** — Twenty `sc-*` commands accumulated organically. Overlap between commands (study/know/map/context, sprint/fix/feature/backlog/goal) suggests the grammar has grown by addition rather than design.
 
-**Decision** — Consolidate the 20 verbs into 6 nouns: `/sc`, `/sc plan`, `/sc knowledge`, `/sc rules`, `/sc review`, `/sc config`. Legacy commands become invisible aliases for one release cycle, then removed.
+**Decision** — Expose one root command, `/sc`, with five domain nouns: `plan`, `knowledge`, `rules`, `review`, and `config`. Actions remain canonical long flags. Client integrations are generated from one command manifest. Legacy commands are real compatibility adapters during migration, never prompts that merely tell the user to invoke another command.
 
-**Consequences** — Grammar reflects method structure (§4 composition). Discoverability improves without hiding power. Cost: one-time migration effort for existing users — currently only the author.
+**Consequences** — The installed surface becomes genuinely smaller and the grammar reflects method structure. One manifest prevents drift between clients, help, tests, and documentation. Cost: v1 installations require an explicit migration path.
 
 **Alternatives considered** — Keep 20 with better docs: does not address root cause (design accretion). Reduce to 2 (only intake + one power command): loses the ability to script determin­istically.
 
@@ -210,3 +210,87 @@ Date: 2026-07-17
 **Consequences** — Method is usable in the owner's native language without translation overhead. Cost: docs and examples may lag between languages — accepted.
 
 **Alternatives considered** — Auto-detect from user input: unreliable across sessions and mixed-language inputs.
+
+---
+
+## ADR-015 — Task, Sprint, Feature, and Run are separate entities
+Status: accepted
+Date: 2026-07-21
+
+**Context** — Earlier ScrumRun versions treated a sprint as the smallest executable unit. That conflated a task with an Agile timebox, made retries overwrite operational meaning, and forced agents to infer relationships from large Markdown catalogs.
+
+**Decision** — Task is the atomic unit of intended work. Sprint is a timebox or delivery batch that references tasks. Feature is a long-lived initiative that can span tasks and sprints. Run is one concrete execution attempt of a task. All relations use stable ids: `FEAT-NNN`, `TASK-NNN`, `SPRINT-NNN`, and `RUN-NNN`.
+
+**Consequences** — Agents can traverse an explicit graph, retry a task without erasing failed attempts, distinguish product intent from execution, and attach decisions/insights to the correct granularity. Cost: migration must split legacy sprint records into the new entities without inventing false detail.
+
+**Alternatives considered** — Keep sprint as the atomic work item: simpler storage but semantically incorrect and weak for retries. Nest task files under features/sprints: creates duplicated ownership and fragile moves.
+
+---
+
+## ADR-016 — Guardrails are canonical and lean is a read policy
+Status: accepted
+Date: 2026-07-21
+
+**Context** — A generated `guardrails.md` sourced from `golden-rules.md` duplicated the most important rules and could drift or point to missing canonical files in lean mode.
+
+**Decision** — `.scrumrun/guardrails.md` is the single canonical project-policy artifact and replaces `golden-rules.md`. Universal method invariants remain in `core.md`; owner/project constraints live in `guardrails.md`; operational preferences live in `config.md`. Lean mode changes the initial read set, not the completeness of stored truth.
+
+**Consequences** — The normal agent hot path is `AGENTS.md → guardrails.md → state.md`, with `core.md` and targeted canonical artifacts loaded only when needed. Cost: v1 golden rules require a lossless migration into guardrails.
+
+**Alternatives considered** — Keep both files: preserves v1 paths but creates ambiguous precedence and drift. Make guardrails generated: fast to read but unsafe as an authority.
+
+---
+
+## ADR-017 — Semantic memory uses Markdown truth and a derived index
+Status: accepted
+Date: 2026-07-21
+
+**Context** — Semantic code memory needs fast relationship queries, while ScrumRun's portability requires human-readable, diffable, tool-independent truth.
+
+**Decision** — Knowledge, architectural decisions, insights, dossiers, tasks, sprints, features, and runs remain canonical Markdown artifacts. SQLite under `.scrumrun/.cache/` stores only rebuildable indexes, code symbols, derived relations, and temporary context packages. Deleting the cache must never delete authored knowledge.
+
+**Consequences** — Agents get graph-speed retrieval without locking project memory to a database. Confirmed insights require evidence; AI extraction creates candidates only. Cost: rebuild and equivalence tests become release requirements.
+
+**Alternatives considered** — SQLite as canonical storage: faster writes but opaque diffs and weaker portability. Markdown-only scanning: portable but increasingly slow and token-heavy.
+
+---
+
+## ADR-018 — ScrumRun v2 persists only after approval
+Status: accepted
+Date: 2026-07-21
+
+**Context** — Contextualization, risk assessment, classification, and planning must inspect significant project state, but intake is required to remain side-effect free.
+
+**Decision** — `RECEIVED → CONTEXTUALIZING → POLICY → RISK → CLASSIFICATION → PLANNING → AWAITING_APPROVAL` is transient. Context packages may exist only in ignored disposable cache. Explicit approval creates or updates the canonical Task and starts a Run. A Run then moves through `executing → validating → learning → completed|failed|blocked`.
+
+**Consequences** — Intake remains read-only while approved execution becomes fully auditable. Retries create new runs for the same task. Learning proposes `K`, `DEC`, or `INS` records but never confirms them automatically.
+
+**Alternatives considered** — Persist every received request: stronger raw audit but violates read-only intake and retains unapproved user content. Reuse task status for attempts: loses retry history.
+
+---
+
+## ADR-019 — v1-to-v2 migration is explicit, lossless, and reversible
+Status: accepted
+Date: 2026-07-21
+
+**Context** — ScrumRun 1.x stores atomic work as sprint entries inside aggregate Markdown files. ScrumRun 2.0 separates Feature, Task, Sprint, Run, and Memory. Blindly renaming files would either lose history or invent relationships that never existed.
+
+**Decision** — `scrumrun migrate --to 2` is an explicit workflow with `--dry-run`, content-hashed inventory, local backup, staged transformation, validation, atomic application, mapping report, idempotent replay, and `--rollback`. Ordinary updates never auto-migrate project data. An update may perform a read-only preflight; only the explicit `update --migrate` flag applies the verified plan. Legacy sprint entries become Tasks; historical attempts become Runs; a v2 Sprint is created only when v1 evidence supports a real grouping/timebox. Uncertain mappings are preserved and flagged, never guessed.
+
+**Consequences** — Every source block is traceable to a destination id and users can recover the complete v1 tree. Cost: the v2 artifact kernel must ship with dual-layout readers and realistic migration fixtures before the new layout becomes default.
+
+**Alternatives considered** — In-place rewrite: smaller implementation but unsafe and hard to audit. Preserve v1 forever: avoids migration risk but prevents a coherent v2 domain model.
+
+---
+
+## ADR-020 — Ongoing projects preflight migration during update
+Status: accepted
+Date: 2026-07-21
+
+**Context** — Existing users naturally run `npx scrumrun@latest update` to receive new client commands. If project migration is completely separate, an ongoing v1 project can receive a v2 command surface without noticing that its canonical layout still needs review.
+
+**Decision** — When `update` runs inside a v1 project, it automatically executes the v1→v2 dry-run and prints its verified inventory, mappings, warnings, and blockers. The preflight is read-only. Project state changes only when the owner supplies `--migrate`, which applies the same verified migration workflow and preserves standalone rollback.
+
+**Consequences** — Ongoing projects cannot silently miss the required migration, while automation and cautious users retain a zero-write default. Cost: update output is longer inside a v1 project and the update command must remain migration-aware.
+
+**Alternatives considered** — Automatically applying during every update: rejected because updating client integrations is not implicit consent to rewrite project state. Keeping update unaware: safer in isolation but makes partial upgrades easy and confusing.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leander Costa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATION-1-to-2.md

@@ -0,0 +1,109 @@
+# Migrating ScrumRun 1.x to 2.0
+
+ScrumRun 2.0 changes the domain model: legacy “sprint entries” usually become Tasks, execution history becomes Runs, and Sprints exist only when the source proves a real timebox or delivery batch. Migration is therefore explicit, hashed, staged, and reversible.
+
+## Requirements
+
+- Node.js `>=22.13.0`.
+- A readable `.scrumrun/` v1 directory with no symlinks inside it.
+- Enough local disk space for a byte-exact backup plus the migrated tree.
+- A clean understanding of any post-migration changes before rollback.
+
+The local vault stays at `.scrumrun/vault.local.md`; its content is preserved and never printed. Secret-like content outside the vault blocks migration so it is not duplicated into new artifacts.
+
+## Recommended ongoing-project flow
+
+```bash
+npx scrumrun@latest update
+```
+
+Inside a v1 project, update installs the current client integrations and runs a zero-write migration preflight. Review:
+
+- source fingerprint and file count;
+- generated artifact counts;
+- source-to-destination mappings;
+- warnings and blockers.
+
+Apply exactly that workflow only after review:
+
+```bash
+npx scrumrun@latest update --migrate
+```
+
+`--migrate` is explicit consent. Ordinary update never changes canonical project data.
+
+## Standalone flow
+
+```bash
+npx scrumrun@latest migrate --to 2 --dry-run
+npx scrumrun@latest migrate --to 2 --apply
+```
+
+After apply, inspect:
+
+```text
+.scrumrun/.migration/v1-to-v2/manifest.json
+.scrumrun/.migration/v1-to-v2/report.md
+.scrumrun/tasks/
+.scrumrun/runs/
+.scrumrun/sprints/
+.scrumrun/features/
+.scrumrun/memory/
+```
+
+The `.migration/` directory is ignored. The manifest records the original tree fingerprint, every generated file hash, mappings, archived paths, and warnings. The backup contains the byte-exact original tree. After apply, legacy-only aggregate files exist only in that backup, so the active tree has one unambiguous v2 layout.
+
+Incomplete hybrid trees are supported. If canonical `TASK-NNN`, `SPRINT-NNN`, or `RUN-NNN` artifacts already represent a legacy entry, the report marks it `represented-by-existing-v2` and does not create a duplicate. Deterministic pre-release aliases such as a Decision with `status: confirmed` may be normalized to the declared v2 status while the original bytes remain in the backup. Anything ambiguous is blocked or warned instead of guessed.
+
+## Mapping rules
+
+| v1 source | v2 result |
+|---|---|
+| Main/feature sprint entry | Task with legacy provenance |
+| History attempt linked by evidence | Run for the migrated Task |
+| Explicit timebox/delivery batch | Sprint grouping Tasks |
+| Feature lane | Feature plus linked Tasks/Runs |
+| Backlog item | Task with `status: backlog` |
+| Fix | Task with `type: fix`; Run when execution is evidenced |
+| Approved/pending/rejected knowledge | Same semantic state in `K-NNN` |
+| Reusable AI-like insight | Candidate `INS-NNN`, never confirmed |
+| Decision | `DEC-NNN` with original source hash/content |
+| Golden rule | Stable-id entry in canonical `guardrails.md` |
+| Dossier/review | Canonical dossier/review artifact with provenance |
+
+Ambiguous records remain preserved and produce warnings. The migrator never invents a Sprint, Run, approval, or confirmed insight.
+
+## Verification
+
+```bash
+npx scrumrun@latest status
+npx scrumrun@latest sc review artifact --run
+npx scrumrun@latest doctor codex --strict
+npx scrumrun@latest sc knowledge map --build
+npx scrumrun@latest sc knowledge study <topic-or-symbol>
+```
+
+Apply is idempotent. Re-running it reports that the project is already migrated and changes nothing.
+
+## Rollback
+
+```bash
+npx scrumrun@latest migrate --to 2 --rollback
+```
+
+Rollback verifies the backup fingerprint and first checks whether it would erase post-migration canonical, vault, source, or new-file changes. Disposable cache and newly generated `state.md`/`map.md` views do not block restoration. If any unsafe difference exists, rollback refuses.
+
+When rollback refuses:
+
+1. read the listed changed paths;
+2. copy/export work you want to keep outside `.scrumrun/`;
+3. restore or deliberately reconcile those paths;
+4. run rollback again.
+
+Do not delete `.scrumrun/.migration/` until the migration has been accepted and rollback is no longer required.
+
+## Failure recovery
+
+Apply transforms a staging copy and validates it before an atomic directory switch. Injected and real failures before/during the switch restore the v1 tree. If a process is interrupted, do not manually merge staging directories: rerun the dry-run, inspect `.scrumrun` and sibling `.scrumrun-v2-*`/`.scrumrun-v1-*` temporary paths, and recover using the verified backup/manifest.
+
+If the preflight reports a malformed `method.json`, a symlink, an unresolved collision, an active memory record without deterministic evidence, or secret-like content outside the vault, fix that blocker and repeat the dry-run. No canonical migration writes occur while blocked.

package/README.md

@@ -1,138 +1,197 @@
 # ScrumRun
 
-> A protocol for AI-assisted software development.
-> Sprints, decisions, invariants, history — auditable and portable across agents.
+> A simple, fast, evidence-driven Agile runtime for AI coding agents.
 
-**Method:** `1.0` (draft) · **CLI/Skill:** `1.5.0` · **License:** MIT
+ScrumRun gives an agent a small command surface and a precise project memory: what should be done, how each attempt happened, which decisions constrain the code, and why the architecture exists in its current form.
 
-ScrumRun gives AI coding agents a stable memory, an explicit approval model, and a state machine for the work they do. The method is documented so any markdown-capable agent can follow it. Client-specific integrations (Claude Code, Codex, OpenCode) are optimizations, not requirements.
+**Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
 
----
+## The model
 
-## Install
+```text
+Feature = why the initiative matters
+Task    = what atomic work must be done
+Sprint  = when Tasks are grouped as a timebox/batch
+Run     = how one concrete attempt happened
+Memory  = what the project learned and why
+```
 
-```bash
-npx scrumrun@latest init
+```text
+FEAT-003
+   └── TASK-018
+          ├── executed_by → RUN-044
+          ├── included_in → SPRINT-012
+          ├── constrained_by → DEC-018
+          └── generated → INS-041
 ```
 
-Local by default: creates `AGENTS.md` and `.scrumrun/`, adds them to `.git/info/exclude`. Use `--shared` to commit them.
+A Task does not need a Sprint. A retry creates a new Run. A fix is a Task with `type: fix`; backlog is a view of backlog Tasks.
 
-### Migrating from the GitHub installer
+See [`docs/SCHEMA.md`](docs/SCHEMA.md) for the generated executable contract and [`docs/ENTITY-MODEL.md`](docs/ENTITY-MODEL.md) for the conceptual guide.
 
-Older installations used `npx github:leandercosta/scrumrun`. Replace the installed client commands and skill with the npm release by running once:
+## Install
 
 ```bash
-npx scrumrun@latest update all
+npx scrumrun@latest install
+npx scrumrun@latest init
 ```
 
-This overwrites only the ScrumRun integrations for Codex, Claude Code, and OpenCode. It does not remove or reset project data, `.scrumrun/`, `AGENTS.md`, knowledge, history, decisions, backlog, or the local vault.
+`install` adds the client integration; `init` creates the project tree. Initialization is local by default: `.scrumrun/` and the generated agent hint are added to `.git/info/exclude`. Use `--shared` when the team wants to commit the project memory.
 
-From then on, use `npx scrumrun@latest ...`. Projects using the legacy pre-`.scrumrun/` file layout can additionally run:
+ScrumRun installs one canonical agent command:
 
-```bash
-npx scrumrun@latest migrate
+```text
+/sc <noun> <subject> <action> [args]
 ```
 
----
+The five nouns are `plan`, `knowledge`, `rules`, `review`, and `config`.
 
-## Usage
+## Daily flow
 
-Once initialized, talk to your agent in natural language:
+Natural language is the normal entry point:
 
+```text
+Move calculateFinalPrice to checkout.
+Fix duplicate charges after refresh.
+Study why pricing depends on TaxCalculator.
 ```
-add a save button to the profile form
-checkout charges twice after refresh
-study the payments module
-run the next sprint
+
+ScrumRun runs a read-only pipeline before asking for approval:
+
+```text
+RECEIVED → CONTEXTUALIZING → POLICY → RISK → CLASSIFICATION
+         → PLANNING → AWAITING_APPROVAL
 ```
 
-The agent runs intake (read-only), classifies the request, proposes a route, and asks for approval before touching artifacts or code. No configuration silently grants blanket implementation permission.
+Explicit approval atomically creates a Task and a Run. Execution then follows:
 
-If you prefer explicit commands, they exist. The canonical grammar uses long flags (`--add`, `--run`, `--audit`, `--approve`). See `CORE.md` for the full reference.
+```text
+EXECUTING → VALIDATING → LEARNING → COMPLETED | FAILED | BLOCKED
+```
 
----
+Nothing canonical is persisted before approval. Failed retries remain available as separate Runs.
 
-## How it works
+## Semantic project memory
 
-Three surfaces, physically separated:
+Canonical memory is human-readable Markdown:
 
-- **Project rules** — golden rules and configuration that every agent honors.
-- **Main goal** — the primary plan, its sprints, decisions, and history.
-- **Feature lanes** — isolated planning that does not pollute the main goal.
+- `K-NNN` — reviewed facts;
+- `DEC-NNN` — normative decisions;
+- `INS-NNN` — contextual rationale, constraints, warnings, and trade-offs;
+- `DOS-NNN` — curated topic/module dossiers.
 
-Every artifact is a `.md` file under `.scrumrun/` with mandatory frontmatter. State transitions are explicit and recorded in `history.md` (append-only). `context.md` is a token-safe snapshot used as a reading guide — never as authoritative truth.
+The agent can answer questions such as:
 
-Fifteen numbered invariants (`I-01`…`I-15`) define behavior that cannot be silently overridden. Golden rules have highest precedence. Intake is strictly read-only. Approval is synchronous and explicit.
+- Why is this function in this module?
+- Which Decision constrains it?
+- Who depends on it?
+- Which test protects it?
+- What is likely to break if it changes?
 
----
+AI extraction creates candidates only. Confirmation requires resolvable evidence. Stale and invalidated memory is labeled; rejected/deprecated/invalidated records are excluded from active truth by default.
 
-## Documentation
+The fast graph/search layer is `.scrumrun/.cache/semantic-index.sqlite`. It is ignored and disposable: deleting it never deletes knowledge. The current JavaScript/TypeScript adapter derives qualified symbols plus `defined_in`, `depends_on`, `used_by`, and `protected_by` relations.
 
-| File | Purpose |
-|---|---|
-| [`CORE.md`](./CORE.md) | Operational guide agents follow at runtime. |
-| [`SPEC.md`](./SPEC.md) | Formal method specification — state machines, invariants, composition rules. |
-| [`DECISIONS.md`](./DECISIONS.md) | ADRs explaining why the method is the way it is. |
-| `.scrumrun/config.md` | Owner preferences (language, approval policy, quick-task policy). |
-| `.scrumrun/golden-rules.md` | Absolute constraints for the project. |
+## Migrating an ongoing v1 project
 
-For AI clients that do not auto-read project instructions, paste this at the start of a session:
+Update the client integrations and automatically run a read-only migration preflight:
 
+```bash
+npx scrumrun@latest update
 ```
-Read AGENTS.md and .scrumrun/core.md before doing anything else.
-Follow ScrumRun exactly.
+
+This shows the source inventory, proposed mappings, and blockers without changing project data. Apply only the verified plan with:
+
+```bash
+npx scrumrun@latest update --migrate
 ```
 
----
+The standalone workflow remains available:
 
-## Portability
+```bash
+npx scrumrun@latest migrate --to 2 --dry-run
+npx scrumrun@latest migrate --to 2 --apply
+npx scrumrun@latest migrate --to 2 --rollback
+```
 
-ScrumRun is designed to outlive specific AI clients. Any agent that reads markdown and follows instructions can implement it by reading `CORE.md`. Slash commands and skills are conveniences, not dependencies.
+Migration uses content hashes, a byte-exact ignored backup, staging validation, an atomic directory switch, a source-to-destination report, idempotent replay, and rollback protection. It also recognizes incomplete hybrid v1/v2 trees, reuses already-linked canonical work, and normalizes only deterministic schema aliases. Legacy-only files leave the active tree but remain byte-exact in the ignored backup; vault contents remain local. Ambiguous history remains an explicit warning, and the migrator never invents a Sprint or Run.
 
-Compatibility matrix (planned, `method 1.0`):
+After migration or an integration update, verify both installed assets and project state:
 
-| Agent | Slash commands | Skill | Manual (CORE.md) |
-|---|---|---|---|
-| Claude Code | ✓ | ✓ | ✓ |
-| Codex | ✓ | — | ✓ |
-| OpenCode | ✓ | — | ✓ |
-| Any markdown-capable agent | — | — | ✓ |
+```bash
+npx scrumrun@latest doctor codex --strict
+```
 
-A conformance test suite is planned under `tests/conformance/` for verifying implementations against the invariants in `SPEC.md`.
+`doctor` compares managed prompt/skill contents with the package, so an obsolete installation is reported as `stale` rather than `ok` merely because the file exists.
+
+## Canonical tree
+
+```text
+.scrumrun/
+  core.md
+  guardrails.md
+  config.md
+  project.md
+  method.json
+  state.md                         # generated
+  map.md                           # generated
+  features/FEAT-NNN.md
+  tasks/TASK-NNN.md
+  sprints/SPRINT-NNN.md
+  runs/RUN-NNN.md
+  reviews/REV-NNN.md
+  memory/
+    knowledge/K-NNN.md
+    decisions/DEC-NNN.md
+    insights/INS-NNN.md
+    dossiers/DOS-NNN.md
+  .cache/semantic-index.sqlite     # generated, ignored
+  vault.local.md                   # optional, ignored, never indexed
+```
 
----
+`guardrails.md` is canonical project policy. `config.md` contains preferences and cannot weaken it. `state.md`, `map.md`, context packages, and SQLite are generated navigation aids, never authority.
 
-## Versioning
+## Useful commands
 
-Three independent version numbers:
+```bash
+# inspect the grammar
+npx scrumrun@latest commands
 
-- **`method`** — the protocol itself. Major bumps only on breaking spec changes.
-- **`cli`** — the installer and command surface.
-- **`skill`** — the agent-facing instructions.
+# plan without writes, then approve the emitted token
+npx scrumrun@latest sc plan intake "Fix pricing rounding"
+npx scrumrun@latest sc plan intake --approve <token>
 
-Tooling can iterate freely. Adopters pin the method version and update tooling with confidence. Every method change ships with a migration guide.
+# memory lifecycle
+npx scrumrun@latest sc knowledge insight --propose "Pricing stays in backend" --evidence src/pricing.ts
+npx scrumrun@latest sc knowledge insight --confirm INS-001
+npx scrumrun@latest sc knowledge study calculateFinalPrice
 
----
+# rebuild or inspect the derived graph
+npx scrumrun@latest sc knowledge map --build
+npx scrumrun@latest sc knowledge map --show
+```
 
-## Status
+The command manifest in `lib/commands/manifest.js` generates help and compatibility adapters, preventing client grammar drift.
 
-- ✅ Portable `CORE.md` for cross-agent execution
-- ✅ Natural-language intake with approval gates
-- ✅ Sprint, feature lane, fix, backlog, decision, knowledge artifacts
-- ✅ Golden rules with unbypassable precedence
-- ✅ Formal `SPEC.md` and `DECISIONS.md` (method 1.0 draft)
-- 🚧 Command grammar consolidation (20 commands → 6, see ADR-013)
-- 🚧 Method versioning separated from CLI
-- 🚧 Portability matrix + conformance test suite
-- 🚧 Landing page at [`scrumrun.dev`](https://scrumrun.dev)
+## Documentation
 
----
+| File | Purpose |
+|---|---|
+| [`CORE.md`](./CORE.md) | Operational runtime guide for agents. |
+| [`SPEC.md`](./SPEC.md) | Normative 2.0 state machines, invariants, and conformance rules. |
+| [`DECISIONS.md`](./DECISIONS.md) | Architectural decisions and trade-offs. |
+| `MIGRATION-1-to-2.md` | Upgrade, verification, rollback, and recovery guide. |
 
-## Contributing
+ScrumRun remains client-independent: any agent that reads Markdown can follow `CORE.md`; Codex, Claude Code, and OpenCode integrations are accelerators.
 
-The method is public and versioned. Proposals that change spec, invariants, or state machines require an ADR entry in `DECISIONS.md`. Tooling changes follow standard PR flow.
+## Development
+
+```bash
+npm test
+npm pack --dry-run
+```
 
----
+The release gates cover artifact/state conformance, read-only intake, migration failure recovery, semantic cache equivalence, code graph behavior, vault exclusion, and CLI compatibility.
 
 ## License