Capstone: The Self-Maintaining Repository

The Test for a Self-Maintaining Repository

The prerequisite track ended with a test: can a brand-new agent session work effectively in this repository without asking a single question to a human? The prerequisite track's answer was the documentation kit — README, context file, ADRs, runbook, lessons file, drift tests.

This track's test is sharper: can the documentation stay accurate without a scheduled human maintenance session? Not "is it accurate today" but "will it be accurate six months from now, across a hundred PRs, without anyone manually reviewing every doc change?"

A self-maintaining repository passes this test. Not because the documentation is perfect — no doc set is ever perfect. Because the infrastructure maintains the documentation. Drift tests catch countable fact violations in CI. Reference generators own their sections and regenerate on merge. The freshness gate blocks PRs when docs expire. The doc-bot raises mechanical update PRs automatically. The change classifier reserves human review for the semantic boundary where human judgment is required.

The architecture map above shows every component from this track assembled into one system. The path from a merge to a current doc set runs through all of them: the diff triggers the doc-bot, which consults the registry, drafts mechanical patches, runs them through the classifier, stamps provenance, and opens PRs. CI runs the freshness gate and drift tests on every PR. Mechanical PRs auto-merge. Semantic PRs sit in the review queue. The registry stays current because unregistered docs block merge and missing-path violations surface immediately.

The Maturity Model

The path to a self-maintaining repository is not a single project. It is a sequence of levels, each closing a specific failure mode.

One distinction before reading the model: the docs-rot lesson's A0–A4 automation ladder grades how automated a single doc type is. This L0–L4 maturity model grades the whole repository. The two scales rhyme but do not map one-to-one — drift tests move an individual doc to A2 on the per-doc ladder, but the repo as a whole does not reach L3 until the full gate stack (drift tests, generators, and a blocking freshness SLO) is enforced in CI.

The levels are dependencies, not suggestions. The doc-bot at L4 requires the registry from L3 — it cannot identify which docs are affected by a diff without a registry to consult. The freshness gate at L3 requires the DocRecord shape established at L2 — the verified_at and max_age_days fields that the gate reads. Skipping levels to build the "interesting" parts first produces a system that guesses at affected docs, has no enforcement downstream, and breaks in ways that take hours to diagnose.

What This Track Built

This track started where the prerequisite track ended. That track taught what each doc type is for and why docs are the agent interface. This track built the automation that makes the interface self-maintaining.

Ten lessons. Ten components in the assembled system:

The docs-rot lesson established the thesis: docs rot because humans maintain them. The automation ladder from hand-maintained to drift-tested to generated to self-maintaining. Every hand-maintained fact is a future lie.

The drift-detection lesson built the drift test suite. Countable facts, links, schema contracts, code examples — each drift class has a detector that runs in vitest on every PR. This academy's own CI is the worked example: count-integrity tests that assert the real lesson count, link gates that catch deleted runbook steps, BuildChallenge ID cross-checks that block an unregistered challenge from shipping.

The generated-references lesson built reference generators. One source of truth, many projections. The BEGIN-GENERATED / END-GENERATED marker pattern that lets CI regenerate sections and diff them against what is on disk. Hand-editing a generated section is drift — the generator catches it on the next CI run.

The doc-bot lesson built the doc-bot engine. Trigger on merge, scan the diff, map to affected docs via the registry, draft a surgical patch, open a PR. The surgical-edit contract: "fix only these items; do not change anything else" prevents helpful rewrites of prose the bot was not asked to touch.

The runbooks lesson built runbook verification. Runbooks are executable claims — every step references commands, flags, and paths that can stop existing. Drift-checking a runbook means parsing its steps and verifying that the referenced artifacts still exist on a schedule. A runbook whose verification fails is an incident pre-staged for 3am.

The changelog lesson built the changelog pipeline. Conventional commits as the structured input. Classification with claude-haiku-4-5, grouping by type and scope, prose generation with claude-sonnet-4-6. The changelog is a machine interface: this academy's lesson announcement bot reads frontmatter dates to trigger Discord announcements — the changelog is downstream infrastructure, not just a courtesy for humans.

The doc-registry lesson built the doc registry and scanner. The DocRecord shape as the index over all living docs. The registry scanner that walks the docs tree, reconciles against the registry, and flags unregistered docs and registered-but-missing paths. Without the registry, the doc-bot has no map.

The freshness-SLO lesson built the freshness gate. Per-doc-type SLOs. The verified_at field as the freshness signal, not mtime. The block tier that exits 1 and prevents merge when any doc is expired. Advisory warnings that train teams to ignore them versus block gates that change behavior.

The doc-bot-safety lesson built the safety model. The mechanical/semantic boundary. The claude-haiku-4-5 classifier with structured output and a safe default toward semantic for any ambiguous case. Provenance footers on every bot-generated PR. The doctrine: fresh timestamps on wrong content are worse than stale timestamps on old content.

The capstone lesson assembles the system.

The Capstone Challenge

The capstone is not a tutorial exercise. It is a real system that needs to be wired together.

The challenge assembles the registry scanner, drift checks, and freshness gate into a single pipeline function that returns a structured report. Every check is a component built in a prior lesson. The capstone connects them: load the registry, check for unregistered docs, verify checksums on generated docs, run freshness checks, compute an exit code.

The report is the integration point. It names each violation, its type, the affected doc, and the owner. The CI entry point reads the report, prints it, and exits on the code. That is the complete CI gate.

Pick one of your own repositories. Apply the full pipeline:

1. Write the doc registry — a list of DocRecords, one per doc worth tracking
2. Write or audit your drift tests for countable facts and links
3. Add the freshness gate to CI — set max_age_days generously at first, tighten over a sprint
4. Add required-doc rules for the most critical new-code patterns
5. Build the doc-bot for at least one mechanical update class (a count, a key-files table entry, a link)
6. Wire the classifier and provenance footer

The full system takes one to two focused sprints to wire up. The ROI begins on the first PR where the freshness gate catches a stale runbook before an on-call engineer reads it at 3am. The ROI compounds on every agent session that loads a current context file instead of one that was last verified six months ago.

Documentation that maintains itself is not a luxury for well-resourced teams. It is the minimum viable documentation infrastructure for a repository where agents work. An agent that reads a wrong doc produces wrong work — confidently, without warning, at the speed of AI. The self-maintaining repository is how you prevent that.