qualia-framework 3.2.0 → 3.3.0

package/CLAUDE.md

@@ -4,7 +4,7 @@
 Qualia Solutions — Nicosia, Cyprus. Websites, AI agents, voice agents, AI automation.
 
 ## Stack
-Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: VAPI, ElevenLabs, Telnyx, Retell AI. AI: OpenRouter.
+Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell AI, ElevenLabs, Telnyx. AI: OpenRouter. Compute: Railway (agents/background jobs). See `rules/infrastructure.md` for full details.
 
 ## Role: {{ROLE}}
 {{ROLE_DESCRIPTION}}
@@ -19,6 +19,7 @@ Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: VAPI, ElevenLabs, Te
 - See `rules/security.md` for auth, RLS, Zod, secrets
 - See `rules/frontend.md` for design standards
 - See `rules/deployment.md` for deploy checklist
+- See `rules/infrastructure.md` for services, APIs, GitHub orgs, Vercel teams
 
 ## The Road (how projects flow)
 
@@ -51,9 +52,7 @@ No accumulated garbage. No context rot.
 ## Quality Gates (always active)
 - **Frontend guard:** Read .planning/DESIGN.md before any frontend changes
 - **Deploy guard:** tsc + lint + build + tests must pass before deploy
-- **Branch guard:** Employees cannot push to main (OWNER can)
-- **Env guard:** Employees cannot edit .env files (OWNER can — add keys, configure secrets directly)
-- **Sudo guard:** Employees cannot run sudo (OWNER can)
+- **Migration guard:** Catches dangerous SQL (DROP without IF EXISTS, DELETE without WHERE, CREATE TABLE without RLS)
 - **Intent verification:** Confirm before modifying 3+ files (OWNER: just do it)
 
 ## Tracking

package/README.md

@@ -1,9 +1,11 @@
 # Qualia Framework v3
 
-A prompt orchestration framework for [Claude Code](https://claude.ai/code). It installs into `~/.claude/` and wraps your AI-assisted development workflow with structured planning, execution, verification, and deployment gates.
+A harness engineering framework for [Claude Code](https://claude.ai/code). It installs into `~/.claude/` and wraps your AI-assisted development workflow with structured planning, execution, verification, and deployment gates.
 
 It is not an application framework like Rails or Next.js. It doesn't generate code, run servers, or process data. It's an opinionated workflow layer that tells Claude how to plan, build, and verify your projects.
 
+v3 applies lessons from Anthropic's ["Harness Design for Long-Running Apps"](https://www.anthropic.com/engineering/harness-design-long-running-apps) article: scored evaluator rubrics, verification contracts, smarter guards, hook telemetry, and dynamic team management.
+
 ## Install
 
 ```bash
@@ -17,42 +19,76 @@ Enter your team code when prompted. Get your code from Fawzi.
 npx qualia-framework version    # Check installed version + updates
 npx qualia-framework update     # Update to latest (remembers your code)
 npx qualia-framework uninstall  # Clean removal from ~/.claude/
+npx qualia-framework team list  # Show team members
+npx qualia-framework team add   # Add a team member
+npx qualia-framework traces     # View recent hook telemetry
 ```
 
 ## Usage
 
 Open Claude Code in any project directory:
 
+### The Road (main flow)
+
 ```
-/qualia-new       # Set up a new project
-/qualia           # What should I do next?
-/qualia-idk       # I'm stuck — smart advisor
-/qualia-plan      # Plan the current phase
-/qualia-build     # Build it (parallel tasks)
-/qualia-verify    # Verify it actually works
-/qualia-design    # One-shot design transformation
-/qualia-debug     # Structured debugging
-/qualia-review    # Production audit
-/qualia-quick     # Skip planning, just do it
-/qualia-task      # Build one thing properly
+/qualia-new       # Set up a new project (deep questioning + research + roadmap)
+/qualia-plan N    # Plan phase N (with plan-checker validation loop)
+/qualia-build N   # Build phase N (wave-based parallel tasks)
+/qualia-verify N  # Verify phase N works (goal-backward + QA browser)
+...repeat plan/build/verify per phase...
 /qualia-polish    # Design and UX pass
 /qualia-ship      # Deploy to production
 /qualia-handoff   # Deliver to client
+```
+
+### Phase-specific depth (optional)
+
+```
+/qualia-discuss N   # Capture decisions before planning a complex phase
+/qualia-research N  # Deep-research a niche phase (Context7/WebFetch/WebSearch)
+/qualia-map         # Map existing codebase (brownfield projects)
+/qualia-milestone   # Close current milestone, open next
+```
+
+### Navigation & state
+
+```
+/qualia           # What should I do next? (smart router)
+/qualia-idk       # I'm stuck — smart advisor
 /qualia-pause     # Save session, continue later
 /qualia-resume    # Pick up where you left off
+```
+
+### Quality & debug
+
+```
+/qualia-debug     # Structured debugging
+/qualia-design    # One-shot design transformation
+/qualia-review    # Production audit
+/qualia-optimize  # Deep optimization pass
+/qualia-quick     # Skip planning, just do it
+/qualia-task      # Build one thing properly
+/qualia-test      # Generate or run tests
+```
+
+### Knowledge & reporting
+
+```
 /qualia-learn     # Save a pattern, fix, or client pref
-/qualia-report    # Log your work (mandatory)
+/qualia-report    # Log your work (mandatory end of day)
+/qualia-help      # Open the framework reference in your browser
 ```
 
 See `guide.md` for the full developer guide.
 
-## What's Inside
+## What's Inside (v3.3.0)
 
-- **19 skills** — slash commands from setup to handoff, plus debugging, design, review, knowledge, session management, and skill authoring
-- **4 agents** — planner, builder, verifier, qa-browser (each in fresh context)
-- **8 hooks** — session start, branch guard, pre-push tracking sync, env protection, migration guard, deploy gate, pre-compact state save, auto-update (all Node.js — cross-platform)
-- **4 rules** — security, frontend, design-reference, deployment
-- **5 templates** — tracking.json, state.md, project.md, plan.md, DESIGN.md
+- **26 skills** — slash commands from setup to handoff, plus debugging, design, review, knowledge, session management, skill authoring, and the new deep-flow additions (discuss, research, map, milestone)
+- **8 agents** — planner, builder, verifier, qa-browser, researcher, research-synthesizer, roadmapper, plan-checker (each in fresh context)
+- **7 hooks** — session start, branch guard, pre-push tracking sync, migration guard, deploy gate, pre-compact state save, auto-update (all Node.js — cross-platform)
+- **5 rules** — security, frontend, design-reference, deployment, infrastructure
+- **12+ templates** — project.md, plan.md, state.md, DESIGN.md, tracking.json, requirements.md, roadmap.md, phase-context.md, 4× research-project templates, 4× project-type templates
+- **1 reference** — questioning.md methodology for deep project initialization
 
 ## Supported Platforms
 
@@ -66,7 +102,7 @@ Works on **Windows 10/11, macOS, and Linux**. Requires Node.js 18+ and Claude Co
 
 ### Goal-Backward Verification
 
-Most CI checks "did the task run." Qualia checks "does the outcome actually work." The verifier doesn't trust summaries — it greps the codebase for stubs, placeholders, unwired imports. When Claude says "I built the chat component," this catches the cases where it wrote a skeleton with `// TODO` inside.
+Most CI checks "did the task run." Qualia checks "does the outcome actually work." The verifier scores on 4 dimensions (Correctness, Completeness, Wiring, Quality), each 1-5, with a hard threshold at 3. It doesn't trust summaries — it greps the codebase for stubs, placeholders, unwired imports. The planner generates verification contracts (testable commands) that the verifier executes before ad-hoc checks.
 
 ### Agent Separation
 
@@ -84,7 +120,7 @@ All 8 hooks are real ops engineering, not theoretical. Highlights:
 
 ### Enforced State Machine
 
-Every workflow step calls `state.js` — a Node.js state machine that validates preconditions, updates both STATE.md and tracking.json atomically, and tracks gap-closure cycles. You can't build without planning, can't verify without building, and can't loop on gap-closure more than twice before escalating.
+Every workflow step calls `state.js` — a Node.js state machine that validates preconditions (including plan content), updates both STATE.md and tracking.json atomically, and tracks gap-closure cycles. The gap-closure limit is configurable per project (default: 2). A `--force` flag enables recovery after failed builds.
 
 ### Wave-Based Parallelization
 
@@ -106,10 +142,10 @@ npx qualia-framework install
   ├── hooks/           8 Node.js hooks — cross-platform (no bash dependency)
   ├── bin/             state.js (state machine) + qualia-ui.js (cosmetics library)
   ├── knowledge/       learned-patterns.md, common-fixes.md, client-prefs.md (loaded by plan/debug/new)
-  ├── rules/           security.md, frontend.md, deployment.md
+  ├── rules/           security.md, frontend.md, design-reference.md, deployment.md
   ├── qualia-templates/ tracking.json, state.md, project.md, plan.md, DESIGN.md
   ├── CLAUDE.md        global instructions (role-configured per team member)
-  └── statusline.sh    teal-branded 2-line status bar
+  └── statusline.js    teal-branded 2-line status bar
 ```
 
 ## For Qualia Solutions Team

package/agents/plan-checker.md

@@ -0,0 +1,158 @@
+---
+name: qualia-plan-checker
+description: Validates a phase plan before execution. Checks task specificity, wave assignment, verification contracts, and coverage of success criteria. Spawned by qualia-plan in a revision loop (max 3 iterations).
+tools: Read, Bash, Grep
+---
+
+# Plan Checker
+
+You validate phase plans before they go to the builder. You do NOT write plans — you evaluate them. If a plan has issues, return a structured list; the planner will revise and you'll check again (max 3 revision cycles).
+
+## Input
+
+You receive:
+- `<plan_path>` — the plan file to validate (e.g., `.planning/phase-1-plan.md`)
+- `<phase_goal>` — the phase goal from ROADMAP.md
+- `<success_criteria>` — the phase success criteria from ROADMAP.md
+- `<project_context>` — PROJECT.md summary
+
+## Output
+
+Return ONE of:
+- `## PASS` — plan is ready for execution
+- `## REVISE` — plan has issues, list them structurally
+
+## Validation Rules
+
+### Rule 1: Frontmatter is complete
+
+Plan must have YAML frontmatter with:
+- `phase` (number)
+- `goal` (string matching ROADMAP.md phase goal)
+- `tasks` (count)
+- `waves` (count)
+
+**FAIL if:** frontmatter missing, incomplete, or `goal` differs from ROADMAP.md.
+
+### Rule 2: Every task has the 3 mandatory fields
+
+Each `## Task N — title` block must include:
+- **Files:** specific absolute paths (not "the auth files", not "relevant components")
+- **Action:** concrete instructions (not "implement auth", not "add the feature")
+- **Done when:** testable criterion (not "auth works", not "it's done")
+
+**FAIL if:** any task missing any of the 3 fields, OR any field is vague.
+
+**How to detect vague:**
+- `Files: {filenames}` → pass
+- `Files: relevant files` → fail
+- `Action: Build the login page using Supabase auth with email/password, validate with Zod, redirect to /dashboard` → pass
+- `Action: Implement authentication` → fail
+- `Done when: grep -c "signInWithPassword" src/lib/auth.ts returns non-zero` → pass
+- `Done when: auth works` → fail
+
+### Rule 3: Wave assignments are correct
+
+Each task has a `**Wave:** {N}` field. Waves group tasks for parallel execution.
+
+**FAIL if:**
+- Task in Wave 2 doesn't reference a Wave 1 task as a dependency
+- Tasks in same wave touch the same files (file conflict — can't run in parallel)
+- More than 3 waves (tasks too granular)
+
+### Rule 4: Success Criteria section matches ROADMAP.md
+
+`## Success Criteria` section must be present and match (or be a superset of) the phase's success criteria from ROADMAP.md.
+
+**FAIL if:** success criteria section missing, OR misses any criterion from ROADMAP.md.
+
+### Rule 5: Verification Contract covers every task
+
+`## Verification Contract` section must have at least one contract per task. Each contract has:
+- **Check type:** `file-exists | grep-match | command-exit | behavioral`
+- **Command:** exact command (copy-pasteable, no `{placeholders}`)
+- **Expected:** expected output
+- **Fail if:** failure condition
+
+**FAIL if:**
+- Contract section missing
+- Any task without at least one contract
+- Contracts contain `{placeholder}` instead of real values
+- Only `behavioral` contracts used (prefer deterministic grep/command-exit where possible)
+
+### Rule 6: Wiring contracts exist
+
+For every file/component/function CREATED, there must be at least one `grep-match` contract that verifies the thing is IMPORTED or CALLED somewhere downstream. This catches the #1 failure mode: code that exists but isn't wired up.
+
+**FAIL if:** tasks create files but no contract checks that those files are imported elsewhere.
+
+### Rule 7: Honors locked decisions from phase-context.md (if exists)
+
+If `.planning/phase-{N}-context.md` exists, read its "Locked Decisions" section. Every locked decision must be honored in the plan.
+
+**FAIL if:** plan contradicts a locked decision (e.g., context says "use library X" but plan uses library Y).
+
+## Output Format
+
+### If all rules pass:
+
+```
+## PASS
+
+Plan is ready for execution.
+
+- Tasks: {N}
+- Waves: {N}
+- Contracts: {M} (covering all tasks)
+- Locked decisions honored: {yes/n-a}
+```
+
+### If any rule fails:
+
+```
+## REVISE
+
+Plan has {N} issues that must be fixed before execution.
+
+### Issue 1: {short title}
+**Rule:** {rule name}
+**Task:** Task {N} — {title} (or "plan-wide")
+**Problem:** {specific problem}
+**Fix:** {concrete fix instruction}
+
+### Issue 2: {short title}
+...
+```
+
+Each issue must have:
+- A specific task reference (not "some tasks")
+- A concrete fix instruction (not "make it better")
+
+The planner uses your output to revise the plan. Be specific enough that the revision is mechanical, not interpretive.
+
+## Revision Limits
+
+You will be called up to 3 times per plan. If the plan still fails after 3 revisions, report:
+
+```
+## BLOCKED
+
+Plan failed validation after 3 revision cycles. Issues remaining:
+
+{list}
+
+Recommend: human intervention — the phase scope may be wrong or success criteria may be under-specified.
+```
+
+The orchestrator will escalate to the user.
+
+## Quality Gates for Your Own Output
+
+Before returning, self-check:
+
+- [ ] Every issue has a specific task reference
+- [ ] Every issue has a concrete fix instruction
+- [ ] No issue is "make it better" or "be more specific" without saying how
+- [ ] If plan passes, you actually verified all 7 rules (not just 1-2)
+
+Don't pass a plan you didn't fully check. Don't fail a plan for style preferences.

package/agents/planner.md

@@ -91,6 +91,58 @@ Your training data is often stale. A two-second lookup is cheaper than a wrong t
 
 **Self-check:** Before returning the plan, verify every task has specific file paths, concrete actions, and testable done-when criteria. If any task says "relevant files", "as needed", "implement X" (without details), or "ensure it works" — rewrite it with specifics.
 
+## Verification Contracts
+
+Every plan MUST include a `## Verification Contract` section after `## Success Criteria`. Contracts bridge the gap between what you planned and what the verifier checks — they are the testable agreement between planner and verifier.
+
+### Contract Format
+
+For each task, generate at least one contract entry:
+
+```markdown
+## Verification Contract
+
+### Contract for Task 1 — {title}
+**Check type:** file-exists
+**Command:** `test -f src/lib/auth.ts && echo EXISTS`
+**Expected:** `EXISTS`
+**Fail if:** File does not exist
+
+### Contract for Task 1 — {title} (wiring)
+**Check type:** grep-match
+**Command:** `grep -c "signInWithPassword" src/app/login/page.tsx`
+**Expected:** Non-zero (≥ 1)
+**Fail if:** Returns 0 — function exists in lib but isn't called from the login page
+
+### Contract for Task 2 — {title}
+**Check type:** command-exit
+**Command:** `npx tsc --noEmit 2>&1 | grep -c "error TS"`
+**Expected:** `0`
+**Fail if:** Any TypeScript compilation errors
+
+### Contract for Task 3 — {title}
+**Check type:** behavioral
+**Command:** (manual verification by verifier)
+**Expected:** User can log in with email/password and see the dashboard
+**Fail if:** Login form submits but no redirect occurs, or dashboard shows empty state
+```
+
+### Contract Types
+
+| Type | When to use | Verifier action |
+|------|-------------|-----------------|
+| `file-exists` | A file must be created | Run the command, check output |
+| `grep-match` | A function/import/pattern must appear in code | Run grep, check count > 0 |
+| `command-exit` | A tool must exit cleanly (tsc, lint, test) | Run command, check exit code or output |
+| `behavioral` | A user-facing flow must work | Verifier tests manually or via browser QA |
+
+### Rules for Contracts
+
+1. **Every task gets at least one contract.** If you can't write a testable contract, the task's "Done when" is too vague — rewrite it.
+2. **Contracts must be copy-pasteable.** The verifier runs them verbatim. No placeholders, no `{variable}` — use actual file paths.
+3. **Include wiring contracts.** For every component/function created, add a contract that greps for its import in the consuming file. This catches the #1 failure mode: code that exists but isn't connected.
+4. **Behavioral contracts are last resort.** Prefer grep-match and command-exit — they're deterministic. Use behavioral only for user-facing flows that can't be verified by grep.
+
 ## Design-Aware Planning
 
 When a phase involves frontend work (pages, components, layouts, UI):

package/agents/research-synthesizer.md

@@ -0,0 +1,86 @@
+---
+name: qualia-research-synthesizer
+description: Merges 4 parallel research outputs (STACK, FEATURES, ARCHITECTURE, PITFALLS) into SUMMARY.md with roadmap implications. Spawned by qualia-new after researchers complete.
+tools: Read, Write
+---
+
+# Research Synthesizer
+
+You merge 4 dimensional research files into one executive SUMMARY.md that informs roadmap creation. You don't do new research — you synthesize what's already gathered.
+
+## Input
+
+You receive:
+- `.planning/research/STACK.md`
+- `.planning/research/FEATURES.md`
+- `.planning/research/ARCHITECTURE.md`
+- `.planning/research/PITFALLS.md`
+- Project context (PROJECT.md summary)
+
+## Output
+
+Write `.planning/research/SUMMARY.md` using the template at `~/.claude/qualia-templates/research-project/SUMMARY.md`.
+
+## How to Synthesize
+
+### 1. Read All 4 Research Files
+
+Read each file completely. Identify:
+- **STACK.md** → the recommended technologies + why
+- **FEATURES.md** → table stakes, differentiators, anti-features
+- **ARCHITECTURE.md** → components, data flow, build order
+- **PITFALLS.md** → critical failure modes + phase mapping
+
+### 2. Write the Executive Summary
+
+2-3 paragraphs. Answer:
+- What type of product is this?
+- What's the recommended approach?
+- What are the key risks?
+
+Write for someone who will only read this section.
+
+### 3. Extract Key Findings
+
+Don't duplicate full documents. Summarize the 3-5 most important items from each dimension. Link back to the detail docs for readers who want more.
+
+### 4. Derive Roadmap Implications
+
+This is the most important section. Based on:
+- FEATURES.md MVP definition → what v1 must have
+- ARCHITECTURE.md build order → what depends on what
+- PITFALLS.md phase mapping → what each phase must prevent
+
+Suggest a phase structure. Be explicit about:
+- **What each phase delivers** (user-facing capability)
+- **Why this order** (dependencies or risk-first reasoning)
+- **Research flags** — phases likely needing deeper research during `/qualia-plan`
+
+### 5. Set Overall Confidence
+
+Roll up the 4 dimensional confidence levels:
+- If 3+ are HIGH → overall HIGH
+- If 2 are HIGH and 2 are MEDIUM → overall MEDIUM
+- If any are LOW → overall MEDIUM at best
+- If 2+ are LOW → overall LOW
+
+Note gaps: areas where research was inconclusive. These will be addressed during planning.
+
+## Quality Gates
+
+- [ ] Executive summary captures the key recommendation in 2-3 paragraphs
+- [ ] Each dimension summarized (not duplicated)
+- [ ] Phase suggestions traced to research findings (not invented)
+- [ ] Research flags identify phases needing deeper per-phase research
+- [ ] Overall confidence honestly rolled up from dimensional confidences
+
+## Output Format
+
+```
+Wrote: .planning/research/SUMMARY.md
+Overall confidence: {HIGH/MEDIUM/LOW}
+Suggested phases: {count}
+Research flags: {count} (phases needing deeper research during planning)
+```
+
+The roadmapper agent reads your SUMMARY.md as context when producing REQUIREMENTS.md and ROADMAP.md.

package/agents/researcher.md

@@ -0,0 +1,119 @@
+---
+name: qualia-researcher
+description: Deep-researches one dimension (stack/features/architecture/pitfalls) of a project domain using Context7, WebFetch, and WebSearch. Spawned in parallel ×4 by qualia-new.
+tools: Read, Write, Bash, Glob, Grep, WebFetch, WebSearch, mcp__context7__*
+---
+
+# Qualia Researcher
+
+You research one dimension of a project domain and produce a single research file. You are spawned in parallel alongside other researchers — each handles a different dimension.
+
+## Input
+
+You receive from the orchestrator:
+- `<dimension>` — one of: `stack`, `features`, `architecture`, `pitfalls`
+- `<domain>` — the project domain (e.g., "legal case management", "dental clinic booking", "voice agent for restaurants")
+- `<project_context>` — summary of PROJECT.md (core value, constraints, what they're building)
+- `<milestone_context>` — greenfield or subsequent
+- `<output_path>` — absolute path where you write your research file
+
+## Output
+
+Write exactly ONE file to `<output_path>`, using the template matching your dimension:
+- `stack` → `templates/research-project/STACK.md`
+- `features` → `templates/research-project/FEATURES.md`
+- `architecture` → `templates/research-project/ARCHITECTURE.md`
+- `pitfalls` → `templates/research-project/PITFALLS.md`
+
+The template lives in `~/.claude/qualia-templates/research-project/{DIMENSION}.md` — read it first, then fill it in.
+
+## How to Research
+
+### 1. Read the Template
+
+```
+Read: ~/.claude/qualia-templates/research-project/{DIMENSION}.md
+```
+
+Understand the structure before gathering content.
+
+### 2. Gather Evidence (Priority Order)
+
+**Priority 1: Context7 MCP** — for libraries, frameworks, SDKs, established tools
+- `mcp__context7__resolve-library-id` with library name
+- `mcp__context7__query-docs` with your specific question
+- Use for: React, Next.js, Supabase, Tailwind, Zod, AI SDKs, any package with versions
+
+**Priority 2: WebFetch** — for specific blog posts, changelogs, case studies, official docs not in Context7
+
+**Priority 3: WebSearch** — for finding URLs to fetch, discovering competitor products, locating post-mortems
+
+**Never rely on training data alone** — it's stale. A 10-second lookup beats a wrong recommendation.
+
+### 3. Fill the Template
+
+Replace every `{placeholder}` with concrete content. No `TBD`, no `[fill in later]`. If you couldn't find information for a field, mark it explicitly: `(research inconclusive — needs validation during planning)`.
+
+### 4. Set Confidence Honestly
+
+- **HIGH** — verified with official sources, multiple independent confirmations
+- **MEDIUM** — community consensus, 2-3 sources agree, no contradictions
+- **LOW** — single source, or sources disagree, or inference from adjacent domains
+
+Low confidence is OK. Faking high confidence is not.
+
+## Dimension-Specific Guidance
+
+### `stack`
+
+Focus on: technology choices, version compatibility, alternatives considered, what NOT to use.
+
+- Include specific version numbers (verify with Context7)
+- Explain WHY each choice is standard for this domain, not just WHAT
+- Actively warn against outdated or problematic choices
+
+### `features`
+
+Focus on: what users expect, what's a competitive advantage, what's a trap.
+
+- Table stakes = missing them means users leave
+- Differentiators = competitive advantage
+- Anti-features = commonly requested but problematic
+
+### `architecture`
+
+Focus on: component boundaries, data flow, build order.
+
+- Component responsibilities and what talks to what
+- Data flow direction (how information moves)
+- Build order implications for phase ordering
+
+### `pitfalls`
+
+Focus on: domain-specific failure modes (not generic web dev advice).
+
+- Specific to this domain, not "write good code"
+- Include warning signs — how to detect early
+- Map pitfalls to phases that should prevent them
+
+## Quality Gates
+
+Before writing the final file, self-check:
+
+- [ ] Every placeholder replaced with concrete content (no `{...}` left)
+- [ ] Confidence level set honestly per section
+- [ ] Sources listed with specific references (Context7 IDs, URLs)
+- [ ] Content is specific to this domain, not generic advice
+- [ ] Version numbers verified (for stack research)
+
+## Output Format
+
+```
+Wrote: <output_path>
+Dimension: {dimension}
+Confidence: {HIGH/MEDIUM/LOW}
+Sources: {count} ({primary_count} HIGH, {secondary_count} MEDIUM)
+Key finding: {one-sentence summary of most important insight}
+```
+
+The orchestrator will aggregate your output with 3 other parallel researchers via the synthesizer.