scrumrun 4.0.0 → 4.1.1

package/lib/migrate/ops.js

@@ -0,0 +1,92 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+
+function sha256(content) {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+function insideRoot(projectRoot, target) {
+  const absoluteRoot = path.resolve(projectRoot);
+  const absoluteTarget = path.resolve(projectRoot, target);
+  return absoluteTarget === absoluteRoot || absoluteTarget.startsWith(`${absoluteRoot}${path.sep}`);
+}
+
+function requireInside(projectRoot, relative, label) {
+  if (!relative || typeof relative !== "string") throw new Error(`${label}: path must be a non-empty string`);
+  if (path.isAbsolute(relative)) throw new Error(`${label}: absolute paths are not allowed`);
+  if (!insideRoot(projectRoot, relative)) throw new Error(`${label}: path escapes the project root`);
+  return path.resolve(projectRoot, relative);
+}
+
+const OPS = Object.freeze({
+  rename_path(projectRoot, step, journal) {
+    const from = requireInside(projectRoot, step.from, "rename_path.from");
+    const to = requireInside(projectRoot, step.to, "rename_path.to");
+    if (!fs.existsSync(from)) {
+      if (step.if_missing === "skip") return { skipped: true };
+      throw new Error(`rename_path: source does not exist: ${step.from}`);
+    }
+    if (fs.existsSync(to)) throw new Error(`rename_path: destination already exists: ${step.to}`);
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.renameSync(from, to);
+    journal.push({ op: "rename_path", from: step.from, to: step.to });
+    return { renamed: true };
+  },
+  bump_schema(projectRoot, step, journal) {
+    const file = requireInside(projectRoot, step.file || "method.json", "bump_schema.file");
+    if (!fs.existsSync(file)) throw new Error(`bump_schema: method file missing: ${step.file || "method.json"}`);
+    const before = fs.readFileSync(file, "utf8");
+    const method = JSON.parse(before);
+    const previous = method.schemas && method.schemas[step.field];
+    if (step.from !== undefined && previous !== step.from) {
+      throw new Error(`bump_schema: expected ${step.field} to be ${step.from}, found ${previous}`);
+    }
+    method.schemas = method.schemas || {};
+    method.schemas[step.field] = step.to;
+    fs.writeFileSync(file, `${JSON.stringify(method, null, 2)}\n`);
+    journal.push({ op: "bump_schema", file: step.file || "method.json", field: step.field, from: previous, to: step.to });
+    return { previous, next: step.to };
+  },
+  assert_hash(projectRoot, step) {
+    const file = requireInside(projectRoot, step.file, "assert_hash.file");
+    if (!fs.existsSync(file)) throw new Error(`assert_hash: missing file ${step.file}`);
+    const actual = sha256(fs.readFileSync(file));
+    if (actual !== step.sha256) throw new Error(`assert_hash: ${step.file} hash mismatch (expected ${step.sha256}, got ${actual})`);
+    return { hash: actual };
+  },
+  create_backup(projectRoot, step, journal) {
+    const source = requireInside(projectRoot, step.file, "create_backup.file");
+    const backupRoot = requireInside(projectRoot, step.backup_dir || ".backup", "create_backup.backup_dir");
+    if (!fs.existsSync(source)) throw new Error(`create_backup: missing source ${step.file}`);
+    fs.mkdirSync(backupRoot, { recursive: true });
+    const destination = path.join(backupRoot, path.basename(step.file));
+    fs.copyFileSync(source, destination);
+    journal.push({ op: "create_backup", file: step.file, backup: path.relative(projectRoot, destination) });
+    return { backup: path.relative(projectRoot, destination) };
+  },
+  move_frontmatter_field(projectRoot, step, journal) {
+    const file = requireInside(projectRoot, step.file, "move_frontmatter_field.file");
+    if (!fs.existsSync(file)) throw new Error(`move_frontmatter_field: missing ${step.file}`);
+    const source = fs.readFileSync(file, "utf8");
+    const match = /^---\r?\n([\s\S]*?)\r?\n---([\s\S]*)$/.exec(source);
+    if (!match) throw new Error(`move_frontmatter_field: no frontmatter in ${step.file}`);
+    const lines = match[1].split(/\r?\n/);
+    const fromRe = new RegExp(`^${step.from}:\\s*(.*)$`);
+    const idx = lines.findIndex((line) => fromRe.test(line));
+    if (idx === -1) {
+      if (step.if_missing === "skip") return { skipped: true };
+      throw new Error(`move_frontmatter_field: field ${step.from} not found in ${step.file}`);
+    }
+    const value = lines[idx].replace(fromRe, "$1");
+    lines[idx] = `${step.to}: ${value}`;
+    const next = `---\n${lines.join("\n")}\n---${match[2]}`;
+    fs.writeFileSync(file, next);
+    journal.push({ op: "move_frontmatter_field", file: step.file, from: step.from, to: step.to, value });
+    return { renamed: true };
+  }
+});
+
+module.exports = { OPS, sha256, requireInside };

package/lib/migrate/run.js

@@ -0,0 +1,108 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { OPS } = require("./ops");
+
+function extractYamlBlocks(markdown) {
+  const blocks = {};
+  const regex = /```yaml\s+([a-z_0-9]+)\r?\n([\s\S]*?)```/g;
+  let match;
+  while ((match = regex.exec(markdown)) !== null) {
+    blocks[match[1]] = match[2];
+  }
+  return blocks;
+}
+
+function parseYamlList(yaml) {
+  if (!yaml || !yaml.trim()) return [];
+  const items = [];
+  let current = null;
+  for (const rawLine of yaml.split(/\r?\n/)) {
+    const line = rawLine.replace(/\s+$/, "");
+    if (!line.trim()) continue;
+    const listMatch = /^(\s*)-\s+([a-z_0-9]+):\s*(.*)$/.exec(line);
+    const kvMatch = /^(\s+)([a-z_0-9]+):\s*(.*)$/.exec(line);
+    if (listMatch) {
+      current = {};
+      current[listMatch[2]] = coerce(listMatch[3]);
+      items.push(current);
+    } else if (kvMatch && current) {
+      current[kvMatch[2]] = coerce(kvMatch[3]);
+    }
+  }
+  return items;
+}
+
+function coerce(raw) {
+  const text = raw.trim();
+  if (text === "") return "";
+  if (text === "true") return true;
+  if (text === "false") return false;
+  if (text === "null") return null;
+  if (/^-?\d+$/.test(text)) return Number(text);
+  if (text.startsWith('"') && text.endsWith('"')) return text.slice(1, -1);
+  return text;
+}
+
+function parseMigration(source) {
+  const blocks = extractYamlBlocks(source);
+  const errors = [];
+  const steps = parseYamlList(blocks.steps);
+  const verify = parseYamlList(blocks.verify);
+  const rollback = parseYamlList(blocks.rollback);
+  if (!steps.length) errors.push("missing or empty ```yaml steps``` block");
+  if (!verify.length) errors.push("missing or empty ```yaml verify``` block");
+  for (const step of steps) {
+    if (!step.op || !OPS[step.op]) errors.push(`unknown or missing op in step: ${JSON.stringify(step)}`);
+  }
+  for (const step of verify) {
+    if (!step.op || !OPS[step.op]) errors.push(`unknown or missing verify op: ${JSON.stringify(step)}`);
+  }
+  return { steps, verify, rollback, errors };
+}
+
+function loadMigration(migrationFile) {
+  if (!fs.existsSync(migrationFile)) throw new Error(`Migration file not found: ${migrationFile}`);
+  const source = fs.readFileSync(migrationFile, "utf8");
+  const parsed = parseMigration(source);
+  if (parsed.errors.length) throw new Error(`Malformed migration ${path.basename(migrationFile)}: ${parsed.errors.join("; ")}`);
+  return parsed;
+}
+
+function runMigration(projectRoot, migrationFile, { dryRun = false } = {}) {
+  const migration = loadMigration(migrationFile);
+  if (dryRun) {
+    return {
+      status: "dry-run",
+      planned_steps: migration.steps.length,
+      planned_verify: migration.verify.length,
+      planned_rollback: migration.rollback.length
+    };
+  }
+  const journal = [];
+  const applied = [];
+  try {
+    for (const step of migration.steps) {
+      const result = OPS[step.op](projectRoot, step, journal);
+      applied.push({ op: step.op, result });
+    }
+    for (const step of migration.verify) {
+      OPS[step.op](projectRoot, step, journal);
+    }
+    return { status: "applied", steps: applied, journal };
+  } catch (error) {
+    return { status: "failed", steps: applied, error: error.message, journal };
+  }
+}
+
+function listMigrations(projectRoot) {
+  const dir = path.join(projectRoot, "migrations");
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((name) => /\.md$/.test(name))
+    .sort()
+    .map((name) => path.join(dir, name));
+}
+
+module.exports = { parseMigration, loadMigration, runMigration, listMigrations, extractYamlBlocks };

package/lib/runtime/context.js

@@ -167,7 +167,9 @@ function buildContextPackage(projectRoot, request) {
     return capped(content, limit);
   };
   const guardrailsContent = safeControl("guardrails.md", 10000);
-  const config = safeControl("config.md", 1000);
+  // Policy fields must never be truncated: a late Read-Only Paths declaration
+  // is still mandatory, regardless of explanatory prose above it.
+  const config = safeControl("config.md", 10000);
   const project = safeControl("project.md", 1400);
   const artifacts = model.source === "canonical-v2" ? artifactSnapshot(scrumDir) : { records: {}, hashes: [], warnings: [] };
   const openDecisions = (artifacts.records.decision || []).filter((record) => record.status === "open").slice(-10);

package/lib/runtime/policy-engine.js

@@ -3,6 +3,7 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const { containsSecret } = require("../security/secrets");
+const { enforcementBlock } = require("../guardrails/evaluate");
 
 const GUARDRAIL_STATUSES = new Set(["active", "retired", "superseded"]);
 const ENFORCEMENTS = new Set([
@@ -71,7 +72,9 @@ function parseGuardrails(content) {
     const rule = capped(fields.rule || proseRule(block) || title);
     const status = normalized(fields.status || "active").replace(/[._-]+$/, "");
     const enforcement = normalized(fields.enforcement || inferEnforcement(title, rule));
-    const scope = (fields.scope || "all").split(/\s*,\s*/).map((value) => normalized(value)).filter(Boolean);
+    const rawScope = String(fields.scope || "all").replace(/\([^)]*\)/g, "");
+    const scope = rawScope.split(/\s*[,+]\s*/).map((value) => normalized(value)).filter(Boolean);
+    const declarative = enforcementBlock(block, heading[1]);
     return {
       id: heading[1],
       title,
@@ -80,6 +83,8 @@ function parseGuardrails(content) {
       enforcement,
       scope,
       source: fields.source || null,
+      enforcement_rule: declarative.value,
+      enforcement_errors: declarative.errors,
       explicit: {
         status: Object.prototype.hasOwnProperty.call(fields, "status"),
         enforcement: Object.prototype.hasOwnProperty.call(fields, "enforcement"),
@@ -94,6 +99,11 @@ function configFields(content) {
   return fieldMap(String(content || ""));
 }
 
+function declarativeGuardrailConfig(content) {
+  // A project preference can promote warnings to blocks, never demote blocks.
+  return { on_violation: normalized(configFields(content).guardrail_on_violation || "warn") === "block" ? "block" : "warn" };
+}
+
 function agentIdentity(scrumDir) {
   if (process.env.SCRUMRUN_AGENT) {
     const env = String(process.env.SCRUMRUN_AGENT).trim();
@@ -249,6 +259,7 @@ function validateGuardrailDocument(content) {
     if (!ENFORCEMENTS.has(record.enforcement)) errors.push(`${record.id} has unknown enforcement: ${record.enforcement}`);
     if (!record.scope.length) errors.push(`${record.id} has no scope`);
     for (const scope of record.scope) if (!SCOPES.has(scope)) errors.push(`${record.id} has unknown scope: ${scope}`);
+    for (const error of record.enforcement_errors || []) errors.push(error);
   }
   return { records, errors };
 }
@@ -278,6 +289,7 @@ function normalizeGuardrailDocument(content) {
 module.exports = {
   agentIdentity,
   configWeakeningAttempts,
+  declarativeGuardrailConfig,
   evaluatePolicy,
   inferEnforcement,
   normalizeGuardrailDocument,

package/lib/runtime/watcher.js

@@ -0,0 +1,185 @@
+"use strict";
+
+const { spawn } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+const { refreshState } = require("./orchestrator");
+const { incrementalArtifact, rebuildIndex, writeMap } = require("../memory/index");
+const { sourceWatchSnapshot } = require("../memory/index");
+
+const PID_FILE = path.join(".scrumrun", ".cache", "watcher.pid");
+const DEFAULT_DEBOUNCE_MS = 250;
+const DEFAULT_POLL_MS = 1500;
+const GENERATED_OUTPUTS = Object.freeze([".scrumrun/state.md", ".scrumrun/map.md", ".scrumrun/.cache/"]);
+const EXECUTABLE_MARKDOWN = Object.freeze(["CORE.md", "SPEC.md", "DECISIONS.md"]);
+
+function number(value, fallback, minimum, maximum) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed >= minimum && parsed <= maximum ? parsed : fallback;
+}
+
+function watcherConfig(projectRoot) {
+  const file = path.join(projectRoot, ".scrumrun", "config.md");
+  const content = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  const field = (name) => {
+    const matches = [...content.matchAll(new RegExp(`^${name.replace(/\./g, "\\.")}:\\s*(.+)$`, "gmi"))];
+    return matches.length ? matches[matches.length - 1][1] : "";
+  };
+  return {
+    enabled: /^(true|yes|on|1)$/i.test(field("watcher.enabled").trim()),
+    debounceMs: number(field("watcher.debounce_ms"), DEFAULT_DEBOUNCE_MS, 25, 60_000),
+    pollMs: number(field("watcher.poll_interval_ms"), DEFAULT_POLL_MS, 250, 300_000)
+  };
+}
+
+function pidFile(projectRoot) { return path.join(projectRoot, PID_FILE); }
+
+function readStatus(projectRoot) {
+  const file = pidFile(projectRoot);
+  try {
+    const pid = Number(fs.readFileSync(file, "utf8").trim());
+    if (!Number.isInteger(pid) || pid < 1) throw new Error("invalid pid");
+    try { process.kill(pid, 0); return { running: true, pid, file }; }
+    catch { return { running: false, pid, file }; }
+  } catch { return { running: false, pid: null, file }; }
+}
+
+function writeStatus(projectRoot, value) {
+  const file = pidFile(projectRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${value.pid}\n`);
+}
+
+function isRelevant(relative) {
+  const item = String(relative || "").split(path.sep).join("/").replace(/^\.\//, "");
+  if (!item || item === ".") return true;
+  if (item === ".scrumrun/vault.local.md" || item.startsWith(".scrumrun/.cache/contexts/") || item.startsWith(".scrumrun/.cache/") || item === ".scrumrun/state.md" || item === ".scrumrun/map.md") return false;
+  if (item.startsWith(".git/") || item.startsWith("node_modules/") || item.startsWith("dist/") || item.startsWith("build/") || item.startsWith("coverage/")) return false;
+  return item.startsWith(".scrumrun/") || /\.(?:[cm]?[jt]sx?|vue|svelte|astro)$/i.test(item);
+}
+
+function generatedOutputOnly(relative) {
+  const item = String(relative || "").split(path.sep).join("/").replace(/^\.\//, "");
+  return GENERATED_OUTPUTS.some((output) => output.endsWith("/") ? item.startsWith(output) : item === output);
+}
+
+function assertGeneratedOutput(relative) {
+  if (!generatedOutputOnly(relative)) throw new Error(`Watcher output is restricted to generated projections, not ${relative}.`);
+}
+
+function refreshDerived(projectRoot, changed = []) {
+  // state.md is a bounded incremental projection; the SQLite graph falls back
+  // to its complete deterministic rebuild whenever a changed file could alter
+  // graph-wide lexical relations. This favours correctness over a partial edge
+  // update and keeps the incremental seam explicit for future adapters.
+  assertGeneratedOutput(".scrumrun/state.md");
+  assertGeneratedOutput(".scrumrun/.cache/semantic-index.sqlite");
+  assertGeneratedOutput(".scrumrun/map.md");
+  const state = refreshState(path.join(projectRoot, ".scrumrun"));
+  const incremental = incrementalArtifact(projectRoot, changed);
+  const index = incremental || rebuildIndex(projectRoot, { changedPaths: changed });
+  const map = writeMap(projectRoot);
+  return { mode: incremental ? "incremental-artifact" : changed.length === 1 ? "incremental-state+full-index-fallback" : "coalesced-full-index", changed, state, index, map };
+}
+
+function createWatcher(projectRoot, options = {}) {
+  const config = { ...watcherConfig(projectRoot), ...options };
+  let closed = false;
+  let pending = new Set();
+  let timer = null;
+  let poll = null;
+  let native = null;
+  let mode = "polling";
+  let snapshot = sourceWatchSnapshot(projectRoot).fingerprint;
+  let rebuilds = 0;
+  let lastResult = null;
+
+  const flush = () => {
+    timer = null;
+    if (closed || !pending.size) return;
+    const changed = [...pending].sort();
+    pending.clear();
+    lastResult = refreshDerived(projectRoot, changed);
+    snapshot = sourceWatchSnapshot(projectRoot).fingerprint;
+    rebuilds++;
+  };
+  const schedule = (relative) => {
+    if (!isRelevant(relative)) return;
+    pending.add(relative || ".");
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(flush, config.debounceMs);
+  };
+
+  const watch = options.watchImpl || fs.watch;
+  const startPolling = () => {
+    if (poll) return;
+    mode = "polling";
+    poll = setInterval(() => {
+      if (closed) return;
+      const next = sourceWatchSnapshot(projectRoot).fingerprint;
+      if (next !== snapshot) schedule(".");
+    }, config.pollMs);
+  };
+  try {
+    native = watch(projectRoot, { recursive: true }, (_event, filename) => schedule(filename ? String(filename) : "."));
+    mode = "fs.watch";
+    native.once("error", () => {
+      if (native) native.close();
+      native = null;
+      startPolling();
+    });
+  } catch {
+    // Linux and some Windows volumes do not support recursive fs.watch.
+    startPolling();
+  }
+  return {
+    get mode() { return mode; },
+    get rebuilds() { return rebuilds; },
+    get lastResult() { return lastResult; },
+    schedule,
+    close() {
+      closed = true;
+      if (timer) clearTimeout(timer);
+      if (poll) clearInterval(poll);
+      if (native) native.close();
+    }
+  };
+}
+
+function runDaemon(projectRoot) {
+  const config = watcherConfig(projectRoot);
+  if (!config.enabled) throw new Error("Watcher is disabled. Set watcher.enabled: true in .scrumrun/config.md before starting it.");
+  refreshDerived(projectRoot, ["startup"]);
+  const watcher = createWatcher(projectRoot, config);
+  writeStatus(projectRoot, { pid: process.pid });
+  const stop = () => {
+    watcher.close();
+    try { fs.rmSync(pidFile(projectRoot), { force: true }); } catch { /* best effort generated state cleanup */ }
+    process.exit(0);
+  };
+  process.on("SIGTERM", stop);
+  process.on("SIGINT", stop);
+}
+
+function startWatcher(projectRoot) {
+  const config = watcherConfig(projectRoot);
+  if (!config.enabled) return { status: "disabled", config };
+  const status = readStatus(projectRoot);
+  if (status.running) return { status: "already-running", ...status };
+  const child = spawn(process.execPath, [__filename, "--daemon", projectRoot], { detached: true, stdio: "ignore" });
+  child.unref();
+  return { status: "started", pid: child.pid, config };
+}
+
+function stopWatcher(projectRoot) {
+  const status = readStatus(projectRoot);
+  if (status.running) {
+    try { process.kill(status.pid, "SIGTERM"); } catch { /* status is reconciled below */ }
+  }
+  try { fs.rmSync(pidFile(projectRoot), { force: true }); } catch { /* generated state cleanup */ }
+  return { status: status.running ? "stopped" : "not-running", pid: status.pid };
+}
+
+if (require.main === module && process.argv[2] === "--daemon") runDaemon(path.resolve(process.argv[3] || process.cwd()));
+
+module.exports = { EXECUTABLE_MARKDOWN, GENERATED_OUTPUTS, assertGeneratedOutput, createWatcher, generatedOutputOnly, isRelevant, refreshDerived, readStatus, startWatcher, stopWatcher, watcherConfig };

package/lib/v2/conformance.js

@@ -11,10 +11,14 @@ const { extractEvidence } = require("../memory/markdown");
 const { resolveEvidence } = require("../memory/service");
 const { containsSecret, containsSecretWithAllowlist, loadSecretAllowlist } = require("../security/secrets");
 const { pendingTransactionStatus } = require("./transaction");
-const { configWeakeningAttempts, validateGuardrailDocument } = require("../runtime/policy-engine");
+const { configWeakeningAttempts, declarativeGuardrailConfig, validateGuardrailDocument } = require("../runtime/policy-engine");
 const { auditActiveWorkspace } = require("../runtime/mutation-gateway");
 const { canonicalPaths, PATHS_SCHEMA_VERSION } = require("./paths");
 const { auditPolicyIntegrity } = require("../runtime/policy-integrity");
+const { evaluate } = require("../guardrails/evaluate");
+const { collectChangeSet } = require("../guardrails/changeset");
+const { validateArtifacts: validateTaskSchema } = require("./task-schema");
+const { readGitContext } = require("../git/context");
 
 const INVARIANTS = Object.freeze([
   { id: "I-01", summary: "pre-approval work is read-only", tests: ["intake builds bounded context without writing"] },
@@ -65,7 +69,7 @@ function diffPathIndex(expected, actual, prefix = "") {
   return drift;
 }
 
-function auditProject(projectRoot) {
+function auditProject(projectRoot, options = {}) {
   const scrumDir = path.join(projectRoot, ".scrumrun");
   const findings = [];
   if (!fs.existsSync(scrumDir) || !fs.lstatSync(scrumDir).isDirectory()) {
@@ -113,6 +117,16 @@ function auditProject(projectRoot) {
   const configFile = path.join(scrumDir, "config.md");
   const config = fs.existsSync(configFile) && fs.lstatSync(configFile).isFile() ? fs.readFileSync(configFile, "utf8") : "";
   for (const error of configWeakeningAttempts(config)) findings.push(finding("high", "CONFIG_WEAKENS_POLICY", error, configFile));
+  const declarativeRules = guardrailValidation.records.filter((record) => record.status === "active" && record.enforcement_rule);
+  const guardrailEvaluation = evaluate(declarativeRules, options.changeSet || collectChangeSet(projectRoot, { staged: options.staged === true }), {
+    config: declarativeGuardrailConfig(config)
+  });
+  for (const item of guardrailEvaluation.blocked) {
+    findings.push(finding("high", "DECLARATIVE_GUARDRAIL_BLOCK", `${item.guardrail}: ${item.message} Evidence: ${item.evidence.join(", ")}.`, guardrailsFile));
+  }
+  for (const item of guardrailEvaluation.warnings) {
+    findings.push(finding("warning", "DECLARATIVE_GUARDRAIL_WARN", `${item.guardrail}: ${item.message} Evidence: ${item.evidence.join(", ")}.`, guardrailsFile));
+  }
 
   const repository = new ArtifactRepository(scrumDir);
   const counts = {};
@@ -288,6 +302,17 @@ function auditProject(projectRoot) {
   } catch (error) {
     findings.push(finding("high", "INDEX_UNSAFE", `semantic index cannot inspect canonical sources safely: ${error.message}`));
   }
+  const allArtifacts = Object.values(records).flat();
+  const gitContext = options.gitContext || readGitContext(projectRoot);
+  const taskSchemaReport = validateTaskSchema(allArtifacts, { gitContext });
+  const schemaErrorSeverity = options.strict ? "high" : "warning";
+  for (const error of taskSchemaReport.errors) {
+    findings.push(finding(schemaErrorSeverity, error.code, error.message, error.file));
+  }
+  for (const warning of taskSchemaReport.warnings) {
+    findings.push(finding("warning", warning.code, warning.message, warning.file));
+  }
+
   const transactions = pendingTransactionStatus(scrumDir);
   if (transactions.error) {
     findings.push(finding("high", "TRANSACTION_JOURNAL_UNSAFE", transactions.error));

package/lib/v2/runs-jsonl.js

@@ -0,0 +1,134 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const RUNS_JSONL_SCHEMA = 1;
+const ALLOWED_EVENTS = Object.freeze(["created", "started", "transition", "note", "evidence", "guardrail", "mutation", "completed", "failed", "blocked"]);
+const GENESIS_HASH = "0".repeat(64);
+
+function sha256Hex(input) {
+  return crypto.createHash("sha256").update(input).digest("hex");
+}
+
+function jsonlPath(scrumDir, taskId) {
+  return path.join(scrumDir, "runs", `${taskId}.jsonl`);
+}
+
+function assertTaskId(taskId) {
+  if (!/^TASK-\d{3,}$/.test(String(taskId || ""))) throw new Error(`Invalid TASK id for runs.jsonl: ${taskId}`);
+}
+
+function canonicalizePayload(payload) {
+  if (payload === null || payload === undefined) return {};
+  if (typeof payload !== "object" || Array.isArray(payload)) throw new Error("payload must be a plain object");
+  const sorted = {};
+  for (const key of Object.keys(payload).sort()) sorted[key] = payload[key];
+  return sorted;
+}
+
+function computeHash(previousHash, entry) {
+  const material = JSON.stringify({ prev: previousHash, run_id: entry.run_id, ts: entry.ts, event: entry.event, payload: entry.payload });
+  return sha256Hex(material);
+}
+
+function readEntries(scrumDir, taskId) {
+  assertTaskId(taskId);
+  const file = jsonlPath(scrumDir, taskId);
+  if (!fs.existsSync(file)) return [];
+  const contents = fs.readFileSync(file, "utf8");
+  if (!contents) return [];
+  const entries = [];
+  for (const rawLine of contents.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    entries.push(JSON.parse(line));
+  }
+  return entries;
+}
+
+function validateEntries(entries) {
+  const errors = [];
+  let previous = GENESIS_HASH;
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index];
+    if (!entry || typeof entry !== "object") { errors.push(`entry ${index}: not an object`); continue; }
+    for (const field of ["run_id", "ts", "event", "payload", "prev", "hash"]) {
+      if (!(field in entry)) errors.push(`entry ${index}: missing ${field}`);
+    }
+    if (entry.prev !== previous) errors.push(`entry ${index}: prev ${entry.prev} != expected ${previous}`);
+    if (!ALLOWED_EVENTS.includes(entry.event)) errors.push(`entry ${index}: unknown event ${entry.event}`);
+    const expectedHash = computeHash(previous, entry);
+    if (entry.hash !== expectedHash) errors.push(`entry ${index}: hash ${entry.hash} != expected ${expectedHash}`);
+    previous = entry.hash || previous;
+  }
+  return { errors, headHash: previous };
+}
+
+function appendEntry(scrumDir, taskId, { run_id, ts, event, payload }) {
+  assertTaskId(taskId);
+  if (!run_id || !/^RUN-\d{3,}$/.test(String(run_id))) throw new Error(`Invalid run_id: ${run_id}`);
+  if (!ts || Number.isNaN(Date.parse(ts))) throw new Error(`Invalid ts (ISO-8601 required): ${ts}`);
+  if (!ALLOWED_EVENTS.includes(event)) throw new Error(`Unknown event: ${event}`);
+  const canonicalPayload = canonicalizePayload(payload);
+
+  const file = jsonlPath(scrumDir, taskId);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+
+  // Concurrency: exclusive-create a lockfile; retry with jittered backoff.
+  const lock = `${file}.lock`;
+  const deadline = Date.now() + 5000;
+  let handle = null;
+  while (Date.now() < deadline) {
+    try {
+      handle = fs.openSync(lock, "wx");
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const delay = 5 + Math.floor(Math.random() * 15);
+      const busyUntil = Date.now() + delay;
+      while (Date.now() < busyUntil) { /* spin briefly */ }
+    }
+  }
+  if (handle === null) throw new Error(`Could not acquire lock on ${lock} within 5s`);
+
+  try {
+    const entries = readEntries(scrumDir, taskId);
+    const previous = entries.length ? entries[entries.length - 1].hash : GENESIS_HASH;
+    const record = { run_id, ts, event, payload: canonicalPayload, prev: previous };
+    record.hash = computeHash(previous, record);
+    const line = `${JSON.stringify(record)}\n`;
+    fs.appendFileSync(file, line);
+    return record;
+  } finally {
+    try { fs.closeSync(handle); } catch { /* ignore */ }
+    try { fs.unlinkSync(lock); } catch { /* ignore */ }
+  }
+}
+
+function listRunIds(scrumDir, taskId) {
+  const entries = readEntries(scrumDir, taskId);
+  return [...new Set(entries.map((entry) => entry.run_id))];
+}
+
+function listAllTaskLedgers(scrumDir) {
+  const dir = path.join(scrumDir, "runs");
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((name) => /^TASK-\d{3,}\.jsonl$/.test(name))
+    .map((name) => name.replace(/\.jsonl$/, ""));
+}
+
+module.exports = {
+  RUNS_JSONL_SCHEMA,
+  ALLOWED_EVENTS,
+  GENESIS_HASH,
+  jsonlPath,
+  readEntries,
+  validateEntries,
+  appendEntry,
+  listRunIds,
+  listAllTaskLedgers,
+  computeHash
+};