claude-dev-env 1.34.0 → 1.35.0

package/hooks/blocking/test_code_rules_enforcer_string_magic.py

@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+from pathlib import Path
+import importlib.util
+
+ENFORCER_PATH = Path(__file__).resolve().parent / "code_rules_enforcer.py"
+specification = importlib.util.spec_from_file_location(
+    "code_rules_enforcer", ENFORCER_PATH
+)
+code_rules_enforcer = importlib.util.module_from_spec(specification)
+specification.loader.exec_module(code_rules_enforcer)
+
+PRODUCTION_FILE_PATH = "packages/app/services/foo.py"
+TEST_FILE_PATH = "packages/app/tests/test_foo.py"
+CONFIG_FILE_PATH = "packages/app/config/constants.py"
+
+
+def test_should_flag_env_var_name_string_in_function_body() -> None:
+    source = (
+        "import os\n"
+        "\n"
+        "def fetch_secret() -> str:\n"
+        "    return os.environ['STRIPE_SECRET']\n"
+    )
+    issues = code_rules_enforcer.check_string_literal_magic(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert any("STRIPE_SECRET" in each_issue for each_issue in issues), (
+        f"Expected env-var name flagged, got: {issues}"
+    )
+
+
+def test_should_flag_settings_key_all_caps_with_underscore() -> None:
+    source = "def lookup(settings: dict) -> str:\n    return settings['HOOKS_PATH']\n"
+    issues = code_rules_enforcer.check_string_literal_magic(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert any("HOOKS_PATH" in each_issue for each_issue in issues), (
+        f"Expected settings key flagged, got: {issues}"
+    )
+
+
+def test_should_flag_dotted_segment_string() -> None:
+    source = "def is_git_dir(path: str) -> bool:\n    return path.endswith('.git')\n"
+    issues = code_rules_enforcer.check_string_literal_magic(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert any(".git" in each_issue for each_issue in issues), (
+        f"Expected '.git' flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_single_letter_uppercase() -> None:
+    source = "def is_added(line: str) -> bool:\n    return line.startswith('A')\n"
+    issues = code_rules_enforcer.check_string_literal_magic(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"Single capital letter must not be flagged, got: {issues}"
+
+
+def test_should_not_flag_short_uppercase_acronym() -> None:
+    source = "def is_get(method: str) -> bool:\n    return method == 'GET'\n"
+    issues = code_rules_enforcer.check_string_literal_magic(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"Short acronym 'GET' must not be flagged, got: {issues}"
+
+
+def test_should_not_flag_human_readable_message() -> None:
+    source = (
+        "def fail() -> None:\n    raise RuntimeError('Could not connect to host')\n"
+    )
+    issues = code_rules_enforcer.check_string_literal_magic(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"Human-readable message must not be flagged, got: {issues}"
+
+
+def test_should_not_flag_lowercase_string() -> None:
+    source = "def get_label() -> str:\n    return 'hello'\n"
+    issues = code_rules_enforcer.check_string_literal_magic(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"Lowercase string must not be flagged, got: {issues}"
+
+
+def test_should_not_flag_module_level_string() -> None:
+    source = "DEFAULT_KEY = 'STRIPE_SECRET'\n"
+    issues = code_rules_enforcer.check_string_literal_magic(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"Module-level string must not be flagged (it IS the constant), got: {issues}"
+    )
+
+
+def test_should_not_flag_docstring() -> None:
+    source = (
+        "def consume() -> None:\n"
+        '    """STRIPE_SECRET is documented here for reference."""\n'
+        "    return None\n"
+    )
+    issues = code_rules_enforcer.check_string_literal_magic(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"Docstring must not be flagged, got: {issues}"
+
+
+def test_should_skip_in_test_files() -> None:
+    source = (
+        "import os\n"
+        "\n"
+        "def test_env() -> None:\n"
+        "    assert os.environ['STRIPE_SECRET'] == 'x'\n"
+    )
+    issues = code_rules_enforcer.check_string_literal_magic(source, TEST_FILE_PATH)
+    assert issues == [], f"Test files exempt, got: {issues}"
+
+
+def test_should_skip_in_config_files() -> None:
+    source = "def env_keys() -> list[str]:\n    return ['STRIPE_SECRET', 'DB_HOST']\n"
+    issues = code_rules_enforcer.check_string_literal_magic(source, CONFIG_FILE_PATH)
+    assert issues == [], f"Config files exempt, got: {issues}"
+
+
+def test_should_not_flag_default_argument_string_literal() -> None:
+    source = (
+        "def consume(key: str = 'STRIPE_SECRET') -> str:\n"
+        "    return key\n"
+    )
+    issues = code_rules_enforcer.check_string_literal_magic(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"Default argument value (signature, not body) must not be flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_decorator_string_literal() -> None:
+    source = (
+        "from functools import lru_cache\n"
+        "\n"
+        "def cache_with_tag(tag: str):\n"
+        "    return lru_cache\n"
+        "\n"
+        "@cache_with_tag('STRIPE_SECRET')\n"
+        "def consume() -> str:\n"
+        "    return 'hello'\n"
+    )
+    issues = code_rules_enforcer.check_string_literal_magic(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"Decorator argument (not body) must not be flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_annotation_literal_type_argument() -> None:
+    source = (
+        "from typing import Literal\n"
+        "\n"
+        "def consume(method: Literal['STRIPE_SECRET']) -> str:\n"
+        "    return method\n"
+    )
+    issues = code_rules_enforcer.check_string_literal_magic(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"Literal type annotation (signature, not body) must not be flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_default_arg_of_nested_function_when_scanning_outer() -> None:
+    source = (
+        "def outer() -> None:\n"
+        "    def inner(key: str = 'STRIPE_SECRET') -> str:\n"
+        "        return key\n"
+        "    return None\n"
+    )
+    issues = code_rules_enforcer.check_string_literal_magic(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"Nested function's default arg (signature) must not be flagged from outer scan, got: {issues}"
+    )
+
+
+def test_should_flag_class_attribute_in_nested_class_body() -> None:
+    source = (
+        "def outer() -> str:\n"
+        "    class Inner:\n"
+        "        attribute: str = 'STRIPE_SECRET'\n"
+        "    return 'no_magic_here'\n"
+    )
+    issues = code_rules_enforcer.check_string_literal_magic(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert any("STRIPE_SECRET" in each_issue for each_issue in issues), (
+        f"Nested ClassDef body executes when outer() runs; class attribute must be flagged, got: {issues}"
+    )
+
+
+def test_should_flag_class_attribute_in_nested_class_inside_function() -> None:
+    source = (
+        "def outer() -> None:\n"
+        "    class Inner:\n"
+        "        KEY: str = 'STRIPE_SECRET'\n"
+        "    return None\n"
+    )
+    issues = code_rules_enforcer.check_string_literal_magic(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert any("STRIPE_SECRET" in each_issue for each_issue in issues), (
+        f"Class-level attribute inside a nested ClassDef inside outer fn body must be flagged "
+        f"(it executes when outer() runs), got: {issues}"
+    )
+
+
+def test_should_still_flag_literal_in_nested_function_body() -> None:
+    source = (
+        "def outer() -> str:\n"
+        "    def inner() -> str:\n"
+        "        return 'STRIPE_SECRET'\n"
+        "    return inner()\n"
+    )
+    issues = code_rules_enforcer.check_string_literal_magic(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert any("STRIPE_SECRET" in each_issue for each_issue in issues), (
+        f"Inner function's body magic literal must still be flagged via inner scan, got: {issues}"
+    )
+    assert len(issues) == 1, (
+        f"Inner literal must be flagged exactly once (no duplicate from outer walk), got: {issues}"
+    )

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.34.0",
+    "version": "1.35.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/skills/bugteam/PROMPTS.md

@@ -35,47 +35,8 @@ cd into `<worktree_path>` before any git, gh, or file operation.
   H. Security boundaries (injection, path traversal, auth bypass, secret leakage)
   I. Concurrency hazards (race conditions, missing awaits, shared mutable state)
   J. Magic values and configuration drift
-  Copilot-derived addendum (K–N) — verify each one explicitly. Return at
-  least one finding per category OR a verified-clean entry that names the
-  exact files and lines you walked.
-  K. Collection naming. Every tuple, list, set, dict, mapping, or sequence
-     parameter must follow the CODE_RULES.md §5 "Extended naming rules"
-     prefix discipline:
-       - module-level constant whose value is a tuple/list/set/dict/frozenset
-         literal MUST start with `ALL_` (e.g. `ALL_THEMES_INSERT_REQUIRED_COLUMN_NAMES`)
-       - function/method parameter whose annotation is `list[...]`, `tuple[...]`,
-         `set[...]`, `dict[...]`, `Iterable[...]`, `Sequence[...]`, `Mapping[...]`,
-         or `frozenset[...]` MUST start with `all_` (e.g. `all_column_value_pairs`)
-       - exempt: dict/map names that follow the `X_by_Y` pattern (e.g.
-         `price_by_product`)
-  L. Library print / direct stdout. In any module that is not a CLI entry
-     point (`__main__`, `*_cli.py`, `scripts/*.py`), every `print(...)`,
-     `sys.stdout.write(...)`, `sys.stderr.write(...)` call is a finding.
-     The fix is to route through a `logger` call OR to make the output
-     stream an explicit parameter so callers can redirect it.
-  M. String-literal magic values. Treat domain-identifier string literals
-     (database column names, table names, HTTP header names, status enums,
-     environment-variable names) inside a function body as magic values
-     even when the existing number-only check would let them pass. The
-     fix is to extract them into `config/` and reference the imported
-     name. Do not flag plain log messages, error messages, or one-off
-     human-readable strings.
-  N. Wrapper plumb-through. When a public function delegates to an
-     inner function defined in the same package, every optional kwarg
-     accepted by the inner function MUST appear in the public wrapper
-     unless the wrapper docstring explicitly states the kwarg is fixed
-     to a sentinel default. Silently dropping `loud_banner_stream`,
-     `timeout`, `dry_run`, or any similar optional kwarg is a finding.
 </bug_categories>
 
-<copilot_derived_addendum_source>
-  The K–N categories were added after Copilot raised real findings on
-  PR #70 (writer.py / summary.py) and PR #73 (constants.py / writer.py /
-  tracker.py) that converged "0 P0 / 0 P1 / 0 P2" under the original
-  A–J rubric. See ~/.claude/skills/bugteam/reference/copilot-gap-analysis.md
-  for the inventory and the validators that now back categories K and L.
-</copilot_derived_addendum_source>
-
 <constraints>
   - Read-only on source code: the audit does not modify any source file.
   - Cite file:line for every finding.

package/skills/bugteam/SKILL.md

@@ -81,9 +81,7 @@ The fix script removes any non-canonical local-scope override on the active repo
 [ ] Step 0: project permissions granted
 [ ] Step 1: PR scope resolved
 [ ] Step 2: agent team created + loop state set
-[ ] Step 2.6: INITIAL standards review against cumulative PR diff
 [ ] Step 3: cycle complete (converged | cap reached | stuck | error)
-[ ] Step 3.5: FINAL standards review against cumulative PR diff
 [ ] Step 4: team torn down + working tree clean
 [ ] Step 4.5: PR description rewritten (or skip warning logged)
 [ ] Step 5: project permissions revoked
@@ -143,7 +141,7 @@ TeamCreate(
 ```bash
 loop_count=0
 last_action="fresh"
-last_findings=""
+last_findings='{"total": 0}'
 audit_log=""
 starting_sha="$(git rev-parse HEAD)"
 team_name="bugteam-pr-<number>-<YYYYMMDDHHMMSS>"
@@ -205,29 +203,28 @@ jq -n \
 
 **Endpoints:** `POST .../pulls/{pull}/reviews`; `POST .../pulls/{pull}/comments/{id}/replies`; fallback `POST .../issues/{issue}/comments` (`issue` = PR number).
 
-### Step 2.6: INITIAL standards review (once, before Loop 1 audit)
-
-Run BEFORE the first pre-audit gate fires. Spawn a fresh `code-quality-agent`
-teammate inside the same team and drive it through the K–N addendum (see
-PROMPTS.md `<copilot_derived_addendum_source>`). The teammate audits the
-cumulative PR diff (`gh pr diff <N>`) instead of a single loop's incremental
-patch; clean-room context is preserved by the same agent-team isolation as
-the per-loop bugfind teammate. Findings are posted using the same Step 2.5
-review-shape with body `## /bugteam INITIAL standards review against PR #<N>
-cumulative diff: <P0>P0 / <P1>P1 / <P2>P2`. Findings advance the audit/fix
-cycle exactly as if they had been raised in Loop 1: the lead increments
-`loop_count` to 1, sets `last_action = "audited"` with the merged
-`last_findings`, and Step 3 begins on the FIX branch. When the INITIAL
-review returns zero findings, `loop_count` stays at 0 and Step 3 begins on
-the AUDIT branch as before. Failure on this phase logs the error and
-proceeds to Step 3 unchanged so the legacy A–J cycle still runs.
-
 ### Step 3: The cycle
 
 Run the AUDIT-FIX cycle for each PR in all_prs, reusing the same team across PRs. The 10-loop cap applies per PR. Exit reasons (converged, cap reached, stuck, error) are tracked per PR; the final report lists one outcome line per PR.
 
 **Gate:** `validate_content` / `hooks/blocking/code_rules_enforcer.py` on PR-scoped files before every AUDIT (`bugteam_code_rules_gate.py`). Lead runs gate; clean-coder clears failures; then bugfind audits.
 
+**Pre-cycle: walk prior bugteam reviews end-first** (once per PR, after Step 2 and before iteration begins, when `last_action == "fresh"`). A re-invocation of `/bugteam` on a PR with prior loops detects whether the most recent loop already cleaned this HEAD (short-circuit) and otherwise records that prior loops were dirty so the AUDIT runs against the latest diff with that signal in mind:
+
+```bash
+dirty_review_count=0
+gh api "repos/<owner>/<repo>/pulls/<number>/reviews" \
+  --jq '[.[] | select(.body | startswith("## /bugteam loop "))] | sort_by(.submitted_at) | reverse'
+```
+
+Iterate from index 0 (most recent) toward older entries:
+
+- A bugteam review body that ends with `→ clean` is **clean**; any other `## /bugteam loop ...` body is **dirty**.
+- For a dirty review, increment `dirty_review_count` by one. The review's specific finding bodies are not carried forward — bugteam's AUDIT regenerates findings against the current HEAD's diff each loop, so prior bodies are stale by definition. The count alone is the carried signal.
+- Stop at the first clean review. Older reviews are presumed addressed at that clean checkpoint and are not re-read.
+- When index 0 is itself clean AND its `commit_id` matches `git rev-parse HEAD`, the PR is already converged on this HEAD — set `last_action="audited"`, `last_findings='{"total": 0}'`, fall through to step 1's `converged` exit, skip Step 3 iteration entirely.
+- When `dirty_review_count > 0`, log the count and proceed into the normal iteration; the next AUDIT regenerates anchored findings against the current HEAD so `loop_comment_index` stays correct. Unlike `pr-converge` — where Cursor Bugbot's prior dirty-review *bodies* are read back by the Fix protocol because each dirty body lists specific findings the loop must still address — bugteam's per-loop bodies are anchored to the diff at *that loop's* HEAD, so re-applying them against a newer diff would be incorrect. The count is sufficient signal that "prior loops did not converge here."
+
 1. From `last_action` / `last_findings`:
    - `last_action == "audited"` and `last_findings.total == 0` → exit `converged`
    - `last_action == "fixed"` and `git rev-parse HEAD` unchanged since pre-FIX → exit `stuck`
@@ -304,19 +301,6 @@ Pass finding comment URLs/ids from `loop_comment_index` in XML. Replies: `Fixed
 
 [`PROMPTS.md`](PROMPTS.md): fix XML + schema. Verify: `git rev-parse HEAD` advanced; `git fetch origin <branch> && git rev-parse origin/<branch>` matches `HEAD`. Unchanged HEAD → `stuck — bugfix teammate could not address findings`.
 
-### Step 3.5: FINAL standards review (once, after convergence)
-
-Run AFTER Step 3 exits with `converged`, `cap reached`, or `stuck`, and
-BEFORE Step 4 teardown. Spawn one more fresh `code-quality-agent` teammate;
-audit the cumulative PR diff against the K–N addendum a second time. Post
-the review with body `## /bugteam FINAL standards review against PR #<N>
-cumulative diff: <P0>P0 / <P1>P1 / <P2>P2`. When findings remain, the
-exit reason is upgraded to `error: final standards review found <P0>+<P1>+<P2>
-unresolved finding(s)` and the loop log gains an extra `final-review` line.
-A clean FINAL review preserves the existing exit reason. Failure on this
-phase logs the error and continues to Step 4 unchanged so teardown,
-permission revoke, and the final report still run.
-
 ### Step 4: Teardown
 
 1. For each live teammate: `SendMessage(to="<name>", message={"type": "shutdown_request", "reason": "bugteam cycle ending"})`. `approve: false` on cleanup → log and continue.
@@ -361,10 +345,8 @@ Final commit: <current_HEAD_sha7>
 Net change: <total_files> files, +<total_add>/-<total_del>
 
 Loop log:
-  initial standards review: 1P0 0P1 2P2
   1 audit: 3P0 2P1 0P2
   ...
-  final standards review: 0P0 0P1 0P2
 ```
 
 `cap reached` → suggest `/findbugs`. `stuck` → which findings. `error` → detail + loop.

package/skills/bugteam/reference/copilot-gap-analysis.md

@@ -1,5 +1,15 @@
 # Copilot gap analysis
 
+> **Status: HISTORICAL — patch plan partially superseded.**
+>
+> This file documents the read-only investigation that motivated the K–N rubric addendum and the Step 2.6 / Step 3.5 standards-review phases. **The audit-rubric portion of the patch plan was reverted in [PR #292](https://github.com/jl-cmd/claude-code-config/pull/292):** PROMPTS.md no longer carries the K–N addendum or the `<copilot_derived_addendum_source>` block, and SKILL.md no longer runs the Step 2.6 / Step 3.5 standards-review phases.
+>
+> **What replaced K–N (partial coverage):** several judgment-heavy categories now have deterministic validators in `code_rules_enforcer.py` — `check_collection_prefix` (category K), `check_library_print` (category L), `check_inline_literal_collections`, `check_loop_variable_naming`, `check_parameter_annotations`, `check_return_annotations`. These validators are exercised by `bugteam_code_rules_gate.py` during the bugteam pre-audit / loop, and by the shipped repo `pre-commit` / `pre-push` git hooks that invoke that gate. They are **not** wired into the repo's default `PreToolUse` Write|Edit hook list in `packages/claude-dev-env/hooks/hooks.json`, so they do not block at Write/Edit time by default — enforcement comes from the gate (audit-time) and the git hooks (commit/push-time).
+>
+> **What is NOT a full deterministic replacement (remaining limitations):** the string-literal magic case in this doc is largely about snake_case column / key / table-name literals (`"theme_name"`, `"content_id"`, etc.). `check_string_literal_magic` in `code_rules_enforcer.py` still only flags ALL-CAPS-WITH-UNDERSCORE identifiers and dotted segments, so it does **not** cover those snake_case database-column literals by itself. However, the gap called out in this document is no longer accurately described as “unimplemented”: `check_database_column_string_magic` and `check_wrapper_plumb_through` now exist in `bugteam_code_rules_gate.py` and run in the `/bugteam` gate, including via the shipped repo `pre-commit` / `pre-push` hooks that invoke that gate. The remaining limitation is coverage/wiring scope: these checks are gate-time / git-hook-time validators, not part of the repo's default `PreToolUse` Write|Edit hook path, and any residual misses should be described in terms of validator scope rather than absence.
+>
+> Read this file as **investigation history**: the inventory, rubric/validator coverage diffs, and root-cause statement remain useful context for future bugteam improvements. The "Patch plan" section below describes what was originally proposed, not the current state — references to category K, L, M, N or to Step 2.6 / Step 3.5 in the patch plan are historical and should not be reintroduced.
+
 This file is the reference record produced by the read-only investigation of why the `/bugteam` audit/fix loop and `bugteam_code_rules_gate.py` repeatedly miss the classes of code-quality violations that the GitHub Copilot reviewer raises on follow-up review rounds. It is written so future bugteam runs can skim the inventory, the rubric/validator coverage diffs, and the patch plan without re-deriving them.
 
 Sources of truth cited below: `~/.claude/docs/CODE_RULES.md`, `~/.claude/CLAUDE.md`, `~/.claude/rules/file-global-constants.md`, `~/.claude/skills/bugteam/SKILL.md`, `~/.claude/skills/bugteam/PROMPTS.md`, `~/.claude/skills/bugteam/CONSTRAINTS.md`, `~/.claude/skills/bugteam/scripts/bugteam_code_rules_gate.py`, `~/.claude/skills/bugteam/scripts/bugteam_preflight.py`, `~/.claude/hooks/blocking/code_rules_enforcer.py`, plus `gh api repos/JonEcho/python-automation/pulls/{70,73}/comments` filtered to author `Copilot`.
@@ -85,6 +95,8 @@ The bugteam audit rubric (PROMPTS.md §bug_categories A–J) and the determinist
 
 ## Patch plan
 
+> **Historical — the rubric/phases portion below was reverted in PR #292.** Sections (a) PROMPTS.md K–N addendum, (b) Step 2.6 INITIAL standards review, and the FINAL standards review (Step 3.5) were reverted and replaced by deterministic validators (see status banner at the top of this file). Sections that landed deterministic validators in `code_rules_enforcer.py` (collection prefix, library print, string-literal magic, inline literal collections, loop-variable naming, parameter/return annotations) remain in force. Treat the rubric/phase sections below as record-of-what-was-tried, not a current to-do list.
+
 Each section names exactly one target file, the literal text or regex to add, and a verification step that re-runs the new detection against the PR #70 / PR #73 diffs.
 
 ### a. `~/.claude/skills/bugteam/PROMPTS.md`