Prevent stale-coherence-docs CI failures (tool fix + pre-push hook) - #12
Merged
Conversation
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>
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
mnemion | b83d640 | Jun 22 2026, 11:36 PM |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to the CI hiccup on #11, where the
_canvasesfix's comments shifted symbol line numbers andcoherence:docs:checkfailed on pure line-number drift — a false positive that turns "regenerate the derived docs" into a remembered convention.Two complementary layers, matching the project's own doctrine (convert the convention into a contract; make the gate measure only what matters):
1. Tool fix — coherence v0.5.0 → v0.5.1
The freshness gate now normalizes out line numbers (
"line": Nin graph.json,data-line="N"in _graph.html), alongside the existinggeneratedAt/absRoot/ABSstrips. So the gate fails only on real structural drift (nodes, edges, claims, boundaries) — a comment or line-shift no longer drifts the committed artifacts, and committed graph diffs stop being polluted with line churn. A docblock change still flags (it's genuinely semantic). This is the deeper fix for the cross-env gate finickiness that #7/#8 worked around. Line numbers stay in the generated files for theeditor://deep-links — they're just no longer load-bearing for freshness.2. Shift-left — pre-push hook
scripts/git-hooks/pre-pushrunscoherence:docs:checkbefore a push, auto-installed via thepreparescript (core.hooksPath). With v0.5.1 it fires only on genuine structural drift committed without a regenerate — blocking it on your machine with the exact fix command, instead of failing late in CI. Bypass a single push withgit push --no-verify.Verified
docs current; a real new exported symbol still flags stale. ✅docs:checkgreen on this branch.🤖 Generated with Claude Code