scrumrun 2.6.2 → 2.6.3

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

@@ -61,6 +61,7 @@ Usage:
   scrumrun migrate --to 2 --apply
   scrumrun migrate --to 2 --rollback
   scrumrun doctor [all|codex|opencode|claude] [--strict] [--recover]
+  scrumrun repair [--apply]
   scrumrun uninstall [--force]
 
 Install:
@@ -2512,6 +2513,18 @@ if (!command || command === "--help" || command === "-h") {
   } else {
     initProject({ force, mode: shared ? "shared" : "local", agentHint: shared || !noAgentHint, lean });
   }
+} else if (command === "repair") {
+  const scrumDir = path.join(process.cwd(), ".scrumrun");
+  try {
+    const { repair } = require(path.join(root, "lib", "commands", "repair"));
+    const doApply = args.includes("--apply");
+    const result = repair(scrumDir, { apply: doApply });
+    console.log(result.report);
+    if (!doApply && result.plan.entries.length) process.exitCode = 0;
+  } catch (error) {
+    console.error(`repair failed: ${error.message}`);
+    process.exitCode = 1;
+  }
 } else if (command === "uninstall") {
   uninstallProject(force);
 } else if (command === "status") {

package/lib/commands/repair.js

@@ -0,0 +1,228 @@
+"use strict";
+
+// `scrumrun repair [--apply|--dry-run]`
+//
+// Applies safe, mechanical normalizations to a v2 project that has drifted
+// through hand-writing outside the CLI. Only touches categories where the
+// fix is provably deterministic and does not invent data:
+//
+//   1. task.feature: kebab-case slug that does not resolve to a FEAT-NNN → null.
+//      (broken reference; safer to nullify than to fabricate.)
+//   2. task.status alias mapping: done→completed, todo→backlog,
+//      complete→completed, in_progress→executing.
+//   3. frontmatter method field: any value that isn't "2.0.0" → "2.0.0".
+//   4. run.attempt missing → 1 (documented default).
+//
+// Categories intentionally NOT touched (need human judgment):
+//   - Secret-like content (SECRET_CANONICAL)
+//   - Missing Acceptance Criteria sections
+//   - Guardrail scope/enforcement (authored semantics)
+//   - Task/Run status disagreements (requires domain knowledge)
+//   - Empty Run ledgers (use `sc plan run --normalize-legacy`)
+//
+// Every mutated file is backed up byte-exact under
+// `.scrumrun/.migration-backup/repair/<relative-path>` before being rewritten.
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const TASK_FILE = /^TASK-\d{3,}\.md$/;
+const RUN_FILE = /^RUN-\d{3,}\.md$/;
+const FEAT_FILE = /^FEAT-\d{3,}\.md$/;
+const FEAT_REF = /^FEAT-\d{3,}$/;
+const SLUG_REF = /^[a-z0-9][a-z0-9-]*$/;
+
+const STATUS_ALIAS = {
+  done: "completed",
+  todo: "backlog",
+  complete: "completed",
+  in_progress: "executing"
+};
+
+function readIf(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function listDir(dir, pattern) {
+  if (!fs.existsSync(dir) || !fs.lstatSync(dir).isDirectory()) return [];
+  return fs.readdirSync(dir).filter((name) => pattern.test(name)).sort().map((name) => path.join(dir, name));
+}
+
+function splitFrontmatter(text) {
+  const match = String(text || "").match(/^---\r?\n([\s\S]*?)\r?\n---(\r?\n)?([\s\S]*)$/);
+  if (!match) return null;
+  return { header: match[1], sep: match[2] || "\n", body: match[3] || "" };
+}
+
+function extractField(header, field) {
+  const re = new RegExp(`^${field}:\\s*(.*)$`, "im");
+  const match = header.match(re);
+  return match ? match[1].trim() : undefined;
+}
+
+function replaceField(header, field, newValue) {
+  const re = new RegExp(`^(${field}:\\s*)(.*)$`, "im");
+  return header.replace(re, `$1${newValue}`);
+}
+
+function hasField(header, field) {
+  const re = new RegExp(`^${field}:\\s`, "im");
+  return re.test(header);
+}
+
+function insertFieldAfter(header, afterField, field, value) {
+  const re = new RegExp(`^(${afterField}:.*)$`, "im");
+  return header.replace(re, `$1\n${field}: ${value}`);
+}
+
+function scanFeatureIds(scrumDir) {
+  const dir = path.join(scrumDir, "features");
+  const ids = new Set();
+  for (const file of listDir(dir, FEAT_FILE)) {
+    ids.add(path.basename(file, ".md"));
+  }
+  return ids;
+}
+
+function planFile(file, kind, ctx) {
+  const original = readIf(file);
+  if (original === null) return null;
+  const split = splitFrontmatter(original);
+  if (!split) return null;
+
+  let header = split.header;
+  const changes = [];
+
+  const method = extractField(header, "method");
+  if (method !== undefined && method !== "2.0.0" && method !== "null") {
+    const next = replaceField(header, "method", "2.0.0");
+    if (next !== header) {
+      changes.push({ field: "method", from: method, to: "2.0.0" });
+      header = next;
+    }
+  }
+
+  if (kind === "task") {
+    const feature = extractField(header, "feature");
+    if (feature !== undefined && feature !== "null" && feature !== null && feature !== "") {
+      if (!FEAT_REF.test(feature) && SLUG_REF.test(feature) && !ctx.featureIds.has(feature)) {
+        const next = replaceField(header, "feature", "null");
+        if (next !== header) {
+          changes.push({ field: "feature", from: feature, to: "null" });
+          header = next;
+        }
+      }
+    }
+
+    const status = extractField(header, "status");
+    if (status && STATUS_ALIAS[status]) {
+      const next = replaceField(header, "status", STATUS_ALIAS[status]);
+      if (next !== header) {
+        changes.push({ field: "status", from: status, to: STATUS_ALIAS[status] });
+        header = next;
+      }
+    }
+  }
+
+  if (kind === "run") {
+    if (!hasField(header, "attempt") && hasField(header, "task")) {
+      const next = insertFieldAfter(header, "task", "attempt", "1");
+      if (next !== header) {
+        changes.push({ field: "attempt", from: "(missing)", to: "1" });
+        header = next;
+      }
+    }
+  }
+
+  if (!changes.length) return { file, kind, changes: [], nextText: original };
+
+  const nextText = `---\n${header}\n---${split.sep}${split.body}`;
+  return { file, kind, changes, nextText, originalText: original };
+}
+
+function analyze(scrumDir) {
+  const featureIds = scanFeatureIds(scrumDir);
+  const ctx = { featureIds };
+  const entries = [];
+
+  for (const file of listDir(path.join(scrumDir, "tasks"), TASK_FILE)) {
+    const plan = planFile(file, "task", ctx);
+    if (plan && plan.changes.length) entries.push(plan);
+  }
+  for (const file of listDir(path.join(scrumDir, "runs"), RUN_FILE)) {
+    const plan = planFile(file, "run", ctx);
+    if (plan && plan.changes.length) entries.push(plan);
+  }
+  for (const file of listDir(path.join(scrumDir, "features"), FEAT_FILE)) {
+    const plan = planFile(file, "feature", ctx);
+    if (plan && plan.changes.length) entries.push(plan);
+  }
+
+  const totals = { files: entries.length, byField: {} };
+  for (const entry of entries) {
+    for (const change of entry.changes) {
+      totals.byField[change.field] = (totals.byField[change.field] || 0) + 1;
+    }
+  }
+  return { entries, totals };
+}
+
+function apply(scrumDir, plan) {
+  const backupRoot = path.join(scrumDir, ".migration-backup", "repair");
+  fs.mkdirSync(backupRoot, { recursive: true });
+  const applied = [];
+  for (const entry of plan.entries) {
+    const relative = path.relative(scrumDir, entry.file);
+    const backupPath = path.join(backupRoot, relative);
+    fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+    if (!fs.existsSync(backupPath)) fs.writeFileSync(backupPath, entry.originalText);
+    fs.writeFileSync(entry.file, entry.nextText);
+    applied.push({ file: relative, backup: path.relative(scrumDir, backupPath), changes: entry.changes });
+  }
+  return applied;
+}
+
+function renderReport(plan, applied) {
+  const lines = [];
+  lines.push("## Repair plan\n");
+  lines.push(`Files needing repair: ${plan.entries.length}`);
+  const byField = plan.totals.byField;
+  if (Object.keys(byField).length) {
+    lines.push("\nBy field:");
+    for (const [field, count] of Object.entries(byField)) {
+      lines.push(`  - ${field}: ${count}`);
+    }
+  }
+  if (plan.entries.length) {
+    lines.push("\nDetails (up to 30 files shown):");
+    for (const entry of plan.entries.slice(0, 30)) {
+      const summary = entry.changes.map((c) => `${c.field}: ${c.from} → ${c.to}`).join("; ");
+      lines.push(`  - ${path.basename(entry.file)}: ${summary}`);
+    }
+    if (plan.entries.length > 30) lines.push(`  … and ${plan.entries.length - 30} more`);
+  }
+  if (applied) {
+    lines.push("");
+    lines.push(applied.length ? `Applied: ${applied.length} file(s) rewritten. Backups under .scrumrun/.migration-backup/repair/.` : "Applied: no changes.");
+  } else {
+    lines.push("");
+    lines.push("The project remains unchanged. Apply with: scrumrun repair --apply");
+  }
+  return lines.join("\n");
+}
+
+function repair(scrumDir, { apply: doApply = 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 (!doApply) return { plan, applied: null, report: renderReport(plan, null) };
+  const applied = apply(scrumDir, plan);
+  return { plan, applied, report: renderReport(plan, applied) };
+}
+
+module.exports = { repair, analyze, apply, renderReport };

package/package.json

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