Give every agent patch a review receipt

[onatozmenn]

What this changes

Adds deed review --before ... --after ... and the deed_review MCP tool. A receipt reports added authority, weaker obligation tiers, and newly Guarded obligations by stable module/declaration identity. Three independent policy gates can turn those findings into CI failures.

Why this way

The receipt is computed once in deed-driver; CLI and MCP only load inputs and render that shared answer. Authority comparison uses structured exported effect rows for functions and handlers. Obligation matching is order-independent so moving two calls cannot invent a regression. MCP accepts explicit source arrays, preserving its no-filesystem capability boundary.

What it still does not do

This does not discover files for MCP, compare arbitrary signature text, or enforce policy unless a deny flag/rule is selected.

Checks

• cargo fmt --check
• cargo clippy --workspace --all-targets -- -D warnings
• cargo nextest run --workspace --profile ci --no-fail-fast (2520 passed)
• cargo test --doc --workspace
• deed check examples/ (0 errors, 3 intentional warnings) and deed test examples/ (138 passed)
• Real MCP Python client drove all 7 tools
• Focused obligation matcher mutations: 4 caught, 0 missed
• Every mutation missed by the first CI run was reproduced and break-verified: ownership (2 tests), one-side refusal (3 tests), diagnostic category aggregation (4 tests), parser equals form and error classification
• Exported handler authority was reproduced as a clean false negative, then covered in the shared snapshot and test suite
• Agent-surface decision and public guide updated
• Tests cover function and handler authority widening/narrowing, tier regressions, new Guarded evidence, reorder stability, malformed/refused MCP input, JSON, policies, imports and shipped modules

AI-assisted implementation; reviewed and validated locally.

[Copilot]

Pull request overview

Adds a shared “review receipt” facility to Deed, enabling agents/CI to compare two checked module sets and surface evidence changes (new authority, weaker obligation tiers, and newly Guarded obligations) with optional policy gates. The implementation lives in deed-driver and is surfaced consistently via the CLI (deed review) and MCP (deed_review), with documentation and tests ensuring agreement and stable output.

Changes:

• Introduces deed_driver::review (receipt + policy evaluation) and comprehensive unit tests for authority/tier/guarded matching behavior.
• Adds deed review --before ... --after ... to the CLI with human/JSON output and three independent deny gates.
• Adds MCP tool deed_review (before/after source arrays + optional policy), updates the agent guide, smoke tests, and MCP/driver agreement tests.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
README.md	Documents deed review receipts, JSON output, and deny gates; mentions MCP deed_review.
how-to/let-an-agent-use-the-compiler.md	Adds deed_review to the tool list and describes calling it with module arrays + policy.
design/decisions/2026-07-31-agent-surface.md	Updates the agent surface decision to include deed_review and clarifies module-set review semantics.
crates/deed-mcp/tests/session.rs	Extends MCP session tests for tool schemas, tool list, guide parity, and deed_review behaviors.
crates/deed-mcp/tests/agreement.rs	Adds an agreement test ensuring MCP review output matches deed-driver’s receipt+policy JSON.
crates/deed-mcp/src/tools.rs	Implements the deed_review MCP tool, argument schemas, input validation, and refusal vs receipt behavior.
crates/deed-mcp/src/lib.rs	Updates MCP crate docs and handshake instructions to include review expectations.
crates/deed-mcp/smoke.py	Updates the Python smoke client to validate new schema shape and exercise deed_review.
crates/deed-mcp/Cargo.toml	Updates the crate description to reflect broader “evidence out” boundary.
crates/deed-driver/tests/review.rs	Adds driver-level tests for receipts, policy mapping, and stability under reordering.
crates/deed-driver/src/review.rs	Adds receipt computation logic: authority additions, tier regressions, and new guarded obligations + policy verdict JSON.
crates/deed-driver/src/lib.rs	Exposes the new review module publicly.
crates/deed-cli/tests/cli.rs	Adds CLI integration tests for human/JSON receipts, policy gates, imports, and refusal on non-checking sides.
crates/deed-cli/src/main.rs	Implements deed review command and refactors module-set loading/checking to share logic with existing flows.
crates/deed-cli/src/args.rs	Adds review subcommand parsing, repeatable --before/--after, and --deny-* policy flags.
CHANGELOG.md	Documents the new deed review CLI and deed_review MCP tool behavior and policy semantics.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

Suppressed comments (1)

crates/deed-driver/src/review.rs:259

• after.sort_by_key(|(_, tier)| tier_rank(*tier)) does not define an ordering for equal-tier obligations, and Rust’s slice sort is not stable. When multiple obligations share a subject+tier, this can make the paired obligation (and thus the reported occurrence) nondeterministic across runs, undermining the “stable receipt object” goal.

        before.sort_by_key(|tier| tier_rank(*tier));
        after.sort_by_key(|(_, tier)| tier_rank(*tier));