Appendix — the pattern language

The catalogue as a pattern language

This appendix is the governance catalogue rendered as a pattern language. It borrows the style of Design Patterns by Gamma, Helm, Johnson, and Vlissides (the "Gang of Four"), which named and described a canonical set of reusable software-design patterns and wrote each one to a fixed template. Here each governance mechanism becomes one pattern, written the same way.

Every pattern follows the same template:

• Intent — the failure class this mechanism kills, and the shape that kills it.
• Motivation — the recurring failure told as a scenario, and why the naive fix does not hold.
• Applicability — the conditions under which reaching for this pattern pays off.
• Structure — a diagram of the moving parts and how they connect.
• Sample Code — a concrete instance of the pattern.
• Consequences — what adopting it costs and buys, and the second-order effects to watch.
• Example use within DocAble — where the mechanism runs in DocAble.
• Related Patterns — the neighbours it composes with.

How this appendix is organized. The catalogue is split into four lettered appendices, each a different view of the same mechanisms:

• Appendix A — Agent patterns — the mechanisms that govern the fleet that produces the work: how agents are dispatched, isolated, gated, and observed.
• Appendix B — Models-bridge patterns — the mechanisms built around the typed models the fleet reasons through: the shared map a bounded agent uses to operate a codebase larger than its context.
• Appendix C — Product patterns — the mechanisms that govern the shipped artifact itself: its canonical seams, its validation, and its conformance controls.
• Appendix D — Mechanism Stacks — packages of patterns that travel together, each attached to a concept you want to adopt whole.

Read a single page to adopt one mechanism. Read a family in order to see how a cluster of them reinforce each other. The map below is clickable: each mechanism links to its pattern page.

Contents

Agent

Context & dispatch substrate

• Appendix A - 1. Brief-linting
• Appendix A - 2. Docs hierarchy + governance index
• Appendix A - 3. Dynamic context injection
• Appendix A - 4. Role-typed dispatch

Gates & merge-train

• Appendix A - 5. Merge-train MIS batching
• Appendix A - 6. Pre-commit hook (3-stanza, tree-sha markers)
• Appendix A - 7. Sentinel first-commit early-abort
• Appendix A - 8. Staged deploy gates (canary → smoke → promote)

Mediators & resource locks

• Appendix A - 9. Aggregate-compute protection (lint-all host mutex)
• Appendix A - 10. Build-serializer (M=8 semaphore)
• Appendix A - 11. Resource-pressure gating (admit before, shed during)
• Appendix A - 12. Test-serializer (N=1 flock on dotnet test)

Lifecycle & observability

• Appendix A - 13. Agent registry (append-only log + marker cache)
• Appendix A - 14. Caused-by provenance (agent-side change traceability)
• Appendix A - 15. Cron-alerts gate
• Appendix A - 16. Deploy heartbeats + stale-worker detection
• Appendix A - 17. Lifecycle hooks (interpose on the agent runtime's events)
• Appendix A - 18. Reflection-facet substrate (tempo-gated policy nudges)
• Appendix A - 19. Tombstone commits (lifecycle close records)
• Appendix A - 20. Orchestrator-as-reactor over an event bus

Governance-doc controls

• Appendix A - 21. CLAUDE.md rule index (the governance document as a mechanism)
• Appendix A - 22. Doc-hygiene lints (index coverage, autogen provenance)
• Appendix A - 23. Epic & design-doc templates
• Appendix A - 24. Epic Definition-of-Done (Final-Opus trust-nothing re-run)
• Appendix A - 25. Mandatory snippet-table enforcement
• Appendix A - 26. Operational playbooks
• Appendix A - 27. Operator runbook skill (positive map first, symptom index fallback)
• Appendix A - 28. Enforce at the right semantic level

Models-bridge

System models

• Appendix B - 1. The agent-first MBSE harness
• Appendix B - 2. Agent-orchestration model (developer journeys)
• Appendix B - 3. Component & zone model
• Appendix B - 4. Mediator & single-writer contracts
• Appendix B - 5. Control↔substrate dependency (computed blast-radius)
• Appendix B - 6. Coverage → model-node mapping (which invariants are actually tested)
• Appendix B - 7. Deployment & tier topology
• Appendix B - 8. Domain registries
• Appendix B - 9. Drift & parity gates
• Appendix B - 10. Executable source-of-truth models
• Appendix B - 11. Formal invariant verification (temporal form → model checking)
• Appendix B - 12. Invariant-DAG execution policy (a typed Scheduler separates correctness from resource + cost)
• Appendix B - 13. Journey-criticality → test-tier placement (which host a test runs on, derived)
• Appendix B - 14. Meta-model consumption discipline (read, don't hardcode)
• Appendix B - 15. Model-driven codegen
• Appendix B - 16. Model-graded finding severity (distance-graded gate)
• Appendix B - 17. Model query surface (repo-query)
• Appendix B - 18. Service-flow / API model
• Appendix B - 19. Symbol-anchored traceability graph (derived edges)
• Appendix B - 20. Synchronization model (meta-sync)
• Appendix B - 21. User-journey model (product-goal → implementation bridge)

Product

Canonical models & seams

• Appendix C - 1. Canonical walkers (one traversal per tree)
• Appendix C - 2. Office Models ({Slides,Docs,Sheets}Model)
• Appendix C - 3. PdfModel (sole PDF mutation surface)
• Appendix C - 4. Sole raw-Redis seam (the dispatch module)
• Appendix C - 5. ServiceClient (typed cross-service seam)

Validation & conformance

• Appendix C - 6. Cross-source coherence lints
• Appendix C - 7. ContentValidator (input ⊆ output fidelity)
• Appendix C - 8. Blocking semantic lints
• Appendix C - 9. Standards / WCAG rule engine

Regression tests

• Appendix C - 10. DDT pin-trailers (doc-derived characterization)
• Appendix C - 11. Fuzz campaigns (+ auto-coverage)
• Appendix C - 12. FsCheck property tests
• Appendix C - 13. Test-onion tiers (Smoke / Lite / targeted / full)

Provenance & attribution

• Appendix C - 14. a11y_ prefix convention
• Appendix C - 15. derive-changelog (reconstruct mutations)
• Appendix C - 16. F10 mutator-stamp-wiring lint
• Appendix C - 17. Per-mutator attribution stamps

Repair vocabulary

• Appendix C - 18. Codemod-first threshold (N≳50 → AST transformer)
• Appendix C - 19. Closed remediation-verb sets
• Appendix C - 20. Typed ViolationCategory / FailureCategory enums