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
v0.8.5: reports self-title by vault_tag, wikilinks as default citation system (#22)
Jordan Gibbs067a4c2a3683
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4d565d7..18e1705 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,16 @@# Changelog+## [0.8.5] - 2026-04-29++### Reports self-title; wikilinks become the default citation system++Two related changes that fix the "I lost my last report" foot-gun and make the vault genuinely navigable:++- **Final reports now write to `research/notes/final_report_<vault_tag>.md`.** Every run self-titles by the canonical query slug (e.g., `final_report_rl-exploration.md`). No more overwrites — running `/hyperresearch` on a new topic in the same project leaves the previous report untouched. Persistent personal research wiki, no surprise data loss.+- **Wiki-link citations are the new default citation style.** Every citation in the body is `[[<source-note-id>]]` pointing at the source note in the vault. No separate `## Sources` section needed — each wiki-link self-resolves to the source note's frontmatter (title + URL). For users in their own vault this means every citation is one click away from the raw source. The `inline` (`[N]` + Sources section) and `none` styles are still selectable; the benchmark wrapper continues to set `"inline"` via `wrapper_contract.json` so RACE evaluators can read numbered references.+- **Polish auditor updated**: only strips wiki-links pointing at workspace artifacts (`[[interim-*]]`, `[[scaffold]]`, `[[comparisons]]`). Source-note wiki-links are preserved as the citation system when style is `"wikilink"`.+- **Lint rules updated**: `wrapper-report`, `patch-surgery`, and `instruction-coverage` rules glob for `final_report*.md` and validate the most recent. Pre-0.8.5 bare `final_report.md` still works.+## [0.8.4] - 2026-04-29### Polish + release plumbingdiff --git a/pyproject.toml b/pyproject.tomlindex 6488a25..665b764 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "hyperresearch"-version = "0.8.4"+version = "0.8.5"description = "Claude Code harness for disciplined, adversarially-audited deep research with full provenance."readme = "README.md"license = "MIT"diff --git a/src/hyperresearch/__init__.py b/src/hyperresearch/__init__.pyindex c9b76b5..6ee899c 100644--- a/src/hyperresearch/__init__.py+++ b/src/hyperresearch/__init__.py@@ -1,3 +1,3 @@"""Hyperresearch — agent-driven research knowledge base."""-__version__ = "0.8.4"+__version__ = "0.8.5"diff --git a/src/hyperresearch/cli/lint.py b/src/hyperresearch/cli/lint.pyindex 0fe4305..ebe4689 100644--- a/src/hyperresearch/cli/lint.py+++ b/src/hyperresearch/cli/lint.py@@ -191,7 +191,7 @@ def lint(f"[{c.get('id','?')}] {c.get('description','?')[:80]}"for c in unresolved[:5])- + ". Apply the fixes in research/notes/final_report.md, "+ + ". Apply the fixes in research/notes/final_report_<vault_tag>.md, "+ "mark each finding with `fixed_at: <ISO>` in "+ "research/audit_findings.json, and re-run the conformance "+ "auditor to verify."@@ -546,7 +546,18 @@ def lint(wrapper_contract = Noneif prompt_path.exists() or query_files_exist or wrapper_contract is not None:- report_path = vault.root / "research" / "notes" / "final_report.md"+ # Reports are now named final_report_<vault_tag>.md. Glob to find+ # any matching report; fall back to the legacy bare name for+ # back-compat with pre-0.8.5 runs.+ notes_dir = vault.root / "research" / "notes"+ report_candidates = sorted(+ notes_dir.glob("final_report*.md"),+ key=lambda p: p.stat().st_mtime,+ reverse=True,+ ) if notes_dir.exists() else []+ report_path = report_candidates[0] if report_candidates else (+ notes_dir / "final_report.md"+ )if not report_path.exists():issues.append({"rule": "wrapper-report",@@ -555,7 +566,7 @@ def lint("message": ("Wrapped research context detected (prompt.txt, ""query-*.md, or wrapper_contract.json present) but "- "`research/notes/final_report.md` is missing. "+ "no `research/notes/final_report*.md` file is present. ""The final report must exist before export."),})@@ -1060,11 +1071,13 @@ def lint(except (json.JSONDecodeError, OSError):pass- final_report = vault.root / "research" / "notes" / "final_report.md"+ notes_dir = vault.root / "research" / "notes"+ report_matches = sorted(notes_dir.glob("final_report*.md")) if notes_dir.exists() else []+ final_report_exists = bool(report_matches)if (total_logged == 0and critic_totals > 0- and final_report.exists()+ and final_report_exists):issues.append({"rule": "patch-surgery",@@ -1099,7 +1112,15 @@ def lint(# 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"+ notes_dir = vault.root / "research" / "notes"+ report_candidates = sorted(+ notes_dir.glob("final_report*.md"),+ key=lambda p: p.stat().st_mtime,+ reverse=True,+ ) if notes_dir.exists() else []+ final_report = report_candidates[0] if report_candidates else (+ notes_dir / "final_report.md"+ )if decomp_path.exists() and final_report.exists():try:decomp = json.loads(decomp_path.read_text(encoding="utf-8"))diff --git a/src/hyperresearch/core/agent_docs.py b/src/hyperresearch/core/agent_docs.pyindex 45e3190..711f478 100644--- a/src/hyperresearch/core/agent_docs.py+++ b/src/hyperresearch/core/agent_docs.py@@ -21,7 +21,7 @@ HYPERRESEARCH_BLURB = """**CLI path: `{hpr}`** — use this exact path for every hyperresearch command. It may not be on your system PATH.-**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.+**Paths in this document are relative to your current working directory**, not to the CLI binary's location. Use `research/notes/final_report_<vault_tag>.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.diff --git a/src/hyperresearch/core/hooks.py b/src/hyperresearch/core/hooks.pyindex 8fe17dc..132de2a 100644--- a/src/hyperresearch/core/hooks.py+++ b/src/hyperresearch/core/hooks.py@@ -559,7 +559,7 @@ Everything prior to you has already happened: width sweep (Layer 1), locianalysis (Layer 2), depth investigation (Layer 3 — interim notes live inthe 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+`research/notes/final_report_<vault_tag>.md`). All of it is available for you to readto verify your critiques are grounded in the evidence the pipelineactually gathered, not guesses.@@ -573,7 +573,7 @@ actually gathered, not guesses.`research/query-<vault_tag>.md`). Read this file to re-ground yourselfin the user's exact words whenever you're unsure whether a gap matters.- **draft_path**: path to the Layer 4 draft (typically- `research/notes/final_report.md`).+ `research/notes/final_report_<vault_tag>.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@@ -688,7 +688,7 @@ rather than gesturing at it from a distance.`research/query-<vault_tag>.md`). Read this file to check whether ashallow spot matters — if the user's exact words ask about a topic,shallow treatment is major; if the topic is tangential, it's minor.-- **draft_path**: `research/notes/final_report.md`+- **draft_path**: `research/notes/final_report_<vault_tag>.md`- **output_path**: `research/critic-findings-depth.json`- **vault_tag**: corpus tag for searching the vault@@ -792,7 +792,7 @@ because the orchestrator's structural choices buried them.`research/query-<vault_tag>.md`). Read this file and extract everynoun phrase the user mentioned. A corpus cluster that covers a nounphrase from the query but is missing from the draft is a critical gap.-- **draft_path**: `research/notes/final_report.md`+- **draft_path**: `research/notes/final_report_<vault_tag>.md`- **output_path**: `research/critic-findings-width.json`- **vault_tag**: corpus tag@@ -951,7 +951,7 @@ hand findings to the patcher (Layer 6). You do NOT modify the draft.Written in Layer 0 by the orchestrator. Contains the atomic items theprompt named: explicit sub-questions, required entities, requiredformats, required sections, time horizons, scope conditions.-- **draft_path**: `research/notes/final_report.md`+- **draft_path**: `research/notes/final_report_<vault_tag>.md`- **output_path**: `research/critic-findings-instruction.json`## Procedure@@ -1255,7 +1255,7 @@ Concretely:`research/query-<vault_tag>.md`). Read this file when in doubt aboutwhether a finding serves the user's actual question.- **draft_path**: path to the Layer 4 draft (usually- `research/notes/final_report.md`).+ `research/notes/final_report_<vault_tag>.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@@ -1303,8 +1303,9 @@ Concretely:must match the draft exactly — copy it verbatim from your Read output.d. Keep edits minimal. Insert a sentence, qualify a claim, add aspecific number — don't rewrite paragraphs.- e. Integrate evidence as authoritative prose. Use `[N]` citation- markers if `citation_style` is `"inline"`, no markers if `"none"`.+ e. Integrate evidence as authoritative prose. Match the existing+ citation style: `[[<source-note-id>]]` markers for `"wikilink"`,+ `[N]` markers for `"inline"`, no markers for `"none"`.6. **Populate the patch log via Edit.** Update the stub at `patch_log_path`with what you applied, skipped, and why.@@ -1315,7 +1316,7 @@ Concretely:- **Never skip a `critical` finding without logging why.**- **Preserve Markdown structure.** Do not change heading levels,numbered-list numbering, or table column counts.-- **Match citation style.** Use `[N]` if `citation_style` is `"inline"`, no markers if `"none"`.+- **Match citation style.** `[[<source-note-id>]]` for `"wikilink"`, `[N]` for `"inline"`, no markers for `"none"`.## Integrate, don't caveat@@ -1477,7 +1478,7 @@ see any of these patterns in reader-facing prose:| `\\bdepth\\s+investigation\\b` | "the detailed analysis on <topic>" || `(per\\|from)\\s+the\\s+scaffold` | Delete entirely; the substantive claim stands on its own || `hyperresearch(\\s+final\\s+report)?` | Delete entirely — never expose the pipeline name to the reader |-| `\\[?\\[?interim[-_]report[-_]` / `\\[I\\d+\\]` | If `citation_style` is `"inline"`: convert to the matching `[N]` numeric citation from the Sources list. If `"none"`: delete entirely. |+| `\\[?\\[?interim[-_]report[-_]` / `\\[I\\d+\\]` | Workspace-artifact references (NOT source-note wikilinks). `"wikilink"` mode: replace the interim wikilink with the `[[<source-note-id>]]` of the most relevant source the interim cited (read the interim note's frontmatter / first cited source). `"inline"`: convert to matching `[N]`. `"none"`: delete entirely. |**Special case for `\\bloci\\b` as a free-standing word:** some domains(molecular biology, law, neuroscience) use "locus/loci" as legitimate@@ -1499,7 +1500,8 @@ locus", "legal locus"), leave it alone.Rewrite: "On the trajectory question, the evidence commits: the post-2015 decline stalled."- Original: "[I4] [[interim-report-sihuan-zhongshen-dialectic]]"- Rewrite (inline mode): convert to the matching numeric citation, e.g., "[18]".+ Rewrite (wikilink mode): replace with the source-note wikilink the interim was citing, e.g., `[[sihuan-q3-2024-results]]`.+ Rewrite (inline mode): convert to the matching numeric citation, e.g., `[18]`.Rewrite (none mode): delete the reference entirely.Each inline-scaffold fix is a **critical** polish edit. The denylist@@ -1508,12 +1510,21 @@ on the fly.### 1c. Pipeline reference cleanup-Any inline `[[interim-*]]` wikilink or `[I\\d+]` reference is a-pipeline leak — these are internal note IDs, not reader-facing-citations. Convert or delete based on `citation_style`:+`[[interim-*]]` wikilinks and `[I\\d+]` references point at workspace+artifacts, not reader-facing source notes. They are pipeline leaks.+Convert or delete based on `citation_style`:+- `"wikilink"`: replace with the `[[<source-note-id>]]` of the source+ note the interim was citing (read the interim's frontmatter for the+ first / most-relevant cited source)- `"inline"`: convert to matching `[N]` from the Sources list- `"none"`: delete entirely+**Reader-facing `[[<source-note-id>]]` wikilinks** (where the target+is a real source note in the vault, not an interim/scaffold artifact)+are PRESERVED when `citation_style == "wikilink"` — they are the+citation system, not a leak. Strip them ONLY when the style is+`"inline"` (convert to `[N]`) or `"none"` (delete).+Leave all reader-facing `[N]` citations and the Sources sectionintact — they are product features, not polish targets.@@ -1724,7 +1735,7 @@ all three. Your draft is an INPUT to the synthesis, not the final output.- **comparisons_path**: `research/comparisons.md` (if exists).- **source_tensions_path**: `research/temp/source-tensions.json` (if exists).- **response_format**: `"short"` / `"structured"` / `"argumentative"`.-- **citation_style**: `"inline"` / `"none"`.+- **citation_style**: `"wikilink"` / `"inline"` / `"none"`.- **modality**: `"collect"` / `"synthesize"` / `"compare"` / `"forecast"`.## Phase 1: Read the artifacts@@ -1790,7 +1801,7 @@ Write your complete draft to `output_path`. Your draft must:answered, every entity addressed, every required format honored.- **Use numbered hierarchical headings** (e.g., `## I. Title`, `### A. Sub`).- **Include an executive summary** that directly answers the question first.-- **Include a `## Sources` section** if citation_style is "inline".+- **Include a `## Sources` section** ONLY if citation_style is `"inline"`. For `"wikilink"` (default), the wiki-link markers in the body self-resolve — no separate Sources section. For `"none"`, no markers anywhere.### Angle-specific requirements (YOUR DIFFERENTIATOR)@@ -1805,8 +1816,9 @@ Write your complete draft to `output_path`. Your draft must:### Quality rules-- **Citation density:** Aim for 2+ citations per 1000 characters for- inline citation style.+- **Citation density:** Aim for 2+ citations per 1000 characters+ regardless of style (`[[<source-note-id>]]` for wikilink,+ `[N]` for inline).- **Interpretive density:** For every 2-3 factual claims, include atleast one interpretive beat that draws a conclusion the sources didn't.- **No pipeline vocabulary** in prose (no "locus", "tension N",@@ -1826,9 +1838,9 @@ Write your complete draft to `output_path`. Your draft must:### Source attribution-If `citation_style` is `"inline"`: use `[N]` citations with a `## Sources`-section at the end. Number deterministically — first cited = [1], etc.-If `"none"`: no citation markers, no Sources section.+- `"wikilink"` (default): every citation is a `[[<source-note-id>]]` marker pointing at the source note in the vault. No separate Sources section. Each wiki-link resolves to its source note's frontmatter (title + URL). Use the actual note ID from `must_read_note_ids` — copy IDs verbatim.+- `"inline"`: `[N]` citations with a `## Sources` section at the end. Number deterministically — first cited = [1], etc. Read each cited note's YAML frontmatter for title + URL.+- `"none"`: no citation markers anywhere, no Sources section.## Reporting back@@ -1879,7 +1891,7 @@ You are step 11 of the hyperresearch V8 pipeline. Step 10 spawned 3one angle-specific draft (`draft-a.md`, `draft-b.md`, `draft-c.md`). Themain orchestrator wrote a synthesis plan and outline (steps 11.3 and11.4). You consume all of that and produce the final report at-`research/notes/final_report.md`.+`research/notes/final_report_<vault_tag>.md`.After you: step 12 (4 adversarial critics) reads your final report andproduces findings. The patcher (step 14) applies findings as Edit hunks.@@ -1920,7 +1932,7 @@ mental model; writing the final report is a fresh act.claims with verbatim quotes and source IDs.- **pass1_output_path**: `research/temp/synthesis-pass1.md` — whereyou write the rough integrated draft (pass 1).-- **final_output_path**: `research/notes/final_report.md` — where you+- **final_output_path**: `research/notes/final_report_<vault_tag>.md` — where youwrite the cleaned-up final report (pass 2).## Phase 1: Read everything@@ -2071,13 +2083,11 @@ If pass 1 is under target, EXPAND. Specifically:### Citation discipline-- Renumber `[N]` from `[1]` deterministically in order of first appearance- in the final draft-- Build a single `## Sources` section at the end with one entry per cited- source (deduplicated). Format: `[1] Author(s). "Title." *Publication*,- Year. URL`-- Aim for 2+ citations per 1000 characters for `inline` style-- For `none` style: no `[N]` markers, no `## Sources` section+Three citation styles. Match `citation_style` from the decomposition:++- **`"wikilink"`** (default for non-wrapped runs): every citation is a `[[<source-note-id>]]` marker pointing at the source note in the vault. No separate `## Sources` section. Each wiki-link self-resolves to the source note's frontmatter (title + URL). Aim for 2+ citations per 1000 characters. Copy note IDs verbatim from the input drafts and the evidence digest.+- **`"inline"`** (benchmark + public deliverables): `[N]` citations renumbered from `[1]` deterministically in order of first appearance, AND a single `## Sources` section at the end with one entry per cited source (deduplicated). Format: `[1] Author(s). "Title." *Publication*, Year. URL`. Aim for 2+ citations per 1000 characters.+- **`"none"`**: no citation markers anywhere, no Sources section.### Hygiene@@ -2085,7 +2095,11 @@ The final draft MUST NOT contain:- YAML frontmatter- Pipeline vocabulary ("Locus N", "Tension N", "comparisons.md","committed reading", "width corpus", "depth investigation",- "hyperresearch", "synthesis plan", "synthesis outline", `[[wikilinks]]`)+ "hyperresearch", "synthesis plan", "synthesis outline")+- Workspace-artifact wiki-links (`[[interim-*]]`, `[[scaffold]]`,+ `[[comparisons]]`). Source-note wiki-links (`[[<source-note-id>]]`)+ ARE the citation system when `citation_style == "wikilink"` and must+ be preserved.- Scaffold sections, prompt echoes, or meta-discussion of the pipeline- Filler phrases (see length section)@@ -2199,7 +2213,7 @@ apply. You are advisory.## Inputs (from the orchestrator)- **research_query**: verbatim user question. GOSPEL.-- **draft_path**: `research/notes/final_report.md` — the polished report.+- **draft_path**: `research/notes/final_report_<vault_tag>.md` — the polished report.- **recommendations_path**: `research/readability-recommendations.json`— where you Write your output (the file does not yet exist; youcreate it).diff --git a/src/hyperresearch/skills/hyperresearch-1-decompose.md b/src/hyperresearch/skills/hyperresearch-1-decompose.mdindex 3025b0c..804f89a 100644--- a/src/hyperresearch/skills/hyperresearch-1-decompose.md+++ b/src/hyperresearch/skills/hyperresearch-1-decompose.md@@ -90,7 +90,7 @@ Read both before starting. The vault_tag is in the scaffold's "Run config" secti"scope_conditions": ["urban rail specifically, not mainline"],"pipeline_tier": "full","response_format": "argumentative",- "citation_style": "inline"+ "citation_style": "wikilink"}```@@ -127,8 +127,11 @@ Read both before starting. The vault_tag is in the scaffold's "Run config" secti| Style | When to use | Output ||-------|-------------|--------|- | `"inline"` | **Default.** User wants a verifiable research report. | `[N]` inline citations + formatted `## Sources` list. |- | `"none"` | Polished expert-analysis with no visible citation apparatus. | No `[N]` markers, no Sources section. |+ | `"wikilink"` | **Default.** Personal use in a vault — every citation is a clickable wiki-link back to the raw source note in `research/notes/`. | `[[note-id]]` markers inline. No separate Sources section (each link self-resolves to the source note's frontmatter title + URL). |+ | `"inline"` | Public deliverable, benchmark wrappers, or verifiable research report for someone outside the vault. | `[N]` inline citations + a formatted `## Sources` list at the end. |+ | `"none"` | Polished expert-analysis with no visible citation apparatus. | No citation markers, no Sources section. |++ **Wrapper override:** if `research/wrapper_contract.json` exists and specifies `citation_style`, it overrides the default. The benchmark harness sets `"inline"` via wrapper_contract so RACE evaluators can read numbered references; everything else gets the wikilink default.8. **Coverage matrix self-audit.** Re-read the verbatim query. Walk through it phrase by phrase and extract every **significant noun phrase, proper noun, technical term, and category name**. For each:- Does it map to at least one atomic item in the decomposition?diff --git a/src/hyperresearch/skills/hyperresearch-10-triple-draft.md b/src/hyperresearch/skills/hyperresearch-10-triple-draft.mdindex ddf1a3e..0b4a443 100644--- a/src/hyperresearch/skills/hyperresearch-10-triple-draft.md+++ b/src/hyperresearch/skills/hyperresearch-10-triple-draft.md@@ -13,9 +13,9 @@ description: ># Step 10 — Triple-draft ensemble (curated lists, parallel writers)-**⚠ CRITICAL ANTI-PATTERN: Writing a single draft for `full` tier is a PIPELINE VIOLATION.** In V7 runs, context compaction caused the orchestrator to forget this step's procedure and write a single draft instead of spawning 3 sub-orchestrators. V8 fixes this by loading this skill fresh at the moment it's needed. **If you find yourself about to write `research/notes/final_report.md` directly without spawning 3 `hyperresearch-draft-orchestrator` subagents, STOP. Re-read this skill. Spawn the sub-orchestrators.** (Light tier is the ONE exception — see "Light tier" section below.)+**⚠ CRITICAL ANTI-PATTERN: Writing a single draft for `full` tier is a PIPELINE VIOLATION.** In V7 runs, context compaction caused the orchestrator to forget this step's procedure and write a single draft instead of spawning 3 sub-orchestrators. V8 fixes this by loading this skill fresh at the moment it's needed. **If you find yourself about to write `research/notes/final_report_<vault_tag>.md` directly without spawning 3 `hyperresearch-draft-orchestrator` subagents, STOP. Re-read this skill. Spawn the sub-orchestrators.** (Light tier is the ONE exception — see "Light tier" section below.)-**Tier gate:** Runs for ALL tiers. For `light` tier: write a single draft directly to `research/notes/final_report.md` and skip ahead to step 15 (polish). For `full`: run the triple-draft ensemble below — step 11 (synthesizer) will turn the 3 drafts into the final report.+**Tier gate:** Runs for ALL tiers. For `light` tier: write a single draft directly to `research/notes/final_report_<vault_tag>.md` and skip ahead to step 15 (polish). For `full`: run the triple-draft ensemble below — step 11 (synthesizer) will turn the 3 drafts into the final report.**Goal:** produce THREE independent angle-specific drafts (`draft-{a,b,c}.md`). Step 11 (synthesizer subagent) consumes all three and writes the final report.@@ -57,7 +57,7 @@ Read `response_format` and `citation_style` from `research/prompt-decomposition.If `pipeline_tier == "light"`: SKIP step 10.1 — 10.3 below and follow this section instead.-**Light tier writes a single draft directly to `research/notes/final_report.md`.** No subagents, no triple-draft ensemble, no synthesizer.+**Light tier writes a single draft directly to `research/notes/final_report_<vault_tag>.md`.** No subagents, no triple-draft ensemble, no synthesizer.1. **Read the vault directly.** Light tier has no `evidence-digest.md` (step 9 was skipped). Survey the vault: `$HPR search "" --tag <vault_tag> -j` and pick the 8–15 most relevant non-deprecated notes. Read each one (`$HPR note show <id1> <id2> ... -j`) before writing.@@ -66,11 +66,14 @@ If `pipeline_tier == "light"`: SKIP step 10.1 — 10.3 below and follow this sec- Hit the length target from step 10.0's table for the chosen `response_format` (light typically pairs with `short` or `structured`).- Apply the modality calibration from the recover-state list above.-3. **Citations.** If `citation_style == "inline"`: use numbered `[N]` citations and end the report with a `## Sources` section listing each cited note as `[N] Title. URL` (read each cited note's YAML frontmatter for title + URL). If `citation_style == "none"`: no inline citation markers, no Sources section.+3. **Citations.** Three styles:+ - `"wikilink"` (default for non-wrapped runs): every citation is a `[[<source-note-id>]]` marker pointing at the source note in the vault. No separate `## Sources` section. Each wikilink resolves to its source note's frontmatter (title + URL). This is the navigable-vault format.+ - `"inline"` (benchmark + public deliverables): numbered `[N]` citations + a `## Sources` section listing each cited note as `[N] Title. URL` (read each cited note's YAML frontmatter for title + URL).+ - `"none"`: no citation markers anywhere, no Sources section.-4. **Hygiene.** No YAML frontmatter on the final report. No `[[wikilink]]` markers. No pipeline vocabulary in prose ("hyperresearch", "evidence digest", "comparisons.md", "committed reading", etc.). Step 15 (polish) is a backstop, not a license to leak.+4. **Hygiene.** No YAML frontmatter on the final report. No pipeline vocabulary in prose ("hyperresearch", "evidence digest", "comparisons.md", "committed reading", etc.). When `citation_style == "wikilink"`, `[[<source-note-id>]]` markers ARE the citation system and must be preserved — only strip wikilinks that point at workspace artifacts (interim-*, scaffold, comparisons). Step 15 (polish) is a backstop, not a license to leak.-5. **Exit and route.** Once `research/notes/final_report.md` is written, return to the entry skill and invoke `Skill(skill: "hyperresearch-15-polish")`. Light tier skips steps 11–14 entirely.+5. **Exit and route.** Once `research/notes/final_report_<vault_tag>.md` is written, return to the entry skill and invoke `Skill(skill: "hyperresearch-15-polish")`. Light tier skips steps 11–14 entirely.---@@ -161,7 +164,7 @@ prompt: |- comparisons_path: research/comparisons.md- source_tensions_path: research/temp/source-tensions.json- response_format: "<short|structured|argumentative>"- - citation_style: "<inline|none>"+ - citation_style: "<wikilink|inline|none>"- modality: "<collect|synthesize|compare|forecast>"Read every note on must_read_note_ids before writing. Do NOT survey@@ -198,7 +201,7 @@ When all 3 sub-orchestrators return:## Exit criterion**Light tier:**-- `research/notes/final_report.md` exists, hits the length target from step 10.0, follows `required_section_headings`, and respects `citation_style`.+- `research/notes/final_report_<vault_tag>.md` exists, hits the length target from step 10.0, follows `required_section_headings`, and respects `citation_style`.**Standard / full tier:**- All three drafts exist at `research/temp/draft-{a,b,c}.md`@@ -211,5 +214,5 @@ When all 3 sub-orchestrators return:Return to the entry skill (`hyperresearch`). Tier-based routing:-- **light tier:** You already wrote `research/notes/final_report.md` directly. Skip steps 11-14 (no synthesis, no critics, no patcher) and invoke `Skill(skill: "hyperresearch-15-polish")`.+- **light tier:** You already wrote `research/notes/final_report_<vault_tag>.md` directly. Skip steps 11-14 (no synthesis, no critics, no patcher) and invoke `Skill(skill: "hyperresearch-15-polish")`.- **full tier:** Invoke `Skill(skill: "hyperresearch-11-synthesize")`.diff --git a/src/hyperresearch/skills/hyperresearch-11-synthesize.md b/src/hyperresearch/skills/hyperresearch-11-synthesize.mdindex ce4c33e..776e4a4 100644--- a/src/hyperresearch/skills/hyperresearch-11-synthesize.md+++ b/src/hyperresearch/skills/hyperresearch-11-synthesize.md@@ -12,9 +12,9 @@ description: ># Step 11 — Synthesize the final report-**Tier gate:** SKIP entirely for `light` tier — light tier wrote `research/notes/final_report.md` directly in step 10 and proceeds straight to step 15 (polish). For `full`: run as documented below.+**Tier gate:** SKIP entirely for `light` tier — light tier wrote `research/notes/final_report_<vault_tag>.md` directly in step 10 and proceeds straight to step 15 (polish). For `full`: run as documented below.-**Goal:** turn the 3 angle-specific drafts from step 10 into ONE integrated final report at `research/notes/final_report.md`. The orchestrator preps the strategic brief; the synthesizer subagent writes the report in two passes (rough integrated draft, then voice/redundancy/length cleanup).+**Goal:** turn the 3 angle-specific drafts from step 10 into ONE integrated final report at `research/notes/final_report_<vault_tag>.md`. The orchestrator preps the strategic brief; the synthesizer subagent writes the report in two passes (rough integrated draft, then voice/redundancy/length cleanup).**Why split orchestrator + synthesizer:** the orchestrator has been running for 30+ minutes and 200K+ tokens of context. Writing a coherent 5000-10000 word report at this point is the highest cognitive load step in the pipeline, and orchestrator context is full of stale subagent dispatch logic. The synthesizer is a fresh Opus session with `[Read, Write]` tool-lock, focused exclusively on producing the final report. This is the same architectural move that made the patcher and polish-auditor reliable.@@ -124,7 +124,7 @@ Write `research/temp/synthesis-outline.md`. This is the per-section contract —<1-2 sentences: the committed reading, the strongest forward-looking implication>## Sources-<inline citation style only — N entries, deduplicated>+<only emitted when citation_style == "inline" — N numbered entries, deduplicated. For "wikilink" style (default), the wiki-link markers in the body are self-resolving and no separate Sources section is needed.>```The outline is short (50-200 words total). It's the structural anchor that prevents pass-1 sections from rambling.@@ -175,14 +175,27 @@ prompt: |- source_tensions_path: research/temp/source-tensions.json- evidence_digest_path: research/temp/evidence-digest.md- pass1_output_path: research/temp/synthesis-pass1.md- - final_output_path: research/notes/final_report.md+ - final_output_path: research/notes/final_report_<vault_tag>.md- response_format: "<short|structured|argumentative>"- - citation_style: "<inline|none>"+ - citation_style: "<wikilink|inline|none>"Read everything. Write pass 1 to pass1_output_path. Then audit pass 1for redundancy, voice consistency, weak sections, and length, andwrite the cleaned pass 2 to final_output_path. Do not paste paragraphsfrom the input drafts — synthesize them in your own voice.++ **Citation rendering:**+ - If citation_style == "wikilink" (default): every citation is a+ `[[note-id]]` marker pointing at the source note in the vault. No+ separate `## Sources` section. The wiki-link IS the citation —+ readers click through to the source note's frontmatter for title ++ URL. Do NOT add numbered references.+ - If citation_style == "inline": every citation is a `[N]` marker,+ AND the report ends with a `## Sources` section listing each cited+ source as `[N] Title. URL` (read each cited note's YAML frontmatter+ for title + URL).+ - If citation_style == "none": no citation markers anywhere, no+ Sources section.```**CRITICAL: never emit bare text while the synthesizer is running.** It will take 5-15 minutes (two passes). Use the wait time to think — append notes to `research/temp/orchestrator-notes.md` about what you'll watch for in step 12 (the critics) based on the synthesis plan you just wrote.@@ -195,7 +208,7 @@ When the synthesizer returns:1. **Confirm both files exist:**- `research/temp/synthesis-pass1.md` (pass 1, rough integrated)- - `research/notes/final_report.md` (pass 2, final)+ - `research/notes/final_report_<vault_tag>.md` (pass 2, final)2. **Read the synthesizer's report-back.** It tells you:- Word/character count@@ -207,12 +220,12 @@ When the synthesizer returns:3. **Sanity checks on the final report:**- Length is in the target range for `response_format` (not 3x)- Has all H2s from `required_section_headings`- - Has `## Sources` section if `citation_style == "inline"`+ - Citations match `citation_style`: `[[note-id]]` markers for `"wikilink"` (no Sources section); `[N]` markers + a `## Sources` section for `"inline"`; no markers for `"none"`- No YAML frontmatter, no scaffold leaks, no pipeline vocabularyIf pass 2 is longer than pass 1 (positive delta), something went wrong — pass 2 is supposed to cut. Investigate before proceeding.-If a sanity check fails, hand-craft an Edit on `research/notes/final_report.md` yourself to fix it. Do NOT re-spawn the synthesizer — that's regeneration, which violates the patch-not-regenerate invariant once we have a final draft.+If a sanity check fails, hand-craft an Edit on `research/notes/final_report_<vault_tag>.md` yourself to fix it. Do NOT re-spawn the synthesizer — that's regeneration, which violates the patch-not-regenerate invariant once we have a final draft.---@@ -224,10 +237,10 @@ After this step, the final report is only modified by Edit hunks from the patche## Exit criterion-- `research/notes/final_report.md` exists, length in target range+- `research/notes/final_report_<vault_tag>.md` exists, length in target range- `research/temp/synthesis-pass1.md` exists (debugging artifact)- All H2s from `required_section_headings` present-- `## Sources` section exists if `citation_style == "inline"`+- Citations match `citation_style` (wikilink → `[[note-id]]` no Sources section; inline → `[N]` + Sources section; none → no markers)- No YAML frontmatter, no pipeline vocabulary, no scaffold leaks---diff --git a/src/hyperresearch/skills/hyperresearch-12-critics.md b/src/hyperresearch/skills/hyperresearch-12-critics.mdindex 40e92db..d47d3f8 100644--- a/src/hyperresearch/skills/hyperresearch-12-critics.md+++ b/src/hyperresearch/skills/hyperresearch-12-critics.md@@ -21,7 +21,7 @@ description: >Read these inputs:- `research/scaffold.md` — vault_tag- `research/prompt-decomposition.json` — pipeline_tier, atomic items-- `research/notes/final_report.md` — merged draft from step 10+- `research/notes/final_report_<vault_tag>.md` — merged draft from step 10- `research/query-<vault_tag>.md` — canonical research query---@@ -45,11 +45,11 @@ Read these inputs:PIPELINE POSITION: You are step 12 (<critic-name> critic) of thehyperresearch V8 pipeline. Step 11 (synthesizer) produced the final report at- research/notes/final_report.md. After you return, step 13 may run a+ research/notes/final_report_<vault_tag>.md. After you return, step 13 may run agap-fetch wave, then step 14 (patcher) applies findings as Edit hunks.YOUR INPUTS:- - draft_path: research/notes/final_report.md+ - draft_path: research/notes/final_report_<vault_tag>.md- output_path: research/critic-findings-<critic-name>.json- vault_tag: <vault_tag>- decomposition_path: research/prompt-decomposition.json (instruction-critic only)diff --git a/src/hyperresearch/skills/hyperresearch-14-patcher.md b/src/hyperresearch/skills/hyperresearch-14-patcher.mdindex 0eafe48..66f3836 100644--- a/src/hyperresearch/skills/hyperresearch-14-patcher.md+++ b/src/hyperresearch/skills/hyperresearch-14-patcher.md@@ -21,7 +21,7 @@ description: >Read these inputs:- `research/scaffold.md` — vault_tag-- `research/notes/final_report.md` — the synthesized final report from step 11+- `research/notes/final_report_<vault_tag>.md` — the synthesized final report from step 11- All `research/critic-findings-*.json` files (count depends on tier)- `research/temp/evidence-digest.md` — patcher's primary citation source- `research/query-<vault_tag>.md` — canonical research query@@ -80,7 +80,7 @@ prompt: |You are TOOL-LOCKED to [Read, Edit] — you cannot Write.YOUR INPUTS:- - draft_path: research/notes/final_report.md+ - draft_path: research/notes/final_report_<vault_tag>.md- findings_paths: [research/critic-findings-dialectic.json, (full tier only)research/critic-findings-depth.json, (full tier only)@@ -123,7 +123,7 @@ The patcher populates `orchestrator_escalated` with findings where `requires_orcFor each entry:1. Read the `issue` field to understand which H2 in the draft needs to move, be added, or be renamed.-2. Apply the restructure via hand-written Edit calls on `research/notes/final_report.md`. You have Write and Edit access — the tool lock applies only to the patcher and polish auditor subagents.+2. Apply the restructure via hand-written Edit calls on `research/notes/final_report_<vault_tag>.md`. You have Write and Edit access — the tool lock applies only to the patcher and polish auditor subagents.3. Preserve the body content within each H2 section — you are moving / renaming / inserting headings, not regenerating prose. If a new heading is added and its body needs fresh content, write a short evidence-grounded paragraph for it.4. Log changes in `research/orchestrator-restructure-log.md` (plain markdown, one bullet per change) so downstream lint rules can see this step happened.5. Never regenerate a whole section or the whole draft. The "patch not regenerate" invariant still binds you — broader tools but not broader license.@@ -132,7 +132,7 @@ For each entry:## Constraints-- **Do not apply revisions yourself in step 14.2.** You MUST spawn the patcher subagent. Do NOT call Edit directly on `research/notes/final_report.md` — the patcher has the tool-lock invariants (surgical-edit discipline, conflict resolution, integrate-don't-caveat rule) baked into its prompt. Bypassing it defeats the entire adversarial-review architecture. If the patcher returns empty, re-spawn it once — don't fall back to doing the work yourself unless step 14.4 escalations require it.+- **Do not apply revisions yourself in step 14.2.** You MUST spawn the patcher subagent. Do NOT call Edit directly on `research/notes/final_report_<vault_tag>.md` — the patcher has the tool-lock invariants (surgical-edit discipline, conflict resolution, integrate-don't-caveat rule) baked into its prompt. Bypassing it defeats the entire adversarial-review architecture. If the patcher returns empty, re-spawn it once — don't fall back to doing the work yourself unless step 14.4 escalations require it.- **Do not re-spawn the patcher on the same findings** unless you've modified the findings. The patcher's second run on identical input is a waste.@@ -143,7 +143,7 @@ For each entry:- `research/patch-log.json` exists with `total_findings` set and at least one of `applied` / `skipped` / `conflicts` populated- All critical findings either applied or resolved by orchestrator- All `orchestrator_escalated` findings handled (with `research/orchestrator-restructure-log.md` if any structural restructures were applied)-- `research/notes/final_report.md` has been edited (or no edits needed if findings were trivial)+- `research/notes/final_report_<vault_tag>.md` has been edited (or no edits needed if findings were trivial)---diff --git a/src/hyperresearch/skills/hyperresearch-15-polish.md b/src/hyperresearch/skills/hyperresearch-15-polish.mdindex bca5df4..832d353 100644--- a/src/hyperresearch/skills/hyperresearch-15-polish.md+++ b/src/hyperresearch/skills/hyperresearch-15-polish.md@@ -21,7 +21,7 @@ description: >## Recover stateRead these inputs:-- `research/notes/final_report.md` — the patched draft from step 14 (or single-pass draft for light tier)+- `research/notes/final_report_<vault_tag>.md` — the patched draft from step 14 (or single-pass draft for light tier)- `research/query-<vault_tag>.md` — canonical research query---@@ -56,12 +56,12 @@ prompt: |[Read, Edit].YOUR INPUTS:- - draft_path: research/notes/final_report.md+ - draft_path: research/notes/final_report_<vault_tag>.md- polish_log_path: research/polish-log.json (already stubbed)```The polish auditor strips:-- Pipeline reference leaks (`[[interim-*]]` wikilinks, `[I\d+]` references) — converted to proper citations or deleted depending on `citation_style`+- **Pipeline reference leaks**: `[I\d+]` references, `[[interim-*]]` wiki-links pointing at workspace artifacts (NOT source notes), references to scaffold/comparisons/synthesis-plan files in prose. **Citation wiki-links** of the form `[[<source-note-id>]]` (where the target is a real source note in the vault, not an interim/scaffold workspace file) are PRESERVED when `citation_style == "wikilink"` — they are the citation system, not a leak. Strip wikilinks only when `citation_style` is `"inline"` or `"none"`.- Hygiene leaks (YAML frontmatter, scaffold sections, prompt echoes)- Filler phrases ("It is worth noting", "Importantly", etc.)- Redundant sentences / paragraphs that restate prior content@@ -136,7 +136,7 @@ If any artifact is missing, the responsible step failed silently. Re-spawn the r## Step 15.6 — Ship-The final report lives at `research/notes/final_report.md`. The wrapper's required save path (if any) is a separate copy — handle per the wrapper contract.+The final report lives at `research/notes/final_report_<vault_tag>.md`. The wrapper's required save path (if any) is a separate copy — handle per the wrapper contract.---@@ -145,7 +145,7 @@ The final report lives at `research/notes/final_report.md`. The wrapper's requir- `research/polish-log.json` populated- Final integrity gate passed (or stub-filled with documented failure)- Lint gate passed-- `research/notes/final_report.md` is the final, shippable artifact+- `research/notes/final_report_<vault_tag>.md` is the final, shippable artifact---diff --git a/src/hyperresearch/skills/hyperresearch-16-readability-audit.md b/src/hyperresearch/skills/hyperresearch-16-readability-audit.mdindex 19c3893..fbf8f91 100644--- a/src/hyperresearch/skills/hyperresearch-16-readability-audit.md+++ b/src/hyperresearch/skills/hyperresearch-16-readability-audit.md@@ -26,7 +26,7 @@ description: >Read these inputs:- `research/scaffold.md` — vault_tag-- `research/notes/final_report.md` — the polished final report from step 15+- `research/notes/final_report_<vault_tag>.md` — the polished final report from step 15---@@ -45,7 +45,7 @@ prompt: |PIPELINE POSITION: You are step 16 of the hyperresearch V8 pipeline —the final analytical pass. The final report at- research/notes/final_report.md has been drafted (step 10),+ research/notes/final_report_<vault_tag>.md has been drafted (step 10),synthesized (step 11), critiqued (step 12), gap-filled (step 13),patched (step 14), and polish-audited (step 15). Your job: writeJSON recommendations for paragraph rhythm, list/table conversions,@@ -54,7 +54,7 @@ prompt: |reads your recommendations and decides which to apply.YOUR INPUTS:- - draft_path: research/notes/final_report.md+ - draft_path: research/notes/final_report_<vault_tag>.md- recommendations_path: research/readability-recommendations.jsonWrite recommendations as a JSON array per the schema in your agent@@ -108,7 +108,7 @@ You are not obligated to apply every recommendation. Use these heuristics:For each recommendation you decide to apply:-1. Use the Edit tool on `research/notes/final_report.md`+1. Use the Edit tool on `research/notes/final_report_<vault_tag>.md`2. `old_string` = the recommendation's `current` field (exactly as the recommender wrote it)3. `new_string` = the recommendation's `recommended` field@@ -152,7 +152,7 @@ This is the audit trail. If a future review finds a readability problem we shoul- `research/readability-recommendations.json` exists- `research/readability-decisions.json` exists with at least one entry in `applied` or all `skipped`-- `research/notes/final_report.md` reflects the applied recommendations+- `research/notes/final_report_<vault_tag>.md` reflects the applied recommendations- The final report's structure (H2 list, executive summary, conclusion) is unchanged from step 15's output (this step does not restructure)---diff --git a/src/hyperresearch/skills/hyperresearch.md b/src/hyperresearch/skills/hyperresearch.mdindex ad49ae3..45c3100 100644--- a/src/hyperresearch/skills/hyperresearch.md+++ b/src/hyperresearch/skills/hyperresearch.md@@ -167,8 +167,8 @@ Context compaction may eat parts of this conversation. If you're unsure what ste- Step 7: `research/temp/source-tensions.json`- Step 8: `research/corpus-critic-gaps.json`, `research/temp/corpus-critic-results.md`- Step 9: `research/temp/evidence-digest.md`- - Step 10: `research/temp/draft-{a,b,c}.md` (or `research/notes/final_report.md` for light tier single-pass)- - Step 11: `research/temp/synthesis-plan.md`, `research/temp/synthesis-outline.md`, `research/temp/synthesis-pass1.md`, `research/notes/final_report.md`+ - Step 10: `research/temp/draft-{a,b,c}.md` (or `research/notes/final_report_<vault_tag>.md` for light tier single-pass)+ - Step 11: `research/temp/synthesis-plan.md`, `research/temp/synthesis-outline.md`, `research/temp/synthesis-pass1.md`, `research/notes/final_report_<vault_tag>.md`- Step 12: `research/critic-findings-{dialectic,depth,width,instruction}.json`- Step 13: `research/temp/post-critic-fetch-log.md`- Step 14: `research/patch-log.json` (and edited final_report.md)@@ -206,7 +206,7 @@ $HPR lint --rule scaffold-prompt --json$HPR lint --rule patch-surgery --json```-If any rule returns `error` severity issues, address them before declaring complete. Then ship: the final report lives at `research/notes/final_report.md`.+If any rule returns `error` severity issues, address them before declaring complete. Then ship: the final report lives at `research/notes/final_report_<vault_tag>.md`.---@@ -221,7 +221,7 @@ If any rule returns `error` severity issues, address them before declaring compl7. **Canonical research query is gospel everywhere.** Every subagent gets the verbatim query.8. **Hygiene rules apply to the final report only.** Workspace artifacts (scaffold, loci JSONs, interim notes, comparisons.md, patch log) can look however they need to look.9. **NEVER skip a step that the tier gate says to run.** For `full` tier, ALL 16 steps run. For `light`, the prescribed 5 steps run.-10. **Step 10 triple-draft ensemble is MANDATORY for `full` tier.** You MUST spawn 3 `hyperresearch-draft-orchestrator` subagents. Writing `research/notes/final_report.md` directly in step 10 (instead of going through the synthesizer in step 11) is a PIPELINE VIOLATION for these tiers.+10. **Step 10 triple-draft ensemble is MANDATORY for `full` tier.** You MUST spawn 3 `hyperresearch-draft-orchestrator` subagents. Writing `research/notes/final_report_<vault_tag>.md` directly in step 10 (instead of going through the synthesizer in step 11) is a PIPELINE VIOLATION for these tiers.11. **Step 11 synthesis is MANDATORY for `full` tier.** The synthesizer subagent (Read+Write tool-locked) writes the final report from the 3 drafts. The orchestrator does NOT write the final report itself for these tiers.12. **Subagents read full source text.** Draft sub-orchestrators MUST batch-read every note in their `must_read_note_ids` list before writing. Fetchers MUST chase 3-8 primary sources via citation chains.13. **NEVER emit a bare text response while subagent tasks are in flight.**