feat(audit): visibility-aware kb.audit queries

[claytonlin1110]

What changed

kb.audit / vouch audit now accept optional viewer context (project, agent, or nested viewer_scope on JSONL). audit.read_events() can filter events whose object_ids reference scoped claims, sources, or claim proposals outside that context; events with no object_ids are always included. Filtering is wired through MCP, JSONL, CLI, and the web audit timeline. Capabilities advertises kb.audit under scoped methods; spec and CHANGELOG updated.

Why

gbrain-style multi-project KBs need audit timelines that respect the same visibility model as retrieval — a reviewer in project A should not see project B's audit events. Issue #232. This builds on VEP-0005 (ArtifactScope / ViewerContext) by enforcing scope on the audit read path instead of leaving filtering to callers.

What might break

Breaking (API): kb.audit no longer returns a bare [AuditEvent] array. It now returns { "viewer": { "project", "agent" }, "events": [...] } on MCP and JSONL. CLI --json output matches that envelope.

Non-breaking (on-disk): No changes to .vouch/ layout, audit log format, or proposal/claim files. Existing audit.log.jsonl entries are untouched. Callers that use audit.read_events(kb_dir) without viewer/store (metrics, stats, provenance) still see the full log.

VEP

Extends VEP-0005 (richer scopes / retrieval filtering). No new on-disk schema; audit read filtering only. Tracked in #232.

Tests

• make check passes locally (lint + mypy + pytest) — note: one pre-existing failure in test_import_apply_rejects_absolute_path unrelated to this branch
• New / changed behaviour has a test (tests/test_audit_scoping.py, updates to test_audit.py, test_scoping.py)
• CHANGELOG.md updated under ## [Unreleased]

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 25e2e9a8-6e87-4da8-b33e-8f99927c62ae

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[plind-junior]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0cf2514f2d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claytonlin1110]

@codex review

[chatgpt-codex-connector]

To use Codex here, create a Codex account and connect to github.

[claytonlin1110]

@plind-junior please review