@attalabs/vinaya 0.4.2 → 0.4.3

package/studio-standalone/.worktrees/fix/bump-0.4.3/aeg-root/aeg-manual-flow.md

@@ -0,0 +1,216 @@
+---
+sidebar_title: Manual Flow
+---
+# AEG — Running the Flow by Hand
+
+**Agentic Execution Governance (AEG)**, manual mode. The playbook for running the flow with nothing but a coding agent, a Git forge, and this repo — no orchestration tool required.
+
+Companion to `process.md` (the eleven-phase walkthrough), `state-machine.md` (the constitution), `tranche-model.md` (the tranche + task model), and the `roles/` docs. This file is the operator's guide: what a human does, in what order, calling which agent, with what in hand.
+
+> **AEG is forge-native, orchestrator-independent.** It depends on a Git forge (GitHub/GitLab) the way it depends on git — the forge is its source of truth for execution state. It does **not** depend on any orchestration tool; a human or a thin dispatch script invokes roles. Knowledge flows one way: a tool may know AEG; AEG does not know the tool.
+
+---
+
+## 0. Starting and maintaining an AEG repo (`aeg.sh`)
+
+AEG "init" is not software — it is a **state the repo is in**. A repo is running AEG when **everything the flow references is present**:
+
+1. **The model layer** — `aeg-root/` scaffold (exists ONCE, at the repo root only): `state-machine.md`, `coordination.md`, `process.md`, `aeg-manual-flow.md`, `tranche-model.md`, `roles/`, `skills/` (the AEG skills — canonical home); plus `projects.md` only once multi-project.
+2. **The living-state layer** — forge-native. State only, never the model: active/blocked/next is derived from Issue/branch/PR state, and completed-work history, lessons, per-project operational state, and ratification items live in `git log`/PR history, pinned Issues, and the `needs:principal-input` label respectively.
+3. **The enforcement layer (referenced by the model, so it must travel with it):**
+   - `.aeg/packages` — the static collision-domain list (conflicts are package-level, `tranche-model.md` §5).
+   - the `verify-docs` script (`packages/aeg-core/bin/verify-docs.ts`), run as a step of the `aeg-gate-suite` job in `.github/workflows/forge-lifecycle.yml` — the doc-tier CI gate. The standalone `verify-docs.yml` workflow it once had was consolidated into that job and deleted.
+   - the Issue template restricting Issues to deps / conflicts / project label / ticket link, and the CI check rejecting forbidden planning fields (`tranche-model.md` §9.3).
+   - the generated agent-surface skill view (e.g. `.claude/skills/`) — derived from `aeg-root/skills/`.
+4. At least one tranche file exists, and the role docs are reachable.
+
+You can create that by hand, or use **`aeg.sh`** — one self-contained, downloadable shell script (from the AEG site). It is a **dumb scaffolder**: it writes files, nothing else. It does not dispatch agents, query the forge, or reason — that's a tool's or a human's job. Self-contained (scaffold embedded, no network) so you can read every byte first. It lays down **all four layers above** — not just `aeg-root/` + `aeg-project/` — so the unit it produces is complete: nothing the model references is missing. Subcommands:
+
+```
+aeg init [folder]                       # scaffold the repo (once): model + state + enforcement + skills
+aeg add-project <name> --path <folder>  # register a project (creates/appends projects.md + stubs)
+aeg new-tranche <name>                # create a thin tranche topology file
+aeg generate-skills                     # regenerate the agent-surface skill view from aeg-root/skills/
+```
+
+`init` scaffolds the enforcement layer (`.aeg/packages`, the verify-docs workflow + script, the Issue template/CI check) and the skills alongside `aeg-root/` + `aeg-project/`, because the model docs reference all of them — a unit missing any of them references a gate that isn't there. `add-project` stores the `--path` verbatim (never derives it), refuses to overwrite an existing folder or re-register a name, and on first use promotes a single-project repo to multi-project. `generate-skills` writes the agent-specific skill view (Claude Code's `.claude/skills/`, or another agent's equivalent) from the canonical skills in `aeg-root/skills/` — so the canonical skills travel with the unit and the loadable view is rebuilt, never authored by hand. See `projects.md`. Tasks themselves are **forge Issues**, created by the Planner on the forge — not by `aeg.sh`.
+
+---
+
+## 1. The flow is the product; a tool is optional
+
+AEG is the flow. A tool may *automate the orchestration slice* — collapsing the hand-offs between roles into commands — but it is not the flow, and the flow does not depend on it. Everything below runs by hand: you open your coding agent, name the role, the agent reads its role doc, checks whether it should act now (against forge state), and does the work.
+
+**Manual mode is the teaching mode.** Companies fear AI because work happens invisibly. AEG's hand-offs make the invisible visible: each is a checkpoint where a human sees a risk automation hides — why review is separate from authorship, why the brief is frozen into the PR, why nothing merges without a human, why the reasoning is frozen with the change. Running it by hand once teaches the *why* of every gate.
+
+---
+
+## 2. The task model — Issues + forge-derived status
+
+A **task is a forge Issue.** Its status is never written anywhere — it is **derived by querying the forge**:
+
+| Status | Forge fact |
+|--------|-----------|
+| `todo` | Issue open (assigned or unassigned), no branch — all open tranche tasks are minimum `todo`; `backlog` is project-level only |
+| `in-flight` | branch `task/<tranche>/<n>` exists, no PR |
+| `in-review` | PR open |
+| `changes-requested` | PR open, `reviewDecision: CHANGES_REQUESTED` |
+| `merged` | PR merged (Issue auto-closes) |
+| `blocked` | `vinaya/blocked` label present — wins over every other conclusion |
+| `dropped` | Issue closed `NOT_PLANNED` — decided against, not done |
+| `incoherent` | Issue closed `COMPLETED` with no merged PR — done-but-unprovable, surfaced for a human |
+
+This table is a **reader's summary, not the source.** The authoritative list is `DERIVED_STATUSES` + the ordered `DERIVATION_RULES` in `packages/aeg-core/src/state-machine-model.ts`, rendered live at `/docs/state-machine`; order is load-bearing there in ways a flat table cannot show.
+
+So **no role ever writes status.** Opening the PR *is* the in-review signal; merging *is* the done signal. To see the board you query the forge (`gh pr list`, the Issues view, a project board) — you never read status from a file. The thin tranche file holds only topology (task→issue, dependency/conflict edges); see `tranche-model.md`.
+
+---
+
+## 3. The brief is the unit of context
+
+1. **Context lives in the brief.** If it isn't in the brief, it doesn't exist. An agent never needs to read elsewhere to understand its task.
+2. **The brief is pasted, not committed — and lands in the PR body.** You hand it to the Developer directly (all sections per the `brief-authoring` skill). When the Developer opens the PR, the brief goes into the PR description — its permanent home, attached to the work it governed, read by Reviewer and Archivist. **Never in the Issue** (it would age and attract edits). Retry reuses the same PR body.
+3. **`Ticket:` and `Project:` are reference-only.** `Ticket:` is N↔M provenance (Jira/Linear) — no agent reads it, it's never a substitute for brief context. `Project:` (multi-valued) resolves against `projects.md` to route the agent to the right specs (and is what the Reviewer spec-checks against, and what the Archivist records in the provenance block); omit it in a single-project repo.
+
+---
+
+## 4. Every agent is self-locating
+
+When invoked, an agent does not trust that you called it correctly. It checks two things first: **is this my phase?** (given forge state) and **is my input well-formed?** If either fails, it **refuses or redirects.** Every role has an entry gate.
+
+**Shared state = the forge** (Issue / branch / PR / review / merge) **+ the thin tranche file** (topology). The gates read state that exists whether or not any tool runs. **The PR is the state machine:** no PR yet = not ready to review; open PR = ready to review; merged PR = ready to close out. That's what makes the gates work identically with or without a tool — and why no agent needs to write status.
+
+---
+
+## 4.5. The conversational protocol — how every role talks to the Principal
+
+Self-location (§4) is *what* an agent verifies before acting. The **conversational protocol** is *how* it speaks while it works. It applies to **every conversational role** (the Principal-facing Planner and Brief Author, and the Developer, Reviewer, Security passes), so that across the whole flow the human always knows **who is speaking, what stage they're in, what just happened, and what comes next.** A governed flow that runs silently is illegible; legibility is itself a governance property (it is the same "make the invisible visible" that §1 calls the point of manual mode).
+
+This is a **shared, model-level protocol**. Each role specializes it in its own role doc (the Planner's specialization is in `roles/planner.md` — the first written; Brief Author, Developer, and Reviewer specializations follow as each is modeled). The shared spine, which no role overrides:
+
+1. **Announce the role on entry.** Open by naming who you are and what you're about to do. The Principal should never be unsure which role/mode they're talking to. *"I'm the Planner. I'll turn this intent into a tranche — readiness gate first, then sizing, then the topology and the Issues."*
+
+2. **Name the stages, and always say which one you're in.** State the stages up front; at each transition, say where you are. The Principal should be able to point at any moment and know the stage. *"Readiness — running it now."* … *"Readiness passed. Moving to sizing."*
+
+3. **Narrate the load-bearing reads and the conclusions they produce — briefly.** Say what you're reading and what it told you, when it matters to a decision. Not a transcript; the reads that change the outcome. This is what turns a black box into a visible chain of reasoning, and lets the Principal catch a wrong turn early. *"Reading `llm.ts` — structured output only exists on the Anthropic path; that changes the sizing."*
+
+4. **Move little by little; confirm before proceeding.** Don't dump everything at once. Work in small, confirmable steps — especially during clarification. Surface one cluster, get answers, reflect them back, **then** ask to proceed. The Principal sets the pace; you check in at each seam. *"That's the scope for the read path — lock it and move on, or refine more first?"*
+
+5. **Reflect back before you commit anything durable.** Before writing a decision, a spec change, the topology, or the Issues, play back your understanding in your own words and get a yes. This catches misunderstanding before it becomes a commit.
+
+6. **Signal stage completion clearly — every time, and especially at the end.** When a stage finishes, say so and say what's next. At the end, close out explicitly so the Principal is never left wondering whether it's done: *"Planning complete — topology written, N Issues cut (#…), dispatch order is […]. Nothing else is needed to plan this; the next stage is dispatch, which is yours to trigger."* The single most important line in the protocol is the one that says **"this stage is finished, here is what's next, and here is whose move it is."**
+
+7. **Be clear about durability — never let the Principal think a conclusion lives only in the chat.** Everything you commit is on the forge/repo, permanent, not in conversation memory; if the laptop or the chat vanished, the committed work remains. When you record something, say plainly that it's written and where, so "decided but revisable" is never mistaken for "unsaved."
+
+8. **Proactive coherence status report — before any phase that touches a prior task's archival state.** Before beginning any brief-authoring or execution phase, the chat-surface role MUST proactively report the coherence status of relevant prior tasks to the Principal — not just silently gate-fail on a mismatch. The pattern is **detect-and-INFORM**, not only detect-and-refuse. Do not wait for the Principal to ask. State the status of each predicate for each in-scope prior task, then declare whether the gate passes or fails and what is owed if it fails. Example: *"Before beginning brief for task X, I must report: prior task Y — Issue #N is closed ✓, PR #M is merged to main ✓, provenance block is absent ✗. Gate fails — the Archivist must post the provenance block on PR #M before I can author this brief. Here is what is owed: [list]."* Or, when all predicates pass: *"Prior task Y gate: Issue #N closed ✓, PR #M merged ✓, provenance block present ✓ — gate passes."* This report is mandatory even when the gate passes (one line suffices) — silence is not an acceptable "all good" signal.
+
+Keep all of this **light** — a sentence at each seam, not paragraphs. The goal is a Principal who always feels oriented, never managed. Terse remains the house style (`coordination.md`); this protocol adds **signposting, not verbosity.** A role that runs the whole flow in silence and dumps a result at the end is violating the protocol even if the result is correct — because the Principal could not see, and therefore could not govern, the steps that produced it.
+
+---
+
+## 5. The manual run order
+
+| Step | Role | You hand it | It produces | Entry gate (refuses if…) |
+|------|------|-------------|-------------|--------------------------|
+| 0 | **Planner** (Brief Author mode) | intent + a ticket slice | a tranche: Issues + thin topology file | asked to write one brief / to implement |
+| 1 | **Principal** (you) | an intent / goal | a decision to proceed, a tier | — |
+| 2 | **Brief Author** (Brief Author mode) | the intent + the task's Issue | a brief, all sections | asked to write code instead of a brief |
+| 3 | **Developer** | the brief | a worktree, the work, an open PR (brief in body) | input isn't a well-formed brief; a `depends-on` isn't merged; a `conflicts-with` sibling's PR is open |
+| 4 | **Reviewer (code)** | "review the PR for task N" | VERDICT (APPROVE / REQUEST CHANGES) | no open PR, no brief in the PR body, or it authored the code |
+| 5 | **Security** | "security-review the PR for task N" | VERDICT (PASS / FAIL) | no open PR, or no brief in the PR body |
+| 6 | **Principal + Brief Author** (you) | the verdicts | merge decision (review side) | review passes not done |
+| 7a | **Verification — agent half** (the Developer-agent re-runs) | the brief's §9 Test Plan | every `[agent]` item executed with the actual output posted to the PR | no open PR; no brief in the PR body; no Test Plan; or all items are `[principal]`-only |
+| 7b | **Verification — Principal half** (you, in a browser) | the brief's §9 Test Plan | every `[principal]` checkbox ticked on the PR | no open PR; no brief in the PR body; no `[principal]` items in the Test Plan |
+| 8 | **Principal** (you) | a PR with all Test Plan checkboxes ticked AND review verdicts clean | the merge | any Test Plan checkbox unticked, or review/security verdict unresolved |
+| 9 | **Archivist** | "close out the PR for task N" | a close-out report + provenance block | **PR is not merged** |
+
+Each agent finds the task's PR via the branch convention `task/<tranche>/<n>` and self-locates from forge state. Nobody writes status — the forge already reflects every transition. Every conversational role in this table follows the conversational protocol (§4.5): it announces itself, signposts its stage, and closes out clearly.
+
+> **Verification is a phase, not a new actor.** Steps 7a and 7b are different halves of the **Verification phase** (`roles/developer.md` § Verification), split by who can structurally execute each test-plan item: the Developer-agent runs `[agent]` items because they don't require auth/keys/eyes-on-render; the Principal runs `[principal]` items because they do. Mirror of the chat-vs-terminal token-capture asymmetry. **Doctrine: CI green ≠ app boots ≠ feature works** — a passed review is not a green light to merge; a ticked-checkbox Test Plan is. A brief whose §4 surface is pure-logic declares `Test Plan: unit-tests-only` (a first-class allowed value) and Phase 11 is satisfied by the CI unit-test gate alone — no runtime execution needed.
+
+### Tranche-close trigger
+
+**When the last open task branch for a tranche is merged, the tranche enters Tranche Close** (Phase 13 in `process.md`). Detect this by querying the forge: `gh pr list --state open --json number,headRefName` filtered to branches matching `task/<tranche>/*` — if nothing returns, the tranche's last task has merged.
+
+The Principal **initiates** tranche close explicitly (declares "we're closing this tranche" and hands off to the Planner / Brief Author). The Archivist **may detect** it automatically in future versions — when all task PRs merged and no open branches remain for the tranche. Until then, the Principal's explicit call is the gate.
+
+See `process.md` Phase 13 for the full close-out steps: verify all tasks merged, run a brief retrospective, archive the tranche file, update state docs, ratify pending Type 1 decisions, declare what's next.
+
+### Pre-merge gate (Step 8 prerequisite)
+
+Before the Principal merges (Step 8), any Developer helping merge or pushing a "fix CI" commit after review must run this gate — it is the mechanical check that Verification (Steps 7a + 7b) is actually complete. If any item fails, post a comment on the PR listing exactly what's missing, and **block and report** — do not proceed with merge.
+
+**Tool:** `gh pr view <n> --json reviews,statusCheckRollup,body`
+
+**Check items (all three must pass):**
+
+1. **Reviewer approved?** The JSON `reviews` array contains at least one entry with `state: APPROVED`.
+2. **Test Plan `[agent]` items ticked?** The PR body's Test Plan section contains no unchecked `- [ ] **[agent]**` lines (Step 7a complete).
+3. **Test Plan `[principal]` items ticked?** The PR body's Test Plan section contains no unchecked `- [ ] **[principal]**` lines (Step 7b complete).
+
+If any fails: post a comment listing the exact items missing. The Principal decides whether to proceed.
+
+> **At the end of every role's turn: report your tokens — you do not append your own row** to the tranche's token/cost ledger (`aeg-root/tranches/<name>.tokens.md`). No role writes its own row on a task branch: terminal roles (Developer; Archivist when automated) report exact figures from `/cost` in the PR body; chat roles (Planner, Brief Author, Reviewer, Security) report in their verdict comment or planning report, numeric cells `—` if unknown. The per-task **Archivist** collects every report and appends the rows — Phase, Role, Agent/Model, Tokens in, Tokens out, Cost, Date — post-merge at close-out; never edits a row; re-entry appends. See `tranche-model.md` §12 for the canonical format and the rationale; the file is a §13 append-only artifact.
+
+---
+
+## 6. Per-role entry gates (refusal language)
+
+**Planner** — see `roles/planner.md` (split-vs-combine by verification coupling; plan-integrity gates; the conversational protocol specialization). Refuses single-brief / implement requests; refuses execution metadata in the file or Issue; refuses planning metadata on Issues; refuses to build a conflict scanner; validates every `Project:` against the registry.
+
+**Brief Author** — requires an intent (ideally an Issue). Refuses to implement: *"I author the brief, I don't implement."* Produces a brief per the skill (tier, type, scope, stop conditions, deliverable, optional `Ticket:`/`Project:`).
+
+**Developer**
+- Requires a well-formed brief. If handed a loose prompt → *"This isn't a brief — missing tier / scope / stop-conditions. Get one from the Brief Author."*
+- Checks the gates against the forge before starting: dependency's PR merged? conflicting sibling's PR closed? If not → *"Task N serializes behind <dep/sibling>; not starting."*
+- If `Project:` doesn't resolve against the registry → *"Project 'x' isn't registered."*
+- Worktree Step 0: `git worktree add .worktrees/task/<it>/<n> -b task/<it>/<n> origin/main && cd .worktrees/task/<it>/<n>`, do the work, open the PR.
+- Done-checklist: **the brief (and `Ticket:`/`Project:` lines) is pasted into the PR body.** That's it for state — opening the PR *is* the status transition. The Developer writes no status anywhere.
+
+**Reviewer (code)** — requires an open PR with the brief in its body. Refuses: no PR → *"Nothing to review."* No brief → *"This PR has no brief; I can't judge scope against intent."* Authored it → *"I can't review my own work."* Checks brief-conformance **and** spec-conformance (the `Project:` spec in the unit's `specs/`). Produces APPROVE | REQUEST CHANGES (per `roles/reviewer.md`).
+
+**Security** — same gate as Reviewer; produces PASS | FAIL (per `roles/security.md`).
+
+**Verification** (the phase, two halves, `roles/developer.md` § Verification)
+- Requires an open PR with the brief in its body AND a §9 Test Plan in that brief. Refuses if either is missing — *"This PR has no Test Plan; without one I cannot judge what 'verified' means. Flag the brief malformed (`needs:brief-correction`)."*
+- **Agent half:** the Developer-agent boots the relevant dev server(s) from the PR's branch, runs each `[agent]` item in the Test Plan, and posts the actual command output as evidence on the PR (paraphrase is not evidence). Re-runs after a fix append a new comment; they do not edit the previous one.
+- **Principal half:** the Principal runs each `[principal]` item in a real signed-in browser and ticks the checkbox on the PR. The agent does not tick `[principal]` boxes; the Principal does not tick `[agent]` boxes — the asymmetry is the gate's whole shape.
+- `Test Plan: unit-tests-only` (a first-class allowed value, for pure-logic briefs with no runtime surface in §4) satisfies the phase by the CI unit-test gate alone.
+- Produces ticked checkboxes on the PR and the evidence comments alongside them; writes no status anywhere.
+
+**Archivist** (close-out)
+- Requires a **merged** PR. Refuses: not merged → *"Nothing to close out; merge first."*
+- Confirms: Issue closed (the merge auto-closes it if linked), docs updated, per-project pinned state Issue updated for every project the task listed. Sets the tranche's `Lifecycle: complete` marker and moves the file to `tranches/completed/` when every task is merged (`tranche-model.md` §11). (`now.md` no longer exists.)
+- Assembles the **provenance block** from frozen facts (brief, PR reviews, merge metadata) and posts it to the merged PR (append-only, never a status field) — see `roles/archivist.md`.
+- Flags — does not perform — orphaned branches (branch with no/stale PR) and local worktree removal as cleanup candidates for the human. Writes no status (the merge already is the status).
+- Produces a close-out report listing anything dangling.
+
+*(The Archivist is non-conversational automation; the conversational protocol §4.5 binds the human-facing roles. When the Archivist is run by hand as a conversational pass, it signposts like the rest.)*
+
+---
+
+## 7. What an automation layer adds (and doesn't change)
+
+A tool can automate the steps 2→6 hand-offs: spawn the Developer in a fresh worktree from a brief, stream its work, unblock escalations, and enforce the dependency/conflict gates in code at dispatch. It does **not** change the gates, roles, brief rules, tranche model, task-as-Issue model, or order. If the tool is unavailable, you run the same flow by hand against the forge. The flow is primary; the tool is convenience — and AEG never names it.
+
+---
+
+## 8. Observe mode — the read-only adoption tier
+
+A team will not bet a production repo on a new governance model on day one. So AEG has a lowest-commitment entry: **observe mode** — run the whole flow read-only over a team's *existing* process, enforcing nothing, changing nothing.
+
+In observe mode:
+- The team keeps its existing workflow untouched — its Jira/Linear, its branching, its PR habits. AEG sits *beside* it, not in front of it.
+- The roles run in **advisory** posture: the Reviewer and Security passes produce their verdicts, the Planner can map existing work into a tranche's topology, the Archivist can assemble provenance — but **none of it blocks a merge.** A finding is a comment, not a gate.
+- **Status is still derived** from the forge (read-only) — the board (`gh pr list`, the future AEG UI) renders what's already happening. AEG writes nothing.
+- `verify-docs` and the dispatch gates run in **report-only** mode (surfacing what *would* fail), not blocking.
+
+The value in observe mode is exactly the thing companies are afraid of losing: **visibility without disruption.** The team sees what AEG *would* say — which PRs lack a brief, which changes drift from the spec, which tasks would collide — while nothing is taken away from them. This is the "start with monitoring, not restriction" on-ramp.
+
+From there, adoption **tightens one gate at a time**, along the advisory → enforced gradient already in `state-machine.md` §12: turn on `verify-docs` as blocking, then require the brief-in-PR, then enforce the dispatch gates. Each step is a deliberate decision, not a big-bang switch. Observe mode is the floor; full AEG is the ceiling; a team climbs at its own pace.
+
+A team can sit in observe mode indefinitely and still get the audit-by-construction provenance — which, for a regulated team, may itself be the whole reason to adopt.
+
+---
+
+For the tranche / task / conflict model, see `tranche-model.md`. For the Planner's gates and conversational protocol, see `roles/planner.md`. For authority, tiers, and the advisory→enforced gradient, see `state-machine.md`. For the registry, see `projects.md`. For provenance, see `roles/archivist.md`.

package/studio-standalone/.worktrees/fix/bump-0.4.3/aeg-root/contracts/archivist-tranche-archivist.md

@@ -0,0 +1,92 @@
+---
+sidebar_title: Archivist → Tranche Archivist
+title: Archivist → Tranche Archivist
+order: 5
+contract_id: archivist-tranche-archivist
+description: Carries each task’s close-out record up to the tranche close-out, so a phase can only be called finished once its parts genuinely are.
+status: active
+producer: archivist
+consumer: tranche-archivist
+carrier: pr-provenance-comments, tranche-file
+summary: Ever closed out a big project only to find smaller pieces were never really finished?
+---
+# Contract: per-task Archivist → Tranche Archivist
+
+## The short version
+
+This seam sits between closing out one task and closing out the tranche that contained it. It exists because a tranche's history is only honest if each task's history was completed first.
+
+**What crosses** — the set of merged pull requests, each carrying its own provenance record. That record is what proves a task was genuinely closed out rather than merely merged. Alongside it: a note on the standing lessons thread for any serious finding that was raised in review and merged anyway, so a consciously accepted deviation is available as a pattern later; and a follow-up issue for every finding that the product's specification has gone stale, so the gap outlives the task that found it.
+
+**The hand-off is malformed when** — a merged pull request carries no provenance record. That means the task's close-out never ran, and the tranche's retrospective would then be assembled from a gap rather than a fact. It is malformed in the same way when an accepted deviation left no note, or when a stale-specification finding left no follow-up: in each case something real happened and nothing durable records it.
+
+**What it does not carry** — permission to proceed on partial evidence. A partial close-out is worse than none, because it produces a record that looks complete and is not. It also carries no new judgement: nothing here re-opens, re-reviews or re-decides a merged task; both roles assemble from facts, and neither authors one.
+
+**How it physically runs** — the carrier is the merged pull requests themselves, each with its provenance comment, plus the standing lessons thread and any follow-up issues. Tranche close-out reads them and stops if one is missing, flagging exactly which task's record is incomplete rather than working around it. The retrospective it then writes is a structured projection of those facts — assembled from merged work, recorded lessons and the decisions of the period, never generated from memory.
+
+
+---
+
+## Reference
+
+**Status:** active
+**Seam:** the hand-off from the per-task Archivist (producer) to the Tranche Archivist (consumer).
+**Single source of truth for this seam.** The two role docs do **not** redefine what crosses this boundary — they point here. `aeg-root/roles/archivist.md` (producer side) and `aeg-root/roles/tranche-archivist.md` (consumer side) each reference this file; this file is where the field-by-field hand-off lives, once.
+
+---
+
+## Why this file exists
+
+The per-task Archivist closes out individual tasks; the Tranche Archivist closes out the whole tranche. The Tranche Archivist's close-out is only honest if every per-task Archivist ran correctly — a missing provenance block means a task's history is incomplete, and an incomplete history means the retrospective is assembled from gaps rather than facts. This contract specifies exactly what the per-task Archivist must produce before the Tranche Archivist is authorized to begin, and exactly what the Tranche Archivist reads from those outputs.
+
+The failure mode this prevents: a Tranche Archivist who begins close-out before verifying that every task's per-task Archivist ran, and then assembles a retrospective and tranche provenance block that silently omits a task's history or fabricates fields whose source facts were never produced.
+
+---
+
+## The hand-off carrier
+
+The **set of merged PRs**, each bearing a per-task provenance block comment, plus the **tranche file** at `aeg-root/tranches/<name>.md` which provides the task topology the Tranche Archivist checks against. Every task in the topology must have a merged PR with a provenance block; the absence of either is a gap the Tranche Archivist must flag before proceeding.
+
+---
+
+## The contract — field-by-field mapping
+
+Every output the per-task Archivist produces (left) has exactly one obligation for the Tranche Archivist (right). A task missing any left-column output is a close-out gap — the Tranche Archivist does not proceed with partial evidence.
+
+| per-task Archivist produces (per task) | Tranche Archivist consumes at | What the consumption means |
+|---|---|---|
+| **Provenance block comment** on each merged PR | Entry gate verification | The Tranche Archivist verifies every task PR has a provenance block comment before starting close-out. A missing provenance block means that task's per-task Archivist close-out was incomplete — stop and flag: *"Task N's PR has no provenance block — per-task Archivist did not run for this task. Flag for Principal before proceeding."* |
+| **Lessons Issue comments** for any `BLOCKER`/`MAJOR` findings that merged | Retrospective assembly | The Tranche Archivist reads the pinned lessons Issue's comments since the tranche started and includes the patterns they identify in the retrospective's "What stalled or caused rework" and "Carry-forward lessons" sections. |
+| **Follow-up Issues** opened for `STALE-SPEC` findings | State doc update | The Tranche Archivist notes open follow-up Issues in the relevant pinned state Issue under "Pending manual operations" (or in the output report as DANGLING items). A `STALE-SPEC` finding with no follow-up Issue is a DANGLING item — flag it for the Principal. (`now.md` is retired.) |
+
+**Reading the table:** left is the producer obligation (per-task Archivist role doc and this contract enforce it), right is the consumer obligation (Tranche Archivist role doc and this contract enforce it). The two role docs must not contradict this table.
+
+---
+
+## Producer obligations (the per-task Archivist)
+
+- Post a provenance block comment on every merged task PR — no exceptions. This is the single most critical output: without it, the Tranche Archivist's entry gate fails and close-out cannot proceed.
+- Post a new comment on the pinned lessons Issue for every `BLOCKER` or `MAJOR` finding that was present in the Reviewer's verdict and merged anyway (a deviation). A deviation without a lessons entry is a missed learning.
+- Open a follow-up Issue for every `STALE-SPEC` finding identified by the Reviewer. If the Developer already opened one, confirm it exists; do not open a duplicate.
+- Append one row to the tranche's token ledger at close-out.
+
+## Consumer obligations (the Tranche Archivist)
+
+- Verify every task PR has a provenance block comment before starting. If any is missing, stop and flag — do not proceed with partial close-out. Partial close-out is worse than no close-out: it creates a plausible-looking but incomplete record.
+- Read the pinned lessons Issue's comments since the tranche start date before assembling the retrospective. Carry-forward lessons that appear there but are not reflected in the retrospective are a gap.
+- Note open follow-up Issues in the relevant pinned state Issue (under "Pending manual operations") or in the close-out report as DANGLING items. If a `STALE-SPEC` finding has no follow-up Issue (the per-task Archivist missed it), flag it as DANGLING and open the Issue on behalf of the Principal. (`now.md` is retired.)
+- Do not assemble the tranche retrospective from memory or inference — assemble it from merged PR summaries, the pinned lessons Issue's comments, and the tranche topology file. The retrospective is a structured projection of facts.
+
+---
+
+## Changing this contract
+
+A contract changes **as a unit**. You may not change what the per-task Archivist produces without, in the same change, updating what the Tranche Archivist consumes — because the property that makes the seam sound is that the producer's output side is *identical* to the consumer's input side. Concretely:
+
+- A change to this file is a **Tier 3** change: it alters a cross-role contract, so the reasoning belongs in the pull request that makes it, where the reviewer and the close-out both read it.
+- The same PR that edits this contract must verify both `aeg-root/roles/archivist.md` and `aeg-root/roles/tranche-archivist.md` still point here and still match the table.
+- Never edit one side's role doc to add/drop a hand-off field directly. Add/drop it **here**; the role docs inherit it by reference.
+
+---
+
+*This contract is the seam. The per-task Archivist fills the left column; the Tranche Archivist drains the right. One source of truth, changed as a unit.*

package/studio-standalone/.worktrees/fix/bump-0.4.3/aeg-root/contracts/brief-developer.md

@@ -0,0 +1,140 @@
+---
+sidebar_title: Brief Author → Developer
+title: Brief Author → Developer
+order: 2
+contract_id: brief-developer
+description: Carries a brief to the agent that executes it, so nothing the author knew is left implicit.
+status: active
+producer: brief-author
+consumer: developer
+carrier: pr-body
+summary: Ever handed someone a task and they missed something you thought was obvious?
+---
+# Contract: Brief Author → Developer
+
+## The short version
+
+This seam sits between the brief and the agent that executes it. It exists to close the gap where an author assumes something is obvious and an executor never sees it stated.
+
+**What crosses** — one brief, complete. The exact command that creates the isolated working copy and branch, to be run before anything else. The impact tier, which decides how much documentation and record-keeping the work owes. The projects it touches. The context: what the task is not, and the traps already found. What must exist and be merged before it can start. The bounded file surface it may touch. Pinned assertions about the current code, so a brief written yesterday cannot be executed against a surface that has moved. The documents it must update. The checklist it satisfies before opening a pull request. A test plan, each item marked as one an agent can run or one only a person can. The conditions that stop it. The constraints it may not weigh against convenience.
+
+**The hand-off is malformed when** — any of those is missing. A brief without stop conditions is not a terse brief; it is one whose executor will invent them. A file surface described as "wherever else turns out to need it" is not bounded. A documentation list assembled from memory rather than reading is not a list. It is equally malformed to skim rather than read it, to treat a stop condition as advice, to execute past the file surface because nothing blocked it, or to paraphrase a verification result instead of pasting what the command printed.
+
+**What it does not carry** — status, which is derived from branches and pull requests and never written; the planner's durable reasoning, which crossed the previous seam and lives on the issue; and any authority to amend the brief. The brief is frozen at dispatch; a change to it is an escalation, not an edit.
+
+**How it physically runs** — the carrier is the pull-request body, which holds the brief verbatim. That is the brief's permanent home: the executing agent reads it there, the reviewer reads it there to judge intent against outcome, and the close-out reads it there as evidence. It is never committed into the repository and never stored in the issue, which holds task identity only — a brief kept anywhere durable goes stale before the work starts.
+
+
+---
+
+## Reference
+
+**Status:** active
+**Seam:** the hand-off from the Brief Author (producer) to the Developer (consumer).
+**Single source of truth for this seam.** The two role docs do **not** redefine what crosses this boundary — they point here. `aeg-root/skills/brief-authoring/SKILL.md` (producer side) and `aeg-root/roles/developer.md` (consumer side) each reference this file; this file is where the field-by-field hand-off lives, once.
+
+---
+
+## Why this file exists
+
+A brief is the executable contract between intent and implementation. When the hand-off from Brief Author to Developer is described separately in each role doc, the descriptions drift: the Brief Author believes the Developer will infer certain things; the Developer misses the fields the Brief Author thought were obvious. This contract removes that drift structurally — there is exactly one description of what a brief must carry and what the Developer must do with each field.
+
+The failure mode this prevents: a Developer who starts work without reading the full brief, or who treats stop conditions as suggestions, or who improvises past a surface-map boundary because nothing explicitly blocked them. Every field below is present in every well-formed brief; its absence is a signal the brief is malformed, not that the field is optional.
+
+---
+
+## The hand-off carrier
+
+The **PR body** — which the Developer opens at the start of execution and which carries the full brief verbatim. The brief is not in the Issue (the Issue is task identity + Planner's rationale only). The PR body is the brief's permanent, durable home. The Developer reads the PR body as the brief; the Reviewer and Archivist read it as evidence of intent.
+
+---
+
+## The contract — field-by-field mapping
+
+Every field the Brief Author emits (left) has exactly one named obligation for the Developer (right). A brief missing any left-column field is malformed — the Brief Author refuses to dispatch it. A Developer who drops a right-column obligation is executing incorrectly.
+
+| Brief Author emits | Developer consumes at | What the consumption means |
+|---|---|---|
+| **Worktree step 0** (verbatim `git worktree add` command) | First action before any other command | The Developer must execute this exact command first. No exceptions. Never assume the right branch exists. Before executing it, the Developer independently re-verifies the branch-name suffix literal-matches the topology's `#` column — the same check the Brief Author already ran before writing the command. |
+| **Tier:** field | PR-open checklist + `vinaya/tier:*` label | The Developer sets the matching `vinaya/tier:*` label on the Issue at PR open. The field is binding; the label is the scannable projection. |
+| **Project:** field | PR description + `verify-docs` | The Developer confirms the project resolves against `.vinaya/projects.md`. |
+| **Context** including boundary + traps | Mental model before any code | The Developer reads the boundary ("what this task is NOT") to know what to refuse to build, and the traps to know what not to do. |
+| **Technical Dependencies** | Verify all depends-on are merged | The Developer confirms every named dependency is on `main` before starting. A depends-on not yet merged is a hard stop. |
+| **Technical Surface Map** | Bounds the diff | The Developer touches only files in the surface map. Files outside it are a stop-and-escalate. |
+| **Premise pins (`Premise:` block, mandatory when the surface map names a real code surface)** | Re-asserted before Step 0, via `verify-dispatch --premise <body-file>`; re-asserted again pre-PR via `verify-task` | A failed premise means the surface moved since the brief was authored — the Developer stops and re-digs rather than executing against a stale mental model. This is a stop condition, not a silent re-guess. `checkPremiseCoverage` (Brief Validation) fails a brief with a real code surface and zero premise coverage. |
+| **Documentation-update list** | Self-check before opening PR + Reviewer doc check | The Developer updates every doc named in the list before claiming done. The list is a DoD obligation, not a recommendation — a named doc not updated is a BLOCKER at review. `verify-docs --pr` gates structural presence; the Reviewer gates content correctness. |
+| **Task Done checklist** | Self-check before opening PR | The Developer runs every item before opening the PR. An unchecked item means the PR is not ready. |
+| **Test Plan** tagged `[agent]` / `[principal]` | Runs `[agent]` items; leaves `[principal]` for Principal | The Developer runs every `[agent]` item and posts evidence. Does not tick `[principal]` boxes. |
+| **Stop conditions** | Halt triggers | The Developer stops and posts a blocker comment on the Issue when any condition is met. Never improvises past a stop condition. |
+| **Constraints** | Hard rules during execution | The Developer treats these as absolute — not "guidelines." A violated constraint is a PR that must not merge. |
+
+**Reading the table:** left is the producer obligation (Brief Author enforces it by refusing to dispatch a malformed brief), right is the consumer obligation (Developer role doc and executor protocol enforce it). The two role docs must not contradict this table.
+
+---
+
+## Producer obligations (the Brief Author)
+
+- Every field in the left column above must be present. A brief missing any of them is malformed — the Brief Author refuses to dispatch it.
+- The brief is frozen at dispatch; amendments go through escalation (`severity:execution` or `severity:strategy` depending on what changed).
+- The worktree step 0 command must be exact — branch name, base ref (`origin/main`), and destination path must all be present. The branch name's suffix must literal-match the task's row in the tranche topology file's `#` column — character for character, no added prefix, no case change, no truncation.
+- Stop conditions must be explicit, not inferred. Every known failure mode for this task belongs in the brief's stop conditions — the Developer will not invent stop conditions that aren't stated.
+- The surface map must be bounded and named. "Wherever else turns out to need it" is not a surface map.
+- **The documentation-update list must be populated from reading, not memory.** The Brief Author's Dig must identify and read any relevant specs/skills/docs before drafting it. The list for Tier 1+ must be non-empty unless the surface map genuinely touches no documented surface (state "No doc updates required" explicitly in that case). A list populated from the Planner's rationale alone without the Brief Author's own reading is malformed.
+- **A brief with a real code surface must carry a `Premise:` block pinning at least one checkable fact inside that surface.** A Tier 0 brief with zero code/runtime surface has nothing to pin.
+
+## Task-status coherence precondition — hard STOP before authoring or executing any task
+
+> **SUPERSEDED (2026-07-13).** This precondition (the per-task archival / row-adjacency gate) is no longer a hard-STOP for the Brief Author or the Developer — automated post-merge provenance posting made the drift signal it protected moot. The section below is preserved as historical record — do NOT enforce it.
+
+~~The Brief Author MUST verify this precondition before authoring any task brief. The Developer MUST verify it before step 0. **If any predicate fails for any in-scope prior, STOP and report to the Principal what is owed — do NOT author, do NOT begin work, do NOT rationalize past it.**~~
+
+**The archival bar.** A prior task is "done" when ALL THREE predicates hold:
+1. Its forge Issue is **closed**
+2. Its PR is **merged to main**
+3. Its **provenance block** comment is present on the merged PR (posted by the Archivist)
+
+"PR merged" alone is NOT the bar. A merged PR whose Issue is still open, or whose provenance block is absent, is an incomplete archival — the Archivist has not fully closed out.
+
+**Scope of "prior task" — verify all three predicates for each:**
+- **Mid-tranche task:** every earlier task in the same tranche that this task depends on (direct `depends-on` edges).
+- **First task of an vinaya/tranche:** the entire previous tranche of that product must be archived — all Issues closed, all PRs in main, all tasks with provenance blocks, tranche file in `aeg-root/tranches/completed/`.
+- **ALL tasks:** every cross-tranche dependency declared in the topology (e.g. a task in one project that depends on a task in another, from an earlier tranche) must also satisfy all three predicates.
+
+**Hard STOP language:** *"Prior task [Y] does not pass the coherence gate: Issue #N is [open/closed], PR #M is [merged/unmerged], provenance block is [present/absent]. The Archivist must fully close out task [Y] before this task can proceed. Here is what is owed: [list]."*
+
+**Accepted-backfill never bypasses this gate.** Deferring backfill of historical provenance on **already-closed tranches** is a permitted debt record; proceeding with a new task on an **unarchived active prior** is not. The accepted-gap clause is strictly limited to closed historical tranches; it cannot be cited to bypass the coherence precondition for tasks in an active tranche. An accepted historical backlog is a debt record, not a gate bypass. The coherence precondition applies to active prior tasks; it cannot be waived by citing accepted historical gaps.
+
+The Brief Author's enforcement is at Dig stage, item (c) (see `aeg-root/skills/brief-authoring/SKILL.md`). The Developer's enforcement is at entry gate items 3–5 (see `aeg-root/roles/developer.md`). The Brief Author gate fires one stage earlier than the Developer gate — catching the gap before a brief the Developer will immediately refuse is dispatched.
+
+---
+
+## Consumer obligations (the Developer)
+
+- **Honor the documentation-update list.** Every doc named in the list must be updated as part of the task deliverable — not post-merge cleanup, not a follow-up task. A named doc not updated is a BLOCKER at review. If the list names a doc you cannot find or access, stop and report — do not silently skip it.
+- **Row-existence precondition (hard STOP before step 0).** Before executing step 0, `git fetch origin main`, then confirm this task's row exists at all in its tranche topology file (`aeg-root/tranches/<name>.md`) — read from the freshly-fetched `origin/main`, never a stale local checkout or memory. This is distinct from and prior to the Issue-existence precondition below: a missing row means the plan PR that adds this task has not merged yet. STOP: *"Task <id> is not present in `aeg-root/tranches/<name>.md` on a freshly-fetched `origin/main` — the plan PR that adds it has not merged. Not dispatchable until it does."* This gate is enforced in `aeg-root/roles/developer.md` (entry gate, item 7).
+- **Issue-existence precondition (hard STOP before step 0).** Before executing step 0, locate this task in its tranche topology file (`aeg-root/tranches/<name>.md`) and confirm the Issue column carries a real GitHub Issue number — not `#TBD`, not blank. If it is `#TBD` or blank, the task has no forge Issue and is not dispatchable. STOP: *"Task <id> in tranche `<name>` has no Issue (#TBD) — it is not dispatchable. The Planner must cut the Issue before this task can start."* This gate is enforced in `aeg-root/roles/developer.md` (entry gate, item 3).
+- ~~**Prior-archival precondition (hard STOP before step 0).**~~ **SUPERSEDED (2026-07-13)** — no longer a Developer obligation. See the notice above the task-status coherence precondition section. Preserved as historical record: ~~Before executing step 0, apply the task-status coherence precondition above to every in-scope prior task. Verify all three predicates (Issue closed, PR in main, provenance block present) for each. If any predicate fails for any in-scope prior, STOP: report to the Principal exactly what is owed and do not begin work. If no prior task exists in scope (first task of a fresh tranche with no prior tranche on this product), this check passes trivially. This gate was enforced in `aeg-root/roles/developer.md` (entry gate, item 4) and the coherence signal it read is defined in `aeg-root/contracts/reviewer-archivist.md`.~~
+- **Branch-ID verification precondition (hard STOP before step 0).** Before executing step 0, read this task's row in the tranche topology file and confirm the Step 0 branch-name suffix literal-matches the `#` column — character for character, no added prefix, no case change, no truncation. If it doesn't, STOP: do not create the worktree/branch, report the mismatch to the Brief Author/Principal rather than silently using either name. This is the same check the Brief Author already ran before writing the command — the Developer re-runs it independently rather than trusting the brief was authored correctly. This gate is enforced in `aeg-root/roles/developer.md` (entry gate, item 6).
+- **Mechanized precondition check.** The three preceding preconditions (row-existence, Issue-existence, and the prior-tranche-archival check in `roles/developer.md` entry gate item 5) are all re-derivable in one command: `bun packages/aeg-core/bin/verify-dispatch.ts <tranche> <n>`. Run it before step 0; a `NOT READY` result names the exact failing precondition and is the same STOP described above. (The prior-archival/row-adjacency precondition previously listed here was removed from this composed check.)
+- **Premise re-check (hard STOP before step 0).** If the brief carries a `Premise:` block, re-assert it before step 0 via `verify-dispatch --premise <body-file>` (the body-file being the dispatched brief text). A failed premise means the surface moved since authoring — STOP and re-dig, do not proceed on a stale mental model.
+- Read the full brief before opening the worktree. Not a skim — every section.
+- Execute step 0 first, always. Never branch from `HEAD` of the current local checkout.
+- Verify all dependencies are merged before the first line of code.
+- Stay within the surface map. Files outside it are a stop-and-escalate, not a judgment call.
+- Run every `[agent]` Test Plan item and post the actual command output as evidence. Do not paraphrase verification results.
+- Stop on any stop condition — post a blocker comment, do not improvise.
+- Append one row to the tranche's token ledger at turn-end (before opening PR, and again on each re-push after `CHANGES_REQUESTED`).
+
+---
+
+## Changing this contract
+
+A contract changes **as a unit**. You may not change what the Brief Author emits without, in the same change, updating what the Developer consumes — because the property that makes the seam sound is that the producer's output side is *identical* to the consumer's input side. Concretely:
+
+- A change to this file is a **Tier 3** change: it alters a cross-role contract, so the reasoning belongs in the pull request that makes it, where the reviewer and the close-out both read it.
+- The same PR that edits this contract must verify both `aeg-root/skills/brief-authoring/SKILL.md` and `aeg-root/roles/developer.md` still point here and still match the table.
+- Never edit one side's role doc to add/drop a hand-off field directly. Add/drop it **here**; the role docs inherit it by reference.
+
+---
+
+*This contract is the seam. The Brief Author fills the left column; the Developer drains the right. One source of truth, changed as a unit.*

package/studio-standalone/.worktrees/fix/bump-0.4.3/aeg-root/contracts/developer-reviewer.md

@@ -0,0 +1,106 @@
+---
+sidebar_title: Developer → Reviewer
+title: Developer → Reviewer
+order: 3
+contract_id: developer-reviewer
+description: Carries finished work to its reviewer already accounted for, so review spends itself on judgement rather than on basics.
+status: active
+producer: developer
+consumer: reviewer
+carrier: pr-diff-and-body
+summary: Ever had a reviewer waste time on basics instead of judging the actual work?
+---
+# Contract: Developer → Reviewer
+
+## The short version
+
+This seam sits between finished work and the review of it. It exists so that an independent reviewer spends the session judging the work rather than verifying that it was ready to be looked at.
+
+**What crosses** — one open pull request, and everything that makes it reviewable. The brief in its body, pasted whole rather than summarised, because it is the statement of intent the diff has to be judged against. The impact tier, which sets how deep the review goes. Green checks: the type checker, the linter, the tests and the documentation gate all passing already, so a failure found in review is the work's, not the environment's. A diff that stayed inside the file surface the brief named. A completed checklist. Every test-plan item an agent can run, actually run, with the real command output posted rather than a claim about it. And every document the brief named, updated in the same change.
+
+**The hand-off is malformed when** — the brief is missing, paraphrased or edited; when the checks are red; when the diff reaches outside the named surface; when a checklist item is ticked without evidence; when a test-plan item is claimed rather than shown; or when a promised document did not move. Each of those sends the change back rather than becoming a review finding, because none of them is a judgement call.
+
+**What it does not carry** — the authority to fix anything. The reviewer reports and the author repairs; the reviewer never edits the code, never merges, and never writes status. It also does not carry a second opinion on taste: a change is judged against its brief, the product's specification, and safety, not against how the reviewer would have written it.
+
+**How it physically runs** — the carrier is the open pull request: the diff, plus the body holding the brief. Coverage of the documents a change must touch is already enforced mechanically before review begins, which is why the reviewer's remaining job is the question no check can answer — whether the update is true, or a no-op edit that silenced the gate without describing the change. The verdict lands as comments on the pull request, with a severity on every finding, and a change cannot merge without a clean one.
+
+
+---
+
+## Reference
+
+**Status:** active
+**Seam:** the hand-off from the Developer (producer) to the Reviewer (consumer).
+**Single source of truth for this seam.** The two role docs do **not** redefine what crosses this boundary — they point here. `aeg-root/roles/developer.md` (producer side) and `aeg-root/roles/reviewer.md` (consumer side) each reference this file; this file is where the field-by-field hand-off lives, once.
+
+---
+
+## Why this file exists
+
+A review is only as good as the artifact it reviews. When the Developer hands off an incomplete, CI-failing, or brief-free PR, the Reviewer's independence is wasted — they spend the session verifying basics rather than judging correctness and spec-conformance. This contract removes ambiguity about what "ready for review" means: the Developer cannot open a PR without satisfying the left column; the Reviewer cannot start without verifying the right column.
+
+The failure mode this prevents: a Reviewer who begins reviewing a diff without reading the brief (and therefore judges code rather than intent), or who reviews a red-CI PR (and cannot distinguish the Developer's errors from pre-existing failures), or who accepts a PR that touched files outside the brief's surface map without flagging it as a BLOCKER.
+
+---
+
+## The hand-off carrier
+
+The **open PR** — the diff plus the PR body, which carries the brief verbatim. The PR is the Reviewer's primary artifact. The brief (in the PR body) is the intent document; the diff is the execution; the Reviewer's job is to judge whether the execution matched the intent, safely and correctly.
+
+---
+
+## The contract — field-by-field mapping
+
+Every item the Developer produces in the open PR (left) has exactly one obligation for the Reviewer (right). A PR missing any left-column item is not ready for review — the Reviewer refuses to start and sends it back to the Developer.
+
+| Developer produces in the PR | Reviewer consumes at | What the consumption means |
+|---|---|---|
+| **Brief in PR body** (the frozen brief, pasted verbatim) | Entry — read before looking at the diff | The Reviewer reads the brief first to understand intent, boundary, surface map, and traps. Reviewing a diff without the brief is not a valid review pass. |
+| **Tier:** field in PR body | Determines review depth | Tier 0 → light pass; Tier 1 → standard including spec-conformance; Tier 3 → full including spec and state doc verification. |
+| **CI green** (typecheck, lint, tests, `verify-docs`) | Entry gate | The Reviewer does not start if CI is red. A red CI is a Developer problem, not a Reviewer finding. |
+| **Surface map respected** (diff touches only files named in the brief's surface map) | First diff check | If the diff touches files outside the surface map, that is a BLOCKER finding before reading any logic. |
+| **Task Done checklist ticked** | Confirms Developer self-checked | The Reviewer verifies the checklist is present and ticked. An unticked item that the Reviewer then finds broken is a MAJOR finding. |
+| **`[agent]` Test Plan items run with evidence comment** | Confirms runtime verification | The Reviewer checks that actual command output was posted for every `[agent]` item. Missing evidence = unticked item = MAJOR finding. |
+| **Documentation-update list honored** (every named doc updated in the diff) | Doc coupling check — first diff step after surface-map check | A named doc absent from the diff or present but incorrect is a BLOCKER (it is a DoD obligation, not guidance). `verify-docs` gates structural presence; the Reviewer gates content correctness. |
+| **`.vinaya/doc-owners` coverage (C5) satisfied** — every binding fired by the diff is bound (in-diff doc), URL-acked (`Doc-ack: <pointer> — <note>`), or waived by an actor-verified `vinaya/waiver:docs` label applied by a principal. | Coverage check — *mechanical* via CI; the Reviewer reads it as already-true and moves on. | Coverage presence is mechanical (`verify-docs` C5 fails CI if missing). The Reviewer's job shrinks to **judging correctness of the covered doc**: a passing C5 plus an incorrect / no-op / misleading doc update is still a BLOCKER. A waiver is no longer the author's to grant — it is an actor-verified `vinaya/waiver:docs` label applied by a principal, so there is no deferral line for the Reviewer to judge. The seam is dormant when `.vinaya/doc-owners` is absent or no binding matches; in that case there is nothing for either side to do. |
+
+**Reading the table:** left is the producer obligation (Developer role doc and this contract enforce it), right is the consumer obligation (Reviewer role doc and this contract enforce it). The two role docs must not contradict this table.
+
+---
+
+## Producer obligations (the Developer)
+
+- ~~**Prior-archival precondition satisfied.**~~ **SUPERSEDED (2026-07-13).** This is no longer a Developer producer obligation — the per-task archival / row-adjacency precondition formerly defined in `aeg-root/contracts/brief-developer.md` is removed as a hard-STOP; automated post-merge provenance posting made the drift signal it protected moot.
+- **Documentation-update list honored.** Every doc named in the list must be updated in the diff before opening the PR. A PR with list items outstanding is not ready for review; do not open it and expect the Reviewer to discover the gap.
+- **`.vinaya/doc-owners` coverage satisfied.** For every binding fired by the diff: update the bound doc in this PR; or, for URL bindings, add `Doc-ack: <pointer> — <note>`; or have a principal apply the actor-verified `vinaya/waiver:docs` label — you cannot self-serve it, and there is no body-field waiver grammar anymore. `verify-docs` C5 enforces this mechanically — if it fails CI, do not request review.
+- CI must be green before requesting review. Do not request review with a red CI and expect the Reviewer to begin.
+- The brief must be in the PR body, unmodified — pasted verbatim, not summarized or paraphrased.
+- The diff must touch only files in the brief's Technical Surface Map. Files outside it are a stop-and-escalate before opening the PR, not a finding for the Reviewer to catch.
+- The Task Done checklist must be ticked — all items, with actual verification evidence for each.
+- Every `[agent]` Test Plan item must have an evidence comment posted on the PR — the actual command output, not a paraphrase.
+- One row appended to the tranche's token ledger before opening the PR.
+
+## Consumer obligations (the Reviewer)
+
+- Read the brief before the diff. This is not optional — the brief is the intent document; the diff without the brief is just code.
+- Do not start if CI is red. Post a comment: *"CI is red — returning to Developer. Start review once CI is green."*
+- Check surface map compliance as the first diff-inspection step. A surface map violation is a BLOCKER before any logic review.
+- **Verify documentation-update-list compliance as a BLOCKER gate.** For every doc named in the list, confirm it appears in the diff AND is correct (not just present — `verify-docs` already checks presence). A named doc absent from the diff or present but wrong is a BLOCKER finding before reviewing logic. This is a hard gate, not an advisory; the list is a DoD commitment.
+- **Judge correctness of `.vinaya/doc-owners` coverage.** Coverage *presence* is mechanical — `verify-docs` C5 has already enforced it (or the PR would not be green). Your job is to read each in-diff doc update that satisfied a C5 binding and confirm it actually reflects the code change, not a no-op edit or misleading rewrite that silenced the gate. A passing C5 + an incorrect doc update is a BLOCKER. A doc-coverage waiver is no longer a body field you weigh: it exists only as an actor-verified `vinaya/waiver:docs` label applied by a principal, which is a forge-authenticated human act rather than a parseable string.
+- Produce a structured verdict per `roles/reviewer.md` output format — with severity tags on every finding. A verdict without severity tags is malformed.
+- Do not edit the code. Do not expand scope. Do not approve to be agreeable.
+- Append one row to the tranche's token ledger after posting the verdict (and again on each re-review after `CHANGES_REQUESTED`).
+
+---
+
+## Changing this contract
+
+A contract changes **as a unit**. You may not change what the Developer produces without, in the same change, updating what the Reviewer consumes — because the property that makes the seam sound is that the producer's output side is *identical* to the consumer's input side. Concretely:
+
+- A change to this file is a **Tier 3** change: it alters a cross-role contract, so the reasoning belongs in the pull request that makes it, where the reviewer and the close-out both read it.
+- The same PR that edits this contract must verify both `aeg-root/roles/developer.md` and `aeg-root/roles/reviewer.md` still point here and still match the table.
+- Never edit one side's role doc to add/drop a hand-off field directly. Add/drop it **here**; the role docs inherit it by reference.
+
+---
+
+*This contract is the seam. The Developer fills the left column; the Reviewer drains the right. One source of truth, changed as a unit.*