[CLI] weaver-kernel audit — inspect, filter, and verify action traces from the terminal

[dgenio]

Summary

Add an audit subcommand to the package CLI that reads a persisted trace store and lets operators answer audit questions from the terminal: list and filter traces (by principal, capability, decision, time window), show one action in full (explain), tail a live log, export a filtered set, and verify log integrity.

Why this matters

The audit trail is the product's payoff, but today the only way to read it is Python code in the same process. The moment traces persist (pluggable stores) and chain (verifiable log), the obvious next question is "how do I look at this?" — and the answer should be one command. This is also the natural companion to the planned doctor command (#124): doctor checks the setup, audit operates the result.

Proposed scope

• weaver-kernel audit list — table view with filters: --principal, --capability, --decision allow|deny|ask, --since/--until, --limit.
• weaver-kernel audit show <action_id> — full redaction-safe trace detail (the CLI face of kernel.explain()).
• weaver-kernel audit verify — run chain verification and report OK or first divergent record (composes with the hash-chain issue).
• weaver-kernel audit export --format jsonl — filtered export for downstream analysis (aligned with the export-shape work in Interop: export action traces for downstream lesson extraction #94, not competing with it).
• --json on every subcommand for scripting; human output via plain stdlib formatting (no new runtime dependency; rich only if already justified by cli: add doctor for examples, environment, secret configuration, and test vectors #124's CLI work).
• Docs page (docs/cli.md shared with cli: add doctor for examples, environment, secret configuration, and test vectors #124) + entry point in pyproject.toml [project.scripts] if cli: add doctor for examples, environment, secret configuration, and test vectors #124 hasn't added it yet.

Implementation notes

• Coordinate with cli: add doctor for examples, environment, secret configuration, and test vectors #124 (doctor): one console entry point (weaver-kernel) with subcommands; whichever lands first creates the CLI skeleton (argparse is sufficient — stdlib-only keeps the minimal-deps rule intact).
• Depends on persistent trace stores for real value; against an in-memory store the command should fail with a clear typed error pointing at the persistence docs.
• Output must remain redaction-safe by construction — the CLI renders only what ActionTrace already contains; no flag may surface raw driver output.
• Tests: CLI invocations as subprocess or via the argparse entry function, against a SQLite/JSONL fixture store; verify command tested against a deliberately tampered fixture.

Acceptance criteria

• list, show, verify, and export work against a persisted trace store with documented filters.
• Every subcommand supports --json; human output readable without third-party deps.
• verify detects a tampered fixture and exits non-zero with the divergent record id.
• Clear typed error when no persistent store is configured.
• docs/cli.md covers all subcommands; CHANGELOG updated.

Out of scope

• A web/TUI dashboard (the CLI is the foundation; a dashboard could follow).
• Trace analytics/aggregation beyond filters and counts.
• The export schema definition itself (Interop: export action traces for downstream lesson extraction #94 owns the contract; the CLI emits it).

References

• In-repo: cli: add doctor for examples, environment, secret configuration, and test vectors #124 (CLI doctor — shared skeleton), Interop: export action traces for downstream lesson extraction #94 (export shape), kernel/__init__.py explain(), trace.py.
• Ecosystem pattern: kubectl get events / gh run list-style operator ergonomics as neutral precedent.

---

Priority: P2 · Effort: M · Impact: High

[dgenio]

Closing as completed — this is implemented and merged.

The weaver-kernel audit operator CLI shipped in v0.11.0 via PR #148 (commit e593456, on main at e78a863).

Evidence against the acceptance criteria:

• src/weaver_kernel/cli/_audit.py implements audit list | show | verify | export with the documented filters (--principal, --capability, --decision, --since, --until, --limit).
• --json on every subcommand; human output via stdlib formatting (no new runtime dependency).
• verify runs chain verification and reports OK or the first divergent record, exiting non-zero on a tampered store.
• Reads a persisted trace store (SQLite/JSONL) and raises a clear typed error against a non-persistent/in-memory store; export emits JSONL aligned with the Interop: export action traces for downstream lesson extraction #94 export shape.
• Registered under the weaver-kernel console entry point (pyproject.toml [project.scripts]), documented in docs/cli.md, covered by tests/test_cli_audit.py. CHANGELOG [0.11.0] records it ([CLI] weaver-kernel audit — inspect, filter, and verify action traces from the terminal #147).

The out-of-scope items (web/TUI dashboard, analytics beyond filters/counts) remain available as follow-ups.

---

Generated by Claude Code