@attalabs/vinaya 0.4.2 → 0.4.3

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

@@ -0,0 +1,130 @@
+---
+sidebar_title: Planner → Brief Author
+title: Planner → Brief Author
+order: 1
+contract_id: planner-brief
+description: Carries a tranche’s plan down to a single task’s brief, so a task keeps the reasoning that shaped it.
+status: active
+producer: planner
+consumer: brief-author
+carrier: issue-body
+summary: Ever had a plan's key details get lost the moment someone else picked it up?
+---
+# Contract: Planner → Brief Author
+
+## The short version
+
+This seam sits between planning a tranche and writing one task's brief. It exists because a role boundary is where work is lost: the planner does a deep technical pass, and without a contract its conclusions quietly fail to arrive.
+
+**What crosses** — the planner's rationale for one task, written into that task's issue: what the task is and deliberately is not; why it is one task rather than three; every project and shared-package consumer in its blast radius; why each dependency and conflict edge exists; the traps the dig already found; the class of agent the work needs; when the executing agent must stop rather than improvise; and the documents this work will make incoherent. Each has exactly one named home in the brief that consumes it, so a conclusion cannot arrive without a place to land.
+
+**The hand-off is malformed when** — a rationale is missing any of those parts, in which case the planner does not emit it; or when a brief drops one on the floor, in which case the brief is wrong rather than merely thin. It is malformed too when the rationale carries detail that cannot survive the wait — exact signatures, precise file lists — which goes stale between planning and dispatch; re-deriving that fresh is the brief author's half. And when the brief author's own dig contradicts the rationale, that is escalated back, never silently overridden.
+
+**What it does not carry** — the brief itself, which is written later and lives elsewhere; any statement of status, which is derived from the forge and never written down; scheduling or estimates, which belong to whatever tool plans the roadmap; and the freshly pinned facts a brief asserts about current code, which belong entirely to the next seam.
+
+**How it physically runs** — the carrier is the task's issue body. The planner writes the rationale there in a fixed grammar, readable by a person and checkable by a machine alike; an issue whose body does not carry every part is refused at creation, and the same check re-runs against issues already open. The brief author reads it there and writes the brief, which lands in the pull-request body at dispatch. The issue holds the reasoning; the pull request holds the instruction.
+
+
+---
+
+## Reference
+
+**Status:** active
+**Seam:** the hand-off from the Planner (producer) to the Brief Author (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/planner.md` (producer side) and `aeg-root/skills/brief-authoring/SKILL.md` (consumer side) each reference this file; this file is where the field-by-field hand-off lives, once.
+
+---
+
+## Why this file exists
+
+A role boundary is where work is lost. The Planner does a deep technical pass and produces durable conclusions; the Brief Author must consume *every one* of them or the conclusion is dropped and the executing agent walks into a trap the planner already saw. When the hand-off is described separately in each role doc, the two descriptions drift (they already did once — the brief side was missing "Sizing" and "Dependency rationale" that the planner side required). A **contract** removes the drift structurally: there is exactly one description of the seam, and both roles are bound to it.
+
+This is the first of AEG's role-seam contracts. Others (`brief-developer`, `developer-reviewer`, …) follow the same shape as each seam is modeled. A contract is a Class 1 artifact and changes **as a unit** — see "Changing this contract" below.
+
+---
+
+## The hand-off carrier
+
+The Planner's output unit is the **task**, which exists as a forge Issue (identity + metadata + Planner's rationale) and a row in the tranche topology file (Issue link + edges only). The thing that crosses this seam is the **Planner's rationale** block, which the Planner writes into the **Issue body**. The Brief Author reads the rationale from the Issue — the forge artifact — and turns it into the executable brief that lands in the PR body. The tranche file row is a topology pointer (the Issue number); the Issue is the definition.
+
+The Planner persists **durable conclusions** (which do not decay). The Brief Author adds **perishable detail** (current signatures, exact files, final model pick) at dispatch. Neither re-does the other's half; the rationale is the carrier between them, and the Issue is its home.
+
+---
+
+## The contract — field-by-field mapping
+
+Every field the Planner emits in the rationale (left) has exactly one named home in the brief (right). The Planner MUST emit every left-column field; the Brief Author MUST consume every one into the named brief section. A rationale missing a field is malformed (Planner refuses). A brief that drops a field on the floor is malformed (Brief Author error).
+
+| Planner emits (rationale field) | Brief Author consumes it in (brief section) | What the consumption means |
+|---|---|---|
+| **Boundary** (what this task is / is not) | Context + Technical Surface Map | The brief's scope and out-of-surface set are the planner's boundary made concrete against current code. |
+| **Sizing** (passed the four "too big?" tests) | Re-confirmation only | The brief assumes the task is one PR. If the Brief Author's own dig finds it no longer fits (code moved), that is **stop-and-escalate**, not a silent re-split. |
+| **Project(s) + blast radius** (every project/consumer touched) | `Project:` field + blast-radius re-verification in the Done checklist | The brief carries the identical `Project(s)`; the Done checklist re-verifies every blast-radius consumer the planner named. |
+| **Dependency rationale** (why each depends-on / conflicts-with edge) | Technical Dependencies | The brief turns the *why* of each edge into the concrete "what must already exist" preconditions (exports, migrations, capabilities, merged dependencies). |
+| **Traps to avoid** (concrete pitfalls the dig surfaced) | Context + Constraints | The trap becomes an explicit "do NOT do X; do Y instead" the executing agent cannot miss. Highest-value field — never drop it. |
+| **Suggested agent-class** (high/mid/fast + one-line reason) | `For:` + `Reason:` header | The Brief Author confirms or deviates (with stated reason) and makes the **final** model pick. Class is the planner's; pick is the brief's. |
+| **Stop-and-escalate** (when the agent must stop, not improvise) | Stop conditions | The planner's stop conditions are copied into the brief's stop-condition list verbatim in substance. |
+| **Docs to keep coherent** (which specs/skills/docs this task will make incoherent) | the documentation-update list | The Brief Author turns the Planner's named list into the explicit doc-update items. Conditional: if the Planner stated "No docs touched," the list is "No doc updates required (Tier 0)." If the Planner named docs, they are all in the list. Presence-**and-correctness** of the list is the Planner's mechanical obligation, not naming docs from memory: the Planner names intended surfaces and the Brief Author derives the floor at brief-authoring time by matching those surfaces against `.vinaya/doc-owners` (`deriveSection7`), then supplements from the read obligation. Any override of the derived floor (added doc, or a derived pointer marked out of scope) must carry a one-line reason in the brief — silent overrides are a regression. |
+
+**Reading the table:** left is the producer obligation (Planner role doc enforces it), right is the consumer obligation (brief-authoring skill enforces it). The two role docs must not contradict this table; if either needs to change what it emits or consumes, it changes *here*, and both sides update together.
+
+**Premise pinning is deliberately NOT a field in this table.** `verify-dispatch`/`verify-task`'s `Premise:` block is file-content-level, perishable detail — current signatures, current constants — squarely inside the Brief Author's half of the division of labor this contract already describes, not a durable conclusion the Planner should seed as a rationale field. It is governed entirely by the Brief Author → Developer seam (`contracts/brief-developer.md`), not this one.
+
+---
+
+## Rationale grammar
+
+The eight left-column fields above are the rationale's **content**; this section defines its **format** — how a field must be written in the Issue body for it to be machine-detectable. Before this grammar existed the rationale was prose with no defined format; a check cannot parse what has no format.
+
+Two serializations are accepted, case-insensitive, matched by field name (or an established synonym — e.g. `Depends-on` for **Dependency rationale**):
+
+- **Bold-inline:** `**<Field>** — <content>` (e.g. `**Boundary** — …`)
+- **Heading:** `### <Field>` followed by the content on subsequent lines (e.g. `### Traps to avoid`)
+
+A ready-to-fill skeleton of the full eight-field rationale lives at `aeg-root/templates/issue-rationale-template.md` — copy it rather than reconstructing the shape from this section's prose; this section remains the grammar's definition.
+
+**`Dependency rationale` carries one exception to the two-serialization tolerance above: it must be written `**Dependency rationale** — <content>` exactly** — bold-inline only, with the closing `**` immediately after the label, no colon inside the bold (`**Dependency rationale:**` is rejected) and no heading form. This field alone has a downstream consumer beyond the creation gate: `amendRationaleDeps` (`packages/aeg-forge-state/src/amend-rationale-deps.ts`), the only sanctioned way to edit `Depends-on`/`Conflicts-with` after creation, locates the section by the exact anchor `SECTION_HEADER` (`packages/aeg-forge-state/src/parse-rationale-deps.ts`) and refuses any other form. `checkIssueRationale` imports that same constant rather than a second regex, so a body it accepts is always rewritable by `amend-deps` — the two consumers share one grammar for this field. Found live 2026-08-05 on a real task Issue that used the colon form for all eight fields: it passed creation but could not be amended.
+
+A task Issue's body must carry all eight fields in one of these two forms. **Canonical implementation:** `packages/aeg-core/src/issue-validation.ts` (`checkIssueRationale`, `isTaskIssueLabelSet`) — the single grammar/parser, consumed at two enforcement points per `aeg-root/enforcement.md`'s ring model:
+
+- **Ring 0 (creation gate):** `packages/aeg-core/bin/open-issue.ts` refuses to create or edit a task Issue (any Issue labeled `vinaya/tranche:<slug>`) whose body fails `checkIssueRationale`. **It also refuses on three content checks, which grade what the fields *say* rather than that they exist:**
+  - `checkBlastRadiusScope` — if **Boundary** or **Project(s) + blast radius** names a path under a collision domain in `.aeg/packages` that none of the declared projects owns (ownership resolves against `.vinaya/projects.md`), the Issue must declare a second project or carry a `blast-radius-ack: <why one lens is enough>` line. `Project(s)` drives the review fan-out, so an under-declared blast radius under-governs the change. Dormant when `.aeg/packages` is absent.
+  - `checkNoBriefContent` — the body must carry no `## References`, `Technical surface map`, `Premise`, `Step 0`, or `Test Plan` section. Those are Brief-Author artifacts; an Issue is not a brief's home (it would go stale before work starts).
+  - `checkRationaleNamesDocs` — **Docs to keep coherent** and/or **Traps to avoid** must name at least one concrete doc path (`aeg-root/…`, `.claude/skills/…`, `.claude/rules/…`, `apps/<x>/CLAUDE.md`, `apps/<x>/specs/…`, a repo-level `*.md`). A genuinely doc-less surface uses the explicit `no-doc-surface` sentinel — the same shape as `Test Plan: unit-tests-only`. This is the only read-obligation signal a forge write leaves: the skill-check hook fires on file edits, and cutting an Issue edits no file.
+
+  A fourth check, `checkConflictCompleteness`, **warns and never blocks**: two open task Issues naming the same collision domain with no mutual `Conflicts-with` edge. Non-blocking because an Issue declares no precise file surface, so the overlap is a hint, not a fact.
+- **Ring 1/2 (continuous oracle):** `verify-coherence`'s **R1** check re-runs the same function against the live stock of open task Issues, catching bodies edited by ungated writers or predating the gate. Pre-grammar Issues are grandfathered by explicit Issue number (`R1_GRANDFATHERED_ISSUES` in `packages/aeg-core/src/coherence-checks.ts`) — visible as `info`, never blocking.
+
+R1 checks **presence/structure only**; whether the content is correct (sizing actually right, traps actually real) stays the Reviewer's judgment, never CI's.
+
+---
+
+## Producer obligations (the Planner)
+
+- **Cut a real forge Issue for every task before dispatch.** Before the Brief Author can author a brief, the Planner must have replaced any `#TBD` in the topology table's Issue column with a real GitHub Issue number. A `#TBD` entry means the task has no forge Issue — it is neither briefable nor executable regardless of its derived status. The Brief Author hard-STOPs on `#TBD` during Dig; the Developer hard-STOPs at entry gate item 3. Cutting the Issue makes the task forge-addressable and dispatchable; it is a Planner-only act.
+- Emit a rationale block per task containing **all eight left-column fields**. (Enforced in `planner.md` — a task missing its rationale is refused.) The eighth field, **Docs to keep coherent**, must name every spec/skill/doc this task will make incoherent, or state "No docs touched" explicitly. Omitting it forces the Brief Author to populate the documentation-update list from memory — the exact failure the read obligation exists to close.
+- The rationale holds durable conclusions only — no perishable line-level detail (that's the Brief Author's half).
+- `Project(s)` must include every shared-package consumer in the blast radius (the blast-radius rule in `planner.md`).
+- **Read relevant docs before emitting the "Docs to keep coherent" field.** The read obligation requires the Planner to have identified and read the relevant specs/skills/docs before planning. The "Docs to keep coherent" field is only trustworthy if it was derived from reading, not from memory.
+
+## Consumer obligations (the Brief Author)
+
+- Read the rationale first; **start from it, never from a blank page**. (Enforced in `brief-authoring`.)
+- Consume **every** right-column mapping — no field dropped.
+- Add the perishable detail the planner deliberately left out (current signatures, exact file list, final model pick).
+- **Read obligation:** During the Dig, identify and read any specs/skills/docs relevant to this task's code surface. Then (a) surface in Context what the Developer must know from those docs, and (b) populate the documentation-update list from this reading — the Planner's "Docs to keep coherent" field is the starting point, but the Brief Author's own reading may surface additional docs the Planner missed.
+- If the Brief Author's own dig **contradicts** the rationale (the boundary moved, sizing no longer holds), that is a `severity:strategy` escalation back toward the Planner — not a silent override.
+
+---
+
+## Changing this contract
+
+A contract changes **as a unit**. You may not change what the Planner emits without, in the same change, updating what the Brief Author 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 `planner.md` and `brief-authoring/SKILL.md` still point here and still match the table (they should need no field-level edits, since the fields live here — but their references must stay valid).
+- 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 Planner fills the left column; the Brief Author drains the right. One source of truth, changed as a unit.*

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

@@ -0,0 +1,96 @@
+---
+sidebar_title: Reviewer → Archivist
+title: Reviewer → Archivist
+order: 4
+contract_id: reviewer-archivist
+description: Carries a review’s actual findings into the permanent record, so a verdict says what was checked, not just that it passed.
+status: active
+producer: reviewer
+consumer: archivist
+carrier: pr-verdict-comment
+summary: Ever had a vague "looks good" review that told you nothing about what was checked?
+---
+# Contract: Reviewer → per-task Archivist
+
+## The short version
+
+This seam sits between a review and the permanent record of the work it reviewed. It exists because close-out can only be honest if the verdict it reads says what was actually checked.
+
+**What crosses** — the reviewer's verdict, and the merged pull request that carries it. The verdict itself: approved, or changes requested. The findings, each with a severity, so the record can tell a note from a blocker. And the result of the check against the product's own specification — whether the change conforms to it, drifts from it, contradicts it, or reveals that the specification itself is now stale.
+
+**The hand-off is malformed when** — the verdict is absent or unclear, when a finding carries no severity, or when the specification check is simply not stated. A verdict comment missing any of the three is not posted; the reviewer revises it first. "Looks good" is the failure this seam was written against: it tells the record nothing about what was examined, and close-out then has the choice of inventing a field or leaving a hole.
+
+**What it does not carry** — permission to close out an unmerged change. The verdict is not the authorisation; the merge is. Nor does it carry any obligation to re-review: close-out is bookkeeping, not a second opinion, and a merged change is not reopened because the record-keeper would have judged it differently.
+
+**How it physically runs** — the carrier is the verdict comment on the pull request, which becomes a frozen fact once that pull request merges. The verdict line is written bare, on its own line, because it is read by machine as well as by people, and the merge gate requires a clean one. After the merge, close-out reads it from the pull request's own history and copies it into the provenance record. A serious finding that was raised and merged anyway means a deviation was consciously accepted — it is recorded as such, not quietly dropped. A finding that the specification has gone stale becomes a follow-up issue, because it is not a reason to block the merge and must not vanish either.
+
+
+---
+
+## Reference
+
+**Status:** active
+**Seam:** the hand-off from the Reviewer (producer) to the per-task 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/reviewer.md` (producer side) and `aeg-root/roles/archivist.md` (consumer side) each reference this file; this file is where the field-by-field hand-off lives, once.
+
+---
+
+## Why this file exists
+
+Close-out is not a mechanical afterthought — it is the step that makes a tranche's history honest. When the Reviewer's verdict is incomplete (no severity tags, no spec-conformance result, no explicit verdict line), the Archivist cannot assemble the provenance block correctly: they cannot distinguish what was reviewed from what was inferred, what was found from what was missed. This contract removes that ambiguity by specifying exactly what the Reviewer's verdict must contain and exactly what the Archivist reads from it.
+
+The failure mode this prevents: an Archivist who assembles a provenance block with fabricated or inferred fields because the Reviewer's comment was vague; or a BLOCKER finding that merged silently because the Archivist didn't know it existed; or a STALE-SPEC finding that disappeared without a follow-up Issue because no one tracked it.
+
+---
+
+## The hand-off carrier
+
+The **Reviewer's verdict comment** on the open (then merged) PR, plus the **merged PR itself**. The verdict comment is the producer's output; the merge is the trigger that authorizes the Archivist to begin close-out. The Archivist reads the verdict from the PR's review history — it is a frozen fact on the PR record.
+
+---
+
+## The contract — field-by-field mapping
+
+Every item the Reviewer produces in the verdict (left) has exactly one obligation for the per-task Archivist (right). A verdict missing any left-column item is malformed — the Reviewer refuses to post it in that state.
+
+| Reviewer produces | per-task Archivist consumes at | What the consumption means |
+|---|---|---|
+| **Verdict** (`APPROVE` or `REQUEST CHANGES`) | Entry gate | The Archivist only runs close-out on `APPROVE` + merged PRs. A `REQUEST CHANGES` verdict means the task is not done — close-out does not run until the Reviewer posts `APPROVE` and the PR is subsequently merged. |
+| **Finding list** with severity tags (`BLOCKER` / `MAJOR` / `MINOR` / `NIT`) | Provenance block assembly | The Archivist includes the verdict and finding count in the provenance block. A `MAJOR` or `BLOCKER` finding that merged despite being raised means a deviation was approved — the Archivist logs it in the provenance block under DANGLING. |
+| **Spec-conformance result** (`CONFORMS` / `DRIFTS` / `CONTRADICTS` / `STALE-SPEC`) | Provenance block + pinned lessons Issue | `CONTRADICTS` that merged is a `severity:strategy` flag in the provenance block. `STALE-SPEC` triggers a follow-up Issue (the Archivist opens it if the Developer did not) — it is not a reason to block merge, but it must not disappear. |
+
+**Reading the table:** left is the producer obligation (Reviewer role doc and this contract enforce it), right is the consumer obligation (Archivist role doc and this contract enforce it). The two role docs must not contradict this table.
+
+---
+
+## Producer obligations (the Reviewer)
+
+- Every finding must carry a severity tag (`BLOCKER`, `MAJOR`, `MINOR`, or `NIT`). A finding without a tag is malformed — the Reviewer revises the comment before the verdict is considered valid.
+- The verdict line must be the **first line** of the verdict comment, in the exact format specified by `roles/reviewer.md`: `VERDICT: APPROVE | REQUEST CHANGES`.
+- The spec-conformance result must be stated explicitly — `CONFORMS`, `DRIFTS`, `CONTRADICTS`, or `STALE-SPEC`. "Not checked" is not acceptable for Tier 1+ tasks with a named Project.
+- A verdict comment missing any of these three elements is malformed. The Reviewer does not post it.
+- Append one row to the tranche's token ledger after posting the verdict.
+
+## Consumer obligations (the per-task Archivist)
+
+- Do not run close-out on unmerged PRs. The merge is the authorization signal — confirmed by querying the forge, not by reading a status field.
+- Assemble the provenance block from frozen PR facts (brief in PR body, verdict comment, merge metadata) — never fabricate a field whose source fact is absent. A missing source fact is a DANGLING item, not an opportunity to infer.
+- Post the provenance block as a comment on the merged PR (the PR is a frozen truth domain once merged; the provenance block is its permanent record).
+- **The provenance block comment is the forge-derived coherence signal that downstream roles depend on.** The next Developer to start a task in this tranche checks whether the most-recently-merged task PR carries a provenance block before executing step 0 — its absence is a hard STOP that blocks the next task from starting. Post it completely; a partial or absent block does not satisfy the Developer's entry gate (see `aeg-root/roles/developer.md` and `aeg-root/contracts/brief-developer.md`).
+- A `BLOCKER` or `MAJOR` finding present in the verdict of a merged PR means a deviation was approved. Log it in the provenance block under DANGLING and post a new comment on the pinned lessons Issue.
+- A `STALE-SPEC` finding in a merged PR must produce a follow-up Issue if the Developer did not already open one. This is the Archivist's responsibility to ensure it happens.
+- Append one row to the tranche's token ledger at close-out.
+
+---
+
+## Changing this contract
+
+A contract changes **as a unit**. You may not change what the Reviewer produces without, in the same change, updating what the per-task 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/reviewer.md` and `aeg-root/roles/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 Reviewer fills the left column; the per-task Archivist drains the right. One source of truth, changed as a unit.*

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

@@ -0,0 +1,116 @@
+---
+sidebar_title: Tranche Archivist → Planner
+title: Tranche Archivist → Planner
+order: 6
+contract_id: tranche-archivist-planner
+description: Carries a finished tranche’s real outcome to the planning of the next, so no plan is built on a product that no longer exists.
+status: active
+producer: tranche-archivist
+consumer: planner
+carrier: archived-tranche-file, pinned-state-issue, retrospective-comment
+summary: Ever started planning the next phase on outdated info about the last one?
+---
+# Contract: Tranche Archivist → Planner
+
+## The short version
+
+This seam sits between the end of one tranche and the planning of the next. It exists because planning starts by reading the current state of a product, and a tranche that was never closed out leaves those records describing a product that no longer exists.
+
+**What crosses** — three artefacts, all produced when a tranche closes. The archived tranche itself, which is the physical signal that close-out happened at all. The product's state record, brought up to date: what it is now working toward, which manual steps are still outstanding, and what the tranche just shipped. And the retrospective, posted to the standing lessons thread — the durable record of what stalled and what carries forward.
+
+**The hand-off is malformed when** — any of the three is absent. Each has a matching check on the planning side, and the planning side stops rather than working around it: the archive is a fact to be confirmed, not an assumption to be made. "It was probably closed out" is not a passed check. The failure this was written against is real: tranches completed without close-out, and the next plans were then built on records describing the product as it had been before.
+
+**What it does not carry** — a statement of what happens next. That is not archived, it is derived: the open work on the forge is the answer, read directly rather than maintained by hand in a file that would drift. Nor does it carry the power to move a task between tranches; that is a scoping decision, and it belongs to planning.
+
+**How it physically runs** — the carriers are the archived tranche, the product's state record, and the retrospective comment. The ordering is normally close first, then plan. One exception: when a new plan absorbs an existing tranche's unstarted work, the move happens first and the close-out follows, because the close cannot proceed while that work is open and the plan is what empties it. Only unstarted work may move — anything with a branch or an open pull request is finished or dropped where it is, never relocated mid-flight — and every move leaves a note on the task, so a task that changed address can be told from one that vanished.
+
+
+---
+
+## Reference
+
+**Status:** active
+**Seam:** the hand-off from the Tranche Archivist (producer) to the Planner (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/tranche-archivist.md` (producer side) and `aeg-root/roles/planner.md` (consumer side) each reference this file; this file is where the field-by-field hand-off lives, once.
+
+---
+
+## Why this file exists
+
+The Planner starts a new tranche by reading the current state of a product. If the previous tranche was not archived — if the Tranche Archivist did not run — the Planner reads state docs that describe a product that no longer exists. The plan is built on wrong assumptions and dispatches tasks against a reality that merged away.
+
+This is the failure that actually happened: two earlier tranches completed without the Tranche Archivist running. The Planner then started three new tranches against state docs still describing the pre-completion product. The root cause was a missing gate: the Planner's readiness gate had no item that checked whether the previous tranche on each product was archived.
+
+This contract formalizes the close-out outputs the Tranche Archivist must produce, and the physical check the Planner must perform on them. The check is not a checklist item the Planner reviews — it is a filesystem fact: does `aeg-root/tranches/completed/<name>.md` exist? If no, the gate fails.
+
+---
+
+## The hand-off carrier
+
+Four artifacts, all produced by the Tranche Archivist at close-out:
+
+1. The **archived tranche file** at `aeg-root/tranches/completed/<name>.md` — the physical signal.
+2. The updated **pinned state Issue** (one per product, plus an ecosystem-wide bucket) — the authoritative current-state snapshot for the product (current-focus pointer, resolved pending-manual-ops, recently-shipped entry).
+3. The **retrospective** posted as a new comment on the pinned lessons Issue — the durable failure-mode record.
+
+All three must exist before the Planner is authorized to plan the next tranche on the product. (`now.md` is retired. "What's next" is derived from the forge: open Issues without an assigned PR in the current tranche, plus `gh issue list --label "vinaya/tranche:<slug>" --state open`.)
+
+---
+
+## The contract — field-by-field mapping
+
+Every artifact the Tranche Archivist produces (left) has exactly one obligation for the Planner (right). A product missing any left-column artifact means the Tranche Archivist close-out was incomplete — the Planner's gate correctly blocks.
+
+| Tranche Archivist produces | Planner consumes at | What the consumption means |
+|---|---|---|
+| **Archived tranche file** at `aeg-root/tranches/completed/<name>.md` | Readiness gate item 8 | The Planner MUST confirm this file exists before planning any new tranche on the same product. Absence means the Tranche Archivist has not run — planning is blocked. |
+| **Updated pinned state Issue** reflecting current product state (current-focus pointer updated, pending-manual-ops current, recently-shipped entry added) | Readiness gate item 2 (specs reachable) | The Planner reads the updated state Issue as the authoritative current-state snapshot. A state Issue not updated by the Tranche Archivist means the plan is built on wrong assumptions about what the product looks like post-tranche. |
+| **Retrospective** posted as a comment on the pinned lessons Issue | Readiness gate item 5 (prior decisions known) | The Planner reads lessons since the last tranche to avoid re-litigating resolved decisions or repeating known failure modes. A missing retrospective means the Planner plans blind to the tranche's carry-forward lessons. |
+
+> **`now.md` is retired.** "What's next" is not a produced artifact — it is derived from the forge: `gh issue list --label "vinaya/tranche:<slug>" --state open` filtered to Issues with no open PR. The Planner runs this query directly rather than reading a file that would need hand-maintenance.
+
+**Reading the table:** left is the producer obligation (Tranche Archivist role doc and this contract enforce it), right is the consumer obligation (Planner role doc and this contract enforce it). The two role docs must not contradict this table.
+
+---
+
+## Producer obligations (the Tranche Archivist)
+
+- Move the tranche file to `completed/` — this is the **physical signal** the Planner's gate checks. A close-out that does everything else but fails to move the file is an incomplete close-out that correctly blocks planning.
+- Update the relevant pinned state Issue(s) to reflect the tranche's output: update the current-focus pointer, add a recently-shipped entry, clear resolved pending-manual-ops. A state Issue that still describes work in progress after the tranche closed is a bug in the close-out.
+- Post the retrospective as a new comment on the pinned lessons Issue. These three outputs are the close-out contract. A close-out missing any of them is incomplete and the Planner's gate will correctly block.
+- **Do not** update `now.md` — it no longer exists. "What's next" is derived from the forge by the Planner, not written by the Archivist.
+
+## Consumer obligations (the Planner)
+
+- Run readiness gate item 8 before planning any tranche that includes a product: confirm `aeg-root/tranches/completed/<name>.md` exists for the previous tranche on each product in scope.
+- If any prior tranche on an in-scope product exists in `aeg-root/tranches/` but NOT in `completed/`, STOP: *"The previous tranche `<name>` on `<product>` has not been archived — the Tranche Archivist has not run. Dispatch the Tranche Archivist for `<name>` before planning proceeds."*
+- Do not improvise around a missing close-out. "The Tranche Archivist probably ran" is not a passed gate. The filesystem check is the gate. If the file isn't there, stop.
+- Read the updated pinned state Issue and lessons Issue as the authoritative current-state snapshot — not a previous session's memory, not an earlier planning pass. These reflect what the tranche actually shipped; planning against anything else is planning against stale reality.
+- Derive "what's next" from the forge: `gh issue list --label "vinaya/tranche:<slug>" --state open` filtered to Issues without an assigned open PR. Do not look for a `now.md` — it no longer exists.
+
+---
+
+## Supersession — when the Planner's new plan absorbs the source tranche
+
+The normal seam is **archive → then plan**: the Tranche Archivist closes tranche N, and only then does the Planner plan tranche N+1 (readiness gate item 8 enforces this). There is one exception.
+
+When the new tranche the Planner is cutting **supersedes** an existing, still-active tranche — absorbing its `todo`/backlog tasks — the ordering **inverts** for that one source vinaya/tranche:
+
+1. **Planner refactor-and-plan first.** The Planner plans the destination, relabels the moved Issues (`vinaya/tranche:<src>` → `vinaya/tranche:<dest>` + provenance comment), and annotates the source topology (`Moved out → <dest>`) — all while the source is still in `aeg-root/tranches/`. Moving tasks is the Planner's power; the Archivist neither moves them nor decides the destination.
+2. **Then the Tranche Archivist closes the source.** By now the source has **no open task work** (entry-gate item 1: every task `merged`/`dropped`/`moved`), so the close-out proceeds normally and records the moved tasks under the retrospective's "Tasks moved out" field.
+
+The Planner's readiness-gate item 8 is **carved out** for this one superseded source (it would otherwise deadlock: item 8 wants it archived before planning, but planning is what empties it). Item 8 still fully applies to every *unrelated* prior tranche. This carve-out lives in `planner.md` item 8 and is mirrored here; the two must stay in sync.
+
+---
+
+## Changing this contract
+
+A contract changes **as a unit**. You may not change what the Tranche Archivist produces without, in the same change, updating what the Planner 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/tranche-archivist.md` and `aeg-root/roles/planner.md` still point here and still match the table. In particular, readiness gate item 8 in `planner.md` must reference this file explicitly — that reference is the enforcement hook.
+- 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 Tranche Archivist fills the left column; the Planner drains the right. One source of truth, changed as a unit.*