The GMAA Engine Map

How the engine implements the specification. Engine package v2.5.7 · canon pin v1.6.1 · cite by version. Canonical home: gmaa.ai. Verification fingerprints for the release are on gmaa.ai/versions.html.

Who this is for. Anyone evaluating GMAA for a project, and anyone who has downloaded the engine and wants the map before the tree. The specification states the law; the engine is the machinery that enforces it. Reading the law alone answers "what must hold" but not "what runs, what fires it, and what it costs to operate," and an evaluation made on the law alone tends to overprice the discipline and misread designed absences as gaps. This document is the missing middle: every file in the release, grouped into ten functional areas, each anchored to its canon section, with the execution wiring that shows what invokes what and when.

Three facts an evaluation can miss reading the specification alone. First, the engine creates its own repository at instantiation: no prior version control is required, and an ungoverned workspace is the starting condition adoption is designed for, not a blocker to it. Second, empty substrate slots are a designed posture, not gaps: a project with no database, no API, and no side-effectful backend leaves the C-DB and C-GATE slots unfilled, and SLOTS.md is the inventory of exactly those decisions. Third, the discipline is wired, not manual: hooks fire at every commit, a guard fires on every shell call, probes run on schedule, and seat files are generated rather than maintained, so the recurring human act is one ratification decision per set, and that decision is the product rather than the overhead.

Method. The canon (v1.6.1, all sections) was read whole, then every one of the 102 files in the package plus the 4 loose release files beside the zip was inventoried and its header, purpose block, or full body read. Every file is assigned to exactly one functional area below; a coverage account at the foot proves nothing was orphaned. Where a file is machinery, the map states what invokes it and when it fires, because a gate is defined as much by its trigger as by its logic.

The shape of the whole thing in one paragraph. The canon states one correction: authorize the set, not only the change, with an integrator agent assessing and an independent human ratifying. The engine implements that correction as ten cooperating layers: an identity layer that makes a seat something you derive rather than assert; a single-writer enforcement layer that makes the spine physically uncommittable by anyone but foundation; the set-authorization machinery itself, which is the thesis in executable form; a work lifecycle that moves a change from dispatch to independently audited closure; a merge and reap layer that keeps worktrees honest; a relay layer that keeps transport off the participants; a standing audit layer that probes invariants instead of asserting them; an instantiation and upgrade layer that turns the blank template into a project and keeps it upgradeable; the harness wiring that makes the runtime itself enforce the above; and the release integrity envelope around all of it.

1 The specification layer, the law everything below implements

Canon anchor: the whole document.

The canon's own instantiation checklist (§12) is the adopter's entry point into it; section 9 below carries the files that walk it.

2 Identity and the seat lifecycle

Canon anchors: §1.0 definitions, §1.1 seats and surfaces, §2 ONE-SESSION-ONE-SEAT, §7.1 Boot-0, §7.2 provisioning, §7.3 project-qualified identity.

The design law of this area: identity comes from location, is derived on both sides of the spawn boundary, and the two derivations must agree or the seat halts. A hand-made folder cannot mint a seat because it has no committed stamp.

The agent-definition roster (.claude/agents/), canon §1.0 "agent definition" and §1.3 subagent classes. These are the qualifications a session loads to become a fit occupant:

One file in this area is deliberately absent: seats.yaml is not shipped. It is the adopter's roster and spine-path declaration, created at instantiation (SLOTS.md row 49), spine-owned and set-gated once it exists, and read at HEAD by the enforcement layer below.

3 Single-writer enforcement and spine protection

Canon anchors: §1.1 single-writer invariant, §8 permission architecture, Appendix A wrong-authorization-unit and FIX-SURFACE-DIVERGENCE.

This area answers one question mechanically: can anyone but foundation land bytes on the spine? The answer is layered so that no single bypass defeats it.

4 Set-level authorization, the thesis in executable form

Canon anchors: §4 pending-set ledger and apply-boundary set-evaluation, §10 ratification flow. Contracts: C-SET-AUTHORIZATION.md, C-RATIFICATION-PACKET.md, COST-CAPS.md.

This is the machinery the whole architecture exists to carry: the set, not only the change, is what gets authorized, with foundation assembling and assessing and the independent human ratifying.

Its dedicated enforcement, probed rather than asserted:

5 The work lifecycle, dispatch to audited closure

Canon anchors: §3 discipline rules, §4 receipts ledger. Schemas: the schema/ directory whole.

6 Merge, reap, and lane currency

Canon anchor: §7.2 retirement as the mirror event. Contract: SPEC-REAPER.md.

7 Communication, relay, and escalation

Canon anchor: §5 communication architecture: transport lives outside every participant. Contract: SPEC-DOORBELL.md. Protocol: _knowledge/COORDINATION.md.

8 Standing audit and enforcement

Canon anchor: §4 enforcement mechanisms: invariants are probed, not asserted, the component most governance frameworks lack.

9 Instantiation, adoption, and upgrade

Canon anchors: §11 packaging and adoption, §12 instantiation checklist.

10 Release integrity and the release envelope

The release is bigger than the package: four loose files ride beside the zip, and the README is the front door to all of it. The two layers verify each other in sequence, loose first, package second, which is why they are one area.

In-zip integrity and hygiene:

The loose release layer, beside the zip:

The README's sections, each mapped to what makes it true:

The README carries no engine version label by design: it points at versions.html for the current version and fingerprints, so the file stays stable across releases while the fingerprints move where they are published.

Execution wiring, the whole engine as a timeline

At adoption: preflight.sh clears the floor → CHECKLIST.md walks §12 → hooks installed (install_pre_commit_hook.sh, install_post_commit_hook.sh) → slots filled per SLOTS.md (including creating seats.yaml) → docs/FOUNDATION.md authored.

At seat launch: operator runs orc-up.sh <lane> → launch-orc.sh resolves the stamp, refuses double-launch, creates {project}-{lane} → claude --agent orc loads orc.md → SessionStart hook fires boot-check.sh → the session derives identity via resolve-lane.sh, reads its charter, reads dispatch/LATEST.md, checks its inbox.

Per tool call: the PreToolUse hook runs guard-command-shape.sh on every Bash invocation.

Per change: foundation dispatches into an inbox and rings doorbell.sh → the lane works on its branch → worker emits artifact plus receipt (receipt-ledger.py allocates) → probe runs → the post-commit hook's auditor reproduces → only then does the state machine allow CLOSED.

Per commit: .git/hooks/pre-commit (from agents/pre-commit-hook.sh) reads spine-census.sh plus declared-spine-paths.sh at HEAD and blocks non-writer spine writes and uncovered foundation writes; .git/hooks/post-commit reaps, pushes, and launches the auditor.

Per set: members enter PENDING-SET.md via pending-set.sh → ratify.sh assemble computes joint edges and writes the packet → assess records foundation's reasoning, cost-guard.sh prices it → the operator writes one decision line → ratify.sh ratify records it → foundation merges, reap_at_merge.sh backstops, pushes at close.

Continuously: the nine probes in standing-probes.yaml run on their schedules, ledgered; audit_issue_register.py flags push drift; the seeded-fault batteries re-prove the gates can fail at every release.

Coverage account

The release is 106 files: 102 in the sealed package plus 4 loose beside the zip. In-package assignment: area 1 carries 1; area 2 carries 17 (10 identity files plus the 7 agent definitions); area 3 carries 7; area 4 carries 12; area 5 carries 14; area 6 carries 4; area 7 carries 7; area 8 carries 12; area 9 carries 17; area 10's in-zip table carries 4. Total 95, plus the 7 remaining: PENDING-SET.md counted in area 4, CLAUDE.md and disciplines.md counted in areas 2 and 5, dispatch/LATEST.md in area 5, issues_register.md in area 8, _escalations/escalation-003.md in area 7, export/EXPORT-set-authorization.md in area 4. The 4 loose files (README.md, LICENSE.md, the canon PDF, SHA256SUMS) carry their own rows in area 10's loose-layer table. Every file in the release appears exactly once above; none is unassigned.

One absence is load-bearing and named: seats.yaml does not ship. It is created at instantiation, and the engine's enforcement reads it at HEAD from the moment it exists.

This map is re-derived from the tree at every engine version; nothing in it is maintained by hand against drift. GMAA · gmaa.ai · cite by version.