scrumrun 1.5.2 → 2.1.0

package/lib/v2/project-store.js

@@ -0,0 +1,44 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { ArtifactRepository, graphFromRecords } = require("./artifacts");
+const { MANIFEST_PATH, migrationPlan } = require("./migration");
+
+const LEGACY_PATHS = [
+  "backlog.md",
+  "fixes.md",
+  "golden-rules.md",
+  "knowledge.md",
+  path.join("goals", "main", "sprint.md"),
+  path.join("goals", "main", "history.md"),
+  path.join("goals", "main", "decisions.md")
+];
+
+function readProjectModel(projectRoot) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  if (!fs.existsSync(scrumDir)) throw new Error("Not a ScrumRun project: .scrumrun/ is missing.");
+  const hasV2Marker = fs.existsSync(path.join(scrumDir, "method.json")) || fs.existsSync(path.join(scrumDir, MANIFEST_PATH));
+  const hasLegacy = LEGACY_PATHS.some((relative) => fs.existsSync(path.join(scrumDir, relative)));
+
+  if (hasV2Marker) {
+    const repository = new ArtifactRepository(scrumDir);
+    return {
+      layout: hasLegacy ? "mixed" : "v2",
+      source: "canonical-v2",
+      graph: repository.graph(),
+      warnings: []
+    };
+  }
+
+  const plan = migrationPlan(projectRoot);
+  return {
+    layout: "v1",
+    source: "read-only-v2-projection",
+    graph: graphFromRecords(plan.artifacts.map((artifact) => artifact.record)),
+    warnings: plan.warnings,
+    errors: plan.errors
+  };
+}
+
+module.exports = { LEGACY_PATHS, readProjectModel };

package/lib/v2/run-ledger-migration.js

@@ -0,0 +1,240 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const {
+  ArtifactRepository,
+  METHOD_VERSION,
+  assertNoSymlinkPath,
+  atomicWrite,
+  parseArtifact,
+  serializeArtifact,
+  sha256,
+  validateArtifact,
+  withArtifactLock
+} = require("./artifacts");
+const { RUN_LEDGER_VERSION } = require("./schema");
+const { migrateLegacyRun, validateRunLedger } = require("../runtime/run-ledger");
+
+const MIGRATION_NAME = "run-ledger-v1";
+const MIGRATION_DIR = path.join(".migration", MIGRATION_NAME);
+const MANIFEST_PATH = path.join(MIGRATION_DIR, "manifest.json");
+
+function posix(value) {
+  return value.split(path.sep).join("/");
+}
+
+function backupPath(relative) {
+  return posix(path.join(MIGRATION_DIR, "backup", relative));
+}
+
+function readMarker(scrumDir) {
+  const file = assertNoSymlinkPath(scrumDir, path.join(scrumDir, "method.json"));
+  if (!fs.existsSync(file) || !fs.lstatSync(file).isFile()) throw new Error("Canonical method.json is missing or unsafe.");
+  try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (value.method !== METHOD_VERSION) throw new Error(`method must be ${METHOD_VERSION}`);
+    return { file, value, content: fs.readFileSync(file, "utf8") };
+  } catch (error) {
+    throw new Error(`Canonical method.json is malformed: ${error.message}`);
+  }
+}
+
+function planRunLedgerMigration(projectRoot) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  if (!fs.existsSync(scrumDir) || !fs.lstatSync(scrumDir).isDirectory()) throw new Error("Not a ScrumRun project: .scrumrun/ is missing.");
+  const marker = readMarker(scrumDir);
+  const repository = new ArtifactRepository(scrumDir);
+  const changes = [];
+  const warnings = [];
+  const errors = [];
+
+  for (const artifact of repository.list("run")) {
+    if (!artifact.record || artifact.errors.length) {
+      errors.push(`${path.relative(scrumDir, artifact.file)}: ${artifact.errors.join("; ")}`);
+      continue;
+    }
+    if (artifact.record.ledger === RUN_LEDGER_VERSION) {
+      const ledger = validateRunLedger(artifact.record, artifact.body);
+      for (const error of ledger.errors) errors.push(`${artifact.record.id}: ${error}`);
+      continue;
+    }
+    const relative = posix(path.relative(scrumDir, artifact.file));
+    const before = fs.readFileSync(artifact.file, "utf8");
+    try {
+      const migrated = migrateLegacyRun(artifact.record, artifact.body, {
+        legacyHash: sha256(before),
+        backupRef: `.scrumrun/${backupPath(relative)}`
+      });
+      const after = serializeArtifact(migrated.record, migrated.body);
+      const parsed = parseArtifact(after);
+      const validation = [...parsed.errors, ...validateArtifact(parsed.record, "run"), ...validateRunLedger(parsed.record, parsed.body).errors];
+      if (validation.length) throw new Error(validation.join("; "));
+      changes.push({ relative, before, after, beforeSha256: sha256(before), afterSha256: sha256(after), mode: migrated.mode });
+      if (migrated.mode === "snapshot") warnings.push(`${artifact.record.id}: missing transition history is preserved as an evidenced snapshot, not reconstructed.`);
+    } catch (error) {
+      errors.push(`${artifact.record.id}: ${error.message}`);
+    }
+  }
+
+  const markerValue = {
+    ...marker.value,
+    schemas: { ...(marker.value.schemas || {}), run_ledger: RUN_LEDGER_VERSION }
+  };
+  const markerAfter = `${JSON.stringify(markerValue, null, 2)}\n`;
+  if (marker.content !== markerAfter) {
+    changes.push({
+      relative: "method.json",
+      before: marker.content,
+      after: markerAfter,
+      beforeSha256: sha256(marker.content),
+      afterSha256: sha256(markerAfter),
+      mode: "schema-marker"
+    });
+  }
+  const fingerprint = sha256(changes.map((change) => `${change.relative}\0${change.beforeSha256}`).sort().join("\n"));
+  return {
+    projectRoot,
+    scrumDir,
+    status: errors.length ? "blocked" : changes.length ? "ready" : "current",
+    migration: MIGRATION_NAME,
+    ledger: RUN_LEDGER_VERSION,
+    fingerprint,
+    changes,
+    warnings,
+    errors
+  };
+}
+
+function reportRunLedgerMigration(plan, status = plan.status) {
+  const mappings = plan.changes.length
+    ? plan.changes.map((change) => `- \`${change.relative}\` · ${change.mode} · \`${change.beforeSha256.slice(0, 12)}\` → \`${change.afterSha256.slice(0, 12)}\``).join("\n")
+    : "- No changes required.";
+  const warnings = plan.warnings.length ? plan.warnings.map((warning) => `- ${warning}`).join("\n") : "- None.";
+  const errors = plan.errors.length ? plan.errors.map((error) => `- ${error}`).join("\n") : "- None.";
+  return `# ScrumRun Run Ledger Migration\n\nStatus: ${status}\nSchema: ${RUN_LEDGER_VERSION}\nSource fingerprint: \`${plan.fingerprint}\`\nChanged files: ${plan.changes.length}\n\n## Mappings\n\n${mappings}\n\n## Warnings\n\n${warnings}\n\n## Blockers\n\n${errors}\n`;
+}
+
+function manifestFile(scrumDir) {
+  return assertNoSymlinkPath(scrumDir, path.join(scrumDir, MANIFEST_PATH));
+}
+
+function loadManifest(scrumDir) {
+  const file = manifestFile(scrumDir);
+  if (!fs.existsSync(file)) return null;
+  if (!fs.lstatSync(file).isFile() || fs.lstatSync(file).isSymbolicLink()) throw new Error("Run ledger migration manifest is unsafe.");
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function backupChanges(plan) {
+  for (const change of plan.changes) {
+    const target = assertNoSymlinkPath(plan.scrumDir, path.join(plan.scrumDir, backupPath(change.relative)));
+    if (fs.existsSync(target)) {
+      if (sha256(fs.readFileSync(target)) !== change.beforeSha256) throw new Error(`Migration backup conflicts for ${change.relative}.`);
+      continue;
+    }
+    atomicWrite(target, change.before);
+  }
+}
+
+function verifyChanges(scrumDir, changes, field) {
+  const problems = [];
+  for (const change of changes) {
+    const file = assertNoSymlinkPath(scrumDir, path.join(scrumDir, change.relative));
+    const actual = fs.existsSync(file) && fs.lstatSync(file).isFile() ? sha256(fs.readFileSync(file)) : "missing";
+    if (actual !== change[field]) problems.push(`${change.relative}: expected ${change[field]}, found ${actual}`);
+  }
+  return problems;
+}
+
+function restoreChanges(scrumDir, changes) {
+  for (const change of [...changes].reverse()) {
+    const backup = assertNoSymlinkPath(scrumDir, path.join(scrumDir, backupPath(change.relative)));
+    if (!fs.existsSync(backup) || sha256(fs.readFileSync(backup)) !== change.beforeSha256) {
+      throw new Error(`Run ledger backup is missing or corrupt for ${change.relative}.`);
+    }
+    const target = assertNoSymlinkPath(scrumDir, path.join(scrumDir, change.relative));
+    atomicWrite(target, fs.readFileSync(backup));
+  }
+}
+
+function recoverPrepared(scrumDir, manifest) {
+  if (!manifest || manifest.status !== "prepared") return false;
+  const allowed = [];
+  for (const change of manifest.changes) {
+    const file = path.join(scrumDir, change.relative);
+    const actual = fs.existsSync(file) ? sha256(fs.readFileSync(file)) : "missing";
+    if (![change.beforeSha256, change.afterSha256].includes(actual)) allowed.push(`${change.relative}: unexpected ${actual}`);
+  }
+  if (allowed.length) throw new Error(`Interrupted Run ledger migration cannot recover safely:\n${allowed.join("\n")}`);
+  restoreChanges(scrumDir, manifest.changes);
+  atomicWrite(manifestFile(scrumDir), `${JSON.stringify({ ...manifest, status: "recovered", recovered_at: new Date().toISOString() }, null, 2)}\n`);
+  return true;
+}
+
+function applyRunLedgerMigration(projectRoot, { failurePoint = null } = {}) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  const preview = planRunLedgerMigration(projectRoot);
+  if (preview.errors.length) throw new Error(`Run ledger migration is blocked:\n${preview.errors.join("\n")}`);
+  if (!preview.changes.length) return { status: "current", plan: preview, output: reportRunLedgerMigration(preview, "current") };
+  return withArtifactLock(scrumDir, "run-ledger-migration", () => {
+    const existing = loadManifest(scrumDir);
+    if (existing && existing.status === "prepared") recoverPrepared(scrumDir, existing);
+    const plan = planRunLedgerMigration(projectRoot);
+    if (plan.errors.length) throw new Error(`Run ledger migration is blocked:\n${plan.errors.join("\n")}`);
+    if (!plan.changes.length) return { status: "current", plan, output: reportRunLedgerMigration(plan, "current") };
+    const changed = verifyChanges(scrumDir, plan.changes, "beforeSha256");
+    if (changed.length) throw new Error(`Run ledger source changed after preflight:\n${changed.join("\n")}`);
+    backupChanges(plan);
+    const manifest = {
+      migration: MIGRATION_NAME,
+      schema: RUN_LEDGER_VERSION,
+      status: "prepared",
+      prepared_at: new Date().toISOString(),
+      source_fingerprint: plan.fingerprint,
+      changes: plan.changes.map(({ relative, beforeSha256, afterSha256, mode }) => ({ relative, beforeSha256, afterSha256, mode }))
+    };
+    atomicWrite(manifestFile(scrumDir), `${JSON.stringify(manifest, null, 2)}\n`);
+    try {
+      for (let index = 0; index < plan.changes.length; index++) {
+        const change = plan.changes[index];
+        const target = assertNoSymlinkPath(scrumDir, path.join(scrumDir, change.relative));
+        atomicWrite(target, change.after);
+        if (failurePoint === `after-${index + 1}`) throw new Error(`Injected Run ledger migration failure after write ${index + 1}.`);
+      }
+      const afterProblems = verifyChanges(scrumDir, plan.changes, "afterSha256");
+      if (afterProblems.length) throw new Error(`Run ledger migration verification failed:\n${afterProblems.join("\n")}`);
+      const applied = { ...manifest, status: "applied", applied_at: new Date().toISOString() };
+      atomicWrite(manifestFile(scrumDir), `${JSON.stringify(applied, null, 2)}\n`);
+      return { status: "applied", plan, manifest: applied, output: reportRunLedgerMigration(plan, "applied") };
+    } catch (error) {
+      restoreChanges(scrumDir, manifest.changes);
+      atomicWrite(manifestFile(scrumDir), `${JSON.stringify({ ...manifest, status: "recovered", recovered_at: new Date().toISOString() }, null, 2)}\n`);
+      throw error;
+    }
+  });
+}
+
+function rollbackRunLedgerMigration(projectRoot) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  return withArtifactLock(scrumDir, "run-ledger-migration", () => {
+    const manifest = loadManifest(scrumDir);
+    if (!manifest || !["applied", "prepared"].includes(manifest.status)) throw new Error("No applied Run ledger migration is available for rollback.");
+    if (manifest.status === "applied") {
+      const changed = verifyChanges(scrumDir, manifest.changes, "afterSha256");
+      if (changed.length) throw new Error(`Rollback would erase post-migration changes:\n${changed.join("\n")}`);
+    }
+    restoreChanges(scrumDir, manifest.changes);
+    const rolledBack = { ...manifest, status: "rolled-back", rolled_back_at: new Date().toISOString() };
+    atomicWrite(manifestFile(scrumDir), `${JSON.stringify(rolledBack, null, 2)}\n`);
+    return { status: "rolled-back", manifest: rolledBack };
+  });
+}
+
+module.exports = {
+  MIGRATION_NAME,
+  applyRunLedgerMigration,
+  planRunLedgerMigration,
+  reportRunLedgerMigration,
+  rollbackRunLedgerMigration
+};

package/lib/v2/schema.js

@@ -0,0 +1,148 @@
+"use strict";
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const nested of Object.values(value)) deepFreeze(nested);
+  return Object.freeze(value);
+}
+
+const METHOD_VERSION = "2.0.0";
+const RUN_LEDGER_VERSION = 1;
+
+const RUN_EVENT_TYPES = deepFreeze(["transition", "snapshot"]);
+const RUN_EVIDENCE_KINDS = deepFreeze([
+  "approval",
+  "command",
+  "test",
+  "file",
+  "review",
+  "decision",
+  "insight",
+  "risk",
+  "note",
+  "migration",
+  "legacy"
+]);
+
+const ARTIFACT_TYPES = deepFreeze({
+  feature: {
+    prefix: "FEAT",
+    directory: "features",
+    initial: ["backlog", "proposed"],
+    statuses: ["backlog", "proposed", "active", "completed", "paused", "cancelled"]
+  },
+  task: {
+    prefix: "TASK",
+    directory: "tasks",
+    initial: ["backlog", "proposed", "running"],
+    statuses: ["backlog", "proposed", "running", "validating", "learning", "partial", "completed", "failed", "blocked", "cancelled"]
+  },
+  sprint: {
+    prefix: "SPRINT",
+    directory: "sprints",
+    initial: ["proposed"],
+    statuses: ["proposed", "running", "partial", "completed", "blocked", "cancelled"]
+  },
+  run: {
+    prefix: "RUN",
+    directory: "runs",
+    initial: ["executing"],
+    statuses: ["executing", "validating", "learning", "partial", "completed", "failed", "blocked"]
+  },
+  review: {
+    prefix: "REV",
+    directory: "reviews",
+    initial: ["proposed"],
+    statuses: ["proposed", "running", "passed", "failed", "archived"]
+  },
+  knowledge: {
+    prefix: "K",
+    directory: "memory/knowledge",
+    initial: ["candidate"],
+    statuses: ["candidate", "approved", "rejected", "deprecated", "invalidated"]
+  },
+  decision: {
+    prefix: "DEC",
+    directory: "memory/decisions",
+    initial: ["open"],
+    statuses: ["open", "resolved", "deprecated", "invalidated"]
+  },
+  insight: {
+    prefix: "INS",
+    directory: "memory/insights",
+    initial: ["candidate"],
+    statuses: ["candidate", "confirmed", "stale", "deprecated", "invalidated"]
+  },
+  dossier: {
+    prefix: "DOS",
+    directory: "memory/dossiers",
+    initial: ["active"],
+    statuses: ["active", "stale", "deprecated", "archived"]
+  }
+});
+
+const ARTIFACT_TRANSITIONS = deepFreeze({
+  feature: {
+    backlog: ["proposed", "active", "cancelled"], proposed: ["active", "cancelled"], active: ["paused", "completed", "cancelled"], paused: ["active", "cancelled"]
+  },
+  task: {
+    backlog: ["proposed", "running", "cancelled"], proposed: ["running", "cancelled"], running: ["validating", "failed", "blocked", "cancelled"], validating: ["learning", "failed", "blocked"], learning: ["completed", "failed", "blocked"], partial: ["running", "cancelled"], failed: ["running", "cancelled"], blocked: ["running", "cancelled"]
+  },
+  sprint: {
+    proposed: ["running", "cancelled"], running: ["partial", "completed", "blocked", "cancelled"], partial: ["running", "completed", "cancelled"], blocked: ["running", "cancelled"]
+  },
+  run: {
+    executing: ["validating", "failed", "blocked"], validating: ["learning", "failed", "blocked"], learning: ["completed", "failed", "blocked"], partial: ["executing", "failed", "blocked"], blocked: ["executing", "failed"]
+  },
+  review: { proposed: ["running"], running: ["passed", "failed"], failed: ["running", "archived"], passed: ["archived"] },
+  knowledge: { candidate: ["approved", "rejected"], approved: ["deprecated", "invalidated"], rejected: ["candidate"], deprecated: ["approved"], invalidated: [] },
+  decision: { open: ["resolved", "deprecated", "invalidated"], resolved: ["deprecated", "invalidated"], deprecated: ["open"], invalidated: [] },
+  insight: { candidate: ["confirmed", "invalidated"], confirmed: ["stale", "deprecated", "invalidated"], stale: ["confirmed", "deprecated", "invalidated"], deprecated: ["confirmed"], invalidated: [] },
+  dossier: { active: ["stale", "deprecated", "archived"], stale: ["active", "deprecated", "archived"], deprecated: ["archived"], archived: [] }
+});
+
+const STRUCTURAL_RELATIONS = deepFreeze({
+  feature: { targetKind: "feature", cardinality: "0..1", meaning: "long-lived initiative containing the artifact" },
+  sprint: { targetKind: "sprint", cardinality: "0..1", meaning: "optional delivery batch containing a Task or Run" },
+  task: { targetKind: "task", cardinality: "1 for Run; otherwise 0..1", requiredFor: ["run"], meaning: "atomic work executed or reviewed by the artifact" }
+});
+
+const SCALAR_FIELDS = deepFreeze({
+  attempt: { kinds: ["run"], required: true, type: "positive integer", meaning: "monotonic execution-attempt number within one Task" },
+  ledger: { kinds: ["run"], required: false, type: `integer ${RUN_LEDGER_VERSION}`, meaning: "canonical Run event-ledger schema; required for newly authored Runs" }
+});
+
+const TRUTH_OWNERSHIP = deepFreeze({
+  feature: { question: "Why does this initiative exist?", truth: "initiative purpose, scope, dependencies, and lifecycle" },
+  task: { question: "What approved atomic outcome is intended?", truth: "scope, acceptance criteria, approval, and intended status" },
+  sprint: { question: "When are related Tasks grouped?", truth: "timebox or delivery-batch membership; never execution history" },
+  run: { question: "How did one execution attempt actually happen?", truth: "append-only execution events, evidence, result, and attempt number" },
+  review: { question: "What independent validation was performed?", truth: "scoped findings, checks, evidence, and verdict" },
+  knowledge: { question: "What verified project fact is reusable?", truth: "approved evidence-backed fact and validity" },
+  decision: { question: "What normative choice constrains future work?", truth: "decision, rationale, validity, and lifecycle" },
+  insight: { question: "Why is something arranged or constrained this way?", truth: "explanatory candidate/confirmed context and evidence" },
+  dossier: { question: "What evidence belongs to one retrieval topic?", truth: "reviewed topic bundle and freshness" }
+});
+
+const AUTHORITY = deepFreeze({
+  semantics: { source: "SPEC.md", scope: "normative meanings and invariants" },
+  schema: { source: "lib/v2/schema.js", scope: "machine-enforced ids, paths, statuses, transitions, relations, and ownership metadata" },
+  commands: { source: "lib/commands/manifest.js", scope: "public command grammar and compatibility routes" },
+  projectPolicy: { source: ".scrumrun/guardrails.md", scope: "owner/project constraints" },
+  projectTruth: { source: ".scrumrun/**/*.md", scope: "authored canonical project records" },
+  projections: { source: ".scrumrun/state.md, .scrumrun/map.md, .scrumrun/.cache/", scope: "disposable derived views; never authority" }
+});
+
+module.exports = {
+  ARTIFACT_TRANSITIONS,
+  ARTIFACT_TYPES,
+  AUTHORITY,
+  METHOD_VERSION,
+  RUN_EVENT_TYPES,
+  RUN_EVIDENCE_KINDS,
+  RUN_LEDGER_VERSION,
+  SCALAR_FIELDS,
+  STRUCTURAL_RELATIONS,
+  TRUTH_OWNERSHIP,
+  deepFreeze
+};