@attalabs/vinaya 0.4.2 → 0.4.4

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

@@ -0,0 +1,35 @@
+# Tranche: herald-agents-v2 — June–July 2026
+Lifecycle: complete
+
+Goal: Extract forensic-hiring-auditor intelligence into `packages/agents/forensic-hiring-auditor/`
+(D-046 first execution), make Herald a thin consumer, overhaul Bulk Audit UX, improve report
+quality, expose Herald MCP, close housekeeping debt from two completed tranches.
+
+Repo: daniboomerang/attalabs · Team Leader: Claude (web)
+
+## Tasks (topology)
+
+| # | Task                                                                                                                                | Issue | Project(s)          | Depends-on | Conflicts-with           |
+|---|-------------------------------------------------------------------------------------------------------------------------------------|-------|---------------------|------------|--------------------------|
+| 1 | Housekeeping — Archivists (herald-onto-engine + aeg-ui-v1) + herald backlog fix + herald-ai/aeg-project state/now rewrite           | #167  | herald, aeg         | —          | —                        |
+| 2 | Agent migration — `packages/agents/forensic-hiring-auditor/` (YAML + GitHub tool + MatchReport schema + NO-FIT gate) + Herald thin consumer + Bulk Audit stays green | #168  | herald, engine, aeg-core | #167  | —                        |
+| 3 | Herald MCP — `herald__audit` at `herald.attalabs.dev/api/mcp`                                                                       | #169  | herald              | #168       | —                        |
+| 4 | Bulk Audit UX overhaul — matrix result rendering, report cards, cell status, overall flow                                           | #170  | herald              | #168       | #181 (vada-production-v1/6) |
+| 5 | Report quality — research existing forensic hiring frameworks + vendor-diverse LLM review + real improvement to agent YAML/prompt with fixture-based before/after evidence | #171  | herald, aeg-core    | #168       | —                        |
+| 6 | Abuse cap — per-owner per-day rate limit on public profile audits (D-033 follow-up)                                                 | #172  | herald              | #168       | —                        |
+| 7 | Deploy verification — `herald.attalabs.dev` Phase 2 flows (avatar, CV upload, bio save, onboarding, Bulk Audit with real BYOK)      | #173  | herald              | #168       | —                        |
+| 8 | Owner `/ui` + `/settings` relocated under `/[username]` (owner-gated, build-time library per D-035) + topbar Palette/Settings icon buttons via `extraActions` + Bulk Audit excluded from profile layout. Supersedes D-036 route/nav (→ D-060). | #210 | herald | — | — |
+
+## Backlog (this tranche, not yet dispatched)
+
+- Per-audit (one-off) vendor + model override on Bulk Audit — deferred post-V1, not in scope.
+- Herald Phase 4 (recruiter as distinct B2B surface) — future, not in scope.
+
+## Cross-tranche dependencies
+
+- Task 1 (#167) must merge before herald-agents-v2 task 2 (#168) can dispatch AND before
+  vada-production-v1 task 1 (#175) can dispatch (Planner readiness gate on both).
+- Task 4 (#170) conflicts-with vada-production-v1/6 (#181) (SmartTextInput extraction). Serialize:
+  #181 merges first (extract to @atta/ui), then #170 consumes it.
+- Task 2 (#168) must merge before vada-production-v1 task 1 (#175) (Vāda YAML migration follows the
+  package structure established here).

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

@@ -0,0 +1,11 @@
+# Token ledger — herald-agents-v2
+
+Append-only. One row per phase/role turn. See `tranches/README.md` §12.
+
+| Phase | Role | Agent/Model | Tokens in | Tokens out | Cost | Date |
+|-------|------|-------------|-----------|------------|------|------|
+| task-5: archive | Archivist | claude-sonnet-4-6 | — | — | — | 2026-06-23 |
+| task-8: planning | Planner | claude-opus-4-7 | — | — | — | 2026-06-25 |
+| task-8: developer | Developer | claude-opus-4-7 | — | — | — | 2026-06-25 |
+| task-8: archive | Archivist | claude-opus-4-7 | — | — | — | 2026-06-25 |
+| tranche-close | Tranche Archivist | claude-sonnet-4-6 | — | — | — | 2026-06-30 |

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

@@ -0,0 +1,99 @@
+# Tranche: herald-onto-engine — June 2026
+
+Lifecycle: complete
+
+**Goal (execution, not product-why):** onboard **Herald onto `@atta/engine`** — express Herald's auditor as a **flow YAML the engine runs** (exactly as Vāda's agents are YAMLs the engine runs), then build **Bulk Audit** (N CVs × M JDs → one forensic report per pair) on top, and finally make the auditor a **tool-using YAML agent** (it gathers its own GitHub evidence) — which requires first **building custom client-side tool execution into the shared engine.** The durable, multi-project win is Herald stopping being special: one engine runs every product's agents, defined declaratively in YAML — including their tools.
+
+**Center of gravity:** Herald-as-an-engine-consumer, plus one genuine **shared-engine capability** (custom tool execution, task 7a). `@atta/engine` is the shared substrate; Vāda is the first consumer, Herald becomes the second. The migration (task 1) consumes the engine unchanged; the tool work (7a) **extends** it (Vāda in blast radius, additive). Bulk Audit and the tool-using auditor are downstream of the migration.
+
+> **Re-scope note (June 12 — Brief Author dig, severity:strategy):** the original plan had a task **3a "add multi-vendor structured output to the engine."** The task-1 briefing dig **overturned its premise** and 3a was **dropped (#87 closed not-planned).** Findings: (1) the engine already runs any vendor in a YAML (text) today; (2) the only gap was the narrow `outputSchema` typed-object path on non-Anthropic vendors; (3) **Herald doesn't need it** — its auditor prompt already requests JSON-as-text and parses it, like Vāda. So the *migration* (task 1) is purely Herald-side, zero engine change, any vendor. Structured-output-on-other-vendors is an optional *future* engine enhancement, backlogged, not here.
+
+> **Task 7 split into 7a + 7b (June 13 — Principal decision, readiness-gate catch):** the original task 7 ("auditor gets a GitHub tool") assumed the engine could already run **custom client-side tools.** The planning dig (`node-executor.ts` + `graph-state.ts`) **proved it cannot** — the adapter supports only **provider-native server tools** (the classifier *allocates* tools; the vendor executes them; there is no loop where the engine pauses, runs an app-supplied function, and feeds the result back). So "give Herald a tool" is two things: **7a — build custom client-side tool execution into `@atta/adapter-langgraph`** (shared engine, **Vāda in blast radius**, additive/opt-in), and **7b — Herald defines its GitHub tool in the YAML** (depends on 7a). Split by verification coupling: 7a is provable with a trivial throwaway tool; 7b proves it in production with the real GitHub tool. This was the planner's readiness gate working — it refused to plan 7 as a "small Herald task" once the dig showed it required shared-engine work.
+
+**Repo:** attalabs (`daniboomerang/atta.ai`)   ·   **Team Leader:** Dani
+
+> **Status is derived from the forge, not stored here.** This file is topology + the planner's durable rationale only. No PR numbers, no dates, no status. Issues are cut: task → Issue mapping below is fixed; live status is `gh pr list` / the Issue/PR state, never written here.
+
+> **This tranche is a working demonstration of the model catching its own errors.** It was the first deliberate planning prototype (F1–F6, global D-042); then the **Brief Author dig caught a mis-scoped task** (3a dropped, June 12); then the **planner readiness gate caught a hidden shared-engine dependency** (task 7 split into 7a/7b, June 13). Twice, the dig overturned a premise before a wrong brief shipped. The full Planner's rationale lives in each task's Issue body; the per-task summaries below are for topology reading.
+
+---
+
+## Tasks (topology)
+
+| # | Task | Issue | Project(s) | Depends-on | Conflicts-with |
+|---|------|-------|-----------|------------|----------------|
+| 1 | Herald auditor → `solo` YAML run by `@atta/engine` | #88 | herald, engine | — | — |
+| 2 | Endpoint unification → one `/api/audit` cell runner | #89 | herald | 1 | 4, 5 |
+| 3b | Herald multi-vendor BYOK UI + audit model selector | #90 | herald | 1 | — |
+| 4 | N×M matrix UI (Bulk Audit accepts N CVs × M JDs, renders per-pair grid) | #91 | herald | 2 | 2, 5 |
+| 5 | Polymorphic inputs (JD link/text; CV text/.md/.pdf/published profile) | #92 | herald | 2, 4 | 2, 4 |
+| 6 | Per-key rate limit / cap on profile audits (D-033 abuse surface) | #93 | herald | 2 | — |
+| 7a | Custom client-side tool execution in `@atta/engine` (shared) | #102 | engine, vada, herald | — | — |
+| 7b | Herald auditor uses a GitHub tool defined in its YAML | #103 | herald | 1, 7a | — |
+
+*(Task 3a — "multi-vendor structured output in the engine" — removed; #87 closed not-planned. Task 7 split into 7a/7b — see the split note above.)*
+
+**Wave structure (max concurrency, derived from the edges):**
+- **Wave 1 (lead):** **1 (#88)** — Herald auditor onto the engine. Clean single lead; everything Herald-side builds on it. **7a (#102) can also start in wave 1** — it's pure engine work (no `depends-on`), independent of the migration, so it may run in parallel with task 1 from the start. (Sequencing 7a early is attractive: it's the highest-risk/highest-value shared work and unblocks 7b.)
+- **Wave 2 (after 1 merged — parallel):** 2 (#89, endpoint unification) and 3b (#90, BYOK UI + model selector) — different surfaces, no conflict; depend on task 1 only.
+- **Wave 3 (after 2 merged — parallel):** 4 (#91, matrix UI) and 6 (#93, rate limit) — different surfaces (UI vs `/api/audit` middleware).
+- **Wave 4 (after 4 merged):** 5 (#92, polymorphic inputs) — builds on the matrix.
+- **7b (#103)** runs once **both 1 and 7a** are merged — the last Herald-side step (depends-on 1 + 7a). Naturally lands late.
+
+Max concurrency: up to 3 (e.g. task 1 + 7a + an unblocked sibling). The hard serial points are wave 1 (task 1) for the Herald chain and 7a→7b for the tool chain.
+
+**Dispatch order:** 1 (#88) is the Herald wave-1 lead; **7a (#102) is independently dispatchable now** (no deps) and is the long pole for the tool feature, so starting it early is sensible. Assigning an Issue promotes it `backlog → todo`; a Developer then writes the brief just-in-time from its Planner's rationale (per the planner-brief contract), opens `task/herald-onto-engine/<n>`, and opens the PR with the brief in the body.
+
+---
+
+## Task details (Planner's rationale lives in each Issue body — summaries here for topology)
+
+### Task 1 — Herald auditor → `solo` YAML run by `@atta/engine` · Issue #88 · **wave-1 lead**
+**Project(s):** herald, engine · **Depends-on:** — · **Conflicts-with:** —
+
+Migrate Herald's **one auditor LLM call** from bespoke `generateText()` + TS-string prompt + manual parse onto the engine, by expressing the auditor as a **`solo` flow YAML** (`loadFlow` + `compileFlow`), exactly as Vāda runs its agents. **Only the LLM call moves.** `extractSignals()` (the GitHub fetch, `signals.ts`), the SHA-256 cache, and `buildPartialReport()` / the JSON parse **stay as Herald code** — the engine runs agents, not GitHub fetches. **Maximize what lives in the YAML:** the prompt (`SKEPTICAL_AUDITOR_PROMPT` moves *into* the YAML, deleted from `prompts.ts`), the model, and the message/output-instruction all live in `herald-auditor.yaml`; only `MATCH_REPORT_SCHEMA` stays in code as the shared parse contract (interpolated into the YAML prompt as a `{{schema}}` customVar). Vendor-agnostic: the YAML names the model, the engine already runs all 12 vendors as text, Herald's prompt already asks for JSON-as-text and parses it → **no engine change, any vendor.** Engine is *consumed*, not modified (Vāda not touched). **Traps:** don't use `loadYamlFromCatalog` (hardcodes `apps/vada-ai/yamls`) — use `loadFlow(readFileSync(...))`; don't add `outputSchema`/structured (prompt-instructed JSON, like today); keep signals/cache/parse AND the NO-FIT gate as Herald code. High-capability. **Stop-and-escalate `severity:strategy`** if running Herald through the engine requires *changing* `@atta/engine` (real engine gap → Vāda enters blast radius). *Full rationale: Issue #88.*
+
+### Task 2 — Endpoint unification → one `/api/audit` cell runner · Issue #89
+**Project(s):** herald · **Depends-on:** 1 · **Conflicts-with:** 4, 5
+
+Fold `/api/match` + `/api/recruiter/batch` into one `/api/audit` whose unit of work is the engine-backed auditor (from task 1); repoint `BulkAudit`. Separate from task 1 by verification story/failure mode/files; the "don't migrate twice" concern is handled by *ordering* (depends-on 1), not by welding routing into the migration. Mid-to-high. *Full rationale: Issue #89.*
+
+### Task 3b — Herald multi-vendor BYOK UI + audit model selector · Issue #90
+**Project(s):** herald · **Depends-on:** 1 · **Conflicts-with:** —
+
+Herald settings save keys for multiple vendors + a model picker for the audit. (Depends on task 1 only; vendor support is inherent in the engine, so the selector simply offers the vendors the user has keys for.) Reuse `@atta/ui/account` `ProviderKeysSection`; don't rebuild. Respects D-033 (whose key, orthogonal to which vendor). Mid. *Full rationale: Issue #90.*
+
+### Task 4 — N×M matrix UI · Issue #91
+**Project(s):** herald · **Depends-on:** 2 · **Conflicts-with:** 2, 5
+
+The actual "bulk" feature: accept N CVs × M JDs, render a grid of one report per pair through `/api/audit`. The matrix doesn't exist yet (today `/bulk-audit` is single-pair-capable). Real grid state (async per-pair partial/loading/error). Mid-to-high. *Full rationale: Issue #91.*
+
+### Task 5 — Polymorphic inputs · Issue #92
+**Project(s):** herald · **Depends-on:** 2, 4 · **Conflicts-with:** 2, 4
+
+JD as link|text; CV as text|.md|.pdf|published profile, normalized into the audit text, wired into the matrix + endpoint. `.pdf` extraction and link-fetch are the real work. **Trap:** link-fetch is outbound (SSRF/abuse — validate/scope); `.pdf` library choice; profile input resolves through Herald's own data. Mid. *Full rationale: Issue #92.*
+
+### Task 6 — Per-key rate limit / cap on profile audits · Issue #93
+**Project(s):** herald · **Depends-on:** 2 · **Conflicts-with:** —
+
+Close the D-033 hole (strangers spend the owner's key budget). Per-key cap at the `/api/audit` layer (Upstash Redis backbone). **Operational dependency, not a code blocker:** Upstash creds expired — ship with graceful degradation; enforcement needs the creds. Parallelizes with wave 3. Mid. Stop-and-escalate `severity:product` if it needs a D-033 policy change. *Full rationale: Issue #93.*
+
+### Task 7a — Custom client-side tool execution in `@atta/engine` · Issue #102 · **shared engine, Vāda in blast radius**
+**Project(s):** engine, vada, herald · **Depends-on:** — · **Conflicts-with:** —
+
+Build **custom client-side function-tool execution** into the adapter (`@atta/adapter-langgraph`). Today the adapter supports **provider-native server tools only** — the classifier *allocates* tools and the vendor executes them; there is **no loop** where the model emits a `tool_use`, the engine pauses, runs an app-supplied TypeScript function, and feeds the result back (proven by `node-executor.ts` + `graph-state.ts`: `toolUseHistory` is "best-effort — server tools don't emit countable tool_use blocks"). 7a adds: a YAML-declared **custom tool**, a registration surface for app-supplied tool implementations, and the call→tool→call execution loop. **Shared-engine change → Vāda in blast radius → additive/opt-in is mandatory** (an agent with no custom tools behaves byte-identically to today; that's the Vāda-safety guarantee). One verification story: a flow with a trivial custom tool (e.g. `add`) runs the loop and the registered fn executes. **Independently verifiable** with a throwaway tool → clean split from 7b. High. **Stop-and-escalate `severity:strategy`** if the loop can't be made additive (forces a change to the shared call path that alters Vāda) — that's a Type 1 engine-architecture decision for the Principal. *Full rationale: Issue #102.*
+
+### Task 7b — Herald auditor uses a GitHub tool defined in its YAML · Issue #103 · **last (depends on 7a)**
+**Project(s):** herald · **Depends-on:** 1, 7a · **Conflicts-with:** —
+
+Define Herald's **GitHub signal tool in the auditor YAML** and register its implementation, so the agent **gathers its own evidence** instead of Herald pre-fetching it (Principal intent: agents own their tools; apps stop pre-fetching). The YAML agent gains a `tools` entry + a tool-using classifier mode; Herald registers the tool's body via the surface **7a** builds; `extractSignals` is retired as a pre-fetch. **Reuse `signals.ts` as the tool's implementation — don't rewrite the GitHub-walking.** The **NO-FIT gate stays Herald code.** Preserve a timeout/budget (today's 3s → the tool budget); the no-GitHub case must still produce a valid audit. **depends-on 1** (must be a YAML agent first) **and 7a** (the engine must support custom tools first). Herald-only surface (7a carried the engine blast radius). Mid. **Stop-and-escalate** if audit quality drops materially vs. pre-fetch (may keep pre-fetch), or if 7a's tool surface proves insufficient (`severity:strategy` back to 7a). *Full rationale: Issue #103.*
+
+---
+
+## Open questions / notes for dispatch
+
+- **Issues:** #88–#93, #102 (7a), #103 (7b) live (#87/3a closed not-planned). Assigning an Issue is the `backlog → todo` promotion.
+- **One genuine shared-engine change this tranche: 7a** (custom tool execution), Vāda in blast radius, additive/opt-in. Everything else is Herald-side. The *migration* (task 1) consumes the engine unchanged; if task 1 finds a hidden engine gap, that's a `severity:strategy` escalation (not assumed).
+- **The tool chain is 1 → 7a → 7b:** task 1 makes the auditor a YAML agent (signals pre-fetched); 7a gives the engine the ability to run custom tools (shared); 7b moves Herald's signal-gathering into the agent as a YAML-declared tool. End state: maximal "logic in the YAML, not code," with the agent owning its own evidence-gathering.
+- **Structured-output-on-other-vendors** (the old 3a) is backlogged as an optional future engine enhancement, not required by Herald.
+- **This tranche is the model catching its own errors twice:** 3a dropped (Brief Author dig, June 12) and task 7 split into 7a/7b (planner readiness gate, June 13) — both before a wrong brief shipped.

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

@@ -0,0 +1,220 @@
+Lifecycle: complete
+
+# Tranche: vada-agents-v2 — June–July 2026
+
+Goal: Migrate all Vāda YAMLs into `packages/agents/` (following the pattern established by
+herald-agents-v2), make Vāda a thin consumer, fix known bugs, refine Reviewers prompt,
+run the first benchmark, rewrite the homepage, extract SmartTextInput to @atta/ui, and
+build tool/MCP support into the deliberation UI.
+
+Repo: daniboomerang/attalabs · Team Leader: Claude (web)
+
+## Tasks (topology)
+
+| # | Task | Issue | Project(s) | Depends-on | Conflicts-with |
+|---|------|-------|------------|------------|----------------|
+| 1 | Vāda YAML migration + bug fixes — all YAMLs to `packages/agents/`, Vāda thin consumer, fix Reviewers ERROR + Sparring duplicate Critic, update YAML-location refs in vada-state.md + backlog | #TBD | vada, engine, aeg-core | herald-agents-v2/2 | — |
+| 2 | Stale spec cleanup — vada-state.md full rewrite, CLAUDE.md, teams-catalog stale refs, byok refs, backlog non-YAML items | #TBD | vada | 1 | — |
+| 3 | Trust page rewrite — replace browser-only BYOK framing with server-side at-rest model (post D-028/D-029) | #TBD | vada | — | — |
+| 4 | Homepage rewrite — remove engine/YAML/closed-room sections; new structure: what it is → why it works → try it → MCP/developer; remove EcosystemSection (Atta/Vitakka not public); update NegationsSection copy to remove "no tools" hardcoding | #TBD | vada | — | — |
+| 5 | SmartTextInput — extract generic multi-kind input pattern (tabs: paste text / URL / file upload) from `apps/herald-ai/web/src/components/audit/{JdInputControl,CvInputControl}.tsx` into `@atta/ui` as a domain-neutral component; wire into Vāda `/deliberate` input | #TBD | vada, herald | 1 | herald-agents-v2/4 |
+| 6 | Reviewers prompt iteration — B-3b (Reviewer system-prompt) + B-3c (Synthesizer system-prompt); Principal-driven judgment loop: run vada__consult, read responses, judge, tweak, re-run | #TBD | vada | 1 | — |
+| 7 | Agent tools + MCP support — deliberation UI refactor to support tool-equipped YAMLs; context-completeness validation (YAML declares required inputs, UI validates before dispatch); `forensic-hiring-auditor` callable as a tool from a Vāda deliberation agent | #TBD | vada, engine, aeg-core | 1, 5 | — |
+| 8 | First benchmark run — B-4: six conditions per test case (A0, A1, VR-NS, VR-S-same, VR-S-cross); manual judging; per-question-type breakdown; validates the whole tranche's refactor | #TBD | vada | 6 | — |
+
+## Planner's rationale
+
+### Task 1 — Vāda YAML migration + bug fixes
+**Boundary:** Move all 9 Vāda YAMLs from `apps/vada-ai/web/yamls/` into per-agent packages
+under `packages/agents/` (e.g. `packages/agents/vada-reviewers/`, `packages/agents/a0-baseline/`,
+etc.), following the package shape established by herald-agents-v2/2. Rewire Vāda's deliberation
+route to consume from the new packages. Fix the two known bugs IN THE SAME PR since the agent
+will be reading and running every YAML: (a) Reviewers team ERROR (provider keys / SDK routing
+— diagnose and fix); (b) Sparring duplicate Critic message (diagnose and fix). Update YAML-
+location references in `apps/vada-ai/specs/vada-state.md` and `vada-backlog.md` (the subset
+that mentions YAML paths — full spec cleanup is task 2).
+NOT in scope: Vāda homepage (task 4), trust page (task 3), SmartTextInput (task 5),
+deliberation tool support (task 7).
+**Sizing:** Large but bounded. One PR. Single verification story (`vada__deliberate` returns
+a result on the new package). Bounded (new packages + vada route + 2 bug fixes + YAML-path
+refs). Single failure mode (migration breaks deliberation). Passes all four tests.
+**Project(s) + blast radius:** vada (primary consumer, deliberation route rewired), engine
+(in blast radius — re-verify vada deliberation and herald audit both still work after any
+shared package reads change), aeg-core (YAML location changes — verify `parseTranche` and
+`parseLedger` still pass; verify any YAML catalog discovery still works).
+**Dependency rationale:** Depends on herald-agents-v2/2 — the package shape and conventions
+for `packages/agents/<name>/` are established by the Herald migration. Vāda follows that
+pattern, not invents a new one. Cannot start until herald-agents-v2/2 is merged.
+**Traps to avoid:** Follow the EXACT package shape established by `packages/agents/forensic-
+hiring-auditor/` — same directory structure, same export pattern, same `loadFlow` usage.
+Do NOT use `loadYamlFromCatalog` with hardcoded paths. Do NOT change `@atta/engine` or
+`@atta/adapter-langgraph` shared contracts. For the Reviewers ERROR bug: read the actual
+error from production logs or reproduce locally before coding a fix — do not guess.
+**Suggested agent-class:** high — multi-package migration, two bug fixes requiring diagnosis,
+shared blast radius.
+**Stop-and-escalate:** If fixing either bug requires changing `@atta/engine` or
+`@atta/adapter-langgraph` shared contracts, escalate `severity:strategy` — that changes the
+blast radius significantly. If the Reviewers ERROR diagnosis reveals it is a Clerk/BYOK
+issue (not a routing issue), escalate `severity:strategy` before fixing.
+
+---
+
+### Task 2 — Stale spec cleanup
+**Boundary:** Full rewrite of `apps/vada-ai/specs/vada-state.md` (last meaningful update
+May 4-5; does not reflect engine migration, shared keys UI, vendor registry, current routes,
+or current YAML catalog state). Update `apps/vada-ai/CLAUDE.md` (Settings tab still shows
+Teams tab). Update `apps/vada-ai/specs/vada-teams-catalog/` stale files: `02-mcp-tool-
+interface.md` (old `apiKey` body param — route now reads from DB by `clerkId`),
+`04-caller-claude-protocol.md` ("Caller Claude owns synthesis" reversed by D-016).
+Update BYOK references in `vada-byok-principles.md` that still describe the browser-only
+model. Update `vada-backlog.md` non-YAML items (YAML-location refs were updated in task 1).
+NOT in scope: vada-reviewers-spec.md (too large for this task; patch opportunistically when
+touched), vada-product-spec.md + vada-product-recognitions.md (legacy, not in active use).
+**Sizing:** Doc-only. One PR. Bounded (6-7 files). Mid-capability — research required to
+verify current state before rewriting.
+**Project(s) + blast radius:** vada only.
+**Dependency rationale:** Depends on task 1 — the YAML-location migration must land first
+so that vada-state.md can correctly describe where YAMLs now live.
+**Traps to avoid:** Read the current code and routes before rewriting specs — do not write
+specs that describe how things used to work. Use audit mode (current code wins, D-004).
+**Suggested agent-class:** mid — doc rewrite, no architecture.
+**Stop-and-escalate:** If auditing the current code reveals a behavioral gap not captured
+in any spec or decision log, flag it in the PR body as a new issue rather than silently
+patching it into a spec.
+
+---
+
+### Task 3 — Trust page rewrite
+**Boundary:** Rewrite `apps/vada-ai/web/src/app/(main)/trust/` content. Replace the browser-
+only BYOK framing (pre-May 4) with the current server-side at-rest model (AES-256-GCM,
+envelope-encrypted, AAD-bound to clerkId, per apps/vada-ai/docs/vada-decisions-legacy.md D-028 + D-029). Pure
+content rewrite — no route changes, no component architecture changes.
+**Sizing:** Small. One PR. Content only.
+**Project(s) + blast radius:** vada only. No dependencies.
+**Suggested agent-class:** mid — prose rewriting.
+**Stop-and-escalate:** None anticipated.
+
+---
+
+### Task 4 — Homepage rewrite
+**Boundary:** Replace the current homepage sections with a simpler, product-focused structure.
+Remove: `PositioningSection` (YAML/engine explanation), `MechanismSection` (Atta Engine /
+compileFlow diagram), `EcosystemSection` (Atta + Vitakka brands not public yet).
+Replace with: (1) updated hero copy (keep canvas animation, update tagline to be concrete
+about what Vāda does); (2) what it is — simple, no YAML, no engine; (3) why it works —
+the deliberation insight (models disagree when uncertain; disagreement is the signal);
+(4) try it CTA; (5) MCP / developer section (one small section, link to /mcp).
+Update `NegationsSection` copy: remove "no tools / no web access / no integrations"
+hardcoded claims — these are YAML decisions, not Vāda product decisions. Replace with
+honest negations about what Vāda is NOT (not a chatbot, not a workflow, not trying to
+be helpful — trying to be right).
+NOT in scope: route changes, new CMS content, component library changes.
+**Sizing:** UI rewrite. One PR. Bounded to homepage components.
+**Project(s) + blast radius:** vada only. No dependencies.
+**Traps to avoid:** Do NOT add CMS dependencies. Keep the homepage component-local and
+static — no async CMS fetches for the new sections. The `EcosystemSection` CMS fetch
+(Atta/Vitakka branding) is deleted, not replaced.
+**Suggested agent-class:** mid — component rewrite, no architecture.
+**Stop-and-escalate:** None anticipated.
+
+---
+
+### Task 5 — SmartTextInput
+**Boundary:** Extract the generic multi-kind input pattern from Herald's `JdInputControl.tsx`
+and `CvInputControl.tsx` into `@atta/ui` as a domain-neutral `SmartTextInput` (or
+`MultiKindInput`) component. The pattern: tabs to switch input kind (paste text / URL /
+file upload), a textarea or input or file slot per kind, controlled state. Wire the new
+component into Vāda's `/deliberate` page input (question field + optional context). Herald's
+`JdInputControl` and `CvInputControl` should be refactored to consume the shared component.
+NOT in scope: per-audit model override, Herald Bulk Audit UX redesign (herald-agents-v2/4).
+**Sizing:** One PR. Two consumers (Vāda + Herald refactored to use it). Bounded to @atta/ui
++ vada deliberate page + herald audit controls.
+**Project(s) + blast radius:** vada (new deliberation input), herald (JdInputControl +
+CvInputControl refactored), engine (in blast radius — @atta/ui change; verify Vāda still
+deliberates and Herald still audits).
+**Dependency rationale:** Depends on task 1 (Vāda deliberation route must be stable before
+rewiring its input). Conflicts-with herald-agents-v2/4 (both touch Herald's audit input
+components; serialize — this task merges first, then herald-agents-v2/4 consumes the
+extracted component).
+**Traps to avoid:** Keep the component domain-neutral — no CV/JD terminology in `@atta/ui`.
+Labels, placeholders, accepted file types are all props, not hardcoded. Herald passes its
+domain labels; Vāda passes its domain labels.
+**Suggested agent-class:** mid — component extraction, two consumers.
+**Stop-and-escalate:** If extracting the component requires changes to `@atta/ui`'s existing
+Tailwind v4 token system or shadcn component wiring that have a wider blast radius, escalate
+`severity:strategy`.
+
+---
+
+### Task 6 — Reviewers prompt iteration
+**Boundary:** B-3b: run `vada__consult` with `spec_id: "vada-reviewers"`, read 3 reviewer
+responses, judge behavior against the rev 5 spec §4.1.1 criteria, tweak system prompt in
+the YAML, re-run. B-3c: same loop for the synthesizer (rev 5 spec §4.1.2). This is a
+Principal-driven judgment loop — the Developer sets up the tooling and initial test run;
+the Principal evaluates and iterates on the prompts. Deliverable: improved reviewer and
+synthesizer YAMLs in `packages/agents/` with the iteration history documented.
+**Sizing:** Research + prompt iteration. Principal-in-the-loop. One PR.
+**Project(s) + blast radius:** vada only (YAMLs in packages/agents/).
+**Dependency rationale:** Depends on task 1 — the YAMLs must be in their new package home
+before iterating on them.
+**Suggested agent-class:** high — prompt judgment, evaluation, iteration history.
+**Stop-and-escalate:** If the Reviewers ERROR from task 1 is not fully resolved and the
+team still errors during B-3b runs, stop and report — cannot iterate on a broken team.
+
+---
+
+### Task 7 — Agent tools + MCP support
+**Boundary:** Refactor the Vāda deliberation UI (`/deliberate` page) to support tool-equipped
+YAMLs. If a YAML declares `required_inputs` or `custom_tools`, the UI must: (a) show the
+right input fields before dispatch (context-completeness validation — the user must supply
+what the agent needs); (b) pass tool handlers to the adapter for custom tools. Wire up
+`forensic-hiring-auditor` as a callable tool from a Vāda deliberation agent (a new
+demonstration YAML that uses it). This is the realization of the "Vāda agents can use MCP
+tools" vision.
+**Sizing:** Large. One PR. This is the most complex task in the tranche — it touches the
+UI input layer, the adapter wiring, and requires a new demonstration YAML.
+**Project(s) + blast radius:** vada (deliberation UI + new YAML), engine (in blast radius —
+the tool dispatch path goes through the adapter), aeg-core (if YAML schema changes for
+`required_inputs` — assess).
+**Dependency rationale:** Depends on task 1 (Vāda on new package structure) and task 5
+(SmartTextInput must exist for the new input fields). Serialized last because it is the
+most ambitious task and benefits from everything else landing first.
+**Traps to avoid:** Do NOT require the YAML author to know the UI implementation — the YAML
+declares `required_inputs` (declarative); the UI reads them and renders the right fields.
+The coupling is YAML → UI (one direction). Do NOT hardcode Herald as the only tool — the
+architecture must support any registered tool.
+**Suggested agent-class:** high — architectural judgment, multi-layer change, new YAML design.
+**Stop-and-escalate:** If making the UI context-completeness validation generic requires
+a new YAML schema field not currently in `@atta/engine`'s flow-schema, escalate
+`severity:strategy` — that is a shared-engine change with Vāda + Herald blast radius.
+
+---
+
+### Task 8 — First benchmark run
+**Boundary:** B-4: six conditions per test case — A0 baseline, A1 baseline, VR-NS (Vāda
+Reviewers no synthesis), VR-S-same (synthesis, same-vendor), VR-S-cross (synthesis, cross-
+vendor), MW-where-available (multi-round where available). Manual judging by Claude in fresh
+context; Dani final arbiter. Per-question-type breakdown required. Documents whether the
+tranche's refactor (YAML migration + bug fixes + prompt iteration) improved output quality.
+This is the validation layer for the whole tranche.
+**Sizing:** Research + benchmark execution. One PR (results doc). Principal-in-the-loop.
+**Project(s) + blast radius:** vada only.
+**Dependency rationale:** Depends on task 6 (prompt iteration must complete first — benchmarking
+against an un-iterated prompt gives no meaningful signal about whether the tranche improved
+quality).
+**Suggested agent-class:** high — judgment, synthesis, multi-model evaluation.
+**Stop-and-escalate:** If the OpenAI + xAI keys are not yet added to Vercel (pending manual op in `aeg-project/state.md` or the per-product `apps/vada-ai/aeg-project/state.md`), the cross-vendor benchmark conditions cannot run. Stop and flag — the Principal must add the keys before dispatch.
+
+## Backlog (this tranche, not yet dispatched)
+
+- vada-reviewers-spec.md §8 patch (phantom consensus not in locked decisions) — patch
+  opportunistically if touched, otherwise defer.
+- Fate of experimental YAMLs (crucible, sparring, war-room) — decide after benchmark data.
+- Hosted MCP hardening (E8-E12) — deferred, post-benchmark.
+
+## Cross-tranche dependencies
+
+- Task 1 here depends on herald-agents-v2/2 (package structure established first).
+- Task 5 here conflicts-with herald-agents-v2/4. Serialize: vada-agents-v2/5 merges first,
+  then herald-agents-v2/4 consumes the extracted @atta/ui component.
+- Tasks 3 and 4 have no dependencies — can run from day 1 in parallel with everything.

package/studio-standalone/.worktrees/fix/studio-standalone-repo-root/apps/vinaya/web/.next/standalone/apps/vinaya/cli/aeg-root/contracts/archivist-tranche-archivist.md

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