scrumrun 1.5.2 → 2.0.0

package/lib/v2/artifacts.js

@@ -0,0 +1,343 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+const {
+  ARTIFACT_TRANSITIONS,
+  ARTIFACT_TYPES,
+  METHOD_VERSION,
+  SCALAR_FIELDS,
+  STRUCTURAL_RELATIONS
+} = require("./schema");
+
+function sha256(content) {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+function scalar(value) {
+  if (value === null || value === undefined) return "null";
+  if (typeof value === "boolean" || typeof value === "number") return String(value);
+  const text = String(value);
+  if (/^[A-Za-z0-9._/-]+$/.test(text)) return text;
+  return JSON.stringify(text);
+}
+
+function parseScalar(value) {
+  const text = value.trim();
+  if (text === "null") return null;
+  if (text === "true") return true;
+  if (text === "false") return false;
+  if (/^-?\d+(?:\.\d+)?$/.test(text)) return Number(text);
+  if (text.startsWith('"')) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  return text;
+}
+
+function serializeArtifact(record, body = "") {
+  const required = ["id", "kind", "status", "created", "updated", "method"];
+  const ordered = {};
+  for (const key of required) ordered[key] = record[key];
+  for (const [key, value] of Object.entries(record)) {
+    if (!required.includes(key)) ordered[key] = value;
+  }
+  const frontmatter = Object.entries(ordered)
+    .filter(([, value]) => value !== undefined)
+    .map(([key, value]) => `${key}: ${scalar(value)}`)
+    .join("\n");
+  return `---\n${frontmatter}\n---\n\n${body.trim()}\n`;
+}
+
+function parseArtifact(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/);
+  if (!match) return { record: null, body: content, errors: ["missing or malformed frontmatter"] };
+  const record = {};
+  const errors = [];
+  for (const line of match[1].split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const field = line.match(/^([a-z][a-z0-9_]*):\s*(.*)$/i);
+    if (!field) {
+      errors.push(`malformed frontmatter line: ${line}`);
+      continue;
+    }
+    if (Object.prototype.hasOwnProperty.call(record, field[1])) {
+      errors.push(`duplicate frontmatter field: ${field[1]}`);
+      continue;
+    }
+    record[field[1]] = parseScalar(field[2]);
+  }
+  return { record, body: match[2], errors };
+}
+
+function validateArtifact(record, expectedKind = null) {
+  const errors = [];
+  if (!record || typeof record !== "object") return ["artifact record is missing"];
+  const type = ARTIFACT_TYPES[record.kind];
+  if (!type) errors.push(`unknown kind: ${record.kind || "missing"}`);
+  if (expectedKind && record.kind !== expectedKind) errors.push(`expected kind ${expectedKind}, got ${record.kind}`);
+  if (type && !new RegExp(`^${type.prefix}-\\d{3,}$`).test(record.id || "")) {
+    errors.push(`invalid ${record.kind} id: ${record.id || "missing"}`);
+  }
+  if (type && !type.statuses.includes(record.status)) {
+    errors.push(`invalid ${record.kind} status: ${record.status || "missing"}`);
+  }
+  if (record.method !== METHOD_VERSION) errors.push(`method must be ${METHOD_VERSION}`);
+  for (const field of ["created", "updated"]) {
+    const value = record[field] || "";
+    const timestamp = /^\d{4}-\d{2}-\d{2}$/.test(value) ? Date.parse(`${value}T00:00:00.000Z`) : NaN;
+    const valid = Number.isFinite(timestamp) && new Date(timestamp).toISOString().slice(0, 10) === value;
+    if (!valid) errors.push(`${field} must be a real YYYY-MM-DD date`);
+  }
+  for (const [field, relation] of Object.entries(STRUCTURAL_RELATIONS)) {
+    const target = ARTIFACT_TYPES[relation.targetKind];
+    if (record[field] !== undefined && record[field] !== null && !new RegExp(`^${target.prefix}-\\d{3,}$`).test(record[field])) {
+      errors.push(`${record.kind}.${field} must reference ${target.prefix}-NNN or null`);
+    }
+    if ((relation.requiredFor || []).includes(record.kind) && (record[field] === undefined || record[field] === null)) {
+      errors.push(`${record.kind}.${field} must reference ${target.prefix}-NNN`);
+    }
+  }
+  for (const [field, constraint] of Object.entries(SCALAR_FIELDS)) {
+    if (!constraint.kinds.includes(record.kind)) continue;
+    if (constraint.required && (record[field] === undefined || record[field] === null)) {
+      errors.push(`${record.kind}.${field} is required`);
+      continue;
+    }
+    if (field === "attempt" && (!Number.isInteger(record[field]) || record[field] < 1)) {
+      errors.push(`${record.kind}.${field} must be a positive integer`);
+    }
+  }
+  return errors;
+}
+
+function transitionArtifact(record, nextStatus, updated) {
+  const errors = validateArtifact(record);
+  if (errors.length) throw new Error(`Cannot transition invalid artifact: ${errors.join("; ")}`);
+  const allowed = (ARTIFACT_TRANSITIONS[record.kind] && ARTIFACT_TRANSITIONS[record.kind][record.status]) || [];
+  if (!allowed.includes(nextStatus)) {
+    throw new Error(`Invalid ${record.kind} transition: ${record.status} -> ${nextStatus}`);
+  }
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(updated || "")) throw new Error("Transition date must be YYYY-MM-DD");
+  return { ...record, status: nextStatus, updated };
+}
+
+function relativeArtifactPath(record) {
+  const type = ARTIFACT_TYPES[record.kind];
+  if (!type) throw new Error(`Unknown artifact kind: ${record.kind}`);
+  if (!new RegExp(`^${type.prefix}-\\d{3,}$`).test(record.id || "")) throw new Error(`Invalid artifact id: ${record.id}`);
+  return path.join(type.directory, `${record.id}.md`);
+}
+
+function safePath(root, relative) {
+  const resolvedRoot = path.resolve(root);
+  const target = path.resolve(resolvedRoot, relative);
+  if (target !== resolvedRoot && !target.startsWith(`${resolvedRoot}${path.sep}`)) {
+    throw new Error(`Path escapes artifact root: ${relative}`);
+  }
+  return target;
+}
+
+function assertNoSymlinkPath(root, target) {
+  const resolvedRoot = path.resolve(root);
+  const resolvedTarget = path.resolve(target);
+  if (resolvedTarget !== resolvedRoot && !resolvedTarget.startsWith(`${resolvedRoot}${path.sep}`)) {
+    throw new Error(`Path escapes artifact root: ${target}`);
+  }
+  const relative = path.relative(resolvedRoot, resolvedTarget);
+  let current = resolvedRoot;
+  const candidates = [resolvedRoot, ...relative.split(path.sep).filter(Boolean).map((segment) => (current = path.join(current, segment)))];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate) && fs.lstatSync(candidate).isSymbolicLink()) {
+      throw new Error(`Symbolic links are forbidden in canonical artifact paths: ${path.relative(resolvedRoot, candidate) || "."}`);
+    }
+  }
+  return resolvedTarget;
+}
+
+function atomicWrite(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`);
+  try {
+    fs.writeFileSync(temp, content);
+    fs.renameSync(temp, file);
+  } catch (error) {
+    if (fs.existsSync(temp)) fs.rmSync(temp, { force: true });
+    throw error;
+  }
+}
+
+function wait(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
+function withArtifactLock(scrumDir, name, operation, { timeoutMs = 3000, staleMs = 30000 } = {}) {
+  if (!/^[a-z0-9-]+$/i.test(name)) throw new Error(`Invalid lock name: ${name}`);
+  const lockDir = path.join(scrumDir, ".cache", "locks");
+  assertNoSymlinkPath(scrumDir, lockDir);
+  fs.mkdirSync(lockDir, { recursive: true });
+  const lockFile = path.join(lockDir, `${name}.lock`);
+  const token = `${process.pid}:${Date.now()}:${crypto.randomBytes(8).toString("hex")}`;
+  const started = Date.now();
+  let descriptor = null;
+  while (descriptor === null) {
+    try {
+      descriptor = fs.openSync(lockFile, "wx", 0o600);
+      fs.writeFileSync(descriptor, token);
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      let stat;
+      try {
+        stat = fs.lstatSync(lockFile);
+      } catch (statError) {
+        if (statError.code === "ENOENT") continue;
+        throw statError;
+      }
+      if (stat.isSymbolicLink()) throw new Error(`Symbolic lock path is forbidden: ${name}`);
+      if (Date.now() - stat.mtimeMs > staleMs) {
+        let current;
+        try {
+          current = fs.lstatSync(lockFile);
+        } catch (statError) {
+          if (statError.code === "ENOENT") continue;
+          throw statError;
+        }
+        if (current.ino === stat.ino && current.mtimeMs === stat.mtimeMs) fs.rmSync(lockFile, { force: true });
+        continue;
+      }
+      if (Date.now() - started >= timeoutMs) throw new Error(`Timed out waiting for ScrumRun lock: ${name}`);
+      wait(10);
+    }
+  }
+  try {
+    return operation();
+  } finally {
+    if (descriptor !== null) fs.closeSync(descriptor);
+    try {
+      if (fs.existsSync(lockFile) && fs.readFileSync(lockFile, "utf8") === token) fs.rmSync(lockFile, { force: true });
+    } catch {
+      // A failed cleanup leaves a short-lived stale lock; it never changes canonical state.
+    }
+  }
+}
+
+function graphFromRecords(records) {
+  const nodes = [];
+  const edges = [];
+  for (const record of records) {
+    if (!record || validateArtifact(record).length) continue;
+    nodes.push({ id: record.id, kind: record.kind, status: record.status });
+    const relations = [
+      ["feature", "belongs_to"],
+      ["sprint", "included_in"],
+      ["task", "executes"],
+      ["subject", "about"],
+      ["source_id", "evidenced_by"]
+    ];
+    for (const [field, relation] of relations) {
+      if (typeof record[field] === "string" && /^[A-Z]+-\d{3,}$/.test(record[field])) {
+        edges.push({ from: record.id, relation, to: record[field] });
+      }
+    }
+  }
+  return { nodes, edges };
+}
+
+class ArtifactRepository {
+  constructor(scrumDir) {
+    this.scrumDir = path.resolve(scrumDir);
+  }
+
+  pathFor(record) {
+    const file = safePath(this.scrumDir, relativeArtifactPath(record));
+    return assertNoSymlinkPath(this.scrumDir, file);
+  }
+
+  write(record, body, { overwrite = false } = {}) {
+    const errors = validateArtifact(record);
+    if (errors.length) throw new Error(`Invalid artifact ${record.id || "unknown"}: ${errors.join("; ")}`);
+    const file = this.pathFor(record);
+    const content = serializeArtifact(record, body);
+    if (fs.existsSync(file)) {
+      const current = fs.readFileSync(file, "utf8");
+      if (current === content) return { status: "unchanged", file, hash: sha256(content) };
+      if (!overwrite) throw new Error(`Artifact already exists with different content: ${path.relative(this.scrumDir, file)}`);
+    }
+    atomicWrite(file, content);
+    return { status: "written", file, hash: sha256(content) };
+  }
+
+  read(kind, id) {
+    const file = this.pathFor({ kind, id });
+    if (!fs.existsSync(file)) return null;
+    const content = fs.readFileSync(file, "utf8");
+    const parsed = parseArtifact(content);
+    const errors = [...parsed.errors, ...validateArtifact(parsed.record, kind)];
+    if (parsed.record && parsed.record.id !== id) errors.push(`artifact id ${parsed.record.id || "missing"} does not match filename ${id}`);
+    return { ...parsed, file, errors };
+  }
+
+  transition(kind, id, nextStatus, updated) {
+    const artifact = this.read(kind, id);
+    if (!artifact) throw new Error(`Artifact not found: ${id}`);
+    if (artifact.errors.length) throw new Error(`Invalid artifact ${id}: ${artifact.errors.join("; ")}`);
+    transitionArtifact(artifact.record, nextStatus, updated);
+    const content = fs.readFileSync(artifact.file, "utf8");
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---([\s\S]*)$/);
+    if (!match) throw new Error(`Invalid artifact ${id}: missing frontmatter`);
+    let frontmatter = match[1];
+    frontmatter = frontmatter.replace(/^status:\s*.*$/m, `status: ${nextStatus}`);
+    frontmatter = frontmatter.replace(/^updated:\s*.*$/m, `updated: ${updated}`);
+    const next = `---\n${frontmatter}\n---${match[2]}`;
+    const parsed = parseArtifact(next);
+    const errors = [...parsed.errors, ...validateArtifact(parsed.record, kind)];
+    if (errors.length) throw new Error(`Transition validation failed for ${id}: ${errors.join("; ")}`);
+    atomicWrite(artifact.file, next);
+    return { status: "written", file: artifact.file, record: parsed.record, hash: sha256(next) };
+  }
+
+  list(kind) {
+    const type = ARTIFACT_TYPES[kind];
+    if (!type) throw new Error(`Unknown artifact kind: ${kind}`);
+    const directory = safePath(this.scrumDir, type.directory);
+    assertNoSymlinkPath(this.scrumDir, directory);
+    if (!fs.existsSync(directory)) return [];
+    return fs.readdirSync(directory, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && new RegExp(`^${type.prefix}-\\d{3,}\\.md$`).test(entry.name))
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .map((entry) => this.read(kind, path.basename(entry.name, ".md")));
+  }
+
+  graph() {
+    const records = [];
+    for (const kind of Object.keys(ARTIFACT_TYPES)) {
+      for (const artifact of this.list(kind)) {
+        if (!artifact.record || artifact.errors.length) continue;
+        records.push(artifact.record);
+      }
+    }
+    return graphFromRecords(records);
+  }
+}
+
+module.exports = {
+  ARTIFACT_TYPES,
+  ARTIFACT_TRANSITIONS,
+  ArtifactRepository,
+  METHOD_VERSION,
+  assertNoSymlinkPath,
+  atomicWrite,
+  graphFromRecords,
+  parseArtifact,
+  relativeArtifactPath,
+  safePath,
+  serializeArtifact,
+  sha256,
+  transitionArtifact,
+  validateArtifact,
+  withArtifactLock
+};

package/lib/v2/conformance.js

@@ -0,0 +1,167 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { ArtifactRepository } = require("./artifacts");
+const { ARTIFACT_TYPES, METHOD_VERSION } = require("./schema");
+const { stateIsStale } = require("../runtime/orchestrator");
+const { indexStatus } = require("../memory/index");
+const { extractEvidence } = require("../memory/markdown");
+const { resolveEvidence } = require("../memory/service");
+const { containsSecret } = require("../security/secrets");
+
+const INVARIANTS = Object.freeze([
+  { id: "I-01", summary: "pre-approval work is read-only", tests: ["intake builds bounded context without writing"] },
+  { id: "I-02", summary: "approval creates Task and Run atomically", tests: ["explicit approval creates exactly one linked Task and Run", "approval failure injection rolls back"] },
+  { id: "I-03", summary: "Task is atomic and Sprint only groups evidenced batches", tests: ["migration apply creates linked v2 artifacts", "artifact repository builds explicit Feature Task Sprint Run graph"] },
+  { id: "I-04", summary: "retry preserves prior Runs", tests: ["retry creates a new Run and preserves"] },
+  { id: "I-05", summary: "state transitions are declared and recoverable", tests: ["run state machine follows", "paired transition failure restores"] },
+  { id: "I-06", summary: "guardrails are canonical and cannot be weakened", tests: ["guardrails build preserves canonical v2 rules"] },
+  { id: "I-07", summary: "Markdown is canonical and indexes are disposable", tests: ["SQLite index is disposable"] },
+  { id: "I-08", summary: "AI memory remains candidate", tests: ["AI insights stay candidate"] },
+  { id: "I-09", summary: "confirmed claims require evidence", tests: ["confirmed facts reject missing"] },
+  { id: "I-10", summary: "inactive memory is not active truth", tests: ["stale and expired memory are labeled"] },
+  { id: "I-11", summary: "vault values never leave the vault boundary", tests: ["migration dry-run is read-only and never renders vault", "SQLite index is disposable"] },
+  { id: "I-12", summary: "canonical schemas and identities are valid", tests: ["v2 artifact schemas round-trip", "malformed and mismatched artifacts are rejected"] },
+  { id: "I-13", summary: "generated state exposes staleness", tests: ["generated state includes structured decisions", "approval rejects tampered or stale plans"] },
+  { id: "I-14", summary: "context and retrieval are bounded", tests: ["lean context stays within twenty-five percent", "semantic query caps relation output"] },
+  { id: "I-15", summary: "migration and ordinary update are read-only by default", tests: ["migration dry-run is read-only", "update preflights an ongoing v1 project"] },
+  { id: "I-16", summary: "migration is hashed, idempotent, and reversible", tests: ["migration apply is idempotent and rollback restores"] },
+  { id: "I-17", summary: "ambiguous migration is preserved and warned", tests: ["partial v1 layout is preserved"] },
+  { id: "I-18", summary: "unsafe and partial writes fail safely", tests: ["canonical writes reject traversal and symlink paths", "repository refuses conflicting overwrite"] },
+  { 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"] }
+]);
+
+function finding(severity, code, message, file = null) {
+  return { severity, code, message, ...(file ? { file } : {}) };
+}
+
+function auditProject(projectRoot) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  const findings = [];
+  if (!fs.existsSync(scrumDir) || !fs.lstatSync(scrumDir).isDirectory()) {
+    findings.push(finding("critical", "PROJECT_MISSING", ".scrumrun/ is missing or is not a directory."));
+    return { method: METHOD_VERSION, passed: false, findings, counts: {} };
+  }
+  const marker = path.join(scrumDir, "method.json");
+  try {
+    if (!fs.existsSync(marker) || !fs.lstatSync(marker).isFile()) throw new Error("marker is missing, not a regular file, or is a symbolic link");
+    const value = JSON.parse(fs.readFileSync(marker, "utf8"));
+    if (value.method !== METHOD_VERSION) findings.push(finding("critical", "METHOD_VERSION", `method.json must declare ${METHOD_VERSION}.`, marker));
+  } catch (error) {
+    findings.push(finding("critical", "METHOD_MARKER", `method.json is missing or malformed: ${error.message}`, marker));
+  }
+  for (const relative of ["core.md", "guardrails.md", "config.md", "project.md"]) {
+    const file = path.join(scrumDir, relative);
+    if (!fs.existsSync(file) || !fs.lstatSync(file).isFile()) findings.push(finding("high", "CANONICAL_MISSING", `${relative} is missing or unsafe.`, file));
+  }
+  const guardrailsFile = path.join(scrumDir, "guardrails.md");
+  const guardrails = fs.existsSync(guardrailsFile) && fs.lstatSync(guardrailsFile).isFile() ? fs.readFileSync(guardrailsFile, "utf8") : "";
+  if (!/^## GR-\d{3,}/m.test(guardrails)) findings.push(finding("high", "GUARDRAILS_EMPTY", "No stable-id Guardrail is defined."));
+
+  const repository = new ArtifactRepository(scrumDir);
+  const counts = {};
+  const ids = new Set();
+  const records = {};
+  for (const kind of Object.keys(ARTIFACT_TYPES)) {
+    try {
+      const artifacts = repository.list(kind);
+      records[kind] = artifacts;
+      counts[kind] = artifacts.length;
+      for (const artifact of artifacts) {
+        for (const error of artifact.errors) findings.push(finding("high", "ARTIFACT_INVALID", `${path.basename(artifact.file)}: ${error}`, artifact.file));
+        if (containsSecret(fs.readFileSync(artifact.file, "utf8"))) findings.push(finding("critical", "SECRET_CANONICAL", `Secret-like content detected in ${path.relative(scrumDir, artifact.file)}.`, artifact.file));
+        if (artifact.record && ids.has(artifact.record.id)) findings.push(finding("critical", "ID_DUPLICATE", `Duplicate artifact id: ${artifact.record.id}`));
+        if (artifact.record) ids.add(artifact.record.id);
+      }
+    } catch (error) {
+      findings.push(finding("critical", "ARTIFACT_PATH", `${kind}: ${error.message}`));
+    }
+  }
+  for (const run of records.run || []) {
+    const task = run.record ? repository.read("task", run.record.task) : null;
+    if (run.record && (!task || task.errors.length)) findings.push(finding("high", "RUN_TASK_MISSING", `${run.record.id} references missing or invalid ${run.record.task}.`, run.file));
+    if (run.record && task && !task.errors.length && (run.record.sprint || null) !== (task.record.sprint || null)) {
+      findings.push(finding("high", "RUN_SPRINT_MISMATCH", `${run.record.id}.sprint must match ${task.record.id}.sprint.`, run.file));
+    }
+  }
+  const byId = new Map(Object.values(records).flat().filter((artifact) => artifact.record).map((artifact) => [artifact.record.id, artifact]));
+  for (const task of records.task || []) {
+    for (const [field, prefix] of [["feature", "FEAT"], ["sprint", "SPRINT"]]) {
+      const target = task.record && task.record[field];
+      if (target && (!target.startsWith(`${prefix}-`) || !byId.has(target))) findings.push(finding("high", "RELATION_MISSING", `${task.record.id}.${field} references missing ${target}.`, task.file));
+    }
+  }
+  for (const run of records.run || []) {
+    const sprint = run.record && run.record.sprint;
+    if (sprint && !byId.has(sprint)) findings.push(finding("high", "RELATION_MISSING", `${run.record.id}.sprint references missing ${sprint}.`, run.file));
+  }
+  const attemptsByTask = new Map();
+  for (const run of records.run || []) {
+    if (!run.record || run.errors.length) continue;
+    if (!attemptsByTask.has(run.record.task)) attemptsByTask.set(run.record.task, []);
+    attemptsByTask.get(run.record.task).push(run.record.attempt);
+  }
+  for (const [taskId, attempts] of attemptsByTask) {
+    const ordered = [...attempts].sort((a, b) => a - b);
+    const expected = ordered.map((_, index) => index + 1);
+    if (ordered.length !== new Set(ordered).size || ordered.some((attempt, index) => attempt !== expected[index])) {
+      findings.push(finding("high", "RUN_ATTEMPT_SEQUENCE", `${taskId} Run attempts must be unique and contiguous from 1; found ${ordered.join(", ")}.`));
+    }
+  }
+  for (const sprint of records.sprint || []) {
+    if (!sprint.record || sprint.errors.length) continue;
+    const heading = /^## Tasks[ \t]*$/m.exec(sprint.body);
+    let taskSection = "";
+    if (heading) {
+      const tail = sprint.body.slice(heading.index + heading[0].length);
+      const nextHeading = /^## [^\r\n]+$/m.exec(tail);
+      taskSection = nextHeading ? tail.slice(0, nextHeading.index) : tail;
+    }
+    const listed = new Set([...taskSection.matchAll(/^-\s+(TASK-\d{3,})\s*$/gm)].map((match) => match[1]));
+    const expected = new Set((records.task || [])
+      .filter((task) => task.record && !task.errors.length && task.record.sprint === sprint.record.id)
+      .map((task) => task.record.id));
+    const missing = [...expected].filter((id) => !listed.has(id));
+    const extra = [...listed].filter((id) => !expected.has(id));
+    if (missing.length || extra.length) {
+      findings.push(finding("high", "SPRINT_MEMBERSHIP_MISMATCH", `${sprint.record.id} Tasks projection disagrees with Task.sprint (missing: ${missing.join(", ") || "none"}; extra: ${extra.join(", ") || "none"}).`, sprint.file));
+    }
+  }
+  const confirmed = new Set(["approved", "confirmed", "resolved", "active"]);
+  for (const kind of ["knowledge", "decision", "insight", "dossier"]) {
+    for (const artifact of records[kind] || []) {
+      if (!artifact.record || !confirmed.has(artifact.record.status)) continue;
+      const evidence = extractEvidence(artifact.body);
+      if (!evidence.length) {
+        findings.push(finding("high", "EVIDENCE_MISSING", `${artifact.record.id} is active truth without evidence.`, artifact.file));
+        continue;
+      }
+      for (const reference of evidence) {
+        const result = resolveEvidence(projectRoot, repository, reference);
+        if (!result.resolved) findings.push(finding("high", "EVIDENCE_UNRESOLVED", `${artifact.record.id}: ${reference} (${result.reason}).`, artifact.file));
+      }
+    }
+  }
+  const ignoreFile = path.join(scrumDir, ".gitignore");
+  const ignore = fs.existsSync(ignoreFile) && fs.lstatSync(ignoreFile).isFile() ? fs.readFileSync(ignoreFile, "utf8") : "";
+  for (const pattern of [".cache/", "vault.local.md"]) {
+    if (!ignore.split(/\r?\n/).includes(pattern)) findings.push(finding("high", "IGNORE_MISSING", `${pattern} must be ignored by .scrumrun/.gitignore.`));
+  }
+  try {
+    if (stateIsStale(scrumDir)) findings.push(finding("warning", "STATE_STALE", "state.md is missing or stale; rebuild it before relying on the view."));
+  } catch (error) {
+    findings.push(finding("high", "STATE_UNSAFE", `state cannot be rebuilt safely: ${error.message}`));
+  }
+  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."));
+  } catch (error) {
+    findings.push(finding("high", "INDEX_UNSAFE", `semantic index cannot inspect canonical sources safely: ${error.message}`));
+  }
+  const blocking = findings.filter((item) => ["critical", "high"].includes(item.severity));
+  return { method: METHOD_VERSION, passed: blocking.length === 0, findings, counts, invariants: INVARIANTS.length };
+}
+
+module.exports = { INVARIANTS, auditProject };