CI: make coherence docs portable (green the freshness gate)

mnemion-js/docs/coherence/_overview.html

@@ -150,5 +150,5 @@ <h3>files</h3><ul class="mono"><li>block-palette.ts <span class="dim">shared/cor
 ├─ vite.preview.ts
 ├─ vite.web.ts
 └─ worker-configuration.d.ts</pre><p style="color:var(--dim);font-size:.85rem">● marks a node (a folder with a <code>*.spec.md</code>).</p></section>
-  <footer>Generated at <span id="stamp">2026-06-22 17:28Z</span> — do not edit; run the harness.</footer>
+  <footer>Generated at <span id="stamp">NORMALIZED-TIMESTAMP</span> — do not edit; run the harness.</footer>
 </body></html>

mnemion-js/docs/coherence/graph.json

@@ -1,7 +1,7 @@
 {
-  "generatedAt": "2026-06-22 17:28Z",
+  "generatedAt": "NORMALIZED-TIMESTAMP",
   "root": "mnemion-js",
-  "absRoot": "/Users/daniloc/Documents/Dev/mnemion/mnemion-js",
+  "absRoot": "NORMALIZED-ABSROOT",
   "nodes": [
     {
       "id": "c:.",

mnemion-js/package.json

@@ -19,8 +19,8 @@
     "mcp:smoke": "node scripts/mcp-smoke.mjs",
     "setup": "bash scripts/setup.sh",
     "enable-documents": "bash scripts/enable-documents.sh",
-    "coherence:docs": "coherence docs",
-    "coherence:docs:check": "coherence docs --check",
+    "coherence:docs": "coherence docs && node scripts/coherence-normalize.mjs",
+    "coherence:docs:check": "coherence docs && node scripts/coherence-normalize.mjs && test -z \"$(git diff --name-only -- AGENTS.md docs/coherence/_overview.html docs/coherence/_graph.html docs/coherence/graph.json)\" || (echo 'stale coherence docs — run: npm run coherence:docs' && exit 1)",
     "coherence:claude": "coherence claude",
     "coherence:verify": "coherence verify --fast",
     "coherence:verify:full": "coherence verify",

mnemion-js/scripts/coherence-normalize.mjs

@@ -0,0 +1,37 @@
+// Normalize the non-portable fields the coherence `docs` generator stamps into its
+// output, so the committed artifacts are byte-identical regardless of WHERE they were
+// generated (a dev's absolute checkout path vs CI's /home/runner/...). Without this the
+// docs-freshness gate can only ever pass in the one environment that produced the
+// committed files — which is why CI went red the moment that gate was added.
+//
+// Two non-portable bits:
+//   - generatedAt / a "YYYY-MM-DD HH:MMZ" wall-clock timestamp (changes every run)
+//   - absRoot: the absolute path of the entry dir (machine-specific)
+//
+// Both are derivation-irrelevant (the graph itself is derived from the spec tree + code
+// + git history, which is identical across checkouts). We collapse them to constants in
+// BOTH `coherence:docs` (so the committed copy is normalized) and `coherence:docs:check`
+// (which regenerates, normalizes, then `git diff`s) — so the comparison is deterministic.
+//
+// Run with cwd = mnemion-js (as npm scripts do).
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+
+const TS = /\d{4}-\d{2}-\d{2} \d{2}:\d{2}Z/g;
+const FILES = ["docs/coherence/graph.json", "docs/coherence/_graph.html", "docs/coherence/_overview.html"];
+
+// The absolute root, read from graph.json's own `absRoot` field — so we replace whatever
+// path THIS environment produced (mac, Linux, …), not a hardcoded one.
+let absRoot = null;
+try {
+  const g = readFileSync("docs/coherence/graph.json", "utf8");
+  absRoot = g.match(/"absRoot":\s*"([^"]*)"/)?.[1] ?? null;
+} catch { /* graph.json absent — nothing to normalize */ }
+
+for (const f of FILES) {
+  if (!existsSync(f)) continue;
+  let s = readFileSync(f, "utf8");
+  s = s.replace(TS, "NORMALIZED-TIMESTAMP");
+  if (absRoot) s = s.split(absRoot).join("NORMALIZED-ABSROOT");
+  writeFileSync(f, s);
+}