scrumrun 4.0.0 → 4.1.1

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 4.1.1 - 2026-09-22
+
+### Added
+
+- **`scrumrun update --repair-legacy`.** New flag runs `repair --apply` after refreshing project guidance, so a single `scrumrun update --project --repair-legacy` upgrades the CLI, refreshes packaged Markdown, and normalizes the local `.scrumrun/` tree in one shot. The repair pass covers status aliases, `feature:` free-text kebab labels, guardrail scopes, missing frontmatter, orphaned Runs/Tasks, and legacy Sprint projections — never touches secrets (they always require human review).
+
+### Changed
+
+- **Broader status aliases in `scrumrun repair`.** `TASK_STATUS_ALIAS` now maps `pending`, `planned`, `skipped`, `canceled`, `wontdo`/`won't do`, `wip`, `doing`, `in-progress`, `review`, `reviewing`, `finished`, `closed` alongside the existing `done`/`todo`/`complete`/`in_progress`/`executing`/`active`. `RUN_STATUS_ALIAS` gains `in-progress`, `wip`, `finished`, `closed`, `canceled`/`cancelled`, `skipped`, `running`. `doctor --strict` remains strict for fresh installs; the aliases only take effect when an owner explicitly runs `repair --apply` (or `update --repair-legacy`).
+- **Guardrail scope parser tolerates parentheses and `+` separators.** `Scope: frontend + backend` and `Scope: frontend (vue templates, docs)` now parse to the intended token(s) instead of splitting on commas inside parens and producing bogus scope names. Unknown scopes still fail conformance in fresh installs — `repair` rewrites them to `all` when normalizing legacy projects.
+
+## 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

package/README.md

@@ -4,7 +4,7 @@
 
 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:** `4.0.0` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `4.1.1` · **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).
 
@@ -63,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:
@@ -90,6 +116,8 @@ EXECUTING → VALIDATING → LEARNING → COMPLETED | FAILED | BLOCKED
 
 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.
 
+**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:
@@ -151,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.

package/SPEC.md

@@ -234,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,11 +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);
@@ -59,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] [--seal-policy] [--migrate] [--verbose]
+  scrumrun update  [all|codex|opencode|claude] [--project] [--seal-policy] [--migrate] [--repair-legacy] [--verbose]
   scrumrun init [--local|--shared] [--lean] [--no-agent-hint] [--force]
   scrumrun status
   scrumrun core [--path|--prompt]
@@ -68,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]
 
@@ -219,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}`);
+    }
   }
 }
 
@@ -384,10 +392,13 @@ function refreshProjectGuidance(cwd = process.cwd()) {
   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, sealPolicy = false, verbose = false } = {}) {
+function updateInstallation(target, { migrate = false, project = false, sealPolicy = false, verbose = false, repairLegacy = false } = {}) {
   installVerbose = verbose;
   installSummary.cleaned = 0;
   installSummary.written = 0;
@@ -403,6 +414,18 @@ function updateInstallation(target, { migrate = false, project = false, sealPoli
     const sealed = writeFile(marker, sealPolicyIntegrity(scrumDir, { includeGuardrails: true }), { backup: true });
     projectResults.push({ status: sealed.changed ? "updated" : "skipped", dest: marker, backup: sealed.backup });
   }
+  let repairSummary = "";
+  if (repairLegacy && v2Project()) {
+    try {
+      const { repair } = require(path.join(root, "lib", "commands", "repair"));
+      const scrumDir = path.join(process.cwd(), ".scrumrun");
+      const result = repair(scrumDir, { apply: true, recoverOrphanTasks: true });
+      const applied = (result.plan && result.plan.entries && result.plan.entries.length) || 0;
+      repairSummary = ` Legacy repair: ${applied} entry(ies) normalized.`;
+    } catch (error) {
+      repairSummary = ` Legacy repair skipped: ${error.message}.`;
+    }
+  }
   if (migrate && v2Project()) {
     try {
       refreshState(path.join(process.cwd(), ".scrumrun"));
@@ -414,7 +437,7 @@ function updateInstallation(target, { migrate = false, project = false, sealPoli
   if (!verbose) {
     const targetSummary = installSummary.targets.join(", ") || "no clients";
     const projectSummary = projectResults.length ? ` Project guidance: ${projectResults.filter((item) => item.status === "updated").length} file(s) refreshed.` : "";
-    console.log(`Updated ${targetSummary} — ${installSummary.written} files written, ${installSummary.cleaned} legacy removed.${projectSummary} Run with --verbose to see file paths.`);
+    console.log(`Updated ${targetSummary} — ${installSummary.written} files written, ${installSummary.cleaned} legacy removed.${projectSummary}${repairSummary} Run with --verbose to see file paths.`);
   }
   return migration;
 }
@@ -1372,6 +1395,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));
@@ -1691,7 +1733,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;
@@ -1715,6 +1757,15 @@ 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, {
@@ -2350,6 +2401,7 @@ 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 });
@@ -2632,7 +2684,7 @@ function doctor(target = "all", { compatibility = false, strict = false, recover
       ok = false;
       console.log(`miss ScrumRun project audit: ${scrumDir}`);
     } else {
-      const audit = auditProject(process.cwd());
+      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)`);
@@ -2656,12 +2708,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"), sealPolicy: args.includes("--seal-policy"), 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"), repairLegacy: args.includes("--repair-legacy") });
   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

@@ -69,13 +69,20 @@ 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
 
@@ -85,6 +92,7 @@ scrumrun config init --local|--shared|--lean|--no-agent-hint|--force
 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>
 ```
@@ -94,3 +102,5 @@ Top-level CLI aliases (`init`, `update`, `migrate`, `doctor`, `uninstall`, `stat
 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`.

package/docs/ERROR-CODES.md

@@ -77,6 +77,7 @@ SR-E-102 Run transition rejected: missing validation or learning evidence.
 | `SR-E-150` | Guardrail check blocked the operation. | Read the reported GR-NNN, satisfy or retire it explicitly; guardrails never bypass silently. |
 | `SR-E-151` | Guardrail obligation is still pending. | Resolve each pending guardrail via `scrumrun plan run --satisfy-guardrail` before completing the Run. |
 | `SR-E-152` | Guardrail declaration is malformed. | Every active guardrail requires Status, Enforcement, Scope, and Rule fields; check `.scrumrun/guardrails.md`. |
+| `SR-E-153` | Declarative Guardrail YAML is malformed. | Use the documented yaml enforcement block with match, on_violation, severity, and optional evidence. |
 
 ### Edit permits (Mutation Gateway)
 
@@ -121,6 +122,9 @@ SR-E-102 Run transition rejected: missing validation or learning evidence.
 |---|---|---|
 | `SR-E-450` | Conformance check failed. | The reported invariant identifies the exact violation; the message includes the file and expected shape. |
 | `SR-E-451` | Installed client asset is stale. | Re-run `scrumrun update` for the specific client. `doctor --strict` shows which files diverge. |
+| `SR-E-452` | Task Markdown is missing a required section. | Add the reported section (e.g. `## Request`, `## Done when`) to the Task file. The validator lives in `lib/v2/task-schema.js`. |
+| `SR-E-453` | Completed Task has no `## Completion` or associated Run `## Technical Summary`. | Append a short `## Completion` bullet list to the Task, or complete the Run with `plan run --complete --summary "..."`. |
+| `SR-E-454` | Task is running inside a git repository but no `git.branch` was captured. | Warning-only. Reconcile with `scrumrun repair --apply`, or add `git: { branch: <name>, base_sha: <sha> }` to the Task frontmatter. |
 
 ### Configuration and installation
 

package/docs/SCHEMA.md

@@ -86,6 +86,10 @@ A native ledger begins with `created → executing`; an evidenced migration `sna
 | insight | `candidate` → `confirmed`, `invalidated`<br>`confirmed` → `stale`, `deprecated`, `invalidated`<br>`stale` → `confirmed`, `deprecated`, `invalidated`<br>`deprecated` → `confirmed`<br>`invalidated` → terminal |
 | dossier | `active` → `stale`, `deprecated`, `archived`<br>`stale` → `active`, `deprecated`, `archived`<br>`deprecated` → `archived`<br>`archived` → terminal |
 
+## Declarative Guardrail enforcement
+
+Project Guardrails may include an optional fenced `yaml enforcement` block. Its restricted, dependency-free YAML schema is defined normatively in `SPEC.md §6.1`: `match.paths[]`, `match.diff[]`, `match.symbols[]`, `on_violation` (`block` or `warn`), `severity`, and optional `evidence`. The pure evaluator consumes only that normalized rule data and a supplied ChangeSet; it has no network or LLM dependency. Prose-only Guardrails remain valid.
+
 ## Projections
 
 `state.md`, `map.md`, context packages, and `.cache/` are disposable. They may summarize or index canonical artifacts, but they cannot introduce status, policy, relations, decisions, or knowledge.

package/docs/SEMANTIC-MEMORY.md

@@ -66,3 +66,31 @@ scrumrun knowledge context --clear
 ```
 
 SQLite is ignored and disposable. The derived index records its search backend: FTS5/BM25 is selected when the current Node.js SQLite build supports it; otherwise ScrumRun uses deterministic parameterized token matching over the same artifact, code, and relation tables. Queries default to 10 records/40 relations and hard-cap at 100/100. Match type, truth state, warnings, relation counts, and evidence are returned so recommendations remain explainable.
+
+## Deterministic Dossier compaction
+
+Compaction is an opt-in maintenance operation for a project with many related,
+already reviewed memory records. It never calls an LLM and never runs in the
+background:
+
+```bash
+scrumrun knowledge dossier --compact --dry-run
+scrumrun knowledge dossier --compact --apply --approve
+scrumrun knowledge dossier --compact --rollback DOS-001
+```
+
+Only approved Knowledge and confirmed Insights without `superseded_by` are
+eligible. Each record is represented by its subject, declared relations
+(including `used_by`), and explicit `#tags` or `## Tags`/`## Topics` bullets.
+Two records are connected when the Jaccard overlap of those features is at
+least `memory.compaction.threshold` (default `0.6`). Connected components with
+at least `memory.compaction.min_members` records (default `3`) become proposed
+clusters. IDs, feature sorting, links, and labels are all deterministic.
+
+Dry-run is read-only and reports member IDs, pair evidence, score and effective
+configuration. Apply additionally requires the explicit `--approve` flag: it
+creates a Dossier with original artifact IDs as evidence and adds only
+`superseded_by: DOS-NNN` to the source records. Sources are never deleted. The
+Dossier holds a reversible snapshot; rollback restores byte-exact sources only
+when they have not changed since compaction, then archives the Dossier. This
+refusal protects later owner edits rather than overwriting them.

package/lib/actions/index.js

@@ -0,0 +1,81 @@
+"use strict";
+
+const { addPlanArtifact, amendPlanArtifact } = require("../runtime/orchestrator");
+const { createMemory } = require("../memory/service");
+
+const REGISTRY = Object.freeze({
+  "plan.task.add": {
+    describe: "Create a Task (optionally as backlog or fix).",
+    handler: (projectRoot, payload) => {
+      requireString(payload, "title");
+      return addPlanArtifact(projectRoot, "task", payload.title, {
+        type: payload.type || null,
+        status: payload.status || null
+      });
+    }
+  },
+  "plan.feature.add": {
+    describe: "Create a Feature.",
+    handler: (projectRoot, payload) => {
+      requireString(payload, "title");
+      return addPlanArtifact(projectRoot, "feature", payload.title, {});
+    }
+  },
+  "plan.sprint.add": {
+    describe: "Create a Sprint.",
+    handler: (projectRoot, payload) => {
+      requireString(payload, "title");
+      return addPlanArtifact(projectRoot, "sprint", payload.title, {});
+    }
+  },
+  "plan.task.amend": {
+    describe: "Amend an existing Task's title/sections/type/feature/sprint.",
+    handler: (projectRoot, payload) => {
+      requireString(payload, "id");
+      return amendPlanArtifact(projectRoot, "task", payload.id, payload);
+    }
+  },
+  "knowledge.fact.add": {
+    describe: "Create a Knowledge (K-NNN) candidate.",
+    handler: (projectRoot, payload) => {
+      requireString(payload, "title");
+      return createMemory(projectRoot, "knowledge", payload);
+    }
+  },
+  "knowledge.decision.add": {
+    describe: "Create a Decision (DEC-NNN) candidate.",
+    handler: (projectRoot, payload) => {
+      requireString(payload, "title");
+      return createMemory(projectRoot, "decision", payload);
+    }
+  },
+  "knowledge.insight.propose": {
+    describe: "Propose an Insight (INS-NNN) candidate.",
+    handler: (projectRoot, payload) => {
+      requireString(payload, "title");
+      return createMemory(projectRoot, "insight", payload);
+    }
+  }
+});
+
+function requireString(payload, field) {
+  if (!payload || typeof payload[field] !== "string" || !payload[field].trim()) {
+    throw new Error(`payload.${field} must be a non-empty string`);
+  }
+}
+
+function listActions() {
+  return Object.entries(REGISTRY).map(([name, { describe }]) => ({ name, describe }));
+}
+
+function executeAction(name, projectRoot, payload) {
+  const entry = REGISTRY[name];
+  if (!entry) {
+    const known = Object.keys(REGISTRY).sort().join(", ");
+    throw new Error(`Unknown action "${name}". Known actions: ${known}`);
+  }
+  const normalizedPayload = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
+  return entry.handler(projectRoot, normalizedPayload);
+}
+
+module.exports = { REGISTRY, executeAction, listActions };

package/lib/commands/manifest.js

@@ -36,7 +36,7 @@ const nouns = Object.freeze({
       fact: ["--add [--title] [--content] [--evidence] [--relation] [--subject] [--source] [--source-id] [--valid-from] [--valid-until] [--review-trigger]", "--list [--include-inactive]", "--show", "--approve [--evidence] [--note]", "--reject [--note]", "--deprecate [--note]", "--invalidate [--note]"],
       decision: ["--add [--title] [--content] [--evidence] [--relation] [--subject] [--source] [--source-id] [--valid-from] [--valid-until] [--review-trigger]", "--list [--include-inactive]", "--show", "--resolve [--evidence] [--note]", "--deprecate [--note]", "--invalidate [--note]"],
       insight: ["--propose [--title] [--content] [--evidence] [--relation] [--subject] [--source] [--source-id] [--confidence] [--valid-from] [--valid-until] [--review-trigger]", "--list [--include-inactive]", "--show", "--confirm [--evidence] [--note]", "--stale [--note]", "--reject [--note]", "--deprecate [--note]", "--invalidate [--note]"],
-      dossier: ["--add [--title] [--content] [--evidence] [--relation] [--subject] [--source] [--source-id] [--valid-from] [--valid-until] [--review-trigger]", "--list [--include-inactive]", "--show", "--refresh [--evidence] [--note]", "--stale [--note]", "--deprecate [--note]", "--archive [--note]"],
+      dossier: ["--add [--title] [--content] [--evidence] [--relation] [--subject] [--source] [--source-id] [--valid-from] [--valid-until] [--review-trigger]", "--list [--include-inactive]", "--show", "--refresh [--evidence] [--note]", "--stale [--note]", "--deprecate [--note]", "--archive [--note]", "--compact --dry-run", "--compact --apply --approve", "--compact --rollback <DOS-NNN>"],
       context: ["--build", "--update", "--show", "--clear"],
       map: ["--build", "--show"],
       errors: ["--show"],
@@ -55,7 +55,7 @@ const nouns = Object.freeze({
     description: "run scoped evidence-based quality gates",
     subjects: {
       code: ["--run"],
-      artifact: ["--run", "--record --task <TASK-NNN> [--run <RUN-NNN>] [--title] [--evidence]"],
+      artifact: ["--run [--staged]", "--record --task <TASK-NNN> [--run <RUN-NNN>] [--title] [--evidence]"],
       migration: ["--run"],
       release: ["--run"]
     }
@@ -68,6 +68,7 @@ const nouns = Object.freeze({
       update: ["all [--project] [--seal-policy] [--migrate]", "codex [--project] [--seal-policy] [--migrate]", "opencode [--project] [--seal-policy] [--migrate]", "claude [--project] [--seal-policy] [--migrate]"],
       migrate: ["--to 2 --dry-run", "--to 2 --apply", "--to 2 --rollback"],
       doctor: ["all [--strict] [--recover] [--dry-run]", "codex [--strict] [--recover] [--dry-run]", "opencode [--strict] [--recover] [--dry-run]", "claude [--strict] [--recover] [--dry-run]"],
+      watch: ["--start", "--stop", "--status"],
       uninstall: ["--force"],
       help: ["<topic>"]
     }

package/lib/commands/repair.js

@@ -51,17 +51,38 @@ const VALID_RUN_STATUS = new Set(["executing", "validating", "learning", "partia
 const TASK_STATUS_ALIAS = {
   done: "completed",
   todo: "backlog",
+  pending: "backlog",
+  planned: "backlog",
   complete: "completed",
+  finished: "completed",
+  closed: "completed",
+  skipped: "cancelled",
+  canceled: "cancelled",
+  wontdo: "cancelled",
+  "won't do": "cancelled",
   in_progress: "running",
-  executing: "running",   // Task uses "running", Run uses "executing"
-  active: "running"
+  "in-progress": "running",
+  wip: "running",
+  doing: "running",
+  executing: "running",
+  active: "running",
+  review: "validating",
+  reviewing: "validating"
 };
 
 const RUN_STATUS_ALIAS = {
   complete: "completed",
   in_progress: "executing",
+  "in-progress": "executing",
+  running: "executing",
+  wip: "executing",
   done: "completed",
-  partial: "failed"
+  finished: "completed",
+  closed: "completed",
+  partial: "failed",
+  canceled: "blocked",
+  cancelled: "blocked",
+  skipped: "blocked"
 };
 
 // When syncing Task.status from latest Run.status, translate Run vocabulary

package/lib/errors.js

@@ -40,6 +40,7 @@ const CATALOG = Object.freeze({
   "SR-E-150": { summary: "Guardrail check blocked the operation.", remediation: "Read the reported GR-NNN, satisfy or retire it explicitly; guardrails never bypass silently." },
   "SR-E-151": { summary: "Guardrail obligation is still pending.", remediation: "Resolve each `pending guardrail` via `scrumrun plan run --satisfy-guardrail` before completing the Run." },
   "SR-E-152": { summary: "Guardrail declaration is malformed.", remediation: "Every active guardrail requires Status, Enforcement, Scope, and Rule fields; check .scrumrun/guardrails.md." },
+  "SR-E-153": { summary: "Declarative Guardrail YAML is malformed.", remediation: "Use the documented yaml enforcement block with match, on_violation, severity, and optional evidence." },
 
   // Edit permits (Mutation Gateway)
   "SR-E-200": { summary: "No edit permit for this path.", remediation: "Request one with `scrumrun plan run --authorize-mutation RUN-NNN --path <path>` before editing canonical or source files." },
@@ -66,6 +67,9 @@ const CATALOG = Object.freeze({
   // Conformance / doctor
   "SR-E-450": { summary: "Conformance check failed.", remediation: "The reported invariant identifies the exact violation; the message includes the file and expected shape." },
   "SR-E-451": { summary: "Installed client asset is stale.", remediation: "Re-run `scrumrun update` for the specific client. `doctor --strict` shows which files diverge." },
+  "SR-E-452": { summary: "Task Markdown is missing a required section.", remediation: "Add the reported section (e.g. `## Request`, `## Done when`) to the Task file. The validator lives in `lib/v2/task-schema.js`." },
+  "SR-E-453": { summary: "Completed Task has no `## Completion` or associated Run `## Technical Summary`.", remediation: "Append a short `## Completion` bullet list to the Task, or complete the Run with `plan run --complete --summary \"...\"`." },
+  "SR-E-454": { summary: "Task is running inside a git repository but no `git.branch` was captured.", remediation: "Warning-only. Reconcile with `scrumrun repair --apply`, or add `git: { branch: <name>, base_sha: <sha> }` to the Task frontmatter." },
 
   // Configuration / install
   "SR-E-500": { summary: "ScrumRun project not initialized.", remediation: "Run `scrumrun init` in the repository root." },