docs: add contextweaver + repository-check integration cookbook (#92, #93)#101
Merged
Conversation
…93) Add an ecosystem integration cookbook under docs/integrations/ with two reference flows and runnable, offline companions. #92 — contextweaver "policy before action": documents that context routing is advisory and policy enforcement still happens before execution. New docs/integrations/contextweaver.md and examples/contextweaver_policy_flow.py demonstrate the allow / ask-confirm / deny outcomes. Because PolicyDecision is binary, the ask outcome is derived from the recoverable insufficient_justification denial code, while missing_role is terminal. The shortlist deliberately includes a capability the principal cannot use, proving that routing is not permission. #93 — repository safety check as a policy-controlled capability: a RepositoryCheckDriver shells out to a local checker (swappable for VibeGuard) behind a READ repo.code_safety_check capability; the high-impact WRITE repo.publish_artifact action is gated behind a passing check, and both steps are recorded in the audit trace. New docs/integrations/repository_safety_check.md and examples/repository_safety_check.py. Both examples are wired into the Makefile `example` target so they run under `make ci`; docs/integrations.md and the README link the new pages; CHANGELOG updated. No new dependencies (the shell-out uses sys.executable).
There was a problem hiding this comment.
Pull request overview
Adds an "ecosystem integration cookbook" under docs/integrations/ consisting of two reference flows (contextweaver policy-before-action, and a repository-safety-check capability) plus runnable, offline example scripts wired into make ci. No src/ changes — purely additive documentation and examples implementing issues #92 and #93.
Changes:
- New docs
contextweaver.mdandrepository_safety_check.mddescribing the patterns, linked fromREADME.mdanddocs/integrations.md. - New examples
contextweaver_policy_flow.py(allow/ask/deny on top of the binaryPolicyDecisionviaDenialReasoncodes) andrepository_safety_check.py(aRepositoryCheckDrivershelling out to a tiny embedded scanner, gating aWRITEpublish behind aREADcheck). Makefileruns both examples in theexampletarget;CHANGELOG.mdgets an[Unreleased]entry.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Adds nested links to the two new integration docs. |
| Makefile | Runs the two new examples in make example/make ci. |
| CHANGELOG.md | Documents the additions under [Unreleased]. |
| docs/integrations.md | New "Ecosystem integration patterns" section pointing at the two docs and examples. |
| docs/integrations/contextweaver.md | Reference flow for advisory routing + binding policy enforcement. |
| docs/integrations/repository_safety_check.md | Capability pattern for gating high-impact actions behind a deterministic check. |
| examples/contextweaver_policy_flow.py | Demonstrates allow / ask-confirm / deny outcomes using real kernel APIs. |
| examples/repository_safety_check.py | Implements RepositoryCheckDriver and a check-then-publish gate with audit. |
Addresses findings from an audit-grade re-review of this PR. F1 (#93 acceptance — "audit trail records the check result"): Successful invocations now record `ActionTrace.result_summary`, a redaction-safe dict of counts/flags (`fact_count`, `row_count`, `warning_count`, `has_handle`) derived only from the post-Firewall Frame — never raw driver data — so the I-01 boundary is preserved and no scanned content reaches the audit log. The repository safety check's pass/block decision is now recorded in the trail (`result_summary["row_count"] == 0` ⇒ passed) rather than merely inferred from whether a later publish occurred. Failed runs keep `result_summary == None`. Wired through both the invoke and stream trace paths; example asserts the decision is reconstructable from the trace; architecture.md and security.md updated. F2: narrow the contextweaver.md "ask/confirm" outcome wording — role checks run before the justification check, so a DESTRUCTIVE action for an unauthorized principal surfaces as terminal `missing_role`, never the recoverable `ask`. Documented the ordering explicitly. F3: drop the redundant `AGENT_KERNEL_SECRET` env setdefault from both examples (the secret is passed to HMACTokenProvider explicitly). make ci: fmt-check, lint, mypy strict (41 files), 568 passed / 1 skipped, both examples run clean. https://claude.ai/code/session_01E3HbAruNmmMLKwiifTy3kp
This was referenced May 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
Adds an ecosystem integration cookbook under
docs/integrations/with two reference flows, each with a runnable, offline companion. Implements issues #92 and #93 in a single PR.#92 — contextweaver "policy before action"
docs/integrations/contextweaver.md(new) — reference flow stating that context routing is advisory and policy enforcement still happens before execution.examples/contextweaver_policy_flow.py(new) — demonstrates allow / ask-confirm / deny.PolicyDecisionis binary, so theaskoutcome is derived from the recoverableinsufficient_justificationdenial code (host confirms + supplies a justification, then re-grants);missing_roleis terminal. The synthetic tool-card shortlist deliberately includes aDESTRUCTIVEcapability the principal cannot use, proving routing ≠ permission.#93 — repository safety check as a policy-controlled capability
docs/integrations/repository_safety_check.md(new) — the capability pattern end to end.examples/repository_safety_check.py(new) — aRepositoryCheckDriverthat shells out to a local checker (swappable forvibeguard) behind aREADrepo.code_safety_check; the high-impactWRITErepo.publish_artifactis gated behind a passing check; blocking findings stop the publish; both steps are recorded in the audit trace and read back viaKernel.explain().Wiring
Makefile— both examples added to theexampletarget so they run undermake ci.docs/integrations.md+README.md— link the two new pages.CHANGELOG.md—[Unreleased]entry.Why
#92 and #93 are both pure additive docs/example work demonstrating the same invariant — an action must clear policy/capability enforcement before it executes — and share the same files-shape and audit-trace surface, so they were grouped per the triage recommendation. Modeling
ask/confirmon top of the binary policy via theinsufficient_justificationcode keeps the example honest about real kernel behavior rather than inventing a verdict the engine does not have.How verified
All run locally:
make fmt-check— 71 files already formattedmake lint— All checks passedmake type— mypy strict: no issues in 41 source filesmake test— 566 passed, 1 skippedmake example— both new examples run clean (allow/ask/deny and pass/block paths print as expected); strongasserts in each example fail loudly on regression (e.g. shortlist-includes-destructive,insufficient_justificationthen success,missing_roleterminal, findings present ⇒ publish skipped)Scope notes (Mode B)
RepositoryCheckDriverlives in the example, not insrc/.sys.executablerunning a tiny embedded scanner.Risks / caveats
dgenio/contextweaver#320,dgenio/weaver-spec#61,dgenio/vibeguard) that could not be inspected here; exact upstream API/field names should be confirmed before anyone wires these to real services.make ci; mypy only coverssrc/, matching the repo's existing example convention.https://claude.ai/code/session_0132D4ChZq738mNiNTvNsfUP
Generated by Claude Code