[Epic] Tool surface redesign — reconciliation-driven workflows

[dougborg]

Why

While diagnosing the mcp__statuspro-erp-dev__list_orders failure that became #27, we audited the wider MCP tool surface. Two findings drove this epic:

1. The MCP today mirrors the StatusPro REST API 1:1. That works as a starting point but leaves real workflow gaps.
2. The user's primary workflow — reconciliation against external systems (e.g. Katana) — is materially harder than it should be: no batch order fetch, no updated_since for incremental sync, no per-order outcomes from bulk_update_order_status, etc.

Goal of this epic: redesign the tool surface so an authenticated agent can drive operational workflows (reconciliation, bulk updates, "orders needing attention") without 10x the round-trips and without falling back to fragile customer-portal verbs.

Foundation (must come first)

• area/infra: set up issue/project conventions for tool-surface redesign #28 — F1: Set up issue/project conventions ✅ done
• area/spec: decide spec ownership model and execute #29 — F2: Decide spec ownership model and execute ✅ shipped in feat(spec): OpenAPI spec sync script + upstream snapshot #47 (fork-and-sync via poe sync-openapi-spec); chore(ci): add weekly upstream OpenAPI spec sync workflow #48 added the weekly auto-sync workflow
• area/spec: investigate StatusPro server capabilities for filter additions #30 — F3: Investigate StatusPro server capabilities ✅ probes complete; headline: every proposed undocumented parameter is silently ignored by the server

Tier 1 — Reconciliation-driven (P0)

Directly unblock the reconciliation workflow. Re-scoped to upstream feature requests after #30 probes.

• feat(client): list_orders id[] batch fetch #32 — R1: list_orders id[] batch fetch (upstream feature request — no client workaround)
• feat(client): list_orders updated_since filter #33 — R2: list_orders updated_since filter (upstream feature request — server doesn't expose updated_at)
• feat(mcp): bulk_update_order_status returns per-order outcomes #34 — R3: bulk_update_order_status returns per-order outcomes (upstream contract change)
• feat(mcp)!: drop lookup_order tool from MCP surface #35 — R4: Drop lookup_order tool from MCP surface ✅ shipped in feat(mcp)!: drop lookup_order tool from MCP surface #42

Tier 2 — Workflow polish (P1)

• feat(client): list_orders overdue + sort filters #36 — P1: list_orders overdue + sort filters (upstream feature request; client-side sort possible as expensive stopgap)
• feat(client): list_orders customer_email exact-match filter #37 — P2: list_orders customer_email exact-match filter (upstream feature request; search=<email> fuzzy-matches as workaround)
• feat(mcp): update_order_status preview self-validates against viable transitions #38 — P3: update_order_status preview self-validates against viable transitions ✅ shipped in feat(mcp): update_order_status preview self-validates against viable transitions #44
• feat(mcp): Prefab UI parity for remaining mutation previews #39 — P4: Prefab UI parity for remaining mutation previews ✅ shipped in feat(mcp): Prefab UI parity for add_order_comment, update_order_due_date, bulk_update_order_status #46
• feat(mcp): get_order history truncation + get_order_history pagination #40 — P5: get_order history truncation + get_order_history pagination ✅ shipped in feat: get_order history truncation + new get_order_history tool (and fix latent empty-history bug) #43

Tier 3 — Bigger features (P2)

• feat(mcp): summarize_orders aggregation tool #41 — B1: summarize_orders aggregation tool (no upstream endpoint; client-side aggregation possible but expensive)

Out of scope

• Anything outside the /orders* and /statuses REST surface
• Authentication / multi-tenancy changes
• TypeScript client parity (separate epic when it comes up)

Status snapshot

Closed (7): #28, #29, #30, #35, #38, #39, #40 ✅
Re-scoped to "upstream feature request" (6): #32, #33, #34, #36, #37, #41 — all blocked indefinitely until StatusPro extends the server-side API. Each issue's comment thread documents what we'd need from upstream.

Net effect of today's work: All implementable items shipped (8 PRs); the foundation is in place (spec sync + investigation done); everything remaining is gated on capabilities the StatusPro server doesn't yet provide.

Next steps

There's nothing more to do in this repo until upstream priorities change. Recommend:

1. File the six upstream feature requests with the StatusPro team — tracked in [Tracker] File the 6 upstream StatusPro server feature requests #57.
2. Re-evaluate Tier 3 (feat(mcp): summarize_orders aggregation tool #41 summarize) — could ship as a client-side aggregation if reporting becomes a real need before upstream does.
3. Watch for upstream spec changes via the weekly sync workflow added in chore(ci): add weekly upstream OpenAPI spec sync workflow #48.