claude-dev-env 1.50.3 → 1.51.0

package/skills/auditing-claude-config/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: auditing-claude-config
-description: Audits a Claude Code setup (user CLAUDE.md, ~/.claude/rules/, project .claude/) for context-budget waste — duplicate @-imports, eagerly-loaded rules that should be path-scoped or converted to skills, oversized always-on files, and rules duplicating existing skills. Produces a migration table with line-count savings. Use when reviewing the always-on instruction load, when sessions feel sluggish, when /memory shows surprising loads, when adding new rules, or for periodic config hygiene. Optionally verifies findings empirically via an InstructionsLoaded probe hook that logs every load event with its load_reason and parent_file_path.
+description: >-
+  Audits a Claude Code setup (user CLAUDE.md, ~/.claude/rules/, project .claude/) for
+  context-budget waste — duplicate @-imports, always-on rules to path-scope or convert
+  to skills, oversized files — and produces a migration table with savings. Use when
+  reviewing the startup/instruction load, when /memory shows surprising loads, when
+  adding new rules, or for periodic config hygiene.
 ---
 
 # Auditing Claude Config

package/skills/bugteam/CONSTRAINTS.md

@@ -2,7 +2,7 @@
 
 ## Constraints
 
-- **Full A–N audit every loop, no exceptions.** PR size, "focused audit," "team overhead," "CODE_RULES already passed" — not valid reasons. Empty `<findings/>` for any category is a valid result. The audit agent walks all A–N rubrics each loop.
+- **Full A–P audit every loop, no exceptions.** PR size, "focused audit," "team overhead," "CODE_RULES already passed" — not valid reasons. Empty `<findings/>` for any category is a valid result. The audit agent walks all A–P rubrics each loop.
 - **One run per invocation, multi-PR supported.** All PRs in a single /bugteam invocation share one `run_temp_dir`. Per-PR identity lives in the subagent name prefix (`bugfind-pr<N>-loop<L>` / `bugfix-pr<N>-loop<L>`) and the `<run_temp_dir>/pr-<N>/` subfolder containing that PR's git worktree, diff patches, and outcome XML files.
 - **Grant before any spawn, revoke before any return.** Step 0 grants project `.claude/**` permissions; Step 5 revokes. Both are mandatory. Revoke runs on every exit path including error, cap-reached, and stuck.
 - **Fresh subagent per loop.** Both bugfind and bugfix are spawned new each loop. Reusing a subagent across loops accumulates context inside that subagent's window — defeats clean-room.

package/skills/bugteam/PROMPTS.md

@@ -24,7 +24,7 @@ cd into `<worktree_path>` before any git or file operation.
 </scope>
 
 <bug_categories>
-  Investigate each of the fourteen categories (A–N) explicitly. For each,
+  Investigate each of the sixteen categories (A–P) explicitly. For each,
   return either at least one finding OR a verified-clean entry with the
   evidence backing the verdict. A category is verified-clean only when one
   complete execution path through the changed code has been traced from
@@ -37,7 +37,7 @@ cd into `<worktree_path>` before any git or file operation.
   When evidence contains any of these phrases, the category is not
   verified-clean -- re-audit with a concrete trace.
 
-  Categories A–N (one-line summary; full rubric and sub-bucket
+  Categories A–P (one-line summary; full rubric and sub-bucket
   decomposition for each is in
   `$HOME/.claude/audit-rubrics/category_rubrics/`; ready-to-send Variant
   C prompts — each with a PR/repo-independent generalized skeleton above
@@ -58,6 +58,8 @@ cd into `<worktree_path>` before any git or file operation.
   L. Behavior-equivalence for refactors
   M. Producer/consumer cardinality vs collection-type contract
   N. Test-name scenario verifier
+  O. Docstring / fixture-prose vs implementation drift
+  P. Name / regex / word-list vs behavior-contract precision
 </bug_categories>
 
 <rubric_reference>
@@ -77,7 +79,7 @@ cd into `<worktree_path>` before any git or file operation.
 </constraints>
 
 <comment_posting>
-  Load all A–N rubrics from
+  Load all A–P rubrics from
   `$HOME/.claude/audit-rubrics/{category_rubrics,prompts}/`. The prompt file
   is a template for output shape, not a straitjacket — reorganize when the
   diff demands it. The diff supplies the findings; the rubric supplies the
@@ -88,7 +90,7 @@ cd into `<worktree_path>` before any git or file operation.
   done.
 
   <self_audit_checklist>
-    [ ] Walk all 14 categories (A–N), each with Shape A or Shape B
+    [ ] Walk all 16 categories (A–P), each with Shape A or Shape B
     [ ] Assign finding IDs (loop<L>-<K>)
     [ ] Capture excerpts, validate anchors, format finding bodies
     [ ] Build findings JSON, invoke post_audit_thread.py, capture html_url
@@ -96,7 +98,7 @@ cd into `<worktree_path>` before any git or file operation.
     [ ] Write outcome XML
   </self_audit_checklist>
 
-  1. Audit the diff against the 14 categories above. Buffer the findings
+  1. Audit the diff against the 16 categories above. Buffer the findings
      in memory; all posting happens at step 4 once anchors are validated.
   2. Assign each finding a stable finding_id of exactly the form `loop<L>-<K>`
      where <K> is 1-based within this loop.
@@ -227,7 +229,7 @@ attributes.
 </bugteam_audit>
 ```
 
-Verified-clean evidence per A–N category is surfaced in the agent's text-mode
+Verified-clean evidence per A–P category is surfaced in the agent's text-mode
 final report, not in this outcome XML (the writer accepts a flat findings list
 only).
 

package/skills/bugteam/SKILL.md

@@ -11,10 +11,10 @@ description: >-
 # Bugteam
 
 Audit–fix until convergence. Bugfind: `code-quality-agent`, fresh context each
-loop, auditing all A–N categories. Bugfix: `clean-coder`. Hard cap: 20 audit
+loop, auditing all A–P categories. Bugfix: `clean-coder`. Hard cap: 20 audit
 loops. Grant `.claude/**` at start, revoke always at end.
 
-The audit agent loads the A–N category rubrics from
+The audit agent loads the A–P category rubrics from
 `$HOME/.claude/audit-rubrics/{category_rubrics,prompts}/` alongside
 [`PROMPTS.md`](PROMPTS.md) and produces a single outcome XML per loop.
 
@@ -146,7 +146,7 @@ end-to-end mental model before starting Step 0.
 | Posting the end-of-pass audit review via `post_audit_thread.py` (APPROVE on CLEAN — the request event; GitHub stores it as `state=APPROVED` — REQUEST_CHANGES with inline anchored comments on DIRTY) | [§ Audit posting](#audit-posting) |
 | Posting per-finding fix replies via GitHub MCP `add_reply_to_pull_request_comment` (rendered with the unified template at [`_shared/pr-loop/audit-reply-template.md`](../../_shared/pr-loop/audit-reply-template.md)) | [reference/github-pr-reviews.md](reference/github-pr-reviews.md) |
 | Teardown, PR description rewrite via `pr-description-writer`, permission revoke, final report | [reference/teardown-publish-permissions.md](reference/teardown-publish-permissions.md) |
-| Spawn-prompt XML, A–N category bindings, outcome XML schemas | [PROMPTS.md](PROMPTS.md) |
+| Spawn-prompt XML, A–P category bindings, outcome XML schemas | [PROMPTS.md](PROMPTS.md) |
 | Per-category audit content (sub-buckets, decision criteria, ready-to-send Variant C templates) | `$HOME/.claude/audit-rubrics/{category_rubrics,prompts}/` |
 | Invariants and design rationale | [CONSTRAINTS.md](CONSTRAINTS.md), [reference/design-rationale.md](reference/design-rationale.md) |
 | Audit-contract finding shape (Shape A / B), Haiku secondary, post-fix self-audit | [reference/audit-contract.md](reference/audit-contract.md) |
@@ -159,11 +159,11 @@ end-to-end mental model before starting Step 0.
 - `SKILL.md` — this hub.
 - `reference/` — workflow detail per situation.
 - `scripts/` — utility scripts executed, not loaded as primary context.
-- `PROMPTS.md` — spawn XML, A–N category bindings, outcome schemas.
+- `PROMPTS.md` — spawn XML, A–P category bindings, outcome schemas.
 - `CONSTRAINTS.md` — invariants.
 - `EXAMPLES.md` — exit scenarios.
 - `sources.md` — doc URLs and verbatim quotes.
 - `~/.claude/audit-rubrics/` — installed by `npx claude-dev-env` from
-  `packages/claude-dev-env/audit-rubrics/`; the audit agent reads all A–N
+  `packages/claude-dev-env/audit-rubrics/`; the audit agent reads all A–P
   rubrics under `category_rubrics/` and prompts under `prompts/`. Required
   at audit time alongside `PROMPTS.md`.

package/skills/bugteam/reference/audit-and-teammates.md

@@ -116,7 +116,7 @@ Repeat until an exit condition fires.
 
 ## AUDIT action
 
-Spawn one audit agent that walks all A–N categories:
+Spawn one audit agent that walks all A–P categories:
 
 ```
 Agent(

package/skills/bugteam/reference/audit-contract.md

@@ -21,7 +21,7 @@ Each finding an audit produces MUST be one of exactly two shapes.
   "id": "loop<L>-<K>",
   "file": "path/relative/to/repo/root.py",
   "line": 123,
-  "category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N",
+  "category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P",
   "severity": "P0 | P1 | P2",
   "excerpt": "verbatim code snippet from the offending line(s)",
   "failure_mode": "one sentence describing what goes wrong and when",
@@ -37,7 +37,7 @@ Used when an audit investigates a category and does NOT find a bug. Bare "verifi
 
 ```json
 {
-  "category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N",
+  "category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P",
   "files_opened": ["file1.py", "file2.py"],
   "lines_quoted": [
     {"file": "file1.py", "line": 88, "text": "verbatim line content"}
@@ -89,7 +89,7 @@ After the primary finding list is complete, every audit runs a second pass again
 
 The audit must either produce new Shape A findings citing new file:line references not present in the first pass, or cite explicit Shape B adversarial-probe entries for each category it re-examined. An adversarial pass that returns "nothing new, confident first pass was complete" is REJECTED — produce evidence or findings, not confidence.
 
-For `/bugteam`, the single audit agent provides per-category coverage by walking all A–N rubrics in one invocation.
+For `/bugteam`, the single audit agent provides per-category coverage by walking all A–P rubrics in one invocation.
 
 ## Merge rules
 
@@ -113,7 +113,7 @@ Sequence:
 3. Run `py_compile` (or language-equivalent) on each modified file.
 4. Compute `fix_diff` against pre-fix contents for the modified set.
 5. Run `bugteam_code_rules_gate.py` with explicit paths for every modified file.
-6. Spawn a scoped audit of `fix_diff` with full A–N rigor, Shape A/B contract, adversarial pass, AND Haiku secondary in parallel (paranoid mode on post-fix).
+6. Spawn a scoped audit of `fix_diff` with full A–P rigor, Shape A/B contract, adversarial pass, AND Haiku secondary in parallel (paranoid mode on post-fix).
 7. Any new findings become same-loop fix-targets. Internal iteration count increments by one.
 8. After 3 internal iterations with fresh findings each time, exit `stuck: post-fix audit not converging`.
 9. Only when `gate_findings` empty AND `post_fix_findings` empty: `git add`, commit, push.

package/skills/bugteam/reference/design-rationale.md

@@ -2,7 +2,7 @@
 
 ## Core principle (expanded)
 
-One audit agent (`code-quality-agent`, opus) walks all A–N categories per loop. One fix agent (`clean-coder`, opus) addresses the audit's findings.
+One audit agent (`code-quality-agent`, opus) walks all A–P categories per loop. One fix agent (`clean-coder`, opus) addresses the audit's findings.
 
 Fresh-spawn clean-room isolation: each `Agent` call creates a new subagent with its own context window and no access to prior conversation. After the subagent writes its outcome XML and self-terminates, the lead reads the file. Results never accumulate in the lead’s context beyond the XML artifact. Verbatim Anthropic quotes and URLs: [`../sources.md`](../sources.md).
 

package/skills/bugteam/reference/obstacles/audit-walk-categories.md

@@ -1,6 +1,6 @@
 # Walk categories
 
-Audit every category A through K. Each returns Shape A finding or Shape B verified-clean. No skipped categories.
+Audit every category A through P. Each returns Shape A finding or Shape B verified-clean. No skipped categories.
 
 ## Self-population
 

package/skills/bugteam/reference/team-setup.md

@@ -17,11 +17,23 @@ python "${CLAUDE_SKILL_DIR}/scripts/bugteam_preflight.py"
 Non-zero → fix before grant. `BUGTEAM_PREFLIGHT_SKIP=1` emergency only.
 `--pre-commit` if `.pre-commit-config.yaml` exists.
 
-**Auto-remediation for `core.hooksPath`:** when preflight fails with stderr
-containing `core.hooksPath` (the message starts with `bugteam_preflight:
-core.hooksPath is`, or `Git-side CODE_RULES enforcement is not active`), Claude
-must auto-invoke the fix script — do not fall through to `AskUserQuestion`, do
-not punt to the user, do not ask for confirmation:
+**Self-heal for stale local-scope `core.hooksPath`:** preflight silently
+unsets ALL local-scope `core.hooksPath` entries on the active repository when
+two conditions both hold: at least one entry does not end in the canonical
+`hooks/git-hooks` suffix, AND a canonical global `core.hooksPath` is already
+configured. The check clears the `<repo>/.git/hooks` entry git can seed into a
+worktree's local config when `extensions.worktreeConfig` is set or seeding
+tooling is in use, so the canonical global setting takes effect without Claude
+needing to surface a failure or invoke the fix script. When the global is
+unset or non-canonical, the self-heal stands down so the downstream
+`core.hooksPath is '<path>'` diagnostic stays informative.
+
+**Auto-remediation for `core.hooksPath`:** when preflight reports stderr
+containing `core.hooksPath` (the message starts with
+`bugteam_preflight: core.hooksPath is`, or `Git-side CODE_RULES enforcement is
+not active`) — which surfaces when the global setting is missing or points
+elsewhere — Claude must auto-invoke the fix script. Do not fall through to
+`AskUserQuestion`, do not punt to the user, do not ask for confirmation:
 
 ```bash
 python "${CLAUDE_SKILL_DIR}/scripts/bugteam_fix_hookspath.py"

package/skills/bugteam/scripts/bugteam_preflight.py

@@ -36,7 +36,8 @@ _shared_pr_loop_scripts_directory = (
 if str(_shared_pr_loop_scripts_directory) not in sys.path:
     sys.path.insert(0, str(_shared_pr_loop_scripts_directory))
 
-from reviews_disabled import (
+from preflight_self_heal import silently_clear_stale_local_hooks_path_override  # noqa: E402
+from reviews_disabled import (  # noqa: E402
     CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN,
     CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME,
     EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV,
@@ -47,9 +48,17 @@ from reviews_disabled import (
 def verify_git_hooks_path(repository_root: Path | None) -> int:
     """Check that core.hooksPath resolves to the claude-dev-env git-hooks directory.
 
-    When *repository_root* is provided, queries the effective config for that
-    repository (``git -C <root> config --get``), which detects repo-level
-    overrides such as Husky or lefthook. Falls back to the current working
+    Silently clears any stale, non-canonical local-scope core.hooksPath
+    override before querying the effective config, so a worktree-seeded local
+    entry cannot shadow a correctly configured global setting. When
+    *repository_root* is provided, queries the effective config for that
+    repository (``git -C <root> config --get``). When a canonical global
+    ``core.hooksPath`` is already configured, the preceding self-heal step
+    clears non-canonical local-scope entries, so repo-level overrides such
+    as Husky or lefthook at local scope are silently removed in favor of
+    the canonical global; when the global is unset or non-canonical, the
+    self-heal stands down and the ``--get`` query still surfaces those
+    overrides through the failure path. Falls back to the current working
     directory's effective config when *repository_root* is None.
 
     Args:
@@ -60,12 +69,15 @@ def verify_git_hooks_path(repository_root: Path | None) -> int:
         Zero when the configured path ends with the expected hooks suffix.
         Non-zero and prints a correction message when unset or pointing elsewhere.
     """
+    silently_clear_stale_local_hooks_path_override(
+        repository_root, EXPECTED_HOOKS_PATH_SUFFIX
+    )
     git_command: list[str] = ["git"]
     if repository_root is not None:
         git_command.extend(["-C", str(repository_root)])
     git_command.extend(list(ALL_GIT_CONFIG_HOOKS_PATH_ARGUMENTS))
     try:
-        query_result = subprocess.run(
+        query_completed_process = subprocess.run(
             git_command,
             capture_output=True,
             text=True,
@@ -87,13 +99,13 @@ def verify_git_hooks_path(repository_root: Path | None) -> int:
             file=sys.stderr,
         )
         return EXIT_CODE_HOOKS_PATH_CHECK_FAILED
-    if query_result.returncode != 0:
+    if query_completed_process.returncode != 0:
         print(
             f"{BUGTEAM_PREFLIGHT_PREFIX}{ENFORCEMENT_ABSENT_MESSAGE}",
             file=sys.stderr,
         )
         return EXIT_CODE_HOOKS_PATH_CHECK_FAILED
-    configured_path = query_result.stdout.strip().replace("\\", "/").rstrip("/")
+    configured_path = query_completed_process.stdout.strip().replace("\\", "/").rstrip("/")
     if not configured_path.endswith(EXPECTED_HOOKS_PATH_SUFFIX):
         print(
             f"{BUGTEAM_PREFLIGHT_PREFIX}core.hooksPath is '{configured_path}' — "
@@ -178,20 +190,20 @@ def _pytest_exit_code_no_tests_collected() -> int:
     return PYTEST_EXIT_CODE_NO_TESTS_COLLECTED
 
 
-def run_pytest(repository_root: Path, verbose: bool) -> int:
+def run_pytest(repository_root: Path, is_verbose: bool) -> int:
     """Run pytest in the repository root and return the exit code.
 
     Treats the "no tests collected" exit code as a pass (exit 0).
 
     Args:
         repository_root: The repository root for running pytest.
-        verbose: When True, pass no -q flag (shows individual test names).
+        is_verbose: When True, pass no -q flag (shows individual test names).
 
     Returns:
         The pytest exit code, or 0 when no tests were collected.
     """
     command = [sys.executable, "-m", "pytest"]
-    if not verbose:
+    if not is_verbose:
         command.append("-q")
     completed = subprocess.run(
         command,

package/skills/bugteam/scripts/test_bugteam_preflight.py

@@ -282,3 +282,35 @@ def test_main_should_halt_when_env_var_contains_uppercase_or_whitespace_bugteam_
     monkeypatch.delenv("BUGTEAM_PREFLIGHT_SKIP", raising=False)
     exit_code = bugteam_preflight.main(["--no-pytest"])
     assert exit_code == bugteam_preflight.EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV
+
+
+def _was_called_with_argument(
+    mock_subprocess_run: MagicMock, argument_token: str
+) -> bool:
+    return any(
+        argument_token in each_call_args[0][0]
+        for each_call_args in mock_subprocess_run.call_args_list
+    )
+
+
+def test_verify_git_hooks_path_invokes_self_heal_before_effective_query(
+    tmp_path: Path,
+) -> None:
+    """verify_git_hooks_path must delegate to the shared self-heal helper before --get."""
+    canonical_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
+    canonical_hooks_path.mkdir(parents=True)
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            str(canonical_hooks_path) + "\n", returncode=0
+        )
+        bugteam_preflight.verify_git_hooks_path(tmp_path)
+    assert _was_called_with_argument(mock_run, "--get-all"), (
+        "verify_git_hooks_path must run the --local --get-all read for self-heal"
+    )
+    assert _was_called_with_argument(mock_run, "--get"), (
+        "verify_git_hooks_path must still run the effective --get verification"
+    )
+    first_called_command = mock_run.call_args_list[0][0][0]
+    assert "--get-all" in first_called_command, (
+        "Self-heal must run BEFORE the effective config query, not after"
+    )

package/skills/copilot-review/SKILL.md

@@ -1,14 +1,11 @@
 ---
 name: copilot-review
 description: >-
-  Spawns a background subagent that babysits the GitHub Copilot reviewer on the
-  current PR. The subagent self-paces at ~5 minutes per tick, fetches the
-  latest copilot-pull-request-reviewer[bot] review, fixes unaddressed inline
-  findings against current HEAD (new commit, push, inline replies), and
-  re-requests review via the documented requested_reviewers API. The subagent
-  terminates on convergence (clean review against HEAD) and reports back.
-  Triggers: '/copilot-review', 'watch copilot', 'babysit copilot review',
-  'loop copilot reviews', 're-request copilot', 'keep re-requesting copilot'.
+  Spawns a background subagent that babysits the GitHub Copilot reviewer on the current
+  PR: each ~5-min tick it fetches the latest copilot-pull-request-reviewer[bot] review,
+  fixes unaddressed findings against HEAD (commit, push, inline replies), re-requests
+  review, and exits on convergence. Triggers: '/copilot-review', 'watch copilot',
+  'babysit copilot review', 'keep re-requesting copilot'.
 ---
 
 # Copilot Review

package/skills/doc-gist/SKILL.md

@@ -1,14 +1,11 @@
 ---
 name: doc-gist
 description: >-
-  Use when the user asks to share, publish, preview, or open as a webpage any
-  HTML doc, writeup, report, plan, decision record, runbook, explainer, status
-  update, or interactive artifact. Triggers on `/doc-gist`, "publish this",
-  "share as a gist", "open this as a webpage", "make me a writeup", "publish my
-  report", or any request that ends in a shareable HTML preview URL. Provides
-  the `gist_upload` transport script, an auto-publish hook keyed off the
-  `<!-- @publish-as-gist -->` HTML comment, and a 20-file gallery of HTML
-  artifact patterns to draw from when designing fresh.
+  Use when the user asks to share, publish, preview, or open as a webpage any HTML doc,
+  writeup, report, plan, runbook, or interactive artifact. Triggers on /doc-gist,
+  "publish this", "share as a gist", "open this as a webpage", "make me a writeup", or
+  any request ending in a shareable HTML preview URL. Provides the gist_upload transport
+  script, the <!-- @publish-as-gist --> auto-publish hook, and an HTML pattern gallery.
 ---
 
 # doc-gist

package/skills/fixbugs/SKILL.md

@@ -33,7 +33,7 @@ Locate the most recent `/findbugs` output in the current conversation. For each
 
 - Severity (`P0` / `P1` / `P2`)
 - `file:line`
-- Category (the A–N letter or category name `/findbugs` reported)
+- Category (the A–P letter or category name `/findbugs` reported)
 - One-sentence description as `/findbugs` wrote it
 
 Apply the severity filter from `$ARGUMENTS` if present:

package/skills/gh-paginate/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: gh-paginate
+description: Safe pagination for gh api reads of paginated GitHub list endpoints (PR reviews/comments/files, issue comments, pulls, issues) — --paginate --slurp piped to external jq, single-page bounds, newest-first walks. Use before composing any gh api list-endpoint call or any cross-page jq operation (sort_by | last, reverse).
+---
+
+# gh API Pagination Rule
+
+**Root cause:** GitHub REST API list endpoints paginate by default. Without `--paginate --slurp`, callers see only the oldest page, and cross-page jq operations (e.g., `sort_by | last`) operate within a single page — producing wrong-but-confident results.
+
+**Rule:** All `gh api` calls that read `pulls/<number>/reviews`, `pulls/<number>/comments`, `issues/<number>/comments`, or any other paginated GitHub list endpoint **must** request the full set of pages AND apply any cross-page jq operation through external `jq`, not through `gh`'s built-in `--jq`. Use `--paginate --slurp | jq` (preferred — see [Safe patterns](#safe-patterns)). Never call these endpoints with their default pagination, and never use `gh`'s `--jq` for cross-page operations like `sort_by | last` or `| reverse | .[0]`.
+
+## Two defects, one rule
+
+This rule guards against two distinct silent-truncation defects that compound:
+
+1. **Default page truncation.** Without `--paginate`, only the first page is fetched.
+2. **`--jq` runs per-page, not on the concatenated result.** Per [GitHub CLI #10459](https://github.com/cli/cli/issues/10459), `gh api --paginate --jq '<filter>'` applies `<filter>` to each page **separately** and emits one output per page. Cross-page operations like `sort_by(.submitted_at) | last` therefore operate within each page independently, not across the merged result set.
+
+The safe patterns below fix both defects together: `--paginate --slurp` walks every page AND emits a single merged structure, and an **external** `jq` then runs cross-page operations on that merged structure.
+
+## Affected endpoints
+
+The rule applies to every paginated read from the GitHub REST API. Common offenders in PR-loop skills:
+
+- `gh api repos/<owner>/<repo>/pulls/<number>/reviews`
+- `gh api repos/<owner>/<repo>/pulls/<number>/comments`
+- `gh api repos/<owner>/<repo>/pulls/<number>/files`
+- `gh api repos/<owner>/<repo>/issues/<number>/comments`
+- `gh api repos/<owner>/<repo>/pulls`
+- `gh api repos/<owner>/<repo>/issues`
+
+The same rule applies to any other endpoint documented as paginated by GitHub (see [GitHub REST API pagination](https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api)).
+
+Single-object endpoints (e.g., `repos/<owner>/<repo>/pulls/<number>` returning one PR object) are not paginated — `?per_page=...` is silently ignored, and neither `--paginate` nor external `jq` is required. Use `gh`'s `--jq` directly on those endpoints.
+
+## Safe patterns
+
+### Preferred — `--paginate --slurp` piped to external `jq`
+
+`gh api ... --paginate --slurp` walks every page and emits a single merged JSON array of page-arrays (`[[page1_items...], [page2_items...], ...]`). Pipe to external `jq` to flatten and filter across the full result set:
+
+```bash
+gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' --paginate --slurp \
+  | jq '[.[][] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
+```
+
+The `.[][]` flattens the array-of-pages into one stream of items before the cross-page operators (`sort_by`, `last`, `reverse`) run. Combine with `?per_page=100` to reduce round-trips on long PRs.
+
+`gh`'s `--jq` flag and `--slurp` flag are mutually exclusive (gh CLI rejects `--paginate --slurp --jq` with `the --slurp option is not supported with --jq or --template`), which is why the filter must run in an external `jq` invocation.
+
+### Acceptable — single-page bound on a paginated list endpoint when result fits
+
+When you have an explicit reason to read at most one page from a **paginated** list endpoint (e.g., a known-small list), document the bound in a comment and use `?per_page=100` without `--paginate`. Cross-page operators are not in play here, so `gh`'s `--jq` is safe:
+
+```bash
+# Bound: a freshly created issue is expected to have <= 100 comments.
+gh api 'repos/<owner>/<repo>/issues/<number>/comments?per_page=100' \
+  --jq '[.[] | select(.user.login=="cursor[bot]")] | length'
+```
+
+This pattern is only safe when the endpoint is confirmed to return a list smaller than 100 entries. Lists that grow over the PR's lifetime (reviews, comments) must use `--paginate --slurp` plus external `jq`.
+
+### Single-object endpoints — no pagination needed
+
+Endpoints that return a single object (e.g., `pulls/<number>`, `issues/<number>`) are not paginated. `?per_page=...`, `--paginate`, and `--slurp` are all unnecessary. Use `gh`'s built-in `--jq` directly:
+
+```bash
+gh api 'repos/<owner>/<repo>/pulls/<number>' --jq '.head.sha'
+```
+
+### Newest-first walk
+
+Pair pagination with explicit reverse-sort so the consumer reads newest-first regardless of the API's internal order:
+
+```bash
+gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' --paginate --slurp \
+  | jq '[.[][] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | reverse'
+```
+
+This is the canonical pattern for the bugbot <-> bugteam convergence loop: walk newest-first, stop at the first clean review.
+
+## Enforcement
+
+This rule is documentation-only at present. A future PreToolUse hook may pattern-match `Bash` invocations of `gh api repos/.../pulls/<n>/(reviews|comments)` without `--paginate --slurp` (or with `--paginate --jq` doing cross-page operations) and return a corrective message. Until that hook lands, treat this rule as binding by review and rely on it during skill authoring.

package/skills/pr-converge/SKILL.md

@@ -105,6 +105,15 @@ For each unresolved thread, verify the concern against current HEAD;
 either fix-and-resolve, or reply-with-note-and-resolve when the concern
 no longer applies.
 
+**Full-PR-diff rule: every CODE-REVIEW round (Step 5) and every BUGTEAM
+round (Step 6) covers the FULL `origin/main...HEAD` diff — every file
+the PR touches.** A round that scopes to a subset — only the last commit,
+only files touched since the prior clean SHA, only bugbot-flagged paths,
+or any other delta cut — does not satisfy the gate, and a "clean" verdict
+against a partial diff is not a valid clean. Re-run the round against the
+full diff before recording `code_review_clean_at` or treating the bugteam
+round as converged. This rule holds every tick, every loop, every PR.
+
 - [ ] **Step 0: Grant project permissions**
       `python "$HOME/.claude/skills/bugteam/scripts/grant_project_claude_permissions.py"`
 
@@ -159,12 +168,22 @@ no longer applies.
 
       Pre-condition: `bugbot_clean_at == current_head` (or `bugbot_down == true`).
 
-      Run Claude Code's built-in `/code-review --fix` on the current diff —
+      Run Claude Code's built-in `/code-review --fix` on the full
+      `origin/main...HEAD` diff —
       the [local diff review](https://code.claude.com/docs/en/code-review#review-a-diff-locally)
       — so it reviews the diff and applies its findings to the working
       tree. Pass no effort argument, so the review uses the session's
       current effort.
 
+      **Scope: the FULL `origin/main...HEAD` diff every tick** — every file
+      the PR touches. Do not delta-scope to commits added since the prior
+      clean SHA, do not scope to a single file, do not scope to bugbot's
+      flagged paths. Before running, confirm the working tree is on the
+      PR's HEAD with no uncommitted edits, then invoke `/code-review --fix`
+      with no path arguments so it audits the whole branch diff against
+      `origin/main`. A partial-scope round does not count and cannot set
+      `code_review_clean_at`.
+
       - [ ] **fixes applied** (working tree changed) →
             - [ ] Commit the applied fixes (one commit) → push
             - [ ] reset `bugbot_clean_at = null`, `code_review_clean_at = null`
@@ -187,6 +206,14 @@ no longer applies.
       `pr_converge_bugteam_enforcer` hook blocks it. `qbug` is NOT an accepted
       substitute; `bugteam` is the only allowed skill at this step.
 
+      **Scope: the FULL `origin/main...HEAD` diff every tick** — every file
+      the PR touches. Pass the PR URL as the sole argument so bugteam audits
+      the whole branch diff against `origin/main`. Do not pass a file list,
+      a path filter, a commit range, or any "just the new commits since
+      last clean" cut — bugteam owns its own discovery on the full PR diff.
+      A partial-scope round does not count and cannot satisfy the
+      converged-on-current-HEAD condition below.
+
       After bugteam completes, re-resolve HEAD.
 
       - [ ] **bugteam pushed new commits** →

package/skills/pr-converge/reference/per-tick.md

@@ -117,14 +117,23 @@ c. Decide (four branches; match first whose predicate holds):
 
 Local correctness/quality pass between BUGBOT clean and BUGTEAM. Enters
 after BUGBOT reports clean on `current_head` (or `bugbot_down == true`).
-Runs Claude Code's built-in `/code-review --fix` on the current diff; it
-produces no GitHub review artifact, so there are no code-review threads to
-resolve.
-
-a. Run Claude Code's built-in `/code-review --fix` on the current diff —
-   the [local diff review](https://code.claude.com/docs/en/code-review#review-a-diff-locally).
-   It reviews the diff and applies its findings to the working tree. Pass
-   no effort argument, so the review uses the session's current effort.
+Runs Claude Code's built-in `/code-review --fix` on the full
+`origin/main...HEAD` diff; it produces no GitHub review artifact, so there
+are no code-review threads to resolve.
+
+a. Run Claude Code's built-in `/code-review --fix` on the FULL
+   `origin/main...HEAD` diff — every file the PR touches — via the
+   [local diff review](https://code.claude.com/docs/en/code-review#review-a-diff-locally).
+   It reviews the diff and applies its findings to the working tree.
+
+   Before running, confirm the working tree sits on the PR's HEAD with no
+   uncommitted edits, then invoke `/code-review --fix` with no path
+   arguments so it audits the whole branch diff against `origin/main`. Do
+   not delta-scope to commits added since the prior clean SHA, do not
+   scope to a single file, do not scope to bugbot's flagged paths. A
+   partial-scope round does not count and cannot set
+   `code_review_clean_at`. Pass no effort argument, so the review uses
+   the session's current effort.
 
 b. Decide (two branches; match first whose predicate holds):
 
@@ -144,6 +153,13 @@ b. Decide (two branches; match first whose predicate holds):
 
 a. Run **bugteam** on current PR.
 
+   Pass the PR URL as the sole argument so bugteam audits the FULL
+   `origin/main...HEAD` diff — every file the PR touches. Bugteam owns
+   its own discovery on the full PR diff. Do not pass a file list, a
+   path filter, a commit range, or any "just the new commits since last
+   clean" cut. A partial-scope round does not count and cannot satisfy
+   the converged-on-current-HEAD condition in step (d).
+
    - **`Skill` invokable**: invoke bugteam
      with `Skill`.
 

package/skills/pre-compact/SKILL.md

@@ -1,15 +1,10 @@
 ---
 name: pre-compact
 description: >-
-  Composes a focus directive for `/compact [instructions]` and copies the full
-  `/compact <directive>` string to the operator's clipboard so the next prompt
-  is a single paste. The directive pins the session's load-bearing identifiers
-  (branch, PR, HEAD, worktree, in-flight work, decisions, blockers, files in
-  play, follow-ups) the next steps depend on, so the summarizer keeps them with
-  high fidelity. It confirms the operator's intent for the next chat through a
-  structured question first, then validates each identifier against its live
-  source before stating it. Use when the user says `/pre-compact`, asks to prep for compaction, or
-  asks to compose a focus directive for `/compact`.
+  Composes a focus directive for /compact and copies the full "/compact <directive>"
+  string to the clipboard, pinning the session's load-bearing identifiers (branch, PR,
+  HEAD, worktree, in-flight work, decisions, blockers, files in play) after validating
+  each against its live source. Use on /pre-compact or any ask to prep for compaction.
 disable-model-invocation: true
 ---