Skip to content

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

v0.8.5: reports self-title by vault_tag, wikilinks as default citation system (#22)

Jordan Gibbs067a4c2a3683
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 plumbing
diff --git a/pyproject.toml b/pyproject.toml
index 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__.py
index 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.py
index 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 = None
if 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 == 0
and 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.py
index 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.py
index 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), 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
+`research/notes/final_report_<vault_tag>.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.
@@ -573,7 +573,7 @@ actually gathered, not guesses.
`research/query-<vault_tag>.md`). Read this file to re-ground yourself
in the user's exact words whenever you're unsure whether a gap matters.
- **draft_path**: path to the Layer 4 draft (typically
- `research/notes/final_report.md`).
+ `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 a
shallow spot matters — if the user's exact words ask about a topic,
shallow treatment is major; if the topic is tangential, it's minor.
-- **draft_path**: `research/notes/final_report.md`
+- **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 every
noun phrase the user mentioned. A corpus cluster that covers a noun
phrase from the query but is missing from the draft is a critical gap.
-- **draft_path**: `research/notes/final_report.md`
+- **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 the
prompt named: explicit sub-questions, required entities, required
formats, 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 about
whether 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 a
specific number — don't rewrite paragraphs.
- e. Integrate evidence as authoritative prose. Use `[N]` citation
- markers if `citation_style` is `"inline"`, no markers if `"none"`.
+ 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 section
intact — 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 at
least 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 3
one angle-specific draft (`draft-a.md`, `draft-b.md`, `draft-c.md`). The
main orchestrator wrote a synthesis plan and outline (steps 11.3 and
11.4). You consume all of that and produce the final report at
-`research/notes/final_report.md`.
+`research/notes/final_report_<vault_tag>.md`.
After you: step 12 (4 adversarial critics) reads your final report and
produces 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` — where
you 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 you
write 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; you
create it).
diff --git a/src/hyperresearch/skills/hyperresearch-1-decompose.md b/src/hyperresearch/skills/hyperresearch-1-decompose.md
index 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.md
index 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.md
index 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 1
for redundancy, voice consistency, weak sections, and length, and
write the cleaned pass 2 to final_output_path. Do not paste paragraphs
from the input drafts — synthesize them in your own voice.
+
+ **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 vocabulary
If pass 2 is longer than pass 1 (positive delta), something went wrong — pass 2 is supposed to cut. Investigate before proceeding.
-If a sanity check fails, hand-craft an Edit on `research/notes/final_report.md` yourself to fix it. Do NOT re-spawn the synthesizer — that's regeneration, which violates the patch-not-regenerate invariant once we have a final draft.
+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.md
index 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 the
hyperresearch V8 pipeline. Step 11 (synthesizer) produced the final report at
- research/notes/final_report.md. After you return, step 13 may run a
+ research/notes/final_report_<vault_tag>.md. After you return, step 13 may run a
gap-fetch wave, then step 14 (patcher) applies findings as Edit hunks.
YOUR INPUTS:
- - draft_path: research/notes/final_report.md
+ - 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.md
index 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_orc
For each entry:
1. Read the `issue` field to understand which H2 in the draft needs to move, be added, or be renamed.
-2. Apply the restructure via hand-written Edit calls on `research/notes/final_report.md`. You have Write and Edit access — the tool lock applies only to the patcher and polish auditor subagents.
+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.md
index 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 state
Read 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.md
index 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: write
JSON 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.json
Write 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.md
index 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 compl
7. **Canonical research query is gospel everywhere.** Every subagent gets the verbatim query.
8. **Hygiene rules apply to the final report only.** Workspace artifacts (scaffold, loci JSONs, interim notes, comparisons.md, patch log) can look however they need to look.
9. **NEVER skip a step that the tier gate says to run.** For `full` tier, ALL 16 steps run. For `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.**