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(skills): settle prompt contract wording conflicts across steps (#183)

Jordan Gibbsfbe0ad715b40
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d3d663d..68b3897 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,7 @@
## [Unreleased]
+- **Step prompts agree with each other (#102).** Settles the contract conflicts listed in the issue: the no-re-synthesis invariant names the ship gate's compression pass as its one exception; width-sweep fetchers take no new topic searches but still chase the primary sources their batch cites; step 7 has a documented path for fewer than the target tensions when step 4 justified zero loci; a failed critic is re-spawned once and otherwise leaves an empty `critic_failed` findings file, since the ship gate checks all four exist; the step 11 outline leaves out Opinionated Synthesis for `short` reports; the step 1 example no longer shows a wrapper requirement in the decomposition; the readability recommender writes a JSON object, matching its schema; the polish auditor receives `wrapper_contract_path` so it knows whether to keep YAML frontmatter; step 16 hands off to the ship gate instead of declaring the run done; the one-chapter case in step 1.5 is described as an escape hatch; and the cite-check Goal states that non-numeric citations are sampled.
- **The pipeline runs on the OpenAI Codex CLI.** `hyperresearch install . --target codex` installs the entry skill at `.agents/skills/hyperresearch/`, invoked as `$hyperresearch <query>`, along with the 18 step procedures as plain files under `.hyperresearch/codex/steps/`, the subagent roster as custom agents in `.codex/agents/*.toml`, a Stop hook in `.codex/hooks.json`, and an `AGENTS.md` block. The step procedures are plain files because Codex caps the skill listing and has no skill-to-skill invocation. `--target all` installs both platforms. `--global --target codex` writes the skill to `~/.agents/skills/` and the agents to `~/.codex/agents/`. `--target claude` is the default and its output is byte-identical to 0.12.0. Differences on Codex: there is no browser lane, so blocked fetches stay queued and are listed for the user; the Read+Edit tool locks are instructions rather than enforcement; and the Stop hook (`hyperresearch run stop-gate`) blocks the session from ending mid-pipeline. The Stop hook exists because an earlier Codex attempt answered inline and never touched the vault. Codex's sandbox defaults to read-only with no network, so a session needs `--sandbox workspace-write -c sandbox_workspace_write.network_access=true`. hyperresearch documents these flags and never writes to Codex's config.
- **The repo is a Codex plugin marketplace too.** `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json` publish the same `deep-research` bootstrap skill as the Claude Code plugin: `codex plugin marketplace add jordan-gibbs/hyperresearch`, then `codex plugin add hyperresearch@hyperresearch`. The skill no longer assumes Claude Code. On Codex it runs `install --target codex` and then reads the entry skill directly, because Codex discovers skills when a session starts. It gains `license` and `compatibility` frontmatter and an `agents/openai.yaml`. Codex namespaces plugin skills, so from the plugin it is `$hyperresearch:deep-research`; installed standalone with `npx skills add jordan-gibbs/hyperresearch -a codex` (to `.agents/skills/deep-research/`) it is `$deep-research`. The `openai.yaml` starter prompt names the skill in words rather than by a `$` mention that would only match one of those. The README now leads with Claude Code and Codex install paths side by side.
- **`run resume` follows the tier step 1 declared.** A run is initialized with the installed gear's step list, and step 1 can reclassify it (usually to `light`) in `prompt-decomposition.json`. The ship gate already honoured that tier; `resume_position` did not, so a light-tier run that finished step 2 was told to resume at step 3, a step its tier skips. `run resume`, `run status` and the Codex Stop gate now use the declared tier's steps. Found during the first live Codex run.
diff --git a/src/hyperresearch/core/hooks.py b/src/hyperresearch/core/hooks.py
index b7f7169..ac99bd5 100644
--- a/src/hyperresearch/core/hooks.py
+++ b/src/hyperresearch/core/hooks.py
@@ -1558,13 +1558,14 @@ You are the polish auditor. Last pass before the draft ships.
## Pipeline position
-You are **Layer 7** — the final step of the 7-phase hyperresearch pipeline.
+You are **Layer 7** — the last pass that edits the report's text.
Everything is done: width sweep, loci analysis, depth investigation,
cross-locus reconciliation, the single draft, the four critics, and the
patcher (Layer 6) have all run. The draft now has the patcher's applied
findings in it. Your job: final hygiene + readability pass.
-After you finish, the report ships. There is no layer after you. If you
+After you finish, only the readability audit (layout suggestions the
+orchestrator applies selectively) and the ship gate remain. If you
find a structural problem this hunk pass cannot fix, escalate — do not
attempt it yourself.
@@ -1588,6 +1589,10 @@ prompt. No block = this prompt's defaults apply unchanged.
tool lock is `[Read, Edit]` only. If the stub is missing when you
arrive, STOP and report back so the orchestrator can re-stub and
retry.
+- **wrapper_contract_path** (optional): `research/wrapper_contract.json`,
+ passed only when that file exists. It is the only way you learn whether
+ a wrapper requires the YAML frontmatter block (section 1a). Absent =
+ no wrapper requirement.
## What you check
@@ -1599,7 +1604,8 @@ are planning artifacts that leaked from the orchestrator's scratch work:
{scaffold_only_sections}
Also strip:
-- YAML frontmatter at the top of the file (the `---\\n...\\n---\\n` block)
+- YAML frontmatter at the top of the file (the `---\\n...\\n---\\n` block),
+ unless `wrapper_contract_path` requires it — then fix it per section 1a
- Literal prompt echoes ("User prompt:", "The query is:", etc.)
- Leftover backticks around section headings
- Stray "Here is the report:" / "Below is the draft:" preamble lines
@@ -1622,7 +1628,8 @@ the offending block entirely.
### 1a. Frontmatter hygiene (YAML metadata block)
-If the file keeps a YAML frontmatter block (some wrappers require it),
+If the wrapper contract at `wrapper_contract_path` requires a YAML
+frontmatter block,
fix these specific failures — they are reader-visible metadata that
graders and downstream consumers see:
@@ -1637,9 +1644,9 @@ graders and downstream consumers see:
- `summary:` ending in `...` (truncated) — rewrite to a complete
one-sentence description of the report's thesis.
-If the entire frontmatter block is safe to remove (no wrapper requires
-it), prefer stripping it. If a wrapper requires it, fix the fields
-above in place.
+If no `wrapper_contract_path` was passed, or the contract does not
+require frontmatter, strip the whole block (section 1). If it does,
+fix the fields above in place.
### 1b. Inline scaffold vocabulary strip (reader-facing prose)
diff --git a/src/hyperresearch/skills/hyperresearch-1-5-chapter-partition.md b/src/hyperresearch/skills/hyperresearch-1-5-chapter-partition.md
index 73192d6..5485f9b 100644
--- a/src/hyperresearch/skills/hyperresearch-1-5-chapter-partition.md
+++ b/src/hyperresearch/skills/hyperresearch-1-5-chapter-partition.md
@@ -33,7 +33,7 @@ Read these inputs:
- Every atomic item lands in exactly ONE chapter (cross-cutting items go to the chapter that will treat them most deeply; other chapters reference, not re-research).
- A chapter is a *research unit*: it must be answerable with << dissertation.chapter_source_target|dash >> sources. If a candidate chapter obviously needs more, split it.
- When `required_section_headings` already implies a chapter structure (the prompt asked for named parts), FOLLOW IT — chapters must map 1:1 onto required top-level headings when they exist.
- - Fewer than ~12 atomic items → the query doesn't need chaptering; record 1 chapter and note the pipeline degenerates to the flat `full` shape.
+ - Fewer than ~12 atomic items → the query doesn't need chaptering; record 1 chapter and note the pipeline degenerates to the flat `full` shape. This is a deliberate escape hatch below the profile's << dissertation.chapters|dash >> range, not a violation of it; the range applies to queries that do need chaptering.
2. **Write the chapter plan** to `research/runs/<vault_tag>/chapter-plan.json`:
```json
diff --git a/src/hyperresearch/skills/hyperresearch-1-decompose.md b/src/hyperresearch/skills/hyperresearch-1-decompose.md
index e1572c3..9ec128f 100644
--- a/src/hyperresearch/skills/hyperresearch-1-decompose.md
+++ b/src/hyperresearch/skills/hyperresearch-1-decompose.md
@@ -73,7 +73,7 @@ Read both before starting. The vault_tag is in the scaffold's "Run config" secti
"5-tier support/resistance table"
],
"required_sections": [
- "## Opinionated Synthesis (if wrapper_contract demands it)"
+ "## Risks and Open Questions (the prompt asks for one)"
],
"required_section_headings": [
"## 1. Major Manufacturers, Device Models, and Configurations",
diff --git a/src/hyperresearch/skills/hyperresearch-11-synthesize.md b/src/hyperresearch/skills/hyperresearch-11-synthesize.md
index 83ef3d1..cac0352 100644
--- a/src/hyperresearch/skills/hyperresearch-11-synthesize.md
+++ b/src/hyperresearch/skills/hyperresearch-11-synthesize.md
@@ -122,7 +122,7 @@ Write `research/runs/<vault_tag>/temp/synthesis-outline.md`. This is the per-sec
...
## Conclusion / Opinionated synthesis
-<1-2 sentences: the committed reading, the strongest forward-looking implication>
+<1-2 sentences: the committed reading, the strongest forward-looking implication. For `short` response_format, name the closing beat only — `short` has no Opinionated Synthesis section.>
## Sources
<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.>
diff --git a/src/hyperresearch/skills/hyperresearch-12-critics.md b/src/hyperresearch/skills/hyperresearch-12-critics.md
index 1e714ad..8760f9e 100644
--- a/src/hyperresearch/skills/hyperresearch-12-critics.md
+++ b/src/hyperresearch/skills/hyperresearch-12-critics.md
@@ -57,7 +57,7 @@ Read these inputs:
RUN DIRECTIVES: append the FULL contents of research/runs/<vault_tag>/shims/critics.md here, verbatim.
```
-3. **Wait for all critics.** If one fails, you can proceed with the partial set, but log the absence to the run log — the patch pass is less robust with missing critic coverage. **Do NOT skip the instruction-critic specifically** — it's the only critic measuring prompt adherence, which is the dimension with the widest variance.
+3. **Wait for all critics.** If one fails, re-spawn it once. If it fails again, you can proceed with the partial set: write its output file yourself as `{"findings": [], "critic_failed": "<reason>"}` (the ship gate requires all four findings files to exist) and log the absence to the run log — the patch pass is less robust with missing critic coverage. **Do NOT skip the instruction-critic specifically** — it's the only critic measuring prompt adherence, which is the dimension with the widest variance.
4. **Do not read the findings yourself and apply them.** The patcher (step 14) reads the findings. Your job is to hand them to the patcher — AFTER step 13 (gap-fetch) runs.
@@ -65,7 +65,7 @@ Read these inputs:
## Exit criterion
-- All 4 critic findings JSONs exist (`research/runs/<vault_tag>/critic-findings-<name>.json`)
+- All 4 critic findings JSONs exist (`research/runs/<vault_tag>/critic-findings-<name>.json`), a failed critic's as the empty `critic_failed` stub from step 3
- Each is valid JSON with a `findings` array
---
diff --git a/src/hyperresearch/skills/hyperresearch-14-5-cite-check.md b/src/hyperresearch/skills/hyperresearch-14-5-cite-check.md
index 5064115..bddbf55 100644
--- a/src/hyperresearch/skills/hyperresearch-14-5-cite-check.md
+++ b/src/hyperresearch/skills/hyperresearch-14-5-cite-check.md
@@ -14,7 +14,7 @@ description: >
**Tier gate:** Runs for `full` and `dissertation`. SKIP for `light` — a light report's citation volume doesn't justify the pass; the `quote-integrity` and `numeric-consistency` lint rules still cover it mechanically at the step-15 gate.
-**Goal:** every citation that ships either supports its sentence or gets fixed. This is the difference between "has citations" and "citations are true bindings" — the single thing external fact-checkers actually measure.
+**Goal:** every citation the check covers — all dangling citations, every number-bearing sentence, and a sample of the rest — either supports its sentence or gets fixed. This is the difference between "has citations" and "citations are true bindings" — the single thing external fact-checkers actually measure.
---
diff --git a/src/hyperresearch/skills/hyperresearch-15-polish.md b/src/hyperresearch/skills/hyperresearch-15-polish.md
index d5a8e98..0ad2f70 100644
--- a/src/hyperresearch/skills/hyperresearch-15-polish.md
+++ b/src/hyperresearch/skills/hyperresearch-15-polish.md
@@ -50,7 +50,8 @@ prompt: |
QUERY FILE: research/runs/<vault_tag>/query.md
PIPELINE POSITION: You are step 15 (polish auditor) of the
- hyperresearch V8 pipeline — the final step. Step 14 (patcher) applied
+ hyperresearch V8 pipeline — the last editing pass before step 16's
+ readability audit. Step 14 (patcher) applied
<% if platform == "codex" %> critic findings as patch hunks. After you return, the orchestrator
runs the final integrity gate and ships. You only read files and
apply surgical patches (apply_patch) — never create or rewrite a file.
@@ -61,13 +62,14 @@ prompt: |
YOUR INPUTS:
- draft_path: research/notes/final_report_<vault_tag>.md
- polish_log_path: research/runs/<vault_tag>/polish-log.json (already stubbed)
+ - wrapper_contract_path: research/wrapper_contract.json (include ONLY if the file exists; it says whether YAML frontmatter must be kept)
RUN DIRECTIVES: append the FULL contents of research/runs/<vault_tag>/shims/polish.md here, verbatim.
```
The polish auditor strips:
- **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)
+- Hygiene leaks (YAML frontmatter unless the wrapper contract requires it, scaffold sections, prompt echoes)
- Filler phrases ("It is worth noting", "Importantly", etc.)
- Redundant sentences / paragraphs that restate prior content
- Run-on sentences and over-long paragraphs (breaks into smaller units via <% if platform == "codex" %>apply_patch<% else %>Edit<% endif %>)
diff --git a/src/hyperresearch/skills/hyperresearch-16-readability-audit.md b/src/hyperresearch/skills/hyperresearch-16-readability-audit.md
index d618039..c2dae61 100644
--- a/src/hyperresearch/skills/hyperresearch-16-readability-audit.md
+++ b/src/hyperresearch/skills/hyperresearch-16-readability-audit.md
@@ -63,7 +63,8 @@ prompt: |
RUN DIRECTIVES: append the FULL contents of research/runs/<vault_tag>/shims/polish.md here, verbatim.
- Write recommendations as a JSON array per the schema in your agent
+ Write recommendations as a JSON object (`recommendations` array plus
+ `summary`) per the schema in your agent
prompt. Cap at << p.readability_rec_cap >> recommendations, prioritized by impact.
```
@@ -171,10 +172,10 @@ This is the audit trail. If a future review finds a readability problem we shoul
---
-## Pipeline complete
+## Next: the ship gate
<% if platform == "codex" %>Return to the entry skill (`hyperresearch`) and run its **Final integrity gate** (`run finish`). Mark all plan items complete. Only after `run finish` reports `"passed": true` (or the run is honestly `blocked` after 3 fix rounds), tell the user the final report path and list any still-queued escalations.
-The run is not done until the gate has spoken.<% else %>Return to the entry skill (`hyperresearch`). Mark all todos complete. Tell the user the final report path.
+The run is not done until the gate has spoken.<% else %>Return to the entry skill (`hyperresearch`) and run its **Final integrity gate** (`run finish`). Mark all todos complete. Only after `run finish` reports `"passed": true` (or the run is honestly `blocked` after 3 fix rounds), tell the user the final report path and list any still-queued escalations.
-You're done.<% endif %>
+The run is not done until the gate has spoken.<% endif %>
diff --git a/src/hyperresearch/skills/hyperresearch-2-width-sweep.md b/src/hyperresearch/skills/hyperresearch-2-width-sweep.md
index 587148b..c6f3412 100644
--- a/src/hyperresearch/skills/hyperresearch-2-width-sweep.md
+++ b/src/hyperresearch/skills/hyperresearch-2-width-sweep.md
@@ -142,8 +142,10 @@ prompt: |
PIPELINE POSITION: You are step 2 (width-sweep fetcher) of the
hyperresearch V8 pipeline. The orchestrator partitioned the URL queue into
- non-overlapping batches; you fetch ONLY the URLs in your batch. Do not
- search for additional URLs. After you return, the orchestrator runs a
+ non-overlapping batches; your batch is closed to new topic searches. Fetch
+ the URLs in your batch, then chase the primary sources those pages cite
+ (your Phase 2 citation-chasing, within its cap). Do not run new searches
+ for other URLs on the topic. After you return, the orchestrator runs a
coverage check (step 2.5) and may dispatch wave 2 fetchers.
YOUR INPUTS:
@@ -154,7 +156,7 @@ prompt: |
RUN DIRECTIVES: append the FULL contents of research/runs/<vault_tag>/shims/research.md here, verbatim.
```
-**CRITICAL: no token waste.** Each fetcher gets ONLY its batch. No fetcher searches for new URLs or duplicates another fetcher's work. If a fetcher finishes early, it's done.
+**CRITICAL: no token waste.** Each fetcher gets ONLY its batch, plus the primary sources its batch pages cite (citation-chasing stays mandatory, within the fetcher's cap). No fetcher runs new topic searches or duplicates another fetcher's work. If a fetcher finishes early, it's done.
<% if platform == "codex" %>**CRITICAL: do not end your turn while waiting.** Wait for every fetcher to finish; a message with no tool call ends the run in `codex exec`.<% else %>**CRITICAL: never emit bare text while waiting.** In `-p` mode, a text-only response triggers `end_turn`.<% endif %>
diff --git a/src/hyperresearch/skills/hyperresearch-7-source-tensions.md b/src/hyperresearch/skills/hyperresearch-7-source-tensions.md
index bbd6562..352613d 100644
--- a/src/hyperresearch/skills/hyperresearch-7-source-tensions.md
+++ b/src/hyperresearch/skills/hyperresearch-7-source-tensions.md
@@ -32,7 +32,7 @@ Read these inputs:
## Procedure
-1. **Re-read `comparisons.md`.** Each tension there is already a candidate source tension. Extract: the two positions, the strongest evidence for each, your preliminary reading of which side has the better case.
+1. **Re-read `comparisons.md`** (absent when step 4 justified zero loci via `skip_loci`; go straight to the orphan scan). 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_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)
@@ -87,7 +87,7 @@ This artifact feeds directly into step 10's mandatory Source Tensions section. E
## Exit criterion
-- `research/runs/<vault_tag>/temp/source-tensions.json` exists with << p.source_tensions|dash >> tensions
+- `research/runs/<vault_tag>/temp/source-tensions.json` exists with << p.source_tensions|dash >> tensions. Fewer, down to zero, is allowed only when the corpus genuinely lacks real disagreements (the case where step 4 justified `skip_loci` with a univocal corpus): write the tensions you did find plus a top-level `"shortfall_reason"` naming what you read and why no further tensions exist. Never invent a tension to reach the range.
- Each tension has both sides with proponents, a committed resolution, and decision_relevance
---
diff --git a/src/hyperresearch/skills/hyperresearch.md b/src/hyperresearch/skills/hyperresearch.md
index d7721fa..d158531 100644
--- a/src/hyperresearch/skills/hyperresearch.md
+++ b/src/hyperresearch/skills/hyperresearch.md
@@ -287,7 +287,7 @@ Ship only after `run finish` reports `"passed": true`: the final report lives at
## Invariants you cannot break
1. **PATCHING not REGENERATION after step 11.** Once step 11 produces the final report (or step 10 for light tier), modifications are surgical <% if platform == "codex" %>patch<% else %>Edit<% endif %> hunks only.
-2. **One final report.** Step 11's synthesizer writes the final report ONCE. No re-synthesizing. (Light tier: step 10 writes it once.)
+2. **One final report.** Step 11's synthesizer writes the final report ONCE. No re-synthesizing. (Light tier: step 10 writes it once.) The one exception is the ship gate's `length-in-range` compression pass, which runs the synthesizer on its own output to shorten it, never to re-synthesize from the drafts.
3. **At least one dialectical locus.** Step 4 must surface ≥1 dialectical locus unless skip is justified.
4. **Every interim note commits to a position.** Step 5 investigators end with `## Committed position`.
5. **`research/runs/<vault_tag>/comparisons.md` exists when loci count ≥ 1.** Step 6 is mandatory whenever step 4 produced any loci.
diff --git a/tests/fixtures/golden_prompts/skills/hyperresearch-16-readability-audit.md b/tests/fixtures/golden_prompts/skills/hyperresearch-16-readability-audit.md
index 03e1a01..83b2909 100644
--- a/tests/fixtures/golden_prompts/skills/hyperresearch-16-readability-audit.md
+++ b/tests/fixtures/golden_prompts/skills/hyperresearch-16-readability-audit.md
@@ -59,7 +59,8 @@ prompt: |
RUN DIRECTIVES: append the FULL contents of research/runs/<vault_tag>/shims/polish.md here, verbatim.
- Write recommendations as a JSON array per the schema in your agent
+ Write recommendations as a JSON object (`recommendations` array plus
+ `summary`) per the schema in your agent
prompt. Cap at 50 recommendations, prioritized by impact.
```
@@ -159,8 +160,8 @@ This is the audit trail. If a future review finds a readability problem we shoul
---
-## Pipeline complete
+## Next: the ship gate
-Return to the entry skill (`hyperresearch`). Mark all todos complete. Tell the user the final report path.
+Return to the entry skill (`hyperresearch`) and run its **Final integrity gate** (`run finish`). Mark all todos complete. Only after `run finish` reports `"passed": true` (or the run is honestly `blocked` after 3 fix rounds), tell the user the final report path and list any still-queued escalations.
-You're done.
+The run is not done until the gate has spoken.
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 2143a5a..1218785 100644
--- a/tests/fixtures/golden_prompts/skills/hyperresearch-2-width-sweep.md
+++ b/tests/fixtures/golden_prompts/skills/hyperresearch-2-width-sweep.md
@@ -142,8 +142,10 @@ prompt: |
PIPELINE POSITION: You are step 2 (width-sweep fetcher) of the
hyperresearch V8 pipeline. The orchestrator partitioned the URL queue into
- non-overlapping batches; you fetch ONLY the URLs in your batch. Do not
- search for additional URLs. After you return, the orchestrator runs a
+ non-overlapping batches; your batch is closed to new topic searches. Fetch
+ the URLs in your batch, then chase the primary sources those pages cite
+ (your Phase 2 citation-chasing, within its cap). Do not run new searches
+ for other URLs on the topic. After you return, the orchestrator runs a
coverage check (step 2.5) and may dispatch wave 2 fetchers.
YOUR INPUTS:
@@ -154,7 +156,7 @@ prompt: |
RUN DIRECTIVES: append the FULL contents of research/runs/<vault_tag>/shims/research.md here, verbatim.
```
-**CRITICAL: no token waste.** Each fetcher gets ONLY its batch. No fetcher searches for new URLs or duplicates another fetcher's work. If a fetcher finishes early, it's done.
+**CRITICAL: no token waste.** Each fetcher gets ONLY its batch, plus the primary sources its batch pages cite (citation-chasing stays mandatory, within the fetcher's cap). No fetcher runs new topic searches or duplicates another fetcher's work. If a fetcher finishes early, it's done.
**CRITICAL: never emit bare text while waiting.** In `-p` mode, a text-only response triggers `end_turn`.
diff --git a/tests/fixtures/golden_prompts/skills/hyperresearch.md b/tests/fixtures/golden_prompts/skills/hyperresearch.md
index fec8d15..fc32398 100644
--- a/tests/fixtures/golden_prompts/skills/hyperresearch.md
+++ b/tests/fixtures/golden_prompts/skills/hyperresearch.md
@@ -249,7 +249,7 @@ Ship only after `run finish` reports `"passed": true`: the final report lives at
## Invariants you cannot break
1. **PATCHING not REGENERATION after step 11.** Once step 11 produces the final report (or step 10 for light tier), modifications are surgical Edit hunks only.
-2. **One final report.** Step 11's synthesizer writes the final report ONCE. No re-synthesizing. (Light tier: step 10 writes it once.)
+2. **One final report.** Step 11's synthesizer writes the final report ONCE. No re-synthesizing. (Light tier: step 10 writes it once.) The one exception is the ship gate's `length-in-range` compression pass, which runs the synthesizer on its own output to shorten it, never to re-synthesize from the drafts.
3. **At least one dialectical locus.** Step 4 must surface ≥1 dialectical locus unless skip is justified.
4. **Every interim note commits to a position.** Step 5 investigators end with `## Committed position`.
5. **`research/runs/<vault_tag>/comparisons.md` exists when loci count ≥ 1.** Step 6 is mandatory whenever step 4 produced any loci.
diff --git a/tests/test_core/test_prompt_golden.py b/tests/test_core/test_prompt_golden.py
index f2d8355..4ad8ed0 100644
--- a/tests/test_core/test_prompt_golden.py
+++ b/tests/test_core/test_prompt_golden.py
@@ -110,6 +110,11 @@ Deliberate deviations already folded into the goldens (2026-07-19):
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.
+ - Prompt contract wording (#102): the router's invariant 2 names the
+ ship gate's compression pass as its exception; width-sweep fetchers
+ keep citation-chasing inside a batch closed to new topic searches;
+ step 16 writes recommendations as a JSON object and hands off to the
+ ship gate instead of declaring the run done.
"""
from __future__ import annotations