@attalabs/vinaya 0.4.4 → 0.4.5

package/dist/index.js

@@ -1247,6 +1247,9 @@ function printJson(data) {
 function realDeps2() {
   return { detectRepo: detectGitRepo };
 }
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 var COMMAND_TIMEOUT_MS = 20000;
 var DEAD_BRANCH_LABEL = label("dead-branch-push");
 var DEAD_BRANCH_MARKER = `<!-- ${DEAD_BRANCH_LABEL} -->`;
@@ -1392,6 +1395,18 @@ function fetchAssociatedMergedPrs(sha, repoFlag) {
   const prs = JSON.parse(out);
   return prs.filter((pr) => pr.merged_at !== null).map((pr) => pr.number);
 }
+var DIRECT_PUSH_POLL_ATTEMPTS = 6;
+var DIRECT_PUSH_POLL_DELAY_MS = 20000;
+async function pollAssociatedMergedPrs(sha, repoFlag, fetch, attempts, delayMs, sleep) {
+  for (let attempt = 1;attempt <= attempts; attempt++) {
+    const prs = fetch(sha, repoFlag);
+    if (prs.length > 0)
+      return prs;
+    if (attempt < attempts)
+      await sleep(delayMs);
+  }
+  return [];
+}
 function incidentAlreadyOpen(sha, repoFlag) {
   const out = sh2([
     "gh",
@@ -1440,11 +1455,11 @@ function openDirectPushIncident(sha, repoFlag) {
     DIRECT_PUSH_LABEL
   ]);
 }
-function runDirectMainPushCheck(sha, repoFlag) {
-  const associatedMergedPrNumbers = fetchAssociatedMergedPrs(sha, repoFlag);
+async function runDirectMainPushCheck(sha, repoFlag, deps) {
+  const associatedMergedPrNumbers = await pollAssociatedMergedPrs(sha, repoFlag, deps.fetchAssociatedMergedPrs ?? fetchAssociatedMergedPrs, deps.pollAttempts ?? DIRECT_PUSH_POLL_ATTEMPTS, deps.pollDelayMs ?? DIRECT_PUSH_POLL_DELAY_MS, deps.sleep ?? defaultSleep);
   const result = checkDirectMainPush({ sha, associatedMergedPrNumbers });
   if (result.verdict === "direct-push") {
-    openDirectPushIncident(sha, repoFlag);
+    (deps.openDirectPushIncident ?? openDirectPushIncident)(sha, repoFlag);
     return { verdict: "direct-push" };
   }
   return { verdict: "legitimate", mergedPrNumber: result.mergedPrNumber };
@@ -1480,7 +1495,7 @@ async function runAudit(args, deps) {
   const repoFlag = `${repo.owner}/${repo.repo}`;
   const sha = parseSha(args) ?? sh2(["git", "rev-parse", "HEAD"]);
   const deadBranch = only === "direct-push" ? { scanned: 0, findings: [] } : runDeadBranchAudit(repoFlag);
-  const directPush = only === "dead-branches" ? null : runDirectMainPushCheck(sha, repoFlag);
+  const directPush = only === "dead-branches" ? null : await runDirectMainPushCheck(sha, repoFlag, deps);
   const failed = directPush?.verdict === "direct-push";
   if (jsonOutput) {
     printJson({
@@ -1559,7 +1574,10 @@ function coreCheckRegistry() {
       run: bin("check-brief-shape"),
       scope: "diff",
       timeoutMs: 15000,
-      env: { PR_BODY: { optional: true } }
+      env: {
+        PR_BODY: { optional: true },
+        BRANCH: { optional: true }
+      }
     },
     {
       name: "doc-coverage",
@@ -2663,7 +2681,7 @@ name: Vinaya Checks
 
 on:
   pull_request:
-    types: [opened, synchronize, reopened]
+    types: [opened, synchronize, reopened, edited]
 
 jobs:
   vinaya-checks:
@@ -2735,12 +2753,8 @@ jobs:
           # it the adapter reads "no PR yet — local dev" and exits 0, and
           # the gate is green regardless of review state.
           PR_NUMBER: \${{ github.event.pull_request.number }}
-          # Same PR_BODY gap as vinaya-checks.yml — this job also runs
-          # \`check --all\` (test-plan/closes-n included), so it needs the
-          # same wiring or those two checks pass vacuously here too.
-          PR_BODY: \${{ github.event.pull_request.body }}
           BRANCH: \${{ github.head_ref }}
-        run: npx --yes @attalabs/vinaya check --all
+        run: npx --yes @attalabs/vinaya check review-gate
 `;
 }
 function reviewVerdictWorkflow() {
@@ -5541,7 +5555,7 @@ var COMMANDS = [
       { flag: "--json", description: "Enveloped JSON output" }
     ],
     details: [
-      "Dead-branch-push is never-red — a notification channel that flags (label + PR comment) any `task/*` branch whose tip commit lands after its own PR already resolved. Direct-main-push is a real pass/fail — it opens an incident Issue and exits 1 if a commit on `main` has no associated merged PR.",
+      "Dead-branch-push is never-red — a notification channel that flags (label + PR comment) any `task/*` branch whose tip commit lands after its own PR already resolved. Direct-main-push is a real pass/fail — it polls the merge-association API for up to ~100s before deciding, then opens an incident Issue and exits 1 if a commit on `main` genuinely has no associated merged PR.",
       "The same logic the generated `vinaya-archivist.yml` workflow's `daily-drift` and `direct-main-push-detection` jobs run on schedule / on every push to `main` — callable directly for a one-off run or local verification."
     ],
     status: "shipped"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attalabs/vinaya",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Vinaya — Agentic Engineering Harness. Deterministic checks every AI coding agent must satisfy before merge.",
   "type": "module",
   "license": "Apache-2.0",

package/studio-standalone/.worktrees/fix/vinaya-cli-noconsole/.vinaya/projects.md

@@ -0,0 +1,63 @@
+---
+sidebar_title: Projects
+---
+# Projects in this repo
+
+**The project registry.** Declares the projects in this repo and where each one's specs and per-project state live. The `Project` field on a task (a forge Issue) resolves against this file: `Project: vada` → the Developer reads that project's specs, the Archivist updates its per-project state.
+
+## What a project is (and isn't)
+
+A project is **a `(name, folder)` pair the developer declared** — nothing more. Not derived from the folder tree, not required to match a `package.json` name, not required to be a single package. AEG does not define what a project "really" is; the developer does, by choosing a name and a home folder when registering it.
+
+The folder is simply **the home for that project's specs and status** (`<path>/specs/`, `<path>/aeg-project/`). A project may be one package, an app, or a grouping built from several packages.
+
+- **Identity = the registry row.** A project exists because it has a row here, not because a folder with some name exists somewhere. Nothing searches the tree; names are unique by this registry, paths are whatever the human gave.
+- **Path = declared, never derived.** `--path` is a required argument to `aeg add-project`; the tool stores it.
+
+**Presence of this file means this is a multi-project repo** — the `Project` field is required. A single-project repo has **no** `projects.md`; every task shares one project, so the field is omitted, and state lives in the root `aeg-project/`. The registry appears only when there is more than one project to disambiguate.
+
+## Registry
+
+| Project  | Path                  | Specs                       | Per-project state                    |
+|----------|-----------------------|-----------------------------|--------------------------------------|
+| admin    | `tools/admin`         | `tools/admin/specs/`        | (state tracked globally for now)     |
+| vada     | `apps/vada-ai`        | `apps/vada-ai/specs/`       | `apps/vada-ai/aeg-project/`   |
+| herald   | `apps/herald-ai`      | `apps/herald-ai/specs/`     | `apps/herald-ai/aeg-project/` |
+| aeg-core | `packages/aeg-core`   | `packages/aeg-core/specs/`  | (state tracked globally for now)     |
+| aeg-forge-state | `packages/aeg-forge-state` | `packages/aeg-forge-state/specs/` | (state tracked globally for now) |
+| attalabs | `apps/attalabs`       | `apps/attalabs/specs/`      | (state tracked globally for now)     |
+| vinaya   | `apps/vinaya`         | `apps/vinaya/specs/`        | Issue #768 (pinned)                  |
+
+> **admin** — `tools/admin`: the internal Sanity-backed admin tool for managing per-product theme/library config across every AttaLabs product (not a product itself, no `.attalabs.dev` domain). Had real code and a task PR (#557, the Library-picker feature) before ever getting a registry row — added retroactively once that gap was noticed. `tools/*` carries no `-ai` suffix (internal-tooling convention, like `apps/desktop`, `apps/attalabs`).
+
+> **vinaya** — Vinaya: the npm-distributed reference implementation of AEG, installed into any GitHub repository. One app folder, three workspaces: `apps/vinaya/cli` (the `vinaya` command — init/check/pr/issue/doctor/upgrade/eject/demo/waiver), `apps/vinaya/web` (**Vinaya Studio**, ported from the old AEG Studio app), and `apps/vinaya/sources` (the StateSource adapters — forge-backed primary, file-backed transitional). Imports `@atta/aeg-core` unchanged; the vinaya-namespace migration of shared code rides the later npm extraction, never a standalone rename. The registry row deliberately precedes the code. "Vinaya is the reference implementation of AEG": AEG stays the model's name (`aeg-root/` is untouched); Vinaya is the tool. Pāli name by elective aesthetic. `apps/vinaya` carries no `-ai` suffix (meta/infra convention).
+
+> **attalabs** — The AttaLabs ecosystem hub app (`@atta/attalabs-web`/`-mobile`/`-mcp-server`, serving `attalabs.dev`), distinct from **Atta** (the deep-thinking AI product — Vāda+Vitakka+Sati; its dedicated app scaffold, `apps/atta-ai`, was retired — Atta remains a real, code-less concept, not a registered project). Registered here because it has real code and its own `apps/attalabs/specs/`, but had no registry row until it was added retroactively (found while sizing an unrelated task's `Project(s)` field). `apps/attalabs` carries no `-ai` suffix (meta/infra-app convention, like `apps/desktop`).
+
+> **aeg-core** — `@atta/aeg-core` (`packages/aeg-core`): the pure, no-I/O package the AEG product runs on. Two capabilities: parse a repo's AEG artifacts (registry, tranche files) into a typed model, and `deriveTranche(tranche, forgeFacts)` → per-task derived status + the dependency/conflict graph + dispatch eligibility, mirroring `tranche-model.md` §3 exactly. Both **AEG Studio** (local, the first consumer) and the future **Portal** (hosted) read through this same substrate; they differ only in how they fetch the inputs. Registered as a project because a task declares `Project: aeg-core` — a package may be a project, per this file's framing above.
+
+> **aeg-forge-state** — `@atta/aeg-forge-state` (`packages/aeg-forge-state`): the one sanctioned adapter that reads live GitHub forge state (Milestone + labeled Issues) and derives the typed `Tranche`/`Task` shapes `aeg-core`'s pure evaluators consume — `gh`-CLI-only, read-only, zero topology file. Listed in `.aeg/packages` as its own collision domain (distinct from `aeg-core`) since before this row, but had no registry row of its own — any task editing its `src/**` had no `Project:` whose declared path actually covered it, forcing every prior task to fall back on a `blast-radius-ack:` line instead of a real ownership match. Registered retroactively (found while planning follow-on forge-adapter test-coverage and label-vocabulary work) for the same reason `attalabs` and `admin` were: real code, its own collision domain, no row.
+
+## How `Project` is validated
+
+This registry is the **authority for valid project names.** A `Project:` value is valid iff every name in it is a row above. The Planner and Developer resolve `Project:` against this file; an unmatched name (a typo like `vda`, or unregistered) makes the task malformed and the agent refuses rather than guessing — *"Project 'vda' isn't registered; did you mean 'vada', or run `aeg add-project` first?"* Can also run mechanically in `verify-docs`.
+
+## A task can span multiple projects — and that is normal
+
+`Project` is **multi-valued.** A task carries as many projects as it genuinely touches: usually one (`Project: vada`), sometimes several (`Project: engine, herald`, or more). Not an exception — cross-project PRs are an expected shape. The Planner decides split-vs-combine by **verification coupling** (see `tranche-model.md` §6): provable independently → separate tasks with a `depends-on` edge; provable only as a unit → one task / branch / PR / multiple projects. The same `Ticket:` rides on all resulting tasks, so work stays atomic in Jira however it's shaped in AEG.
+
+When a task lists multiple projects, every mechanism fans out: the Developer reads every listed project's specs; the PR is reviewed through each project's lens (more projects = more review lenses = proportionally more rigor, matching the wider blast radius); the Archivist updates every listed project's `state.md` (non-derivable operational facts; `now.md` is retired).
+
+## Routing vs. conflicts — two different granularities
+
+`Project` is the **coarse routing/ownership label** — "whose specs, whose state." It is **not** the conflict unit. Conflicts happen at the **package / collision-domain level**:
+
+- **Collision domains are packages**, listed in a rarely-changed static file, `.aeg/packages`. Known cross-cutting paths that couple tasks across package boundaries — **lockfiles, `migrations/`, codegen outputs (protobuf/GraphQL/OpenAPI), monorepo config (tsconfig/eslint/turbo)** — are declared as their own collision domains.
+- Two tasks conflict if they touch the same collision domain. The canonical case: a task generalizing `@atta/engine` (a package Vāda shares) conflicts with any in-flight Vāda task touching the engine — different projects, same package, real collision. So conflict detection keys on **packages, not projects**.
+- Conflicts are **declared by the Planner** (`conflicts-with` edges) and **static**. The gate is forge-answerable with zero stored state: "is a `conflicts-with` sibling's PR open?" There is **no dynamic path-overlap scanner** — that would need a live task→changed-files map, the mutable state AEG eliminates (forbidden; see `tranche-model.md` §9). When unsure two tasks collide, declare the conflict and serialize.
+
+Don't conflate them: `Project` = whose specs/state; `conflicts-with` (via collision domains) = whose files.
+
+---
+
+Project backlogs (held / future items, out of the AEG flow) live alongside each project's specs as `<path>/specs/<project>-backlog.md`. Cross-cutting / ecosystem items are cut as backlog Issues on the forge (the old `specs/ecosystem-backlog.md` was deleted).

package/studio-standalone/.worktrees/fix/vinaya-cli-noconsole/aeg-root/aeg-manual-flow.md

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

package/studio-standalone/.worktrees/fix/vinaya-cli-noconsole/aeg-root/contracts/archivist-tranche-archivist.md

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