claude-dev-env 1.33.0 → 1.34.1

package/hooks/hooks.json

@@ -224,6 +224,18 @@
           }
         ]
       }
+    ],
+    "InstructionsLoaded": [
+      {
+        "matcher": "session_start|nested_traversal|path_glob_match|include|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/observability/instructions_loaded_logger.py",
+            "timeout": 10
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/observability/instructions_loaded_logger.py

@@ -0,0 +1,38 @@
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def main() -> int:
+    log_path = Path.home() / ".claude" / "logs" / "instructions_loaded.jsonl"
+    payload_fields = (
+        "file_path",
+        "load_reason",
+        "memory_type",
+        "trigger_file_path",
+        "parent_file_path",
+        "globs",
+        "session_id",
+    )
+    try:
+        payload = json.load(sys.stdin)
+        record = {"timestamp": datetime.now(timezone.utc).isoformat()}
+        for each_field_name in payload_fields:
+            record[each_field_name] = payload.get(each_field_name)
+    except Exception as exception:
+        record = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "error": str(exception),
+        }
+    try:
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        with log_path.open("a", encoding="utf-8") as log_file:
+            log_file.write(json.dumps(record) + "\n")
+    except OSError:
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/observability/test_instructions_loaded_logger.py

@@ -0,0 +1,85 @@
+"""Tests for instructions_loaded_logger observability hook."""
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+SCRIPT_PATH = Path(__file__).parent / "instructions_loaded_logger.py"
+
+
+def _run_hook(payload: dict, fake_home: Path) -> subprocess.CompletedProcess[str]:
+    child_environment = os.environ.copy()
+    child_environment["HOME"] = str(fake_home)
+    child_environment["USERPROFILE"] = str(fake_home)
+    return subprocess.run(
+        [sys.executable, str(SCRIPT_PATH)],
+        input=json.dumps(payload),
+        text=True,
+        capture_output=True,
+        check=False,
+        env=child_environment,
+    )
+
+
+def test_should_write_record_with_known_payload_fields_to_jsonl_log() -> None:
+    with tempfile.TemporaryDirectory() as fake_home_string:
+        fake_home = Path(fake_home_string)
+        payload = {
+            "file_path": "/tmp/CLAUDE.md",
+            "load_reason": "session_start",
+            "memory_type": "User",
+            "trigger_file_path": "/tmp/trigger",
+            "parent_file_path": "/tmp/parent",
+            "globs": ["**/*.py"],
+            "session_id": "abc-123",
+        }
+        completed = _run_hook(payload, fake_home)
+        assert completed.returncode == 0, completed.stderr
+        log_path = fake_home / ".claude" / "logs" / "instructions_loaded.jsonl"
+        assert log_path.exists()
+        record = json.loads(log_path.read_text(encoding="utf-8").strip())
+        assert record["file_path"] == "/tmp/CLAUDE.md"
+        assert record["load_reason"] == "session_start"
+        assert record["session_id"] == "abc-123"
+        assert "timestamp" in record
+
+
+def test_should_exit_zero_and_record_error_when_stdin_payload_is_invalid_json() -> None:
+    with tempfile.TemporaryDirectory() as fake_home_string:
+        fake_home = Path(fake_home_string)
+        completed = subprocess.run(
+            [sys.executable, str(SCRIPT_PATH)],
+            input="not json",
+            text=True,
+            capture_output=True,
+            check=False,
+            env={**os.environ, "HOME": str(fake_home), "USERPROFILE": str(fake_home)},
+        )
+        assert completed.returncode == 0, completed.stderr
+        log_path = fake_home / ".claude" / "logs" / "instructions_loaded.jsonl"
+        assert log_path.exists()
+        record = json.loads(log_path.read_text(encoding="utf-8").strip())
+        assert "error" in record
+        assert "timestamp" in record
+
+
+def test_should_exit_zero_when_log_directory_creation_fails() -> None:
+    with tempfile.TemporaryDirectory() as fake_home_string:
+        fake_home = Path(fake_home_string)
+        blocking_file = fake_home / ".claude"
+        blocking_file.write_text("not a directory", encoding="utf-8")
+        payload = {
+            "file_path": "/tmp/CLAUDE.md",
+            "load_reason": "path_glob_match",
+            "memory_type": "User",
+            "trigger_file_path": None,
+            "parent_file_path": None,
+            "globs": None,
+            "session_id": "abc-123",
+        }
+        completed = _run_hook(payload, fake_home)
+        assert completed.returncode == 0, completed.stderr

package/package.json

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

package/rules/code-standards.md

@@ -3,8 +3,6 @@
 > **MANDATORY REFERENCE:** CODE_RULES.md - Load for ALL code generation.
 > This is the single source of truth for code standards. Non-negotiable.
 
-@~/.claude/docs/CODE_RULES.md
-
 **Key principles (see CODE_RULES.md for complete reference):**
 - Self-documenting code (no comments)
 - Centralized configuration (one source of truth)

package/rules/file-global-constants.md

@@ -1,3 +1,7 @@
+---
+paths: **/*.py
+---
+
 # File-Global Constants
 
 This rule extends the `constants-location` rule defined in `~/.claude/docs/CODE_RULES.md` — see the ⚡ HOOK-ENFORCED RULES table, Constants location row.

package/rules/shell-invocation-policy.md

@@ -0,0 +1,144 @@
+# Shell Invocation Policy (pwsh-only)
+
+**When this applies:** Every shell command issued through the `Bash` tool on Windows.
+
+## What to use
+
+### Pattern A — Run a `.ps1` script with named arguments
+
+```
+pwsh -NoProfile -File 'Y:\absolute\path\to\Build-Skyline.ps1' -RunTests -Tag staging
+```
+
+Use this when a `.ps1` script accepts named parameters. The `-File` form exposes the script path as a flat token, so `permissions.allow` rules of the form `Bash(pwsh -NoProfile -File *)` match the invocation directly.
+
+### Pattern B — Run an inline expression
+
+```
+pwsh -NoProfile -Command "Get-Date -Format o"
+```
+
+Use this for one or two lines of work that does not need a script file. Quote the entire `-Command` argument with double quotes; use single quotes inside for embedded strings.
+
+### Pattern C — Multi-line inline script with a here-string
+
+```
+pwsh -NoProfile -Command @'
+$projects = Get-ChildItem -Path 'Y:\Projects\LLM Plugins' -Directory
+$projects | Where-Object Name -Like 'claude*' | Select-Object FullName
+'@
+```
+
+Use this for multi-line logic without a separate `.ps1` file. The `@'...'@` form is literal — variables and backticks inside are not expanded.
+
+### Pattern D — The built-in `PowerShell` tool
+
+Use the `PowerShell` tool directly when the entire workflow is PowerShell and does not pipe through external `Bash`-tool-native commands. The built-in tool already runs PowerShell 7+ from `C:\Program Files\PowerShell\7\pwsh.exe`. It supports `run_in_background` for long-running tasks, which `Bash` invocations of `pwsh` do not.
+
+## Migration mapping (replace left with right)
+
+| Existing pattern | Replacement |
+|---|---|
+| `powershell -Command "X"` | `pwsh -NoProfile -Command "X"` |
+| `powershell.exe -Command "X"` | `pwsh -NoProfile -Command "X"` |
+| `powershell -File path.ps1` | `pwsh -NoProfile -File 'path.ps1'` |
+| `powershell.exe -File path.ps1` | `pwsh -NoProfile -File 'path.ps1'` |
+| `powershell -Command "& 'path.ps1' -A v"` | `pwsh -NoProfile -File 'path.ps1' -A v` |
+| `bash -c "X"` | `pwsh -NoProfile -Command "X"` |
+| `cmd /c X` | `pwsh -NoProfile -Command "X"` |
+| `cmd.exe /c X` | `pwsh -NoProfile -Command "X"` |
+| `Bash(powershell:*)` (settings.json) | `Bash(pwsh:*)` |
+| `Bash(powershell.exe:*)` (settings.json) | `Bash(pwsh:*)` |
+
+## Common operations in pwsh
+
+| Task | pwsh syntax |
+|---|---|
+| List directory names | `Get-ChildItem -Path 'X' -Directory -Name` |
+| Read a whole file | `Get-Content -Path 'X' -Raw` |
+| Write file (UTF-8 no BOM) | `[IO.File]::WriteAllText('X', $content, [Text.UTF8Encoding]::new($false))` |
+| Test a path | `Test-Path 'X'` |
+| Remove a directory | `Remove-Item -Path 'X' -Recurse -Force` |
+| Activate a venv | `& 'Y:\path\.venv\Scripts\Activate.ps1'` |
+| Run venv-Python | `& 'Y:\path\.venv\Scripts\python.exe' script.py` |
+| Set env var (current process) | `$env:NAME = 'value'` |
+| Pipe to ripgrep | `Get-ChildItem | Select-String -Pattern 'X'` |
+| First match in a stream | `Select-Object -First 1` |
+
+The `&` call operator is appropriate for invoking an executable at a path — for example, `& '<venv>\Scripts\python.exe' script.py`. The forbidden form is wrapping a script path inside `pwsh -Command "& 'X' -A v"`, where the call operator is inside a `-Command` payload and breaks `permissions.allow` matching. Use `pwsh -File 'X' -A v` instead for that case.
+
+## External binaries usable from pwsh
+
+Invoke these directly without wrapping:
+
+- `git` — `git status`, `git log --oneline -10`, `git -C 'path' status`
+- `gh` — `gh pr create`, `gh issue list`
+- `python`, `pip` (via venv path: `& '.venv\Scripts\python.exe'`)
+- `node`, `npm`, `npx`
+- `rg` (ripgrep), `fd`, `es.exe` (Everything search)
+- `pytest`, `mypy`, `pyright` (via venv)
+
+## Verification
+
+To confirm pwsh is correctly installed and routed:
+
+```
+pwsh -NoProfile -Command "$PSVersionTable.PSVersion.ToString()"
+```
+
+Expected output: `7.x.x.x` or higher. The verified install at the time of writing this rule is `7.5.5.0` at `C:\Program Files\PowerShell\7\pwsh.exe`.
+
+## Permission allowlist (settings.json `permissions.allow`)
+
+These entries pre-approve canonical pwsh invocations:
+
+```
+Bash(pwsh -NoProfile -File *)
+Bash(pwsh -File *)
+Bash(pwsh -NoProfile -Command *)
+Bash(pwsh -Command *)
+Bash(pwsh:*)
+PowerShell
+```
+
+The `PowerShell` entry auto-approves the built-in tool.
+
+## Permission denylist (settings.json `permissions.deny`)
+
+These entries block legacy shells:
+
+```
+Bash(powershell *)
+Bash(powershell.exe *)
+Bash(powershell:*)
+Bash(powershell.exe:*)
+Bash(bash -c *)
+Bash(bash --login *)
+Bash(bash --rcfile *)
+Bash(bash --init-file *)
+Bash(cmd /c *)
+Bash(cmd.exe /c *)
+```
+
+## Migration scripts
+
+Two scripts ship with this rule, located at `packages/claude-dev-env/scripts/`:
+
+- `Audit-ShellPolicy.ps1` — scans `settings*.json` files under the configured project roots and prints one summary line: `POLICY: OK` or `POLICY: VIOLATIONS=<count> IN=<n> FILES`. Exit code 0 when clean, 1 when violations remain. Use this as a check before merging.
+- `Migrate-ShellPolicy.ps1` — applies the migration mapping to `settings*.json` files in place. Defaults to dry-run; pass `-Apply` to write changes. Prints one summary line: `MIGRATED: <count> rules IN=<n> FILES` or `DRY RUN: would migrate <count> rules IN=<n> FILES`.
+
+Run order: audit → migrate (dry run) → migrate (apply) → audit.
+
+## Enforcement layers
+
+1. **`permissions.allow`** pre-approves the canonical patterns so Claude never gets a prompt for them.
+2. **`permissions.deny`** blocks the legacy patterns at the permission layer.
+3. **`pwsh_enforcer.py`** PreToolUse hook catches edge cases that wildcard syntax misses (compound commands, process wrappers, alternate spellings). Source: `packages/claude-dev-env/hooks/blocking/pwsh_enforcer.py`.
+4. **Migration scripts** keep existing `settings.local.json` files in compliance.
+
+## Precedent
+
+This rule mirrors the convention from [ProteoWizard/pwiz-ai](https://github.com/ProteoWizard/pwiz-ai) `CLAUDE.md`:
+
+> "Always use `pwsh` (PowerShell 7), never `powershell` (5.1). The Bash tool uses Git Bash, which has limited Windows tool access. Route commands through PowerShell when needed."
+> "Never use the `&` call operator — it breaks permissions matching. Use `-File` instead, which supports arguments directly."

package/scripts/Audit-ShellPolicy.ps1

@@ -0,0 +1,142 @@
+#!/usr/bin/env pwsh
+<#
+.SYNOPSIS
+    Scans Claude Code settings*.json files for legacy shell-invocation patterns
+    that violate the pwsh-only policy.
+
+.DESCRIPTION
+    Walks the configured project roots, finds every settings.json,
+    settings.local.json, and settings.local.json.template, and counts permission
+    rule strings that invoke powershell.exe / Windows PowerShell 5.1 / bash -c /
+    cmd /c instead of pwsh. Prints exactly one summary line and exits 0 when
+    clean or 1 when violations remain.
+
+.PARAMETER Roots
+    One or more directories to scan recursively. Defaults to the user's known
+    Claude Code project parents.
+
+.PARAMETER Verbose
+    Use the standard PowerShell -Verbose switch to print per-file violation
+    detail in addition to the summary line.
+
+.OUTPUTS
+    One line on stdout:
+        POLICY: OK
+        POLICY: VIOLATIONS=<count> IN=<n> FILES UNPARSEABLE=<m> FILES
+        POLICY: UNPARSEABLE=<m> FILES (audit unsound)
+
+.EXAMPLE
+    pwsh -NoProfile -File Audit-ShellPolicy.ps1
+    pwsh -NoProfile -File Audit-ShellPolicy.ps1 -Verbose
+    pwsh -NoProfile -File Audit-ShellPolicy.ps1 -Roots 'Y:\Projects'
+#>
+[CmdletBinding()]
+param(
+    [string[]]$Roots = @(
+        (Join-Path $env:USERPROFILE '.claude'),
+        'Y:\Projects',
+        'Y:\Information Technology\Scripts',
+        'Y:\Python',
+        'Y:\claude-settings'
+    )
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$caseInsensitive = [System.Text.RegularExpressions.RegexOptions]::IgnoreCase
+$violationPatterns = @(
+    [regex]::new('^Bash\(powershell(?:\.exe)?(?:[\s:].*)?\)$', $caseInsensitive)
+    [regex]::new('^Bash\(bash\s+(?:-c|--login|--rcfile|--init-file)\b.*\)$', $caseInsensitive)
+    [regex]::new('^Bash\(cmd(?:\.exe)?\s+/c\b.*\)$', $caseInsensitive)
+    [regex]::new('^Bash\(pwsh(?:\.exe)?\s+(?:-NoProfile\s+)?-Command\s+["'']?&\s+[''"].*\)$', $caseInsensitive)
+)
+
+$settingsFileNames = @(
+    'settings.json',
+    'settings.local.json',
+    'settings.local.json.template'
+)
+
+function Test-RuleViolatesPolicy {
+    param([string]$Rule)
+    foreach ($pattern in $violationPatterns) {
+        if ($pattern.IsMatch($Rule)) { return $true }
+    }
+    return $false
+}
+
+function Test-HasProperty {
+    param($Target, [string]$Name)
+    if ($null -eq $Target) { return $false }
+    if ($Target -isnot [psobject]) { return $false }
+    return ($Target.PSObject.Properties.Name -contains $Name)
+}
+
+function Get-PermissionRuleArrays {
+    param([Parameter(Mandatory)] $SettingsObject)
+    $arrays = @()
+    if (-not (Test-HasProperty -Target $SettingsObject -Name 'permissions')) { return $arrays }
+    $permissions = $SettingsObject.permissions
+    foreach ($key in @('allow', 'ask')) {
+        if (-not (Test-HasProperty -Target $permissions -Name $key)) { continue }
+        $maybeArray = $permissions.$key
+        if ($null -ne $maybeArray) { $arrays += , $maybeArray }
+    }
+    return $arrays
+}
+
+$totalViolations = 0
+$filesWithViolations = 0
+$unparseableFileCount = 0
+$scannedFileCount = 0
+$existingRoots = $Roots | Where-Object { Test-Path $_ }
+
+foreach ($root in $existingRoots) {
+    $candidateFiles = Get-ChildItem -Path $root -Recurse -File -ErrorAction SilentlyContinue |
+        Where-Object { $settingsFileNames -contains $_.Name }
+    foreach ($file in $candidateFiles) {
+        $rawContent = Get-Content -Path $file.FullName -Raw -ErrorAction SilentlyContinue
+        if ([string]::IsNullOrWhiteSpace($rawContent)) { continue }
+        try {
+            $parsed = $rawContent | ConvertFrom-Json -ErrorAction Stop
+        } catch {
+            $unparseableFileCount++
+            Write-Warning "Skipped (invalid JSON): $($file.FullName)"
+            continue
+        }
+        $scannedFileCount++
+        $fileViolationCount = 0
+        foreach ($ruleArray in (Get-PermissionRuleArrays -SettingsObject $parsed)) {
+            foreach ($rule in $ruleArray) {
+                if ($rule -is [string] -and (Test-RuleViolatesPolicy -Rule $rule)) {
+                    $fileViolationCount++
+                    Write-Verbose "  $($file.FullName): $rule"
+                }
+            }
+        }
+        if ($fileViolationCount -gt 0) {
+            $totalViolations += $fileViolationCount
+            $filesWithViolations++
+        }
+    }
+}
+
+if ($scannedFileCount -eq 0 -and $unparseableFileCount -eq 0) {
+    Write-Warning 'No settings files found in any of the configured roots — audit is vacuous.'
+    Write-Output 'POLICY: NO FILES SCANNED'
+    exit 1
+}
+
+if ($totalViolations -eq 0 -and $unparseableFileCount -eq 0) {
+    Write-Output ('POLICY: OK SCANNED={0} FILES' -f $scannedFileCount)
+    exit 0
+}
+
+if ($totalViolations -eq 0 -and $unparseableFileCount -gt 0) {
+    Write-Output ('POLICY: UNPARSEABLE={0} FILES SCANNED={1} FILES (audit unsound)' -f $unparseableFileCount, $scannedFileCount)
+    exit 1
+}
+
+Write-Output ('POLICY: VIOLATIONS={0} IN={1} FILES UNPARSEABLE={2} FILES SCANNED={3} FILES' -f $totalViolations, $filesWithViolations, $unparseableFileCount, $scannedFileCount)
+exit 1

package/scripts/Migrate-ShellPolicy.ps1

@@ -0,0 +1,192 @@
+#!/usr/bin/env pwsh
+<#
+.SYNOPSIS
+    Rewrites legacy shell-invocation rules in Claude Code settings*.json files
+    to the pwsh-only canonical form.
+
+.DESCRIPTION
+    Walks the configured project roots, finds every settings.json,
+    settings.local.json, and settings.local.json.template, and rewrites permission
+    rule strings that invoke powershell / powershell.exe / bash -c / cmd /c
+    into their pwsh equivalents per the migration mapping in
+    rules/shell-invocation-policy.md. Defaults to dry-run; pass -Apply to write
+    changes. Prints exactly one summary line.
+
+.PARAMETER Roots
+    One or more directories to scan recursively. Defaults to the user's known
+    Claude Code project parents.
+
+.PARAMETER Apply
+    Write changes back to disk. Without this switch, runs in dry-run mode and
+    reports what would change without modifying any files.
+
+.OUTPUTS
+    One line on stdout:
+        DRY RUN: would migrate <count> rules IN=<n> FILES UNPARSEABLE=<m> FILES
+        MIGRATED: <count> rules IN=<n> FILES UNPARSEABLE=<m> FILES
+        MIGRATED: 0 rules SCANNED=<n> FILES UNPARSEABLE=<m> FILES (already compliant)
+        MIGRATED: NO FILES SCANNED UNPARSEABLE=<m> FILES
+
+.EXAMPLE
+    pwsh -NoProfile -File Migrate-ShellPolicy.ps1
+    pwsh -NoProfile -File Migrate-ShellPolicy.ps1 -Apply
+    pwsh -NoProfile -File Migrate-ShellPolicy.ps1 -Apply -Verbose
+
+.NOTES
+    Files are written as UTF-8 without BOM to preserve cross-platform
+    compatibility and avoid corrupting first-line JSON parsing.
+#>
+[CmdletBinding()]
+param(
+    [string[]]$Roots = @(
+        (Join-Path $env:USERPROFILE '.claude'),
+        'Y:\Projects',
+        'Y:\Information Technology\Scripts',
+        'Y:\Python',
+        'Y:\claude-settings'
+    ),
+    [switch]$Apply
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$caseInsensitiveOptions = [System.Text.RegularExpressions.RegexOptions]::IgnoreCase
+$ruleRewrites = @(
+    @{ Pattern = [regex]::new('^Bash\(powershell\.exe:\*\)$', $caseInsensitiveOptions);                                       Replacement = 'Bash(pwsh:*)' }
+    @{ Pattern = [regex]::new('^Bash\(powershell:\*\)$', $caseInsensitiveOptions);                                            Replacement = 'Bash(pwsh:*)' }
+    @{ Pattern = [regex]::new('^Bash\((?:powershell|pwsh)(?:\.exe)?\s+(?:-NoProfile\s+)?-Command\s+"&\s+''([^'']+)''(.*?)"\)$', $caseInsensitiveOptions); Replacement = 'Bash(pwsh -NoProfile -File ''$1''$2)' }
+    @{ Pattern = [regex]::new('^Bash\((?:powershell|pwsh)(?:\.exe)?\s+(?:-NoProfile\s+)?-Command\s+''&\s+"([^"]+)"(.*?)''\)$', $caseInsensitiveOptions); Replacement = 'Bash(pwsh -NoProfile -File "$1"$2)' }
+    @{ Pattern = [regex]::new('^Bash\(powershell\.exe\s+-Command\s+(.*)\)$', $caseInsensitiveOptions);                        Replacement = 'Bash(pwsh -NoProfile -Command $1)' }
+    @{ Pattern = [regex]::new('^Bash\(powershell\s+-Command\s+(.*)\)$', $caseInsensitiveOptions);                             Replacement = 'Bash(pwsh -NoProfile -Command $1)' }
+    @{ Pattern = [regex]::new('^Bash\(powershell\.exe\s+-NoProfile\s+-Command\s+(.*)\)$', $caseInsensitiveOptions);           Replacement = 'Bash(pwsh -NoProfile -Command $1)' }
+    @{ Pattern = [regex]::new('^Bash\(powershell\s+-NoProfile\s+-Command\s+(.*)\)$', $caseInsensitiveOptions);                Replacement = 'Bash(pwsh -NoProfile -Command $1)' }
+    @{ Pattern = [regex]::new('^Bash\(powershell\.exe\s+-NoProfile\s+-File\s+(.*)\)$', $caseInsensitiveOptions);              Replacement = 'Bash(pwsh -NoProfile -File $1)' }
+    @{ Pattern = [regex]::new('^Bash\(powershell\s+-NoProfile\s+-File\s+(.*)\)$', $caseInsensitiveOptions);                   Replacement = 'Bash(pwsh -NoProfile -File $1)' }
+    @{ Pattern = [regex]::new('^Bash\(powershell\.exe\s+-File\s+(.*)\)$', $caseInsensitiveOptions);                           Replacement = 'Bash(pwsh -NoProfile -File $1)' }
+    @{ Pattern = [regex]::new('^Bash\(powershell\s+-File\s+(.*)\)$', $caseInsensitiveOptions);                                Replacement = 'Bash(pwsh -NoProfile -File $1)' }
+    @{ Pattern = [regex]::new('^Bash\(bash\s+-c\s+(.*)\)$', $caseInsensitiveOptions);                                         Replacement = 'Bash(pwsh -NoProfile -Command $1)' }
+    @{ Pattern = [regex]::new('^Bash\(cmd\.exe\s+/c\s+(.*)\)$', $caseInsensitiveOptions);                                     Replacement = 'Bash(pwsh -NoProfile -Command $1)' }
+    @{ Pattern = [regex]::new('^Bash\(cmd\s+/c\s+(.*)\)$', $caseInsensitiveOptions);                                          Replacement = 'Bash(pwsh -NoProfile -Command $1)' }
+    @{ Pattern = [regex]::new('^Bash\(bash\s+--login\b.*\)$', $caseInsensitiveOptions);                                       Replacement = 'Bash(pwsh -NoProfile -Command ''Write-Error "manual conversion needed for bash --login rule"; exit 1'')' }
+    @{ Pattern = [regex]::new('^Bash\(bash\s+--rcfile\b.*\)$', $caseInsensitiveOptions);                                      Replacement = 'Bash(pwsh -NoProfile -Command ''Write-Error "manual conversion needed for bash --rcfile rule"; exit 1'')' }
+    @{ Pattern = [regex]::new('^Bash\(bash\s+--init-file\b.*\)$', $caseInsensitiveOptions);                                   Replacement = 'Bash(pwsh -NoProfile -Command ''Write-Error "manual conversion needed for bash --init-file rule"; exit 1'')' }
+)
+
+$settingsFileNames = @(
+    'settings.json',
+    'settings.local.json',
+    'settings.local.json.template'
+)
+
+function Get-MigratedRule {
+    param([string]$Rule)
+    foreach ($rewrite in $ruleRewrites) {
+        if ($rewrite.Pattern.IsMatch($Rule)) {
+            return $rewrite.Pattern.Replace($Rule, $rewrite.Replacement)
+        }
+    }
+    return $Rule
+}
+
+function Test-HasProperty {
+    param($Target, [string]$Name)
+    if ($null -eq $Target) { return $false }
+    if ($Target -isnot [psobject]) { return $false }
+    return ($Target.PSObject.Properties.Name -contains $Name)
+}
+
+function Convert-PermissionsArrays {
+    param($SettingsObject)
+    $rewriteCount = 0
+    if (-not (Test-HasProperty -Target $SettingsObject -Name 'permissions')) { return $rewriteCount }
+    $permissions = $SettingsObject.permissions
+    foreach ($key in @('allow', 'ask')) {
+        if (-not (Test-HasProperty -Target $permissions -Name $key)) { continue }
+        $existingArray = $permissions.$key
+        if ($null -eq $existingArray) { continue }
+        $newArray = @()
+        $seenMigratedStrings = [System.Collections.Generic.HashSet[string]]::new()
+        foreach ($rule in $existingArray) {
+            if ($rule -is [string]) {
+                $migrated = Get-MigratedRule -Rule $rule
+                $isRewrite = ($migrated -ne $rule)
+                if ($seenMigratedStrings.Contains($migrated)) {
+                    if ($isRewrite) {
+                        Write-Verbose "  dedupe-collapsed: '$rule' -> '$migrated' (duplicate of earlier rewrite)"
+                        $rewriteCount++
+                    }
+                    continue
+                }
+                [void]$seenMigratedStrings.Add($migrated)
+                if ($isRewrite) {
+                    Write-Verbose "  rewrite: '$rule' -> '$migrated'"
+                    $rewriteCount++
+                }
+                $newArray += $migrated
+            } else {
+                $newArray += $rule
+            }
+        }
+        $permissions.$key = $newArray
+    }
+    return $rewriteCount
+}
+
+$totalRewrites = 0
+$filesChanged = 0
+$scannedFileCount = 0
+$unparseableFileCount = 0
+$existingRoots = $Roots | Where-Object { Test-Path $_ }
+
+foreach ($root in $existingRoots) {
+    $candidateFiles = Get-ChildItem -Path $root -Recurse -File -ErrorAction SilentlyContinue |
+        Where-Object { $settingsFileNames -contains $_.Name }
+    foreach ($file in $candidateFiles) {
+        $rawContent = Get-Content -Path $file.FullName -Raw -ErrorAction SilentlyContinue
+        if ([string]::IsNullOrWhiteSpace($rawContent)) { continue }
+        try {
+            $parsed = $rawContent | ConvertFrom-Json -ErrorAction Stop
+        } catch {
+            $unparseableFileCount++
+            Write-Warning "Skipped (invalid JSON): $($file.FullName)"
+            continue
+        }
+        $scannedFileCount++
+        Write-Verbose "Scanning: $($file.FullName)"
+        $rewriteCount = Convert-PermissionsArrays -SettingsObject $parsed
+        if ($rewriteCount -gt 0) {
+            $totalRewrites += $rewriteCount
+            $filesChanged++
+            if ($Apply) {
+                $newJson = $parsed | ConvertTo-Json -Depth 100
+                [IO.File]::WriteAllText($file.FullName, $newJson, [Text.UTF8Encoding]::new($false))
+            }
+        }
+    }
+}
+
+if ($scannedFileCount -eq 0 -and $unparseableFileCount -eq 0) {
+    Write-Warning 'No settings files found in any of the configured roots — migration is vacuous.'
+    Write-Output 'MIGRATED: NO FILES SCANNED UNPARSEABLE=0 FILES'
+    exit 1
+}
+
+if ($scannedFileCount -eq 0 -and $unparseableFileCount -gt 0) {
+    Write-Output ('MIGRATED: NO FILES SCANNED UNPARSEABLE={0} FILES (migration unsound)' -f $unparseableFileCount)
+    exit 1
+}
+
+if ($totalRewrites -eq 0) {
+    Write-Output ('MIGRATED: 0 rules SCANNED={0} FILES UNPARSEABLE={1} FILES (already compliant)' -f $scannedFileCount, $unparseableFileCount)
+    if ($unparseableFileCount -gt 0) { exit 1 }
+    exit 0
+}
+
+if ($Apply) {
+    Write-Output ('MIGRATED: {0} rules IN={1} FILES SCANNED={2} FILES UNPARSEABLE={3} FILES' -f $totalRewrites, $filesChanged, $scannedFileCount, $unparseableFileCount)
+} else {
+    Write-Output ('DRY RUN: would migrate {0} rules IN={1} FILES SCANNED={2} FILES UNPARSEABLE={3} FILES' -f $totalRewrites, $filesChanged, $scannedFileCount, $unparseableFileCount)
+}
+if ($unparseableFileCount -gt 0) { exit 1 }
+exit 0

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

@@ -0,0 +1,171 @@
+---
+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.
+---
+
+# Auditing Claude Config
+
+This skill audits what gets eagerly loaded into every Claude Code session and identifies wins — duplicate imports, lazy-load candidates, skill-conversion candidates, and pointer-shrink opportunities. It is grounded in three Anthropic docs cited at the bottom.
+
+## When to invoke
+
+- `/memory` shows files the user did not expect to be loaded
+- The user is adding new rules and wants to know if the preload is growing past the recommended ceiling (CLAUDE.md target: under 200 lines)
+- Sessions feel sluggish or adherence to rules has degraded (the docs warn that bloated CLAUDE.md files cause Claude to ignore actual instructions)
+- A new template or shared `.claude/` directory has just been adopted
+- Periodic hygiene — quarterly is a reasonable cadence
+
+## Background facts the audit relies on
+
+These come from the official Claude Code documentation; do not re-derive them.
+
+| Fact | Source phrasing |
+|---|---|
+| `@path` imports in CLAUDE.md and rules expand into context **at launch** — they are not pointers | "Imported files are expanded and loaded into context at launch alongside the CLAUDE.md that references them" |
+| Splitting into `@`-imports does **not** reduce context | "Splitting into `@path` imports helps organization but does not reduce context, since imported files load at launch" |
+| Files in `.claude/rules/` without `paths:` frontmatter load **every** session | "Rules without `paths` frontmatter are loaded unconditionally and apply to all files" |
+| Path-scoped rules load **lazily** when matching files are accessed | "Rules can be scoped to specific files using YAML frontmatter with the `paths` field. These conditional rules only apply when Claude is working with files matching the specified patterns" |
+| Skills preload **metadata only** | "At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads SKILL.md only when the Skill becomes relevant, and reads additional files only as needed" |
+| `@`-imports inside fenced/inline code blocks do not trigger imports | Empirical (verified in this skill's source session) — referenced files alongside backtick-wrapped `@` paths do not appear in session-start context |
+
+## Audit workflow
+
+### Step 1 — Inventory the always-loaded set
+
+```
+Files to count:
+  ~/.claude/CLAUDE.md
+  ~/.claude/CLAUDE.local.md (if present)
+  ./CLAUDE.md (project root)
+  ./.claude/CLAUDE.md (project alt)
+  ./CLAUDE.local.md
+  every file in ~/.claude/rules/ without `paths:` frontmatter
+  every file in ./.claude/rules/ without `paths:` frontmatter
+  every file referenced via @-import from any of the above (recursively, max depth 5)
+```
+
+Count lines with `wc -l` (cygwin/Git Bash) or `Get-Content … | Measure-Object -Line` (PowerShell). Sum is the always-loaded line budget.
+
+Flag the result against the docs:
+- CLAUDE.md alone over 200 lines → strong nudge to slim
+- Total preload over ~1,000 lines → likely losing instruction adherence
+
+### Step 2 — Find duplicate `@`-imports
+
+Search every always-loaded file (CLAUDE.md and every rule file without `paths:`) for `@`-references. Build a multimap of `imported_path → [referrer_path, ...]`. Any entry with two or more referrers is loading the import twice into context.
+
+Fix: delete the import from one of the parents (keep it in the file with the broader scope, typically CLAUDE.md).
+
+### Step 3 — Classify each rule
+
+For every rule in `~/.claude/rules/` (and project `.claude/rules/`), apply this matrix:
+
+| Rule body describes | Verdict | Action |
+|---|---|---|
+| Behavior that applies every turn (TDD, conservative-action, ask-via-tool, etc.) | Keep always-on | No change |
+| File-type-specific patterns (Python idioms, JS/TS, Windows fs, test patterns) | Path-scope | Add `paths:` frontmatter with appropriate globs |
+| A multi-step workflow or procedure | Convert to skill | Move body to `~/.claude/skills/<name>/SKILL.md`, leave a 2-3 line pointer rule |
+| Content already covered by an existing skill in `~/.claude/skills/` | Shrink to pointer | Replace body with a 2-3 line reference to the skill |
+| Reference doc consumed only by one rule | Inline or co-locate | Move into the consumer rule or skill, drop the standalone doc |
+
+When suggesting `paths:` globs, derive them from the rule's body — do not guess. Examples:
+- Body discusses `shutil.rmtree`, `os.unlink` → `paths: ["**/*.py"]`
+- Body discusses `mkdirSync`, `fs.promises` → `paths: ["**/*.{mjs,js,ts}"]`
+- Body discusses pytest fixtures, test naming → `paths: ["**/test_*.py", "**/*_test.py", "**/conftest.py"]`
+
+### Step 4 — Produce the migration table
+
+Output one table with these columns: `Rule | Lines today | Verdict | Specific action | Lines removed from preload`. Total the savings. Express as both an absolute line count and a percentage of step 1's baseline.
+
+### Step 5 — Stage the changes
+
+Group recommendations by risk:
+- **Zero-risk:** duplicate-import deletion (largest single win in most setups)
+- **Low-risk:** adding `paths:` frontmatter (the docs guarantee fallback to "applies to all files" if syntax is wrong; verify with `/memory`)
+- **Medium-risk:** moving content into skills (changes when content reaches Claude — skill-discovery dependent)
+- **Author-required:** shrinking rules to pointers (requires deciding what content survives)
+
+## Empirical verification (optional)
+
+If the audit's recommendations rest on assumptions about lazy-load behavior — especially `@`-imports nested inside path-scoped rules — install this probe hook to capture every `InstructionsLoaded` event.
+
+### Hook script
+
+Path: `~/.claude/hooks/observability/instructions_loaded_logger.py`
+
+```python
+#!/usr/bin/env python3
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def main() -> int:
+    log_path = Path.home() / ".claude" / "logs" / "instructions_loaded.jsonl"
+    try:
+        payload = json.load(sys.stdin)
+        record = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "file_path": payload.get("file_path"),
+            "load_reason": payload.get("load_reason"),
+            "memory_type": payload.get("memory_type"),
+            "trigger_file_path": payload.get("trigger_file_path"),
+            "parent_file_path": payload.get("parent_file_path"),
+            "globs": payload.get("globs"),
+            "session_id": payload.get("session_id"),
+        }
+    except Exception as exception:
+        record = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "error": str(exception),
+        }
+    try:
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        with log_path.open("a", encoding="utf-8") as log_file:
+            log_file.write(json.dumps(record) + "\n")
+    except OSError:
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+```
+
+### settings.json registration
+
+Merge under `hooks.InstructionsLoaded` in `~/.claude/settings.json`:
+
+```json
+{
+  "matcher": "session_start|nested_traversal|path_glob_match|include|compact",
+  "hooks": [
+    {
+      "type": "command",
+      "command": "python ~/.claude/hooks/observability/instructions_loaded_logger.py"
+    }
+  ]
+}
+```
+
+### Test protocol
+
+1. Start a fresh Claude Code session in a directory with no test files (`*.test.*`, `test_*.py`, etc.).
+2. Read `~/.claude/logs/instructions_loaded.jsonl`. Every entry should have `load_reason: "session_start"` (plus any `nested_traversal` for ancestor CLAUDE.md files). Entries for path-scoped rules should be absent.
+3. Open a `.test.tsx` (or `test_foo.py`) file. Re-read the log. New entries should have `load_reason: "path_glob_match"` for the rule itself, and `load_reason: "include"` (with `parent_file_path` pointing at the rule) for any `@`-imports nested inside it.
+4. Acceptance: a rule classified as path-scoped does not appear in step 2 but does appear in step 3. Its nested imports follow the same pattern.
+
+## Output format
+
+Always end an audit run with:
+1. **Baseline:** total always-loaded lines today, broken down by file
+2. **Findings:** the migration table from step 4
+3. **Recommended next step:** the single highest-leverage change (usually duplicate-import deletion)
+4. **Open questions:** anything not verified empirically
+
+## Sources
+
+- [Claude Code — How Claude remembers your project](https://code.claude.com/docs/en/memory)
+- [Claude Code — Hooks (InstructionsLoaded)](https://code.claude.com/docs/en/hooks)
+- [Claude API — Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)

package/skills/caveman/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: caveman
+description: "Inline counterpart to the caveman agent — trim noise from `$ARGUMENTS` (or the previous assistant message) and reply with the trimmed text only, no report, no Agent spawn. Triggers: /caveman, caveman this, trim this, make it terse, caveman voice."
+argument-hint: "[text to trim, or omit and the model uses the previous assistant message]"
+---
+
+# Caveman
+
+Inline counterpart to the `caveman` agent at `packages/claude-dev-env/agents/caveman.md`. Use this skill when the trim target is conversational text in the current turn rather than a separate file or multi-section artifact. The model performs the trim itself in the next reply — no `Agent` invocation, no structured report, just the trimmed text.
+
+## Instructions
+
+1. **Resolve the source.** If `$ARGUMENTS` is non-empty, that text is the trim source. Otherwise the source is the previous assistant message in the current conversation.
+
+2. **Trim the same noise categories the agent trims:**
+
+   | Noise type | Example |
+   |---|---|
+   | Preamble / recap | "As discussed above, this skill will..." |
+   | Hedging | "This might, in some cases, potentially..." |
+   | Filler transitions | "Now, moving on to..." / "It's worth noting that..." |
+   | Restatement | the same point made twice in different words |
+   | Empty future-proofing | parameters, sections, or fields with no current consumer |
+   | Dead examples | examples that duplicate another example without adding coverage |
+   | Pleasantries | "Hope this helps." / "Feel free to..." |
+   | Vague qualifiers | "various", "several", "a number of" — replace with the actual count or cut |
+
+3. **Preserve verbatim:** code, commands, paths, URLs, errors, JSON, schemas, frontmatter, counts, version strings, identifiers, safety/destructive-op language, and anything the user explicitly flagged as keep-as-is.
+
+4. **Output only the trimmed text.** No `trimmed / removed / preserved-verbatim / flagged` report. No commentary about what was cut. No preamble like "Here is the trimmed version:". The trimmed text is the entire reply.
+
+## Escape hatch
+
+If trimming would drop a safety warning, collapse a deliberate distinction, or you are unsure whether a span is load-bearing, leave that span in place verbatim. Do not flag, narrate, or ask about the preserved span — instruction 4 still applies, so the trimmed text (with the preserved span included) remains the entire reply. Terse is for noise, not for substance.
+
+## When NOT to use
+
+Use the `caveman` agent (via `Task` / `Agent` tool with `subagent_type: caveman`) when the input is a file path, a multi-section artifact requiring the structured `trimmed / removed / preserved-verbatim / flagged` report, or any delegated workflow. This skill is for inline conversational text only.

package/skills/pr-converge/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: pr-converge
+description: >-
+  Drives the current PR to convergence by alternating Cursor Bugbot and the
+  in-house bugteam audit. Each invocation runs one tick of work in the main
+  session: fetches the latest reviewer state, applies TDD fixes for any
+  findings, pushes one commit per tick, replies inline, and re-triggers the
+  reviewer. To loop automatically, invoke as `/loop /pr-converge` — the /loop
+  skill self-paces re-entry via ScheduleWakeup. Convergence requires a
+  back-to-back clean cycle (bugbot CLEAN immediately followed by bugteam CLEAN
+  with no intervening fixes), at which point the PR is flipped to ready for
+  review and the loop terminates. Triggers: '/pr-converge', 'drive PR to
+  convergence', 'loop bugbot and bugteam', 'babysit bugbot and bugteam',
+  'until both are clean', 'converge this PR'.
+---
+
+# PR Converge
+
+Runs one tick of the bugbot ↔ bugteam convergence loop in the main session. Designed to be invoked under `/loop /pr-converge` so the parent's ScheduleWakeup paces re-entry. Self-terminates the loop on convergence (back-to-back clean) by flipping the PR to ready for review and omitting the next ScheduleWakeup.
+
+## Why the work runs in the main session, not a background subagent
+
+`ScheduleWakeup` is a primitive of the parent harness; it is not exposed to `general-purpose` subagents. A prior version of this skill spawned a background subagent and instructed it to call `ScheduleWakeup` at the end of each tick. The subagent's tool registry returned "No matching deferred tools found" for `ScheduleWakeup`, so the loop could never self-perpetuate — it ran exactly one tick and stalled. Running the loop in the main session via `/loop /pr-converge` puts the work on the same harness that owns `ScheduleWakeup`, eliminating that failure mode.
+
+## When this skill applies
+
+The user is on a PR branch and wants both reviewers — Cursor's Bugbot AND the in-house `/bugteam` audit — to keep re-reviewing after each push, with findings auto-addressed between ticks. The PR stays in draft until convergence; on convergence the skill flips it to ready for review.
+
+## Invocation modes
+
+- **`/loop /pr-converge`** (recommended): loops automatically. The /loop skill runs each tick and uses ScheduleWakeup to pace re-entry. Termination on convergence is automatic; the skill omits the next wakeup at the convergence tick.
+- **`/pr-converge`** (manual): runs exactly one tick and returns. Useful for ad-hoc state checks or for advancing the loop one step manually. The user re-runs the skill (or wraps it in `/loop`) to continue.
+
+## State across ticks
+
+Track the following in plain text in the assistant's response so subsequent ticks can re-read it from conversation context:
+
+- `phase`: `BUGBOT` or `BUGTEAM`. Start in `BUGBOT` on the first tick of a fresh loop.
+- `bugbot_clean_at`: the HEAD SHA at which bugbot last reported clean, or `null`. Reset to `null` whenever a new commit is pushed.
+- `inline_lag_streak`: integer counter, initialized to `0`. Tracks consecutive ticks where bugbot's review body indicates findings against `current_head` but the inline-comments API returns zero matching comments. Reset to `0` on any other branch outcome.
+- `tick_count`: integer, initialized to `0`. Increment on every tick to enforce the safety cap.
+
+Each tick begins by reading the prior tick's state line from the most recent assistant message and ends by emitting the updated state line.
+
+## Per-tick work
+
+### Step 1: Resolve current HEAD and PR context
+
+Read the prior tick's state line from the most recent assistant message (or initialize all fields if none). **Increment `tick_count` by 1.** This is the increment referenced in the **State across ticks** section; without it the safety cap (Step 3.5, §Safety cap) never fires.
+
+```bash
+gh pr view --json number,url,headRefOid,baseRefName,headRefName,isDraft
+```
+
+Capture `number` (`<NUMBER>`), `headRefOid` (`current_head`), owner/repo (from `url`), branch name (`<BRANCH>`).
+
+### Step 2: Branch on `phase`
+
+#### `phase == BUGBOT`
+
+a. Fetch the latest Cursor Bugbot review:
+   ```bash
+   gh api repos/<OWNER>/<REPO>/pulls/<NUMBER>/reviews \
+     --jq '[.[] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
+   ```
+   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.
+
+b. Fetch unaddressed inline comments from `cursor[bot]` on `current_head`:
+   ```bash
+   gh api repos/<OWNER>/<REPO>/pulls/<NUMBER>/comments \
+     --jq "[.[] | select(.user.login==\"cursor[bot]\") | select(.commit_id==\"$current_head\")]"
+   ```
+
+c. Decide (the four branches below cover every input combination — match the first branch whose predicate holds):
+   - **No bugbot review yet, OR latest bugbot review's `commit_id` differs from `current_head`:** Re-trigger bugbot (Step 3), set `bugbot_clean_at = null`, reset `inline_lag_streak = 0`, schedule next wakeup, return.
+   - **Latest review's `commit_id == current_head` AND zero unaddressed inline findings AND review body indicates clean:** Set `bugbot_clean_at = current_head`. Reset `inline_lag_streak = 0`. Transition `phase = BUGTEAM`. Continue to bugteam branch in this same tick — back-to-back convergence requires bugteam to run against the same HEAD before the next wakeup is scheduled.
+   - **Latest review's `commit_id == current_head` with unaddressed inline findings (review body indicates findings):** Apply the **Fix protocol** below to address them. Reset `inline_lag_streak = 0`. The fix protocol pushes a new commit, which sets `current_head` to the new SHA, sets `bugbot_clean_at = null`, replies inline on each thread, and re-triggers bugbot. Schedule next wakeup, return.
+   - **Latest review's `commit_id == current_head` AND review body indicates findings AND inline-comments API returns zero matching comments for `current_head`:** Treat as transient API propagation lag — bugbot publishes the review body and inline comments through separate API operations and the two writes can briefly desync. Increment `inline_lag_streak`. When `inline_lag_streak >= 3`, escalate as a hard blocker (bugbot review is structurally inconsistent — body claims findings while inline anchors stay empty across three consecutive ticks); report and terminate. Otherwise schedule next wakeup at `delaySeconds: 60` (lag is short-lived) and return; the inline comments should appear on the next tick.
+
+#### `phase == BUGTEAM`
+
+a. Run the in-house bugteam audit on the current PR by invoking the `Skill` tool in the main session:
+
+   ```
+   Skill({skill: "bugteam", args: "https://github.com/<OWNER>/<REPO>/pull/<NUMBER>"})
+   ```
+
+   The main session is the team lead, so `TeamCreate` fires from the orchestrator and `/bugteam` emits its CODE_RULES gate output, teammate spawn lines, and audit progress as expected. The skill audits the current PR against CODE_RULES, posts review threads, and converges or stops at its own internal cap. Wait for it to complete; capture exit and final summary.
+
+b. **Re-resolve current HEAD now** because `/bugteam` may have pushed commits during its run. The `current_head` from Step 1 is potentially stale at this point:
+   ```bash
+   new_head=$(gh api repos/<OWNER>/<REPO>/pulls/<NUMBER> --jq '.head.sha')
+   ```
+   If `new_head != current_head`, set `current_head = new_head` AND set `bugbot_clean_at = null`. The new commits from bugteam invalidate bugbot's prior clean.
+
+c. Inspect bugteam's output. Bugteam reports either `convergence (zero findings)` or a list of unfixed findings with file:line.
+
+d. Decide based on the (post-bugteam) state — order matters; check pushed-during-bugteam FIRST so a convergence report against a stale HEAD never falsely terminates:
+   - **bugteam pushed during this tick (i.e., `bugbot_clean_at` was just reset to `null` in step b):** Re-trigger bugbot in this same tick (Step 3) so the new HEAD enters bugbot's queue immediately, transition `phase = BUGBOT`, schedule next wakeup, return. The new commit needs a fresh bugbot review before convergence can be claimed.
+   - **bugteam reports convergence AND `bugbot_clean_at == current_head` (no push during this tick):** This is back-to-back clean. Mark the PR ready for review:
+     ```bash
+     gh pr ready <NUMBER> --repo <OWNER>/<REPO>
+     ```
+     Report to the user in one sentence: "PR #<NUMBER> converged: bugbot CLEAN at <SHA>, bugteam CLEAN at <SHA>; marked ready for review." **Omit the next ScheduleWakeup call** — this terminates the /loop.
+   - **bugteam reports convergence BUT `bugbot_clean_at != current_head` (no push during this tick):** Bugteam reached zero findings without committing, yet bugbot still needs re-confirmation against this HEAD. This branch is reachable only when state diverged BETWEEN ticks — for example, the user pushed a manual commit between two wakeups, leaving `current_head` ahead of the SHA bugbot last cleaned. Transition `phase = BUGBOT`, schedule next wakeup, return.
+   - **bugteam reports findings without committing fixes:** apply the **Fix protocol** below (which always re-triggers bugbot after the push), transition `phase = BUGBOT`, schedule next wakeup, return.
+
+### Step 3: Re-trigger bugbot
+
+Used in Step 2 BUGBOT branch 1, in Step 2 BUGTEAM branch 1, and in the Fix protocol. Post a literal `bugbot run` PR comment. Write the body via the Write tool to a temp file, then pass it with `--body-file` (per the gh-body-file rule):
+
+```bash
+gh pr comment <NUMBER> --repo <OWNER>/<REPO> --body-file <path/to/bugbot_run.md>
+```
+
+The body file contains exactly the literal phrase `bugbot run` followed by a newline. Use that phrase exactly — empirically the only re-trigger Cursor Bugbot recognizes; alternative phrasings (`re-review`, `bugbot please`, etc.) silently no-op.
+
+### Step 3.5: Enforce the safety cap
+
+Before scheduling the next wakeup, evaluate `tick_count`. When `tick_count >= 30`, stop and report per the **Stop conditions** safety-cap branch (§Safety cap) — **omit Step 4 entirely**. Reaching this many rounds means something structural is wrong with the loop and continuing wastes work. Otherwise proceed to Step 4.
+
+### Step 4: Schedule the next wakeup (only when invoked under `/loop`)
+
+**Skip this step entirely when the skill was invoked as bare `/pr-converge`** (manual mode). Manual mode runs exactly one tick and returns without scheduling — the user re-runs the skill or wraps it in `/loop` to continue. References elsewhere in this document to "schedule next wakeup, return" mean Step 4 below; under manual mode every such reference becomes "return" only.
+
+Detect manual mode by inspecting the conversation context: when the most recent user message that triggered this run was `/pr-converge` (no `/loop` prefix and no prior `ScheduleWakeup` chain entry that fired with `prompt: "/loop /pr-converge"`), this is manual mode. When the run was triggered by the parent's /loop wakeup chain or the user typed `/loop /pr-converge`, this is loop mode.
+
+In **loop mode**, call `ScheduleWakeup` with:
+
+- `delaySeconds: 270` whenever bugbot was just re-triggered (whether by Step 3 directly, by the Fix protocol's mandatory re-trigger, or by BUGTEAM branch 1's same-tick re-trigger). Bugbot finishes a review in 1–4 minutes, so 270s stays under the 5-minute prompt-cache TTL while giving a margin past bugbot's typical upper bound. The single exception is the BUGBOT inline-lag branch, which uses `delaySeconds: 60` because no re-trigger fired and the only thing being awaited is GitHub's inline-comments API catching up.
+- `reason`: one short sentence on what is being awaited, including the current `phase` and `bugbot_clean_at` SHA when set.
+- `prompt: "/loop /pr-converge"` — re-enters this skill via /loop on the next firing.
+
+**On convergence (loop mode):** omit the ScheduleWakeup call entirely. The /loop terminates because no next wakeup was scheduled.
+
+## Fix protocol
+
+Used by both phases when findings exist:
+
+- Read each referenced file:line.
+- Write a failing test first when the finding has behavior to test. For pure doc, comment, or naming nits with no behavior, go straight to the fix.
+- Implement the fix.
+- Stage the affected files and create one new commit on the existing branch:
+  ```bash
+  git add <files> && git commit -m "fix(review): <brief summary>"
+  ```
+  Honor pre-commit and pre-push hooks; when a hook rejects, read its message, fix the underlying issue, retry. Hook rejections flag real underlying issues worth investigating.
+- Push the new commit:
+  ```bash
+  git push origin <BRANCH>
+  ```
+  Capture the new HEAD SHA. Set `current_head` to it. Set `bugbot_clean_at = null`.
+- Reply inline on each addressed comment thread using `--body-file` (per gh-body-file rule):
+  ```bash
+  gh api -X POST repos/<OWNER>/<REPO>/pulls/<NUMBER>/comments/<comment_id>/replies \
+    --field body=@<path/to/reply.md>
+  ```
+- **Always re-trigger bugbot (Step 3 above) after pushing a fix**, regardless of which phase originated the findings. Any new commit invalidates bugbot's prior clean by definition, so bugbot must re-review the new HEAD before convergence can be claimed. Re-triggering in the same tick saves a full wakeup cycle compared to deferring the trigger to the next tick.
+
+## Stop conditions
+
+- **Convergence** (back-to-back clean as defined in Step 2 BUGTEAM second branch — `bugteam reports convergence AND bugbot_clean_at == current_head` with no push during this tick): mark PR ready for review, report one-sentence summary, omit ScheduleWakeup.
+- **Hard blocker:** API auth failure persists across two ticks, a CI regression whose root cause falls outside this PR, a hook rejection investigated through three commits and still unresolved, `inline_lag_streak >= 3`, or `/bugteam` itself reports a stuck state. Report the specific blocker and the diagnosis, then omit ScheduleWakeup.
+- **User stops the loop:** user says "stop the converge loop" → omit ScheduleWakeup on the next tick.
+- **Safety cap:** `tick_count >= 30` (evaluated in Step 3.5) → omit ScheduleWakeup, report the cap was hit. See §Safety cap below for rationale.
+
+## Safety cap
+
+When `tick_count >= 30`, stop and report. That many rounds means something structural is wrong with the loop. (Higher than copilot-review's 20-tick cap because two reviewers run sequentially per round.) The increment lives in Step 1; the evaluation lives in Step 3.5.
+
+## Ground rules
+
+- **Append commits.** Each tick adds at most one new fix commit. Multiple findings within one tick collapse into a single commit; the next tick handles the next round.
+- **`bugbot_clean_at` resets on every push.** A new commit invalidates bugbot's prior clean by definition — bugbot must re-review the new HEAD before convergence can be claimed.
+- **Back-to-back clean is the ONLY termination criterion.** Convergence requires both reviewers clean against the same HEAD with no intervening fixes; either reviewer clean alone counts as in-progress.
+- **The `bugbot run` comment is load-bearing.** Use the literal phrase `bugbot run` exactly — empirically the only re-trigger Cursor Bugbot recognizes; alternative phrasings silently no-op.
+- **`gh pr ready` is the convergence action.** Mark the PR ready for review and stop there. Merge, additional reviewers, title, and body remain the user's decisions; the skill's contract ends at "ready for review."
+- **Honor pre-push and pre-commit hooks.** When a hook rejects the change, read its output, fix the underlying issue (the failing test, the missing constant, the broken import), and retry.
+
+## Examples
+
+<example>
+User: `/loop /pr-converge`
+Claude: [reads PR context, runs one tick of bugbot phase, schedules next wakeup at 270s with prompt `/loop /pr-converge`, returns]
+</example>
+
+<example>
+User: `/pr-converge`
+Claude: [runs one tick manually, reports state, does NOT schedule a wakeup; user re-runs to advance]
+</example>
+
+<example>
+Tick fires in BUGBOT phase, latest bugbot review is against an older commit.
+Claude: [posts `bugbot run` comment, sets `bugbot_clean_at = null`, schedules next wakeup at 270s, returns]
+</example>
+
+<example>
+Tick fires in BUGBOT phase, bugbot has 2 unaddressed findings on HEAD.
+Claude: [TDD-fixes both, one commit, pushes, replies inline on both threads, posts `bugbot run`, schedules next wakeup at 270s, returns]
+</example>
+
+<example>
+Tick fires in BUGBOT phase, bugbot is clean against HEAD.
+Claude: [sets `bugbot_clean_at = HEAD`, transitions `phase = BUGTEAM`, runs `/bugteam` in the same tick]
+</example>
+
+<example>
+In BUGTEAM phase, /bugteam reports convergence and `bugbot_clean_at == current_head`.
+Claude: [runs `gh pr ready <NUMBER>`, reports "PR converged: bugbot CLEAN at <SHA>, bugteam CLEAN at <SHA>; marked ready for review", omits ScheduleWakeup, terminates the /loop]
+</example>
+
+<example>
+In BUGTEAM phase, /bugteam pushed a fix commit during its run.
+Claude: [re-resolves HEAD, sets `bugbot_clean_at = null`, posts `bugbot run` in this same tick, transitions `phase = BUGBOT`, schedules next wakeup at 270s]
+</example>
+
+<example>
+Tick fires in BUGBOT phase, bugbot review body says "found 3 potential issues" against HEAD but the inline-comments API returns zero matching comments for `current_head`.
+Claude: [increments `inline_lag_streak` to 1, schedules next wakeup at 60s, returns; expects inline comments to appear by the next tick]
+</example>