@attalabs/vinaya 0.4.2 → 0.4.3

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

@@ -0,0 +1,28 @@
+# Tranche: aeg-consolidation — July 2026
+Lifecycle: complete
+
+Goal: Home the AEG coherence-check engine (originally `scripts/verify-coherence.ts` +
+`scripts/verify-docs.ts`) in `@atta/aeg-core` as pure, exhaustively-tested functions;
+fix the CI≠local drift; re-arm the coherence gate as blocking; add the docs coherence
+gate. The CLI shims themselves also moved, into `packages/aeg-core/bin/` — AEG is a
+black box to the host monorepo; the only sanctioned crossing point is
+`.github/workflows/*.yml` (a GitHub Actions platform requirement), never the
+monorepo's generic `scripts/` folder. Full task rationale lives on each Issue
+(Planner's rationale block); this file holds topology only.
+
+Repo: daniboomerang/attalabs · Team Leader: Claude (web)
+
+## Tasks (topology)
+
+| #  | Task                                                          | Issue | Project(s) | Depends-on | Conflicts-with |
+|----|----------------------------------------------------------------|-------|------------|------------|----------------|
+| 1  | Home verify-docs checks in `@atta/aeg-core`                    | #263  | aeg, aeg-core | —          | —              |
+| 2  | Home verify-coherence checks in `@atta/aeg-core`                | #264  | aeg, aeg-core | #263       | 4              |
+| 3  | Fix CI≠local drift, complete grandfather, re-arm coherence gate | #220  | aeg, aeg-core | #264       | —              |
+| 4  | Docs coherence gate (surfaced-doc manifest)                    | #265  | aeg, aeg-core | #263       | 2              |
+
+## Cross-tranche dependencies
+
+- **`aeg-governance-hardening`** depends on this tranche: its task 1 (#251) depends on this tranche's task 2 (#264); its task 2 (#252) and task 3 (#218) each depend on this tranche's task 1 (#263). Dispatch gates are forge-answerable regardless of which tranche file lists the task — do not dispatch those `aeg-governance-hardening` tasks until the referenced Issue here is merged.
+- **`aeg-studio-cleanup`** (not yet planned) will depend on this tranche's task 4 (#265) — it defines the "surfaced doc" manifest that tranche's docs-curation task consumes.
+- Superseded, absorbed the unbuilt tail of `aeg-coherence-v1` (D-070 movement, 2026-07-01): task 3 (#220) is that tranche's former task 5, re-scoped after a deep-dig into the actual code found the two real CI≠local bugs its old exit criteria depended on. See `aeg-root/tranches/aeg-coherence-v1.md` for the per-task move annotations.

package/studio-standalone/.worktrees/fix/studio-standalone-repo-root/apps/vinaya/web/.next/standalone/aeg-root/tranches/completed/aeg-governance-hardening.md

@@ -0,0 +1,80 @@
+# Tranche: aeg-governance-hardening — July 2026
+Lifecycle: complete
+
+Goal: Finish D-069's role-seam contract gates (planner→brief, brief→developer) natively
+on the `@atta/aeg-core` engine `aeg-consolidation` builds; drive code→doc linkage to
+100% and audit staleness against the decision log; auto-derive the Planner's §7
+doc-update list; close three live-fire model-hardening gaps found while dispatching
+D-069 itself (ledger-ownership, reviewer disk-isolation, executor-protocol chaining).
+Full task rationale lives on each Issue; this file holds topology only.
+
+Repo: daniboomerang/attalabs · Team Leader: Claude (web)
+
+## Tasks (topology)
+
+| #  | Task                                                                          | Issue | Project(s) | Depends-on           | Conflicts-with |
+|----|--------------------------------------------------------------------------------|-------|------------|-----------------------|----------------|
+| 1  | Planner→Brief rationale-completeness gate (R1)                                 | #251  | aeg        | aeg-consolidation #264 | 2, 5d          |
+| 2  | Brief→Developer brief-validation gate                                          | #252  | aeg        | aeg-consolidation #263 | 1              |
+| 3  | Bind-all + staleness audit: drive linkage to 100%, emit fix punch-list          | #218  | aeg        | aeg-consolidation #263 | —              |
+| 4  | Planner §7 auto-derivation from `doc-owners`                                   | #219  | aeg        | 3                      | —              |
+| 5  | Model hardening: ledger-ownership, reviewer isolation, executor-protocol chain | #266  | aeg        | —                      | —              |
+| 5a | Branch-ID verification: Step 0 must literal-match topology's # column          | #293  | aeg        | —                      | —              |
+| 5b | Forbid committed report/scratch files; findings live in PR/Issue only          | #297  | aeg        | —                      | —              |
+| 5c | Issue-existence precondition: "row absent" is its own hard-stop, not folded into #TBD | #300  | aeg        | —                      | —              |
+| 5d | Post-merge Archivist automation + plan-PR Closes guard                        | #309  | aeg, aeg-core | —                   | 1              |
+| 6  | Fix stale claim vs D-060 in ui-cms-theme skill                                | #278  | aeg        | —                      | —              |
+| 7  | Fix stale claim vs D-044/D-045 in ui-api-routes skill                         | #279  | aeg        | —                      | —              |
+| 8  | Fix stale claim vs D-025 in atta-ai/attalabs CLAUDE.md                        | #280  | aeg        | —                      | —              |
+| 9  | Fix stale claim vs D-050/D-052 in cetana-spec.md + cetana-coordinator skill   | #281  | aeg        | —                      | —              |
+| 10 | Fix stale claim vs D-044/D-045 in herald-engine skill                         | #282  | aeg        | —                      | —              |
+| 11 | Deterministic dispatch gate: verify-dispatch, premise pinning, verify-task    | #324  | aeg, aeg-core | —                   | 1, 15          |
+| 12 | Fix stale claims vs D-045/D-051 in herald web CLAUDE.md                       | #326  | aeg        | —                      | —              |
+| 13 | Fix herald web tests: deleted YAML path (ENOENT); CI-filter report            | #327  | herald     | —                      | —              |
+| 14 | Align commit-format docs with enforced commitlint grammar                     | #328  | aeg        | —                      | —              |
+| 15 | Clear the 44 pre-existing F1/F2 full-mode findings                            | #329  | aeg        | —                      | 11             |
+| 16 | Fresh-worktree bootstrap: wire UI generate into dev task                      | #330  | aeg        | —                      | —              |
+| 17 | Forge wrappers ship empty bodies on stream body-file input                    | #333  | aeg        | —                      | —              |
+| 18 | Pre-push guard: refuse pushes to a branch whose PR is merged/closed           | #335  | aeg        | —                      | 11             |
+| 19 | End the plan-PR race: CI-scope T2 + single-plan-PR guard                      | #336  | aeg        | —                      | 11, 18         |
+| 20 | Coherence oracle A2 false positive: provenance exists but undetected (#287)   | #340  | aeg        | —                      | —              |
+| 21 | verify-dispatch baseline capture silently reports 0 findings on tool failure | #351  | aeg-core   | —                      | —              |
+| 23 | Fix verify-dispatch repo resolution, explain row-adjacency, wire daily-drift to stuck blockers | #360  | aeg, aeg-core | —                 | —              |
+| 22 | turbo-ignore builds unconditionally on a branch's first deploy (no --fallback) | #353  | vada, herald, atta, attalabs | — | —      |
+| 24 | CI backstops for local-only gates + enforcement pairing matrix               | #364  | aeg, aeg-core | —                 | 23, 25         |
+| 25 | Mechanize verify-dispatch + verify-task: gates agents cannot skip            | #365  | aeg, aeg-core | 23                | 24             |
+| 26 | Studio: render Issue assignment as display-only chip on Todo tasks           | #368  | aeg        | —                      | —              |
+| 27 | Scope CI to the diff: affected-only typecheck/tests + turbo cache            | #370  | aeg        | —                      | —              |
+| 28 | Purify aeg-core: move docs UI to Studio, zero react/next/UI dependencies     | #372  | aeg, aeg-core | —                 | —              |
+| 35 | URGENT: fix task 31's Vercel skip — no origin remote, still builds everything | #409  | vada, herald, atta, attalabs | —                 | —              |
+| 31 | Vercel shallow-clone fallback + direct-main-push permission + 9-job PR-gate consolidation | #395 | aeg, vada, herald, atta, attalabs | — | — |
+| 30 | Structured templates for every agent-authored artifact (Issue/brief/PR report) | #393  | aeg        | —                      | —              |
+| 32 | Kill the D-073 bash fork in .husky/pre-push: delegate to parseTranche      | #399  | aeg, aeg-core | —                  | 29, 33         |
+| 33 | Mechanize task-issue self-assignment at dispatch (task 26's chip has no producer) | #401  | aeg, aeg-core | —              | 32             |
+| 36 | open-issue.ts edit path never checks existing labels: rationale gate bypassed | #417  | aeg, aeg-core | —                      | —              |
+| 29 | Waiver authentication: actor-verified label supersedes Doc-waiver grammar    | #380  | aeg, aeg-core | —                 | 25, 32         |
+
+## Backlog (this tranche, not yet dispatched)
+
+- **Task 35 (#409) registered and placed immediately ahead of everything, including task 31 (Planner act, 2026-07-05, Principal-directed urgent priority) — task 31's own Vercel fix does not work.** Confirmed live via `vercel inspect --logs` on PR #408 (a pure docs-only topology PR): task 31's `(git fetch --deepen=100 origin || true) && (git fetch --depth=100 origin main:main || true)` fails immediately with `fatal: 'origin' does not appear to be a git repository` — Vercel's checkout never configures a remote named `origin`, so the deepening fetches never ran, `turbo-ignore` still couldn't resolve `main`, and it fell back to its own fail-open default ("✓ Proceeding with deployment") — a full, unnecessary build ran for `vada-ai` and `atta-ai` on a diff touching zero app code. The same log independently confirms `turbo-ignore` itself is deprecated per its own output; task 35 must seriously evaluate migrating to Vercel's native project-skipping over patching the deprecated tool further. Placed ahead of task 31's own row (which is otherwise done/merged, but the underlying mechanism it shipped remains broken in production) since every push right now keeps burning real Vercel build minutes until this lands.
+- **Task 29 (#380) deferred, moved to end of queue (Planner act, 2026-07-05) — dispatch attempted and correctly stopped, not a task-content problem.** Dispatched once; the Developer's own pre-flight (brief §5/§10) halted before Step 0 (no worktree, no branch, no commits — zero cost) because D-097, the decision this task implements, is `Status: PENDING` in `aeg-project/decisions.md`, not Principal-ratified (blocker recorded on Issue #380). Principal elected not to ratify now — D-097 is optional hardening (closes a theoretical agent-self-waiver trust gap) with no effect on the actual doc-coherence check itself, which keeps working identically with or without it; deferring costs nothing today. Moved to the end of this tranche's queue rather than left in place, since leaving it wherever it sat would permanently block every task behind it under row-adjacency. Task 29's own brief remains valid and unchanged for whenever D-097 is ratified — re-dispatch as-is at that point. New order: 28→31→30→32→33→29.
+- **Task 29 (#380) unblocked — D-097 ratified (Principal act, 2026-07-06), carved out ahead of the rest of the D-083–D-109 Vinaya batch.** `decisions.md` D-097 flipped `PENDING → ACTIVE` with a `Ratified by:` note; D-080 flipped `ACTIVE → SUPERSEDED` per D-097's own consequences clause; `ratification-queue.md`'s D-083–D-109 entry annotated with the carve-out (26 of 27 entries remain PENDING, gated on the separate Strategist-mode `aeg-root/` layout decision). Task 29 is now the last remaining task in this tranche (both `conflicts-with` siblings, 25 and 32, already merged) — dispatchable as soon as the Brief Author re-authors the brief against current `origin/main` (the previously-dispatched brief was never committed, per the "pasted, not committed" rule, so it must be re-authored, not resumed).
+- **Task 34 (#404) consolidated into task 31 (#395), not dispatched separately (Planner act, 2026-07-05).** Task 34 was briefly registered as its own row (consolidating 9 cheap, mostly-overhead PR gate jobs into one job, ~50% billed-minute cut, root-caused by measuring real per-job durations on PR #400), then folded into task 31 as its item 3 before either dispatched, after confirming from source (`fetchTrancheBranchPrs`, `packages/aeg-core/bin/verify-dispatch.ts:118-131`) that bundling two pre-registered task rows into one PR is NOT supported by the branch-name-based dispatch gate: a PR under one branch name leaves the other task's row permanently unmatched, blocking every task after it forever. One task, one branch, one PR closes this correctly. Issue #404 closed as superseded; its content preserved verbatim on #395. Row 31 (still first among 29/30/32/33 — none of which have a real `depends-on`/`conflicts-with` relationship forcing the prior strict order) stays prioritized ahead of them: the prior order was pure row-position, not functional necessity, and every push for the rest of this tranche's remaining tasks otherwise keeps paying today's inflated per-push CI cost. New order: 28→31→29→30→32→33. No gate overridden.
+- **Task 36 (#417) — found live, 2026-07-06, by the Vinaya planning session** while amending Issues #384/#382 with load-bearing planner constraints; routed here correctly (the defective tool, `open-issue.ts`, is this tranche's own scope) via a handoff brief rather than acted on directly. `open-issue.ts edit <n> --body-file <path>` detects whether the D-078 rationale gate applies by reading `--label` flags on the edit command itself, never the target Issue's actual forge labels — so a body edit on a real task Issue (carrying a real `tranche:*` label) silently bypasses `checkIssueRationale` entirely, printing a message ("no tranche label — rationale gate does not apply") that looks like a correct determination but isn't one. Confirmed independently against source before registering. Affects every body edit this tranche has made to a task Issue via the sanctioned wrapper (including this Planner's own edits to #395 and #372) — none of them were actually validated. Fix: fetch the Issue's real labels from the forge on the edit path before deciding; fail loud if the fetch itself fails, never silently treat a fetch failure as "no tranche label."
+- **Task 33 (#401) — found live, 2026-07-05, dispatching task 28 (#372).** Task 26's dispatch-visibility chip (renders when `facts.assigned` is true) had no producer: the Principal checked Studio mid-dispatch, saw task 28 rendering as plain, untouched `Todo` despite two real commits already pushed to its branch. Root cause: Issue assignment has never been mechanized — `developer.md`/`executor-protocol/SKILL.md` never mandate it; task 27's Issue (#370) was only assigned because the Principal happened to do it manually around dispatch time, task 28's wasn't. Fix: mechanize the assignment at the task branch's first real push, piggybacking on the same `verify-dispatch` hook path task 25 already wired into `.husky/pre-push` — one idempotent `gh issue edit --add-assignee` call, fail-open (a failed assignment attempt warns, never blocks the push). `Conflicts-with: 32` — same file (`.husky/pre-push`), disjoint sections (32 extracts the D-073 row-check; this adds the first-push assignment call); task 32's row conflicts-with updated to `29, 33` for symmetry. Immediate instance resolved live: #372 manually assigned by the Principal.
+- **Task 32 (#399) — found by an independent enforcement-ownership audit (2026-07-05) run for the Vinaya tranches.** `.husky/pre-push`'s D-073 branch↔topology-row check is a hand-forked bash reimplementation (`grep` against the tranche file) while every sibling check in the same hook correctly delegates to an aeg-core bin — a genuine logic fork against `packages/aeg-core/src/parse-tranche.ts`. Closed now, ahead of `vinaya-cli-v1` task 2 (#382) making Vinaya's file-backed StateSource adapter a third consumer of topology parsing. `Conflicts-with: 29` (both edit `.husky/pre-push`, disjoint sections) — task 29's row conflicts-with updated to `25, 32` for symmetry. The same audit's other finding (`direct-main-push-detection` missing `pull-requests: read`) duplicates already-registered task 31 (#395, item 2) — no new task filed; new evidence (run IDs) added as a comment on #395 instead.
+- **Task 30 (#393) — the templates task, from the same live incident that produced tasks 21/25's Test Plan fix.** PR #392's pasted reference-brief duplicated its own Test Plan template inside the PR body — hand-fixed live (2026-07-04) by wrapping the reference copy in a collapsed `<details>` block; this task makes that the standing convention, generalizes anchored/delimited fields (Tier, Project, Closes #N, Premise, Test Plan) beyond just Test Plan, and replaces prose-described artifact shapes (Issue rationale, brief, PR report) with literal `aeg-root/templates/*.md` files agents copy and fill in. Root cause named explicitly in the rationale: every malformed-artifact incident this tranche (task 21, #363, #377, #392) traces to gates reverse-engineering structure from freehand prose instead of reading a fixed, unambiguous location.
+- **Task 29 (#380) — registered by the vinaya plan PR (Planner act, 2026-07-04).** Implements D-097 (R-16 of the Vinaya review program; supersedes D-080 upon ratification): waivers become a `waiver:docs` PR label verified by the ACTOR of the labeling timeline event against a principal allowlist; the agent-emittable `Doc-waiver:` body/trailer grammar is removed from CI-accepted inputs; ring 0 downgrades to warn-with-declared-intent; the tool-layer forge gate denies waiver-label mutations in agent sessions (shared-credential hole). `Conflicts-with: 25` — task 25 is in flight on the same `.husky/pre-push` + waiver-detection path; 29 lands on top of whatever 25 ships. Placed here rather than in a Vinaya tranche because it patches the live gate engine, and the mechanism must be proven in this repo before Vinaya productizes it (vinaya-cli-v1 #387 depends on it). Backlog note for a later tranche: a separate machine identity for agents is the clean long-term fix for the shared-credential caveat.
+
+- **Fix punch-list — promoted.** The staleness audit in task 3 (#218) emitted 5 real findings (#278–282), filed by PR #283. All 5 are now promoted to tasks 6–10 above (topology rows added 2026-07-02, each carries its own Planner's rationale posted as an Issue comment). No further unpromoted punch-list items remain from task 3 at this time; task 5a's `5a` letter-suffix convention avoided colliding with this now-realized 6–10 range as designed.
+- **Task 21 (#351) — found live, promoted directly.** A Brief Author's dig on task 15 (2026-07-03) found `verify-dispatch.ts`'s informational baseline-capture path (`currentFindingCounts()`/`sh()`) silently reports 0 findings whenever the wrapped `verify-docs.ts --full` command exits non-zero — its `catch` block discards stderr and returns `''` unconditionally. Not gating (does not affect `checkDispatchReadiness`'s READY/NOT READY verdict), but the baseline print it feeds is misleading exactly when a task needs it most. Filed straight to a topology row (no separate punch-list PR) since it's a single, already-fully-scoped finding, `Project: aeg-core`, Tier 0.
+- **Task 22 (#353) — merged forward from PR #352 (2026-07-03).** This branch (PR #354) was cut from `origin/main` before #352 merged, so its topology omitted task 21's row and CI's `T2` coherence check correctly failed (Issue #351 was open and tranche-labeled but absent from this branch's topology). Resolved by merging `main` into this branch once #352 landed — both rows now present, in numeric order. Carry-forward lesson: register concurrent Planner tasks in one shared plan branch/PR (as tasks 6–10 and 5a–5d were) rather than parallel plan branches, to avoid this class of forge/branch-state race entirely.
+- **Row reorder: 23 now precedes 22 (Planner act, 2026-07-04) — resolving a bug-induced dispatch deadlock.** Task 22 (`Project: vada, herald, atta, attalabs`) was blocked solely by FOUR false `prior-tranche-archival` findings from the confirmed `verify-dispatch` repo-resolution bug (its un-targeted `gh issue list` returns `[]` from linked worktrees, making `herald-hardening-v1` — which genuinely has 4 open Issues — look done-but-unarchived). Task 23 IS the fix for that bug, but sat behind 22 by row-adjacency: 22 needed 23's fix, 23 needed 22 merged. Rows reordered so 23 (whose own gates pass with true data — `Project: aeg, aeg-core`, prior task 21 fully archived) dispatches first; 22 follows with the bug fixed and its gates evaluating honestly. Row order is Planner-owned topology; task numbers and Issues are unchanged — only dispatch order moved. No gate was overridden.
+- **Task 26 (#368) — Studio dispatch-visibility chip.** Renders the already-fetched-but-never-displayed `facts.assigned` as a display-only decoration on Todo tasks (NOT a new derived state — D-059 stands). Closes the live gap where a dispatched-but-not-yet-pushed task is indistinguishable from an untouched one. Assignment-at-dispatch chosen over early branch pushes (a dead terminal would leave a zero-commit branch lying "in-flight"; a stale assignee is visible and one-click reversible).
+- **Tasks 24 (#364) + 25 (#365) — registered together in one plan PR (2026-07-04), applying the #352/#354 carry-forward lesson.** Both born from a full enforcement audit that found two systematic gap families: (a) three gates existing only as local hooks/wrappers, invisible to any writer without them (task 24 adds forge-side backstops + the Principal-requested enforcement pairing matrix in `enforcement.md`); (b) the two highest-value gates (`verify-dispatch`, `verify-task`) being manual CLIs nothing forces anyone to run — the exact "agents obey checkers, not documents" failure the enforcement doc's founding observation records (task 25 mechanizes both). Task 25 `depends-on` 23: wiring `verify-dispatch` into `pre-push` before 23's repo-resolution fix lands would false-block every first push from a worktree. Principal priority: extremely high; row order after the 20–23 chain is the dispatch mechanism (AEG stores no priority metadata).
+- **Task 23 (#360) — bundled at Principal's explicit instruction; sizing tension flagged, not resolved.** Three coupled findings from the `herald-hardening-v1` tasks 4/5 dispatch attempt (2026-07-03): a repo-resolution bug in `verify-dispatch.ts`'s `gh` calls (silent empty-array false positives from linked worktrees), an undocumented-but-intentional row-adjacency design in `dispatch-gate.ts` that an agent misdiagnosed as a bug, and the unused `daily-drift` CI stub that could have surfaced the whole incident proactively. These are three separate verification stories by the split/combine rule (`tranches/README.md` §6) and would normally be three tasks — combined into one at explicit Principal direction; the Issue's own rationale flags this tension rather than silently overriding it.
+
+## Cross-tranche dependencies
+
+- **Depends on `aeg-consolidation`:** task 1 (#251) depends on `aeg-consolidation` task 2 (#264, verify-coherence checks homed in `@atta/aeg-core`); task 2 (#252) and task 3 (#218) each depend on `aeg-consolidation` task 1 (#263, verify-docs checks homed). Do not dispatch tasks 1/2/3 here until the referenced `aeg-consolidation` Issue is merged.
+- Absorbed the unbuilt tail of `aeg-coherence-v1` (D-070 movement, 2026-07-01): tasks 1, 2, 3, 4 are that tranche's former tasks 7, 8, 3, 4 respectively, re-homed here because `aeg-consolidation` claimed the check-engine work they were built on. See `aeg-root/tranches/aeg-coherence-v1.md` for the per-task move annotations.

package/studio-standalone/.worktrees/fix/studio-standalone-repo-root/apps/vinaya/web/.next/standalone/aeg-root/tranches/completed/aeg-governance-ui-v2.md

@@ -0,0 +1,168 @@
+---
+sidebar_title: aeg-governance-ui-v2
+---
+# Tranche: aeg-governance-ui-v2 — June–July 2026
+Lifecycle: complete
+
+Goal: Complete the AEG model by writing all missing role-seam contracts and adding the
+Planner readiness gate that enforces tranche close-out before new planning begins
+(task 1 — blocks both other tranches). Then refactor AEG Studio with the science-route
+UI pattern, add a cross-product tranches view, and complete the token ledger Studio display.
+
+Repo: daniboomerang/attalabs · Team Leader: Claude (web)
+
+## Tasks (topology)
+
+| # | Task | Issue | Project(s) | Depends-on | Conflicts-with |
+|---|------|-------|------------|------------|----------------|
+| 1 | AEG governance — all missing role-seam contracts + Planner readiness gate + any other structural gaps found in roles/, contracts/, process.md, aeg-manual-flow.md | #TBD | aeg, aeg-core | — | — |
+| 2 | Studio UI refactor — copy full layout from `apps/vada-ai/web/src/app/(main)/_archived-science/` (layout, ScienceSidebar, ScienceSidebarClient, shell) as AEG Studio's new shell; replace current StudioShell + StudioSidebar; wire to AEG nav items; apply default theme, no CMS | #TBD | aeg | 1 | — |
+| 3 | Tranches cross-product view — new `/tranches` route showing all active + archived tranches across all projects in one view; reads `aeg-root/tranches/` + `aeg-root/tranches/completed/`; derives status from forge | #TBD | aeg, aeg-core | 2 | — |
+| 4 | Token ledger Studio display (#110-view) — per-task and per-tranche totals on the tranche view; consumes `parseLedger` + `sumLedger` from `@atta/aeg-core` (already built, D-048) | #TBD | aeg, aeg-core | 2 | — |
+
+## Planner's rationale
+
+### Task 1 — AEG governance
+**Boundary:** Audit every role doc, contracts/, process.md, and aeg-manual-flow.md for
+structural gaps. Write all missing role-seam contracts. Add the Planner readiness gate item
+that checks for completed tranche close-out on every product in scope before planning begins.
+Make the model structurally complete.
+
+Missing contracts confirmed (from this planning session):
+- `contracts/brief-developer.md` — what the Brief Author must produce, what the Developer
+  verifies before starting (brief in body, tier declared, Test Plan tagged, surface map,
+  Task Done, worktree step 0)
+- `contracts/developer-reviewer.md` — what the PR must contain before the Reviewer starts
+  (brief in body, tier, Test Plan, CI green, surface map)
+- `contracts/reviewer-archivist.md` — what the Reviewer must produce (verdict format,
+  finding severity tags), what the per-task Archivist confirms before closing out
+- `contracts/archivist-tranche-archivist.md` — what per-task close-outs must have completed
+  before the Tranche Archivist can declare a tranche fully archivable
+- `contracts/tranche-archivist-planner.md` — what the Tranche Archivist must have
+  produced, what the Planner must verify before planning a new tranche on that product
+  (THE KEY ONE — this is the structural fix for the staleness problem)
+
+Planner readiness gate addition (in `aeg-root/roles/planner.md`):
+- Item 8 in the readiness gate: "For every product in scope, confirm the previous tranche
+  is in `aeg-root/tranches/completed/`. If any prior tranche on that product exists in
+  `aeg-root/tranches/` but not `completed/`, the Tranche Archivist has not run — STOP
+  and instruct the Principal to dispatch the Tranche Archivist for that tranche before
+  planning proceeds."
+
+Also verify and fix any other gaps found in process.md (Phase 13 wording), aeg-manual-flow.md,
+and role docs that reference stale paths or missing contract pointers.
+
+NOT in scope: writing briefs, writing new role docs beyond the above contracts, any code changes.
+This is a pure doc task — governance docs only.
+**Sizing:** Doc-only. One PR. Single verification story (all 5 contracts exist and the Planner
+gate has item 8). Bounded (6 new files + 2 updated role docs + process.md + aeg-manual-flow.md).
+**Project(s) + blast radius:** aeg (governance model docs). aeg-core is in the blast radius
+only if the contract shape requires a new parsed artifact — unlikely for pure markdown contracts.
+**Dependency rationale:** No dependencies. Independent — can run from day 1. Must merge BEFORE
+herald-agents-v2 task 1 (housekeeping) dispatches, because the Planner readiness gate it
+introduces is what makes the Archivist dispatch non-optional.
+**Traps to avoid:** Do NOT write contracts that contradict the existing `planner-brief.md`
+contract — extend the pattern, don't diverge. Each contract is a single source of truth for
+its seam; the two role docs on either side POINT AT it, they do not restate it. Do NOT add
+enforcement mechanisms (CI checks, automation) in this task — that is future work. The
+contracts are trusted-discipline in V1 (same as everything else in the model). Do NOT change
+any tranche files or state docs — governance docs only.
+**Suggested agent-class:** mid — doc writing, pattern replication across 5 contracts.
+**Stop-and-escalate:** If writing a contract reveals a genuine gap in the model that requires
+a Type 1 decision (a structural AEG change beyond adding a contract), stop and escalate
+`severity:strategy` before writing the contract.
+
+---
+
+### Task 2 — Studio UI refactor
+**Boundary:** Lift the entire layout solution from
+`apps/vada-ai/web/src/app/(main)/_archived-science/` into AEG Studio as its new shell.
+Specifically: copy `ScienceSidebar.tsx`, `ScienceSidebarClient.tsx`, and `layout.tsx`
+structure verbatim; adapt nav items to AEG's content (Projects, Tranches, Docs, Graph);
+replace the current `StudioShell.tsx` and `StudioSidebar.tsx` entirely; apply a hardcoded
+default theme (no CMS, no `getHeraldConfig`-style resolution — AEG Studio is an internal
+tool with a fixed design system). Refactor all existing pages (`/projects`, `/projects/[name]`,
+`/docs`, root page) against the new shell. NOT in scope: new routes (task 3), token ledger
+display (task 4), any CMS integration.
+**Sizing:** UI refactor. One PR. Single verification story (Studio boots with new sidebar,
+all existing pages render). Bounded (Studio src/ only). Passes all four tests.
+**Project(s) + blast radius:** aeg only. The archived-science source is read-only reference —
+no changes to the Vāda app.
+**Dependency rationale:** Depends on task 1 — governance must be complete before Studio
+work begins (the Studio is the product that visualizes the model; starting the UI before the
+model is complete is backwards).
+**Traps to avoid:** Copy the layout EXACTLY — do not redesign or improve. The brief explicitly
+references `apps/vada-ai/web/src/app/(main)/_archived-science/` as the canonical source. The
+agent reads those files first and copies the pattern, it does not interpret or simplify it.
+The shell is `SidebarProvider` + `SidebarContent` + groups with `SidebarGroupLabel` + items
+with `SidebarMenuButton` + `usePathname` active state — exact copy, renamed for AEG.
+Default theme: pick one clean Tailwind-based default (dark, data-dense, monospace accents —
+consistent with AEG's governance/internal-tool character). No user-configurable theme.
+**Suggested agent-class:** mid — component copy + adaptation, no architecture.
+**Stop-and-escalate:** If the archived-science components depend on Vāda-specific packages
+or context providers that don't exist in the AEG Studio, stop and flag — the copy may need
+adapter work before it can be used.
+
+---
+
+### Task 3 — Tranches cross-product view
+**Boundary:** New `/tranches` route in AEG Studio. Reads `aeg-root/tranches/` (active)
+and `aeg-root/tranches/completed/` (archived). Displays all tranches across all products
+in one view — not per-product. Two sections: Active (files in `aeg-root/tranches/` without
+`completed/` path) and Archived (files in `aeg-root/tranches/completed/`). Derives status
+from the tranche file's `Lifecycle:` marker and the task topology. Uses `@atta/aeg-core`'s
+`parseTranche` for file parsing. Sidebar nav: `/tranches` entry under a new "Tranches"
+group.
+**Sizing:** New route. One PR. Single verification story (route renders active + archived
+tranches). Bounded (new route file + sidebar entry + aeg-core parser reuse). Passes all.
+**Project(s) + blast radius:** aeg (new route), aeg-core (if the parser needs extension for
+the completed/ path format — check first).
+**Dependency rationale:** Depends on task 2 — must have the new shell/layout before adding
+a new route that uses it.
+**Traps to avoid:** Do NOT fetch forge state (PR status, branch existence) in this task —
+that is Phase 2 AEG Studio work (the forge-fact cache and `deriveTranche`). This task
+reads the tranche FILES only and displays their topology + lifecycle marker. Status is
+the lifecycle marker from the file, not derived forge state.
+**Suggested agent-class:** mid — new Next.js route, existing parser reuse.
+**Stop-and-escalate:** If `parseTranche` in `@atta/aeg-core` needs structural changes to
+support the completed/ path format, that is a shared-package change — blast radius includes
+vada (if aeg-core is consumed there) and must be assessed before proceeding.
+
+---
+
+### Task 4 — Token ledger Studio display (#110-view)
+**Boundary:** Display per-task and per-tranche token/cost totals on the tranche view
+in AEG Studio. Consumes `parseLedger` and `sumLedger` from `@atta/aeg-core` (both built
+and tested in D-048 / task 9 model half). Reads `aeg-root/tranches/<name>.tokens.md`
+sibling files. Shows totals inline on the tranche detail page. This is the Studio view
+half of the original task 9 (#110) that was left unbuilt.
+**Sizing:** Small. One PR. Single verification story (tranche view shows ledger totals).
+Bounded (tranche detail page component + ledger file reads). Passes all four tests.
+**Project(s) + blast radius:** aeg (Studio display), aeg-core (consumed unchanged).
+**Dependency rationale:** Depends on task 2 — the tranche detail page is part of the
+refactored Studio; must exist before adding the ledger display to it.
+**Traps to avoid:** Do NOT change `parseLedger` or `sumLedger` in `@atta/aeg-core` — they
+are built and tested; consume them as-is. Do NOT block the view if the `.tokens.md` file is
+absent — render "No ledger data yet" gracefully. The `—` / null convention means some rows
+have unknown totals; show them as `—`, not as `$0.00`.
+**Suggested agent-class:** mid — display component, existing parser reuse.
+**Stop-and-escalate:** If the ledger format in any existing `.tokens.md` file doesn't parse
+cleanly (malformed rows, unexpected structure), log it in the PR body and render gracefully —
+do not alter the ledger files themselves.
+
+## Backlog (this tranche, not yet dispatched)
+
+- GitHub App auth + encrypted token store — deferred to next AEG tranche.
+- Webhook-fed forge-fact cache + `deriveTranche` integration — deferred.
+- `aeg.sh` scaffolder — deferred.
+- Attention queue (`/queue`) — deferred.
+
+## Cross-tranche dependencies
+
+- Task 1 here has no dependencies and must merge BEFORE herald-agents-v2/1 dispatches
+  and BEFORE vada-agents-v2/1 dispatches. It is the structural prerequisite for both
+  other tranches' Planner readiness gates.
+
+## Shipped
+
+- Token ledger view shipped on tranche detail page (parseLedger + sumLedger, D-048).

package/studio-standalone/.worktrees/fix/studio-standalone-repo-root/apps/vinaya/web/.next/standalone/aeg-root/tranches/completed/aeg-governance-ui-v2.tokens.md

@@ -0,0 +1,18 @@
+---
+sidebar_title: Tokens (aeg-gov-ui-v2)
+---
+# Token ledger — aeg-governance-ui-v2
+
+Append-only per-tranche token/cost ledger. Format + rationale: `aeg-root/tranches/README.md` §12. Append-only artifact class: `aeg-root/state-machine.md` §13.
+
+**The rule:** at the end of a role's turn, append one row; never edit a row; re-entry appends another row; the tranche total is `sum(rows)`, derived at read time, never stored.
+
+**Capture sources:** terminal roles run in Claude Code (Developer; Archivist when automated) and self-report exact tokens via `/cost`. claude.ai roles (Planner; Brief Author; Reviewer; Security) cannot read their own token count and append the row with numeric cells as `—`; the Principal fills them later from the claude.ai UI usage figure.
+
+**Cost-table dependency (V1):** the adapter PRICING table is currently missing some recent models (e.g. `claude-sonnet-4-20250514`), so a row's `Cost` cell may read `$0.00` even when tokens are exact. Tokens are still authoritative; cost is best-effort and noted at this seam. Backlogged in `apps/herald-ai/specs/herald-backlog.md`.
+
+| Phase | Role | Agent/Model | Tokens in | Tokens out | Cost | Date |
+|-------|------|-------------|-----------|------------|------|------|
+| theme: brief | Brief Author | gemini-3.5-flash (chat) | — | — | — | 2026-06-20 |
+| theme: develop | Developer | gemini-3.5-flash (chat) | — | — | — | 2026-06-20 |
+| tranche-close | Tranche Archivist | claude-sonnet-4-6 | — | — | — | 2026-06-21 |

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

@@ -0,0 +1,37 @@
+# Tranche: aeg-studio-cleanup — July 2026
+Lifecycle: complete
+
+Goal (execution, not roadmap-why): curate AEG Studio's UI surface — add missing
+canonical reference content, remove unwanted tranche-view surfaces (dependency
+graph, board/graph toggle), fix status-badge colors, and (once `aeg-consolidation`
+task 4 / #265 lands its "surfaced doc" manifest) exclude execution-state artifacts
+currently leaking into the docs nav. Full task rationale lives on each Issue; this
+file holds topology only.
+
+Repo: daniboomerang/attalabs · Team Leader: Claude (web)
+
+## Tasks (topology)
+
+| # | Task                                                          | Issue | Project(s)    | Depends-on | Conflicts-with |
+|---|----------------------------------------------------------------|-------|---------------|------------|----------------|
+| 1 | Add "Documentation Coherence" reference doc                    | #287  | aeg           | —          | —              |
+| 2 | Remove dependency-graph + board view, table-only task list     | #290  | aeg           | —          | —              |
+| 3 | Status badge colors: in-flight/in-review toward cyan/blue      | #291  | aeg           | —          | —              |
+| 4 | Exclude tranche execution files from docs nav                | #292  | aeg, aeg-core | aeg-consolidation #265 | —  |
+| 5 | Remove dead "Dependency graph" topbar link (`/graph` has no page) | #331  | aeg           | —          | —              |
+
+## Cross-tranche dependencies
+
+- Task 1 (#287) has no dependency on #265 — it adds new, uncontroversially-canonical
+  content, not nav-inclusion/exclusion logic. Referenced by `aeg-consolidation.md`'s
+  cross-tranche notes as the anticipated destination for docs-curation work; this is
+  this tranche's first real task, seeded ahead of that larger, #265-gated one.
+- Task 4 (#292) depends on `aeg-consolidation` task 4 (#265, not yet merged) — that task
+  defines the canonical "surfaced doc" manifest this task consumes rather than
+  re-inventing a second, competing exclusion rule. Do not dispatch task 4 until #265 merges.
+- Tasks 2 and 3 have no cross-tranche or intra-tranche dependencies; fully
+  independent, dispatchable in parallel with task 1 and with each other.
+- Runs concurrently with `aeg-consolidation` and `aeg-governance-hardening` (both active,
+  `Project: aeg`) — no collision domain shared with either (all four tasks touch only
+  AEG Studio files or this tranche's own topology; neither in-flight tranche's
+  surface reaches them).

package/studio-standalone/.worktrees/fix/studio-standalone-repo-root/apps/vinaya/web/.next/standalone/aeg-root/tranches/completed/aeg-ui-v1.md

@@ -0,0 +1,176 @@
+# Tranche: aeg-ui-v1 — June 2026
+
+Lifecycle: complete
+
+> **Status (June 17):** 9 of 10 tasks merged. Task 9-view (#110, token ledger Studio display) is the only remaining task — never built, unblocked. All other tasks are on main.
+
+**Goal (execution, not roadmap-why):** build **AEG Studio** — the local, no-auth tool that reads *this* monorepo's AEG artifacts off disk and reads GitHub locally (operator's own token) for live per-task status, and renders this repo's governance: projects → tranches → tasks (kanban by derived status) → task detail (brief from the PR body), a task-dependency-graph view, and the full model documentation. Plus the shared **`@atta/aeg-core`** package (parser + `deriveTranche` + the shared docs renderer) that Studio runs on and the future public **Portal** will inherit.
+
+**Center of gravity:** `@atta/aeg-core` (the shared substrate) + AEG Studio (its first consumer). Per AEG-product D-001, AEG is two products over this core — **Studio** (local, this tranche) and **Portal** (public, future). This tranche builds the core and Studio only; the Portal is explicitly out.
+
+**Repo:** attalabs (`daniboomerang/attalabs`)   ·   **Team Leader:** Dani
+
+> **Status is derived from the forge, not stored here.** This file is topology + the planner's durable rationale only. Live status is `gh pr list` / the forge, never written here. Per `tranches/README.md` §11, the Archivist sets `Lifecycle: complete` and moves this file to `tranches/completed/` when every task is merged — it is never deleted (the rationale is durable history).
+
+> **Readiness gate (run explicitly, per `roles/planner.md`):** intent bounded ✅ (Studio local-first read path + docs; Portal out); specs reachable ✅ (`apps/aeg/specs/aeg-app-architecture.md` §0/§3, `aeg-backlog.md`); code readable ✅ (`@atta/aeg-core` is greenfield; reuse surfaces verified: `@atta/ui/engine-flow`, `@atta/ui/topbar`, `@atta/ui/footer`, Vāda's `content/` + archived "science" doc layout, `apps/vada-ai/web` shell); shared substrate inspectable ✅ (`@atta/ui` consumers known — Vāda, Herald; this tranche *consumes* `@atta/ui` additively, does not change it, so no cross-product blast radius); locked decisions known ✅ (AEG-product D-001 two-product split + local-first; D-029 read-only/derived-status; D-036 shared TopBar props); registry resolves ✅ (`aeg` registered; new `aeg-core` package registered as part of task 1). Concurrency ✅ — **disjoint from `herald-onto-engine`**: that tranche touches `engine`, `adapter-langgraph`, `herald`; this one touches `aeg-core` (new), `apps/aeg`, and *consumes* `@atta/ui` without editing it. **No shared collision domain → the two tranches run fully parallel** (`tranches/README.md` §5, §11).
+
+---
+
+## Tasks (topology)
+
+| # | Task | Issue | Project(s) | Depends-on | Conflicts-with |
+|---|------|-------|-----------|------------|----------------|
+| 1 | `@atta/aeg-core` — AEG-artifact parser + `deriveTranche` (pure) | #94 | aeg-core | — | — |
+| 2 | Scaffold `apps/aeg/web/studio` + top-bar/sidebar shell | #95 | aeg | — | — |
+| 3 | Local GitHub read adapter → forge facts for `deriveTranche` | #97 | aeg, aeg-core | 1 | — |
+| 4 | Projects + tranches pages (sidebar nav, topology table, active/archived) | #98 | aeg | 1, 2 | 5, 6 |
+| 5 | Kanban + task detail (columns by derived status; brief from PR body) | #100 | aeg | 1, 2, 3 | 4, 6 |
+| 6 | Task-dependency-graph view (`@atta/ui/engine-flow`) | #99 | aeg | 1, 2 | 4, 5 |
+| 7 | Shared docs renderer in `@atta/aeg-core` + Studio docs section | #101 | aeg-core, aeg | 1, 2 | — |
+| 8 | AEG icon — find/design | #96 | aeg | — | — |
+| 9 | Per-tranche token/cost ledger (append-only in the model + Studio view) | #110 | aeg, aeg-core | 1, 4 | — |
+| 10 | Verification role — runtime test-plan execution as a model phase + merge gate | #126 | aeg-core | — | — |
+
+**Wave structure (max concurrency, from the edges):**
+- **Wave 1 (parallel):** 1 (#94, `aeg-core` parser), 2 (#95, shell scaffold), 8 (#96, icon) — three independent foundations, no shared surface. (2 can stub data until 1 lands; 8 is pure asset work.)
+- **Wave 2:** 3 (#97, GitHub read) — needs 1's types.
+- **Wave 3 (serialized within the app surface):** 4 (#98), 5 (#100), 6 (#99) all build pages inside `apps/aeg/web/studio` and share the app's routing/layout surface, so they **conflict with each other** (same collision domain: the Studio app shell wiring). Run them one at a time: **4 → 6 → 5** (4 establishes the project/tranche nav the others hang off; 6 is read-only-ish graph; 5 is the richest, needs 3's live status + PR-body read, so last). 7 (#101, docs) touches `aeg-core` + a separate docs route, so it can run **parallel to one** of 4/5/6 if desired, but to stay safe it's simplest to slot it after 4.
+- **Wave 4 (last):** 9 (#110, token ledger) — its **model half** (the append-only ledger format + the per-role append rule + the `aeg-core` parser) could ship anytime after task 1, but its **view half** hangs on the tranche pages, so it depends-on 4 and runs last. Its `aeg-core` parser addition is additive (no conflict with 7's renderer).
+- **Task 10 (#126, verification role)** is dependency-free and conflict-free (model docs + brief skill + optional CI gate; no app surface). Runs parallel with any task in either tranche, anytime.
+- Max *cross-tranche* concurrency with `herald-onto-engine`: unlimited (disjoint).
+
+> **Note on the 4/5/6 conflict:** these are same-project, same-app-shell tasks. The model's conflict rule is package-level; here the collision domain is the Studio app's shared layout/routing files. Declaring them mutually `conflicts-with` and serializing is the conservative, correct call (`tranches/README.md` §5 — "when unsure, declare and serialize"). If, at brief time, the surfaces prove cleanly separable (distinct route files, no shared layout edits), they may parallelize — but the plan declares the conflict.
+
+---
+
+## Task details — Planner's rationale per task (full rationale also in each Issue body)
+
+### Task 1 — `@atta/aeg-core`: AEG-artifact parser + `deriveTranche` (pure) · Issue #94
+**Project(s):** aeg-core · **Depends-on:** — · **Conflicts-with:** —
+
+- **Boundary:** a new shared package `packages/aeg-core` (`@atta/aeg-core`). Two pure capabilities: (a) **parse** a repo's AEG artifacts — `aeg-root/projects.md` (the registry), `aeg-root/tranches/*.md` (topology tables + edges + lifecycle marker), and the per-project `aeg-project/` state — into a typed model; (b) **`deriveTranche(parsedFile, forgeFacts)`** → per-task derived status, the dependency/conflict graph, dispatch-eligibility. **Pure: no I/O, no GitHub client, no filesystem reads** (the caller passes file contents + forge facts in). What this is NOT: not the GitHub read (task 3 supplies `forgeFacts`), not the docs renderer (task 7, separate concern in the same package), not any UI.
+- **Sizing:** passes the four tests — one verification story (given fixture files + a forge-fact snapshot, the typed model + derived statuses are correct), one agent can hold it (pure functions + types + tests), bounded file surface (the new package only), single failure mode (a parse or a derivation is wrong). It is the cleanest, most testable unit and everything depends on it, so it is wave-1 lead.
+- **Project(s) + blast radius:** new package `aeg-core`, no consumers yet → zero blast radius. (Studio becomes the first consumer in later tasks; the Portal later. Designing it pure + standalone now is what lets both consume it.)
+- **Dependency rationale:** none. Foundation.
+- **Traps to avoid:** keep it **pure** — the temptation is to read files/call GitHub inside it; don't, or it becomes untestable and couples to a runtime. The parser must tolerate the *real* current artifact shapes (the `herald-onto-engine` tranche file's table + rationale blocks; the `aeg-ui-v1` file's; the lifecycle marker just added) — use the live files as fixtures. `deriveTranche` must mirror the status table in `tranches/README.md` §3 exactly (don't invent statuses).
+- **Suggested agent-class:** **mid-to-high** — pure logic, but the parsing + derivation correctness is the heart of the product; worth careful work and exhaustive tests.
+- **Stop-and-escalate:** if the artifact formats turn out under-specified for reliable parsing (ambiguous table shapes across tranche files), STOP and escalate `severity:strategy` — the fix may be to tighten the tranche-file format in the model, not to write a fragile parser.
+
+### Task 2 — Scaffold `apps/aeg/web/studio` + top-bar/sidebar shell · Issue #95
+**Project(s):** aeg · **Depends-on:** — · **Conflicts-with:** —
+
+- **Boundary:** create the Next.js app at `apps/aeg/web/studio` (mirroring the Vāda/Herald app setup — App Router, `@atta/ui` styles, Biome, tsconfig) and build the **shell**: a **top bar** (reusing `@atta/ui/topbar`, with the **AEG icon slot top-left** — placeholder "AEG" text until task 8) **plus a left sidebar** (modeled on Vāda's archived "science" doc layout, `apps/vada-ai/web/src/app/(main)/_archived-science`). No auth, no `(app)` guard. The shell renders with stubbed/empty data — real data arrives in tasks 4–7. What this is NOT: not the pages' content (4/5/6), not docs (7).
+- **Sizing:** passes the four tests — one verification story (the app boots locally, the top-bar+sidebar shell renders, nav scaffolding works), one agent can hold it (app config + layout), bounded file surface (the new app dir), single failure mode (the app doesn't boot / shell doesn't render).
+- **Project(s) + blast radius:** `aeg` (the new app). **Consumes `@atta/ui` (topbar, styles) additively — does NOT edit it**, so Vāda/Herald are NOT in the blast radius (re-confirm: no `@atta/ui` source change). If the shell needs a `@atta/ui` change, that's a scope change → escalate.
+- **Dependency rationale:** none — can scaffold against stub data before `aeg-core` lands. (Kept independent of task 1 deliberately so wave 1 has two parallel foundations.)
+- **Traps to avoid:** **do not edit `@atta/ui`** — reuse `TopBar` via its existing props (`isSignedIn`/`accountMenu` exist per global D-036; Studio is no-auth so pass the no-auth shape). Confirm whether Studio uses the CMS-library chrome pattern (like Herald, D-035) or plain `@atta/ui` (simpler; likely correct for an infra tool). Copy the Next.js worktree-root resolution fix the other apps needed (`next.config.ts`).
+- **Suggested agent-class:** **mid** — app scaffold + layout reuse; mechanical but multi-file. Reference the existing app setups closely.
+- **Stop-and-escalate:** if scaffolding reveals the shell genuinely needs a new shared `@atta/ui` capability (not just reuse), STOP and escalate `severity:strategy` (it pulls Vāda/Herald into scope).
+- **Note:** Plain `@atta/ui` (no CMS chrome). Known follow-up backlogged: TopBar `useUser()` is unconditional → Studio needs Clerk env to boot (a `@atta/ui` change, Vāda/Herald in blast radius).
+
+### Task 3 — Local GitHub read adapter → forge facts for `deriveTranche` · Issue #97
+**Project(s):** aeg, aeg-core · **Depends-on:** 1 · **Conflicts-with:** —
+
+- **Boundary:** the thin adapter that, running locally with the operator's own GitHub auth (the `gh` CLI token or a `GITHUB_TOKEN` env), fetches the **forge facts** `deriveTranche` consumes — Issue state/assignment, branch existence (`task/<tranche>/<n>`), PR state, review decision, merge — for this repo, and maps them to the `forgeFacts` type task 1 defined. Read-only. What this is NOT: not `deriveTranche` itself (task 1), not the UI that displays the result (tasks 4–6), not a GitHub App / vault / webhook cache (deferred, hosted-only, D-001 §3.2–3.3).
+- **Sizing:** passes the four tests — one verification story (against this real repo, the adapter returns correct current forge facts that drive correct derived statuses), one agent can hold it (one read module + its types), bounded file surface (the adapter, likely in `aeg-core` or a thin `studio` lib calling `aeg-core` types), single failure mode (a forge read is wrong/missing).
+- **Project(s) + blast radius:** `aeg` + `aeg-core` (the fact-shape may live in `aeg-core` as a type, the fetch in the app). No other consumers.
+- **Dependency rationale:** **depends-on 1** — it produces the `forgeFacts` shape task 1 defined; that type must exist first.
+- **Traps to avoid:** **read-only, always** (D-029 — the UI never writes the forge). Use the operator's existing auth; **do not** build an auth system. Handle the no-token / unauthenticated case gracefully (the file-derived topology still renders; only live status is absent) — Studio must be useful even before GitHub is reachable. Note (from task 2): Studio currently needs Clerk env to boot — keep the GitHub-read path independent of that so "useful before GitHub reachable" still holds. Mind rate limits but **do not** build the webhook cache (that's the deferred hosted path).
+- **Suggested agent-class:** **mid** — a contained read adapter; the GitHub API surface is well-trodden.
+- **Stop-and-escalate:** if read-only local auth can't cover what the kanban needs (e.g. a datum only available via an App), STOP and escalate `severity:strategy` rather than reaching for the hosted machinery.
+
+### Task 4 — Projects + tranches pages (sidebar nav, topology table, active/archived) · Issue #98
+**Project(s):** aeg · **Depends-on:** 1, 2 · **Conflicts-with:** 5, 6
+
+- **Boundary:** populate the **sidebar** with the repo's projects (from `aeg-core`'s parse), and build the **project page** → its **tranches** (active/archived, from the lifecycle marker) → the **tranche topology table** (the parsed table). This is the navigational spine: root project → projects → tranches → (table). What this is NOT: not the kanban/task-detail (task 5), not the graph (task 6).
+- **Sizing:** passes the four tests — one verification story (launch on this repo → sidebar lists the real projects → drill to a tranche → its real topology table renders), one agent can hold it (the nav + table pages), bounded file surface (these routes + sidebar wiring), single failure mode (nav/table doesn't render the parsed model).
+- **Project(s) + blast radius:** `aeg` only.
+- **Dependency rationale:** **depends-on 1** (the parsed model) **and 2** (the shell to render inside). **Conflicts-with 5 and 6** — all three add pages inside the Studio app and touch shared layout/routing; serialize (this one first — it builds the nav spine the others hang off).
+- **Traps to avoid:** active/archived comes from the **lifecycle marker** + `completed/` location (`tranches/README.md` §11), not from inventing a status. Read topology from `aeg-core`, don't re-parse in the component.
+- **Suggested agent-class:** **mid** — standard data-driven pages over a parsed model.
+- **Stop-and-escalate:** if the parsed model from task 1 is missing something these pages need, escalate back toward task 1's scope (`severity:strategy`).
+
+### Task 5 — Kanban + task detail (columns by derived status; brief from PR body) · Issue #100
+**Project(s):** aeg · **Depends-on:** 1, 2, 3 · **Conflicts-with:** 4, 6
+
+- **Boundary:** the **kanban** view of a tranche's tasks — columns = derived statuses (`todo`/`in-flight`/`in-review`/`changes-requested`/`merged`/`blocked`), each task placed in its column by **live** status (from task 3). Click a task → **task detail**: read the **brief** (from the **PR body** — the model's home for the brief), show status/progress, link to the Issue/PR. What this is NOT: not the graph (task 6), not the nav/table (task 4).
+- **Sizing:** passes the four tests — one verification story (a tranche's real tasks land in the right columns by live status; opening one shows its real brief from the PR body), one agent can hold it (the kanban + detail views), bounded file surface (these routes/components), single failure mode (wrong column placement or brief not fetched).
+- **Project(s) + blast radius:** `aeg` only.
+- **Dependency rationale:** **depends-on 1** (derived status), **2** (shell), **3** (live forge facts + the PR-body fetch for the brief). It is the richest task and the most dependency-laden, so it runs **last** in the app-surface wave. **Conflicts-with 4 and 6** (shared app shell).
+- **Traps to avoid:** the **brief lives in the PR body** (`tranches/README.md` §7) — fetch it from the PR, not the Issue (the Issue holds the rationale, not the brief). Derived status must come from `aeg-core`'s `deriveTranche`, not re-derived in the component. Handle the no-PR-yet / no-token cases (a `backlog`/`todo` task has no brief yet).
+- **Suggested agent-class:** **mid-to-high** — the most stateful view (live data, columns, detail fetch), though still Herald-free and bounded.
+- **Stop-and-escalate:** if the PR-body brief isn't reliably fetchable read-only, or derived status needs a fact task 3 doesn't supply, escalate `severity:strategy`.
+
+### Task 6 — Task-dependency-graph view (`@atta/ui/engine-flow`) · Issue #99
+**Project(s):** aeg · **Depends-on:** 1, 2 · **Conflicts-with:** 4, 5
+
+- **Boundary:** render a tranche's tasks as a **graph** (UI label: **"task dependency graph"**) using `@atta/ui/engine-flow` (React Flow / `@xyflow/react`) — nodes = tasks, **depends-on = directed arrows**, **conflicts-with = dashed/undirected links**. Optional per-node live-status tint if task 3's data is present (additive, not required for V1). What this is NOT: not the kanban (task 5), not the nav (task 4).
+- **Sizing:** passes the four tests — one verification story (a tranche's real depends-on/conflicts-with edges render as a correct directed graph), one agent can hold it (one graph view reusing engine-flow), bounded file surface (the graph route/component), single failure mode (graph/edges render wrong).
+- **Project(s) + blast radius:** `aeg` only. **Reuses `@atta/ui/engine-flow` as-is** — verify no change needed to the shared renderer (if a change *is* needed, Vāda enters scope → escalate).
+- **Dependency rationale:** **depends-on 1** (the graph structure from the parse) **and 2** (shell). **Conflicts-with 4 and 5** (shared app shell). Independent of task 3 (structure is file-derived; live tint is optional).
+- **Traps to avoid:** the two edge types are different (directed depends-on = a DAG; undirected conflicts-with = symmetric) — render them distinctly. Reuse engine-flow's existing node/edge components; **do not** fork or modify `@atta/ui/engine-flow`.
+- **Suggested agent-class:** **mid** — reuse of an existing renderer over a parsed graph.
+- **Stop-and-escalate:** if engine-flow can't express the two edge types without a shared-package change, STOP and escalate `severity:strategy` (pulls Vāda into scope).
+
+### Task 7 — Shared docs renderer in `@atta/aeg-core` + Studio docs section · Issue #101
+**Project(s):** aeg-core, aeg · **Depends-on:** 1, 2 · **Conflicts-with:** —
+
+- **Boundary:** add the **docs renderer** to `@atta/aeg-core` — render the `aeg-root/` model docs (constitution, roles, flow, contracts, routes & meanings — **everything**) following **Vāda's local-markdown pattern** (local `.md` → reader component; ref `apps/vada-ai/web/content/` + the archived "science" doc layout). Then wire Studio's **docs section** to it (sidebar-doc layout). Built **shared** so the future Portal inherits it (AEG-product D-001). What this is NOT: not Studio-only (the renderer is shared), not the Portal (future).
+- **Sizing:** passes the four tests — one verification story (the full `aeg-root/` model renders as browsable docs in Studio via the shared renderer), one agent can hold it (the renderer + the docs route), bounded file surface (the renderer in `aeg-core` + Studio's docs route), single failure mode (docs don't render/navigate).
+- **Project(s) + blast radius:** `aeg-core` (the renderer) + `aeg` (Studio's docs route). The renderer is a **new shared capability** with one consumer now (Studio) and one future (Portal) — design it consumer-agnostic.
+- **Dependency rationale:** **depends-on 1** (lives in the `aeg-core` package created there) **and 2** (rendered in Studio's shell). No conflict — separate package surface + a distinct docs route, so it can parallelize with one of 4/5/6 if desired.
+- **Traps to avoid:** reuse Vāda's **existing** markdown rendering approach — don't invent a new MDX pipeline. Keep the renderer **content-source-agnostic** (it takes markdown + a nav structure; it doesn't hardcode Studio's filesystem) so the Portal can feed it the same `aeg-root/` docs from a deployed context. Render the *whole* model per the Principal's intent — constitution, roles, flow, contracts, routes, meanings — not a subset.
+- **Suggested agent-class:** **mid** — pattern reuse, but the shared-renderer design (consumer-agnostic) wants care.
+- **Stop-and-escalate:** if Vāda's doc pattern can't be cleanly shared (it's too app-coupled to extract), escalate `severity:strategy` — the fix is a small shared extraction, decided deliberately.
+
+### Task 8 — AEG icon (find/design) · Issue #96
+**Project(s):** aeg · **Depends-on:** — · **Conflicts-with:** —
+
+- **Boundary:** produce the **AEG icon/logo** asset (we don't have one) for the top-left of the shell (and later the Portal/favicon). Deliver the asset + drop it into the icon slot task 2 leaves as placeholder text. What this is NOT: not the shell (task 2 leaves a placeholder), not branding beyond the mark.
+- **Sizing:** trivially bounded — one asset. Passes all four tests by being a single deliverable.
+- **Project(s) + blast radius:** `aeg` only (an asset + a one-line swap).
+- **Dependency rationale:** none — pure asset work, parallel to everything. (The shell's placeholder means task 2 doesn't block on it.)
+- **Traps to avoid:** it's a design/taste task, not code — may be Principal-driven or need a design pass. Keep it an SVG that fits the `@atta/ui` aesthetic; don't let it block the shell (placeholder covers that).
+- **Suggested agent-class:** **fast / or Principal** — asset sourcing/design, minimal code. (Could be done by hand by the Principal; flagged as a task so it isn't forgotten.)
+- **Stop-and-escalate:** none material; if it needs a real design decision, that's the Principal's call.
+
+### Task 9 — Per-tranche token/cost ledger (append-only in the model + Studio view) · Issue #110 · **last**
+**Project(s):** aeg, aeg-core · **Depends-on:** 1, 4 · **Conflicts-with:** —
+
+- **Principal intent (June 14):** every role reports its token/cost; each tranche carries a **simple table updated by each agent in each phase**; re-entering a stage (plan again, code again) **adds** a row, never overwrites. Add to the **model** now; the Studio **view** later (same task, sequenced last).
+- **Boundary — two halves:** **(model, now)** an **append-only per-tranche token ledger** — a markdown table (`Phase | Role | Agent/Model | Tokens in | Tokens out | Cost | Date`), either a `## Token ledger` section in the tranche file or a sibling `tranches/<name>.tokens.md` (sibling is cleaner for append-without-collision; decide at brief) — plus the **rule** (into `roles/*.md` + `aeg-manual-flow.md`): *at the end of a role's turn, append one row; never edit a row; re-entry appends; the tranche total is `sum(rows)`, derived at read time, never stored.* Same philosophy as forge-derived status + append-only logs. Also teach `@atta/aeg-core` to **parse** the ledger + a pure `sumLedger()`. **(view, later — same task)** Studio displays per-task/per-tranche token+cost totals on the tranche pages (task 4) / task detail (task 5), summed via `sumLedger()`.
+- **Two capture sources (the design constraint):** **terminal roles** (Developer in Claude Code) know their tokens (`/cost`) → append exact numbers, ideally auto (a close-out step or **Cetana** captures at dispatch-end). **claude.ai roles** (Planner / Brief Author / Reviewer) **cannot see their own token count** → rows filled **by the Principal from the claude.ai UI** figure, or left approximate. V1 accepts the manual seam (chat turns are cheap; coding dominates and is captured exactly). Design for this asymmetry — don't pretend it's uniform.
+- **Sizing:** model half small (table format + append rule + `aeg-core` parser/`sumLedger`); view half mid and hangs on the pages. `depends-on 1` (aeg-core parser) **and 4** (the pages to display on). Last in the tranche.
+- **Project(s) + blast radius:** `aeg-core` (parser/`sumLedger`) + `aeg` (display) + **model docs** (`roles/*.md`, `aeg-manual-flow.md`, and `state-machine.md` §13 append-only list — the ledger is a new append-only artifact + a per-role turn-end obligation). No runtime blast radius. **Tier 3, Type 1** (changes what every role does at turn-end).
+- **Dependency rationale:** **1** (aeg-core ledger parser) + **4** (the view). Additive in both — no conflict.
+- **Traps to avoid:** **append-only, never edit** (derive the sum at read time — a mutable total reintroduces merge-collisions + stale aggregates). Don't make claude.ai roles auto-report tokens they can't see — design for auto-terminal / manual-chat. Keep the `aeg-core` ledger parser **pure**. Token counts are exact from the meters; **cost depends on the PRICING table** (currently missing `claude-sonnet-4-20250514` → `$0.0000`, a known Herald-backlog bug) — show tokens reliably, cost best-effort, note the dependency.
+- **Suggested agent-class:** **mid** — format + append rule + pure parser + read-only display; the care is in append-only discipline + the two-source model.
+- **Stop-and-escalate:** if "every role appends a row" needs an automation layer that doesn't exist yet (Cetana can't cleanly capture terminal-session tokens) → ship the **manual append-by-hand** V1, backlog auto-capture, don't block. If the ledger format can't be parsed unambiguously → tighten it (`severity:strategy`, like task 1). If touching `state-machine.md` artifact classes is contentious → Type 1, Principal ratifies.
+- **Why last:** observes the *whole* process (every role, every phase); its view depends on the pages (task 4). Makes AEG's legibility include **cost legibility** (per-phase agent spend — neither Spec Kit nor Cordum surfaces this). Resolves the long-open **OQ-aeg-2 (cost/token tier)**.
+
+### Task 10 — Verification role: runtime test-plan execution as a model phase + merge gate · Issue #126 · **Tier 3, Type 1**
+**Project(s):** aeg-core · **Depends-on:** — · **Conflicts-with:** —
+
+- **Principal intent (June 16):** Across this tranche, four features merged CI-green but were broken at runtime — a missing DB migration, a missing env var, a missing IdentityProvider, an unexecuted polymorphic-input test plan. Root cause is structural: no role owns runtime verification. The Developer agent writes code + static gates but cannot exercise auth-gated, key-dependent, or browser-rendered flows; the Reviewer reads the diff, not a running app. So the test plan — which good agents already write into PR bodies — falls into a gap between "agent who can't run it" and "reviewer who doesn't," is never executed, and untested features merge. This task makes runtime verification a first-class phase with an explicit owner and a merge gate.
+- **Boundary — four coordinated edits to the model (no app code):**
+  - **New role `aeg-root/roles/verifier.md`** — the role that executes a PR's runtime test plan before merge. The **two-actor split** (mirroring D-048's two-source ledger design): **[agent]** items (non-auth, scriptable — SSRF rejections, parse checks, route responses, render smoke) run by a dispatched local agent with a booted app; **[principal]** items (auth-gated, key-dependent, visual — a real signed-in BYOK audit, a ModelPicker render behind Clerk) run by the Principal in a browser. The Verifier is a **phase** jointly satisfied by the Developer-agent and the Principal, **not a new actor**.
+  - **`aeg-root/skills/brief-authoring/SKILL.md`** (the canonical source — `.claude/skills/brief-authoring/SKILL.md` is a generated view per D-039, regenerated by `aeg generate-skills`) — make the Test Plan a **required brief field**, each item tagged `[agent]` or `[principal]`. A brief with runtime surface and no tagged test plan is blocked by Brief Validation. Pure-logic tasks declare `Test Plan: unit-tests-only` explicitly (an allowed value, not an empty skip).
+  - **`aeg-root/process.md` + `aeg-root/aeg-manual-flow.md`** — insert a **Verification phase** between Review and Merge: a PR is not mergeable until its `[agent]` test-plan items are executed-and-passing (reported in the PR) and its `[principal]` items are Principal-confirmed. State the doctrine: **CI green ≠ app boots ≠ feature works.**
+  - **`aeg-root/state-machine.md`** — register the Verification gate + the Verifier role; record "runtime test plan executed" as a merge precondition alongside "CI passing." Add a decision-log entry in `aeg-project/decisions.md` (this is Type 1 → Principal ratifies).
+- **Optional enforcement** (decide at build, ship doctrine regardless): a `verify-test-plan` CI check that fails if the PR body has unchecked `[principal]`/`[runtime]` boxes. If the PR-body parse is clean, ship it; if flaky, ship the doctrine + Brief-Validation requirement and backlog the CI enforcer. **Do NOT over-engineer** — a checkbox-state parse is the whole scope.
+- **Traps to avoid:** don't build a heavyweight QA bureaucracy — one tagged section in the brief + one gate before merge. Keep the **two-actor split** sharp (the all-session failure was pretending the agent could verify what it structurally can't). Make `Test Plan: unit-tests-only` first-class. The `[principal]` gate is satisfied by the Principal ticking the box, **not** the agent (mirror D-048's "dispatched agent can't self-fill" asymmetry).
+- **Suggested agent-class:** **mid-to-high** — small code, but a Type-1 constitutional change; care is in the role boundary, the two-actor ownership, and enforceable-but-not-bureaucratic wording.
+- **Stop-and-escalate:** if the CI enforcer proves flaky, ship doctrine + human gate, backlog the enforcer. If the role boundary needs a new actor the model lacks, **STOP** and escalate `severity:strategy` (Principal ratifies).
+
+---
+
+## Open questions / notes for dispatch
+
+- **Issues cut** (#94–#101, #110); the topology above is live. Assigning an Issue is the `backlog → todo` promotion.
+- **Dispatch order:** wave 1 = **1 (#94), 2 (#95), 8 (#96)** in parallel (parser, shell, icon). Then 3 (#97). Then the app-surface wave **4 (#98) → 6 (#99) → 5 (#100)** serialized (shared shell), with 7 (#101) slottable after 4. **9 (#110, token ledger) last** — its view hangs on task 4's pages.
+- **Progress (June 14):** task 1 (#94) MERGED via PR #105; task 2 (#95) MERGED via PR #108. Next dispatchable: 3 (#97), 8 (#96), and — once 4 lands — the app-surface wave.
+- **Runs fully parallel with `herald-onto-engine`** — disjoint collision domains (that tranche: engine/adapter/herald; this: aeg-core/apps-aeg/+ consumes @atta/ui read-only). No cross-tranche serialization needed (`tranches/README.md` §5, §11).
+- **Resolves AEG-product D-001's first tranche.** OQ-aeg-1 (primary viewer) remains open and is NOT in V1. **OQ-aeg-2 (cost/token tier) is now addressed by task 9** (#110).
+- **The `@atta/ui` reuse is additive** across tasks 2/5/6 — none edits `@atta/ui`. If any task finds it must, that's a scope change pulling Vāda/Herald into the blast radius → escalate before proceeding. (Task 2 surfaced one such follow-up — the TopBar `useUser()` unbind — now backlogged as a shared-package task.)
+- **Prototypes the model's tranche-lifecycle + cross-tranche-concurrency rules** (just added to `tranches/README.md` §11) — this is the first tranche to run *concurrent* with another.
+- **`aeg-core` registers as a project row (task-1 decision, June 14).** At task-1 dispatch the Brief Author leaned "don't register `aeg-core`"; the Developer's dig overturned that, correctly: `projects.md` explicitly allows a project to be "one package," the tranche's `Project(s)` column already names `aeg-core` multiple times, and the model's own validation rule (`projects.md` §"How `Project` is validated") makes every one of those cells **malformed** without a registry row — and forcing the pure parser to special-case an unregistered name would couple it to a hidden convention that breaks on the next such package. So `aeg-core` gets a registry row (`packages/aeg-core` · `packages/aeg-core/specs/` · state-tracked-globally, mirroring the `atta`/`desktop` pattern), added by task 1. **Precedent for the model:** a **shared package may be a registry row** — registry identity is about routing/validation resolution, not app-vs-package ontology; `aeg-core` is the first package-as-project. A one-line note belongs in `projects.md` §"What a project is" so the next shared package follows the same path rather than re-litigating — **do this on top of merged main** (task 1's PR already edited `projects.md`).

package/studio-standalone/.worktrees/fix/studio-standalone-repo-root/apps/vinaya/web/.next/standalone/aeg-root/tranches/completed/aeg-ui-v1.tokens.md

@@ -0,0 +1,17 @@
+# Token ledger — aeg-ui-v1
+
+Append-only per-tranche token/cost ledger. Format + rationale: `aeg-root/tranches/README.md` §12. Append-only artifact class: `aeg-root/state-machine.md` §13.
+
+**The rule:** at the end of a role's turn, append one row; never edit a row; re-entry appends another row; the tranche total is `sum(rows)`, derived at read time, never stored.
+
+**Capture sources:** terminal roles run in Claude Code (Developer; Archivist when automated) and self-report exact tokens via `/cost`. claude.ai roles (Planner; Brief Author; Reviewer; Security) cannot read their own token count and append the row with numeric cells as `—`; the Principal fills them later from the claude.ai UI usage figure.
+
+**Backfill policy:** the per-role turn-end obligation is introduced in task 9 (this tranche). Rows for prior tasks in this tranche (tasks 1, 2, 4, 7) are not backfilled — those turns predate the obligation, and inventing numbers would falsify the ledger. The ledger starts here.
+
+**Cost-table dependency (V1):** the adapter PRICING table is currently missing some recent models (e.g. `claude-sonnet-4-20250514`), so a row's `Cost` cell may read `$0.00` even when tokens are exact. Tokens are still authoritative; cost is best-effort and noted at this seam. Backlogged in `apps/herald-ai/specs/herald-backlog.md`.
+
+| Phase | Role | Agent/Model | Tokens in | Tokens out | Cost | Date |
+|-------|------|-------------|-----------|------------|------|------|
+| 9: brief | Brief Author | claude-opus-4-7 (chat) | — | — | — | 2026-06-15 |
+| 9: develop | Developer | claude-opus-4-7 (CC) | — | — | — | 2026-06-15 |
+| tranche-close | Tranche Archivist | claude-sonnet-4-6 (CC) | — | — | — | 2026-06-21 |