ci: no-growth ratchet for file length and function complexity

.github/workflows/ci.yml

@@ -77,6 +77,12 @@ jobs:
       - name: registry-drift-check
         if: ${{ !cancelled() }}
         run: python -m dokimi.config_check
+      # Not a gate: file length and complexity totals and the top offenders in
+      # the step summary, so the trend is visible per run. The gate (no growth
+      # past scripts/growth_baseline.json) is tests/test_growth_ratchet.py.
+      - name: File length and complexity report
+        if: ${{ !cancelled() }}
+        run: python scripts/check_growth.py --report --markdown >> "$GITHUB_STEP_SUMMARY"
       - name: guidance self-scan (L0)
         if: ${{ !cancelled() }}
         run: python cli.py repo scan .. --manifest-file benchmarks/self-scan.repo-eval.yaml --fail-on-fail

AGENTS.md

@@ -31,6 +31,9 @@ also holds a PR to:
 - Imports follow the layers in `dokimi/tests/test_import_architecture.py`: no
   upward import, no new cycle, LLM SDKs only in `dokimi.llm`, spawns only in
   `dokimi.process`. Its baselines only shrink.
+- No growth: a file over 800 lines (tests 1000) or a function over complexity 10
+  fails unless `scripts/growth_baseline.json` holds it, and then it may only
+  shrink. Split instead; after shrinking, `python scripts/check_growth.py --update`.
 - Tests that check behaviour: `tests/test_audit_test_quality.py` fails a test that only
   checks types, echoes its input, only checks a mock was called, asserts nothing or
   repeats another (`python scripts/audit_test_quality.py` lists them).

dokimi/CONTRIBUTING.md

@@ -85,6 +85,13 @@ CI additionally holds a PR to:
   (front end → tracks → evaluation → components → foundation; nothing imports `cli` or
   `commands`), fails a new import cycle, and keeps provider SDKs behind `dokimi.llm` and
   child processes behind `dokimi.process`. Its baselines only shrink.
+- **No growth in file length or complexity.** A first-party `.py` file over 800
+  lines (1000 under `tests/`) or a function over cyclomatic complexity 10 (ruff's
+  C901 count) fails `tests/test_growth_ratchet.py` unless `scripts/growth_baseline.json`
+  records it; a recorded one may shrink, never grow, and its entry comes down with
+  it (`python scripts/check_growth.py --update`). Raising or adding an entry needs a
+  `"rationale"` of at most 300 characters. `--report` prints the totals; the static
+  job adds them to its step summary.
 - **Tests that fail loudly.** `pytest` fails a test that runs over 60 s
   (`@pytest.mark.timeout(N)` allows more), turns a warning into an error, and
   shuffles the test order (pytest-randomly). The header prints

dokimi/changelog.d/20261020_091500_napetrov_growth-ratchet.md

@@ -0,0 +1,10 @@
+### Changed
+
+- **Internal refactor, no behavior change** — functions over the new
+  complexity cap were split into helpers. CI now fails a PR that makes a
+  file longer or a function more complex than its entry in
+  `scripts/growth_baseline.json`; `python scripts/check_growth.py --update`
+  lowers the baseline when code shrinks.
+  After rebasing onto main, run it to lower shrunk entries; `--seed`
+  re-records every over-cap entry at its current value. Once main has a
+  baseline, a raised or added entry needs a hand-written rationale.

dokimi/dokimi/commands/answers.py

@@ -21,46 +21,59 @@
 )
 
 
+def _load_runtime_config() -> dict:
+    import yaml
+
+    from dokimi.config import runtime_config_path
+
+    config_path = runtime_config_path()
+    if not config_path.exists():
+        return {}
+    try:
+        loaded = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        print(f"Error: invalid YAML in {config_path}: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc
+    if loaded is not None and not isinstance(loaded, dict):
+        print(f"Error: expected a mapping in {config_path}", file=sys.stderr)
+        raise SystemExit(1)
+    return loaded or {}
+
+
+def _load_questions(path: str) -> list:
+    from dokimi.questions.artifact import load_questions
+
+    try:
+        return load_questions(path).questions
+    except ValueError as exc:  # ArtifactValidationError: names the record and the fix
+        print(f"Error: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc
+
+
+def _output_path(args: argparse.Namespace) -> Path:
+    if args.output:
+        return Path(args.output)
+    if getattr(args, "run_id", None):
+        return Path(f"results/{args.product.lower()}_{args.run_id}/answers/{args.product}.json")
+    return Path(f"answers/{args.product}.json")
+
+
 def cmd_answers_generate(args: argparse.Namespace) -> None:
     """Generate context-arm and baseline answers for questions."""
     if getattr(args, "ragas", False):
         _require_ragas()
-    import yaml
     from dokimi.eval import Answerer
     from dokimi.mcp.factory import (
         create_doc_source_client,
         resolve_library_id_for_product,
     )
 
-    # Load config
-    from dokimi.config import runtime_config_path
-
-    config_path = runtime_config_path()
-    config: dict = {}
-    if config_path.exists():
-        try:
-            loaded = yaml.safe_load(config_path.read_text(encoding="utf-8"))
-        except yaml.YAMLError as exc:
-            print(f"Error: invalid YAML in {config_path}: {exc}", file=sys.stderr)
-            raise SystemExit(1) from exc
-        if loaded is not None and not isinstance(loaded, dict):
-            print(f"Error: expected a mapping in {config_path}", file=sys.stderr)
-            raise SystemExit(1)
-        config = loaded or {}
-
-    _product_config = config.get("products", {}).get(args.product, {})
+    config = _load_runtime_config()
     _retrieval_cfg = config.get("retrieval", {})
     if args.top_k is None:
         args.top_k = _retrieval_cfg.get("top_k", DEFAULT_RETRIEVAL_TOP_K)
 
-    # Load questions
-    from dokimi.questions.artifact import load_questions
-
-    try:
-        questions = load_questions(args.questions).questions
-    except ValueError as exc:  # ArtifactValidationError: names the record and the fix
-        print(f"Error: {exc}", file=sys.stderr)
-        raise SystemExit(1) from exc
+    questions = _load_questions(args.questions)
     print(f"Loaded {len(questions)} questions from {args.questions}")
 
     # Setup documentation source client
@@ -91,13 +104,7 @@ def cmd_answers_generate(args: argparse.Namespace) -> None:
         debug_retrieval=args.debug_retrieval
     )
 
-    if args.output:
-        output_path = Path(args.output)
-    elif getattr(args, "run_id", None):
-        output_path = Path(f"results/{args.product.lower()}_{args.run_id}/answers/{args.product}.json")
-    else:
-        output_path = Path(f"answers/{args.product}.json")
-
+    output_path = _output_path(args)
     answers = answerer.generate_answers(
         library_name=args.product,
         library_id=library_id,