Docs That Hash Themselves

Repo docs generated from source, fingerprinted for drift

The Frame

Docs rot because they're written by hand and live apart from the code

Every repo needs an accurate map of its own agents, modules, tools, and wiring. Amplifier's DOT-as-Docs system generates that map FROM the repo itself instead of maintaining it by hand.

First question: is this real, or a slideware idea?

×Hand-written docs drift — they live apart from the code and no one remembers to update them.
→DOT-as-Docs generates a repo's docs from the repo's own structure.

The Proof

This is real, shipped code — not a slideware idea

The bundle_docs package is 1,524 lines across 5 modules, covered by 35 unit tests, with source-hashed bundle.dot files already checked into three canonical Amplifier repos.

So generation works. But generating once isn't the hard part.

1,524

lines in bundle_docs, across 5 modules

35

unit tests in test_bundle_to_dot.py

3

canonical repos with a source-hashed bundle.dot

The Tension

The hard part isn't drawing the diagram once — it's knowing later whether it still matches the code

A generated diagram is only useful if you can tell, weeks later, that it hasn't quietly gone stale. Otherwise generated docs drift exactly like hand-written ones.

So the system has to derive the docs from source — and make staleness checkable.

Mechanism — Derive From Source

bundle_repo_dot() builds the overview from the repo's own files

It reads each file's YAML frontmatter and @mention wiring — extract_mentions() and extract_delegation_targets() — and emits one structured DOT overview built entirely from source-of-truth.

That gives an accurate map. Next: how do you fingerprint it?

Walk the repoAgents, modules, tools, behaviors, context files.
Read the source-of-truthYAML frontmatter + @mentions parsed from each file.
Emit one DOT overview8 subgraph clusters; root reports 4 tools · 11 agents.

Mechanism — Fingerprint It

It stamps the diagram with a SHA-256 source_hash, embedded in the DOT

bundle_to_dot.py computes hashlib.sha256 over the diagram body (L608) and writes source_hash="..." right into the generated DOT (L628) — the repo's structure becomes a single checkable value.

Now compare that fingerprint over time.

# bundle_to_dot.py
import hashlib  # L18

structural_hash = hashlib.sha256(
    body_str.encode()
).hexdigest()          # L608

source_hash="..."       # L628

foundation bundle.dot:
source_hash="4e75ed198c47f3216995c14b089832295baab45549d7067fc1a6d5701ba5a6a2"

The Turn

The recipe recomputes the hash and compares it to the one on disk

generate-bundle-docs (v3.0.0) recomputes the source_hash and diffs it against the existing bundle.dot: identical means no drift, so it skips; different means the structure changed, so the docs regenerate.

The embedded hash is now an on-demand drift signal.

=new_hash == old_hash → needs_regen = False (skip — no drift).
≠Hashes differ → structure changed → regenerate the docs.
+Then zen-architect (ARCHITECT mode) rewrites labels for humans — instructed to preserve ALL numeric annotations exactly.

The Payoff

Docs become a deterministic function of source you can re-derive and diff

test_source_hash_deterministic asserts the same input always produces the same hash (hashes1 == hashes2). Because the fingerprint is proven deterministic, drift is detectable by comparison — not by someone remembering to look.

Freshness stops being trust and becomes a diff.

# test_bundle_to_dot.py L171
def test_source_hash_deterministic():
    # Same input always produces
    # the same source_hash
    ...
    assert hashes1 == hashes2  # L182

The Takeaway

Fingerprint any artifact against its source, and detect drift by diff instead of by discipline

The pattern generalizes past documentation: derive the artifact from its source-of-truth, hash the result deterministically, and compare. Staleness becomes a value you can check — not a habit you hope people keep.

Docs as a function of source: re-derivable, diffable, honest.

Sources

Research Methodology

Status: Shipped & tested in amplifier-foundation

Data as of: February 20, 2026. Development landed 2026-04-01 to 2026-04-03 (PRs #145, #146, #149), all by Brian Krabach — sole author of all 6 commits on the bundle_docs code path.

Research performed:

Line counts: wc -l amplifier_foundation/bundle_docs/*.py → 1,524 lines across 5 modules.
Hash mechanism: grep -n 'hashlib\|source_hash\|sha256\|def bundle_repo_dot' bundle_to_dot.py → L18 / L66 / L608 / L628.
Embedded hash: head -20 bundle.dot → source_hash="4e75ed19...ba5a6a2".
Recipe logic: sed -n '1,80p' recipes/generate-bundle-docs.yaml → v3.0.0 hash-compare / needs_regen.
Test count: grep -c 'def test_' tests/test_bundle_to_dot.py → 35; determinism at L171-182.
Artifacts: grep -rl 'source_hash=' --include='*.dot' → 3 canonical repos.
Timeline & authorship: git log --format='%H|%an|%ad' -- bundle_docs/ generate-bundle-docs.yaml.

Gaps / not claimed: There is NO cron/CI job that regenerates or verifies docs (only ci.yml runs pytest). No "24h correction" SLA, no per-commit verification, and no "zero human hours" or "83 sections / 34 repos" metric exists in the repos — those slogans were investigated and could not be verified, so they are not asserted here.

Primary contributor: Brian Krabach (6 of 6 commits, 100%, 2026-04-01..03).