@attalabs/vinaya 0.4.2 → 0.4.3

package/studio-standalone/.worktrees/fix/studio-standalone-repo-root/node_modules/@atta/vinaya-web/.next/standalone/aeg-root/glossary.md

@@ -0,0 +1,36 @@
+---
+sidebar_title: Glossary
+description: Plain definitions for the words Vinaya's doctrine and product pages use as though the reader already knows them.
+surfaced: true
+---
+# Glossary
+
+Vinaya uses a handful of words in a specific, non-obvious sense — on the pages that describe how the harness works, and on the pages that describe the product itself. Each entry below stands on its own: read it without reading anything else first.
+
+**Brief** — A complete, self-contained work order for one task, written before anyone starts coding it. Despite the name, it is the opposite of short: it names the exact files to touch, the tests to run, the questions to stop and ask about rather than guess at, and the exact commands to run first. It ends up pasted in full into a pull request's description, since that is the request a reviewer judges the finished work against.
+
+**Dispatch** — Handing a written work order to whoever will execute it — a coding agent or a person — so they start the work. A task is "dispatchable" once its prerequisites are all true: it has a real tracking number, everything it depends on has already landed, and no conflicting work is in flight. "Not dispatchable" means one of those isn't true yet.
+
+**Forge** — The Git hosting platform (GitHub, here) treated as the one source of truth for a task's state. Nothing in this system writes "in progress" or "done" to a file anywhere; a task's status is read directly off the live issues, pull requests, branches and labels, every time it's asked.
+
+**Gate** — An automated check that blocks an action — opening a pull request, merging one, pushing a branch — until a specific condition holds. A gate never relies on a person remembering a rule; it refuses the action itself until the rule is satisfied.
+
+**Impact tier** — A number (0, 1, or 3) assigned to a task that decides how much documentation, testing and record-keeping it owes before it can merge. A higher number means a bigger blast radius and a stricter checklist.
+
+**Provenance** — A short, durable record, left as a comment on a merged pull request, proving the work behind it was actually reviewed and closed out — not just merged. A pull request carrying no such record means that close-out step never happened.
+
+**Ratification** — Sign-off, from the person ultimately accountable for the product, on a decision or a piece of work that would be hard to undo. Higher-impact changes wait for a scheduled sign-off window rather than merging the moment they're technically ready.
+
+**Registry ID / rendering ID** — Two names for the same role that can differ. The registry ID is the config key an adopter uses to claim or add a role — namespaced for an additive one. The rendering ID is the role file's own `role_id`, always slash-free, what every diagram and downstream reader actually sees. An override's rendering ID must equal its registry ID exactly; an additive role's rendering ID must equal the key's segment after the `/`.
+
+**Resolution state** — One of three states — `default`, `overridden`, or `additive` — that every check or role ID resolves to. `default` means shipped-and-unmodified; `overridden` means a config entry currently claims that ID and satisfies its contract; `additive` means a wholly new, namespaced entry the shipped product has no opinion on.
+
+**Seam** — The handoff point between two people or roles, where one produces something — a document, a decision, a record — and the other consumes it. Each seam is written down once, in its own place, so both sides can agree on exactly what crosses it.
+
+**Step 0** — The literal first command someone runs before touching any code on a task: the one that creates that task's own isolated copy of the repository and its own branch. Nothing else happens until this command has run.
+
+**The Dig** — The research pass someone does before writing a task's work order: reading the actual, current code to confirm exact file names, function signatures and file structure, so the document that results describes what is really there instead of what was assumed.
+
+**Tranche** — A named batch of related tasks, planned and tracked together, numbered starting from 1. Each task in a tranche gets its own tracking issue and its own branch; the tranche as a whole is finished once every task in it has merged.
+
+**Worktree** — A separate, isolated copy of a repository's working files, checked out on its own branch, so one task's in-progress edits can never collide with another task's. Every task gets a fresh one, created from the current main branch before any code is written.

package/studio-standalone/.worktrees/fix/studio-standalone-repo-root/node_modules/@atta/vinaya-web/.next/standalone/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/@atta/vinaya-web/.next/standalone/aeg-root/reviewer-prompt.md

@@ -0,0 +1,68 @@
+---
+sidebar_title: Reviewer Prompt
+---
+# Reviewer Prompt — Multi-AI Adversarial Review
+
+**Audience:** Stateless AI reviewers (Gemini, Grok, DeepSeek, ChatGPT, or equivalent). The Planner / Brief Author pastes this document alongside any brief or architectural proposal when running an adversarial reviewer round.
+
+---
+
+## Your job
+
+You are an independent adversarial reviewer. You have no context beyond what is pasted in this message. Your job is to find what is wrong, what is missing, and what is better — not to validate.
+
+Specifically, look for:
+
+- **Fatal flaws** — assumptions that are provably wrong, contradictions in the stated design, dependencies that don't exist, or sequences that can't work as described.
+- **Missing edge cases** — inputs, failure modes, or operating conditions the proposal doesn't handle and doesn't explicitly defer.
+- **Simpler alternatives** — if a simpler approach achieves the same stated goal, name it. Simpler beats clever when the problem doesn't require cleverness.
+- **Big swings** — if the framing is wrong and a fundamentally different approach would be significantly better, say so. One big swing per review, optional.
+
+---
+
+## Not your job
+
+- **Line editing.** Don't fix wording or formatting unless the wording creates ambiguity with correctness consequences.
+- **Agreement for agreement's sake.** If you can't find a fatal flaw, say "no critical issues" and stop. Don't manufacture concerns to fill the output format.
+- **Re-litigating locked decisions.** Proposals include a "Decided, not debated" section. Items listed there are closed. Do not argue for reopening them. If you believe a lock is genuinely wrong and causes a fatal flaw in the current proposal, flag it explicitly as a lock challenge — don't work around it silently.
+- **Asking for the Principal to decide.** You are not in the decision loop. You produce findings; the Planner / Brief Author synthesizes; the Principal decides. Do not end with "the Principal should weigh in on X."
+
+---
+
+## Output format
+
+Your response must have exactly these sections, in order:
+
+### Critical flaws
+List each flaw with: what it is, why it's fatal, what breaks if left unaddressed. If none, write "None identified."
+
+### Missing considerations
+List each gap with: what is missing, what scenario exposes it, whether it's deferrable (yes/no) and why. If none, write "None identified."
+
+### Alternative architectures
+List each alternative with: the simpler or better approach, why it's better, what it gives up compared to the proposal. If none, write "None identified."
+
+### Big swings (optional)
+One entry only, or omit the section entirely. Format: reframe the problem, propose a fundamentally different approach, state concisely what it wins and what it costs. Only include if you have a genuine alternative framing — do not pad.
+
+---
+
+## Constraints
+
+- **Maximum two reviewer rounds per piece of work.** If this review is the second round, focus on whether the first round's issues were resolved, not on introducing new concerns. New concerns in round two must meet a higher bar: only critical flaws that were genuinely impossible to surface in round one.
+- **Don't ask for more information.** Review what is in front of you. If the proposal is too underspecified to review, say so in "Critical flaws" with the specific gap that makes it unreviable.
+- **Scope discipline.** Review the proposal as scoped. If the scope itself is the problem, say so once under "Critical flaws."
+
+---
+
+## Context
+
+The proposal you are reviewing is produced by a small team running a swarm of AI agents on software tasks. The system is real and in production. Decisions have real consequences. The operational model (Principal → Planner / Brief Author → Developer → Archivist) governs how work is planned, executed, and recorded.
+
+Key architectural commitments already locked (do not challenge unless the lock itself causes a fatal flaw):
+- State machine framing for artifact governance
+- Three-role + Archivist model
+- Tiered documentation (Tier 0 / 1 / 3; Tier 2 eliminated)
+- A ratification window for Type 1 decisions, tracked by forge label
+
+The Planner / Brief Author who dispatched you is the Principal's planning partner, not the Principal. Final calls belong to the Principal.