Define hosted memory governance contract between coven-github and coven-code

[romgenie]

Local source: coven-github/issues/09-define-hosted-memory-governance-contract.md

Summary

coven-github needs an explicit memory governance contract for invoking coven-code as a memory-backed familiar in hosted review mode. Memory is a product differentiator, but hosted memory also creates cross-repository and cross-tenant risk.

Current Evidence

• README.md positions familiars as having persistent identity, memory, composable skills, and operator-defined behavior.
• FAMILIAR-CONTRACT.md says a familiar can use organization/repo memory and prior task history when enabled.
• FAMILIAR-CONTRACT.md says hosted needs familiar memory boundaries that are opt-in, inspectable, and revocable.
• HOSTED.md says cloud familiar memory is optional and scoped by installation/repository policy.
• docs/security.md says cloud familiar memory should be opt-in for hosted customers and should remain scoped, inspectable, revocable, and redacted.
• Prior review of coven-code found several memory controls exist locally, but hosted tenant/install/repo boundaries must be explicit at the adapter boundary.

Problem

The GitHub adapter is the component that knows installation id, repository, actor, trigger, task kind, and customer policy. coven-code is the component that loads, uses, and writes memory. Without an explicit contract between them, hosted memory can accidentally become path-scoped, user-scoped, or globally familiar-scoped rather than tenant/repo/policy-scoped.

Impact

• A familiar could use memory from the wrong installation, repo, branch, or customer.
• Untrusted PR content could be written into durable memory.
• Maintainers may not know which memory influenced a review.
• Customers cannot inspect, revoke, or export memory use by installation/repo.
• The hosted product promise becomes a liability rather than a differentiator.

Proposed Design

Add a memory_policy block to the session brief or agent invocation metadata:

• enabled: boolean.
• tenant_scope: installation id and account id/login.
• repo_scope: repository id, owner/name, visibility, default branch.
• branch_scope: base/head/ref rules.
• trust_scope: trusted maintainer, collaborator, external contributor, fork PR, scheduled job.
• read_scopes: memories the agent may read.
• write_scopes: memories the agent may propose or write.
• approval_required: when learned facts require maintainer approval.
• retention_policy: expiration/deletion/redaction rules.

The agent result should include memory usage metadata:

• memory entries read;
• candidate memories proposed;
• rejected memories and reason;
• approval status.

Acceptance Criteria

• Every hosted coven-code invocation includes explicit memory policy metadata.
• Hosted mode refuses memory reads/writes when tenant/repo scope is missing.
• Untrusted PR/fork content cannot directly write durable memory.
• Reviews can cite which memory entries influenced output.
• Customers can inspect and revoke memory by installation and repository.
• Tests cover cross-installation, cross-repo, fork PR, and memory-disabled modes.

Test Notes

Use fake coven-code invocations to assert the adapter passes memory policy fields. Add contract tests that reject result envelopes containing memory writes outside the allowed scope.