integration: model repository safety checks as a policy-controlled capability

[dgenio]

Context

agent-kernel already focuses on policy enforcement, capability modelling, authorization, firewall redaction, and auditable tool calls. VibeGuard fits naturally as an example of a repository-level check that can be invoked only under explicit policy.

Problem

Agents that can write files, open PRs, or publish artifacts need a clear pattern for running deterministic checks before high-impact actions.

The repository can document this as a capability pattern without depending on any specific checker.

Scope

Add a cookbook or example showing:

• a repository_check or code_safety_check capability;
• policy rules controlling when the capability is required;
• an example adapter that shells out to a local command such as VibeGuard;
• audit events capturing command, scope, result, and decision;
• behavior when the check returns a blocking result.

Non-goals

• Do not add VibeGuard as a required dependency.
• Do not make agent-kernel responsible for implementing scanning logic.
• Do not bypass existing policy enforcement.

Acceptance criteria

• Example/cookbook shows the capability pattern end to end.
• The safety check is invoked through policy-controlled capability execution.
• Audit trail records the check result.
• README or docs index links to the example.

Related ecosystem

• VibeGuard: dgenio/vibeguard
• Weaver spec: dgenio/weaver-spec

[dgenio]

Closing as completed — implemented and merged via PR #101 (cookbook commit e23e324, plus follow-up 72fd494 that closed the audit-trail acceptance gap).

The merged work satisfies every acceptance criterion:

• Capability pattern end to end — docs/integrations/repository_safety_check.md + examples/repository_safety_check.py show a READ repo.code_safety_check backed by a RepositoryCheckDriver that shells out to a local checker, gating the high-impact WRITE repo.publish_artifact.
• Invoked through policy-controlled capability execution — the check runs via Kernel.invoke(); a blocking result stops the publish (the host does not grant the WRITE capability).
• Audit trail records the check result — follow-up 72fd494 added a redaction-safe ActionTrace.result_summary (counts/flags derived only from the post-Firewall Frame, never raw findings), so the pass/block decision is recorded in the trace itself and reconstructable via Kernel.explain(action_id) — not merely inferred from whether a later publish happened.
• No required dependency on any checker — the example uses a tiny embedded scanner and documents swapping in vibeguard; the shell-out uses sys.executable, adding no new dependencies. Non-goals (no scanning logic in agent-kernel, no policy bypass) are honored.
• Docs index links the example — README.md and docs/integrations.md both link the new page and companion example, which is wired into make ci via the Makefile example target.

If the delivered audit shape doesn't meet your needs, feel free to reopen.

---

Generated by Claude Code