scrumrun 2.4.1 → 2.5.1

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 2.5.1 - 2026-07-23
+
+### Fixed
+
+- `doctor` no longer crashes on Runs with a null `task` reference. `conformance.js` now guards `repository.read("task", …)` and emits a specific `RUN_TASK_MISSING` finding when `record.task` is `null`, differentiating it from the "task exists but is invalid" case. Affects any project normalized with `sc plan run --normalize-legacy` where the original Run had an unparseable task ref.
+
+## 2.5.0 - 2026-07-23
+
+### Added
+
+- `sc plan run --normalize-legacy [--dry-run]` collapses malformed Run ledgers (invalid `type`, unknown evidence `kind`, missing snapshot invariant, unparseable `task` reference, empty ledger) into a single valid `snapshot` event that preserves the fact of the Run without inventing transitions. Byte-exact originals are moved to `.scrumrun/.migration-backup/runs/RUN-NNN.md` (numbered suffix if a backup already exists). Coherent with ADR-021: ambiguous history becomes evidence, never invented state.
+- Invariant **I-24**: canonical Runs must pass ledger validation. Hand-written Runs surface as a `high` `RUN_WRITE_BYPASS` finding in `doctor --strict`, with a pointer to the recovery command.
+- New module `lib/commands/normalize-legacy` exposes `normalizeLegacyRuns`, `analyze`, `apply`, `renderReport`, `needsNormalization`, and `scanRuns` for library consumers.
+- CORE and the shared SKILL now open with a hard instruction: **never write Run events by hand**. Only the CLI mutates `runs/*.md`. Direct writes produce invalid vocabulary and break conformance; if the CLI does not expose the shape you need, propose a spec change instead of inventing.
+
+### Changed
+
+- Manifest declares `--normalize-legacy` and `--dry-run` on `sc plan run`.
+- SPEC.md conformance range extended to `I-01 through I-24`.
+- Test suite grew from 184 to 192 passing.
+
 ## 2.4.1 - 2026-07-23
 
 ### Added

package/CORE.md

@@ -84,6 +84,8 @@ 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/`.
 
+**Never write Run events by hand.** Runs are only mutated through the CLI: `sc plan run --validate | --learn | --complete | --resume | --fail | --block | --satisfy-guardrail | --authorize-mutation | --record-mutation`. Editing `runs/RUN-NNN.md` directly bypasses schema validation, produces invalid ledger events (invalid `type`, unknown evidence `kind`, missing snapshot, wrong `from`), and breaks conformance for the entire project. If the CLI does not expose the shape you need, propose a spec change through an ADR — do not invent event vocabulary. Existing hand-written Runs can be recovered with `sc plan run --normalize-legacy` (byte-exact original preserved in `.scrumrun/.migration-backup/runs/`).
+
 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.
 
 `state.md` and the semantic index use two-tier freshness checks. Matching path/stat watch fingerprints avoid rereading unchanged sources; any metadata drift falls back to complete content hashing. A cache schema mismatch rebuilds the disposable index once. Watch metadata is only an optimization and never authority.

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:** `2.4.1` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `2.5.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).
 

package/SPEC.md

@@ -310,6 +310,7 @@ Legacy sprint entries become Tasks. History entries become Runs only with an evi
 - **I-21** Material mutations are policy-bound, path-scoped, hash-verified, append-only, and fail closed on bypass; unresolved Guardrail obligations block completion.
 - **I-22** The semantic index's declared search backend must match the runtime capabilities of the current Node.js SQLite build; conformance flags a mismatch instead of relying on lazy runtime fallback.
 - **I-23** `method.json` declares the canonical path index for every artifact family so agents navigate by declaration, not by search. Missing or drifted paths fail conformance; grep and directory scans are fallbacks, never the first step.
+- **I-24** Runs are only mutated through the CLI. A canonical Run whose ledger fails validation is a bypass — conformance reports `RUN_WRITE_BYPASS` with a pointer to the recovery command `sc plan run --normalize-legacy`, which collapses the bad ledger into a single `snapshot` event and preserves the byte-exact original under `.scrumrun/.migration-backup/runs/`.
 
 ## 11. Command grammar
 
@@ -327,7 +328,7 @@ Unknown syntax fails deterministically and never guesses a mutation.
 
 An implementation may claim ScrumRun method 2.0.0 only when it:
 
-1. passes positive and negative tests for I-01 through I-23;
+1. passes positive and negative tests for I-01 through I-24;
 2. enforces every exposed state machine and schema;
 3. proves read-only intake and dry-run migration through full-tree fingerprints;
 4. proves migration failure recovery, rollback safety, and vault exclusion;

package/bin/scrumrun.js

@@ -1386,6 +1386,27 @@ function executeRootRoute(route) {
     }
     return;
   }
+  if (noun === "plan" && subject === "run" && routeArgs[0] === "--normalize-legacy") {
+    const { normalizeLegacyRuns, renderReport } = require(path.join(root, "lib", "commands", "normalize-legacy"));
+    const dryRun = routeArgs.includes("--dry-run");
+    const scrumDir = path.join(process.cwd(), ".scrumrun");
+    try {
+      const result = normalizeLegacyRuns(scrumDir, { dryRun });
+      console.log(renderReport(result.plan, result.applied));
+      if (!dryRun && result.applied && result.applied.length) {
+        refreshState(scrumDir);
+        console.log(`\nNormalized ${result.applied.length} Run(s). Byte-exact originals live under .scrumrun/.migration-backup/runs/.`);
+      } else if (dryRun && result.plan.malformed) {
+        console.log(`\nDry-run only. Re-run without --dry-run to apply the plan.`);
+      } else if (!result.plan.malformed) {
+        console.log(`\nEvery Run already conforms to the current ledger schema. Nothing to normalize.`);
+      }
+    } catch (error) {
+      console.error(error.message);
+      process.exitCode = 1;
+    }
+    return;
+  }
   if (noun === "plan" && subject === "run" && routeArgs[0] === "--stats") {
     const { computeStats, renderStats } = require(path.join(root, "lib", "commands", "run-stats"));
     const filters = {

package/lib/commands/manifest.js

@@ -14,6 +14,7 @@ const nouns = Object.freeze({
         "--show",
         "--render <RUN-NNN>",
         "--stats [--task <TASK-NNN>] [--feature <FEAT-NNN>] [--sprint <SPRINT-NNN>] [--json]",
+        "--normalize-legacy [--dry-run]",
         "--authorize-mutation <RUN-NNN> --path <relative-path>",
         "--record-mutation <RUN-NNN> --permit <MUT-id> [--note] [--actor]",
         "--satisfy-guardrail <RUN-NNN> --guardrail <GR-NNN> [--note] [--evidence] [--review] [--migration] [--actor]",

package/lib/commands/normalize-legacy.js

@@ -0,0 +1,214 @@
+"use strict";
+
+// `sc plan run --normalize-legacy [--dry-run]`
+//
+// Reads every Run under `.scrumrun/runs/` and validates its ledger
+// against the current schema. When a Run fails validation (invalid
+// event type, unknown evidence kind, missing snapshot, bad transition,
+// empty ledger, etc.), the whole ledger is collapsed into a single
+// snapshot event that preserves the fact of the Run without inventing
+// transitions. The original body is preserved byte-exact under
+// `.scrumrun/.migration-backup/runs/RUN-NNN.md` (append `.NN` when a
+// backup already exists so history is never overwritten).
+//
+// This is coherent with ADR-021: ambiguous history becomes evidence,
+// never invented transitions.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+const { parseRunLedger, validateRunLedger, renderRunEvent } = require("../runtime/run-ledger");
+const { RUN_LEDGER_VERSION } = require("../v2/schema");
+
+const RUN_FILENAME_PATTERN = /^RUN-\d{3,}\.md$/;
+const TASK_REF_PATTERN = /^TASK-\d{3,}$/;
+
+function readFrontmatterAndBody(text) {
+  const match = String(text || "").match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, header: "", body: String(text || "") };
+  const header = match[1];
+  const body = match[2] || "";
+  const frontmatter = {};
+  for (const line of header.split(/\r?\n/)) {
+    const kv = line.match(/^([a-z_][a-z0-9_]*):\s*(.*)$/i);
+    if (!kv) continue;
+    let value = kv[2].trim();
+    if (value === "null" || value === "") value = null;
+    else if (/^-?\d+$/.test(value)) value = Number(value);
+    frontmatter[kv[1]] = value;
+  }
+  return { frontmatter, header, body };
+}
+
+function extractTitle(body, fallback) {
+  const match = String(body || "").match(/^# ([^\r\n]+)$/m);
+  return match ? match[1] : fallback;
+}
+
+function serializeFrontmatter(frontmatter) {
+  const lines = Object.entries(frontmatter).map(([key, value]) => {
+    if (value === null || value === undefined) return `${key}: null`;
+    return `${key}: ${value}`;
+  });
+  return `---\n${lines.join("\n")}\n---`;
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function reserveBackupPath(backupDir, runId) {
+  ensureDir(backupDir);
+  const base = path.join(backupDir, `${runId}.md`);
+  if (!fs.existsSync(base)) return base;
+  for (let n = 1; n <= 99; n++) {
+    const candidate = path.join(backupDir, `${runId}.md.${String(n).padStart(2, "0")}`);
+    if (!fs.existsSync(candidate)) return candidate;
+  }
+  throw new Error(`Cannot reserve backup slot for ${runId}: 100 backups already exist.`);
+}
+
+function needsNormalization(record, body) {
+  if (!record) return { needs: true, reason: "frontmatter is malformed or missing" };
+  if (typeof record.task === "string" && record.task && !TASK_REF_PATTERN.test(record.task)) {
+    return { needs: true, reason: `task field does not match TASK-NNN (was ${JSON.stringify(record.task)})` };
+  }
+  const result = validateRunLedger(record, body);
+  const errors = result.errors || [];
+  if (errors.length) return { needs: true, reason: `ledger validation failed (${errors.length} error${errors.length === 1 ? "" : "s"})`, errors };
+  return { needs: false };
+}
+
+function buildNormalizedBody({ record, originalBody, backupRelative, reason, errors }) {
+  const title = extractTitle(originalBody, `Run ${record.id}`);
+  const sha = crypto.createHash("sha256").update(originalBody).digest("hex");
+  const normalizedRecord = {
+    id: record.id,
+    kind: "run",
+    status: record.status || "partial",
+    created: record.created,
+    updated: new Date().toISOString().slice(0, 10),
+    method: "2.0.0",
+    task: TASK_REF_PATTERN.test(record.task || "") ? record.task : null,
+    sprint: record.sprint || null,
+    attempt: record.attempt || 1,
+    ledger: RUN_LEDGER_VERSION
+  };
+  const evidence = [
+    { kind: "legacy", ref: backupRelative, summary: `byte-exact original preserved (sha256:${sha.slice(0, 12)}…)` },
+    { kind: "note", summary: reason }
+  ];
+  if (errors && errors.length) {
+    const sampled = errors.slice(0, 5).map((error) => `- ${error}`).join("; ");
+    evidence.push({ kind: "note", summary: `Pre-normalization validation errors: ${sampled}${errors.length > 5 ? `; +${errors.length - 5} more` : ""}` });
+  }
+  const event = {
+    schema: RUN_LEDGER_VERSION,
+    id: `${record.id}-EVT-001`,
+    sequence: 1,
+    type: "snapshot",
+    occurred_at: `${normalizedRecord.created || normalizedRecord.updated}T00:00:00.000Z`,
+    timestamp_precision: "date",
+    actor: "migration",
+    from: null,
+    to: normalizedRecord.status,
+    reason: `Legacy Run ledger normalized to preserve history without inventing canonical transitions. See ${backupRelative}.`,
+    evidence
+  };
+  const front = serializeFrontmatter(normalizedRecord);
+  const bodyText = `# ${title}\n\n## Events\n\n${renderRunEvent(event)}\n`;
+  return `${front}\n\n${bodyText}`;
+}
+
+function scanRuns(scrumDir) {
+  const runsDir = path.join(scrumDir, "runs");
+  if (!fs.existsSync(runsDir) || !fs.lstatSync(runsDir).isDirectory()) return [];
+  return fs
+    .readdirSync(runsDir)
+    .filter((name) => RUN_FILENAME_PATTERN.test(name))
+    .sort()
+    .map((name) => path.join(runsDir, name));
+}
+
+function analyze(scrumDir) {
+  const plan = { runs: [], safe: 0, malformed: 0 };
+  for (const file of scanRuns(scrumDir)) {
+    const raw = fs.readFileSync(file, "utf8");
+    const { frontmatter } = readFrontmatterAndBody(raw);
+    const check = needsNormalization(frontmatter, raw);
+    plan.runs.push({ id: frontmatter.id || path.basename(file, ".md"), file, needs: check.needs, reason: check.reason || "ledger validates", errors: check.errors || [] });
+    if (check.needs) plan.malformed += 1;
+    else plan.safe += 1;
+  }
+  return plan;
+}
+
+function apply(scrumDir, plan) {
+  const backupDir = path.join(scrumDir, ".migration-backup", "runs");
+  const applied = [];
+  for (const entry of plan.runs) {
+    if (!entry.needs) continue;
+    const raw = fs.readFileSync(entry.file, "utf8");
+    const { frontmatter } = readFrontmatterAndBody(raw);
+    const backupPath = reserveBackupPath(backupDir, entry.id);
+    fs.writeFileSync(backupPath, raw);
+    const backupRelative = path.relative(scrumDir, backupPath);
+    const normalized = buildNormalizedBody({
+      record: frontmatter,
+      originalBody: raw,
+      backupRelative,
+      reason: entry.reason,
+      errors: entry.errors
+    });
+    fs.writeFileSync(entry.file, normalized);
+    applied.push({ id: entry.id, backup: backupRelative, reason: entry.reason });
+  }
+  return applied;
+}
+
+function renderReport(plan, applied) {
+  const lines = [];
+  lines.push("## Run ledger normalization plan");
+  lines.push("");
+  lines.push(`Runs scanned:      ${plan.runs.length}`);
+  lines.push(`Already valid:     ${plan.safe}`);
+  lines.push(`Needs normalize:   ${plan.malformed}`);
+  if (plan.malformed) {
+    lines.push("");
+    lines.push("Malformed Runs:");
+    for (const entry of plan.runs) {
+      if (!entry.needs) continue;
+      lines.push(`  - ${entry.id}: ${entry.reason}`);
+    }
+  }
+  if (applied) {
+    lines.push("");
+    lines.push("Applied:");
+    if (!applied.length) lines.push("  (no changes)");
+    for (const entry of applied) {
+      lines.push(`  - ${entry.id} → normalized (backup ${entry.backup})`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function normalizeLegacyRuns(scrumDir, { dryRun = false } = {}) {
+  if (!fs.existsSync(scrumDir) || !fs.lstatSync(scrumDir).isDirectory()) {
+    throw new Error(".scrumrun/ not found; run this inside a ScrumRun project.");
+  }
+  const plan = analyze(scrumDir);
+  if (dryRun) return { plan, applied: null };
+  const applied = apply(scrumDir, plan);
+  return { plan, applied };
+}
+
+module.exports = {
+  normalizeLegacyRuns,
+  analyze,
+  apply,
+  renderReport,
+  buildNormalizedBody,
+  needsNormalization,
+  scanRuns
+};

package/lib/v2/conformance.js

@@ -38,7 +38,8 @@ const INVARIANTS = Object.freeze([
   { id: "I-20", summary: "learning candidates never block execution", tests: ["post-validation extraction creates candidate insights"] },
   { id: "I-21", summary: "material mutations are scoped, policy-bound, and fail closed", tests: ["Mutation Gateway rejects bypass and out-of-scope writes", "Run completion rejects unresolved Guardrail obligations"] },
   { id: "I-22", summary: "declared search backend matches observed runtime capabilities", tests: ["conformance detects a semantic index that declares fts5 when the runtime does not provide it"] },
-  { id: "I-23", summary: "method.json declares canonical paths so agents navigate by index, not by search", tests: ["method.json path index is present, well-formed, and matches the canonical layout"] }
+  { id: "I-23", summary: "method.json declares canonical paths so agents navigate by index, not by search", tests: ["method.json path index is present, well-formed, and matches the canonical layout"] },
+  { id: "I-24", summary: "every canonical Run passes ledger validation; hand-written events surface as bypass findings", tests: ["conformance flags Run write bypass when the ledger uses invalid vocabulary or misses the snapshot invariant"] }
 ]);
 
 function finding(severity, code, message, file = null) {
@@ -132,14 +133,28 @@ function auditProject(projectRoot) {
     }
   }
   for (const run of records.run || []) {
-    const task = run.record ? repository.read("task", run.record.task) : null;
-    if (run.record && (!task || task.errors.length)) findings.push(finding("high", "RUN_TASK_MISSING", `${run.record.id} references missing or invalid ${run.record.task}.`, run.file));
+    let task = null;
+    if (run.record && run.record.task) {
+      try {
+        task = repository.read("task", run.record.task);
+      } catch (error) {
+        task = null;
+      }
+    }
+    if (run.record && !run.record.task) {
+      findings.push(finding("high", "RUN_TASK_MISSING", `${run.record.id} has no task reference (record.task is null).`, run.file));
+    } else if (run.record && (!task || task.errors.length)) {
+      findings.push(finding("high", "RUN_TASK_MISSING", `${run.record.id} references missing or invalid ${run.record.task}.`, run.file));
+    }
     if (run.record && task && !task.errors.length && (run.record.sprint || null) !== (task.record.sprint || null)) {
       findings.push(finding("high", "RUN_SPRINT_MISMATCH", `${run.record.id}.sprint must match ${task.record.id}.sprint.`, run.file));
     }
     if (run.record && run.record.ledger === RUN_LEDGER_VERSION) {
       const ledger = validateRunLedger(run.record, run.body);
-      for (const error of ledger.errors) findings.push(finding("high", "RUN_LEDGER_INVALID", `${run.record.id}: ${error}`, run.file));
+      if (ledger.errors.length) {
+        findings.push(finding("high", "RUN_WRITE_BYPASS", `${run.record.id}: ledger has ${ledger.errors.length} validation error(s); this Run was likely written without going through the CLI. Recover with \`sc plan run --normalize-legacy --dry-run\` then re-run without --dry-run.`, run.file));
+        for (const error of ledger.errors) findings.push(finding("high", "RUN_LEDGER_INVALID", `${run.record.id}: ${error}`, run.file));
+      }
     } else if (run.record) {
       const declared = methodMarker && methodMarker.schemas && methodMarker.schemas.run_ledger === RUN_LEDGER_VERSION;
       findings.push(finding(declared ? "high" : "warning", "RUN_LEDGER_LEGACY", `${run.record.id} requires the Run ledger ${RUN_LEDGER_VERSION} migration.`, run.file));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrumrun",
-  "version": "2.4.1",
+  "version": "2.5.1",
   "description": "Evidence-driven Agile runtime and semantic project memory for AI coding agents.",
   "bin": {
     "scrumrun": "bin/scrumrun.js",

package/templates/shared/skills/scrumrun/SKILL.md

@@ -36,6 +36,8 @@ Normal hot path:
 5. follow the ids/pointers to only the relevant canonical artifacts;
 6. load `.scrumrun/core.md` when the method contract or an exceptional transition is needed.
 
+**Never write Run events by hand.** Only the CLI mutates `runs/RUN-NNN.md`: `sc plan run --validate | --learn | --complete | --resume | --fail | --block | --satisfy-guardrail | --authorize-mutation | --record-mutation`. Direct edits produce invalid ledger events (unknown `type` like `execution`/`validation`/`learning`, unknown evidence `kind` like `guardrail-check`/`build`/`task-status`, missing snapshot invariant) and break project conformance. If the CLI does not expose the shape you need, propose a spec change instead of inventing vocabulary. Recover hand-written Runs via `sc plan run --normalize-legacy` — originals are preserved byte-exact under `.scrumrun/.migration-backup/runs/`.
+
 Lean mode is a read policy, not an incomplete store. Generated files and `.scrumrun/.cache/` are never authoritative.
 
 Generated state and semantic indexes use a metadata-watch fast path with a full content-hash fallback. Treat cache-schema mismatch as a request to rebuild the disposable projection, never as permission to rewrite canonical Markdown.