Governance map

The governance map

A governance map of the catalogue: 69 controls across 11 families and three roles — agent (the fleet that produces the work), models-bridge (the typed models the fleet reasons through), and product (the shipped artifact). The catalogue is shown in four concern-specific views in the spirit of the 4+1 architectural view model; colour encodes role — human blue, agent coral, product green, environment slate.

69 controls · 11 families · three roles (agent · models-bridge · product), inside the governed engineering environment. Four views of one catalogue — each answers a different question, in the spirit of the 4+1 architectural view model (a system is understood through several concern-specific views, not one master diagram). Same palette (human=blue, agent=coral, product=green, environment=slate).

The live system these mechanisms govern: scholaccess.com · the case study: paper · the full writeups: catalogue · the codegen'd views (same mechanisms, grouped live from metadata).

How to read the encodings (all four views): node colour = target (coral=agent, blue=models-bridge, green=product); node style = enforcement (HARD solid, SOFT dashed, S·H blue-accent). Single-mechanism nodes are clickable — they link to the mechanism's writeup; hover for its one-line summary.
Relationships: ═══ counterpart (soft↔hard) ──▶ enabler (A before B) ◀── consumer (B reads A) ▼ layer (defense in depth) ◀▶ bridge (agent↔product via a model) Enforcement: Hard deterministic · Soft probabilistic · S·H soft core + hard counterpart
View 1 — Census map · logical view — the structural inventory: two target zones of family cards inside the environment; relationships shown inline (═ ─▶ ◀─)

Human architect

sets objectives · authors briefs · reviews / ratifies

▼briefs
ENGINEERING ENVIRONMENT — the governed substrate
AGENT TARGET · governs the fleet + the work-producing substrate

Context & dispatch

brief-linting docs-hierarchy dyn-ctx-injection role-typed-dispatch

Gates & merge-train

pre-commit-hook sentinel-first-commit merge-train-batching staged-deploy

Mediators & locks

test-serializer build-serializer lint-all mutex

Lifecycle & obs.

agent-registry typed-event-bus deploy-heartbeats tombstone-commits cron-alerts-gate lifecycle-hooks

Governance-docs

CLAUDE.md index ═ cap-lint snippet-table epic-DoD doc-hygiene-lints
▼feeds / is queried
MODELS-BRIDGE · typed models — agents read them ◀▶ the codebase is generated from them

Models (source-of-truth)

executable-source-of-truth agent-first-mbse-harness component-zone synchronization (meta-sync) concurrency-contracts service-flow · user-journey · deployment · domain

Kept true (map = territory)

meta-sync ═ drift-parity gates model-driven codegen ──▶ artifacts

Consumed by agents

query-surface (repo-query) read-don't-hardcode
▼governs & generates → produces the artifact
PRODUCT TARGET · governs the shipped artifact

Canonical models & seams

PdfModel ═ PDF-lib ban Office ═ openxml-ban ServiceClient canonical-walkers raw-Redis seam

Validation & conf.

ContentValidator semantic-lints WCAG-engine ═ scope-doc coherence-lints

Regression tests

test-onion tiers property tests fuzz campaigns DDT pin-trailers

Provenance & attr.

mutator-stamps ═ F10-lint derive-changelog ◀─ stamps a11y_ prefix

Repair vocabulary

typed enums remediation-verbs codemod-first
Inline edges shown: ═ counterpart pairs (e.g. rule-index═cap-lint, PdfModel═PDF-lib-ban, stamps═F10-lint) · ◀─ consumer (derive-changelog◀─stamps). Cross-family edges (enabler/consumer) are omitted here for legibility — see View 3.
View 2 — Path-to-production staircase · process view — the flow: emphasises the LAYER relationship, each stage a backstop for the last; the artifact descends through product gates

Agent controls form a descending staircase from dispatch to runtime — defense in depth, each stair catching what the last missed. The shipped artifact (green rail, below) flows through the product-control gates as it is built.

brief-time · dispatch
Context & dispatch substrate
brief-linting (structure) · dynamic-context-injection soft (content) · role-typed-dispatch · snippet-table ──▶ brief-lint
▼
commit-time
Gates — pre-commit & sentinel
pre-commit-hook (changed-file lints + unit-tier, tree-sha markers) · sentinel-first-commit (substrate health, t≈0 abort)
▼
cron · merge
Merge-train (independent-set batching)
merge-train-batching lands non-conflicting worktrees ◀── reads agent-registry
▼
deploy-time
Staged deploy gates
canary → smoke → promote · pre-launch predicate (lints green, no flaky class) · deploy-heartbeats (liveness)
▼
runtime · prod
Lifecycle & observability
typed-event-bus · cron-alerts-gate (blocks new dispatch on HIGH alert) · tombstone-commits
host tier Mediators (test-serializer N=1 · build-serializer M=8 · lint-all mutex) ration compute across all stairs, not on one.

The shipped artifact — flowing through the PRODUCT gates (green)

Canonical models (typed I/O)▶ mutator-stamps + verbs (bounded, attributed edits)▶ ContentValidator (input ⊆ output)▶ WCAG rule-engine (conformance)▶ derive-changelog
View 3 — Soft↔hard lattice · development / wiring view — positions every control by enforcement and draws the counterpart / enabler / consumer wiring: the "pattern language" view
SOFT · probabilistic (aims the fleet)HARD · deterministic (holds the line)

Soft (5)

influence, not a gate — cannot block

dynamic-context-injection reads the component model (bridge) · file-addr. rules
operational-playbooks the orchestrator consults, not improvises
semantic-level-enforcement a design-time placement judgment
codemod-first threshold a discipline; the transform is deterministic
query-surface (repo-query) agent-facing read API over the models (bridge)

Soft · Hard (3)

soft guidance kept honest by a hard counterpart

CLAUDE.md rule index ═══ cap-lint + conformance-lint
docs-hierarchy ═══ its cap / conformance lints
Epic & design-doc templates ═══ stub scaffold + DoD / section lints

Hard (46 — the bulk of the fleet)

deterministic: blocking gates · lints · mediators · signals · audit records

brief-linting · role-typed-dispatch · pre-commit-hook · sentinel · merge-train-batching · staged-deploy · test-serializer · build-serializer · lint-all-mutex · pressure-gating · agent-registry · event-bus · heartbeats · tombstones · cron-alerts-gate · lifecycle-hooks · reflection-facets · caused-by-provenance · snippet-table · epic-DoD · doc-hygiene-lints · operator-runbook-skill · bridge: executable-src-of-truth · agent-first-mbse-harness · component-zone · synchronization(meta-sync) · agent-orch(dev-journeys) · concurrency · service-flow · user-journey · deployment-topology · domain-registries · drift-parity · formal-invariant-verify · coverage→node · journey-criticality→tier · invariant-DAG-exec-policy · codegen · read-no-hardcode · control↔substrate · trace-graph · model-graded-severity · PdfModel · Office · ServiceClient · walkers · raw-Redis · ContentValidator · semantic-lints · WCAG-engine · coherence-lints · test-onion · property · fuzz · DDT · mutator-stamps · F10-lint · derive-changelog · a11y_prefix · typed-enums · remediation-verbs
The wiring, by relationship (a sample of the edges — the full list is in each entry's Related mechanisms):
═══ counterpart soft ↔ hard, or construction ↔ its detection
──▶ enabler A must exist before B
◀── consumer B reads A at runtime
▼ layer defense in depth — each a backstop for the last
◀▶ bridge the one cross-role edge — agent ↔ product via a model
The asymmetry is the finding: of 69 controls, 55 are Hard, only 5 Soft and 9 Soft·Hard. Probabilistic guidance aims agents; deterministic machinery holds the line — and every soft control sits beside a hard counterpart.
View 4 — The model bridge · +1 scenario view — the scaling story: a context-bounded agent operates a context-exceeding codebase through the typed models

The single most important structural idea: the model layer is the interface through which a context-bounded agent operates a context-exceeding codebase. It faces both ways — agents read it to reason; the codebase is generated & governed from it — and meta-sync keeps the two faces equal, or the bridge would lie.

AGENTS (the fleet)

context-bounded — cannot hold the whole codebase

dynamic-context-injection
repo-query (the query API)
role-typed-dispatch · brief-linting

reason about the codebase through the model

◀
▶

THE MODEL BRIDGE — system-models

executable documentation that cannot drift

One subject-agnostic method holds any model true, then reifies toward two subjects — a product face and an orchestration face — over one shared spine.

Drawn in full below: the method → two arms + spine.

CODEBASE / PRODUCT

context-exceeding — 430 KLOC, unbounded

NetworkPolicy · service wiring (gen)
deployment topology · tiers
boundary / seam lints

generated & governed from the model

The Y — one method, two faces, one spine

The trunk is the method itself — subject-agnostic mechanisms that hold any model true. It forks into a product-facing arm and an orchestration-facing arm, sharing one spine that faces both ways. Each name links to its mechanism.

The models-bridge Y One MBSE method forks into product-facing and orchestration-facing model arms, with a shared spine straddling both. THE METHOD · subject-agnostic the trunk — holds any model true executable-source-of-truth drift-parity-gates formal-invariant-verification coverage-model-mapping model-driven-codegen query-surface meta-model-consumption control-substrate-dependency held true by the drift-parity / meta-sync gate — the map stays equal to the territory reified toward two subjects PRODUCT-facing service-flow-model user-journey-model domain-registries the shipped artifact — what users touch ORCHESTRATION-facing synchronization-model agent-orchestration-model the fleet that produces the work SHARED SPINE · one model · both faces component-zone-model concurrency-contracts deployment-topology-model structure both faces reason through — one map, no second copy
Why now: MBSE (modelling your system as typed source-of-truth) has always been possible and rarely done — because maintaining the models and satisfying the drift gates is tedious, and humans resent the nagging. Agents dissolve that barrier: the upkeep is exactly the disciplined, repetitive work they do without complaint. So agentic engineering finally makes MBSE practical.
The same one-into-two shape, at the packaging layer: the catalogue ships as two partner skills over this one substrate — self-governance (the design-time census of controls) and self-operations (the run-time operation of the substrate they govern). A control lives in the census and is run day-to-day: one substrate, two lenses — the skill-layer echo of the method-into-two-subjects Y above. The two skills →