Mechanism census
Every mechanism, by role and family. form (the shape it takes) and Enf. (soft/hard) are the cross-cuts (see README). Families 1–5 = the agent role (the fleet + work-producing substrate); family 6 = the models-bridge (the MBSE substrate between the two); families 7–11 = the product role (the shipped artifact). All 85 entries are fully written (✅).
Read this as a construction kit. The census below lists every mechanism by role and family. For the architecture behind the list — what the environment must be able to do, and which mechanisms give it those capabilities — start at Constructing the Governed Engineering Environment. The case produced 85 concrete mechanisms; comparative analysis reduced them to 24 canonical mechanisms under 9 capabilities, with the remainder retained as variants and known uses. That page groups every entry under its capability and names the eight compositions that are strong together.
Enf. = soft/hard (see README Two independent axes: move and form): Hard = deterministic (blocking / audit / signal); Soft = probabilistic (influences, cannot block); Soft·Hard = soft guidance with a hard counterpart. The Move column (constraint/sensor/package) and Model column (is-a-model/governs-a-model/—) are the two book-thesis cross-cuts, independent of soft/hard.
Agent target
1. Context & dispatch substrate
What an agent knows and how it is launched. — family folder
| ✓ | Mechanism | Form | Move | Model | Enf. | Entry |
|---|---|---|---|---|---|---|
| ✅ | Brief-linting | validation | sensor | — | Hard | brief-linting.md |
| ✅ | Docs hierarchy + governance index | validation | package | — | Soft·Hard | docs-hierarchy.md |
| ✅ | Dynamic context injection | agent-output | constraint | — | Soft | dynamic-context-injection.md |
| ✅ | Role-typed dispatch | quality-gate | sensor | — | Hard | role-typed-dispatch.md |
2. Gates & merge-train
The path-to-production staircase for agent work. — family folder
| ✓ | Mechanism | Form | Move | Model | Enf. | Entry |
|---|---|---|---|---|---|---|
| ✅ | Pre-commit hook (3-stanza, tree-sha markers) | quality-gate | sensor | — | Hard | pre-commit-hook.md |
| ✅ | Sentinel first-commit early-abort | quality-gate | sensor | — | Hard | sentinel-first-commit.md |
| ✅ | Merge-train MIS batching | quality-gate | sensor | — | Hard | merge-train-mis-batching.md |
| ✅ | Staged deploy gates (canary → smoke → promote) | quality-gate | sensor | — | Hard | staged-deploy-gates.md |
3. Mediators & resource locks
Host-level wrappers that ration shared compute across concurrent worktrees. Three cap by cardinality — one resource-mediator pattern at three lock cardinalities (exclusive N=1 · bounded M=8 · a global mutex); the fourth caps by live pressure instead of count (an admit-before / shed-during gate on a GREEN/YELLOW/RED signal). — family folder
| ✓ | Mechanism | Form | Move | Model | Enf. | Entry |
|---|---|---|---|---|---|---|
| ✅ | Test-serializer (N=1 flock on dotnet test) | regression | sensor | — | Hard | test-serializer.md |
| ✅ | Build-serializer (M=8 semaphore) | validation | sensor | — | Hard | build-serializer.md |
| ✅ | Aggregate-compute protection (lint-all host mutex) | validation | sensor | — | Hard | aggregate-compute-protection.md |
| ✅ | Resource-pressure gating (admit before, shed during) | quality-gate | sensor | — | Hard | resource-pressure-gating.md |
4. Lifecycle & observability
Live signal surfaces over the fleet. — family folder
| ✓ | Mechanism | Form | Move | Model | Enf. | Entry |
|---|---|---|---|---|---|---|
| ✅ | Agent-registry (agent-registry.jsonl + marker cache) | observability | sensor | — | Hard (signal) | agent-registry.md |
| ✅ | Orchestrator-as-reactor over an event bus | observability | sensor | — | Hard (signal) | typed-event-bus.md |
| ✅ | Deploy heartbeats + stale-worker detection | observability | sensor | — | Hard (signal) | deploy-heartbeats.md |
| ✅ | Tombstone commits (lifecycle close records) | audit-trail | sensor | — | Hard (audit) | tombstone-commits.md |
| ✅ | Cron-alerts gate | observability | sensor | — | Hard (blocking) | cron-alerts-gate.md |
| ✅ | Lifecycle hooks (turn-stop / compaction / session-start / pre-action) | quality-gate | package | — | Soft·Hard | lifecycle-hooks.md |
| ✅ | Reflection-facet substrate (tempo-gated policy nudges) | quality-gate | package | — | Soft·Hard | reflection-facet-substrate.md |
| ✅ | Caused-by provenance (agent-side change traceability) | audit-trail | package | — | Hard | caused-by-provenance.md |
5. Governance-doc mechanisms
Documentation treated as enforced infrastructure. — family folder
| ✓ | Mechanism | Form | Move | Model | Enf. | Entry |
|---|---|---|---|---|---|---|
| ✅ | CLAUDE.md rule index + cap lint | validation | package | — | Soft·Hard | claude-md-rule-index.md |
| ✅ | Mandatory snippet-table enforcement | validation | sensor | — | Hard | mandatory-snippet-table.md |
| ✅ | Epic Definition-of-Done (Final-Opus trust-nothing re-run) | quality-gate | package | — | Hard | epic-definition-of-done.md |
| ✅ | Doc-hygiene lints (index coverage, autogen provenance) | validation | sensor | — | Hard | doc-hygiene-lints.md |
| ✅ | Operational playbooks (situation-keyed devops procedures) | agent-output | constraint | — | Soft | operational-playbooks.md |
| ✅ | Operator runbook skill (positive map + symptom index, ref-lint-kept) | agent-output | package | — | Soft·Hard | operator-runbook-skill.md |
| ✅ | Epic & design-doc templates | agent-output | package | — | Soft·Hard | epic-and-design-templates.md |
| ✅ | Independent pre-implementation design review (fresh reviewer rules on forks) | quality-gate | package | — | Soft·Hard | independent-design-review.md |
| ✅ | Enforce at the right semantic level | agent-output | constraint | governs-a-model | Soft | semantic-level-enforcement.md |
| ✅ | Self-governance (recurring failure → tasteful control, fired on a cadence) | agent-output | package | — | Soft·Hard | self-governance.md |
Models-bridge
6. System models
One MBSE method (the trunk — seventeen subject-agnostic mechanisms) reified toward the two subjects the bridge couples: the product it ships and the orchestration that builds it (a Y). Eighteen models split product-facing (service-flow, user-journey, domain-registries, composed-state-machine, process-view) · orchestration-facing (synchronization, agent-orch, governance-graph, lifecycle) · shared-spine (component-zone, concurrency, deployment — both faces); the seventeen method-mechanisms — incl. formal temporal-logic verification, coverage→model-node mapping, journey-criticality → test-tier placement, invariant-DAG execution policy, computed control↔substrate blast-radius, and the symbol-anchored traceability graph — hold them all true. These model entries are a curated sample of the portable genres, not the whole zoo: the real substrate carries on the order of sixty typed models, and these cover the ones that transfer. Rows below are grouped trunk → product → orchestration → shared. — family folder · role README
| ✓ | Mechanism | Form | Move | Model | Enf. | Entry |
|---|---|---|---|---|---|---|
| ✅ | Executable source-of-truth (data-not-code, can't drift) — trunk / method | typed-ir | package | governs-a-model | Hard | executable-source-of-truth.md |
| ✅ | Drift & parity gates (model↔reality) — trunk / method | validation | sensor | governs-a-model | Hard | drift-parity-gates.md |
| ✅ | Agent-first MBSE harness (frozen records; adopt schema, skip runtime) — trunk / method | typed-ir | package | governs-a-model | Hard | agent-first-mbse-harness.md |
| ✅ | Formal invariant verification (temporal form → model check) — trunk / method | validation | sensor | governs-a-model | Hard | formal-invariant-verification.md |
| ✅ | Coverage → model-node mapping (which invariants are tested) — trunk / method | validation | sensor | governs-a-model | Soft·Hard | coverage-model-mapping.md |
| ✅ | Journey-criticality → test-tier placement (which host a test runs on) — trunk / method | validation | package | governs-a-model | Soft·Hard | journey-criticality-test-placement.md |
| ✅ | Journey task-closure (typed terminal post-condition → derived strength) — trunk / method | validation | package | governs-a-model | Soft·Hard | journey-task-closure.md |
| ✅ | Invariant-DAG execution policy (typed Scheduler: correctness vs resource + cost) — trunk / method | typed-ir | package | governs-a-model | Soft·Hard | invariant-dag-execution-policy.md |
| ✅ | Model-driven codegen — trunk / method | validation | sensor | governs-a-model | Hard | model-driven-codegen.md |
| ✅ | Model query surface (repo-query) — trunk / method | agent-output | constraint | governs-a-model | Soft | query-surface.md |
| ✅ | Meta-model consumption (read, don't hardcode) — trunk / method | typed-ir | constraint | governs-a-model | Hard | meta-model-consumption.md |
| ✅ | Control↔substrate dependency (computed blast-radius) — trunk / method | typed-ir | package | is-a-model | Hard | control-substrate-dependency.md |
| ✅ | Symbol-anchored traceability graph (derived edges) — trunk / method | typed-ir | package | is-a-model | Hard | symbol-anchored-traceability-graph.md |
| ✅ | Model-graded finding severity (distance-graded gate) — trunk / method | quality-gate | sensor | governs-a-model | Hard | model-graded-finding-severity.md |
| ✅ | Model-derived test-obligation census (derive obligations, lint the gap) — trunk / method | validation | sensor | governs-a-model | Hard | model-derived-test-obligation-census.md |
| ✅ | Control-coverage census (controls per governance target) — trunk / method | validation | sensor | governs-a-model | Soft·Hard | control-coverage-census.md |
| ✅ | Orphan-coverage metric (walk code → governance; score the un-covered remainder) — trunk / method | validation | sensor | governs-a-model | Soft | orphan-coverage-metric.md |
| ✅ | Service-flow / API model — product-facing | typed-ir | package | is-a-model | Hard | service-flow-model.md |
| ✅ | User-journey model (product-goal → implementation) — product-facing | typed-ir | package | is-a-model | Hard | user-journey-model.md |
| ✅ | Domain registries — product-facing | typed-ir | package | is-a-model | Hard | domain-registries.md |
| ✅ | Composed state-machine model (typed lifecycles + cross-machine invariants) — product-facing | typed-ir | package | is-a-model | Hard | composed-state-machine-model.md |
| ✅ | Process view (concurrent processes, lanes, racing edges) — product-facing | typed-ir | package | is-a-model | Hard | process-view.md |
| ✅ | Typed contract surfaces (checked boundary, not a comment) — product-facing | typed-ir | package | is-a-model | Hard | typed-contract-surfaces.md |
| ✅ | Compliance data-flow model (typed sinks & edges for privacy) — product-facing | typed-ir | package | is-a-model | Hard | data-flow-model.md |
| ✅ | Timeout-budget ordering model (nested wall-clock budgets, checked) — product-facing | typed-ir | package | is-a-model | Hard | timeout-budget-ordering-model.md |
| ✅ | Required-config-per-role manifest (admission on complete env) — product-facing | typed-ir | package | is-a-model | Hard | required-config-per-role-manifest.md |
| ✅ | Telemetry-collection provenance (origin · landing · per-env coverage) — product-facing | typed-ir | package | is-a-model | Hard | telemetry-collection-provenance.md |
| ✅ | Rule-metadata registry (queryable governance metadata) — product-facing | typed-ir | package | is-a-model | Hard | rule-metadata-registry.md |
| ✅ | Synchronization model (meta-sync) — orchestration-facing | typed-ir | package | is-a-model | Hard | synchronization-model.md |
| ✅ | Agent-orchestration model (developer journeys) — orchestration-facing | typed-ir | package | is-a-model | Hard | agent-orchestration-model.md |
| ✅ | Governance graph (mechanism-interaction model) — orchestration-facing | typed-ir | package | is-a-model | Soft·Hard | governance-graph.md |
| ✅ | Lifecycle model (typed operational map → generated runbook) — orchestration-facing | typed-ir | package | is-a-model | Hard | lifecycle-model.md |
| ✅ | Component & zone model — shared spine | typed-ir | package | is-a-model | Hard | component-zone-model.md |
| ✅ | Mediator & single-writer contracts — shared spine | typed-ir | package | is-a-model | Hard | concurrency-contracts.md |
| ✅ | Deployment & tier topology — shared spine | typed-ir | package | is-a-model | Hard | deployment-topology-model.md |
Product target
7. Canonical models & seams
The one sanctioned typed model or seam per concern, each held in place by a ban-lint. — family folder
| ✓ | Mechanism | Form | Move | Model | Enf. | Entry |
|---|---|---|---|---|---|---|
| ✅ | PdfModel (sole PDF mutation surface) | typed-ir | package | is-a-model | Hard | pdf-model.md |
| ✅ | Office Models ({Slides,Docs,Sheets}Model) | typed-ir | package | is-a-model | Hard | office-models.md |
| ✅ | ServiceClient (typed cross-service seam) | bounded-service | constraint | — | Hard | service-client.md |
| ✅ | Canonical walkers (one traversal per tree) | typed-ir | package | is-a-model | Hard | canonical-walkers.md |
| ✅ | Sole raw-Redis seam (the dispatch module) | bounded-service | constraint | — | Hard | raw-redis-seam.md |
8. Validation & conformance
Deterministic pass/fail checks over the artifact. — family folder
| ✓ | Mechanism | Form | Move | Model | Enf. | Entry |
|---|---|---|---|---|---|---|
| ✅ | ContentValidator (input ⊆ output fidelity) | validation | sensor | — | Hard | content-validator.md |
| ✅ | Blocking semantic lints | validation | sensor | — | Hard | semantic-lints.md |
| ✅ | Standards / WCAG rule engine | validation | sensor | — | Hard | standards-rule-engine.md |
| ✅ | Cross-source coherence lints | validation | sensor | — | Hard | coherence-lints.md |
9. Regression tests
Repeatable behaviour-pinning bodies. — family folder
| ✓ | Mechanism | Form | Move | Model | Enf. | Entry |
|---|---|---|---|---|---|---|
| ✅ | Test-onion tiers (Smoke / Lite / targeted / full) | regression | sensor | — | Hard | test-onion-tiers.md |
| ✅ | FsCheck property tests | regression | sensor | — | Hard | property-tests.md |
| ✅ | Fuzz campaigns (+ auto-coverage) | regression | sensor | — | Hard | fuzz-campaigns.md |
| ✅ | DDT pin-trailers | regression | sensor | — | Hard | ddt-pin-trailers.md |
10. Provenance & attribution
Durable records of what the tool changed. — family folder
| ✓ | Mechanism | Form | Move | Model | Enf. | Entry |
|---|---|---|---|---|---|---|
| ✅ | Per-mutator attribution stamps | audit-trail | sensor | — | Hard (audit) | mutator-stamps.md |
| ✅ | F10 mutator-stamp-wiring lint | validation | sensor | governs-a-model | Hard | f10-wiring-lint.md |
| ✅ | derive-changelog (reconstruct mutations) | audit-trail | sensor | — | Hard (audit) | derive-changelog.md |
| ✅ | a11y_ prefix convention | repair-vocab | constraint | — | Hard | a11y-prefix.md |
11. Repair vocabulary
The bounded move-space of the remediator. — family folder
| ✓ | Mechanism | Form | Move | Model | Enf. | Entry |
|---|---|---|---|---|---|---|
| ✅ | Typed ViolationCategory / FailureCategory enums | repair-vocab | constraint | — | Hard | typed-categories.md |
| ✅ | Closed remediation-verb sets | repair-vocab | constraint | — | Hard | remediation-verbs.md |
| ✅ | Codemod-first threshold (N≳50 → AST transformer) | repair-vocab | constraint | — | Soft | codemod-first.md |
Three roles complete — 85 mechanisms across 11 families, all fully developed. Agent (30): Context & dispatch (4) · Gates & merge-train (4) · Mediators & resource locks (4) · Lifecycle & observability (8) · Governance-doc mechanisms (10, incl. the CLAUDE.md rule index meta-mechanism and the self-governance conversion loop). Models-bridge (35): the MBSE method (17 subject-agnostic mechanisms, incl. formal temporal-logic verification, coverage→model-node mapping, journey-criticality → test-tier placement, journey task-closure, invariant-DAG execution policy, computed control↔substrate blast-radius, the per-target control-coverage census, + the symbol-anchored traceability graph) reified as a Y over 18 models — product-facing 5 (service-flow · user-journey · domain-registries · composed-state-machine · process-view) · orchestration-facing 4 (synchronization · agent-orch · governance-graph · lifecycle) · shared-spine 3 (component-zone · concurrency · deployment, both faces); the MBSE substrate through which a bounded agent operates an unbounded codebase. These model entries are a curated sample of the portable genres — the substrate carries on the order of sixty typed models, and these cover the ones whose shape transfers. Product (20): Canonical models & seams (5) · Validation & conformance (4) · Regression tests (4) · Provenance & attribution (4) · Repair vocabulary (3).