@zigrivers/scaffold 3.10.1 → 3.12.0

package/README.md

@@ -1,6 +1,6 @@
 # Scaffold
 
-A TypeScript CLI that assembles AI-powered prompts at runtime to guide you from "I have an idea" to working software. Scaffold walks you through 60 structured pipeline steps — organized into 16 phases — plus 10 utility tools, and the supported AI tools handle the research, planning, and implementation for you.
+A TypeScript CLI that assembles AI-powered prompts at runtime to guide you from "I have an idea" to working software. Scaffold walks you through 60 structured pipeline steps — organized into 16 phases — plus 11 utility tools, and the supported AI tools handle the research, planning, and implementation for you.
 
 By the end, you'll have a fully planned, standards-documented, implementation-ready project with working code.
 
@@ -38,7 +38,7 @@ Either way, Scaffold constructs the prompt and the target AI tool does the work.
 
 **Depth scale** (1-5) — Controls how thorough each step's output is, from "focus on the core deliverable" (1) to "explore all angles, tradeoffs, and edge cases" (5). Depth resolves with 4-level precedence: CLI flag > step override > custom default > preset default.
 
-**Multi-model validation** — At depth 4-5, all 19 review and validation steps can dispatch independent reviews to Codex and/or Gemini CLIs. Two independent models catch more blind spots than one. When both CLIs are available, findings are reconciled by confidence level (both agree = high confidence, single model P0 = still actionable). Auth is verified before every dispatch (`codex login status`, `NO_BROWSER=true gemini -p "respond with ok"`). See the [Multi-Model Review](#multi-model-review) section.
+**Multi-model validation** — At depth 4-5, all 19 review and validation steps can dispatch independent reviews to Codex and/or Gemini CLIs. Two independent models catch more blind spots than one. When both CLIs are available, findings are reconciled by confidence level (both agree = high confidence, single model P0 = still actionable). When a channel is unavailable, a compensating Claude self-review pass runs in its place (labeled `[compensating: Codex-equivalent]` or `[compensating: Gemini-equivalent]`, single-source confidence). CLI commands must always run in the foreground — background execution produces empty output. See the [Multi-Model Review](#multi-model-review) section.
 
 **State management** — Pipeline progress is tracked in `.scaffold/state.json` with atomic file writes and crash recovery. An advisory lock prevents concurrent runs. Decisions are logged to an append-only `decisions.jsonl`.
 
@@ -931,12 +931,13 @@ mmr review --pr 47           ──→  Dispatches to all channels in background
                                    Agent continues working
 
 mmr status mmr-a1b2c3        ──→  Poll progress (which channels done?)
-                                   Exit code: 0=done, 1=running, 2=failed
+                                   Exit code: 0=done, 1=running, 4=failed
 
 mmr results mmr-a1b2c3       ──→  Reconcile findings across channels
+                                   Run compensating passes for unavailable channels
                                    Apply severity gate
                                    Output unified findings
-                                   Exit code: 0=passed, 1=gate failed
+                                   Exit code: 0=passed, 2=gate failed, 3=degraded
 ```
 
 **Key features:**
@@ -1381,9 +1382,10 @@ These are orthogonal to the pipeline — usable at any time, not tied to pipelin
 | `scaffold run review-code` | Run all 3 code review channels on local code before commit or push. |
 | `scaffold run review-pr` | Run all 3 code review channels (Codex CLI, Gemini CLI, Superpowers) on a PR. |
 | `scaffold run post-implementation-review` | Full 3-channel codebase review after an AI agent completes all tasks — checks requirements coverage, security, architecture alignment, and more. |
+| `scaffold run spark` | Explore and expand a raw project idea through Socratic questioning, competitive research, and innovation expansion. Produces a `docs/spark-brief.md` that feeds into `create-vision`. At depth 4+, dispatches to external models for independent research and adversarial red-teaming. |
 | `scaffold run session-analyzer` | Analyze Claude Code session logs for patterns and insights. |
 
-Use `scaffold run review-code` before commit or push when you want a local gate on the current delivery candidate. Use `scaffold run review-pr` after a GitHub PR exists.
+Use `scaffold run spark` before `create-vision` when you have a vague idea that needs sharpening. Use `scaffold run review-code` before commit or push when you want a local gate on the current delivery candidate. Use `scaffold run review-pr` after a GitHub PR exists.
 
 Run any of these via the CLI or ask the scaffold runner skill in Claude Code or Gemini.
 

package/content/knowledge/core/automated-review-tooling.md

@@ -10,194 +10,191 @@ Automated PR review leverages AI models to provide consistent, thorough code rev
 
 ## Summary
 
-### Architecture: Local CLI Review
+### Review Severity and Reconciliation
 
-The scaffold approach uses local CLI review rather than GitHub Actions:
-- **No CI secrets required** — models run locally via CLI tools
-- **Dual-model review** — run Codex and Gemini (when available) for independent perspectives
-- **Agent-managed loop** — Claude orchestrates the review-fix cycle locally
+See `review-methodology` for severity definitions (P0-P3). See `multi-model-review-dispatch` for finding reconciliation rules.
 
-Components:
-- `AGENTS.md` — reviewer instructions with project-specific rules
-- `docs/review-standards.md` — severity definitions (P0-P3) and criteria
-- `scripts/cli-pr-review.sh` — dual-model review script
-- `scripts/await-pr-review.sh` — polling script for external bot mode
+**Action thresholds:** P0/P1/P2 findings must be fixed before proceeding to the next task. P3 findings are recorded but not actioned.
 
-### Review Severity Levels
+### Degraded-Mode Behavior
 
-Consistent with the pipeline's review step severity:
-- **P0 (blocking)** — must fix before merge (security, data loss, broken functionality)
-- **P1 (important)** — should fix before merge (bugs, missing tests, performance)
-- **P2 (suggestion)** — consider fixing (style, naming, documentation)
-- **P3 (nit)** — optional (personal preference, minor optimization)
+#### Verdict Definitions
 
-### Dual-Model Review Pattern
+These are the authoritative verdict definitions. Tool files (`review-code.md`, `review-pr.md`) reference these.
 
-When both Codex CLI and Gemini CLI are available:
-1. Run both reviewers independently on the PR diff
-2. Collect findings from each
-3. Reconcile: consensus findings get higher confidence
-4. Disagreements are flagged for the implementing agent to resolve
+| Verdict | Condition |
+|---------|-----------|
+| `pass` | All configured channels ran, no unresolved P0/P1/P2 |
+| `degraded-pass` | Channels skipped, compensated, or have non-full coverage (e.g., partial timeout), no unresolved P0/P1/P2 |
+| `blocked` | Unresolved P0/P1/P2 after 3 fix rounds |
+| `needs-user-decision` | Contradictions or unresolvable findings |
 
-### Integration with PR Workflow
+**Verdict precedence:** `needs-user-decision` > `blocked` > `degraded-pass` > `pass`. When multiple conditions apply, the higher-precedence verdict wins.
 
-The review step integrates into the standard PR flow:
-1. Agent creates PR
-2. Agent runs `scripts/cli-pr-review.sh` (or review runs automatically)
-3. Review findings are posted as PR comments or written to a local file
-4. Agent addresses P0/P1/P2 findings, pushes fixes
-5. Re-review until no P0/P1/P2 findings remain
-6. PR is ready for merge
+**Both external channels missing:** Maximum achievable verdict is `degraded-pass` — never `pass`. Review summary must note: "All findings are single-model (Claude only). External validation was unavailable."
 
-## Deep Guidance
+#### Status Model
 
-### AGENTS.md Structure
+`compensating` is a **coverage label** applied to a channel's output, not a replacement for the root-cause status. Each channel retains its root-cause status (`not_installed`, `auth_failed`, `auth_timeout`, `failed`) AND gains a coverage label (`compensating (X-equivalent)`) when a compensating pass ran. The fix cycle uses the **root-cause status** to decide whether to retry (never retry `not_installed`, `auth_failed`, `auth_timeout`). The report uses the **coverage label** to show the reader what ran.
 
-The `AGENTS.md` file provides reviewer instructions:
+#### Compensating Passes
 
-```markdown
-# Code Review Instructions
+When an external channel (Codex or Gemini) is unavailable, run a compensating Claude self-review pass:
 
-## Project Context
-[Brief description of what this project does]
+- Same prompt structure as the missing channel, executed as a Claude self-review pass.
+- Labeled `[compensating: Codex-equivalent]` or `[compensating: Gemini-equivalent]` in the review summary.
+- Missing Codex → focus on implementation correctness, security, API contracts.
+- Missing Gemini → focus on architectural patterns, design reasoning, broad context.
+- Missing both → two compensating passes (one per missing channel's strength area).
+- Compensating-pass findings are **single-source confidence** — they do NOT raise to high confidence even if they agree with another channel's findings.
+- Normal mandatory-fix thresholds apply: P0/P1/P2 findings from compensating passes still require fixing.
 
-## Review Focus Areas
-- Security: [project-specific security concerns]
-- Performance: [known hot paths or constraints]
-- Testing: [coverage requirements, test patterns]
+**Superpowers channel:** No compensating pass needed — Superpowers is a Claude subagent and is always available. If the Superpowers plugin is not installed, run available external CLIs and warn the user that review coverage is reduced.
 
-## Coding Standards Reference
-See docs/coding-standards.md for:
-- Naming conventions
-- Error handling patterns
-- Logging standards
+#### Foreground-Only Execution
 
-## Known Patterns
-[Project-specific patterns reviewers should enforce]
+Always run Codex and Gemini CLI commands as foreground Bash calls. Never use `run_in_background`, `&`, or `nohup`. Background execution produces empty or truncated output from Codex and Gemini CLIs. Multiple foreground calls can still run in parallel if the tool runner supports parallel tool invocations.
 
-## Out of Scope
-[Things reviewers should NOT flag]
-```
+This constraint is intentionally duplicated from `multi-model-review-dispatch`. Knowledge entries are injected independently by the assembly engine — an agent may receive this entry without `multi-model-review-dispatch`, so both need the constraint.
+
+## Deep Guidance
+
+### Finding Reconciliation
+
+After all channels complete (including compensating passes), reconcile findings using the rules in `multi-model-review-dispatch`. This orchestration entry triggers reconciliation; the dispatch entry defines how to perform it.
 
-### CLI Review Script Pattern
+Reconciliation normalizes findings from all channels (real and compensating) to a common schema, then matches findings across channels by location and category. The purpose is to detect when multiple independent channels agree on a finding (raising confidence) and to surface contradictions that require human judgment. A finding reported by Codex alone has lower confidence than the same finding reported by both Codex and Gemini.
 
-The `cli-pr-review.sh` script follows this structure:
+The reconciliation output is a deduplicated list of findings with confidence scores. High-confidence findings (agreed by 2+ real channels) are actionable without further discussion. Low-confidence findings (single-source, or from compensating passes) still require action at P0/P1/P2 but should be noted as lower-confidence in the review summary.
+
+Findings that appear in all three channels (Codex, Gemini, Superpowers) are considered maximum-confidence and should be surfaced first in the review summary. Findings that appear in only one channel should include the channel name in the finding description to help the developer assess confidence independently.
 
 ```bash
-#!/usr/bin/env bash
-set -euo pipefail
-
-# 1. Get the PR diff
-diff=$(gh pr diff "$PR_NUMBER")
-
-# 2. Run Codex review (if available)
-if command -v codex &>/dev/null; then
-  codex_findings=$(echo "$diff" | codex review --context AGENTS.md)
-fi
-
-# 3. Run Gemini review (if available)
-if command -v gemini &>/dev/null; then
-  gemini_findings=$(echo "$diff" | gemini review --context AGENTS.md)
-fi
-
-# 4. Reconcile findings
-# - Findings from both models: HIGH confidence
-# - Findings from one model: MEDIUM confidence
-# - Contradictions: flagged for human review
+# Orchestration reconciliation workflow
+# 1. Collect findings from all channels (real + compensating)
+# 2. Normalize to common schema (severity, category, location, description)
+# 3. Match findings across channels by location + category
+# 4. Apply consensus rules from multi-model-review-dispatch
+# 5. Produce reconciled findings list with confidence scores
 ```
 
-### Review Standards Document
+### Channel Dispatch Pattern and Orchestration
 
-`docs/review-standards.md` should define:
-- Severity levels with concrete examples per project
-- What constitutes a blocking review (P0/P1/P2 threshold)
-- Auto-approve criteria (when review can be skipped)
-- Review SLA (how long before auto-approve kicks in)
+Each external channel (Codex, Gemini) follows the same dispatch pattern: check installation, check auth, then dispatch as a foreground call. If any step fails, record the root-cause status, queue a compensating pass, and continue to the next channel. The Superpowers channel is always available as a Claude subagent and does not require installation or auth checks.
 
-### Fallback When Models Unavailable
+```bash
+# Channel dispatch pattern
+# For each external channel (Codex, Gemini):
+#   1. command -v <tool> >/dev/null 2>&1 || { status=not_installed; queue_compensating; continue; }
+#   2. <auth_check> || { status=auth_failed; queue_compensating; continue; }
+#   3. <dispatch_foreground> || { status=failed; queue_compensating; continue; }
+# For Superpowers: dispatch subagent (always available)
+# After all: run queued compensating passes → reconcile → verdict
+```
+
+After all channels and compensating passes complete, run the reconciliation workflow above and apply the verdict decision flow. Channel results and compensating-pass labels must be preserved in the review output for auditability — do not collapse or omit them even when findings are empty.
+
+### Degraded-Mode Worked Example
 
-If neither Codex nor Gemini CLI is available:
-1. Claude performs an enhanced self-review of the diff
-2. Focus on the AGENTS.md review criteria
-3. Apply the same severity classification
-4. Document that the review was single-model
+When Codex is unavailable (not installed or auth failure), the orchestration proceeds as follows:
 
-### Updating Review Standards Over Time
+1. The installation check (`command -v codex`) fails. Codex channel status is set to `not_installed`.
+2. A compensating Codex-equivalent pass is queued: a Claude self-review focused on implementation correctness, security, and API contracts.
+3. Gemini and Superpowers channels run normally.
+4. The compensating pass runs, producing findings labeled `[compensating: Codex-equivalent]`.
+5. Reconciliation merges findings from all three sources (Gemini, Superpowers, compensating-Codex).
+6. Maximum achievable verdict is `degraded-pass` because a real channel was absent.
+7. The review summary notes: "Codex channel: not_installed (compensating: Codex-equivalent pass ran)."
 
-As the project evolves:
-- Add new review focus areas when new patterns emerge
-- Remove rules that linters now enforce automatically
-- Update AGENTS.md when architecture changes
-- Track false-positive rates and adjust thresholds
+**Fix-cycle channel rule:** Only re-run channels that originally completed or ran as compensating passes. `failed` channels are covered by their compensating pass and are not retried during fix rounds. Never retry a channel with status `not_installed`, `auth_failed`, or `auth_timeout` — these indicate persistent environment conditions that will not resolve between fix rounds.
 
-### Review Finding Reconciliation
+### Verdict Decision Flow
 
-When running dual-model review, reconcile findings systematically:
+Apply the following evaluation order to determine the final verdict. The first matching condition wins; all subsequent conditions are skipped.
 
 ```
-Finding Classification:
-┌─────────────────┬──────────┬──────────┬───────────────────┐
-│                 │ Codex    │ Gemini   │ Action            │
-├─────────────────┼──────────┼──────────┼───────────────────┤
-│ Same issue      │ Found    │ Found    │ HIGH confidence   │
-│ Unique finding  │ Found    │ -        │ MEDIUM confidence │
-│ Unique finding  │ -        │ Found    │ MEDIUM confidence │
-│ Contradiction   │ Fix X    │ Keep X   │ Flag for agent    │
-└─────────────────┴──────────┴──────────┴───────────────────┘
+Verdict evaluation order:
+1. Any contradictions or unresolvable findings? → needs-user-decision
+2. Any unresolved P0/P1/P2 after 3 fix rounds? → blocked
+3. Any channel not at full coverage? → degraded-pass
+4. All channels completed, no unresolved P0/P1/P2? → pass
 ```
 
-HIGH confidence findings are always addressed. MEDIUM confidence findings are addressed if P0/P1/P2. Contradictions require the implementing agent to make a judgment call and document the reasoning.
+A "contradiction" exists when two channels report opposite conclusions about the same code location — for example, Codex flags a function as insecure while Gemini explicitly approves it. Contradictions cannot be resolved by the agent alone and must be surfaced to the user.
+
+A channel is "not at full coverage" when: it ran as a compensating pass instead of a real tool, it timed out partially, or the Superpowers plugin is not installed and available channels do not cover the full diff.
+
+**Verdict precedence reminder:** `needs-user-decision` > `blocked` > `degraded-pass` > `pass`. If multiple conditions apply simultaneously (for example, both a contradiction and an unresolved P0 exist), the higher-precedence verdict wins.
+
+The verdict is always computed after all fix rounds are exhausted — do not emit a partial verdict mid-cycle. If a fix round resolves all P0/P1/P2 findings and no contradictions remain, the verdict upgrades from `blocked` to `pass` or `degraded-pass` depending on channel coverage. This upgrade must be verified explicitly by re-running the reconciliation step after each fix round, not assumed from the fact that fixes were applied.
 
 ### Security-Focused Review Checklist
 
 Every automated review should check:
-- No secrets or credentials in the diff (API keys, passwords, tokens)
-- No `eval()` or equivalent unsafe operations introduced
-- SQL queries use parameterized queries (no string concatenation)
-- User input is validated before use
-- Authentication/authorization checks are present on new endpoints
-- Dependencies added are from trusted sources with known versions
+- No secrets or credentials in the diff (API keys, passwords, tokens, private keys)
+- No `eval()` or equivalent unsafe operations introduced (dynamic code execution, shell injection)
+- SQL queries use parameterized queries — no string concatenation with user input
+- User input is validated and sanitized before use in queries, commands, or output
+- Authentication/authorization checks are present on all new endpoints and operations
+- Dependencies added are from trusted sources with known, pinned versions
+- No new global state or singletons that could cause cross-request data leaks
+- Error messages do not expose internal paths, stack traces, or sensitive system details
+- File system operations use safe path handling (no path traversal vulnerabilities)
+- Cryptographic operations use approved algorithms and key lengths
+
+When reviewing diffs that touch authentication, authorization, or data handling, elevate any security-related finding by one severity level. A finding that would normally be P2 (recommended) becomes P1 (required) in security-sensitive code paths. This conservative stance reflects the asymmetric cost of security failures versus the cost of over-caution during review.
 
 ### Performance Review Patterns
 
-Look for these performance anti-patterns:
-- N+1 queries (loop with individual DB calls)
-- Missing pagination on list endpoints
-- Synchronous operations that should be async
-- Large objects passed by value instead of reference
-- Missing caching for expensive computations
-- Unbounded growth in arrays or maps
+Look for these performance anti-patterns in the diff:
+- N+1 queries (loop containing individual DB calls — use batch queries or eager loading)
+- Missing pagination on list endpoints (unbounded result sets)
+- Synchronous operations that should be async (blocking I/O in hot paths)
+- Large objects passed by value instead of reference (unnecessary deep copies)
+- Missing caching for expensive computations that are called repeatedly
+- Unbounded growth in arrays or maps (no eviction, no size limits)
+- Missing indexes on columns used in WHERE clauses of new queries
+- Eager loading where lazy loading would suffice (over-fetching)
+- Missing connection pooling or connection reuse for external services
 
-### Integration with CLAUDE.md
+### Common False Positives
 
-The workflow-audit step should add review commands to CLAUDE.md:
+Track and suppress recurring false positives to reduce noise in future reviews:
+- Test files flagged for "hardcoded values" (test fixtures and expected values are intentional)
+- Migration files flagged for "raw SQL" (migrations must use raw SQL for schema changes)
+- Generated files flagged for style issues (generated code follows its own generator's conventions)
+- Intentional use of `any` types in TypeScript adapter layers or third-party type overrides
+- Deliberate `eslint-disable` comments that are already justified in surrounding context
+- Seed data files flagged for hardcoded credentials (test-only, not production)
 
-```markdown
-## Code Review
-| Command | Purpose |
-|---------|---------|
-| `scripts/cli-pr-review.sh <PR#>` | Run dual-model review |
-| `scripts/await-pr-review.sh <PR#>` | Poll for external review |
-```
+Add suppressions to AGENTS.md under "Out of Scope" to prevent repeated false findings across review cycles.
 
-This ensures agents always know how to trigger reviews without consulting separate docs.
+### Review Metrics and Continuous Improvement
 
-### Common False Positives
+Track these metrics over time to improve review quality and calibrate thresholds:
 
-Track and suppress recurring false positives:
-- Test files flagged for "hardcoded values" (test fixtures are intentional)
-- Migration files flagged for "raw SQL" (migrations must use raw SQL)
-- Generated files flagged for style issues (generated code has its own conventions)
+| Metric | Definition | Use |
+|--------|------------|-----|
+| False positive rate | Findings dismissed without action / total findings | Calibrate severity thresholds |
+| Escape rate | Bugs reaching production despite review / total bugs | Identify coverage gaps |
+| Time to resolve | Average time between finding logged and fix merged | Identify bottlenecks |
+| Coverage | PRs receiving automated review / total PRs merged | Track adoption |
+| Model agreement rate | Findings agreed by 2+ channels / total findings | Tune reconciliation rules |
+| Compensating-pass rate | Reviews using compensating passes / total reviews | Track environment health |
 
-Add suppressions to AGENTS.md under "Out of Scope" to prevent repeated false findings.
+Use the false positive rate to determine whether a severity category is over-triggering. Use the escape rate to determine whether the review is missing entire classes of bugs. Use the compensating-pass rate to identify when the review environment needs maintenance (expired auth tokens, broken CLI installs).
 
-### Review Metrics and Continuous Improvement
+Log metric snapshots in AGENTS.md after each major project milestone. A declining model agreement rate over time suggests either that the review prompts are drifting in quality or that the codebase is accumulating technical debt in areas where models diverge. A rising escape rate despite consistent review coverage is a signal to revisit the severity thresholds or the focus areas in the review prompts.
+
+### Fallback When Models Unavailable
+
+When external CLIs are unavailable, the degraded-mode behavior defined in the Summary section applies. To summarize the operational steps:
 
-Track these metrics over time to improve review quality:
-- **False positive rate** — findings that are dismissed without action
-- **Escape rate** — bugs that reach production despite review
-- **Time to resolve** — average time between finding and fix
-- **Coverage** — percentage of PRs that receive automated review
-- **Model agreement rate** — how often Codex and Gemini agree
+1. For each unavailable external channel, queue a compensating Claude self-review pass focused on that channel's strength area.
+2. Label findings as `[compensating: Codex-equivalent]` or `[compensating: Gemini-equivalent]`.
+3. Treat compensating findings as single-source confidence — they do not raise to high confidence even when they agree with another channel.
+4. Maximum verdict is `degraded-pass` when any channel ran as compensating instead of real.
+5. When both external channels are unavailable, note "All findings are single-model (Claude only). External validation was unavailable." in the review summary.
+6. Never silently drop unavailable channels — always record the channel status and compensating coverage label in the review output.
 
-Use these metrics to calibrate severity thresholds and update AGENTS.md focus areas.
+**Superpowers channel exception:** Superpowers is a Claude subagent and requires no external CLI or auth. It is always available as long as the Superpowers plugin is installed in the Claude Code environment. If the plugin is not installed, run available external CLIs and warn the user that review coverage is reduced — but do not run a compensating pass for Superpowers (the compensating-pass mechanism only applies to external CLIs that have an installation/auth gate).

package/content/knowledge/core/multi-model-research-dispatch.md

@@ -0,0 +1,219 @@
+---
+name: multi-model-research-dispatch
+description: Patterns for dispatching research and adversarial challenge to external AI models (Codex, Gemini) with reconciliation rules and single-model fallback
+topics: [multi-model, research, competitive-analysis, red-team, codex, gemini, dispatch, reconciliation]
+---
+
+# Multi-Model Research Dispatch
+
+At higher methodology depths (4+), idea exploration and adversarial challenge benefit from independent research by external AI models. This entry provides dispatch patterns, reconciliation rules, and fallback strategies for research and red-team workflows.
+
+## Summary
+
+### When to Dispatch
+| Depth | Research Dispatch | Challenge Dispatch |
+|-------|-------------------|-------------------|
+| 1-3 | Skip | Skip |
+| 4 | 1 external model | 1 external model |
+| 5 | Multi-model with reconciliation | Multi-model with reconciliation |
+
+### Graceful Fallback Chain
+1. Check if external CLI is available (`command -v codex`, `command -v gemini`)
+2. If not installed, skip that model silently — note in Session Metadata
+3. If installed, check auth (`codex login status`, `NO_BROWSER=true gemini -p "respond with ok" -o json`)
+4. If auth fails, surface loudly to the user with `!` recovery command — do NOT silently skip
+5. If auth succeeds, dispatch with timeout
+6. If no external models available, fall back to primary model with distinct framing prompts
+7. Never block the session waiting for unavailable tools
+
+### Reconciliation Rules
+- **2+ models agree** on the same finding = **consensus** — high confidence, present as validated
+- **Models disagree** = **divergent** — present ALL perspectives including minority views. Do NOT suppress the minority. A 2-1 split where the lone dissent flags a real risk is more valuable than a comfortable consensus.
+- **Single model** (fallback) = skip reconciliation labels. Present findings directly without consensus/divergent framing.
+
+## Deep Guidance
+
+### CLI Availability Check
+
+Before dispatching, verify CLI tools are installed and authenticated:
+
+### Foreground-Only Execution
+
+When an AI agent dispatches research or challenge prompts via a tool runner, always run commands in the foreground. Background execution (`run_in_background`, `&`, `nohup`) produces empty or truncated output from Codex and Gemini CLIs. Multiple foreground calls can still run in parallel if the tool runner supports parallel tool invocations.
+
+```bash
+# Codex CLI — step 1: check installed
+command -v codex >/dev/null 2>&1 || { echo "Codex not installed — skipping"; exit 0; }
+# step 2: check auth
+codex login status 2>/dev/null
+# Exit 0 = ready. Non-zero = auth failure (surface to user).
+
+# Gemini CLI — step 1: check installed
+command -v gemini >/dev/null 2>&1 || { echo "Gemini not installed — skipping"; exit 0; }
+# step 2: check auth
+NO_BROWSER=true gemini -p "respond with ok" -o json 2>&1
+# Check for "ok" in response. Exit 41 = auth failure (surface to user).
+```
+
+Two distinct failure modes:
+- **Not installed** (`command -v` fails): skip silently, note in Session Metadata
+- **Auth failed** (non-zero after install check): surface loudly — tell the user which tool failed and how to fix it:
+  - Codex: "Codex auth expired — run `! codex login` to re-authenticate"
+  - Gemini: "Gemini auth expired — run `! gemini -p \"hello\"` to re-authenticate"
+
+Auth failures are NOT silent fallbacks — surface them explicitly.
+
+### Timeout Handling
+
+| Dispatch type | Timeout |
+|---------------|---------|
+| Research dispatch (idea summary + questions) | 120 seconds |
+| Challenge dispatch (full brief review) | 180 seconds |
+
+If a dispatch times out:
+- Use whatever partial response was received (if parseable)
+- Note the timeout in Session Metadata
+- Do NOT retry — proceed with available data
+
+### Research Dispatch Mode
+
+**When**: Phase 2 at depth 4-5.
+
+**Prompt template for external model:**
+
+```
+You are conducting independent competitive research for a product idea.
+
+IDEA: [1-2 sentence summary of the idea from Phase 1]
+
+RESEARCH QUESTIONS:
+1. What are the direct competitors in this space? For each, note what they do well and where they fall short.
+2. What indirect alternatives exist — different approaches to the same problem?
+3. How do users currently cope without a dedicated solution?
+4. What recent market signals exist — funding rounds, product launches, shutdowns, regulatory changes?
+5. What adjacent markets or analogous systems could inform this idea?
+
+Be thorough and honest. Acknowledge competitor strengths — do not dismiss them.
+Respond in structured markdown with one section per question.
+```
+
+**Execution:**
+
+```bash
+# Codex
+codex exec --skip-git-repo-check -s read-only --ephemeral "RESEARCH_PROMPT" 2>&1
+
+# Gemini
+NO_BROWSER=true gemini -p "RESEARCH_PROMPT" --output-format json --approval-mode yolo 2>/dev/null
+```
+
+**Processing results:**
+- Parse the response as structured markdown
+- Extract key findings per research question
+- If multi-model (depth 5), run reconciliation (see below)
+- Present findings to the user conversationally, not as raw output
+
+### Challenge Dispatch Mode (Red-Team)
+
+**When**: Phase 6 at depth 4-5.
+
+**Prompt template for external model:**
+
+```
+You are an adversarial reviewer stress-testing a product idea brief.
+Your job is to find weaknesses, challenge assumptions, and surface missed opportunities.
+
+SPARK BRIEF:
+[Full content of the draft spark-brief.md]
+
+CHALLENGE INSTRUCTIONS:
+1. For each section, identify the weakest assumption and explain why it might be wrong.
+2. What competitors or market dynamics does the brief underestimate?
+3. What technical feasibility risks are glossed over?
+4. What user segments or use cases are missing?
+5. If you could only flag ONE critical risk, what would it be?
+
+Be constructive but ruthless. The goal is to strengthen the idea, not validate it.
+Respond in structured markdown with one section per challenge area.
+```
+
+**Processing results:**
+- Parse challenges from response
+- Present each challenge to the user one at a time
+- For each challenge, ask: "Accept (update the brief), dismiss (explain why it's not applicable), or defer (note as open question)?"
+- Track dispositions and update the brief accordingly
+
+### Single-Model Fallback
+
+When no external models are available, the primary model simulates multiple perspectives:
+
+**Perspective 1 — Venture Capitalist**: "Analyze this idea as a VC evaluating a pitch. What's the market size? What's the defensibility? What are the unit economics? Would you invest?"
+
+**Perspective 2 — Competitor's Product Lead**: "You're the product lead at [biggest competitor]. You just learned about this idea. What's your reaction? What would you do to defend your position? What aspects worry you?"
+
+**Perspective 3 — Skeptical End User**: "You're a potential user who has tried and abandoned 3 similar products. What would make you try this one? What would make you abandon it after a week? What's the one thing that would keep you?"
+
+Run each perspective as a separate reasoning pass. Synthesize the three viewpoints into findings the user can act on.
+
+### Model Selection
+
+| Task | Recommended model | Rationale |
+|------|-------------------|-----------|
+| Research dispatch | Either Codex or Gemini | Both capable of web-informed reasoning |
+| Challenge dispatch | Either Codex or Gemini | Adversarial analysis is model-agnostic |
+| Depth 4 (1 model) | Prefer Gemini (Google search built-in) | Strongest for competitive research |
+| Depth 5 (multi) | Both Codex AND Gemini | Diverse perspectives from different architectures |
+
+### Reconciliation Process (Depth 5)
+
+When two or more models return research findings, reconcile them:
+
+1. **Extract findings**: Parse each model's response into discrete findings (one competitor, one market signal, one risk = one finding).
+2. **Match findings**: Compare findings across models. Two findings match if they reference the same entity (competitor, trend, risk) even if the wording differs.
+3. **Classify each finding**:
+   - **Consensus**: 2+ models independently identified the same finding. High confidence.
+   - **Divergent**: Models disagree about the same entity (e.g., one says competitor X is strong, another says X is weak). Present both perspectives with reasoning.
+   - **Unique**: Only one model surfaced this finding. Not necessarily wrong — may be the most valuable insight. Present it without discounting.
+4. **Synthesize for the user**: Present findings grouped by classification. Lead with consensus (highest confidence), then unique (potential insights), then divergent (needs user judgment).
+5. **Never suppress minority views**: A lone model flagging a risk that others missed may be the most important finding in the entire research pass.
+
+### Quality Gates
+
+Before presenting research findings to the user, verify:
+
+- At least 2 competitors or alternatives identified (even at depth 4 with single model)
+- Each competitor has both a strength and a weakness documented
+- The "do nothing" option is addressed (how users cope without any tool)
+- Market timing signals are present (why now?)
+- If multi-model: reconciliation labels (consensus/divergent/unique) are applied
+
+### Common Anti-Patterns
+
+| Anti-pattern | Problem | Fix |
+|-------------|---------|-----|
+| Dismissing competitors | "They're not really competition" — every alternative is competition | Acknowledge strengths honestly |
+| Echo chamber | Both models agree because both drew from the same training data | Look for unique findings, not just consensus |
+| Recency bias | Focusing only on recent launches, ignoring established players | Include both established and emerging competitors |
+| Feature-list comparison | Comparing feature lists instead of positioning | Compare on audience, value prop, and differentiation |
+| Silent fallback | External model fails, no mention in output | Always note which models were used and any failures |
+| Over-synthesis | Merging distinct findings into one summary, losing nuance | Preserve individual findings before synthesizing |
+
+### Output Format
+
+When presenting research findings to the user, structure them as:
+
+**Competitive Landscape:**
+- [Competitor 1]: Strengths — [specifics]. Weaknesses — [specifics]. Why users choose them — [specifics].
+- [Competitor 2]: ...
+- "Do nothing" option: How users cope today — [specifics]. Why it's insufficient — [specifics].
+
+**Market Signals:**
+- [Signal 1]: [What happened, when, why it matters for this idea]
+- [Signal 2]: ...
+
+**Expansion Opportunities** (from adjacent market research):
+- [Opportunity 1]: [What it is, why it's relevant, how it connects]
+
+**Red-Team Challenges** (from adversarial review):
+- [Challenge 1]: [Weakness identified, why it matters, recommended action]
+  - Disposition: [accept/dismiss/defer — tracked after user response]