@cluesmith/codev 3.2.4 → 3.3.0

package/skeleton/protocols/research/protocol.md

@@ -1,169 +1,44 @@
 # RESEARCH Protocol
 
-## Overview
+Scope → Investigate → Synthesize → Critique. Multiple models investigate the same question
+independently, their findings are synthesized, and the synthesis is adversarially critiqued
+before it is trusted. **The state machine below is authoritative on which models actually
+run** — the set can be smaller than the ideal when a provider's consult lane is unavailable
+(it is currently `["codex"]` for investigation, the agy/Gemini and hermes lanes being degraded).
 
-Multi-agent research with 3-way investigation, synthesis, and critique. Three AI models independently investigate a question, their findings are synthesized into a single report, and then all three models critique the synthesis for gaps, errors, and bias.
+Use it for competitive and technology analysis, "state of X" questions, and architectural
+decision support in an unfamiliar domain — cases where a single model's confident answer is
+exactly the failure mode.
 
-**Core Principle**: Triangulate. No single model's knowledge is authoritative. Consensus across models is more reliable than any individual output.
+## The state machine
 
-## When to Use
-
-**Use for**: Competitive analysis, technology evaluation, market research, architectural decision support, "what's the state of X?" questions, exploring unfamiliar domains.
-
-**Skip for**: Implementation work (use SPIR/ASPIR), quick questions (just ask), experiments (use EXPERIMENT), known-answer lookups (just search).
+```json
+{{> protocols/research/protocol.json}}
+```
 
 ## Output
 
-All research artifacts go to `codev/research/`. The final deliverable is a single synthesis report at `codev/research/<topic>.md`.
+`codev/research/<topic>.md` — the report, with its sources and its disagreements preserved.
 
 ## Phases
 
-### Phase 1: Scope
-
-**Purpose**: Make sure we're asking the right question before spending 3 models' worth of compute on answering it.
-
-The builder:
-1. Reads the architect's research request
-2. Clarifies the question — what specifically are we trying to learn?
-3. Defines the scope — what's in, what's out, what depth is needed
-4. Defines acceptance criteria — what does a good answer look like?
-5. Writes a **research brief** (`codev/research/<topic>-brief.md`) with:
-   - The precise question(s)
-   - Scope boundaries
-   - **Required targets** (when applicable — not all research questions have them). When the user names specific projects, products, or systems, those are exemplars of a CLASS, not an exhaustive list. The brief should:
-     - List the named targets as required coverage (each gets a dedicated section)
-     - Identify the CLASS they represent (e.g., "open-source always-on agent frameworks")
-     - Instruct investigators to find OTHER members of that class the user didn't name — discovering what the user SHOULD be thinking about is often the most valuable part of the research
-     - If an investigator cannot find information about a required target, they must say so explicitly — not silently skip it
-   - **Optional context** — additional sources that may be useful but are not required
-   - What a useful answer looks like
-   - Suggested sources or angles for the investigators
-6. Sends the brief to the architect for approval
-
-**Gate**: `scope-approval` — the architect confirms the question is correctly scoped before the 3-way investigation begins. This prevents wasting compute on a badly-framed question.
-
-### Phase 2: Investigate (3-way parallel)
-
-**Purpose**: Get three independent perspectives on the question.
-
-The builder dispatches the research brief to three models (Gemini, Codex, Claude) via `consult`. Each model:
-1. Receives the scoped research brief
-2. Independently investigates using web search, its training knowledge, and reasoning
-3. Produces a standalone investigation report with:
-   - **A dedicated section for each required target** from the brief. Every required target gets its own heading with specific findings — not mentioned in passing, not substituted with an easier target. If a required target yields no findings, the section must say "No information found" rather than being omitted.
-   - Findings (with sources where possible)
-   - Confidence levels on key claims
-   - Gaps it couldn't fill
-   - Surprises or things that contradicted expectations
-
-The investigations run in **parallel** — each model works independently without seeing the others' output. This prevents anchoring bias.
-
-Investigation reports are saved to:
-- `codev/research/<topic>-gemini.md`
-- `codev/research/<topic>-codex.md`
-- `codev/research/<topic>-claude.md`
-
-### Phase 3: Synthesize
-
-**Purpose**: Merge three independent reports into one coherent document.
-
-The builder:
-1. Reads all three investigation reports
-2. Identifies **consensus** — what all three agree on (highest confidence)
-3. Identifies **disagreements** — where models contradict each other
-4. Resolves conflicts — picks the best-supported position, notes the disagreement
-5. Identifies **unique contributions** — things only one model found that the others missed
-6. Writes the **synthesis report** (`codev/research/<topic>.md`) with:
-   - **Scope summary** — a short section (before the executive summary) restating the research question, required targets, and scope boundaries from the brief. A reader should understand what was asked without needing to read the brief separately.
-   - Executive summary
-   - Findings (organized by topic, not by model)
-   - Confidence annotations (consensus vs. single-source)
-   - Gaps and limitations
-   - Recommendations (if the research brief asked for them)
-
-The synthesis is written as a **standalone document** — a reader should never need to reference the individual investigation reports. Those are kept as appendices for traceability.
-
-### Phase 4: Critique (3-way review)
-
-**Purpose**: Pressure-test the synthesis for gaps, errors, and bias.
+**Scope** — write the research brief: the question, why it matters, what would count as an
+answer, and what is out of scope. Gated by `scope-approval`, because a badly framed question
+wastes the investigation's compute and produces a confident answer to the wrong thing.
 
-The builder dispatches the synthesis report back to all three models for critique. Each model:
-1. Reads the synthesis
-2. **Checks coverage against the brief** — does every required target from the research brief have dedicated coverage in the synthesis? Lists any required targets that were named in the brief but have zero or minimal coverage. This is the #1 critique check.
-3. Checks for factual errors or unsupported claims
-4. Identifies gaps — important aspects the synthesis missed
-5. Flags potential bias — did the synthesis over-weight one model's perspective?
-6. Suggests specific improvements
+**Investigate** — the configured models (see the state machine) work the question
+**independently**. Independence is the point: cross-contaminated investigations converge on a
+shared error, so where more than one model is available each researches without seeing the others.
 
-The builder then:
-1. Incorporates valid critique
-2. Documents rejected critique with rationale
-3. Finalizes the report
-4. Commits to `codev/research/<topic>.md`
+**Synthesize** — merge findings and, critically, **preserve disagreement**. Where models
+diverge, say so and say why; a synthesis that smooths over conflict has destroyed the signal
+that made a multi-model investigation worth running.
 
-## File Structure
+**Critique** — adversarial pass over the synthesis. What is asserted without a source? What
+would change the conclusion? Reaching `research-complete` means the report survived this, not
+that it was written.
 
-Only the brief and final report are checked in. Individual investigation reports and full critique outputs are working artifacts — useful during the process but not committed to the repo.
-
-```
-codev/research/
-├── <topic>-brief.md              # Phase 1: scoped research question (checked in)
-└── <topic>.md                    # Phase 3+4: final synthesis (the deliverable, checked in)
-```
-
-The final report includes:
-- A **"Disagreements and resolution"** section documenting where the three investigators disagreed and how the synthesis resolved each disagreement
-- A **"Changes from critique"** section summarizing what the critique phase changed (not the full critique — just what was added, removed, or corrected and why)
-
-Individual investigation reports (`<topic>-gemini.md`, `<topic>-codex.md`, `<topic>-claude.md`) and raw critique outputs are kept locally during the research process but NOT committed. The final report is the deliverable; the process artifacts are disposable.
-
-## Best Practices
-
-### Scoping
-- A good research question is specific enough to answer in 1500-3000 words per model
-- "What's the state of X?" is too broad — "What are the top 5 players in X, their strengths/weaknesses, and the structural gaps?" is better
-- Include the "so what" — why are we researching this? What decision does it inform?
-
-### Investigation
-- Tell each model to cite sources where possible
-- Tell each model to be candid about uncertainty — "I don't know" is better than confabulation
-- Tell each model to note surprises — the most valuable findings are often the unexpected ones
-
-### Synthesis
-- Organize by topic, not by model ("here's what we found about X" not "here's what Gemini said")
-- Weight consensus over single-model claims
-- Don't smooth over disagreements — note them explicitly
-- Keep the synthesis shorter than the sum of the investigations
-
-### Critique
-- Critiquers should focus on gaps and errors, not style
-- A critique that says "add more about X" is useful; "rewrite the intro" is not
-- The builder should reject critique that's outside the original scope
-
-## Integration with Other Protocols
-
-### Research → SPIR
-When research informs a feature decision:
-1. Reference the research report in the spec
-2. Link specific findings as evidence for design choices
-
-### Research → EXPERIMENT
-When research identifies something worth testing:
-1. Create an experiment to validate the research finding
-2. Reference the research report as motivation
-
-## Git Workflow
-
-### Commits
-```
-[Research: topic] Scoped research brief
-[Research: topic] 3-way investigation complete
-[Research: topic] Synthesis report
-[Research: topic] Final report (post-critique)
-```
+## Reporting standard
 
-### What to Commit
-- All investigation reports (for traceability)
-- The final synthesis (the deliverable)
-- The critique rebuttals (for process transparency)
-- Do NOT commit raw web search results or intermediate notes
+Cite sources for factual claims and mark inference as inference. A research report that cannot
+be checked is an opinion with footnotes.

package/skeleton/protocols/spike/builder-prompt.md

@@ -1,68 +1,50 @@
 # {{protocol_name}} Builder ({{mode}} mode)
 
-You are executing a time-boxed technical feasibility spike.
+You are implementing {{input_description}}.
 
 {{#if mode_soft}}
 ## Mode: SOFT
-You are running in SOFT mode. This means:
-- You follow the SPIKE protocol yourself (no porch orchestration)
-- Stay focused on the question — don't gold-plate
-- The findings document is your deliverable, not the code
-{{/if}}
-
-## Protocol
-Follow the SPIKE protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**.
 
-{{#if task}}
-## Spike Question
-{{task_text}}
+You follow the protocol yourself; the architect verifies compliance.
 {{/if}}
 
-## Recommended Workflow
+{{#if mode_strict}}
+## Mode: STRICT
 
-Follow this 3-step workflow. You can skip or reorder steps as the investigation demands.
+Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never
+hand-edit `status.yaml` — only porch commands modify project state.
+{{/if}}
 
-### 1. Research
-- Read documentation, examine existing code, search for prior art
-- Identify constraints, dependencies, and potential blockers
-- Understand the problem space before writing any code
+## Protocol
 
-### 2. Iterate
-- Build minimal proof-of-concept code to test approaches
-- Focus on answering the feasibility question, not building production code
-- POC code doesn't need tests or polish
-- **Skip this step** if the answer is clear from research alone
+The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not
+need to fetch it.
 
-### 3. Findings
-- Write findings to `codev/spikes/<id>-<name>.md` using the template
-- Provide a clear feasibility verdict: Feasible / Not Feasible / Feasible with Caveats
-- Commit the findings document
-- Notify the architect: `afx send architect "Spike <id> complete. Verdict: [verdict]"`
+## Spike Question
 
-## Key Principles
+{{task_text}}
 
-- **Time-boxing**: Stay focused on the question. Don't explore tangents.
-- **Exploration over perfection**: POC code doesn't need tests or polish.
-- **Clear output**: The findings document is the deliverable, not the code.
-- **Know when to stop**: Once you can answer the feasibility question, write findings and stop. Don't keep iterating.
-- **Document failures**: "Not feasible" is a valid and valuable finding.
+## Workflow
 
-## Handling Flaky Tests
+Three steps; skip or reorder as the investigation demands.
 
-If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes):
-1. **DO NOT** edit `status.yaml` to bypass checks
-2. **DO NOT** skip porch checks or use any workaround to avoid the failure
-3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`)
-4. **DO** document each skipped flaky test in your findings under a `## Flaky Tests` section
-5. Commit the skip and continue with your work
+1. **Research** — documentation, existing code, prior art. Identify constraints, dependencies
+   and blockers before writing any code.
+2. **Iterate** — minimal proof-of-concept to test approaches. POC code needs no tests or polish;
+   it exists to answer the question. **Skip this entirely** if research already answers it.
+3. **Findings** — write `codev/spikes/<id>-<name>.md` with a clear verdict (Feasible / Not
+   Feasible / Feasible with Caveats), commit it, and notify:
+   `afx send architect "Spike <id> complete. Verdict: [verdict]"`
 
-## Getting Started
-1. Read the SPIKE protocol document
-2. Understand the question you're investigating
-3. Start with research — don't jump straight to code
+## Key Principles
 
----
+- **Time-box**: stay on the question, don't explore tangents
+- **The findings document is the deliverable, not the code**
+- **Know when to stop**: once you can answer the question, write findings and stop
+- **"Not feasible" is a valuable finding.** The failure mode is an inconclusive spike — time
+  spent, nothing recorded, question still open
 
-## Protocol Reference (full text)
+## Notifications
 
-{{protocol_reference}}
+The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR
+merged, blocked.

package/skeleton/protocols/spike/protocol.md

@@ -1,128 +1,45 @@
 # SPIKE Protocol
 
-## Overview
+A time-boxed feasibility investigation that answers one question: **can this be done, and at
+what cost?** The deliverable is findings, not shipped code.
 
-Time-boxed technical feasibility exploration. Answer "Can we do X?" and "What would it take?" before committing to a full SPIR project.
+Use it before committing to a SPIR project whose feasibility is genuinely unknown — an unfamiliar
+library, an unproven integration, a performance question that argument cannot settle.
 
-**Core Principle**: Stay focused on the question. Once you can answer it, write findings and stop.
+## The state machine
 
-## When to Use
-
-**Use for**: Quick technical feasibility investigations, proof-of-concept explorations, "can we do X?" questions, evaluating approaches before committing to SPIR
-
-**Skip for**: Production code (use SPIR), formal hypothesis testing (use EXPERIMENT), bug fixes (use BUGFIX)
-
-### Spike vs Experiment
-
-| | Spike | Experiment |
-|---|---|---|
-| **Goal** | Answer a feasibility question | Test a formal hypothesis |
-| **Structure** | Lightweight guidance | Formal phases (hypothesis/design/execute/analyze) |
-| **Output** | Findings document | Experiment notes with metrics |
-| **Rigor** | Exploration-first | Measurement-first |
-| **Time** | Short (hours) | Longer (days) |
-
-## Spawning a Spike
-
-```bash
-afx spawn --task "Can we use WebSockets for real-time updates?" --protocol spike
-afx spawn --task "What would it take to support SQLite FTS?" --protocol spike
+```json
+{{> protocols/spike/protocol.json}}
 ```
 
-Spikes are always soft mode — no porch orchestration, no gates, no consultation.
-
-## Recommended Workflow
-
-The following 3-step workflow is **guidance only** — not enforced by porch. Follow it, skip steps, or reorder as the investigation demands.
-
-### Step 1: Research
-
-- Read documentation, examine existing code, search for prior art
-- Identify constraints, dependencies, and potential blockers
-- Understand the problem space before writing any code
-- Check if someone has already investigated this (look in `codev/spikes/`)
-
-### Step 2: Iterate
-
-- Build minimal proof-of-concept code
-- Try different approaches, hit walls, pivot
-- Focus on answering the feasibility question, not building production code
-- **Skip this step** if the answer is clear from research alone
-
-### Step 3: Findings
-
-- Write the findings document at `codev/spikes/<id>-<name>.md`
-- Use the embedded template at the end of this protocol
-- Provide a clear feasibility verdict
-- Commit and notify the architect
+## Proof-of-concept code
 
-## Output
+Throwaway by design. It exists to answer the question, and it is not held to production
+standards — but it must not be quietly promoted into production later either. If the answer is
+"feasible", a SPIR project builds the real thing.
 
-Findings are stored in `codev/spikes/` using the pattern: `<id>-<descriptive-name>.md`
+## Outcomes
 
-Examples:
-- `codev/spikes/462-websocket-feasibility.md`
-- `codev/spikes/475-sqlite-fts-performance.md`
+| Verdict | What the findings must contain |
+|---|---|
+| **Feasible** | Recommended approach and rough cost, enough for the architect to decide on a SPIR project |
+| **Not feasible** | Why, what was tried, and what alternatives exist — this is what stops the investigation being repeated in six months |
+| **Feasible with caveats** | The conditions, risks and trade-offs that make it conditional |
 
-The `<id>` is the GitHub issue number or project ID.
+A negative result is a successful spike. The failure mode is an inconclusive one: time spent,
+nothing recorded, question still open.
 
-## Proof-of-Concept Code
+Notify the architect with the verdict when done.
 
-POC code from the iterate step is committed to the spike branch alongside the findings document. It serves as evidence supporting the findings. However:
+## Findings
 
-- POC code does NOT need tests, polish, or production quality
-- POC code does NOT get merged to main — it stays on the spike branch
-- The findings document is the primary deliverable; the code is supporting evidence
-- If the spike leads to a SPIR project, the builder starts fresh
+Write findings using this structure:
 
-## Outcome Handling
-
-- **Feasible**: Write findings with recommended approach and effort estimate. Architect decides whether to create a SPIR project.
-- **Not Feasible**: Write findings documenting why, what was tried, and what alternatives exist. This prevents future teams from repeating the investigation.
-- **Feasible with Caveats**: Write findings with conditions, risks, and trade-offs.
-
-In all cases, notify the architect:
-```bash
-afx send architect "Spike <id> complete. Verdict: [feasible/not feasible/caveats]"
-```
+{{> protocols/spike/templates/findings.md}}
 
-## Git Workflow
+## Git
 
-### Commits
 ```
 [Spike 462] Research: WebSocket library comparison
-[Spike 462] Iterate: POC with ws library
 [Spike 462] Findings: WebSockets feasible for real-time updates
 ```
-
-### When to Commit
-- After significant research findings
-- After each iteration attempt
-- When writing the findings document (final commit)
-
-## Integration with Other Protocols
-
-### Spike -> SPIR
-When a spike validates feasibility:
-1. Create a SPIR spec referencing the spike findings
-2. Use findings to inform the solution approach
-3. Reference effort estimate for planning
-
-Example spec reference:
-```markdown
-## Background
-Spike 462 confirmed WebSocket feasibility with the `ws` library.
-See: codev/spikes/462-websocket-feasibility.md
-```
-
-### Spike -> "Do Not Pursue"
-When a spike finds something is not feasible:
-1. Document clearly in findings
-2. Close the related GitHub issue with a link to findings
-3. The findings become institutional knowledge
-
-## Template: findings.md
-
-Write the findings document using the following template:
-
-{{> protocols/spike/templates/findings.md}}

package/skeleton/protocols/spike/templates/findings.md

@@ -1,67 +1,37 @@
 # Spike: [Title]
 
-**Date**: YYYY-MM-DD
-
-**Verdict**: Feasible | Not Feasible | Feasible with Caveats
+**Date**: YYYY-MM-DD · **Verdict**: Feasible | Not Feasible | Feasible with Caveats
 
 ## Question
 
-What technical question was being investigated? Be specific:
-- What are you trying to determine?
-- What prompted this investigation?
-- What decision depends on the answer?
+The technical question investigated, what prompted it, and the decision that depends on the answer.
 
 ## Research Summary
 
-What was explored during the research phase:
-- Documentation read
-- Existing code examined
-- Prior art found
-- Key constraints identified
+What was explored — documentation read, existing code examined, prior art, and the key constraints identified.
 
 ## Approaches Tried
 
-What was built or tested during the iterate phase:
+What was built or tested. For each: what it was, what happened, and whether it worked.
 
 ### Approach 1: [Name]
-- **What**: Brief description of what was tried
-- **Result**: What happened
-- **Verdict**: Worked / Didn't work / Partially worked
-
-### Approach 2: [Name]
-*(Add more approaches as needed, or remove if research alone answered the question)*
 
 ## Constraints Discovered
 
-Technical limitations, dependencies, and gotchas found during the investigation:
-- [Constraint 1]
-- [Constraint 2]
+Technical limitations, dependencies, and gotchas found during the investigation.
 
 ## Recommended Approach
 
-*(If feasible)* How should full implementation proceed?
-- Recommended library/technique/pattern
-- Key architectural decisions
-- Things to watch out for
-
-*(If not feasible)* Why not, and what alternatives exist?
+If feasible: how full implementation should proceed — recommended library/technique/pattern, key architectural decisions, and what to watch out for. If not feasible: why, and what alternatives exist.
 
 ## Effort Estimate
 
-Rough sizing for a full SPIR project: **Small** | **Medium** | **Large**
-
-- Small: < 300 LOC, 1-2 files, straightforward
-- Medium: 300-1000 LOC, multiple files, some complexity
-- Large: 1000+ LOC, architectural changes, significant complexity
+Rough sizing for a full SPIR project: **Small** (< 300 LOC) | **Medium** (300–1000 LOC) | **Large** (1000+ LOC, architectural).
 
 ## Next Steps
 
-- [ ] [Recommended action — e.g., "Create SPIR spec for WebSocket integration"]
-- [ ] [Or: "Do not pursue — blocked by X"]
-- [ ] [Or: "Investigate Y further before deciding"]
+- [ ] The recommended action (create a SPIR spec, do not pursue, or investigate further before deciding).
 
 ## References
 
-- [Link to relevant documentation]
-- [Link to relevant code/commits]
-- [Link to external resources consulted]
+Relevant documentation, code/commits, and external resources consulted.