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
Python agentsagentskillscitationsclaude-codecodexcodex-plugincodex-skilldeep-researchdeep-research-agentdeepresearchmcp-serverresearchresearch-agentresearch-tools
feat: layercake architecture — 7-phase pipeline with tool-locked patching (#8)
Jordan Gibbs75b828de9cee
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex dbfd2cf..6a87dd2 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,50 @@# Changelog+## [0.7.0] - 2026-04-17++### Architecture — `/research-ensemble` retired, `/research-layercake` 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`.+- **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.+- **`patch-surgery` lint rule** — reads `research/patch-log.json` (Layer 6 output) and surfaces any critical finding the patcher skipped. The 500-char "patch too large" regeneration guard is also surfaced at warning severity.+- **`instruction-coverage` lint rule** — reads `research/prompt-decomposition.json` and verifies every atomic item (entity, required format) appears in the final report. Catches drafts that drifted from the user's explicit ask.+- **Layer 0.5 — prompt decomposition** — new orchestrator step before Layer 1 produces `research/prompt-decomposition.json`, a structured breakdown of the atomic items the user's prompt named (sub-questions, entities, required formats, required sections, time horizons, scope conditions). This becomes a first-class contract that flows through Layer 4 drafting and Layer 5 instruction-critique.+- **`hyperresearch-instruction-critic`** — fourth adversarial critic (Opus, `[Bash, Read]` only). Reads the Layer 4 draft against the prompt-decomposition and emits findings for missing / under-covered / mis-ordered / mis-formatted atomic items. Spawned in parallel with dialectic / depth / width critics in Layer 5.+- **Pipeline-awareness contract** — every subagent now receives the verbatim research_query AND an explicit pipeline-position statement in its Task prompt. The skill file documents the three-piece spawn contract (research_query / pipeline position / inputs) and provides a copy-paste template so the orchestrator applies it consistently to every Task call.+- **Schema v7 migration** — safely rebuilds the `notes` table with `'interim'` added to the type CHECK constraint on existing vaults.++### Removed++- **`/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).++### New subagent roster (9 agents)++| Agent | Model | Tools | Role |+|---|---|---|---|+| `hyperresearch-fetcher` | Haiku | Bash, Read | URL → vault note (unchanged) |+| `hyperresearch-loci-analyst` | Sonnet | Bash, Read, Write | Returns 1–8 depth loci from width corpus |+| `hyperresearch-depth-investigator` | Sonnet | Bash, Read, Write, Task | Investigates one locus, writes one interim note |+| `hyperresearch-dialectic-critic` | Opus | Bash, Read | Finds counter-evidence gaps |+| `hyperresearch-depth-critic` | Opus | Bash, Read | Finds shallow spots |+| `hyperresearch-width-critic` | Opus | Bash, Read | Finds topical coverage gaps |+| `hyperresearch-instruction-critic` | Opus | Bash, Read | Finds atomic items the draft missed from prompt-decomposition |+| `hyperresearch-patcher` | Sonnet | **Read, Edit** | Applies critic findings as Edit hunks |+| `hyperresearch-polish-auditor` | Sonnet | **Read, Edit** | Cuts filler + strips hygiene leaks |++### Breaking changes++- Scripts calling `hyperresearch install` on a pre-v0.7 vault will get the old agent files pruned. Pre-existing `research/audit_findings.json` and extract notes stay in the vault (no user data is deleted) but the protocol no longer references them.+- `analyst-coverage` in `hyperresearch lint --rule ...` is gone — use `locus-coverage` and `patch-surgery`.+- The `benchmark-report` lint rule is renamed to `wrapper-report`. The rule's logic is unchanged — it fires whenever `research/prompt.txt` or `research/wrapper_contract.json` is present and enforces the wrapper's contract on the final report. The rename reflects what the rule actually does (wrapper-contract enforcement) rather than the specific harness context where it was first used.+## [0.4.0] - 2026-04-13### Newdiff --git a/README.md b/README.mdindex 4bc0e04..0d760a9 100644--- a/README.md+++ b/README.md@@ -13,13 +13,7 @@----**HyoerResearch is a deep research harness for Claude Code, currently leading the deep research bench internally. Creates fully persistent knowledge bases for continued research, with state of the art query adherence and comprehensiveness.**--<p align="center">- <img src="assets/benchmark.png" alt="DeepResearch-Bench top-5 — hyperresearch at 57.5, ahead of Tongyi DeepResearch (55.8), Kimi Researcher (53.2), Gemini Deep Research (42.1), OpenAI Deep Research (37.4)" width="780">-</p>--<p align="center"><sub>Preliminary — one-query pilot lift (+2.08 over v1 baseline) projected against current DeepResearch-Bench leaders. Full 100-query sweep pending.</sub></p>+**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.**## Installation@@ -28,9 +22,9 @@ pip install hyperresearchhyperresearch install```-In Claude Code, type `/research <anything>` and the full protocol fires.+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 sequence creates a v6 SQLite vault, auto-installs Chromium for headless browsing, generates `CLAUDE.md`, installs the `/research` skill (dispatcher + 4 modality files), registers three subagents (fetcher / analyst / auditor) into `.claude/agents/`, and wires PreToolUse hooks.+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.---@@ -91,6 +85,64 @@ The save gate blocks until every CRITICAL is **genuinely** resolved. Bookkeeping---+## `/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.++### The 7 phases++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.++### Why the tool lock matters++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.++### Opting out — faster single-pass mode++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.++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.++---++## 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:++```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 researchYour 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:@@ -143,13 +195,18 @@ Your AI agent searches the web, skims sources, writes an answer that sounds good└─────────────────────────────────────────────────────────────────────┘```-**Subagent triad**, each picked for its job:+**Subagent roster**, each picked for its job:| Agent | Model | Role ||---|---|---|| `hyperresearch-fetcher` | **Haiku** | Mechanical URL fetching via crawl4ai. Cheap, fast, parallel. |-| `hyperresearch-analyst` | **Sonnet** | Reads one source with research goal in hand. Writes a focused extract, proposes 2-5 next URLs for the loop. |-| `hyperresearch-auditor` | **Opus** | Adversarial review in two modes against the verbatim prompt. Persists structured findings the save gate verifies. |+| `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:@@ -166,16 +223,17 @@ A query about a fictional franchise can be `collect` (per-character enumeration)## What's enforced-Eight invariants the protocol structurally prevents from breaking:+Nine invariants the protocol structurally prevents from breaking:-1. **Verbatim prompt as gospel** — `scaffold-prompt` lint blocks at Checkpoint 3 if the scaffold doesn't open with the user's exact prompt+1. **Verbatim prompt as gospel** — `scaffold-prompt` lint blocks if the scaffold doesn't open with the user's exact prompt2. **Rooted-tree provenance** — `--suggested-by` chain must form a real tree from at least one seed; isolated breadcrumbs flagged-3. **Analyst coverage** — at least 1 extract per 3 sources, no silent skipping-4. **Adversarial dissent** — at least one source explicitly contradicts the dominant view, named in writing-5. **Audit-gate self-cert detection** — CRITICAL findings marked fixed get their underlying lint rules re-run-6. **Save blocked** until every CRITICAL is genuinely resolved-7. **Schema integrity** — `tier` and `content_type` are SQLite CHECK-constrained vocabularies; corrupted frontmatter cannot poison the index-8. **PDF + raw artifact persistence** — fetched PDFs land in `research/raw/` and the `raw_file` frontmatter field survives every re-serialization+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---@@ -196,11 +254,8 @@ Eight invariants the protocol structurally prevents from breaking:- **Forecasting + strategy** — "Will US inflation stay above 3% through 2026?" → ground-truth statistics + institutional analysis + named contrarians, probability language not hedge- **Interpretive analysis** — "What does *Blood Meridian*'s violence mean?" → primary text + critical tradition + dissenting reading, every paragraph fuses fact with interpretive claim- **Enumerative coverage** — "For each Napoleonic marshal, cover key campaigns and fate" → every named entity gets every requested field, no silent downgrades-- **Persistent knowledge base** — every source ever fetched stays searchable. Future sessions check the vault before searching the web. Knowledge compounds.-### `/research-ensemble` — 3 parallel sub-runs + Opus merger (what was benchmarked)--For queries where depth-of-corpus and argument stability matter more than wall-clock time, use `/research-ensemble <query>`. Opus orchestrates; three `hyperresearch-subrun` Sonnet agents run the full protocol in parallel against one shared vault, each with a subtly different framing (evidentiary breadth / citation-chain depth / dialectical tension). A fourth agent (`hyperresearch-merger`, Opus) scores each draft on comprehensiveness / readability / argument strength / citation quality, picks the strongest as the base, and splices in unique evidence from the other two. Cost is ~5× a normal run; the payoff is detailed in [Benchmarks](#benchmarks) below.+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.---@@ -210,8 +265,8 @@ 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-ensemble/`** — `/research-ensemble` skill (3× parallel sub-runs + Opus merger; see [Benchmarks](#benchmarks))-- **`.claude/agents/`** — six registered subagents: `hyperresearch-fetcher` (Haiku), `hyperresearch-analyst` (Sonnet), `hyperresearch-auditor` (Opus), `hyperresearch-rewriter` (Sonnet), `hyperresearch-subrun` (Sonnet, ensemble), `hyperresearch-merger` (Opus, ensemble)+- **`.claude/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 sessionhyperresearch 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.@@ -271,26 +326,6 @@ LinkedIn, Twitter, Facebook, Instagram, and TikTok automatically use a visible b----## Benchmarks--Hyperresearch is being evaluated on the [DeepResearch Bench](https://github.com/Ayanami0730/deep_research_bench) RACE eval (Gemini-2.5-Pro judges reports on comprehensiveness, insight, instruction-following, readability). Full per-modality scores and head-to-head comparisons vs other research harnesses will land here as the 100-query sweep completes. **Status:** in progress.--### Ensemble lift — preliminary data point--Query 91 from DeepResearch-Bench ("detailed analysis of the Saint Seiya franchise, structured around armor classes, per-character power/techniques/arcs/fate") is a deep-collect query with ~100 named entities. One data point so far:--| Variant | Overall | Comp. | Insight | Inst. | Read. | Cost | Time |-|---|---:|---:|---:|---:|---:|---:|---:|-| `/research` single-run (sonnet, v1 baseline) | **52.74** | 52.95 | 58.74 | 51.28 | 51.90 | ~$1.50 | ~8 min |-| `/research-ensemble` (3× sonnet + opus merger) | **54.82** | 54.52 | 58.57 | 53.30 | 56.10 | $21.98 | 57 min |-| **Delta** | **+2.08** | +1.57 | −0.17 | +2.02 | +4.20 | ~14× | ~7× |--Readability is the biggest single lift (+4.20) — the merger smooths splice boundaries and harmonizes voice across the three sub-runs. Instruction-following (+2.02) gains from three independent passes cross-checking the prompt's entity list; prompt-named entities the base run collapsed get restored from sibling runs. Comprehensiveness (+1.57) comes from the 3-way evidence union (167 sources fetched into the shared corpus vs ~30 for a single run). Insight is flat as expected — the merger is a compiler, not a re-thinker; it can't deepen an argument beyond what the strongest sub-run already had.--One query is not a benchmark. Full 100-query sweep coming next. The cost ceiling is honest: ~5× per query at the tool-call level, ~14× here because `/research` ran on Sonnet and `/research-ensemble` requires Opus orchestration + Opus merger. Use ensemble where the query earns it; use `/research` for everything else.------## Philosophy- **Process is load-bearing.** A draft without a scaffold, comparisons, audit findings, and a clean provenance graph is unfinished — regardless of how good the prose reads.diff --git a/assets/_generate_benchmark.py b/assets/_generate_benchmark.pydeleted file mode 100644index 732bdb9..0000000--- a/assets/_generate_benchmark.py+++ /dev/null@@ -1,165 +0,0 @@-"""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.pngdeleted file mode 100644index a670847..0000000Binary files a/assets/benchmark.png and /dev/null differdiff --git a/pyproject.toml b/pyproject.tomlindex eb77af9..dd04c80 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "hyperresearch"-version = "0.6.0"+version = "0.7.0"description = "Claude Code harness for disciplined, adversarially-audited deep research with full provenance."readme = "README.md"license = "MIT"diff --git a/src/hyperresearch/cli/lint.py b/src/hyperresearch/cli/lint.pyindex e70aeaf..b66762a 100644--- a/src/hyperresearch/cli/lint.py+++ b/src/hyperresearch/cli/lint.py@@ -2,11 +2,13 @@from __future__ import annotations+import jsonfrom datetime import UTCimport typerfrom hyperresearch.cli._output import console, output+from hyperresearch.core.hooks import SCAFFOLD_ONLY_SECTION_HEADERSfrom hyperresearch.models.output import successapp = typer.Typer(invoke_without_command=True)@@ -16,11 +18,15 @@ RULES = {"missing-tags": "Notes without any tags","missing-summary": "Notes without a summary","uncurated": "Non-draft notes without tier or content_type classification",- "workflow": "Draft or synthesis notes missing paired scaffold/comparison notes",+ "workflow": "Layercake 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","provenance": "Source notes with no --suggested-by breadcrumb chain (data-flow chain broken)",- "analyst-coverage": "Fetched sources without paired extract notes (analyst skipped most sources)",+ "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)","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",@@ -253,16 +259,40 @@ def lint(("gospel rule", "scaffold-prompt"),("user prompt missing", "scaffold-prompt"),- # analyst-coverage (extract notes per source)- ("analyst-coverage", "analyst-coverage"),- ("analyst coverage", "analyst-coverage"),- ("analyst_coverage", "analyst-coverage"),- ("extract coverage", "analyst-coverage"),- ("extract ratio", "analyst-coverage"),- ("extract notes", "analyst-coverage"),- ("fetch:extract", "analyst-coverage"),- ("analyst skipped", "analyst-coverage"),- ("no extract", "analyst-coverage"),+ # locus-coverage (interim note per identified locus)+ ("locus-coverage", "locus-coverage"),+ ("locus coverage", "locus-coverage"),+ ("locus_coverage", "locus-coverage"),+ ("missing interim", "locus-coverage"),+ ("interim note", "locus-coverage"),+ ("depth investigator", "locus-coverage"),++ # extract-coverage (single-pass extract:source ratio)+ ("extract-coverage", "extract-coverage"),+ ("extract coverage", "extract-coverage"),+ ("extract_coverage", "extract-coverage"),+ ("extract ratio", "extract-coverage"),+ ("extract notes", "extract-coverage"),+ ("fetch:extract", "extract-coverage"),+ ("analyst skipped", "extract-coverage"),+ ("no extract", "extract-coverage"),++ # patch-surgery (patcher didn't apply critical findings)+ ("patch-surgery", "patch-surgery"),+ ("patch surgery", "patch-surgery"),+ ("patch_surgery", "patch-surgery"),+ ("patch log", "patch-surgery"),+ ("critical finding skipped", "patch-surgery"),+ ("regeneration", "patch-surgery"),++ # instruction-coverage (decomposition items in final report)+ ("instruction-coverage", "instruction-coverage"),+ ("instruction coverage", "instruction-coverage"),+ ("instruction_coverage", "instruction-coverage"),+ ("prompt decomposition", "instruction-coverage"),+ ("prompt-decomposition", "instruction-coverage"),+ ("atomic item", "instruction-coverage"),+ ("atomic items", "instruction-coverage"),# provenance (bouncing reading loop + --suggested-by chain)("provenance", "provenance"),@@ -362,6 +392,37 @@ def lint(r"^\s*##\s+User\s+Prompt\s*\(\s*VERBATIM.*gospel\s*\)",_re.IGNORECASE,)+ prompt_path = vault.root / "research" / "prompt.txt"+ canonical_prompt: str | None = None+ if prompt_path.exists():+ try:+ canonical_prompt = (+ prompt_path.read_text(encoding="utf-8-sig")+ .replace("\r\n", "\n")+ .rstrip("\n")+ )+ except OSError:+ canonical_prompt = None++ def _extract_prompt_text(body_lines: list[str], header_line_idx: int) -> str:+ prompt_lines: list[str] = []+ for line in body_lines[header_line_idx + 1:]:+ stripped = line.rstrip("\r\n")+ if stripped.lstrip().startswith("##"):+ break+ if stripped.lstrip().startswith(">"):+ raw = stripped.lstrip()[1:]+ if raw.startswith(" "):+ raw = raw[1:]+ prompt_lines.append(raw)+ else:+ prompt_lines.append(stripped)+ while prompt_lines and not prompt_lines[0]:+ prompt_lines.pop(0)+ while prompt_lines and not prompt_lines[-1]:+ prompt_lines.pop()+ return "\n".join(prompt_lines).replace("\r\n", "\n")+for row in conn.execute("""SELECT n.id, n.path, nc.bodyFROM notes n@@ -397,23 +458,31 @@ def lint(})continue- # Check for non-empty blockquote after the header (>= 50 chars total,- # which is a loose floor — a real prompt will be much longer).- quote_chars = 0- for line in body_lines[header_line_idx + 1:]:- stripped = line.strip()- if not stripped:- continue- if stripped.startswith(">"):- quote_chars += len(stripped.lstrip("> ").strip())- elif stripped.startswith("##"):- break # hit next header without finding quoted content- else:- # some scaffolds paste the prompt as plain text without- # the blockquote prefix — accept if substantive.- quote_chars += len(stripped)- break+ extracted_prompt = _extract_prompt_text(body_lines, header_line_idx)++ # When a canonical prompt artifact exists, require exact equality+ # (modulo line-ending normalization only). This turns the scaffold+ # rule from "has something prompt-like" into a real contract check.+ if canonical_prompt is not None:+ if extracted_prompt != canonical_prompt:+ issues.append({+ "rule": "scaffold-prompt",+ "severity": "error",+ "note_id": row["id"],+ "note_path": row["path"],+ "message": (+ "Scaffold prompt does not exactly match research/prompt.txt. "+ "The verbatim prompt is a hard contract when a harness pins it — "+ "re-copy it character-for-character under the "+ "`## User Prompt (VERBATIM — gospel)` header."+ ),+ })+ continue+ # Fallback for vaults without a canonical-prompt artifact with no canonical prompt artifact:+ # require non-trivial content after the header so the rule still+ # protects against empty placeholder scaffolds.+ quote_chars = len(extracted_prompt)if quote_chars < 50:issues.append({"rule": "scaffold-prompt",@@ -427,6 +496,111 @@ 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/wrapper_contract.json exists (harness declared packaging)+ #+ # Required terminal sections are READ from wrapper_contract.json, not+ # hardcoded. This keeps the lint mechanism-focused — any wrapper can+ # declare its own packaging contract and the rule will enforce it+ # verbatim. No wrapper declared => skip the terminal-section check+ # but still enforce scaffold-leak hygiene (always wrong regardless+ # of wrapper).+ prompt_path = vault.root / "research" / "prompt.txt"+ contract_path = vault.root / "research" / "wrapper_contract.json"+ wrapper_contract: dict | None = None+ if contract_path.exists():+ try:+ wrapper_contract = json.loads(+ contract_path.read_text(encoding="utf-8-sig")+ )+ except (OSError, json.JSONDecodeError) as exc:+ issues.append({+ "rule": "wrapper-report",+ "severity": "error",+ "note_id": "<vault>",+ "message": (+ f"wrapper_contract.json exists but is unreadable: "+ f"{type(exc).__name__}: {exc}. Fix the JSON or remove "+ f"the file."+ ),+ })+ wrapper_contract = None++ if prompt_path.exists() or wrapper_contract is not None:+ report_path = vault.root / "research" / "notes" / "final_report.md"+ if not report_path.exists():+ issues.append({+ "rule": "wrapper-report",+ "severity": "error",+ "note_id": "<vault>",+ "message": (+ "Wrapped research context detected (prompt.txt or "+ "wrapper_contract.json present) but "+ "`research/notes/final_report.md` is missing. "+ "The final report must exist before export."+ ),+ })+ else:+ try:+ report_body = report_path.read_text(encoding="utf-8-sig").replace("\r\n", "\n")+ except OSError as exc:+ issues.append({+ "rule": "wrapper-report",+ "severity": "error",+ "note_id": "<vault>",+ "message": (+ f"Could not read final report at {report_path}: "+ f"{type(exc).__name__}."+ ),+ })+ report_body = ""++ # Wrapper-declared required terminal sections (optional).+ required_headers: list[str] = []+ if wrapper_contract is not None:+ raw = wrapper_contract.get("required_terminal_sections", [])+ if isinstance(raw, list):+ required_headers = [str(h) for h in raw if isinstance(h, str)]+ missing_headers = [h for h in required_headers if h not in report_body]+ if missing_headers:+ issues.append({+ "rule": "wrapper-report",+ "severity": "error",+ "note_id": "<vault>",+ "message": (+ "wrapper_contract.json declares required_terminal_sections "+ "that are missing from the final report. Missing: "+ f"{', '.join(missing_headers)}."+ ),+ })++ # Scaffold-leak hygiene: ALWAYS enforced. Base list comes from+ # the canonical SCAFFOLD_ONLY_SECTION_HEADERS constant in+ # hooks.py (shared with the three agent prompts). Wrapper can+ # declare additional forbidden body sections on top.+ forbidden_headers = list(SCAFFOLD_ONLY_SECTION_HEADERS)+ if wrapper_contract is not None:+ extra = wrapper_contract.get("forbidden_body_sections", [])+ if isinstance(extra, list):+ for h in extra:+ if isinstance(h, str) and h not in forbidden_headers:+ forbidden_headers.append(h)++ leaked = [h for h in forbidden_headers if h in report_body]+ if leaked:+ issues.append({+ "rule": "wrapper-report",+ "severity": "error",+ "note_id": "<vault>",+ "message": (+ "Final report is leaking scaffold-only sections into "+ "the deliverable. Remove: "+ f"{', '.join(leaked)}."+ ),+ })+if "provenance" in rules_to_run:# Verify the `--suggested-by` data-flow chain forms a rooted tree# (or forest) across all fetched source notes:@@ -537,12 +711,37 @@ def lint(),})- # Condition: coverage. At least half of non-seed sources should have a breadcrumb.- # (Cheap heuristic: the count of non-seeds is the count of sources with at least- # one breadcrumb; compare to the count of sources that SHOULD have one.)+ # Coverage / bouncing-loop heuristic: DOES NOT APPLY to layercake 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:+ # - 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.+ # - Layer 3 depth investigators: each can spawn fetchers with+ # --suggested-by when URLs come from corpus notes, but most+ # depth fetches are also driven by locus planning, not+ # analyst-hop chaining.+ #+ # 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()+non_seed_ratio = len(non_seeds) / max(len(source_rows), 1)- # If there is exactly one seed and no non-seeds, the loop never fired.- if len(source_rows) > 5 and len(non_seeds) == 0:+ if is_layercake_run:+ # Layercake: 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+ # loop must fire. Zero breadcrumbs on >5 sources = flat batch.issues.append({"rule": "provenance","severity": "error",@@ -556,10 +755,6 @@ def lint(),})elif non_seed_ratio < 0.3 and len(source_rows) > 10:- # Less than 30% of the corpus came from analyst recommendations.- # The guided reading loop effectively didn't fire — this is the- # exact failure mode both v2 runs exhibited (3/19 and 2/33).- # Error severity because it blocks Checkpoint 2.issues.append({"rule": "provenance","severity": "error",@@ -573,7 +768,6 @@ def lint(),})elif non_seed_ratio < 0.5 and len(source_rows) > 10:- # Between 30% and 50% — under-firing but marginal. Warning only.issues.append({"rule": "provenance","severity": "warning",@@ -585,83 +779,386 @@ def lint(),})- if "analyst-coverage" in rules_to_run:- # Detect when source notes were fetched but few were analyzed (i.e.,- # spawned a hyperresearch-analyst that wrote an extract note). An- # extract note is identified by carrying the `extract` tag.- #- # Rule applies UNCONDITIONALLY — previous versions gated on- # `source_count >= 10` which silently disabled the rule for small- # corpora (a compare session with 8 named entities could ship zero- # extracts and pass). The gate is removed.+ if "locus-coverage" in rules_to_run:+ # Layercake Layer 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.+ loci_path = vault.root / "research" / "loci.json"+ if loci_path.exists():+ try:+ loci_data = json.loads(loci_path.read_text(encoding="utf-8"))+ loci_list = loci_data.get("loci", []) if isinstance(loci_data, dict) else loci_data+ except (json.JSONDecodeError, OSError):+ loci_list = []+ issues.append({+ "rule": "locus-coverage",+ "severity": "error",+ "note_id": "<vault>",+ "message": (+ "research/loci.json exists but is not valid JSON. "+ "Layer 2 output corrupted — re-run loci analysis."+ ),+ })++ missing_loci: list[str] = []+ for locus in loci_list:+ if not isinstance(locus, dict):+ continue+ name = locus.get("name")+ if not name:+ continue+ tag = f"locus-{name}"+ row = conn.execute(+ "SELECT COUNT(*) as c FROM notes n "+ "JOIN tags t ON t.note_id = n.id "+ "WHERE t.tag = ? AND n.type = 'interim'",+ (tag,),+ ).fetchone()+ interim_count = row["c"] if row else 0+ if interim_count == 0:+ missing_loci.append(name)++ if missing_loci:+ severity = "error" if len(missing_loci) >= 2 else "warning"+ issues.append({+ "rule": "locus-coverage",+ "severity": severity,+ "note_id": "<vault>",+ "message": (+ f"{len(missing_loci)} of {len(loci_list)} loci have no interim note: "+ f"{', '.join(missing_loci[:6])}{'...' if len(missing_loci) > 6 else ''}. "+ "The depth investigator either failed or was skipped. "+ "Layer 3 must produce one `interim-<locus>.md` note per locus "+ "with `type: interim` and `tag: locus-<name>`."+ ),+ })++ # Duplicate interim notes on the same locus — a past failure+ # mode where one locus accumulated 3 interim notes. Inflates+ # source count and confuses Layer 5 critics. Warn when any+ # locus has >1 interim.+ duplicate_loci: list[tuple[str, int]] = []+ for locus in loci_list:+ if not isinstance(locus, dict):+ continue+ name = locus.get("name")+ if not name:+ continue+ tag = f"locus-{name}"+ row = conn.execute(+ "SELECT COUNT(*) as c FROM notes n "+ "JOIN tags t ON t.note_id = n.id "+ "WHERE t.tag = ? AND n.type = 'interim'",+ (tag,),+ ).fetchone()+ c = row["c"] if row else 0+ if c > 1:+ duplicate_loci.append((name, c))++ if duplicate_loci:+ summary = ", ".join(f"{n} ({c})" for n, c in duplicate_loci[:6])+ issues.append({+ "rule": "locus-coverage",+ "severity": "warning",+ "note_id": "<vault>",+ "message": (+ f"{len(duplicate_loci)} locus/loci have duplicate interim notes: "+ f"{summary}. Depth investigators must check for an existing "+ "interim note on their locus before calling `note new`; if one "+ "exists, use `note update` or report back to the orchestrator. "+ "Delete the weaker copies manually."+ ),+ })++ if "extract-coverage" in rules_to_run:+ # Single-pass /research runs use the "bouncing reading loop": fetch a+ # seed, analyst reads it and proposes next URLs, main agent fetches+ # those, loop. Each fetched source should have a paired extract note+ # (tagged `extract`) with ≥150 words of real content. This rule+ # enforces that discipline — it catches flat-batch fetchers who never+ # spawned an analyst, AND it catches stub-padding attacks where the+ # agent mints hollow extract notes to pass numerical coverage.#- # extract_min_words floor: only notes with body word_count >= this- # threshold count as "real" extracts. Anti-lint-gaming — a batch of- # 40 stub notes at ~75 words each must not satisfy analyst-coverage- # by count alone. Real analyst extracts run 400-1000+ words with- # direct quotes; anything below 150 words is a label, not an- # extraction. See the Q91 ensemble run where the orchestrator- # minted 45 stub extracts to pass this gate.- extract_min_words = 150-- source_count_row = conn.execute(- "SELECT COUNT(*) as c FROM notes n "- "WHERE n.source IS NOT NULL "- "AND n.id NOT LIKE '\\_%' ESCAPE '\\' "- "AND n.type NOT IN ('index','raw','moc') "- "AND n.id NOT IN (SELECT note_id FROM tags WHERE tag = 'extract') "- "AND n.id NOT IN (SELECT note_id FROM tags WHERE tag = 'scaffold') "- "AND n.id NOT IN (SELECT note_id FROM tags WHERE tag = 'comparison')"- ).fetchone()- source_count = source_count_row["c"] if source_count_row else 0-- # Count REAL extracts (body word_count >= 150) — stubs don't satisfy.- extract_count_row = conn.execute(- "SELECT COUNT(DISTINCT n.id) as c FROM notes n "- "JOIN tags t ON t.note_id = n.id "- "WHERE t.tag = 'extract' AND n.word_count >= ?",- (extract_min_words,),- ).fetchone()- extract_count = extract_count_row["c"] if extract_count_row else 0-- # Also count stubs separately so the lint message can be honest about- # what's there — a vault with 13 real + 45 stub extracts shows that- # fact explicitly rather than silently collapsing to "13 extracts".- stub_count_row = conn.execute(- "SELECT COUNT(DISTINCT n.id) as c FROM notes n "- "JOIN tags t ON t.note_id = n.id "- "WHERE t.tag = 'extract' AND n.word_count < ?",- (extract_min_words,),- ).fetchone()- stub_count = stub_count_row["c"] if stub_count_row else 0-- # Require 1/3 coverage (error floor at 1/4). Even a 2-source session- # needs at least 1 extract — the analyst is mandatory, not optional.- if source_count >= 1:- required_extracts = max(1, source_count // 3)- error_floor = max(1, source_count // 4)- if extract_count < required_extracts:- ratio = extract_count / source_count if source_count else 0- stub_note = (- f" (plus {stub_count} stub notes under {extract_min_words} words, not counted)"- if stub_count else ""+ # Layercake 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:+ extract_min_words = 150++ source_count_row = conn.execute(+ "SELECT COUNT(*) as c FROM notes n "+ "WHERE n.source IS NOT NULL "+ "AND n.id NOT LIKE '\\_%' ESCAPE '\\' "+ "AND n.type NOT IN ('index','raw','moc') "+ "AND n.id NOT IN (SELECT note_id FROM tags WHERE tag = 'extract') "+ "AND n.id NOT IN (SELECT note_id FROM tags WHERE tag = 'scaffold') "+ "AND n.id NOT IN (SELECT note_id FROM tags WHERE tag = 'comparison') "+ "AND n.id NOT IN (SELECT note_id FROM tags WHERE tag = 'dud')"+ ).fetchone()+ source_count = source_count_row["c"] if source_count_row else 0++ # REAL extracts: tagged `extract`, body ≥150 words, with parent+ # pointing at a real source note (chain of custody). Stubs and+ # unlinked real-looking extracts don't satisfy.+ extract_count_row = conn.execute(+ "SELECT COUNT(DISTINCT n.id) as c FROM notes n "+ "JOIN tags t ON t.note_id = n.id "+ "WHERE t.tag = 'extract' "+ "AND n.word_count >= ? "+ "AND n.parent IS NOT NULL AND n.parent != '' "+ "AND n.parent IN (SELECT id FROM notes WHERE source IS NOT NULL) "+ "AND n.id NOT IN (SELECT note_id FROM tags WHERE tag = 'dud')",+ (extract_min_words,),+ ).fetchone()+ extract_count = extract_count_row["c"] if extract_count_row else 0++ # Count stubs separately so the lint message stays honest — a+ # vault with 13 real + 45 stub extracts should show that, not+ # silently collapse to "13 extracts".+ stub_count_row = conn.execute(+ "SELECT COUNT(DISTINCT n.id) as c FROM notes n "+ "JOIN tags t ON t.note_id = n.id "+ "WHERE t.tag = 'extract' AND n.word_count < ? "+ "AND n.id NOT IN (SELECT note_id FROM tags WHERE tag = 'dud')",+ (extract_min_words,),+ ).fetchone()+ stub_count = stub_count_row["c"] if stub_count_row else 0++ # Real extracts with no valid parent — broken chain of custody.+ unlinked_real_row = conn.execute(+ "SELECT COUNT(DISTINCT n.id) as c FROM notes n "+ "JOIN tags t ON t.note_id = n.id "+ "WHERE t.tag = 'extract' "+ "AND n.word_count >= ? "+ "AND (n.parent IS NULL OR n.parent = '' "+ " OR n.parent NOT IN (SELECT id FROM notes WHERE source IS NOT NULL)) "+ "AND n.id NOT IN (SELECT note_id FROM tags WHERE tag = 'dud')",+ (extract_min_words,),+ ).fetchone()+ unlinked_real = unlinked_real_row["c"] if unlinked_real_row else 0++ # Require 1/3 coverage (error floor at 1/4). Even a 2-source+ # session needs at least 1 extract — the analyst is mandatory+ # on single-pass runs, not optional.+ if source_count >= 1:+ required_extracts = max(1, source_count // 3)+ error_floor = max(1, source_count // 4)+ if extract_count < required_extracts:+ ratio = extract_count / source_count if source_count else 0+ notes_parts = []+ if stub_count:+ notes_parts.append(+ f"{stub_count} stub notes under {extract_min_words} words, not counted"+ )+ if unlinked_real:+ notes_parts.append(+ f"{unlinked_real} unlinked real extracts missing a valid parent source-id, not counted"+ )+ stub_note = f" (plus {'; '.join(notes_parts)})" if notes_parts else ""+ issues.append({+ "rule": "extract-coverage",+ "severity": "error" if extract_count < error_floor else "warning",+ "note_id": "<vault>",+ "message": (+ f"Vault has {source_count} fetched source notes but only {extract_count} "+ f"real source-linked extract notes{stub_note} "+ f"({ratio:.0%} coverage, need ≥{required_extracts}). "+ f"The analyst was skipped on most sources or the source->extract chain "+ f"of custody is broken. Spawn an analyst subagent on the unanalyzed "+ f"sources during curation. Target: at least 1 extract "+ f"(≥{extract_min_words} words, with `parent=<source-note-id>`) per 3 "+ f"sources (floor of 1 for any corpus size). Minting stub notes to "+ f"pass this gate is lint-gaming and will not satisfy."+ ),+ })++ if "patch-surgery" in rules_to_run:+ # Layer 6 writes research/patch-log.json. The log records applied,+ # skipped, and conflicted findings. Skipped `critical` findings are+ # blockers — the draft shipped with a critical critique unresolved.+ # This rule surfaces that.+ patch_log_path = vault.root / "research" / "patch-log.json"+ if patch_log_path.exists():+ try:+ log = json.loads(patch_log_path.read_text(encoding="utf-8"))+ except (json.JSONDecodeError, OSError):+ issues.append({+ "rule": "patch-surgery",+ "severity": "error",+ "note_id": "<vault>",+ "message": (+ "research/patch-log.json exists but is not valid JSON. "+ "Layer 6 output corrupted."+ ),+ })+ log = {}++ skipped = log.get("skipped", []) if isinstance(log, dict) else []+ critical_skipped = [+ e for e in skipped+ if isinstance(e, dict) and e.get("severity") == "critical"+ ]+ if critical_skipped:+ names = ", ".join(+ f"#{e.get('finding_id', '?')} ({e.get('critic', '?')})"+ for e in critical_skipped[:5])issues.append({- "rule": "analyst-coverage",- "severity": "error" if extract_count < error_floor else "warning",+ "rule": "patch-surgery",+ "severity": "error","note_id": "<vault>","message": (- f"Vault has {source_count} fetched source notes but only {extract_count} "- f"real extract notes{stub_note} ({ratio:.0%} coverage, need ≥{required_extracts}). "- f"The analyst was skipped on most sources. Spawn "- f"hyperresearch-analyst (mode=extract or mode=guided) on the "- f"unanalyzed sources during curation. Target: at least 1 extract "- f"(≥{extract_min_words} words) per 3 sources (floor of 1 for any "- f"corpus size). Minting stub notes to pass this gate is lint-gaming "- f"and will not satisfy — spawn real analysts."+ 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."),})+ # "Empty log" detector — distinguishes "patcher ran, log lost" from+ # "patcher ran, applied nothing legitimately".+ #+ # If: (a) there are critic findings files with >0 findings AND+ # (b) the final report exists AND+ # (c) the patch log's applied+skipped+conflicts total is 0+ # then the patcher's log was lost in transit (e.g., the log-stub+ # file wasn't pre-created, so the Edit-only patcher couldn't+ # populate it and inlined the log in its Task result). The real+ # patches DID get applied to the draft, but the audit trail is+ # gone — we can't verify what the patcher did.+ applied = log.get("applied", []) if isinstance(log, dict) else []+ conflicts = log.get("conflicts", []) if isinstance(log, dict) else []+ total_logged = len(applied) + len(skipped) + len(conflicts)++ # Only flag when there WERE findings to apply.+ critic_totals = 0+ for name in ("dialectic", "depth", "width"):+ cf = vault.root / "research" / f"critic-findings-{name}.json"+ if cf.exists():+ try:+ cdata = json.loads(cf.read_text(encoding="utf-8"))+ critic_totals += len(cdata.get("findings", []))+ except (json.JSONDecodeError, OSError):+ pass++ final_report = vault.root / "research" / "notes" / "final_report.md"+ if (+ total_logged == 0+ and critic_totals > 0+ and final_report.exists()+ ):+ issues.append({+ "rule": "patch-surgery",+ "severity": "warning",+ "note_id": "<vault>",+ "message": (+ f"Patch log is empty (applied=0, skipped=0, conflicts=0) "+ f"but critics returned {critic_totals} findings and the "+ "final report exists. The patcher's log was almost "+ "certainly lost in transit — Layer 6 orchestrator "+ "didn't pre-create `research/patch-log.json` as an "+ "empty stub, so the tool-locked patcher (`[Read, Edit]` "+ "only) couldn't populate it and inlined the log in its "+ "Task result instead. The draft WAS patched — you can "+ "verify via `git diff` on the L4 draft snapshot — but "+ "the audit trail is gone. Fix: orchestrator must "+ "`echo '{\"applied\":[], \"skipped\":[], \"conflicts\":[]}' "+ "> research/patch-log.json` before spawning the patcher."+ ),+ })++ if "instruction-coverage" in rules_to_run:+ # Layer 0.5 produces `research/prompt-decomposition.json` — a structured+ # breakdown of the atomic items the user's prompt named (sub-questions,+ # entities, required formats, etc.). The final_report.md is expected to+ # cover every atomic item. This rule does a lightweight text-presence+ # check: for each named entity or sub-question in the decomposition,+ # verify the final report mentions it.+ #+ # This is a shallow check — surface presence, not structural mirroring.+ # The instruction-critic agent (Layer 5) does the deeper structural+ # audit. This lint rule is the final post-patch gate that catches+ # items the critic flagged but the patcher couldn't apply.+ decomp_path = vault.root / "research" / "prompt-decomposition.json"+ final_report = vault.root / "research" / "notes" / "final_report.md"+ if decomp_path.exists() and final_report.exists():+ try:+ decomp = json.loads(decomp_path.read_text(encoding="utf-8"))+ except (json.JSONDecodeError, OSError) as exc:+ issues.append({+ "rule": "instruction-coverage",+ "severity": "error",+ "note_id": "<vault>",+ "message": (+ f"research/prompt-decomposition.json exists but is "+ f"not valid JSON: {exc}. Layer 0.5 output corrupted."+ ),+ })+ decomp = None++ if isinstance(decomp, dict):+ try:+ report_text = final_report.read_text(encoding="utf-8")+ except OSError:+ report_text = ""+ report_lower = report_text.lower()++ missing_entities: list[str] = []+ entities = decomp.get("entities", []) or []+ for ent in entities:+ if not isinstance(ent, dict):+ continue+ name = ent.get("name") or ""+ if name and name.lower() not in report_lower:+ missing_entities.append(name)++ if missing_entities:+ severity = "error" if len(missing_entities) >= 3 else "warning"+ preview = ", ".join(missing_entities[:8])+ if len(missing_entities) > 8:+ preview += f", ... (+{len(missing_entities) - 8} more)"+ issues.append({+ "rule": "instruction-coverage",+ "severity": severity,+ "note_id": "<vault>",+ "message": (+ f"{len(missing_entities)} atomic entity/entities "+ f"from prompt-decomposition.json are missing from "+ f"the final report: {preview}. The draft drifted "+ "from the user's explicit ask. Re-spawn the "+ "instruction-critic with the missing items "+ "flagged, or hand-craft Edits to restore them."+ ),+ })++ # Required formats are a more structural check — we can't+ # reliably grep for "is this a mind map" — but if the format+ # name is literally missing from the prose, that's a signal.+ missing_formats: list[str] = []+ for fmt in (decomp.get("required_formats", []) or []):+ if not isinstance(fmt, str):+ continue+ # Pull the content-word from the format spec (e.g., "mind+ # map of causal structure" → "mind map")+ head = fmt.split(" of ")[0].strip().lower()+ if head and head not in report_lower:+ missing_formats.append(fmt)+ if missing_formats:+ issues.append({+ "rule": "instruction-coverage",+ "severity": "warning",+ "note_id": "<vault>",+ "message": (+ f"Required format(s) from prompt-decomposition not "+ f"visibly present in draft: {', '.join(missing_formats[:5])}. "+ "This may be a false positive if the format is "+ "rendered without the spec word in the prose — "+ "review manually."+ ),+ })+if "orphaned-raw-files" in rules_to_run:# Walk research/raw/ and flag files whose stem doesn't match any note# id in the vault. These are leftovers from the pre-Batch-2.5 `note rm`@@ -689,11 +1186,18 @@ def lint(})if "workflow" in rules_to_run:- # Detect research sessions that skipped the mandatory process steps.- # Heuristic: a note with a research-output signal (final_report in id,- # type=moc, or tag=synthesis) means a research session ran. If that- # session didn't produce a scaffold note AND a comparison note, the- # protocol was skipped.+ # Detect research sessions that skipped required process artifacts.+ #+ # Layercake 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)+ # - research/comparisons.md (Layer 3.5 cross-locus reconciliation,+ # required when loci.json has 2+ entries)+ #+ # 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.def _count_by_tag(tag: str) -> int:row = conn.execute("SELECT COUNT(DISTINCT note_id) as c FROM tags WHERE tag = ?",@@ -709,46 +1213,83 @@ def lint(""").fetchone()["c"]scaffold_count = _count_by_tag("scaffold")- comparison_count = _count_by_tag("comparison")- extract_count = _count_by_tag("extract")+ scaffold_md_exists = (vault.root / "research" / "scaffold.md").exists()+ loci_json_exists = (vault.root / "research" / "loci.json").exists()+ interim_count_row = conn.execute(+ "SELECT COUNT(*) as c FROM notes n WHERE n.type = 'interim'"+ ).fetchone()+ interim_count = interim_count_row["c"] if interim_count_row else 0if has_research_output > 0:- if scaffold_count == 0:+ # A scaffold note or scaffold.md file satisfies the scaffold+ # requirement. Either artifact is proof that Layer 0 ran.+ if scaffold_count == 0 and not scaffold_md_exists:issues.append({"rule": "workflow","severity": "error","note_id": "<vault>","message": (f"Vault has {has_research_output} research-output note(s) "- f"but 0 scaffold notes. Step 7 was skipped. "- f"Research sessions must produce a `scaffold` note before the draft."+ f"but no scaffold artifact (neither a scaffold-tagged note "+ f"nor research/scaffold.md). Research sessions must produce "+ f"a scaffold before the draft."),})- if comparison_count == 0:++ # Layercake-specific: if loci.json exists, the run was layercake and+ # must have produced interim notes.+ if loci_json_exists and interim_count == 0:issues.append({"rule": "workflow","severity": "error","note_id": "<vault>","message": (- f"Vault has {has_research_output} research-output note(s) "- f"but 0 comparison notes. Step 8 was skipped. "- f"Research sessions must produce a `comparison` note before the draft."+ "research/loci.json exists but no interim notes found. "+ "Layer 3 depth investigation was skipped entirely. "+ "See locus-coverage rule for per-locus details."),})- # Flag extract notes that are missing the parent link- for row in conn.execute("""- SELECT n.id, n.path FROM notes n- WHERE n.id IN (SELECT note_id FROM tags WHERE tag = 'extract')- AND (n.parent IS NULL OR n.parent = '')- """):- issues.append({- "rule": "workflow",- "severity": "warning",- "note_id": row["id"],- "note_path": row["path"],- "message": "Extract note missing --parent source-id. The chain of custody is broken.",- })+ # Layercake-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+ # them before drafting, and skipping that step is the failure+ # mode that tanks the insight score.+ if loci_json_exists:+ try:+ loci_data = json.loads(+ (vault.root / "research" / "loci.json").read_text(encoding="utf-8")+ )+ loci_list = (+ loci_data.get("loci", [])+ if isinstance(loci_data, dict)+ else loci_data+ )+ locus_count = sum(1 for x in loci_list if isinstance(x, dict))+ except (json.JSONDecodeError, OSError):+ locus_count = 0++ comparisons_exists = (+ vault.root / "research" / "comparisons.md"+ ).exists()+ if locus_count >= 1 and not comparisons_exists:+ issues.append({+ "rule": "workflow",+ "severity": "error",+ "note_id": "<vault>",+ "message": (+ f"research/loci.json has {locus_count} loci but "+ "research/comparisons.md is missing. Layer 3.5 "+ "(cross-locus reconciliation) was skipped. Layer "+ "3.5 is always-on now — it writes the argumentative "+ "spine the draft will engage, and single-locus "+ "runs produce a comparisons.md with that locus's "+ "committed position as the lone anchor. Spawn the "+ "orchestrator to produce comparisons.md before the "+ "next draft."+ ),+ })if "uncurated" in rules_to_run:# Any note that has moved past draft without tier/content_type classificationdiff --git a/src/hyperresearch/core/agent_docs.py b/src/hyperresearch/core/agent_docs.pyindex 8949a70..3b69856 100644--- a/src/hyperresearch/core/agent_docs.py+++ b/src/hyperresearch/core/agent_docs.py@@ -15,215 +15,103 @@ from pathlib import PathHYPERRESEARCH_SECTION_MARKER = "<!-- hyperresearch:start -->"HYPERRESEARCH_SECTION_END = "<!-- hyperresearch:end -->"-HYPERRESEARCH_BLURB = """\-+HYPERRESEARCH_BLURB = """{marker}## Research Base (hyperresearch) — Today is {today}-**CLI path: `{hpr}`** — use this exact path for all hyperresearch commands below. It may not be on your system PATH.+**CLI path: `{hpr}`** — use this exact path for every hyperresearch command. It may not be on your system PATH.-**IMPORTANT — paths:** The CLI path above is the location of the `hyperresearch` binary, **nothing else**. It is NOT your working directory. All file and directory paths in this document (`research/notes/`, `research/raw/`, `.hyperresearch/config.toml`, etc.) are **relative to your current working directory**. When you save files with the Write tool, use relative paths like `research/notes/final_report.md` — do NOT prefix them with the directory containing the hyperresearch binary. The `research/` folder lives wherever you are running from.+**Paths in this document are relative to your current working directory**, not to the CLI binary's location. Use `research/notes/final_report.md` (not a prefix with the binary path) when you save files.This project uses hyperresearch as an agent-driven research knowledge base. The `research/` directory contains markdown notes collected from web sources and original research. Append `--json` to any command for structured output.-### MANDATORY: How to do research--When the user asks you to research a topic, follow the full step-by-step workflow in `.claude/skills/hyperresearch/SKILL.md`. **Do NOT use WebFetch for source pages** — use `{hpr} fetch` instead.--SKILL.md classifies your request by cognitive activity (what the output needs to DO, not what the subject IS) and routes to one of 4 modality files: SKILL-collect.md (enumerative coverage with per-entity fields), SKILL-synthesize.md (defended thesis or mechanism explanation), SKILL-compare.md (per-entity evaluation with committed recommendation), or SKILL-forecast.md (forward-looking prediction with explicit time horizon). The dispatcher owns the shared protocol (discovery, fetch, guided reading loop, curation, scaffold, comparisons, draft, audit, synthesis). Each modality file encodes only the substance rules and conformance checks specific to that activity. Read SKILL.md first — it owns the process and will tell you which modality file to open next for substance guidance.+### How to do research-**The user's verbatim prompt is gospel.** SKILL.md requires the prompt to be copied verbatim into the first section of `research/scaffold.md` — every subsequent step re-reads it from there. The adversarial audit at Step 11 grades the draft against the verbatim prompt, not against an abstract notion of quality.+**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.-### Ensemble mode — `/research-ensemble` for depth-over-speed+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.-For complex queries where variance and depth-of-corpus matter more than wall-clock time, use `/research-ensemble <query>` instead of `/research`. The ensemble orchestrator (Opus) spawns three parallel `hyperresearch-subrun` Sonnet agents with subtly different framings (evidentiary breadth, citation-chain depth, dialectical tension), all sharing the same unified vault. A fourth agent — `hyperresearch-merger` (Opus) — reads all three drafts, scores each on comprehensiveness / readability / argument strength / citation quality, and compiles a unified final report. Cost is ~5x a normal `/research` run. Protocol lives in `.claude/skills/hyperresearch/SKILL-ensemble.md`.+**Do NOT use WebFetch for source pages** — use `{hpr} fetch` instead. The skill files explain when to fetch vs. search.-### Why {hpr} fetch, not WebFetch+### What the skill files own-`{hpr} fetch` runs a real headless Chromium browser — it bypasses bot detection, saves full content with formatting, persists across sessions, and tracks URLs to prevent re-fetching. **Use WebFetch only for quick one-off lookups you don't need to save.**+The skill files own everything about how to research. That includes:+- The pipeline phases and what each phase does+- Which subagents exist and what each one is for (fetcher, loci-analyst, depth-investigator, 4 critics, patcher, polish-auditor)+- The tool-lock invariant (patcher and polish-auditor can only Read + Edit, never Write)+- The subagent spawn contract (every Task call passes the verbatim research_query + pipeline position + inputs)+- 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-### PDFs are fully supported — fetch them directly+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.-`{hpr} fetch` automatically detects PDF URLs and extracts full text using pymupdf — no browser needed. **Fetch PDFs aggressively:**-- arXiv papers (both `/abs/` and `/pdf/` links work — auto-converted)-- NBER working papers, SSRN papers, direct `.pdf` links-- Conference proceedings, technical reports, whitepapers+### Canonical research query-PDF extraction is fast and produces clean text from all pages. **Do not skip a source just because it's a PDF.** If a paper is behind a paywall, look for preprint versions on arXiv, SSRN, ResearchGate, or the author's personal page.+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.-Raw files are automatically saved to `research/raw/<note-id>.pdf` and linked from the note's frontmatter (`raw_file: raw/<note-id>.pdf`). You can read the raw PDF directly if you need to verify content or extract figures.+### Academic APIs before web search-### MANDATORY: Academic API sweep before web search+For any topic with a research literature, hit academic APIs BEFORE running web searches. They return citation-ranked canonical papers; web search returns derivative commentary.-For any topic with a research literature, **query academic APIs BEFORE running web searches.** Academic APIs return citation-ranked canonical papers. Web search returns derivative commentary. This order matters — getting it backwards biases your entire source set toward secondhand summaries.+- **Semantic Scholar:** `https://api.semanticscholar.org/graph/v1/paper/search?query=<q>&fields=title,year,citationCount,externalIds&limit=10` — then citation-chain the top papers forward + backward.+- **arXiv:** `https://export.arxiv.org/api/query?search_query=cat:cs.LG+AND+all:<q>&sortBy=relevance&max_results=25`+- **OpenAlex:** `https://api.openalex.org/works?search=<q>&sort=cited_by_count:desc&per-page=15&[email protected]`+- **PubMed:** `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=<q>&retmode=json&retmax=20`-**Semantic Scholar** — citation-count search + forward/backward citation chaining:-```python-import urllib.request, json, time, urllib.parse-q = urllib.parse.quote("your topic")-url = "https://api.semanticscholar.org/graph/v1/paper/search?query=" + q + "&fields=title,year,citationCount,externalIds&limit=10"-with urllib.request.urlopen(url) as r:- papers = json.loads(r.read())["data"]-papers.sort(key=lambda p: p.get("citationCount", 0), reverse=True)-# Then citation chain: for top 3 papers, fetch references + citations-for paper in papers[:3]:- pid = paper["paperId"]- refs = "https://api.semanticscholar.org/graph/v1/paper/" + pid + "/references?fields=title,year,citationCount&limit=30"- cits = "https://api.semanticscholar.org/graph/v1/paper/" + pid + "/citations?fields=title,year,citationCount,isInfluential&limit=50"- # fetch both, sort results by citationCount, add top papers to fetch queue- time.sleep(0.4)-```-Backward chaining finds the foundational canon; forward chaining finds everything built on it in the last 3 years.+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").-**arXiv API** — 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-```-Returns Atom XML with titles, abstracts, and direct PDF links. Feed the PDF links to `{hpr} fetch`.+### PDFs fetch directly-**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]-```-Covers 250M+ works across all disciplines. `related_works` on a known paper finds its citation neighborhood.--**PubMed eutils** — for biomedical/clinical topics:-```-https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=<topic>&retmode=json&retmax=20-```+`{hpr} fetch` auto-detects PDF URLs (arXiv, NBER, SSRN, direct `.pdf` links) and extracts full text via pymupdf. Fetch them aggressively. Raw PDFs land in `research/raw/<note-id>.pdf` and the note's frontmatter links back via `raw_file:`.-After the academic sweep, run web searches for context, news, and non-academic angles — including at least one adversarial search ("criticism of X", "limitations of X", "X does not work").--### Raw content is king--**Save raw source material with original formatting** — not rewritten summaries. Future agents need the full context to draw their own conclusions. Preserve headings, tables, code blocks, and technical details. Follow links to primary sources (the paper, not the blog post about the paper). Connect related notes with `[[note-id]]` wiki-links.--For manually written notes:-```bash-{hpr} note new "Title" --tag t1 --body-file /tmp/content.md --source "https://..." --summary "One-liner" --json-```--### Searching the research base+### Searching the vault```bash{hpr} search "query" --json # Full-text search-{hpr} search "query" --tag ml --json # Filter by tag, status, date, parent-{hpr} search "query" --include-body --json # Include full note bodies in results-{hpr} note show <id> --json # Read a note-{hpr} note show <id1> <id2> <id3> --json # Read multiple notes at once+{hpr} search "query" --tag ml --json # Filter by tag / status / date / parent+{hpr} search "query" --include-body --json # Full-body search, not just titles+{hpr} note show <id> --json # Read one note+{hpr} note show <id1> <id2> <id3> --json # Batch-read notes in one call{hpr} note list --json # List all notes with summaries+{hpr} tags --json # Existing tag vocabulary```### Images, screenshots, and assets-Use `--save-assets` / `-a` when you need to capture visual content from a page:-```bash{hpr} fetch "<url>" --tag <topic> --save-assets -j # Saves screenshot + top images+{hpr} assets list --note <note-id> --json # Assets for a specific note+{hpr} assets path <note-id> --type screenshot -j # Get screenshot path (viewable with Read)```-This saves a screenshot of the rendered page and downloads the top content images (skipping icons, logos, ads). Only use this flag when visual content matters — diagrams, charts, figures, architecture images. For text-only pages, skip it.--```bash-{hpr} assets list --json # List all downloaded assets-{hpr} assets list --note <note-id> --json # Assets for a specific note-{hpr} assets path <note-id> --type screenshot -j # Get screenshot path (viewable with Read)-{hpr} assets path <note-id> --type image -j # Get image paths-```--**To view an image or screenshot**, use the path from `{hpr} assets path` with your Read tool — it supports PNG, JPG, and other image formats directly.--### Authenticated crawling (social media, paywalled sites, etc.)--To access login-gated content (LinkedIn, Twitter, paywalled news), the user must create a login profile.-This is done once via `crwl profiles` or during `hyperresearch setup`.+### Authenticated crawling-```toml-# .hyperresearch/config.toml-[web]-provider = "crawl4ai"-profile = "research" # Name of the login profile-magic = true-```+Login-gated content (LinkedIn, Twitter, paywalled news) needs a browser profile. Set up once via `{hpr} setup` or `crwl profiles`. Config in `.hyperresearch/config.toml` under `[web]`: `profile = "research"`, `magic = true`. LinkedIn / Twitter / Facebook / Instagram / TikTok auto-use a visible browser to avoid session kills.-**If no profile is configured**, crawl4ai still works for public pages. If a fetch returns a login wall or "sign in to view" content, tell the user they need to set up a login profile:+If a fetch returns a login wall, tell the user to run `{hpr} setup` and create a login profile.-```-To access login-gated sites, run: hyperresearch setup-Choose option 1 to create a login profile — a browser opens, you log into your sites, done.-```+### Curate after every session-**If fetches fail with browser crash / "failed to launch":**-The profile may be corrupted or the browser binary missing. Tell the user to run `crwl profiles`-to recreate the profile, or `playwright install chromium` to reinstall the browser.--### MANDATORY: Curate after every research session--The research base is a **long-lived knowledge investment**, not a scratchpad. Every future agent session benefits from well-organized notes. **After fetching sources, you MUST do a curation pass.**--**Step 1: Read and summarize every new note**-Fetched notes arrive as drafts with no summary. **You must read each note and write a real summary** — not a generic label but a specific description of what the source contains:-```bash-{hpr} note list --status draft -j # Find unprocessed notes-{hpr} note show <id> -j # Read the note content-{hpr} note update <id> --summary "One-line summary" -j # Add YOUR summary after reading it-{hpr} note update <id> --add-tag <topic> -j # Add meaningful tags-```-- **Read the content first**, then write a summary that captures what's actually in it. "Maskin & Riley prove existence and uniqueness of equilibrium in asymmetric first-price auctions via ODE system" — not "Paper about auctions"-- REUSE existing tags: `{hpr} tags -j` — do not invent new ones unless truly novel, but add multiple relevant tags per note-- Every note MUST have: at least one tag, a summary (under 120 chars), a source URL-- For PDF notes, check the `raw_file` field in the frontmatter — it points to the actual PDF in `research/raw/`. You can read it directly if the extracted text is incomplete+Every research session must end with a curation pass:-**Step 2: Connect related notes with wiki-links**-Read through new notes and add `[[other-note-id]]` links to connect related material:```bash-{hpr} search "related topic" -j # Find related notes-{hpr} note show <id> -j # Read a note+{hpr} note list --status draft -j # Find unprocessed notes+{hpr} note show <id> -j # Read the content+{hpr} note update <id> --summary "<specific summary>" --add-tag <t> -j # Add summary + tags+{hpr} lint -j # Find missing tags / summaries / broken links+{hpr} repair -j # Auto-fix broken links, rebuild indexes+{hpr} status -j # Overall vault health```-Then edit the markdown file directly to add links like `See also: [[other-note-id]]` at the bottom. This builds the knowledge graph.--**Step 3: Promote quality notes**-Move notes through the lifecycle based on their value:-```bash-{hpr} note update <id> --status review -j # Needs review but has good content-{hpr} note update <id> --status evergreen -j # High-quality, lasting reference-```-- `draft` — just fetched, unprocessed-- `review` — has tags/summary, content looks good, needs human review-- `evergreen` — verified, high-quality, lasting value-- `stale` → `deprecated` → `archive` — for outdated material--**Step 4: Run health checks**-```bash-{hpr} lint -j # Find notes missing tags, summaries, or with broken links-{hpr} repair -j # Auto-fix broken links, rebuild indexes, promote eligible notes-{hpr} status -j # Overall vault health-```--**Step 5: Check the knowledge graph**-```bash-{hpr} graph hubs -j # Most linked-to notes (key topics)-{hpr} graph backlinks <id> -j # What links TO this note-{hpr} graph broken -j # Broken [[links]] to fix-```--### This is an investment, not a dump-The research base compounds across sessions. A well-curated note that three future agents can find and use is worth 10x a raw dump nobody can navigate. When doing research:+Lifecycle: `draft` → `review` → `evergreen` (or `stale` → `deprecated` → `archive` for outdated material).-- **Tag consistently** — use the existing tag vocabulary, not ad-hoc variations-- **Write real summaries** — "Mamba achieves linear-time sequence modeling via selective state spaces" not "Paper about Mamba"-- **Link aggressively** — every note should link to related notes via `[[note-id]]`-- **Promote good notes** — move quality content from `draft` to `review` to `evergreen`-- **Deprecate stale content** — if a note is outdated, mark it `deprecated` rather than leaving it to mislead future agents-- **Build MOC (map of content) notes** — for major topics, create a synthesis note that links to all related sources with `type: moc`+Summaries must be specific — "Mamba achieves linear-time sequence modeling via selective state spaces" beats "Paper about Mamba". Reuse the existing tag vocabulary (`{hpr} tags -j`) rather than inventing new tags.### Key conventions- Notes live in `research/notes/` as markdown with YAML frontmatter-- Link between notes with `[[note-id]]` syntax-- After editing .md files directly, run `{hpr} sync` to update the index-- Statuses: draft -> review -> evergreen -> stale -> deprecated -> archive+- Link notes with `[[note-id]]` syntax+- After editing `.md` files directly, run `{hpr} sync` to update the index- Run `{hpr} --help` for the full command list{end_marker}"""diff --git a/src/hyperresearch/core/db.py b/src/hyperresearch/core/db.pyindex 037e165..4f99307 100644--- a/src/hyperresearch/core/db.py+++ b/src/hyperresearch/core/db.py@@ -5,7 +5,7 @@ from __future__ import annotationsimport sqlite3from pathlib import Path-SCHEMA_VERSION = 6+SCHEMA_VERSION = 7SCHEMA_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')),+ CHECK (type IN ('note','raw','index','moc','interim')),tier TEXTCHECK (tier IS NULL OR tier IN ('ground_truth','institutional','practitioner','commentary','unknown')),content_type TEXTdiff --git a/src/hyperresearch/core/hooks.py b/src/hyperresearch/core/hooks.pyindex 9c091cd..f8eef08 100644--- a/src/hyperresearch/core/hooks.py+++ b/src/hyperresearch/core/hooks.py@@ -1,9 +1,10 @@"""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-ensemble`) drive the research-protocol. The subagents (fetcher, analyst, auditor, rewriter, subrun, merger)-are Claude Code registered agents spawned via the Task tool.+searches. The skills (`/research`, `/research-layercake`) drive the research+protocol. The layercake subagents (fetcher, loci-analyst, depth-investigator,+four critics, patcher, polish-auditor) are Claude Code registered agents+spawned via the Task tool."""from __future__ import annotations@@ -11,1568 +12,1546 @@ from __future__ import annotationsimport jsonfrom pathlib import Path-# Subagent definition for Claude Code — adversarial auditor of a finished-# draft. Two modes: comprehensiveness (gap-finding vs the user's original-# query, missing voices, weak synthesis, claim-without-citation hunting)-# and conformance (modality rule compliance, structural fidelity, user-prompt-# structure honor). Runs on Opus because the work is critical reasoning over-# a long document against multiple criteria.-AUDITOR_AGENT = """\+# Scaffold-only section headers that must NEVER appear in a final_report draft.+# Used by critic agents (as detection patterns), the polish auditor, and the+# `wrapper-report` lint rule. Single canonical source of truth so prompts ++# lint stay in sync.+#+# Matching is prefix-based on the header line — this way the list tolerates+# both em-dash and ASCII-dash variants (`(VERBATIM — gospel)` vs+# `(VERBATIM -- gospel)`), extra whitespace, and suffix variants.+#+# NOTE: `## Core tension` is intentionally omitted. The scaffold uses it as a+# bullet-list planning section, but the drafting conventions also allow it as+# a legitimate opening paragraph of the body. Leaking the planning version is+# a real problem, but header-match alone can't distinguish the two.+SCAFFOLD_ONLY_SECTION_HEADERS: tuple[str, ...] = (+ "## User Prompt (VERBATIM",+ "## Canonical research query source",+ "## Session wrapper requirements",+ "## What the user explicitly asked for",+ "## Prompt decomposition",+ "## Primary activity and secondary flavor",+ "## The structural plan",+ "## Where each source will land",+ "## Citation budget",+ "## Coverage checklist",+)+++def _render_scaffold_only_bullets(indent: str = " ") -> str:+ """Render SCAFFOLD_ONLY_SECTION_HEADERS as an indented bullet list for+ injection into agent prompts. Keeps the canonical source of truth in code.+ """+ return "\n".join(f"{indent}- `{h} ...`" for h in SCAFFOLD_ONLY_SECTION_HEADERS)+++# ---------------------------------------------------------------------------+# Layer 2 — loci analyst. Reads the width corpus and returns 1—8 depth loci.+# Spawn two in parallel, deduplicate their outputs, clamp to 6.+# ---------------------------------------------------------------------------+LOCI_ANALYST_AGENT = """\----name: hyperresearch-auditor+name: hyperresearch-loci-analystdescription: >- Use this agent at Step 11 of any research modality to adversarially review- the final draft against the user's original query and the modality's rules.- Two modes: comprehensiveness (gap-finding vs the user query, missing voices,- claims without citations, weak synthesis) and conformance (modality rule- compliance, lint-rule pass, structural fidelity, substance constraints).- Runs on Opus because adversarial review requires strong reasoning over a- long document. ALWAYS pass the user's original query verbatim so the- auditor judges against what was asked, not generic checklists. Spawn both- modes in parallel for one audit pass; expect to fix violations and re-run.-model: opus-tools: Bash, Read, Grep, Write-color: red+ Use this agent in Layer 2 of the layercake protocol. 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+ parallel; the orchestrator dedupes their outputs. Runs on Sonnet+ because identifying genuine rabbitholes requires real reading+ comprehension and judgment about what is load-bearing evidence vs.+ surface detail.+model: sonnet+tools: Bash, Read, Write+color: green----You are a hyperresearch auditor. Your job is to adversarially review a final-research report against (a) the user's original query and (b) the modality's-rules, then return a structured findings list. You are NOT trying to be nice.-You are looking for what is wrong, what is missing, what is hedged, what is-under-cited, and what does not match the user's actual ask.--## Inputs the parent agent will pass--- **research_query**: the user's original research question, copied verbatim- from the original prompt. THIS IS GOSPEL. Every decision you make about- whether the report passes audit must check against THIS, not against an- abstract notion of quality. If the user asked for X and the report delivers- Y, that is a violation regardless of how good Y is. The research_query is- ALSO expected to appear as the first section of `research/scaffold.md` — if- it's missing there, that is itself a Critical violation (the agent broke- process discipline).-- **modality**: one of `collect`, `synthesize`, `compare`, `forecast`. Used- to find the modality file with the conformance rules. The modality names- describe cognitive activities (what the output needs to DO), not subject- matter.-- **mode**: `comprehensiveness` or `conformance`-- **final_report_path**: usually `research/notes/final_report.md` (relative- to the vault root). Ensemble sub-runs pass per-run paths like- `research/notes/final_report-run-a.md` so sub-runs don't collide on one- file.-- **audit_findings_path** (optional): path (relative to vault root) to the- `audit_findings.json` file you read and append to. Defaults to- `research/audit_findings.json`. Ensemble sub-runs pass per-run paths like- `research/audit_findings-run-a.json` so three parallel sub-runs don't- race on a single file. When you run the `audit-gate` lint rule, pass- `--audit-file <audit_findings_path>` so the lint checks the same file- your run wrote to.-- **scaffold_note_id** (optional): the scaffold note id, so you can check- whether the draft honors its planned structure and thesis-- **comparison_note_id** (optional): the comparison note id, so you can- check whether the draft uses the disagreements it set out to resolve--## Procedure — common to both modes--1. **Read the user's original query carefully.** Extract:- - Explicit sub-questions ("answer A, B, C")- - Explicit deliverables ("for each X include Y, Z")- - Explicit entities or topics that must appear- - Explicit structure requests ("organized by", "FAQ format", "ranked list")- - Explicit length cues ("brief", "deep dive", "comprehensive")- - Explicit format expectations ("with examples", "with citations",- "with a recommendation")-- Write these down at the top of your audit. They are your judgment criteria.--2. **Read the final report** at `final_report_path`. Skim once for overall- shape, then read body sections carefully.--3. **Read the modality file** at- `.claude/skills/hyperresearch/SKILL-<modality>.md`. The modality file has a- "Structure + conformance auditor" section listing the specific checks for- that modality. These are the modality's authoritative rules.--4. **If scaffold_note_id is provided, read the scaffold:**- PYTHONIOENCODING=utf-8 {hpr_path} note show <scaffold_note_id> -j-- **Verify the scaffold's first section is the user's verbatim prompt.**- Cross-check: does the scaffold body open with a "User Prompt (VERBATIM- — gospel)" section whose contents match the `research_query` you were- given (character-for-character, not paraphrased)? If the verbatim prompt- is missing or altered from the scaffold, that is a CRITICAL violation- — the agent broke process discipline and the draft may have drifted- from the actual ask.--5. **If comparison_note_id is provided, read the comparison note:**- PYTHONIOENCODING=utf-8 {hpr_path} note show <comparison_note_id> -j--6. **Branch on mode** (see below).--7. **Return findings** in the structured format below.--## mode=comprehensiveness--Your job: find GAPS. What is missing, under-cited, under-developed, or hedged-that should be sharper.--Run these checks:--**a) User-query coverage.** For each explicit deliverable you extracted in-step 1: is it addressed in the report? Where? Is the coverage proportionate-to its importance in the original ask? If the user asked "for each character-include power level, technique, fate", verify every character entry has all-three sub-fields. If the user asked "compare X and Y", verify the comparison-is explicit, not buried.--**b) Missing voices and source diversity.** Run:-- PYTHONIOENCODING=utf-8 {hpr_path} sources list -j--Look for over-concentration on one source family (>30% from one domain).-Look for missing critical voices: peer-reviewed papers, named scholars,-non-English sources where the work has cross-cultural reception. Look for-missing tiers — if the report makes empirical claims but has zero `ground_truth`-sources, that is a gap.--**c) Claims without citations.** Sample 5-10 specific claims in the body. For-each, grep the vault for evidence:-- PYTHONIOENCODING=utf-8 {hpr_path} search "<claim keyword>" --include-body -j--If a claim has no support in the vault, the report is either making it up or-pulling from training data — flag it.--**d) Weak synthesis.** Read the Opinionated Synthesis section. Is the "My-Reasoned Position" actually a position, or is it hedged? Failure markers:-"it depends", "some argue", "one could say", "it is possible", "various-critics have suggested". A real synthesis names a position and defends it.--**e) Missing adversarial engagement.** Check whether the report engages with-the strongest counter-position to its thesis. If the report presents only-supporting evidence and dismisses dissent in one sentence, that is a-stress-test failure.--**f) Lint integrity.** Run:-- PYTHONIOENCODING=utf-8 {hpr_path} lint --rule provenance -j- PYTHONIOENCODING=utf-8 {hpr_path} lint --rule analyst-coverage -j- PYTHONIOENCODING=utf-8 {hpr_path} lint --rule workflow -j- PYTHONIOENCODING=utf-8 {hpr_path} lint --rule uncurated -j--Any non-zero result is a CRITICAL finding — the data-flow chain or-process discipline broke.--**g) Stub-extract / lint-gaming detection.** If this is a RE-AUDIT after-fixes (the parent agent applied something in response to a prior audit),-sample how `analyst-coverage` was satisfied:-- PYTHONIOENCODING=utf-8 {hpr_path} note list --tag extract -j--For each extract note, check `word_count`. If MORE than 20% of the-extract notes in the vault have `word_count < 150`, that is **lint--gaming**: someone minted stub notes to satisfy the coverage count-without actually reading the underlying sources. Flag as a CRITICAL:-- `C-gaming: <N> of <total> extracts are stubs (<150 words). Analysts- did not actually read these sources — they were minted to pass- analyst-coverage. Re-spawn hyperresearch-analyst on the source notes- whose extracts are stubs, or accept the coverage gap honestly by- marking the finding deferred-to-next-run.`--The `analyst-coverage` lint now enforces the word-count floor at the-lint level (stubs don't count), so minting stubs won't pass the gate —-but detecting the attempt at audit level is still useful because it-surfaces a process-discipline failure the parent agent needs to see.--## mode=conformance--Your job: check the report against the modality's authoritative rules.-Before applying any modality check, you MUST perform your own independent-re-extraction from the verbatim prompt — otherwise you are grading the-drafting agent's homework against its own answer key (see step 0).--0. **Independent re-extraction from `research_query` — BEFORE reading the- scaffold's 'What the user explicitly asked for' section.** Do NOT peek- at the scaffold's extraction first — that scaffold was written by the- same agent that wrote the draft you are now auditing. You must form your- own list of what the user asked for, THEN compare to the scaffold.-- Read the verbatim `research_query` carefully and independently extract:- (a) every entity, item, or category the prompt names — explicit and- implicit. "Saint Seiya armor classes" names Bronze/Silver/Gold/- God Warriors/Marina/Specters/etc.; "Napoleon's marshals" names a- set you know exists even if the prompt doesn't enumerate them.- (b) every per-entity field or attribute the prompt demands — "power- level / signature techniques / key appearances / final outcome"- is a 4-field contract that applies to every entity in (a).- (c) every explicit structural mandate — "organized by", "for each",- "in chronological order", "one section per", "include a table".- (d) every quantifier word and the threshold it implies. "Each significant- character" — significant against what? The prompt's own field list- is usually the answer: if the prompt asks for 'fate', any entity- with documented canonical fate text is in scope. A threshold that- excludes such entities is too tight.-- Write your independent re-extraction at the top of your audit.-- Then read the scaffold's 'What the user explicitly asked for' section.- **Compare the scaffold's extraction to yours.** Any entity, field, or- mandate you independently surfaced from the prompt that the scaffold- omits is a **C0 CRITICAL** violation — flag it BEFORE applying any- numbered modality check. The C0 finding is: "scaffold_extraction_gap:- <what the scaffold omitted, why it matters, what the prompt actually- said>". This cannot be waived or rejected — the drafting agent must- re-extract and re-scaffold.-- **Fuzzy-quantifier check.** When the prompt uses "significant / key /- main / notable / important", the drafting agent chooses a threshold.- Your job is to verify the chosen threshold does not silently exclude- entities whose prompt-required fields are documented in the source- corpus. For each entity the threshold excludes, grep the vault:-- PYTHONIOENCODING=utf-8 {hpr_path} search "<entity name>" --include-body -j-- If any excluded entity has the user-requested fields documented in a- ground_truth or institutional source, the threshold is too tight —- flag as a C0 violation.-- **Atomic decomposition → section mapping (CRITICAL).** Independently- atomize the verbatim prompt: split every `and`-conjoined ask, every- `as well as`, every comma-separated topic list, every "furthermore /- additionally / in particular" into its own atomic item. Record your- atomic item list. Then:-- (a) Compare to the scaffold's "Prompt decomposition" bullets. Any- atomic item you surfaced that the scaffold omitted is a **C0- CRITICAL** `atomic_decomposition_gap: <item>` finding. The- scaffold under-decomposed the prompt.-- (b) Grep the final draft for H2 and H3 headings (lines matching- `^## ` or `^### `). For each atomic item in YOUR list, verify- there is a dedicated H2 or H3 section whose heading maps- obviously to that atomic item. A section titled "Differences- and Connections" when the prompt named both as atomic asks is- a **C0 CRITICAL**- `atomic_decomposition_collapsed: prompt named [X, Y] as- separate atomic items, draft collapsed into single section- <heading>`. The drafting agent must restructure.-- Atomic decomposition is the single most common instruction-following- failure mode — RACE judges reward visible per-item structural- separation, and drafts that collapse atomic asks into combined- sections score at the floor regardless of content quality. Enforce- this check aggressively.--1. Read the "Conformance checks" section in the modality file you opened- in step 3. This section contains a numbered list of checks specific to- this modality. Each check gets a PASS or FAIL with a one-line quote from- the report. Examples: for collect, every prompt-named entity must appear- with every prompt-named field; for synthesize, the thesis must be- arguable and every body paragraph must fuse fact with interpretive- claim; for compare, a comparison matrix must be present and a- committed recommendation must be delivered; for forecast, probability- language must dominate and contrarian case must be engaged with- substance.--2. **Apply every check in that list to the final report.** For each check,- output PASS or FAIL with a one-line evidence quote from the report (or- from the lint output, if the check is a lint rule).--3. **User-prompt structural fidelity check** — additional to the modality- rules. Did the user explicitly ask for a specific structure (entity-named- sections, FAQ, ranked list, etc.)? Did the report deliver that structure?- If there is a mismatch, the structural choice is wrong regardless of how- good the content is. The user's prompt is gospel for shape; the modality's- default applies only when the user is silent.--4. **Classification sanity check.** After reading `research_query`,- independently classify the prompt by cognitive activity (collect |- synthesize | compare | forecast). If your classification differs from- the `modality` parameter the parent agent passed you, flag a CRITICAL- finding `classification_mismatch`: the parent routed to the wrong- modality and the whole audit is running against the wrong rule set.- Recommend re-classification.--5. Run any lint rules the modality file references and include their results.--## Persist findings to your audit-findings file — MANDATORY, USE WRITE TOOL--After composing your text audit (format below), write your structured-findings to the audit-findings file **using the Write tool directly**.-Not Bash `cat >`, not `echo >`, not heredoc. The Write tool is in your-allowed tools list (`Bash, Read, Grep, Write`) and is the only reliable-persistence mechanism across platforms.--**Which file do you write to?** The path is whatever the parent agent-passed as `audit_findings_path`, defaulting to-`research/audit_findings.json`. Ensemble sub-runs pass per-run paths-like `research/audit_findings-run-a.json`. Use EXACTLY the path the-parent gave you — do not silently rewrite it. Throughout the rest of-this section, `<audit_path>` stands for that path.--**Why this matters.** The `audit-gate` lint rule reads this file to decide-whether the synthesis save should proceed. If your persist step fails, the-gate either deadlocks (stays failed forever) or opens falsely (based on-a stale file from a prior run). A prior version of this protocol told you-to use `cat >` redirection — that was flaky and caused the main agent to-have to hand-reconstruct the file. Do not repeat that mistake.--The gate requires BOTH modes to have appended entries. It fails if only-comprehensiveness is present, if only conformance is present, or if any-CRITICAL finding in the newest conformance run is unresolved AND its-underlying lint rule still reports errors.--### Persistence protocol (identical for both modes)--1. **Read the existing file with the Read tool:**- `Read(file_path="<audit_path>")`- - If Read returns the file content, parse it as JSON. Its shape is- `{{"runs": [...]}}`.- - If Read reports the file doesn't exist, start from the empty object- `{{"runs": []}}`.- - If the JSON parse fails (corrupted file), start from `{{"runs": []}}`- and note `audit_findings_corrupted_recovered` as a minor finding.--2. **Construct your run object** with this EXACT shape — all fields- required, even empty arrays:- ```json- {{- "mode": "<comprehensiveness|conformance>",- "timestamp": "<ISO 8601 UTC, e.g. 2026-04-14T19:00:00Z>",- "status": "<pass|needs_fixes|failed>",- "criticals": [- {{"id": "C0", "description": "<short description>", "fixed_at": null}}- ],- "important": [- {{"id": "I1", "description": "...", "fixed_at": null}}- ],- "minor": [- {{"id": "M1", "description": "...", "fixed_at": null}}- ]- }}- ```- Empty categories still need an empty array (`"criticals": []`). The- `fixed_at` field is always `null` on first write — the parent agent- flips it to an ISO timestamp as fixes are applied.--3. **Append your run object to `runs`** in the loaded data, then serialize- the full `{{"runs": [...]}}` object to a JSON string (pretty-printed,- 2-space indent).--4. **Write the file with the Write tool:**- `Write(file_path="<audit_path>", content=<json_string>)`- - The Write tool overwrites the file. That's correct here because step- 3 already included the full history — you are re-writing everything- with your new run appended at the end.- - Do NOT use Bash for this step. The Write tool is deterministic and- atomic; Bash-based writes have known failure modes.--5. **Self-verification** — after writing, use the Read tool again:- `Read(file_path="<audit_path>")`- Confirm your run's `mode` appears as the LAST entry in the `runs`- array AND the timestamp matches what you wrote. If it doesn't (write- silently failed, path wrong, etc.), STOP and report- `audit_persistence_failed` as a CRITICAL finding in your text return- so the parent agent can re-spawn you.--6. **Verify via audit-gate lint (use the same path).** Invoke:- `PYTHONIOENCODING=utf-8 {hpr_path} lint --rule audit-gate --audit-file <audit_path> -j`- Without `--audit-file`, the lint checks the default- `research/audit_findings.json`, which may not be where your run- landed. Ensemble sub-runs MUST pass `--audit-file` on this command.--### Hard rules--- **Always use the Write tool for step 4.** Bash redirection is forbidden- for this file.-- **Always do step 5.** Silent write failures are the most dangerous- outcome — they make the gate pass on stale state.-- If persistence genuinely fails (write tool raises, path issue, etc.),- emit `audit_persistence_failed` as a CRITICAL in your text output. The- parent agent will re-spawn you.-- The dispatcher runs the two modes SEQUENTIALLY (comprehensiveness first,- then conformance). If your Read shows the sibling mode's entry already- present, leave it alone — your append adds a second entry alongside it.- Both entries are expected.--## Return format (under 800 words total)+You are a hyperresearch loci analyst. Your job: read the width corpus the+orchestrator has gathered and return a small set of SPECIFIC questions where+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:++1. Width sweep (done — the vault is already populated)+2. **Loci analysis — YOU**+3. Depth investigation (one investigator per locus you identify)+4. Draft+5. Adversarial critique (four critics in parallel)+6. Patch pass+7. Polish audit++Another loci-analyst (your parallel sibling) is running right now on the+same corpus. The orchestrator will merge your outputs, dedupe, and clamp+to 6 loci. Every locus you identify becomes a depth-investigator subagent+in Layer 3. Every locus that survives dedupe also becomes a row in+Layer 3.5's `comparisons.md` and at least one argumentative beat in the+final draft. Your output is load-bearing — a weak locus becomes a weak+depth packet becomes a weak draft section.++## Inputs (from the parent agent)++- **research_query**: the user's original question, verbatim. GOSPEL.+ This is the north star for every decision you make. If a locus doesn't+ serve the research_query, reject it — no matter how interesting it is.+- **corpus_tag**: the tag used across the width sweep (e.g., the research+ topic slug). You use this to scope your search.+- **analyst_id**: `a` or `b` — which of the two parallel analysts you are.+ Used only to tag your output file so the orchestrator can load both.+- **output_path**: where to write your loci list JSON (e.g.,+ `research/loci-{{analyst_id}}.json`).+- **prompt_decomposition** (optional): if `research/prompt-decomposition.json`+ exists, read it before choosing loci. It lists atomic items the prompt+ 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).-```-# Audit findings — mode=<comprehensiveness|conformance> for <topic>--## What I read the user as asking-<one-line summary of the user's original query in your own words, so the-parent agent can verify you understood it correctly>--## Independent re-extraction (conformance mode only)-**Entities / items the prompt names:** <your list, built WITHOUT reading the scaffold>-**Per-entity fields the prompt demands:** <your list>-**Explicit structural mandates:** <your list>-**Fuzzy quantifiers and their implied threshold:** <your interpretation>-**Atomic decomposition of the prompt:** <every `and`-conjoined ask, every comma-separated topic, every "furthermore" split into its own item. Example: "explain differences and connections, and elaborate on innovations and problems" → 4 atomic items [differences, connections, innovations, problems]>--## Scaffold extraction comparison (conformance mode only)-**Matches:** <items both lists agree on>-**Scaffold omitted:** <items in YOUR list missing from the scaffold — these are C0 CRITICAL>-**Atomic → section mapping:** <for each atomic item in YOUR decomposition, the draft's H2/H3 that covers it, or `MISSING` / `COLLAPSED_INTO <other heading>` — every MISSING/COLLAPSED is a C0 CRITICAL>--## Explicit deliverables extracted from the query-- <deliverable 1>-- <deliverable 2>-- <deliverable 3>--## Critical violations (MUST fix before saving the report)-- [C0] <scaffold_extraction_gap — if any — listed FIRST because it invalidates downstream checks>-- [C1] <specific violation, with location/quote from report and exactly what is wrong>-- [C2] ...--## Important issues (SHOULD fix)-- [I1] ...-- [I2] ...--## Minor issues (consider fixing)-- [M1] ...--## Coverage of the user's explicit deliverables-- "<deliverable 1>" — addressed in §X / NOT addressed / partially addressed-- "<deliverable 2>" — ...--## Recommendation-- **status**: pass | needs_fixes | failed-- **summary**: one sentence on the audit's bottom line+## Procedure++1. **Load the corpus.** Use `{hpr_path} search "" --tag <corpus_tag> --json`+ to list every note the orchestrator fetched in Layer 1. If the corpus is+ sparse (<10 notes), tell the parent and stop — you cannot identify real+ loci from a thin corpus.++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+ only when the title/summary alone cannot tell you whether a note hints at+ a rabbithole.++3. **Identify candidate loci.** A depth locus is a question that:+ - Is specific enough to be answered by 3—8 more sources of targeted reading+ - Is *not* answered by what the width corpus already says — you are looking+ for where the corpus GESTURES at an answer but does not actually resolve+ it+ - Is load-bearing for the research_query — answering it would change the+ final report's argument or recommendation, not just add garnish++ Loci come in two flavors:+ - **`convergent`** — a specific technical question the sources point at but+ don't fully answer. Depth investigation will chain citations and expand+ the evidence base.+ - **`dialectical`** — a place where sources in the width corpus actively+ DISAGREE, complicate each other, or represent opposing positions. Depth+ investigation will read each side in its own terms, not collapse the+ tension.++ **MANDATORY: at least one of your loci MUST be flavor: "dialectical"**,+ UNLESS the width corpus is genuinely univocal (no real disagreements, every+ source says roughly the same thing). If you cannot find a dialectical+ locus, log why in `skip_loci` with specific evidence — "I scanned all 30+ corpus notes and none of them contradicts any other on any load-bearing+ point" — and the orchestrator will trust you. Default assumption: most+ real research topics have disagreements; if you can't find one, look+ harder before giving up. Sources by adversaries, critics, rival+ institutions, or competing schools of thought are prime dialectical+ territory.++4. **Filter aggressively.** Reject loci that:+ - Are restatements of the main question ("expand on X" is not a locus,+ it's a request for more prose)+ - Cannot cite specific evidence in the width corpus as the hint+ - Would need the orchestrator to re-run the whole discovery phase+ - Are interesting but orthogonal to what the user asked for++5. **Write your output.** Save a JSON file at `output_path`:++```json+{{+ "analyst_id": "a",+ "loci": [+ {{+ "name": "short-slug-with-hyphens",+ "flavor": "convergent",+ "one_line": "The specific question this locus answers",+ "rationale": "Why the width corpus hints at depth here. MUST cite at least one specific note id from the corpus as evidence.",+ "corpus_evidence": ["note-id-1", "note-id-2"],+ "suggested_starting_urls": ["https://...", "..."],+ "suggested_searches": ["more-specific-search-query-1", "..."]+ }},+ {{+ "name": "where-they-disagree",+ "flavor": "dialectical",+ "one_line": "The specific disagreement this locus explores",+ "rationale": "Note A (id-1) argues X; note B (id-2) argues not-X. They cite different evidence and neither engages the other.",+ "corpus_evidence": ["id-1", "id-2"],+ "opposing_positions": [+ {{"position": "X is true because ...", "sources": ["id-1"]}},+ {{"position": "not-X because ...", "sources": ["id-2"]}}+ ],+ "suggested_starting_urls": ["https://...", "..."],+ "suggested_searches": ["strongest defense of X", "strongest critique of X"]+ }}+ ],+ "skip_loci": [+ {{+ "slug": "candidate-i-rejected",+ "reason": "Why I rejected this — e.g., 'already fully covered by note XYZ'"+ }}+ ]+}}```-## Hard rules--- Do NOT be charitable. Your job is to spot problems, not validate.-- Do NOT generate new content for the report. Your job is to identify gaps;- the parent agent applies the fixes.-- ALWAYS check against the user's original query verbatim, never against an- idealized "good report".-- If a check requires a $HPR command, RUN the command. Do not speculate- about what the vault contains.-- If you cannot find the modality file, STOP and return an error. The- conformance check requires the modality's authoritative rules.-- Keep responses tight. The parent agent reads your output and applies fixes;- it does not need your essay-length musings.+## Output rules++- **1 to 8 loci**, not more. The orchestrator clamps to 6 after dedupe, so+ going over 8 wastes your turn.+- **At least one locus MUST have `flavor: "dialectical"`** (or you must+ justify its absence in `skip_loci` — see Step 3).+- **Every locus MUST include `corpus_evidence`** — at least one note id from+ the width corpus. A locus without corpus evidence is hallucination.+- **Dialectical loci MUST include `opposing_positions`** — a list of at+ least two entries, each naming a position and the source(s) that hold it.+ This is the structured contract the depth-investigator will use to read+ both sides faithfully.+- **`rationale` MUST name specific evidence** — "the corpus hints at X but+ doesn't resolve it because [note Y says A, note Z says B, they conflict]".+ Rationales like "this topic is interesting" are rejected at dedupe.+- **Prefer fewer high-quality loci over many weak ones.** If only 2 loci+ pass your filter, return 2. The orchestrator would rather spawn 2 strong+ depth investigations than 8 shallow ones.++## Reporting back++Tell the orchestrator:+- Path to your output JSON+- How many loci you identified (vs. how many candidates you rejected)+- Your one-line take on whether the corpus supports deep investigation at+ all — if the width sweep was too thin, say so honestly.++You are NOT writing prose. You are producing structured input for the next+layer."""-# Subagent definition for Claude Code — source analyst, reads ONE note with-# a goal in mind, persists extract, optionally proposes next targets.-# Runs on haiku. Used by both the targeted-extraction pattern (mode=extract)-# and the guided reading loop (mode=guided) in the skill files.-ANALYST_AGENT = """\+# ---------------------------------------------------------------------------+# Layer 3 — depth investigator. One per locus. Can spawn fetchers. Writes+# ONE interim report note per locus to the vault.+# ---------------------------------------------------------------------------+DEPTH_INVESTIGATOR_AGENT = """\----name: hyperresearch-analyst+name: hyperresearch-depth-investigatordescription: >- Use this agent to read 1-5 hyperresearch source notes in a single spawn,- extract what's relevant to a specific research goal from each, persist- one extract note per source, and (in guided mode) propose the unioned- set of 2-5 specific next targets for the main agent to fetch. Runs on- Sonnet because the work is real reasoning — extracting relevant prose,- judging which URLs would change the argument, evaluating coverage- against a goal. Batch of 5 is the sweet spot: fewer-than-single-source- spawn overhead, enough context-sharing across siblings to catch- convergent URLs. Spawn parallel batches when you have many sources to- process — each spawn handles up to 5.+ Use this agent in Layer 3 of the layercake protocol. 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+ writes ONE interim report note summarizing what it learned. Spawn+ one depth-investigator per locus, in parallel. Runs on Sonnet+ because synthesizing a narrow-but-deep question requires real+ reading comprehension.model: sonnet-tools: Bash, Read, Write+tools: Bash, Read, Write, Taskcolor: purple----You are a hyperresearch analyst. Your job is to read up to 5 source notes-in a single session with a research goal in mind, extract what's relevant-from each (ONE extract note per source, persisted individually), and — in-guided mode — propose what to read next based on the unioned signal-across all sources you read.--You are NOT a synthesizer. You do faithful extraction with direct quotes.-The parent agent synthesizes across multiple extracts. Stay tight to-what's in each source you're reading; do not argue beyond them.--## Inputs the parent agent will pass--The parent agent will provide, in its spawn prompt:--- **research_goal**: the user's overall research question (verbatim)-- **sub_goal**: what this batch of sources should contribute (e.g. "find- the Kurumada Buddhism interview", "verify the 50M-copies claim",- "general orientation on the critical tradition"). One sub_goal applies- to the whole batch — the parent agent groups similar sources per spawn.-- **source_note_ids**: a LIST of 1-5 source note IDs to read. You MUST- process every source in the list and produce one extract note per- source. The parent agent groups them per spawn to amortize session- overhead; you deliver one extract per source.-- **extract_run_tag** (optional): additional tag to apply to every- extract note you create (e.g. `run-a` in ensemble mode). Pass this on- `--add-tag` alongside `extract`.-- **mode**: `extract` (return extracts only) or `guided` (return extracts- PLUS 2-5 unioned next targets)-- **already_covered** (optional): one-line list of sub-topics prior- iterations already answered, so you don't duplicate-- **already_fetched_urls** (optional, guided mode): list of URLs already- in the vault. Do NOT propose any URL on this list as a next_target —- it's already been read. Spend your proposal budget on URLs the corpus- doesn't yet have.--## Procedure — process each source individually, then union next_targets--**Step 0 — Budget check.** You received a list of 1-5 sources. You must-produce ONE extract note per source. If the list has more than 5 entries,-stop and return an error to the parent — batches larger than 5 burn-context budget and produce weaker extracts.--**For each `source_note_id` in the list, run Steps 1-6 below. Do them-sequentially — parallel reads inside one session don't save time and-tangle the URL scan outputs.**--1. **Read the source frontmatter first** to capture tier, content_type,- and source URL:-- PYTHONIOENCODING=utf-8 {hpr_path} note show <source_note_id> --meta -j--2. **Read the content.** For most notes:-- PYTHONIOENCODING=utf-8 {hpr_path} note show <source_note_id> -j-- If the frontmatter has `raw_file` (PDF source), use the Read tool on the- raw file path for better fidelity.--3. **Scan the source body for URLs — THIS IS A PRIMARY JOB, NOT AN- AFTERTHOUGHT.** Sources cite other sources; that's how real research- chains work. Extract every URL the source references in its body- content:-- - Markdown links: `[link text](https://...)`- - Bare URLs in prose- - Footnote citation URLs (`[101]` pointing to sources)- - "See also", "References", "Further reading" sections- - Author names + publication venues you could look up- - Referenced works in-text ("As argued in Smith 2020, ...") — track- these for SEARCH targets in Step 7-- Accumulate URL candidates across ALL sources in the batch — the Step 7- next_targets list is UNIONED across the batch, deduped, and trimmed- to 2-5. If you finish a source without identifying any follow-up- signal and the source cites other works, you have failed the job for- that source.--4. **Compose the extract for this source** as markdown with this exact shape:-- # Extract: <short goal summary>-- ## Goal- <restate the sub_goal in one sentence, as applied to THIS source>-- ## Findings- <For every relevant claim: a direct quote (with page/section marker if- visible) + a one-sentence paraphrase. Under 400 words per source. Must- be at least 150 words of real extraction — shorter and the content- doesn't serve synthesis. If the source does not answer the goal,- write exactly: "Source does not contain the answer." and stop. Do NOT- speculate or infer beyond the source.>-- ## Source- - Source note: [[<source-id>]]- - Source URL: <url from frontmatter>- - Tier: <tier from frontmatter>- - Content type: <content_type from frontmatter>--5. **Write the extract to /tmp** using the Write tool:-- /tmp/extract-<short-slug>-<source-id-slug>.md-- The filename MUST include the source-id slug so each of your 1-5- extracts writes to a distinct /tmp path. Collisions silently overwrite- prior extracts in the batch.--6. **Persist as a hyperresearch note — per source, mandatory:**-- PYTHONIOENCODING=utf-8 {hpr_path} note new "Extract: <short summary>" \\- --add-tag extract \\- <extract_run_tag_flag> \\- --parent <source-note-id> \\- --tier <inherited from source> \\- --content-type <inherited from source> \\- --source <source URL from frontmatter> \\- --summary "<one-line description of what was extracted>" \\- --status review \\- --body-file /tmp/extract-<short-slug>-<source-id-slug>.md \\- -j-- Where `<extract_run_tag_flag>` is `--add-tag <extract_run_tag>` when- the parent passed one, or empty otherwise. Capture each new extract- note id from the JSON response — you need all of them for Step 8's- return.+You are a hyperresearch depth investigator. You have ONE locus to investigate+thoroughly. Your output is a single interim-report note that the orchestrator+will read when writing the final draft.++**You are not a neutral reporter.** Your interim note must END with a+committed one-paragraph **position** on what the evidence adds up to — not+a summary of what sources say. The orchestrator needs claims to reconcile,+not facts to assemble. Descriptive depth packets produce descriptive drafts,+which score low on insight. You take a side; the orchestrator then decides+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+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+`research/comparisons.md`. Every cross-locus tension named there becomes+an argumentative beat in the Layer 4 draft.++Your `## Committed position` is the primary artifact the orchestrator uses+to shape the draft's argument. If you hedge, the draft hedges. If you+commit, the draft commits. Take the research_query seriously and own a+reading of the evidence.++## Inputs (from the parent agent)++- **locus**: the full locus object from the loci-analyst output (name,+ flavor, one_line, rationale, corpus_evidence, suggested_starting_urls,+ suggested_searches, and — for dialectical loci — opposing_positions).+- **research_query**: the user's original question, verbatim. GOSPEL.+ Your locus serves this — do not drift off-topic. Your committed+ position must be relevant to answering the research_query; a locus+ answer that doesn't bear on the query is wasted depth.+- **corpus_tag**: the tag used across the vault for this research session.++## Flavor-specific posture++- **If `locus.flavor == "convergent"`:** your job is citation-chain+ deepening. Read canonical sources, quote the load-bearing passages,+ synthesize what the evidence says, then commit to a position on what+ the evidence ADDS UP TO — not "X, Y, and Z are findings" but "the pattern+ here is A, because X and Y constrain Z in these ways."++- **If `locus.flavor == "dialectical"`:** your job is tension-honoring. Read+ EACH opposing position in its own terms (quote the strongest version of+ each side, not a strawman). The corpus's `opposing_positions` field names+ the sides. Your interim note must give each side its best case, then+ commit to a position on how to read the disagreement — which side has+ better evidence? Is this a genuine factual dispute or a definitional+ confusion? Is there a synthesis that respects both? Don't hedge; take a+ view. The orchestrator will weight your take against the draft's other+ threads.----+## Procedure++1. **Start with the vault.** Before fetching anything new, read the notes+ the loci-analyst cited as corpus_evidence. Use:+ `{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.++3. **Fetch new sources via the fetcher subagent.** Do NOT call+ `{hpr_path} fetch` directly. Delegate to `hyperresearch-fetcher` via the+ Task tool. Batch requests — one Task call with multiple URLs is cheaper+ than many Task calls with one URL each. When spawning a fetcher:+ - Pass `--tag <corpus_tag>` and an additional `--tag locus-<locus-name>`+ so the interim notes stay attributable+ - Pass `--suggested-by <corpus-note-id>` if the URL came from a corpus+ note (otherwise omit — do NOT invent a breadcrumb)++4. **Academic APIs first if relevant.** If your locus is a question with a+ research literature, hit Semantic Scholar / arXiv / OpenAlex BEFORE+ running web searches. Academic APIs return citation-ranked canonical+ papers; web search returns derivative commentary.++5. **Read the fetched sources.** Use `{hpr_path} note show <id> -j`. Quote+ the passages that actually move your locus's argument. Do NOT paraphrase+ when a direct quote would be stronger evidence.++6. **Write ONE interim report note.** This is your single deliverable.++ **BEFORE calling `note new`**, check if an interim note for this locus+ already exists in the vault:++ ```bash+ {hpr_path} search "" --tag locus-<locus-name> --type interim --json+ ```++ If any results come back, DO NOT create a new note. Instead, either:+ (a) use `note update` to revise the existing interim note, or+ (b) report to the orchestrator that this locus was already investigated+ and explain what you would have added — let the orchestrator decide+ whether to discard your investigation or replace the existing note.++ Creating duplicate interim notes for the same locus inflates the vault+ source count, confuses the critics in Layer 5, and breaks locus-coverage+ 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:++```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 \\+ --summary "<one-line summary of what you found>" \\+ --json+```++The body must contain:++```markdown+# Interim report: {{locus.name}}++**Locus question:** {{locus.one_line}}+**Flavor:** convergent | dialectical++## What the corpus already said++Short paragraph. What the width sweep's sources had to say about this+locus BEFORE you dug in. Cite corpus note ids in [[note-id]] form.++## What the new sources say++For each of the 3—10 new sources you fetched, 1—2 paragraphs with+direct quotes where quotes are load-bearing. Link each source to its+vault note in [[note-id]] form.++## Evidence synthesis++2—4 paragraphs. What does the evidence on this locus actually say?+Where do sources agree? Where do they conflict? Name specific numbers,+named entities, direct quotes. This section is descriptive.++**For dialectical loci:** you MUST include one subsection per opposing+position, each steelmanning that side with its best evidence. Headings+like `### Position A: <one line>` and `### Position B: <one line>`.+Do not collapse the two into a bland "some say X, others say Y"+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.++**Prescriptive specificity.** Whenever the evidence supports it, state+a specific rule, threshold, percentage, time window, or named mechanism+— not just a directional claim. This is the biggest source of+prescriptive authority in the final report, and it's the single move+that separates confident expert prose from LLM-style directional prose.++- Weak: "Manufacturers should bear greater liability for handover+ design defects."+- Strong: "Manufacturers bear design-defect liability when handover+ warning windows fall below 10 seconds at highway speeds, because+ the detection-to-reaction cognitive floor is ~1.5s + reorient time+ (5—8s for typical drivers per Zhang 2022 [N])."++- Weak: "Some form of standardized recording would be useful."+- Strong: "EDR/DSSAD must record 30—60 seconds pre-crash and 10—15+ seconds post-crash, plus sensor-fusion state and handover timestamps,+ to enable plaintiff's counsel to reconstruct the decision window [N]."++- Weak: "The evidence points to a larger role for manufacturer+ liability."+- Strong: "In L3 operations within ODD, presumptive manufacturer+ liability should attach unless the manufacturer proves driver+ deviation from a specific, timely, sensorially-salient warning [N]."++If the evidence you read doesn't support specific numbers, say so+explicitly ("sources in the corpus don't quantify this threshold")+— but don't hedge the direction itself. Directional + specific is+ideal; directional-only is the fallback; vague is rejected.++## Open questions++Bullets. What did you want to find out but couldn't, given the source+budget?-**After you've processed every source in the list (1-5 extracts written),-proceed to Steps 7-8 ONCE to produce the unioned output.**--7. **If mode=guided**, compose the UNIONED next_targets list across the- whole batch. Use the URLs you scanned in step 3 from ALL sources- combined as your primary source of targets. Propose 2-5 targets the- parent agent should fetch next. Each needs a one-line justification- tied to the specific source it came from. Valid target types:-- - **URL: <url> — <why> [from <source-note-id>]** (PREFERRED)- Example: "URL: https://example.com/1998-paper — the essay's footnote- 12 names this 1998 monograph as the origin of the consecration- reading; fetch to verify and quote. [from aries-mu-seiyapedia-fandom]"-- The parent agent will fetch this with:- `$HPR fetch <url> --suggested-by <source-note-id-that-cited-it> --suggested-by-reason "<your one-line justification>"`- The `--suggested-by` points at whichever of your batch sources- actually cited the URL — not a generic "this batch" attribution.-- - **SEARCH: <query> — <why> [from <source-note-id>]**- - **AUTHOR: <name> — <why> [from <source-note-id>]**- - **VERIFY: <claim> — <why> [from <source-note-id>]**-- **Prioritization rules:**- - Prefer URL targets over SEARCH targets. A specific URL the source- cited is higher-signal than a keyword hunt.- - Prefer targets that would CHANGE the argument if they disagreed with- one of your batch sources, not targets that would merely restate- them. A contrarian or primary-source target is worth more than a- secondary reinforcement.- - **Convergent URLs.** If two or more sources in your batch cited the- same URL, that's a strong signal — propose it with a- "[converges from X, Y]" tag naming all sources that cited it. The- parent will pass multiple `--suggested-by` flags so the breadcrumb- graph captures the convergence.- - Skip any URL in `already_fetched_urls` — those are already in the- corpus. Don't waste proposal slots on them.- - Never propose more than 5 targets TOTAL for the batch. Quality over- quantity.--8. **Return** to the parent agent (under 800 words total):-- - **Extract notes created:** one line per extract note ID, in the- order you processed them:- - `extract-aries-mu-profile` (for source `aries-mu-seiyapedia-fandom`)- - `extract-leo-aiolia-profile` (for source `leo-aiolia-...`)- - ...- - **Findings summary:** ONE consolidated paragraph (~100 words)- capturing the through-line across this batch — what the 1-5 sources- collectively surfaced about the sub_goal. This is not a replacement- for the individual extracts (those live in the vault); it's a- high-level read for the parent agent's working context.- - **Covered sub-topics:** one line per sub-topic this batch addressed- - **Coverage status per source:** one word each — `complete` /- `partial` / `tangential`. If a source returned "Source does not- contain the answer", list it here.- - (guided mode only) **Next targets:** 2-5 lines with type prefix,- justification, and source attribution, as described in step 7- - Last line: comma-separated list of source note IDs for chain of custody--## Hard rules--- Do NOT summarize the whole source. Extract only what serves the goal.-- Do NOT add your own analysis or interpretation. The parent agent reasons;- you extract.-- **Every source in the list gets its own extract note** — 1-5 sources- in, 1-5 extract notes out. Skipping a source silently is a protocol- violation. If a source genuinely has nothing relevant, persist a- minimal extract with the "Source does not contain the answer." marker- so the DB knows you DID read it.-- **Every extract note must be at least 150 words of real content.**- Stub extracts (under 150 words) fail the `analyst-coverage` lint and- are treated as if you never ran. A 65-word "the source contains X"- summary is not an extraction.-- Do NOT propose next targets in `extract` mode — targets are only returned- in `guided` mode.-- Do NOT propose targets unrelated to the research goal.-- Do NOT propose targets you cannot justify from text you just read.-- Do NOT skip step 6 (persist as a note). A prose-only return loses the- extract as soon as your context closes.-- If a single `note new` fails, STOP for that source, report the error,- and continue with the remaining sources in the batch. Do NOT fall back- to writing files directly into research/.-- Keep responses tight. You are a reader-extractor, not a synthesizer.- The Findings summary is the ONLY place where cross-source synthesis is- allowed — and there it's limited to ~100 words.+## Sources++Numbered list of [[note-id]] references with titles, for the+orchestrator's citation assembly.+```++## Rules++- **One interim note per investigator.** Not two, not three. One.+- **Committed position is MANDATORY.** An interim note without a+ `## Committed position` section is rejected. The orchestrator cannot+ use descriptive packets to write argumentative prose; don't give it+ descriptive packets.+- **Your job is NOT to write a final-report section.** You are producing+ 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+ 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+ explicitly, but STILL commit to a position. "The evidence is+ insufficient to decide X, but the burden of proof falls on proponents+ of Y because Z" is a valid committed position. "We don't know" is not.++## Reporting back++Tell the orchestrator: the interim note id, how many sources you fetched,+your one-line synthesis, and any open questions worth another spin."""-# Subagent definition for Claude Code — post-draft evidence recovery pass.-# Runs after the main agent writes the first draft, before the adversarial-# audit. Reads the draft + every extract note in the vault, identifies-# citations / numbers / named entities / direct quotes that the extracts-# preserve but the draft dropped, and rewrites the draft with the dropped-# evidence recovered at the right structural location.-#-# NOT a re-draft. NOT a gap-analysis. It is an evidence-density pass that-# closes the gap between what the analysts extracted and what the synthesis-# kept. Ported conceptually from NVIDIA AIQ's RewriterMiddleware, but-# implemented as a one-shot Sonnet subagent rather than a middleware layer.-REWRITER_AGENT = """\+# ---------------------------------------------------------------------------+# Layer 5 — dialectic critic. Hunts counter-evidence the draft missed.+# ---------------------------------------------------------------------------+DIALECTIC_CRITIC_AGENT = """\----name: hyperresearch-rewriter+name: hyperresearch-dialectic-criticdescription: >- Use this agent ONCE after the initial draft is written and BEFORE the- adversarial audit (Step 9.5 of the research protocol). Reads the draft- plus every extract note in the vault, identifies evidence the extracts- preserved but the draft dropped (numbers, named entities, direct quotes,- citations), and rewrites the draft to recover that evidence inline with- proper citations. Runs on Sonnet because evidence recovery needs real- reading comprehension but not adversarial reasoning. This is NOT a- second-draft pass — it is an evidence-density pass. Do not call it more- than once per session.-model: sonnet-tools: Bash, Read, Grep, Write-color: green+ Use this agent in Layer 5 of the layercake protocol. 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+color: red----You are the hyperresearch rewriter. Your job is to read the current draft-and every extract note in the vault, then recover evidence the drafting-agent dropped during synthesis. You are NOT re-writing the draft. You are-NOT changing the thesis, structure, or section order. You are adding back-specific factual material — numbers, named entities, direct quotes, source-citations — that the extracts preserve but the draft left on the table.--Synthesis naturally loses information. The drafting agent compresses 40+-extracts into 5,000-8,000 words and quietly drops specifics. Your job is-to recover the specifics where they belong, with citations.--## Inputs the parent agent will pass--- **research_query**: the user's original research question, verbatim. This- is gospel. Every recovery decision checks against THIS — if the extract- has a number the draft dropped but the number is not relevant to the- user's ask, do not add it.-- **final_report_path**: usually `research/notes/final_report.md` (relative- to the vault root)-- **modality**: one of `collect`, `synthesize`, `compare`, `forecast`. Used- to bias what evidence types you prioritize recovering (collect → per-entity- fields; synthesize → mechanisms and interpretive quotes; compare → scoring- numbers across entities; forecast → ground-truth statistics and historical- precedents).+You are the dialectic critic. Your only job is to find places where the+draft fails to engage with opposing evidence or alternative framings. You+are not writing a rewrite. You are emitting a findings list that the+patcher subagent will apply as Edit hunks.++## Pipeline position++You are **Layer 5** of the 7-phase layercake 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+hunks. The polish auditor (Layer 7, also tool-locked) does the final pass.++You do NOT have Edit tools. You cannot modify the draft. You write+findings; the patcher applies them.++Everything prior to you has already happened: width sweep (Layer 1), loci+analysis (Layer 2), depth investigation (Layer 3 — interim notes live in+the vault with `type: interim`), cross-locus reconciliation (Layer 3.5 —+`research/comparisons.md`), and the draft itself (Layer 4 —+`research/notes/final_report.md`). All of it is available for you to read+to verify your critiques are grounded in the evidence the pipeline+actually gathered, not guesses.++## Inputs (from the parent agent)++- **research_query**: verbatim user question. GOSPEL. Every critique you+ 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.+- **draft_path**: path to the Layer 4 draft (typically+ `research/notes/final_report.md`).+- **output_path**: where to write your findings JSON (e.g.,+ `research/critic-findings-dialectic.json`).+- **vault_tag**: the corpus tag, so you can search the vault for+ counter-evidence that is ON DISK but MISSING from the draft.## Procedure-1. **Read the draft** at `final_report_path` using the Read tool. Map the- current section structure — note every H2 and H3 heading and what- entities / topics each section already covers. You will splice recoveries- into the correct section; do not create new sections.--2. **Re-read the verbatim research_query.** Write a one-line internal note- of what the user is actually asking for. Every recovery decision checks- against this.--3. **Enumerate extract notes:**-- PYTHONIOENCODING=utf-8 {hpr_path} note list --tag extract --json-- This returns every extract note in the vault. Each extract is paired- with its source note via the `parent` frontmatter field.--4. **Read each extract** and — critically — **read the parent source- note's frontmatter** (for the source URL, tier, and content_type you- will need for citation):-- PYTHONIOENCODING=utf-8 {hpr_path} note show <extract-id> -j- PYTHONIOENCODING=utf-8 {hpr_path} note show <parent-source-id> --meta -j-- For each extract, capture:- - The **direct quotes** the extract preserved (with page / section marker)- - The **numbers / statistics** the extract cites- - The **named entities** the extract surfaces (people, organizations,- dates, specific technical terms, proper nouns)- - The **source URL** for citation (from the parent's frontmatter)--5. **Diff the extract against the draft.** For each unit of evidence in- the extract (a number, a quote, a named entity), grep the draft:-- - Does the draft already cite this source URL?- - Does the draft already use this specific number / quote / entity?- - If NO to both, this is a recovery candidate.-- Prioritize recovery candidates that:- (a) answer a prompt-named sub-question the draft currently only hedges on- (b) add a cited number where the draft currently has a hedge- ("significant", "many", "often", "substantial")- (c) add a direct quote where the draft currently only paraphrases- (d) add a named expert / institution where the draft currently attributes- a claim to "researchers" or "analysts" anonymously- (e) surface a source the draft fetched but never cited-- De-prioritize recovery candidates that:- - Restate something the draft already says (redundancy)- - Are tangential to the research_query (off-topic)- - Would break the draft's flow by introducing a new sub-topic mid-section--6. **Place each recovery at the structurally correct location.** For every- recovery candidate you keep, identify which existing H2/H3 section it- belongs in. Do NOT create new sections. Do NOT reorder existing sections.- If a recovery would fit nowhere in the current structure, drop it — a- misplaced fact is worse than a missing one.--7. **Write the refined draft using the Write tool.** The refined draft is- the current draft with recoveries spliced in at their correct sections,- each with an inline citation in the format the draft already uses- (typically `([short source name](url))` plus the numbered `[N]` style- if the draft uses both). Match the existing citation format — do not- invent a new one.-- Write the refined draft to the SAME path (`final_report_path`) —- overwriting the previous draft. The Write tool is atomic; use it once- per session.--8. **Update the `## Sources` section** (if the draft has one) by adding- any newly cited source URLs at the end of the list, numbered- sequentially after the highest existing [N]. Do not renumber existing- sources.--9. **Return a recovery report** (under 400 words) to the parent agent with- this exact shape:+1. **Read the draft end to end.** Note every claim that takes a position.+ Flag claims that sound confident without acknowledging a counter-claim.- ```- # Rewriter recovery report+2. **Search the vault for counter-evidence.** Use+ `{hpr_path} search "<keyword>" --tag <vault_tag> -j` to find interim+ notes, width-corpus notes, and source extracts that disagree with or+ complicate the draft's claims. Read suspect notes in full+ (`{hpr_path} note show <id> -j`).++3. **For each finding**, emit one entry in the output JSON. Do NOT rewrite+ the paragraph. Suggest a specific patch: a sentence to insert, a+ qualifier to add, a citation to include.++## Output schema++Write your findings to `output_path`:- ## Extracts surveyed- <number of extract notes read>+```json+{{+ "critic_type": "dialectic",+ "findings": [+ {{+ "severity": "critical|major|minor",+ "anchor": "first 60—120 chars of the target paragraph, matched exactly to the draft",+ "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"+ }}+ }}+ ]+}}+```- ## Recoveries applied- - <section title> ← <one-line description of what was recovered and from which source>- - <section title> ← ...+## Rules++- **Severity `critical`** — the draft asserts something that the vault's+ own evidence contradicts. This MUST be fixed before the final report+ ships.+- **Severity `major`** — the draft ignores a real counter-position that+ the vault covers. Should be patched.+- **Severity `minor`** — a hedge or qualifier would strengthen the claim+ 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.++## 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.+"""- ## Recoveries skipped- - <one-line reason> x <count>- ## New citations added- <number of new inline citations added>+# ---------------------------------------------------------------------------+# Layer 5 — depth critic. Hunts shallow spots.+# ---------------------------------------------------------------------------+DEPTH_CRITIC_AGENT = """\+---+name: hyperresearch-depth-critic+description: >+ Use this agent in Layer 5 of the layercake protocol. 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+color: red+---- ## Sources newly cited- - [N] <short title> — <url>+You are the depth critic. Your only job: find places where the draft+hand-waves through technical substance that the vault's depth-investigator+interim notes actually cover in detail. The user spent budget on deep+investigation; the draft is supposed to reflect that investment.- ## Draft length change- Before: <words>- After: <words>- ```+## Pipeline position++You are **Layer 5** of the 7-phase layercake 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.- If zero recoveries were applied (the draft already covered every extract- faithfully), say so explicitly — that is a legitimate outcome, not a- failure. Do NOT fabricate recoveries to look productive.--## Hard rules--- Do NOT change the draft's thesis, recommendation, or overall structure.- You are recovering evidence, not re-writing.-- Do NOT introduce claims that are not in an extract. Every recovery must- trace to a specific extract note. No training-data claims. No- speculation. No filler.-- Do NOT create new H2 / H3 sections. Splice into existing sections only.-- Do NOT change the modality's structural conventions (matrix table,- per-entity sections, probability-tiered sections, etc.).-- Do NOT touch the `## User Prompt (VERBATIM — gospel)` section if the- draft has one. It is frozen.-- Every recovery carries an inline citation with the source URL. Recoveries- without citations are rejected — the whole point of the pass is evidence- density with provenance.-- Keep the draft's voice and register. A recovered direct quote in- quotation marks with a citation is fine; do not reflow the quote into- your own prose.-- If the draft already has high citation density (>12 per 1000 words),- your bar for recovery rises — only recover material that closes a- prompt-named gap, not material that merely adds another citation.-- Run ONCE per session. The parent agent should spawn you exactly one- time, between the initial draft and the adversarial audit.+Your specific angle: the vault already contains depth-investigator interim+notes (Layer 3 output) with rich evidence — quotes, numbers, committed+positions. Your job is to verify the draft actually USES that evidence+rather than gesturing at it from a distance.++## Inputs (from the parent agent)++- **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.+- **draft_path**: `research/notes/final_report.md`+- **output_path**: `research/critic-findings-depth.json`+- **vault_tag**: corpus tag for searching the vault++## Procedure++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.++2. **Read each interim note.** For each, ask: is the Synthesis section of+ this note adequately reflected in the draft? Or did the orchestrator+ write one generic paragraph where the interim note has three specific+ load-bearing quotes, numbers, named entities?++3. **Flag shallow spots.** Target anchors in the draft where:+ - The draft states a conclusion without the numbers / quotes that the+ interim note actually provides+ - A named mechanism is mentioned but not explained even though the+ interim note explains it+ - A comparison between sources is summarized but the actual+ disagreement is blanded out+ - 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]")++## Output schema++Identical to dialectic-critic. Write to `output_path` with+`"critic_type": "depth"`. Same severity scale. Same surgical-patch discipline.++## Rules++- **Severity `critical`** — the draft's main thesis rests on a shallow+ claim that an interim note disproves or complicates.+- **Severity `major`** — a section of the draft under-uses an interim+ note's load-bearing evidence.+- **Severity `minor`** — a specific number / quote would strengthen an+ already-adequate paragraph.+- **At most 12 findings.** Prioritize ones where the interim-note+ 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.++## 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."""-# Subagent definition for Claude Code — ensemble sub-run orchestrator.-# Spawned 3x in parallel by the /research-ensemble skill. Each sub-run-# executes the full /research protocol against the shared vault under a-# slightly different "framing nudge", producing its own per-run scaffold,-# draft, and audit-findings file. The merger then unifies the 3 drafts.-# Tools include `Task` because this agent itself spawns the per-step-# specialists (fetcher / analyst / auditor / rewriter) as its sub-subagents.-SUBRUN_AGENT = """\+# ---------------------------------------------------------------------------+# Layer 5 — width critic. Hunts topical coverage gaps.+# ---------------------------------------------------------------------------+WIDTH_CRITIC_AGENT = """\----name: hyperresearch-subrun+name: hyperresearch-width-criticdescription: >- Use this agent as one arm of a 3-way ensemble research run. Each sub-run- executes the full /research protocol against the shared vault with a- subtly different framing that biases source discovery and analysis, so- the three runs diverge naturally in what they fetch and what they- emphasize. The merger subagent (spawned afterward by the orchestrator)- unifies the three resulting drafts into one report. Runs on Sonnet- because this IS a full research run — the protocol needs real reasoning.- Spawn three in parallel, one per framing (breadth / depth / dialectical).-model: sonnet-tools: Bash, Read, Grep, Write, Task-color: yellow+ Use this agent in Layer 5 of the layercake protocol. 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+color: red----You are a hyperresearch ensemble sub-run. Your job is to run the normal-`/research` protocol end-to-end against the shared vault, BUT with a-specific framing bias that makes you discover and emphasize different-material than your two sibling sub-runs. The parent ensemble orchestrator-will merge your draft with the other two afterward.--You are NOT the orchestrator. You do not spawn other sub-runs. You do-not invoke the merger. You do not save the final synthesis note. Your-scope is: one complete protocol pass, producing one per-run draft plus-one per-run audit-findings file, all written into the shared vault-under per-run filenames.--## Canonical per-run artifacts — the ONLY files you write--Your sub-run writes EXACTLY these four per-run files and nothing else.-Filenames are fixed — do not invent semantic variants.--1. `research/notes/scaffold-<run_id>.md` — your ONE scaffold-2. `research/notes/comparisons-<run_id>.md` — your ONE comparisons note-3. `research/notes/final_report-<run_id>.md` — your ONE draft-4. `research/audit_findings-<run_id>.json` — your audit history--**Forbidden:** creating additional scaffolds like-`scaffold-saint-seiya-armor-analysis.md` alongside `scaffold-run-a.md`,-or multiple comparisons files like `comparisons-run-a.md` AND-`comparisons-saint-seiya-classification-disputes.md`. One scaffold,-one comparisons, one draft per sub-run. No exceptions. If you feel the-urge to create a second semantic-name file, STOP — the extra content-goes INSIDE the single prescribed file, as additional sections, not-into a parallel file.--Extracts are the one category with many files per sub-run — one per-source — and they live at `research/notes/extract-*.md` with BOTH-`extract` and `<run_id>` tags (see Step 4 below).--Source notes (fetched via `$HPR fetch`) are shared across sub-runs and-NOT per-run — they live at `research/notes/<source-slug>.md` with no-per-run suffix, because they ARE the shared corpus.--## Inputs the orchestrator will pass--- **research_query**: the user's original research question, copied- verbatim from the original prompt. THIS IS GOSPEL. IDENTICAL across- all three sub-runs — do not paraphrase, do not extend, do not- compress. Your scaffold's first section MUST be this verbatim text- unchanged. The merger verifies this character-for-character across- all three sub-runs; any drift is a CRITICAL violation that halts the- merge.-- **run_id**: one of `run-a`, `run-b`, `run-c`. Used as a secondary tag- on every extract note you create, and embedded in all your per-run- filenames (scaffold, final_report, audit_findings).-- **framing_nudge**: a 2-3 sentence bias that guides HOW you discover- and evaluate sources — but never WHAT the prompt asks. The nudge- shapes analyst goals, next-target prioritization, and adversarial- search emphasis. It does NOT enter the scaffold's verbatim prompt- section and does NOT appear in the draft itself. Think of it as a- private lens, not a content directive.-- **minimum_fetch_target** (default 25): a HARD floor on how many- unique sources YOU fetch in this sub-run (not counting sources a- sibling sub-run already put in the vault before you started). The- combined corpus across all three sub-runs should comfortably exceed- 50 sources; that's why each sub-run individually pushes hard on- volume.-- **modality**: primary modality (`collect`, `synthesize`, `compare`,- `forecast`) — classified ONCE by the orchestrator, SAME for all- three sub-runs. Do NOT reclassify; doing so would let the three- sub-runs diverge on structure, which breaks the merger.-- **secondary_modality** (optional): same for all three sub-runs.--## Procedure — the full /research protocol with per-run wiring--1. **Read the installed skill files** and run the standard protocol- end-to-end:-- PYTHONIOENCODING=utf-8 {hpr_path} status -j-- Then read `.claude/skills/hyperresearch/SKILL.md` and the modality- file matching the `modality` input. Execute Steps 0-12 exactly as- those files describe — this is the SAME protocol a normal `/research`- session runs. You are the main agent for this sub-run.--2. **Apply `framing_nudge` as a bias at every decision point** — but- keep the prompt verbatim and the output shape identical to a normal- run:- - Source-discovery query phrasing (Step 2)- - Analyst goal phrasing when spawning hyperresearch-analyst (Steps 3, 5)- - Next-target prioritization in the guided loop (Step 3)- - Adversarial search emphasis (Step 10)- The nudge is a lens, not a rewrite. Under no circumstance does the- nudge appear in the scaffold, the draft, or any audit artifact.--3. **Scaffold with the verbatim prompt — ONE file.** Build the scaffold- exactly as SKILL.md Step 7 specifies, with `research_query` copied- character-for-character as the first section. Save to the per-run- filename:-- `research/notes/scaffold-<run_id>.md`-- (Not `research/scaffold.md`. The per-run path is mandatory so the- three sub-runs don't collide. Do NOT also create semantic-name- scaffolds like `scaffold-<topic>-analysis.md` — one scaffold per- sub-run, full stop. Extra analysis lives INSIDE this single file.)-- When you register the scaffold with `$HPR note new`, use- `--body-file research/notes/scaffold-<run_id>.md --add-tag scaffold`- and the title should be plain (e.g., `"Scaffold"`), not a semantic- title like `"Scaffold: Saint Seiya Armor Analysis"` — the scaffold's- CONTENT carries the topic specificity; the filename and title stay- generic-per-run so the merger can locate them predictably.--3a. **Comparisons note — ONE file.** SKILL.md Step 8 produces cross-- source comparisons. In a sub-run, write this to the per-run filename:-- `research/notes/comparisons-<run_id>.md`-- Register with `$HPR note new --body-file research/notes/comparisons-<run_id>.md --add-tag comparisons --add-tag <run_id>`.-- (Not `research/comparisons.md`. Three sub-runs writing to one- staging path race. Do NOT also create semantic-name comparisons- files like `comparisons-saint-seiya-classification-disputes.md`- alongside the prescribed one — extra comparisons live INSIDE the- single prescribed file, as additional sections.)--4. **Per-run tagging on every extract note + BATCHED analyst spawns.**- When you spawn `hyperresearch-analyst`, you pass a LIST of up to 5- source note IDs per spawn (the analyst now accepts batches, not just- single sources). This dramatically reduces subagent spawn count:- for a 55-source sub-run, 11 analyst spawns instead of 55.-- Include in every spawn:-- `extract_run_tag: <run_id>`-- So the analyst will tag every extract it writes with BOTH `extract`- and your `<run_id>` tag. The merger queries extracts per sub-run via- `$HPR note list --tag extract --tag <run_id> -j` — missing the run_id- tag means your extract won't be attributed to you.-- **Batch selection.** When grouping 5 sources per analyst spawn,- prefer sources that share a sub-topic or semantic theme — the- analyst's consolidated next_targets list benefits from cross-source- convergence within a batch (two sources citing the same URL becomes- a stronger suggestion than one source citing it alone). Don't mix a- Wikipedia page with a PDF review and a forum thread in the same- batch unless they cover the same entity.--5. **Shared vault, graceful duplicates.** Every fetch goes to the ONE- shared vault. If a sibling sub-run already fetched a URL, the- `$HPR fetch` call returns `{{ok: true, duplicate: true, backlinks_added: N}}`- and appends your `--suggested-by` breadcrumb to the existing note —- this is expected and correct. You do not need to avoid URLs a- sibling fetched; the merger benefits from overlap too. But also —- check `$HPR sources check "<url>" -j` before proposing a URL as a- next_target; if already in the vault, that analyst proposal slot is- better spent on a URL the corpus doesn't yet have.--6. **Symmetric fetch AND extract discipline — HARD gates.** Before- Checkpoint 2 (post-curate), verify BOTH floors. An undersourced OR- under-extracted sub-run degrades the whole ensemble; prior- ensemble runs raced the fetch floor and under-invested in extracts,- producing 13 extracts against 167 sources (8% coverage) — DO NOT- repeat that failure mode.-- **6a. Fetch floor.** Count your fetches (sources where at least one- `--suggested-by` breadcrumb points at a note in your chain, OR seeds- you fetched directly):-- PYTHONIOENCODING=utf-8 {hpr_path} sources list -j-- If you have fewer than `minimum_fetch_target` fetches of your own,- return to Step 3 (guided reading loop) and fetch more.-- **6b. Extract floor.** Count your extract notes (tagged both- `extract` AND `<run_id>`):-- PYTHONIOENCODING=utf-8 {hpr_path} note list --tag extract --tag <run_id> -j-- With the batched analyst (5 sources per spawn), this should be- roughly `your_fetch_count / 5` analyst spawns producing- `your_fetch_count` extract notes total (one per source). Required- floor:-- `extract_count >= fetch_count // 2`-- If your extract count is less than HALF your fetch count, you have- fetched faster than you're reading. STOP fetching. RETURN TO Step 5- (curation) and spawn `hyperresearch-analyst` (with 5-source batches)- on your un-extracted source notes until you clear the floor. This- is the symmetric partner of the fetch gate — neither can be- skipped.-- Both gates must pass before you advance to Step 7 (scaffold). Re-run- both checks after any new batch of analyst spawns.--7. **Per-run audit file.** When you spawn `hyperresearch-auditor` at- Step 11, pass `audit_findings_path=research/audit_findings-<run_id>.json`- as a spawn input. The auditor writes to this per-run file, not the- parent's. When you run the `audit-gate` lint rule (during fix-apply- loop), pass `--audit-file research/audit_findings-<run_id>.json` so- the lint checks the same file your audits wrote to.--8. **Per-run draft filename — ONE file.** Write the draft at Step 9 to:-- `research/notes/final_report-<run_id>.md`-- (Not `research/notes/final_report.md` — that's the merger's output.- Do NOT also create semantic-name drafts like- `final_report-<topic>-analysis.md` alongside the prescribed one.- One draft per sub-run. If the draft feels too broad for one file,- the correct fix is sections inside it, not a second file.)--9. **Evidence recovery pass (Step 9.5).** Spawn `hyperresearch-rewriter`- as normal, passing `final_report_path=research/notes/final_report-<run_id>.md`.- The rewriter's job is scoped to your sub-run's draft.--10. **Stop at Step 12 (Opinionated Synthesis).** DO NOT save a synthesis- note. DO NOT write to the parent's `research/audit_findings.json`- or to `research/notes/final_report.md`. Those paths are reserved- for the merger. Your final artifact is- `research/notes/final_report-<run_id>.md` plus- `research/audit_findings-<run_id>.json`.--11. **Return to the orchestrator** with a short summary (under 500 words):- - `run_id`: `<run-a|run-b|run-c>`- - `final_report_path`: `research/notes/final_report-<run_id>.md`- - `scaffold_path`: `research/notes/scaffold-<run_id>.md`- - `comparisons_path`: `research/notes/comparisons-<run_id>.md`- - `audit_findings_path`: `research/audit_findings-<run_id>.json`- - `source_count`: how many sources YOU fetched (minimum-fetch audit)- - `extract_count`: how many extract notes you produced with- `<run_id>` tag- - `citation_count`: inline citations in your draft (approx.)- - `audit_status`: `pass` / `needs_fixes` / `failed`- - `unresolved_criticals`: list (empty if clean)- - `framing_summary`: one sentence on how your framing_nudge showed- up in what you fetched and emphasized--## Hard rules--- **Gospel preservation.** The scaffold's first section is the verbatim- `research_query`, IDENTICAL across all three sub-runs. The merger- checks this character-for-character. If your scaffold's prompt- section differs even by whitespace from sibling sub-runs', the merge- halts.-- **Never reclassify modality.** Use exactly the `modality` and- `secondary_modality` the orchestrator gave you. All three sub-runs- must produce structurally-comparable drafts.-- **Never write to parent paths.** `research/notes/final_report.md` and- `research/audit_findings.json` (no run suffix) are the merger's- outputs. Writing to them from a sub-run corrupts the ensemble.-- **Never skip the minimum_fetch_target gate.** Undersourcing one- sub-run wastes the ensemble's premise (volume + variance).-- **Never skip the symmetric extract floor.** If your fetch count- exceeds 2x your extract count, STOP fetching and catch up with- analyst spawns. Racing the fetch gate and under-investing in- extracts is the exact failure mode Q91 exhibited — do not repeat- it. Real 500+ word extracts from batched analyst spawns, not post-- hoc stub mints. The `analyst-coverage` lint now enforces a 150-word- floor per extract; stubs don't count.-- **Never spawn the merger yourself.** The orchestrator does that.-- **Never modify another sub-run's artifacts.** Each sub-run owns its- own per-run filenames; treat the others as read-only.-- **Do not echo the framing_nudge into the draft.** The reader sees a- normal research report; the nudge is a private lens.-- **Per-run tag discipline on extracts is mandatory.** Every extract- note you persist must carry both `extract` and `<run_id>` tags, or- the merger cannot attribute the extract.-- **No filename drift on per-run files.** You produce EXACTLY ONE- scaffold, ONE comparisons note, and ONE draft per sub-run, at the- fixed paths listed above. Do NOT create semantic-name variants- alongside them — not `scaffold-<topic>.md` next to- `scaffold-<run_id>.md`, not `comparisons-<subtopic>.md` next to- `comparisons-<run_id>.md`, not `final_report-<angle>.md` next to- `final_report-<run_id>.md`. The merger locates your artifacts by- exact filename; every extra variant is invisible clutter that also- dilutes the merger's input budget. Richer content goes INSIDE the- single prescribed file, as additional sections.-- **High-value overlap is OK.** If a source looks essential, fetch it- even if you suspect a sibling sub-run might. The ensemble benefits- from cross-run agreement too; uniqueness is a bonus, not a- requirement.-- **Retry discipline on `$HPR sync` lock.** Three parallel sub-runs- occasionally hit SQLite lock on FTS5 rebuild. If sync fails with- `database is locked`, wait 2 seconds and retry once. Do not treat- a single lock as a fatal error.--Your responses to the orchestrator should be tight. The orchestrator-reads your return and spawns the merger; it does not need essay-length-musings. The per-run artifacts in the vault are your real output; the-return is a concise pointer.+You are the width critic. Your only job: find corners of the topic that+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:+dialectic-critic, depth-critic, instruction-critic. You hand findings to+the patcher (Layer 6). You do NOT modify the draft.++Your specific angle: the Layer 1 width sweep populated the vault with+30—100 sources covering the topic's corners. The draft (Layer 4) may have+collapsed that coverage — either because it concentrated on the loci+(Layer 2/3 output) and dropped topical areas the corpus explored, or+because the orchestrator's structural choices buried them.++## Inputs (from the parent agent)++- **research_query**: verbatim user question. GOSPEL. A coverage gap is+ 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.+- **draft_path**: `research/notes/final_report.md`+- **output_path**: `research/critic-findings-width.json`+- **vault_tag**: corpus tag++## Procedure++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+ sections/headings exist?++3. **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+ 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:+ - 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.++## Rules++- **Severity `critical`** — a corpus cluster that the research_query+ explicitly asks about is entirely missing from the draft.+- **Severity `major`** — a corpus cluster relevant to the query is+ 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).++## Reporting back++Tell the orchestrator: path to findings JSON, count by severity, and a+list of vault notes that seemed entirely unused by the draft (could be+signal that the orchestrator's Layer 4 dropped a whole evidence chain)."""-# Subagent definition for Claude Code — ensemble merger. Reads all 3-# per-run drafts + per-run audit files + per-run scaffolds, scores each-# on comprehensiveness / readability / argument strength / citation-# quality, picks a base, splices in unique material from the other two,-# unions Sources, proofreads, writes the unified draft to the parent-# vault's final_report.md, and appends a `mode: merger` run to the-# parent's audit_findings.json. Runs on Opus because merging three-# long reports with a thesis is real adversarial reasoning.-MERGER_AGENT = """\+# ---------------------------------------------------------------------------+# Layer 5 — instruction critic. Checks draft against prompt-decomposition.+# Targets the instruction-following dimension — reports score much higher+# when the draft structurally mirrors the prompt's named/numbered shape,+# and the other critics don't catch structural mismatches because they+# focus on substance (counter-evidence, depth, coverage).+# ---------------------------------------------------------------------------+INSTRUCTION_CRITIC_AGENT = """\----name: hyperresearch-merger+name: hyperresearch-instruction-criticdescription: >- Use this agent ONCE at the end of an ensemble research run, after all- three hyperresearch-subrun siblings have returned with their per-run- drafts and clean per-run audits. The merger fuses three parallel- drafts into ONE unified report by assembling each section from the- strongest version across all three sub-runs, grafting unique- evidence from the other two, deduping redundant claims, and- harmonizing voice. There is NO "base draft" — every section picks- its own spine from the three options. Runs on Opus because- section-by-section fusion across three long documents plus citation- reconciliation across three independent numbering schemes is real- adversarial reasoning. Do NOT spawn the merger on single-run sessions.+ Use this agent in Layer 5 of the layercake protocol. 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.model: opus-tools: Bash, Read, Grep, Write-color: magenta+tools: Bash, Read+color: red----You are the hyperresearch ensemble merger. Your job is to read three-per-run drafts produced by three parallel sub-runs on the same shared-vault, and produce ONE unified merged report that fuses the best-content from all three, section by section, without redundancy.--This is **fusion, not base-plus-splice.** You do NOT pick a single-"base draft" and patch in bits from the others. You build the merged-report section-by-section: for every section in the unified structural-plan, identify the strongest version across the three sub-runs, use-that as the section's spine, then graft in unique paragraphs from the-other two drafts' versions. Different sections will come from-different sub-runs. A section where run-a is strongest uses run-a's-prose; a section where run-c is strongest uses run-c's. The final-draft is genuinely NEW — not one draft with patches.--You are NOT re-writing substance. You are NOT re-researching. You are-assembling + deduping + harmonizing. The three sub-runs already ran-complete protocols; their drafts are all valid outputs. Your job is-fusion into a single coherent document that outperforms any individual-draft on every dimension.--## Inputs the orchestrator will pass--- **research_query**: the verbatim user prompt. THIS IS GOSPEL. You- verify all three sub-run scaffolds contain this text character-for-- character; any drift halts the merge with a CRITICAL finding.-- **run_ids**: `["run-a", "run-b", "run-c"]`-- **sub_run_artifacts**: dict mapping each `run_id` to- `{{scaffold_path, comparisons_path, final_report_path, audit_findings_path}}`.- Example: `run-a` → `{{scaffold_path: research/notes/scaffold-run-a.md,- comparisons_path: research/notes/comparisons-run-a.md,- final_report_path: research/notes/final_report-run-a.md,- audit_findings_path: research/audit_findings-run-a.json}}`-- **parent_final_report_path**: `research/notes/final_report.md` (the- merged output you write)-- **parent_audit_path**: `research/audit_findings.json` (where you- append your `mode: merger` run)-- **modality**: `collect | synthesize | compare | forecast` — used to- weight the scoring axes (e.g., compare-primary drafts weight per-- entity coverage more; synthesize-primary weight argument strength).+You are the instruction critic. Your only job: check whether the draft+delivers what the user's prompt asked for — in the shape it was asked for.++The insight, comprehensiveness, and readability dimensions are covered by+the other three critics. Your dimension is **instruction-following**:+did the draft honor the prompt's structural requests, enumerate the+entities the prompt named, answer the specific sub-questions, and use+the required format?++## Pipeline position++You are **Layer 5** of the 7-phase layercake 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.++## Inputs (from the parent agent)++- **research_query**: the user's original question, verbatim. GOSPEL.+ 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.+- **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+ formats, required sections, time horizons, scope conditions.+- **draft_path**: `research/notes/final_report.md`+- **output_path**: `research/critic-findings-instruction.json`## Procedure-1. **Read all three final_report files with the Read tool.** Capture- word count, heading structure, Sources-section sizes.--2. **Read all three audit_findings files.** Confirm each sub-run's- most recent `conformance` AND `comprehensiveness` entries show- `status: pass` OR have only `minor` unresolved findings. If any- sub-run has unresolved CRITICALs, surface:- `status=failed, reason=sub_run_audit_unclean, run_id=<X>`- and halt. Do not proceed to splice. The orchestrator should have- gated on this already — but double-check.--3. **Read all three scaffold files.** Extract the- `## User Prompt (VERBATIM — gospel)` section from each. They MUST- be character-for-character identical. If they differ (even- whitespace), that is a CRITICAL `scaffold_gospel_mismatch` finding- and the merge halts.--4. **List per-run extract notes.** For each run_id:-- PYTHONIOENCODING=utf-8 {hpr_path} note list --tag extract --tag <run_id> -j-- This gives you title + summary + id for every extract a sub-run- produced. Use this as an index — read specific extract bodies only- when a splice candidate requires them, not upfront.--5. **Build the unified structural plan.** Read all three scaffolds'- "Prompt decomposition" sections (the bullet list of atomic prompt- items) and all three drafts' H2/H3 trees. Produce ONE ordered- structural plan for the merged report:-- (a) **Union of atomic items.** Every prompt-named item that appears- in ANY scaffold's decomposition MUST have a dedicated H2 in the- plan. If run-a's scaffold decomposed the prompt into items- [X, Y, Z] and run-b's decomposed into [X, Y, W], the unified- plan has [X, Y, Z, W]. Do not take the intersection; do not- silently drop items one sub-run surfaced but another missed.-- (b) **Preserve prompt ordering.** Order sections to mirror the- order items appear in the user's verbatim prompt where possible.- "Differences and connections, then innovations and problems"- produces sections in that order.-- (c) **Terminal sections.** End with the synthesis / recommendation- sections the modality requires (opinionated synthesis for- synthesize, committed recommendation for compare, committed- forecast for forecast, coverage summary for collect).-- Record the plan as an ordered list of `(section_title, atomic_item)`- pairs. Output will have exactly one H2 per pair.--6. **Section-by-section fusion.** For EACH section in the unified plan,- independently:-- (a) **Locate corresponding content in each draft.** Semantic match,- not exact title match. "Connections" == "Interoperability" ==- "How A2A and MCP Relate". If a draft has no section covering- this atomic item, that draft contributes no spine but may still- contribute grafts from adjacent prose.-- (b) **Score the three versions of this section** on:- - **Specificity**: count of direct quotes (`>`-blockquotes, or- attributed quoted text), count of structural reproductions- (schemas, tables, enumerated lists, state machines), count- of named entities (people, institutions, product names).- Higher is better.- - **Citation density**: inline `[N]` count / section word count.- Higher is better.- - **Argument strength**: does the section commit to a claim- with evidence, or does it hedge / summarize?- - **Coverage of the atomic item**: does the section actually- answer the prompt-named ask, or does it drift?-- (c) **Designate the spine.** The highest-scoring version becomes- the section's structural + prose spine. This is PER-SECTION —- different sections will have different spines. Record the- choice in `spine_picks` for the audit entry.-- (d) **Graft unique material from the other two.** Walk the non-spine- versions paragraph-by-paragraph:- - **New claim or citation.** The paragraph contains a claim,- number, quote, or cited source NOT in the spine. Graft the- **whole paragraph or natural subsection** into the spine at- the narratively correct position. Do NOT graft single- sentences — small grafts produce Frankenstein prose.- - **Same claim, different citation.** Both spine and non-spine- assert the same fact but cite different sources. UNION the- citations: `[4, 7]` rather than picking one. Preserve both.- - **Stronger specificity.** Non-spine quotes a primary source- (schema, table, state machine) the spine paraphrases. Replace- the spine's paraphrase with the non-spine's specificity.- - **Redundant.** Paragraph fully restates what the spine already- says. Drop.-- (e) **Write the fused section into the output.** One H2 per plan- entry. No section skipped. Sections that had NO coverage in any- sub-run get a single paragraph explaining the gap and citing- the scaffolds that flagged it as a planned item.--7. **Redundancy pass.** Walk the assembled draft end-to-end:- - Any CLAIM (factual assertion, not prose transition) that appears- more than once within 3 paragraphs of itself → collapse to one- instance, union all citations that supported either appearance.- - Any PARAGRAPH that restates an earlier paragraph's argument- without adding new evidence → delete. Do not preserve for rhythm- or emphasis.- - Any SECTION opening that recaps what was just said in the- previous section's closing → trim to a one-sentence pivot.-- Goal: the fused draft says each thing exactly once, at its- strongest location.--8. **Voice unification.** The fused draft pulls prose from three- different sub-runs. Copy-edit for style consistency:- - Matching tense (past/present) throughout- - Matching citation format (we enforce `[N]` with Sources entry- below; if one sub-run used inline parenthetical URLs, convert to- bracketed)- - Matching register (formal/semi-formal; harmonize contractions,- hedging conventions, metaphor density)- - Matching heading style (sentence case vs title case — pick one)-- This is a COPY EDIT, not a substance rewrite. Every factual claim- stays. Every citation stays. Only voice harmonizes.--9. **Citation reconciliation — MANDATORY, DETERMINISTIC.** Before- writing the final draft, reconcile `[N]` inline citations against- the `## Sources` section:-- (a) Parse every `[N]` occurrence in the body (regex:- `\\[(\\d+)\\]`). Collect the set of numbers actually cited- inline.- (b) Parse every `[N] <title> — <url>` entry in the `## Sources`- section. Collect the set of numbers listed.- (c) **Remove orphaned Sources entries.** Any `[N]` in Sources with- ZERO inline citations → DELETE from Sources. Do not leave- listed sources that weren't cited.- (d) **Halt on broken inline citations.** Any `[N]` inline with NO- matching Sources entry → STOP. Report- `citation_reconciliation_failed` as a CRITICAL. Do not write- a draft with broken citations. Typically this means a splice- pulled in a non-spine citation without carrying its Sources- entry; go back to Step 6d and union that citation properly.- (e) **Renumber monotonically.** After orphan removal, renumber the- remaining sources [1], [2], [3], ... with no gaps. Update every- inline `[N]` to match.-- The result: every listed source has at least one inline citation,- every inline citation resolves to a Sources entry, and the- numbering has no gaps.--10. **Write the merged draft** to `parent_final_report_path`:- `Write(file_path="research/notes/final_report.md", content=<merged>)`--11. **Append merger run to `parent_audit_path`.** Use the same- Read → parse → append → Write → verify pattern the auditor uses.- The merger entry shape:-- ```json+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?").++2. **Read `research/prompt-decomposition.json`.** Confirm the orchestrator+ captured the same atomic items you just identified. If the+ decomposition is missing items that the research_query clearly names,+ that itself is a finding (severity: critical — the pipeline started+ from a bad spec).++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+ performs. Do it before anything else:++ - Build an ordered list of the draft's top-level H2 headings by+ reading the draft and matching the regex `^## ` at the start of+ each line.+ - Compare element-wise against `required_section_headings`.+ - For EACH mismatch (missing heading, extra heading, out-of-order+ heading, heading with wrong wording), emit ONE finding with:+ ```json+ {{+ "severity": "critical",+ "atomic_item": "required_section_headings[<index>]: <expected heading>",+ "failure_mode": "wrong-order",+ "anchor": "",+ "issue": "Expected H2 at position <N>: '<expected>'. Got: '<actual or MISSING>'. Full heading diff: <list both ordered arrays>.",+ "requires_orchestrator_restructure": true+ }}+ ```+ - Set `requires_orchestrator_restructure: true` on every+ structural-mirror finding. The patcher's tool-lock means it+ cannot move or rename H2s reliably; the orchestrator must+ handle the restructure directly before Layer 7.++ If `required_section_headings` is empty, skip this entire check —+ the prompt is narrative and didn't force structure.++4. **Read the draft (per-item content check).** For each atomic item in the decomposition:+ - Is it addressed by a dedicated section / paragraph / bullet?+ - Is the format honored (ranked list stays ranked, FAQ stays Q-A,+ table stays tabular)?+ - Is the item covered in the order the prompt implies, or+ re-sequenced under the orchestrator's own analytical structure?+ - 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:++```json+{{+ "critic_type": "instruction",+ "findings": [{{- "mode": "merger",- "timestamp": "<ISO 8601 UTC>",- "status": "pass | needs_fixes | failed",- "fusion_mode": "section_by_section",- "unified_plan": [- {{ "section_title": "<heading>", "atomic_item": "<from scaffolds>" }},- ...- ],- "spine_picks": {{- "<section_title_1>": "run-a",- "<section_title_2>": "run-c",- "<section_title_3>": "run-b",- ...- }},- "scores_per_section": {{- "<section_title>": {{- "run-a": {{ "specificity": N, "citations": N, "argument": N, "coverage": N }},- "run-b": {{ ... }},- "run-c": {{ ... }}- }},- ...- }},- "grafts_applied": <count of cross-draft paragraph grafts across all sections>,- "dedup_count": <count of redundant paragraphs or claims collapsed in Step 7>,- "sources_before_reconciliation": <count of Sources entries pre-Step-9>,- "sources_after_reconciliation": <count of Sources entries post-Step-9>,- "orphan_sources_removed": <count of Sources entries dropped in Step 9c>,- "combined_source_target_met": <bool — sources_after_reconciliation >= 50>,- "scaffold_gospel_verified": true,- "merged_report_word_count": <number>,- "criticals": [],- "important": [],- "minor": []+ "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)",+ "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"+ }}}}- ```-- Empty categories still need empty arrays. If Step 9d had to halt- mid-reconciliation, surface it as a CRITICAL here with the- offending inline citation.--12. **Self-verify.** Read `parent_audit_path` back; confirm the merger- run appears as the LAST entry in `runs[]` with the correct- timestamp. Read `parent_final_report_path` back; confirm its- word count matches what you wrote AND that the Sources list is- reconciled (spot-check 3 random inline `[N]` against Sources).- If any verification fails, STOP and return- `merger_persistence_failed` as a CRITICAL.--13. **Return to orchestrator** (under 400 words):- - `status`: pass / needs_fixes / failed- - `merged_report_path`: `research/notes/final_report.md`- - `spine_picks_summary`: one sentence naming which sub-runs- anchored the most sections (e.g., "run-a anchored 4 sections,- run-b anchored 2, run-c anchored 3; each sub-run contributed- grafts to every section")- - `grafts_applied`: count- - `dedup_count`: count- - `sources_unified`: count (post-reconciliation)- - `combined_source_target_met`: bool- - Any critical issues the orchestrator should surface to the user- - One-sentence summary of how the fused draft outperforms any- single sub-run (e.g., "16 unique citations pulled from run-b's- citation-chain rabbit holes, 5 schema reproductions grafted from- run-a's primary-source quotes, 3 dialectical sections restored- from run-c")--## Merger failure fallback — MANDATORY--If you cannot complete the merge for any reason (context overflow,-splice produces incoherent output, write error, scaffold-gospel-mismatch, unclean sub-run audit), do this INSTEAD of writing a-merged draft:--1. Append a `mode: merger-failed` entry to `parent_audit_path` with- the reason in the `criticals` array.-2. Do NOT write to `parent_final_report_path` — leave it absent. Do- NOT write a broken merged draft that the parent audit will then- grade against.-3. Return to the orchestrator with:- - `status`: failed- - `reason`: one line explaining why- - `sub_run_drafts`: the 3 per-run draft paths as valid- independently-readable artifacts:- `research/notes/final_report-run-a.md`,- `research/notes/final_report-run-b.md`,- `research/notes/final_report-run-c.md`--The 3 sub-run drafts are usable on their own — they each passed their-own audit. A merger failure means the user still has 3 drafts, not-zero drafts. The orchestrator will surface this to the user.--## Hard rules--- **No claim in the merged report without traceability.** Every- sentence with a factual claim must either already live in one of- the three sub-run drafts, OR be directly supported by an extract- note from one of the three sub-runs (via its per-run tag). No- training-data claims. No merger speculation. No filler prose.-- **Fusion, not base-plus-splice.** There is no "base draft". Every- section independently picks its strongest version across the three- sub-runs as the section's spine, and grafts unique material from- the other two. Different sections will have different spines —- that is correct and expected. A run-c-anchored "Connections"- section followed by a run-a-anchored "Differences" section is the- target, not a failure mode.-- **Thesis emergence, not thesis preservation.** If 2 or 3 sub-runs- committed to the same thesis or recommendation, that is the fused- report's thesis. If all three diverge, pick the thesis with the- strongest per-section specificity scores (most direct quotes, most- primary-source citations, most committed language) AND surface the- disagreement in the modality's dialectical section (tension /- counter-position / bear-case / alternatives-considered).-- **Verbatim prompt section is frozen.** If the draft has a- "User Prompt (VERBATIM — gospel)" section, it is the same verbatim- prompt that appeared in all three scaffolds. Do not edit,- paraphrase, or omit it.-- **Per-run tag discipline on extract reads.** When you read an- extract during fusion evaluation, pull it via the per-run tag —- never attribute a run-a extract as evidence in a run-b graft.-- **Structural plan is authoritative.** The H2 set in the merged- report exactly matches the unified structural plan from Step 5.- No H2 outside the plan. No scaffold-named item dropped. If an- atomic item had no coverage in any sub-run, write a one-paragraph- gap-acknowledgment section rather than silently dropping it.-- **Grafts are whole paragraphs or natural subsections.** Never- single sentences. Sentence-level grafts produce Frankenstein prose- and lose context that made the original claim credible.-- **Citation reconciliation is non-negotiable.** Step 9 runs- deterministically. Every listed source has at least one inline- citation. Every inline citation resolves to a listed source. No- ghost references.-- **The merged draft must pass its own Step 11 audit.** The- orchestrator runs conformance + comprehensiveness audits on the- merged draft after you return. Write the merge with those audits- in mind — modality conformance rules still apply.-- **Keep the summary return tight.** The orchestrator reads your- return to decide whether to surface merge issues to the user. Long- returns hide signal. Numbers + one-liners.+ ]+}}+```++**`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`.++## Severity scale++- **`critical`** — an atomic item the prompt explicitly named is+ entirely missing from the draft, OR the draft uses a fundamentally+ wrong format (prompt asked for a ranked list; draft is unranked+ prose). This must be fixed before ship.+- **`major`** — an item is present but under-covered (a paragraph where+ the prompt implied a dedicated section), OR the order is scrambled+ (prompt named A then B then C; draft does B, A, C), OR a+ recommendation the prompt asked for is abstract where the evidence+ supports specificity.+- **`minor`** — item is present and adequate, but a specific phrasing+ or sub-bullet the prompt implied is missing; low-leverage.++## Prescriptive-specificity check (failure_mode: `vague-recommendation`)++When the prompt asks for recommendations, frameworks, rules, or+guidelines, the draft's responses must include **specific thresholds,+numbers, time windows, percentages, or named mechanisms** whenever the+evidence in the vault supports them. Abstract recommendations read as+LLM-directional prose; specific recommendations read as expert+argument. This distinction is the largest single gap between+agent-generated reports and PhD-quality reference answers.++For every recommendation-shaped claim in the draft, check:++1. Does the claim have a specific threshold? ("below 10 seconds",+ "above 60 mph", "L3 within ODD")+2. Does it name a specific mechanism? ("rebuttable presumption",+ "strict liability", "24-hour OTA notification")+3. Does it cite specific numbers? ("30—60s pre-crash", "80% of L3+ accidents", "six-month sunset")++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.++Example finding:++```json+{{+ "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",+ "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."+ }}+}}+```++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+doesn't try to fabricate a number.++## Rules++- **At most 12 findings.** 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.+- **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`.++## Reporting back++Tell the orchestrator:+- Path to findings JSON+- Count by severity+- Any structural-format mismatches that cannot be patched (these need+ orchestrator-level restructure, not Layer 6)++## Why this critic exists++Instruction-following is the dimension where the pipeline has the widest+variance — strong when the draft structurally mirrors the prompt, weak+when it reorganizes around the orchestrator's own analytical axes. This+critic targets that gap directly: every atomic item the user named is+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.+# ---------------------------------------------------------------------------+PATCHER_AGENT = """\+---+name: hyperresearch-patcher+description: >+ Use this agent in Layer 6 of the layercake protocol. 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+tools: Read, Edit+color: orange+---++You are the patcher. **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 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).+After you: Layer 7 (polish auditor, also tool-locked `[Read, Edit]`).++You are the ONE step in the pipeline that modifies the draft's substance.+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++If a finding would require rewriting a whole section, **reject the+finding**. Write a note back to the orchestrator saying the finding was+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+ 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.++## 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.+ The research_query wins.+- **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.++## 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.++ **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)"}}+ ]+}}+```++## 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.+- **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.++## Integrate, don't caveat++When a critic finding is about counter-evidence the draft missed, you+have two ways to patch it. Prefer the first; reject the second:++- **Integrate by scoping the claim.** The existing claim is probably+ too broad. Narrow it with the counter-evidence's domain or+ condition. Example: draft says "X is true." Counter-evidence says+ "X is false in China because Y." Good patch: "X holds in Europe+ and North America; in China, Y creates a different regime in which+ X does not apply [N]." This turns the counter-evidence into a+ scope bound on the claim — the thesis gets sharper, not weaker.++- **Append-as-caveat (BAD).** Draft says "X is true." Patch appends+ "though this may resolve differently in other regimes." This adds+ hedge words to a claim that was previously committed. It reads as+ backpedaling, it makes the claim less specific, and the polish+ auditor will strike the hedge anyway. Avoid this pattern.++The difference in one sentence: integrate-by-scoping tells the reader+*where and why* the claim is true; append-as-caveat tells the reader+*that the writer is no longer sure*. The first strengthens insight;+the second weakens it. A draft that shifts from "X is true"+→ "X is true in scope A; Y is true in scope B because Z" has gained+argumentative density. A draft that shifts from "X is true" → "X may+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.++## Reporting back++Tell the orchestrator:+- How many findings were applied, skipped, conflicted+- Path to the patch log+- Any severity-critical finding that could not be applied (this blocks+ the pipeline — orchestrator must resolve)"""-# Subagent definition for Claude Code — uses haiku for cheap URL fetching+# ---------------------------------------------------------------------------+# Layer 7 — polish auditor. Read + Edit ONLY. Cuts fat, checks readability,+# enforces prompt adherence, strips hygiene leaks.+# ---------------------------------------------------------------------------+POLISH_AUDITOR_AGENT = """\+---+name: hyperresearch-polish-auditor+description: >+ Use this agent in Layer 7 of the layercake protocol. 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+tools: Read, Edit+color: yellow+---++You are the polish auditor. Last pass before the draft ships.+**Tool-locked: Read + Edit only.** Same patching invariant as the patcher+— you cannot regenerate; you can only apply small surgical hunks.++## Pipeline position++You are **Layer 7** — the final step of the 7-phase layercake 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+findings in it. Your job: final hygiene + readability pass.++After you finish, the report ships. There is no layer after you. If you+find a structural problem this hunk pass cannot fix, escalate — do not+attempt it yourself.++## Inputs (from the parent agent)++- **research_query**: the user's original question, verbatim. GOSPEL.+ Use it to check prompt adherence — does the final draft actually+ deliver what the user asked for? Mismatches go in `escalations`, not+ fabricated-content patches.+- **draft_path**: the post-patcher draft.+- **polish_log_path**: path to a PRE-EXISTING empty-stub polish log+ (e.g., `research/polish-log.json`). The orchestrator creates this+ stub before spawning you, with content+ `{{"applied": [], "escalations": []}}`. You populate it via Edit+ (same pattern as the patcher). You cannot Write a new file — your+ tool lock is `[Read, Edit]` only. If the stub is missing when you+ arrive, STOP and report back so the orchestrator can re-stub and+ retry.++## What you check++### 1. Hygiene leaks (strip immediately)++The draft MUST NOT contain any of these scaffold-only sections — they+are planning artifacts that leaked from the orchestrator's scratch work:++{scaffold_only_sections}++Also strip:+- YAML frontmatter at the top of the file (the `---\\n...\\n---\\n` block)+- 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++Every leak is a **critical** polish fix. Apply as an Edit that removes+the offending block entirely.++### 1a. Frontmatter hygiene (YAML metadata block)++If the file keeps a YAML frontmatter block (some wrappers require it),+fix these specific failures — they are reader-visible metadata that+graders and downstream consumers see:++- `title: Untitled` — the note-creation helper did not pick up a real+ 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+ 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.+- `summary:` ending in `...` (truncated) — rewrite to a complete+ one-sentence description of the report's thesis.++If the entire frontmatter block is safe to remove (no wrapper requires+it), prefer stripping it. If a wrapper requires it, fix the fields+above in place.++### 1b. Inline scaffold vocabulary strip (reader-facing prose)++Section 1 covers scaffold section HEADERS. This rule catches inline+leaks in body prose — pipeline-internal vocabulary that bled into+reader-facing sentences. Audits of past runs found 13 of 15 reports+containing at least one of these terms in the body text; graders see+them as self-referential process talk and score them down on+readability and instruction-following.++Apply **semantic rewrite Edits** (not literal substitutions) when you+see any of these patterns in reader-facing prose:++| Pattern (regex) | Rewrite strategy |+|---|---|+| `\\bLocus\\s+\\d+\\b` | Name the substantive topic that locus covered. E.g., "Locus 3" → "the 500K-passenger threshold question" |+| `\\bTension\\s+\\d+\\b` | Describe the actual dynamic. E.g., "Tension 2" → "the isolation-versus-competition question" |+| `comparisons\\.md` / `research/comparisons\\.md` | Delete the file-path reference; preserve the substantive sentence |+| `committed\\s+(reading\\|position)` | "the argument this report commits to" or just delete and let the following sentence stand |+| `cross[- ]locus` | "across the evidence clusters" or drop and state the substance directly |+| `\\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 |++**Special case for `\\bloci\\b` as a free-standing word:** some domains+(molecular biology, law, neuroscience) use "locus/loci" as legitimate+domain nouns. Only strip/rewrite "loci" when it refers to the+pipeline's internal taxonomy of investigator outputs (e.g., "three+loci converge", "the fidelity locus", "across loci"). When the+surrounding phrase uses "locus" in its domain sense (e.g., "genetic+locus", "legal locus"), leave it alone.++**Worked examples** (from real past-run drafts):++- Original: "This is Tension 2 from `research/comparisons.md`, engaged directly: the subsidy-ROI evidence complicates the catchment-leakage thesis."+ Rewrite: "The subsidy-ROI evidence complicates the catchment-leakage thesis."++- Original: "Three separate loci converge on the same methodological failure mode."+ Rewrite: "Three separate lines of inquiry converge on the same methodological failure mode."++- Original: "Locus 1 commits: the post-2015 decline stalled."+ 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.++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++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:++- 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]`.++### 2. Prompt adherence++Read the research_query. Does the draft actually deliver what was asked?+Flag mismatches:+- User asked for N items, draft covers fewer → add a qualifier noting+ the scope limit (do NOT invent items)+- User asked for a specific format (FAQ, ranked list, tabular) and the+ draft uses a different one → note the mismatch in the polish log; a+ format flip is usually too big for a polish Edit and you escalate+- User asked for a recommendation and the draft only describes → flag+ as escalation, do not fabricate a recommendation in a polish pass++### 3. Filler and redundancy++Edit out filler phrases where they add no information:+- "It is worth noting that..."+- "Importantly, ..."+- "It should be mentioned that..."+- "Notably, ..."+- "Of course, ..."+- "In essence, ..."++Edit out sentences that restate the prior sentence. If a paragraph ends+with a sentence that summarizes what the prior two sentences said, the+summary sentence usually goes.++### 3a. Hedge language that softens committed claims++The draft upstream was built to commit to positions. If the patcher+or any earlier layer added hedging verbs that soften a claim the+paragraph already supports with evidence, strike the hedge. This is+one of the highest-leverage cuts you can make — hedging dilutes the+argumentative density that generates insight scoring.++Watch for these softeners, in context where the surrounding evidence+would support a stronger claim:++- **`suggests that`** when used to introduce a conclusion the cited+ evidence already supports directly. "Data X suggests Y" → "Data X+ shows Y" (or just delete "suggests that" entirely if the next+ clause is already assertive).+- **`may`, `might`, `could`** used to hedge a conclusion the+ paragraph has already made. "The evidence *may* indicate..." →+ "The evidence indicates..." when the evidence is in the same+ sentence or paragraph. Keep the hedge only when the claim is+ genuinely speculative (no evidence cited, or cited evidence does+ not fully support the claim).+- **`appears to`, `seems to`, `tends to`** — same pattern. If the+ surrounding citations support the claim, drop the softener. "X+ tends to cause Y [3][5]" → "X causes Y [3][5]".+- **Appended caveats that dilute rather than scope.** If a sentence+ makes a committed claim and then appends "though this may resolve+ differently in other regimes" WITHOUT naming the other regime and+ the reason it differs, that caveat is hedge-shaped weakening.+ Either delete it (if the claim is strong enough to stand) or+ escalate to the orchestrator noting the claim may need scoping —+ but do not leave a bare "may be different" hedge on the draft.++Do NOT strike hedges on genuinely speculative claims (forecasts+without data, open questions, places where the underlying evidence+is contested). The rule is: if the same paragraph provides evidence+that supports the stronger claim, the hedge is filler and should go.+If the evidence is absent or weak, the hedge is honesty and should+stay.++### 4. Repetitive sections++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.++### 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++## Procedure++1. Read the draft end to end. Note every issue against the five+ categories above.+2. For each issue, compose an Edit hunk. Keep it surgical (change as+ little as possible while addressing the issue). Polish edits are+ almost always NEGATIVE in net chars — you are cutting, not adding.+3. Apply Edits in order: hygiene first (critical), then prompt-adherence+ tweaks (major), then filler and redundancy (minor), then readability+ breaks (minor).+4. Populate the pre-stubbed polish log via Edit. The orchestrator+ pre-created `polish_log_path` with content+ `{{"applied": [], "escalations": []}}`. Populate by calling Edit with+ `old_string='"applied": []'` and `new_string` set to the populated+ applied array (same pattern for escalations). You CANNOT Write. If+ the stub is missing, STOP and tell the orchestrator.++Target log schema:++```json+{{+ "applied": [+ {{"category": "hygiene", "description": "stripped YAML frontmatter", "chars_removed": 142}},+ {{"category": "filler", "description": "removed 14 instances of 'It is worth noting'", "chars_removed": 322}}+ ],+ "escalations": [+ {{"category": "prompt_adherence", "issue": "user asked for ranked list; draft is unranked prose. Recommend restructure."}}+ ]+}}+```++## Rules++- **Never fabricate content.** Polish only removes, condenses, or gently+ rephrases. Do not add claims that were not already in the draft.+- **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.+- **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.++## Reporting back++Tell the orchestrator: count of applied polish edits by category, net+char delta, list of escalations. The orchestrator decides whether to+ship or loop back for a structural fix.+"""+++# ---------------------------------------------------------------------------+# Layer 1 — fetcher. UNCHANGED from prior architecture. Single source of+# truth for URL → vault-note translation.+# ---------------------------------------------------------------------------RESEARCHER_AGENT = """\---name: hyperresearch-fetcher@@ -1668,6 +1647,7 @@ If given multiple URLs and fetching works, process them sequentially. Report resKeep your responses short — just the facts. The parent agent will synthesize."""+# The hook script that gets installedHOOK_SCRIPT_TEMPLATE = """\#!/usr/bin/env node@@ -1711,20 +1691,31 @@ 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."""+ """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),+ 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_ensemble_skill(vault_root),+ lambda: _install_layercake_skill(vault_root),lambda: _install_researcher_agent(vault_root, hpr_path),- lambda: _install_analyst_agent(vault_root, hpr_path),- lambda: _install_auditor_agent(vault_root, hpr_path),- lambda: _install_rewriter_agent(vault_root, hpr_path),- lambda: _install_subrun_agent(vault_root, hpr_path),- lambda: _install_merger_agent(vault_root, hpr_path),+ lambda: _install_loci_analyst_agent(vault_root, hpr_path),+ lambda: _install_depth_investigator_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: _prune_retired_agents(vault_root),):result = installer()if result:@@ -1738,7 +1729,6 @@ def _write_hook_script(vault_root: Path, hpr_path: str) -> Path:hook_dir = vault_root / ".hyperresearch"hook_dir.mkdir(parents=True, exist_ok=True)hook_path = hook_dir / "hook.js"- # Escape backslashes for JS string literaljs_path = hpr_path.replace("\\", "\\\\")hook_path.write_text(HOOK_SCRIPT_TEMPLATE.format(hpr_path=js_path), encoding="utf-8")return hook_path@@ -1762,14 +1752,12 @@ def _install_claude_hook(vault_root: Path, hpr_path: str) -> str | None:hooks = settings.setdefault("hooks", {})pre_tool = hooks.setdefault("PreToolUse", [])- # Check if already installedfor entry in pre_tool:if isinstance(entry, dict):for h in entry.get("hooks", []):if "hyperresearch" in h.get("command", ""):- return None # Already installed+ return None- # Add hook that fires before web-related toolspre_tool.append({"matcher": "Glob|Grep|WebSearch|WebFetch","hooks": [{@@ -1782,114 +1770,169 @@ def _install_claude_hook(vault_root: Path, hpr_path: str) -> str | None:return "Claude Code: .claude/settings.json (PreToolUse hook)"-def _install_researcher_agent(vault_root: Path, hpr_path: str) -> str | None:- """Install the hyperresearch-fetcher subagent for Claude Code."""+def _write_agent_file(+ vault_root: Path,+ filename: str,+ content: str,+ label: str,+) -> str | None:+ """Install a subagent file, returning the install message or None if unchanged."""agents_dir = vault_root / ".claude" / "agents"agents_dir.mkdir(parents=True, exist_ok=True)- agent_path = agents_dir / "hyperresearch-fetcher.md"-- # Use forward slashes for bash compatibility on Windows- hpr_posix = hpr_path.replace("\\", "/")- content = RESEARCHER_AGENT.format(hpr_path=hpr_posix)+ agent_path = agents_dir / filename- # Always overwrite to keep in sync with latest versionif agent_path.exists():existing = agent_path.read_text(encoding="utf-8")if existing == content:return Noneagent_path.write_text(content, encoding="utf-8")- return "Claude Code: .claude/agents/hyperresearch-fetcher.md (haiku research agent)"-+ return f"Claude Code: .claude/agents/{filename} ({label})"-def _install_analyst_agent(vault_root: Path, hpr_path: str) -> str | None:- """Install the hyperresearch-analyst subagent for Claude Code."""- agents_dir = vault_root / ".claude" / "agents"- agents_dir.mkdir(parents=True, exist_ok=True)- agent_path = agents_dir / "hyperresearch-analyst.md"+def _install_researcher_agent(vault_root: Path, hpr_path: str) -> str | None:hpr_posix = hpr_path.replace("\\", "/")- content = ANALYST_AGENT.format(hpr_path=hpr_posix)-- if agent_path.exists():- existing = agent_path.read_text(encoding="utf-8")- if existing == content:- return None-- agent_path.write_text(content, encoding="utf-8")- return "Claude Code: .claude/agents/hyperresearch-analyst.md (sonnet source analyst)"-+ content = RESEARCHER_AGENT.format(hpr_path=hpr_posix)+ return _write_agent_file(+ vault_root, "hyperresearch-fetcher.md", content, "haiku fetcher"+ )-def _install_auditor_agent(vault_root: Path, hpr_path: str) -> str | None:- """Install the hyperresearch-auditor subagent for Claude Code."""- agents_dir = vault_root / ".claude" / "agents"- agents_dir.mkdir(parents=True, exist_ok=True)- agent_path = agents_dir / "hyperresearch-auditor.md"+def _install_loci_analyst_agent(vault_root: Path, hpr_path: str) -> str | None:hpr_posix = hpr_path.replace("\\", "/")- content = AUDITOR_AGENT.format(hpr_path=hpr_posix)+ content = LOCI_ANALYST_AGENT.format(hpr_path=hpr_posix)+ return _write_agent_file(+ vault_root, "hyperresearch-loci-analyst.md", content, "sonnet loci analyst"+ )- if agent_path.exists():- existing = agent_path.read_text(encoding="utf-8")- if existing == content:- return None-- agent_path.write_text(content, encoding="utf-8")- return "Claude Code: .claude/agents/hyperresearch-auditor.md (opus adversarial auditor)"---def _install_rewriter_agent(vault_root: Path, hpr_path: str) -> str | None:- """Install the hyperresearch-rewriter subagent for Claude Code."""- agents_dir = vault_root / ".claude" / "agents"- agents_dir.mkdir(parents=True, exist_ok=True)- agent_path = agents_dir / "hyperresearch-rewriter.md"+def _install_depth_investigator_agent(vault_root: Path, hpr_path: str) -> str | None:hpr_posix = hpr_path.replace("\\", "/")- content = REWRITER_AGENT.format(hpr_path=hpr_posix)-- if agent_path.exists():- existing = agent_path.read_text(encoding="utf-8")- if existing == content:- return None-- agent_path.write_text(content, encoding="utf-8")- return "Claude Code: .claude/agents/hyperresearch-rewriter.md (sonnet evidence-recovery rewriter)"+ content = DEPTH_INVESTIGATOR_AGENT.format(hpr_path=hpr_posix)+ return _write_agent_file(+ vault_root,+ "hyperresearch-depth-investigator.md",+ content,+ "sonnet depth investigator",+ )-def _install_subrun_agent(vault_root: Path, hpr_path: str) -> str | None:- """Install the hyperresearch-subrun subagent for Claude Code."""- agents_dir = vault_root / ".claude" / "agents"- agents_dir.mkdir(parents=True, exist_ok=True)- agent_path = agents_dir / "hyperresearch-subrun.md"-+def _install_dialectic_critic_agent(vault_root: Path, hpr_path: str) -> str | None:hpr_posix = hpr_path.replace("\\", "/")- content = SUBRUN_AGENT.format(hpr_path=hpr_posix)+ content = DIALECTIC_CRITIC_AGENT.format(hpr_path=hpr_posix)+ return _write_agent_file(+ vault_root,+ "hyperresearch-dialectic-critic.md",+ content,+ "opus dialectic critic",+ )- if agent_path.exists():- existing = agent_path.read_text(encoding="utf-8")- if existing == content:- return None- agent_path.write_text(content, encoding="utf-8")- return "Claude Code: .claude/agents/hyperresearch-subrun.md (sonnet ensemble sub-run)"+def _install_depth_critic_agent(vault_root: Path, hpr_path: str) -> str | None:+ hpr_posix = hpr_path.replace("\\", "/")+ content = DEPTH_CRITIC_AGENT.format(hpr_path=hpr_posix)+ return _write_agent_file(+ vault_root,+ "hyperresearch-depth-critic.md",+ content,+ "opus depth critic",+ )-def _install_merger_agent(vault_root: Path, hpr_path: str) -> str | None:- """Install the hyperresearch-merger subagent for Claude Code."""- agents_dir = vault_root / ".claude" / "agents"- agents_dir.mkdir(parents=True, exist_ok=True)- agent_path = agents_dir / "hyperresearch-merger.md"-+def _install_width_critic_agent(vault_root: Path, hpr_path: str) -> str | None:hpr_posix = hpr_path.replace("\\", "/")- content = MERGER_AGENT.format(hpr_path=hpr_posix)-- if agent_path.exists():- existing = agent_path.read_text(encoding="utf-8")- if existing == content:- return None+ content = WIDTH_CRITIC_AGENT.format(hpr_path=hpr_posix)+ return _write_agent_file(+ vault_root,+ "hyperresearch-width-critic.md",+ content,+ "opus width critic",+ )+++def _install_instruction_critic_agent(vault_root: Path, hpr_path: str) -> str | None:+ # Instruction-critic prompt has no {hpr_path} placeholder currently,+ # but the .format() call is harmless — it leaves the text untouched.+ content = INSTRUCTION_CRITIC_AGENT+ return _write_agent_file(+ vault_root,+ "hyperresearch-instruction-critic.md",+ content,+ "opus instruction critic",+ )+++def _install_patcher_agent(vault_root: Path, hpr_path: str) -> str | None:+ # Patcher prompt does not reference hpr_path, but format is harmless+ content = PATCHER_AGENT+ return _write_agent_file(+ vault_root, "hyperresearch-patcher.md", content, "sonnet patcher (Read+Edit only)"+ )+++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="- "),+ )+ return _write_agent_file(+ vault_root,+ "hyperresearch-polish-auditor.md",+ content,+ "sonnet polish auditor (Read+Edit only)",+ )+++# Files that were installed by the pre-layercake 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, ...] = (+ "hyperresearch-analyst.md",+ "hyperresearch-auditor.md",+ "hyperresearch-rewriter.md",+ "hyperresearch-subrun.md",+ "hyperresearch-merger.md",+)++_RETIRED_SKILL_DIRS: tuple[str, ...] = (+ "research-ensemble",+)+++def _prune_retired_agents(vault_root: Path) -> str | None:+ """Delete agent files + skill dirs from the pre-layercake 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.+ """+ pruned: list[str] = []- agent_path.write_text(content, encoding="utf-8")- return "Claude Code: .claude/agents/hyperresearch-merger.md (opus ensemble merger)"+ agents_dir = vault_root / ".claude" / "agents"+ if agents_dir.exists():+ for name in _RETIRED_AGENT_FILES:+ p = agents_dir / name+ if p.exists():+ p.unlink()+ pruned.append(f"agent {name}")++ skills_dir = vault_root / ".claude" / "skills"+ if skills_dir.exists():+ for name in _RETIRED_SKILL_DIRS:+ p = skills_dir / name+ if p.is_dir():+ for child in p.iterdir():+ if child.is_file():+ child.unlink()+ elif child.is_dir():+ # Should not happen — skills are flat — but be safe+ import shutil+ shutil.rmtree(child)+ p.rmdir()+ pruned.append(f"skill dir {name}")++ if not pruned:+ return None+ return "Pruned retired: " + ", ".join(pruned)_SKILL_FILES = [@@ -1959,21 +2002,18 @@ def _install_research_skill(vault_root: Path) -> str | None:return f"Claude Code: .claude/skills/hyperresearch/ ({'; '.join(parts)})"-def _install_ensemble_skill(vault_root: Path) -> str | None:- """Install the /research-ensemble skill as its own Claude Code skill directory.+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-ensemble/SKILL.md` (NOT as a sibling+ Must live at `.claude/skills/research-layercake/SKILL.md` (NOT as a siblinginside `.claude/skills/hyperresearch/`) so Claude Code registers- `/research-ensemble` as a real slash-command trigger via the skill's- `name: research-ensemble` frontmatter. A file at- `.claude/skills/hyperresearch/SKILL-ensemble.md` is just an extra file in- the hyperresearch skill's directory — the harness does not register it as- a separate skill, so users typing `/research-ensemble` get no routing.+ `/research-layercake` as a real slash-command trigger via the skill's+ `name: research-layercake` frontmatter."""- skill_dir = vault_root / ".claude" / "skills" / "research-ensemble"+ skill_dir = vault_root / ".claude" / "skills" / "research-layercake"skill_dir.mkdir(parents=True, exist_ok=True)- content = _read_skill_source("research-ensemble.md")+ content = _read_skill_source("research-layercake.md")if content is None:return None@@ -1982,4 +2022,4 @@ def _install_ensemble_skill(vault_root: Path) -> str | None:return Nonedest_path.write_text(content, encoding="utf-8")- return "Claude Code: .claude/skills/research-ensemble/SKILL.md (/research-ensemble trigger)"+ return "Claude Code: .claude/skills/research-layercake/SKILL.md (/research-layercake trigger)"diff --git a/src/hyperresearch/core/migrations.py b/src/hyperresearch/core/migrations.pyindex da3ab01..9dd3693 100644--- a/src/hyperresearch/core/migrations.py+++ b/src/hyperresearch/core/migrations.py@@ -24,6 +24,74 @@ def _migrate_v6_tier_content_type(conn: sqlite3.Connection) -> None:""")+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+ pre-v7 vaults would reject those on sync.+ """+ # Cheap pre-check: if the table already accepts 'interim', skip.+ try:+ with conn:+ conn.execute("SAVEPOINT check_interim_type")+ try:+ conn.execute(+ "INSERT INTO notes (id, title, path, type, created) "+ "VALUES ('__migrate_probe__', 'probe', '__migrate_probe__', 'interim', '1970-01-01T00:00:00Z')"+ )+ conn.execute("DELETE FROM notes WHERE id = '__migrate_probe__'")+ conn.execute("RELEASE check_interim_type")+ return # already compatible+ except sqlite3.IntegrityError:+ conn.execute("ROLLBACK TO check_interim_type")+ conn.execute("RELEASE check_interim_type")+ except sqlite3.OperationalError:+ pass++ # Rebuild the table with the expanded CHECK. Preserve all data.+ conn.executescript("""+ CREATE TABLE notes_v7 (+ 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')),+ 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 ''+ );+ """)+ # Copy preserving only columns that exist in the old table — defensive+ # against any schema drift between versions.+ 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_v7)")}+ shared = sorted(old_cols & new_cols)+ col_list = ", ".join(shared)+ conn.execute(+ f"INSERT INTO notes_v7 ({col_list}) SELECT {col_list} FROM notes"+ )+ conn.executescript("""+ DROP TABLE notes;+ ALTER TABLE notes_v7 RENAME TO notes;+ """)++MIGRATIONS: dict[int, str | Callable[[sqlite3.Connection], None]] = {2: """CREATE TABLE IF NOT EXISTS tag_aliases (@@ -66,6 +134,7 @@ CREATE INDEX IF NOT EXISTS idx_assets_type ON assets(type);-- New vaults won't have them. No structural changes needed.""",6: _migrate_v6_tier_content_type,+ 7: _migrate_v7_interim_note_type,}diff --git a/src/hyperresearch/models/note.py b/src/hyperresearch/models/note.pyindex f2a7770..5a78f64 100644--- a/src/hyperresearch/models/note.py+++ b/src/hyperresearch/models/note.py@@ -23,6 +23,7 @@ class NoteType(StrEnum):RAW = "raw"INDEX = "index"MOC = "moc"+ INTERIM = "interim" # layercake depth-investigator output (Layer 3)class Tier(StrEnum):diff --git a/src/hyperresearch/skills/research-collect.md b/src/hyperresearch/skills/research-collect.mdindex fe2b2cc..e6cd8e1 100644--- a/src/hyperresearch/skills/research-collect.md+++ b/src/hyperresearch/skills/research-collect.md@@ -119,7 +119,7 @@ When the auditor runs in conformance mode on a collect draft, it applies these c(4) **Provenance chain.** Run `$HPR lint --rule provenance -j`. FAIL if any `--suggested-by` issues.-(5) **Analyst coverage.** Run `$HPR lint --rule analyst-coverage -j`. FAIL if the extract:source ratio is below 30%.+(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.diff --git a/src/hyperresearch/skills/research-compare.md b/src/hyperresearch/skills/research-compare.mdindex 5eec0b0..8adeb16 100644--- a/src/hyperresearch/skills/research-compare.md+++ b/src/hyperresearch/skills/research-compare.md@@ -164,7 +164,7 @@ If the entities have dramatically different maturity (A has 10 years of producti(9) **Provenance chain.** Run `$HPR lint --rule provenance -j`. FAIL if any issues.-(10) **Analyst coverage.** Run `$HPR lint --rule analyst-coverage -j`. FAIL if below 30%.+(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.diff --git a/src/hyperresearch/skills/research-ensemble.md b/src/hyperresearch/skills/research-ensemble.mddeleted file mode 100644index bf0a281..0000000--- a/src/hyperresearch/skills/research-ensemble.md+++ /dev/null@@ -1,508 +0,0 @@-----name: research-ensemble-description: >- Ensemble research mode. Trades ~5x cost for one unified report that- integrates three parallel sub-runs on the SAME shared vault, each with- a subtly different framing that drives natural divergence in what they- fetch and emphasize. Opus orchestrates, spawns three Sonnet sub-runs- (breadth / depth / dialectical), and then spawns an Opus merger that- compiles the final report on comprehensiveness, readability, argument- strength, and citation quality. Use when depth-of-corpus and- argument-stability matter more than wall-clock time.------# Research Ensemble Protocol--> You are the ensemble orchestrator. Your job is to run the `/research`-> protocol THREE TIMES in parallel against the SAME shared vault, each-> with a subtly different framing, then spawn a merger subagent that-> unifies the three drafts into one final report. The user's verbatim-> prompt is GOSPEL — identical across all three sub-runs, never altered.-> The three "framings" are private lenses the sub-runs use to bias-> discovery and analysis; they never enter the scaffolds or the drafts.--**This is the ensemble skill. It's SEPARATE from `/research`.** The user-typed `/research-ensemble` specifically because they want the 3-way-compound reading. Do not convert to single-run; do not abort to-`/research` without orchestrator-level failure.--**Cost disclosure to the user — required, early.** Before you do real-work, tell the user: "Ensemble mode costs ~5x a normal `/research` run-(3 parallel sub-runs + merger + post-merger audit). Each sub-run-targets 25+ fetches; combined corpus aims for 50+ sources. Takes-longer and costs more, but produces a noticeably deeper report."-------## Step 0: The same clarify-if-vague rule as `/research`--If the prompt is ambiguous enough that three sub-runs might diverge-on WHAT the user is asking (not just HOW), ask ONE clarifying-question before proceeding. Ambiguity in scope destroys the ensemble-— three sub-runs on three different interpretations of the prompt-cannot be merged. Ambiguity in approach is fine; the ensemble-exploits that.--If the prompt is already clear, skip this step and proceed.-------## Step 1: Classify the prompt ONCE (not per-sub-run)--Read `.claude/skills/hyperresearch/SKILL.md` Step 1 — run the same-classification logic to pick a primary modality (`collect`,-`synthesize`, `compare`, `forecast`) and optional secondary flavor.--**Classification is done ONCE.** All three sub-runs use the SAME-modality and secondary flavor. If sub-runs reclassify individually,-they produce structurally-incomparable drafts and the merger has-nothing to splice.--Record the classification — you will pass it to every sub-run spawn.-------## Step 2: Capture the verbatim prompt as gospel--Store the user's verbatim prompt (character-for-character, no edits)-in a TodoWrite entry or a scratch note. This is what you pass into-every sub-run's `research_query` parameter. The merger verifies all-three sub-run scaffolds contain this text IDENTICALLY; any drift-halts the merge.--Do not paraphrase. Do not "clean up" whitespace. Do not strip-punctuation. Copy exactly.-------## Step 3: Auto-archive prior ensemble artifacts--Before spawning any sub-run, check whether the vault has leftover-per-run files from a previous ensemble attempt:--```bash-ls research/notes/final_report-run-*.md 2>/dev/null-ls research/notes/scaffold-run-*.md 2>/dev/null-ls research/notes/comparisons-run-*.md 2>/dev/null-ls research/audit_findings-run-*.json 2>/dev/null-ls research/notes/final_report.md 2>/dev/null-```--If ANY of these exist, auto-archive them to-`research/archive/ensemble-<ISO-timestamp>/` and log the path. Do NOT-halt and ask the user — ensemble retries after an interrupted run are-common enough that friction on this path is a real nuisance. The-archive preserves the prior artifacts if the user wants them; the-ensemble proceeds cleanly.--Implementation:--```bash-TIMESTAMP=$(date -u +%Y-%m-%dT%H%M%SZ)-ARCHIVE=research/archive/ensemble-$TIMESTAMP-mkdir -p $ARCHIVE-# Move every prior per-run artifact, plus the prior merged report.-mv research/notes/final_report-run-*.md $ARCHIVE/ 2>/dev/null-mv research/notes/scaffold-run-*.md $ARCHIVE/ 2>/dev/null-mv research/notes/comparisons-run-*.md $ARCHIVE/ 2>/dev/null-mv research/audit_findings-run-*.json $ARCHIVE/ 2>/dev/null-mv research/notes/final_report.md $ARCHIVE/ 2>/dev/null-# Sync to de-index the moved notes.-$HPR sync -j-```--Tell the user once: "Auto-archived prior ensemble artifacts to-`research/archive/ensemble-<timestamp>/`." Then proceed. Source notes-and extracts stay in `research/notes/` — they're part of the shared-vault's compounding corpus and continue to be useful for this run.-------## Step 4: Build the orchestration TODO list--Use TodoWrite to lay out the full ensemble. Do NOT spawn anything-until this list exists:--1. Clarify prompt if vague (Step 0)-2. Classify prompt once (Step 1)-3. Capture verbatim prompt (Step 2)-4. Check / archive prior artifacts (Step 3)-5. Spawn `hyperresearch-subrun` x3 in parallel (Step 5 — one per framing)-6. Wait for all 3 returns; collect artifacts + audit statuses-7. **Pre-merger gate:** read each per-run audit_findings; halt on unresolved CRITICALs (Step 6)-8. Spawn `hyperresearch-merger` (Step 7)-9. Spawn `hyperresearch-auditor` on merged draft — comprehensiveness + conformance (Step 8)-10. Apply audit fixes, re-audit if needed (Step 9)-11. Save synthesis note (Step 10)-12. Report to user (Step 11)--Mark each item `completed` only after its artifact exists AND you've-verified it with a command. Mid-orchestration crashes are recoverable-if the TODO list accurately reflects where you stopped.-------## Step 5: Spawn three `hyperresearch-subrun` agents IN PARALLEL--Each sub-run receives:-- The same verbatim `research_query` (gospel)-- A unique `run_id` — `run-a`, `run-b`, or `run-c`-- A unique `framing_nudge` — a 2-3 sentence private lens-- `minimum_fetch_target` = 25 (hard floor on this sub-run's fetches)-- The ONE classified `modality` and optional `secondary_modality`--**The three framings — copy these verbatim into spawn prompts:**--### run-a — evidentiary breadth--```-framing_nudge: Approach this with a bias toward evidentiary breadth.-Prioritize casting a wide net over going deep. Emphasize primary--source hunting, ground-truth tier (official statistics, filings,-policy text, institutional datasets), non-English sources where-regionally relevant, and named dissenting voices. When spawning-analysts, phrase their goals to maximize BREADTH of what they look-for in each source. Target as many distinct sub-topics as the prompt-touches, not depth within any single one.-```--### run-b — citation-chain depth--```-framing_nudge: Approach this with a bias toward citation-chain depth.-When reading sources, prioritize tracing their references — follow-footnote chains, fetch the originating paper not the blog post about-it, pursue the cited dataset not the summary. When spawning analysts,-phrase their goals to extract NEXT-TARGET URLS above all — a source-that cites 10 other sources is more valuable to you than a source-that concludes. Prefer fewer high-density seeds with aggressive-rabbit-hole depth over a wide flat set of shallow reads.-```--### run-c — dialectical tension--```-framing_nudge: Approach this with a bias toward dialectical tension.-Prioritize finding where domain experts disagree, where the dominant-framing is challenged, where the strongest counter-argument lives.-When running adversarial searches, use named-skeptic queries over-generic criticism. When analysts extract, tell them to flag-commentary's strongest dissent. Your scaffold and draft will still-commit to a position like any `/research` run, but your source mix-will weight the contrarian side more heavily than a default reading-would.-```--### The spawn itself--Launch all three in a single message — three parallel `Task` calls-(this is where parallelism pays off; sequential spawns waste the-whole point):--```-Spawn hyperresearch-subrun with:- research_query: <verbatim user prompt from Step 2>- run_id: run-a- framing_nudge: <the run-a text above, copied exactly>- minimum_fetch_target: 25- modality: <from Step 1>- secondary_modality: <from Step 1, or "none">--Spawn hyperresearch-subrun with:- research_query: <verbatim user prompt from Step 2>- run_id: run-b- framing_nudge: <the run-b text above>- minimum_fetch_target: 25- modality: <same>- secondary_modality: <same>--Spawn hyperresearch-subrun with:- research_query: <verbatim user prompt from Step 2>- run_id: run-c- framing_nudge: <the run-c text above>- minimum_fetch_target: 25- modality: <same>- secondary_modality: <same>-```--Each sub-run is a full `/research` protocol pass — it will take real-time (typically 10-30 minutes each, depending on the prompt's depth).-Wait for all three to complete before proceeding. The sub-runs share-the vault; their fetches deduplicate naturally via-`INSERT OR IGNORE INTO sources`; their per-run filenames and tags-keep their scaffolds, drafts, and audit files distinct.-------## Step 6: Pre-merger gate — verify all three sub-runs passed audit--Each sub-run returns a summary with `audit_status`. But trust-and--verify: read each per-run audit file directly.--For each run_id in `[run-a, run-b, run-c]`:--```bash-PYTHONIOENCODING=utf-8 $HPR lint --rule audit-gate \- --audit-file research/audit_findings-<run_id>.json -j-```--The `audit-gate` lint rule returns `pass` only when both-comprehensiveness AND conformance entries exist AND every CRITICAL-is resolved.--**If any sub-run's audit-gate fails:**--Do NOT spawn the merger. Surface to the user:--> "Sub-run `<run_id>` did not pass audit — its findings at-> `research/audit_findings-<run_id>.json` have unresolved CRITICAL-> issues. All three sub-run drafts exist at-> `research/notes/final_report-run-{a,b,c}.md` as independently-> readable artifacts. You can:-> 1. Review the unresolved findings, apply fixes to the sub-run's-> draft manually (re-spawn `hyperresearch-auditor` with the-> per-run audit path after fixes), and re-run this orchestrator.-> 2. Accept one of the passing sub-run drafts as the final report-> by copying it to `research/notes/final_report.md`.-> 3. Start the ensemble over with a refined prompt."--Halt the ensemble. The merger does NOT get spawned with known-bad-sub-run inputs.--**If all three sub-runs pass:** proceed to Step 7.-------## Step 7: Spawn `hyperresearch-merger` (ONCE)--```-Spawn hyperresearch-merger with:- research_query: <verbatim user prompt from Step 2>- run_ids: ["run-a", "run-b", "run-c"]- sub_run_artifacts: {- "run-a": {- "scaffold_path": "research/notes/scaffold-run-a.md",- "comparisons_path": "research/notes/comparisons-run-a.md",- "final_report_path": "research/notes/final_report-run-a.md",- "audit_findings_path": "research/audit_findings-run-a.json"- },- "run-b": { ... run-b paths ... },- "run-c": { ... run-c paths ... }- }- parent_final_report_path: research/notes/final_report.md- parent_audit_path: research/audit_findings.json- modality: <from Step 1>-```--The merger reads all three drafts + audits + scaffolds, scores each-on four axes, picks a base, splices in unique material from the-other two, unions the Sources sections, proofreads, and writes the-unified draft. It ALSO appends a `mode: merger` run to the parent's-`audit_findings.json` with detailed scoring per sub-run.--Wait for the merger to return. The merger's return shape:--- `status`: pass / needs_fixes / failed-- `merged_report_path`: `research/notes/final_report.md`-- `base_run`: which sub-run anchored the merge-- `splice_mode`: full / short_circuited-- `splices_applied`: integer-- `sources_unified`: integer-- `combined_source_target_met`: bool-- Any critical issues the orchestrator should surface--### Merger failure fallback--If `status` is `failed`, the merger writes a `mode: merger-failed`-entry to the parent's audit_findings.json and does NOT produce-`research/notes/final_report.md`. Surface this to the user:--> "The merger could not produce a unified draft. The three sub-run-> drafts at `research/notes/final_report-run-{a,b,c}.md` are-> independently valid artifacts — each passed its own audit. The-> merger reported: `<reason>`. You can pick the strongest sub-run-> draft, promote it to `research/notes/final_report.md`, and save-> it manually as the final report. Or re-run the ensemble."--Halt. Do not proceed to Step 8 without a merged draft.-------## Step 8: Run Step 11 audit on the merged draft (parent vault)--The merged draft is a NEW synthesis — it gets a full adversarial-audit in the parent vault's `research/audit_findings.json`, same as-a normal `/research` run would.--Spawn `hyperresearch-auditor` twice — sequentially, comprehensiveness-first then conformance:--```-First spawn (wait for completion before the second):- research_query: <verbatim user prompt from Step 2>- modality: <from Step 1>- mode: comprehensiveness- final_report_path: research/notes/final_report.md- audit_findings_path: research/audit_findings.json- scaffold_note_id: <id of run-a's scaffold note, or the base_run's>--Second spawn (after the first returns):- research_query: <verbatim user prompt from Step 2>- modality: <from Step 1>- mode: conformance- final_report_path: research/notes/final_report.md- audit_findings_path: research/audit_findings.json- scaffold_note_id: <same as above>-```--The auditor writes to the parent's audit_findings.json, which now-contains:-1. The merger's `mode: merger` entry-2. The comprehensiveness auditor's entry-3. The conformance auditor's entry-------## Step 9: Apply audit fixes, re-audit if needed--Standard fix-apply loop:-1. Read both auditor returns. For each CRITICAL, apply the fix to- `research/notes/final_report.md`. The merged draft can tolerate- small edits here — the merger's structural spine stays, but you- can add a missing citation, tighten a hedge, or expand an under-- developed prompt-named section by pulling from the per-run- extract notes (tagged with `run-a`/`run-b`/`run-c`).-2. For each fix, set the finding's `fixed_at` timestamp in the- parent's audit_findings.json.-3. If any CRITICAL cannot be resolved by editing (e.g., the merged- draft lacks evidence for a prompt-named item AND no sub-run- surfaced it), the correct fix may be to fetch new sources and- re-audit — but at this point you are doing single-run work on the- merged draft, not ensemble work.-4. Re-run `hyperresearch-auditor` (both modes) to verify the fixes- landed. The `audit-gate` lint rule checks that every CRITICAL in- the newest conformance run has `fixed_at` populated.--```bash-PYTHONIOENCODING=utf-8 $HPR lint --rule audit-gate -j-```--Must return no issues. The default `audit-gate` path is the parent's-`research/audit_findings.json` — no `--audit-file` override needed-at this step because you ARE checking the parent.-------## Step 10: Save the synthesis — standard Step 13 of `/research`--Promote the merged draft to a first-class synthesis note in the-vault. Use the same command `/research` uses:--```bash-PYTHONIOENCODING=utf-8 $HPR note new "<concise title derived from prompt>" \- --tag synthesis --tag ensemble \- --tier institutional \- --content-type synthesis \- --summary "<one-line summary of the merged conclusion>" \- --status review \- --body-file research/notes/final_report.md \- -j-```--The `audit-gate` lint rule blocks save if any CRITICAL in the latest-conformance run is unresolved — standard protection.-------## Step 11: Report to the user--Report a tight summary. What the user needs to see:--```-Ensemble research complete.--Merged final report: research/notes/final_report.md (<N> words)--Sub-run drafts (preserved for reference):-- research/notes/final_report-run-a.md (breadth, <N> words, <K> citations)-- research/notes/final_report-run-b.md (depth, <N> words, <K> citations)-- research/notes/final_report-run-c.md (dialectical, <N> words, <K> citations)--Merger picked run-<X> as base; <S> splices applied from siblings.-Combined unique sources: <N> (target was 50+).-Merged draft passed comprehensiveness + conformance audit.--Per-run audit files: research/audit_findings-run-{a,b,c}.json-Parent audit findings: research/audit_findings.json (includes merger-entry + post-merger audits)-```--If the combined source count fell short of 50, note that explicitly-— ensemble underperformed its volume target, which likely means all-three sub-runs ran out of high-signal sources in the domain (benign)-or skimped on fetching (non-benign; surface it so the user can-decide).-------## Hard rules — orchestrator scope--- **The user's prompt is gospel.** Pass it verbatim to all three- sub-runs; the merger verifies character-for-character identity- across the three scaffolds' prompt sections.-- **Classify exactly once.** All three sub-runs use the same- modality. No per-sub-run reclassification.-- **Spawn the three sub-runs in parallel, not sequentially.** Three- `Task` calls in a single message. Sequential spawning defeats- half the point.-- **Do NOT spawn the merger before verifying all three sub-run- audit-gates pass.** Bad sub-run inputs produce bad merges.-- **Do NOT write to `research/notes/final_report.md` before the- merger runs.** That path is reserved for the merged output.-- **Do NOT skip the post-merger audit.** The merged draft is a new- synthesis — it gets the same Step 11 treatment as a normal- `/research` run.-- **Do NOT silently delete per-run artifacts after merging.** The- sub-run drafts stay on disk as independently readable artifacts- — users may want to see how the three framings diverged.-- **Do NOT convert the ensemble to a single-run on sub-run failure.**- If a sub-run fails audit, halt and surface options. The user- invoked `/research-ensemble` specifically; silently degrading to- single-run is worse than explicit failure.-- **Cost disclosure is mandatory, early.** The user must know ~5x- cost before the three sub-runs start.-------## Why this design (for future maintainers)--The ensemble attacks two single-run ceilings:--1. **Variance ceiling** — three Sonnet sub-runs with subtly different- framings produce three parallel readings; compounding LLM- randomness drives natural divergence in source discovery and- emphasis. The merger picks the best-of-3 structural spine and- splices in unique evidence from the other two.--2. **Depth-of-corpus ceiling** — because all three sub-runs share ONE- unified vault, their combined fetch decisions stack into a richer- source corpus than any single run could produce. Each sub-run- pushes for 25+ of its own fetches; the shared corpus grows toward- 60+, and every sub-run sees what the others found (natural, not- forced, deduplication via `INSERT OR IGNORE`).--The unified vault is the critical architectural choice. Per-sub-run-vaults would isolate the corpora, losing the compounding-knowledge-benefit. With a shared vault, the knowledge base persists across the-ensemble and across future sessions — a long-lived asset, not a-per-run workspace.--The three framings are deliberately SUBTLE — not radical "styles".-Radical styles produce tonally incompatible drafts the merger can't-harmonize. Subtle nudges plus LLM nondeterminism produce divergent-source discovery without clashing voices; the merger's job stays-tractable.--Cost: ~5x a normal `/research` run (3 sub-runs + merger + post--merger audit + orchestrator overhead). Not 2x, not 3x. Be honest-with users.diff --git a/src/hyperresearch/skills/research-forecast.md b/src/hyperresearch/skills/research-forecast.mdindex afa06a3..fa19a7b 100644--- a/src/hyperresearch/skills/research-forecast.md+++ b/src/hyperresearch/skills/research-forecast.md@@ -154,7 +154,7 @@ The draft must include — in the body or in the synthesis — a statement of wh(9) **Provenance chain.** Run `$HPR lint --rule provenance -j`. FAIL if any issues.-(10) **Analyst coverage.** Run `$HPR lint --rule analyst-coverage -j`. FAIL if below 30%.+(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.diff --git a/src/hyperresearch/skills/research-layercake.md b/src/hyperresearch/skills/research-layercake.mdnew file mode 100644index 0000000..ffcf35a--- /dev/null+++ b/src/hyperresearch/skills/research-layercake.md@@ -0,0 +1,512 @@+---+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.mdindex 0a2f58d..73d5b77 100644--- a/src/hyperresearch/skills/research-synthesize.md+++ b/src/hyperresearch/skills/research-synthesize.md@@ -212,7 +212,7 @@ Sections build on each other. Section 2's claim depends on section 1's setup; se(8) **Provenance chain.** Run `$HPR lint --rule provenance -j`. FAIL if any issues.-(9) **Analyst coverage.** Run `$HPR lint --rule analyst-coverage -j`. FAIL if below 30%.+(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.diff --git a/src/hyperresearch/skills/research.md b/src/hyperresearch/skills/research.mdindex 342496b..d296c13 100644--- a/src/hyperresearch/skills/research.md+++ b/src/hyperresearch/skills/research.md@@ -13,7 +13,9 @@ The research protocol has ONE process spine (this file) and FOUR modality files**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 user's verbatim prompt is the only gospel in this session.** 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 prompt. Whenever the draft feels like it's drifting, re-read the prompt. The auditor at Step 11 grades the draft against the verbatim prompt — not against any abstract notion of quality.+**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.---@@ -50,22 +52,52 @@ If the vault already has >10 relevant notes: tell the user, summarize what's the----## Step 1: Classify + commit the verbatim prompt+## 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:-State your classification in writing BEFORE doing anything else. Copy the user's prompt verbatim into your working memory. This is the format you MUST output:+- 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>@@ -106,10 +138,11 @@ When two activities seem equally applicable:## Prompt fidelity — the gospel rule-**Re-read the user's verbatim prompt at every checkpoint.** The prompt is inside the scaffold (Step 7). Every checkpoint re-opens the scaffold. Every time you re-open the scaffold, re-read the prompt first. Every structural decision must trace back to the prompt or a modality default that the prompt is silent on.+**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 prompt specifies structure / format / entities / fields / ordering / scope: **the user's request is authoritative**. Modality defaults yield.-- If the prompt is silent on any of those: **the modality default applies** to what the prompt left open.+- 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.@@ -265,6 +298,19 @@ $HPR note edit <new-id> ... # tries to graft a breadcrumb after the fBackfilling 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:```@@ -377,7 +423,7 @@ For each batch of 1-5 draft source notes (semantically grouped):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 `analyst-coverage` lint rule catches both misses AND stubs at Checkpoint 2 (extracts under 150 words do NOT count — minting stubs will not satisfy the gate).+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@@ -400,7 +446,7 @@ $HPR note update <source-id> \```bash$HPR lint --rule uncurated -j # zero uncurated$HPR lint --rule provenance -j # zero provenance issues (--suggested-by chain exists)-$HPR lint --rule analyst-coverage -j # zero analyst-coverage issues+$HPR lint --rule extract-coverage -j # zero extract-coverage issues$HPR link --auto -j$HPR graph hubs -j```@@ -409,20 +455,26 @@ If any lint returns issues, curation is NOT done. Go back, run more analyst call----## Step 7: Build the scaffold — with the verbatim user prompt as the first section+## 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 user's verbatim prompt.-**Verification:** `$HPR note list --tag scaffold -j` must return ≥1 entry after this step AND the body of that note must contain the verbatim user prompt.+**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 user's entire message, copied character-for-character from the prompt.+> [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">@@ -435,7 +487,8 @@ Using the **Write tool**, create `research/scaffold.md` with this exact structur## Primary activity and secondary flavor- **Primary:** <collect | synthesize | compare | forecast>- **Secondary (optional):** <or "none">-- **Why:** <one sentence>+- **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,@@ -510,7 +563,7 @@ $HPR note new "Scaffold: <topic>" --tag scaffold --status draft \## Step 8: Cross-source comparisons-**Required artifact:** a note tagged `comparison` containing 3–5 explicit source-vs-source disagreements with your position on each.+**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.@@ -519,6 +572,16 @@ Find 3–5 places where sources disagree. Read both at Level 3+ before comparingUsing 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>@@ -537,7 +600,7 @@ $HPR note new "Comparisons: <topic>" --tag comparison --status draft \## Step 9: Write the draft-**Before writing anything:** re-open `research/scaffold.md`. Re-read the verbatim user prompt. 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 the prompt.+**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).@@ -546,16 +609,18 @@ Then read your modality file's substance rules. The modality file tells you HOW### 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 parenthetical URLs like `([Author Year](url))` or `([short source name](url))`. **The same source can and should be cited multiple times** across different sections whenever it anchors a different claim — treat each citation as an independent audit point, not a one-per-source rationing. A 5,000-word deep-research draft should carry **40-80 inline citations** (density of 8-16 per 1000 words); anything under 5 per 1000 reads as under-sourced to both human reviewers and automated judges. Shallow citation is the single most common failure mode in structured research writing.-- **Exhaustive sub-topic coverage — 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 — the RACE judge rewards visible structural separation. 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.+- **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 serves substance, not the reverse.** There is no fixed length target. BUT deep-research drafts typically run 5,000-12,000 words because exhaustive sub-topic coverage plus dense citation plus source-vs-source tension cannot fit in 2,000 words. If you find yourself at 3,000 words on a complex prompt, you are probably collapsing sections or under-citing — reconsider both.+- **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.-- **Inline citations as bracketed references AND a final Sources section.** In addition to inline parenthetical URLs, number every unique source `[1]`, `[2]`, `[3]` the first time it appears, reuse the same number on later citations, and include a `## Sources` section at the end of the draft listing `[N] Short title — URL` for every reference. This dual format (parenthetical inline + numbered footnote style + end Sources list) gives both human readers and automated reviewers a traceable audit path. Do NOT invent alternative citation formats (no unicode bracket pairs, no `†`, no author-year-only). Numbered plus final Sources list is the standard here.+- **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.@@ -563,6 +628,27 @@ Then read your modality file's substance rules. The modality file tells you HOW- **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 rulesOpen 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.@@ -575,8 +661,8 @@ 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 (Q91-style: `primary=collect`, `secondary=synthesize`):-- Collect (primary) forces per-character coverage across every entity category in the prompt. The structure is entity-based.+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).@@ -668,9 +754,35 @@ The auditor reads your modality file's "Conformance checks" section, applies eac----## Step 12: Opinionated synthesis+## 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.-Append this to the end of the draft:+### 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@@ -699,6 +811,10 @@ change your position>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@@ -787,14 +903,14 @@ for dom, count in domains.most_common(10):```bash$HPR lint --rule uncurated -j$HPR lint --rule provenance -j-$HPR lint --rule analyst-coverage -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 `analyst-coverage` issues (at least 33% of fetched sources have a paired extract note)+- [ ] 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@@ -814,7 +930,7 @@ $HPR note list --tag extract -j | python -c "import sys,json; d=json.load(sys.st$HPR lint --rule scaffold-prompt -j$HPR lint --rule uncurated -j$HPR lint --rule provenance -j-$HPR lint --rule analyst-coverage -j+$HPR lint --rule extract-coverage -j$HPR lint --rule workflow -j```@@ -823,7 +939,7 @@ $HPR lint --rule workflow -j- [ ] 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`, `analyst-coverage`, `workflow` issues+- [ ] 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.diff --git a/tests/test_cli/test_lint.py b/tests/test_cli/test_lint.pyindex 2a1352b..b6297d1 100644--- a/tests/test_cli/test_lint.py+++ b/tests/test_cli/test_lint.py@@ -98,6 +98,30 @@ def test_scaffold_prompt_warns_when_quote_too_short(tmp_vault):assert scaffold_issues[0]["severity"] == "warning"+def test_scaffold_prompt_fails_when_canonical_prompt_mismatch(tmp_vault):+ (tmp_vault.root / "research" / "prompt.txt").write_text(+ "Exact wrapped prompt text.\nSecond line.",+ encoding="utf-8",+ )+ _write_scaffold(+ tmp_vault,+ body=(+ "## User Prompt (VERBATIM — gospel)\n"+ "> Exact wrapped prompt text.\n"+ "> Second line with drift.\n\n"+ "## What the user explicitly asked for\n"+ "- thing\n"+ ),+ )+ _, out = _run_lint(tmp_vault, rule="scaffold-prompt")+ import json+ data = json.loads(out)+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "scaffold-prompt"]+ assert len(issues) == 1+ assert issues[0]["severity"] == "error"+ assert "research/prompt.txt" in issues[0]["message"]++def test_scaffold_prompt_no_scaffold_notes_is_noop(tmp_vault):# A vault with no scaffold-tagged notes should produce no issues for this rule.code, out = _run_lint(tmp_vault, rule="scaffold-prompt")@@ -109,6 +133,174 @@ def test_scaffold_prompt_no_scaffold_notes_is_noop(tmp_vault):assert scaffold_issues == []+def _write_wrapper_contract(vault, **fields):+ """Persist a research/wrapper_contract.json at the vault root."""+ import json+ (vault.root / "research" / "wrapper_contract.json").write_text(+ json.dumps(fields), encoding="utf-8",+ )+++def test_wrapper_report_requires_terminal_sections_from_wrapper_contract(tmp_vault):+ """When wrapper_contract.json declares required_terminal_sections, the+ wrapper-report rule must fail if any are missing from the final report."""+ (tmp_vault.root / "research" / "prompt.txt").write_text(+ "Exact wrapped prompt text.",+ encoding="utf-8",+ )+ _write_wrapper_contract(+ tmp_vault,+ required_terminal_sections=[+ "## Opinionated Synthesis",+ "### Concluding Thoughts",+ ],+ )+ (tmp_vault.root / "research" / "notes" / "final_report.md").write_text(+ "# Report\n\n## Body\nSome body content.\n",+ encoding="utf-8",+ )++ _, out = _run_lint(tmp_vault, rule="wrapper-report")+ import json+ data = json.loads(out)+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "wrapper-report"]+ assert len(issues) == 1+ assert issues[0]["severity"] == "error"+ assert "required_terminal_sections" in issues[0]["message"]+ assert "Opinionated Synthesis" in issues[0]["message"]+ assert "Concluding Thoughts" in issues[0]["message"]+++def test_wrapper_report_passes_when_required_sections_present(tmp_vault):+ """Wrapper contract + report with all declared sections => no issues."""+ (tmp_vault.root / "research" / "prompt.txt").write_text(+ "Exact wrapped prompt text.",+ encoding="utf-8",+ )+ _write_wrapper_contract(+ tmp_vault,+ required_terminal_sections=[+ "## Opinionated Synthesis",+ "### Concluding Thoughts",+ ],+ )+ (tmp_vault.root / "research" / "notes" / "final_report.md").write_text(+ (+ "# Report\n\n"+ "## Body\nSome body content.\n\n"+ "## Opinionated Synthesis\n\n"+ "### Concluding Thoughts\nE\n"+ ),+ encoding="utf-8",+ )++ _, out = _run_lint(tmp_vault, rule="wrapper-report")+ import json+ data = json.loads(out)+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "wrapper-report"]+ assert issues == []+++def test_wrapper_report_without_contract_only_checks_hygiene(tmp_vault):+ """With prompt.txt but no wrapper_contract.json, the rule should NOT+ flag missing terminal sections (since nothing was declared required).+ Scaffold-leak hygiene is still enforced."""+ (tmp_vault.root / "research" / "prompt.txt").write_text(+ "Exact wrapped prompt text.",+ encoding="utf-8",+ )+ (tmp_vault.root / "research" / "notes" / "final_report.md").write_text(+ "# Report\n\n## Body\nSome content, no synthesis tail.\n",+ encoding="utf-8",+ )++ _, out = _run_lint(tmp_vault, rule="wrapper-report")+ import json+ data = json.loads(out)+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "wrapper-report"]+ assert issues == []+++def test_wrapper_report_forbids_scaffold_leaks_without_contract(tmp_vault):+ """Scaffold-leak hygiene runs regardless of whether wrapper_contract.json+ declares forbidden_body_sections — the canonical base list from+ SCAFFOLD_ONLY_SECTION_HEADERS is always forbidden."""+ (tmp_vault.root / "research" / "prompt.txt").write_text(+ "Exact wrapped prompt text.",+ encoding="utf-8",+ )+ (tmp_vault.root / "research" / "notes" / "final_report.md").write_text(+ (+ "# Report\n\n"+ "## User Prompt (VERBATIM — gospel)\n"+ "> Exact wrapped prompt text.\n\n"+ "## Body\nContent.\n"+ ),+ encoding="utf-8",+ )++ _, out = _run_lint(tmp_vault, rule="wrapper-report")+ import json+ data = json.loads(out)+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "wrapper-report"]+ assert len(issues) == 1+ assert issues[0]["severity"] == "error"+ assert "leaking scaffold-only sections" in issues[0]["message"]+ assert "User Prompt (VERBATIM" in issues[0]["message"]+++def test_wrapper_report_honors_wrapper_extra_forbidden_sections(tmp_vault):+ """A wrapper can declare ADDITIONAL forbidden body sections on top of the+ canonical base list."""+ _write_wrapper_contract(+ tmp_vault,+ forbidden_body_sections=["## Internal-only scratch"],+ )+ (tmp_vault.root / "research" / "notes" / "final_report.md").write_text(+ (+ "# Report\n\n"+ "## Body\nContent.\n\n"+ "## Internal-only scratch\nLeaked note.\n"+ ),+ encoding="utf-8",+ )++ _, out = _run_lint(tmp_vault, rule="wrapper-report")+ import json+ data = json.loads(out)+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "wrapper-report"]+ assert len(issues) == 1+ assert "Internal-only scratch" in issues[0]["message"]+++def test_wrapper_report_inactive_without_signals(tmp_vault):+ """No prompt.txt, no wrapper_contract.json => rule is inactive, no issues."""+ (tmp_vault.root / "research" / "notes" / "final_report.md").write_text(+ "# Report\n\n## Body\nRegular /research output.\n",+ encoding="utf-8",+ )++ _, out = _run_lint(tmp_vault, rule="wrapper-report")+ import json+ data = json.loads(out)+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "wrapper-report"]+ assert issues == []+++def test_wrapper_report_unreadable_contract_surfaces_error(tmp_vault):+ """Malformed wrapper_contract.json produces an error rather than silently+ disabling the rule."""+ (tmp_vault.root / "research" / "wrapper_contract.json").write_text(+ "{not valid json",+ encoding="utf-8",+ )+ _, out = _run_lint(tmp_vault, rule="wrapper-report")+ import json+ data = json.loads(out)+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "wrapper-report"]+ assert any("wrapper_contract.json" in i["message"] for i in issues)++def _write_source(vault, title: str, note_id: str, body: str = "Source content."):write_note(vault.notes_dir,@@ -121,18 +313,48 @@ def _write_source(vault, title: str, note_id: str, body: str = "Source content.")-def _write_extract(vault, note_id: str, word_count_target: int, run_tag: str | None = None):- """Write an extract note with a body of roughly `word_count_target` words."""+def _write_extract(+ vault,+ note_id: str,+ word_count_target: int,+ run_tag: str | None = None,+ parent: str | None = None,+ dud: bool = False,+):+ """Write an extract note with a body of roughly `word_count_target` words.++ When `dud=True`, the extract is tagged `dud` — marking it as an honest+ "source had no extractable content" placeholder. The analyst-coverage+ lint excludes dud notes from both its numerator and denominator.+ """body = "word " * word_count_targettags = ["extract"]if run_tag:tags.append(run_tag)+ if dud:+ tags.append("dud")write_note(vault.notes_dir,f"Extract {note_id}",body=body,note_id=note_id,tags=tags,+ parent=parent,+ )+++def _write_dud_source(vault, title: str, note_id: str, body: str = "Dud source content."):+ """Write a source note that is also tagged `dud` — simulating a fetch+ that returned something but the body is genuinely unextractable."""+ write_note(+ vault.notes_dir,+ title,+ body=body,+ note_id=note_id,+ source=f"https://example.com/{note_id}",+ tier="institutional",+ content_type="article",+ tags=["dud"],)@@ -461,9 +683,9 @@ def test_audit_gate_catches_self_certification_on_provenance(tmp_vault):marked `fixed_at`, but the provenance rule still returns errors, theaudit-gate must emit a SELF-CERTIFICATION VIOLATION error.- This is exactly the Q62 failure mode — the agent marked the C1- provenance finding as fixed with a justification string, but the- vault's actual breadcrumb graph was still broken.+ This is a past self-certification failure mode — the agent marked+ the C1 provenance finding as fixed with a justification string, but+ the vault's actual breadcrumb graph was still broken."""# Build a vault where provenance is genuinely broken (12 sources, none# with breadcrumbs — classic flat batch).@@ -587,61 +809,605 @@ def test_orphaned_raw_files_ignores_matched_raw(tmp_vault):assert issues == []-def test_analyst_coverage_counts_real_extracts(tmp_vault):- """A vault with enough real extracts (>= 150 words) passes the gate."""++# ---------------------------------------------------------------------------+# locus-coverage (layercake Layer 3 — every locus must have an interim note)+# ---------------------------------------------------------------------------+++def _write_loci_json(vault, loci: list[dict]) -> None:+ """Write research/loci.json so the locus-coverage rule has something to read."""+ import json+ research_dir = vault.root / "research"+ research_dir.mkdir(parents=True, exist_ok=True)+ (research_dir / "loci.json").write_text(+ json.dumps({"loci": loci}, ensure_ascii=False, indent=2),+ encoding="utf-8",+ )+++def _write_interim(vault, locus_name: str, note_id: str | None = None) -> None:+ """Write an interim-report note for a given locus. Mimics the Layer 3+ depth-investigator output shape: type=interim, tag=locus-<name>."""+ from hyperresearch.core.note import write_note+ nid = note_id or f"interim-{locus_name}"+ write_note(+ vault.notes_dir,+ f"Interim report {locus_name}",+ body="Interim synthesis for locus.",+ note_id=nid,+ tags=["interim", f"locus-{locus_name}"],+ note_type="interim",+ )+++def test_locus_coverage_passes_when_every_locus_has_interim(tmp_vault):+ _write_loci_json(tmp_vault, [+ {"name": "alpha", "one_line": "Q1"},+ {"name": "beta", "one_line": "Q2"},+ ])+ _write_interim(tmp_vault, "alpha")+ _write_interim(tmp_vault, "beta")+ tmp_vault.auto_sync()++ _, out = _run_lint(tmp_vault, rule="locus-coverage")+ import json+ data = json.loads(out)+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "locus-coverage"]+ assert issues == []+++def test_locus_coverage_flags_missing_interim(tmp_vault):+ _write_loci_json(tmp_vault, [+ {"name": "alpha", "one_line": "Q1"},+ {"name": "beta", "one_line": "Q2"},+ {"name": "gamma", "one_line": "Q3"},+ ])+ # Only alpha got investigated; beta and gamma are orphans+ _write_interim(tmp_vault, "alpha")+ tmp_vault.auto_sync()++ _, out = _run_lint(tmp_vault, rule="locus-coverage")+ import json+ data = json.loads(out)+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "locus-coverage"]+ assert len(issues) == 1+ msg = issues[0]["message"]+ assert "2 of 3" in msg+ assert "beta" in msg+ assert "gamma" in msg+ # 2 missing -> error severity (threshold at 2)+ assert issues[0]["severity"] == "error"+++def test_locus_coverage_noop_when_no_loci_json(tmp_vault):+ """A vault from a single-pass /research run has no loci.json; the rule+ must stay silent in that case, not misfire."""+ _, out = _run_lint(tmp_vault, rule="locus-coverage")+ import json+ data = json.loads(out)+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "locus-coverage"]+ assert issues == []+++# ---------------------------------------------------------------------------+# patch-surgery (layercake Layer 6 — patcher must not skip critical findings)+# ---------------------------------------------------------------------------+++def _write_patch_log(vault, applied=None, skipped=None, conflicts=None) -> None:+ import json+ research_dir = vault.root / "research"+ research_dir.mkdir(parents=True, exist_ok=True)+ (research_dir / "patch-log.json").write_text(+ json.dumps({+ "applied": applied or [],+ "skipped": skipped or [],+ "conflicts": conflicts or [],+ }, ensure_ascii=False, indent=2),+ encoding="utf-8",+ )+++def test_patch_surgery_passes_with_clean_log(tmp_vault):+ _write_patch_log(tmp_vault, applied=[+ {"finding_id": 0, "severity": "critical", "critic": "dialectic", "chars_added": 87},+ {"finding_id": 1, "severity": "major", "critic": "depth", "chars_added": 54},+ ])+ _, out = _run_lint(tmp_vault, rule="patch-surgery")+ import json+ data = json.loads(out)+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "patch-surgery"]+ assert issues == []+++def test_patch_surgery_flags_critical_skip(tmp_vault):+ _write_patch_log(tmp_vault,+ applied=[+ {"finding_id": 0, "severity": "major", "critic": "depth", "chars_added": 50},+ ],+ skipped=[+ {"finding_id": 1, "severity": "critical", "critic": "dialectic",+ "reason": "anchor drifted"},+ ],+ )+ _, out = _run_lint(tmp_vault, rule="patch-surgery")+ import json+ data = json.loads(out)+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "patch-surgery"]+ assert len(issues) == 1+ assert issues[0]["severity"] == "error"+ assert "1 critical" in issues[0]["message"]+ assert "dialectic" in issues[0]["message"]+++def test_patch_surgery_noop_when_no_patch_log(tmp_vault):+ """Single-pass /research runs produce no patch-log.json. Rule stays silent."""+ _, out = _run_lint(tmp_vault, rule="patch-surgery")+ import json+ data = json.loads(out)+ issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "patch-surgery"]+ assert issues == []+++# ---------------------------------------------------------------------------+# workflow — comparisons.md gate for layercake runs with 2+ loci+# ---------------------------------------------------------------------------+++def test_workflow_flags_missing_comparisons_when_multiple_loci(tmp_vault):+ """2+ loci without research/comparisons.md is a Layer 3.5 skip — the+ insight-killing failure mode the cross-locus reconciliation step was+ added to prevent."""+ from hyperresearch.core.note import write_note+ # Layercake final-report signal+ write_note(+ tmp_vault.notes_dir,+ "final_report",+ body="Some draft content.",+ note_id="final_report",+ tags=["synthesis"],+ )+ # Scaffold artifact so the scaffold check passes+ (tmp_vault.root / "research" / "scaffold.md").write_text(+ "scaffold\n", encoding="utf-8"+ )+ # 2 loci, 2 interim notes — but NO comparisons.md+ _write_loci_json(tmp_vault, [+ {"name": "alpha", "one_line": "Q1"},+ {"name": "beta", "one_line": "Q2"},+ ])+ _write_interim(tmp_vault, "alpha")+ _write_interim(tmp_vault, "beta")+ tmp_vault.auto_sync()++ _, out = _run_lint(tmp_vault, rule="workflow")+ import json+ data = json.loads(out)+ issues = [+ i for i in data.get("data", {}).get("issues", [])+ if i.get("rule") == "workflow"+ ]+ comparisons_issues = [i for i in issues if "comparisons.md" in i["message"]]+ assert len(comparisons_issues) == 1+ assert comparisons_issues[0]["severity"] == "error"+ assert "2 loci" in comparisons_issues[0]["message"]+ assert "Layer 3.5" in comparisons_issues[0]["message"]+++def test_workflow_passes_with_comparisons_md(tmp_vault):+ """With comparisons.md present alongside 2+ loci, workflow rule stays silent."""+ from hyperresearch.core.note import write_note+ write_note(+ tmp_vault.notes_dir,+ "final_report",+ body="Draft.",+ note_id="final_report",+ tags=["synthesis"],+ )+ (tmp_vault.root / "research" / "scaffold.md").write_text(+ "scaffold\n", encoding="utf-8"+ )+ (tmp_vault.root / "research" / "comparisons.md").write_text(+ "# Cross-locus comparisons\n\n## Tension 1\n...", encoding="utf-8"+ )+ _write_loci_json(tmp_vault, [+ {"name": "alpha", "one_line": "Q1"},+ {"name": "beta", "one_line": "Q2"},+ ])+ _write_interim(tmp_vault, "alpha")+ _write_interim(tmp_vault, "beta")+ tmp_vault.auto_sync()++ _, out = _run_lint(tmp_vault, rule="workflow")+ import json+ data = json.loads(out)+ issues = [+ i for i in data.get("data", {}).get("issues", [])+ if i.get("rule") == "workflow" and "comparisons.md" in i["message"]+ ]+ assert issues == []+++def test_workflow_requires_comparisons_even_on_single_locus(tmp_vault):+ """Layer 3.5 is always-on: single-locus runs still produce a+ comparisons.md distilling that locus's committed position. Missing+ comparisons.md when loci >= 1 is now an error."""+ from hyperresearch.core.note import write_note+ write_note(+ tmp_vault.notes_dir,+ "final_report",+ body="Draft.",+ note_id="final_report",+ tags=["synthesis"],+ )+ (tmp_vault.root / "research" / "scaffold.md").write_text(+ "scaffold\n", encoding="utf-8"+ )+ _write_loci_json(tmp_vault, [+ {"name": "alpha", "one_line": "Q1"},+ ])+ _write_interim(tmp_vault, "alpha")+ tmp_vault.auto_sync()++ _, out = _run_lint(tmp_vault, rule="workflow")+ import json+ data = json.loads(out)+ issues = [+ i for i in data.get("data", {}).get("issues", [])+ if i.get("rule") == "workflow" and "comparisons.md" in i["message"]+ ]+ assert len(issues) == 1+ assert issues[0]["severity"] == "error"+ assert "always-on" in issues[0]["message"]+++# ---------------------------------------------------------------------------+# provenance — layercake-aware: skip breadcrumb coverage ratio checks when+# research/loci.json exists (layercake'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+ 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+ _write_loci_json(tmp_vault, [+ {"name": "alpha", "one_line": "Q"},+ {"name": "beta", "one_line": "Q"},+ ])+ tmp_vault.auto_sync()++ _, out = _run_lint(tmp_vault, rule="provenance")+ import json+ data = json.loads(out)+ issues = [+ 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}"+++def test_provenance_still_fires_coverage_check_on_non_layercake_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+ tmp_vault.auto_sync()++ _, out = _run_lint(tmp_vault, rule="provenance")+ import json+ data = json.loads(out)+ issues = [+ i for i in data.get("data", {}).get("issues", [])+ if i.get("rule") == "provenance"+ ]+ # Old behavior: zero breadcrumbs on >5 sources = error+ assert any(i["severity"] == "error" for i in issues)+++# ---------------------------------------------------------------------------+# locus-coverage — flag duplicate interim notes on the same locus+# ---------------------------------------------------------------------------+++def test_locus_coverage_flags_duplicate_interim_notes(tmp_vault):+ """Past failure mode: a single locus accumulated 3 interim notes+ instead of 1. Inflates source count and confuses critics."""+ _write_loci_json(tmp_vault, [+ {"name": "alpha", "one_line": "Q1"},+ ])+ _write_interim(tmp_vault, "alpha", note_id="interim-alpha-1")+ _write_interim(tmp_vault, "alpha", note_id="interim-alpha-2")+ _write_interim(tmp_vault, "alpha", note_id="interim-alpha-3")+ tmp_vault.auto_sync()++ _, out = _run_lint(tmp_vault, rule="locus-coverage")+ import json+ data = json.loads(out)+ issues = [+ i for i in data.get("data", {}).get("issues", [])+ if i.get("rule") == "locus-coverage"+ ]+ dup_issues = [i for i in issues if "duplicate" in i["message"]]+ assert len(dup_issues) == 1+ assert "alpha (3)" in dup_issues[0]["message"]+ assert dup_issues[0]["severity"] == "warning"+++# ---------------------------------------------------------------------------+# patch-surgery — empty log vs real zero-apply distinction+# ---------------------------------------------------------------------------+++def test_patch_surgery_flags_empty_log_with_findings_present(tmp_vault):+ """When critics returned findings and the draft exists, but the patch+ log is empty, the patcher's log was lost. Warn so the operator knows."""+ import json as _json+ # Draft exists+ notes_dir = tmp_vault.root / "research" / "notes"+ notes_dir.mkdir(parents=True, exist_ok=True)+ (notes_dir / "final_report.md").write_text("# Report\n\nBody.", encoding="utf-8")+ # Critic findings with 12 findings+ research = tmp_vault.root / "research"+ research.mkdir(parents=True, exist_ok=True)+ (research / "critic-findings-dialectic.json").write_text(+ _json.dumps({"findings": [{"severity": "major"} for _ in range(12)]}),+ encoding="utf-8",+ )+ # Empty stub patch log+ _write_patch_log(tmp_vault)++ _, out = _run_lint(tmp_vault, rule="patch-surgery")+ data = _json.loads(out)+ issues = [+ i for i in data.get("data", {}).get("issues", [])+ if i.get("rule") == "patch-surgery" and "log was almost certainly lost" in i["message"]+ ]+ assert len(issues) == 1+ assert issues[0]["severity"] == "warning"+++def test_patch_surgery_empty_log_without_findings_is_silent(tmp_vault):+ """If no critic findings exist, an empty patch log is correct (nothing+ to apply), not a warning."""+ import json as _json+ _write_patch_log(tmp_vault)++ _, out = _run_lint(tmp_vault, rule="patch-surgery")+ data = _json.loads(out)+ issues = [+ i for i in data.get("data", {}).get("issues", [])+ if i.get("rule") == "patch-surgery"+ ]+ assert issues == []+++# ---------------------------------------------------------------------------+# instruction-coverage — atomic items from prompt-decomposition must+# appear in the final report+# ---------------------------------------------------------------------------+++def _write_decomposition(vault, entities=None, formats=None):+ import json as _json+ research = vault.root / "research"+ research.mkdir(parents=True, exist_ok=True)+ data = {+ "sub_questions": [],+ "entities": entities or [],+ "required_formats": formats or [],+ "required_sections": [],+ "time_horizons": [],+ "scope_conditions": [],+ }+ (research / "prompt-decomposition.json").write_text(+ _json.dumps(data, ensure_ascii=False, indent=2),+ encoding="utf-8",+ )+++def _write_final_report(vault, body: str):+ notes_dir = vault.root / "research" / "notes"+ notes_dir.mkdir(parents=True, exist_ok=True)+ (notes_dir / "final_report.md").write_text(body, encoding="utf-8")+++def test_instruction_coverage_passes_when_all_entities_present(tmp_vault):+ _write_decomposition(tmp_vault, entities=[+ {"name": "Alpha Method", "type": "concept"},+ {"name": "Beta Framework", "type": "concept"},+ ])+ _write_final_report(tmp_vault,+ "# Report\n\n## Alpha Method\nContent about the Alpha Method.\n\n"+ "## Beta Framework\nContent about the Beta Framework.\n"+ )+ _, out = _run_lint(tmp_vault, rule="instruction-coverage")+ import json+ data = json.loads(out)+ issues = [+ i for i in data.get("data", {}).get("issues", [])+ if i.get("rule") == "instruction-coverage"+ ]+ assert issues == []+++def test_instruction_coverage_flags_missing_entities(tmp_vault):+ _write_decomposition(tmp_vault, entities=[+ {"name": "Alpha Method"},+ {"name": "Beta Framework"},+ {"name": "Gamma Protocol"},+ ])+ _write_final_report(tmp_vault,+ "# Report\n\n## Alpha Method\nContent about the Alpha Method.\n"+ )+ _, out = _run_lint(tmp_vault, rule="instruction-coverage")+ import json+ data = json.loads(out)+ issues = [+ i for i in data.get("data", {}).get("issues", [])+ if i.get("rule") == "instruction-coverage"+ ]+ assert len(issues) == 1+ assert "2 atomic entity" in issues[0]["message"]+ assert "Beta Framework" in issues[0]["message"]+ assert "Gamma Protocol" in issues[0]["message"]+ # 2 missing → warning, 3+ would be error+ assert issues[0]["severity"] == "warning"+++def test_instruction_coverage_errors_on_three_plus_missing(tmp_vault):+ _write_decomposition(tmp_vault, entities=[+ {"name": "Alpha"},+ {"name": "Beta"},+ {"name": "Gamma"},+ {"name": "Delta"},+ ])+ _write_final_report(tmp_vault, "# Report\n\nOnly Alpha is here.\n")+ _, out = _run_lint(tmp_vault, rule="instruction-coverage")+ import json+ data = json.loads(out)+ issues = [+ i for i in data.get("data", {}).get("issues", [])+ if i.get("rule") == "instruction-coverage"+ ]+ # Beta, Gamma, Delta all missing → error severity+ entity_issues = [i for i in issues if "atomic entity" in i["message"]]+ assert len(entity_issues) == 1+ assert entity_issues[0]["severity"] == "error"+++def test_instruction_coverage_flags_missing_format(tmp_vault):+ _write_decomposition(tmp_vault,+ entities=[{"name": "X"}],+ formats=["mind map of causal structure", "ranked list of tradeoffs"],+ )+ _write_final_report(tmp_vault, "# Report\n\n## X\nPlain prose about X.\n")+ _, out = _run_lint(tmp_vault, rule="instruction-coverage")+ import json+ data = json.loads(out)+ issues = [+ i for i in data.get("data", {}).get("issues", [])+ if i.get("rule") == "instruction-coverage"+ and "Required format" in i["message"]+ ]+ assert len(issues) == 1+ assert "mind map" in issues[0]["message"]+ assert "ranked list" in issues[0]["message"]+++def test_instruction_coverage_noop_when_no_decomposition(tmp_vault):+ """Non-layercake runs have no decomposition file — rule stays silent."""+ _, out = _run_lint(tmp_vault, rule="instruction-coverage")+ import json+ data = json.loads(out)+ issues = [+ i for i in data.get("data", {}).get("issues", [])+ if i.get("rule") == "instruction-coverage"+ ]+ assert issues == []+++# ---------------------------------------------------------------------------+# extract-coverage — single-pass /research runs must have analyst-extract+# notes per source. Skips on layercake runs (loci.json present).+# ---------------------------------------------------------------------------+++def test_extract_coverage_passes_with_healthy_ratio(tmp_vault):+ """9 sources + 3 real extracts (≥150 words, parent points to source) =+ 33% coverage = passes the 1/3 gate."""for i in range(9):_write_source(tmp_vault, f"Source {i}", f"source-{i}")- # 3 real extracts (>=150 words each) — 3/9 sources = 33% meets 1/3 floorfor i in range(3):- _write_extract(tmp_vault, f"extract-{i}", word_count_target=200, run_tag="run-a")+ _write_extract(+ tmp_vault,+ f"extract-{i}",+ word_count_target=200,+ parent=f"source-{i}",+ )tmp_vault.auto_sync()- _, out = _run_lint(tmp_vault, rule="analyst-coverage")+ _, out = _run_lint(tmp_vault, rule="extract-coverage")import jsondata = json.loads(out)- issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "analyst-coverage"]- assert issues == [], f"expected no issues, got: {issues}"+ issues = [+ i for i in data.get("data", {}).get("issues", [])+ if i.get("rule") == "extract-coverage"+ ]+ assert issues == []-def test_analyst_coverage_rejects_stub_extracts(tmp_vault):- """Lint-gaming defense: 45 stub extracts (<150 words) do NOT satisfy the gate.- This is the Q91 ensemble failure mode — orchestrator minted hollow extract- notes to pass analyst-coverage numerically."""+def test_extract_coverage_flags_missing_extracts(tmp_vault):+ """9 sources + 0 extracts = 0% coverage = error."""for i in range(9):_write_source(tmp_vault, f"Source {i}", f"source-{i}")- # 45 STUB extracts at ~70 words each — would pass old count-based rule.- for i in range(45):- _write_extract(tmp_vault, f"stub-extract-{i}", word_count_target=70)tmp_vault.auto_sync()- _, out = _run_lint(tmp_vault, rule="analyst-coverage")+ _, out = _run_lint(tmp_vault, rule="extract-coverage")import jsondata = json.loads(out)- issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "analyst-coverage"]+ issues = [+ i for i in data.get("data", {}).get("issues", [])+ if i.get("rule") == "extract-coverage"+ ]assert len(issues) == 1- msg = issues[0]["message"]- # Error message must expose the stub count honestly so the agent sees the- # lint-gaming attempt for what it is.- assert "45 stub notes" in msg- assert "lint-gaming" in msg- # Zero REAL extracts → 0% coverage → error severityassert issues[0]["severity"] == "error"+ assert "9 fetched source notes" in issues[0]["message"]+ assert "0 real" in issues[0]["message"]-def test_analyst_coverage_mixed_real_and_stub(tmp_vault):- """Real extracts count toward the gate; stubs are reported but ignored."""- for i in range(12):+def test_extract_coverage_rejects_stubs(tmp_vault):+ """9 sources + 20 stub extracts (<150 words) = 0 real extracts, all+ stubs counted separately. Lint-gaming defense."""+ for i in range(9):+ _write_source(tmp_vault, f"Source {i}", f"source-{i}")+ for i in range(20):+ _write_extract(+ tmp_vault,+ f"stub-{i}",+ word_count_target=70,+ parent=f"source-{i % 9}",+ )+ tmp_vault.auto_sync()++ _, out = _run_lint(tmp_vault, rule="extract-coverage")+ import json+ data = json.loads(out)+ issues = [+ i for i in data.get("data", {}).get("issues", [])+ if i.get("rule") == "extract-coverage"+ ]+ assert len(issues) == 1+ assert issues[0]["severity"] == "error"+ 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+ over for quality gating."""+ for i in range(9):_write_source(tmp_vault, f"Source {i}", f"source-{i}")- # 4 real extracts (>=150 words) — 4/12 = 33%, passes ceil(12/3)=4 threshold- for i in range(4):- _write_extract(tmp_vault, f"real-extract-{i}", word_count_target=300, run_tag="run-a")- # Plus 10 stubs that should not pad the count- for i in range(10):- _write_extract(tmp_vault, f"stub-extract-{i}", word_count_target=70)+ # No extracts — would normally fire — but...+ _write_loci_json(tmp_vault, [+ {"name": "alpha", "one_line": "Q1"},+ ])tmp_vault.auto_sync()- _, out = _run_lint(tmp_vault, rule="analyst-coverage")+ _, out = _run_lint(tmp_vault, rule="extract-coverage")import jsondata = json.loads(out)- issues = [i for i in data.get("data", {}).get("issues", []) if i.get("rule") == "analyst-coverage"]+ issues = [+ i for i in data.get("data", {}).get("issues", [])+ if i.get("rule") == "extract-coverage"+ ]+ # Silent on layercake — locus-coverage handles this modeassert issues == []diff --git a/tests/test_core/test_hooks.py b/tests/test_core/test_hooks.pyindex e2d4703..7026813 100644--- a/tests/test_core/test_hooks.py+++ b/tests/test_core/test_hooks.py@@ -1,15 +1,30 @@-"""Tests for hook installer and skill file provisioning."""+"""Tests for hook installer and skill file provisioning (layercake roster)."""from __future__ import annotationsfrom hyperresearch.core.hooks import (+ _RETIRED_AGENT_FILES,+ _RETIRED_SKILL_DIRS,_SKILL_FILES,- _install_ensemble_skill,- _install_merger_agent,+ _install_depth_critic_agent,+ _install_depth_investigator_agent,+ _install_dialectic_critic_agent,+ _install_instruction_critic_agent,+ _install_layercake_skill,+ _install_loci_analyst_agent,+ _install_patcher_agent,+ _install_polish_auditor_agent,_install_research_skill,- _install_subrun_agent,+ _install_researcher_agent,+ _install_width_critic_agent,+ _prune_retired_agents,+ install_hooks,)+# ---------------------------------------------------------------------------+# /research skill (single-pass, unchanged)+# ---------------------------------------------------------------------------+def test_install_skill_writes_expected_files(tmp_vault):result = _install_research_skill(tmp_vault.root)@@ -26,12 +41,12 @@ 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)- # Simulate a pre-refactor vault with the old modality files present.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")@@ -54,89 +69,287 @@ def test_install_skill_idempotent_second_run(tmp_vault):assert second is None, "second run should report no changes"-def test_install_ensemble_skill_creates_separate_skill_dir(tmp_vault):- """The ensemble skill MUST install as its own .claude/skills/<name>/SKILL.md- directory so Claude Code registers `/research-ensemble` as a slash-command- trigger. A sibling file inside .claude/skills/hyperresearch/ does NOT get- registered as a separate trigger — the harness discovers skills by- directory, not by SKILL-*.md filename variation."""- result = _install_ensemble_skill(tmp_vault.root)- # Must live at its own dir, NOT alongside hyperresearch/SKILL.md- own_dir_path = tmp_vault.root / ".claude" / "skills" / "research-ensemble" / "SKILL.md"+# ---------------------------------------------------------------------------+# /research-layercake skill+# ---------------------------------------------------------------------------+++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()- sibling_path = tmp_vault.root / ".claude" / "skills" / "hyperresearch" / "SKILL-ensemble.md"- assert not sibling_path.exists(), "ensemble must NOT install as a sibling of SKILL.md"body = own_dir_path.read_text(encoding="utf-8")- assert "name: research-ensemble" in body- assert "hyperresearch-subrun" in body- assert "hyperresearch-merger" in body+ assert "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 bodyassert result is not None-def test_install_ensemble_skill_idempotent(tmp_vault):- first = _install_ensemble_skill(tmp_vault.root)+def test_install_layercake_skill_idempotent(tmp_vault):+ first = _install_layercake_skill(tmp_vault.root)assert first is not None- second = _install_ensemble_skill(tmp_vault.root)+ second = _install_layercake_skill(tmp_vault.root)assert second is None-def test_install_research_skill_prunes_stale_ensemble_sibling(tmp_vault):- """Pre-refactor vaults had SKILL-ensemble.md inside the hyperresearch dir.- After the fix, that path must be pruned on reinstall so users don't end- up with both old and new files (confusing — two sources of truth)."""- hyperresearch_skill_dir = tmp_vault.root / ".claude" / "skills" / "hyperresearch"- hyperresearch_skill_dir.mkdir(parents=True, exist_ok=True)- stale_ensemble = hyperresearch_skill_dir / "SKILL-ensemble.md"- stale_ensemble.write_text("pre-refactor ensemble content\n", encoding="utf-8")+# ---------------------------------------------------------------------------+# Subagent installers — per-agent sanity checks+# ---------------------------------------------------------------------------- _install_research_skill(tmp_vault.root)- assert not stale_ensemble.exists(), "stale SKILL-ensemble.md in hyperresearch dir was not pruned"+def test_install_fetcher_agent(tmp_vault):+ result = _install_researcher_agent(tmp_vault.root, "hyperresearch")+ 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 result is not None-def test_install_subrun_agent_writes_file(tmp_vault):- result = _install_subrun_agent(tmp_vault.root, "hyperresearch")- agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-subrun.md"+def test_install_loci_analyst_agent(tmp_vault):+ result = _install_loci_analyst_agent(tmp_vault.root, "hyperresearch")+ agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-loci-analyst.md"assert agent_path.exists()body = agent_path.read_text(encoding="utf-8")assert "model: sonnet" in body- assert "Task" in body # tools list must include Task for nested spawning- assert "framing_nudge" in body- assert "minimum_fetch_target" in body- assert "run_id" in body+ assert "corpus_evidence" in body+ assert "analyst_id" in bodyassert result is not None-def test_install_subrun_agent_idempotent(tmp_vault):- first = _install_subrun_agent(tmp_vault.root, "hyperresearch")- assert first is not None- second = _install_subrun_agent(tmp_vault.root, "hyperresearch")- assert second is None+def test_install_depth_investigator_agent(tmp_vault):+ result = _install_depth_investigator_agent(tmp_vault.root, "hyperresearch")+ agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-depth-investigator.md"+ assert agent_path.exists()+ body = agent_path.read_text(encoding="utf-8")+ assert "model: sonnet" in body+ # Depth investigator must have Task tool so it can spawn fetcher subagents+ assert "Task" in body+ assert "interim" in body.lower()+ assert "10 new" in body # the fetch budget rule+ 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).+ assert "surgical" in body.lower()+ assert result is not None-def test_install_merger_agent_writes_file(tmp_vault):- result = _install_merger_agent(tmp_vault.root, "hyperresearch")- agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-merger.md"+def test_install_depth_critic_agent(tmp_vault):+ result = _install_depth_critic_agent(tmp_vault.root, "hyperresearch")+ agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-depth-critic.md"assert agent_path.exists()body = agent_path.read_text(encoding="utf-8")assert "model: opus" in body- assert "merger-failed" in body- assert "parent_final_report_path" in body- # Fusion model: no base draft, per-section spine picks- assert "Fusion, not base-plus-splice" in body- assert "spine_picks" in body- assert "unified structural plan" in body.lower()- # Citation reconciliation is deterministic + mandatory- assert "citation reconciliation" in body.lower()- assert "orphan" in body.lower()- # Redundancy pass- assert "dedup_count" in body+ assert "tools: Bash, Read" in body+ assert "interim" in body.lower()assert result is not None-def test_install_merger_agent_idempotent(tmp_vault):- first = _install_merger_agent(tmp_vault.root, "hyperresearch")+def test_install_width_critic_agent(tmp_vault):+ result = _install_width_critic_agent(tmp_vault.root, "hyperresearch")+ agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-width-critic.md"+ assert agent_path.exists()+ body = agent_path.read_text(encoding="utf-8")+ assert "model: opus" in body+ assert "tools: Bash, Read" in body+ assert "coverage" in body.lower()+ assert result is not None+++def test_install_instruction_critic_agent(tmp_vault):+ """Instruction-critic specifically targets the instruction-following+ dimension by checking the draft against prompt-decomposition atomic+ items. Read-only tool lock — it produces findings, never patches."""+ result = _install_instruction_critic_agent(tmp_vault.root, "hyperresearch")+ agent_path = (+ tmp_vault.root / ".claude" / "agents" / "hyperresearch-instruction-critic.md"+ )+ assert agent_path.exists()+ body = agent_path.read_text(encoding="utf-8")+ assert "model: opus" in body+ assert "tools: Bash, Read" in body+ # The critic explicitly consumes the decomposition artifact+ assert "prompt-decomposition.json" in body+ assert "atomic_item" in body+ # Failure modes it tracks+ assert "missing|under-covered|wrong-order|wrong-format" in body+ # Structural-mirror check: runs FIRST, emits findings against+ # required_section_headings. This is the highest-leverage InstF lever.+ assert "STRUCTURAL MIRROR CHECK" in body+ assert "required_section_headings" in body+ # Escalation field for restructures the patcher cannot handle+ assert "requires_orchestrator_restructure" in body+ assert result is not None+++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."""+ 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+ # 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.+ 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.+ 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+ assert "requires_orchestrator_restructure" in body+ assert result is not None+++def test_install_polish_auditor_agent_is_edit_only(tmp_vault):+ """The polish auditor is the second tool-locked [Read, Edit] agent.+ Same invariant: no regeneration path."""+ result = _install_polish_auditor_agent(tmp_vault.root, "hyperresearch")+ 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+ assert "tools: Read, Edit" in body+ assert "tools: Bash" not in body+ # scaffold-only section list must be injected+ assert "User Prompt (VERBATIM" in body+ # Hedge-language cutting category — strikes softeners on claims the+ # paragraph already supports with evidence. Highest-leverage polish cut.+ assert "Hedge language that softens committed claims" in body+ assert "suggests that" in body+ assert result is not None+++# ---------------------------------------------------------------------------+# Idempotency — at least one agent confirms the pattern holds+# ---------------------------------------------------------------------------+++def test_loci_analyst_install_idempotent(tmp_vault):+ first = _install_loci_analyst_agent(tmp_vault.root, "hyperresearch")+ assert first is not None+ second = _install_loci_analyst_agent(tmp_vault.root, "hyperresearch")+ assert second is None+++def test_patcher_install_idempotent(tmp_vault):+ first = _install_patcher_agent(tmp_vault.root, "hyperresearch")assert first is not None- second = _install_merger_agent(tmp_vault.root, "hyperresearch")+ second = _install_patcher_agent(tmp_vault.root, "hyperresearch")assert second is None+++# ---------------------------------------------------------------------------+# Retired-roster pruning+# ---------------------------------------------------------------------------+++def test_prune_retired_agents_removes_old_files(tmp_vault):+ """Pre-layercake 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")++ skills_dir = tmp_vault.root / ".claude" / "skills"+ for name in _RETIRED_SKILL_DIRS:+ retired_skill = skills_dir / name+ retired_skill.mkdir(parents=True, exist_ok=True)+ (retired_skill / "SKILL.md").write_text("old skill\n", encoding="utf-8")++ result = _prune_retired_agents(tmp_vault.root)+ assert result is not None+ assert "Pruned retired" in result++ for name in _RETIRED_AGENT_FILES:+ assert not (agents_dir / name).exists(), f"{name} still present"+ for name in _RETIRED_SKILL_DIRS:+ assert not (skills_dir / name).exists(), f"skill dir {name} still present"+++def test_prune_retired_agents_noop_on_clean_vault(tmp_vault):+ """On a fresh vault, prune is a no-op."""+ result = _prune_retired_agents(tmp_vault.root)+ assert result is None+++# ---------------------------------------------------------------------------+# install_hooks — end-to-end integration+# ---------------------------------------------------------------------------+++def test_install_hooks_registers_full_layercake_roster(tmp_vault):+ """install_hooks wires the hook + both skills + all 8 layercake agents."""+ actions = install_hooks(tmp_vault.root, "hyperresearch")+ assert actions # something happened++ # All 8 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-dialectic-critic.md",+ "hyperresearch-depth-critic.md",+ "hyperresearch-width-critic.md",+ "hyperresearch-instruction-critic.md",+ "hyperresearch-patcher.md",+ "hyperresearch-polish-auditor.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+ assert (tmp_vault.root / ".claude" / "skills" / "hyperresearch" / "SKILL.md").exists()+ assert (+ tmp_vault.root / ".claude" / "skills" / "research-layercake" / "SKILL.md"+ ).exists()++ # Hook settings written+ assert (tmp_vault.root / ".claude" / "settings.json").exists()+ assert (tmp_vault.root / ".hyperresearch" / "hook.js").exists()+++def test_install_hooks_second_run_is_noop(tmp_vault):+ first = install_hooks(tmp_vault.root, "hyperresearch")+ assert first+ second = install_hooks(tmp_vault.root, "hyperresearch")+ # Hook installer may still report the hook is already installed → no+ # actions or a trivial subset. Must not crash, must not reinstall files.+ assert not second or all("pruned" not in a.lower() for a in second)diff --git a/tests/test_core/test_patterns.py b/tests/test_core/test_patterns.pyindex b4fd54d..352091a 100644--- a/tests/test_core/test_patterns.py+++ b/tests/test_core/test_patterns.py@@ -22,7 +22,8 @@ def test_anchors_and_paths_rejected():def test_pure_numeric_citation_footnotes_rejected():- # The Q91 bug: Wikipedia footnotes rendered as [[100]]+ # Past bug: Wikipedia footnotes rendered as [[100]] and got mistaken+ # for wiki-link targets.assert not is_valid_wiki_link_target("100")assert not is_valid_wiki_link_target("1")assert not is_valid_wiki_link_target("999")@@ -63,8 +64,8 @@ def test_cite_prefixes_are_case_insensitive():def test_space_separated_footnote_names_rejected():- """HTML footnote rendering: <sup>Note 1</sup> → [[Note 1]]. The Q91- ensemble run produced stubs for these because the filter missed them."""+ """HTML footnote rendering: <sup>Note 1</sup> → [[Note 1]]. Past+ runs produced stubs for these because the filter missed them."""assert not is_valid_wiki_link_target("Note 1")assert not is_valid_wiki_link_target("Note 2")assert not is_valid_wiki_link_target("Footnote 12")