scrumrun 3.1.2 → 4.1.0

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 4.1.0 - 2026-09-22
+
+### Added
+
+- **Declarative migration runner (`lib/migrate/run.js`).** Migrations become plain Markdown files under `migrations/*.md` with fenced `​```yaml steps`, `​```yaml verify`, and optional `​```yaml rollback` blocks. Whitelisted ops: `create_backup`, `rename_path`, `bump_schema`, `move_frontmatter_field`, `assert_hash`. Runner supports `{ dryRun: true }` (no writes) and returns `{ status, journal }` so rollback can operate on exactly what was applied. Path safety enforced: absolute paths and paths escaping the project root are rejected. See `migrations/README.md` for the format contract. Rewrite of the existing v1→v2 imperative migration into this format is delegated to the release cycle (large diff, coordinated release).
+- **Declarative actions API (`lib/actions/`).** New `executeAction(name, projectRoot, payload)` entry point exposes 7 pure functions (`plan.task.add`, `plan.feature.add`, `plan.sprint.add`, `plan.task.amend`, `knowledge.fact.add`, `knowledge.decision.add`, `knowledge.insight.propose`) that delegate to the existing orchestrator/memory services, sharing validation and atomicity. New CLI command `scrumrun action <name> [--payload <json>|--file <path>|--stdin]` and `scrumrun action --list`. Enables hooks, the static view (TASK-026), and future clients to share one write layer without shelling into subcommands. Existing `plan/knowledge/rules/review/config` subcommands are unchanged; rip-out is a release-cycle task.
+- **Append-only per-Task Run ledger (`runs/TASK-NNN.jsonl`).** New `lib/v2/runs-jsonl.js` records each execution event on one line with SHA-256 chain (`prev`/`hash`) for tamper detection. Supersedes the one-file-per-attempt Markdown layout for new work; historic `RUN-NNN.md` files remain readable. Cross-process append safety via `TASK-NNN.jsonl.lock` (exclusive `open wx` + jittered backoff). Design captured in `DEC-010`. Reader/writer wiring for `scrumrun plan run *` and migration of legacy Markdown Runs will land alongside the declarative migration runner (see task TASK-030).
+- **Static HTML view at `.scrumrun/view.html`.** Zero-dependency single-file dashboard (vanilla JS, inline CSS, self-contained) that reads canonical Markdown via relative `fetch()` and renders a status kanban (Tasks), a recent-Runs list, active Guardrails, and Decisions. `scrumrun init` copies it into every project; `scrumrun update --project` refreshes it. Open with `open .scrumrun/view.html` on macOS, `xdg-open .scrumrun/view.html` on Linux, or `start .scrumrun\view.html` on Windows. If your browser blocks `file://` fetches, serve locally: `cd .scrumrun && python3 -m http.server 8080`.
+- **Task Markdown schema validator (opt-in).** New pure library `lib/v2/task-schema.js` validates that a Task carries the sections and evidence its lifecycle requires: `## Request` + `## Done when` for opt-in Tasks, `## Completion` on `status: completed` (or a linked Run whose body contains `## Technical Summary`), and — inside a git repo — a `branch` field in the frontmatter when the Task is `running`/`in_progress`/`validating`/`learning`. Errors: `SR-E-452` (missing section), `SR-E-453` (completed without summary), `SR-E-454` (running without branch, warning-only). Legacy Tasks without `task_schema: 1` in frontmatter are silently skipped for full backward compatibility. Wired into `scrumrun review artifact --run` and `scrumrun doctor --strict`; both accept `--strict` to promote schema warnings to blocking errors.
+- **`lib/git/context.js`.** Pure shell-out helper that returns `{ isRepo, branch, headSha }` for any project directory. Never throws — returns a non-repo shape when git is missing or the cwd is outside a working tree. Cross-platform: resolves `git` from `PATH` (Git for Windows, macOS, Linux). Consumed by the task-schema validator and available to any future feature (e.g. review/verify diff scoping).
+
+### Changed
+
+- **Legacy `sc-*` skill directories are removed on install/update.** Older versions of ScrumRun published one skill per compatibility alias (`sc-sprint`, `sc-decisions`, `sc-vault`, …). Every listed skill costs context in every client conversation, so install/update now sweeps those directories from the target skills folder alongside the pre-existing `ai-scrum` cleanup, while leaving unrelated user skills untouched. The canonical skill remains `scrumrun`; the `scrumrun sc-*` command aliases are unchanged.
+
+## 4.0.0 - 2026-08-31
+
+### Changed
+
+- **Simple Markdown model.** Core, Guardrails, Knowledge, Feature, Sprint, Task, Run, and Backlog are one local Markdown graph connected by stable IDs and relative links. Derived cache/index data is optional and never required for normal work.
+- **Execution-first.** An approved Task continues through discover → implement → verify → fix → verify. Intermediate inventories, progress reports, and discovered in-scope gaps are internal work, never a valid stopping point or Follow-up.
+- **Flexible Task bodies.** Tasks preserve arbitrary owner frontmatter and sections. `## Done when` and `## Completion` are the packaged minimal convention; project Guardrails may require extra sections only for affected Tasks.
+- **Human status vocabulary.** `in_progress` is accepted as a Task status. A Markdown-first Task neither needs a Run nor must agree with historical Run state.
+- **Runs are optional.** A Run may record a Task or a Sprint execution, but no Run, ledger, permit, or CLI state transition can block daily delivery.
+
+### Safety
+
+- **Sealed Markdown policy.** Fresh and refreshed projects pin Core and Guardrail fingerprints. Agents do not edit policy during product work; owner-reviewed policy changes use `scrumrun update --project --seal-policy`. Strict doctor/release audits detect policy drift at the edge, not during every edit.
+
 ## 3.1.2 - 2026-08-31
 
 ### Fixed

package/CORE.md

@@ -84,13 +84,21 @@ AGENTS.md
 
 **Before querying project state, read `.scrumrun/method.json`.** Its `paths` block is the authoritative index of every canonical location in this project. Navigate by that index; if a path is not declared there, it is not canonical truth. Directory listing and grep are fallbacks — never the first step. A ScrumRun-aware agent must never search for `goals/`, `backlog.md`, `sprint.md`, or any legacy layout: those are absent by design once migration completes and are surfaced only through `.scrumrun/.migration-backup/`.
 
-**Markdown is the normal runtime.** After explicit approval, work directly in source files and relevant `.scrumrun/` Markdown. A Task is free to be created, refined, started, completed, and handed off in Markdown; a Run is optional audit context, never a state machine that can prevent daily work. Update the Task's scope, Acceptance Criteria, Technical Summary, and Follow-ups directly. Do not use `npx scrumrun@latest` or normal `scrumrun plan/run` commands during execution.
+**Markdown is the normal runtime.** After explicit approval, work directly in source files and relevant `.scrumrun/` Markdown. A Task is free to be created, refined, started, completed, and handed off in Markdown; a Run is optional audit context, never a state machine that can prevent daily work. Update the Task's scope, Done when, Completion, and Follow-ups directly. Do not use `npx scrumrun@latest` or normal `scrumrun plan/run` commands during execution.
+
+**Execution is continuous.** Once the owner approves a Task, implement it through its delivery contract before replying. Keep using tools and editing files through the full loop: discover → implement → verify → fix → verify. A progress report is allowed only when the owner asks for status, and it must be followed immediately by more execution in the same workflow; it is never an endpoint. Do not stop to give an inventory, a progress report, a decomposition, or a remaining-work list: those are internal steps, not a deliverable. A discovery of missing code, literals, tests, migrations, or configuration inside the approved contract is required work to implement now — it cannot become a report, a partial checker, a “next step”, or a Follow-up. Stop only for an owner decision, external access, an explicit Guardrail, a secret/security risk, destructive work without approval, or an unmet required delivery criterion. A Task's `## Done when` is short and observable; `## Follow-ups` contains only work outside that contract. Never move unfinished contract work to Follow-ups without explicit owner approval.
+
+**Verification must cover the claim.** Never claim that a Task condition is verified merely because a narrower check passes. If the request is “no visible hardcoded literals”, a locale-key parity checker alone is insufficient: scan the relevant views for literals, replace every result in scope, then re-run both the scan and the build. The same rule applies to every delivery claim.
 
 **The CLI is maintenance, not a work gate.** Use it for `init`, `update --project`, `migrate`, `repair`, `doctor`, reports, and release checks. Strict per-edit permits and ledger finalization remain available only when the owner asks for that audit level. Missing/invalid Runs, old status vocabulary, stale projections, and optional tests are warnings to reconcile in Markdown — never an automatic blocker.
 
-**Block only on real constraints.** An agent must stop for an explicit active Guardrail, secret/security risk, destructive action without approval, or an unmet required Acceptance Criterion. It must not manufacture a failed/blocked Run because optional E2E coverage, an optional reviewer, or a non-required environment is unavailable; record meaningful gaps in `## Follow-ups` or a risk note.
+**Block only on real constraints.** An agent must stop for an explicit active Guardrail, secret/security risk, destructive action without approval, or an unmet required Done when item. It must not manufacture a failed/blocked Run because optional E2E coverage, an optional reviewer, or a non-required environment is unavailable; record meaningful gaps in `## Follow-ups` or a risk note.
+
+**Normal operation never mutates Run state through the CLI.** Do not call `plan run --fail|--block|--retry|--finalize|--complete|--validate` or `plan task --start` in daily work. Those are owner-requested strict audit tools only. When a legacy Run already has the wrong administrative outcome, preserve it as history and correct the delivery record directly in the Task's Completion and Follow-ups.
+
+**Policy is sealed at the edge.** `core.md` is the universal execution contract and `guardrails.md` is project policy. Never edit either while delivering product work. A policy change requires an explicit owner request; after review, `scrumrun update --project --seal-policy` records fresh fingerprints. Daily work stays Markdown-only; `doctor --strict` and release audit policy fingerprints, canonical guardrails, and code checks at the boundary.
 
-**Normal operation never mutates Run state through the CLI.** Do not call `plan run --fail|--block|--retry|--finalize|--complete|--validate` or `plan task --start` in daily work. Those are owner-requested strict audit tools only. When a legacy Run already has the wrong administrative outcome, preserve it as history and correct the delivery record directly in the Task's Technical Summary and Follow-ups.
+**Markdown relations are the graph.** Every artifact has a stable ID. Use small frontmatter links such as `sprint: SPRINT-012`, `feature: FEAT-003`, and `depends_on: [TASK-151, DEC-008]`, plus a human-readable `## Related` section with relative links. Preserve all unknown frontmatter and all owner-defined sections. A Guardrail may require a Task section such as `## Migration Plan`, `## Rollback`, or `## Guardrail Evidence`; add it only to the affected Task and keep it until the rule is satisfied.
 
 Canonical truth is Markdown. SQLite/cache data stores only rebuildable indexes, symbol projections, relations, and bounded context packages. Deleting `.cache/` must never delete authored truth.
 
@@ -176,7 +184,7 @@ understand → approve → work → validate required criteria → hand off
 
 Rules:
 
-- a Task carries the intended scope, `## Acceptance Criteria`, `## Technical Summary`, and relevant `## Follow-ups`;
+- a Task carries intended scope, a short `## Done when` contract, `## Completion`, and relevant `## Follow-ups`;
 - validation matches risk and acceptance criteria; tests, reviews, and environments are gates only when explicitly required by the owner, the Task, or an active Guardrail;
 - direct Markdown workflow never blocks on Run linkage, status syntax, stale generated views, or missing optional coverage. If an optional check matters, record it as a follow-up/risk instead of fabricating failure;
 - configured reviews run only when a Guardrail requires one;
@@ -184,7 +192,7 @@ Rules:
 - strict permits, workspace-drift checks, and append-only Guardrail obligations apply only to that optional strict audit path;
 - learning proposes memory candidates when work reveals reusable context and never auto-confirms AI inference;
 - complete a Sprint only when its included Tasks meet its real exit gate;
-- do not mark work complete merely because time or token budget ended.
+- do not mark work complete merely because time or token budget ended, and do not stop an approved Task merely to report intermediate progress.
 
 Canonical mutations are schema-validated, lossless, and atomic. Preserve unknown fields, prose, and unrelated owner edits. A failed mutation must leave canonical state unchanged or recoverable.
 

package/README.md

@@ -4,30 +4,33 @@
 
 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.
 
-**Package:** `3.1.2` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `4.1.0` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
 
 **New here?** Read the [Quickstart](docs/QUICKSTART.md) — first Run in under 10 minutes, no `SPEC.md` reading required. Full docs map in [`docs/INDEX.md`](docs/INDEX.md).
 
 ## The model
 
 ```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
+Core       = how the agent works
+Guardrails = rules that cannot be broken
+Knowledge  = what the project knows and why
+Backlog    = provisioned Tasks not yet started
+Feature    = why a larger initiative exists
+Sprint     = a feature, fix, or maintenance delivery grouping Tasks
+Task       = concrete work, independent or in a Sprint
+Run        = optional record of what happened while executing a Task/Sprint
 ```
 
 ```text
-FEAT-003
+SPRINT-012 (type: fix)
    └── TASK-018
-          ├── executed_by → RUN-044
-          ├── included_in → SPRINT-012
-          ├── constrained_by → DEC-018
-          └── generated → INS-041
+          ├── feature → FEAT-003
+          ├── depends_on → TASK-014, DEC-018
+          ├── guardrails → GR-004
+          └── run → RUN-044 (optional)
 ```
 
-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.
+A Task does not need a Sprint. A Sprint may be `feature`, `fix`, or `maintenance`. A Run is optional and may document a Task or Sprint. Backlog is simply Tasks with `status: backlog`.
 
 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.
 
@@ -60,6 +63,32 @@ scrumrun <noun> <subject> <action> [args]
 
 The five nouns are `plan`, `knowledge`, `rules`, `review`, and `config`. `/sc` is an optional AI-client shortcut; `scrumrun sc ...` remains a compatibility alias for existing integrations.
 
+## Compatibility
+
+ScrumRun is designed to be **portable across AI clients and operating systems**. The runtime is plain Markdown + a small Node.js CLI; nothing is tied to a specific vendor.
+
+### Operating systems
+
+| OS | Status | Notes |
+|---|---|---|
+| macOS 12+ | Supported | Primary development platform. |
+| Linux (glibc-based distros) | Supported | Tested on Ubuntu/Debian/Fedora; `fs.watch` uses inotify. |
+| Windows 10/11 | Supported | Requires Git for Windows for the optional pre-commit hook; `.scrumrun/` paths are POSIX-normalized internally. |
+| WSL2 | Supported | Behaves as Linux. |
+
+Requirement everywhere: **Node.js ≥ 22.13.0** and (optionally) `git` on `PATH`.
+
+### AI clients
+
+| Client | Integration | Notes |
+|---|---|---|
+| Claude Code | `scrumrun install claude` | Installs the `scrumrun` skill under `~/.claude/skills/`. |
+| OpenCode | `scrumrun install opencode` | Installs skill under `~/.config/opencode/skills/`. |
+| Codex | `scrumrun install codex` | Installs skill under `~/.codex/skills/`. |
+| Cursor / Windsurf / Zed / any Markdown-capable agent | Manual | Point the agent at `.scrumrun/` and `CORE.md`; no CLI adapter required. |
+
+The method itself (Markdown tree + guardrails + task/run model) is client-agnostic: any agent that can read files can operate a ScrumRun project.
+
 ## Daily flow
 
 Natural language is the normal entry point:
@@ -79,15 +108,17 @@ RECEIVED → CONTEXTUALIZING → POLICY → RISK → CLASSIFICATION
 
 The agent may assert the classification (`--type fix|task|feature|docs|discovery`) and attach a short technical preview (`--preview "…"`), rendered with color in the terminal before any Task exists. Nothing canonical is persisted before approval.
 
-Explicit approval authorizes work. In 3.1, the daily runtime is the `.scrumrun/` folder: the agent creates or refines the relevant Task Markdown, works in code, and leaves a short handoff. Feature, Sprint, and Run are optional context, not prerequisites. A structured CLI audit path remains available when a team wants it.
+Explicit approval authorizes work. In 4.0, the daily runtime is the `.scrumrun/` folder: the agent creates or refines the relevant Task Markdown, works in code, and leaves a short handoff. Feature, Sprint, and Run are optional context, not prerequisites. A structured CLI audit path remains available only at maintenance/release edges.
 
 ```text
 EXECUTING → VALIDATING → LEARNING → COMPLETED | FAILED | BLOCKED
 ```
 
-Every Task carries `## Acceptance Criteria` so "done" is defined before work begins. After approval, the agent works directly in code and Task Markdown, updating `## Technical Summary` and `## Follow-ups`. The normal close is simply the documented Task handoff — no CLI transition is required.
+Every Task carries a short `## Done when` delivery contract. After approval, the agent works directly in code and Task Markdown until that contract is delivered: it keeps the full discover → implement → verify → fix → verify loop running. A report is allowed only when you ask for it and never ends execution. The normal close is a concise `## Completion`; `## Follow-ups` may only contain work outside the agreed contract. No CLI transition is required.
 
-Guardrails still apply. An agent stops only for an explicit active Guardrail, a secret/security risk, destructive work without approval, or an unmet required Acceptance Criterion. Tests, reviews, and environments are gates only when the owner, Acceptance Criteria, or a Guardrail explicitly requires them. Optional missing E2E coverage is a follow-up/risk, not a failed Task.
+**Opt-in Task-schema validator.** Adding `task_schema: 1` to a Task's frontmatter turns on the structural checks in `lib/v2/task-schema.js`: `## Request` + `## Done when` are required, `## Completion` (or an associated Run's `## Technical Summary`) is required once the Task is `completed`, and inside a git repo the Task must record its `branch` while executing. `scrumrun doctor --strict` and `scrumrun review artifact --run --strict` promote these to blocking errors; without `--strict` they are warnings. Legacy Tasks without `task_schema` are unaffected.
+
+Guardrails still apply. An agent stops only for an explicit active Guardrail, a secret/security risk, destructive work without approval, or an unmet required delivery criterion. Tests, reviews, and environments are gates only when the owner, `Done when`, or a Guardrail explicitly requires them. Optional missing E2E coverage is a follow-up/risk, not a failed Task.
 
 Use the CLI at the edges, where its safety is valuable:
 
@@ -99,6 +130,10 @@ scrumrun repair --recover-orphan-tasks --apply
 scrumrun review release --run
 ```
 
+`core.md` and `guardrails.md` are sealed Markdown policy. Agents never edit them during normal product work. An owner-requested policy change is reviewed and then sealed explicitly with `scrumrun update --project --seal-policy`; `doctor --strict` and release checks detect later policy drift.
+
+Relations are plain, offline Markdown: stable IDs in frontmatter (`sprint: SPRINT-012`, `depends_on: [TASK-014, DEC-018]`) and relative links in `## Related`. Task Markdown is intentionally extensible: a Guardrail can require `## Migration Plan`, `## Rollback`, or `## Guardrail Evidence` only where relevant, and ScrumRun preserves every unknown section.
+
 `update --project` refreshes packaged `core.md` and recognized generated `AGENTS.md` with a local byte-exact backup before replacing them. The CLI can still generate/validate Task, Feature, Sprint, and Run records when desired, but it must never become a routine blocker.
 
 For extra protection, CLI Task start/retry and every Run state transition require `--strict`. This prevents accidental administrative failures in the normal Markdown-first workflow.
@@ -144,6 +179,22 @@ The fast graph/search layer is `.scrumrun/.cache/semantic-index.sqlite`. It is i
 
 `map.md` is shown only when its source fingerprint matches the current semantic index. A fresh placeholder or stale map is rejected with an explicit rebuild instruction instead of being presented as project truth.
 
+For local projects that benefit from always-fresh projections, opt into the lightweight watcher in `.scrumrun/config.md` and start it once:
+
+```yaml
+watcher.enabled: true
+watcher.debounce_ms: 250
+watcher.poll_interval_ms: 1500
+```
+
+```bash
+scrumrun config watch --start
+scrumrun config watch --status
+scrumrun config watch --stop
+```
+
+The watcher uses native `fs.watch` where recursive watching is available and polling otherwise. It is never authority or a work gate: a later on-demand rebuild always remains correct if it stops. The daemon records its PID in `.scrumrun/.cache/watcher.pid`, ignores the vault, `.cache/contexts/`, and its own generated outputs, coalesces rapid writes, and writes only `state.md`, `map.md`, and `.cache/`.
+
 ## Project briefing
 
 `state.md` is the **briefing**: a bounded summary an agent reads first, before touching anything else.
@@ -161,12 +212,18 @@ It is progressive disclosure: the briefing is enough for most work; the agent fo
 
 ## Migrating an ongoing v1 project
 
-Update the client integrations. For an existing project, refresh the Markdown-first guidance explicitly:
+Update the client integrations. For an existing project, refresh the execution-first guidance explicitly:
 
 ```bash
 scrumrun update --project
 ```
 
+If you intentionally changed project Guardrails after owner review, seal the reviewed Markdown policy once:
+
+```bash
+scrumrun update --project --seal-policy
+```
+
 This shows the source inventory, proposed mappings, and blockers without changing project data. Apply only the verified plan with:
 
 ```bash

package/SPEC.md

@@ -83,6 +83,8 @@ method: 2.0.0
 
 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.
 
+Relationship lists are valid local frontmatter, for example `depends_on: [TASK-014, DEC-018]` and `guardrails: [GR-004]`. Human-readable `## Related` links use relative Markdown paths. These local IDs and links are the canonical graph; generated indexes only accelerate retrieval.
+
 A Task may carry an optional `assignee` scalar recording the agent identity (`SCRUMRUN_AGENT` or `config.md` `Agent Identity`) that owns the work. It is descriptive metadata, never a competing authority: it does not change status transitions or block conformance.
 
 ### 3.2 Stable identifiers
@@ -200,13 +202,15 @@ RECEIVED
 
 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, canonical context fingerprint, and complete workspace fingerprint. Canonical or source drift after planning invalidates approval.
 
-Approval authorizes work after the read-only planning pass. In Markdown-first mode, a Task and optional Run may be created or updated directly; their absence or imperfect administrative metadata never prevents approved work. The CLI's atomic Task/Run creation remains an optional strict/audit path. Tests, reviews, and environments are completion gates only when explicitly required by the owner, the Task's Acceptance Criteria, or an active Guardrail; missing optional coverage is a documented follow-up/risk, not a failure by itself.
+Approval authorizes work after the read-only planning pass. In Markdown-first mode, a Task and optional Run may be created or updated directly; their absence or imperfect administrative metadata never prevents approved work. The CLI's atomic Task/Run creation remains an optional strict/audit path. Tests, reviews, and environments are completion gates only when explicitly required by the owner, the Task's `## Done when` contract, or an active Guardrail; missing optional coverage is a documented follow-up/risk, not a failure by itself.
+
+An approved Task executes continuously to its delivery contract. An agent must not end a work turn merely to provide inventory, decomposition, progress, or a list of remaining implementation work. Those are internal execution steps. It may stop only for an owner decision, external access, an active Guardrail, secret/security risk, destructive work without approval, or an unmet required contract item. `## Follow-ups` may contain only work outside `## Done when`; moving required work there requires explicit owner approval.
 
 When a structured Run is explicitly chosen, it binds the exact Guardrail-policy fingerprint and workspace baseline. Strict audit then verifies the complete delta: policy freshness, read-only boundaries, symlink safety, scannability, newly introduced secret-like content, and evidence for every Guardrail. Strict teams may opt into short-lived, path-scoped permits and per-edit recording. This audit path is never a prerequisite for ordinary Markdown-first execution.
 
-The agent may assert the classification explicitly (`--type fix|task|feature|docs|discovery`), overriding keyword inference with validation and a stable reason. It may attach a short technical preview (`--preview`), rendered in the terminal, bound into the approval token, and stored as `## Preview` on the approved Task. A Task declares its `## Acceptance Criteria` before execution; completion is measured against them, never against elapsed time or token budget.
+The agent may assert the classification explicitly (`--type fix|task|feature|docs|discovery`), overriding keyword inference with validation and a stable reason. It may attach a short technical preview (`--preview`), rendered in the terminal, bound into the approval token, and stored as `## Preview` on the approved Task. A Task normally declares a concise `## Done when` contract before execution, but owner-defined Markdown sections remain valid; completion is measured against the agreed delivery contract, never against elapsed time or token budget.
 
-When a structured Run is used, CLI transitions synchronously update the linked Task and append one event to its ledger. This is an optional audit path, not daily operational authority. Markdown-first completion records the Acceptance Criteria, Technical Summary, validation evidence, and Follow-ups directly on the Task. Multi-file CLI mutations use a durable local transaction journal; `doctor --recover` and `repair` remain explicit maintenance operations. Entering learning may extract candidates, but no administrative artifact failure blocks approved work.
+When a structured Run is used, CLI transitions synchronously update the linked Task and append one event to its ledger. This is an optional audit path, not daily operational authority. Markdown-first completion records the Done when contract, Completion, validation evidence, and Follow-ups directly on the Task. Multi-file CLI mutations use a durable local transaction journal; `doctor --recover` and `repair` remain explicit maintenance operations. Entering learning may extract candidates, but no administrative artifact failure blocks approved work.
 
 Backlog is a queue view of intentionally parked Tasks, ordered oldest-first by id. CLI `--next`/`--start` helpers may create a structured Run when wanted, but an explicit owner approval is the only daily-work start gate.
 
@@ -230,6 +234,37 @@ Secret-like content detection is canonical-policy-level and applies to every art
 
 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.
 
+### 6.1 Declarative Guardrail enforcement
+
+A Guardrail may add one optional fenced `yaml enforcement` block. It is parsed without an LLM and evaluated as a pure function over a ChangeSet (`paths`, `diff`, and optional `symbols`); ordinary prose-only Guardrails remain valid. The supported YAML subset is intentionally limited to mappings and string lists so every installed client evaluates the same rule without a network dependency.
+
+````markdown
+## GR-010 - No debug logs in production code
+
+Status: active
+Enforcement: manual
+Scope: validation, commit
+Rule: Production changes must not add debug logging.
+
+```yaml enforcement
+match:
+  paths:
+    - "src/**/*.js"
+  diff:
+    - "/\\bconsole\\.log\\s*\\(/"
+  symbols:
+    - "debug*"
+on_violation: block
+severity: high
+evidence:
+  - "Remove debug output or justify it in the reviewed policy."
+```
+````
+
+`match.paths` accepts globs (`src/**`), extensions (`.ts` or `ext:.ts`), and regexes (`regex:^src/` or `/^src\\//`). `match.diff` accepts regexes (recommended) or literal fragments; `match.symbols` uses the same glob/regex form. At least one matcher is required. `on_violation` is `block` or `warn`; `severity` is `low`, `medium`, `high`, or `critical`; `evidence` is an optional scalar or string list surfaced with a match. Invalid blocks are a conformance error with `SR-E-153`.
+
+The declared action is authoritative. `config.md` may promote a warning to a block through `Guardrail On Violation: block`; it may never downgrade an explicit block. `scrumrun review artifact --run` evaluates the worktree, `--staged` evaluates the index, and `doctor --strict` consumes the same evaluator. The optional offline pre-commit template is `templates/shared/hooks/pre-commit`.
+
 ## 7. Semantic memory and code intelligence
 
 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.

package/bin/scrumrun.js

@@ -35,10 +35,13 @@ const { addPlanArtifact, amendPlanArtifact, approveRequest, finalizeRun, nextBac
 const { authorizeMutation, recordMutation, satisfyGuardrail } = require(path.join(root, "lib", "runtime", "mutation-gateway"));
 const { recordArtifactReview } = require(path.join(root, "lib", "runtime", "review-service"));
 const { createMemory, listMemory, showMemory, transitionMemory } = require(path.join(root, "lib", "memory", "service"));
+const { applyCompaction, proposedClusters, rollbackCompaction } = require(path.join(root, "lib", "memory", "compaction"));
 const { indexPath, indexStatus, mapStatus, queryIndex, rebuildIndex, writeMap } = require(path.join(root, "lib", "memory", "index"));
 const { auditProject } = require(path.join(root, "lib", "v2", "conformance"));
 const { recoverPendingTransactions, previewPendingRecovery } = require(path.join(root, "lib", "v2", "transaction"));
 const { containsSecret } = require(path.join(root, "lib", "security", "secrets"));
+const { sealPolicyIntegrity } = require(path.join(root, "lib", "runtime", "policy-integrity"));
+const { readStatus: watcherStatus, startWatcher, stopWatcher } = require(path.join(root, "lib", "runtime", "watcher"));
 
 const COMMANDS = ["sc"];
 const COMPATIBILITY_COMMANDS = Object.keys(COMMAND_ALIASES);
@@ -58,7 +61,7 @@ Usage:
   scrumrun <noun> <subject> <action> [args]
   scrumrun sc <noun> <subject> <action> [args]  # compatibility alias
   scrumrun install [all|codex|opencode|claude] [--force]
-  scrumrun update  [all|codex|opencode|claude] [--project] [--migrate] [--verbose]
+  scrumrun update  [all|codex|opencode|claude] [--project] [--seal-policy] [--migrate] [--verbose]
   scrumrun init [--local|--shared] [--lean] [--no-agent-hint] [--force]
   scrumrun status
   scrumrun core [--path|--prompt]
@@ -67,6 +70,7 @@ Usage:
   scrumrun migrate --to 2 --apply
   scrumrun migrate --to 2 --rollback
   scrumrun doctor [all|codex|opencode|claude] [--strict] [--recover]
+  scrumrun config watch --start|--stop|--status  # optional generated-projection daemon; never a gate
   scrumrun repair [--recover-orphan-tasks] [--apply]
   scrumrun uninstall [--force]
 
@@ -218,11 +222,16 @@ function cleanupLegacy(commandsDir, skillsDir) {
       }
     }
   }
-  const oldSkill = path.join(skillsDir, "ai-scrum");
-  if (fs.existsSync(oldSkill)) {
-    fs.rmSync(oldSkill, { recursive: true, force: true });
-    installSummary.cleaned += 1;
-    installLog(`  rm legacy ${oldSkill}`);
+  if (fs.existsSync(skillsDir)) {
+    const legacySkillNames = new Set(["ai-scrum", ...COMPATIBILITY_COMMANDS]);
+    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      if (!legacySkillNames.has(entry.name)) continue;
+      const target = path.join(skillsDir, entry.name);
+      fs.rmSync(target, { recursive: true, force: true });
+      installSummary.cleaned += 1;
+      installLog(`  rm legacy ${target}`);
+    }
   }
 }
 
@@ -380,10 +389,16 @@ function refreshProjectGuidance(cwd = process.cwd()) {
   } else {
     results.push({ status: "skipped", dest: `${agentsFile} (not recognized as ScrumRun-generated)` });
   }
+  const marker = path.join(cwd, ".scrumrun", "method.json");
+  const sealed = writeFile(marker, sealPolicyIntegrity(path.join(cwd, ".scrumrun")), { backup: true });
+  results.push({ status: sealed.changed ? "updated" : "skipped", dest: marker, backup: sealed.backup });
+  const viewFile = path.join(cwd, ".scrumrun", "view.html");
+  const viewResult = writeFile(viewFile, fs.readFileSync(path.join(templates, "shared", "view.html"), "utf8"), { backup: true });
+  results.push({ status: viewResult.changed ? "updated" : "skipped", dest: viewFile, backup: viewResult.backup });
   return results;
 }
 
-function updateInstallation(target, { migrate = false, project = false, verbose = false } = {}) {
+function updateInstallation(target, { migrate = false, project = false, sealPolicy = false, verbose = false } = {}) {
   installVerbose = verbose;
   installSummary.cleaned = 0;
   installSummary.written = 0;
@@ -391,7 +406,14 @@ function updateInstallation(target, { migrate = false, project = false, verbose
   installSummary.targets.length = 0;
   const migration = migrate ? migrationPreflightOnUpdate({ apply: true }) : { status: "skipped" };
   install(target, true, { compatibility: true });
+  if (sealPolicy && !project) throw new Error("`--seal-policy` requires `--project` so the owner-reviewed project policy is explicit.");
   const projectResults = project ? refreshProjectGuidance() : [];
+  if (sealPolicy && project) {
+    const scrumDir = path.join(process.cwd(), ".scrumrun");
+    const marker = path.join(scrumDir, "method.json");
+    const sealed = writeFile(marker, sealPolicyIntegrity(scrumDir, { includeGuardrails: true }), { backup: true });
+    projectResults.push({ status: sealed.changed ? "updated" : "skipped", dest: marker, backup: sealed.backup });
+  }
   if (migrate && v2Project()) {
     try {
       refreshState(path.join(process.cwd(), ".scrumrun"));
@@ -1361,6 +1383,25 @@ function printMemoryArtifact(artifact) {
 function runV2Memory(subject, args) {
   const kind = subject === "fact" ? "knowledge" : subject;
   const action = args[0];
+  if (kind === "dossier" && action === "--compact") {
+    if (args.includes("--dry-run")) {
+      const preview = proposedClusters(process.cwd());
+      console.log(JSON.stringify({ mode: "dry-run", ...preview }, null, 2));
+      return;
+    }
+    if (args.includes("--apply")) {
+      const result = applyCompaction(process.cwd(), { approved: args.includes("--approve") });
+      console.log(JSON.stringify({ mode: "apply", ...result }, null, 2));
+      return;
+    }
+    if (args.includes("--rollback")) {
+      const dossier = args[args.indexOf("--rollback") + 1];
+      if (!dossier || dossier.startsWith("--")) throw new Error("--rollback requires a DOS-NNN id.");
+      console.log(JSON.stringify(rollbackCompaction(process.cwd(), dossier), null, 2));
+      return;
+    }
+    throw new Error("Usage: scrumrun knowledge dossier --compact --dry-run|--apply --approve|--rollback DOS-NNN");
+  }
   const createAction = kind === "insight" ? "--propose" : "--add";
   if (action === createAction) {
     const artifact = createMemory(process.cwd(), kind, memoryOptions(args));
@@ -1680,7 +1721,7 @@ function executeRootRoute(route) {
   if (noun === "knowledge" && subject === "vault") return runVault(routeArgs);
   if (noun === "knowledge" && subject === "context") return runContext(routeArgs);
   if (noun === "review" && subject === "artifact" && routeArgs[0] === "--run") {
-    const audit = auditProject(process.cwd());
+    const audit = auditProject(process.cwd(), { staged: routeArgs.includes("--staged"), strict: routeArgs.includes("--strict") });
     console.log(JSON.stringify(audit, null, 2));
     if (!audit.passed) process.exitCode = 1;
     return;
@@ -1704,9 +1745,23 @@ function executeRootRoute(route) {
     const target = ["all", "codex", "opencode", "claude"].includes(routeArgs[0]) ? routeArgs[0] : "all";
     return doctor(target, { strict: routeArgs.includes("--strict"), recover: routeArgs.includes("--recover"), dryRun: routeArgs.includes("--dry-run") });
   }
+  if (noun === "config" && subject === "watch") {
+    let result;
+    if (routeArgs[0] === "--start") result = startWatcher(process.cwd());
+    else if (routeArgs[0] === "--stop") result = stopWatcher(process.cwd());
+    else if (routeArgs[0] === "--status") result = watcherStatus(process.cwd());
+    else throw new Error("Usage: scrumrun config watch --start|--stop|--status");
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
   if (noun === "config" && subject === "update") {
     const target = ["all", "codex", "opencode", "claude"].includes(routeArgs[0]) ? routeArgs[0] : "all";
-    return updateInstallation(target, { migrate: !routeArgs.includes("--no-migrate"), verbose: routeArgs.includes("--verbose") });
+    return updateInstallation(target, {
+      migrate: routeArgs.includes("--migrate"),
+      project: routeArgs.includes("--project"),
+      sealPolicy: routeArgs.includes("--seal-policy"),
+      verbose: routeArgs.includes("--verbose")
+    });
   }
   if (noun === "config" && subject === "init") {
     const localMode = routeArgs.includes("--local");
@@ -2322,6 +2377,8 @@ function promptCommand(parts) {
 
 function initProject({ force, mode, agentHint, lean }) {
   const cwd = process.cwd();
+  const marker = path.join(cwd, ".scrumrun", "method.json");
+  const markerExisted = fs.existsSync(marker);
   const vars = {
     PROJECT_NAME: path.basename(cwd),
     DATE: new Date().toISOString().slice(0, 10)
@@ -2332,6 +2389,11 @@ function initProject({ force, mode, agentHint, lean }) {
 
   results.push(...copyDir(path.join(projectTemplate, ".scrumrun"), path.join(cwd, ".scrumrun"), { force, vars }));
   results.push(copyFile(path.join(root, "CORE.md"), path.join(cwd, ".scrumrun", "core.md"), { force, vars }));
+  results.push(copyFile(path.join(templates, "shared", "view.html"), path.join(cwd, ".scrumrun", "view.html"), { force }));
+  if (force || !markerExisted) {
+    const sealed = writeFile(marker, sealPolicyIntegrity(path.join(cwd, ".scrumrun"), { includeGuardrails: true }), { backup: false });
+    results.push({ status: sealed.changed ? "written" : "skipped", dest: marker, backup: sealed.backup });
+  }
   results.push(ensureProjectIgnore(cwd));
 
   if (mode === "shared" || agentHint) {
@@ -2610,9 +2672,10 @@ function doctor(target = "all", { compatibility = false, strict = false, recover
       ok = false;
       console.log(`miss ScrumRun project audit: ${scrumDir}`);
     } else {
-      const audit = auditProject(process.cwd());
-      ok = ok && audit.passed && audit.findings.length === 0;
-      console.log(`${audit.passed && audit.findings.length === 0 ? "ok " : "fail"} ScrumRun project audit: ${audit.findings.length} finding(s)`);
+      const audit = auditProject(process.cwd(), { strict: true });
+      const blocking = audit.findings.filter((item) => ["critical", "high"].includes(item.severity));
+      ok = ok && audit.passed && blocking.length === 0;
+      console.log(`${audit.passed && blocking.length === 0 ? "ok " : "fail"} ScrumRun project audit: ${audit.findings.length} finding(s)`);
       for (const item of audit.findings) console.log(`  ${item.severity} ${item.code}: ${item.message}`);
     }
   }
@@ -2633,12 +2696,38 @@ if (!command || command === "--help" || command === "-h") {
   console.log(`ScrumRun ${version}`);
 } else if (command === "install" || command === "update") {
   const target = ["all", "codex", "opencode", "claude"].includes(args[1]) ? args[1] : "all";
-  if (command === "update") updateInstallation(target, { migrate: args.includes("--migrate"), project: args.includes("--project"), verbose: args.includes("--verbose") });
+  if (command === "update") updateInstallation(target, { migrate: args.includes("--migrate"), project: args.includes("--project"), sealPolicy: args.includes("--seal-policy"), verbose: args.includes("--verbose") });
   else install(target, true, { compatibility: false });
 } else if (command === "sc") {
   runRoot(args.slice(1));
 } else if (["plan", "knowledge", "rules", "review", "config"].includes(command)) {
   runRoot(args);
+} else if (command === "action") {
+  const { executeAction, listActions } = require(path.join(root, "lib", "actions"));
+  try {
+    const name = args[1];
+    if (!name || name === "--list") {
+      console.log("Available actions:");
+      for (const item of listActions()) console.log(`  ${item.name.padEnd(30)} ${item.describe}`);
+      process.exit(0);
+    }
+    const rest = args.slice(2);
+    let payload = {};
+    const payloadFlag = rest.indexOf("--payload");
+    const fileFlag = rest.indexOf("--file");
+    if (payloadFlag !== -1) {
+      payload = JSON.parse(rest[payloadFlag + 1] || "{}");
+    } else if (fileFlag !== -1) {
+      payload = JSON.parse(fs.readFileSync(rest[fileFlag + 1], "utf8"));
+    } else if (rest.includes("--stdin")) {
+      payload = JSON.parse(fs.readFileSync(0, "utf8"));
+    }
+    const result = executeAction(name, process.cwd(), payload);
+    console.log(JSON.stringify(result, null, 2));
+  } catch (error) {
+    console.error(`action failed: ${error.message}`);
+    process.exitCode = 1;
+  }
 } else if (COMMAND_ALIASES[command]) {
   runCompatibilityAlias(command, args.slice(1));
 } else if (command === "init") {

package/docs/COMMANDS.md

@@ -1,4 +1,4 @@
-# ScrumRun 3.1 Command Reference
+# ScrumRun 4.0 Command Reference
 
 The canonical grammar is:
 
@@ -27,13 +27,13 @@ scrumrun plan run --satisfy-guardrail RUN-NNN --guardrail GR-NNN [typed evidence
 scrumrun plan challenge <question>
 ```
 
-Normal execution is Markdown-first: after approval, work in code and the relevant Task Markdown, then record the Technical Summary and any Follow-ups directly. A Run/`--finalize` checkpoint is optional strict audit, never a prerequisite. Mutation permits are available only for explicitly requested strict mode.
+Normal execution is Markdown-first: after approval, work in code and the relevant Task Markdown through discover → implement → verify → fix → verify, then record `## Completion` and any genuinely out-of-scope Follow-ups directly. A Run/`--finalize` checkpoint is optional strict audit, never a prerequisite. Mutation permits are available only for explicitly requested strict mode.
 
 The CLI refuses Task start/retry and all Run state changes unless `--strict` is present. This prevents an agent from accidentally manufacturing a failed/blocked retry during normal work; `--strict` is for an owner-requested audit only.
 
 `--amend` is an optional structured helper. The Markdown-first workflow may adjust Task/Feature/Sprint content directly, preserving a useful handoff. Use the CLI when atomic relation synchronization or machine audit is valuable; do not let status vocabulary or missing relations stop approved work.
 
-Every new Task starts with a `## Validation Scope`: only checks explicitly required by the owner, Acceptance Criteria, or an active Guardrail block completion. Missing optional E2E, integration, or review coverage belongs in a follow-up/risk note; it must not be used to mark the Run failed.
+Every new Task starts with `## Done when` and `## Validation Scope`: only checks explicitly required by the owner, Done when contract, or an active Guardrail block completion. A discovered in-scope gap remains work to implement, not a status report or Follow-up. Missing optional E2E, integration, or review coverage belongs in a follow-up/risk note; it must not be used to mark the Run failed.
 
 ## What can be changed
 
@@ -69,28 +69,38 @@ Creation options include `--title`, `--content`, repeated `--evidence`, repeated
 scrumrun rules guardrail --add|--list|--show|--retire
 scrumrun rules reviewer --add|--list|--show|--run
 scrumrun review code --run
-scrumrun review artifact --run
+scrumrun review artifact --run [--staged]
 scrumrun review artifact --record --task TASK-NNN [--run RUN-NNN] [--title "..."] [--evidence "..."]
 scrumrun review migration --run
 scrumrun review release --run
 ```
 
-`review artifact --run` is read-only and returns a machine-readable 21-invariant project audit. `--record` reruns that audit and persists its exact pass/fail result as a canonical `REV-NNN`; supplied evidence is additive and cannot turn a failed audit into a pass. Other review routes require repository reasoning and remain read-only unless fixes receive separate approval.
+`review artifact --run` is read-only and returns a machine-readable project audit, including declarative Guardrail matches against the current Git worktree. `--staged` evaluates the Git index, for the optional pre-commit hook. `--record` reruns that audit and persists its exact pass/fail result as a canonical `REV-NNN`; supplied evidence is additive and cannot turn a failed audit into a pass. Other review routes require repository reasoning and remain read-only unless fixes receive separate approval.
+
+To install the optional offline hook locally:
+
+```bash
+cp node_modules/scrumrun/templates/shared/hooks/pre-commit .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```
 
 ## Config and lifecycle
 
 ```text
 scrumrun config project --show|--language|--interaction|--approval|--quick-tasks
 scrumrun config init --local|--shared|--lean|--no-agent-hint|--force
-scrumrun config update [all|codex|opencode|claude] [--project] [--migrate]
+scrumrun config update [all|codex|opencode|claude] [--project] [--seal-policy] [--migrate]
 scrumrun config migrate --to 2 --dry-run|--apply|--rollback
 scrumrun config doctor [all|codex|opencode|claude] [--strict] [--recover]
+scrumrun config watch --start|--stop|--status
 scrumrun config uninstall --force
 scrumrun config help <topic>
 ```
 
-Top-level CLI aliases (`init`, `update`, `migrate`, `doctor`, `uninstall`, `status`) remain available for shell automation. `update --project` refreshes the packaged Markdown-first Core and recognized generated agent instructions with local backup; ordinary update does not inspect migrations, while `--migrate` explicitly does so and applies the verified plan.
+Top-level CLI aliases (`init`, `update`, `migrate`, `doctor`, `uninstall`, `status`) remain available for shell automation. `update --project` refreshes the packaged execution-first Core and recognized generated agent instructions with local backup. `update --project --seal-policy` is the owner-reviewed maintenance action that pins fresh Core/Guardrail fingerprints. Ordinary update does not inspect migrations, while `--migrate` explicitly does so and applies the verified plan.
 
 Run transitions accept typed evidence through `--command`, `--test`, `--file`, `--review`, `--decision`, `--insight`, `--risk`, or generic `--evidence kind:value`. `doctor --recover` is an explicit write that resolves only safe pending kernel transactions; doctor without it remains read-only.
 
 Run `scrumrun commands` for grammar rendered directly from the current manifest.
+
+`watch` is an optional convenience, never a gate or authority. Set `watcher.enabled: true` in `.scrumrun/config.md`, then use `--start`. It records its liveness PID at `.scrumrun/.cache/watcher.pid`; `--stop` shuts that daemon down. Native recursive `fs.watch` is used where supported; otherwise the daemon falls back to portable polling. It ignores `vault.local.md`, `.cache/contexts/`, its own generated outputs, and writes only generated `state.md`, `map.md`, and `.cache/semantic-index.sqlite`.