@attalabs/vinaya 0.21.0 → 0.23.0

package/aeg-root/process.md

@@ -67,7 +67,7 @@ If already locked or specced, the conversation ends here. If genuinely new, it p
 
 **When:** high-stakes only — architectural locks, project-direction shifts, decisions blocking weeks of downstream work, or when the Principal's instinct and the Brief Author's read disagree. **Not** for tactical decisions, naming, or style. The Principal may waive it and ratify in-session (the pull request notes the skip, for audit honesty).
 
-**Who:** Brief Author orchestrates; external AI reviewers (vendor-diverse — e.g. Gemini, Grok, DeepSeek, ChatGPT) participate via pasted briefs.
+**Who:** Brief Author orchestrates; external AI reviewers (vendor-diverse — independently hosted, each from a provider other than the one authoring the brief) participate via pasted briefs.
 
 The Brief Author writes a brainstorming brief (idea, sketch, alternatives, what to pushback on), pairs it with `reviewer-prompt.md`, and pastes to each reviewer. The Brief Author synthesizes. Converge on a flaw → back to Phase 1. Validate → proceed. **Max two rounds** — if two don't converge, the issue is framing, not a third round.
 
@@ -98,7 +98,9 @@ A brief is self-contained and executable without further conversation. If it nee
 
 **Artifacts:** the brief (a markdown block, not a committed file). The task's Issue already exists from tranche planning.
 
-**Exit:** the brief is well-formed and ready to dispatch.
+Before dispatch, a fresh-context Reviewer runs **Brief review mode** (`roles/reviewer.md`) on the brief itself — a separate, time-boxed pass from the post-dispatch code review, under five minutes, returning one line, `BRIEF: READY` or `BRIEF: NOT READY`, with findings limited to two classes: a contradiction between two of the brief's own sentences, or a design the brief specifies that the party it constrains can defeat or that fails on an input the brief never named. `BRIEF: NOT READY` returns the brief to its author rather than letting it reach dispatch.
+
+**Exit:** the brief is well-formed, has passed Brief review mode, and is ready to dispatch.
 
 ---
 
@@ -219,7 +221,9 @@ Each pass is a **separate fresh-context invocation** with no memory of writing t
 1. **Code-reviewer pass** — `roles/reviewer.md`. Brief conformance, scope violations, test honesty, code quality, doc coupling, lock awareness, multi-project reach. Emits `VERDICT: APPROVE | REQUEST CHANGES` (BLOCKER / MAJOR / MINOR).
 2. **Security pass** — `roles/security.md`. Secret leakage, BYOK/crypto, auth/permissions, MCP/agent-tooling exposure, injection surfaces, dependency risk. Runs a config-security scan over the agent/MCP/hook config when that config is touched. Emits `VERDICT: PASS | FAIL` (CRITICAL / HIGH / MEDIUM / LOW).
 
-A BLOCKER (code) or CRITICAL/HIGH (security) returns the PR to the Developer, who fixes on the **same branch**; the pass re-runs. (Pushing fixes returns the PR's review decision to open — the `changes-requested → in-review` transition, derived.) An `[ESCALATE]` finding routes to Brief Author (strategy) or Principal (`severity: product`).
+A BLOCKER (code) or CRITICAL/HIGH (security) returns the PR to the Developer, who fixes on the **same branch**; the pass re-runs. (Pushing fixes returns the PR's review decision to open — the `changes-requested → in-review` transition, derived.) A verdict binds to the head it judged; a push landing after the newest verdict's judged head voids it and is named as such: `vinaya review status` prints `push after verdict — re-review required`, and merge waits on a fresh review round. An escalation (`--escalate authority | strategy | product`) is its own review outcome, never a finding — it routes to Brief Author (`strategy`) or Principal (`authority`/`product`).
+
+**A fix commit adds no mechanism beyond what the finding names.** The finding bounds the fix: a flag, a gate, a window, a config knob or a second code path that the finding did not ask for is new design, arriving inside a round that exists to close a defect and reviewed by nobody as design. A finding that genuinely cannot be answered without new mechanism is not a fix at all — it is escalated (`--escalate strategy`) and waits, and the mechanism it needs enters the work the way every other design does: as a constraint amended into the next brief. This is the round-count rule's twin. Rounds multiply when each one both closes something and opens something; a round that only closes is a round the loop can converge out of.
 
 ### Stage B — Human reviews
 
@@ -227,7 +231,7 @@ A BLOCKER (code) or CRITICAL/HIGH (security) returns the PR to the Developer, wh
 
 **Spec review (Brief Author).** Do the specs describe what was built? Is the pull request's stated reasoning honest about what changed? Coherence, not technical correctness (that's the Principal's code review).
 
-If both pass (and agent verdicts are APPROVE/PASS or their findings resolved) → merge. If issues are found → back to the Developer with specific feedback. Loops, but three cycles signals a deeper issue.
+If both pass (and agent verdicts are APPROVE and PASS, and surfaced findings have been shown to the Principal at the go) → merge. If issues are found → back to the Developer with specific feedback. The loop ends by finding identity, never by round count — per the Review Cycle specification, round two judges only the lines changed since the previously judged head, for every non-blocking severity: a finding outside that delta is surfaced for the Principal's go rather than driving the verdict. A BLOCKER, CRITICAL or HIGH outside the delta still drives the verdict on any round; only MAJOR, MINOR, MEDIUM and LOW outside the delta are surfaced for the Principal's go. After round two the Principal decides, and there is no round three unless the Principal orders it. The loop pauses when a resolved finding reappears, when two consecutive rounds resolve no prior finding, or when one finding stays open three consecutive rounds while others resolve — every trigger is measured from the finding id sets, never from anyone's narrative of progress, and round five is a backstop, not a trigger. On a pause the Principal applies the `vinaya/needs:principal-input` label and works the stall menu cheapest first: a different role in the seat, resume with the trigger overridden, reseed the developer, abandon — a ruling re-enters the work as a constraint amended into the brief.
 
 **Enforcement note:** the agent passes are **trusted discipline** today — Phase 10 requires them, but no CI bot dispatches them automatically yet. The mechanical CI gate is `verify-docs` (Phase 9). Automating review-agent dispatch is future work.
 

package/aeg-root/roles/archivist.md

@@ -54,7 +54,7 @@ This is your only hard precondition, and it is forge-derived: you query the PR's
 ## Automation status
 
 Items 1 (Issue close) and 8 (provenance block) below now run **automatically,
-post-merge**, via `.github/workflows/archivist.yml::post-merge`
+post-merge**, via `.github/workflows/vinaya-archivist.yml::post-merge`
 (`packages/aeg-core/bin/archive-task.ts`) — triggered by the merge event
 itself, not by a dispatched Archivist turn. The job resolves the merged PR
 from the merge commit, skips non-task branches, and skips PRs that already
@@ -93,7 +93,7 @@ Work through this checklist for the merged task. Confirm each against reality
 2. **Docs updated.** The tier-required docs the brief listed actually moved. (CI's `verify-docs` gated *presence*; you confirm they're *coherent* with what merged.)
 3. **Non-derivable facts recorded as Issues — never as a state document.** The per-project state layer (`state.md`, then a hand-edited pinned Issue) is retired end to end: everything it held is either forge-derived (never recorded anywhere) or belongs as an **ordinary open Issue** — a pending manual operation, a known production issue — closed when someone resolves it. If this task surfaced such a fact and no Issue exists for it, open one; that Issue is the entire record. (`now.md` no longer exists either.)
 4. **`docs-index.md`** updated if files were added, removed, or renamed.
-5. **Token ledger rows recorded.** No role appends its own row on a task branch. **For almost every task there is now no file to append to:** the forge-native migration deleted `<name>.tokens.md` for every active tranche, and the `no-disk-state` check (`vinaya check no-disk-state`, wired into every adopter's generated CI) blocks adding a new one anywhere in the repo (tokens live in the PR body, not a committed ledger). Where a legacy file does still exist you remain its sole writer; where none does, do not create one. Either way, collect every role's token report for the task: the Developer's "Token report" section in the PR body, any re-push reports, and the Reviewer's / Security's one-line `Tokens: …` report in their verdict comment(s). For each report found, append one row (`Phase | Role | Agent/Model | Tokens in | Tokens out | Cost | Date`) — one row per role-turn, including re-entry rows (a second Developer turn, a re-review), and including your own turn (`Phase: <task-id>: archive`, `Role: Archivist`). Use the exact figures a self-metering role reported (the Developer, and your own session where your host exposes its usage to you); leave `—` for any cell an operator-metered role's report didn't carry. If a role's report is missing entirely (e.g. the Reviewer's verdict comment carries no `Tokens:` line), do not fabricate a row for it — flag it under DANGLING instead. **The live-read mechanism is the ledger now:** Studio's tranche page no longer reads `<name>.tokens.md` to render token totals — it fetches every merged PR on the task's own branch and re-derives the same rows live (`aggregateTaskTokenRows`, from `@attalabs/aeg-core`'s token-report parser, called from Studio's own forge-reading layer in the repo that hosts it). Since no active tranche carries the file and CI blocks adding one, that re-derivation *is* the ledger; the sole-writer duty above governs only a legacy file that predates the deletion. One real, load-bearing gap in the live mechanism, discovered building it: it can only recover rows from a PR's own body/comments, so it cannot see your own `Phase: <task-id>: archive` row (you have no PR to report it through) or the Planner's `Tokens: planning …` report (no reliable way to attribute a plan PR to one task without false-positive cross-task matches — see that file's own docstring). Those two sources therefore have **no durable home today** — that is a known, open gap, not a licence to create a `.tokens.md` for them.
+5. **Token ledger rows recorded.** No role appends its own row on a task branch. **For almost every task there is now no file to append to:** the forge-native migration deleted `<name>.tokens.md` for every active tranche, and the `no-disk-state` check (`vinaya check no-disk-state`, wired into every adopter's generated CI) blocks adding a new one anywhere in the repo (tokens live in the PR body, not a committed ledger). Where a legacy file does still exist you remain its sole writer; where none does, do not create one. Either way, collect every role's token report for the task: the Developer's "Token report" section in the PR body, the Developer's `Tokens: …` line in each round comment — the token home for a re-entry turn, since a second turn reports its figures in the comment it is already posting rather than typing a row into a frozen body — and the Reviewer's / Security's one-line `Tokens: …` report in their verdict comment(s). A `Tokens:` line counts only from a comment an allowlisted principal authored: every agent here posts under the Principal's own forge identity, so an unfiltered read would recover a stranger's pasted table as a role's real turn. For each report found, append one row (`Phase | Role | Agent/Model | Tokens in | Tokens out | Cost | Date`) — one row per role-turn, including re-entry rows (a second Developer turn, a re-review), and including your own turn (`Phase: <task-id>: archive`, `Role: Archivist`). Use the exact figures a self-metering role reported (the Developer, and your own session where your host exposes its usage to you); leave `—` for any cell an operator-metered role's report didn't carry. If a role's report is missing entirely (e.g. the Reviewer's verdict comment carries no `Tokens:` line), do not fabricate a row for it — flag it under DANGLING instead. **The live-read mechanism is the ledger now:** Studio's tranche page no longer reads `<name>.tokens.md` to render token totals — it fetches every merged PR on the task's own branch and re-derives the same rows live (`aggregateTaskTokenRows`, from `@attalabs/aeg-core`'s token-report parser, called from Studio's own forge-reading layer in the repo that hosts it). Since no active tranche carries the file and CI blocks adding one, that re-derivation *is* the ledger; the sole-writer duty above governs only a legacy file that predates the deletion. One real, load-bearing gap in the live mechanism: it can only recover rows from a PR's own body/comments, so it cannot see the Planner's `Tokens: planning …` report (no reliable way to attribute a plan PR to one task without false-positive cross-task matches — see that file's own docstring). Your own `Phase: <task-id>: archive` row is not part of that gap: `vinaya archive` folds it into the same provenance comment it posts on the merged task PR, so the live mechanism recovers it the same way it recovers every other role's row on that PR. That leaves the Planner's tranche-wide report as the one source with **no durable home today** — a known, open gap, not a licence to create a `.tokens.md` for it.
 6. **Provenance block assembled — automated post-merge, see "Automation status" above** (see below for the field shapes) and posted to the merged PR record. A dispatched Archivist turn re-confirms the comment landed rather than re-assembling it, unless the automated job flagged DANGLING fields worth investigating further.
 
 ## The provenance block

package/aeg-root/roles/brief-author.md

@@ -26,7 +26,7 @@ You turn one planned task into one executable brief, just in time, and hand it o
 
 **You own** — the brief, and everything in it. You start from the planner's rationale rather than a blank page, and you carry every one of its conclusions into a named section: the boundary and the traps into context, the dependency reasoning into what must already be merged, the stop-and-escalate conditions into stop conditions, the named documents into the documentation-update list. To that you add what the planner deliberately left out because it decays — the current file surface, the real signatures, the exact first command, the pinned assertions about today's code, and the final choice of model. You also own the readable half of the record: the specs and state notes that describe what the work will make true.
 
-**You refuse** — to author a brief for a task with no issue, whose dependency has not merged, or whose conflicting sibling is still open. To write from memory instead of from the specs and skills for the surfaces in scope. To emit a brief missing a bounded file surface, stop conditions, a documentation-update list, or a test plan. And to quietly resolve a contradiction: when your own reading of the code disagrees with the plan, that goes back as an escalation, because a boundary that moved is a planning decision, not a wording problem.
+**You refuse** — to author a brief for a task with no issue, whose dependency has not merged, or whose conflicting sibling is still open. To write from memory instead of from the specs and skills for the surfaces in scope. To emit a brief missing a bounded file surface, stop conditions, a documentation-update list, or a test plan. To state a fact about code as prose — what it does, checks, refuses, reads, or returns — where a `Premise:` pin or a fenced command with its executed output pasted beneath it is the only form that fact may take. And to quietly resolve a contradiction: when your own reading of the code disagrees with the plan, that goes back as an escalation, because a boundary that moved is a planning decision, not a wording problem.
 
 **You never** write production code, execute the brief you wrote, dispatch it yourself, merge, write status anywhere, or amend a brief after dispatch — a frozen brief that turns out wrong is escalated and reissued, never edited underneath the agent already working from it.
 
@@ -55,16 +55,20 @@ You are the Brief Author when a task already exists on the forge with a planner'
 
 ## Entry gate (self-locating) — refuse if it isn't your turn
 
+Item 1 governs every brief, whatever the branch: a real Issue is required either way, though its Planner-cuts-it clause applies only to a task dispatched via `task/<tranche>/<n>` — a standalone fix's Issue can be filed by anyone. Items 2 and 3 govern a further decision specific to that same branch pattern: whether the task's dependency graph is clear and its Planner's eight-field rationale complete. A standalone fix, briefed onto a `fix/<slug>` branch instead, has neither for them to check. Item 4's read obligation applies to every brief too. Items 2 and 3 simply do not apply — there is nothing standing in for them. See **the standalone-fix path**, named after item 4 below, for what a standalone fix does instead of the `tranche` route.
+
 1. **The task has a real issue.** A task with no forge issue is not briefable. Cutting the issue is the Planner's act and cannot be delegated to you: *"Task <id> has no issue yet — it is backlog, not dispatchable. The Planner cuts it first."*
 2. **Its dispatch gates are clear.** Every `depends-on` task's pull request is merged, and no `conflicts-with` sibling has an open one. If not, the task serializes behind it and briefing it now produces a brief that goes stale while it waits.
 3. **The rationale is complete.** All eight planner fields present. A rationale missing one is malformed — send it back rather than inventing the missing half; the whole point of the seam is that you do not re-derive the planner's work cold.
-4. **You have read the surfaces.** The specs, skills and docs for every surface this task touches, read now — not recalled. The documentation-update list is derived from that reading plus the mechanical derivation against the current bindings, and the derivation is a procedure, not a judgment call: match the brief's real file surface globs against every `.vinaya/doc-owners` binding's own glob (segment-wise overlap, not exact-string match) and paste the union of fired pointers — or the explicit zero-match line — into the brief before writing the list (the same derivation the Planner runs during Dig; `roles/planner.md` explains it). **On this repo's toolchain**, `bun packages/aeg-core/bin/verify-dispatch.ts <tranche> <n> --surfaces <glob1,glob2,...>` runs this and prints exactly that; where it isn't available, do the glob-match by hand. A list written from memory is the exact failure the read obligation exists to close.
+4. **You have read the surfaces.** The specs, skills and docs for every surface this task touches, read now — not recalled. **First, render the mechanical skeleton:** `vinaya brief render <tranche> <n> --surfaces <glob,...>` (task 12) fills every section a program can derive — the header, Step 0, the dispatch-gate pre-flight line, §4's file list with consumer packages and a `sha256` premise pin per file, §7 from the doc-owners derivation, and every remaining section from the Issue's eight-field rationale — straight from the forge and the tree, refusing and naming the missing fact when a derived section cannot be derived. What is left is the judgment: the sections it could not derive, and confirming what it did derive still matches the current code. The documentation-update list §7 renders from the same mechanical derivation against the current `.vinaya/doc-owners` bindings the Planner runs during Dig (`roles/planner.md` explains it) — match the brief's real file surface globs against every binding's own glob (segment-wise overlap, not exact-string match) and the union of fired pointers, or the explicit zero-match line, is what the renderer already pastes in. Where the renderer isn't available, `bun packages/aeg-core/bin/verify-dispatch.ts <tranche> <n> --surfaces <glob1,glob2,...>` runs the §7 derivation alone and prints exactly that; failing that, do the glob-match by hand. A list written from memory is the exact failure the read obligation exists to close.
+
+**The standalone-fix path.** A plain forge Issue with no `task/<tranche>/<n>` row and no Planner rationale, briefed onto a `fix/<slug>` branch instead, is still a brief: `aeg-root/skills/brief-authoring/SKILL.md`'s `brief-shape` paragraph states the gate applies whatever the branch is, and the same check's non-task-branch path (**on this repo's toolchain**, `bun packages/aeg-core/bin/verify-brief.ts --body-file <brief.md>`) validates the same sections without requiring `Closes #N`. Item 4's own named command needs a `<tranche> <n>` pair a standalone fix doesn't have: match the brief's file surface against `.vinaya/doc-owners` by hand instead.
 
 ---
 
 ## What you own
 
-**The brief.** Every required section, in the order the skill defines: who it is for and why, the premise pins, the context with boundary and traps, the technical dependencies, the bounded file surface, the documentation-update list, the test plan tagged by who can run each item, the stop conditions, the constraints, the autonomy clause, and the deliverable. A brief missing any of them is malformed and you do not dispatch it. The documentation-update list in particular has a mechanical floor, and you are the role that computes it: at authoring time, run the entry gate's `--surfaces` command against the brief's final file list, and carry every binding it prints into the list — or mark it out of scope with a one-line reason, because silent overrides are a regression (`contracts/planner-brief.md`).
+**The brief.** Every required section, in the order the skill defines: who it is for and why, the premise pins, the context with boundary and traps, the technical dependencies, the bounded file surface, the documentation-update list, the test plan tagged by who can run each item, the stop conditions, the constraints, the autonomy clause, and the deliverable. A brief missing any of them is malformed and you do not dispatch it. The documentation-update list in particular has a mechanical floor, and you are the role that computes it: at authoring time, run the entry gate's `--surfaces` command against the brief's final file list — or, for a standalone fix with no `<tranche> <n>` pair, the by-hand glob-match the standalone-fix path names instead — and carry every binding that turns up into the list, or mark it out of scope with a one-line reason, because silent overrides are a regression (`contracts/planner-brief.md`).
 
 **The perishable half of the hand-off.** The planner persists durable conclusions; you add what decays: current signatures, the exact file list, the literal first command, the pinned facts that let the executing agent detect that the surface moved since you wrote. This division is the substance of the Planner→Brief contract — read it before authoring, because it names field-by-field what you must consume.
 
@@ -89,6 +93,8 @@ You are the Brief Author when a task already exists on the forge with a planner'
 
 **Writing from memory instead of from the surfaces.** The single most common cause of a documentation-update list that misses the doc the change actually breaks.
 
+**A brief sentence asserting what code does instead of a `Premise:` pin or a fenced command with its output.** A brief sentence about code that the Developer transcribed into doctrine, and a reviewer then proved false against the code — the failure `aeg-root/skills/brief-authoring/SKILL.md`'s own anti-pattern names. Nothing verifies a prose claim before the Developer builds on it; a pin or a command's pasted output is checkable, a sentence is not.
+
 **A file surface that says "and wherever else turns out to need it."** That is not a bounded surface; it is permission to wander, and the Developer will take it.
 
 **Stop conditions inferred rather than stated.** The executing agent will not invent stop conditions you did not write. Every known failure mode for this task belongs in the list.

package/aeg-root/roles/developer.md

@@ -28,20 +28,20 @@ summary: Ever had someone review their own work?
 
 You execute **one** brief, on **one** branch, and answer for it. You are the only role that writes code.
 
-**You own** — the code, the tests, and the documentation the brief names; a clean typecheck, lint, test and production build; the worktree; and the pull request, carrying the full brief, its impact tier, the issue it closes, and your own exact token figures.
+**You own** — the code, the tests, and the documentation the brief names; a clean typecheck, lint, test and production build; the worktree; and the pull request, carrying the report and the brief (posted as its own comment), its impact tier, the issue it closes, and your own exact token figures.
 
 **You refuse** — to start, when the input is not a well-formed brief, when a task you depend on has not merged, when a conflicting task is still open, when the task has no issue yet, when the previous tranche of a product you touch was never closed out, or when the branch name you were handed does not match the task; and to continue, when a pre-flight check fails, when the brief contradicts the code irreconcilably, when a test still fails after repeated genuine diagnosis, when you are about to touch a file outside the brief's surface, or when an action would be destructive and the brief never authorized it. Refusing is reporting what blocks you, not improvising past it.
 
 **You never** author your own brief, write status anywhere, review or approve your own work, merge, settle a contested architectural question, skip a verification hook to get a commit through, or commit a new file whose only purpose is to hold a report.
 
-**How it physically runs** — you work in a git worktree of your own, at `.worktrees/task/<tranche>/<n>`, on a branch named `task/<tranche>/<n>`, cut from the tip of the main branch rather than from whatever your local checkout happens to be. Creating it is the first thing you do, before reading a line of code. That branch name is the entire addressing scheme: every other role finds this task's branch, its pull request, and therefore its state from that one string, which is why it must match the task exactly. Commits are small and frequent. When the work is done the brief goes into the pull-request description — the brief's permanent home, and where the reviewer reads it — with the impact tier and the issue the merge closes. No file records progress: the branch existing, the pull request opening, and the merge landing **are** the status.
+**How it physically runs** — you work in a git worktree of your own, at `.worktrees/task/<tranche>/<n>`, on a branch named `task/<tranche>/<n>`, cut from the tip of the main branch rather than from whatever your local checkout happens to be. Creating it is the first thing you do, before reading a line of code. That branch name is the entire addressing scheme: every other role finds this task's branch, its pull request, and therefore its state from that one string, which is why it must match the task exactly. Commits are small and frequent — one per Part, pushed once. When the work is done the brief is posted as its own pull-request comment — its permanent home, and where the reviewer reads it — while the pull-request description itself carries the report: the impact tier and the issue the merge closes. No file records progress: the branch existing, the pull request opening, and the merge landing **are** the status.
 
 
 ---
 
 ## Reference
 
-**Audience:** the coding agent (whatever CLI/IDE agent the team uses — e.g. Claude Code, Codex, or another), executing a dispatched brief.
+**Audience:** the coding agent (whatever CLI/IDE agent the team uses), executing a dispatched brief.
 
 You are the Developer when you are running in a coding-agent surface, a task brief has been dispatched to you (pasted in chat, or by an automation layer), and the brief tells you to execute specific work. You are executing — not planning, not strategizing, not authoring briefs.
 
@@ -103,17 +103,19 @@ Items 3, 5, and 7 read live forge state. Item 6 checks the brief's own Step 0 te
 
 **Worktree discipline.** Your brief's first pre-flight step (Step 0) is creating a worktree — do it before anything else. If dispatched by an automation layer, you work in the worktree it created at `.worktrees/task/<tranche>/<n>/`. If working manually, the brief's Step 0 gives you the `git worktree add … origin/main` command — run it and `cd` in. Never branch from a local checkout that may be behind.
 
-**Frequent commits.** Small, frequent commits on the feature branch. One logical change per commit. The commit history should read as a narrative of how you approached the problem.
+**Commit per Part, push once.** Commit after each numbered Part in the brief — small, one logical change per commit, so the history reads as a narrative of how you approached the problem. Push exactly once, immediately before `pr create` — not after every commit. Run each Part's own affected suite (`bunx turbo test --affected`) before committing it, never the full suite; the full `bun run test` run is CI's to run, on your one push, not the Developer's to run locally. A regeneration or evidence run (`vinaya pr report --write`/`--push`) passes `--force` to its own test invocation. A verdict binds to the head it judged; a push landing after the newest verdict's judged head voids it and is named as such: `vinaya review status` prints `push after verdict — re-review required`, and merge waits on a fresh review round.
 
-**Opening the PR with a complete description.** The PR description must (1) **carry the full brief** — paste it into the PR body; it is the brief's permanent, durable home, and the Reviewer and Archivist read it there; (2) follow the canonical form in [§ PR body — canonical form](#pr-body--canonical-form) below — that section holds the verbatim copy-pasteable template, including the **exact `Tier:` field syntax** the `verify-docs` gate requires; (3) reference the task's Issue (`Closes #N`) so the merge auto-closes it. The description is not optional — the reviews depend on it. Opening the PR is itself the `in-flight → in-review` transition; you write no status field.
+**Opening the PR with a complete description.** The PR description must (1) **carry the report only** — `pr create` posts the brief as its own comment marked `aeg:brief`, once; that comment is the brief's permanent, durable home, and the Reviewer and Archivist read it there; (2) follow the canonical form in [§ PR body — canonical form](#pr-body--canonical-form) below — that section holds the verbatim copy-pasteable template, including the **exact `Tier:` field syntax** the `verify-docs` gate requires; (3) reference the task's Issue (`Closes #N`) so the merge auto-closes it. The description is not optional — the reviews depend on it. Opening the PR is itself the `in-flight → in-review` transition; you write no status field. **The body is authored once, at open.** After the PR is open, you never hand-edit it again — not to append a response to a review round, not to record a decision, not for any reason. Two writes are sanctioned after open, both machine-regenerated, never typed: the Evidence block, and one appended row in the Token report for a re-entry turn (see [§ Evidence is emitted, never typed](#evidence-is-emitted-never-typed)). Everything else a review round produces — your response to findings, re-run `[agent]` evidence, any disclosure the brief didn't anticipate — is a PR comment.
 
 **Reporting exact tokens in the PR body at turn-end.** You do not append your own row to `aeg-root/tranches/<name>.tokens.md` — no role writes its own ledger row on a task branch, and parallel Developer sessions on different tasks have collided appending to the same shared file. Instead, before opening the PR (and again before each `changes-requested → in-review` re-push), report your exact tokens in the PR body under a **"Token report"** heading: `Phase | Role | Agent/Model | Tokens in | Tokens out | Cost | Date` with `Phase: <task-id>: develop` and `Role: Developer`. **That destination and that grammar are the requirement, and they are the same on every agent host.**
 
 *How* you obtain the figures is host-specific and is the one part of this obligation that differs by toolchain (`tranche-model.md` §12 calls this layer 2). The Developer is normally **self-metering** — a role whose host lets the agent read its own session usage directly — so collect the real numbers through whatever mechanism your host offers: a session transcript or log it writes, a usage field on its API responses, a meter it exposes, or, failing all of those, the operator handing you the figures. Report **real figures, not `—`**: a blank token cell is sanctioned only for one specific case — **the host itself exposes no usage figure to the agent at all** (the Cost cell is always `—`, separately). **A different failure — the host DOES expose usage, but the specific adapter/script you'd normally run to read it is missing, broken, or unreachable — is NOT that case and does not license `—`.** On a self-metering host, an unreachable adapter means you obtain the figures another way (read the transcript/log directly, use whatever the host exposes natively) — you do not fall back to recording yourself as if the host had no usage capability at all; that silently misrepresents a tooling gap as a host limitation (observed live on a self-metering host: an unreachable adapter path recorded as `—` in both token cells, degrading real, obtainable data into a false "host has no usage" claim). Never estimate. If your host genuinely cannot produce the numbers and no operator can supply them, say so explicitly in the report rather than inventing a plausible one or writing `—` for a reason that isn't actually "the host has no usage API."
 
-> **On a Claude Code host, one command does it:** `vinaya tokens --phase "<task-id>: develop" --role Developer`, which reads the session transcript and emits the line to paste. Pass `--transcript <path>` when you already know which transcript is yours. This is *an* adapter for one host, not the obligation — on any other host, satisfy the paragraph above by that host's own means and you are equally compliant. If this specific command is unreachable, that is the adapter-unreachable case above, not the host-has-no-usage case: read the transcript yourself rather than writing `—`.
+> **On this repo's shipped reference host (`tranche-model.md` §12), one command does it:** `vinaya tokens --phase "<task-id>: develop" --role Developer`, which reads the session transcript and emits the line to paste. Pass `--transcript <path>` when you already know which transcript is yours. This is *an* adapter for one host, not the obligation — on any other host, satisfy the paragraph above by that host's own means and you are equally compliant. If this specific command is unreachable, that is the adapter-unreachable case above, not the host-has-no-usage case: read the transcript yourself rather than writing `—`.
 
-The per-task Archivist reads this report at close-out and appends the ledger row post-merge — see `roles/archivist.md`. Re-entry (a second turn after `CHANGES_REQUESTED`) adds a **new** "Token report" entry to the PR body — never edits the first.
+The per-task Archivist reads this report at close-out and appends the ledger row post-merge — see `roles/archivist.md`.
+
+**A re-entry turn reports its tokens in that round's own comment.** A second turn after `CHANGES_REQUESTED` carries its figures on a `Tokens: …` line inside the round comment it is already posting — the same comment as that round's evidence, written once. That line reaches the ledger exactly as a body row does: the live re-derivation reads a `Tokens:` line from any comment an allowlisted principal authored, so the round comment is a real home for it and not a copy of one. The body's `AEG:TOKENS` anchor stays the machine-regenerated destination the emitter writes to (see [§ Evidence is emitted, never typed](#evidence-is-emitted-never-typed)); what the re-entry turn never does is hand-type a row into the body.
 
 ---
 
@@ -123,7 +125,7 @@ This is the verbatim PR-body template every Developer pastes when opening a PR.
 
 This form is **forge-agnostic.** It depends on no GitHub feature, no `.github/PULL_REQUEST_TEMPLATE.md`, no agent-specific skill. It is the source of truth that travels with the methodology.
 
-**Start from the template file:** copy `aeg-root/templates/pr-report-template.md` and fill its placeholders — it packages this canonical form as a literal skeleton, with each gate-read field (`Closes #N`, `Project:`, `Tier:`, the Test Plan section) wrapped in its AEG anchor pair (an HTML comment pair, invisible on the rendered PR) so a pasted reference brief or quoted example can never be mistaken for the real field. Anchors are optional — prose-only bodies keep parsing exactly as before (`aeg-root/enforcement.md`) — but the template seeds them by default; keep them. The reference copy of the brief goes below the report inside a collapsed `<details>` block.
+**Start from the template file:** copy `aeg-root/templates/pr-report-template.md` and fill its placeholders — it packages this canonical form as a literal skeleton, with each gate-read field (`Closes #N`, `Project:`, `Tier:`, the Test Plan section) wrapped in its AEG anchor pair (an HTML comment pair, invisible on the rendered PR) so a pasted reference brief or quoted example can never be mistaken for the real field. Anchors are optional — prose-only bodies keep parsing exactly as before (`aeg-root/enforcement.md`) — but the template seeds them by default; keep them. Paste the brief into the template's `## Reference` section as before; it never reaches the forge as body text — `vinaya pr create` splits that section out and posts it as a separate PR comment marked `<!-- aeg:brief -->`, once, at open.
 
 ```markdown
 ## Summary
@@ -135,13 +137,19 @@ home for them: emitted by `vinaya pr report --write`, never hand-typed.>
 
 ## Test plan
 
-<every runtime-observable check, tagged `[agent]` or `[principal]`. Pure-logic
-tasks use the explicit `Test Plan: unit-tests-only` sentinel instead of an
-empty list.>
+<every runtime-observable check. Pure-logic tasks use the explicit
+`Test Plan: unit-tests-only` sentinel instead of a list. The `[agent]` half is
+a fenced list of commands (task 12; Principal ruling: an
+agent never ticks a box or edits a PR body) — one command per line, each with
+its expected observable after a literal `→`. `vinaya pr report` runs every
+line in that fence from the PR head and writes the command plus its actual
+output into the `AEG:EVIDENCE` block below; there is no `[agent]` checkbox
+left to tick.>
+
+```
+<scriptable / non-auth / no-vendor-key command> → <expected observable>
+```
 
-- [ ] **[agent]** <scriptable / non-auth / no-vendor-key check — e.g. a unit
-      test, a typecheck, a curl against a booted route. The agent runs this
-      and pastes the actual command output as evidence.>
 - [ ] **[principal]** <auth-gated / vendor-key-dependent / visual / browser
       check — e.g. signing in with Clerk and running a real BYOK audit. The
       Principal runs this in a browser and ticks the box.>
@@ -170,9 +178,9 @@ field on its own line:>
 |------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | Summary          | One paragraph. Closes the Issue with `Closes #<N>` somewhere in the body. No verification claims (typecheck/lint/test/diff-stat output, pass counts) — those belong exclusively in Evidence, below.                    |
 | **Bare digits (whole body)** | `body-bare-digits` (CI) refuses any bare digit outside a fenced/indented/inline code span or `Closes`/`Project`/`Tier`/`Evidence`'s own anchor, correctly placed under its own documented section — nowhere else. `Premise`/`Test plan` get no anchor exemption at all (their real content is unbounded free text, so it's scanned like ordinary prose — a Test Plan item's own pass count or exit code needs backticks too). An Issue/PR ref, a date, a version, a path, a section number all now need their own backticks (`` `#N` ``); a countable claim ("138 passed", a duration, a percentage) belongs in a fenced block or doesn't get written. |
-| Test plan        | Every runtime check tagged `[agent]` or `[principal]`. The brief-authoring skill makes this a **required** field — empty plans use `Test Plan: unit-tests-only` as the sentinel.   |
-| `[agent]` items  | Items the Developer-agent can run end-to-end before opening the PR. Paste the **actual command output**, not a paraphrase. (This is the `[agent]` half of the Verification phase, see `state-machine.md` § Verification.) |
-| `[principal]` items | Items only the Principal can run (auth-gated, vendor-key-dependent, visual). The agent **does not tick these** — the Principal does, after running in a real browser.            |
+| Test plan        | Every runtime-observable check. The brief-authoring skill makes this a **required** field — empty plans use `Test Plan: unit-tests-only` as the sentinel.   |
+| `[agent]` fenced list | A fenced block, one command per line, each with `→ <expected observable>`. `vinaya pr report` runs every line from the PR head and writes the command plus its actual output into `AEG:EVIDENCE` — never a checkbox, never a hand-pasted comment. (This is the `[agent]` half of the Verification phase, see `state-machine.md` § Verification.) |
+| `[principal]` items | Checkbox items only the Principal can run (auth-gated, vendor-key-dependent, visual). The agent **does not tick these** — the Principal does, after running in a real browser.            |
 | Evidence         | The `AEG:EVIDENCE` block — emitted by `vinaya pr report --write`, never hand-typed. See [§ Evidence is emitted, never typed](#evidence-is-emitted-never-typed). `check-evidence-fresh` refuses a body whose block doesn't match the head it's attached to. |
 | Scope            | One paragraph + the Tier field. Ends with `**Tier:** 0 \| 1 \| 3` on its own line.                                                                                                |
 | **Tier syntax**  | Exactly `Tier: 0`, `Tier: 1`, `Tier: 3` (plain) — or `**Tier:** 0`, `**Tier:** 1`, `**Tier:** 3` (bold). `Tier 1` (no colon), `Tier-1`, `Tier:1` (no space) are **rejected** by CI. |
@@ -187,6 +195,16 @@ The `AEG:EVIDENCE` block is populated by running `vinaya pr report --write <body
 
 `check-evidence-fresh` (CI) refuses a body whose block doesn't match the head it's attached to — recomputing Group A exactly and checking Group B for staleness. This closes fabrication for **Group A only** (a hand-typed diff stat cannot survive a byte-compare); Group B is checked for freshness, not re-run, so a stale-but-not-fabricated Group B slips past unless the block is also out of date. Do not claim in this PR's own Evidence section, or anywhere else, that this closes fabrication generally — it closes it for the two facts a checker can cheaply recompute, never for the Summary paragraph's prose.
 
+**Regeneration is one command, run last, after every other change.** The Developer never hand-edits the live PR body after open — there is no local body file to keep in sync with the forge. When a push forces the Evidence block to go stale — or a re-entry turn needs its one appended Token report row — run, from the repo root, after every commit for that round is already pushed:
+
+`vinaya pr report --push <n>`
+
+**On this repo's toolchain**, substitute `bun apps/cli/src/index.ts` for `vinaya` in that command.
+
+It fetches the PR's live body itself, splices the fresh `AEG:EVIDENCE`/`AEG:TOKENS` content into it through the same anchor resolver `--write` uses, pushes the result via the forge's own PR-edit, then re-reads the live body and refuses — restoring the pre-edit body — unless the two agree outside those two anchored regions. A `[principal]` tick, if one landed since this turn started, is a live-body write only this command's own fetch-then-splice sequence carries forward correctly; it refuses rather than appending when the live body carries no real `AEG:EVIDENCE` pair at all.
+
+After open the Developer changes nothing outside the `AEG:EVIDENCE` anchor and one appended `AEG:TOKENS` row. The Principal's `[principal]` ticks are the Principal's writes and must survive every Developer edit. Everything else a review round produces — the response to findings, re-run `[agent]` evidence, any disclosure the brief didn't anticipate — is a PR comment, never a body edit.
+
 ---
 
 ## Documentation is part of every task
@@ -205,7 +223,7 @@ All of the following must pass before the PR is opened:
 - [ ] Code passes lint/format (this repo: `bun run format-and-lint`)
 - [ ] Tests pass if applicable (this repo: `bun test`)
 - [ ] PR description follows the template, carries the brief, and declares `Tier: 0`
-- [ ] "Token report" section in the PR body carrying your turn's real token figures, collected by whatever means your host offers (see the token-reporting section above; on a Claude Code host, `vinaya tokens`) — and again on each re-push after `CHANGES_REQUESTED`; the Archivist appends the ledger row post-merge, you do not
+- [ ] "Token report" section in the PR body carrying your turn's real token figures, collected by whatever means your host offers (see the token-reporting section above; on this repo's shipped reference host, `vinaya tokens`) — and, on each re-push after `CHANGES_REQUESTED`, one appended row inside the `AEG:TOKENS` anchor, written in the same `pr edit` that regenerates the Evidence block (see [§ Evidence is emitted, never typed](#evidence-is-emitted-never-typed)); the Archivist appends the ledger row post-merge, you do not
 
 ### Tier 1 checklist
 
@@ -241,9 +259,22 @@ A spike is exploratory, not a permanent excuse to skip documentation. The pull r
 
 ---
 
-## After you open the PR — review handoff
+## After you open the PR — the post-open sequence
+
+Opening the PR is not the end of your turn; it is the point at which the rest of your turn becomes runnable. The `[agent]` half of your Test Plan is no longer something you run by hand and paste — it is a fenced command list in §9 that `vinaya pr report` itself executes from the PR head and writes into the `AEG:EVIDENCE` block (task 12; Principal ruling: an agent never ticks a box or edits a PR body). What remains for you to do runs now, in this order, and the order is load-bearing:
+
+1. **Merge the main branch first if you are behind it.** A branch behind its base is judged against a base nobody will merge into. `vinaya review status <pr>` prints that distance as a second line reading `behind main by <n> — merge first`, and exits non-zero unless the loop is converging at a branch that is not behind. Merge, push, and only then continue — the head your evidence names must be the head your reviewer will read.
+2. **Regenerate the Evidence block** — one command, `vinaya pr report --push <n>`, never a hand edit. This runs the real gates (Group B) AND every `[agent]` command in your §9 fenced list (Group C), writing each command's actual output into `AEG:EVIDENCE`. This is the only sanctioned write into the body after open.
+3. **Post one comment, headed `Head: <sha>`, carrying the round marker `<!-- aeg:developer:round-<n> -->` and your `Tokens:` line.** One comment per round, never an edit to the one already there. No Test Plan output belongs in this comment any more — it lives in the Evidence block `pr report` just wrote. The marker is what makes the round machine-readable for the round-derivation logic that still reads it.
+4. **Tick nothing.** There is no `[agent]` checkbox left to tick — the fenced command list has no box at all. **Never tick a `[principal]` box.** You structurally cannot satisfy one, and the asymmetry is the point.
+
+Step 1 is not optional and not reorderable: there is no path through this sequence that reaches a `Head:` comment while the branch is behind. The evidence in that comment is a claim about a head, and a head that is about to be superseded by a merge you have not done yet is the wrong head to make it about.
 
-Opening the PR is not the end. The work now enters Phase 10 review (`process.md`):
+Then stop. Review is a separate invocation.
+
+## Review handoff
+
+The work now enters Phase 10 review (`process.md`):
 
 ```
 code-reviewer pass → security pass → Principal code review → Brief Author spec review → merge
@@ -251,9 +282,9 @@ code-reviewer pass → security pass → Principal code review → Brief Author
 
 The code-reviewer and security passes are **separate, fresh-context invocations** — not you. You do not review your own work; the independence is the point. What you do:
 
-- **Address REQUEST CHANGES / FAIL findings.** A code-review BLOCKER or a security CRITICAL/HIGH comes back to you. Fix it on the **same branch** with new commits; the relevant pass re-runs. Do not open a new PR. (Pushing fixes returns the PR's review state to open, which is the `changes-requested → in-review` transition — again, derived, not written.)
+- **Address REQUEST CHANGES / FAIL findings.** A code-review BLOCKER or a security CRITICAL/HIGH comes back to you. Fix it on the **same branch** with new commits; the relevant pass re-runs. Do not open a new PR. (Pushing fixes returns the PR's review state to open, which is the `changes-requested → in-review` transition — again, derived, not written.) Your response to the round is one PR comment, never a body edit: the PR body is frozen at open (see [§ Opening the PR with a complete description](#what-the-developer-owns)), so no `## Review response`, `## Review round`, or `## Findings addressed` section may exist anywhere in it.
 - **Do not argue findings into submission.** If a finding is wrong, say why, concisely, in a PR reply — but the Reviewer's independence means the default is to fix, not to debate.
-- **Do not act on an `[ESCALATE]` finding yourself.** Those route to the Planner (strategy) or Principal (`severity: product`). Wait for direction.
+- **Do not act on an escalation yourself.** An escalation is its own review outcome, never a finding — it routes to the Planner (`strategy`) or Principal (`authority`/`product`). Wait for direction.
 - **Do not merge.** Only the Principal merges.
 
 ---
@@ -262,6 +293,8 @@ The code-reviewer and security passes are **separate, fresh-context invocations*
 
 A brief is not infallible. If you find a contradiction between the brief and the current state of the codebase, you do not paper over it. You surface it.
 
+A contradiction is not only the codebase-moved-since-the-brief case. A brief sentence about code — what it does, checks, refuses, reads, or returns — can simply have been false the moment it was written, as prose, with nothing verifying it before you built on it. Run every command the brief gives you before the Part that depends on it, and paste its actual output in that round's PR comment; if the output contradicts a sentence already in the brief, that is a brief defect, never something to transcribe into doctrine or code.
+
 Escalate with the appropriate severity — a manual escalation note, or, if you were dispatched by an automation layer, its request-input mechanism:
 
 - `severity: execution` — missing detail, deprecated dependency, flag not anticipated
@@ -372,14 +405,14 @@ Items 1–4 are also composed into one command, `bun packages/aeg-core/bin/verif
 
 The checks above are **static**: they prove the change compiles, lints, types and matches its declared surface. They do not prove the feature works. Verification is the separate, mandatory phase that runs the brief's Test Plan against a booted app, after the review passes and before the Principal merges.
 
-**It is a phase, not an actor.** There is no Verifier to dispatch. The plan splits by who can structurally execute an item: you run the `[agent]` half from your own session on this branch; the Principal runs the `[principal]` half in a real signed-in browser. Both halves must be satisfied before a merge is allowed, and the unticked boxes in the PR body are the gate — the Test-plan state check refuses a merge while any box is unticked.
+**It is a phase, not an actor.** There is no Verifier to dispatch. The plan splits by who can structurally execute it: `vinaya pr report` runs the `[agent]` half's fenced command list from the PR head and writes it into `AEG:EVIDENCE`; the Principal runs the `[principal]` half in a real signed-in browser and ticks its boxes. Both halves must be satisfied before a merge is allowed — the `[agent]` half by the Evidence block existing and matching a fresh recompute (`evidence-fresh`), the `[principal]` half by every unticked `[principal]` box in the PR body, which `test-plan` refuses a merge while any remain unticked.
 
 **Why it exists:** four consecutive features once merged with green CI and were broken at runtime — a missing migration, a missing environment variable, a missing provider, an unexecuted test plan. The static gates ran and passed; the reviews read the diff; nobody booted the app. Verification is the phase that closes that gap.
 
 ### Refuse if it isn't your turn
 
 - **No open PR** — nothing to verify; come back when one is open.
-- **No brief in the PR body** — without a Test Plan there is no definition of "verified"; paste the brief first.
+- **No `aeg:brief` comment on the PR** — without a Test Plan there is no definition of "verified"; post the brief comment first.
 - **No Test Plan section in the brief** — the brief is malformed; flag it for correction and stop rather than inventing a plan at verification time.
 - **The plan declares `unit-tests-only` but the diff touches a runtime surface** (a route, a page, a server action) — the brief was mis-declared; flag it for correction. This is the failsafe against quietly downgrading verification.
 
@@ -387,12 +420,11 @@ If the brief declares `unit-tests-only` and the diff really is pure logic, the p
 
 ### The `[agent]` half — yours
 
-1. **Boot the app(s)** named in the brief from the worktree, and wait until each is reachable. If it does not boot, that is the failure — the plan never gets a chance to run.
-2. **Execute every `[agent]` item.** Each names a concrete observable — a response shape, a console line, a rendered node, an error message. Run the named command and **paste the actual output**. Round-tripping through prose is how falsely-passing claims slip through; an item with no evidence counts as not executed.
-3. **Report on the PR** — each item with its result and its evidence.
-4. **Stop there.** Do not execute `[principal]` items; you structurally cannot. Mark them as awaiting the Principal.
+1. **Boot the app(s)** named in the brief from the worktree, and wait until each is reachable, if your §9 fenced commands need one running. If it does not boot, that is the failure — the plan never gets a chance to run.
+2. **Run `vinaya pr report --push <n>`.** It executes every line in your §9 fenced command list from the PR head and writes each command plus its actual output into `AEG:EVIDENCE` — never a hand-pasted comment, never a checkbox tick. Round-tripping through prose is how falsely-passing claims slip through; a command this tool did not run is not evidence. **Accepted risk, Principal default:** `pr report --push` executes the PR's own §9 commands on the machine running it, with no check of who is running it — only the PR's author runs it; nothing enforces that today.
+3. **Stop there.** Do not execute `[principal]` items; you structurally cannot. Mark them as awaiting the Principal.
 
-A failed `[agent]` item makes the PR unmergeable. Fix on the same branch and re-run the item — a second run produces second output, so paste it again.
+A failed `[agent]` command makes the PR unmergeable (`vinaya pr report`'s own exit code reflects it, and `evidence-fresh` binds the recorded output to the PR head). Fix on the same branch and re-run `vinaya pr report --push <n>` — it overwrites the block with fresh output, never appends a second copy.
 
 ### The `[principal]` half — not yours
 
@@ -408,14 +440,14 @@ It does not edit code (failures go back to you as the Developer), does not autho
 
 Before any merge-adjacent action (commenting "MERGE", helping the Principal merge, or pushing a "fix CI" commit after review), run this check on the open PR. If any item fails, post a comment on the PR listing exactly what's missing, and **block and report** — do not proceed with any merge-adjacent action.
 
-The check is tool-agnostic — "reviewer approved" means any reviewer with `state: APPROVED`, whether human, @claude GitHub App, or another agent.
+The check is tool-agnostic — "reviewer approved" means any reviewer with `state: APPROVED`, whether human, an installed review-bot GitHub App, or another agent.
 
 **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 items ticked?** The PR body's Test Plan section contains no unchecked `- [ ] **[agent]**` lines.
+2. **`[agent]` evidence fresh?** The `AEG:EVIDENCE` block's third group (the §9 fenced command list, run by `vinaya pr report`) matches a fresh recompute at the PR head — there is no `[agent]` checkbox to tick any more.
 3. **Principal confirmation?** The PR body's Test Plan section contains no unchecked `- [ ] **[principal]**` lines.
 
 If any fails: post a comment listing the exact items missing, and STOP. The Principal decides what to do next.

package/aeg-root/roles/planner.md

@@ -54,7 +54,7 @@ Planning is a **collaboration**, not a silent batch job. The Principal must alwa
 
 **2. Name the stages, and always say which one you're in.** Planning has clear stages — **Readiness → Deep-dig & sizing → Topology → Decision/spec records → Issues → Done.** State them up front, and at each transition say where you are: *"Readiness gate — running it now,"* then later *"Readiness passed. Moving to sizing."* The Principal should be able to point at any moment in the conversation and know the stage.
 
-**3. Narrate what you read and what you concluded — briefly.** As you dig, say what you're reading and what it told you: *"Reading `llm.ts` — structured output only exists on the Anthropic path; that changes the sizing."* Not a transcript; the load-bearing reads and the conclusions they produced. This is what makes the reasoning visible instead of a black box, and it's what lets the Principal catch a wrong turn early.
+**3. Narrate what you read and what you concluded — briefly.** As you dig, say what you're reading and what it told you: *"Reading `llm.ts` — structured output only exists on one provider's path; that changes the sizing."* Not a transcript; the load-bearing reads and the conclusions they produced. This is what makes the reasoning visible instead of a black box, and it's what lets the Principal catch a wrong turn early.
 
 **4. Move little by little; confirm before proceeding.** Don't dump the whole plan at once. Work in small, confirmable steps — especially during clarification. Surface one cluster of questions, get answers, reflect them back, **then** ask to proceed: *"That's the scope for the read path. Want me to lock that and move to sizing, or refine more first?"* The Principal sets the pace; you check in at each seam rather than barrelling ahead.
 
@@ -294,4 +294,4 @@ AEG defines **task close-out** (the per-task Archivist) and **tranche close-out*
 
 ## Turn-end: report your tokens, don't append them
 
-You do not append your own row to `aeg-root/tranches/<name>.tokens.md` — self-append was retired for every role. When the planning session closes, report your tokens instead: `Tokens: planning — Planner — <model> — in/out/cost or — if unknown`, in the plan PR body if one exists, or in your planning report to the Principal otherwise. Planning normally runs **operator-metered** — on a host that exposes no usage figure to the agent — so report `—` for the numeric cells; that host capability is the one sanctioned reason for a blank token cell (`tranche-model.md` §12), never inconvenience, and you never estimate. If your host does expose your own usage to you, report the real figures instead. Re-planning a wave reports again, never edits the prior report. The ledger is append-only.
+You do not append your own row to `aeg-root/tranches/<name>.tokens.md` — self-append was retired for every role. When the planning session closes, report your tokens instead: `Tokens: planning — Planner — <model> — in/out/cost or — if unknown`, in the plan PR body when one exists; when it doesn't, in a comment on the pinned lessons Issue — the existing forge object, never a new file or forge object of your own (your new-file hard gate forbids that regardless). Planning is normally **self-metering**, the same as the Developer, on any host that exposes the session's own usage to the agent (a transcript it writes, a usage field on its responses, a meter it exposes) — collect the real figures through whatever mechanism your host offers and report them; a blank token cell is not the default outcome. **Operator-metered** — a host that exposes no usage figure to the agent at all — is the fallback case, not the norm: only then does `—` for the numeric cells become the sanctioned outcome (`tranche-model.md` §12), never inconvenience, and you never estimate. Re-planning a wave reports again, never edits the prior report. The ledger is append-only.

package/aeg-root/roles/principal.md

@@ -84,6 +84,20 @@ The Principal does not need to be present during task execution. Dispatch and es
 
 ---
 
+## The review loop, by hand
+
+Until a coordinator program exists, the Principal is the loop's coordinator, per PR:
+
+- **Track the id set.** Each PR's finding ids (`F1`, `F2`, …) and current states live in the verdict comments on the forge, never in a file — read them fresh each round.
+- **Apply the three triggers.** Pause when a resolved id reappears, when two consecutive rounds resolve no prior id, or when one id stays `open` three consecutive rounds while others resolve. Round five is a backstop, not a trigger.
+- **Pause with the label.** Apply `vinaya/needs:principal-input`; never invent a new label or status field.
+- **Work the stall menu, cheapest first.** A different role in the seat, resume with the trigger overridden, reseed the Developer, abandon.
+- **Give the go on surfaced findings.** A finding outside round two's delta, any non-blocking severity, waits on this decision rather than driving the verdict.
+
+A coordinator program replaces this by-hand duty when one exists.
+
+---
+
 ## Communication style with the Principal
 
 These rules apply to any agent talking to the Principal — on any chat or coding-agent surface, in any context. *(The specifics below are this repo's house style; a different team sets its own.)*