crapkit 0.4.6__tar.gz → 0.4.7__tar.gz

{crapkit-0.4.6/src/crapkit.egg-info → crapkit-0.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crapkit
-Version: 0.4.6
+Version: 0.4.7
 Summary: Scores every function on complexity times uncovered risk, ranks the worst, and blocks commits that add more.
 Author: Jean-Francois Gagne
 License: MIT
@@ -145,7 +145,7 @@ changing crapkit.
 
 ```
 $ crapkit --version
-crapkit 0.4.6
+crapkit 0.4.7
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -227,6 +227,33 @@ ceiling. It adds no files to your repo, and it needs the crapkit CLI on PATH.
 A repo with no `crapkit.toml` costs a silent sub-50 ms no-op per edit. Other agent
 runtimes have no marketplace: copy `plugin/skills/*` into their skills directory instead.
 
+The hook registers on `Edit|Write`, which is every write that names a file. An agent that
+writes its source through a shell heredoc names none, so a `Bash` event is judged off the
+working tree instead. That half is yours to register, because it costs two
+git spawns per shell call. Add a second PostToolUse entry to your own settings, same
+command, matcher `Bash`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "crapkit claude-hook --protocol 1", "timeout": 20 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The cost is one `git rev-parse --show-toplevel` and one `git status --porcelain -z -uall`
+per shell call in any git repo, whether or not crapkit measures it: about 30 ms together
+on crapkit's own checkout, and more on a bigger tree. What comes back is the dirty or
+untracked `*.py` files written in the last 12 seconds, 25 at most, each judged the way an
+edit is. Python only, so a TypeScript or Go repo pays the two spawns and hears nothing.
+
 ## Languages
 
 14 languages, two coverage parsers. Coverage joins where a parser exists; everything else
@@ -346,7 +373,7 @@ crapkit ships a `.pre-commit-hooks.yaml` declaring `id: crapkit-gate`. In your
 repos:
   - repo: https://github.com/JeanFrancoisGagne/crapkit
     # crapkit's release step rewrites this line to the tag it just cut
-    rev: v0.4.6
+    rev: v0.4.7
     hooks:
       - id: crapkit-gate
 ```
@@ -488,7 +515,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `mutate [--files F ...] [--max-mutants N] [--drop-pool] [--json]` | Diff-scoped mutation testing: flips comparisons, boundary shifts, boolean connectives and boolean literals on changed lines, runs `mutation_command` per mutant, lists survivors. `--files` replaces diff scope with the whole file. `--max-mutants` (default 100) caps the run and the cap warning goes to stderr only, so `mutants` in `--json` is the capped count. Shell and PowerShell files are refused by name on stderr rather than mutated: `<` and `>` are redirections there, not comparisons. With `mutation_workers > 1` the worker worktrees are kept at `.crapkit/mutate-pool/` and re-prepared per run (30.6 s to build four on a 31,459-file repo, 0.46 s to re-prepare them); `--drop-pool` removes them and exits. |
 | `test-scoped FILE ...` | Runs each owning scope's `[crapkit.scoped_tests]` template on the files (quoted, longest-prefix scope wins). A template with no `{files}` runs as written, which is how a scope whose tests live outside its own paths runs its whole suite. Exit code only; a nonzero runner exits 1. |
 | `hook-precommit` | The cc-only gate on staged blobs. No coverage, no snapshot, no repo-wide cache. Exit 6 on a violation. |
-| `claude-hook [--protocol N]` | Reads one Claude Code PostToolUse payload from stdin and judges the file it edited: ccn against the scope ceiling, on functions the edit changed, minus functions a ratchet mark already covers. Advisory only. The edit has landed, nothing is blocked, and `hook-precommit` stays the enforcement point. Exit 2 with three lines on stderr is the only thing it ever says: no `crapkit.toml` above the edited file, an unscoped file, mid-rebase or mid-merge, a `--protocol` other than 1, source that parses to no functions, or any internal failure all exit 0 in silence. Takes no `--repo`, because the root is the first `crapkit.toml` above the edited file and the upward walk stops at a `.git` entry, so a worktree never borrows its parent's config. It opens no snapshot and writes nothing. |
+| `claude-hook [--protocol N]` | Reads one Claude Code PostToolUse payload from stdin and judges the file it edited: ccn against the scope ceiling, on functions the edit changed, minus functions a ratchet mark already covers. Advisory only: the edit has landed, and `hook-precommit` stays the enforcement point. Exit 2 and an advisory on stderr is the only thing it ever says, one block per judged file (a head line, one line per breaching function, a closing line): no `crapkit.toml` above the edited file, an unscoped file, mid-rebase or mid-merge, a `--protocol` other than 1, source that parses to no functions, or any internal failure all exit 0 in silence. The root is the first `crapkit.toml` above the edited file; the walk stops at a `.git` entry, so a worktree never borrows its parent's config. A `Bash` event names no file, so it judges the working tree instead: the dirty or untracked `*.py` files touched in the last 12 seconds, 25 at most, each through the same ladder, and silence for a clean tree or a cwd outside any repo. That half fires only where you register a `Bash` matcher ([The Claude Code plugin](#the-claude-code-plugin)). It opens no snapshot and writes nothing. |
 | `watch [--interval SECONDS] [--cycles N]` | Rescores tracked files as they change (mtime polling, default 2s, subprocess-isolated so a half-saved syntax error never kills the watcher). `--cycles N` polls exactly N times and exits 0; without it the loop runs until ctrl-c. |
 | `mcp` | A dependency-free stdio MCP server (newline JSON-RPC 2.0) exposing nine read-only tools. Every tool shells to the CLI's own `--json` surface, so the MCP view cannot drift from what the CLI reports. Answering from a kept in-process store was benchmarked and rejected: a packet's `source` would go stale behind the edit it describes. See [docs/agent-json.md](docs/agent-json.md#mcp-server). |
 
@@ -616,7 +643,7 @@ crapkit: run 3 is an inventory run (no coverage was measured) and cannot serve a
 | 2 | Usage error from argparse: unknown flag, missing positional. Raised before crapkit's own error handling. |
 | 3 | Config error: `crapkit.toml` missing or unparseable, an unknown language or parser, a lane command the shell that runs it reads as a narrowed suite, a ratchet metric-stamp mismatch ([Upgrading from 0.4.4](#upgrading-from-044)), a `test-scoped` file under no scope or under a scope with no template. |
 | 4 | Git error: not a repository, a baseline commit rewritten out of the history. |
-| 5 | Tool error: lizard not importable, a lane produced no artifact or one that measured a different tree, a lane timed out past its retries, an override alert command failed. A `timeout_seconds` kills the whole process tree, so no orphan suite keeps running behind the failure. |
+| 5 | Tool error: lizard not importable, a lane that produced no artifact, one that measured a different tree, one that measured this tree and reported it in absolute paths (the join is root-relative, so those match nothing either; the refusal names the runner's own switch, `relative_files = true` under `[tool.coverage.run]` for a coveragepy lane, the reporter's `cwd`/`root` option for an istanbul one), a lane that timed out past its retries, an override alert command that failed. A `timeout_seconds` kills the whole process tree, so no orphan suite keeps running behind the failure. |
 | 6 | Gate violation. A function the diff touched is over its ceiling and past any ratchet mark it carries: an edit that leaves a marked function at or under its mark is the debt the repo signed for and is exempt. Also `rescore --gate`, which applies the same rule, and `hook-precommit`, which exempts on the mark's existence instead. |
 | 7 | Ratchet regression the diff never touched. A marked function scores worse than its recorded high-water mark; a touched one past its mark reports 6. |
 | 8 | New test failures against the baseline run. Failures the baseline already had do not count. |
@@ -671,7 +698,8 @@ coverage lane from what the repo already has: a pytest marker file (`pyproject.t
 the matching `run` for the rest), because a bare `python` binds to whichever venv the shell
 has active rather than the one the repo pins — see
 [The interpreter a lane binds to](docs/lanes.md#the-interpreter-a-lane-binds-to). Whatever
-it detects, it also leaves commented templates for the runners it did not find. Every lane
+it detects, it also leaves commented templates for the runners it did not find, and those
+carry the same launcher, so uncommenting one cannot hand the bare `python` back. Every lane
 it writes reports into `.crapkit/cov/`, which is why the `.gitignore` list is so short: see
 [Where artifacts live](docs/lanes.md#where-artifacts-live).
 

{crapkit-0.4.6 → crapkit-0.4.7}/README.md

@@ -106,7 +106,7 @@ changing crapkit.
 
 ```
 $ crapkit --version
-crapkit 0.4.6
+crapkit 0.4.7
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -188,6 +188,33 @@ ceiling. It adds no files to your repo, and it needs the crapkit CLI on PATH.
 A repo with no `crapkit.toml` costs a silent sub-50 ms no-op per edit. Other agent
 runtimes have no marketplace: copy `plugin/skills/*` into their skills directory instead.
 
+The hook registers on `Edit|Write`, which is every write that names a file. An agent that
+writes its source through a shell heredoc names none, so a `Bash` event is judged off the
+working tree instead. That half is yours to register, because it costs two
+git spawns per shell call. Add a second PostToolUse entry to your own settings, same
+command, matcher `Bash`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "crapkit claude-hook --protocol 1", "timeout": 20 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The cost is one `git rev-parse --show-toplevel` and one `git status --porcelain -z -uall`
+per shell call in any git repo, whether or not crapkit measures it: about 30 ms together
+on crapkit's own checkout, and more on a bigger tree. What comes back is the dirty or
+untracked `*.py` files written in the last 12 seconds, 25 at most, each judged the way an
+edit is. Python only, so a TypeScript or Go repo pays the two spawns and hears nothing.
+
 ## Languages
 
 14 languages, two coverage parsers. Coverage joins where a parser exists; everything else
@@ -307,7 +334,7 @@ crapkit ships a `.pre-commit-hooks.yaml` declaring `id: crapkit-gate`. In your
 repos:
   - repo: https://github.com/JeanFrancoisGagne/crapkit
     # crapkit's release step rewrites this line to the tag it just cut
-    rev: v0.4.6
+    rev: v0.4.7
     hooks:
       - id: crapkit-gate
 ```
@@ -449,7 +476,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `mutate [--files F ...] [--max-mutants N] [--drop-pool] [--json]` | Diff-scoped mutation testing: flips comparisons, boundary shifts, boolean connectives and boolean literals on changed lines, runs `mutation_command` per mutant, lists survivors. `--files` replaces diff scope with the whole file. `--max-mutants` (default 100) caps the run and the cap warning goes to stderr only, so `mutants` in `--json` is the capped count. Shell and PowerShell files are refused by name on stderr rather than mutated: `<` and `>` are redirections there, not comparisons. With `mutation_workers > 1` the worker worktrees are kept at `.crapkit/mutate-pool/` and re-prepared per run (30.6 s to build four on a 31,459-file repo, 0.46 s to re-prepare them); `--drop-pool` removes them and exits. |
 | `test-scoped FILE ...` | Runs each owning scope's `[crapkit.scoped_tests]` template on the files (quoted, longest-prefix scope wins). A template with no `{files}` runs as written, which is how a scope whose tests live outside its own paths runs its whole suite. Exit code only; a nonzero runner exits 1. |
 | `hook-precommit` | The cc-only gate on staged blobs. No coverage, no snapshot, no repo-wide cache. Exit 6 on a violation. |
-| `claude-hook [--protocol N]` | Reads one Claude Code PostToolUse payload from stdin and judges the file it edited: ccn against the scope ceiling, on functions the edit changed, minus functions a ratchet mark already covers. Advisory only. The edit has landed, nothing is blocked, and `hook-precommit` stays the enforcement point. Exit 2 with three lines on stderr is the only thing it ever says: no `crapkit.toml` above the edited file, an unscoped file, mid-rebase or mid-merge, a `--protocol` other than 1, source that parses to no functions, or any internal failure all exit 0 in silence. Takes no `--repo`, because the root is the first `crapkit.toml` above the edited file and the upward walk stops at a `.git` entry, so a worktree never borrows its parent's config. It opens no snapshot and writes nothing. |
+| `claude-hook [--protocol N]` | Reads one Claude Code PostToolUse payload from stdin and judges the file it edited: ccn against the scope ceiling, on functions the edit changed, minus functions a ratchet mark already covers. Advisory only: the edit has landed, and `hook-precommit` stays the enforcement point. Exit 2 and an advisory on stderr is the only thing it ever says, one block per judged file (a head line, one line per breaching function, a closing line): no `crapkit.toml` above the edited file, an unscoped file, mid-rebase or mid-merge, a `--protocol` other than 1, source that parses to no functions, or any internal failure all exit 0 in silence. The root is the first `crapkit.toml` above the edited file; the walk stops at a `.git` entry, so a worktree never borrows its parent's config. A `Bash` event names no file, so it judges the working tree instead: the dirty or untracked `*.py` files touched in the last 12 seconds, 25 at most, each through the same ladder, and silence for a clean tree or a cwd outside any repo. That half fires only where you register a `Bash` matcher ([The Claude Code plugin](#the-claude-code-plugin)). It opens no snapshot and writes nothing. |
 | `watch [--interval SECONDS] [--cycles N]` | Rescores tracked files as they change (mtime polling, default 2s, subprocess-isolated so a half-saved syntax error never kills the watcher). `--cycles N` polls exactly N times and exits 0; without it the loop runs until ctrl-c. |
 | `mcp` | A dependency-free stdio MCP server (newline JSON-RPC 2.0) exposing nine read-only tools. Every tool shells to the CLI's own `--json` surface, so the MCP view cannot drift from what the CLI reports. Answering from a kept in-process store was benchmarked and rejected: a packet's `source` would go stale behind the edit it describes. See [docs/agent-json.md](docs/agent-json.md#mcp-server). |
 
@@ -577,7 +604,7 @@ crapkit: run 3 is an inventory run (no coverage was measured) and cannot serve a
 | 2 | Usage error from argparse: unknown flag, missing positional. Raised before crapkit's own error handling. |
 | 3 | Config error: `crapkit.toml` missing or unparseable, an unknown language or parser, a lane command the shell that runs it reads as a narrowed suite, a ratchet metric-stamp mismatch ([Upgrading from 0.4.4](#upgrading-from-044)), a `test-scoped` file under no scope or under a scope with no template. |
 | 4 | Git error: not a repository, a baseline commit rewritten out of the history. |
-| 5 | Tool error: lizard not importable, a lane produced no artifact or one that measured a different tree, a lane timed out past its retries, an override alert command failed. A `timeout_seconds` kills the whole process tree, so no orphan suite keeps running behind the failure. |
+| 5 | Tool error: lizard not importable, a lane that produced no artifact, one that measured a different tree, one that measured this tree and reported it in absolute paths (the join is root-relative, so those match nothing either; the refusal names the runner's own switch, `relative_files = true` under `[tool.coverage.run]` for a coveragepy lane, the reporter's `cwd`/`root` option for an istanbul one), a lane that timed out past its retries, an override alert command that failed. A `timeout_seconds` kills the whole process tree, so no orphan suite keeps running behind the failure. |
 | 6 | Gate violation. A function the diff touched is over its ceiling and past any ratchet mark it carries: an edit that leaves a marked function at or under its mark is the debt the repo signed for and is exempt. Also `rescore --gate`, which applies the same rule, and `hook-precommit`, which exempts on the mark's existence instead. |
 | 7 | Ratchet regression the diff never touched. A marked function scores worse than its recorded high-water mark; a touched one past its mark reports 6. |
 | 8 | New test failures against the baseline run. Failures the baseline already had do not count. |
@@ -632,7 +659,8 @@ coverage lane from what the repo already has: a pytest marker file (`pyproject.t
 the matching `run` for the rest), because a bare `python` binds to whichever venv the shell
 has active rather than the one the repo pins — see
 [The interpreter a lane binds to](docs/lanes.md#the-interpreter-a-lane-binds-to). Whatever
-it detects, it also leaves commented templates for the runners it did not find. Every lane
+it detects, it also leaves commented templates for the runners it did not find, and those
+carry the same launcher, so uncommenting one cannot hand the bare `python` back. Every lane
 it writes reports into `.crapkit/cov/`, which is why the `.gitignore` list is so short: see
 [Where artifacts live](docs/lanes.md#where-artifacts-live).
 

{crapkit-0.4.6 → crapkit-0.4.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "crapkit"
-version = "0.4.6"
+version = "0.4.7"
 description = "Scores every function on complexity times uncovered risk, ranks the worst, and blocks commits that add more."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { text = "MIT" }

{crapkit-0.4.6 → crapkit-0.4.7}/src/crapkit/__init__.py

@@ -1,2 +1,2 @@
 """crapkit: deterministic CRAP-score framework."""
-__version__ = "0.4.6"
+__version__ = "0.4.7"

{crapkit-0.4.6 → crapkit-0.4.7}/src/crapkit/cli/admin.py

@@ -350,9 +350,16 @@ def _warn_missing_pytest_cov(lanes: tuple) -> None:
     """The first-run trap, caught where it starts. The py lane shells out to
     `pytest --cov`, and the --cov flags come from pytest-cov — a package of the
     REPO's interpreter, so a crapkit dependency could only ever cover installs
-    sharing the suite's venv. Probe the python the lane will actually run and
-    say the fix now, instead of `coverage` exiting 5 with a lane log the first
-    run has to decode."""
+    sharing the suite's venv. Say the fix now, instead of `coverage` exiting 5
+    with a lane log the first run has to decode.
+
+    Only a lane whose pytest segment starts with a python is probed at all. A
+    lane an environment manager heads is not: `uv run` and its siblings create
+    or sync the project environment before running anything, so probing one
+    would provision an environment to ask a question about it. Such a lane
+    still earns the two notes ahead of the probe, a manager PATH does not carry
+    and a first word the shell cannot start.
+    """
     for lane in _probed_lanes(lanes):
         note = _lane_first_run_note(lane)
         if note:
@@ -386,9 +393,12 @@ def cmd_init(args: argparse.Namespace) -> int:
         raise ConfigError(_no_scopes_reason(root))
     # A config whose lanes are all commented out scores every function no-lane,
     # so a fresh repo cannot rank anything until somebody hand-writes a lane.
-    lanes = detect_lanes(_present_markers(root), _package_json(root),
-                         interpreter=_interpreter(root))
-    text = starter_toml(scopes, lanes)
+    # The interpreter goes to both: a repo with no pytest marker file gets no
+    # lane to read it back off, and its commented template is what the reader
+    # uncomments.
+    interpreter = _interpreter(root)
+    lanes = detect_lanes(_present_markers(root), _package_json(root), interpreter=interpreter)
+    text = starter_toml(scopes, lanes, interpreter=interpreter)
     load_config_text(text)  # self-check: never write a config crapkit cannot read back
     toml_path.write_text(text, encoding="utf-8", newline="\n")
     _print_init_summary(scopes, lanes)

{crapkit-0.4.6 → crapkit-0.4.7}/src/crapkit/cli/claude_hook.py

@@ -6,6 +6,12 @@ measures, over its ceiling, carrying no ratchet mark. Everything else is exit 0
 and silence: the malformed payload, the unmeasured repo, the half-typed source
 and the internal exception included.
 
+An Edit, Write or MultiEdit event names its file in `tool_input.file_path` and
+is judged as that one file. A Bash event carries `tool_input.command` instead —
+a heredoc or `python - <<'PY'` writes source no file_path ever names — so it
+falls back to the working tree: the changed *.py files fresh enough for this
+command to have plausibly written, each through the same per-file ladder.
+
 That silence is the design, not laziness. On PostToolUse a nonzero exit that is
 not 2 is invisible and a 2 is text the model has to read, so a hook that fires
 where crapkit measures nothing is either useless or unbearable; 47.5% of the
@@ -34,6 +40,8 @@ from __future__ import annotations
 import json
 import subprocess
 import sys
+import time
+from collections.abc import Iterator
 from pathlib import Path
 
 PROTOCOL = "1"
@@ -45,6 +53,15 @@ _SEQUENCING_MARKERS = ("rebase-merge", "rebase-apply", "MERGE_HEAD", "CHERRY_PIC
 # root walk into a filesystem scan.
 _MAX_LEVELS = 64
 
+# The Bash fallback's freshness window: a dirty *.py whose mtime is older than
+# this was not written by the command this event reports, so advising it again
+# would repeat the advisory on every later Bash call in the session.
+_FRESH_WINDOW_SECONDS = 12
+
+# And its bound: PostToolUse waits this process out, so a huge dirty tree is a
+# stall, not a license to judge everything in it.
+_MAX_COMMAND_FILES = 25
+
 
 def cmd_claude_hook(args) -> int:
     """The whole subcommand, wrapped in the catch-all the contract promises.
@@ -62,12 +79,19 @@ def cmd_claude_hook(args) -> int:
 def _advise(args, stream) -> int:
     """The ladder. Each rung that fails to advance exits 0 and says nothing."""
     payload = _payload(stream)
-    edited = _edited_file(payload)
-    if not edited:
+    if args.protocol != PROTOCOL:
         return 0
-    path = _edited_path(payload, edited)
+    edited = _edited_file(payload)
+    if edited:
+        return _judge_path(_edited_path(payload, edited))
+    return _advise_command(payload)
+
+
+def _judge_path(path: Path) -> int:
+    """Root discovery and judgement for one absolute file path: the tail every
+    event shape shares once it holds a file to answer for."""
     root = _repo_root(path.parent)
-    if root is None or _sequencing(root) or args.protocol != PROTOCOL:
+    if root is None or _sequencing(root):
         return 0
     return _judge(root, path.relative_to(root).as_posix())
 
@@ -110,6 +134,105 @@ def _edited_path(payload: dict, edited: str) -> Path:
     return Path(payload.get("cwd") or ".") / path
 
 
+def _command_event(payload: dict) -> bool:
+    """Whether this is a PostToolUse for a tool that wrote through the shell.
+
+    Bash carries `tool_input.command` and never `file_path`, so protocol 1 has
+    no single file to judge and reads the working tree instead. Shape-based like
+    `_edited_file`: NotebookEdit and friends carry no `command` and fall out
+    here rather than needing a rule.
+    """
+    if payload.get("hook_event_name") != "PostToolUse":
+        return False
+    tool_input = payload.get("tool_input")
+    return isinstance(tool_input, dict) and isinstance(tool_input.get("command"), str)
+
+
+def _advise_command(payload: dict) -> int:
+    """The Bash fallback: judge the fresh *.py files the working tree changed.
+
+    A shell heredoc or `python - <<'PY'` writes source no Edit event ever names,
+    so judging only `file_path` left every Bash-written breach unadvised. Each
+    file takes the same per-file ladder an Edit takes, so a file under no
+    crapkit root, mid-sequencing, unscoped or marked stays silent, and exit 2
+    means what it always means.
+    """
+    if not _command_event(payload):
+        return 0
+    top = _repo_top(Path(payload.get("cwd") or "."))
+    if top is None:
+        return 0
+    verdicts = [_judge_path(path) for path in _fresh_python(top)]
+    return 2 if 2 in verdicts else 0
+
+
+def _repo_top(cwd: Path) -> Path | None:
+    """The git working-tree top above the command's own cwd, or None outside any
+    repo. The event's `cwd` is where the command ran, and `status --porcelain`
+    names every file relative to this top whatever directory asks."""
+    if not cwd.is_dir():
+        return None
+    res = subprocess.run(["git", "rev-parse", "--show-toplevel"], cwd=cwd,
+                         capture_output=True, text=True, encoding="utf-8",
+                         errors="replace")
+    top = res.stdout.strip()
+    return Path(top) if res.returncode == 0 and top else None
+
+
+def _fresh_python(top: Path) -> list[Path]:
+    """Absolute paths of the changed *.py files this command plausibly wrote:
+    dirty or untracked per git, on disk, and with an mtime inside the window."""
+    cutoff = time.time() - _FRESH_WINDOW_SECONDS
+    fresh: list[Path] = []
+    for status, rel in _status_records(_porcelain(top)):
+        if _judgeable(status, rel) and _fresh(top / rel, cutoff):
+            fresh.append(top / rel)
+        if len(fresh) == _MAX_COMMAND_FILES:
+            break
+    return fresh
+
+
+def _porcelain(top: Path) -> str:
+    """`git status --porcelain -z` over the whole tree, or "" when git cannot
+    answer. -uall, because a heredoc that creates a new DIRECTORY of source
+    would otherwise arrive as one collapsed `?? newdir/` row naming no file."""
+    res = subprocess.run(["git", "status", "--porcelain", "-z", "-uall"], cwd=top,
+                         capture_output=True, text=True, encoding="utf-8",
+                         errors="replace")
+    return res.stdout if res.returncode == 0 else ""
+
+
+def _status_records(text: str) -> Iterator[tuple[str, str]]:
+    """(XY status, new-side path) per `--porcelain -z` record.
+
+    -z is NUL-separated and never quoted, so a non-ASCII path arrives as
+    itself. A rename or copy record carries the original name in a second
+    field, consumed here so it cannot be read as the next record's status.
+    """
+    fields = text.split("\0")
+    i = 0
+    while i < len(fields) and fields[i]:
+        status = fields[i][:2]
+        yield status, fields[i][3:]
+        i += 2 if status[:1] in ("R", "C") else 1
+
+
+def _judgeable(status: str, rel: str) -> bool:
+    """A *.py with content on disk. A deletion in either column has nothing
+    left to judge, and every other language stays the commit gate's business:
+    only Python is cheap enough to analyze per shell call."""
+    return rel.endswith(".py") and "D" not in status
+
+
+def _fresh(path: Path, cutoff: float) -> bool:
+    """mtime inside the window — the approximation of "this command wrote it".
+    A path status names but disk lacks is not fresh, whatever the record said."""
+    try:
+        return path.stat().st_mtime >= cutoff
+    except OSError:
+        return False
+
+
 def _repo_root(start: Path) -> Path | None:
     """The crapkit root above an edited file, or None when there is none.
 

{crapkit-0.4.6 → crapkit-0.4.7}/src/crapkit/lanes.py

@@ -57,6 +57,11 @@ _CAUSE_WIDTH = 200
 # scrolls off above it.
 _DIAGNOSTIC = re.compile(r"\s*(E\s|Traceback \(most recent call last\)|\w*(Error|Exception): )")
 
+# The banner `_log_header` writes before every attempt after the first. A whole
+# line, so a log line that quotes those words mid-text is output and not a
+# boundary.
+_ATTEMPT_BANNER = re.compile(r"--- attempt \d+ ---")
+
 
 def _log_lines(log_path: Path) -> list[str]:
     if not log_path.is_file():
@@ -94,8 +99,18 @@ def _cut_cause(line: str) -> str:
     return line if len(line) <= _CAUSE_WIDTH else "..." + line[-(_CAUSE_WIDTH - 3):]
 
 
+def _last_attempt(lines: list[str]) -> list[str]:
+    """The final attempt's lines. A retried lane appends every attempt to one
+    log, so a scan of the whole file can hoist the reason a superseded attempt
+    died for and stand it in front of the last attempt's own output, with
+    nothing marking the boundary. Attempt 1 writes no banner, so a log holding
+    none is one attempt and comes back whole."""
+    banners = [i for i, line in enumerate(lines) if _ATTEMPT_BANNER.fullmatch(line)]
+    return lines[banners[-1] + 1:] if banners else lines
+
+
 def _cause_lines(lines: list[str], tail: list[str]) -> list[str]:
-    """The last lines anywhere in the log that name a failure, when the tail
+    """The last lines of the final attempt that name a failure, when the tail
     carries none. Nothing when the tail already says why — repeating it would
     spend the message on the same words twice."""
     if any(_DIAGNOSTIC.match(line) for line in tail):
@@ -110,7 +125,7 @@ def _log_tail(log_path: Path) -> str:
     ellipsis between them marks the output they skipped over."""
     lines = _log_lines(log_path)
     tail = _tail_lines(lines, _TAIL_BUDGET)
-    cause = _cause_lines(lines, tail)
+    cause = _cause_lines(_last_attempt(lines), tail)
     return "\n".join([*cause, "...", *tail] if cause else tail)
 
 
@@ -373,14 +388,49 @@ def _read_and_parse(lane: Lane, root: Path,
 
 _SAMPLE_PATHS = 3
 
-# A path the runner could not write relative to this checkout: absolute, drive
+# A path the runner did not write relative to this checkout: absolute, drive
 # lettered, or climbing out of the tree. Both parsers rebase a file INSIDE the
-# repo to a repo-relative path, so one that is not is a file somewhere else.
+# repo to a repo-relative path, so one that is not either came from elsewhere or
+# was spelled absolutely by a runner told to spell it that way. Which of the two
+# is decided against the root, below; the shape alone does not say.
 _DRIVE = re.compile(r"[A-Za-z]:[\\/]")
 
 
+def _is_absolute(path: str) -> bool:
+    """Absolute in either spelling: a POSIX root, or a drive letter."""
+    return path.startswith("/") or _DRIVE.match(path) is not None
+
+
 def _escapes_repo(path: str) -> bool:
-    return path.startswith(("/", "../")) or _DRIVE.match(path) is not None
+    return _is_absolute(path) or path.startswith("../")
+
+
+def _resolved(path: str) -> str:
+    """One spelling, so both sides of the root comparison can be compared at
+    all: symlinks followed, separators normalized, and the case folded where the
+    filesystem folds it (`normcase` is identity on POSIX, which does not).
+
+    A path whose tail does not exist still normalizes; only a name the platform
+    cannot express at all raises, and that is answered as written."""
+    try:
+        resolved = str(Path(path).resolve())
+    except (OSError, ValueError):
+        return os.path.normcase(path)
+    return os.path.normcase(resolved)
+
+
+def _under(root: str, path: str) -> bool:
+    """Both already `_resolved`. The root itself counts as under itself."""
+    return path == root or path.startswith(root.rstrip(os.sep) + os.sep)
+
+
+def _lands_in_checkout(root: str, path: str) -> bool:
+    """An absolute path naming a file this checkout holds after all.
+
+    `../` is excluded on purpose: it is relative to the runner's working
+    directory, which the artifact never records, so there is nothing to resolve
+    it against and no honest way to place it."""
+    return _is_absolute(path) and _under(root, _resolved(path))
 
 
 def _as_reported(lane: Lane, path: str) -> str:
@@ -413,13 +463,26 @@ def _unreached_paths(lane: Lane, coverage: dict, scope_paths: dict) -> tuple[str
     return tuple(dict.fromkeys(m.path for m in matchers))
 
 
-def _outside_paths(lane: Lane, coverage: dict) -> list[str]:
-    """The measured files that are not in this checkout, spelled the way the
-    artifact spells them."""
+def _escaped_paths(lane: Lane, coverage: dict) -> list[str]:
+    """The measured files the runner did not write relative to this checkout,
+    spelled the way the artifact spells them."""
     reported = (_as_reported(lane, path) for path in coverage)
     return sorted(path for path in reported if _escapes_repo(path))
 
 
+def _split_escaped(root: Path, escaped: list[str]) -> tuple[list[str], list[str]]:
+    """(paths from another tree, absolute paths that land under this root).
+
+    The root resolves once, and every path resolves the same way, or a symlinked
+    or short-name checkout compares unequal to its own files."""
+    resolved_root = _resolved(str(root))
+    elsewhere: list[str] = []
+    inside: list[str] = []
+    for path in escaped:
+        (inside if _lands_in_checkout(resolved_root, path) else elsewhere).append(path)
+    return elsewhere, inside
+
+
 def _sample(paths) -> str:
     """A few of them and a count of the rest. A lane scoped to forty declared
     paths listed all forty, which pushed the sentence saying what to do off the
@@ -447,11 +510,25 @@ _ISTANBUL_FIX = ("The reader rebases every path under this checkout's root, so t
 _COVERAGEPY_MISS = "or the runner reports paths this lane needs path_prefix to rebase"
 _ISTANBUL_MISS = "or the suite measured a part of the tree these scopes do not name"
 
+# And the third case: this tree, spelled absolutely. Neither fix above applies —
+# the environment is right and path_prefix only ever PREPENDS — so the knob is
+# the runner's own, and each reader has a different one.
+_COVERAGEPY_ABSOLUTE_FIX = ("Make the runner write relative paths: `relative_files = true` "
+                            "under `[tool.coverage.run]` in pyproject.toml, or "
+                            "`[run] relative_files = true` in .coveragerc, then rerun the lane")
+_ISTANBUL_ABSOLUTE_FIX = ("The reader strips this checkout's root off every measured path "
+                          "literally, so the reporter spelled that root some other way: point "
+                          "it at this checkout with its own cwd/root option, then rerun the lane")
+
 
 def _wrong_tree_fix(lane: Lane) -> str:
     return _COVERAGEPY_FIX if lane.parser == "coveragepy" else _ISTANBUL_FIX
 
 
+def _absolute_fix(lane: Lane) -> str:
+    return _COVERAGEPY_ABSOLUTE_FIX if lane.parser == "coveragepy" else _ISTANBUL_ABSOLUTE_FIX
+
+
 def _unmeasured_reading(lane: Lane) -> str:
     return _COVERAGEPY_MISS if lane.parser == "coveragepy" else _ISTANBUL_MISS
 
@@ -471,6 +548,14 @@ def _wrong_tree_message(lane: Lane, coverage: dict, declared, outside: list[str]
             f"paths like {_sample(outside)}. {_wrong_tree_fix(lane)}")
 
 
+def _absolute_message(lane: Lane, coverage: dict, declared, inside: list[str]) -> str:
+    return (f"{_zero_overlap(lane, coverage, declared)}, and {len(inside)} of them written "
+            f"as absolute paths that DO sit under this checkout — {lane.artifact} measured "
+            f"this tree and spelled it absolutely, and the join is on root-relative paths, "
+            f"so it still matches nothing and every function in those scopes would score "
+            f"untested; it reports paths like {_sample(inside)}. {_absolute_fix(lane)}")
+
+
 def _unmeasured_message(lane: Lane, coverage: dict, declared) -> str:
     reports = f"; it measured {_sample(coverage)}" if coverage else ""
     return (f"{_zero_overlap(lane, coverage, declared)}, so every function in those "
@@ -478,7 +563,8 @@ def _unmeasured_message(lane: Lane, coverage: dict, declared) -> str:
             f"{_unmeasured_reading(lane)}")
 
 
-def _judge_artifact_scope(lane: Lane, coverage: dict, scope_paths: dict | None) -> None:
+def _judge_artifact_scope(lane: Lane, coverage: dict, scope_paths: dict | None,
+                          root: Path) -> None:
     """Say something when a lane's artifact reaches none of the scopes it claims.
 
     Coverage joins on path and nothing else, so such an artifact contributes
@@ -488,18 +574,29 @@ def _judge_artifact_scope(lane: Lane, coverage: dict, scope_paths: dict | None)
     answer. Two worktrees of one branch reach it quietly: a venv whose editable
     install points at the other checkout makes coverage.py measure that tree.
 
-    Two verdicts, because zero overlap has two readings and the paths tell them
-    apart. Measured files OUTSIDE this checkout can only be another tree, and
-    that fails the lane. In-tree paths that simply miss the scopes are the
-    greenfield shape as well — a suite that imports none of the scoped source
-    yet, which SHOULD score untested — so that one warns and scores on.
+    Three verdicts, because zero overlap has three readings and the paths tell
+    them apart, against the root. Measured files OUTSIDE the root can only be
+    another tree, and that fails the lane. Absolute paths that resolve UNDER it
+    are this tree with the runner spelling every path absolutely: the join is
+    root-relative, so it matches nothing either, and that fails the lane too —
+    with the runner's own knob named, because the venv advice above is not the
+    cause and path_prefix only prepends. In-tree relative paths that simply miss
+    the scopes are the greenfield shape as well — a suite that imports none of
+    the scoped source yet, which SHOULD score untested — so that one warns and
+    scores on.
+
+    A mixed artifact is another tree. A path from somewhere else can only have
+    come from somewhere else, and the absolute in-tree ones are what the same
+    wrong run reports about the files it did reach.
     """
     declared = _unreached_paths(lane, coverage, scope_paths or {})
     if not declared:
         return
-    outside = _outside_paths(lane, coverage)
-    if outside:
-        raise ToolError(_wrong_tree_message(lane, coverage, declared, outside))
+    elsewhere, inside = _split_escaped(root, _escaped_paths(lane, coverage))
+    if elsewhere:
+        raise ToolError(_wrong_tree_message(lane, coverage, declared, elsewhere))
+    if inside:
+        raise ToolError(_absolute_message(lane, coverage, declared, inside))
     print(f"crapkit: {_unmeasured_message(lane, coverage, declared)}", file=sys.stderr)
 
 
@@ -630,7 +727,7 @@ def run_lane(root: Path, lane: Lane, *, reuse_artifact: bool = False,
     _refuse_container_python(lane)
     exit_code, seconds = _run_or_reuse(root, lane, facts, scope_paths, reuse_artifact)
     coverage, digest = _read_and_parse(lane, root, _artifact_path(root, lane))
-    _judge_artifact_scope(lane, coverage, scope_paths)
+    _judge_artifact_scope(lane, coverage, scope_paths, root)
     provenance = {
         "artifact_sha256": digest,
         "exit_code": exit_code,

{crapkit-0.4.6 → crapkit-0.4.7}/src/crapkit/scaffold.py

@@ -303,9 +303,13 @@ def _live_lanes(lanes: tuple[LaneSpec, ...],
     return lines, covered
 
 
+# The python in the coveragepy template is a placeholder for the same reason
+# the scoped-tests entries carry one: what a reader uncomments has to be the
+# command init would have written live. A repo whose lockfile pins `uv run`
+# read a bare `python` here and got the environment bug one uncomment later.
 _TEMPLATES = {
     "coveragepy": ("# [[lane]]", '# name = "py"',
-                   '# command = "python -m pytest --cov --cov-branch '
+                   '# command = "{python} -m pytest --cov --cov-branch '
                    f'--cov-report=json:{_PY_ARTIFACT} --junitxml={_PY_RESULTS}"',
                    f'# artifact = "{_PY_ARTIFACT}"',
                    f'# results_artifact = "{_PY_RESULTS}"', '# parser = "coveragepy"'),
@@ -350,16 +354,21 @@ def _pytest_lane_launcher(lanes: tuple[LaneSpec, ...]) -> str | None:
     return None
 
 
-def python_launcher(lanes: tuple[LaneSpec, ...]) -> str:
-    """The python invocation the detected pytest lane already settled on.
+def python_launcher(lanes: tuple[LaneSpec, ...], fallback: str = _DEFAULT_PYTHON) -> str:
+    """The python invocation the detected pytest lane already settled on, and
+    `fallback` when no detected lane runs pytest.
 
     Read back off the lane rather than passed in beside it, so the scoped-tests
     entry runs the suite the way the coverage lane runs it and the two cannot
     drift: a `uv run python` lane with a bare `python` step 4 would measure one
     environment and test another.
+
+    A repo with no pytest marker file has no lane to read, and every python
+    line init writes for it is commented. `fallback` is what init would have
+    run had there been one, so those lines uncomment into the same environment.
     """
     launcher = _pytest_lane_launcher(lanes)
-    return _DEFAULT_PYTHON if launcher is None else launcher
+    return fallback if launcher is None else launcher
 
 
 def _scoped_test_command(languages: tuple[str, ...], launcher: str) -> str:
@@ -423,7 +432,14 @@ def _commented_block(rest: dict[str, tuple[str, ...]], has_live: bool,
     return header + _scoped_entry_lines(rest, False, launcher)
 
 
-def _template_lines(covered: set[str], scopes: dict[str, tuple[str, ...]]) -> list[str]:
+def _template_stanza(parser: str, launcher: str) -> list[str]:
+    """One commented lane template, with the python it names filled in. The js
+    templates carry no placeholder, so they come back as written."""
+    return [line.replace("{python}", launcher) for line in _TEMPLATES[parser]]
+
+
+def _template_lines(covered: set[str], scopes: dict[str, tuple[str, ...]],
+                    launcher: str = _DEFAULT_PYTHON) -> list[str]:
     """Commented lane templates for the parsers no live lane covers.
 
     None at all when every scope is cc-only. Neither parser reads any language
@@ -437,21 +453,25 @@ def _template_lines(covered: set[str], scopes: dict[str, tuple[str, ...]]) -> li
     lines: list[str] = []
     for parser in sorted(_TEMPLATES):
         if parser not in covered:
-            lines += [*_TEMPLATES[parser], '# scopes = ["<your-scope>"]', ""]
+            lines += [*_template_stanza(parser, launcher), '# scopes = ["<your-scope>"]', ""]
     if not lines:
         return []
     return ["# Declare one [[lane]] per coverage command, then run `crapkit coverage`.", *lines]
 
 
-def starter_toml(scopes: dict[str, tuple[str, ...]], lanes: tuple[LaneSpec, ...] = ()) -> str:
+def starter_toml(scopes: dict[str, tuple[str, ...]], lanes: tuple[LaneSpec, ...] = (),
+                 *, interpreter: str = _DEFAULT_PYTHON) -> str:
+    """The starter crapkit.toml. `interpreter` is the python a committed config
+    on this repo can call, the lockfile's manager prefix included; every python
+    line the file holds names it, commented templates as much as live lanes."""
     lines = ["[crapkit]", "target = 6", ""]
     for name, languages in scopes.items():
         lines += _scope_stanza(name, languages)
     lines += _exclude_stanza()
     live, covered = _live_lanes(lanes, scopes)
-    return "\n".join(lines + live + _template_lines(covered, scopes)
-                     + _scoped_tests_stub(scopes, _confirmed_languages(lanes),
-                                          python_launcher(lanes)))
+    launcher = python_launcher(lanes, interpreter)
+    return "\n".join(lines + live + _template_lines(covered, scopes, launcher)
+                     + _scoped_tests_stub(scopes, _confirmed_languages(lanes), launcher))
 
 
 _STORE_IGNORE = ".crapkit/"

{crapkit-0.4.6 → crapkit-0.4.7/src/crapkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crapkit
-Version: 0.4.6
+Version: 0.4.7
 Summary: Scores every function on complexity times uncovered risk, ranks the worst, and blocks commits that add more.
 Author: Jean-Francois Gagne
 License: MIT
@@ -145,7 +145,7 @@ changing crapkit.
 
 ```
 $ crapkit --version
-crapkit 0.4.6
+crapkit 0.4.7
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -227,6 +227,33 @@ ceiling. It adds no files to your repo, and it needs the crapkit CLI on PATH.
 A repo with no `crapkit.toml` costs a silent sub-50 ms no-op per edit. Other agent
 runtimes have no marketplace: copy `plugin/skills/*` into their skills directory instead.
 
+The hook registers on `Edit|Write`, which is every write that names a file. An agent that
+writes its source through a shell heredoc names none, so a `Bash` event is judged off the
+working tree instead. That half is yours to register, because it costs two
+git spawns per shell call. Add a second PostToolUse entry to your own settings, same
+command, matcher `Bash`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "crapkit claude-hook --protocol 1", "timeout": 20 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The cost is one `git rev-parse --show-toplevel` and one `git status --porcelain -z -uall`
+per shell call in any git repo, whether or not crapkit measures it: about 30 ms together
+on crapkit's own checkout, and more on a bigger tree. What comes back is the dirty or
+untracked `*.py` files written in the last 12 seconds, 25 at most, each judged the way an
+edit is. Python only, so a TypeScript or Go repo pays the two spawns and hears nothing.
+
 ## Languages
 
 14 languages, two coverage parsers. Coverage joins where a parser exists; everything else
@@ -346,7 +373,7 @@ crapkit ships a `.pre-commit-hooks.yaml` declaring `id: crapkit-gate`. In your
 repos:
   - repo: https://github.com/JeanFrancoisGagne/crapkit
     # crapkit's release step rewrites this line to the tag it just cut
-    rev: v0.4.6
+    rev: v0.4.7
     hooks:
       - id: crapkit-gate
 ```
@@ -488,7 +515,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `mutate [--files F ...] [--max-mutants N] [--drop-pool] [--json]` | Diff-scoped mutation testing: flips comparisons, boundary shifts, boolean connectives and boolean literals on changed lines, runs `mutation_command` per mutant, lists survivors. `--files` replaces diff scope with the whole file. `--max-mutants` (default 100) caps the run and the cap warning goes to stderr only, so `mutants` in `--json` is the capped count. Shell and PowerShell files are refused by name on stderr rather than mutated: `<` and `>` are redirections there, not comparisons. With `mutation_workers > 1` the worker worktrees are kept at `.crapkit/mutate-pool/` and re-prepared per run (30.6 s to build four on a 31,459-file repo, 0.46 s to re-prepare them); `--drop-pool` removes them and exits. |
 | `test-scoped FILE ...` | Runs each owning scope's `[crapkit.scoped_tests]` template on the files (quoted, longest-prefix scope wins). A template with no `{files}` runs as written, which is how a scope whose tests live outside its own paths runs its whole suite. Exit code only; a nonzero runner exits 1. |
 | `hook-precommit` | The cc-only gate on staged blobs. No coverage, no snapshot, no repo-wide cache. Exit 6 on a violation. |
-| `claude-hook [--protocol N]` | Reads one Claude Code PostToolUse payload from stdin and judges the file it edited: ccn against the scope ceiling, on functions the edit changed, minus functions a ratchet mark already covers. Advisory only. The edit has landed, nothing is blocked, and `hook-precommit` stays the enforcement point. Exit 2 with three lines on stderr is the only thing it ever says: no `crapkit.toml` above the edited file, an unscoped file, mid-rebase or mid-merge, a `--protocol` other than 1, source that parses to no functions, or any internal failure all exit 0 in silence. Takes no `--repo`, because the root is the first `crapkit.toml` above the edited file and the upward walk stops at a `.git` entry, so a worktree never borrows its parent's config. It opens no snapshot and writes nothing. |
+| `claude-hook [--protocol N]` | Reads one Claude Code PostToolUse payload from stdin and judges the file it edited: ccn against the scope ceiling, on functions the edit changed, minus functions a ratchet mark already covers. Advisory only: the edit has landed, and `hook-precommit` stays the enforcement point. Exit 2 and an advisory on stderr is the only thing it ever says, one block per judged file (a head line, one line per breaching function, a closing line): no `crapkit.toml` above the edited file, an unscoped file, mid-rebase or mid-merge, a `--protocol` other than 1, source that parses to no functions, or any internal failure all exit 0 in silence. The root is the first `crapkit.toml` above the edited file; the walk stops at a `.git` entry, so a worktree never borrows its parent's config. A `Bash` event names no file, so it judges the working tree instead: the dirty or untracked `*.py` files touched in the last 12 seconds, 25 at most, each through the same ladder, and silence for a clean tree or a cwd outside any repo. That half fires only where you register a `Bash` matcher ([The Claude Code plugin](#the-claude-code-plugin)). It opens no snapshot and writes nothing. |
 | `watch [--interval SECONDS] [--cycles N]` | Rescores tracked files as they change (mtime polling, default 2s, subprocess-isolated so a half-saved syntax error never kills the watcher). `--cycles N` polls exactly N times and exits 0; without it the loop runs until ctrl-c. |
 | `mcp` | A dependency-free stdio MCP server (newline JSON-RPC 2.0) exposing nine read-only tools. Every tool shells to the CLI's own `--json` surface, so the MCP view cannot drift from what the CLI reports. Answering from a kept in-process store was benchmarked and rejected: a packet's `source` would go stale behind the edit it describes. See [docs/agent-json.md](docs/agent-json.md#mcp-server). |
 
@@ -616,7 +643,7 @@ crapkit: run 3 is an inventory run (no coverage was measured) and cannot serve a
 | 2 | Usage error from argparse: unknown flag, missing positional. Raised before crapkit's own error handling. |
 | 3 | Config error: `crapkit.toml` missing or unparseable, an unknown language or parser, a lane command the shell that runs it reads as a narrowed suite, a ratchet metric-stamp mismatch ([Upgrading from 0.4.4](#upgrading-from-044)), a `test-scoped` file under no scope or under a scope with no template. |
 | 4 | Git error: not a repository, a baseline commit rewritten out of the history. |
-| 5 | Tool error: lizard not importable, a lane produced no artifact or one that measured a different tree, a lane timed out past its retries, an override alert command failed. A `timeout_seconds` kills the whole process tree, so no orphan suite keeps running behind the failure. |
+| 5 | Tool error: lizard not importable, a lane that produced no artifact, one that measured a different tree, one that measured this tree and reported it in absolute paths (the join is root-relative, so those match nothing either; the refusal names the runner's own switch, `relative_files = true` under `[tool.coverage.run]` for a coveragepy lane, the reporter's `cwd`/`root` option for an istanbul one), a lane that timed out past its retries, an override alert command that failed. A `timeout_seconds` kills the whole process tree, so no orphan suite keeps running behind the failure. |
 | 6 | Gate violation. A function the diff touched is over its ceiling and past any ratchet mark it carries: an edit that leaves a marked function at or under its mark is the debt the repo signed for and is exempt. Also `rescore --gate`, which applies the same rule, and `hook-precommit`, which exempts on the mark's existence instead. |
 | 7 | Ratchet regression the diff never touched. A marked function scores worse than its recorded high-water mark; a touched one past its mark reports 6. |
 | 8 | New test failures against the baseline run. Failures the baseline already had do not count. |
@@ -671,7 +698,8 @@ coverage lane from what the repo already has: a pytest marker file (`pyproject.t
 the matching `run` for the rest), because a bare `python` binds to whichever venv the shell
 has active rather than the one the repo pins — see
 [The interpreter a lane binds to](docs/lanes.md#the-interpreter-a-lane-binds-to). Whatever
-it detects, it also leaves commented templates for the runners it did not find. Every lane
+it detects, it also leaves commented templates for the runners it did not find, and those
+carry the same launcher, so uncommenting one cannot hand the bare `python` back. Every lane
 it writes reports into `.crapkit/cov/`, which is why the `.gitignore` list is so short: see
 [Where artifacts live](docs/lanes.md#where-artifacts-live).