The agent proposes, the human decides: grapharc mcp and the Claude Code skill

[Shashankss1205]

Phase 2 of the supervision plan, scoped to the MCP server and the Claude Code skill. Three commits, each with failure-mode gate tests; the full suite is green after each (2,009 passed at HEAD). Builds on main independently of #98.

What lands

1. The approval gate becomes real where it was promised (9d115b4)

• GovernedLoop used to return PLANNED before the approval block could fire, so plan --approve — the form the Slack gate injects — was inert by ordering. The approval now precedes the plan-only return: an approved plan is still PLANNED, and a denial saves no plan.json for a later go to pick up.
• go <dir> --approve was accepted and silently dropped (_cmd_go passed neither flag on; execute_plan had no parameter for them). Both commands now share one gate builder, so they cannot drift on how a parked run asks its question.
• plan --json carries the admitted shape as data: run_dir, fingerprint, the proposal's nodes/edges/rationale, and a mutating verdict computed against the registry module's own MUTATING_KINDS — with a module that declared nothing read as "assume mutating", never as "declared safe".

2. grapharc mcp (164d14f) — the supervision surface, behind the mcp extra that had waited unimported since it was declared. Exactly three stdio tools:

• plan(goal, scripted?, max_rounds?) — no registry, policy or model parameters: the operator's grapharc.toml in the server's root decides those, never the requester's call.
• show_graph(run_dir) — read-only; rendered summaries, never raw state_delta; run directories confined to the server's root.
• execute(run_dir, approval_timeout?) — re-admits the saved plan; parks on the file handshake exactly when the plan's own record says it can change files, so a read-only plan runs on the host's prompt while a mutating one waits for grapharc approve <run_dir> from a human, out of band.
• There is no approve, deny, or decide tool, and a gate test holds the tool list to that sentence. The server drives the CLI as subprocesses (stdout belongs to the protocol; the --json contract is the tested one), and plan.json without a mutating field reads as mutating — an old plan is never assumed safe.

3. grapharc init --claude-code (8df4a4f) — writes .mcp.json and .claude/skills/grapharc/SKILL.md: the contract that routes multi-step work through plan → show the user the graph → execute, quotes the approve command when parked, and carries the never-clauses (never run grapharc approve, never touch the handshake files, a timeout means ask). Templates are string constants, byte-asserted by tests, never overwritten. Cookbook 09 walks the adoption; the deep dive and README state the trust boundary: the MCP gate binds the MCP surface, not a co-located agent's own file tools.

Verified

• 18 new gate tests across test_approval.py, test_mcp_gate.py, test_adopt.py — including: a denied plan --approve leaves no plan file; an unanswered mutating execute leaves the plan unexecuted and reissuable; the tool list contains no approval verb; a run_dir outside the root is refused; the server writes nothing to stdout; the skill's never-self-approve clause is present in the exact bytes shipped.
• End-to-end scripted through the real machinery: plan → show_graph → out-of-band grapharc approve from a thread → execute, plus the read-only path executing without a park.
• init --claude-code smoke-tested through the real CLI, including the exit-2 refusal on rerun.

🤖 Generated with Claude Code