feat(audit): structured JSONL audit log for mutating verbs (Phase G)

Every mutating action now appends a JSONL record to
`<content_dir>.parent/audit.log` (defaults to
`~/.config/claude-config/audit.log`). Each line is a self-contained
JSON object with `ts` (RFC3339 UTC), `event`, `content_dir`,
`target`, and per-event fields.

Events emitted:

- `install`: {links_created, dir_links_created, already_correct,
  real_files_backed_up, global_writes}
- `uninstall`: {removed, backups_restored}
- `track`: {path, kind}
- `decisions_apply`: {pack, force, written, overwritten, skipped}

Dry-run calls do NOT write to the audit log (the log is for actual
mutations only). The writer is best-effort: OSError on the log path
never blocks the operation that triggered it.

`ClaudeConfig.audit_log_path` is a public property so users can
script over it (jq, grep, log-shipping).

Four tests:
- install writes one event
- install --dry-run writes nothing
- decisions_apply writes an event with pack name
- audit_log_path lives next to content_dir

Full suite: 252 passing. Closes SPEC §4 Phase G.

Author: imanimanyara

src/ai_config_kit/manager.py

@@ -1119,6 +1119,45 @@ def __repr__(self) -> str:
             f"include_history={self._include_history})"
         )
 
+    # ---- audit log (Phase G) -------------------------------------------
+
+    @property
+    def audit_log_path(self) -> Path:
+        """Append-only JSONL audit log for mutating verbs.
+
+        Lives next to ``content_dir`` so it's outside the symlinked tree
+        but still on the same filesystem (the default content_dir lives
+        at ``~/.config/claude-config/content/``, so the log goes to
+        ``~/.config/claude-config/audit.log``).
+        """
+        return self._content_dir.parent / "audit.log"
+
+    def _audit(self, event: str, **fields: Any) -> None:
+        """Append a single JSONL event. Best-effort: never raises.
+
+        Each line is a self-contained JSON object with at minimum
+        ``ts`` (RFC3339 UTC), ``event``, ``content_dir``, ``target``,
+        and the caller's keyword fields. Designed so ``jq`` /
+        ``grep`` over the file is straightforward.
+        """
+        from datetime import datetime, timezone
+
+        record: dict[str, Any] = {
+            "ts": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "event": event,
+            "content_dir": str(self._content_dir),
+            "target": str(self._target_base),
+            **fields,
+        }
+        path = self.audit_log_path
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            with path.open("a", encoding="utf-8") as fh:
+                fh.write(json.dumps(record, ensure_ascii=False, sort_keys=True) + "\n")
+        except OSError:
+            # Audit must never block the operation it's recording.
+            return
+
     @classmethod
     def from_config(cls, config_path: Path | str | None = None) -> ClaudeConfig:
         """Load config from JSON. Falls back to defaults when file is absent.
@@ -1543,7 +1582,7 @@ def install(self, dry_run: bool = False) -> InstallReport:
                 continue  # missing canonical: surfaced via project_install
             global_writes.append((vendor, str(dest)))
 
-        return InstallReport(
+        report = InstallReport(
             links_created=links,
             dir_links_created=dirs,
             already_correct=correct,
@@ -1553,6 +1592,16 @@ def install(self, dry_run: bool = False) -> InstallReport:
             secrets_skipped=secrets,
             global_writes=global_writes,
         )
+        if not dry_run:
+            self._audit(
+                "install",
+                links_created=report.links_created,
+                dir_links_created=report.dir_links_created,
+                already_correct=report.already_correct,
+                real_files_backed_up=report.real_files_backed_up,
+                global_writes=len(report.global_writes),
+            )
+        return report
 
     def _adapter_for(self, vendor: str) -> VendorAdapter | None:
         """Resolve a vendor name to its adapter.
@@ -1841,6 +1890,11 @@ def uninstall(self, restore_backups: bool = True) -> UninstallReport:
                 if backup.exists() and not link.exists():
                     backup.rename(link)
                     restored += 1
+        self._audit(
+            "uninstall",
+            removed=removed,
+            backups_restored=restored,
+        )
         return UninstallReport(removed=removed, backups_restored=restored)
 
     # ---- track --------------------------------------------------------
@@ -1889,6 +1943,11 @@ def track(self, path: Path | str) -> ClaudeConfig:
         if state_changed and self._loaded_config_path is not None:
             self.save_config(self._loaded_config_path)
 
+        self._audit(
+            "track",
+            path=str(rel),
+            kind="dir" if dest.is_dir() else "file",
+        )
         return self
 
     # ---- cleanup ------------------------------------------------------
@@ -2859,13 +2918,23 @@ def decisions_apply(
             else:
                 written.append(f.dest)
 
-        return DecisionsApplyReport(
+        report = DecisionsApplyReport(
             pack=name,
             written=written,
             skipped=skipped,
             overwritten=overwritten,
             dry_run=dry_run,
         )
+        if not dry_run:
+            self._audit(
+                "decisions_apply",
+                pack=name,
+                force=force,
+                written=len(written),
+                overwritten=len(overwritten),
+                skipped=len(skipped),
+            )
+        return report
 
     def _build_pack(self, data: dict[str, Any], pack_dir: Any) -> DecisionPack:
         files = [

tests/test_manager.py

@@ -934,6 +934,44 @@ def test_decisions_diff_unknown_pack_raises(cfg: ClaudeConfig) -> None:
         cfg.decisions_diff("does-not-exist")
 
 
+# --- audit log (Phase G) --------------------------------------------------
+
+
+def test_audit_log_records_install(cfg: ClaudeConfig) -> None:
+    """install() with dry_run=False writes one JSONL entry."""
+    cfg.install(dry_run=False)
+    log = cfg.audit_log_path
+    assert log.is_file()
+    lines = [json.loads(line) for line in log.read_text(encoding="utf-8").splitlines() if line]
+    install_events = [r for r in lines if r["event"] == "install"]
+    assert install_events
+    e = install_events[-1]
+    assert "ts" in e and e["ts"].endswith("Z")
+    assert e["content_dir"] == str(cfg._content_dir)
+
+
+def test_audit_log_skips_install_dry_run(cfg: ClaudeConfig) -> None:
+    """Dry-run install does not emit an audit event."""
+    cfg.install(dry_run=True)
+    log = cfg.audit_log_path
+    if log.is_file():
+        lines = [json.loads(line) for line in log.read_text(encoding="utf-8").splitlines() if line]
+        assert not [r for r in lines if r["event"] == "install"]
+
+
+def test_audit_log_records_decisions_apply(cfg: ClaudeConfig) -> None:
+    """decisions_apply() with dry_run=False writes an event including pack name."""
+    cfg.decisions_apply("script-generation-pattern")
+    log = cfg.audit_log_path
+    lines = [json.loads(line) for line in log.read_text(encoding="utf-8").splitlines() if line]
+    events = [r for r in lines if r["event"] == "decisions_apply"]
+    assert events and events[-1]["pack"] == "script-generation-pattern"
+
+
+def test_audit_log_path_lives_next_to_content_dir(cfg: ClaudeConfig) -> None:
+    assert cfg.audit_log_path == cfg._content_dir.parent / "audit.log"
+
+
 def test_decisions_apply_dry_run_writes_nothing(cfg: ClaudeConfig) -> None:
     r = cfg.decisions_apply("script-generation-pattern", dry_run=True)
     assert r.dry_run