scrumrun 2.7.9 → 2.7.10

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.7.9` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `2.7.10` · **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).
 
@@ -167,6 +167,15 @@ npx scrumrun@latest migrate --to 2 --rollback
 
 Migration uses content hashes, a byte-exact ignored backup, staging validation, an atomic directory switch, a source-to-destination report, idempotent replay, and rollback protection. It also recognizes incomplete hybrid v1/v2 trees, reuses already-linked canonical work, and normalizes only deterministic schema aliases. Early v2 Run prose is preflighted and upgraded to the structured ledger by the same explicit `update --migrate` gate; ambiguous paths become evidenced snapshots instead of invented transitions. Legacy-only files leave the active tree but remain byte-exact in the ignored backup; vault contents remain local. Ambiguous history remains an explicit warning, and the migrator never invents a Sprint or Run.
 
+For projects that already have v2 directories but contain pre-v2 Markdown records without YAML frontmatter, use the explicit repair gate:
+
+```bash
+npx scrumrun@latest repair
+npx scrumrun@latest repair --apply
+```
+
+Repair converts deterministic `## Metadata` fields into v2 frontmatter, preserves the authored body, recovers IDs from canonical filenames, and stores byte-exact backups under `.scrumrun/.migration-backup/repair/`. It does not guess ambiguous relationships; validate afterward with `doctor --strict`.
+
 After migration or an integration update, verify both installed assets and project state:
 
 ```bash

package/lib/commands/repair.js

@@ -72,6 +72,7 @@ const RUN_TO_TASK_STATUS = {
 };
 
 const GUARDRAIL_SCOPES = new Set(["all", "intake", "execution", "mutation", "canonical", "memory", "migration", "validation", "learning", "completion", "commit", "release", "logs"]);
+const CANONICAL_DIRS = ["tasks", "runs", "features", "sprints", "reviews", "memory/knowledge", "memory/decisions", "memory/insights", "memory/dossiers"];
 
 function readIf(file) {
   try {
@@ -131,6 +132,85 @@ function scanTaskIds(scrumDir) {
   return ids;
 }
 
+function legacyMetadata(body) {
+  const metadata = {};
+  const section = String(body || "").match(/^## Metadata\s*$([\s\S]*?)(?=^##\s+|(?![\s\S]))/im);
+  if (!section) return metadata;
+  for (const line of section[1].split(/\r?\n/)) {
+    const match = line.match(/^\s*-\s*([a-z][a-z0-9_]*)\s*:\s*(.*?)\s*$/i);
+    if (match) metadata[match[1].toLowerCase()] = match[2];
+  }
+  return metadata;
+}
+
+function canonicalKind(relative) {
+  if (/^tasks\/TASK-\d{3,}\.md$/.test(relative)) return "task";
+  if (/^runs\/RUN-\d{3,}\.md$/.test(relative)) return "run";
+  if (/^features\/FEAT-\d{3,}\.md$/.test(relative)) return "feature";
+  if (/^sprints\/SPRINT-\d{3,}\.md$/.test(relative)) return "sprint";
+  if (/^reviews\/REV-\d{3,}\.md$/.test(relative)) return "review";
+  if (/^memory\/knowledge\/K-\d{3,}\.md$/.test(relative)) return "knowledge";
+  if (/^memory\/decisions\/DEC-\d{3,}\.md$/.test(relative)) return "decision";
+  if (/^memory\/insights\/INS-\d{3,}\.md$/.test(relative)) return "insight";
+  if (/^memory\/dossiers\/DOS-\d{3,}\.md$/.test(relative)) return "dossier";
+  return null;
+}
+
+function legacyStatus(kind, value) {
+  const raw = String(value || "").trim().toLowerCase();
+  const aliases = kind === "task" ? TASK_STATUS_ALIAS : kind === "run" ? RUN_STATUS_ALIAS : {};
+  const normalized = aliases[raw] || raw;
+  const valid = {
+    feature: ["backlog", "proposed", "active", "completed", "paused", "cancelled"],
+    task: [...VALID_TASK_STATUS],
+    sprint: ["proposed", "running", "partial", "completed", "blocked", "cancelled"],
+    run: [...VALID_RUN_STATUS],
+    review: ["proposed", "running", "passed", "failed", "archived"],
+    knowledge: ["candidate", "approved", "rejected", "deprecated", "invalidated"],
+    decision: ["open", "resolved", "deprecated", "invalidated"],
+    insight: ["candidate", "confirmed", "stale", "deprecated", "invalidated"],
+    dossier: ["active", "stale", "deprecated", "archived"]
+  }[kind] || [];
+  if (valid.includes(normalized)) return normalized;
+  return { feature: "proposed", task: "proposed", sprint: "proposed", run: "partial", review: "proposed", knowledge: "candidate", decision: "open", insight: "candidate", dossier: "active" }[kind];
+}
+
+function planMissingFrontmatter(scrumDir) {
+  const entries = [];
+  for (const directory of CANONICAL_DIRS) {
+    const absolute = path.join(scrumDir, directory);
+    if (!fs.existsSync(absolute) || !fs.lstatSync(absolute).isDirectory()) continue;
+    for (const file of fs.readdirSync(absolute).sort().map((name) => path.join(absolute, name))) {
+      if (!fs.lstatSync(file).isFile()) continue;
+      const relative = path.relative(scrumDir, file).split(path.sep).join("/");
+      const kind = canonicalKind(relative);
+      if (!kind) continue;
+      const original = readIf(file);
+      if (original === null || splitFrontmatter(original)) continue;
+      const metadata = legacyMetadata(original);
+      const id = path.basename(file, ".md");
+      const statDate = new Date(fs.statSync(file).mtimeMs).toISOString().slice(0, 10);
+      const created = ISO_DATE.test(metadata.created || "") ? metadata.created : statDate;
+      const updated = ISO_DATE.test(metadata.updated || "") ? metadata.updated : created;
+      const task = kind === "run" ? (TASK_REF.test(metadata.task || "") ? metadata.task : ((original.match(/\b(TASK-\d{3,})\b/) || [])[1] || null)) : null;
+      const featureValue = metadata.feature || metadata.scope || null;
+      const feature = FEAT_REF.test(featureValue || "") ? featureValue : null;
+      const sprint = /^SPRINT-\d{3,}$/.test(metadata.sprint || "") ? metadata.sprint : null;
+      const record = { id, kind, status: legacyStatus(kind, metadata.status), created, updated, method: "2.0.0" };
+      if (kind === "task") Object.assign(record, { type: metadata.type || "task", feature, sprint });
+      if (kind === "run") Object.assign(record, { task, sprint, attempt: Number(metadata.attempt) > 0 ? Number(metadata.attempt) : 1, ledger: 1 });
+      if (kind === "feature") record.type = "initiative";
+      if (kind === "decision" && feature) record.feature = feature;
+      const frontmatter = Object.entries(record).map(([key, value]) => `${key}: ${value === null ? "null" : value}`).join("\n");
+      const acceptance = kind === "task" && !/^## Acceptance Criteria\b/m.test(original)
+        ? "\n\n## Acceptance Criteria\n\n- Preserved from legacy migration. Define what done means before re-approaching this work.\n"
+        : "";
+      entries.push({ file, kind: "legacy-frontmatter", changes: [{ field: "frontmatter", from: "missing", to: `${kind} schema` }], nextText: `---\n${frontmatter}\n---\n\n${original}${acceptance}`, originalText: original });
+    }
+  }
+  return entries;
+}
+
 function planStatusSync(scrumDir) {
   // For each Task with Runs, align Task.status with the latest Run's status
   // (by highest attempt number, then created date). Legacy Tasks hand-marked
@@ -537,7 +617,7 @@ function analyze(scrumDir) {
   const featureIds = scanFeatureIds(scrumDir);
   const taskIds = scanTaskIds(scrumDir);
   const ctx = { featureIds };
-  const entries = [];
+  const entries = planMissingFrontmatter(scrumDir);
   const orphanRuns = planOrphanRuns(scrumDir, taskIds);
 
   const guardrailPlan = planGuardrails(scrumDir);
@@ -546,7 +626,8 @@ function analyze(scrumDir) {
   // Extra passes: status sync, attempt resequence, acceptance criteria, secret redaction.
   entries.push(...planStatusSync(scrumDir));
   entries.push(...planAttemptResequence(scrumDir));
-  entries.push(...planAcceptanceCriteria(scrumDir));
+  const missingFrontmatter = new Set(entries.filter((entry) => entry.kind === "legacy-frontmatter").map((entry) => entry.file));
+  entries.push(...planAcceptanceCriteria(scrumDir).filter((entry) => !missingFrontmatter.has(entry.file)));
   entries.push(...planSecretRedaction(scrumDir));
 
   for (const file of listDir(path.join(scrumDir, "tasks"), TASK_FILE)) {

package/package.json

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