@cluesmith/codev 3.0.0-rc.10 → 3.0.0-rc.12

package/skeleton/protocols/aspir/prompts/review.md

@@ -181,11 +181,22 @@ Before PR:
 porch consultation reviews the actual PR, and the architect can review a real PR
 when the pr gate fires.
 
+**PR body requirements**: The PR body MUST include `Closes #<N>` (for feature issues)
+or `Fixes #<N>` (for bug issues) for the driving GitHub issue. If the PR closes
+multiple issues (e.g. duplicates consolidated), include one keyword per issue.
+Without this, GitHub will not auto-close the issue on merge.
+
+**Exception**: if this PR only partially addresses the issue (e.g. one phase of a
+multi-PR effort), DO NOT use `Closes`/`Fixes` — reference the issue with `Refs #<N>`
+or `Part of #<N>` instead. The issue stays open until the follow-up PR closes it.
+
 ```bash
 gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF'
 ## Summary
 [Brief description of the implementation]
 
+Closes #<N>  <!-- Replace <N> with the driving issue number, or use "Refs #<N>" for partial fixes -->
+
 ## Changes
 - [Change 1]
 - [Change 2]

package/skeleton/protocols/bugfix/prompts/pr.md

@@ -15,15 +15,27 @@ Create a pull request, run CMAP review, and address feedback.
 
 ### 1. Create the Pull Request
 
-Create a PR that links to the issue:
+Create a PR that links to the issue.
+
+**PR body requirements**: The PR body MUST include `Fixes #<N>` (where `<N>` is
+the driving issue number) so GitHub auto-closes the issue on merge. If the PR
+fixes multiple issues (e.g. duplicates consolidated), include one `Fixes #<N>`
+per issue. Without this, GitHub will not auto-close the issue.
+
+**Exception**: if this PR only partially addresses the issue, use `Refs #<N>`
+or `Part of #<N>` instead of `Fixes` — the issue stays open until a
+follow-up PR closes it.
+
+**Note**: substitute the real issue number for `<N>` — do not leave the
+placeholder or any `{{...}}` template tag in the committed PR body.
 
 ```bash
-gh pr create --title "Fix #{{issue.number}}: <brief description>" --body "$(cat <<'EOF'
+gh pr create --title "Fix #<N>: <brief description>" --body "$(cat <<'EOF'
 ## Summary
 
 <1-2 sentence description of the bug and fix>
 
-Fixes #{{issue.number}}
+Fixes #<N>  <!-- Substitute <N> with the real issue number -->
 
 ## Root Cause
 

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

@@ -46,6 +46,21 @@ The EXPERIMENT protocol ensures disciplined experimentation:
 - Document findings regardless of outcome
 - Separate experiment artifacts from production code
 
+## If You Open a PR
+
+Most experiments are committed to a branch without a PR, but if you do open one
+to integrate findings and the experiment was triggered by a GitHub issue:
+
+**PR body requirements**: The PR body MUST include `Closes #<N>` (for feature
+issues) or `Fixes #<N>` (for bug issues) for the driving issue so GitHub
+auto-closes it on merge. If the PR closes multiple issues, include one keyword
+per issue.
+
+**Exception**: if this PR only partially addresses the issue (e.g. experiment
+validates an approach but production implementation is deferred), use
+`Refs #<N>` or `Part of #<N>` instead — the issue stays open until a follow-up
+PR closes it.
+
 ## Handling Flaky Tests
 
 If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes):

package/skeleton/protocols/maintain/prompts/review.md

@@ -33,6 +33,16 @@ Update `codev/maintain/NNNN.md` with:
 
 ### 4. Create PR
 
+**PR body requirements**: If this maintenance run was triggered by a GitHub issue
+(e.g. "track down dead X", "clean up Y module"), the PR body MUST include
+`Closes #<N>` for that issue so GitHub auto-closes it on merge. If multiple
+issues are addressed in one run, include one `Closes #<N>` per issue.
+
+**Exception**: if this PR only partially addresses a tracking issue (e.g. more
+cleanup passes are planned), use `Refs #<N>` or `Part of #<N>` instead.
+
+If the run was not tied to any issue, the `Closes` line can be omitted.
+
 ```bash
 git push origin HEAD
 
@@ -41,6 +51,8 @@ gh pr create --title "[Maintain] Codebase maintenance run NNNN" --body "$(cat <<
 
 <2-3 bullet points of what was done>
 
+Closes #<N>  <!-- Only if this run was triggered by a GitHub issue. Use "Refs #<N>" for partial cleanup. -->
+
 ## Changes
 
 - Dead code removed: X items

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

@@ -0,0 +1,85 @@
+# {{protocol_name}} Builder ({{mode}} mode)
+
+You are conducting multi-agent research.
+
+{{#if mode_soft}}
+## Mode: SOFT
+You are running in SOFT mode. This means:
+- You follow the RESEARCH protocol yourself (no porch orchestration)
+- The architect monitors your work and verifies you're adhering to the protocol
+- Use `consult` for the 3-way investigation and critique phases
+{{/if}}
+
+{{#if mode_strict}}
+## Mode: STRICT
+You are running in STRICT mode. This means:
+- Porch orchestrates your work
+- Run: `porch next` to get your next tasks
+- Follow porch signals and gate approvals
+
+### ABSOLUTE RESTRICTIONS (STRICT MODE)
+- **NEVER edit `status.yaml` directly** — only porch commands may modify project state
+- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to
+- **NEVER skip the 3-way consultation** — always follow porch next → porch done cycle
+{{/if}}
+
+## Protocol
+Follow the RESEARCH protocol: `codev/protocols/research/protocol.md`
+
+## RESEARCH Overview
+
+The RESEARCH protocol produces a high-confidence research report through triangulation:
+
+1. **Scope** — Define the precise question, scope, and acceptance criteria. Write a research brief. Gate: architect approval before proceeding.
+2. **Investigate** — Dispatch the brief to 3 models (Gemini, Codex, Claude) in parallel. Each investigates independently. No anchoring — they don't see each other's work.
+3. **Synthesize** — Read all 3 reports. Identify consensus, disagreements, and unique contributions. Write a single synthesis report organized by topic (not by model).
+4. **Critique** — Send the synthesis back to all 3 models for critique. Incorporate valid feedback. Document rejected critique. Finalize the report.
+
+## Output Location
+
+All artifacts go to `codev/research/`:
+- `<topic>-brief.md` — the scoped question (Phase 1)
+- `<topic>-gemini.md`, `<topic>-codex.md`, `<topic>-claude.md` — individual investigations (Phase 2)
+- `<topic>.md` — the final synthesis report (Phase 3+4, this is the deliverable)
+- `<topic>-critique-rebuttals.md` — critique responses (Phase 4)
+
+{{#if task}}
+## Research Topic
+{{task_text}}
+{{/if}}
+
+## Key Principles
+
+- **Triangulate**: consensus across 3 models > any single model's claim
+- **Cite sources**: tell investigators to provide sources where possible
+- **Be candid about uncertainty**: "I don't know" > confabulation
+- **Organize by topic, not by model**: the synthesis is a standalone document
+- **Note surprises**: the most valuable findings are often unexpected
+- **Keep it concise**: the synthesis should be shorter than the sum of the investigations
+
+## Using consult for 3-way Investigation
+
+For the investigate phase, use the `consult` CLI to dispatch to each model:
+
+```bash
+# Phase 2: parallel investigation
+consult -m gemini --prompt-file codev/research/<topic>-brief.md --output codev/research/<topic>-gemini.md &
+consult -m codex --prompt-file codev/research/<topic>-brief.md --output codev/research/<topic>-codex.md &
+consult -m claude --prompt-file codev/research/<topic>-brief.md --output codev/research/<topic>-claude.md &
+wait
+```
+
+For the critique phase:
+```bash
+# Phase 4: parallel critique
+consult -m gemini --prompt "Critique this research synthesis for gaps, errors, and bias:" --prompt-file codev/research/<topic>.md --output codev/research/<topic>-critique-gemini.md &
+consult -m codex --prompt "Critique this research synthesis for gaps, errors, and bias:" --prompt-file codev/research/<topic>.md --output codev/research/<topic>-critique-codex.md &
+consult -m claude --prompt "Critique this research synthesis for gaps, errors, and bias:" --prompt-file codev/research/<topic>.md --output codev/research/<topic>-critique-claude.md &
+wait
+```
+
+## Getting Started
+1. Read the RESEARCH protocol document
+2. Understand the research question from the architect
+3. Write the research brief (Phase 1)
+4. Wait for scope-approval before proceeding to investigation

package/skeleton/protocols/research/protocol.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "../../protocol-schema.json",
+  "name": "research",
+  "version": "1.0.0",
+  "description": "Multi-agent research with 3-way investigation, synthesis, and critique",
+  "input": {
+    "type": "none",
+    "required": false,
+    "default_for": []
+  },
+  "hooks": {
+    "pre-spawn": {}
+  },
+  "phases": [
+    {
+      "id": "scope",
+      "name": "Scope",
+      "description": "Define the research question, scope, and acceptance criteria",
+      "type": "once",
+      "steps": [
+        "clarify_question",
+        "define_scope",
+        "define_acceptance_criteria",
+        "create_research_brief"
+      ],
+      "gate": {
+        "name": "scope-approval",
+        "description": "Architect confirms the research question is correctly scoped",
+        "requires": ["research_brief_exists"],
+        "next": "investigate"
+      }
+    },
+    {
+      "id": "investigate",
+      "name": "Investigate",
+      "description": "3-way parallel investigation — each model researches independently",
+      "type": "once",
+      "steps": [
+        "dispatch_gemini_investigation",
+        "dispatch_codex_investigation",
+        "dispatch_claude_investigation",
+        "collect_all_reports"
+      ],
+      "consultation": {
+        "enabled": true,
+        "models": ["codex"],
+        "parallel": true,
+        "type": "investigation"
+      },
+      "transition": {
+        "on_complete": "synthesize"
+      }
+    },
+    {
+      "id": "synthesize",
+      "name": "Synthesize",
+      "description": "Merge the 3 investigation reports into a single coherent research document",
+      "type": "once",
+      "steps": [
+        "read_all_investigation_reports",
+        "identify_consensus_and_disagreements",
+        "resolve_conflicts",
+        "write_synthesis_report"
+      ],
+      "transition": {
+        "on_complete": "critique"
+      }
+    },
+    {
+      "id": "critique",
+      "name": "Critique",
+      "description": "3-way review of the synthesis — each model critiques for gaps, errors, and bias",
+      "type": "once",
+      "steps": [
+        "dispatch_gemini_critique",
+        "dispatch_codex_critique",
+        "dispatch_claude_critique",
+        "incorporate_feedback",
+        "finalize_report"
+      ],
+      "consultation": {
+        "enabled": true,
+        "models": ["codex"],
+        "parallel": true,
+        "type": "critique"
+      },
+      "gate": {
+        "name": "research-complete",
+        "description": "Research report finalized",
+        "requires": ["report_finalized"],
+        "next": null
+      }
+    }
+  ],
+  "signals": {
+    "PHASE_COMPLETE": {
+      "description": "Signal current phase is complete",
+      "transitions_to": "next_phase"
+    },
+    "BLOCKED": {
+      "description": "Signal research is blocked",
+      "requires": "reason"
+    },
+    "SCOPE_REJECTED": {
+      "description": "Architect rejects the scope — rework needed",
+      "transitions_to": "scope"
+    }
+  },
+  "defaults": {
+    "mode": "strict",
+    "consultation": {
+      "enabled": true,
+      "models": ["codex"],
+      "parallel": true
+    },
+    "checks": {}
+  }
+}

package/skeleton/protocols/research/protocol.md

@@ -0,0 +1,169 @@
+# RESEARCH Protocol
+
+## Overview
+
+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.
+
+**Core Principle**: Triangulate. No single model's knowledge is authoritative. Consensus across models is more reliable than any individual output.
+
+## 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).
+
+## Output
+
+All research artifacts go to `codev/research/`. The final deliverable is a single synthesis report at `codev/research/<topic>.md`.
+
+## 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.
+
+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
+
+The builder then:
+1. Incorporates valid critique
+2. Documents rejected critique with rationale
+3. Finalizes the report
+4. Commits to `codev/research/<topic>.md`
+
+## File Structure
+
+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)
+```
+
+### 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

package/skeleton/protocols/spir/prompts/review.md

@@ -181,11 +181,22 @@ Before PR:
 porch consultation reviews the actual PR, and the architect can review a real PR
 when the pr gate fires.
 
+**PR body requirements**: The PR body MUST include `Closes #<N>` (for feature issues)
+or `Fixes #<N>` (for bug issues) for the driving GitHub issue. If the PR closes
+multiple issues (e.g. duplicates consolidated), include one keyword per issue.
+Without this, GitHub will not auto-close the issue on merge.
+
+**Exception**: if this PR only partially addresses the issue (e.g. one phase of a
+multi-PR effort), DO NOT use `Closes`/`Fixes` — reference the issue with `Refs #<N>`
+or `Part of #<N>` instead. The issue stays open until the follow-up PR closes it.
+
 ```bash
 gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF'
 ## Summary
 [Brief description of the implementation]
 
+Closes #<N>  <!-- Replace <N> with the driving issue number, or use "Refs #<N>" for partial fixes -->
+
 ## Changes
 - [Change 1]
 - [Change 2]

package/skeleton/templates/AGENTS.md

@@ -14,6 +14,7 @@ This project uses **Codev** for AI-assisted development.
 - **BUGFIX**: Bug fixes from GitHub issues (`codev/protocols/bugfix/protocol.md`)
 - **EXPERIMENT**: Disciplined experimentation (`codev/protocols/experiment/protocol.md`)
 - **MAINTAIN**: Codebase maintenance (`codev/protocols/maintain/protocol.md`)
+- **RESEARCH**: Multi-agent research with 3-way investigation, synthesis, and critique (`codev/protocols/research/protocol.md`)
 
 ## Key Locations
 

package/skeleton/templates/CLAUDE.md

@@ -12,6 +12,7 @@ This project uses **Codev** for AI-assisted development.
 - **BUGFIX**: Bug fixes from GitHub issues (`codev/protocols/bugfix/protocol.md`)
 - **EXPERIMENT**: Disciplined experimentation (`codev/protocols/experiment/protocol.md`)
 - **MAINTAIN**: Codebase maintenance (`codev/protocols/maintain/protocol.md`)
+- **RESEARCH**: Multi-agent research with 3-way investigation, synthesis, and critique (`codev/protocols/research/protocol.md`)
 
 ## Key Locations
 

package/skeleton/templates/cheatsheet.md

@@ -63,6 +63,7 @@ A **protocol** is a structured workflow that defines how work progresses from id
 | **SPIR** | New features | Specify → Plan → Implement → Review |
 | **MAINTAIN** | Codebase hygiene | Dead code removal, documentation sync |
 | **EXPERIMENT** | Research & prototyping | Hypothesis → Experiment → Conclude |
+| **RESEARCH** | Multi-agent research | Scope → Investigate (3-way) → Synthesize → Critique (3-way) |
 
 ### Roles