claude-dev-env 2.0.1 → 2.1.0

package/scripts/test_claude_chain_runner.py

@@ -1,6 +1,7 @@
 """Behavioral tests for the claude fallback-chain runner."""
 
 import json
+import os
 import subprocess
 import sys
 from pathlib import Path
@@ -78,20 +79,32 @@ class _Recorder:
         self.behavior_by_command = behavior_by_command
         self.invocations = []
         self.timeouts = []
+        self.all_keyword_arguments = []
 
     def __call__(self, invocation, **keyword_arguments):
         self.invocations.append(invocation)
         self.timeouts.append(keyword_arguments.get("timeout"))
+        self.all_keyword_arguments.append(keyword_arguments)
         behavior = self.behavior_by_command[invocation[0]]
         if isinstance(behavior, BaseException):
             raise behavior
         return behavior
 
 
+class _TtyStdin:
+    def isatty(self) -> bool:
+        return True
+
+
+def _install_tty_stdin(monkeypatch):
+    monkeypatch.setattr(runner.sys, "stdin", _TtyStdin())
+
+
 def _install(monkeypatch, config_file, behavior_by_command):
     recorder = _Recorder(behavior_by_command)
     monkeypatch.setattr(runner, "chain_config_path", lambda: config_file)
     monkeypatch.setattr(runner, "chain_subprocess_runner", recorder)
+    _install_tty_stdin(monkeypatch)
     return recorder
 
 
@@ -276,6 +289,45 @@ def test_extra_args_are_appended_to_invocation(
     assert recorder.invocations[0] == ["claude", "-p", "hello", "--account", "ev"]
 
 
+def test_run_claude_forwards_stdin_text_to_subprocess(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude")])
+    recorder = _install(monkeypatch, config_file, {"claude": _completed("claude", 0)})
+    runner.run_claude(
+        _PROMPT_ARGUMENTS, timeout_seconds=5, stdin_text="charter body"
+    )
+    assert recorder.all_keyword_arguments[0]["input"] == "charter body"
+
+
+def test_run_claude_passes_none_input_when_stdin_text_omitted(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude")])
+    recorder = _install(monkeypatch, config_file, {"claude": _completed("claude", 0)})
+    runner.run_claude(_PROMPT_ARGUMENTS, timeout_seconds=5)
+    assert recorder.all_keyword_arguments[0].get("input") is None
+
+
+def test_cli_forwards_piped_stdin_to_invocation(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry("claude")])
+    recorder = _install(monkeypatch, config_file, {"claude": _completed("claude", 0)})
+
+    class _PipedStdin:
+        def isatty(self) -> bool:
+            return False
+
+        def read(self) -> str:
+            return "charter body"
+
+    monkeypatch.setattr(runner.sys, "stdin", _PipedStdin())
+    exit_code = runner.main([CLI_ARGUMENTS_SEPARATOR, "-p", "hi"])
+    assert exit_code == 0
+    assert recorder.all_keyword_arguments[0]["input"] == "charter body"
+
+
 def test_signature_matching_is_case_insensitive(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:
@@ -362,6 +414,7 @@ def test_cli_missing_config_exits_config_error(
 ) -> None:
     missing_config = tmp_path / CONFIG_FILENAME
     monkeypatch.setattr(runner, "chain_config_path", lambda: missing_config)
+    _install_tty_stdin(monkeypatch)
     exit_code = runner.main([CLI_ARGUMENTS_SEPARATOR, "-p", "hi"])
     captured = capsys.readouterr()
     assert exit_code == CHAIN_CONFIG_ERROR_EXIT_CODE
@@ -470,3 +523,62 @@ def test_chain_config_path_points_at_home_config() -> None:
     config_path = runner.chain_config_path()
     assert config_path.name == CONFIG_FILENAME
     assert CLAUDE_HOME_SUBDIRECTORY in config_path.parts
+
+
+def test_real_subprocess_capture_replaces_undecodable_bytes(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry(sys.executable)])
+    monkeypatch.setattr(runner, "chain_config_path", lambda: config_file)
+    child_code = 'import sys; sys.stdout.buffer.write(b"ok \\x90 end")'
+    chain_result = runner.run_claude(["-c", child_code], timeout_seconds=60)
+    assert chain_result.served_command == sys.executable
+    assert chain_result.returncode == 0
+    assert chain_result.stdout == "ok � end"
+
+
+def test_real_subprocess_capture_preserves_utf8_text(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    config_file = _write_chain_config(tmp_path, [_entry(sys.executable)])
+    monkeypatch.setattr(runner, "chain_config_path", lambda: config_file)
+    child_code = 'import sys; sys.stdout.buffer.write("report ✅ done".encode("utf-8"))'
+    chain_result = runner.run_claude(["-c", child_code], timeout_seconds=60)
+    assert chain_result.served_command == sys.executable
+    assert chain_result.returncode == 0
+    assert chain_result.stdout == "report ✅ done"
+
+
+def test_cli_emits_utf8_when_console_encoding_is_legacy(tmp_path: Path) -> None:
+    tmp_home = tmp_path / "home"
+    claude_directory = tmp_home / CLAUDE_HOME_SUBDIRECTORY
+    claude_directory.mkdir(parents=True)
+    config_file = claude_directory / CONFIG_FILENAME
+    config_file.write_text(
+        json.dumps({CONFIG_CHAIN_KEY: [_entry(sys.executable)]}),
+        encoding=UTF8_ENCODING,
+    )
+    runner_script = _SCRIPTS_DIR / "claude_chain_runner.py"
+    child_code = 'import sys; sys.stdout.buffer.write("report ✅".encode("utf-8"))'
+    legacy_console_encoding = "cp1252"
+    child_environment = dict(os.environ)
+    child_environment["USERPROFILE"] = str(tmp_home)
+    child_environment["HOME"] = str(tmp_home)
+    child_environment["PYTHONIOENCODING"] = legacy_console_encoding
+    child_environment.pop("PYTHONUTF8", None)
+    runner_command = [
+        sys.executable,
+        str(runner_script),
+        CLI_ARGUMENTS_SEPARATOR,
+        "-c",
+        child_code,
+    ]
+    completed = subprocess.run(
+        runner_command,
+        capture_output=True,
+        env=child_environment,
+        timeout=60,
+    )
+    assert completed.returncode == 0
+    assert b"Traceback" not in completed.stderr
+    assert "report ✅" in completed.stdout.decode(UTF8_ENCODING)

package/scripts/test_grok_headless_runner.py

@@ -418,7 +418,6 @@ def test_tightened_auth_phrases_still_classify_auth_failure(
         assert outcome.classification == CLASSIFICATION_AUTH_FAILURE, each_stderr
 
 
-def test_dual_match_prefers_auth_failure_over_usage_limit(
 def test_missing_binary_returns_dedicated_error(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:

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 (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)
+---
+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

@@ -21,6 +21,7 @@ Drives one draft PR to convergence in a single autonomous workflow run. Each rou
 | `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. |