Skip to content

Convert Claude Code or Codex into the most intelligent Deep Research Agent. Collect, search, and synthesize web research into a persistent, searchable wiki that builds on itself. Hosted API + MCP: hyperresearch.ai

v0.6.0: ensemble mode + Claude Code-only rebrand (#2)

Jordan Gibbscb0283e7fe1f
diff --git a/.gitignore b/.gitignore
index 31c9acd..9c756b4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -27,3 +27,4 @@ GEMINI.md
# Per-vault research output
research/
+
diff --git a/README.md b/README.md
index 9fbdd71..54d1c58 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
<img src="assets/banner.png" alt="HYPERRESEARCH" width="700">
</p>
-<h3 align="center">Deep, structured, adversarially-audited research for AI coding agents</h3>
+<h3 align="center">Turn Claude Code into a disciplined research agent</h3>
<p align="center">
<a href="https://pypi.org/project/hyperresearch/"><img src="https://img.shields.io/pypi/v/hyperresearch" alt="PyPI version"></a>
@@ -13,213 +13,200 @@
---
-Your AI agent searches the web, skims sources, writes an answer that sounds good, and ships it. There's no scaffold, no audit, no source-vs-source comparison, no provenance, no way to know if it actually engaged with the strongest counter-position. Next session, the work is gone.
-
-**Hyperresearch makes research disciplined and persistent.** Every fetched source becomes a markdown note in a Zettelkasten knowledge base. Every research session follows a 14-step protocol with four hard checkpoints. Two adversarial auditor subagents tear the draft apart against the user's verbatim prompt before save is allowed. The user's prompt is gospel — pasted into the scaffold's first section, re-read at every step, machine-checked at the gate.
+## Install in 30 seconds
```bash
pip install hyperresearch
hyperresearch install
```
-That's it. In Claude Code: type `/research <topic>`.
+In Claude Code, type `/research <anything>` and the full protocol fires.
+
+That single sequence creates a v6 SQLite vault, auto-installs Chromium for headless browsing, generates `CLAUDE.md`, installs the `/research` skill (dispatcher + 4 modality files), registers three subagents (fetcher / analyst / auditor) into `.claude/agents/`, and wires PreToolUse hooks. You're ready.
---
-## The architecture
+## What it actually produces
-### One dispatcher, four cognitive activities
+Every research session leaves three load-bearing artifacts on disk. These are real excerpts from a recent run on *"Is there a general method for solving asymmetric first-price sealed-bid auctions?"*
-Hyperresearch routes every research request by what the output needs to **do**, not what the subject **is**. A query about a fictional franchise can be `collect` (per-character enumeration), `synthesize` (a thesis about meaning), `compare` (this work vs another), or `forecast` (will this sequel succeed). Subject doesn't decide; activity does.
+### Provenance breadcrumbs in every fetched note
-```mermaid
-graph LR
- P[User Prompt] --> D{Dispatcher}
- D -->|"what exists"| C[collect<br/>enumerative coverage]
- D -->|"what it means"| S[synthesize<br/>defended thesis]
- D -->|"which is best"| CMP[compare<br/>committed pick]
- D -->|"what will happen"| F[forecast<br/>committed prediction]
+```
+asymmetric-auctions-with-more-than-two.md
- C --> R[Final Report<br/>+ Audit Trail]
- S --> R
- CMP --> R
- F --> R
+*Suggested by [[games-and-economic-behavior-73-2011-479495]] — Hubbard on
+asymmetric auctions with more than two bidders*
+```
- style D fill:#1e293b,stroke:#475569,color:#fff
- style C fill:#0f4c5c,stroke:#3b82f6,color:#fff
- style S fill:#0f4c5c,stroke:#3b82f6,color:#fff
- style CMP fill:#0f4c5c,stroke:#3b82f6,color:#fff
- style F fill:#0f4c5c,stroke:#3b82f6,color:#fff
- style R fill:#166534,stroke:#22c55e,color:#fff
+Every fetched source carries a wiki-link breadcrumb back to whatever source recommended it. The chain forms a rooted tree from the seed fetches. The `provenance` lint rule catches disconnected components and flat-batch fetches.
+
+### Persisted audit findings
+
+```json
+{
+ "mode": "comprehensiveness",
+ "status": "needs_fixes",
+ "criticals": [
+ {
+ "id": "C1",
+ "description": "Provenance lint error: 6 source notes have breadcrumbs
+ but are disconnected from the provenance graph...",
+ "fixed_at": "2026-04-15T00:23:00Z",
+ "notes": "Provenance ratio is 40% (above 30% threshold).
+ Disconnected graph is from retroactive backlinks added to existing
+ seeds, not fabricated provenance."
+ }
+ ],
+ "important": [
+ { "id": "I1", "description": "Zero non-academic voices...", "fixed_at": "..." }
+ ]
+}
```
-Each modality file encodes only its substance differences (source strategy, writing rules, conformance checks). The shared 14-step protocol — discovery, fetch, curation, scaffold, comparisons, draft, audit, synthesis — lives in one dispatcher. Tight, factored, no duplication.
-
-### The context flow — verbatim prompt is gospel
-
-Every step re-encounters the user's original prompt. It gets pasted verbatim into the scaffold's first section, the auditor reads it at every audit, the save gate machine-checks it. No paraphrasing, no drift.
-
-```mermaid
-flowchart TB
- P[📥 User Prompt] -->|verbatim, never paraphrased| CLS[1. Classify activity<br/>+ extract deliverables]
- CLS --> SRC[2. Source discovery<br/>+ adversarial round]
- SRC --> FET[3. Seed fetch<br/>3-5 high-signal URLs]
- FET --> LOOP{4. Guided reading loop}
- LOOP -->|analyst proposes targets| FET2[Fetch with --suggested-by<br/>builds rooted provenance graph]
- FET2 --> LOOP
- LOOP -->|coverage complete| CK1[✓ Checkpoint 1<br/>voice diversity + dissent]
-
- CK1 --> CUR[5-6. Curate every source<br/>tier + content_type + analyst extract]
- CUR --> CK2[✓ Checkpoint 2<br/>provenance rooted-tree<br/>analyst coverage]
-
- CK2 --> SCF[7. Build scaffold<br/>📌 verbatim prompt as §1]
- SCF --> CMP[8. Comparisons note<br/>3-5 source-vs-source disagreements]
- CMP --> CK3[✓ Checkpoint 3<br/>scaffold-prompt lint<br/>artifacts present]
-
- CK3 --> DRF[9. Write draft<br/>against the scaffold]
- DRF --> GAP[10. Gap analysis<br/>+ adversarial search]
- GAP --> AUD[11. Adversarial audit<br/>2 modes, persisted to JSON]
- AUD --> CK4[✓ Checkpoint 4<br/>audit-gate self-cert detection]
-
- CK4 --> SYN[12. Opinionated synthesis]
- SYN --> SAVE[13-14. Save synthesis note<br/>blocked until audit-gate passes]
-
- style P fill:#7c2d12,stroke:#ea580c,color:#fff
- style SCF fill:#7c2d12,stroke:#ea580c,color:#fff
- style AUD fill:#581c87,stroke:#a855f7,color:#fff
- style CK1 fill:#166534,stroke:#22c55e,color:#fff
- style CK2 fill:#166534,stroke:#22c55e,color:#fff
- style CK3 fill:#166534,stroke:#22c55e,color:#fff
- style CK4 fill:#166534,stroke:#22c55e,color:#fff
- style SAVE fill:#166534,stroke:#22c55e,color:#fff
+Both audit modes (comprehensiveness + conformance, both Opus) persist their findings to `research/audit_findings.json`. The agent applies fixes and marks each finding `fixed_at: <timestamp>`.
+
+### Self-certification detector blocks save
+
+The `audit-gate` lint rule extracts the keyword from each CRITICAL's description, **re-runs the underlying lint rule**, and emits this if the rule still fails:
+
```
+SELF-CERTIFICATION VIOLATION: CRITICAL [C1] was marked `fixed_at` in
+research/audit_findings.json, but lint rule `provenance` still returns
+3 error(s). The draft's `fixed_at` marker does not match the vault's
+actual state — you must fix the underlying issue (not just the
+bookkeeping). Run `$HPR lint --rule provenance -j` to see what's
+still broken.
+```
+
+The save gate blocks until every CRITICAL is **genuinely** resolved. Bookkeeping fixes get caught.
-The four checkpoints are hard gates. **Checkpoint 3** runs `scaffold-prompt` lint that machine-checks the verbatim prompt is in the scaffold's first section. **Checkpoint 4** runs `audit-gate` lint that re-runs the underlying lint rules referenced by every CRITICAL audit finding — if a finding was marked "fixed" but the underlying rule still fails, the gate emits a `SELF-CERTIFICATION VIOLATION` and blocks save. The agent cannot ship a draft that grades its own homework.
+---
-### The subagent triad
+## Why it works on hard research
-Hyperresearch ships three registered Claude Code subagents, each picked for its job:
+Your AI agent searches the web, skims sources, writes an answer that sounds good, and ships it. There's no scaffold, no audit, no source-vs-source comparison, no provenance, no way to know if it actually engaged with the strongest counter-position. Hyperresearch breaks that pattern through structural enforcement:
-```mermaid
-graph TB
- M[🤖 Main Agent<br/>your Claude Code session]
+- **Verbatim user prompt is gospel** — pasted into the scaffold's first section, re-read at every step, machine-checked at the save gate
+- **Bouncing reading loop** — fetch a seed, an analyst reads it and proposes next URLs, main agent fetches those WITH `--suggested-by` provenance, loop. Builds a rooted research graph instead of a flat batch.
+- **Per-source analyst extraction** — every fetched source gets a Sonnet subagent that reads it with the research goal in hand
+- **Adversarial dissent is mandatory** — Checkpoint 1 fails until at least one source explicitly contradicts the dominant view
+- **Two-mode adversarial audit (Opus)** — comprehensiveness finds gaps vs the verbatim prompt; conformance checks modality rules
+- **Save is blocked** until every CRITICAL is verified-resolved by the audit-gate detector
- M -.spawns.-> F[🌐 hyperresearch-fetcher<br/><b>Haiku</b><br/>cheap URL fetching]
- M -.spawns.-> A[📖 hyperresearch-analyst<br/><b>Sonnet</b><br/>guided reading + extraction]
- M -.spawns.-> AU[🔍 hyperresearch-auditor<br/><b>Opus</b><br/>adversarial review]
+---
- F -->|fetched note| V[(Vault<br/>SQLite + markdown)]
- A -->|extract note + next_targets| V
- A -.proposes URLs.-> M
- AU -->|findings JSON| V
- AU -->|pass/fail| M
+## How it works — the contextual flow
- style M fill:#1e293b,stroke:#475569,color:#fff
- style F fill:#0c4a6e,stroke:#0ea5e9,color:#fff
- style A fill:#0e7490,stroke:#06b6d4,color:#fff
- style AU fill:#581c87,stroke:#a855f7,color:#fff
- style V fill:#166534,stroke:#22c55e,color:#fff
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│ │
+│ USER PROMPT (verbatim, gospel) │
+│ │ │
+│ ▼ │
+│ ┌─────────────────────────────────────────────────────────────┐ │
+│ │ MAIN AGENT (your Claude Code session) │ │
+│ │ classify → seed fetch → guided loop → audit → save │ │
+│ └──────┬──────────────────┬──────────────────┬─────────────────┘ │
+│ │ │ │ │
+│ spawn ▼ spawn ▼ spawn ▼ │
+│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
+│ │ FETCHER │ │ ANALYST │ │ AUDITOR │ │
+│ │ (Haiku) │ │ (Sonnet) │ │ (Opus) │ │
+│ │ │ │ │ │ │ │
+│ │ crawl4ai │ │ read note │ │ check vs │ │
+│ │ +headless │ │ extract + │ │ verbatim │ │
+│ │ Chromium │ │ next URLs │ │ prompt │ │
+│ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │
+│ │ │ │ │
+│ │ note + │ extract + │ findings.json │
+│ │ raw.pdf │ next_targets │ │
+│ ▼ ▼ ▼ │
+│ ┌─────────────────────────────────────────────────────────────┐ │
+│ │ VAULT (SQLite v6 + markdown) │ │
+│ │ notes/*.md raw/*.pdf scaffold.md comparisons.md │ │
+│ │ audit_findings.json ←── audit-gate lint blocks save │ │
+│ └─────────────────────────────────────────────────────────────┘ │
+│ ▲ │
+│ │ analyst's next_targets re-enter FETCHER with │
+│ │ --suggested-by, building a rooted provenance tree │
+│ └─────────── bouncing reading loop ─────────────────────────┘
+│ │
+└─────────────────────────────────────────────────────────────────────┘
```
-| Agent | Model | Job | Why this model |
-|---|---|---|---|
-| **hyperresearch-fetcher** | Haiku | Fetches a URL via crawl4ai, persists the note. Mechanical, fast, parallel. | URL fetching is mechanical. Haiku is 10× cheaper. |
-| **hyperresearch-analyst** | Sonnet | Reads one source with the research goal in hand, writes a focused extract, proposes 2-5 next targets for the guided loop. | Reasoning about what's relevant + what to read next is real work. Sonnet hits the cost/quality sweet spot for hundreds of source reads per session. |
-| **hyperresearch-auditor** | Opus | Runs in two modes (`comprehensiveness` + `conformance`) against the verbatim prompt. Independently re-extracts entities, runs lint rules, persists findings to JSON. | Adversarial review over a long document against multiple criteria is critical reasoning. Worth Opus's ceiling. |
+**Subagent triad**, each picked for its job:
-The **guided reading loop** is the engine of deep research: seed-fetch 3-5 URLs → spawn an analyst on each → analysts propose `next_targets` → main agent fetches those WITH `--suggested-by` provenance → loop. Every fetched source carries a wiki-link breadcrumb back to the source that recommended it, so the research graph is a rooted, traceable tree. The provenance lint rule enforces this structurally.
+| Agent | Model | Role |
+|---|---|---|
+| `hyperresearch-fetcher` | **Haiku** | Mechanical URL fetching via crawl4ai. Cheap, fast, parallel. |
+| `hyperresearch-analyst` | **Sonnet** | Reads one source with research goal in hand. Writes a focused extract, proposes 2-5 next URLs for the loop. |
+| `hyperresearch-auditor` | **Opus** | Adversarial review in two modes against the verbatim prompt. Persists structured findings the save gate verifies. |
-### The audit-gate self-certification detector
+**Routing** — the dispatcher classifies every request by **what the output needs to do**, not what the subject is:
-The most important quality guarantee in v0.5.0. Two modes of the auditor run sequentially, each persisting findings to `research/audit_findings.json`. The agent applies fixes and marks each CRITICAL `fixed_at: <timestamp>`. The save gate then doesn't trust those marks blindly:
+```
+collect → enumerative coverage with per-entity fields
+synthesize → defended thesis grounded in evidence
+compare → per-entity evaluation + committed recommendation
+forecast → committed prediction with explicit time horizon
+```
-```mermaid
-flowchart LR
- A[Auditor finds<br/>CRITICAL: provenance broken] --> B[Agent applies fix]
- B --> C[Agent marks<br/>fixed_at: timestamp]
- C --> D{audit-gate lint}
- D -->|extracts keyword<br/>'provenance'| E[Re-run<br/>provenance lint rule]
- E -->|still has errors| F[❌ SELF-CERTIFICATION VIOLATION<br/>save blocked]
- E -->|now clean| G[✓ Save proceeds]
+A query about a fictional franchise can be `collect` (per-character enumeration), `synthesize` (a thesis about meaning), `compare` (this vs another), or `forecast` (will the sequel succeed). Subject doesn't decide; activity does.
- style F fill:#7f1d1d,stroke:#ef4444,color:#fff
- style G fill:#166534,stroke:#22c55e,color:#fff
- style D fill:#581c87,stroke:#a855f7,color:#fff
-```
+---
+
+## What's enforced
+
+Eight invariants the protocol structurally prevents from breaking:
-Every CRITICAL with a `fixed_at` timestamp gets its underlying lint rule re-run in the same lint pass. If the rule still returns errors, the agent's "fix" was bookkeeping not substance — and the synthesis save is blocked until the actual vault state matches the claim. The 60+ keyword map covers `provenance`, `analyst-coverage`, `scaffold-prompt`, `workflow`, `uncurated` and natural-language variants. Findings that don't map to any rule emit an advisory warning ("not machine-verified") so the human reviewer sees which findings rest on agent self-report.
+1. **Verbatim prompt as gospel** — `scaffold-prompt` lint blocks at Checkpoint 3 if the scaffold doesn't open with the user's exact prompt
+2. **Rooted-tree provenance** — `--suggested-by` chain must form a real tree from at least one seed; isolated breadcrumbs flagged
+3. **Analyst coverage** — at least 1 extract per 3 sources, no silent skipping
+4. **Adversarial dissent** — at least one source explicitly contradicts the dominant view, named in writing
+5. **Audit-gate self-cert detection** — CRITICAL findings marked fixed get their underlying lint rules re-run
+6. **Save blocked** until every CRITICAL is genuinely resolved
+7. **Schema integrity** — `tier` and `content_type` are SQLite CHECK-constrained vocabularies; corrupted frontmatter cannot poison the index
+8. **PDF + raw artifact persistence** — fetched PDFs land in `research/raw/` and the `raw_file` frontmatter field survives every re-serialization
---
-## What people use it for
+## What hyperresearch doesn't do
-- **In-depth topic research** — "What does the literature say about ion-trap quantum scaling?" → 25+ academic sources, 8+ analyst extracts, dissenting voices represented, full provenance graph
-- **Comparative evaluation** — "TigerBeetle vs Postgres vs FoundationDB for write-heavy workloads" → per-entity coverage, comparison matrix, committed recommendation, mandatory critical voice on the market leader
-- **Forecasting + strategy** — "Will US inflation stay above 3% through 2026?" → ground-truth statistics + institutional analysis + named contrarians, probability language not hedge language, explicit time horizon
-- **Interpretive analysis** — "What does Blood Meridian's violence mean?" → primary text + critical tradition + dissenting reading, every paragraph fuses fact with interpretive claim
-- **Enumerative coverage** — "For each Napoleonic marshal, cover key campaigns and fate" → per-entity treatment with the 4 fields, no silent downgrades from "each" to "representative examples"
-- **Persistent knowledge base** — every source ever fetched stays searchable. Future sessions check the vault before searching the web. Knowledge compounds.
+- It doesn't replace your judgment on which sources matter — the agent picks, you steer
+- It can't fetch what's behind a paywall you haven't logged into (but it tries: `--visible` flag bypasses many bot-detectors, and configured login profiles work transparently)
+- It runs on Anthropic models — Opus + Sonnet + Haiku via the subagent triad. Costs scale with corpus size; expect $5-15 per deep research session.
+- The audit gate catches **structural** failures (missing scaffold, broken provenance, unresolved CRITICALs). It cannot guarantee factual accuracy — that's still your call.
+- Network fetches fail. The protocol surfaces failures explicitly and walks a fallback chain (alternative URLs → visible browser → summary fallback), but some sources won't ever be fetchable.
---
-## What you get out of the box
+## Use cases
-```bash
-pip install hyperresearch
-hyperresearch install
-```
+- **Deep technical research** — "What does the literature say about ion-trap quantum scaling?" → 25+ academic sources, full provenance graph, dissenting voices, primary papers quoted directly
+- **Comparative evaluation** — "TigerBeetle vs Postgres vs FoundationDB for write-heavy workloads" → per-entity coverage, comparison matrix, committed pick, mandatory critical voice on the leader
+- **Forecasting + strategy** — "Will US inflation stay above 3% through 2026?" → ground-truth statistics + institutional analysis + named contrarians, probability language not hedge
+- **Interpretive analysis** — "What does *Blood Meridian*'s violence mean?" → primary text + critical tradition + dissenting reading, every paragraph fuses fact with interpretive claim
+- **Enumerative coverage** — "For each Napoleonic marshal, cover key campaigns and fate" → every named entity gets every requested field, no silent downgrades
+- **Persistent knowledge base** — every source ever fetched stays searchable. Future sessions check the vault before searching the web. Knowledge compounds.
+
+### `/research-ensemble` — 3 parallel sub-runs + Opus merger
-That single sequence:
-
-1. Initializes a v6 SQLite vault with FTS5 search at `.hyperresearch/`
-2. Auto-installs Chromium for crawl4ai if missing
-3. Writes `CLAUDE.md` with the protocol overview
-4. Installs the `/research` skill (dispatcher + 4 modality files) to `.claude/skills/hyperresearch/`
-5. Registers all 3 subagents (fetcher, analyst, auditor) to `.claude/agents/`
-6. Wires PreToolUse hooks into `.claude/settings.json`
-7. Sets crawl4ai as the default web provider
-
-You're ready. Type `/research <anything>` in Claude Code.
-
-### What's enforced
-
-- **Verbatim prompt as gospel** — machine-checked via `scaffold-prompt` lint rule
-- **Rooted-tree provenance graph** — `--suggested-by` chain must form an actual tree from seeds; isolated breadcrumbs are flagged
-- **Analyst coverage** — at least 1 extract per 3 sources (no silent skipping)
-- **Adversarial dissent** — Checkpoint 1 requires at least one source explicitly dissents from the dominant view
-- **Audit gate self-cert detection** — CRITICAL findings marked fixed must actually be fixed; bookkeeping fixes get caught
-- **Save blocked** until audit-gate passes — synthesis cannot ship if any CRITICAL is unresolved
-- **Schema integrity** — `tier` and `content_type` are SQLite CHECK-constrained vocabularies; corrupted frontmatter cannot poison the index
-- **PDF + raw artifact persistence** — fetched PDFs land in `research/raw/` and the `raw_file` frontmatter field survives all re-serializations
-
-### Key features
-
-- **Real headless browser** — crawl4ai runs local Chromium. JS rendering, bot detection bypass, SPA support. Not an HTTP fetch.
-- **Native PDF extraction** — fetched PDFs go through pymupdf, full text extracted, raw file persisted
-- **Authenticated crawling** — log into LinkedIn / Twitter / paywalled news once via `hyperresearch setup`; the profile auto-applies on every fetch
-- **Junk detection** — captchas, cookie walls, login redirects, binary garbage, error pages all caught and rejected
-- **Fetch resilience** — when a high-priority source fails, the agent tries alternative URLs (preprint server, author page, institutional repo), then `--visible` browser, then a summary as fallback. Failures get documented; nothing silently disappears.
-- **MCP server** — 13 tools (read + write) for Claude Desktop, Cursor, or any MCP client
-- **Note lifecycle** — `draft → review → evergreen → stale → deprecated → archive`
-- **Knowledge graph** — `[[wiki-links]]`, backlinks, hub detection, auto-linking
-- **FTS5 search** — instant full-text search with BM25 ranking across thousands of notes
+For queries where depth-of-corpus and argument stability matter more than wall-clock time, use `/research-ensemble <query>`. Opus orchestrates; three `hyperresearch-subrun` Sonnet agents run the full protocol in parallel against one shared vault, each with a subtly different framing (evidentiary breadth / citation-chain depth / dialectical tension). A fourth agent (`hyperresearch-merger`, Opus) scores each draft on comprehensiveness / readability / argument strength / citation quality, picks the strongest as the base, and splices in unique evidence from the other two. Cost is ~5× a normal run; the payoff is detailed in [Benchmarks](#benchmarks) below.
---
-## Hooks for every major agent
+## What `hyperresearch install` wires into Claude Code
-`hyperresearch install` wires into your agent in one step:
+One command sets up the full integration:
-| Platform | Hook | Trigger |
-|----------|------|---------|
-| **Claude Code** | `.claude/settings.json` + `/research` skill + 3 subagents | Before WebSearch, WebFetch |
-| **Codex** | `.codex/hooks.json` | Before Bash |
-| **Cursor** | `.cursor/rules/hyperresearch.mdc` | Always-apply rule |
-| **Gemini CLI** | `.gemini/settings.json` | Before tool calls |
+- **`.claude/settings.json`** — PreToolUse hook that nudges Claude Code to check the vault before any raw web search
+- **`.claude/skills/hyperresearch/`** — `/research` skill (dispatcher + 4 modality files: collect / synthesize / compare / forecast)
+- **`.claude/skills/research-ensemble/`** — `/research-ensemble` skill (3× parallel sub-runs + Opus merger; see [Benchmarks](#benchmarks))
+- **`.claude/agents/`** — six registered subagents: `hyperresearch-fetcher` (Haiku), `hyperresearch-analyst` (Sonnet), `hyperresearch-auditor` (Opus), `hyperresearch-rewriter` (Sonnet), `hyperresearch-subrun` (Sonnet, ensemble), `hyperresearch-merger` (Opus, ensemble)
+- **`CLAUDE.md`** at the vault root — the full research workflow, automatically loaded by Claude Code on every session
-```bash
-hyperresearch install --platform all # Hook every platform at once
-```
+hyperresearch is Claude Code-only for now. Codex, Cursor, and Gemini support was trimmed from v0.6 to focus the surface area — may return as real integrations later.
---
@@ -236,7 +223,7 @@ hyperresearch search "query" -j # Full-text search
hyperresearch search "query" --tier ground_truth -j # Filter by epistemic tier
hyperresearch search "query" --content-type paper -j # Filter by artifact kind
hyperresearch note show <id> -j # Read a note
-hyperresearch note show <id> --meta -j # Read frontmatter only (cheap triage)
+hyperresearch note show <id> --meta -j # Frontmatter only (cheap triage)
hyperresearch note list --status draft -j # List notes with summaries
# Knowledge graph
@@ -276,6 +263,26 @@ LinkedIn, Twitter, Facebook, Instagram, and TikTok automatically use a visible b
---
+## Benchmarks
+
+Hyperresearch is being evaluated on the [DeepResearch Bench](https://github.com/Ayanami0730/deep_research_bench) RACE eval (Gemini-2.5-Pro judges reports on comprehensiveness, insight, instruction-following, readability). Full per-modality scores and head-to-head comparisons vs other research harnesses will land here as the 100-query sweep completes. **Status:** in progress.
+
+### Ensemble lift — preliminary data point
+
+Query 91 from DeepResearch-Bench ("detailed analysis of the Saint Seiya franchise, structured around armor classes, per-character power/techniques/arcs/fate") is a deep-collect query with ~100 named entities. One data point so far:
+
+| Variant | Overall | Comp. | Insight | Inst. | Read. | Cost | Time |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| `/research` single-run (sonnet, v1 baseline) | **52.74** | 52.95 | 58.74 | 51.28 | 51.90 | ~$1.50 | ~8 min |
+| `/research-ensemble` (3× sonnet + opus merger) | **54.82** | 54.52 | 58.57 | 53.30 | 56.10 | $21.98 | 57 min |
+| **Delta** | **+2.08** | +1.57 | −0.17 | +2.02 | +4.20 | ~14× | ~7× |
+
+Readability is the biggest single lift (+4.20) — the merger smooths splice boundaries and harmonizes voice across the three sub-runs. Instruction-following (+2.02) gains from three independent passes cross-checking the prompt's entity list; prompt-named entities the base run collapsed get restored from sibling runs. Comprehensiveness (+1.57) comes from the 3-way evidence union (167 sources fetched into the shared corpus vs ~30 for a single run). Insight is flat as expected — the merger is a compiler, not a re-thinker; it can't deepen an argument beyond what the strongest sub-run already had.
+
+One query is not a benchmark. Full 100-query sweep coming next. The cost ceiling is honest: ~5× per query at the tool-call level, ~14× here because `/research` ran on Sonnet and `/research-ensemble` requires Opus orchestration + Opus merger. Use ensemble where the query earns it; use `/research` for everything else.
+
+---
+
## Philosophy
- **Process is load-bearing.** A draft without a scaffold, comparisons, audit findings, and a clean provenance graph is unfinished — regardless of how good the prose reads.
@@ -283,15 +290,15 @@ LinkedIn, Twitter, Facebook, Instagram, and TikTok automatically use a visible b
- **No LLM calls inside the tool.** Hyperresearch stores, indexes, lints, and orchestrates. Your agent is the LLM.
- **Markdown is truth, SQLite is cache.** Notes are plain files. Delete the DB; `hyperresearch sync` rebuilds it.
- **Audit findings are artifacts, not just outputs.** They persist to JSON, get verified by lint rules, and gate the save. Self-certification is structurally prevented.
-- **Deeper-not-broader.** v0.5.0 prefers 15 well-extracted sources over 50 skim-fetched ones. The protocol enforces analyst coverage, not source count.
+- **Exhaustive and deep.** v0.5.0 seeds 10-15 sources, iterates the bouncing loop 8 rounds, and typically produces drafts anchored in 40-80 fetched-and-analyst-read sources with 40+ inline citations. Depth AND breadth — not a tradeoff.
---
## Requirements
- Python 3.11+
-- Claude Code (or Codex / Cursor / Gemini CLI) with API access
-- Anthropic API key with access to Opus, Sonnet, and Haiku (for the subagent triad)
+- [Claude Code](https://claude.com/claude-code) with Anthropic API access
+- API key with access to Opus, Sonnet, and Haiku — one key powers the full subagent triad
- Windows, macOS, Linux
---
diff --git a/pyproject.toml b/pyproject.toml
index 8b45eb6..eb77af9 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
[project]
name = "hyperresearch"
-version = "0.5.0"
-description = "Agent-driven research knowledge base. Browse, collect, and synthesize web sources into a searchable wiki."
+version = "0.6.0"
+description = "Claude Code harness for disciplined, adversarially-audited deep research with full provenance."
readme = "README.md"
license = "MIT"
requires-python = ">=3.11"
diff --git a/src/hyperresearch/cli/config_cmd.py b/src/hyperresearch/cli/config_cmd.py
index 3c7b873..3d879b1 100644
--- a/src/hyperresearch/cli/config_cmd.py
+++ b/src/hyperresearch/cli/config_cmd.py
@@ -123,15 +123,14 @@ def config_get(
@app.command("agent-docs")
def config_agent_docs(
- agents: list[str] = typer.Option(["claude"], "--agents", "-a", help="Which files: claude|agents|gemini|copilot"),
json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
) -> None:
- """Update agent config files (CLAUDE.md, AGENTS.md, GEMINI.md, copilot-instructions.md)."""
+ """Update CLAUDE.md with the latest hyperresearch blurb."""
from hyperresearch.core.agent_docs import inject_agent_docs
from hyperresearch.core.vault import Vault
vault = Vault.discover()
- modified = inject_agent_docs(vault.root, agents=agents)
+ modified = inject_agent_docs(vault.root)
if json_output:
output(success({"modified": modified}, vault=str(vault.root)), json_mode=True)
@@ -140,4 +139,4 @@ def config_agent_docs(
for m in modified:
console.print(f" [green]{m}[/]")
else:
- console.print("[dim]Agent docs already up to date.[/]")
+ console.print("[dim]CLAUDE.md already up to date.[/]")
diff --git a/src/hyperresearch/cli/graph.py b/src/hyperresearch/cli/graph.py
index 9a01d86..67f7a65 100644
--- a/src/hyperresearch/cli/graph.py
+++ b/src/hyperresearch/cli/graph.py
@@ -219,12 +219,14 @@ def graph_stub(
console.print(f" [cyan]{t}[/]")
return
+ # Stubs are sidelined to research/temp/ (not research/notes/) so they
+ # resolve broken wiki-links without cluttering the real notes listing.
+ # Sync still picks them up via rglob, so link-resolution works.
created = []
for target in targets:
- # Create a minimal stub note
title = target.replace("-", " ").replace("_", " ").title()
path = write_note(
- vault.notes_dir,
+ vault.temp_dir,
title,
body=f"# {title}\n\n*Stub — created to resolve a broken link. Expand this note.*\n",
note_id=target,
diff --git a/src/hyperresearch/cli/install.py b/src/hyperresearch/cli/install.py
index 21c1b6d..90d6704 100644
--- a/src/hyperresearch/cli/install.py
+++ b/src/hyperresearch/cli/install.py
@@ -13,21 +13,9 @@ from hyperresearch.models.output import error, success
def install(
path: str = typer.Argument(".", help="Path to install in"),
name: str = typer.Option("Research Base", "--name", "-n", help="Vault name"),
- platforms: list[str] = typer.Option(
- ["claude"],
- "--platform",
- "-p",
- help="Agent platforms to hook: claude|codex|cursor|gemini|all",
- ),
- agents: list[str] = typer.Option(
- ["claude"],
- "--agents",
- "-a",
- help="Agent doc files: claude|agents|gemini|copilot",
- ),
json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
) -> None:
- """Install hyperresearch: init vault + inject agent docs + install hooks."""
+ """Install hyperresearch: init vault + inject CLAUDE.md + install Claude Code hooks."""
import sys
from hyperresearch.core.hooks import install_hooks
@@ -50,7 +38,7 @@ def install(
vault_action = "existing"
except VaultError:
try:
- vault = Vault.init(root, name=name, agents=agents)
+ vault = Vault.init(root, name=name)
vault_action = "created"
except VaultError as e:
if json_output:
@@ -64,11 +52,11 @@ def install(
hpr_path = _resolve_executable()
- # Step 3: Always re-inject agent docs (updates CLAUDE.md etc. with latest blurb + path)
- doc_actions = inject_agent_docs(root, agents=agents)
+ # Step 3: Always re-inject CLAUDE.md (updates blurb + path)
+ doc_actions = inject_agent_docs(root)
- # Step 4: Install hooks (with resolved path baked in)
- hook_actions = install_hooks(root, platforms=platforms, hpr_path=hpr_path)
+ # Step 4: Install Claude Code hook + skills + subagents
+ hook_actions = install_hooks(root, hpr_path=hpr_path)
# Step 3: Auto-configure crawl4ai if installed
crawl4ai_status = _setup_crawl4ai(vault)
@@ -79,7 +67,6 @@ def install(
"vault": vault_action,
"agent_docs": doc_actions,
"hooks_installed": hook_actions,
- "platforms": platforms,
"crawl4ai": crawl4ai_status,
}
diff --git a/src/hyperresearch/cli/lint.py b/src/hyperresearch/cli/lint.py
index f278204..e70aeaf 100644
--- a/src/hyperresearch/cli/lint.py
+++ b/src/hyperresearch/cli/lint.py
@@ -38,6 +38,15 @@ def lint(
ctx: typer.Context,
fix: bool = typer.Option(False, "--fix", help="Auto-fix what's possible"),
rule: str | None = typer.Option(None, "--rule", "-r", help="Run specific rule only"),
+ audit_file: str | None = typer.Option(
+ None,
+ "--audit-file",
+ help=(
+ "Path (relative to vault root) to the audit_findings.json file the "
+ "audit-gate rule reads. Defaults to research/audit_findings.json. "
+ "Ensemble sub-runs pass research/audit_findings-run-{a,b,c}.json."
+ ),
+ ),
json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
) -> None:
"""Health-check the vault."""
@@ -114,7 +123,10 @@ def lint(
# a missing conformance run is itself an error — the protocol demands
# both modes, not just comprehensiveness.
import json as _json
- audit_path = vault.root / "research" / "audit_findings.json"
+ if audit_file:
+ audit_path = vault.root / audit_file
+ else:
+ audit_path = vault.root / "research" / "audit_findings.json"
if audit_path.exists():
try:
audit_data = _json.loads(audit_path.read_text(encoding="utf-8"))
@@ -582,6 +594,16 @@ def lint(
# `source_count >= 10` which silently disabled the rule for small
# corpora (a compare session with 8 named entities could ship zero
# extracts and pass). The gate is removed.
+ #
+ # extract_min_words floor: only notes with body word_count >= this
+ # threshold count as "real" extracts. Anti-lint-gaming — a batch of
+ # 40 stub notes at ~75 words each must not satisfy analyst-coverage
+ # by count alone. Real analyst extracts run 400-1000+ words with
+ # direct quotes; anything below 150 words is a label, not an
+ # extraction. See the Q91 ensemble run where the orchestrator
+ # minted 45 stub extracts to pass this gate.
+ extract_min_words = 150
+
source_count_row = conn.execute(
"SELECT COUNT(*) as c FROM notes n "
"WHERE n.source IS NOT NULL "
@@ -593,11 +615,26 @@ def lint(
).fetchone()
source_count = source_count_row["c"] if source_count_row else 0
+ # Count REAL extracts (body word_count >= 150) — stubs don't satisfy.
extract_count_row = conn.execute(
- "SELECT COUNT(DISTINCT note_id) as c FROM tags WHERE tag = 'extract'"
+ "SELECT COUNT(DISTINCT n.id) as c FROM notes n "
+ "JOIN tags t ON t.note_id = n.id "
+ "WHERE t.tag = 'extract' AND n.word_count >= ?",
+ (extract_min_words,),
).fetchone()
extract_count = extract_count_row["c"] if extract_count_row else 0
+ # Also count stubs separately so the lint message can be honest about
+ # what's there — a vault with 13 real + 45 stub extracts shows that
+ # fact explicitly rather than silently collapsing to "13 extracts".
+ stub_count_row = conn.execute(
+ "SELECT COUNT(DISTINCT n.id) as c FROM notes n "
+ "JOIN tags t ON t.note_id = n.id "
+ "WHERE t.tag = 'extract' AND n.word_count < ?",
+ (extract_min_words,),
+ ).fetchone()
+ stub_count = stub_count_row["c"] if stub_count_row else 0
+
# Require 1/3 coverage (error floor at 1/4). Even a 2-source session
# needs at least 1 extract — the analyst is mandatory, not optional.
if source_count >= 1:
@@ -605,17 +642,23 @@ def lint(
error_floor = max(1, source_count // 4)
if extract_count < required_extracts:
ratio = extract_count / source_count if source_count else 0
+ stub_note = (
+ f" (plus {stub_count} stub notes under {extract_min_words} words, not counted)"
+ if stub_count else ""
+ )
issues.append({
"rule": "analyst-coverage",
"severity": "error" if extract_count < error_floor else "warning",
"note_id": "<vault>",
"message": (
f"Vault has {source_count} fetched source notes but only {extract_count} "
- f"extract notes ({ratio:.0%} coverage, need ≥{required_extracts}). "
+ f"real extract notes{stub_note} ({ratio:.0%} coverage, need ≥{required_extracts}). "
f"The analyst was skipped on most sources. Spawn "
f"hyperresearch-analyst (mode=extract or mode=guided) on the "
- f"unanalyzed sources during curation. Target: at least 1 extract per "
- f"3 sources (floor of 1 for any corpus size)."
+ f"unanalyzed sources during curation. Target: at least 1 extract "
+ f"(≥{extract_min_words} words) per 3 sources (floor of 1 for any "
+ f"corpus size). Minting stub notes to pass this gate is lint-gaming "
+ f"and will not satisfy — spawn real analysts."
),
})
diff --git a/src/hyperresearch/cli/main.py b/src/hyperresearch/cli/main.py
index e3f514e..ab80675 100644
--- a/src/hyperresearch/cli/main.py
+++ b/src/hyperresearch/cli/main.py
@@ -17,14 +17,13 @@ def init(
path: str = typer.Argument(".", help="Path to initialize vault in"),
name: str = typer.Option("Research Base", "--name", "-n", help="Vault name"),
research_dir: str = typer.Option("research", "--dir", "-d", help="Research directory name"),
- agents: list[str] = typer.Option(["claude"], "--agents", "-a", help="Agent config files: claude|agents|gemini|copilot"),
json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
) -> None:
- """Initialize a new hyperresearch vault."""
+ """Initialize a new hyperresearch vault (Claude Code integration)."""
from hyperresearch.core.vault import Vault, VaultError
try:
- vault = Vault.init(Path(path).resolve(), name=name, research_dir=research_dir, agents=agents)
+ vault = Vault.init(Path(path).resolve(), name=name, research_dir=research_dir)
data = {"vault_path": str(vault.root), "name": name}
if json_output:
output(success(data), json_mode=True)
diff --git a/src/hyperresearch/cli/note.py b/src/hyperresearch/cli/note.py
index e8de28c..8872107 100644
--- a/src/hyperresearch/cli/note.py
+++ b/src/hyperresearch/cli/note.py
@@ -258,7 +258,7 @@ def note_show(
def note_list(
status: str | None = typer.Option(None, "--status", "-s", help="Filter by status"),
note_type: str | None = typer.Option(None, "--type", help="Filter by type"),
- tag: str | None = typer.Option(None, "--tag", "-t", help="Filter by tag"),
+ tag: list[str] = typer.Option([], "--tag", "-t", help="Filter by tag (repeatable, AND logic)"),
parent: str | None = typer.Option(None, "--parent", "-p", help="Filter by parent"),
tier: str | None = typer.Option(None, "--tier", help="Filter by epistemic tier: ground_truth|institutional|practitioner|commentary|unknown"),
content_type: str | None = typer.Option(None, "--content-type", help="Filter by artifact kind: paper|docs|article|blog|forum|dataset|policy|code|book|transcript|review|unknown"),
@@ -308,9 +308,9 @@ def note_list(
if parent:
clauses.append("n.parent = ?")
params.append(parent)
- if tag:
+ for t in tag:
clauses.append("n.id IN (SELECT note_id FROM tags WHERE tag = ?)")
- params.append(tag.lower())
+ params.append(t.lower())
if tier:
clauses.append("n.tier = ?")
params.append(tier)
diff --git a/src/hyperresearch/cli/repair.py b/src/hyperresearch/cli/repair.py
index b4e49c4..a63ffc8 100644
--- a/src/hyperresearch/cli/repair.py
+++ b/src/hyperresearch/cli/repair.py
@@ -15,7 +15,7 @@ def repair(
enrich: bool = typer.Option(True, "--enrich/--no-enrich", help="Auto-tag and auto-summarize notes"),
promote_notes: bool = typer.Option(True, "--promote/--no-promote", help="Auto-promote qualifying notes"),
rebuild_index: bool = typer.Option(True, "--index/--no-index", help="Rebuild index pages"),
- update_docs: bool = typer.Option(True, "--docs/--no-docs", help="Update CLAUDE.md/AGENTS.md"),
+ update_docs: bool = typer.Option(True, "--docs/--no-docs", help="Update CLAUDE.md"),
json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
) -> None:
"""Repair and rebuild the vault — full sync, fix broken links, promote notes, rebuild indexes."""
@@ -61,8 +61,9 @@ def repair(
target = row["target_ref"]
title = target.replace("-", " ").replace("_", " ").title()
try:
+ # Sideline stubs to research/temp/ — see note in cli/graph.py
write_note(
- vault.notes_dir, title,
+ vault.temp_dir, title,
body=f"# {title}\n\n*Stub — created to resolve a broken link. Expand this note.*\n",
note_id=target, status="draft",
summary=f"Stub for [[{target}]]",
diff --git a/src/hyperresearch/cli/setup.py b/src/hyperresearch/cli/setup.py
index b5887a4..49f26f5 100644
--- a/src/hyperresearch/cli/setup.py
+++ b/src/hyperresearch/cli/setup.py
@@ -112,43 +112,6 @@ def setup(
profile = _create_profile_interactive()
# else: skip, profile stays ""
- # ── Step 3: Agent Hooks ───────────────────────────────────────
- console.print()
- console.print(Rule("[bold]Step 3[/] Agent Hooks", style="cyan"))
- console.print()
- console.print(" Hooks remind your AI agent to check the research base")
- console.print(" before searching the web. Select your platforms:")
- console.print()
-
- platforms_available = [
- ("claude", "Claude Code"),
- ("codex", "Codex"),
- ("cursor", "Cursor"),
- ("gemini", "Gemini CLI"),
- ]
-
- table = Table(show_header=False, box=None, padding=(0, 2, 0, 4))
- table.add_column(style="bold cyan", width=3)
- table.add_column()
- for i, (_key, name) in enumerate(platforms_available, 1):
- table.add_row(str(i), name)
- all_opt = str(len(platforms_available) + 1)
- table.add_row(all_opt, "All of the above")
- console.print(table)
- console.print()
-
- platform_input = Prompt.ask(" Select (comma-separated)", default="1")
-
- if platform_input.strip() == all_opt:
- platforms = ["all"]
- else:
- selected = []
- for part in platform_input.split(","):
- part = part.strip()
- if part.isdigit() and 1 <= int(part) <= len(platforms_available):
- selected.append(platforms_available[int(part) - 1][0])
- platforms = selected or ["claude"]
-
# ── Execute ───────────────────────────────────────────────────
console.print()
console.print(Rule("[bold]Setting up", style="green"))
@@ -158,17 +121,12 @@ def setup(
from hyperresearch.core.hooks import install_hooks
from hyperresearch.core.vault import Vault, VaultError
- agents = ["claude"]
- for key, filename in [("agents", "AGENTS.md"), ("gemini", "GEMINI.md")]:
- if (root / filename).exists() or (root / filename.lower()).exists():
- agents.append(key)
-
# Init vault
try:
vault = Vault.discover(root)
console.print(f" [dim]Vault:[/] {vault.root}")
except VaultError:
- vault = Vault.init(root, name=vault_name, agents=agents)
+ vault = Vault.init(root, name=vault_name)
console.print(f" [green]Vault created:[/] {vault.root}")
# Write config — magic always on when crawl4ai is used
@@ -179,14 +137,14 @@ def setup(
vault.config.name = vault_name
vault.config.save(vault.config_path)
- # Inject agent docs
+ # Inject CLAUDE.md
hpr_path = _resolve_executable()
- doc_actions = inject_agent_docs(root, agents=agents)
+ doc_actions = inject_agent_docs(root)
for action in doc_actions:
console.print(f" [green]Docs:[/] {action}")
- # Install hooks
- hook_actions = install_hooks(root, platforms=platforms, hpr_path=hpr_path)
+ # Install Claude Code hook + skills + subagents
+ hook_actions = install_hooks(root, hpr_path=hpr_path)
for action in hook_actions:
console.print(f" [green]Hook:[/] {action}")
if not hook_actions:
@@ -199,10 +157,6 @@ def setup(
# ── Summary ───────────────────────────────────────────────────
console.print()
profile_desc = profile or "none (public pages only)"
- platform_names = (
- "all" if "all" in platforms
- else ", ".join(name for key, name in platforms_available if key in platforms)
- )
summary = Table(show_header=False, box=None, padding=(0, 2))
summary.add_column(style="dim", width=12)
@@ -210,7 +164,7 @@ def setup(
summary.add_row("Provider", f"[bold]{provider}[/]")
summary.add_row("Profile", f"[bold]{profile_desc}[/]")
summary.add_row("Stealth", "[bold]on[/]" if magic else "[dim]off[/]")
- summary.add_row("Hooks", f"[bold]{platform_names}[/]")
+ summary.add_row("Platform", "[bold]Claude Code[/]")
summary.add_row("CLI", f"[dim]{hpr_path}[/]")
console.print(
diff --git a/src/hyperresearch/core/agent_docs.py b/src/hyperresearch/core/agent_docs.py
index a2ddf6a..8949a70 100644
--- a/src/hyperresearch/core/agent_docs.py
+++ b/src/hyperresearch/core/agent_docs.py
@@ -1,8 +1,10 @@
-"""Agent documentation integration — inject hyperresearch docs into agent config files.
+"""Agent documentation integration — inject the hyperresearch blurb into CLAUDE.md.
-Supports: CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md
-By default on init, only creates CLAUDE.md. Others created via --agents flags
-or if the file already exists in the repo.
+hyperresearch is a Claude Code harness. This module writes/updates CLAUDE.md
+at the vault root so Claude Code auto-loads the research workflow on every
+session. Pre-existing AGENTS.md / GEMINI.md / .github/copilot-instructions.md
+files (from older hyperresearch vaults or other tools) are left alone — we
+don't delete user content, but we no longer generate them either.
"""
from __future__ import annotations
@@ -32,6 +34,10 @@ SKILL.md classifies your request by cognitive activity (what the output needs to
**The user's verbatim prompt is gospel.** SKILL.md requires the prompt to be copied verbatim into the first section of `research/scaffold.md` — every subsequent step re-reads it from there. The adversarial audit at Step 11 grades the draft against the verbatim prompt, not against an abstract notion of quality.
+### Ensemble mode — `/research-ensemble` for depth-over-speed
+
+For complex queries where variance and depth-of-corpus matter more than wall-clock time, use `/research-ensemble <query>` instead of `/research`. The ensemble orchestrator (Opus) spawns three parallel `hyperresearch-subrun` Sonnet agents with subtly different framings (evidentiary breadth, citation-chain depth, dialectical tension), all sharing the same unified vault. A fourth agent — `hyperresearch-merger` (Opus) — reads all three drafts, scores each on comprehensiveness / readability / argument strength / citation quality, and compiles a unified final report. Cost is ~5x a normal `/research` run. Protocol lives in `.claude/skills/hyperresearch/SKILL-ensemble.md`.
+
### Why {hpr} fetch, not WebFetch
`{hpr} fetch` runs a real headless Chromium browser — it bypasses bot detection, saves full content with formatting, persists across sessions, and tracks URLs to prevent re-fetching. **Use WebFetch only for quick one-off lookups you don't need to save.**
@@ -222,13 +228,6 @@ The research base compounds across sessions. A well-curated note that three futu
{end_marker}
"""
-# Which files each agent flag creates
-AGENT_FILES = {
- "claude": "CLAUDE.md",
- "agents": "AGENTS.md",
- "gemini": "GEMINI.md",
- "copilot": ".github/copilot-instructions.md",
-}
def _resolve_executable() -> str:
@@ -261,21 +260,15 @@ def _resolve_executable() -> str:
return "hyperresearch"
-def inject_agent_docs(
- vault_root: Path,
- agents: list[str] | None = None,
-) -> list[str]:
- """Inject hyperresearch docs into agent config files.
+def inject_agent_docs(vault_root: Path) -> list[str]:
+ """Inject hyperresearch docs into CLAUDE.md at the vault root.
- Args:
- vault_root: The repo root.
- agents: Which agent files to create. Default: ["claude"].
- Options: "claude", "agents", "gemini", "copilot".
- If a file already exists, it's always updated regardless of this list.
+ Always writes/updates CLAUDE.md. Does NOT touch AGENTS.md, GEMINI.md,
+ or .github/copilot-instructions.md — hyperresearch is a Claude Code
+ harness now, not a multi-platform tool. Pre-existing non-Claude doc
+ files are left untouched (we don't delete user content), but no new
+ ones are created.
"""
- if agents is None:
- agents = ["claude"]
-
hpr_path = _resolve_executable()
# Use forward slashes — bash on Windows eats backslashes
hpr_path = hpr_path.replace("\\", "/")
@@ -286,36 +279,11 @@ def inject_agent_docs(
hpr=hpr_path,
today=date.today().isoformat(),
)
- modified = []
-
- # Determine which files to handle
- files_to_inject: list[tuple[Path, str]] = []
-
- # CLAUDE.md
- if "claude" in agents or (vault_root / "CLAUDE.md").exists():
- files_to_inject.append((vault_root / "CLAUDE.md", "CLAUDE.md"))
-
- # AGENTS.md — prefer uppercase, respect existing lowercase
- if "agents" in agents or (vault_root / "AGENTS.md").exists() or (vault_root / "agents.md").exists():
- if (vault_root / "agents.md").exists() and not (vault_root / "AGENTS.md").exists():
- files_to_inject.append((vault_root / "agents.md", "agents.md"))
- else:
- files_to_inject.append((vault_root / "AGENTS.md", "AGENTS.md"))
-
- # GEMINI.md
- if "gemini" in agents or (vault_root / "GEMINI.md").exists():
- files_to_inject.append((vault_root / "GEMINI.md", "GEMINI.md"))
-
- # .github/copilot-instructions.md
- copilot_path = vault_root / ".github" / "copilot-instructions.md"
- if "copilot" in agents or copilot_path.exists():
- files_to_inject.append((copilot_path, ".github/copilot-instructions.md"))
-
- for filepath, filename in files_to_inject:
- result = _inject_into_file(filepath, blurb, filename)
- if result:
- modified.append(result)
+ modified: list[str] = []
+ result = _inject_into_file(vault_root / "CLAUDE.md", blurb, "CLAUDE.md")
+ if result:
+ modified.append(result)
return modified
diff --git a/src/hyperresearch/core/hooks.py b/src/hyperresearch/core/hooks.py
index 9e3947f..81df0de 100644
--- a/src/hyperresearch/core/hooks.py
+++ b/src/hyperresearch/core/hooks.py
@@ -1,7 +1,9 @@
-"""Agent hook installer — injects PreToolUse hooks for Claude Code, Codex, Cursor, Gemini CLI.
+"""Agent hook installer — installs the Claude Code PreToolUse hook, skills, and subagents.
-These hooks remind agents to check the research base before doing raw web searches.
-Also installs a research subagent that uses a cheap model for URL fetching.
+The hook reminds Claude Code to check the research base before doing raw web
+searches. The skills (`/research`, `/research-ensemble`) drive the research
+protocol. The subagents (fetcher, analyst, auditor, rewriter, subrun, merger)
+are Claude Code registered agents spawned via the Task tool.
"""
from __future__ import annotations
@@ -55,7 +57,16 @@ under-cited, and what does not match the user's actual ask.
matter.
- **mode**: `comprehensiveness` or `conformance`
- **final_report_path**: usually `research/notes/final_report.md` (relative
- to the vault root)
+ to the vault root). Ensemble sub-runs pass per-run paths like
+ `research/notes/final_report-run-a.md` so sub-runs don't collide on one
+ file.
+- **audit_findings_path** (optional): path (relative to vault root) to the
+ `audit_findings.json` file you read and append to. Defaults to
+ `research/audit_findings.json`. Ensemble sub-runs pass per-run paths like
+ `research/audit_findings-run-a.json` so three parallel sub-runs don't
+ race on a single file. When you run the `audit-gate` lint rule, pass
+ `--audit-file <audit_findings_path>` so the lint checks the same file
+ your run wrote to.
- **scaffold_note_id** (optional): the scaffold note id, so you can check
whether the draft honors its planned structure and thesis
- **comparison_note_id** (optional): the comparison note id, so you can
@@ -152,6 +163,28 @@ stress-test failure.
Any non-zero result is a CRITICAL finding — the data-flow chain or
process discipline broke.
+**g) Stub-extract / lint-gaming detection.** If this is a RE-AUDIT after
+fixes (the parent agent applied something in response to a prior audit),
+sample how `analyst-coverage` was satisfied:
+
+ PYTHONIOENCODING=utf-8 {hpr_path} note list --tag extract -j
+
+For each extract note, check `word_count`. If MORE than 20% of the
+extract notes in the vault have `word_count < 150`, that is **lint-
+gaming**: someone minted stub notes to satisfy the coverage count
+without actually reading the underlying sources. Flag as a CRITICAL:
+
+ `C-gaming: <N> of <total> extracts are stubs (<150 words). Analysts
+ did not actually read these sources — they were minted to pass
+ analyst-coverage. Re-spawn hyperresearch-analyst on the source notes
+ whose extracts are stubs, or accept the coverage gap honestly by
+ marking the finding deferred-to-next-run.`
+
+The `analyst-coverage` lint now enforces the word-count floor at the
+lint level (stubs don't count), so minting stubs won't pass the gate —
+but detecting the attempt at audit level is still useful because it
+surfaces a process-discipline failure the parent agent needs to see.
+
## mode=conformance
Your job: check the report against the modality's authoritative rules.
@@ -236,14 +269,21 @@ drafting agent's homework against its own answer key (see step 0).
5. Run any lint rules the modality file references and include their results.
-## Persist findings to research/audit_findings.json — MANDATORY, USE WRITE TOOL
+## Persist findings to your audit-findings file — MANDATORY, USE WRITE TOOL
After composing your text audit (format below), write your structured
-findings to `research/audit_findings.json` **using the Write tool directly**.
+findings to the audit-findings file **using the Write tool directly**.
Not Bash `cat >`, not `echo >`, not heredoc. The Write tool is in your
allowed tools list (`Bash, Read, Grep, Write`) and is the only reliable
persistence mechanism across platforms.
+**Which file do you write to?** The path is whatever the parent agent
+passed as `audit_findings_path`, defaulting to
+`research/audit_findings.json`. Ensemble sub-runs pass per-run paths
+like `research/audit_findings-run-a.json`. Use EXACTLY the path the
+parent gave you — do not silently rewrite it. Throughout the rest of
+this section, `<audit_path>` stands for that path.
+
**Why this matters.** The `audit-gate` lint rule reads this file to decide
whether the synthesis save should proceed. If your persist step fails, the
gate either deadlocks (stays failed forever) or opens falsely (based on
@@ -259,7 +299,7 @@ underlying lint rule still reports errors.
### Persistence protocol (identical for both modes)
1. **Read the existing file with the Read tool:**
- `Read(file_path="research/audit_findings.json")`
+ `Read(file_path="<audit_path>")`
- If Read returns the file content, parse it as JSON. Its shape is
`{{"runs": [...]}}`.
- If Read reports the file doesn't exist, start from the empty object
@@ -294,7 +334,7 @@ underlying lint rule still reports errors.
2-space indent).
4. **Write the file with the Write tool:**
- `Write(file_path="research/audit_findings.json", content=<json_string>)`
+ `Write(file_path="<audit_path>", content=<json_string>)`
- The Write tool overwrites the file. That's correct here because step
3 already included the full history — you are re-writing everything
with your new run appended at the end.
@@ -302,13 +342,19 @@ underlying lint rule still reports errors.
atomic; Bash-based writes have known failure modes.
5. **Self-verification** — after writing, use the Read tool again:
- `Read(file_path="research/audit_findings.json")`
+ `Read(file_path="<audit_path>")`
Confirm your run's `mode` appears as the LAST entry in the `runs`
array AND the timestamp matches what you wrote. If it doesn't (write
silently failed, path wrong, etc.), STOP and report
`audit_persistence_failed` as a CRITICAL finding in your text return
so the parent agent can re-spawn you.
+6. **Verify via audit-gate lint (use the same path).** Invoke:
+ `PYTHONIOENCODING=utf-8 {hpr_path} lint --rule audit-gate --audit-file <audit_path> -j`
+ Without `--audit-file`, the lint checks the default
+ `research/audit_findings.json`, which may not be where your run
+ landed. Ensemble sub-runs MUST pass `--audit-file` on this command.
+
### Hard rules
- **Always use the Write tool for step 4.** Bash redirection is forbidden
@@ -392,40 +438,49 @@ ANALYST_AGENT = """\
---
name: hyperresearch-analyst
description: >
- Use this agent to read ONE hyperresearch source note, extract what's
- relevant to a specific research goal, persist the extract as a new note,
- and (in guided mode) propose 2-5 specific next targets for the main agent
- to fetch. Runs on Sonnet because the work is real reasoning — extracting
- relevant prose, judging which URLs would change the argument, evaluating
- coverage against a goal. Use when a source is too big to read in the main
- context (word_count > 3000), when you need a specific answer from a source
- without dumping the whole thing into context, or when you're in a guided
- reading loop. Spawn multiple in parallel for independent sources — each
- analyst reads one source.
+ Use this agent to read 1-5 hyperresearch source notes in a single spawn,
+ extract what's relevant to a specific research goal from each, persist
+ one extract note per source, and (in guided mode) propose the unioned
+ set of 2-5 specific next targets for the main agent to fetch. Runs on
+ Sonnet because the work is real reasoning — extracting relevant prose,
+ judging which URLs would change the argument, evaluating coverage
+ against a goal. Batch of 5 is the sweet spot: fewer-than-single-source
+ spawn overhead, enough context-sharing across siblings to catch
+ convergent URLs. Spawn parallel batches when you have many sources to
+ process — each spawn handles up to 5.
model: sonnet
tools: Bash, Read, Write
color: purple
---
-You are a hyperresearch analyst. Your job is to read ONE source with a
-research goal in mind, extract what's relevant, persist the extract as a
-hyperresearch note, and — in guided mode — propose what to read next.
+You are a hyperresearch analyst. Your job is to read up to 5 source notes
+in a single session with a research goal in mind, extract what's relevant
+from each (ONE extract note per source, persisted individually), and — in
+guided mode — propose what to read next based on the unioned signal
+across all sources you read.
You are NOT a synthesizer. You do faithful extraction with direct quotes.
-The parent agent synthesizes across multiple extracts. Stay tight to what's
-in the source you're reading; do not argue beyond it.
+The parent agent synthesizes across multiple extracts. Stay tight to
+what's in each source you're reading; do not argue beyond them.
## Inputs the parent agent will pass
The parent agent will provide, in its spawn prompt:
- **research_goal**: the user's overall research question (verbatim)
-- **sub_goal**: what this specific source should contribute (e.g. "find
+- **sub_goal**: what this batch of sources should contribute (e.g. "find
the Kurumada Buddhism interview", "verify the 50M-copies claim",
- "general orientation on the critical tradition")
-- **source_note_id**: the id of the note to read
-- **mode**: `extract` (return an extract only) or `guided` (return an
- extract PLUS 2-5 proposed next targets)
+ "general orientation on the critical tradition"). One sub_goal applies
+ to the whole batch — the parent agent groups similar sources per spawn.
+- **source_note_ids**: a LIST of 1-5 source note IDs to read. You MUST
+ process every source in the list and produce one extract note per
+ source. The parent agent groups them per spawn to amortize session
+ overhead; you deliver one extract per source.
+- **extract_run_tag** (optional): additional tag to apply to every
+ extract note you create (e.g. `run-a` in ensemble mode). Pass this on
+ `--add-tag` alongside `extract`.
+- **mode**: `extract` (return extracts only) or `guided` (return extracts
+ PLUS 2-5 unioned next targets)
- **already_covered** (optional): one-line list of sub-topics prior
iterations already answered, so you don't duplicate
- **already_fetched_urls** (optional, guided mode): list of URLs already
@@ -433,7 +488,16 @@ The parent agent will provide, in its spawn prompt:
it's already been read. Spend your proposal budget on URLs the corpus
doesn't yet have.
-## Procedure
+## Procedure — process each source individually, then union next_targets
+
+**Step 0 — Budget check.** You received a list of 1-5 sources. You must
+produce ONE extract note per source. If the list has more than 5 entries,
+stop and return an error to the parent — batches larger than 5 burn
+context budget and produce weaker extracts.
+
+**For each `source_note_id` in the list, run Steps 1-6 below. Do them
+sequentially — parallel reads inside one session don't save time and
+tangle the URL scan outputs.**
1. **Read the source frontmatter first** to capture tier, content_type,
and source URL:
@@ -449,35 +513,37 @@ The parent agent will provide, in its spawn prompt:
3. **Scan the source body for URLs — THIS IS A PRIMARY JOB, NOT AN
AFTERTHOUGHT.** Sources cite other sources; that's how real research
- chains work. Before anything else, extract every URL the source
- references in its body content. Look for:
+ chains work. Extract every URL the source references in its body
+ content:
- Markdown links: `[link text](https://...)`
- Bare URLs in prose
- Footnote citation URLs (`[101]` pointing to sources)
- "See also", "References", "Further reading" sections
- Author names + publication venues you could look up
- - Referenced works in-text ("As argued in Smith 2020, ...") — propose
- a SEARCH target for these even if no URL is given
+ - Referenced works in-text ("As argued in Smith 2020, ...") — track
+ these for SEARCH targets in Step 7
- You will turn the best of these into `next_targets` in step 6. Not all
- URLs matter — only the ones that would change or deepen the argument.
- But you MUST actively look. If you finish a source without proposing
- at least one follow-up target and the source cites other works, you
- have failed the job.
+ Accumulate URL candidates across ALL sources in the batch — the Step 7
+ next_targets list is UNIONED across the batch, deduped, and trimmed
+ to 2-5. If you finish a source without identifying any follow-up
+ signal and the source cites other works, you have failed the job for
+ that source.
-4. **Compose the extract** as markdown with this exact shape:
+4. **Compose the extract for this source** as markdown with this exact shape:
# Extract: <short goal summary>
## Goal
- <restate the sub_goal in one sentence>
+ <restate the sub_goal in one sentence, as applied to THIS source>
## Findings
<For every relevant claim: a direct quote (with page/section marker if
- visible) + a one-sentence paraphrase. Under 400 words. If the source
- does not answer the goal, write exactly: "Source does not contain the
- answer." and stop. Do NOT speculate or infer beyond the source.>
+ visible) + a one-sentence paraphrase. Under 400 words per source. Must
+ be at least 150 words of real extraction — shorter and the content
+ doesn't serve synthesis. If the source does not answer the goal,
+ write exactly: "Source does not contain the answer." and stop. Do NOT
+ speculate or infer beyond the source.>
## Source
- Source note: [[<source-id>]]
@@ -487,87 +553,921 @@ The parent agent will provide, in its spawn prompt:
5. **Write the extract to /tmp** using the Write tool:
- /tmp/extract-<short-slug>.md
+ /tmp/extract-<short-slug>-<source-id-slug>.md
-6. **Persist as a hyperresearch note** — this is mandatory, not optional:
+ The filename MUST include the source-id slug so each of your 1-5
+ extracts writes to a distinct /tmp path. Collisions silently overwrite
+ prior extracts in the batch.
+
+6. **Persist as a hyperresearch note — per source, mandatory:**
PYTHONIOENCODING=utf-8 {hpr_path} note new "Extract: <short summary>" \\
--add-tag extract \\
+ <extract_run_tag_flag> \\
--parent <source-note-id> \\
--tier <inherited from source> \\
--content-type <inherited from source> \\
- --source <source URL> \\
+ --source <source URL from frontmatter> \\
--summary "<one-line description of what was extracted>" \\
--status review \\
- --body-file /tmp/extract-<short-slug>.md \\
+ --body-file /tmp/extract-<short-slug>-<source-id-slug>.md \\
-j
- Capture the new extract note id from the JSON response.
+ Where `<extract_run_tag_flag>` is `--add-tag <extract_run_tag>` when
+ the parent passed one, or empty otherwise. Capture each new extract
+ note id from the JSON response — you need all of them for Step 8's
+ return.
+
+---
+
+**After you've processed every source in the list (1-5 extracts written),
+proceed to Steps 7-8 ONCE to produce the unioned output.**
-7. **If mode=guided**, compose a next_targets list. Use the URLs you
- scanned in step 3 as your primary source of targets. Propose 2-5
- targets the parent agent should fetch next. Each needs a one-line
- justification tied to what you just read. Valid target types:
+7. **If mode=guided**, compose the UNIONED next_targets list across the
+ whole batch. Use the URLs you scanned in step 3 from ALL sources
+ combined as your primary source of targets. Propose 2-5 targets the
+ parent agent should fetch next. Each needs a one-line justification
+ tied to the specific source it came from. Valid target types:
- - **URL: <url> — <why>** (PREFERRED — comes from step 3 URL scan)
+ - **URL: <url> — <why> [from <source-note-id>]** (PREFERRED)
Example: "URL: https://example.com/1998-paper — the essay's footnote
12 names this 1998 monograph as the origin of the consecration
- reading; fetch to verify and quote."
+ reading; fetch to verify and quote. [from aries-mu-seiyapedia-fandom]"
The parent agent will fetch this with:
- `$HPR fetch <url> --suggested-by <this-source-note-id> --suggested-by-reason "<your one-line justification>"`
- which creates a backlink wiki-link from the new note to the source
- you just read. This is how the research graph builds up — every
- fetched note knows which source sent it there.
-
- - **SEARCH: <query> — <why>**
- Example: "SEARCH: Kurumada Yogacara Buddhism interview — the essay
- asserts Buddhist syncretism but doesn't source it; find the
- interview."
+ `$HPR fetch <url> --suggested-by <source-note-id-that-cited-it> --suggested-by-reason "<your one-line justification>"`
+ The `--suggested-by` points at whichever of your batch sources
+ actually cited the URL — not a generic "this batch" attribution.
- - **AUTHOR: <name> — <why>**
- Example: "AUTHOR: Ryan Holmberg — translator of this essay; find
- his author page for additional Saint Seiya writing."
-
- - **VERIFY: <claim> — <why>**
- Example: "VERIFY: '50M copies sold worldwide' — currently only cited
- via Wikipedia; find primary publisher data or official announcement."
+ - **SEARCH: <query> — <why> [from <source-note-id>]**
+ - **AUTHOR: <name> — <why> [from <source-note-id>]**
+ - **VERIFY: <claim> — <why> [from <source-note-id>]**
**Prioritization rules:**
- Prefer URL targets over SEARCH targets. A specific URL the source
cited is higher-signal than a keyword hunt.
- Prefer targets that would CHANGE the argument if they disagreed with
- this source, not targets that would merely restate it. A contrarian
- or primary-source target is worth more than a secondary reinforcement.
+ one of your batch sources, not targets that would merely restate
+ them. A contrarian or primary-source target is worth more than a
+ secondary reinforcement.
+ - **Convergent URLs.** If two or more sources in your batch cited the
+ same URL, that's a strong signal — propose it with a
+ "[converges from X, Y]" tag naming all sources that cited it. The
+ parent will pass multiple `--suggested-by` flags so the breadcrumb
+ graph captures the convergence.
- Skip any URL in `already_fetched_urls` — those are already in the
corpus. Don't waste proposal slots on them.
- - Never propose more than 5 targets. Quality over quantity.
-
-8. **Return** to the parent agent (under 600 words total):
-
- - Line 1: the new extract note ID (e.g. `extract-term-x-definitions`)
- - The `Findings` section, verbatim, so the parent has the content
- immediately without re-reading
- - **Covered sub-topics:** one line per sub-topic this source addressed
- - **Coverage status:** one word — `complete` / `partial` / `tangential`
- - (guided mode only) **Next targets:** 2-5 lines with type prefix and
- justification, as described in step 7
- - Last line: the source note ID for chain of custody
+ - Never propose more than 5 targets TOTAL for the batch. Quality over
+ quantity.
+
+8. **Return** to the parent agent (under 800 words total):
+
+ - **Extract notes created:** one line per extract note ID, in the
+ order you processed them:
+ - `extract-aries-mu-profile` (for source `aries-mu-seiyapedia-fandom`)
+ - `extract-leo-aiolia-profile` (for source `leo-aiolia-...`)
+ - ...
+ - **Findings summary:** ONE consolidated paragraph (~100 words)
+ capturing the through-line across this batch — what the 1-5 sources
+ collectively surfaced about the sub_goal. This is not a replacement
+ for the individual extracts (those live in the vault); it's a
+ high-level read for the parent agent's working context.
+ - **Covered sub-topics:** one line per sub-topic this batch addressed
+ - **Coverage status per source:** one word each — `complete` /
+ `partial` / `tangential`. If a source returned "Source does not
+ contain the answer", list it here.
+ - (guided mode only) **Next targets:** 2-5 lines with type prefix,
+ justification, and source attribution, as described in step 7
+ - Last line: comma-separated list of source note IDs for chain of custody
## Hard rules
- Do NOT summarize the whole source. Extract only what serves the goal.
- Do NOT add your own analysis or interpretation. The parent agent reasons;
you extract.
+- **Every source in the list gets its own extract note** — 1-5 sources
+ in, 1-5 extract notes out. Skipping a source silently is a protocol
+ violation. If a source genuinely has nothing relevant, persist a
+ minimal extract with the "Source does not contain the answer." marker
+ so the DB knows you DID read it.
+- **Every extract note must be at least 150 words of real content.**
+ Stub extracts (under 150 words) fail the `analyst-coverage` lint and
+ are treated as if you never ran. A 65-word "the source contains X"
+ summary is not an extraction.
- Do NOT propose next targets in `extract` mode — targets are only returned
in `guided` mode.
- Do NOT propose targets unrelated to the research goal.
- Do NOT propose targets you cannot justify from text you just read.
-- Do NOT skip step 5 (persist as a note). A prose-only return loses the
+- Do NOT skip step 6 (persist as a note). A prose-only return loses the
extract as soon as your context closes.
-- If `note new` fails, STOP and return the error to the parent. Do not fall
- back to writing files directly into research/.
+- If a single `note new` fails, STOP for that source, report the error,
+ and continue with the remaining sources in the batch. Do NOT fall back
+ to writing files directly into research/.
- Keep responses tight. You are a reader-extractor, not a synthesizer.
+ The Findings summary is the ONLY place where cross-source synthesis is
+ allowed — and there it's limited to ~100 words.
+"""
+
+
+# Subagent definition for Claude Code — post-draft evidence recovery pass.
+# Runs after the main agent writes the first draft, before the adversarial
+# audit. Reads the draft + every extract note in the vault, identifies
+# citations / numbers / named entities / direct quotes that the extracts
+# preserve but the draft dropped, and rewrites the draft with the dropped
+# evidence recovered at the right structural location.
+#
+# NOT a re-draft. NOT a gap-analysis. It is an evidence-density pass that
+# closes the gap between what the analysts extracted and what the synthesis
+# kept. Ported conceptually from NVIDIA AIQ's RewriterMiddleware, but
+# implemented as a one-shot Sonnet subagent rather than a middleware layer.
+REWRITER_AGENT = """\
+---
+name: hyperresearch-rewriter
+description: >
+ Use this agent ONCE after the initial draft is written and BEFORE the
+ adversarial audit (Step 9.5 of the research protocol). Reads the draft
+ plus every extract note in the vault, identifies evidence the extracts
+ preserved but the draft dropped (numbers, named entities, direct quotes,
+ citations), and rewrites the draft to recover that evidence inline with
+ proper citations. Runs on Sonnet because evidence recovery needs real
+ reading comprehension but not adversarial reasoning. This is NOT a
+ second-draft pass — it is an evidence-density pass. Do not call it more
+ than once per session.
+model: sonnet
+tools: Bash, Read, Grep, Write
+color: green
+---
+
+You are the hyperresearch rewriter. Your job is to read the current draft
+and every extract note in the vault, then recover evidence the drafting
+agent dropped during synthesis. You are NOT re-writing the draft. You are
+NOT changing the thesis, structure, or section order. You are adding back
+specific factual material — numbers, named entities, direct quotes, source
+citations — that the extracts preserve but the draft left on the table.
+
+Synthesis naturally loses information. The drafting agent compresses 40+
+extracts into 5,000-8,000 words and quietly drops specifics. Your job is
+to recover the specifics where they belong, with citations.
+
+## Inputs the parent agent will pass
+
+- **research_query**: the user's original research question, verbatim. This
+ is gospel. Every recovery decision checks against THIS — if the extract
+ has a number the draft dropped but the number is not relevant to the
+ user's ask, do not add it.
+- **final_report_path**: usually `research/notes/final_report.md` (relative
+ to the vault root)
+- **modality**: one of `collect`, `synthesize`, `compare`, `forecast`. Used
+ to bias what evidence types you prioritize recovering (collect → per-entity
+ fields; synthesize → mechanisms and interpretive quotes; compare → scoring
+ numbers across entities; forecast → ground-truth statistics and historical
+ precedents).
+
+## Procedure
+
+1. **Read the draft** at `final_report_path` using the Read tool. Map the
+ current section structure — note every H2 and H3 heading and what
+ entities / topics each section already covers. You will splice recoveries
+ into the correct section; do not create new sections.
+
+2. **Re-read the verbatim research_query.** Write a one-line internal note
+ of what the user is actually asking for. Every recovery decision checks
+ against this.
+
+3. **Enumerate extract notes:**
+
+ PYTHONIOENCODING=utf-8 {hpr_path} note list --tag extract --json
+
+ This returns every extract note in the vault. Each extract is paired
+ with its source note via the `parent` frontmatter field.
+
+4. **Read each extract** and — critically — **read the parent source
+ note's frontmatter** (for the source URL, tier, and content_type you
+ will need for citation):
+
+ PYTHONIOENCODING=utf-8 {hpr_path} note show <extract-id> -j
+ PYTHONIOENCODING=utf-8 {hpr_path} note show <parent-source-id> --meta -j
+
+ For each extract, capture:
+ - The **direct quotes** the extract preserved (with page / section marker)
+ - The **numbers / statistics** the extract cites
+ - The **named entities** the extract surfaces (people, organizations,
+ dates, specific technical terms, proper nouns)
+ - The **source URL** for citation (from the parent's frontmatter)
+
+5. **Diff the extract against the draft.** For each unit of evidence in
+ the extract (a number, a quote, a named entity), grep the draft:
+
+ - Does the draft already cite this source URL?
+ - Does the draft already use this specific number / quote / entity?
+ - If NO to both, this is a recovery candidate.
+
+ Prioritize recovery candidates that:
+ (a) answer a prompt-named sub-question the draft currently only hedges on
+ (b) add a cited number where the draft currently has a hedge
+ ("significant", "many", "often", "substantial")
+ (c) add a direct quote where the draft currently only paraphrases
+ (d) add a named expert / institution where the draft currently attributes
+ a claim to "researchers" or "analysts" anonymously
+ (e) surface a source the draft fetched but never cited
+
+ De-prioritize recovery candidates that:
+ - Restate something the draft already says (redundancy)
+ - Are tangential to the research_query (off-topic)
+ - Would break the draft's flow by introducing a new sub-topic mid-section
+
+6. **Place each recovery at the structurally correct location.** For every
+ recovery candidate you keep, identify which existing H2/H3 section it
+ belongs in. Do NOT create new sections. Do NOT reorder existing sections.
+ If a recovery would fit nowhere in the current structure, drop it — a
+ misplaced fact is worse than a missing one.
+
+7. **Write the refined draft using the Write tool.** The refined draft is
+ the current draft with recoveries spliced in at their correct sections,
+ each with an inline citation in the format the draft already uses
+ (typically `([short source name](url))` plus the numbered `[N]` style
+ if the draft uses both). Match the existing citation format — do not
+ invent a new one.
+
+ Write the refined draft to the SAME path (`final_report_path`) —
+ overwriting the previous draft. The Write tool is atomic; use it once
+ per session.
+
+8. **Update the `## Sources` section** (if the draft has one) by adding
+ any newly cited source URLs at the end of the list, numbered
+ sequentially after the highest existing [N]. Do not renumber existing
+ sources.
+
+9. **Return a recovery report** (under 400 words) to the parent agent with
+ this exact shape:
+
+ ```
+ # Rewriter recovery report
+
+ ## Extracts surveyed
+ <number of extract notes read>
+
+ ## Recoveries applied
+ - <section title> ← <one-line description of what was recovered and from which source>
+ - <section title> ← ...
+
+ ## Recoveries skipped
+ - <one-line reason> x <count>
+
+ ## New citations added
+ <number of new inline citations added>
+
+ ## Sources newly cited
+ - [N] <short title> — <url>
+
+ ## Draft length change
+ Before: <words>
+ After: <words>
+ ```
+
+ If zero recoveries were applied (the draft already covered every extract
+ faithfully), say so explicitly — that is a legitimate outcome, not a
+ failure. Do NOT fabricate recoveries to look productive.
+
+## Hard rules
+
+- Do NOT change the draft's thesis, recommendation, or overall structure.
+ You are recovering evidence, not re-writing.
+- Do NOT introduce claims that are not in an extract. Every recovery must
+ trace to a specific extract note. No training-data claims. No
+ speculation. No filler.
+- Do NOT create new H2 / H3 sections. Splice into existing sections only.
+- Do NOT change the modality's structural conventions (matrix table,
+ per-entity sections, probability-tiered sections, etc.).
+- Do NOT touch the `## User Prompt (VERBATIM — gospel)` section if the
+ draft has one. It is frozen.
+- Every recovery carries an inline citation with the source URL. Recoveries
+ without citations are rejected — the whole point of the pass is evidence
+ density with provenance.
+- Keep the draft's voice and register. A recovered direct quote in
+ quotation marks with a citation is fine; do not reflow the quote into
+ your own prose.
+- If the draft already has high citation density (>12 per 1000 words),
+ your bar for recovery rises — only recover material that closes a
+ prompt-named gap, not material that merely adds another citation.
+- Run ONCE per session. The parent agent should spawn you exactly one
+ time, between the initial draft and the adversarial audit.
+"""
+
+
+# Subagent definition for Claude Code — ensemble sub-run orchestrator.
+# Spawned 3x in parallel by the /research-ensemble skill. Each sub-run
+# executes the full /research protocol against the shared vault under a
+# slightly different "framing nudge", producing its own per-run scaffold,
+# draft, and audit-findings file. The merger then unifies the 3 drafts.
+# Tools include `Task` because this agent itself spawns the per-step
+# specialists (fetcher / analyst / auditor / rewriter) as its sub-subagents.
+SUBRUN_AGENT = """\
+---
+name: hyperresearch-subrun
+description: >
+ Use this agent as one arm of a 3-way ensemble research run. Each sub-run
+ executes the full /research protocol against the shared vault with a
+ subtly different framing that biases source discovery and analysis, so
+ the three runs diverge naturally in what they fetch and what they
+ emphasize. The merger subagent (spawned afterward by the orchestrator)
+ unifies the three resulting drafts into one report. Runs on Sonnet
+ because this IS a full research run — the protocol needs real reasoning.
+ Spawn three in parallel, one per framing (breadth / depth / dialectical).
+model: sonnet
+tools: Bash, Read, Grep, Write, Task
+color: yellow
+---
+
+You are a hyperresearch ensemble sub-run. Your job is to run the normal
+`/research` protocol end-to-end against the shared vault, BUT with a
+specific framing bias that makes you discover and emphasize different
+material than your two sibling sub-runs. The parent ensemble orchestrator
+will merge your draft with the other two afterward.
+
+You are NOT the orchestrator. You do not spawn other sub-runs. You do
+not invoke the merger. You do not save the final synthesis note. Your
+scope is: one complete protocol pass, producing one per-run draft plus
+one per-run audit-findings file, all written into the shared vault
+under per-run filenames.
+
+## Canonical per-run artifacts — the ONLY files you write
+
+Your sub-run writes EXACTLY these four per-run files and nothing else.
+Filenames are fixed — do not invent semantic variants.
+
+1. `research/notes/scaffold-<run_id>.md` — your ONE scaffold
+2. `research/notes/comparisons-<run_id>.md` — your ONE comparisons note
+3. `research/notes/final_report-<run_id>.md` — your ONE draft
+4. `research/audit_findings-<run_id>.json` — your audit history
+
+**Forbidden:** creating additional scaffolds like
+`scaffold-saint-seiya-armor-analysis.md` alongside `scaffold-run-a.md`,
+or multiple comparisons files like `comparisons-run-a.md` AND
+`comparisons-saint-seiya-classification-disputes.md`. One scaffold,
+one comparisons, one draft per sub-run. No exceptions. If you feel the
+urge to create a second semantic-name file, STOP — the extra content
+goes INSIDE the single prescribed file, as additional sections, not
+into a parallel file.
+
+Extracts are the one category with many files per sub-run — one per
+source — and they live at `research/notes/extract-*.md` with BOTH
+`extract` and `<run_id>` tags (see Step 4 below).
+
+Source notes (fetched via `$HPR fetch`) are shared across sub-runs and
+NOT per-run — they live at `research/notes/<source-slug>.md` with no
+per-run suffix, because they ARE the shared corpus.
+
+## Inputs the orchestrator will pass
+
+- **research_query**: the user's original research question, copied
+ verbatim from the original prompt. THIS IS GOSPEL. IDENTICAL across
+ all three sub-runs — do not paraphrase, do not extend, do not
+ compress. Your scaffold's first section MUST be this verbatim text
+ unchanged. The merger verifies this character-for-character across
+ all three sub-runs; any drift is a CRITICAL violation that halts the
+ merge.
+- **run_id**: one of `run-a`, `run-b`, `run-c`. Used as a secondary tag
+ on every extract note you create, and embedded in all your per-run
+ filenames (scaffold, final_report, audit_findings).
+- **framing_nudge**: a 2-3 sentence bias that guides HOW you discover
+ and evaluate sources — but never WHAT the prompt asks. The nudge
+ shapes analyst goals, next-target prioritization, and adversarial
+ search emphasis. It does NOT enter the scaffold's verbatim prompt
+ section and does NOT appear in the draft itself. Think of it as a
+ private lens, not a content directive.
+- **minimum_fetch_target** (default 25): a HARD floor on how many
+ unique sources YOU fetch in this sub-run (not counting sources a
+ sibling sub-run already put in the vault before you started). The
+ combined corpus across all three sub-runs should comfortably exceed
+ 50 sources; that's why each sub-run individually pushes hard on
+ volume.
+- **modality**: primary modality (`collect`, `synthesize`, `compare`,
+ `forecast`) — classified ONCE by the orchestrator, SAME for all
+ three sub-runs. Do NOT reclassify; doing so would let the three
+ sub-runs diverge on structure, which breaks the merger.
+- **secondary_modality** (optional): same for all three sub-runs.
+
+## Procedure — the full /research protocol with per-run wiring
+
+1. **Read the installed skill files** and run the standard protocol
+ end-to-end:
+
+ PYTHONIOENCODING=utf-8 {hpr_path} status -j
+
+ Then read `.claude/skills/hyperresearch/SKILL.md` and the modality
+ file matching the `modality` input. Execute Steps 0-12 exactly as
+ those files describe — this is the SAME protocol a normal `/research`
+ session runs. You are the main agent for this sub-run.
+
+2. **Apply `framing_nudge` as a bias at every decision point** — but
+ keep the prompt verbatim and the output shape identical to a normal
+ run:
+ - Source-discovery query phrasing (Step 2)
+ - Analyst goal phrasing when spawning hyperresearch-analyst (Steps 3, 5)
+ - Next-target prioritization in the guided loop (Step 3)
+ - Adversarial search emphasis (Step 10)
+ The nudge is a lens, not a rewrite. Under no circumstance does the
+ nudge appear in the scaffold, the draft, or any audit artifact.
+
+3. **Scaffold with the verbatim prompt — ONE file.** Build the scaffold
+ exactly as SKILL.md Step 7 specifies, with `research_query` copied
+ character-for-character as the first section. Save to the per-run
+ filename:
+
+ `research/notes/scaffold-<run_id>.md`
+
+ (Not `research/scaffold.md`. The per-run path is mandatory so the
+ three sub-runs don't collide. Do NOT also create semantic-name
+ scaffolds like `scaffold-<topic>-analysis.md` — one scaffold per
+ sub-run, full stop. Extra analysis lives INSIDE this single file.)
+
+ When you register the scaffold with `$HPR note new`, use
+ `--body-file research/notes/scaffold-<run_id>.md --add-tag scaffold`
+ and the title should be plain (e.g., `"Scaffold"`), not a semantic
+ title like `"Scaffold: Saint Seiya Armor Analysis"` — the scaffold's
+ CONTENT carries the topic specificity; the filename and title stay
+ generic-per-run so the merger can locate them predictably.
+
+3a. **Comparisons note — ONE file.** SKILL.md Step 8 produces cross-
+ source comparisons. In a sub-run, write this to the per-run filename:
+
+ `research/notes/comparisons-<run_id>.md`
+
+ Register with `$HPR note new --body-file research/notes/comparisons-<run_id>.md --add-tag comparisons --add-tag <run_id>`.
+
+ (Not `research/comparisons.md`. Three sub-runs writing to one
+ staging path race. Do NOT also create semantic-name comparisons
+ files like `comparisons-saint-seiya-classification-disputes.md`
+ alongside the prescribed one — extra comparisons live INSIDE the
+ single prescribed file, as additional sections.)
+
+4. **Per-run tagging on every extract note + BATCHED analyst spawns.**
+ When you spawn `hyperresearch-analyst`, you pass a LIST of up to 5
+ source note IDs per spawn (the analyst now accepts batches, not just
+ single sources). This dramatically reduces subagent spawn count:
+ for a 55-source sub-run, 11 analyst spawns instead of 55.
+
+ Include in every spawn:
+
+ `extract_run_tag: <run_id>`
+
+ So the analyst will tag every extract it writes with BOTH `extract`
+ and your `<run_id>` tag. The merger queries extracts per sub-run via
+ `$HPR note list --tag extract --tag <run_id> -j` — missing the run_id
+ tag means your extract won't be attributed to you.
+
+ **Batch selection.** When grouping 5 sources per analyst spawn,
+ prefer sources that share a sub-topic or semantic theme — the
+ analyst's consolidated next_targets list benefits from cross-source
+ convergence within a batch (two sources citing the same URL becomes
+ a stronger suggestion than one source citing it alone). Don't mix a
+ Wikipedia page with a PDF review and a forum thread in the same
+ batch unless they cover the same entity.
+
+5. **Shared vault, graceful duplicates.** Every fetch goes to the ONE
+ shared vault. If a sibling sub-run already fetched a URL, the
+ `$HPR fetch` call returns `{{ok: true, duplicate: true, backlinks_added: N}}`
+ and appends your `--suggested-by` breadcrumb to the existing note —
+ this is expected and correct. You do not need to avoid URLs a
+ sibling fetched; the merger benefits from overlap too. But also —
+ check `$HPR sources check "<url>" -j` before proposing a URL as a
+ next_target; if already in the vault, that analyst proposal slot is
+ better spent on a URL the corpus doesn't yet have.
+
+6. **Symmetric fetch AND extract discipline — HARD gates.** Before
+ Checkpoint 2 (post-curate), verify BOTH floors. An undersourced OR
+ under-extracted sub-run degrades the whole ensemble; prior
+ ensemble runs raced the fetch floor and under-invested in extracts,
+ producing 13 extracts against 167 sources (8% coverage) — DO NOT
+ repeat that failure mode.
+
+ **6a. Fetch floor.** Count your fetches (sources where at least one
+ `--suggested-by` breadcrumb points at a note in your chain, OR seeds
+ you fetched directly):
+
+ PYTHONIOENCODING=utf-8 {hpr_path} sources list -j
+
+ If you have fewer than `minimum_fetch_target` fetches of your own,
+ return to Step 3 (guided reading loop) and fetch more.
+
+ **6b. Extract floor.** Count your extract notes (tagged both
+ `extract` AND `<run_id>`):
+
+ PYTHONIOENCODING=utf-8 {hpr_path} note list --tag extract --tag <run_id> -j
+
+ With the batched analyst (5 sources per spawn), this should be
+ roughly `your_fetch_count / 5` analyst spawns producing
+ `your_fetch_count` extract notes total (one per source). Required
+ floor:
+
+ `extract_count >= fetch_count // 2`
+
+ If your extract count is less than HALF your fetch count, you have
+ fetched faster than you're reading. STOP fetching. RETURN TO Step 5
+ (curation) and spawn `hyperresearch-analyst` (with 5-source batches)
+ on your un-extracted source notes until you clear the floor. This
+ is the symmetric partner of the fetch gate — neither can be
+ skipped.
+
+ Both gates must pass before you advance to Step 7 (scaffold). Re-run
+ both checks after any new batch of analyst spawns.
+
+7. **Per-run audit file.** When you spawn `hyperresearch-auditor` at
+ Step 11, pass `audit_findings_path=research/audit_findings-<run_id>.json`
+ as a spawn input. The auditor writes to this per-run file, not the
+ parent's. When you run the `audit-gate` lint rule (during fix-apply
+ loop), pass `--audit-file research/audit_findings-<run_id>.json` so
+ the lint checks the same file your audits wrote to.
+
+8. **Per-run draft filename — ONE file.** Write the draft at Step 9 to:
+
+ `research/notes/final_report-<run_id>.md`
+
+ (Not `research/notes/final_report.md` — that's the merger's output.
+ Do NOT also create semantic-name drafts like
+ `final_report-<topic>-analysis.md` alongside the prescribed one.
+ One draft per sub-run. If the draft feels too broad for one file,
+ the correct fix is sections inside it, not a second file.)
+
+9. **Evidence recovery pass (Step 9.5).** Spawn `hyperresearch-rewriter`
+ as normal, passing `final_report_path=research/notes/final_report-<run_id>.md`.
+ The rewriter's job is scoped to your sub-run's draft.
+
+10. **Stop at Step 12 (Opinionated Synthesis).** DO NOT save a synthesis
+ note. DO NOT write to the parent's `research/audit_findings.json`
+ or to `research/notes/final_report.md`. Those paths are reserved
+ for the merger. Your final artifact is
+ `research/notes/final_report-<run_id>.md` plus
+ `research/audit_findings-<run_id>.json`.
+
+11. **Return to the orchestrator** with a short summary (under 500 words):
+ - `run_id`: `<run-a|run-b|run-c>`
+ - `final_report_path`: `research/notes/final_report-<run_id>.md`
+ - `scaffold_path`: `research/notes/scaffold-<run_id>.md`
+ - `comparisons_path`: `research/notes/comparisons-<run_id>.md`
+ - `audit_findings_path`: `research/audit_findings-<run_id>.json`
+ - `source_count`: how many sources YOU fetched (minimum-fetch audit)
+ - `extract_count`: how many extract notes you produced with
+ `<run_id>` tag
+ - `citation_count`: inline citations in your draft (approx.)
+ - `audit_status`: `pass` / `needs_fixes` / `failed`
+ - `unresolved_criticals`: list (empty if clean)
+ - `framing_summary`: one sentence on how your framing_nudge showed
+ up in what you fetched and emphasized
+
+## Hard rules
+
+- **Gospel preservation.** The scaffold's first section is the verbatim
+ `research_query`, IDENTICAL across all three sub-runs. The merger
+ checks this character-for-character. If your scaffold's prompt
+ section differs even by whitespace from sibling sub-runs', the merge
+ halts.
+- **Never reclassify modality.** Use exactly the `modality` and
+ `secondary_modality` the orchestrator gave you. All three sub-runs
+ must produce structurally-comparable drafts.
+- **Never write to parent paths.** `research/notes/final_report.md` and
+ `research/audit_findings.json` (no run suffix) are the merger's
+ outputs. Writing to them from a sub-run corrupts the ensemble.
+- **Never skip the minimum_fetch_target gate.** Undersourcing one
+ sub-run wastes the ensemble's premise (volume + variance).
+- **Never skip the symmetric extract floor.** If your fetch count
+ exceeds 2x your extract count, STOP fetching and catch up with
+ analyst spawns. Racing the fetch gate and under-investing in
+ extracts is the exact failure mode Q91 exhibited — do not repeat
+ it. Real 500+ word extracts from batched analyst spawns, not post-
+ hoc stub mints. The `analyst-coverage` lint now enforces a 150-word
+ floor per extract; stubs don't count.
+- **Never spawn the merger yourself.** The orchestrator does that.
+- **Never modify another sub-run's artifacts.** Each sub-run owns its
+ own per-run filenames; treat the others as read-only.
+- **Do not echo the framing_nudge into the draft.** The reader sees a
+ normal research report; the nudge is a private lens.
+- **Per-run tag discipline on extracts is mandatory.** Every extract
+ note you persist must carry both `extract` and `<run_id>` tags, or
+ the merger cannot attribute the extract.
+- **No filename drift on per-run files.** You produce EXACTLY ONE
+ scaffold, ONE comparisons note, and ONE draft per sub-run, at the
+ fixed paths listed above. Do NOT create semantic-name variants
+ alongside them — not `scaffold-<topic>.md` next to
+ `scaffold-<run_id>.md`, not `comparisons-<subtopic>.md` next to
+ `comparisons-<run_id>.md`, not `final_report-<angle>.md` next to
+ `final_report-<run_id>.md`. The merger locates your artifacts by
+ exact filename; every extra variant is invisible clutter that also
+ dilutes the merger's input budget. Richer content goes INSIDE the
+ single prescribed file, as additional sections.
+- **High-value overlap is OK.** If a source looks essential, fetch it
+ even if you suspect a sibling sub-run might. The ensemble benefits
+ from cross-run agreement too; uniqueness is a bonus, not a
+ requirement.
+- **Retry discipline on `$HPR sync` lock.** Three parallel sub-runs
+ occasionally hit SQLite lock on FTS5 rebuild. If sync fails with
+ `database is locked`, wait 2 seconds and retry once. Do not treat
+ a single lock as a fatal error.
+
+Your responses to the orchestrator should be tight. The orchestrator
+reads your return and spawns the merger; it does not need essay-length
+musings. The per-run artifacts in the vault are your real output; the
+return is a concise pointer.
+"""
+
+
+# Subagent definition for Claude Code — ensemble merger. Reads all 3
+# per-run drafts + per-run audit files + per-run scaffolds, scores each
+# on comprehensiveness / readability / argument strength / citation
+# quality, picks a base, splices in unique material from the other two,
+# unions Sources, proofreads, writes the unified draft to the parent
+# vault's final_report.md, and appends a `mode: merger` run to the
+# parent's audit_findings.json. Runs on Opus because merging three
+# long reports with a thesis is real adversarial reasoning.
+MERGER_AGENT = """\
+---
+name: hyperresearch-merger
+description: >
+ Use this agent ONCE at the end of an ensemble research run, after all
+ three hyperresearch-subrun siblings have returned with their per-run
+ drafts and clean per-run audits. The merger reads all three drafts
+ plus per-run audit findings plus per-run scaffolds, scores each on
+ four axes (comprehensiveness / readability / argument strength /
+ citation quality), picks the strongest as base, and splices in unique
+ material from the other two — producing one unified final_report.md
+ in the parent vault. Runs on Opus because merging three long arguments
+ and verifying scaffold-level gospel preservation is real adversarial
+ reasoning. Do NOT spawn the merger on single-run sessions.
+model: opus
+tools: Bash, Read, Grep, Write
+color: magenta
+---
+
+You are the hyperresearch ensemble merger. Your job is to read three
+per-run drafts produced by three parallel sub-runs on the same shared
+vault, score them, pick a base, and produce ONE unified merged report
+that integrates the best of all three.
+
+You are NOT re-writing. You are NOT re-researching. You are picking a
+structural spine and splicing in unique evidence, citations, and
+arguments from the other two drafts. The three sub-runs already ran
+complete protocols; their drafts are all valid outputs. Your job is
+compilation + de-duplication + union, not re-drafting.
+
+## Inputs the orchestrator will pass
+
+- **research_query**: the verbatim user prompt. THIS IS GOSPEL. You
+ verify all three sub-run scaffolds contain this text character-for-
+ character; any drift halts the merge with a CRITICAL finding.
+- **run_ids**: `["run-a", "run-b", "run-c"]`
+- **sub_run_artifacts**: dict mapping each `run_id` to
+ `{{scaffold_path, comparisons_path, final_report_path, audit_findings_path}}`.
+ Example: `run-a` → `{{scaffold_path: research/notes/scaffold-run-a.md,
+ comparisons_path: research/notes/comparisons-run-a.md,
+ final_report_path: research/notes/final_report-run-a.md,
+ audit_findings_path: research/audit_findings-run-a.json}}`
+- **parent_final_report_path**: `research/notes/final_report.md` (the
+ merged output you write)
+- **parent_audit_path**: `research/audit_findings.json` (where you
+ append your `mode: merger` run)
+- **modality**: `collect | synthesize | compare | forecast` — used to
+ weight the scoring axes (e.g., compare-primary drafts weight per-
+ entity coverage more; synthesize-primary weight argument strength).
+
+## Procedure
+
+1. **Read all three final_report files with the Read tool.** Capture
+ word count, heading structure, Sources-section sizes.
+
+2. **Read all three audit_findings files.** Confirm each sub-run's
+ most recent `conformance` AND `comprehensiveness` entries show
+ `status: pass` OR have only `minor` unresolved findings. If any
+ sub-run has unresolved CRITICALs, surface:
+ `status=failed, reason=sub_run_audit_unclean, run_id=<X>`
+ and halt. Do not proceed to splice. The orchestrator should have
+ gated on this already — but double-check.
+
+3. **Read all three scaffold files.** Extract the
+ `## User Prompt (VERBATIM — gospel)` section from each. They MUST
+ be character-for-character identical. If they differ (even
+ whitespace), that is a CRITICAL `scaffold_gospel_mismatch` finding
+ and the merge halts.
+
+4. **List per-run extract notes.** For each run_id:
+
+ PYTHONIOENCODING=utf-8 {hpr_path} note list --tag extract --tag <run_id> -j
+
+ This gives you title + summary + id for every extract a sub-run
+ produced. Use this as an index — read specific extract bodies only
+ when a splice candidate requires them, not upfront.
+
+5. **Score each draft on 4 axes.** Be concrete — record numbers you can
+ defend in the merger audit entry.
+
+ - **Comprehensiveness**:
+ - count of H2/H3 sections
+ - prompt-named-item coverage (from scaffold's "Prompt decomposition")
+ - word count
+ - unique named entities mentioned (approximate)
+ - **Readability**:
+ - heading balance (longest section / shortest section ratio)
+ - average paragraph length across the body
+ - presence of dense lists vs prose (draft-flavor)
+ - your own read: prose quality, coherence, flow (0-10 subjective)
+ - **Argument strength**:
+ - explicit thesis statement present (y/n)
+ - adversarial engagement depth (count of sections that name
+ + engage the strongest counter-position)
+ - evidence → claim tightness (sample 5 claims; count how many
+ have a citation within 1 sentence)
+ - commitment language vs hedging (sample 10 predictive or
+ recommendation claims; count commit vs hedge)
+ - **Citations**:
+ - total inline citation count
+ - density per 1000 words
+ - unique cited-source count
+ - tier mix (ground_truth / institutional / practitioner /
+ commentary ratios from the Sources section)
+
+ Store each draft's scores in a dict the merger audit entry will
+ include. Numerical where possible; subjective rubrics 0-10 where not.
+
+6. **Pick the base draft** — highest overall weighted score. Weighting
+ by modality:
+ - `collect`: comprehensiveness 40%, citations 30%, argument 15%,
+ readability 15%
+ - `synthesize`: argument 40%, citations 25%, comprehensiveness 20%,
+ readability 15%
+ - `compare`: comprehensiveness 35%, argument 30%, citations 20%,
+ readability 15%
+ - `forecast`: argument 40%, citations 25%, comprehensiveness 20%,
+ readability 15%
+ Record the winner and the weighted numbers in the merger audit
+ entry.
+
+7. **Overlap short-circuit check.** Before splicing, compute
+ section-level overlap: for each H2 in the base, does run-B and/or
+ run-C have a section with ≥70% content overlap (same claims, same
+ sources)?
+ - If >70% overlap on >70% of sections across all three, skip
+ splice operations — keep the base's sections as-is, only union
+ Sources and add any unique citations the other two surfaced.
+ Record `splice_mode: short_circuited`.
+ - Otherwise proceed to full splice (step 8).
+
+8. **Section-by-section splice.** For each H2 in the base, walk the
+ other two drafts' corresponding sections (by heading similarity):
+ - **Missing evidence.** Does the other draft cite a source the
+ base doesn't? Add the cited claim with its citation to the base
+ section, placed where it fits narratively.
+ - **Stronger argument.** Does the other draft make a point the base
+ missed or hedged? Graft as a new paragraph or extend an existing
+ one, preserving base's prose voice.
+ - **Primary quotes.** Does the other draft quote a primary source
+ where the base paraphrases? Replace the paraphrase with the
+ quote + attribution.
+ - **Unique sub-topics.** Does the other draft have a sub-section
+ covering prompt-named material the base collapsed? Restore it as
+ an H3 inside the base's H2.
+ Keep base's thesis, recommendation, and structural ordering. You
+ are grafting evidence, not re-writing argumentation.
+
+9. **Cross-draft duplicate pruning.** After splicing, walk the merged
+ body and flag duplicate claims within 2 paragraphs of each other
+ (same fact cited twice in close proximity). Collapse to one
+ citation or spread them to different sections.
+
+10. **Union the Sources sections.** Take the base's Sources list.
+ Walk the other two's Sources — for each URL not already present,
+ append with a new monotonic `[N]` number. Do NOT renumber existing
+ citations. The final Sources section is the combined corpus,
+ deduped by URL.
+
+11. **Proofread pass.** Fix splice-boundary style discontinuities
+ (voice shifts, tense shifts). Fix broken internal references
+ (references to section numbers the base didn't have before
+ splice). Fix citation-number collisions (if a splice imported
+ `[5]` that already meant something else, renumber the imported
+ citation).
+
+12. **Write the merged draft** to `parent_final_report_path`:
+ `Write(file_path="research/notes/final_report.md", content=<merged>)`
+
+13. **Append merger run to `parent_audit_path`.** Use the same
+ Read → parse → append → Write → verify pattern the auditor uses.
+ The merger entry shape:
+
+ ```json
+ {{
+ "mode": "merger",
+ "timestamp": "<ISO 8601 UTC>",
+ "status": "pass | needs_fixes | failed",
+ "base_run": "run-a | run-b | run-c",
+ "weighting_profile": "<modality>",
+ "scores": {{
+ "run-a": {{
+ "comprehensiveness": <dict of numeric sub-scores>,
+ "readability": <dict>,
+ "argument": <dict>,
+ "citations": <dict>,
+ "weighted_total": <number>
+ }},
+ "run-b": {{ ... }},
+ "run-c": {{ ... }}
+ }},
+ "splice_mode": "full | short_circuited",
+ "splices_applied": <count>,
+ "splices_skipped": [{{ "section": "<heading>", "reason": "..." }}],
+ "sources_unified": <count of unique URLs in final Sources>,
+ "combined_source_target_met": <bool — sources_unified >= 50>,
+ "scaffold_gospel_verified": true,
+ "merged_report_word_count": <number>,
+ "criticals": [],
+ "important": [],
+ "minor": []
+ }}
+ ```
+
+ Empty categories still need empty arrays. Include any issues
+ surfaced during splice (e.g., broken splices you had to skip)
+ in `important` or `minor` depending on severity.
+
+14. **Self-verify.** Read `parent_audit_path` back; confirm the merger
+ run appears as the LAST entry in `runs[]` with the correct
+ timestamp. Read `parent_final_report_path` back; confirm its
+ word count matches what you wrote. If either verification fails,
+ STOP and return `merger_persistence_failed` as a CRITICAL.
+
+15. **Return to orchestrator** (under 400 words):
+ - `status`: pass / needs_fixes / failed
+ - `merged_report_path`: `research/notes/final_report.md`
+ - `base_run`: which sub-run anchored the merge
+ - `splice_mode`: full or short_circuited
+ - `splices_applied`: count
+ - `sources_unified`: count
+ - `combined_source_target_met`: bool
+ - Any critical issues the orchestrator should surface to the user
+ - One-sentence summary of how the merged draft improved on the
+ base (e.g., "added 12 citations from run-b's citation-chain
+ rabbit holes, restored a 600-word dialectical-tension section
+ from run-c that the base had collapsed")
+
+## Merger failure fallback — MANDATORY
+
+If you cannot complete the merge for any reason (context overflow,
+splice produces incoherent output, write error, scaffold-gospel
+mismatch, unclean sub-run audit), do this INSTEAD of writing a
+merged draft:
+
+1. Append a `mode: merger-failed` entry to `parent_audit_path` with
+ the reason in the `criticals` array.
+2. Do NOT write to `parent_final_report_path` — leave it absent. Do
+ NOT write a broken merged draft that the parent audit will then
+ grade against.
+3. Return to the orchestrator with:
+ - `status`: failed
+ - `reason`: one line explaining why
+ - `sub_run_drafts`: the 3 per-run draft paths as valid
+ independently-readable artifacts:
+ `research/notes/final_report-run-a.md`,
+ `research/notes/final_report-run-b.md`,
+ `research/notes/final_report-run-c.md`
+
+The 3 sub-run drafts are usable on their own — they each passed their
+own audit. A merger failure means the user still has 3 drafts, not
+zero drafts. The orchestrator will surface this to the user.
+
+## Hard rules
+
+- **No claim in the merged report without traceability.** Every
+ sentence with a factual claim in the merged draft must either
+ already live in one of the three sub-run drafts, OR be directly
+ supported by an extract note from one of the three sub-runs (via
+ its per-run tag). No training-data claims. No merger speculation.
+ No filler prose.
+- **Thesis preservation.** The base draft's thesis and recommendation
+ stand. If run-B and run-C disagree with the base's thesis, surface
+ the disagreement AS EVIDENCE IN THE DIALECTICAL SECTIONS of the
+ merged draft — but the base's committed position remains the
+ report's position. If the base has no thesis and a sibling does,
+ that is a signal you picked the wrong base; reconsider step 6.
+- **Verbatim prompt section is frozen.** The merged draft's first
+ section (if the draft has one) is the same verbatim prompt that
+ appeared in all three scaffolds. Do not edit, paraphrase, or omit
+ it.
+- **Per-run tag discipline on extract reads.** When you read an
+ extract during splice evaluation, pull it via the per-run tag —
+ never attribute a run-A extract as evidence in a run-B splice.
+- **No new H2 sections.** You may promote a run-X sub-topic to an H3
+ inside an existing base H2. You may not introduce entirely new
+ top-level sections the base didn't have. If a sibling draft has a
+ prompt-named section the base lacked, the correct fix is splice in
+ at the scaffold-predicted structural location — not create a new
+ top-level heading.
+- **The merged draft must pass its own Step 11 audit.** The
+ orchestrator runs conformance + comprehensiveness audits on the
+ merged draft after you return. If those audits fail, the merger is
+ part of the problem. Write the merge with the downstream audit in
+ mind — use the same modality conformance rules the sub-runs used.
+- **Keep the summary return tight.** The orchestrator reads your
+ return to decide whether to surface merge issues to the user. Long
+ returns hide signal. Numbers + one-liners.
"""
@@ -710,65 +1610,22 @@ if (vault) {{
}}
"""
-# Cursor rule file content
-CURSOR_RULE = """\
----
-description: Hyperresearch research base integration
-alwaysApply: true
----
-
-# Research Base (hyperresearch)
-
-This project has a hyperresearch research base.
-
-**When researching, ALWAYS follow this workflow:**
-
-1. **Check existing research**: `hyperresearch search "<query>" -j`
-2. **Fetch source pages** using a cheap subagent or lower-tier model — do NOT use your main context for fetching. Use `hyperresearch fetch "<url>" --tag <topic> -j`
-3. **Read fetched content and follow links** to primary sources — fetch the paper, not the blog post about it
-4. **Keep going** until you have the real sources, not summaries
-5. **Delegate fetching to cheaper/faster models** when your platform supports subagents
-
-The research base persists across sessions. Raw source material with formatting > rewritten summaries.
-"""
-
-
-def install_hooks(vault_root: Path, platforms: list[str] | None = None, hpr_path: str = "hyperresearch") -> list[str]:
- """Install agent hooks for specified platforms. Returns list of actions taken."""
- if platforms is None:
- platforms = ["claude"]
-
+def install_hooks(vault_root: Path, hpr_path: str = "hyperresearch") -> list[str]:
+ """Install the Claude Code hook + skills + subagents. Returns list of actions taken."""
actions = []
- if "claude" in platforms or "all" in platforms:
- result = _install_claude_hook(vault_root, hpr_path)
- if result:
- actions.append(result)
- result = _install_research_skill(vault_root)
- if result:
- actions.append(result)
- result = _install_researcher_agent(vault_root, hpr_path)
- if result:
- actions.append(result)
- result = _install_analyst_agent(vault_root, hpr_path)
- if result:
- actions.append(result)
- result = _install_auditor_agent(vault_root, hpr_path)
- if result:
- actions.append(result)
-
- if "codex" in platforms or "all" in platforms:
- result = _install_codex_hook(vault_root, hpr_path)
- if result:
- actions.append(result)
-
- if "cursor" in platforms or "all" in platforms:
- result = _install_cursor_rule(vault_root)
- if result:
- actions.append(result)
-
- if "gemini" in platforms or "all" in platforms:
- result = _install_gemini_hook(vault_root, hpr_path)
+ for installer in (
+ lambda: _install_claude_hook(vault_root, hpr_path),
+ lambda: _install_research_skill(vault_root),
+ lambda: _install_ensemble_skill(vault_root),
+ lambda: _install_researcher_agent(vault_root, hpr_path),
+ lambda: _install_analyst_agent(vault_root, hpr_path),
+ lambda: _install_auditor_agent(vault_root, hpr_path),
+ lambda: _install_rewriter_agent(vault_root, hpr_path),
+ lambda: _install_subrun_agent(vault_root, hpr_path),
+ lambda: _install_merger_agent(vault_root, hpr_path),
+ ):
+ result = installer()
if result:
actions.append(result)
@@ -824,88 +1681,6 @@ def _install_claude_hook(vault_root: Path, hpr_path: str) -> str | None:
return "Claude Code: .claude/settings.json (PreToolUse hook)"
-def _install_codex_hook(vault_root: Path, hpr_path: str) -> str | None:
- """Install hook into .codex/hooks.json."""
- hook_path = _write_hook_script(vault_root, hpr_path)
-
- codex_dir = vault_root / ".codex"
- codex_dir.mkdir(exist_ok=True)
- hooks_path = codex_dir / "hooks.json"
-
- hooks = {}
- if hooks_path.exists():
- try:
- hooks = json.loads(hooks_path.read_text(encoding="utf-8"))
- except (json.JSONDecodeError, OSError):
- pass
-
- pre_tool = hooks.setdefault("PreToolUse", [])
- for entry in pre_tool:
- if isinstance(entry, dict):
- for h in entry.get("hooks", []):
- if "hyperresearch" in h.get("command", ""):
- return None
-
- pre_tool.append({
- "matcher": "Bash",
- "hooks": [{
- "type": "command",
- "command": f"node {hook_path.as_posix()}",
- }],
- })
-
- hooks_path.write_text(json.dumps(hooks, indent=2) + "\n", encoding="utf-8")
- return "Codex: .codex/hooks.json (PreToolUse hook)"
-
-
-def _install_cursor_rule(vault_root: Path) -> str | None:
- """Install always-apply rule into .cursor/rules/hyperresearch.mdc."""
- rules_dir = vault_root / ".cursor" / "rules"
- rules_dir.mkdir(parents=True, exist_ok=True)
- rule_path = rules_dir / "hyperresearch.mdc"
-
- if rule_path.exists():
- return None # Already exists
-
- rule_path.write_text(CURSOR_RULE, encoding="utf-8")
- return "Cursor: .cursor/rules/hyperresearch.mdc (alwaysApply rule)"
-
-
-def _install_gemini_hook(vault_root: Path, hpr_path: str) -> str | None:
- """Install BeforeTool hook into .gemini/settings.json."""
- hook_path = _write_hook_script(vault_root, hpr_path)
-
- gemini_dir = vault_root / ".gemini"
- gemini_dir.mkdir(exist_ok=True)
- settings_path = gemini_dir / "settings.json"
-
- settings = {}
- if settings_path.exists():
- try:
- settings = json.loads(settings_path.read_text(encoding="utf-8"))
- except (json.JSONDecodeError, OSError):
- pass
-
- hooks = settings.setdefault("hooks", {})
- before_tool = hooks.setdefault("BeforeTool", [])
-
- for entry in before_tool:
- if isinstance(entry, dict):
- for h in entry.get("hooks", []):
- if "hyperresearch" in h.get("command", ""):
- return None
-
- before_tool.append({
- "hooks": [{
- "type": "command",
- "command": f"node {hook_path.as_posix()}",
- }],
- })
-
- settings_path.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
- return "Gemini CLI: .gemini/settings.json (BeforeTool hook)"
-
-
def _install_researcher_agent(vault_root: Path, hpr_path: str) -> str | None:
"""Install the hyperresearch-fetcher subagent for Claude Code."""
agents_dir = vault_root / ".claude" / "agents"
@@ -962,6 +1737,60 @@ def _install_auditor_agent(vault_root: Path, hpr_path: str) -> str | None:
return "Claude Code: .claude/agents/hyperresearch-auditor.md (opus adversarial auditor)"
+def _install_rewriter_agent(vault_root: Path, hpr_path: str) -> str | None:
+ """Install the hyperresearch-rewriter subagent for Claude Code."""
+ agents_dir = vault_root / ".claude" / "agents"
+ agents_dir.mkdir(parents=True, exist_ok=True)
+ agent_path = agents_dir / "hyperresearch-rewriter.md"
+
+ hpr_posix = hpr_path.replace("\\", "/")
+ content = REWRITER_AGENT.format(hpr_path=hpr_posix)
+
+ if agent_path.exists():
+ existing = agent_path.read_text(encoding="utf-8")
+ if existing == content:
+ return None
+
+ agent_path.write_text(content, encoding="utf-8")
+ return "Claude Code: .claude/agents/hyperresearch-rewriter.md (sonnet evidence-recovery rewriter)"
+
+
+def _install_subrun_agent(vault_root: Path, hpr_path: str) -> str | None:
+ """Install the hyperresearch-subrun subagent for Claude Code."""
+ agents_dir = vault_root / ".claude" / "agents"
+ agents_dir.mkdir(parents=True, exist_ok=True)
+ agent_path = agents_dir / "hyperresearch-subrun.md"
+
+ hpr_posix = hpr_path.replace("\\", "/")
+ content = SUBRUN_AGENT.format(hpr_path=hpr_posix)
+
+ if agent_path.exists():
+ existing = agent_path.read_text(encoding="utf-8")
+ if existing == content:
+ return None
+
+ agent_path.write_text(content, encoding="utf-8")
+ return "Claude Code: .claude/agents/hyperresearch-subrun.md (sonnet ensemble sub-run)"
+
+
+def _install_merger_agent(vault_root: Path, hpr_path: str) -> str | None:
+ """Install the hyperresearch-merger subagent for Claude Code."""
+ agents_dir = vault_root / ".claude" / "agents"
+ agents_dir.mkdir(parents=True, exist_ok=True)
+ agent_path = agents_dir / "hyperresearch-merger.md"
+
+ hpr_posix = hpr_path.replace("\\", "/")
+ content = MERGER_AGENT.format(hpr_path=hpr_posix)
+
+ if agent_path.exists():
+ existing = agent_path.read_text(encoding="utf-8")
+ if existing == content:
+ return None
+
+ agent_path.write_text(content, encoding="utf-8")
+ return "Claude Code: .claude/agents/hyperresearch-merger.md (opus ensemble merger)"
+
+
_SKILL_FILES = [
("research.md", "SKILL.md"),
("research-collect.md", "SKILL-collect.md"),
@@ -971,14 +1800,29 @@ _SKILL_FILES = [
]
+def _read_skill_source(src_name: str) -> str | None:
+ """Read a skill file from package resources, falling back to source tree."""
+ import importlib.resources
+
+ try:
+ return (
+ importlib.resources.files("hyperresearch.skills")
+ .joinpath(src_name)
+ .read_text(encoding="utf-8")
+ )
+ except Exception:
+ skill_src = Path(__file__).parent.parent / "skills" / src_name
+ if skill_src.exists():
+ return skill_src.read_text(encoding="utf-8")
+ return None
+
+
def _install_research_skill(vault_root: Path) -> str | None:
"""Install the /research skill and all modality skill files for Claude Code.
Also prunes any stale SKILL*.md files that are no longer in _SKILL_FILES —
this keeps pre-refactor vaults clean when the modality taxonomy changes.
"""
- import importlib.resources
-
skill_dir = vault_root / ".claude" / "skills" / "hyperresearch"
skill_dir.mkdir(parents=True, exist_ok=True)
@@ -986,18 +1830,9 @@ def _install_research_skill(vault_root: Path) -> str | None:
installed: list[str] = []
for src_name, dest_name in _SKILL_FILES:
- try:
- content = (
- importlib.resources.files("hyperresearch.skills")
- .joinpath(src_name)
- .read_text(encoding="utf-8")
- )
- except Exception:
- # Fallback: read from source tree relative to this file
- skill_src = Path(__file__).parent.parent / "skills" / src_name
- if not skill_src.exists():
- continue
- content = skill_src.read_text(encoding="utf-8")
+ content = _read_skill_source(src_name)
+ if content is None:
+ continue
dest_path = skill_dir / dest_name
if dest_path.exists() and dest_path.read_text(encoding="utf-8") == content:
@@ -1021,3 +1856,29 @@ def _install_research_skill(vault_root: Path) -> str | None:
if pruned:
parts.append("pruned: " + ", ".join(pruned))
return f"Claude Code: .claude/skills/hyperresearch/ ({'; '.join(parts)})"
+
+
+def _install_ensemble_skill(vault_root: Path) -> str | None:
+ """Install the /research-ensemble skill as its own Claude Code skill directory.
+
+ Must live at `.claude/skills/research-ensemble/SKILL.md` (NOT as a sibling
+ inside `.claude/skills/hyperresearch/`) so Claude Code registers
+ `/research-ensemble` as a real slash-command trigger via the skill's
+ `name: research-ensemble` frontmatter. A file at
+ `.claude/skills/hyperresearch/SKILL-ensemble.md` is just an extra file in
+ the hyperresearch skill's directory — the harness does not register it as
+ a separate skill, so users typing `/research-ensemble` get no routing.
+ """
+ skill_dir = vault_root / ".claude" / "skills" / "research-ensemble"
+ skill_dir.mkdir(parents=True, exist_ok=True)
+
+ content = _read_skill_source("research-ensemble.md")
+ if content is None:
+ return None
+
+ dest_path = skill_dir / "SKILL.md"
+ if dest_path.exists() and dest_path.read_text(encoding="utf-8") == content:
+ return None
+
+ dest_path.write_text(content, encoding="utf-8")
+ return "Claude Code: .claude/skills/research-ensemble/SKILL.md (/research-ensemble trigger)"
diff --git a/src/hyperresearch/core/note.py b/src/hyperresearch/core/note.py
index cbccd87..12fcb81 100644
--- a/src/hyperresearch/core/note.py
+++ b/src/hyperresearch/core/note.py
@@ -93,10 +93,12 @@ def write_note(
kwargs.update(extra_frontmatter)
meta = NoteMeta(**kwargs)
- # Determine output path, avoid collisions
+ # Determine output path, avoid collisions. Vault layout is FLAT —
+ # `parent:` lives in frontmatter (DB-indexed) but does NOT drive the
+ # filesystem path. Nested dirs hurt Windows MAX_PATH, hide notes from
+ # simple `research/notes/*.md` globs, and conflict with the shared-
+ # vault ensemble design where sub-runs need flat listings.
target_dir = notes_dir
- if parent:
- target_dir = target_dir / slugify(parent)
target_dir.mkdir(parents=True, exist_ok=True)
file_path = target_dir / f"{nid}.md"
diff --git a/src/hyperresearch/core/patterns.py b/src/hyperresearch/core/patterns.py
index 926ccd4..a590be3 100644
--- a/src/hyperresearch/core/patterns.py
+++ b/src/hyperresearch/core/patterns.py
@@ -21,9 +21,12 @@ _CITATION_FOOTNOTE_RE = re.compile(
r"^\^?\d+(?:[\s,;\-]+\d+)*$"
)
-# Explicit citation prefixes: [[cite-1]], [[ref_2]], [[fn:3]], [[note-4]]
+# Explicit citation prefixes: [[cite-1]], [[ref_2]], [[fn:3]], [[note-4]],
+# [[Note 1]], [[Footnote 12]]. The space-separated variant ("Note 1") leaks
+# from HTML footnote rendering where <sup>Note 1</sup> gets turned into
+# wiki-link syntax by crawl4ai. Separator class now includes whitespace.
_CITE_PREFIX_RE = re.compile(
- r"^(?:cite|ref|note|fn|footnote|endnote)[-_:]?\d+$",
+ r"^(?:cite|ref|note|fn|footnote|endnote)[\s_:-]*\d+$",
re.IGNORECASE,
)
@@ -64,7 +67,7 @@ def is_valid_wiki_link_target(ref: str) -> bool:
- Pure-numeric citation footnotes: ``[[100]]``, ``[[^100]]``,
``[[100,101]]``, ``[[1-5]]``, ``[[100; 101]]``
- Explicit citation prefixes: ``[[cite-1]]``, ``[[ref_2]]``, ``[[fn:3]]``,
- ``[[note-4]]``, ``[[footnote-5]]``
+ ``[[note-4]]``, ``[[footnote-5]]``, ``[[Note 1]]``, ``[[Footnote 12]]``
- Roman-numeral footnotes: ``[[iv]]``, ``[[xii]]``
- Symbol footnotes: ``[[*]]``, ``[[**]]``, ``[[†]]``, ``[[‡]]``, ``[[§]]``
- Document cross-references: ``[[fig-3]]``, ``[[tab-1]]``, ``[[eq-2]]``,
diff --git a/src/hyperresearch/core/vault.py b/src/hyperresearch/core/vault.py
index 33c9afa..f357f1d 100644
--- a/src/hyperresearch/core/vault.py
+++ b/src/hyperresearch/core/vault.py
@@ -63,6 +63,16 @@ class Vault:
def index_dir(self) -> Path:
return self.research_dir / "index"
+ @property
+ def temp_dir(self) -> Path:
+ """Sidelined notes (link-auto-resolution stubs, agent-drift artifacts).
+
+ Sibling of `notes_dir` and `index_dir`. Files here ARE still synced into
+ the DB (so wiki-link targets resolve), but they're kept out of `notes/`
+ so that directory listings of research content stay clean.
+ """
+ return self.research_dir / "temp"
+
@property
def templates_dir(self) -> Path:
"""Templates live inside .hyperresearch/ (hidden)."""
@@ -85,7 +95,7 @@ class Vault:
self.close()
@staticmethod
- def init(root: Path, name: str = "Research Base", research_dir: str = "research", agents: list[str] | None = None) -> Vault:
+ def init(root: Path, name: str = "Research Base", research_dir: str = "research") -> Vault:
"""Initialize a new vault at the given path."""
root = root.resolve()
hyperresearch_dir = root / HYPERRESEARCH_DIR
@@ -102,6 +112,7 @@ class Vault:
kb_dir = root / research_dir
(kb_dir / "notes").mkdir(parents=True, exist_ok=True)
(kb_dir / "index").mkdir(exist_ok=True)
+ (kb_dir / "temp").mkdir(exist_ok=True)
# Write config
config = VaultConfig(name=name, research_dir=research_dir)
@@ -125,9 +136,9 @@ class Vault:
"# {{ title }}\n\n"
)
- # Inject hyperresearch docs into agent config files (CLAUDE.md, AGENTS.md)
+ # Inject CLAUDE.md at vault root
from hyperresearch.core.agent_docs import inject_agent_docs
- inject_agent_docs(root, agents=agents)
+ inject_agent_docs(root)
return vault
diff --git a/src/hyperresearch/skills/research-collect.md b/src/hyperresearch/skills/research-collect.md
index d60a18e..fe2b2cc 100644
--- a/src/hyperresearch/skills/research-collect.md
+++ b/src/hyperresearch/skills/research-collect.md
@@ -129,4 +129,8 @@ When the auditor runs in conformance mode on a collect draft, it applies these c
(9) **Cross-source tension at least twice.** At least two body sections must put specific sources in tension with explicit "Source A says X; Source B says Y; I hold Z because..." structure. FAIL if the draft only cites, never contrasts.
+(10) **Citation density.** Count inline citations (parenthetical URLs or `[[note-id]]` links) in the body. FAIL if density < 8 per 1000 words, FAIL if any H2 section runs ≥300 words without a citation, FAIL if < 50% of fetched sources are cited at least once in the draft. A collect draft's authority comes from anchoring every entity claim in a source — under-citation reads as assertion without evidence.
+
+(11) **Prompt-named subtopic coverage.** For every explicitly named subtopic, entity, context, or field in the user's verbatim prompt, verify a dedicated H2 or H3 section exists. FAIL if any prompt-named item is collapsed into another section or silently dropped.
+
Auditor output: list every violation with a one-line quote from the report. The parent agent applies fixes.
diff --git a/src/hyperresearch/skills/research-compare.md b/src/hyperresearch/skills/research-compare.md
index 54a990e..5eec0b0 100644
--- a/src/hyperresearch/skills/research-compare.md
+++ b/src/hyperresearch/skills/research-compare.md
@@ -170,4 +170,8 @@ If the entities have dramatically different maturity (A has 10 years of producti
(12) **Maturity asymmetry flagged if present.** If the entities have dramatically different evidence bases, is this flagged in the opening and in affected sections? FAIL if the draft presents asymmetric alternatives as if they were evenly characterized.
+(13) **Citation density.** Count inline citations in the body. FAIL if density < 8 per 1000 words, FAIL if any entity section runs ≥300 words without a citation, FAIL if < 50% of fetched sources are cited at least once. Per-entity evaluation requires per-entity evidence — an entity description with 0-1 citations is a description, not an evaluation.
+
+(14) **Prompt-named entity coverage.** For every explicitly named entity in the user's verbatim prompt, verify a dedicated section exists with its own H2 or H3. FAIL if any named entity is collapsed or silently dropped.
+
Auditor output: list every violation with a one-line quote from the report.
diff --git a/src/hyperresearch/skills/research-ensemble.md b/src/hyperresearch/skills/research-ensemble.md
new file mode 100644
index 0000000..bf0a281
--- /dev/null
+++ b/src/hyperresearch/skills/research-ensemble.md
@@ -0,0 +1,508 @@
+---
+name: research-ensemble
+description: >
+ Ensemble research mode. Trades ~5x cost for one unified report that
+ integrates three parallel sub-runs on the SAME shared vault, each with
+ a subtly different framing that drives natural divergence in what they
+ fetch and emphasize. Opus orchestrates, spawns three Sonnet sub-runs
+ (breadth / depth / dialectical), and then spawns an Opus merger that
+ compiles the final report on comprehensiveness, readability, argument
+ strength, and citation quality. Use when depth-of-corpus and
+ argument-stability matter more than wall-clock time.
+---
+
+# Research Ensemble Protocol
+
+> You are the ensemble orchestrator. Your job is to run the `/research`
+> protocol THREE TIMES in parallel against the SAME shared vault, each
+> with a subtly different framing, then spawn a merger subagent that
+> unifies the three drafts into one final report. The user's verbatim
+> prompt is GOSPEL — identical across all three sub-runs, never altered.
+> The three "framings" are private lenses the sub-runs use to bias
+> discovery and analysis; they never enter the scaffolds or the drafts.
+
+**This is the ensemble skill. It's SEPARATE from `/research`.** The user
+typed `/research-ensemble` specifically because they want the 3-way
+compound reading. Do not convert to single-run; do not abort to
+`/research` without orchestrator-level failure.
+
+**Cost disclosure to the user — required, early.** Before you do real
+work, tell the user: "Ensemble mode costs ~5x a normal `/research` run
+(3 parallel sub-runs + merger + post-merger audit). Each sub-run
+targets 25+ fetches; combined corpus aims for 50+ sources. Takes
+longer and costs more, but produces a noticeably deeper report."
+
+---
+
+## Step 0: The same clarify-if-vague rule as `/research`
+
+If the prompt is ambiguous enough that three sub-runs might diverge
+on WHAT the user is asking (not just HOW), ask ONE clarifying
+question before proceeding. Ambiguity in scope destroys the ensemble
+— three sub-runs on three different interpretations of the prompt
+cannot be merged. Ambiguity in approach is fine; the ensemble
+exploits that.
+
+If the prompt is already clear, skip this step and proceed.
+
+---
+
+## Step 1: Classify the prompt ONCE (not per-sub-run)
+
+Read `.claude/skills/hyperresearch/SKILL.md` Step 1 — run the same
+classification logic to pick a primary modality (`collect`,
+`synthesize`, `compare`, `forecast`) and optional secondary flavor.
+
+**Classification is done ONCE.** All three sub-runs use the SAME
+modality and secondary flavor. If sub-runs reclassify individually,
+they produce structurally-incomparable drafts and the merger has
+nothing to splice.
+
+Record the classification — you will pass it to every sub-run spawn.
+
+---
+
+## Step 2: Capture the verbatim prompt as gospel
+
+Store the user's verbatim prompt (character-for-character, no edits)
+in a TodoWrite entry or a scratch note. This is what you pass into
+every sub-run's `research_query` parameter. The merger verifies all
+three sub-run scaffolds contain this text IDENTICALLY; any drift
+halts the merge.
+
+Do not paraphrase. Do not "clean up" whitespace. Do not strip
+punctuation. Copy exactly.
+
+---
+
+## Step 3: Auto-archive prior ensemble artifacts
+
+Before spawning any sub-run, check whether the vault has leftover
+per-run files from a previous ensemble attempt:
+
+```bash
+ls research/notes/final_report-run-*.md 2>/dev/null
+ls research/notes/scaffold-run-*.md 2>/dev/null
+ls research/notes/comparisons-run-*.md 2>/dev/null
+ls research/audit_findings-run-*.json 2>/dev/null
+ls research/notes/final_report.md 2>/dev/null
+```
+
+If ANY of these exist, auto-archive them to
+`research/archive/ensemble-<ISO-timestamp>/` and log the path. Do NOT
+halt and ask the user — ensemble retries after an interrupted run are
+common enough that friction on this path is a real nuisance. The
+archive preserves the prior artifacts if the user wants them; the
+ensemble proceeds cleanly.
+
+Implementation:
+
+```bash
+TIMESTAMP=$(date -u +%Y-%m-%dT%H%M%SZ)
+ARCHIVE=research/archive/ensemble-$TIMESTAMP
+mkdir -p $ARCHIVE
+# Move every prior per-run artifact, plus the prior merged report.
+mv research/notes/final_report-run-*.md $ARCHIVE/ 2>/dev/null
+mv research/notes/scaffold-run-*.md $ARCHIVE/ 2>/dev/null
+mv research/notes/comparisons-run-*.md $ARCHIVE/ 2>/dev/null
+mv research/audit_findings-run-*.json $ARCHIVE/ 2>/dev/null
+mv research/notes/final_report.md $ARCHIVE/ 2>/dev/null
+# Sync to de-index the moved notes.
+$HPR sync -j
+```
+
+Tell the user once: "Auto-archived prior ensemble artifacts to
+`research/archive/ensemble-<timestamp>/`." Then proceed. Source notes
+and extracts stay in `research/notes/` — they're part of the shared
+vault's compounding corpus and continue to be useful for this run.
+
+---
+
+## Step 4: Build the orchestration TODO list
+
+Use TodoWrite to lay out the full ensemble. Do NOT spawn anything
+until this list exists:
+
+1. Clarify prompt if vague (Step 0)
+2. Classify prompt once (Step 1)
+3. Capture verbatim prompt (Step 2)
+4. Check / archive prior artifacts (Step 3)
+5. Spawn `hyperresearch-subrun` x3 in parallel (Step 5 — one per framing)
+6. Wait for all 3 returns; collect artifacts + audit statuses
+7. **Pre-merger gate:** read each per-run audit_findings; halt on unresolved CRITICALs (Step 6)
+8. Spawn `hyperresearch-merger` (Step 7)
+9. Spawn `hyperresearch-auditor` on merged draft — comprehensiveness + conformance (Step 8)
+10. Apply audit fixes, re-audit if needed (Step 9)
+11. Save synthesis note (Step 10)
+12. Report to user (Step 11)
+
+Mark each item `completed` only after its artifact exists AND you've
+verified it with a command. Mid-orchestration crashes are recoverable
+if the TODO list accurately reflects where you stopped.
+
+---
+
+## Step 5: Spawn three `hyperresearch-subrun` agents IN PARALLEL
+
+Each sub-run receives:
+- The same verbatim `research_query` (gospel)
+- A unique `run_id` — `run-a`, `run-b`, or `run-c`
+- A unique `framing_nudge` — a 2-3 sentence private lens
+- `minimum_fetch_target` = 25 (hard floor on this sub-run's fetches)
+- The ONE classified `modality` and optional `secondary_modality`
+
+**The three framings — copy these verbatim into spawn prompts:**
+
+### run-a — evidentiary breadth
+
+```
+framing_nudge: Approach this with a bias toward evidentiary breadth.
+Prioritize casting a wide net over going deep. Emphasize primary-
+source hunting, ground-truth tier (official statistics, filings,
+policy text, institutional datasets), non-English sources where
+regionally relevant, and named dissenting voices. When spawning
+analysts, phrase their goals to maximize BREADTH of what they look
+for in each source. Target as many distinct sub-topics as the prompt
+touches, not depth within any single one.
+```
+
+### run-b — citation-chain depth
+
+```
+framing_nudge: Approach this with a bias toward citation-chain depth.
+When reading sources, prioritize tracing their references — follow
+footnote chains, fetch the originating paper not the blog post about
+it, pursue the cited dataset not the summary. When spawning analysts,
+phrase their goals to extract NEXT-TARGET URLS above all — a source
+that cites 10 other sources is more valuable to you than a source
+that concludes. Prefer fewer high-density seeds with aggressive
+rabbit-hole depth over a wide flat set of shallow reads.
+```
+
+### run-c — dialectical tension
+
+```
+framing_nudge: Approach this with a bias toward dialectical tension.
+Prioritize finding where domain experts disagree, where the dominant
+framing is challenged, where the strongest counter-argument lives.
+When running adversarial searches, use named-skeptic queries over
+generic criticism. When analysts extract, tell them to flag
+commentary's strongest dissent. Your scaffold and draft will still
+commit to a position like any `/research` run, but your source mix
+will weight the contrarian side more heavily than a default reading
+would.
+```
+
+### The spawn itself
+
+Launch all three in a single message — three parallel `Task` calls
+(this is where parallelism pays off; sequential spawns waste the
+whole point):
+
+```
+Spawn hyperresearch-subrun with:
+ research_query: <verbatim user prompt from Step 2>
+ run_id: run-a
+ framing_nudge: <the run-a text above, copied exactly>
+ minimum_fetch_target: 25
+ modality: <from Step 1>
+ secondary_modality: <from Step 1, or "none">
+
+Spawn hyperresearch-subrun with:
+ research_query: <verbatim user prompt from Step 2>
+ run_id: run-b
+ framing_nudge: <the run-b text above>
+ minimum_fetch_target: 25
+ modality: <same>
+ secondary_modality: <same>
+
+Spawn hyperresearch-subrun with:
+ research_query: <verbatim user prompt from Step 2>
+ run_id: run-c
+ framing_nudge: <the run-c text above>
+ minimum_fetch_target: 25
+ modality: <same>
+ secondary_modality: <same>
+```
+
+Each sub-run is a full `/research` protocol pass — it will take real
+time (typically 10-30 minutes each, depending on the prompt's depth).
+Wait for all three to complete before proceeding. The sub-runs share
+the vault; their fetches deduplicate naturally via
+`INSERT OR IGNORE INTO sources`; their per-run filenames and tags
+keep their scaffolds, drafts, and audit files distinct.
+
+---
+
+## Step 6: Pre-merger gate — verify all three sub-runs passed audit
+
+Each sub-run returns a summary with `audit_status`. But trust-and-
+verify: read each per-run audit file directly.
+
+For each run_id in `[run-a, run-b, run-c]`:
+
+```bash
+PYTHONIOENCODING=utf-8 $HPR lint --rule audit-gate \
+ --audit-file research/audit_findings-<run_id>.json -j
+```
+
+The `audit-gate` lint rule returns `pass` only when both
+comprehensiveness AND conformance entries exist AND every CRITICAL
+is resolved.
+
+**If any sub-run's audit-gate fails:**
+
+Do NOT spawn the merger. Surface to the user:
+
+> "Sub-run `<run_id>` did not pass audit — its findings at
+> `research/audit_findings-<run_id>.json` have unresolved CRITICAL
+> issues. All three sub-run drafts exist at
+> `research/notes/final_report-run-{a,b,c}.md` as independently
+> readable artifacts. You can:
+> 1. Review the unresolved findings, apply fixes to the sub-run's
+> draft manually (re-spawn `hyperresearch-auditor` with the
+> per-run audit path after fixes), and re-run this orchestrator.
+> 2. Accept one of the passing sub-run drafts as the final report
+> by copying it to `research/notes/final_report.md`.
+> 3. Start the ensemble over with a refined prompt."
+
+Halt the ensemble. The merger does NOT get spawned with known-bad
+sub-run inputs.
+
+**If all three sub-runs pass:** proceed to Step 7.
+
+---
+
+## Step 7: Spawn `hyperresearch-merger` (ONCE)
+
+```
+Spawn hyperresearch-merger with:
+ research_query: <verbatim user prompt from Step 2>
+ run_ids: ["run-a", "run-b", "run-c"]
+ sub_run_artifacts: {
+ "run-a": {
+ "scaffold_path": "research/notes/scaffold-run-a.md",
+ "comparisons_path": "research/notes/comparisons-run-a.md",
+ "final_report_path": "research/notes/final_report-run-a.md",
+ "audit_findings_path": "research/audit_findings-run-a.json"
+ },
+ "run-b": { ... run-b paths ... },
+ "run-c": { ... run-c paths ... }
+ }
+ parent_final_report_path: research/notes/final_report.md
+ parent_audit_path: research/audit_findings.json
+ modality: <from Step 1>
+```
+
+The merger reads all three drafts + audits + scaffolds, scores each
+on four axes, picks a base, splices in unique material from the
+other two, unions the Sources sections, proofreads, and writes the
+unified draft. It ALSO appends a `mode: merger` run to the parent's
+`audit_findings.json` with detailed scoring per sub-run.
+
+Wait for the merger to return. The merger's return shape:
+
+- `status`: pass / needs_fixes / failed
+- `merged_report_path`: `research/notes/final_report.md`
+- `base_run`: which sub-run anchored the merge
+- `splice_mode`: full / short_circuited
+- `splices_applied`: integer
+- `sources_unified`: integer
+- `combined_source_target_met`: bool
+- Any critical issues the orchestrator should surface
+
+### Merger failure fallback
+
+If `status` is `failed`, the merger writes a `mode: merger-failed`
+entry to the parent's audit_findings.json and does NOT produce
+`research/notes/final_report.md`. Surface this to the user:
+
+> "The merger could not produce a unified draft. The three sub-run
+> drafts at `research/notes/final_report-run-{a,b,c}.md` are
+> independently valid artifacts — each passed its own audit. The
+> merger reported: `<reason>`. You can pick the strongest sub-run
+> draft, promote it to `research/notes/final_report.md`, and save
+> it manually as the final report. Or re-run the ensemble."
+
+Halt. Do not proceed to Step 8 without a merged draft.
+
+---
+
+## Step 8: Run Step 11 audit on the merged draft (parent vault)
+
+The merged draft is a NEW synthesis — it gets a full adversarial
+audit in the parent vault's `research/audit_findings.json`, same as
+a normal `/research` run would.
+
+Spawn `hyperresearch-auditor` twice — sequentially, comprehensiveness
+first then conformance:
+
+```
+First spawn (wait for completion before the second):
+ research_query: <verbatim user prompt from Step 2>
+ modality: <from Step 1>
+ mode: comprehensiveness
+ final_report_path: research/notes/final_report.md
+ audit_findings_path: research/audit_findings.json
+ scaffold_note_id: <id of run-a's scaffold note, or the base_run's>
+
+Second spawn (after the first returns):
+ research_query: <verbatim user prompt from Step 2>
+ modality: <from Step 1>
+ mode: conformance
+ final_report_path: research/notes/final_report.md
+ audit_findings_path: research/audit_findings.json
+ scaffold_note_id: <same as above>
+```
+
+The auditor writes to the parent's audit_findings.json, which now
+contains:
+1. The merger's `mode: merger` entry
+2. The comprehensiveness auditor's entry
+3. The conformance auditor's entry
+
+---
+
+## Step 9: Apply audit fixes, re-audit if needed
+
+Standard fix-apply loop:
+1. Read both auditor returns. For each CRITICAL, apply the fix to
+ `research/notes/final_report.md`. The merged draft can tolerate
+ small edits here — the merger's structural spine stays, but you
+ can add a missing citation, tighten a hedge, or expand an under-
+ developed prompt-named section by pulling from the per-run
+ extract notes (tagged with `run-a`/`run-b`/`run-c`).
+2. For each fix, set the finding's `fixed_at` timestamp in the
+ parent's audit_findings.json.
+3. If any CRITICAL cannot be resolved by editing (e.g., the merged
+ draft lacks evidence for a prompt-named item AND no sub-run
+ surfaced it), the correct fix may be to fetch new sources and
+ re-audit — but at this point you are doing single-run work on the
+ merged draft, not ensemble work.
+4. Re-run `hyperresearch-auditor` (both modes) to verify the fixes
+ landed. The `audit-gate` lint rule checks that every CRITICAL in
+ the newest conformance run has `fixed_at` populated.
+
+```bash
+PYTHONIOENCODING=utf-8 $HPR lint --rule audit-gate -j
+```
+
+Must return no issues. The default `audit-gate` path is the parent's
+`research/audit_findings.json` — no `--audit-file` override needed
+at this step because you ARE checking the parent.
+
+---
+
+## Step 10: Save the synthesis — standard Step 13 of `/research`
+
+Promote the merged draft to a first-class synthesis note in the
+vault. Use the same command `/research` uses:
+
+```bash
+PYTHONIOENCODING=utf-8 $HPR note new "<concise title derived from prompt>" \
+ --tag synthesis --tag ensemble \
+ --tier institutional \
+ --content-type synthesis \
+ --summary "<one-line summary of the merged conclusion>" \
+ --status review \
+ --body-file research/notes/final_report.md \
+ -j
+```
+
+The `audit-gate` lint rule blocks save if any CRITICAL in the latest
+conformance run is unresolved — standard protection.
+
+---
+
+## Step 11: Report to the user
+
+Report a tight summary. What the user needs to see:
+
+```
+Ensemble research complete.
+
+Merged final report: research/notes/final_report.md (<N> words)
+
+Sub-run drafts (preserved for reference):
+- research/notes/final_report-run-a.md (breadth, <N> words, <K> citations)
+- research/notes/final_report-run-b.md (depth, <N> words, <K> citations)
+- research/notes/final_report-run-c.md (dialectical, <N> words, <K> citations)
+
+Merger picked run-<X> as base; <S> splices applied from siblings.
+Combined unique sources: <N> (target was 50+).
+Merged draft passed comprehensiveness + conformance audit.
+
+Per-run audit files: research/audit_findings-run-{a,b,c}.json
+Parent audit findings: research/audit_findings.json (includes merger
+entry + post-merger audits)
+```
+
+If the combined source count fell short of 50, note that explicitly
+— ensemble underperformed its volume target, which likely means all
+three sub-runs ran out of high-signal sources in the domain (benign)
+or skimped on fetching (non-benign; surface it so the user can
+decide).
+
+---
+
+## Hard rules — orchestrator scope
+
+- **The user's prompt is gospel.** Pass it verbatim to all three
+ sub-runs; the merger verifies character-for-character identity
+ across the three scaffolds' prompt sections.
+- **Classify exactly once.** All three sub-runs use the same
+ modality. No per-sub-run reclassification.
+- **Spawn the three sub-runs in parallel, not sequentially.** Three
+ `Task` calls in a single message. Sequential spawning defeats
+ half the point.
+- **Do NOT spawn the merger before verifying all three sub-run
+ audit-gates pass.** Bad sub-run inputs produce bad merges.
+- **Do NOT write to `research/notes/final_report.md` before the
+ merger runs.** That path is reserved for the merged output.
+- **Do NOT skip the post-merger audit.** The merged draft is a new
+ synthesis — it gets the same Step 11 treatment as a normal
+ `/research` run.
+- **Do NOT silently delete per-run artifacts after merging.** The
+ sub-run drafts stay on disk as independently readable artifacts
+ — users may want to see how the three framings diverged.
+- **Do NOT convert the ensemble to a single-run on sub-run failure.**
+ If a sub-run fails audit, halt and surface options. The user
+ invoked `/research-ensemble` specifically; silently degrading to
+ single-run is worse than explicit failure.
+- **Cost disclosure is mandatory, early.** The user must know ~5x
+ cost before the three sub-runs start.
+
+---
+
+## Why this design (for future maintainers)
+
+The ensemble attacks two single-run ceilings:
+
+1. **Variance ceiling** — three Sonnet sub-runs with subtly different
+ framings produce three parallel readings; compounding LLM
+ randomness drives natural divergence in source discovery and
+ emphasis. The merger picks the best-of-3 structural spine and
+ splices in unique evidence from the other two.
+
+2. **Depth-of-corpus ceiling** — because all three sub-runs share ONE
+ unified vault, their combined fetch decisions stack into a richer
+ source corpus than any single run could produce. Each sub-run
+ pushes for 25+ of its own fetches; the shared corpus grows toward
+ 60+, and every sub-run sees what the others found (natural, not
+ forced, deduplication via `INSERT OR IGNORE`).
+
+The unified vault is the critical architectural choice. Per-sub-run
+vaults would isolate the corpora, losing the compounding-knowledge
+benefit. With a shared vault, the knowledge base persists across the
+ensemble and across future sessions — a long-lived asset, not a
+per-run workspace.
+
+The three framings are deliberately SUBTLE — not radical "styles".
+Radical styles produce tonally incompatible drafts the merger can't
+harmonize. Subtle nudges plus LLM nondeterminism produce divergent
+source discovery without clashing voices; the merger's job stays
+tractable.
+
+Cost: ~5x a normal `/research` run (3 sub-runs + merger + post-
+merger audit + orchestrator overhead). Not 2x, not 3x. Be honest
+with users.
diff --git a/src/hyperresearch/skills/research-forecast.md b/src/hyperresearch/skills/research-forecast.md
index 26423e8..afa06a3 100644
--- a/src/hyperresearch/skills/research-forecast.md
+++ b/src/hyperresearch/skills/research-forecast.md
@@ -162,4 +162,8 @@ The draft must include — in the body or in the synthesis — a statement of wh
(13) **No academic API sweep was run.** Confirm via vault tags — if the corpus is dominated by `paper` content_type sources, the agent ran the wrong source strategy. FAIL (non-critical — correct the source mix and re-run).
+(14) **Citation density.** Count inline citations in the body. FAIL if density < 8 per 1000 words, FAIL if any H2 section runs ≥300 words without a citation, FAIL if < 50% of fetched sources are cited at least once. Forecasts that cite a handful of sources read as opinion; forecasts that cite widely read as reasoned positions.
+
+(15) **Prompt-named dimension coverage.** For every explicitly named force, driver, scenario, or time-horizon in the user's verbatim prompt, verify a dedicated section exists. FAIL if any prompt-named item is collapsed.
+
Auditor output: list every violation with a one-line quote from the report.
diff --git a/src/hyperresearch/skills/research-synthesize.md b/src/hyperresearch/skills/research-synthesize.md
index 85503a4..0a2f58d 100644
--- a/src/hyperresearch/skills/research-synthesize.md
+++ b/src/hyperresearch/skills/research-synthesize.md
@@ -218,4 +218,8 @@ Sections build on each other. Section 2's claim depends on section 1's setup; se
(11) **Core tension present in opening.** Does the opening state what makes the thesis non-trivial (the paradox, received view being pushed against, open problem)? FAIL if the opening is a neutral setup.
+(12) **Citation density.** Count inline citations in the body. FAIL if density < 8 per 1000 words, FAIL if any H2 section runs ≥300 words without a citation, FAIL if < 50% of fetched sources are cited at least once. The thesis-driven synthesize register can LOOK deep while actually citing only a handful of sources; cite aggressively across the argument.
+
+(13) **Prompt-named subtopic coverage.** For every explicitly named subtopic, entity, context, or field in the user's verbatim prompt, verify a dedicated H2 or H3 section exists. FAIL if any prompt-named item is collapsed into another section.
+
Auditor output: list every violation with a one-line quote from the report.
diff --git a/src/hyperresearch/skills/research.md b/src/hyperresearch/skills/research.md
index 00d7cc0..5c4edfd 100644
--- a/src/hyperresearch/skills/research.md
+++ b/src/hyperresearch/skills/research.md
@@ -140,11 +140,12 @@ Before executing Step 2, create this exact TODO list with the TodoWrite tool. Do
10. Write comparisons note (Step 8)
11. **Checkpoint 3: pre-draft gate — CRITICAL**
12. Write `research/notes/final_report.md` (Step 9)
-13. Gap analysis + adversarial search (Step 10)
-14. Adversarial audit via `hyperresearch-auditor` — both modes in parallel (Step 11)
-15. **Checkpoint 4: post-audit review**
-16. Write Opinionated Synthesis section (Step 12)
-17. Save synthesis note + health checks (Steps 13–14)
+13. Evidence recovery pass via `hyperresearch-rewriter` — one Sonnet call (Step 9.5)
+14. Gap analysis + adversarial search (Step 10)
+15. Adversarial audit via `hyperresearch-auditor` — both modes sequentially (Step 11)
+16. **Checkpoint 4: post-audit review**
+17. Write Opinionated Synthesis section (Step 12)
+18. Save synthesis note + health checks (Steps 13–14)
Mark each item `completed` only after its artifact exists AND you have verified it exists with a command. You may NOT mark item 12 (the draft) `in_progress` until items 1–11 are all `completed`. The TODO list is the process ledger.
@@ -196,9 +197,9 @@ A corpus without dissent is advocacy, not research. If the adversarial round ret
## Step 3: Fetch — guided reading loop (preferred) or batch
-**Default: the guided reading loop** (described below). Seed with 3–5 high-signal URLs, then let each iteration's analyst subagents propose next targets based on what the prior sources cite.
+**Default: the guided reading loop** (described below). **Seed broadly (10–15 high-signal URLs), then iterate aggressively.** Every iteration's analyst subagents propose next targets; every target gets fetched. The goal is exhaustive coverage of the question, not minimal corpora. A deep-research draft anchored in 25-40 fetched and analyst-read sources cites richer than one anchored in 10-15.
-**Batch fetch** only when the target set is already known and complete — e.g., the user handed you 10 URLs, or the modality file says to batch (compare activity with explicitly-named entities is the usual case).
+**Batch fetch** when the target set is already known and complete — e.g., the user handed you 20 URLs, or the modality file says to batch (compare activity with explicitly-named entities is the usual case).
### Guided reading loop protocol
@@ -213,12 +214,14 @@ fetch 3-5 seeds → hyperresearch-analyst reads each with goal in hand →
Each iteration is a research director: the analyst reads one source, proposes what to read next, and hands the decision back to the main agent. This discovers source trees you couldn't find by keyword search alone — the essay names three critics, those critics cite a 1998 monograph, the monograph references a specific passage in the primary work.
-**Phase 1 — Seed fetch.** Pick the 3–5 highest-signal URLs:
-- 1–2 canonical reference entries (Wikipedia, field survey, official docs)
-- 1–2 analytical/critical sources visible in search results
-- 0–1 adversarial/dissenting source
+**Phase 1 — Seed fetch.** Pick the **10–15 highest-signal URLs** (more for broad enumerative queries, fewer only for very narrow single-question prompts):
+- 2–3 canonical reference entries (Wikipedia, field survey, official docs)
+- 3–5 analytical/critical sources visible in search results
+- 2–3 primary sources (original papers, ground-truth datasets, official filings)
+- 2–3 adversarial/dissenting sources — named critic, contrarian view, opposing position
+- 1–2 practitioner voices (blogs, postmortems, industry perspectives) where applicable
-Spawn `hyperresearch-fetcher` on ONLY those 3–5. Do NOT batch-fetch 20 URLs upfront — half get wasted on sources the loop would tell you to skip.
+Spawn `hyperresearch-fetcher` on all of them **in parallel**. The fetcher is cheap (Haiku); parallel seed-fetching of 10-15 URLs finishes in under a minute. Exhaustive coverage beats cautious minimalism — an under-fetched corpus produces a draft that cannot cite widely.
#### When a fetch fails — try harder before giving up
@@ -262,18 +265,18 @@ $HPR note edit <new-id> ... # tries to graft a breadcrumb after the f
Backfilling is supported (the fetch CLI is idempotent on re-call with `--suggested-by`), but the resulting provenance graph has disconnected components — the new note's breadcrumb points at the suggester, but if the suggester was itself a seed, the chain looks artificial. The rooted-tree provenance lint flags this and the audit-gate blocks save until you connect the islands.
-**Phase 2 — Guided reading iterations.** For each fresh note, spawn the **`hyperresearch-analyst`** agent (Sonnet, registered at `.claude/agents/hyperresearch-analyst.md`) with `mode=guided`:
+**Phase 2 — Guided reading iterations.** For each batch of fresh notes, spawn the **`hyperresearch-analyst`** agent (Sonnet, registered at `.claude/agents/hyperresearch-analyst.md`) with `mode=guided`. The analyst accepts a LIST of 1-5 source note IDs per spawn and produces one extract note per source:
```
research_goal: <the user's original verbatim prompt>
-sub_goal: <what this specific source should contribute>
-source_note_id: <the id of the note to read>
+sub_goal: <what this batch of sources should contribute>
+source_note_ids: [<id-1>, <id-2>, <id-3>, <id-4>, <id-5>] # 1-5 ids
mode: guided
already_covered: <sub-topics prior iterations answered, or "none">
already_fetched_urls: <output of `$HPR sources list -j`>
```
-Spawn multiple analysts in parallel — one per source in the current batch. Each returns: extract content + covered sub-topics + 2–5 next_targets + coverage status.
+Group sources per spawn by semantic similarity (same sub-topic or entity — the analyst's unioned next_targets list benefits from cross-source convergence within a batch). Spawn batches in parallel — a 20-source iteration becomes 4 analyst spawns (not 20). Each returns: N extract note IDs + a consolidated Findings summary + covered sub-topics + 2–5 unioned next_targets + coverage status per source.
**Phase 3 — Main agent orchestration.** After each iteration returns:
@@ -281,7 +284,7 @@ Spawn multiple analysts in parallel — one per source in the current batch. Eac
2. Collect every extract into a running knowledge accumulator.
3. Merge and dedupe next_targets across all analysts. If three subagents propose the same URL, fetch it once — pass all three suggesting source IDs via repeated `--suggested-by` flags.
4. Prioritize next_targets by: (a) which would most likely *change* the argument if they disagreed with current sources, (b) which sub-topics the corpus doesn't yet cover, (c) which tiers are missing.
-5. **Fetch the top 3–5 next_targets WITH `--suggested-by` flag. This is mandatory:**
+5. **Fetch the top 8–12 next_targets per iteration WITH `--suggested-by` flag. This is mandatory.** Bias toward more rather than fewer — every analyst-recommended URL that gets skipped is a citation the draft won't make. Cheap fetches beat expensive re-runs.
```bash
$HPR fetch "<url>" \
@@ -303,7 +306,7 @@ Spawn multiple analysts in parallel — one per source in the current batch. Eac
- **Coverage complete** — all analyst returns report `coverage: complete` for the sub-topics you need.
- **Cycle detected** — next_targets repeat or every proposed target's fetch returns `duplicate: true` with `backlinks_added: 0`.
- **Diminishing returns** — a full iteration adds zero new sub-topics. The TodoWrite delta tracker catches this.
-- **Iteration cap: 5 full loops** — more than this and the loop is drifting, not converging. Stop and move on.
+- **Iteration cap: 8 full loops** — more than this and the loop is drifting. With 10-15 seeds and 8-12 fetches per iteration, 8 loops produces a target corpus of 40-80 sources before convergence, which is the right depth for deep research.
Then proceed to curation (Steps 5–6).
@@ -359,20 +362,22 @@ Raw fetched notes arrive with `status=draft`, `tier=unknown`, auto-detected `con
For research, the analyst is the default reading mechanism — not a fallback for big sources. Even small sources (1500 words) deserve analyst treatment because the analyst's URL-scan surfaces follow-up targets for the loop.
+The analyst is **batched**: one spawn reads 1-5 sources and produces one extract note per source. This amortizes per-spawn overhead so processing 20 draft notes means 4 analyst spawns (not 20). Group sources per spawn by semantic similarity — a batch of 5 Bronze Saints character pages converges on shared URLs; a batch mixing Bronze Saints + a physics paper + a forum thread doesn't.
+
```
-For each draft source note:
+For each batch of 1-5 draft source notes (semantically grouped):
Spawn hyperresearch-analyst with:
research_goal: <the user's original verbatim prompt>
- sub_goal: "establish what this source contributes and what URLs / authors / claims warrant follow-up"
- source_note_id: <draft note id>
+ sub_goal: "establish what these sources contribute and what URLs / authors / claims warrant follow-up"
+ source_note_ids: [<draft-id-1>, <draft-id-2>, ..., up to 5]
mode: guided
already_covered: <running list from prior analysts>
already_fetched_urls: <output of `$HPR sources list -j`>
```
-Spawn 3–5 in parallel (Sonnet, cheap). Each analyst reads the source, persists an extract note (`--add-tag extract --parent <source-id>`), and returns an extract + next_targets + coverage status.
+Spawn 3–4 batches in parallel (Sonnet, cheap). Each analyst reads its 1-5 sources sequentially, persists one extract note per source (`--add-tag extract --parent <source-id>` per extract), and returns a list of extract note IDs + a consolidated Findings summary + unioned next_targets + coverage status per source.
-Collect every analyst's next_targets into TodoWrite. After each batch, fetch the top next_targets WITH `--suggested-by` so the loop iterates. **The fetch:extract ratio after curation should be at least 1:1** — every fetched source has a paired extract note. The `analyst-coverage` lint rule catches misses at Checkpoint 2.
+Collect every analyst's next_targets into TodoWrite. After each batch, fetch the top next_targets WITH `--suggested-by` so the loop iterates. **The fetch:extract ratio after curation should be at least 1:1** — every fetched source has a paired extract note with at least 150 words of real content. The `analyst-coverage` lint rule catches both misses AND stubs at Checkpoint 2 (extracts under 150 words do NOT count — minting stubs will not satisfy the gate).
### Step B: Set metadata from the analyst's findings
@@ -436,15 +441,37 @@ Using the **Write tool**, create `research/scaffold.md` with this exact structur
<what makes this question non-trivial — the paradox, disagreement, tradeoff,
or open problem the draft has to earn its way through>
+## Prompt decomposition — one H2/H3 per named item (MANDATORY)
+<Extract EVERY explicitly named subtopic, entity, context, field, or dimension
+from the verbatim prompt. Examples: "liability in ADAS accidents" names
+{technical ADAS principles, legal frameworks, case law, regulatory guidelines};
+"Diamond Sutra in daily life, workplace, business, marriage, parenting,
+emotional well-being, interpersonal dynamics" names 7 contexts. Each MUST
+become its own H2 or H3 in the draft — NEVER collapse or merge. If the prompt
+names 7 contexts, deliver 7 sections. The audit at Step 11 FAILS if any
+prompt-named item is silently dropped or merged.>
+
+- item 1: <section title>
+- item 2: <section title>
+- ...
+
## The structural plan
-<Ordered list of sections the draft will produce. Honor every explicit
-structural mandate from "What the user explicitly asked for". Where the
-prompt is silent, apply the primary modality's default structural guidance.
+<Ordered list of sections the draft will produce. Must include one dedicated
+section per item in "Prompt decomposition" above, PLUS additional sections
+the modality requires (scaffold opening, synthesis close, etc.).
For each section, name it AND describe what it will contain in one line.>
## Where each source will land
<One line per curated source-id: which heading(s) it serves and in what role
-(ground-truth evidence, institutional synthesis, dissenting voice, etc.).>
+(ground-truth evidence, institutional synthesis, dissenting voice, etc.).
+Every source should appear in at least one section; high-signal sources
+should be cited across multiple sections.>
+
+## Citation budget
+<Plan for at least 40-80 inline citations in the final draft. Rough target:
+density of 8-16 citations per 1000 words. The same source can be cited
+multiple times across sections — list which sources will anchor which
+claims. Under-citation is the #1 failure mode.>
## Coverage checklist (the auditor will verify this)
<One line per explicit contract from "What the user explicitly asked for".
@@ -505,9 +532,18 @@ Then read your modality file's substance rules. The modality file tells you HOW
- **The opening must establish the core tension.** What makes this question non-trivial? What paradox, disagreement, tradeoff, or open problem is the draft earning its way through? If the user requested a specific opening shape (definitions, executive summary, narrative hook), honor that shape — then make it do tension-framing work.
- **Every body section must earn its analytical beat.** A section that just describes facts without making an interpretive / comparative / forward move is a catalog entry, not a research contribution. Each section ends with a so-what, a comparison, a tension, or a forward beat.
- **Sources in tension at least twice in the body.** Find two places where your sources disagree and walk the reader through the disagreement, naming both positions and explaining which is more defensible. Synthesis alone does not make up for this — the body itself must engage dissent.
-- **Every claim has a citation.** Inline parenthetical URL, or `[[note-id]]` if you want the reader to trace it in the vault.
-- **Tier weighting.** Anchor substantive claims in `ground_truth` sources. Use `institutional` for positioning. Use `practitioner` for reality checks. Use `commentary` only to characterize reception, never to establish a load-bearing claim.
-- **No padding to hit a length.** There is no length target. If your substance fits in 3,000 words, write 3,000 words. If it needs 12,000, write 12,000. A draft should be as long as the content demands.
+- **Cite aggressively. Every factual claim, every number, every attributed position, every direct or paraphrased quote gets an inline citation.** Use parenthetical URLs like `([Author Year](url))` or `([short source name](url))`. **The same source can and should be cited multiple times** across different sections whenever it anchors a different claim — treat each citation as an independent audit point, not a one-per-source rationing. A 5,000-word deep-research draft should carry **40-80 inline citations** (density of 8-16 per 1000 words); anything under 5 per 1000 reads as under-sourced to both human reviewers and automated judges. Shallow citation is the single most common failure mode in structured research writing.
+- **Exhaustive sub-topic coverage.** For every explicitly named subtopic, entity, context, or field in the user's verbatim prompt, produce a dedicated H2 or H3 section — do not collapse or merge prompt-named items. If the prompt asks for 7 contexts, deliver 7 sections. Every prompt-named subtopic should itself carry ≥3 inline citations.
+- **Tier weighting.** Anchor substantive claims in `ground_truth` sources. Use `institutional` for positioning. Use `practitioner` for reality checks. Use `commentary` only to characterize reception, never to establish a load-bearing claim. Still cite commentary when quoting reception.
+- **Length serves substance, not the reverse.** There is no fixed length target. BUT deep-research drafts typically run 5,000-12,000 words because exhaustive sub-topic coverage plus dense citation plus source-vs-source tension cannot fit in 2,000 words. If you find yourself at 3,000 words on a complex prompt, you are probably collapsing sections or under-citing — reconsider both.
+
+- **Pick numbers over hedges.** When the prompt asks a quantitative question ("how much", "how many", "to what extent", "by when"), pin down a specific figure or a tight range and cite the source. A concrete number with a citation beats an abstract characterization every time. If the evidence genuinely disagrees, state the range and name the sources on each side. Don't dodge into "this varies" or "it depends" when the user asked for a number.
+
+- **Inline citations as bracketed references AND a final Sources section.** In addition to inline parenthetical URLs, number every unique source `[1]`, `[2]`, `[3]` the first time it appears, reuse the same number on later citations, and include a `## Sources` section at the end of the draft listing `[N] Short title — URL` for every reference. This dual format (parenthetical inline + numbered footnote style + end Sources list) gives both human readers and automated reviewers a traceable audit path. Do NOT invent alternative citation formats (no unicode bracket pairs, no `†`, no author-year-only). Numbered plus final Sources list is the standard here.
+
+- **Never re-search a query you already ran in this session, and never paste a URL into a search engine.** Keep a running list of search queries you've already made, and avoid repeating them verbatim — if a query returned shallow results, rephrase meaningfully before retrying. URLs go to `$HPR fetch`, not `WebSearch`. Loop-burn from redundant search is a real failure mode.
+
+- **If you cannot cite it, cut it.** Every sentence that makes a factual claim must trace back to a source in the vault — either one you fetched this session or one the analyst surfaced from a source. Sentences that paraphrase the user's question, stall with throat-clearing ("it is important to note that..."), or summarize what you're about to say next are padding. They inflate word count without adding substance and they dilute citation density, which the auditor grades. Cut them. The only path to a longer draft is more evidence, not more words about the evidence. If a section feels thin, fetch another source — do not pad with generic prose.
### Activity-specific substance rules
@@ -530,6 +566,43 @@ The auditor applies BOTH check lists at Step 11. Secondary-flavor violations are
---
+## Step 9.5: Evidence recovery pass — spawn `hyperresearch-rewriter` ONCE
+
+**Required artifact:** the final draft, rewritten in place at `research/notes/final_report.md`, with evidence the extracts preserved but the first draft dropped now present inline with citations.
+**Verification:** the rewriter returns a recovery report naming the sections where recoveries landed and the new sources cited. A zero-recovery return is valid (means the first draft was already evidence-faithful); a fabricated recovery report is not.
+**On failure:** skip the audit and fix the rewriter invocation — the audit's citation-density checks will fail if the density gap wasn't closed.
+
+Synthesis naturally loses information. Writing a 5,000-word draft from 40+ extracts means the main agent quietly drops specifics — a number here, a named expert there, a direct quote collapsed into paraphrase. The rewriter is a cheap Sonnet pass that reads the draft plus every extract note and splices dropped evidence back in at the structurally correct location.
+
+**Spawn `hyperresearch-rewriter` exactly once.** Not per-section. Not per-extract. One call, one rewrite, one return. The rewriter is a registered Claude Code agent (`.claude/agents/hyperresearch-rewriter.md`) running on Sonnet.
+
+```
+Spawn hyperresearch-rewriter with:
+ research_query: <paste the user's verbatim prompt from scaffold §1>
+ modality: <collect | synthesize | compare | forecast>
+ final_report_path: research/notes/final_report.md
+```
+
+The rewriter:
+- Reads the draft and maps its current H2/H3 structure (does NOT add new sections)
+- Enumerates every `extract`-tagged note in the vault
+- Diffs each extract's evidence against the draft — finds numbers, quotes, named entities, source citations the draft dropped
+- Splices the highest-priority recoveries into the correct existing section with inline citations
+- Overwrites `final_report.md` with the refined draft
+- Returns a short report of what was recovered, what was skipped, and how many new citations / sources the draft now carries
+
+**Hard boundaries on the rewriter:**
+- It does NOT change the thesis, recommendation, or section order
+- It does NOT invent claims that aren't in an extract
+- It does NOT touch the `## User Prompt (VERBATIM — gospel)` section (if present)
+- It only recovers evidence with a traceable extract → source citation chain
+
+After the rewriter returns, you may spot-check the diff (read the recovery report, read the refined draft, verify the recoveries land in their stated sections) — but do not re-invoke the rewriter. If the recovery report is empty, that is a legitimate outcome meaning the first draft already covered the extracts faithfully.
+
+Then proceed to Step 10 (gap analysis) with the refined draft as your starting point.
+
+---
+
## Step 10: Gap analysis + adversarial search
After the first draft, run adversarial searches specific to your activity — the modality file names the queries. Ask yourself:
diff --git a/tests/test_cli/test_lint.py b/tests/test_cli/test_lint.py
index 1d1d94a..2a1352b 100644
--- a/tests/test_cli/test_lint.py
+++ b/tests/test_cli/test_lint.py
@@ -8,7 +8,7 @@ from hyperresearch.cli.lint import app as lint_app
from hyperresearch.core.note import write_note
-def _run_lint(vault, rule: str | None = None) -> tuple[int, str]:
+def _run_lint(vault, rule: str | None = None, audit_file: str | None = None) -> tuple[int, str]:
"""Invoke `hyperresearch lint` CLI against a vault. Returns (exit_code, stdout)."""
import os
@@ -16,9 +16,11 @@ def _run_lint(vault, rule: str | None = None) -> tuple[int, str]:
prev_cwd = os.getcwd()
try:
os.chdir(vault.root)
- args = ["--json"]
+ args: list[str] = ["--json"]
if rule:
- args = ["--rule", rule, "--json"]
+ args = ["--rule", rule, *args]
+ if audit_file:
+ args = [*args, "--audit-file", audit_file]
result = runner.invoke(lint_app, args, catch_exceptions=False)
return result.exit_code, result.output
finally:
@@ -119,6 +121,21 @@ def _write_source(vault, title: str, note_id: str, body: str = "Source content."
)
+def _write_extract(vault, note_id: str, word_count_target: int, run_tag: str | None = None):
+ """Write an extract note with a body of roughly `word_count_target` words."""
+ body = "word " * word_count_target
+ tags = ["extract"]
+ if run_tag:
+ tags.append(run_tag)
+ write_note(
+ vault.notes_dir,
+ f"Extract {note_id}",
+ body=body,
+ note_id=note_id,
+ tags=tags,
+ )
+
+
def test_provenance_rooted_tree_passes_with_valid_chain(tmp_vault):
# Build a valid chain: seed → child1 → child2, plus a few more non-seeds
# pointing at the seed or each other. 6+ sources so the rule activates.
@@ -224,13 +241,67 @@ def test_orphaned_raw_files_flags_disk_leak(tmp_vault):
assert "orphan-note" in issues[0]["message"]
-def _write_audit_findings(vault, data: dict) -> None:
+def _write_audit_findings(vault, data: dict, path: str = "research/audit_findings.json") -> None:
import json as _json
- audit_path = vault.root / "research" / "audit_findings.json"
+ audit_path = vault.root / path
audit_path.parent.mkdir(parents=True, exist_ok=True)
audit_path.write_text(_json.dumps(data, indent=2), encoding="utf-8")
+def test_audit_gate_accepts_custom_audit_file_flag(tmp_vault):
+ """Ensemble sub-runs need to point audit-gate at per-run audit files."""
+ # Parent audit_findings.json has unresolved CRITICALs — would normally block.
+ _write_audit_findings(tmp_vault, {
+ "runs": [
+ {
+ "mode": "conformance",
+ "timestamp": "2026-04-14T10:00:00Z",
+ "status": "needs_fixes",
+ "criticals": [{"id": "C0", "description": "parent gap", "fixed_at": None}],
+ "important": [],
+ "minor": [],
+ }
+ ],
+ })
+ # But the per-run file for run-a is clean. Gate should pass when pointed there.
+ _write_audit_findings(tmp_vault, {
+ "runs": [
+ {
+ "mode": "comprehensiveness",
+ "timestamp": "2026-04-14T10:00:00Z",
+ "status": "pass",
+ "criticals": [],
+ "important": [],
+ "minor": [],
+ },
+ {
+ "mode": "conformance",
+ "timestamp": "2026-04-14T10:01:00Z",
+ "status": "pass",
+ "criticals": [],
+ "important": [],
+ "minor": [],
+ },
+ ],
+ }, path="research/audit_findings-run-a.json")
+
+ _, out = _run_lint(
+ tmp_vault,
+ rule="audit-gate",
+ audit_file="research/audit_findings-run-a.json",
+ )
+ import json
+ data = json.loads(out)
+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "audit-gate"]
+ assert issues == [], f"sub-run gate should pass, got: {issues}"
+
+ # Sanity: the DEFAULT path (parent's) still blocks — the flag is scoped, not global.
+ _, out = _run_lint(tmp_vault, rule="audit-gate")
+ data = json.loads(out)
+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "audit-gate"]
+ assert len(issues) >= 1, "parent gate should still block"
+
+
def test_audit_gate_missing_file_is_open(tmp_vault):
"""No audit file = gate is OPEN (early-stage research)."""
code, out = _run_lint(tmp_vault, rule="audit-gate")
@@ -514,3 +585,63 @@ def test_orphaned_raw_files_ignores_matched_raw(tmp_vault):
data = json.loads(out)
issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "orphaned-raw-files"]
assert issues == []
+
+
+def test_analyst_coverage_counts_real_extracts(tmp_vault):
+ """A vault with enough real extracts (>= 150 words) passes the gate."""
+ for i in range(9):
+ _write_source(tmp_vault, f"Source {i}", f"source-{i}")
+ # 3 real extracts (>=150 words each) — 3/9 sources = 33% meets 1/3 floor
+ for i in range(3):
+ _write_extract(tmp_vault, f"extract-{i}", word_count_target=200, run_tag="run-a")
+ tmp_vault.auto_sync()
+
+ _, out = _run_lint(tmp_vault, rule="analyst-coverage")
+ import json
+ data = json.loads(out)
+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "analyst-coverage"]
+ assert issues == [], f"expected no issues, got: {issues}"
+
+
+def test_analyst_coverage_rejects_stub_extracts(tmp_vault):
+ """Lint-gaming defense: 45 stub extracts (<150 words) do NOT satisfy the gate.
+ This is the Q91 ensemble failure mode — orchestrator minted hollow extract
+ notes to pass analyst-coverage numerically."""
+ for i in range(9):
+ _write_source(tmp_vault, f"Source {i}", f"source-{i}")
+ # 45 STUB extracts at ~70 words each — would pass old count-based rule.
+ for i in range(45):
+ _write_extract(tmp_vault, f"stub-extract-{i}", word_count_target=70)
+ tmp_vault.auto_sync()
+
+ _, out = _run_lint(tmp_vault, rule="analyst-coverage")
+ import json
+ data = json.loads(out)
+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "analyst-coverage"]
+ assert len(issues) == 1
+ msg = issues[0]["message"]
+ # Error message must expose the stub count honestly so the agent sees the
+ # lint-gaming attempt for what it is.
+ assert "45 stub notes" in msg
+ assert "lint-gaming" in msg
+ # Zero REAL extracts → 0% coverage → error severity
+ assert issues[0]["severity"] == "error"
+
+
+def test_analyst_coverage_mixed_real_and_stub(tmp_vault):
+ """Real extracts count toward the gate; stubs are reported but ignored."""
+ for i in range(12):
+ _write_source(tmp_vault, f"Source {i}", f"source-{i}")
+ # 4 real extracts (>=150 words) — 4/12 = 33%, passes ceil(12/3)=4 threshold
+ for i in range(4):
+ _write_extract(tmp_vault, f"real-extract-{i}", word_count_target=300, run_tag="run-a")
+ # Plus 10 stubs that should not pad the count
+ for i in range(10):
+ _write_extract(tmp_vault, f"stub-extract-{i}", word_count_target=70)
+ tmp_vault.auto_sync()
+
+ _, out = _run_lint(tmp_vault, rule="analyst-coverage")
+ import json
+ data = json.loads(out)
+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "analyst-coverage"]
+ assert issues == []
diff --git a/tests/test_core/test_hooks.py b/tests/test_core/test_hooks.py
index c5c27c7..79bd492 100644
--- a/tests/test_core/test_hooks.py
+++ b/tests/test_core/test_hooks.py
@@ -2,7 +2,13 @@
from __future__ import annotations
-from hyperresearch.core.hooks import _SKILL_FILES, _install_research_skill
+from hyperresearch.core.hooks import (
+ _SKILL_FILES,
+ _install_ensemble_skill,
+ _install_merger_agent,
+ _install_research_skill,
+ _install_subrun_agent,
+)
def test_install_skill_writes_expected_files(tmp_vault):
@@ -46,3 +52,84 @@ def test_install_skill_idempotent_second_run(tmp_vault):
assert first is not None
second = _install_research_skill(tmp_vault.root)
assert second is None, "second run should report no changes"
+
+
+def test_install_ensemble_skill_creates_separate_skill_dir(tmp_vault):
+ """The ensemble skill MUST install as its own .claude/skills/<name>/SKILL.md
+ directory so Claude Code registers `/research-ensemble` as a slash-command
+ trigger. A sibling file inside .claude/skills/hyperresearch/ does NOT get
+ registered as a separate trigger — the harness discovers skills by
+ directory, not by SKILL-*.md filename variation."""
+ result = _install_ensemble_skill(tmp_vault.root)
+ # Must live at its own dir, NOT alongside hyperresearch/SKILL.md
+ own_dir_path = tmp_vault.root / ".claude" / "skills" / "research-ensemble" / "SKILL.md"
+ assert own_dir_path.exists()
+ sibling_path = tmp_vault.root / ".claude" / "skills" / "hyperresearch" / "SKILL-ensemble.md"
+ assert not sibling_path.exists(), "ensemble must NOT install as a sibling of SKILL.md"
+
+ body = own_dir_path.read_text(encoding="utf-8")
+ assert "name: research-ensemble" in body
+ assert "hyperresearch-subrun" in body
+ assert "hyperresearch-merger" in body
+ assert result is not None
+
+
+def test_install_ensemble_skill_idempotent(tmp_vault):
+ first = _install_ensemble_skill(tmp_vault.root)
+ assert first is not None
+ second = _install_ensemble_skill(tmp_vault.root)
+ assert second is None
+
+
+def test_install_research_skill_prunes_stale_ensemble_sibling(tmp_vault):
+ """Pre-refactor vaults had SKILL-ensemble.md inside the hyperresearch dir.
+ After the fix, that path must be pruned on reinstall so users don't end
+ up with both old and new files (confusing — two sources of truth)."""
+ hyperresearch_skill_dir = tmp_vault.root / ".claude" / "skills" / "hyperresearch"
+ hyperresearch_skill_dir.mkdir(parents=True, exist_ok=True)
+ stale_ensemble = hyperresearch_skill_dir / "SKILL-ensemble.md"
+ stale_ensemble.write_text("pre-refactor ensemble content\n", encoding="utf-8")
+
+ _install_research_skill(tmp_vault.root)
+
+ assert not stale_ensemble.exists(), "stale SKILL-ensemble.md in hyperresearch dir was not pruned"
+
+
+def test_install_subrun_agent_writes_file(tmp_vault):
+ result = _install_subrun_agent(tmp_vault.root, "hyperresearch")
+ agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-subrun.md"
+ assert agent_path.exists()
+ body = agent_path.read_text(encoding="utf-8")
+ assert "model: sonnet" in body
+ assert "Task" in body # tools list must include Task for nested spawning
+ assert "framing_nudge" in body
+ assert "minimum_fetch_target" in body
+ assert "run_id" in body
+ assert result is not None
+
+
+def test_install_subrun_agent_idempotent(tmp_vault):
+ first = _install_subrun_agent(tmp_vault.root, "hyperresearch")
+ assert first is not None
+ second = _install_subrun_agent(tmp_vault.root, "hyperresearch")
+ assert second is None
+
+
+def test_install_merger_agent_writes_file(tmp_vault):
+ result = _install_merger_agent(tmp_vault.root, "hyperresearch")
+ agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-merger.md"
+ assert agent_path.exists()
+ body = agent_path.read_text(encoding="utf-8")
+ assert "model: opus" in body
+ assert "scores" in body
+ assert "splice" in body.lower()
+ assert "merger-failed" in body
+ assert "parent_final_report_path" in body
+ assert result is not None
+
+
+def test_install_merger_agent_idempotent(tmp_vault):
+ first = _install_merger_agent(tmp_vault.root, "hyperresearch")
+ assert first is not None
+ second = _install_merger_agent(tmp_vault.root, "hyperresearch")
+ assert second is None
diff --git a/tests/test_core/test_note.py b/tests/test_core/test_note.py
index f9ff2fe..56069aa 100644
--- a/tests/test_core/test_note.py
+++ b/tests/test_core/test_note.py
@@ -41,12 +41,17 @@ def test_write_avoids_collision(tmp_vault):
def test_write_with_parent(tmp_vault):
+ """`parent:` is frontmatter metadata (DB-indexed), NOT a filesystem dir."""
path = write_note(
tmp_vault.notes_dir,
"Child Note",
parent="parent-topic",
)
- assert "parent-topic" in str(path)
+ # Flat layout: note lives directly under notes_dir, not in a parent-slug subdir.
+ assert path.parent == tmp_vault.notes_dir
+ assert path.name == "child-note.md"
+ # parent still appears in the YAML frontmatter for DB filtering.
+ assert "parent: parent-topic" in path.read_text(encoding="utf-8")
def test_read_extracts_links(tmp_vault):
diff --git a/tests/test_core/test_patterns.py b/tests/test_core/test_patterns.py
index b233390..b4fd54d 100644
--- a/tests/test_core/test_patterns.py
+++ b/tests/test_core/test_patterns.py
@@ -62,6 +62,17 @@ def test_cite_prefixes_are_case_insensitive():
assert not is_valid_wiki_link_target("Fn-3")
+def test_space_separated_footnote_names_rejected():
+ """HTML footnote rendering: <sup>Note 1</sup> → [[Note 1]]. The Q91
+ ensemble run produced stubs for these because the filter missed them."""
+ assert not is_valid_wiki_link_target("Note 1")
+ assert not is_valid_wiki_link_target("Note 2")
+ assert not is_valid_wiki_link_target("Footnote 12")
+ assert not is_valid_wiki_link_target("note 10")
+ assert not is_valid_wiki_link_target("Endnote 3")
+ assert not is_valid_wiki_link_target("Ref 42")
+
+
def test_valid_note_ids_accepted():
# Real note IDs should pass through
assert is_valid_wiki_link_target("pegasus-seiya")
diff --git a/tests/test_core/test_vault.py b/tests/test_core/test_vault.py
index 9f80aa8..53b7370 100644
--- a/tests/test_core/test_vault.py
+++ b/tests/test_core/test_vault.py
@@ -19,6 +19,10 @@ def test_init_creates_structure(tmp_path: Path):
assert vault.research_dir.is_dir()
assert vault.notes_dir.is_dir()
assert vault.index_dir.is_dir()
+ # Sidelined artifacts (stubs, drift) go here so notes/ stays clean
+ assert vault.temp_dir.is_dir()
+ assert vault.temp_dir.parent == vault.research_dir
+ assert vault.temp_dir.name == "temp"
def test_init_custom_dir(tmp_path: Path):
@@ -59,9 +63,12 @@ def test_agent_docs_created(tmp_path: Path):
assert "hyperresearch" in content
-def test_agent_docs_all(tmp_path: Path):
- vault = Vault.init(tmp_path / "kb-all", agents=["claude", "agents", "gemini", "copilot"])
+def test_init_only_creates_claude_md(tmp_path: Path):
+ """Vault.init writes CLAUDE.md ONLY — no AGENTS.md, GEMINI.md, or
+ .github/copilot-instructions.md. hyperresearch is Claude Code-only;
+ multi-platform doc generation was removed in v0.6."""
+ vault = Vault.init(tmp_path / "kb-claude-only")
assert (vault.root / "CLAUDE.md").exists()
- assert (vault.root / "AGENTS.md").exists()
- assert (vault.root / "GEMINI.md").exists()
- assert (vault.root / ".github" / "copilot-instructions.md").exists()
+ assert not (vault.root / "AGENTS.md").exists()
+ assert not (vault.root / "GEMINI.md").exists()
+ assert not (vault.root / ".github" / "copilot-instructions.md").exists()