@attalabs/vinaya 0.4.2 → 0.4.4

package/studio-standalone/.worktrees/fix/studio-standalone-repo-root/node_modules/@attalabs/vinaya/studio-standalone/node_modules/@attalabs/vinaya/aeg-root/process.md

@@ -0,0 +1,371 @@
+---
+sidebar_title: Process
+---
+# Process: From idea to merged code
+
+This document describes how work flows through the AEG operational model — from the moment the Principal has an idea to the moment that work merges to `main` with all specs and skills updated.
+
+It is the canonical "how do we actually work?" document. Every other PM doc (`coordination.md`, `state-machine.md`, `tranche-model.md`, role docs, `brief-authoring` skill) describes a slice of this process. This document stitches them together into a single readable walkthrough.
+
+If you are starting a new session and need to understand the workflow, read this first. Then `coordination.md` for session protocol, then the role doc that applies to you, then any project-specific specs.
+
+---
+
+## Where tasks come from: the tranche
+
+The thirteen phases below are the **per-task** flow. Tasks do not appear from nowhere — they are produced by the **Planner** (a Planner / Brief Author mode) when a tranche is planned: the Planner turns an intent plus a slice of tickets into a set of **forge Issues** (one per task) plus a thin topology file declaring their `depends-on` / `conflicts-with` edges (`tranche-model.md`, `roles/planner.md`). Each Issue that enters the flow below is a task the Planner already shaped.
+
+**Status is never stored.** Throughout every phase, a task's status is *derived* from the forge — Issue open/assigned, branch existence, PR open, review decision, merge — never written to a label or a file. When a phase below says a task "becomes in-review," it means *a PR was opened*, not that anyone set a status field.
+
+---
+
+## The thirteen phases
+
+Every piece of work moves through some subset of these. Trivial work (Tier 0) skips most; complex work (Tier 3) hits all and may loop back from review.
+
+```
+1.  Idea origination
+2.  Pressure-testing (optional; high-stakes only)
+3.  Brief authoring (just-in-time)
+4.  Brief validation
+5.  Dispatch
+6.  Execution
+7.  Escalation (optional; only when Developer blocks)
+8.  Task Done verification
+9.  Pull request opened
+10. Review (agent passes, then human reviews)
+11. Verification (runtime test plan execution — agent half + Principal half)
+12. Merge
+13. Tranche Close
+```
+
+> **Doctrine: CI green ≠ app boots ≠ feature works.** Phase 11 (Verification) exists because four consecutive features merged CI-green and were broken at runtime. The static gates of Phase 8 and the diff-reading reviews of Phase 10 cannot exercise an auth-gated / key-dependent / browser-rendered path. Phase 11 closes that gap with a tagged, executed test plan (see `roles/developer.md` § Verification and).
+
+After merge, the **Archivist** runs close-out (`roles/archivist.md`). That's the final step of the flow.
+
+---
+
+## Phase 1: Idea origination
+
+**Who:** Principal and Planner.
+
+The Principal brings an idea. The Brief Author pressure-tests, pushes back, surfaces related decisions, checks whether it's already specced. The Brief Author's job is **not** to immediately agree and plan — it's to:
+- Read the relevant specs to confirm the idea isn't already settled
+- Push back if it's wrong, premature, or duplicative
+- Identify the impact tier (0 / 1 / 3) — this drives everything downstream
+- Identify the Type 1 (irreversible — Principal ratifies) vs Type 2 (reversible — Brief Author ratifies) profile
+
+If already locked or specced, the conversation ends here. If genuinely new, it produces a shared understanding of what the work is, why now, its tier, and its decision profile — which the Planner then turns into Issues (the tranche).
+
+**Artifacts:** usually none (conversation is ephemeral). A significant decision is stated in the pull request that carries the work.
+
+**Exit:** the idea dies, or it's worth planning into a tranche.
+
+---
+
+## Phase 2: Pressure-testing (optional)
+
+**When:** high-stakes only — architectural locks, project-direction shifts, decisions blocking weeks of downstream work, or when the Principal's instinct and the Brief Author's read disagree. **Not** for tactical decisions, naming, or style. The Principal may waive it and ratify in-session (the pull request notes the skip, for audit honesty).
+
+**Who:** Brief Author orchestrates; external AI reviewers (vendor-diverse — e.g. Gemini, Grok, DeepSeek, ChatGPT) participate via pasted briefs.
+
+The Brief Author writes a brainstorming brief (idea, sketch, alternatives, what to pushback on), pairs it with `reviewer-prompt.md`, and pastes to each reviewer. The Brief Author synthesizes. Converge on a flaw → back to Phase 1. Validate → proceed. **Max two rounds** — if two don't converge, the issue is framing, not a third round.
+
+This phase pressure-tests an *idea*; Phase 10 reviews *shipped code*. Different things.
+
+**Exit:** Brief Author and Principal agree the direction holds.
+
+---
+
+## Phase 3: Brief authoring (just-in-time)
+
+**Who:** Planner / Brief Author in Brief Author mode.
+
+When a task is picked up for execution, the Brief Author writes its brief — **just-in-time, not at plan time** — following the `brief-authoring` skill. The brief MUST include:
+- Impact tier (0 / 1 / 3)
+- Type 1 / Type 2 declaration if architectural decisions are expected
+- `principal_delegate:` if the work runs while the Principal is offline
+- Spike flag (`spike: true`) if exploratory
+- The mandatory worktree-first Step 0 (`git worktree add .worktrees/task/<tranche>/<n> -b task/<tranche>/<n> origin/main` — no exceptions)
+- An explicit documentation-update list tied to the tier
+- Optional `Ticket:` (reference-only provenance) and, in a multi-project repo, `Project:` (resolves against `projects.md`)
+- Clear scope, stop conditions, Task Done checklist
+- A deliverable section stating "done" means "passed Phase 11 verification," not "PR opened"
+
+A brief is self-contained and executable without further conversation. If it needs clarifying questions, it's incomplete.
+
+**Where the brief lives:** it is pasted to the Developer and will land in the **PR body** at Phase 9. It is **not** committed and **not** put in the Issue body — the Issue (created by the Planner) holds task identity + metadata only. A brief in the Issue would age before work starts.
+
+**Artifacts:** the brief (a markdown block, not a committed file). The task's Issue already exists from tranche planning.
+
+**Exit:** the brief is well-formed and ready to dispatch.
+
+---
+
+## Phase 4: Brief validation
+
+**Who:** Archivist gate (automated) + the Developer's own entry gate.
+
+Before work begins, the brief is checked for well-formedness:
+- `tier:` present and valid; brief structure follows the skill (scope, stop conditions, deliverable)
+- `principal_delegate:` valid if declared
+- `Project:` (if present) resolves against the registry
+- No obvious contradiction with the ratified specs (string-match heuristic)
+- The task's Issue carries only execution metadata — **no** planning fields (priority/estimates/points), which the required Issue template + a CI check reject
+
+If it fails, it's not dispatchable until fixed. The Developer also re-checks well-formedness as its entry gate (`roles/developer.md`) — a malformed brief is refused, not guessed at. (Brief Validation is a real blocking gate — the `Brief Validation` step (9/9) of the `aeg-gate-suite` job; see `state-machine.md` for mechanically-enforced vs trusted.)
+
+**Exit:** the brief is well-formed and dispatchable.
+
+---
+
+## Phase 5: Dispatch
+
+**Who:** Principal (or delegated Brief Author within ratification-window scope), by hand or via an automation layer.
+
+Dispatch starts the task. There are two equivalent routes:
+
+- **Manual:** the Principal pastes the brief into the coding agent. The brief's worktree-first Step 0 makes the Developer create its own worktree (`.worktrees/task/<tranche>/<n>/`, branch `task/<tranche>/<n>`, from `origin/main`) as its first action.
+- **Automated:** an automation layer creates the worktree, generates the agent's config, spawns the Developer in it, and streams progress. This is a convenience; the semantics are identical to manual.
+
+Either way: **before starting, the Developer checks the dispatch gates against the forge** — every `depends-on` task's PR merged, no `conflicts-with` sibling's PR open. If a gate isn't satisfied, it does not start (the task serializes). Opening the branch *is* the `todo → in-flight` transition; nobody writes a status label.
+
+The branch name `task/<tranche>/<n>` is the convention that links the task to its branch and PR, so any role can derive its live status with one forge query.
+
+**Exit:** the Developer is working in its worktree.
+
+---
+
+## Phase 6: Execution
+
+**Who:** Developer (the coding agent — spawned or pasted).
+
+Per `roles/developer.md`, the Developer reads `coordination.md` / `state.md` / its role doc, derives live execution state from the forge (session-start queries in `coordination.md`), reads the relevant skills (auto-loaded when matching code is touched) and project specs, confirms pre-flight (starting with the worktree), and works in small, frequent commits on the `task/<tranche>/<n>` branch. When dispatched by an automation layer, it streams progress events to that layer.
+
+The Developer cannot author its own briefs, expand scope without escalation, modify files outside scope, skip verification hooks, skip the Task Done checklist, or **write status anywhere** (status is derived). If the brief is wrong or contradicts reality, it escalates (Phase 7) — it does not paper over confusion or improvise outside scope.
+
+**Exit:** the work is done (Phase 8), or the Developer is blocked (Phase 7).
+
+---
+
+## Phase 7: Escalation (optional)
+
+**When:** the Developer hits a decision not covered by the brief, finds the brief contradicts reality, or needs new information.
+
+**Who initiates:** Developer.
+
+The Developer escalates through the escalation mechanism — a manual escalation note, or, if dispatched by an automation layer, its request-input mechanism — tagged with a `severity` that routes it:
+
+- `severity: execution` → Brief Author. Most common: a deprecated dependency, an unanticipated flag, a "null or throw?" call.
+- `severity: strategy` → Brief Author. Less common: the brief's approach has a structural problem; the work touches an undiscussed area.
+- `severity: product` → Principal. Rare: user-visible behavior the brief didn't address; a Type 1 decision is required.
+
+The task is marked `blocked` (an `aeg:blocked` label — the one status with no native forge fact) until a reply arrives. The responder (Planner or Principal) formulates a reply and the Developer resumes.
+
+**Type 1 during execution:** if the question needs an irreversible decision and the Principal isn't available, the Issue/PR stays labeled `needs:principal-input`; the next window resolves it. The Developer may terminate and resume via a follow-up dispatch after the window.
+
+**Brief amendment:** if the brief itself is wrong in a way that blocks all paths, the Brief Author issues an amendment (logged as a separate event, not a brief edit — briefs are frozen after dispatch) or kills the task.
+
+**Exit:** the Developer is unblocked and resumes.
+
+---
+
+## Phase 8: Task Done verification
+
+**Who:** Developer.
+
+Before opening the PR, the Developer runs the tier-appropriate Task Done checklist (`roles/developer.md`). The commands below are this repo's instances (Bun/JS) — substitute your repo's declared equivalents:
+- **Tier 0:** typecheck + lint, tests if applicable, PR description follows template (and will carry the brief)
+- **Tier 1:** Tier 0 + specs updated, skills updated if conventions shifted, `verify-docs --pr` passes
+- **Tier 3:** Tier 1 + per-project PM updated if state changed, Lock entry if irreversible, `docs-index.md` regenerated
+
+`verify-docs --pr` is a **real gate**, the same script CI runs. If any item fails, the Developer fixes or escalates — the PR does not open.
+
+**Exit:** all Task Done items pass.
+
+---
+
+## Phase 9: Pull request opened
+
+**Who:** Developer.
+
+The Developer opens a PR with:
+- Title in commitlint format (`Type: Subject`)
+- **The brief pasted into the body** — its permanent home, read by the Reviewer and Archivist
+- A `Tier:` declaration (`Tier: 0|1|3`) so verify-docs reads the correct tier
+- `Closes #N` linking the task's Issue (so the merge auto-closes it)
+- Body following the PR template (what shipped, validated mechanism, what's not in scope, next steps)
+
+**Opening the PR is itself the `in-flight → in-review` transition** — derived from the PR's existence, not written anywhere.
+
+CI runs typecheck, lint, tests, `verify-docs` (the load-bearing doc gate — fails if tier-appropriate updates are missing), and pre-commit hooks. The Archivist posts advisory comments (synthesis hints, related-decision surfacing, hygiene) — advisory, not blocking.
+
+**Exit:** PR is open, CI green (including verify-docs), advisory comments addressed or dismissed.
+
+---
+
+## Phase 10: Review
+
+Two stages: independent **agent passes** (fresh-context), then **human reviews** (Principal + Brief Author). Agent passes run first and feed the human reviews — they do not replace them.
+
+```
+code-reviewer pass → security pass → Principal code review → Brief Author spec review → merge
+```
+
+### Stage A — Agent review passes
+
+Each pass is a **separate fresh-context invocation** with no memory of writing the code (the independence rule). Manual: the Principal pastes the review prompt. Automated: the automation layer dispatches the `code-reviewer` and `security-reviewer` passes. The agent reads its role doc + the PR diff + **the brief in the PR body**, and emits a structured verdict. Review agents do not edit code, do not merge, and do not write status.
+
+1. **Code-reviewer pass** — `roles/reviewer.md`. Brief conformance, scope violations, test honesty, code quality, doc coupling, lock awareness, multi-project reach. Emits `VERDICT: APPROVE | REQUEST CHANGES` (BLOCKER / MAJOR / MINOR).
+2. **Security pass** — `roles/security.md`. Secret leakage, BYOK/crypto, auth/permissions, MCP/agent-tooling exposure, injection surfaces, dependency risk. Runs a config-security scan over the agent/MCP/hook config when that config is touched. Emits `VERDICT: PASS | FAIL` (CRITICAL / HIGH / MEDIUM / LOW).
+
+A BLOCKER (code) or CRITICAL/HIGH (security) returns the PR to the Developer, who fixes on the **same branch**; the pass re-runs. (Pushing fixes returns the PR's review decision to open — the `changes-requested → in-review` transition, derived.) An `[ESCALATE]` finding routes to Brief Author (strategy) or Principal (`severity: product`).
+
+### Stage B — Human reviews
+
+**Code review (Principal).** The Principal reviews the diff — does it match the brief, scope violations, honest tests, spot-check quality. The agent verdict is an input, not a substitute; the Principal can overrule either way.
+
+**Spec review (Brief Author).** Do the specs describe what was built? Is the pull request's stated reasoning honest about what changed? Coherence, not technical correctness (that's the Principal's code review).
+
+If both pass (and agent verdicts are APPROVE/PASS or their findings resolved) → merge. If issues are found → back to the Developer with specific feedback. Loops, but three cycles signals a deeper issue.
+
+**Enforcement note:** the agent passes are **trusted discipline** today — Phase 10 requires them, but no CI bot dispatches them automatically yet. The mechanical CI gate is `verify-docs` (Phase 9). Automating review-agent dispatch is future work.
+
+**Exit:** agent passes complete, both human reviews pass.
+
+---
+
+## Phase 11: Verification (runtime test plan)
+
+**Who:** the Developer-agent (for `[agent]` items) and the Principal (for `[principal]` items). Verification is a *phase*, not a new actor — see `roles/developer.md` § Verification.
+
+A PR that has passed code review and security review still has not been run. The reviews read the diff; the static gates of Phase 8 prove the code compiles and types and tests; CI does not boot the app. Phase 11 boots it, executes the brief's **Test Plan** (a required brief field, `brief-authoring/SKILL.md` §9), and posts the results onto the PR. Doctrine: **CI green ≠ app boots ≠ feature works** — runtime verification is its own gate.
+
+The test plan is split by who can structurally execute each item:
+
+- **`[agent]` items** (non-auth, scriptable — SSRF rejections, parse checks, route responses, render smoke). The Developer-agent boots the relevant dev server(s) from the PR's branch, runs each `[agent]` item, and posts the actual output as evidence on the PR. Paraphrase is not evidence; the command + the response body is.
+- **`[principal]` items** (auth-gated, key-dependent, visual — a signed-in BYOK audit, a ModelPicker render behind Clerk, a card landing in the right column). The Principal runs each item in a browser with the dev server up and ticks the box on the PR. The agent **cannot** tick `[principal]` boxes and the Principal does **not** tick `[agent]` boxes — the asymmetry is the whole shape of the gate (mirror of the chat-vs-terminal token capture).
+
+**`Test Plan: unit-tests-only`** is a first-class allowed value for pure-logic briefs (a parser, a sum function, a markdown normaliser — nothing the §4 Technical Surface Map lists as a runtime path). When the brief declares it, Phase 11 is satisfied by the CI unit-test gate alone; no runtime execution is required. Brief Validation rejects `unit-tests-only` on a brief whose §4 surface includes a runtime path.
+
+**The merge gate.** A PR is not mergeable while any Test Plan checkbox is unticked — `[agent]` items waiting for evidence, or `[principal]` items waiting for Principal confirmation. An `[agent]` item that fails returns the PR to the Developer on the same branch (same loop as a `CHANGES_REQUESTED` review); a `[principal]` failure does the same. Re-running an item appends a fresh evidence comment; it does not edit the previous one.
+
+**Enforcement note:** the `verify-test-plan` CI check (a checkbox-state parse over the PR body) is **live and mandatory** — `packages/aeg-core/bin/verify-test-plan.ts` runs unconditionally as one of the nine always-produced verdicts of the `aeg-gate-suite` job (`.github/workflows/forge-lifecycle.yml`). It is not opt-in and not decided per-tranche. What remains **trusted discipline** is the judgment the parse cannot make — whether a ticked box was genuinely run. The doctrine (Phase 11 exists; the brief carries a tagged Test Plan; an unticked box means not-yet-mergeable) holds whether the CI enforcer is on or off. Brief Validation rejects a brief that touches a runtime surface and has no tagged Test Plan.
+
+**Exit:** every `[agent]` Test Plan item has an evidence comment on the PR and is ticked; every `[principal]` item is ticked by the Principal. Or: the brief declared `Test Plan: unit-tests-only` and the §4 surface is pure-logic.
+
+---
+
+## Phase 12: Merge
+
+**Who:** Principal (or Brief Author if explicit per-PR delegation was set in the brief).
+
+The Principal merges. Tier 3 work merges during a ratification window (`coordination.md`); Tier 0/1 anytime. The merge **auto-closes the linked Issue** (via `Closes #N`) — and the merge *is* the `merged` status; nobody writes a label. An automation layer may surface a completion notification.
+
+**Post-merge: the Archivist closes out** (`roles/archivist.md`) — confirms the Issue closed, docs coherent, per-project pinned state Issue updated for every project the task listed, `docs-index.md` regenerated. It **flags** (does not perform) orphaned branches and worktree removal. It writes no task status.
+
+**Exit:** code is in main, Issue closed, close-out done.
+
+---
+
+## Phase 13: Tranche Close
+
+**Who:** Principal (declares), Tranche Archivist (executes).
+
+When the last task of a tranche has merged, the Principal declares it done and dispatches the Tranche Archivist with an explicit declaration that the tranche is closed. The Tranche Archivist (roles/tranche-archivist.md) owns all close-out steps. No automation or GitHub Actions required — self-contained, forge-agnostic.
+
+**Steps (executed by the Tranche Archivist):**
+
+1. **Verify the forge** — confirm all task PRs are merged, all task Issues are closed, no orphaned branches remain.
+
+2. **Write the retrospective** — append a new section to `aeg-project/lessons.md` with observations on what went well, what stalled, carry-forward lessons, decisions made, and unbuilt tasks. Assembled from merged PR summaries and topology — not invented.
+
+3. **Archive the tranche** — set `Lifecycle: complete` as the first line after the tranche file's heading, move the file from `aeg-root/tranches/` to `aeg-root/tranches/completed/` (one commit: `git mv`). This signals to the AEG Studio and any reader that the tranche is no longer active.
+
+4. **Update state docs** — refresh `aeg-project/state.md` (last-updated date, current focus pointer, recently shipped section, clear any resolved pending-manual-ops). Active-work state is derived from the forge — no `now.md`.
+
+5. **Surface pending Type 1 decisions** — query the `needs:principal-input` label for this tranche's open items. List them explicitly; the Principal ratifies at the next ratification window.
+
+6. **Update docs-index.md** — if tranche tasks added, removed, or renamed files tracked in the index, confirm it reflects the current state.
+
+7. **Post tranche provenance** — comment on the last merged task PR with a summary of tasks completed, duration, archival path, pending ratifications, and any dangling items.
+
+**Artifacts:** no new commits beyond the tranche file move and state doc updates — those commits *are* the close-out. Lessons appended to `lessons.md`. Pending decisions surfaced (not ratified by the Archivist).
+
+**Exit:** tranche is archived, state docs are current, pending decisions are surfaced, and the Principal has declared what's next (new tranche, pause, pivot, cross-cutting initiative).
+
+---
+
+## What happens after merge and tranche close
+
+The Principal eventually removes the worktree (`git worktree remove …`) — deliberate friction; the worktree is sometimes useful for post-merge inspection. The specs and skills are now canonical repo state that future sessions read.
+
+---
+
+## Variations and special cases
+
+### Spike work
+`spike: true` → reduced Task Done (typecheck + lint, with what was tried and learned recorded in the pull request). Spike code does not merge — it rebases away or converts to a full Tier 1+ task in a separate brief.
+
+### Tier 0 work (trivial)
+Skips Phase 2; short brief; minimal checklist; light Phase 10 (a code-reviewer pass is cheap insurance, but the security pass and Brief Author spec review can be skipped when there's no config/auth surface and no spec change). Declare `Tier: 0` in the PR body so verify-docs doesn't require doc updates.
+
+### Multi-developer parallel work
+Each Developer gets its own worktree, branched from `origin/main`. Parallel safety is the dispatch gates: a task does not start while a `conflicts-with` sibling's PR is open, or before a `depends-on`'s PR merges (`tranche-model.md` §8). Conflicts are declared at planning time as package-level collision domains — the coordination lives in the tranche's edges, not in ad-hoc scope-checking. When unsure two tasks collide, the Planner declares the conflict and serializes.
+
+### Cross-project tasks
+A task may legitimately span multiple projects (one branch, one PR, `Project: a, b`) when the change is only verifiable as a unit (e.g. generalize a shared engine + migrate the first consumer). Review fans out across each project's lens; close-out updates each project's state. See `projects.md` and `roles/planner.md`.
+
+### Rollback
+A rollback is its own task with its own brief. The decision to roll back is a Type 1 decision (ratification window). The spec for the affected surface is updated to describe the state rolled back to.
+
+---
+
+## Anti-patterns
+
+- **Going straight to brief authoring without Phase 1** — produces briefs that solve the wrong problem.
+- **Dispatching an unvalidated or malformed brief** — the Developer's entry gate refuses it; bypassing the gate manually defeats the model.
+- **Letting the Developer review its own work** — the Phase 10 agent passes are separate fresh-context invocations for a reason.
+- **Writing status anywhere** — status is derived from the forge. Setting a label or editing the tranche file to record state recreates the racing status model the design eliminated.
+- **Putting the brief in the Issue** — it lives in the PR body, just-in-time. The Issue is task identity only.
+- **Developer scope creep** — "while I'm here…" is a new task and a new brief.
+- **Brief Author self-ratifying Type 1 decisions in solo sessions** — they queue as PENDING for a ratification window.
+- **Skipping the Task Done checklist under deadline pressure** — it's the load-bearing discipline; skipping it is how the BYOK gap happened.
+- **Treating "PR opened" as "done"** — done is "passed Phase 11 verification" (which requires Phase 10 review to have already passed).
+- **Treating "review passed" as "ready to merge"** — review reads the diff; verification runs the booted app. CI green ≠ app boots ≠ feature works. An unticked Test Plan box is the merge gate even when the reviews are clean.
+- **Inventing a Test Plan at verification time when the brief omitted one** — that is the Brief Author's job by design; verification *executes* the plan, it does not author it. A missing Test Plan is a brief-validation failure (`needs:brief-correction`).
+- **Mis-tagging a `[principal]` Test Plan item as `[agent]`** to make the agent half look complete — the asymmetry is structural (the agent surface lacks auth/keys/eyes); reclassifying loses the point of the split.
+- **Building a dynamic conflict scanner** to catch what the Planner missed — declare conflicts conservatively and serialize instead (`tranche-model.md` §9).
+
+---
+
+## How this process maps to file artifacts
+
+For which files get mutated in which phase by which actor, see `state-machine.md` (the artifact + mutation matrix). For the roles, see `roles/principal.md`, `roles/planner.md`, `roles/brief-author.md`, `developer.md`, `reviewer.md`, `security.md`, `archivist.md`. For the tranche/task model, see `tranche-model.md` and `roles/planner.md`. For brief authoring, see the `brief-authoring` skill.
+
+---
+
+## Spec format guidance
+
+Specs produced during process phases follow this format. Adopted from GitHub Spec Kit's spec-template (May 12, 2026 evaluation).
+
+### Required sections
+
+**1. User stories (prioritized).** Priority (P1 must / P2 should / P3 nice), story ("As a [role], I want [action], so that [benefit]"), and an Independent Test (how it's verified in isolation).
+
+**2. Acceptance scenarios.** Given/When/Then, one or more per story.
+
+**3. Success criteria** — measurable, user-focused, technology-agnostic. ("User completes signup in under 60 seconds." NOT "function returns void" / "uses Drizzle.")
+
+**4. Edge cases** — explicit enumeration, one bullet each.
+
+**5. `[NEEDS CLARIFICATION]` markers** — wherever there's a real ambiguity, mark it inline; do not silently guess. Each is a candidate escalation point.
+
+### When this format applies
+New project specs and major feature specs (Tier 1 / Tier 3); the "Goal" section of dispatch briefs. NOT for Tier 0 tasks or narrative lessons/anti-patterns.
+
+### Retroactive migration
+Existing specs are not migrated wholesale; a spec adopts this format when it's next rewritten for other reasons.
+
+### Why
+Spec Kit's evaluation found the template produces measurably better-structured artifacts — explicit priority, visible ambiguities, success tied to user-observable outcomes. The repo adopts the format without adopting Spec Kit the tool. (The open question of whether an orchestrator eventually wraps Spec Kit templates as MCP tools was Cetana's; it retired with that product.)

package/studio-standalone/.worktrees/fix/studio-standalone-repo-root/node_modules/@attalabs/vinaya/studio-standalone/node_modules/@attalabs/vinaya/aeg-root/roles/archivist.md

@@ -0,0 +1,167 @@
+---
+sidebar_title: Archivist
+title: Archivist
+order: 6
+role_id: archivist
+description: Closes out a merged pull request, recording what shipped and the intent it came from.
+actor: either
+performs:
+  - close-the-issue
+  - confirm-docs-updated
+  - update-per-project-state-issue
+  - update-docs-index
+  - assemble-provenance-block
+  - post-provenance-comment
+  - append-token-ledger-rows
+refuses_when: >
+  The task's PR isn't merged — close-out happens after merge, not before.
+summary: Ever lost track of why a decision was made, months later?
+---
+# Archivist — Role Reference
+
+## The short version
+
+You close out one merged pull request, so that months later it is still clear what shipped and from what intent.
+
+**You own** — the aftermath of a single task. The task's issue is closed explicitly and confirmed closed, rather than trusted to close itself. A change large enough to have needed a recorded decision actually has one. The documents the brief promised did move, and say what the merged code does — presence was checked mechanically; you check truth. Each project the task touched has its state record updated. The document index still matches the files that exist. Every role's token report for this task is collected into the ledger, including your own. And the provenance record is assembled and posted to the merged pull request: the issue, the impact tier, the brief, the projects, the model that did the work, both review verdicts, the decision if there was one, and the merge itself.
+
+**You refuse** — when the pull request has not merged. That is your only precondition, and it is read from the forge rather than from anything written down. A merged pull request is the single fact that authorises close-out; before it, there is nothing to make durable.
+
+**You never** write task status anywhere, author a provenance field, reopen or re-argue the work, or merge. Every field you post is copied from something the merge already froze; where a source fact is missing you record it as missing, because a record with one invented field is worse than an honest gap. You never perform the cleanups you find either — a stale branch, a leftover working copy — you list them for a person.
+
+**How it physically runs** — you run after the merge, found by the task's branch name. The mechanical half runs by itself when the merge lands: the issue is closed and the provenance record posted automatically, once per pull request, from frozen facts only. The judgement half is a dispatched turn — the decision record, the coherence of the documents, the project state, the index, the ledger — and it re-confirms the automated half landed rather than repeating it. Everything you produce lives on the merged pull request, append-only once merged. Nothing goes into the plan: adding status, dates or provenance there is the one regression this design exists to prevent.
+
+
+---
+
+## Reference
+
+**Audience:** An agent (or an automation layer) invoked to **close out** a merged pull request — the final step of the flow. Often automated, but fully runnable by hand.
+
+You are the Archivist when a task's PR has been merged and the work needs to be made durable and tidy: records updated, the tranche left honest, loose ends flagged, and a provenance record assembled. You are NOT the Developer, Reviewer, or Principal. You do not write code, judge correctness, or merge — those are done. You make the *aftermath* correct.
+
+**Scope:** this role closes out individual tasks after their PR merges (Phase 12). It does NOT close out tranches. Tranche close-out — the retrospective, archival, state-sync, and ratification sweep at the end of a full tranche — belongs to the Tranche Archivist (roles/tranche-archivist.md), which runs Phase 13. If you were dispatched to close a tranche, you are in the wrong role doc.
+
+---
+
+## Entry gate (self-locating) — refuse if it isn't your turn
+
+- **The PR is not merged** → *"Nothing to close out — the PR for task N isn't merged. Close out happens after merge, not before."*
+
+This is your only hard precondition, and it is forge-derived: you query the PR's merge state, you do not read a status field. A merged PR is the single fact that authorizes close-out. (Find the PR via the branch convention `task/<tranche>/<n>`.)
+
+---
+
+## Automation status
+
+Items 1 (Issue close) and 8 (provenance block) below now run **automatically,
+post-merge**, via `.github/workflows/archivist.yml::post-merge`
+(`packages/aeg-core/bin/archive-task.ts`) — triggered by the merge event
+itself, not by a dispatched Archivist turn. The job resolves the merged PR
+from the merge commit, skips non-task branches, and skips PRs that already
+carry a provenance comment (idempotent, scoped **per-PR** — an Issue can
+legitimately accrue multiple merged PRs over its life, e.g. rework after a
+reopen, and each merged PR gets its own provenance block; idempotency never
+spans PRs). It assembles the block purely from frozen PR facts — the
+cardinal ASSEMBLE-never-author constraint below applies identically to the
+automated job — and explicitly closes the Issue, confirming the
+closed state before exiting. It fails loud (non-zero exit, error printed) on
+any `gh`/permission error rather than swallowing it into a silent success.
+
+Items 2–7 remain judgment work the automated job does **not** perform:
+docs coherence with what actually merged, per-project
+state (a pinned forge Issue per project — see item 5 below),
+`docs-index.md`, and the token ledger still require a dispatched Archivist
+turn (agent or human). Where the automated job can't assemble a
+required field for items 1/8 (e.g. no `Tier:` field, no code-review verdict
+comment), it surfaces a DANGLING marker in the posted comment rather than
+guessing — a dispatched Archivist turn still investigates those.
+
+**Task-vs-tranche boundary.** This automates only the **per-task** close-out mechanics
+above. The **Tranche** Archivist (`roles/tranche-archivist.md`) —
+the retrospective, archival, state-sync, and ratification sweep at the end of
+a full tranche — is untouched: it remains Principal-dispatched,
+forge-agnostic, and explicitly "no GitHub Actions required." Nothing here
+extends automation to tranche close-out.
+
+---
+
+## What you do at close-out
+
+Work through this checklist for the merged task. Confirm each against reality — do not assume.
+
+1. **Issue closed — mandatory explicit step. Automated post-merge — see "Automation status" above.** Close the task's Issue explicitly via `gh issue close <N>`. **Do not rely on GitHub's `Closes #N` auto-close** — it is advisory-only and does not reliably fire across all branch/merge configurations. The Archivist is the **single closer**: closing the Issue is a named, mandatory, non-optional step in the close-out procedure, not a confirmation of something that may or may not have already happened. After running `gh issue close <N>`, confirm the closed state: `gh issue view <N> --json state | jq '.state'` — must return `"CLOSED"`. If it does not, re-run and confirm before proceeding. Note: running `gh issue close` on an already-closed Issue is a no-op (safe); running it is always correct. A dispatched Archivist turn re-confirms this step happened rather than re-performing it.
+2. **Docs updated.** The tier-required docs the brief listed actually moved. (CI's `verify-docs` gated *presence*; you confirm they're *coherent* with what merged.)
+3. **Per-project status updated — for every project the task listed.** Per-project operational state is no longer a `state.md` file — it lives on a **pinned GitHub Issue**, one per project, created at the migration (one per project with its own folder; the root ecosystem-wide bucket — every project without one plus cross-project facts — is its own pinned Issue). Update state by editing that Issue's body if state changed (phase advance, resolved known issue, updated pending-manual-ops). A multi-project task updates *every* listed project's pinned Issue. This is the one place you write to per-project state — and note: this is project *status documentation*, not task status (task status stays derived from the forge). (`now.md` no longer exists.)
+4. **`docs-index.md`** updated if files were added, removed, or renamed.
+5. **Token ledger rows recorded.** No role appends its own row on a task branch. **For almost every task there is now no file to append to:** the forge-native migration deleted `<name>.tokens.md` for every active tranche, and `packages/aeg-core/bin/check-no-disk-state.ts` CI-blocks adding a new one anywhere in the repo (tokens live in the PR body, not a committed ledger). Where a legacy file does still exist you remain its sole writer; where none does, do not create one. Either way, collect every role's token report for the task: the Developer's "Token report" section in the PR body, any re-push reports, and the Reviewer's / Security's one-line `Tokens: …` report in their verdict comment(s). For each report found, append one row (`Phase | Role | Agent/Model | Tokens in | Tokens out | Cost | Date`) — one row per role-turn, including re-entry rows (a second Developer turn, a re-review), and including your own turn (`Phase: <task-id>: archive`, `Role: Archivist`). Use the exact figures a terminal role reported (Developer, and your own session if run in Claude Code); leave `—` for any cell a chat role's report didn't carry. If a role's report is missing entirely (e.g. the Reviewer's verdict comment carries no `Tokens:` line), do not fabricate a row for it — flag it under DANGLING instead. **The live-read mechanism is the ledger now:** Studio's tranche page no longer reads `<name>.tokens.md` to render token totals — it fetches every merged PR on the task's own branch and re-derives the same rows live (`aggregateTaskTokenRows`, `packages/aeg-core/src/parse-token-report.ts`, called from `apps/vinaya/web/src/lib/forge/fetch-token-ledger.ts`). Since no active tranche carries the file and CI blocks adding one, that re-derivation *is* the ledger; the sole-writer duty above governs only a legacy file that predates the deletion. One real, load-bearing gap in the live mechanism, discovered building it: it can only recover rows from a PR's own body/comments, so it cannot see your own `Phase: <task-id>: archive` row (you have no PR to report it through) or the Planner's `Tokens: planning …` report (no reliable way to attribute a plan PR to one task without false-positive cross-task matches — see that file's own docstring). Those two sources therefore have **no durable home today** — that is a known, open gap, not a licence to create a `.tokens.md` for them.
+6. **Provenance block assembled — automated post-merge, see "Automation status" above** (see below for the field shapes) and posted to the merged PR record. A dispatched Archivist turn re-confirms the comment landed rather than re-assembling it, unless the automated job flagged DANGLING fields worth investigating further.
+
+## The provenance block
+
+At close-out you assemble one **provenance record** for the task and post it as a comment on the merged PR (the PR is a frozen truth domain once merged; the comment is append-only). This is the audit-by-construction output — the thing a reviewer, an auditor, or a future maintainer reads to know *what shipped, from what intent, checked by whom*.
+
+**The cardinal constraint: you ASSEMBLE, you do not author.** Every field is **copied from a fact the merge already froze** — the brief (in the PR body), the PR's reviews, the forge's own merge metadata. You compute nothing new and you store no new state. The provenance block is a **projection of frozen facts**, exactly like derived status is a projection of forge state — which is why it does **not** violate the anti-regression rule against storing execution metadata: it lives on the merged PR, not in the tranche file or the Issue, and it is written once, never updated.
+
+Fields (omit any whose source fact is genuinely absent; never invent one):
+
+```
+### AEG provenance — task <n> (tranche <name>)
+- Issue:        #N  (closed by merge)
+- Tier:         0|1|3
+- Brief:        in this PR body (the frozen intent)
+- Project(s):   <from the brief's Project: field, resolved via projects.md>
+- Model/agent:  <from the brief's `For:` line — AEG forbids commit-trailer attribution, so this is the source>
+- Code review:  APPROVE | REQUEST CHANGES→resolved   (PR review by <reviewer>)
+- Security:     PASS | FAIL→resolved                 (PR review by <reviewer>)
+- Ticket:       <from the brief's Ticket: field, if any — reference only>
+- Merged:       <merge commit SHA> at <merge timestamp>   (forge facts)
+```
+
+If a *required* source fact is missing (e.g. no recorded review), that is a close-out finding — record it under DANGLING, don't fabricate the field.
+
+## What you flag — but do NOT perform
+
+- **Orphaned branches.** A `task/<tranche>/<n>` branch with no PR, or a stale branch whose PR merged but the branch lingers → list it as a cleanup candidate. (An orphaned in-flight task — branch, no PR, gone stale — is returned to `todo` by a human deleting the branch; you flag it, you don't delete it.)
+- **Local worktree removal.** The worktree lives on the operator's machine; you (often running in the cloud) cannot reach the local filesystem. List the `git worktree remove` candidate for the human.
+
+You flag these in your report because performing them is either outside your reach or a human's call.
+
+## What you do NOT do
+
+- **Write task status.** Status is derived from the forge. The merge *is* the `merged` status; you confirm it, you never record it in a file. (Per-project state, now a pinned Issue, is project *operational* documentation — non-derivable facts only — a different thing.)
+- **Author provenance facts.** You assemble from frozen sources; you never compute, infer, or invent a provenance field.
+- **Reopen or re-litigate the work.** It merged; close-out is bookkeeping, not a second review.
+- **Merge anything.** Merge already happened; if it didn't, you refuse (entry gate).
+- **Edit the tranche topology file** to add status/PR/dates/provenance. The file is plan topology only — adding execution metadata is the forbidden regression. Provenance goes on the merged PR, never here.
+
+## Output format
+
+```
+CLOSE-OUT: task N (PR #M) — COMPLETE | INCOMPLETE
+
+DONE:
+- Issue #N closed
+- <project> pinned state Issue updated
+- token ledger rows appended (N roles: <list>)
+- provenance block posted to PR #M
+- ...
+
+PROVENANCE: posted | INCOMPLETE (missing: <fields whose source fact was absent>)
+
+DANGLING (needs a human):
+- worktree .worktrees/task/<it>/<n> — remove with `git worktree remove …`
+- orphaned branch task/<it>/<x> (PR never opened) — delete?
+
+VERDICT: clean | N items need attention (listed above)
+```
+
+If required docs didn't move, or a required provenance source fact is absent, the close-out is **INCOMPLETE** — say so plainly; don't paper over it.
+
+## Where you sit in the process
+
+You are the last step of the flow (`process.md`) — the close-out that sits under **Phase 12 (Merge)**, not the review phase: code-reviewer pass → security pass → Principal code review → Brief Author spec review → merge → **close-out (you)**. After you, the task is done, durable, and provenanced.
+
+## Turn-end: record the ledger rows for every role that turned on this task
+
+You are the **sole writer** of `aeg-root/tranches/<name>.tokens.md` for a task branch — no other role appends its own row. **In practice there is usually no such file:** it is deleted for every active tranche and CI blocks creating a new one (item 6 above), so for those tasks the rows live in the forge — the Developer's PR-body "Token report" entries and the chat roles' `Tokens: …` verdict lines — and are re-derived on read. Do not create the file to have somewhere to write. Only when a legacy file survives do you append to it; then append one row per role-turn you collected in item 7 above (`Phase | Role | Agent/Model | Tokens in | Tokens out | Cost | Date`), then append your own turn's row last (`Phase: <task-id>: archive`, `Role: Archivist`). When you run as automation in Claude Code, you are a **terminal role** for your own row: run `bun packages/aeg-core/bin/report-tokens.ts --phase "<task-id>: archive" --role Archivist` against your own session and fill its numeric cells with the exact values it emits — not `/cost`, which an automated session cannot invoke itself. Every chat-role row you record (Reviewer, Security, Planner) carries whatever the role reported — `—` where the report itself had no numeric figure; you never estimate or fill in a chat role's cell yourself. Drift cron: as part of the close-out checks, flag any merged task in this tranche that has **no Developer row** for `<task-id>: develop` (the role obligation was missed), and any inline `## Token ledger` section that violates the append-only rule (an existing row was edited rather than a new one appended). The ledger is append-only.