AGENTS.md

1# `apps/daemon/src/critique/` (Critique Theater, daemon side)
2 
3Module map agents enter when they need to change anything in the critique
4pipeline. The user-facing feature name is **Design Jury**; the directory
5keeps the **Critique Theater** internal name so the product label can move
6without churning code paths.
7 
8## Layout
9 
10| File | Responsibility |
11|---|---|
12| `config.ts` | `CritiqueConfig` defaults + `OD_CRITIQUE_*` env-var parsing. The single source of truth for thresholds, weights, max-rounds, timeouts. |
13| `orchestrator.ts` | The state machine. Spawns a CLI session, feeds the panelist prompts in order, awaits each round's SHIP / round_end, and decides whether to continue or terminate. |
14| `parser.ts` + `parsers/v1.ts` | Streaming parser that ingests the agent's stdout and yields `PanelEvent`s. Owns the `<CRITIQUE_RUN>`, `<PANELIST>`, `<SHIP>` envelope. |
15| `errors.ts` | Typed parser failures: `MalformedBlockError`, `OversizeBlockError`, `MissingArtifactError`. Each maps to a `DegradedReason` so the wire-level `critique.degraded` event carries the right tag. |
16| `persistence.ts` | SQLite writes for run rows and per-round summaries (`critique_runs`, `critique_rounds`). |
17| `artifact-writer.ts` | Disk persistence for the SHIP artifact body. Owns the byte-budget guard (`ArtifactTooLargeError`) and the `O_NOFOLLOW` path-traversal protections. |
18| `artifact-handler.ts` | HTTP read path: `GET /api/projects/:id/critique/:runId/artifact`. |
19| `interrupt-handler.ts` | Resolves the kill request from `POST /api/projects/:id/critique/:runId/interrupt`. |
20| `adapter-degraded.ts` | In-memory degraded-adapter registry with 24h TTL. The orchestrator + Settings UI consult `isDegraded(adapterId)` before routing a run to it. |
21| `conformance.ts` | Conformance harness entry point. The prerelease cycle calls `runAdapterConformance` per adapter × per brief template and tallies `shipped / degraded / failed`. |
22| `conformance-history.ts` | Reads and summarizes persisted conformance history used by rollout decisions. |
23| `ratchet.ts` + `rollout.ts` | Evaluate conformance evidence and resolve the current feature rollout tier. |
24| `run-registry.ts` | Project-keyed in-process run registry used by interrupt handling. |
25| `scoreboard.ts` | Aggregates per-adapter conformance outcomes for the status surfaces. |
26| `spawn-inputs.ts` | Builds the isolated prompt and filesystem inputs passed to critique subprocesses. |
27| `transcript.ts` | Persists and reads replayable critique event transcripts. |
28| `__fixtures__/v1/` | Canonical transcripts the parser tests + conformance harness consume (happy-3-rounds, malformed-unbalanced, missing-artifact, etc.). |
29| `__fixtures__/adapters/` | Synthetic adapter stubs that emit the v1 fixtures. The conformance harness wraps them in `AsyncIterable<string>` so the parser path is exercised end-to-end without a real model. |
30 
31## Invariants
32 
33- **Parser yields one `PanelEvent` at a time** via async generator. The
34  orchestrator drives the loop; nothing in this directory collects events
35  into an array eagerly.
36- **Terminal phases (`shipped`, `degraded`, `interrupted`, `failed`) are
37  emitted exactly once** per run. The reducer treats them as sticky;
38  duplicate ship events trip `duplicate_ship` in `parser_warning`.
39- **Artifact bytes never travel on the wire.** The SHIP event carries an
40  `artifactRef: { projectId, artifactId }` only; the byte body is written
41  by `artifact-writer.ts` and fetched via the HTTP route.
42- **Round bookkeeping is keyed by round number**, not by "always the
43  last." A stray late panelist event from round 1 must NOT corrupt
44  round 2's bucket. See `withRound` in the web reducer for the parallel.
45- **No `apps/daemon/src/agents/registry.ts`.** The plan refers to that
46  path historically; the actual adapter registry is `runtimes/registry.ts`
47  in this repo. Phase 10 routing extensions land here in
48  `adapter-degraded.ts` instead.
49- **Designer weight is frozen at 0.0 until v2 cast config lands.**
50  `config.ts` exposes the panel weights as `CritiqueConfig.weights`
51  but every production deployment uses the v1 distribution
52  (designer 0 / critic 0.4 / brand 0.2 / a11y 0.2 / copy 0.2). The
53  v2 work is cross-package: the daemon adds per-skill weight
54  overrides driven off `od.critique.cast` in `SKILL.md` frontmatter
55  (this directory) and the web Settings surface adds a per-project
56  weight editor (`apps/web/src/components/SettingsDialog.tsx`). Treat the v1
57  weights as a wire-shape invariant rather than a tuning knob;
58  changing them mid-v1 will break the `composite` numbers persisted
59  in `critique_runs`.
60 
61## When you change anything here
62 
631. The contracts in `packages/contracts/src/critique.ts` are the single
64   source of truth for `PanelEvent`, `DegradedReason`, `FailedCause`,
65   `ParserWarningKind`. Update them before changing this directory.
662. The parser is the natural place to enforce schema strictness; do not
67   loosen it under pressure. The web `sseToPanelEvent` already runs a
68   defence-in-depth variant validator.
693. Add a v1 fixture under `__fixtures__/v1/` for every new failure
70   shape, and a corresponding conformance test case.
714. Bump `CRITIQUE_PROTOCOL_VERSION` in the contracts when the wire
72   shape changes. Adapter conformance auto-marks `degraded` on
73   protocol-version mismatch, so this is load-bearing.
74 
75## Related
76 
77- Spec: `specs/current/critique-theater.md`
78- Plan: `specs/current/critique-theater-plan.md`
79- User docs: `docs/critique-theater.md`
80- Web counterpart: `apps/web/src/components/Theater/AGENTS.md`
81