diagrams: single source of truth + bin/regen-diagrams + CI staleness check#91
Merged
Conversation
…check
Both docs/research/repo-tree.md (D3 tree) and repo-layout.md (Mermaid graph)
are now regenerated from docs/research/_diagrams.yaml by bin/regen-diagrams.
Pan/zoom code, container HTML, and prose around the diagrams are
untouched — only the data blocks (between AUTOGEN markers) get rewritten.
Caught real drift on first regen:
- findings_count: 38 → 41 (auto-counted via glob)
- task_count: "1-10 + INDEX" → 11 (auto-counted via glob)
- Added GEMINI.md to top-level docs (was missing in tree)
- Added challenges/ to sparse_parity (was missing in tree)
- Added complexity-check, score-all, regen-diagrams to bin/
Auto-counts:
- findings_count: glob "findings/exp_*.md"
- experiments_jsonl_count: lines of "research/log.jsonl"
- task_count: glob "docs/tasks/[0-9]*-*.md"
Generator is idempotent: running twice produces no diff.
CI workflow (.github/workflows/diagram-staleness.yml) runs
`bin/regen-diagrams --check` on PRs that touch the YAML or the
generated files; fails if a regen would change anything, with the fix
("run bin/regen-diagrams locally and commit") in the error message.
mkdocs --strict build: clean (no new warnings).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2 tasks
0bserver07
added a commit
that referenced
this pull request
Apr 25, 2026
#92) Changelog v0.29.0: - New section "Auto-generated repo diagrams (PR #91)" with the drift it caught and the contributor workflow. - PR #91 added to "Pull requests landed" table. CONTRIBUTING.md: - Branch protection note in PR process (1 approval required, admin override for hotfixes, force-push and deletion blocked). - Diagram-staleness CI flagged as the only current CI gate. - New "Updating the repo diagrams" section: edit YAML → run bin/regen-diagrams → commit, with a list of auto-counted placeholders. - New "Releases and version tags" section: SemVer + Keep a Changelog, annotated tag at the merge commit, push pattern. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
6 tasks
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.
Summary
Implements option (C) — full overhaul. Both repo diagrams now regenerate from a single YAML.
What's new
docs/research/_diagrams.yaml— single source of truth. Layer titles, node labels, edges, tree groups, auto-count placeholders.bin/regen-diagrams— Python generator. Reads YAML, computes auto-counts via globs, splices generated content between AUTOGEN markers in the two target files. Idempotent: running twice produces no diff.--checkmode for CI.docs/research/repo-tree.md+repo-layout.md— pan/zoom + container HTML untouched. Only the data blocks live between markers and get rewritten..github/workflows/diagram-staleness.yml— runsbin/regen-diagrams --checkon PRs that touch the YAML or the generated files. Fails the build with a helpful "runbin/regen-diagramslocally and commit" message if regen would change anything.Drift caught on first regen
findings_count: hardcoded 38 → actual 41 (auto-counted)task_count: hardcoded "specs 1-10 + INDEX" → actual 11 (auto-counted)GEMINI.md(added Apr 21 via PR docs: Agent compatibility tracking + GEMINI.md #72)challenges/(added Apr 20 via PR Sprint: address 7 open issues (#7 #8 #27 #30 #43 #56 #61) #82)bin/was missingcomplexity-check,score-all,regen-diagramsWhat stayed untouched
<div>and<button>HTML## Notessection,!!! infoadmonitionThe generator never sees the JS/HTML — it only edits the marked data blocks.
Workflow for editing the diagrams
docs/research/_diagrams.yamlbin/regen-diagrams.mdfilesCI catches anyone who edits the YAML without running the regen.
Test plan
bin/regen-diagramsruns clean (idempotent on second invocation)bin/regen-diagrams --checkexits 0 after a fresh regenpython3 -m mkdocs build --strictpasses (no new warnings)🤖 Generated with Claude Code