[napetrov]

Summary

Codifies "new error paths and tests trace to the contract", taken from carver/unslop-code's min12 prompt (tests come from spec phrases, a new error path only where the spec can be quoted, unclear requirements go to an ambiguities note; erosion fell 0.58 → 0.15 on SlopCodeBench). Follows #729 (ruff BLE001/S110/S112).

Changes

• REVIEW.md: a new raise/sys.exit/refusal no doc, contract or issue asks for, or a test of new behaviour that cites no doc line, is a defect to ask about; code built on a guessed requirement too.
• AGENTS.md "Before opening a PR": the author-side rule.
• PR template: new Open questions section and a checklist line.
• dokimi/scripts/list_new_error_paths.py: lists added raise, sys.exit, SystemExit(, exit_code=N and def test_ lines in the --base...--head diff of *.py files as path:line: kind: text. It judges nothing: exits 0 (also when empty), 2 when git cannot diff. Not wired into CI, since a listing is not a pass/fail signal.

Risk

Docs and a standalone script; no package code changes.

Testing

tests/test_list_new_error_paths.py (diff parsing, deleted file, ++-content row not taken as a header (mutation-checked), exit 2), tests/test_docs_code_refs.py, tests/test_audit_test_quality.py, ruff, check_comment_blocks.py. Not run: mypy and full make ci-local (no dev venv on this box).

Open questions

• Should list_new_error_paths.py become a CI step that posts its listing as a job summary? Left out here as it judges nothing.

Revert

Plain revert; nothing persisted.

Local self-review (pr-review local mode, 2 passes): one blocking parse bug and two nits found and fixed.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The diff parser silently omits added error paths and tests when hunk content resembles file headers, filenames contain spaces, or Git disables path prefixes.

3 open issues

• Strip header tab before checking Python file suffix · New
• Recognize file headers only outside diff hunks · New
• Set explicit Git diff prefixes to support noprefix config · New

What changed in this PR

3 findings.

This PR adds contract traceability to dokimi’s author and review guidance, extending the earlier work on explicit error handling. It introduces a standalone listing tool without changing package code or adding a CI gate.

Changes:

• Require new error paths and tests to cite their supporting requirements.
• Add an Open questions section for unclear requirements.
• Add a diff-based listing script and tests for parsing and exit behavior.

File	Description
REVIEW.md	Adds contract-traceability review criteria.
dokimi/​tests/​test_list_new_error_paths.py	Tests diff parsing and command exit behavior.
dokimi/​scripts/​list_new_error_paths.py	Lists added error-path and test lines for review.
dokimi/​changelog.d/​20261113_120000_napetrov_contract-trace.md	Documents the guidance and listing tool.
AGENTS.md	Adds author-side traceability and ambiguity checks.
.github/​pull_request_template.md	Adds open questions and a traceability checklist item.

_{Review effort: Balanced}

[exai-bot]

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

CI at 00f71c0: 24 passing, 3 skipped.

Review limit reached. This PR has had 6 reviews, so it will only be reviewed again when you ask.
To ask: re-request review from exai-bot in the Reviewers list.

Review details

• Commit reviewed: 00f71c0 against merge base abed276
• Coverage: 4 files in 2 groups
• Engine: OpenCodeReview v1.13.5-exai.4.8f73eada, us.openai.gpt-6.1-sol
• Usage: 70k tokens (35k from cache), 17s
• Tool calls: 7 (6 file_read, 1 file_read_diff)
• Repository agent and review guidance: 2 files
• Dokimi error-path tests and changelog: 2 files

[vchamarthi]

Pushed 1 commit to contract-trace (db80233..96e265c).

• Header rows are recognised only between hunks.
• Trailing tab on headers is stripped.
• Explicit --src-prefix=a/ --dst-prefix=b/ --inter-hunk-context=0 passed to git.
• Context rows count toward line numbers.
• Spaced exit calls match.
• main test uses a non-empty diff.
• Shebang removed.

Threads: 7 fixed, 0 answered as not a defect.
Run: the full suite with main merged in, 19799 passed.
Static checks fails on main as well: the committed docs/reference/cli-interface.json is over the 500 KB limit of the pre-commit large-file hook. #737 fixes it.

[xaleryb]

• Ran: head merged with current main, full suite plus ruff, mypy, bandit, growth, comment-block and docs benchmark gates, and the script on this PR's own diff under several git diff configs.
• Open thread on L70 (external diff) reproduces: GIT_EXTERNAL_DIFF=/bin/true or diff.external=/bin/true or a *.py textconv driver -> 0 new error path(s), exit 0 -> expected the same sites as a plain run.
• Pushed (96e265c..a68aeb4): a68aeb4 fix(scripts): pass --no-ext-diff --no-textconv to git diff; adds a real-git test parametrized over an external diff and a textconv driver, red without either flag.
• Left to the author: cleanup(); raise X on one line (thread on the regex) is still not listed; no code on main uses that idiom today.
• Static checks fails only on the pre-existing cli-interface.json size, which main already fixes.

[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 95.72%. Comparing base (f12057b) to head (00f71c0).
⚠️ Report is 2 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     #732   +/-   ##
=======================================
  Coverage   95.71%   95.72%           
=======================================
  Files         415      415           
  Lines       55346    55362   +16     
  Branches     9514     9516    +2     
=======================================
+ Hits        52977    52993   +16     
  Misses       1466     1466           
  Partials      903      903           

see 2 files with indirect coverage changes

🚀 New features to boost your workflow:

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

[xaleryb]

Re-checked on a68aeb4 merged with main: with an external diff driver or a textconv driver configured, the script now lists the same error paths as a plain run (it listed 0 before); the full suite, ruff, mypy, bandit, the docs gate and the growth and comment-block checks pass, and CI is green. Left as a note: cleanup(); raise X on one line is still not listed; main has no such site today.

[antonwolfy]

The parser holds up: line numbers were right for multi-hunk diffs, renames, new and deleted files, and \ No newline rows, and the docs match the script. The nits inline are both silent omissions from the listing. The merge also waits for the question @xaleryb left to the author on cleanup(); raise X.

What I ran, on a Linux review host at c536fd9:

• make ci-local: 31 passed, 1 failed, 14 skipped. The failure is Run tests: 19,961 passed, 2 errors, both pytest timeouts (>60s) in tests/test_audit_test_quality.py, a file this PR does not touch. Run alone, that file passes (172 passed). Changed-line coverage passed.
• Reproductions of the parser cases and mutations of the script (line counting, header guards, each git flag), against a real git repo.
• Every commit carries a Signed-off-by.

Checked, no issues

• Usage lines: python scripts/list_new_error_paths.py --base origin/main from dokimi/ and the dokimi/scripts/ form from the repo root both run. A bad --base exits 2, an empty listing exits 0, as the changelog says.
• Changelog fragment: category and style match the neighbouring fragments.

Bot points I checked that no longer apply at this head (7)

• Copilot's point on the trailing tab in a header for a path with spaces does not apply: removesuffix("\t") drops it and test_a_path_with_spaces_keeps_its_sites pins it.
• Copilot's point on --- old / +++ new content rows read as file headers does not apply: headers are read only between hunks, using the hunk line counts.
• Copilot's point on diff.noprefix does not apply: git diff is called with --src-prefix=a/ --dst-prefix=b/.
• exai-bot's point on the shebang in a mode 100644 file does not apply: the shebang is gone and ruff passes.
• exai-bot's point on header-like content rows does not apply at this head: the parser tracks hunk line counts and reads headers only outside hunks.
• exai-bot's point on missing diff prefixes does not apply: the prefixes are passed explicitly.
• exai-bot's point on external diff and textconv drivers does not apply: --no-ext-diff --no-textconv are passed and a real-git test covers both.

[napetrov]

Re: review by antonwolfy

The merge waits for the question on cleanup(); raise X.
Fixed in e9a13d9: a ; starts a statement now.

[napetrov]

Re: comment by vchamarthi

Static checks fails on main as well; #737 fixes it.
Already in 4ac7838: intel/main with #737 is merged in.

[napetrov]

Re: comment by xaleryb

cleanup(); raise X on one line is still not listed.
Fixed in e9a13d9: a ; starts a statement now.

[antonwolfy]

LGTM. The three commits since my last review fix both of my earlier nits: cleanup(); raise X is listed, and a git-quoted path such as "b/a\tb.py" is decoded before the b/ check. The explicit --output-indicator-* flags are pinned in the call. Two nits inline.

What I ran, on a Linux review host at abed276:

• make ci-local: 31 passed, 2 failed, 14 skipped. Run tests, Coverage of changed lines, ruff, mypy, bandit, Fragment for package changes, Comment blocks and the docs build pass. The two failures are Install gitleaks (an HTTP 504 on the download) and Scan commits, which needs that binary. Neither touches this PR's files.
• Real-git reproductions in a temporary repo with the LLM transport not involved: paths with a tab, ", \, a newline, a bell, ;, a space, é and CJK all list their sites, and the run exits 0.
• A mutation run of the new code: removing the ; alternative, changing the octal decoding or dropping any of the three --output-indicator-* flags is caught by the tests.
• Every non-merge commit carries a Signed-off-by.

Checked, no issues

• Docs against the script: the scripts/... and dokimi/scripts/... usage lines both run, the exit codes (0, also when empty; 2 when git cannot diff) match the changelog fragment, and the docs-gate tests pass.
• PR template, REVIEW.md and AGENTS.md: they say the same thing about tracing to a doc, contract or issue and about "Open questions".

[antonwolfy]

LGTM. I pushed a commit per nit, up to 00f71c0, which fix the two nits from my review:

• 48092cd: REVIEW.md:30: the sentence now says the script lists a raise, a sys.exit or SystemExit call, or a literal exit_code=N, and that parser.error and return N refusals are not listed; AGENTS.md and the changelog fragment say the same.
• 00f71c0: dokimi/tests/test_list_new_error_paths.py:94: a parametrized test pins the a, b, n, v, f and r escapes of a git-quoted path.

make ci-local at 00f71c0: 31 passed, 2 failed (host: gitleaks download 504 and the scan that needs it), 14 skipped.