scrumrun 2.6.7 → 2.6.9

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

@@ -102,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;
@@ -164,6 +187,23 @@ function planFile(file, kind, ctx) {
   }
 
   if (kind === "run") {
+    // Reconcile `updated` with the last event's occurred_at date. Fixes Runs
+    // normalized by an older CLI that stamped `updated: today` instead of
+    // matching the snapshot event, which produced the "Run updated date
+    // disagrees with final event timestamp" migration blocker.
+    const currentUpdated = extractField(header, "updated");
+    const eventDates = [...split.body.matchAll(/"occurred_at":\s*"(\d{4}-\d{2}-\d{2})/g)].map((m) => m[1]);
+    if (eventDates.length && currentUpdated && ISO_DATE.test(currentUpdated)) {
+      const lastEventDate = eventDates[eventDates.length - 1];
+      if (currentUpdated !== lastEventDate) {
+        const next = replaceField(header, "updated", lastEventDate);
+        if (next !== header) {
+          changes.push({ field: "updated", from: currentUpdated, to: lastEventDate });
+          header = next;
+        }
+      }
+    }
+
     const taskRef = extractField(header, "task");
     if (taskRef === undefined) {
       if (hasField(header, "id")) {
@@ -223,8 +263,10 @@ function planGuardrails(scrumDir) {
 
 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);
@@ -258,7 +300,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) {
@@ -280,7 +322,18 @@ function apply(scrumDir, plan) {
   } catch {
     ledgerResult = { plan: { malformed: 0 }, applied: [] };
   }
-  return { applied, ledger: ledgerResult };
+  // 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) {
@@ -288,6 +341,7 @@ function renderReport(plan, applied) {
   lines.push("## Repair plan\n");
   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:");
@@ -307,9 +361,11 @@ function renderReport(plan, applied) {
     lines.push("");
     const frontmatterCount = applied.applied ? applied.applied.length : 0;
     const ledgerCount = applied.ledger && applied.ledger.applied ? applied.ledger.applied.length : 0;
-    if (frontmatterCount || ledgerCount) {
+    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.");

package/package.json

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