feat(scripts): YOLO transcript analyzer for permissions.allow seeding (#281)

* feat(scripts): YOLO transcript analyzer for permissions.allow seeding

Walks Claude Code JSONL session transcripts under
~/.claude-work/projects/ and ~/.claude/projects/, extracts paired-success
Bash invocations, classifies them by safety category (read-only,
search/inspect, build/test, file/cache, local-git mutation, MUTATING),
and emits a proposed permissions.allow array as both stdout summary
and machine-readable JSON at
~/.local/spellbook/state/proposed_allow_list.json.

The script never writes settings.json -- the orchestrator (or user) is
expected to review the proposal before piping it through
install_permissions.

Mutating commands (git push, gh pr merge, acli jira workitem
transition/edit) are recorded under rejected_mutating and never
promoted to the allowlist regardless of frequency.

Bash invocations are yielded only when paired with an explicit
non-error tool_result; unpaired tool_uses (interrupted sessions where
the user-side confirmation never landed) are dropped, since we cannot
confirm the command actually succeeded.

* fix(installer): handle null values in settings.json reads

A settings.json file containing the literal JSON value ``null`` (or any
non-object top-level value) used to crash the installer with
``TypeError: dict(None)`` when ``read_settings`` returned the parsed
``None`` and downstream callers tried to wrap it in a dict.

Fixes three null-propagation paths surfaced by Gemini code review:

- ``_settings_io.read_settings`` now returns ``{}`` for any non-dict
  top-level JSON value, treating it the same as a missing or empty
  file.
- ``install_permissions`` now uses ``... or {}`` / ``... or []``
  guards on ``existing_settings.get("permissions")`` and
  ``perms_section.get(bucket)`` so an explicit ``"permissions": null``
  or ``"allow": null`` in the user's settings.json no longer crashes
  the install path.
- ``uninstall_permissions`` carries the same guards on its own read of
  the permissions section.

* test(installer): migrate managed_permissions_state test to tripwire

The wiring tests in test_claude_code_wires_default_mode_and_permissions
used ``monkeypatch.setattr`` to redirect the
``managed_permissions_state._STATE_FILE_PATH`` constant to a tmp_path,
which violates the repo style rule that ``monkeypatch`` is reserved for
env vars, cwd, and sys.path.

To support tripwire-based mocking of the state-file path, introduce a
``_state_file_path()`` accessor on ``managed_permissions_state`` and
route every internal callsite through it. The accessor reads the
existing ``_STATE_FILE_PATH`` constant dynamically so the legacy
monkeypatch-based tests in test_install_default_mode.py continue to
work unchanged; new tests should mock the accessor instead.

The five wiring tests now register a tripwire mock for
``_state_file_path`` with an empirically probed call budget
(9 per install, 6 per uninstall) and assert the calls in the same
``in_any_order`` block as the existing mocks. If the SUT changes the
number of state-file accesses, the assertion will fail loudly and the
constants ``_STATE_PATH_CALLS_PER_INSTALL`` and
``_STATE_PATH_CALLS_PER_UNINSTALL`` must be updated together with the
new probed counts.

* test(installer): replace _FlakyReplace stub with tripwire sequential mock

The hooks atomic-write tests used a hand-rolled ``_FlakyReplace``
class to stub ``os.replace``: first call raises ``PermissionError``,
second call performs the real rename. Hand-rolled stubs are forbidden
by the repo style guide -- mocks must go through tripwire so the
verifier can assert every interaction.

Replace the stub with tripwire's sequential FIFO of side effects:
``mock_replace.__call__.raises(PermissionError(...)).calls(real_os_replace)``.
The retry contract is now expressed in the assertion order itself --
``assert_call(..., raised=AnyThing)`` followed by
``assert_call(..., returned=AnyThing)`` -- which is strictly more
verifiable than the previous ``flaky.count == 2`` check, since the
order of the raise-then-succeed sequence is now part of the assertion.

Also drops the import-time ``_REAL_OS_REPLACE`` capture; the real
``os.replace`` is captured inside the helper instead so the test file
has no module-global state.

* test(installer): cover read_settings non-dict JSON guard

Adds 12 tests for read_settings in installer/components/_settings_io.py:
absent file, empty file, whitespace-only file, valid object, malformed
JSON (raises), and the non-object top-level cases (null, empty array,
populated array, number, string, true, false) that the isinstance guard
collapses to {}.

Closes Momus BOT-A2 (review on axiomantic/spellbook PR review pass 2).

---------

Co-authored-by: elijahr <153711+elijahr@users.noreply.github.com>

Author: elijahr

.version

@@ -1 +1 @@
-0.60.0
+0.61.0

CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.61.0] - 2026-05-06
+
+### Added
+
+- **YOLO transcript analyzer** (`scripts/analyze_yolo_transcripts.py`).
+  Scans Claude Code session JSONLs under `~/.claude-work/projects/` and
+  `~/.claude/projects/` (both by default; `--config-dir PATH` repeatable
+  to override) for successful Bash invocations, buckets them by
+  `(first-token, sorted -flag tokens)`, and proposes a
+  `permissions.allow` array of gitignore-style patterns
+  (`Bash(git status:*)`, etc.) grouped into five safety categories:
+  read-only, search/inspect, build/test idempotent, local file/cache,
+  and local git mutation. Mutating commands (`git push`, `gh pr merge`,
+  `gh pr close`, `acli jira workitem transition`, `acli jira workitem
+  edit`) are explicitly rejected and surfaced in a separate
+  `rejected_mutating` section so reviewers can see what was filtered.
+  Output is written to `~/.local/spellbook/state/proposed_allow_list.json`
+  with deterministic key ordering, plus a human-readable summary on
+  stdout. The script never writes `settings.json` directly — the
+  proposal is intended for review before being fed into
+  `install_permissions(allow=...)` from Phase 0. Subagent transcripts
+  under `<session>/subagents/agent-*.jsonl` are walked alongside main
+  sessions; failed Bash invocations (paired `tool_result.is_error`) are
+  filtered out before bucketing.
+
 ## [0.60.0] - 2026-05-05
 
 ### Added

installer/components/_settings_io.py

@@ -15,10 +15,16 @@ def read_settings(settings_path: Path) -> dict:
 
     Raises ``json.JSONDecodeError`` on malformed JSON and ``OSError``
     on read failures; callers handle those to emit failed HookResults.
+
+    A file containing the literal JSON value ``null`` (or any non-object
+    top-level JSON like an array or scalar) is treated as "no settings"
+    and returned as an empty dict, since downstream callers assume a
+    mapping.
     """
     if not settings_path.exists():
         return {}
     text = settings_path.read_text(encoding="utf-8")
     if not text.strip():
         return {}
-    return json.loads(text)
+    obj = json.loads(text)
+    return obj if isinstance(obj, dict) else {}

installer/components/managed_permissions_state.py

@@ -37,10 +37,23 @@
 
 logger = logging.getLogger(__name__)
 
-# Resolved at import time. Tests monkeypatch this attribute to redirect to a
-# pytest tmp_path. See ``tests/installer/test_managed_permissions_state.py``.
+# Resolved at import time. Legacy tests monkeypatch this attribute to redirect
+# to a pytest tmp_path; new tests should mock ``_state_file_path`` via tripwire
+# instead. See ``tests/installer/test_managed_permissions_state.py``.
 _STATE_FILE_PATH: Path = Path.home() / ".local" / "spellbook" / "state" / "managed_permissions.json"
 
+
+def _state_file_path() -> Path:
+    """Return the on-disk path of the managed-permissions state file.
+
+    Internal callers use this indirection so tests can mock the path via
+    ``tripwire.mock("installer.components.managed_permissions_state:_state_file_path")``
+    instead of monkey-patching the module-level constant. Reads
+    ``_STATE_FILE_PATH`` dynamically so existing monkeypatch-based tests
+    continue to work without modification.
+    """
+    return _STATE_FILE_PATH
+
 _SCHEMA_VERSION = 1
 
 
@@ -59,7 +72,7 @@ def read_state() -> Dict:
     recovery path. Callers do not need to handle ``FileNotFoundError`` or
     ``json.JSONDecodeError`` themselves.
     """
-    path = _STATE_FILE_PATH
+    path = _state_file_path()
     if not path.exists():
         return _empty_schema()
     try:
@@ -149,7 +162,7 @@ def update_managed_set(
         new_entry["ask"] = desired["ask"]
         config_dirs[key] = new_entry
         state["version"] = _SCHEMA_VERSION
-        atomic_write_json(str(_STATE_FILE_PATH), state)
+        atomic_write_json(str(_state_file_path()), state)
 
     return diff
 
@@ -184,7 +197,7 @@ def set_managed_default_mode(config_dir: Path, mode: Optional[str]) -> None:
         else:
             per_dir["default_mode"] = mode
         state["version"] = _SCHEMA_VERSION
-        atomic_write_json(str(_STATE_FILE_PATH), state)
+        atomic_write_json(str(_state_file_path()), state)
 
 
 def reconcile(config_dir: Path) -> Dict[str, List[str]]:
@@ -211,4 +224,5 @@ def _state_lock_path() -> Path:
     Distinct suffix from ``atomic_write_json``'s internal ``.lock`` sibling so
     the two locks do not collide on the same name during a write.
     """
-    return _STATE_FILE_PATH.with_suffix(_STATE_FILE_PATH.suffix + ".coordlock")
+    state_path = _state_file_path()
+    return state_path.with_suffix(state_path.suffix + ".coordlock")

installer/components/permissions.py

@@ -102,16 +102,23 @@ def install_permissions(
             message=f"permissions: failed to read state file: {e}",
         )
 
-    perms_section: Dict[str, List[str]] = dict(existing_settings.get("permissions", {}))
+    # ``or {}`` guards against settings files that contain ``"permissions": null``
+    # (or any non-dict value) -- ``dict(None)`` raises TypeError. Treat those as
+    # "no permissions section" so a malformed-but-recoverable settings file does
+    # not crash the installer.
+    perms_section: Dict[str, List[str]] = dict(
+        existing_settings.get("permissions") or {}
+    )
 
     # Snapshot the pre-modification bucket contents BEFORE we mutate anything.
     # Used after the write to distinguish entries spellbook actually added
     # (absent before, present after) from entries the user had already added
     # by hand and that happened to overlap our desired set. Recording the
     # latter as "managed" would silently transfer ownership and let a future
     # uninstall delete the user's entry. See GEM-M3 / design §14.
+    # ``or []`` guards against bucket values that are explicitly ``null``.
     pre_existing: Dict[str, set] = {
-        bucket: set(perms_section.get(bucket, []))
+        bucket: set(perms_section.get(bucket) or [])
         for bucket in ("allow", "deny", "ask")
     }
 
@@ -125,7 +132,8 @@ def install_permissions(
         ("deny", desired_deny),
         ("ask", desired_ask),
     ):
-        current_list: List[str] = list(perms_section.get(bucket, []))
+        # ``or []`` guards against bucket values that are explicitly ``null``.
+        current_list: List[str] = list(perms_section.get(bucket) or [])
         prior_set = set(prior_managed.get(bucket, []))
         desired_set = set(desired)
         to_remove = prior_set - desired_set
@@ -335,11 +343,14 @@ def uninstall_permissions(
             message=f"permissions: failed to read {settings_path.name}: {e}",
         )
 
-    perms_section: Dict[str, List[str]] = dict(existing_settings.get("permissions", {}))
+    # ``or {}`` / ``or []`` guard against ``null`` values in settings.json.
+    perms_section: Dict[str, List[str]] = dict(
+        existing_settings.get("permissions") or {}
+    )
     removed_total = 0
     new_perms: Dict[str, List[str]] = {}
     for bucket in ("allow", "deny", "ask"):
-        current_list = list(perms_section.get(bucket, []))
+        current_list = list(perms_section.get(bucket) or [])
         managed_set = set(prior_managed.get(bucket, []))
         kept = [e for e in current_list if e not in managed_set]
         removed_total += len(current_list) - len(kept)