scrumrun 2.7.9 → 2.7.11

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.11` · **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

@@ -12,6 +12,8 @@
 //      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).
+//   5. Sprint task projections: add Task.sprint references absent from the
+//      Sprint's `## Tasks` list. Extra entries remain for human review.
 //
 // Categories intentionally NOT touched (need human judgment):
 //   - Secret-like content (SECRET_CANONICAL)
@@ -72,6 +74,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 +134,127 @@ function scanTaskIds(scrumDir) {
   return ids;
 }
 
+function planSprintMembership(scrumDir) {
+  const tasksBySprint = new Map();
+  for (const file of listDir(path.join(scrumDir, "tasks"), TASK_FILE)) {
+    const parsed = splitFrontmatter(readIf(file));
+    if (!parsed) continue;
+    const sprint = extractField(parsed.header, "sprint");
+    const id = extractField(parsed.header, "id") || path.basename(file, ".md");
+    if (!/^SPRINT-\d{3,}$/.test(sprint || "") || !TASK_REF.test(id)) continue;
+    if (!tasksBySprint.has(sprint)) tasksBySprint.set(sprint, []);
+    tasksBySprint.get(sprint).push(id);
+  }
+  const entries = [];
+  for (const file of listDir(path.join(scrumDir, "sprints"), SPRINT_FILE)) {
+    const original = readIf(file);
+    const parsed = splitFrontmatter(original);
+    if (!parsed) continue;
+    const sprintId = extractField(parsed.header, "id") || path.basename(file, ".md");
+    const expected = tasksBySprint.get(sprintId) || [];
+    if (!expected.length) continue;
+    const heading = /^## Tasks[ \t]*$/m.exec(parsed.body);
+    if (!heading) continue;
+    const tail = parsed.body.slice(heading.index + heading[0].length);
+    const nextHeading = /^## [^\r\n]+$/m.exec(tail);
+    const sectionEnd = nextHeading ? heading.index + heading[0].length + nextHeading.index : parsed.body.length;
+    const section = parsed.body.slice(heading.index + heading[0].length, sectionEnd);
+    const listed = new Set([...section.matchAll(/^-\s+(TASK-\d{3,})\s*$/gm)].map((match) => match[1]));
+    const missing = expected.filter((id) => !listed.has(id));
+    if (!missing.length) continue;
+    const before = parsed.body.slice(0, sectionEnd).replace(/\s*$/, "\n");
+    const after = parsed.body.slice(sectionEnd).replace(/^\n/, "");
+    const body = `${before}${missing.map((id) => `- ${id}`).join("\n")}\n${after}`;
+    entries.push({
+      file,
+      kind: "sprint-membership",
+      changes: [{ field: "sprint.tasks", from: "missing projection", to: missing.join(", ") }],
+      nextText: `---\n${parsed.header}\n---${parsed.sep}${body}`,
+      originalText: original
+    });
+  }
+  return entries;
+}
+
+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 +661,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,8 +670,10 @@ 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));
+  entries.push(...planSprintMembership(scrumDir));
 
   for (const file of listDir(path.join(scrumDir, "tasks"), TASK_FILE)) {
     const plan = planFile(file, "task", ctx);

package/package.json

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