scrumrun 1.5.2 → 2.1.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,143 @@ 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.
+
+---
+
+## ADR-021 — Run owns a structured append-only event ledger
+Status: accepted
+Date: 2026-07-22
+
+**Context** — A prose `history.md` made operational truth expensive to parse and allowed two incompatible event formats, ambiguous same-day entries, duplicated Task/Run history, and status derived from punctuation-sensitive text.
+
+**Decision** — Run is the sole operational-history authority. Every native Run stores schema-versioned `RUN-NNN-EVT-NNN` JSON events with RFC3339 time, actor, ordered `from`/`to`, reason, and typed evidence. Task synchronizes current status without copying event prose. Early-v2 Runs migrate explicitly: deterministic chains are recovered; ambiguity becomes an evidenced snapshot rather than an invented transition.
+
+**Consequences** — Status reconstruction and audit are deterministic, retries preserve attempts, and agents can retrieve a bounded Run instead of rereading a global log. Cost: event/schema migrations and stricter evidence gates become release obligations.
+
+**Alternatives considered** — Keep one append-only Markdown history with a better template: simpler storage, but still global, token-heavy, and vulnerable to parser drift. Duplicate transitions into Task: convenient locally but creates two authorities.
+
+---
+
+## ADR-022 — Canonical multi-file mutations use durable local transactions
+Status: accepted
+Date: 2026-07-22
+
+**Context** — Approval, Run transitions, and retries update linked artifacts. Per-file atomic rename prevents partial bytes but cannot prevent a crash after only one file has committed.
+
+**Decision** — Linked canonical mutations use an ignored durable transaction journal with prepared/committed states, byte-exact before images, content hashes, fsync-backed writes, deterministic recovery, and hash-only receipts. Prepared work rolls back; committed work is verified and finalized. Recovery refuses to overwrite owner changes made after interruption. Ordinary audit reports pending recovery but remains read-only.
+
+**Consequences** — Task/Run pairs cannot silently diverge after an interrupted mutation. Failure injection proves rollback and recovery. Cost: more local I/O and a transaction schema that must be validated as hostile input.
+
+**Alternatives considered** — Best-effort compensating writes: cannot distinguish interruption from later owner edits. SQLite as canonical transaction store: violates Markdown portability and creates another authority.
+
+---
+
+## ADR-023 — Guardrails are evaluated by an executable Policy Engine
+Status: accepted
+Date: 2026-07-22
+
+**Context** — Canonical Guardrails without deterministic evaluation could be present in context yet silently ignored or described as passed. Migrated prose also makes aggressive inference unsafe.
+
+**Decision** — Active stable-id Guardrails produce structured `passed`, `blocked`, or `deferred` evaluations. Blocks cite the exact `GR-NNN` id and reason code. Deferred checks remain visible for their mutation, migration, review, or owner boundary. Fresh rules declare enforcement explicitly; migrated prose uses conservative inference and ambiguous rules stay manual. Configuration cannot disable approval or weaken active policy.
+
+**Consequences** — Policy advice is traceable to project authority instead of model opinion, while uncertainty stays explicit. Cost: not every project rule can be automated; manual/deferred enforcement remains a first-class result.
+
+**Alternatives considered** — Treat every loaded rule as passed unless a keyword matches: false assurance. Block all manual rules at intake: safe but makes legitimate project-specific policy unusable.
+
+---
+
+## ADR-024 — Derived freshness uses metadata fast path and content-hash fallback
+Status: accepted
+Date: 2026-07-22
+
+**Context** — Recomputing every artifact hash and reparsing the entire code graph before each status or semantic query makes a disposable index defeat its purpose. Trusting timestamps alone would make cache metadata an accidental authority.
+
+**Decision** — `state.md` and semantic SQLite store a source fingerprint plus a watch fingerprint over path/stat identity. An unchanged watch avoids source reads. Any metadata drift triggers a complete canonical/source content fingerprint before staleness is asserted. Cache schemas are explicit and mismatches force one rebuild. Commit-only changes do not invalidate semantically unchanged code.
+
+**Consequences** — Normal queries stay fast while content remains the final verifier. State and intake share one canonical fingerprint implementation. Cost: metadata-only touches may trigger one full verification, and scanner changes require a cache-schema bump.
+
+**Alternatives considered** — Hash every source on every query: maximally simple but O(project) on the hot path. Timestamp-only cache validity: faster but allows derived metadata to masquerade as truth.

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,120 @@
+# 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.
+
+### Early v2 Run upgrade
+
+Projects created by the first 2.0.0 build may contain prose-based Run transitions. The same ongoing-project commands detect this layout without writes and, after explicit `--migrate`, upgrade it to ledger schema 1:
+
+```text
+.scrumrun/.migration/run-ledger-v1/manifest.json
+.scrumrun/.migration/run-ledger-v1/backup/runs/RUN-NNN.md
+```
+
+Every changed Run and `method.json` is hashed and backed up byte-exactly. Proven transition chains become ordered `RUN-NNN-EVT-NNN` events. When only the recorded status is provable, migration emits one evidenced `snapshot`; it does not invent the missing path. Replay is idempotent, an interrupted apply restores prepared sources, and rollback refuses when a Run changed after migration.
+
+## 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.