V2 architecture baseline: next-generation from collapsed, git substrate, no JSONB during generation

Context

The pre-grilling V2 spec modeled V2 as a simplification of 'V1,' conflating two distinct things: V1-original (42 agents, 12 HITL checkpoints, 5 phase orchestrators — described in docs/pipeline/overview.md) and the course-generation support manifest (8 agents in library-course-generation.yaml). That support manifest had already eliminated V1-original's complexity; V2 didn't need to re-do that work.

Three forces drive this ADR:

Force A · The pre-grilling V2 spec mistook the baseline

It treated V1-original's complexity as if it were the migration source. The grilling re-baselined V2 against collapsed, which has very different implications — collapsed has 5 LLM agents (including an Evaluator), 3 KB agents, and the locked milestone architecture.

Force B · The JSONB substrate breaks continuously

Operator-confirmed: workflow_node_states.output (JSONB) + spec_files.status + per-table state coordination breaks too often. Symptoms include schema drift between read sites, opaque diffs in audit logs, RLS complexity from SECURITY DEFINER helpers, and debugging difficulty. The filesystem substrate replaces all this with markdown files that diff in git log, render in cat, and have no schema-drift surface beyond the contract linter.

Force C · The locked milestone architecture supplies the shape

08-milestone-architecture.md already defines the milestones, gates, state machine, and 3-zone UI. V2's job is to implement that shape on a new substrate — not to redesign it.

Decision

V2 is architected as the next-generation migration from collapsed, with three substrate-level commitments (D1–D5):

• D1 — V2 baselines on collapsed, not V1-original. Collapsed's 8-agent contract is what V2 reimplements on the filesystem substrate.
• D2 — Git-as-substrate. Each per-course workspace IS a git repository. Every meaningful action is a commit. Branching is used for edit-proposals only (per ADR 0008).
• D3 — Workspace location + identity: Supabase Storage, per-course repos. Per-teacher dashboard lists all the teacher's course repos.
• D4 — Per-course repo (not per-teacher monorepo, not per-school). Each course = its own git history. KB repo is separate (per-teacher) per ADR 0006.
• D5 — Pure-workspace projection. During M1–M4, all state lives in workspace markdown + git history. Supabase tables only hold published content.

Why this choice, not the alternatives

• Baseline on collapsed (not V1-original): V1-original is already migrated; re-eliminating its complexity would be wasted work.
• Git, not raw filesystem: the LLM-judge mechanism needs diffs; git provides them for free. Audit trail, branching for proposals, cheap revert, mechanical conflict detection — all free.
• Supabase Storage, not hosted git or local-disk: already in stack, RLS works at bucket-level, no per-teacher GitHub accounts.
• Per-course repo, not monorepo: smaller blast radius, clean delete/archive/branch operations, bounded repo growth.
• Pure-workspace projection: the whole point of escaping JSONB. Half-measures don't solve the substrate problem.

Consequences

Migration / execution

1. 1.V2 lives on claude/coe-filesystem-backbone-TYD7T (long-lived branch; PR guard from #2039 blocks merge).
2. 2.Cutover at V2-P6 is a default-branch swap, not a merge.
3. 3.Implementation waves R1 → R7 per the design spec §10.

Open questions

• Worker queue medium (Inngest / Vercel Background Functions / Supabase Edge / pg-boss) — deferred to R6.
• Per-workspace prompt-override semantics (file-presence vs layered) — deferred to R1 first override case.
• AD_HOC card lifecycle (which workspace files spawn review cards) — deferred to R4.