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

fix: resolve $HPR in skills, route OA URLs through the SSRF gate, Python 3.14 (#141)

Jordan Gibbsd329565d3fa0
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5d0ad15..4265ed2 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -18,7 +18,7 @@ jobs:
fail-fast: false
matrix:
os: [ubuntu-latest]
- python-version: ["3.11", "3.12", "3.13"]
+ python-version: ["3.11", "3.12", "3.13", "3.14"]
include:
# The maintainer develops on Windows; socket, path and signal
# semantics differ enough (#104) that ubuntu-only checks cannot
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6daeb17..9278b64 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,11 @@
- **Note ids are fixed points of the slugifier, and the link validator rejects shell fragments and traversal (#126, from @fduple).** `write_note` built the filename from the raw id while the frontmatter id was slugified, and `repair` / `graph stub` pass broken-link text through as the id, so fetched content chose the path: `[[../../outside]]` wrote outside the vault, and `[[-n "$kernel"]]` crashed on Windows. Stub files now get slug filenames. `is_valid_wiki_link_target` also refuses targets containing `$ " \` = \ < > ;`, a leading `-` or `!`, or a `.`/`..` segment. Slug ids never contain those, but a title or alias link such as `[[E=mc2]]` that used to resolve by title will drop out of the links table on the next sync.
- **`note mv` keeps notes where sync can see them (#128, from @fduple).** The destination was joined onto the vault root verbatim, so a bare name landed at the root with no `.md` and left the index, `../x.md` wrote outside the vault, and an existing file was overwritten (POSIX) or crashed the command (Windows). A bare name now lands in `research/notes/` with `.md` added; destinations outside `research/notes/` and `research/temp/` are refused with `OUTSIDE_SYNCED_TREE`, and an existing file with `DESTINATION_EXISTS`. `research/index/` is refused too, since `repair` regenerates it and deletes every `.md` there. Case-only renames work on case-insensitive filesystems. The docstring no longer claims `mv` updates references; the id lives in frontmatter, so it never needed to.
- **The builtin provider keeps fetched code as markdown code (#129, from @fduple).** `<pre>` blocks and inline `<code>` were flattened to prose, so bash test syntax (`[[ -n "$k" ]]`) reached the wiki-link parser and `repair` minted stub notes named after shell fragments. `<pre>` now becomes a fenced block whose fence outruns any backtick run inside it, inline `<code>` becomes a backtick span, and indentation survives in the stdlib fallback. Because `strip_markdown` drops code before indexing, code on builtin-fetched pages is no longer in full-text search, embeddings, or the quote-integrity comparison, which is how crawl4ai-fetched pages already behaved. A report that quotes a sentence containing an inline identifier can now fail quote integrity where it passed before.
+- **Skills name the CLI by its resolved path (#133, reported by @blrain3).** 14 of the 19 installed skills spelled the CLI `$HPR`, which nothing defined, so `$HPR run finish <tag>` (the ship gate) ran as `run finish` and the shell answered `command not found`. Skills now carry the `{hpr_path}` placeholder the agent prompts already used, and `install` (including `install --steps-only`, the entry skill's bootstrap) fills it with the same absolute path CLAUDE.md shows. The corpus-critic step had one literal `{hpr_path}` that was never substituted; it resolves now too. Re-run `hyperresearch install` to pick this up.
+- **The open-access URL gate uses the SSRF gate's address rules (#138).** `check_oa_url` classified resolved addresses with `is_global`, which on Python 3.11 passes IPv4-mapped and 6to4-wrapped CGNAT (`::ffff:100.64.0.1`, `2002:6440:1::`) — the addresses #127 closed on the fetch path. It now calls `safe_http.check_url` after its own credential and bare-hostname checks, and ignores `allow_private_hosts`. Europe PMC JATS downloads now go through `safe_get`, so a redirect to a private host is refused instead of followed.
+- **Cite-check samples at the configured rate.** `sample_needs_llm` kept every `round(1 / rate)`-th weak pair, so the default 0.6 sampled 50% and 0.3 sampled 33%. It now keeps exactly `rate` of them, spread evenly, still without an RNG.
+- **Python 3.14 (#81, requested by @cjangrist).** `requires-python` is now `<3.15`, and CI runs 3.14. No code changes were needed; the full suite passes on 3.14.2.
+- **The dissertation tier is labelled experimental (#103).** Its word, read-budget and citation targets are defined in the profile but no prompt or check reads them. README and the router now say so, and the router tells the orchestrator to warn the user before starting one.
## [0.11.1] - 2026-09-11
diff --git a/README.md b/README.md
index 869a8a8..0ce5bf3 100644
--- a/README.md
+++ b/README.md
@@ -29,7 +29,7 @@
- **Paywalled papers get read, not skimmed.** A closed paper normally enters a vault as a 1,500-character abstract that the report then cites as though it had been read. Hyperresearch asks Unpaywall, Europe PMC and CORE for a legal open-access copy and stores the full text instead, even when the publisher blocks the fetch outright. Every substitution is disclosed in the note, the frontmatter, and the CLI output.
- **Nothing is thrown away.** Every source lands in a searchable markdown-plus-SQLite vault that your next session reuses before it fetches anything new.
- **Crashed runs resume.** Each run keeps a manifest; `run resume` picks up at the exact step where it died.
-- **Scales from 30 minutes to a dissertation.** Bounded queries auto-route to a 5-step fast path. Opt-in dissertation runs write 25K–80K words across chapters, from 300–450 sources.
+- **Scales from 30 minutes to a dissertation.** Bounded queries auto-route to a 5-step fast path. Opt-in dissertation runs (experimental) write 25K–80K words across chapters, from 300–450 sources.
## Install
@@ -40,7 +40,7 @@ pip install hyperresearch && hyperresearch install
Then `/hyperresearch <anything>` in Claude Code.
-> Python 3.11–3.13. (3.14 not yet supported. Use `pyenv install 3.13`, `uv venv -p 3.13`, or `py -3.13 -m venv .venv`.)
+> Python 3.11–3.14.
>
> Power users: `hyperresearch install --global` makes `/hyperresearch` reachable from every Claude Code session anywhere, at the cost of ~15 lines in every session's system reminder. Per-project install (above) keeps unrelated CC sessions clean.
@@ -73,13 +73,13 @@ The entry skill is a thin router. It pins down the canonical research query, the
### Tiers and gears: the two scale levers
-**Tiers** route per query. Step 1 auto-classifies `light` vs `full`. `dissertation` is opt-in only; ask for it in your prompt.
+**Tiers** route per query. Step 1 auto-classifies `light` vs `full`. `dissertation` is opt-in only; ask for it in your prompt. It is experimental: its length, read-budget and citation targets are configured but not yet wired in ([#103](https://github.com/jordan-gibbs/hyperresearch/issues/103)).
| Tier | What runs | Typical time |
|---|---|---|
| `light` | bounded factual queries, surveys, comparisons: 1 → 2 → 10 → 15 → 16 | ~30–40 min |
| `full` (default) | deep argumentative analysis with adversarial review: all 16 steps + cite-check | ~1.5–2.5 h at `full` gear |
-| `dissertation` | chaptered mega-runs: 300–450 sources across 4–10 chapters, 25K–80K words | ~4–8 hours |
+| `dissertation` (experimental) | chaptered mega-runs: 300–450 sources across 4–10 chapters, 25K–80K words | ~4–8 hours |
**Gears** set the scale of the standard pipeline: the source targets, depth budgets, and word targets rendered into the step skills.
diff --git a/pyproject.toml b/pyproject.toml
index 87886d6..3ee2c0b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -8,7 +8,7 @@ version = "0.11.1"
description = "Claude Code harness for disciplined, adversarially-audited deep research with full provenance."
readme = "README.md"
license = "MIT"
-requires-python = ">=3.11,<3.14"
+requires-python = ">=3.11,<3.15"
authors = [{name = "Jordan Gibbs", email = "[email protected]"}]
keywords = ["research", "knowledge-base", "wiki", "llm", "markdown", "cli", "agent", "zettelkasten"]
classifiers = [
@@ -19,6 +19,7 @@ classifiers = [
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: 3.13",
+ "Programming Language :: Python :: 3.14",
"Topic :: Text Processing :: Markup :: Markdown",
]
dependencies = [
diff --git a/src/hyperresearch/cli/install.py b/src/hyperresearch/cli/install.py
index 30b44f9..f6632fb 100644
--- a/src/hyperresearch/cli/install.py
+++ b/src/hyperresearch/cli/install.py
@@ -78,7 +78,9 @@ def install(
steps_profile = _default_profile(steps_config_path)
_check_profile(steps_profile, steps_config_path)
_set_render_state(steps_profile, steps_config_path)
- result = _install_hyperresearch_step_skills(target)
+ from hyperresearch.core.agent_docs import _resolve_executable
+
+ result = _install_hyperresearch_step_skills(target, _resolve_executable())
if json_output:
output(
success({"steps_installed": result, "target": str(target)}, vault=None),
diff --git a/src/hyperresearch/cli/lint.py b/src/hyperresearch/cli/lint.py
index cd29f81..ea70209 100644
--- a/src/hyperresearch/cli/lint.py
+++ b/src/hyperresearch/cli/lint.py
@@ -973,7 +973,7 @@ def lint(
f"Vault has {len(source_rows)} fetched source notes but ZERO "
f"`*Suggested by [[...]]` breadcrumbs. The bouncing reading loop never "
f"fired — every fetch was a flat batch with no link back to the source "
- f"that proposed it. Use `$HPR fetch ... --suggested-by <source-note-id> "
+ f"that proposed it. Use `hyperresearch fetch ... --suggested-by <source-note-id> "
f"--suggested-by-reason \"<why>\"` for every follow-up fetch."
),
})
@@ -1801,7 +1801,7 @@ def lint(
f"The finding was '{guard['description']}'. The draft's `fixed_at` "
f"marker does not match the vault's actual state — you must fix the "
f"underlying issue (not just the bookkeeping). Run "
- f"`$HPR lint --rule {guard['rule']} -j` to see what's still broken."
+ f"`hyperresearch lint --rule {guard['rule']} -j` to see what's still broken."
),
})
diff --git a/src/hyperresearch/core/citecheck.py b/src/hyperresearch/core/citecheck.py
index bf6ab03..3737708 100644
--- a/src/hyperresearch/core/citecheck.py
+++ b/src/hyperresearch/core/citecheck.py
@@ -175,21 +175,24 @@ def triage_pairs(pairs: list[dict], conn) -> dict:
def sample_needs_llm(pairs: list[dict], sample_rate: float = 0.6) -> list[dict]:
"""Deterministic sampling of the LLM tier: 100% of strong (number-bearing)
- sentences, every k-th of the rest. No RNG — reproducible across resumes."""
+ sentences, `sample_rate` of the rest. No RNG — reproducible across resumes.
+
+ A weak pair is kept whenever floor(seen * rate) steps up, which spreads the
+ kept pairs evenly and hits the rate exactly. The old every-k-th rule
+ rounded 1/rate, so 0.6 became every 2nd and sampled 50%.
+ """
out = []
- weak_kept = 0
weak_seen = 0
- keep_every = max(1, round(1 / sample_rate)) if sample_rate > 0 else 0
+ rate = min(max(sample_rate, 0.0), 1.0)
for pair in pairs:
if pair.get("verdict") != "needs-llm":
continue
if pair["strong"]:
out.append(pair)
- elif keep_every:
- weak_seen += 1
- if weak_seen % keep_every == 0:
- out.append(pair)
- weak_kept += 1
+ continue
+ weak_seen += 1
+ if int(weak_seen * rate) > int((weak_seen - 1) * rate):
+ out.append(pair)
return out
diff --git a/src/hyperresearch/core/hooks.py b/src/hyperresearch/core/hooks.py
index d05dd29..8d80903 100644
--- a/src/hyperresearch/core/hooks.py
+++ b/src/hyperresearch/core/hooks.py
@@ -39,13 +39,19 @@ def _get_render_state() -> dict:
return _RENDER_STATE
-def _render_installed(content: str) -> str:
- """Render a prompt template and stamp the provenance header."""
+def _render_installed(content: str, hpr_path: str = "hyperresearch") -> str:
+ """Render a prompt template, resolve `{hpr_path}`, and stamp the provenance header.
+
+ Skills spell the CLI `{hpr_path}`, the placeholder the agent prompts fill
+ with `.format()`. Skills carry literal braces elsewhere, so this is a plain
+ replace rather than a format call.
+ """
from hyperresearch import __version__
from hyperresearch.core.render import insert_after_frontmatter, render_header, render_prompt
state = _get_render_state()
rendered = render_prompt(content, state["context"])
+ rendered = rendered.replace("{hpr_path}", hpr_path.replace("\\", "/"))
header = render_header(state["profile_name"], __version__)
return insert_after_frontmatter(rendered, header)
@@ -3587,8 +3593,8 @@ def install_hooks(
for installer in (
lambda: _install_claude_hook(vault_root, hpr_path),
- lambda: _install_hyperresearch_skill(vault_root),
- lambda: _install_hyperresearch_step_skills(vault_root),
+ lambda: _install_hyperresearch_skill(vault_root, hpr_path),
+ lambda: _install_hyperresearch_step_skills(vault_root, hpr_path),
lambda: _install_researcher_agent(vault_root, hpr_path),
lambda: _install_loci_analyst_agent(vault_root, hpr_path),
lambda: _install_depth_investigator_agent(vault_root, hpr_path),
@@ -3649,7 +3655,7 @@ def install_global_hooks(
actions = []
for installer in (
- lambda: _install_hyperresearch_skill(home),
+ lambda: _install_hyperresearch_skill(home, hpr_path),
lambda: _install_researcher_agent(home, hpr_path),
lambda: _install_loci_analyst_agent(home, hpr_path),
lambda: _install_depth_investigator_agent(home, hpr_path),
@@ -4096,7 +4102,7 @@ def _read_skill_source(src_name: str) -> str | None:
return None
-def _install_hyperresearch_skill(vault_root: Path) -> str | None:
+def _install_hyperresearch_skill(vault_root: Path, hpr_path: str = "hyperresearch") -> str | None:
"""Install the entry skill at .claude/skills/hyperresearch/SKILL.md.
Claude Code registers `/hyperresearch` as the slash-command trigger via
@@ -4106,7 +4112,7 @@ def _install_hyperresearch_skill(vault_root: Path) -> str | None:
content = _read_skill_source("hyperresearch.md")
if content is None:
return None
- content = _render_installed(content)
+ content = _render_installed(content, hpr_path)
skill_dir = vault_root / ".claude" / "skills" / "hyperresearch"
skill_dir.mkdir(parents=True, exist_ok=True)
@@ -4169,7 +4175,9 @@ def step_skill_slug(step: str | None) -> str | None:
return STEP_SKILL_BY_ID.get(str(step))
-def _install_hyperresearch_step_skills(vault_root: Path) -> str | None:
+def _install_hyperresearch_step_skills(
+ vault_root: Path, hpr_path: str = "hyperresearch"
+) -> str | None:
"""Install the 16 V8 step skills, each as its own Claude Code skill directory.
Each step skill lives at `.claude/skills/hyperresearch-N-name/SKILL.md` and is
@@ -4194,7 +4202,7 @@ def _install_hyperresearch_step_skills(vault_root: Path) -> str | None:
content = _read_skill_source(src_name)
if content is None:
continue
- content = _render_installed(content)
+ content = _render_installed(content, hpr_path)
skill_dir = skills_root / skill_name
skill_dir.mkdir(parents=True, exist_ok=True)
diff --git a/src/hyperresearch/core/oa.py b/src/hyperresearch/core/oa.py
index 4d1b635..91775fe 100644
--- a/src/hyperresearch/core/oa.py
+++ b/src/hyperresearch/core/oa.py
@@ -65,7 +65,6 @@ network.
from __future__ import annotations
import ipaddress
-import socket
import sqlite3
from collections.abc import Iterator
from dataclasses import dataclass
@@ -135,14 +134,15 @@ def check_oa_url(url: str) -> tuple[bool, str]:
"""Gate a resolver-supplied URL before fetching it. Returns (ok, reason).
The URL comes out of a third-party API response, so a poisoned DOI record
- can steer the fetcher at internal infrastructure. This is a deliberately
- narrow SSRF check: scheme, no credentials in the netloc, and every address
- the host resolves to must be publicly routable.
-
- NOTE: this duplicates the intent of `web.safe_http.check_url` (PR #53).
- When that lands, collapse this into a call to it — the version there does
- redirect revalidation too, which this one cannot.
+ can steer the fetcher at internal infrastructure. Address classification
+ is `web.safe_http.check_url`'s, so this refuses whatever the fetch gate
+ refuses (mapped and 6to4-wrapped private ranges included, #138). On top
+ of that it refuses embedded credentials and bare hostnames, and it
+ ignores `allow_private_hosts`: a user's intranet mirror is never a
+ legitimate open-access location.
"""
+ from hyperresearch.web.safe_http import SafeHTTPError, check_url
+
try:
parsed = urlparse(url)
except ValueError:
@@ -162,19 +162,12 @@ def check_oa_url(url: str) -> tuple[bool, str]:
return False, f"non-public hostname {host!r}"
try:
- infos = socket.getaddrinfo(host, None)
+ check_url(url)
+ except SafeHTTPError as exc:
+ return False, str(exc)
except OSError as exc:
return False, f"DNS resolution failed: {exc}"
- for info in infos:
- addr = info[4][0]
- try:
- ip = ipaddress.ip_address(addr.split("%")[0])
- except ValueError:
- return False, f"unparseable address {addr!r}"
- if not ip.is_global or ip.is_multicast:
- return False, f"host resolves to non-public address {ip}"
-
return True, ""
@@ -532,12 +525,14 @@ def _http_get_text(url: str) -> str | None:
Deliberately NOT routed through `api_cache`: that table is for small JSON
metadata, and the note itself is the cache for full text.
"""
- import httpx
+ from hyperresearch.web.safe_http import MAX_BYTES_PDF, safe_get
+ # safe_get re-checks every redirect hop; `check_oa_url` only saw the
+ # first URL, and a repository redirect is the easy way past it.
try:
- resp = httpx.get(
+ resp = safe_get(
url,
- follow_redirects=True,
+ max_bytes=MAX_BYTES_PDF,
timeout=60,
headers={"User-Agent": "hyperresearch (mailto:[email protected])"},
)
diff --git a/src/hyperresearch/skills/hyperresearch-1-5-chapter-partition.md b/src/hyperresearch/skills/hyperresearch-1-5-chapter-partition.md
index 14e22d3..f2a944d 100644
--- a/src/hyperresearch/skills/hyperresearch-1-5-chapter-partition.md
+++ b/src/hyperresearch/skills/hyperresearch-1-5-chapter-partition.md
@@ -55,13 +55,13 @@ Read these inputs:
4. **Register chapters in the manifest.** For each chapter in the plan:
```bash
- $HPR run event <vault_tag> --type chapter-plan --data '{"chapter": "<id>", "title": "<title>"}' -j
+ {hpr_path} run event <vault_tag> --type chapter-plan --data '{"chapter": "<id>", "title": "<title>"}' -j
```
The `chapter-plan` event is the registration: `run event` folds it into the manifest's `chapters` table (status `planned`), which is what `run status` / `run resume` read as `chapters_pending`. A chapter stays pending until its step 10 is recorded done with `--chapter <id>`. Then close the step:
```bash
- $HPR run step <vault_tag> 1.5 --status done -j
+ {hpr_path} run step <vault_tag> 1.5 --status done -j
```
- Verify before moving on: `$HPR run resume <vault_tag> -j` must list every chapter id under `chapters_pending`. An empty list here means the chapters were never registered and a resumed run would think there is nothing left to do.
+ Verify before moving on: `{hpr_path} run resume <vault_tag> -j` must list every chapter id under `chapters_pending`. An empty list here means the chapters were never registered and a resumed run would think there is nothing left to do.
5. **Chapter tagging convention.** Every note fetched or written for a chapter carries BOTH tags: `<vault_tag>` and `<vault_tag>-<id>` (e.g. `china-rail-x9f2a1-ch3`). Whole-run queries use the first; per-chapter queries use the second. Cross-chapter source reuse is free — dedup is by URL, and a chapter's coverage check searches the whole `<vault_tag>` corpus before fetching.
@@ -76,10 +76,10 @@ For each chapter (respecting `depends_on`, up to << dissertation.chapter_concurr
- Artifact paths swap `research/runs/<vault_tag>/` for `research/runs/<vault_tag>/chapters/<id>/` (each chapter has its own loci.json, comparisons.md, temp/).
- Source targets come from `chapter_source_target`, not the global `source_target`.
- Step 10 writes ONE draft per chapter to `research/runs/<vault_tag>/chapters/<id>/draft.md` (draft_count is 1 for chaptered profiles — angle diversity comes from the chapters themselves).
-2. Record progress: `$HPR run step <vault_tag> <N> --status done --chapter <id> -j` after each chapter-step completes.
+2. Record progress: `{hpr_path} run step <vault_tag> <N> --status done --chapter <id> -j` after each chapter-step completes.
3. After ALL chapters finish step 10, proceed to the global layers: step 6 re-runs GLOBALLY (cross-CHAPTER tensions from the chapters' comparisons.md files → `research/runs/<vault_tag>/comparisons.md`), then step 11 synthesizes the chapter drafts into the final document (chapter titles become H1s), then steps 12-16 run once against the whole document.
-**Budget check at every chapter boundary:** `$HPR run status <vault_tag> -j`. If `status` is `blocked` with `blocked_on: "budget"`, STOP spawning and surface to the user. Never silently skip profile-mandated steps — shrink the NEXT chapter's fan-out (fewer wave-2 fetchers, lower depth budgets) when `budget_remaining_usd` is under ~30% instead.
+**Budget check at every chapter boundary:** `{hpr_path} run status <vault_tag> -j`. If `status` is `blocked` with `blocked_on: "budget"`, STOP spawning and surface to the user. Never silently skip profile-mandated steps — shrink the NEXT chapter's fan-out (fewer wave-2 fetchers, lower depth budgets) when `budget_remaining_usd` is under ~30% instead.
---
diff --git a/src/hyperresearch/skills/hyperresearch-1-decompose.md b/src/hyperresearch/skills/hyperresearch-1-decompose.md
index cf9d5e1..381405d 100644
--- a/src/hyperresearch/skills/hyperresearch-1-decompose.md
+++ b/src/hyperresearch/skills/hyperresearch-1-decompose.md
@@ -183,7 +183,7 @@ Read both before starting. The vault_tag is in the scaffold's "Run config" secti
10. **Render the lever shims:**
```bash
- $HPR levers render <vault_tag> -j
+ {hpr_path} levers render <vault_tag> -j
```
This writes `research/runs/<vault_tag>/shims/{research,drafting,critics,polish}.md` from the levers block. Later steps paste these files VERBATIM into subagent spawn prompts — you never compose or edit shim text yourself. If the command errors on an enum value, fix the levers block in the decomposition and re-run it.
@@ -194,7 +194,7 @@ Read both before starting. The vault_tag is in the scaffold's "Run config" secti
- `research/runs/<vault_tag>/prompt-decomposition.json` exists, is valid JSON, every atomic item traces to the research_query
- `pipeline_tier` + `response_format` + `citation_style` are all set, and the `levers` block is present (register, domain_notes, inference_depth)
-- `$HPR levers render` succeeded — all four shim files exist under `research/runs/<vault_tag>/shims/`
+- `{hpr_path} levers render` succeeded — all four shim files exist under `research/runs/<vault_tag>/shims/`
- `research/runs/<vault_tag>/temp/coverage-matrix.md` exists with **zero `Gap? = YES` rows**
- `research/runs/<vault_tag>/scaffold.md` includes a Tier rationale subsection
diff --git a/src/hyperresearch/skills/hyperresearch-10-triple-draft.md b/src/hyperresearch/skills/hyperresearch-10-triple-draft.md
index 62da2bb..c273170 100644
--- a/src/hyperresearch/skills/hyperresearch-10-triple-draft.md
+++ b/src/hyperresearch/skills/hyperresearch-10-triple-draft.md
@@ -30,7 +30,7 @@ Read these inputs:
- `research/runs/<vault_tag>/comparisons.md` (full tier) — cross-locus tensions
- `research/runs/<vault_tag>/temp/source-tensions.json` (full tier) — expert disagreements
- `research/runs/<vault_tag>/temp/coverage-gaps.md` (if exists) — items with weak source coverage
-- Survey vault: `$HPR note list --tag <vault_tag> --all -j` for the evidence landscape
+- Survey vault: `{hpr_path} note list --tag <vault_tag> --all -j` for the evidence landscape
- Modality calibration (from the scaffold's `modality` field):
- **collect** — enumerative coverage, per-entity sections with named fields
- **synthesize** — defended thesis with evidence chains, interpretive density
@@ -59,7 +59,7 @@ If `pipeline_tier == "light"`: SKIP step 10.1 — 10.3 below and follow this sec
**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 note list --tag <vault_tag> --all -j` and pick the << p.single_draft_reads|dash >> most relevant non-deprecated notes. Read each one (`$HPR note show <id1> <id2> ... -j`) before writing.
+1. **Read the vault directly.** Light tier has no `evidence-digest.md` (step 9 was skipped). Survey the vault: `{hpr_path} note list --tag <vault_tag> --all -j` and pick the << p.single_draft_reads|dash >> most relevant non-deprecated notes. Read each one (`{hpr_path} note show <id1> <id2> ... -j`) before writing.
2. **Honor the structural contract.**
- Use the literal H2 headings from `required_section_headings` in `research/runs/<vault_tag>/prompt-decomposition.json`, in order.
@@ -101,13 +101,13 @@ Write the 3 angle assignments to `research/runs/<vault_tag>/temp/draft-angles.md
1. **List all substantive vault notes:**
```bash
- $HPR note list --tag <vault_tag> --all --json
+ {hpr_path} note list --tag <vault_tag> --all --json
```
Filter to non-deprecated notes. You should have 50-100 candidates.
**Rank the pool before picking.** For each atomic item, run a quality-ranked search to surface the best-evidence sources first:
```bash
- $HPR search "<atomic item keywords>" --tag <vault_tag> --ranked -j
+ {hpr_path} search "<atomic item keywords>" --tag <vault_tag> --ranked -j
```
`--ranked` folds the composite `quality_score` (tier + utility + citation authority + vault centrality, retractions floored) into relevance. Prefer high-quality sources when two candidates cover the same ground; a note with `quality_score` near the retraction floor should not appear in any must_read list unless the draft explicitly discusses its retraction.
diff --git a/src/hyperresearch/skills/hyperresearch-11-synthesize.md b/src/hyperresearch/skills/hyperresearch-11-synthesize.md
index 62fad4c..5d66fcd 100644
--- a/src/hyperresearch/skills/hyperresearch-11-synthesize.md
+++ b/src/hyperresearch/skills/hyperresearch-11-synthesize.md
@@ -51,7 +51,7 @@ The synthesizer is tool-locked to `[Read, Write]` — it cannot run Bash to quer
For each substantive contradiction between drafts:
1. Identify the cited source IDs on both sides
-2. `$HPR note show <id1> <id2> -j` to read the actual source bodies
+2. `{hpr_path} note show <id1> <id2> -j` to read the actual source bodies
3. Decide which side is correct. Write the verdict to `research/runs/<vault_tag>/temp/synthesis-conflicts.md`:
```markdown
## Conflict 1: <one-line description>
diff --git a/src/hyperresearch/skills/hyperresearch-13-gap-fetch.md b/src/hyperresearch/skills/hyperresearch-13-gap-fetch.md
index 2fa10e0..7596dfd 100644
--- a/src/hyperresearch/skills/hyperresearch-13-gap-fetch.md
+++ b/src/hyperresearch/skills/hyperresearch-13-gap-fetch.md
@@ -34,7 +34,7 @@ Read these inputs:
2. **For each qualifying finding, check whether the vault has evidence.** Run a targeted vault search for the topic the finding names:
```bash
- $HPR search "<finding topic keywords>" --tag <vault_tag> --json
+ {hpr_path} search "<finding topic keywords>" --tag <vault_tag> --json
```
If 2+ relevant notes exist, the patcher can handle it — move on. If 0-1 relevant notes exist, this is a **fetch-worthy gap**.
diff --git a/src/hyperresearch/skills/hyperresearch-14-5-cite-check.md b/src/hyperresearch/skills/hyperresearch-14-5-cite-check.md
index f690c78..c50e482 100644
--- a/src/hyperresearch/skills/hyperresearch-14-5-cite-check.md
+++ b/src/hyperresearch/skills/hyperresearch-14-5-cite-check.md
@@ -29,7 +29,7 @@ Read these inputs:
## Step 14.5.1 — Extract + mechanical triage
```bash
-$HPR citecheck extract <vault_tag> -j
+{hpr_path} citecheck extract <vault_tag> -j
```
This parses every (sentence, citation) pair from the report — `[N]` markers (including grouped `[7, 12]`, one pair per source number) and `[[note-id]]` styles — and auto-passes pairs whose numbers or wording the cited note's extracted claims already confirm. Output: `research/runs/<vault_tag>/cite-check-pairs.json` with:
@@ -39,7 +39,7 @@ This parses every (sentence, citation) pair from the report — `[N]` markers (i
**Dangling citations are findings immediately** — no agent needed. Each one becomes a `critical` finding (fabricated or mangled citation).
-**If `sampled_for_llm` is empty and there are no dangling citations:** write an empty findings file `[]` to `research/runs/<vault_tag>/cite-check-findings.json`, record `$HPR run step <vault_tag> 14.5 --status done -j`, and proceed to step 15. Done.
+**If `sampled_for_llm` is empty and there are no dangling citations:** write an empty findings file `[]` to `research/runs/<vault_tag>/cite-check-findings.json`, record `{hpr_path} run step <vault_tag> 14.5 --status done -j`, and proceed to step 15. Done.
---
@@ -90,7 +90,7 @@ Fix repertoire (in the findings' `suggested_fix`): swap to `correct_note_id`, so
- `research/runs/<vault_tag>/cite-check-pairs.json` exists
- `research/runs/<vault_tag>/cite-check-findings.json` exists (possibly `[]`)
- If findings were non-empty: `cite-check-patch-log.json` shows every `critical` finding applied or escalated
-- Manifest: `$HPR run step <vault_tag> 14.5 --status done -j`
+- Manifest: `{hpr_path} run step <vault_tag> 14.5 --status done -j`
## Next step
diff --git a/src/hyperresearch/skills/hyperresearch-15-polish.md b/src/hyperresearch/skills/hyperresearch-15-polish.md
index 40e5a08..c831f60 100644
--- a/src/hyperresearch/skills/hyperresearch-15-polish.md
+++ b/src/hyperresearch/skills/hyperresearch-15-polish.md
@@ -122,10 +122,10 @@ If any artifact is missing, the responsible step failed silently. Re-spawn the r
2. **Run the lint gate:**
```bash
- $HPR lint --rule wrapper-report --json
- $HPR lint --rule locus-coverage --json
- $HPR lint --rule scaffold-prompt --json
- $HPR lint --rule patch-surgery --json
+ {hpr_path} lint --rule wrapper-report --json
+ {hpr_path} lint --rule locus-coverage --json
+ {hpr_path} lint --rule scaffold-prompt --json
+ {hpr_path} lint --rule patch-surgery --json
```
If any rule returns `error` severity issues, address them before declaring complete:
@@ -134,7 +134,7 @@ If any artifact is missing, the responsible step failed silently. Re-spawn the r
- `scaffold-prompt`: scaffold's User Prompt section doesn't match the query file exactly — fix the scaffold
- `patch-surgery`: draft churn from step 11 → final exceeds the safety threshold — read the patch log and investigate
- These four rules are pre-checks. The BINDING gate is `$HPR run finish <vault_tag>` in the router's final phase — it re-runs the battery (including quote-integrity and retracted-citations) and refuses to mark the run done while any check fails. Gate errors are facts about the report, not opinions to assess: never classify a gate error as a false positive. In particular, quotation marks are reserved for verbatim source text — the fix for a flagged rhetorical/framing quote is removing its quotation marks, not a memo explaining why it's fine.
+ These four rules are pre-checks. The BINDING gate is `{hpr_path} run finish <vault_tag>` in the router's final phase — it re-runs the battery (including quote-integrity and retracted-citations) and refuses to mark the run done while any check fails. Gate errors are facts about the report, not opinions to assess: never classify a gate error as a false positive. In particular, quotation marks are reserved for verbatim source text — the fix for a flagged rhetorical/framing quote is removing its quotation marks, not a memo explaining why it's fine.
---
diff --git a/src/hyperresearch/skills/hyperresearch-2-width-sweep.md b/src/hyperresearch/skills/hyperresearch-2-width-sweep.md
index e532f86..1afb15d 100644
--- a/src/hyperresearch/skills/hyperresearch-2-width-sweep.md
+++ b/src/hyperresearch/skills/hyperresearch-2-width-sweep.md
@@ -121,7 +121,7 @@ Before batching URLs, score each candidate URL on six dimensions (0–3 each, ma
Write to `research/runs/<vault_tag>/temp/scored-urls.md`.
-**Scores travel with the URLs.** When you assign batches (step 2.4), include each URL's composite utility score next to it. Fetchers pass it to `$HPR fetch --utility-score <N>` so the score persists into note frontmatter — it becomes one input to the vault's composite `quality_score`, which step 10 uses for ranked curation.
+**Scores travel with the URLs.** When you assign batches (step 2.4), include each URL's composite utility score next to it. Fetchers pass it to `{hpr_path} fetch --utility-score <N>` so the score persists into note frontmatter — it becomes one input to the vault's composite `quality_score`, which step 10 uses for ranked curation.
---
@@ -169,7 +169,7 @@ Append a few lines with `Edit` or `Write` every 30-60 seconds. Productive thinki
**Vault count check** — once every << p.vault_check_interval_s >> seconds max:
```bash
-PYTHONIOENCODING=utf-8 $HPR note list --tag <vault_tag> --all --json | python -c "import sys,json; d=json.load(sys.stdin); print(f'Notes in vault: {len(d.get(\"data\",[]))}')"
+PYTHONIOENCODING=utf-8 {hpr_path} note list --tag <vault_tag> --all --json | python -c "import sys,json; d=json.load(sys.stdin); print(f'Notes in vault: {len(d.get(\"data\",[]))}')"
```
The wave is done when the vault note count is ≥<< (p.wave_done_ratio * 100)|int >>% of total URLs queued.
@@ -180,7 +180,7 @@ The wave is done when the vault note count is ≥<< (p.wave_done_ratio * 100)|in
After Wave 1 returns, run the coverage check before proceeding:
-1. **List fetched sources:** `$HPR note list --tag <vault_tag> --all --json` — count substantive (non-deprecated) notes.
+1. **List fetched sources:** `{hpr_path} note list --tag <vault_tag> --all --json` — count substantive (non-deprecated) notes.
2. **Map sources → atomic items.** For each atomic item in the decomposition, identify which fetched sources serve it. Mark each item as:
- **Well-covered** (4+ relevant sources)
@@ -226,10 +226,10 @@ After Wave 1 returns, run the coverage check before proceeding:
Four commands that turn the corpus into a *ranked* corpus. Run them once, in order, after fetching completes:
```bash
-$HPR claims ingest --tag <vault_tag> -j # claims JSONs -> queryable claims table
-$HPR sources backfill-doi --tag <vault_tag> -j # catch DOIs the fetchers missed
-$HPR sources score --tag <vault_tag> -j # citation counts + retraction check (cached APIs)
-$HPR graph rank -j # vault centrality + composite quality_score
+{hpr_path} claims ingest --tag <vault_tag> -j # claims JSONs -> queryable claims table
+{hpr_path} sources backfill-doi --tag <vault_tag> -j # catch DOIs the fetchers missed
+{hpr_path} sources score --tag <vault_tag> -j # citation counts + retraction check (cached APIs)
+{hpr_path} graph rank -j # vault centrality + composite quality_score
```
**If `sources score` reports RETRACTED sources:** flag them in `research/runs/<vault_tag>/temp/coverage-gaps.md` immediately — a retracted source must never anchor a locus or survive into drafting as unqualified evidence. The retraction floor also crushes its `quality_score`, so ranked curation (step 10) buries it automatically.
@@ -243,7 +243,7 @@ These commands are local/cached and cost seconds. Skipping them leaves step 10's
Blocked fetches (login walls, bot walls, captchas) were NOT lost — the fetch gate queued them:
```bash
-$HPR escalation list --status queued --tag <vault_tag> -j
+{hpr_path} escalation list --status queued --tag <vault_tag> -j
```
**If queued items exist**, spawn EXACTLY ONE `hyperresearch-browser-fetcher` subagent to drain them (serial, one browser — never spawn two):
@@ -264,7 +264,7 @@ prompt: |
YOUR INPUTS:
- vault_tag: <vault_tag>
- - drain up to 10 items (claim via `$HPR escalation claim --tag <vault_tag>`)
+ - drain up to 10 items (claim via `{hpr_path} escalation claim --tag <vault_tag>`)
RUN DIRECTIVES: append the FULL contents of research/runs/<vault_tag>/shims/research.md here, verbatim.
```
@@ -273,8 +273,8 @@ prompt: |
1. **Consolidate into ONE message to the user** — never one interruption per URL:
> "3 sources need you: [site A: solve the CAPTCHA], [site B: log in], [site C: approve 2FA]. Open them in Chrome, complete the challenges, then tell me 'done' (or 'skip')."
-2. In non-interactive (`-p`) runs where no user can answer: record `$HPR run block <vault_tag> --on human-challenges -j` and CONTINUE the pipeline with everything else — the queue drains on the next `hpr run resume`.
-3. After the user says done: `$HPR escalation retry <id>` each item, re-spawn the browser-fetcher once, then re-run step 2.7's ranking commands so the new sources are scored.
+2. In non-interactive (`-p`) runs where no user can answer: record `{hpr_path} run block <vault_tag> --on human-challenges -j` and CONTINUE the pipeline with everything else — the queue drains on the next `hpr run resume`.
+3. After the user says done: `{hpr_path} escalation retry <id>` each item, re-spawn the browser-fetcher once, then re-run step 2.7's ranking commands so the new sources are scored.
**If the Claude-in-Chrome extension is unavailable**, the queue simply accumulates — report the queued count in your wave summary and move on. Abandoned/queued items are exactly the pre-4.0 status quo (lost sources), never worse.
@@ -296,7 +296,7 @@ Substantive (non-deprecated) note counts. The `full` row reflects the installed
When a single long source (><< p.source_analyst_word_trigger >> words) is load-bearing, delegate end-to-end analysis to `hyperresearch-source-analyst` (full-source deep read):
Trigger conditions (ALL three must hold):
-1. **Length:** source's `word_count` (visible on `$HPR note show <id> -j`) exceeds ~<< p.source_analyst_word_trigger >> words
+1. **Length:** source's `word_count` (visible on `{hpr_path} note show <id> -j`) exceeds ~<< p.source_analyst_word_trigger >> words
2. **Relevance:** source is relevant to the research_query
3. **No existing analysis:** no `type: source-analysis` note already exists for this source
diff --git a/src/hyperresearch/skills/hyperresearch-3-contradiction-graph.md b/src/hyperresearch/skills/hyperresearch-3-contradiction-graph.md
index ff8e670..1a83839 100644
--- a/src/hyperresearch/skills/hyperresearch-3-contradiction-graph.md
+++ b/src/hyperresearch/skills/hyperresearch-3-contradiction-graph.md
@@ -55,7 +55,7 @@ If no claims files exist (e.g., fetchers didn't produce them), skip this step en
5. **Write `research/runs/<vault_tag>/temp/contradiction-graph.json`** — array of ranked fight clusters.
-6. **Identify consensus claims.** Claims where 3+ INDEPENDENT sources agree. Independence is computed, not assumed: run `$HPR sources independence --tag <vault_tag> -j` first — it clusters syndicated copies (same canonical URL, near-duplicate bodies, shared wire-service boilerplate) and scores members `1/cluster_size`. **Count each cluster as ONE voice** (sum of independence scores ≥ 3.0, not raw source count ≥ 3). Write consensus claims to `research/runs/<vault_tag>/temp/consensus-claims.json`. These are the "settled ground" the draft can assert confidently without hedging.
+6. **Identify consensus claims.** Claims where 3+ INDEPENDENT sources agree. Independence is computed, not assumed: run `{hpr_path} sources independence --tag <vault_tag> -j` first — it clusters syndicated copies (same canonical URL, near-duplicate bodies, shared wire-service boilerplate) and scores members `1/cluster_size`. **Count each cluster as ONE voice** (sum of independence scores ≥ 3.0, not raw source count ≥ 3). Write consensus claims to `research/runs/<vault_tag>/temp/consensus-claims.json`. These are the "settled ground" the draft can assert confidently without hedging.
---
diff --git a/src/hyperresearch/skills/hyperresearch-4-loci-analysis.md b/src/hyperresearch/skills/hyperresearch-4-loci-analysis.md
index 1998573..deb8b84 100644
--- a/src/hyperresearch/skills/hyperresearch-4-loci-analysis.md
+++ b/src/hyperresearch/skills/hyperresearch-4-loci-analysis.md
@@ -25,7 +25,7 @@ Read these inputs:
- `research/runs/<vault_tag>/temp/contradiction-graph.json` — ranked fight clusters (if step 3 ran)
- `research/runs/<vault_tag>/temp/coverage-gaps.md` — which atomic items have weak coverage
-Survey the corpus: `$HPR note list --tag <vault_tag> --all -j` to confirm width sweep is complete.
+Survey the corpus: `{hpr_path} note list --tag <vault_tag> --all -j` to confirm width sweep is complete.
---
@@ -106,7 +106,7 @@ Survey the corpus: `$HPR note list --tag <vault_tag> --all -j` to confirm width
7. **Reconsider `inference_depth` against the actual corpus.** Step 1 set it provisionally from the query alone; you have now seen what the surface web actually holds. Upgrade to `deep` when the corpus shows the load-bearing questions are underdetermined by clearly-published sources — high-uncertainty loci where the missing evidence is gray literature, filings, or unpublished figures rather than papers nobody fetched yet. Downgrade to `surface` only if step 1 chose `deep` and the corpus turned out rich and univocal. To change it:
```bash
- $HPR levers set <vault_tag> inference_depth=deep --rerender -j
+ {hpr_path} levers set <vault_tag> inference_depth=deep --rerender -j
```
The `--rerender` refreshes the shim files so step 5's investigators inherit the new posture. If the step-1 value still fits, do nothing.
diff --git a/src/hyperresearch/skills/hyperresearch-5-depth-investigation.md b/src/hyperresearch/skills/hyperresearch-5-depth-investigation.md
index eb396ae..83e87d8 100644
--- a/src/hyperresearch/skills/hyperresearch-5-depth-investigation.md
+++ b/src/hyperresearch/skills/hyperresearch-5-depth-investigation.md
@@ -81,11 +81,11 @@ Read these inputs:
4. **Read the interim notes.** After all return, list them:
```bash
- $HPR note list --tag <vault_tag> --type interim --all --json
+ {hpr_path} note list --tag <vault_tag> --type interim --all --json
```
Then batch-read them:
```bash
- $HPR note show <id1> <id2> ... -j
+ {hpr_path} note show <id1> <id2> ... -j
```
Hold the Committed Position sections in your context — they are the load-bearing input to step 6 (cross-locus reconciliation).
diff --git a/src/hyperresearch/skills/hyperresearch-6-cross-locus-reconcile.md b/src/hyperresearch/skills/hyperresearch-6-cross-locus-reconcile.md
index 87d80e6..48070f3 100644
--- a/src/hyperresearch/skills/hyperresearch-6-cross-locus-reconcile.md
+++ b/src/hyperresearch/skills/hyperresearch-6-cross-locus-reconcile.md
@@ -25,7 +25,7 @@ description: >
Read these inputs:
- `research/runs/<vault_tag>/scaffold.md` — vault_tag
- `research/runs/<vault_tag>/loci.json` — scored loci
-- All interim notes: `$HPR note list --tag <vault_tag> --type interim --all --json` then `$HPR note show <id1> <id2> ... -j`
+- All interim notes: `{hpr_path} note list --tag <vault_tag> --type interim --all --json` then `{hpr_path} note show <id1> <id2> ... -j`
You need the `## Committed position` section from every interim note in your context.
diff --git a/src/hyperresearch/skills/hyperresearch-7-source-tensions.md b/src/hyperresearch/skills/hyperresearch-7-source-tensions.md
index 5e95d66..32d584a 100644
--- a/src/hyperresearch/skills/hyperresearch-7-source-tensions.md
+++ b/src/hyperresearch/skills/hyperresearch-7-source-tensions.md
@@ -26,7 +26,7 @@ Read these inputs:
- `research/runs/<vault_tag>/scaffold.md` — vault_tag
- `research/runs/<vault_tag>/comparisons.md` — cross-locus tensions
- `research/runs/<vault_tag>/temp/contradiction-graph.json` (if step 3 ran)
-- Survey vault: `$HPR note list --tag <vault_tag> --all -j` for the << p.tension_survey|dash >> highest-quality non-deprecated sources
+- Survey vault: `{hpr_path} note list --tag <vault_tag> --all -j` for the << p.tension_survey|dash >> highest-quality non-deprecated sources
---
@@ -34,7 +34,7 @@ Read these inputs:
1. **Re-read `comparisons.md`.** Each tension there is already a candidate source tension. Extract: the two positions, the strongest evidence for each, your preliminary reading of which side has the better case.
-2. **Scan the width corpus for orphan tensions.** For the << p.tension_survey|dash >> highest-quality non-deprecated sources, then **read the full body** of the top << p.tension_full_reads|dash >> sources most likely to contain disagreements — use `$HPR note show <id1> <id2> ... -j` in batches. **Tensions hide in nuance that summaries flatten:** a source's "however" clause, a footnote caveat, a methodological critique buried in a discussion section. You cannot extract tensions you haven't read. Look for:
+2. **Scan the width corpus for orphan tensions.** For the << p.tension_survey|dash >> highest-quality non-deprecated sources, then **read the full body** of the top << p.tension_full_reads|dash >> sources most likely to contain disagreements — use `{hpr_path} note show <id1> <id2> ... -j` in batches. **Tensions hide in nuance that summaries flatten:** a source's "however" clause, a footnote caveat, a methodological critique buried in a discussion section. You cannot extract tensions you haven't read. Look for:
- Sources that explicitly disagree with each other (different conclusions from similar evidence)
- Sources that use competing theoretical frameworks to explain the same phenomenon
- Sources where one side cites data the other side ignores
diff --git a/src/hyperresearch/skills/hyperresearch.md b/src/hyperresearch/skills/hyperresearch.md
index 782823a..103e9f0 100644
--- a/src/hyperresearch/skills/hyperresearch.md
+++ b/src/hyperresearch/skills/hyperresearch.md
@@ -70,7 +70,7 @@ Step 1 classifies the query into a `pipeline_tier` (`light` / `full`). The tier
| `full` | 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12 → 13 → 14 → 14.5 → 15 → 16 | << p.time_estimate >> |
| `dissertation` | 1 → 1.5 (chapter partition) → [2 → … → 10 per chapter] → 6g/11 (global) → 12 → 13 → 14 → 14.5 → 15 → 16 | << dissertation.time_estimate >> |
-`dissertation` is opt-in only — the user must explicitly request it (or the run was initialized with `--profile dissertation`). Step 1 never auto-classifies into it. On dissertation runs, steps 2–10 loop per chapter (see `hyperresearch-1-5-chapter-partition`), with up to << dissertation.chapter_concurrency >> chapters in flight; each chapter stays within the proven << dissertation.chapter_source_target|dash >>-source envelope while the run totals << dissertation.source_target|dash >> sources.
+`dissertation` is opt-in only — the user must explicitly request it (or the run was initialized with `--profile dissertation`). Step 1 never auto-classifies into it. **It is experimental.** Its length, read-budget and citation targets are configured but nothing reads them yet (#103). Say so to the user before starting one. On dissertation runs, steps 2–10 loop per chapter (see `hyperresearch-1-5-chapter-partition`), with up to << dissertation.chapter_concurrency >> chapters in flight; each chapter stays within the proven << dissertation.chapter_source_target|dash >>-source envelope while the run totals << dissertation.source_target|dash >> sources.
**RESPECT THE TIER GATE.** When step 1 classifies a query as `light`, do NOT run the skipped steps "just to be thorough." The tier classification is a product decision: simple queries should produce fast, right-sized answers. Trust the classification. If you're uncertain, tier up — but never silently upgrade every query to `full`.
@@ -157,9 +157,9 @@ After step 1 returns, read `research/runs/<vault_tag>/prompt-decomposition.json`
## Browser-lane escalations (all tiers)
-Blocked fetches (login walls, bot walls, captchas) are queued, not lost: `$HPR escalation list --status queued --tag <vault_tag> -j`. Step 2.8 drains the queue via ONE `hyperresearch-browser-fetcher` subagent driving the user's real Chrome browser. Two standing rules:
+Blocked fetches (login walls, bot walls, captchas) are queued, not lost: `{hpr_path} escalation list --status queued --tag <vault_tag> -j`. Step 2.8 drains the queue via ONE `hyperresearch-browser-fetcher` subagent driving the user's real Chrome browser. Two standing rules:
-1. **CAPTCHAs / logins / 2FA are ALWAYS the human's.** The browser-fetcher marks them `needs_human`; you consolidate ALL of them into ONE message to the user at a natural pause point (never one interruption per URL). In non-interactive runs, `$HPR run block <vault_tag> --on human-challenges` and continue with everything else.
+1. **CAPTCHAs / logins / 2FA are ALWAYS the human's.** The browser-fetcher marks them `needs_human`; you consolidate ALL of them into ONE message to the user at a natural pause point (never one interruption per URL). In non-interactive runs, `{hpr_path} run block <vault_tag> --on human-challenges` and continue with everything else.
2. **One browser-fetcher at a time.** It's the user's actual browser — parallel instances are chaos. Check the queue again after step 13 (gap-fetch) if new fetches got blocked.
## Subagent spawn contract (applies to every Task call)
@@ -172,7 +172,7 @@ When a step skill instructs you to spawn a subagent, the prompt you pass MUST in
3. **The subagent's specific inputs** (vault_tag, output_path, locus, etc.). Each step skill's spawn template documents the required fields.
-4. **The run's shim file, pasted VERBATIM.** Step 1 renders posture shims (register / domain notes / inference depth) to `research/runs/<vault_tag>/shims/{research,drafting,critics,polish}.md`. Each step skill's spawn template names which shim its subagents receive; append that file's FULL contents to the end of the spawn prompt, unedited. You never write, summarize, or trim shim text — the file is the single source of truth. The cite-checker receives NO shim (verification is register-independent). If the shims directory is missing, run `$HPR levers render <vault_tag> -j` before spawning.
+4. **The run's shim file, pasted VERBATIM.** Step 1 renders posture shims (register / domain notes / inference depth) to `research/runs/<vault_tag>/shims/{research,drafting,critics,polish}.md`. Each step skill's spawn template names which shim its subagents receive; append that file's FULL contents to the end of the spawn prompt, unedited. You never write, summarize, or trim shim text — the file is the single source of truth. The cite-checker receives NO shim (verification is register-independent). If the shims directory is missing, run `{hpr_path} levers render <vault_tag> -j` before spawning.
Skipping any of these in a Task prompt is a process violation.
@@ -186,10 +186,10 @@ Context compaction may eat parts of this conversation. If you're unsure what ste
1. **Check the TodoWrite list.** It carries integer step numbers and survives compaction.
2. **Check disk artifacts (fallback).** Each step writes a canonical artifact:
- Step 1: `research/runs/<vault_tag>/scaffold.md`, `research/runs/<vault_tag>/prompt-decomposition.json`, `research/runs/<vault_tag>/temp/coverage-matrix.md`
- - Step 2: vault notes tagged with vault_tag (`$HPR note list --tag <vault_tag> --all -j`)
+ - Step 2: vault notes tagged with vault_tag (`{hpr_path} note list --tag <vault_tag> --all -j`)
- Step 3: `research/runs/<vault_tag>/temp/contradiction-graph.json`, `research/runs/<vault_tag>/temp/consensus-claims.json`
- Step 4: `research/runs/<vault_tag>/loci.json`
- - Step 5: vault notes with `type: interim` (`$HPR note list --tag <vault_tag> --type interim --all -j`)
+ - Step 5: vault notes with `type: interim` (`{hpr_path} note list --tag <vault_tag> --type interim --all -j`)
- Step 6: `research/runs/<vault_tag>/comparisons.md`
- Step 7: `research/runs/<vault_tag>/temp/source-tensions.json`
- Step 8: `research/runs/<vault_tag>/corpus-critic-gaps.json`, `research/runs/<vault_tag>/temp/corpus-critic-results.md`
@@ -227,8 +227,8 @@ done
Then refresh retraction data and run the SHIP GATE:
```bash
-$HPR sources retractions --tag <vault_tag> --json # ship-time retraction re-check (bypasses cache)
-$HPR run finish <vault_tag> --json # THE ship gate: verify + manifest flip
+{hpr_path} sources retractions --tag <vault_tag> --json # ship-time retraction re-check (bypasses cache)
+{hpr_path} run finish <vault_tag> --json # THE ship gate: verify + manifest flip
```
`run finish` runs the whole verification battery — report exists, required headings, **length within the profile's word target (±20%)**, citation density, tier artifacts, cite-check resolution, **quote-integrity**, and **retracted-citations** — and flips the manifest to `done` only when every check passes. On failure it flips the run to `blocked (verify)` and exits 1.
@@ -240,7 +240,7 @@ $HPR run finish <vault_tag> --json # THE ship gate: verify + ma
- `retracted-citations` → acknowledge the retraction in the sentence or remove the citation.
- Anything else → fix the specific artifact the check names.
-Re-run `$HPR run finish <vault_tag> --json` after each fix round. Maximum 3 rounds; if the gate still fails, leave the run `blocked` and report the failing checks to the user honestly — a blocked run with a true manifest beats a shipped report that lies. Optional advisory: `$HPR lint --rule numeric-consistency --json` (warnings only, never blocks).
+Re-run `{hpr_path} run finish <vault_tag> --json` after each fix round. Maximum 3 rounds; if the gate still fails, leave the run `blocked` and report the failing checks to the user honestly — a blocked run with a true manifest beats a shipped report that lies. Optional advisory: `{hpr_path} lint --rule numeric-consistency --json` (warnings only, never blocks).
Ship only after `run finish` reports `"passed": true`: the final report lives at `research/notes/final_report_<vault_tag>.md`.
diff --git a/tests/fixtures/golden_prompts/skills/hyperresearch-10-triple-draft.md b/tests/fixtures/golden_prompts/skills/hyperresearch-10-triple-draft.md
index 8f057da..eb9bd67 100644
--- a/tests/fixtures/golden_prompts/skills/hyperresearch-10-triple-draft.md
+++ b/tests/fixtures/golden_prompts/skills/hyperresearch-10-triple-draft.md
@@ -30,7 +30,7 @@ Read these inputs:
- `research/runs/<vault_tag>/comparisons.md` (full tier) — cross-locus tensions
- `research/runs/<vault_tag>/temp/source-tensions.json` (full tier) — expert disagreements
- `research/runs/<vault_tag>/temp/coverage-gaps.md` (if exists) — items with weak source coverage
-- Survey vault: `$HPR note list --tag <vault_tag> --all -j` for the evidence landscape
+- Survey vault: `{hpr_path} note list --tag <vault_tag> --all -j` for the evidence landscape
- Modality calibration (from the scaffold's `modality` field):
- **collect** — enumerative coverage, per-entity sections with named fields
- **synthesize** — defended thesis with evidence chains, interpretive density
@@ -59,7 +59,7 @@ If `pipeline_tier == "light"`: SKIP step 10.1 — 10.3 below and follow this sec
**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 note list --tag <vault_tag> --all -j` and pick the 8–15 most relevant non-deprecated notes. Read each one (`$HPR note show <id1> <id2> ... -j`) before writing.
+1. **Read the vault directly.** Light tier has no `evidence-digest.md` (step 9 was skipped). Survey the vault: `{hpr_path} note list --tag <vault_tag> --all -j` and pick the 8–15 most relevant non-deprecated notes. Read each one (`{hpr_path} note show <id1> <id2> ... -j`) before writing.
2. **Honor the structural contract.**
- Use the literal H2 headings from `required_section_headings` in `research/runs/<vault_tag>/prompt-decomposition.json`, in order.
@@ -101,13 +101,13 @@ Write the 3 angle assignments to `research/runs/<vault_tag>/temp/draft-angles.md
1. **List all substantive vault notes:**
```bash
- $HPR note list --tag <vault_tag> --all --json
+ {hpr_path} note list --tag <vault_tag> --all --json
```
Filter to non-deprecated notes. You should have 50-100 candidates.
**Rank the pool before picking.** For each atomic item, run a quality-ranked search to surface the best-evidence sources first:
```bash
- $HPR search "<atomic item keywords>" --tag <vault_tag> --ranked -j
+ {hpr_path} search "<atomic item keywords>" --tag <vault_tag> --ranked -j
```
`--ranked` folds the composite `quality_score` (tier + utility + citation authority + vault centrality, retractions floored) into relevance. Prefer high-quality sources when two candidates cover the same ground; a note with `quality_score` near the retraction floor should not appear in any must_read list unless the draft explicitly discusses its retraction.
diff --git a/tests/fixtures/golden_prompts/skills/hyperresearch-13-gap-fetch.md b/tests/fixtures/golden_prompts/skills/hyperresearch-13-gap-fetch.md
index 63e6ebb..036cabb 100644
--- a/tests/fixtures/golden_prompts/skills/hyperresearch-13-gap-fetch.md
+++ b/tests/fixtures/golden_prompts/skills/hyperresearch-13-gap-fetch.md
@@ -34,7 +34,7 @@ Read these inputs:
2. **For each qualifying finding, check whether the vault has evidence.** Run a targeted vault search for the topic the finding names:
```bash
- $HPR search "<finding topic keywords>" --tag <vault_tag> --json
+ {hpr_path} search "<finding topic keywords>" --tag <vault_tag> --json
```
If 2+ relevant notes exist, the patcher can handle it — move on. If 0-1 relevant notes exist, this is a **fetch-worthy gap**.
diff --git a/tests/fixtures/golden_prompts/skills/hyperresearch-2-width-sweep.md b/tests/fixtures/golden_prompts/skills/hyperresearch-2-width-sweep.md
index 3a9a606..2143a5a 100644
--- a/tests/fixtures/golden_prompts/skills/hyperresearch-2-width-sweep.md
+++ b/tests/fixtures/golden_prompts/skills/hyperresearch-2-width-sweep.md
@@ -121,7 +121,7 @@ Before batching URLs, score each candidate URL on six dimensions (0–3 each, ma
Write to `research/runs/<vault_tag>/temp/scored-urls.md`.
-**Scores travel with the URLs.** When you assign batches (step 2.4), include each URL's composite utility score next to it. Fetchers pass it to `$HPR fetch --utility-score <N>` so the score persists into note frontmatter — it becomes one input to the vault's composite `quality_score`, which step 10 uses for ranked curation.
+**Scores travel with the URLs.** When you assign batches (step 2.4), include each URL's composite utility score next to it. Fetchers pass it to `{hpr_path} fetch --utility-score <N>` so the score persists into note frontmatter — it becomes one input to the vault's composite `quality_score`, which step 10 uses for ranked curation.
---
@@ -169,7 +169,7 @@ Append a few lines with `Edit` or `Write` every 30-60 seconds. Productive thinki
**Vault count check** — once every 60 seconds max:
```bash
-PYTHONIOENCODING=utf-8 $HPR note list --tag <vault_tag> --all --json | python -c "import sys,json; d=json.load(sys.stdin); print(f'Notes in vault: {len(d.get(\"data\",[]))}')"
+PYTHONIOENCODING=utf-8 {hpr_path} note list --tag <vault_tag> --all --json | python -c "import sys,json; d=json.load(sys.stdin); print(f'Notes in vault: {len(d.get(\"data\",[]))}')"
```
The wave is done when the vault note count is ≥80% of total URLs queued.
@@ -180,7 +180,7 @@ The wave is done when the vault note count is ≥80% of total URLs queued.
After Wave 1 returns, run the coverage check before proceeding:
-1. **List fetched sources:** `$HPR note list --tag <vault_tag> --all --json` — count substantive (non-deprecated) notes.
+1. **List fetched sources:** `{hpr_path} note list --tag <vault_tag> --all --json` — count substantive (non-deprecated) notes.
2. **Map sources → atomic items.** For each atomic item in the decomposition, identify which fetched sources serve it. Mark each item as:
- **Well-covered** (4+ relevant sources)
@@ -226,10 +226,10 @@ After Wave 1 returns, run the coverage check before proceeding:
Four commands that turn the corpus into a *ranked* corpus. Run them once, in order, after fetching completes:
```bash
-$HPR claims ingest --tag <vault_tag> -j # claims JSONs -> queryable claims table
-$HPR sources backfill-doi --tag <vault_tag> -j # catch DOIs the fetchers missed
-$HPR sources score --tag <vault_tag> -j # citation counts + retraction check (cached APIs)
-$HPR graph rank -j # vault centrality + composite quality_score
+{hpr_path} claims ingest --tag <vault_tag> -j # claims JSONs -> queryable claims table
+{hpr_path} sources backfill-doi --tag <vault_tag> -j # catch DOIs the fetchers missed
+{hpr_path} sources score --tag <vault_tag> -j # citation counts + retraction check (cached APIs)
+{hpr_path} graph rank -j # vault centrality + composite quality_score
```
**If `sources score` reports RETRACTED sources:** flag them in `research/runs/<vault_tag>/temp/coverage-gaps.md` immediately — a retracted source must never anchor a locus or survive into drafting as unqualified evidence. The retraction floor also crushes its `quality_score`, so ranked curation (step 10) buries it automatically.
@@ -243,7 +243,7 @@ These commands are local/cached and cost seconds. Skipping them leaves step 10's
Blocked fetches (login walls, bot walls, captchas) were NOT lost — the fetch gate queued them:
```bash
-$HPR escalation list --status queued --tag <vault_tag> -j
+{hpr_path} escalation list --status queued --tag <vault_tag> -j
```
**If queued items exist**, spawn EXACTLY ONE `hyperresearch-browser-fetcher` subagent to drain them (serial, one browser — never spawn two):
@@ -264,7 +264,7 @@ prompt: |
YOUR INPUTS:
- vault_tag: <vault_tag>
- - drain up to 10 items (claim via `$HPR escalation claim --tag <vault_tag>`)
+ - drain up to 10 items (claim via `{hpr_path} escalation claim --tag <vault_tag>`)
RUN DIRECTIVES: append the FULL contents of research/runs/<vault_tag>/shims/research.md here, verbatim.
```
@@ -273,8 +273,8 @@ prompt: |
1. **Consolidate into ONE message to the user** — never one interruption per URL:
> "3 sources need you: [site A: solve the CAPTCHA], [site B: log in], [site C: approve 2FA]. Open them in Chrome, complete the challenges, then tell me 'done' (or 'skip')."
-2. In non-interactive (`-p`) runs where no user can answer: record `$HPR run block <vault_tag> --on human-challenges -j` and CONTINUE the pipeline with everything else — the queue drains on the next `hpr run resume`.
-3. After the user says done: `$HPR escalation retry <id>` each item, re-spawn the browser-fetcher once, then re-run step 2.7's ranking commands so the new sources are scored.
+2. In non-interactive (`-p`) runs where no user can answer: record `{hpr_path} run block <vault_tag> --on human-challenges -j` and CONTINUE the pipeline with everything else — the queue drains on the next `hpr run resume`.
+3. After the user says done: `{hpr_path} escalation retry <id>` each item, re-spawn the browser-fetcher once, then re-run step 2.7's ranking commands so the new sources are scored.
**If the Claude-in-Chrome extension is unavailable**, the queue simply accumulates — report the queued count in your wave summary and move on. Abandoned/queued items are exactly the pre-4.0 status quo (lost sources), never worse.
@@ -296,7 +296,7 @@ Substantive (non-deprecated) note counts. The `full` row reflects the installed
When a single long source (>5000 words) is load-bearing, delegate end-to-end analysis to `hyperresearch-source-analyst` (full-source deep read):
Trigger conditions (ALL three must hold):
-1. **Length:** source's `word_count` (visible on `$HPR note show <id> -j`) exceeds ~5000 words
+1. **Length:** source's `word_count` (visible on `{hpr_path} note show <id> -j`) exceeds ~5000 words
2. **Relevance:** source is relevant to the research_query
3. **No existing analysis:** no `type: source-analysis` note already exists for this source
diff --git a/tests/fixtures/golden_prompts/skills/hyperresearch-4-loci-analysis.md b/tests/fixtures/golden_prompts/skills/hyperresearch-4-loci-analysis.md
index 4a0e6d4..55f282a 100644
--- a/tests/fixtures/golden_prompts/skills/hyperresearch-4-loci-analysis.md
+++ b/tests/fixtures/golden_prompts/skills/hyperresearch-4-loci-analysis.md
@@ -25,7 +25,7 @@ Read these inputs:
- `research/runs/<vault_tag>/temp/contradiction-graph.json` — ranked fight clusters (if step 3 ran)
- `research/runs/<vault_tag>/temp/coverage-gaps.md` — which atomic items have weak coverage
-Survey the corpus: `$HPR note list --tag <vault_tag> --all -j` to confirm width sweep is complete.
+Survey the corpus: `{hpr_path} note list --tag <vault_tag> --all -j` to confirm width sweep is complete.
---
@@ -106,7 +106,7 @@ Survey the corpus: `$HPR note list --tag <vault_tag> --all -j` to confirm width
7. **Reconsider `inference_depth` against the actual corpus.** Step 1 set it provisionally from the query alone; you have now seen what the surface web actually holds. Upgrade to `deep` when the corpus shows the load-bearing questions are underdetermined by clearly-published sources — high-uncertainty loci where the missing evidence is gray literature, filings, or unpublished figures rather than papers nobody fetched yet. Downgrade to `surface` only if step 1 chose `deep` and the corpus turned out rich and univocal. To change it:
```bash
- $HPR levers set <vault_tag> inference_depth=deep --rerender -j
+ {hpr_path} levers set <vault_tag> inference_depth=deep --rerender -j
```
The `--rerender` refreshes the shim files so step 5's investigators inherit the new posture. If the step-1 value still fits, do nothing.
diff --git a/tests/fixtures/golden_prompts/skills/hyperresearch-5-depth-investigation.md b/tests/fixtures/golden_prompts/skills/hyperresearch-5-depth-investigation.md
index 202c2b6..805b55a 100644
--- a/tests/fixtures/golden_prompts/skills/hyperresearch-5-depth-investigation.md
+++ b/tests/fixtures/golden_prompts/skills/hyperresearch-5-depth-investigation.md
@@ -81,11 +81,11 @@ Read these inputs:
4. **Read the interim notes.** After all return, list them:
```bash
- $HPR note list --tag <vault_tag> --type interim --all --json
+ {hpr_path} note list --tag <vault_tag> --type interim --all --json
```
Then batch-read them:
```bash
- $HPR note show <id1> <id2> ... -j
+ {hpr_path} note show <id1> <id2> ... -j
```
Hold the Committed Position sections in your context — they are the load-bearing input to step 6 (cross-locus reconciliation).
diff --git a/tests/fixtures/golden_prompts/skills/hyperresearch.md b/tests/fixtures/golden_prompts/skills/hyperresearch.md
index 7ae0483..fec8d15 100644
--- a/tests/fixtures/golden_prompts/skills/hyperresearch.md
+++ b/tests/fixtures/golden_prompts/skills/hyperresearch.md
@@ -70,7 +70,7 @@ Step 1 classifies the query into a `pipeline_tier` (`light` / `full`). The tier
| `full` | 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12 → 13 → 14 → 14.5 → 15 → 16 | ~1.5–2.5 hours |
| `dissertation` | 1 → 1.5 (chapter partition) → [2 → … → 10 per chapter] → 6g/11 (global) → 12 → 13 → 14 → 14.5 → 15 → 16 | ~4–8 hours |
-`dissertation` is opt-in only — the user must explicitly request it (or the run was initialized with `--profile dissertation`). Step 1 never auto-classifies into it. On dissertation runs, steps 2–10 loop per chapter (see `hyperresearch-1-5-chapter-partition`), with up to 2 chapters in flight; each chapter stays within the proven 40–80-source envelope while the run totals 300–450 sources.
+`dissertation` is opt-in only — the user must explicitly request it (or the run was initialized with `--profile dissertation`). Step 1 never auto-classifies into it. **It is experimental.** Its length, read-budget and citation targets are configured but nothing reads them yet (#103). Say so to the user before starting one. On dissertation runs, steps 2–10 loop per chapter (see `hyperresearch-1-5-chapter-partition`), with up to 2 chapters in flight; each chapter stays within the proven 40–80-source envelope while the run totals 300–450 sources.
**RESPECT THE TIER GATE.** When step 1 classifies a query as `light`, do NOT run the skipped steps "just to be thorough." The tier classification is a product decision: simple queries should produce fast, right-sized answers. Trust the classification. If you're uncertain, tier up — but never silently upgrade every query to `full`.
@@ -157,9 +157,9 @@ After step 1 returns, read `research/runs/<vault_tag>/prompt-decomposition.json`
## Browser-lane escalations (all tiers)
-Blocked fetches (login walls, bot walls, captchas) are queued, not lost: `$HPR escalation list --status queued --tag <vault_tag> -j`. Step 2.8 drains the queue via ONE `hyperresearch-browser-fetcher` subagent driving the user's real Chrome browser. Two standing rules:
+Blocked fetches (login walls, bot walls, captchas) are queued, not lost: `{hpr_path} escalation list --status queued --tag <vault_tag> -j`. Step 2.8 drains the queue via ONE `hyperresearch-browser-fetcher` subagent driving the user's real Chrome browser. Two standing rules:
-1. **CAPTCHAs / logins / 2FA are ALWAYS the human's.** The browser-fetcher marks them `needs_human`; you consolidate ALL of them into ONE message to the user at a natural pause point (never one interruption per URL). In non-interactive runs, `$HPR run block <vault_tag> --on human-challenges` and continue with everything else.
+1. **CAPTCHAs / logins / 2FA are ALWAYS the human's.** The browser-fetcher marks them `needs_human`; you consolidate ALL of them into ONE message to the user at a natural pause point (never one interruption per URL). In non-interactive runs, `{hpr_path} run block <vault_tag> --on human-challenges` and continue with everything else.
2. **One browser-fetcher at a time.** It's the user's actual browser — parallel instances are chaos. Check the queue again after step 13 (gap-fetch) if new fetches got blocked.
## Subagent spawn contract (applies to every Task call)
@@ -172,7 +172,7 @@ When a step skill instructs you to spawn a subagent, the prompt you pass MUST in
3. **The subagent's specific inputs** (vault_tag, output_path, locus, etc.). Each step skill's spawn template documents the required fields.
-4. **The run's shim file, pasted VERBATIM.** Step 1 renders posture shims (register / domain notes / inference depth) to `research/runs/<vault_tag>/shims/{research,drafting,critics,polish}.md`. Each step skill's spawn template names which shim its subagents receive; append that file's FULL contents to the end of the spawn prompt, unedited. You never write, summarize, or trim shim text — the file is the single source of truth. The cite-checker receives NO shim (verification is register-independent). If the shims directory is missing, run `$HPR levers render <vault_tag> -j` before spawning.
+4. **The run's shim file, pasted VERBATIM.** Step 1 renders posture shims (register / domain notes / inference depth) to `research/runs/<vault_tag>/shims/{research,drafting,critics,polish}.md`. Each step skill's spawn template names which shim its subagents receive; append that file's FULL contents to the end of the spawn prompt, unedited. You never write, summarize, or trim shim text — the file is the single source of truth. The cite-checker receives NO shim (verification is register-independent). If the shims directory is missing, run `{hpr_path} levers render <vault_tag> -j` before spawning.
Skipping any of these in a Task prompt is a process violation.
@@ -186,10 +186,10 @@ Context compaction may eat parts of this conversation. If you're unsure what ste
1. **Check the TodoWrite list.** It carries integer step numbers and survives compaction.
2. **Check disk artifacts (fallback).** Each step writes a canonical artifact:
- Step 1: `research/runs/<vault_tag>/scaffold.md`, `research/runs/<vault_tag>/prompt-decomposition.json`, `research/runs/<vault_tag>/temp/coverage-matrix.md`
- - Step 2: vault notes tagged with vault_tag (`$HPR note list --tag <vault_tag> --all -j`)
+ - Step 2: vault notes tagged with vault_tag (`{hpr_path} note list --tag <vault_tag> --all -j`)
- Step 3: `research/runs/<vault_tag>/temp/contradiction-graph.json`, `research/runs/<vault_tag>/temp/consensus-claims.json`
- Step 4: `research/runs/<vault_tag>/loci.json`
- - Step 5: vault notes with `type: interim` (`$HPR note list --tag <vault_tag> --type interim --all -j`)
+ - Step 5: vault notes with `type: interim` (`{hpr_path} note list --tag <vault_tag> --type interim --all -j`)
- Step 6: `research/runs/<vault_tag>/comparisons.md`
- Step 7: `research/runs/<vault_tag>/temp/source-tensions.json`
- Step 8: `research/runs/<vault_tag>/corpus-critic-gaps.json`, `research/runs/<vault_tag>/temp/corpus-critic-results.md`
@@ -227,8 +227,8 @@ done
Then refresh retraction data and run the SHIP GATE:
```bash
-$HPR sources retractions --tag <vault_tag> --json # ship-time retraction re-check (bypasses cache)
-$HPR run finish <vault_tag> --json # THE ship gate: verify + manifest flip
+{hpr_path} sources retractions --tag <vault_tag> --json # ship-time retraction re-check (bypasses cache)
+{hpr_path} run finish <vault_tag> --json # THE ship gate: verify + manifest flip
```
`run finish` runs the whole verification battery — report exists, required headings, **length within the profile's word target (±20%)**, citation density, tier artifacts, cite-check resolution, **quote-integrity**, and **retracted-citations** — and flips the manifest to `done` only when every check passes. On failure it flips the run to `blocked (verify)` and exits 1.
@@ -240,7 +240,7 @@ $HPR run finish <vault_tag> --json # THE ship gate: verify + ma
- `retracted-citations` → acknowledge the retraction in the sentence or remove the citation.
- Anything else → fix the specific artifact the check names.
-Re-run `$HPR run finish <vault_tag> --json` after each fix round. Maximum 3 rounds; if the gate still fails, leave the run `blocked` and report the failing checks to the user honestly — a blocked run with a true manifest beats a shipped report that lies. Optional advisory: `$HPR lint --rule numeric-consistency --json` (warnings only, never blocks).
+Re-run `{hpr_path} run finish <vault_tag> --json` after each fix round. Maximum 3 rounds; if the gate still fails, leave the run `blocked` and report the failing checks to the user honestly — a blocked run with a true manifest beats a shipped report that lies. Optional advisory: `{hpr_path} lint --rule numeric-consistency --json` (warnings only, never blocks).
Ship only after `run finish` reports `"passed": true`: the final report lives at `research/notes/final_report_<vault_tag>.md`.
diff --git a/tests/test_cli/test_oa_fetch.py b/tests/test_cli/test_oa_fetch.py
index aca626d..316402d 100644
--- a/tests/test_cli/test_oa_fetch.py
+++ b/tests/test_cli/test_oa_fetch.py
@@ -10,6 +10,7 @@ from __future__ import annotations
import json
import os
+import socket
from pathlib import Path
import pytest
@@ -85,14 +86,14 @@ def vault_dir(tmp_path: Path, monkeypatch) -> Path:
encoding="utf-8",
)
- from hyperresearch.core import oa, scholar
+ from hyperresearch.core import scholar
from hyperresearch.web import pdf as pdf_lane
monkeypatch.setattr("hyperresearch.web.base.get_provider", lambda *a, **k: _AbstractOnlyProvider())
monkeypatch.setattr(
scholar, "_http_get_json", lambda url: UNPAYWALL if "unpaywall" in url else None
)
- monkeypatch.setattr(oa.socket, "getaddrinfo", lambda h, p: [(2, 1, 6, "", ("93.184.216.34", 0))])
+ monkeypatch.setattr(socket, "getaddrinfo", lambda h, p: [(2, 1, 6, "", ("93.184.216.34", 0))])
monkeypatch.setattr(
pdf_lane,
"fetch_pdf",
@@ -290,11 +291,11 @@ def test_recovery_is_off_without_an_email(tmp_path: Path, monkeypatch):
runner.invoke(app, ["init", str(tmp_path / "kb2"), "--name", "No Email"])
os.chdir(tmp_path / "kb2")
- from hyperresearch.core import oa, scholar
+ from hyperresearch.core import scholar
seen: list[str] = []
monkeypatch.setattr("hyperresearch.web.base.get_provider", lambda *a, **k: _AbstractOnlyProvider())
- monkeypatch.setattr(oa.socket, "getaddrinfo", lambda h, p: [(2, 1, 6, "", ("93.184.216.34", 0))])
+ monkeypatch.setattr(socket, "getaddrinfo", lambda h, p: [(2, 1, 6, "", ("93.184.216.34", 0))])
def track(url):
seen.append(url)
diff --git a/tests/test_core/test_hooks.py b/tests/test_core/test_hooks.py
index 45d8327..6697344 100644
--- a/tests/test_core/test_hooks.py
+++ b/tests/test_core/test_hooks.py
@@ -110,6 +110,30 @@ def test_install_hyperresearch_step_skills_idempotent(tmp_vault):
assert second is None
+def test_installed_skills_carry_the_resolved_cli_path(tmp_vault):
+ """Skills must name the CLI by the path install resolved, the way CLAUDE.md
+ and the agent prompts do. `$HPR` shipped for months with nothing defining
+ it, so `$HPR run finish` ran as `run finish` (#133)."""
+ from hyperresearch.core.hooks import (
+ _HYPERRESEARCH_STEP_SKILLS,
+ _install_hyperresearch_step_skills,
+ )
+
+ hpr = r"C:\venv\Scripts\hyperresearch.exe"
+ _install_hyperresearch_skill(tmp_vault.root, hpr)
+ _install_hyperresearch_step_skills(tmp_vault.root, hpr)
+
+ skills_root = tmp_vault.root / ".claude" / "skills"
+ bodies = {
+ name: (skills_root / name / "SKILL.md").read_text(encoding="utf-8")
+ for name in ["hyperresearch", *_HYPERRESEARCH_STEP_SKILLS]
+ }
+ for name, body in bodies.items():
+ assert "$HPR" not in body, name
+ assert "{hpr_path}" not in body, name
+ assert "C:/venv/Scripts/hyperresearch.exe run finish" in bodies["hyperresearch"]
+
+
# ---------------------------------------------------------------------------
# Subagent installers — per-agent sanity checks
# ---------------------------------------------------------------------------
diff --git a/tests/test_core/test_oa_core_resolver.py b/tests/test_core/test_oa_core_resolver.py
index ad68987..1d364c5 100644
--- a/tests/test_core/test_oa_core_resolver.py
+++ b/tests/test_core/test_oa_core_resolver.py
@@ -8,6 +8,7 @@ CORE, which needs a bearer header that the older layer cannot send.
from __future__ import annotations
import json
+import socket
from typing import ClassVar
import pytest
@@ -74,7 +75,7 @@ def _result(content: str, url: str = "https://publisher.example.com/doi/10.1/x",
@pytest.fixture
def public_dns(monkeypatch):
monkeypatch.setattr(
- oa.socket, "getaddrinfo", lambda host, port: [(2, 1, 6, "", ("93.184.216.34", 0))]
+ socket, "getaddrinfo", lambda host, port: [(2, 1, 6, "", ("93.184.216.34", 0))]
)
@@ -470,7 +471,7 @@ class TestUrlGate:
_stub_legacy(monkeypatch, {})
_stub_core(monkeypatch, {"search/works": _search_hit(rec)})
monkeypatch.setattr(
- oa.socket, "getaddrinfo", lambda h, p: [(2, 1, 6, "", ("169.254.169.254", 0))]
+ socket, "getaddrinfo", lambda h, p: [(2, 1, 6, "", ("169.254.169.254", 0))]
)
tried = _stub_pdf(monkeypatch, _result(FULL_TEXT))
original = _result(ABSTRACT)
@@ -483,7 +484,7 @@ class TestUrlGate:
id is theirs, and the gate is cheap."""
_stub_legacy(monkeypatch, {})
core_calls = _stub_core(monkeypatch, {"search/works": _search_hit(), "/works/": _work()})
- monkeypatch.setattr(oa.socket, "getaddrinfo", lambda h, p: [(2, 1, 6, "", ("10.0.0.5", 0))])
+ monkeypatch.setattr(socket, "getaddrinfo", lambda h, p: [(2, 1, 6, "", ("10.0.0.5", 0))])
_stub_pdf(monkeypatch, None)
original = _result(ABSTRACT)
out, loc = oa.recover_full_text(vault, None, "https://p/x", DOI, original)
@@ -500,7 +501,7 @@ class TestUrlGate:
addr = "169.254.169.254" if host.startswith("169.") else "93.184.216.34"
return [(2, 1, 6, "", (addr, 0))]
- monkeypatch.setattr(oa.socket, "getaddrinfo", dns)
+ monkeypatch.setattr(socket, "getaddrinfo", dns)
tried = _stub_pdf(monkeypatch, lambda url: _result(PDF_TEXT, url=url))
_, loc = oa.recover_full_text(vault, None, "https://p/x", DOI, _result(ABSTRACT))
assert tried == [SOURCE_PDF]
diff --git a/tests/test_core/test_oa_recovery.py b/tests/test_core/test_oa_recovery.py
index 9328a85..266850e 100644
--- a/tests/test_core/test_oa_recovery.py
+++ b/tests/test_core/test_oa_recovery.py
@@ -2,6 +2,8 @@
from __future__ import annotations
+import socket
+
import pytest
from hyperresearch.core import oa, scholar
@@ -20,7 +22,7 @@ def _result(content: str, url: str = "https://publisher.example.com/doi/10.1/x",
def public_dns(monkeypatch):
"""Resolve every hostname to a public address, with no network access."""
monkeypatch.setattr(
- oa.socket, "getaddrinfo", lambda host, port: [(2, 1, 6, "", ("93.184.216.34", 0))]
+ socket, "getaddrinfo", lambda host, port: [(2, 1, 6, "", ("93.184.216.34", 0))]
)
@@ -82,21 +84,52 @@ class TestCheckOaUrl:
def test_rejects_private_address(self, monkeypatch):
monkeypatch.setattr(
- oa.socket, "getaddrinfo", lambda h, p: [(2, 1, 6, "", ("169.254.169.254", 0))]
+ socket, "getaddrinfo", lambda h, p: [(2, 1, 6, "", ("169.254.169.254", 0))]
)
ok, reason = oa.check_oa_url("https://metadata.example.org/p.pdf")
assert ok is False and "non-public address" in reason
def test_rejects_loopback_ip_literal(self, monkeypatch):
- monkeypatch.setattr(oa.socket, "getaddrinfo", lambda h, p: [(2, 1, 6, "", ("127.0.0.1", 0))])
+ monkeypatch.setattr(socket, "getaddrinfo", lambda h, p: [(2, 1, 6, "", ("127.0.0.1", 0))])
ok, reason = oa.check_oa_url("https://127.0.0.1/p.pdf")
assert ok is False and "non-public address" in reason
+ @pytest.mark.parametrize("addr", ["::ffff:100.64.0.1", "2002:6440:1::", "::ffff:10.0.0.5"])
+ def test_rejects_wrapped_private_addresses(self, monkeypatch, addr):
+ # Python 3.11 reports the first two as is_global. The fetch gate
+ # unwraps them (#127); the OA gate has to agree with it (#138).
+ monkeypatch.setattr(socket, "getaddrinfo", lambda h, p: [(10, 1, 6, "", (addr, 0, 0, 0))])
+ ok, reason = oa.check_oa_url("https://repo.example.org/p.pdf")
+ assert ok is False and "non-public address" in reason
+
+ def test_jats_fetch_refuses_a_redirect_to_a_private_host(self, monkeypatch):
+ import httpx
+
+ def fake_resolve(host, port):
+ ip = "10.0.0.5" if host == "internal.example.org" else "93.184.216.34"
+ return [(2, 1, 6, "", (ip, 0))]
+
+ monkeypatch.setattr(socket, "getaddrinfo", fake_resolve)
+ hits: list[str] = []
+
+ def handler(request):
+ hits.append(str(request.url))
+ return httpx.Response(302, headers={"location": "http://internal.example.org/x"})
+
+ real_client = httpx.Client
+ monkeypatch.setattr(
+ httpx,
+ "Client",
+ lambda **kw: real_client(**{**kw, "transport": httpx.MockTransport(handler)}),
+ )
+ assert oa._http_get_text("https://repo.example.org/jats.xml") is None
+ assert hits == ["https://repo.example.org/jats.xml"]
+
def test_rejects_unresolvable_host(self, monkeypatch):
def boom(host, port):
raise OSError("nope")
- monkeypatch.setattr(oa.socket, "getaddrinfo", boom)
+ monkeypatch.setattr(socket, "getaddrinfo", boom)
ok, reason = oa.check_oa_url("https://nowhere.example.org/p.pdf")
assert ok is False and "DNS resolution failed" in reason
@@ -341,7 +374,7 @@ class TestRecoverFullText:
}
_stub_http(monkeypatch, {"unpaywall": payload})
monkeypatch.setattr(
- oa.socket, "getaddrinfo", lambda h, p: [(2, 1, 6, "", ("169.254.169.254", 0))]
+ socket, "getaddrinfo", lambda h, p: [(2, 1, 6, "", ("169.254.169.254", 0))]
)
self._stub_pdf(monkeypatch, _result(FULL_TEXT))
original = _result(ABSTRACT)
@@ -587,7 +620,7 @@ class TestRescueFullText:
}
_stub_http(monkeypatch, {"unpaywall": payload})
monkeypatch.setattr(
- oa.socket, "getaddrinfo", lambda h, p: [(2, 1, 6, "", ("169.254.169.254", 0))]
+ socket, "getaddrinfo", lambda h, p: [(2, 1, 6, "", ("169.254.169.254", 0))]
)
self._stub_pdf(monkeypatch, _result(FULL_TEXT))
assert oa.rescue_full_text(vault, None, "https://p/x", "10.1/x") == (None, None)
diff --git a/tests/test_core/test_prompt_golden.py b/tests/test_core/test_prompt_golden.py
index cbe080c..f2d8355 100644
--- a/tests/test_core/test_prompt_golden.py
+++ b/tests/test_core/test_prompt_golden.py
@@ -104,6 +104,12 @@ Deliberate deviations already folded into the goldens (2026-07-19):
word boundaries — against `p.citation_density_min` per 1000 WORDS (9,
the old 1.5-per-1000-characters floor expressed in English words)
instead of per 1000 characters.
+ - CLI path in skills (2026-09-22, #133): the skills spelled the CLI
+ `$HPR`, which nothing defined, so `$HPR run finish` expanded to
+ `run finish` and failed in the shell. They now carry `{hpr_path}`,
+ the agent prompts' placeholder, which install resolves to the CLI's
+ absolute path. These goldens pin the pre-install render, so they hold
+ the placeholder.
"""
from __future__ import annotations
diff --git a/tests/test_core/test_verification.py b/tests/test_core/test_verification.py
index bf6174d..f6c4f39 100644
--- a/tests/test_core/test_verification.py
+++ b/tests/test_core/test_verification.py
@@ -104,6 +104,15 @@ class TestCiteCheckExtraction:
assert len(strong) == 5 # 100% of number-bearing
assert len(weak) == 5 # every 2nd weak pair
+ @pytest.mark.parametrize(("rate", "expected"), [(0.6, 6), (0.3, 3), (1.0, 10), (0.0, 0)])
+ def test_sampling_hits_the_configured_rate(self, rate, expected):
+ # round(1 / 0.6) is 2, so the every-k-th rule sampled 0.6 as 50%.
+ pairs = [
+ {"verdict": "needs-llm", "strong": False, "sentence": f"w{i}", "numbers": []}
+ for i in range(10)
+ ]
+ assert len(sample_needs_llm(pairs, sample_rate=rate)) == expected
+
def test_citecheck_cli(self, cited_vault, monkeypatch):
from typer.testing import CliRunner