claude-dev-env 1.32.0 → 1.34.0

package/rules/windows-filesystem-safe.md

@@ -53,9 +53,7 @@ Two things to know about the handler:
 If a skill or runbook genuinely needs a one-line shell invocation, the equivalent without `ignore_errors=True` is:
 
 ```bash
-python -c "import os, shutil, stat, sys; \
-def _h(f, p, *_): os.chmod(p, stat.S_IWRITE); f(p); \
-shutil.rmtree(r'<path>', **({'onexc': _h} if sys.version_info >= (3, 12) else {'onerror': _h}))"
+python -c "import os, shutil, stat, sys; h = lambda f, p, *_: (os.chmod(p, stat.S_IWRITE), f(p)); shutil.rmtree(r'<path>', **({'onexc': h} if sys.version_info >= (3, 12) else {'onerror': h}))"
 ```
 
 Prefer the multi-line `force_rmtree` helper — the one-liner is hard to read and easy to mis-quote.

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/bugteam/PROMPTS.md

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

package/skills/bugteam/SKILL.md

@@ -81,7 +81,9 @@ The fix script removes any non-canonical local-scope override on the active repo
 [ ] Step 0: project permissions granted
 [ ] Step 1: PR scope resolved
 [ ] Step 2: agent team created + loop state set
+[ ] Step 2.6: INITIAL standards review against cumulative PR diff
 [ ] Step 3: cycle complete (converged | cap reached | stuck | error)
+[ ] Step 3.5: FINAL standards review against cumulative PR diff
 [ ] Step 4: team torn down + working tree clean
 [ ] Step 4.5: PR description rewritten (or skip warning logged)
 [ ] Step 5: project permissions revoked
@@ -203,6 +205,23 @@ jq -n \
 
 **Endpoints:** `POST .../pulls/{pull}/reviews`; `POST .../pulls/{pull}/comments/{id}/replies`; fallback `POST .../issues/{issue}/comments` (`issue` = PR number).
 
+### Step 2.6: INITIAL standards review (once, before Loop 1 audit)
+
+Run BEFORE the first pre-audit gate fires. Spawn a fresh `code-quality-agent`
+teammate inside the same team and drive it through the K–N addendum (see
+PROMPTS.md `<copilot_derived_addendum_source>`). The teammate audits the
+cumulative PR diff (`gh pr diff <N>`) instead of a single loop's incremental
+patch; clean-room context is preserved by the same agent-team isolation as
+the per-loop bugfind teammate. Findings are posted using the same Step 2.5
+review-shape with body `## /bugteam INITIAL standards review against PR #<N>
+cumulative diff: <P0>P0 / <P1>P1 / <P2>P2`. Findings advance the audit/fix
+cycle exactly as if they had been raised in Loop 1: the lead increments
+`loop_count` to 1, sets `last_action = "audited"` with the merged
+`last_findings`, and Step 3 begins on the FIX branch. When the INITIAL
+review returns zero findings, `loop_count` stays at 0 and Step 3 begins on
+the AUDIT branch as before. Failure on this phase logs the error and
+proceeds to Step 3 unchanged so the legacy A–J cycle still runs.
+
 ### Step 3: The cycle
 
 Run the AUDIT-FIX cycle for each PR in all_prs, reusing the same team across PRs. The 10-loop cap applies per PR. Exit reasons (converged, cap reached, stuck, error) are tracked per PR; the final report lists one outcome line per PR.
@@ -285,6 +304,19 @@ Pass finding comment URLs/ids from `loop_comment_index` in XML. Replies: `Fixed
 
 [`PROMPTS.md`](PROMPTS.md): fix XML + schema. Verify: `git rev-parse HEAD` advanced; `git fetch origin <branch> && git rev-parse origin/<branch>` matches `HEAD`. Unchanged HEAD → `stuck — bugfix teammate could not address findings`.
 
+### Step 3.5: FINAL standards review (once, after convergence)
+
+Run AFTER Step 3 exits with `converged`, `cap reached`, or `stuck`, and
+BEFORE Step 4 teardown. Spawn one more fresh `code-quality-agent` teammate;
+audit the cumulative PR diff against the K–N addendum a second time. Post
+the review with body `## /bugteam FINAL standards review against PR #<N>
+cumulative diff: <P0>P0 / <P1>P1 / <P2>P2`. When findings remain, the
+exit reason is upgraded to `error: final standards review found <P0>+<P1>+<P2>
+unresolved finding(s)` and the loop log gains an extra `final-review` line.
+A clean FINAL review preserves the existing exit reason. Failure on this
+phase logs the error and continues to Step 4 unchanged so teardown,
+permission revoke, and the final report still run.
+
 ### Step 4: Teardown
 
 1. For each live teammate: `SendMessage(to="<name>", message={"type": "shutdown_request", "reason": "bugteam cycle ending"})`. `approve: false` on cleanup → log and continue.
@@ -329,8 +361,10 @@ Final commit: <current_HEAD_sha7>
 Net change: <total_files> files, +<total_add>/-<total_del>
 
 Loop log:
+  initial standards review: 1P0 0P1 2P2
   1 audit: 3P0 2P1 0P2
   ...
+  final standards review: 0P0 0P1 0P2
 ```
 
 `cap reached` → suggest `/findbugs`. `stuck` → which findings. `error` → detail + loop.