claude-dev-env 8.15.0 → 8.16.0

package/audit-rubrics/category_rubrics/category-m-producer-consumer-cardinality.md

@@ -1,44 +0,0 @@
-# Category M — Producer/consumer cardinality vs collection-type contract
-
-**What this category audits:** functions returning `list[X]`, `Sequence[X]`, or `Iterable[X]` where the producer can emit duplicates but the consumer treats the value as a set. Common when a subprocess-stdout parser walks every output line, when a registry query returns rows with non-unique keys, when a recursive walker re-enters the same node via two paths, or when a stream-fold accumulates without dedup. The bug surfaces downstream as `RuntimeError: duplicate key`, as a UI showing the same item twice, or as a writeback that re-applies the same operation.
-
-**Why this category is its own bucket:** Categories A–K catch failure modes in either the producer or the consumer in isolation. Category M catches the contract drift between them: the producer's return type promises `list[X]` (cardinality unconstrained), but a consumer downstream calls `set(result)`, builds a `dict.fromkeys(result, ...)`, or feeds the result into an `INSERT ... ON CONFLICT` that crashes on duplicates. The producer and consumer each look correct individually; the bug emerges only when their cardinality contracts disagree.
-
-**Examples of Category M findings:**
-- `_extract_paths_from_everything_cli_stdout` returns `list[Path]` but the consumer runs one `INSERT` per element against a `UNIQUE(path)` table, raising `sqlite3.IntegrityError: UNIQUE constraint failed` when the subprocess emits the same path twice. (pa#143 F10)
-- A database query returns duplicate `content_id` rows; the writeback path submits the same content twice and the second `INSERT` fails with a constraint violation. (pa#136 F30)
-- A writeback ignores the `content_id` key and re-applies an `UPDATE` against the same row, masking which row "won". (pa#136 F32)
-- A logger flushes every accumulator line without dedup; the same warning appears N times in the user-facing report.
-
-**Companion reference:** see `../source-material-section-types.md`.
-
----
-
-## Sub-bucket decomposition (Category M)
-
-Decomposition is by the **kind of producer/consumer pair** whose cardinality contracts must agree.
-
-| ID | Axis name | Concrete checks |
-|---|---|---|
-| M1 | Subprocess-stdout parsers | Functions that walk lines from `subprocess.run(...).stdout` MUST return `frozenset[X]`, `dict.fromkeys`-deduplicated `list[X]`, OR carry explicit "duplicates preserved" docstring text — never bare `list[X]` |
-| M2 | Database / registry queries | Functions that build a `list[Row]` from a query MUST dedup by primary key when the consumer treats rows as a set, OR document "all rows returned, including duplicates" |
-| M3 | Consumer-expects-set anti-pattern | Consumer calls `set(producer())`, `dict.fromkeys(producer())`, `dict((k, v) for k, v in producer())`, or `INSERT ON CONFLICT` on the producer's output — this is a sign the producer should have returned a `frozenset` / `dict` upstream |
-| M4 | `extend(...)` into list consumers (acceptable) | Consumer's only operation is `accumulator.extend(producer())` and the accumulator is itself a list — cardinality is preserved by design, no dedup needed |
-| M5 | "Duplicates preserved" docstring (acceptable) | Producer's docstring explicitly states duplicates are part of the contract (e.g., for replay logs, audit trails, ordered streams) — no dedup required |
-| M6 | Producer signature widening | `Sequence[X]` widened to `Iterable[X]` (or `list[X]` → `Sequence[X]`) without re-validating each consumer's cardinality assumption |
-| M7 | Recursive / cycle-prone walkers | Walkers that traverse a graph or directory tree where a node can be re-entered via two paths MUST dedup at the walker boundary, not at every consumer |
-| M8 | Stream-fold accumulators | Generators / `yield`-based producers consumed by `list(...)` or `collections.Counter` — verify the consumer's cardinality expectation matches the producer's emission frequency |
-
-Customize per-artifact: a pure-function producer that returns a single value reduces to "verified clean — no collection involved"; a subprocess parser without a downstream consumer in the same PR may still need M1 satisfied by docstring text.
-
----
-
-## Sample prompt
-
-The reusable Variant C template for Category M is in [`../prompts/category-m-producer-consumer-cardinality.md`](../prompts/category-m-producer-consumer-cardinality.md). Inline both the producer function and every consumer call site under `## Source material` so the audit can verify each cardinality boundary.
-
-## Why Category M matters as its own bucket
-
-Categories A–K each examine one side of an interface in isolation. Category M examines the cardinality contract spanning two sides: the producer's "can my return value contain duplicates?" question and the consumer's "do I tolerate duplicates?" answer. A reviewer walking only A–K reads the producer, finds it correct on its own terms, and approves it — then reads the consumer separately and finds it also correct on its own terms. The bug emerges only when the two are exercised against the same input together.
-
-The pa#143 F10 case is the canonical worked example: `_extract_paths_from_everything_cli_stdout` returned `list[Path]` by walking the `es.exe` stdout line-by-line. The consumer iterated the list directly and ran one `INSERT INTO watched_dirs(path) VALUES (...)` per element against a table with a `UNIQUE(path)` constraint. When the subprocess emitted the same path on two lines (an edge case — Everything's stdout can repeat results across drive letters), the list carried the path twice, so the writeback ran the same `INSERT` twice; the second `INSERT` raised `sqlite3.IntegrityError: UNIQUE constraint failed: watched_dirs.path` and the entire watchdog crashed. The fix was to change the producer to `frozenset[Path]`, which deduplicates at the boundary so each path reaches the writeback once; the consumer's per-element `INSERT` loop was already correct. The contract was the bug.

package/audit-rubrics/category_rubrics/category-n-test-name-scenario-verifier.md

@@ -1,54 +0,0 @@
-# Category N — Test-name scenario verifier
-
-**What this category audits:** tests whose names assert a specific scenario (`test_*_when_*`, `test_*_at_*`, `test_*_under_*`, `test_*_with_*`) must demonstrate via fixture inspection, monkeypatch state, or environment setup that the named condition is in effect when the system under test runs. Common failure: a test named `test_resolves_under_unc_prefix` constructs a regular drive-letter path, asserts the function returns a non-empty result, and passes — but the UNC-prefix branch was never exercised. The test is a load-bearing witness that the named scenario works, but it only exercises the no-op default path.
-
-**Why this category is its own bucket:** Categories A–K catch defects in the production code. Category N catches defects in the *test corpus's claim to coverage*. A green test suite is only meaningful when each test's name accurately describes what was exercised. When a test passes "for the wrong reason" — e.g., the assertion matches a substring that appears in both the scenario-named branch AND the default branch — the suite reports coverage of a scenario it never ran.
-
-**Examples of Category N findings:**
-- Cross-platform tests named `test_*_on_windows` / `test_*_on_linux` that don't gate on `sys.platform` or `monkeypatch.setattr(os, "name", ...)` and run unchanged on every platform. (ccc#476 F5, F21, F23, F26, F27)
-- String-shape tests that exercise only the no-op branch (`assert result == ""` after constructing an input that hits the early-return path, not the named scenario). (pa#135 F11, F15)
-- Integration tests with assertions like `<substring> not in executed_sql` where the substring shape never matches the SQL fragment shape — the assertion cannot fail by construction. (pa#136 F50)
-- Path-decision tests for `is_test_file` / `is_hook_infrastructure` / `_resolve_*_path` without a parametric matrix of canonical edge cases (empty string, tilde-prefix, UNC, drive-letter, symlinked, `..`-containing, trailing slash).
-- A test resolves `Path(__file__).parents[3]` expecting the `claude-dev-env/` package root, but the parents chain stops at `skills/` — the test cannot fail for the right reason and the asserted directory wiring is broken by construction.
-- A test imports the same function twice under two names (`from path_utils import is_config_file` plus `from path_utils import is_config_file as path_utils_is_config_file`) and asserts the two bound names produce the same result — the assertion cannot fail because both names are the same function object; the appearance of two parallel implementations is fake.
-
-**Companion reference:** see `../source-material-section-types.md`.
-
----
-
-## Sub-bucket decomposition (Category N)
-
-Decomposition is by the **kind of scenario claim** the test name makes vs the evidence in its body.
-
-| ID | Axis name | Concrete checks |
-|---|---|---|
-| N1 | Scenario-named tests demonstrate the scenario | A test whose name contains `_when_`, `_at_`, `_under_`, `_with_`, `_on_`, `_after_`, `_during_` proves via monkeypatch / fixture / environment setup that the named condition holds during the act phase |
-| N2 | Path-decision parametric matrices | Tests for `is_*_path` / `_resolve_*_path` / `*_path_exemptions` modules ship a parametrized matrix covering: empty string, single filename, tilde-prefix, UNC path, drive-letter path, symlinked path, `..`-containing path, trailing-slash path |
-| N3 | Tests that pass "for the wrong reason" | The assertion's substring matches both the scenario-named branch and the default branch — the test cannot distinguish which branch executed |
-| N4 | No-op branch exercised by scenario name | The constructed input hits an early-return / guard / no-feature-installed branch BEFORE the scenario-named code runs; the assertion succeeds against the no-op output |
-| N5 | Assertion shape mismatch | The assertion shape (`<substring> not in result`, `result == ""`, `len(result) > 0`) cannot fail by construction against the return type / value space |
-| N6 | Cross-platform scenario gating | Tests named `_on_<platform>` MUST gate on `sys.platform`, `monkeypatch.setattr(os, ...)`, or `@pytest.mark.skipif(sys.platform != "<platform>")` — bare scenario names that run unchanged across platforms claim more than they prove |
-| N7 | Time / clock scenario gating | Tests named `_after_<duration>` / `_at_midnight` / `_during_business_hours` MUST inject a frozen clock (`freezegun.freeze_time`, `monkeypatch.setattr(time, "time", ...)`) — wall-clock tests are non-deterministic and may pass against the wrong scenario |
-| N8 | Concurrent / load scenario gating | Tests named `_under_load` / `_with_concurrent_writers` MUST spawn the concurrent workers and `wait()` on them — single-threaded tests cannot claim concurrent-scenario coverage |
-| N9 | Neutral-named tests (out of scope) | Tests named `test_returns_empty_list_for_unknown_key` / `test_handles_y` (no scenario claim in the name) are NOT subject to N1–N8; flag them only for assertion-shape mismatches under N5 |
-| N10 | Test fixture wiring correctness | The test's fixture / path / import wiring resolves to the artifact the test name claims. Path arithmetic (`Path(__file__).parents[k]`) reaches the directory the assertion expects — verify by walking the parents chain symbolically. Same-symbol dual imports (`from m import f` plus `from m import f as f_alias`) bind two names to the same function object, so any parity assertion between them is true by construction. Fixture file lookups (`open(Path(__file__).parent / 'fixture.txt')`) reach a file that exists. |
-
-Customize per-artifact: a pure-function test corpus with no scenario claims reduces N1–N4 to "verified clean — no scenario-named tests in scope"; a path-classifier PR may need N2 exhausted across 8+ canonical inputs.
-
----
-
-## Write-time advisory for the flag-gated N1 slice
-
-`check_flag_gated_scenario_test_naming` in `code_rules_test_assertions.py` (wired into `code_rules_enforcer.py`) catches the deterministic N1 slice at Write/Edit time. When two or more sibling tests in a file `monkeypatch.setattr` the same module-level UPPER_SNAKE flag, that flag governs which branch the code under test runs. A `test_*` whose name carries a scenario clause (`_when_`, `_passes`, `_succeeds`, `_on_clean`) but never patches that flag runs under the flag's default value, so its named condition may not be in effect. The check prints an advisory to stderr and never blocks the write — the breadth of the sibling-pattern heuristic suits a judgment lane, where the author decides whether to patch the flag (and assert the gated path runs) or rename the test. The audit still owns the full N1–N10 surface; the advisory only surfaces this one mechanically-detectable shape early.
-
----
-
-## Sample prompt
-
-The reusable Variant C template for Category N is in [`../prompts/category-n-test-name-scenario-verifier.md`](../prompts/category-n-test-name-scenario-verifier.md). Inline every changed test function under `## Source material` along with the production function it claims to cover, so the audit can compare the named scenario against the body's act phase.
-
-## Why Category N matters as its own bucket
-
-Categories A–K each examine production code. Category N examines whether the test corpus's name claims match its body evidence. A green suite without N coverage gives a false sense of confidence: scenario-named tests that pass against the no-op branch report success for code that was never run.
-
-The ccc#476 cases (F5, F21, F23, F26, F27) demonstrate the cost of not running N: tests named `_on_windows` and `_on_linux` ran unchanged on every CI runner. The Windows-specific test passed on Linux because the production function's Windows branch was guarded by `sys.platform == "win32"` and short-circuited — the assertion succeeded against the Linux fallback. The test name claimed Windows coverage; the body never exercised it. Only an N6-style gating audit (require `monkeypatch.setattr(sys, "platform", "win32")` inside any `_on_windows`-named test, or `@pytest.mark.skipif`) would have caught this in review.

package/audit-rubrics/category_rubrics/category-p-name-vs-behavior-contract.md

@@ -1,59 +0,0 @@
-# Category P — Name / regex / word-list vs behavior-contract precision
-
-**What this category audits:** identifiers and reference data whose label asserts a contract the body does not deliver. The label may be too broad (`is_inside_function` flag set on def but never reset on scope exit), too narrow (`_is_docstring_section_header` matching only terminating headers), or shaped as one thing while behaving as another (`FILE_PATH_PATTERN` regex matching `client/server` because it lacks path-shape anchors; a hard-deny replacement word list containing ordinary technical English).
-
-The label-vs-body gap is its own failure mode independent of behavior-equivalence (L) because nothing was rewritten — the contract is broken at the moment the name is first chosen. The hook-enforced naming rules (J5 abbreviations, J6 vague nouns) ban specific identifiers but say nothing about precision-of-fit between what a name promises and what its body does.
-
-**Examples of Category P findings:**
-- A flag `is_inside_function` set on `def` and never reset on scope exit — name asserts state the body fails to keep.
-- A helper `_split_module_stem_prefix` returning `code_rules` which substring-matches unrelated stems (`code_ruleset.py`) — name asserts the tighter contract; body delivers a looser one.
-- A predicate `_is_docstring_section_header` matching only terminating headers — name asserts the general case; body delivers a specific subset.
-- A regex `FILE_PATH_PATTERN = r"(\S+/\S+)"` unanchored — name asserts path-shape; body accepts any `word/word`.
-- A hard-deny replacement-by-term list including `command`, `address`, `function`, `subject`, `however`, `forward` — list name asserts "banned heavy words"; entries are ordinary technical vocabulary.
-
-**Companion reference:** see `../source-material-section-types.md`.
-
----
-
-## Binding counterexample protocol
-
-For every regex, brace or token scanner, or word-list the diff adds or edits, build at least three concrete inputs and trace each one through the pattern by hand before you call the pattern clean:
-
-- **One intended match** — an input the pattern must catch.
-- **One near-miss** — an input a quick reading would expect to catch, but the contract says the pattern must reject.
-- **One structural edge** — an input whose shape stresses the scanner: a destructured parameter, a quoted key, a nested brace, an escaped delimiter.
-
-Walk each input character by character (or token by token) and write down what the pattern returns. A pattern that returns the wrong answer on any of the three inputs is a Category P finding; cite the input that breaks it. The pattern is clean only after all three inputs return the answer the contract promises.
-
-`hooks/blocking/` is the priority surface. Its patterns gate every write, so a pattern that matches too much or too little there fires on edits across the whole codebase.
-
-Two canonical failures show why the hand trace is binding:
-
-- **Brace scan that reads a parameter as body.** A scanner counts braces from the signature's opening `(` and treats the first balanced close as the end of the function body. A destructured parameter closes a brace inside the signature — `renderRow({ id, label })` in JavaScript, or a `{a, b}` binding in another language — so the scanner marks the body one token too early and reads the parameter list as body code.
-- **`\bschema\b` that matches a value reference.** A `\bschema\b` pattern targets a `schema` declaration, yet it also matches `schema` as the value in `{ label: schema }`, where the word is a reference, not the declaration the pattern means to find. A word boundary alone does not tell a declaration from a key or a value.
-
----
-
-## Sub-bucket decomposition (Category P)
-
-Decomposition is by the **kind of identifier / reference data** whose label is being audited against its body.
-
-| ID | Axis name | Concrete checks |
-|---|---|---|
-| P1 | Boolean / flag names assert state the body keeps | A `is_*` / `has_*` / `was_*` / `should_*` flag's lifecycle in the body matches what the name promises: set when the named condition becomes true, reset when it becomes false. Flags set once and never reset are P1 findings. |
-| P2 | Predicate-name breadth matches body coverage | A `_is_*` / `_has_*` predicate function — the body covers exactly the input class the name names. Bodies matching a narrower subset ("section header" name matching only terminating section headers) or a broader superset ("shared temp resolution" name matching shared temp AND HOME/TMP env-derived paths) are P2 findings. |
-| P3 | Regex name vs regex shape | A `*_PATTERN` / `*_REGEX` constant — the regex includes the anchors (^, $, \b, lookarounds) the name implies. An unanchored regex named `FILE_PATH_PATTERN` matching `word/word` is a P3 finding. |
-| P4 | Helper-function name vs return contract | A helper-function name (`_split_module_stem_prefix`, `_resolve_*`, `_extract_*`) — the return shape and matching semantics deliver what the name promises. Helpers whose return value's matching surface is looser than the name suggests (a stem-prefix substring-matching unrelated stems) are P4 findings. |
-| P5 | Word-list / replacement-table precision | A reference list named for a specific class of inputs (`HARD_DENY_REPLACEMENT_TERMS`, `BANNED_PROMPT_PHRASES`, `VAGUE_ADJECTIVES`) — every entry must satisfy the named class. Entries that are common in legitimate inputs (`command`, `function`, `however` in a list named "heavy words to ban") are P5 findings. |
-| P6 | Class / module name vs scope | A class name (`SingleFileParser`) or module name (`enforcer.py`) — the body's responsibility fits the name's named scope. A class that grew responsibilities outside its name is a P6 finding. |
-| P7 | Reverse: name understates what the body does | A name that promises a narrow contract while the body delivers a broader effect — future callers may rely on the narrow contract and be surprised. (Symmetric mirror of P2 / P3.) |
-
----
-
-## Sample prompt
-
-The reusable Variant C template for Category P is in [`../prompts/category-p-name-vs-behavior-contract.md`](../prompts/category-p-name-vs-behavior-contract.md). Inline every newly-added or renamed identifier alongside the body code that implements its contract under `## Source material`.
-
-## Why Category P matters as its own bucket
-
-Category L (behavior-equivalence) audits a rewrite against a prior implementation — it only fires when there is a `before` state to compare. Category P audits a fresh identifier whose label asserts a contract; the bug is that the body never delivered the named contract, even on the first commit. The hook-enforced J5 / J6 naming rules ban specific identifiers (`ctx`, `cfg`, `data`, `result`, `handle_*`) but say nothing about whether the identifier the author chose matches the body's reach. P is the bucket that catches a regex named `FILE_PATH_PATTERN` that accepts `TCP/IP`, a hard-deny word list that bans `function` and `address`, and a predicate named for the general case that only handles a subset — at audit time, before the gate ships and starts producing false positives in production.

package/audit-rubrics/category_rubrics/category-q-cross-surface-claims.md

@@ -1,46 +0,0 @@
-# Category Q — Cross-surface claim consistency (terminology, PR-description claims, message-vs-guard)
-
-**What this category audits:** claims a change makes on one surface that a second surface contradicts. A code field carries one spelling while the prose that names it uses a near-miss variant. A PR description states a fact that the diff or the repo does not bear out. A log or error string asserts a condition that the branch gating it does not guarantee. Each defect lives in the gap between two surfaces that must agree: the code and the prose about it, the PR body and the diff, the message text and the guard that fires it.
-
-**Why this category is its own bucket:** each surface reads as correct on its own. The code field is a valid identifier. The PR sentence is a well-formed claim. The log line is grammatical. The defect surfaces only when a reader holds two surfaces side by side and finds that one says a thing the other denies. Categories that read a single surface miss this; Q forces the reader to pair every claim with the surface that must back it.
-
-## Canonical examples
-
-- **PR #810 (Q1).** Eleven prose surfaces name the term one way while the code field reads `premium_interactions`. One divergent term spreads across README text, doc tables, and inline prose, so a reader who trusts any of the eleven surfaces reaches for a field name the code does not define.
-- **PR #808 (Q2).** The PR description claims zero remaining gate subjects while `converge.mjs` still holds them. The body asserts a cleanup the diff does not finish, so a reviewer who trusts the description approves a state the code contradicts.
-- **PR #823 (Q3).** A skip-branch log asserts a hardening PR opened, yet `spawnStandardsFollowUp` can return `hardeningPrOpened: false`. The message states an outcome the guard that reaches it does not guarantee, so the log reads as a success the run did not achieve.
-
-## Other typical patterns
-
-- A config key the diff adds reads `retry_budget`; a doc table row names it `retry-budget`, and a runbook names it `retry budget`.
-- An API field the diff introduces is `itemCount` (singular tail); a client doc calls it `itemCounts`.
-- A PR body says "this removes the last caller of `legacy_resolve`"; a reference search still finds a caller in a sibling module.
-- A PR body claims a 30-second ceiling; the config value the diff sets reads 60 seconds.
-- An error string says "config file is missing" while the branch that raises it fires on a parse failure, not an absent file.
-- A log line says "retry limit reached this run" while the counter it reads resets each round, so the wording overstates the lifetime of the state it names.
-
-**Companion reference:** see `../source-material-section-types.md`.
-
----
-
-## Sub-bucket decomposition (Category Q)
-
-Decomposition is by the **pair of surfaces** that must agree.
-
-| ID | Axis name | Concrete checks |
-|---|---|---|
-| Q1 | Term sweep | Pull out every identifier, API field, and config key the diff introduces or reads. Sweep all changed prose surfaces for near-miss variants — hyphen or space in place of an underscore, singular where the code is plural (or the reverse), a shared prefix with a divergent tail. Run `packages/claude-dev-env/_shared/pr-loop/scripts/terminology_sweep.py` for mechanical recall — it reads a unified diff on stdin or via `--diff-file`, prints one `file:line` finding per near-miss, exits 1 when findings exist and 0 when clean — then adjudicate each finding, since a near-miss can be an intentional distinct term. |
-| Q2 | PR-description claim verification | Fetch the PR body. For each falsifiable claim, verify it two ways against the diff and the repo. A dead-code claim ("removes the last caller of X") gets a reference search across the repo. A performance or ceiling claim ("caps at 30 seconds", "cuts calls in half") gets checked against the config values and call sites the diff sets. |
-| Q3 | Message-vs-guard consistency | For every log, error, and evidence string the diff adds or edits, read the condition that gates it. The message text matches what the guard guarantees — a string that asserts an outcome fires only on a branch that reaches that outcome. Temporal wording matches the lifetime of the state variable it names: "this run" versus "this round", "is open" versus "was opened", "reached" versus "attempted". |
-
-Customize per-artifact: a change that adds no new identifier and no PR-body claim reduces Q to "verify every message the diff touches still matches its guard." A rename that spreads a term across many docs may need Q1 alone to list every prose surface.
-
----
-
-## Sample prompt
-
-The reusable template for Category Q is in [`../prompts/category-q-cross-surface-claims.md`](../prompts/category-q-cross-surface-claims.md). The Category Q source-material block needs the diff, the PR body text, and the changed prose surfaces the agent must cross-reference against the code.
-
-## Why Category Q matters as its own bucket
-
-A reviewer walking a single surface at a time — the code alone, the docs alone, the PR body alone — judges each on its own merits and misses Q. The code field is a valid name; the PR sentence is a plausible claim; the log line is grammatical. Only pairing each claim with the surface that must back it surfaces the gap. Q forces that pairing: every identifier the diff touches is swept against the prose, every PR-body claim is checked against the diff and the repo, and every message is read against the guard that fires it.

package/audit-rubrics/prompts/category-a-api-contracts.md

@@ -1,407 +0,0 @@
-Audit [REPO/ARTIFACT] [TARGET_ID] for **Category A only** (API contract verification). Skip B–P. Sub-bucket forced-exhaustion mode: Category A is decomposed into 9 sub-buckets below. Each sub-bucket REQUIRES at least one Shape A finding OR exactly one Shape B proof-of-absence with **at least 3 adversarial probes** specific to that sub-bucket. A sub-bucket returning neither is a protocol gap.
-
-[ARTIFACT METADATA: title / change description / head SHA or revision identifier / scope summary]
-ID prefix: `find`.
-
-## Source material ([N] files/sections, all lines in scope)
-
-[INLINE THE FULL ARTIFACT HERE — see ../source-material-section-types.md for chunking guidance.]
-
-## Sub-buckets (each requires Shape A finding OR Shape B with ≥3 adversarial probes)
-
-**A1. Function/method signatures vs internal call sites**
-- Enumerate every defined function or method's parameter list: count, names, defaults, kw-only barriers (Python `*`), positional-only barriers (`/`), variadic markers (`*args`, `**kwargs`).
-- For every internal call within the artifact, verify the binding matches the callee's signature: positional count, keyword names, required-vs-optional, default fall-through.
-- Flag positional arguments passed to keyword-only parameters and vice versa.
-- Flag calls that omit a required parameter relying on a default that does not exist on the current branch.
-- Verify decorators (`@staticmethod`, `@classmethod`, `@property`) do not silently shift the parameter binding (e.g., `self` / `cls` insertion).
-- Confirm sync-vs-async (is the symbol `async def`?), the exact access path a caller uses (free function vs instance method via an object attribute vs import path), and that a keyword-only parameter with no default is required — omitting it raises `TypeError`.
-- When a call passes a config value as an argument, confirm the value's documented role matches the parameter's role (poll interval vs timeout vs budget). A poll interval such as `PollingIntervals.resume_check` handed to a `progress_check_timeout` parameter type-checks but carries the wrong meaning.
-
-**A2. Return-type annotation vs every code path**
-- For each annotated function, walk every code path: explicit `return X`, fall-through to implicit `None`, exception-handler exit, generator `yield` paths, async coroutine return value.
-- Verify each path's return value is assignable to the declared annotation; flag `-> bool` functions that can return `None`, `-> list[T]` functions that can return `None` on an early exit, etc.
-- For functions that raise instead of returning on some path, confirm the annotation does not promise a value the caller will dereference.
-- Inspect `try/except/finally` chains for paths that return from `finally` and override `try`/`except` returns.
-- For async functions, confirm the annotation refers to the awaited type, not the coroutine wrapper.
-- The full failure contract is the return value AND every exception raised — list each `raise` in the body and the docstring `Raises:`; a `-> bool` that can also raise is not fully described as "returns bool".
-
-**A3. CLI/argument-parser declaration → downstream Namespace contract**
-- For every `add_argument(...)` (or equivalent CLI declaration), verify the auto-derived or explicit `dest=` matches the attribute name accessed downstream on the parsed namespace.
-- Verify `type=` (or schema coercion) matches every downstream consumer's expectation — e.g., a value handed to a function requiring `int` is declared `type=int`, not the default `str`.
-- Switch flags (`action="store_true"` / `store_false`) produce booleans; non-switch arguments produce typed values; flag the mismatch where a switch is treated as a value or vice versa.
-- Default values resolve correctly when the flag is omitted; flag any code path that assumes the user supplied the argument.
-- Required-vs-optional declaration matches the downstream code's null-handling.
-
-**A4. Stdlib/library callback contracts**
-- Identify every callback handed to a library function (e.g., `os.walk(onerror=...)`, sort `key=`, `filter`, `map`, `re.sub(repl=callable)`, signal handlers, threading callbacks). Verify each callback's signature matches what the library calls it with — arity, positional-vs-keyword, return type the library consumes.
-- For every stdlib function the artifact calls, verify argument types and exception contracts: which exceptions can each call raise, and is each caller prepared (or deliberately not prepared) for them.
-- Verify kwargs to stdlib functions are spelled correctly for the targeted runtime version (deprecated/renamed kwargs, version-introduced kwargs).
-- Catch-site precision — for any "catches X" claim confirm the exact catch site and scope (an `except` around only a rollback inside `finally` does not catch the same error from the `with` body).
-- Flag callbacks whose return value the library consumes but the implementation returns `None` (or vice versa).
-- Confirm callback exception behavior: which exceptions in the callback bubble out, which are swallowed by the library, which terminate iteration.
-
-**A5. Subprocess / external-process invocation contract**
-- For every `subprocess.run` / `subprocess.Popen` / equivalent call, verify the `args` shape: list-of-strings vs single string vs `shell=True` semantics.
-- Verify kwargs are valid for the targeted runtime version (`capture_output`, `text`, `encoding`, `check`, `timeout`); flag combinations that conflict (`stdout=PIPE` + `capture_output=True`).
-- Exception contract under `check=True` (raises `CalledProcessError` on non-zero exit) — verify callers either propagate or handle, with no silent swallow that masks failure.
-- Verify quoting/escaping of arguments crossing the subprocess boundary, especially when interpolating untrusted strings.
-- Verify the resolved executable path exists on the target platform, not assumed (`which` / `Get-Command` failure paths).
-
-**A6. Shell/host-language cmdlet or function parameter sets and binding**
-- For every shell or host-language function/cmdlet declaration with parameter sets (PowerShell `param(...)` with `ParameterSetName=`, Bash `getopts`, etc.), verify the declaration matches every invocation pattern. Confirm a default parameter set is declared if no-arg invocation is reachable.
-- For every cmdlet/builtin invocation, verify the parameter combination is valid per the cmdlet's documented parameter sets — flag combinations that mix flags from disjoint parameter sets.
-- Flag missing `-ErrorAction` (or equivalent) declarations on calls whose null-checks downstream assume swallowed errors.
-- Verify each cmdlet/builtin argument's type coercion at the boundary matches what the cmdlet expects.
-- Confirm pipeline-bound parameters (`ValueFromPipeline`, `ValueFromPipelineByPropertyName`) match what upstream emits.
-
-**A7. Cross-language / cross-process argv and serialization boundary**
-- Trace every value crossing a language or process boundary (shell argv → Python `sys.argv`, environment variables, JSON/IPC payloads, file-format round-trips). Verify the producer's serialization matches the consumer's parser.
-- Flag trailing-backslash, embedded-space, embedded-quote, and Unicode hazards on Windows argv composition (Microsoft C-runtime argv parser rules) and POSIX shell word-splitting.
-- Verify argument-order conventions match across the boundary — e.g., flag order, positional placement, separator handling (`--`).
-- Cross-language default-value drift: a default declared on one side that differs from the default on the other side; verify either both are sourced from a single config or both are intentionally mirrored.
-- Cross-language type drift: integer width, signed/unsigned, floating-point precision, string encoding (UTF-8 vs UTF-16), null/empty-string semantics.
-
-**A8. Documented API/tool calls vs official API documentation**
-- For every API call, MCP tool invocation, CLI command, or SDK method call documented in the source material, identify the provider.
-- Look up the official documentation for that API (Context7 MCP for libraries/SDKs, API reference docs for REST endpoints, tool definitions in session for MCP calls, `--help` for CLI tools).
-- Verify the documented parameter names, types, and required-ness match the official API signature.
-- For read-only API calls, execute one safe invocation to confirm the documented shape succeeds in practice.
-- For write calls, verify the signature against the provider's own published API contract — their REST reference docs, OpenAPI spec, SDK source code, or `--help` output. When a read endpoint exposes the same state, call it to confirm the write contract.
-- Flag every call where documented parameters, types, or behavior diverge from the official API contract.
-
-**A9. Intra-module sibling-helper API parity**
-- Did the diff add a new check / validator / parser / handler alongside existing sibling helpers in the same module? Verify the new one matches the sibling cohort's signature — every parameter the peer checks accept (e.g., `all_changed_lines` for diff-line filtering).
-- Verify the new helper's scoping semantics match the cohort: whole-file vs fragment content surface, diff-line filtering, and `defer_scope_to_caller` handling.
-- Verify the new helper's result-shape contract matches: where the result cap is applied (pre-scope vs post-scope), whether `defer_scope_to_caller=True` is honored, and the return type.
-- When the new helper omits a sibling-accepted parameter, runs on a different content surface than its siblings, or applies the result cap at a different point in the pipeline, name it as an A9 finding. Cite the new helper and the sibling it diverges from as the pair.
-- For a pure-code artifact with no new sibling helper, A9 is one line of proof-of-absence (the diff adds no helper alongside an existing cohort).
-
-### Documentation as contract (when the artifact asserts facts about the code)
-
-When the artifact is documentation that asserts facts about the codebase (symbol names, signatures, return types, exceptions, file paths), run all seven documentation-as-contract checks below; each yields a confirmation or a finding. For a pure-code artifact, this section is one line of proof-of-absence (the artifact asserts no code facts).
-
-- Full failure contract — the failure signals of a function are its return value AND every exception it raises; trace the body and the docstring `Raises:` for every `raise`. _Example:_ a docs PR says a UI helper "returns `bool`", but it also raises a custom not-found error, so "returns bool" understates the contract.
-- Call shape — required versus optional parameters (a keyword-only parameter with NO default is required; omitting it raises `TypeError`), sync versus async, and the exact access path (free function versus instance method reached through an object attribute versus import path). _Example:_ a doc presents a helper as a free function, but it is an `async` instance method reached through an object attribute, so the doc's call example would raise `TypeError`.
-- Reuse-first — before a doc endorses a hand-written snippet, search for a dedicated helper that already does it. _Example:_ a doc endorses hand-composing `normalize(name).lower()` inline while a dedicated `normalize_for_matching()` helper already does exactly that.
-- Path resolution — every file or directory path a doc cites resolves from the repository root. _Example:_ a doc cites a bare `snapshots/` directory as if it sat at the repo root, but the tree lives under `subsystem/snapshots/`.
-- Cross-entry consistency — scan parallel rows, sections, and table entries for claims that contradict each other. _Example:_ two adjacent table rows map the same subsystem to two different exception base classes.
-- Catch-site precision — when a doc claims code "catches X", confirm the exact site and scope of the catch. _Example:_ a doc says a context manager catches a driver error, but the `except` wraps only the rollback inside `finally`, so an error raised in the `with` body propagates uncaught.
-- Citation freshness — re-derive every `file:line` claim against the current code; never trust a prior "verified" assertion or wording borrowed from a comment. _Example:_ an attribute name carried over from a review comment names a member the class does not define; the current code exposes it under a different name.
-
-## Cross-bucket questions to answer at the end
-
-Q1: Are there any contracts that span two sub-buckets that single-bucket analysis would miss?
-Q2: What is the worst contract-drift hazard introduced by this artifact? Cite file:line.
-Q3: Where would a future refactor most likely break a cross-bucket or cross-language contract? Name the line(s) most fragile.
-
-## Output
-
-Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket A1–A9, produce Shape A or Shape B (with ≥3 adversarial probes). Documentation-as-contract: when the artifact asserts code facts, walk all seven checks and report each as a finding or a confirmation; for a pure-code artifact, one line of proof-of-absence. Cross-bucket Q1–Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 P1 bugs across these 9 sub-buckets — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
-
----
-
-# Worked example: jl-cmd/claude-dev-env PR #394 (May 2026 audit experiment)
-
-Audit jl-cmd/claude-dev-env PR #394 for **Category A only** (API contract verification). Skip B–N. Sub-bucket forced-exhaustion mode: Category A is decomposed into 8 sub-buckets below. Each sub-bucket REQUIRES at least one Shape A finding OR exactly one Shape B proof-of-absence with **at least 3 adversarial probes** specific to that sub-bucket. A sub-bucket returning neither is a protocol gap.
-
-PR: feat(scripts): add sweep-empty-dirs utility and scheduled-task installer
-Head SHA: 62c9c169ee7a44824e5da25c4cf8b74fdca08a53
-ID prefix: `find`.
-
-## Sub-buckets (each requires Shape A finding OR Shape B with ≥3 adversarial probes)
-
-**A1. Python function signatures vs internal call sites**
-- Every defined function's parameter list (count, names, defaults, kw-only).
-- Every internal call within `sweep_empty_dirs.py` matches its target's signature.
-
-**A2. Python return-type annotation vs every code path**
-- Each function's return annotation is satisfied by every path: explicit `return X`, fall-through, exception-handler exit.
-- Pay specific attention to `main() -> None` (with the `KeyboardInterrupt` path) and `sweep(...) -> list[str]` (single return path).
-
-**A3. argparse parser → Namespace contract**
-- Every `add_argument(...)` declared in `_build_parser()` produces the exact dest name accessed in `main()`.
-- `type=` matches downstream usage (e.g., `time.sleep` accepts the type).
-- Switch flag (`--once`) produces a bool; non-switches produce typed values.
-- Default values resolve correctly when the flag is omitted.
-
-**A4. stdlib callback contracts (os.walk onerror, getctime, rmdir)**
-- `os.walk(root, onerror=_log_walk_error, topdown=False)` — `_log_walk_error` matches the exact signature stdlib calls (positional `OSError`).
-- `os.path.getctime`, `os.rmdir` argument and exception contracts.
-- `time.sleep` argument contract.
-- `os.walk`'s own kwargs (`onerror`, `topdown`) are spelled correctly for the Python version targeted.
-
-**A5. subprocess invocation contract (test file)**
-- `subprocess.run([list], check=True, capture_output=True)` — kwargs valid for the targeted Python.
-- The list shape — `["powershell", "-Command", string]` — matches `subprocess.run`'s expected `args` parameter.
-- Exception contract: `check=True` raises CalledProcessError on non-zero exit; tests do not catch it.
-
-**A6. PowerShell cmdlet parameter sets and binding**
-- `param(...)` declarations with `ParameterSetName=` — does the script declare `[CmdletBinding(DefaultParameterSetName=...)]`? If not, what happens with no-arg invocation?
-- `New-ScheduledTaskTrigger -Daily -At ... -RepetitionInterval ...` — is `-RepetitionInterval` valid for the `-Daily` parameter set per Microsoft's docs? Verify against https://learn.microsoft.com/powershell/module/scheduledtasks/new-scheduledtasktrigger.
-- `Get-Command python` (line 80) — missing `-ErrorAction SilentlyContinue` in the fallback breaks the subsequent null-check contract.
-- `Register-ScheduledTask`, `New-ScheduledTaskAction`, `New-ScheduledTaskSettingsSet`, `Get-ScheduledTask`, `Unregister-ScheduledTask` — verify each call's parameter shape against its cmdlet signature.
-
-**A7. Cross-language argv boundary (PowerShell argv construction → Python sys.argv → argparse)**
-- The `New-ScheduledTaskAction -Argument` string `"$ScriptPath --once --age $AgeSeconds ""$Target"""` — when expanded and passed to Windows process creation, does the resulting argv match what argparse expects?
-- Trailing-backslash hazard: if `$Target` ends with `\`, what does the Microsoft C-runtime argv parser produce?
-- The Python `argparse` flag order — does the launcher's argv arrangement (`<flags> <positional>`) match what argparse accepts?
-- Cross-language default-value drift: PowerShell `[int]$AgeSeconds = 120` vs Python `DEFAULT_AGE_SECONDS: int = 120` — both hardcoded, no shared source of truth.
-- Cross-language type drift: PowerShell `[int]` vs Python `type=int` — both convert to integer, but PowerShell's `[int]` is 32-bit signed; argparse's `int(...)` is Python int (arbitrary precision). Match for normal values.
-
-## Cross-bucket questions to answer at the end
-
-Q1: Are there any contracts that span two sub-buckets that single-bucket analysis would miss?
-Q2: What's the worst contract-drift hazard introduced by this PR? Cite file:line.
-Q3: Where would a future refactor most likely break a cross-language contract? Name the line(s) most fragile.
-
-## Output
-
-Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket A1-A7, produce Shape A or Shape B (with ≥3 probes). Cross-bucket Q1-Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 P1 bugs across these 8 sub-buckets — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
-
-## Diff (4 new files, all lines in scope)
-
-### packages/claude-dev-env/scripts/sweep_empty_dirs.py
-```python
-#!/usr/bin/env python3
-"""Delete empty directories older than 2 minutes under a given root."""
-
-import argparse
-import os
-import sys
-import time
-
-from config.sweep_config import DEFAULT_AGE_SECONDS
-from config.sweep_config import DEFAULT_POLL_INTERVAL
-
-
-def _log_walk_error(os_error: OSError) -> None:
-    print(f"warning: cannot scan {os_error.filename} — {os_error.strerror}", file=sys.stderr)
-
-
-def sweep(root: str, min_age_seconds: int) -> list[str]:
-    """Remove empty directories under *root* older than *min_age_seconds*."""
-
-    now = time.time()
-    removed: list[str] = []
-
-    for each_directory_path, _, _ in os.walk(
-        root, onerror=_log_walk_error, topdown=False
-    ):
-        try:
-            created = os.path.getctime(each_directory_path)
-        except OSError:
-            continue
-        if now - created >= min_age_seconds:
-            try:
-                os.rmdir(each_directory_path)
-                print(f"deleted: {each_directory_path}")
-                removed.append(each_directory_path)
-            except OSError:
-                pass
-
-    return removed
-
-
-def _build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(description="Delete empty directories older than a given age.")
-    parser.add_argument("root", help="Root directory to scan")
-    parser.add_argument("--age", type=int, default=DEFAULT_AGE_SECONDS,
-                        help=f"Minimum age in seconds (default: {DEFAULT_AGE_SECONDS} = 2 minutes)")
-    parser.add_argument("--once", action="store_true",
-                        help="Single pass and exit instead of watching in a loop")
-    parser.add_argument("--interval", type=int, default=DEFAULT_POLL_INTERVAL,
-                        help=f"Poll interval in seconds when looping (default: {DEFAULT_POLL_INTERVAL})")
-    return parser
-
-
-def main() -> None:
-    parser = _build_parser()
-    arguments = parser.parse_args()
-
-    if not os.path.isdir(arguments.root):
-        print(f"error: not a directory: {arguments.root}", file=sys.stderr)
-        sys.exit(1)
-
-    if arguments.once:
-        sweep(arguments.root, arguments.age)
-        return
-
-    print(f"watching {arguments.root} every {arguments.interval}s (age threshold: {arguments.age}s)")
-    try:
-        while True:
-            sweep(arguments.root, arguments.age)
-            time.sleep(arguments.interval)
-    except KeyboardInterrupt:
-        print("\nstopped.")
-
-
-if __name__ == "__main__":
-    main()
-```
-
-### packages/claude-dev-env/scripts/config/sweep_config.py
-```python
-"""Centralized timing configuration for sweep_empty_dirs."""
-
-DEFAULT_AGE_SECONDS: int = 120
-DEFAULT_POLL_INTERVAL: int = 30
-```
-
-### packages/claude-dev-env/scripts/tests/test_sweep_empty_dirs.py
-```python
-"""Tests for sweep_empty_dirs.py"""
-
-from __future__ import annotations
-
-import datetime
-import os
-import subprocess
-import sys
-import tempfile
-import time
-from pathlib import Path
-
-_SCRIPTS_DIR = Path(__file__).resolve().parent.parent
-if str(_SCRIPTS_DIR) not in sys.path:
-    sys.path.insert(0, str(_SCRIPTS_DIR))
-
-from sweep_empty_dirs import sweep  # noqa: E402
-
-
-def _set_creation_time_windows(path: str, timestamp: float) -> None:
-    dt = datetime.datetime.fromtimestamp(timestamp, tz=datetime.timezone.utc)
-    date_str = dt.strftime("%Y-%m-%d %H:%M:%S")
-    subprocess.run(
-        ["powershell", "-Command",
-         f"(Get-Item '{path}').CreationTimeUtc = [DateTime]'{date_str}'"],
-        check=True, capture_output=True,
-    )
-
-
-def test_deletes_empty_dir_older_than_threshold() -> None:
-    with tempfile.TemporaryDirectory() as tmp:
-        empty_dir = os.path.join(tmp, "old_empty")
-        os.mkdir(empty_dir)
-        _set_creation_time_windows(empty_dir, time.time() - 300)
-        removed = sweep(tmp, min_age_seconds=120)
-        assert empty_dir in removed
-        assert not os.path.isdir(empty_dir)
-
-
-def test_skips_empty_dir_newer_than_threshold() -> None:
-    with tempfile.TemporaryDirectory() as tmp:
-        fresh_dir = os.path.join(tmp, "fresh_empty")
-        os.mkdir(fresh_dir)
-        removed = sweep(tmp, min_age_seconds=120)
-        assert fresh_dir not in removed
-        assert os.path.isdir(fresh_dir)
-
-
-def test_deletes_nested_empty_dirs() -> None:
-    with tempfile.TemporaryDirectory() as tmp:
-        leaf = os.path.join(tmp, "parent", "child", "leaf")
-        os.makedirs(leaf)
-        _set_creation_time_windows(os.path.join(tmp, "parent"), time.time() - 300)
-        _set_creation_time_windows(os.path.join(tmp, "parent", "child"), time.time() - 300)
-        _set_creation_time_windows(leaf, time.time() - 300)
-        removed = sweep(tmp, min_age_seconds=120)
-        assert leaf in removed
-        assert os.path.join(tmp, "parent", "child") in removed
-        assert os.path.join(tmp, "parent") in removed
-
-
-def test_empty_root_does_not_crash() -> None:
-    with tempfile.TemporaryDirectory() as tmp:
-        _set_creation_time_windows(tmp, time.time() - 300)
-        sweep(tmp, min_age_seconds=120)
-
-
-def test_skips_nonempty_dir() -> None:
-    with tempfile.TemporaryDirectory() as tmp:
-        nonempty_dir = os.path.join(tmp, "has_stuff")
-        os.mkdir(nonempty_dir)
-        Path(nonempty_dir, "keepme.txt").write_text("hello")
-        removed = sweep(tmp, min_age_seconds=0)
-        assert nonempty_dir not in removed
-        assert os.path.isdir(nonempty_dir)
-```
-
-### packages/claude-dev-env/scripts/Install-SweepEmptyDirs.ps1
-```powershell
-#!/usr/bin/env pwsh
-param(
-    [Parameter(ParameterSetName = "install")]
-    [string]$Target,
-
-    [Parameter(ParameterSetName = "install")]
-    [int]$IntervalMinutes = 5,
-
-    [Parameter(ParameterSetName = "install")]
-    [int]$AgeSeconds = 120,
-
-    [Parameter(ParameterSetName = "remove")]
-    [switch]$Remove,
-
-    [Parameter(ParameterSetName = "status")]
-    [switch]$Status
-)
-
-$TaskName = "SweepEmptyDirs"
-
-if ($Status) {
-    $task = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
-    if (-not $task) {
-        Write-Host "STATUS: $TaskName is not registered."
-        return
-    }
-    Write-Host "STATUS: $TaskName is registered."
-    Write-Host "  State: $($task.State)"
-    Write-Host "  Actions:"
-    foreach ($action in $task.Actions) {
-        Write-Host "    $($action.Execute) $($action.Arguments)"
-    }
-    Write-Host "  Triggers:"
-    foreach ($trigger in $task.Triggers) {
-        Write-Host "    $($trigger.Repetition.Interval) (starting $($trigger.StartBoundary))"
-    }
-    return
-}
-
-if ($Remove) {
-    Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false -ErrorAction SilentlyContinue
-    Write-Host "$TaskName removed."
-    return
-}
-
-$ScriptDir = Split-Path -Parent $PSCommandPath
-$ScriptPath = Join-Path $ScriptDir "sweep_empty_dirs.py"
-
-if (-not (Test-Path $ScriptPath)) {
-    Write-Error "sweep_empty_dirs.py not found at: $ScriptPath"
-    exit 1
-}
-
-if (-not $Target) {
-    Write-Error "Parameter -Target is required (the directory to watch)."
-    exit 1
-}
-
-if (-not (Test-Path $Target)) {
-    Write-Error "Target directory does not exist: $Target"
-    exit 1
-}
-
-$_py = Get-Command py -ErrorAction SilentlyContinue
-$PythonPath = if ($_py) { $_py.Source } else { (Get-Command python).Source }
-if (-not $PythonPath) {
-    Write-Error "Cannot find Python (py or python) on PATH."
-    exit 1
-}
-$Action = New-ScheduledTaskAction -Execute $PythonPath -Argument "$ScriptPath --once --age $AgeSeconds ""$Target"""
-$Trigger = New-ScheduledTaskTrigger -Daily -At "00:00" -RepetitionInterval (New-TimeSpan -Minutes $IntervalMinutes)
-$Settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable
-
-Register-ScheduledTask -TaskName $TaskName -Action $Action -Trigger $Trigger -Settings $Settings -Force | Out-Null
-Write-Host "$TaskName registered — runs every ${IntervalMinutes}min against '$Target' (age ≥ ${AgeSeconds}s)."
-```