claude-dev-env 1.50.4 → 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/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
 ---
 

package/skills/refine/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: refine
-description: Interview-driven plan refiner with built-in audit loop. Takes a draft, a topic, or the active conversation; fans out research agents; interviews via AskUserQuestion until further questions would be impractical hypotheticals; writes the plan to the Obsidian vault under Research/<topic>/<slug>.md; then loops a general-purpose audit and fix pass (both with plan-quality rubrics) until the plan is clean, with a sibling <slug>-implementation-notes.html capturing design decisions, deviations, tradeoffs, and open questions across iterations. The interview is mandatory and the vault is the only output target — these survive any session-level "no clarifying questions" or local plans/ shortcuts. Use when the user says /refine, "refine this", "turn this into a plan", "flesh this out", "make a spec for this", "let's plan this out", or asks for a vague idea to be matured into a plan. Always operates on plans — skill plans, new-code implementation plans, or code-refinement plans.
+description: >-
+  Interview-driven plan refiner with built-in audit loop: fans out research agents,
+  interviews via AskUserQuestion (mandatory — survives no-question directives), writes
+  the plan to the Obsidian vault under Research/<topic>/<slug>.md, then loops audit and
+  fix until clean. Triggers: /refine, "refine this", "turn this into a plan", "flesh
+  this out", "make a spec for this", "let's plan this out", or any vague idea to mature
+  into a plan.
 ---
 
 # refine
@@ -164,7 +170,7 @@ Spawn `general-purpose` (`subagent_type: general-purpose`, foreground) with:
   - **Ambiguity** — no parked open questions where a decision is required for implementation to begin
   - **Implementer-readiness** — a downstream implementer can act on each step without back-and-forth (file paths named, agents named, change concrete)
 - A required return shape: structured findings as `severity (P0/P1/P2) | location | violation`, plus an explicit `CLEAN` verdict when no findings remain
-- An explicit instruction NOT to apply code-review rubrics (CODE_RULES categories A–N, API contracts, resource cleanup, etc.) — the audit target is a markdown plan, not source code
+- An explicit instruction NOT to apply code-review rubrics (CODE_RULES categories A–P, API contracts, resource cleanup, etc.) — the audit target is a markdown plan, not source code
 
 If the verdict is `CLEAN`: skip step 8 and proceed to step 10.
 

package/skills/structure-prompt/SKILL.md

@@ -1,16 +1,11 @@
 ---
 name: structure-prompt
 description: >-
-  Restructure any user-provided prompt — order blocks correctly, replace persona
-  framing with task constraints, enforce per-category dispositions, replace
-  ceremony directives with measurable constraints, expand placeholder tokens
-  into real values via the sibling rubric or AskUserQuestion, add file:line
-  citations for identifiers that appear in the data body, mark the canonical
-  sub-bucket with ⭐, and sharpen generic adversarial-pass phrasing into a
-  category-specific failure-mode noun. Trigger when the user invokes
-  /structure-prompt, pastes a prompt and asks to optimize it, asks for a
-  "minimally invasive edit" to a prompt artifact, or asks to "tighten this
-  prompt."
+  Restructure a user-provided prompt: order blocks, replace persona framing with task
+  constraints, enforce per-category dispositions, expand placeholder tokens via the
+  sibling rubric or AskUserQuestion, add file:line citations, mark the canonical
+  sub-bucket, sharpen adversarial-pass phrasing. Triggers: /structure-prompt, "optimize
+  this prompt", "minimally invasive edit" to a prompt artifact, "tighten this prompt".
 ---
 
 # structure-prompt