fix(mcp): make axme_finalize_close required-field errors agent-actionable

[George-iam]

Summary

When an agent calls axme_finalize_close and omits any of the six required handoff strings (stopped_at, summary, in_progress, next_steps, worklog_entry, startup_text), Zod emits per-field \"Expected string, received undefined\" errors. Multiple agents have mis-read this as a per-field server bug rather than "you forgot to pass these arguments."

Most recent occurrence: another session's agent ran into the error, gave up after 4 retries with different content in the two fields it was already passing, and reported it as a server-side parser bug affecting four specific long-string fields.

Diagnosis

The schema is symmetric — all six handoff strings are plain z.string() with .describe(), no per-field preprocess, transform, or size limit. The error shape is real (Zod genuinely returns four errors when four required fields are missing), but the root cause is the missing payload, not server-side handling.

axme_begin_close's checklist output listed the six fields without marking them required, and the schema's .describe() text did not signal that omitting was an error. So the call-site contract was ambiguous → agent omitted → Zod fired multiple errors → agent inferred wrong cause.

Fix

Two surface-level changes, no behavior change for any valid call:

1. Actionable Zod messages with .min(1)

Each of the six required strings now uses .min(1, \"...\") with a custom message that:

• Names the field by name (\"in_progress is REQUIRED — ...\").
• Marks it explicit REQUIRED.
• Suggests an empty-state placeholder so the agent can satisfy the contract when the session legitimately has nothing to report (\"(nothing in progress)\", \"(none — work is complete)\", \"- (no items)\").

Example new message:

in_progress is REQUIRED — pass branches / PRs / uncommitted work, or '(nothing in progress)' if the working tree is clean. Do not omit the field.

2. Mark required vs optional in axme_begin_close checklist

The handoff section in the checklist output now splits into two blocks:

• Required (six fields) — with the omit-is-error warning and per-field placeholder examples.
• Optional — prs, test_results, blockers, dirty_branches.

Each .describe() text also leads with [REQUIRED] or [optional] so the schema-rendered tool docs match the checklist.

What this fixes

Before	After
Expected string, received undefined (4×)	in_progress is REQUIRED — pass branches / PRs / uncommitted work, or '(nothing in progress)' if the working tree is clean. (per field)
Checklist: "in_progress: current state (branches, PRs, uncommitted work)"	Checklist: "in_progress (REQUIRED) — branches, PRs, uncommitted work. Empty placeholder: \"(nothing in progress)\""

Behaviour change

For valid calls (non-empty strings for all six): no change. Same code path, same outputs.

For invalid calls that pass an empty string \"\" for a required field: now rejected with the new actionable message instead of being silently accepted and writing a blank handoff field. This is the correct behavior — a blank handoff field has no value.

For invalid calls that omit a required field: now get a much more useful Zod message naming the field, marking it required, and showing how to satisfy the contract with a placeholder.

Test plan

• Type-check clean (npx tsc --noEmit)
• Full unit test suite passes (608/608)
• Bundle builds (npm run build)
• Existing successful flows (the worklog has dozens of past successful axme_finalize_close calls) continue to work — all six fields are already populated in those, and .min(1) accepts any non-empty string.

Out of scope

• Whether to make any of the six fields actually optional. They're load-bearing for handoff quality; an empty placeholder is fine, but skipping them entirely should remain an error.
• MCP transport-layer size limits on tool arguments (not relevant — the server has none and the error wasn't a truncation, just missing fields).

🤖 Generated with Claude Code