goal-attach-evidence
PRIMARY path to close a Grove goal: this is the ONLY tool that covers an acceptance criterion. Attach binary evidence (screenshot, log dump, API response, export) to an AC — call it once per criterion to satisfy the close gate. The subordinate goal-add-evidence-text only adds context for proofs with NO bytes (URLs to permanent external sources, manual repro descriptions) and does NOT cover an AC. Caption is optional but strongly recommended: state what the file captures and the reproduction conditions (URL/commit/session/inputs) so a third reviewer can reproduce.
⚠ PICK THE RIGHT TRANSPORT BEFORE YOU CALL THIS TOOL ⚠
• BEST for ANY file > ~1 KB raw — and the ONLY no-token path, so use it in a claude.ai / hosted-agent session that has no raw X-Auth-Token → call the sibling MCP tool goal-request-upload with this same criterionId. It returns a one-time {uploadUrl, expiresAt}; then stream the raw bytes with a single PUT: curl -sS --fail --upload-file "/abs/path/to/file.png" "<uploadUrl>" (optionally add -H "X-Content-Sha256: " so corruption fails fast). No base64, no token — the signed ?t= ticket in the URL is the only credential, single-use, criterion-scoped. The PUT response is the same evidence JSON this tool returns.
• ALTERNATIVELY, if you DO have the raw X-Auth-Token in your shell → the planner-attach.sh helper (zero-install bash, binary-safe).
The MCP base64 path below is unreliable for non-trivial files: long string arguments get truncated or whitespace-corrupted on the agent side BEFORE the JSON-RPC request is sent. Measured 2026-05-20 on prod: a 4 KB PNG arrived at the server as 1874 decoded bytes (file_hash_mismatch); a 2 KB payload arrived with stray whitespace (failed base64_decode). The server itself accepts up to 25 MiB raw — the bottleneck is the agent-side serialisation of contentBase64, NOT the server.
planner-attach.sh COPY-PASTE RECIPE (replace 3 placeholders, run in your shell):
curl -sS https://planner.monopoly-gold.com/api/cli/planner-attach.sh
| PLANNER_TOKEN="" bash -s --
--criterion-id ""
--file "/abs/path/to/file.png"
--caption "what is captured and the repro conditions"
--created-by ""
Where to get each value:
PLANNER_TOKEN: the very same token that is already in your MCP config under the X-Auth-Token header for the
plannerserver. NOT a separate credential.CRITERION_UUID: the AC id you got from goal-get / goal-list. Same UUID you would pass to this MCP tool.
file path: absolute path on YOUR (agent) machine — the script reads it locally and streams multipart. The planner server never sees your filesystem.
The helper computes SHA-256 itself and ships it as contentSha256, so any in-flight corruption fails fast with HTTP 400 instead of poisoning the evidence row. Output on stdout is the same JSON shape this MCP tool returns; non-zero exit means HTTP ≥ 400 (stderr explains).
Without curl/bash? Fall back to raw multipart: POST https://planner.monopoly-gold.com/api/criteria//evidence/file, header X-Auth-Token, form fields file=@..., contentSha256=..., caption, createdBy.
• File ≤ ~1 KB raw → this MCP tool is fine. ALWAYS pass contentSha256 (hex SHA-256 of raw bytes BEFORE base64). Without it, a silently truncated PNG looks valid to the MIME sniffer; the server cannot distinguish a truncated 4 KB PNG from a valid 1 KB one and the vision judge burns ~30s on broken bytes. With the hash, the server fast-fails with error=file_hash_mismatch and points back here at the multipart endpoint.
Validates MIME whitelist (png/jpeg/webp/gif/pdf/txt/json/zip), per-file size cap (ATTACHMENTS_MAX_FILE_BYTES, default 25 MiB), per-project attachments quota. Returns evidence record + file URL + serverSha256.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Optional evidence kind override. The only accepted value is `session_history` — marks this attachment as the goal-level «full Claude session transcript» artifact required by the close gate (I4-session-history). Such evidence does NOT cover any AC and is NOT sent to the evidence judge. Omit for normal per-AC proof (kind is derived from MIME). NOTE: transcripts are usually > 1 KB → use goal-request-upload (pass kind=session_history) or the multipart helper, not this base64 path. | |
| caption | No | Optional human-readable description, stored in evidence.payload | |
| filename | Yes | Original filename (used to derive MIME). Path components are stripped. | |
| mimeType | No | MIME type — if omitted, derived from filename extension; must be in whitelist | |
| createdBy | No | Identifier of the uploading agent | |
| criterionId | Yes | UUID acceptance criterion the file will be evidence for | |
| contentBase64 | Yes | File payload, base64-encoded (RFC 4648 §4 standard alphabet, padding optional) | |
| contentSha256 | No | Hex-encoded SHA-256 of the raw bytes (before base64). When provided, the server recomputes the hash on the decoded payload and rejects with error=file_hash_mismatch if they diverge — primary defence against MCP base64 truncation. |