gather-engine 2.2.0__tar.gz → 2.3.0__tar.gz

{gather_engine-2.2.0/src/gather_engine.egg-info → gather_engine-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gather-engine
-Version: 2.2.0
+Version: 2.3.0
 Summary: Accountable research intake for difficult sources, with provenance receipts and witnessed digests.
 Author: Zain Dana Harper
 License-Expression: LicenseRef-FSL-1.1-MIT
@@ -34,7 +34,7 @@ Dynamic: license-file
 [![downloads](https://img.shields.io/pypi/dm/gather-engine?label=downloads&style=flat-square&labelColor=14041b)](https://pypi.org/project/gather-engine/)
 ![python: 3.11+](https://img.shields.io/badge/python-3.11%2B-blue?style=flat-square&labelColor=14041b)
 ![deps: none (core)](https://img.shields.io/badge/core%20deps-none-success?style=flat-square&labelColor=14041b)
-![version: 2.2.0](https://img.shields.io/badge/version-2.2.0-26dfe8?style=flat-square&labelColor=14041b)
+![version: 2.3.0](https://img.shields.io/badge/version-2.3.0-26dfe8?style=flat-square&labelColor=14041b)
 
 gather pulls research out of the places most tools break on: arXiv papers, authenticated JSON APIs, JavaScript-rendered pages via a real headless browser, scanned images through OCR, and audio through transcription, alongside video, web, feeds, and local docs. The core runs with zero third-party runtime dependencies, and the same engine is reachable from the CLI, MCP tools, and plain Python. Every run writes a receipt you can re-check.
 
@@ -42,7 +42,7 @@ gather pulls research out of the places most tools break on: arXiv papers, authe
 
 ## Current status
 
-`gather-engine 2.2.0` is the current source version. Core intake,
+`gather-engine 2.3.0` is the current source version. Core intake,
 content-addressed corpus storage, exact UTF-8 source-byte receipts, readable
 context selection, descriptor handoff, pilot monitoring, CLI, Python API, and MCP
 surfaces are present in this checkout. Browser rendering, OCR, audio, and fast
@@ -83,7 +83,7 @@ fabricated field cannot reach the corpus by being plausible.
 - **Structured extraction with a hallucination check.** `gather.schema_extract` binds schema fields to source nodes, and `verify_record` rejects any LLM-proposed field value not grounded in the fetched content.
 - **Streaming extraction.** `gather.stream` parses an HTML stream chunk by chunk and emits partial-update commits as blocks complete, each folded into a hash chain, so a streamed extraction is replayable.
 - **Hard-source adapters behind one shape.** Video with captions and comments (`yt-dlp` first, with the official YouTube Data API as a fallback when you supply your own key; each item records which path served it and how fast), Reddit through its official Data API with your own app credentials, static web, RSS/Atom feeds, local docs, arXiv, PDFs (`pdftotext`), authenticated JSON APIs (token from env, never logged), JS-rendered pages (headless Chromium), scanned images (`tesseract`), and audio (`whisper`). Each external tool is optional and only needed for its own adapter.
-- **Cited reports, checked in code.** `gather report` asks a model on your own machine to answer from fixed excerpts with exact quotes, then checks every quote against the excerpt it cites and marks any it cannot verify.
+- **Cited reports, checked in code.** `gather report` asks a model on your own machine to answer from fixed excerpts with exact quotes, then checks every quote against the excerpt it cites and marks any it cannot verify. An answer that cites an excerpt without quoting it is sent back for a rewrite, up to twice.
 - **Filter ledgers.** `--scope TERMS --ledger DIR` writes one row per dropped item with its reason code, plus the input, so `gather ledger verify` can recompute every count.
 - **Channel and playlist intake.** `gather channel <url> --store DIR` lists a channel's videos, shorts, and streams tabs (or one playlist) and gathers every entry with bounded concurrency, resumable from a per-pass ledger. Metadata and comments run as one pass and captions as another (`--no-captions`, `--captions-only`), with polite pacing, bounded backoff on HTTP 429 and session rate limits, a stop at the first bot check (never retried or answered), one caption track per video, and a run summary that counts every outcome by reason.
 - **Scholarly-graph federation.** `gather scholar` queries OpenAlex, Semantic Scholar, and Crossref in one call, dedupes results by normalized DOI (never a fuzzy title match), and can capture citation edges as first-class records with `--edges`.

{gather_engine-2.2.0 → gather_engine-2.3.0}/README.md

@@ -8,7 +8,7 @@
 [![downloads](https://img.shields.io/pypi/dm/gather-engine?label=downloads&style=flat-square&labelColor=14041b)](https://pypi.org/project/gather-engine/)
 ![python: 3.11+](https://img.shields.io/badge/python-3.11%2B-blue?style=flat-square&labelColor=14041b)
 ![deps: none (core)](https://img.shields.io/badge/core%20deps-none-success?style=flat-square&labelColor=14041b)
-![version: 2.2.0](https://img.shields.io/badge/version-2.2.0-26dfe8?style=flat-square&labelColor=14041b)
+![version: 2.3.0](https://img.shields.io/badge/version-2.3.0-26dfe8?style=flat-square&labelColor=14041b)
 
 gather pulls research out of the places most tools break on: arXiv papers, authenticated JSON APIs, JavaScript-rendered pages via a real headless browser, scanned images through OCR, and audio through transcription, alongside video, web, feeds, and local docs. The core runs with zero third-party runtime dependencies, and the same engine is reachable from the CLI, MCP tools, and plain Python. Every run writes a receipt you can re-check.
 
@@ -16,7 +16,7 @@ gather pulls research out of the places most tools break on: arXiv papers, authe
 
 ## Current status
 
-`gather-engine 2.2.0` is the current source version. Core intake,
+`gather-engine 2.3.0` is the current source version. Core intake,
 content-addressed corpus storage, exact UTF-8 source-byte receipts, readable
 context selection, descriptor handoff, pilot monitoring, CLI, Python API, and MCP
 surfaces are present in this checkout. Browser rendering, OCR, audio, and fast
@@ -57,7 +57,7 @@ fabricated field cannot reach the corpus by being plausible.
 - **Structured extraction with a hallucination check.** `gather.schema_extract` binds schema fields to source nodes, and `verify_record` rejects any LLM-proposed field value not grounded in the fetched content.
 - **Streaming extraction.** `gather.stream` parses an HTML stream chunk by chunk and emits partial-update commits as blocks complete, each folded into a hash chain, so a streamed extraction is replayable.
 - **Hard-source adapters behind one shape.** Video with captions and comments (`yt-dlp` first, with the official YouTube Data API as a fallback when you supply your own key; each item records which path served it and how fast), Reddit through its official Data API with your own app credentials, static web, RSS/Atom feeds, local docs, arXiv, PDFs (`pdftotext`), authenticated JSON APIs (token from env, never logged), JS-rendered pages (headless Chromium), scanned images (`tesseract`), and audio (`whisper`). Each external tool is optional and only needed for its own adapter.
-- **Cited reports, checked in code.** `gather report` asks a model on your own machine to answer from fixed excerpts with exact quotes, then checks every quote against the excerpt it cites and marks any it cannot verify.
+- **Cited reports, checked in code.** `gather report` asks a model on your own machine to answer from fixed excerpts with exact quotes, then checks every quote against the excerpt it cites and marks any it cannot verify. An answer that cites an excerpt without quoting it is sent back for a rewrite, up to twice.
 - **Filter ledgers.** `--scope TERMS --ledger DIR` writes one row per dropped item with its reason code, plus the input, so `gather ledger verify` can recompute every count.
 - **Channel and playlist intake.** `gather channel <url> --store DIR` lists a channel's videos, shorts, and streams tabs (or one playlist) and gathers every entry with bounded concurrency, resumable from a per-pass ledger. Metadata and comments run as one pass and captions as another (`--no-captions`, `--captions-only`), with polite pacing, bounded backoff on HTTP 429 and session rate limits, a stop at the first bot check (never retried or answered), one caption track per video, and a run summary that counts every outcome by reason.
 - **Scholarly-graph federation.** `gather scholar` queries OpenAlex, Semantic Scholar, and Crossref in one call, dedupes results by normalized DOI (never a fuzzy title match), and can capture citation edges as first-class records with `--edges`.

{gather_engine-2.2.0 → gather_engine-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gather-engine"
-version = "2.2.0"
+version = "2.3.0"
 description = "Accountable research intake for difficult sources, with provenance receipts and witnessed digests."
 readme = "README.md"
 requires-python = ">=3.11"

{gather_engine-2.2.0 → gather_engine-2.3.0}/src/gather/__init__.py

@@ -28,7 +28,7 @@ from gather.scope import filter_scope, in_scope
 from gather.source import Catalog, Source
 from gather.store import Corpus
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 
 __all__ = [
     "Catalog", "Corpus", "CorpusRootDescriptor", "CorpusRootIdentity", "Digest", "Item", "NullProvenanceProvider", "NullSynthesizer",

{gather_engine-2.2.0 → gather_engine-2.3.0}/src/gather/report.py

@@ -6,6 +6,12 @@ the answer. The report becomes one Item with ``method="synthesized"``, ``derived
 the excerpts' content hashes, and the full check result in ``meta["citation_check"]``. An
 unverifiable citation is marked in that result, never removed from the text.
 
+Every citation must quote its excerpt. When an answer carries a bracketed number with no quote
+before it (status ``unchecked``), ``write_report`` asks again, naming the sentences at fault, up to
+``quote_retries`` times (default ``QUOTE_RETRIES``). It keeps the first answer with no unquoted
+citation, or else the last answer unchanged, with ``meta["quote_requirement"]`` set to ``"unmet"``.
+Each model call is recorded in ``meta["attempts"]``.
+
 The model is a ``LocalModel``: loopback endpoints only, so only a model the user runs on their own
 machine writes the report. The method follows the one-pass local report writers described for
 AstaBrief; Gather ships no AstaBrief weights, data or outputs.
@@ -17,22 +23,25 @@ import json
 import time
 from collections.abc import Callable, Sequence
 
-from gather.citecheck import check_report
+from gather.citecheck import check_report, sentences
 from gather.item import Item, content_hash, make_item
 from gather.local_model import LocalModel
 
 REPORT_SCHEMA = "gather.report/1"
 MAX_EXCERPT_CHARS = 4000
+QUOTE_RETRIES = 2
 
 SYSTEM = (
     "You write short research answers from numbered excerpts and nothing else. Rules: "
     "1. Every sentence that states a fact must contain an exact quotation copied word for word from "
     "one excerpt, in double quotes, followed by that excerpt's number in square brackets, like this: "
     '"exact words from the excerpt" [2]. '
-    "2. Quote at least four consecutive words. Do not change, shorten or join the quoted words. "
-    "3. Cite only the numbered excerpts. Use no outside knowledge. "
-    "4. If the excerpts do not answer the question, write: The excerpts do not answer this question. "
-    "5. Write at most five sentences, in plain prose, with no headings."
+    "2. Every bracketed excerpt number must come directly after the double-quoted words it supports. "
+    "A bracketed number with no quotation right before it is not allowed. "
+    "3. Quote at least four consecutive words. Do not change, shorten or join the quoted words. "
+    "4. Cite only the numbered excerpts. Use no outside knowledge. "
+    "5. If the excerpts do not answer the question, write: The excerpts do not answer this question. "
+    "6. Write at most five sentences, in plain prose, with no headings."
 )
 
 
@@ -41,19 +50,56 @@ def excerpts_block(excerpts: Sequence[Item], max_chars: int = MAX_EXCERPT_CHARS)
                        for n, it in enumerate(excerpts, 1))
 
 
+def unquoted_sentences(text: str, check: dict) -> list[str]:
+    """The sentences of ``text`` holding a citation with no quote (status ``unchecked``)."""
+    found = sorted({c["sentence"] for c in check["citations"] if c["status"] == "unchecked"})
+    split = sentences(text)
+    return [split[n] for n in found]
+
+
+def retry_prompt(user: str, previous: str, faulty: Sequence[str]) -> str:
+    """The user message for a regeneration: the original request, the previous answer, and the
+    sentences whose citations had no quote."""
+    listed = "\n".join(f"- {s}" for s in faulty)
+    return (f"{user}\n\nYour previous answer:\n{previous}\n\n"
+            f"These sentences cite an excerpt number with no quotation before it:\n{listed}\n\n"
+            "Rewrite the whole answer. Every citation must quote its excerpt: put the exact words, copied "
+            'word for word, in double quotes directly before the excerpt number, like "exact words" [2].')
+
+
+def _ask_until_quoted(model: LocalModel, user: str, texts: list[str], retries: int):
+    """Call the model until an answer has no unquoted citation or the retries run out."""
+    attempts: list[dict] = []
+    prompt = user
+    for _ in range(retries + 1):
+        reply = model.chat(SYSTEM, prompt)
+        check = check_report(reply.text, texts)
+        faulty = unquoted_sentences(reply.text, check)
+        attempts.append({"elapsed_s": round(reply.elapsed_s, 3), "unchecked": check["counts"]["unchecked"]})
+        if not faulty:
+            break
+        prompt = retry_prompt(user, reply.text, faulty)
+    return reply, check, attempts
+
+
 def write_report(question: str, excerpts: Sequence[Item], model: LocalModel, *,
-                 wall: Callable[[], float] = time.time) -> Item:
-    """Ask the local model, check its citations, and return the report Item."""
+                 quote_retries: int = QUOTE_RETRIES, wall: Callable[[], float] = time.time) -> Item:
+    """Ask the local model, regenerate answers with unquoted citations, check every citation, and
+    return the report Item."""
     if not question.strip():
         raise ValueError("a report needs a question")
     if not excerpts:
         raise ValueError("a report needs at least one excerpt")
+    if quote_retries < 0:
+        raise ValueError("quote retries must be 0 or more")
     user = f"Question: {question.strip()}\n\nExcerpts:\n\n{excerpts_block(excerpts)}"
-    reply = model.chat(SYSTEM, user)
     texts = [it.text.strip()[:MAX_EXCERPT_CHARS] for it in excerpts]
-    check = check_report(reply.text, texts)
+    reply, check, attempts = _ask_until_quoted(model, user, texts, quote_retries)
     meta = {"schema": REPORT_SCHEMA, "question": question.strip(), "model": reply.model,
-            "endpoint": "loopback", "elapsed_s": round(reply.elapsed_s, 3), "citation_check": check}
+            "endpoint": "loopback", "elapsed_s": round(sum(a["elapsed_s"] for a in attempts), 3),
+            "quote_retries": quote_retries, "attempts": attempts,
+            "quote_requirement": "unmet" if check["counts"]["unchecked"] else "met",
+            "citation_check": check}
     return make_item(kind="report", id=f"report-{content_hash(question.strip())[:12]}", title=question.strip()[:120],
                      text=reply.text, source="report", ref=question.strip()[:200], method="synthesized",
                      fetched_at=float(wall()),

{gather_engine-2.2.0 → gather_engine-2.3.0}/src/gather/report_cmd.py

@@ -2,10 +2,12 @@
 (the citation check alone, on any report text).
 
 Both exit 0 when every citation is verified and 1 when any is not, so either can gate a pipeline.
+``gather report`` asks the model again when a citation has no quote, up to ``--quote-retries``.
 """
 
 from __future__ import annotations
 
+import argparse
 import json
 import sys
 from collections.abc import Callable
@@ -22,6 +24,8 @@ def add_report_parsers(sub, add_common: Callable) -> None:
     rep.add_argument("--endpoint", default=DEFAULT_ENDPOINT,
                      help=f"OpenAI-compatible endpoint on this machine (default {DEFAULT_ENDPOINT})")
     rep.add_argument("--timeout", type=float, default=600.0, metavar="S", help="seconds for the model's answer")
+    rep.add_argument("--quote-retries", type=_retries, default=2, metavar="N",
+                     help="new answers to ask for when a citation has no quote (default 2; 0 turns this off)")
     add_common(rep)
     rep.set_defaults(func=cmd_report)
 
@@ -32,6 +36,13 @@ def add_report_parsers(sub, add_common: Callable) -> None:
     chk.set_defaults(func=cmd_cite_check)
 
 
+def _retries(value: str) -> int:
+    n = int(value)
+    if n < 0:
+        raise argparse.ArgumentTypeError("must be 0 or more")
+    return n
+
+
 def _summary(check: dict) -> str:
     counts = ", ".join(f"{k} {v}" for k, v in check["counts"].items() if v)
     return (f"citations: {check['total']} ({counts or 'none'}); precision {check['precision']}; "
@@ -49,7 +60,8 @@ def cmd_report(args) -> int:
 
     try:
         model = LocalModel(args.model, endpoint=args.endpoint, timeout=args.timeout)
-        item = write_report(args.question, load_excerpts(args.excerpts), model)
+        item = write_report(args.question, load_excerpts(args.excerpts), model,
+                            quote_retries=args.quote_retries)
     except (ValueError, OSError, RuntimeError) as exc:
         print(f"report failed: {exc}", file=sys.stderr)
         return 2
@@ -60,6 +72,7 @@ def cmd_report(args) -> int:
     else:
         print(item.text)
         print(f"\n{_summary(check)}")
+        print(f"quote requirement: {item.meta['quote_requirement']} after {len(item.meta['attempts'])} model call(s)")
     if args.store:
         _emit([item], _scope(args), False, store=args.store)
     return 0 if _all_verified(check) else 1

{gather_engine-2.2.0 → gather_engine-2.3.0/src/gather_engine.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gather-engine
-Version: 2.2.0
+Version: 2.3.0
 Summary: Accountable research intake for difficult sources, with provenance receipts and witnessed digests.
 Author: Zain Dana Harper
 License-Expression: LicenseRef-FSL-1.1-MIT
@@ -34,7 +34,7 @@ Dynamic: license-file
 [![downloads](https://img.shields.io/pypi/dm/gather-engine?label=downloads&style=flat-square&labelColor=14041b)](https://pypi.org/project/gather-engine/)
 ![python: 3.11+](https://img.shields.io/badge/python-3.11%2B-blue?style=flat-square&labelColor=14041b)
 ![deps: none (core)](https://img.shields.io/badge/core%20deps-none-success?style=flat-square&labelColor=14041b)
-![version: 2.2.0](https://img.shields.io/badge/version-2.2.0-26dfe8?style=flat-square&labelColor=14041b)
+![version: 2.3.0](https://img.shields.io/badge/version-2.3.0-26dfe8?style=flat-square&labelColor=14041b)
 
 gather pulls research out of the places most tools break on: arXiv papers, authenticated JSON APIs, JavaScript-rendered pages via a real headless browser, scanned images through OCR, and audio through transcription, alongside video, web, feeds, and local docs. The core runs with zero third-party runtime dependencies, and the same engine is reachable from the CLI, MCP tools, and plain Python. Every run writes a receipt you can re-check.
 
@@ -42,7 +42,7 @@ gather pulls research out of the places most tools break on: arXiv papers, authe
 
 ## Current status
 
-`gather-engine 2.2.0` is the current source version. Core intake,
+`gather-engine 2.3.0` is the current source version. Core intake,
 content-addressed corpus storage, exact UTF-8 source-byte receipts, readable
 context selection, descriptor handoff, pilot monitoring, CLI, Python API, and MCP
 surfaces are present in this checkout. Browser rendering, OCR, audio, and fast
@@ -83,7 +83,7 @@ fabricated field cannot reach the corpus by being plausible.
 - **Structured extraction with a hallucination check.** `gather.schema_extract` binds schema fields to source nodes, and `verify_record` rejects any LLM-proposed field value not grounded in the fetched content.
 - **Streaming extraction.** `gather.stream` parses an HTML stream chunk by chunk and emits partial-update commits as blocks complete, each folded into a hash chain, so a streamed extraction is replayable.
 - **Hard-source adapters behind one shape.** Video with captions and comments (`yt-dlp` first, with the official YouTube Data API as a fallback when you supply your own key; each item records which path served it and how fast), Reddit through its official Data API with your own app credentials, static web, RSS/Atom feeds, local docs, arXiv, PDFs (`pdftotext`), authenticated JSON APIs (token from env, never logged), JS-rendered pages (headless Chromium), scanned images (`tesseract`), and audio (`whisper`). Each external tool is optional and only needed for its own adapter.
-- **Cited reports, checked in code.** `gather report` asks a model on your own machine to answer from fixed excerpts with exact quotes, then checks every quote against the excerpt it cites and marks any it cannot verify.
+- **Cited reports, checked in code.** `gather report` asks a model on your own machine to answer from fixed excerpts with exact quotes, then checks every quote against the excerpt it cites and marks any it cannot verify. An answer that cites an excerpt without quoting it is sent back for a rewrite, up to twice.
 - **Filter ledgers.** `--scope TERMS --ledger DIR` writes one row per dropped item with its reason code, plus the input, so `gather ledger verify` can recompute every count.
 - **Channel and playlist intake.** `gather channel <url> --store DIR` lists a channel's videos, shorts, and streams tabs (or one playlist) and gathers every entry with bounded concurrency, resumable from a per-pass ledger. Metadata and comments run as one pass and captions as another (`--no-captions`, `--captions-only`), with polite pacing, bounded backoff on HTTP 429 and session rate limits, a stop at the first bot check (never retried or answered), one caption track per video, and a run summary that counts every outcome by reason.
 - **Scholarly-graph federation.** `gather scholar` queries OpenAlex, Semantic Scholar, and Crossref in one call, dedupes results by normalized DOI (never a fuzzy title match), and can capture citation edges as first-class records with `--edges`.

{gather_engine-2.2.0 → gather_engine-2.3.0}/src/gather_engine.egg-info/SOURCES.txt

@@ -177,6 +177,7 @@ tests/test_release_workflow.py
 tests/test_repo_art.py
 tests/test_repo_card.py
 tests/test_report.py
+tests/test_report_quotes.py
 tests/test_route.py
 tests/test_run.py
 tests/test_schema_extract.py

gather_engine-2.3.0/tests/test_report_quotes.py

@@ -0,0 +1,119 @@
+"""Every citation must quote its excerpt: answers with an unquoted citation are asked again."""
+import json
+
+import pytest
+
+from gather.item import make_item
+from gather.local_model import LocalModel
+from gather.report import QUOTE_RETRIES, SYSTEM, write_report
+
+
+def excerpt(n, text):
+    return make_item(kind="excerpt", id=str(n), title=f"E{n}", text=text, source="docs", ref="x",
+                     method="file-read", fetched_at=0.0)
+
+
+EXCERPTS = [excerpt(1, "Every run writes a receipt you can re-check later."),
+            excerpt(2, "Gather stops at bot checks and records the reason.")]
+QUOTED = 'Gather says "every run writes a receipt" [1].'
+BARE = "Gather keeps receipts [1]. It also stops at bot checks [2]."
+
+
+class Tick:
+    t = 0.0
+
+    def __call__(self):
+        self.t += 2.0
+        return self.t
+
+
+def scripted(*answers):
+    """A model that gives the answers in order and records every request."""
+    calls = []
+
+    def post(url, body, timeout):
+        calls.append(json.loads(body))
+        text = answers[min(len(calls), len(answers)) - 1]
+        return json.dumps({"model": "m", "choices": [{"message": {"content": text}}]}).encode()
+    return LocalModel("m", post=post, clock=Tick()), calls
+
+
+def test_the_prompt_forbids_a_bracketed_number_without_a_quote():
+    assert "A bracketed number with no quotation right before it is not allowed." in SYSTEM
+    assert QUOTE_RETRIES == 2
+
+
+def test_an_unquoted_answer_is_asked_again_and_the_quoted_answer_is_kept():
+    model, calls = scripted(BARE, QUOTED)
+    item = write_report("What does Gather record?", EXCERPTS, model)
+    assert len(calls) == 2 and item.text == QUOTED
+    assert item.meta["quote_requirement"] == "met"
+    assert item.meta["attempts"] == [{"elapsed_s": 2.0, "unchecked": 2}, {"elapsed_s": 2.0, "unchecked": 0}]
+    assert item.meta["elapsed_s"] == 4.0
+    assert item.meta["citation_check"]["counts"]["verified"] == 1
+    retry = calls[1]["messages"]
+    assert retry[0]["content"] == SYSTEM
+    assert retry[1]["content"].startswith(calls[0]["messages"][1]["content"])
+    assert f"Your previous answer:\n{BARE}" in retry[1]["content"]
+    assert "- Gather keeps receipts [1].\n- It also stops at bot checks [2]." in retry[1]["content"]
+
+
+def test_retries_stop_at_the_cap_and_the_last_answer_is_kept_unchanged():
+    last = 'It writes "every run writes a receipt" [1] and more [2].'
+    model, calls = scripted(BARE, BARE, last, QUOTED)
+    item = write_report("q", EXCERPTS, model)
+    assert len(calls) == 1 + QUOTE_RETRIES
+    assert item.text == last
+    assert item.meta["quote_requirement"] == "unmet"
+    check = item.meta["citation_check"]
+    assert check["counts"]["unchecked"] == 1 and check["counts"]["verified"] == 1
+    assert check["total"] == 2 and check["precision"] == 0.5
+
+
+@pytest.mark.parametrize("answer", [
+    QUOTED,
+    'Gather "invents facts out of nothing at all" [1].',
+    'Gather "keeps receipts" [1].',
+    "The excerpts do not answer this question.",
+])
+def test_only_an_unquoted_citation_triggers_a_new_answer(answer):
+    model, calls = scripted(answer, QUOTED)
+    item = write_report("q", EXCERPTS, model)
+    assert len(calls) == 1 and item.text == answer
+    assert item.meta["quote_requirement"] == "met"
+
+
+def test_zero_retries_makes_one_call_and_marks_the_requirement_unmet():
+    model, calls = scripted(BARE, QUOTED)
+    item = write_report("q", EXCERPTS, model, quote_retries=0)
+    assert len(calls) == 1 and item.text == BARE
+    assert item.meta["quote_requirement"] == "unmet" and item.meta["quote_retries"] == 0
+    with pytest.raises(ValueError):
+        write_report("q", EXCERPTS, model, quote_retries=-1)
+
+
+def _cli(monkeypatch, tmp_path, *answers):
+    import gather.local_model as lm
+    model, calls = scripted(*answers)
+    monkeypatch.setattr(lm, "LocalModel", lambda *a, **k: model)
+    ex = tmp_path / "ex.json"
+    ex.write_text(json.dumps([{"text": e.text} for e in EXCERPTS]), encoding="utf-8")
+    return str(ex), calls
+
+
+def test_gather_report_regenerates_by_default(monkeypatch, tmp_path, capsys):
+    from gather.cli import main
+    ex, calls = _cli(monkeypatch, tmp_path, BARE, QUOTED)
+    assert main(["report", "q", "--excerpts", ex, "--model", "m"]) == 0
+    assert len(calls) == 2
+    assert "quote requirement: met after 2 model call(s)" in capsys.readouterr().out
+
+
+def test_gather_report_quote_retries_flag(monkeypatch, tmp_path, capsys):
+    from gather.cli import main
+    ex, calls = _cli(monkeypatch, tmp_path, BARE, QUOTED)
+    assert main(["report", "q", "--excerpts", ex, "--model", "m", "--quote-retries", "0"]) == 1
+    assert len(calls) == 1
+    with pytest.raises(SystemExit) as exc:
+        main(["report", "q", "--excerpts", ex, "--model", "m", "--quote-retries", "-1"])
+    assert exc.value.code == 2