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

feat: pedagogy primers, calm grouped citations, register discipline (#50)

Jordan Gibbs1e33dbcd3b65
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b068ddd..e016b9c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,12 @@ The first end-to-end premier benchmark run exposed both prose-only gates failing
- **`verify_run` now includes the blocking content lints** (`quote-integrity`, `retracted-citations`) in-process, so one command carries the whole verdict and there is no seam where a failing rule can be run separately and argued with.
- **Length enforcement moved upstream too.** Step 11 gains a mechanical word-count gate with the one permitted fix (a single synthesizer compression respawn, cheapest at that moment); the synthesizer's word-target table is now rendered from the profile (it was hardcoded to full-gear numbers, so premier's 8-16K target never reached the prompt) with the high end stated as a hard ceiling; the polish auditor strips quotation marks from non-verbatim rhetorical framing before the gate ever sees them.
+### Report register: pedagogy primers, calm citations, and de-AI'd prose
+
+- **Pedagogy primers.** A four-report comparison on bench Q62 (benchmark reference vs. two pipeline generations) showed the judge's only consistent losses were pedagogy and audience adaptation, never coverage or insight: the reference teaches each concept before judging it; our reports open expert-dense. Every major body section now starts with a 3-5 sentence plain-language primer (what the thing is, how it works, why it matters here) before the analysis. Written by the synthesizer (pass-1 requirement + pass-2 structural gate), enforced by a new instruction-critic check (`missing-section-primers`).
+- **Calm citation style.** Stacked brackets (`[7][8][79]`) made claim-dense prose read like a parts list. New style: one citation point per sentence at the sentence end, multiple sources grouped in a single bracket (`[7, 12]`, capped at 3), same-source sentence runs consolidated to one marker, and number-bearing or quoting sentences always keeping their own anchor so cite-check pair verification stays exact. All four mechanical consumers understand grouped markers (cite-check triage splits them into per-source pairs; `run verify` citation density counts cited sources rather than brackets, so grouping never lowers measured density; the quote/numeric lint strips them; style-preservation accepts them). The polish auditor's one permitted citation edit is merging an adjacent stack into a grouped bracket, numbers verbatim.
+- **Register discipline, distilled from a humanization ruleset.** The synthesizer's pass-2 audit and the polish auditor now target the two loudest machine-writing tells in past reports: meta-descriptive text (narrating what the report or section is doing instead of saying it; self-describing prose; section-number cross-references) is deleted on sight, and hedging is restricted to unverified specifics — provenance-stated scoping stays, but conclusions the report argues for are asserted bare, and hedge-stacks ("may potentially indicate") always collapse. Dramatic standalone kicker sentences are rationed to one per section, and the primers double as rhythm breaks so density stays readable.
+
### Per-agent models are now real config; dollar-cost claims removed
- **ModelMap wired into agent rendering.** The profile's per-agent model map existed but was decorative — every installed agent's `model:` frontmatter line was hardcoded in `hooks.py`, so overriding models via a profile silently did nothing. All 16 agent templates now carry `model: << p.models.X >>`, rendered from the profile at install time, and `ModelMap` gained the two missing agents (`cite_checker`, `browser_fetcher`) plus validation (non-empty; aliases or full model IDs both accepted). Full flexibility per agent: `[profile.full]` + `models = { fetcher = "haiku" }` swaps every fetcher to Haiku on the next install/`profile use`; unspecified agents keep their defaults. Defaults are unchanged (verified byte-identical by the goldens).
diff --git a/src/hyperresearch/cli/lint.py b/src/hyperresearch/cli/lint.py
index 35db65c..8f32adf 100644
--- a/src/hyperresearch/cli/lint.py
+++ b/src/hyperresearch/cli/lint.py
@@ -104,7 +104,7 @@ def _report_body_only(report_text: str) -> str:
import re as _re
body = _re.split(r"^##\s+(?:Sources|References)\b", report_text, maxsplit=1, flags=_re.M | _re.I)[0]
- return _re.sub(r"\[\d{1,3}\]", "", body)
+ return _re.sub(r"\[\d{1,3}(?:\s*,\s*\d{1,3})*\]", "", body)
def _check_quote_integrity(vault, conn, report_path, report_text) -> list[dict]:
@@ -1482,7 +1482,9 @@ def lint(
elif citation_style == "inline":
import re as _re
- has_numbered_ref = bool(_re.search(r"\[\d+\]", report_text))
+ has_numbered_ref = bool(
+ _re.search(r"\[\d+(?:\s*,\s*\d+)*\]", report_text)
+ )
has_refs_heading = bool(_re.search(
r"^#{1,6}\s*(sources|references)\b",
report_text,
diff --git a/src/hyperresearch/core/citecheck.py b/src/hyperresearch/core/citecheck.py
index db6def3..bf6ab03 100644
--- a/src/hyperresearch/core/citecheck.py
+++ b/src/hyperresearch/core/citecheck.py
@@ -28,7 +28,7 @@ from hyperresearch.core.patterns import WIKI_LINK_RE
# Sentence split: period/question/exclamation followed by space+capital, or newline.
_SENTENCE_SPLIT_RE = re.compile(r"(?<=[.!?])\s+(?=[A-Z一-鿿])|\n+")
-_NUMBERED_CITE_RE = re.compile(r"\[(\d{1,3})\]")
+_NUMBERED_CITE_RE = re.compile(r"\[(\d{1,3}(?:\s*,\s*\d{1,3})*)\]")
_SOURCES_ENTRY_RE = re.compile(r"^\s*\[(\d{1,3})\]\s+(.+)$")
_NUMBER_RE = re.compile(r"\d[\d,]*\.?\d*%?")
@@ -91,8 +91,9 @@ def extract_pairs(report_text: str, conn) -> list[dict]:
for sentence in _split_sentences(body):
cited: list[str | None] = []
for m in _NUMBERED_CITE_RE.finditer(sentence):
- if m.group(1) in numbered_map:
- cited.append(numbered_map[m.group(1)])
+ for num in re.split(r"\s*,\s*", m.group(1)):
+ if num in numbered_map:
+ cited.append(numbered_map[num])
for m in WIKI_LINK_RE.finditer(sentence):
target = m.group(1).strip()
cited.append(target if target in known_ids else None)
diff --git a/src/hyperresearch/core/hooks.py b/src/hyperresearch/core/hooks.py
index 3c24eb8..ec0137f 100644
--- a/src/hyperresearch/core/hooks.py
+++ b/src/hyperresearch/core/hooks.py
@@ -1159,9 +1159,10 @@ them on first use (inline parenthetical or dedicated glossary), emit:
a brief parenthetical definition on first mention
**Check R2: Citation density.**
-Count inline `[N]` citations in the body (excluding the ## Sources
-section). Count total body characters. If the ratio is below **1.5
-citations per 1000 characters**, emit:
+Count cited-source references in the body (excluding the ## Sources
+section) — a grouped marker like `[7, 12]` counts as two. Count total
+body characters. If the ratio is below **1.5 citations per 1000
+characters**, emit:
- `failure_mode`: `"low-citation-density"`
- `severity`: `major`
- `recommendation`: identify 5-8 claim-dense passages with no
@@ -1183,6 +1184,16 @@ prose (no comparison table), emit:
- `severity`: `minor`
- `recommendation`: suggest converting the comparison to a table
+**Check R5: Section primers.**
+If 2+ major body sections open directly with evaluation, ranking, or
+dense quantitative analysis — no 3-5 sentence plain-language primer
+explaining the section's subject (what it is, how it works, why it
+matters here) before the judgment starts — emit ONE finding:
+ - `failure_mode`: `"missing-section-primers"`
+ - `severity`: `major`
+ - `recommendation`: name the sections that need a primer and, for
+ each, the concept the primer should teach
+
**Cap:** At most **3** readability-structural findings total. Do not
let these crowd out core instruction-following findings. Use
`"readability-structural"` as the `atomic_item` prefix for these.
@@ -1470,7 +1481,10 @@ Also strip:
decorative quote you leave is a guaranteed gate failure.
- **Citation pass-through.** Leave all `[N]` inline citations and the
Sources/References section exactly as the drafter wrote them.
- Citations are a product feature, not a polish target.
+ Citations are a product feature, not a polish target. The ONE
+ permitted citation edit: merging an adjacent stack (`[3][4][5]`)
+ into a single grouped bracket (`[3, 4, 5]`) — numbers preserved
+ verbatim, nothing dropped, nothing renumbered.
Every leak is a **critical** polish fix. Apply as an Edit that removes
the offending block entirely.
@@ -1595,6 +1609,27 @@ Edit out sentences that restate the prior sentence. If a paragraph ends
with a sentence that summarizes what the prior two sentences said, the
summary sentence usually goes.
+**3-meta. Meta-discourse (high priority — the signature machine-writing
+tell).** Delete every clause that narrates what the report or section is
+doing instead of saying the thing:
+
+- "This report examines / evaluates / turns to..."
+- "This section maps / covers / addresses..."
+- "As noted above / as discussed in section N" when the point is
+ restated right there (keep the restatement, cut the narration)
+- "a caveat developed in section 10" / "declared up front so the
+ analysis can return to them"
+- "The interpretive point the sources do not make:" and kin — cut the
+ frame, keep the interpretive point
+- Self-describing adjectives about the report's own prose ("a brief
+ overview", "a quick summary", "this concise assessment")
+
+The fix is deletion or a minimal splice, not a rewrite: "This section
+maps the four strategies. The first is X..." becomes "The first
+strategy is X...". If a cross-reference is genuinely load-bearing,
+rephrase it by topic ("the yield question, below") rather than by
+section number.
+
### 3a. Hedge language that softens committed claims
The draft upstream was built to commit to positions. If the patcher
@@ -1626,6 +1661,10 @@ would support a stronger claim:
Either delete it (if the claim is strong enough to stand) or
escalate to the orchestrator noting the claim may need scoping —
but do not leave a bare "may be different" hedge on the draft.
+- **Hedge-stacks.** Two or more softeners on one claim ("may
+ potentially indicate", "could arguably suggest", "seems to
+ possibly") always collapse to at most one hedge — or none, when
+ the paragraph's evidence supports the bare claim.
Do NOT strike hedges on genuinely speculative claims (forecasts
without data, open questions, places where the underlying evidence
@@ -1660,8 +1699,9 @@ Look for:
- Sentences longer than ~50 words — break in two
- Paragraphs longer than ~200 words — break in two by finding a natural
hinge
-- Dense stacked citations (`[3][4][5][6]`) — consolidate to 1-2 per
- claim for readability.
+- Adjacent citation brackets (`[3][4][5]`) — merge into one grouped
+ bracket (`[3, 4, 5]`), numbers verbatim; if a group exceeds 3
+ sources, escalate rather than dropping any yourself.
## Procedure
@@ -2023,13 +2063,16 @@ permitted to be uneven — pass 2 cleans it up. Goals for pass 1:
evidence from whichever draft surfaced it. Pull the strongest
argumentative beat from whichever draft made it best. Re-state both
in your voice.
-4. **Cite as you write — high density.** Use `[N]` markers (numbered fresh
- from `[1]` at first citation in pass 1). Build the `## Sources` list as
- you go. **Citation density target: 80-150 total citations** for
- `argumentative` format, 40-80 for `structured`, 15-30 for `short` —
- roughly 2+ citations per 1000 characters. Every claim-dense paragraph
- should have at least one inline citation. Under-citation is a
- consistent scoring gap versus reference reports.
+4. **Cite as you write — high density, calm presentation.** Use `[N]`
+ markers (numbered fresh from `[1]` at first citation in pass 1). Build
+ the `## Sources` list as you go. **Citation density target: 80-150
+ total cited-source references** for `argumentative` format, 40-80 for
+ `structured`, 15-30 for `short` — roughly 2+ per 1000 characters,
+ where a grouped marker like `[7, 12]` counts as two. Every claim-dense
+ paragraph needs at least one citation point. Under-citation is a
+ consistent scoring gap versus reference reports. Placement follows the
+ calm citation style in the pass-2 Citation discipline section — write
+ to it from the start so pass 2 isn't a citation rewrite.
5. **Cover every atomic item.** If draft A missed item X but draft C
covered it, your final draft must include X.
6. **Engage cross-locus tensions explicitly** where they bear on a
@@ -2053,6 +2096,17 @@ permitted to be uneven — pass 2 cleans it up. Goals for pass 1:
frameworks) across 2 or more dimensions (cost, performance, scope,
timeline), use a markdown table — not prose. Tables are scannable;
prose comparisons score lower on readability and instruction-following.
+11. **Open every major body section with a pedagogy primer.** Before any
+ evaluation, ranking, or audit, give the reader 3-5 plain sentences
+ that teach the section's subject to a technically informed
+ non-specialist: what the thing is, how it works mechanically, and why
+ it matters for the research question. THEN argue. Reference-quality
+ reports win their readability scores on exactly this move — patient
+ explanation first, dense judgment second — and expert-pitched reports
+ that skip straight to the analysis lose those points every time. The
+ primer is not filler; it is the on-ramp that makes the density that
+ follows legible. Skip it only for the executive summary and for
+ short connective sections with nothing new to explain.
Pass 1 length target: in the response_format range, leaning slightly long
(15-20% over target). Pass 2 cuts.
@@ -2135,9 +2189,68 @@ If pass 1 is under target, EXPAND. Specifically:
Three citation styles. Match `citation_style` from the decomposition:
- **`"wikilink"`** (default for non-wrapped runs): every citation is a `[[<source-note-id>]]` marker pointing at the source note in the vault. No separate `## Sources` section. Each wiki-link self-resolves to the source note's frontmatter (title + URL). Aim for 2+ citations per 1000 characters. Copy note IDs verbatim from the input drafts and the evidence digest.
-- **`"inline"`** (benchmark + public deliverables): `[N]` citations renumbered from `[1]` deterministically in order of first appearance, AND a single `## Sources` section at the end with one entry per cited source (deduplicated). Format: `[1] Author(s). "Title." *Publication*, Year. URL`. Aim for 2+ citations per 1000 characters.
+- **`"inline"`** (benchmark + public deliverables): `[N]` citations renumbered from `[1]` deterministically in order of first appearance, AND a single `## Sources` section at the end with one entry per cited source (deduplicated). Format: `[1] Author(s). "Title." *Publication*, Year. URL`.
- **`"none"`**: no citation markers anywhere, no Sources section.
+**Calm citation placement (applies to both marker styles).** Density
+without clutter. The failure mode this prevents: sentences studded with
+three or four bracket stacks that make the prose read like a parts list.
+
+- **One citation point per sentence, at the end** (before the final
+ period) is the default.
+- **Group, never stack.** Multiple sources at one citation point go in
+ ONE bracket, comma-separated: `[7, 12]`, never `[7][12]`. Adjacent
+ brackets (`][`) must not appear anywhere in the report. Cap a group at
+ 3 sources — beyond that, cite the strongest and drop the rest.
+- **Mid-sentence citations only anchor specifics.** A specific figure,
+ measured value, or verbatim quote keeps its citation directly beside
+ it. Everything else waits for the sentence end.
+- **Consolidate runs.** When consecutive sentences in a paragraph draw
+ on the same source(s), cite once at the end of the run — EXCEPT
+ sentences carrying a specific number or a verbatim quote, which always
+ keep their own anchor (the citation checker verifies number-bearing
+ sentences pair-by-pair, and an unanchored figure is an automatic
+ finding).
+
+### Register discipline (write like an expert author, not a model)
+
+Four rules, applied while editing pass 1. They make the report denser
+and less annoying to read; each targets a documented machine-writing
+tell.
+
+- **Zero meta-discourse.** Delete every clause that narrates what the
+ report, section, or sentence is doing rather than saying the thing:
+ "This report evaluates...", "This section maps the strategies",
+ "declared up front so the analysis can return to them", "a caveat
+ developed in section 10", "The interpretive point the sources do not
+ make:", "as noted above", "It is worth pausing to observe that".
+ State the content and trust the reader. Cross-references earn their
+ place only when the reader genuinely cannot follow without one, and
+ they point at the topic ("the yield question"), not at a section
+ number. Announcing what you are about to argue is not argument.
+- **Hedging discipline.** Hedge unverified specifics; own your
+ conclusions. A secondhand figure nobody has replicated gets its
+ provenance stated ("the only published measurement is X; nothing
+ above 30 qubits exists in print") — that is scoping, not hedging.
+ But conclusions this report argues for are asserted bare: no "may
+ suggest", no "it could be argued that", and never a hedge-stack
+ ("may potentially indicate"). Hedging everything reads as mush;
+ hedging nothing reads as bravado. Put the uncertainty in the
+ evidence, not in the verb.
+- **Ration the kickers.** A short dramatic standalone sentence built
+ for effect ("Width and width do not compose into speed.") is a
+ strong move exactly once per section, at most. When every paragraph
+ ends on a bolded aphorism the report reads as performance and the
+ genuine findings drown. Fold the surplus into the surrounding
+ sentence as a plain clause; keep the one that earns the emphasis.
+- **Vary the rhythm.** Alternate the register: after a dense
+ evidence-heavy passage, give the reader a plain declarative sentence
+ or two. Mix sentence lengths — a 500-word stretch where every
+ sentence runs 20-30 words with two subordinate clauses and a
+ bracketed citation is exhausting no matter how good the content is.
+ The primer paragraphs (pass 1, item 11) are the natural breathing
+ points; keep them plain.
+
### Hygiene
The final draft MUST NOT contain:
@@ -2171,12 +2284,17 @@ cause of low instruction-following scores:
subsection near the end).
- **Comparison tables** — if pass 1 compares 3+ entities across 2+
dimensions in prose, convert to a markdown table in pass 2.
-- **Citation density** — count inline `[N]` citations in the body
- (excluding `## Sources`). If the ratio is below 1.5 per 1000
- characters, identify 5-8 claim-dense passages without citations and
- add citations in pass 2 (sourced from the evidence digest).
-
-These five checks are NOT optional polish — they're structural
+- **Section primers** — verify every major body section opens with the
+ 3-5 sentence plain-language primer (pass 1, item 11) before the
+ analysis starts. Where a section dives straight into evaluation,
+ write the primer in pass 2.
+- **Citation density** — count cited-source references in the body
+ (excluding `## Sources`; a grouped `[7, 12]` counts as two). If the
+ ratio is below 1.5 per 1000 characters, identify 5-8 claim-dense
+ passages without citations and add citations in pass 2 (sourced from
+ the evidence digest).
+
+These six checks are NOT optional polish — they're structural
requirements that drive instruction-following scores. Pass 2 is the
LAST chance to add them. The polish auditor (step 15) only does
hygiene/filler cuts; the readability recommender (step 16) only
diff --git a/src/hyperresearch/core/runs.py b/src/hyperresearch/core/runs.py
index 9043e42..bbb3559 100644
--- a/src/hyperresearch/core/runs.py
+++ b/src/hyperresearch/core/runs.py
@@ -384,9 +384,12 @@ def verify_run(vault, vault_tag: str) -> dict:
import re as _re
- cites = len(_re.findall(r"\[\d{1,3}\]", report_text)) + len(
- _re.findall(r"\[\[[^\]]+\]\]", report_text)
- )
+ # Grouped markers ([7, 12]) count one citation per source number,
+ # so consolidating stacks never lowers measured density.
+ cites = sum(
+ len(g.split(","))
+ for g in _re.findall(r"\[(\d{1,3}(?:\s*,\s*\d{1,3})*)\]", report_text)
+ ) + len(_re.findall(r"\[\[[^\]]+\]\]", report_text))
density = cites / max(1, len(report_text)) * 1000
floor = 1.5 # instruction-critic's re-count trigger
check(
diff --git a/src/hyperresearch/skills/hyperresearch-1-decompose.md b/src/hyperresearch/skills/hyperresearch-1-decompose.md
index 491666a..9f9d007 100644
--- a/src/hyperresearch/skills/hyperresearch-1-decompose.md
+++ b/src/hyperresearch/skills/hyperresearch-1-decompose.md
@@ -128,7 +128,7 @@ Read both before starting. The vault_tag is in the scaffold's "Run config" secti
| Style | When to use | Output |
|-------|-------------|--------|
| `"wikilink"` | **Default.** Personal use in a vault — every citation is a clickable wiki-link back to the raw source note in `research/notes/`. | `[[note-id]]` markers inline. No separate Sources section (each link self-resolves to the source note's frontmatter title + URL). |
- | `"inline"` | Public deliverable, benchmark wrappers, or verifiable research report for someone outside the vault. | `[N]` inline citations + a formatted `## Sources` list at the end. |
+ | `"inline"` | Public deliverable, benchmark wrappers, or verifiable research report for someone outside the vault. | `[N]` inline citations (grouped `[7, 12]` when one point cites several sources) + a formatted `## Sources` list at the end. |
| `"none"` | Polished expert-analysis with no visible citation apparatus. | No citation markers, no Sources section. |
**Wrapper override:** if `research/wrapper_contract.json` exists and specifies `citation_style`, it overrides the default. The benchmark harness sets `"inline"` via wrapper_contract so RACE evaluators can read numbered references; everything else gets the wikilink default.
diff --git a/src/hyperresearch/skills/hyperresearch-11-synthesize.md b/src/hyperresearch/skills/hyperresearch-11-synthesize.md
index e8ab861..c22eea5 100644
--- a/src/hyperresearch/skills/hyperresearch-11-synthesize.md
+++ b/src/hyperresearch/skills/hyperresearch-11-synthesize.md
@@ -190,10 +190,11 @@ prompt: |
separate `## Sources` section. The wiki-link IS the citation —
readers click through to the source note's frontmatter for title +
URL. Do NOT add numbered references.
- - If citation_style == "inline": every citation is a `[N]` marker,
- AND the report ends with a `## Sources` section listing each cited
- source as `[N] Title. URL` (read each cited note's YAML frontmatter
- for title + URL).
+ - If citation_style == "inline": every citation is a `[N]` marker
+ (multiple sources at one point grouped in a single bracket:
+ `[7, 12]`, never stacked `[7][12]`), AND the report ends with a
+ `## Sources` section listing each cited source as `[N] Title. URL`
+ (read each cited note's YAML frontmatter for title + URL).
- If citation_style == "none": no citation markers anywhere, no
Sources section.
```
@@ -221,6 +222,8 @@ When the synthesizer returns:
- **LENGTH GATE (mechanical, not a judgment call):** count the words (`wc -w` or python). The profile ceiling for the response_format is a HARD limit — the ship gate (`run finish`) fails any report more than 20% over target, so an over-long report here is guaranteed rework later. Check it now, when fixing is cheapest.
- Has all H2s from `required_section_headings`
- Citations match `citation_style`: `[[note-id]]` markers for `"wikilink"` (no Sources section); `[N]` markers + a `## Sources` section for `"inline"`; no markers for `"none"`
+ - No adjacent citation stacks (`grep -c ']['` should be 0 — grouped brackets like `[7, 12]` are the style)
+ - Major body sections open with a plain-language primer before the analysis (spot-check 3 sections)
- No YAML frontmatter, no scaffold leaks, no pipeline vocabulary
If pass 2 is longer than pass 1 (positive delta), something went wrong — pass 2 is supposed to cut. Investigate before proceeding.
@@ -242,7 +245,7 @@ After this step, the final report is only modified by Edit hunks from the patche
- `research/notes/final_report_<vault_tag>.md` exists, **word count verified ≤ target high** (counted mechanically, not estimated)
- `research/runs/<vault_tag>/temp/synthesis-pass1.md` exists (debugging artifact)
- All H2s from `required_section_headings` present
-- Citations match `citation_style` (wikilink → `[[note-id]]` no Sources section; inline → `[N]` + Sources section; none → no markers)
+- Citations match `citation_style` (wikilink → `[[note-id]]` no Sources section; inline → `[N]` + Sources section; none → no markers), with no adjacent citation stacks
- No YAML frontmatter, no pipeline vocabulary, no scaffold leaks
---
diff --git a/src/hyperresearch/skills/hyperresearch-14-5-cite-check.md b/src/hyperresearch/skills/hyperresearch-14-5-cite-check.md
index ef42f4e..f690c78 100644
--- a/src/hyperresearch/skills/hyperresearch-14-5-cite-check.md
+++ b/src/hyperresearch/skills/hyperresearch-14-5-cite-check.md
@@ -32,7 +32,7 @@ Read these inputs:
$HPR citecheck extract <vault_tag> -j
```
-This parses every (sentence, citation) pair from the report — both `[N]` 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:
+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:
- `summary` — total / auto-passed / dangling / needs-llm counts
- `sampled_for_llm` — the pairs the agent must judge (100% of number-bearing sentences; sampled for the rest)
- `dangling` — citations that resolve to NO vault note
diff --git a/tests/fixtures/golden_prompts/agents/instruction_critic_agent.md b/tests/fixtures/golden_prompts/agents/instruction_critic_agent.md
index b8d015e..f096286 100644
--- a/tests/fixtures/golden_prompts/agents/instruction_critic_agent.md
+++ b/tests/fixtures/golden_prompts/agents/instruction_critic_agent.md
@@ -216,9 +216,10 @@ them on first use (inline parenthetical or dedicated glossary), emit:
a brief parenthetical definition on first mention
**Check R2: Citation density.**
-Count inline `[N]` citations in the body (excluding the ## Sources
-section). Count total body characters. If the ratio is below **1.5
-citations per 1000 characters**, emit:
+Count cited-source references in the body (excluding the ## Sources
+section) — a grouped marker like `[7, 12]` counts as two. Count total
+body characters. If the ratio is below **1.5 citations per 1000
+characters**, emit:
- `failure_mode`: `"low-citation-density"`
- `severity`: `major`
- `recommendation`: identify 5-8 claim-dense passages with no
@@ -240,6 +241,16 @@ prose (no comparison table), emit:
- `severity`: `minor`
- `recommendation`: suggest converting the comparison to a table
+**Check R5: Section primers.**
+If 2+ major body sections open directly with evaluation, ranking, or
+dense quantitative analysis — no 3-5 sentence plain-language primer
+explaining the section's subject (what it is, how it works, why it
+matters here) before the judgment starts — emit ONE finding:
+ - `failure_mode`: `"missing-section-primers"`
+ - `severity`: `major`
+ - `recommendation`: name the sections that need a primer and, for
+ each, the concept the primer should teach
+
**Cap:** At most **3** readability-structural findings total. Do not
let these crowd out core instruction-following findings. Use
`"readability-structural"` as the `atomic_item` prefix for these.
diff --git a/tests/test_cli/test_lint.py b/tests/test_cli/test_lint.py
index c1dd4a2..ad0ff22 100644
--- a/tests/test_cli/test_lint.py
+++ b/tests/test_cli/test_lint.py
@@ -1510,6 +1510,31 @@ def test_citation_preservation_inline_passes_with_refs_and_heading(tmp_vault):
assert _citation_issues(out) == []
+def test_citation_preservation_inline_accepts_grouped_markers(tmp_vault):
+ _write_source(tmp_vault, "Battery Paper", "battery-paper")
+ _write_decomposition(tmp_vault, citation_style="inline")
+ _write_final_report(
+ tmp_vault,
+ "# Report\n\nDensity doubled [1, 2].\n\n## Sources\n\n"
+ "1. Chen et al. 2025\n2. Park 2026\n",
+ )
+ _, out = _run_lint(tmp_vault, rule="citation-style-preservation")
+ assert _citation_issues(out) == []
+
+
+def test_report_body_only_strips_grouped_citation_markers():
+ from hyperresearch.cli.lint import _report_body_only
+
+ body = _report_body_only(
+ "Claim one [1]. Claim two [2, 14]. Claim three [3,4]. "
+ "A 12,000-unit figure survives.\n\n## Sources\n[1] A\n"
+ )
+ assert "[1]" not in body
+ assert "[2, 14]" not in body
+ assert "[3,4]" not in body
+ assert "12,000-unit" in body
+
+
def test_citation_preservation_inline_flags_missing_refs(tmp_vault):
_write_source(tmp_vault, "Battery Paper", "battery-paper")
_write_decomposition(tmp_vault, citation_style="inline")
diff --git a/tests/test_core/test_prompt_golden.py b/tests/test_core/test_prompt_golden.py
index d939360..cc60a5b 100644
--- a/tests/test_core/test_prompt_golden.py
+++ b/tests/test_core/test_prompt_golden.py
@@ -54,6 +54,15 @@ Deliberate deviations already folded into the goldens (2026-07-19):
+ manifest flip, no-override language, bounded fix loop) instead of the
advisory verify+lint checklist, and invariant 14 makes `passed: true`
the only definition of complete.
+ - Report register + calm citations (2026-07-20, after the Q62 four-report
+ comparison showed the judge's only consistent losses were pedagogy and
+ readability): the instruction critic gained check R5 (section primers)
+ and R2 now counts grouped citation markers (`[7, 12]` = two citations).
+ The synthesizer and polish auditor (not golden-covered) gained the
+ primer requirement, the calm citation style (grouped brackets, sentence-
+ end placement, run consolidation with number-bearing anchors kept), and
+ register discipline (meta-discourse ban, hedging discipline, kicker
+ rationing) distilled from the humanize-ai-text skill.
"""
from __future__ import annotations
diff --git a/tests/test_core/test_verification.py b/tests/test_core/test_verification.py
index 39301e5..d7d4d08 100644
--- a/tests/test_core/test_verification.py
+++ b/tests/test_core/test_verification.py
@@ -56,6 +56,17 @@ class TestCiteCheckExtraction:
assert len(pairs) == 1
assert pairs[0]["note_id"] == "python-async-patterns"
+ def test_grouped_citation_pairs_split_per_source(self, cited_vault):
+ report = (
+ "Throughput improves 10x under load [1, 2].\n\n"
+ "## Sources\n[1] Python Async Patterns. https://example.com/async\n"
+ "[2] Unrelated Study. https://example.com/other\n"
+ )
+ pairs = extract_pairs(report, cited_vault.db)
+ assert len(pairs) == 2
+ assert pairs[0]["note_id"] == "python-async-patterns"
+ assert pairs[1]["note_id"] is None
+
def test_dangling_citation_detected(self, cited_vault):
report = "A bold claim [[no-such-note]]."
pairs = extract_pairs(report, cited_vault.db)
@@ -259,6 +270,25 @@ class TestTelemetryAndVerify:
assert by_name["citation-density"]["ok"]
assert result["passed"] is True
+ def test_verify_density_counts_each_grouped_source(self, tmp_vault):
+ init_run(tmp_vault, "vf-04", profile="light")
+ run_dir = tmp_vault.run_dir("vf-04")
+ (run_dir / "prompt-decomposition.json").write_text(json.dumps({
+ "response_format": "short",
+ "required_section_headings": ["## Findings"],
+ }), encoding="utf-8")
+ report = tmp_vault.root / "research" / "notes" / "final_report_vf-04.md"
+ filler = "Substantive analysis continues with replicated evidence in view. " * 11
+ block = filler + "The consensus across measurements holds [1, 2, 3]. "
+ report.write_text("## Findings\n\n" + block * 8, encoding="utf-8")
+
+ result = verify_run(tmp_vault, "vf-04")
+ by_name = {c["name"]: c for c in result["checks"]}
+ # One bracket per ~770 chars sits under the 1.5/1000 floor; the three
+ # sources inside each grouped bracket clear it. Counting markers
+ # instead of cited-source numbers would fail this check.
+ assert by_name["citation-density"]["ok"]
+
def test_verify_fails_on_missing_heading_and_report(self, tmp_vault):
init_run(tmp_vault, "vf-02", profile="light")
result = verify_run(tmp_vault, "vf-02")