[antonwolfy]

Summary

Follow-up to an audit of a dokimi repo reach run on IntelPython/dpnp#3099 (item 7, part 1): a lead-in line before the tokens tripped the prose warning.
Haiku answered the read=dpnp scenario with Now I'll list all verification tokens found in my context: on its own line, then all 4 tokens one per line. prose_words counted the lead-in's 10 words, over PROSE_LIMIT (8), so the text output printed warning: read=dpnp answered with 10 words besides tokens; read its trace before trusting its not_loaded cells although every token was reported.

Review of this PR (comment): the first version dropped the lead-in whatever its length, so a one-line explanation or partial refusal ending in : counted as 0 prose and the warning stayed silent. The lead-in is now skipped only when it has at most 12 words.

prose_words on main and on this branch (<lead-in> is the line above, <4 tokens> the four tokens one per line, <refusal> the reviewer's line I could not read most files because the sandbox denied access, and I refuse to guess what else was there, but here is what I saw:):

answer	main	here
<lead-in> + <4 tokens> (the dpnp answer)	10	0
blank line, <lead-in>, blank line, <4 tokens>	10	0
<lead-in> + <4 tokens> + These are all the tokens.	15	5
<lead-in> alone	10	10
<lead-in> + NONE	10	10
<lead-in> ending in . instead of : + <4 tokens>	10	10
a token, then <lead-in>, then a token	10	10
Here are all the verification tokens that were found in my context: (12 words) + a token	12	0
Here are all of the verification tokens that were found in my context: (13 words) + a token	13	13
<refusal> + a token	23	23 (0 at this PR's first commit)

Changes

• dokimi/dokimi/repos/reach.py::prose_words: the first non-empty line is not counted when it ends in :, has at most LEAD_IN_WORDS (12) words, counted as prose counts them, and a later line holds a token. Every other word still counts: a sentence after the tokens, a lead-in with no token after it, a first line not ending in :, a : line that is not the first, a first line of 13 or more words. The docstring says so. The word count moves into a helper, _prose, used for both the line and the answer.
• docs/repo-evaluation-contract.md §7, the prose bullet: a lead-in line of at most 12 words ending in : before the tokens is not counted.
• tests/test_repo_reach_edges.py::test_prose_skips_only_a_lead_in_before_tokens: the ten cases in the table, next to the existing prose_words test.
• Changelog fragment (Fixed).

Risk

prose in guidance_reach.v1 payloads, and the warning in the text output, are lower for an answer that opens with such a lead-in, by that line's word count. No schema, scenario, class or exit code changes. An answer whose first line is a :-ended sentence of real explanation, 12 words or fewer, before the tokens no longer counts that line. A longer first line, and any further explanation, still counts.

Testing

On a Linux review host, at d0b1adf (on main 93ff3a4):

• make ci-local: 28 passed, 2 failed, 7 skipped. The 2 failures were windows-smoke's Build and install the wheel (pip: [Errno 28] No space left on device in the host's temp dir) and the Smoke-test the installed wheel step after it (No module named 'dokimi'). Rerun alone (CI_LOCAL_ARGS='--jobs windows-smoke'), all 4 of that job's steps passed. Skipped: ci.yml test-latest, docs.yml deploy, pip-audit.yml report (job condition false on a PR); cli-interface Package the result (unknown expression); conda-forge-deps (micromamba not on PATH); semgrep secrets (offline). 12552 tests passed, 5 skipped, 6 xfailed; changed-line coverage 100% (8 lines).
• The new test against main's code: the dpnp answer, the blank-line variant, the trailing-sentence case and the 12-word line fail (10, 10, 15, 12 instead of 0, 0, 5, 0). Against this PR's first commit (268a8f2): the 13-word line and the refusal fail (0 instead of 13 and 23).
• Mutants, each run against the new test:
  • drop the endswith(":") check: the lead-in ending in . case fails (0 instead of 10);
  • drop the "a later line holds a token" check: the lead-in alone and lead-in + NONE cases fail (0 instead of 10);
  • drop the word limit: the 13-word line and the refusal fail;
  • <= LEAD_IN_WORDS to <: the 12-word line fails;
  • LEAD_IN_WORDS = 13: the 13-word line fails.
• Live, Claude Code 2.1.316 with Haiku 4.5, on a synthetic tree, at 268a8f2: on main's prose_words Haiku answered a scenario with Now listing all verification tokens I can see in my context: and its two tokens, and the text output warned answered with 10 words besides tokens. With the first commit, rerun: the answers opened with Now, listing all verification tokens visible in my context: and printed no warning. Both lead-ins have 12 words or fewer (10 and 9 as prose counts them), so the word limit changes neither result. Not rerun live at d0b1adf.
• Merged together with fix(repo): Claude Code Bash reads count as reads; bash= reach scenario #369 on main 93ff3a4, at 268a8f2: pytest -n auto 12525 passed, 59 skipped, 6 xfailed; mypy and ruff check clean. Not yet run merged together with the other follow-up branches at d0b1adf.
• Not run: a real harness against IntelPython/dpnp; the table's cases use the answer text from that run.

Revert

A plain revert restores the old count. Nothing stored changes shape: payloads written with the new count stay valid under guidance_reach.v1.

Checklist

• Tests added/updated and pytest passes
• ruff, mypy, and schema checks pass
• Docs updated (or N/A) — see the docs-drift checklist in CONTRIBUTING.md
• Self-reviewed per "Before opening a PR" in AGENTS.md
• No ad-hoc run artifacts committed
• New files carry the SPDX license header (or are exempt in .github/.licenserc.yaml)

[Copilot]

🟢 Approval recommended

No active review issues remain for the change that avoids false prose warnings for token-list lead-ins.

No open issues 🎉

What changed in this PR

0 new findings; nothing to fix.

This PR prevents false prose warnings in repo reach when an agent introduces its token list with a short lead-in.

Changes:

• Excludes the first non-empty line from the prose count when it ends in : and a later line contains a token.
• Adds seven regression cases covering qualifying lead-ins and prose that must still count.
• Updates the contract and changelog to describe the counting rule.

File	Description
dokimi/​tests/​test_repo_reach_edges.py	Adds regression coverage for lead-in handling.
dokimi/​dokimi/​repos/​reach.py	Implements and documents the lead-in exclusion.
dokimi/​docs/​repo-evaluation-contract.md	Clarifies how lead-ins affect prose.
dokimi/​changelog.d/​20261102_120000_antonwolfy_reach-lead-in-prose.md	Records the prose-warning fix.

_{Review effort: Balanced}

[exai-bot]

✅ OpenCodeReview: Review complete: 0 finding(s) across 4 selected item(s).

Review details

• Commit reviewed: d0b1adf against merge base 93ff3a4
• Coverage: 4 files in 1 groups
• Engine: OpenCodeReview v1.13.3, us.openai.gpt-6.1-sol
• Usage: 34k tokens (13k from cache), 7s
• Tool calls: 4 (4 file_read)
• Reach lead-in prose behavior, contract, tests, and changelog: 4 files

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.30%. Comparing base (93ff3a4) to head (d0b1adf).
⚠️ Report is 1 commits behind head on main.
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #368      +/-   ##
==========================================
+ Coverage   94.29%   94.30%   +0.01%     
==========================================
  Files         308      309       +1     
  Lines       39322    39443     +121     
  Branches     6651     6673      +22     
==========================================
+ Hits        37077    37198     +121     
- Misses       1432     1433       +1     
+ Partials      813      812       -1     

Files with missing lines	Coverage Δ
dokimi/dokimi/repos/reach.py	96.87% <100.00%> (+0.06%)	⬆️

... and 6 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[vlad-perevezentsev]

Review at 268a8f2. The fix is right for the Haiku answer and the tests pin the cases that must still count; one gap: a lead-in of any length is dropped, so a long explanation on one line ending in : hides the prose warning (line comment).

What I ran, at 268a8f2:

• make ci-local --offline: 0 failed, 19 passed, 13 skipped.
• prose_words on a 25-word refusal line ending in : followed by one token: 0.

Checked, no issues

• Docs and changelog: the contract and the fragment (Fixed) describe the new rule and its limits.

[napetrov]

The only finding is the one already open in #368 (comment): a one-line refusal ending in : goes from 18 to 0 words and the prose warning goes silent (probe_prose.py, base vs head). Nothing else found. Not handled on either tree, and not claimed: a lead-in wrapped over two lines, a full-width ：.

Coverage: plain + edge passes; test_repo_reach_edges.py 23 passed on head; no live harness.

[antonwolfy]

Round for @vlad-perevezentsev's review, at d0b1adf (CI green, OpenCodeReview 0 findings): a first line ending in : is skipped as a lead-in only when it has at most 12 words (LEAD_IN_WORDS; Haiku's has 10). A longer one-line explanation or refusal ending in : counts as prose again, so the warning fires: your example counts 23 words.

[napetrov]

Approving at d0b1adf: CI green, my earlier threads are addressed, and re-review of the latest round found nothing in this PR's files.