@attalabs/vinaya 0.4.2 → 0.4.4

package/studio-standalone/.worktrees/fix/check-lifecycle-phase/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/check-lifecycle-phase/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/check-lifecycle-phase/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/check-lifecycle-phase/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/check-lifecycle-phase/apps/vinaya/cli/tests/fixtures/checks/vinaya.config.json

@@ -0,0 +1,9 @@
+{
+  "checks": {
+    "fixture-check": {
+      "run": "./tests/fixtures/checks/passing-check.ts",
+      "scope": "diff",
+      "include": ["**/*"]
+    }
+  }
+}

package/studio-standalone/.worktrees/fix/check-lifecycle-phase/node_modules/@attalabs/vinaya/tests/fixtures/checks/vinaya.config.json

@@ -0,0 +1,9 @@
+{
+  "checks": {
+    "fixture-check": {
+      "run": "./tests/fixtures/checks/passing-check.ts",
+      "scope": "diff",
+      "include": ["**/*"]
+    }
+  }
+}

package/studio-standalone/.worktrees/fix/check-lifecycle-phase/vinaya.config.json

@@ -0,0 +1,36 @@
+{
+  "checks": {
+    "attalabs/vocabulary-citation": {
+      "run": "./scripts/vinaya-checks/vocabulary-citation.ts",
+      "scope": "full",
+      "timeoutMs": 30000
+    },
+    "attalabs/task-anchor": {
+      "run": "./scripts/vinaya-checks/task-anchor.ts",
+      "scope": "full",
+      "timeoutMs": 30000
+    }
+  },
+  "briefSchema": {
+    "pr": {
+      "sections": [
+        { "builtin": "tier" },
+        { "builtin": "testPlan" },
+        { "builtin": "testPlanExclusivity" },
+        { "builtin": "principalPlaceholder" },
+        { "builtin": "surfaceMap" },
+        { "builtin": "docUpdateList" },
+        { "builtin": "worktreeStep0" },
+        { "builtin": "stopConditions" },
+        { "builtin": "autonomyClause" },
+        { "builtin": "project" },
+        { "builtin": "for" },
+        { "builtin": "closesN" },
+        { "builtin": "premiseCoverage" }
+      ]
+    },
+    "issue": {
+      "sections": [{ "builtin": "issueRationale" }]
+    }
+  }
+}

package/studio-standalone/.worktrees/fix/studio-standalone-repo-root/.vinaya/projects.md

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