Appendix A — Agent patterns

Appendix A - 2. Docs hierarchy + governance index

The Structure of Docs hierarchy + governance index — its shape at a glance:

The index is the one shared map: every agent boots with it, each rule points at exactly one canonical deep doc, and two lints keep it from rotting back into a pile.

flowchart LR
  Index["Rule index<br/>(boot context)"] --> Agent([Every agent boots with it])
  Index -->|each rule cites one| Doc[(Canonical deep docs)]
  Cap{{Cap + coverage lint}} -.->|fail if bloated or unlinked| Index

Accessible description: a single rule index is booted by every agent and points each rule at one canonical deep doc; a cap-and-coverage lint fails the build if the index bloats past its budget or a rule stops cross-referencing its doc.

Projected from the catalogue entry context-and-dispatch / Docs hierarchy + governance index.

On this page: Intent · Motivation · Applicability · Structure · Sample Code · Consequences · Example use within DocAble · Related Patterns

Intent

Intent — Give every agent a single, numbered, cross-referenced rule index (loaded into its boot context) that points at the canonical deep doc for each rule, so the fleet shares one authoritative map instead of re-deriving invariants from scattered files.

Motivation

In a large codebase, the knowledge an agent needs to not-break-things is spread across hundreds of docs. Left to discover that knowledge on its own, an agent re-derives an invariant (badly), or violates a cross-file rule it never found. The failure recurs every time the doc corpus grows: more documentation makes any single fact less findable, not more. Without a canonical index, "the docs say so" is unfalsifiable and unenforceable; there is no agreed place the rule lives.

Applicability

Structure

The Structure diagram appears at the top of this page.

Sample Code

Two lints hold the index honest: a cap lint bounds its size so it stays scannable, and a conformance lint verifies each rule cross-references exactly one canonical doc that exists. The index carries the one-line summary; the doc carries the detail.

import sys

LINE_CAP = 1300   # the index must stay scannable, or agents stop reading it

def lint_index(lines: list[str], doc_exists) -> list[str]:
    findings = []
    if len(lines) > LINE_CAP:
        findings.append(f"index is {len(lines)} lines; cap is {LINE_CAP} — evict a rule to a sub-doc")
    for i, line in enumerate(lines, 1):
        if line.lstrip().startswith("#rule"):          # a numbered rule row
            ref = line.split("->")[-1].strip() if "->" in line else ""
            if not ref:
                findings.append(f"line {i}: rule cites no canonical doc")
            elif not doc_exists(ref):
                findings.append(f"line {i}: rule cites '{ref}', which does not resolve")
    return findings

if __name__ == "__main__":
    import os
    text = open(sys.argv[1]).read().splitlines()
    findings = lint_index(text, doc_exists=os.path.exists)   # doc_exists: does the cited path resolve?
    print("\n".join(findings))
    sys.exit(1 if findings else 0)

Consequences

Example use within DocAble

Contents
⇐ Beginning of this partNext part ⇒Next chapter ›⇤ BeginningEnd ⇥Index
© James C. Davis, 2026–present