CI: make coherence docs portable (green the freshness gate) - #7
Merged
Conversation
The docs-freshness gate (added with the coherence-improvements work) has been red since #2 for a reason unrelated to any feature: `coherence docs` stamps two machine-specific fields into graph.json / _graph.html / _overview.html — - a wall-clock `generatedAt` timestamp, and - `absRoot`, the ABSOLUTE checkout path (/Users/daniloc/… locally vs /home/runner/… in CI) so the committed artifacts only ever matched the one machine that generated them. The tool's own `--check` normalizes the timestamp but not absRoot, so CI (regenerating at a different path) always saw graph.json/_graph.html as stale. Fix: a tiny post-generate normalize step (scripts/coherence-normalize.mjs) that collapses the timestamp + absRoot to constants — both derivation-irrelevant (the graph is derived from the spec tree + code + git history, identical across checkouts). Wired into: - coherence:docs → generate, then normalize (committed copy is portable) - coherence:docs:check → generate, normalize, then `git diff --name-only` the four artifacts (deterministic across environments) Regenerated + normalized the committed docs. coherence:docs:check is green. (The proper home for this is the coherence tool emitting relative paths — a candidate for the upstreaming already tracked in coherence-tooling-upstream.md.) 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 | bb497aa | Jun 22 2026, 05:40 PM |
This was referenced Jun 22, 2026
daniloc
added a commit
that referenced
this pull request
Jun 23, 2026
) 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>
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.
The docs-freshness gate (added with the coherence-improvements work) has been red since #2 — unrelated to any feature.
coherence docsstamps two machine-specific fields into the generated artifacts:generatedAttimestamp, andabsRoot, the absolute checkout path (/Users/daniloc/…locally vs/home/runner/…in CI).The tool's own
--checknormalizes the timestamp but notabsRoot, so CI — regenerating at a different path — always sawgraph.json/_graph.htmlas stale. The committed artifacts only ever matched the one machine that produced them.Fix: a tiny post-generate normalize step (
scripts/coherence-normalize.mjs) collapsing the timestamp +absRootto constants (both derivation-irrelevant — the graph is derived from the spec tree + code + git history, identical across checkouts). Wired into:coherence:docs→ generate, then normalize (committed copy is portable)coherence:docs:check→ generate, normalize, thengit diff --name-onlythe four artifacts (deterministic across environments)Regenerated + normalized the committed docs;
coherence:docs:checkis green locally. The proper long-term home is the coherence tool emitting relative paths (already tracked incoherence-tooling-upstream.md).🤖 Generated with Claude Code