[napetrov]

Summary

Files and functions can no longer grow without bound. Anything over a cap today is frozen at its current size and may only shrink. Anything new over a cap fails.

dokimi/
├── scripts/check_growth.py         + measures lines per file and mccabe complexity per function (stdlib ast)
├── scripts/growth_baseline.json    + 15 files, 99 functions, each at its exact current value
└── tests/test_growth_ratchet.py    + the gate (test job) and the tests showing it fails
├── dokimi/commands/answers.py      a function over the complexity cap was split into helpers, no behavior change
└── tests/test_answers_command.py   + tests for the split
.github/workflows/ci.yml            + static job: `check_growth.py --report --markdown` >> step summary (non-blocking)
AGENTS.md, dokimi/CONTRIBUTING.md   + one bullet each in the quality-gate lists

for each first-party .py (dokimi/, scripts/, tests/, cli.py):
  lines > cap (800 prod, 1000 tests)            -> must be in baseline.files
  any def with complexity > 10                  -> must be in baseline.functions ("path::Qual.name")
for each baseline entry:
  now > recorded                -> FAIL "grew past its baseline"
  now < recorded / under cap / gone -> FAIL "lower or remove it" (`--update` does this, never raises; `--seed` rewrites the whole baseline once, keeping rationales of unchanged entries)
vs the base branch's baseline (origin/$GITHUB_BASE_REF):
  entry added or raised         -> FAIL unless it has "rationale" (<= 300 chars)

How the caps were picked from the tree:

• Prod 800 lines. When the gate was added, 6 of 224 files were over it (model_compare 1317, llm 1112, novelty/bundle 994, commands/novelty 977, harnesses/benchflow 869, harnesses/docker_solver 850). The next largest file has 766 lines.
• Tests 1000 lines. When the gate was added, 8 of 163 test files were over it, 3 over 1200. As of the merge with main (622926c), 15 files in total are over a cap (prod + tests).
• Complexity 10. This is ruff's and mccabe's default max-complexity, so C901 could later move into ruff with the same number. When the gate was added, 81 of 6354 functions were over 10 (29 over 15); as of 622926c, 99 of 7844. The 99 match ruff check --select C901 (max-complexity 10) on the tree, this PR's files included (0 differences). ruff itself is not used because the test job installs only requirements.lock.txt, which does not include ruff.

Fourteen entries were raised or added by the last two merges with main. Each has a rationale naming the PR that grew it before this gate existed: tests/test_repo_environment.py 1369 -> 1371 (#147), repos/manifest.py::_check_task 21 -> 22 (#113), scripts/ci_local.py::run 28 -> 29 (#146), commands/repo.py::cmd_repo_validate 11, new (#150), scripts/cli_surface.py::_value 17, new (#88), scripts/research_register.py::check 19 and ::main 15, new (#139); tests/test_judge_validity.py 1423 -> 2235, tests/test_judge_reliability.py 1505 -> 1695, report/model_compare.py 1296 -> 1297, commands/evaluate.py::cmd_eval_judge_validity 25 -> 29, eval/degrade.py::build_pairs 17, new, and eval/judge_sequential.py::run_sequential 12, new (all #73); repos/l0/adapters.py::_build_names 14 -> 15 (#115). #115 also shrank _cmake under the cap (entry dropped) and Scan.resolve_path 20 -> 19.

Entry values are exact, not ceilings. The rule for raising one is checked against the base branch. A slack ceiling that later growth could fill without anyone noticing is a known way this kind of ratchet stops binding, so a shrunk entry has to come down.

Top 5 by complexity: report/model_compare.py::generate_section_report 53, schema_compat.py::_compare 41, scripts/check_treatment_batch.py::check_file 36, commands/judge_reliability.py::cmd_eval_cross_judge 32, commands/evaluate.py::cmd_eval_judge_validity 29 (tied with gate/novelty_gate.py::evaluate_novelty and scripts/ci_local.py::run).

Evidence

The gate on this tree is tests/test_growth_ratchet.py::test_no_file_or_function_grew_past_its_baseline. With one line appended to dokimi/llm.py:

before: (no gate) -> passes
after:  E  dokimi/llm.py: 1113 lines grew past its baseline 1112; split it instead (see growth_baseline.json)
        1 failed

Tests that the gate binds. Each builds a small project in tmp with the caps lowered:

• test_a_baselined_file_that_grows_fails, test_a_baselined_function_that_grows_fails
• test_a_new_file_over_the_cap_fails (prod and test caps), test_a_new_complex_function_fails
• test_slack_and_stale_entries_fail (shrunk but still over the cap, function gone), test_an_entry_back_under_the_cap_must_go
• test_update_lowers_and_removes_but_never_raises_or_adds
• test_raised_or_added_entries_need_a_rationale, test_an_overlong_rationale_fails
• test_the_base_baseline_is_read_from_git: a real git repo in tmp. Raising an entry with no rationale makes main() exit 1.
• test_complexity_counts_like_ruff_c901: if/elif, loops with else, try handlers and else, with, bool ops, comprehensions, match with a wildcard, nested defs.

test_a_raised_or_added_baseline_entry_says_why skips on this PR because main has no baseline yet. It binds from the next PR on. The mechanism is covered by the git test above.

Local: make ci-local on cd6bc53 (one merge back): 0 failed, 29 passed, 7 skipped (docker smoke, test-latest, cli-surface packaging, conda-forge (no micromamba), docs deploy, pip-audit report, semgrep). The new report step passes. CI: see checks below.

Merge Danger

Door: two-way. Reverting the commit removes the gate and nothing else depends on it.

Blast Radius: contributors

• An open PR that adds a branch to one of the 99 baselined functions, or lines to one of the 15 baselined files, fails tests/test_growth_ratchet.py after rebase. The same happens to a PR that adds a function over complexity 10 or a file over its cap. The fix is to split the code, or to raise the entry with a "rationale". Sibling PRs merged before this one shift the numbers. Merge main into this PR right before it merges and run python scripts/check_growth.py --seed (main has no baseline yet, so raises are accepted), then give each raised or added entry a rationale.
• Open PRs' CI is stale once this lands: their Tests ran before the gate existed, so they can be green and still fail the gate on merge. Re-run their Tests after this merges. Open PRs now: fix(ci): install PyYAML from the tools lock so make dev works again #179, ci(mutation): mutmut pilot over the stats, gates and cache key #178, feat(repo): show result.json process counts in repo report and repo compare #177, fix(gates): nothing measured is not a pass #176, feat(novelty): --repeats for routing noise floor; keep declined replies #175, feat(arms): multi-turn session measurement with per-turn usage #174, feat(novelty): analyze states the measured share of readable words on stdout #173, feat(novelty): routing takes the catalog field, skips disabled and mirrored skills, adds all-vs-all #172, refactor(novelty): move the coverage record below the gate, break the novelty import cycle #171, test(llm): pin provider-call budgets for judge, panel, answer and validation paths #170, refactor(report): split generate_section_report into per-section helpers (complexity 53 -> 4) #169, fix(routing): triage queries skip code fences, zero-query runs say why #168, fix(skills): discovery skips template dirs and counts a mirror once #167, feat(novelty): estimate-only projects the calls and dollars a run will spend #166, refactor(eval): break the stats/interactions and judge/panel import cycles #165, feat(novelty): usage and cost block for routing --model #164, feat(catalog): review skills against the Agent Skills spec, add --strict and --format json #163, feat(skills): draft dokimi-design-evals skill #162, feat(runner): plan.v1 / result.v1 and engine-computed completeness #161, fix(repo): PATH@REV takes a revision with a slash; flush progress per task #159, docs(treatments): how to measure tool choice #158, feat(repo): process metrics in result.json, manifest process_metrics, grade optional for dokimi: graders #157, feat(ci): allow-unsupported input for the repo-eval workflow #156, feat(context, repo): consistency of repeated runs; pass^k and path stability in repo compare #155, feat(repo): record whether the agent used what a patch: arm added (#41 D4) #153, ci: post the cli-interface label and comment from a workflow_run job #151, feat(repo): skill/skill-catalog arms, cache tokens, MCP config when repo ships one #137, feat(repos): built-in review graders dokimi:review_seeds and dokimi:review_replay #120, feat(repo): Codex and Copilot CLI harness profiles, native review mode #116, feat(repo): compare flags comparisons with no headroom #114.
• A PR that shrinks a baselined file or function also has to lower its entry (--update). This is deliberate.
• No package, CLI, artifact or schema change. Changelog fragment changelog.d/20261020_091500_napetrov_growth-ratchet.md (internal refactor, no behavior change).

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
• No ad-hoc run artifacts committed
• New files carry the SPDX license header (or are exempt in .github/.licenserc.yaml)

🤖 Generated with Claude Code

[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 91.62%. Comparing base (caae46a) to head (e893657).
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #93      +/-   ##
==========================================
+ Coverage   91.51%   91.62%   +0.10%     
==========================================
  Files         216      216              
  Lines       27074    27079       +5     
  Branches     4457     4457              
==========================================
+ Hits        24777    24810      +33     
+ Misses       1632     1606      -26     
+ Partials      665      663       -2     

Files with missing lines	Coverage Δ
dokimi/dokimi/commands/answers.py	91.86% <100.00%> (+32.60%)	⬆️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

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

[Copilot]

🟡 Changes recommended

Local CI does not pass its selected base ref to the growth gate, allowing incorrect or skipped rationale checks.

1 open issue

• Pass resolved remote base ref to pytest in make ci-local · New

What changed in this PR

Adds a CI ratchet to prevent unapproved growth in Python file length and function complexity.

Changes:

• Adds measurement, baseline validation, update, and reporting commands.
• Records existing over-cap code and tests enforcement.
• Documents the gate and adds CI summary reporting.

File	Description
dokimi/​tests/​test_growth_ratchet.py	Adds enforcement gates and regression tests.
dokimi/​scripts/​growth_baseline.json	Records existing over-cap measurements.
dokimi/​scripts/​check_growth.py	Implements measurement, validation, and reporting.
dokimi/​CONTRIBUTING.md	Documents limits and baseline maintenance.
AGENTS.md	Adds growth-gate guidance.
.github/​workflows/​ci.yml	Publishes growth metrics in step summaries.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

Baseline measurements match the source tree, and no unresolved blocking issues remain in enforcement or CI integration.

1 open issue

• Pass resolved remote base ref to pytest in make ci-local

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Question validation bypasses rejected-payload preservation and can raise the wrong exception; runtime changes also lack a required changelog fragment.

1 open issue

• Pass resolved remote base ref to pytest in make ci-local

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

Baseline verification supports the recorded values, the prior remote-selection issue is fixed, and no blocking issues remain.

1 open issue

• Pass resolved remote base ref to pytest in make ci-local

_{Review effort: Balanced}

[antonwolfy]

The ratchet is sound. The complexity count matches ruff's C901 on the whole tree and the baseline matches the code. Three things are worth fixing before merge, all about the rule that guards raising an entry.

What I ran, on a Linux review host at 6c4cc20:

• make ci-local: 20 passed, 0 failed, 4 skipped (docker smoke, test-latest, docs deploy, semgrep). 5248 tests passed, 2 skipped.
• Reproductions for the findings, with no network and no LLM calls.
• A mutation run on check_growth.py and ci_local.py: 33 mutants, 12 of which pass the full growth test file.
• check_growth.py complexity against ruff --select C901 on all 6421 defs in the tree: 0 differences.

Checked, no issues

• Baseline: every entry equals the current measurement and the set of over-cap files and functions equals the baseline.
• Line counts: len(text.splitlines()) equals the newline count in every file in the tree.
• CI step: the new static step runs from dokimi/, uses only the standard library, and is not a gate. The test job uses fetch-depth: 0, so origin/main is there for the rationale check.
• Repo rules: SPDX headers are present (the baseline JSON is covered by paths-ignore). No changelog fragment is needed for a CI, scripts, tests and docs change.

I agree with @copilot-pull-request-reviewer's point that make ci-local must pass its resolved base to the growth check; the fix at ci_local.py:283 is right. Its test does not cover it, see the inline comment.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

3 open issues

• DOKIMI_GROWTH_BASE is added to base_env, but in run() the env used for ISOLATED jobs is… · New
• ast.TryStar is only available on newer Python versions (introduced with except*). Referencing… · New
• Pass resolved remote base ref to pytest in make ci-local

_{Review effort: Lite}

[antonwolfy]

Review at 18fb57e. The three test gaps from my last review are closed, and the new tests fail for the right mutants. One new gap in the top_k test is worth fixing before merge, and there is one nit.

What I ran, on a Linux review host at 18fb57e:

• make ci-local: 21 passed, 0 failed, 4 skipped (docker smoke, test-latest, docs deploy, semgrep). 5363 tests passed, 2 skipped.
• Mutants of the three new tests, run against a copy of the tree: replacing 1 + _complexity(case.body) with 1 fails the new if-in-case row (assert 3 == 4); making _is_irrefutable return True for any MatchAs fails the (2 as z) row (assert 2 == 3); dropping the ./ from the git show path fails the subdirectory test only; replacing the config lookup with DEFAULT_RETRIEVAL_TOP_K fails the config row (assert 3 == 7); dropping the default fails the default row (assert None == 3).
• The top_k flag mutant below, with the LLM and MCP transports mocked as in the test file.

Other points

1. Nit: the counts in the comments are stale. check_growth.py:55 says 3 test files are over 1200 lines; the baseline has 4 (1223, 1423, 1480, 1704). check_growth.py:59 says 81 of 6354 functions are over the cap; the baseline has 80, and --report counts 6548 functions. Also, answers.py:72 assigns _product_config, which nothing reads.

Checked, no issues

• Subdirectory test: the project sits under proj/ in the git root, the base baseline is read with 22 lines, and a raise to 23 with no rationale exits 1.
• Match rows: each new row is the only row that fails its mutant, and each fails on the expected count.
• CI step and docs: unchanged since 2a2bdd2.

[napetrov]

Review at 18fb57e, pushed in 4c8c624:

1. Counts in check_growth.py: fixed. The test-file line now reads 4 over 1200 (of 167 over 1000 lines: 8), and the function line reads 80 of 6548 at this commit. The PR description still has the old numbers; I have not edited it.
2. answers.py: fixed. The unused _product_config assignment is removed. Behaviour is unchanged.

The top_k flag row is fixed as well (inline reply above). Growth gate --base HEAD exits 0, and tests/test_answers_command.py plus tests/test_growth_ratchet.py pass (53 passed, 1 skipped).

[napetrov]

Items from the review comment above, pushed in fb5275f:

1. Concurrent shrink on main: option a. check_growth.py now documents running python scripts/check_growth.py --update after rebasing to lower shrunk entries (docstring and changelog fragment). A second PR can still break main between rebase and merge.
2. Reseed: merged intel/dokimi main (8346024) and rebuilt the baseline from the current tree with a new --seed option. Every entry that grew or was new carries the rationale "pre-existing when the gate was introduced"; shrunk entries were lowered. test_growth_ratchet passes (with a regression test for --seed), full suite and ruff pass.
3. Stale green: added to the Merge Danger section of the PR body, with the list of open PRs. Their Tests should be re-run after this merges.

[xaleryb]

Ran at fb5275f: the full suite, ruff, mypy and bandit; the growth gate against a base with and without a baseline; and each earlier point's original input.

• --seed after this lands: append 20 lines to dokimi/llm.py, run check_growth.py --seed, and the entry becomes 1132 with "pre-existing when the gate was introduced". The gate then exits 0. Expected: exit 1, a raise needs a hand-written rationale.
• Description: it still says "14 files, 81 functions" and "No package change ... No changelog fragment". The head has 15 files and 88 functions, changes commands/answers.py and adds a fragment.

Pushed:

• a38b9be: the rationale check treats the --seed text as missing once the base has a baseline, so seeding still works for this PR only. Includes a test and a line in the fragment.

Left for the author: update the description. Static checks fails on the license header of two files from main (#112), not from this PR.

[antonwolfy]

Review at a38b9be. The --seed mode and the seed-text rule hold up, and the top_k thread is fixed. One test gap in the seed test is worth closing before merge, and there is one nit.

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

• make ci-local: 27 passed, 0 failed, 4 skipped (docker smoke, test-latest, docs deploy, semgrep).
• A mutation run on the new seeded() and SEED_RATIONALE code against test_growth_ratchet.py: 13 mutants, 1 of which passes the file (inline).
• The top_k mutant from my earlier thread (if True: at answers.py:73): the flag row now fails (1 failed, 9 passed).

Checked, no issues

• Seed rule: a base entry whose rationale is the seed text, raised in the head with that text kept, is reported as raised without a rationale. So is a hand-added entry with the seed text. A raise that reuses the base's rationale is still reported.
• --seed against a git base: test_seed_cannot_explain_growth_once_the_base_has_a_baseline goes through the real git path; main --base main exits 1 and flags exactly the raised and the new file.
• Docs and flags: --update, --seed, --report, --markdown, --json, --base, the 800/1000/10 caps and the 300-character limit match the docstring, AGENTS.md, CONTRIBUTING.md and the changelog fragment.

[napetrov]

Re @xaleryb's description point: the PR body is updated to the current head (edf7e19): 15 files and 94 functions in the baseline, and it names the commands/answers.py change and the changelog fragment 20261020_091500_napetrov_growth-ratchet.md. @antonwolfy's --seed equality test and stale-count nit are fixed in a7f377b (answered on their threads); the baseline was reseeded after main grew in edf7e19.

[xaleryb]

Re-checked at edf7e19: full suite, ruff, mypy and bandit, the original input of each earlier point, and the head merged with current main (ad1cbd0).

• Head merged with current main -> check_growth.py exits 1 with 4 violations: tests/test_repo_environment.py 1371 > 1369, repos/manifest.py::_check_task 22 > 21, scripts/ci_local.py::run 29 > 28, and commands/repo.py::cmd_repo_validate at 11 with no entry. test_no_file_or_function_grew_past_its_baseline fails on the merge. Expected: green. The head's CI ran against an older main, and main requires no checks, so merging now turns main red.
• Earlier points: --seed after a raise against a baselined base now exits 1. The description counts (15 files, 94 functions) match the head.

No commits pushed this round.

Left for the author: merge main, run python scripts/check_growth.py --seed right before merging, then re-run CI.

[napetrov]

@xaleryb thanks, done as you suggested. I merged main and ran --seed. Main moved while the first CI run was going, so I did it twice.

• Round 1: merged main (86e0a8c, Add a research register for ideas, experiments and decisions #139) in ce9b275 and seeded in cd6bc53. CI on that head failed only test_no_file_or_function_grew_past_its_baseline, because feat(judge-validity): --context stored — gate the judge the way arms are scored #73 and repo scan: L0 rules for parity with oneDAL static_check (D6) #115 landed during the run. Round 2: merged main (caae46a, repo scan: L0 rules for parity with oneDAL static_check (D6) #115) in 622926c and re-seeded in e893657. Both are merge commits with no conflicts. A --update after each seed lowered nothing extra.
• Each raised or added entry has a rationale naming the PR that grew it before the gate existed ("grew/added on main in #N ... before the ratchet landed; split it in its own PR"). I measured each value at the commit before and after that PR:
  • test(repo-environment): give the hostile-string regex test a CI-safe time limit #147: tests/test_repo_environment.py 1369 -> 1371
  • ci: reusable repo-eval workflow (validate, scan, tasks check) with dokimi pinned #113: repos/manifest.py::_check_task 21 -> 22
  • ci(conda-forge): solve the runtime dependencies from conda-forge on PRs that change them #146: scripts/ci_local.py::run 28 -> 29
  • feat(repo): repo fetch --json, validate and budget --out, validate --fail-on-warning #150: commands/repo.py::cmd_repo_validate 10 -> 11 (new entry)
  • ci: report user-facing CLI surface changes on every PR #88: scripts/cli_surface.py::_value 17 (new)
  • Add a research register for ideas, experiments and decisions #139: scripts/research_register.py::check 19 and ::main 15 (new)
  • feat(judge-validity): --context stored — gate the judge the way arms are scored #73: tests/test_judge_validity.py 1423 -> 2235, tests/test_judge_reliability.py 1505 -> 1695, report/model_compare.py 1296 -> 1297, commands/evaluate.py::cmd_eval_judge_validity 25 -> 29, eval/degrade.py::build_pairs 10 -> 17 (new), eval/judge_sequential.py::run_sequential 6 -> 12 (new)
  • repo scan: L0 rules for parity with oneDAL static_check (D6) #115: repos/l0/adapters.py::_build_names 14 -> 15. repo scan: L0 rules for parity with oneDAL static_check (D6) #115 also shrank _cmake to 6 (entry dropped) and Scan.resolve_path 20 -> 19 (lowered).
• New counts: 15 files and 99 functions (was 94) out of 7844. The 99 still match ruff check --select C901 exactly. I updated the counts, top 5, open-PR list and ci-local numbers in the PR body.
• Local results: check_growth.py exits 0 against both main and the old head edf7e19 (so every raise has a new rationale). The growth, import-architecture and ci_local tests show 92 passed, 1 skipped, and mypy is clean. make ci-local on cd6bc53 shows 0 failed, 29 passed, 7 skipped.
• CI on e893657: all green (22 pass, 2 skipped: test-latest and Pages deploy). The PR is mergeable and main has not moved since.

With about 30 open PRs, any sibling that lands first will shift these numbers again. If that happens before this merges, the merge plus --seed needs one more round.

[antonwolfy]

LGTM. Both threads from my last review are fixed, and the reseed after the merge of main holds up. No new findings.

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

• make ci-local: 28 passed, 1 failed, 7 skipped. 7146 tests passed, 2 skipped. The one failure is pip-audit, which reports a gitpython 3.2.0 advisory (fix in 3.2.1). The PR touches no lock file.
• 32 mutants of check_growth.py against test_growth_ratchet.py: 28 killed. The 4 survivors are equivalent or cosmetic (the isinstance guard in seeded(), > vs >= on the 300-character rationale limit, splitlines() vs count("\n") on a file with no trailing newline, startswith("tests/")). The now < old[metric] mutant from my thread now fails.

Checked, no issues

• Baseline: check_growth.py --base HEAD exits 0. ruff check --select C901 at max-complexity 10 finds the same 99 functions with the same values, and the 15 files over a cap match the baseline line for line.
• Rationales: every one is at most 300 characters. I measured each raised or added entry at the commit before and after the PR it names (#73, #88, #113, #115, #139, #146, #147, #150, #72, #101); the "from X to Y" claims are right.
• Docs and CI step: flags, caps and the DOKIMI_GROWTH_BASE fallback order match AGENTS.md, CONTRIBUTING.md, the changelog fragment and the static step.
• answers.py split: messages, exit codes and the order of side effects match the PR's base. test_answers_command.py: 10 passed.