crapkit 0.4.2__tar.gz → 0.4.3__tar.gz

{crapkit-0.4.2/src/crapkit.egg-info → crapkit-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crapkit
-Version: 0.4.2
+Version: 0.4.3
 Summary: Scores every function on complexity times uncovered risk, ranks the worst, and blocks commits that add more.
 Author: Jean-Francois Gagne
 License: MIT
@@ -116,7 +116,7 @@ changing crapkit.
 
 ```
 $ crapkit --version
-crapkit 0.4.2
+crapkit 0.4.3
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -124,6 +124,22 @@ source checkout. Every subcommand accepts `--repo PATH` (default: the current di
 so you never have to `cd` into the repo you are scoring. The flag goes after the
 subcommand; [Subcommands](#subcommands) shows both orders.
 
+### Upgrading on Windows
+
+`uv tool upgrade crapkit`, and `pip install -U` into a tool venv, fail with `os error 32`
+("The process cannot access the file because it is being used by another process") while a
+crapkit MCP server is live: an agent session spawns `crapkit.exe mcp`, which holds the
+launcher, and Windows will not overwrite a running executable. The venv upgrades before
+that copy fails, so `crapkit --version` already reports the new version and the launcher is
+the only stale piece. Quit the agent session and rerun the upgrade, or rename the locked
+exe aside (Windows allows renaming a running one) and copy the new one in; the `.old` file
+goes at the next reboot.
+
+```
+mv ~/.local/bin/crapkit.exe ~/.local/bin/crapkit.exe.old
+cp %APPDATA%/uv/tools/crapkit/Scripts/crapkit.exe ~/.local/bin/crapkit.exe
+```
+
 ## The Claude Code plugin
 
 ```
@@ -247,7 +263,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.2
+    rev: v0.4.3
     hooks:
       - id: crapkit-gate
 ```
@@ -321,11 +337,11 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `doctor [--show-files] [--json] [--tune] [--plugin-root PATH]` | Checks the config still describes the repo: unknown keys (with the accepted spellings), zero-file scopes, tracked source no scope claims, scopes no lane covers, lane cwds and commands that no longer resolve, lizard importable, oversized files. It WARNs on a lane writing its artifact at the repo root, a committed hook under `core.hooksPath` that is not executable in the index, a directory whose functions are all `untested` while its tests exist, and a scope a lane measures with no `[crapkit.scoped_tests]` template behind it, which is the loop's step 4 with nothing to run. `--tune` prints suggested parallelism knobs and writes nothing. `--plugin-root PATH` reads no repo at all: it checks an installed [plugin](plugin/) against this CLI on both version and hook `--protocol`, one line per disagreement and silence when they agree. See [docs/agent-json.md](docs/agent-json.md#doctor---json). |
 | `inventory [--db PATH] [--export PATH] [--json]` | One lizard pass over every in-scope file into a SQLite snapshot run, cached by content hash. `--db` is the only way to point crapkit at a store outside `.crapkit/`, and only this command accepts it. |
 | `coverage [--lane NAME] [--reuse-artifacts] [--reuse-unchanged] [--export PATH] [--sarif PATH] [--github] [--json]` | Runs the lanes, joins branch coverage onto a fresh inventory, writes a scored run. A failed lane is recorded, not fatal: its scopes fall back to `no-lane` and the run is typed `partial`, so it can never serve as a baseline. See [docs/lanes.md](docs/lanes.md). |
-| `verify [--baseline ID \| --base REF \| --baseline-tsv PATH] [--emit-baseline PATH] [--override REASON] [--reuse-artifacts] [--reuse-unchanged] [--sarif PATH] [--github] [--json]` | The full verdict against the trusted baseline: gate on touched functions, ratchet, no new test failures, optional diff-coverage ceiling. The three baseline selectors are mutually exclusive; `--baseline ID` also bypasses the taint rule ([The trusted baseline](#the-trusted-baseline)), and `--baseline-tsv` reads a commit-stamped file so a fresh clone verifies with no store. Findings a dirty tree produced are tagged `dirty` and counted apart. |
+| `verify [--baseline ID \| --base REF \| --baseline-tsv PATH] [--emit-baseline PATH] [--override REASON] [--reuse-artifacts] [--reuse-unchanged] [--no-tighten] [--sarif PATH] [--github] [--json]` | The full verdict against the trusted baseline: gate on touched functions, ratchet, no new test failures, optional diff-coverage ceiling. The three baseline selectors are mutually exclusive; `--baseline ID` also bypasses the taint rule ([The trusted baseline](#the-trusted-baseline)), and `--baseline-tsv` reads a commit-stamped file so a fresh clone verifies with no store. `--no-tighten` passes the verdict without rewriting the ratchet. Findings a dirty tree produced are tagged `dirty` and counted apart. |
 | `worklist [--top N] [--scope NAME] [--batches N] [--json]` | The risk map: every admitted function ranked by `ccn * churn weight`, floored by `worklist_floor`, with hot simple code and anything over its ceiling admitted past that floor. It ranks finished rows and `no-lane` rows too, marked `ok` and `no-lane`, so it never empties; `next-item` carries the stop condition. `--scope NAME` (repeatable) is exact, not a substring. `--batches N` **adds** a `batches[]` view cutting the active list into at most N file-disjoint batches with co-changing files kept together; the normal keys stay. |
 | `next-item [--top N] [--exclude FRAG] [--scope NAME] [--claim]` | The actionable queue as JSON, with churn, budget estimates and uncovered lines. Same run and same admission floor as `worklist`, a different view of it: `no-lane` rows are skipped and counted in `skipped_no_lane`, and what is left is ranked by `crap` descending rather than by risk, so the item it hands out is often not the worklist's first row. `--exclude FRAG` (repeatable) skips items whose path or function name contains FRAG; `--scope NAME` (repeatable) is exact, not a substring. `--claim` holds what it hands out so a second session skips it. `stale` is true when the ranked run's commit is not HEAD, the same field `worklist` carries. Every item carries a `handle`: the bare identifier, or `(anonymous)#N` for a function with no name, which is the name form that survives the edit the item asks for. |
 | `claims [list \| release PATH NAME \| release --all] [--json]` | The open claims, and the way to hand one back without waiting for a verify. `release` takes the bare identifier, the whole long name, or the `handle` the claim was taken under, which is the only one that picks out a single `(anonymous)` claim. |
-| `brief FILE NAME [--batch N] [--json]` | The start-editing packet for one function: its own `source` text, every function in the file, the scored row and the scope ceiling, the ratchet mark and what the gate will bind on, uncovered lines, duplication twins, file churn, coupling partners, the config's notes, and the literal commands for the rest of the loop. Plus `handle`, `remedy` and the same `est_splits` / `est_uncovered_paths` the queue prints, and a `commands.refresh` that writes a run (`refresh_writes_run`) rather than re-reading the stale one. `NAME` takes the bare identifier, the long name `next-item` printed, the function's start line, or `(anonymous)#N` for a function printed `(anonymous)`, counting the file's anonymous functions from the top. `--batch N` drops the positionals and emits `packets[]` instead: the top N of the queue, built from one read of the store. |
+| `brief FILE NAME [--batch N] [--json]` | The start-editing packet for one function: its own `source` text, every function in the file, the scored row and the scope ceiling, the ratchet mark and what the gate will bind on, uncovered lines, duplication twins, file churn, coupling partners, the config's notes, and the literal commands for the rest of the loop. Plus `handle`, `remedy` and the same `est_splits` / `est_uncovered_paths` the queue prints, and a `commands.refresh` that writes a run (`refresh_writes_run`) rather than re-reading the stale one. `NAME` takes the bare identifier, the long name `next-item` printed, the function's start line, `(anonymous)#N` for a function printed `(anonymous)` counting the file's anonymous functions from the top, or `NAME#2` for the second of several functions a file gives one name to. `--batch N` drops the positionals and emits `packets[]` instead: the top N of the queue, built from one read of the store. |
 | `explain FILE NAME [--history] [--tests] [--json]` | A function's score across runs plus its mark. `NAME` resolves exact first: a function whose bare identifier or long name is exactly `NAME` wins, and only when nothing matches exactly does it fall back to a prefix match, so `route` explains `route` rather than every `route_*` beside it. `--history` adds the commits that touched it (`git log -L`), each carrying its message `body`, `--tests` the tests that covered it, which needs coverage.py contexts turned on ([recipe](docs/lanes.md#test-attribution-for-explain---tests)). `--json` emits the same content as one `schema` 1 object. |
 | `rescore FILE ... [--gate] [--json]` | Fresh complexity for named files over the latest run's stale coverage, joined by name. Advisory: it writes no run. `--gate` applies the pre-commit hook's policy to the same selection the hook uses (functions the tree changed since HEAD), minus functions a ratchet mark already covers, and exits 6. |
 | `ratchet seed \| prune \| merge \| move \| report [--enforce] [--json]` | The mark lifecycle: seed new debt, prune gone code (a mark whose file git renamed follows it), merge as a git driver, move re-paths marks, report reads burn-down from the file's own git history. See [docs/ratchet.md](docs/ratchet.md). |
@@ -334,7 +350,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `trend [--json]` | Totals per trusted run: functions, over-target count, CRAP load, average, per-scope rollup. |
 | `digest [--alert]` | The delta between the two newest runs with identical lane sets. Silent when nothing changed. `--alert` pipes the body to `alert_command` on stdin. Plain lines, never JSON. |
 | `report [--out PATH]` | One self-contained HTML page written to `.crapkit/report.html` (or `--out PATH`, repo-relative), with the path printed on stdout. It renders what `worklist --json` and `trend --json` already answer at their defaults: the ranked worklist capped at `worklist_top`, the per-scope grades off the newest run, the trend series, and a banner naming every stale lane. It measures nothing and opens no network connection. Per-function CRAP and coverage are absent because no repo-wide payload carries them; each row prints the `crapkit explain` call that does. |
-| `duplication [--min-lines N] [--similarity F] [--top N] [--json]` | Near-duplicate functions by normalized line shingles with containment scoring. Defaults: `--min-lines 8`, `--similarity 0.8`, `--top 50`. `--top` truncates the list. |
+| `duplication [--min-lines N] [--similarity F] [--top N] [--json]` | Near-duplicate functions by normalized line shingles with containment scoring. Defaults: `--min-lines 8`, `--similarity 0.8`, `--top 50`. `--top` truncates the list. A function and a function nested inside it never pair: their spans nest, they score 1.0 by construction, and nobody can deduplicate a factory from its own closure. |
 | `coupling [--min-support N] [--min-confidence F] [--top N] [--json]` | File pairs that keep landing in the same commits. Defaults: `--min-support 5` shared commits, `--min-confidence 0.5` max-direction ratio, `--top 50`. Bulk commits never couple pairs, and a young repo returns nothing at the default support. |
 | `mutate [--files F ...] [--max-mutants N] [--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. |
 | `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. |
@@ -412,7 +428,9 @@ baseline**. `crapkit runs list` marks which one that is today.
 never qualifies, and neither does a `partial` run (a lane failed, so some scope fell back
 to `no-lane`) nor a `hook` override record, which carries no scored rows at all. In `runs
 list`, `verdict=-` marks a run that produces no verdict rather than one that failed: only
-`verify` renders a verdict.
+`verify` renders a verdict. Three readers ask this one question and get this one answer:
+the baseline pick here, `ratchet seed` and `prune`, and the tighten damping that compares a
+mark against the same commit's previous run.
 
 **What advances it.** Any qualifying run. `coverage` writes one wherever HEAD is, so a
 dashboard cron advances the baseline exactly as CI does. A passing `verify` advances it

{crapkit-0.4.2 → crapkit-0.4.3}/README.md

@@ -83,7 +83,7 @@ changing crapkit.
 
 ```
 $ crapkit --version
-crapkit 0.4.2
+crapkit 0.4.3
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -91,6 +91,22 @@ source checkout. Every subcommand accepts `--repo PATH` (default: the current di
 so you never have to `cd` into the repo you are scoring. The flag goes after the
 subcommand; [Subcommands](#subcommands) shows both orders.
 
+### Upgrading on Windows
+
+`uv tool upgrade crapkit`, and `pip install -U` into a tool venv, fail with `os error 32`
+("The process cannot access the file because it is being used by another process") while a
+crapkit MCP server is live: an agent session spawns `crapkit.exe mcp`, which holds the
+launcher, and Windows will not overwrite a running executable. The venv upgrades before
+that copy fails, so `crapkit --version` already reports the new version and the launcher is
+the only stale piece. Quit the agent session and rerun the upgrade, or rename the locked
+exe aside (Windows allows renaming a running one) and copy the new one in; the `.old` file
+goes at the next reboot.
+
+```
+mv ~/.local/bin/crapkit.exe ~/.local/bin/crapkit.exe.old
+cp %APPDATA%/uv/tools/crapkit/Scripts/crapkit.exe ~/.local/bin/crapkit.exe
+```
+
 ## The Claude Code plugin
 
 ```
@@ -214,7 +230,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.2
+    rev: v0.4.3
     hooks:
       - id: crapkit-gate
 ```
@@ -288,11 +304,11 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `doctor [--show-files] [--json] [--tune] [--plugin-root PATH]` | Checks the config still describes the repo: unknown keys (with the accepted spellings), zero-file scopes, tracked source no scope claims, scopes no lane covers, lane cwds and commands that no longer resolve, lizard importable, oversized files. It WARNs on a lane writing its artifact at the repo root, a committed hook under `core.hooksPath` that is not executable in the index, a directory whose functions are all `untested` while its tests exist, and a scope a lane measures with no `[crapkit.scoped_tests]` template behind it, which is the loop's step 4 with nothing to run. `--tune` prints suggested parallelism knobs and writes nothing. `--plugin-root PATH` reads no repo at all: it checks an installed [plugin](plugin/) against this CLI on both version and hook `--protocol`, one line per disagreement and silence when they agree. See [docs/agent-json.md](docs/agent-json.md#doctor---json). |
 | `inventory [--db PATH] [--export PATH] [--json]` | One lizard pass over every in-scope file into a SQLite snapshot run, cached by content hash. `--db` is the only way to point crapkit at a store outside `.crapkit/`, and only this command accepts it. |
 | `coverage [--lane NAME] [--reuse-artifacts] [--reuse-unchanged] [--export PATH] [--sarif PATH] [--github] [--json]` | Runs the lanes, joins branch coverage onto a fresh inventory, writes a scored run. A failed lane is recorded, not fatal: its scopes fall back to `no-lane` and the run is typed `partial`, so it can never serve as a baseline. See [docs/lanes.md](docs/lanes.md). |
-| `verify [--baseline ID \| --base REF \| --baseline-tsv PATH] [--emit-baseline PATH] [--override REASON] [--reuse-artifacts] [--reuse-unchanged] [--sarif PATH] [--github] [--json]` | The full verdict against the trusted baseline: gate on touched functions, ratchet, no new test failures, optional diff-coverage ceiling. The three baseline selectors are mutually exclusive; `--baseline ID` also bypasses the taint rule ([The trusted baseline](#the-trusted-baseline)), and `--baseline-tsv` reads a commit-stamped file so a fresh clone verifies with no store. Findings a dirty tree produced are tagged `dirty` and counted apart. |
+| `verify [--baseline ID \| --base REF \| --baseline-tsv PATH] [--emit-baseline PATH] [--override REASON] [--reuse-artifacts] [--reuse-unchanged] [--no-tighten] [--sarif PATH] [--github] [--json]` | The full verdict against the trusted baseline: gate on touched functions, ratchet, no new test failures, optional diff-coverage ceiling. The three baseline selectors are mutually exclusive; `--baseline ID` also bypasses the taint rule ([The trusted baseline](#the-trusted-baseline)), and `--baseline-tsv` reads a commit-stamped file so a fresh clone verifies with no store. `--no-tighten` passes the verdict without rewriting the ratchet. Findings a dirty tree produced are tagged `dirty` and counted apart. |
 | `worklist [--top N] [--scope NAME] [--batches N] [--json]` | The risk map: every admitted function ranked by `ccn * churn weight`, floored by `worklist_floor`, with hot simple code and anything over its ceiling admitted past that floor. It ranks finished rows and `no-lane` rows too, marked `ok` and `no-lane`, so it never empties; `next-item` carries the stop condition. `--scope NAME` (repeatable) is exact, not a substring. `--batches N` **adds** a `batches[]` view cutting the active list into at most N file-disjoint batches with co-changing files kept together; the normal keys stay. |
 | `next-item [--top N] [--exclude FRAG] [--scope NAME] [--claim]` | The actionable queue as JSON, with churn, budget estimates and uncovered lines. Same run and same admission floor as `worklist`, a different view of it: `no-lane` rows are skipped and counted in `skipped_no_lane`, and what is left is ranked by `crap` descending rather than by risk, so the item it hands out is often not the worklist's first row. `--exclude FRAG` (repeatable) skips items whose path or function name contains FRAG; `--scope NAME` (repeatable) is exact, not a substring. `--claim` holds what it hands out so a second session skips it. `stale` is true when the ranked run's commit is not HEAD, the same field `worklist` carries. Every item carries a `handle`: the bare identifier, or `(anonymous)#N` for a function with no name, which is the name form that survives the edit the item asks for. |
 | `claims [list \| release PATH NAME \| release --all] [--json]` | The open claims, and the way to hand one back without waiting for a verify. `release` takes the bare identifier, the whole long name, or the `handle` the claim was taken under, which is the only one that picks out a single `(anonymous)` claim. |
-| `brief FILE NAME [--batch N] [--json]` | The start-editing packet for one function: its own `source` text, every function in the file, the scored row and the scope ceiling, the ratchet mark and what the gate will bind on, uncovered lines, duplication twins, file churn, coupling partners, the config's notes, and the literal commands for the rest of the loop. Plus `handle`, `remedy` and the same `est_splits` / `est_uncovered_paths` the queue prints, and a `commands.refresh` that writes a run (`refresh_writes_run`) rather than re-reading the stale one. `NAME` takes the bare identifier, the long name `next-item` printed, the function's start line, or `(anonymous)#N` for a function printed `(anonymous)`, counting the file's anonymous functions from the top. `--batch N` drops the positionals and emits `packets[]` instead: the top N of the queue, built from one read of the store. |
+| `brief FILE NAME [--batch N] [--json]` | The start-editing packet for one function: its own `source` text, every function in the file, the scored row and the scope ceiling, the ratchet mark and what the gate will bind on, uncovered lines, duplication twins, file churn, coupling partners, the config's notes, and the literal commands for the rest of the loop. Plus `handle`, `remedy` and the same `est_splits` / `est_uncovered_paths` the queue prints, and a `commands.refresh` that writes a run (`refresh_writes_run`) rather than re-reading the stale one. `NAME` takes the bare identifier, the long name `next-item` printed, the function's start line, `(anonymous)#N` for a function printed `(anonymous)` counting the file's anonymous functions from the top, or `NAME#2` for the second of several functions a file gives one name to. `--batch N` drops the positionals and emits `packets[]` instead: the top N of the queue, built from one read of the store. |
 | `explain FILE NAME [--history] [--tests] [--json]` | A function's score across runs plus its mark. `NAME` resolves exact first: a function whose bare identifier or long name is exactly `NAME` wins, and only when nothing matches exactly does it fall back to a prefix match, so `route` explains `route` rather than every `route_*` beside it. `--history` adds the commits that touched it (`git log -L`), each carrying its message `body`, `--tests` the tests that covered it, which needs coverage.py contexts turned on ([recipe](docs/lanes.md#test-attribution-for-explain---tests)). `--json` emits the same content as one `schema` 1 object. |
 | `rescore FILE ... [--gate] [--json]` | Fresh complexity for named files over the latest run's stale coverage, joined by name. Advisory: it writes no run. `--gate` applies the pre-commit hook's policy to the same selection the hook uses (functions the tree changed since HEAD), minus functions a ratchet mark already covers, and exits 6. |
 | `ratchet seed \| prune \| merge \| move \| report [--enforce] [--json]` | The mark lifecycle: seed new debt, prune gone code (a mark whose file git renamed follows it), merge as a git driver, move re-paths marks, report reads burn-down from the file's own git history. See [docs/ratchet.md](docs/ratchet.md). |
@@ -301,7 +317,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 | `trend [--json]` | Totals per trusted run: functions, over-target count, CRAP load, average, per-scope rollup. |
 | `digest [--alert]` | The delta between the two newest runs with identical lane sets. Silent when nothing changed. `--alert` pipes the body to `alert_command` on stdin. Plain lines, never JSON. |
 | `report [--out PATH]` | One self-contained HTML page written to `.crapkit/report.html` (or `--out PATH`, repo-relative), with the path printed on stdout. It renders what `worklist --json` and `trend --json` already answer at their defaults: the ranked worklist capped at `worklist_top`, the per-scope grades off the newest run, the trend series, and a banner naming every stale lane. It measures nothing and opens no network connection. Per-function CRAP and coverage are absent because no repo-wide payload carries them; each row prints the `crapkit explain` call that does. |
-| `duplication [--min-lines N] [--similarity F] [--top N] [--json]` | Near-duplicate functions by normalized line shingles with containment scoring. Defaults: `--min-lines 8`, `--similarity 0.8`, `--top 50`. `--top` truncates the list. |
+| `duplication [--min-lines N] [--similarity F] [--top N] [--json]` | Near-duplicate functions by normalized line shingles with containment scoring. Defaults: `--min-lines 8`, `--similarity 0.8`, `--top 50`. `--top` truncates the list. A function and a function nested inside it never pair: their spans nest, they score 1.0 by construction, and nobody can deduplicate a factory from its own closure. |
 | `coupling [--min-support N] [--min-confidence F] [--top N] [--json]` | File pairs that keep landing in the same commits. Defaults: `--min-support 5` shared commits, `--min-confidence 0.5` max-direction ratio, `--top 50`. Bulk commits never couple pairs, and a young repo returns nothing at the default support. |
 | `mutate [--files F ...] [--max-mutants N] [--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. |
 | `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. |
@@ -379,7 +395,9 @@ baseline**. `crapkit runs list` marks which one that is today.
 never qualifies, and neither does a `partial` run (a lane failed, so some scope fell back
 to `no-lane`) nor a `hook` override record, which carries no scored rows at all. In `runs
 list`, `verdict=-` marks a run that produces no verdict rather than one that failed: only
-`verify` renders a verdict.
+`verify` renders a verdict. Three readers ask this one question and get this one answer:
+the baseline pick here, `ratchet seed` and `prune`, and the tighten damping that compares a
+mark against the same commit's previous run.
 
 **What advances it.** Any qualifying run. `coverage` writes one wherever HEAD is, so a
 dashboard cron advances the baseline exactly as CI does. A passing `verify` advances it

{crapkit-0.4.2 → crapkit-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "crapkit"
-version = "0.4.2"
+version = "0.4.3"
 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.2 → crapkit-0.4.3}/src/crapkit/__init__.py

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

{crapkit-0.4.2 → crapkit-0.4.3}/src/crapkit/analyze.py

@@ -160,10 +160,11 @@ _NAMES_SHOWN = 5
 def _colliding_names(records: list[FunctionRecord]) -> list[str]:
     """Names this file gives to more than one function, in first-seen order.
 
-    Anonymous functions are exempt. lizard calls every one of them
+    Anonymous functions are exempt from the line. lizard calls every one of them
     `(anonymous)`, so a file with two arrow callbacks collides by construction
-    and a warning would name nothing anyone could act on; `packet.handles`
-    answers that collision with the `(anonymous)#N` ordinal instead.
+    and the line would name nothing anyone could act on. They take the same
+    ordinal keys as any other twin; `packet.handles` already addresses them as
+    `(anonymous)#N`.
     """
     seen: set[str] = set()
     colliding: dict[str, None] = {}
@@ -174,23 +175,26 @@ def _colliding_names(records: list[FunctionRecord]) -> list[str]:
     return list(colliding)
 
 
-def _warn_on_collisions(rel_path: str, records: list[FunctionRecord]) -> None:
-    """One stderr line for a file whose records cannot all reach the ratchet.
+def _note_twin_keys(rel_path: str, records: list[FunctionRecord]) -> None:
+    """One stderr line for a file that gives one name to more than one function.
 
-    A mark is keyed on (path, long_name), and so is the row a run writes, so the
-    last function under a colliding name is the only one marked and the only one
-    gated. C makes this ordinary: both arms of an `#ifdef` fork are textually
-    present, so a platform shim defines the same function twice in one file.
-    Python makes it ordinary too, because a method's long_name carries no class.
-    Neither is fixable here — the ratchet cannot key on a span, which drifts with
-    every edit — so the loss is announced rather than silent.
+    Information, not a warning. Until 0.4.2 it was the second: a mark keyed on
+    (path, long_name) meant one twin owned the key and the rest were neither
+    marked nor gated, which is the loss this announced. `keys` ends that by
+    giving each twin its own ordinal, so the line now says what a reader will
+    see in `crapkit-ratchet.tsv` and nothing is lost.
+
+    Still printed, because a `#2` appearing in a committed marks file is
+    otherwise unexplained. C makes the shape ordinary — both arms of an `#ifdef`
+    fork are textually present — and so does Python, whose method long_names
+    carry no class.
     """
     names = _colliding_names(records)
     if not names:
         return
-    print(f"crapkit: {rel_path} defines {_listed(names)} more than once; the ratchet keys "
-          f"on (path, long_name) and keeps the last, so the earlier ones are neither "
-          f"marked nor gated", file=sys.stderr)
+    print(f"crapkit: {rel_path} defines {_listed(names)} more than once; each one takes "
+          f"its own ratchet key — the first as written, later ones suffixed #2, #3 in "
+          f"file order", file=sys.stderr)
 
 
 def _listed(names: list[str]) -> str:
@@ -201,7 +205,7 @@ def _listed(names: list[str]) -> str:
 
 def _file_records(rel_path: str, functions) -> list[FunctionRecord]:
     records = [_record(rel_path, fn) for fn in functions]
-    _warn_on_collisions(rel_path, records)
+    _note_twin_keys(rel_path, records)
     return records
 
 

{crapkit-0.4.2 → crapkit-0.4.3}/src/crapkit/cli/__init__.py

@@ -109,6 +109,7 @@ _OWNER = {
     "_group_files_by_scope": "verifying",
     "_guard_ratchet_stamp": "verifying",
     "_handle": "queue",
+    "_held_marks": "verifying",
     "_hook_handlers": "admin",
     "_hook_modes": "admin",
     "_hook_protocols": "admin",
@@ -160,6 +161,8 @@ _OWNER = {
     "_no_line_message": "queue",
     "_no_match_message": "queue",
     "_no_scopes_reason": "admin",
+    "_no_tighten_line": "verifying",
+    "_no_twin_message": "queue",
     "_note_marked_staged": "verifying",
     "_note_stale_staged": "verifying",
     "_open_store": "_shared",
@@ -176,6 +179,7 @@ _OWNER = {
     "_policy_findings": "ratchet_cmds",
     "_present_markers": "admin",
     "_present_on_disk": "scoring",
+    "_prior_crap": "verifying",
     "_print_batches": "queue",
     "_print_brief": "queue",
     "_print_brief_context": "queue",

{crapkit-0.4.2 → crapkit-0.4.3}/src/crapkit/cli/claude_hook.py

@@ -154,7 +154,7 @@ def _judge(root: Path, rel: str) -> int:
     records = _records(root, rel)
     ranges = _changed(root, rel, diff.communicate()[0])
     breaches, ceiling = _verdict(cfg, in_scope, rel, records, ranges)
-    return _report(root, cfg, rel, breaches, ceiling)
+    return _report(root, cfg, rel, breaches, ceiling, _keys(records))
 
 
 def _config(root: Path):
@@ -260,11 +260,21 @@ def _answerable(over: list, ranges) -> list:
     return [rec for rec in over if _touches(rec, ranges)]
 
 
-def _report(root: Path, cfg, rel: str, breaches: list, ceiling: int) -> int:
+def _keys(records: list) -> dict:
+    """The file's ratchet keys, built from every record rather than the breaching
+    ones: the ordinal counts same-named functions in file order."""
+    from ..keys import key_names
+
+    return key_names(records)
+
+
+def _report(root: Path, cfg, rel: str, breaches: list, ceiling: int, keys: dict) -> int:
     """Rung 9. stdout stays empty whatever happens: protocol 1 reserves it for a
     future JSON channel, and Claude Code parses stdout JSON on exit 0."""
+    from ..keys import key_of
+
     marked = _marks_for(root / cfg.ratchet_file, rel)
-    unmarked = [rec for rec in breaches if rec.long_name not in marked]
+    unmarked = [rec for rec in breaches if key_of(keys, rec)[1] not in marked]
     if not unmarked:
         return 0
     for line in _advisory_lines(rel, unmarked, ceiling):
@@ -273,7 +283,7 @@ def _report(root: Path, cfg, rel: str, breaches: list, ceiling: int) -> int:
 
 
 def _marks_for(marks_path: Path, rel: str) -> set[str]:
-    """The function names one file carries ratchet marks for.
+    """The ratchet KEY names one file carries marks for, `#N` ordinals included.
 
     Existence, not the numeric high-water rule `verify` applies: crap needs
     coverage, coverage needs the store, and the store stays closed. A mark is a

{crapkit-0.4.2 → crapkit-0.4.3}/src/crapkit/cli/parser.py

@@ -286,6 +286,8 @@ def build_parser() -> argparse.ArgumentParser:
                      help="rerun only lanes whose scope files changed since their artifact; reuse the rest")
     ver.add_argument("--override", default=None, metavar="REASON",
                      help="audited exemption for gate violations: alert + ratchet debt + snapshot record")
+    ver.add_argument("--no-tighten", action="store_true",
+                     help="pass the verdict without rewriting the ratchet; marks stay where they are")
     ver.add_argument("--sarif", default=None, metavar="PATH",
                      help="write gate/ratchet findings as SARIF 2.1.0, relative to the repo")
     ver.add_argument("--github", action="store_true",

{crapkit-0.4.2 → crapkit-0.4.3}/src/crapkit/cli/queue.py

@@ -13,6 +13,7 @@ from .. import packet
 from ..churn_cache import load_churn
 from ..errors import ConfigError, CrapkitError
 from ..gitio import head_commit
+from ..keys import key_names, key_of, split_ordinal
 from ..store import SnapshotStore
 from ..uncovered import load_uncovered
 from ..worklist import admission, build_worklist, sql_floor
@@ -443,31 +444,50 @@ def _no_handle_message(path: str, name: str, rows: list) -> str:
 
 
 def _pick_function(path: str, rows: list, name: str):
-    """The one row `name` names, or an error listing what the file does hold.
-
-    Twins (one long_name at two spans) are ONE candidate, not an ambiguity: the
-    worst-scoring twin is what a burn-down item means, the same rule the ratchet
-    and the verdict use. The -start term keeps verify.worst_twins' tie-break —
-    equal-scoring twins resolve to the one that appears first in the file.
-    """
+    """The one row `name` names, or an error listing what the file does hold."""
     at_line = _row_at_line(path, rows, name)
     if at_line is not None:
         return at_line
     by_handle = _row_by_handle(path, rows, name)
     if by_handle is not None:
         return by_handle
-    matched = _matching_rows(rows, name)
+    wanted, ordinal = split_ordinal(name)
+    matched = _matching_rows(rows, wanted)
     candidates = sorted({r.long_name for r in matched})
     if len(candidates) != 1:
         raise CrapkitError(_no_match_message(path, name, rows, candidates))
-    return max(matched, key=lambda r: (r.crap, -r.start))
+    return _one_of(path, matched, name, wanted, ordinal)
+
+
+def _one_of(path: str, matched: list, name: str, wanted: str, ordinal: int):
+    """Which of the same-named rows NAME meant.
+
+    A bare name means the burn-down item, and that is the worst twin — the rule
+    the ratchet, the verdict and `next-item` all run. The -start term is the
+    tie-break: equal-scoring twins resolve to the one that appears first.
+
+    `name#2` means the second of them in file order, which is the function its
+    own ratchet key `name#2` is about. That is how a session addresses the twin
+    a bare name does not pick.
+    """
+    if wanted == name:
+        return max(matched, key=lambda r: (r.crap, -r.start))
+    ordered = sorted(matched, key=lambda r: r.start)
+    if ordinal > len(ordered):
+        raise CrapkitError(_no_twin_message(path, name, wanted, len(ordered)))
+    return ordered[ordinal - 1]
+
+
+def _no_twin_message(path: str, name: str, wanted: str, held: int) -> str:
+    return (f"no {name} in {path} in the latest scored run"
+            f" — it holds {held} function(s) named {wanted!r}")
 
 
-def _brief_mark(entries: list | None, row) -> float | None:
+def _brief_mark(entries: list | None, key: tuple[str, str]) -> float | None:
     """The committed mark on this function, or None when the repo carries none."""
     from ..ratchet import mark_for
 
-    return None if entries is None else mark_for(entries, row.path, row.long_name)
+    return None if entries is None else mark_for(entries, *key)
 
 
 def _brief_churn(churn: dict, path: str) -> dict | None:
@@ -505,6 +525,7 @@ class _BriefLoader:
         self.latest = latest
         self._whole_repo: dict = {}
         self._scored_files: dict = {}
+        self._file_keys: dict = {}
         self._attempts: dict = {}
 
     def _once(self, key: str, build):
@@ -555,9 +576,20 @@ class _BriefLoader:
             self._scored_files[path] = self.store.read_scored_file(self.latest["id"], path)
         return self._scored_files[path]
 
+    def key(self, row) -> tuple[str, str]:
+        """The row's ratchet key, counted over the whole file it lives in.
+
+        Cached per path beside the rows it is built from: a batch of packets
+        about one file would otherwise recount its ordinals per packet.
+        """
+        if row.path not in self._file_keys:
+            self._file_keys[row.path] = key_names(self.scored_file(row.path))
+        return key_of(self._file_keys[row.path], row)
+
     def mark(self, row) -> float | None:
         return _brief_mark(self._once("marks",
-                                      lambda: _ratchet_entries(self.root, self.cfg)), row)
+                                      lambda: _ratchet_entries(self.root, self.cfg)),
+                           self.key(row))
 
     def mark_age(self, row, mark: float | None) -> int | None:
         """How long the mark has stood. No mark, no history read: reading the
@@ -565,7 +597,7 @@ class _BriefLoader:
         if mark is None:
             return None
         return packet.mark_age_days(self._once("mark_events", self._read_mark_events),
-                                    (row.path, row.long_name))
+                                    self.key(row))
 
     def _read_mark_events(self) -> list:
         from ..gitio import file_log_patches

{crapkit-0.4.2 → crapkit-0.4.3}/src/crapkit/cli/ratchet_cmds.py

@@ -12,11 +12,40 @@ from ..store import SnapshotStore
 from ._shared import _load_ratchet_or_die, _load_repo_config, _open_store, _print_json
 
 
-def _latest_full_run(store: SnapshotStore) -> dict:
-    runs = [r for r in store.list_runs() if r["kind"] in ("coverage", "verify")]
-    if not runs:
-        raise CrapkitError("no full coverage run to work from — run `crapkit coverage` first")
-    return runs[-1]
+def _is_failed_verify(run: dict) -> bool:
+    return run["kind"] == "verify" and run["verdict_ok"] is False
+
+
+def _skipped_failed_verifies(runs: list[dict], chosen_id: int) -> list[dict]:
+    """The failed verifies newer than the run this seed or prune settled on."""
+    return [r for r in runs if r["id"] > chosen_id and _is_failed_verify(r)]
+
+
+def _latest_full_run(store: SnapshotStore) -> tuple[dict, list[dict]]:
+    """The newest TRUSTED run to work from, and the failed verifies passed over.
+
+    `verify`'s own rule, shared: a failed verify never serves as a baseline
+    because it can carry the scores of a red tree, and the failure is visible in
+    the same run. Seeding from one signs debt at values verify itself will not
+    accept as a comparison point. Before this, seed took the newest run whose
+    kind was coverage or verify and never read the verdict (#16).
+    """
+    from ..store import is_trusted
+
+    runs = store.list_runs()
+    trusted = [r for r in runs if is_trusted(r)]
+    if not trusted:
+        raise CrapkitError("no trusted full run to work from — run `crapkit coverage` first "
+                           "(failed verifies and hook runs never serve as baselines)")
+    return trusted[-1], _skipped_failed_verifies(runs, trusted[-1]["id"])
+
+
+def _skip_note(skipped: list[dict]) -> str:
+    """Why the line names an older run than the newest one in the store."""
+    if not skipped:
+        return ""
+    ids = ", ".join(str(r["id"]) for r in skipped)
+    return f", skipped failed verify {'runs' if len(skipped) > 1 else 'run'} {ids}"
 
 
 def _merge_stamp(texts: list[str]) -> str:
@@ -108,7 +137,7 @@ def _print_ratchet_report(report: dict, violations: list, ratchet_file: str) ->
 
 
 def _working_marks(root: Path, ratchet_file: str) -> dict:
-    """The marks on disk, keyed (path, long_name) -> crap. Ages come from the
+    """The marks on disk, keyed (path, key name) -> crap. Ages come from the
     file's git history, but which marks are OPEN is a question about now, and a
     seed prints "added 1" long before anybody commits the TSV."""
     entries = _load_ratchet_or_die(root / ratchet_file, ratchet_file)
@@ -156,7 +185,7 @@ def cmd_ratchet(args: argparse.Namespace) -> int:
     if args.action == "move":  # a hand-declared rename needs no run to follow
         return _ratchet_move(root, cfg, args.files)
     store = _open_store(root)
-    latest = _latest_full_run(store)
+    latest, skipped = _latest_full_run(store)
     fresh = store.read_scored(latest["id"])
     ratchet_path = root / cfg.ratchet_file
     prior = _load_ratchet_or_die(ratchet_path, cfg.ratchet_file)
@@ -168,5 +197,5 @@ def cmd_ratchet(args: argparse.Namespace) -> int:
         entries, note = _pruned(root, store, prior, fresh)
     ratchet_path.write_text(dump_ratchet(entries), encoding="utf-8", newline="\n")
     print(f"{cfg.ratchet_file}: {note} — {len(entries)} mark(s) vs run {latest['id']} "
-          f"({latest['commit'][:11]})")
+          f"({latest['commit'][:11]}){_skip_note(skipped)}")
     return 0

{crapkit-0.4.2 → crapkit-0.4.3}/src/crapkit/cli/reports.py

@@ -318,6 +318,10 @@ class _ExplainCtx(NamedTuple):
     uncovered: MissingLines
     ratchet: list | None
     contexts: dict
+    # The twin NAME selected: 1 for a bare name, 2 for `f#2`. It is the ordinal
+    # in the ratchet key, and `(anonymous)#2` reads the same way — that handle
+    # and that twin's key are the same string.
+    ordinal: int = 1
 
 
 def cmd_explain(args: argparse.Namespace) -> int:
@@ -338,19 +342,24 @@ def cmd_explain(args: argparse.Namespace) -> int:
 
 
 def _explain_ctx(root: Path, cfg, store: SnapshotStore, args) -> _ExplainCtx:
+    from ..keys import split_ordinal
+
     runs = [r for r in store.list_runs() if r["kind"] != "hook"]
     return _ExplainCtx(root, args.path, runs[-1]["id"] if runs else None,
                        load_uncovered(root, cfg), _ratchet_entries(root, cfg),
-                       _contexts_for_path(root, cfg, args.path) if args.tests else {})
+                       _contexts_for_path(root, cfg, args.path) if args.tests else {},
+                       split_ordinal(args.name)[1])
 
 
 def _explain_payload(ctx: _ExplainCtx, store: SnapshotStore, args, long_name: str) -> dict:
     """One function's whole packet. The span is looked up once and passed down:
     dark lines, --history and --tests all want the same line range."""
+    from ..keys import key_name
+
     span = _latest_span(store, ctx.run_id, ctx.path, long_name)
     out = {"long_name": long_name,
            "history": store.function_history(ctx.path, long_name),
-           **_mark_fields(ctx.ratchet, ctx.path, long_name),
+           **_mark_fields(ctx.ratchet, ctx.path, key_name(long_name, ctx.ordinal)),
            **_dark_fields(ctx.uncovered, ctx.path, span)}
     if args.history:
         out.update(_commits_fields(ctx.root, ctx.path, span))
@@ -384,7 +393,11 @@ def _latest_span(store: SnapshotStore, run_id: int | None, path: str, long_name:
 
 def _mark_fields(ratchet: list | None, path: str, long_name: str) -> dict:
     """null and a note when the repo carries no marks file: an unmarked function
-    and a repo with no ratchet both read as null, and they want different moves."""
+    and a repo with no ratchet both read as null, and they want different moves.
+
+    `long_name` arrives as the KEY name, so `explain path f#2` reads the second
+    twin's mark and a bare `f` reads the first's.
+    """
     from ..ratchet import mark_for
 
     if ratchet is None: