scrumrun 2.0.0 → 2.1.0

package/docs/RELEASE.md

@@ -1,7 +1,9 @@
-# ScrumRun 2.0 Release Procedure
+# ScrumRun Package Release Procedure
 
 Publication is owner-gated. Tests, packaging, local commits, and release metadata preparation do not authorize npm publication, git push, tags, GitHub releases, or dist-tag changes.
 
+The npm package/CLI follows SemVer independently from the ScrumRun method contract. For this release, package `2.1.0` implements method `2.0.0`. Published package `2.0.0` is immutable and must never be overwritten or reused.
+
 ## Local release gate
 
 ```bash
@@ -12,11 +14,13 @@ npm pack --dry-run
 npx scrumrun@latest sc review artifact --run   # in a clean v2 fixture/current package equivalent
 ```
 
-Confirm package contents exclude repository-local `.scrumrun/` state, caches, migration records, backups, vaults, tests, and secrets. The `.scrumrun/` directory inside project templates is expected. Confirm `package.json`, README, changelog, SPEC, CORE, skill, migration guide, and tag all name 2.0.0.
+Confirm package contents exclude repository-local `.scrumrun/` state, caches, migration records, backups, vaults, tests, and secrets. The `.scrumrun/` directory inside project templates is expected. Confirm package metadata, README, changelog, tarball filename, checksum, and Git tag agree on `2.1.0`; SPEC, CORE, artifact frontmatter, migration, and installed skill continue to declare method `2.0.0`.
+
+Record the local evidence and residual risks against [`RELEASE-SCORECARD.md`](./RELEASE-SCORECARD.md). Scores describe local readiness only and never replace registry smoke or owner approval.
 
-## Release candidate (owner approval required)
+## Optional registry candidate (separate owner approval required)
 
-1. Set `2.0.0-rc.1` metadata and create a reviewed commit.
+1. Set a new unpublished prerelease such as `2.1.0-rc.1` and create a reviewed commit.
 2. `npm pack`; record tarball SHA-256/integrity.
 3. Publish to `next`, never `latest`:
 
@@ -28,17 +32,20 @@ Confirm package contents exclude repository-local `.scrumrun/` state, caches, mi
 5. Run init, intake/approval, memory confirmation/query, v1 update preflight/apply/rollback, doctor, and uninstall.
 6. Fix findings in a new RC; never replace an already-published version.
 
-## Final promotion (new owner approval required)
+An RC is immutable. Fixes create `rc.2`, `rc.3`, and so on. Skipping an RC does not skip any local, tarball, owner, registry-smoke, or final-promotion gate.
+
+## Final release (new owner approval required)
 
-1. Set `2.0.0`, rerun every local/registry gate, and create the final metadata commit.
-2. Create/push tag `v2.0.0` and publish npm `2.0.0`.
-3. Promote `latest` only after registry smoke tests pass.
-4. Create the GitHub release from `CHANGELOG.md` and link the migration guide.
-5. Verify npm metadata, Git tag/commit, GitHub release, README, and checksums agree.
+1. Set `2.1.0`, rerun every local gate, inspect the exact tarball, and create the final local metadata commit.
+2. Stop and request explicit owner authorization for each external boundary.
+3. Publish npm `2.1.0` to `next` using the reviewed tarball/source commit (`npm publish --tag next`); never publish from a changed worktree and do not move `latest` yet.
+4. Install the registry artifact in a clean fixture and run init, intake/approval, Run lifecycle, memory query, v1 migration apply/rollback, doctor, and uninstall.
+5. Only after registry smoke passes, create/push tag `v2.1.0`, promote/verify `latest` with an explicit dist-tag command, and create the GitHub release from `CHANGELOG.md` with the migration guide and checksum.
+6. Verify npm metadata, dist-tags, Git tag/commit, GitHub release, README, and checksums all agree.
 
 ## Recovery
 
 - RC defect: publish another RC; keep `latest` unchanged.
-- Final package defect before `latest`: do not promote; publish `2.0.1` after correction if 2.0.0 already exists.
-- Defect after `latest`: assess deprecation vs immediate 2.0.1; never overwrite/unpublish without explicit owner decision and npm-policy review.
+- Final package defect before `latest`: do not promote; publish a new patch after correction because `2.1.0` cannot be replaced.
+- Defect after `latest`: assess deprecation vs immediate patch; never overwrite/unpublish without explicit owner decision and current npm-policy review.
 - Migration issue: stop promotion, preserve registry artifact/checksum, use the documented rollback fixture, and publish a corrected version.

package/docs/SCHEMA.md

@@ -46,9 +46,18 @@ Task is the atomic unit. A Task may have zero or one Sprint. A Task may have man
 | Field | Kinds | Presence | Type | Meaning |
 |---|---|---|---|---|
 | `attempt` | run | required | positive integer | monotonic execution-attempt number within one Task |
+| `ledger` | run | optional | integer 1 | canonical Run event-ledger schema; required for newly authored Runs |
 
 Native creation uses the declared initial statuses. Migration may restore a historical non-initial status only with provenance and validation.
 
+## Run event ledger
+
+Newly authored Runs use `ledger: 1`. Their `## Events` section contains append-only JSON event blocks with stable ids in the form `RUN-NNN-EVT-NNN`.
+
+Every event requires `schema`, `id`, contiguous `sequence`, RFC3339 `occurred_at`, `timestamp_precision`, `actor`, `from`, `to`, `reason`, and structured `evidence`. Event types are `transition`, `snapshot`. Evidence kinds are `approval`, `command`, `test`, `file`, `review`, `decision`, `insight`, `risk`, `note`, `migration`, `legacy`.
+
+A native ledger begins with `created → executing`; an evidenced migration `snapshot` may establish one historical baseline without inventing missing transitions. Event order, transition legality, final status, updated date, and completion evidence are machine-validated. Run owns the event history; Task stores its intended scope and synchronized current status without copying Run events.
+
 ## Truth questions
 
 - **feature:** Why does this initiative exist?

package/docs/TROUBLESHOOTING.md

@@ -25,8 +25,20 @@ Rollback detected post-migration work that it would erase. Copy/export wanted ch
 npx scrumrun@latest sc knowledge map --build
 ```
 
+Fresh projections include a source fingerprint and a watch fingerprint. A matching watch avoids a full read. If file metadata changed, ScrumRun hashes canonical/source content before deciding whether the projection is actually stale. `check: "schema"` means the disposable SQLite format changed and one rebuild is required; `check: "hash"` means the safe fallback was used.
+
 Stale generated views are warnings, not canonical corruption.
 
+## Doctor reports `TRANSACTION_PENDING`
+
+An approved multi-file mutation was interrupted after its durable journal was prepared. Ordinary doctor/audit is read-only and leaves the evidence untouched. Either retry the same approved operation, which recovers before writing, or explicitly run:
+
+```bash
+npx scrumrun@latest doctor codex --recover --strict
+```
+
+Prepared transactions restore their original bytes; committed transactions verify the applied bytes and finalize. Recovery refuses if a target changed to content matching neither journal side, because that would overwrite later owner work. Receipts contain hashes and outcomes, not file contents.
+
 ## SQLite is missing/corrupt
 
 Delete or clear only the disposable cache:

package/lib/commands/manifest.js

@@ -9,7 +9,16 @@ const nouns = Object.freeze({
       task: ["--add [--type fix] [--status backlog]", "--list", "--show", "--run", "--audit", "--cancel", "--retry"],
       sprint: ["--add", "--list", "--show", "--start", "--complete", "--block"],
       feature: ["--add", "--list", "--show", "--activate", "--complete"],
-      run: ["--list", "--show", "--validate", "--learn", "--complete", "--resume", "--fail", "--block"],
+      run: [
+        "--list",
+        "--show",
+        "--validate [--note] [--evidence] [--command] [--test] [--file] [--review] [--actor] [--at]",
+        "--learn [--note] [--evidence] [--decision] [--insight] [--file] [--actor] [--at]",
+        "--complete [--note] [--evidence] [--review] [--test] [--file] [--actor] [--at]",
+        "--resume [--note] [--evidence] [--risk] [--actor] [--at]",
+        "--fail [--note] [--evidence] [--risk] [--test] [--actor] [--at]",
+        "--block [--note] [--evidence] [--risk] [--actor] [--at]"
+      ],
       intake: ["<request>", "--request", "--approve"],
       challenge: ["<question>"]
     }
@@ -50,7 +59,7 @@ const nouns = Object.freeze({
       init: ["--local", "--shared", "--lean", "--no-agent-hint", "--force"],
       update: ["all [--migrate]", "codex [--migrate]", "opencode [--migrate]", "claude [--migrate]"],
       migrate: ["--to 2 --dry-run", "--to 2 --apply", "--to 2 --rollback"],
-      doctor: ["all [--strict]", "codex [--strict]", "opencode [--strict]", "claude [--strict]"],
+      doctor: ["all [--strict] [--recover]", "codex [--strict] [--recover]", "opencode [--strict] [--recover]", "claude [--strict] [--recover]"],
       uninstall: ["--force"],
       help: ["<topic>"]
     }

package/lib/commands/render.js

@@ -31,7 +31,10 @@ ${grammarLines().join("\n")}
 - Intake, contextualization, policy, risk, classification, and planning are read-only until explicit approval.
 - Approved work creates/updates a Task and creates a Run; a Sprint only groups Tasks when a real timebox/batch exists.
 - Run execution follows \`executing → validating → learning → completed|failed|blocked\`.
+- Run owns one structured, evidenced event ledger; Task synchronizes current status without copying Run history.
+- Linked Task/Run writes use a durable recovery journal; audit reports pending recovery and never repairs without explicit authorization.
 - \`guardrails.md\` is canonical project policy; \`golden-rules.md\` is v1 compatibility only.
+- Evaluate active Guardrails as \`passed\`, \`blocked\`, or \`deferred\`; cite exact \`GR-NNN\` ids and keep deferred execution gates visible.
 - Knowledge/Decision/Insight records require evidence; AI-proposed Insights remain \`candidate\` until confirmed.
 - Never print vault values or write before approval.
 - Unknown nouns, subjects, actions, ids, or ambiguous approval must produce a deterministic explanation, never a guessed mutation.

package/lib/memory/index.js

@@ -5,11 +5,14 @@ const path = require("node:path");
 const { DatabaseSync } = require("node:sqlite");
 const { ARTIFACT_TYPES, ArtifactRepository, assertNoSymlinkPath, atomicWrite, sha256 } = require("../v2/artifacts");
 const { extractEvidence, extractRelations } = require("./markdown");
-const { scanProject } = require("../code-intel/scanner");
+const { JavaScriptAdapter } = require("../code-intel/javascript");
+const { scanProject, sourceFiles } = require("../code-intel/scanner");
 const { DEFAULT_CONTEXT_RESULTS, DEFAULT_RELATIONS_PER_RESULT, MAX_CONTEXT_RESULTS, MAX_RELATIONS_PER_RESULT } = require("../runtime/budgets");
 const { containsSecret } = require("../security/secrets");
+const { canonicalWatchSnapshot, fileWatchSnapshot } = require("../runtime/canonical-snapshot");
 
 const CACHE_RELATIVE = path.join(".cache", "semantic-index.sqlite");
+const INDEX_SCHEMA_VERSION = 3;
 const INACTIVE = new Set(["rejected", "invalidated", "deprecated", "archived"]);
 
 function indexPath(projectRoot) {
@@ -46,7 +49,7 @@ function memoryFingerprint(scrumDir) {
   return sha256(rows.join("\n"));
 }
 
-function sourceSnapshot(projectRoot) {
+function sourceSnapshot(projectRoot, { watch = null } = {}) {
   const scrumDir = path.join(projectRoot, ".scrumrun");
   const artifacts = canonicalArtifacts(scrumDir);
   const code = scanProject(projectRoot);
@@ -54,8 +57,26 @@ function sourceSnapshot(projectRoot) {
   const codeRows = code.nodes
     .filter((node) => node.kind === "module")
     .map((node) => `${node.path}\0${node.fingerprint}`);
-  const fingerprint = sha256([...artifactRows, ...codeRows, `commit\0${code.commit || "unavailable"}`].sort().join("\n"));
-  return { artifacts, code, fingerprint };
+  const fingerprint = sha256([...artifactRows, ...codeRows].sort().join("\n"));
+  return { artifacts, code, fingerprint, watch: watch || sourceWatchSnapshot(projectRoot) };
+}
+
+function sourceWatchSnapshot(projectRoot) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  const canonical = canonicalWatchSnapshot(scrumDir);
+  const adapters = [new JavaScriptAdapter()];
+  const discovered = sourceFiles(path.resolve(projectRoot), adapters);
+  const code = fileWatchSnapshot(projectRoot, discovered.files.map((item) => item.file), adapters.map((adapter) => `adapter\0${adapter.id}`));
+  const rows = [
+    ...canonical.rows.map((row) => `canonical\0${row}`),
+    ...code.rows.map((row) => `code\0${row}`)
+  ];
+  return {
+    fingerprint: sha256(rows.sort().join("\n")),
+    canonicalFiles: canonical.files,
+    sourceFiles: code.files,
+    warnings: discovered.warnings
+  };
 }
 
 function explicitEdges(artifact) {
@@ -380,11 +401,13 @@ function rebuildIndex(projectRoot) {
       const insertInvalidation = database.prepare("INSERT INTO invalidations(artifact_id, reason, reference, artifact_hash) VALUES (?, ?, ?, ?)");
       for (const item of derived.invalidations) insertInvalidation.run(item.artifactId, item.reason, item.reference, item.artifactHash);
       const metadata = database.prepare("INSERT INTO metadata(key, value) VALUES (?, ?)");
-      metadata.run("schema_version", "2");
+      metadata.run("schema_version", String(INDEX_SCHEMA_VERSION));
       metadata.run("method_version", "2.0.0");
       metadata.run("source_fingerprint", snapshot.fingerprint);
+      metadata.run("source_watch_fingerprint", snapshot.watch.fingerprint);
       metadata.run("artifact_count", String(artifacts.length));
       metadata.run("code_node_count", String(remapped.nodes.length));
+      metadata.run("source_file_count", String(snapshot.watch.sourceFiles));
       metadata.run("code_adapter", snapshot.code.adapterIds.join(","));
       database.exec("COMMIT");
     } catch (error) {
@@ -399,7 +422,7 @@ function rebuildIndex(projectRoot) {
     if (fs.existsSync(temp)) fs.rmSync(temp, { force: true });
     throw error;
   }
-  return { file: target, fingerprint: snapshot.fingerprint, artifacts: artifacts.length, codeNodes: remapped.nodes.length, warnings: snapshot.code.warnings };
+  return { file: target, fingerprint: snapshot.fingerprint, watchFingerprint: snapshot.watch.fingerprint, artifacts: artifacts.length, codeNodes: remapped.nodes.length, warnings: [...snapshot.code.warnings, ...snapshot.watch.warnings] };
 }
 
 function indexStatus(projectRoot) {
@@ -409,9 +432,26 @@ function indexStatus(projectRoot) {
   try {
     assertNoSymlinkPath(path.join(projectRoot, ".scrumrun"), file);
     database = new DatabaseSync(file, { readOnly: true });
-    const row = database.prepare("SELECT value FROM metadata WHERE key = 'source_fingerprint'").get();
-    const actual = sourceSnapshot(projectRoot).fingerprint;
-    return { exists: true, stale: !row || row.value !== actual, file, stored: row && row.value, actual };
+    const metadata = new Map(database.prepare("SELECT key, value FROM metadata").all().map((row) => [row.key, row.value]));
+    const stored = metadata.get("source_fingerprint") || null;
+    if (metadata.get("schema_version") !== String(INDEX_SCHEMA_VERSION) || !metadata.get("source_watch_fingerprint")) {
+      return { exists: true, stale: true, file, stored, check: "schema", reason: `semantic index schema ${INDEX_SCHEMA_VERSION} rebuild required` };
+    }
+    const watch = sourceWatchSnapshot(projectRoot);
+    if (metadata.get("source_watch_fingerprint") === watch.fingerprint) {
+      return { exists: true, stale: false, file, stored, actual: stored, watch: watch.fingerprint, check: "metadata" };
+    }
+    const actual = sourceSnapshot(projectRoot, { watch }).fingerprint;
+    return {
+      exists: true,
+      stale: !stored || stored !== actual,
+      file,
+      stored,
+      actual,
+      watch: watch.fingerprint,
+      check: "hash",
+      reason: stored === actual ? "file metadata changed but semantic content is unchanged" : "canonical or source content changed"
+    };
   } catch (error) {
     return { exists: true, stale: true, file, error: error.message };
   } finally {
@@ -571,7 +611,8 @@ function writeMap(projectRoot, { nodeLimit = 200, edgeLimit = 400 } = {}) {
   const body = [
     "# ScrumRun Project Map",
     "",
-    `Generated: ${new Date().toISOString().slice(0, 10)}`,
+    "Projection schema: 1",
+    `Generated: ${new Date().toISOString()}`,
     `Source fingerprint: ${current.stored}`,
     "Authority: none; rebuild from canonical artifacts and source code.",
     "",
@@ -597,4 +638,22 @@ function writeMap(projectRoot, { nodeLimit = 200, edgeLimit = 400 } = {}) {
   return { file, nodes: graph.nodes.length, edges: graph.edges.length, fingerprint: current.stored };
 }
 
-module.exports = { CACHE_RELATIVE, graphIndex, indexPath, indexStatus, memoryFingerprint, queryIndex, rebuildIndex, sourceSnapshot, writeMap };
+function mapStatus(projectRoot, { semanticStatus = null } = {}) {
+  const file = path.join(projectRoot, ".scrumrun", "map.md");
+  if (!fs.existsSync(file)) return { exists: false, stale: true, file, reason: "map.md is missing" };
+  try {
+    assertNoSymlinkPath(path.join(projectRoot, ".scrumrun"), file);
+    if (!fs.lstatSync(file).isFile()) return { exists: true, stale: true, file, reason: "map.md is not a regular file" };
+    const content = fs.readFileSync(file, "utf8");
+    const stored = (content.match(/^Source fingerprint:\s*([a-f0-9]{64})$/m) || [])[1] || null;
+    if (!stored) return { exists: true, stale: true, file, stored, reason: "map.md has no source fingerprint" };
+    const semantic = semanticStatus || indexStatus(projectRoot);
+    if (!semantic.exists) return { exists: true, stale: true, file, stored, reason: "semantic index is missing" };
+    if (semantic.stale) return { exists: true, stale: true, file, stored, reason: semantic.reason || "semantic index is stale" };
+    return { exists: true, stale: stored !== semantic.stored, file, stored, actual: semantic.stored, reason: stored === semantic.stored ? null : "map fingerprint differs from the semantic index" };
+  } catch (error) {
+    return { exists: true, stale: true, file, error: error.message, reason: "map freshness check failed" };
+  }
+}
+
+module.exports = { CACHE_RELATIVE, INDEX_SCHEMA_VERSION, graphIndex, indexPath, indexStatus, mapStatus, memoryFingerprint, queryIndex, rebuildIndex, sourceSnapshot, sourceWatchSnapshot, writeMap };

package/lib/runtime/budgets.js

@@ -7,10 +7,14 @@ const MAX_CONTEXT_RESULTS = 100;
 const DEFAULT_CONTEXT_RESULTS = 10;
 const MAX_RELATIONS_PER_RESULT = 100;
 const DEFAULT_RELATIONS_PER_RESULT = 40;
+const KERNEL_LIFECYCLE_MAX_MS = 1500;
+const INDEX_STATUS_100_MAX_MS = 2500;
 
 module.exports = {
   DEFAULT_CONTEXT_RESULTS,
   DEFAULT_RELATIONS_PER_RESULT,
+  INDEX_STATUS_100_MAX_MS,
+  KERNEL_LIFECYCLE_MAX_MS,
   LEAN_CONTROL_CONTEXT_MAX_CHARS,
   LEAN_CONTROL_CONTEXT_MAX_RATIO,
   MAX_CONTEXT_RESULTS,

package/lib/runtime/canonical-snapshot.js

@@ -0,0 +1,110 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { ARTIFACT_TYPES, ArtifactRepository, assertNoSymlinkPath, sha256 } = require("../v2/artifacts");
+const { containsSecret } = require("../security/secrets");
+
+const CONTROL_FILES = Object.freeze(["guardrails.md", "config.md", "project.md", "method.json"]);
+
+function posix(value) {
+  return value.split(path.sep).join("/");
+}
+
+function read(file) {
+  return fs.existsSync(file) && fs.lstatSync(file).isFile() ? fs.readFileSync(file, "utf8") : "";
+}
+
+function artifactSnapshot(scrumDir) {
+  const repository = new ArtifactRepository(scrumDir);
+  const records = {};
+  const hashes = [];
+  const warnings = [];
+  for (const kind of Object.keys(ARTIFACT_TYPES)) {
+    records[kind] = repository.list(kind).map((artifact) => {
+      const relative = posix(path.relative(scrumDir, artifact.file));
+      const content = read(artifact.file);
+      hashes.push(`${relative}\0${sha256(content)}`);
+      if (containsSecret(content)) {
+        warnings.push(`Secret-like content detected in canonical artifact: ${relative}`);
+        return { id: artifact.record ? artifact.record.id : path.basename(artifact.file, ".md"), status: "unsafe", title: "[redacted]" };
+      }
+      return artifact.record ? {
+        id: artifact.record.id,
+        status: artifact.record.status,
+        title: ((artifact.body || "").match(/^# ([^\r\n]+)/m) || [])[1] || artifact.record.id,
+        task: artifact.record.task || null,
+        sprint: artifact.record.sprint || null,
+        feature: artifact.record.feature || null
+      } : { id: path.basename(artifact.file, ".md"), status: "invalid", errors: artifact.errors };
+    });
+  }
+  return { records, hashes, warnings };
+}
+
+function canonicalFingerprint(scrumDir, artifactHashes = null) {
+  const hashes = artifactHashes || artifactSnapshot(scrumDir).hashes;
+  const controls = CONTROL_FILES.map((relative) => {
+    const file = path.join(scrumDir, relative);
+    const exists = fs.existsSync(file) && fs.lstatSync(file).isFile();
+    return `${relative}\0${exists ? sha256(fs.readFileSync(file)) : "missing"}`;
+  });
+  return sha256([...controls, ...hashes].sort().join("\n"));
+}
+
+function statRow(root, file) {
+  assertNoSymlinkPath(root, file);
+  const stat = fs.statSync(file, { bigint: true });
+  if (!stat.isFile()) throw new Error(`Projection source is not a regular file: ${posix(path.relative(root, file))}`);
+  return [
+    posix(path.relative(root, file)),
+    stat.size,
+    stat.mtimeNs,
+    stat.ctimeNs,
+    stat.ino,
+    stat.dev
+  ].join("\0");
+}
+
+function canonicalWatchSnapshot(scrumDir) {
+  const root = path.resolve(scrumDir);
+  const rows = [];
+  let files = 0;
+  for (const relative of CONTROL_FILES) {
+    const file = path.join(root, relative);
+    if (!fs.existsSync(file)) rows.push(`${relative}\0missing`);
+    else {
+      rows.push(statRow(root, file));
+      files++;
+    }
+  }
+  for (const type of Object.values(ARTIFACT_TYPES)) {
+    const directory = path.join(root, type.directory);
+    assertNoSymlinkPath(root, directory);
+    if (!fs.existsSync(directory)) continue;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+      if (!new RegExp(`^${type.prefix}-\\d{3,}\\.md$`).test(entry.name)) continue;
+      const file = path.join(directory, entry.name);
+      if (!entry.isFile()) throw new Error(`Canonical projection source is not a regular file: ${posix(path.relative(root, file))}`);
+      rows.push(statRow(root, file));
+      files++;
+    }
+  }
+  return { fingerprint: sha256(rows.sort().join("\n")), files, rows };
+}
+
+function fileWatchSnapshot(root, files, extraRows = []) {
+  const resolvedRoot = path.resolve(root);
+  const rows = files.map((file) => statRow(resolvedRoot, path.resolve(file)));
+  rows.push(...extraRows.map(String));
+  return { fingerprint: sha256(rows.sort().join("\n")), files: files.length, rows };
+}
+
+module.exports = {
+  CONTROL_FILES,
+  artifactSnapshot,
+  canonicalFingerprint,
+  canonicalWatchSnapshot,
+  fileWatchSnapshot,
+  statRow
+};

package/lib/runtime/context.js

@@ -2,9 +2,10 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
-const { ARTIFACT_TYPES, ArtifactRepository, sha256 } = require("../v2/artifacts");
 const { readProjectModel } = require("../v2/project-store");
 const { containsSecret } = require("../security/secrets");
+const { parseGuardrails } = require("./policy-engine");
+const { artifactSnapshot, canonicalFingerprint } = require("./canonical-snapshot");
 
 const EXCLUDED_ROOT_ENTRIES = new Set([".git", ".scrumrun", "node_modules", "dist", "build", "coverage"]);
 
@@ -40,51 +41,10 @@ function projectScan(projectRoot) {
   return { project: path.basename(projectRoot), entries, package: packageSummary };
 }
 
-function guardrailRecords(content) {
-  const headings = [...content.matchAll(/^## (GR-\d{3,})\s*[-—:]\s*([^\r\n]+)$/gm)];
-  return headings.map((heading, index) => {
-    const end = index + 1 < headings.length ? headings[index + 1].index : content.length;
-    const block = content.slice(heading.index, end);
-    const rule = (block.match(/^Rule:\s*(.+)$/m) || [])[1] || heading[2];
-    const status = ((block.match(/^Status:\s*(.+)$/m) || [])[1] || "active").trim();
-    return { id: heading[1], title: heading[2].trim(), rule: capped(rule.trim(), 500), status };
-  });
-}
-
-function artifactSnapshot(scrumDir) {
-  const repository = new ArtifactRepository(scrumDir);
-  const records = {};
-  const hashes = [];
-  const warnings = [];
-  for (const kind of Object.keys(ARTIFACT_TYPES)) {
-    records[kind] = repository.list(kind).map((artifact) => {
-      const relative = path.relative(scrumDir, artifact.file).split(path.sep).join("/");
-      const content = read(artifact.file);
-      hashes.push(`${relative}\0${sha256(content)}`);
-      if (containsSecret(content)) {
-        warnings.push(`Secret-like content detected in canonical artifact: ${relative}`);
-        return { id: artifact.record ? artifact.record.id : path.basename(artifact.file, ".md"), status: "unsafe", title: "[redacted]" };
-      }
-      return artifact.record ? {
-        id: artifact.record.id,
-        status: artifact.record.status,
-        title: ((artifact.body || "").match(/^# ([^\r\n]+)/m) || [])[1] || artifact.record.id,
-        task: artifact.record.task || null,
-        sprint: artifact.record.sprint || null,
-        feature: artifact.record.feature || null
-      } : { id: path.basename(artifact.file, ".md"), status: "invalid", errors: artifact.errors };
-    });
-  }
-  return { records, hashes, warnings };
-}
+const guardrailRecords = parseGuardrails;
 
 function contextFingerprint(scrumDir, artifactHashes) {
-  const canonical = ["guardrails.md", "config.md", "project.md", "method.json"]
-    .map((relative) => {
-      const content = read(path.join(scrumDir, relative));
-      return `${relative}\0${content ? sha256(content) : "missing"}`;
-    });
-  return sha256([...canonical, ...artifactHashes].sort().join("\n"));
+  return canonicalFingerprint(scrumDir, artifactHashes);
 }
 
 function buildContextPackage(projectRoot, request) {
@@ -138,4 +98,4 @@ function buildContextPackage(projectRoot, request) {
   };
 }
 
-module.exports = { buildContextPackage, contextFingerprint, guardrailRecords, projectScan };
+module.exports = { artifactSnapshot, buildContextPackage, contextFingerprint, guardrailRecords, projectScan };