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.8.0 — V8.3 release: drop layercake codename, /hyperresearch + /research aliases (#9)

Jordan Gibbsda77656ebf07
diff --git a/.gitignore b/.gitignore
index 9c756b4..de8e6ad 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,6 +14,7 @@ build/
.env
bench/
codex_bench/
+draco-bench/
# Agent install outputs — generated per-user by `hyperresearch install`.
# These files contain absolute paths resolved to the installing user's
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6a87dd2..7c4f845 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,14 +1,32 @@
# Changelog
+## [0.8.0] - 2026-04-29
+
+### Architecture — V8.3 deployment release
+
+The flagship pipeline ships as a tier-adaptive 16-step chain. The `/research-layercake` slash command is retired; the entry skill is now invokable as both `/hyperresearch` and `/research`. Internal codename "layercake" is gone — everywhere — replaced by the product name. The simple V1 single-pass research skill and its four modality variants are removed; the V8 `light` tier replaces them as the fast path for bounded queries.
+
+### Changed
+- **Entry skill aliasing.** `hyperresearch install` now writes the entry skill to both `.claude/skills/hyperresearch/SKILL.md` and `.claude/skills/research/SKILL.md` so Claude Code registers `/hyperresearch` and `/research` as independent triggers for the same V8 pipeline.
+- **Step skills renamed.** All 16 step skills moved from `layercake-N-name` to `hyperresearch-N-name`. The Skill-tool invocations in every step file route to the new names. Pre-existing `layercake-*` skill directories are pruned automatically on the next `hyperresearch install`.
+- **V1 skills removed.** `research.md`, `research-collect.md`, `research-compare.md`, `research-forecast.md`, `research-synthesize.md` deleted from the source tree. The V8 `light` tier (steps 1 → 2 → 10 → 15 → 16) is the fast path for short bounded queries.
+- **Light tier coherence.** Step 10's light path now has explicit guidance for vault-driven evidence sourcing, structural-heading compliance, citation rendering, and hygiene rules. Step 15's integrity gate is tier-conditional — it no longer demands critic-findings or patch-log artifacts when those steps were tier-skipped.
+- **Lint workflow rule** renamed from "Layercake artifacts missing" to "Hyperresearch artifacts missing" (cosmetic).
+
+### Pruned on upgrade
+- Skill dir `research-layercake` deleted (superseded by `/hyperresearch` alias).
+- V1 modality files (`SKILL-collect.md`, `SKILL-synthesize.md`, `SKILL-compare.md`, `SKILL-forecast.md`) removed from the install dir.
+- Legacy `layercake-*` step-skill directories cleaned up.
+
## [0.7.0] - 2026-04-17
-### Architecture — `/research-ensemble` retired, `/research-layercake` introduced
+### Architecture — `/research-ensemble` retired, `/hyperresearch` introduced
This release replaces the three-parallel-drafts-plus-merger ensemble design with a seven-phase layered pipeline. Width is discovered first, depth loci are derived from the width corpus (not pre-assigned framings), one draft is written from the combined evidence, three adversarial critics run in parallel against it, and the draft is then modified ONLY by surgical Edit hunks — never regenerated.
### New
-- **7-phase layercake pipeline** — (1) width sweep via parallel fetchers, (2) two parallel loci-analysts identify 1–8 depth loci from the corpus, (3) one depth-investigator per locus writes an `interim-<locus>.md` note, (4) orchestrator writes ONE draft, (5) dialectic / depth / width critics return structured findings JSONs, (6) the patcher applies findings as Edit hunks, (7) the polish auditor cuts filler and strips hygiene leaks via more Edit hunks. Protocol lives at `.claude/skills/research-layercake/SKILL.md`.
+- **7-phase hyperresearch pipeline** — (1) width sweep via parallel fetchers, (2) two parallel loci-analysts identify 1–8 depth loci from the corpus, (3) one depth-investigator per locus writes an `interim-<locus>.md` note, (4) orchestrator writes ONE draft, (5) dialectic / depth / width critics return structured findings JSONs, (6) the patcher applies findings as Edit hunks, (7) the polish auditor cuts filler and strips hygiene leaks via more Edit hunks. Protocol lives at `.claude/skills/hyperresearch/SKILL.md`.
- **Tool-locked patcher + polish auditor** — both agents register with tools `[Read, Edit]` ONLY. They physically cannot Write. Every hunk is capped at 500 chars of net expansion — any critic that proposes a larger patch escalates to the orchestrator instead of triggering a rewrite. This is the load-bearing invariant that enforces PATCH-NOT-REGEN at the tool level, not the prompt level.
- **`NoteType.INTERIM`** — new first-class note type for depth-investigator outputs. Persisted in the vault with `type: interim` and tagged `locus-<name>` for indexability. Added to the SQLite CHECK constraint via migration v7.
- **`locus-coverage` lint rule** — reads `research/loci.json` (Layer 2 output) and verifies every identified locus has a corresponding interim-report note. Missing interims flag as errors.
@@ -23,7 +41,7 @@ This release replaces the three-parallel-drafts-plus-merger ensemble design with
- **`/research-ensemble` skill** — the three-parallel-sub-run ensemble protocol is gone. The slash command no longer registers.
- **Retired subagents** — `hyperresearch-analyst`, `hyperresearch-auditor`, `hyperresearch-rewriter`, `hyperresearch-subrun`, `hyperresearch-merger` are no longer installed. On reinstall, any vault that had them gets them pruned automatically by `_prune_retired_agents()`.
-- **`analyst-coverage` lint rule** — superseded by `locus-coverage` (extracts were the ensemble era's per-source deep-read artifact; interim notes are the layercake equivalent scoped per locus).
+- **`analyst-coverage` lint rule** — superseded by `locus-coverage` (extracts were the ensemble era's per-source deep-read artifact; interim notes are the hyperresearch equivalent scoped per locus).
### New subagent roster (9 agents)
diff --git a/README.md b/README.md
index 0d760a9..70125e3 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
<img src="assets/banner.png" alt="HYPERRESEARCH" width="700">
</p>
-<h3 align="center">The Most Intelligent Deep Research Agent Harness</h3>
+<h3 align="center">A Deep Research Harness for Claude Code</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,327 +13,146 @@
---
-**HyperResearch is a deep research harness for Claude Code. It produces adversarially-audited reports with full source provenance and creates a persistent, searchable knowledge base that compounds across sessions.**
+**Hyperresearch turns Claude Code into a deep research agent — and currently leads the DeepResearch-Bench RACE leaderboard internally.** A tier-adaptive 16-step pipeline produces adversarially-audited reports with full source provenance. Every fetched source lands in a persistent, searchable vault that compounds across sessions.
-## Installation
+<p align="center">
+ <img src="assets/benchmark.png" alt="DeepResearch-Bench top-5 — hyperresearch leads the chart ahead of Grep Deep Research, Cellcog Max, nvidia-aiq, Gemini Deep Research, and OpenAI Deep Research" width="780">
+</p>
+
+<p align="center"><sub>Forward-looking projection from a stratified pilot against the DeepResearch-Bench leaderboard snapshot (muset-ai/DeepResearch-Bench-Leaderboard). Full 100-query sweep pending.</sub></p>
+
+## Install
```bash
pip install hyperresearch
hyperresearch install
```
-In Claude Code, type `/research-layercake <anything>` and the full flagship protocol fires — **a 7-phase pipeline that discovers width first, derives depth loci from the width corpus, runs parallel depth investigations, drafts once, and patches the draft via adversarial critics (no regeneration).** This is the default way to use hyperresearch. If you want a faster single-pass run instead, type `/research <anything>`.
-
-That single install command creates a v7 SQLite vault, auto-installs Chromium for headless browsing, generates `CLAUDE.md`, installs both skills (`/research-layercake` and `/research`), registers eight subagents (fetcher / loci-analyst / depth-investigator / dialectic-critic / depth-critic / width-critic / patcher / polish-auditor) into `.claude/agents/`, and wires PreToolUse hooks.
-
----
-
-## What it actually produces
-
-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?"*
-
-### Provenance breadcrumbs in every fetched note
-
-```
-asymmetric-auctions-with-more-than-two.md
-
-*Suggested by [[games-and-economic-behavior-73-2011-479495]] — Hubbard on
-asymmetric auctions with more than two bidders*
-```
-
-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": "..." }
- ]
-}
-```
-
-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
+In Claude Code, type `/research <anything>` or `/hyperresearch <anything>` (they're aliases for the same pipeline). Step 1 classifies your query into one of three tiers and the rest of the pipeline scales accordingly:
-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:
+| Tier | Steps that run | Typical cost | Typical time |
+|---|---|---|---|
+| `light` | bounded factual queries — 1 → 2 → 10 → 15 → 16 | ~$3–8 | ~3–8 min |
+| `standard` | landscape surveys, multi-entity comparisons | ~$10–22 | ~10–22 min |
+| `full` | deep argumentative analysis with adversarial review | ~$35–65 | ~25–60 min |
-```
-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 single install command provisions a SQLite vault, auto-installs Chromium for headless browsing, generates `CLAUDE.md`, registers the entry skill at both `/research` and `/hyperresearch`, installs all 16 step skills, and wires the agent roster + PreToolUse hooks into `.claude/`.
---
-## `/research-layercake` — 7 phases, one draft, patched not regenerated (the default)
-
-The flagship research surface and the default way to use hyperresearch. Type `/research-layercake <query>` in Claude Code.
-
-**Width before depth, then one draft patched by adversarial critics.** An Opus orchestrator walks a seven-phase pipeline: wide corpus sweep → rabbithole identification → parallel depth investigations → single draft → three adversarial readings → surgical patch pass → polish audit.
+## How it works — the 16-step pipeline
-### The 7 phases
+The entry skill is a thin **router**. It bootstraps the canonical research query, then invokes one step skill per pipeline phase via Claude Code's `Skill` tool. Each step's procedure is loaded fresh into context only when needed — defeating the context-compaction problem that makes monolithic long pipelines silently drop steps.
-1. **Width sweep.** The orchestrator spawns parallel `hyperresearch-fetcher` Haiku agents to build a 30–80 source corpus covering the topic's corners. Academic APIs (Semantic Scholar, arXiv, OpenAlex, PubMed) run BEFORE web search — citation-ranked canonical papers before derivative commentary.
-2. **Loci analysis.** Two `hyperresearch-loci-analyst` Sonnet agents read the width corpus in parallel and each returns 1–8 specific "depth loci" — questions where deeper investigation would meaningfully improve the final report. The orchestrator dedupes their outputs and clamps to 6.
-3. **Depth investigation.** One `hyperresearch-depth-investigator` Sonnet agent per locus, in parallel. Each investigator can spawn its own fetchers (capped at 10 new sources), reads the existing vault, and writes ONE `interim-<locus>.md` note with dense synthesis, direct quotes, and citations. The orchestrator consumes these interim notes during Layer 4.
-4. **Draft.** The orchestrator writes `research/notes/final_report.md` ONCE, weaving the width corpus with the interim notes under the modality file's substance rules (collect / synthesize / compare / forecast).
-5. **Adversarial critique.** Three Opus critics fire in parallel: `dialectic-critic` (counter-evidence the draft missed), `depth-critic` (shallow spots the interim notes could fill), `width-critic` (topical corners the draft ignores despite the corpus supporting them). Each returns a findings JSON with structured `suggested_patch` entries — never a rewrite.
-6. **Patch pass.** `hyperresearch-patcher` (Sonnet, **tool-locked to `[Read, Edit]`**) reads all three findings files and applies them as surgical Edit hunks. Per-hunk cap: `new_string` may be at most 500 chars longer than `old_string`. The patcher physically cannot Write — it has no path to regenerate the draft.
-7. **Polish audit.** `hyperresearch-polish-auditor` (Sonnet, also `[Read, Edit]` only) strips hygiene leaks (YAML frontmatter, scaffold sections, prompt echoes), cuts filler phrases ("Importantly", "It is worth noting"), removes redundancy, and breaks long sentences — all via surgical Edits. Structural mismatches (wrong format for the prompt, missing sections) escalate to the orchestrator rather than getting force-patched.
+| # | Step | What it does | Tiers |
+|---|---|---|---|
+| 1 | Decompose | Canonical query → atomic items + coverage matrix + tier classification | all |
+| 2 | Width sweep | Multi-perspective search plan + parallel fetcher waves (Haiku) | all |
+| 3 | Contradiction graph | Pair contradictions across the corpus into ranked clusters | std/full |
+| 4 | Loci analysis | Two parallel loci-analysts → scored loci with source budgets | full |
+| 5 | Depth investigation | K parallel depth-investigators → interim notes with committed positions | full |
+| 6 | Cross-locus reconcile | Reconcile committed positions → comparisons.md | full |
+| 7 | Source tensions | Extract expert disagreements → source-tensions.json | full |
+| 8 | Corpus critic | "What source would overturn this?" + targeted gap-fill fetch | full |
+| 9 | Evidence digest | Top claims + verbatim quotes → evidence-digest.md | std/full |
+| 10 | Triple draft | Per-angle source curation + 3 parallel draft sub-orchestrators | all |
+| 11 | Synthesize | Plan + outline + spawn synthesizer subagent → final_report.md | std/full |
+| 12 | Critics | 4 adversarial critics in parallel → findings JSONs | std/full |
+| 13 | Gap-fetch | Targeted fetch wave for critic-identified vault gaps | std/full |
+| 14 | Patcher | Surgical Edit hunks applied to draft (tool-locked Read+Edit) | std/full |
+| 15 | Polish | Hygiene + filler pass (tool-locked Read+Edit subagent) | all |
+| 16 | Readability audit | Recommender writes JSON suggestions; orchestrator selectively applies | all |
-### Why the tool lock matters
+### The two load-bearing invariants
-The load-bearing invariant of layercake is: **after Layer 4 the draft is only ever modified by small Edit hunks.** This is enforced at the Claude Code tool-allowlist level — the patcher and polish auditor do not have `Write` or `Bash`. If a critic's finding cannot fit into a ≤500-char hunk, it escalates to the orchestrator as a structural issue instead of triggering a regeneration. This prevents the "just rewrite it" failure mode that plagues post-hoc review in long-running agent pipelines.
+1. **Patch, never regenerate.** After step 11 produces the synthesized report (or step 10 for light tier), the only modifications are surgical Edit hunks. The patcher and polish auditor are tool-locked to `[Read, Edit]` at the Claude Code allowlist level — they physically cannot Write a new draft. Per-hunk caps make "just rewrite it" mechanically impossible. Critic findings that don't fit a small hunk escalate as structural issues.
-### Opting out — faster single-pass mode
+2. **Canonical research query is gospel.** The verbatim user prompt is persisted to `research/query-<vault_tag>.md` once and re-read by every subsequent step and every spawned subagent. Wrapper requirements (save paths, citation format, terminal sections) are a separate contract — they never contaminate the query itself.
-Layercake is the default because width-plus-depth-plus-adversarial-review beats a single investigator on almost every real research query. If you want a faster single-pass run — e.g., for a quick sanity-check or a prompt where one pass is plenty — type `/research <query>` instead. Single-pass fires the same modality rules on one Sonnet agent, no loci analysis, no critics, no patcher.
+### Subagent roster
-A rule of thumb: use `/research-layercake` for anything you would want a human researcher to take seriously. Use `/research` when you just want the vault populated and a first-pass draft in front of you quickly.
+| Agent | Model | Role |
+|---|---|---|
+| `hyperresearch-fetcher` | Haiku | URL fetching via crawl4ai; runs 8–12 in parallel per wave |
+| `hyperresearch-source-analyst` | Sonnet (1M ctx) | End-to-end digest of any single long source >5000 words |
+| `hyperresearch-loci-analyst` | Sonnet | Reads the width corpus, returns 1–8 depth loci with rationale |
+| `hyperresearch-depth-investigator` | Sonnet | Investigates one locus, writes one interim note with a committed position |
+| `hyperresearch-corpus-critic` | Sonnet | "What source would overturn the current direction?" pre-draft gap analysis |
+| `hyperresearch-draft-orchestrator` | Sonnet | One per draft angle; reads its curated source list and writes one draft |
+| `hyperresearch-synthesizer` | Opus | Reads all 3 drafts, writes the final report (two-pass write, Read+Write locked) |
+| `hyperresearch-dialectic-critic` | Opus | Counter-evidence the draft missed |
+| `hyperresearch-depth-critic` | Opus | Shallow spots interim notes could fill |
+| `hyperresearch-width-critic` | Opus | Topical corners the corpus supports but the draft ignores |
+| `hyperresearch-instruction-critic` | Opus | Structural mismatches against the prompt's atomic items |
+| `hyperresearch-patcher` | Opus | Tool-locked `[Read, Edit]`. Applies critic findings as surgical Edit hunks |
+| `hyperresearch-polish-auditor` | Opus | Tool-locked `[Read, Edit]`. Cuts filler, strips hygiene leaks |
+| `hyperresearch-readability-recommender` | Opus | Writes JSON suggestions for paragraph rhythm and list/table conversion |
---
## The vault: persistent, searchable, compounding
-hyperresearch is not a one-shot report generator. Every fetched source lands in a durable SQLite-indexed vault that every future research session can reuse. Knowledge compounds across sessions; the tool's value grows with the corpus.
-
-### What persists
-
-- **Raw source material, not rewritten summaries.** Fetched content keeps its original formatting — headings, tables, code blocks, technical details. If the source is a PDF, pymupdf extracts the full text and the original PDF lives at `research/raw/<note-id>.pdf`. Every note carries its source URL, fetch timestamp, tier classification, and `--suggested-by` breadcrumb pointing at whichever note surfaced it.
-- **Extract notes** — per-source analyst reads with direct quotes, context markers, one-line summaries, and inherited tier + content-type tags. These are the second derivative of raw content and stay in the vault as first-class, queryable notes.
-- **Scaffolds, comparisons, audit findings** — every research session's planning artifacts and adversarial review trail persist alongside the sources they drew on. Past synthesis notes are discoverable next to the raw sources that justified them.
-- **The knowledge graph** — `[[wiki-links]]` between notes form a queryable graph. `hyperresearch graph hubs` surfaces the most-connected notes in a domain; `hyperresearch graph backlinks <id>` shows every note that references a given source.
-
-### Searchability
-
-Before any web search the vault gets queried first — the hook reminds Claude Code, and the protocol checks explicitly:
+Hyperresearch is not a one-shot report generator. Every fetched source lands in a SQLite-indexed vault that every future research session can reuse.
```bash
-hyperresearch search "ion-trap gate fidelity" -j # Full-text across every note
-hyperresearch search "quantum" --tier ground_truth -j # Filter by epistemic tier
-hyperresearch search "attention" --include-body -j # Full-body search, not just titles
-hyperresearch note show <id> <id> <id> -j # Batch-read notes in one call
-```
-
-When the vault already holds ≥10 relevant notes on a topic, `/research` tells the user so and asks whether to dig deeper, take a new angle, or synthesize from the existing corpus — instead of re-fetching what's already there. The sunk-cost of past research pays forward.
-
-### Markdown is truth, SQLite is cache
-
-Notes live as plain markdown with YAML frontmatter in `research/notes/`. The SQLite index is fully rebuildable — delete it and `hyperresearch sync` reconstructs it from the markdown. The vault is inspectable in any editor, version-controllable in git, and readable without the tool installed. hyperresearch stores and indexes; it does not hide data behind the tool.
-
----
-
-## Why it works on hard research
-
-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:
-
-- **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
-
----
-
-## How it works — the contextual flow
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│ │
-│ 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 ─────────────────────────┘
-│ │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-**Subagent roster**, each picked for its job:
-
-| Agent | Model | Role |
-|---|---|---|
-| `hyperresearch-fetcher` | **Haiku** | Mechanical URL fetching via crawl4ai. Cheap, fast, parallel. |
-| `hyperresearch-loci-analyst` | **Sonnet** | Reads the width corpus, returns 1–8 depth loci with rationale. Spawn 2 in parallel, dedupe. |
-| `hyperresearch-depth-investigator` | **Sonnet** | Investigates one locus: fetches new sources, writes one interim-report note per locus. |
-| `hyperresearch-dialectic-critic` | **Opus** | Finds counter-evidence the draft missed, emits structured findings with surgical patches. |
-| `hyperresearch-depth-critic` | **Opus** | Finds shallow spots where interim notes could fill specifics. |
-| `hyperresearch-width-critic` | **Opus** | Finds topical corners the corpus supports but the draft ignores. |
-| `hyperresearch-patcher` | **Sonnet** | Tool-locked `[Read, Edit]`. Applies critic findings as surgical Edit hunks. Cannot regenerate. |
-| `hyperresearch-polish-auditor` | **Sonnet** | Tool-locked `[Read, Edit]`. Cuts filler, strips hygiene leaks, breaks long sentences. |
-
-**Routing** — the dispatcher classifies every request by **what the output needs to do**, not what the subject is:
-
-```
-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
+hyperresearch search "ion-trap gate fidelity" -j # Full-text search
+hyperresearch search "quantum" --include-body -j # Full-body search
+hyperresearch note show <id1> <id2> <id3> -j # Batch-read notes
+hyperresearch graph hubs -j # Most-connected notes
+hyperresearch graph backlinks <id> -j # Reverse links
+hyperresearch lint -j # Health check (broken links, missing tags)
```
-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.
-
----
-
-## What's enforced
+**Markdown is truth, SQLite is cache.** Notes live as plain markdown with YAML frontmatter in `research/notes/`. The SQLite index is fully rebuildable — delete it and `hyperresearch sync` reconstructs it from the markdown. The vault is inspectable in any editor, version-controllable in git, and readable without the tool installed.
-Nine invariants the protocol structurally prevents from breaking:
+**PDFs fetch directly.** `hyperresearch fetch` auto-detects PDF URLs (arXiv, NBER, SSRN, direct `.pdf` links) and extracts full text via pymupdf. Raw PDFs land in `research/raw/<note-id>.pdf` and the note's `raw_file:` frontmatter links back.
-1. **Verbatim prompt as gospel** — `scaffold-prompt` lint blocks 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. **Locus coverage** — every Layer 2 locus must have a Layer 3 `interim-<name>.md` note; missing interims flag as errors
-4. **Patch-only draft modification** — after Layer 4, the patcher and polish auditor are tool-locked to `[Read, Edit]`. They cannot regenerate; the ≤500-char hunk-expansion cap is a mechanical tripwire
-5. **Critical findings never silently skip** — `patch-surgery` lint surfaces any critical finding the patcher couldn't apply
-6. **Schema integrity** — `tier`, `content_type`, and `type` are SQLite CHECK-constrained vocabularies; corrupted frontmatter cannot poison the index
-7. **PDF + raw artifact persistence** — fetched PDFs land in `research/raw/` and the `raw_file` frontmatter field survives every re-serialization
-8. **Interim notes are persisted, not ephemeral** — depth-investigator outputs stay in the vault forever; future sessions can query them
-9. **Hygiene leaks caught on the way out** — scaffold sections, YAML frontmatter, and prompt echoes are stripped by the polish auditor before ship
+**Provenance breadcrumbs.** Every fetched source carries a `--suggested-by` link back to whatever surfaced it. The chain forms a rooted tree from seed fetches; the `provenance` lint rule catches disconnected components.
---
-## What hyperresearch doesn't do
+## What's structurally enforced
-- 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.
+- **Verbatim prompt as gospel** — `scaffold-prompt` lint blocks if the scaffold doesn't open with the user's exact prompt
+- **Locus coverage** — every step 4 locus must have a step 5 interim note; missing interims flag as errors
+- **Patch-only modification** — steps 14, 15, 16 are tool-locked to `[Read, Edit]`. They cannot regenerate the draft
+- **Critical findings never silently skip** — `patch-surgery` lint surfaces any critical finding the patcher couldn't apply
+- **Schema integrity** — `tier`, `content_type`, and `type` are SQLite CHECK-constrained vocabularies; corrupted frontmatter cannot poison the index
+- **Hygiene leaks caught on the way out** — scaffold sections, YAML frontmatter, and prompt echoes are stripped by step 15 before ship
---
-## Use cases
-
-- **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
-
-All of the above run under the default [`/research-layercake`](#research-layercake--7-phases-one-draft-patched-not-regenerated-the-default) mode: width sweep → loci analysis → depth investigations → one draft → three adversarial critics → surgical patch pass → polish audit. For faster turnaround when the query doesn't warrant the full pipeline, type `/research <query>` for a single-pass run.
-
----
-
-## What `hyperresearch install` wires into Claude Code
-
-One command sets up the full integration:
-
-- **`.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-layercake/`** — `/research-layercake` skill (the 7-phase pipeline)
-- **`.claude/agents/`** — eight registered subagents: `hyperresearch-fetcher` (Haiku), `hyperresearch-loci-analyst` (Sonnet), `hyperresearch-depth-investigator` (Sonnet), `hyperresearch-dialectic-critic` (Opus), `hyperresearch-depth-critic` (Opus), `hyperresearch-width-critic` (Opus), `hyperresearch-patcher` (Sonnet, `[Read, Edit]`-locked), `hyperresearch-polish-auditor` (Sonnet, `[Read, Edit]`-locked)
-- **`CLAUDE.md`** at the vault root — the full research workflow, automatically loaded by Claude Code on every session
-
-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.
-
----
+## Authenticated crawling
-## Commands
+Fetch from LinkedIn, Twitter, paywalled sites — anything you can log into:
```bash
-# Research workflow
-hyperresearch fetch <url> --tag t -j # Fetch a URL into the KB
-hyperresearch fetch <url> --suggested-by <id> -j # Track provenance during the guided loop
-hyperresearch fetch <url> --visible -j # Bypass bot detection with a visible browser
-
-# Search + read
-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 # Frontmatter only (cheap triage)
-hyperresearch note list --status draft -j # List notes with summaries
-
-# Knowledge graph
-hyperresearch link --auto -j # Auto-link related notes
-hyperresearch graph hubs -j # Most-connected notes
-hyperresearch graph backlinks <id> -j # What links to this note
-
-# Health checks
-hyperresearch lint -j # Run all rules
-hyperresearch lint --rule scaffold-prompt -j # Verbatim prompt gospel rule
-hyperresearch lint --rule provenance -j # Rooted-tree breadcrumb chain
-hyperresearch lint --rule audit-gate -j # Self-certification detector
-hyperresearch lint --rule analyst-coverage -j # Extract:source ratio
-hyperresearch repair -j # Fix links, rebuild indexes
+hyperresearch setup # Browser opens. Log into your sites. Done.
```
-Every command returns `{"ok": true, "data": {...}}` with `-j`.
+LinkedIn, Twitter, Facebook, Instagram, and TikTok automatically use a visible browser to avoid session kills.
---
-## Authenticated crawling
+## Academic APIs before web search
-Fetch from LinkedIn, Twitter, paywalled sites — anything you can log into:
+For any topic with a research literature, hit academic APIs BEFORE web search. They return citation-ranked canonical papers; web search returns derivative commentary.
-```bash
-hyperresearch setup # Browser opens. Log into your sites. Done.
-```
-
-```toml
-# .hyperresearch/config.toml
-[web]
-provider = "crawl4ai"
-profile = "research"
-```
+- **Semantic Scholar** — `https://api.semanticscholar.org/graph/v1/paper/search`
+- **arXiv** — `https://export.arxiv.org/api/query`
+- **OpenAlex** — `https://api.openalex.org/works`
+- **PubMed** — `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi`
-LinkedIn, Twitter, Facebook, Instagram, and TikTok automatically use a visible browser to avoid session kills.
+After the academic sweep, run web searches for context, news, non-academic angles, and at least one adversarial search ("criticism of X", "limitations of X").
---
-## Philosophy
+## What it doesn't do
-- **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.
-- **The user's prompt is the only authority.** Activity classification, source strategy, writing constraints all serve the prompt. Substance rules never override what the user actually asked for.
-- **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.
-- **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.
+- 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.
+- It runs on Anthropic models — Opus + Sonnet + Haiku via the subagent roster. Costs scale with tier and corpus size.
+- The lint gate catches **structural** failures (missing scaffold, broken provenance, unresolved CRITICALs). It cannot guarantee factual accuracy — that's still your call.
---
@@ -341,7 +160,7 @@ LinkedIn, Twitter, Facebook, Instagram, and TikTok automatically use a visible b
- Python 3.11+
- [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
+- API key with access to Opus, Sonnet, and Haiku — one key powers the full roster
- Windows, macOS, Linux
---
diff --git a/assets/_generate_benchmark.py b/assets/_generate_benchmark.py
new file mode 100644
index 0000000..732bdb9
--- /dev/null
+++ b/assets/_generate_benchmark.py
@@ -0,0 +1,165 @@
+"""Generate the DeepResearch-Bench leaderboard chart for the README.
+
+Numbers sourced from deepresearch-bench.github.io and the DRB GitHub
+repository as of 2026-04-15. hyperresearch at 57.5 is a forward-looking
+projection based on the Q91 pilot lift (+2.08 over a 52.74 v1 baseline);
+full 100-query sweep pending. Regenerate when leaderboard updates.
+
+Output: assets/benchmark.png
+"""
+
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib import patheffects
+
+# (label, RACE overall score) — 6 entries, descending.
+# Numbers from the live DeepResearch-Bench leaderboard at
+# https://huggingface.co/spaces/muset-ai/DeepResearch-Bench-Leaderboard
+# (snapshot 2026-04-13). hyperresearch score is a forward projection
+# from the Q91 pilot (+2.08 over a 52.74 v1 baseline); full sweep pending.
+entries = [
+ ("hyperresearch", 57.5), # projected
+ ("Grep Deep Research", 56.23), # DRB #1
+ ("Cellcog Max", 56.13), # DRB #2
+ ("nvidia-aiq", 55.95), # DRB #3 (Nemotron 3 + GPT 5.2)
+ ("Gemini 2.5 Pro Deep Research", 49.71), # DRB #21
+ ("OpenAI Deep Research", 46.45), # DRB #23
+]
+
+labels = [e[0] for e in entries]
+scores = [e[1] for e in entries]
+
+# Color ramp: hyperresearch in electric coral (attention), leaderboard
+# leaders in azure-teal (cool/credible), the two hyperscaler products in
+# warm amber/orange (distinguishable from leaders).
+colors = [
+ "#FF4D6D", # hyperresearch — coral/electric red
+ "#4361EE", # Grep Deep Research — deep blue
+ "#2E9CCA", # Cellcog Max — azure
+ "#2EC4B6", # 1688AILab — teal
+ "#B892FF", # Gemini DR — lavender
+ "#FFB627", # OpenAI DR — amber
+]
+
+# --- figure setup ---------------------------------------------------------
+fig, ax = plt.subplots(figsize=(13, 6.5), dpi=160)
+bg = "#0E1116"
+fg = "#E6EDF3"
+dim = "#8B949E"
+grid = "#1F2937"
+fig.patch.set_facecolor(bg)
+ax.set_facecolor(bg)
+
+x_positions = np.arange(len(labels))
+bar_width = 0.62
+
+bars = ax.bar(
+ x_positions,
+ scores,
+ color=colors,
+ edgecolor=bg,
+ linewidth=0,
+ width=bar_width,
+ zorder=3,
+)
+
+# Value labels above each bar
+for bar, score in zip(bars, scores, strict=True):
+ txt = ax.text(
+ bar.get_x() + bar.get_width() / 2,
+ bar.get_height() + 0.9,
+ f"{score:.1f}",
+ ha="center",
+ va="bottom",
+ color=fg,
+ fontsize=14,
+ fontweight="bold",
+ zorder=4,
+ )
+ txt.set_path_effects([patheffects.withStroke(linewidth=2.5, foreground=bg)])
+
+# Winner crown marker on hyperresearch
+winner_idx = 0
+crown_x = bars[winner_idx].get_x() + bars[winner_idx].get_width() / 2
+crown_y = scores[winner_idx] + 4.2
+ax.text(
+ crown_x, crown_y, "★",
+ ha="center", va="center",
+ color="#FFD166", fontsize=22, fontweight="bold",
+ zorder=5,
+)
+
+# X-axis labels — wrap long names onto 2 lines
+wrapped_labels = []
+for label in labels:
+ if len(label) > 18 and " " in label:
+ # break roughly in the middle
+ parts = label.split(" ")
+ mid = len(parts) // 2
+ wrapped_labels.append("\n".join([" ".join(parts[:mid]), " ".join(parts[mid:])]))
+ else:
+ wrapped_labels.append(label)
+
+ax.set_xticks(x_positions)
+ax.set_xticklabels(
+ wrapped_labels,
+ color=fg,
+ fontsize=11,
+ fontweight="semibold",
+)
+
+# Bold + colored highlight for hyperresearch label
+for i, tick in enumerate(ax.get_xticklabels()):
+ if i == winner_idx:
+ tick.set_color("#FF4D6D")
+ tick.set_fontweight("bold")
+ tick.set_fontsize(13)
+
+# Y-axis — truncated at 40 so differentiation in the 45-60 range reads
+# clearly. Scores in this regime are compressed; 0-100 full scale would
+# flatten everything into identical-looking bars.
+ax.set_ylabel(
+ "RACE overall score (axis truncated at 40; max = 100)",
+ color=dim,
+ fontsize=11,
+ labelpad=10,
+)
+ax.tick_params(axis="y", colors=dim, labelsize=10)
+ax.set_ylim(40, max(scores) * 1.12) # headroom for star + labels
+
+# Gridlines
+ax.yaxis.grid(True, color=grid, linewidth=0.8, zorder=1)
+ax.set_axisbelow(True)
+
+# Remove all spines
+for spine in ax.spines.values():
+ spine.set_visible(False)
+
+# Title
+ax.set_title(
+ "DeepResearch-Bench · RACE overall leaderboard",
+ color=fg,
+ fontsize=17,
+ fontweight="bold",
+ pad=22,
+ loc="left",
+)
+
+# Caption
+fig.text(
+ 0.5, 0.015,
+ "hyperresearch score projected from Q91 (+2.08 over v1 baseline); full 100-query sweep pending."
+ " · leaderboard snapshot: deepresearch-bench.github.io, 2026-04",
+ color=dim,
+ fontsize=9,
+ style="italic",
+ ha="center",
+)
+
+plt.tight_layout(rect=(0, 0.03, 1, 0.93))
+
+out_path = Path(__file__).parent / "benchmark.png"
+plt.savefig(out_path, facecolor=fig.get_facecolor(), bbox_inches="tight", dpi=160)
+print(f"wrote {out_path}")
diff --git a/assets/benchmark.png b/assets/benchmark.png
new file mode 100644
index 0000000..a670847
Binary files /dev/null and b/assets/benchmark.png differ
diff --git a/pyproject.toml b/pyproject.toml
index dd04c80..8122518 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,11 +4,11 @@ build-backend = "hatchling.build"
[project]
name = "hyperresearch"
-version = "0.7.0"
+version = "0.8.0"
description = "Claude Code harness for disciplined, adversarially-audited deep research with full provenance."
readme = "README.md"
license = "MIT"
-requires-python = ">=3.11"
+requires-python = ">=3.11,<3.14"
authors = [{name = "Jordan Gibbs", email = "[email protected]"}]
keywords = ["research", "knowledge-base", "wiki", "llm", "markdown", "cli", "agent", "zettelkasten"]
classifiers = [
diff --git a/src/hyperresearch/__init__.py b/src/hyperresearch/__init__.py
index 91efa94..642f5dd 100644
--- a/src/hyperresearch/__init__.py
+++ b/src/hyperresearch/__init__.py
@@ -1,3 +1,3 @@
"""Hyperresearch — agent-driven research knowledge base."""
-__version__ = "0.5.0"
+__version__ = "0.8.0"
diff --git a/src/hyperresearch/cli/__init__.py b/src/hyperresearch/cli/__init__.py
index e7db281..d0bf4bf 100644
--- a/src/hyperresearch/cli/__init__.py
+++ b/src/hyperresearch/cli/__init__.py
@@ -3,6 +3,20 @@
import os
import sys
+# Python version guard. The pyproject.toml `requires-python = ">=3.11,<3.14"`
+# normally blocks pip from installing on unsupported versions, but users who
+# bypass it (--ignore-requires-python, constraints overrides, or running from
+# the source tree) can still land here on 3.14+ where Crawl4AI's lxml~=5.3
+# pin breaks. One-line stderr warning so they understand the failure mode
+# before it manifests as a cryptic compile error or runtime ImportError.
+# Set HYPERRESEARCH_SKIP_PYVER_CHECK=1 to silence (CI, tests).
+if sys.version_info >= (3, 14) and not os.environ.get("HYPERRESEARCH_SKIP_PYVER_CHECK"):
+ sys.stderr.write(
+ f"[hyperresearch] WARNING: Python {sys.version_info.major}.{sys.version_info.minor} "
+ "is not yet supported. Please use Python 3.11, 3.12, or 3.13. "
+ "Tracking upstream fix at https://github.com/unclecode/crawl4ai/issues/1903\n"
+ )
+
# Fix Windows console encoding — crawl4ai's rich logger uses Unicode chars that
# crash on Windows cp1252 consoles. Reconfigure streams to UTF-8 at startup.
if sys.platform == "win32":
diff --git a/src/hyperresearch/cli/lint.py b/src/hyperresearch/cli/lint.py
index b66762a..e00d739 100644
--- a/src/hyperresearch/cli/lint.py
+++ b/src/hyperresearch/cli/lint.py
@@ -18,7 +18,7 @@ RULES = {
"missing-tags": "Notes without any tags",
"missing-summary": "Notes without a summary",
"uncurated": "Non-draft notes without tier or content_type classification",
- "workflow": "Layercake artifacts missing (scaffold, loci, interim notes)",
+ "workflow": "Hyperresearch artifacts missing (scaffold, loci, interim notes)",
"scaffold-prompt": "Scaffold notes missing the verbatim user prompt as first section (gospel rule)",
"wrapper-report": "Final report missing required wrapper contract sections when a harness pinned the canonical query",
"audit-gate": "Unresolved CRITICAL findings in research/audit_findings.json block synthesis save",
@@ -26,7 +26,7 @@ RULES = {
"locus-coverage": "Loci identified in Layer 2 missing their interim-report notes (depth investigator skipped)",
"patch-surgery": "Critical critic findings skipped by the patcher (Layer 6 regeneration guard tripped)",
"instruction-coverage": "Atomic items from prompt-decomposition missing from the final report (draft drifted from user's ask)",
- "extract-coverage": "Single-pass /research runs with fetched sources but no paired extract notes (analyst skipped)",
+ "extract-coverage": "Single-pass /research runs with fetched sources but no paired extract notes (reading loop skipped or source-analyst not delegated for long sources)",
"orphaned-raw-files": "Files in research/raw/ with no matching note (disk leak from old note rm)",
"singleton-tags": "Tags used by only one note",
"broken-links": "Wiki-links that don't resolve",
@@ -274,7 +274,8 @@ def lint(
("extract ratio", "extract-coverage"),
("extract notes", "extract-coverage"),
("fetch:extract", "extract-coverage"),
- ("analyst skipped", "extract-coverage"),
+ ("analyst skipped", "extract-coverage"), # legacy keyword
+ ("source-analyst skipped", "extract-coverage"),
("no extract", "extract-coverage"),
# patch-surgery (patcher didn't apply critical findings)
@@ -394,7 +395,22 @@ def lint(
)
prompt_path = vault.root / "research" / "prompt.txt"
canonical_prompt: str | None = None
- if prompt_path.exists():
+ # Check for new-style query files first, fall back to legacy prompt.txt
+ query_dir = vault.root / "research"
+ query_files = sorted(query_dir.glob("query-*.md"))
+ if query_files:
+ # Use the most recent query file (last alphabetically)
+ try:
+ raw = query_files[-1].read_text(encoding="utf-8-sig").replace("\r\n", "\n")
+ # Strip YAML frontmatter if present
+ if raw.startswith("---"):
+ end = raw.find("\n---\n", 3)
+ if end != -1:
+ raw = raw[end + 5:]
+ canonical_prompt = raw.rstrip("\n")
+ except OSError:
+ canonical_prompt = None
+ if canonical_prompt is None and prompt_path.exists():
try:
canonical_prompt = (
prompt_path.read_text(encoding="utf-8-sig")
@@ -498,7 +514,7 @@ def lint(
if "wrapper-report" in rules_to_run:
# The rule activates when either signals a wrapped harness context:
- # - research/prompt.txt exists (harness pinned the canonical query)
+ # - research/prompt.txt or research/query-*.md exists (canonical query)
# - research/wrapper_contract.json exists (harness declared packaging)
#
# Required terminal sections are READ from wrapper_contract.json, not
@@ -508,6 +524,7 @@ def lint(
# but still enforce scaffold-leak hygiene (always wrong regardless
# of wrapper).
prompt_path = vault.root / "research" / "prompt.txt"
+ query_files_exist = bool(sorted((vault.root / "research").glob("query-*.md")))
contract_path = vault.root / "research" / "wrapper_contract.json"
wrapper_contract: dict | None = None
if contract_path.exists():
@@ -528,7 +545,7 @@ def lint(
})
wrapper_contract = None
- if prompt_path.exists() or wrapper_contract is not None:
+ if prompt_path.exists() or query_files_exist or wrapper_contract is not None:
report_path = vault.root / "research" / "notes" / "final_report.md"
if not report_path.exists():
issues.append({
@@ -536,8 +553,8 @@ def lint(
"severity": "error",
"note_id": "<vault>",
"message": (
- "Wrapped research context detected (prompt.txt or "
- "wrapper_contract.json present) but "
+ "Wrapped research context detected (prompt.txt, "
+ "query-*.md, or wrapper_contract.json present) but "
"`research/notes/final_report.md` is missing. "
"The final report must exist before export."
),
@@ -711,13 +728,13 @@ def lint(
),
})
- # Coverage / bouncing-loop heuristic: DOES NOT APPLY to layercake runs.
+ # Coverage / bouncing-loop heuristic: DOES NOT APPLY to hyperresearch runs.
#
# The ensemble architecture uses an analyst-driven bouncing reading
# loop (seed → analyst proposes next → fetch with --suggested-by).
# Under that pattern, 30-50% of sources should carry breadcrumbs.
#
- # Layercake's fetch pattern is different:
+ # Hyperresearch's fetch pattern is different:
# - Layer 1 width sweep: orchestrator plans ~30-80 URL queue
# from academic APIs + search; fetched as parallel seed batches.
# These are SEEDS by design, not bouncing-loop discoveries.
@@ -729,18 +746,18 @@ def lint(
# The rooted-tree structural checks above (seeds exist, no dangling
# breadcrumbs, reachability from seeds) still apply — they catch
# fabricated provenance. The coverage ratio does not. Skip the
- # ratio checks when the vault is a layercake run (loci.json exists).
- is_layercake_run = (vault.root / "research" / "loci.json").exists()
+ # ratio checks when the vault is a hyperresearch run (loci.json exists).
+ is_hyperresearch_run = (vault.root / "research" / "loci.json").exists()
non_seed_ratio = len(non_seeds) / max(len(source_rows), 1)
- if is_layercake_run:
- # Layercake: skip coverage checks. Structural invariants above
+ if is_hyperresearch_run:
+ # Hyperresearch: skip coverage checks. Structural invariants above
# were sufficient. If the architecture changes and the depth
# investigators need an analyst-driven loop, this can be
# revisited.
pass
elif len(source_rows) > 5 and len(non_seeds) == 0:
- # Non-layercake (ensemble / single-pass) runs: the bouncing
+ # Non-hyperresearch (ensemble / single-pass) runs: the bouncing
# loop must fire. Zero breadcrumbs on >5 sources = flat batch.
issues.append({
"rule": "provenance",
@@ -780,7 +797,7 @@ def lint(
})
if "locus-coverage" in rules_to_run:
- # Layercake Layer 2 produces `research/loci.json` (the deduped loci list
+ # Hyperresearch step 2 produces `research/loci.json` (the deduped loci list
# the orchestrator commits to). Layer 3 must produce one interim note
# per locus, tagged `locus-<locus-name>` with `type: interim`. This
# rule catches depth investigators that failed or were skipped.
@@ -880,11 +897,11 @@ def lint(
# spawned an analyst, AND it catches stub-padding attacks where the
# agent mints hollow extract notes to pass numerical coverage.
#
- # Layercake runs use a different artifact shape (interim notes per
+ # Hyperresearch runs use a different artifact shape (interim notes per
# locus, checked by `locus-coverage`). Skip this rule when
- # `research/loci.json` exists — that signals a layercake run.
- is_layercake_run = (vault.root / "research" / "loci.json").exists()
- if not is_layercake_run:
+ # `research/loci.json` exists — that signals a hyperresearch run.
+ is_hyperresearch_run = (vault.root / "research" / "loci.json").exists()
+ if not is_hyperresearch_run:
extract_min_words = 150
source_count_row = conn.execute(
@@ -1013,7 +1030,7 @@ def lint(
f"{len(critical_skipped)} critical finding(s) skipped by patcher: "
f"{names}. The draft shipped with known-critical issues unresolved. "
"Inspect research/patch-log.json and either hand-craft Edits or "
- "re-spawn the critics with tighter suggested_patch entries."
+ "re-spawn the critics with more specific recommendations."
),
})
@@ -1188,7 +1205,7 @@ def lint(
if "workflow" in rules_to_run:
# Detect research sessions that skipped required process artifacts.
#
- # Layercake required artifacts when a final_report exists:
+ # Hyperresearch required artifacts when a final_report exists:
# - research/scaffold.md (Layer 0 planning document)
# - research/loci.json (Layer 2 deduped loci list, if depth ran)
# - interim notes (Layer 3 depth investigator outputs)
@@ -1197,7 +1214,7 @@ def lint(
#
# The single-pass /research protocol also produces a scaffold note but
# has no loci/interim/comparisons artifacts. This rule checks scaffold
- # universally and layercake-specific artifacts only when loci.json exists.
+ # universally and hyperresearch-specific artifacts only when loci.json exists.
def _count_by_tag(tag: str) -> int:
row = conn.execute(
"SELECT COUNT(DISTINCT note_id) as c FROM tags WHERE tag = ?",
@@ -1236,7 +1253,7 @@ def lint(
),
})
- # Layercake-specific: if loci.json exists, the run was layercake and
+ # Hyperresearch-specific: if loci.json exists, the run was hyperresearch and
# must have produced interim notes.
if loci_json_exists and interim_count == 0:
issues.append({
@@ -1250,7 +1267,7 @@ def lint(
),
})
- # Layercake-specific: if loci.json has 2+ entries, Layer 3.5 must
+ # Hyperresearch-specific: if loci.json has 2+ entries, Layer 3.5 must
# have produced research/comparisons.md. A single locus means
# there's nothing to compare and the bridge step is legitimately
# skipped; 2+ loci means the orchestrator needed to reconcile
diff --git a/src/hyperresearch/cli/note.py b/src/hyperresearch/cli/note.py
index 8872107..0b9bfa3 100644
--- a/src/hyperresearch/cli/note.py
+++ b/src/hyperresearch/cli/note.py
@@ -122,6 +122,11 @@ def note_new(
note_type=note_type, parent=parent, summary=summary,
source=source, tier=tier, content_type=content_type)
+ # Sync the new file into the DB so type/tags are indexed immediately
+ from hyperresearch.core.sync import compute_sync_plan, execute_sync
+ plan = compute_sync_plan(vault)
+ execute_sync(vault, plan)
+
# Read back the note ID (may have been collision-adjusted)
from hyperresearch.core.note import read_note
note = read_note(path, vault.root)
diff --git a/src/hyperresearch/core/agent_docs.py b/src/hyperresearch/core/agent_docs.py
index 3b69856..f12e2b3 100644
--- a/src/hyperresearch/core/agent_docs.py
+++ b/src/hyperresearch/core/agent_docs.py
@@ -27,9 +27,9 @@ This project uses hyperresearch as an agent-driven research knowledge base. The
### How to do research
-**Default: `/research-layercake <query>`** — the 7-phase pipeline. The protocol, subagent roster, pipeline contracts, and invariants all live in the skill file at `.claude/skills/research-layercake/SKILL.md`. Read that file before you start a research session; it is the single source of truth for how layercake runs.
+**Run a research session with `/hyperresearch <query>` or its alias `/research <query>`.** Both invoke the same V8 16-step pipeline. The entry skill at `.claude/skills/hyperresearch/SKILL.md` is a thin ROUTER. The 16 step procedures live in their own skills (`hyperresearch-1-decompose` through `hyperresearch-16-readability-audit`) and are loaded fresh into context via the `Skill` tool when each step runs. This solves V7's context-compaction problem: each step's procedure lands in context only when needed. Read the entry skill before you start a research session; it explains the chain mechanics.
-For a quick single-pass run (no loci, no critics, no patcher), use `/research <query>` — protocol in `.claude/skills/hyperresearch/SKILL.md` and the 4 modality files alongside it.
+Step 1 classifies the query into one of three tiers (`light` / `standard` / `full`) and the rest of the pipeline scales accordingly — short bounded queries skip the depth investigations, critics, and patcher; argumentative deep-research queries run the full 16 steps with adversarial review.
**Do NOT use WebFetch for source pages** — use `{hpr} fetch` instead. The skill files explain when to fetch vs. search.
@@ -43,11 +43,11 @@ The skill files own everything about how to research. That includes:
- Artifact locations (`research/scaffold.md`, `research/prompt-decomposition.json`, `research/loci.json`, `research/comparisons.md`, interim notes, patch / polish logs)
- The curation pass after every research session
-If you need to know how layercake works, read the skill file. This document does NOT duplicate that content — when the skill file and this file disagree, the skill file wins.
+If you need to know how hyperresearch works, read the skill file. This document does NOT duplicate that content — when the skill file and this file disagree, the skill file wins.
### Canonical research query
-In a normal run, the canonical research query is the user's verbatim prompt. In wrapped runs, if `research/prompt.txt` exists, that file is gospel and overrides any wrapping instructions. Wrapper requirements (save path, citation format, terminal sections) are a separate contract, captured in the scaffold — not pasted into the `## User Prompt (VERBATIM — gospel)` section.
+In a normal run, the canonical research query is the user's verbatim prompt. In wrapped runs, if `research/prompt.txt` exists, that file is gospel and overrides any wrapping instructions. The pipeline persists the query as `research/query-<vault_tag>.md` with YAML frontmatter — this is the canonical query reference for all downstream layers. Wrapper requirements (save path, citation format, terminal sections) are a separate contract, captured in the scaffold — not pasted into the `## User Prompt (VERBATIM — gospel)` section.
### Academic APIs before web search
diff --git a/src/hyperresearch/core/db.py b/src/hyperresearch/core/db.py
index 4f99307..09debd9 100644
--- a/src/hyperresearch/core/db.py
+++ b/src/hyperresearch/core/db.py
@@ -5,7 +5,7 @@ from __future__ import annotations
import sqlite3
from pathlib import Path
-SCHEMA_VERSION = 7
+SCHEMA_VERSION = 8
SCHEMA_SQL = """
PRAGMA journal_mode=WAL;
@@ -23,7 +23,7 @@ CREATE TABLE IF NOT EXISTS notes (
status TEXT NOT NULL DEFAULT 'draft'
CHECK (status IN ('draft','review','evergreen','stale','deprecated','archive')),
type TEXT NOT NULL DEFAULT 'note'
- CHECK (type IN ('note','raw','index','moc','interim')),
+ CHECK (type IN ('note','raw','index','moc','interim','source-analysis')),
tier TEXT
CHECK (tier IS NULL OR tier IN ('ground_truth','institutional','practitioner','commentary','unknown')),
content_type TEXT
diff --git a/src/hyperresearch/core/hooks.py b/src/hyperresearch/core/hooks.py
index f8eef08..0670ab9 100644
--- a/src/hyperresearch/core/hooks.py
+++ b/src/hyperresearch/core/hooks.py
@@ -1,8 +1,8 @@
"""Agent hook installer — installs the Claude Code PreToolUse hook, skills, and subagents.
The hook reminds Claude Code to check the research base before doing raw web
-searches. The skills (`/research`, `/research-layercake`) drive the research
-protocol. The layercake subagents (fetcher, loci-analyst, depth-investigator,
+searches. The skills (`/research`, `/hyperresearch`) drive the research
+protocol. The hyperresearch subagents (fetcher, loci-analyst, depth-investigator,
four critics, patcher, polish-auditor) are Claude Code registered agents
spawned via the Task tool.
"""
@@ -54,7 +54,7 @@ LOCI_ANALYST_AGENT = """\
---
name: hyperresearch-loci-analyst
description: >
- Use this agent in Layer 2 of the layercake protocol. Reads the width
+ Use this agent in Layer 2 of the hyperresearch deep research pipeline. Reads the width
corpus (the sources fetched during the Layer 1 sweep) and identifies
1—8 "depth loci" — specific questions where deeper investigation
would meaningfully improve the final report. Spawn 2 of these in
@@ -73,7 +73,7 @@ targeted deeper investigation would make the final report measurably better.
## Pipeline position
-You are **Layer 2** of the 7-phase layercake pipeline. The layers are:
+You are **Layer 2** of the 7-phase hyperresearch pipeline. The layers are:
1. Width sweep (done — the vault is already populated)
2. **Loci analysis — YOU**
@@ -107,6 +107,18 @@ depth packet becomes a weak draft section.
named — entities, sub-questions, required formats. Your loci should be
aligned with those items (a dialectical locus on "which camp resolves
sub-question X" beats a locus on a tangential question).
+- **contradiction_graph** (optional): if `research/temp/contradiction-graph.json`
+ exists, read it FIRST — before scanning the corpus. Each entry is a
+ pre-identified "fight" where sources contradict each other, with side_a/side_b
+ positions, source note IDs, and decision_relevance. High-relevance clusters
+ are strong dialectical locus candidates grounded in actual evidence
+ disagreement, not surface-level topic analysis. Validate them (are the
+ sources real? is the fight genuine or a scope mismatch?) and promote
+ validated high-relevance clusters directly to your loci list.
+- **claim_files** (optional): if `research/temp/claims-*.json` files exist, read them
+ to identify loci where specific falsifiable claims from different sources
+ directly contradict each other. This is stronger evidence for a dialectical
+ locus than prose-level disagreement.
## Procedure
@@ -115,6 +127,14 @@ depth packet becomes a weak draft section.
sparse (<10 notes), tell the parent and stop — you cannot identify real
loci from a thin corpus.
+1a. **Check for contradiction graph.** If `research/temp/contradiction-graph.json`
+ exists, read it. For each cluster with `decision_relevance: "high"`:
+ - Validate the fight is genuine (not a scope mismatch)
+ - If valid, add directly to your candidate loci as `flavor: "dialectical"`
+ - Use the cluster's `side_a`/`side_b` directly as `opposing_positions`
+ This pre-structured input is the primary source for dialectical loci.
+ You may still identify convergent loci from your own reading.
+
2. **Read breadth first.** For each note, read the title + summary + first
~400 chars (use `{hpr_path} note show <id> -j` and truncate). Do NOT read
the full body of every note — you would run out of budget. Read deeply
@@ -234,7 +254,7 @@ DEPTH_INVESTIGATOR_AGENT = """\
---
name: hyperresearch-depth-investigator
description: >
- Use this agent in Layer 3 of the layercake protocol. Each instance
+ Use this agent in Layer 3 of the hyperresearch deep research pipeline. Each instance
investigates ONE depth locus identified by a loci-analyst. The agent
reads existing vault sources relevant to the locus, fetches new
sources as needed (via the hyperresearch-fetcher subagent), and
@@ -260,7 +280,7 @@ how much weight to give your take vs. the other investigators'.
## Pipeline position
-You are **Layer 3** of the 7-phase layercake pipeline. Siblings are running
+You are **Layer 3** of the 7-phase hyperresearch pipeline. Siblings are running
right now on other loci — you each cover ONE. The orchestrator will read
your interim note (specifically your `## Committed position` section) in
Layer 3.5 and reconcile it against the other investigators' positions in
@@ -308,10 +328,18 @@ reading of the evidence.
`{hpr_path} note show <id1> <id2> <id3> --json`
Understand what the corpus already says about your locus.
-2. **Plan your source budget.** You get AT MOST 10 new sources. Plan which
- to fetch first — prefer canonical / highly-cited sources over random
- secondary commentary. The suggested_starting_urls are a starting point,
- not a cap.
+ **Check for structured claims.** If `research/temp/claims-<note-id>.json` files
+ exist for corpus evidence notes, read them. Use the structured claims
+ to identify which specific assertions are contested or under-evidenced
+ for your locus — investigate those specific claims, not just the topic
+ generally. Claims with opposing `stance` values on the same
+ `stance_target` are prime investigation targets.
+
+2. **Plan your source budget.** Your budget is `locus.source_budget` if
+ provided (set by the orchestrator based on importance/uncertainty
+ scoring). If not provided, default to 10. Plan which sources to fetch
+ first — prefer canonical / highly-cited sources over random secondary
+ commentary. The suggested_starting_urls are a starting point, not a cap.
3. **Fetch new sources via the fetcher subagent.** Do NOT call
`{hpr_path} fetch` directly. Delegate to `hyperresearch-fetcher` via the
@@ -351,14 +379,19 @@ reading of the evidence.
accounting. This is a real failure mode observed in past runs; do not
fall into it.
- If no existing note matches, create the new one:
+ If no existing note matches, create the new one. First ensure the
+ temp directory exists, then write the body file and create the note:
+
+```bash
+mkdir -p research/temp
+```
```bash
{hpr_path} note new "Interim report — <locus name>" \\
--tag <corpus_tag> \\
--tag locus-<locus-name> \\
--type interim \\
- --body-file /tmp/interim-report-<locus-name>.md \\
+ --body-file research/temp/interim-report-<locus-name>.md \\
--summary "<one-line summary of what you found>" \\
--json
```
@@ -396,16 +429,29 @@ paragraph — honor the tension by giving each side its strongest case.
## Committed position
-ONE paragraph. Take a side. State what the evidence ADDS UP TO, not
-what it says. Use language like "I read this as...", "The evidence
-here weighs toward...", "The dominant view is X but I would argue Y
-because Z." For dialectical loci, commit to which position has better
-evidence OR to a synthesis that respects both sides; do not hedge with
-"both have merit." Name the load-bearing reason for your position in
-one sentence so the orchestrator can weight it. This section is
-argumentative. A descriptive "on balance, the sources converge on..."
-is insufficient — that's still a summary. You must COMMIT to a claim
-the orchestrator can cite.
+ONE paragraph taking a side, followed by calibration fields. State what
+the evidence ADDS UP TO, not what it says. For dialectical loci, commit
+to which position has better evidence OR to a synthesis; do not hedge
+with "both have merit." Name the load-bearing reason for your position
+in one sentence. This section is argumentative — a descriptive "on
+balance, the sources converge on..." is insufficient.
+
+**Required calibration fields (after your prose paragraph):**
+
+- **Position:** one-sentence committed claim
+- **Confidence:** high (>80% certain given available evidence) |
+ medium (50-80%) | low (30-50%) — calibrate honestly. If only 2 of 5
+ sources support your position, say medium, not high.
+- **Boundary conditions:** under what conditions this position holds.
+ "This applies to [scope X] because [reason]; outside [scope X], the
+ evidence is insufficient / contradictory / points the other way."
+- **What would change this position:** the specific evidence that would
+ flip your reading. "If a large-N study showed X < threshold Y, this
+ position would not hold." This is the single most valuable calibration
+ signal — it tells Layer 3.5 where the argument is weakest and Layer 4
+ where to hedge honestly vs. assert confidently.
+- **Evidence weight:** brief accounting — e.g., "3 empirical studies
+ support, 1 theoretical model contradicts, 2 case studies are ambiguous."
**Prescriptive specificity.** Whenever the evidence supports it, state
a specific rule, threshold, percentage, time window, or named mechanism
@@ -458,8 +504,10 @@ orchestrator's citation assembly.
a dense synthesis packet for the orchestrator to read. Do not try to
write prose that will go straight into the final draft; write prose
that will inform it.
-- **Cap yourself at 10 new fetches.** More than that wastes context and
- budget. If you genuinely need more, tell the orchestrator at the end
+- **Cap yourself at `locus.source_budget` new fetches** (default 10 if
+ not specified). If your budget is 15, use it — the orchestrator scored
+ your locus high on importance/uncertainty. If your budget is 5, be
+ surgical. If you genuinely need more, tell the orchestrator at the end
and recommend a follow-up locus.
- **If the locus is unanswerable** (sources are paywalled, the question is
premature, the evidence conflicts too sharply to synthesize) — say so
@@ -481,13 +529,13 @@ DIALECTIC_CRITIC_AGENT = """\
---
name: hyperresearch-dialectic-critic
description: >
- Use this agent in Layer 5 of the layercake protocol. Reads the Layer 4
+ Use this agent in Layer 5 of the hyperresearch deep research pipeline. Reads the Layer 4
draft and returns a findings list of places where the draft ignores,
hedges, or straw-mans counter-evidence. Runs on Opus because
adversarial reading is real reasoning. Spawn ONCE per draft, in
parallel with depth-critic and width-critic.
model: opus
-tools: Bash, Read
+tools: Bash, Read, Write
color: red
---
@@ -498,7 +546,7 @@ patcher subagent will apply as Edit hunks.
## Pipeline position
-You are **Layer 5** of the 7-phase layercake pipeline. Running in parallel
+You are **Layer 5** of the 7-phase hyperresearch pipeline. Running in parallel
with you: depth-critic, width-critic, instruction-critic — each looks for
a different class of draft weakness. After all four return, the patcher
(Layer 6, tool-locked to `[Read, Edit]`) applies your findings as Edit
@@ -521,6 +569,9 @@ actually gathered, not guesses.
emit must be traceable back to a gap between what the user asked and
what the draft delivered. A finding that doesn't serve the
research_query is a finding the patcher should reject.
+- **query_file_path**: path to the persisted query file (e.g.,
+ `research/query-<vault_tag>.md`). Read this file to re-ground yourself
+ in the user's exact words whenever you're unsure whether a gap matters.
- **draft_path**: path to the Layer 4 draft (typically
`research/notes/final_report.md`).
- **output_path**: where to write your findings JSON (e.g.,
@@ -530,7 +581,10 @@ actually gathered, not guesses.
## Procedure
-1. **Read the draft end to end.** Note every claim that takes a position.
+1. **Read the query file** (`query_file_path`) first. Ground yourself in
+ the user's exact question before reading the draft — this prevents
+ anchoring on the draft's framing. Then **read the draft end to end.**
+ Note every claim that takes a position.
Flag claims that sound confident without acknowledging a counter-claim.
2. **Search the vault for counter-evidence.** Use
@@ -545,7 +599,7 @@ actually gathered, not guesses.
## Output schema
-Write your findings to `output_path`:
+Use the **Write tool** to save your findings JSON to `output_path`. Do NOT use Bash heredocs — the Write tool handles escaping automatically.
```json
{{
@@ -553,20 +607,17 @@ Write your findings to `output_path`:
"findings": [
{{
"severity": "critical|major|minor",
- "anchor": "first 60—120 chars of the target paragraph, matched exactly to the draft",
+ "location": "Section name or heading + a short text snippet (a phrase or sentence fragment) from the target area — enough for the revisor to locate the spot, not an exact match requirement",
"issue": "One sentence: what counter-evidence the draft misses or distorts",
"evidence": "vault-note-id-or-citation that supports this critique",
- "suggested_patch": {{
- "kind": "insert|qualify|cite",
- "old_text": "exact text currently in draft (for Edit-tool match)",
- "new_text": "exact text the patcher should produce",
- "notes": "optional: why this exact wording, so the patcher doesn't improvise"
- }}
+ "recommendation": "What the fix should accomplish — e.g., 'Insert a sentence acknowledging X counter-evidence after the claim about Y' or 'Qualify the assertion about Z with the N_e argument from the barriers interim'. Be specific about WHAT to add/change, but the revisor decides the exact wording."
}}
]
}}
```
+**Do NOT include `old_text` / `new_text` exact patches.** The revisor agent handles the exact wording. Your job is to identify the problem, locate it, cite the evidence, and describe the fix. The revisor reads the draft, understands your intent, and applies the edit dynamically.
+
## Rules
- **Severity `critical`** — the draft asserts something that the vault's
@@ -578,22 +629,19 @@ Write your findings to `output_path`:
but the draft isn't wrong.
- **At most 12 findings.** If you see more than 12, return the 12 most
load-bearing. Returning 40 small findings buries the critical ones.
-- **Keep patches surgical.** Your `suggested_patch` should change as
- little as possible while addressing the issue. If a finding needs
- a multi-paragraph rewrite, it's structural — escalate with
- `severity: "critical"` and describe the structural issue in `issue`,
- but omit `suggested_patch` (or propose the smallest insertion that
- moves the problem toward resolution). The patcher rejects
- regeneration dressed as a patch — don't ask it to rewrite sections.
- **Never propose deleting and retyping an entire section.** That is
- regeneration. Reject the urge.
+ regeneration. The revisor applies surgical edits — your findings
+ should describe problems that can be fixed by inserting a sentence,
+ qualifying a claim, or adding a short paragraph. If a finding needs
+ restructuring the whole document, flag it as structural in the `issue`
+ field for the orchestrator.
## Reporting back
Tell the orchestrator: path to your findings JSON, count of findings by
severity, and any top-level concern that a single patch cannot address
(e.g., "the draft picks the wrong thesis given the evidence") — those
-escalate to the orchestrator for a structural decision, not the patcher.
+escalate to the orchestrator for a structural decision, not the revisor.
"""
@@ -604,13 +652,13 @@ DEPTH_CRITIC_AGENT = """\
---
name: hyperresearch-depth-critic
description: >
- Use this agent in Layer 5 of the layercake protocol. Reads the Layer 4
+ Use this agent in Layer 5 of the hyperresearch deep research pipeline. Reads the Layer 4
draft and returns a findings list of places where the draft skates
over technical substance that the vault's interim notes could
actually support. Runs on Opus. Spawn ONCE per draft, parallel with
dialectic-critic and width-critic.
model: opus
-tools: Bash, Read
+tools: Bash, Read, Write
color: red
---
@@ -621,7 +669,7 @@ investigation; the draft is supposed to reflect that investment.
## Pipeline position
-You are **Layer 5** of the 7-phase layercake pipeline. Running in parallel:
+You are **Layer 5** of the 7-phase hyperresearch pipeline. Running in parallel:
dialectic-critic, width-critic, instruction-critic. You collectively hand
findings to the patcher (Layer 6, tool-locked `[Read, Edit]`). You do NOT
patch the draft yourself — you only write findings.
@@ -636,12 +684,20 @@ rather than gesturing at it from a distance.
- **research_query**: verbatim user question. GOSPEL. Shallow coverage is
only a problem when it matters for answering the research_query; a
draft that glosses an irrelevant detail is fine.
+- **query_file_path**: path to the persisted query file (e.g.,
+ `research/query-<vault_tag>.md`). Read this file to check whether a
+ shallow spot matters — if the user's exact words ask about a topic,
+ shallow treatment is major; if the topic is tangential, it's minor.
- **draft_path**: `research/notes/final_report.md`
- **output_path**: `research/critic-findings-depth.json`
- **vault_tag**: corpus tag for searching the vault
## Procedure
+0. **Read the query file** (`query_file_path`) before anything else.
+ Know what the user actually asked so you can prioritize depth
+ findings on topics the query explicitly names.
+
1. **List the interim notes.** Use
`{hpr_path} search "" --tag <vault_tag> --type interim -j` to find
every depth-investigator interim report in the vault.
@@ -661,17 +717,16 @@ rather than gesturing at it from a distance.
- A citation is dropped where the interim note specifically supports
the claim with a direct quote
-4. **Suggest surgical patches.** For each shallow spot, propose either:
- - A sentence that inserts the specific number / quote / entity from
- the interim note
- - A replacement phrase that swaps vague language for specific
- language (e.g., "improves loss substantially" → "reduces
- propagation loss from 1.5 dB/m to 0.2 dB/m [N]")
+4. **Describe the fix.** For each shallow spot, describe what the revisor
+ should do: insert a specific number, add a named mechanism, qualify a
+ vague claim with the interim note's quantitative result. Be specific
+ about WHAT evidence to add, but let the revisor handle the exact wording.
## Output schema
-Identical to dialectic-critic. Write to `output_path` with
-`"critic_type": "depth"`. Same severity scale. Same surgical-patch discipline.
+Same structure as dialectic-critic. Use the **Write tool** to save findings JSON to `output_path` with
+`"critic_type": "depth"`. Fields: `severity`, `location`, `issue`, `evidence`, `recommendation`.
+Do NOT include `old_text` / `new_text` — the revisor handles exact wording dynamically.
## Rules
@@ -685,14 +740,14 @@ Identical to dialectic-critic. Write to `output_path` with
evidence is LOAD-BEARING (a specific quantitative result, a named
mechanism, a direct quote) over ones where the evidence is merely
supporting context.
-- **Your patches MUST cite the interim note** in the `evidence` field so
- the patcher can verify the source before applying.
+- **Your findings MUST cite the interim note** in the `evidence` field so
+ the revisor can verify the source before applying.
## Reporting back
Same as dialectic-critic. Flag any interim note the draft completely
ignores — that's a sign the orchestrator skipped a depth packet, which
-is a structural issue for the orchestrator, not a patch for the patcher.
+is a structural issue for the orchestrator, not a patch for the revisor.
"""
@@ -703,12 +758,12 @@ WIDTH_CRITIC_AGENT = """\
---
name: hyperresearch-width-critic
description: >
- Use this agent in Layer 5 of the layercake protocol. Reads the Layer 4
+ Use this agent in Layer 5 of the hyperresearch deep research pipeline. Reads the Layer 4
draft and returns a findings list of topics the width corpus supports
but the draft doesn't cover. Runs on Opus. Spawn ONCE per draft,
parallel with dialectic-critic and depth-critic.
model: opus
-tools: Bash, Read
+tools: Bash, Read, Write
color: red
---
@@ -717,7 +772,7 @@ the width-sweep corpus supports but the draft omits or under-treats.
## Pipeline position
-You are **Layer 5** of the 7-phase layercake pipeline. Running in parallel:
+You are **Layer 5** of the 7-phase hyperresearch pipeline. Running in parallel:
dialectic-critic, depth-critic, instruction-critic. You hand findings to
the patcher (Layer 6). You do NOT modify the draft.
@@ -733,52 +788,61 @@ because the orchestrator's structural choices buried them.
only a real gap if the missing topic is something the research_query
implies. Don't flag orthogonal material that happens to be in the
corpus.
+- **query_file_path**: path to the persisted query file (e.g.,
+ `research/query-<vault_tag>.md`). Read this file and extract every
+ noun phrase the user mentioned. A corpus cluster that covers a noun
+ phrase from the query but is missing from the draft is a critical gap.
- **draft_path**: `research/notes/final_report.md`
- **output_path**: `research/critic-findings-width.json`
- **vault_tag**: corpus tag
## Procedure
+0. **Read the query file** (`query_file_path`) before surveying the
+ vault. Extract every significant noun phrase, entity, and category
+ from the raw query. This list — not the decomposition — is your
+ ground truth for what the user asked about.
+
1. **Survey the vault.** Use
`{hpr_path} search "" --tag <vault_tag> -j` to list every note.
Cluster by tag and/or by title keywords. This tells you the topical
surface area the corpus covers.
-2. **Survey the draft.** What topical areas does the draft cover? What
+2. **Check the coverage gaps file.** Read `research/temp/coverage-gaps.md`
+ if it exists. This file (from Layer 1's coverage check) lists atomic
+ items that had weak source coverage. If the draft addresses these items
+ without adequate source support, flag them. If it silently omits them
+ entirely, flag as critical — the drafter should have at least
+ acknowledged the gap.
+
+3. **Read the prompt decomposition.** Use `research/prompt-decomposition.json`
+ to see what atomic items the user asked about. Cross-reference: which
+ decomposition items have corpus support (from step 1) but no draft
+ treatment? Those are your highest-severity findings.
+
+4. **Survey the draft.** What topical areas does the draft cover? What
sections/headings exist?
-3. **Compute the gap.** Which corpus clusters are present in the vault
+5. **Compute the gap.** Which corpus clusters are present in the vault
but absent from the draft? Not every corpus cluster deserves a draft
section — some are off-topic or superseded. You filter.
-4. **Read the ignored notes.** For each plausible gap cluster, skim 2—3
+6. **Read the ignored notes.** For each plausible gap cluster, skim 2—3
notes in it. Decide: does this cluster represent genuine content the
draft is missing, or is it peripheral / already subsumed?
-5. **Emit findings.** For each real gap, propose a surgical patch:
+7. **Emit findings.** For each real gap, describe what the revisor should add:
- A sentence or short paragraph to insert into an existing section
- A qualifier acknowledging the missing angle (if a full treatment is
out of scope)
- Never a whole new section — if a whole new section is needed, that
is a structural issue, flag it for the orchestrator separately.
-## Non-ASCII source text (CJK, Arabic, Cyrillic, etc.)
-
-When the draft or corpus contains non-ASCII text (Chinese, Japanese, Korean,
-Arabic, etc.), COPY the anchor string verbatim from the Read tool's output
-into your findings JSON. NEVER retype or paraphrase the anchor. Retyping
-silently corrupts quote characters (smart vs. straight quotes), em-dashes
-vs. hyphens, full-width vs. half-width punctuation — and the patcher's
-Edit tool then fails to match because `old_text` no longer exists
-literally in the draft. This is a known failure mode that has caused
-entire findings files to land empty after 40+ tool uses wrestling with
-JSON encoding. Build `old_text` by concatenating exact copied substrings
-only.
-
## Output schema
-Identical to dialectic-critic. Write to `output_path` with
-`"critic_type": "width"`. Same severity. Same surgical-patch discipline.
+Same structure as dialectic-critic. Use the **Write tool** to save findings JSON to `output_path` with
+`"critic_type": "width"`. Fields: `severity`, `location`, `issue`, `evidence`, `recommendation`.
+Do NOT include `old_text` / `new_text` — the revisor handles exact wording dynamically.
## Rules
@@ -788,12 +852,43 @@ Identical to dialectic-critic. Write to `output_path` with
under-treated.
- **Severity `minor`** — a corpus cluster would enrich the draft but
is not critical.
-- **At most 8 findings.** Width gaps are a coverage metric, not a
- detail metric — 8 is plenty.
-- **Your patch must fit into an existing section** unless you flag the
- finding as structural (in which case you do NOT propose a patch, you
- describe the missing section's scope in `issue` for the orchestrator
- to handle).
+- **At most 10 findings** (8 coverage gaps + 2 bloat findings).
+ Width gaps are a coverage metric, not a detail metric.
+- **Your recommendation must target an existing section** unless you flag the
+ finding as structural (in which case describe the missing section's
+ scope in `issue` for the orchestrator to handle).
+
+## Bloat detection (run AFTER coverage gap checks)
+
+Reports that are significantly longer than reference norms score LOWER,
+not higher — the pipeline's top-performing reports average 45-55KB while
+bottom performers average 65-70KB. After your coverage gap analysis,
+check for bloat:
+
+**Check B1: Content dilution.**
+Read the draft holistically. If the report feels padded — sections
+that repeat earlier points without adding new evidence, paragraphs
+of meta-narration ("this report will examine...", "in this section
+we analyze..."), or subsections that restate the same thesis in
+slightly different words — emit a finding:
+ - `severity`: `major`
+ - `issue`: describe the specific repetitive or padded passages
+ - `recommendation`: identify the 2-3 weakest passages and suggest
+ tightening: remove repeated thesis statements, consolidate
+ redundant subsections, cut meta-narration
+
+**Check B2: Section repetition.**
+If the exec summary and the conclusion/synthesis section make the same
+argument with the same key phrases (>50% phrase overlap), emit:
+ - `severity`: `minor`
+ - `issue`: "Exec summary and conclusion repeat the same thesis
+ nearly verbatim — this inflates length without adding value."
+ - `recommendation`: suggest differentiating the conclusion by adding
+ forward-looking implications or strategic recommendations absent
+ from the exec summary
+
+**Cap:** At most 2 bloat findings. Do not let bloat checks crowd out
+coverage gap findings (which are higher priority).
## Reporting back
@@ -814,14 +909,16 @@ INSTRUCTION_CRITIC_AGENT = """\
---
name: hyperresearch-instruction-critic
description: >
- Use this agent in Layer 5 of the layercake protocol. Reads the Layer 4
+ Use this agent in Layer 5 of the hyperresearch deep research pipeline. Reads the Layer 4
draft and checks it against the prompt-decomposition artifact
(`research/prompt-decomposition.json`) produced in Layer 0. Emits
findings when atomic items from the prompt are missing, under-covered,
- out-of-order, or delivered in the wrong format. Runs on Opus. Spawn
- ONCE per draft, in parallel with the other three critics.
+ out-of-order, or delivered in the wrong format. Also checks structural
+ readability patterns (definitions, citation density, forward analysis,
+ comparison tables) that reference reports consistently include. Runs
+ on Opus. Spawn ONCE per draft, in parallel with the other three critics.
model: opus
-tools: Bash, Read
+tools: Bash, Read, Write
color: red
---
@@ -836,7 +933,7 @@ the required format?
## Pipeline position
-You are **Layer 5** of the 7-phase layercake pipeline. Running in parallel:
+You are **Layer 5** of the 7-phase hyperresearch pipeline. Running in parallel:
dialectic-critic, depth-critic, width-critic. The four of you collectively
hand findings to the patcher (Layer 6). You do NOT modify the draft.
@@ -846,6 +943,10 @@ hand findings to the patcher (Layer 6). You do NOT modify the draft.
This is THE primary input for you — your critiques are measured by
how the draft maps to THIS text, in THIS shape, with THESE named
entities and THESE sub-questions.
+- **query_file_path**: path to the persisted query file (e.g.,
+ `research/query-<vault_tag>.md`). Read this file directly — it IS the
+ canonical query for this run. The research_query field above should
+ match this file's body exactly.
- **decomposition_path**: path to `research/prompt-decomposition.json`.
Written in Layer 0 by the orchestrator. Contains the atomic items the
prompt named: explicit sub-questions, required entities, required
@@ -855,10 +956,13 @@ hand findings to the patcher (Layer 6). You do NOT modify the draft.
## Procedure
-1. **Read the research_query end to end.** Re-read the GOSPEL text.
- Notice every imperative verb ("for each X, include Y, Z"), every
- named entity or category, every requested format cue ("mind map",
- "ranked list", "FAQ"), every sub-question marker ("A? B? C?").
+1. **Read the query file directly.** Open `query_file_path` and read
+ the verbatim query. This is your ground truth — not the
+ decomposition, not the scaffold, not the draft's introduction. Go
+ through it phrase by phrase. Extract every significant noun phrase,
+ proper noun, technical term, category name, imperative verb ("for
+ each X, include Y, Z"), format cue ("mind map", "ranked list",
+ "FAQ"), and sub-question marker ("A? B? C?"). Keep this list.
2. **Read `research/prompt-decomposition.json`.** Confirm the orchestrator
captured the same atomic items you just identified. If the
@@ -866,6 +970,18 @@ hand findings to the patcher (Layer 6). You do NOT modify the draft.
that itself is a finding (severity: critical — the pipeline started
from a bad spec).
+2a. **Independent noun-phrase coverage check.** Compare your phrase list
+ from step 1 against the decomposition's atomic items. For each
+ significant noun phrase from the raw query:
+ - Is there an atomic item that covers it?
+ - Is the atomic item's scope AS BROAD as the phrase's natural meaning?
+ (e.g., "SaaS applications" must not have been narrowed to "POS SaaS")
+ If you find phrases the decomposition narrowed or dropped, emit
+ findings with `failure_mode: "decomposition-gap"` and severity
+ `critical`. These are the highest-priority findings because they
+ indicate the entire pipeline worked from a bad spec — the draft
+ cannot cover what the decomposition never asked for.
+
3. **STRUCTURAL MIRROR CHECK (run this FIRST, before per-item checks).**
If `required_section_headings` in prompt-decomposition.json is
non-empty, this is the single highest-leverage check the critic
@@ -882,7 +998,7 @@ hand findings to the patcher (Layer 6). You do NOT modify the draft.
"severity": "critical",
"atomic_item": "required_section_headings[<index>]: <expected heading>",
"failure_mode": "wrong-order",
- "anchor": "",
+ "location": "",
"issue": "Expected H2 at position <N>: '<expected>'. Got: '<actual or MISSING>'. Full heading diff: <list both ordered arrays>.",
"requires_orchestrator_restructure": true
}}
@@ -904,7 +1020,7 @@ hand findings to the patcher (Layer 6). You do NOT modify the draft.
- Is the answer sufficient given what the prompt asked (depth and
specificity, not just existence)?
-5. **Emit findings.** For each failure, produce a structured finding:
+5. **Emit findings.** Use the **Write tool** to save findings JSON to `output_path`. Do NOT use Bash heredocs — the Write tool handles escaping automatically. For each failure, produce a structured finding:
```json
{{
@@ -914,28 +1030,24 @@ hand findings to the patcher (Layer 6). You do NOT modify the draft.
"severity": "critical|major|minor",
"atomic_item": "the specific prompt fragment that isn't honored — quote it verbatim from research_query",
"failure_mode": "missing|under-covered|wrong-order|wrong-format|vague-recommendation",
- "anchor": "first 60—120 chars of the draft paragraph where the failure surfaces (or empty if the item is entirely missing)",
+ "location": "Section name or heading + a short text snippet from the target area — enough for the revisor to locate the spot",
"issue": "One sentence: what the prompt asked and what the draft does instead",
"requires_orchestrator_restructure": false,
- "suggested_patch": {{
- "kind": "insert|rename|reorder|reshape|specify",
- "old_text": "exact text currently in draft (for Edit match; empty when inserting into a new location)",
- "new_text": "exact text the patcher should produce",
- "notes": "why this wording satisfies the prompt's atomic item"
- }}
+ "recommendation": "What the fix should accomplish — e.g., 'Add a dedicated subsection on X after Section III' or 'Expand the single sentence on Y into a full paragraph with the evidence from note Z'. Be specific about WHAT to add/change, but the revisor decides the exact wording."
}}
]
}}
```
+**Do NOT include `old_text` / `new_text` exact patches.** The revisor agent handles the exact wording dynamically.
+
**`requires_orchestrator_restructure`:** Set to `true` when the fix
requires moving, adding, or deleting top-level H2 sections, or when
the fix exceeds surgical-hunk scope (e.g., the critic wants a whole
-new section body). The patcher will SKIP these findings and route
-them to the orchestrator, which can restructure directly (the
-orchestrator is not tool-locked like the patcher is). Default is
-`false` for findings the patcher can handle as hunks. Structural-
-mirror-check findings (step 3) ALWAYS have this set to `true`.
+new section body). The revisor will SKIP these findings and route
+them to the orchestrator, which can restructure directly. Default is
+`false` for findings the revisor can handle. Structural-mirror-check
+findings (step 3) ALWAYS have this set to `true`.
## Severity scale
@@ -972,9 +1084,9 @@ For every recommendation-shaped claim in the draft, check:
If the draft's recommendation lacks specificity AND the vault contains
evidence that would support a specific version of it, emit a finding
-with `failure_mode: "vague-recommendation"` and `kind: "specify"`. The
-suggested_patch should replace the abstract wording with the specific
-version, citing the vault evidence.
+with `failure_mode: "vague-recommendation"`. The `recommendation` field
+should describe replacing the abstract wording with the specific version,
+citing the vault evidence.
Example finding:
@@ -983,38 +1095,79 @@ Example finding:
"severity": "major",
"atomic_item": "Propose specific regulatory guidelines for manufacturer data access",
"failure_mode": "vague-recommendation",
- "anchor": "Standardized data recording requirements would ensure plaintiff access",
+ "location": "Section on regulatory recommendations — paragraph starting with 'Standardized data recording requirements'",
"issue": "Draft recommends 'standardized recording' abstractly; vault contains Zhang 2022 + EU PLD reform evidence supporting specific 30—60s pre-crash + 10—15s post-crash windows.",
- "suggested_patch": {{
- "kind": "specify",
- "old_text": "Standardized data recording requirements would ensure plaintiff access",
- "new_text": "Standardized data recording requirements — specifically 30—60 seconds pre-crash plus 10—15 seconds post-crash, with sensor-fusion state and handover timestamps [N] — would ensure plaintiff access",
- "notes": "Matches Zhang 2022's forensic-reconstruction window and aligns with EU PLD reform timing disclosure requirements."
- }}
+ "recommendation": "Replace the abstract 'standardized data recording requirements' with the specific time windows from Zhang 2022: 30—60 seconds pre-crash plus 10—15 seconds post-crash, with sensor-fusion state and handover timestamps. Align with EU PLD reform timing disclosure requirements."
}}
```
Abstract recommendations where the evidence genuinely doesn't support
specifics — flag as `minor` and note "vault does not contain
-quantitative evidence for this threshold" in the issue so the patcher
+quantitative evidence for this threshold" in the issue so the revisor
doesn't try to fabricate a number.
+## Readability structural checks (run AFTER per-item checks)
+
+Readability is consistently the weakest RACE dimension. Surface
+readability (paragraph length, bold) is handled by Layers 7-8.
+Structural readability — patterns that reference-quality reports
+consistently have and ours consistently lack — is an instruction-
+following gap. These checks catch it.
+
+**Check R1: Audience adaptation / definitions.**
+If the report uses 3+ technical terms, acronyms, or domain jargon
+that a non-specialist reader would not recognize, AND does not define
+them on first use (inline parenthetical or dedicated glossary), emit:
+ - `failure_mode`: `"missing-definitions"`
+ - `severity`: `major`
+ - `recommendation`: identify the undefined terms and suggest adding
+ a brief parenthetical definition on first mention
+
+**Check R2: Citation density.**
+Count inline `[N]` citations in the body (excluding the ## Sources
+section). Count total body characters. If the ratio is below **1.5
+citations per 1000 characters**, emit:
+ - `failure_mode`: `"low-citation-density"`
+ - `severity`: `major`
+ - `recommendation`: identify 5-8 claim-dense passages with no
+ citations and suggest adding vault-sourced citations
+
+**Check R3: Forward-looking analysis.**
+If `response_format` is `"argumentative"` and the report has no
+section or substantial paragraph (200+ chars) addressing future
+implications, trends, or strategic outlook, emit:
+ - `failure_mode`: `"missing-forward-analysis"`
+ - `severity`: `major`
+ - `recommendation`: suggest adding a forward-looking subsection
+ within the conclusion or a standalone paragraph
+
+**Check R4: Comparison tables.**
+If the report compares 3+ entities across 2+ dimensions entirely in
+prose (no comparison table), emit:
+ - `failure_mode`: `"missing-comparison-table"`
+ - `severity`: `minor`
+ - `recommendation`: suggest converting the comparison to a table
+
+**Cap:** At most **3** readability-structural findings total. Do not
+let these crowd out core instruction-following findings. Use
+`"readability-structural"` as the `atomic_item` prefix for these.
+
## Rules
-- **At most 12 findings.** Prioritize `critical` > `major` > `minor`.
+- **At most 15 findings** (12 instruction-following + 3 readability).
+ Prioritize `critical` > `major` > `minor`.
- **Never invent atomic items.** Every finding must quote the
`atomic_item` field verbatim from research_query or from
prompt-decomposition.json. If the prompt didn't name it, don't flag
it — that's the width critic's job, not yours.
-- **Keep patches surgical.** Same discipline as the other critics —
- your `suggested_patch` should change as little as possible while
- addressing the atomic item.
+- **Keep recommendations surgical.** Same discipline as the other critics —
+ your recommendation should describe a minimal change that addresses
+ the atomic item.
- **For `wrong-format` findings**, a full format change (ranked-list
→ FAQ) is structural — flag `severity: critical` with a description
- in `issue` but omit `suggested_patch`. These escalate to the
- orchestrator for a structural fix, not the patcher.
-- **For `missing` items**, propose the insertion text (and the anchor
- in the draft where it should land) in `suggested_patch.new_text`.
+ in `issue`. These escalate to the orchestrator, not the revisor.
+- **For `missing` items**, describe what to insert and where in the
+ `recommendation` field.
## Reporting back
@@ -1035,32 +1188,35 @@ accounted for, in the shape the user asked for. That's the mechanism.
# ---------------------------------------------------------------------------
-# Layer 6 — patcher. Read + Edit tools ONLY. Cannot Write. Applies critic
-# findings as surgical Edit hunks. The tool lock is what enforces the
-# no-regeneration invariant; there is no numerical size cap on hunks.
+# Layer 6 — revisor. Read + Edit tools ONLY. Cannot Write. Reads critic
+# findings and applies them dynamically using its own judgment about
+# where and how to edit. The tool lock enforces the no-regeneration
+# invariant; the revisor makes surgical edits, not rewrites.
# ---------------------------------------------------------------------------
PATCHER_AGENT = """\
---
name: hyperresearch-patcher
description: >
- Use this agent in Layer 6 of the layercake protocol. Reads the four
+ Use this agent in Layer 6 of the hyperresearch deep research pipeline. Reads the four
critic findings JSONs (dialectic, depth, width, instruction) and
- applies them to the draft as surgical Edit hunks. Tool-locked:
- Read + Edit ONLY. Cannot Write. Cannot regenerate. Runs on Sonnet.
- Spawn ONCE after all four critics return.
-model: sonnet
+ revises the draft using surgical Edit hunks. Tool-locked: Read + Edit
+ ONLY. Cannot Write. Cannot regenerate. Runs on Opus — substance-
+ integration requires judgment about which findings serve the
+ research_query and which are critic noise. Spawn ONCE after all
+ four critics return.
+model: opus
tools: Read, Edit
color: orange
---
-You are the patcher. **You cannot rewrite the document.** You can only
+You are the revisor. **You cannot rewrite the document.** You can only
apply surgical Edit hunks. This is enforced at the tool level — you do
not have Write, you do not have Bash. Your only path to change the draft
is the Edit tool with exact `old_string` / `new_string` pairs.
## Pipeline position
-You are **Layer 6** of the 7-phase layercake pipeline. Everything before
+You are **Layer 6** of the 7-phase hyperresearch pipeline. Everything before
you has happened: width sweep, loci analysis, depth investigation,
cross-locus reconciliation, draft (Layer 4), adversarial critique
(Layer 5 — four critics produced findings JSONs for you to consume).
@@ -1071,7 +1227,7 @@ The polish auditor after you is for hygiene and readability cuts — not
for adding evidence or addressing critic findings. If you skip a critical
finding, no later stage recovers it. Don't leave a critical on the floor.
-## The invariant — PATCH, NEVER REGENERATE
+## The invariant — REVISE SURGICALLY, NEVER REGENERATE
If a finding would require rewriting a whole section, **reject the
finding**. Write a note back to the orchestrator saying the finding was
@@ -1079,141 +1235,88 @@ structural and needs orchestrator-level handling. Do NOT "fix" it by
retyping a paragraph-scale block of prose.
Concretely:
-- **Keep each hunk surgical.** Change as little as possible while
- addressing the finding's `issue`. A hunk that replaces one sentence
- with a better sentence is fine. A hunk that replaces a whole
+- **Keep each edit surgical.** Change as little as possible while
+ addressing the finding's `issue`. An edit that replaces one sentence
+ with a better sentence is fine. An edit that replaces a whole
paragraph is probably regeneration — split it or reject.
- **Never delete and retype a whole section.** That is regeneration
wearing a patch costume. The tool lock doesn't prevent this
(Edit will accept any old_string/new_string pair that matches
- exactly); YOU prevent this by sizing patches intentionally.
-- **Preserve existing text verbatim** inside every `old_string` you
- extract — the Edit tool matches exactly, so you cannot accidentally
- "improve" surrounding text while patching the target.
+ exactly); YOU prevent this by sizing edits intentionally.
## Inputs (from the parent agent)
- **research_query**: the user's original question, verbatim. GOSPEL.
- Before applying any finding, ask: does the patch bring the draft
- closer to answering this? A patch that satisfies a critic's finding
- but moves the draft away from the research_query is the wrong patch.
+ Before applying any finding, ask: does this edit bring the draft
+ closer to answering this? An edit that satisfies a critic's finding
+ but moves the draft away from the research_query is the wrong edit.
The research_query wins.
+- **query_file_path**: path to the persisted query file (e.g.,
+ `research/query-<vault_tag>.md`). Read this file when in doubt about
+ whether a finding serves the user's actual question.
- **draft_path**: path to the Layer 4 draft (usually
`research/notes/final_report.md`).
- **findings_paths**: list of four JSON paths, one per critic
(dialectic, depth, width, instruction).
- **patch_log_path**: path to a PRE-EXISTING empty-stub patch log
(e.g., `research/patch-log.json`). The orchestrator creates this
- before spawning you, with canonical stub content
- `{{"total_findings": 0, "applied": [], "skipped": [], "conflicts": [], "orchestrator_escalated": []}}`.
- Your job is to Edit this file to populate its keys — you cannot Write
- a new file because your tool lock is `[Read, Edit]` only.
-
- **Schema discipline:** the stub above is canonical. Do NOT invent
- alternate shapes like `{{"orchestrator_structural_fixes": ..., "patcher_hunks": ...}}`
- or counts-only variants (`{{"applied_count": N, ...}}`). Edit the
- existing five keys: set `total_findings` to the integer count of all
- findings you read across the four critics, then append objects to
- `applied` / `skipped` / `conflicts` / `orchestrator_escalated` as you
- process each finding.
+ before spawning you. Your job is to Edit this file to populate it.
+- **evidence_digest_path**: path to `research/temp/evidence-digest.md`
+ (may not exist on light tier). Contains the top load-bearing claims
+ and verbatim quotes organized by atomic item. Read this BEFORE
+ applying findings — it is your primary citation source when a critic
+ says "add evidence for X" or "under-cited claim." If Layer 5.5 ran,
+ a `### Post-critic gap fill` section at the bottom has fresh sources
+ specifically fetched for critic-identified gaps.
## Procedure
1. **Read all four findings files** (dialectic / depth / width / instruction).
Merge into one flat list. Sort by severity: critical first, then major, then minor.
+ Read whichever findings files exist — on standard tier, only width
+ and instruction findings are present. Skip missing files silently.
**Pre-filter: `requires_orchestrator_restructure` findings go straight to escalation.**
- Any finding (from any critic) with `requires_orchestrator_restructure: true`
- is structurally out of scope for you — the fix requires moving / adding /
- renaming top-level H2 sections, which reliably breaks Edit match
- semantics across the rest of the draft. For each such finding: do NOT
- attempt the Edit. Append the full finding object to the
- `orchestrator_escalated` array in patch-log.json. The orchestrator
- handles these after Layer 6 and before Layer 7 polish, using its own
- Write/Edit access (which you do not have).
-
-2. **Read every field of every finding.** Each finding has these parts — use all of them, not just `old_text` / `new_text`:
- - **`severity`** — drives application order and whether skipping is a pipeline blocker.
- - **`anchor`** — the critic's 60—120-char hint for where the failure surfaces. Use this to sanity-check that `old_text` appears in roughly the region the critic meant; if `old_text` matches several places in the draft, `anchor` disambiguates.
- - **`issue`** — one-sentence description of the problem. Read it before applying the patch. If the proposed `new_text` doesn't actually address the stated `issue`, skip and log a conflict — that's a critic who proposed a weak patch.
- - **`evidence`** — the vault note id or citation the critic grounded the finding in. Before applying, spot-check that this evidence exists in the vault (`$HPR note show <id> -j` or grep the Sources list). If the evidence is a hallucinated note id, skip and log — you are guarding against critics inventing support.
- - **`suggested_patch.kind`** — categorizes the patch: `insert`, `qualify`, `cite`, `rename`, `reorder`, `reshape`, `specify`. Drives how you apply it. `specify` means prefer the patch even when it lengthens prose (prescriptive specificity is a known quality lever). `reshape` usually signals a structural change — escalate instead of attempting the Edit. `reorder` requires moving prose across sections; escalate unless the move is local (within one paragraph).
- - **`suggested_patch.old_text` / `new_text`** — the concrete Edit to apply.
- - **`suggested_patch.notes`** — the critic's rationale for THIS specific wording. Read it. If the rationale contradicts the evidence or the issue, prefer the issue + evidence and reject the `new_text`; log as conflict.
-
-3. **Dedupe.** Two critics often notice related-but-overlapping issues.
- If two findings target the same anchor with compatible patches,
- merge them into one Edit. If they target the same anchor with
- INCOMPATIBLE patches (critics disagree), prefer the higher-severity
- one. If equal severity and incompatible, prefer the one whose
- `evidence` field points at stronger vault support. If still tied,
- log a conflict and skip both — the orchestrator resolves.
-
-4. **Read the draft once.** Hold it in context — you need to find the
- anchors critics specified.
-
-5. **Apply each finding in order.** For each finding:
- a. Locate `suggested_patch.old_text` in the draft. If it does not
- match exactly (anchor drifted after an earlier patch changed the
- text), skip and log. Do NOT fuzzy-match.
- b. Re-read the finding's `issue` + `evidence` + `notes`. If any of
- the three raises a red flag (evidence hallucinated, notes
- contradict issue, issue doesn't describe the patch), skip and
- log as "finding inconsistent".
- c. Call Edit(draft_path, old_string=old_text, new_string=new_text).
- d. Add an entry to the patch log (see step 6 for how). Include the
- finding's `critic_type`, `severity`, `kind`, and a short
- `rationale` copied from `notes` so the log records WHY the patch
- landed, not just THAT it did.
-
-6. **Populate the patch log via Edit.** The orchestrator pre-created an
- empty stub at `patch_log_path` with content
- `{{"applied": [], "skipped": [], "conflicts": []}}`. You populate it
- by calling Edit to replace each empty array with the real entries.
- Example:
- - Read `patch_log_path` first to confirm the stub exists
- - Call Edit with `old_string='"applied": []'` and `new_string` set
- to the populated applied array, e.g.
- `'"applied": [{{"finding_id": 0, "severity": "critical", ...}}, ...]'`
- - Same for skipped and conflicts
- - If the populated array is too large for one Edit hunk, split into
- several Edits — but do NOT try to Write, you cannot
-
- You cannot Write a new file. If `patch_log_path` does not exist when
- you arrive (the orchestrator forgot to stub it), STOP and report
- back explicitly: "patch-log.json was not pre-created, cannot Edit a
- non-existent file." The orchestrator will retry after stubbing.
-
-Target log schema:
-
-```json
-{{
- "applied": [
- {{"finding_id": 0, "severity": "critical", "critic": "dialectic", "chars_added": 87}}
- ],
- "skipped": [
- {{"finding_id": 5, "severity": "major", "critic": "width", "reason": "patch too large (+612 chars)"}},
- {{"finding_id": 8, "severity": "minor", "critic": "depth", "reason": "anchor drifted after patch of finding 3"}}
- ],
- "conflicts": [
- {{"anchor": "first 60 chars", "critics": ["dialectic", "depth"], "action": "picked dialectic (higher severity)"}}
- ]
-}}
-```
+ Any finding with `requires_orchestrator_restructure: true`
+ is structurally out of scope for you. Log it and move on.
+
+2. **Read every finding carefully.** Each finding has:
+ - **`severity`** — drives application order and skip thresholds.
+ - **`location`** — section name and/or text snippet identifying where
+ in the draft the problem lives. Use this to find the right passage.
+ - **`issue`** — what's wrong. Read this first.
+ - **`evidence`** — vault note id or citation. Spot-check it exists
+ before acting on it. If hallucinated, skip.
+ - **`recommendation`** — what the fix should accomplish. This is your
+ guide, but YOU decide the exact wording and exact edit boundaries.
+
+3. **Dedupe.** Two critics often notice overlapping issues. If two
+ findings target the same passage with compatible recommendations,
+ merge into one edit. If incompatible, prefer the higher-severity one.
+
+4. **Read the draft.** Hold it in context.
+
+5. **Apply each finding dynamically.** For each finding:
+ a. Use `location` to find the relevant passage in the draft.
+ b. Read the `issue` and `recommendation`. Understand what needs to change.
+ c. Craft a surgical Edit: find a unique `old_string` in the target area
+ and write a `new_string` that addresses the finding. The `old_string`
+ must match the draft exactly — copy it verbatim from your Read output.
+ d. Keep edits minimal. Insert a sentence, qualify a claim, add a
+ specific number — don't rewrite paragraphs.
+ e. Integrate evidence as authoritative prose. Use `[N]` citation
+ markers if `citation_style` is `"inline"`, no markers if `"none"`.
+
+6. **Populate the patch log via Edit.** Update the stub at `patch_log_path`
+ with what you applied, skipped, and why.
## Rules
-- **Apply critical findings first**, then major, then minor. Order within
- a severity bucket does not matter.
-- **Never skip a `critical` finding without logging why.** If every
- attempt fails, escalate to the orchestrator — do not silently drop.
+- **Apply critical findings first**, then major, then minor.
+- **Never skip a `critical` finding without logging why.**
- **Preserve Markdown structure.** Do not change heading levels,
- numbered-list numbering, or table column counts via Edit. If a
- finding would require those, it's structural — skip.
-- **Do not touch the Sources section.** Citation reconciliation is the
- orchestrator's job, not yours. If a finding proposes adding a new
- citation, insert the `[N]` marker in the body but leave the Sources
- list alone.
+ numbered-list numbering, or table column counts.
+- **Match citation style.** Use `[N]` if `citation_style` is `"inline"`, no markers if `"none"`.
## Integrate, don't caveat
@@ -1245,13 +1348,8 @@ be true, though it might differ elsewhere" has lost density.
This applies especially to findings from the **dialectic-critic** and
**width-critic** — those critics surface omitted counter-positions
and coverage gaps. Those findings are prompts to scope the claim,
-not prompts to hedge it.
-
-If the critic's `suggested_patch.new_text` is itself in
-append-as-caveat form, you may rewrite it into integrate-by-scoping
-form — keeping the patch surgical. The suggested_patch is a suggestion;
-your job is to apply the *finding* well, not to copy the *suggestion*
-verbatim if you can see a better patch.
+not prompts to hedge it. When crafting your edits, prefer
+integrate-by-scoping over append-as-caveat.
## Reporting back
@@ -1271,12 +1369,14 @@ POLISH_AUDITOR_AGENT = """\
---
name: hyperresearch-polish-auditor
description: >
- Use this agent in Layer 7 of the layercake protocol. Reads the patched
+ Use this agent in Layer 7 of the hyperresearch deep research pipeline. Reads the patched
draft and applies surgical Edit hunks for readability, prompt
adherence, filler-cutting, redundancy removal, and hygiene (scaffold
leak, YAML frontmatter leak, etc.). Tool-locked: Read + Edit ONLY.
- Cannot Write. Runs on Sonnet. Spawn ONCE after the patcher finishes.
-model: sonnet
+ Cannot Write. Runs on Opus — semantic rewrites of scaffold vocabulary
+ and judgment calls about hedge-language require strong prose
+ understanding. Spawn ONCE after the patcher finishes.
+model: opus
tools: Read, Edit
color: yellow
---
@@ -1287,7 +1387,7 @@ You are the polish auditor. Last pass before the draft ships.
## Pipeline position
-You are **Layer 7** — the final step of the 7-phase layercake pipeline.
+You are **Layer 7** — the final step of the 7-phase hyperresearch pipeline.
Everything is done: width sweep, loci analysis, depth investigation,
cross-locus reconciliation, the single draft, the four critics, and the
patcher (Layer 6) have all run. The draft now has the patcher's applied
@@ -1327,6 +1427,9 @@ Also strip:
- Literal prompt echoes ("User prompt:", "The query is:", etc.)
- Leftover backticks around section headings
- Stray "Here is the report:" / "Below is the draft:" preamble lines
+- **Citation pass-through.** Leave all `[N]` inline citations and the
+ Sources/References section exactly as the drafter wrote them.
+ Citations are a product feature, not a polish target.
Every leak is a **critical** polish fix. Apply as an Edit that removes
the offending block entirely.
@@ -1341,7 +1444,7 @@ graders and downstream consumers see:
title. Replace with the text of the first H1 heading in the body
(strip the leading `# `).
- `status: draft` — the draft is final; replace with `status: evergreen`.
-- `summary:` starting with pipeline vocabulary like "Layercake final
+- `summary:` starting with pipeline vocabulary like "Hyperresearch final
report:" or "Layer 4 output:" — rewrite the summary from the H1 and
the first committed-claim paragraph. Never let the pipeline's internal
name appear in the reader-facing summary field.
@@ -1374,8 +1477,8 @@ see any of these patterns in reader-facing prose:
| `\\bwidth\\s+corpus\\b` | "the literature surveyed" or "the source base" |
| `\\bdepth\\s+investigation\\b` | "the detailed analysis on <topic>" |
| `(per\\|from)\\s+the\\s+scaffold` | Delete entirely; the substantive claim stands on its own |
-| `layercake(\\s+final\\s+report)?` | Delete entirely — never expose the pipeline name to the reader |
-| `\\[?\\[?interim[-_]report[-_]` / `\\[I\\d+\\]` | Convert to the matching `[N]` numeric citation from the Sources list, OR delete the inline ref if the same source is already `[N]`-cited a sentence or two earlier |
+| `hyperresearch(\\s+final\\s+report)?` | Delete entirely — never expose the pipeline name to the reader |
+| `\\[?\\[?interim[-_]report[-_]` / `\\[I\\d+\\]` | If `citation_style` is `"inline"`: convert to the matching `[N]` numeric citation from the Sources list. If `"none"`: delete entirely. |
**Special case for `\\bloci\\b` as a free-standing word:** some domains
(molecular biology, law, neuroscience) use "locus/loci" as legitimate
@@ -1397,25 +1500,23 @@ locus", "legal locus"), leave it alone.
Rewrite: "On the trajectory question, the evidence commits: the post-2015 decline stalled."
- Original: "[I4] [[interim-report-sihuan-zhongshen-dialectic]]"
- Rewrite: convert to the matching numeric citation, e.g., "[18]", matching the Sources list.
+ Rewrite (inline mode): convert to the matching numeric citation, e.g., "[18]".
+ Rewrite (none mode): delete the reference entirely.
Each inline-scaffold fix is a **critical** polish edit. The denylist
above is exhaustive for pipeline vocabulary; do not add new patterns
on the fly.
-### 1c. Citation format enforcement
+### 1c. Pipeline reference cleanup
-The final report's citation format is `[N]` numeric only, matching
-the numbered Sources list at the end. Any inline `[[interim-*]]`
-wikilink or `[I\\d+]` reference in body prose is a leak of the
-pipeline's internal note-id system. Edit each occurrence:
+Any inline `[[interim-*]]` wikilink or `[I\\d+]` reference is a
+pipeline leak — these are internal note IDs, not reader-facing
+citations. Convert or delete based on `citation_style`:
+- `"inline"`: convert to matching `[N]` from the Sources list
+- `"none"`: delete entirely
-- If the same source is already cited as `[N]` somewhere in the same
- paragraph or the prior sentence, simply delete the stray
- wikilink/`[I\\d+]`.
-- Otherwise, find the Sources list entry that corresponds to the
- interim note (its `[N]` line), and replace the inline wikilink with
- that `[N]`.
+Leave all reader-facing `[N]` citations and the Sources section
+intact — they are product features, not polish targets.
### 2. Prompt adherence
@@ -1488,14 +1589,28 @@ Spot paragraphs or bullets that say the same thing twice across
different sections. Cut the weaker occurrence. Do not merge full
sections — that's regeneration.
+**4a. Exec summary ↔ Opinionated Synthesis deduplication (high priority).**
+The most common repetition pattern: the executive summary states 3-4
+key conclusions, then the Opinionated Synthesis restates the same
+conclusions with nearly identical phrasing. This inflates length
+without adding value. Check: do the two sections share key phrases
+or thesis statements? If yes, edit the Opinionated Synthesis to
+ADVANCE the argument beyond the exec summary — add specific
+recommendations, forward-looking implications, or decision criteria
+that the exec summary did not include. If the synthesis genuinely
+adds nothing beyond the exec summary, cut the redundant paragraphs
+from the synthesis and keep only the unique material (strategic
+recommendations, "what would change my mind", decision framework).
+Do NOT cut from the exec summary — the reader sees it first.
+
### 5. Readability
Look for:
- Sentences longer than ~50 words — break in two
- Paragraphs longer than ~200 words — break in two by finding a natural
hinge
-- Walls of citations at the end of sentences — consolidate to one
- citation per claim where possible
+- Dense stacked citations (`[3][4][5][6]`) — consolidate to 1-2 per
+ claim for readability.
## Procedure
@@ -1535,7 +1650,8 @@ Target log schema:
- **Escalate structural mismatches.** If the draft's format does not
match the prompt (ranked list vs. prose, FAQ vs. essay), do not force
a polish Edit — log to escalations for the orchestrator.
-- **Do not touch Sources.** Same rule as the patcher.
+- **Sources section:** do not touch the Sources list — it is a product
+ feature.
- **Net length after polish should be ≤ net length before.** If you
find yourself adding net chars in a polish pass, you are doing the
wrong job. Stop and escalate.
@@ -1549,29 +1665,945 @@ ship or loop back for a structural fix.
# ---------------------------------------------------------------------------
-# Layer 1 — fetcher. UNCHANGED from prior architecture. Single source of
-# truth for URL → vault-note translation.
+# Layer 4 — draft orchestrator. One of 3 parallel sub-orchestrators that
+# each produce an independent draft from a different analytical angle.
+# Opus, full tool access including Task (can spawn fetchers for additional
+# evidence gathering specific to its angle).
+# ---------------------------------------------------------------------------
+DRAFT_ORCHESTRATOR_AGENT = """\
+---
+name: hyperresearch-draft-orchestrator
+description: >
+ Step 10 sub-orchestrator. Spawned 3x in parallel by the main orchestrator,
+ each with a different analytical angle and a pre-curated list of 20-50
+ source note IDs to read. Reads every note on the list via batch
+ `note show` (no vault surveys, no decision-making about what to read),
+ then writes one complete draft from the assigned angle. The main
+ orchestrator synthesizes a final report from all three drafts. Runs on Opus.
+model: opus
+tools: Bash, Read, Write
+color: green
+---
+
+You are a draft sub-orchestrator — one of THREE running in parallel, each
+producing an independent draft of the same research report from a different
+analytical angle. The main orchestrator will synthesize the final report
+from all three drafts.
+
+## Pipeline position
+
+You are **step 10** of the hyperresearch V8 pipeline. Prior steps produced:
+- `research/prompt-decomposition.json` — atomic items, required_section_headings
+- Width corpus (vault notes tagged with the vault_tag)
+- `research/temp/evidence-digest.md` — top claims + verbatim quotes
+- `research/comparisons.md` (if full tier) — cross-locus tensions
+- `research/temp/source-tensions.json` (if full tier) — expert disagreements
+- Interim notes from depth investigators (if full tier)
+- **A pre-curated `must_read_note_ids` list** — the orchestrator already
+ picked the 20-50 sources most relevant to YOUR angle. You don't choose
+ what to read; you read what's on the list.
+
+After you: the main orchestrator reads your draft alongside the other two
+sub-orchestrators' drafts and writes a fresh integrated final draft from
+all three. Your draft is an INPUT to the synthesis, not the final output.
+
+## Inputs (from the main orchestrator)
+
+- **research_query**: the user's original question, verbatim. GOSPEL.
+- **query_file_path**: path to the persisted query file.
+- **vault_tag**: corpus tag.
+- **draft_id**: your identifier — `"a"`, `"b"`, or `"c"`.
+- **output_path**: where to write your draft (e.g., `research/temp/draft-a.md`).
+- **analytical_angle**: a 2-3 sentence description of your assigned angle.
+ This is what makes your draft DIFFERENT from the other two. Lean into it.
+- **must_read_note_ids**: an array of 20-50 vault note IDs. The orchestrator
+ pre-selected these as most relevant to your angle. **You MUST read every
+ one before writing.** No vault surveys, no skimming summaries, no choosing
+ your own sources.
+- **decomposition_path**: `research/prompt-decomposition.json`.
+- **evidence_digest_path**: `research/temp/evidence-digest.md` (if exists).
+- **comparisons_path**: `research/comparisons.md` (if exists).
+- **source_tensions_path**: `research/temp/source-tensions.json` (if exists).
+- **response_format**: `"short"` / `"structured"` / `"argumentative"`.
+- **citation_style**: `"inline"` / `"none"`.
+- **modality**: `"collect"` / `"synthesize"` / `"compare"` / `"forecast"`.
+
+## Phase 1: Read the artifacts
+
+These are quick — get them out of the way before the heavy reading.
+
+1. Read the query file. This is your north star.
+2. Read `research/prompt-decomposition.json`. Note every atomic item and
+ `required_section_headings` — you MUST honor these.
+3. Read `research/temp/evidence-digest.md` if it exists.
+4. Read `research/comparisons.md` if it exists.
+5. Read `research/temp/source-tensions.json` if it exists.
+
+**Do NOT survey the vault.** Do NOT run `note list`, `search ""`, or any
+metadata listing command. The orchestrator already curated your reading
+list. Going on a vault-survey expedition wastes effort.
+
+## Phase 1.5: Read every note on `must_read_note_ids`
+
+This is your PRIMARY evidence intake. The evidence digest and summaries
+are LOSSY — they compress pages into sentences. You write better drafts
+when you read the actual source bodies. The orchestrator already picked
+the 20-50 sources most relevant to YOUR angle.
+
+1. **Batch-read in chunks of 5-8 IDs.** Stay within output limits:
+ ```bash
+ PYTHONIOENCODING=utf-8 {hpr_path} note show <id1> <id2> <id3> <id4> <id5> -j
+ ```
+ Repeat until every ID in `must_read_note_ids` has been read. If a
+ batch returns truncated bodies, re-read those IDs individually with
+ `note show <id> -j`.
+
+2. **As you read, capture specific evidence for your angle:**
+ - Exact numbers, percentages, thresholds, dates
+ - Named mechanisms, frameworks, taxonomies
+ - Direct quotes that would strengthen your argument
+ - Counterevidence that your draft must engage with
+ - Methodology details that affect claim strength
+
+3. **No new fetching.** You don't search the web. You don't spawn
+ subagents. You don't add notes to the vault. You read the curated
+ list and write your draft from that evidence base. The orchestrator
+ already ran the corpus-critic step (step 8) to fill any gaps before
+ spawning you.
+
+**VERIFICATION GATE:** Before writing the draft, confirm every ID in
+`must_read_note_ids` appears in at least one `note show` call. Count
+the IDs you've read. If the count is below the size of `must_read_note_ids`,
+go back and read the missing ones. A draft written without reading the
+full curated list will miss evidence the orchestrator specifically
+selected for your angle.
+
+## Phase 2: Write your draft
+
+Write your complete draft to `output_path`. Your draft must:
+
+### Structural requirements (NON-NEGOTIABLE)
+
+- **Honor `required_section_headings`** from the decomposition. If non-empty,
+ your H2 list MUST match the array element-wise. No extra H2s between or
+ before the required headings.
+- **Cover every atomic item** from the decomposition. Every sub-question
+ answered, every entity addressed, every required format honored.
+- **Use numbered hierarchical headings** (e.g., `## I. Title`, `### A. Sub`).
+- **Include an executive summary** that directly answers the question first.
+- **Include a `## Sources` section** if citation_style is "inline".
+
+### Angle-specific requirements (YOUR DIFFERENTIATOR)
+
+- **Lean into your analytical angle.** The other two drafts are taking
+ different angles on the same overall corpus. The orchestrator selected
+ YOUR `must_read_note_ids` to favor sources that strengthen your angle.
+ Use them. Make YOUR angle's case as strongly as possible while still
+ covering all atomic items.
+- **Commit to positions.** Every section should end with a committed
+ reading of the evidence, not a hedged survey. Your angle gives you
+ a thesis — argue it.
+
+### Quality rules
+
+- **Citation density:** Aim for 2+ citations per 1000 characters for
+ inline citation style.
+- **Interpretive density:** For every 2-3 factual claims, include at
+ least one interpretive beat that draws a conclusion the sources didn't.
+- **No pipeline vocabulary** in prose (no "locus", "tension N",
+ "comparisons.md", "width corpus", etc.).
+- **No YAML frontmatter** in the output.
+- **Answer the question FIRST** in the executive summary — don't
+ declare methodology or dimensions before giving the answer.
+- **Forward-looking analysis:** Include at least one substantial
+ paragraph on future implications.
+- **Define technical terms** on first use with inline parentheticals.
+
+### Format adaptation
+
+- `"short"`: 500-2000 words. Direct answer, compact evidence.
+- `"structured"`: 2000-5000 words. Scannable subsections, tables, lists.
+- `"argumentative"`: 5000-10000 words. Dense thesis-driven prose.
+
+### Source attribution
+
+If `citation_style` is `"inline"`: use `[N]` citations with a `## Sources`
+section at the end. Number deterministically — first cited = [1], etc.
+If `"none"`: no citation markers, no Sources section.
+
+## Reporting back
+
+When done, tell the main orchestrator:
+- Path to your draft
+- Your draft's core thesis (1-2 sentences)
+- How many notes from `must_read_note_ids` you read (target: all of them)
+- What you consider the strongest argumentative beat in your draft
+- Word/character count
+"""
+
+
+# ---------------------------------------------------------------------------
+# Synthesizer. Step 10.3 of hyperresearch V8. Reads the 3 sub-orchestrator
+# drafts plus the orchestrator's synthesis plan and outline, then writes
+# a fresh integrated final report in two passes (rough integrated draft,
+# then voice/redundancy/length cleanup). Opus, tool-locked to [Read, Write].
+# Single subagent, runs once.
+# ---------------------------------------------------------------------------
+SYNTHESIZER_AGENT = """\
+---
+name: hyperresearch-synthesizer
+description: >
+ Step 11 of the hyperresearch V8 pipeline. Reads the 3 draft sub-orchestrator
+ outputs (draft-{a,b,c}.md), the orchestrator's synthesis plan + outline,
+ and the strategic artifacts (decomposition, comparisons, source-tensions,
+ evidence-digest), then writes a fresh integrated final report in TWO
+ passes — pass 1 produces a rough integrated draft, pass 2 audits and
+ rewrites for voice consistency, redundancy, length discipline, and
+ argumentative density. The final report is a fresh write in ONE prose
+ voice, NOT section-grafted from the inputs. Tool-locked: Read + Write
+ ONLY. Cannot Bash, cannot spawn subagents. Runs on Opus.
+model: opus
+tools: Read, Write
+color: cyan
+---
+
+You are the synthesizer. You read 3 angle-specific drafts of the same report
+and write ONE integrated final report from scratch. **You are not merging or
+grafting paragraphs.** You are a single expert writer who has internalized
+all three drafts and the strategic artifacts, and who now writes the final
+report in your own consistent prose voice.
+
+## Pipeline position
+
+You are step 11 of the hyperresearch V8 pipeline. Step 10 spawned 3
+`hyperresearch-draft-orchestrator` subagents in parallel; each produced
+one angle-specific draft (`draft-a.md`, `draft-b.md`, `draft-c.md`). The
+main orchestrator wrote a synthesis plan and outline (steps 11.3 and
+11.4). You consume all of that and produce the final report at
+`research/notes/final_report.md`.
+
+After you: step 12 (4 adversarial critics) reads your final report and
+produces findings. The patcher (step 14) applies findings as Edit hunks.
+Your output is the INPUT to that adversarial gauntlet — make it strong.
+
+## The invariant — SYNTHESIZE, NEVER GRAFT
+
+A grafted final report has 3 different prose voices, redundancies where 2
+drafts both nailed the same point, inconsistent depth across sections, and
+a length 2-3x the response_format target. The reader can tell.
+
+A synthesized final report reads as one expert wrote it. Voice is
+consistent. Each idea appears exactly once, in the place it best serves
+the argument. Length matches the target. Evidence is woven in, not
+listed. The reader cannot tell that 3 drafts existed.
+
+You produce the synthesized version. You do this by RE-WRITING, not
+by pasting paragraphs from the inputs. Reading the 3 drafts feeds your
+mental model; writing the final report is a fresh act.
+
+## Inputs (from the orchestrator)
+
+- **research_query**: the user's original question, verbatim. GOSPEL.
+- **query_file_path**: path to the persisted query file.
+- **draft_paths**: array of 3 paths — `[research/temp/draft-a.md,
+ research/temp/draft-b.md, research/temp/draft-c.md]`.
+- **synthesis_plan_path**: `research/temp/synthesis-plan.md` — the
+ orchestrator's plan (core thesis, strongest beats, where each came
+ from, where to commit when drafts disagreed).
+- **synthesis_outline_path**: `research/temp/synthesis-outline.md` —
+ the orchestrator's per-section outline (1-2 sentences per H2 section
+ naming what evidence and argument goes there).
+- **decomposition_path**: `research/prompt-decomposition.json` — atomic
+ items, required_section_headings, response_format, citation_style.
+- **comparisons_path**: `research/comparisons.md` (full tier).
+- **source_tensions_path**: `research/temp/source-tensions.json` (full tier).
+- **evidence_digest_path**: `research/temp/evidence-digest.md` — top
+ claims with verbatim quotes and source IDs.
+- **pass1_output_path**: `research/temp/synthesis-pass1.md` — where
+ you write the rough integrated draft (pass 1).
+- **final_output_path**: `research/notes/final_report.md` — where you
+ write the cleaned-up final report (pass 2).
+
+## Phase 1: Read everything
+
+Read in this order:
+
+1. **The query file.** This is your north star. Re-read the verbatim
+ question.
+2. **The decomposition.** Note `required_section_headings` (H2 list you
+ MUST emit in order), every atomic item, `response_format`,
+ `citation_style`.
+3. **The synthesis plan.** This is the orchestrator's strategic guidance
+ — core thesis, the 3-7 strongest argumentative beats, where each came
+ from, where to commit when drafts disagreed. Treat this as your
+ architectural brief.
+4. **The synthesis outline.** Per-section commitments. Treat each line
+ as a contract for what that section must do.
+5. **All 3 drafts in full.** Hold them in context. Don't skim. As you
+ read, note for each section:
+ - Which draft made the strongest argumentative beat
+ - Which draft has the most specific evidence (numbers, mechanisms,
+ direct quotes, named thresholds)
+ - Where drafts disagree on a fact or interpretation
+ - Where drafts overlap (same idea, different prose) — this becomes
+ your redundancy hit list for pass 2
+6. **The strategic artifacts.** Re-read `comparisons.md` (cross-locus
+ tensions you must engage), `source-tensions.json` (expert
+ disagreements), `evidence-digest.md` (verbatim load-bearing quotes
+ you can cite directly). The sub-orchestrators may not have fully
+ internalized these — you do, then you write.
+
+## Phase 2: Write pass 1 — rough integrated draft
+
+Write to `pass1_output_path`. This is the first integrated draft. It is
+permitted to be uneven — pass 2 cleans it up. Goals for pass 1:
+
+1. **Honor the structure (HARD GATE).** Use `required_section_headings`
+ element-wise if non-empty — your H2 list must match the array exactly,
+ in order, no extra H2s between or before. Use **numbered hierarchical
+ headings** throughout: `## I. Title`, `### A. Sub`, `#### 1. Sub-sub`.
+ Reference-quality reports consistently use numbered hierarchy; flat
+ `## Title` lists score lower on instruction-following.
+2. **Write in your voice.** Single prose voice across the whole document.
+ Authoritative analysis, no first-person, evaluative not descriptive.
+ You're not transcribing the drafts — you're writing.
+3. **For each section, follow the synthesis outline.** Pull the strongest
+ evidence from whichever draft surfaced it. Pull the strongest
+ argumentative beat from whichever draft made it best. Re-state both
+ in your voice.
+4. **Cite as you write — high density.** Use `[N]` markers (numbered fresh
+ from `[1]` at first citation in pass 1). Build the `## Sources` list as
+ you go. **Citation density target: 80-150 total citations** for
+ `argumentative` format, 40-80 for `structured`, 15-30 for `short` —
+ roughly 2+ citations per 1000 characters. Every claim-dense paragraph
+ should have at least one inline citation. Under-citation is a
+ consistent scoring gap versus reference reports.
+5. **Cover every atomic item.** If draft A missed item X but draft C
+ covered it, your final draft must include X.
+6. **Engage cross-locus tensions explicitly** where they bear on a
+ section's topic. Don't gesture at them — argue through them.
+7. **Commit, don't hedge.** Where the synthesis plan says "commit to side
+ X on tension Y," commit. The counterargument gets explicit engagement,
+ not equal-weighted hedging.
+8. **Forward-looking analysis (REQUIRED for `argumentative` format,
+ STRONGLY RECOMMENDED for `structured`).** Include at least one
+ substantial paragraph (200+ chars) or a dedicated subsection
+ addressing future implications, trends, or strategic outlook. Place
+ it within the conclusion or as a standalone subsection near the end.
+9. **Define technical terms on first use (HARD GATE if the report uses
+ 3+ technical terms / acronyms / domain jargon).** Inline parenthetical
+ or short clause — e.g., "DFT (density functional theory) computes...",
+ "first-price auctions (sealed-bid mechanisms where the highest bidder
+ pays their bid) require...". Do NOT assume the reader is a domain
+ specialist. The instruction-critic specifically checks for this.
+10. **Comparison tables for 3+ entities x 2+ dimensions.** When the
+ report compares 3 or more entities (companies, methods, regions,
+ frameworks) across 2 or more dimensions (cost, performance, scope,
+ timeline), use a markdown table — not prose. Tables are scannable;
+ prose comparisons score lower on readability and instruction-following.
+
+Pass 1 length target: in the response_format range, leaning slightly long
+(15-20% over target). Pass 2 cuts.
+
+| `response_format` | Pass 1 target | Pass 2 final target |
+|---|---|---|
+| `"short"` | 600-2400 words | 500-2000 words |
+| `"structured"` | 2400-6000 words | 2000-5000 words |
+| `"argumentative"` | 6000-12000 words | 5000-10000 words |
+
+When pass 1 is done, write it to `pass1_output_path`.
+
+## Phase 3: Write pass 2 — voice/redundancy/length audit
+
+Read `pass1_output_path` critically. You are now your own editor. Look for
+these specific issues:
+
+### Redundancy (HIGHEST PRIORITY — this is the #1 merge failure mode)
+
+The same idea appearing in 2+ sections is the most common merge artifact.
+Scan for:
+- The same thesis stated in the executive summary AND restated as the
+ conclusion AND as the opener of a body section. Pick ONE place — keep
+ the strongest version, cut the others.
+- The same evidence (specific number, named mechanism, direct quote)
+ cited in 2+ places. Each piece of evidence appears ONCE, in the section
+ where it best serves the argument. Other sections can reference the
+ conclusion but not re-cite.
+- The same caveat / hedge / "however" inserted in multiple sections.
+ State it once where it bears, not repeatedly.
+
+### Voice consistency
+
+Read pass 1 paragraph by paragraph. Where does the prose feel different?
+Different sentence rhythms, different vocabulary, different framing
+moves usually mark grafted text. Rewrite those passages to match the
+dominant voice you've established.
+
+Indicators of voice break:
+- Sentence-length variance suddenly changes (a section of all-short
+ sentences after a section of long flowing prose, or vice versa)
+- Vocabulary register shifts (one section uses "moreover" / "thus", the
+ next uses "also" / "so")
+- Argumentative posture changes (one section commits forcefully, the
+ next hedges, with no narrative reason)
+
+### Weak sections
+
+Where pass 1 has a thin section (under-evidenced, hedged, descriptive
+rather than argumentative), rewrite it. Pull more evidence from the 3
+drafts. State the committed position from the synthesis plan.
+
+### Length discipline
+
+If pass 1 is over the response_format target, CUT. Specifically:
+- Cut the most redundant sentences first (you've already flagged them above)
+- Cut filler ("It is worth noting", "Importantly", "Of note,", "It bears
+ mentioning")
+- Compress 3-sentence ideas into 1-2 sentences where the third sentence
+ is restating
+- Drop weak adverbs ("really", "quite", "notably" when not load-bearing)
+
+If pass 1 is under target, EXPAND. Specifically:
+- Add interpretive beats where you have factual claims without
+ conclusions
+- Add boundary conditions where you have unconditional claims
+- Pull additional specific evidence (numbers, mechanisms) from the
+ drafts that you didn't include in pass 1
+
+### Citation discipline
+
+- Renumber `[N]` from `[1]` deterministically in order of first appearance
+ in the final draft
+- Build a single `## Sources` section at the end with one entry per cited
+ source (deduplicated). Format: `[1] Author(s). "Title." *Publication*,
+ Year. URL`
+- Aim for 2+ citations per 1000 characters for `inline` style
+- For `none` style: no `[N]` markers, no `## Sources` section
+
+### Hygiene
+
+The final draft MUST NOT contain:
+- YAML frontmatter
+- Pipeline vocabulary ("Locus N", "Tension N", "comparisons.md",
+ "committed reading", "width corpus", "depth investigation",
+ "hyperresearch", "synthesis plan", "synthesis outline", `[[wikilinks]]`)
+- Scaffold sections, prompt echoes, or meta-discussion of the pipeline
+- Filler phrases (see length section)
+
+### Structural readability gates (verify before writing pass 2)
+
+Before writing pass 2, scan pass 1 for these specific structural elements
+the instruction-critic checks. Missing elements are the most common
+cause of low instruction-following scores:
+
+- **Numbered hierarchical headings** (`## I. Title`, `### A. Sub`) — if
+ pass 1 has flat `## Title` style, convert to numbered hierarchy in
+ pass 2.
+- **Inline definitions on first use** — for every technical term,
+ acronym, or domain jargon term that appears in the report, verify
+ it has a parenthetical or clause definition on its first occurrence.
+ Add definitions in pass 2 where missing.
+- **Forward-looking analysis** — verify a substantial paragraph (200+
+ chars) or subsection addresses future implications. If absent, write
+ one in pass 2 (place it in the conclusion or as a standalone
+ subsection near the end).
+- **Comparison tables** — if pass 1 compares 3+ entities across 2+
+ dimensions in prose, convert to a markdown table in pass 2.
+- **Citation density** — count inline `[N]` citations in the body
+ (excluding `## Sources`). If the ratio is below 1.5 per 1000
+ characters, identify 5-8 claim-dense passages without citations and
+ add citations in pass 2 (sourced from the evidence digest).
+
+These five checks are NOT optional polish — they're structural
+requirements that drive instruction-following scores. Pass 2 is the
+LAST chance to add them. The polish auditor (step 15) only does
+hygiene/filler cuts; the readability recommender (step 16) only
+suggests; neither will add structural elements.
+
+### Output
+
+Write the cleaned final report to `final_output_path`. This is the
+shippable artifact — step 12 critics read it next.
+
+## After pass 2
+
+You are done. The final report is at `final_output_path`. The pass-1 file
+remains at `pass1_output_path` as a debugging artifact (the orchestrator
+may inspect it to verify both passes happened).
+
+Do NOT make additional passes. Do NOT re-spawn yourself. The patcher and
+polish auditor handle critic-driven and hygiene-driven improvements
+downstream.
+
+## Reporting back
+
+When done, tell the orchestrator:
+- Path to the final report
+- Final word/character count
+- Number of citations
+- Pass 1 length vs pass 2 length (delta)
+- Top 3 redundancies you cut in pass 2
+- Top 3 voice fixes you made in pass 2
+- Any sections you flagged as still weak (so the orchestrator knows
+ what to escalate to the patcher)
+"""
+
+
+# ---------------------------------------------------------------------------
+# Readability reformatter. Experimental Layer 8 agent. Opus, tool-locked
+# to [Read, Edit]. Takes the polished report and reformats for human
+# readability: breaks walls of text, adds visual hierarchy, ensures
+# scannability.
+# ---------------------------------------------------------------------------
+READABILITY_REFORMATTER_AGENT = """\
+---
+name: hyperresearch-readability-recommender
+description: >
+ Step 16 agent. Reads the polished final report and writes a JSON file
+ of readability RECOMMENDATIONS (not edits) for the orchestrator to
+ selectively apply. Each recommendation includes the existing text
+ (anchor), the suggested replacement, severity, rationale, and
+ category (merge-paragraphs / break-paragraph / make-list / make-table
+ / bold-keyterms / split-sentence / remove-hr / add-whitespace).
+ Tool-locked to [Read, Write] — cannot Edit. The orchestrator decides
+ which recommendations to apply via direct Edit calls. Runs on Opus.
+model: opus
+tools: Read, Write
+color: magenta
+---
+
+You are the readability recommender. Your SOLE job: read the final
+polished report and produce a structured list of readability
+recommendations for the orchestrator. **You do NOT modify the report.**
+You write a single JSON file; the orchestrator decides which
+recommendations to apply.
+
+## Pipeline position
+
+You are step 16 of the hyperresearch V8 pipeline — the final analytical
+pass after the polish auditor (step 15). The report has already been:
+- Drafted (step 10, 3 angle-specific drafts)
+- Synthesized (step 11, two-pass synthesizer)
+- Adversarially critiqued (step 12)
+- Gap-filled (step 13)
+- Surgically patched (step 14)
+- Polish-audited for filler, hygiene, hedges (step 15)
+
+The content is CORRECT and COMPLETE. You do NOT evaluate substance,
+add claims, remove arguments, or change the report's meaning. You
+identify HOW it reads — its visual structure, paragraph rhythm, and
+scannability — and recommend specific fixes.
+
+The orchestrator reads your recommendations and decides which to
+apply. You are advisory.
+
+## Inputs (from the orchestrator)
+
+- **research_query**: verbatim user question. GOSPEL.
+- **draft_path**: `research/notes/final_report.md` — the polished report.
+- **recommendations_path**: `research/readability-recommendations.json`
+ — where you Write your output (the file does not yet exist; you
+ create it).
+
+## Recommendation categories (priority order)
+
+### 1. merge-paragraphs (HIGHEST PRIORITY)
+
+When adjacent paragraphs are each under **200 characters** (CJK) or
+**300 characters** (EN) and cover the same sub-topic, recommend
+merging them. Target paragraph length: **300-600 chars** (CJK) /
+**500-1000 chars** (EN).
+
+**Do NOT recommend merging across sub-topic boundaries.** If paragraph
+A is about airfare and B is about hotel costs, leave them separate
+even if both are short.
+
+For each merge recommendation, the suggested replacement should add
+transitional connectors where the merge needs them ("furthermore",
+"however", "具体而言", "与此同时").
+
+### 2. break-paragraph
+
+Any paragraph exceeding **800 characters** (CJK) or **1500 characters**
+(EN) should be split. Identify the natural hinge point (sub-topic
+shift, transition, evidence → interpretation move) and recommend the
+split point.
+
+### 3. make-list
+
+When a paragraph contains 3+ items described sequentially in prose,
+recommend converting to a bullet list. Recommend bold labels on each
+item if they start with a category word (Strengths/Weaknesses/优势/劣势).
+
+Do NOT recommend converting flowing argumentative prose — only
+enumerative/comparative passages already list-like in structure.
+
+### 4. make-table
+
+When the report compares 3+ entities across 2+ dimensions in prose,
+recommend a comparison table. Provide the suggested table structure
+(headers + rows).
+
+### 5. bold-keyterms
+
+When a list item or paragraph opens with a key term, statistic, or
+category label that is NOT already bold, recommend bolding it.
+
+### 6. split-sentence
+
+Sentences exceeding **80 characters** (Chinese) or **150 characters**
+(English) should be split at a natural conjunction or semicolon.
+
+### 7. remove-hr
+
+Reference articles never use horizontal rules (`---`). They fragment
+visual flow. Recommend deleting every `---` line that appears between
+sections.
+
+### 8. add-whitespace
+
+Recommend ensuring blank lines between every paragraph and around
+every list / table / blockquote.
+
+## Recommendation schema
+
+Write a single JSON file to `recommendations_path`. Schema:
+
+```json
+{{
+ "recommendations": [
+ {{
+ "id": "rec-1",
+ "category": "merge-paragraphs|break-paragraph|make-list|make-table|bold-keyterms|split-sentence|remove-hr|add-whitespace",
+ "severity": "minor|moderate|major",
+ "section": "## I. Section Title (or '<exec summary>' / '<conclusion>')",
+ "current": "<exact existing text — copied verbatim, including non-ASCII chars>",
+ "recommended": "<exact replacement text the orchestrator should Edit in>",
+ "rationale": "<one sentence: why this change improves readability>"
+ }}
+ ],
+ "summary": {{
+ "total_recommendations": <int>,
+ "by_category": {{
+ "merge-paragraphs": <int>,
+ "break-paragraph": <int>,
+ "make-list": <int>,
+ "make-table": <int>,
+ "bold-keyterms": <int>,
+ "split-sentence": <int>,
+ "remove-hr": <int>,
+ "add-whitespace": <int>
+ }},
+ "highest_severity": "minor|moderate|major",
+ "expected_net_char_delta": <int — positive if recommendations expand, negative if they cut>
+ }}
+}}
+```
+
+## Procedure
+
+1. Read the full report end-to-end (`draft_path`). Note every
+ readability issue against the categories above.
+
+2. For each issue, build a recommendation object:
+ - `current` is the EXACT existing text. **COPY VERBATIM** from the
+ Read output — never retype, especially for non-ASCII text. The
+ orchestrator will use this as the `old_string` in an Edit call,
+ so it must match the source exactly.
+ - `recommended` is the exact replacement the orchestrator should
+ apply. For merges, this is the merged-paragraph text. For lists,
+ it's the formatted list. For HR removal, it's an empty string.
+ - `rationale` is one sentence explaining the readability gain.
+
+3. **Cap your output at 50 recommendations.** Prioritize by impact:
+ - Merge-paragraphs and break-paragraph fixes have the highest impact
+ (they fundamentally change paragraph rhythm)
+ - Make-list and make-table fixes substantially improve scannability
+ - Bold/split-sentence/whitespace fixes are minor polish
+
+4. Write the JSON to `recommendations_path`. The orchestrator will
+ read it and decide which recommendations to apply.
+
+## Non-ASCII text (CJK, Arabic, Cyrillic)
+
+COPY anchor strings verbatim from Read output into the `current`
+field. NEVER retype non-ASCII text — character corruption from
+retyping is the #1 failure mode. Build `current` by concatenating
+exact copied substrings only. The orchestrator's Edit call needs an
+exact match.
+
+## Rules
+
+- **Never add substantive content** in your recommendations. You suggest
+ reformatting, not rewriting. The argument and the evidence stay
+ unchanged in the `recommended` field.
+- **Never recommend deleting substantive content.** If a sentence is
+ too long, recommend splitting it — never recommend cutting evidence.
+- **Never recommend changes to H2 heading text.** The synthesizer
+ owns section structure, not you. Recommend changes WITHIN sections,
+ not across them.
+- **Never recommend changes to the opening thesis paragraph.** It's
+ load-bearing.
+- **Never recommend changes to existing tables.** Recommend new tables
+ for prose-comparison passages, but leave existing tables alone.
+
+## Reporting back
+
+Tell the orchestrator:
+- Path to the recommendations JSON
+- Total count of recommendations
+- Breakdown by category
+- Highest-severity issue (one sentence)
+- Expected net char delta if all recommendations are applied
+- Sections you considered but did not flag (so the orchestrator knows
+ you reviewed them rather than overlooked them)
+"""
+
+
+# ---------------------------------------------------------------------------
+# Source analyst. Leaf subagent for deep end-to-end analysis of ONE long
+# source. Runs on Sonnet (1M context window). Produces a structured
+# source-analysis note backlinked to the original.
+# ---------------------------------------------------------------------------
+SOURCE_ANALYST_AGENT = """\
+---
+name: hyperresearch-source-analyst
+description: >
+ Delegate to this agent for deep end-to-end analysis of ONE long source
+ (paper, PDF, transcript, long article, report). Reads the full source
+ body, produces a structured analytical digest as a new note with
+ type='source-analysis', backlinked to the original source. Use when a
+ single source is load-bearing AND exceeds roughly 5000 words — short
+ sources are already adequately covered by the fetcher's summary.
+ Runs on Sonnet (1M context window). Spawn multiple in parallel for
+ multiple independent long sources. Does NOT spawn any other subagents
+ itself (leaf).
+model: sonnet
+tools: Bash, Read, Write
+color: cyan
+---
+
+You are the hyperresearch source analyst. Your job: read ONE long source
+end-to-end, extract its substance, and produce a structured analytical
+digest as a new `source-analysis` note in the vault. The digest serves
+as a dense proxy that downstream agents (depth investigators, the
+draft orchestrator, critics) can consume without paying the context
+cost of re-reading the original source.
+
+## Pipeline position
+
+You are a leaf subagent available to the orchestrator (Layer 1-4) and
+the depth investigator (Layer 3). Neither layer reads long sources
+optimally: the orchestrator would consume excessive context, the
+depth investigator is scoped to its locus and may miss cross-locus
+substance. You fill that gap by reading ONE source fully on Sonnet's
+1M-token context window.
+
+You do NOT spawn other subagents. If you need something beyond the
+single source you were assigned, report back to the parent agent
+with a specific ask — the parent decides whether to spawn another
+analyst, fetch new sources, or move on.
+
+## Inputs (from the parent agent)
+
+- **research_query**: canonical, verbatim. GOSPEL. Your analysis is
+ scoped to this question — the digest should surface what matters for
+ this specific research_query, not a generic abstract.
+- **source_note_id**: the vault note id of the source you will analyze
+ (e.g., `confronting-capital-punishment-in-china-wikipedia`). You
+ will call `{hpr_path} note show <source_note_id> -j` to read the
+ full body.
+- **output_path**: the markdown file path where you write the analysis
+ body BEFORE calling `note new --body-file` (e.g.,
+ `research/temp/source-analysis-<source_note_id>.md`).
+- **vault_tag**: the run-level corpus tag so the new note is findable
+ alongside its sibling notes.
+
+## Procedure
+
+1. **Check for an existing analysis.** Before writing anything, search:
+ ```bash
+ PYTHONIOENCODING=utf-8 {hpr_path} search "" --tag <vault_tag> --type source-analysis --json
+ ```
+ Then filter for any note whose body contains `[[<source_note_id>]]`.
+ If one exists, report back to the parent — do NOT duplicate.
+
+2. **Read the source.** Pull the full body:
+ ```bash
+ PYTHONIOENCODING=utf-8 {hpr_path} note show <source_note_id> -j
+ ```
+ Hold the full body in your context. Sonnet 1M lets you read up to
+ roughly 750K words before truncation matters. If the source exceeds
+ that (rare — most 500-page PDFs extract to <300K words), report
+ back to the parent with `truncation_warning: true` and analyze
+ what you could read.
+
+3. **Read the research_query again.** Anchor your analysis to what
+ the user actually asked. Not every load-bearing claim in the
+ source matters for this query — you extract for this query
+ specifically.
+
+4. **Write the structured analysis body to `output_path`** using
+ this template (verbatim section headings, preserve ordering):
+
+```markdown
+# Source Analysis — <source title, preserve exact capitalization>
+
+**Original source:** [[<source_note_id>]]
+**Source type:** <paper | PDF | article | transcript | report | book | other>
+**Source word count:** <N>
+**Your judgment:** <one line — what kind of evidence this source contributes to the research_query. E.g., "Quantitative anchor for the 2010-2022 time series", "Methodological critique of the standard approach", "Canonical survey establishing the term's definition".>
+
+*Suggested by [[<source_note_id>]] — source analyst's digest of the full source body*
+
+## Thesis / Central claim
+<2-4 sentences. What the source is arguing. Commit — do not hedge.>
+
+## Methodology / Basis of claims
+<How the source supports its thesis: dataset + specific N, derivation, case study, survey, polemic, literature review, field observation, etc. Name the specific method and its load-bearing assumptions.>
+
+## Key findings / Claims (with specific numbers where present)
+<Enumerated list (1., 2., 3., ...). Preserve exact numbers, thresholds, dates, named mechanisms. Where the specific wording matters, quote 1-3 sentences verbatim with page/section reference if available. Each finding should stand alone — a depth investigator reading only this list should understand what the source contributes.>
+
+## Load-bearing citations / sources this source depends on
+<Which upstream sources this one leans on. Name authors + year + title fragments. This is the "references tree" a depth investigator could chase. If the source depends on non-replicated data or a specific named dataset, flag it.>
+
+## Caveats, limitations, contradictions
+<What the source itself flags as limitation. What internal tensions exist (if the source contradicts itself). Anything a reader should know before citing this as authoritative.>
+
+## Relevance to research_query
+<One paragraph. How does this source inform the specific research_query? Which atomic items from prompt-decomposition (if provided) does it address? If the source doesn't serve the research_query at all, say so explicitly — a clear "this source turned out to be tangential" is a valuable finding.>
+
+## Extracted quotes
+<0-10 direct quotes of 1-3 sentences each, for claims where the exact wording carries argumentative weight that paraphrase would lose. Each quote on its own line, in blockquote format, followed by a short context sentence.>
+```
+
+5. **Create the source-analysis note:**
+ ```bash
+ PYTHONIOENCODING=utf-8 {hpr_path} note new "Source Analysis — <short title>" \\
+ --type source-analysis \\
+ --tag <vault_tag> \\
+ --tag source-analysis \\
+ --body-file <output_path> \\
+ --summary "<2-4 sentence summary: the source's thesis + its contribution to the research_query>" \\
+ --json
+ ```
+
+ The `*Suggested by [[<source_note_id>]]*` line inside the body
+ creates the wiki-link the extractor picks up, so the source
+ note's backlinks view will show this analysis as an incoming
+ link — no separate CLI flag needed.
+
+6. **Report back to the orchestrator.** Include: new note id, source's
+ word count, your analysis's word count, relevance verdict
+ (load-bearing / useful / tangential / not-relevant), any
+ `truncation_warning` flag, and 2-3 of the sharpest findings
+ inline so the orchestrator can decide whether to prioritize this
+ source in the draft.
+
+## Tool lock — why `[Bash, Read, Write]` and NOT `[Task]`
+
+You are a LEAF agent. You cannot spawn other subagents. This prevents:
+- **Recursive cost explosion** (analysts spawning analysts spawning analysts)
+- **Pipeline contract violations** — only the orchestrator decides which sources get analyzed and in what order.
+- **Scope drift** — your job is ONE source, deeply. If you find yourself wanting to fetch another URL or analyze another source, that impulse is a finding to report, not an action to take.
+
+If a source references another source you think is critical, name it
+in `## Load-bearing citations` — the orchestrator will decide whether
+to fetch it and potentially spawn another analyst for it.
+
+## Non-ASCII source text
+
+When the source contains non-ASCII text (Chinese, Japanese, Korean,
+Arabic, etc.), your extracted quotes MUST be copied verbatim from
+the Read tool output. Never retype or transliterate. Downstream
+agents and lint rules expect exact character matches.
+
+## Cost discipline
+
+You run on Sonnet 1M context. A full read of a 60K-word source costs
+roughly $2-5 per spawn. Do not pad: if the source's substantive
+density is low despite its length (e.g., a long transcript that
+repeats itself), your analysis should be correspondingly short. The
+template sections are REQUIRED, but each section's length is
+proportional to the substance actually present.
+
+If the parent agent gives you a source that turns out to be <5000
+words, ABORT early — report "source too short, use fetcher summary
+instead" and do not write an analysis. The analyst is overkill for
+short sources.
+
+## Reporting back
+
+Return a compact status line to the parent:
+- Path to the new source-analysis note
+- Your word count
+- Relevance verdict (load-bearing / useful / tangential / not-relevant)
+- Top 2-3 findings (1 sentence each) for quick parent-agent triage
+- Any caveats the parent should know (truncation, missing context, etc.)
+"""
+
+
+# ---------------------------------------------------------------------------
+# Layer 1 — fetcher. Sonnet-powered research agent with agency to follow
+# leads to primary sources. Fetches assigned URLs + chases citation chains.
# ---------------------------------------------------------------------------
RESEARCHER_AGENT = """\
---
name: hyperresearch-fetcher
description: >
- Use this agent to fetch web URLs into the research base. Delegate to this agent
- whenever you need to fetch one or more URLs with hyperresearch. It runs on a cheap,
- fast model — spawn multiple in parallel for bulk research. Do NOT do URL fetching
- yourself when this agent is available.
-model: haiku
-tools: Bash, Read
+ Research fetcher with primary-source-chasing agency. Fetches assigned URLs,
+ reads and summarizes content, extracts structured claims, then follows
+ citation chains and references to discover and fetch primary sources the
+ secondary sources cite. Runs on Sonnet for better comprehension and
+ judgment. Spawn multiple in parallel for bulk research.
+model: sonnet
+tools: Bash, Read, Write, WebSearch
color: blue
---
-You are a research fetcher. Your job is to fetch URLs and save them to the
-hyperresearch knowledge base using the CLI.
+You are a research fetcher with agency to chase primary sources. Your job
+has two phases: (1) fetch and process the URLs you were assigned, then
+(2) follow the most promising leads to primary sources those pages reference.
+
+## Period-pinned filings (READ FIRST)
+
+When the parent agent's research_query names a specific historical reporting
+period — Q3 2024, FY 2023, "9 months ended September 30, 2024", "as of
+November 17, 2025", a dated event like "March 2024 equity raise" — the
+filing for THAT exact period is almost always load-bearing. Tabular line
+items (segment revenue, EBITDA breakdown, working capital components) only
+exist in the period-pinned filing itself. Earnings-call transcripts narrate
+those numbers in already-rounded form ("revenue grew about 27%"); rubrics
+and serious analyses demand the tabular precision the filing provides.
+
+Rules when the query names a period:
+1. **Fetch the filing for the named period, not the most recent filing.**
+ - SEC: open the EDGAR filing-history page for the issuer
+ (`https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=<id>&type=10-Q`),
+ find the filing whose "Period of Report" matches the named period, and
+ fetch THAT filing's documents page.
+ - Companies House: open the filing-history view
+ (`https://find-and-update.company-information.service.gov.uk/company/<num>/filing-history`),
+ find accounts/confirmation statements with `made up to` matching the
+ named period, and fetch THAT specific document PDF.
+2. **Fetch the underlying PDF or filing document, not the press release
+ that paraphrases it.** SEC documents links live on the filing index page;
+ click through to the actual `.htm` or `.pdf`. Companies House serves
+ accounts as direct PDFs.
+3. **Extract tabular line items.** When the filing has segment revenue,
+ nine-month period figures, gross margin breakdowns, debt schedules, or
+ working capital components, capture them VERBATIM in the `numbers`
+ field of `claims-<note-id>.json` — exact thousands ("$2,062"), exact
+ percentages ("73.09%"), exact dates ("July 18, 2023"). Do NOT round.
+4. **A Q1 2025 10-Q does not satisfy a Q3 2024 ask.** Different reporting
+ periods have different tabular columns. If your assigned URLs point you
+ to the wrong-period filing, surface that mismatch to the parent agent
+ in your report rather than substituting silently.
## Error handling
If you get AUTH_REQUIRED or "Redirected to login page":
-- The browser profile session has expired.
- Tell the parent agent: "Auth expired for this site. User needs to run
'hyperresearch setup' and re-create their login profile."
- Do NOT retry — the session is dead.
@@ -1593,11 +2625,8 @@ PYTHONIOENCODING=utf-8 {hpr_path} fetch "<url>" --tag <topic> -j
### Backlink flag — `--suggested-by`
-When the parent agent tells you "fetch URL X because source note Y suggested
-it", you MUST pass `--suggested-by Y` (and optionally `--suggested-by-reason
-"<short reason>"`) to the fetch command. This creates a wiki-link from the
-new note back to the suggesting source, so the research graph shows which
-source sent you to each URL.
+When fetching a URL that was referenced by a source you already processed,
+pass `--suggested-by <note-id>` to create the citation chain in the vault:
```bash
PYTHONIOENCODING=utf-8 {hpr_path} fetch "<url>" \\
@@ -1607,44 +2636,261 @@ PYTHONIOENCODING=utf-8 {hpr_path} fetch "<url>" \\
-j
```
-The flag can be repeated if multiple notes suggested the same URL. If the
-parent agent did not tell you which note suggested this URL (e.g. you're
-fetching a seed source directly from a search result), omit the flag.
+If you're fetching a seed source directly from the parent agent's URL list
+(not discovered by you), omit the flag.
-### Procedure
+## Phase 1: Fetch assigned URLs
-For each URL you are given:
+For each URL the parent agent gave you:
1. Check if it's already fetched:
- PYTHONIOENCODING=utf-8 {hpr_path} sources check "<url>" -j
+ `PYTHONIOENCODING=utf-8 {hpr_path} sources check "<url>" -j`
-2. If not already fetched, fetch it (with `--suggested-by` if the parent
- told you which note suggested the URL):
- PYTHONIOENCODING=utf-8 {hpr_path} fetch "<url>" --tag <topic> --suggested-by <source-id> --suggested-by-reason "<reason>" -j
+2. If not already fetched, fetch it:
+ `PYTHONIOENCODING=utf-8 {hpr_path} fetch "<url>" --tag <topic> -j`
3. After fetching, read the note content:
- PYTHONIOENCODING=utf-8 {hpr_path} note show <note-id> -j
+ `PYTHONIOENCODING=utf-8 {hpr_path} note show <note-id> -j`
4. **Quality check** — read the content and decide:
- - Is this actually relevant to the research topic? If it's completely off-topic, deprecate it:
- PYTHONIOENCODING=utf-8 {hpr_path} note update <note-id> --status deprecated -j
- - Is the content meaningful (not binary garbage, not a cookie page, not just nav elements)?
- If it's junk, deprecate it and report "junk content" to the parent agent.
- - Is this a duplicate of another source? If so, deprecate the worse copy.
+ - Is this actually relevant to the research topic? If completely off-topic, deprecate it:
+ `PYTHONIOENCODING=utf-8 {hpr_path} note update <note-id> --status deprecated -j`
+ - Is the content meaningful (not junk)? If junk, deprecate it.
+ - Is this a duplicate? If so, deprecate the worse copy.
+
+ **Wikipedia SOURCE HUB rule:** Wikipedia articles are source hubs, never
+ citable sources. Extract references/citations, tag with `source-hub`,
+ and fetch the primary sources in Phase 2.
5. If the content is good, write a real summary and add tags:
- PYTHONIOENCODING=utf-8 {hpr_path} note update <note-id> --summary "<specific summary>" -j
- PYTHONIOENCODING=utf-8 {hpr_path} note update <note-id> --add-tag <specific-tag> -j
+ `PYTHONIOENCODING=utf-8 {hpr_path} note update <note-id> --summary "<specific summary>" -j`
+ `PYTHONIOENCODING=utf-8 {hpr_path} note update <note-id> --add-tag <specific-tag> -j`
+
+ **Summary length is proportional to the source's substantive density.**
+ - **Short/thin:** 1-2 specific sentences.
+ - **Medium:** 1-2 paragraphs with claims, methodology, numbers, mechanisms.
+ - **Long/dense:** 3-6 paragraphs covering thesis, methodology, key findings
+ with specific numbers, load-bearing citations, caveats, contradictions.
+ Quote short passages verbatim when exact wording carries weight.
+
+ **Specificity rule:** "Proves existence/uniqueness of equilibrium in
+ asymmetric first-price auctions via coupled ODE system" NOT "Paper about
+ auctions". Domain nouns, specific mechanisms, preserve numbers.
+
+ **Long source flag:** if >5000 words AND relevant, report prominently
+ to the parent agent for potential `hyperresearch-source-analyst` delegation.
+
+6. **Extract structured claims** to `research/temp/claims-<note-id>.json`:
+
+ ```json
+ {{
+ "claim": "one-sentence falsifiable statement",
+ "stance": "supports|refutes|neutral",
+ "stance_target": "what position this supports/refutes",
+ "evidence_type": "empirical|theoretical|anecdotal|expert-opinion|statistical|legal|historical",
+ "scope_conditions": "geographic, temporal, domain constraints",
+ "quoted_support": "verbatim quote from source, max 2 sentences — THIS IS THE MOST IMPORTANT FIELD, the evidence digest surfaces these quotes directly to the drafter as primary evidence; a claim without a quoted passage is invisible downstream",
+ "numbers": ["specific numbers, thresholds, percentages"],
+ "entities": ["named entities relevant to this claim"],
+ "time_period": "temporal scope if stated",
+ "region": "geographic scope if stated",
+ "confidence": "high|medium|low",
+ "source_note_id": "<note-id>"
+ }}
+ ```
+
+ Caps: short sources 3-8, medium 8-15, long 15-25 claims.
+ No trivial claims. Load-bearing only.
+
+7. **Collect leads.** As you process each source, note every reference,
+ citation, link, or named source that points to PRIMARY evidence:
+ - Academic papers cited in the text (author + title + year)
+ - Government reports or official statistics referenced
+ - Original studies that secondary commentary is built on
+ - Data sources (datasets, databases, official registries)
+ - Named experts whose work is cited but not directly fetched
+
+ Keep a running list of these leads for Phase 2.
+
+## Phase 2: Chase primary sources (MANDATORY — do NOT skip)
+
+**This phase is NON-OPTIONAL.** You MUST execute Phase 2 after finishing
+Phase 1. The audit shows fetchers that skip Phase 2 produce flat-batch
+output with no provenance chains — this directly hurts the pipeline's
+insight and comprehensiveness scores. If you processed 5+ URLs in Phase 1,
+you MUST have collected at least 3 leads. Chase them.
+
+After processing ALL assigned URLs, review your leads list. This is where
+you add real value — secondary sources cite primary evidence, and fetching
+those primaries gives the pipeline higher-authority sources to cite.
+
+1. **Prioritize leads.** From your collected leads, select the **3-8 most
+ promising** based on:
+ - **Authority:** government data, peer-reviewed papers, and official
+ reports over blog commentary or news articles
+ - **Specificity:** sources with exact data, methods, or thresholds
+ over general overviews
+ - **Citation frequency:** sources cited by multiple of your assigned
+ URLs are likely load-bearing
+ - **Relevance:** directly addresses the research_query, not tangential
+
+2. **Find and fetch the primary sources.** For each priority lead:
+ - If you have a direct URL from the citation, fetch it with the
+ hyperresearch CLI (same commands as Phase 1):
+ ```
+ PYTHONIOENCODING=utf-8 {hpr_path} sources check "<url>" -j
+ PYTHONIOENCODING=utf-8 {hpr_path} fetch "<url>" --tag <topic> --suggested-by <note-id-that-cited-it> --suggested-by-reason "cited as primary source" -j
+ ```
+ - If you only have author + title (no URL), use WebSearch to locate it:
+ search for `"<author> <title> <year>"` or `"<title> filetype:pdf"`
+ - For academic papers: try these URL patterns directly:
+ - arXiv: `https://arxiv.org/abs/<id>` or search arXiv
+ - DOI: `https://doi.org/<doi>` — fetch the DOI URL directly
+ - Semantic Scholar: search the API
+ - Once you have the URL, fetch it with `{hpr_path} fetch` as above.
+ Always use `--suggested-by` pointing to the note that cited this
+ source — this builds the citation chain in the vault graph.
+
+3. **Process each discovered source** with the same full procedure as
+ Phase 1: read the note content with `{hpr_path} note show <id> -j`,
+ quality check, write summary with `{hpr_path} note update`, add tags,
+ and extract structured claims to `research/temp/claims-<note-id>.json`.
+ Primary sources often have the specific numbers and methodological
+ details that secondary commentary paraphrases — extract these precisely.
+
+4. **Cap:** Fetch at most **8 additional primary sources** beyond your
+ assigned URLs. This is targeted enrichment. If you find more promising
+ leads than you can fetch, report the unfetched leads to the parent
+ agent.
+
+## Reporting back
+
+Tell the parent agent:
+- Note IDs and summaries for all fetched sources (assigned + discovered)
+- Quality verdicts (good/junk/off-topic) for each
+- How many primary sources you discovered and fetched in Phase 2
+- Any unfetched leads that looked promising but exceeded your cap
+- Any long sources (>5000 words) flagged for source-analyst delegation
+- Total note count added to the vault
+
+If a fetch fails (JUNK_CONTENT, FETCH_ERROR, AUTH_REQUIRED), report the
+failure and move on. Do NOT stop on first failure — try all URLs.
+
+Keep responses focused — facts and findings, not commentary.
+"""
+
+
+CORPUS_CRITIC_AGENT = """\
+---
+name: hyperresearch-corpus-critic
+description: >
+ Use this agent in Layer 3.7 of the hyperresearch deep research pipeline. Reads the full
+ corpus (width + depth sources), the contradiction graph, the loci,
+ and comparisons.md. Verifies committed positions against original
+ source text via note show, then asks: "what source, if found, would
+ overturn the current direction?" Outputs a targeted fetch list of 3-8
+ high-leverage missing sources. Runs on Sonnet. Spawn ONCE before
+ drafting, after Layer 3.5 comparisons.
+model: sonnet
+tools: Bash, Read, Write
+color: teal
+---
+
+You are the corpus critic. Your job: BEFORE the draft is written,
+identify the most dangerous gaps in the evidence base. You ask one
+question of every committed position and every consensus claim:
+"What source, if it existed, would overturn this?"
+
+## Pipeline position
+
+You are **Layer 3.7** — between cross-locus comparisons (Layer 3.5) and
+the draft (Layer 4). Everything gathered so far is available: width
+corpus, depth interim notes with committed positions, contradiction
+graph, comparisons.md. After you return, the orchestrator runs a
+targeted fetch wave to fill the gaps you identified, THEN proceeds
+to drafting.
+
+## Inputs (from the parent agent)
+
+- **research_query**: verbatim. GOSPEL.
+- **corpus_tag**: vault tag for searching.
+- **comparisons_path**: `research/comparisons.md`
+- **loci_path**: `research/loci.json`
+- **output_path**: `research/corpus-critic-gaps.json`
+
+## Procedure
- The summary must be specific — "Proves existence/uniqueness of equilibrium in asymmetric first-price auctions via coupled ODE system" NOT "Paper about auctions". Add multiple relevant tags based on the actual content.
+1. **Read comparisons.md.** For each committed position and cross-locus
+ tension:
+ - Read the investigator's "What would change this position" field
+ - Name the specific counter-evidence that would weaken the position
+ - Name the specific source TYPE that would strengthen it
+ - Example: "Position: FRMCS will be industry standard by 2030.
+ Overturning source: a deployment timeline study showing delays
+ past 2035. Strengthening source: vendor commitment data showing
+ 95%+ adoption plans."
+
+2. **Verify positions against original sources.** For each committed
+ position in comparisons.md, identify the 2-3 source note IDs that
+ the position rests on. Read them in full:
+ ```bash
+ PYTHONIOENCODING=utf-8 {hpr_path} note show <id1> <id2> <id3> -j
+ ```
+ Check: does the original source actually support the committed
+ position as stated? Summaries and interim notes can drift from
+ what the source really said. If the full text reveals a caveat,
+ scope limitation, or contradicting detail that the position ignores,
+ flag that as a gap — the draft would inherit the error.
+
+3. **Read consensus claims** from `research/temp/consensus-claims.json`
+ (if it exists). For each high-confidence consensus:
+ - Is there a plausible dissenting source you haven't looked for?
+ - Is the consensus supported by INDEPENDENT sources, or by
+ derivative sources tracing to one upstream report? Check
+ `research/temp/redundancy-audit.md` if it exists.
+
+4. **Check the redundancy audit** (`research/temp/redundancy-audit.md`).
+ Are any positions supported only by derivative sources? That support
+ is fragile — flag it.
+
+5. **Search the vault** for existing sources that might already contain
+ overturning evidence that the investigators missed:
+ ```bash
+ PYTHONIOENCODING=utf-8 {hpr_path} search "<adversarial query>" --tag <corpus_tag> -j
+ ```
-6. Report back: the note ID, title, word count, your summary, quality verdict (good/junk/off-topic), AND a list of links found in the content that look like they lead to primary sources, references, related material, or deeper content. The parent agent will decide what to pursue.
+6. **Produce output** at `output_path`:
+ ```json
+ {{
+ "gaps": [
+ {{
+ "type": "overturning|strengthening|independent-verification",
+ "target_position": "which claim/position this source would test",
+ "search_queries": ["2-3 specific search queries to find this source"],
+ "source_type": "academic|government|industry|investigative",
+ "priority": "critical|high|medium",
+ "rationale": "why finding this source matters for the draft"
+ }}
+ ]
+ }}
+ ```
-If a fetch fails (JUNK_CONTENT, FETCH_ERROR, AUTH_REQUIRED), report the failure and move on to the next URL. Do NOT stop on first failure — try all URLs.
+ **Cap: 3-8 gaps.** Only `critical` and `high` priority. Do not
+ identify gaps for tangential topics — every gap must serve the
+ research_query.
-If given multiple URLs and fetching works, process them sequentially. Report results for each.
+## Rules
-Keep your responses short — just the facts. The parent agent will synthesize.
+- Every gap must be **actionable** — specific enough to turn into a
+ search query that a fetcher can execute.
+- **Overturning sources are highest priority.** The draft needs to
+ either find them (and adjust the committed position) or confirm they
+ don't exist (and commit harder).
+- Do NOT flag things the width sweep already covered. Check the vault
+ first.
+- Do NOT re-litigate the investigators' positions. Your job is to find
+ what's MISSING from the evidence base, not to disagree with how it
+ was interpreted.
"""
@@ -1695,26 +2941,33 @@ if (vault) {{
def install_hooks(vault_root: Path, hpr_path: str = "hyperresearch") -> list[str]:
"""Install the Claude Code hook + skills + subagents. Returns list of actions taken.
- Layercake roster (as of v0.7.0):
- fetcher (Layer 1, 3), loci-analyst (Layer 2), depth-investigator (Layer 3),
- dialectic-critic + depth-critic + width-critic (Layer 5),
+ Hyperresearch roster (as of v7):
+ fetcher (Layer 1, 3, 4), loci-analyst (Layer 2), depth-investigator (Layer 3),
+ source-analyst (on-demand, 1M context), corpus-critic (Layer 3.7),
+ draft-orchestrator (Layer 4, 3x parallel),
+ dialectic-critic + depth-critic + width-critic + instruction-critic (Layer 5),
patcher (Layer 6), polish-auditor (Layer 7).
"""
actions = []
for installer in (
lambda: _install_claude_hook(vault_root, hpr_path),
- lambda: _install_research_skill(vault_root),
- lambda: _install_layercake_skill(vault_root),
+ lambda: _install_hyperresearch_skill(vault_root),
+ lambda: _install_hyperresearch_step_skills(vault_root),
lambda: _install_researcher_agent(vault_root, hpr_path),
lambda: _install_loci_analyst_agent(vault_root, hpr_path),
lambda: _install_depth_investigator_agent(vault_root, hpr_path),
+ lambda: _install_source_analyst_agent(vault_root, hpr_path),
lambda: _install_dialectic_critic_agent(vault_root, hpr_path),
lambda: _install_instruction_critic_agent(vault_root, hpr_path),
lambda: _install_depth_critic_agent(vault_root, hpr_path),
lambda: _install_width_critic_agent(vault_root, hpr_path),
lambda: _install_patcher_agent(vault_root, hpr_path),
lambda: _install_polish_auditor_agent(vault_root, hpr_path),
+ lambda: _install_readability_reformatter_agent(vault_root, hpr_path),
+ lambda: _install_corpus_critic_agent(vault_root, hpr_path),
+ lambda: _install_draft_orchestrator_agent(vault_root, hpr_path),
+ lambda: _install_synthesizer_agent(vault_root, hpr_path),
lambda: _prune_retired_agents(vault_root),
):
result = installer()
@@ -1794,7 +3047,7 @@ def _install_researcher_agent(vault_root: Path, hpr_path: str) -> str | None:
hpr_posix = hpr_path.replace("\\", "/")
content = RESEARCHER_AGENT.format(hpr_path=hpr_posix)
return _write_agent_file(
- vault_root, "hyperresearch-fetcher.md", content, "haiku fetcher"
+ vault_root, "hyperresearch-fetcher.md", content, "sonnet fetcher (primary-source chasing)"
)
@@ -1806,6 +3059,17 @@ def _install_loci_analyst_agent(vault_root: Path, hpr_path: str) -> str | None:
)
+def _install_source_analyst_agent(vault_root: Path, hpr_path: str) -> str | None:
+ hpr_posix = hpr_path.replace("\\", "/")
+ content = SOURCE_ANALYST_AGENT.format(hpr_path=hpr_posix)
+ return _write_agent_file(
+ vault_root,
+ "hyperresearch-source-analyst.md",
+ content,
+ "sonnet source analyst (1M context)",
+ )
+
+
def _install_depth_investigator_agent(vault_root: Path, hpr_path: str) -> str | None:
hpr_posix = hpr_path.replace("\\", "/")
content = DEPTH_INVESTIGATOR_AGENT.format(hpr_path=hpr_posix)
@@ -1870,6 +3134,17 @@ def _install_patcher_agent(vault_root: Path, hpr_path: str) -> str | None:
)
+def _install_synthesizer_agent(vault_root: Path, hpr_path: str) -> str | None:
+ # Synthesizer prompt does not reference hpr_path; tool-locked to [Read, Write]
+ content = SYNTHESIZER_AGENT
+ return _write_agent_file(
+ vault_root,
+ "hyperresearch-synthesizer.md",
+ content,
+ "opus synthesizer (Read+Write only, two-pass)",
+ )
+
+
def _install_polish_auditor_agent(vault_root: Path, hpr_path: str) -> str | None:
content = POLISH_AUDITOR_AGENT.format(
scaffold_only_sections=_render_scaffold_only_bullets(indent="- "),
@@ -1882,7 +3157,54 @@ def _install_polish_auditor_agent(vault_root: Path, hpr_path: str) -> str | None
)
-# Files that were installed by the pre-layercake architecture. We prune them
+def _install_readability_reformatter_agent(vault_root: Path, hpr_path: str) -> str | None:
+ """Install the readability recommender (formerly the reformatter).
+
+ Despite the function name (kept for backward compatibility with the
+ install loop), this writes the recommender agent — Read+Write
+ tool-locked, produces JSON recommendations the orchestrator
+ selectively applies. The old reformatter (Read+Edit, applied changes
+ directly) is replaced. The old `hyperresearch-readability-reformatter.md`
+ file is removed if present, and the new agent installs at
+ `hyperresearch-readability-recommender.md`.
+ """
+ content = READABILITY_REFORMATTER_AGENT # already updated to recommender body
+
+ # Prune the old agent filename if it exists from a prior install
+ old_path = vault_root / ".claude" / "agents" / "hyperresearch-readability-reformatter.md"
+ if old_path.exists():
+ old_path.unlink()
+
+ return _write_agent_file(
+ vault_root,
+ "hyperresearch-readability-recommender.md",
+ content,
+ "opus readability recommender (Read+Write — writes JSON recommendations only)",
+ )
+
+
+def _install_corpus_critic_agent(vault_root: Path, hpr_path: str) -> str | None:
+ content = CORPUS_CRITIC_AGENT.replace("{hpr_path}", hpr_path)
+ return _write_agent_file(
+ vault_root,
+ "hyperresearch-corpus-critic.md",
+ content,
+ "sonnet corpus critic (Layer 3.7)",
+ )
+
+
+def _install_draft_orchestrator_agent(vault_root: Path, hpr_path: str) -> str | None:
+ hpr_posix = hpr_path.replace("\\", "/")
+ content = DRAFT_ORCHESTRATOR_AGENT.replace("{hpr_path}", hpr_posix)
+ return _write_agent_file(
+ vault_root,
+ "hyperresearch-draft-orchestrator.md",
+ content,
+ "opus draft sub-orchestrator (Layer 4)",
+ )
+
+
+# Files that were installed by the pre-hyperresearch architecture. We prune them
# on install so upgrading vaults don't keep stale agent definitions that
# reference missing skills / dead protocols.
_RETIRED_AGENT_FILES: tuple[str, ...] = (
@@ -1895,15 +3217,25 @@ _RETIRED_AGENT_FILES: tuple[str, ...] = (
_RETIRED_SKILL_DIRS: tuple[str, ...] = (
"research-ensemble",
+ "research-layercake", # superseded by /hyperresearch alias
+)
+
+# V1 modality files — left over inside .claude/skills/hyperresearch/ on
+# vaults that were installed before the V8 alias-based entry skill.
+_RETIRED_HYPERRESEARCH_FILES: tuple[str, ...] = (
+ "SKILL-collect.md",
+ "SKILL-synthesize.md",
+ "SKILL-compare.md",
+ "SKILL-forecast.md",
)
def _prune_retired_agents(vault_root: Path) -> str | None:
- """Delete agent files + skill dirs from the pre-layercake roster.
+ """Delete agent files + skill dirs from the pre-hyperresearch roster.
Running this on a fresh vault is a no-op. On an upgraded vault, it removes
- the 5 retired agent .md files and the old /research-ensemble skill dir so
- the installed state matches the current architecture.
+ retired agent .md files and the old /research-ensemble + /research-layercake
+ skill dirs so the installed state matches the current architecture.
"""
pruned: list[str] = []
@@ -1930,20 +3262,21 @@ def _prune_retired_agents(vault_root: Path) -> str | None:
p.rmdir()
pruned.append(f"skill dir {name}")
+ # V1 modality files (SKILL-collect.md etc.) left inside the
+ # /hyperresearch skill dir from the old multi-file install layout.
+ hpr_dir = skills_dir / "hyperresearch"
+ if hpr_dir.is_dir():
+ for name in _RETIRED_HYPERRESEARCH_FILES:
+ p = hpr_dir / name
+ if p.exists():
+ p.unlink()
+ pruned.append(f"file hyperresearch/{name}")
+
if not pruned:
return None
return "Pruned retired: " + ", ".join(pruned)
-_SKILL_FILES = [
- ("research.md", "SKILL.md"),
- ("research-collect.md", "SKILL-collect.md"),
- ("research-synthesize.md", "SKILL-synthesize.md"),
- ("research-compare.md", "SKILL-compare.md"),
- ("research-forecast.md", "SKILL-forecast.md"),
-]
-
-
def _read_skill_source(src_name: str) -> str | None:
"""Read a skill file from package resources, falling back to source tree."""
import importlib.resources
@@ -1961,65 +3294,116 @@ def _read_skill_source(src_name: str) -> str | None:
return None
-def _install_research_skill(vault_root: Path) -> str | None:
- """Install the /research skill and all modality skill files for Claude Code.
+def _install_hyperresearch_skill(vault_root: Path) -> str | None:
+ """Install the entry skill as both /hyperresearch and /research.
+
+ Two skill directories are written from the single `hyperresearch.md`
+ source. The /research copy has its `name:` frontmatter rewritten so
+ Claude Code registers it as an independent slash-command trigger.
+ Both directories contain identical step instructions — they are
+ aliases for the same V8 pipeline. The 16 step skills are installed
+ separately by `_install_hyperresearch_step_skills`.
+ """
+ source = _read_skill_source("hyperresearch.md")
+ if source is None:
+ return None
+
+ aliases = [
+ ("hyperresearch", source),
+ ("research", source.replace("name: hyperresearch", "name: research", 1)),
+ ]
+
+ written: list[str] = []
+ for alias, content in aliases:
+ skill_dir = vault_root / ".claude" / "skills" / alias
+ skill_dir.mkdir(parents=True, exist_ok=True)
+ dest_path = skill_dir / "SKILL.md"
+ if dest_path.exists() and dest_path.read_text(encoding="utf-8") == content:
+ continue
+ dest_path.write_text(content, encoding="utf-8")
+ written.append(f"/{alias}")
+
+ if not written:
+ return None
+ return f"Claude Code: entry skill installed ({', '.join(written)} triggers)"
+
+
+_HYPERRESEARCH_STEP_SKILLS = [
+ "hyperresearch-1-decompose",
+ "hyperresearch-2-width-sweep",
+ "hyperresearch-3-contradiction-graph",
+ "hyperresearch-4-loci-analysis",
+ "hyperresearch-5-depth-investigation",
+ "hyperresearch-6-cross-locus-reconcile",
+ "hyperresearch-7-source-tensions",
+ "hyperresearch-8-corpus-critic",
+ "hyperresearch-9-evidence-digest",
+ "hyperresearch-10-triple-draft",
+ "hyperresearch-11-synthesize",
+ "hyperresearch-12-critics",
+ "hyperresearch-13-gap-fetch",
+ "hyperresearch-14-patcher",
+ "hyperresearch-15-polish",
+ "hyperresearch-16-readability-audit",
+]
+
+
+def _install_hyperresearch_step_skills(vault_root: Path) -> str | None:
+ """Install the 16 V8 step skills, each as its own Claude Code skill directory.
+
+ Each step skill lives at `.claude/skills/hyperresearch-N-name/SKILL.md` and is
+ invocable via the Skill tool. The orchestrator (loaded via /hyperresearch)
+ invokes each step skill in sequence per the tier routing table. This
+ decomposition solves the V7 context-compaction problem: each step's
+ procedure is loaded fresh into context only at the moment it's needed.
- 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.
+ Also prunes any stale `hyperresearch-*` skill directories (e.g. from a prior
+ V8 layout where steps were numbered differently) so the user doesn't see
+ obsolete entries in their skill list.
"""
- skill_dir = vault_root / ".claude" / "skills" / "hyperresearch"
- skill_dir.mkdir(parents=True, exist_ok=True)
+ skills_root = vault_root / ".claude" / "skills"
+ skills_root.mkdir(parents=True, exist_ok=True)
- expected = {dest_name for _, dest_name in _SKILL_FILES}
+ expected = set(_HYPERRESEARCH_STEP_SKILLS)
installed: list[str] = []
+ pruned: list[str] = []
- for src_name, dest_name in _SKILL_FILES:
+ for skill_name in _HYPERRESEARCH_STEP_SKILLS:
+ src_name = f"{skill_name}.md"
content = _read_skill_source(src_name)
if content is None:
continue
- dest_path = skill_dir / dest_name
+ skill_dir = skills_root / skill_name
+ skill_dir.mkdir(parents=True, exist_ok=True)
+ dest_path = skill_dir / "SKILL.md"
+
if dest_path.exists() and dest_path.read_text(encoding="utf-8") == content:
continue
dest_path.write_text(content, encoding="utf-8")
- installed.append(dest_name)
+ installed.append(skill_name)
- pruned: list[str] = []
- for existing in skill_dir.glob("SKILL*.md"):
- if existing.name not in expected:
- existing.unlink()
- pruned.append(existing.name)
+ # Prune stale skill dirs: any hyperresearch-* not in current roster, plus
+ # any leftover layercake-* dirs from the pre-rename install layout.
+ for child in skills_root.iterdir():
+ if not child.is_dir():
+ continue
+ is_stale_hpr = child.name.startswith("hyperresearch-") and child.name not in expected
+ is_legacy_layercake = child.name.startswith("layercake-")
+ if not (is_stale_hpr or is_legacy_layercake):
+ continue
+ for f in child.iterdir():
+ f.unlink()
+ child.rmdir()
+ pruned.append(child.name)
if not installed and not pruned:
return None
parts: list[str] = []
if installed:
- parts.append(", ".join(installed))
+ parts.append(f"{len(installed)} step skills: {', '.join(installed)}")
if pruned:
- parts.append("pruned: " + ", ".join(pruned))
- return f"Claude Code: .claude/skills/hyperresearch/ ({'; '.join(parts)})"
-
-
-def _install_layercake_skill(vault_root: Path) -> str | None:
- """Install the /research-layercake skill as its own Claude Code skill directory.
-
- Must live at `.claude/skills/research-layercake/SKILL.md` (NOT as a sibling
- inside `.claude/skills/hyperresearch/`) so Claude Code registers
- `/research-layercake` as a real slash-command trigger via the skill's
- `name: research-layercake` frontmatter.
- """
- skill_dir = vault_root / ".claude" / "skills" / "research-layercake"
- skill_dir.mkdir(parents=True, exist_ok=True)
-
- content = _read_skill_source("research-layercake.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-layercake/SKILL.md (/research-layercake trigger)"
+ parts.append(f"pruned: {', '.join(pruned)}")
+ return f"Claude Code: .claude/skills/hyperresearch-N-*/SKILL.md ({'; '.join(parts)})"
diff --git a/src/hyperresearch/core/migrations.py b/src/hyperresearch/core/migrations.py
index 9dd3693..2a86e0d 100644
--- a/src/hyperresearch/core/migrations.py
+++ b/src/hyperresearch/core/migrations.py
@@ -28,7 +28,7 @@ def _migrate_v7_interim_note_type(conn: sqlite3.Connection) -> None:
"""Add 'interim' to the notes.type CHECK constraint.
SQLite can't alter a CHECK constraint in place — we rebuild the table.
- Layercake Layer 3 depth-investigator writes type='interim' notes, so
+ Hyperresearch step 3 depth-investigator writes type='interim' notes, so
pre-v7 vaults would reject those on sync.
"""
# Cheap pre-check: if the table already accepts 'interim', skip.
@@ -92,6 +92,72 @@ def _migrate_v7_interim_note_type(conn: sqlite3.Connection) -> None:
""")
+def _migrate_v8_source_analysis_note_type(conn: sqlite3.Connection) -> None:
+ """Add 'source-analysis' to the notes.type CHECK constraint.
+
+ Same pattern as v7: SQLite can't alter a CHECK in place, so we rebuild
+ the table when the existing one rejects the new type. Pre-v8 vaults
+ would fail on sync once the source-analyst subagent starts writing
+ type='source-analysis' notes.
+ """
+ try:
+ with conn:
+ conn.execute("SAVEPOINT check_source_analysis_type")
+ try:
+ conn.execute(
+ "INSERT INTO notes (id, title, path, type, created) "
+ "VALUES ('__migrate_probe_v8__', 'probe', '__migrate_probe_v8__', "
+ "'source-analysis', '1970-01-01T00:00:00Z')"
+ )
+ conn.execute("DELETE FROM notes WHERE id = '__migrate_probe_v8__'")
+ conn.execute("RELEASE check_source_analysis_type")
+ return # already compatible
+ except sqlite3.IntegrityError:
+ conn.execute("ROLLBACK TO check_source_analysis_type")
+ conn.execute("RELEASE check_source_analysis_type")
+ except sqlite3.OperationalError:
+ pass
+
+ conn.executescript("""
+ CREATE TABLE notes_v8 (
+ id TEXT PRIMARY KEY,
+ title TEXT NOT NULL,
+ path TEXT NOT NULL UNIQUE,
+ status TEXT NOT NULL DEFAULT 'draft'
+ CHECK (status IN ('draft','review','evergreen','stale','deprecated','archive')),
+ type TEXT NOT NULL DEFAULT 'note'
+ CHECK (type IN ('note','raw','index','moc','interim','source-analysis')),
+ tier TEXT
+ CHECK (tier IS NULL OR tier IN ('ground_truth','institutional','practitioner','commentary','unknown')),
+ content_type TEXT
+ CHECK (content_type IS NULL OR content_type IN ('paper','docs','article','blog','forum','dataset','policy','code','book','transcript','review','unknown')),
+ source TEXT,
+ parent TEXT,
+ deprecated INTEGER NOT NULL DEFAULT 0,
+ reviewed TEXT,
+ expires TEXT,
+ word_count INTEGER NOT NULL DEFAULT 0,
+ summary TEXT,
+ created TEXT NOT NULL,
+ updated TEXT,
+ file_mtime REAL NOT NULL DEFAULT 0,
+ content_hash TEXT NOT NULL DEFAULT '',
+ synced_at TEXT NOT NULL DEFAULT ''
+ );
+ """)
+ old_cols = {row[1] for row in conn.execute("PRAGMA table_info(notes)")}
+ new_cols = {row[1] for row in conn.execute("PRAGMA table_info(notes_v8)")}
+ shared = sorted(old_cols & new_cols)
+ col_list = ", ".join(shared)
+ conn.execute(
+ f"INSERT INTO notes_v8 ({col_list}) SELECT {col_list} FROM notes"
+ )
+ conn.executescript("""
+ DROP TABLE notes;
+ ALTER TABLE notes_v8 RENAME TO notes;
+ """)
+
+
MIGRATIONS: dict[int, str | Callable[[sqlite3.Connection], None]] = {
2: """
CREATE TABLE IF NOT EXISTS tag_aliases (
@@ -135,6 +201,7 @@ CREATE INDEX IF NOT EXISTS idx_assets_type ON assets(type);
""",
6: _migrate_v6_tier_content_type,
7: _migrate_v7_interim_note_type,
+ 8: _migrate_v8_source_analysis_note_type,
}
diff --git a/src/hyperresearch/models/note.py b/src/hyperresearch/models/note.py
index 5a78f64..5ed66fb 100644
--- a/src/hyperresearch/models/note.py
+++ b/src/hyperresearch/models/note.py
@@ -23,7 +23,8 @@ class NoteType(StrEnum):
RAW = "raw"
INDEX = "index"
MOC = "moc"
- INTERIM = "interim" # layercake depth-investigator output (Layer 3)
+ INTERIM = "interim" # hyperresearch depth-investigator output (Layer 3)
+ SOURCE_ANALYSIS = "source-analysis" # deep single-source analytical digest
class Tier(StrEnum):
diff --git a/src/hyperresearch/skills/hyperresearch-1-decompose.md b/src/hyperresearch/skills/hyperresearch-1-decompose.md
new file mode 100644
index 0000000..4e16ce0
--- /dev/null
+++ b/src/hyperresearch/skills/hyperresearch-1-decompose.md
@@ -0,0 +1,175 @@
+---
+name: hyperresearch-1-decompose
+description: >
+ Step 1 of the hyperresearch V8 pipeline. Decomposes the canonical research
+ query into atomic items, classifies pipeline_tier and response_format,
+ and produces the coverage matrix that downstream steps depend on. The
+ required_section_headings field this step produces is the single
+ highest-leverage input for instruction-following scores. Invoked via
+ Skill tool from the entry skill (hyperresearch).
+---
+
+# Step 1 — Prompt decomposition
+
+**Tier gate:** Runs for ALL tiers. This step also classifies the tier itself.
+
+**Goal:** before any research happens, decompose the user's prompt into its atomic items. This artifact is read by the instruction-critic in step 11 and by the draft sub-orchestrators in step 10 to make sure the pipeline doesn't drift from what was actually asked.
+
+**Why this step exists:** the single dimension where the pipeline has the widest variance is whether the draft structurally mirrors the prompt. When the prompt asks "for each significant character, describe techniques / arcs / fate" and the draft produces per-character sections with those three fields in order — that's a structural match, high instruction-following. When the prompt asks the same thing and the draft organizes around thematic analysis — that's a structural mismatch, even if every fact is in there. The decomposition makes the structural requirement explicit, in writing, BEFORE drafting.
+
+---
+
+## Recover state
+
+The orchestrator's bootstrap step (in the entry skill) has already produced:
+- `research/scaffold.md` — vault_tag, modality, wrapper requirements
+- `research/query-<vault_tag>.md` — canonical research query (GOSPEL)
+
+Read both before starting. The vault_tag is in the scaffold's "Run config" section.
+
+---
+
+## Procedure
+
+1. **Re-read the canonical research query** end to end (`research/query-<vault_tag>.md`).
+
+2. **Walk through it and extract every atomic item** — anything that's a discrete thing the prompt named. These fall into categories:
+ - **Sub-questions** — explicit or implicit questions the draft must answer ("What cues influence this?" → atomic: "cues influencing X")
+ - **Named entities / categories** — every character, product, company, concept, time period, etc. the prompt names by name
+ - **Required formats** — "mind map", "ranked list", "FAQ", "tabular", "scenario matrix", etc.
+ - **Required sections** — "include X section", "end with Y", "begin with Z"
+ - **Time horizons** — forward-looking spans: "through 2027", "next 12 months", "historical through 2010-present"
+ - **Time periods (historical, period-pinned)** — backward-looking specific reporting periods that have a primary-source filing somewhere: "Q3 2024", "FY 2023", "9 months ended September 30, 2024", "as of November 17, 2025", "March 2024 equity raise". Different from time_horizons. Extract every one — they drive period-targeted searches in step 2 and a primary-source-coverage check in step 8. **Failing to extract these is the #1 cause of "agent had the topic right but missed the rubric's exact figures"**: the answer lives in the period-pinned filing the agent never fetched (10-Q, 10-K, statutory accounts, regulatory disclosure).
+ - **Scope conditions** — "for non-academic contexts", "under SIL-4 constraints"
+
+3. **Produce `required_section_headings`.** This is the single highest-leverage field for instruction-following scores. Ordered array of literal H2 heading strings the draft MUST emit in order. **Never leave this array empty** — an empty heading contract means the drafter invents its own structure, which systematically scores lower on IF because it never matches the evaluator's structural expectations. Population rule:
+ - If the prompt contains enumerated asks (regex `\b\d[.\)]` such as "1)", "1." or leading phrase "List X, Y, Z" / "cover the following:"), produce one entry per enumerated item, in prompt order, with the prompt's verbatim noun-phrase as the heading slug.
+ - If the prompt names N entities in a list and asks to "discuss", "analyze", "describe", or "evaluate" each, produce one heading per entity.
+ - **Otherwise (narrative prompts):** generate headings from the sub-questions you extracted in step 2. Each sub-question becomes one H2 heading, phrased as a declarative topic ("## 1. Historical Context and Evolution", "## 2. Key Mechanisms and Drivers", etc.). For open-ended prompts ("Write about X"), derive 4-7 headings from the topic's natural analytical structure: background/context → core analysis (1-3 sections mapped to sub-questions) → comparative analysis → implications/future outlook. The headings don't need to quote the prompt verbatim, but they MUST cover every sub-question from step 2.
+
+ Example (prompt: "Your report should: 1) List major manufacturers... 2) Include images... 3) Analyze primary use cases... 4) Investigate market penetration..."):
+ ```json
+ "required_section_headings": [
+ "## 1. Major Manufacturers, Device Models, and Configurations",
+ "## 2. Images of Representative Devices",
+ "## 3. Primary Use Cases and Deployment Scenarios",
+ "## 4. Regional Market Analysis"
+ ]
+ ```
+
+4. **Write `research/prompt-decomposition.json`:**
+
+```json
+{
+ "sub_questions": [
+ "What is the specific question this addresses?",
+ "..."
+ ],
+ "entities": [
+ {"name": "Bronze Saints", "type": "category", "required_fields": ["techniques", "arcs", "fate"]}
+ ],
+ "required_formats": [
+ "mind map of causal structure",
+ "5-tier support/resistance table"
+ ],
+ "required_sections": [
+ "## Opinionated Synthesis (if wrapper_contract demands it)"
+ ],
+ "required_section_headings": [
+ "## 1. Major Manufacturers, Device Models, and Configurations",
+ "## 2. Images of Representative Devices",
+ "## 3. Primary Use Cases and Deployment Scenarios",
+ "## 4. Regional Market Analysis"
+ ],
+ "time_horizons": ["2010-present", "12-month forward"],
+ "time_periods": [
+ {"period": "Q3 2024", "type": "fiscal-quarter", "primary_source": "10-Q for the quarter ended September 30, 2024", "issuer": "ClearPoint Neuro"},
+ {"period": "FY 2023", "type": "fiscal-year", "primary_source": "10-K for fiscal year ended December 31, 2023", "issuer": "ClearPoint Neuro"},
+ {"period": "March 2024", "type": "event-anchored", "primary_source": "8-K disclosure or press release for March 2024 equity raise", "issuer": "ClearPoint Neuro"}
+ ],
+ "scope_conditions": ["urban rail specifically, not mainline"],
+ "pipeline_tier": "full",
+ "response_format": "argumentative",
+ "citation_style": "inline"
+}
+```
+
+5. **Omit nothing the prompt names explicitly.** List every numbered ask, every named entity, every format cue as a separate atomic item, even if they feel redundant. The instruction-critic catches false-positive atomic items cheaply; it cannot catch false-negatives.
+
+6. **Do NOT include wrapper-contract requirements here** — those live in `research/wrapper_contract.json` separately. The decomposition is ONLY about what the user's actual prompt named.
+
+7. **Classify `pipeline_tier` and `response_format`.**
+
+ **`pipeline_tier`** — how much pipeline to run:
+
+ | Tier | When to use | Signal words / patterns |
+ |------|-------------|------------------------|
+ | `"light"` | Query has a clear, bounded answer. Factual lookup, definition, simple explanation, short how-to, list/catalog, quick comparison. | "What is...", "How do I...", "List the...", "Define...", short prompts (<50 words), single clear question |
+ | `"standard"` | Moderate coverage across a topic. Survey, landscape overview, current-state report, multi-entity comparison, decision support. | "Overview of...", "Compare X and Y", "What's the current state of...", moderate-length prompts, 2-5 sub-questions |
+ | `"full"` | Deep analysis, synthesis of conflicting evidence, defended thesis, literature review, forecast with evidence chains. | "Analyze the impact of...", "Evaluate whether...", multi-paragraph prompts, explicit request for depth/rigor, research-grade questions, contested topics |
+
+ **Default is `"full"`.** When uncertain, tier up. The cost of running extra layers on a simple query is wasted money (~$30); the cost of running too few layers on a complex query is a bad report.
+
+ **`response_format`** — how the output is shaped:
+
+ | Format | When to use | Characteristics |
+ |--------|-------------|----------------|
+ | `"short"` | Direct answer, not a report. | 500–2000 words. 1–5 paragraphs. Tables/lists as needed. No Opinionated Synthesis section. Thesis up front, evidence follows. |
+ | `"structured"` | Coverage across entities/topics. Scannability matters more than argumentative density. | 2000–5000 words. Scannable subsections. Breadth-first. Tables, bullets, visual devices liberally. Survey-style coverage acceptable. |
+ | `"argumentative"` | Defended thesis, deep analysis, evidence-chain reasoning. | 5000–10000 words. Dense thesis-driven prose. "ARGUE, DON'T JUST REPORT" fully active. Required Opinionated Synthesis with all subsections. |
+
+ **The two dimensions are independent.** Most common pairings:
+ - `light` + `short` — factual lookup, definition, simple how-to
+ - `light` + `structured` — list/catalog, quick multi-entity comparison
+ - `standard` + `structured` — survey, landscape overview, decision matrix
+ - `full` + `argumentative` — deep analysis, literature review, forecast (the current default)
+ - `full` + `structured` — comprehensive survey where adversarial depth still matters
+
+ **`citation_style`** — how the final report handles source attribution:
+
+ | Style | When to use | Output |
+ |-------|-------------|--------|
+ | `"inline"` | **Default.** User wants a verifiable research report. | `[N]` inline citations + formatted `## Sources` list. |
+ | `"none"` | Polished expert-analysis with no visible citation apparatus. | No `[N]` markers, no Sources section. |
+
+8. **Coverage matrix self-audit.** Re-read the verbatim query. Walk through it phrase by phrase and extract every **significant noun phrase, proper noun, technical term, and category name**. For each:
+ - Does it map to at least one atomic item in the decomposition?
+ - Is the decomposition's interpretation **as broad as the phrase's natural scope**? (e.g., "SaaS applications" must not be narrowed to "POS SaaS"; "rugged tablets" must not be collapsed into "payment terminals")
+ - If the phrase has multiple plausible referents, does the decomposition cover BOTH readings?
+
+ Write the matrix to `research/temp/coverage-matrix.md`:
+
+ ```markdown
+ ## Coverage Matrix — query phrase → atomic item mapping
+
+ | Query phrase (verbatim) | Mapped atomic item(s) | Scope check | Gap? |
+ |---|---|---|---|
+ | "rugged tablets" | Entity: rugged tablets | OK — full scope | No |
+ | "SaaS applications" | Sub-Q3: SaaS deployment | NARROWED — decomposition says "POS SaaS" but query says "SaaS applications" broadly | **YES** |
+ | "Southeast Asia" | Sub-Q4: Regional market — SEA | OK | No |
+ ```
+
+ **If any row has `Gap? = YES`:** go back and fix the decomposition. Add the missing atomic items, broaden the narrowed scope_conditions, or add missing entities. Then re-run the matrix until every row passes. Do NOT proceed with known gaps — they cascade into missing searches, missing sources, and missing draft sections.
+
+9. **Update the scaffold.** Append a "Tier rationale" subsection to `research/scaffold.md` with a 2-3 sentence justification for the tier classification.
+
+---
+
+## Exit criterion
+
+- `research/prompt-decomposition.json` exists, is valid JSON, every atomic item traces to the research_query
+- `pipeline_tier` + `response_format` + `citation_style` are all set
+- `research/temp/coverage-matrix.md` exists with **zero `Gap? = YES` rows**
+- `research/scaffold.md` includes a Tier rationale subsection
+
+---
+
+## Next step
+
+Return to the entry skill (`hyperresearch`). Read `research/prompt-decomposition.json` to learn the tier, then invoke step 2:
+
+```
+Skill(skill: "hyperresearch-2-width-sweep")
+```
+
+Step 2 runs for ALL tiers.
diff --git a/src/hyperresearch/skills/hyperresearch-10-triple-draft.md b/src/hyperresearch/skills/hyperresearch-10-triple-draft.md
new file mode 100644
index 0000000..e65a18d
--- /dev/null
+++ b/src/hyperresearch/skills/hyperresearch-10-triple-draft.md
@@ -0,0 +1,215 @@
+---
+name: hyperresearch-10-triple-draft
+description: >
+ Step 10 of the hyperresearch V8 pipeline. Orchestrator pre-curates 20-50
+ angle-specific source IDs per draft, then spawns 3 hyperresearch-draft-
+ orchestrator subagents in parallel — each reads its curated list (no
+ vault surveys, no source-fetching) and writes one angle-specific draft.
+ This step ENDS when all 3 drafts are written and validated. Step 11
+ (synthesizer) handles the synthesis-write that produces the final report.
+ For light tier: writes a single draft directly to final_report.md and
+ skips ahead to step 15 (polish). Invoked via Skill tool.
+---
+
+# Step 10 — Triple-draft ensemble (curated lists, parallel writers)
+
+**⚠ CRITICAL ANTI-PATTERN: Writing a single draft for `standard` or `full` tier is a PIPELINE VIOLATION.** In V7 runs, context compaction caused the orchestrator to forget this step's procedure and write a single draft instead of spawning 3 sub-orchestrators. V8 fixes this by loading this skill fresh at the moment it's needed. **If you find yourself about to write `research/notes/final_report.md` directly without spawning 3 `hyperresearch-draft-orchestrator` subagents, STOP. Re-read this skill. Spawn the sub-orchestrators.** (Light tier is the ONE exception — see "Light tier" section below.)
+
+**Tier gate:** Runs for ALL tiers. For `light` tier: write a single draft directly to `research/notes/final_report.md` and skip ahead to step 15 (polish). For `standard` and `full`: run the triple-draft ensemble below — step 11 (synthesizer) will turn the 3 drafts into the final report.
+
+**Goal:** produce THREE independent angle-specific drafts (`draft-{a,b,c}.md`). Step 11 (synthesizer subagent) consumes all three and writes the final report.
+
+---
+
+## Recover state
+
+Read these inputs:
+- `research/scaffold.md` — vault_tag, modality, wrapper requirements
+- `research/prompt-decomposition.json` — atomic items, required_section_headings, response_format, citation_style, pipeline_tier
+- `research/temp/evidence-digest.md` — top claims + verbatim quotes — PRIMARY EVIDENCE LAYER (standard / full only; absent for light)
+- `research/comparisons.md` (full tier) — cross-locus tensions
+- `research/temp/source-tensions.json` (full tier) — expert disagreements
+- `research/temp/coverage-gaps.md` (if exists) — items with weak source coverage
+- Survey vault: `$HPR search "" --tag <vault_tag> -j` for the evidence landscape
+- Modality calibration (from the scaffold's `modality` field):
+ - **collect** — enumerative coverage, per-entity sections with named fields
+ - **synthesize** — defended thesis with evidence chains, interpretive density
+ - **compare** — proportionate per-entity depth + a committed recommendation
+ - **forecast** — predictive claims grounded in past + present, explicit time horizon
+
+---
+
+## Step 10.0 — Read response_format and citation_style
+
+Read `response_format` and `citation_style` from `research/prompt-decomposition.json`. These control the draft shape:
+
+| Format | Target length | Character |
+|--------|-------------|-----------|
+| `"short"` | 500–2000 words / 1500–6000 chars (CJK) | Direct answer, compact |
+| `"structured"` | 2000–5000 words / 6000–15000 chars (CJK) | Scannable, breadth-first |
+| `"argumentative"` | 5000–10000 words / 20000–25000 chars (CJK) | Dense thesis-driven |
+
+**Length discipline:** Target the MIDDLE of the range. Under-length loses on comprehensiveness; over-length dilutes good content.
+
+---
+
+## Light tier ONLY: single-draft path
+
+If `pipeline_tier == "light"`: SKIP step 10.1 — 10.3 below and follow this section instead.
+
+**Light tier writes a single draft directly to `research/notes/final_report.md`.** No subagents, no triple-draft ensemble, no synthesizer.
+
+1. **Read the vault directly.** Light tier has no `evidence-digest.md` (step 9 was skipped). Survey the vault: `$HPR search "" --tag <vault_tag> -j` and pick the 8–15 most relevant non-deprecated notes. Read each one (`$HPR note show <id1> <id2> ... -j`) before writing.
+
+2. **Honor the structural contract.**
+ - Use the literal H2 headings from `required_section_headings` in `research/prompt-decomposition.json`, in order.
+ - Hit the length target from step 10.0's table for the chosen `response_format` (light typically pairs with `short` or `structured`).
+ - Apply the modality calibration from the recover-state list above.
+
+3. **Citations.** If `citation_style == "inline"`: use numbered `[N]` citations and end the report with a `## Sources` section listing each cited note as `[N] Title. URL` (read each cited note's YAML frontmatter for title + URL). If `citation_style == "none"`: no inline citation markers, no Sources section.
+
+4. **Hygiene.** No YAML frontmatter on the final report. No `[[wikilink]]` markers. No pipeline vocabulary in prose ("hyperresearch", "evidence digest", "comparisons.md", "committed reading", etc.). Step 15 (polish) is a backstop, not a license to leak.
+
+5. **Exit and route.** Once `research/notes/final_report.md` is written, return to the entry skill and invoke `Skill(skill: "hyperresearch-15-polish")`. Light tier skips steps 11–14 entirely.
+
+---
+
+## Step 10.1 — Define 3 analytical angles (standard / full tier)
+
+Based on the evidence, tensions, and query, assign each sub-orchestrator a distinct angle. The angles should produce genuinely different drafts — not three versions of the same argument.
+
+**For topics with clear tensions/disagreements:**
+- **Draft A — Strongest-thesis:** take the position best supported by evidence and argue it forcefully.
+- **Draft B — Steelman-contrarian:** take the strongest counter-position seriously. Defend the MINORITY view.
+- **Draft C — Synthesis-reconciler:** argue that both sides capture part of the truth. Focus on BOUNDARY CONDITIONS — when does each side's argument hold?
+
+**For topics without clear tensions (surveys, comparisons, collections):**
+- **Draft A — Breadth-optimized:** widest possible coverage of all atomic items.
+- **Draft B — Depth-optimized:** deeper treatment of the 3-4 most important atomic items.
+- **Draft C — Practitioner-optimized:** organized around actionable recommendations.
+
+Write the 3 angle assignments to `research/temp/draft-angles.md` (for the run log). Each angle: 2-3 sentences describing the analytical direction.
+
+---
+
+## Step 10.2 — Curate per-angle source lists
+
+**Critical step.** Each draft sub-orchestrator does NOT decide what to read. YOU pick the 20-50 most relevant vault notes for each angle and pass them as `must_read_note_ids`. This eliminates wasted vault-survey loops in the sub-orchestrators and forces real differentiation by giving each draft a different evidence base.
+
+1. **List all substantive vault notes:**
+ ```bash
+ $HPR search "" --tag <vault_tag> --json
+ ```
+ Filter to non-deprecated notes. You should have 50-100 candidates.
+
+2. **For each draft (A, B, C), pick 20-50 angle-specific notes.** Use these signals:
+ - **Source-analysis notes** (`type: source-analysis`): high-value, full digests of long sources. Include relevant ones in EVERY draft's list — these are gold.
+ - **Interim notes** (`type: interim`, full tier only): include all of them in EVERY draft's list — these have the committed positions.
+ - **For Draft A (strongest-thesis or breadth):** prefer sources that support the dominant evidence direction. Include any source the evidence digest cites for high-confidence claims.
+ - **For Draft B (steelman-contrarian or depth):** prefer minority-view or methodological-critique sources. Pull from `source-tensions.json` proponents on the contested side. If `contradiction-graph.json` exists, include the lower-quality-evidence side's sources to force the steelman to engage them.
+ - **For Draft C (synthesis or practitioner):** prefer sources with boundary conditions, comparative analyses, or applied case studies. Pull from sources the evidence digest groups under multiple atomic items (cross-cutting sources).
+
+3. **Source overlap is fine.** Drafts can share source IDs — interim notes and key source-analyses should appear in all three lists. Differentiation comes from the angle-specific extras (the 5-15 sources unique to each draft's list).
+
+4. **Cap each list at 50, minimum 20.** For `argumentative` format, lean toward 35-50. For `structured`, lean toward 25-40. For `short`, lean toward 20-30.
+
+5. **Write each list to disk** so the spawn template can reference it:
+ - `research/temp/draft-a-source-list.md`
+ - `research/temp/draft-b-source-list.md`
+ - `research/temp/draft-c-source-list.md`
+
+ Format:
+ ```markdown
+ # Draft A — must_read_note_ids (n=37)
+ Angle: <2-3 sentence angle assignment>
+
+ - <note-id-1>: <one-line summary or title>
+ - <note-id-2>: <one-line summary or title>
+ ...
+ ```
+
+---
+
+## Step 10.3 — Spawn 3 draft sub-orchestrators in parallel
+
+**Spawn 3 `hyperresearch-draft-orchestrator` subagents in ONE message.** This is true parallel execution. Each gets a different `draft_id`, `analytical_angle`, and (CRUCIALLY) a different `must_read_note_ids` array.
+
+**Spawn template:**
+```
+subagent_type: hyperresearch-draft-orchestrator
+prompt: |
+ RESEARCH QUERY (verbatim, gospel):
+ > {{paste research/query-<vault_tag>.md body}}
+
+ QUERY FILE: research/query-<vault_tag>.md
+
+ PIPELINE POSITION: You are one of 3 parallel step 10 sub-orchestrators
+ in the hyperresearch V8 pipeline. After you and the other two return, the
+ main orchestrator runs step 11 (synthesizer subagent) which reads all
+ 3 drafts and writes the final report. Your draft is an INPUT to that
+ synthesis, not the final output.
+
+ YOUR INPUTS:
+ - query_file_path: research/query-<vault_tag>.md
+ - vault_tag: <vault_tag>
+ - draft_id: "a" (or "b" or "c")
+ - output_path: research/temp/draft-a.md (or draft-b.md or draft-c.md)
+ - analytical_angle: "<the 2-3 sentence angle assignment>"
+ - must_read_note_ids: [<paste the IDs from research/temp/draft-<x>-source-list.md, e.g. 30-50 IDs>]
+ - decomposition_path: research/prompt-decomposition.json
+ - evidence_digest_path: research/temp/evidence-digest.md
+ - comparisons_path: research/comparisons.md
+ - source_tensions_path: research/temp/source-tensions.json
+ - response_format: "<short|structured|argumentative>"
+ - citation_style: "<inline|none>"
+ - modality: "<collect|synthesize|compare|forecast>"
+
+ Read every note on must_read_note_ids before writing. Do NOT survey
+ the vault — your reading list is curated. Do NOT fetch new sources.
+ Write your draft from your assigned angle, citing your curated sources.
+```
+
+**CRITICAL: never emit bare text while the 3 sub-orchestrators are running.** They will take 5-15 minutes each. Use this time to think — append notes to `research/temp/orchestrator-notes.md` about the synthesis you'll plan in step 11: what's the strongest thesis emerging across angles? Which atomic items will be contentious? What argumentative beats must the final draft commit to? One vault count check per minute max. Write your thoughts, don't just poll.
+
+---
+
+## Step 10.4 — Validate that all 3 drafts came back
+
+When all 3 sub-orchestrators return:
+
+1. **Confirm all 3 draft files exist:**
+ - `research/temp/draft-a.md`
+ - `research/temp/draft-b.md`
+ - `research/temp/draft-c.md`
+
+2. **Read each sub-orchestrator's report-back.** Each should report:
+ - Path to the draft
+ - Core thesis
+ - How many notes from `must_read_note_ids` it actually read
+ - Strongest argumentative beat
+ - Word/character count
+
+3. **If a draft is missing or trivially short** (under 1000 chars for argumentative, 500 for structured), re-spawn that single sub-orchestrator with the same inputs. Do not proceed to step 11 with fewer than 3 drafts.
+
+4. **Do NOT synthesize the drafts in this step.** Step 11 (the synthesizer subagent) does that. Your only job here is to ensure 3 valid drafts exist.
+
+---
+
+## Exit criterion
+
+**Light tier:**
+- `research/notes/final_report.md` exists, hits the length target from step 10.0, follows `required_section_headings`, and respects `citation_style`.
+
+**Standard / full tier:**
+- All three drafts exist at `research/temp/draft-{a,b,c}.md`
+- Each draft has non-trivial length (1000+ chars argumentative, 500+ structured)
+- Sub-orchestrator report-backs are captured (you can paraphrase them in `research/temp/orchestrator-notes.md` for the synthesis plan you'll write in step 11)
+
+---
+
+## Next step
+
+Return to the entry skill (`hyperresearch`). Tier-based routing:
+
+- **light tier:** You already wrote `research/notes/final_report.md` directly. Skip steps 11-14 (no synthesis, no critics, no patcher) and invoke `Skill(skill: "hyperresearch-15-polish")`.
+- **standard / full tier:** Invoke `Skill(skill: "hyperresearch-11-synthesize")`.
diff --git a/src/hyperresearch/skills/hyperresearch-11-synthesize.md b/src/hyperresearch/skills/hyperresearch-11-synthesize.md
new file mode 100644
index 0000000..28d17a3
--- /dev/null
+++ b/src/hyperresearch/skills/hyperresearch-11-synthesize.md
@@ -0,0 +1,241 @@
+---
+name: hyperresearch-11-synthesize
+description: >
+ Step 11 of the hyperresearch V8 pipeline. Reads the 3 angle-specific drafts
+ from step 10, spot-checks factual conflicts, writes a synthesis plan +
+ outline, then spawns ONE hyperresearch-synthesizer subagent (Read+Write
+ tool-locked) that writes the final report in TWO passes — pass 1 rough
+ integrated draft, pass 2 voice/redundancy/length cleanup. Skipped for
+ light tier (which writes a single draft directly in step 10). Invoked
+ via Skill tool from the entry skill (standard / full tiers).
+---
+
+# Step 11 — Synthesize the final report
+
+**Tier gate:** SKIP entirely for `light` tier — light tier wrote `research/notes/final_report.md` directly in step 10 and proceeds straight to step 15 (polish). For `standard` and `full`: run as documented below.
+
+**Goal:** turn the 3 angle-specific drafts from step 10 into ONE integrated final report at `research/notes/final_report.md`. The orchestrator preps the strategic brief; the synthesizer subagent writes the report in two passes (rough integrated draft, then voice/redundancy/length cleanup).
+
+**Why split orchestrator + synthesizer:** the orchestrator has been running for 30+ minutes and 200K+ tokens of context. Writing a coherent 5000-10000 word report at this point is the highest cognitive load step in the pipeline, and orchestrator context is full of stale subagent dispatch logic. The synthesizer is a fresh Opus session with `[Read, Write]` tool-lock, focused exclusively on producing the final report. This is the same architectural move that made the patcher and polish-auditor reliable.
+
+---
+
+## Recover state
+
+Read these inputs:
+- `research/scaffold.md` — vault_tag
+- `research/prompt-decomposition.json` — atomic items, required_section_headings, response_format, citation_style
+- `research/temp/draft-a.md`, `research/temp/draft-b.md`, `research/temp/draft-c.md` — the 3 angle-specific drafts from step 10
+- `research/comparisons.md` (full tier) — cross-locus tensions
+- `research/temp/source-tensions.json` (full tier) — expert disagreements
+- `research/temp/evidence-digest.md` — load-bearing claims with verbatim quotes
+- `research/query-<vault_tag>.md` — canonical research query (GOSPEL)
+
+---
+
+## Step 11.1 — Read all 3 drafts in full
+
+1. **Read each draft in full** from `research/temp/draft-{a,b,c}.md`. Don't skim — actually read. Hold them in context.
+
+2. **Re-read each sub-orchestrator's report-back** (from your own task results in step 10). Note each draft's:
+ - Core thesis
+ - How many notes from `must_read_note_ids` it actually read
+ - Strongest argumentative beat
+ - Word/character count
+
+---
+
+## Step 11.2 — Spot-check factual conflicts (orchestrator only)
+
+The synthesizer is tool-locked to `[Read, Write]` — it cannot run Bash to query the vault. So YOU resolve factual conflicts here, before spawning it.
+
+For each substantive contradiction between drafts:
+1. Identify the cited source IDs on both sides
+2. `$HPR note show <id1> <id2> -j` to read the actual source bodies
+3. Decide which side is correct. Write the verdict to `research/temp/synthesis-conflicts.md`:
+ ```markdown
+ ## Conflict 1: <one-line description>
+ - Draft A says: <claim with citation>
+ - Draft B says: <opposing claim with citation>
+ - Source check: <what the source actually says, verbatim where possible>
+ - **Verdict:** <which side, with reason>
+ ```
+
+If there are no substantive conflicts, write a one-line file: "No factual conflicts found across drafts."
+
+---
+
+## Step 11.3 — Write the synthesis plan
+
+Write `research/temp/synthesis-plan.md`. This is your strategic brief for the synthesizer:
+
+```markdown
+# Synthesis plan
+
+## Core thesis (1-2 sentences)
+<the final report's central argument>
+
+## The 3-7 strongest argumentative beats
+1. **<short name>** — sourced from Draft <A/B/C>. <one sentence on the beat and why it's load-bearing>
+2. ...
+
+## Section structure
+<list required_section_headings if present, OR the inferred H2 structure>
+
+## Per-section commitments
+### Section 1: <heading>
+- Evidence to pull from: Draft A's <topic>, Draft C's <topic>
+- Argumentative beat: <which committed position to argue here>
+- Cross-locus tension to engage (if any): <name from comparisons.md>
+
+### Section 2: ...
+
+## Where drafts disagreed
+- **<Disagreement 1>:** Draft A says X; Draft B says Y. **Commit to <side>** because <reason>. The other side gets explicit engagement, not equal hedging.
+- ...
+
+## Length target
+- response_format: <short|structured|argumentative>
+- Pass 1 target: <middle of pass-1 range>
+- Pass 2 final target: <middle of pass-2 range>
+```
+
+---
+
+## Step 11.4 — Write the synthesis outline
+
+Write `research/temp/synthesis-outline.md`. This is the per-section contract — 1-2 sentences per H2 naming what evidence and argument lives there:
+
+```markdown
+# Synthesis outline
+
+## Executive summary
+<1-2 sentences: the direct answer to the research_query, with top-line numbers if applicable>
+
+## I. <First H2 from required_section_headings or plan>
+<1-2 sentences: what this section establishes, which evidence anchors it, what argumentative beat lives here>
+
+## II. <Second H2>
+<1-2 sentences>
+
+...
+
+## Conclusion / Opinionated synthesis
+<1-2 sentences: the committed reading, the strongest forward-looking implication>
+
+## Sources
+<inline citation style only — N entries, deduplicated>
+```
+
+The outline is short (50-200 words total). It's the structural anchor that prevents pass-1 sections from rambling.
+
+---
+
+## Step 11.5 — VERIFICATION GATE
+
+Before spawning the synthesizer, verify these files exist with non-trivial content:
+- `research/temp/synthesis-plan.md` — must include the core thesis and at least one per-section commitment
+- `research/temp/synthesis-outline.md` — must include one outline entry per H2 in the planned structure
+- `research/temp/synthesis-conflicts.md` — exists (may say "no conflicts found")
+- `research/temp/draft-{a,b,c}.md` — all three exist
+
+If any are missing or trivial, fix them before proceeding. The synthesizer cannot do strategic planning — it can only execute the plan. Skipping plan/outline produces a thin synthesizer output that doesn't beat the original drafts.
+
+---
+
+## Step 11.6 — Spawn the synthesizer
+
+Spawn ONE `hyperresearch-synthesizer` subagent. Single spawn, runs once.
+
+**Spawn template:**
+```
+subagent_type: hyperresearch-synthesizer
+prompt: |
+ RESEARCH QUERY (verbatim, gospel):
+ > {{paste research/query-<vault_tag>.md body}}
+
+ QUERY FILE: research/query-<vault_tag>.md
+
+ PIPELINE POSITION: You are step 11 of the hyperresearch V8 pipeline.
+ Step 10 produced 3 angle-specific drafts. The orchestrator wrote a
+ synthesis plan and outline. You read everything and write the final
+ report in TWO passes (pass 1 = rough integrated draft, pass 2 = voice/
+ redundancy/length cleanup). You are tool-locked to [Read, Write] — you
+ cannot Bash, cannot spawn subagents. After you return, step 12 (4
+ critics) reads your final report.
+
+ YOUR INPUTS:
+ - query_file_path: research/query-<vault_tag>.md
+ - draft_paths: [research/temp/draft-a.md, research/temp/draft-b.md, research/temp/draft-c.md]
+ - synthesis_plan_path: research/temp/synthesis-plan.md
+ - synthesis_outline_path: research/temp/synthesis-outline.md
+ - synthesis_conflicts_path: research/temp/synthesis-conflicts.md
+ - decomposition_path: research/prompt-decomposition.json
+ - comparisons_path: research/comparisons.md
+ - source_tensions_path: research/temp/source-tensions.json
+ - evidence_digest_path: research/temp/evidence-digest.md
+ - pass1_output_path: research/temp/synthesis-pass1.md
+ - final_output_path: research/notes/final_report.md
+ - response_format: "<short|structured|argumentative>"
+ - citation_style: "<inline|none>"
+
+ Read everything. Write pass 1 to pass1_output_path. Then audit pass 1
+ for redundancy, voice consistency, weak sections, and length, and
+ write the cleaned pass 2 to final_output_path. Do not paste paragraphs
+ from the input drafts — synthesize them in your own voice.
+```
+
+**CRITICAL: never emit bare text while the synthesizer is running.** It will take 5-15 minutes (two passes). Use the wait time to think — append notes to `research/temp/orchestrator-notes.md` about what you'll watch for in step 12 (the critics) based on the synthesis plan you just wrote.
+
+---
+
+## Step 11.7 — Validate the synthesizer output
+
+When the synthesizer returns:
+
+1. **Confirm both files exist:**
+ - `research/temp/synthesis-pass1.md` (pass 1, rough integrated)
+ - `research/notes/final_report.md` (pass 2, final)
+
+2. **Read the synthesizer's report-back.** It tells you:
+ - Word/character count
+ - Pass 1 vs pass 2 length delta (should be NEGATIVE — pass 2 cuts)
+ - Top redundancies cut
+ - Top voice fixes
+ - Sections flagged as still weak
+
+3. **Sanity checks on the final report:**
+ - Length is in the target range for `response_format` (not 3x)
+ - Has all H2s from `required_section_headings`
+ - Has `## Sources` section if `citation_style == "inline"`
+ - No YAML frontmatter, no scaffold leaks, no pipeline vocabulary
+
+If pass 2 is longer than pass 1 (positive delta), something went wrong — pass 2 is supposed to cut. Investigate before proceeding.
+
+If a sanity check fails, hand-craft an Edit on `research/notes/final_report.md` yourself to fix it. Do NOT re-spawn the synthesizer — that's regeneration, which violates the patch-not-regenerate invariant once we have a final draft.
+
+---
+
+## Write-once after synthesis
+
+After this step, the final report is only modified by Edit hunks from the patcher (step 14) and polish auditor (step 15). Do NOT re-write or re-synthesize.
+
+---
+
+## Exit criterion
+
+- `research/notes/final_report.md` exists, length in target range
+- `research/temp/synthesis-pass1.md` exists (debugging artifact)
+- All H2s from `required_section_headings` present
+- `## Sources` section exists if `citation_style == "inline"`
+- No YAML frontmatter, no pipeline vocabulary, no scaffold leaks
+
+---
+
+## Next step
+
+Return to the entry skill (`hyperresearch`). Invoke step 12:
+
+```
+Skill(skill: "hyperresearch-12-critics")
+```
diff --git a/src/hyperresearch/skills/hyperresearch-12-critics.md b/src/hyperresearch/skills/hyperresearch-12-critics.md
new file mode 100644
index 0000000..8b6252a
--- /dev/null
+++ b/src/hyperresearch/skills/hyperresearch-12-critics.md
@@ -0,0 +1,85 @@
+---
+name: hyperresearch-12-critics
+description: >
+ Step 12 of the hyperresearch V8 pipeline. Spawns 4 adversarial critics in
+ parallel against the synthesized final report from step 11 (full tier)
+ or 2 critics (standard tier). Each critic produces an independent
+ findings JSON that the patcher (step 14) consumes. Critics never
+ modify the draft directly. Invoked via Skill tool from the entry skill
+ (standard / full tiers).
+---
+
+# Step 12 — Adversarial critique (parallel critics)
+
+**Tier gate:** SKIP entirely for `light` tier — proceed directly to step 15 (polish). For `standard` tier: spawn only **2 critics** — `width-critic` and `instruction-critic`. For `full` tier: spawn all 4.
+
+**Goal:** independent findings lists against the synthesized final report, each from a different adversarial angle. Critics complement rather than duplicate.
+
+---
+
+## Recover state
+
+Read these inputs:
+- `research/scaffold.md` — vault_tag
+- `research/prompt-decomposition.json` — pipeline_tier, atomic items
+- `research/notes/final_report.md` — merged draft from step 10
+- `research/query-<vault_tag>.md` — canonical research query
+
+---
+
+## Procedure
+
+1. **Spawn critics in parallel.** In ONE message, invoke the right number of critics for the tier:
+
+ **Full tier — all 4 critics:**
+ - `hyperresearch-dialectic-critic` → `research/critic-findings-dialectic.json` (counter-evidence the draft missed or straw-manned)
+ - `hyperresearch-depth-critic` → `research/critic-findings-depth.json` (shallow spots where interim notes could fill substance)
+ - `hyperresearch-width-critic` → `research/critic-findings-width.json` (corpus clusters the draft ignores despite evidence)
+ - `hyperresearch-instruction-critic` → `research/critic-findings-instruction.json` (atomic items from the decomposition that the draft missed, under-covered, reordered, or reformatted)
+
+ **Standard tier — 2 critics only:**
+ - `hyperresearch-width-critic` → `research/critic-findings-width.json`
+ - `hyperresearch-instruction-critic` → `research/critic-findings-instruction.json`
+
+2. **Pass each critic** (standard 3-piece contract):
+ ```
+ subagent_type: hyperresearch-<critic-name>-critic
+ prompt: |
+ RESEARCH QUERY (verbatim, gospel):
+ > {{paste research/query-<vault_tag>.md body}}
+
+ QUERY FILE: research/query-<vault_tag>.md
+
+ PIPELINE POSITION: You are step 12 (<critic-name> critic) of the
+ hyperresearch V8 pipeline. Step 11 (synthesizer) produced the final report at
+ research/notes/final_report.md. After you return, step 13 may run a
+ gap-fetch wave, then step 14 (patcher) applies findings as Edit hunks.
+
+ YOUR INPUTS:
+ - draft_path: research/notes/final_report.md
+ - output_path: research/critic-findings-<critic-name>.json
+ - vault_tag: <vault_tag>
+ - decomposition_path: research/prompt-decomposition.json (instruction-critic only)
+ ```
+
+3. **Wait for all critics.** If one fails, you can proceed with the partial set, but log the absence to the run log — the patch pass is less robust with missing critic coverage. **Do NOT skip the instruction-critic specifically** — it's the only critic measuring prompt adherence, which is the dimension with the widest variance.
+
+4. **Do not read the findings yourself and apply them.** The patcher (step 14) reads the findings. Your job is to hand them to the patcher — AFTER step 13 (gap-fetch) runs.
+
+---
+
+## Exit criterion
+
+- All required critic findings JSONs exist (`research/critic-findings-<name>.json`)
+- Each is valid JSON with a `findings` array
+- For full tier: 4 files. For standard: 2 files (width + instruction).
+
+---
+
+## Next step
+
+Return to the entry skill (`hyperresearch`). Invoke step 13:
+
+```
+Skill(skill: "hyperresearch-13-gap-fetch")
+```
diff --git a/src/hyperresearch/skills/hyperresearch-13-gap-fetch.md b/src/hyperresearch/skills/hyperresearch-13-gap-fetch.md
new file mode 100644
index 0000000..0503598
--- /dev/null
+++ b/src/hyperresearch/skills/hyperresearch-13-gap-fetch.md
@@ -0,0 +1,92 @@
+---
+name: hyperresearch-13-gap-fetch
+description: >
+ Step 13 of the hyperresearch V8 pipeline. Conditional fetcher wave to fill
+ vault gaps that critics identified. If a critic says "the draft ignored
+ topic X" and the vault has zero sources on X, the patcher has nothing
+ to cite. This step fetches the missing sources BEFORE patching so the
+ patcher has ammunition. Capped at 5 gaps. Invoked via Skill tool from
+ the entry skill (standard / full tiers).
+---
+
+# Step 13 — Post-critic gap fetch (conditional)
+
+**Tier gate:** Run for `standard` and `full`. Skip for `light` (no critics = no findings).
+
+**Goal:** critics identify gaps the draft missed, but the patcher can only work with evidence already in the vault. If a critic says "the draft ignored topic X" and the vault has zero sources on X, the patcher has nothing to cite. This step fills those gaps BEFORE patching.
+
+---
+
+## Recover state
+
+Read these inputs:
+- `research/scaffold.md` — vault_tag
+- All `research/critic-findings-*.json` files (which exist depends on tier)
+
+---
+
+## Procedure
+
+1. **Read whichever critic findings files exist.** Scan for findings where:
+ - `failure_mode` is `"missing"`, `"under-covered"`, or `"missing-forward-analysis"`
+ - `failure_mode` is any width-critic finding (these are coverage gaps by definition)
+ - `severity` is `major` or `critical`
+
+2. **For each qualifying finding, check whether the vault has evidence.** Run a targeted vault search for the topic the finding names:
+ ```bash
+ $HPR search "<finding topic keywords>" --tag <vault_tag> --json
+ ```
+ If 2+ relevant notes exist, the patcher can handle it — move on. If 0-1 relevant notes exist, this is a **fetch-worthy gap**.
+
+3. **Collect fetch-worthy gaps.** Cap at **5 gaps maximum** — this is a surgical fill, not a second width sweep. Prioritize by severity (critical first) then by how many critic findings the gap would resolve.
+
+ If 0 fetch-worthy gaps: log "no gaps to fill" and proceed directly to step 14.
+
+4. **Run targeted fetch wave.** For each gap, generate 2-3 search queries and collect URLs. Spawn **2-4 fetchers** with the gap-filling URLs.
+
+ **Spawn template:**
+ ```
+ subagent_type: hyperresearch-fetcher
+ prompt: |
+ RESEARCH QUERY (verbatim, gospel):
+ > {{paste research/query-<vault_tag>.md body}}
+
+ QUERY FILE: research/query-<vault_tag>.md
+
+ PIPELINE POSITION: You are a step 13 (post-critic gap-fill) fetcher
+ of the hyperresearch V8 pipeline. Critics identified gaps in vault
+ coverage; you fetch sources targeting those gaps. After you return,
+ the patcher (step 14) cites your sources to address findings.
+
+ YOUR INPUTS:
+ - vault_tag: <vault_tag>
+ - urls: [<gap-targeted URLs>]
+ - extra_tags: ["post-critic-fill"]
+ ```
+
+ Each fetcher: fetches, quality-checks, summarizes, extracts claims (same procedure as step 2). Tags notes with `vault_tag` + `post-critic-fill`. Writes claims to `research/temp/claims-<note-id>.json`.
+
+5. **Update evidence digest.** If new claims were extracted, append them to `research/temp/evidence-digest.md` under a new `### Post-critic gap fill` section. The patcher reads the evidence digest when looking for citation sources to insert.
+
+6. **Log results** to `research/temp/post-critic-fetch-log.md`:
+ - Each gap: what was searched, how many new sources found, note IDs
+ - If a gap remained unfilled after fetching: flag it so the patcher knows to acknowledge the limitation rather than fabricate
+
+---
+
+## Exit criterion
+
+- `research/temp/post-critic-fetch-log.md` exists (even if it says "no gaps found")
+- All fetch-worthy gaps attempted (proceed to step 14 whether or not all gaps were filled — unfilled gaps are noted in the log)
+
+**Cost:** +$1-3 per run (2-4 Sonnet fetchers). Most runs with good step 2 coverage will find 0-2 gaps, making this a near-no-op.
+
+---
+
+## Next step
+
+Return to the entry skill (`hyperresearch`). Invoke step 14:
+
+```
+Skill(skill: "hyperresearch-14-patcher")
+```
diff --git a/src/hyperresearch/skills/hyperresearch-14-patcher.md b/src/hyperresearch/skills/hyperresearch-14-patcher.md
new file mode 100644
index 0000000..c5a13b0
--- /dev/null
+++ b/src/hyperresearch/skills/hyperresearch-14-patcher.md
@@ -0,0 +1,156 @@
+---
+name: hyperresearch-14-patcher
+description: >
+ Step 14 of the hyperresearch V8 pipeline. Spawns the hyperresearch-patcher
+ subagent (TOOL-LOCKED to Read + Edit) to apply critic findings as
+ surgical Edit hunks against the synthesized final report. Zero
+ regeneration. Pre-stubs the patch log because Edit cannot create files.
+ Handles orchestrator-escalated structural restructures inline. Invoked
+ via Skill tool from the entry skill (standard / full tiers).
+---
+
+# Step 14 — Patch pass
+
+**Tier gate:** SKIP entirely for `light` tier (no critics = no findings to patch). For `standard` and `full`: run as documented.
+
+**Goal:** apply critic findings to the draft as surgical Edit hunks. Zero regeneration.
+
+---
+
+## Recover state
+
+Read these inputs:
+- `research/scaffold.md` — vault_tag
+- `research/notes/final_report.md` — the synthesized final report from step 11
+- All `research/critic-findings-*.json` files (count depends on tier)
+- `research/temp/evidence-digest.md` — patcher's primary citation source
+- `research/query-<vault_tag>.md` — canonical research query
+
+---
+
+## Step 14.0 — Skip gate (optional)
+
+Before spawning the patcher, check whether `research/skip-patcher.txt` exists. If it does, the invoker has requested that step 14 be bypassed. In that case, skip to "Skip path" below.
+
+**Skip path:** Record a minimal log:
+
+```bash
+python -c "
+import json, pathlib
+files = ['research/critic-findings-dialectic.json','research/critic-findings-depth.json','research/critic-findings-width.json','research/critic-findings-instruction.json']
+total = sum(len(json.loads(pathlib.Path(f).read_text()).get('findings',[])) for f in files if pathlib.Path(f).exists())
+pathlib.Path('research/patch-log.json').write_text(json.dumps({'total_findings': total, 'applied': [], 'skipped': [{'reason': 'patcher-skipped-by-invoker'}], 'conflicts': [], 'orchestrator_escalated': []}))
+"
+```
+
+Then proceed to step 15. Most runs should not use this gate.
+
+---
+
+## Step 14.1 — Pre-create the patch log stub
+
+The patcher is tool-locked to `[Read, Edit]` — it cannot Write. Edit can only modify files that already exist. So you (the orchestrator) MUST write the canonical stub first, which the patcher will then Edit to populate:
+
+```bash
+echo '{"total_findings": 0, "applied": [], "skipped": [], "conflicts": [], "orchestrator_escalated": []}' > research/patch-log.json
+```
+
+The schema above is canonical. The patcher's only job on this file is to Edit the existing keys — `total_findings` becomes an integer, the four arrays get populated. **The patcher MUST NOT invent alternate schemas** — downstream tooling assumes the canonical shape.
+
+If you skip this step the patcher will silently have nowhere to write its log, will inline the log in its response instead, and you may mis-capture or drop the data entirely.
+
+---
+
+## Step 14.2 — Spawn the patcher
+
+Spawn ONCE.
+
+**Spawn template:**
+```
+subagent_type: hyperresearch-patcher
+prompt: |
+ RESEARCH QUERY (verbatim, gospel):
+ > {{paste research/query-<vault_tag>.md body}}
+
+ QUERY FILE: research/query-<vault_tag>.md
+
+ PIPELINE POSITION: You are step 14 (patcher) of the hyperresearch V8
+ pipeline. Step 12 produced critic findings; step 13 filled vault gaps.
+ After you return, step 15 (polish auditor) does the final hygiene pass.
+ You are TOOL-LOCKED to [Read, Edit] — you cannot Write.
+
+ YOUR INPUTS:
+ - draft_path: research/notes/final_report.md
+ - findings_paths: [
+ research/critic-findings-dialectic.json, (full tier only)
+ research/critic-findings-depth.json, (full tier only)
+ research/critic-findings-width.json,
+ research/critic-findings-instruction.json
+ ]
+ - patch_log_path: research/patch-log.json (already stubbed)
+ - evidence_digest_path: research/temp/evidence-digest.md
+```
+
+The patcher's job:
+- Apply each finding's patch as an Edit on the draft file
+- Populate the pre-stubbed patch log via Edit on `research/patch-log.json`
+- Each Edit hunk stays surgical: change as little as possible while addressing the issue
+- Reject findings that don't serve the research_query (the patcher checks every finding against the canonical query)
+- Escalate findings that require structural restructure (rather than applying them as oversized patches)
+
+---
+
+## Step 14.3 — Read the patch log
+
+Check the patch log when the patcher returns:
+
+- **Did the patcher apply all `critical` findings?** If any critical was SKIPPED, that's a pipeline blocker — resolve it yourself before step 15. Options:
+ - (a) reject the finding as invalid after re-reading the draft
+ - (b) escalate to the user
+ - (c) hand-craft an Edit to address it (you have Write/Edit access; the lock applies only to the patcher subagent)
+
+- **Did any findings CONFLICT?** Look at the conflict log. If two critics disagreed and the patcher picked one, consider whether the discarded one was actually more important.
+
+- **Did the patcher log a "patch too large" skip?** That means a critic proposed regeneration in patch clothing. If the finding was critical, re-spawn the critic with a tighter suggestion, or address it yourself with multiple small hunks.
+
+- **Is the patch log still the empty stub?** If yes, the patcher failed to log — its Task result will contain the real log inline. Read the Task result, parse out the JSON, and write it to `research/patch-log.json` yourself via Bash so downstream lint rules see it.
+
+---
+
+## Step 14.4 — Handle orchestrator-escalated findings (structural restructures)
+
+The patcher populates `orchestrator_escalated` with findings where `requires_orchestrator_restructure: true` — most commonly, structural-mirror-check findings from the instruction critic (wrong H2 order / missing required heading / extra H2). The patcher's tool-lock cannot safely move / rename H2 sections, so YOU handle them here, before step 15:
+
+For each entry:
+1. Read the `issue` field to understand which H2 in the draft needs to move, be added, or be renamed.
+2. Apply the restructure via hand-written Edit calls on `research/notes/final_report.md`. You have Write and Edit access — the tool lock applies only to the patcher and polish auditor subagents.
+3. Preserve the body content within each H2 section — you are moving / renaming / inserting headings, not regenerating prose. If a new heading is added and its body needs fresh content, write a short evidence-grounded paragraph for it.
+4. Log changes in `research/orchestrator-restructure-log.md` (plain markdown, one bullet per change) so downstream lint rules can see this step happened.
+5. Never regenerate a whole section or the whole draft. The "patch not regenerate" invariant still binds you — broader tools but not broader license.
+
+---
+
+## Constraints
+
+- **Do not apply revisions yourself in step 14.2.** You MUST spawn the patcher subagent. Do NOT call Edit directly on `research/notes/final_report.md` — the patcher has the tool-lock invariants (surgical-edit discipline, conflict resolution, integrate-don't-caveat rule) baked into its prompt. Bypassing it defeats the entire adversarial-review architecture. If the patcher returns empty, re-spawn it once — don't fall back to doing the work yourself unless step 14.4 escalations require it.
+
+- **Do not re-spawn the patcher on the same findings** unless you've modified the findings. The patcher's second run on identical input is a waste.
+
+---
+
+## Exit criterion
+
+- `research/patch-log.json` exists with `total_findings` set and at least one of `applied` / `skipped` / `conflicts` populated
+- All critical findings either applied or resolved by orchestrator
+- All `orchestrator_escalated` findings handled (with `research/orchestrator-restructure-log.md` if any structural restructures were applied)
+- `research/notes/final_report.md` has been edited (or no edits needed if findings were trivial)
+
+---
+
+## Next step
+
+Return to the entry skill (`hyperresearch`). Invoke step 15:
+
+```
+Skill(skill: "hyperresearch-15-polish")
+```
diff --git a/src/hyperresearch/skills/hyperresearch-15-polish.md b/src/hyperresearch/skills/hyperresearch-15-polish.md
new file mode 100644
index 0000000..085d658
--- /dev/null
+++ b/src/hyperresearch/skills/hyperresearch-15-polish.md
@@ -0,0 +1,163 @@
+---
+name: hyperresearch-15-polish
+description: >
+ Step 15 (final) of the hyperresearch V8 pipeline. Spawns the
+ hyperresearch-polish-auditor subagent (TOOL-LOCKED to Read + Edit) for
+ the final hygiene + readability pass. Strips pipeline-reference leaks,
+ YAML frontmatter, scaffold sections, filler phrases, run-on sentences.
+ Escalates structural mismatches rather than fabricating content.
+ Invoked via Skill tool from the entry skill. Followed by step 16
+ (readability audit) which is the actual final step before ship.
+---
+
+# Step 15 — Polish audit
+
+**Tier gate:** Runs for ALL tiers. Every report gets a polish pass regardless of tier.
+
+**Goal:** final hygiene + readability pass. Tool-locked to `[Read, Edit]`.
+
+---
+
+## Recover state
+
+Read these inputs:
+- `research/notes/final_report.md` — the patched draft from step 14 (or single-pass draft for light tier)
+- `research/query-<vault_tag>.md` — canonical research query
+
+---
+
+## Step 15.1 — Pre-create the polish log stub
+
+The polish auditor has `[Read, Edit]` only and cannot create a new file (same tool-lock rule as the step 14 patcher). Stub it first:
+
+```bash
+echo '{"applied": [], "escalations": []}' > research/polish-log.json
+```
+
+---
+
+## Step 15.2 — Spawn the polish auditor
+
+Spawn ONCE.
+
+**Spawn template:**
+```
+subagent_type: hyperresearch-polish-auditor
+prompt: |
+ RESEARCH QUERY (verbatim, gospel):
+ > {{paste research/query-<vault_tag>.md body}}
+
+ QUERY FILE: research/query-<vault_tag>.md
+
+ PIPELINE POSITION: You are step 15 (polish auditor) of the
+ hyperresearch V8 pipeline — the final step. Step 14 (patcher) applied
+ critic findings as Edit hunks. After you return, the orchestrator
+ runs the final integrity gate and ships. You are TOOL-LOCKED to
+ [Read, Edit].
+
+ YOUR INPUTS:
+ - draft_path: research/notes/final_report.md
+ - polish_log_path: research/polish-log.json (already stubbed)
+```
+
+The polish auditor strips:
+- Pipeline reference leaks (`[[interim-*]]` wikilinks, `[I\d+]` references) — converted to proper citations or deleted depending on `citation_style`
+- Hygiene leaks (YAML frontmatter, scaffold sections, prompt echoes)
+- Filler phrases ("It is worth noting", "Importantly", etc.)
+- Redundant sentences / paragraphs that restate prior content
+- Run-on sentences and over-long paragraphs (breaks into smaller units via Edit)
+
+---
+
+## Step 15.3 — Handle escalations
+
+The polish auditor ESCALATES structural mismatches (wrong format for the prompt, missing required sections, etc.) rather than fabricating content to fix them. Read the escalations in the polish log.
+
+If the escalation names a structural issue (e.g., "user asked for a ranked list; draft is unranked prose"), you have one shot to fix it — craft the restructure yourself with hand-written Edits, then ship.
+
+**Sanity-check net length.** Polish should have NEGATIVE net char delta. If the polish log shows positive net chars added, something went wrong — polish is for cutting, not expanding.
+
+**Do not apply polish edits yourself in step 15.2.** The polish auditor's tool lock is the mechanism. Calling Edit directly bypasses the hygiene-check and filler-detection logic baked into the auditor's prompt. If the auditor returned empty, re-spawn it; don't do the work yourself unless step 15.3 escalations require it.
+
+---
+
+## Step 15.4 — Final integrity gate
+
+Before declaring the run complete, verify every expected pipeline artifact exists. **The required set depends on the tier:**
+
+- **light tier:** only `research/polish-log.json` is required (steps 12–14 are skipped, so no critic findings or patch log).
+- **standard tier:** require `research/critic-findings-width.json`, `research/critic-findings-instruction.json`, `research/patch-log.json`, `research/polish-log.json` (depth and dialectic critics did not run).
+- **full tier:** require all four critic findings + patch-log + polish-log:
+
+```bash
+for f in research/critic-findings-dialectic.json \
+ research/critic-findings-depth.json \
+ research/critic-findings-width.json \
+ research/critic-findings-instruction.json \
+ research/patch-log.json \
+ research/polish-log.json; do
+ test -f "$f" || echo "MISSING: $f"
+done
+```
+
+If any artifact is missing, the responsible step failed silently. Re-spawn the responsible agent ONCE with the missing output path as its explicit required output. If it fails a second time, write a minimal stub (`{"findings":[]}` for critic files, canonical empty-log schema for patch-log.json / polish-log.json) and log the failure in the run log before proceeding.
+
+---
+
+## Step 15.5 — Record the run + lint gate
+
+1. **Record the run.** Append to `research/audit_findings.json`:
+ ```json
+ {
+ "mode": "hyperresearch-v8",
+ "run_id": "<iso timestamp>",
+ "loci_count": <K>,
+ "critical_findings_applied": <int>,
+ "critical_findings_skipped": <int>,
+ "polish_escalations": <int>,
+ "final_word_count": <int>
+ }
+ ```
+
+2. **Run the lint gate:**
+ ```bash
+ $HPR lint --rule wrapper-report --json
+ $HPR lint --rule locus-coverage --json
+ $HPR lint --rule scaffold-prompt --json
+ $HPR lint --rule patch-surgery --json
+ ```
+
+ If any rule returns `error` severity issues, address them before declaring complete:
+ - `wrapper-report`: scaffold leaked into the body — re-spawn the polish auditor with the specific leak flagged
+ - `locus-coverage`: a locus identified in step 4 has no interim note — a depth investigator failed silently; do not re-run, just note in the run log
+ - `scaffold-prompt`: scaffold's User Prompt section doesn't match the query file exactly — fix the scaffold
+ - `patch-surgery`: draft churn from step 11 → final exceeds the safety threshold — read the patch log and investigate
+
+---
+
+## Step 15.6 — Ship
+
+The final report lives at `research/notes/final_report.md`. The wrapper's required save path (if any) is a separate copy — handle per the wrapper contract.
+
+---
+
+## Exit criterion
+
+- `research/polish-log.json` populated
+- Final integrity gate passed (or stub-filled with documented failure)
+- Lint gate passed
+- `research/notes/final_report.md` is the final, shippable artifact
+
+---
+
+---
+
+## Next step
+
+Return to the entry skill (`hyperresearch`). Invoke step 16:
+
+```
+Skill(skill: "hyperresearch-16-readability-audit")
+```
+
+Step 16 is the final step — readability audit + selective apply. Runs for ALL tiers.
diff --git a/src/hyperresearch/skills/hyperresearch-16-readability-audit.md b/src/hyperresearch/skills/hyperresearch-16-readability-audit.md
new file mode 100644
index 0000000..19c3893
--- /dev/null
+++ b/src/hyperresearch/skills/hyperresearch-16-readability-audit.md
@@ -0,0 +1,164 @@
+---
+name: hyperresearch-16-readability-audit
+description: >
+ Step 16 (final) of the hyperresearch V8 pipeline. Spawns the
+ hyperresearch-readability-recommender subagent (Read+Write tool-locked,
+ Opus) to audit the polished final report and write JSON
+ recommendations for paragraph merges, breaks, list/table conversions,
+ bold injection, sentence splits, and HR removal. The orchestrator
+ reads the recommendations and SELECTIVELY applies them via direct
+ Edit calls (the recommender does NOT modify the report itself).
+ Logs orchestrator decisions to a separate file. Runs for ALL tiers.
+ Invoked via Skill tool from the entry skill.
+---
+
+# Step 16 — Readability audit & selective apply (FINAL STEP)
+
+**Tier gate:** Runs for ALL tiers. Every report gets a readability audit, regardless of tier — readability is the dimension where small structural changes (paragraph rhythm, list/table conversions, bold injection) yield outsized scoring gains.
+
+**Goal:** improve the report's visual structure, paragraph rhythm, and scannability without changing substantive content. The recommender writes a JSON list of suggested changes; YOU (the orchestrator) decide which to apply.
+
+**Why split recommender + orchestrator-applied:** an Edit-based reformatter (V7-style) sometimes makes changes that hurt the argument — converting a flowing paragraph to a bullet list when the prose was load-bearing, or merging paragraphs that addressed distinct sub-topics. By having the recommender produce JSON suggestions and the orchestrator decide what to apply, we get the recommender's pattern-matching speed plus your judgment about which changes serve the research_query.
+
+---
+
+## Recover state
+
+Read these inputs:
+- `research/scaffold.md` — vault_tag
+- `research/notes/final_report.md` — the polished final report from step 15
+
+---
+
+## Step 16.1 — Spawn the readability recommender
+
+Spawn ONE `hyperresearch-readability-recommender` subagent. Single spawn, runs once.
+
+**Spawn template:**
+```
+subagent_type: hyperresearch-readability-recommender
+prompt: |
+ RESEARCH QUERY (verbatim, gospel):
+ > {{paste research/query-<vault_tag>.md body}}
+
+ QUERY FILE: research/query-<vault_tag>.md
+
+ PIPELINE POSITION: You are step 16 of the hyperresearch V8 pipeline —
+ the final analytical pass. The final report at
+ research/notes/final_report.md has been drafted (step 10),
+ synthesized (step 11), critiqued (step 12), gap-filled (step 13),
+ patched (step 14), and polish-audited (step 15). Your job: write
+ JSON recommendations for paragraph rhythm, list/table conversions,
+ and other structural readability improvements. You are tool-locked
+ to [Read, Write] — you cannot Edit the report. The orchestrator
+ reads your recommendations and decides which to apply.
+
+ YOUR INPUTS:
+ - draft_path: research/notes/final_report.md
+ - recommendations_path: research/readability-recommendations.json
+
+ Write recommendations as a JSON array per the schema in your agent
+ prompt. Cap at 50 recommendations, prioritized by impact.
+```
+
+---
+
+## Step 16.2 — Read the recommendations
+
+When the recommender returns:
+
+1. **Read `research/readability-recommendations.json`.**
+
+2. **Read the recommender's report-back.** It tells you:
+ - Total count of recommendations
+ - Breakdown by category (merge-paragraphs, break-paragraph, make-list, make-table, bold-keyterms, split-sentence, remove-hr, add-whitespace)
+ - Highest-severity issue
+ - Expected net char delta if all applied
+
+---
+
+## Step 16.3 — Decide which to apply
+
+You are not obligated to apply every recommendation. Use these heuristics:
+
+**Apply confidently:**
+- All `merge-paragraphs` recommendations where adjacent paragraphs are clearly the same sub-topic (rationale field confirms this)
+- All `break-paragraph` recommendations on paragraphs > 800 CJK / 1500 EN chars
+- All `remove-hr` recommendations (horizontal rules don't belong in research reports)
+- All `add-whitespace` recommendations (zero risk)
+- `make-table` recommendations when the prose-comparison passage cited 3+ entities × 2+ dimensions and the recommender's suggested table preserves all comparison points
+
+**Apply with judgment:**
+- `make-list` recommendations: confirm the prose was actually enumerative (3+ items in sequence) and not load-bearing argumentative prose. If the rationale says "items appear sequentially in flowing prose," that's NOT a list candidate — skip it.
+- `bold-keyterms` recommendations: confirm the term is genuinely a key term, not just any noun. Bold load-bearing concepts and statistics; don't over-bold.
+
+**Apply skeptically (often skip):**
+- `split-sentence` recommendations on argumentative prose where sentence length serves emphasis or rhythm
+- Recommendations that touch the opening thesis paragraph (load-bearing — keep as written)
+- Recommendations that change tables that already exist
+
+**Always skip:**
+- Any recommendation whose `current` field doesn't match the actual draft (the recommender mis-anchored — log and ignore)
+- Recommendations that would change H2 heading text
+- Recommendations that delete substantive content (the recommender shouldn't, but verify)
+
+---
+
+## Step 16.4 — Apply chosen recommendations via Edit
+
+For each recommendation you decide to apply:
+
+1. Use the Edit tool on `research/notes/final_report.md`
+2. `old_string` = the recommendation's `current` field (exactly as the recommender wrote it)
+3. `new_string` = the recommendation's `recommended` field
+
+**For non-ASCII text (CJK / Arabic / Cyrillic):** the recommender copied `current` verbatim from Read output. Trust that. Don't retype.
+
+**Order of application:**
+1. `remove-hr` first (smallest changes, cleanest baseline)
+2. `merge-paragraphs` and `break-paragraph` (paragraph-level changes)
+3. `make-list` and `make-table` (structural conversions)
+4. `bold-keyterms` (within paragraphs that survived the merges/breaks)
+5. `split-sentence` (within finalized paragraphs)
+6. `add-whitespace` (final cleanup)
+
+If an Edit fails because `old_string` doesn't match (recommender mis-anchored), skip that recommendation and continue with the rest.
+
+---
+
+## Step 16.5 — Log decisions
+
+Write `research/readability-decisions.json` with the orchestrator's decisions:
+
+```json
+{
+ "total_recommendations": <int>,
+ "applied": [<list of recommendation IDs you applied>],
+ "skipped": [
+ {"id": "rec-N", "reason": "<one sentence>"}
+ ],
+ "edit_failures": [
+ {"id": "rec-N", "reason": "old_string did not match the draft"}
+ ],
+ "net_char_delta_actual": <int — measure the actual delta>
+}
+```
+
+This is the audit trail. If a future review finds a readability problem we should have fixed, this log shows whether we considered it and skipped, or never saw the recommendation.
+
+---
+
+## Exit criterion
+
+- `research/readability-recommendations.json` exists
+- `research/readability-decisions.json` exists with at least one entry in `applied` or all `skipped`
+- `research/notes/final_report.md` reflects the applied recommendations
+- The final report's structure (H2 list, executive summary, conclusion) is unchanged from step 15's output (this step does not restructure)
+
+---
+
+## Pipeline complete
+
+Return to the entry skill (`hyperresearch`). Mark all todos complete. Tell the user the final report path.
+
+You're done.
diff --git a/src/hyperresearch/skills/hyperresearch-2-width-sweep.md b/src/hyperresearch/skills/hyperresearch-2-width-sweep.md
new file mode 100644
index 0000000..72dc3e2
--- /dev/null
+++ b/src/hyperresearch/skills/hyperresearch-2-width-sweep.md
@@ -0,0 +1,280 @@
+---
+name: hyperresearch-2-width-sweep
+description: >
+ Step 2 of the hyperresearch V8 pipeline. Multi-perspective search planning
+ (breadth / depth / adversarial lenses) followed by parallel fetcher waves.
+ Achieves comprehensive topical coverage with 40-100 curated sources for
+ standard/full tiers. Includes coverage check, evidence redundancy audit,
+ and source count gating. Invoked via Skill tool from the entry skill
+ after step 1 completes.
+---
+
+# Step 2 — Width sweep
+
+**Tier gate:** Runs for ALL tiers. For `light` tier: skip academic APIs, target 12–20 sources, limit to 2–3 fetcher batches. For `standard` and `full`: run the full procedure below.
+
+**Goal:** achieve comprehensive topical coverage — every atomic item from the decomposition must have at least 3 supporting sources by the end of this step. Target 40–80 curated sources for `full` tier.
+
+---
+
+## Recover state
+
+Read these inputs:
+- `research/scaffold.md` — vault_tag (in Run config), modality
+- `research/prompt-decomposition.json` — atomic items, sub_questions, entities, pipeline_tier
+- `research/temp/coverage-matrix.md` — verbatim query phrases mapped to atomic items
+- `research/query-<vault_tag>.md` — canonical research query (GOSPEL)
+
+---
+
+## Step 2.1 — Multi-perspective search planning
+
+Before spawning any fetchers, produce a **search plan** that maps the decomposition to concrete searches from **three independent perspectives**. This is the single highest-leverage step for comprehensiveness — an ad-hoc search finds 40 sources on the same 3 sub-topics; a multi-perspective planned search distributes sources across all atomic items from angles a single researcher would miss.
+
+1. **Read the decomposition.** Extract every `sub_question` and every `entity` with its `required_fields`.
+
+2. **Generate searches from three lenses.** For EACH atomic item, generate searches from all three perspectives:
+
+ **Lens A — Breadth coverage (systematic):**
+ - One search for the core factual content of that item
+ - One search for recent developments / state-of-the-art (last 2 years)
+ - One search for each named entity or sub-concept within the item
+ - Goal: no atomic item left uncovered. Cast wide.
+
+ **Lens B — Citation-chain depth (academic/canonical):**
+ - Academic API queries (Semantic Scholar, arXiv, OpenAlex, PubMed) for each item with research literature
+ - Searches targeting canonical/seminal works, foundational papers, authoritative reports
+ - Searches for the upstream sources that derivative commentary cites ("original study", "primary data", "foundational paper")
+ - Goal: find the load-bearing sources that secondary commentary is built on.
+
+ **Lens C — Adversarial/contrarian (dialectical):**
+ - "criticism of X", "limitations of X", "problems with X", "why X doesn't work" for each item
+ - Searches for competing frameworks, alternative explanations, dissenting experts
+ - Searches for failure cases, negative results, counter-examples
+ - At least one "X is wrong" or "against X" search per major atomic item
+ - Goal: ensure the corpus includes the strongest case AGAINST the emerging consensus.
+
+ **Lens D — Period-pinned primary sources (MANDATORY when `time_periods` is non-empty in the decomposition):**
+ - For EVERY entry in `prompt-decomposition.json -> time_periods`, generate at least one search that targets the **primary filing for that exact period** — not the most recent filing, not narrative commentary, not earnings-call summaries.
+ - **SEC EDGAR (US public companies):** target the filing index for the named period. Example queries: `site:sec.gov 10-Q "period ended September 30, 2024" <company>` or `site:sec.gov/cgi-bin/browse-edgar <CIK> 10-Q dateb=20241231`. Open the EDGAR filing-history page directly when CIK is known.
+ - **Companies House (UK):** target the filing-history view, NOT the search index. Example: `site:find-and-update.company-information.service.gov.uk <company> filing-history`. Then fetch the specific accounts PDF made up to the named period.
+ - **Earnings releases / press releases:** target the dated press release for that period, not coverage of it. Example: `<company> "third quarter 2024" results press release`.
+ - **Government / central-bank releases, regulatory disclosures, statutory accounts:** target the publication for the exact reporting period.
+ - **Earnings-call transcripts are insufficient on their own.** Transcripts narrate already-rounded numbers ("revenue grew about 27%"); rubrics demand the tabular line items from the filing itself. If the prompt names a fiscal period, the search plan MUST include a query for the filing PDF, not just the transcript.
+ - Goal: every period in `time_periods` has at least one search that, if successful, fetches the filing's tabular data — not a paraphrase of it.
+
+3. **Write the combined search plan to `research/temp/search-plan.md`** — a table with a `Lens` column:
+ ```markdown
+ | Atomic item | Search query | Type | Lens | Target |
+ |---|---|---|---|---|
+ | Sub-Q1 | "China financial industry growth trends 2025" | web | breadth | factual |
+ | Sub-Q1 | "China financial sector structural risks" | web | adversarial | contrarian |
+ | Sub-Q1 | "financial repression China scholarly analysis" | academic | depth | canonical |
+ | Entity: PE | "China private equity returns academic study" | academic | depth | canonical |
+ ```
+
+ Plan typically has **40–100 planned searches** for a `full` query.
+
+4. **Search gap check.** Cross-check the search plan against `research/temp/coverage-matrix.md`. For every row in the coverage matrix, verify at least one search in the plan targets that query phrase's atomic item. Re-read the verbatim query and check: is there any significant topic, entity, or category in the query that has ZERO rows in the search plan?
+
+ Common failure modes this catches:
+ - Decomposition correctly listed "rugged tablets" but search plan has no queries for tablet manufacturers, enterprise mobility, or field-service devices
+ - Query mentions "Southeast Asia" but all regional searches target only "North America" and "Japan/Korea"
+ - Query says "SaaS applications" but every search is about "payment terminals"
+
+ If gaps exist: add the missing searches to the plan NOW, before proceeding. Do NOT proceed to fetching with known search gaps — a missing search now becomes a missing section in step 10.
+
+5. **Execute searches from ALL three lenses.** Do not shortcut by running only Lens A. The adversarial and depth lenses produce qualitatively different URLs that breadth searching misses.
+
+6. **Minimum adversarial coverage:** at least **5 adversarial searches total**. The dialectic critic will punish one-sided coverage.
+
+---
+
+## Step 2.2 — Execute searches and build URL queue
+
+1. **Academic APIs first.** For topics with a research literature, hit Semantic Scholar / arXiv / OpenAlex / PubMed BEFORE web search. Academic APIs return citation-ranked canonical papers.
+
+2. **Web searches from the plan.** Execute ALL planned searches across all three lenses. Aim for **80–120 candidate URLs** before deduplication for `full` tier, 60–100 for `standard`.
+
+3. **Build and deduplicate the master URL queue.** Remove exact-URL duplicates. Remove obvious junk domains. The deduplicated queue should have **60–100 URLs** for `full` tier, 50–80 for `standard`.
+
+ **Wikipedia SOURCE HUB rule:** Include Wikipedia URLs in the queue — they're valuable for discovery — but treat them as SOURCE HUBS, not as citable sources. When a fetcher processes a Wikipedia article, it extracts the references/citations Wikipedia links to. Those primary sources go into Wave 2 (or the same wave if capacity permits). Wikipedia itself is NEVER cited in the final report.
+
+4. **Partition the queue into non-overlapping batches.** Split the master queue into **10–12 batches** of **8–12 URLs each**. Each batch goes to exactly ONE fetcher. **Zero overlap.**
+
+---
+
+## Step 2.3 — Utility scoring and selection
+
+**Tier gate:** SKIP for `light`. Run for `standard` and `full`.
+
+Before batching URLs, score each candidate URL on six dimensions (0–3 each, max composite 18):
+
+1. **Authority (0–3):** Primary data / government / academic (3) > institutional report (2) > quality journalism (1) > blog (0)
+2. **Novelty (0–3):** Unique domain or perspective (3) > partially overlapping (1) > redundant (0)
+3. **Stance diversity (0–3):** Adversarial / contrarian (3) > mixed-stance (2) > neutral (1) > same-stance majority (0)
+4. **Coverage (0–3):** Targets uncovered atomic item (3) > thin item (2) > adequate item (1) > well-covered (0)
+5. **Redundancy (0–3):** Likely novel content (3) > possibly overlapping (1) > almost certainly a rewrite (0)
+6. **Freshness (0–3):** For temporal topics: last 12 months (3), 1–3 years (2), 3–5 years (1), older (0). For foundational topics: canonical/seminal (3), recent derivative (1).
+
+**Selection rule:** Rank by composite utility score. Select the top N URLs (where N = batch capacity × batch count). Hard constraint: every atomic item must have ≥3 candidate URLs before low-utility URLs from well-covered items are included.
+
+Write to `research/temp/scored-urls.md`.
+
+---
+
+## Step 2.4 — Parallel fetcher waves
+
+**Wave 1 (main wave):** Spawn **10–12 fetcher subagents in ONE message** — true parallel execution. Each fetcher gets its own non-overlapping batch.
+
+**Subagent type:** `hyperresearch-fetcher`
+
+**Spawn template (use the standard 3-piece contract):**
+```
+subagent_type: hyperresearch-fetcher
+prompt: |
+ RESEARCH QUERY (verbatim, gospel):
+ > {{paste contents of research/query-<vault_tag>.md}}
+
+ QUERY FILE: research/query-<vault_tag>.md
+
+ PIPELINE POSITION: You are step 2 (width-sweep fetcher) of the
+ hyperresearch V8 pipeline. The orchestrator partitioned the URL queue into
+ non-overlapping batches; you fetch ONLY the URLs in your batch. Do not
+ search for additional URLs. After you return, the orchestrator runs a
+ coverage check (step 2.5) and may dispatch wave 2 fetchers.
+
+ YOUR INPUTS:
+ - vault_tag: <vault_tag>
+ - urls: [<batch URLs, exactly as assigned>]
+ - batch_id: <number>
+```
+
+**CRITICAL: no token waste.** Each fetcher gets ONLY its batch. No fetcher searches for new URLs or duplicates another fetcher's work. If a fetcher finishes early, it's done.
+
+**CRITICAL: never emit bare text while waiting.** In `-p` mode, a text-only response triggers `end_turn`.
+
+**Use wait time to think.** While subagents are working, write evolving thoughts to `research/temp/orchestrator-notes.md`:
+- What patterns are emerging from sources?
+- What tensions or contradictions do you expect?
+- What's the strongest thesis forming? What could overturn it?
+- How will atomic items map to sections?
+- What's the narrative arc?
+
+Append a few lines with `Edit` or `Write` every 30-60 seconds. Productive thinking time AND keeps the turn alive.
+
+**Vault count check** — once every 60 seconds max:
+```bash
+PYTHONIOENCODING=utf-8 $HPR search "" --tag <vault_tag> --json | python -c "import sys,json; d=json.load(sys.stdin); print(f'Notes in vault: {len(d.get(\"data\",{}).get(\"results\",[]))}')"
+```
+
+The wave is done when the vault note count is ≥80% of total URLs queued.
+
+---
+
+## Step 2.5 — Coverage check (MANDATORY)
+
+After Wave 1 returns, run the coverage check before proceeding:
+
+1. **List fetched sources:** `$HPR search "" --tag <vault_tag> --json` — count substantive (non-deprecated) notes.
+
+2. **Map sources → atomic items.** For each atomic item in the decomposition, identify which fetched sources serve it. Mark each item as:
+ - **Well-covered** (4+ relevant sources)
+ - **Adequate** (2–3 sources)
+ - **Thin** (1 source)
+ - **Uncovered** (0 sources)
+
+3. **Wave 2 fetch for gaps.** For every `thin` or `uncovered` item:
+ - Run 2–3 targeted searches specifically for that item
+ - Spawn 3–5 fetchers with gap-filling URLs (non-overlapping batches)
+ - This wave is smaller (typically 20–40 URLs) but surgically targeted
+
+4. **Write coverage report** to `research/temp/coverage-gaps.md`:
+ - List every atomic item with its coverage status and source count
+ - Any item still at 0 sources after Wave 2 is a genuine gap — flag it prominently
+
+**Do NOT skip the coverage check.** Comprehensiveness scores directly with how many atomic items have multi-source coverage.
+
+---
+
+## Step 2.6 — Evidence redundancy audit
+
+**Tier gate:** SKIP for `light`. Run for `standard` and `full`.
+
+**Goal:** detect when N sources are really 1 source in N outfits.
+
+1. **Collect all claims.** Read `research/temp/claims-<note-id>.json` for every non-deprecated note tagged `<vault_tag>`. If no claim files exist, skip this step.
+
+2. **Cluster by content overlap.** Sources sharing >60% of their `quoted_support` passages are likely derivative.
+
+3. **Cluster by citation ancestry.** Use `suggested-by` links in the vault graph.
+
+4. **For each cluster, identify the canonical upstream source.** Tag derivative sources with `derivative-of`. Do NOT deprecate them — discount them in coverage counting.
+
+5. **Write `research/temp/redundancy-audit.md`** — clusters, adjusted coverage counts, atomic items dropping below 2 → flag for Wave 3.
+
+6. **Wave 3 fetch (conditional).** If any atomic item's independent source count drops below 2, run targeted searches for INDEPENDENT sources. Spawn 2-3 fetchers.
+
+---
+
+## Source count targets
+
+| Tier | Minimum sources | Target sources | Fetchers per wave | Waves |
+|------|----------------|---------------|-------------------|-------|
+| `light` | 10 | 15–25 | 3–5 | 1–2 |
+| `standard` | 30 | 40–70 | 8–10 | 2 |
+| `full` | 45 | 55–80 | 8–12 | 2–3 |
+
+Substantive (non-deprecated) note counts. Quality over quantity — reference reports average ~65 sources. Beyond ~80, each additional source yields diminishing returns while degrading summarizer quality.
+
+---
+
+## Long-source delegation (any time during step 2)
+
+When a single long source (>5000 words) is load-bearing, delegate end-to-end analysis to `hyperresearch-source-analyst` (Sonnet, 1M context):
+
+Trigger conditions (ALL three must hold):
+1. **Length:** source's `word_count` (visible on `$HPR note show <id> -j`) exceeds ~5000 words
+2. **Relevance:** source is relevant to the research_query
+3. **No existing analysis:** no `type: source-analysis` note already exists for this source
+
+**Cap: at most 6 source-analysts per query.**
+
+Spawn template:
+```
+subagent_type: hyperresearch-source-analyst
+prompt: |
+ RESEARCH QUERY (verbatim, gospel):
+ > {{paste research/query-<vault_tag>.md body}}
+
+ QUERY FILE: research/query-<vault_tag>.md
+
+ PIPELINE POSITION: You are a leaf subagent for deep end-to-end analysis
+ of ONE long source. Your digest feeds downstream hyperresearch V8 steps. You
+ do NOT spawn other subagents.
+
+ YOUR INPUTS:
+ - source_note_id: <vault note id of the long source>
+ - output_path: research/temp/source-analysis-<source_note_id>.md
+ - vault_tag: <vault_tag>
+```
+
+---
+
+## Exit criterion
+
+- Minimum source count met (per tier table)
+- Coverage check shows no `uncovered` atomic items (thin is acceptable)
+- `research/temp/coverage-gaps.md` written
+- (For std/full): `research/temp/redundancy-audit.md` written if any claim files existed
+
+If you fall short after two waves, proceed anyway but ensure `coverage-gaps.md` lists what's missing so the drafter handles it.
+
+---
+
+## Next step
+
+Return to the entry skill (`hyperresearch`). Tier-based routing:
+
+- **light tier:** Skip directly to step 10 — invoke `Skill(skill: "hyperresearch-10-triple-draft")` (light tier writes a single draft, not the ensemble)
+- **standard / full tier:** Invoke `Skill(skill: "hyperresearch-3-contradiction-graph")`
diff --git a/src/hyperresearch/skills/hyperresearch-3-contradiction-graph.md b/src/hyperresearch/skills/hyperresearch-3-contradiction-graph.md
new file mode 100644
index 0000000..e4a3968
--- /dev/null
+++ b/src/hyperresearch/skills/hyperresearch-3-contradiction-graph.md
@@ -0,0 +1,74 @@
+---
+name: hyperresearch-3-contradiction-graph
+description: >
+ Step 3 of the hyperresearch V8 pipeline. Builds an explicit graph of opposing
+ claims across the corpus. Ranked fight clusters feed step 4's loci
+ analysis so that loci emerge from where evidence actually forks, not
+ from agent intuition. Also identifies consensus claims (3+ independent
+ agreements) for confident assertion in the draft. Invoked via Skill
+ tool from the entry skill after step 2 completes.
+---
+
+# Step 3 — Contradiction graph
+
+**Tier gate:** SKIP for `light`. Run for `standard` and `full`.
+
+**Goal:** before loci analysis, build an explicit graph of opposing claims. Loci should emerge from where the evidence actually forks, not from agent intuition about what seems interesting.
+
+---
+
+## Recover state
+
+Read these inputs:
+- `research/scaffold.md` — vault_tag
+- `research/prompt-decomposition.json` — atomic items, pipeline_tier
+- All `research/temp/claims-*.json` files (one per fetched note)
+
+If no claims files exist (e.g., fetchers didn't produce them), skip this step entirely — the next step (loci analysis) falls back to corpus prose-scanning.
+
+---
+
+## Procedure
+
+1. **Load all claims** from `research/temp/claims-*.json` files.
+
+2. **Pair contradictions.** For each claim, find claims from OTHER sources that contradict it. Match on:
+ - Same `stance_target` with opposing `stance` (supports vs. refutes)
+ - Same `entities` with opposite conclusions
+ - Same scope but different `numbers` (e.g., "market grew 15%" vs. "market shrank 3%")
+ - Overlapping `scope_conditions` but different `evidence_type` pointing different directions
+
+3. **Cluster contradiction pairs into fights.** Group related pairs into clusters — each cluster is one contested question:
+ ```json
+ {
+ "cluster_id": "short-slug",
+ "fight": "one-sentence description of what's contested",
+ "side_a": {"position": "...", "claims": ["claim-text-1"], "sources": ["note-id-1"]},
+ "side_b": {"position": "...", "claims": ["claim-text-1"], "sources": ["note-id-1"]},
+ "evidence_quality_delta": "which side has stronger evidence types (empirical > theoretical > anecdotal)",
+ "scope_overlap": "genuine disagreement, or scoped differently and both right?",
+ "decision_relevance": "high|medium|low — does resolving this matter for the research_query"
+ }
+ ```
+
+4. **Rank clusters** by decision_relevance (high first), then by evidence_quality_delta (tighter fights rank higher).
+
+5. **Write `research/temp/contradiction-graph.json`** — array of ranked fight clusters.
+
+6. **Identify consensus claims.** Claims where 3+ INDEPENDENT sources (after redundancy audit if step 2.6 ran) agree. Write these to `research/temp/consensus-claims.json`. These are the "settled ground" the draft can assert confidently without hedging.
+
+---
+
+## Exit criterion
+
+- `research/temp/contradiction-graph.json` exists (may be empty array if corpus is univocal)
+- `research/temp/consensus-claims.json` exists (may be empty array)
+
+---
+
+## Next step
+
+Return to the entry skill (`hyperresearch`). Tier-based routing:
+
+- **standard tier:** Skip steps 4–8. Invoke `Skill(skill: "hyperresearch-9-evidence-digest")`
+- **full tier:** Invoke `Skill(skill: "hyperresearch-4-loci-analysis")`
diff --git a/src/hyperresearch/skills/hyperresearch-4-loci-analysis.md b/src/hyperresearch/skills/hyperresearch-4-loci-analysis.md
new file mode 100644
index 0000000..009d1da
--- /dev/null
+++ b/src/hyperresearch/skills/hyperresearch-4-loci-analysis.md
@@ -0,0 +1,124 @@
+---
+name: hyperresearch-4-loci-analysis
+description: >
+ Step 4 of the hyperresearch V8 pipeline. Spawns 2 parallel loci-analyst
+ subagents that read the width corpus and identify 1-6 specific
+ questions where depth investigation will pay off. Deduplicates and
+ scores each locus on importance/uncertainty/disagreement/decision_impact,
+ then allocates source budgets dynamically. Invoked via Skill tool from
+ the entry skill (full tier only).
+---
+
+# Step 4 — Loci analysis (parallel, 2 analysts)
+
+**Tier gate:** SKIP entirely for `light` and `standard` tiers — proceed directly to step 9. Only `full` tier runs loci analysis.
+
+**Goal:** identify 1–6 specific questions where depth investigation will pay off.
+
+---
+
+## Recover state
+
+Read these inputs:
+- `research/scaffold.md` — vault_tag
+- `research/prompt-decomposition.json` — atomic items, sub-questions
+- `research/temp/contradiction-graph.json` — ranked fight clusters (if step 3 ran)
+- `research/temp/coverage-gaps.md` — which atomic items have weak coverage
+
+Survey the corpus: `$HPR search "" --tag <vault_tag> -j` to confirm width sweep is complete.
+
+---
+
+## Procedure
+
+1. **Spawn 2 `hyperresearch-loci-analyst` subagents in parallel** (ONE message, both Task calls). Both read the same width corpus but return independently.
+
+ **Spawn template:**
+ ```
+ subagent_type: hyperresearch-loci-analyst
+ prompt: |
+ RESEARCH QUERY (verbatim, gospel):
+ > {{paste research/query-<vault_tag>.md body}}
+
+ QUERY FILE: research/query-<vault_tag>.md
+
+ PIPELINE POSITION: You are step 4 (loci-analyst, instance A or B) of
+ the hyperresearch V8 pipeline. The width sweep (step 2) populated the vault
+ tagged <vault_tag>. The contradiction graph (step 3) lives at
+ research/temp/contradiction-graph.json. After you and the other
+ analyst return, the orchestrator dedupes your loci and assigns budgets.
+
+ YOUR INPUTS:
+ - corpus_tag: <vault_tag>
+ - analyst_id: "a" (for one) / "b" (for the other)
+ - output_path: research/loci-a.json (or research/loci-b.json)
+ ```
+
+2. **Wait for both.** If one fails, proceed with the single successful output. If both fail (empty loci lists), tell the user the width sweep was too thin and stop — do not force depth on a weak corpus.
+
+3. **Deduplicate and clamp to 6.**
+ - Read both JSON outputs.
+ - Dedupe on `name` (exact match) or near-match (same core question, different phrasing). When in doubt, prefer the entry with stronger `corpus_evidence`.
+ - If the deduped list exceeds 6, drop the weakest entries — rank by how load-bearing the rationale is for the canonical research query.
+ - **Persist both analysts' `skip_loci` arrays** in the merged output — union them under a top-level `skip_loci` key. These justifications matter downstream.
+
+4. **Score and budget each locus (dynamic depth allocation).** For each surviving locus, compute four dimensions:
+ - **importance** (0-10): how central is this locus to the research_query? A locus that directly answers a primary sub-question scores 8-10; tangential enrichment scores 2-4.
+ - **uncertainty** (0-10): how uncertain is the current evidence? If the contradiction graph shows a sharp fight with equal-quality evidence on both sides, uncertainty is high (8-10). If one side has clearly stronger evidence, moderate (4-6). If the corpus already resolves this, low (1-3).
+ - **disagreement** (0-10): how many independent sources disagree? Proxy from the contradiction cluster size. Singletons score low (2-3); multi-source fights score high (7-10). If no contradiction graph exists, estimate from the loci analyst's `opposing_positions`.
+ - **decision_impact** (0-10): would resolving this locus change the draft's recommendation or thesis? If yes, high (8-10). If it adds nuance but doesn't change direction, moderate (4-6).
+
+ **Composite score** = importance + uncertainty + disagreement + decision_impact (max 40).
+
+ **Allocate source budgets.** Total source budget for step 5 is 40. Distribute proportionally:
+ - Loci scoring 30-40: `source_budget` up to 15 (deep dive)
+ - Loci scoring 20-29: `source_budget` up to 10 (standard)
+ - Loci scoring 10-19: `source_budget` up to 5 (shallow pass)
+ - Loci scoring <10: `source_budget` 0-3, or skip investigation entirely
+
+ It's fine if only 1-2 loci score above 20 — allocate heavily to them.
+
+5. **Write scored loci to `research/loci.json`.** Schema:
+ ```json
+ {
+ "loci": [
+ {
+ "name": "...",
+ "one_line": "...",
+ "flavor": "dialectical|synthesis|technical",
+ "importance": 8,
+ "uncertainty": 7,
+ "disagreement": 6,
+ "decision_impact": 9,
+ "composite_score": 30,
+ "source_budget": 12,
+ "rationale": "..."
+ }
+ ],
+ "skip_loci": [...union from both analysts...]
+ }
+ ```
+
+6. **Decide investigator count.** Spawn ONE depth-investigator (in step 5) per locus with `source_budget > 0`, capped at 6. If only 1 locus passes scoring, spawn 1.
+
+**INVARIANT:** at least one `flavor: "dialectical"` locus must be present unless an analyst's `skip_loci` justifies its absence with specific evidence of a univocal corpus. No dialectical locus + no justification = re-spawn the loci-analyst with a tighter prompt.
+
+**Placeholder-breadcrumb ban:** depth investigators will fetch sources; do not hand them breadcrumb placeholders like `hyperresearch-locus-seed` — use real source note ids from the vault or omit `--suggested-by` entirely.
+
+---
+
+## Exit criterion
+
+- `research/loci.json` exists with at least 1 locus (or both analysts justified skip with `skip_loci`)
+- At least one dialectical locus OR a documented justification in `skip_loci`
+- All retained loci have `source_budget` allocated
+
+---
+
+## Next step
+
+Return to the entry skill (`hyperresearch`). Invoke step 5:
+
+```
+Skill(skill: "hyperresearch-5-depth-investigation")
+```
diff --git a/src/hyperresearch/skills/hyperresearch-5-depth-investigation.md b/src/hyperresearch/skills/hyperresearch-5-depth-investigation.md
new file mode 100644
index 0000000..676a3aa
--- /dev/null
+++ b/src/hyperresearch/skills/hyperresearch-5-depth-investigation.md
@@ -0,0 +1,109 @@
+---
+name: hyperresearch-5-depth-investigation
+description: >
+ Step 5 of the hyperresearch V8 pipeline. Spawns K depth-investigator
+ subagents in parallel (one per scored locus), each producing one
+ interim note with a Committed Position section. Investigators read
+ full source bodies for their locus and may fetch additional sources
+ within their source_budget. Invoked via Skill tool from the entry
+ skill (full tier only).
+---
+
+# Step 5 — Depth investigation (parallel, K = len(loci))
+
+**Tier gate:** SKIP entirely for `light` and `standard` tiers. Only `full` tier runs depth investigation.
+
+**Goal:** produce ONE `interim-{locus}.md` note per locus with dense synthesis that the draft sub-orchestrators (step 10) will draft from.
+
+---
+
+## Recover state
+
+Read these inputs:
+- `research/scaffold.md` — vault_tag
+- `research/loci.json` — scored loci with source_budget per locus
+- `research/temp/contradiction-graph.json` (if step 3 ran)
+- `research/query-<vault_tag>.md` — canonical research query
+
+---
+
+## Procedure
+
+1. **Spawn K `hyperresearch-depth-investigator` subagents in parallel** (ONE message, all Task calls). One per locus with `source_budget > 0`, capped at 6.
+
+ **Spawn template:**
+ ```
+ subagent_type: hyperresearch-depth-investigator
+ prompt: |
+ RESEARCH QUERY (verbatim, gospel):
+ > {{paste research/query-<vault_tag>.md body}}
+
+ QUERY FILE: research/query-<vault_tag>.md
+
+ PIPELINE POSITION: You are step 5 (depth-investigator) of the
+ hyperresearch V8 pipeline. Step 4's loci analysts produced research/loci.json;
+ after you return, step 6 will reconcile your committed position against
+ the other investigators' positions in research/comparisons.md.
+
+ YOUR LOCUS (from research/loci.json):
+ - name: "<locus name>"
+ - one_line: "<one-line locus description>"
+ - flavor: "dialectical" / "synthesis" / "technical"
+ - source_budget: <integer from loci.json>
+ - rationale: "<why this locus matters>"
+
+ YOUR INPUTS:
+ - corpus_tag: <vault_tag>
+ - locus_name: <locus name>
+ - source_budget: <hard cap on additional sources you can fetch>
+
+ CRITICAL: Read the full source text of relevant vault notes (via
+ `hyperresearch note show <id1> <id2> ... -j`) BEFORE writing your
+ interim note. Drafting from summaries alone produces paraphrase;
+ drafting from full text produces synthesis. Use your source_budget
+ to fetch additional sources beyond the width corpus if needed.
+
+ OUTPUT: Write a single interim note via the hyperresearch CLI with
+ type=interim, tags = <vault_tag> + locus-<locus-name>. The note MUST
+ end with a "## Committed position" section that takes a SIDE on the
+ dialectical question (or a synthesis verdict for non-dialectical
+ loci). Include calibration: confidence level, what evidence would
+ change your mind.
+ ```
+
+ Each investigator's hard cap is `locus.source_budget`, not a flat number.
+
+2. **Each investigator writes ONE interim note** into the vault with `type: interim` and tags `<vault_tag>` + `locus-<locus-name>`. Return value is the note id.
+
+3. **Wait for all K to complete.** Investigators can fail independently. Proceed with whichever succeeded. If >50% failed, stop and reassess loci quality with the user.
+
+4. **Read the interim notes.** After all return, list them:
+ ```bash
+ $HPR search "" --tag <vault_tag> --type interim --json
+ ```
+ Then batch-read them:
+ ```bash
+ $HPR note show <id1> <id2> ... -j
+ ```
+ Hold the Committed Position sections in your context — they are the load-bearing input to step 6 (cross-locus reconciliation).
+
+**INVARIANT:** Every interim note ends with a `## Committed position` section. An interim note ending with descriptive summary only is defective — flag it and re-spawn that investigator with the committed-position requirement emphasized.
+
+---
+
+## Exit criterion
+
+- One interim note per locus with `source_budget > 0`, each tagged `<vault_tag>` + `locus-<locus-name>`
+- Every interim note ends with `## Committed position`
+
+If >50% of investigators failed: stop and escalate.
+
+---
+
+## Next step
+
+Return to the entry skill (`hyperresearch`). Invoke step 6:
+
+```
+Skill(skill: "hyperresearch-6-cross-locus-reconcile")
+```
diff --git a/src/hyperresearch/skills/hyperresearch-6-cross-locus-reconcile.md b/src/hyperresearch/skills/hyperresearch-6-cross-locus-reconcile.md
new file mode 100644
index 0000000..0e2124f
--- /dev/null
+++ b/src/hyperresearch/skills/hyperresearch-6-cross-locus-reconcile.md
@@ -0,0 +1,82 @@
+---
+name: hyperresearch-6-cross-locus-reconcile
+description: >
+ Step 6 of the hyperresearch V8 pipeline. Reconciles the committed positions
+ from all depth investigators into research/comparisons.md — 3-5 named
+ cross-locus tensions with engagement guidance for the draft. This is
+ the structural step that gives the single draft argumentative density.
+ Invoked via Skill tool from the entry skill (full tier only).
+---
+
+# Step 6 — Cross-locus reconciliation
+
+**Tier gate:** SKIP entirely for `light` and `standard` tiers (no loci = no comparisons). Only `full` tier runs this step.
+
+**Goal:** before drafting, reconcile the committed positions from all depth investigators. Produce `research/comparisons.md` — a short document naming 3–5 places where the loci conflict or complicate each other.
+
+**Why this step exists:** the depth investigators each committed to a position on their own locus. Some of those positions disagree, some reinforce each other, some partially complicate each other. The draft must engage those cross-locus dynamics explicitly — not summarize each locus in isolation. Writing `comparisons.md` forces you to see the loci in cross-section before opening the draft.
+
+**This step is always-on for full tier.** Even single-locus runs produce `comparisons.md` — with that locus's committed position as the lone argumentative anchor the draft must engage. The discipline of writing it down BEFORE drafting is the same.
+
+---
+
+## Recover state
+
+Read these inputs:
+- `research/scaffold.md` — vault_tag
+- `research/loci.json` — scored loci
+- All interim notes: `$HPR search "" --tag <vault_tag> --type interim --json` then `$HPR note show <id1> <id2> ... -j`
+
+You need the `## Committed position` section from every interim note in your context.
+
+---
+
+## Procedure
+
+1. **Lay out all committed positions.** For each interim note, read its `## Committed position` section. Write them down side-by-side in a scratch list (you can use `research/temp/orchestrator-notes.md` as scratch).
+
+2. **Hunt for tensions.** Ask of every pair of positions:
+ - Do they agree on the facts but disagree on what the facts mean?
+ - Do they cite different evidence and reach opposite conclusions?
+ - Does one locus's position assume something another locus's evidence complicates?
+ - Is one locus's position a special case of another's general claim?
+ - Do they converge on a conclusion but via different mechanisms (worth noting — convergence from independent paths is itself a finding)?
+
+3. **Pick the 3–5 strongest cross-locus dynamics.** Reject weak ones (loci that are simply orthogonal, or that restate each other). You want cross-locus relationships that a good final draft should actually wrestle with.
+
+4. **Write `research/comparisons.md`:**
+
+ ```markdown
+ # Cross-locus comparisons
+
+ ## Tension 1: <short name for the dynamic>
+
+ - **Locus A** ([[interim-A]]) commits: <one-line committed position>
+ - **Locus B** ([[interim-B]]) commits: <one-line committed position>
+ - **The cross-locus dynamic:** <2–3 sentences naming exactly how they relate — conflict? convergence? complication? special case? Name the load-bearing disagreement or agreement.>
+ - **How the draft should engage this:** <one sentence. Example: "Section on X must acknowledge that Y from Locus B undercuts the simple reading of Locus A" or "The recommendation should privilege Locus B's position because its evidence base is stronger.">
+
+ ## Tension 2: ...
+ ```
+
+5. **Calibration synthesis.** For each tension, note the investigators' confidence levels and "what would change this position" conditions from their calibrated committed positions. When two investigators disagree but one is "high confidence" and the other is "low confidence," the draft should weight accordingly. When both name the same "what would change my mind" condition, that's a genuine open question to flag explicitly.
+
+6. **This document is the argumentative spine of the draft.** Every tension you name here must become a visible argumentative beat in the final report — a paragraph or section that engages the disagreement explicitly, not a one-line gesture. If you write `comparisons.md` with 4 tensions and the draft only visibly engages 1, the insight score suffers.
+
+---
+
+## Exit criterion
+
+- `research/comparisons.md` exists
+- Contains 3–5 named tensions (or 1 distilled position for single-locus runs)
+- Each tension includes: locus references, dynamic description, engagement guidance, calibration note
+
+---
+
+## Next step
+
+Return to the entry skill (`hyperresearch`). Invoke step 7:
+
+```
+Skill(skill: "hyperresearch-7-source-tensions")
+```
diff --git a/src/hyperresearch/skills/hyperresearch-7-source-tensions.md b/src/hyperresearch/skills/hyperresearch-7-source-tensions.md
new file mode 100644
index 0000000..85387bb
--- /dev/null
+++ b/src/hyperresearch/skills/hyperresearch-7-source-tensions.md
@@ -0,0 +1,101 @@
+---
+name: hyperresearch-7-source-tensions
+description: >
+ Step 7 of the hyperresearch V8 pipeline. Extracts explicit expert
+ disagreements from the corpus into research/temp/source-tensions.json,
+ including orphan tensions that didn't surface as loci. Reads full source
+ bodies of top 8-12 sources (not summaries) to find tensions that hide
+ in nuance. The Source Tensions section in step 10's draft is the single
+ highest-leverage move for insight scores. Invoked via Skill tool from
+ the entry skill (full tier only).
+---
+
+# Step 7 — Source tension extraction
+
+**Tier gate:** SKIP for `light` and `standard` tiers. Only `full` tier runs this step.
+
+**Goal:** extract explicit expert disagreements from the corpus and comparisons into a structured artifact that step 10 MUST include as a dedicated section. This is the single highest-leverage move for the insight dimension.
+
+**Why this step exists:** step 6's `comparisons.md` captures cross-locus tensions — places where depth investigators disagree. But the richest disagreements often live in the width corpus itself: Source A says X, Source B says Y, and neither the loci analysts nor the depth investigators elevated this as a locus because it cut across multiple topics. These "orphan tensions" are invisible to locus-driven analysis but are exactly what distinguishes an expert synthesis from a competent survey.
+
+---
+
+## Recover state
+
+Read these inputs:
+- `research/scaffold.md` — vault_tag
+- `research/comparisons.md` — cross-locus tensions
+- `research/temp/contradiction-graph.json` (if step 3 ran)
+- Survey vault: `$HPR search "" --tag <vault_tag> -j` for the 15–20 highest-quality non-deprecated sources
+
+---
+
+## Procedure
+
+1. **Re-read `comparisons.md`.** Each tension there is already a candidate source tension. Extract: the two positions, the strongest evidence for each, your preliminary reading of which side has the better case.
+
+2. **Scan the width corpus for orphan tensions.** For the 15–20 highest-quality non-deprecated sources, then **read the full body** of the top 8–12 sources most likely to contain disagreements — use `$HPR note show <id1> <id2> ... -j` in batches. **Tensions hide in nuance that summaries flatten:** a source's "however" clause, a footnote caveat, a methodological critique buried in a discussion section. You cannot extract tensions you haven't read. Look for:
+ - Sources that explicitly disagree with each other (different conclusions from similar evidence)
+ - Sources that use competing theoretical frameworks to explain the same phenomenon
+ - Sources where one side cites data the other side ignores
+ - Government/institutional positions that conflict with academic findings
+ - Industry claims that contradict independent research
+ - Historical consensus that recent evidence challenges
+
+3. **If `research/temp/contradiction-graph.json` exists**, read it. Any high-relevance fight cluster that was NOT promoted to a locus is a prime orphan-tension candidate. It was important enough for the contradiction graph but wasn't investigated in depth — these deserve standalone treatment in the draft.
+
+4. **Select 3–7 source tensions.** Combine comparisons.md tensions with orphan tensions. Rank by:
+ - **Decision relevance:** does resolving this tension change the report's recommendation?
+ - **Evidence quality:** are both sides grounded in real evidence (not just opinion)?
+ - **Reader value:** would an expert reader find this tension illuminating?
+
+ Drop tensions that are: trivially resolved (one side is clearly wrong), definitional (the disagreement is about word meaning, not substance), or orthogonal to the research query.
+
+5. **For each tension, pre-commit to a resolution.** Do NOT leave tensions open. For each:
+ - Name it in 5–10 words (e.g., "NHTSA's 'no defect' vs. NTSB's 'design failure'")
+ - State Side A's strongest case with evidence (quote or cite specific sources)
+ - State Side B's strongest case with evidence
+ - Commit to a reading: which side has the better evidence, or is there a synthesis? Name the load-bearing reason.
+
+6. **Write `research/temp/source-tensions.json`:**
+ ```json
+ {
+ "tensions": [
+ {
+ "name": "short descriptive name",
+ "side_a": {
+ "position": "one-sentence claim",
+ "evidence": "strongest evidence with source note ids",
+ "proponents": ["source-note-id-1", "source-note-id-2"]
+ },
+ "side_b": {
+ "position": "one-sentence claim",
+ "evidence": "strongest evidence with source note ids",
+ "proponents": ["source-note-id-3"]
+ },
+ "resolution": "one-paragraph committed reading with load-bearing reason",
+ "origin": "comparisons|contradiction-graph|orphan-scan",
+ "decision_relevance": "high|medium"
+ }
+ ]
+ }
+ ```
+
+This artifact feeds directly into step 10's mandatory Source Tensions section. Every tension named here becomes a subsection in the final report.
+
+---
+
+## Exit criterion
+
+- `research/temp/source-tensions.json` exists with 3–7 tensions
+- Each tension has both sides with proponents, a committed resolution, and decision_relevance
+
+---
+
+## Next step
+
+Return to the entry skill (`hyperresearch`). Invoke step 8:
+
+```
+Skill(skill: "hyperresearch-8-corpus-critic")
+```
diff --git a/src/hyperresearch/skills/hyperresearch-8-corpus-critic.md b/src/hyperresearch/skills/hyperresearch-8-corpus-critic.md
new file mode 100644
index 0000000..49300a1
--- /dev/null
+++ b/src/hyperresearch/skills/hyperresearch-8-corpus-critic.md
@@ -0,0 +1,136 @@
+---
+name: hyperresearch-8-corpus-critic
+description: >
+ Step 8 of the hyperresearch V8 pipeline. Spawns one corpus-critic subagent
+ to identify "what source, if found, would overturn the current
+ direction?" gaps, then runs a targeted fetch wave to fill them.
+ Highest-leverage intervention point: corrections applied before drafting
+ cost nothing; corrections applied after drafting require patches.
+ Invoked via Skill tool from the entry skill (full tier only).
+---
+
+# Step 8 — Pre-draft corpus critic (targeted gap-fill)
+
+**Tier gate:** `full` tier ONLY. Skip for `light` and `standard`.
+
+**Goal:** before drafting, ask "what source, if found, would overturn the current direction?" and run a targeted fetch wave to fill the most dangerous gaps. This is the highest-leverage intervention point in the pipeline — corrections applied before drafting cost nothing; corrections applied after drafting require patches and risk structural drift.
+
+---
+
+## Recover state
+
+Read these inputs:
+- `research/scaffold.md` — vault_tag
+- `research/comparisons.md` — cross-locus tensions
+- `research/loci.json` — scored loci
+- `research/temp/source-tensions.json` — expert disagreements
+- `research/prompt-decomposition.json` — specifically the `time_periods` array
+
+---
+
+## Pre-flight: period-pinned primary-source coverage check
+
+**Run this BEFORE spawning the corpus-critic subagent.** If `prompt-decomposition.json -> time_periods` is non-empty, walk every entry and verify the vault contains a primary source filed *for that exact period* — not "most recent", not narrative commentary, not earnings-call transcripts standing in for tabular filings.
+
+For each `time_period` entry:
+
+1. Search the vault for a primary source matching the `primary_source` description and the `issuer`:
+ ```bash
+ PYTHONIOENCODING=utf-8 {hpr_path} search "<period> <issuer>" --tag <vault_tag> --include-body -j
+ ```
+2. Open the candidate notes (`note show <id> -j`) and verify the document's actual reporting period — the filing must cover the SPECIFIC period named in the prompt, not an adjacent one. A Q1 2025 10-Q does NOT satisfy "Q3 2024" — different period, different tabular data.
+3. **If the period-pinned filing is missing, add it to `research/corpus-critic-gaps.json` as a `priority: critical` gap of type `period-pinned-primary` BEFORE spawning the corpus-critic subagent.** Schema:
+ ```json
+ {{
+ "type": "period-pinned-primary",
+ "target_position": "<period> exact figures for <issuer>",
+ "search_queries": [
+ "site:sec.gov 10-Q \"period ended September 30, 2024\" <issuer>",
+ "<issuer> Q3 2024 10-Q filing PDF"
+ ],
+ "source_type": "primary-filing",
+ "priority": "critical",
+ "rationale": "Prompt names <period>; vault has no filing covering that exact period. Tabular line items only exist in the period-pinned filing. Without it, the draft will paraphrase rounded numbers from earnings calls and miss the rubric's exact figures."
+ }}
+ ```
+
+The targeted fetch wave in the next step will pull these filings BEFORE the corpus-critic finishes its broader gap analysis. This ordering matters: numerical-precision misses are the largest single category of avoidable factual-accuracy failures.
+
+---
+
+## Procedure
+
+1. **Spawn ONE `hyperresearch-corpus-critic` subagent** (Sonnet).
+
+ **Spawn template:**
+ ```
+ subagent_type: hyperresearch-corpus-critic
+ prompt: |
+ RESEARCH QUERY (verbatim, gospel):
+ > {{paste research/query-<vault_tag>.md body}}
+
+ QUERY FILE: research/query-<vault_tag>.md
+
+ PIPELINE POSITION: You are step 8 of the hyperresearch V8 pipeline.
+ Step 6 produced research/comparisons.md. After you return, the
+ orchestrator runs a targeted fetch wave, then step 10 drafts.
+
+ YOUR INPUTS:
+ - corpus_tag: <vault_tag>
+ - comparisons_path: research/comparisons.md
+ - loci_path: research/loci.json
+ - output_path: research/corpus-critic-gaps.json
+ ```
+
+2. **Read the gaps output** (`research/corpus-critic-gaps.json`). Each gap has a `priority` (critical / high) and a `type` (overturning / strengthening / independent-verification).
+
+3. **Targeted fetch wave.** Spawn **2–4 fetcher subagents** (Sonnet) to search for and fetch the sources identified in the gaps.
+
+ **Spawn template:**
+ ```
+ subagent_type: hyperresearch-fetcher
+ prompt: |
+ RESEARCH QUERY (verbatim, gospel):
+ > {{paste research/query-<vault_tag>.md body}}
+
+ QUERY FILE: research/query-<vault_tag>.md
+
+ PIPELINE POSITION: You are a step 8 fetcher (corpus-critic gap-fill)
+ of the hyperresearch V8 pipeline. The corpus critic identified specific
+ gaps; you fetch sources targeting those gaps. After you return, the
+ orchestrator updates comparisons.md based on what you found.
+
+ YOUR INPUTS:
+ - vault_tag: <vault_tag>
+ - search_queries: [<gap.search_queries>]
+ - source_type: <gap.source_type>
+ - gap_id: <gap.id>
+ ```
+
+4. **Assess results.**
+ - **Overturning source found:** re-read the relevant committed position from the interim note. If the new source genuinely undercuts it, update `research/comparisons.md` to note the weakened position — the draft will handle it with appropriate calibration. Do NOT re-run the full depth investigation; adjust the position's confidence level.
+ - **Overturning source NOT found:** the committed position gains confidence. Note this in `comparisons.md` — "adversarial search for counter-evidence to [position] returned no substantive challenges."
+ - **Strengthening/verification source found:** note the additional support in `comparisons.md`. The draft can assert more confidently.
+
+5. **Log results** to `research/temp/corpus-critic-results.md`:
+ - Each gap: what was searched, what was found (or not), how it affects the committed positions
+ - Updated confidence levels for any positions that changed
+
+---
+
+## Exit criterion
+
+- `research/corpus-critic-gaps.json` exists
+- All critical gaps attempted (fetched or documented as unfindable)
+- `research/temp/corpus-critic-results.md` exists
+- `research/comparisons.md` updated with confidence/strengthening/overturning notes
+
+---
+
+## Next step
+
+Return to the entry skill (`hyperresearch`). Invoke step 9:
+
+```
+Skill(skill: "hyperresearch-9-evidence-digest")
+```
diff --git a/src/hyperresearch/skills/hyperresearch-9-evidence-digest.md b/src/hyperresearch/skills/hyperresearch-9-evidence-digest.md
new file mode 100644
index 0000000..869a784
--- /dev/null
+++ b/src/hyperresearch/skills/hyperresearch-9-evidence-digest.md
@@ -0,0 +1,87 @@
+---
+name: hyperresearch-9-evidence-digest
+description: >
+ Step 9 of the hyperresearch V8 pipeline. Assembles the top load-bearing
+ claims and verbatim quotes from the claims JSONs into
+ research/temp/evidence-digest.md — a single high-fidelity evidence
+ index the draft sub-orchestrators read as primary evidence (higher
+ fidelity than fetcher summaries). Invoked via Skill tool from the
+ entry skill (standard / full tiers).
+---
+
+# Step 9 — Evidence digest
+
+**Tier gate:** Run for `standard` and `full`. Skip for `light`.
+
+**Goal:** assemble the top load-bearing claims and verbatim quotes from the claims JSONs into a single digest file the drafter reads as primary evidence — higher-fidelity than fetcher summaries.
+
+---
+
+## Recover state
+
+Read these inputs:
+- `research/scaffold.md` — vault_tag
+- `research/prompt-decomposition.json` — atomic items, response_format, pipeline_tier
+- All `research/temp/claims-*.json` files
+- `research/temp/consensus-claims.json` (if step 3 ran)
+- `research/temp/contradiction-graph.json` (if step 3 ran)
+
+---
+
+## Procedure
+
+1. **Read all claims files** from `research/temp/claims-*.json` for every non-deprecated note tagged with the vault tag. If no claim files exist (e.g., fetchers didn't produce them), skip this step.
+
+2. **Filter and rank.** Keep claims where `confidence` is `"high"` OR `evidence_type` is `"empirical"` or `"statistical"`. From the remainder, prefer claims with non-empty `numbers` arrays and non-empty `quoted_support`. Cap at:
+ - **80–120 claims total** for `full` tier
+ - **40–60 claims** for `standard` tier
+
+3. **Group by atomic item.** Match each surviving claim to the atomic item it is most relevant to based on **topic overlap** — do not rely on exact field matching. A claim about "United Health Group regulatory exposure" serves the atomic item "UNH risk factors" even though no field matches exactly. Use the claim's `entities`, `stance_target`, `scope_conditions`, and `claim` text holistically to judge relevance. When uncertain, include the claim under the most relevant item rather than dropping it to Ungrouped. Claims that genuinely don't map to any atomic item go into an "Ungrouped" section at the end.
+
+4. **Include consensus and contested claims.**
+ - If `research/temp/consensus-claims.json` exists, include its claims marked as `[consensus]`.
+ - If `research/temp/contradiction-graph.json` exists, include the top 3–5 contested claim pairs with both sides' `quoted_support` passages.
+
+5. **Write `research/temp/evidence-digest.md`.** Format: one H3 per atomic item, bullet list of claims. Each bullet includes:
+ - The `claim` text
+ - The `quoted_support` verbatim passage (block-quoted)
+ - The `source_note_id`
+
+ Keep it scannable — this is an evidence index, not a narrative.
+
+ Example:
+ ```markdown
+ ### Atomic item: Market growth in Southeast Asia
+
+ - Annual growth rate of 12.4% in 2024 (empirical)
+ > "Southeast Asian e-commerce GMV grew from $89B to $100B between 2023 and 2024, a 12.4% YoY expansion."
+ [source-note-12]
+
+ - Vietnam led by penetration rate (statistical)
+ > "Vietnam reached 64% e-commerce penetration in 2024, the highest in SEA, surpassing Singapore (61%)."
+ [source-note-19]
+ ```
+
+---
+
+## Exit criterion
+
+- `research/temp/evidence-digest.md` exists
+- Contains at least:
+ - 30 claims for `full` tier
+ - 15 claims for `standard` tier
+- Grouped by atomic item with verbatim quoted_support and source_note_id
+
+If fewer claims exist in total, include all of them.
+
+---
+
+## Next step
+
+Return to the entry skill (`hyperresearch`). Invoke step 10:
+
+```
+Skill(skill: "hyperresearch-10-triple-draft")
+```
+
+Step 10 is the most important step in the pipeline. Re-read the entry skill before invoking if needed — the triple-draft ensemble must spawn 3 draft-orchestrators for `standard` and `full` tiers.
diff --git a/src/hyperresearch/skills/hyperresearch.md b/src/hyperresearch/skills/hyperresearch.md
new file mode 100644
index 0000000..34d77f1
--- /dev/null
+++ b/src/hyperresearch/skills/hyperresearch.md
@@ -0,0 +1,247 @@
+---
+name: hyperresearch
+description: >
+ Deep research via the HYPERRESEARCH V8 architecture — a tier-adaptive 16-step
+ pipeline (light / standard / full) that scales from a 3-minute $5 answer
+ to a 55-minute $60 adversarially-audited report. This entry skill is a
+ ROUTER. It does not contain step procedures — it tells you which Skill to
+ invoke for each step, in order. Each step's instructions live in its own
+ skill file (`hyperresearch-1-decompose` through `hyperresearch-16-readability-audit`) and
+ are loaded fresh into context when you invoke them. This solves the
+ context-compaction problem that V7 hit: instead of one 1200-line skill
+ that gets evicted by Layer 4, each step is a focused 50-150 line skill
+ that lands in context only when needed.
+---
+
+# Hyperresearch V8 — multi-skill chain orchestrator
+
+You are the orchestrator (Opus). Your entire job in this conversation is:
+1. Read this file once at the start.
+2. Bootstrap canonical inputs (research_query, vault_tag, scaffold).
+3. Invoke each step skill in sequence via the `Skill` tool.
+4. Between steps, do nothing except mark todos and (optionally) think to `research/temp/orchestrator-notes.md`.
+
+You do NOT do the work of any step yourself. The step skills do. You just sequence them.
+
+---
+
+## How the chain works (READ THIS CAREFULLY)
+
+Each pipeline step is its own skill file. To run a step:
+
+```
+Skill(skill: "hyperresearch-N-stepname")
+```
+
+When you invoke a Skill, that skill's full procedure is loaded into your context **fresh**. You then execute that step's procedure, hit its exit criterion, and return to the entry skill (this file) to invoke the next step.
+
+**Why this design?** Context compaction. V7 was one 1200-line skill that got compacted away by the time Layer 4 needed its triple-draft procedure. The orchestrator forgot the procedure, wrote a single draft, and produced a flat-scoring report. V8 fixes this at the source: each step's procedure is loaded into context **only at the moment it's needed**, fresh, with no eviction risk.
+
+**The 16 step skills** (all prefixed `hyperresearch-`):
+
+| # | Skill name | What it does | Tiers |
+|---|---|---|---|
+| 1 | `hyperresearch-1-decompose` | Canonical query → scaffold + decomposition + coverage matrix + tier classification | all |
+| 2 | `hyperresearch-2-width-sweep` | Multi-perspective search plan + parallel fetcher waves | all |
+| 3 | `hyperresearch-3-contradiction-graph` | Pair contradictions across the corpus into ranked fight clusters | std/full |
+| 4 | `hyperresearch-4-loci-analysis` | 2 loci-analysts → scored loci.json with source budgets | full |
+| 5 | `hyperresearch-5-depth-investigation` | K depth-investigators in parallel → interim notes with committed positions | full |
+| 6 | `hyperresearch-6-cross-locus-reconcile` | Reconcile committed positions → comparisons.md | full |
+| 7 | `hyperresearch-7-source-tensions` | Extract expert disagreements → source-tensions.json | full |
+| 8 | `hyperresearch-8-corpus-critic` | "What source would overturn this?" + targeted gap-fill fetch | full |
+| 9 | `hyperresearch-9-evidence-digest` | Top claims + verbatim quotes → evidence-digest.md | std/full |
+| 10 | `hyperresearch-10-triple-draft` | Per-angle source curation + 3 parallel draft-orchestrators (3 angle-specific drafts) | all |
+| 11 | `hyperresearch-11-synthesize` | Synthesis plan + outline + spawn synthesizer subagent (two-pass write) → final_report.md | std/full |
+| 12 | `hyperresearch-12-critics` | 4 adversarial critics in parallel → findings JSONs | std/full |
+| 13 | `hyperresearch-13-gap-fetch` | Fetch sources for critic-identified vault gaps | std/full |
+| 14 | `hyperresearch-14-patcher` | Surgical Edit hunks applied to draft | std/full |
+| 15 | `hyperresearch-15-polish` | Hygiene + filler pass (Edit-based subagent) | all |
+| 16 | `hyperresearch-16-readability-audit` | Readability recommender writes JSON suggestions; orchestrator selectively applies via Edit | all |
+
+---
+
+## Tier routing
+
+Step 1 classifies the query into a `pipeline_tier` (`light` / `standard` / `full`). The tier is written to `research/prompt-decomposition.json`. After step 1, **read that file** to learn the tier, then sequence steps according to:
+
+| Tier | Steps that run | Typical cost | Typical time |
+|------|---|---|---|
+| `light` | 1 → 2 → 10 (single draft) → 15 → 16 | ~$3–8 | ~3–8 min |
+| `standard` | 1 → 2 → 3 → 9 → 10 → 11 → 12 → 13 → 14 → 15 → 16 | ~$10–22 | ~10–22 min |
+| `full` | 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12 → 13 → 14 → 15 → 16 | ~$35–65 | ~25–60 min |
+
+**RESPECT THE TIER GATE.** When step 1 classifies a query as `light` or `standard`, do NOT run the skipped steps "just to be thorough." The tier classification is a product decision: simple queries should produce fast, cheap, right-sized answers. Trust the classification. If you're uncertain, tier up — but never silently upgrade every query to `full`.
+
+---
+
+## Bootstrap (run BEFORE invoking step 1)
+
+Before you invoke any step skill, do this:
+
+1. **Resolve the canonical research query.** Order of precedence:
+ - If `research/prompt.txt` exists (legacy harness / wrapped run), read it. Its contents are the canonical research query. GOSPEL.
+ - Otherwise, use the user's verbatim prompt as the canonical research query.
+ - Extract wrapper requirements separately: required save path, citation format, terminal-section shape, wrapper contract. These are binding but NOT part of the query.
+ - If `research/wrapper_contract.json` exists, read it.
+
+2. **Generate a vault tag** (short slug from the canonical query, e.g., `efield-dft-sac`).
+
+3. **Persist the query file.** Write the verbatim canonical query to `research/query-<vault_tag>.md`:
+ ```markdown
+ ---
+ vault_tag: <slug>
+ created: <ISO-8601 timestamp>
+ source: prompt.txt | user-prompt
+ ---
+
+ <verbatim query text, character-for-character>
+ ```
+ This file is the **canonical query reference for the entire pipeline**. Every step skill and every subagent reads it by path.
+
+4. **Classify modality** (collect / synthesize / compare / forecast) — record in the scaffold. This is a label that calibrates step 10's drafting style:
+ - **collect**: enumerative coverage, per-entity sections with named fields
+ - **synthesize**: defended thesis with evidence chains
+ - **compare**: proportionate per-entity depth + a committed recommendation
+ - **forecast**: predictive claims grounded in past + present, explicit time horizon
+
+5. **Write the scaffold.** Write `research/scaffold.md` with the same template `/research` uses (see `.claude/skills/hyperresearch/SKILL.md` Step 7). The scaffold is your private planning document — it MUST NOT appear anywhere in the final report. Include in scaffold:
+ - User Prompt (VERBATIM — gospel)
+ - Run config (vault_tag, query_file_path, modality, wrapper requirements)
+ - Modality classification rationale
+ - Tier rationale (filled in after step 1)
+ - Wrapper requirements (save path, citation format, terminal sections)
+
+6. **Seed the TodoWrite list.** Create todos for all 16 step skill invocations using the integer step numbers, e.g.:
+ - `Step 1 — Skill: hyperresearch-1-decompose`
+ - `Step 2 — Skill: hyperresearch-2-width-sweep`
+ - ... (through Step 16)
+
+ The todo list survives context compaction; it's your durable memory of where you are in the chain.
+
+7. **Invoke step 1:** `Skill(skill: "hyperresearch-1-decompose")`.
+
+After step 1 returns, read `research/prompt-decomposition.json` to learn the tier, then continue invoking step skills per the tier routing table above. After each step's exit criterion is met, mark its todo complete and move to the next.
+
+---
+
+## Four canonical rules (ALWAYS in force)
+
+1. **NEVER EMIT BARE TEXT WHILE TASKS ARE RUNNING.** In non-interactive (`-p`) mode, a text-only response (no tool call) triggers `end_turn` — the process exits and the pipeline dies. Every response while subagent tasks are in flight MUST include a tool call. The best one is appending analytical thoughts to `research/temp/orchestrator-notes.md`. Vault count checks at most once per minute.
+
+2. **PATCH, NEVER REGENERATE.** After step 11 produces the synthesized final report (or step 10 for light tier), the only modifications are surgical Edit hunks from step 14 (patcher) and step 15 (polish-auditor). Both subagents are tool-locked to `[Read, Edit]`. If a critic's finding would require rewriting a whole section, it escalates to you as a structural issue — not a rewrite. Keep hunks surgical.
+
+3. **ARGUE, DON'T JUST REPORT** (full force for `argumentative` response_format; relaxed for `structured` and `short`). The pipeline is engineered to push the final report toward argumentative density. Loci must include at least one dialectical locus. Depth investigators must commit to a position. Step 6 forces cross-locus reconciliation. Step 11's synthesizer requires every body section that touches a tension to engage it explicitly.
+
+4. **RESPECT THE TIER GATE.** See tier routing table. Don't add steps "for thoroughness." Don't drop steps "for budget." The tier is a binding contract.
+
+---
+
+## Subagent spawn contract (applies to every Task call)
+
+When a step skill instructs you to spawn a subagent, the prompt you pass MUST include three pieces near the top:
+
+1. **`research_query` — verbatim, block-quoted** from `research/query-<vault_tag>.md`. Do not paraphrase, do not summarize.
+
+2. **Pipeline position statement.** One sentence naming what step the subagent runs in, what came before, what comes after. Example: *"You are step 5 (depth investigator) of the hyperresearch V8 pipeline. Step 4's loci analysts produced `research/loci.json`; after you return, step 6 will reconcile your committed position against the other investigators'."*
+
+3. **The subagent's specific inputs** (vault_tag, output_path, locus, etc.). Each step skill's spawn template documents the required fields.
+
+Skipping any of these in a Task prompt is a process violation.
+
+---
+
+## Recovery: if you wake up uncertain where you are
+
+Context compaction may eat parts of this conversation. If you're unsure what step you're on:
+
+1. **Check the TodoWrite list.** It carries integer step numbers and survives compaction.
+2. **Check disk artifacts.** Each step writes a canonical artifact:
+ - Step 1: `research/scaffold.md`, `research/prompt-decomposition.json`, `research/temp/coverage-matrix.md`
+ - Step 2: vault notes tagged with vault_tag (`$HPR search "" --tag <vault_tag> -j`)
+ - Step 3: `research/temp/contradiction-graph.json`, `research/temp/consensus-claims.json`
+ - Step 4: `research/loci.json`
+ - Step 5: vault notes with `type: interim` (`$HPR search "" --tag <vault_tag> --type interim -j`)
+ - Step 6: `research/comparisons.md`
+ - Step 7: `research/temp/source-tensions.json`
+ - Step 8: `research/corpus-critic-gaps.json`, `research/temp/corpus-critic-results.md`
+ - Step 9: `research/temp/evidence-digest.md`
+ - Step 10: `research/temp/draft-{a,b,c}.md` (or `research/notes/final_report.md` for light tier single-pass)
+ - Step 11: `research/temp/synthesis-plan.md`, `research/temp/synthesis-outline.md`, `research/temp/synthesis-pass1.md`, `research/notes/final_report.md`
+ - Step 12: `research/critic-findings-{dialectic,depth,width,instruction}.json`
+ - Step 13: `research/temp/post-critic-fetch-log.md`
+ - Step 14: `research/patch-log.json` (and edited final_report.md)
+ - Step 15: `research/polish-log.json` (and edited final_report.md)
+ - Step 16: `research/readability-recommendations.json`, `research/readability-decisions.json` (and edited final_report.md)
+3. **Find the highest-numbered step whose artifact exists.** Resume from the next step.
+4. **Re-invoke this entry skill** if you've lost track entirely: `Skill(skill: "hyperresearch")`. It loads fresh.
+
+If you're ever uncertain what to do next, the answer is: re-read this file and find the next step in the tier sequence.
+
+---
+
+## Final integrity gate (after step 16)
+
+Once step 16 returns, run the integrity check:
+
+```bash
+for f in research/critic-findings-dialectic.json \
+ research/critic-findings-depth.json \
+ research/critic-findings-width.json \
+ research/critic-findings-instruction.json \
+ research/patch-log.json \
+ research/polish-log.json; do
+ test -f "$f" || echo "MISSING: $f"
+done
+```
+
+(Skip critic-findings-{dialectic,depth} if standard tier — only width + instruction critics ran.)
+
+Then run lint:
+```bash
+$HPR lint --rule wrapper-report --json
+$HPR lint --rule locus-coverage --json
+$HPR lint --rule scaffold-prompt --json
+$HPR lint --rule patch-surgery --json
+```
+
+If any rule returns `error` severity issues, address them before declaring complete. Then ship: the final report lives at `research/notes/final_report.md`.
+
+---
+
+## Invariants you cannot break
+
+1. **PATCHING not REGENERATION after step 11.** Once step 11 produces the final report (or step 10 for light tier), modifications are surgical Edit hunks only.
+2. **One final report.** Step 11's synthesizer writes the final report ONCE. No re-synthesizing. (Light tier: step 10 writes it once.)
+3. **At least one dialectical locus.** Step 4 must surface ≥1 dialectical locus unless skip is justified.
+4. **Every interim note commits to a position.** Step 5 investigators end with `## Committed position`.
+5. **`research/comparisons.md` exists when loci count ≥ 1.** Step 6 is mandatory whenever step 4 produced any loci.
+6. **Steps are sequential at the outermost level, parallel within.** You cannot start step N+1 before step N completes. Within a step, parallelism is mandatory when there are multiple subagents.
+7. **Canonical research query is gospel everywhere.** Every subagent gets the verbatim query.
+8. **Hygiene rules apply to the final report only.** Workspace artifacts (scaffold, loci JSONs, interim notes, comparisons.md, patch log) can look however they need to look.
+9. **NEVER skip a step that the tier gate says to run.** For `full` tier, ALL 16 steps run. For `standard`, the prescribed 11 steps run. For `light`, the prescribed 5 steps run.
+10. **Step 10 triple-draft ensemble is MANDATORY for `standard` and `full` tiers.** You MUST spawn 3 `hyperresearch-draft-orchestrator` subagents. Writing `research/notes/final_report.md` directly in step 10 (instead of going through the synthesizer in step 11) is a PIPELINE VIOLATION for these tiers.
+11. **Step 11 synthesis is MANDATORY for `standard` and `full` tiers.** The synthesizer subagent (Read+Write tool-locked) writes the final report from the 3 drafts. The orchestrator does NOT write the final report itself for these tiers.
+12. **Subagents read full source text.** Draft sub-orchestrators MUST batch-read every note in their `must_read_note_ids` list before writing. Fetchers MUST chase 3-8 primary sources via citation chains.
+13. **NEVER emit a bare text response while subagent tasks are in flight.**
+
+---
+
+## Why V8
+
+V7 was one 1200-line skill loaded once. By Layer 4 (line ~2200 in a 3000-line conversation), context compaction had evicted the procedure. The orchestrator silently dropped Layer 3.7 (corpus critic), rewrote its todo to replace the triple-draft ensemble with a single draft, and produced a flat-scoring report. This happened in 100% of runs where the orchestrator didn't re-read the skill file.
+
+V8 makes re-reading structural. Each step skill is loaded fresh via the `Skill` tool at the moment it's needed. The procedure is in context exactly when it matters. Compaction can evict an old step's procedure — that's fine, the orchestrator never needs it again because each step is self-contained and reads its inputs from disk.
+
+The trade: 16 skill files instead of 1, plus 16 invocations of the `Skill` tool over the run. The cost is negligible; the reliability gain is the difference between Q57 (55.9, full pipeline) and Q9 (52.6, single-draft fallback).
+
+---
+
+## Now begin
+
+If you've read this far and the bootstrap (above) is done, invoke step 1:
+
+```
+Skill(skill: "hyperresearch-1-decompose")
+```
+
+If the bootstrap is NOT done, do the bootstrap first, then invoke step 1.
diff --git a/src/hyperresearch/skills/research-collect.md b/src/hyperresearch/skills/research-collect.md
deleted file mode 100644
index e6cd8e1..0000000
--- a/src/hyperresearch/skills/research-collect.md
+++ /dev/null
@@ -1,136 +0,0 @@
----
-name: research-collect
-description: >
- Enumerative coverage research. The user wants to know what exists, what
- happened, who did what — in full. Primary virtue is exhaustive per-entity
- coverage with every requested field. Sources are artifacts, official
- references, and anything that establishes ground truth on what's in the set.
----
-
-# Collect Protocol
-
-> You are in **collect** modality. The dispatcher routed you here because the output needs to enumerate a set of entities or facts, not advance a thesis. If the prompt said "for each X, provide Y / Z / W", the contract is clear: every X gets every field. If the prompt named a category without naming members, your job is to identify the significant members and cover them.
-
-Read the dispatcher (`.claude/skills/hyperresearch/SKILL.md`) for the process. This file is the SUBSTANCE reference for collect.
-
----
-
-## What collect is for
-
-| Prompt shape | Why it's collect |
-|---|---|
-| "For each Napoleonic marshal, cover key campaigns, defeat, and death" | Per-entity field list |
-| "Analyze the armor classes in Saint Seiya: for each significant character, provide power / technique / arc / fate" | Per-entity field list |
-| "List the major infrastructure bills passed between 2020 and 2025 with their key provisions" | Enumerative scope |
-| "What are all the endogenous opioid receptors and what does each do?" | Enumerative scope |
-| "Survey the state capitals of India and their major industries" | Per-entity field list |
-
-Collect is NOT for: "explain how X works" (synthesize), "which is best, X or Y" (compare), "will X happen in 2026" (forecast).
-
----
-
-## Source strategy
-
-Collect is **primary-source-heavy for the artifact itself, then secondary for the per-entity fields.**
-
-**Ground truth (first priority):**
-- Official / authoritative registries, directories, catalogs, databases — whatever lists the enumerable set
-- The primary artifact itself (if the subject is a text, franchise, or body of work)
-- For historical enumerations: primary documents, archival sources, official records
-- For scientific enumerations: peer-reviewed classifications, reference databases (NCBI, ChEBI, PDB, etc.)
-
-**Institutional signal (second priority):**
-- Encyclopedia entries (Wikipedia, domain-specific wikis — these are load-bearing for collect because they often *are* the enumerable set)
-- Reference books and field handbooks
-- Academic reviews that enumerate and classify
-
-**Practitioner triangulation (third priority):**
-- Named practitioners who have catalogued the set (niche experts, fandom compilers, historical societies)
-- Community-curated databases (TV Tropes, Fandom wikis, GitHub awesome-lists)
-
-**Commentary (de-prioritized):**
-- Listicles and "top N" posts are often derivative of the reference sources above. Use them only as leads, not as citations for per-entity facts.
-
-### Academic sweep — only if peer-reviewed literature enumerates the set
-
-Run Semantic Scholar / OpenAlex only if the enumerable set has a scholarly classification literature. For fictional / pop-culture / product / historical enumerations, skip it — the reference wikis and primary sources are the authoritative tier.
-
-### Adversarial round — MANDATORY, run all three before proceeding
-
-A collect report with no engagement with classification disputes is a transcription, not research. Run all three searches and **fetch at least one source that explicitly disputes the consensus list / classification**:
-
-```
-WebSearch("<topic> disputed contested membership classification")
-WebSearch("missing from <consensus list> <topic> overlooked")
-WebSearch("<topic> alternative classification non-mainstream taxonomy")
-```
-
-If the set has a "minor" / "non-canonical" / "rejected" / "lost" / "obscure" tier (e.g., apocryphal works, deprecated species, withdrawn standards), search for it explicitly and fetch one such source. The audit at Step 11 verifies at least one source flagged a missing or disputed member — a corpus that only contains consensus-list confirmations fails the comprehensiveness check.
-
-Specific dispute patterns to watch for: members the consensus list omits, members whose membership is contested, members that get grouped differently in non-mainstream sources, ordering / hierarchy disputes within the set.
-
----
-
-## Substance rules for Step 9 (writing)
-
-These are the collect-specific rules that layer on top of the dispatcher's shared writing constraints.
-
-### 1. The coverage contract is non-negotiable
-
-If the prompt says "for each X, provide Y / Z / W", the draft must deliver every X with every field. If the prompt named 108 entities, the draft covers all 108. If the prompt said "each significant X", YOU define the significance threshold explicitly in the scaffold (e.g., "named in ≥2 primary sources" or "featured in a canonical arc"), state it in the opening, and then honor it without silent downgrades.
-
-**Representative examples + thematic commentary is NOT a substitute for enumerative coverage.** If you cannot deliver the full set inside the draft, surface that to the user and ask — do not paper over it.
-
-### 2. Proportionate depth across entities
-
-Every entity the prompt asked about gets proportionate treatment. If Gold Saint #1 gets 200 words, Gold Saint #12 gets approximately 200 words. Deeply over-covering the famous entries and thin-covering the obscure ones is a violation — the prompt asked for "each", not "the ones you find interesting".
-
-### 3. Structured entity treatment is allowed and expected
-
-Collect is the one activity where **structured per-entity treatment** (including tight dossier-style subsections, roundup tables, or densely packed per-entity paragraphs) is the correct shape. You do NOT have to write full essayistic paragraphs for every entity. A per-entity subsection with clear field labels (technique, role, fate, outcome) and 2–4 sentences of prose per field is correct, efficient, and legible.
-
-However: **dense roundup is not license for bullet-only listicles.** Each field still needs a sentence of context or consequence, not just a 3-word noun phrase. And the section as a whole still needs an opening orientation paragraph and a closing analytical beat — the per-entity dossier is flanked by interpretive framing, not presented raw.
-
-### 4. Grouping is legitimate when the set is very large
-
-For sets larger than you can cover with individual treatment (100+ entities), group by natural categorical structure (rank, era, region, function). Every entity still appears, but less-significant entities can share a subsection with shorter per-entity lines. The scaffold's coverage checklist records the grouping strategy; the auditor verifies every entity from the source set is accounted for.
-
-### 5. Opening establishes the scope and the significance threshold
-
-The opening answers: *what is the set you're enumerating, how did you define its boundaries, and what significance threshold did you apply*. A reader must understand in the first 200 words what "every X" means in this draft. If the set has disputed membership, the opening names the dispute and states your inclusion rule.
-
-### 6. Closing synthesizes the set
-
-The closing section (before the Opinionated Synthesis) draws out what the enumeration as a whole reveals. This is where a collect draft earns its analytical beat: what pattern does the full set expose? What does the coverage reveal that no single entity could? This is NOT a thesis replacement — the draft is primarily enumerative — but every corpus-level report should have one moment where the whole is more than the sum.
-
----
-
-## Conformance checks (auditor reads this at Step 11, mode=conformance)
-
-When the auditor runs in conformance mode on a collect draft, it applies these checks in order. Each is a PASS / FAIL with a one-line quote from the report or the vault.
-
-(0) **Verbatim prompt check.** Open `research/scaffold.md` — does its first section contain the user's verbatim prompt (unchanged, not paraphrased)? FAIL if missing or modified.
-
-(1) **Coverage contract check.** Read the scaffold's "What the user explicitly asked for" section. For each explicit entity or field requirement, verify the draft delivers it. If the user said "for each of 108 Specters provide techniques and fate", count the draft's Specter entries and verify every entry has both fields. FAIL if any entity or field is silently dropped.
-
-(2) **Proportionate depth check.** Count substantive claims per entity across the draft (not raw word count — count assertions about the entity's attributes, actions, or fate). Flag any entity with less than ~50% the depth of the most-covered entity in the same category. FAIL if the draft over-develops the famous entries and thins the obscure ones.
-
-(3) **Scaffold + comparisons + extract artifacts exist.** Run `$HPR search 'scaffold' -j`, `$HPR search 'comparisons' -j`, and `$HPR note list --tag extract -j`. All must return non-empty. FAIL otherwise.
-
-(4) **Provenance chain.** Run `$HPR lint --rule provenance -j`. FAIL if any `--suggested-by` issues.
-
-(5) **Extract coverage.** Run `$HPR lint --rule extract-coverage -j`. FAIL if the extract:source ratio is below 30%.
-
-(6) **Opening scope + significance threshold.** Read the opening. Does it state what set is being enumerated, how boundaries were defined, and what significance threshold was applied? FAIL if any of the three is missing.
-
-(7) **Corpus-level analytical beat.** Read the closing body section (not the Opinionated Synthesis). Does it draw out a pattern the full set reveals? FAIL if the closing is just a transition to synthesis without a substantive pattern claim.
-
-(8) **Adversarial engagement.** Does the draft acknowledge at least one disputed / ambiguous / contested classification? FAIL if the enumeration is presented as uncontested when the adversarial search round found disputes.
-
-(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
deleted file mode 100644
index 8adeb16..0000000
--- a/src/hyperresearch/skills/research-compare.md
+++ /dev/null
@@ -1,177 +0,0 @@
----
-name: research-compare
-description: >
- Comparative evaluation research. The user wants to know which option is
- better for what, how alternatives differ, and which one to pick. Primary
- virtue is proportionate per-entity depth plus a committed recommendation.
- Covers vendor scans, tool evaluations, approach selection, and any
- prompt that names multiple alternatives.
----
-
-# Compare Protocol
-
-> You are in **compare** modality. The dispatcher routed you here because the output needs to evaluate N alternatives against each other and commit to a recommendation. The reader leaves knowing which option to pick and why, plus the conditions under which alternatives win.
-
-Read the dispatcher (`.claude/skills/hyperresearch/SKILL.md`) for the process. This file is the SUBSTANCE reference for compare.
-
----
-
-## What compare is for
-
-| Prompt shape | Why it's compare |
-|---|---|
-| "TigerBeetle vs Postgres vs FoundationDB for write-heavy workloads" | Named alternatives, explicit comparison |
-| "Which JavaScript framework should I pick for a new SaaS startup" | Unnamed set, evaluation ask |
-| "How does Kubernetes compare to Nomad for stateful workloads" | Two named alternatives |
-| "What's the best reinforcement learning approach for robotic manipulation" | Named alternatives, selection ask |
-| "Compare TLS 1.3 with QUIC for mobile apps" | Two named alternatives, comparison ask |
-
-Compare is NOT for: "what exists" (collect), "explain how X works" (synthesize), "will X win" (forecast — if the ask is future-tense).
-
-**Two variants:**
-1. **market-scan** — entity set is discovered through research (the user asked about a space, not specific alternatives)
-2. **comparison** — entity set is named explicitly in the prompt
-
-Both use this file. The variants differ only in how you acquire the entity list.
-
----
-
-## Source strategy
-
-Compare is a **3-tier source hierarchy** that privileges the artifact itself, then authoritative synthesis, then practitioner reality checks.
-
-### Ground truth (first priority — fetch for every entity)
-
-- Official product / project pages, feature lists, pricing pages, API documentation, release notes
-- Company filings, official announcements, specs
-- Benchmark results (both official and independent)
-- Source code / README / architecture docs for open-source entities
-- Standards documents (RFC, ISO, IEEE) when the entities implement a standard
-
-**For comparison variant:** fetch ground-truth sources for EACH named entity before moving to Tier 2. Imbalanced ground-truth coverage (entity A has 5 primary sources, entity B has 1) propagates to imbalanced body sections later.
-
-### Institutional signal (second priority)
-
-- Authoritative analyst reports and research firm writing
-- Named expert reviews and long-form evaluations by recognized practitioners
-- Academic / technical papers when the comparison is between methods rather than products
-- Industry benchmarking bodies and standards organizations
-
-**Paywall fallback:** when reports are gated: (1) search for "[report title] key findings"; (2) look for press coverage of the report; (3) find earlier free editions; (4) check the organization's free-publications section.
-
-### Practitioner triangulation (third priority)
-
-- Named practitioner postmortems and migration reports (the most honest signal in the ecosystem)
-- Conference talks with transcripts (by practitioners who built the thing, not evangelists)
-- StackOverflow canonical answers (accepted + high-upvote)
-- Community threads (Hacker News, Reddit, Lobste.rs) on specific failure modes
-- User reviews on professional review sites (not single-line "it's great" reviews)
-
-### Commentary (load-bearing only for reception, not facts)
-
-- News articles about product launches
-- Blog summaries by authors who haven't used the thing
-- Listicles
-
-Never use commentary as the sole source for a factual claim about an entity. Use it only to characterize positioning or reception.
-
-### Adversarial round — MANDATORY, run all four before proceeding
-
-Required — specifically for the market leader. A compare report without at least one source critical of the dominant entity is advocacy, not evaluation. **Fetch at least one source that explicitly criticizes the leading entity** (a postmortem, a "why we migrated away" blog, a dissenting analyst report, a public outage retrospective, a regulatory complaint).
-
-```
-WebSearch("<market-leader entity> problems limitations")
-WebSearch("<market-leader entity> alternatives why leave")
-WebSearch("moving away from <market-leader entity>")
-WebSearch("<method A> vs <method B> when <method A> wins")
-```
-
-The audit at Step 11 verifies at least one body section engages the critique with substance. A compare draft that recommends X without engaging "people who tried X and switched to Y" lacks the experiential evidence that distinguishes a real evaluation from a marketing summary.
-
-For symmetric comparisons (no clear leader, e.g., "Postgres vs MySQL"), run the adversarial searches against EACH entity — every option must have at least one critical voice in the corpus.
-
-### Academic sweep — only when comparing methods, not products
-
-If the comparison is between academic methods, algorithms, or theoretical approaches (e.g., "PPO vs SAC for continuous control"), run Semantic Scholar first. If the comparison is between products or services, skip the academic sweep and go straight to vendor docs + analyst reports.
-
----
-
-## Substance rules for Step 9 (writing)
-
-These are the compare-specific rules that layer on top of the dispatcher's shared writing constraints.
-
-### 1. Scoring dimensions declared upfront
-
-The opening establishes WHICH dimensions the entities will be evaluated on — and WHY those dimensions matter for the user's question. "Throughput", "correctness guarantees", "operational complexity", "ecosystem maturity" are dimensions; "performance" alone is not. Dimensions should reflect where the entities actually differ, not generic attributes.
-
-A compare draft with undeclared or arbitrary dimensions is a set of entity descriptions pretending to be an evaluation. Declare them first; score against them throughout.
-
-### 2. Proportionate depth per entity is the PRIMARY substance rule
-
-Every entity named in the prompt (or discovered during market-scan) gets proportionate body coverage. If entity A has a 1,200-word section and entity B has a 400-word section, rebalance — either expand B's coverage or trim A's.
-
-**This rule holds regardless of section structure.** Whether the draft has per-entity sections, per-dimension sections, clustered sections, or prose-embedded comparisons, count substantive claims per entity across the whole body. If one entity ends up with half the coverage of another, the research was lopsided, not the draft.
-
-### 3. A mandatory comparison matrix
-
-Somewhere in the body there is a table (or equivalent structured view) that places every entity against every scoring dimension. This is non-negotiable — no compare draft is complete without it. If the prompt requests prose comparison over a table, the matrix can be rendered as a structured prose section ("On throughput: A leads with X; B follows at Y; C lags at Z because..."), but every entity must be parseable on every dimension in a single view.
-
-If a dimension cannot be scored for an entity (e.g., a private company with no public pricing), note the gap and explain why. Do not silently omit cells.
-
-### 4. A committed recommendation
-
-Compare drafts MUST end with a committed pick: "For [primary use case], use X because [reason]. For [condition A], Y wins because [reason]. For [condition B], Z wins because [reason]." "It depends" alone is not acceptable — it must be followed by the conditions that determine the answer.
-
-The recommendation is a claim the reader can act on, not a balanced list.
-
-### 5. Entities in tension, not in isolation
-
-Body sections must put entities in direct tension: "A and B both claim to handle C; the difference is that A does C1 well while B does C2 well." A draft that describes each entity in isolation and then synthesizes at the end is missing the comparative substance that justifies the modality.
-
-### 6. Opening establishes the question the evaluation answers
-
-What is the user trying to decide? The draft frames this explicitly in the opening, then every body section is a step toward that decision. The opening is NOT a description of the first entity — it is the problem statement + the dimensions the solution will be scored on.
-
-### 7. Entity sections open with mechanism, then method
-
-For each entity: first explain what it IS and HOW it works (mechanism), then what you DO with it (method / usage / interface). Readers evaluate alternatives best when they understand the underlying model, not just the surface API.
-
-### 8. Honest about maturity asymmetry
-
-If the entities have dramatically different maturity (A has 10 years of production use and benchmarks; B is a 2024 research prototype with no independent replication), flag this explicitly in the opening AND in each affected section. Treating asymmetric alternatives as if they were evenly characterized is a form of dishonesty — the reader needs to know the evidence bases are uneven.
-
----
-
-## Conformance checks (auditor reads this at Step 11, mode=conformance)
-
-(0) **Verbatim prompt check.** Open `research/scaffold.md` — does its first section contain the user's verbatim prompt (unchanged)? FAIL if missing or modified.
-
-(1) **All prompt-named entities appear.** If the prompt named specific entities, every one must appear in the draft with substantive coverage. FAIL if any named entity is missing or relegated to a passing mention.
-
-(2) **Scoring dimensions declared.** Read the opening. Are the comparison dimensions named and their relevance explained? FAIL if dimensions are undeclared or arbitrary.
-
-(3) **Proportionate depth per entity.** Count substantive claims per entity across the whole body. Flag any entity with less than ~50% the depth of the most-covered entity. FAIL if the draft over-develops one entity and thin-covers others.
-
-(4) **Comparison matrix present.** Find the matrix (table or structured prose). Verify every entity is scored on every declared dimension. FAIL if the matrix is missing, incomplete, or present only as a synthesis afterthought.
-
-(5) **Committed recommendation.** Read the recommendation section. Does it commit to a specific pick for the primary use case? If it uses "it depends", does it immediately enumerate the conditions and their answers? FAIL if the draft hedges without committing.
-
-(6) **Entities in tension.** Count body sections where entities are put in direct tension (not described in isolation). FAIL if fewer than two — isolation descriptions are not comparisons.
-
-(7) **Adversarial engagement with the market leader.** Find sources critical of the dominant entity. Is the draft's body engaging with those critiques, or is the recommendation a consensus echo? FAIL if there is zero engagement with dissent on the leader.
-
-(8) **Scaffold + comparisons + extract artifacts exist.** Run `$HPR search 'scaffold' -j`, `$HPR search 'comparisons' -j`, `$HPR note list --tag extract -j`. All non-empty. FAIL otherwise.
-
-(9) **Provenance chain.** Run `$HPR lint --rule provenance -j`. FAIL if any issues.
-
-(10) **Extract coverage.** Run `$HPR lint --rule extract-coverage -j`. FAIL if below 30%.
-
-(11) **Mechanism-before-method per entity.** Sample 3 entity sections. Does each open with mechanism (what it is, how it works) before method (how to use it)? FAIL if sections jump straight to usage without the underlying model.
-
-(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-forecast.md b/src/hyperresearch/skills/research-forecast.md
deleted file mode 100644
index fa19a7b..0000000
--- a/src/hyperresearch/skills/research-forecast.md
+++ /dev/null
@@ -1,169 +0,0 @@
----
-name: research-forecast
-description: >
- Forward-looking research. The user wants to know what will happen or
- what should be done. Primary virtue is a committed prediction or
- recommendation grounded in past + current state with an explicit time
- horizon. Sources are ground-truth statistics, institutional analysis,
- policy documents, and practitioner positioning. NOT academic papers.
----
-
-# Forecast Protocol
-
-> You are in **forecast** modality. The dispatcher routed you here because the output needs a committed position on something that has not yet happened: a prediction, a recommendation, a strategy. The reader leaves knowing what you expect / recommend and the reasoning chain that got you there. **Do not hedge.** Use probability language, not "it is possible".
-
-Read the dispatcher (`.claude/skills/hyperresearch/SKILL.md`) for the process. This file is the SUBSTANCE reference for forecast.
-
----
-
-## What forecast is for
-
-| Prompt shape | Why it's forecast |
-|---|---|
-| "Will US inflation stay above 3% through 2026" | Prediction |
-| "What should the US Navy do about the China shipbuilding gap" | Strategy / recommendation |
-| "How will LLM pricing evolve over the next 2 years" | Forward-looking |
-| "Is the AI bubble going to burst and when" | Prediction |
-| "What's the right architecture for building a trading firm in 2026" | Forward-looking recommendation |
-
-Forecast is NOT for: "what exists now" (collect), "how does X work" (synthesize), "which option is best today" (compare).
-
----
-
-## Source strategy
-
-Forecast is **secondary-heavy** — triangulation across many institutional perspectives matters more than any single primary source. BUT the forecast must still be **anchored in ground-truth** (official stats, filings, policy text). The structure is:
-
-**Ground truth (anchoring evidence):**
-- Official policy documents, regulatory filings, legislative text
-- Government statistics and economic data (central banks, national statistics offices, international bodies)
-- Company earnings guidance, SEC filings, official roadmaps and announcements
-- Primary datasets with time-series data for trend establishment
-
-**Time-horizon rule:** for 6–12 month forecasts, prioritize data from the last 12 months. For 3–5 year forecasts, prioritize structural trend data spanning 5–20 years. A short-horizon forecast built on 20-year structural data will miss the current regime; a long-horizon forecast built only on last-quarter data is noise-chasing.
-
-**Institutional signal (main triangulation layer):**
-- Research organizations and think-tanks relevant to your domain
-- Industry analysts and sector research firms
-- International organizations (IMF, OECD, World Bank for macro; ITU for telecom; IEA for energy)
-- Named economists, strategists, and domain experts in institutional roles
-
-**Find the right institutional voice for the domain.** Do not default to generic management consultants — find the analyst body with domain authority. Energy forecasts come from the IEA and industry-specific firms, not from McKinsey. Tech forecasts come from Gartner / IDC / 451 Research and specialized analysts, not general news.
-
-**Paywall fallback:** when reports are gated: (1) search for "[report title] key findings"; (2) press coverage of the report; (3) the organization's free-publications section; (4) earlier free editions.
-
-**Practitioner triangulation:**
-- Expert commentary — op-eds and essays by named practitioners (not anonymous)
-- Practitioner forecasts and positioning signals (how people operating in this domain are actually betting)
-- Conference keynotes with transcripts
-
-**Contrarian and dissenting voices:** independent analysts who challenge the consensus. These are load-bearing for forecast — the contrarian case is not optional; it must be represented with substance.
-
-### Do NOT run academic API sweeps
-
-Academic papers are the wrong sources for forecasting. Citation-ranked scholarship describes what's known about the past, not what will happen. Skip Semantic Scholar / arXiv / OpenAlex / PubMed for forecast queries.
-
-### Adversarial round — MANDATORY, run all five before proceeding
-
-A forecast without explicit engagement with the failure case is not analysis — it is advocacy. Run all five searches and **fetch at least one source that explicitly argues the bear case** (a contrarian analyst report, a named-skeptic op-ed, a historical-failure post-mortem):
-
-```
-WebSearch("<topic> bear case downside risk")
-WebSearch("<topic> contrarian view dissenting forecast")
-WebSearch("why <dominant forecast> is wrong")
-WebSearch("<topic> worst case scenario")
-WebSearch("<topic> historical failure analogous case")
-```
-
-The audit at Step 11 verifies the bear case gets substantive coverage — at minimum a full paragraph engaging the contrarian position at its strongest, ideally a full section. A one-paragraph dismissal is strawmanning, not stress-testing.
-
-If the dominant forecast has a named skeptic (e.g., "consensus says soft landing but Roubini predicts X"), search for the skeptic by name. Named-contrarian search produces sharper dissent than generic "criticism of X".
-
----
-
-## Substance rules for Step 9 (writing)
-
-These are the forecast-specific rules that layer on top of the dispatcher's shared writing constraints.
-
-### 1. Commit to a position
-
-The draft is built around a committed forecast or recommendation. Use probability language: "more likely than not", "substantial probability", "unlikely unless", "approaches certainty in the 12-month horizon". Do NOT use hedge language: "it is possible", "some experts believe", "time will tell". Probability language commits to a distribution; hedging commits to nothing.
-
-### 2. Time horizon is explicit
-
-Every forecast claim carries a time scope. If the user specified a horizon ("what happens by 2026"), deliver claims scoped to that horizon. If the prompt is silent on time, distinguish between:
-- **Short-term** (6–12 months): near-certain / high-confidence dynamics
-- **Medium-term** (1–3 years): trend-dependent, structural moves
-- **Long-term** (3–5+ years): speculative, path-dependent
-
-A forecast that conflates short- and long-term claims is incoherent. Either scope every claim or dedicate sections to each horizon.
-
-### 3. Directional commitment in the body, not only synthesis
-
-At least one substantive body section must take a clear directional stance — a claim about what will happen or what should be done. "The synthesis will take a position" is not sufficient. The reasoning has to commit along the way, not just at the end.
-
-If the user requested scenario-neutral analysis (e.g., "outline optimistic, central, and bear cases"), directional commitment lives *within each scenario branch*. Each scenario has a named probability and its own committed path — the branching is not an escape from commitment.
-
-### 4. Engage the contrarian case with substance
-
-Find the strongest argument against your forecast / recommendation. Give it real engagement — at minimum a full paragraph, ideally a full section. Represent it at its strongest. Then explain why you reject it.
-
-If the consensus view gets 3 sections of analysis, the bear case deserves comparable substantive coverage. A one-paragraph dismissal of dissent is strawmanning, not stress-testing.
-
-### 5. Historical precedent grounds the prediction
-
-Anchor forward-looking claims in at least one analogous historical case. "This looks like 1998-99 in tech valuations" is stronger than "valuations are high". If the domain is genuinely unprecedented (which is rare), say so explicitly and explain why past cases don't apply.
-
-A forecast with zero historical grounding has no epistemic floor — it is a guess.
-
-### 6. Tier weighting
-
-Anchor the forecast in `ground_truth` sources (official statistics, filings, policy text). Use `institutional` (analyst reports, think-tanks) for consensus positioning. Use `practitioner` (expert commentary, positioning signals) and `commentary` (contrarian op-eds) for the bear case and dissent.
-
-Do NOT build a forecast on `commentary` alone. A forecast grounded in news opinions is an opinion amplifier, not a forecast.
-
-### 7. Opening frames the decision and the forces
-
-The opening answers: *what decision or question is this answering, and what are the 3–5 forces that will determine the outcome*. The reader understands in the first 300 words what is at stake and what the draft is actually measuring.
-
-### 8. Explicit "what would change my mind"
-
-The draft must include — in the body or in the synthesis — a statement of what evidence would shift your position. "My forecast of X would flip if Y happens, because Z" is load-bearing: it separates a real forecast from a religious conviction.
-
----
-
-## Conformance checks (auditor reads this at Step 11, mode=conformance)
-
-(0) **Verbatim prompt check.** Open `research/scaffold.md` — does its first section contain the user's verbatim prompt (unchanged)? FAIL if missing or modified.
-
-(1) **Committed position stated.** Read the opening and the synthesis. Is there a clear committed forecast / recommendation? FAIL if the draft hedges without committing or hides commitment behind "it depends" language alone.
-
-(2) **Probability language, not hedge language.** Sample 10 predictive claims in the body. Do they use probability language ("more likely than not", "substantial probability", "unlikely unless") or hedge language ("it is possible", "some experts believe")? FAIL if hedge language dominates.
-
-(3) **Time horizon explicit.** Every forecast claim carries a time scope — either inline or via sectioning (short-term / medium-term / long-term). FAIL if horizon is ambiguous or claims conflate time scales.
-
-(4) **Directional commitment in the body, not only synthesis.** At least one substantive body section takes a clear directional stance, not just the Opinionated Synthesis. FAIL if commitment is wholly deferred to the closing synthesis.
-
-(5) **Contrarian case engaged with substance.** Find the bear-case section or engagement. Is it a substantive paragraph (or more), representing the opposing view at its strongest? FAIL if dissent is dismissed in one sentence or strawmanned.
-
-(6) **Historical precedent present.** Find at least one analogous historical case used to ground the prediction. FAIL if the draft makes forward-looking claims with zero historical anchoring AND does not explicitly justify why the domain is unprecedented.
-
-(7) **Tier weighting.** Are forecast claims anchored in `ground_truth` tier sources? Is any load-bearing claim resting solely on `commentary`? FAIL if commentary is the sole support for a substantive prediction.
-
-(8) **Scaffold + comparisons + extract artifacts exist.** Run `$HPR search 'scaffold' -j`, `$HPR search 'comparisons' -j`, `$HPR note list --tag extract -j`. All non-empty. FAIL otherwise.
-
-(9) **Provenance chain.** Run `$HPR lint --rule provenance -j`. FAIL if any issues.
-
-(10) **Extract coverage.** Run `$HPR lint --rule extract-coverage -j`. FAIL if below 30%.
-
-(11) **Opening frames the decision + forces.** Does the opening state what is being forecast, why it is uncertain, and what 3–5 forces will determine the outcome? FAIL if the opening is a history lesson or a definition.
-
-(12) **Explicit "what would change my mind" statement.** Find a statement of what evidence would flip the forecast. FAIL if no such statement exists.
-
-(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-layercake.md b/src/hyperresearch/skills/research-layercake.md
deleted file mode 100644
index ffcf35a..0000000
--- a/src/hyperresearch/skills/research-layercake.md
+++ /dev/null
@@ -1,512 +0,0 @@
----
-name: research-layercake
-description: >
- Deep research via the LAYERCAKE architecture — a 7-phase pipeline:
- prompt decomposition → width sweep → loci analysis → depth
- investigation → draft → four adversarial critics in parallel
- (dialectic / depth / width / instruction) → surgical patch pass →
- polish audit.
- The patcher and polish auditor are TOOL-LOCKED to Read + Edit: they
- cannot regenerate the draft, only apply surgical hunks. Invoke with
- /research-layercake.
----
-
-# Layercake — the default multi-agent research protocol
-
-This is the orchestrator. You are running it as Opus. The pipeline spawns specialized subagents in every layer; you do not do their work yourself. You coordinate, assemble evidence, write ONE draft, and ship.
-
-**Two canonical rules:**
-
-1. **PATCH, NEVER REGENERATE.** After the first draft is written (Layer 4), the draft is only ever modified by Edit hunks produced by the patcher (Layer 6) and the polish auditor (Layer 7). Both subagents are tool-locked to `[Read, Edit]`. Neither can Write a new draft. If a critic's finding would require rewriting a whole section, it escalates to you as a structural issue — not a rewrite. Keep hunks surgical: change as little as possible while addressing the issue.
-
-2. **ARGUE, DON'T JUST REPORT.** The layercake pipeline is engineered to push the final report toward argumentative density. Loci analysts must flag at least one dialectical locus (where sources disagree). Depth investigators must commit to a position at the end of every interim note — not just summarize. Layer 3.5 forces you to reconcile those positions in `comparisons.md` before drafting. Layer 4 requires every body section that touches a cross-locus tension to engage it explicitly. A descriptive "survey" draft is a pipeline failure, not a neutral output.
-
----
-
-## Subagent spawn contract (applies to every Task call you make)
-
-Every subagent in the pipeline needs context about **what they're for, where they sit in the pipeline, and what the user actually asked**. When you spawn ANY subagent via the Task tool, the prompt you pass must include the following three pieces — in this order, near the top:
-
-1. **`research_query` — verbatim, block-quoted.** The canonical user question. If `research/prompt.txt` exists, that file's content IS the research_query. Do not paraphrase, do not summarize, do not "clean up" — paste it character-for-character. This is every subagent's north star; an agent without the research_query in its prompt is guaranteed to drift off the user's ask.
-
-2. **Pipeline position statement.** One sentence naming what layer the subagent is running in, what came before, what comes after. Example: *"You are Layer 3 (depth investigator) of the layercake pipeline. Layer 2's loci analysts produced `research/loci.json`; after you return, Layer 3.5 will reconcile your committed position against the other investigators'."* This prevents subagents from doing adjacent layers' work (e.g., patchers trying to regenerate, critics trying to fix).
-
-3. **The subagent's specific inputs.** What the subagent prompt documents as its required fields (vault_tag, output_path, locus, etc.). These vary per subagent — see each agent's description for its schema.
-
-Skipping any of these three in a Task prompt is a process violation. A fetcher that doesn't see the research_query fetches URLs without context for why; a critic that doesn't see the pipeline position may patch the draft directly (it shouldn't); a patcher that doesn't see the research_query applies findings without the north-star check.
-
-Concrete Task-call template:
-
-```
-subagent_type: hyperresearch-<agent-name>
-prompt: |
- RESEARCH QUERY (verbatim, gospel):
- > {{paste contents of research/prompt.txt OR user's literal prompt here, character-for-character}}
-
- PIPELINE POSITION: You are Layer N of the 7-phase layercake pipeline.
- Prior layers: {{list what's already run and what artifacts they produced}}.
- After you: {{list what comes next and what it expects from your output}}.
-
- YOUR INPUTS:
- - <input_1>: <value>
- - <input_2>: <value>
- - ...
-
- {{Any agent-specific guidance beyond what's already in the agent's
- own prompt file.}}
-```
-
-This contract applies to ALL subagent Task calls — fetchers included. A fetcher that knows the research_query can make smarter quality calls ("is this URL relevant to *this* question?") than one fetching blind.
-
----
-
-## Inputs and setup
-
-**Canonical research query.** Resolve the same way the single-pass `/research` skill does:
-
-- If `research/prompt.txt` exists, read it. Its contents are the canonical research query. GOSPEL.
-- Otherwise, use the user's verbatim prompt as the canonical research query.
-- Extract wrapper requirements separately: required save path, citation format, terminal-section shape, wrapper contract. These are binding but NOT part of the query.
-- If `research/wrapper_contract.json` exists, read it — it encodes forbidden body sections and required terminal sections for the ambient wrapper.
-
-**Vault tag.** Generate a short slug from the canonical query. Every note created during this run gets this tag so you can scope searches later.
-
-**Modality.** Classify the query by cognitive activity the same way `/research` does: collect / synthesize / compare / forecast. The modality file lives at `.claude/skills/hyperresearch/SKILL-<modality>.md`. You will read it before writing the Layer 4 draft.
-
-Write all of this to `research/scaffold.md` before Layer 1 starts. Use the same scaffold template the single-pass skill uses (see `.claude/skills/hyperresearch/SKILL.md` Step 7). The scaffold is your private planning document — it MUST NOT appear anywhere in the final report.
-
----
-
-## Layer 0.5 — Prompt decomposition
-
-**Goal:** before any research happens, decompose the user's prompt into its atomic items. This artifact is read by the instruction-critic in Layer 5 and by the final draft in Layer 4 to make sure the pipeline doesn't drift from what was actually asked.
-
-**Why this layer exists:** the single dimension where the pipeline has the widest variance is whether the draft structurally mirrors the prompt. When the prompt asks for "for each significant character, describe techniques / arcs / fate" and the draft produces per-character sections with those three fields in order — that's a structural match, high instruction-following. When the prompt asks the same thing and the draft organizes around thematic analysis with characters mentioned as illustrations — that's a structural mismatch, even if every fact is in there. The decomposition makes the structural requirement explicit, in writing, BEFORE drafting.
-
-### Procedure
-
-1. Re-read the canonical research_query end to end.
-2. Walk through it and extract every atomic item — anything that's a discrete thing the prompt named. These fall into categories:
- - **Sub-questions** — explicit or implicit questions the draft must answer ("What cues influence this?" → atomic: "cues influencing X")
- - **Named entities / categories** — every character, product, company, concept, time period, etc. the prompt names by name
- - **Required formats** — "mind map", "ranked list", "FAQ", "tabular", "scenario matrix", etc.
- - **Required sections** — "include X section", "end with Y", "begin with Z"
- - **Time horizons** — "through 2027", "next 12 months", "historical through 2010-present"
- - **Scope conditions** — "for non-academic contexts", "under SIL-4 constraints"
-3. **Produce `required_section_headings`.** This is the single highest-leverage field. It is an ordered array of literal H2 heading strings the draft MUST emit in order. Population rule:
- - If the prompt contains enumerated asks (regex `\b\d[.\)]` such as "1)", "1." or leading phrase "List X, Y, Z" / "cover the following:"), produce one entry per enumerated item, in prompt order, with the prompt's verbatim noun-phrase as the heading slug.
- - If the prompt names N entities in a list and asks to "discuss", "analyze", "describe", or "evaluate" each, produce one heading per entity.
- - Otherwise, leave the array **empty**. Narrative prompts ("Write a paper about X", "How did Y happen?") do not force structure — the drafter picks its own spine.
-
- Example (prompt: "Your report should: 1) List major manufacturers... 2) Include images... 3) Analyze primary use cases... 4) Investigate market penetration across North America, Japan/Korea, Southeast Asia, South America"):
- ```json
- "required_section_headings": [
- "## 1. Major Manufacturers, Device Models, and Configurations",
- "## 2. Images of Representative Devices",
- "## 3. Primary Use Cases and Deployment Scenarios",
- "## 4. Regional Market Analysis"
- ]
- ```
-
-4. Write `research/prompt-decomposition.json`:
-
-```json
-{
- "sub_questions": [
- "What is the specific question this addresses?",
- "..."
- ],
- "entities": [
- {"name": "Bronze Saints", "type": "category", "required_fields": ["techniques", "arcs", "fate"]},
- ...
- ],
- "required_formats": [
- "mind map of causal structure",
- "5-tier support/resistance table"
- ],
- "required_sections": [
- "## Opinionated Synthesis (if wrapper_contract demands it)"
- ],
- "required_section_headings": [
- "## 1. Major Manufacturers, Device Models, and Configurations",
- "## 2. Images of Representative Devices",
- "## 3. Primary Use Cases and Deployment Scenarios",
- "## 4. Regional Market Analysis"
- ],
- "time_horizons": ["2010-present", "12-month forward"],
- "scope_conditions": ["urban rail specifically, not mainline"]
-}
-```
-
-5. Every atomic item you put here becomes a draft requirement in Layer 4 and a critic-verifiable check in Layer 5. If you leave an atomic item out of the decomposition, the instruction-critic won't catch it. **Omit nothing the prompt names explicitly. List every numbered ask, every named entity, every format cue as a separate atomic item, even if they feel redundant.** The critic catches false-positive atomic items cheaply; it cannot catch false-negatives.
-
-6. **Do NOT include wrapper-contract requirements here** — those live in `research/wrapper_contract.json` separately. The decomposition is ONLY about what the user's actual prompt named.
-
-**Exit criterion:** `research/prompt-decomposition.json` exists, is valid JSON, and every atomic item in it can be pointed at a specific passage of the research_query.
-
----
-
-## Layer 1 — Width sweep
-
-**Goal:** cover the topical corners of the query with 30–80 curated sources before any depth investigation starts.
-
-1. **Academic APIs first.** For topics with a research literature, hit Semantic Scholar / arXiv / OpenAlex / PubMed BEFORE web search. Academic APIs return citation-ranked canonical papers; web search returns derivative commentary.
-
-2. **Plan the URL queue.** Aim for at least 30 URLs spanning:
- - Top-cited canonical sources on the core topic
- - Recent (last 2 years) developments
- - At least one adversarial angle ("criticism of X", "limitations of Y")
- - Obviously off-center corners (related subfields the query brushes against)
-
-3. **Parallel fetcher batches.** Spawn `hyperresearch-fetcher` subagents via the Task tool with URL lists. Batch sizes of 4–8 URLs per fetcher. Spawn multiple fetchers in a single message when they're independent — that's parallel execution.
-
-4. **Fetcher must tag every new note** with your `<vault_tag>`. Seed fetches (URLs you found directly from search, not from another note) omit `--suggested-by` entirely. Do NOT invent breadcrumb tokens like `layercake-seed` — placeholder breadcrumbs are a process violation.
-
-5. **Curation happens inline.** The fetcher already deprecates junk and writes summaries. You monitor: if >30% of fetches come back as junk, the URL queue was bad — reassess before continuing.
-
-**Exit criterion for Layer 1:** at least 20 substantive (non-deprecated) notes in the vault tagged with `<vault_tag>`. If you fall short after two fetcher rounds, tell the user the topic is under-resourced and proceed anyway; the loci analysts will flag the shortfall.
-
----
-
-## Layer 2 — Loci analysis (parallel, 2 analysts)
-
-**Goal:** identify 1–6 specific questions where depth investigation will pay off.
-
-1. **Spawn 2 `hyperresearch-loci-analyst` subagents in parallel.** Both read the same width corpus but return independently. Pass each:
- - `research_query` — canonical, verbatim
- - `corpus_tag` — `<vault_tag>`
- - `analyst_id` — `a` for one, `b` for the other
- - `output_path` — `research/loci-a.json` and `research/loci-b.json`
-
-2. **Wait for both.** If one fails, proceed with the single successful output. If both fail (empty loci lists), tell the user the width sweep was too thin and stop — do not force depth on a weak corpus.
-
-3. **Deduplicate and clamp to 6.**
- - Read both JSON outputs.
- - Dedupe on `name` (exact match) or near-match (same core question, different phrasing). When in doubt, prefer the entry with stronger `corpus_evidence`.
- - If the deduped list exceeds 6, drop the weakest entries — rank by how load-bearing the rationale is for the canonical research query.
- - The deduped, clamped list is authoritative. Write it to `research/loci.json`.
- - **Persist both analysts' `skip_loci` arrays** in the same file — union them under a top-level `skip_loci` key. These justifications matter downstream: the `locus-coverage` lint rule can cross-reference them when an interim note is "missing" to distinguish real investigator failure from legitimate skip. Schema: `{"loci": [...deduped-clamped...], "skip_loci": [...union from both analysts...]}`.
-
-4. **Decide investigator count.** You spawn ONE depth-investigator per locus, capped at 6. If only 1 locus passes dedupe, spawn 1. The cap is a cost control — depth investigators can each fetch up to 10 new sources, and 6 × 10 = 60 new sources on top of the width corpus is already a lot.
-
-**Placeholder-breadcrumb ban reminder:** depth investigators will fetch sources; make sure your instructions to them match what the fetcher will accept. Do not hand them breadcrumb placeholders like `layercake-locus-seed` — use real source note ids from the vault or omit `--suggested-by` entirely.
-
----
-
-## Layer 3 — Depth investigation (parallel, K = len(loci))
-
-**Goal:** produce ONE `interim-{locus}.md` note per locus with dense synthesis that the orchestrator will draft from in Layer 4.
-
-1. **Spawn K `hyperresearch-depth-investigator` subagents in parallel.** Pass each:
- - `locus` — the full locus object from `research/loci.json`
- - `research_query` — canonical, verbatim
- - `corpus_tag` — `<vault_tag>`
-
-2. **Each investigator writes ONE interim note** into the vault with `type: interim` and tags `<vault_tag>` + `locus-<locus-name>`. Return value is the note id.
-
-3. **Wait for all K to complete.** Investigators can fail independently. Proceed with whichever succeeded. If >50% failed, reassess — the loci analyst may have produced un-investigatable questions.
-
-4. **Read the interim notes.** Before writing the draft, use `$HPR search "" --tag <vault_tag> --type interim --json` to list them, then `$HPR note show <id1> <id2> ... -j` to read them in one call. Hold the Committed Position sections in your context — they are the load-bearing input to Layer 3.5 and Layer 4.
-
----
-
-## Layer 3.5 — Cross-locus comparisons (orchestrator, bridge step)
-
-**Goal:** before drafting, reconcile the committed positions from all depth investigators. Produce `research/comparisons.md` — a short document naming 3–5 places where the loci conflict or complicate each other. This is the structural step that gives the single draft the argumentative density the old ensemble got from compiling three independent drafts.
-
-**Why this step exists:** the depth investigators each committed to a position on their own locus. Some of those positions will disagree with each other, some will reinforce each other, some will partially complicate each other. The draft must engage those cross-locus dynamics explicitly — not summarize each locus in isolation. Writing `comparisons.md` forces you (the orchestrator) to see the loci in cross-section before you open the draft.
-
-**This step is always-on.** Even single-locus runs produce `comparisons.md` — with that locus's committed position as the lone argumentative anchor the draft must engage. The document is different (one position distilled vs. 3–5 tensions reconciled) but the discipline of writing it down BEFORE drafting is the same, and the lint rules expect the file to exist whenever Layer 2 wrote `research/loci.json`.
-
-### Procedure
-
-1. **Lay out all committed positions.** For each interim note, read its `## Committed position` section. Write them down side-by-side in a scratch list.
-
-2. **Hunt for tensions.** Ask of every pair of positions:
- - Do they agree on the facts but disagree on what the facts mean?
- - Do they cite different evidence and reach opposite conclusions?
- - Does one locus's position assume something another locus's evidence complicates?
- - Is one locus's position a special case of another's general claim?
- - Do they converge on a conclusion but via different mechanisms (worth noting — convergence from independent paths is itself a finding)?
-
-3. **Pick the 3–5 strongest cross-locus dynamics.** Reject weak ones (loci that are simply orthogonal, or that restate each other). You want cross-locus relationships that a good final draft should actually wrestle with — not every possible pair.
-
-4. **Write `research/comparisons.md`:**
-
-```markdown
-# Cross-locus comparisons
-
-## Tension 1: <short name for the dynamic>
-
-- **Locus A** ([[interim-A]]) commits: <one-line committed position>
-- **Locus B** ([[interim-B]]) commits: <one-line committed position>
-- **The cross-locus dynamic:** <2–3 sentences naming exactly how they relate — conflict? convergence? complication? special case? Name the load-bearing disagreement or the load-bearing agreement.>
-- **How the draft should engage this:** <one sentence. Example: "Section on X must acknowledge that Y from Locus B undercuts the simple reading of Locus A" or "The recommendation should privilege Locus B's position because its evidence base is stronger on the point where they disagree.">
-
-## Tension 2: ...
-```
-
-5. **This document is the argumentative spine of your draft.** Every tension you name here must become a visible argumentative beat in the final report — a paragraph or section that engages the disagreement explicitly, not a one-line gesture. If you write `comparisons.md` with 4 tensions and the draft only visibly engages 1 of them, the insight score suffers.
-
----
-
-## Layer 4 — Draft (orchestrator, single pass)
-
-**Goal:** write ONE draft that weaves the width corpus with the depth interim notes AND engages the cross-locus tensions from `research/comparisons.md` AND mirrors the atomic items from `research/prompt-decomposition.json`, following the modality file's substance rules.
-
-1. **Re-read `research/prompt-decomposition.json`.** Every atomic item named there is a draft requirement. For each sub-question, the draft must answer it. For each named entity, the draft must address it (in a dedicated section, subsection, or paragraph, as the decomposition's structure implies). For each required format, the draft must honor it. You are mirroring the user's structure, not reorganizing the topic around your own analytical axes.
-
-2. **Re-read `research/comparisons.md`.** The tensions there are your argumentative spine. Keep the document open in your working context while drafting.
-
-3. **Read your modality file now.** Open `.claude/skills/hyperresearch/SKILL-<modality>.md` and apply its substance rules. Pay particular attention to the modality's insight-generation rules — these are the rules that push you from reporting evidence to interpreting it.
-
-4. **Read SKILL.md's Step 9 (draft conventions).** The dispatcher's drafting rules (citation placement, length discipline, visual-device encouragement, filler bans) apply to the layercake draft the same way they apply to a single-pass draft.
-
-5. **Structure the draft around the decomposition.** When the prompt named 5 entities in a list, the draft should typically have 5 sections or subsections in that order. When the prompt asked for a mind map, include a mind map. When the prompt named sub-questions A/B/C, answer them in that order. Your own analytical framing belongs in the synthesis section at the end — NOT as the body's structural spine. This single rule is the highest-leverage insight-following move available.
-
- **HARD GATE on `required_section_headings`.** If `research/prompt-decomposition.json` has a non-empty `required_section_headings` array, the draft's ordered top-level H2 list MUST equal that array element-wise before the body proceeds to the Opinionated Synthesis (or any terminal section). Every heading string from `required_section_headings` appears in order as a literal H2. Your own analytical framing (cross-tension narratives, methodological caveats, etc.) goes INSIDE those sections or inside the terminal Synthesis — NEVER as an additional top-level H2 that sits between or before the required headings. If `required_section_headings` is empty, this gate does not apply and you pick the spine.
-
-6. **Write the draft to `research/notes/final_report.md`.** Structure:
- - Opening paragraphs that state the thesis / framing. Your thesis must commit to a position — not "this report surveys X" but "X is true (or X is false, or X is the right frame) because..." — grounded in the cross-locus comparisons you identified.
- - Body sections mirroring the decomposition's structural cues. **Each body section that touches a tension named in `comparisons.md` must engage that tension explicitly** — by name, with a paragraph that commits to a reading of the disagreement, not just reports both sides.
- - Closing section per the modality rule. Where the modality demands a reasoned position (synthesize, compare, forecast), that position must visibly incorporate the strongest cross-locus tensions — not average them out into hedged prose.
- - Sources list — numbered `[N]` entries matching the inline `[N]` citations
-
-7. **Insight-generation rules (applied to every body section):**
- - **Commit, don't hedge.** Sentences like "some argue X while others argue Y" are allowed as setup but MUST be followed by "the evidence weighs toward X because Z" or an equivalent committed reading. Pure "on the one hand / on the other hand" prose is low-insight reporting.
- - **Interpret, don't just cite.** For every 2–3 citations, there should be at least one interpretive beat — a sentence or clause that draws a conclusion the sources themselves didn't draw. Interpretive density drives the insight dimension; descriptive citation stacks suppress it.
- - **Privilege committed investigator positions.** Each `## Committed position` section from a depth investigator is a claim the draft can cite directly ("our reading of the FRMCS evidence is that..." — then [N]). These are your strongest argumentative levers — use them, don't soften them into "the literature suggests...".
- - **Every body section argues, not just the synthesis.** A common failure mode is drafts that save commitment for the synthesis section and leave body sections in descriptive / reporting mode. That doesn't work — the body is where evidence is introduced, and the body is where arguments should LAND. Each H2 should end with (or contain) at least one sentence that commits to a reading of that section's evidence. "Here is how this evidence is best understood" belongs in every section, not just the final one.
- - **Weave named tensions INLINE with immediate resolution.** When a cross-locus tension from `comparisons.md` is relevant to a body section, engage it inline in that section — name the tension, quote the strongest version of each side, and commit to a reading — then move on. Do NOT gather tensions into a dedicated "Source Tensions" H2 at the end; that gives the reader an unresolved buffet. Reference-quality reports name tensions where they arise in the doctrinal or analytical flow and resolve them immediately.
- - **Prescriptive specificity when evidence supports it.** When an investigator's `## Committed position` contains a specific threshold, number, rule, or named mechanism, preserve that specificity in the draft. Do not soften "manufacturer liability attaches when handover warnings fall below 10 seconds at highway speeds" into "manufacturer liability attaches when warnings are too brief." The precision is the authority; softening it to LLM-directional language drops the report's prescriptive weight. If a recommendation in the draft reads abstract, ask yourself what specific threshold or rule the evidence supports, and say it.
-
-8. **Include inline citations.** Every load-bearing claim gets `[N]`. The `[N]` numbering is deterministic: first cited source is `[1]`, next new source is `[2]`, and so on. The Sources list at the end matches this numbering.
-
-9. **Honor wrapper contracts.** If `research/wrapper_contract.json` specifies a required terminal section (e.g., `## Opinionated Synthesis`), include it. If it specifies forbidden body sections, do not use them.
-
-10. **Hygiene.** The final report MUST NOT contain:
- - YAML frontmatter
- - Any scaffold-only section (the polish auditor strips these if they leak, but prevention is cheaper)
- - The user prompt verbatim
- - Literal "User asked:" or similar prompt-echo preambles
- - `research/comparisons.md` content verbatim — comparisons.md is planning, not body content
- - `research/prompt-decomposition.json` content verbatim — decomposition is planning, not body content
-
-10a. **Vocabulary prohibitions.** The following pipeline-internal terms are SCAFFOLDING. Never write them into reader-facing prose. Audits of past runs found them leaking into the body text of 13 of 15 final reports, and graders mark those reports down on readability and instruction-following. The polish auditor strips these as a backstop, but preventing the leak at draft time is cheaper than rewriting afterward.
-
- **Forbidden in body prose:** `Locus <N>`, `Tension <N>`, `comparisons.md` / `research/comparisons.md`, `committed reading`, `committed position` (as self-reference), `cross-locus`, `width corpus`, `depth investigation`, `layercake` / "layercake final report", `per the scaffold` / `from the scaffold`, bare `loci` when referring to pipeline taxonomy, `[[interim-report-*]]` wikilinks, `[I\\d+]` citation format.
-
- **When you need to reference a cross-locus tension captured in `comparisons.md`:** name the substantive dynamic the tension describes. Not "Tension 2" but "the isolation-versus-competition question." Not "Locus 3's verdict" but "the 500K-threshold evidence commits:". The reader does not know about loci, tensions, or comparisons.md — do not teach them the pipeline's internal vocabulary just to cite it.
-
- **When you cite an interim note:** use the `[N]` numeric citation that corresponds to it in the Sources list. The internal note id (`interim-report-*`) is never reader-facing.
-
- **"Loci" as a domain word** — if your topic is one where "locus" is a legitimate domain term (molecular biology, law, neuroscience), the ban applies only to pipeline-taxonomy usage. A sentence like "the coding locus lies within exon 3" is fine; "three loci converged on the same finding" is a leak.
-
-11. **Write-once.** You write this draft once. After this point, the draft is only modified by Edit hunks from the patcher and polish auditor. Do NOT re-draft.
-
----
-
-## Layer 5 — Adversarial critique (parallel, 4 critics)
-
-**Goal:** four independent findings lists against the single draft, each from a different adversarial angle. Each critic has its own role — they complement, not duplicate.
-
-1. **Spawn 4 critics in parallel.** In ONE message, invoke:
- - `hyperresearch-dialectic-critic` → `research/critic-findings-dialectic.json` (counter-evidence the draft missed or straw-manned)
- - `hyperresearch-depth-critic` → `research/critic-findings-depth.json` (shallow spots where interim notes could fill substance)
- - `hyperresearch-width-critic` → `research/critic-findings-width.json` (corpus clusters the draft ignores despite evidence)
- - `hyperresearch-instruction-critic` → `research/critic-findings-instruction.json` (atomic items from `research/prompt-decomposition.json` that the draft missed, under-covered, reordered, or reformatted)
-
-2. **Pass each critic:**
- - `research_query` — canonical, verbatim (GOSPEL — same text every critic sees)
- - `draft_path` — `research/notes/final_report.md`
- - `output_path` — one of the four paths above
- - `vault_tag` — `<vault_tag>`
- - For `instruction-critic` additionally: `decomposition_path` = `research/prompt-decomposition.json`
-
-3. **Wait for all four.** If one fails, you can proceed with three findings files, but log the absence to the run log — the patch pass is less robust with missing critic coverage. Do NOT skip the instruction-critic specifically — it's the only critic measuring prompt adherence, which is the dimension with the widest variance.
-
-4. **Do not read the findings yourself and apply them.** The patcher reads the findings. Your job is to hand them to the patcher.
-
----
-
-## Layer 6 — Patch pass (`hyperresearch-patcher`)
-
-**Goal:** apply critic findings to the draft as surgical Edit hunks. Zero regeneration.
-
-0. **Skip gate (optional — for advanced users).** Before spawning the patcher, check whether `research/skip-patcher.txt` exists. If it does, the invoker has requested that Layer 6 be bypassed for this run. In that case, skip steps 1–6 entirely and record a minimal log:
-
-```bash
-# Count findings across all four critic JSON files
-total=$(jq -s '[.[] | .findings | length] | add' \
- research/critic-findings-dialectic.json \
- research/critic-findings-depth.json \
- research/critic-findings-width.json \
- research/critic-findings-instruction.json 2>/dev/null)
-cat > research/patch-log.json <<EOF
-{"total_findings": ${total:-0}, "applied": [], "skipped": [{"reason": "patcher-skipped-by-invoker"}], "conflicts": [], "orchestrator_escalated": []}
-EOF
-```
-
-Then proceed directly to Layer 7 (polish auditor). Do NOT spawn the patcher and do NOT attempt to apply findings yourself — the skip flag is respected as-is. Most runs should not use this gate; it exists for users who want to compare draft quality with and without surgical patching.
-
-1. **Pre-create the patch log stub.** The patcher is tool-locked to `[Read, Edit]` — it cannot Write. Edit can only modify files that already exist. So you (the orchestrator) MUST write the canonical stub first, which the patcher will then Edit to populate:
-
-```bash
-echo '{"total_findings": 0, "applied": [], "skipped": [], "conflicts": [], "orchestrator_escalated": []}' > research/patch-log.json
-```
-
- The schema above is canonical. The patcher's only job on this file is to Edit the existing keys — `total_findings` becomes an integer, the four arrays get populated. **The patcher MUST NOT invent alternate schemas** like `{orchestrator_structural_fixes, patcher_hunks}` or counts-only variants. Downstream tooling assumes the canonical shape.
-
- If you skip this step the patcher will silently have nowhere to write its log, will inline the log in its response instead, and you may mis-capture or drop the data entirely. This has historically been the single most common Layer 6 failure mode — do not skip it.
-
-2. **Spawn the patcher ONCE.** Pass:
- - `research_query` — canonical, verbatim (same as every other subagent). The patcher checks every finding against this before applying; findings that don't serve the research_query are rejected.
- - `draft_path` — `research/notes/final_report.md`
- - `findings_paths` — list of the four critic JSONs (dialectic / depth / width / instruction)
- - `patch_log_path` — `research/patch-log.json` (already stubbed above)
-
-3. **The patcher is tool-locked to `[Read, Edit]`.** It physically cannot Write. It can only call Edit with old_string/new_string pairs, and its prompt requires each hunk to stay surgical. Its job is to: (a) apply each finding's patch as an Edit on the draft file, and (b) populate the pre-stubbed patch log via Edit on `research/patch-log.json`.
-
-4. **Read the patch log when it returns.** Check:
- - Did the patcher apply all `critical` findings? If any critical was SKIPPED, that's a pipeline blocker — resolve it yourself before Layer 7. Options: (a) reject the finding as invalid after re-reading the draft, (b) escalate to the user, (c) hand-craft an Edit to address it.
- - Did any findings CONFLICT? Look at the conflict log — if two critics disagreed and the patcher picked one, consider whether the discarded one was actually more important.
- - Did the patcher log a "patch too large" skip? That means a critic proposed regeneration in patch clothing. If the finding was critical, re-spawn the critic with a tighter suggestion, or address it yourself with multiple small hunks.
- - **Is the patch log still the empty stub `{"total_findings":0,"applied":[],"skipped":[],"conflicts":[],"orchestrator_escalated":[]}`?** If yes, the patcher failed to log — its Task result will contain the real log inline. Read the Task result, parse out the JSON, and write it to `research/patch-log.json` yourself via Bash so downstream lint rules see it.
-
-4a. **Handle `orchestrator_escalated` findings (structural restructures).** The patcher populates this array with findings where `requires_orchestrator_restructure: true` — most commonly, structural-mirror-check findings from the instruction critic (wrong H2 order / missing required heading / extra H2). The patcher's tool-lock cannot safely move / rename H2 sections, so YOU (the orchestrator) handle them here, before Layer 7:
- - For each entry, read the `issue` field to understand which H2 in the draft needs to move, be added, or be renamed.
- - Apply the restructure via hand-written Edit calls on `research/notes/final_report.md`. You have Write and Edit access — the tool lock only applies to the patcher and polish auditor subagents, not to you.
- - Preserve the body content within each H2 section — you are moving / renaming / inserting headings, not regenerating prose. If a new heading is added and its body needs fresh content, write a short evidence-grounded paragraph for it, citing notes from the width corpus or relevant interim notes.
- - Log what you changed in a new `research/orchestrator-restructure-log.md` file (plain markdown, one bullet per change) so downstream lint rules can see this step happened.
- - Never regenerate a whole section or the whole draft. The "patch not regenerate" invariant still binds you — you have broader tools but not broader license.
-
-5. **Do not apply the patches yourself.** You MUST spawn the patcher subagent. Do NOT call Edit directly on `research/notes/final_report.md` in Layer 6 — the patcher has the tool-lock invariants (surgical-hunk discipline, old-text exact match, conflict resolution, integrate-don't-caveat rule) baked into its prompt. Bypassing it defeats the entire adversarial-patch architecture. If the patcher returns an empty result or appears to have failed, re-spawn it — don't fall back to doing it yourself.
-
-6. **Do not re-spawn the patcher on the same findings** unless you've modified the findings. The patcher's second run on identical input is a waste.
-
----
-
-## Layer 7 — Polish audit (`hyperresearch-polish-auditor`)
-
-**Goal:** final hygiene + readability pass. Also tool-locked to `[Read, Edit]`.
-
-1. **Pre-create the polish log stub.** Same rule as Layer 6 — the polish auditor has `[Read, Edit]` only and cannot create a new file. Stub it first:
-
-```bash
-echo '{"applied": [], "escalations": []}' > research/polish-log.json
-```
-
-2. **Spawn the polish auditor ONCE.** Pass:
- - `research_query` — canonical, verbatim
- - `draft_path` — `research/notes/final_report.md`
- - `polish_log_path` — `research/polish-log.json` (already stubbed above)
-
-3. **The polish auditor strips:**
- - Hygiene leaks (YAML frontmatter, scaffold sections, prompt echoes)
- - Filler phrases ("It is worth noting", "Importantly", etc.)
- - Redundant sentences / paragraphs that restate prior content
- - Run-on sentences and over-long paragraphs (breaks into smaller units via Edit)
-
-4. **The polish auditor ESCALATES** structural mismatches (wrong format for the prompt, missing required sections, etc.) rather than fabricating content to fix them. Read the escalations in the polish log. If the escalation names a structural issue (e.g., "user asked for a ranked list; draft is unranked prose"), you have one shot to fix it — craft the restructure yourself with hand-written Edits, then ship.
-
-5. **Sanity-check net length.** Polish should have NEGATIVE net char delta. If the polish log shows positive net chars added, something went wrong — polish is for cutting, not expanding.
-
-6. **Do not apply polish edits yourself.** Same rule as Layer 6 — the polish auditor's tool lock is the mechanism. Calling Edit directly in Layer 7 bypasses the hygiene-check and filler-detection logic baked into the auditor's prompt. If the auditor returned empty, re-spawn it; don't do the work yourself.
-
----
-
-## After Layer 7: audit findings + lint gate
-
-0. **Required-artifacts integrity check.** Before declaring the run complete, verify every expected pipeline artifact exists. Run:
-
-```bash
-for f in research/critic-findings-dialectic.json \
- research/critic-findings-depth.json \
- research/critic-findings-width.json \
- research/critic-findings-instruction.json \
- research/patch-log.json \
- research/polish-log.json; do
- test -f "$f" || echo "MISSING: $f"
-done
-```
-
- If any artifact is missing, the responsible layer failed silently. Re-spawn the responsible agent ONCE with the missing output path as its explicit required output. If it fails a second time, write a minimal stub (`{"findings":[]}` for critic files, canonical empty-log schema for patch-log.json / polish-log.json) and log the failure in the run log before proceeding — never let a pipeline step leave a missing artifact.
-
-1. **Record the run.** Append to `research/audit_findings.json`:
-```json
-{
- "mode": "layercake",
- "run_id": "<iso timestamp>",
- "loci_count": <K>,
- "critical_findings_applied": <int>,
- "critical_findings_skipped": <int>,
- "polish_escalations": <int>,
- "final_word_count": <int>
-}
-```
-
-2. **Run the lint gate.**
-```bash
-$HPR lint --rule wrapper-report --json
-$HPR lint --rule locus-coverage --json
-$HPR lint --rule scaffold-prompt --json
-$HPR lint --rule patch-surgery --json
-```
-
-If any rule returns `error` severity issues, address them before declaring the run complete:
-- `wrapper-report`: scaffold leaked into the body — spawn the polish auditor once more with the specific leak flagged
-- `locus-coverage`: a locus identified in Layer 2 has no interim note in the vault — a depth investigator failed silently; do not re-run, just note it in the run log
-- `scaffold-prompt`: the scaffold's `## User Prompt (VERBATIM — gospel)` does not match `research/prompt.txt` exactly — fix the scaffold
-- `patch-surgery`: the draft's churn from Layer 4 → final exceeds the safety threshold — this is a red flag that regeneration snuck in somewhere; read the patch log and investigate
-
-3. **Ship.** The final report lives at `research/notes/final_report.md`. The wrapper's required save path (if any) is a separate copy — handle per the wrapper contract.
-
----
-
-## Invariants you cannot break
-
-1. **PATCHING not REGENERATION after Layer 4.** The draft is written once in Layer 4. Every modification after that is an Edit hunk from the patcher or polish auditor. If you catch yourself thinking "let me just rewrite this section," stop — that's a Layer 4 or Layer 6 issue to handle through the subagent, not a shortcut.
-
-2. **One draft.** You write the final report ONCE. Do not re-draft between Layer 4 and Layer 7. If the critics flag a structural issue that a patch cannot fix, resolve it by spawning a targeted helper with Edit tool (hand-craft Edit calls yourself) — never by re-writing from scratch.
-
-3. **At least one dialectical locus.** Unless a loci-analyst justifies its absence in `skip_loci` with specific evidence of a univocal corpus, Layer 2 must surface at least one `flavor: "dialectical"` locus. No dialectical locus + no justification = re-spawn the loci-analyst with a tighter prompt.
-
-4. **Every interim note commits to a position.** Depth investigators return a `## Committed position` section that takes a side. An interim note ending with descriptive summary only is defective — flag it and re-spawn that investigator with the committed-position requirement emphasized.
-
-5. **`research/comparisons.md` exists whenever loci count ≥ 2.** Layer 3.5 is mandatory when there are at least 2 loci to compare. Skipping Layer 3.5 causes the draft to report locus-by-locus instead of engaging cross-locus dynamics — that's the failure mode that tanks the insight score.
-
-6. **Depth investigators' outputs are interim notes, not prose sections.** You consume their synthesis and positions in Layer 4. You do not paste their text into the draft; you weave it and reconcile it against other investigators.
-
-7. **Layers are sequential at the outermost level, parallel within.** You cannot start Layer 2 before Layer 1 completes, Layer 3 before Layer 2 completes, Layer 3.5 before Layer 3 completes, Layer 4 before Layer 3.5 completes. Within a layer, parallelism is mandatory when there are multiple subagents (spawn them in one message).
-
-8. **Canonical research query is gospel everywhere.** Every subagent you spawn gets the canonical research query as an explicit input. Do not let wrapper instructions leak into their task prompts.
-
-9. **Hygiene rules apply to the final report only.** The scaffold, the loci JSONs, the interim notes, `comparisons.md`, the patch log — these are workspace artifacts and can look however they need to look. The `final_report.md` is the single artifact subject to frontmatter-strip, scaffold-strip, filler-strip rules.
-
-10. **Orchestrator scratch files live under `research/tmp/`.** Any test JSON you build while debugging a critic output, any Python assembly script, any `.pkl` / `.txt` / `build_*.py` helper — these go in `research/tmp/` or `<run_dir>/tmp/`. Never emit scratch files directly under `research/`. The top-level `research/` namespace is reserved for the canonical pipeline artifacts listed in the integrity check above.
-
----
-
-## Escalation hotlines
-
-- **Width sweep too thin** → tell the user, run Layer 2 anyway, expect weaker loci
-- **No dialectical locus returned** → re-spawn the loci-analyst once with an emphatic reminder that dialectical loci are mandatory unless the corpus is univocal. If the analyst still returns none, trust its skip_loci justification.
-- **Both loci analysts fail** → stop the pipeline, tell the user the corpus was insufficient
-- **>50% depth investigators fail** → stop, reassess loci quality with the user
-- **Interim note missing `## Committed position`** → re-spawn that investigator. Uncommitted interim notes are the root cause of descriptive drafts.
-- **Only 1 locus** → Layer 3.5 still runs; `comparisons.md` distills that locus's committed position as the lone argumentative anchor for the draft. Don't skip the file.
-- **Critic disagreement unresolvable by patcher** → you pick a side (higher severity wins); log to the run log
-- **Critical finding cannot be patched** → do not ship; address it (hand-craft Edit, or re-spawn targeted critic with tighter suggestion, or reject the finding with reason)
-- **Polish escalation on structural mismatch** → hand-craft the Edits yourself; do not expand polish auditor's scope
-
----
-
-## Why layercake
-
-The single-pass `/research` skill runs one investigator against the whole topic. Layercake sequences width first (to lay a map), then depth (to fill the rabbitholes the map revealed), then cross-locus reconciliation (Layer 3.5, to turn parallel depth packets into a coherent argument before drafting). The depth loci are *discovered from the width corpus* — they are not pre-assigned framings. That means the depth investigations track the evidence the query actually turned up, not framings we guessed before reading anything.
-
-Layer 3.5 is the insight-generation step. The old ensemble architecture generated argumentative density by compiling three independent drafts and letting the merger graft the strongest argumentative beats across them. Layercake substitutes a cheaper move: force each investigator to commit to a position, force the orchestrator to reconcile those positions before drafting, then draft once with the reconciliation as the argumentative spine. The insight gain of ensemble's 3×-draft strategy is available without actually running 3 full drafts — IF the Layer 3.5 reconciliation is done honestly.
-
-The adversarial critics + patcher + polish auditor are a checked commit on the draft: three independent readings flag issues, a tool-locked patcher applies them surgically, and a tool-locked polish auditor cuts the fat. The tool lock is the load-bearing invariant — it prevents the "just rewrite it" failure mode that plagues post-hoc review in long-running agent pipelines.
-
-If any layer's subagent fails, you can fall back to manual handling (hand-craft Edits via your own Edit tool, rerun a single critic, etc.). You cannot fall back to "re-draft from scratch" — that violates the core invariant.
diff --git a/src/hyperresearch/skills/research-synthesize.md b/src/hyperresearch/skills/research-synthesize.md
deleted file mode 100644
index 73d5b77..0000000
--- a/src/hyperresearch/skills/research-synthesize.md
+++ /dev/null
@@ -1,225 +0,0 @@
----
-name: research-synthesize
-description: >
- Interpretive and explanatory research. The user wants to know what
- something MEANS, how it WORKS, or WHY it is the way it is. Primary virtue
- is interpretation density — every paragraph fuses fact with an analytical
- claim. Covers everything from literary/humanities interpretation to
- conceptual explanation of scientific mechanisms.
----
-
-# Synthesize Protocol
-
-> You are in **synthesize** modality. The dispatcher routed you here because the output needs a defended thesis or a mechanism explanation — not enumeration, not comparison, not prediction. The reader leaves with an argument they can be persuaded by or disagree with.
-
-Read the dispatcher (`.claude/skills/hyperresearch/SKILL.md`) for the process. This file is the SUBSTANCE reference for synthesize.
-
----
-
-## What synthesize is for
-
-| Prompt shape | Why it's synthesize |
-|---|---|
-| "What does Blood Meridian's violence mean" | Thesis-driven interpretation |
-| "Explain how attention mechanisms work in transformers" | Mechanism explanation |
-| "Why did the Roman Republic collapse" | Causal / explanatory |
-| "What is Wittgenstein's private language argument and why does it matter" | Interpretive + conceptual |
-| "How does CRISPR-Cas9 edit DNA and what are its limitations" | Mechanism + critique |
-
-Synthesize is NOT for: "list all X" (collect), "which X is best" (compare), "will X happen" (forecast).
-
-**Two legitimate sub-shapes:**
-1. **Interpretive synthesis** — the subject is a text, work, tradition, cultural phenomenon, or philosophical position. The thesis is an interpretation. Sources are primary texts + established critical tradition + dissenting readings.
-2. **Mechanism synthesis** — the subject is a process, system, or phenomenon. The thesis is a mechanism explanation with WHY it works the way it does. Sources are peer-reviewed literature + authoritative technical references.
-
-The dispatcher picks synthesize when the output's primary virtue is *understanding*, regardless of which sub-shape applies.
-
----
-
-## Source strategy
-
-### If a peer-reviewed literature exists — academic API sweep BEFORE web search
-
-For mechanism synthesis, or interpretive synthesis where scholarly criticism is the dominant tradition: run the academic APIs first. Web search returns derivative commentary; academic APIs return citation-ranked canonical papers.
-
-**Semantic Scholar** — citation count + forward/backward chaining:
-
-```python
-import httpx, json, urllib.parse, os, time
-SS_KEY = os.environ.get("SS_API_KEY", "")
-HEADERS = {"x-api-key": SS_KEY} if SS_KEY else {}
-q = urllib.parse.quote("<topic>")
-url = f"https://api.semanticscholar.org/graph/v1/paper/search?query={q}&fields=title,year,citationCount,externalIds&limit=10"
-r = httpx.get(url, headers=HEADERS, timeout=15).json()
-papers = sorted(r["data"], key=lambda p: p.get("citationCount", 0), reverse=True)
-# Top 3 → backward chain (references) AND forward chain (citations)
-for p in papers[:3]:
- pid = p["paperId"]
- refs = httpx.get(f"https://api.semanticscholar.org/graph/v1/paper/{pid}/references?fields=title,year,citationCount&limit=30", headers=HEADERS, timeout=15).json()
- cits = httpx.get(f"https://api.semanticscholar.org/graph/v1/paper/{pid}/citations?fields=title,year,citationCount,isInfluential&limit=50", headers=HEADERS, timeout=15).json()
- time.sleep(0.4)
-```
-
-Backward chaining finds the foundational canon; forward chaining finds everything built on it in the last 3 years.
-
-**OpenAlex** for humanities, social science, medicine, or non-arXiv disciplines:
-
-```
-https://api.openalex.org/works?search=<topic>&sort=cited_by_count:desc&per-page=15&[email protected]
-```
-
-**arXiv** for cs / stat / q-bio / econ / math / physics:
-
-```
-https://export.arxiv.org/api/query?search_query=cat:cs.LG+AND+all:<topic>&sortBy=relevance&max_results=25
-```
-
-**PubMed eutils** for biomedical / clinical:
-
-```
-https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=<topic>&retmode=json&retmax=20
-```
-
-Feed PDF links directly to `$HPR fetch` — the fetcher handles PDF extraction automatically.
-
-### If the subject has no peer-reviewed literature — start with primary sources + guided reading loop
-
-For interpretive synthesis of pop-culture / contemporary / niche subjects where scholarly criticism is thin or absent, skip the academic sweep. The source strategy is:
-
-**Ground truth:** the primary work itself (if available online; substantial excerpts if not), author/creator interviews stating intent, official materials.
-
-**Institutional signal:** named critical essays, longform analyses, scholarly monographs, Wikipedia references harvest (curated for notability).
-
-**Practitioner triangulation:** professional reviews, interviews with domain experts, conference keynote transcripts.
-
-**Commentary (de-prioritized):** listicles and YouTube reviews — lead-generation only, not load-bearing.
-
-Use the **guided reading loop** from the dispatcher as the default discovery mechanism. The critical tradition for interpretive subjects is discoverable only by reading — the essay names three critics, those critics cite a 1998 monograph, the monograph references a specific passage.
-
-### Non-English sources when the subject has non-English reception
-
-If the subject has major non-English reception (a franchise bigger in France than the US, a philosopher with denser German scholarship, a movement with foundational French literature), run searches in those languages:
-
-```
-WebSearch("<topic> análise crítica") # Portuguese
-WebSearch("<topic> critique analyse") # French
-WebSearch("<topic> analisi critica") # Italian
-WebSearch("<topic> Kritik Rezeption") # German
-WebSearch("<topic> 批評 論文") # Japanese
-```
-
-Non-English sources count toward voice diversity at Checkpoint 1.
-
-### Adversarial round — MANDATORY, run all four before proceeding
-
-Find the strongest dissenting reading / dissenting mechanism explanation / dissenting theoretical position. Your thesis must engage it with substance, not a one-sentence dismissal. **Fetch at least one source that explicitly argues against the dominant interpretation.**
-
-```
-WebSearch("<topic> criticism limitations")
-WebSearch("against <dominant reading> <topic>")
-WebSearch("<topic> reappraisal revisionist new reading")
-WebSearch("<topic> overrated wrong contested")
-```
-
-The audit at Step 11 verifies at least one body section engages the dissenting reading with substance (a paragraph or more, not a sentence). A synthesize draft built entirely from sources that agree with each other is advocacy — the corpus must contain the strongest counter-voice you could find, even if your draft ultimately rejects it.
-
-If the dominant reading has a named opponent (e.g., "the Lacanians say X but Žižek argues Y"), search for the opponent by name, not just by topic. Named-critic search produces sharper dissent than generic "criticism of X".
-
-### Source diversity — at least one non-academic voice
-
-If the subject has practitioners (applied economists, engineers, policy analysts, industry users, operators), **at least one non-academic voice is mandatory.** A synthesize corpus built entirely of peer-reviewed papers plus lecture notes is a monoculture — the thesis loses its grip on reality when nobody in the corpus has actually *used* the thing.
-
-Examples of required non-academic voices:
-- "Is there a general method for solving first-price auctions?" — the academic corpus says "here are 5 methods"; an applied voice (FTC economist blog, procurement handbook, named practitioner postmortem) tells you whether any of them is actually used in the wild.
-- "How does CRISPR edit DNA?" — the academic papers explain the mechanism; a biotech industry voice (Moderna process description, patent litigation commentary) tells you which off-target effects matter in production.
-- "What does Blood Meridian mean?" — the scholarly tradition sets the interpretive axes; a named critic blog or longform essay brings the thesis into the present.
-
-Search for these explicitly:
-
-```
-WebSearch("<topic> in practice applied industry")
-WebSearch("<topic> practitioner guide used by")
-WebSearch("<topic> does anyone actually use")
-```
-
-If no such voice exists (genuinely novel topic, purely theoretical subject), state that explicitly in the scaffold and explain why — otherwise Checkpoint 1 flags the corpus as under-diverse.
-
----
-
-## Substance rules for Step 9 (writing)
-
-These are the synthesize-specific rules that layer on top of the dispatcher's shared writing constraints.
-
-### 1. Commit to a thesis
-
-The draft is built around ONE defensible claim: what you are arguing about the subject. State it clearly — ideally in a single short sentence in the opening — then spend the draft defending it.
-
-A thesis is NOT a summary ("Blood Meridian is about violence"). A thesis is an arguable position ("Blood Meridian's violence is structural, not expressive — it enacts a theological claim that human agency is a ventriloquism of geology"). A neutral reader could read your thesis and disagree.
-
-### 2. Interpretation density — every paragraph fuses fact with claim
-
-Every body paragraph must do both: report a fact / quote / source AND make an interpretive claim about what the fact MEANS within your thesis. A paragraph that only reports facts is a textbook excerpt, not synthesis.
-
-**Bad:** "Transformers use a self-attention mechanism. The mechanism computes a weighted sum where weights come from query-key similarity."
-
-**Good:** "Transformers use self-attention — but the substantive move is not the attention itself, it is what attention *replaces*. Recurrence imposes a temporal bottleneck: position N can only reach position N-1 through the sequence of hidden states. Self-attention obliterates this bottleneck and treats the sequence as a set, which is why transformers scale but LSTMs don't. The mechanism is a structural concession, not just an engineering trick."
-
-Every paragraph earns its place by advancing the thesis or complicating it — not by restating source material.
-
-### 3. Engage the strongest dissent
-
-Find the reading / explanation / theoretical position that most directly contradicts your thesis. Give it substantive engagement — at minimum a full paragraph, ideally a full section. Represent it at its strongest, not strawmanned. Then explain why you reject it.
-
-A thesis that never engages its opposite is advocacy, not argument.
-
-### 4. Sources in tension at least twice
-
-At least two body sections must put specific sources in direct tension: "Smith reads this passage as X; Jones reads it as Y. The textual evidence supports Z because..." This is the mark of synthesis — the reader sees you weighing evidence, not just citing it.
-
-### 5. Quote the primary source directly
-
-When the synthesis is interpretive, quote the primary work. Claim → direct quote → analysis of what the quote means. Paraphrase only when quotation is impossible or redundant.
-
-When the synthesis is mechanism-explanation, quote the canonical paper's own description of the mechanism before you extend it.
-
-### 6. Opening establishes the thesis AND the core tension
-
-The opening answers: *what am I claiming, and why is this claim non-trivial*. If the thesis is obvious, the draft has no reason to exist. Name the tension: the paradox, the received view you're pushing against, the open problem, the tradeoff. That's the engine that drives the rest of the draft.
-
-### 7. Section progression tracks the argument
-
-Sections build on each other. Section 2's claim depends on section 1's setup; section 3 complicates section 2; the dissenting-view section is placed where the argument is strongest, so the reader feels the weight of the opposition before they see your counter. A shuffled set of thematic sections is not synthesis — it is a collage.
-
----
-
-## Conformance checks (auditor reads this at Step 11, mode=conformance)
-
-(0) **Verbatim prompt check.** Open `research/scaffold.md` — does its first section contain the user's verbatim prompt (unchanged, not paraphrased)? FAIL if missing or modified.
-
-(1) **Thesis exists and is arguable.** Read the opening. Is there a clear thesis sentence? Is it a position a neutral reader could disagree with (not a neutral summary)? FAIL if the draft never commits to a claim.
-
-(2) **Interpretation density.** Sample 5 random body paragraphs. For each: does it fuse a factual / source claim with an interpretive claim about what the fact means? FAIL any paragraph that is pure description or pure source-citation without an analytical move.
-
-(3) **Dissenting view engaged substantively.** Find the section that engages the strongest opposing reading / explanation. Is the opposing position given a substantive paragraph (or more)? Is it represented at its strongest? FAIL if dissent is dismissed in one sentence or strawmanned.
-
-(4) **Sources in tension at least twice.** Count body sections where specific sources are put in direct tension. FAIL if fewer than two.
-
-(5) **Primary sources cited directly.** For interpretive synthesis: are there at least 3 direct quotations from the primary work? For mechanism synthesis: is the canonical source's own description of the mechanism quoted before the explanation extends it? FAIL if the draft only paraphrases.
-
-(6) **Section progression.** Can sections be shuffled without loss? If yes, the draft is a collage, not an argument. FAIL.
-
-(7) **Scaffold + comparisons + extract artifacts exist.** Run `$HPR search 'scaffold' -j`, `$HPR search 'comparisons' -j`, `$HPR note list --tag extract -j`. All must return non-empty. FAIL otherwise.
-
-(8) **Provenance chain.** Run `$HPR lint --rule provenance -j`. FAIL if any issues.
-
-(9) **Extract coverage.** Run `$HPR lint --rule extract-coverage -j`. FAIL if below 30%.
-
-(10) **Tier weighting.** Are substantive claims anchored in `ground_truth` or `institutional` sources? Are load-bearing claims ever supported only by `commentary`? FAIL if any load-bearing claim rests solely on derivative commentary.
-
-(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
deleted file mode 100644
index d296c13..0000000
--- a/src/hyperresearch/skills/research.md
+++ /dev/null
@@ -1,965 +0,0 @@
----
-name: research
-description: >
- Deep research on any topic. Classifies requests by cognitive activity
- (collect / synthesize / compare / forecast), not subject matter. Produces
- a sourced, adversarially-audited report with full data-flow provenance.
- Trigger: /research
----
-
-# Research Dispatcher
-
-The research protocol has ONE process spine (this file) and FOUR modality files that encode substance differences. Read this file end-to-end. Then read the modality file the classifier routes you to. Both are required.
-
-**There are no numeric targets in this protocol.** No word counts, no H2 counts, no words-per-section floors. A draft is as long as the substance demands and as short as the structure allows. The user's own scope cues (if any) are the only length guidance that applies.
-
-**The canonical research query is gospel in this session.** In a normal interactive run, that is the user's verbatim prompt. In wrapped runs (an invoking harness, higher-level orchestrators, etc.), a file at `research/prompt.txt` overrides the wrapper text and becomes the canonical research query for the scaffold and every downstream `research_query` parameter. It gets copied into the scaffold at Step 7 and every subsequent step re-reads it. Whenever you are unsure what to do, re-read the canonical query. Whenever the draft feels like it's drifting, re-read the canonical query. The auditor at Step 11 grades the draft against the canonical query — not against any abstract notion of quality.
-
-**Wrapper requirements are a SECOND contract, not part of the query.** The invoking environment may separately require a save path, citation format, or terminal section shape (for example a harness-required `## Opinionated Synthesis` block). Record those requirements separately in the scaffold and obey them. Do NOT paste wrapper instructions into the `## User Prompt (VERBATIM — gospel)` section — that section is reserved for the canonical research query only.
-
----
-
-## The 4 activities
-
-Research requests are classified by what the output needs to DO, not what the subject IS.
-
-| Activity | Question it answers | Primary virtue | Modality file |
-|---|---|---|---|
-| **collect** | "What exists / what happened / who did what" | Exhaustive enumerative coverage with per-entity fields | `.claude/skills/hyperresearch/SKILL-collect.md` |
-| **synthesize** | "What does it mean / how does it work / why" | Interpretive density — a defended thesis grounded in evidence | `.claude/skills/hyperresearch/SKILL-synthesize.md` |
-| **compare** | "Which is better for what / how do they differ" | Proportionate per-entity depth + a committed recommendation | `.claude/skills/hyperresearch/SKILL-compare.md` |
-| **forecast** | "What will happen / what should we do" | Committed prediction from past + current state with explicit time horizon | `.claude/skills/hyperresearch/SKILL-forecast.md` |
-
-**Subject matter does not decide the classification.** A query about a fictional franchise can be collect (per-character enumeration), synthesize (a thesis about what the franchise means), compare (this franchise vs another), or forecast (will this franchise's new arc succeed). A query about distributed databases can be any of the four. The classifier reads what the output should *do*, not what the subject *is*.
-
-**A single prompt can blend activities** — that is normal. Pick ONE primary and optionally ONE secondary flavor. The primary determines the process and the structural backbone; the secondary informs the substance rules at Step 9. Example: "Analyze Saint Seiya's armor classes: for each significant character, cover techniques, story arcs, fate — and develop a thematic argument about what the armor means" is **collect** (primary — the per-character enumeration is the backbone) + **synthesize** (secondary — thematic beats layered into each entity section).
-
----
-
-## Step 0: Clarify if vague
-
-If the request is vague or ambiguous, ask 1–3 focused questions before proceeding. Don't guess.
-
----
-
-## Step 0.5: Check existing vault coverage first
-
-```bash
-$HPR search "<topic>" -j
-```
-
-If the vault already has >10 relevant notes: tell the user, summarize what's there, and ask whether they want deeper research, a specific angle, or synthesis from existing notes. Don't re-fetch what's already curated.
-
----
-
-## Step 1: Classify + commit the canonical research query
-
-State your classification in writing BEFORE doing anything else.
-
-First resolve the canonical research query and the wrapper contract:
-
-- If `research/prompt.txt` exists, read it and use its contents EXACTLY as the canonical research query.
-- Otherwise, use the user's verbatim prompt as the canonical research query.
-- Separately extract any wrapper requirements from the current session instructions: required save path, required citation format, required closing block, harness-specific structure, or other packaging constraints. These are binding, but they are NOT part of the canonical query.
-
-Then copy the canonical research query into your working memory. This is the format you MUST output:
-
-```markdown
-## Canonical research query source
-<research/prompt.txt | live user prompt>
-
-## User Prompt (VERBATIM — gospel)
-> [paste the entire user message here, character-for-character. Do not
-> paraphrase. Do not summarize. Do not reformat. This text is the only
-> authoritative source for what the output should contain and look like.]
-
-## Session wrapper requirements
-- **Required artifact path:** <path or "none">
-- **Required citation contract:** <e.g. "[N] bracket citations only" or "none">
-- **Required terminal section(s):** <e.g. "must end with ## Opinionated Synthesis ..." or "none">
-- **Other wrapper constraints:** <anything else binding, or "none">
-
-## Primary activity
-<collect | synthesize | compare | forecast>
-
-## Secondary flavor (optional)
-<collect | synthesize | compare | forecast | none>
-
-## Output mode
-<description_only | description_with_takeaway | opinion_demanded>
-
-Pick by reading the prompt's request verbs:
-
-- **description_only** — the user asked for information, explanation, or enumeration. They want to understand something, not to hear your view on it. Typical verbs: "explain", "describe", "list", "provide", "detail", "elaborate", "tell me about", "summarize", "walk me through", "what is X", "how does X work", "for each X give Y".
-- **description_with_takeaway** — the user asked for description but also surfaced an angle of significance or meaning. They want the facts AND a short statement of what the facts amount to. Typical cues: "what does this mean", "why does this matter", "implications", "significance", "the big picture", "what's the upshot", "context".
-- **opinion_demanded** — the user asked for a committed position, argument, recommendation, or prediction. They want you to pick a side with reasoning. Typical verbs: "which is best", "should I / we", "recommend", "predict", "defend", "evaluate", "argue", "make the case", "pick", "is X true", "what's your take".
-
-When ambiguous between two, pick the less-committal option. `description_with_takeaway` is the safe middle default; only promote to `opinion_demanded` when the prompt is explicit about wanting your view.
-
-This field gates how much synthesis the draft produces at Step 12 (see that step for the scaling rule). It does NOT change what the body covers — the body always delivers what the prompt asked for, across whatever activity and secondary flavor you picked. Output mode only controls the synthesis tail unless the session wrapper explicitly requires a specific terminal section shape.
-
-## One-sentence justification
-<why this primary activity matches what the output needs to DO>
-
-## What the user explicitly asked for (extracted from the verbatim prompt)
-- **Explicit deliverables:** <list every specific ask — "answer A, B, C", "include a recommendation", "for each X give Y" — or "none">
-- **Explicit entities or items:** <every item named in the prompt, or "none">
-- **Explicit per-item fields:** <every field the prompt demands per entity — "power level / technique / fate" — or "none">
-- **Explicit structure:** <"one section per", "ranked list", "executive summary", etc., or "silent">
-- **Explicit format:** <prose / bullets / table / code / FAQ, or "silent">
-- **Explicit scope cues:** <"brief", "detailed", "deep dive", specific lengths, or "silent">
-- **Explicit ordering:** <chronological / by importance / custom, or "silent">
-
-## Core tension
-<what makes this question non-trivial — a paradox, a disagreement, a tradeoff,
-a constraint interaction, an open problem. One-to-three sentences. This is
-what the draft must earn its way through.>
-```
-
-Then **read the corresponding modality file with the Read tool.** The modality file tells you HOW to do the activity-specific parts (source strategy, substance rules, conformance checks). This dispatcher tells you WHAT steps to run and in what order.
-
----
-
-## Tiebreaker questions
-
-When two activities seem equally applicable:
-
-**collect vs compare** — Does the user want coverage ("tell me everything") or evaluation ("which is best")? Recommendation expected or entities set against each other → **compare**. Coverage is the point and no recommendation is requested → **collect**.
-
-**collect vs synthesize** — Does the output need a defended thesis or just complete coverage? If the user explicitly asks for interpretation, meaning, or analysis alongside enumeration, the primary is usually **collect** (the enumeration is the dominant ask) and the secondary flavor is **synthesize**. Pure enumeration without thesis → **collect**. Pure thesis without per-entity coverage → **synthesize**.
-
-**synthesize vs forecast** — Is the claim about what IS (how it works, what it means) or what WILL BE (prediction, recommendation)? Past/present → **synthesize**. Future → **forecast**.
-
-**compare vs forecast** — Is the user asking which option is best NOW or which will be best LATER? Now → **compare**. Later → **forecast** (often with compare flavor).
-
-**Any activity when the prompt contains "for each X, provide Y / Z / W"** — The explicit per-entity field list is a collection contract. Route to **collect** as the primary regardless of subject, with any interpretive / comparative / predictive framing as secondary flavor. The per-entity contract takes precedence because it is the most specific kind of user mandate.
-
----
-
-## Prompt fidelity — the gospel rule
-
-**Re-read the canonical research query at every checkpoint.** The query is inside the scaffold (Step 7). Every checkpoint re-opens the scaffold. Every time you re-open the scaffold, re-read the query first, then re-read the scaffold's `## Session wrapper requirements` section. Every structural decision must trace back to the canonical query, the wrapper contract, or a modality default that both are silent on.
-
-- If the canonical query specifies structure / format / entities / fields / ordering / scope: **the user's request is authoritative**. Modality defaults yield.
-- If the session wrapper specifies save path / citation contract / terminal section shape: **the wrapper is authoritative for packaging**. It does not change the substance the user asked for, but it does control how the deliverable must be surfaced.
-- If both the query and wrapper are silent on any point: **the modality default applies** to what they left open.
-- The modality file is authoritative for SUBSTANCE (interpretation density, proportionate depth, probability language, mechanism clarity). Substance rules hold regardless of shape.
-
-**Never negotiate the user's contract.** If the user asked for 108 entities and 4 fields each, you owe 108 × 4 data points. You do NOT get to substitute "representative examples + thematic commentary". You do NOT get to silently downgrade "each" to "the most important". If the user's contract seems impossible to satisfy within a reasonable draft, surface that tension to the user and ask — do not paper over it by producing less than what was asked.
-
----
-
-## Process discipline (applies to every activity)
-
-This protocol is **process-driven**. Each required step produces an **artifact** that a later step reads. Skipping a step does not save work — it breaks the dependency chain silently, and the later step operates on missing-but-pretended input. The draft then gets written without the tension analysis; the audit never fires; the report ships un-stress-tested.
-
-**Definition of task failure:** if a required artifact does not exist on disk or in the vault at the checkpoint where the next step expects it, the task has FAILED at that checkpoint. Failure is not fatal — it means: STOP the current step, return to the step that produces the missing artifact, complete it, and re-run the checkpoint. You may NOT compensate for a missing artifact by doing extra work inside the step that follows it.
-
-Read this section before doing anything else, then follow it literally. You will self-review four times in a single research session. If any review fails, you go back.
-
-### Required TODO list (build this immediately after Step 1 classification)
-
-Before executing Step 2, create this exact TODO list with the TodoWrite tool. Do NOT fetch anything, search anything, or write anything until the list exists:
-
-1. Check existing vault coverage (Step 0.5)
-2. Discover sources (Step 2)
-3. Fetch source batch or open the guided reading loop (Step 3)
-4. **Checkpoint 1: post-fetch review**
-5. Rabbit-hole pass with `--suggested-by` provenance (Step 4)
-6. Curate every source: tier + content_type + summary + analyst extract (Steps 5–6)
-7. Run link / lint / graph hubs (Steps 5–6)
-8. **Checkpoint 2: post-curate review**
-9. Write scaffold note WITH verbatim user prompt as first section (Step 7)
-10. Write comparisons note (Step 8)
-11. **Checkpoint 3: pre-draft gate — CRITICAL**
-12. Write `research/notes/final_report.md` (Step 9)
-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.
-
----
-
-## Zettelkasten conventions (apply in every activity)
-
-All notes follow atomic Zettelkasten conventions. The CLI manages the index.
-
-**Note `type:` field:** `source` | `synthesis` | `moc` | `scaffold` | `comparison`
-
-**Status lifecycle:** `draft` → `review` → `evergreen` → `stale` → `deprecated` → `archive`
-
-**Every source note must have:** `title`, `source` (URL), at least one `tag`, `summary` (≤120 chars), `status`, `tier`, `content_type`.
-
-**Epistemic metadata (required on every source note before Checkpoint 2):**
-
-- **`tier`** — what epistemic role this source plays:
- - `ground_truth` — the artifact itself: official filings, product specs, datasets, primary texts, peer-reviewed papers with original data, regulatory text
- - `institutional` — authoritative synthesizers: analyst reports, think-tanks, review/survey papers, textbooks, canonical criticism
- - `practitioner` — how domain participants actually experience it: user reviews, community threads, practitioner blogs, postmortems, migration guides
- - `commentary` — discussion without new signal: news summaries, opinion pieces, derivative explainers
- - `unknown` — unclassified (default at fetch time; must be replaced during curation)
-- **`content_type`** — what kind of artifact this is: `paper` | `docs` | `article` | `blog` | `forum` | `dataset` | `policy` | `code` | `book` | `transcript` | `review` | `unknown`
-
-Tier and content_type are orthogonal: a `paper` can be `ground_truth` (original data) or `institutional` (a review). A `blog` can be `practitioner` (named engineer's postmortem) or `commentary` (derivative explainer).
-
-**Tagging:** Check existing tags first (`$HPR tags -j`). Reuse existing tags. Apply multiple relevant tags per note. Do not invent synonyms.
-
-**Wiki-links:** Connect related notes with `[[note-id]]`. Every note should link to at least one sibling.
-
----
-
-## Step 2: Source discovery
-
-The modality file tells you the source strategy (what APIs to hit, what source types to prioritize, whether to run the academic sweep). Run it.
-
-Then, regardless of modality, run an **adversarial search round** — searches that specifically look for the failure case, the dissenting view, the critique, the contrarian, the known limitations. Every activity needs this:
-
-```
-WebSearch("<topic> criticism limitations problems")
-WebSearch("<topic> against the grain dissenting view")
-WebSearch("why <dominant view> is wrong")
-```
-
-A corpus without dissent is advocacy, not research. If the adversarial round returns nothing substantive, note that explicitly — it is itself a finding.
-
----
-
-## Step 3: Fetch — guided reading loop (preferred) or batch
-
-**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** 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
-
-The loop is a bounce between fetching and reading:
-
-```
-fetch 3-5 seeds → hyperresearch-analyst reads each with goal in hand →
- analyst returns extract + "next_targets" (URLs, queries, names, claims to verify) →
- main agent fetches next_targets with --suggested-by flag →
- hyperresearch-analyst reads those → ...
-```
-
-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 **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 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
-
-PDF hosts on academic faculty pages, ResearchGate, SSRN, and publisher sites are notoriously flaky (403, paywall walls, junk content, login walls). When a fetch returns `error`, `JUNK_CONTENT`, `AUTH_REQUIRED`, or any non-success status, **do NOT silently move on if the source is high-priority.** A high-priority source is one that:
-
-- Is the seminal paper an analyst specifically named as a `next_target`
-- Is the canonical source for the question (e.g., the original Maskin-Riley paper for an asymmetric-auctions query)
-- Is the only voice from a missing tier (e.g., the only practitioner perspective in a corpus of academic papers)
-
-For high-priority failures, work through this fallback chain in order — stop as soon as one succeeds:
-
-1. **Try alternative URLs for the same paper:**
- - arXiv preprint version (`arxiv.org/abs/<id>` or `arxiv.org/pdf/<id>`)
- - Author's personal page (search `"<author surname> <paper title> filetype:pdf"`)
- - Department / institutional repository (search `"<paper title> site:<institution>.edu"`)
- - SSRN, RePEc, NBER, OpenAlex, Semantic Scholar mirror
- - Google Scholar's "All N versions" link
-2. **Try the visible-browser flag** on the original URL: `$HPR fetch "<url>" --visible ...`. The `--visible` flag runs the browser non-headless; many sites that block headless requests succeed when the browser is visible. Cost: ~5-10s slower per fetch.
-3. **If a login profile is configured for this vault** (`.hyperresearch/config.toml` has a `[web] profile = "<name>"` entry), crawl4ai uses it automatically — paywalled sites the user has logged into in that profile will succeed transparently. If profile-protected sites still fail, the profile may be expired; tell the user to re-run `hyperresearch setup` to refresh it. There is no `--profile` CLI flag — it's a per-vault config setting.
-4. **As a last resort**, search for a **summary or review** of the paper that captures its key claims (e.g., a textbook chapter that summarizes the result). Note this in the source's frontmatter `summary:` field as `(via summary, original PDF unavailable)`.
-5. **If all four fail and the source is genuinely irreplaceable**, surface the failure to the user — don't ship a draft that depends on a source you couldn't read.
-
-Document failures in the scaffold's "Where each source will land" section. The auditor will see the explicit gap and can flag whether the draft works around it correctly.
-
-**Low-priority fetch failures** (a peripheral source the analyst flagged with low confidence) — skip and move on. Don't waste five fallback attempts on a tangential source.
-
-#### Mandatory `--suggested-by` discipline at fetch time
-
-Every `$HPR fetch` call from Phase 2 onward MUST pass `--suggested-by <source-note-id>` AT FETCH TIME. Do NOT batch-fetch a list of next_targets first and then backfill breadcrumbs later — that produces disconnected provenance graphs that the rooted-tree lint catches as errors at Checkpoint 2.
-
-The pattern is: analyst returns `next_targets[]` with each target's `proposed_by` source id → main agent fetches each target with the corresponding `--suggested-by` flag in the same call. One subprocess per target, with the breadcrumb baked in.
-
-```bash
-# CORRECT — breadcrumb at fetch time
-$HPR fetch "<url>" --suggested-by <source-id> --suggested-by-reason "<why>" -j
-
-# WRONG — fetch first, append breadcrumb later
-$HPR fetch "<url>" -j # creates seed-style note
-$HPR note edit <new-id> ... # tries to graft a breadcrumb after the fact
-```
-
-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.
-
-**Seed fetches — omit `--suggested-by` entirely.** The very first fetches you do have no upstream suggester. Do NOT invent a placeholder string like `seed-discovery`, `initial-seed`, `run-a-seed`, `run-b-seed`, `run-c-seed`, or any other synthetic value for `--suggested-by`. Placeholder strings are hallucinated note IDs; they are not real notes in the vault, and the provenance lint (which does a real lookup against `hyperresearch note show <id>`) will report every breadcrumb pointing at them as broken. For seed fetches, OMIT the flag:
-
-```bash
-# CORRECT — no --suggested-by on a seed fetch
-$HPR fetch "<seed-url>" --tag <topic> -j
-
-# WRONG — fake placeholder breadcrumb that the provenance lint rejects
-$HPR fetch "<seed-url>" --suggested-by seed-discovery -j # invented id
-$HPR fetch "<seed-url>" --suggested-by run-a-seed -j # invented id
-```
-
-The provenance lint tolerates missing breadcrumbs on seed fetches (a note with no breadcrumb is simply treated as a seed root of its own). It rejects breadcrumbs pointing at note IDs that do not resolve. An invented placeholder is strictly worse than no breadcrumb at all — it declares a chain that does not exist.
-
-**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 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`>
-```
-
-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:
-
-1. **Track the iteration in TodoWrite.** Add `Iteration N: fetch [targets] from [sources]`. After it completes, mark with the coverage delta ("added 4 sources, 2 sub-topics newly covered"). This makes stalls visible.
-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 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>" \
- --tag <topic> \
- --suggested-by <source-note-id-1> \
- --suggested-by <source-note-id-2> \
- --suggested-by-reason "<the analyst's justification>" \
- -j
- ```
-
- Without this flag the data-flow chain breaks — the fetched note has no link back to the source that found it, and you cannot trace how the research graph assembled itself.
-
- **Graceful duplicate handling:** if the URL is already in the vault, fetch will NOT error. It appends the breadcrumb to the existing note and returns `{ok: true, duplicate: true, backlinks_added: N}`. Fetch every next_target; let fetch handle dedup.
-
-6. Refresh `already_fetched_urls` (`$HPR sources list -j`). Pass it to the next iteration.
-7. Spawn `hyperresearch-analyst` on the new notes. Loop.
-
-**Phase 4 — Termination.** Exit when ANY of these fires:
-- **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: 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).
-
----
-
-## Step 4: Rabbit holes — follow what sources point at
-
-Beyond the guided loop's automated next_targets, actively scan fresh notes for:
-
-- **Cited datasets / primary data** → fetch the original, not the summary
-- **Named scholars / practitioners / companies** → find their own writing
-- **Referenced historical cases / precedents** → fetch the case itself
-- **Interviews or quotes** → find the full transcript
-
-Every manual rabbit-hole fetch MUST also pass `--suggested-by` naming the source that sent you there:
-
-```bash
-$HPR fetch "<url>" \
- --tag <topic> \
- --suggested-by <source-note-id> \
- --suggested-by-reason "<one-line reason>" \
- -j
-```
-
-Claims carry more weight when the graph shows you traced them to primary sources.
-
----
-
-## Step 4.5: Note triage (MANDATORY throughout)
-
-Never blindly `note show` every note. Triage first.
-
-| Level | Command | When |
-|---|---|---|
-| 1 — List | `$HPR note list -j` | Always start here. Summaries only, no bodies. |
-| 2 — Meta | `$HPR note show <id> --meta -j` | When the summary hints at deeper value. |
-| 3 — Inline | `$HPR note show <id> -j` | word_count < 2000. Batch small notes: `note show <id1> <id2> <id3> -j` |
-| 4 — Search | `$HPR search "<q>" --include-body --max-tokens 6000 -j` | When you want content across multiple notes. |
-| 5 — Subagent | Spawn `hyperresearch-analyst` (mode=extract) | word_count > 3000, OR whenever you need one specific answer from a big source. Never dump large notes inline. |
-
----
-
-## Steps 5–6: Curate every source
-
-Raw fetched notes arrive with `status=draft`, `tier=unknown`, auto-detected `content_type`, and no summary. Curation has two parallel jobs:
-
-1. **Set metadata** — tier, content_type, summary, tags, status (you do this with `$HPR note update`)
-2. **Extract relevant content** — spawn `hyperresearch-analyst` on the source so you have an extract note grounded in the research goal
-
-**Both must happen for every fetched source.** The analyst extract is what gives you the substance to write deep prose about the source later; the metadata is what lets you query and filter the corpus during drafting.
-
-### Step A: Spawn the analyst on every source
-
-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 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 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–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 with at least 150 words of real content. The `extract-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
-
-The analyst's return tells you the tier and content_type. After it returns:
-
-```bash
-$HPR note update <source-id> \
- --tier <ground_truth|institutional|practitioner|commentary> \
- --content-type <paper|docs|article|blog|forum|dataset|policy|code|book|transcript|review> \
- --summary "<one-line description, can borrow from the analyst's extract>" \
- --add-tag <topic> --add-tag <subtopic> \
- --status review \
- -j
-```
-
-**Tier and content_type are PER-NOTE decisions.** Never apply one value to the whole batch. A fandom wiki is `docs`; a news article is `article`; a named-engineer blog post is `blog`; a reddit thread is `forum`; a GitHub README is `code`. An arxiv paper on theory is `institutional`; the same paper reporting experimental data is `ground_truth`; a conference keynote transcript is `commentary`. Read each analyst return and make the call per source.
-
-### Completion check
-
-```bash
-$HPR lint --rule uncurated -j # zero uncurated
-$HPR lint --rule provenance -j # zero provenance issues (--suggested-by chain exists)
-$HPR lint --rule extract-coverage -j # zero extract-coverage issues
-$HPR link --auto -j
-$HPR graph hubs -j
-```
-
-If any lint returns issues, curation is NOT done. Go back, run more analyst calls, fetch proposed next_targets with `--suggested-by`, and re-run the lints before Checkpoint 2.
-
----
-
-## Step 7: Build the scaffold — with the canonical research query as the first section
-
-**Required artifact:** a note tagged `scaffold` whose FIRST section is the canonical research query.
-**Verification:** `$HPR note list --tag scaffold -j` must return ≥1 entry after this step AND the body of that note must contain the canonical research query.
-**On failure:** the draft has no anchor. Return to Step 7 and write the scaffold.
-
-Using the **Write tool**, create `research/scaffold.md` with this exact structure:
-
-```markdown
-## User Prompt (VERBATIM — gospel)
-> [the canonical research query, copied character-for-character from the prompt source.
-> This is the authoritative source. Every subsequent step re-reads this
-> section. Do not paraphrase. Do not truncate. Do not reformat.]
-
-## Session wrapper requirements
-- **Required artifact path:** <path or "none">
-- **Required citation contract:** <e.g. "[N] bracket citations only" or "none">
-- **Required terminal section(s):** <e.g. "must end with ## Opinionated Synthesis ..." or "none">
-- **Other wrapper constraints:** <anything else binding, or "none">
-
-## What the user explicitly asked for
-- **Explicit deliverables:** <list — or "none">
-- **Explicit entities or items:** <list — or "none">
-- **Explicit per-item fields:** <list — or "none">
-- **Explicit structure:** <or "silent">
-- **Explicit format:** <or "silent">
-- **Explicit scope cues:** <or "silent">
-- **Explicit ordering:** <or "silent">
-
-## Primary activity and secondary flavor
-- **Primary:** <collect | synthesize | compare | forecast>
-- **Secondary (optional):** <or "none">
-- **Output mode:** <description_only | description_with_takeaway | opinion_demanded>
-- **Why:** <one sentence covering the activity choice AND the output mode choice>
-
-## Core tension
-<what makes this question non-trivial — the paradox, disagreement, tradeoff,
-or open problem the draft has to earn its way through>
-
-## Prompt decomposition — ATOMIC, one H2/H3 per item (MANDATORY)
-<Extract EVERY explicitly named subtopic, entity, context, field, or dimension
-from the verbatim prompt. This is ATOMIC DECOMPOSITION — split every
-`and`-conjoined ask, every `as well as`, every comma-separated list,
-every "furthermore / additionally / in particular" into its own bullet.
-
-Examples:
-- "liability in ADAS accidents" names {technical ADAS principles, legal
- frameworks, case law, regulatory guidelines} — 4 items.
-- "Diamond Sutra in daily life, workplace, business, marriage, parenting,
- emotional well-being, interpersonal dynamics" names 7 contexts — 7 items.
-- "explain the differences and connections between A2A and MCP, and
- elaborate on A2A's innovative aspects and the specific problems it
- addresses" names FOUR items: [differences, connections, innovations,
- problems]. NOT two items, NOT three — four. Collapsing "differences
- and connections" into a combined section is the single most common
- instruction-following failure. Do not do it.
-
-Each item becomes its own H2 or H3 in the draft — NEVER collapse or merge
-atomic items. If the prompt names 7 contexts, deliver 7 sections. If an
-`and`-conjoined pair genuinely overlaps, still give each its own heading
-with cross-reference text ("see also §X") rather than silent merging.
-
-The audit at Step 11 counts the atomic items here and verifies the draft
-has one dedicated H2/H3 per item. A shortfall is a CRITICAL finding.>
-
-- item 1: <section title>
-- item 2: <section title>
-- ...
-
-## The structural plan
-<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.).
-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".
-The auditor at Step 11 reads this checklist and verifies each item is
-ticked off in the draft. If the user said "for each of 108 Specters provide
-techniques and fate", there must be a coverage-checklist line that will be
-checked against the draft. Do not write vague checks.>
-```
-
-Then run:
-
-```bash
-$HPR note new "Scaffold: <topic>" --tag scaffold --status draft \
- --body-file research/scaffold.md --summary "Scaffold for <topic>" -j
-```
-
-**The verbatim user prompt goes FIRST.** This is non-negotiable. Every checkpoint re-opens the scaffold, and re-opening the scaffold means re-reading the prompt. The prompt lives inside the document so it cannot drift out of context.
-
----
-
-## Step 8: Cross-source comparisons
-
-**Required artifact:** a note tagged `comparison` containing 3–5 explicit source-vs-source disagreements with your position on each. If the prompt asks to refine, optimize, evaluate, or compare anything (or if `compare` is the primary or secondary modality), this note must ALSO declare the evaluation dimensions the draft will use.
-**Verification:** `$HPR note list --tag comparison -j` must return ≥1 entry after this step.
-**On failure:** the thesis / recommendation / forecast has no stress test. "I did it in my head" is not acceptable.
-
-Find 3–5 places where sources disagree. Read both at Level 3+ before comparing.
-
-Using the **Write tool**, create `research/comparisons.md`:
-
-```markdown
-## Declared comparison / evaluation dimensions (required when the prompt asks to refine / optimize / evaluate / compare, or compare is primary/secondary)
-- **Dimension 1:** <name> — <why this dimension matters for the user's decision>
-- **Dimension 2:** <name> — <why it matters>
-- **Dimension 3:** <name> — <why it matters>
-
-## Matrix candidate (same condition as above)
-| Prompt-named item / option | Dimension 1 | Dimension 2 | Dimension 3 | Evidence to cite later |
-|---|---|---|---|---|
-| <item A> | <score / characterization> | <...> | <...> | <source ids / URLs> |
-
-## Disagreement 1: <what axis are they disagreeing about>
-- Source A ([URL]): <claim/reading> because <reasoning/evidence>
-- Source B ([URL]): <different claim> because <different reasoning>
-- Why they differ: <theoretical framework? different data? different time window? different scope?>
-- My position: <which is more credible and why — take a side, with the evidence that tips the balance>
-```
-
-Then run:
-
-```bash
-$HPR note new "Comparisons: <topic>" --tag comparison --status draft \
- --body-file research/comparisons.md --summary "Source comparison for <topic>" -j
-```
-
----
-
-## Step 9: Write the draft
-
-**Before writing anything:** re-open `research/scaffold.md`. Re-read the canonical research query. Re-read the scaffold's `## Session wrapper requirements`. Re-read the "What the user explicitly asked for" extraction. Re-read the coverage checklist. This is mandatory — every draft session must begin with re-encountering both the user's ask and the wrapper contract.
-
-Then read your modality file's substance rules. The modality file tells you HOW to write: interpretation density (synthesize), enumerative completeness (collect), proportionate depth + recommendation (compare), probability language + time horizon (forecast).
-
-**Write `research/notes/final_report.md`** as a normal markdown file (no frontmatter needed for the draft — final save happens at Step 13).
-
-### Shared writing constraints (apply to every activity)
-
-- **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.
-- **Optimization / evaluation prompts declare dimensions early.** If the prompt asks to refine, optimize, evaluate, or compare anything, or if `compare` is your primary or secondary modality, the opening must name the evaluation dimensions before the body starts. Reuse the same dimensions from `research/comparisons.md`; do not silently invent new ones mid-draft.
-- **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.
-- **Prompt-named sections carry the real work.** When the prompt names components, entities, or options explicitly, each dedicated section must answer the question for that item directly. For refinement / optimization asks, that means the section covers: current state, the main bottlenecks or failure modes, the best-supported optimization levers, and the evidence or metrics that justify those recommendations. Cross-cutting support sections can help, but they must feed back into the prompt-named sections rather than replacing them.
-- **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.
-- **Cite aggressively. Every factual claim, every number, every attributed position, every direct or paraphrased quote gets an inline citation.** Use `[N]` bracket citations only (see the "Clean `[N]` bracket citations ONLY" rule below for the exact format). **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 — one H2 per atomic scaffold item.** Open your scaffold's "Prompt decomposition" section and count the atomic items. Your draft has at least that many dedicated H2 or H3 sections, each titled to map obviously to one atomic item. Collapsed sections (titling "Differences & Connections" as one H2 when the prompt named BOTH as atomic asks) are the single most common instruction-following failure mode — visible structural separation is what a reader (human or automated) looks for first to verify the prompt was answered. If two atomic items genuinely overlap, still give each its own heading with a cross-reference ("see also §X") rather than silent merging. 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 discipline — the draft is as long as substance demands, as short as structure allows.** Deep-research drafts typically run 5,000-9,000 words. If you are at 3,000 on a complex prompt you are probably collapsing sections or under-citing; if you are over 10,000 you are probably padding. There are three common padding sources to cut (detailed in a single rule below) — non-requested sections, verbose prose, and filler words. Apply them before shipping.
-
-- **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.
-
-- **Clean `[N]` bracket citations ONLY — no inline URLs in the body.** 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. The body text must contain ONLY `[N]` bracket markers — do NOT embed inline Markdown URL links like `([Author](https://...))` alongside bracket numbers. The pattern `([Author Year](url)) [1]` is double-citing: it injects URL noise into every paragraph and kills readability. The `## Sources` section already carries full attribution (author, title, URL) for each `[N]` — that is where the URL lives, not inline. Do NOT invent alternative citation formats (no unicode bracket pairs, no `dagger`, no author-year-only, no inline Markdown links). `[N]` bracket plus final Sources list is the only format.
-
-- **`[N]` → Sources entry is 1-to-1 and bidirectional.** Every `[N]` inline in your draft MUST correspond to exactly one entry in the `## Sources` section. Every entry in `## Sources` MUST have at least one matching inline `[N]` in the body. Do not list a source you did not cite. Do not cite a source you did not list. When you finish writing, do a reconciliation pass: grep your own draft for every `[N]` marker, cross-check against the Sources list, and DELETE any Sources entry that has zero inline citations. A fabricated Sources list (ghost references) is worse than a short one — it signals to reviewers that you padded the bibliography without using the content. The ensemble merger will halt with a CRITICAL if it finds broken references post-fusion; catch them in your own sub-run before shipping.
-
-- **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.
-
-- **Cut padding at three scales — sections, sentences, and words.** This is the unified conciseness rule that the length-discipline rule above points at. Apply all three passes before shipping:
-
- **(1) Non-requested sections.** The scaffold's "What the user explicitly asked for" lists the user's deliverables. Anything else — introduction beyond 1-2 paragraphs, background/primer sections, cross-cutting syntheses, dataset/infrastructure overviews, adversarial/limitations sections, the Step 12 tail — is optional scaffolding the user did NOT request. Before including any such section, apply this test: does it (a) make a requested section easier to understand, (b) contain a finding that does not fit inside any requested section, or (c) satisfy a modality substance rule (compare's matrix, forecast's precedent, collect's closing)? If none, cut it. Bonus sections that duplicate content already delivered inside requested sections are the worst offender — e.g., a long Opinionated Synthesis that restates recommendations already made per-entity in the body. When the user's ask is scoped ("refine these 4 components", "answer questions A / B / C / D", "describe these entities"), the analytical moves (refinements, opinions, comparisons, recommendations) belong INSIDE the requested sections, not in a separate tail. Support sections (datasets, limitations, integration, cross-cutting analysis) stay subordinate — they sharpen requested sections, they do not become the primary body. A draft where 40%+ of words are non-requested reads as padded to any reviewer.
-
- **(2) Verbose prose inside kept sections.** Every sentence earns its place or gets cut.
- - Cut meta-commentary: "It is worth noting that...", "As we will see in the next section...", "The following discussion will examine..." are throat-clearing — the next sentence already says what's coming.
- - Cut qualifier pileups: "Extremely significantly important" is one adjective too far. Pick the strongest word and drop the rest.
- - Cut section recaps: do not open a section with "In the previous section, we established X; in this section, we turn to Y." Just start Y.
- - Cut parenthetical asides that restate the main clause: "The magnetic compass (which detects Earth's magnetic field) works by..." → "The magnetic compass works by..."
- - Favor short declarative sentences over long clausal chains. A 30-word sentence with three subordinate clauses is usually two 15-word sentences waiting to be separated.
-
- **(3) Filler words at the sentence level.** Do not summarize what you are about to say next; just say it. Do not paraphrase the user's question back at them. If you cannot cite a claim, cut the claim rather than hedging it.
-
-- **Use visual devices when content has structure worth showing.** Prose is not always the right medium. When the content would benefit from a visual layout, use one — don't force it into paragraphs. Specifically:
- - **Comparison matrix (markdown table)** when you have ≥3 entities evaluated across ≥3 dimensions, or ≥2 entities across ≥5 dimensions. The table makes cross-entity differences legible at a glance in a way prose cannot.
- - **ASCII sequence diagram / pipeline box** when explaining a multi-step mechanism, protocol flow, or state machine. For example: `Client → [Request] → Agent → [Tool Call] → Server → [Response]` — a single line of ASCII carries more clarity than three prose sentences.
- - **ASCII hierarchy / tree** when showing categorical nesting (type hierarchies, org structures, file layouts, taxonomies). Indented tree notation (`├── ...`) is immediately readable.
- - **Inline enumerated list with bolded lead** when presenting parallel items that share structure ("**Option A**: short description. **Option B**: short description.") — clearer than a paragraph that buries the items in prose.
- - **Timeline / horizon block** for forecasts or historical arcs — dates/milestones in a vertical layout rather than prose narrative.
- Do NOT force visuals where the content is genuinely argumentative or narrative prose — a 5-paragraph thesis defense should not become a table. But when you catch yourself writing a paragraph like "Entity A does X, Entity B does Y, Entity C does Z — and for each the tradeoffs are different on dimensions P, Q, R", stop writing prose and make a table. Visual layouts materially improve readability on structured content; a draft that consistently reaches for prose where a table or diagram is the honest medium reads as cluttered even when each sentence is fine in isolation.
-
-### Activity-specific substance rules
-
-Open your modality file and read its Step 9 section. Its substance rules layer on top of the shared constraints above — they do not replace them.
-
-### Secondary flavor layering (MANDATORY when your scaffold declared a secondary)
-
-If your Step 1 classification declared a secondary flavor, your draft must satisfy BOTH modalities' substance rules — not just the primary's. Read the **secondary modality's Step 9 substance rules AND its conformance checks** before you start writing.
-
-Conflict resolution:
-- **Primary wins on structure.** Section shape, entity-vs-thematic sequencing, comparison-matrix presence, scaffold skeleton — all determined by the primary modality.
-- **Secondary wins on substance within sections.** Per-paragraph density rules, tension requirements, interpretation/enumeration discipline — these layer on top of the primary's structure.
-
-Example (`primary=collect`, `secondary=synthesize` — e.g., a prompt like "for each X in category C, describe Y and Z, then interpret what the pattern means"):
-- Collect (primary) forces per-entity coverage across every category in the prompt. The structure is entity-based.
-- Synthesize (secondary) forces every paragraph to fuse fact with interpretive claim AND at least two body sections to put sources in tension.
-- The draft has entity-named sections (primary structure) where every paragraph inside makes an interpretive claim about what that entity means (secondary substance).
-
-The auditor applies BOTH check lists at Step 11. Secondary-flavor violations are **not waivable** — they are CRITICAL findings that block synthesis save via the `audit-gate` lint rule. If a prompt is genuinely 50/50 across two activities, plan to satisfy both; do not silently drop the secondary.
-
----
-
-## 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:
-
-- Did you engage with the strongest counter-position?
-- Is every item in the scaffold's coverage checklist actually ticked off in the draft?
-- Are there tiers you're missing (all commentary, no ground_truth)?
-- Is there a named voice you should be citing that isn't in the vault yet?
-
-Fetch what's missing. Update the draft.
-
----
-
-## Step 11: Adversarial audit — spawn `hyperresearch-auditor` twice
-
-**Required artifact:** text output from both `hyperresearch-auditor` runs in your context, plus every identified violation applied to the draft.
-**Verification:** in writing, list each violation the auditors raised and whether it has been fixed or explicitly rejected.
-**On failure:** an unapplied audit is equivalent to no audit. Task has FAILED at Checkpoint 4.
-
-**Spawn `hyperresearch-auditor` twice — once per mode. Run them SEQUENTIALLY, comprehensiveness first then conformance.** The auditor is a registered Claude Code agent (`.claude/agents/hyperresearch-auditor.md`) running on Opus. Both runs MUST receive the user's original research query **verbatim** — the same prompt you pasted into the scaffold.
-
-Run comprehensiveness first so its findings land in `research/audit_findings.json` without a write race, then run conformance which reads the file and appends its own entry.
-
-```
-First spawn (wait for completion before the second):
- research_query: <paste the user's verbatim prompt from scaffold §1>
- modality: <collect | synthesize | compare | forecast>
- mode: comprehensiveness
- final_report_path: research/notes/final_report.md
- scaffold_note_id: <scaffold note id>
- comparison_note_id: <comparison note id>
-
-Second spawn (only AFTER the first has returned and written its entry):
- research_query: <paste the user's verbatim prompt from scaffold §1>
- modality: <collect | synthesize | compare | forecast>
- mode: conformance
- final_report_path: research/notes/final_report.md
- scaffold_note_id: <scaffold note id>
- comparison_note_id: <comparison note id>
-```
-
-After both have returned, verify `research/audit_findings.json` has TWO new entries (one per mode) before proceeding. If only one mode's entry is present, re-spawn the missing mode — the `audit-gate` lint rule will fail at Step 13 if either is missing.
-
-The auditor reads your modality file's "Conformance checks" section, applies each check, persists its findings to `research/audit_findings.json`, and returns a text summary with `pass` / `needs_fixes` / `failed` status. Apply every CRITICAL finding before saving the synthesis, and mark each fixed finding's `fixed_at` field in the JSON file as you go. The auditor also reads the scaffold — so it re-encounters the verbatim prompt — and verifies the draft honors the scaffold's coverage checklist.
-
----
-
-## Step 12: Opinionated synthesis (scaled by output_mode, unless wrapper-required)
-
-The synthesis tail is scaled by the `output_mode` you committed to at Step 1. Re-read your scaffold's output_mode field AND its `## Session wrapper requirements` before writing this step — together they control whether the synthesis section is full, minimal, or omitted.
-
-**Wrapper override rule.** If the session wrapper explicitly requires a terminal section shape, that requirement overrides the default omission logic below. Example: if the wrapper says the report MUST end with `## Opinionated Synthesis` and specific subsections, you MUST include exactly that block even when `output_mode` would otherwise be `description_only`. The canonical query still governs substance; the wrapper governs packaging.
-
-**Why this is conditional, not always-on.** A user who asked "explain X" did not ask for your reasoned position on X. Appending a thesis to a pure description is padding — it inflates the draft with content the reader did not request and dilutes the instruction-following quality of the output. Conversely, a user who asked "which is best" or "should we" explicitly wants your committed take, and a draft that ends without one has failed them. The three modes below route each prompt to the right amount of synthesis for what the user actually asked.
-
-### If `output_mode == description_only`
-
-**Skip Step 12 entirely UNLESS the wrapper requires a terminal section.** If there is no wrapper-required tail, the draft ends at whatever closing the modality specifies in its own Step 9 substance rules (collect's set-pattern closing, compare's matrix + dimension discussion, synthesize's argument conclusion, forecast's horizon summary). Do NOT append "Opinionated Synthesis", "My Reasoned Position", "Thematic Threads", or any variant unless the wrapper explicitly asked for them. The draft's final content section before `## Sources` is the modality's body closing.
-
-The body already delivers the full answer. Anything more is scope creep.
-
-### If `output_mode == description_with_takeaway`
-
-Append ONE short section — the takeaway the user hinted they wanted, and nothing more:
-
-```markdown
-## Takeaway
-
-<One tight paragraph — 100 to 200 words — naming the single most important thing a reader should leave with, and why it follows from the body. If the modality supports it, one sentence of "open questions" at the end is allowed but not required. No thesis commitment, no recommendation, no forecast unless the body already made one.>
-```
-
-This is a landing pad, not an argument. It summarizes what the corpus amounts to without promoting description into advocacy.
-
-### If `output_mode == opinion_demanded`
-
-Append the full opinionated synthesis block — the user explicitly asked for a committed view:
-
-```markdown
-## Opinionated Synthesis
-
-### <Activity-specific header — see modality file>
-<the cross-cutting picture the modality demands: thematic threads for
-synthesize, comparison matrix for compare, position-with-horizon for
-forecast, coverage summary for collect>
-
-### Thematic Threads
-<patterns across the body sections that the per-section analysis couldn't
-surface — what the whole corpus is saying that no single source said>
-
-### My Reasoned Position
-<your defensible stance, explicitly labeled. Synthesize demands a thesis;
-compare demands a recommendation; forecast demands a prediction with
-probability language and a time horizon; collect demands a "what this whole
-set amounts to" claim.>
-
-### Open Questions
-<what the sources didn't settle, what data is unavailable, what would
-change your position>
-
-### Concluding Thoughts
-<one tight paragraph: the single most important thing a reader should
-take away — and why>
-```
-
-### Record which branch you took
-
-In the draft's scaffold (or a comment at the top of the draft), note which `output_mode` branch you used at Step 12 and whether a wrapper override applied. The auditor's conformance check reads this to verify the synthesis tail matches the classification plus any explicit wrapper contract.
-
----
-
-## Steps 13–14: Save and present
-
-**Before saving the synthesis**, run the audit-gate lint to confirm the audit loop is closed. This is a hard gate — the synthesis cannot be saved until it returns zero error-severity issues:
-
-```bash
-$HPR lint --rule audit-gate -j
-```
-
-The `audit-gate` rule checks three conditions against `research/audit_findings.json`:
-
-1. **Both audit modes must have appended a run.** If the file has a comprehensiveness run but no conformance run (or vice versa), the gate fails with a missing-mode error — spawn the missing auditor mode and retry.
-2. **No unresolved CRITICAL findings in the most recent conformance run.** Every CRITICAL must have a non-null `fixed_at` timestamp. Walk the unresolved list, apply the fix to `research/notes/final_report.md`, and mark `fixed_at: <current ISO timestamp>` on the finding in the JSON file. If a finding cannot be fixed (e.g. the auditor misread the draft), resolve it by marking `fixed_at` with a `notes` field explaining why the rejection is safe — but that is a last resort, not a bypass.
-3. **IMPORTANT findings surface as `info` severity** (advisory, does not block save). They appear in the lint output so you see them before committing. You are strongly encouraged to patch them if they name real gaps — they often do. Mark each as `fixed_at` in the JSON once patched.
-
-After applying fixes:
-- If you patched the draft, re-spawn the conformance auditor (which will append a fresh run to the findings file) and re-run the lint.
-- If `audit-gate` returns zero error-severity issues — proceed to save.
-- If it still fails, diagnose which specific finding is blocking and address it. **Do NOT bypass the gate by editing `audit_findings.json` to clear findings without patching the draft first.**
-
-This is how the audit loop actually closes: findings are persisted → fixes are applied → `fixed_at` is set → the lint passes → the synthesis saves. Each step leaves an artifact on disk.
-
-Using the **Write tool**, create `research/synthesis.md`:
-
-```markdown
-# <Topic> — Synthesis
-## Position
-<your thesis / recommendation / forecast / coverage summary>
-## Sources
-<[[note-id-1]], [[note-id-2]], ...>
-## Open Questions
-<unresolved>
-```
-
-Then run:
-
-```bash
-$HPR note new "Synthesis: <topic>" --tag <topic> --tag synthesis --type moc \
- --status review --body-file research/synthesis.md \
- --summary "<one-line position>" -j
-```
-
-Present to the user: your position in 2–3 sentences, the key structural beats, sources collected, and what would change your position.
-
----
-
-## Process review checkpoints
-
-Each checkpoint is a STOP point. Run the commands, state results in writing, decide whether the task has failed.
-
-### Checkpoint 1 — after Step 3 (post-fetch)
-
-**Purpose:** verify the corpus has enough voice diversity before reading it.
-
-```bash
-$HPR note list --status draft -j | python -c "import sys,json; d=json.load(sys.stdin)['data']; print(f'draft notes: {len(d)}')"
-$HPR sources list -j | python -c "
-import sys, json
-from collections import Counter
-from urllib.parse import urlparse
-d = json.load(sys.stdin)['data']
-sources = d if isinstance(d, list) else d.get('sources', [])
-total = len(sources)
-domains = Counter(urlparse(s['url']).netloc.replace('www.','') for s in sources if s.get('url'))
-print(f'total sources: {total}, unique domains: {len(domains)}')
-for dom, count in domains.most_common(10):
- pct = count / max(total, 1) * 100
- flag = ' <-- OVER 30% (concentrated)' if pct > 30 else ''
- print(f' {count:>3} ({pct:>5.1f}%) {dom}{flag}')
-"
-```
-
-**Pass conditions:**
-- [ ] At least one note fetched from each mandatory adversarial search in your modality file
-- [ ] **At least one source explicitly dissents from / criticizes the dominant view.** "Dominant view" is what the bulk of your corpus implicitly endorses; the dissenting source must contradict it directly (not just complicate it). State the dominant view in writing and identify which source is the dissent. If you cannot identify one, you have NOT satisfied the adversarial round — go fetch one before proceeding.
-- [ ] No single domain represents >30% of fetched sources (voice diversity)
-- [ ] At least 5 unique non-reference voices (critical essays, named-author blog posts, peer-reviewed papers — NOT listicles or reference wikis)
-
-**On failure:** run additional searches with diversified queries, vary the source types, seek named voices. For the dissent gap specifically: search for the named opponent of the dominant figure ("Roubini on inflation" rather than "inflation criticism"), look for retractions/withdrawals, look for "we tried X and switched to Y" postmortems. Return to Step 2.
-
-### Checkpoint 2 — after Steps 5–6 (post-curate)
-
-**Purpose:** verify every source has been analyzed AND classified.
-
-```bash
-$HPR lint --rule uncurated -j
-$HPR lint --rule provenance -j
-$HPR lint --rule extract-coverage -j
-$HPR note list --all -j | python -c "import sys,json; from collections import Counter; notes=json.load(sys.stdin)['data']; t=Counter(n.get('tier') for n in notes if n.get('status')!='draft'); ct=Counter(n.get('content_type') for n in notes if n.get('status')!='draft'); print(f'tiers: {dict(t)}'); print(f'content_types: {dict(ct)}')"
-```
-
-**Pass conditions:**
-- [ ] Zero `uncurated` issues
-- [ ] Zero `provenance` **errors** — the rule itself computes the non-seed ratio and errors when under 30% on a corpus >10, so if this lint returns zero errors the guided loop fired adequately. Read its output carefully; its message tells you `non_seeds / total` directly.
-- [ ] Zero `extract-coverage` issues (at least 33% of fetched sources have a paired extract note)
-- [ ] Tier and content_type distributions are nuanced (not one dominant value)
-- [ ] At least two tiers represented
-- [ ] At least three content_types represented
-
-**On failure:** re-classify per-note based on each analyst's return; spawn analysts on skipped sources; **run the guided reading loop**: spawn `hyperresearch-analyst` on existing sources, collect their `next_targets`, and fetch the top 3-5 WITH `--suggested-by <source-note-id>`. You cannot proceed to Step 7 (scaffold) until the guided loop has fired at least once — the provenance chain is a load-bearing invariant.
-
-**Specifically when `provenance` errors:** the rule message will say something like *"Only 3/19 source notes (16%) have breadcrumbs — the guided reading loop did not fire"*. Read that number literally. If it's below 30%, you MUST return to Step 4 and run the guided loop: spawn an analyst on each existing source, collect `next_targets`, fetch each target with `--suggested-by <source-note-id> --suggested-by-reason "<why>"`, then re-run Checkpoint 2. Skipping this means the draft rests on seed fetches alone and the bouncing-loop-discovered critical voices never made it into the corpus.
-
-### Checkpoint 3 — BEFORE Step 9 (pre-draft gate — CRITICAL)
-
-**Purpose:** this is the gate that protects the draft from being written on a broken foundation.
-
-```bash
-$HPR note list --tag scaffold -j | python -c "import sys,json; d=json.load(sys.stdin)['data']; print(f'scaffold notes: {len(d)}')"
-$HPR note list --tag comparison -j | python -c "import sys,json; d=json.load(sys.stdin)['data']; print(f'comparison notes: {len(d)}')"
-$HPR note list --tag extract -j | python -c "import sys,json; d=json.load(sys.stdin)['data']; print(f'extract notes: {len(d)}')"
-$HPR lint --rule scaffold-prompt -j
-$HPR lint --rule uncurated -j
-$HPR lint --rule provenance -j
-$HPR lint --rule extract-coverage -j
-$HPR lint --rule workflow -j
-```
-
-**Pass conditions:**
-- [ ] Scaffold note count ≥ 1
-- [ ] Zero `scaffold-prompt` issues — the scaffold body MUST contain the verbatim user prompt as its first section. This is machine-checked; the gospel rule is non-negotiable.
-- [ ] Comparison note count ≥ 1
-- [ ] Extract note count ≥ 30% of fetched source count
-- [ ] Zero `uncurated`, `provenance`, `extract-coverage`, `workflow` issues
-
-**On failure:** you CANNOT write the draft. Return to the step that produces the missing artifact. If `scaffold-prompt` failed, return to Step 7 and re-write the scaffold with the user's verbatim prompt as its first section — do not fudge it.
-
-### Checkpoint 4 — after Step 11 (post-audit)
-
-**Purpose:** verify the audit fired and its findings were applied.
-
-**Pass conditions:**
-- [ ] `hyperresearch-auditor` was spawned twice (comprehensiveness + conformance) and both returned
-- [ ] Every violation flagged has been fixed in `research/notes/final_report.md` OR explicitly rejected in writing with a reason
-- [ ] If the conformance auditor flagged missing scaffold / comparison / extract notes, you returned to the relevant checkpoint and fixed it
-
-**On failure:** spawn the auditor (or re-spawn) and apply the findings. Do not save the synthesis note until this checkpoint passes.
-
----
-
-## CLI path
-
-Find the `hyperresearch` executable from CLAUDE.md ("CLI path:" line) and store it:
-
-```bash
-HPR="<path from CLAUDE.md>"
-```
diff --git a/tests/test_cli/test_lint.py b/tests/test_cli/test_lint.py
index b6297d1..52e8d97 100644
--- a/tests/test_cli/test_lint.py
+++ b/tests/test_cli/test_lint.py
@@ -811,7 +811,7 @@ def test_orphaned_raw_files_ignores_matched_raw(tmp_vault):
# ---------------------------------------------------------------------------
-# locus-coverage (layercake Layer 3 — every locus must have an interim note)
+# locus-coverage (hyperresearch Layer 3 — every locus must have an interim note)
# ---------------------------------------------------------------------------
@@ -891,7 +891,7 @@ def test_locus_coverage_noop_when_no_loci_json(tmp_vault):
# ---------------------------------------------------------------------------
-# patch-surgery (layercake Layer 6 — patcher must not skip critical findings)
+# patch-surgery (hyperresearch Layer 6 — patcher must not skip critical findings)
# ---------------------------------------------------------------------------
@@ -951,7 +951,7 @@ def test_patch_surgery_noop_when_no_patch_log(tmp_vault):
# ---------------------------------------------------------------------------
-# workflow — comparisons.md gate for layercake runs with 2+ loci
+# workflow — comparisons.md gate for hyperresearch runs with 2+ loci
# ---------------------------------------------------------------------------
@@ -960,7 +960,7 @@ def test_workflow_flags_missing_comparisons_when_multiple_loci(tmp_vault):
insight-killing failure mode the cross-locus reconciliation step was
added to prevent."""
from hyperresearch.core.note import write_note
- # Layercake final-report signal
+ # Hyperresearch final-report signal
write_note(
tmp_vault.notes_dir,
"final_report",
@@ -1063,20 +1063,20 @@ def test_workflow_requires_comparisons_even_on_single_locus(tmp_vault):
# ---------------------------------------------------------------------------
-# provenance — layercake-aware: skip breadcrumb coverage ratio checks when
-# research/loci.json exists (layercake's fetch pattern is not bouncing-loop)
+# provenance — hyperresearch-aware: skip breadcrumb coverage ratio checks when
+# research/loci.json exists (hyperresearch's fetch pattern is not bouncing-loop)
# ---------------------------------------------------------------------------
-def test_provenance_skips_coverage_ratio_on_layercake_runs(tmp_vault):
- """A layercake run with many flat-seed fetches should NOT fail provenance's
+def test_provenance_skips_coverage_ratio_on_hyperresearch_runs(tmp_vault):
+ """A hyperresearch run with many flat-seed fetches should NOT fail provenance's
coverage-ratio check. Structural invariants (seeds exist, no dangling) still
enforced."""
# 15 source notes, ALL seeds (no --suggested-by breadcrumbs) — would be
# an instant failure under the old ensemble provenance rule.
for i in range(15):
_write_source(tmp_vault, f"Source {i}", f"source-{i}")
- # Add the layercake marker
+ # Add the hyperresearch marker
_write_loci_json(tmp_vault, [
{"name": "alpha", "one_line": "Q"},
{"name": "beta", "one_line": "Q"},
@@ -1090,16 +1090,16 @@ def test_provenance_skips_coverage_ratio_on_layercake_runs(tmp_vault):
i for i in data.get("data", {}).get("issues", [])
if i.get("rule") == "provenance" and i.get("severity") in ("error", "warning")
]
- # No ratio-based errors on layercake runs
- assert issues == [], f"expected no coverage issues on layercake, got: {issues}"
+ # No ratio-based errors on hyperresearch runs
+ assert issues == [], f"expected no coverage issues on hyperresearch, got: {issues}"
-def test_provenance_still_fires_coverage_check_on_non_layercake_runs(tmp_vault):
+def test_provenance_still_fires_coverage_check_on_non_hyperresearch_runs(tmp_vault):
"""Ensemble / single-pass runs (no loci.json) should still get the
bouncing-loop coverage check — nothing about this fix changes that."""
for i in range(15):
_write_source(tmp_vault, f"Source {i}", f"source-{i}")
- # NO loci.json → non-layercake run
+ # NO loci.json → non-hyperresearch run
tmp_vault.auto_sync()
_, out = _run_lint(tmp_vault, rule="provenance")
@@ -1304,7 +1304,7 @@ def test_instruction_coverage_flags_missing_format(tmp_vault):
def test_instruction_coverage_noop_when_no_decomposition(tmp_vault):
- """Non-layercake runs have no decomposition file — rule stays silent."""
+ """Non-hyperresearch runs have no decomposition file — rule stays silent."""
_, out = _run_lint(tmp_vault, rule="instruction-coverage")
import json
data = json.loads(out)
@@ -1317,7 +1317,7 @@ def test_instruction_coverage_noop_when_no_decomposition(tmp_vault):
# ---------------------------------------------------------------------------
# extract-coverage — single-pass /research runs must have analyst-extract
-# notes per source. Skips on layercake runs (loci.json present).
+# notes per source. Skips on hyperresearch runs (loci.json present).
# ---------------------------------------------------------------------------
@@ -1390,9 +1390,9 @@ def test_extract_coverage_rejects_stubs(tmp_vault):
assert "20 stub notes" in issues[0]["message"]
-def test_extract_coverage_skips_on_layercake_runs(tmp_vault):
- """Layercake runs produce loci.json. This rule is single-pass only —
- it should stay silent on layercake vaults, where locus-coverage takes
+def test_extract_coverage_skips_on_hyperresearch_runs(tmp_vault):
+ """Hyperresearch runs produce loci.json. This rule is single-pass only —
+ it should stay silent on hyperresearch vaults, where locus-coverage takes
over for quality gating."""
for i in range(9):
_write_source(tmp_vault, f"Source {i}", f"source-{i}")
@@ -1409,5 +1409,5 @@ def test_extract_coverage_skips_on_layercake_runs(tmp_vault):
i for i in data.get("data", {}).get("issues", [])
if i.get("rule") == "extract-coverage"
]
- # Silent on layercake — locus-coverage handles this mode
+ # Silent on hyperresearch — locus-coverage handles this mode
assert issues == []
diff --git a/tests/test_core/test_hooks.py b/tests/test_core/test_hooks.py
index 7026813..4479acf 100644
--- a/tests/test_core/test_hooks.py
+++ b/tests/test_core/test_hooks.py
@@ -1,101 +1,108 @@
-"""Tests for hook installer and skill file provisioning (layercake roster)."""
+"""Tests for hook installer and skill file provisioning (hyperresearch roster)."""
from __future__ import annotations
from hyperresearch.core.hooks import (
_RETIRED_AGENT_FILES,
_RETIRED_SKILL_DIRS,
- _SKILL_FILES,
_install_depth_critic_agent,
_install_depth_investigator_agent,
_install_dialectic_critic_agent,
+ _install_hyperresearch_skill,
_install_instruction_critic_agent,
- _install_layercake_skill,
_install_loci_analyst_agent,
_install_patcher_agent,
_install_polish_auditor_agent,
- _install_research_skill,
_install_researcher_agent,
+ _install_source_analyst_agent,
_install_width_critic_agent,
_prune_retired_agents,
install_hooks,
)
# ---------------------------------------------------------------------------
-# /research skill (single-pass, unchanged)
+# Entry skill — installs at both /hyperresearch and /research
# ---------------------------------------------------------------------------
-def test_install_skill_writes_expected_files(tmp_vault):
- result = _install_research_skill(tmp_vault.root)
- skill_dir = tmp_vault.root / ".claude" / "skills" / "hyperresearch"
- assert skill_dir.is_dir()
-
- expected = {dest_name for _, dest_name in _SKILL_FILES}
- present = {p.name for p in skill_dir.glob("SKILL*.md")}
- assert expected.issubset(present)
+def test_install_hyperresearch_skill_creates_both_aliases(tmp_vault):
+ """The entry skill installs at .claude/skills/hyperresearch/SKILL.md and
+ .claude/skills/research/SKILL.md so Claude Code registers BOTH
+ `/hyperresearch` and `/research` as slash-command triggers. Same content,
+ different `name:` frontmatter.
+ """
+ result = _install_hyperresearch_skill(tmp_vault.root)
assert result is not None
+ hyper_path = tmp_vault.root / ".claude" / "skills" / "hyperresearch" / "SKILL.md"
+ research_path = tmp_vault.root / ".claude" / "skills" / "research" / "SKILL.md"
+ assert hyper_path.exists()
+ assert research_path.exists()
+
+ hyper_body = hyper_path.read_text(encoding="utf-8")
+ research_body = research_path.read_text(encoding="utf-8")
+ assert "name: hyperresearch" in hyper_body
+ assert "name: research" in research_body
+ # Body content (everything after the name line) is identical
+ assert hyper_body.replace("name: hyperresearch", "") == research_body.replace(
+ "name: research", ""
+ )
-def test_install_skill_prunes_stale_files(tmp_vault):
- skill_dir = tmp_vault.root / ".claude" / "skills" / "hyperresearch"
- skill_dir.mkdir(parents=True, exist_ok=True)
-
- stale_names = [
- "SKILL-humanities.md",
- "SKILL-academic.md",
- "SKILL-landscape.md",
- "SKILL-technical.md",
- "SKILL-ensemble.md", # pre-layercake stale file
- ]
- for name in stale_names:
- (skill_dir / name).write_text("stale content\n", encoding="utf-8")
-
- result = _install_research_skill(tmp_vault.root)
-
- remaining = {p.name for p in skill_dir.glob("SKILL*.md")}
- expected = {dest_name for _, dest_name in _SKILL_FILES}
- assert remaining == expected
- for name in stale_names:
- assert not (skill_dir / name).exists(), f"stale file {name} still present"
- assert result is not None
- assert "pruned" in result
+ # Entry skill is the chain router — must reference step skills
+ assert "hyperresearch-1-decompose" in hyper_body
+ assert "hyperresearch-10-triple-draft" in hyper_body
+ assert "hyperresearch-11-synthesize" in hyper_body
+ assert "hyperresearch-16-readability-audit" in hyper_body
+ # Chain mechanics: must explain Skill tool invocation
+ assert "Skill" in hyper_body
+ # Patching invariant must appear in the skill prose
+ assert "PATCH" in hyper_body
+ # The most common V7 failure mode (single-draft instead of ensemble) must be
+ # called out by name in the entry skill
+ assert "PIPELINE VIOLATION" in hyper_body
-def test_install_skill_idempotent_second_run(tmp_vault):
- first = _install_research_skill(tmp_vault.root)
+def test_install_hyperresearch_skill_idempotent(tmp_vault):
+ first = _install_hyperresearch_skill(tmp_vault.root)
assert first is not None
- second = _install_research_skill(tmp_vault.root)
- assert second is None, "second run should report no changes"
+ second = _install_hyperresearch_skill(tmp_vault.root)
+ assert second is None
-# ---------------------------------------------------------------------------
-# /research-layercake skill
-# ---------------------------------------------------------------------------
+def test_install_hyperresearch_step_skills_creates_all_16(tmp_vault):
+ """Each step skill lives at .claude/skills/hyperresearch-N-name/SKILL.md so the
+ orchestrator can invoke it via the Skill tool. All 16 must install on a
+ fresh vault."""
+ from hyperresearch.core.hooks import (
+ _HYPERRESEARCH_STEP_SKILLS,
+ _install_hyperresearch_step_skills,
+ )
+ result = _install_hyperresearch_step_skills(tmp_vault.root)
+ assert result is not None
+ assert len(_HYPERRESEARCH_STEP_SKILLS) == 16
-def test_install_layercake_skill_creates_separate_skill_dir(tmp_vault):
- """Layercake skill lives at .claude/skills/research-layercake/SKILL.md so
- Claude Code registers `/research-layercake` as its own slash-command trigger."""
- result = _install_layercake_skill(tmp_vault.root)
- own_dir_path = tmp_vault.root / ".claude" / "skills" / "research-layercake" / "SKILL.md"
- assert own_dir_path.exists()
+ skills_root = tmp_vault.root / ".claude" / "skills"
+ for skill_name in _HYPERRESEARCH_STEP_SKILLS:
+ skill_path = skills_root / skill_name / "SKILL.md"
+ assert skill_path.exists(), f"missing step skill: {skill_name}"
- body = own_dir_path.read_text(encoding="utf-8")
- assert "name: research-layercake" in body
- assert "hyperresearch-loci-analyst" in body
- assert "hyperresearch-depth-investigator" in body
- assert "hyperresearch-patcher" in body
- assert "hyperresearch-polish-auditor" in body
- # Patching invariant must appear in the skill prose
- assert "PATCH" in body
- assert result is not None
+ body = skill_path.read_text(encoding="utf-8")
+ # Every step skill must have its name in frontmatter so the Skill tool
+ # can invoke it
+ assert f"name: {skill_name}" in body
+ # Every step skill (except 16, the terminal step) must point to the
+ # next step via the Skill tool
+ if skill_name != "hyperresearch-16-readability-audit":
+ assert "Skill" in body
-def test_install_layercake_skill_idempotent(tmp_vault):
- first = _install_layercake_skill(tmp_vault.root)
+def test_install_hyperresearch_step_skills_idempotent(tmp_vault):
+ from hyperresearch.core.hooks import _install_hyperresearch_step_skills
+
+ first = _install_hyperresearch_step_skills(tmp_vault.root)
assert first is not None
- second = _install_layercake_skill(tmp_vault.root)
+ second = _install_hyperresearch_step_skills(tmp_vault.root)
assert second is None
@@ -109,7 +116,14 @@ def test_install_fetcher_agent(tmp_vault):
agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-fetcher.md"
assert agent_path.exists()
body = agent_path.read_text(encoding="utf-8")
- assert "model: haiku" in body
+ assert "model: sonnet" in body
+ # Summary policy is length-proportional — no hard one-sentence cap.
+ # Long sources should get multi-paragraph summaries, short ones stay
+ # short. The prompt must discuss both ends of that range AND flag
+ # long-source delegation to hyperresearch-source-analyst.
+ assert "proportional" in body.lower()
+ assert "hyperresearch-source-analyst" in body
+ assert "5000 words" in body
assert result is not None
@@ -137,20 +151,46 @@ def test_install_depth_investigator_agent(tmp_vault):
assert result is not None
+def test_install_source_analyst_agent(tmp_vault):
+ """The source-analyst reads ONE long source end-to-end on Sonnet's 1M
+ context window and produces a structured source-analysis note
+ backlinked to the original. Leaf subagent — no Task tool (no
+ recursive spawns)."""
+ result = _install_source_analyst_agent(tmp_vault.root, "hyperresearch")
+ agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-source-analyst.md"
+ assert agent_path.exists()
+ body = agent_path.read_text(encoding="utf-8")
+ assert "model: sonnet" in body
+ # Leaf subagent: no Task, cannot spawn other subagents
+ assert "tools: Bash, Read, Write" in body
+ tools_line = body.split("tools:")[1].split("\n")[0]
+ assert "Task" not in tools_line
+ # Must produce a source-analysis note (canonical NoteType value)
+ assert "source-analysis" in body
+ # Structural template sections the prompt mandates
+ assert "Thesis / Central claim" in body
+ assert "Methodology / Basis of claims" in body
+ assert "Key findings" in body
+ assert "Load-bearing citations" in body
+ assert "Relevance to research_query" in body
+ # Backlink mechanism via body breadcrumb (no custom CLI flag needed)
+ assert "Suggested by" in body
+ # Word-count threshold that decides whether the analyst is appropriate
+ assert "5000" in body
+ assert result is not None
+
+
def test_install_dialectic_critic_agent(tmp_vault):
result = _install_dialectic_critic_agent(tmp_vault.root, "hyperresearch")
agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-dialectic-critic.md"
assert agent_path.exists()
body = agent_path.read_text(encoding="utf-8")
assert "model: opus" in body
- # Critics MUST NOT have Edit or Write — only Bash + Read
- # (they produce JSON findings, they don't mutate the draft)
- assert "tools: Bash, Read" in body
- assert "suggested_patch" in body
- # Surgical-patch discipline (no arbitrary size cap since the 500-char
- # rule was dropped — the tool lock on the patcher enforces regeneration
- # prevention, and critic prompts now teach surgical-patch discipline
- # without a numerical threshold).
+ # Critics have Bash + Read + Write (Write for JSON output; no Edit
+ # since they don't mutate the draft — that's the revisor's job)
+ assert "tools: Bash, Read, Write" in body
+ assert "recommendation" in body
+ assert "location" in body
assert "surgical" in body.lower()
assert result is not None
@@ -204,31 +244,31 @@ def test_install_instruction_critic_agent(tmp_vault):
def test_install_patcher_agent_is_edit_only(tmp_vault):
- """The patcher MUST be tool-locked to Read + Edit only — no Write, no
- Bash. This is the load-bearing invariant that enforces PATCH-NOT-REGEN."""
+ """The revisor (patcher) MUST be tool-locked to Read + Edit only — no
+ Write, no Bash. This is the load-bearing invariant that enforces
+ REVISE-NOT-REGEN."""
result = _install_patcher_agent(tmp_vault.root, "hyperresearch")
agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-patcher.md"
assert agent_path.exists()
body = agent_path.read_text(encoding="utf-8")
- assert "model: sonnet" in body
+ # Opus: substance-integration judgment about which findings serve
+ # the research_query is a reasoning task Sonnet underperforms on.
+ assert "model: opus" in body
# Tool lock: must be exactly "Read, Edit" — not Write, not Bash. The
- # tool lock is what enforces the no-regeneration invariant; there is
- # no arbitrary numerical size cap on hunks.
+ # tool lock is what enforces the no-regeneration invariant.
assert "tools: Read, Edit" in body
assert "tools: Bash" not in body
assert "Write" not in body.split("tools:")[1].split("\n")[0]
assert "regenerat" in body.lower() # the invariant spelled out
assert "surgical" in body.lower()
# Integrate-don't-caveat rule lifts insight score by preventing
- # hedge-appending patches that dilute committed claims.
+ # hedge-appending edits that dilute committed claims.
assert "Integrate, don't caveat" in body
assert "scoping the claim" in body
- # Canonical patch-log schema: the patcher must populate the five
- # fields below and must not invent alternate shapes. Drift across
- # runs (orchestrator_structural_fixes / counts-only variants) was a
- # concrete past failure the test now locks out.
- assert "orchestrator_escalated" in body
- assert "total_findings" in body
+ # Dynamic revision: revisor reads findings with location/issue/
+ # recommendation fields and applies edits using its own judgment.
+ assert "location" in body
+ assert "recommendation" in body
assert "requires_orchestrator_restructure" in body
assert result is not None
@@ -240,7 +280,9 @@ def test_install_polish_auditor_agent_is_edit_only(tmp_vault):
agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-polish-auditor.md"
assert agent_path.exists()
body = agent_path.read_text(encoding="utf-8")
- assert "model: sonnet" in body
+ # Opus: semantic rewrites of scaffold vocabulary + hedge-language
+ # judgment need strong prose comprehension.
+ assert "model: opus" in body
assert "tools: Read, Edit" in body
assert "tools: Bash" not in body
# scaffold-only section list must be injected
@@ -277,13 +319,13 @@ def test_patcher_install_idempotent(tmp_vault):
def test_prune_retired_agents_removes_old_files(tmp_vault):
- """Pre-layercake vaults have analyst/auditor/rewriter/subrun/merger agent
+ """Pre-hyperresearch vaults have analyst/auditor/rewriter/subrun/merger agent
files and a research-ensemble skill dir. Installing onto such a vault
must prune those so the installed state matches the current architecture."""
agents_dir = tmp_vault.root / ".claude" / "agents"
agents_dir.mkdir(parents=True, exist_ok=True)
for name in _RETIRED_AGENT_FILES:
- (agents_dir / name).write_text("pre-layercake content\n", encoding="utf-8")
+ (agents_dir / name).write_text("pre-hyperresearch content\n", encoding="utf-8")
skills_dir = tmp_vault.root / ".claude" / "skills"
for name in _RETIRED_SKILL_DIRS:
@@ -312,34 +354,37 @@ def test_prune_retired_agents_noop_on_clean_vault(tmp_vault):
# ---------------------------------------------------------------------------
-def test_install_hooks_registers_full_layercake_roster(tmp_vault):
- """install_hooks wires the hook + both skills + all 8 layercake agents."""
+def test_install_hooks_registers_full_hyperresearch_roster(tmp_vault):
+ """install_hooks wires the hook, both entry-skill aliases, and the agent roster."""
actions = install_hooks(tmp_vault.root, "hyperresearch")
assert actions # something happened
- # All 8 agent files must be present
+ # All agent files must be present
agents_dir = tmp_vault.root / ".claude" / "agents"
expected_agents = {
"hyperresearch-fetcher.md",
"hyperresearch-loci-analyst.md",
"hyperresearch-depth-investigator.md",
+ "hyperresearch-source-analyst.md",
+ "hyperresearch-corpus-critic.md",
"hyperresearch-dialectic-critic.md",
"hyperresearch-depth-critic.md",
"hyperresearch-width-critic.md",
"hyperresearch-instruction-critic.md",
"hyperresearch-patcher.md",
"hyperresearch-polish-auditor.md",
+ "hyperresearch-readability-recommender.md",
+ "hyperresearch-draft-orchestrator.md",
+ "hyperresearch-synthesizer.md",
}
actual_agents = {p.name for p in agents_dir.iterdir() if p.is_file()}
assert expected_agents == actual_agents, (
f"missing: {expected_agents - actual_agents}, extra: {actual_agents - expected_agents}"
)
- # Both skill entry points registered
+ # Both entry-skill aliases registered (/hyperresearch and /research)
assert (tmp_vault.root / ".claude" / "skills" / "hyperresearch" / "SKILL.md").exists()
- assert (
- tmp_vault.root / ".claude" / "skills" / "research-layercake" / "SKILL.md"
- ).exists()
+ assert (tmp_vault.root / ".claude" / "skills" / "research" / "SKILL.md").exists()
# Hook settings written
assert (tmp_vault.root / ".claude" / "settings.json").exists()
diff --git a/tests/test_core/test_note.py b/tests/test_core/test_note.py
index 56069aa..2839469 100644
--- a/tests/test_core/test_note.py
+++ b/tests/test_core/test_note.py
@@ -32,6 +32,29 @@ def test_write_and_read_roundtrip(tmp_vault):
assert note.word_count > 0
+def test_write_source_analysis_note_roundtrip(tmp_vault):
+ """A source-analysis note (new v8 NoteType) round-trips through write +
+ read with its type preserved in frontmatter. Body breadcrumb
+ `*Suggested by [[source-id]]*` surfaces as an outgoing link that the
+ sync layer will store as a backlink."""
+ path = write_note(
+ tmp_vault.notes_dir,
+ "Source Analysis — Test Paper",
+ body="*Suggested by [[test-paper-source]]*\n\n## Thesis\nThe paper argues X.",
+ note_type="source-analysis",
+ tags=["source-analysis", "test-run"],
+ summary="Multi-paragraph summary.\n\nSecond paragraph with specific numbers: 42 pct.",
+ )
+ assert path.exists()
+
+ note = read_note(path, tmp_vault.root)
+ assert note.meta.type == "source-analysis"
+ assert "test-paper-source" in note.outgoing_links
+ # Multi-line summary preserved through YAML frontmatter serialization
+ assert "Multi-paragraph summary" in note.meta.summary
+ assert "42 pct" in note.meta.summary
+
+
def test_write_avoids_collision(tmp_vault):
p1 = write_note(tmp_vault.notes_dir, "Same Title")
p2 = write_note(tmp_vault.notes_dir, "Same Title")