docs(proposals): VEP-0005 — richer scopes on Claim/Source (draft)

[dripsmvcp]

Summary

• Adds VEP-0005 (draft) proposing structured (visibility, project, agent) scopes on Claim/Source, replacing the single scope enum, with out-of-scope artifacts filtered from retrieval (feat: richer scopes on Claim/Source — (visibility, project, agent) [VEP] #100 is tagged [VEP]).
• Design record only — no code. Implementation lands in separate PRs after acceptance.

Why a VEP and not a code PR

proposals/README.md requires a VEP for changes to the object model and to config.yaml semantics — both of which this touches. So this opens the design for review before any code, same as VEP-0004.

What the VEP proposes

• Rename the flat Scope enum → Visibility (values unchanged); add ArtifactScope(visibility, project, agent); Claim.scope/Source.scope become that object.
• Retrieval filtering by a viewer context (project, agent) from request param > VOUCH_PROJECT/VOUCH_AGENT env > config.yaml, with an explicit visibility match table. Default viewer reproduces today's single-agent behavior.
• Backward compatible: a mode="before" validator coerces the old bare scope: project string into {visibility: project}, so existing .vouch/ reads with no migration.
• Security honesty: scope is a retrieval/relevance filter, not an access-control or confidentiality boundary — .vouch/ is plaintext; private means "hidden from other agents' default context," not "secret." Calls out fail-closed behavior for private.

Open questions for reviewers (in the VEP)

team vs project-unbound semantics; filter location (post-pass vs SQL WHERE); viewer-context precedence; whether Entity/Relation/Page also need scope (deferred); how sync (#90/#91) interacts with scope.

Note on numbering

This is 0005; 0004 is reserved by my in-flight HTTP-transport PR (#94), so the index here skips 0004 intentionally. If the README index conflicts when both merge, I'll rebase per the numbering rule.

Test Plan

• N/A — documentation only
• Adds proposals/VEP-0005-richer-scopes.md (status draft) + index row

Refs #100 (implementation in separate PRs once/if accepted)

[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: 7f7cac36-4cc5-4336-ac88-c3a445cbfbbb

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]

I wanna you prove vouch compatible with claude code and codex in next PR