scrumrun 2.6.6 → 2.6.8

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.6.6` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `2.6.8` · **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/lib/commands/normalize-legacy.js

@@ -83,12 +83,13 @@ function needsNormalization(record, body) {
 function buildNormalizedBody({ record, originalBody, backupRelative, reason, errors }) {
   const title = extractTitle(originalBody, `Run ${record.id}`);
   const sha = crypto.createHash("sha256").update(originalBody).digest("hex");
+  const snapshotDate = record.created || new Date().toISOString().slice(0, 10);
   const normalizedRecord = {
     id: record.id,
     kind: "run",
     status: record.status || "partial",
     created: record.created,
-    updated: new Date().toISOString().slice(0, 10),
+    updated: snapshotDate,
     method: "2.0.0",
     task: TASK_REF_PATTERN.test(record.task || "") ? record.task : null,
     sprint: record.sprint || null,
@@ -108,7 +109,7 @@ function buildNormalizedBody({ record, originalBody, backupRelative, reason, err
     id: `${record.id}-EVT-001`,
     sequence: 1,
     type: "snapshot",
-    occurred_at: `${normalizedRecord.created || normalizedRecord.updated}T00:00:00.000Z`,
+    occurred_at: `${snapshotDate}T00:00:00.000Z`,
     timestamp_precision: "date",
     actor: "migration",
     from: null,

package/lib/commands/repair.js

@@ -26,6 +26,8 @@
 const fs = require("node:fs");
 const path = require("node:path");
 
+const { normalizeLegacyRuns } = require("./normalize-legacy");
+
 const TASK_FILE = /^TASK-\d{3,}\.md$/;
 const RUN_FILE = /^RUN-\d{3,}\.md$/;
 const FEAT_FILE = /^FEAT-\d{3,}\.md$/;
@@ -49,6 +51,8 @@ const RUN_STATUS_ALIAS = {
   done: "completed"
 };
 
+const GUARDRAIL_SCOPES = new Set(["all", "intake", "execution", "mutation", "canonical", "memory", "migration", "validation", "learning", "completion", "commit", "release", "logs"]);
+
 function readIf(file) {
   try {
     return fs.readFileSync(file, "utf8");
@@ -98,6 +102,29 @@ function scanFeatureIds(scrumDir) {
   return ids;
 }
 
+function scanTaskIds(scrumDir) {
+  const dir = path.join(scrumDir, "tasks");
+  const ids = new Set();
+  for (const file of listDir(dir, TASK_FILE)) {
+    ids.add(path.basename(file, ".md"));
+  }
+  return ids;
+}
+
+function planOrphanRuns(scrumDir, taskIds) {
+  const orphans = [];
+  for (const file of listDir(path.join(scrumDir, "runs"), RUN_FILE)) {
+    const raw = readIf(file);
+    if (raw === null) continue;
+    const split = splitFrontmatter(raw);
+    if (!split) continue;
+    const taskRef = extractField(split.header, "task");
+    if (taskRef && taskRef !== "null" && TASK_REF.test(taskRef) && taskIds.has(taskRef)) continue;
+    orphans.push({ file, reason: taskRef ? `task ${taskRef} is null or missing from .scrumrun/tasks/` : "task field missing", originalText: raw });
+  }
+  return orphans;
+}
+
 function planFile(file, kind, ctx) {
   const original = readIf(file);
   if (original === null) return null;
@@ -161,7 +188,15 @@ function planFile(file, kind, ctx) {
 
   if (kind === "run") {
     const taskRef = extractField(header, "task");
-    if (taskRef !== undefined && taskRef !== "null" && taskRef !== null && taskRef !== "" && !TASK_REF.test(taskRef)) {
+    if (taskRef === undefined) {
+      if (hasField(header, "id")) {
+        const next = insertFieldAfter(header, "id", "task", "null");
+        if (next !== header) {
+          changes.push({ field: "task", from: "(missing)", to: "null" });
+          header = next;
+        }
+      }
+    } else if (taskRef !== "null" && taskRef !== null && taskRef !== "" && !TASK_REF.test(taskRef)) {
       const next = replaceField(header, "task", "null");
       if (next !== header) {
         changes.push({ field: "task", from: taskRef, to: "null" });
@@ -191,10 +226,33 @@ function planFile(file, kind, ctx) {
   return { file, kind, changes, nextText, originalText: original };
 }
 
+function planGuardrails(scrumDir) {
+  const file = path.join(scrumDir, "guardrails.md");
+  const original = readIf(file);
+  if (original === null) return null;
+  const changes = [];
+  let text = original;
+  const scopeRe = /^(\s*scope:\s*)([^\n\r]+)$/gim;
+  text = text.replace(scopeRe, (match, prefix, value) => {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed === "null") return match;
+    if (GUARDRAIL_SCOPES.has(trimmed)) return match;
+    changes.push({ field: "scope", from: trimmed, to: "all" });
+    return `${prefix}all`;
+  });
+  if (!changes.length) return null;
+  return { file, kind: "guardrails", changes, nextText: text, originalText: original };
+}
+
 function analyze(scrumDir) {
   const featureIds = scanFeatureIds(scrumDir);
+  const taskIds = scanTaskIds(scrumDir);
   const ctx = { featureIds };
   const entries = [];
+  const orphanRuns = planOrphanRuns(scrumDir, taskIds);
+
+  const guardrailPlan = planGuardrails(scrumDir);
+  if (guardrailPlan) entries.push(guardrailPlan);
 
   for (const file of listDir(path.join(scrumDir, "tasks"), TASK_FILE)) {
     const plan = planFile(file, "task", ctx);
@@ -225,7 +283,7 @@ function analyze(scrumDir) {
       totals.byField[change.field] = (totals.byField[change.field] || 0) + 1;
     }
   }
-  return { entries, totals };
+  return { entries, totals, orphanRuns };
 }
 
 function apply(scrumDir, plan) {
@@ -240,13 +298,33 @@ function apply(scrumDir, plan) {
     fs.writeFileSync(entry.file, entry.nextText);
     applied.push({ file: relative, backup: path.relative(scrumDir, backupPath), changes: entry.changes });
   }
-  return applied;
+  // Also normalize legacy Run ledgers (empty/broken) — same safety guarantee: byte-exact backup.
+  let ledgerResult = null;
+  try {
+    ledgerResult = normalizeLegacyRuns(scrumDir, { dryRun: false });
+  } catch {
+    ledgerResult = { plan: { malformed: 0 }, applied: [] };
+  }
+  // Quarantine orphan Runs (Task ref missing/invalid — schema requires TASK-NNN). Move byte-exact
+  // to backup so nothing is deleted; the orphan can be manually re-linked or discarded later.
+  const orphanBackup = path.join(scrumDir, ".migration-backup", "repair", "orphan-runs");
+  const quarantined = [];
+  for (const orphan of plan.orphanRuns || []) {
+    fs.mkdirSync(orphanBackup, { recursive: true });
+    const target = path.join(orphanBackup, path.basename(orphan.file));
+    if (!fs.existsSync(target)) fs.writeFileSync(target, orphan.originalText);
+    fs.rmSync(orphan.file, { force: true });
+    quarantined.push({ id: path.basename(orphan.file, ".md"), reason: orphan.reason, backup: path.relative(scrumDir, target) });
+  }
+  return { applied, ledger: ledgerResult, quarantined };
 }
 
 function renderReport(plan, applied) {
   const lines = [];
   lines.push("## Repair plan\n");
-  lines.push(`Files needing repair: ${plan.entries.length}`);
+  lines.push(`Files needing frontmatter repair: ${plan.entries.length}`);
+  if (plan.ledgerMalformed) lines.push(`Run ledgers to normalize:        ${plan.ledgerMalformed}`);
+  if (plan.orphanRuns && plan.orphanRuns.length) lines.push(`Orphan Runs to quarantine:       ${plan.orphanRuns.length}`);
   const byField = plan.totals.byField;
   if (Object.keys(byField).length) {
     lines.push("\nBy field:");
@@ -264,7 +342,17 @@ function renderReport(plan, applied) {
   }
   if (applied) {
     lines.push("");
-    lines.push(applied.length ? `Applied: ${applied.length} file(s) rewritten. Backups under .scrumrun/.migration-backup/repair/.` : "Applied: no changes.");
+    const frontmatterCount = applied.applied ? applied.applied.length : 0;
+    const ledgerCount = applied.ledger && applied.ledger.applied ? applied.ledger.applied.length : 0;
+    const quarantinedCount = applied.quarantined ? applied.quarantined.length : 0;
+    if (frontmatterCount || ledgerCount || quarantinedCount) {
+      if (frontmatterCount) lines.push(`Applied: ${frontmatterCount} frontmatter file(s) rewritten.`);
+      if (ledgerCount) lines.push(`Normalized: ${ledgerCount} Run ledger(s) collapsed to snapshot events.`);
+      if (quarantinedCount) lines.push(`Quarantined: ${quarantinedCount} orphan Run(s) moved to .scrumrun/.migration-backup/repair/orphan-runs/.`);
+      lines.push("Backups under .scrumrun/.migration-backup/repair/ and .scrumrun/.migration-backup/runs/.");
+    } else {
+      lines.push("Applied: no changes.");
+    }
   } else {
     lines.push("");
     lines.push("The project remains unchanged. Apply with: scrumrun repair --apply");
@@ -277,8 +365,16 @@ function repair(scrumDir, { apply: doApply = false } = {}) {
     throw new Error(".scrumrun/ not found; run this inside a ScrumRun project.");
   }
   const plan = analyze(scrumDir);
+  let ledgerPreview = null;
+  try {
+    ledgerPreview = normalizeLegacyRuns(scrumDir, { dryRun: true }).plan;
+  } catch {
+    ledgerPreview = null;
+  }
+  plan.ledgerMalformed = ledgerPreview ? ledgerPreview.malformed : 0;
   if (!doApply) return { plan, applied: null, report: renderReport(plan, null) };
   const applied = apply(scrumDir, plan);
+  plan.ledgerNormalized = applied.ledger && applied.ledger.applied ? applied.ledger.applied.length : 0;
   return { plan, applied, report: renderReport(plan, applied) };
 }
 

package/package.json

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