feat: dogfood Understand Anything on this repo (#508)

[ethpran]

What & why

Closes #508 — "eat your own dog food." Runs the plugin on this repo and commits the result, so the repo carries a live, maintained knowledge graph of its own architecture. Useful for onboarding, PR-review context, and as a real-world example of the tool.

Committed artifacts (.understand-anything/)

• knowledge-graph.json — structural graph: 674 nodes, 960 edges, 8 architectural layers, 12-step guided tour (includes this PR's own scripts/check-graph.mjs)
• domain-graph.json — business-flow view: 7 domains, 12 flows, 45 steps, version-matched to the knowledge graph via project.gitCommitHash
• meta.json, fingerprints.json — analysis baseline + structural fingerprints (400 files) for incremental updates
• config.json — { "autoUpdate": true }
• .understandignore — analysis scope

Per the README's Share the Graph with Your Team guidance, .gitignore is scoped to drop only the pipeline's local scratch (intermediate/, tmp/, .trash-*/, diff-overlay.json) and track the rest.

Keeping it fresh

• Auto-update enabled (config.json). The plugin's bundled hooks fire the incremental auto-update on commit (+ a staleness check at session start), spending zero LLM tokens on cosmetic changes. The hook refreshes only knowledge-graph.json.
• The domain graph is not auto-refreshed (it's derived from the knowledge graph, no incremental path). Every commit that meaningfully changes structure should run /understand (or let the hook run) and /understand-domain, then commit the refreshed domain-graph.json. Documented in CLAUDE.md and CONTRIBUTING.md.

CI guard — scripts/check-graph.mjs (wired into ci.yml)

Deterministic, zero LLM tokens:

• schema-validates both committed graphs (blocking),
• rebuilds structural fingerprints for the current source tree, warns on drift from fingerprints.json (advisory),
• warns when domain-graph.json's project.gitCommitHash no longer matches meta.json — i.e. the domain view is behind the knowledge graph (advisory).

--strict makes the advisory checks blocking. Reuses core's validateGraph, buildFingerprintStore/analyzeChanges, and createIgnoreFilter, mirroring the auto-update hook's deterministic Phase 1. Graph regeneration is an LLM task and deliberately stays off the PR path.

This PR practices what it documents: after adding check-graph.mjs, the graph and domain view were regenerated to include it, so the guard runs clean (✓ schema · ✓ in sync · ✓ domain in sync).

🤖 Generated with Claude Code