claude-dev-env 1.79.0 → 1.81.0

package/_shared/pr-loop/scripts/tests/test_terminology_sweep.py

@@ -0,0 +1,297 @@
+"""Behavioral tests for the commit-time terminology sweep."""
+
+import importlib.util
+import subprocess
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_sweep_module() -> ModuleType:
+    module_path = Path(__file__).parent.parent / "terminology_sweep.py"
+    spec = importlib.util.spec_from_file_location("terminology_sweep", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+sweep_module = _load_sweep_module()
+sweep_diff = sweep_module.sweep_diff
+staged_terminology_findings = sweep_module.staged_terminology_findings
+main = sweep_module.main
+parse_added_lines = sweep_module._parse_added_lines
+
+
+def _init_git_repository(repository_path: Path) -> None:
+    for each_command in (
+        ["git", "init"],
+        ["git", "config", "user.email", "test@example.com"],
+        ["git", "config", "user.name", "Test"],
+    ):
+        subprocess.run(each_command, cwd=repository_path, check=True, capture_output=True)
+
+
+CODE_AND_PROSE_DIFF = (
+    "diff --git a/api/quota.py b/api/quota.py\n"
+    "--- a/api/quota.py\n"
+    "+++ b/api/quota.py\n"
+    "@@ -0,0 +1,2 @@\n"
+    "+def read_quota(account):\n"
+    '+    return account["premium_interactions"]\n'
+    "diff --git a/docs/README.md b/docs/README.md\n"
+    "--- a/docs/README.md\n"
+    "+++ b/docs/README.md\n"
+    "@@ -0,0 +1,1 @@\n"
+    "+The premium-request budget gates the run.\n"
+)
+
+
+def test_flags_prose_near_miss_of_code_identifier() -> None:
+    findings = sweep_diff(CODE_AND_PROSE_DIFF)
+    assert len(findings) == 1
+    assert "docs/README.md:1" in findings[0]
+    assert "premium-request" in findings[0]
+    assert "premium_interactions" in findings[0]
+
+
+def test_does_not_flag_exact_hyphen_variant() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+premium_interactions = 5\n"
+        "diff --git a/docs/README.md b/docs/README.md\n"
+        "--- a/docs/README.md\n"
+        "+++ b/docs/README.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+The premium-interactions budget gates the run.\n"
+    )
+    assert sweep_diff(diff) == []
+
+
+def _code_and_prose_collision_diff(code_identifier: str, prose_compound: str) -> str:
+    return (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        f"+{code_identifier} = 5\n"
+        "diff --git a/docs/README.md b/docs/README.md\n"
+        "--- a/docs/README.md\n"
+        "+++ b/docs/README.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        f"+This is a {prose_compound} cache.\n"
+    )
+
+
+def test_does_not_flag_english_compound_tail_read_only() -> None:
+    diff = _code_and_prose_collision_diff("read_config", "read-only")
+    assert sweep_diff(diff) == []
+
+
+def test_does_not_flag_english_compound_tail_data_driven() -> None:
+    diff = _code_and_prose_collision_diff("data_source", "data-driven")
+    assert sweep_diff(diff) == []
+
+
+def test_does_not_flag_english_compound_tail_type_safe() -> None:
+    diff = _code_and_prose_collision_diff("type_check", "type-safe")
+    assert sweep_diff(diff) == []
+
+
+def test_does_not_flag_english_compound_tail_test_driven() -> None:
+    diff = _code_and_prose_collision_diff("test_case", "test-driven")
+    assert sweep_diff(diff) == []
+
+
+def test_does_not_flag_english_compound_tail_high_quality() -> None:
+    diff = _code_and_prose_collision_diff("high_level", "high-quality")
+    assert sweep_diff(diff) == []
+
+
+def test_does_not_flag_unrelated_hyphenated_prose() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+premium_interactions = 5\n"
+        "diff --git a/docs/README.md b/docs/README.md\n"
+        "--- a/docs/README.md\n"
+        "+++ b/docs/README.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+A well-known open-source project.\n"
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_does_not_flag_plural_prose_of_singular_identifier() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+test_file = 5\n"
+        "diff --git a/docs/README.md b/docs/README.md\n"
+        "--- a/docs/README.md\n"
+        "+++ b/docs/README.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+We scan the test files for coverage.\n"
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_does_not_flag_plural_prose_of_singular_identifier_audit_prompt() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+audit_prompt = 5\n"
+        "diff --git a/docs/README.md b/docs/README.md\n"
+        "--- a/docs/README.md\n"
+        "+++ b/docs/README.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+The audit prompts drive each round.\n"
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_does_not_flag_singular_prose_of_plural_identifier() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+audit_prompts = 5\n"
+        "diff --git a/docs/README.md b/docs/README.md\n"
+        "--- a/docs/README.md\n"
+        "+++ b/docs/README.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+The audit prompt drives each round.\n"
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_does_not_flag_y_to_ies_plural_variant() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+retry_policy = 5\n"
+        "diff --git a/docs/README.md b/docs/README.md\n"
+        "--- a/docs/README.md\n"
+        "+++ b/docs/README.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+The retry policies bound each attempt.\n"
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_still_flags_non_plural_divergent_tail() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+premium_interactions = 5\n"
+        "diff --git a/docs/README.md b/docs/README.md\n"
+        "--- a/docs/README.md\n"
+        "+++ b/docs/README.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+The premium request budget gates the run.\n"
+    )
+    findings = sweep_diff(diff)
+    assert len(findings) == 1
+    assert "premium request" in findings[0]
+
+
+def test_flags_near_miss_inside_code_comment() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,2 @@\n"
+        "+premium_interactions = 5\n"
+        "+# the premium-request path resets the counter\n"
+    )
+    findings = sweep_diff(diff)
+    assert len(findings) == 1
+    assert "premium-request" in findings[0]
+
+
+def test_no_findings_when_no_multiword_identifier_introduced() -> None:
+    diff = (
+        "diff --git a/docs/README.md b/docs/README.md\n"
+        "--- a/docs/README.md\n"
+        "+++ b/docs/README.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+The premium-request budget gates the run.\n"
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_main_exits_one_when_findings(tmp_path: Path) -> None:
+    diff_file = tmp_path / "change.diff"
+    diff_file.write_text(CODE_AND_PROSE_DIFF, encoding="utf-8")
+    exit_code = main(["--diff-file", str(diff_file)])
+    assert exit_code == 1
+
+
+def test_main_exits_zero_when_clean(tmp_path: Path) -> None:
+    diff_file = tmp_path / "clean.diff"
+    diff_file.write_text(
+        "diff --git a/docs/README.md b/docs/README.md\n"
+        "--- a/docs/README.md\n"
+        "+++ b/docs/README.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+Nothing to see here.\n",
+        encoding="utf-8",
+    )
+    exit_code = main(["--diff-file", str(diff_file)])
+    assert exit_code == 0
+
+
+def test_staged_terminology_findings_flags_staged_prose(tmp_path: Path) -> None:
+    _init_git_repository(tmp_path)
+    (tmp_path / "quota.py").write_text(
+        "premium_interactions = 5\n", encoding="utf-8"
+    )
+    (tmp_path / "README.md").write_text(
+        "The premium-request budget gates the run.\n", encoding="utf-8"
+    )
+    subprocess.run(["git", "add", "-A"], cwd=tmp_path, check=True, capture_output=True)
+    findings = staged_terminology_findings(tmp_path)
+    assert any("premium-request" in each_finding for each_finding in findings)
+
+
+def test_staged_terminology_findings_empty_when_clean(tmp_path: Path) -> None:
+    _init_git_repository(tmp_path)
+    (tmp_path / "README.md").write_text("Nothing notable here.\n", encoding="utf-8")
+    subprocess.run(["git", "add", "-A"], cwd=tmp_path, check=True, capture_output=True)
+    assert staged_terminology_findings(tmp_path) == []
+
+
+def test_parse_added_lines_counts_pre_increment_content_as_added_line() -> None:
+    diff_with_pre_increment = (
+        "diff --git a/app.mjs b/app.mjs\n"
+        "--- a/app.mjs\n"
+        "+++ b/app.mjs\n"
+        "@@ -0,0 +1,3 @@\n"
+        "+++counter;\n"
+        "+let first_total = read_first_value();\n"
+        "+let second_total = read_second_value();\n"
+    )
+
+    all_added_lines = parse_added_lines(diff_with_pre_increment)
+
+    assert [
+        (each_line_number, each_text) for _, each_line_number, each_text in all_added_lines
+    ] == [
+        (1, "++counter;"),
+        (2, "let first_total = read_first_value();"),
+        (3, "let second_total = read_second_value();"),
+    ]

package/audit-rubrics/CLAUDE.md

@@ -1,6 +1,6 @@
 # audit-rubrics
 
-Audit rubrics for the PR-loop code-review suite. The rubrics define the 16 bug categories (A–P), their sub-bucket decompositions, and the prompt templates agents use during an audit pass. Installed into `~/.claude/audit-rubrics/` by `bin/install.mjs`.
+Audit rubrics for the PR-loop code-review suite. The rubrics define the 17 bug categories (A–Q), their sub-bucket decompositions, and the prompt templates agents use during an audit pass. Installed into `~/.claude/audit-rubrics/` by `bin/install.mjs`.
 
 ## Key file
 
@@ -12,7 +12,7 @@ Audit rubrics for the PR-loop code-review suite. The rubrics define the 16 bug c
 
 | Entry | Description |
 |---|---|
-| `category_rubrics/` | One `.md` per category (A–P): defines what the category audits, example findings, and a sub-bucket decomposition table |
+| `category_rubrics/` | One `.md` per category (A–Q): defines what the category audits, example findings, and a sub-bucket decomposition table |
 | `prompts/` | One `.md` per category: the ready-to-use audit prompt template an agent inlines the artifact into |
 
 ## Categories
@@ -35,6 +35,7 @@ Audit rubrics for the PR-loop code-review suite. The rubrics define the 16 bug c
 | N | Test name / scenario verifier |
 | O | Docstring vs implementation drift |
 | P | Name vs behavior contract |
+| Q | Cross-surface claim consistency |
 
 ## Breaking-change rule
 

package/audit-rubrics/category_rubrics/CLAUDE.md

@@ -1,6 +1,6 @@
 # audit-rubrics/category_rubrics
 
-One rubric file per audit category (A–P). Each file defines what the category covers, gives concrete examples of findings, and provides the sub-bucket decomposition an audit agent uses to structure its pass.
+One rubric file per audit category (A–Q). Each file defines what the category covers, gives concrete examples of findings, and provides the sub-bucket decomposition an audit agent uses to structure its pass.
 
 ## Files
 
@@ -22,6 +22,7 @@ One rubric file per audit category (A–P). Each file defines what the category
 | `category-n-test-name-scenario-verifier.md` | N — Test name / scenario verifier |
 | `category-o-docstring-vs-impl-drift.md` | O — Docstring vs implementation drift |
 | `category-p-name-vs-behavior-contract.md` | P — Name vs behavior contract |
+| `category-q-cross-surface-claims.md` | Q — Cross-surface claim consistency |
 
 ## Rubric structure
 

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

@@ -10,6 +10,7 @@
 - A PowerShell cmdlet is invoked with a parameter that belongs to a different parameter set.
 - A new gate-time validator omits the `all_changed_lines` parameter that peer span-based validators accept, so the dispatcher cannot plumb diff scope through and the check silently over- or under-blocks.
 - A new span-based check applies its result cap before honoring `defer_scope_to_caller=True`, while peer checks return all violations in that mode and let the caller cap; this leaves the new sibling stale against the established pattern.
+- A call passes `PollingIntervals.resume_check` (a poll interval — how often to re-check) into a `progress_check_timeout` parameter (a timeout — how long to wait). The value's role does not match the parameter's role, so the call type-checks while the behavior is wrong.
 
 **Companion reference:** see `../source-material-section-types.md` for guidance on how to chunk the artifact under audit.
 
@@ -23,7 +24,7 @@ The decomposition that worked best for PR #394 (a Python+PowerShell scheduled-ta
 
 | ID | Axis name | Concrete checks |
 |---|---|---|
-| A1 | Python function signatures vs internal call sites | Parameter count, names, defaults, kw-only barriers; every internal call binds correctly. Is the symbol `async def`? Confirm the exact access path a caller uses: free function vs instance method reached through an object attribute vs import path. A keyword-only parameter with no default is required; omitting it raises `TypeError`. |
+| A1 | Python function signatures vs internal call sites | Parameter count, names, defaults, kw-only barriers; every internal call binds correctly. Is the symbol `async def`? Confirm the exact access path a caller uses: free function vs instance method reached through an object attribute vs import path. 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 — a poll interval is not a timeout, and a timeout is not a budget. |
 | 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. The full failure contract is the return value AND every exception raised — trace the body and the docstring `Raises:` for each `raise`, including custom errors. A `-> bool` function that also raises is not fully described by "returns bool". |
 | A3 | argparse parser → Namespace contract | Every `add_argument(...)` produces the exact dest name accessed downstream; `type=` matches downstream usage; switches produce bools. |
 | A4 | Stdlib callback contracts | `os.walk(onerror=...)` callback shape; `os.path.getctime` / `os.rmdir` argument and exception contracts; `time.sleep` argument types. Catch-site precision: for any claim that code "catches X", confirm the exact catch site and scope — an `except` around only a rollback inside `finally` does not catch the same error raised in the `with` body. |

package/audit-rubrics/category_rubrics/category-j-code-rules-compliance.md

@@ -30,7 +30,19 @@
 | J11 | sys.path.insert dedup | `sys.path.insert(0, X)` must be guarded by `if X not in sys.path:` (test files exempt). |
 | J12 | Hardcoded user paths | String literals naming a specific user's home directory (`C:/Users/jon/...`, `/Users/alice/...`, `/home/bob/...`). Use `pathlib.Path.home()`. |
 
-Test files (`test_*.py`, `*_test.py`, `*.test.*`, `*.spec.*`, `conftest.py`, paths under `/tests/`) are exempt from Category J except where the rule explicitly applies (e.g., J11 on `sys.path.insert`).
+The write-time hook (`code_rules_enforcer.py`) exempts test files (`test_*.py`, `*_test.py`, `*.test.*`, `*.spec.*`, `conftest.py`, paths under `/tests/`) from most Category J sub-buckets, and skips the naming, logging, annotation, and unused-import rules on `.mjs` / `.js` files. J11 (`sys.path.insert`) always applies. Read the next section for the sub-buckets this audit applies more widely than the hook.
+
+## Write-time exemptions do not scope this audit
+
+The write-time hook skips several rules on test files and on `.mjs` / `.js` files. This audit does not. Apply these rules to every changed line — production files, test files, and JavaScript files alike:
+
+- **Naming (J5, J6)** — banned identifiers (`ctx`, `cfg`, `msg`, `result`, `data`, `output`, `value`, `item`, `temp`, `elem`, `val`, …) and banned function prefixes (`handle_`, `process_`, `manage_`, `do_`); boolean names prefixed `is_` / `has_` / `should_` / `can_` / `was_` / `did_`.
+- **Logging format (J9)** — the format string and its arguments pass as separate parameters (`log_*("...", arg)`), never an f-string.
+- **Type annotations (J7)** — every changed function parameter and return is typed; no `Any`, no bare `# type: ignore`.
+- **Unused imports** — a module-level import a changed file does not read is a finding.
+- **Function length** — a changed function that runs past the length threshold splits into named helpers.
+
+A `test_*.py` name or a `.mjs` extension takes the line out of the write-time gate, not out of this audit. When the diff touches a test or a JavaScript file, walk these five rules against the changed lines there too. J1 (magic values) and J3 (constants location) keep their test-file exemption.
 
 ---
 

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

@@ -15,6 +15,25 @@ The label-vs-body gap is its own failure mode independent of behavior-equivalenc
 
 ---
 
+## 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 real 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.

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

@@ -0,0 +1,46 @@
+# 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 actual 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/CLAUDE.md

@@ -1,6 +1,6 @@
 # audit-rubrics/prompts
 
-Agent-ready audit prompt templates, one per category (A–P). An agent inlines the artifact under review into the `[INLINE THE FULL ARTIFACT HERE]` placeholder and runs the prompt as-is.
+Agent-ready audit prompt templates, one per category (A–Q). An agent inlines the artifact under review into the `[INLINE THE FULL ARTIFACT HERE]` placeholder and runs the prompt as-is.
 
 ## Files
 
@@ -22,6 +22,7 @@ Agent-ready audit prompt templates, one per category (A–P). An agent inlines t
 | `category-n-test-name-scenario-verifier.md` | N — Test name / scenario verifier |
 | `category-o-docstring-vs-impl-drift.md` | O — Docstring vs implementation drift |
 | `category-p-name-vs-behavior-contract.md` | P — Name vs behavior contract |
+| `category-q-cross-surface-claims.md` | Q — Cross-surface claim consistency |
 
 ## Prompt structure
 

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

@@ -16,6 +16,7 @@ ID prefix: `find`.
 - 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.

package/audit-rubrics/prompts/category-j-code-rules-compliance.md

@@ -11,10 +11,22 @@ ID prefix: `find`.
 
 ## Source material
 
-Inline the artifact (full diff or full file contents) under a clearly delimited block below this section. Use the chunking guide in [`../source-material-section-types.md`](../source-material-section-types.md) to choose the right Source-material section type (full-diff, file-set, patch-series, or excerpt-with-context). Mark every line range that is in scope; mark explicitly which files are test files (exempt) and which are production.
+Inline the artifact (full diff or full file contents) under a clearly delimited block below this section. Use the chunking guide in [`../source-material-section-types.md`](../source-material-section-types.md) to choose the right Source-material section type (full-diff, file-set, patch-series, or excerpt-with-context). Mark every line range that is in scope; mark explicitly which files are test files and which are production.
 
 Replace this paragraph with the chunked source material before issuing the prompt.
 
+## Write-time exemptions do not scope this audit
+
+The write-time hook skips several rules on test files and on `.mjs` / `.js` files; this audit does not. Apply these rules to every changed line — production, test, and JavaScript files alike:
+
+- Naming (J5, J6) — banned identifiers and banned function prefixes; boolean names prefixed `is_` / `has_` / `should_` / `can_` / `was_` / `did_`.
+- Logging format (J9) — the format string and its arguments pass as separate parameters, never an f-string.
+- Type annotations (J7) — every changed parameter and return is typed; no `Any`, no bare `# type: ignore`.
+- Unused imports — a module-level import a changed file does not read.
+- Function length — a changed function past the length threshold splits into named helpers.
+
+A `test_*.py` name or a `.mjs` extension takes the line out of the write-time gate, not out of this audit. J1 (magic values) and J3 (constants location) keep their test-file exemption; the five rules above do not.
+
 ## Sub-buckets (each requires Shape A finding OR Shape B with ≥3 adversarial probes)
 
 **J1. Magic values in production function bodies**
@@ -40,18 +52,18 @@ Replace this paragraph with the chunked source material before issuing the promp
 - Adversarial probes: (a) is any imported constant referenced only once in the importing file (suggesting the import itself is gratuitous)? (b) is any helper function defined in a production file but never called from inside the same file (separate dead-code concern, surfaced here for completeness)? (c) does any constant in `config/` get imported from zero call sites across the repo?
 
 **J5. Abbreviations**
-- Walk every parameter, local, and attribute name in production code. Flag: `ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `elem`, `val`, `tmp`, `str`, `num`, `arr`, `obj`, `fn`, `cb`, `req`, `res`. Loop counters `i`/`j`/`k` and `e` for exceptions are exempt.
-- Test files are exempt.
+- Walk every parameter, local, and attribute name across production, test, and JavaScript changed lines. Flag: `ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `elem`, `val`, `tmp`, `str`, `num`, `arr`, `obj`, `fn`, `cb`, `req`, `res`. Loop counters `i`/`j`/`k` and `e` for exceptions are exempt.
+- This audit walks changed test-file and `.mjs` / `.js` lines for this rule, even though the write-time hook skips them.
 - Adversarial probes: (a) is there a borderline name (e.g., `removed`, `arguments`) that someone might mis-classify as an abbreviation but is actually a full English word? Confirm. (b) does any callback / parameter / attribute use a short variant of a domain term that is technically a full word but conventionally abbreviates a longer one? (c) does any variable in a comprehension or lambda use a single letter outside the `i`/`j`/`k`/`e` exemption?
 
 **J6. Vague names**
 - Flag any name from the vague list: `result`, `data`, `output`, `response`, `value`, `item`, `temp`, `info`, `stuff`, `thing`. Vague verb prefixes for function names: `handle`, `process`, `manage`, `do`.
-- Test files are exempt.
+- This audit walks changed test-file and `.mjs` / `.js` lines for this rule, even though the write-time hook skips them.
 - Adversarial probes: (a) does any local variable use a domain-adjacent name that is actually on the vague list (e.g., `result` from a parser, `data` from a fetch)? (b) does any newly-introduced function name start with a vague prefix? (c) does any public attribute / dict key use a vague label that the call site has to disambiguate by surrounding context?
 
 **J7. Type hints**
-- Walk every function in production files. Verify parameter and return types are present, no `Any`, no `# type: ignore`.
-- Test files are exempt.
+- Walk every function across production, test, and JavaScript changed lines. Verify parameter and return types are present, no `Any`, no `# type: ignore`.
+- This audit walks changed test-file and `.mjs` / `.js` lines for this rule, even though the write-time hook skips them.
 - Adversarial probes: (a) does any production function rely on inferred return type from a single `return` path? (b) does any parameter use a string-quoted forward reference that masks `Any`? (c) is there a `# type: ignore` anywhere? Grep the diff explicitly.
 
 **J8. New inline comments**
@@ -64,7 +76,7 @@ Replace this paragraph with the chunked source material before issuing the promp
 **J9. Logging format**
 - Walk every `log_*(...)` call. Must be `log_*("template with {}", arg)`, not `log_*(f"...")`.
 - The rule applies to the project's structured `log_*` family, not stdlib `print`. `print` f-strings are J2-scope (string-template magic), not J9-scope.
-- Test files are exempt.
+- This audit walks changed test-file and `.mjs` / `.js` lines for this rule, even though the write-time hook skips them.
 - Adversarial probes: (a) is there any imported `log_*` function in production code that uses an f-string? (b) is there a logger-equivalent call (e.g., `logger.info(f"...")` from `logging` stdlib) that should be subject to the same rule? (c) does any non-Python logger family (e.g., `console.log`, `Write-Host`, structured-log helpers) appear with a template-string pattern that mirrors the J9 anti-pattern?
 
 **J10. Imports inside functions**

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

@@ -19,6 +19,20 @@ ID prefix: `find`.
 
 [INLINE each fresh identifier in context — the constant declaration with the value, the function signature with the body, the flag with every assignment / reset site, the regex source with surrounding usage.]
 
+## Binding counterexample protocol (run before every Shape B "clean" verdict)
+
+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:
+
+- One intended match the pattern must catch.
+- One near-miss the pattern must reject (hyphen vs underscore, a value reference vs a declaration, a substring of a longer word).
+- One structural edge that stresses the scanner: a destructured parameter, a quoted key, a nested brace, an escaped delimiter.
+
+Record what the pattern returns for each input. A wrong answer on any input is a Shape A finding, cited with the breaking input; a clean verdict is earned only after all three inputs return the contract's answer. `hooks/blocking/` is the priority surface — its patterns gate every write.
+
+Two canonical failures to probe for:
+- A brace scan that counts from the signature `(` and reads a destructured parameter (`renderRow({ id, label })`) as the start of the function body.
+- A `\bschema\b` pattern that matches the value in `{ label: schema }`, not just the `schema` declaration it targets.
+
 ## Sub-buckets (each requires Shape A finding OR Shape B with ≥3 adversarial probes)
 
 **P1. Boolean / flag names assert state the body keeps**

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

@@ -0,0 +1,51 @@
+Audit [REPO/ARTIFACT] [TARGET_ID] for **Category Q only** (cross-surface claim consistency — terminology, PR-description claims, message-vs-guard). Skip A–P. Sub-bucket forced-exhaustion mode: Category Q is decomposed into 3 sub-buckets below. Each sub-bucket needs 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 / one-line summary: [TITLE]
+- Base ref / SHA (state before the change): [BASE_SHA]
+- Head ref / SHA at audit time (state after the change): [HEAD_SHA]
+- Changed surfaces (file + line range + symbol/region name): [CHANGED_SURFACES]
+- New or read identifiers, API fields, and config keys the diff touches: [DIFF_TERMS]
+- Changed prose surfaces (README, doc tables, inline prose, log and error strings): [CHANGED_PROSE_SURFACES]
+- PR description body text: [PR_BODY]
+- Stated intent of the change: [INTENT]
+
+ID prefix: `find`.
+
+[ONE-PARAGRAPH FRAME: describe what the diff changed in plain English, naming the identifiers and config keys it introduces, the PR-body claims it makes, and the messages it adds or edits. State the audit goal: find any surface whose wording contradicts another surface that must agree with it — a prose term that misspells a code field, a PR-body claim the diff or repo does not bear out, or a message that asserts more than the guard gating it guarantees.]
+
+## Source material ([N] files/sections, all lines in scope)
+
+[INLINE THE FULL DIFF — the changed lines and enough surrounding context to show each identifier's definition and each message's guard.]
+
+[ALSO INLINE the PR description body text and every changed prose surface — README sections, doc tables, runbooks, log and error strings — so the agent can pair each claim with the code it names.]
+
+## Sub-buckets (each needs a Shape A finding OR Shape B with ≥3 adversarial probes)
+
+**Q1. Term sweep**
+- Pull out every identifier, API field, and config key the diff introduces or reads. For each, sweep all changed prose surfaces for a near-miss variant — a hyphen or a space in place of an underscore, a 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. Feed it the PR diff, then adjudicate each finding: a near-miss can be an intentional distinct term, so cite the code definition and the prose line and judge whether they name the same thing.
+- Adversarial probes when the sweep is clean: (a) check camelCase versus snake_case spellings of the same field across code and docs; (b) check singular/plural drift on collection field names; (c) check a shared-prefix family (`retry_budget`, `retry_count`, `retry_limit`) for a doc that names the wrong member.
+
+**Q2. PR-description claim verification**
+- Read the PR body. List each falsifiable claim — a dead-code removal, a performance or ceiling number, a "last caller" assertion, a "no remaining X" cleanup claim.
+- Verify each claim two ways against the diff and the repo. A dead-code claim gets a reference search across the repo for the named symbol. A ceiling or performance claim gets checked against the actual config value the diff sets and the call sites it touches. Cite the PR-body line and the diff or repo line that confirms or contradicts it.
+- Adversarial probes when the body looks correct: (a) search the repo for a surviving caller of any symbol the body calls dead; (b) compare each stated number against the config constant the diff sets; (c) check whether a "this finishes the cleanup" claim leaves a matching pattern in an unchanged sibling file.
+
+**Q3. Message-vs-guard consistency**
+- For every log, error, and evidence string the diff adds or edits, read the branch condition that gates it. The message text matches what that guard guarantees: a string asserting an outcome fires only on a branch that reaches the outcome.
+- Check temporal wording against the lifetime of the state variable the message names: "this run" versus "this round", "is open" versus "was opened", "reached" versus "attempted". Cite the message line and the guard or state-variable line.
+- Adversarial probes when messages look aligned: (a) trace each success message back to the return value or flag it claims and confirm the branch cannot reach it with the opposite value; (b) check every "missing" / "not found" error against the exception class the branch actually catches; (c) check every counter-based message against where the counter resets.
+
+## Cross-bucket questions to answer at the end
+
+Q-a: Which single claim in this change is most likely to mislead a reader at runtime — a prose term that names a field the code does not define, a PR-body fact the diff contradicts, or a message that overstates its guard? Cite both surfaces by `path:line`.
+
+Q-b: Which surface is the strongest witness to the contradiction — the doc, PR body, or message a reader would trust while the code says otherwise?
+
+Q-c: Is there a term the diff introduces that appears correct in the code yet drifts across two or more prose surfaces at once? Cite each prose line and the code definition.
+
+## Output
+
+Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket Q1-Q3, produce Shape A or Shape B (with ≥3 probes). Each Shape A finding cites BOTH surfaces — the claim and the surface that contradicts it — by `path:line`. The `failure_mode` describes the contradiction between the two surfaces. Cross-bucket Q-a through Q-c answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 cross-surface contradictions — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.