From b83d640aea6bb4b13401cdf1a59e7b1ea8ae2405 Mon Sep 17 00:00:00 2001
From: Danilo Campos <danilo@posthog.com>
Date: Mon, 22 Jun 2026 16:36:01 -0700
Subject: [PATCH] Prevent stale-coherence-docs CI failures (tool fix + pre-push
 hook)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two-layer prevention for the class where a source edit drifts the committed
coherence graph and CI fails late on coherence:docs:check:

1. Tool fix — bump coherence v0.5.0 → v0.5.1, whose freshness gate now
   normalizes out line numbers. A comment/line-shift edit no longer drifts
   graph.json/_graph.html, so the common false positive is gone and committed
   graph diffs show only real structural change. (This is the deeper fix for
   the cross-env gate finickiness #7/#8 worked around.)

2. Shift-left — a pre-push hook (scripts/git-hooks/pre-push, auto-installed
   via the `prepare` script setting core.hooksPath) runs coherence:docs:check
   before a push. With v0.5.1 it fires ONLY on genuine structural drift
   committed without a regenerate — blocking it on your machine instead of in
   CI, with the exact fix command. Bypass with `git push --no-verify`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 mnemion-js/package-lock.json          |  6 +++---
 mnemion-js/package.json               |  3 ++-
 mnemion-js/scripts/git-hooks/pre-push | 20 ++++++++++++++++++++
 3 files changed, 25 insertions(+), 4 deletions(-)
 create mode 100755 mnemion-js/scripts/git-hooks/pre-push

diff --git a/mnemion-js/package-lock.json b/mnemion-js/package-lock.json
index 308ddc0..2aecf56 100644
--- a/mnemion-js/package-lock.json
+++ b/mnemion-js/package-lock.json
@@ -33,7 +33,7 @@
         "@types/react-dom": "^19.2.0",
         "@vitejs/plugin-react": "^5.0.0",
         "ai": "^6.0.206",
-        "coherence-harness": "github:daniloc/coherence#v0.5.0",
+        "coherence-harness": "github:daniloc/coherence#v0.5.1",
         "concurrently": "^9.0.0",
         "typescript": "^6.0.3",
         "vite": "^8.0.16",
@@ -4025,8 +4025,8 @@
       }
     },
     "node_modules/coherence-harness": {
-      "version": "0.5.0",
-      "resolved": "git+ssh://git@github.com/daniloc/coherence.git#1a164d5155d2b108a11363c1fea55ef946e65e78",
+      "version": "0.5.1",
+      "resolved": "git+ssh://git@github.com/daniloc/coherence.git#87009cd650657fededd0140865941dce06ba1b1c",
       "dev": true,
       "bin": {
         "coherence": "dist/cli.js"
diff --git a/mnemion-js/package.json b/mnemion-js/package.json
index 825218c..fcfb426 100644
--- a/mnemion-js/package.json
+++ b/mnemion-js/package.json
@@ -4,6 +4,7 @@
   "private": true,
   "license": "MIT",
   "scripts": {
+    "prepare": "git config core.hooksPath mnemion-js/scripts/git-hooks || true",
     "build:pages": "vite build --config vite.fragment.ts",
     "build:web": "vite build --config vite.web.ts",
     "preview:render": "vite dev --config vite.preview.ts --open /render-preview.html",
@@ -63,7 +64,7 @@
     "@types/react-dom": "^19.2.0",
     "@vitejs/plugin-react": "^5.0.0",
     "ai": "^6.0.206",
-    "coherence-harness": "github:daniloc/coherence#v0.5.0",
+    "coherence-harness": "github:daniloc/coherence#v0.5.1",
     "concurrently": "^9.0.0",
     "typescript": "^6.0.3",
     "vite": "^8.0.16",
diff --git a/mnemion-js/scripts/git-hooks/pre-push b/mnemion-js/scripts/git-hooks/pre-push
new file mode 100755
index 0000000..c814d93
--- /dev/null
+++ b/mnemion-js/scripts/git-hooks/pre-push
@@ -0,0 +1,20 @@
+#!/bin/sh
+# Block a push that would land STALE coherence docs.
+#
+# The committed docs/coherence/{graph.json,_graph.html} + AGENTS.md are derived
+# from the spec tree + code; CI's `coherence:docs:check` fails if they drift. This
+# hook moves that check left — to before the push leaves your machine — so the
+# regenerate step is enforced by the tool, not remembered as a convention.
+#
+# With coherence >=0.5.1 the freshness gate ignores line numbers, so this fires
+# ONLY on real structural drift (a new/removed/renamed symbol, import, component,
+# claim, or boundary) committed without regenerating. Comment/line-shift edits
+# pass silently. Installed via the `prepare` script (core.hooksPath); bypass a
+# single push with `git push --no-verify` if you must.
+cd "$(git rev-parse --show-toplevel)/mnemion-js" || exit 1
+if ! npm run --silent coherence:docs:check; then
+  echo ""
+  echo "✗ push blocked: coherence docs are stale (a structural change without a regenerate)."
+  echo "  Fix:  (cd mnemion-js && npm run coherence:docs)  then commit docs/coherence/ + AGENTS.md."
+  exit 1
+fi