Appendix C — Mechanism Catalog
How to use this catalogue
This appendix is a reference manual, not a chapter. Browse it; you are not meant to read it straight through. Each mechanism appears in its smallest useful form — a diagram, a short engineering summary, and a line of metadata — so you can recognize a mechanism and find it fast.
The chip line under each mechanism tells you four things at a glance: its family, its primary concern, whether it enforces softly or hard, and whether it is essential (expected in nearly every Governed Engineering Environment) or specialized (worth adopting when your domain calls for it). Essential and specialized mark expected applicability, not quality — a specialized mechanism is not a lesser one.
When a mechanism is central to MAGE, its Engineering Note in Appendix B carries the judgment behind it, and the brick points you there. The full online catalogue holds the complete documentation, implementation guidance, and extended examples.
| Surface | Purpose | The reader's question |
|---|---|---|
| Appendix A | Reusable engineering architectures | How do these mechanisms work together? |
| Appendix B | Engineering judgment | Why would an experienced engineer build it this way? |
| Appendix C (this appendix) | Mechanism catalogue | What mechanisms exist, and where do I find them? |
| Online catalogue | Complete documentation | I want the full entry — implementation, examples, the rest. |
Reading a brick. Under each mechanism: Family · Primary concern · Enforcement · Applicability. Enforcement — Hard blocks, Soft guides, Soft·Hard ships a soft aim with a hard sensor. Applicability — Essential (expected in nearly every environment) or Specialized (adopt when the domain calls for it); this marks expected fit, not quality. A technique brick leads with the transferable pattern name and points to its advanced examples; an instance brick names the technique it folds under, loudest for the document-accessibility instances whose transferable lesson is the technique. A flagship mechanism also carries an Engineering Note link to its deeper discussion in Appendix B.
The techniques. 24 canonical techniques organize the catalogue. Every instance brick names the technique it folds under; every technique brick lists its advanced examples. Here are the techniques, by number of in-book examples:
Executable Source of Truth (19) · Staged Admission Gates (5) · Caused-By Provenance (4) · Model-Derived Assurance Coverage (4) · One Door Enforced (4) · Closed Action Vocabulary (3) · Drift / Parity Gate (3) · Mediated Resource Admission (3) · Point-of-Action Policy Delivery (2) · Read the Model, Don't Copy It (2) · Validated Dispatch (2) · Authoritative Lifecycle State (1) · Encoded Operational Judgment (1) · Fleet Observability Surface (1) · Generative Validation (1) · Governance Graph (1) · Governed Knowledge Base (1) · Composed State-Machine Model · Computed Control Blast Radius · Derived Traceability · Machine-Enforced Semantic Policy · Preservation Invariant · Re-Derived Definition of Done · Self-governance
C.1 Agent
Agent — the fleet that produces the work, and the substrate that runs it — how agents are dispatched, isolated, gated, and observed.
30 mechanisms. Each brick links to its full Gang-of-Four entry in the online catalogue; a flagship also carries a deep-dive note in Appendix B.
Technique · Validated Dispatch
Statically lint an agent's task brief before the agent is spawned, refusing to launch any brief missing the markers that make the agent's work safe and well-scoped.
Advanced examples → Epic & design-doc templates, Mandatory snippet-table enforcement
Engineering Note → B.1
Docs hierarchy + governance index (online)
An instance of: Governed Knowledge Base →
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.
An instance of: Point-of-Action Policy Delivery →
Map the files an agent is about to touch to the exact constraints that govern those files (lints, conventions, component boundaries, tests) and inject that subset into the agent's brief before it writes code, moving detection left of the cheapest CI gate.
Engineering Note → B.2
Role-typed dispatch (online)
An instance of: Closed Action Vocabulary →
Dispatch every agent under a typed role (sonnet-active / opus / lint-runner / commit-slave) that determines its LLM, isolation mode, permissions, and which gates apply, so those choices are policy-by-type, not a per-dispatch judgment call.
Merge-train MIS batching (online)
An instance of: Staged Admission Gates →
A merge-train that lands the largest set of non-conflicting agent worktrees per tick by computing a Maximum Independent Set over their file footprints, so many agents' work merges in one conflict-free pass instead of thrashing sequentially.
Pre-commit hook (3-stanza, tree-sha markers) (online)
An instance of: Staged Admission Gates →
A three-stanza pre-commit hook that runs changed-file lints and unit-tier tests and writes tree-sha-keyed marker files, so an agent's commit cannot advance to merge unless the cheap checks actually passed on exactly this tree.
Sentinel first-commit early-abort (online)
An instance of: Staged Admission Gates →
A health check on an agent's first commit that surfaces orphaned-worktree and broken-substrate failures at minute zero, before the agent burns its whole budget producing work that can never land.
Technique · Staged Admission Gates
Staged deploy gates (canary → smoke → promote)
A deploy pipeline that escalates canary → smoke → promote, blocking promotion to production until each cheaper stage passes on a traffic-free revision, so a bad build is caught before users see it, not after.
Advanced examples → Merge-train MIS batching, Pre-commit hook (3-stanza, tree-sha markers), Sentinel first-commit early-abort, Cron-alerts gate, Test-onion tiers (Smoke / Lite / targeted / full)
Engineering Note → B.3
Aggregate-compute protection (lint-all host mutex) (online)
An instance of: Mediated Resource Admission →
A one-per-host mutex on lint-all (the aggregate lint sweep) plus a one-in-flight declaration per orchestrator, so the single heaviest compute job cannot run twice on a machine or be triggered by many agents at once.
Build-serializer (M=8 semaphore) (online)
An instance of: Mediated Resource Admission →
A host-level counting semaphore (M=8) over the adjacent heavy-compute tools (dotnet build, tsc, csharp-query, jedi lints, pyright), so concurrent worktrees get parallelism up to the machine's capacity without oversubscribing it.
Resource-pressure gating (admit before, shed during)
An instance of: Mediated Resource Admission →
Govern a saturable host resource with one live pressure signal read at two layers: an admission gate deferring heavy work before dispatch, and an execution shed stopping it when pressure spikes. Heavy work is never started into, or left running on, an overloaded host.
Engineering Note → B.4
Technique · Mediated Resource Admission
Test-serializer (N=1 flock on dotnet test)
A host-level wrapper that serializes dotnet test to a single writer via an exclusive flock, so concurrent agent worktrees on one machine don't saturate I/O and interfere with each other's test runs.
Advanced examples → Aggregate-compute protection (lint-all host mutex), Build-serializer (M=8 semaphore), Resource-pressure gating (admit before, shed during)
Engineering Note → B.5
Technique · Authoritative Lifecycle State
Agent registry (append-only log + marker cache)
An append-only registry, dual-written by every lifecycle tool, that is the authoritative record of which agents are in flight, so cleanup, tombstone, and merge decisions read a fact instead of guessing from filesystem timestamps.
Advanced examples → Tombstone commits (lifecycle close records)
Engineering Note → B.6
Caused-by provenance (agent-side change traceability) (online)
An instance of: Caused-By Provenance →
Traces every agent-driven change back to the reason that caused it, drawn from a closed taxonomy and enforced as a field at the commit gate. Correlation is upgraded to causation when the cause is known at the moment of action; the trace exists to explain, not to be optimized.
Cron-alerts gate (online)
An instance of: Staged Admission Gates →
A gate that blocks new orchestrator work-dispatch while an unresolved HIGH-severity cron alert exists, forcing the orchestrator to ack or resolve it before piling more work onto a possibly-broken substrate.
Deploy heartbeats + stale-worker detection (online)
An instance of: Fleet Observability Surface →
Periodic [heartbeat] phase=X elapsed=Ns emissions from long-running deploys, plus a stale-worker sweep, so a hung deploy or worker is distinguishable from a merely slow one.
Technique · Point-of-Action Policy Delivery
Lifecycle hooks (interpose on the agent runtime's events)
Bind a script to the agent runtime's lifecycle events (turn-stop, pre-compaction, session-start, before-a-tool-call) so a step the operator keeps omitting at runtime fires deterministically, whether or not anyone remembered it.
Advanced examples → Dynamic context injection, Reflection-facet substrate (tempo-gated policy nudges)
Engineering Note → B.7
Reflection-facet substrate (tempo-gated policy nudges) (online)
An instance of: Point-of-Action Policy Delivery →
Consolidate an operator's policy-reflection nudges into one tempo-gated substrate: a registry of facets, each checking context against a single policy dimension it references, never copies. The family emits at most one reflection per window, preventing alarm fatigue.
Tombstone commits (lifecycle close records) (online)
An instance of: Authoritative Lifecycle State →
A tombstone commit written at a worktree's branch tip that durably records its lifecycle close and disposition (cherry-picked / declared-skipped), so cleanup can prove a worktree is safely reclaimable instead of guessing.
Technique · Fleet Observability Surface
Orchestrator-as-reactor over an event bus
A structured event bus with a closed topic registry and a companion playbook, over which substrate emits lifecycle and health events. It turns the orchestrator into a reactor that reads fleet health from a queryable signal surface and responds with a prescribed action.
Advanced examples → Deploy heartbeats + stale-worker detection
Engineering Note → B.8
Technique · Governed Knowledge Base
CLAUDE.md rule index (the governance document as a mechanism)
Treat the top-level governance document as enforced infrastructure: a stable-numbered rule index loaded into every agent's boot context. It is held honest by its own enforcement counterpart, a size-cap lint plus a rule-conformance lint, so it cannot silently rot.
Advanced examples → Docs hierarchy + governance index
Engineering Note → B.9
Doc-hygiene lints (index coverage, autogen provenance) (online)
An instance of: Drift / Parity Gate →
A family of lints that hold documentation to mechanical checks (index coverage, auto-generated-file provenance headers, cross-reference validity), so docs cannot silently drift, go stale, or be hand-edited where they will be overwritten.
Epic & design-doc templates (online)
An instance of: Validated Dispatch →
Fixed section-templates for the two core planning artifacts, Epics and design docs. Every effort uses the same required sections: scope, phase decomposition, second-order dynamics, definition-of-done, observability. The template drives the work, not documents it after.
Technique · Re-Derived Definition of Done
Epic Definition-of-Done (Final-Opus trust-nothing re-run)
An Epic-close gate mandating a "trust nothing" Final-Opus review that re-runs every owned pin test and lint at HEAD, rather than trusting phase markers or prior claims, so an Epic cannot close on stale or rotted assertions.
Engineering Note → B.10
Independent pre-implementation design review (online)
Before any implementation phase, a fresh reviewer that did not author the design re-derives it from the code, verifies its load-bearing claims empirically, and rules on the open design forks — the reviewer wins conflicts, and implementation proceeds only on the ratified design (our instance: every founding design earns one second, independent review pass before…
Mandatory snippet-table enforcement (online)
An instance of: Validated Dispatch →
A registry of mandatory agent-brief snippets (PATH export, commit-cadence, worktree discovery, submodule check, …) whose presence is asserted at dispatch by brief-linting, so every dispatched brief carries the safety and context boilerplate it needs.
Technique · Encoded Operational Judgment
A library of documented, devops-themed decision procedures that agents and orchestrators consult instead of reasoning from scratch. Recurring operational situations — a broken deploy, a wedged cron, a stuck worktree — get a consistent, incident-tested response.
Advanced examples → Operator runbook skill (positive map first, symptom index fallback)
Engineering Note → B.11
Operator runbook skill (positive map first, symptom index fallback) (online)
An instance of: Encoded Operational Judgment →
A loadable skill giving an operating agent the positive map of how the substrate works and its healthy baselines first, with a symptom-to-resolving-doc catalog as fallback. Its content is generated from a structured source of truth, kept honest by a reference-validity lint.
Technique · Self-governance
Self-governance (detect your own recurring issues; convert each into a tasteful control)
Give the system permission to govern the way it is governed: detect recurring issues and introduce proportionate controls that prevent them, rather than re-patching each instance. Classify the failure class, then add the smallest guardrail that kills it, on a cadence.
Engineering Note → B.12
Enforce at the right semantic level (online)
Place a check at the level where the property it verifies first becomes visible, not the cheapest point. A check fired too early can't see the property, or rejects a legitimate partial state. Example: check model-code drift when an agent finishes a task, not at each commit.
C.2 Models-bridge
Models-bridge — the structured models the fleet reasons through — the shared map a bounded agent uses to operate a codebase larger than its context.
35 mechanisms. Each brick links to its full Gang-of-Four entry in the online catalogue; a flagship also carries a deep-dive note in Appendix B.
The agent-first MBSE harness (online)
An instance of: Executable Source of Truth →
Builds the structured system models as a thin, hand-rolled harness over plain frozen records: adopt a modeling genre's vocabulary and schema per view, but skip its runtime. Build-time checks then keep the model equal to the code it describes.
Agent-orchestration model (developer journeys) (online)
An instance of: Executable Source of Truth →
Models the agent fleet and the orchestrator's loop with the same method applied to the product: structured lifecycle states and seams, invariants whose tier is derived, not hand-set. The substrate producing the software becomes as checkable as the software itself.
Component & zone model (online)
An instance of: Executable Source of Truth →
A typed catalogue of every component's code zone (focus-dirs, tags, boundary kind, external seams, read surfaces), so "which component owns this file, and what may touch it" is a queried fact, not a guess.
Technique · Composed State-Machine Model
Composed state-machine model (typed lifecycles + cross-machine invariants)
Model a concurrent lifecycle as structured state machines running at once, and name cross-machine predicates as first-class invariants. Derive each invariant's check from its shape: safety gets exhaustive verification, liveness a temporal check, linear a property test.
Engineering Note → B.13
Technique · Derived Traceability
Symbol-anchored traceability graph (derived edges)
Links every model to its lint, code entry-point, proof, and registry as a structured graph whose edges are derived obligations a lint re-checks, anchored to resolvable symbols rather than line numbers. Derived edges defend against drift; snapshotted ones decay.
Engineering Note → B.22
Mediator & single-writer contracts (online)
An instance of: Executable Source of Truth →
Typed registries of the system's concurrency contracts: which subprocess invocations are serialized by a mediator, and which state-mutation functions are single-writer / monopoly. "Who may run this, and how many at once" becomes declared and enforceable.
Control-coverage census (controls per governance target) (online)
An instance of: Governance Graph →
Classifies every governance control by which complementary control target it guards, derived from the control's own code anchor rather than hand-declared. Rolls the control set up per target, so a target with zero controls or only soft aims surfaces as a re-derived coverage gap.
Technique · Computed Control Blast Radius
Control↔substrate dependency (computed blast-radius)
Each control declares the substrate assumption it bakes in as structured metadata, so "what depends on this, and what breaks if I change it" becomes a computed query, not a grep-and-read. This surfaces the blast radius before any cross-cutting substrate change.
Engineering Note → B.14
Coverage → model-node mapping (which invariants are actually tested)
An instance of: Model-Derived Assurance Coverage →
Projects test coverage onto a model's own nodes — its states, seams, and invariants — so "is this tested?" is a queried fact, not a guess from a line-coverage percentage. An invariant node with no covering test is a visible gap that becomes the next test to write.
Engineering Note → B.15
Compliance data-flow model (typed sinks and edges for privacy reasoning) (online)
An instance of: Executable Source of Truth →
Model where governed data can flow as a structured graph of sinks and edges. A question like where personal data lands, and whether it can all be erased, is answered by walking the model, not by grepping code. An unmodeled sink is a build finding, not an audit surprise.
Deployment & tier topology (online)
An instance of: Executable Source of Truth →
Structured models of where things run and how they layer (the managed-deployment topology, each service's tier class, and the agent-substrate's layer boundaries), so deploy scripts and layering lints reason about a declared topology, not scattered constants.
Domain registries (online)
An instance of: Executable Source of Truth →
A set of frozen, typed registries for the system's domain facts (the supported filetypes, the WCAG coverage gaps, the periodic-GC cron entries, the UX write-authority surfaces, the competitor set, the CLAUDE.md rule metadata), each the single source of truth for its slice.
Technique · Drift / Parity Gate
The fleet of lints and tests that enforce bidirectional parity between each model and reality (every model row ↔ a real thing on disk, and every real thing ↔ a model row), so the models cannot drift.
Advanced examples → Doc-hygiene lints (index coverage, autogen provenance), Cross-source coherence lints, DDT pin-trailers (doc-derived characterization)
Engineering Note → B.16
Technique · Executable Source of Truth
Executable source-of-truth models
Model the system as typed data that tools read on every run and generate real artifacts from. The model becomes executable documentation that cannot drift, and the codebase becomes operable by a context-bounded agent.
Advanced examples → The agent-first MBSE harness, Agent-orchestration model (developer journeys), Component & zone model, Mediator & single-writer contracts, Compliance data-flow model (typed sinks and edges for privacy reasoning), Deployment & tier topology, Domain registries, Invariant-DAG execution policy (a typed Scheduler separates correctness from resource + cost), Lifecycle model (typed operational map → generated runbook), Model-driven codegen, Process view (concurrent processes, lanes, and racing edges), Required-configuration-per-role manifest (admission policy on complete env), Rule-metadata registry (machine-readable metadata on governance rules), Service-flow / API model, Synchronization model (meta-sync), Telemetry-collection provenance (per-stream origin, landing, per-env coverage), Timeout-budget ordering model (nested wall-clock budgets, checked), Typed contract surfaces (the contract is a checked model, not a comment), User-journey model (product-goal → implementation bridge)
Engineering Note → B.17
Formal invariant verification (temporal form → model checking)
An instance of: Model-Derived Assurance Coverage →
Gives every model invariant a temporal form — safety (always holds) or liveness (eventually leads to) — and uses that form to derive which exhaustive checker verifies it. An invariant is proven by the method its shape demands, a state-space check rather than a sampled test.
Engineering Note → B.18
Technique · Governance Graph
Governance graph (mechanism-interaction model)
Model the fleet's governance mechanisms as a structured graph: each mechanism a node tagged by its firing event and the resources it reads, writes, or locks. Each edge marks a conflict between two mechanisms over one resource, caught by construction, not in production.
Advanced examples → Control-coverage census (controls per governance target)
Engineering Note → B.19
Invariant-DAG execution policy (a typed Scheduler separates correctness from resource + cost) (online)
An instance of: Executable Source of Truth →
Keeps a build/deploy dependency graph a statement of correctness only, pushing concurrency and cost concerns into a Scheduler that reads a per-host profile. Edges carry an intent tag — correctness, cost-gate, or load — separating a dependency from a resource accommodation.
Journey-criticality → test-tier placement (which host a test runs on, derived) (online)
An instance of: Model-Derived Assurance Coverage →
A journey's criticality is the single input that derives which environment tier its tests run in, never hand-drawn. A coverage floor requires every high-criticality journey-part to carry a test in the fast local tier, so a green local run means the major paths work.
Journey task-closure (type the terminal post-condition, derive its strength) (online)
An instance of: Model-Derived Assurance Coverage →
Express a journey's terminal post-condition as a boolean formula over reusable, observable leaf-predicates. Derive a closure-strength verdict from it, and require every major journey to reach TASK_CLOSED. A journey test can no longer pass while the task is broken.
Lifecycle model (typed operational map → generated runbook) (online)
An instance of: Executable Source of Truth →
Models how the operating substrate works as a structured object: each lifecycle a named subsystem with a healthy-state predicate, each symptom a row keyed to its lifecycle. The operator's runbook is generated from this model, so it cannot drift from the system it describes.
Technique · Read the Model, Don't Copy It
Meta-model consumption discipline (read, don't hardcode)
Consume the models by querying them at runtime, never by embedding a hardcoded snapshot — so a lint, test, or brief always reasons from the live model, and a copied-out value can't drift behind the model it was copied from.
Advanced examples → Model-graded finding severity (distance-graded gate), Model query surface (repo-query)
Engineering Note → B.20
Technique · Model-Derived Assurance Coverage
Model-derived test-obligation census (derive what should be tested, lint the gap)
Derives what should be tested — seams to fuzz, failure edges needing injection tests, invariants needing checkers — directly from the structured models. Lints the gap between that obligation set and the tests that exist, turning missing coverage into a named finding.
Advanced examples → Coverage → model-node mapping (which invariants are actually tested), Formal invariant verification (temporal form → model checking), Journey-criticality → test-tier placement (which host a test runs on, derived), Journey task-closure (type the terminal post-condition, derive its strength)
Engineering Note → B.21
Model-driven codegen (online)
An instance of: Executable Source of Truth →
Generate real artifacts from the models — NetworkPolicy, service catalog, env wiring, public-API docs, competitor catalog, wire-contract types, docker — each carrying a provenance header, so the model drives the system (not merely describes it) and hand-edits are caught.
Model-graded finding severity (distance-graded gate) (online)
An instance of: Read the Model, Don't Copy It →
Grades each lint finding's severity — block, warn, or silence — by its distance, in a structured component model, from the files the commit actually changed. One central join computes this over every finding at check time, rather than each lint scoping itself.
Orphan-coverage metric (walk code → governance; score the un-covered remainder) (online)
Point a tracer at the code and ask, for each governance-relevant site, "does any model row or any control node reach this?" Score the remainder — the orphans, sites nothing governs — as a rate, cluster them, and treat each cluster as a candidate for a new model or a new control. It walks the…
Process view (concurrent processes, lanes, and racing edges) (online)
An instance of: Executable Source of Truth →
Project a system's concurrency as an explicit process view: the processes running at once, the lanes they run in, and the racing edges where two touch shared state simultaneously. It answers what is live at once and where it can collide, not what transitions are legal.
Model query surface (repo-query) (online)
An instance of: Read the Model, Don't Copy It →
One canonical, self-describing query API over all the models — a repo-query CLI with deterministic --json subcommands — so an agent reads the system's compressed truth through a tool rather than parsing raw files, and the tool itself documents how the models load.
Required-configuration-per-role manifest (admission policy on complete env) (online)
An instance of: Executable Source of Truth →
Declares, per operating role and plane, the complete configuration a process must have to start, as a structured manifest an admission check reads. A process whose environment is missing any required setting is refused at launch rather than failing quietly deep in a request.
Rule-metadata registry (machine-readable metadata on governance rules) (online)
An instance of: Executable Source of Truth →
Attaches machine-readable metadata — identifier, scope, severity, enforcing check, detail location — to each governance rule, then extracts it into a queryable registry. Questions like "which rules lack an enforcing lint" become registry queries, not manual reads.
Service-flow / API model (online)
An instance of: Executable Source of Truth →
A Backstage-dialect model of the service-oriented architecture — every service, its APIs, inter-service auth, URL wiring, and frontend trees — that is the source of truth the deployment, NetworkPolicy, and API docs are generated from and validated against.
Synchronization model (meta-sync)
An instance of: Executable Source of Truth →
A typed registry that models the system's synchronization behaviour — every OS-level lock (flock/lockf), which shared resource it guards, and the required acquisition ordering — so concurrency contracts are declared and checkable, not tribal.
Engineering Note → B.23
Telemetry-collection provenance (per-stream origin, landing, per-env coverage) (online)
An instance of: Executable Source of Truth →
Records each telemetry stream's provenance — origin, landing sink, and which environments actually collect it — as a checkable fact, not an assumption. This catches the silent failure of a metric that exists in production but is quietly missing elsewhere.
Timeout-budget ordering model (nested wall-clock budgets, checked) (online)
An instance of: Executable Source of Truth →
Gathers a system's scattered wall-clock budgets — timeouts, deadlines, lock waits, retry windows — into one surface. States the required nesting order as a machine-checkable invariant, so a timeout raised past its container is a build finding, not a production hang.
Typed contract surfaces (the contract is a checked model, not a comment) (online)
An instance of: Executable Source of Truth →
Turns the contract between two parties — an API and its clients, a CLI and the scripts parsing its output — into a checked model instead of a shared assumption. A breaking change then reddens a build gate instead of silently breaking the other side at runtime.
User-journey model (product-goal → implementation bridge) (online)
An instance of: Executable Source of Truth →
Model the product's user journeys as first-class structured entities: an actor pursuing a goal through ordered steps, each boundary-crossing step joined to the endpoint it calls. This becomes a queryable model, grafted into the existing service-architecture dialect.
C.3 Product
Product — the shipped artifact itself — its canonical seams, its content-fidelity validation, and its conformance controls.
20 mechanisms. Each brick links to its full Gang-of-Four entry in the online catalogue; a flagship also carries a deep-dive note in Appendix B.
Canonical walkers (one traversal per tree) (online)
A document-accessibility instance of the technique: One Door Enforced →
Give each tree exactly one canonical walker that owns its traversal invariants, and route all traversal through it instead of ad hoc recursion, so those invariants live in one place (our instances: one walker for the PDF structure tree, one for the checking pass, one per Office part: PdfStructTreeWalker, the RuleWalkers, DocxTopLevelPartWalker).
Office Models ({Slides,Docs,Sheets}Model) (online)
A document-accessibility instance of the technique: One Door Enforced →
Route all remediation of a format family through one structured model, with raw library access (and raw string-matching into the serialized form) banned by lint. The same construction+ban-lint pattern as pdf-model, on a second object model (our instance: {Slides,Docs,Sheets}Model over DocumentFormat.OpenXml).
Technique · One Door Enforced
PdfModel (sole PDF mutation surface)
Route all reads and writes of a complex file format through one structured model, with raw access to the underlying library banned by a lint, so the structure is compiler-checked and every mutation passes through a surface that encodes the format's invariants (our instance: PdfModel over the canonical PDF library).
Advanced examples → Canonical walkers (one traversal per tree), Office Models ({Slides,Docs,Sheets}Model), Sole raw-Redis seam (the dispatch module), ServiceClient (typed cross-service seam)
Engineering Note → B.24
Sole raw-Redis seam (the dispatch module) (online)
An instance of: One Door Enforced →
Confine all raw-Redis access to one module, with every queue key declared there, so the queue's atomicity and schema invariants live in exactly one lint-enforced place.
ServiceClient (typed cross-service seam) (online)
An instance of: One Door Enforced →
Route all cross-service HTTP through one typed client whose BinaryIO signature makes the file-path-over-wire bug class impossible at the type level; direct requests.post against another service is banned.
Cross-source coherence lints (online)
An instance of: Drift / Parity Gate →
Lints that assert two or more independent sources agree (config record ↔ sample JSON, registry ↔ its consumers, enum ↔ its uses), catching drift between sources that each look valid on their own.
Technique · Preservation Invariant
ContentValidator (input ⊆ output fidelity)
A deterministic gate asserting that every piece of the user's original content survives remediation (input content ⊆ output content), run in production, with a per-pass variant in staging that pinpoints which pass dropped content (our instance: the ContentValidator fidelity gate).
Engineering Note → B.25
Technique · Machine-Enforced Semantic Policy
A fleet of blocking semantic lints over the tool's own source (banned APIs, silent-catch bans, Console.WriteLine-in-prod, typed-seam violations) that fail the build on domain-invariant violations the compiler and review can't catch.
Engineering Note → B.26
Standards / WCAG rule engine (online)
A document-accessibility instance of the technique: Conformance-to-External-Spec Engine →
A rule engine that maps each finding to the exact external-standard clause it closes, turning "does this conform?" into a deterministic, standards-grounded predicate rather than a judgement call (our instance: the WCAG 2.1 AA / Section 508 / PDF-UA accessibility rule engine).
DDT pin-trailers (doc-derived characterization) (online)
An instance of: Drift / Parity Gate →
Doc-derived tests that characterize current behaviour before structural churn, each carrying a provenance trailer (audited / source / pins) so it is regenerated when the source it cites is edited.
Technique · Generative Validation
Fuzz campaigns (+ auto-coverage)
Campaigns that feed malformed and adversarial inputs to the tool to find crashes and corruption, with coverage collected automatically, plus an RCA discipline that fixes to the spec, not the failing seed.
Advanced examples → FsCheck property tests
Engineering Note → B.27
FsCheck property tests (online)
An instance of: Generative Validation →
Property-based tests that assert invariants (round-trip, combinatorial) over machine-generated inputs, catching bugs in the input space that example-based tests never reach.
Test-onion tiers (Smoke / Lite / targeted / full) (online)
An instance of: Staged Admission Gates →
A tiered test suite that stratifies ~4000+ tests by cost and coverage (Smoke, Lite, targeted, full) so cheap tiers gate fast iterations and the full tier gates deploy, pinning behaviour at the right price per decision.
a11y_ prefix convention (online)
A document-accessibility instance of the technique: Caused-By Provenance →
A reserved naming prefix that marks tool-inserted, invisible-to-author artifacts (user-visible insertions keep ordinary names), so inserted content is distinguishable from authored content and a validator can cover it by prefix (our instance: the a11y_ prefix + InsertedContentValidator).
derive-changelog (reconstruct mutations) (online)
A document-accessibility instance of the technique: Caused-By Provenance →
A command that reconstructs the document's mutation history from the embedded stamp registry, turning the attribution stamps into a readable, attributed ChangeLog after the fact.
F10 mutator-stamp-wiring lint (online)
A document-accessibility instance of the technique: Caused-By Provenance →
A lint that fails the build if any mutator verb in the Model Primitives lacks stamp wiring, so a new mutator cannot land producing unattributable mutations.
Technique · Caused-By Provenance
Per-mutator attribution stamps
Every remediation verb that mutates a document embeds an attribution stamp in the artifact itself, written through one sanctioned stamp-writer per format. This makes every change durably attributable and the mutation history reconstructable after the fact.
Advanced examples → Caused-by provenance (agent-side change traceability), a11y_ prefix convention, derive-changelog (reconstruct mutations), F10 mutator-stamp-wiring lint
Engineering Note → B.28
Codemod-first threshold (N≳50 → AST transformer) (online)
An instance of: Closed Action Vocabulary →
For a large mechanical backlog (N≳50 sites with a deterministic fix shape), author one AST-level transformer instead of dispatching N agents, bounding how large mechanical changes are made.
Technique · Closed Action Vocabulary
Route the remediator's mutations through a bounded, named set of typed verbs (a closed typed-mutator layer) rather than free-form edits, so the move-space is enumerable and every move can be stamped, validated, and policy-checked (our instance: the document models' Primitives).
Advanced examples → Role-typed dispatch, Codemod-first threshold (N≳50 → AST transformer), Typed ViolationCategory / FailureCategory enums
Engineering Note → B.29
Typed ViolationCategory / FailureCategory enums (online)
An instance of: Closed Action Vocabulary →
Replace free-form failure strings with typed enums, so the categorical move-space is a closed, enumerable set that the compiler and lints can check for exhaustive handling.
Reference: every mechanism
The 29 flagship patterns are printed in full below; all 85 mechanisms — including these — are online in the web catalogue at https://davisjam.github.io/model-based-agentic-software-engineering. A flagship row links to its page in this appendix; a web-only mechanism links to its live catalogue entry, marked (online).
Agent
Context & dispatch substrate
- Appendix B - 1. Brief-linting
- Docs hierarchy + governance index (online)
package· under Governed Knowledge Base - Appendix B - 2. Dynamic context injection
- Role-typed dispatch (online) · under Closed Action Vocabulary
Gates & merge-train
- Merge-train MIS batching (online) · under Staged Admission Gates
- Pre-commit hook (3-stanza, tree-sha markers) (online) · under Staged Admission Gates
- Sentinel first-commit early-abort (online) · under Staged Admission Gates
- Appendix B - 3. Staged deploy gates (canary → smoke → promote)
Mediators & resource locks
- Aggregate-compute protection (
lint-allhost mutex) (online) · under Mediated Resource Admission - Build-serializer (M=8 semaphore) (online) · under Mediated Resource Admission
- Appendix B - 4. Resource-pressure gating (admit before, shed during)
- Appendix B - 5. Test-serializer (N=1 flock on
dotnet test)
Lifecycle & observability
- Appendix B - 6. Agent registry (append-only log + marker cache)
- Caused-by provenance (agent-side change traceability) (online)
package· under Caused-By Provenance - Cron-alerts gate (online) · under Staged Admission Gates
- Deploy heartbeats + stale-worker detection (online) · under Fleet Observability Surface
- Appendix B - 7. Lifecycle hooks (interpose on the agent runtime's events)
package - Reflection-facet substrate (tempo-gated policy nudges) (online)
package· under Point-of-Action Policy Delivery - Tombstone commits (lifecycle close records) (online) · under Authoritative Lifecycle State
- Appendix B - 8. Orchestrator-as-reactor over an event bus
Governance-doc controls
- Appendix B - 9. CLAUDE.md rule index (the governance document as a mechanism)
package - Doc-hygiene lints (index coverage, autogen provenance) (online) · under Drift / Parity Gate
- Epic & design-doc templates (online)
package· under Validated Dispatch - Appendix B - 10. Epic Definition-of-Done (Final-Opus trust-nothing re-run)
package - Independent pre-implementation design review (online)
package - Mandatory snippet-table enforcement (online) · under Validated Dispatch
- Appendix B - 11. Operational playbooks
- Operator runbook skill (positive map first, symptom index fallback) (online)
package· under Encoded Operational Judgment - Appendix B - 12. Self-governance (detect your own recurring issues; convert each into a tasteful control)
package - Enforce at the right semantic level (online) · under P8 (Enforce at the right semantic level)
Models-bridge
System models
- The agent-first MBSE harness (online)
package· under Executable Source of Truth - Agent-orchestration model (developer journeys) (online)
package· under Executable Source of Truth - Component & zone model (online)
package· under Executable Source of Truth - Appendix B - 13. Composed state-machine model (typed lifecycles + cross-machine invariants)
package - Mediator & single-writer contracts (online)
package· under Executable Source of Truth - Control-coverage census (controls per governance target) (online) · under Governance Graph
- Appendix B - 14. Control↔substrate dependency (computed blast-radius)
package - Appendix B - 15. Coverage → model-node mapping (which invariants are actually tested)
- Compliance data-flow model (typed sinks and edges for privacy reasoning) (online)
package· under Executable Source of Truth - Deployment & tier topology (online)
package· under Executable Source of Truth - Domain registries (online)
package· under Executable Source of Truth - Appendix B - 16. Drift & parity gates
- Appendix B - 17. Executable source-of-truth models
package - Appendix B - 18. Formal invariant verification (temporal form → model checking)
- Appendix B - 19. Governance graph (mechanism-interaction model)
package - Invariant-DAG execution policy (a typed Scheduler separates correctness from resource + cost) (online)
package· under Executable Source of Truth - Journey-criticality → test-tier placement (which host a test runs on, derived) (online)
package· under Model-Derived Assurance Coverage - Journey task-closure (type the terminal post-condition, derive its strength) (online)
package· under Model-Derived Assurance Coverage - Lifecycle model (typed operational map → generated runbook) (online)
package· under Executable Source of Truth - Appendix B - 20. Meta-model consumption discipline (read, don't hardcode)
- Appendix B - 21. Model-derived test-obligation census (derive what should be tested, lint the gap)
- Model-driven codegen (online) · under Executable Source of Truth
- Model-graded finding severity (distance-graded gate) (online) · under Read the Model, Don't Copy It
- Orphan-coverage metric (walk code → governance; score the un-covered remainder) (online)
- Process view (concurrent processes, lanes, and racing edges) (online)
package· under Executable Source of Truth - Model query surface (
repo-query) (online) · under Read the Model, Don't Copy It - Required-configuration-per-role manifest (admission policy on complete env) (online)
package· under Executable Source of Truth - Rule-metadata registry (machine-readable metadata on governance rules) (online)
package· under Executable Source of Truth - Service-flow / API model (online)
package· under Executable Source of Truth - Appendix B - 22. Symbol-anchored traceability graph (derived edges)
package - Appendix B - 23. Synchronization model (meta-sync)
package - Telemetry-collection provenance (per-stream origin, landing, per-env coverage) (online)
package· under Executable Source of Truth - Timeout-budget ordering model (nested wall-clock budgets, checked) (online)
package· under Executable Source of Truth - Typed contract surfaces (the contract is a checked model, not a comment) (online)
package· under Executable Source of Truth - User-journey model (product-goal → implementation bridge) (online)
package· under Executable Source of Truth
Product
Canonical models & seams
- Canonical walkers (one traversal per tree) (online)
package· under One Door Enforced - Office Models ({Slides,Docs,Sheets}Model) (online)
package· under One Door Enforced - Appendix B - 24. PdfModel (sole PDF mutation surface)
package - Sole raw-Redis seam (the dispatch module) (online) · under One Door Enforced
- ServiceClient (typed cross-service seam) (online) · under One Door Enforced
Validation & conformance
- Cross-source coherence lints (online) · under Drift / Parity Gate
- Appendix B - 25. ContentValidator (input ⊆ output fidelity)
- Appendix B - 26. Blocking semantic lints
- Standards / WCAG rule engine (online) · under Conformance-to-External-Spec Engine
Regression tests
- DDT pin-trailers (doc-derived characterization) (online) · under Drift / Parity Gate
- Appendix B - 27. Fuzz campaigns (+ auto-coverage)
- FsCheck property tests (online) · under Generative Validation
- Test-onion tiers (Smoke / Lite / targeted / full) (online) · under Staged Admission Gates
Provenance & attribution
a11y_prefix convention (online) · under Caused-By Provenancederive-changelog(reconstruct mutations) (online) · under Caused-By Provenance- F10 mutator-stamp-wiring lint (online) · under Caused-By Provenance
- Appendix B - 28. Per-mutator attribution stamps
Repair vocabulary
- Codemod-first threshold (N≳50 → AST transformer) (online) · under Closed Action Vocabulary
- Appendix B - 29. Closed remediation-verb sets
- Typed
ViolationCategory/FailureCategoryenums (online) · under Closed Action Vocabulary