opencastle 0.1.0

package/src/orchestrator/customizations/DISPUTES.md

@@ -0,0 +1,162 @@
+````markdown
+# Dispute Records
+
+Structured escalation records created when agents exhaust all automated resolution paths. Unlike the Dead Letter Queue (simple failure log), disputes are **formal action items for humans** — they package conflicting perspectives, prior attempts, and resolution options so a human can make an informed decision.
+
+> **Review this file at the start of each session.** Pending disputes may block downstream work and need human input before proceeding.
+
+---
+
+## When to Create a Dispute
+
+Create a dispute record when **any** of these occur:
+
+| Trigger | Typical Path |
+|---------|-------------|
+| Panel review BLOCKs 3 times | Fast review 3x FAIL → Panel → Panel 3x BLOCK → **Dispute** |
+| Agent and reviewer fundamentally disagree on approach | Agent retries with reviewer feedback but keeps failing because the feedback conflicts with other constraints → **Dispute** |
+| Conflicting acceptance criteria | Reviewer flags an issue, but fixing it would violate another acceptance criterion → **Dispute** |
+| Architectural ambiguity | Multiple valid approaches exist, automated agents can't converge → **Dispute** |
+| External dependency blocks resolution | Fix requires upstream library change, API access, or infrastructure action → **Dispute** |
+
+**Do NOT create a dispute for:**
+- Simple tool errors (MCP server down, build timeout) → use the DLQ
+- Scope creep → use the DLQ with a redirect
+- First or second failure → retry automatically
+
+## Dispute Record Format
+
+```markdown
+### DSP-XXX: Short description of the disagreement
+
+| Field | Value |
+|-------|-------|
+| **Date** | YYYY-MM-DD |
+| **Priority** | `critical` / `high` / `medium` / `low` |
+| **Linear Issue** | PRJ-XX |
+| **Trigger** | `panel-3x-block` / `approach-conflict` / `criteria-conflict` / `architectural-ambiguity` / `external-dependency` |
+| **Implementing Agent** | Agent name |
+| **Reviewing Agent(s)** | Agent name(s) |
+| **Attempts** | Total attempts (fast review + panel) |
+| **Est. Tokens Spent** | ~XXK across all attempts |
+| **Status** | `pending` / `resolved` / `deferred` |
+
+#### Context
+
+Brief description of the task and what was being implemented.
+
+#### Agent's Position
+
+What the implementing agent produced and why it believes the approach is correct.
+Include specific file paths and code references.
+
+#### Reviewer's Position
+
+What the reviewer(s) flagged and why they believe changes are needed.
+Include the specific MUST-FIX items from the last review attempt.
+
+#### Attempt History
+
+| # | Type | Verdict | Key Feedback |
+|---|------|---------|-------------|
+| 1 | Fast review | FAIL | [one-line summary] |
+| 2 | Fast review | FAIL | [one-line summary] |
+| 3 | Fast review | FAIL → escalate | [one-line summary] |
+| 4 | Panel (attempt 1) | BLOCK (1/3 PASS) | [one-line summary] |
+| 5 | Panel (attempt 2) | BLOCK (0/3 PASS) | [one-line summary] |
+| 6 | Panel (attempt 3) | BLOCK (1/3 PASS) | [one-line summary] |
+
+#### Resolution Options
+
+Present 2-3 concrete options for the human decision-maker:
+
+1. **Option A: [Accept agent's approach]** — Rationale: ... Risk: ...
+2. **Option B: [Accept reviewer's feedback]** — Rationale: ... Risk: ...
+3. **Option C: [Alternative approach]** — Rationale: ... Risk: ...
+
+#### Recommended Action
+
+Which option the Team Lead recommends and why. Include specific next steps:
+- [ ] Human decides on option A/B/C
+- [ ] If A: merge as-is, create follow-up ticket for reviewer concerns
+- [ ] If B: re-delegate with explicit instruction to [specific change]
+- [ ] If C: [describe the alternative path]
+
+#### Artifacts
+
+Links to evidence for human review:
+- Panel report: `customizations/logs/panel/[panel-key].md`
+- Review log entries: `customizations/logs/reviews.ndjson` (filter by issue)
+- Changed files: [list of files in the last attempt]
+- DLQ entry (if any): `DLQ-XXX`
+```
+
+## Priority Guidelines
+
+| Priority | Criteria | Expected Human Response Time |
+|----------|----------|------------------------------|
+| `critical` | Blocks other in-progress work; overnight run stopped | Same day |
+| `high` | Blocks the current feature; no workaround | Within 2 days |
+| `medium` | Feature can proceed without this subtask | Within 1 week |
+| `low` | Nice-to-have; deferrable | Next planning session |
+
+## Lifecycle
+
+```
+┌──────────────────────────────────────┐
+│  Automated resolution exhausted      │
+│  (3x panel BLOCK or approach conflict)│
+└──────────────┬───────────────────────┘
+               │
+               ▼
+┌──────────────────────────────────────┐
+│  Team Lead creates dispute record     │
+│  Status: pending                      │
+│  Logs to disputes.ndjson              │
+│  Links to Linear issue                │
+└──────────────┬───────────────────────┘
+               │
+               ▼
+┌──────────────────────────────────────┐
+│  Human reviews dispute                │
+│  Picks resolution option              │
+│  Updates Status → resolved/deferred   │
+└──────────────┬───────────────────────┘
+               │
+     ┌─────────┴──────────┐
+     ▼                    ▼
+  resolved             deferred
+  (re-delegate          (create follow-up
+   with human's          ticket, continue
+   decision)             with other work)
+```
+
+## Integration with DLQ
+
+Disputes and DLQ entries serve different purposes:
+
+| | Dead Letter Queue | Dispute Record |
+|--|-------------------|----------------|
+| **Purpose** | Diagnostic failure log | Actionable human decision |
+| **When** | Tool errors, timeouts, simple failures | Unresolvable agent/reviewer conflicts |
+| **Action** | Retry or investigate root cause | Human picks a resolution option |
+| **Urgency** | Can wait for pattern analysis | Needs human input to unblock |
+| **File** | `AGENT-FAILURES.md` | `DISPUTES.md` (this file) |
+
+A dispute MAY reference a DLQ entry if the dispute escalated from a logged failure. Use the `DLQ-XXX` ID in the Artifacts section.
+
+---
+
+## Disputes
+
+<!-- Disputes are appended here by the Team Lead during sessions.
+     Start numbering from DSP-001. -->
+
+---
+
+## Index
+
+| ID | Date | Priority | Trigger | Linear Issue | Status |
+|----|------|----------|---------|-------------|--------|
+
+````

package/src/orchestrator/customizations/KNOWLEDGE-GRAPH.md

@@ -0,0 +1,10 @@
+# Knowledge Graph
+
+<!-- Append-only relationship log capturing structured connections between files, agents, patterns, decisions, bugs, and lessons.
+     Used by the Team Lead to discover file dependencies, match agents to tasks, and surface relevant context during delegation.
+     See the agent-memory skill for the full protocol, entity types, and relationship types. -->
+
+## Relationships
+
+| Source | Relationship | Target | Added | Context |
+|--------|-------------|--------|-------|---------|

package/src/orchestrator/customizations/LESSONS-LEARNED.md

@@ -0,0 +1,70 @@
+````markdown
+# Lessons Learned
+
+Structured log of tool/command pitfalls, workarounds, and correct approaches discovered through agent execution. **Every agent** must read this file before starting work and must add entries when they discover a new pitfall through trial-and-error.
+
+> **This file is the collective memory of the agent team.** It prevents repeating the same mistakes across sessions.
+
+---
+
+## How to Use This File
+
+### Before starting work
+
+1. Read the **entire file** (or at minimum, the sections relevant to your task)
+2. Apply any relevant lessons to your approach **before** attempting commands or tool calls
+
+### When to add a new entry
+
+Add a lesson when **any** of these occur:
+- A command, tool call, or API call fails and you had to retry with a different approach
+- You discover a parameter, syntax, or configuration quirk not documented elsewhere
+- A workaround is needed for a third-party tool, MCP server, or platform limitation
+- An approach that seems obvious turns out to be wrong
+
+### Entry format
+
+```markdown
+### LES-XXX: Short descriptive title
+
+| Field | Value |
+|-------|-------|
+| **Category** | `linear` / `mcp-tools` / `nx-commands` / `terminal` / `next-js` / `sanity` / `supabase` / `git` / `vercel` / `browser-testing` / `general` |
+| **Added** | YYYY-MM-DD |
+| **Severity** | `high` (blocks work) / `medium` (wastes 5+ min) / `low` (minor annoyance) |
+
+**Problem:** What went wrong and what error or unexpected behavior was observed.
+
+**Wrong approach:** The obvious/intuitive approach that fails.
+
+**Correct approach:** The working solution.
+
+**Why:** Root cause explanation (if known).
+```
+
+---
+
+## Lessons
+
+<!-- Lessons are appended here by agents during sessions.
+     Start numbering from LES-001. -->
+
+---
+
+## Index by Category
+
+| Category | Lessons |
+|----------|---------|
+| `linear` | — |
+| `mcp-tools` | — |
+| `nx-commands` | — |
+| `terminal` | — |
+| `next-js` | — |
+| `sanity` | — |
+| `supabase` | — |
+| `git` | — |
+| `vercel` | — |
+| `browser-testing` | — |
+| `general` | — |
+
+````

package/src/orchestrator/customizations/README.md

@@ -0,0 +1,59 @@
+# Customizations
+
+Project-specific configuration for the AI agent framework. Everything in this folder is **particular to this project** — the rest of the orchestrator directory (instructions, skills, agents, prompts, workflows) is designed to be project-agnostic and reusable across repositories.
+
+## Why this exists
+
+Skills and instructions contain generic methodology (how to write migrations, how to test in a browser, how to run a panel review). This folder holds the concrete values those skills operate on — project IDs, table schemas, team UUIDs, endpoint inventories, and similar configuration that changes per project.
+
+Skills reference these files with relative links like `../../customizations/stack/api-config.md`, so agents automatically load project context when they load a skill.
+
+## Contents
+
+| File | Purpose |
+|------|---------|
+| `project.instructions.md` | High-level project context — apps, libraries, tech stack, ports, URLs |
+| `LESSONS-LEARNED.md` | Knowledge base of retries, workarounds, and gotchas — read before every session |
+| `AGENT-FAILURES.md` | Dead letter queue for failed agent delegations |
+| `AGENT-PERFORMANCE.md` | Agent success tracking, log query recipes, performance metrics |
+| `AGENT-EXPERTISE.md` | Structured tracking of agent strengths/weaknesses across sessions |
+| `KNOWLEDGE-GRAPH.md` | Append-only relationship log for file dependencies, patterns, decisions |
+
+### `agents/` — Agent framework config
+
+| File | Purpose |
+|------|---------|
+| `agent-registry.md` | Specialist agents with model tier assignments and scope examples |
+| `skill-matrix.md` | Maps capability slots to concrete skill names per agent role |
+
+### `stack/` — Tech stack config
+
+| File | Purpose |
+|------|---------|
+| _(created by `bootstrap-customizations` prompt based on detected technologies)_ | |
+
+### `project/` — Project management config
+
+| File | Purpose |
+|------|---------|
+| `docs-structure.md` | `docs/` directory tree and documentation practices |
+| _(task tracker config created by `bootstrap-customizations` prompt)_ | |
+
+### `logs/` — Append-only NDJSON session logs
+
+Structured machine-readable logs appended automatically by agents during sessions, delegations, and panel reviews.
+
+| File | Purpose |
+|------|---------|
+| `README.md` | Schema documentation for the NDJSON log files |
+| `sessions.ndjson` | Structured session log entries |
+| `delegations.ndjson` | Structured delegation log entries |
+| `panels.ndjson` | Structured panel review log entries |
+
+## When to update
+
+Update these files when the project changes — new tables, new API routes, new apps, new Linear labels, etc. The skills themselves should rarely need editing; changing a project ID or adding a table column is a customization change, not a skill change.
+
+## Bootstrap
+
+Run the `bootstrap-customizations` prompt to auto-discover the project's structure and populate these files. It will scan for frameworks, databases, CMS, deployment config, and task tracking, then generate the appropriate `stack/` and `project/` files.

package/src/orchestrator/customizations/agents/agent-registry.md

@@ -0,0 +1,46 @@
+````markdown
+# Agent Registry
+
+Project-specific agent-to-model assignments and scope examples referenced by the `team-lead-reference` skill.
+
+<!-- Populated by the `bootstrap-customizations` prompt based on project structure. -->
+
+## Specialist Agent Registry
+
+| Agent | Model | Tier | Best For |
+|-------|-------|------|----------|
+| **Developer** | Gemini 3.1 Pro | Standard | Full-stack feature implementation, pages, components, routing, API routes |
+| **Testing Expert** | GPT-5.3-Codex | Utility | E2E tests, browser validation, terminal-heavy test loops |
+| **Content Engineer** | Gemini 3.1 Pro | Standard | CMS schema, GROQ queries, MCP tool coordination |
+| **Database Engineer** | Gemini 3.1 Pro | Standard | Migrations, RLS policies, SQL optimization |
+| **UI/UX Expert** | Gemini 3.1 Pro | Standard | Components, styling, accessibility |
+| **Performance Expert** | Gemini 3.1 Pro | Standard | Bundle size, Core Web Vitals, profiling |
+| **Security Expert** | Claude Opus 4.6 | Premium | Auth, RLS audits, headers, precision analysis |
+| **Data Expert** | GPT-5.3-Codex | Utility | ETL pipelines, scrapers, terminal-heavy data import |
+| **DevOps Expert** | GPT-5.3-Codex | Utility | Deployments, cron jobs, terminal-heavy infrastructure |
+| **Documentation Writer** | GPT-5 mini | Economy | Docs, roadmaps, ADRs (cost-effective) |
+| **Architect** | Claude Opus 4.6 | Premium | Architecture decisions, critical review, expert reasoning |
+| **Reviewer** | GPT-5 mini | Economy | Mandatory fast review after every delegation, code correctness checks |
+| **Researcher** | GPT-5 mini | Economy | Codebase exploration, pattern discovery, git archaeology, pre-implementation research |
+| **Copywriter** | GPT-5 mini | Economy | UI microcopy, marketing text, email templates |
+| **SEO Specialist** | GPT-5 mini | Economy | Meta tags, structured data, sitemaps |
+| **API Designer** | Gemini 3.1 Pro | Standard | API route architecture, endpoint conventions |
+| **Release Manager** | GPT-5.3-Codex | Utility | Pre-release verification, changelog generation |
+
+## Deepen-Plan Scope Examples
+
+<!-- Customize these paths to match your project structure.
+     When running the Deepen-Plan protocol, split research by domain: -->
+
+```
+Researcher A: "Research database/backend aspects of [feature]"
+  Scope: <database-migrations-dir>/, <server-libs>/
+
+Researcher B: "Research frontend/UI aspects of [feature]"
+  Scope: <ui-libs>/, <app-dir>/
+
+Researcher C: "Research CMS/content aspects of [feature]"
+  Scope: <cms-dir>/, <queries-lib>/
+```
+
+````

package/src/orchestrator/customizations/agents/skill-matrix.md

@@ -0,0 +1,142 @@
+````markdown
+# Skill Matrix
+
+Maps abstract technology capabilities to concrete skill implementations. Agents reference **capability slots** instead of hardcoded technology skills — when the stack changes, update the bindings here and all agents automatically resolve to the correct skill.
+
+**Process/methodology skills** (session checkpoints, validation gates, self-improvement, etc.) are referenced directly in agent files — they don't go through the matrix.
+
+## How It Works
+
+```
+Agent file                  Skill Matrix                 Skill file
+┌──────────────┐           ┌──────────────┐           ┌──────────────┐
+│ Developer    │           │ framework:   │           │ nextjs-      │
+│  needs:      │──lookup──▶│  nextjs      │──load────▶│ patterns     │
+│  framework   │           │              │           │              │
+│  ui-library  │           │ ui-library:  │           │ react-       │
+│  api-layer   │           │  react       │──load────▶│ development  │
+│              │           │              │           │              │
+│              │           │ api-layer:   │           │ api-         │
+│              │           │  nextjs-api  │──load────▶│ patterns     │
+│              │           │              │           │              │
+└──────────────┘           └──────────────┘           └──────────────┘
+```
+
+1. **Agents** declare which capability slots they need (e.g., `framework`, `database`)
+2. **This matrix** maps each slot to the current technology and its skill file
+3. **When delegating**, resolve slots through this matrix to load the correct skill
+4. **To switch tech**, update only the binding row — no agent files change
+
+## Stack Bindings
+
+<!-- Populated by the `bootstrap-customizations` prompt based on detected technologies. -->
+
+### Primary Stack
+
+| Slot | Technology | Skill | Description |
+|------|-----------|-------|-------------|
+| `language` | | _(general.instructions.md)_ | Primary programming language, type system |
+| `ui-library` | | | Component architecture, hooks, state, styling |
+| `framework` | | | SSR/SSG, routing, layouts, Server/Client Components |
+| `database` | | | Schema, migrations, auth flow, roles |
+| `cms` | | | Document types, queries, schema management |
+| `deployment` | | | Hosting, cron jobs, env vars, caching, headers |
+| `monorepo` | | | Task running, caching, affected commands, generators |
+
+### Tooling
+
+| Slot | Technology | Skill | Description |
+|------|-----------|-------|-------------|
+| `api-layer` | | | API routes, validation, search architecture |
+| `data-pipeline` | | | ETL, scraping, data processing |
+| `testing` | | | Unit/integration tests, coverage, test planning |
+| `e2e-testing` | | | Browser automation, viewport testing, visual validation |
+
+### Disciplines
+
+| Slot | Approach | Skill | Description |
+|------|---------|-------|-------------|
+| `performance` | | `performance-optimization` | Bundle size, rendering, caching, profiling |
+| `security` | | `security-hardening` | Auth, headers, input validation, vulnerability mgmt |
+| `accessibility` | WCAG 2.2 Level AA | `accessibility-standards` | Keyboard nav, screen readers, contrast, semantics |
+| `design-system` | | `frontend-design` | Design thinking, typography, color, motion, layout |
+| `seo` | | `seo-patterns` | Technical SEO patterns for meta tags, JSON-LD, sitemaps, URL strategy |
+
+## Agent Capability Matrix
+
+Each row shows which capability slots an agent needs (resolved through this matrix) and which process skills it uses directly.
+
+| Agent | Capability Slots | Direct Skills |
+|-------|-----------------|---------------|
+| **Developer** | `framework`, `ui-library`, `api-layer` | `validation-gates` |
+| **Database Engineer** | `database`, `security` | — |
+| **UI/UX Expert** | `design-system`, `ui-library`, `accessibility` | `e2e-testing`¹ |
+| **Content Engineer** | `cms` | — |
+| **Testing Expert** | `e2e-testing`, `testing` | `validation-gates` |
+| **Security Expert** | `security`, `database` | — |
+| **Data Expert** | `data-pipeline` | — |
+| **DevOps Expert** | `deployment` | — |
+| **Performance Expert** | `performance` | — |
+| **Architect** | `monorepo` | `documentation-standards` |
+| **Copywriter** | `cms` | `documentation-standards` |
+| **SEO Specialist** | `framework`, `cms`, `seo` | — |
+| **API Designer** | `api-layer`, `framework`, `security` | — |
+| **Release Manager** | `monorepo`, `deployment` | `validation-gates`, `documentation-standards` |
+| **Documentation Writer** | — | `documentation-standards`, `code-commenting` |
+| **Researcher** | — | `context-map`, `self-improvement` |
+| **Team Lead** | — | `team-lead-reference`, `task-management`, `session-checkpoints`, `validation-gates`, `fast-review`, `panel-majority-vote`, `context-map`, `memory-merger`, `agent-hooks` |
+
+¹ UI/UX Expert uses `e2e-testing` as a utility (viewport resize commands) — resolved through the matrix like other slots.
+
+## Process Skills (Always Direct)
+
+These are methodology/workflow skills — not tied to any technology. Referenced directly in agent files, never through capability slots.
+
+| Skill | Purpose |
+|-------|---------|
+| `self-improvement` | Lessons-learned protocol, retry documentation |
+| `session-checkpoints` | Session state saving, resuming, forking |
+| `context-map` | File impact mapping before complex changes |
+| `panel-majority-vote` | 3-reviewer quality gate (PASS/BLOCK) |
+| `memory-merger` | Graduate lessons into permanent skills/instructions |
+| `code-commenting` | Self-documenting code patterns, annotation tags |
+| `agent-hooks` | Agent lifecycle hooks (session-start, session-end, etc.) |
+| `agent-memory` | Agent expertise tracking, cross-session knowledge graph |
+| `task-management` | Linear board conventions, issue naming, priorities |
+| `team-lead-reference` | Team Lead orchestration reference, model routing |
+| `fast-review` | Mandatory single-reviewer gate after every delegation |
+| `validation-gates` | Shared validation gate definitions (lint, test, build) |
+| `documentation-standards` | Documentation templates, formatting rules |
+
+## Switching Technologies
+
+### Example: Supabase → Convex
+
+1. Create a new skill: `skills/convex-database/SKILL.md`
+2. Update this matrix: `database` row → Technology: `Convex`, Skill: `convex-database`
+3. Update `project.instructions.md` to reflect the new tech stack
+4. **No agent files change** — Database Engineer, Security Expert still reference the `database` slot
+
+### Example: React → Svelte + Next.js → SvelteKit
+
+1. Create skills: `skills/svelte-development/SKILL.md`, `skills/sveltekit-patterns/SKILL.md`
+2. Update matrix: `ui-library` → `Svelte` / `svelte-development`
+3. Update matrix: `framework` → `SvelteKit` / `sveltekit-patterns`
+4. Update `project.instructions.md` and `general.instructions.md`
+5. **No agent files change** — Developer, UI/UX Expert still reference `framework` and `ui-library` slots
+
+### Example: Jest → Vitest
+
+1. Create skill: `skills/vitest-workflow/SKILL.md`
+2. Update matrix: `testing` → `Vitest` / `vitest-workflow`
+3. **No agent files change** — Testing Expert still references the `testing` slot
+
+## Design Principles
+
+1. **Single source of truth** — Technology choices live here, not scattered across agent files
+2. **Agents are stack-agnostic** — They describe *what* they need, not *which* tool they use
+3. **Swap without rewriting** — Changing one matrix row updates every agent that uses that slot
+4. **Process skills are stable** — Methodology doesn't change with technology; direct references are fine
+5. **Capability slots are composable** — Agents can combine any slots (e.g., Security Expert needs both `security` + `database`)
+
+````

package/src/orchestrator/customizations/logs/README.md

@@ -0,0 +1,181 @@
+# Agent Session Logs
+
+Append-only NDJSON logs for agent activity tracking. Each file stores one JSON object per line.
+
+## Files
+
+| File | Appended by | Schema |
+|------|------------|--------|
+| `sessions.ndjson` | All agents (via self-improvement protocol) | Session record |
+| `delegations.ndjson` | Team Lead agent | Delegation record |
+| `reviews.ndjson` | Team Lead (via fast-review skill) | Fast review record |
+| `panels.ndjson` | Panel runner (via panel majority vote skill) | Panel record |
+| `disputes.ndjson` | Team Lead (via dispute protocol) | Dispute record |
+
+## Session Record Schema
+
+```json
+{
+  "timestamp": "2026-02-25T14:30:00Z",
+  "agent": "Developer",
+  "model": "gpt-5.3-codex",
+  "task": "PRJ-57: Fix header component",
+  "linear_issue": "PRJ-57",
+  "outcome": "success",
+  "duration_min": 12,
+  "files_changed": 5,
+  "retries": 0,
+  "lessons_added": [],
+  "discoveries": []
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `timestamp` | `string` | Yes | ISO 8601 datetime (YYYY-MM-DDTHH:MM:SSZ) |
+| `agent` | `string` | Yes | Agent name from the registry |
+| `model` | `string` | Yes | Model used (e.g., `claude-opus-4-6`, `gpt-5.3-codex`) |
+| `task` | `string` | Yes | Short description of the task performed |
+| `linear_issue` | `string` | No | Issue ID if applicable (e.g., `PRJ-57`) |
+| `outcome` | `string` | Yes | `success`, `partial`, `failed` |
+| `duration_min` | `number` | No | Estimated session duration in minutes |
+| `files_changed` | `number` | No | Number of files created/modified |
+| `retries` | `number` | No | Number of retried operations |
+| `lessons_added` | `string[]` | No | Lesson IDs added (e.g., `["LES-015"]`) |
+| `discoveries` | `string[]` | No | Issues discovered (issue IDs or KNOWN-ISSUES IDs) |
+
+## Delegation Record Schema
+
+```json
+{
+  "timestamp": "2026-02-25T14:30:00Z",
+  "session_id": "feat/prj-57",
+  "agent": "Developer",
+  "model": "gpt-5.3-codex",
+  "tier": "fast",
+  "mechanism": "sub-agent",
+  "linear_issue": "PRJ-57",
+  "outcome": "success",
+  "retries": 0,
+  "phase": 2,
+  "file_partition": ["src/components/", "src/pages/"]
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `timestamp` | `string` | Yes | ISO 8601 datetime (YYYY-MM-DDTHH:MM:SSZ) |
+| `session_id` | `string` | Yes | Branch name or feature identifier |
+| `agent` | `string` | Yes | Agent name delegated to |
+| `model` | `string` | Yes | Model used |
+| `tier` | `string` | Yes | `economy`, `fast`, `standard`, `premium` |
+| `mechanism` | `string` | Yes | `sub-agent` or `background` |
+| `linear_issue` | `string` | No | Issue ID |
+| `outcome` | `string` | Yes | `success`, `partial`, `failed`, `redirected` |
+| `retries` | `number` | No | Times re-delegated |
+| `phase` | `number` | No | Execution phase number |
+| `file_partition` | `string[]` | No | Directories/files assigned |
+
+## Fast Review Record Schema
+
+```json
+{
+  "timestamp": "2026-02-28T14:30:00Z",
+  "linear_issue": "PRJ-42",
+  "agent": "Developer",
+  "reviewer_model": "gpt-5-mini",
+  "verdict": "pass",
+  "attempt": 1,
+  "issues_critical": 0,
+  "issues_major": 0,
+  "issues_minor": 2,
+  "confidence": "high",
+  "escalated": false,
+  "duration_sec": 45
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `timestamp` | `string` | Yes | ISO 8601 datetime (YYYY-MM-DDTHH:MM:SSZ) |
+| `linear_issue` | `string` | No | Issue ID if applicable |
+| `agent` | `string` | Yes | Agent whose output was reviewed |
+| `reviewer_model` | `string` | Yes | Model used for the reviewer (e.g., `gpt-5-mini`) |
+| `verdict` | `string` | Yes | `pass` or `fail` |
+| `attempt` | `number` | Yes | Review attempt number (1, 2, or 3) |
+| `issues_critical` | `number` | Yes | Count of critical severity issues |
+| `issues_major` | `number` | Yes | Count of major severity issues |
+| `issues_minor` | `number` | Yes | Count of minor severity issues |
+| `confidence` | `string` | Yes | Reviewer self-reported confidence: `low`, `medium`, `high` |
+| `escalated` | `boolean` | Yes | Whether this review triggered escalation to panel |
+| `duration_sec` | `number` | No | Review duration in seconds |
+
+## Panel Record Schema
+
+```json
+{
+  "timestamp": "2026-02-25T14:30:00Z",
+  "panel_key": "instruction-refactoring",
+  "verdict": "pass",
+  "pass_count": 3,
+  "block_count": 0,
+  "must_fix": 0,
+  "should_fix": 5,
+  "reviewer_model": "claude-opus-4-6",
+  "weighted": false,
+  "attempt": 1,
+  "linear_issue": "PRJ-57",
+  "artifacts_count": 14,
+  "report_path": "customizations/logs/panel/instruction-refactoring.md"
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `timestamp` | `string` | Yes | ISO 8601 datetime (YYYY-MM-DDTHH:MM:SSZ) |
+| `panel_key` | `string` | Yes | Filesystem-safe panel identifier |
+| `verdict` | `string` | Yes | `pass` or `block` |
+| `pass_count` | `number` | Yes | Number of reviewers who voted PASS |
+| `block_count` | `number` | Yes | Number of reviewers who voted BLOCK |
+| `must_fix` | `number` | Yes | Total MUST-FIX items across all reviewers |
+| `should_fix` | `number` | Yes | Total SHOULD-FIX items across all reviewers |
+| `reviewer_model` | `string` | Yes | Model used for reviewers |
+| `weighted` | `boolean` | Yes | Whether performance-weighted voting was applied |
+| `attempt` | `number` | Yes | Attempt number (1 = first try) |
+| `linear_issue` | `string` | No | Issue ID if applicable |
+| `artifacts_count` | `number` | No | Number of artifacts reviewed |
+| `report_path` | `string` | No | Path to the full panel report |
+
+## Dispute Record Schema
+
+```json
+{
+  "timestamp": "2026-02-28T16:00:00Z",
+  "dispute_id": "DSP-001",
+  "linear_issue": "PRJ-42",
+  "priority": "high",
+  "trigger": "panel-3x-block",
+  "implementing_agent": "Developer",
+  "reviewing_agents": ["Reviewer", "Panel (3x)"],
+  "total_attempts": 6,
+  "est_tokens_spent": 120000,
+  "status": "pending",
+  "resolution_option_chosen": null,
+  "resolved_at": null
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `timestamp` | `string` | Yes | ISO 8601 datetime when dispute was created |
+| `dispute_id` | `string` | Yes | Dispute ID (e.g., `DSP-001`) |
+| `linear_issue` | `string` | No | Issue ID if applicable |
+| `priority` | `string` | Yes | `critical`, `high`, `medium`, `low` |
+| `trigger` | `string` | Yes | `panel-3x-block`, `approach-conflict`, `criteria-conflict`, `architectural-ambiguity`, `external-dependency` |
+| `implementing_agent` | `string` | Yes | Agent that attempted the implementation |
+| `reviewing_agents` | `string[]` | Yes | Agents that reviewed (e.g., `["Reviewer", "Panel (3x)"]`) |
+| `total_attempts` | `number` | Yes | Sum of fast review + panel attempts |
+| `est_tokens_spent` | `number` | No | Estimated tokens spent across all attempts |
+| `status` | `string` | Yes | `pending`, `resolved`, `deferred` |
+| `resolution_option_chosen` | `string` | No | Which option the human chose (null if pending) |
+| `resolved_at` | `string` | No | ISO 8601 datetime when resolved (null if pending) |

package/src/orchestrator/customizations/logs/delegations.ndjson

@@ -0,0 +1 @@
+

package/src/orchestrator/customizations/logs/panels.ndjson

@@ -0,0 +1 @@
+