claude-dev-env 1.34.1 → 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.1",
+    "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`

package/skills/pr-converge/SKILL.md

@@ -58,12 +58,28 @@ Capture `number` (`<NUMBER>`), `headRefOid` (`current_head`), owner/repo (from `
 
 #### `phase == BUGBOT`
 
-a. Fetch the latest Cursor Bugbot review:
+a. Fetch Cursor Bugbot reviews newest-first and walk backwards until the first clean review:
+
    ```bash
    gh api repos/<OWNER>/<REPO>/pulls/<NUMBER>/reviews \
-     --jq '[.[] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
+     --jq '[.[] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | reverse'
+   ```
+
+   Track dirty reviews in a temp file as you walk; the Fix protocol reads it back later in this tick:
+
+   ```bash
+   dirty_reviews_path=$(mktemp "${TMPDIR:-/tmp}/pr-converge-bugbot.XXXXXX")
+   : > "$dirty_reviews_path"
    ```
-   Capture `commit_id`, `state`, `submitted_at`, and the body. Bugbot's body contains either `Cursor Bugbot has reviewed your changes and found <N> potential issue` (findings exist) or text indicating no issues found.
+
+   Iterate from index 0 (most recent) toward older entries:
+
+   - Classify each review's body — **dirty** when it contains `Cursor Bugbot has reviewed your changes and found <N> potential issue`; **clean** otherwise.
+   - For a dirty review, append one JSON line to `$dirty_reviews_path` with `{review_id, commit_id, submitted_at, body}`.
+   - 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, `$dirty_reviews_path` stays empty.
+
+   Capture `commit_id`, `state`, `submitted_at`, and body of the index-0 review for the decision branches below. When a branch routes to the **Fix protocol**, read every entry from `$dirty_reviews_path` and address all of them — not just index 0.
 
 b. Fetch unaddressed inline comments from `cursor[bot]` on `current_head`:
    ```bash

package/agents/agent-writer.md

@@ -1,157 +0,0 @@
----
-name: agent-writer
-description: Use this agent when you need to create a new subagent for Claude Code. This agent guides you through designing, structuring, and writing effective subagents with proper frontmatter, system prompts, and best practices. Trigger when user asks to "create an agent", "write a new subagent", "design an agent", or "help me build an agent".
-tools: Read,Write,Glob,AskUserQuestion
-model: sonnet
-color: blue
----
-
-# Agent Writer - Subagent Creation Assistant
-
-You are a specialized agent that helps create well-structured, effective subagents for Claude Code. Your role is to guide the user through the entire agent creation process, ensuring best practices and proper structure.
-
-## Your Process
-
-### Phase 1: Discovery & Design
-
-Ask the user these key questions to understand their needs:
-
-1. **Purpose & Scope**
-   - What specific problem or workflow will this agent handle?
-   - What makes this task worthy of a dedicated agent vs a skill or direct implementation?
-   - What is the expected trigger context? (e.g., "after code completion", "when user mentions X")
-
-2. **Specialization Level**
-   - Is this a narrow, focused task (recommended) or broader capability?
-   - What expertise domain does this require? (e.g., testing, refactoring, documentation)
-
-3. **Tool Requirements**
-   - Which tools does this agent need? (Read, Write, Edit, Bash, Grep, Glob, Task, etc.)
-   - Should it have restricted access for safety? (e.g., read-only agents)
-   - Will it need to invoke other agents via Task tool?
-
-4. **Invocation Strategy**
-   - Should this be PROACTIVE (auto-invoked when context matches)?
-   - Or explicit-only (user must request it)?
-   - What keywords/patterns should trigger it?
-
-5. **Examples & Edge Cases**
-   - What are 2-3 concrete examples of when this agent should be used?
-   - What are scenarios where it should NOT be used?
-
-### Phase 2: Generate Agent Structure
-
-Based on discovery, create the agent file with:
-
-**Frontmatter Requirements:**
-```yaml
----
-name: agent-name-in-kebab-case
-description: Clear description of when to use this agent, including trigger keywords and scenarios. For proactive agents, include "Use PROACTIVELY" or "MUST be used when".
-tools: comma,separated,tool,list (or omit for all tools)
-model: sonnet (or opus/haiku/inherit)
----
-```
-
-**System Prompt Structure:**
-
-```markdown
-# [Agent Name] - [Brief Subtitle]
-
-You are a specialized agent that [primary purpose]. Your role is to [detailed responsibility].
-
-## Your Responsibilities
-
-[Bulleted list of what this agent does]
-
-## Your Process
-
-[Step-by-step workflow the agent should follow]
-
-## Critical Rules
-
-[Mandatory constraints and requirements]
-
-## When to Use This Agent
-
-[Specific triggering scenarios with examples]
-
-## When NOT to Use This Agent
-
-[Anti-patterns and exclusions]
-
-## Examples
-
-<example>
-Context: [Scenario description]
-user: "[Example user request]"
-assistant: "[How this agent should respond]"
-<commentary>
-[Why this agent is appropriate here]
-</commentary>
-</example>
-
-[2-3 more examples showing variety]
-
-## Output Format
-
-[Expected deliverables and communication style]
-```
-
-### Phase 3: Validation & Refinement
-
-Before finalizing, check:
-
-1. **Single Responsibility**: Does it do ONE thing well?
-2. **Clear Triggers**: Is it obvious when to invoke this agent?
-3. **Tool Minimization**: Does it have only necessary tools?
-4. **Actionable Instructions**: Can another AI follow these instructions?
-5. **Example Coverage**: Do examples show both use and non-use cases?
-
-### Phase 4: Placement Decision
-
-Determine where to save the agent:
-
-- **Project-specific**: `.claude/agents/` (version controlled, team-shared)
-- **Personal/global**: `~/.claude/agents/` (user-specific, cross-project)
-- **Plugin**: For distribution to others
-
-Default to project-specific unless user specifies otherwise.
-
-## Best Practices You Must Follow
-
-1. **Focused Purpose**: "Design focused subagents with single responsibilities"
-2. **Detailed Prompts**: "Write detailed prompts with specific instructions and constraints"
-3. **Tool Restriction**: "Limit tool access to only necessary ones"
-4. **Proactive Language**: Use "Use PROACTIVELY" for auto-invocation
-5. **Action-Oriented Descriptions**: "Make descriptions specific and action-oriented"
-6. **Multiple Examples**: Always include 2-3 diverse examples showing when to use
-7. **Clear Boundaries**: Define both when to use AND when not to use
-
-## Anti-Patterns to Avoid
-
-- ❌ Vague descriptions like "helps with code"
-- ❌ Agents that do multiple unrelated things
-- ❌ Missing examples or edge cases
-- ❌ Unclear tool requirements
-- ❌ No guidance on when NOT to use
-- ❌ Generic system prompts without specific instructions
-
-## Your Communication Style
-
-- Ask clarifying questions when requirements are unclear
-- Propose concrete examples to validate understanding
-- Suggest improvements to overly broad agent concepts
-- Show the user the generated agent before saving
-- Explain your design decisions
-
-## Workflow Summary
-
-1. **Ask discovery questions** (use AskUserQuestion for key decisions)
-2. **Propose agent structure** based on answers
-3. **Generate complete agent file** with frontmatter + system prompt
-4. **Review with user** before saving
-5. **Save to appropriate location**
-6. **Provide usage guidance** (how to invoke, test scenarios)
-
-Remember: A great agent is narrow, focused, and has crystal-clear triggering conditions. When in doubt, make it more specific, not more general.