feat(agent-graph): prepare grounded ingestion material

[forhappy]

Summary

• teach the bundled Compass skill how to initialize and manage GROUNDED Agent Graph enhancements during AI coding sessions
• add the read-only compass.agent-graph.ingestion-preparation/1 contract so agents select Base node/edge IDs and repository-relative source byte spans while Compass calculates canonical record, file, excerpt, and anchor values
• expose preparation through compass agent-graph prepare and MCP inspect_agent_graph operation prepare
• make prepared output directly reusable in strict atomic node-and-edge change batches, including the active compare-and-swap Overlay Revision
• freeze the new contract with a checked JSON fixture and update compatibility, command, output, guide, changelog, and installed-skill documentation
• keep Effective Graph view context compact and resolve the task-context Clippy diagnostic found by the expanded CI pass

Ingestion protocol

1. Select a current or historical Base Generation and Overlay.
2. Call prepare with exact Base IDs and at least one FILE:START_BYTE:END_BYTE source span.
3. Copy the returned Base Generation, optional expectedRevision, Base references, and grounding submission into compass.agent-graph.batch/1.
4. Apply with explicit write authority. Compass re-verifies every prepared citation and commits the whole batch or none of it.
5. Pin the receipt revision for all later reads and writes; rebase explicitly after a Base rebuild.

Preparation is read-only and never emits GROUNDED. Stale source bytes, missing or duplicate references/spans, uninventoried paths, out-of-range spans, cross-generation overlays, and caller-supplied revisions fail closed.

Safety contract

• Base Graph records and published history remain immutable
• navigation and preparation remain read-only; apply still requires explicit CLI/server write enablement
• masking requires separate intent and capability
• every accepted write advances an exact immutable Overlay Revision through CAS publication
• GROUNDED remains Compass-issued citation-integrity verification, not structural confidence or proof of semantic truth
• write scope, principal, permissions, limits, and HTTP capability stay server-owned

Verification

• cargo fmt --all -- --check
• cargo clippy --workspace --lib --bins --locked -- -D warnings
• cargo test --workspace --lib --bins --locked
• cargo clippy -p compass-agent-graph -p compass-output -p compass-cli -p compass-mcp --all-targets --all-features --locked -- -D warnings
• cargo test -p compass-agent-graph --locked
• cargo test -p compass-cli --test agent_graph_cli --locked
• cargo test -p compass-cli --test install_cli --locked
• cargo test -p compass-mcp --test agent_graph_tools --locked
• cargo test -p compass-output --lib --locked
• cargo test -p compass-cli --test compass_product --locked
• python3 scripts/check_agent_graph_contracts.py
• uv run --with pyyaml python /Users/haipingfu/.agents/skills/skill-creator/scripts/quick_validate.py crates/compass-cli/assets/compass-skill
• sh scripts/check_product_boundary.sh
• node scripts/check_viewer_assets.mjs
• ./scripts/qualify_code_graph_v1.sh --fixtures-only
• git diff --check

All Cargo commands used CARGO_TARGET_DIR=/Volumes/Workspace/crabbuild-target/compass-grounded-agent-graph and --locked.

[forhappy]

Fixed the CI compile failure in workbench::tests::workbench_document_escapes_embedded_json_and_title by initializing the new optional GraphViewModel::effective_graph field with None.

Verification:

• cargo test -p compass-output workbench_document_escapes_embedded_json_and_title --locked
• cargo test -p compass-output --lib --locked (56 passed)
• cargo fmt --all -- --check
• git diff --check