Dual-Graph Drift Detection for Solo Devs: What Happens When Your Docs and Your Code Start Talking to Each Other

Dual-Graph Drift Detection for Solo Devs What Happens When Your Docs and Your Code Start Talking to Each Other I'm a coffee roaster in Taiwan who taught myself to code with AI over the past 8 months. I built a full vertical-integration ERP for my coffee brand — from green bean inventory to roasting orders to e-commerce checkout. Along the way I ran into something nobody on the internet seems to be writing about: a way for the **prose* I've written (docs, specs, governance rules) and the code I've shipped to literally audit each other. This is that workflow.* The 14-Hour Origin of My "Governance Awareness" People ask me, "When did you start caring about governance?" I can answer with 14-hour precision. April 21, 2026, 11:41 AM. That was the first time I wrote governance-guard into a prompt to Claude Code: "Should we put these 3 audit rules into governance-guard? Yes. Then can you do a targeted scan based on these and report potential errors back to me?" Later that afternoon at 15:08, I doubled down: "Option B (CI layer): governance-guard adds a rule to scan all relative / alias import paths... fail = block ——> do this." 14 hours later, April 22, 1:12 AM, I used the word "governance" for the first time: "Should we save all the fixes and rules we discussed as a 'skill', so future projects can reuse them? I'm worried that once my attention returns to MVP launch, all this governance work will be forgotten and turn into hidden risk. I don't know how a solo developer is supposed to allocate this kind of work." In the same Claude Code session (70aa7ce0), in those 14 hours, three governance artifacts were born: governance-guard.mjs — a CI script that blocks pushes on rule violations TECH-DEBT-BACKLOG.md — known violations don't get fixed immediately; they get queued for me to triage skill files — a way to make rules survive across sessions and across projects These 14 hours are the precise moment my governance awareness was born. Before this, I asked AI "fix this." After this, I asked "fix this *+ prevent it from happening again*." The question went from one-dimensional to two-dimensional. That Month: 348 Commits, Fixing the Same Bug Five Times April 2026 was the most brutal month of my 8 months of development — I accumulated 348 git commits, the highest single-month count in the project's history. It went like this: I'd fix one order bug, fix it, realize the same pattern showed up elsewhere, fix that, fix again, then the first one would break. The most dramatic prompt came at 8:39 AM on April 29: "I'm dumbfounded. Why is the previous balance showing 0? We've fixed it five or six versions already — go look at git. This should be a really simple problem for you. Why has it taken so many tries?" That wasn't a technical question. It was the scream of a governance problem. The root cause (which I later turned into one of 14 data-drift debugging records): Layer What was written CLAUDE.md Rule 21 (spec) SSOT — frontend may not override DB truth; single_price is the canonical source single_price (DB schema) Exists useOrderAggregation.js (code) Uses `product.single_price \ {% raw %}Reports.vue (code) Uses a different legacy fallback chain AdminPOS.vue (code) Recalculates totals on the frontend The docs said "single_price is SSOT", the code used a 5-layer fallback, and the UI was still recalculating. Fix one location, the other four kept dropping. By the fifth attempt I realized — I'm not fixing a bug, I'm fixing a governance problem. That prompt became the entire motivation for CLAUDE.md Rule 17 Step 0: "For value-mismatch bugs, the first step MUST be a SQL query against the DB. Do not guess in code." The "Governance Terminology Birth Engine" Looking back at that month's prompts, I noticed a very consistent pattern in how I asked things. I call it my governance terminology birth engine. The canonical example (also April 29, 6:03 AM): "Help me find all of them. Is there an industry term for this phenomenon? Use it to do a comprehensive search." The structure is always the same: I observe a symptom (button doesn't respond, order totals don't match, bean inventory off by a kilogram) What's the term? (literally ask AI to name the phenomenon) Now scan for all instances using that name Every governance term in my codebase was born this way — skill files, Type A/B/C drift classification, Layer 1-6 defense, SSOT, governance-guard, TECH-DEBT-BACKLOG, "data-drift debugging records." Each name has a prompt like this behind it. Converting daily pain into indexable abstract terminology — that's the seed crystal that governance systems grow around. I didn't suddenly understand governance one day. I had 8 months of AI repeatedly asking me, "Does the concept you're describing have a name in your project?" Same Day, Two Opposite Attitudes Toward AI What's more interesting — on the same day, I had two completely opposite attitudes toward AI. April 21, 2:20 AM: "Please... synthesize everything you're about to say to me into markdown — but as questions you ask me back, not as answers. Let's go from divergent to convergent." This is the soft inquiry mode — treat AI as Socrates, force me to think through it myself. Same day, 11:41 AM: "Should we put these 3 audit rules into governance-guard? Yes." This is the hard blocking mode — use a CI script to fence AI (and my future self) out of mistakes. That's when I realized — two opposite attitudes on the same day, mapping exactly to the human need for freedom vs. discipline: For business direction, persona refinement, brand positioning (divergent work): I want AI to question me (soft) For code governance, SSOT maintenance, file contracts (convergent work): I want a CI script to block AI (hard) The greatest discipline of a one-person founder — knowing when to loosen the reins and when to lock them down. This dual-attitude toward AI is the most precious methodology I've developed in 8 months. Geology of Rules: Layer 6 of Rule 21 Was Born at May 2, 3:14 AM My CLAUDE.md has 26 rules. Rule 21 ("SSOT Five-Layer Defense") is the most-cited one. But you should know — it originally had only 4 layers. I can date the exact moment it gained a 6th: May 2, 2026, 3:14 AM. That day I was fixing a roast-degree display bug — the orders list mixed Chinese and English: "medium roast", "medium", "medium_light", "medium_dark". The same field was being handled three different ways across RPC, normalizeOrder, and UI — classic drift. The prompt: "Should I write this skill and update CLAUDE.md Rule 21 to add Layer 6? Yes, do it. Also, I just noticed — why are some roast degrees in Chinese and some in English? They're clearly not being read from the SSOT." That was the moment of expansion from 4 to 6 layers. The two new layers: Layer 5: RPC ↔ normalizeOrder ↔ UI three-tier field contract (born from the balance_before = 0 bug) Layer 6: Cross-layer data contract propagation audit (born from the roast-degree mixed-language bug) 28 minutes later at 3:42 AM, I asked: "Is there a way to do a comprehensive scan that proactively finds where else this kind of problem might occur?" Rules grow in geological layers. Each layer is a specific frustration that crystallized into a fossil. Layer 5 is the pain of fixing balance_before five times. Layer 6 is the pain of roast degrees being handled three different ways. If you see my CLAUDE.md grow a Layer 7 or Layer 8 in the future — that will absolutely be another specific frustration that forced it out. Not because I read a "treasure hunt defense design guide" first. The Real Solution Isn't "Fix Bugs", It's "Reconcile" Starting that month I did three things: Built governance-guard.mjs — a CI script that scans code for violations of CLAUDE.md rules Wrote 14 data-drift debugging records — classified each bug into Type A / B / C / D / E drift For every bug I fixed, I now ask: "Is this bug just the surface symptom of an SSOT violation?" If yes — fix upstream, add a governance rule But it wasn't enough. governance-guard can only scan known violations — the ones I've written rules for. Drifts I haven't written into rules are invisible to it. The deeper problem is — even rules I've written, I forget. 6 months ago I wrote Rule 9 (no raw system_role compare), but in a new Claude session this month, neither I nor the AI remembered. Looking Only at Code, You Miss "Intent Has Changed" GitNexus is a powerful tool. It turns my codebase into a graph of 23,280 symbols / 45,727 edges — every function, every call, every import. Ask it, "What's the blast radius of fn_create_order_atomic?" — perfect answer, lists which functions break at distance d=1, d=2, d=3. But ask it, "Is CLAUDE.md Rule 9 (no raw system_role compare) still being respected, 6 months after I wrote it?" — it doesn't know that rule exists. It only sees code, not doc-intent. This is the ceiling of code-graphs — they can only tell you "what code is doing now", not "how much that has drifted from what I originally intended". Looking Only at Docs, You Miss "Code Quietly Never Implemented It" Graphify (covered in detail in T10) turns my 50+ .md files into a graph of 7,230 concept nodes. It helps me find cross-file surprising connections I never consciously made. But ask it, "This RPC I designed 2 months ago — did the code actually return the fields I said it would?" — it can't answer. It only sees docs, not whether code quietly never implemented them. This is the ceiling of doc-graphs — they can only tell you "what intent I wrote", not "whether the code caught up". Even Graphify Misses Systemic Problems The most honest admission — May 15, 2026 morning, I was fixing a roasting batch display anomaly when I said: "This isn't a single-batch problem. This is **systemic data drift. Why didn't the previous root-cause analysis catch this serious failure? **Did graphify and gitnexus both fail to help?" That moment I realized — graphify can catch "the same concept appearing similarly in different files", but it can't catch "a structural data drift distributed across 5 files as 5 different symptoms". Each file only contains part of the symptom; there's no complete pattern to detect. This is why just chaining two graphs isn't enough — you need a third layer, governance-guard, which explicitly writes "symptom patterns" as rules to enable reverse scanning. A Live Case That Happened While Writing This Article While drafting this article, I just realized my admin UI is missing the "assign series" interface. My blog post schema (content_pages table) has had series_slug and series_order columns for weeks. I've manually filled in values for 4 posts (via SQL console direct UPDATE). But the admin content management page has no UI for editing series. I'd been changing it via SQL the whole time. I literally forgot, "oh, I never built that UI." This is a 100% live case of doc-as-spec × code-as-reality drift: Layer State DB schema ✅ series_slug + series_order exist DB data ✅ 4 posts have values (filled manually via SQL) Admin UI ❌ No edit field built Public series cards (frontend) ❌ Probably also not built If graphify + gitnexus + governance-guard were chained and auto-reconciling: graphify catches the series concept appearing in .md / spec files gitnexus detects no admin UI component references series_slug governance-guard auto-flags: "Schema has series_slug, but 0 admin UI components reference it" This would've been blocked the first time. I wouldn't have only noticed today that "oh, I never built that UI." Another Meta Moment: cp950 Codepage Failure Mid-article, I tried re-running npx gitnexus analyze to get the latest numbers. First attempt failed instantly — DuckDB's COPY command on Windows with a Chinese path tried to encode in cp950 and crashed. My reaction (with AI's help) was "oh, must be UTF-8 issue" — ran chcp 65001 + LC_ALL=UTF-8 + Console.OutputEncoding=UTF8 three-layer enforcement. Still failed, because DuckDB internal IO looks at Windows system locale, not console codepage. Finally I checked memory and realized — I had solved this exact problem 17 days earlier, using an NTFS junction (C:\gn-cssaas) to give the project an ASCII-only path. The most ironic part — my graphify-out vault already had a community labeled 183 documenting this: Gitnexus zh-TW cp950 Codepage Failure → chcp 65001 + LC_ALL UTF-8 fix If doc↔code drift detection were running, today's first error would have been caught by graphify, surfacing the message "you wrote a solution 17 days ago in reference_gitnexus_setup.md". What actually happened — I (with AI) just walked into the trap. Failure #1, failure #2, then checked memory for the solution. 20 minutes of tuition. This is the real cost of dev-time drift — not the big-bang bugs, but the 20-minutes × 365 days = 122 hours/year of low-grade friction. Four Drift Types That Stacked Graphs Can Detect Chain graphify (doc-graph) + gitnexus (code-graph) + governance-guard (auditor), and you can auto-detect four kinds of drift: Drift Type Example Detection Method Intention drift Docs say it exists, code didn't implement it doc-graph has node + code-graph empty Undocumented knowledge Code works fine, docs never described it code-graph has node + doc-graph empty Concept gap Docs link A→B, code never imports doc-graph has edge + code-graph missing edge Hidden complexity Code has complex flow, docs give zero explanation code-graph node degree high + doc-graph corresponding node low All four I've stepped on. Series UI absence = Intention drift. cp950 solution forgotten = Undocumented knowledge (solution was in memory.md but governance-guard didn't know about it). Why Nobody Else Online Is Writing About This Combo I did web research. Conclusion: the community isn't doing this. Someone is doing code-graph routing (Sidharth Satapathy's 17-agent crew uses dual-graph for problem routing), but nobody is doing drift detection. Several structural reasons: Most engineers don't write docs — no doc-graph to reconcile against In large companies, specs are written by other people — engineers don't trust them, no incentive to reconcile Both tools are new — GitNexus + Graphify both emerged in 2026; the user intersection is small No economic incentive — drift reconciliation is the hardest value to quantify; no startup makes it a selling point Solo devs have "self-written docs" as a unique asset — large-company docs have low trust, open-source docs are scarce "Governance" isn't a familiar concept in solo circles — most solo devs see governance as a big-company thing Stack these 6 conditions. The number of people who simultaneously have all 6 isn't large. I'm not discovering a new continent. I just happen to stand in the only spot where this landscape is visible. My Workflow Ritual How I'm trying to make this combo run (incomplete, still experimenting): Every git commit → triggers a graphify hook, creates a flag in graphify-out/needs_update, the ritual reminds me to re-run Every new Claude session → first thing the ritual does is check TECH-DEBT-BACKLOG.md high-priority items + needs_update flag Every code symbol change → I'm required to run gitnexus_impact first to see blast radius Weekly → run governance-guard.mjs to see new violations Every schema change → simultaneously run graphify (does spec/.md mention this concept?) and gitnexus (are there UI components referencing this field?) Honestly, this workflow isn't fully formed yet. Item 5 I only realized I needed today (because of the series UI absence). But the scaffolding is there, what's missing is the orchestration script that wires three tool outputs together. Governance Has Evolved Beyond Rules — Into a Skill Network Walking through the 4-22 governance awakening, the 4-29 "I'm dumbfounded" moment, and the 5-02 Layer 6 expansion, my definition of governance has evolved. The most dramatic moment was 2026-05-15 afternoon: "Chain these three governance skills together: data-flow-audit + data-contract-propagation-audit + workstation-button-interaction — the same production bug simultaneously triggered all three abstract governance skills." That moment I realized — governance is no longer about "how many rules I've written". It's about "how many of my written skills the same bug triggers simultaneously". Drawn as a diagram: Production Bug │ ┌──────────┼──────────┐ ↓ ↓ ↓ data-flow- data-contract workstation- audit.md propagation button- -audit.md interaction.md ↓ ↓ ↓ └─── 3 governance skills resonate ──┘ ↓ Fix once, prevent thrice Graphify already knew, during community detection, that these three skills belong to the same community. They share surprising_similar_to edges. But only when I query "what skills relate to this bug?" does graphify return all three. Put another way — the highest form of governance is not the count of rules, but the network resonance between them. Honest Costs I also have to say — this combo isn't cheap: Graphify ~7,000 tokens per full corpus run (~$0.05 USD / run) GitNexus is free (self-hosted MCP), but you have to learn a new tool + maintain an MCP server governance-guard is self-written script; each new rule costs writing + testing + CI integration Correlation layer that chains all three I still haven't built — probably 200-500 lines of orchestration script Total maintenance cost — about 5-8% of my weekly dev time Not something to do during MVP phase. Who Should and Who Shouldn't Should: Solo devs with 30+ .md files accumulated Already has clear governance rules (not necessarily 26, 10+ at minimum) Want to maintain the project long-term, don't want to rewrite in 6 months Has been burned by doc-code drift at least 2-3 times Shouldn't: MVP phase (over-engineering) Pure prototypes (no docs to reconcile) Fewer than 10 .md files (doc-graph has nothing to extract) Short-term 1-2 month contract projects For Anyone Headed This Direction If you also want to start building this combo, the minimum steps I'd recommend: Write governance rules first — not 26, just 3-5 (the SSOT rules around your specific pain points) Build governance-guard script — pure grep / regex is enough; no fancy AST needed Accumulate .md to 20+ before adding graphify — too early and the corpus is too thin Add gitnexus only when your code exceeds 5,000 symbols — small codebases are faster to grep directly Wait until you've actually been hurt by drift 3 times before chaining all three Don't combo for combo's sake. Each tool comes in to solve a specific pain. Not because "it sounds cool to chain them". Closing: When Your Words and Your Code Start Talking to Each Other For me personally, this combo is how I turn that April governance trauma into something systemic. Before, bug-fixing felt like whack-a-mole — fix one, another pops up. Then I built governance-guard and it felt like inventory — I knew what violations existed but didn't know when they'd detonate. The vision now — let all the .md I've written (past me), all the code I've shipped (present me), and the governance rules (my promises to future me) talk to each other. It's not about letting AI write faster. It's about letting past me and present me stop fighting each other. Those 348 commits in April — if this combo had been running, maybe only 100 would have been needed. The other 248 were tuition for "I'd already written the solution but forgot." One last meta moment: writing this article was itself a reconciliation mechanism. While auditing my own GRAPH_REPORT numbers for the T10 article, I finally saw clearly that the god-nodes were minified noise — 50 minutes to clean up 4,549 noise nodes. The cleanup record lives at 治理深度整合紀錄/dist2_cleanup_meta_moment_2026-05-22.md. I'm coffeeshooters — a coffee roaster building software because there wasn't anything off-the-shelf that fit my real workflow. If this resonates: my full dev toolkit is public, and you can also support my coffee brand at coffeeshooters.com. 本文原載於我的部落格：Dual-Graph Drift Detection for Solo Devs: What Happens When Your Docs and Your Code Start Talking to Each Other