@attalabs/vinaya 0.4.2 → 0.4.4

package/studio-standalone/.worktrees/fix/studio-standalone-repo-root/apps/vinaya/web/.next/standalone/aeg-root/coordination.md

@@ -0,0 +1,293 @@
+---
+sidebar_title: Coordination
+---
+# Coordination — How to Work With This System
+
+**This file lives in the repo at `aeg-root/coordination.md`.**
+**All agents read this at session start.**
+
+This is the coordination contract for **this repo's instance** of the AEG operating model. (The model itself is neutral and lives in `state-machine.md`, `aeg-manual-flow.md`, `tranche-model.md`, the role docs, and the `aeg` skill; *this* file fills in the repo-specific parts: the names, the products, the tools in use, the house communication style. A different repo adopting AEG would keep the model and replace this file's specifics.)
+
+Dani works with multiple agents across a chat/planning surface and a coding-agent surface. This file tells each agent who it is, how to orient, and what the rules are.
+
+**The model described here is Agentic Execution Governance (AEG)** — the v3 operational model. AEG is a small set of accountable roles (Principal, Planner / Brief Author, Developer, Reviewer, Archivist) coordinating AI agents through briefs, blocking escalation, and independent review. It is *not* "project management" (there is no product plan, timeline, or resource tracking here — that stays in the company's tool) — it is governance plus orchestration of delegated AI execution.
+
+**AEG is forge-native, orchestrator-independent.** It depends on a Git forge (GitHub) as its source of truth for execution state — task status is *derived* from Issue/branch/PR/merge state, never stored. It does **not** depend on any orchestration tool. The governance half (authority, ratification, review) lives in this repo, not in any tool.
+
+---
+
+## Reading order for new sessions
+
+If you are starting a fresh session and need to orient:
+
+1. `aeg-root/coordination.md` — this file (start here)
+2. `aeg-root/state-machine.md` — the constitution; artifact states, roles, permissions, decision schema
+3. `aeg-root/roles/{your-role}.md` — Planner / Brief Author (incl. Planner & Brief Author modes), Developer, Principal, Reviewer, Security, or Archivist
+4. `aeg-root/tranche-model.md` — the tranche model: tasks-as-Issues, forge-derived status, the thin topology file, conflicts (read when planning or executing)
+5. **Per-project state (pinned Issues)** — what is true right now, per project (one pinned Issue each, found via the repo's native Pinned Issues view, not a memorized number) plus the ecosystem-wide bucket (every project with no dedicated folder, plus cross-project facts, its own pinned Issue). Non-derivable operational facts; current focus pointer.
+6. **Derive current execution state from the forge** — see the "Session-start forge queries" section below
+7. `aeg-root/tranches/<name>.md` — the current tranche's task topology (the plan); live status is queried from the forge, not read here. **Post-cutover:** most active tranches no longer have this file at all — task→Issue topology derives straight from the forge (a Milestone + `tranche:<slug>`-labeled Issues). **No active tranche carries this file at all today** — the last tracked exception's file was deleted once its backfill completed (`tranche-model.md` §4); `completed/` tranches keep theirs permanently, by design, and `check-no-disk-state.ts` now CI-blocks adding a new active one.
+8. **Lessons log (pinned Issue)** — calibration lessons + anti-patterns, one comment per lesson (read when authoring briefs or post-mortems)
+
+The AEG model front door is the **`aeg`** skill (the model in one read) → the **`aeg-roles`** skill (routes you to your role doc). Load those first; this file is the repo-specific companion.
+
+### One AEG model, at the root. Always orient from there.
+
+There is exactly one AEG model in this monorepo, at the repo-root `aeg-root/` (constitution, flow, roles, skills, the project registry `projects.md`). It exists nowhere else. **Any agent, executing any task for any project — an app, a package, a library, the monorepo itself — orients from `aeg-root/` first:** it reads the constitution, the role doc, and the active tranche there. It never expects a per-project copy of the model.
+
+Living **state** is held in pinned forge Issues (lessons, per-project operational state): one root ecosystem-wide pinned Issue (covering every project with no dedicated folder, plus cross-project facts) and one pinned Issue per project that has its own folder. A task updates the pinned state Issue of each project it touches (one for a single-project task, several for a cross-project task — resolve which project via `.vinaya/projects.md`, then which Issue via this list or `gh issue search`). This state layer holds facts only — never the model — which is what forces every agent back to `aeg-root/` for the rules.
+
+For deeper context on the operational model design:
+- `aeg-root/aeg-manual-flow.md` — running the flow by hand (the operator's guide)
+- `aeg-root/process.md` — the thirteen-phase walkthrough from idea to merged code
+- `aeg-root/diagrams/` — process and architecture diagrams (note: being brought in line with the forge-derived-status model; if a diagram shows agents writing status, the prose docs are canonical)
+
+Do not generate strategy, plan a tranche, or author briefs until you have read `state-machine.md` and the spec for any project in scope.
+
+### Session-start forge queries — deriving current state
+
+`now.md` is retired. Current execution state is **derived from the forge**, not read from a file. Run these queries to answer the three orientation questions:
+
+**"What's active?"** — open Issues with an `tranche:<slug>` label, or check open PRs:
+```bash
+gh issue list --label "tranche:<slug>" --state open
+gh pr list --state open
+```
+
+**"What's next?"** — open Issues in the current tranche that have no open PR (unassigned branch):
+```bash
+gh issue list --label "tranche:<slug>" --state open --assignee ""
+# Then for each: gh pr list --state open | grep "task/<slug>/"
+```
+
+**"What's blocked?"** — Issues with the `aeg:blocked` label:
+```bash
+gh issue list --label "aeg:blocked" --state open
+```
+
+**"What's the current focus?"** — read the ecosystem pinned state Issue's "Current focus" section and the active tranche file at `aeg-root/tranches/<name>.md`.
+
+**"What merged recently?"** — `gh pr list --state merged --limit 20`
+
+No brief, no audit finding, no "next steps" recommendation is valid without this forge check. Forge state > file state > memory. Always.
+
+---
+
+## The coordination model — four truth domains
+
+Every fact lives in exactly one place (see `tranche-model.md` §1):
+
+- **The Git forge** (Issue / branch / PR / review / merge state) = **all live execution status, derived not stored.** Authoritative for task status and merge state. A task *is* a forge Issue.
+- **Repo** = code, specs, skills, PM docs, role docs, the thin tranche topology files, design decisions. Git-tracked, long-lived, changed by commits/PRs. The source of truth for *plan and governance* (not live status).
+- **The PR body** = the just-in-time brief — a task's full execution context. The brief is pasted here at PR-open, never committed separately, never in the Issue.
+- **Local filesystem** = orchestration-tool runtime state, worktrees, dev servers. Ephemeral. Never canonical.
+
+Conversation logs / thinking are not artifacts; do not cite as authority.
+
+### PM files that change frequently
+
+| File | Purpose | Update cadence |
+|------|---------|----------------|
+| `aeg-root/coordination.md` | This file. Rules, names, how to work. | Rare (system changes only) |
+| Per-project state (pinned Issue) | Non-derivable operational facts: known production issues, env-var requirements, phase intent, pending manual ops, current-focus pointer. | Whenever state changes |
+| `aeg-root/tranches/<name>.md` | The current tranche's task topology (edges, grouping). Plan only — no status. | At plan time (Planner) |
+| Lessons log (pinned Issue) | Calibration lessons + anti-patterns. One new comment per lesson. | Monthly review |
+| `docs-index.md` | Discovery map of repo content. Auto-generated. | When repo files added/removed/renamed |
+
+> **`now.md` is retired.** Active work, blocked tasks, and next candidates are derived from the forge (see "Session-start forge queries" above). The forge is the single source of truth for what is happening; the per-project pinned state Issue holds what the forge cannot derive.
+
+The roadmap is **not** an AEG file — it lives in the company's tool (or, for solo work, in the per-project backlogs `apps/<project>/specs/<project>-backlog.md`, which are reference docs out of the flow). The old global `roadmap.md` is retired, and the monorepo-wide `specs/ecosystem-backlog.md` it once sat beside was deleted with the rest of the stale AEG research — cross-cutting items are cut as backlog Issues instead. **Backlog convention:** a unit's *plan* lives in its `specs/` (`apps/<project>/specs/<project>-backlog.md` per project); a unit's *flow + governance* lives in the root `aeg-root/` (model, exists once); its *living state* lives on the per-project pinned Issue (the old per-unit `aeg-project/` state folder is retired).
+
+### What lives in the repo
+
+Everything else. All skills (canonical home `aeg-root/skills/*/SKILL.md`, with a generated agent-surface view e.g. `.claude/skills/`), agent definitions, specs (`apps/*/specs/*.md`), role docs, the state machine, this file. The index (`docs-index.md`) lists where things are.
+
+---
+
+## The names — where the host repo defines them
+
+Every session needs a shared vocabulary for the products, brands, and domains the work touches. **That vocabulary is the host repo's, not this model's**, so it is not defined here.
+
+An earlier revision carried one repo's product table, brand architecture, and naming conventions inline, marked as instance content. Marking it was not enough: a repo adopting this model still received another organization's product names, domains, and house naming rules as part of its own doctrine. The section is now a pointer rather than a payload.
+
+**Where to look, in order:** the project registry (`.vinaya/projects.md` — the authority for valid `Project:` values, and the only names any gate resolves against), then the repo's own root guidance file for brand and naming conventions. A repo with a single project needs neither: one project, no disambiguation, no registry.
+
+Nothing in this model resolves a product name. Names route work to specs and state; the routing is registry-driven, and the registry is the adopter's.
+
+---
+
+## Session start protocol
+
+Role is determined by environment and context — not by which agent you are. Read `state-machine.md` Section 1 for the role determination rules.
+
+### If you are the Planner / Brief Author (a chat/planning surface, talking strategy/planning)
+
+1. **Read `state-machine.md`** — confirm the authority matrix and decision schema.
+2. **Read `roles/planner.md` or `roles/brief-author.md`** — confirm which of the two you are. Planning a tranche is the Planner; authoring one task's brief is the Brief Author.
+3. **Read the ecosystem pinned state Issue** — orient on current ecosystem state, known production issues, and pending manual ops; read the relevant per-project pinned Issue too if scoped to one project. Read the current `tranches/<name>.md` for in-flight task topology.
+4. **Derive live execution state from the forge** — run the session-start forge queries above: open Issues by `tranche:<slug>`, open PRs, `aeg:blocked` labels.
+5. **Check the `needs:principal-input` label** — any labeled Issues/PRs for today's window? (`gh issue list --label needs:principal-input --state open`, `gh pr list --label needs:principal-input --state open` retired the `ratification-queue.md` file in favor of this label query — historical entries preserved on the pinned ratification Issue.)
+6. **Determine the project in scope** — apply the spec-check gate (below) before anything substantive.
+
+### If you are the Developer (a coding-agent surface, executing a brief)
+
+1. **Read the brief completely** before writing any code.
+2. **Read `roles/developer.md`** — confirm the entry gate, tier, stop conditions, verification checklist.
+3. **Check the dispatch gates against the forge** — is every `depends-on` task's PR merged? Is any `conflicts-with` sibling's PR open? If a gate isn't satisfied, STOP (the task serializes).
+4. **Create the worktree** — Step 0, branch `task/<tranche>/<n>` from `origin/main`. Do this before anything else:
+   ```
+   git worktree add .worktrees/task/<tranche>/<n> -b task/<tranche>/<n> origin/main && cd .worktrees/task/<tranche>/<n> && bun install --frozen-lockfile --silent
+   ```
+   The `bun install` step initializes Husky, which fires the post-checkout hook (`tools/sync-env-from-main.sh`) to symlink `.env*.local` files from the main checkout.
+5. **Run remaining pre-flight** — `git status`, `git log --oneline -3`, confirm the branch.
+6. **Identify which skills apply** — the brief's scope determines which skills to invoke.
+7. **Do not begin implementation** until gates are clear, worktree exists, pre-flight passes, skill-check is satisfied.
+
+### If you are the Reviewer or Security agent (reviewing an open PR)
+
+You were invoked specifically to review a PR. You run with fresh context on purpose; you did not write this code.
+
+1. **Read your role doc** — `roles/reviewer.md` (code) or `roles/security.md` (security). It is your full spec, including the entry-gate refusals.
+2. **Read the brief — in the PR body** (not the Issue; the Developer pastes the brief into the PR description). If there's no open PR, or no brief in the PR body, refuse per your role doc.
+3. **Read the PR diff** — `git diff main...HEAD` (stat first, then substantive files).
+5. **Emit the VERDICT block** from your role doc. Do not edit code. Do not merge. Do not write status. Route `[ESCALATE]` findings to Planner/Principal.
+
+### If you are the Archivist (closing out a merged PR)
+
+1. **Confirm the PR is merged** — your only hard precondition (forge-derived). If not merged, refuse.
+2. **Read `roles/archivist.md`** — the close-out checklist.
+3. **Work the checklist** — Issue closed, docs coherent, per-project pinned state Issue updated for every project the task listed (remove stale operational notes; `now.md` no longer exists), provenance block posted to the merged PR. Flag (don't perform) orphaned branches and worktree removal. Write no task status — the merge is the status.
+
+### Mandatory forge check (before any brief, audit, or recommendation)
+
+Run or fetch before producing output that depends on knowing what's in flight:
+- Open Issues (current tranche): `gh issue list --label "tranche:<slug>" --state open`
+- Open PRs: `gh pr list --state open`
+- Blocked Issues: `gh issue list --label "aeg:blocked" --state open`
+- Recent merges: `gh pr list --state merged --limit 20`
+
+No brief, no audit finding, no "next steps" recommendation is valid without this.
+Forge state > file state > memory. Always.
+
+### Hard rule — the spec-check gate
+
+If Dani asks a strategic, architectural, or product-shape question about a named product, and you have not read the specs for that product, **stop and read them first.** No "thinking out loud first." Applies to the Planner and the Brief Author alike. Does NOT apply when executing a brief (the brief specifies scope; do not expand it).
+
+---
+
+## Ratification windows
+
+1-2 daily sessions where the Principal resolves items requiring his final authority. there is no queue file — the Brief Author applies the `needs:principal-input` label to whichever Issue/PR needs ratification and batches the labeled set (`gh issue list --label needs:principal-input`, `gh pr list --label needs:principal-input`) before each window. Historical entries predating this mechanism are preserved on the pinned ratification Issue.
+
+**Batches at windows:** Type 1 decisions (irreversible; PENDING until window); Tier 3 PR merges; `severity: product` escalations; PENDING Type 2 decisions.
+
+**Does NOT wait:** Type 2 decisions the Brief Author makes (ACTIVE immediately); Tier 0/1 PR merges (after CI + Brief Author spec review); `severity: execution`/`strategy` escalations (Brief Author handles); already-ratified items.
+
+**Brief Author responsibility:** before each window, surface PENDING items; after, mark RESOLVED with the Principal's action and date.
+
+---
+
+## Spec naming convention
+
+Locked. Spec filenames are `{product}-spec.md` or `{component}-spec.md` — no `-v0`/`-v1`/`-draft`/date suffixes. Version state lives in the file's `Status:` block (`draft` / `target` / `ratified` / `retired`), not the filename. Renaming to add a version suffix requires a lock challenge to.
+
+---
+
+## Coordination rules — keeping sessions in sync
+
+### Every repo-file change goes through a worktree + PR — no direct commits to `main`
+
+**Universal rule, every role.** Any change to a repo-tracked file — code, specs, skills, role docs, the tranche topology — reaches `main` through a worktree branch + PR + green merge. **No role commits or pushes directly to `main`.** This applies to the Planner editing the tranche file just as much as the Developer editing code: "I only touched a doc" is not an exemption. The drift that produced this rule was a plan commit landing on `main` with no worktree and nothing stopping it.
+
+This is **mechanically enforced**, not merely asked:
+- `.husky/pre-commit` refuses a commit while the current branch is `main`; `.husky/pre-push` refuses any push whose target is `refs/heads/main`. (Husky activates per-worktree via the post-checkout hook, so the guards fire in every worktree.)
+- The merge-gate hook `.claude/hooks/check-pr-green.sh` (a `PreToolUse` hook wired in `.claude/settings.json`, sibling to `check-skill.sh`) intercepts every agent merge path — `gh pr merge`, `gh api …/merge`, `curl …/merge`, and the GitHub MCP `merge_pull_request` tool — and **denies the merge unless `gh pr checks <pr>` is all-green**. A red or pending PR cannot be merged by an agent. The gate fails closed: if greenness can't be proven, the merge is denied.
+
+The green-merge + no-direct-commit invariants now live in both these hooks and a GitHub setting: repository ruleset `17656829` ("Main protection") requires the `AEG gate suite`, `Typecheck + unit tests`, and `Review gate` checks on `~DEFAULT_BRANCH`, with `bypass_actors: []`. The exception path is the same as everywhere: a `Lock`/override is a Principal action, not an agent one.
+
+The only thing a non-Developer role does *not* route through a worktree is a pure forge action (cutting an Issue, posting a comment, merging via the gate) — those touch the forge, not repo files. Every repo *file* edit goes through the worktree + PR.
+
+### When state changes, update the pinned state Issue
+
+State changes: a project phase advances, an app ships/scaffolds, auth/DNS config changes, a known production issue is resolved, a pending manual op is completed. The Brief Author updates the relevant project's pinned state Issue (one per project, or the ecosystem-wide one) directly (editing an Issue body is a forge action, not a repo-file change — it does not go through a worktree/PR). For Tier 3 work affecting the state Issue, note it in the code PR's body too.
+
+Active work, next candidates, and blocked tasks are **derived from the forge** — they are never written to a file. (`now.md` is retired.)
+
+### When the plan changes, update the appropriate file
+
+- **The execution plan changes** (a task's edges, a new task, tranche scope) → the current `tranches/<name>.md` (Planner, at plan time). Live task *status* is never written — it's derived from the forge.
+- **Held/future project items change** → the relevant per-project backlog (`apps/<project>/specs/<project>-backlog.md`) — out of the flow.
+- **Lesson learned / anti-pattern** → post a new comment on the pinned lessons Issue — never edit an existing comment
+
+### When repo structure changes, regenerate `docs-index.md`
+
+Run `bun docs:index`, commit the result. On add/remove/rename. Content changes within existing files do not require regeneration.
+
+### When decisions are made, log them immediately
+
+State the decision in the pull request that carries the work, during the conversation. Announce: "I'm treating this as a Type [1/2] decision." Do not defer to session end.
+
+---
+
+## What goes where — quick reference
+
+| If you're updating... | Where |
+|----------------------|-------|
+| A skill / agent definition | Repo only (skills: canonical in `aeg-root/skills/`, generated view in `.claude/skills/`) |
+| A project spec, ecosystem vision, naming decision | Repo only |
+| Non-derivable operational facts (production issues, env-var requirements, phase intent, pending manual ops, current-focus pointer) | Per-project pinned Issue, one per project, plus one covering ecosystem-wide facts |
+| The execution plan (task topology, edges) | `aeg-root/tranches/<name>.md` |
+| Held / future project items | `apps/{project}/specs/{project}-backlog.md` (per project); cross-cutting items are cut as backlog Issues |
+| Completed work history | `git log` / merged-PR history (redundant with a committed changelog, so none is kept) |
+| Calibration lessons + anti-patterns | Pinned lessons Issue, one new comment per lesson |
+| Items awaiting Principal ratification | `needs:principal-input` label on the relevant Issue/PR; historical record on the pinned ratification Issue |
+| Live task status (what's active, blocked, next) | **Nowhere — derived from the forge** (`gh issue list --label "tranche:<slug>"`, `gh pr list`, Issues view) |
+| Adding/removing/renaming a repo file | Repo + `bun docs:index` |
+| Fundamental coordination rules | This file |
+
+---
+
+## Anti-patterns
+
+- ❌ Reading or writing `roadmap.md` — it's retired; the execution plan is the tranche file, the product roadmap is the company's tool / backlogs (`apps/*/specs/*-backlog.md`)
+- ❌ Putting a backlog anywhere but a `specs/` folder — the plan lives in `specs/`; `aeg-root/` is the model, flow + governance only, and living state is the per-project pinned Issue
+- ❌ Writing task status anywhere (a file, the tranche topology, an Issue field) — status is derived from the forge; storing it recreates the racing status model the design eliminated
+- ❌ Adding execution metadata (status, PR #, dates) to the tranche topology file — it is plan topology only (`tranche-model.md` §9)
+- ❌ Putting the brief in the Issue — the brief is just-in-time and lives in the PR body; the Issue is task identity + metadata only
+- ❌ Putting planning metadata (priority, estimates, points) on an Issue — that's the company's roadmap, not AEG
+- ❌ Building a dynamic conflict scanner — declare conflicts conservatively and serialize (`tranche-model.md` §9)
+- ❌ Putting tactical day-to-day plans in project specs (commit churn)
+- ❌ Pretending to have read a spec that isn't in context — ask for it by exact path, or read it from the forge
+- ❌ Restating the host repo's brand, namespace, or product-naming rules here — they belong to the adopting repo, not to this model
+- ❌ Letting the Developer review its own work — review/security passes are separate fresh-context invocations
+- ❌ Generating strategy or planning a tranche before reading the specs (spec-check gate)
+- ❌ Adding version suffixes to spec filenames (locked)
+- ❌ Making a Type 1 decision in the Brief Author's absence without flagging PENDING
+- ❌ Logging decisions at session end instead of at the moment of decision
+- ❌ Letting PENDING items accumulate without surfacing them at the next window
+
+---
+
+## Communication style with Dani
+
+- Terse. No preamble.
+- No time-of-day, energy, or wellness framing.
+- No reflexive caveats unless risk is concrete.
+- Direct recommendations, not balanced both-sides answers.
+- Match length to substance.
+- Don't repeat back what Dani said.
+- Push back when warranted. Don't manufacture criticism when a position is sound.
+- Diagnose before iterating — find root cause before proposing fixes.
+- Project files are authoritative when they conflict with memory.
+
+---
+
+## Multi-agent context
+
+Dani works with multiple AI collaborators simultaneously: Claude (multiple sessions), Gemini, Grok, DeepSeek, ChatGPT. Dani is always the Principal.
+
+When other AI outputs are pasted in, Claude responds as the adversarial reviewer / Critic. Synthesis across multiple AI views is part of the working pattern — the manual version of what Vāda automates.
+
+The AEG model formalizes this: Principal → Planner → Brief Author → Developer → Reviewer + Security → merge → Archivist. The Brief Author routes escalations by severity. Agents do not make final calls.
+
+**Tooling note (this repo, May 2026):** GitHub MCP may be available via OAuth in fresh conversations — prefer it over paste-back for reading repo content and creating Issues/PRs. The coding-agent surface has direct filesystem access to the worktree. Self-hosted MCP servers with bearer-token auth (e.g. Vāda's hosted MCP) work via a coding-agent CLI, not via the chat connector broker. An orchestration tool may bind the same conversational surface (list active tasks, reply to a blocked task) — a convenience of whatever tool is in use, never part of the model.

package/studio-standalone/.worktrees/fix/studio-standalone-repo-root/apps/vinaya/web/.next/standalone/aeg-root/documentation-coherence.md

@@ -0,0 +1,65 @@
+---
+sidebar_title: Documentation Coherence
+---
+# Documentation Coherence — who reads, who writes, and when
+
+Documentation coherence is not one obligation — it is a relay across every role in the flow, each leg governed by a role-seam contract. This page indexes that relay: what each role reads before it acts, what it writes as it hands off, and the two enforcement tracks (judgment vs. mechanical) that keep the relay from silently dropping a doc. It does not restate the authoritative sources — the seam contracts, `state-machine.md` §15, and `enforcement.md` remain canonical; this page cross-links them.
+
+---
+
+## Role × reads/writes
+
+| Role | Reads (before acting) | Writes (at its seam) |
+|---|---|---|
+| **Planner** | Every spec/skill/doc relevant to the whole tranche's code surfaces — the whole-tranche read pass required before cutting a single task (Pillar 1). | The **"Docs to keep coherent"** rationale field on each task's Issue — names intended surfaces (not resolved doc pointers; the manifest evolves before dispatch). No doc files edited directly. |
+| **Brief Author** | The Planner's rationale (via `contracts/planner-brief.md`), plus its **own task-scoped re-read** of the same surface — re-verified fresh at dispatch time, since docs may have moved since planning (Pillar 1). | Brief **§2** (surfaces what the Developer must know) and **§7** (the doc-update list) — mechanically re-derived by matching the task's intended surfaces against the live `.vinaya/doc-owners` manifest (`deriveSection7`), then supplemented by its own reading. Any override of the derived floor carries a one-line reason. |
+| **Developer** | The brief's §2 and §7 — zero-discovery execution: the Developer does not re-derive what §7 already names. | Updates every doc named in §7 in the same PR (Pillar 2, a DoD gate — a named doc not updated is a BLOCKER at review). Independently, for any changed code file that matches an `.vinaya/doc-owners` binding, satisfies C5's bind‑or‑waive rule (update the bound doc, `Doc-ack:`, or a principal's actor-verified waiver label) whether or not §7 named it. |
+| **Reviewer** | The brief in the PR body, then the diff. | No files — a **verdict** with a dual check: §7 completeness/correctness as a BLOCKER gate (`contracts/developer-reviewer.md`), and judgment of C5-covered doc **correctness** (a passing C5 plus a no-op or misleading doc edit is still a BLOCKER). |
+| **Archivist** | The merged PR (brief, diff, Reviewer's verdict). | Post-merge **coherence confirmation** — confirms the tier-required docs actually moved and are coherent with what merged (not just present); updates the per-project `state.md` for every project the task listed; updates `docs-index.md` if files were added, removed, or renamed. |
+
+---
+
+## Two tracks, not one
+
+Coherence is enforced on two independent tracks that both run on every PR:
+
+- **Judgment track — §7.** A human/agent-read obligation: the Planner and Brief Author identify which docs a task's *specific* change will make incoherent, name them, and the Developer updates them; the Reviewer judges whether the update is actually correct, not just present. This catches docs the mechanical manifest hasn't been taught about yet — a doc that's relevant by context and reading, not by a declared glob.
+- **Mechanical track — C5 / `.vinaya/doc-owners`.** A CODEOWNERS-shaped `<code-glob> → <doc-pointer>` manifest; `verify-docs` C5 glob-matches every changed code file against it and enforces bind-or-waive (update the bound doc, `Doc-ack:` a URL pointer, or a principal's actor-verified waiver label) — dormant until a binding exists, orthogonal to tier (state-machine.md §15). This is the backstop for surfaces someone already declared load-bearing, independent of whether any human remembered to name them in §7 this time.
+
+Neither track substitutes for the other: §7 catches what the manifest doesn't yet know; C5 catches what a tired §7 pass forgets.
+
+---
+
+## The Planner/Brief-Author split
+
+The read obligation splits by altitude, not by redundancy:
+
+- The **Planner's** read pass is whole-tranche — before any task is cut, it reads the specs/skills/docs relevant to every surface in scope and records, per task, which docs that task will make incoherent.
+- The **Brief Author's** read pass is task-scoped re-verification — at dispatch time (which may be well after planning), it re-reads the same surface fresh and mechanically re-derives the §7 floor from the *live* `doc-owners` manifest (`deriveSection7`), because the manifest — and the docs themselves — can have moved since the Planner's pass. The Planner names intended surfaces, never resolved pointers, for exactly this reason.
+
+This is why the Planner's rationale field survives even though a mechanical derivation exists: the derivation runs once, at brief time, against current reality — it cannot run at plan time without freezing a pointer list that goes stale.
+
+---
+
+## Reader-facing readability — no unresolvable symbols
+
+Some of these docs are read by strangers, not only by agents that carry this repo's history in context. The published set (the enforcement map, the role docs, the contracts) is the harness's public face, and any token that requires insider knowledge — a decision id, a section number, an Issue or PR number, a tranche slug, an internal file path — means nothing to a stranger, because it points at something not on the page. The rule is therefore a principle, not a fixed list of symbol types:
+
+> **A reader-facing published doc contains no token that requires insider knowledge — no decision ids, section refs, Issue/PR numbers, tranche slugs, or internal paths; state facts in plain words. Machine fields and named references to other published docs are exempt.**
+
+State the fact in plain words and delete the token; the sentence must stay true and complete for a stranger. Exempt: machine fields a parser/build reads (frontmatter keys), and named references to other **published** docs a reader can open.
+
+**This rule is mechanized — C7, in `verify-docs`.** It scans the text that actually reaches a reader and nothing else: for a role or contract that is the `## The short version` section (the binding opener each one now carries), and for the enforcement map it is the introduction plus the four columns the page renders — the row's own name, `Summary`, `Category`, `Description`. The enforcing columns are never scanned; they exist to gate, not to read. C7 also asserts the structure of that section: all four blocks present, in order, inside the word band. It runs **blocking at the pull-request gate**, scoped to the doctrine files the diff touched, and again repo-wide in full mode. Protocol mechanics an adopter must learn — the isolated-worktree path and the task branch convention — are explicit, tested exemptions rather than accidental passes.
+
+**Frontmatter `provenance:` is the sanctioned home for an internal reference.** A decision id, a file path or a tranche slug an agent genuinely needs stays greppable there and never reaches the page, because frontmatter is stripped before render. **HTML comments are not a substitute:** this repo's renderer runs without raw-HTML support and prints `<!-- … -->` as visible text on the page — verified live. `aeg-root/enforcement.md` demonstrates the pattern.
+
+The Reviewer's judgment now sits **on top of** the check rather than instead of it: C7 catches the token classes it can name, and the Reviewer still judges whether a published page reads complete to a stranger who lands on it cold — the question no pattern can answer. A published doc that leaves an insider-only token on the page is a finding either way.
+
+---
+
+## Cross-references
+
+- The read/write obligation, the `doc-owners` coverage gate, and the mechanical derivation of the doc-update list are all stated above; the seam contracts carry the per-role halves.
+- **Seam contracts** (`aeg-root/contracts/`): `planner-brief.md`, `brief-developer.md`, `developer-reviewer.md`, `reviewer-archivist.md`, `archivist-tranche-archivist.md`, `tranche-archivist-planner.md`.
+- **`state-machine.md` §15** — Coherence Seam: Doc Coverage — the C5 mechanics in full.
+- **`enforcement.md`** — the three-ring enforcement map; documentation coverage is called out there as enforced at both push and PR-open.

package/studio-standalone/.worktrees/fix/studio-standalone-repo-root/apps/vinaya/web/.next/standalone/aeg-root/enforcement.md

@@ -0,0 +1,161 @@
+---
+sidebar_title: Enforcement Map
+# `provenance` is the home for internal references that must NOT reach a
+# reader. Frontmatter is stripped before render, so a pointer here is
+# greppable by an agent and invisible on the page. HTML comments are NOT a
+# substitute: this repo's docs renderer (react-markdown, no rehype-raw)
+# surfaces them as literal text on the page — verified live.
+provenance: >
+  The normative registry of every gate lives in aeg-root/state-machine.md.
+  It is unpublished, so it is not named in this file's reader-facing prose.
+---
+# Enforcement Map — how the forge stays valid
+
+This page answers two questions: **what prevents an invalid artifact from ever being created**, and **what detects one if it slips through anyway**. Every mechanism listed is real and installed — nothing aspirational. Each ring below is read from the harness's own rules, not written for this page.
+
+
+**The founding observation:** agents obey checkers, not documents. A rule that exists only as prose will eventually be violated by an honest agent under context pressure — proven live when a pull request satisfied exactly the sections the checker verified and dropped the two it didn't. So every contract rule must be a deterministic check, and every check must sit at the earliest chokepoint that can host it.
+
+---
+
+## The model: three rings, by where a violation dies
+
+| Ring | Where | What happens on violation | Who pays |
+|---|---|---|---|
+| **Hooks** | The agent's own machine (command, commit, push) | The action itself is **refused** — the invalid artifact never exists outside the agent's session. The exact errors feed back; the agent fixes and retries, in-session. | Nobody. Self-correcting. |
+| **Branch Rules** | The forge (CI on every pull request) | The identical checks re-run; CI goes **red**; the merge gate makes red unmergeable by agents. Covers writers the local gates can't reach (web UI, humans, other tools). | Visible red — a human may look. Red on a gated rule now means a *gate bug*, not an agent failure. |
+| **Audits** | After merge, continuously, across the whole forge | Drift is surfaced as findings, regardless of who or what wrote it — including history that predates the gates. | Scheduled clean-up, never a surprise mid-dispatch. |
+
+The same check implementations run at ring 0 and ring 1 — one codebase, two enforcement points, so the local gates and CI can never disagree.
+
+---
+
+## Ring 0 — Hooks (nothing invalid leaves the machine)
+
+| Action | Summary | Category | Description | Gate | What must be true before the action is allowed | implementation |
+| --- | --- | --- | --- | --- | --- | --- |
+| Editing a governed file | Ever had a teammate change code they clearly never read the docs for? | hook | Refuses an edit to a governed file until the document that governs it has been read in this session. | **Edit gate** | The architecture document that owns the file has been loaded in this session — no editing governed code from pattern-matching alone | `.claude/hooks/check-skill.sh` |
+| `git commit` | Ever pushed code that didn't even compile? | hook | Refuses a commit that does not build or pass its own checks, before the broken state exists at all. | **Git pre-commit hooks** | The code compiles, passes lint and formatting, the unit tests pass, and the commit message follows the repo's message convention | `.husky/pre-commit` |
+| `git push` | Ever had someone accidentally push straight to main? | hook | Refuses a push that would land straight on main, on the machine that attempted it. | **Git pre-push hook** | No pushing straight to `main` — a direct push cannot be refused for a commit that already landed on `main` some other way (e.g. a repo-admin action outside the hook's reach); that residual class now has a ring-2 detection backstop (see below, task 24 item 1). A task branch's name must exactly match its planned task row in the tranche plan. A task branch whose most recent pull request is already `MERGED` or `CLOSED` is refused outright — closing the class of bug where stale local work lands on an already-resolved branch, silently reopening/confusing forge state (live-fire incident, 2026-07-03: six topology rows landed on a plan PR's branch after that PR had merged); this check is fail-open (hook-dependent), so it too now has a ring-2 detection backstop (see below, task 24 item 2). This check is deliberately **fail-open**: if the forge cannot be reached (network flake, auth issue, rate limit) it is treated the same as "no pull request exists yet" and the push is allowed — a transient reachability issue must never block every push. On a task branch's first push (before its PR exists), `verify-dispatch` also runs itself here — see the dedicated row below (task 25). Any changed code that has a designated owning document must have that document updated in the same branch, OR (task 29) carry an actor-verified `vinaya/waiver:docs` label on the open pull request, OR (task 4) carry a `Doc-neutral: <pointer> — <note>` PR-body declaration whose matched-file diff is verified comment/whitespace-only (`isMechanicallyNeutralDiff`) — a waiver is a forge-authenticated human act, never a parseable string, and a Doc-neutral declaration is never sufficient by itself; only diff-confirmed evidence satisfies it. Before a PR exists (first push) no waiver label can exist yet, so an owned-doc violation here is **warn-with-declared-intent, not a hard block**: the push always succeeds, and the printed message states plainly that ring 1 stays red until a principal applies the label, the doc is updated, or a Doc-neutral declaration with confirming evidence is added — this replaces the earlier first-push `Doc-waiver:` commit-trailer self-service, which is now dead code (that path is superseded). `Doc-ack:` (URL-pointer acknowledgment) is unaffected by the waiver change — still read from the branch's own last commit message before a PR exists, or — for a pre-authoring dry run via `verify-dispatch --simulate`, before any commit exists — from a local drafted-PR-body file. | `.husky/pre-push` |
+| Creating a pull request, or editing its title/description | Ever opened a PR that was missing half the info reviewers needed? | event | Refuses to open or edit a pull request until it carries everything a reviewer needs to judge it. | **Forge command gate** — the raw command is refused; the validated wrapper is the only path | The title follows the naming convention. The description carries every required section of the task brief: the impact tier, the executing model, the project(s) touched, a tagged test plan, the file surface the task may touch, the documentation it must update, the isolated-worktree setup step, the stop conditions, the standing autonomy clause, the Issue this work closes,. A *plan* pull request must never close a task Issue. The documentation required by the change's impact tier is present — a doc-coverage finding here is honored ONLY by an actor-verified `vinaya/waiver:docs` label, never a body field. The branch, its planned task row, and the Issue it closes all agree with each other. **Single-plan-PR guard (task 19):** a diff that touches a tranche's topology file (`aeg-root/tranches/*.md`, excluding `completed/`) is refused outright if another OPEN pull request's diff already touches that SAME tranche's topology file — closing the race that produced two concurrent plan pull requests for the same tranche, each cut before the other's newly-added Issue was visible. Ordinary task pull requests never touch a topology file, so this never fires for them. A PR opened via the web UI bypasses this wrapper entirely, so this predicate (extracted to `packages/aeg-core/src/single-plan-pr.ts`, task 24 item 3) now also has a ring-1 CI backstop (see below) — one implementation, two enforcement points. | `packages/aeg-core/bin/open-pr.ts` |
+| Creating a task Issue, or editing its title/description | Ever seen a ticket with zero context on why it exists? | event | Refuses to open or edit a task Issue until it carries the full reasoning behind the task. | **Forge command gate** → validated wrapper | The title follows the naming convention, and the Issue carries the complete planning rationale — what the task is and is not, its sizing, the projects and blast radius it touches, why its dependency edges exist, the known traps, the suggested agent class, the stop-and-escalate conditions, and the documents it must keep coherent. Issues outside the task system pass through untouched. **Beyond presence, three content checks block: the rationale's declared surface must not reach into a shared collision domain (`.aeg/packages`) that none of its declared projects owns without either a second project or an explicit `blast-radius-ack:` line; the body must carry no brief-shaped section (`## References`, `Technical surface map`, `Premise`, `Step 0`, `Test Plan`) — brief content goes stale before work starts and belongs in the brief; and the rationale must name at least one concrete doc/skill path (or the explicit `no-doc-surface` sentinel), which is the only read-obligation signal a forge write produces, since the skill-check hook fires on file edits and cutting an Issue edits no file. A fourth check warns, never blocks: two open task Issues naming the same collision domain with no mutual `Conflicts-with` edge.** **Label-name validity is checked here too:** a tranche label is the one label whose value the Planner invents, and `vinaya/tranche:` spends 15 of GitHub's 50-character label budget before the slug starts — so a slug that reads fine in prose can be one the forge refuses to create. The wrapper refuses an over-long slug with the exact overshoot, at the point the label is first applied, rather than letting `gh` fail with an opaque 422. **Dependency-edge amendments have exactly one path — the `amend-deps` subcommand, which rewrites the structured `Dependency rationale` field AND appends the `**Amendment (...)**` note in one atomic write, gated on a runtime round-trip parse (`parseRationaleDeps` must read back exactly the requested edges) — no code path changes one representation without the other (closing a five-incident field-vs-amendment drift class this session; modeled on the actor-verified waiver pattern: the sanctioned path is the only path).** | `packages/aeg-core/bin/open-issue.ts` |
+| Writing to pull requests or Issues through the raw API | Ever had a bot silently edit a PR or issue behind your back? | event | Refuses raw API writes to pull requests and Issues, so nothing can edit them behind the gates. | **Forge command gate** | Refused outright — there is no unvalidated path | `.claude/hooks/check-forge-gates.sh` |
+| Merging | Ever had a broken build get merged anyway? | event | Refuses a merge while anything the gates check is still failing. | **Merge gate** | Every CI check is green — red or pending cannot be merged by an agent | `.claude/hooks/check-pr-green.sh` |
+| Starting the Dig (before authoring a brief) / starting Step 0 (before executing one) / **every push on a task branch before its PR exists** | Ever started work only to find out halfway it was blocked on something else? | hook | Refuses to start work until every precondition for the task is checked live and found clear. | **`verify-dispatch` CLI** (`packages/aeg-core/bin/verify-dispatch.ts` — mandated by `roles/developer.md` and `skills/brief-authoring/SKILL.md`; **now also hook-automated** — task 25) | Every dispatch precondition is re-checked live against the forge (the task's row/Issue are derived directly from a Milestone + `vinaya/tranche:<slug>`-labeled Issues as of the forge-native migration — no `origin/main` file read involved; leftover-branch detection still fetches `origin/main` for its own commit-count comparison): the task's row and Issue exist; the Issue passes the rationale gate; every `depends-on` PR is merged and no `conflicts-with` PR is open/in-flight; every named project's prior tranche is archived. (2026-07-13: the immediately-prior task's three-predicate archival bar — the row-adjacency predicate — was removed once the provenance-posting signal it existed to protect became automated.) A `NOT READY` result is a stop condition. Every `gh` call this script makes carries an explicit `-R <owner>/<repo>` (task 23) — from a linked `git worktree add` checkout, an untargeted `gh issue list`/`gh issue view`/`gh pr list` silently scopes to the wrong repo (or returns nothing), which previously produced false prior-tranche-archival blockers. **`.husky/pre-push`** now runs this gate itself on a `task/*/*` branch's first push (before a PR exists), refusing on genuine `NOT READY` and failing OPEN — loudly — when a `gh auth status` reachability probe fails or `verify-dispatch`'s own repo/token resolution fails (task 18's fail-open precedent). The gate reads only the `dispatch-readiness:` predicate, not verify-dispatch's combined exit code, which also folds in `leftover-detection` (a pre-Step-0 "safe to branch fresh" advisory that would otherwise false-block every push after the first on a task legitimately mid-flight — discovered live while building this gate). Once a PR exists, later pushes skip the gate: dispatch was already validated once. | `packages/aeg-core/bin/verify-dispatch.ts` |
+| Opening a task PR whose surface includes real code | Ever had a PR's description quietly stop matching what the code does? | event | Refuses a code-carrying pull request whose description no longer matches what it changes. | **Brief Validation — `checkPremiseCoverage`** | The PR body carries a `Premise:` block with at least one assertion (`contains`/`absent`/`sha256`) whose path falls inside the task's surface map — re-assertable at any point via `verify-dispatch --premise` or `verify-task`. | `packages/aeg-core/src/brief-validation.ts` |
+| Opening a task PR (final self-check before creation) | Ever opened a PR and only then discovered the tests were failing? | event | Runs the whole exit check before a pull request is created, so failures surface first. | **`verify-task` CLI** (`packages/aeg-core/bin/verify-task.ts` — mandated by `roles/developer.md`; **now also hook-automated** — task 25) | Typecheck, lint, tests, build, `verify-docs --pr`, and the premise coverage/recheck pair all pass, as one summary, against the PR's actual diff, before `open-pr.ts` is invoked. **`open-pr.ts` now runs this composite itself** for task branches (via `gatePlanForBranch`), invoked wholesale rather than partially re-implemented — non-task branches are unaffected (byte-identical gate set). `verify-docs --pr` runs twice on a task-branch PR-open as an accepted, measured overlap (~4s with a warm turbo cache). | `packages/aeg-core/bin/verify-task.ts` |
+| Spawning a check (`vinaya check`, ring-0 pre-push AND ring-1 CI) | Ever had a check quietly read a secret it had no business seeing, because nothing scoped what it could reach? | hook | Governs which environment variables a spawned check's child process can see, instead of every check inheriting the full parent environment unconditionally. | **Env allowlist** (`CheckSpec['env']`, `apps/vinaya/cli/src/checks/contract.ts`; construction: `buildCheckEnv`, `apps/vinaya/cli/src/checks/runner.ts`) | **⚠️ BREAKING, live (task 3):** a spawned check's child process sees only a fixed baseline (`PATH`, `LANG`, `HOME`, `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, `TMPDIR`) plus whatever its own `env` declaration (`true` / `{ optional: true }` / `{ anyOf: [...] }` / a literal string) explicitly forwards — **no longer the full parent environment.** An undeclared variable a check's own code reads is now genuinely invisible to it, not merely warned about; a `true` or unsatisfied `anyOf` declaration missing from the caller's environment synthesizes a `CheckError` and the check never spawns at all. All 15 core checks in `registry.ts` carry an audited declaration, and every core check that spawns `gh` or reaches the forge through the token-resolution chain additionally forwards `GITHUB_TOKEN`/`GH_TOKEN` as `{ optional: true }` — on a CI runner those env vars are `gh`'s only authentication path, so a check that shells out without forwarding them runs unauthenticated there (hard-failing or silently degrading, depending on the bin's failure mode) while passing locally on `gh`'s keyring; the pairing is coupling-tested (`apps/vinaya/cli/tests/checks/registry-env.test.ts` detects `gh` invocations in any call shape — array-form, string-form, and template-literal — and demands both declarations). This repo's own core checks are therefore unaffected — an adopter's **custom** check that reads `process.env` directly with no `env` declared will lose that access at this minor; declare `env` on it (`vinaya.config.json`'s `checks.<name>.env`) before upgrading. `vinaya check`'s prior warn-phase print (task 2) is retired now that the behavior it warned about is live; `vinaya doctor` still carries the same missing-declaration diagnostic permanently, at `info` severity, so a custom check's gap remains visible after upgrade even though `vinaya check` no longer prints it inline. | `apps/vinaya/cli/src/checks/runner.ts` |
+| `vinaya check` / `vinaya check --plan` (a CLI mechanism, not a git hook — this row is `.husky`-free) | Ever had a config entry silently double-run alongside the core check it was meant to replace, with no way to see that from the outside? | event | Resolves core-registered and config-registered checks into one deterministic table before anything runs, instead of letting a config entry run alongside the core check it collides with, unannounced. | **Checks-side resolver** (`resolveChecks`/`isValidNamespacedKey`, `apps/vinaya/cli/src/checks/resolver.ts`) | An exact-key match against a core check ID is an **override** — a complete replacement of the spec, never a merge. A key containing exactly one `/`, both segments matching `[a-z0-9][a-z0-9-]*` and the `vinaya` prefix rejected as an exact segment match, is **additive**. Anything else — a bare key with no `/` matching no core ID — is a loud `FAIL_CLOSED` refusal: never silently dropped, never defaulted, never last-wins. `--plan` never resolves or prints an env *value*, only how each one resolves. **This release feeds `vinaya check --plan` / `--plan --json` only** — `vinaya check`'s real execution (`check.ts`'s flat `[...coreCheckRegistry(), ...customSpecs]` concat) is unaffected until a later task wires it in. | `apps/vinaya/cli/src/checks/resolver.ts` |
+
+**Documentation coverage, specifically** (a historical pain point): the code→document ownership rule is enforced at *two* prevention chokepoints — at every push (over the branch's cumulative change set) and again at pull-request creation and editing. A change to owned code cannot be published, let alone turned into a pull request, without its owning document.
+
+**The impact-tier rule, specifically** (another historical pain point): a change that touches doctrine must explicitly declare its impact tier, and the documentation that tier demands must be present — checked before the pull request can exist, for every branch type.
+
+**Gate-read field recognition, specifically** (task 30): every gate-read PR-body field (`Tier:`, `Project:`, `Closes #N`, the `Premise:` block, the Test Plan section) is anchor-recognized where present — an `AEG:<FIELD>` HTML-comment pair (`packages/aeg-core/src/anchored-region.ts`) is read exclusively when it exists, so identical-looking text elsewhere in the body (a pasted reference brief, a quoted example) can never masquerade as the field — with the original prose/heading recognition as the compatibility fallback for every body that carries no anchors.
+
+**Issue self-assignment at first push, specifically** (task 33): the pre-push hook carries one deliberate non-gate side effect — on a `task/*/*` branch's genuinely first push (the remote ref is being created; its pre-push remote-sha is all zeros), `packages/aeg-core/bin/assign-task-issue.ts` assigns the task's Issue to the authenticated `gh` user, i.e. the actual pusher. This mechanizes the signal Studio's dispatch-visibility chip reads (task 26: `assigned = assigneesCount > 0`), which until this task was populated only when the Principal remembered to assign by hand (live-fire gap: task 28 showed no chip despite two real pushed commits). Deliberately **assignment-at-first-push, not at brief-authoring** — a written-but-undispatched brief is not "in flight", and assigning earlier would reintroduce the false positive task 26 was built to avoid. Idempotent (an already-assigned Issue is a no-op, so a deleted-and-recreated branch cannot double-assign; a force-push to an existing branch never re-triggers at all) and **fail-open by contract**: it runs last, after every blocking gate has passed, warns and exits 0 on any API failure, and the hook never gates on its exit code — a failed assignment can never block a legitimate push.
+
+---
+
+## Ring 1 — Branch Rules (what turns the forge red)
+
+Every pull request, on open and on every push, re-runs the same checks in CI:
+
+> **Packaging (task 31, item 3):** every row below except `Typecheck + unit tests` (and the LLM-based claude-review workflow) runs as a sequential **step of one consolidated "AEG gate suite" job** in `.github/workflows/forge-lifecycle.yml`, not as its own job — one checkout/setup/install instead of nine (GitHub bills per-job, rounded up to the minute; the old packaging burned ~9 billed minutes of pure setup overhead per push). Same checks, same strictness, same pass/fail criteria. Independent failure visibility is preserved: every gate step is guarded by `!cancelled()` (an earlier failure never skips a later gate), and each step reports its own red/green in the job's step list.
+
+| CI check | Summary | Category | Description | Re-verifies | implementation |
+| --- | --- | --- | --- | --- | --- |
+| Brief validation | Ever seen a PR title that told you nothing about what changed? | ci | Re-checks in CI that a pull request’s title and brief sections are properly formed. | Title convention (all branches) and every required brief section — on a task branch **or any PR whose body is a brief** (`isBriefShaped`); a PR carrying no brief stays exempt, and `Closes #N` is required only on task branches. Also runnable at authoring time: `verify-brief.ts --body-file <brief.md>`. | `packages/aeg-core/bin/verify-brief.ts` |
+| Closes linkage | Ever had a PR merge and it wasn't clear which ticket it actually closed? | ci | Re-checks that a pull request names the Issue it closes. | A task pull request names, and will close, exactly its planned Issue | `packages/aeg-core/bin/verify-coherence.ts` |
+| Single-plan-PR guard | Ever had two people plan the same work at the same time, unknowingly? | ci | Re-checks that no two open pull requests are planning the same work at once. | The identical ring-0 predicate (`checkSinglePlanPr`) re-run forge-side against this PR's own touched files (via `gh pr view`) and every other open PR's touched files — closes the gap where a web-UI-opened plan PR bypasses `open-pr.ts` entirely. No-ops for an ordinary task-branch PR (never touches a topology file), and dormant altogether where a plan is a Milestone plus Issues rather than a file. | `packages/aeg-core/bin/verify-single-plan-pr.ts` |
+| Coherence check | Ever found a task marked "done" that was never actually merged? | ci | Re-checks every task’s recorded state against what actually merged. | Plan↔forge consistency across the whole repository: tasks closed without a merge, archived without their audit record, orphaned Issues (T2), phantom references, unplanned placeholders in active tranches (T3), duplicate decision numbers, broken document manifests, open task Issues missing a planner-rationale field (R1 — the same grammar the ring-0 Issue gate above enforces at creation). **L5 (open-Milestone-all-closed) surfaces a tranche whose Milestone stayed open after every one of its task Issues closed — advisory (info-only), the forge-native analogue of file-based L1 for post-cutover tranches that no longer carry a topology file (drift class 2; one live incident — the forge-state tranche's Milestone left open after full archive).** **T2 and T3 are CI-scoped to the pull request's own tranche** (parsed from the branch name) — a coherence gap in an unrelated tranche's topology never blocks this pull request (task 19, closing the incident where an unrelated tranche's gap failed CI). **T2 additionally blocks CI only for a plan PR** (task 24 item 4, superseding half of task 19's placement) — the point-of-power principle: a task PR can neither cause nor cure a topology gap, so T2's findings are demoted to non-blocking for every other PR kind, `--json`/audit mode, and `daily-drift` alike (a live incident proved the old placement wrong). The full repo-wide picture (every tranche, unscoped) remains visible in `--json`/audit mode. **The job's repo-state inputs (topology files, tranche list) read from a freshly-fetched `origin/main`, not the checkout's `refs/pull/N/merge`** (task 24 item 5) — GitHub materializes that ref lazily and it can lag behind `main` (5+ false-red cycles, 2026-07-03/04); a plan PR's own topology diff still reads from its head ref. **`id`/`issue` per task now derive from the forge (`@atta/aeg-forge-state`, task 3b) instead of the topology file, falling back to the file if forge derivation fails; `dependsOn`/`conflictsWith` and `#TBD` rows stay file-sourced and are merged onto the forge-derived task list, but only when a topology file still exists.** As of task 7, no active tranche still carries a topology file — every one was deleted once its forge-native replacement was proven live, so `dependsOn`/`conflictsWith` is fully forge-derived for all of them, with no file fallback anywhere. | `packages/aeg-core/bin/verify-coherence.ts` |
+| Documentation gate | Ever shipped a change and forgot to update the doc explaining it? | ci | Re-checks that a change carrying real code also updates the docs explaining it. | Tier declaration and tier-appropriate documentation, including code→document ownership | `packages/aeg-core/bin/verify-docs.ts` |
+| Test-plan state | Ever merged a PR with an unchecked "did you test this" box? | ci | Re-checks that the pull request’s test plan is genuinely ticked. | Unticked test-plan boxes block merge readiness | `packages/aeg-core/bin/verify-test-plan.ts` |
+| Typecheck + unit tests | Ever had a change silently break something it wasn't even touching? | ci | Re-runs the type checker and the unit tests for every package this change can reach. | Packages affected by this PR's diff, plus their full transitive-dependent set (`turbo --affected`; application builds are verified by the deployment pipeline). A diff touching no package (docs/workflow-only) runs 0 packages — sound, since repo-file gates like `verify-docs`/coherence run in their own jobs regardless (task 27) | `.github/workflows/ci.yml` |
+| Conventions | Ever opened a PR full of inconsistent formatting and naming? | ci | Re-checks formatting and naming against the repo’s own conventions. | Lint/format, commit-message grammar, no hardcoded UI colors | `.github/workflows/forge-lifecycle.yml` |
+| AI review | Ever wished every PR got a second pair of eyes, even at 2am? | ci | Puts an automated reviewer on every pull request, whatever the hour. | Posts a judgment review of the change. **Advisory only, including its verdict markers** (ruled 2026-08-09, verdict-author verification): the Review gate below counts a verdict comment only when its author is on the principal allowlist, and this job posts under a bot identity — deliberately excluded, because the job reads the PR's own content, so a crafted PR can steer what it writes; letting its `APPROVE` gate merges would re-open the forged-verdict channel author verification closes. In practice this changes nothing: the gate has only ever flipped on principal-identity verdicts. The bot's review remains visible input to the human/dispatched reviews | `.github/workflows/claude-code-review.yml` |
+| Review gate | Ever had a PR merge with nobody actually approving it? | ci | Holds the merge until the required review verdicts actually exist. | Required, blocking: a task-branch PR must carry a clean code-reviewer `APPROVE` verdict comment AND a clean security-review `PASS` verdict comment before merge — reusing `extractCodeReviewVerdict`/`extractSecurityReviewVerdict` (`packages/aeg-core/src/verdict-extraction.ts`), extracted out of the post-merge Archivist's `archive-task.ts` so both the pre-merge gate and the post-merge provenance assembly read the identical detection logic (one implementation, two call sites). Picks the MOST RECENT comment carrying a clear value, not the first comment merely matching the loose marker pattern — fixed live during this task, since the original single-verdict `.find()` broke on real multi-comment PRs (a `REQUEST_CHANGES` verdict followed by fixes and a later clean `APPROVE`, or the post-merge provenance comment's own DANGLING-note prose, which contains the word "verdict" and would otherwise poison a naive first-match search). **Verdict authors are verified** (2026-08-09): only comments whose author is on the principal allowlist (`PRINCIPAL_ALLOWLIST` — the same trust anchor the waiver actor-check uses) participate in verdict extraction; forged, bot, and unresolvable-author comments are ignored, never fatal — a later forged `APPROVE` can no longer override a real `REQUEST_CHANGES`. A principal-actor-verified `vinaya/waiver:review` label (the same `isWaiverLabelActorVerified` pattern, now parameterized by label name and reused — not duplicated — for this second label) skips the requirement for one PR; label presence alone is never sufficient. **Tool-layer protection extended** (`check-forge-gates.sh`): mutating `vinaya/waiver:review` from an agent session is denied, exactly like `vinaya/waiver:docs` — without this, an agent sharing the Principal's own `gh` credential could self-apply the waiver and inherit the Principal's identity on the labeling event, defeating actor verification entirely (confirmed live during this task before the hook was extended). Non-task branches (plan PRs) bypass — a plan PR touching only topology files has no code to review. Going-forward only: never re-evaluates already-merged history. | `packages/aeg-core/bin/verify-review-gate.ts` |
+| G1 — implementation exists | Ever read about a safeguard that turned out not to actually exist? | ci | Re-checks that every gate the doctrine describes has real code behind it. | Every ring's non-empty `implementation` cell on this very page resolves to a real path on disk — makes this page's registry columns load-bearing instead of decorative. | `packages/aeg-core/bin/verify-registry.ts` |
+| G2 — no orphan hook/CLI | Ever found a script nobody remembers the purpose of? | ci | Re-checks that every hook and CLI in the repo is one the doctrine claims. | Every file under `.husky/*`, `.claude/hooks/*.sh`, `packages/aeg-core/bin/*.ts` is named by some row's `implementation` — the inverse direction of G1: no enforcement mechanism exists off-page. | `packages/aeg-core/bin/verify-registry.ts` |
+| G3 — no seventh way into GitHub | Ever discovered a backdoor that skipped all your checks? | ci | Re-checks that no route into GitHub exists beyond the ones the doctrine gates. | Every file making the exact class of GitHub-mutating call `.claude/hooks/check-forge-gates.sh` itself gates (PR/Issue create, PR/Issue body/title edit, `gh api` create/edit, raw curl/wget writes) is named by some Ring-0 row's `implementation` — a mutating call outside that set would be an unguarded hole in the prevention model. | `packages/aeg-core/bin/verify-registry.ts` |
+| G4 — cited forge numbers resolve | Ever read a doc that cited a ticket number that didn't exist? | ci | Re-checks that every Issue and PR number cited in the docs resolves to a real one. | Every `#NNN` cited anywhere in this page's body is a real Issue or PR in the forge — a fabricated citation fails the build. **Currently scans nothing by design** (task 14): this page's body carries zero forge citations, since task 3 banned them from `aeg-root/**` as doctrine and the `reader-resolvable-prose` check (task 15) now enforces that ban directly. G4 is a standing guard against reintroduction, not a live proof of ongoing citation correctness — it fires the moment a `#NNN` reappears here and doesn't resolve, but has nothing to scan while the ban holds. Verified live: `packages/aeg-core/src/registry-checks.test.ts` appends a fabricated citation to this page's real content and asserts `checkG4` catches it. | `packages/aeg-core/bin/verify-registry.ts` |
+| G5 — role/contract integrity | Ever had a process doc reference a role that was never actually defined? | ci | Re-checks that every role and contract the doctrine references is really defined. | Every `aeg-root/contracts/*.md`'s `producer`/`consumer` names a real `role_id` from `aeg-root/roles/*.md`; every role's `performs`/`refuses_when` frontmatter is present and non-empty. | `packages/aeg-core/bin/verify-registry.ts` |
+| reader-resolvable-prose | Ever read a doc that assumed you already worked here? | ci | Re-checks that reader-facing doctrine and site pages don't cite a forge number/tranche slug the reader can't resolve, or use coined vocabulary without defining it. | Two mechanizable classes over every `aeg-root/**` doc and every public-site `(site)/**/page.tsx`, never `apps/*/specs/**` or a `CLAUDE.md` (this reader has this forge): unresolvable references (a bare forge number, or a `-vN`/legacy tranche slug — the same pattern shapes `retired-vocabulary.test.ts` proved, scoped wider here); and a coined term (`tranche`, `brief`, `forge`, `provenance`, `dispatch`, …) used with neither an inline definition nor a link to the glossary — the term list is derived live from `aeg-root/glossary.md`'s own entry headings, never hard-coded. Registered as the fifth check in `coreCheckRegistry()`, so it ships at both ring 0 (`pre-push --diff-only`) and ring 1 (CI `vinaya check --all`) of any repo `vinaya init` installs into; this repo's own `forge-lifecycle.yml` does not yet route through `vinaya check` for any of its five core checks, so today it runs here only on direct invocation (`vinaya check reader-resolvable-prose` / `--all`). | `apps/vinaya/cli/src/checks/bin/check-reader-resolvable-prose.ts` |
+
+**G-checks rollout (task 3):** G1/G2 ship report-only this tranche — they can only ever print an `info` finding, never fail CI, so pre-existing gaps (four orphan hooks, several orphan `bin/*.ts` CLIs found on first run) surface as visible debt without retroactively failing in-flight work. G3/G4/G5 are blocking from this tranche onward. G1 flips to blocking in a later, separately-dispatched task, once the report-only period has let the orphan backlog get cleaned up.
+
+**reader-resolvable-prose rollout (task 15):** ships report-only, same precedent as G1/G2 above — it can only ever print a `warning` finding, never fail CI (the check's own exit code always stays 0), so the real backlog this run surfaces (161 findings, all class 2, across `aeg-root` and the public site's `(site)` pages on the day this shipped) is visible debt rather than a wave of newly-red pull requests. A later, separately-dispatched task flips it to blocking once that backlog is cleared.
+
+Red CI is now unmergeable by any actor — the repository ruleset's `required_status_checks` rule carries `bypass_actors: []`, so the Principal has no ambient override either. The Principal's override paths are explicit and auditable instead: edit the ruleset itself, or apply an actor-verified `vinaya/waiver:review` label to skip the review gate specifically.
+
+---
+
+## Ring 2 — Audits (drift from any writer, any era)
+
+| Mechanism | Summary | Category | Description | Runs | Catches | implementation |
+| --- | --- | --- | --- | --- | --- | --- |
+| **Post-merge archivist** | Ever wanted a permanent, honest record of exactly what shipped and why? | event | Records what each merged task shipped, from what intent, and checked by whom. | Automatically on every merge to `main` | Every merged task gets its permanent audit record (what shipped, from what intent, checked by whom) and its Issue is closed and verified; any fact that cannot be sourced is flagged as missing, never invented. Task-PR eligibility is an OR of two signals, not branch-name-only: a `task/<tranche>/<id>` branch, OR the closed Issue itself carrying a `vinaya/tranche:*` label — closes a confirmed gap where a tracked Issue closed by an ad-hoc non-task-branch PR silently never got provenance. | `packages/aeg-core/bin/archive-task.ts` |
+| **Coherence oracle, full sweep** | Ever wondered if old, forgotten work is quietly drifting out of sync? | event | Sweeps the whole forge for drift, including work old enough that nobody is watching it. | Every pull request, and on demand | The same plan↔forge drift classes as ring 1, but across all history — including violations that predate the gates | `packages/aeg-core/bin/verify-coherence.ts` |
+| **Docs coherence gate** | Ever clicked a link in your own docs and hit a dead end? | event | Checks that every link and reference in the docs still points at something real. | `verify-docs.ts` full mode, on demand (not yet CI-wired) | Every surfaced doc in the surfaced-doc manifest is reachable in the doc-nav tree, with no orphans and no dangling cross-references | `packages/aeg-core/bin/verify-docs.ts` |
+| **Staleness audits** | Ever had documentation flatly contradict a decision everyone agreed to? | event | Flags documentation that has fallen behind the decisions it is meant to follow. | Dispatched periodically | Documentation whose claims contradict recorded decisions; each contradiction becomes a tracked fix Issue |  |
+| Direct-main-push detection | Ever had someone push straight to main and nobody noticed for a while? | event | Catches pushes that reached main anyway, including from writers the hooks cannot reach. | Every push to `main`, or manual `workflow_dispatch` (task 31) | Whether the pushed commit is introduced by a merged pull request, via the commits→pulls association API. No associated merged PR → opens an incident Issue (`aeg:direct-main-push` label, idempotent per SHA) and **fails the run loudly** — the one ring-2 check in this table that IS allowed to go red, because nothing it does blocks a pull request or a merge; it only makes an already-irreversible direct push visible. **Detection only, never mutation** — no revert, no force-push; permissions are read-only plus `issues: write`, including the `pull-requests: read` the association API requires — as shipped by task 24 that scope was missing, so the job 403'd (`Resource not accessible by integration`) on every real `main` push instead of detecting anything; fixed by task 31 (item 2). | `packages/aeg-core/bin/check-direct-main-push.ts` |
+| Dead-branch-push audit | Ever kept committing to a branch after its PR had already merged? | event | Catches commits still landing on a branch whose pull request already resolved. | Scheduled (`0 2 * * *`) or manual `workflow_dispatch` | Every remote `task/*` branch whose most recent PR already resolved (`MERGED`/`CLOSED`): flags it when the branch's current tip commit is dated strictly after that resolution — commits kept landing on a branch after the forge considered its work done (the exact "six topology rows landed on a merged plan PR's branch" incident class, 2026-07-03, now caught within a day instead of never). `aeg:dead-branch-push` label plus one idempotent tracking comment on the branch's own PR. **Notification only, never a gate** — `continue-on-error: true`. (2026-07-13: this job previously also ran a stuck row-adjacent-blocker check, `stale-blocker.ts`, retired along with the dispatch-gate predicate it watched for.) | `packages/aeg-core/bin/dead-branch-audit.ts` |
+
+---
+
+## Enforcement pairing matrix (task 24 item 6)
+
+A full audit of this page against the installed hooks and CI workflows (2026-07-04) found three gates that existed **only** at ring 0 — invisible to any writer without the local hooks installed (web UI, another tool, a human on a fresh clone, an agent harness without the wiring). This table is the durable record of that audit: every enforcement on this page, its ring coverage, its paired status, and — for anything still a gap — which of the two known gap families it belongs to.
+
+**Two gap families:**
+- **(a) Local-only gates lacking a forge backstop** — a ring-0 mechanism with no ring-1 (CI) or ring-2 (audit) counterpart, so a writer that skips the local hook skips the rule entirely. This task closes three.
+- **(b) Manual CLIs lacking a forcing mechanism** — a tool that mechanizes a check (`verify-dispatch`, `verify-task`) but nothing yet *requires* an agent to run it; an agent can simply skip invoking it. **Closed by task 25**: `verify-dispatch` now runs itself on a task branch's first push (`.husky/pre-push`); `verify-task` now runs itself inside `open-pr.ts` for task branches. Both land at ring 0 only (no ring-1/ring-2 backstop yet) — the same accepted, tracked shape as the branch-ID check below, not a new gap this task opened.
+
+| Enforcement | Ring 0 | Ring 1 | Ring 2 | Paired status | Gap family |
+|---|---|---|---|---|---|
+| Direct push to `main` | ✅ pre-push hook (fail-closed refusal) | — | ✅ **new** — `direct-main-push-detection` job (shipped by task 24 with `pull-requests: read` missing — 403'd on every real push, never actually detected; **permission fixed + made manually triggerable by task 31, item 2**) | **Paired (this task, item 1)** | was (a) — closed |
+| Dead-branch push (stale local work landing on a resolved branch) | ✅ pre-push hook (task 18, fail-open) | — | ✅ **new** — `dead-branch-audit` joins `daily-drift` | **Paired (this task, item 2)** | was (a) — closed |
+| Single-plan-PR guard | ✅ `open-pr.ts` (extracted to `src/single-plan-pr.ts`) | ✅ **new** — `single-plan-pr-gate`, now a step of the AEG gate suite job (task 31) | — | **Paired (this task, item 3)** | was (a) — closed |
+| Orphan-task coherence (T2) | — (no ring-0 form; a CI-only check) | ✅ coherence oracle, **relocated to plan-PRs-only** | ✅ `--json`/audit mode, `daily-drift` (info-only) | Paired (pre-existing); **placement corrected** (this task, item 4) | n/a — not a coverage gap, a point-of-power correction |
+| Coherence oracle repo-state reads | n/a | ✅ now reads fetched `origin/main`, not the merge-ref checkout | ✅ same fix applies to `--json`/audit mode | Paired (pre-existing); **staleness bug fixed** (this task, item 5) | n/a — not a coverage gap, a correctness fix |
+| Branch-ID must match a topology row | ✅ pre-push hook — delegates to aeg-core (`check-branch-topology.ts` → forge-derived Tranche via `deriveTrancheFromForge`, task 3a; originally `parseTranche`, task 32); formerly a hand-rolled grep fork of the same table-parse | — | — | Ring-0 only | **(a) — still a gap, not addressed by this task** |
+| Code→doc ownership (C5) | ✅ pre-push hook + PR-open gate | ✅ `verify-docs --pr`, now a step of the AEG gate suite job (`verify-docs.yml` deleted — task 31) | — | Paired (pre-existing) | not a gap |
+| Brief-section grammar / title convention | ✅ `open-pr.ts`/`open-issue.ts` | ✅ Brief Validation, now a step of the AEG gate suite job (moved out of `archivist.yml` — task 31) | — | Paired (pre-existing) | not a gap |
+| Planner-rationale **content** — blast radius / brief-content / docs-read | ✅ `open-issue.ts` (A/B/D refuse; C warns) | — (no continuous half yet: the checks read `.aeg/packages` + `projects.md`, which CI has, but no oracle check re-runs them over the live Issue stock) | — | Ring-0 only | **gap: no ring-1 half** |
+| Planner-rationale completeness (R1) | ✅ `open-issue.ts` — on `edit`, gate applicability now reads the target Issue's **actual forge labels** (`gh issue view --json labels`, unioned with argv; fetch failure = hard refusal), not just this command's own `--label` flags, which are absent on normal body edits (task 36 — every task-Issue body edit previously bypassed the gate silently) | ✅ coherence oracle's R1 | ✅ `--json`/audit mode | Paired (pre-existing); **edit-path bypass fixed** (task 36) | not a gap |
+| `verify-dispatch` (pre-work readiness) | ✅ **new** — `.husky/pre-push` first-push gate (task branch's first push only; fail-open on forge-unreachable) | — | — | **Forced, ring-0 only (this task, item 1)** | was (b) — closed; ring-1/2 backstop not yet built (same accepted shape as the branch-ID check below) |
+| `verify-task` (pre-PR exit composite) | ✅ **new** — `open-pr.ts` runs it wholesale for task branches (`gatePlanForBranch`); on `edit <n>` the gate set now resolves from the target PR's **actual forge head branch** (`gh pr view --json headRefName`, fetch failure = hard refusal), not the local checkout/`BRANCH` env, which silently skipped `closes-n`/`verify-task` on task-PR body edits from a `main` checkout (task 36 bundled finding) | — | — | **Forced, ring-0 only (this task, item 2)**; **edit-path gate-selection bypass fixed** (task 36) | was (b) — closed; ring-1/2 backstop not yet built (same accepted shape as the branch-ID check below) |
+| Runtime Test Plan checkbox state (`verify-test-plan`) | n/a (CI-only check) | ✅ now a step of the AEG gate suite job (`verify-test-plan.yml` deleted — task 31; still runs on PR-body `edited` events) — **reads `BRANCH`; parses both the inline `**Test Plan:**` marker and the `## N. Test Plan` heading form** (task 25, item 3) | — | Paired (pre-existing); **parser bug fixed** | n/a — not a coverage gap, a correctness fix (a live-fire gap: heading-form sections were never matched, so a task PR with an unticked `[principal]` box advisory-PASSED) |
+| Waiver-label-actor verification (task 29; **extended to `vinaya/waiver:review`, review-gate task 1**) | ✅ **new** — pre-push is warn-only (no `vinaya/waiver:docs`/`vinaya/waiver:review` label can exist before a PR does) **+ tool-layer**: `.claude/hooks/check-forge-gates.sh` denies any agent-session command mutating either label (closes the shared-credential hole — a local agent otherwise acts with the Principal's own `gh` PAT) | ✅ **new** — a GraphQL `LABELED_EVENT`/REST timeline step resolves the label's actor, verified by `isWaiverLabelActorVerified` (now parameterized by label name) and fed into `verify-docs --pr`'s C5 waiver check (`vinaya/waiver:docs`) and `verify-review-gate.ts`'s review check (`vinaya/waiver:review`) | — | **New (this task)**; **extended (review-gate task 1)** | n/a — new mechanism |
+| Review gate — code-reviewer + security-review verdicts (review-gate task 1) | n/a (CI-only check; the underlying verdict comments come from a human, a dispatched reviewer subagent, or the AI-review job) | ✅ **new** — `verify-review-gate.ts`, a step of the AEG gate suite job. Blocks merge unless a clean code-reviewer `APPROVE` AND a clean security-review `PASS` verdict comment exist, or the PR carries an actor-verified `vinaya/waiver:review` label | — | **New (this task)** | n/a — new mechanism (closes the gap where task PRs could previously merge with no review pass at all — the post-merge Archivist's `extractVerdict`/DANGLING flag was advisory-only) |
+
+This table describes **installed mechanisms only** (the page's own change-discipline rule, below). The `verify-dispatch`/`verify-task` rows and the `verify-test-plan` fix landed in task 25's own change set, per that rule.
+
+---
+
+## Portability: what you get on ANY coding agent (or none)
+
+Every check on this page is a plain command-line program — runnable by any human, any agent, any CI, with zero dependency on any vendor. The *triggers* differ by environment:
+
+| Enforcement | Any team, any agent, today | Requires |
+|---|---|---|
+| Commit gates | ✅ Full | git hooks — vendor-neutral |
+| Push gates | ✅ Full | git hooks — vendor-neutral |
+| CI detection | ✅ Full | The forge's CI — vendor-neutral |
+| Post-merge audit | ✅ Full | The forge's CI — vendor-neutral |
+| **Forge command gate** | ⚠️ **Not yet vendor-neutral** | Today it needs a coding-agent harness that can intercept commands before they run (~40 lines of refuse-and-redirect glue on any harness that has such a hook point). The **vendor-neutral form is a wrapper binary placed ahead of the real `gh` on the PATH** — it would work identically for every agent and for humans, and is the planned canonical mechanism. Until it ships, teams without an interceptable harness get prevention at commit/push and detection at CI. |
+| Edit gate | ⚠️ Harness feature | Only meaningful on harnesses with a pre-edit hook; others rely on review and CI |
+
+The design intent, stated plainly: **nothing in AEG's contracts assumes any particular coding agent.** Where a repository's concrete wiring uses one harness's hook system, that is an implementation convenience of that repository — never a requirement of the model. Concrete wiring locations for this repository are recorded in `state-machine.md`'s gate registry.
+
+---
+
+## Known residuals (accepted)
+
+1. **Indirection** — a script file wrapping a raw command, or an exotic API client, escapes command interception. Ring 1 catches the result. The PATH-level wrapper binary above is the hardening if it is ever needed.
+2. **Session-start window** — local gates load when an agent session starts. **Operational rule: restart running agent sessions after merging any change to the gates or their wiring.**
+3. **The judgment layer** — every gate here is deterministic about presence and shape. Whether content is *true* (a file-surface list that matches reality, a test plan that tests the right thing) is irreducibly review work — not yet mechanically wired (the AI review runs but does not block). This is the known next hardening frontier.
+
+---
+
+*Change discipline: this map describes installed mechanisms only. A change that adds, removes, or weakens a gate must update this page in the same change set (the gate code is bound to this page by the document-ownership rule), and the tool-layer gates are a locked decision — weakening them is a reviewed change with its reasoning in the pull request, never a quiet edit.*