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

58.1 KB
Raw Blame
"""Phase-5 tests: cite-check, verification lints, independence, telemetry, verify."""

from __future__ import annotations

import json

import pytest

from hyperresearch.core.citecheck import (
    extract_pairs,
    parse_sources_section,
    sample_needs_llm,
    triage_pairs,
)
from hyperresearch.core.independence import canonical_url, compute_independence
from hyperresearch.core.runs import init_run, run_report_data, set_step, verify_run


@pytest.fixture
def cited_vault(seeded_vault):
    """Seeded vault + claims + a source row so citations resolve."""
    from hyperresearch.core.claims import ingest_claims_dir

    temp = seeded_vault.root / "research" / "temp"
    temp.mkdir(parents=True, exist_ok=True)
    (temp / "claims-python-async-patterns.json").write_text(json.dumps([
        {"claim": "Async improves throughput by 10x for network-bound workloads",
         "quoted_support": "async/await syntax enables concurrent I/O with a 10x gain",
         "numbers": ["10x"], "confidence": "high", "evidence_type": "empirical"},
    ]), encoding="utf-8")
    ingest_claims_dir(seeded_vault, vault_tag="cc-run")
    seeded_vault.db.execute(
        "INSERT OR IGNORE INTO sources (url, note_id, domain, fetched_at, provider, content_hash) "
        "VALUES ('https://example.com/async', 'python-async-patterns', 'example.com', '2026-01-01', 'test', 'x')"
    )
    seeded_vault.db.commit()
    return seeded_vault


class TestCiteCheckExtraction:
    def test_wikilink_pairs(self, cited_vault):
        report = "Async gives a 10x gain [[python-async-patterns]]. Rust is safe [[rust-ownership]]."
        pairs = extract_pairs(report, cited_vault.db)
        assert len(pairs) == 2
        assert pairs[0]["note_id"] == "python-async-patterns"
        assert pairs[0]["numbers"] == ["10"] or "10x" in pairs[0]["sentence"]

    def test_numbered_pairs_resolve_via_sources_section(self, cited_vault):
        report = (
            "Throughput improves 10x [1].\n\n"
            "## Sources\n[1] Python Async Patterns. https://example.com/async\n"
        )
        mapping = parse_sources_section(report, cited_vault.db)
        assert mapping["1"] == "python-async-patterns"
        pairs = extract_pairs(report, cited_vault.db)
        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)
        assert pairs[0]["note_id"] is None
        assert pairs[0].get("unresolved") == "unknown-note-id"
        triaged = triage_pairs(pairs, cited_vault.db)
        assert triaged["dangling"] == 1

    def test_sources_entry_resolves_through_the_notes_own_source_field(self, cited_vault):
        # `note rm` leaves the sources row with note_id NULL; a note written
        # again for the work holds the URL only in its own source field.
        url = "https://repo.example.org/portal/3549507.pdf"
        cited_vault.db.execute(
            "INSERT INTO sources (url, note_id, domain, fetched_at, provider, content_hash) "
            "VALUES (?, NULL, 'repo.example.org', '2026-01-01', 'test', 'y')", (url,)
        )
        cited_vault.db.execute("UPDATE notes SET source = ? WHERE id = 'python-async-patterns'", (url,))
        cited_vault.db.commit()
        report = f"Throughput improves 10x [1].\n\n## Sources\n[1] Some Paper (A. Author, 2022). {url}\n"
        assert parse_sources_section(report, cited_vault.db)["1"] == "python-async-patterns"

    @pytest.mark.parametrize("link", [
        "[https://vendor.example.com](https://vendor.example.com)",
        "https://[vendor.example.com]/a",
        "https://vendor.example.com]",
    ])
    def test_link_that_urlsplit_rejects_is_unresolved_not_an_error(self, cited_vault, link):
        # urlsplit raises ValueError on a bracket in the host position.
        report = f"Throughput improves 10x [1].\n\n## Sources\n[1] A Vendor Page. {link}\n"
        assert parse_sources_section(report, cited_vault.db) == {"1": None}

    @pytest.mark.parametrize("link", [
        "https://dx.doi.org/10.1145/3313831.3376831",
        "https://doi.org/10.1145/3313831.3376831?utm_source=x",
    ])
    def test_doi_link_resolves_through_the_notes_doi_column(self, cited_vault, link):
        cited_vault.db.execute(
            "UPDATE notes SET doi = '10.1145/3313831.3376831' WHERE id = 'python-async-patterns'"
        )
        cited_vault.db.commit()
        report = f"Throughput improves 10x [1].\n\n## Sources\n[1] A Postmortem (CHI 2020). {link}\n"
        assert parse_sources_section(report, cited_vault.db)["1"] == "python-async-patterns"

    def test_arxiv_link_resolves_through_the_notes_doi_column(self, cited_vault):
        # fetch stores extract_doi's result, an arXiv id for arxiv.org links.
        cited_vault.db.execute("UPDATE notes SET doi = 'arXiv:2301.00001' WHERE id = 'python-async-patterns'")
        cited_vault.db.commit()
        report = "Throughput improves 10x [1].\n\n## Sources\n[1] A Preprint. https://arxiv.org/pdf/2301.00001\n"
        assert parse_sources_section(report, cited_vault.db)["1"] == "python-async-patterns"

    @pytest.mark.parametrize("link", [
        "<https://doi.org/10.1145/3313831.3376831>",
        "https://doi.org/10.1145/3313831.3376831;",
    ])
    def test_doi_link_resolves_to_a_note_saved_from_another_address(self, cited_vault, link):
        cited_vault.db.execute(
            "UPDATE notes SET source = ? WHERE id = 'python-async-patterns'",
            ("https://api.example.org/graph/v1/paper/DOI:10.1145/3313831.3376831?fields=title",),
        )
        cited_vault.db.commit()
        report = f"Throughput improves 10x [1].\n\n## Sources\n[1] A Postmortem (CHI 2020). {link}\n"
        assert parse_sources_section(report, cited_vault.db)["1"] == "python-async-patterns"

    def test_exact_doi_column_beats_an_address_that_merely_holds_the_doi(self, cited_vault):
        doi = "10.1145/3313831.3376831"
        cited_vault.db.execute("UPDATE notes SET doi = ? WHERE id = 'rust-ownership'", (doi,))
        cited_vault.db.execute(
            "UPDATE notes SET source = ? WHERE id = 'concurrency'", (f"https://cite.example/refs?doi={doi}",)
        )
        cited_vault.db.commit()
        report = f"Throughput improves 10x [1].\n\n## Sources\n[1] A Postmortem (CHI 2020). https://doi.org/{doi}\n"
        assert parse_sources_section(report, cited_vault.db)["1"] == "rust-ownership"

    def test_title_match_beats_an_address_that_merely_holds_the_doi(self, cited_vault):
        doi = "10.1145/3313831.3376831"
        cited_vault.db.execute(
            "UPDATE notes SET source = ? WHERE id = 'concurrency'", (f"https://cite.example/refs?doi={doi}",)
        )
        cited_vault.db.commit()
        report = f"Memory safety without GC [1].\n\n## Sources\n[1] Rust Ownership. https://doi.org/{doi}\n"
        assert parse_sources_section(report, cited_vault.db)["1"] == "rust-ownership"

    @pytest.mark.parametrize(("stored", "expected"), [
        ("https://x.example.org/view/10.1145/3313831.3376831", "python-async-patterns"),
        ("https://x.example.org/view/10.1145/3313831.3376831?utm=1", "python-async-patterns"),
        ("https://x.example.org/refs?doi=10.1145/3313831.3376831&from=feed", "python-async-patterns"),
        ("https://x.example.org/view/10.1145/3313831.3376831#abstract", "python-async-patterns"),
        ("https://x.example.org/view/10.1145/3313831.3376831/full", None),
    ], ids=["end", "query", "ampersand", "fragment", "slash"])
    def test_doi_inside_an_address_ends_at_the_url_end_query_or_fragment(
        self, cited_vault, stored, expected
    ):
        """`/` is part of many DOIs, so a path that goes on after the DOI may
        name another one and does not match."""
        cited_vault.db.execute(
            "UPDATE notes SET source = ? WHERE id = 'python-async-patterns'", (stored,)
        )
        cited_vault.db.commit()
        link = "https://doi.org/10.1145/3313831.3376831"
        report = f"Throughput improves 10x [1].\n\n## Sources\n[1] A Postmortem (CHI 2020). {link}\n"
        assert parse_sources_section(report, cited_vault.db)["1"] == expected

    def test_doi_that_prefixes_another_does_not_resolve_to_it(self, cited_vault):
        cited_vault.db.execute("UPDATE notes SET source = 'https://x.org/10.1000/abc1' WHERE id = 'concurrency'")
        cited_vault.db.commit()
        report = "Claim [1] and [2].\n\n## Sources\n[1] One Paper. https://doi.org/10.1000/abc\n[2] Other Paper. https://doi.org/10.1000/abc1\n"
        assert parse_sources_section(report, cited_vault.db) == {"1": None, "2": "concurrency"}

    def test_doi_cut_short_at_a_parenthesis_is_not_looked_up(self, cited_vault):
        # DOI_RE stops at `)` and fetch stores the cut value, so two Lancet 2020
        # papers (Elsevier PII DOIs) share notes.doi; the cut DOI must resolve
        # through the sources row or notes.source only, never the doi column.
        cut = "10.1016/S0140-6736(20"
        huang = "https://dx.doi.org/10.1016/S0140-6736(20)30183-5"
        zhou = "https://doi.org/10.1016/S0140-6736(20)30566-3"
        cited_vault.db.execute("UPDATE notes SET source = ?, doi = ? WHERE id = 'concurrency'", (huang, cut))
        cited_vault.db.execute("UPDATE notes SET source = ?, doi = ? WHERE id = 'rust-ownership'", (zhou, cut))
        cited_vault.db.execute(
            "INSERT INTO sources (url, note_id, domain, fetched_at, provider, content_hash) "
            "VALUES (?, 'rust-ownership', 'doi.org', '2026-01-01', 'test', 'z')", (zhou,)
        )
        cited_vault.db.commit()

        def resolve(link):
            return parse_sources_section(f"Claim [1].\n\n## Sources\n[1] A Paper. {link}\n", cited_vault.db)["1"]

        assert resolve(zhou) == "rust-ownership"  # the sources row
        assert resolve(huang) == "concurrency"  # notes.source
        absent = "https://doi.org/10.1016/S0140-6736(20)31142-9"
        variants = [
            "https://dx.doi.org/10.1016/S0140-6736(20)30566-3",
            "http://doi.org/10.1016/S0140-6736(20)30566-3",
            "https://doi.org/10.1016/S0140-6736(20)30566-3?via=x",
            absent,
        ]
        assert {v: resolve(v) for v in variants} == dict.fromkeys(variants)

    @pytest.mark.parametrize("tail", ["(20)", "(20"])
    def test_link_cut_after_a_parenthesised_group_is_not_looked_up(self, cited_vault, tail):
        # The caller strips a trailing `)` from the link, which leaves the key
        # fetch stores for every Lancet 2020 paper.
        cited_vault.db.execute(
            "UPDATE notes SET doi = '10.1016/S0140-6736(20' WHERE id = 'concurrency'"
        )
        cited_vault.db.commit()
        report = f"Claim [1].\n\n## Sources\n[1] A Paper. https://doi.org/10.1016/S0140-6736{tail}\n"
        assert parse_sources_section(report, cited_vault.db)["1"] is None

    def test_title_match_beats_a_doi_another_page_holds(self, cited_vault):
        # fetch fills notes.doi from the first DOI in a page's body when the
        # page has no DOI meta tag, so a page that only cites the paper can
        # hold its DOI.
        doi = "10.1145/3313831.3376831"
        cited_vault.db.execute("UPDATE notes SET doi = ? WHERE id = 'concurrency'", (doi,))
        cited_vault.db.commit()
        report = f"Claim [1].\n\n## Sources\n[1] Python Async Patterns. https://doi.org/{doi}\n"
        assert parse_sources_section(report, cited_vault.db)["1"] == "python-async-patterns"

    def test_doi_two_notes_hold_resolves_to_neither(self, cited_vault):
        doi = "10.1145/3313831.3376831"
        cited_vault.db.execute(
            "UPDATE notes SET doi = ? WHERE id IN ('concurrency', 'rust-ownership')", (doi,)
        )
        cited_vault.db.commit()
        report = f"Claim [1].\n\n## Sources\n[1] A Postmortem (CHI 2020). https://doi.org/{doi}\n"
        assert parse_sources_section(report, cited_vault.db)["1"] is None

    def test_sici_doi_via_dx_doi_org_is_not_looked_up(self, cited_vault):
        cited_vault.db.execute(
            "UPDATE notes SET source = ?, doi = '10.1002/(SICI' WHERE id = 'concurrency'",
            ("https://doi.org/10.1002/(SICI)1097-0258(19980415)17:7<857::AID-SIM777>3.0.CO;2-E",),
        )
        cited_vault.db.commit()
        report = (
            "Claim [1].\n\n## Sources\n"
            "[1] Another Article. https://dx.doi.org/10.1002/(SICI)1097-0258(19980430)17:8<900::AID-SIM800>3.0.CO;2-F\n"
        )
        assert parse_sources_section(report, cited_vault.db)["1"] is None

    def test_marker_without_a_sources_entry_is_dangling_not_dropped(self, cited_vault):
        report = (
            "Throughput improves 10x [1][7].\n\n"
            "## Sources\n[1] Python Async Patterns. https://example.com/async\n"
        )
        pairs = extract_pairs(report, cited_vault.db)
        assert [p["note_id"] for p in pairs] == ["python-async-patterns", None]
        assert [p.get("marker") for p in pairs] == ["[1]", "[7]"]
        assert pairs[1].get("unresolved") == "no-sources-entry"
        assert triage_pairs(pairs, cited_vault.db)["dangling"] == 1

    def test_numbering_from_zero_or_zero_padded_still_cites(self, cited_vault):
        report = (
            "First claim [01]. Second claim [0]. An id [007].\n\n"
            "## Sources\n[0] Rust Ownership. https://example.com/rust\n"
            "[01] Python Async Patterns. https://example.com/async\n"
        )
        pairs = extract_pairs(report, cited_vault.db)
        assert [(p["sentence"], p["note_id"]) for p in pairs] == [
            ("First claim [01].", "python-async-patterns"),
            ("Second claim [0].", "rust-ownership"),
        ]

    def test_unresolvable_sources_entry_is_labelled_as_such(self, cited_vault):
        report = (
            "Throughput improves 10x [1].\n\n"
            "## Sources\n[1] Unrelated Study. https://example.com/other\n"
        )
        pairs = extract_pairs(report, cited_vault.db)
        assert pairs[0]["note_id"] is None
        assert pairs[0].get("unresolved") == "unresolved-entry"

    def test_bracketed_numbers_without_a_sources_section_are_not_citations(self, cited_vault):
        report = "See item [3] in the list [[python-async-patterns]]."
        pairs = extract_pairs(report, cited_vault.db)
        assert [p["note_id"] for p in pairs] == ["python-async-patterns"]
        assert [p.get("marker") for p in pairs] == ["[[python-async-patterns]]"]

    def test_brackets_in_code_and_link_definitions_are_not_citations(self, cited_vault):
        report = (
            "Intro claim [1].\n\n"
            "```python\narr[0] = x[2]\n```\n\n"
            "Set `v[3]` before the call [1].\n\n"
            "[7]: https://example.com/seven\n\n"
            "| Item | Source |\n|---|---|\n| foo | [5] |\n\n"
            "Run `[[ -n \"$k\" ]]` first [1].\n\n"
            "Run `foo [5]\nbar` now [1].\n\n"
            "Then [12] and [0].\n\n"
            "## Sources\n[1] Python Async Patterns. https://example.com/async\n"
        )
        pairs = extract_pairs(report, cited_vault.db)
        # The stored sentence keeps its code span: the patcher edits by it.
        assert [(p["sentence"], p["note_id"]) for p in pairs] == [
            ("Intro claim [1].", "python-async-patterns"),
            ("Set `v[3]` before the call [1].", "python-async-patterns"),
            ("| foo | [5] |", None),
            ("Run `[[ -n \"$k\" ]]` first [1].", "python-async-patterns"),
            ("bar` now [1].", "python-async-patterns"),
            ("Then [12] and [0].", None),
        ]
        assert all(p["sentence"] in report for p in pairs)
        assert [p.get("marker") for p in pairs] == ["[1]", "[1]", "[5]", "[1]", "[1]", "[12]"]
        assert [p.get("unresolved") for p in pairs] == [None, None, "no-sources-entry", None, None, "no-sources-entry"]

    def test_code_span_that_shifts_the_sentence_split_keeps_markers_on_their_sentences(self, cited_vault):
        # The first span sits between a sentence end and a capital, so the
        # stripped side gains a sentence; the last holds a sentence break, so
        # the report side gains one. Equal counts, different splits.
        report = (
            "Setup. `cfg` Loads the file [1].\n\n"
            "Second paragraph has a claim [1].\n\n"
            "The log says `Error. Retry` on failure [1].\n\n"
            "## Sources\n[1] Python Async Patterns. https://example.com/async\n"
        )
        pairs = extract_pairs(report, cited_vault.db)
        assert [p["sentence"] for p in pairs] == [
            "Setup. `cfg` Loads the file [1].",
            "Second paragraph has a claim [1].",
            "Retry` on failure [1].",
        ]

    def test_code_spans_that_shift_the_split_both_ways_on_one_line(self, cited_vault):
        # One span sits between a sentence end and a capital, the other holds
        # a sentence break; each marker stays on the report sentence it is in.
        report = (
            "Run it. `make` Builds everything [1]. The tool prints `Done. Exiting` when finished [2].\n\n"
            "## Sources\n[1] Python Async Patterns. https://example.com/async\n"
            "[2] Rust Ownership. https://example.com/rust\n"
        )
        pairs = extract_pairs(report, cited_vault.db)
        assert [(p.get("marker"), p["sentence"]) for p in pairs] == [
            ("[1]", "Run it. `make` Builds everything [1]."),
            ("[2]", "Exiting` when finished [2]."),
        ]

    def test_stored_sentence_drops_indentation_and_line_endings(self, cited_vault):
        # The patcher finds a sentence by its text, so it is stored without the
        # line's indentation, trailing blanks or a CRLF's `\r`.
        report = (
            "  Indented claim [1].\r\n"
            "Trailing blanks [1].   \r\n\r\n"
            "## Sources\n[1] Python Async Patterns. https://example.com/async\n"
        )
        pairs = extract_pairs(report, cited_vault.db)
        assert [p["sentence"] for p in pairs] == ["Indented claim [1].", "Trailing blanks [1]."]

    def test_sentence_break_in_one_code_span_leaves_other_lines_stripped(self, cited_vault):
        report = (
            "Run `foo [5]\nbar` now [1].\n\n"
            "Much later `echo \"Done. Next\"` prints two words [1].\n\n"
            "## Sources\n[1] Python Async Patterns. https://example.com/async\n"
        )
        pairs = extract_pairs(report, cited_vault.db)
        assert [p["sentence"] for p in pairs] == ["bar` now [1].", "Next\"` prints two words [1]."]

    def test_triage_auto_passes_full_numeric_claim(self, cited_vault):
        pairs = extract_pairs(
            "Async improves throughput by 10x for network-bound workloads [[python-async-patterns]].",
            cited_vault.db,
        )
        triaged = triage_pairs(pairs, cited_vault.db)
        assert triaged["supported_mechanical"] == 1
        assert triaged["needs_llm"] == 0

    def test_triage_flags_unsupported_for_llm(self, cited_vault):
        pairs = extract_pairs(
            "Async cures all database contention problems entirely [[python-async-patterns]].",
            cited_vault.db,
        )
        triaged = triage_pairs(pairs, cited_vault.db)
        assert triaged["needs_llm"] == 1

    def test_numeric_overlap_does_not_certify_different_claims(self, cited_vault):
        report = "\n".join(
            [
                "Async improves throughput by 10x for network-bound workloads [[python-async-patterns]].",
                "Another team improves throughput by 10x for network-bound workloads [[python-async-patterns]].",
                "Async employs 10 engineers for network-bound workloads [[python-async-patterns]].",
                "Async improves throughput by 99x for network-bound workloads [[python-async-patterns]].",
            ]
        )
        triaged = triage_pairs(extract_pairs(report, cited_vault.db), cited_vault.db)

        assert [pair["verdict"] for pair in triaged["pairs"]] == [
            "supported-mechanical",
            "needs-llm",
            "needs-llm",
            "needs-llm",
        ]
        assert len(sample_needs_llm(triaged["pairs"], sample_rate=1.0)) == 3

    @pytest.mark.parametrize(
        ("sentence", "verdict"),
        [
            # Single-digit tokens are labels, not figures: the sentence
            # takes the word-overlap path and passes on the shared run.
            ("In step 1, async/await syntax enables concurrent I/O with a gain", "supported-mechanical"),
            ("Like GPT-4, async/await syntax enables concurrent I/O with a gain", "supported-mechanical"),
            # A 2+-digit figure makes the sentence numeric evidence, so the
            # same overlap no longer suffices without a full-claim match.
            ("In step 12, async/await syntax enables concurrent I/O with a gain", "needs-llm"),
        ],
    )
    def test_single_digit_tokens_are_not_numeric_evidence(self, cited_vault, sentence, verdict):
        pairs = extract_pairs(f"{sentence} [[python-async-patterns]].", cited_vault.db)
        triaged = triage_pairs(pairs, cited_vault.db)
        assert [p["verdict"] for p in triaged["pairs"]] == [verdict]

    def test_sampling_keeps_all_strong(self):
        pairs = [
            {"verdict": "needs-llm", "strong": True, "sentence": f"s{i}", "numbers": ["5"]}
            for i in range(5)
        ] + [
            {"verdict": "needs-llm", "strong": False, "sentence": f"w{i}", "numbers": []}
            for i in range(10)
        ]
        sampled = sample_needs_llm(pairs, sample_rate=0.5)
        strong = [p for p in sampled if p["strong"]]
        weak = [p for p in sampled if not p["strong"]]
        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

        from hyperresearch.cli import app

        init_run(cited_vault, "cc-run")
        report = cited_vault.root / "research" / "notes" / "final_report_cc-run.md"
        report.write_text(
            "Async improves throughput by 10x for network-bound workloads [[python-async-patterns]]. "
            "Also a dangling one [[ghost-note]].",
            encoding="utf-8",
        )
        monkeypatch.chdir(cited_vault.root)
        runner = CliRunner()
        r = runner.invoke(app, ["citecheck", "extract", "cc-run", "--json"])
        assert r.exit_code == 0
        data = json.loads(r.stdout)["data"]
        assert data["summary"]["supported_mechanical"] == 1
        assert data["dangling"] == 1
        assert (cited_vault.run_dir("cc-run") / "cite-check-pairs.json").exists()


class TestQuoteSpanExtraction:
    """Regression tests for quote span pairing (no min-length in the regex)."""

    def _extract_spans(self, text: str) -> list[str]:
        from hyperresearch.cli.lint import _QUOTE_SPAN_RE, _report_body_only

        body = _report_body_only(text)
        return [m.group(1) for m in _QUOTE_SPAN_RE.finditer(body)]

    def test_short_quotes_extracted_individually(self):
        text = (
            'Metrics include "TVL", "Low Security", "reasonable use", '
            '"6x Exits", and "registered entity" in the analysis.'
        )
        assert self._extract_spans(text) == [
            "TVL",
            "Low Security",
            "reasonable use",
            "6x Exits",
            "registered entity",
        ]

    def test_short_quote_before_long_quote_does_not_desync(self):
        text = (
            'The report discusses "Low Security" instruments.\n'
            'The source states "this is a sufficiently long quoted passage from the source".'
        )
        spans = self._extract_spans(text)
        assert spans == [
            "Low Security",
            "this is a sufficiently long quoted passage from the source",
        ]
        assert len(spans) == 2
        giant = "Low Security" + text.split('"Low Security"', 1)[1].split('"', 1)[0]
        assert giant not in spans[0]
        assert " instruments" not in spans[0]

    def test_curly_quotes_and_straight_quotes(self):
        text = 'Curly “quoted phrase” and straight "another phrase" here.'
        assert self._extract_spans(text) == ["quoted phrase", "another phrase"]

    def test_adjacent_quoted_phrases(self):
        text = 'Terms "TVL" "Low Security" appear back to back.'
        assert self._extract_spans(text) == ["TVL", "Low Security"]

    def test_punctuation_after_closing_quote(self):
        text = 'The label "Low Security", is used throughout.'
        assert self._extract_spans(text) == ["Low Security"]

    def test_apostrophe_inside_quote(self):
        text = 'As noted, "Python\'s async/await syntax enables concurrent I/O" today.'
        assert self._extract_spans(text) == ["Python's async/await syntax enables concurrent I/O"]

    def test_citation_markers_stripped_before_extraction(self):
        text = 'Evidence shows "Low Security" risk [[rust-ownership]].'
        assert self._extract_spans(text) == ["Low Security"]


class TestVerificationLints:
    def _lint(self, vault, rule, monkeypatch):
        from typer.testing import CliRunner

        from hyperresearch.cli import app

        monkeypatch.chdir(vault.root)
        r = CliRunner().invoke(app, ["lint", "--rule", rule, "--json"])
        return json.loads(r.stdout)

    def test_quote_integrity_catches_fabrication(self, seeded_vault, monkeypatch):
        report = seeded_vault.root / "research" / "notes" / "final_report_q.md"
        report.write_text(
            'The paper concludes that "quantum entanglement reverses causality in every measurable frame of reference".',
            encoding="utf-8",
        )
        payload = self._lint(seeded_vault, "quote-integrity", monkeypatch)
        issues = [i for i in payload["data"]["issues"] if i["rule"] == "quote-integrity"]
        assert len(issues) == 1
        assert issues[0]["severity"] == "error"

    def test_quote_integrity_passes_real_quote(self, seeded_vault, monkeypatch):
        report = seeded_vault.root / "research" / "notes" / "final_report_q.md"
        # This sentence exists verbatim in the seeded python-async-patterns note
        report.write_text(
            'As the note says, "Python\'s async/await syntax enables concurrent I/O" today.',
            encoding="utf-8",
        )
        payload = self._lint(seeded_vault, "quote-integrity", monkeypatch)
        issues = [i for i in payload["data"]["issues"] if i["rule"] == "quote-integrity"]
        assert issues == []

    def test_quote_integrity_skips_short_quotes_without_false_positive(
        self, seeded_vault, monkeypatch
    ):
        report = seeded_vault.root / "research" / "notes" / "final_report_q.md"
        report.write_text(
            'The analysis covers "TVL", "Low Security", "reasonable use", '
            '"6x Exits", and "registered entity" throughout the report body. '
            "Intervening prose that would be swallowed by a desynchronized matcher "
            "when it crosses twenty characters of unquoted text in the document.",
            encoding="utf-8",
        )
        payload = self._lint(seeded_vault, "quote-integrity", monkeypatch)
        issues = [i for i in payload["data"]["issues"] if i["rule"] == "quote-integrity"]
        assert issues == []

    def test_quote_integrity_short_quote_before_long_fabrication(
        self, seeded_vault, monkeypatch
    ):
        report = seeded_vault.root / "research" / "notes" / "final_report_q.md"
        report.write_text(
            'The report discusses "Low Security" instruments with intervening prose '
            "that must not be treated as part of a quoted span.\n"
            'The paper concludes that "quantum entanglement reverses causality in every measurable frame of reference".',
            encoding="utf-8",
        )
        payload = self._lint(seeded_vault, "quote-integrity", monkeypatch)
        issues = [i for i in payload["data"]["issues"] if i["rule"] == "quote-integrity"]
        assert len(issues) == 1
        assert "quantum entanglement" in issues[0]["message"]
        assert "Low Security" not in issues[0]["message"]

    def test_numeric_consistency_flags_untraceable(self, cited_vault, monkeypatch):
        report = cited_vault.root / "research" / "notes" / "final_report_n.md"
        report.write_text("Revenue grew 47.3% while costs fell 1,234,567 dollars.", encoding="utf-8")
        payload = self._lint(cited_vault, "numeric-consistency", monkeypatch)
        issues = [i for i in payload["data"]["issues"] if i["rule"] == "numeric-consistency"]
        assert len(issues) == 2
        assert all(i["severity"] == "warning" for i in issues)

    def test_retracted_citation_blocks_unless_marked(self, seeded_vault, monkeypatch):
        conn = seeded_vault.db
        conn.execute("UPDATE notes SET is_retracted = 1 WHERE id = 'rust-ownership'")
        conn.commit()
        report = seeded_vault.root / "research" / "notes" / "final_report_r.md"
        report.write_text("Rust guarantees safety [[rust-ownership]].", encoding="utf-8")
        payload = self._lint(seeded_vault, "retracted-citations", monkeypatch)
        issues = [i for i in payload["data"]["issues"] if i["rule"] == "retracted-citations"]
        assert len(issues) == 1 and issues[0]["severity"] == "error"

        # Acknowledged retraction passes
        report.write_text(
            "One early study claimed safety guarantees [[rust-ownership]] (retracted 2025).",
            encoding="utf-8",
        )
        payload = self._lint(seeded_vault, "retracted-citations", monkeypatch)
        issues = [i for i in payload["data"]["issues"] if i["rule"] == "retracted-citations"]
        assert issues == []


class TestIndependence:
    def test_canonical_url(self):
        assert canonical_url("https://www.Example.com/a/?utm_source=x") == canonical_url("http://example.com/a")

    def test_wire_cluster_discounts_members(self, tmp_vault):
        from hyperresearch.core.note import write_note
        from hyperresearch.core.sync import compute_sync_plan, execute_sync

        pr = "NEW YORK, PRNewswire — MegaCorp announces quantum widget breakthrough today."
        for i, (title, when) in enumerate([("MegaCorp Breakthrough", "2026-01-01"),
                                           ("MegaCorp Announces Widget", "2026-01-02"),
                                           ("Quantum Widget from MegaCorp", "2026-01-03")]):
            write_note(
                tmp_vault.notes_dir, title, body=pr + f" Outlet {i} adds a sentence.",
                source=f"https://outlet{i}.com/story", tags=["ind-run"],
                extra_frontmatter={"created": when + "T00:00:00+00:00"},
            )
        write_note(
            tmp_vault.notes_dir, "Independent Analysis",
            body="A genuinely independent, differently-worded long analysis of quantum widgets and their many limitations in practice.",
            source="https://analyst.com/deep-dive", tags=["ind-run"],
        )
        plan = compute_sync_plan(tmp_vault, force=True)
        execute_sync(tmp_vault, plan)

        result = compute_independence(tmp_vault, tag="ind-run")
        assert len(result["clusters"]) == 1
        cluster = result["clusters"][0]
        assert cluster["size"] == 3
        assert "wire" in cluster["kind"]

        scores = {r["id"]: r["independence"] for r in tmp_vault.db.execute(
            "SELECT id, independence FROM notes WHERE independence IS NOT NULL"
        )}
        assert scores[cluster["root"]] == 1.0
        assert scores["independent-analysis"] == 1.0
        for member in cluster["members"]:
            assert scores[member] == pytest.approx(1 / 3, abs=0.001)

    def test_same_canonical_url_clusters(self, tmp_vault):
        from hyperresearch.core.note import write_note
        from hyperresearch.core.sync import compute_sync_plan, execute_sync

        write_note(tmp_vault.notes_dir, "Copy A", body="Some words here for the body.",
                   source="https://www.site.com/story?utm_source=feed")
        write_note(tmp_vault.notes_dir, "Copy B", body="Entirely different words in this body text.",
                   source="https://site.com/story/")
        plan = compute_sync_plan(tmp_vault, force=True)
        execute_sync(tmp_vault, plan)
        result = compute_independence(tmp_vault)
        assert any(c["kind"] == "url" for c in result["clusters"])


class TestCJKLengthCheck:
    """`str.split()` word counts collapse to near-zero for prose in scripts
    that don't delimit words with ASCII whitespace (Chinese, Japanese,
    Korean, Thai, ...), so a report that is squarely within its documented
    character-count target must not fail length-in-range on a spurious
    word count. The detector is a structural heuristic (average
    whitespace-delimited token length), not a hardcoded script allowlist --
    it must generalize to any such script without code changes."""

    def test_lacks_word_boundaries(self):
        from hyperresearch.core.runs import _lacks_word_boundaries

        # Japanese (kana + kanji) and Chinese (hanzi) prose is written with
        # no spaces between words at all.
        assert _lacks_word_boundaries("この文章はほぼ全て日本語の文字で構成されています。")
        assert _lacks_word_boundaries("这是一段中文测试文本内容和证据。")
        # Structural-only proof of generality to a non-CJK, non-Latin
        # script family (Thai) -- no claim about grammaticality, just that
        # a long run of a spaceless script's characters trips the same
        # heuristic without any script-specific code.
        assert _lacks_word_boundaries("คำ" * 30)
        # Korean is the counter-example that justifies a *structural*
        # heuristic over a hardcoded script list: unlike Chinese/Japanese,
        # modern Korean orthography IS space-delimited, so str.split()
        # word counts are meaningful for it and it must NOT trip this
        # branch. A script-identity allowlist would get this wrong.
        assert not _lacks_word_boundaries(
            "이것은 한국어 문장으로 구성된 테스트입니다 그리고 띄어쓰기를 사용합니다."
        )
        assert not _lacks_word_boundaries(
            "This paragraph is entirely English prose with no CJK content at all."
        )
        # A handful of long wikilink citation keys inside a mostly-English
        # report should not trip the branch -- many short real words still
        # dominate the average token length.
        assert not _lacks_word_boundaries(
            "This is an English report with real citations. "
            "[[dagitty-a-graphical-tool-for-analyzing-causal-diagrams-semantic-scholar]] " * 15
        )

    def test_verify_passes_cjk_report_within_char_target_despite_low_word_count(
        self, tmp_vault
    ):
        init_run(tmp_vault, "cjk-01", profile="light")
        run_dir = tmp_vault.run_dir("cjk-01")
        (run_dir / "prompt-decomposition.json").write_text(json.dumps({
            "response_format": "short",
            "required_section_headings": ["## 結果"],
        }), encoding="utf-8")
        (run_dir / "polish-log.json").write_text('{"applied": []}', encoding="utf-8")
        # light/short CJK char target is 1500-6000; this Japanese sentence
        # has almost no ASCII whitespace, so str.split() would count only a
        # handful of "words" despite being solidly in-range by characters.
        sentence = "これは実質的な証拠を伴う文章である[[src-note]]。"
        report = tmp_vault.root / "research" / "notes" / "final_report_cjk-01.md"
        body = "## 結果\n\n" + (sentence * 90)
        report.write_text(body, encoding="utf-8")

        word_count = len(body.split())
        assert word_count < 500  # would fail the English word-count target

        result = verify_run(tmp_vault, "cjk-01")
        by_name = {c["name"]: c for c in result["checks"]}
        assert by_name["length-in-range"]["ok"] is True
        assert "chars" in by_name["length-in-range"]["detail"]
        assert result["passed"] is True

    def test_verify_still_fails_cjk_report_far_outside_char_target(self, tmp_vault):
        init_run(tmp_vault, "cjk-02", profile="light")
        run_dir = tmp_vault.run_dir("cjk-02")
        (run_dir / "prompt-decomposition.json").write_text(json.dumps({
            "response_format": "short",
            "required_section_headings": ["## 結果"],
        }), encoding="utf-8")
        # Well under the 1500-char floor (even with the 20% tolerance) --
        # the CJK branch must still be a real length check, not a bypass.
        report = tmp_vault.root / "research" / "notes" / "final_report_cjk-02.md"
        report.write_text("## 結果\n\n短い。", encoding="utf-8")

        result = verify_run(tmp_vault, "cjk-02")
        by_name = {c["name"]: c for c in result["checks"]}
        assert by_name["length-in-range"]["ok"] is False
        assert result["passed"] is False

    def test_verify_respects_profile_override_for_non_cjk_script(self, tmp_vault):
        """End-to-end proof that a deployment serving a non-CJK,
        non-word-boundary script (simulated here with a spaceless Thai-script
        blob) is not stuck with CJK-calibrated numbers: it configures its own
        char_targets_no_word_boundary via the standard profile-overlay
        mechanism, and verify_run honors it -- no code change needed to
        support a script this project has no real usage data for."""
        cfg_dir = tmp_vault.root / ".hyperresearch"
        cfg_dir.mkdir(parents=True, exist_ok=True)
        (cfg_dir / "config.toml").write_text(
            "[profile.light]\n"
            "char_targets_no_word_boundary = { short = [300, 900] }\n",
            encoding="utf-8",
        )
        init_run(tmp_vault, "th-01", profile="light")
        run_dir = tmp_vault.run_dir("th-01")
        (run_dir / "prompt-decomposition.json").write_text(json.dumps({
            "response_format": "short",
            "required_section_headings": ["## Results"],
        }), encoding="utf-8")
        (run_dir / "polish-log.json").write_text('{"applied": []}', encoding="utf-8")
        # A spaceless Thai-script blob: within the overridden 300-900 char
        # target, but far below the shipped CJK default's 1500-char floor --
        # this only passes if the override is actually being read.
        report = tmp_vault.root / "research" / "notes" / "final_report_th-01.md"
        report.write_text("## Results\n\n" + ("คำ" * 250), encoding="utf-8")

        result = verify_run(tmp_vault, "th-01")
        by_name = {c["name"]: c for c in result["checks"]}
        assert by_name["length-in-range"]["ok"] is True
        assert "300-900" in by_name["length-in-range"]["detail"]


class TestClassifiedTierArtifacts:
    """The router lets step 1 reclassify a run's tier after `run init`:
    "the manifest's profile field is informational — the decomposition's
    tier rules". The ship gate has to read the same rule, or a
    light-classified run started on the installed gear is asked for critic
    findings that light tier never produces."""

    def _light_classified_gear_run(self, tmp_vault, tag: str, tier: str | None):
        init_run(tmp_vault, tag, profile="full")
        run_dir = tmp_vault.run_dir(tag)
        decomp = {
            "response_format": "short",
            "required_section_headings": ["## Findings"],
        }
        if tier is not None:
            decomp["pipeline_tier"] = tier
        (run_dir / "prompt-decomposition.json").write_text(
            json.dumps(decomp), encoding="utf-8"
        )
        (run_dir / "polish-log.json").write_text('{"applied": []}', encoding="utf-8")
        report = tmp_vault.root / "research" / "notes" / f"final_report_{tag}.md"
        report.write_text(
            "## Findings\n\n"
            + ("Substantive sentence with real evidence attached [[src-note]]. " * 80),
            encoding="utf-8",
        )
        return run_dir

    def test_light_classified_gear_run_passes_without_critic_artifacts(self, tmp_vault):
        self._light_classified_gear_run(tmp_vault, "tier-01", "light")

        result = verify_run(tmp_vault, "tier-01")
        names = {c["name"] for c in result["checks"]}
        assert not [n for n in names if n.startswith("artifact:critic-findings")]
        assert "artifact:patch-log.json" not in names
        assert "artifact:polish-log.json" in names
        assert result["passed"] is True

    def test_gear_run_without_declared_tier_still_needs_critic_artifacts(self, tmp_vault):
        self._light_classified_gear_run(tmp_vault, "tier-02", None)

        result = verify_run(tmp_vault, "tier-02")
        by_name = {c["name"]: c for c in result["checks"]}
        assert by_name["artifact:critic-findings-dialectic.json"]["ok"] is False
        assert result["passed"] is False

    def test_unknown_declared_tier_falls_back_to_manifest_profile(self, tmp_vault):
        self._light_classified_gear_run(tmp_vault, "tier-03", "bogus")

        result = verify_run(tmp_vault, "tier-03")
        by_name = {c["name"]: c for c in result["checks"]}
        assert by_name["artifact:critic-findings-dialectic.json"]["ok"] is False
        assert result["passed"] is False


class TestTelemetryAndVerify:
    def test_run_report_rollup(self, tmp_vault):
        init_run(tmp_vault, "tel-01", profile="light")
        set_step(tmp_vault, "tel-01", "1", "running")
        set_step(tmp_vault, "tel-01", "1", "done")
        report = run_report_data(tmp_vault, "tel-01")
        step1 = next(s for s in report["steps"] if s["step"] == "1")
        assert step1["status"] == "done"
        assert step1["minutes"] is not None
        assert report["events"]["step"] >= 2

    def test_verify_passes_well_formed_light_run(self, tmp_vault):
        init_run(tmp_vault, "vf-01", profile="light")
        run_dir = tmp_vault.run_dir("vf-01")
        (run_dir / "prompt-decomposition.json").write_text(json.dumps({
            "response_format": "short",
            "required_section_headings": ["## Findings"],
        }), encoding="utf-8")
        (run_dir / "polish-log.json").write_text('{"applied": []}', encoding="utf-8")
        report = tmp_vault.root / "research" / "notes" / "final_report_vf-01.md"
        body = "## Findings\n\n" + ("Substantive sentence with real evidence attached [[src-note]]. " * 80)
        report.write_text(body, encoding="utf-8")

        result = verify_run(tmp_vault, "vf-01")
        by_name = {c["name"]: c for c in result["checks"]}
        assert by_name["report-exists"]["ok"]
        assert by_name["required-headings"]["ok"]
        assert by_name["length-in-range"]["ok"]
        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. " * 14
        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 133 words (~7.5/1000) sits under the 9/1000 floor;
        # the three sources inside each grouped bracket clear it (~22/1000).
        # Counting markers instead of cited-source numbers would fail this.
        assert by_name["citation-density"]["ok"]
        assert "citations/1000 words" in by_name["citation-density"]["detail"]

    @staticmethod
    def _density_check(tmp_vault, tag: str, body: str, heading: str = "## Findings") -> dict:
        init_run(tmp_vault, tag, profile="light")
        run_dir = tmp_vault.run_dir(tag)
        (run_dir / "prompt-decomposition.json").write_text(json.dumps({
            "response_format": "short",
            "required_section_headings": [heading],
        }), encoding="utf-8")
        report = tmp_vault.root / "research" / "notes" / f"final_report_{tag}.md"
        report.write_text(body, encoding="utf-8")
        result = verify_run(tmp_vault, tag)
        return {c["name"]: c for c in result["checks"]}["citation-density"]

    def test_density_english_boundary_is_nine_per_thousand_words(self, tmp_vault):
        """The floor is 9 cited-source references per 1000 words — the old
        1.5-per-1000-characters floor expressed in words for English prose
        (~6 characters per word incl. the space), so English verdicts don't
        move (#76). Exactly 9 in 1000 words passes; 8 fails."""
        cited = "Replicated measurements support the committed position here [1]. "
        plain = "Replicated measurements support the committed position here too. "

        def report(n_cited: int) -> str:
            # n_cited cited sentences, then plain prose, padded with single
            # tokens to exactly 1000 whitespace-delimited words.
            body = "## Findings\n\n" + cited * n_cited
            while len((body + plain).split()) <= 1000:
                body += plain
            body += "pad " * (1000 - len(body.split()))
            assert len(body.split()) == 1000, len(body.split())
            return body

        ok = self._density_check(tmp_vault, "den-en-1", report(9))
        assert ok["ok"] is True, ok
        assert ok["detail"].startswith("9.00 citations/1000 words (floor 9.0)")
        fail = self._density_check(tmp_vault, "den-en-2", report(8))
        assert fail["ok"] is False, fail

    def test_density_cjk_clears_the_same_floor_per_unit_of_content(self, tmp_vault):
        """A Japanese report has no ASCII word boundaries, so the denominator
        is characters / chars_per_word_no_word_boundary (3): one citation
        per ~50 characters is ~60 per 1000 effective words and passes; one
        per ~600 characters (~5 per 1000 words) fails — even though the
        old per-character floor (1.67 per 1000 chars) would have passed it.
        The floor now means the same amount of content in every script."""
        dense = "この文章は再現された測定結果に基づく実質的な証拠を示している[1]。"  # ~34 chars, 1 cite
        assert 30 <= len(dense) <= 40
        body = "## 結果\n\n" + dense * 60
        ok = self._density_check(tmp_vault, "den-ja-1", body, heading="## 結果")
        assert ok["ok"] is True, ok
        assert "no word boundaries" in ok["detail"]

        sparse_filler = "この文章は再現された測定結果に基づく実質的な証拠を示している。"  # ~31 chars
        sparse = sparse_filler * 18 + "この文章は再現された測定結果に基づく実質的な証拠を示している[1]。"
        assert 560 <= len(sparse) <= 640
        from hyperresearch.core.runs import _lacks_word_boundaries

        assert _lacks_word_boundaries(sparse)
        body = "## 結果\n\n" + sparse * 4
        old_chars_density = 4 / len(body) * 1000
        assert old_chars_density >= 1.5  # would have cleared the old gate
        fail = self._density_check(tmp_vault, "den-ja-2", body, heading="## 結果")
        assert fail["ok"] is False, fail

    def test_density_korean_takes_the_word_path(self, tmp_vault):
        """Korean is space-delimited, so it is counted by words like English
        — the detail names plain words, not the chars/ratio denominator."""
        sentence = "이 문장은 반복된 측정에서 확인된 실질적인 근거를 제시한다 [1]. "  # 9 tokens, 1 cite
        body = "## 결과\n\n" + sentence * 60
        from hyperresearch.core.runs import _lacks_word_boundaries

        assert not _lacks_word_boundaries(body)
        res = self._density_check(tmp_vault, "den-ko-1", body, heading="## 결과")
        assert res["ok"] is True, res
        assert "citations/1000 words (floor" in res["detail"]
        assert "no word boundaries" not in res["detail"]

    def test_density_counts_wikilinks_with_the_shared_pattern(self, tmp_vault):
        """[[...]] citations are counted with core.patterns.WIKI_LINK_RE, not
        a private regex, so this gate agrees with lint and cite-check about
        what a wiki-link citation is."""
        from hyperresearch.core.patterns import WIKI_LINK_RE

        plain = "Replicated measurements support the committed position here too. "
        body = "## Findings\n\n" + (
            "Evidence sits in the vault [[src-note-alpha]] and [[src-note-beta|Beta]]. "
            + plain * 3
        ) * 20
        expected = len(WIKI_LINK_RE.findall(body))
        assert expected == 40
        res = self._density_check(tmp_vault, "den-wl-1", body)
        words = len(body.split())
        assert res["detail"].startswith(f"{expected * 1000 / words:.2f} citations/1000 words")

    def test_verify_density_floor_comes_from_profile(self, tmp_vault):
        """`citation_density_min` used to be dead config (declared, never
        read) while the gate hardcoded its own floor (#101). A profile
        overlay must now move the gate."""
        cfg = tmp_vault.root / ".hyperresearch" / "config.toml"
        cfg.parent.mkdir(parents=True, exist_ok=True)
        cfg.write_text("[profile.light]\ncitation_density_min = 10000\n", encoding="utf-8")
        init_run(tmp_vault, "vf-05", profile="light")
        run_dir = tmp_vault.run_dir("vf-05")
        (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-05.md"
        body = "## Findings\n\n" + ("Substantive sentence with real evidence attached [[src-note]]. " * 80)
        report.write_text(body, encoding="utf-8")

        result = verify_run(tmp_vault, "vf-05")
        by_name = {c["name"]: c for c in result["checks"]}
        assert by_name["citation-density"]["ok"] is False
        assert "floor 10000" in by_name["citation-density"]["detail"]

    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")
        assert result["passed"] is False

    def test_verify_cli_exit_code(self, tmp_vault, monkeypatch):
        from typer.testing import CliRunner

        from hyperresearch.cli import app

        init_run(tmp_vault, "vf-03", profile="light")
        monkeypatch.chdir(tmp_vault.root)
        r = CliRunner().invoke(app, ["run", "verify", "vf-03", "--json"])
        assert r.exit_code == 1  # no report -> fail


class TestFinishGate:
    """`run finish` is the terminal gate: it must be impossible to reach
    status "done" past a failing check, and the two Q62 failure modes
    (hallucinated quotes assessed away, length gate never run) must now be
    mechanically blocking."""

    def _well_formed_light_run(self, tmp_vault, tag: str, body: str | None = None):
        init_run(tmp_vault, tag, profile="light")
        run_dir = tmp_vault.run_dir(tag)
        (run_dir / "prompt-decomposition.json").write_text(json.dumps({
            "response_format": "short",
            "required_section_headings": ["## Findings"],
        }), encoding="utf-8")
        (run_dir / "polish-log.json").write_text('{"applied": []}', encoding="utf-8")
        report = tmp_vault.root / "research" / "notes" / f"final_report_{tag}.md"
        if body is None:
            body = "## Findings\n\n" + (
                "Substantive sentence with real evidence attached [[src-note]]. " * 80
            )
        report.write_text(body, encoding="utf-8")
        return report

    def test_finish_marks_clean_run_done(self, tmp_vault):
        from hyperresearch.core.runs import finish_run, load_manifest

        self._well_formed_light_run(tmp_vault, "fin-01")
        result = finish_run(tmp_vault, "fin-01")
        assert result["verify"]["passed"] is True
        manifest = load_manifest(tmp_vault, "fin-01")
        assert manifest["status"] == "done"
        assert manifest["blocked_on"] is None
        assert manifest["verify"]["passed"] is True
        assert manifest["verify"]["failed_checks"] == []

    def test_finish_blocks_hallucinated_quote(self, tmp_vault):
        from hyperresearch.core.runs import finish_run, load_manifest

        body = "## Findings\n\n" + (
            "Substantive sentence with real evidence attached [[src-note]]. " * 80
        ) + '\n\nAs one expert put it, "this quotation was never fetched into any vault note anywhere."\n'
        self._well_formed_light_run(tmp_vault, "fin-02", body=body)
        result = finish_run(tmp_vault, "fin-02")
        assert result["verify"]["passed"] is False
        by_name = {c["name"]: c for c in result["verify"]["checks"]}
        assert by_name["quote-integrity"]["ok"] is False
        manifest = load_manifest(tmp_vault, "fin-02")
        assert manifest["status"] == "blocked"
        assert manifest["blocked_on"] == "verify"
        assert "quote-integrity" in manifest["verify"]["failed_checks"]

    def test_finish_blocks_over_length_report(self, tmp_vault):
        from hyperresearch.core.runs import finish_run, load_manifest

        # light/short target is 500-2000 words; 20% tolerance caps at 2400.
        body = "## Findings\n\n" + (
            "Substantive sentence with real evidence attached [[src-note]]. " * 500
        )
        self._well_formed_light_run(tmp_vault, "fin-03", body=body)
        result = finish_run(tmp_vault, "fin-03")
        assert result["verify"]["passed"] is False
        by_name = {c["name"]: c for c in result["verify"]["checks"]}
        assert by_name["length-in-range"]["ok"] is False
        manifest = load_manifest(tmp_vault, "fin-03")
        assert manifest["status"] == "blocked"
        assert manifest["blocked_on"] == "verify"

    def test_finish_then_fix_then_done(self, tmp_vault):
        """The intended loop: blocked -> fix the report -> finish passes."""
        from hyperresearch.core.runs import finish_run, load_manifest

        body = "## Findings\n\n" + (
            "Substantive sentence with real evidence attached [[src-note]]. " * 80
        ) + '\n\nAs one expert put it, "this quotation was never fetched into any vault note anywhere."\n'
        report = self._well_formed_light_run(tmp_vault, "fin-04", body=body)
        assert finish_run(tmp_vault, "fin-04")["verify"]["passed"] is False

        # The prescribed fix: drop the quotation marks, not the gate.
        fixed = report.read_text(encoding="utf-8").replace(
            '"this quotation was never fetched into any vault note anywhere."',
            "this claim stands as the report's own framing.",
        )
        report.write_text(fixed, encoding="utf-8")
        assert finish_run(tmp_vault, "fin-04")["verify"]["passed"] is True
        assert load_manifest(tmp_vault, "fin-04")["status"] == "done"

    def test_finish_cli_exit_code(self, tmp_vault, monkeypatch):
        from typer.testing import CliRunner

        from hyperresearch.cli import app

        init_run(tmp_vault, "fin-05", profile="light")
        monkeypatch.chdir(tmp_vault.root)
        r = CliRunner().invoke(app, ["run", "finish", "fin-05", "--json"])
        assert r.exit_code == 1  # no report -> gate fails -> blocked
        from hyperresearch.core.runs import load_manifest

        assert load_manifest(tmp_vault, "fin-05")["status"] == "blocked"

    def test_verify_includes_content_gates(self, tmp_vault):
        """verify_run itself must carry quote-integrity + retracted-citations
        checks — one command, whole verdict."""
        self._well_formed_light_run(tmp_vault, "fin-06")
        result = verify_run(tmp_vault, "fin-06")
        names = {c["name"] for c in result["checks"]}
        assert "quote-integrity" in names
        assert "retracted-citations" in names

    def test_cite_check_findings_accepts_both_shapes(self, tmp_vault):
        """The pipeline writes {"findings": [...]}; verify must not crash on
        it (it did, on the first live gate run) and must still resolve
        criticals for the bare-list shape."""
        from hyperresearch.core.runs import set_step

        for tag, payload in (
            ("fin-07", {"findings": [{"severity": "critical", "verdict": "unsupported"}]}),
            ("fin-08", [{"severity": "critical", "verdict": "unsupported"}]),
        ):
            self._well_formed_light_run(tmp_vault, tag)
            run_dir = tmp_vault.run_dir(tag)
            set_step(tmp_vault, tag, "14.5", "done")
            (run_dir / "cite-check-findings.json").write_text(
                json.dumps(payload), encoding="utf-8"
            )
            result = verify_run(tmp_vault, tag)  # must not raise
            by_name = {c["name"]: c for c in result["checks"]}
            # A critical finding with no patch log fails the check cleanly.
            assert by_name["cite-check-resolved"]["ok"] is False
            (run_dir / "cite-check-patch-log.json").write_text("[]", encoding="utf-8")
            result = verify_run(tmp_vault, tag)
            by_name = {c["name"]: c for c in result["checks"]}
            assert by_name["cite-check-resolved"]["ok"] is True


class TestCiteCheckerAgentInstall:
    def test_agent_installs(self, tmp_vault):
        from hyperresearch.core.hooks import _install_cite_checker_agent

        result = _install_cite_checker_agent(tmp_vault.root, "hyperresearch")
        assert result is not None
        body = (tmp_vault.root / ".claude" / "agents" / "hyperresearch-cite-checker.md").read_text(encoding="utf-8")
        assert "name: hyperresearch-cite-checker" in body
        assert "model: sonnet" in body
        assert "wrong-source" in body
        assert "SKEPTICAL" in body
        assert "{hpr_path}" not in body
        assert "<<" not in body