scrumrun 2.2.0 → 2.4.0

package/lib/v2/conformance.js

@@ -13,6 +13,7 @@ const { containsSecret, containsSecretWithAllowlist, loadSecretAllowlist } = req
 const { pendingTransactionStatus } = require("./transaction");
 const { configWeakeningAttempts, validateGuardrailDocument } = require("../runtime/policy-engine");
 const { auditActiveWorkspace } = require("../runtime/mutation-gateway");
+const { canonicalPaths, PATHS_SCHEMA_VERSION } = require("./paths");
 
 const INVARIANTS = Object.freeze([
   { id: "I-01", summary: "pre-approval work is read-only", tests: ["intake builds bounded context without writing"] },
@@ -35,13 +36,33 @@ const INVARIANTS = Object.freeze([
   { id: "I-18", summary: "unsafe and partial writes fail safely", tests: ["canonical writes reject traversal and symlink paths", "repository refuses conflicting overwrite", "interrupted kernel transaction is recovered"] },
   { id: "I-19", summary: "code intelligence is derived and fingerprinted", tests: ["language adapters are replaceable", "moves remap by fingerprint"] },
   { id: "I-20", summary: "learning candidates never block execution", tests: ["post-validation extraction creates candidate insights"] },
-  { id: "I-21", summary: "material mutations are scoped, policy-bound, and fail closed", tests: ["Mutation Gateway rejects bypass and out-of-scope writes", "Run completion rejects unresolved Guardrail obligations"] }
+  { id: "I-21", summary: "material mutations are scoped, policy-bound, and fail closed", tests: ["Mutation Gateway rejects bypass and out-of-scope writes", "Run completion rejects unresolved Guardrail obligations"] },
+  { id: "I-22", summary: "declared search backend matches observed runtime capabilities", tests: ["conformance detects a semantic index that declares fts5 when the runtime does not provide it"] },
+  { id: "I-23", summary: "method.json declares canonical paths so agents navigate by index, not by search", tests: ["method.json path index is present, well-formed, and matches the canonical layout"] }
 ]);
 
 function finding(severity, code, message, file = null) {
   return { severity, code, message, ...(file ? { file } : {}) };
 }
 
+function diffPathIndex(expected, actual, prefix = "") {
+  const drift = [];
+  for (const [key, value] of Object.entries(expected)) {
+    const label = prefix ? `${prefix}.${key}` : key;
+    const actualValue = actual && typeof actual === "object" ? actual[key] : undefined;
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      if (!actualValue || typeof actualValue !== "object" || Array.isArray(actualValue)) {
+        drift.push({ label, expected: "<object>", actual: actualValue });
+        continue;
+      }
+      drift.push(...diffPathIndex(value, actualValue, label));
+    } else if (actualValue !== value) {
+      drift.push({ label, expected: value, actual: actualValue });
+    }
+  }
+  return drift;
+}
+
 function auditProject(projectRoot) {
   const scrumDir = path.join(projectRoot, ".scrumrun");
   const findings = [];
@@ -55,6 +76,16 @@ function auditProject(projectRoot) {
     if (!fs.existsSync(marker) || !fs.lstatSync(marker).isFile()) throw new Error("marker is missing, not a regular file, or is a symbolic link");
     methodMarker = JSON.parse(fs.readFileSync(marker, "utf8"));
     if (methodMarker.method !== METHOD_VERSION) findings.push(finding("critical", "METHOD_VERSION", `method.json must declare ${METHOD_VERSION}.`, marker));
+    const expectedPaths = canonicalPaths();
+    if (!methodMarker.paths || typeof methodMarker.paths !== "object" || Array.isArray(methodMarker.paths)) {
+      findings.push(finding("high", "METHOD_PATHS_MISSING", `method.json must declare a canonical "paths" block so agents navigate by declaration, not by search. Run \`npx scrumrun@latest update --migrate\` to backfill.`, marker));
+    } else {
+      const drift = diffPathIndex(expectedPaths, methodMarker.paths);
+      for (const entry of drift) findings.push(finding("high", "METHOD_PATHS_DRIFT", `method.json paths[${entry.label}] is ${entry.actual === undefined ? "missing" : `"${entry.actual}"`}; expected "${entry.expected}". Regenerate via \`update --migrate\`.`, marker));
+      if (methodMarker.paths_schema !== PATHS_SCHEMA_VERSION) {
+        findings.push(finding("warning", "METHOD_PATHS_SCHEMA", `method.json paths_schema is ${methodMarker.paths_schema || "missing"}; expected ${PATHS_SCHEMA_VERSION}.`, marker));
+      }
+    }
   } catch (error) {
     findings.push(finding("critical", "METHOD_MARKER", `method.json is missing or malformed: ${error.message}`, marker));
   }
@@ -213,7 +244,11 @@ function auditProject(projectRoot) {
   }
   try {
     const semantic = indexStatus(projectRoot);
-    if (semantic.exists && semantic.stale) findings.push(finding("warning", "INDEX_STALE", "semantic-index.sqlite is stale and will be rebuilt on query."));
+    if (semantic.exists && semantic.backendMismatch) {
+      findings.push(finding("high", "SEARCH_BACKEND_MISMATCH", `semantic index declares search_backend=${semantic.searchBackend} but the current Node.js runtime does not provide it; delete .scrumrun/.cache/semantic-index.sqlite to rebuild against the observed capabilities.`));
+    } else if (semantic.exists && semantic.stale) {
+      findings.push(finding("warning", "INDEX_STALE", "semantic-index.sqlite is stale and will be rebuilt on query."));
+    }
     const map = mapStatus(projectRoot, { semanticStatus: semantic });
     if (semantic.exists && map.stale) findings.push(finding("warning", "MAP_STALE", `map.md is stale: ${map.reason || map.error || "unknown reason"}.`));
   } catch (error) {

package/lib/v2/migration.js

@@ -18,6 +18,7 @@ const {
 } = require("./artifacts");
 const { inferEnforcement, normalizeGuardrailDocument } = require("../runtime/policy-engine");
 const { RUN_LEDGER_VERSION } = require("./schema");
+const { renderMethodJson } = require("./paths");
 const { migrateLegacyRun } = require("../runtime/run-ledger");
 
 const MIGRATION_NAME = "v1-to-v2";
@@ -927,13 +928,12 @@ function migrationPlan(projectRoot) {
   }
 
   const sourceLayout = existingIds.size ? "hybrid-v1-v2" : "1.x";
-  generated.set("method.json", `${JSON.stringify({
-    method: METHOD_VERSION,
-    layout: "v2",
+  generated.set("method.json", renderMethodJson({
+    methodVersion: METHOD_VERSION,
     schemas: { run_ledger: RUN_LEDGER_VERSION, guardrails: 1, run_obligations: 1, mutation_gateway: 1 },
-    migrated_from: sourceLayout,
+    migratedFrom: sourceLayout,
     migration: MIGRATION_NAME
-  }, null, 2)}\n`);
+  }));
 
   const counts = {};
   for (const artifact of artifacts) counts[artifact.kind] = (counts[artifact.kind] || 0) + 1;

package/lib/v2/paths.js

@@ -0,0 +1,72 @@
+"use strict";
+
+// Single source of truth for the canonical layout inside `.scrumrun/`.
+//
+// This module powers `method.json.paths` — the machine-readable index a
+// ScrumRun-aware agent must consult BEFORE searching. Any change here
+// must land in the template, the migration generator, and the doctor
+// invariant together so no drift is possible.
+
+const CANONICAL_PATHS = Object.freeze({
+  guardrails: "guardrails.md",
+  config: "config.md",
+  project: "project.md",
+  core: "core.md",
+  state_view: "state.md",
+  map_view: "map.md",
+  tasks: "tasks/",
+  sprints: "sprints/",
+  features: "features/",
+  runs: "runs/",
+  reviews: "reviews/",
+  memory: Object.freeze({
+    knowledge: "memory/knowledge/",
+    decisions: "memory/decisions/",
+    insights: "memory/insights/",
+    dossiers: "memory/dossiers/"
+  }),
+  vault_local: "vault.local.md",
+  cache: ".cache/"
+});
+
+const PATHS_SCHEMA_VERSION = 1;
+
+function clone(value) {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(clone);
+  const out = {};
+  for (const [key, entry] of Object.entries(value)) out[key] = clone(entry);
+  return out;
+}
+
+function canonicalPaths() {
+  return clone(CANONICAL_PATHS);
+}
+
+function flattenPaths(paths = CANONICAL_PATHS, prefix = "") {
+  const out = [];
+  for (const [key, value] of Object.entries(paths)) {
+    const label = prefix ? `${prefix}.${key}` : key;
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      out.push(...flattenPaths(value, label));
+    } else if (typeof value === "string") {
+      out.push({ label, relative: value });
+    }
+  }
+  return out;
+}
+
+function renderMethodJson({ methodVersion, layout = "v2", schemas = {}, migratedFrom, migration } = {}) {
+  const payload = {
+    method: methodVersion,
+    layout,
+    paths_schema: PATHS_SCHEMA_VERSION,
+    paths: canonicalPaths(),
+    schemas
+  };
+  if (migratedFrom) payload.migrated_from = migratedFrom;
+  if (migration) payload.migration = migration;
+  return `${JSON.stringify(payload, null, 2)}\n`;
+}
+
+module.exports = { CANONICAL_PATHS, PATHS_SCHEMA_VERSION, canonicalPaths, flattenPaths, renderMethodJson };

package/lib/v2/transaction.js

@@ -236,6 +236,64 @@ function runKernelTransaction(scrumDir, name, changes, options = {}) {
   });
 }
 
+function previewPendingRecovery(scrumDir) {
+  const preview = { plans: [], errors: [] };
+  let entries;
+  try {
+    entries = pendingTransactions(scrumDir);
+  } catch (error) {
+    preview.errors.push(error.message);
+    return preview;
+  }
+  for (const { file, transaction } of entries) {
+    const plan = { id: transaction.id, name: transaction.name || null, journal: path.basename(file), status: transaction.status, action: null, files: [], warnings: [] };
+    const journalErrors = validateJournal(transaction);
+    if (journalErrors.length) {
+      plan.action = "blocked";
+      plan.warnings.push(`journal validation failed: ${journalErrors.join("; ")}`);
+      preview.plans.push(plan);
+      continue;
+    }
+    let unsafePath = null;
+    for (const change of transaction.changes) {
+      const target = relativeTarget(scrumDir, path.join(scrumDir, change.relative));
+      if (target.relative !== change.relative) {
+        unsafePath = change.relative;
+        break;
+      }
+    }
+    if (unsafePath) {
+      plan.action = "blocked";
+      plan.warnings.push(`unsafe transaction target: ${unsafePath}`);
+      preview.plans.push(plan);
+      continue;
+    }
+    const current = transaction.changes.map((change) => ({ change, value: fileSnapshot(scrumDir, change.relative) }));
+    const unexpected = current.filter(({ change, value }) => !sameSnapshot(value, change.before) && !sameSnapshot(value, change.after));
+    if (unexpected.length) {
+      plan.action = "blocked";
+      plan.warnings.push(`would overwrite owner changes at: ${unexpected.map(({ change }) => change.relative).join(", ")}`);
+      preview.plans.push(plan);
+      continue;
+    }
+    if (transaction.status === "prepared") {
+      plan.action = "rollback";
+      plan.files = transaction.changes.map((change) => ({ relative: change.relative, from: "current", to: "pre-transaction" }));
+    } else {
+      const incomplete = current.filter(({ change, value }) => !sameSnapshot(value, change.after));
+      if (incomplete.length) {
+        plan.action = "blocked";
+        plan.warnings.push(`committed transaction is incomplete: ${incomplete.map(({ change }) => change.relative).join(", ")}`);
+      } else {
+        plan.action = "verify-commit";
+        plan.files = transaction.changes.map((change) => ({ relative: change.relative, from: "current", to: "verified-commit" }));
+      }
+    }
+    preview.plans.push(plan);
+  }
+  return preview;
+}
+
 function pendingTransactionStatus(scrumDir) {
   try {
     return { pending: pendingTransactions(scrumDir).map(({ transaction }) => ({ id: transaction.id, name: transaction.name, status: transaction.status })) };
@@ -247,6 +305,7 @@ function pendingTransactionStatus(scrumDir) {
 module.exports = {
   TRANSACTION_SCHEMA,
   pendingTransactionStatus,
+  previewPendingRecovery,
   recoverPendingTransactions,
   recoverPendingTransactionsUnlocked,
   runKernelTransaction,

package/package.json

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

package/templates/project/.scrumrun/method.json

@@ -1,6 +1,28 @@
 {
   "method": "2.0.0",
   "layout": "v2",
+  "paths_schema": 1,
+  "paths": {
+    "guardrails": "guardrails.md",
+    "config": "config.md",
+    "project": "project.md",
+    "core": "core.md",
+    "state_view": "state.md",
+    "map_view": "map.md",
+    "tasks": "tasks/",
+    "sprints": "sprints/",
+    "features": "features/",
+    "runs": "runs/",
+    "reviews": "reviews/",
+    "memory": {
+      "knowledge": "memory/knowledge/",
+      "decisions": "memory/decisions/",
+      "insights": "memory/insights/",
+      "dossiers": "memory/dossiers/"
+    },
+    "vault_local": "vault.local.md",
+    "cache": ".cache/"
+  },
   "schemas": {
     "run_ledger": 1,
     "guardrails": 1,

package/templates/shared/skills/scrumrun/SKILL.md

@@ -29,11 +29,12 @@ Apply instructions in this order:
 
 Normal hot path:
 
-1. read `AGENTS.md`;
-2. read `.scrumrun/guardrails.md`;
-3. read `.scrumrun/state.md`;
-4. follow the ids/pointers to only the relevant canonical artifacts;
-5. load `.scrumrun/core.md` when the method contract or an exceptional transition is needed.
+1. read `.scrumrun/method.json` — its `paths` block is the authoritative index of every canonical location; navigate by that index and never grep for legacy paths (`goals/`, `backlog.md`, `sprint.md`, `history.md`);
+2. read `AGENTS.md`;
+3. read `.scrumrun/guardrails.md`;
+4. read `.scrumrun/state.md`;
+5. follow the ids/pointers to only the relevant canonical artifacts;
+6. load `.scrumrun/core.md` when the method contract or an exceptional transition is needed.
 
 Lean mode is a read policy, not an incomplete store. Generated files and `.scrumrun/.cache/` are never authoritative.