session 2026-07-28: governance block closed — CLAUDE.md drift 9→0 (REVIEWED-76/77/79/80), PENDING.md split 1848→430 + archive, wake-digest SessionStart hook, doctrine ids live, PENDING-79/80/81

scripts/governance-drift-check.py

@@ -142,6 +142,55 @@ for i, line in enumerate(lines, 1):
                         f"— orphans the section beneath it")
 
 
+# --------------------------------------------- 6. doctrine-ID integrity
+# Doctrine units may carry a stable id in an HTML comment: `<!-- D:memory.check-first -->`.
+# Invisible in prose, parseable by tools, and IN the canonical — so there is no second
+# version to drift (L110). Skills cite an id instead of paraphrasing the rule; this
+# section catches a citation whose doctrine has been reworded away, and duplicate ids.
+# Dormant until the first id exists; the controls below run either way, so "nothing
+# reported" means "checked and clean", not "never looked".
+DOCTRINE_DEF = re.compile(r"<!--\s*(D:[a-z0-9][a-z0-9-]*\.[a-z0-9][a-z0-9-]*)\s*-->")
+DOCTRINE_REF = re.compile(r"\b(D:[a-z0-9][a-z0-9-]*\.[a-z0-9][a-z0-9-]*)\b")
+
+defined: dict[str, int] = {}
+for i, line in enumerate(lines, 1):
+    for did in DOCTRINE_DEF.findall(line):
+        if did in defined:
+            findings.append(f"L{i}: duplicate doctrine id {did} "
+                            f"(also L{defined[did]}) — a citation cannot resolve it")
+        else:
+            defined[did] = i
+
+# Citing surface: the skills, which are the intended consumers. Deliberately NOT
+# PENDING.md — drafts there legitimately quote ids that do not exist yet.
+skills_dir = HOME / ".claude" / "skills"
+scanned = 0
+if skills_dir.is_dir():
+    for f in sorted(skills_dir.rglob("*.md")):
+        try:
+            if f.stat().st_size > 200_000:
+                continue
+            body = f.read_text(errors="replace")
+        except OSError:
+            continue
+        scanned += 1
+        for ref in sorted(set(DOCTRINE_REF.findall(body))):
+            if ref not in defined:
+                findings.append(
+                    f"{f.relative_to(HOME)}: cites doctrine id {ref}, which "
+                    f"~/CLAUDE.md does not define — the rule was reworded or removed")
+
+control("doctrine-id parser detects a definition",
+        bool(DOCTRINE_DEF.findall("x <!-- D:memory.check-first --> y")))
+control("doctrine-id parser detects a citation",
+        DOCTRINE_REF.findall("see D:memory.check-first here") == ["D:memory.check-first"])
+control("doctrine-id parser rejects a non-id",
+        not DOCTRINE_DEF.findall("<!-- D:nodot -->")
+        and not DOCTRINE_REF.findall("D:NoDot.Caps"))
+control("doctrine-id citing surface is reachable",
+        (not skills_dir.is_dir()) or scanned > 0)
+
+
 # ------------------------------------------------------------- report
 failed_controls = [lbl for lbl, ok in controls if not ok]
 if failed_controls: