refactor: phase 4 cleanups (M5 layering cycle, M12 architecture, cat-file guard)

- M5: applyPrimaryTool (repo_config.js) no longer dynamically imports the sync
  compiler; the sync runner is injected by cli.js (the orchestration layer),
  keeping the config-leaf module acyclic. syncFn is now required at runtime.
- M12: refresh ARCHITECTURE.md for the v0.20-v0.24 modules that were absent from
  the reference -- commit_gate (forge precommit), consensus (forge verify --deep),
  knowledge_router, deja, and docs_impact (forge docs impact).
- LOW: ledger_store.js git cat-file -e ref resolver passes `--` before the ref.

Full suite (1069 pass), typecheck, biome, and docs check all green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C7htTiesXKLvAUtv6ET2jz

Author: claude

ARCHITECTURE.md

@@ -299,6 +299,43 @@ 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.
 
+**Commit-boundary gate (`src/commit_gate.js`, `forge precommit`).** The commit rung of
+the gate lattice (turn ⊂ commit ⊂ PR): the Stop hook gates the turn and CI's `docs check`
+gates the PR, so this runs the SAME registry-derived completeness classifier
+(`classifyPath` from `gate.js`) plus `hasSecret` over staged added lines at the commit
+boundary — code staged without its doc/state artifact, or a staged secret, is caught
+while the fix is still one `git add` away. Each rung is an independent catch layer, so
+the silent-miss probability falls multiplicatively.
+
+**Deep verification (`src/consensus.js`, `forge verify --deep`).** Where plain `verify`
+asks one oracle (the tests) plus one heuristic, this runs a table of independent lenses
+and aggregates them with the same noisy-OR risk score `lessons.js` uses, behind a
+cross-family gate so correlated structural signals can't block alone. Deep `ok` is a
+conjunction: the core verifier must PASS **and** the lens consensus must not block; an
+unconfigured core can never yield `ok:true`. The score is a calibrated heuristic, not a
+proof.
+
+**Knowledge routing (`src/knowledge_router.js`).** The third routing leg beside `route.js`
+(model tiers) and `intent.js` (intent classes), using the same exemplar k-NN math: a fact
+is routed to its storage home (decisions vs. the ledger vs. …) tuned by adding example
+rows, never regexes. It is TOTAL by construction — a fact resembling nothing falls back to
+the ledger (whose decay semantics make an unsure placement safe), never "nowhere".
+
+**Anti-repetition memory (`src/deja.js`).** Closes the "why do I keep re-solving solved
+tasks" gap: a clean first-try success used to leave no durable trace (cortex only mints on
+correction). At Stop it mints one `summary` claim (a deterministic, secret-redacted gist),
+attaching a `test.run` confirm when the session's tests passed; `dejaLookup` then ranks
+prior summary/lesson/diagnosis claims for a new task with the same `retrieve()` (rel × rec
+× val) the ledger query uses. No new protocol — it reuses the shipped PCM machinery.
+
+**The documentation-impact graph (`src/docs_impact.js`, `forge docs impact`).** Where
+`docs check` reconciles fixed registries and `docs sync` scans a diff for identifiers,
+this answers "I changed X — which documented surfaces mention X and are now potentially
+stale?" via a data-driven `EXTRACTORS` registry (commands, flags, env vars, MCP tools,
+exported symbols, brand tokens, version, package.json fields) reused from `docs_check.js`,
+an inverted entity → `file:line` index over every doc surface, and a diff-scoped impact
+query ranked by confidence. Advisory by default; `--strict` exits non-zero for CI.
+
 **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.

CHANGELOG.md

@@ -48,6 +48,14 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Removed the dead `plugin` entry from `package.json` `files`, the vestigial
   `.gitlab-ci.yml`, and the dangling `@AGENTS.md` import in `CLAUDE.md`; fixed the
   off-palette Codex plugin `brandColor`.
+- **Broke a layering cycle in `repo_config.js`.** `applyPrimaryTool` no longer reaches
+  back into the sync compiler via a dynamic `import("./sync.js")`; the sync runner is now
+  injected by the caller (`cli.js`), keeping the config leaf acyclic.
+- `ledger_store.js`'s `git cat-file -e` ref resolver now passes `--` before the ref
+  (defense in depth against a ref that begins with `-`).
+- **Refreshed `ARCHITECTURE.md`** for the v0.20–v0.24 modules that were missing from the
+  reference: `commit_gate` (`forge precommit`), `consensus` (`forge verify --deep`),
+  `knowledge_router`, `deja`, and `docs_impact` (`forge docs impact`).
 
 ## [0.25.0] - 2026-07-20
 

src/cli.js

@@ -2439,7 +2439,12 @@ async function run(argv) {
         process.exitCode = 1;
         return;
       }
-      const r = await applyPrimaryTool(root, name);
+      // Inject the sync runner from here (the orchestration layer) so repo_config —
+      // a config-leaf module — no longer reaches back into the sync compiler.
+      const { sync } = await import("./sync.js");
+      const r = await applyPrimaryTool(root, name, {
+        syncFn: (r2) => sync({ targetRoot: r2 }),
+      });
       if (json) return console.log(JSON.stringify(r, null, 2));
       heading(`${BRAND.brand} tools — primary set\n`);
       console.log(`  primary tool   ${paint(r.primaryTool, "ok")}`);

src/ledger_store.js

@@ -55,7 +55,9 @@ const repoRootOf = (dir) => dirname(dirname(dir));
 // (and non-git repos) never spawn git.
 const gitResolver = (root) => (sha) => {
   try {
-    execFileSync("git", ["cat-file", "-e", sha], {
+    // `--` guards against a ref that begins with "-" being read as a flag (defense in
+    // depth; execFileSync already avoids the shell, and refs here are validated).
+    execFileSync("git", ["cat-file", "-e", "--", sha], {
       cwd: root,
       stdio: "ignore",
     });

src/repo_config.js

@@ -311,20 +311,23 @@ export function nonPrimaryTargets(report, primary) {
 
 /**
  * Set `name` as the repo's primary tool and gitignore every other tool's emitted
- * artifacts. Runs a real sync to learn the emit targets (injectable via `syncFn` for
- * tests), so the gitignore block always reflects what Forge actually emits.
+ * artifacts. The caller injects `syncFn` (the sync runner) so this config-leaf module
+ * never imports the sync compiler; the gitignore block reflects what Forge actually emits.
  * @param {string} root
  * @param {string} name canonical primary-tool key (must be in KNOWN_TOOLS)
- * @param {{syncFn?:(root:string)=>Promise<{report:any[]}>|{report:any[]}}} [opts]
+ * @param {{syncFn?:(root:string)=>Promise<{report:any[]}>|{report:any[]}}} [opts] syncFn is required at runtime
  * @returns {Promise<{primaryTool:string, configPath:string, targets:string[],
  *   gitignore:string, gitignorePath:string}>}
  */
 export async function applyPrimaryTool(root, name, { syncFn } = {}) {
   if (!KNOWN_TOOLS.includes(name))
     throw new Error(`unknown tool: ${name} (known: ${KNOWN_TOOLS.join(", ")})`);
   const cfgFile = setPrimaryTool(root, name);
-  const runSync = syncFn || (async (r) => (await import("./sync.js")).sync({ targetRoot: r }));
-  const { report } = await runSync(root);
+  // syncFn is injected by the caller (cli.js / tests). Required so this config-leaf
+  // module never imports the sync compiler — keeping the layering acyclic.
+  if (typeof syncFn !== "function")
+    throw new Error("applyPrimaryTool requires an injected syncFn(root) -> { report }");
+  const { report } = await syncFn(root);
   const targets = nonPrimaryTargets(report, name);
   const gi = ensureGitignoreBlock(root, targets);
   return {