From 3de9257a459d2a5d03f2ddb9099145d0ace39671 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 10 Jul 2026 08:18:15 +0000
Subject: [PATCH 01/12] feat(atlas): config artifacts join the impact graph
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI workflows (.github is now walked), manifests, and Dockerfiles become
config: nodes with references edges to the code paths they name — a code
change now lists the configs it can break. Lockfiles stay out (generated
churn). RULES/DOC_EXTS/CODE_EXTS/CONFIG_* are exported as the ONE
classification registry the completion gate and docs sweep reuse.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
---
 src/atlas.js       | 56 ++++++++++++++++++++++++++++++++++++++++++----
 test/atlas.test.js | 50 ++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 101 insertions(+), 5 deletions(-)

diff --git a/src/atlas.js b/src/atlas.js
index 6a1418e..bc27874 100644
--- a/src/atlas.js
+++ b/src/atlas.js
@@ -12,7 +12,7 @@ const JS_RULES = [
   { re: /(?:export\s+)?class\s+([A-Za-z_$][\w$]*)/g, kind: "class" },
   { re: /(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/g, kind: "const" },
 ];
-const RULES = {
+export const RULES = {
   ".js": JS_RULES,
   ".jsx": JS_RULES,
   ".ts": JS_RULES,
@@ -38,13 +38,31 @@ const RULES = {
 // doc node + `references` edges to the code it names), never by the symbol RULES.
 // This is the missing code→doc half of impact: change a symbol, its docs show up
 // as dependents.
-const DOC_EXTS = new Set([".md"]);
+export const DOC_EXTS = new Set([".md"]);
 
 // Docs excluded from the graph: generated files the Stop hook rewrites (AGENTS.md
 // auto-sync would re-stale the atlas after every session) and the changelog, which
 // churns on every change and whose references describe HISTORY, not current code.
 const DOC_SKIP = /^(AGENTS|CLAUDE|GEMINI|CHANGELOG)\.md$/i;
 
+// The extensions the symbol RULES parse — exported as the ONE code-class registry so
+// the completion gate and docs sweep classify paths from the same table the graph is
+// built from, instead of growing their own regex lists.
+export const CODE_EXTS = new Set(Object.keys(RULES));
+
+// Config artifacts — CI workflows, manifests, build/deploy wiring. They name code
+// paths, so a code change must surface the configs that point at it (the missing
+// config half of impact). Lockfiles are generated churn, never sources of truth.
+export const CONFIG_EXTS = new Set([".json", ".yml", ".yaml", ".toml"]);
+export const CONFIG_FILE_RE = /^Dockerfile$|\.config\.[\w.]+$/;
+const CONFIG_SKIP = /^package-lock\.json$|[-.]lock(\.[\w]+)?$|\.cache\.json$/i;
+
+/** True when a basename is a config artifact worth graphing (lockfiles excluded). */
+export function isConfigFile(name) {
+  if (CONFIG_SKIP.test(name)) return false;
+  return CONFIG_EXTS.has(extname(name)) || CONFIG_FILE_RE.test(name);
+}
+
 const IMPORT_RE =
   /(?:import\s+(?:[^"'\n]+\s+from\s+)?["']([^"']+)["']|require\(["']([^"']+)["']\)|^\s*(?:from\s+([\w.]+)\s+)?import\s+([\w*,\s]+))/gm;
 const BUILTINS = new Set([
@@ -96,7 +114,9 @@ function walk(dir, files, cap) {
     return;
   }
   for (const name of entries) {
-    if (IGNORE_DIRS.has(name) || name.startsWith(".")) continue;
+    // Dot-entries stay out of the graph — except `.github`, whose workflows are config
+    // artifacts that name code paths (a CI file IS a dependent of the code it runs).
+    if (IGNORE_DIRS.has(name) || (name.startsWith(".") && name !== ".github")) continue;
     const path = join(dir, name);
     let st;
     try {
@@ -106,7 +126,9 @@ function walk(dir, files, cap) {
     }
     if (st.isDirectory()) walk(path, files, cap);
     else if (
-      (RULES[extname(name)] || (DOC_EXTS.has(extname(name)) && !DOC_SKIP.test(name))) &&
+      (RULES[extname(name)] ||
+        (DOC_EXTS.has(extname(name)) && !DOC_SKIP.test(name)) ||
+        isConfigFile(name)) &&
       files.length < cap
     )
       files.push(path);
@@ -164,6 +186,31 @@ function extractDoc(rel, text) {
   return { symbols: [], nodes: [doc], edges, hash: hash(text) };
 }
 
+// A config artifact (CI workflow, manifest, Dockerfile) becomes ONE config node whose
+// `references` edges point at the code files it names — quoted or bare, since YAML and
+// Dockerfiles reference paths without quotes (`run: node src/cli.js`). Reverse-BFS then
+// lists the configs a code change can break, closing the config half of blast radius.
+function extractConfig(rel, text) {
+  const cfg = { id: `config:${rel}`, name: rel, kind: "config", file: rel, line: 1 };
+  const edges = [];
+  const seen = new Set();
+  for (const m of text.matchAll(/[A-Za-z0-9_.@-]+(?:[/\\][A-Za-z0-9_.@-]+)*/g)) {
+    const tok = m[0].replace(/^\.\//, "");
+    if (!RULES[extname(tok)]) continue; // only path-like tokens ending in a code extension
+    const target = `module:${moduleId(tok)}`;
+    if (seen.has(target)) continue;
+    seen.add(target);
+    edges.push({
+      source: cfg.id,
+      target,
+      kind: "references",
+      confidence: 0.8,
+      line: lineOf(text, m.index),
+    });
+  }
+  return { symbols: [], nodes: [cfg], edges, hash: hash(text) };
+}
+
 function extractFile(path, root, preRead) {
   const ext = extname(path);
   const rules = RULES[ext];
@@ -177,6 +224,7 @@ function extractFile(path, root, preRead) {
     }
   }
   if (DOC_EXTS.has(ext)) return extractDoc(rel, text);
+  if (isConfigFile(rel.split(/[/\\]/).pop() || "")) return extractConfig(rel, text);
 
   const mod = {
     id: `module:${moduleId(rel)}`,
diff --git a/test/atlas.test.js b/test/atlas.test.js
index fb73ce3..b4a5880 100644
--- a/test/atlas.test.js
+++ b/test/atlas.test.js
@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { existsSync, mkdtempSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { test } from "node:test";
@@ -115,3 +115,51 @@ test("markdown docs become graph nodes whose references make them impact depende
   const byFile = impact(atlas, "src.js");
   assert.ok(byFile.impactedFiles.includes("GUIDE.md"), JSON.stringify(byFile.impactedFiles));
 });
+
+test("config artifacts become graph nodes; a code change lists its CI/config dependents", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-atlas-"));
+  mkdirSync(join(root, ".github", "workflows"), { recursive: true });
+  mkdirSync(join(root, "src"), { recursive: true });
+  writeFileSync(join(root, "src", "val.js"), "export function validate(x){ return !!x }\n");
+  writeFileSync(
+    join(root, ".github", "workflows", "ci.yml"),
+    "jobs:\n  test:\n    steps:\n      - run: node src/val.js\n",
+  );
+  writeFileSync(join(root, "Dockerfile"), "FROM node:20\nCOPY src/val.js /app/val.js\n");
+  writeFileSync(join(root, "package-lock.json"), JSON.stringify({ lockfileVersion: 3 }));
+  mkdirSync(join(root, ".hidden"));
+  writeFileSync(join(root, ".hidden", "x.yml"), "a: src/val.js\n");
+  const atlas = build({ root });
+  assert.ok(
+    atlas.nodes.some((n) => n.kind === "config" && n.file === ".github/workflows/ci.yml"),
+    "workflow is a config node",
+  );
+  assert.ok(
+    atlas.nodes.some((n) => n.kind === "config" && n.file === "Dockerfile"),
+    "Dockerfile is a config node",
+  );
+  assert.ok(
+    !atlas.nodes.some((n) => n.file === "package-lock.json"),
+    "lockfiles are generated churn, never graphed",
+  );
+  assert.ok(
+    !atlas.nodes.some((n) => n.file?.startsWith(".hidden")),
+    "other dot-dirs stay out of the walk",
+  );
+  const r = impact(atlas, "src/val.js");
+  assert.ok(r.impactedFiles.includes(".github/workflows/ci.yml"), JSON.stringify(r.impactedFiles));
+  assert.ok(
+    r.impactedFiles.includes("Dockerfile"),
+    "the Dockerfile copying the file is a dependent",
+  );
+});
+
+test("a config edit flips isStale (configs are tracked like any other artifact)", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-atlas-"));
+  writeFileSync(join(root, "app.js"), "export function main(){}\n");
+  writeFileSync(join(root, "deploy.yml"), "run: node app.js\n");
+  const atlas = build({ root });
+  assert.equal(isStale(root, atlas), false);
+  writeFileSync(join(root, "deploy.yml"), "run: node app.js --prod\n");
+  assert.equal(isStale(root, atlas), true, "config content change detected");
+});

From 7292636a9902c094ff382415a40bec9f33cea0f2 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 10 Jul 2026 08:18:15 +0000
Subject: [PATCH 02/12] =?UTF-8?q?feat(memory):=20forge=20handoff=20+=20for?=
 =?UTF-8?q?ge=20decide=20=E2=80=94=20state=20that=20survives=20sessions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

handoff rewrites .forge/state.md (bounded ≤150 lines: goal/phase, criteria,
done, next, gotchas, recorded assumptions, in-progress git files) — snapshot
semantics, injected at every session start so the next session resumes
instead of re-assuming. decide appends ADR-lite D-#### entries to
.forge/decisions.md (log semantics — supersede, never edit) and mints a
machine-readable decision ledger twin. Both refuse secrets at write.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
---
 src/decide.js        |  78 +++++++++++++++++++++
 src/handoff.js       | 161 +++++++++++++++++++++++++++++++++++++++++++
 test/decide.test.js  |  63 +++++++++++++++++
 test/handoff.test.js |  95 +++++++++++++++++++++++++
 4 files changed, 397 insertions(+)
 create mode 100644 src/decide.js
 create mode 100644 src/handoff.js
 create mode 100644 test/decide.test.js
 create mode 100644 test/handoff.test.js

diff --git a/src/decide.js b/src/decide.js
new file mode 100644
index 0000000..66dc136
--- /dev/null
+++ b/src/decide.js
@@ -0,0 +1,78 @@
+// forge decide — the append-only, human-readable decision log. Lessons capture
+// corrections and the ledger captures machine claims, but "we picked X over Y because Z"
+// had no home the NEXT session reads — so sessions re-decided (or contradicted) settled
+// choices. .forge/decisions.md is ADR-lite: one line per decision, append-only. Append
+// is one syscall, merge-friendly, and never rewrites history — a decision that stops
+// being true gets a new entry, not an edit.
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { BRAND } from "./brand.js";
+import { mintClaim } from "./ledger.js";
+import { putClaim } from "./ledger_store.js";
+import { hasSecret } from "./secrets.js";
+import { gitAuthor } from "./util.js";
+
+export const decisionsPath = (root) => join(root, ".forge", "decisions.md");
+
+const LINE_RE = /^- \*\*D-(\d{4,})\*\* \((\d{4}-\d{2}-\d{2})\): (.*)$/;
+
+/** Parse decision entries out of the log; unparseable lines are ignored, never fatal. */
+export function parseDecisions(text) {
+  const out = [];
+  for (const line of String(text ?? "").split("\n")) {
+    const m = LINE_RE.exec(line.trim());
+    if (m) out.push({ n: Number(m[1]), id: `D-${m[1]}`, date: m[2], text: m[3] });
+  }
+  return out;
+}
+
+/** The most recent `limit` decisions, oldest→newest (chronological log order). */
+export function listDecisions(root, { limit = 10 } = {}) {
+  try {
+    const p = decisionsPath(root);
+    if (!existsSync(p)) return [];
+    return parseDecisions(readFileSync(p, "utf8")).slice(-limit);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Append one decision ("<what was decided> — <why>"). Refuses secrets (same rule as
+ * every forge store). Also mints a `decision` ledger claim — the machine-readable twin —
+ * best-effort only: the markdown line is the source of truth and must never fail
+ * because the ledger couldn't be written.
+ */
+export function appendDecision(root, text, { t = Date.now() } = {}) {
+  const body = String(text ?? "")
+    .trim()
+    .replace(/\s+/g, " ");
+  if (!body) return { ok: false, reason: "empty decision — say what was decided and why" };
+  if (hasSecret(body))
+    return { ok: false, reason: "refused: decision looks like it contains a secret/credential" };
+  mkdirSync(join(root, ".forge"), { recursive: true });
+  const p = decisionsPath(root);
+  let existing = "";
+  try {
+    existing = existsSync(p) ? readFileSync(p, "utf8") : "";
+  } catch {}
+  const prior = parseDecisions(existing);
+  const n = prior.length ? Math.max(...prior.map((d) => d.n)) + 1 : 1;
+  const id = `D-${String(n).padStart(4, "0")}`;
+  const date = new Date(t).toISOString().slice(0, 10);
+  const header = existing.trim()
+    ? ""
+    : `# Decisions\n\nAppend-only — supersede an old choice with a NEW entry (\`${BRAND.cli} decide\`), never an edit.\n\n`;
+  appendFileSync(p, `${header}- **${id}** (${date}): ${body}\n`);
+  try {
+    const minted = mintClaim({
+      kind: "decision",
+      body: { id, text: body },
+      scope: { level: "repo" },
+      provenance: { author: gitAuthor() },
+      t: Math.floor(t / 86_400_000),
+    });
+    if (minted.ok) putClaim(join(root, ".forge", "ledger"), minted.claim);
+  } catch {}
+  return { ok: true, id, text: body };
+}
diff --git a/src/handoff.js b/src/handoff.js
new file mode 100644
index 0000000..559a309
--- /dev/null
+++ b/src/handoff.js
@@ -0,0 +1,161 @@
+// forge handoff — the bounded session-state checkpoint. goal.md holds the objective and
+// lessons hold corrections, but "what got done, what's next, what bit us" died with each
+// session — the next one re-derived it or, worse, assumed. state.md is a REWRITTEN
+// (never appended) snapshot injected at every session start: bounded compression, so the
+// loader's token cost stays constant over the project's life while total knowledge grows.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { BRAND } from "./brand.js";
+import { getGoal } from "./goal.js";
+import { hasSecret } from "./secrets.js";
+
+export const statePath = (root) => join(root, ".forge", "state.md");
+
+function git(root, args) {
+  try {
+    return execFileSync("git", args, {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+/** Branch, dirty files (capped), recent commits — empty-safe outside a git repo. */
+export function gatherGitFacts(root, { statusCap = 20 } = {}) {
+  const branch = git(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const status = git(root, ["status", "--short"]).split("\n").filter(Boolean);
+  const log = git(root, ["log", "--oneline", "-5"]).split("\n").filter(Boolean);
+  return {
+    branch,
+    status: status.slice(0, statusCap),
+    overflow: Math.max(0, status.length - statusCap),
+    log,
+  };
+}
+
+/** Assumption events recorded this session (preflight appends them when it proceeds
+ *  without asking) — surfaced here so the handoff carries what was GUESSED, not
+ *  just what was done. Empty-safe when no session log exists. */
+export function gatherAssumptions(root) {
+  try {
+    const dir = join(root, ".forge", "sessions");
+    const newest = readdirSync(dir)
+      .filter((f) => f.endsWith(".jsonl"))
+      .map((f) => ({ f, m: statSync(join(dir, f)).mtimeMs }))
+      .sort((a, b) => b.m - a.m)[0];
+    if (!newest) return [];
+    const out = [];
+    for (const line of readFileSync(join(dir, newest.f), "utf8").split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const e = JSON.parse(line);
+        if (e.type === "assumption") out.push(e);
+      } catch {}
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+const arr = (v) =>
+  (Array.isArray(v) ? v : v ? [v] : []).map((x) => String(x).trim()).filter(Boolean);
+
+const section = (title, rows, fallback = "- (none)") => [
+  `## ${title}`,
+  ...(rows.length ? rows.map((r) => `- ${r}`) : [fallback]),
+  "",
+];
+
+/**
+ * Rewrite the whole snapshot from this session's fields + auto-gathered git facts.
+ * Refuses secrets in the human-supplied fields (same rule as every forge store) and
+ * truncates to `maxLines` so the session-start injection can never balloon.
+ * @param {string} root
+ * @param {{done?:string[]|string, next?:string[]|string, gotchas?:string[]|string,
+ *          criteria?:string[]|string, goal?:string, phase?:string}} fields
+ */
+export function writeState(root, fields = {}, { t = Date.now(), maxLines = 150 } = {}) {
+  const done = arr(fields.done);
+  const next = arr(fields.next);
+  const gotchas = arr(fields.gotchas);
+  const criteria = arr(fields.criteria);
+  if (!done.length && !next.length && !gotchas.length && !criteria.length)
+    return { ok: false, reason: "empty handoff — say what was done and what comes next" };
+  const supplied = [...done, ...next, ...gotchas, ...criteria, fields.goal, fields.phase]
+    .filter(Boolean)
+    .join("\n");
+  if (hasSecret(supplied))
+    return { ok: false, reason: "refused: handoff looks like it contains a secret/credential" };
+  const goal = fields.goal || getGoal(root) || `(none set — \`${BRAND.cli} anchor set "…"\`)`;
+  const facts = gatherGitFacts(root);
+  const assumptions = gatherAssumptions(root).map(
+    (a) =>
+      `proceeded without asking — missing: ${(a.missing || []).join(", ") || "?"}${
+        (a.questions || []).length ? ` (${a.questions[0]})` : ""
+      }`,
+  );
+  const progress = facts.status.length
+    ? [...facts.status, ...(facts.overflow ? [`(+${facts.overflow} more dirty files)`] : [])]
+    : [];
+  const lines = [
+    "# Session state",
+    "",
+    ...section("Goal / Phase", [`${goal}${fields.phase ? ` — phase: ${fields.phase}` : ""}`]),
+    ...section("Acceptance criteria", criteria),
+    ...section("Done this session", done),
+    ...section("Next steps", next),
+    ...section("Gotchas", gotchas),
+    ...section("Open assumptions", assumptions),
+    ...section("In-progress files (git, at handoff)", progress, "- (clean tree)"),
+    "## Decisions",
+    `- append-only log: \`.forge/decisions.md\` (\`${BRAND.cli} decide\`)`,
+    "",
+  ];
+  const provenance = `<!-- written ${new Date(t).toISOString()} — ${BRAND.cli} handoff${
+    facts.branch ? ` on ${facts.branch}` : ""
+  } -->`;
+  const kept =
+    lines.length + 1 > maxLines
+      ? [...lines.slice(0, maxLines - 2), "- (truncated to stay bounded)"]
+      : lines;
+  mkdirSync(join(root, ".forge"), { recursive: true });
+  writeFileSync(statePath(root), [...kept, provenance, ""].join("\n"));
+  return { ok: true, path: statePath(root), lines: kept.length + 1 };
+}
+
+/** The snapshot text minus provenance, or null when none exists. */
+export function readState(root) {
+  const p = statePath(root);
+  if (!existsSync(p)) return null;
+  try {
+    const raw = readFileSync(p, "utf8");
+    const cut = raw.indexOf("<!--");
+    const text = (cut === -1 ? raw : raw.slice(0, cut)).trim();
+    return text || null;
+  } catch {
+    return null;
+  }
+}
+
+/** SessionStart injection block — empty string when no snapshot exists (low-nag). */
+export function stateBlock(root, { maxLines = 80 } = {}) {
+  const text = readState(root);
+  if (!text) return "";
+  const body = text.split("\n").filter((l) => l.trim() !== "# Session state");
+  const capped =
+    body.length > maxLines
+      ? [...body.slice(0, maxLines), `_(truncated — read \`.forge/state.md\` for the rest)_`]
+      : body;
+  return [
+    `## Session state (${BRAND.brand} Handoff)`,
+    ...capped,
+    `Keep it current: \`${BRAND.cli} handoff "<done>" --next "<next>"\` before stopping.`,
+    "",
+  ].join("\n");
+}
diff --git a/test/decide.test.js b/test/decide.test.js
new file mode 100644
index 0000000..7fc13b7
--- /dev/null
+++ b/test/decide.test.js
@@ -0,0 +1,63 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { appendDecision, decisionsPath, listDecisions, parseDecisions } from "../src/decide.js";
+import { loadClaims } from "../src/ledger_store.js";
+import { fakeAnthropic } from "./_fixtures.js";
+
+test("appendDecision numbers sequentially and never rewrites prior lines", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-decide-"));
+  const r1 = appendDecision(root, "use exemplar k-NN over keyword lists — decisions stay math");
+  assert.equal(r1.ok, true);
+  assert.equal(r1.id, "D-0001");
+  const r2 = appendDecision(root, "state.md is rewritten, decisions.md is append-only");
+  assert.equal(r2.id, "D-0002");
+  const text = readFileSync(decisionsPath(root), "utf8");
+  assert.match(text, /D-0001/);
+  assert.match(text, /D-0002/);
+  assert.ok(text.indexOf("D-0001") < text.indexOf("D-0002"), "chronological append order");
+  assert.match(text, /# Decisions/, "header written once");
+  assert.equal((text.match(/# Decisions/g) || []).length, 1);
+});
+
+test("listDecisions returns the most recent entries; empty on a fresh repo", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-decide-"));
+  assert.deepEqual(listDecisions(root), []);
+  for (let i = 0; i < 12; i += 1) appendDecision(root, `decision number ${i} — because`);
+  const last = listDecisions(root, { limit: 10 });
+  assert.equal(last.length, 10);
+  assert.match(last[9].text, /number 11/);
+});
+
+test("appendDecision refuses empty text and secrets", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-decide-"));
+  assert.equal(appendDecision(root, "  ").ok, false);
+  const s = appendDecision(root, `store ${fakeAnthropic("AAAAbbbbCCCCddddEEEEffff")} in env`);
+  assert.equal(s.ok, false);
+  assert.match(s.reason, /secret/);
+});
+
+test("a decision mints a machine-readable ledger twin (best-effort)", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-decide-"));
+  const r = appendDecision(root, "gate blocks once per session — repeated nagging trains bypass");
+  assert.equal(r.ok, true);
+  const claims = loadClaims(join(root, ".forge", "ledger"));
+  const twin = claims.find((c) => c.kind === "decision");
+  assert.ok(twin, "decision claim exists");
+  assert.match(twin.body.text, /blocks once per session/);
+});
+
+test("a corrupted decisions file is tolerated — numbering restarts from parseable max", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-decide-"));
+  mkdirSync(join(root, ".forge"), { recursive: true });
+  writeFileSync(
+    decisionsPath(root),
+    "# Decisions\n\ngarbage line no entry\n- **D-0007** (2026-01-01): earlier decision\nmore garbage\n",
+  );
+  const r = appendDecision(root, "new decision after corruption");
+  assert.equal(r.id, "D-0008", "continues from the max parseable id");
+  const parsed = parseDecisions(readFileSync(decisionsPath(root), "utf8"));
+  assert.equal(parsed.length, 2, "garbage ignored, both real entries parse");
+});
diff --git a/test/handoff.test.js b/test/handoff.test.js
new file mode 100644
index 0000000..f646662
--- /dev/null
+++ b/test/handoff.test.js
@@ -0,0 +1,95 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { gatherGitFacts, readState, stateBlock, statePath, writeState } from "../src/handoff.js";
+import { fakeAnthropic } from "./_fixtures.js";
+
+function gitFixture() {
+  const root = mkdtempSync(join(tmpdir(), "forge-handoff-"));
+  const git = (...args) =>
+    execFileSync("git", args, { cwd: root, stdio: ["ignore", "pipe", "pipe"] });
+  git("init", "-q");
+  git("config", "user.email", "forge@test.invalid");
+  git("config", "user.name", "forge-test");
+  writeFileSync(join(root, "a.js"), "export const one = 1;\n");
+  git("add", "-A");
+  git("-c", "commit.gpgsign=false", "commit", "-qm", "fixture");
+  return root;
+}
+
+test("writeState produces every section, bounded, and rewrites (never appends)", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-handoff-"));
+  const r = writeState(root, { done: ["built the gate"], next: ["wire manifests"] });
+  assert.equal(r.ok, true);
+  const text = readFileSync(statePath(root), "utf8");
+  for (const s of [
+    "Goal / Phase",
+    "Acceptance criteria",
+    "Done this session",
+    "Next steps",
+    "Gotchas",
+    "Open assumptions",
+    "In-progress files",
+    "Decisions",
+  ])
+    assert.match(text, new RegExp(`## ${s}`), `section ${s} present`);
+  assert.match(text, /built the gate/);
+  // Second write REPLACES the first — bounded snapshot, not a growing log.
+  writeState(root, { done: ["second session"] });
+  const after = readFileSync(statePath(root), "utf8");
+  assert.doesNotMatch(after, /built the gate/, "old rows do not accumulate");
+  assert.match(after, /second session/);
+});
+
+test("writeState caps at maxLines and refuses empty or secret-bearing handoffs", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-handoff-"));
+  const many = Array.from({ length: 400 }, (_, i) => `row ${i}`);
+  const r = writeState(root, { done: many }, { maxLines: 60 });
+  assert.equal(r.ok, true);
+  const lineCount = readFileSync(statePath(root), "utf8").trimEnd().split("\n").length;
+  assert.ok(lineCount <= 61, `bounded: got ${lineCount} lines`);
+  assert.equal(writeState(root, {}).ok, false, "empty handoff refused");
+  // Runtime-assembled credential shape — never a literal (gitleaks scans history).
+  const s = writeState(root, { done: [`the key is ${fakeAnthropic("AAAAbbbbCCCCddddEEEEffff")}`] });
+  assert.equal(s.ok, false);
+  assert.match(s.reason, /secret/);
+});
+
+test("stateBlock injects the snapshot, empty when none exists, capped when long", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-handoff-"));
+  assert.equal(stateBlock(root), "", "fresh repo injects nothing");
+  writeState(root, { done: ["a thing"], next: Array.from({ length: 120 }, (_, i) => `n${i}`) });
+  const block = stateBlock(root, { maxLines: 20 });
+  assert.match(block, /Session state/);
+  assert.match(block, /a thing/);
+  assert.match(block, /truncated/, "overflow becomes a pointer, not silent growth");
+});
+
+test("gatherGitFacts: branch + dirty files inside a repo, empty-safe outside", () => {
+  const root = gitFixture();
+  writeFileSync(join(root, "b.js"), "export const two = 2;\n");
+  const facts = gatherGitFacts(root);
+  assert.ok(facts.branch.length > 0, "branch known");
+  assert.ok(
+    facts.status.some((s) => s.includes("b.js")),
+    "dirty file listed",
+  );
+  const bare = gatherGitFacts(mkdtempSync(join(tmpdir(), "forge-handoff-")));
+  assert.equal(bare.branch, "");
+  assert.deepEqual(bare.status, []);
+});
+
+test("writeState surfaces recorded assumption events from the newest session log", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-handoff-"));
+  mkdirSync(join(root, ".forge", "sessions"), { recursive: true });
+  writeFileSync(
+    join(root, ".forge", "sessions", "s1.jsonl"),
+    `${JSON.stringify({ type: "assumption", missing: ["target_scope"], ambiguous: ["it"] })}\n`,
+  );
+  writeState(root, { done: ["x"] });
+  const text = readFileSync(statePath(root), "utf8");
+  assert.match(text, /target_scope/, "assumption keys carried into the handoff");
+});

From 8cfb49fdc14817dcece2105179e5defa56100758 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 10 Jul 2026 08:19:17 +0000
Subject: [PATCH 03/12] feat(session): git baseline anchoring + rehydration +
 artifact pruning
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SessionStart records HEAD once per session (.forge/sessions/<sid>.base —
a resume never moves the anchor), prunes week-old session artifacts, and
the rehydration block carries recent commits + uncommitted changes so a
fresh session orients on evidence. sessionPath() becomes the one naming
rule for every per-session artifact (log, baseline, marker, intent).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
---
 src/cortex_hook.js   |   9 +++-
 src/session.js       | 100 +++++++++++++++++++++++++++++++++++++++++++
 test/session.test.js |  77 +++++++++++++++++++++++++++++++++
 3 files changed, 184 insertions(+), 2 deletions(-)
 create mode 100644 src/session.js
 create mode 100644 test/session.test.js

diff --git a/src/cortex_hook.js b/src/cortex_hook.js
index 862cb86..68db267 100644
--- a/src/cortex_hook.js
+++ b/src/cortex_hook.js
@@ -7,8 +7,13 @@ import { join } from "node:path";
 import { recordContradiction, recordMistake } from "./cortex.js";
 import { contentHash, slug } from "./util.js";
 
-const sessionFile = (root, sid) =>
-  join(root, ".forge", "sessions", `${String(sid).replace(/[^A-Za-z0-9_-]/g, "_")}.jsonl`);
+// One naming rule for every per-session artifact (event log, git baseline, gate marker,
+// last-intent) — the sanitized sid plus an extension, all under .forge/sessions/ so one
+// prune sweep ages them together.
+export const sessionPath = (root, sid, ext = "jsonl") =>
+  join(root, ".forge", "sessions", `${String(sid).replace(/[^A-Za-z0-9_-]/g, "_")}.${ext}`);
+
+const sessionFile = (root, sid) => sessionPath(root, sid);
 
 /** Append one normalized event to a session's log (called by capture hooks). */
 export function appendSessionEvent(root, sid, event) {
diff --git a/src/session.js b/src/session.js
new file mode 100644
index 0000000..4efb541
--- /dev/null
+++ b/src/session.js
@@ -0,0 +1,100 @@
+// forge session — per-session git anchoring. Nothing recorded WHERE the repo stood when
+// a session began, so "what changed this session" was unanswerable and every diff ran
+// against live HEAD. SessionStart records the anchor once (resume keeps it); the
+// completion gate diffs against it; the rehydration block tells a fresh session what
+// recently happened instead of letting it assume.
+import { execFileSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { BRAND } from "./brand.js";
+import { sessionPath } from "./cortex_hook.js";
+
+function git(root, args) {
+  try {
+    return execFileSync("git", args, {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+/** Record HEAD as this session's baseline — once. An existing file wins (a --resume
+ *  re-fires SessionStart and must NOT move the anchor mid-session). */
+export function recordBaseline(root, sid) {
+  const head = git(root, ["rev-parse", "HEAD"]);
+  if (!head) return { recorded: false, head: null }; // not a repo (or unborn HEAD) → nothing to anchor
+  const p = sessionPath(root, sid, "base");
+  try {
+    if (existsSync(p)) return { recorded: false, head: readFileSync(p, "utf8").trim() };
+    mkdirSync(join(root, ".forge", "sessions"), { recursive: true });
+    writeFileSync(p, `${head}\n`);
+    return { recorded: true, head };
+  } catch {
+    return { recorded: false, head };
+  }
+}
+
+/** The session's anchor: baseline sha + the file's mtime (= when the session started —
+ *  the completion gate compares state.md's mtime against it). Null when never recorded. */
+export function readBaseline(root, sid) {
+  const p = sessionPath(root, sid, "base");
+  try {
+    if (!existsSync(p)) return null;
+    return { head: readFileSync(p, "utf8").trim(), t: statSync(p).mtimeMs };
+  } catch {
+    return null;
+  }
+}
+
+/** Age out stale per-session artifacts (logs, baselines, markers) in one sweep. */
+export function pruneSessions(root, { maxAgeDays = 7, now = Date.now() } = {}) {
+  const dir = join(root, ".forge", "sessions");
+  let removed = 0;
+  try {
+    for (const f of readdirSync(dir)) {
+      try {
+        if (now - statSync(join(dir, f)).mtimeMs > maxAgeDays * 86_400_000) {
+          unlinkSync(join(dir, f));
+          removed += 1;
+        }
+      } catch {}
+    }
+  } catch {}
+  return { removed };
+}
+
+/** SessionStart injection: recent commits + uncommitted changes — the repo's actual
+ *  recent history, so a fresh session orients on evidence instead of assumptions.
+ *  Empty string outside a git repo (low-nag). */
+export function rehydrationBlock(root, { commits = 10, statusCap = 20 } = {}) {
+  const log = git(root, ["log", "--oneline", `-${commits}`])
+    .split("\n")
+    .filter(Boolean);
+  if (!log.length) return "";
+  const lines = [
+    `## Where this repo stands (${BRAND.brand})`,
+    "Recent commits:",
+    ...log.map((l) => `- ${l}`),
+  ];
+  const status = git(root, ["status", "--short"]).split("\n").filter(Boolean);
+  if (status.length) {
+    lines.push(
+      "Uncommitted changes at session start:",
+      ...status.slice(0, statusCap).map((s) => `- ${s}`),
+    );
+    if (status.length > statusCap) lines.push(`- (+${status.length - statusCap} more)`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
diff --git a/test/session.test.js b/test/session.test.js
new file mode 100644
index 0000000..e4391b4
--- /dev/null
+++ b/test/session.test.js
@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { sessionPath } from "../src/cortex_hook.js";
+import { pruneSessions, readBaseline, recordBaseline, rehydrationBlock } from "../src/session.js";
+
+function gitFixture() {
+  const root = mkdtempSync(join(tmpdir(), "forge-session-"));
+  const git = (...args) =>
+    execFileSync("git", args, { cwd: root, stdio: ["ignore", "pipe", "pipe"] });
+  git("init", "-q");
+  git("config", "user.email", "forge@test.invalid");
+  git("config", "user.name", "forge-test");
+  writeFileSync(join(root, "a.js"), "export const one = 1;\n");
+  git("add", "-A");
+  git("-c", "commit.gpgsign=false", "commit", "-qm", "fixture");
+  return { root, git };
+}
+
+test("recordBaseline anchors HEAD once; a resume never moves the anchor", () => {
+  const { root, git } = gitFixture();
+  const first = recordBaseline(root, "s1");
+  assert.equal(first.recorded, true);
+  assert.match(first.head, /^[0-9a-f]{40}$/);
+  // New commit, then SessionStart re-fires (resume) — the original anchor must survive.
+  writeFileSync(join(root, "a.js"), "export const one = 2;\n");
+  git("add", "-A");
+  git("-c", "commit.gpgsign=false", "commit", "-qm", "second");
+  const again = recordBaseline(root, "s1");
+  assert.equal(again.recorded, false, "resume keeps the anchor");
+  assert.equal(again.head, first.head, "anchor still points at session-start HEAD");
+  assert.equal(readBaseline(root, "s1").head, first.head);
+});
+
+test("recordBaseline outside a git repo is a safe no-op; readBaseline null", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-session-"));
+  assert.equal(recordBaseline(root, "s").recorded, false);
+  assert.equal(readBaseline(root, "s"), null);
+  assert.equal(existsSync(sessionPath(root, "s", "base")), false, "no file written");
+});
+
+test("pruneSessions removes week-old artifacts, keeps fresh ones", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-session-"));
+  mkdirSync(join(root, ".forge", "sessions"), { recursive: true });
+  const old = sessionPath(root, "old", "base");
+  const fresh = sessionPath(root, "fresh");
+  writeFileSync(old, "abc\n");
+  writeFileSync(fresh, "{}\n");
+  const past = (Date.now() - 10 * 86_400_000) / 1000;
+  utimesSync(old, past, past);
+  const { removed } = pruneSessions(root, { maxAgeDays: 7 });
+  assert.equal(removed, 1);
+  assert.equal(existsSync(old), false, "aged artifact pruned");
+  assert.equal(existsSync(fresh), true, "fresh artifact kept");
+});
+
+test("rehydrationBlock: commits + dirty files in a repo; empty string outside", () => {
+  const { root } = gitFixture();
+  writeFileSync(join(root, "b.js"), "export const two = 2;\n");
+  const block = rehydrationBlock(root);
+  assert.match(block, /Recent commits:/);
+  assert.match(block, /fixture/);
+  assert.match(block, /Uncommitted changes at session start:/);
+  assert.match(block, /b\.js/);
+  assert.equal(rehydrationBlock(mkdtempSync(join(tmpdir(), "forge-session-"))), "");
+});
+
+test("rehydrationBlock caps the dirty list with an overflow pointer", () => {
+  const { root, git } = gitFixture();
+  for (let i = 0; i < 25; i += 1) writeFileSync(join(root, `f${i}.js`), "export const x = 1;\n");
+  const block = rehydrationBlock(root, { statusCap: 5 });
+  assert.match(block, /\(\+20 more\)/, "overflow counted, not silently dropped");
+  git("add", "-A"); // keep fixture dir reusable; not asserted
+});

From 4f919023526b13ee6910aad0a45fdf97b6024926 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 10 Jul 2026 08:19:17 +0000
Subject: [PATCH 04/12] =?UTF-8?q?feat(docs):=20forge=20docs=20sync=20?=
 =?UTF-8?q?=E2=80=94=20the=20diff-driven=20stale-docs=20sweep?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

docs check reconciles registries; docs sync answers the diff-shaped
question: changed identifiers (paths + definitions + called symbols, from
added AND removed lines, via the same RULES grammars the atlas parses)
swept against every doc artifact → UPDATED / STALE (file:line hits) /
VERIFIED-UNAFFECTED with the reason recorded. Advisory by default,
--strict for CI, --base <ref> to widen. CHANGELOG + decisions.md exempt
(append-only history). Symbols come only from non-test code files and
only code-shaped names scan — dogfooding on this very branch caught the
prose-parenthesis false-positive class.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
---
 src/docs_sync.js       | 206 +++++++++++++++++++++++++++++++++++++++++
 test/docs_sync.test.js | 113 ++++++++++++++++++++++
 2 files changed, 319 insertions(+)
 create mode 100644 src/docs_sync.js
 create mode 100644 test/docs_sync.test.js

diff --git a/src/docs_sync.js b/src/docs_sync.js
new file mode 100644
index 0000000..05f7511
--- /dev/null
+++ b/src/docs_sync.js
@@ -0,0 +1,206 @@
+// forge docs sync — the diff-driven half of docs↔code alignment. `docs check` reconciles
+// REGISTRIES (commands, env vars, MCP tools) against the contract docs; this sweep answers
+// the other question: given WHAT JUST CHANGED, which prose mentions it? Diff → identifiers
+// → scan every doc artifact → UPDATED (the doc moved with the change), STALE (mentions a
+// changed identifier but didn't move — with file:line hits), or VERIFIED-UNAFFECTED (zero
+// mentions, and the reason is RECORDED: checked, not assumed). Pure reporter — updating
+// prose is the agent's job; refusing "done" without it is the completion gate's.
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+import { load as loadAtlas, RULES } from "./atlas.js";
+import { CALL_IGNORE, extractCalledSymbols } from "./extract.js";
+import { statePath } from "./handoff.js";
+import { isTestFile } from "./substrate.js";
+
+function git(root, args) {
+  try {
+    return execFileSync("git", args, {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch {
+    return "";
+  }
+}
+
+// Definition names on changed lines — the SAME grammars the atlas parses, so the sweep
+// and the graph can never disagree about what counts as a definition.
+function definedNames(rel, text) {
+  const rules = RULES[extname(rel)];
+  if (!rules) return [];
+  const out = [];
+  for (const { re } of rules) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(text))) out.push(m[1]);
+  }
+  return out;
+}
+
+/**
+ * The identifier set of a diff: changed rel paths + called symbols + definition names on
+ * the changed lines (added AND removed — a deleted symbol makes docs stale too).
+ */
+export function changedIdentifiers(root, { base = "HEAD" } = {}) {
+  const diff =
+    git(root, ["diff", "--unified=0", base]) || git(root, ["diff", "--unified=0", "--cached"]);
+  const perFile = new Map();
+  let current = null;
+  for (const line of diff.split("\n")) {
+    const header = /^\+\+\+ b\/(.*)$/.exec(line);
+    if (header) {
+      current = header[1] === "/dev/null" ? null : header[1];
+      if (current && !perFile.has(current)) perFile.set(current, []);
+      continue;
+    }
+    const gone = /^--- a\/(.*)$/.exec(line);
+    if (gone && gone[1] !== "/dev/null" && !perFile.has(gone[1])) perFile.set(gone[1], []);
+    if (!current) continue;
+    if (
+      (line.startsWith("+") && !line.startsWith("+++")) ||
+      (line.startsWith("-") && !line.startsWith("---"))
+    )
+      perFile.get(current).push(line.slice(1));
+  }
+  for (const f of git(root, ["ls-files", "--others", "--exclude-standard"])
+    .split("\n")
+    .filter(Boolean)) {
+    if (!perFile.has(f)) {
+      let text = "";
+      try {
+        text = readFileSync(join(root, f), "utf8");
+      } catch {}
+      perFile.set(f, text.split("\n")); // a brand-new file: every line is a changed line
+    }
+  }
+  const identifiers = new Set();
+  const changedFiles = [...perFile.keys()].sort();
+  // Precision rules (dogfooding found them): symbols come ONLY from code-class files —
+  // prose parentheses in a changed .md line are not call sites — and never from test
+  // files (docs don't document test internals). A plain lowercase English word that
+  // happens to be a variable (`status`, `body`) would flag every doc that uses the
+  // word, so only code-shaped names (case transition, digit, _ . / -) are scanned.
+  const codeShaped = (s) => /[A-Z0-9_./\\-]/.test(s);
+  for (const [rel, lines] of perFile) {
+    identifiers.add(rel);
+    if (!RULES[extname(rel)] || isTestFile(rel)) continue;
+    const text = lines.join("\n");
+    for (const s of extractCalledSymbols(text))
+      if (s.length >= 3 && codeShaped(s)) identifiers.add(s);
+    for (const d of definedNames(rel, text))
+      if (d.length >= 3 && !CALL_IGNORE.has(d) && codeShaped(d)) identifiers.add(d);
+  }
+  return { base, changedFiles, identifiers: [...identifiers].sort() };
+}
+
+// CHANGELOG and the decisions log are append-only HISTORY — their mentions of changed
+// identifiers are correct-by-design (same reasoning as the atlas DOC_SKIP set).
+const HISTORY_RE = /(^|[/\\])CHANGELOG\.md$/i;
+
+/** Every doc artifact the sweep owes an answer for: atlas doc nodes + the contract docs
+ *  + the session-state snapshot (when they exist). */
+export function docSet(root, atlas = loadAtlas(root)) {
+  const docs = new Set();
+  for (const n of atlas?.nodes || []) if (n.kind === "doc" && n.file) docs.add(n.file);
+  for (const d of ["README.md", join("docs", "GUIDE.md"), "ARCHITECTURE.md"])
+    if (existsSync(join(root, d))) docs.add(d);
+  if (existsSync(statePath(root))) docs.add(join(".forge", "state.md"));
+  return [...docs].filter((f) => !HISTORY_RE.test(f)).sort();
+}
+
+// The newest session baseline on disk — `docs sync` defaults to "what changed THIS
+// session" when a baseline exists, falling back to HEAD (uncommitted work) otherwise.
+export function newestBaseline(root) {
+  try {
+    const dir = join(root, ".forge", "sessions");
+    const newest = readdirSync(dir)
+      .filter((f) => f.endsWith(".base"))
+      .map((f) => ({ f, m: statSync(join(dir, f)).mtimeMs }))
+      .sort((a, b) => b.m - a.m)[0];
+    if (!newest) return null;
+    const sha = readFileSync(join(dir, newest.f), "utf8").trim();
+    return git(root, ["rev-parse", "--verify", `${sha}^{commit}`]) ? sha : null;
+  } catch {
+    return null;
+  }
+}
+
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * The sweep. Per doc artifact: UPDATED (changed in this diff), STALE (mentions changed
+ * identifiers — every hit cited file:line), or VERIFIED-UNAFFECTED with the recorded
+ * reason. `base` defaults to the newest session baseline, then HEAD.
+ * @param {string} root
+ * @param {{base?: string, atlas?: object|null, maxHitsPerDoc?: number}} [opts]
+ */
+export function docsSyncReport(root, { base, atlas, maxHitsPerDoc = 20 } = {}) {
+  const resolvedBase = base || newestBaseline(root) || "HEAD";
+  const { changedFiles, identifiers } = changedIdentifiers(root, { base: resolvedBase });
+  const docs = docSet(root, atlas === undefined ? loadAtlas(root) : atlas);
+  const report = {
+    base: resolvedBase,
+    changedFiles,
+    identifiers,
+    updated: [],
+    stale: [],
+    unaffected: [],
+  };
+  if (!identifiers.length) return report;
+  const scanRe = new RegExp(`(?:^|[^\\w$/.-])(${identifiers.map(esc).join("|")})(?![\\w$])`, "g");
+  for (const doc of docs) {
+    if (changedFiles.includes(doc)) {
+      report.updated.push({ file: doc, reason: "changed in this diff" });
+      continue;
+    }
+    let text;
+    try {
+      text = readFileSync(join(root, doc), "utf8");
+    } catch {
+      continue;
+    }
+    const hits = [];
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length && hits.length < maxHitsPerDoc; i += 1) {
+      scanRe.lastIndex = 0;
+      let m;
+      while ((m = scanRe.exec(lines[i])) && hits.length < maxHitsPerDoc) {
+        if (m[1] === doc) continue; // a doc naming itself is not staleness
+        hits.push({ identifier: m[1], line: i + 1, text: lines[i].trim().slice(0, 160) });
+      }
+    }
+    if (hits.length) report.stale.push({ file: doc, hits });
+    else
+      report.unaffected.push({
+        file: doc,
+        reason: `mentions none of the ${identifiers.length} changed identifiers`,
+      });
+  }
+  return report;
+}
+
+/** Human rendering — one line per artifact, hits cited as file:line. */
+export function renderDocsSync(report) {
+  const out = [
+    `docs sync — diff vs ${report.base}: ${report.changedFiles.length} changed file(s), ${report.identifiers.length} identifier(s)`,
+  ];
+  if (!report.changedFiles.length) {
+    out.push("  clean — nothing changed, nothing owed.");
+    return out.join("\n");
+  }
+  for (const u of report.updated) out.push(`  UPDATED     ${u.file} (${u.reason})`);
+  for (const s of report.stale) {
+    out.push(`  STALE       ${s.file} — mentions changed identifiers:`);
+    for (const h of s.hits.slice(0, 5))
+      out.push(`                ${s.file}:${h.line}  \`${h.identifier}\` — ${h.text}`);
+    if (s.hits.length > 5) out.push(`                (+${s.hits.length - 5} more hits)`);
+  }
+  for (const v of report.unaffected) out.push(`  VERIFIED    ${v.file} — ${v.reason}`);
+  if (report.stale.length)
+    out.push(
+      `  → update the STALE artifacts (or justify why not), then re-run. History files (CHANGELOG) are exempt by design.`,
+    );
+  return out.join("\n");
+}
diff --git a/test/docs_sync.test.js b/test/docs_sync.test.js
new file mode 100644
index 0000000..b670cb0
--- /dev/null
+++ b/test/docs_sync.test.js
@@ -0,0 +1,113 @@
+import assert from "node:assert/strict";
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { build } from "../src/atlas.js";
+import { changedIdentifiers, docSet, docsSyncReport } from "../src/docs_sync.js";
+
+const CLI = fileURLToPath(new URL("../src/cli.js", import.meta.url));
+
+function gitFixture() {
+  const root = mkdtempSync(join(tmpdir(), "forge-docsync-"));
+  const git = (...args) =>
+    execFileSync("git", args, { cwd: root, stdio: ["ignore", "pipe", "pipe"] });
+  git("init", "-q");
+  git("config", "user.email", "forge@test.invalid");
+  git("config", "user.name", "forge-test");
+  mkdirSync(join(root, "src"));
+  writeFileSync(join(root, "src", "val.js"), "export function validateOrder(x){ return !!x }\n");
+  writeFileSync(
+    join(root, "README.md"),
+    "# app\n\nUse `validateOrder` from `src/val.js` to check orders.\n",
+  );
+  writeFileSync(join(root, "SILENT.md"), "# notes\n\nNothing about that code here.\n");
+  writeFileSync(join(root, "CHANGELOG.md"), "# changes\n\n- added validateOrder\n");
+  const commit = (m) => {
+    git("add", "-A");
+    git("-c", "commit.gpgsign=false", "commit", "-qm", m);
+  };
+  commit("fixture");
+  return { root, git, commit };
+}
+
+test("changedIdentifiers: paths + definitions + calls from added AND removed lines", () => {
+  const { root } = gitFixture();
+  writeFileSync(
+    join(root, "src", "val.js"),
+    "export function validateOrderStrict(x){ return checkLimits(x) }\n",
+  );
+  const { identifiers, changedFiles } = changedIdentifiers(root, { base: "HEAD" });
+  assert.ok(changedFiles.includes("src/val.js"));
+  assert.ok(identifiers.includes("src/val.js"), "the changed path is an identifier");
+  assert.ok(identifiers.includes("validateOrderStrict"), "new definition captured");
+  assert.ok(identifiers.includes("validateOrder"), "REMOVED definition captured too");
+  assert.ok(identifiers.includes("checkLimits"), "called symbol captured");
+});
+
+test("docsSyncReport: stale doc cited file:line; silent doc verified with reason; CHANGELOG exempt", () => {
+  const { root } = gitFixture();
+  build({ root });
+  writeFileSync(join(root, "src", "val.js"), "export function validateOrderV2(x){ return !!x }\n");
+  const r = docsSyncReport(root, { base: "HEAD" });
+  const stale = r.stale.find((s) => s.file === "README.md");
+  assert.ok(stale, `README flagged stale: ${JSON.stringify(r.stale)}`);
+  assert.ok(
+    stale.hits.some((h) => h.identifier === "validateOrder" && h.line === 3),
+    "hit cites the identifier and line",
+  );
+  const silent = r.unaffected.find((v) => v.file === "SILENT.md");
+  assert.ok(silent, "silent doc present in unaffected");
+  assert.match(silent.reason, /mentions none/, "verified-unaffected records its reason");
+  assert.ok(
+    !r.stale.some((s) => /CHANGELOG/.test(s.file)) &&
+      !r.unaffected.some((v) => /CHANGELOG/.test(v.file)),
+    "append-only history is not swept",
+  );
+});
+
+test("a doc edited in the same diff reports UPDATED, not STALE", () => {
+  const { root } = gitFixture();
+  build({ root });
+  writeFileSync(join(root, "src", "val.js"), "export function validateOrderV2(x){ return !!x }\n");
+  writeFileSync(
+    join(root, "README.md"),
+    "# app\n\nUse `validateOrderV2` from `src/val.js` to check orders.\n",
+  );
+  const r = docsSyncReport(root, { base: "HEAD" });
+  assert.ok(
+    r.updated.some((u) => u.file === "README.md"),
+    "doc moved with the change",
+  );
+  assert.ok(!r.stale.some((s) => s.file === "README.md"));
+});
+
+test("docSet includes the state snapshot when present; non-git root yields a clean report", () => {
+  const { root } = gitFixture();
+  mkdirSync(join(root, ".forge"), { recursive: true });
+  writeFileSync(join(root, ".forge", "state.md"), "# Session state\n\nmentions src/val.js\n");
+  build({ root });
+  assert.ok(docSet(root).includes(join(".forge", "state.md")));
+  const bare = mkdtempSync(join(tmpdir(), "forge-docsync-"));
+  const r = docsSyncReport(bare);
+  assert.deepEqual(r.changedFiles, []);
+  assert.deepEqual(r.stale, []);
+});
+
+test("CLI: docs sync --json reports; --strict exits 1 only when stale docs exist", () => {
+  const { root, commit } = gitFixture();
+  build({ root });
+  commit("atlas artifacts");
+  writeFileSync(join(root, "src", "val.js"), "export function validateOrderV3(x){ return !!x }\n");
+  const strict = spawnSync("node", [CLI, "docs", "sync", "--strict"], {
+    cwd: root,
+    encoding: "utf8",
+  });
+  assert.equal(strict.status, 1, `stale docs fail --strict: ${strict.stdout}`);
+  const lax = spawnSync("node", [CLI, "docs", "sync", "--json"], { cwd: root, encoding: "utf8" });
+  assert.equal(lax.status, 0, "advisory by default");
+  const parsed = JSON.parse(lax.stdout);
+  assert.ok(parsed.stale.some((s) => s.file === "README.md"));
+});

From 8648afddd78445d81371ecfcc5436a95d5313cd4 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 10 Jul 2026 08:19:17 +0000
Subject: [PATCH 05/12] =?UTF-8?q?feat(gate):=20the=20completion=20gate=20?=
 =?UTF-8?q?=E2=80=94=20a=20deterministic=20floor=20under=20'done'?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A synchronous Stop guard (the detached cortex.sh stop can never answer)
blocks a session ONCE when code changed since the session baseline but no
doc or state artifact moved with it — the reason IS the repair checklist
(forge docs sync / handoff / decide + CUSUM drift alarm). Loop-safe
(stop_hook_active + once-per-session marker), fail-open on every error
path, FORGE_STOPGATE=0 kill switch. Classification derives from the atlas
registries + shared isTestFile — no parallel regex lists. state.md is
gitignored, so its signal is mtime-vs-baseline. Registered in both hook
manifests (plugin + init template, lockstep-tested).

Also fixes cortex.sh entry resolution in symlink installs: ~/.forge/src/…
pointed at the nonexistent global/src/, silently no-opping every cortex
hook outside plugin mode — both shims now resolve through the symlink
(pwd -P), same as secret-redact.sh.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
---
 global/guards/completion-gate.sh |  17 +++
 global/guards/cortex.sh          |   7 +-
 global/settings.template.json    |   4 +
 hooks/hooks.json                 |   4 +
 install.sh                       |   4 +-
 src/gate.js                      | 193 +++++++++++++++++++++++++++++++
 test/gate.test.js                |  73 ++++++++++++
 test/stop_gate.test.js           | 132 +++++++++++++++++++++
 8 files changed, 431 insertions(+), 3 deletions(-)
 create mode 100755 global/guards/completion-gate.sh
 create mode 100644 src/gate.js
 create mode 100644 test/gate.test.js
 create mode 100644 test/stop_gate.test.js

diff --git a/global/guards/completion-gate.sh b/global/guards/completion-gate.sh
new file mode 100755
index 0000000..4aa81c2
--- /dev/null
+++ b/global/guards/completion-gate.sh
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Forge completion gate — Stop hook, SYNCHRONOUS on purpose: it is the one Stop-path
+# guard allowed to answer (a {"decision":"block"} with the repair checklist) when a
+# session changed code but moved no doc/state artifact. cortex.sh runs `stop` detached
+# so session exit is never delayed — that path can never block, hence this shim.
+# Fail-open: any missing node/module/git swallows to a plain exit 0.
+set -uo pipefail
+
+# ~/.forge is a symlink to <repo>/global, so pwd -P lands inside the real tree in both
+# install modes (install.sh symlink and CLAUDE_PLUGIN_ROOT plugin checkout).
+DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ENTRY="$DIR/../../src/cortex_hook_main.js"
+
+if command -v node >/dev/null 2>&1 && [ -f "$ENTRY" ]; then
+  node "$ENTRY" stop-gate 2>/dev/null || true
+fi
+exit 0
diff --git a/global/guards/cortex.sh b/global/guards/cortex.sh
index dc10fee..1c463c7 100755
--- a/global/guards/cortex.sh
+++ b/global/guards/cortex.sh
@@ -2,8 +2,11 @@
 # Forge Cortex hook shim — pipes the hook JSON (stdin) to the fail-safe node entrypoint.
 # Advisory memory ONLY: it never blocks or fails a tool call. Mode is $1
 # (capture | prompt | stop | session-start). Any error is swallowed; always exits 0.
-root="${CLAUDE_PLUGIN_ROOT:-$HOME/.forge}"
-entry="$root/src/cortex_hook_main.js"
+# Resolve the real tree through the ~/.forge → <repo>/global symlink (pwd -P), so the
+# entry exists in BOTH install modes. The old "$HOME/.forge/src/..." path pointed at
+# global/src/ — nonexistent — and silently no-opped every hook in symlink installs.
+DIR="$(cd "$(dirname "$0")" && pwd -P)"
+entry="$DIR/../../src/cortex_hook_main.js"
 # `stop` may distill lessons (an opt-in model call) — run it detached so session exit is
 # never delayed. Other modes are fast and (session-start) must return stdout synchronously.
 if [ "$1" = "stop" ]; then
diff --git a/global/settings.template.json b/global/settings.template.json
index bebed60..6feb964 100644
--- a/global/settings.template.json
+++ b/global/settings.template.json
@@ -164,6 +164,10 @@
     "Stop": [
       {
         "hooks": [
+          {
+            "type": "command",
+            "command": "bash ~/.forge/guards/completion-gate.sh"
+          },
           {
             "type": "command",
             "command": "bash ~/.forge/guards/lean-guard.sh"
diff --git a/hooks/hooks.json b/hooks/hooks.json
index 4d20020..09a5ef7 100644
--- a/hooks/hooks.json
+++ b/hooks/hooks.json
@@ -88,6 +88,10 @@
     "Stop": [
       {
         "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/global/guards/completion-gate.sh"
+          },
           {
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT}\"/global/guards/lean-guard.sh"
diff --git a/install.sh b/install.sh
index d38352d..26bde50 100644
--- a/install.sh
+++ b/install.sh
@@ -68,7 +68,9 @@ install_forge() {
       "PreToolUse":  [ { "matcher": "Edit|Write|MultiEdit|Bash",
         "hooks": [ { "type": "command", "command": "bash $FORGE_HOME/guards/protect-paths.sh" } ] } ],
       "PostToolUse": [ { "matcher": "Edit|Write|MultiEdit",
-        "hooks": [ { "type": "command", "command": "bash $FORGE_HOME/guards/format-on-edit.sh" } ] } ]
+        "hooks": [ { "type": "command", "command": "bash $FORGE_HOME/guards/format-on-edit.sh" } ] } ],
+      "Stop": [ { "hooks": [ { "type": "command",
+        "command": "bash $FORGE_HOME/guards/completion-gate.sh" } ] } ]
     }
 
   Or install the plugin instead (guards auto-wire): /plugin marketplace add <this-repo> then /plugin install forgekit.
diff --git a/src/gate.js b/src/gate.js
new file mode 100644
index 0000000..6fad7bb
--- /dev/null
+++ b/src/gate.js
@@ -0,0 +1,193 @@
+// forge gate — the completion gate: a deterministic floor under "done". Instructions and
+// lessons raise the PROBABILITY that code ships with its docs/state; this Stop hook
+// guarantees a floor: a session that changed code but moved no doc/state artifact is
+// blocked ONCE, with the exact repair procedure as the reason. P(silent miss) =
+// (1−p)·∏(1−cⱼ) — the gate is the cⱼ≈1 layer for the structural signal "code moved,
+// nothing followed". Loop-safe (stop_hook_active + once-per-session marker), fail-open
+// on every error path, kill switch FORGE_STOPGATE=0.
+//
+// Classification derives from the SAME registries the atlas is built from (CODE_EXTS/
+// DOC_EXTS/config rules) + the shared test-file predicate — no parallel regex lists that
+// could drift. Deliberate deviation from the reference kit: test-only changes do NOT
+// block (a regression-test-only session owes no prose), and .forge/state.md — invisible
+// to git because .forge/ is gitignored — counts as the doc signal via its mtime against
+// the session baseline (the baseline file's mtime IS the session-start timestamp).
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { extname, join } from "node:path";
+import { cusum } from "./anchor.js";
+import { CODE_EXTS, DOC_EXTS, impact, isConfigFile, load as loadAtlas } from "./atlas.js";
+import { BRAND } from "./brand.js";
+import { readSession, sessionPath } from "./cortex_hook.js";
+import { decisionsPath } from "./decide.js";
+import { statePath } from "./handoff.js";
+import { readBaseline } from "./session.js";
+import { isTestFile } from "./substrate.js";
+
+// gitRaw keeps the exact bytes — porcelain's first column is a SPACE for unstaged
+// entries, and a trim() would eat it and shift the path slice by one.
+function gitRaw(root, args) {
+  try {
+    return execFileSync("git", args, {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch {
+    return "";
+  }
+}
+
+const git = (root, args) => gitRaw(root, args).trim();
+
+export const CLASSES = ["code", "docs", "config", "test", "internal", "other"];
+
+/** Total function path → class. Order matters: the state/decisions snapshots are doc
+ *  artifacts FIRST (the minimum-bar trick), then everything else under .forge/ and the
+ *  generated instruction files are internal (never owed docs). */
+export function classifyPath(rel) {
+  const p = String(rel).replace(/\\/g, "/");
+  const name = p.split("/").pop() || "";
+  if (p === ".forge/state.md" || p === ".forge/decisions.md") return "docs";
+  if (p.startsWith(".forge/") || /^(AGENTS|CLAUDE|GEMINI)\.md$/i.test(name)) return "internal";
+  if (DOC_EXTS.has(extname(name))) return "docs";
+  if (isTestFile(p)) return "test";
+  // Config BEFORE code: `vite.config.ts` is wiring, not logic — same dispatch order the
+  // atlas uses, so the gate and the graph agree on every path.
+  if (isConfigFile(name)) return "config";
+  if (CODE_EXTS.has(extname(name))) return "code";
+  return "other";
+}
+
+/** Everything changed this session: diff against the recorded baseline ∪ the working
+ *  tree (staged + unstaged + untracked file-by-file, renames as both paths). */
+export function changedSet(root, baseHead) {
+  const out = new Set();
+  if (baseHead && git(root, ["rev-parse", "--verify", `${baseHead}^{commit}`]))
+    for (const f of git(root, ["diff", "--name-only", baseHead]).split("\n").filter(Boolean))
+      out.add(f);
+  for (const line of gitRaw(root, ["status", "--porcelain", "-uall"]).split("\n").filter(Boolean)) {
+    for (const part of line.slice(3).split(" -> ")) {
+      const p = part.replace(/^"(.*)"$/, "$1").trim();
+      if (p) out.add(p);
+    }
+  }
+  return [...out].sort();
+}
+
+/**
+ * PURE decision table (the kit's ten rows, minus the impure guards the orchestrator
+ * handles). First match wins; returns {allow, row, classes}.
+ */
+export function gateDecision({
+  stopHookActive = false,
+  isRepo = true,
+  markerExists = false,
+  killSwitch = false,
+  changed = [],
+  stateTouched = false,
+} = {}) {
+  if (stopHookActive) return { allow: true, row: "stop-hook-active" };
+  if (!isRepo) return { allow: true, row: "not-a-repo" };
+  if (markerExists) return { allow: true, row: "already-blocked" };
+  if (killSwitch) return { allow: true, row: "kill-switch" };
+  const classes = Object.fromEntries(CLASSES.map((c) => [c, []]));
+  for (const f of changed) classes[classifyPath(f)].push(f);
+  const external = changed.length - classes.internal.length;
+  if (!external && !stateTouched) return { allow: true, row: "no-changes", classes };
+  if (classes.docs.length || stateTouched) return { allow: true, row: "docs-touched", classes };
+  if (classes.code.length) return { allow: false, row: "code-without-docs", classes };
+  return { allow: true, row: "no-code-class", classes };
+}
+
+/** The block reason IS the repair procedure — its consumer is the agent itself, and a
+ *  checklist converts a failure into a same-turn fix. Stale-doc candidates come from the
+ *  CACHED atlas only (a hook never builds). */
+export function repairReason(root, { codeFiles = [], driftAlarm = false } = {}) {
+  let likelyDocs = [];
+  try {
+    const atlas = loadAtlas(root);
+    if (atlas) {
+      const docs = new Set();
+      for (const f of codeFiles.slice(0, 10))
+        for (const d of impact(atlas, f, { maxHops: 2 }).impactedFiles)
+          if (d.endsWith(".md")) docs.add(d);
+      likelyDocs = [...docs].slice(0, 5);
+    }
+  } catch {}
+  const shown = codeFiles.slice(0, 10).join(", ");
+  const more = codeFiles.length > 10 ? ` (+${codeFiles.length - 10} more)` : "";
+  const lines = [
+    "END-TO-END COMPLETENESS: code changed this session but no doc or state artifact moved with it.",
+    `Changed code: ${shown}${more}`,
+    "Do what applies before finishing:",
+    `1. \`${BRAND.cli} docs sync\` — sweep the diff for stale doc mentions${
+      likelyDocs.length ? ` (graph suggests: ${likelyDocs.join(", ")})` : ""
+    } and update every hit.`,
+    `2. \`${BRAND.cli} handoff "<what you did>" --next "<what's next>"\` — rewrite the session snapshot the next session resumes from (this alone satisfies the gate).`,
+    `3. \`${BRAND.cli} decide "<choice — reason>"\` if a non-obvious decision was made.`,
+  ];
+  if (driftAlarm)
+    lines.push(
+      `4. Sustained goal drift this session (CUSUM alarm) — re-read the goal: \`${BRAND.cli} anchor\`.`,
+    );
+  lines.push(
+    `If genuinely no doc is affected, tell the user why in one line and still run \`${BRAND.cli} handoff\`.`,
+    "(Blocks once per session — stopping again proceeds. Kill switch: FORGE_STOPGATE=0.)",
+  );
+  return lines.join("\n");
+}
+
+/**
+ * The impure orchestrator the Stop hook calls. Every step is guarded; ANY internal
+ * error resolves to allow — the gate must never brick a session.
+ */
+export function stopGate(root, sid, hook = {}) {
+  try {
+    if (hook.stop_hook_active === true || hook.stop_hook_active === "true")
+      return { allow: true, row: "stop-hook-active" };
+    if (process.env.FORGE_STOPGATE === "0") return { allow: true, row: "kill-switch" };
+    if (git(root, ["rev-parse", "--is-inside-work-tree"]) !== "true")
+      return { allow: true, row: "not-a-repo" };
+    const marker = sessionPath(root, sid, "blocked");
+    if (existsSync(marker)) return { allow: true, row: "already-blocked" };
+    const base = readBaseline(root, sid);
+    // Session-start timestamp: the baseline file's mtime; degraded fallback = the event
+    // log's birth time (hooks installed mid-session). Without either, mtime signals
+    // can't be trusted — stateTouched stays false and the block-once marker caps cost.
+    let startedAt = base?.t ?? null;
+    if (startedAt == null) {
+      try {
+        startedAt = statSync(sessionPath(root, sid)).birthtimeMs || null;
+      } catch {}
+    }
+    const stateTouched =
+      startedAt != null &&
+      [statePath(root), decisionsPath(root)].some((p) => {
+        try {
+          return statSync(p).mtimeMs > startedAt;
+        } catch {
+          return false;
+        }
+      });
+    const changed = changedSet(root, base?.head);
+    const decision = gateDecision({ changed, stateTouched });
+    if (decision.allow) return decision;
+    let driftAlarm = false;
+    try {
+      const scores = readSession(root, sid)
+        .filter((e) => e.type === "drift")
+        .map((e) => Number(e.score))
+        .filter(Number.isFinite);
+      if (scores.length >= 3) driftAlarm = cusum(scores).alarm;
+    } catch {}
+    const reason = repairReason(root, { codeFiles: decision.classes.code, driftAlarm });
+    try {
+      mkdirSync(join(root, ".forge", "sessions"), { recursive: true });
+      writeFileSync(marker, `${new Date().toISOString()}\n`);
+    } catch {}
+    return { allow: false, row: decision.row, reason, classes: decision.classes };
+  } catch {
+    return { allow: true, row: "internal-error" };
+  }
+}
diff --git a/test/gate.test.js b/test/gate.test.js
new file mode 100644
index 0000000..e44c702
--- /dev/null
+++ b/test/gate.test.js
@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { classifyPath, gateDecision } from "../src/gate.js";
+
+test("classifyPath: one total function from the shared registries", () => {
+  assert.equal(classifyPath(".forge/state.md"), "docs", "state snapshot IS the doc signal");
+  assert.equal(classifyPath(".forge/decisions.md"), "docs");
+  assert.equal(classifyPath(".forge/lessons/x.md"), "internal");
+  assert.equal(classifyPath("AGENTS.md"), "internal", "generated instruction files owe nothing");
+  assert.equal(classifyPath("CLAUDE.md"), "internal");
+  assert.equal(classifyPath("README.md"), "docs");
+  assert.equal(classifyPath("docs/GUIDE.md"), "docs");
+  assert.equal(classifyPath("CHANGELOG.md"), "docs", "a changelog entry satisfies the gate");
+  assert.equal(classifyPath("src/route.js"), "code");
+  assert.equal(classifyPath("lib/store.py"), "code");
+  assert.equal(classifyPath("test/route.test.js"), "test");
+  assert.equal(classifyPath("src/__tests__/x.jsx"), "test");
+  assert.equal(classifyPath("Dockerfile"), "config");
+  assert.equal(classifyPath(".github/workflows/ci.yml"), "config");
+  assert.equal(classifyPath("vite.config.ts"), "config");
+  assert.equal(classifyPath("logo.png"), "other");
+  assert.equal(classifyPath("package-lock.json"), "other", "lockfiles are churn, not config");
+});
+
+test("gate table: guard rows always allow", () => {
+  assert.equal(gateDecision({ stopHookActive: true }).row, "stop-hook-active");
+  assert.equal(gateDecision({ isRepo: false }).row, "not-a-repo");
+  assert.equal(gateDecision({ markerExists: true }).row, "already-blocked");
+  assert.equal(gateDecision({ killSwitch: true }).row, "kill-switch");
+  for (const r of [
+    gateDecision({ stopHookActive: true }),
+    gateDecision({ isRepo: false }),
+    gateDecision({ markerExists: true }),
+    gateDecision({ killSwitch: true }),
+  ])
+    assert.equal(r.allow, true);
+});
+
+test("gate table: clean and internal-only sessions owe nothing", () => {
+  assert.equal(gateDecision({ changed: [] }).row, "no-changes");
+  const internal = gateDecision({ changed: [".forge/lessons/a.md", "AGENTS.md"] });
+  assert.equal(internal.row, "no-changes", "internal artifacts never trigger the gate");
+  assert.equal(internal.allow, true);
+});
+
+test("gate table: THE row — code moved, no doc/state followed → block", () => {
+  const r = gateDecision({ changed: ["src/route.js", "src/gate.js"] });
+  assert.equal(r.allow, false);
+  assert.equal(r.row, "code-without-docs");
+  assert.deepEqual(r.classes.code, ["src/route.js", "src/gate.js"]);
+});
+
+test("gate table: any doc-class artifact (or a state touch) satisfies the floor", () => {
+  assert.equal(gateDecision({ changed: ["src/route.js", "README.md"] }).row, "docs-touched");
+  assert.equal(gateDecision({ changed: ["src/route.js"], stateTouched: true }).row, "docs-touched");
+  assert.equal(gateDecision({ changed: ["docs/GUIDE.md"] }).row, "docs-touched");
+  assert.equal(
+    gateDecision({ changed: ["src/x.js", ".forge/state.md"] }).row,
+    "docs-touched",
+    "the gitignore-invisible snapshot counts via the changed set too",
+  );
+});
+
+test("gate table: test-only, config-only, and other-only changes pass (precision rule)", () => {
+  assert.equal(gateDecision({ changed: ["test/gate.test.js"] }).row, "no-code-class");
+  assert.equal(gateDecision({ changed: [".github/workflows/ci.yml"] }).row, "no-code-class");
+  assert.equal(gateDecision({ changed: ["assets/logo.png"] }).row, "no-code-class");
+  assert.equal(
+    gateDecision({ changed: ["src/x.js", "test/x.test.js"] }).allow,
+    false,
+    "code + tests but NO docs still blocks — tests are not prose",
+  );
+});
diff --git a/test/stop_gate.test.js b/test/stop_gate.test.js
new file mode 100644
index 0000000..3b83100
--- /dev/null
+++ b/test/stop_gate.test.js
@@ -0,0 +1,132 @@
+import assert from "node:assert/strict";
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+
+const ENTRY = fileURLToPath(new URL("../src/cortex_hook_main.js", import.meta.url));
+const GUARD = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "global",
+  "guards",
+  "completion-gate.sh",
+);
+
+const feed = (mode, payload, env = {}) =>
+  spawnSync("node", [ENTRY, mode], {
+    input: JSON.stringify(payload),
+    encoding: "utf8",
+    env: { ...process.env, ...env },
+  });
+
+function gitFixture() {
+  const root = mkdtempSync(join(tmpdir(), "forge-gate-"));
+  const git = (...args) =>
+    execFileSync("git", args, { cwd: root, stdio: ["ignore", "pipe", "pipe"] });
+  git("init", "-q");
+  git("config", "user.email", "forge@test.invalid");
+  git("config", "user.name", "forge-test");
+  writeFileSync(join(root, "a.js"), "export const one = 1;\n");
+  writeFileSync(join(root, "README.md"), "# app\n");
+  git("add", "-A");
+  git("-c", "commit.gpgsign=false", "commit", "-qm", "fixture");
+  return { root, git };
+}
+
+const start = (root, sid) => feed("session-start", { session_id: sid, cwd: root });
+const stopGate = (root, sid, extra = {}, env = {}) =>
+  feed("stop-gate", { session_id: sid, cwd: root, ...extra }, env);
+
+test("code-only session blocks ONCE with the repair checklist, then the marker allows", () => {
+  const { root } = gitFixture();
+  start(root, "g1");
+  writeFileSync(join(root, "a.js"), "export const one = 2;\n");
+  const first = stopGate(root, "g1");
+  assert.equal(first.status, 0, "a blocking gate still exits 0 (decision, not crash)");
+  const out = JSON.parse(first.stdout);
+  assert.equal(out.decision, "block");
+  assert.match(out.reason, /docs sync/, "checklist names the sweep");
+  assert.match(out.reason, /handoff/, "checklist names the snapshot");
+  assert.match(out.reason, /a\.js/, "the changed code file is cited");
+  assert.ok(existsSync(join(root, ".forge", "sessions", "g1.blocked")), "marker set");
+  const second = stopGate(root, "g1");
+  assert.equal(second.stdout.trim(), "", "block-at-most-once per session");
+});
+
+test("stop_hook_active and the kill switch never block", () => {
+  const { root } = gitFixture();
+  start(root, "g2");
+  writeFileSync(join(root, "a.js"), "export const one = 3;\n");
+  const looped = stopGate(root, "g2", { stop_hook_active: true });
+  assert.equal(looped.stdout.trim(), "", "official loop-protection flag respected");
+  const killed = stopGate(root, "g2", {}, { FORGE_STOPGATE: "0" });
+  assert.equal(killed.stdout.trim(), "", "FORGE_STOPGATE=0 disables the gate");
+});
+
+test("code+doc together, docs-only, and clean sessions all pass silently", () => {
+  const { root } = gitFixture();
+  start(root, "g3");
+  assert.equal(stopGate(root, "g3").stdout.trim(), "", "clean session owes nothing");
+  writeFileSync(join(root, "a.js"), "export const one = 4;\n");
+  writeFileSync(join(root, "README.md"), "# app\n\nupdated with the change\n");
+  assert.equal(stopGate(root, "g3").stdout.trim(), "", "docs moved with the code");
+});
+
+test("a handoff (state.md mtime after session start) satisfies the gate", () => {
+  const { root } = gitFixture();
+  start(root, "g4");
+  writeFileSync(join(root, "a.js"), "export const one = 5;\n");
+  mkdirSync(join(root, ".forge"), { recursive: true });
+  writeFileSync(join(root, ".forge", "state.md"), "# Session state\n\n## Done\n- changed a.js\n");
+  const r = stopGate(root, "g4");
+  assert.equal(r.stdout.trim(), "", "the gitignored snapshot counts via mtime-vs-baseline");
+});
+
+test("missing baseline degrades to worktree-only detection and still blocks", () => {
+  const { root } = gitFixture();
+  // no session-start — hooks installed mid-session
+  writeFileSync(join(root, "a.js"), "export const one = 6;\n");
+  const r = stopGate(root, "nobase");
+  const out = JSON.parse(r.stdout);
+  assert.equal(out.decision, "block", "uncommitted code caught without an anchor");
+});
+
+test("non-git root and garbage stdin are silent no-ops (fail-open)", () => {
+  const bare = mkdtempSync(join(tmpdir(), "forge-gate-"));
+  const r = stopGate(bare, "g5");
+  assert.equal(r.status, 0);
+  assert.equal(r.stdout.trim(), "");
+  const garbage = spawnSync("node", [ENTRY, "stop-gate"], { input: "not json", encoding: "utf8" });
+  assert.equal(garbage.status, 0);
+  assert.equal(garbage.stdout.trim(), "");
+});
+
+test("guard shim: synchronous passthrough of the block decision, always exit 0", () => {
+  const { root } = gitFixture();
+  start(root, "g6");
+  writeFileSync(join(root, "a.js"), "export const one = 7;\n");
+  const r = spawnSync("bash", [GUARD], {
+    input: JSON.stringify({ session_id: "g6", cwd: root }),
+    encoding: "utf8",
+  });
+  assert.equal(r.status, 0);
+  assert.equal(JSON.parse(r.stdout).decision, "block", "the shim relays the gate's answer");
+  const bare = spawnSync("bash", [GUARD], {
+    input: JSON.stringify({ session_id: "x", cwd: mkdtempSync(join(tmpdir(), "forge-gate-")) }),
+    encoding: "utf8",
+  });
+  assert.equal(bare.status, 0);
+  assert.equal(bare.stdout.trim(), "");
+});
+
+test("both hook manifests register the completion gate under Stop (lockstep)", () => {
+  const repo = join(dirname(fileURLToPath(import.meta.url)), "..");
+  const plugin = JSON.parse(readFileSync(join(repo, "hooks", "hooks.json"), "utf8"));
+  const template = JSON.parse(readFileSync(join(repo, "global", "settings.template.json"), "utf8"));
+  const flat = (m) => (m.hooks.Stop || []).flatMap((e) => e.hooks.map((h) => h.command)).join("\n");
+  assert.match(flat(plugin), /completion-gate\.sh/, "plugin manifest wires the gate");
+  assert.match(flat(template), /completion-gate\.sh/, "init template wires the gate");
+});

From b803d3e82da0a34c1ad589375dc63d3fe980db40 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 10 Jul 2026 08:19:43 +0000
Subject: [PATCH 06/12] feat(intent): protocol cards routed by exemplar k-NN,
 not a keyword DFA
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The prompt is classified by the same math as model routing — a labeled
bank (English + Hinglish rows) under overlap similarity with a confidence
gate. Work intents (bugfix/feature/refactor/release) inject a ~6-line
protocol card once per run of that intent; questions get no ceremony,
below-confidence prompts get nothing. intentGrams deliberately differs
from route's contentGrams: generic task verbs are complexity noise but
exactly the intent signal — same math, different stop-set data.
FORGE_INTENT=0 kill switch.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
---
 src/intent.js       | 178 ++++++++++++++++++++++++++++++++++++++++++++
 test/intent.test.js |  86 +++++++++++++++++++++
 2 files changed, 264 insertions(+)
 create mode 100644 src/intent.js
 create mode 100644 test/intent.test.js

diff --git a/src/intent.js b/src/intent.js
new file mode 100644
index 0000000..470077a
--- /dev/null
+++ b/src/intent.js
@@ -0,0 +1,178 @@
+// forge intent — what KIND of work is this prompt asking for? The reference kit used a
+// keyword DFA; here classification is the same exemplar k-NN math as route.js (labeled
+// rows + overlap coefficient + confidence gate), so intents are tuned by adding example
+// rows — including Hinglish ones — never by editing regexes. NOTE: intentGrams is NOT
+// route.js contentGrams. Route's STOP set strips generic task verbs (fix/add/build/…)
+// because they carry no COMPLEXITY signal — but they are exactly the INTENT signal.
+// Same math, different stop-set data.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { BRAND } from "./brand.js";
+import { sessionPath } from "./cortex_hook.js";
+import { setOverlap } from "./math.js";
+
+/** Labeled intent bank — DATA, not decision code. Extend coverage by adding rows. */
+export const INTENT_EXEMPLARS = [
+  // question — answered directly, no ceremony (System-1 fast path)
+  { text: "how does the login flow work", intent: "question" },
+  { text: "what does this function do", intent: "question" },
+  { text: "why is startup slow", intent: "question" },
+  { text: "where is the config loaded from", intent: "question" },
+  { text: "explain the difference between these two modules", intent: "question" },
+  { text: "is this endpoint rate limited", intent: "question" },
+  { text: "what happens when the cache expires", intent: "question" },
+  { text: "yeh function kya karta hai", intent: "question" },
+  { text: "yeh error kyun aa raha hai", intent: "question" },
+  { text: "kaise kaam karta hai yeh module", intent: "question" },
+  // bugfix — reproduce → root cause → failing test → fix → sweep
+  { text: "fix the crash when saving a profile", intent: "bugfix" },
+  { text: "the login page throws a 500 error", intent: "bugfix" },
+  { text: "tests are failing after the last merge", intent: "bugfix" },
+  { text: "the app crashes on startup", intent: "bugfix" },
+  { text: "fix the race condition in the queue", intent: "bugfix" },
+  { text: "the button does nothing when clicked", intent: "bugfix" },
+  { text: "resolve the null pointer in checkout", intent: "bugfix" },
+  { text: "fix the regression introduced by the last change", intent: "bugfix" },
+  { text: "payment page thik karo crash ho raha hai", intent: "bugfix" },
+  { text: "yeh bug thik karo", intent: "bugfix" },
+  { text: "error aa raha hai isko sahi karo", intent: "bugfix" },
+  { text: "form submit hone par error deta hai", intent: "bugfix" },
+  // feature — spec → acceptance criteria → build with docs in the same pass
+  { text: "add a login page with otp", intent: "feature" },
+  { text: "implement dark mode for the dashboard", intent: "feature" },
+  { text: "add export to csv", intent: "feature" },
+  { text: "build a notification system", intent: "feature" },
+  { text: "add pagination to the results list", intent: "feature" },
+  { text: "implement password reset flow", intent: "feature" },
+  { text: "add support for multiple languages", intent: "feature" },
+  { text: "naya dashboard banao", intent: "feature" },
+  { text: "ek search feature banao", intent: "feature" },
+  { text: "profile page bana do", intent: "feature" },
+  // refactor — behavior-preserving, tests first, sweep every old name
+  { text: "clean up the api module", intent: "refactor" },
+  { text: "refactor the payment service into smaller functions", intent: "refactor" },
+  { text: "extract the shared logic into a helper", intent: "refactor" },
+  { text: "rename the user manager and update the callers", intent: "refactor" },
+  { text: "simplify this class hierarchy", intent: "refactor" },
+  { text: "restructure the folder layout", intent: "refactor" },
+  { text: "reduce duplication across the handlers", intent: "refactor" },
+  { text: "modernize this file to async await", intent: "refactor" },
+  { text: "code saaf karo is module ka", intent: "refactor" },
+  { text: "is code ko behtar banao bina behavior badle", intent: "refactor" },
+  // release — gates: changelog, version, tests, docs check
+  { text: "ship the release", intent: "release" },
+  { text: "cut a new version and update the changelog", intent: "release" },
+  { text: "prepare the release notes", intent: "release" },
+  { text: "publish the package to npm", intent: "release" },
+  { text: "bump the version and tag it", intent: "release" },
+  { text: "deploy to production", intent: "release" },
+  { text: "get this ready to ship", intent: "release" },
+  { text: "roll out the new build", intent: "release" },
+  { text: "deploy karo", intent: "release" },
+  { text: "release kar do production par", intent: "release" },
+];
+
+// Function words ONLY (English + Hinglish auxiliaries/pronouns). Task verbs stay —
+// they are the intent signal (see module header).
+const STOP = new Set(
+  (
+    "a an the in on of to for with and or is are be it its this that as at by from into up out " +
+    "my your our their please can you i we " +
+    "hai hain ho raha rahi ka ki ke ko par mein se aur yeh ye iska isko"
+  ).split(" "),
+);
+
+const stem = (t) => (t.length > 3 && t.endsWith("s") ? t.slice(0, -1) : t);
+
+/** Same shape as route.js contentGrams — different stop-set (function words only). */
+export function intentGrams(text) {
+  const toks = String(text)
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t && !STOP.has(t))
+    .map(stem);
+  const grams = new Set(toks);
+  for (let i = 0; i + 1 < toks.length; i++) grams.add(`${toks[i]} ${toks[i + 1]}`);
+  return grams;
+}
+
+const EXEMPLAR_GRAMS = INTENT_EXEMPLARS.map((e) => ({ ...e, grams: intentGrams(e.text) }));
+
+/**
+ * k-NN over the bank: similarity-weighted vote among the top-k neighbors, gated on the
+ * best similarity — a prompt resembling nothing in the bank is "none", never a guess.
+ * Neighbors ride along so every classification is attributable to its evidence.
+ */
+export function classifyIntent(text, { k = 3, minConf = 0.25 } = {}) {
+  const grams = intentGrams(text);
+  if (!grams.size) return { intent: "none", confidence: 0, neighbors: [] };
+  const sims = EXEMPLAR_GRAMS.map((e) => ({
+    text: e.text,
+    intent: e.intent,
+    sim: setOverlap(grams, e.grams),
+  }))
+    .sort((a, b) => b.sim - a.sim)
+    .slice(0, k);
+  const top = sims[0];
+  if (!top || top.sim < minConf)
+    return { intent: "none", confidence: top?.sim ?? 0, neighbors: sims };
+  const votes = new Map();
+  for (const s of sims) votes.set(s.intent, (votes.get(s.intent) ?? 0) + s.sim);
+  const [intent] = [...votes.entries()].sort((a, b) => b[1] - a[1])[0];
+  return { intent, confidence: Number(top.sim.toFixed(3)), neighbors: sims };
+}
+
+/** Protocol cards — data. `question`/`none` deliberately have no card (no ceremony). */
+export const PROTOCOL_CARDS = {
+  bugfix: [
+    `## Bugfix protocol (${BRAND.brand})`,
+    "1. Reproduce first — no fix without a failing observation.",
+    "2. Trace the CAUSE, not the symptom (the wrong-status UI is rarely a UI bug).",
+    `3. Write the failing test BEFORE the fix; \`${BRAND.cli} diagnose "<error>"\` if this failure has repeated.`,
+    `4. \`${BRAND.cli} impact <file>\` — sweep the blast radius (callers, configs, docs).`,
+    `5. Full suite green, then \`${BRAND.cli} docs sync\` + \`${BRAND.cli} handoff\` — the gate checks.`,
+  ].join("\n"),
+  feature: [
+    `## Feature protocol (${BRAND.brand})`,
+    `1. \`${BRAND.cli} preflight "<task>"\` — answer its questions or record the assumptions.`,
+    `2. State acceptance criteria up front (\`${BRAND.cli} handoff --criteria "…"\`).`,
+    `3. \`${BRAND.cli} impact\` / \`${BRAND.cli} scope\` before building — know the full artifact list.`,
+    "4. Docs, tests, and configs move IN THE SAME PASS as the code, not later.",
+    `5. \`${BRAND.cli} verify\` before claiming done.`,
+  ].join("\n"),
+  refactor: [
+    `## Refactor protocol (${BRAND.brand})`,
+    "1. Behavior-preserving: capture current behavior with tests FIRST.",
+    `2. \`${BRAND.cli} scope <files>\` — find the coupled files you didn't name.`,
+    `3. Sweep every old name — code AND prose: \`${BRAND.cli} docs sync\` after the rename.`,
+    `4. \`${BRAND.cli} lean\` — keep the footprint proportional to the ask.`,
+  ].join("\n"),
+  release: [
+    `## Release protocol (${BRAND.brand})`,
+    "1. Tests + lint green; CHANGELOG has a real [Unreleased] section.",
+    `2. \`${BRAND.cli} docs check\` — commands/env/tools tables must match the code.`,
+    "3. Version bump + tag; release notes from the changelog.",
+    `4. \`${BRAND.cli} verify\` as the final gate before shipping.`,
+  ].join("\n"),
+};
+
+/**
+ * The UserPromptSubmit hook's entry: classify, dedupe per session (a card is injected
+ * once per run of the same intent — context economy), kill switch FORGE_INTENT=0.
+ * Returns "" whenever there is nothing worth saying (low-nag).
+ */
+export function intentCard(root, sid, text) {
+  if (process.env.FORGE_INTENT === "0") return "";
+  const { intent } = classifyIntent(text);
+  const card = PROTOCOL_CARDS[intent];
+  if (!card) return ""; // question/none: no ceremony
+  const marker = sessionPath(root, sid, "intent");
+  try {
+    if (readFileSync(marker, "utf8").trim() === intent) return "";
+  } catch {}
+  try {
+    mkdirSync(dirname(marker), { recursive: true });
+    writeFileSync(marker, `${intent}\n`);
+  } catch {}
+  return card;
+}
diff --git a/test/intent.test.js b/test/intent.test.js
new file mode 100644
index 0000000..4b47042
--- /dev/null
+++ b/test/intent.test.js
@@ -0,0 +1,86 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { classifyIntent, intentCard, PROTOCOL_CARDS } from "../src/intent.js";
+
+const ENTRY = fileURLToPath(new URL("../src/cortex_hook_main.js", import.meta.url));
+
+test("classifyIntent: each intent recognized from unseen phrasings (English)", () => {
+  assert.equal(classifyIntent("fix the crash on the settings page").intent, "bugfix");
+  assert.equal(classifyIntent("add a page to export invoices as csv").intent, "feature");
+  assert.equal(
+    classifyIntent("clean up the billing module and reduce duplication").intent,
+    "refactor",
+  );
+  assert.equal(classifyIntent("cut a release and update the changelog").intent, "release");
+  assert.equal(classifyIntent("how does the cache expiry work").intent, "question");
+});
+
+test("classifyIntent: Hinglish rows are data, not regexes — unseen variants match", () => {
+  assert.equal(classifyIntent("login page thik karo error aa raha hai").intent, "bugfix");
+  assert.equal(classifyIntent("ek naya profile page banao").intent, "feature");
+  assert.equal(classifyIntent("deploy kar do production par").intent, "release");
+});
+
+test("classifyIntent: no resemblance → none (never a guess); neighbors attribute the call", () => {
+  const vague = classifyIntent("hello there");
+  assert.equal(vague.intent, "none");
+  const r = classifyIntent("fix the race condition in the export queue");
+  assert.equal(r.intent, "bugfix");
+  assert.ok(
+    r.neighbors.length > 0 && r.neighbors[0].sim >= r.confidence - 1e-9,
+    "evidence rides along",
+  );
+});
+
+test("intentCard: question and none are silent; work intents inject once per run", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-intent-"));
+  assert.equal(intentCard(root, "s1", "why is startup slow"), "", "questions get no ceremony");
+  const first = intentCard(root, "s1", "fix the crash when uploading");
+  assert.match(first, /Bugfix protocol/);
+  assert.match(first, /docs sync/, "card names real machinery");
+  assert.equal(intentCard(root, "s1", "fix the other crash too"), "", "same intent deduped");
+  const switched = intentCard(root, "s1", "now add a csv export feature");
+  assert.match(switched, /Feature protocol/, "intent change re-injects");
+  const back = intentCard(root, "s1", "fix the regression this caused");
+  assert.match(back, /Bugfix protocol/, "returning to a prior intent re-injects");
+});
+
+test("intentCard: FORGE_INTENT=0 disables; cards exist only for work intents", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-intent-"));
+  process.env.FORGE_INTENT = "0";
+  try {
+    assert.equal(intentCard(root, "s2", "fix the crash"), "");
+  } finally {
+    delete process.env.FORGE_INTENT;
+  }
+  assert.deepEqual(Object.keys(PROTOCOL_CARDS).sort(), [
+    "bugfix",
+    "feature",
+    "refactor",
+    "release",
+  ]);
+});
+
+test("preflight hook emits the card as additionalContext and dedupes on repeat", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-intent-"));
+  const feed = (prompt) =>
+    spawnSync("node", [ENTRY, "preflight"], {
+      input: JSON.stringify({ session_id: "hook-1", cwd: root, prompt }),
+      encoding: "utf8",
+    });
+  const first = feed("fix the crash in src/tax.ts when rounding");
+  assert.equal(first.status, 0);
+  const out = JSON.parse(first.stdout);
+  assert.match(out.hookSpecificOutput.additionalContext, /Bugfix protocol/);
+  const second = feed("fix the crash in src/tax.ts when rounding");
+  const again = second.stdout.trim() ? JSON.parse(second.stdout) : null;
+  assert.ok(
+    !again || !/Bugfix protocol/.test(again.hookSpecificOutput?.additionalContext ?? ""),
+    "repeat intent does not re-inject the card",
+  );
+});

From fb219878d92f553af364b199f2a93e5245ef9e37 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 10 Jul 2026 08:19:44 +0000
Subject: [PATCH 07/12] feat(evidence): recorded assumptions + goal-drift
 series wire the loop
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Preflight now RECORDS what it only displayed: once a goal is anchored,
every prompt appends its graded driftScore to the session log (cusum —
until now test-only math — accumulates the series and a sustained alarm
rides the gate's block reason); proceeding under assumptions appends a
record the advisory names and the next handoff surfaces. A guess can
never silently become a fact. Hook entrypoint gains the stop-gate mode
and the session-start baseline + snapshot + rehydration injection.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
---
 src/cortex_hook_main.js       | 64 ++++++++++++++++++++++--
 src/substrate.js              | 11 +++++
 test/assumption_trail.test.js | 91 +++++++++++++++++++++++++++++++++++
 test/cortex_hook_main.test.js | 34 ++++++++++++-
 4 files changed, 195 insertions(+), 5 deletions(-)
 create mode 100644 test/assumption_trail.test.js

diff --git a/src/cortex_hook_main.js b/src/cortex_hook_main.js
index 54b3145..85a88ae 100644
--- a/src/cortex_hook_main.js
+++ b/src/cortex_hook_main.js
@@ -8,6 +8,7 @@
 //           preflight       (UserPromptSubmit)            — inject the substrate pre-action advisory
 //           pre-edit        (PreToolUse Edit|Write)       — advise on lessons/risk before an edit
 //           stop            (Stop)                        — distill the session into lessons
+//           stop-gate       (Stop, synchronous)           — completion gate: block once if code moved but no doc/state did
 //           session-start   (SessionStart)               — inject learned lessons as context
 import { applyDistillation, lessonsForContext, startupBlock } from "./cortex.js";
 import {
@@ -75,10 +76,40 @@ async function main() {
       const { autoSyncIfDrifted } = await import("./sync.js");
       autoSyncIfDrifted(root);
     } catch {}
+  } else if (mode === "stop-gate") {
+    // The completion gate — the ONLY Stop-path mode that may block, so it runs through
+    // its own SYNCHRONOUS guard shim (cortex.sh stop is detached and can never answer).
+    // stopGate is fail-open by construction; a block's reason IS the repair checklist.
+    try {
+      const { stopGate } = await import("./gate.js");
+      const r = stopGate(root, sid, hook);
+      try {
+        const { record } = await import("./metrics.js");
+        record(root, { stage: "gate", outcome: r.allow ? "stop-pass" : "stop-block" });
+      } catch {}
+      if (!r.allow) process.stdout.write(JSON.stringify({ decision: "block", reason: r.reason }));
+    } catch {}
   } else if (mode === "session-start") {
-    // Learned lessons + the persistent goal — the two things a fresh session forgets.
+    // Anchor first: record WHERE the repo stands (HEAD) so the completion gate can diff
+    // this session's changes against it; prune week-old session artifacts in the same pass.
+    try {
+      const { pruneSessions, recordBaseline } = await import("./session.js");
+      recordBaseline(root, sid);
+      pruneSessions(root);
+    } catch {}
+    // Then everything a fresh session forgets: learned lessons, the persistent goal,
+    // the handoff snapshot, and the repo's recent history.
     const { goalBlock } = await import("./goal.js");
-    const block = [startupBlock(root, today), goalBlock(root)].filter(Boolean).join("\n");
+    const { stateBlock } = await import("./handoff.js");
+    const { rehydrationBlock } = await import("./session.js");
+    const block = [
+      startupBlock(root, today),
+      goalBlock(root),
+      stateBlock(root),
+      rehydrationBlock(root),
+    ]
+      .filter(Boolean)
+      .join("\n");
     if (block) emit("SessionStart", block);
   } else if (mode === "pre-edit") {
     // A doom loop (the same failure recurring) is the loudest thing to say — it means "stop",
@@ -108,8 +139,35 @@ async function main() {
         process.stdout.write(JSON.stringify({ decision: "block", reason: gate.reason }));
         return;
       }
+      // Session evidence trail (fail-safe): the per-prompt goal-drift score feeds the
+      // completion gate's CUSUM, and assumptions-proceeded-under are RECORDED — the
+      // handoff surfaces them later, so a guess can never silently become a fact.
+      try {
+        const { getGoal } = await import("./goal.js");
+        const goal = getGoal(root);
+        if (goal) {
+          const { goalDrift } = await import("./anchor.js");
+          const d = goalDrift(root, goal, { changed: result.goalAnchor?.changed });
+          appendSessionEvent(root, sid, { type: "drift", score: d.driftScore });
+        }
+        const a = result.assumption;
+        if (!a.shouldAsk && ((a.missing?.length ?? 0) > 0 || (a.questions?.length ?? 0) > 0))
+          appendSessionEvent(root, sid, {
+            type: "assumption",
+            missing: (a.missing ?? []).map((m) => m.key),
+            questions: (a.questions ?? []).slice(0, 3),
+          });
+      } catch {}
       const advisory = substrateContext(result);
-      if (advisory) emit("UserPromptSubmit", advisory);
+      // Intent protocol card (exemplar k-NN, once per run of the same intent) rides the
+      // SAME emit — one hook process must write one JSON object.
+      let card = "";
+      try {
+        const { intentCard } = await import("./intent.js");
+        card = intentCard(root, sid, hook.prompt);
+      } catch {}
+      const combined = [advisory, card].filter(Boolean).join("\n\n");
+      if (combined) emit("UserPromptSubmit", combined);
     }
   }
 }
diff --git a/src/substrate.js b/src/substrate.js
index 62ab9d6..35f3c25 100644
--- a/src/substrate.js
+++ b/src/substrate.js
@@ -489,6 +489,17 @@ export function substrateContext(result) {
     );
   if (result.memory.matchingLessons)
     lines.push(`- ${result.memory.matchingLessons} past lesson(s) match this area (advisory).`);
+  // I3: proceeding is fine below the ask-threshold, but never SILENTLY — the gaps are
+  // named here and recorded to the session log (the handoff surfaces them later).
+  if (
+    !result.assumption.shouldAsk &&
+    ((result.assumption.missing?.length ?? 0) > 0 || result.assumption.questions?.length > 0)
+  ) {
+    const keys = (result.assumption.missing ?? []).map((m) => m.key);
+    lines.push(
+      `- Proceeding without asking under ${keys.length || result.assumption.questions.length} recorded assumption(s)${keys.length ? ` (${keys.join(", ")})` : ""}. Verify them before claiming done.`,
+    );
+  }
   lines.push(`- Verify with: ${result.verification.checklist.join(" · ")}`);
   return lines.join("\n");
 }
diff --git a/test/assumption_trail.test.js b/test/assumption_trail.test.js
new file mode 100644
index 0000000..0fc2aaa
--- /dev/null
+++ b/test/assumption_trail.test.js
@@ -0,0 +1,91 @@
+// Wave: recorded assumptions + CUSUM drift — the evidence trail between "the advisory
+// said something" and "the session actually recorded it for the gate and the handoff".
+import assert from "node:assert/strict";
+import { execFileSync, spawnSync } from "node:child_process";
+import { appendFileSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { setGoal } from "../src/goal.js";
+
+const ENTRY = fileURLToPath(new URL("../src/cortex_hook_main.js", import.meta.url));
+const feed = (mode, payload) =>
+  spawnSync("node", [ENTRY, mode], { input: JSON.stringify(payload), encoding: "utf8" });
+
+function gitFixture() {
+  const root = mkdtempSync(join(tmpdir(), "forge-trail-"));
+  const git = (...args) =>
+    execFileSync("git", args, { cwd: root, stdio: ["ignore", "pipe", "pipe"] });
+  git("init", "-q");
+  git("config", "user.email", "forge@test.invalid");
+  git("config", "user.name", "forge-test");
+  mkdirSync(join(root, "src"));
+  writeFileSync(join(root, "src", "tax.js"), "export function computeTax(x){ return x*0.2 }\n");
+  git("add", "-A");
+  git("-c", "commit.gpgsign=false", "commit", "-qm", "fixture");
+  return { root, git };
+}
+
+const events = (root, sid) =>
+  readFileSync(join(root, ".forge", "sessions", `${sid}.jsonl`), "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((l) => JSON.parse(l));
+
+test("preflight records a drift score per prompt once a goal is anchored", () => {
+  const { root } = gitFixture();
+  setGoal(root, "improve tax calculation accuracy");
+  writeFileSync(join(root, "src", "unrelated.js"), "export const x = 1;\n");
+  feed("preflight", { session_id: "t1", cwd: root, prompt: "tweak the logging colors" });
+  const drift = events(root, "t1").filter((e) => e.type === "drift");
+  assert.equal(drift.length, 1, "one drift observation per prompt");
+  assert.ok(drift[0].score > 0, "off-goal change scored above zero");
+});
+
+test("proceeding under assumptions is RECORDED and named in the advisory", () => {
+  const { root } = gitFixture();
+  const prompt = "refactor src/tax.js keeping behavior, verify with the test suite";
+  const r = feed("preflight", { session_id: "t2", cwd: root, prompt });
+  const recorded = events(root, "t2").filter((e) => e.type === "assumption");
+  assert.equal(recorded.length, 1, "assumption event persisted for the handoff");
+  assert.ok(recorded[0].missing.includes("constraints"), JSON.stringify(recorded[0]));
+  const ctx = JSON.parse(r.stdout).hookSpecificOutput.additionalContext;
+  assert.match(ctx, /Proceeding without asking under 1 recorded assumption/, ctx);
+});
+
+test("sustained drift (CUSUM alarm) is named in the completion-gate block reason", () => {
+  const { root } = gitFixture();
+  feed("session-start", { session_id: "t3", cwd: root });
+  mkdirSync(join(root, ".forge", "sessions"), { recursive: true });
+  for (let i = 0; i < 4; i += 1)
+    appendFileSync(
+      join(root, ".forge", "sessions", "t3.jsonl"),
+      `${JSON.stringify({ type: "drift", score: 1 })}\n`,
+    );
+  writeFileSync(join(root, "src", "tax.js"), "export function computeTax(x){ return x*0.21 }\n");
+  const r = feed("stop-gate", { session_id: "t3", cwd: root });
+  const out = JSON.parse(r.stdout);
+  assert.equal(out.decision, "block");
+  assert.match(out.reason, /CUSUM/, "drift alarm rides the repair checklist");
+  assert.match(out.reason, /anchor/, "and points back at the goal");
+});
+
+test("a session with no goal and no assumptions records nothing extra", () => {
+  const { root } = gitFixture();
+  feed("preflight", {
+    session_id: "t4",
+    cwd: root,
+    prompt: "update computeTax in src/tax.js to round half up",
+  });
+  let evts = [];
+  try {
+    evts = events(root, "t4");
+  } catch {}
+  assert.equal(evts.filter((e) => e.type === "drift").length, 0, "no goal → no drift series");
+  assert.equal(
+    evts.filter((e) => e.type === "assumption").length,
+    0,
+    "fully specified → no record",
+  );
+});
diff --git a/test/cortex_hook_main.test.js b/test/cortex_hook_main.test.js
index 8226036..1824e32 100644
--- a/test/cortex_hook_main.test.js
+++ b/test/cortex_hook_main.test.js
@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
-import { spawnSync } from "node:child_process";
-import { mkdtempSync } from "node:fs";
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { test } from "node:test";
@@ -61,3 +61,33 @@ test("session-start on a fresh repo injects nothing (no noise)", () => {
   assert.equal(r.status, 0);
   assert.equal(r.stdout.trim(), "");
 });
+
+test("session-start anchors a git baseline and injects state + repo history", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-entry-"));
+  const git = (...args) =>
+    execFileSync("git", args, { cwd: root, stdio: ["ignore", "pipe", "pipe"] });
+  git("init", "-q");
+  git("config", "user.email", "forge@test.invalid");
+  git("config", "user.name", "forge-test");
+  writeFileSync(join(root, "a.js"), "export const one = 1;\n");
+  git("add", "-A");
+  git("-c", "commit.gpgsign=false", "commit", "-qm", "anchor fixture");
+  const r = feed("session-start", { session_id: "anchor-1", cwd: root });
+  assert.equal(r.status, 0);
+  const base = join(root, ".forge", "sessions", "anchor-1.base");
+  assert.ok(existsSync(base), "baseline recorded at session start");
+  const sha = readFileSync(base, "utf8").trim();
+  assert.match(sha, /^[0-9a-f]{40}$/);
+  const out = JSON.parse(r.stdout);
+  assert.match(
+    out.hookSpecificOutput.additionalContext,
+    /anchor fixture/,
+    "recent commits injected",
+  );
+  // Re-fired session-start (resume) keeps the anchor even after a new commit.
+  writeFileSync(join(root, "a.js"), "export const one = 2;\n");
+  git("add", "-A");
+  git("-c", "commit.gpgsign=false", "commit", "-qm", "later commit");
+  feed("session-start", { session_id: "anchor-1", cwd: root });
+  assert.equal(readFileSync(base, "utf8").trim(), sha, "resume never moves the anchor");
+});

From 081b3b55aa9ab000db16bcf1ffdea8199deb68d1 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 10 Jul 2026 08:19:44 +0000
Subject: [PATCH 08/12] feat(instructions): end-to-end rules, three skills, and
 a doc-sync agent
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

source/rules.json gains an end-to-end section (Definition of Done, no
silent assumptions, decision log) that forge sync compiles into every
tool. New skills — handoff, sync-docs, catchup — teach the workflow; the
doc-sync crew agent repairs stale docs in its own context (never code)
and joins the plugin agents list.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
---
 .claude-plugin/plugin.json      |  1 +
 global/crew/doc-sync.md         | 33 +++++++++++++++++++++++++++++++++
 global/tools/catchup/SKILL.md   | 25 +++++++++++++++++++++++++
 global/tools/handoff/SKILL.md   | 33 +++++++++++++++++++++++++++++++++
 global/tools/sync-docs/SKILL.md | 30 ++++++++++++++++++++++++++++++
 source/rules.json               |  9 +++++++++
 test/skills.test.js             | 23 +++++++++++++++++++++++
 7 files changed, 154 insertions(+)
 create mode 100644 global/crew/doc-sync.md
 create mode 100644 global/tools/catchup/SKILL.md
 create mode 100644 global/tools/handoff/SKILL.md
 create mode 100644 global/tools/sync-docs/SKILL.md

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 446cc93..e80e846 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -11,6 +11,7 @@
   "keywords": ["config", "cross-tool", "agents-md", "ai-coding", "claude-code", "cognitive-substrate"],
   "skills": "./global/tools",
   "agents": [
+    "./global/crew/doc-sync.md",
     "./global/crew/frontend-verifier.md",
     "./global/crew/independent-reviewer.md",
     "./global/crew/scout.md",
diff --git a/global/crew/doc-sync.md b/global/crew/doc-sync.md
new file mode 100644
index 0000000..8351ab3
--- /dev/null
+++ b/global/crew/doc-sync.md
@@ -0,0 +1,33 @@
+---
+name: doc-sync
+description: Documentation-consistency agent for large diffs. Runs `forge docs sync`, then opens every STALE artifact and updates it to match the code — in its own context, so doc-grepping never floods the main conversation. Use after multi-file changes, renames, or whenever the completion gate lists several stale docs.
+tools: Read, Grep, Glob, Edit, Bash
+model: sonnet
+---
+
+You are the documentation-consistency agent. Your ONLY job: make every doc artifact
+tell the truth about the code as it now is. You never edit code.
+
+## Process
+1. `forge docs sync --json` — the mechanical sweep. It gives you, per artifact:
+   UPDATED / STALE (with identifier + file:line hits) / VERIFIED-UNAFFECTED (+ reason).
+2. For every STALE artifact: open it, read the cited lines IN CONTEXT, and update each
+   mention to match the current code. Read the changed source (`git diff`, the files
+   themselves) when a hit is ambiguous — never guess what the new behavior is.
+3. Widen beyond the hits when the change is structural: a renamed command, module, or
+   endpoint can invalidate prose that never names the identifier. Grep the docs for the
+   OLD name and concept too.
+4. User-facing change? Add a NEW CHANGELOG entry under [Unreleased] — never rewrite
+   released history.
+5. Re-run `forge docs sync` until STALE is empty.
+
+## Report (your final message)
+- `updated:` files you changed, one line each on what was corrected
+- `verified unaffected:` files checked clean (with the sweep's reasons)
+- `doubts:` anything you could NOT resolve from code + docs — ambiguity goes here,
+  never into invented prose
+
+## Rules
+- Facts come from the code, its tests, and `git diff` — never from your priors.
+- Match each doc's existing voice and formatting; smallest edit that makes it true.
+- Never touch code, .forge/ internals, or generated files (AGENTS.md).
diff --git a/global/tools/catchup/SKILL.md b/global/tools/catchup/SKILL.md
new file mode 100644
index 0000000..9512f3d
--- /dev/null
+++ b/global/tools/catchup/SKILL.md
@@ -0,0 +1,25 @@
+---
+name: catchup
+description: Start-of-session context rebuild. Use when resuming work in a repo after a gap, a /clear, or a machine switch — "where were we?" answered from recorded state (goal, session snapshot, decisions, recent commits) instead of assumptions.
+---
+
+# catchup — resume, don't re-assume
+
+A fresh session that guesses the project's state re-burns every iteration the last one
+already paid for. Everything essential is recorded; read it BEFORE acting.
+
+## Do (in order, before any edit)
+1. `.forge/state.md` — the last session's snapshot: goal/phase, done, next steps,
+   gotchas, open assumptions. (The SessionStart hook injects a capped version; read the
+   file for the rest.)
+2. `forge decide` — the last ten recorded decisions. Do not contradict one silently;
+   supersede it with a new `forge decide "<new choice> — <why the old one changed>"`.
+3. `git log --oneline -10` and `git status --short` — what actually happened vs what
+   the snapshot says. Trust code over prose, then fix the prose.
+4. `forge anchor show` — the standing goal. If the new request conflicts with it,
+   surface the conflict instead of quietly switching goals.
+5. For in-progress files listed in the snapshot: read them AND their tests first.
+
+## Then
+State in one short block: current goal, what was last done, what you'll do next.
+Only then start working.
diff --git a/global/tools/handoff/SKILL.md b/global/tools/handoff/SKILL.md
new file mode 100644
index 0000000..279c966
--- /dev/null
+++ b/global/tools/handoff/SKILL.md
@@ -0,0 +1,33 @@
+---
+name: handoff
+description: End-of-session checkpoint. Use when finishing, pausing, or switching away from work in a repo — it rewrites the bounded session snapshot (.forge/state.md) the NEXT session is re-injected with, so nothing essential dies with this conversation. Backed by `forge handoff`.
+---
+
+# handoff — persist what this session knows
+
+Session memory is volatile; `.forge/state.md` is the committed-brain checkpoint the
+SessionStart hook re-injects. Rewritten every time (bounded ≤150 lines), never appended —
+the next session reads a snapshot, not an archive.
+
+## When
+- Ending or pausing a work session, or before a risky context switch.
+- The completion gate blocked with "no doc or state artifact moved" — this satisfies it.
+
+## Do
+1. Gather: what got DONE (with why it matters), what comes NEXT, what BIT you
+   (gotchas: failed approaches, env quirks, traps), acceptance criteria still open.
+2. Run it:
+
+   ```bash
+   forge handoff "<done row>" "<done row 2>" \
+     --next "<next step>" --gotcha "<trap>" --criteria "<open check>"
+   ```
+
+   In-progress git files and recorded assumptions are gathered automatically.
+3. Durable, non-obvious choices graduate to the decision log:
+   `forge decide "<decision> — <reason>"`.
+
+## Rules
+- Specific beats complete: "verify() times out on pyproject repos without pytest" is a
+  gotcha; "be careful with tests" is noise.
+- Secrets are refused at write — store pointers, never values.
diff --git a/global/tools/sync-docs/SKILL.md b/global/tools/sync-docs/SKILL.md
new file mode 100644
index 0000000..b7fe4e3
--- /dev/null
+++ b/global/tools/sync-docs/SKILL.md
@@ -0,0 +1,30 @@
+---
+name: sync-docs
+description: After ANY code change, sweep the diff for documentation that just went stale. Use when finishing an edit, before a commit/PR, or when the completion gate blocks — it turns "did I forget a doc?" into a mechanical checklist. Backed by `forge docs sync`.
+---
+
+# sync-docs — make every artifact true again
+
+A code change isn't done while prose still describes the old behavior. The sweep is
+mechanical: diff → identifiers (paths, definitions, called symbols — added AND removed)
+→ every doc artifact is scanned and answers one of three ways.
+
+## Do
+1. Run the sweep:
+
+   ```bash
+   forge docs sync            # human report; --json for tooling; --base <ref> to widen
+   ```
+
+2. Read the verdicts:
+   - **STALE** — the doc mentions a changed identifier (each hit cited `file:line`).
+     Open it, update the mention to match reality — or say explicitly why it's fine.
+   - **UPDATED** — the doc already moved with this diff. Nothing owed.
+   - **VERIFIED-UNAFFECTED** — zero mentions; the reason is recorded. Checked, not assumed.
+3. Re-run until STALE is empty (or every remaining hit is justified out loud).
+4. CHANGELOG is exempt by design (append-only history) — add a NEW entry for
+   user-facing changes instead of editing old ones.
+
+## Rules
+- Never mark a doc unaffected by assumption — that's exactly what the sweep verifies.
+- Big diff? Delegate this whole loop to the `doc-sync` agent to keep your context clean.
diff --git a/source/rules.json b/source/rules.json
index 49ea743..2667e17 100644
--- a/source/rules.json
+++ b/source/rules.json
@@ -23,6 +23,15 @@
         "Run `verification.checklist` and show the output before claiming done."
       ]
     },
+    {
+      "id": "end-to-end",
+      "title": "End-to-end completeness",
+      "rules": [
+        "A change is DONE only when code, tests, docs, and session state moved together: run `forge docs sync` to sweep the diff for stale doc mentions, and `forge handoff \"<done>\" --next \"<next>\"` before stopping. A Stop gate enforces this floor — code moved with nothing following blocks once, with the repair checklist.",
+        "Never assume silently: answer preflight's clarifying questions, or proceed knowing the assumption is RECORDED to the session log and resurfaces in the handoff — verify it before claiming done.",
+        "Record non-obvious choices with `forge decide \"<decision> — <reason>\"`; read `.forge/decisions.md` (or bare `forge decide`) before re-deciding anything a past session settled."
+      ]
+    },
     {
       "id": "reuse",
       "title": "Reuse & dependencies",
diff --git a/test/skills.test.js b/test/skills.test.js
index 4903756..28bd6a2 100644
--- a/test/skills.test.js
+++ b/test/skills.test.js
@@ -39,3 +39,26 @@ test("every crew agent declares name + description", () => {
 test("verifier crew is diff/review scoped", () => {
   assert.match(read("global/crew/verifier.md").toLowerCase(), /diff|review/);
 });
+
+test("end-to-end skills (handoff / sync-docs / catchup) have valid frontmatter naming their command", () => {
+  for (const [skill, cmd] of [
+    ["handoff", "forge handoff"],
+    ["sync-docs", "forge docs sync"],
+    ["catchup", "forge decide"],
+  ]) {
+    const md = read(`global/tools/${skill}/SKILL.md`);
+    const fm = frontmatter(md);
+    assert.equal(fm?.name, skill, `${skill} frontmatter name`);
+    assert.ok(fm?.description, `${skill} has description`);
+    assert.ok(md.includes(cmd), `${skill} body references \`${cmd}\``);
+  }
+});
+
+test("doc-sync crew agent declares frontmatter and never edits code", () => {
+  const md = read("global/crew/doc-sync.md");
+  const fm = frontmatter(md);
+  assert.equal(fm?.name, "doc-sync");
+  assert.ok(fm?.description, "doc-sync has description");
+  assert.match(md, /forge docs sync/);
+  assert.match(md, /never edit code/i);
+});

From b85e9044bfd9b3ab951a64eb771c8a16c9d34841 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 10 Jul 2026 08:19:44 +0000
Subject: [PATCH 09/12] docs: document the end-to-end reliability layer
 everywhere it lands
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CLI dispatch + command registry for handoff/decide/docs-sync; README
command rows + feature bullet; GUIDE sections (handoff, decide, docs
sync, the completion-gate decision table, env rows FORGE_STOPGATE +
FORGE_INTENT); ARCHITECTURE §5 (the reliability layer, incl. the
deliberate checkpointCadence deferral); CHANGELOG [Unreleased] entries;
CLAUDE.md test count. forge docs check passes on this tree.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
---
 ARCHITECTURE.md | 50 ++++++++++++++++++++++++++
 CHANGELOG.md    | 42 ++++++++++++++++++++++
 CLAUDE.md       |  4 ++-
 README.md       |  9 ++++-
 docs/GUIDE.md   | 93 ++++++++++++++++++++++++++++++++++++++++++++++++-
 src/cli.js      | 81 ++++++++++++++++++++++++++++++++++++++++--
 src/commands.js |  6 ++--
 7 files changed, 277 insertions(+), 8 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 4199386..f332729 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -185,6 +185,56 @@ compression ladder, and reports the *computed missing set* — the inputs it cou
 assemble. That missing set is exactly what the substrate pipeline's context stage reads
 to decide whether an edit is safe to start. Surface: `forge reuse query | mint | stats`.
 
+## 5. The end-to-end reliability layer
+
+Two failure modes this layer exists to kill: **partial work** (code changes without the
+artifacts that depend on it) and **session amnesia** (the next session re-assumes what
+this one knew). Instructions raise the *probability* of correct behavior; deterministic
+hooks guarantee a *floor* — with per-task miss rate `1−p` and gate catch rate `c`,
+silent misses fall to `(1−p)(1−c)`, and every layer here is one more `c`.
+
+**The completion gate (Stop, `src/gate.js`).** The only Stop-path guard that may answer:
+`completion-gate.sh` runs synchronously (the lesson-mining `cortex.sh stop` stays
+detached and can never block). Everything changed since the session's git baseline —
+committed ∪ working tree — is classified by ONE total function derived from the atlas
+registries (`CODE_EXTS`/`DOC_EXTS`/config rules) plus the shared test-file predicate.
+Code moved with no doc/state artifact → block once with the repair checklist as the
+reason; every other row allows, every internal error allows (fail-open), a marker caps
+the cost at one extra turn, `FORGE_STOPGATE=0` kills it. `.forge/state.md` is gitignored,
+so its signal is mtime-vs-baseline (the baseline file's mtime *is* session start).
+
+**Session anchoring (SessionStart, `src/session.js`).** Records `HEAD` once per session
+(`.forge/sessions/<sid>.base`; resume keeps it), prunes week-old session artifacts, and
+injects: learned lessons, the anchored goal, the handoff snapshot, recent commits, and
+uncommitted changes — a fresh session orients on evidence, not priors.
+
+**The state/decision stores (`src/handoff.js`, `src/decide.js`).** `state.md` is a
+bounded REWRITE (snapshot semantics — loader cost stays O(bound) forever);
+`decisions.md` is append-only ADR-lite with a machine-readable `decision` ledger twin
+(log semantics — supersede, never edit). Both refuse secrets at write.
+
+**The diff-driven docs sweep (`src/docs_sync.js`).** `docs check` reconciles registries;
+`docs sync` answers the diff-shaped question: changed identifiers (paths + definitions +
+called symbols, from added AND removed lines, via the same `RULES` grammars the atlas
+parses) swept against every doc artifact → UPDATED / STALE (file:line hits) /
+VERIFIED-UNAFFECTED with the reason recorded. Pure reporter; the gate provides the teeth.
+
+**Intent cards (`src/intent.js`).** Prompt → intent by the same exemplar k-NN math as
+model routing — a labeled bank (English + Hinglish rows) under overlap similarity with a
+confidence gate, NOT a keyword DFA. Note `intentGrams` ≠ `contentGrams`: route.js stops
+generic task verbs (`fix`/`add`/`build`) as complexity noise, but they are exactly the
+intent signal — same math, different stop-set data.
+
+**The evidence trail (preflight).** Once a goal is anchored, every prompt appends its
+graded `driftScore` to the session log; `cusum` (until now test-only math) accumulates
+the series and a sustained alarm rides the gate's block reason. Proceeding under
+assumptions appends a record the advisory names and the next handoff surfaces — a guess
+can never silently become a fact.
+
+**Deliberately not wired:** `checkpointCadence` (optimal-stopping check spacing) still
+has no runtime step-loop to consume it — wiring it would mean inventing one. It stays
+library math with tests until a real consumer exists.
+
 ## Component map — the reuse ledger (30 components)
 
 **Reuse (rename + swap brand token, logic unchanged):**
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b1c179f..5267672 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,43 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
 ### Added
+- **The completion gate** — a synchronous Stop hook (`global/guards/completion-gate.sh`
+  → `src/gate.js`) that blocks a session ONCE when code changed but no doc or state
+  artifact moved with it, answering with the repair checklist (`forge docs sync`,
+  `forge handoff`, `forge decide`, plus a CUSUM goal-drift alarm when the session's
+  recorded drift sustained). Loop-safe (`stop_hook_active` + once-per-session marker),
+  fail-open on every error path, kill switch `FORGE_STOPGATE=0`. Classification derives
+  from the atlas registries + the shared test-file predicate — no parallel regex lists.
+- **`forge handoff`** — the bounded session snapshot: rewrites `.forge/state.md`
+  (≤150 lines; goal/phase, acceptance criteria, done, next, gotchas, recorded
+  assumptions, in-progress git files) and SessionStart re-injects it, so the next
+  session resumes instead of re-assuming. Refuses secrets like every forge store.
+- **`forge decide`** — append-only ADR-lite decision log (`.forge/decisions.md`,
+  `D-####` numbering) + a machine-readable `decision` ledger twin; bare `forge decide`
+  lists the last ten. Supersede with a new entry, never an edit.
+- **`forge docs sync`** — the diff-driven half of docs↔code alignment: changed
+  identifiers (paths, definitions, called symbols — from added AND removed lines) swept
+  against every doc artifact → UPDATED / STALE (file:line hits) / VERIFIED-UNAFFECTED
+  (reason recorded). Advisory by default, `--strict` for CI, `--base <ref>` to widen;
+  CHANGELOG and the decision log are exempt (append-only history).
+- **Session baseline + rehydration** — SessionStart records the session's git anchor
+  (`.forge/sessions/<sid>.base`; a resume never moves it), prunes week-old session
+  artifacts, and injects the handoff snapshot + last 10 commits + uncommitted changes.
+- **Intent protocol cards** — UserPromptSubmit classifies the prompt with the same
+  exemplar k-NN math as routing (labeled bank incl. Hinglish rows, overlap similarity,
+  confidence gate) and injects a bugfix/feature/refactor/release protocol card once per
+  run of that intent; questions get no ceremony. Kill switch `FORGE_INTENT=0`.
+- **Recorded assumptions** — when preflight proceeds without asking, the assumption is
+  appended to the session log, named in the advisory, and surfaces in the next handoff;
+  the per-prompt goal-drift score is recorded the same way and feeds the gate's CUSUM.
+- **Config artifacts in the atlas** — CI workflows (`.github` is now walked),
+  manifests, and Dockerfiles become `config:` nodes with `references` edges to the code
+  paths they name, so `forge impact` lists the configs a change can break (lockfiles
+  excluded as generated churn).
+- **End-to-end skills + agent** — `handoff`, `sync-docs`, and `catchup` skills, a
+  `doc-sync` crew agent that repairs stale docs in its own context, and an
+  `end-to-end` rules section (Definition of Done, no silent assumptions, decision log)
+  compiled into every tool by `forge sync`.
 - **Gateway environments work end to end** — `ANTHROPIC_AUTH_TOKEN` is recognized
   everywhere `ANTHROPIC_API_KEY` is; `ANTHROPIC_MODEL` / `FORGE_MODEL` pin one model
   (bypassing tier routing); a gateway-looking `ANTHROPIC_BASE_URL` auto-classifies as
@@ -46,6 +83,11 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **`providerStatus` probes `/health` on any custom base URL** and reports behavioral
   gateway evidence (a proxy that answers /health is a gateway, whatever its hostname).
 
+### Fixed
+- **`cortex.sh` hook entry resolution in symlink installs** — `~/.forge/src/…` pointed
+  at the nonexistent `global/src/`, silently no-opping every cortex hook outside plugin
+  mode; the shim now resolves through the symlink (`pwd -P`), same as `secret-redact.sh`.
+
 ## [0.8.1] - 2026-07-08
 
 ### Added
diff --git a/CLAUDE.md b/CLAUDE.md
index bd12758..9b5ab32 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,3 +1,5 @@
+@AGENTS.md
+
 # forgekit — contributor instructions
 
 ## Stack
@@ -7,7 +9,7 @@
 
 ## Commands
 - Install: `npm ci`
-- Test: `npm test` (node:test, 471+ tests)
+- Test: `npm test` (node:test, 600+ tests)
 - Lint + format: `npx biome check` (or `npm run check`)
 - Typecheck: `npm run typecheck`
 - Build pages: `npm run pages:build`
diff --git a/README.md b/README.md
index 4eefbd1..e6eaf5f 100644
--- a/README.md
+++ b/README.md
@@ -90,6 +90,11 @@ The day-to-day value first — the substrate gives a frozen model what it can't
 - **Guardrails that can't be forgotten.** Deterministic hooks enforce the rules a model must
   never break (protected paths, cost budget, doom loops) — they survive a context compaction
   the way `CLAUDE.md` prose does not.
+- **Work that finishes end to end.** A completion gate blocks "done" once per session when
+  code moved but no doc or state artifact followed — with the repair checklist as the answer
+  (`forge docs sync` sweeps the diff for stale prose, `forge handoff` writes the bounded
+  session snapshot the next session resumes from, `forge decide` records choices so no
+  session re-decides them).
 - **One config for 9 tools.** Author your rules once; Forge emits each tool's native config,
   plus MCP for Roo and VS Code. Zero runtime dependencies — one Node CLI, plain files in git,
   no server.
@@ -156,7 +161,7 @@ default 25-file threshold).
 | **Config layer** | `forge init` | emit every tool's native config from one source |
 | | `forge sync` | recompile canonical source → each tool's native files (idempotent) |
 | | `forge doctor` | pass/fail health check: tools, guards, MCP, drift |
-| | `forge docs` | docs↔code drift check — commands, env vars, MCP tools, CHANGELOG vs reality |
+| | `forge docs` | docs↔code drift — `check` reconciles commands/env/MCP/CHANGELOG; `sync` sweeps the diff for stale doc mentions |
 | | `forge config` | provider setup — show / switch / add providers, set the default model |
 | | `forge harden` | wire gitleaks pre-commit + sandbox settings |
 | | `forge catalog` | Start-Here index of every tool / crew / guard |
@@ -167,6 +172,8 @@ default 25-file threshold).
 | | `forge brain` | portable project-memory index |
 | | `forge cortex` | self-correcting lessons — `status` / `why` |
 | | `forge reuse` | proof-carrying code cache — query / mint / stats |
+| | `forge handoff` | bounded session snapshot (`.forge/state.md`) — rewritten each handoff, re-injected every session start |
+| | `forge decide` | append-only decision log (`.forge/decisions.md`, D-#### ADR-lite) — future sessions read it instead of re-deciding |
 | **Substrate (pre-action)** | `forge substrate` | the full pre-action gate in one pass |
 | | `forge preflight` | assumption / info-gap check |
 | | `forge route` | cheapest capable model tier (`route gateway` emits LiteLLM config) |
diff --git a/docs/GUIDE.md b/docs/GUIDE.md
index 4dcdcc3..49632f3 100644
--- a/docs/GUIDE.md
+++ b/docs/GUIDE.md
@@ -28,7 +28,7 @@ Every command is real and wired. Grouped by what it does:
 | Group | Commands |
 | --- | --- |
 | **Config / cross-tool sync** | `forge init` · `forge sync` · `forge doctor` · `forge docs` · `forge config` · `forge harden` · `forge catalog` · `forge brand` |
-| **Memory & ledger (PCM)** | `forge ledger` · `forge recall` · `forge remember` · `forge brain` · `forge cortex` · `forge reuse` |
+| **Memory & ledger (PCM)** | `forge ledger` · `forge recall` · `forge remember` · `forge brain` · `forge cortex` · `forge reuse` · `forge handoff` · `forge decide` |
 | **Code graph & retrieval** | `forge atlas` · `forge context` |
 | **Substrate / pre-action** | `forge substrate` · `forge preflight` · `forge route` · `forge impact` · `forge scope` · `forge imagine` · `forge anchor` · `forge diagnose` · `forge lean` · `forge cost` |
 | **Verification & safety** | `forge verify` · `forge scan` · `forge spec` |
@@ -283,6 +283,55 @@ new session re-injects it at SessionStart, a bare `forge anchor` checks against
 `forge anchor show` / `forge anchor clear` manage it. A goal set on Monday still anchors
 Thursday's session — no more each-session re-assumption of what you're working toward.
 
+### `forge handoff "<done>"` — the bounded session snapshot
+
+Session memory is volatile; `.forge/state.md` is the checkpoint that survives. One
+command rewrites it (never appends — it stays ≤150 lines forever) with what got done,
+what comes next, the gotchas, and any assumptions this session proceeded under (gathered
+automatically from the session log, along with in-progress git files):
+
+```bash
+forge handoff "built the export endpoint" \
+  --next "wire pagination" --gotcha "sqlite locks on parallel writes" \
+  --criteria "export completes under 5s on the fixture db"
+```
+
+Every new session re-injects the snapshot at SessionStart, so the next session — any
+machine, any day — *resumes* instead of re-assuming. Refuses secrets, like every forge
+store. Updating it also satisfies the completion gate (below): the weakest way to stop
+cleanly is to tell the future what happened.
+
+### `forge decide "<decision — reason>"` — the append-only decision log
+
+Sessions re-decide (or silently contradict) what a past session already settled, because
+nothing durable recorded the choice. `forge decide` appends one ADR-lite line to
+`.forge/decisions.md` (`- **D-0007** (2026-07-10): …`) and mints a machine-readable
+`decision` claim in the ledger. Bare `forge decide` lists the last ten. Append-only by
+design: a decision that stops being true gets a *new* entry, never an edit — the log is
+history, and `forge docs sync` exempts it for exactly that reason.
+
+### `forge docs sync` — which prose did this diff make stale?
+
+`forge docs check` reconciles the registries; `docs sync` answers the diff-shaped
+question. It extracts the changed identifiers (paths, definitions, called symbols —
+from added *and removed* lines, so deletions count), scans every doc artifact (atlas doc
+nodes + README/GUIDE/ARCHITECTURE + `.forge/state.md`), and gives each one a verdict:
+
+```console
+$ forge docs sync
+docs sync — diff vs a1b2c3d: 2 changed file(s), 7 identifier(s)
+  UPDATED     docs/GUIDE.md (changed in this diff)
+  STALE       README.md — mentions changed identifiers:
+                README.md:41  `validateOrder` — Use `validateOrder` from `src/val.js`…
+  VERIFIED    ARCHITECTURE.md — mentions none of the 7 changed identifiers
+```
+
+**STALE** hits are cited `file:line` — update them or justify out loud. **VERIFIED**
+means checked-not-assumed: the reason is recorded. Advisory by default (it runs
+mid-repair); `--strict` exits 1 on stale docs for CI, `--base <ref>` widens the diff,
+`--json` for tooling. The base defaults to this session's git baseline when the hooks
+recorded one, else `HEAD`.
+
 ### `forge verify` — did it actually work?
 
 The independent check: runs the real test suite and flags edited symbols that aren't in
@@ -626,6 +675,7 @@ Plain `forge cost` remains the per-day spend view via `ccusage`.
 | `forge sync` | Recompile `source/` → each tool's files (idempotent). |
 | `forge doctor` | Health check: layers, install, drift, cortex. |
 | `forge docs check` | Docs↔code drift: commands, env vars, MCP tools, CHANGELOG reconciled against the code (CI-gated on the forge repo itself). |
+| `forge docs sync` | Diff-driven stale-docs sweep: UPDATED / STALE (file:line hits) / VERIFIED-UNAFFECTED per artifact (see the full section above). |
 | `forge catalog` | Start-Here index of every tool / crew / guard. |
 | `forge brain` / `forge remember` | Portable project memory inlined into `AGENTS.md`. |
 | `forge cost` | Real per-day spend (via `ccusage`) + the cost ceiling; `--stages` for the measured report. |
@@ -679,6 +729,45 @@ Forge substrate — pre-action advisory (advisory, never blocks):
 Nothing to wire — the plugin's [`hooks/hooks.json`](../hooks/hooks.json) installs the
 `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` guards for you.
 
+Three more ambient layers ride the same hooks:
+
+**Session rehydration (SessionStart).** Besides lessons and the anchored goal, every
+session start injects the handoff snapshot (`.forge/state.md`), the last 10 commits, and
+any uncommitted changes — and records the session's git baseline (`HEAD`) that the
+completion gate and `forge docs sync` diff against. A `--resume` never moves the baseline.
+
+**Intent protocol cards (UserPromptSubmit).** The prompt is classified by the same
+exemplar k-NN math as model routing (labeled examples + overlap similarity — extended by
+adding rows, including Hinglish ones, never by editing regexes). A work intent
+(bugfix / feature / refactor / release) injects a ~6-line protocol card once per run of
+that intent; questions get no ceremony, and below-confidence prompts get nothing.
+`FORGE_INTENT=0` disables.
+
+**The completion gate (Stop).** The deterministic floor under "done": when the session
+tries to finish, everything changed since the baseline (committed ∪ working tree) is
+classified against the same registries the atlas is built from — and if **code moved but
+no doc or state artifact moved with it**, the stop is blocked *once*, with the repair
+checklist as the reason (`forge docs sync` → update stale docs, `forge handoff`,
+`forge decide`; plus a CUSUM goal-drift alarm when the session's recorded drift series
+sustained). The decision table, first match wins:
+
+| # | Condition | Decision |
+| --- | --- | --- |
+| 1 | `stop_hook_active` (already continuing from a block) | allow |
+| 2 | not a git repo / git unusable | allow (fail-open) |
+| 3 | this session already blocked once | allow (marker) |
+| 4 | `FORGE_STOPGATE=0` | allow (kill switch) |
+| 5 | nothing changed (or only `.forge/` internals / generated files) | allow |
+| 6 | docs changed — or `.forge/state.md`/`decisions.md` touched since session start | allow |
+| 7 | **code changed ∧ no doc/state artifact moved** | **block once + checklist** |
+| 8 | only tests / configs / other files changed | allow |
+| 9 | any internal error in the gate itself | allow (fail-open) |
+
+Test-only sessions pass on purpose (a regression test owes no prose), and the state
+snapshot counts via its mtime against the baseline because `.forge/` is gitignored. The
+gate can never loop (rows 1+3) and never brick a session (rows 2+9) — it costs at most
+one extra turn, exactly when that turn was owed.
+
 ### Every other tool — a rule + MCP tools
 
 `forge init` writes a rule into each tool's native config (`AGENTS.md`, `.cursor/rules`,
@@ -843,6 +932,8 @@ code reads but this table misses fails CI on the forge repo):
 | `FORGE_VERIFY_TIMEOUT_MS` | verify test-run timeout (default 600000) |
 | `FORGE_SKILLGATE_NOEXTERNAL` | `1` skips the external scanner in `forge scan` (heuristic only) |
 | `ENABLE_CORTEX_DISTILL` | `1` distills new lessons into prose via a cheap model call |
+| `FORGE_STOPGATE` | `0` disables the Stop completion gate (code-without-docs block) |
+| `FORGE_INTENT` | `0` disables intent protocol cards on prompts |
 | `FORGE_DEBUG` | `1` writes fail-safe error details to stderr instead of swallowing them |
 
 ---
diff --git a/src/cli.js b/src/cli.js
index 52af723..2ce6a07 100755
--- a/src/cli.js
+++ b/src/cli.js
@@ -133,11 +133,26 @@ async function run(argv) {
     return;
   }
   if (cmd === "docs") {
-    // Self-check of the forge package's own docs against its code (commands table,
-    // env reads, MCP registry, CHANGELOG). `forge docs check` is the only subcommand.
+    const json = argv.includes("--json");
+    const sub = argv.slice(1).filter((a) => !a.startsWith("--"))[0] || "check";
+    // `sync` sweeps THIS repo's diff for stale doc mentions (advisory by default —
+    // it runs mid-repair from the completion gate's checklist; --strict for CI).
+    if (sub === "sync") {
+      const { docsSyncReport, renderDocsSync } = await import("./docs_sync.js");
+      const baseIdx = argv.indexOf("--base");
+      const r = docsSyncReport(process.cwd(), {
+        base: baseIdx >= 0 ? argv[baseIdx + 1] : undefined,
+      });
+      if (json) console.log(JSON.stringify(r, null, 2));
+      else console.log(renderDocsSync(r));
+      if (argv.includes("--strict") && r.stale.length) process.exitCode = 1;
+      return;
+    }
+    // `check` — self-check of the forge package's own docs against its code (commands
+    // table, env reads, MCP registry, CHANGELOG).
     const { docsCheck } = await import("./docs_check.js");
     const r = docsCheck();
-    if (argv.includes("--json")) {
+    if (json) {
       console.log(JSON.stringify(r, null, 2));
       if (!r.ok) process.exitCode = 1;
       return;
@@ -1123,6 +1138,66 @@ async function run(argv) {
     console.log(json ? JSON.stringify(r, null, 2) : renderAnchor(r));
     return; // advisory — never fails the process
   }
+  if (cmd === "handoff") {
+    const { writeState } = await import("./handoff.js");
+    const json = argv.includes("--json");
+    const args = argv.slice(1).filter((a) => a !== "--json");
+    // Repeatable flags collect rows; positionals are "done" rows. Piped stdin (one row
+    // per line) covers agents that assemble the summary programmatically.
+    const fields = { done: [], next: [], gotchas: [], criteria: [] };
+    const FLAG = { "--next": "next", "--gotcha": "gotchas", "--criteria": "criteria" };
+    for (let i = 0; i < args.length; i += 1) {
+      if (FLAG[args[i]]) fields[FLAG[args[i]]].push(args[++i] ?? "");
+      else if (args[i] === "--phase") fields.phase = args[++i] ?? "";
+      else fields.done.push(args[i]);
+    }
+    if (!fields.done.length && !process.stdin.isTTY) {
+      try {
+        const { readFileSync } = await import("node:fs");
+        fields.done = readFileSync(0, "utf8").split("\n");
+      } catch {}
+    }
+    const r = writeState(process.cwd(), fields);
+    if (json) return console.log(JSON.stringify(r, null, 2));
+    if (!r.ok) {
+      console.error(
+        `${BRAND.cli} handoff: ${r.reason}\nusage: ${BRAND.cli} handoff "<done>" [--next "<step>"] [--gotcha "<trap>"] [--criteria "<check>"] [--phase <p>]`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+    console.log(
+      `  state written: ${r.path} (${r.lines} lines)\n  (re-injected at every session start — the next session resumes instead of re-assuming)`,
+    );
+    return;
+  }
+  if (cmd === "decide") {
+    const { appendDecision, listDecisions } = await import("./decide.js");
+    const json = argv.includes("--json");
+    const text = argv
+      .slice(1)
+      .filter((a) => a !== "--json")
+      .join(" ");
+    if (!text) {
+      const rows = listDecisions(process.cwd(), { limit: 10 });
+      if (json) return console.log(JSON.stringify(rows, null, 2));
+      console.log(
+        rows.length
+          ? rows.map((d) => `  ${d.id} (${d.date}): ${d.text}`).join("\n")
+          : `  no decisions recorded — ${BRAND.cli} decide "<what was decided — why>"`,
+      );
+      return;
+    }
+    const r = appendDecision(process.cwd(), text);
+    if (json) return console.log(JSON.stringify(r, null, 2));
+    if (!r.ok) {
+      console.error(`${BRAND.cli} decide: ${r.reason}`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`  recorded ${r.id}: ${r.text}`);
+    return;
+  }
   if (cmd === "diagnose") {
     const { diagnose, THRASH_K } = await import("./diagnose.js");
     const json = argv.includes("--json");
diff --git a/src/commands.js b/src/commands.js
index c8a82ad..d5b246b 100644
--- a/src/commands.js
+++ b/src/commands.js
@@ -29,6 +29,8 @@ export const COMMANDS = {
   substrate: "one pre-action gate: assumptions, route, impact, scope, memory, verify",
   scope: "decompose files into independent clusters (+ coupled files you didn't name)",
   anchor: "goal-drift check — are your actual (git) changes still on the stated goal?",
+  handoff: "bounded session snapshot — rewrite .forge/state.md, re-injected each session start",
+  decide: "append-only decision log — D-#### ADR-lite entries in .forge/decisions.md",
   diagnose:
     "doom-loop check — record a failure; 3× the same signature mints a diagnosis + escalation",
   imagine: "consequence simulation — predicted breaks + the minimal dry-run test suite for a task",
@@ -37,12 +39,12 @@ export const COMMANDS = {
     "deterministic UI checks — contrast <fg> <bg> · fingerprint <file...> · design <file...> · visual <file-or-url>",
   dash: "local dashboard over the ledger, metrics, and blast radius",
   brand: "print the active brand token map",
-  docs: "docs↔code drift check — commands, env vars, MCP tools, CHANGELOG vs reality",
+  docs: "docs↔code drift — check (registry reconcile) / sync (diff-driven stale-docs sweep)",
 };
 
 export const GROUPS = {
   Core: ["init", "sync", "doctor", "catalog", "docs"],
-  Memory: ["cortex", "recall", "remember", "brain", "ledger", "reuse"],
+  Memory: ["cortex", "recall", "remember", "brain", "ledger", "reuse", "handoff", "decide"],
   Substrate: [
     "substrate",
     "preflight",

From 2d7851535b7b80700621578dcb32fae7c10652fd Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 10 Jul 2026 09:47:04 +0000
Subject: [PATCH 10/12] =?UTF-8?q?fix(gate,memory,docs):=20harden=20per=20t?=
 =?UTF-8?q?wo-angle=20adversarial=20review=20=E2=80=94=2012=20verified=20d?=
 =?UTF-8?q?efects?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Gate: the changed set is now SESSION-SCOPED — files from commits with
committer time >= session start plus worktree changes minus the dirt
snapshotted at SessionStart — so pre-existing edits, branch switches, and
git pulls are never pinned on the agent (three demonstrated false-block
classes). All git parsing moved to -z NUL output (C-quoted unicode/space/
arrow paths classified correctly). The block-once marker is written BEFORE
blocking and an unwritable marker stands down instead of nagging every
turn; a missing session_id disables gating (no shared 'default' state);
SessionStart prunes BEFORE anchoring so a >7-day resume re-anchors instead
of losing its baseline; vendor trees never enter the changed set.

Memory: readState no longer truncates at a '<!--' inside snapshot rows
(only the exact provenance line is stripped); forge decide takes an atomic
mkdir lock so concurrent appends can't mint duplicate D-#### ids or
interleave headers, and a failed append reports instead of half-succeeds;
recorded assumptions dedupe and cap before entering the bounded snapshot.

Docs sweep: .forge/state.md left the scanned set (handoff writes changed
paths into it by design — scanning it was an unfixable self-reference);
docs touched in the diff still answer for REMOVED symbols (the rename
case); all-lowercase symbols count only inside backtick code spans; an
unknown --base errors instead of silently diffing the index.

Every fix carries a regression test (605 total, 0 failures).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
---
 ARCHITECTURE.md         |  20 ++++--
 CHANGELOG.md            |  12 ++++
 docs/GUIDE.md           |  41 +++++++----
 src/cli.js              |   2 +-
 src/cortex_hook_main.js |   8 ++-
 src/decide.js           |  64 +++++++++++++----
 src/docs_sync.js        | 152 ++++++++++++++++++++++++++++------------
 src/gate.js             |  92 +++++++++++++++++++-----
 src/handoff.js          |  30 +++++---
 src/session.js          |  48 ++++++++++++-
 test/decide.test.js     |  24 +++++++
 test/docs_sync.test.js  |  63 ++++++++++++++++-
 test/handoff.test.js    |  26 +++++++
 test/session.test.js    |  36 +++++++++-
 test/stop_gate.test.js  |  68 ++++++++++++++++++
 15 files changed, 569 insertions(+), 117 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index f332729..466f1f5 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -195,13 +195,19 @@ silent misses fall to `(1−p)(1−c)`, and every layer here is one more `c`.
 
 **The completion gate (Stop, `src/gate.js`).** The only Stop-path guard that may answer:
 `completion-gate.sh` runs synchronously (the lesson-mining `cortex.sh stop` stays
-detached and can never block). Everything changed since the session's git baseline —
-committed ∪ working tree — is classified by ONE total function derived from the atlas
-registries (`CODE_EXTS`/`DOC_EXTS`/config rules) plus the shared test-file predicate.
-Code moved with no doc/state artifact → block once with the repair checklist as the
-reason; every other row allows, every internal error allows (fail-open), a marker caps
-the cost at one extra turn, `FORGE_STOPGATE=0` kills it. `.forge/state.md` is gitignored,
-so its signal is mtime-vs-baseline (the baseline file's mtime *is* session start).
+detached and can never block). The changed set is **session-scoped**: files from commits
+whose committer time is ≥ session start, plus working-tree changes minus the dirt
+snapshotted at SessionStart — so pre-existing edits, branch switches, and `git pull`s
+are never pinned on the agent (adversarial review demonstrated all three false-block
+classes). Paths are classified by ONE total function derived from the atlas registries
+(`CODE_EXTS`/`DOC_EXTS`/config rules) plus the shared test-file predicate, parsed from
+`-z` NUL-separated git output (C-quoted unicode paths classify correctly). Code moved
+with no doc/state artifact → block once with the repair checklist as the reason; every
+other row allows, every internal error allows (fail-open), the once-per-session marker
+is written BEFORE the block (unwritable marker → stand down rather than nag every turn),
+a missing `session_id` disables gating (no shared-state leaks between sessions), and
+`FORGE_STOPGATE=0` kills it. `.forge/state.md` is gitignored, so its signal is
+mtime-vs-baseline (the baseline file's mtime *is* session start).
 
 **Session anchoring (SessionStart, `src/session.js`).** Records `HEAD` once per session
 (`.forge/sessions/<sid>.base`; resume keeps it), prunes week-old session artifacts, and
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5267672..a5f6154 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -87,6 +87,18 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **`cortex.sh` hook entry resolution in symlink installs** — `~/.forge/src/…` pointed
   at the nonexistent `global/src/`, silently no-opping every cortex hook outside plugin
   mode; the shim now resolves through the symlink (`pwd -P`), same as `secret-redact.sh`.
+- **Twelve defects found by a two-angle adversarial review of the new layer, all with
+  regression tests** — the gate no longer attributes pre-session dirt, branch-switch/pull
+  commits, or vendor trees to the session (session-scoped changed set: committer-time
+  window + SessionStart dirty snapshot); `-z` NUL parsing keeps unicode/space/arrow paths
+  correctly classified; an unwritable block-once marker stands down instead of blocking
+  every turn; a missing `session_id` disables gating instead of sharing `default` state;
+  a >7-day resume re-anchors instead of losing its baseline to the prune; `readState` no
+  longer truncates snapshots whose rows contain `<!--`; `forge decide` takes a lock so
+  concurrent appends can't mint duplicate D-#### ids; the docs sweep stopped scanning its
+  own bookkeeping (`.forge/state.md`), scans touched docs for REMOVED symbols (the rename
+  case), counts lowercase symbols only inside backticks, dedupes recorded assumptions,
+  and errors on an unknown `--base` instead of mislabeling the report.
 
 ## [0.8.1] - 2026-07-08
 
diff --git a/docs/GUIDE.md b/docs/GUIDE.md
index 49632f3..544d7f6 100644
--- a/docs/GUIDE.md
+++ b/docs/GUIDE.md
@@ -315,7 +315,7 @@ history, and `forge docs sync` exempts it for exactly that reason.
 `forge docs check` reconciles the registries; `docs sync` answers the diff-shaped
 question. It extracts the changed identifiers (paths, definitions, called symbols —
 from added *and removed* lines, so deletions count), scans every doc artifact (atlas doc
-nodes + README/GUIDE/ARCHITECTURE + `.forge/state.md`), and gives each one a verdict:
+nodes + README/GUIDE/ARCHITECTURE), and gives each one a verdict:
 
 ```console
 $ forge docs sync
@@ -328,9 +328,16 @@ docs sync — diff vs a1b2c3d: 2 changed file(s), 7 identifier(s)
 
 **STALE** hits are cited `file:line` — update them or justify out loud. **VERIFIED**
 means checked-not-assumed: the reason is recorded. Advisory by default (it runs
-mid-repair); `--strict` exits 1 on stale docs for CI, `--base <ref>` widens the diff,
-`--json` for tooling. The base defaults to this session's git baseline when the hooks
-recorded one, else `HEAD`.
+mid-repair); `--strict` exits 1 on stale docs for CI, `--base <ref>` widens the diff
+(an unknown ref errors instead of silently mislabeling), `--json` for tooling. The base
+defaults to this session's git baseline when the hooks recorded one, else `HEAD`.
+
+Precision rules the sweep applies: symbols come only from non-test code files (prose
+parentheses are not call sites); all-lowercase symbols like `cusum` count only inside
+backtick code spans (in plain prose they're indistinguishable from English); a doc
+touched in the same diff still answers for **removed** symbols (updated-for-one-reason
+isn't updated-for-the-rename); and `.forge/state.md` is never scanned — handoff writes
+the changed-file list into it by design, so the gate's mtime check covers it instead.
 
 ### `forge verify` — did it actually work?
 
@@ -754,18 +761,24 @@ sustained). The decision table, first match wins:
 | # | Condition | Decision |
 | --- | --- | --- |
 | 1 | `stop_hook_active` (already continuing from a block) | allow |
-| 2 | not a git repo / git unusable | allow (fail-open) |
-| 3 | this session already blocked once | allow (marker) |
-| 4 | `FORGE_STOPGATE=0` | allow (kill switch) |
-| 5 | nothing changed (or only `.forge/` internals / generated files) | allow |
-| 6 | docs changed — or `.forge/state.md`/`decisions.md` touched since session start | allow |
-| 7 | **code changed ∧ no doc/state artifact moved** | **block once + checklist** |
-| 8 | only tests / configs / other files changed | allow |
-| 9 | any internal error in the gate itself | allow (fail-open) |
-
+| 2 | no `session_id` in the hook payload (per-session promises impossible) | allow |
+| 3 | not a git repo / git unusable | allow (fail-open) |
+| 4 | this session already blocked once — or the marker can't be persisted | allow |
+| 5 | `FORGE_STOPGATE=0` | allow (kill switch) |
+| 6 | nothing changed (or only `.forge/` internals / generated files) | allow |
+| 7 | docs changed — or `.forge/state.md`/`decisions.md` touched since session start | allow |
+| 8 | **code changed ∧ no doc/state artifact moved** | **block once + checklist** |
+| 9 | only tests / configs / other files changed | allow |
+| 10 | any internal error in the gate itself | allow (fail-open) |
+
+"Changed" is **session-scoped**, not repo-scoped: files from commits made *during* the
+session (committer time ≥ session start) plus working-tree changes *minus* whatever was
+already dirty when the session began (snapshotted at SessionStart). Pre-existing dirt,
+commits reached by a branch switch or `git pull`, and vendor trees (`node_modules/`…)
+are never attributed to the agent — near-zero false blocks is the gate's credibility.
 Test-only sessions pass on purpose (a regression test owes no prose), and the state
 snapshot counts via its mtime against the baseline because `.forge/` is gitignored. The
-gate can never loop (rows 1+3) and never brick a session (rows 2+9) — it costs at most
+gate can never loop (rows 1+4) and never brick a session (rows 3+10) — it costs at most
 one extra turn, exactly when that turn was owed.
 
 ### Every other tool — a rule + MCP tools
diff --git a/src/cli.js b/src/cli.js
index 2ce6a07..2706f05 100755
--- a/src/cli.js
+++ b/src/cli.js
@@ -145,7 +145,7 @@ async function run(argv) {
       });
       if (json) console.log(JSON.stringify(r, null, 2));
       else console.log(renderDocsSync(r));
-      if (argv.includes("--strict") && r.stale.length) process.exitCode = 1;
+      if (r.error || (argv.includes("--strict") && r.stale.length)) process.exitCode = 1;
       return;
     }
     // `check` — self-check of the forge package's own docs against its code (commands
diff --git a/src/cortex_hook_main.js b/src/cortex_hook_main.js
index 85a88ae..2b90718 100644
--- a/src/cortex_hook_main.js
+++ b/src/cortex_hook_main.js
@@ -90,12 +90,14 @@ async function main() {
       if (!r.allow) process.stdout.write(JSON.stringify({ decision: "block", reason: r.reason }));
     } catch {}
   } else if (mode === "session-start") {
-    // Anchor first: record WHERE the repo stands (HEAD) so the completion gate can diff
-    // this session's changes against it; prune week-old session artifacts in the same pass.
+    // Prune BEFORE anchoring: pruning after would delete the very baseline a >7-day
+    // resume just preserved (the anchor then re-records fresh, which is the right
+    // semantics for a week-old session anyway). Then record WHERE the repo stands so
+    // the completion gate can diff this session's changes against it.
     try {
       const { pruneSessions, recordBaseline } = await import("./session.js");
-      recordBaseline(root, sid);
       pruneSessions(root);
+      recordBaseline(root, sid);
     } catch {}
     // Then everything a fresh session forgets: learned lessons, the persistent goal,
     // the handoff snapshot, and the repo's recent history.
diff --git a/src/decide.js b/src/decide.js
index 66dc136..89d8159 100644
--- a/src/decide.js
+++ b/src/decide.js
@@ -4,7 +4,7 @@
 // choices. .forge/decisions.md is ADR-lite: one line per decision, append-only. Append
 // is one syscall, merge-friendly, and never rewrites history — a decision that stops
 // being true gets a new entry, not an edit.
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { BRAND } from "./brand.js";
 import { mintClaim } from "./ledger.js";
@@ -37,6 +37,35 @@ export function listDecisions(root, { limit = 10 } = {}) {
   }
 }
 
+// mkdir is the one atomic zero-dep mutex: the D-#### number is read-then-append, and
+// two concurrent processes (a review demonstrated 12) would mint duplicate ids and
+// interleave headers without it. Held for milliseconds; a lock older than 5s is a
+// crashed holder and is stolen; total wait is bounded (~300ms) then we proceed anyway —
+// a duplicate id under pathological contention beats a lost decision.
+function withDecisionLock(root, fn) {
+  const lock = join(root, ".forge", "decisions.lock");
+  let held = false;
+  for (let i = 0; i < 60 && !held; i += 1) {
+    try {
+      mkdirSync(lock);
+      held = true;
+    } catch {
+      try {
+        if (Date.now() - statSync(lock).mtimeMs > 5000) rmdirSync(lock);
+      } catch {}
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    if (held)
+      try {
+        rmdirSync(lock);
+      } catch {}
+  }
+}
+
 /**
  * Append one decision ("<what was decided> — <why>"). Refuses secrets (same rule as
  * every forge store). Also mints a `decision` ledger claim — the machine-readable twin —
@@ -52,18 +81,27 @@ export function appendDecision(root, text, { t = Date.now() } = {}) {
     return { ok: false, reason: "refused: decision looks like it contains a secret/credential" };
   mkdirSync(join(root, ".forge"), { recursive: true });
   const p = decisionsPath(root);
-  let existing = "";
-  try {
-    existing = existsSync(p) ? readFileSync(p, "utf8") : "";
-  } catch {}
-  const prior = parseDecisions(existing);
-  const n = prior.length ? Math.max(...prior.map((d) => d.n)) + 1 : 1;
-  const id = `D-${String(n).padStart(4, "0")}`;
-  const date = new Date(t).toISOString().slice(0, 10);
-  const header = existing.trim()
-    ? ""
-    : `# Decisions\n\nAppend-only — supersede an old choice with a NEW entry (\`${BRAND.cli} decide\`), never an edit.\n\n`;
-  appendFileSync(p, `${header}- **${id}** (${date}): ${body}\n`);
+  const appended = withDecisionLock(root, () => {
+    let existing = "";
+    try {
+      existing = existsSync(p) ? readFileSync(p, "utf8") : "";
+    } catch {}
+    const prior = parseDecisions(existing);
+    const n = prior.length ? Math.max(...prior.map((d) => d.n)) + 1 : 1;
+    const id = `D-${String(n).padStart(4, "0")}`;
+    const date = new Date(t).toISOString().slice(0, 10);
+    const header = existing.trim()
+      ? ""
+      : `# Decisions\n\nAppend-only — supersede an old choice with a NEW entry (\`${BRAND.cli} decide\`), never an edit.\n\n`;
+    try {
+      appendFileSync(p, `${header}- **${id}** (${date}): ${body}\n`);
+    } catch (err) {
+      return { ok: false, reason: `could not write ${p}: ${err?.code ?? "error"}` };
+    }
+    return { ok: true, id };
+  });
+  if (!appended.ok) return appended;
+  const { id } = appended;
   try {
     const minted = mintClaim({
       kind: "decision",
diff --git a/src/docs_sync.js b/src/docs_sync.js
index 05f7511..2089b1c 100644
--- a/src/docs_sync.js
+++ b/src/docs_sync.js
@@ -10,7 +10,6 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { extname, join } from "node:path";
 import { load as loadAtlas, RULES } from "./atlas.js";
 import { CALL_IGNORE, extractCalledSymbols } from "./extract.js";
-import { statePath } from "./handoff.js";
 import { isTestFile } from "./substrate.js";
 
 function git(root, args) {
@@ -40,29 +39,38 @@ function definedNames(rel, text) {
 }
 
 /**
- * The identifier set of a diff: changed rel paths + called symbols + definition names on
- * the changed lines (added AND removed — a deleted symbol makes docs stale too).
+ * The identifier sets of a diff:
+ * - `identifiers` — changed rel paths + code-shaped symbols from changed lines (added
+ *   AND removed — a deleted symbol makes docs stale too), scanned anywhere in a doc.
+ * - `soft` — all-lowercase symbols (`cusum`); indistinguishable from English words in
+ *   prose, so they are scanned only inside backtick code spans.
+ * - `disappeared` — symbols present in removed lines but absent from added ones: their
+ *   mentions are stale EVEN in a doc that was touched in the same diff (the rename
+ *   case — a doc updated for one reason can still describe a symbol that no longer
+ *   exists).
  */
 export function changedIdentifiers(root, { base = "HEAD" } = {}) {
   const diff =
     git(root, ["diff", "--unified=0", base]) || git(root, ["diff", "--unified=0", "--cached"]);
   const perFile = new Map();
+  const ensure = (rel) => {
+    if (!perFile.has(rel)) perFile.set(rel, { added: [], removed: [] });
+    return perFile.get(rel);
+  };
   let current = null;
   for (const line of diff.split("\n")) {
     const header = /^\+\+\+ b\/(.*)$/.exec(line);
     if (header) {
       current = header[1] === "/dev/null" ? null : header[1];
-      if (current && !perFile.has(current)) perFile.set(current, []);
+      if (current) ensure(current);
       continue;
     }
     const gone = /^--- a\/(.*)$/.exec(line);
-    if (gone && gone[1] !== "/dev/null" && !perFile.has(gone[1])) perFile.set(gone[1], []);
+    if (gone && gone[1] !== "/dev/null") ensure(gone[1]);
     if (!current) continue;
-    if (
-      (line.startsWith("+") && !line.startsWith("+++")) ||
-      (line.startsWith("-") && !line.startsWith("---"))
-    )
-      perFile.get(current).push(line.slice(1));
+    if (line.startsWith("+") && !line.startsWith("+++")) ensure(current).added.push(line.slice(1));
+    else if (line.startsWith("-") && !line.startsWith("---"))
+      ensure(current).removed.push(line.slice(1));
   }
   for (const f of git(root, ["ls-files", "--others", "--exclude-standard"])
     .split("\n")
@@ -72,41 +80,59 @@ export function changedIdentifiers(root, { base = "HEAD" } = {}) {
       try {
         text = readFileSync(join(root, f), "utf8");
       } catch {}
-      perFile.set(f, text.split("\n")); // a brand-new file: every line is a changed line
+      perFile.set(f, { added: text.split("\n"), removed: [] }); // brand-new file: every line added
     }
   }
+  // Precision rules (dogfooding + adversarial review found them): symbols come ONLY
+  // from code-class files — prose parentheses in a changed .md line are not call
+  // sites — and never from test files (docs don't document test internals).
+  const codeShaped = (s) => /[A-Z0-9_./\\-]/.test(s);
   const identifiers = new Set();
   const changedFiles = [...perFile.keys()].sort();
-  // Precision rules (dogfooding found them): symbols come ONLY from code-class files —
-  // prose parentheses in a changed .md line are not call sites — and never from test
-  // files (docs don't document test internals). A plain lowercase English word that
-  // happens to be a variable (`status`, `body`) would flag every doc that uses the
-  // word, so only code-shaped names (case transition, digit, _ . / -) are scanned.
-  const codeShaped = (s) => /[A-Z0-9_./\\-]/.test(s);
-  for (const [rel, lines] of perFile) {
+  const addedSyms = new Set();
+  const removedSyms = new Set();
+  const collect = (rel, text, bucket) => {
+    for (const s of extractCalledSymbols(text)) if (s.length >= 3) bucket.add(s);
+    for (const d of definedNames(rel, text))
+      if (d.length >= 3 && !CALL_IGNORE.has(d)) bucket.add(d);
+  };
+  for (const [rel, { added, removed }] of perFile) {
     identifiers.add(rel);
     if (!RULES[extname(rel)] || isTestFile(rel)) continue;
-    const text = lines.join("\n");
-    for (const s of extractCalledSymbols(text))
-      if (s.length >= 3 && codeShaped(s)) identifiers.add(s);
-    for (const d of definedNames(rel, text))
-      if (d.length >= 3 && !CALL_IGNORE.has(d) && codeShaped(d)) identifiers.add(d);
+    collect(rel, added.join("\n"), addedSyms);
+    collect(rel, removed.join("\n"), removedSyms);
   }
-  return { base, changedFiles, identifiers: [...identifiers].sort() };
+  const soft = new Set();
+  for (const s of new Set([...addedSyms, ...removedSyms])) {
+    if (codeShaped(s)) identifiers.add(s);
+    else if (s.length >= 4) soft.add(s);
+  }
+  const disappeared = [...removedSyms]
+    .filter((s) => !addedSyms.has(s) && (codeShaped(s) || s.length >= 4))
+    .sort();
+  return {
+    base,
+    changedFiles,
+    identifiers: [...identifiers].sort(),
+    soft: [...soft].sort(),
+    disappeared,
+  };
 }
 
 // CHANGELOG and the decisions log are append-only HISTORY — their mentions of changed
 // identifiers are correct-by-design (same reasoning as the atlas DOC_SKIP set).
 const HISTORY_RE = /(^|[/\\])CHANGELOG\.md$/i;
 
-/** Every doc artifact the sweep owes an answer for: atlas doc nodes + the contract docs
- *  + the session-state snapshot (when they exist). */
+/** Every doc artifact the sweep owes an answer for: atlas doc nodes + the contract
+ *  docs. The state snapshot (.forge/state.md) is deliberately NOT scanned: handoff
+ *  writes the changed-file list into it by design, so scanning it flags the sweep's
+ *  own bookkeeping as stale — an unfixable self-reference (review-found). The gate's
+ *  mtime check covers state; the sweep covers prose. */
 export function docSet(root, atlas = loadAtlas(root)) {
   const docs = new Set();
   for (const n of atlas?.nodes || []) if (n.kind === "doc" && n.file) docs.add(n.file);
   for (const d of ["README.md", join("docs", "GUIDE.md"), "ARCHITECTURE.md"])
     if (existsSync(join(root, d))) docs.add(d);
-  if (existsSync(statePath(root))) docs.add(join(".forge", "state.md"));
   return [...docs].filter((f) => !HISTORY_RE.test(f)).sort();
 }
 
@@ -137,45 +163,80 @@ const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
  * @param {{base?: string, atlas?: object|null, maxHitsPerDoc?: number}} [opts]
  */
 export function docsSyncReport(root, { base, atlas, maxHitsPerDoc = 20 } = {}) {
+  // An explicit but unknown ref must ERROR, not silently fall back to the index and
+  // mislabel the report (review-found: a typo yielded a wrong-but-plausible sweep).
+  if (base && !git(root, ["rev-parse", "--verify", `${base}^{commit}`]).trim())
+    return {
+      base,
+      error: `unknown base ref: ${base}`,
+      changedFiles: [],
+      identifiers: [],
+      soft: [],
+      disappeared: [],
+      updated: [],
+      stale: [],
+      unaffected: [],
+    };
   const resolvedBase = base || newestBaseline(root) || "HEAD";
-  const { changedFiles, identifiers } = changedIdentifiers(root, { base: resolvedBase });
+  const { changedFiles, identifiers, soft, disappeared } = changedIdentifiers(root, {
+    base: resolvedBase,
+  });
   const docs = docSet(root, atlas === undefined ? loadAtlas(root) : atlas);
   const report = {
     base: resolvedBase,
     changedFiles,
     identifiers,
+    soft,
+    disappeared,
     updated: [],
     stale: [],
     unaffected: [],
   };
-  if (!identifiers.length) return report;
-  const scanRe = new RegExp(`(?:^|[^\\w$/.-])(${identifiers.map(esc).join("|")})(?![\\w$])`, "g");
-  for (const doc of docs) {
-    if (changedFiles.includes(doc)) {
-      report.updated.push({ file: doc, reason: "changed in this diff" });
-      continue;
+  if (!identifiers.length && !soft.length) return report;
+  const bound = (ids) => `(?:^|[^\\w$/.-])(${ids.map(esc).join("|")})(?![\\w$])`;
+  const generalRe = identifiers.length ? new RegExp(bound(identifiers), "g") : null;
+  // Lowercase symbols only count inside backticks — `cusum` in a code span is a code
+  // reference; "status" in running prose is English.
+  const softRe = soft.length ? new RegExp(`\`(${soft.map(esc).join("|")})\``, "g") : null;
+  const goneRe = disappeared.length ? new RegExp(bound(disappeared), "g") : null;
+  const scan = (lines, regexes, self) => {
+    const hits = [];
+    for (let i = 0; i < lines.length && hits.length < maxHitsPerDoc; i += 1) {
+      for (const re of regexes) {
+        if (!re) continue;
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(lines[i])) && hits.length < maxHitsPerDoc) {
+          if (m[1] === self) continue; // a doc naming itself is not staleness
+          hits.push({ identifier: m[1], line: i + 1, text: lines[i].trim().slice(0, 160) });
+        }
+      }
     }
+    return hits;
+  };
+  for (const doc of docs) {
     let text;
     try {
       text = readFileSync(join(root, doc), "utf8");
     } catch {
       continue;
     }
-    const hits = [];
     const lines = text.split("\n");
-    for (let i = 0; i < lines.length && hits.length < maxHitsPerDoc; i += 1) {
-      scanRe.lastIndex = 0;
-      let m;
-      while ((m = scanRe.exec(lines[i])) && hits.length < maxHitsPerDoc) {
-        if (m[1] === doc) continue; // a doc naming itself is not staleness
-        hits.push({ identifier: m[1], line: i + 1, text: lines[i].trim().slice(0, 160) });
-      }
+    if (changedFiles.includes(doc)) {
+      // Touched docs still owe an answer for REMOVED symbols: updated-for-one-reason
+      // does not mean updated-for-the-rename.
+      const hits = scan(lines, [goneRe], doc);
+      if (hits.length)
+        report.stale.push({ file: doc, hits, note: "touched, but still mentions REMOVED symbols" });
+      else report.updated.push({ file: doc, reason: "changed in this diff" });
+      continue;
     }
+    const hits = scan(lines, [generalRe, softRe], doc);
     if (hits.length) report.stale.push({ file: doc, hits });
     else
       report.unaffected.push({
         file: doc,
-        reason: `mentions none of the ${identifiers.length} changed identifiers`,
+        reason: `mentions none of the ${identifiers.length + soft.length} changed identifiers`,
       });
   }
   return report;
@@ -183,8 +244,9 @@ export function docsSyncReport(root, { base, atlas, maxHitsPerDoc = 20 } = {}) {
 
 /** Human rendering — one line per artifact, hits cited as file:line. */
 export function renderDocsSync(report) {
+  if (report.error) return `docs sync — ${report.error}`;
   const out = [
-    `docs sync — diff vs ${report.base}: ${report.changedFiles.length} changed file(s), ${report.identifiers.length} identifier(s)`,
+    `docs sync — diff vs ${report.base}: ${report.changedFiles.length} changed file(s), ${report.identifiers.length + (report.soft?.length ?? 0)} identifier(s)`,
   ];
   if (!report.changedFiles.length) {
     out.push("  clean — nothing changed, nothing owed.");
@@ -192,7 +254,7 @@ export function renderDocsSync(report) {
   }
   for (const u of report.updated) out.push(`  UPDATED     ${u.file} (${u.reason})`);
   for (const s of report.stale) {
-    out.push(`  STALE       ${s.file} — mentions changed identifiers:`);
+    out.push(`  STALE       ${s.file} — ${s.note ?? "mentions changed identifiers"}:`);
     for (const h of s.hits.slice(0, 5))
       out.push(`                ${s.file}:${h.line}  \`${h.identifier}\` — ${h.text}`);
     if (s.hits.length > 5) out.push(`                (+${s.hits.length - 5} more hits)`);
diff --git a/src/gate.js b/src/gate.js
index 6fad7bb..2f14e66 100644
--- a/src/gate.js
+++ b/src/gate.js
@@ -21,8 +21,9 @@ import { BRAND } from "./brand.js";
 import { readSession, sessionPath } from "./cortex_hook.js";
 import { decisionsPath } from "./decide.js";
 import { statePath } from "./handoff.js";
-import { readBaseline } from "./session.js";
+import { readBaseline, readDirtySnapshot } from "./session.js";
 import { isTestFile } from "./substrate.js";
+import { IGNORE_DIRS } from "./util.js";
 
 // gitRaw keeps the exact bytes — porcelain's first column is a SPACE for unstaged
 // entries, and a trim() would eat it and shift the path slice by one.
@@ -59,20 +60,62 @@ export function classifyPath(rel) {
   return "other";
 }
 
-/** Everything changed this session: diff against the recorded baseline ∪ the working
- *  tree (staged + unstaged + untracked file-by-file, renames as both paths). */
-export function changedSet(root, baseHead) {
-  const out = new Set();
-  if (baseHead && git(root, ["rev-parse", "--verify", `${baseHead}^{commit}`]))
-    for (const f of git(root, ["diff", "--name-only", baseHead]).split("\n").filter(Boolean))
-      out.add(f);
-  for (const line of gitRaw(root, ["status", "--porcelain", "-uall"]).split("\n").filter(Boolean)) {
-    for (const part of line.slice(3).split(" -> ")) {
-      const p = part.replace(/^"(.*)"$/, "$1").trim();
-      if (p) out.add(p);
-    }
+// All -z (NUL-separated) parsing: git's C-quoting of unicode/space/quote paths never
+// reaches us, so `Änderungen.md` classifies as docs instead of `other` (a review-found
+// false block) and a file literally named `plan -> v2.md` can't be split in two.
+function statusEntriesZ(root) {
+  const raw = gitRaw(root, ["status", "--porcelain", "-z", "-uall"]);
+  const tokens = raw.split("\0").filter(Boolean);
+  const paths = [];
+  for (let i = 0; i < tokens.length; i += 1) {
+    const t = tokens[i];
+    if (t.length < 4 || t[2] !== " ") continue;
+    paths.push(t.slice(3));
+    if (/[RC]/.test(t[0])) paths.push(tokens[++i] ?? ""); // rename/copy: next token is the source
+  }
+  return paths.filter(Boolean);
+}
+
+// Files committed DURING the session: commits in base..HEAD whose committer time is at
+// or after session start. A branch switch or `git pull` moves HEAD onto commits made
+// long before the session — a plain baseline diff would attribute all of them to the
+// agent (review-found false block). Merge commits list no files (correct: the merged
+// work predates the session); the 2s slack absorbs clock granularity.
+function committedSince(root, baseHead, sinceMs) {
+  if (!baseHead || !git(root, ["rev-parse", "--verify", `${baseHead}^{commit}`])) return [];
+  const since = new Date(Math.max(0, (sinceMs ?? 0) - 2000)).toISOString();
+  const raw = gitRaw(root, [
+    "log",
+    "--name-only",
+    "-z",
+    "--pretty=format:",
+    `--since=${since}`,
+    `${baseHead}..HEAD`,
+  ]);
+  return raw
+    .split("\0")
+    .flatMap((chunk) => chunk.split("\n"))
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+// Vendor/build trees that are somehow not gitignored must never be pinned on the agent.
+const IGNORED_PREFIX = (p) => IGNORE_DIRS.has(String(p).split("/")[0]);
+
+/**
+ * Everything attributable to THIS session: files from session-time commits ∪ the
+ * working tree minus whatever was already dirty at session start. Pre-existing dirt,
+ * pulled-in commits, and vendor trees stay out — near-zero false blocks is the gate's
+ * credibility. Degraded mode (no baseline/snapshot): the full worktree, still bounded
+ * by the block-once marker.
+ */
+export function changedSet(root, baseHead, { sinceMs, preDirty } = {}) {
+  const out = new Set(committedSince(root, baseHead, sinceMs));
+  for (const p of statusEntriesZ(root)) {
+    if (preDirty?.has(p)) continue; // already dirty before the session began
+    out.add(p);
   }
-  return [...out].sort();
+  return [...out].filter((p) => !IGNORED_PREFIX(p)).sort();
 }
 
 /**
@@ -146,6 +189,9 @@ export function stopGate(root, sid, hook = {}) {
   try {
     if (hook.stop_hook_active === true || hook.stop_hook_active === "true")
       return { allow: true, row: "stop-hook-active" };
+    // No session identity → no per-session marker/baseline is trustworthy; a shared
+    // "default" would leak one session's block/allow into every other (review-found).
+    if (!hook.session_id) return { allow: true, row: "no-session" };
     if (process.env.FORGE_STOPGATE === "0") return { allow: true, row: "kill-switch" };
     if (git(root, ["rev-parse", "--is-inside-work-tree"]) !== "true")
       return { allow: true, row: "not-a-repo" };
@@ -170,9 +216,21 @@ export function stopGate(root, sid, hook = {}) {
           return false;
         }
       });
-    const changed = changedSet(root, base?.head);
+    const changed = changedSet(root, base?.head, {
+      sinceMs: startedAt ?? undefined,
+      preDirty: readDirtySnapshot(root, sid) ?? undefined,
+    });
     const decision = gateDecision({ changed, stateTouched });
     if (decision.allow) return decision;
+    // Marker FIRST: if it can't be persisted, the block-once promise can't be kept —
+    // on a read-only checkout that would mean an unsatisfiable block every turn, so
+    // the honest move is to stand down (fail-open, review-found).
+    try {
+      mkdirSync(join(root, ".forge", "sessions"), { recursive: true });
+      writeFileSync(marker, `${new Date().toISOString()}\n`);
+    } catch {
+      return { allow: true, row: "marker-unwritable" };
+    }
     let driftAlarm = false;
     try {
       const scores = readSession(root, sid)
@@ -182,10 +240,6 @@ export function stopGate(root, sid, hook = {}) {
       if (scores.length >= 3) driftAlarm = cusum(scores).alarm;
     } catch {}
     const reason = repairReason(root, { codeFiles: decision.classes.code, driftAlarm });
-    try {
-      mkdirSync(join(root, ".forge", "sessions"), { recursive: true });
-      writeFileSync(marker, `${new Date().toISOString()}\n`);
-    } catch {}
     return { allow: false, row: decision.row, reason, classes: decision.classes };
   } catch {
     return { allow: true, row: "internal-error" };
diff --git a/src/handoff.js b/src/handoff.js
index 559a309..4acb7ba 100644
--- a/src/handoff.js
+++ b/src/handoff.js
@@ -39,9 +39,11 @@ export function gatherGitFacts(root, { statusCap = 20 } = {}) {
 }
 
 /** Assumption events recorded this session (preflight appends them when it proceeds
- *  without asking) — surfaced here so the handoff carries what was GUESSED, not
- *  just what was done. Empty-safe when no session log exists. */
-export function gatherAssumptions(root) {
+ *  without asking) — surfaced here so the handoff carries what was GUESSED, not just
+ *  what was done. Deduped by content and capped: a constraint missing on every prompt
+ *  appends one event per prompt, and 30 identical rows would eat the bounded snapshot.
+ *  Empty-safe when no session log exists. */
+export function gatherAssumptions(root, { cap = 5 } = {}) {
   try {
     const dir = join(root, ".forge", "sessions");
     const newest = readdirSync(dir)
@@ -49,15 +51,20 @@ export function gatherAssumptions(root) {
       .map((f) => ({ f, m: statSync(join(dir, f)).mtimeMs }))
       .sort((a, b) => b.m - a.m)[0];
     if (!newest) return [];
+    const seen = new Set();
     const out = [];
     for (const line of readFileSync(join(dir, newest.f), "utf8").split("\n")) {
       if (!line.trim()) continue;
       try {
         const e = JSON.parse(line);
-        if (e.type === "assumption") out.push(e);
+        if (e.type !== "assumption") continue;
+        const key = JSON.stringify([e.missing ?? [], e.questions ?? []]);
+        if (seen.has(key)) continue;
+        seen.add(key);
+        out.push(e);
       } catch {}
     }
-    return out;
+    return out.slice(0, cap);
   } catch {
     return [];
   }
@@ -129,14 +136,21 @@ export function writeState(root, fields = {}, { t = Date.now(), maxLines = 150 }
   return { ok: true, path: statePath(root), lines: kept.length + 1 };
 }
 
+// Only the EXACT provenance line is stripped — a naive slice at the first "<!--" would
+// silently truncate a snapshot whose rows mention HTML comments ("strip <!-- markers
+// from templates"), losing every later section from the next session's injection.
+const PROVENANCE_RE = /^<!-- written .* -->\s*$/;
+
 /** The snapshot text minus provenance, or null when none exists. */
 export function readState(root) {
   const p = statePath(root);
   if (!existsSync(p)) return null;
   try {
-    const raw = readFileSync(p, "utf8");
-    const cut = raw.indexOf("<!--");
-    const text = (cut === -1 ? raw : raw.slice(0, cut)).trim();
+    const text = readFileSync(p, "utf8")
+      .split("\n")
+      .filter((l) => !PROVENANCE_RE.test(l))
+      .join("\n")
+      .trim();
     return text || null;
   } catch {
     return null;
diff --git a/src/session.js b/src/session.js
index 4efb541..030cedb 100644
--- a/src/session.js
+++ b/src/session.js
@@ -29,11 +29,43 @@ function git(root, args) {
   }
 }
 
+// Raw NUL-separated porcelain — the ONLY quote-proof status format (paths with
+// spaces/unicode/quotes arrive verbatim, no C-quoting to undo).
+function statusPathsZ(root) {
+  try {
+    const raw = execFileSync("git", ["status", "--porcelain", "-z", "-uall"], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const tokens = raw.split("\0").filter(Boolean);
+    const paths = [];
+    for (let i = 0; i < tokens.length; i += 1) {
+      const t = tokens[i];
+      if (t.length < 4 || t[2] !== " ") continue; // defensive: not an "XY path" entry
+      paths.push(t.slice(3));
+      if (/[RC]/.test(t[0])) paths.push(tokens[++i] ?? ""); // rename/copy: next token is the source path
+    }
+    return paths.filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
 /** Record HEAD as this session's baseline — once. An existing file wins (a --resume
- *  re-fires SessionStart and must NOT move the anchor mid-session). */
+ *  re-fires SessionStart and must NOT move the anchor mid-session). Also snapshots the
+ *  files ALREADY dirty at session start (even on an unborn HEAD), so the completion
+ *  gate never attributes pre-existing dirt to this session. */
 export function recordBaseline(root, sid) {
   const head = git(root, ["rev-parse", "HEAD"]);
-  if (!head) return { recorded: false, head: null }; // not a repo (or unborn HEAD) → nothing to anchor
+  const dirtyPath = sessionPath(root, sid, "dirty");
+  try {
+    if (git(root, ["rev-parse", "--is-inside-work-tree"]) === "true" && !existsSync(dirtyPath)) {
+      mkdirSync(join(root, ".forge", "sessions"), { recursive: true });
+      writeFileSync(dirtyPath, `${statusPathsZ(root).join("\n")}\n`);
+    }
+  } catch {}
+  if (!head) return { recorded: false, head: null }; // unborn HEAD → dirty snapshot only
   const p = sessionPath(root, sid, "base");
   try {
     if (existsSync(p)) return { recorded: false, head: readFileSync(p, "utf8").trim() };
@@ -45,6 +77,18 @@ export function recordBaseline(root, sid) {
   }
 }
 
+/** The set of paths that were already dirty when the session started (empty when the
+ *  snapshot is missing — degraded mode, gate errs toward its other guards). */
+export function readDirtySnapshot(root, sid) {
+  try {
+    const p = sessionPath(root, sid, "dirty");
+    if (!existsSync(p)) return null;
+    return new Set(readFileSync(p, "utf8").split("\n").filter(Boolean));
+  } catch {
+    return null;
+  }
+}
+
 /** The session's anchor: baseline sha + the file's mtime (= when the session started —
  *  the completion gate compares state.md's mtime against it). Null when never recorded. */
 export function readBaseline(root, sid) {
diff --git a/test/decide.test.js b/test/decide.test.js
index 7fc13b7..621b77e 100644
--- a/test/decide.test.js
+++ b/test/decide.test.js
@@ -61,3 +61,27 @@ test("a corrupted decisions file is tolerated — numbering restarts from parsea
   const parsed = parseDecisions(readFileSync(decisionsPath(root), "utf8"));
   assert.equal(parsed.length, 2, "garbage ignored, both real entries parse");
 });
+
+test("concurrent appends never duplicate ids or headers (mkdir lock)", async () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-decide-"));
+  const { spawn } = await import("node:child_process");
+  const one = (i) =>
+    new Promise((resolve) => {
+      const p = spawn(
+        "node",
+        [
+          "-e",
+          `import("${process.cwd()}/src/decide.js").then(m => m.appendDecision(process.argv[1], "parallel decision ${"n"}${i} — race test"))`,
+          root,
+        ],
+        { stdio: "ignore" },
+      );
+      p.on("exit", resolve);
+    });
+  await Promise.all(Array.from({ length: 8 }, (_, i) => one(i)));
+  const text = readFileSync(decisionsPath(root), "utf8");
+  const ids = [...text.matchAll(/\*\*D-(\d{4,})\*\*/g)].map((m) => m[1]);
+  assert.equal(ids.length, 8, `all 8 decisions written: ${text}`);
+  assert.equal(new Set(ids).size, 8, `ids unique: ${ids.join(",")}`);
+  assert.equal((text.match(/# Decisions/g) || []).length, 1, "exactly one header");
+});
diff --git a/test/docs_sync.test.js b/test/docs_sync.test.js
index b670cb0..68da079 100644
--- a/test/docs_sync.test.js
+++ b/test/docs_sync.test.js
@@ -84,18 +84,75 @@ test("a doc edited in the same diff reports UPDATED, not STALE", () => {
   assert.ok(!r.stale.some((s) => s.file === "README.md"));
 });
 
-test("docSet includes the state snapshot when present; non-git root yields a clean report", () => {
+test("docSet EXCLUDES the state snapshot (machine-written bookkeeping, not prose); non-git root yields a clean report", () => {
   const { root } = gitFixture();
   mkdirSync(join(root, ".forge"), { recursive: true });
-  writeFileSync(join(root, ".forge", "state.md"), "# Session state\n\nmentions src/val.js\n");
+  // handoff writes the changed-file list into state.md BY DESIGN — scanning it would
+  // flag the sweep's own bookkeeping as stale, an unfixable self-reference.
+  writeFileSync(join(root, ".forge", "state.md"), "# Session state\n\n- M src/val.js\n");
   build({ root });
-  assert.ok(docSet(root).includes(join(".forge", "state.md")));
+  assert.ok(!docSet(root).includes(join(".forge", "state.md")));
+  writeFileSync(join(root, "src", "val.js"), "export function validateOrderX(x){ return !!x }\n");
+  const r0 = docsSyncReport(root, { base: "HEAD" });
+  assert.ok(
+    !r0.stale.some((s) => s.file.includes("state.md")),
+    "state snapshot never reported stale",
+  );
   const bare = mkdtempSync(join(tmpdir(), "forge-docsync-"));
   const r = docsSyncReport(bare);
   assert.deepEqual(r.changedFiles, []);
   assert.deepEqual(r.stale, []);
 });
 
+test("a renamed symbol stays STALE in a doc that was touched for another reason", () => {
+  const { root, commit } = gitFixture();
+  build({ root });
+  commit("atlas");
+  // Rename validateOrder → checkOrder, and touch README's intro WITHOUT fixing the mention.
+  writeFileSync(join(root, "src", "val.js"), "export function checkOrder(x){ return !!x }\n");
+  writeFileSync(
+    join(root, "README.md"),
+    "# app (new tagline)\n\nUse `validateOrder` from `src/val.js` to check orders.\n",
+  );
+  const r = docsSyncReport(root, { base: "HEAD" });
+  const stale = r.stale.find((s) => s.file === "README.md");
+  assert.ok(stale, `touched README still flagged: ${JSON.stringify(r)}`);
+  assert.ok(stale.hits.some((h) => h.identifier === "validateOrder"));
+  assert.match(stale.note, /REMOVED/, "the reason names the removed-symbol case");
+});
+
+test("lowercase symbols scan only inside backticks (code span = code reference)", () => {
+  const { root, commit } = gitFixture();
+  writeFileSync(join(root, "MATHDOC.md"), "# math\n\nThe `cusum` detector accumulates drift.\n");
+  writeFileSync(
+    join(root, "PROSE.md"),
+    "# prose\n\nWe check the cusum of the queue in plain words here.\n",
+  );
+  commit("docs");
+  build({ root });
+  commit("atlas");
+  writeFileSync(join(root, "src", "val.js"), "export function cusum(s){ return s.length }\n");
+  const r = docsSyncReport(root, { base: "HEAD" });
+  assert.ok(r.soft.includes("cusum"), `cusum is a soft identifier: ${JSON.stringify(r.soft)}`);
+  assert.ok(
+    r.stale.some((s) => s.file === "MATHDOC.md"),
+    "backticked mention flags",
+  );
+  assert.ok(!r.stale.some((s) => s.file === "PROSE.md"), "plain-prose word does not flag");
+});
+
+test("an unknown explicit --base errors instead of silently mislabeling", () => {
+  const { root } = gitFixture();
+  const r = docsSyncReport(root, { base: "totally-bogus-ref" });
+  assert.match(r.error, /unknown base ref/);
+  const cli = spawnSync("node", [CLI, "docs", "sync", "--base", "totally-bogus-ref"], {
+    cwd: root,
+    encoding: "utf8",
+  });
+  assert.equal(cli.status, 1, "CLI exits 1 on a bad ref");
+  assert.match(cli.stdout, /unknown base ref/);
+});
+
 test("CLI: docs sync --json reports; --strict exits 1 only when stale docs exist", () => {
   const { root, commit } = gitFixture();
   build({ root });
diff --git a/test/handoff.test.js b/test/handoff.test.js
index f646662..8b4b45d 100644
--- a/test/handoff.test.js
+++ b/test/handoff.test.js
@@ -93,3 +93,29 @@ test("writeState surfaces recorded assumption events from the newest session log
   const text = readFileSync(statePath(root), "utf8");
   assert.match(text, /target_scope/, "assumption keys carried into the handoff");
 });
+
+test("a row containing '<!--' never truncates the snapshot (only provenance is stripped)", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-handoff-"));
+  writeState(root, {
+    done: ["strip <!-- markers from templates before render"],
+    next: ["CRITICAL: fix auth bypass in login.js"],
+    gotchas: ["templating chokes on <!-- comments"],
+  });
+  const text = readState(root);
+  assert.match(text, /CRITICAL: fix auth bypass/, "later sections survive an inline <!--");
+  assert.match(text, /templating chokes/, "gotchas survive too");
+  assert.doesNotMatch(text, /written .*handoff/, "the provenance line itself is stripped");
+  const block = stateBlock(root);
+  assert.match(block, /CRITICAL: fix auth bypass/, "the injection carries the full snapshot");
+});
+
+test("gatherAssumptions dedupes identical events and caps the list", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-handoff-"));
+  mkdirSync(join(root, ".forge", "sessions"), { recursive: true });
+  const line = `${JSON.stringify({ type: "assumption", missing: ["test-command"] })}\n`;
+  writeFileSync(join(root, ".forge", "sessions", "s1.jsonl"), line.repeat(30));
+  writeState(root, { done: ["x"] });
+  const text = readFileSync(statePath(root), "utf8");
+  const count = (text.match(/test-command/g) || []).length;
+  assert.equal(count, 1, "30 identical events collapse to one row");
+});
diff --git a/test/session.test.js b/test/session.test.js
index e4391b4..c3edab1 100644
--- a/test/session.test.js
+++ b/test/session.test.js
@@ -1,11 +1,17 @@
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, mkdtempSync, utimesSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, statSync, utimesSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { test } from "node:test";
 import { sessionPath } from "../src/cortex_hook.js";
-import { pruneSessions, readBaseline, recordBaseline, rehydrationBlock } from "../src/session.js";
+import {
+  pruneSessions,
+  readBaseline,
+  readDirtySnapshot,
+  recordBaseline,
+  rehydrationBlock,
+} from "../src/session.js";
 
 function gitFixture() {
   const root = mkdtempSync(join(tmpdir(), "forge-session-"));
@@ -75,3 +81,29 @@ test("rehydrationBlock caps the dirty list with an overflow pointer", () => {
   assert.match(block, /\(\+20 more\)/, "overflow counted, not silently dropped");
   git("add", "-A"); // keep fixture dir reusable; not asserted
 });
+
+test("recordBaseline snapshots pre-session dirt (even before the anchor exists)", () => {
+  const { root } = gitFixture();
+  writeFileSync(join(root, "dirty_before.js"), "export const pre = 1;\n");
+  recordBaseline(root, "d1");
+  const snap = readDirtySnapshot(root, "d1");
+  assert.ok(snap.has("dirty_before.js"), "pre-existing dirt captured at session start");
+  // A resume never rewrites the snapshot either.
+  writeFileSync(join(root, "later.js"), "export const post = 1;\n");
+  recordBaseline(root, "d1");
+  assert.ok(!readDirtySnapshot(root, "d1").has("later.js"), "resume keeps the original snapshot");
+});
+
+test("a >7-day-old session re-anchors instead of losing its baseline (prune-then-record)", () => {
+  const { root } = gitFixture();
+  recordBaseline(root, "old1");
+  const base = sessionPath(root, "old1", "base");
+  const past = (Date.now() - 8 * 86_400_000) / 1000;
+  utimesSync(base, past, past);
+  // The session-start order: prune first, THEN record — the stale anchor is replaced,
+  // never silently deleted after being "preserved".
+  pruneSessions(root);
+  recordBaseline(root, "old1");
+  assert.ok(existsSync(base), "baseline exists after the aged resume");
+  assert.ok(Date.now() - statSync(base).mtimeMs < 60_000, "and it is a FRESH anchor");
+});
diff --git a/test/stop_gate.test.js b/test/stop_gate.test.js
index 3b83100..fdf80d2 100644
--- a/test/stop_gate.test.js
+++ b/test/stop_gate.test.js
@@ -130,3 +130,71 @@ test("both hook manifests register the completion gate under Stop (lockstep)", (
   assert.match(flat(plugin), /completion-gate\.sh/, "plugin manifest wires the gate");
   assert.match(flat(template), /completion-gate\.sh/, "init template wires the gate");
 });
+
+test("pre-session dirt is never pinned on the session (review: false-block class)", () => {
+  const { root } = gitFixture();
+  writeFileSync(join(root, "a.js"), "export const one = 99;\n"); // dirty BEFORE the session
+  start(root, "pre1");
+  const r = stopGate(root, "pre1"); // session itself did nothing
+  assert.equal(r.stdout.trim(), "", "no-op session over a dirty repo passes");
+  // But the same session then editing another code file DOES get gated.
+  writeFileSync(join(root, "b.js"), "export const two = 2;\n");
+  const blocked = stopGate(root, "pre1");
+  assert.equal(JSON.parse(blocked.stdout).decision, "block");
+  assert.match(JSON.parse(blocked.stdout).reason, /b\.js/);
+  assert.doesNotMatch(JSON.parse(blocked.stdout).reason, /a\.js/, "pre-existing dirt not cited");
+});
+
+test("a branch switch's old commits are not attributed to the session", () => {
+  const { root, git } = gitFixture();
+  // A feature branch whose commit is an hour old (committer date aged explicitly).
+  git("checkout", "-q", "-b", "feature");
+  writeFileSync(join(root, "old_work.js"), "export const legacy = 1;\n");
+  git("add", "-A");
+  execFileSync("git", ["-c", "commit.gpgsign=false", "commit", "-qm", "old feature work"], {
+    cwd: root,
+    stdio: ["ignore", "pipe", "pipe"],
+    env: {
+      ...process.env,
+      GIT_COMMITTER_DATE: new Date(Date.now() - 3_600_000).toISOString(),
+      GIT_AUTHOR_DATE: new Date(Date.now() - 3_600_000).toISOString(),
+    },
+  });
+  git("checkout", "-q", "master");
+  start(root, "sw1"); // session starts on master
+  git("checkout", "-q", "feature"); // the session merely switches branches
+  const r = stopGate(root, "sw1");
+  assert.equal(r.stdout.trim(), "", "hour-old commits reached by checkout are not the session's");
+});
+
+test("unicode/space doc paths keep their doc credit (-z parsing)", () => {
+  const { root, git } = gitFixture();
+  start(root, "uni1");
+  writeFileSync(join(root, "a.js"), "export const one = 42;\n");
+  writeFileSync(join(root, "Änderungen notes.md"), "# änderungen\n\ndocumented the change\n");
+  git("add", "-A");
+  git("-c", "commit.gpgsign=false", "commit", "-qm", "code + unicode doc");
+  const r = stopGate(root, "uni1");
+  assert.equal(r.stdout.trim(), "", "the unicode-named doc satisfies the gate");
+});
+
+test("missing session_id disables gating (no shared 'default' state)", () => {
+  const { root } = gitFixture();
+  writeFileSync(join(root, "a.js"), "export const one = 7;\n");
+  const r = spawnSync("node", [ENTRY, "stop-gate"], {
+    input: JSON.stringify({ cwd: root }), // no session_id
+    encoding: "utf8",
+  });
+  assert.equal(r.status, 0);
+  assert.equal(r.stdout.trim(), "", "unknown identity → no per-session promises → allow");
+});
+
+test("unwritable marker → stand down instead of blocking every turn", () => {
+  const { root } = gitFixture();
+  mkdirSync(join(root, ".forge"), { recursive: true });
+  writeFileSync(join(root, ".forge", "sessions"), "a file where a directory must be\n");
+  writeFileSync(join(root, "a.js"), "export const one = 8;\n");
+  const r = stopGate(root, "ro1");
+  assert.equal(r.status, 0);
+  assert.equal(r.stdout.trim(), "", "block-once cannot be promised → fail open");
+});

From e03ce5026bf695be44b504869ffe0a9342c89ef0 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 10 Jul 2026 09:49:57 +0000
Subject: [PATCH 11/12] fix(types): changedSet options need explicit JSDoc for
 tsc

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
---
 src/gate.js | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/gate.js b/src/gate.js
index 2f14e66..1b10f98 100644
--- a/src/gate.js
+++ b/src/gate.js
@@ -108,6 +108,9 @@ const IGNORED_PREFIX = (p) => IGNORE_DIRS.has(String(p).split("/")[0]);
  * pulled-in commits, and vendor trees stay out — near-zero false blocks is the gate's
  * credibility. Degraded mode (no baseline/snapshot): the full worktree, still bounded
  * by the block-once marker.
+ * @param {string} root
+ * @param {string|null} [baseHead]
+ * @param {{sinceMs?: number, preDirty?: Set<string>}} [opts]
  */
 export function changedSet(root, baseHead, { sinceMs, preDirty } = {}) {
   const out = new Set(committedSince(root, baseHead, sinceMs));

From 1fa7834dff3f071bc22de61c51cb3bef5369f89f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 10 Jul 2026 09:53:05 +0000
Subject: [PATCH 12/12] chore(changelog): keep unreleased work out of the
 v0.9.0 section after merge

The v0.9.0 rotation on master renamed the [Unreleased] header this branch's
entries sat under, so the textual merge filed unshipped work as released.
Moved this branch's Added/Fixed entries back under [Unreleased]; [0.9.0]
now lists exactly what the tag shipped.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
---
 CHANGELOG.md | 40 +++++++++++++++++++++-------------------
 1 file changed, 21 insertions(+), 19 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c76253a..534e7dd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,8 +6,6 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-## [0.9.0] - 2026-07-10
-
 ### Added
 - **The completion gate** — a synchronous Stop hook (`global/guards/completion-gate.sh`
   → `src/gate.js`) that blocks a session ONCE when code changed but no doc or state
@@ -46,6 +44,27 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   `doc-sync` crew agent that repairs stale docs in its own context, and an
   `end-to-end` rules section (Definition of Done, no silent assumptions, decision log)
   compiled into every tool by `forge sync`.
+
+### Fixed
+- **`cortex.sh` hook entry resolution in symlink installs** — `~/.forge/src/…` pointed
+  at the nonexistent `global/src/`, silently no-opping every cortex hook outside plugin
+  mode; the shim now resolves through the symlink (`pwd -P`), same as `secret-redact.sh`.
+- **Twelve defects found by a two-angle adversarial review of the new layer, all with
+  regression tests** — the gate no longer attributes pre-session dirt, branch-switch/pull
+  commits, or vendor trees to the session (session-scoped changed set: committer-time
+  window + SessionStart dirty snapshot); `-z` NUL parsing keeps unicode/space/arrow paths
+  correctly classified; an unwritable block-once marker stands down instead of blocking
+  every turn; a missing `session_id` disables gating instead of sharing `default` state;
+  a >7-day resume re-anchors instead of losing its baseline to the prune; `readState` no
+  longer truncates snapshots whose rows contain `<!--`; `forge decide` takes a lock so
+  concurrent appends can't mint duplicate D-#### ids; the docs sweep stopped scanning its
+  own bookkeeping (`.forge/state.md`), scans touched docs for REMOVED symbols (the rename
+  case), counts lowercase symbols only inside backticks, dedupes recorded assumptions,
+  and errors on an unknown `--base` instead of mislabeling the report.
+
+## [0.9.0] - 2026-07-10
+
+### Added
 - **Gateway environments work end to end** — `ANTHROPIC_AUTH_TOKEN` is recognized
   everywhere `ANTHROPIC_API_KEY` is; `ANTHROPIC_MODEL` / `FORGE_MODEL` pin one model
   (bypassing tier routing); a gateway-looking `ANTHROPIC_BASE_URL` auto-classifies as
@@ -85,23 +104,6 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **`providerStatus` probes `/health` on any custom base URL** and reports behavioral
   gateway evidence (a proxy that answers /health is a gateway, whatever its hostname).
 
-### Fixed
-- **`cortex.sh` hook entry resolution in symlink installs** — `~/.forge/src/…` pointed
-  at the nonexistent `global/src/`, silently no-opping every cortex hook outside plugin
-  mode; the shim now resolves through the symlink (`pwd -P`), same as `secret-redact.sh`.
-- **Twelve defects found by a two-angle adversarial review of the new layer, all with
-  regression tests** — the gate no longer attributes pre-session dirt, branch-switch/pull
-  commits, or vendor trees to the session (session-scoped changed set: committer-time
-  window + SessionStart dirty snapshot); `-z` NUL parsing keeps unicode/space/arrow paths
-  correctly classified; an unwritable block-once marker stands down instead of blocking
-  every turn; a missing `session_id` disables gating instead of sharing `default` state;
-  a >7-day resume re-anchors instead of losing its baseline to the prune; `readState` no
-  longer truncates snapshots whose rows contain `<!--`; `forge decide` takes a lock so
-  concurrent appends can't mint duplicate D-#### ids; the docs sweep stopped scanning its
-  own bookkeeping (`.forge/state.md`), scans touched docs for REMOVED symbols (the rename
-  case), counts lowercase symbols only inside backticks, dedupes recorded assumptions,
-  and errors on an unknown `--base` instead of mislabeling the report.
-
 ## [0.8.1] - 2026-07-08
 
 ### Added