scrumrun 1.5.2 → 2.1.0

package/SPEC.md

@@ -1,324 +1,332 @@
 # ScrumRun Method Specification
 
-Version: `method 1.0` · Status: draft for review
+Version: `2.0.0` · Status: stable
 
-This document is the formal specification of the ScrumRun method. `CORE.md` is the operational guide agents follow at runtime. `SPEC.md` is the source of truth for state machines, invariants, and composition rules.
+`SPEC.md` defines normative meanings and invariants. `lib/v2/schema.js` defines the machine-enforced ids, paths, statuses, transitions, structural relations, and truth ownership metadata; `lib/commands/manifest.js` defines command grammar. `CORE.md` is the operational runtime guide. Generated `docs/SCHEMA.md` must match the executable schema byte-for-byte. A conflict is a conformance failure: semantics defer to SPEC, mechanically enforced values defer to the schema, grammar defers to the command manifest, and the conflicting representation must be corrected.
 
-If a conflict exists between `CORE.md` and `SPEC.md`, `SPEC.md` wins and `CORE.md` must be updated.
+## 1. Purpose and principles
 
----
+ScrumRun is an evidence-driven Agile runtime for AI-assisted software work. It keeps intent, execution, decisions, and learning distinct while preserving a small daily interface.
 
-## 1. Terminology
+The method is built on five principles:
 
-| Term | Definition |
-|---|---|
-| **Method** | The ScrumRun protocol itself, versioned separately from tooling. |
-| **Artifact** | A `.md` file under `.scrumrun/` that represents state or intent. |
-| **Goal** | The primary long-lived outcome of the project. Exactly one main goal per project. |
-| **Sprint** | A bounded unit of work under the main goal. |
-| **Feature lane** | An isolated planning surface for work that should not pollute the main goal. |
-| **Fix** | A corrective action for a defect or regression. Lighter than a sprint. |
-| **Backlog item** | A candidate for future work. Not active, not committed. |
-| **Decision** | A pending question that blocks or shapes execution. |
-| **Golden rule** | An absolute constraint. Cannot be silently overridden. |
-| **Knowledge fact** | A short, approved statement about the project used during planning. |
-| **Dossier** | A deep, topic-focused study persisted as a durable document. |
-| **Review agent** | A reusable review persona with defined scope and prompt. |
-| **Intake** | The natural-language classifier that routes requests to workflows. |
-| **Approval gate** | A synchronous checkpoint requiring explicit owner consent. |
+1. no canonical write before explicit approval;
+2. Task is the atomic work unit; Sprint is only a timebox or delivery batch;
+3. every execution attempt is a separate Run;
+4. Markdown is canonical and generated indexes are disposable;
+5. knowledge becomes active truth only through evidence and review.
 
----
+## 2. Terminology
+
+| Term | Meaning |
+|---|---|
+| Feature | Long-lived initiative explaining why related work matters. |
+| Task | Atomic intended work: what must be changed or learned. |
+| Sprint | Explicit timebox or delivery batch grouping Tasks: when work is grouped. |
+| Run | One concrete attempt to execute a Task: how it happened. |
+| Review | Scoped validation evidence for a Run, artifact, migration, or release. |
+| Knowledge | Reviewed project fact. |
+| Decision | Explicit normative choice and its evidence. |
+| Insight | Contextual explanation, trade-off, warning, or rationale. |
+| Dossier | Curated topic/module memory with evidence and review metadata. |
+| Guardrail | Mandatory project policy that configuration cannot weaken. |
+| Context package | Bounded, temporary evidence assembled for one request. |
+| Semantic index | Ignored SQLite projection of canonical artifacts, code symbols, and relations. |
+
+A fix is a Task with `type: fix`. A backlog is a view of Tasks with `status: backlog`; neither is a separate canonical entity.
+
+Exact status sets, transitions, directories, cardinalities, and truth-ownership boundaries are generated in [`docs/SCHEMA.md`](docs/SCHEMA.md); they are not duplicated manually here.
+
+## 3. Canonical project model
+
+```text
+.scrumrun/
+  core.md
+  guardrails.md
+  config.md
+  project.md
+  method.json
+  state.md                         # generated view
+  map.md                           # generated view
+  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/                          # ignored and disposable
+    semantic-index.sqlite
+    contexts/
+  vault.local.md                   # optional, ignored, never indexed/rendered
+```
 
-## 2. Artifact Catalog
+`guardrails.md` is the only canonical project-policy file. A v1 `golden-rules.md` may remain as migrated source evidence, but it is never a competing v2 authority.
 
-Every artifact lives at a canonical path and carries mandatory frontmatter. Files without valid frontmatter are treated as untrusted context.
+### 3.1 Universal frontmatter
 
-### 2.1 Frontmatter schema (universal)
+Every canonical entity file must contain:
 
 ```yaml
 ---
-id: <artifact-id>          # e.g. SPR-042, FIX-007, KNOW-K-013
-kind: sprint|fix|feature|goal|backlog|decision|golden|knowledge|dossier|agent|review
-status: <see state machine per kind>
-created: YYYY-MM-DD
-updated: YYYY-MM-DD
-method: 1.0                # method version at time of creation
+id: TASK-018
+kind: task
+status: running
+created: 2026-07-21
+updated: 2026-07-21
+method: 2.0.0
 ---
 ```
 
-### 2.2 Path map
+IDs, filenames, kind, status, real ISO dates, and method version must agree. Unknown fields and authored prose are preserved. Duplicate fields, malformed frontmatter, unsafe paths, and symlinked canonical paths are invalid.
 
-| Kind | Path |
-|---|---|
-| goal (main) | `.scrumrun/goals/main/sprint.md` |
-| goal history | `.scrumrun/goals/main/history.md` |
-| goal decisions | `.scrumrun/goals/main/decisions.md` |
-| feature | `.scrumrun/features/<slug>/feature.md` |
-| feature sprint | `.scrumrun/features/<slug>/sprint.md` |
-| feature history | `.scrumrun/features/<slug>/history.md` |
-| feature decisions | `.scrumrun/features/<slug>/decisions.md` |
-| fix | `.scrumrun/fixes.md` (append-only) |
-| backlog | `.scrumrun/backlog.md` |
-| golden rules | `.scrumrun/golden-rules.md` |
-| knowledge facts | `.scrumrun/knowledge.md` |
-| dossier | `.scrumrun/knowledge/dossiers/<slug>.md` |
-| map | `.scrumrun/map.md` |
-| context | `.scrumrun/context.md` |
-| config | `.scrumrun/config.md` |
-| agents | `.scrumrun/agents.md` |
-| reviews | `.scrumrun/reviews/<id>.md` |
-| vault (local) | `.scrumrun/vault.local.md` |
+### 3.2 Stable identifiers
 
----
-
-## 3. State Machines
-
-### 3.1 Sprint
-
-```
-proposed ──approve──▶ approved ──run──▶ running ──complete──▶ done
-   │                     │                 │
-   │                     └──backlog──▶ shelved
-   │                                       │
-   └──reject──▶ rejected                   └──abort──▶ aborted
-                                     
-   running ──block──▶ blocked ──unblock──▶ running
+| Kind | Identifier |
+|---|---|
+| Feature | `FEAT-NNN` |
+| Task | `TASK-NNN` |
+| Sprint | `SPRINT-NNN` |
+| Run | `RUN-NNN` |
+| Review | `REV-NNN` |
+| Knowledge | `K-NNN` |
+| Decision | `DEC-NNN` |
+| Insight | `INS-NNN` |
+| Dossier | `DOS-NNN` |
+
+Relations use stable IDs or qualified code subjects. Example:
+
+```text
+FEAT-003
+   └── TASK-018
+          ├── executed_by → RUN-044
+          ├── included_in → SPRINT-012
+          ├── constrained_by → DEC-018
+          └── generated → INS-041
 ```
 
-**Transitions:**
-- `proposed → approved`: owner approval required.
-- `approved → running`: explicit `--run` or intake execution consent.
-- `running → done`: all acceptance criteria met AND review agents passed.
-- `running → blocked`: unresolved decision, missing dependency, or golden rule fire.
-- `running → aborted`: owner-initiated cancellation. Requires reason in history.
-- `approved → shelved`: sent to backlog before execution.
+### 3.3 Run event ledger
 
-**Invariant references:** I-01, I-02, I-05, I-07.
+A newly authored Run declares `ledger: 1` and owns exactly one append-only operational event stream under `## Events`. Event ids are stable and scoped to the Run (`RUN-044-EVT-001`, `RUN-044-EVT-002`, ...). Each JSON event records a contiguous sequence, RFC3339 timestamp, timestamp precision, actor, source and destination states, reason, and typed evidence.
 
-### 3.2 Fix
+Native Runs begin with `created → executing`. A migration may instead create one evidenced `snapshot` as the historical baseline when the source proves a recorded status but not its full transition path. A snapshot exposes that uncertainty and never fabricates intermediate states.
 
-```
-proposed ──approve──▶ approved ──run──▶ running ──complete──▶ done
-                                           │
-                                           └──escalate──▶ (becomes sprint)
-```
+The ledger is the execution authority. Task retains approved scope and synchronized current status, but does not copy Run events. Conformance reconstructs the Run state from its ledger and rejects missing or duplicate ids, invalid ordering, time reversal, illegal transitions, frontmatter drift, missing evidence, and unevidenced completion.
 
-Fix is lighter than sprint: no formal review agents required unless the affected area has agents configured. If scope grows during execution, `escalate` promotes to sprint with the same id lineage recorded in history.
+## 4. State machines
 
-### 3.3 Feature lane
+Only the following transitions are valid.
 
-```
-proposed ──approve──▶ active ──archive──▶ archived
-                        │
-                        └──merge-to-main──▶ merged
-```
-
-A feature lane is a container for sprints. Its sprints follow the sprint state machine independently. `merge-to-main` folds accepted sprints into main goal history.
-
-### 3.4 Backlog item
+### Feature
 
+```text
+backlog → proposed|active|cancelled
+proposed → active|cancelled
+active → paused|completed|cancelled
+paused → active|cancelled
 ```
-added ──promote──▶ (becomes sprint|fix|feature)
-   │
-   └──drop──▶ dropped
-```
-
-Backlog items have no execution state. Promotion creates a new artifact.
 
-### 3.5 Decision
+### Task
 
-```
-open ──resolve──▶ resolved
-  │
-  └──defer──▶ deferred
+```text
+backlog → proposed|running|cancelled
+proposed → running|cancelled
+running → validating|failed|blocked|cancelled
+validating → learning|failed|blocked
+learning → completed|failed|blocked
+partial|failed|blocked → running|cancelled
 ```
 
-An open decision that blocks a running sprint moves the sprint to `blocked` (see 3.1).
+### Sprint
 
-### 3.6 Knowledge fact
-
-```
-proposed ──approve──▶ approved ──deprecate──▶ deprecated
-    │
-    └──reject──▶ rejected (kept for anti-repetition)
+```text
+proposed → running|cancelled
+running → partial|completed|blocked|cancelled
+partial → running|completed|cancelled
+blocked → running|cancelled
 ```
 
-Only `approved` facts are planning truth. `rejected` facts are preserved to prevent re-proposing the same bad assumption.
+### Run
 
-### 3.7 Dossier
-
-```
-drafted ──approve──▶ current ──update──▶ current ──deprecate──▶ deprecated
+```text
+executing → validating|failed|blocked
+validating → learning|failed|blocked
+learning → completed|failed|blocked
+partial → executing|failed|blocked
+blocked → executing|failed
 ```
 
-Every `update` records the previous `commit` hash. A dossier older than the current HEAD by more than N commits (configurable) is marked stale in `context.md`.
-
-### 3.8 Golden rule
-
-```
-proposed ──approve──▶ active ──retire──▶ retired
+A failed or blocked Run is never reused as a new attempt. Retrying its Task creates a new `RUN-NNN` with an incremented attempt and preserves the previous Run byte-for-byte.
+
+### Review and memory
+
+```text
+Review:    proposed → running; running → passed|failed
+           failed → running|archived; passed → archived
+Knowledge: candidate → approved|rejected; approved → deprecated|invalidated
+           rejected → candidate; deprecated → approved
+Decision:  open → resolved|deprecated|invalidated; resolved → deprecated|invalidated
+           deprecated → open
+Insight:   candidate → confirmed|invalidated
+           confirmed → stale|deprecated|invalidated
+           stale → confirmed|deprecated|invalidated; deprecated → confirmed
+Dossier:   active → stale|deprecated|archived; stale → active|deprecated|archived
+           deprecated → archived
 ```
 
-Active golden rules cannot be silently bypassed (see I-08). Retirement requires explicit owner action and is logged.
-
----
-
-## 4. Composition Rules
-
-Which artifact can generate which:
-
-| From ↓ / Generates → | Sprint | Fix | Feature | Backlog | Decision | Knowledge | Dossier |
-|---|---|---|---|---|---|---|---|
-| Intake | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Goal (`--set`) | ✓ | — | — | ✓ | ✓ | — | — |
-| Sprint (running) | — | ✓ | — | ✓ | ✓ | ✓ | — |
-| Fix (running) | ✓ (escalate) | — | — | — | ✓ | ✓ | — |
-| Feature (active) | ✓ | ✓ | — | ✓ | ✓ | ✓ | — |
-| Study | — | — | — | ✓ | — | ✓ | ✓ |
-| Review | — | ✓ | — | ✓ | ✓ | ✓ | — |
-
-Blocking relationships:
-
-- An `open` decision **linked** to a sprint blocks that sprint.
-- A `proposed` golden rule does not block anything.
-- An `active` golden rule blocks any transition that would violate it.
-- A `stale` dossier does not block, but must be surfaced in intake responses.
-
----
-
-## 5. Precedence
-
-When guidance conflicts, apply in this strict order:
-
-```
-1. Golden rules (active)
-2. Open decisions linked to current work
-3. Approved knowledge facts
-4. Current sprint / feature plan
-5. Backlog priority
-6. Dossiers and map
-7. context.md (never authoritative)
+Confirmation/resolution requires at least one resolvable evidence reference. An active Dossier requires evidence at creation; refreshing an already active Dossier records verification without changing its state. AI extraction may create candidates only.
+
+## 5. Request and execution protocol
+
+```text
+RECEIVED
+  → CONTEXTUALIZING (Project Scan + History Engine + Decision Engine)
+  → CONTEXT_PACKAGE
+  → POLICY
+  → RISK
+  → CLASSIFICATION
+  → PLANNING
+  → AWAITING_APPROVAL
+  → EXECUTING
+  → VALIDATING
+  → LEARNING
+  → COMPLETED | FAILED | BLOCKED
 ```
 
-Higher precedence always wins. Lower precedence never silently overrides.
+Everything through `AWAITING_APPROVAL` is read-only. It may exist in process memory or ignored cache only. A valid approval token binds the normalized request, policy result, classification, risk, issuance time, and canonical context fingerprint.
 
----
+Approval atomically creates one Task and its first Run. If either write fails, neither may remain. Project changes after planning invalidate the token. Reusing a successfully consumed token is idempotent.
 
-## 6. Invariants
-
-Numbered for stable reference. Every implementation must uphold all of these.
-
-- **I-01** — No sprint may transition from `proposed` to `running` without explicit owner approval.
-- **I-02** — No code changes may occur outside a `running` sprint, a `running` fix, or an explicitly authorized quick task.
-- **I-03** — An active golden rule cannot be bypassed by any command, flag, or config. Retirement is the only path.
-- **I-04** — Intake is read-only. Intake cannot create, modify, or delete artifacts. Intake cannot modify code.
-- **I-05** — Main goal history and feature lane history are physically separate files and never merge automatically.
-- **I-06** — Approval is synchronous and explicit. Ambiguous acknowledgements (e.g., "ok", "sure") do not constitute approval unless the owner has enabled `Quick Tasks: allow` for that class of action.
-- **I-07** — Every state transition writes exactly one entry to the relevant history file. History is append-only.
-- **I-08** — Golden rules are checked before every planning or execution workflow. A rule fire during a running sprint moves that sprint to `blocked`.
-- **I-09** — `context.md` is never authoritative. All planning must verify against canonical artifacts and source.
-- **I-10** — Only `approved` knowledge facts inform planning. `pending` and `rejected` facts are context, not truth.
-- **I-11** — Secrets from `vault.local.md` must never appear in history, knowledge, backlog, reviews, commits, or logs.
-- **I-12** — Every artifact carries `id`, `kind`, `status`, `created`, `updated`, and `method` frontmatter fields.
-- **I-13** — A dossier update must record the source commit hash for drift detection.
-- **I-14** — Quick tasks may be executed with `Quick Tasks: allow`, but never bypass golden rules, security checks, or explicit user constraints.
-- **I-15** — Rejecting a knowledge fact preserves it in `rejected` state to prevent re-proposing the same assumption.
+Run transitions synchronously update the linked Task and append exactly one structured event to the Run ledger. Validation, learning, completion, failure, block, and resume transitions require a reason or typed evidence. Task status changes without receiving a duplicate narrative history. Multi-file mutations use a durable local transaction journal: `prepared` operations roll back byte-exactly after failure/interruption, while `committed` journals are verified and finalized. Ordinary audit is read-only and reports pending recovery; `doctor --recover` or retrying the approved mutation performs recovery explicitly. Entering `learning` may extract structured candidates from the Run, but extraction failure never blocks Run progress.
 
----
+## 6. Policy and precedence
 
-## 7. Intake Protocol (Formal)
+When guidance conflicts, apply this order:
 
-Intake is the single natural-language entry point. Formal steps:
+1. current explicit owner constraints;
+2. universal method invariants in `core.md`/this specification;
+3. active project Guardrails;
+4. resolved Decisions and confirmed, non-stale Memory relevant to the subject;
+5. the approved Task and active Run;
+6. Sprint/Feature grouping context;
+7. generated `state.md`, `map.md`, context packages, and indexes as navigation only.
 
-1. **Load minimum context:** `core.md`, `golden-rules.md`, `config.md`, `context.md`, and the header of `map.md`.
-2. **Interpret intent** using the desired outcome, not keyword matching.
-3. **Determine risk class:** trivial / bounded / cross-cutting / sensitive.
-4. **Load conditional context** based on risk class:
-   - trivial: current sprint header only.
-   - bounded: current sprint + relevant dossier + relevant knowledge facts.
-   - cross-cutting: full sprint plan + all decisions + map.
-   - sensitive: everything in cross-cutting + full history relevant to affected modules.
-5. **Classify** into one of: `quick-task`, `discovery`, `sprint`, `fix`, `feature`, `backlog`, `reject`, `clarify`.
-6. **Compose response:**
-   - Recommendation with rationale.
-   - Up to two alternatives with tradeoffs.
-   - Risks and unknowns.
-   - Explicit approval request.
-7. **Wait for approval.** No side effects until owner responds.
+Configuration controls preferences but cannot weaken higher levels. Missing or stale context must be surfaced, never rendered as certainty.
 
-Response format is machine-parseable enough to be logged verbatim in `history.md` if the request is approved.
+Every project Guardrail has a stable `GR-NNN` identity, lifecycle status, rule text, enforcement mode, and optional scope/source. Intake evaluates active Guardrails into structured `passed`, `blocked`, or `deferred` results. A block names the responsible Guardrail and machine-readable reason code; a deferred result is shown explicitly and must be enforced at the mutation, migration, review, or owner gate it names. Deferred checks do not become evidence of a pass.
 
----
-
-## 8. Approval Semantics
-
-Approval is a first-class concept and comes in three kinds:
-
-| Kind | What it permits |
-|---|---|
-| **Planning approval** | Create planning records (sprint plan, fix plan, backlog item, dossier draft). |
-| **Execution approval** | Change application code, run tests, execute review agents. |
-| **Structural approval** | Modify golden rules, retire rules, change config, delete artifacts. |
-
-Config policy `Execution Approval: always` requires both planning AND execution approvals separately. `implementation-only` collapses them for the recommended path but still requires an explicit yes before code changes.
-
-There is intentionally no mode that grants blanket implementation permission.
+The executable Policy Engine may infer enforcement for migrated prose, but fresh v2 policy declares it explicitly. Unknown enforcement, duplicate ids, inactive-only policy, configuration that disables approval, and unsafe read-only paths fail conformance. Configuration can tune presentation and workflow preferences; it cannot retire, bypass, or weaken active Guardrails.
 
----
+## 7. Semantic memory and code intelligence
 
-## 9. History Semantics
+Memory records include subject, source, evidence, validity window, confidence where useful, review trigger, and last-verified commit. Insight types may include placement rationale, design constraint, known trade-off, failure history, usage warning, compatibility reason, business rule, performance reason, security reason, and testing note.
 
-`history.md` files are append-only. Every entry has:
+The derived graph may contain:
 
-```
-## <YYYY-MM-DD HH:MM> · <id> · <transition>
-- Owner: <name or "agent-approved">
-- Reason: <one line>
-- Files touched: <optional list>
-- Commit: <optional hash>
+```text
+defined_in
+depends_on
+used_by
+protected_by
+constrained_by
+introduced_by
+modified_by
+has_insight
+evidenced_by
 ```
 
-History is the audit substrate. It answers "what happened, when, and why" without requiring `git log`.
+JavaScript/TypeScript symbols carry a qualified id, path, kind, line, content fingerprint, commit, and adapter identity. A move with the same fingerprint may be remapped. A rename/removal that cannot be proved is retained as orphaned context. Code or evidence drift marks linked memory stale in the projection; it never silently rewrites canonical Markdown.
 
----
+Queries must explain content/relation matches, return evidence/provenance, distinguish candidate/confirmed/stale/inactive/orphaned truth, cap result and relation counts, and exclude rejected/deprecated/invalidated records by default.
 
-## 10. Method Versioning
+The agreed v1 control-context baseline is 48,000 characters. A fresh lean v2 intake control package, excluding the user's request, must remain at or below 12,000 characters (25%). Default semantic retrieval returns at most 10 records and 40 relations per record; hard caps are 100/100.
 
-`method` version is separate from `cli` and `skill` versions.
+## 8. Generated views and cache
 
-- **Patch** (`1.0.x`): clarifications, non-normative additions.
-- **Minor** (`1.x.0`): additive changes (new artifact kind, new state, new invariant).
-- **Major** (`x.0.0`): breaking changes (removed states, changed invariants, changed frontmatter schema, changed path map).
+`state.md`, `map.md`, context packages, and `.cache/semantic-index.sqlite` are non-authoritative projections. They carry source fingerprints or are treated as stale. `state.md` uses the exact canonical fingerprint bound into intake, plus a projection schema, RFC3339 generation time, and a disposable watch fingerprint. SQLite stores its source and watch fingerprints with an explicit cache schema.
 
-Every method-version change ships with `MIGRATION-<from>-to-<to>.md`.
+Freshness checks use a two-tier strategy: unchanged path/stat identity proves that no source read or reparse is needed; changed metadata triggers a complete canonical/source content fingerprint before staleness is asserted. Cache metadata may optimize verification but never supplies project truth. A cache-schema mismatch forces one disposable rebuild. Deleting `.cache/` must not remove authored knowledge, and rebuilding it from unchanged sources must yield equivalent query results.
 
-Tooling versions may change freely. `skill 1.4.2` and `cli 1.4.2` can implement `method 1.0`. A future `skill 2.0.0` can still implement `method 1.0`.
+The index must never scan or store `vault.local.md`. Source scanning is bounded, skips dependencies/build output and symlinks, and uses replaceable language adapters.
 
----
+## 9. Migration from v1
 
-## 11. Conformance
+Migration is explicit and reversible:
 
-An implementation is ScrumRun-compatible if it:
+```text
+scrumrun migrate --to 2 --dry-run
+scrumrun migrate --to 2 --apply
+scrumrun migrate --to 2 --rollback
+```
 
-1. Honors every invariant in §6.
-2. Implements the state machines in §3 for every artifact it exposes.
-3. Enforces precedence in §5.
-4. Provides intake per §7 or refuses to accept natural-language requests entirely.
-5. Writes history per §9.
-6. Declares the `method` version it targets.
+`npx scrumrun@latest update` performs the same read-only preflight when run inside a v1 project and leaves project data untouched. `update --migrate` is an explicit request to apply the verified plan; it is not implicit migration.
+
+Inside an early v2 project, the same commands preflight and explicitly upgrade legacy Run prose to ledger schema 1. Deterministic transition chains are recovered; incomplete history becomes an evidenced snapshot. Apply keeps byte-exact ignored backups, verifies hashes, is idempotent, and supports rollback that refuses to erase later Run changes.
+
+The migrator must:
+
+- hash every source file and block;
+- keep a byte-exact ignored backup;
+- transform in staging and validate before an atomic switch;
+- map each source block to a destination or explicit warning;
+- preserve original v1 files byte-exactly in the ignored backup while removing legacy-only aggregates from the active v2 tree;
+- detect incomplete hybrid v1/v2 layouts and reuse proven canonical Task/Sprint/Run relations instead of duplicating them;
+- normalize only deterministic schema aliases and require resolvable evidence for active migrated memory;
+- be idempotent;
+- reject symlinks, malformed markers, ambiguous destructive guesses, and concurrent source changes;
+- rollback only when doing so cannot erase post-migration work.
+
+Legacy sprint entries become Tasks. History entries become Runs only with an evidenced Task relation. A Sprint is created only from real grouping/timebox evidence. Feature lanes become Features, fixes become `type: fix` Tasks, backlog items become backlog Tasks, extracted insights remain candidates, and golden rules become stable-id Guardrails.
+
+## 10. Normative invariants
+
+- **I-01** No canonical artifact or code write occurs before explicit approval.
+- **I-02** Approval creates a linked Task/Run pair atomically or creates nothing.
+- **I-03** Task is atomic work; Sprint only groups Tasks with real batch/timebox evidence.
+- **I-04** Every retry creates a new Run and preserves earlier attempts.
+- **I-05** Only declared, ordered, evidenced state transitions are accepted; Run event ids are unique and paired transitions are recoverable.
+- **I-06** `guardrails.md` is canonical project policy and configuration cannot weaken it.
+- **I-07** Markdown is canonical; SQLite and generated views are disposable projections.
+- **I-08** AI-created facts/insights remain candidates until explicit human confirmation.
+- **I-09** Confirmed claims have resolvable evidence and review metadata.
+- **I-10** Rejected, deprecated, and invalidated memory is auditable but not active truth; stale memory is labeled.
+- **I-11** Vault values never enter context, artifacts, indexes, reports, logs, commits, or approval tokens.
+- **I-12** Canonical artifacts have valid, matching id/kind/status/date/method frontmatter.
+- **I-13** Missing/stale projections are surfaced and never treated as authoritative.
+- **I-14** Context and semantic retrieval are bounded and explain why evidence matched.
+- **I-15** Migration is explicit; dry-run and ordinary update perform no project writes.
+- **I-16** Migration preserves hashed source coverage, backup, mapping, idempotency, and safe rollback.
+- **I-17** Migration warnings preserve ambiguity; they never invent Sprints, Runs, approval, or truth.
+- **I-18** Partial/interrupted writes, conflicting overwrites, unsafe paths, and symlink traversal fail or recover without corrupting canonical state or overwriting later owner work.
+- **I-19** Code intelligence is derived, adapter-based, fingerprinted, and cannot silently confirm memory.
+- **I-20** Post-validation learning proposes candidates and never blocks Task/Run completion.
+
+## 11. Command grammar
+
+The only canonical root is:
+
+```text
+/sc <noun> <subject> <action> [args]
+```
 
-A conformance test suite lives at `tests/conformance/` and MUST pass for any release claiming compatibility.
+Exactly five nouns exist: `plan`, `knowledge`, `rules`, `review`, and `config`. The implementation manifest is the command source of truth for help and client adapters. Fresh installs expose `/sc`; generated v1 aliases may remain for one compatibility cycle and must execute the canonical route.
 
----
+Unknown syntax fails deterministically and never guesses a mutation.
 
-## 12. Open Questions
+## 12. Conformance and compatibility
 
-Items to resolve before `method 1.0` freezes. Tracked as `⚠️ revisitar` per plan discipline.
+An implementation may claim ScrumRun method 2.0.0 only when it:
 
-- ⚠️ Should `blocked` be a real state or a decoration on `running`?
-- ⚠️ How is a dossier "stale threshold" measured — commits since capture, or file-level touch?
-- ⚠️ Should quick tasks generate a lightweight artifact (e.g., `tasks.md` line) or only a history entry?
-- ⚠️ Precedence between two active golden rules that conflict — defined explicit order, or rejection at rule creation?
-- ⚠️ Do feature lane sprints inherit main goal golden rules automatically, or opt-in?
+1. passes positive and negative tests for I-01 through I-20;
+2. enforces every exposed state machine and schema;
+3. proves read-only intake and dry-run migration through full-tree fingerprints;
+4. proves migration failure recovery, rollback safety, and vault exclusion;
+5. reconstructs every native Run status from a valid, evidenced ledger and detects tampering;
+6. proves cache deletion/rebuild equivalence and inactive-memory filtering;
+7. bounds context/retrieval and records benchmark budgets;
+8. declares method `2.0.0` and requires Node.js `>=22.13.0` for the native SQLite index.
 
-Resolution goes to `DECISIONS.md` as an ADR when closed.
+Method changes follow semantic versioning. Breaking entity, path, invariant, or state changes require a major version and a migration guide.