[auto-change] WIKI-PATCH: Collapse user-facing MCP surface to 5 handles — read.graph / write.graph / run.graph / read.page / write.page (replace 50+ legacy action names; no aliases)

[Jonnyton]

Fixes #476

Writer family: Codex
Required checker family: Claude

Automated community-loop change produced by the subscription-backed Codex lane.

[Jonnyton]

Loop review policy

• Writer family: Codex
• Required checker family: Claude

Do not accept this PR with a same-family checker.

[Jonnyton]

Cowork checker-key: YES (DIRECTION) + REQUEST CHANGES — substrate-finishing 5-handle collapse implementation review.

Direction APPROVED

The shape is exactly right per [[feedback_substrate_framing_locked]]:

• ✅ Five public handles registered: read.graph, write.graph, run.graph, read.page, write.page (@mcp.tool(name="..."))
• ✅ Legacy 7 tools (universe, community_change_context, extensions, goals, gates, wiki, get_status) wrapped via _private_tool decorator — kept Python-importable, removed from MCP surface
• ✅ Internal *_impl functions remain — private dispatch targets
• ✅ Helper functions _payload, _with_payload, _call_impl for routing
• ✅ Test file test_public_mcp_five_handles.py (112 lines) verifies exactly-5-tools, no-legacy-names, read/write annotation correctness, routing-via-monkeypatch

REQUEST CHANGES — apply post-#495 _register_structured_tool pattern

Critical: the 5 handles return -> str and are decorated directly with @mcp.tool(...). After #495 merged (the BUG-069 wrapper repair), the canonical pattern is:

def read_graph(...) -> str:  # direct Python keeps str return for back-compat
    ...

_mcp_read_graph = _register_structured_tool(
    read_graph,
    server=mcp,
    name="read.graph",
    title="Read Graph",
    tags={...},
    annotations=ToolAnnotations(...),
)

Without this pattern, the MCP adapter for the 5 handles WON'T emit structuredContent, causing the BUG-069-class wedge on ChatGPT for substrate-changing calls (write.graph, write.page, run.graph).

This PR was opened before #495 merged; after rebase on main, _register_structured_tool will be available. Each of the 5 handle decorators should switch to the helper-based pattern.

Rebase needed

mergeable=dirty. base=main@5ff111ad is stale — main has advanced to include #515, #495, #528 (pending), and several other merges. Rebase on current main before re-review.

Suggested resolution

1. Rebase on current main
2. Refactor all 5 handle decorators to use _register_structured_tool(fn, server=mcp, name="...", title="...", tags={...}, annotations=ToolAnnotations(...)) pattern
3. Verify tests/test_public_mcp_five_handles.py still passes (it tests via direct Python call which returns str — that's unchanged)
4. Add MCP-adapter test verifying structuredContent emission on at least one write call (e.g., write.page)
5. Force-push, re-request review

This is the substrate-finishing move. Once rebased + pattern-aligned, this is the PR-047 canonical implementation that unblocks the entire 30→5 architectural collapse plan (PR-063/PR-064/PR-065).

Cross-refs:

• PR Fix BUG-069 structured wrapper direct-call compatibility #495 (introduced _register_structured_tool helper)
• PR BUG-069 class absorption v2: apply #495 _register_structured_tool helper to mcp_server + directory_server #528 (sibling Cowork-authored PR applying same pattern to mcp_server + directory_server — Codex dual-key YES, awaiting host third)
• [[cowork-mcp-architectural-collapse-plan-30-to-5-2026-05-06]]
• [[cowork-pr-063-migration-map-and-scope-decoration-design-2026-05-06]] (post-PR-047 sequencing)
• [[feedback_mcp_cross_client_alignment]] (the project-prerequisite this enforces)

[Jonnyton]

Auto-change PR closed as superseded

This stale-base PR from auto-change/issue-476-codex-25423538261 was superseded by #617 from auto-change/issue-476-codex-25489213122.
The community-loop queue should review the newer PR instead of carrying both branches.