claude-dev-env 2.0.2 → 2.2.0

package/skills/_shared/pr-loop/scripts/test_select_converge_pacer.py

@@ -0,0 +1,207 @@
+"""Tests for select_converge_pacer — host tool surface → pacer mapping."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+import select_converge_pacer as pacer_module  # noqa: E402
+from skills_pr_loop_constants.pacer_constants import (  # noqa: E402
+    CLI_HAS_SCHEDULE_WAKEUP_FLAG,
+    CLI_HAS_WORKFLOW_FLAG,
+    CLI_SKILL_FLAG,
+    ENTRY_SKILL_AUTOCONVERGE,
+    ENTRY_SKILL_PR_CONVERGE,
+    EXIT_SUCCESS,
+    EXIT_USAGE_ERROR,
+    PACER_PORTABLE,
+    PACER_SCHEDULE_WAKEUP,
+    PACER_WORKFLOW,
+    RESULT_KEY_ENTRY_SKILL,
+    RESULT_KEY_HAS_SCHEDULE_WAKEUP,
+    RESULT_KEY_HAS_WORKFLOW,
+    RESULT_KEY_PACER,
+)
+
+SCRIPT_PATH = _SCRIPTS_DIR / "select_converge_pacer.py"
+
+
+def test_autoconverge_with_workflow_selects_workflow() -> None:
+    selection = pacer_module.select_converge_pacer(
+        entry_skill=ENTRY_SKILL_AUTOCONVERGE,
+        has_workflow=True,
+        has_schedule_wakeup=False,
+    )
+    assert selection.pacer == PACER_WORKFLOW
+    assert selection.entry_skill == ENTRY_SKILL_AUTOCONVERGE
+
+
+def test_autoconverge_without_workflow_selects_portable() -> None:
+    selection = pacer_module.select_converge_pacer(
+        entry_skill=ENTRY_SKILL_AUTOCONVERGE,
+        has_workflow=False,
+        has_schedule_wakeup=True,
+    )
+    assert selection.pacer == PACER_PORTABLE
+
+
+def test_pr_converge_with_schedule_wakeup_selects_schedule_wakeup() -> None:
+    selection = pacer_module.select_converge_pacer(
+        entry_skill=ENTRY_SKILL_PR_CONVERGE,
+        has_workflow=False,
+        has_schedule_wakeup=True,
+    )
+    assert selection.pacer == PACER_SCHEDULE_WAKEUP
+    assert selection.entry_skill == ENTRY_SKILL_PR_CONVERGE
+
+
+def test_pr_converge_without_schedule_wakeup_selects_portable() -> None:
+    selection = pacer_module.select_converge_pacer(
+        entry_skill=ENTRY_SKILL_PR_CONVERGE,
+        has_workflow=True,
+        has_schedule_wakeup=False,
+    )
+    assert selection.pacer == PACER_PORTABLE
+
+
+def test_third_party_surface_selects_portable_for_both_entries() -> None:
+    for each_skill in (ENTRY_SKILL_AUTOCONVERGE, ENTRY_SKILL_PR_CONVERGE):
+        selection = pacer_module.select_converge_pacer(
+            entry_skill=each_skill,
+            has_workflow=False,
+            has_schedule_wakeup=False,
+        )
+        assert selection.pacer == PACER_PORTABLE, each_skill
+
+
+def test_unknown_entry_skill_raises() -> None:
+    with pytest.raises(ValueError, match="entry skill must be one of"):
+        pacer_module.select_converge_pacer(
+            entry_skill="bugteam",
+            has_workflow=False,
+            has_schedule_wakeup=False,
+        )
+
+
+def test_parse_bool_flag_accepts_common_tokens() -> None:
+    assert pacer_module.parse_bool_flag("1") is True
+    assert pacer_module.parse_bool_flag("true") is True
+    assert pacer_module.parse_bool_flag("YES") is True
+    assert pacer_module.parse_bool_flag("0") is False
+    assert pacer_module.parse_bool_flag("false") is False
+    assert pacer_module.parse_bool_flag("OFF") is False
+
+
+def test_parse_bool_flag_rejects_unknown_token() -> None:
+    with pytest.raises(ValueError, match="boolean token"):
+        pacer_module.parse_bool_flag("maybe")
+
+
+def test_selection_as_json_dict_uses_stable_keys() -> None:
+    selection = pacer_module.select_converge_pacer(
+        entry_skill=ENTRY_SKILL_PR_CONVERGE,
+        has_workflow=False,
+        has_schedule_wakeup=False,
+    )
+    payload = pacer_module.selection_as_json_dict(selection)
+    assert payload[RESULT_KEY_PACER] == PACER_PORTABLE
+    assert payload[RESULT_KEY_ENTRY_SKILL] == ENTRY_SKILL_PR_CONVERGE
+    assert payload[RESULT_KEY_HAS_WORKFLOW] is False
+    assert payload[RESULT_KEY_HAS_SCHEDULE_WAKEUP] is False
+
+
+def test_cli_prints_json_and_exits_zero() -> None:
+    completed = subprocess.run(
+        [
+            sys.executable,
+            str(SCRIPT_PATH),
+            "--skill",
+            ENTRY_SKILL_AUTOCONVERGE,
+            "--has-workflow",
+            "0",
+            "--has-schedule-wakeup",
+            "0",
+        ],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    assert completed.returncode == EXIT_SUCCESS, completed.stderr
+    payload = json.loads(completed.stdout)
+    assert payload[RESULT_KEY_PACER] == PACER_PORTABLE
+    assert payload[RESULT_KEY_ENTRY_SKILL] == ENTRY_SKILL_AUTOCONVERGE
+
+
+def test_cli_rejects_bad_bool_with_usage_exit() -> None:
+    completed = subprocess.run(
+        [
+            sys.executable,
+            str(SCRIPT_PATH),
+            "--skill",
+            ENTRY_SKILL_PR_CONVERGE,
+            "--has-workflow",
+            "nope",
+            "--has-schedule-wakeup",
+            "0",
+        ],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    assert completed.returncode == EXIT_USAGE_ERROR
+    assert "boolean token" in completed.stderr
+
+
+def test_main_returns_usage_error_on_value_error(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def raise_value_error(**_kwargs: object) -> object:
+        raise ValueError("entry skill must be one of")
+
+    monkeypatch.setattr(
+        pacer_module, "select_converge_pacer", raise_value_error
+    )
+    exit_code = pacer_module.main(
+        [
+            "--skill",
+            ENTRY_SKILL_PR_CONVERGE,
+            "--has-workflow",
+            "0",
+            "--has-schedule-wakeup",
+            "0",
+        ]
+    )
+    assert exit_code == EXIT_USAGE_ERROR
+
+
+def test_build_argument_parser_requires_skill_and_host_flags() -> None:
+    parser = pacer_module.build_argument_parser()
+    all_option_strings = {
+        each_option
+        for each_action in parser._actions
+        for each_option in each_action.option_strings
+    }
+    assert CLI_SKILL_FLAG in all_option_strings
+    assert CLI_HAS_WORKFLOW_FLAG in all_option_strings
+    assert CLI_HAS_SCHEDULE_WAKEUP_FLAG in all_option_strings
+    parsed_namespace = parser.parse_args(
+        [
+            CLI_SKILL_FLAG,
+            ENTRY_SKILL_AUTOCONVERGE,
+            CLI_HAS_WORKFLOW_FLAG,
+            "1",
+            CLI_HAS_SCHEDULE_WAKEUP_FLAG,
+            "0",
+        ]
+    )
+    assert parsed_namespace.skill == ENTRY_SKILL_AUTOCONVERGE
+    assert parsed_namespace.has_workflow == "1"
+    assert parsed_namespace.has_schedule_wakeup == "0"

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

@@ -9,6 +9,7 @@ Audits a Claude Code setup — user `CLAUDE.md`, `~/.claude/rules/`, project `.c
 | File | Role |
 |---|---|
 | `SKILL.md` | Full audit protocol: inventory the always-loaded set, find duplicate imports, classify each rule, produce the migration table, stage recommendations by risk, and verify lazy-load behavior with an optional probe hook. |
+| `reference/probe-hook.md` | The optional lazy-load probe hook: hook script, `settings.json` registration, and test protocol. |
 
 ## What the skill produces
 
@@ -17,4 +18,4 @@ Audits a Claude Code setup — user `CLAUDE.md`, `~/.claude/rules/`, project `.c
 3. **Recommended next step** — the single highest-leverage change.
 4. **Open questions** — anything not verified by the probe hook.
 
-No scripts or workflow files. The skill body holds all logic.
+No runnable scripts or workflow files. The audit logic lives in the skill body; the optional lazy-load probe hook lives in `reference/probe-hook.md` as copy-ready text.

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

@@ -1,176 +1,114 @@
----
-name: auditing-claude-config
-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
-
-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 (`InstructionsLoaded` hook): a bare `@`-import fires an `include` load event; the same path wrapped in backticks fires none, so the referenced file stays out of 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)
+---
+name: auditing-claude-config
+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
+
+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)
+
+When the audit's recommendations rest on assumptions about lazy-load behavior —
+especially `@`-imports nested inside path-scoped rules — install the probe hook
+in [`reference/probe-hook.md`](reference/probe-hook.md) to capture every
+`InstructionsLoaded` event. It carries the hook script, the `settings.json`
+registration, and the test protocol that confirms a path-scoped rule loads
+lazily while its nested imports follow.
+
+## 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/auditing-claude-config/reference/probe-hook.md

@@ -0,0 +1,74 @@
+# Lazy-load probe hook
+
+Optional empirical check for the `auditing-claude-config` skill. When 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. The hub ([`../SKILL.md`](../SKILL.md) §
+Empirical verification) points here.
+
+## 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.

package/skills/autoconverge/CLAUDE.md

@@ -2,7 +2,7 @@
 
 **Trigger:** `/autoconverge`, "autoconverge this PR", "converge this PR in one run", "run the converge workflow", "drive the PR to ready autonomously".
 
-Drives one draft PR to convergence in a single autonomous workflow run. Each round runs a deterministic static sweep first, then a code-review pass, a bug-audit (with its adversarial second pass), and a self-review parity pass in parallel on the same HEAD, deduplicates findings, applies every fix in one commit, and re-verifies. Once the internal lenses are clean, Cursor Bugbot, Copilot, and Codex run as terminal confirmation gates, and the run marks the PR ready on convergence. State lives in the workflow journal; no `ScheduleWakeup` ticks.
+Drives one draft PR to convergence in one autonomous run. On `pacer=workflow`, each round runs a deterministic static sweep first, then a code-review pass, a bug-audit (with its adversarial second pass), and a self-review parity pass in parallel on the same HEAD, deduplicates findings, applies every fix in one commit, and re-verifies; state lives in the workflow journal. On `pacer=portable`, the continuous driver in `_shared/pr-loop/portable-driver.md` runs the shared pr-converge phase machine with the same helpers and `check_convergence.py` ready definition. Once the internal passes are clean, Cursor Bugbot, Copilot, and Codex run as terminal confirmation gates, and the run marks the PR ready on convergence.
 
 ## Subdirectories
 
@@ -15,12 +15,13 @@ Drives one draft PR to convergence in a single autonomous workflow run. Each rou
 
 | File | Role |
 |---|---|
-| `SKILL.md` | Full entry-point protocol: pre-flight steps, worktree setup, `Workflow` call, budget-aware round boundaries, teardown, and the per-round convergence loop summary. |
+| `SKILL.md` | Full entry-point protocol: pacer selection, pre-flight steps, worktree setup, Workflow or portable path, budget-aware boundaries, teardown, and the convergence loop summary. |
 | `workflow/converge.mjs` | Main convergence workflow. Runs a static sweep then the internal lenses each round, applies fixes, runs Bugbot, Copilot, and Codex as terminal gates, checks convergence, and marks the PR ready. |
 | `workflow/aggregate_runs.py` | Merges every autoconverge journal for a PR into one deduped journal. |
 | `workflow/convergence_summary.py` | Builds the convergence-summary agent prompt over the merged findings. |
 | `workflow/render_report.py` | Builds the closing HTML report from the merged journal and summary. |
 | `reference/convergence.md` | Round shape: the static sweep, the three parallel internal lenses, deduplication, fix commit, the terminal Bugbot, Copilot, and Codex gates, and the ready definition. |
+| `reference/copilot-findings.md` | The Copilot gate tiering, per-finding verification, and the `userReview` return contract. |
 | `reference/stop-conditions.md` | Every way the run ends short of ready, including the budget stop. |
 | `reference/gotchas.md` | Hard-won failure lessons. |
 | `reference/closing-report.md` | The closing HTML report: data source, build steps, publishing. |
@@ -30,4 +31,6 @@ Drives one draft PR to convergence in a single autonomous workflow run. Each rou
 
 ## Entry point
 
-Requires the `Workflow` tool. The `SKILL.md` body specifies the exact pre-flight sequence and `Workflow` call.
+Selects `workflow` or `portable` via `select_converge_pacer.py`. Missing
+`Workflow` selects portable and continues — it does not abort. The `SKILL.md`
+body specifies the pre-flight sequence and each pacer's run path.