Add Phase 16 agent state contract skeleton

[ProfRandom92]

Summary

Phase 16 adds local agent-state capture, verify, and report support as bounded evidence artifacts.

Implemented

• ctxt state capture --task "..."
• ctxt state verify <path>
• ctxt state report <path>
• .comptext/agent_state.latest.json as ignored runtime state
• docs/AGENT_STATE_CONTRACT.md
• docs/EVIDENCE_CONTROL_PLANE.md
• reports/phase_16_status.md
• Phase 16 skill registration

Review-Gate Safeguards

• Branch-only implementation on phase-16-agent-state-contract
• No provider/network/API-key dependency
• No MCP server implementation
• No hook runtime claims
• No replay/compression port
• No autonomous repair flow
• Sensitive paths are skipped during capture and rejected before reads in verify/report
• Evidence entries are sorted by id and file_path before serialization

Validation

• cargo fmt --all --check
• cargo check
• cargo test
• cargo clippy -- -D warnings

Next

Merge only after final PR diff review.

[gemini-code-assist]

Code Review

This pull request implements the Phase 16 Agent State Contract Skeleton, introducing commands to capture, verify, and report local agent state metadata securely. The feedback highlights a few key improvement opportunities: removing unreachable dead code in the file collection logic, addressing potential ID collisions in evidence entry generation, and aligning the sorting logic in the reporting handler with the capture handler for consistency.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The condition (ext == "json" && path.to_string_lossy().contains(".comptext")) is unreachable dead code. This is because the .comptext directory is explicitly skipped during the directory traversal on line 1710 (file_name == ".comptext"). To keep the file inclusion logic clean and avoid confusion, this redundant check should be removed.

Suggested change

	let should_include = ext == "rs"
	|| ext == "md"
	|| ext == "toml"
	|| (ext == "json" && path.to_string_lossy().contains(".comptext"));
	let should_include = ext == "rs"
	|| ext == "md"
	|| ext == "toml";

[gemini-code-assist]

Replacing multiple distinct path separators and characters (/, ., -) with a single underscore (_) introduces a risk of ID collisions. For example, both src/foo-bar.rs and src/foo/bar.rs will produce the identical ID src_foo_bar_rs. When such collisions occur, handle_state_verify will fail with a duplicate evidence ID error, making the captured state invalid. Consider using a more robust mapping or appending a short hash of the original path_str to the ID if a collision is possible, or simply using the path_str itself as the unique identifier.

[gemini-code-assist]

For consistency and to guarantee a deterministic order even if duplicate IDs are present, the sorting logic in handle_state_report should match the sorting logic used in handle_state_capture (sorting by id and then by file_path).

Suggested change

	// Sort evidence by ID to guarantee stable order
	state.evidence.sort_by(|a, b| a.id.cmp(&b.id));
	// Sort evidence by id, then by file_path to guarantee stable/deterministic order
	state.evidence.sort_by(|a, b| a.id.cmp(&b.id).then_with(|| a.file_path.cmp(&b.file_path)));