@thehammer/danx-dashboard-mcp 0.1.63 → 0.1.65

package/README.md

@@ -25,12 +25,13 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 | `issue_get` | `GET /api/issues/:id` or `GET /api/issues/batch` | Pass `id` for one card, or `ids[]` (DX-2727, at most 100) to resolve many across boards in ONE call — global, so `ids` with `board` throws; per-id `not_found` rather than a whole-call 404. Minimal scalars by default; `fields` opts in |
 | `issue_create` | `POST /api/issues` | Epic REQUIRES non-empty `phase_children[]` (atomic insert). `title` = short domain-naming label; `summary` = 1–3 plain-language sentences, always shown; `description` = the collapsed "Context" body. Root and every phase child take their own `summary` |
 | `issue_edit` | `PATCH /api/issues/:id/edit` | Prose + structured keys (`title`, `summary` (null clears), `description`, `ac`, `checklists`, `effort_level`, `parent_id`, `priority`, `list_id`); semantic keys refused with 400 + pointer to dedicated handler. `priority` (DX-1532) takes a tier word (`low`/`high`/…) or a number in `[0,6)` — the ONLY way to set the numeric column the Trello label + dashboard badge read; never set priority via description prose |
-| `issue_transition` | `POST /api/issues/:id/transition` | Actions: ready, pickup, rollback_pickup, complete, cancel, block, unblock, archive, reopen. A successful `block` also returns `solutions_reminder: {solution_count, instruction}` |
-| `issue_solution` | `GET/POST/PATCH/DELETE /api/issues/:id/solutions[/:sid]` | Actions list / add / edit / remove. Edit + remove are hash-guarded (`base_hash`, 409 `stale_solution` with the current row); at most one live `recommended`; a chosen option cannot be edited. No answer action — the operator answers in the dashboard |
+| `issue_transition` | `POST /api/issues/:id/transition` | Actions: ready, pickup, rollback_pickup, complete, cancel, block, unblock, archive, reopen. `block` is a dispatch hold only — it never marks the card as needing a human; use `issue_problem` + `issue_requires_human` for that |
+| `issue_problem` | `GET/POST/PATCH/DELETE /api/issues/:id/problems[/:pid]` | Actions list / add / edit / remove. A problem is one statement the operator must resolve (a question or a plan flaw) with its own solutions and answers; `add` takes `statement` + optional `solutions[]` in one transaction. Edit + remove are hash-guarded (`base_hash`, 409 `stale_problem`); removing the last open problem while `requires_human` is set is refused 409 `last_open_problem` |
+| `issue_solution` | `POST/PATCH/DELETE /api/issues/:id/problems/:pid/solutions[/:sid]` | Actions add / edit / remove, `problem_id` required (list via `issue_problem list`). Edit + remove are hash-guarded (`base_hash`, 409 `stale_solution` with the current row); at most one live `recommended` per problem; a chosen option cannot be edited. No answer action on any tool — the operator answers in the dashboard |
 | `issue_triage` | `POST /api/issues/:id/triage` | Send `{confidence, reason}` — an integer 0-5 score; the server computes the verdict (approve/cancel/keep/defer) against the board's configured thresholds (DX-2086). `keep`/`defer` now block the card. None of these are a cross-card ordering gate; use `issue_dependency` to sequence cards |
 | `issue_comment` | `POST/PATCH/DELETE /api/issues/:id/comments[/:cid]` | Author server-stamped, soft-delete preserved |
 | `issue_dependency` | `POST/DELETE /api/issues/:id/dependencies[/:did]` | `depends_on` cycle-checked; remove hardcodes `reason: "recorded_in_error"`. The only mechanism the dispatch picker enforces to sequence one card after another — status alone is not a substitute |
-| `issue_requires_human` | `POST/DELETE /api/issues/:id/requires-human` | Set replaces step rows atomically; clear soft-deletes them. A successful set also returns `solutions_reminder: {solution_count, instruction}` |
+| `issue_requires_human` | `POST/DELETE /api/issues/:id/requires-human` | Set REQUIRES an open problem (409 `no_open_problem` with the server's `fix` otherwise) and replaces step rows atomically; clear soft-deletes them. The gate clears itself when the last open problem is answered. A successful set also returns `problems_reminder: {open_problem_count, instruction}` |
 | `issue_retro` | `PUT /api/issues/:id/retro` | Requires terminal card; replace semantics |
 
 ## `plan_get` — cheap by default, opt-in for the rest (DX-2727)
@@ -48,7 +49,7 @@ npx -y @thehammer/danx-dashboard-mcp@<version> listen --stream <dashboard>/api/p
 All three flags come from the dashboard's own ticket response; `plan_connect` assembles the command, so never build it by hand.
 
 - **Credential.** `--ticket` is a listener ticket minted by `POST /api/plan-sessions/me/stream-ticket` for THIS session only. It authorizes reading that one session's event stream and nothing else, and stops the moment the credential that minted it is revoked — the MCP server's own token never appears in the command. Minting a new one (calling `plan_connect` again) ends the previous listener; a second connection with the same ticket replaces the first.
-- **Output.** Exactly one line per event on the connected plan's cards — `[DX-8 "Title" repo:board] newms87 answered: chose "Pause E2E" — note: "only this week"`, `… commented: "…"`, `… set requires_human: "…"`, `… cleared requires_human`, `… blocked the card: "…"`, `… unblocked the card`. Nothing for keep-alives or reconnects. The session's own writes are never echoed back to it. An event it cannot read still produces one `could not read event` line.
+- **Output.** Exactly one line per event on the connected plan's cards — `[DX-8 "Title" repo:board] newms87 answered "Which rollout order?": chose "Pause E2E" — note: "only this week"`, `… answered "…": "<free-form answer>"`, `… commented: "…"`, `… set requires_human: "…"`, `… cleared requires_human`, `… blocked the card: "…"`, `… unblocked the card`. Nothing for keep-alives or reconnects. The session's own writes are never echoed back to it. An event it cannot read still produces one `could not read event` line.
 - **Reconnect.** A read-idle timeout (three missed keep-alives) turns a silently dead connection into a drop. Capped exponential backoff (1s → 30s) that resets only after a healthy connection, with `Last-Event-ID`, so a dashboard restart replays what was missed and nothing is printed twice. One final `[danx-dashboard listen] …` line and exit when the ticket is refused or revoked (exit 1), when a newer listener takes over (exit 0), or after `--lease-ms` without a healthy connection (exit 1) — the remedy is always `plan_connect` again.
 
 ## Build + test

package/dist/handlers.js

@@ -23,6 +23,7 @@
  */
 import { readFile } from "node:fs/promises";
 import { basename, extname, isAbsolute } from "node:path";
+import { oneLine } from "./one-line.js";
 import { resolvePriority } from "./priority.js";
 /**
  * `filter`/`fields`/`sort` are JSON/CSV-encoded onto the query string (the
@@ -255,62 +256,92 @@ export async function issueEdit(client, args) {
 }
 export async function issueTransition(client, args) {
     const { id, board, ...body } = args;
-    const result = await client.request({
+    // DX-2735: no reminder on block. A block is a dispatch HOLD only — it never
+    // puts the card in front of a human — so there is no question to list
+    // options for. A card that needs a human uses issue_problem + issue_requires_human.
+    return client.request({
         method: "POST",
         path: `/${encodeURIComponent(id)}/transition`,
         body,
         board,
     });
-    return args.action === "block" ? withSolutionsReminder(client, id, board, result) : result;
+}
+/** How much of a problem statement the reminder quotes — enough to recognise it. */
+const REMINDER_STATEMENT_MAX = 120;
+function isReminderProblem(value) {
+    const p = value;
+    return (typeof p === "object" &&
+        p !== null &&
+        typeof p.id === "number" &&
+        typeof p.statement === "string" &&
+        typeof p.open === "boolean" &&
+        Array.isArray(p.solutions));
 }
 /**
- * Attach the solutions reminder to a SUCCESSFUL gating write.
+ * Attach the problems reminder to a SUCCESSFUL requires-human set.
  *
- * ENFORCED BY FEEDBACK, NOT BY REFUSAL. The server never rejects a block or a
- * requires-human hold for lacking solutions: some holds legitimately have no
- * options to list (a credential only the operator can supply), and a refusal
- * there would push the agent into inventing solutions to get past the gate.
- * What the operator needs is that an agent which CAN lay out options always
- * does — so the reminder rides the success response, where it is read at the
- * exact moment the agent is deciding whether it is done.
+ * DX-2735 — THE SERVER NOW ENFORCES THE QUESTION, THIS ENFORCES THE OPTIONS.
+ * The set route refuses 409 `no_open_problem` unless the card has an open
+ * problem, so a card can no longer be put in front of a human without saying
+ * what the human must decide. Whether each open problem lists its viable
+ * solutions is still feedback, not refusal: a problem with zero solutions is
+ * valid (the operator answers free-form), and refusing it would push the agent
+ * into inventing options. So the reminder rides the success response and names
+ * the STILL-OPEN problems only — an answered sibling needs nothing more.
  *
- * The gating write's own envelope is returned untouched beside it. A refused
- * write gets no reminder (there is no stop to remind about). A failure READING
- * the solutions is reported inside the reminder rather than thrown: the gating
- * write already succeeded, and throwing would tell the agent its block failed
- * when it did not — the failure is surfaced, never swallowed.
+ * The write's own envelope is returned untouched beside it. A refused write
+ * (including `no_open_problem`, whose `fix` text passes through verbatim) gets
+ * no reminder and no extra request. A failure READING the problems is reported
+ * inside the reminder rather than thrown: the set already succeeded, and
+ * throwing would tell the agent it failed when it did not.
  */
-export async function withSolutionsReminder(client, id, board, result) {
+export async function withProblemsReminder(client, id, board, result) {
     if (!result.ok)
         return result;
-    const nextStep = `issue_solution({id: "${id}", action: "add", title, body, pro, con})`;
     let listed;
     try {
         listed = await client.request({
             method: "GET",
-            path: `/${encodeURIComponent(id)}/solutions`,
+            path: `/${encodeURIComponent(id)}/problems`,
             board,
         });
     }
     catch (err) {
-        return { ...result, solutions_reminder: unreadableReminder(id, err instanceof Error ? err.message : String(err)) };
+        return { ...result, problems_reminder: unreadableReminder(id, err instanceof Error ? err.message : String(err)) };
     }
     // `body` is the server's JSON verbatim — `null` is valid JSON, so read it null-safely;
     // a throw here would land OUTSIDE the try above and misreport the successful write.
-    const solutions = listed.ok ? listed.body?.solutions : undefined;
-    if (!Array.isArray(solutions)) {
-        return { ...result, solutions_reminder: unreadableReminder(id, `HTTP ${listed.status}`) };
+    const problems = listed.ok ? listed.body?.problems : undefined;
+    if (!Array.isArray(problems) || !problems.every(isReminderProblem)) {
+        // A 2xx whose body is not the problem list is a contract break, not a refusal —
+        // say so, rather than leaving a bare "HTTP 200" that reads like success.
+        const detail = listed.ok ? `HTTP ${listed.status}, unexpected shape` : `HTTP ${listed.status}`;
+        return { ...result, problems_reminder: unreadableReminder(id, detail) };
+    }
+    const open = problems.filter((p) => p.open);
+    return { ...result, problems_reminder: { open_problem_count: open.length, instruction: openProblemsInstruction(id, open) } };
+}
+function openProblemsInstruction(id, open) {
+    if (open.length === 0) {
+        // Only reachable when every problem was answered between the set and this
+        // read — the gate has already released itself.
+        return `No problem on ${id} is open any more — each was answered after you set requires_human, which releases the gate. Re-read the card before you stop.`;
     }
-    const count = solutions.length;
-    const instruction = count === 0
-        ? `NO SOLUTIONS ARE LISTED ON ${id}. Before you stop, add EVERY viable solution with ${nextStep}, and mark the one you recommend with recommended: true. The operator answers a stopped card by picking a listed solution — with none listed, they have to reconstruct the options from the description.`
-        : `${count} solution${count === 1 ? " is" : "s are"} listed on ${id}. Before you stop, confirm EVERY viable solution is on the card and add any that are missing with ${nextStep}. The operator can only pick from what is listed.`;
-    return { ...result, solutions_reminder: { solution_count: count, instruction } };
+    const listing = open
+        .map((p) => {
+        const statement = oneLine(p.statement, REMINDER_STATEMENT_MAX);
+        const count = p.solutions.length;
+        return `problem ${p.id} "${statement}" — ${count === 0 ? "NO SOLUTIONS LISTED" : `${count} solution${count === 1 ? "" : "s"}`}`;
+    })
+        .join("; ");
+    return (`${open.length} open problem${open.length === 1 ? "" : "s"} on ${id}: ${listing}. ` +
+        `Before you stop, list EVERY viable solution to each with issue_solution({id: "${id}", problem_id, action: "add", title, body, pro, con}) and mark the one you recommend with recommended: true, ` +
+        `and make every other question the operator must answer its own problem with issue_problem. The card needs a human until every open problem is answered.`);
 }
 function unreadableReminder(id, detail) {
     return {
-        solution_count: null,
-        instruction: `Could not read the solutions on ${id} (${detail}). Check with issue_solution({id: "${id}", action: "list"}) and make sure EVERY viable solution is listed before you stop.`,
+        open_problem_count: null,
+        instruction: `Could not read the problems on ${id} (${detail}). Check with issue_problem({id: "${id}", action: "list"}) and make sure EVERY viable solution to each open problem is listed before you stop.`,
     };
 }
 export async function issueTriage(client, args) {
@@ -322,72 +353,104 @@ export async function issueTriage(client, args) {
         board,
     });
 }
+/**
+ * DX-2735 — the ONE boundary check every action-dispatched handler uses for its
+ * required args. The MCP schema already validates, but a handler can be called
+ * without it (tests, the composition E2E, a future caller), so each required arg
+ * is checked by TYPE, not merely for presence: `null`, a number where text
+ * belongs, or a string where a row id belongs all throw here, before any request
+ * is built, as `<tool> <mode> requires <arg> (<what it must be>)`.
+ *
+ * Returns the checkers rather than checking anything itself. `mode` is the
+ * condition the args are required under — `action=<action>` for the
+ * action-dispatched tools, `set=true` for issue_requires_human — so every tool
+ * refuses in the same wording.
+ */
+function argCheckers(tool, mode) {
+    const fail = (name, expected) => {
+        throw new Error(`${tool} ${mode} requires ${name} (${expected})`);
+    };
+    return {
+        /** Text, a content hash, a name, an enum value. */
+        string(value, name) {
+            if (typeof value !== "string")
+                fail(name, "a string");
+            return value;
+        },
+        /** A database row id. */
+        id(value, name) {
+            if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0)
+                fail(name, "a positive integer id");
+            return value;
+        },
+        /**
+         * A list of human-written lines (e.g. requires_human steps). DX-2735: every
+         * element must be a non-blank string, matching the server, which refuses a
+         * blank step — refused here before any request is built. An empty list is
+         * allowed, as the server allows it.
+         */
+        stringArray(value, name) {
+            const valid = Array.isArray(value) && value.every((item) => typeof item === "string" && item.trim() !== "");
+            if (!valid)
+                fail(name, "an array of non-blank strings");
+            return value;
+        },
+    };
+}
 export async function issueComment(client, args) {
     const idEnc = encodeURIComponent(args.id);
     const board = args.board;
+    const need = argCheckers("issue_comment", `action=${args.action}`);
     if (args.action === "add") {
-        if (typeof args.text !== "string") {
-            throw new Error("issue_comment action=add requires text");
-        }
+        const text = need.string(args.text, "text");
         return client.request({
             method: "POST",
             path: `/${idEnc}/comments`,
-            body: { text: args.text, ...(args.metadata !== undefined ? { metadata: args.metadata } : {}) },
+            body: { text, ...(args.metadata !== undefined ? { metadata: args.metadata } : {}) },
             board,
         });
     }
     if (args.action === "edit") {
-        if (args.comment_id === undefined) {
-            throw new Error("issue_comment action=edit requires comment_id");
-        }
-        if (typeof args.text !== "string") {
-            throw new Error("issue_comment action=edit requires text");
-        }
+        const commentId = need.id(args.comment_id, "comment_id");
+        const text = need.string(args.text, "text");
         return client.request({
             method: "PATCH",
-            path: `/${idEnc}/comments/${args.comment_id}`,
-            body: { text: args.text },
+            path: `/${idEnc}/comments/${commentId}`,
+            body: { text },
             board,
         });
     }
     // delete
-    if (args.comment_id === undefined) {
-        throw new Error("issue_comment action=delete requires comment_id");
-    }
+    const commentId = need.id(args.comment_id, "comment_id");
     return client.request({
         method: "DELETE",
-        path: `/${idEnc}/comments/${args.comment_id}`,
+        path: `/${idEnc}/comments/${commentId}`,
         board,
     });
 }
 export async function issueDependency(client, args) {
     const idEnc = encodeURIComponent(args.id);
     const board = args.board;
+    const need = argCheckers("issue_dependency", `action=${args.action}`);
     if (args.action === "add") {
-        if (args.kind === undefined) {
-            throw new Error("issue_dependency action=add requires kind");
-        }
-        if (args.target_id === undefined) {
-            throw new Error("issue_dependency action=add requires target_id");
-        }
+        const kind = need.string(args.kind, "kind");
+        const targetId = need.string(args.target_id, "target_id");
         return client.request({
             method: "POST",
             path: `/${idEnc}/dependencies`,
             body: {
-                kind: args.kind,
-                target_id: args.target_id,
+                kind,
+                target_id: targetId,
                 reason: args.reason ?? "",
             },
             board,
         });
     }
     // remove
-    if (args.dependency_id === undefined) {
-        throw new Error("issue_dependency action=remove requires dependency_id");
-    }
+    const dependencyId = need.id(args.dependency_id, "dependency_id");
     return client.request({
         method: "DELETE",
-        path: `/${idEnc}/dependencies/${args.dependency_id}`,
+        path: `/${idEnc}/dependencies/${dependencyId}`,
         // Server demands literal "recorded_in_error" — any other value is
         // a 400. The MCP boundary hardcodes it to remove a footgun: an
         // agent that types the wrong reason gets a refusal here at MCP
@@ -407,12 +470,10 @@ export async function issueDependency(client, args) {
 export async function issueChecklist(client, args) {
     const idEnc = encodeURIComponent(args.id);
     const board = args.board;
+    const need = argCheckers("issue_checklist", `action=${args.action}`);
     switch (args.action) {
         case "add_list": {
-            if (typeof args.name !== "string") {
-                throw new Error("issue_checklist action=add_list requires name");
-            }
-            const body = { name: args.name };
+            const body = { name: need.string(args.name, "name") };
             if (args.items !== undefined)
                 body.items = args.items;
             return client.request({
@@ -423,55 +484,40 @@ export async function issueChecklist(client, args) {
             });
         }
         case "update_list": {
-            if (args.checklist_id === undefined) {
-                throw new Error("issue_checklist action=update_list requires checklist_id");
-            }
-            if (typeof args.name !== "string") {
-                throw new Error("issue_checklist action=update_list requires name");
-            }
+            const checklistId = need.id(args.checklist_id, "checklist_id");
+            const name = need.string(args.name, "name");
             return client.request({
                 method: "PATCH",
-                path: `/${idEnc}/checklists/${args.checklist_id}`,
-                body: { name: args.name },
+                path: `/${idEnc}/checklists/${checklistId}`,
+                body: { name },
                 board,
             });
         }
         case "remove_list": {
-            if (args.checklist_id === undefined) {
-                throw new Error("issue_checklist action=remove_list requires checklist_id");
-            }
+            const checklistId = need.id(args.checklist_id, "checklist_id");
             return client.request({
                 method: "DELETE",
-                path: `/${idEnc}/checklists/${args.checklist_id}`,
+                path: `/${idEnc}/checklists/${checklistId}`,
                 board,
             });
         }
         case "add_item": {
-            if (args.checklist_id === undefined) {
-                throw new Error("issue_checklist action=add_item requires checklist_id");
-            }
-            if (typeof args.label !== "string") {
-                throw new Error("issue_checklist action=add_item requires label");
-            }
-            const body = { label: args.label };
+            const checklistId = need.id(args.checklist_id, "checklist_id");
+            const body = { label: need.string(args.label, "label") };
             if (args.detail !== undefined)
                 body.detail = args.detail;
             if (args.status !== undefined)
                 body.status = args.status;
             return client.request({
                 method: "POST",
-                path: `/${idEnc}/checklists/${args.checklist_id}/items`,
+                path: `/${idEnc}/checklists/${checklistId}/items`,
                 body,
                 board,
             });
         }
         case "update_item": {
-            if (args.checklist_id === undefined) {
-                throw new Error("issue_checklist action=update_item requires checklist_id");
-            }
-            if (args.item_id === undefined) {
-                throw new Error("issue_checklist action=update_item requires item_id");
-            }
+            const checklistId = need.id(args.checklist_id, "checklist_id");
+            const itemId = need.id(args.item_id, "item_id");
             const body = {};
             if (args.label !== undefined)
                 body.label = args.label;
@@ -481,39 +527,92 @@ export async function issueChecklist(client, args) {
                 body.status = args.status;
             return client.request({
                 method: "PATCH",
-                path: `/${idEnc}/checklists/${args.checklist_id}/items/${args.item_id}`,
+                path: `/${idEnc}/checklists/${checklistId}/items/${itemId}`,
                 body,
                 board,
             });
         }
         case "remove_item": {
-            if (args.checklist_id === undefined) {
-                throw new Error("issue_checklist action=remove_item requires checklist_id");
-            }
-            if (args.item_id === undefined) {
-                throw new Error("issue_checklist action=remove_item requires item_id");
-            }
+            const checklistId = need.id(args.checklist_id, "checklist_id");
+            const itemId = need.id(args.item_id, "item_id");
+            return client.request({
+                method: "DELETE",
+                path: `/${idEnc}/checklists/${checklistId}/items/${itemId}`,
+                board,
+            });
+        }
+    }
+}
+/**
+ * A card's PROBLEMS via `/api/issues/:id/problems[/:pid]` (DX-2735),
+ * action-dispatched like `issue_checklist`. A problem is one statement the
+ * operator must resolve — a question or a flaw in the plan — owning its own
+ * solutions and its own decisions. A missing required arg throws at this
+ * boundary (no round-trip); the server's refusals (`stale_problem` with the
+ * current row, `last_open_problem`) pass through verbatim.
+ *
+ * `add` carries `solutions[]` in the SAME request so a problem and its options
+ * land in one server transaction — never a problem briefly visible to the
+ * operator with none of the options it was created with.
+ *
+ * No answer action, for the reason `issueSolution` gives.
+ */
+export async function issueProblem(client, args) {
+    const idEnc = encodeURIComponent(args.id);
+    const board = args.board;
+    const need = argCheckers("issue_problem", `action=${args.action}`);
+    switch (args.action) {
+        case "list":
+            return client.request({ method: "GET", path: `/${idEnc}/problems`, board });
+        case "add": {
+            const body = { statement: need.string(args.statement, "statement") };
+            if (args.solutions !== undefined)
+                body.solutions = args.solutions;
+            return client.request({ method: "POST", path: `/${idEnc}/problems`, body, board });
+        }
+        case "edit": {
+            const problemId = need.id(args.problem_id, "problem_id");
+            const baseHash = need.string(args.base_hash, "base_hash");
+            const statement = need.string(args.statement, "statement");
+            return client.request({
+                method: "PATCH",
+                path: `/${idEnc}/problems/${problemId}`,
+                body: { base_hash: baseHash, statement },
+                board,
+            });
+        }
+        case "remove": {
+            const problemId = need.id(args.problem_id, "problem_id");
+            const baseHash = need.string(args.base_hash, "base_hash");
             return client.request({
                 method: "DELETE",
-                path: `/${idEnc}/checklists/${args.checklist_id}/items/${args.item_id}`,
+                path: `/${idEnc}/problems/${problemId}`,
+                body: { base_hash: baseHash },
                 board,
             });
         }
     }
 }
 /**
- * A card's candidate solutions via `/api/issues/:id/solutions[/:sid]`,
- * action-dispatched like `issue_checklist`. A missing required arg for the
- * chosen action throws at this boundary (no round-trip); the server's refusal
- * envelopes (`stale_solution` with the current row, a second recommendation,
- * editing a chosen option) pass through verbatim.
+ * One problem's candidate solutions via
+ * `/api/issues/:id/problems/:pid/solutions[/:sid]` (DX-2735), action-dispatched
+ * like `issue_checklist`. A missing required arg for the chosen action throws at
+ * this boundary (no round-trip); the server's refusal envelopes
+ * (`stale_solution` with the current row, a second recommendation on the same
+ * problem, editing a chosen option, a solution id from another problem → 404)
+ * pass through verbatim.
  *
- * There is deliberately NO answer action. Answering a card releases the human
- * gates on it — an agent that could answer its own question could release the
- * very stop it set to wait for a human. The operator answers in the dashboard.
+ * There is deliberately NO answer action, on this tool or any other. Answering
+ * releases the human gate on a card — an agent that could answer its own
+ * question could release the very stop it set to wait for a human. The operator
+ * answers in the dashboard.
  */
 export async function issueSolution(client, args) {
-    const base = `/${encodeURIComponent(args.id)}/solutions`;
+    const need = argCheckers("issue_solution", `action=${args.action}`);
+    // DX-2735: checked at runtime too, not only by the schema — a caller that skips
+    // the MCP boundary must never build `/problems/undefined/solutions`.
+    const problemId = need.id(args.problem_id, "problem_id");
+    const base = `/${encodeURIComponent(args.id)}/problems/${problemId}/solutions`;
     const board = args.board;
     const content = {};
     for (const key of ["title", "body", "pro", "con", "recommended"]) {
@@ -521,58 +620,49 @@ export async function issueSolution(client, args) {
             content[key] = args[key];
     }
     switch (args.action) {
-        case "list":
-            return client.request({ method: "GET", path: base, board });
-        case "add":
-            if (typeof args.title !== "string") {
-                throw new Error("issue_solution action=add requires title");
-            }
-            return client.request({ method: "POST", path: base, body: content, board });
-        case "edit":
-            if (args.solution_id === undefined) {
-                throw new Error("issue_solution action=edit requires solution_id");
-            }
-            if (typeof args.base_hash !== "string") {
-                throw new Error("issue_solution action=edit requires base_hash");
-            }
+        case "add": {
+            // DX-2735: the POST carries the CHECKED title, not a re-read of args.title.
+            const title = need.string(args.title, "title");
+            return client.request({ method: "POST", path: base, body: { ...content, title }, board });
+        }
+        case "edit": {
+            const solutionId = need.id(args.solution_id, "solution_id");
+            const baseHash = need.string(args.base_hash, "base_hash");
             return client.request({
                 method: "PATCH",
-                path: `${base}/${args.solution_id}`,
-                body: { base_hash: args.base_hash, ...content },
+                path: `${base}/${solutionId}`,
+                body: { base_hash: baseHash, ...content },
                 board,
             });
-        case "remove":
-            if (args.solution_id === undefined) {
-                throw new Error("issue_solution action=remove requires solution_id");
-            }
-            if (typeof args.base_hash !== "string") {
-                throw new Error("issue_solution action=remove requires base_hash");
-            }
+        }
+        case "remove": {
+            const solutionId = need.id(args.solution_id, "solution_id");
+            const baseHash = need.string(args.base_hash, "base_hash");
             return client.request({
                 method: "DELETE",
-                path: `${base}/${args.solution_id}`,
-                body: { base_hash: args.base_hash },
+                path: `${base}/${solutionId}`,
+                body: { base_hash: baseHash },
                 board,
             });
+        }
     }
 }
 export async function issueRequiresHuman(client, args) {
     const idEnc = encodeURIComponent(args.id);
     const board = args.board;
     if (args.set) {
-        if (typeof args.reason !== "string") {
-            throw new Error("issue_requires_human set=true requires reason");
-        }
-        if (!Array.isArray(args.steps)) {
-            throw new Error("issue_requires_human set=true requires steps[]");
-        }
+        // DX-2735: the same checkers every action-dispatched tool uses, so the refusal
+        // wording and type checks match — `issue_requires_human set=true requires ...`.
+        const need = argCheckers("issue_requires_human", "set=true");
+        const reason = need.string(args.reason, "reason");
+        const steps = need.stringArray(args.steps, "steps");
         const result = await client.request({
             method: "POST",
             path: `/${idEnc}/requires-human`,
-            body: { reason: args.reason, steps: args.steps },
+            body: { reason, steps },
             board,
         });
-        return withSolutionsReminder(client, args.id, board, result);
+        return withProblemsReminder(client, args.id, board, result);
     }
     return client.request({
         method: "DELETE",

package/dist/index.js

@@ -19,7 +19,8 @@
  *   - issue_triage           POST   /api/issues/:id/triage
  *   - issue_comment          POST/PATCH/DELETE /api/issues/:id/comments[/:cid]
  *   - issue_checklist        POST/PATCH/DELETE /api/issues/:id/checklists[/:cid[/items[/:iid]]]
- *   - issue_solution         GET/POST/PATCH/DELETE /api/issues/:id/solutions[/:sid]
+ *   - issue_problem          GET/POST/PATCH/DELETE /api/issues/:id/problems[/:pid] (DX-2735)
+ *   - issue_solution         POST/PATCH/DELETE /api/issues/:id/problems/:pid/solutions[/:sid] (DX-2735)
  *   - issue_dependency       POST/DELETE /api/issues/:id/dependencies[/:did]
  *   - issue_requires_human   POST/DELETE /api/issues/:id/requires-human
  *   - issue_quality_gate     POST   /api/issues/:id/quality-gates/:gate
@@ -88,7 +89,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { DashboardHttpClient } from "./http-client.js";
-import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueQualityGate, issueQualityGateVerdict, issueRequiresHuman, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, planAddArchitectureSection, planAddCard, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteRecord, planGet, PLAN_FIELD_GROUPS, ISSUE_BATCH_GET_MAX, LIST_PAGE_MAX_LIMIT, PLAN_GET_CARDS_DEFAULT_LIMIT, planGetArchitectureSection, planGetRecord, planList, planRemoveCard, planRename, planReorderArchitectureSection, planUpdateArchitectureSection, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
+import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueProblem, issueQualityGate, issueQualityGateVerdict, issueRequiresHuman, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, planAddArchitectureSection, planAddCard, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteRecord, planGet, PLAN_FIELD_GROUPS, ISSUE_BATCH_GET_MAX, LIST_PAGE_MAX_LIMIT, PLAN_GET_CARDS_DEFAULT_LIMIT, planGetArchitectureSection, planGetRecord, planList, planRemoveCard, planRename, planReorderArchitectureSection, planUpdateArchitectureSection, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
 import { PRIORITY_TIER_WORDS } from "./priority.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -214,7 +215,8 @@ const NON_EPIC_TYPES = ["Bug", "Feature", "Story", "Chore", "Task"];
 // server 400, not silently.
 const LIST_FIELD_GROUPS = [
     "description",
-    "solutions",
+    // DX-2735: replaced the flat "solutions" group (hard cut, no alias).
+    "problems",
     "ac",
     "comments",
     "retro",
@@ -273,16 +275,19 @@ const boardField = {
         .string()
         .min(1)
         .optional()
-        .describe("Target another board by its qualified id `<repo>:<slug>` (e.g. `platform:the-supply-operations-hub`); omit to use this dispatch's board. Unknown board → 404."),
+        .describe("Target another board by its qualified id `<repo>:<slug>`; omit for this dispatch's board. Unknown → 404."),
 };
 // The three prose fields of a card, each with ONE job. Shared by issue_create
 // (root + phase children) and issue_edit so the guidance an agent reads is
 // identical wherever it writes the field.
-const TITLE_DESCRIBE = 'Short, specific label that names the domain, so a reader recognises the card without opening it (e.g. "Guest checkout rejects carts holding a gift card"). Never a generic phrase like "2 real decisions needed", "Fix bug" or "Follow-up".';
-const SUMMARY_DESCRIBE = "1–3 plain-language sentences — no markdown, no jargon — for someone who has never seen this codebase: what the card is about and why it matters. Always shown, never collapsed. It must stand on its own: not a second title, not a teaser for the description.";
-const DESCRIPTION_DESCRIBE = 'The full body ("Context"): evidence, examples, technical detail. Long and markdown is normal; UIs collapse it by default. Candidate answers to the question a card is stopped on do NOT go here — list each one with issue_solution.';
+const TITLE_DESCRIBE = 'Short, specific label naming the domain, so a reader recognises the card unopened (e.g. "Guest checkout rejects carts holding a gift card"). Never generic ("2 real decisions needed", "Fix bug", "Follow-up").';
+const SUMMARY_DESCRIBE = "1–3 plain-language sentences, no markdown/jargon, for someone new to this codebase: what the card is and why it matters. Always shown, never collapsed — not a second title, not a teaser for the description.";
+const DESCRIPTION_DESCRIBE = 'The full body ("Context"): evidence, examples, technical detail; markdown, collapsed by default. A question for the operator and its options go in issue_problem, not here.';
 // ---------------- issue_list ----------------
-server.tool("issue_list", "List issues for the dispatch's board by default via GET /api/issues. Board-scoped; defaults to the dispatch's board. Pass `board` (a qualified id `<repo>:<slug>`) to list another board instead (unknown board → 404). Nested envelope (DX-935 / DX-937 — hard-cut, no flat params): `filter` — the OLD flat filters, now nested (type, parent_id, dispatchable_derived, status_derived[], self_dispatchable_derived, assigned_agent, include_closed, include_deleted, and `q` — free-text over id+title+description, the former standalone `q` param now lives at `filter.q`). `fields` — opt-in named field-GROUPS (description, ac, comments, retro, dependencies, triage, requires_human, assignment, quality_gates, children, effort); THE DEFAULT RESPONSE (no `fields`) IS MINIMAL — only cheap scalar columns (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent, content_hash), zero joins. Point any heavy read (full description, comments[], retro, ac items, dependency edges, triage history, quality-gate rows, children ids) at the matching `fields` entry rather than assuming it's already on the row. `sort` — ordered [{column, order}] (id|priority|repo_name|title|type|status_derived|triage_ice_total|created_at|updated_at); absent → default order (priority desc, repo_name asc) with an always-appended numeric-id tiebreaker (DX-10 follows DX-9). `limit`/`offset` — optional paging (no cap by default). Use issue_get for a single fully-detailed card.", {
+server.tool("issue_list", 
+// DX-2735: trimmed to pay for the problem tools inside the work-profile
+// injected-surface budget — same facts, no repeated prose.
+"List cards via GET /api/issues. Board-scoped; see `board`. `filter`: type, parent_id, dispatchable_derived, status_derived[], self_dispatchable_derived, assigned_agent, include_closed, include_deleted, q (free text over id+title+description). THE DEFAULT ROW IS MINIMAL — scalars only (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent, content_hash), no joins; opt into heavy data with `fields` groups: description (+ summary), problems (open_problem_count), ac, comments, retro, dependencies, triage, requires_human, assignment, quality_gates, children, effort. `sort`: [{column, order}] over id|priority|repo_name|title|type|status_derived|triage_ice_total|created_at|updated_at; default priority desc, repo_name asc, numeric-id tiebreaker. `limit`/`offset` page (uncapped by default). issue_get reads one card in full.", {
     filter: z
         .object({
         q: z.string().optional(),
@@ -295,34 +300,31 @@ server.tool("issue_list", "List issues for the dispatch's board by default via G
         include_closed: z.boolean().optional(),
         include_deleted: z.boolean().optional(),
     })
-        .optional()
-        .describe("Nested list filters (DX-935) — the hard-cut replacement for the old flat top-level params, including the former standalone `q` (now `filter.q`). Omit entirely for no filtering."),
+        .optional(),
     fields: z
         .array(z.enum(LIST_FIELD_GROUPS))
         .optional()
-        .describe("Opt-in field-GROUPS to add to the minimal default row: description (description + summary), solutions (solutions_count), ac, comments, retro, dependencies, triage, requires_human, assignment, quality_gates, children, effort. Absent/empty = minimal scalars only — no joins."),
+        .describe("Field groups to add; absent = minimal scalars."),
     sort: sortField,
     limit: z.number().int().positive().max(LIST_PAGE_MAX_LIMIT).optional(),
     offset: z.number().int().nonnegative().optional(),
     ...boardField,
 }, async (args) => jsonResult(await issueList(client, args)));
 // ---------------- issue_get ----------------
-server.tool("issue_get", "Fetch one card via GET /api/issues/:id, or MANY via GET /api/issues/batch?ids=... (DX-2727) — pass exactly one of `id` (single) or `ids` (batch, an array). Board-scoped for the single form; defaults to the dispatch's board. Issue ids are globally unique, so BOTH forms resolve from any dispatch regardless of `board`; the batch form is a global, cross-board read and REFUSES `board` (passing `ids` with `board` throws). The batch form takes at most " + ISSUE_BATCH_GET_MAX + " ids per call — split a larger set. DEFAULT RESPONSE IS MINIMAL (DX-935 / DX-937) — only cheap scalar columns (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent, content_hash — DX-2741, the card's optimistic-concurrency token; pass it back as `content_hash` on an `issue_edit` touching title/description/checklists); no joined collections. Pass `fields` to opt into named field-GROUPS, applied per card in the batch form too: description (full description body + the plain-language summary), solutions (the card's live candidate solutions, each with its content_hash, + every operator answer in decisions[]), ac (acceptance-criteria + checklists model), comments (comments[]), retro (retro good/bad/action_items/commits), dependencies (waiting_on/conflict_on/blocked gate state), triage (triage history + ICE), requires_human (the requires_human gate + steps), assignment (dispatch/assigned_agent/lifecycle timestamps), quality_gates (DX-1177 — one row per registered gate {gate, required, status pending|pass|fail, completed_at, message}; a required PRE gate not yet `pass` pre-empts the work dispatch, and `issue_transition complete` refuses while a required POST gate row != pass), children (child id list + rollups), mirrors (external mirror sync state), code_review_items (code-review findings). Point any heavy read at the matching `fields` entry rather than assuming it's already on the row. Single form: 404 envelope on unknown id. Batch form: returns `{issues: [...found cards...], not_found: [...ids that didn't resolve...]}` — an unknown or soft-deleted id never fails the whole call, it just lands in `not_found` alongside every card that DID resolve.", {
-    id: z.string().min(1).optional().describe("A single card id. Mutually exclusive with `ids`."),
-    ids: z
-        .array(z.string().min(1))
-        .min(1)
-        .max(ISSUE_BATCH_GET_MAX)
-        .optional()
-        .describe(`Batch form (DX-2727): every requested id (at most ${ISSUE_BATCH_GET_MAX}), resolved globally in ONE call. Mutually exclusive with \`id\`, and never combined with \`board\` (the batch is global; passing both throws). Reports not_found per id rather than failing the whole call.`),
+server.tool("issue_get", 
+// DX-2735: trimmed to pay for the problem tools inside the work-profile
+// injected-surface budget — same facts, no repeated prose.
+"Fetch one card (GET /api/issues/:id, `id`) or many (GET /api/issues/batch, `ids`, at most " + ISSUE_BATCH_GET_MAX + " — split larger sets); pass exactly one. Ids are globally unique, so both resolve from any board; the batch form is global and throws with `board`. THE DEFAULT ROW IS MINIMAL — scalars only (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent, content_hash: the concurrency token issue_edit needs for title/description/checklists). `fields` opts into groups, per card in a batch too: description (body + summary), problems (live problems in order, each {id, statement, content_hash, open} with its solutions[] and decisions[]), ac (acceptance criteria + checklists), comments, retro, dependencies (waiting_on/conflict_on/blocked), triage (history + ICE), requires_human (gate + steps), assignment (dispatch, assigned_agent, lifecycle timestamps), quality_gates (one row per gate {gate, required, status pending|pass|fail, completed_at, message}; a required PRE gate not `pass` pre-empts the work dispatch, and complete refuses while a required POST gate is not `pass`), children (ids + rollups), mirrors (external sync state), code_review_items. Single form: unknown id → 404. Batch form: `{issues: [...], not_found: [...ids]}` — an unknown or deleted id never fails the call.", {
+    id: z.string().min(1).optional(),
+    ids: z.array(z.string().min(1)).min(1).max(ISSUE_BATCH_GET_MAX).optional(),
     fields: z
         .array(z.enum(GET_FIELD_GROUPS))
         .optional()
-        .describe("Opt-in field-GROUPS to add to the minimal default row: description, solutions, ac, comments, retro, dependencies, triage, requires_human, assignment, quality_gates, children, mirrors, code_review_items. Absent/empty = minimal scalars only."),
+        .describe("Field groups to add; absent = minimal scalars."),
     ...boardField,
 }, async (args) => jsonResult(await issueGet(client, args)));
 // ---------------- issue_create ----------------
-server.tool("issue_create", 'Create a card via POST /api/issues on this dispatch\'s board, or another via `board` (`<repo>:<slug>`; unknown → 404). type=Epic REQUIRES non-empty phase_children[] (epic and phases inserted in one transaction; children get the epic as parent); other types refuse phase_children[] (400). Status starts at Review. `list_id` places the card straight into a column — a board_lists id or the list\'s display NAME (case-insensitive, emoji-tolerant): a `ready`-type queue lands it in ToDo, a `completed` list in Done, with no follow-up transition. Not valid on Epic; unknown name/id → 400. `gate_decisions` is REQUIRED when the board has an OPTIONAL quality gate for the card\'s type: a missing one fails closed with 400 `{error, required_gate_decisions:[...]}` naming each gate — retry with one `{gate, enabled, note}` per listed gate. ALWAYS pass `triage_enabled` explicitly on the root card and every phase child: true only when it should enter automatic triage/dispatch without human review; absent → false.', {
+server.tool("issue_create", 'Create a card via POST /api/issues. Board-scoped; see `board`. type=Epic REQUIRES non-empty phase_children[] (epic and phases inserted in one transaction; children get the epic as parent); other types refuse phase_children[] (400). Status starts at Review. `list_id` places the card straight into a column — a board_lists id or the list\'s display NAME (case-insensitive, emoji-tolerant): a `ready`-type queue lands it in ToDo, a `completed` list in Done, with no follow-up transition. Not valid on Epic; unknown name/id → 400. `gate_decisions` is REQUIRED when the board has an OPTIONAL quality gate for the card\'s type: a missing one fails closed with 400 `{error, required_gate_decisions:[...]}` naming each gate — retry with one `{gate, enabled, note}` per listed gate. ALWAYS pass `triage_enabled` explicitly on the root card and every phase child: true only when it should enter automatic triage/dispatch without human review; absent → false.', {
     type: z.enum(ISSUE_TYPES),
     title: z.string().min(1).describe(TITLE_DESCRIBE),
     summary: z.string().min(1).optional().describe(SUMMARY_DESCRIBE),
@@ -374,7 +376,7 @@ server.tool("issue_create", 'Create a card via POST /api/issues on this dispatch
     ...boardField,
 }, async (args) => jsonResult(await issueCreate(client, args, config.board)));
 // ---------------- issue_edit ----------------
-server.tool("issue_edit", 'Patch a card via PATCH /api/issues/:id/edit. ALLOWED keys: title, summary, description, ac, checklists, effort_level, parent_id, priority, list_id, triage_enabled, type, content_hash. Any other key (lifecycle, triage, dependencies, retro, requires_human, blocked) is refused 400 with offending_keys[] naming the right tool: issue_transition / issue_triage / issue_comment / issue_dependency / issue_requires_human / issue_retro. `type`: Story/Bug/Chore makes a card eligible for autonomous pickup; Task or a container (Epic/Feature) removes that eligibility — how a planning item becomes work. `priority` (a tier word or a number) is the ONLY way to set priority; a "Priority:" line in the description changes nothing. CHECKLISTS: each item has one status `incomplete|failing|passing|cancelled|deferred`; `deferred` (work done, a real-world/post-deploy check outstanding) REQUIRES `detail`, and a `📡`-prefixed item can never be `passing`. `ac` edits the default "Acceptance Criteria" checklist (items matched by check_item_id, else exact title); `checklists` REPLACES every named checklist with full status control (`{name, items:[{label, detail?, status}]}`). Send `ac` OR `checklists`, not both (400). `list_id` pins the card to a list by id or display NAME; its type must match the card\'s current derived status (400 otherwise — ready a card before pinning it to a `ready` queue); null clears the pin. `content_hash` (DX-2741) is the card\'s optimistic-concurrency token — REQUIRED (never optional/defaulted) whenever the edit touches `title` / `description` / `checklists` (NOT `ac`, which keeps its own check_item_id/title diffing): a missing hash on one of those fields 400s, a stale one 409s `stale_issue_content` carrying `currentHash` + `currentTitle` + `currentDescription`. Read it off `issue_get`/`issue_list`\'s `content_hash` scalar field (present even in the minimal response) immediately before editing; on a 409, re-`issue_get` and retry with the fresh hash — never blindly.', {
+server.tool("issue_edit", 'Patch a card via PATCH /api/issues/:id/edit. ALLOWED keys: title, summary, description, ac, checklists, effort_level, parent_id, priority, list_id, triage_enabled, type, content_hash. Any other key (lifecycle, triage, dependencies, retro, requires_human, blocked) is refused 400 with offending_keys[] naming the right tool: issue_transition / issue_triage / issue_comment / issue_dependency / issue_requires_human / issue_retro. `type`: Story/Bug/Chore = eligible for autonomous pickup; Task or a container (Epic/Feature) removes that eligibility — how a planning item becomes work. `priority` (a tier word or a number) is the ONLY way to set priority; a "Priority:" line in the description does nothing. CHECKLISTS: each item has one status `incomplete|failing|passing|cancelled|deferred`; `deferred` (work done, a real-world/post-deploy check outstanding) REQUIRES `detail`, and a `📡`-prefixed item can never be `passing`. `ac` edits the default "Acceptance Criteria" checklist (items matched by check_item_id, else exact title); `checklists` REPLACES every named checklist with full status control (`{name, items:[{label, detail?, status}]}`). Send `ac` OR `checklists`, not both (400). `list_id` pins the card to a list by id or display NAME; its type must match the card\'s current derived status (400 otherwise — e.g. ready the card first before pinning it to a `ready`-type list); null clears the pin. `content_hash` (DX-2741) is the card\'s optimistic-concurrency token — REQUIRED whenever the edit touches `title` / `description` / `checklists` (NOT `ac`, which keeps its own check_item_id/title diffing): missing → 400, stale → 409 `stale_issue_content` carrying `currentHash` + `currentTitle` + `currentDescription`. Read it off `issue_get`/`issue_list`\'s `content_hash` scalar (present even minimal); on 409, re-`issue_get` and retry with the fresh hash — never blindly.', {
     id: z.string().min(1),
     title: z.string().min(1).optional().describe(TITLE_DESCRIBE),
     summary: z
@@ -436,7 +438,9 @@ server.tool("issue_edit", 'Patch a card via PATCH /api/issues/:id/edit. ALLOWED
     ...boardField,
 }, async (args) => jsonResult(await issueEdit(client, args)));
 // ---------------- issue_transition ----------------
-server.tool("issue_transition", "Move a card's lifecycle via POST /api/issues/:id/transition — the ONLY way to; `danxbot_complete` never moves a card, so call this BEFORE it. Actions: ready (Review→ToDo); pickup (ToDo→In Progress; checks every dispatch gate — ready, blocked, requires_human, depends_on terminal, conflict_on idle — and refuses 409 with failed_gate naming the cause; `manual:true` is an operator-session self-pickup that bypasses card-flow gates and is never auto-rolled-back: use it when the work happens in YOUR session); rollback_pickup; complete (your explicit decision; refuses 409 on an Epic with non-terminal children, non_terminal_phases[], or while a required POST quality gate is not pass, failed_gate 'quality_gate_post' + failed_post_gates[]); cancel (terminal); block (non-empty reason; the CARD needs a human — env faults use `danxbot_complete({status:'failed'})` instead); unblock; archive (to Backlog, clears ready_at); reopen (terminal→active). Terminal cards refuse everything but reopen; forward stamps never clear earlier ones. Every path into In Progress needs an identified claimer: a dispatched agent's manual pickup MUST pass `assigned_agent` = your agent/profile name (409 otherwise). A manual pickup that loses a race is refused 409 `failed_gate: \"dispatch_id\"` — re-read the card's assigned_agent/dispatch_id, never retry blindly. A successful block returns `solutions_reminder: {solution_count, instruction}`: before stopping, list EVERY viable solution with issue_solution; zero means you listed none.", {
+server.tool("issue_transition", 
+// DX-2735: trimmed with the problem tools to stay inside the work-profile budget.
+"Move a card's lifecycle via POST /api/issues/:id/transition — the ONLY way; `danxbot_complete` never moves a card, so call this first. Actions: ready (Review→ToDo); pickup (ToDo→In Progress; checks every dispatch gate — ready, blocked, requires_human, depends_on terminal, conflict_on idle — and refuses 409 with failed_gate naming the cause; `manual:true` is a self-pickup for work in YOUR session: it bypasses card-flow gates and is never auto-rolled-back); rollback_pickup; complete (your explicit decision; 409 on an Epic with non-terminal children (non_terminal_phases[]) or while a required POST quality gate is not pass (failed_gate 'quality_gate_post' + failed_post_gates[])); cancel (terminal); block (non-empty reason; only holds dispatch, never asks a human — for that use issue_problem then issue_requires_human; env faults use `danxbot_complete({status:'failed'})`); unblock; archive (to Backlog, clears ready_at); reopen (terminal→active). Terminal cards refuse all but reopen; forward stamps never clear earlier ones. A dispatched agent's manual pickup MUST pass `assigned_agent` = your agent/profile name (409 otherwise); one that loses a race is refused 409 `failed_gate: \"dispatch_id\"` — re-read assigned_agent/dispatch_id, never retry blindly.", {
     id: z.string().min(1),
     action: z.enum(TRANSITION_ACTIONS),
     reason: z.string().optional(),
@@ -472,7 +476,7 @@ const CHECKLIST_ITEM_INPUT = z.object({
     detail: z.string().optional(),
     status: z.enum(CHECKLIST_ITEM_STATUSES).optional(),
 });
-server.tool("issue_checklist", "Targeted checklist CUD via /api/issues/:id/checklists[/:cid[/items[/:iid]]] (DX-1362). Mutates ONE checklist or item WITHOUT the wholesale `issue_edit({checklists})` replace — use this for the common case (flip an item's status, add/rename a checklist, add/edit/remove an item); the wholesale path silently DROPS any checklist you omit and churns every item id (orphaning its Trello mirror), so prefer this for single-item changes. Action-dispatched: add_list (POST :id/checklists {name, items?}) — create a named checklist, optionally with initial items; update_list (PATCH :id/checklists/:cid {name}) — rename; remove_list (DELETE :id/checklists/:cid) — soft-delete the checklist (audit trail preserved); add_item (POST :id/checklists/:cid/items {label, detail?, status?}) — append an item (status defaults `incomplete`); update_item (PATCH :id/checklists/:cid/items/:iid {label?, detail?, status?}) — change ONLY the fields you pass, in place (the item keeps its id + Trello linkage; at least one field required); remove_item (DELETE :id/checklists/:cid/items/:iid) — soft-delete one item. Status: incomplete|failing|passing|cancelled|deferred (terminal = passing|cancelled|deferred; DX-2653 added `deferred` — the honest disposition for a criterion whose work is done but names a real-world/post-deploy check still outstanding, REQUIRES a non-empty `detail`). checklist_id is required for every action except add_list; item_id for update_item/remove_item. Each returns the {ok,status,body} envelope; unknown card/checklist/item → 404, invalid status → 400. ADDITIVE — the wholesale `issue_edit({checklists})` path stays for bulk authoring.", {
+server.tool("issue_checklist", "Targeted checklist CUD via /api/issues/:id/checklists[/:cid[/items[/:iid]]] (DX-1362). Mutates ONE checklist/item without the wholesale `issue_edit({checklists})` replace, which DROPS any checklist you omit and churns every item id (orphaning its Trello mirror) — prefer this for single-item changes. Action-dispatched: add_list (POST :id/checklists {name, items?}) — create a named checklist, optionally with initial items; update_list (PATCH :id/checklists/:cid {name}) — rename; remove_list (DELETE :id/checklists/:cid) — soft-delete the checklist (audit trail preserved); add_item (POST :id/checklists/:cid/items {label, detail?, status?}) — append an item (status defaults `incomplete`); update_item (PATCH :id/checklists/:cid/items/:iid {label?, detail?, status?}) — change ONLY the fields you pass, in place (keeps id + Trello link; ≥1 field required); remove_item (DELETE :id/checklists/:cid/items/:iid) — soft-delete one item. Status: incomplete|failing|passing|cancelled|deferred (terminal = passing|cancelled|deferred; DX-2653 added `deferred` — the honest disposition for a criterion whose work is done but names a real-world/post-deploy check still outstanding, REQUIRES a non-empty `detail`). checklist_id is required for every action except add_list; item_id for update_item/remove_item. Each returns the {ok,status,body} envelope; unknown card/checklist/item → 404, invalid status → 400. ADDITIVE — `issue_edit({checklists})` still works for bulk authoring.", {
     id: z.string().min(1),
     action: z.enum([
         "add_list",
@@ -491,24 +495,37 @@ server.tool("issue_checklist", "Targeted checklist CUD via /api/issues/:id/check
     status: z.enum(CHECKLIST_ITEM_STATUSES).optional(),
     ...boardField,
 }, async (args) => jsonResult(await issueChecklist(client, args)));
-// ---------------- issue_solution ----------------
-server.tool("issue_solution", "A card's candidate SOLUTIONS — the options the operator picks from when a card is stopped for a human decision — via /api/issues/:id/solutions[/:sid]. Whenever you block a card or set requires_human, list EVERY viable solution here first, and mark the one you recommend. Action-dispatched: list (GET) — the live solutions (each with its `id` and `content_hash`) plus every operator answer recorded so far (`decisions[]`, oldest first); add (POST {title, body?, pro?, con?, recommended?}) — append one option; edit (PATCH :sid {base_hash, title?, body?, pro?, con?, recommended?}) — change ONLY the fields you pass; remove (DELETE :sid {base_hash}) — soft-remove an option. `title` is a short name for the option, `body` the markdown detail of what it actually does, `pro` / `con` the case for and against. HASH-GUARDED: edit and remove REQUIRE `base_hash` = the `content_hash` you last read; a stale one is refused 409 `stale_solution` carrying `currentHash` + `currentSolution` — merge against that and retry, never re-send blindly. A card recommends AT MOST ONE live solution: a second `recommended: true` is refused 409 naming `recommended_solution_id` (edit that one to recommended:false first). An option the operator has already CHOSEN cannot be edited (409) — add a new solution instead; it can still be removed, and the answer keeps its title. There is no answer action: the operator answers in the dashboard.", {
+// ---------------- issue_problem ----------------
+// DX-2735: the option fields, shared by `issue_problem` add's inline solutions[]
+// and `issue_solution`. Their meaning is stated ONCE, in issue_solution's
+// description — per-field describes repeated it on every call's context.
+const SOLUTION_FIELDS = {
+    body: z.string().optional(),
+    pro: z.string().optional(),
+    con: z.string().optional(),
+    recommended: z.boolean().optional(),
+};
+server.tool("issue_problem", "A card's PROBLEMS via /api/issues/:id/problems[/:pid]: one statement the operator must resolve (a question, or a flaw in the plan), each with its own solutions/answers — one problem per question. OPEN = not yet answered; the card needs a human until none is open, and issue_requires_human set is refused 409 `no_open_problem` until one is. list → live problems in order, each {id, statement, content_hash, open, solutions[], decisions[]}; add {statement, solutions?} → problem_id + solution_ids in one transaction (zero solutions is valid: the operator answers free-form); edit :pid {base_hash, statement}; remove :pid {base_hash} (409 `last_open_problem` while requires_human is set). A stale base_hash → 409 `stale_problem` with currentHash + currentProblem: merge, then retry. No answer action — the operator answers in the dashboard.", {
     id: z.string().min(1),
     action: z.enum(["list", "add", "edit", "remove"]),
-    solution_id: z.number().int().positive().optional().describe("Target solution id — required for edit / remove."),
-    base_hash: z
-        .string()
-        .min(1)
-        .optional()
-        .describe("The solution's content_hash from your last read — required for edit / remove."),
-    title: z.string().min(1).optional().describe("Short name for the option — required for add."),
-    body: z.string().optional().describe("Markdown detail of what this option actually does."),
-    pro: z.string().optional().describe("The case FOR this option."),
-    con: z.string().optional().describe("The case AGAINST this option."),
-    recommended: z
-        .boolean()
+    problem_id: z.number().int().positive().optional().describe("edit/remove"),
+    base_hash: z.string().min(1).optional().describe("content_hash last read; edit/remove"),
+    statement: z.string().min(1).optional().describe("add/edit"),
+    solutions: z
+        .array(z.object({ title: z.string().min(1), ...SOLUTION_FIELDS }))
         .optional()
-        .describe("true on the single option you recommend. At most one live recommended solution per card."),
+        .describe("add only; fields as issue_solution add"),
+    ...boardField,
+}, async (args) => jsonResult(await issueProblem(client, args)));
+// ---------------- issue_solution ----------------
+server.tool("issue_solution", "One problem's options via /api/issues/:id/problems/:pid/solutions[/:sid]; `problem_id` is REQUIRED (from issue_problem list/add; another problem's solution id → 404). add {title, body?, pro?, con?, recommended?}: title names the option, body is its markdown detail, pro/con the case for and against; edit :sid {base_hash, ...only the changed fields}; remove :sid {base_hash}. A stale base_hash → 409 `stale_solution` with currentHash + currentSolution: merge, then retry. At most ONE live recommended per problem: a second → 409 naming `recommended_solution_id`. A chosen option cannot be edited (409 — add a new one) but can be removed.", {
+    id: z.string().min(1),
+    action: z.enum(["add", "edit", "remove"]),
+    problem_id: z.number().int().positive(),
+    solution_id: z.number().int().positive().optional().describe("edit/remove"),
+    base_hash: z.string().min(1).optional().describe("content_hash last read; edit/remove"),
+    title: z.string().min(1).optional().describe("add"),
+    ...SOLUTION_FIELDS,
     ...boardField,
 }, async (args) => jsonResult(await issueSolution(client, args)));
 // ---------------- issue_dependency ----------------
@@ -522,7 +539,7 @@ server.tool("issue_dependency", 'Dependency CRUD via /api/issues/:id/dependencie
     ...boardField,
 }, async (args) => jsonResult(await issueDependency(client, args)));
 // ---------------- issue_requires_human ----------------
-server.tool("issue_requires_human", "Set or clear the requires_human dispatch gate via /api/issues/:id/requires-human. set=true → POST {reason, steps[]} — sets requires_human_reason (the dispatch gate per DX-704 — poller refuses pickup while non-null), set_by from bearer, set_at NOW(), REPLACES the step rows (prior soft-deleted, fresh ordinals). set=false → DELETE — clears the columns and soft-deletes every live step. Terminal cards refuse 409 on set. **A successful set=true returns a `solutions_reminder` beside the envelope** — `{solution_count, instruction}`: before you stop, EVERY viable solution to the question you are asking must be listed on the card with issue_solution, so the operator can answer by picking one. A count of zero means you have listed none.", {
+server.tool("issue_requires_human", "Set/clear the requires_human gate via /api/issues/:id/requires-human — the ONLY flag that puts a card in front of a human (block only holds dispatch). Escalate in order: 1) issue_problem add (statement + every viable solution, one recommended); 2) set=true {reason, steps[]} — refused 409 `no_open_problem` (with the server's `fix`) while no problem is open. Set stamps requires_human_reason (no pickup while non-null) and replaces the steps; it clears itself when the last open problem is answered. set=false → DELETE clears it and its steps. Terminal cards refuse 409. Success returns `problems_reminder: {open_problem_count, instruction}` naming each open problem's solution count.", {
     id: z.string().min(1),
     set: z.boolean(),
     reason: z.string().optional(),
@@ -530,7 +547,7 @@ server.tool("issue_requires_human", "Set or clear the requires_human dispatch ga
     ...boardField,
 }, async (args) => jsonResult(await issueRequiresHuman(client, args)));
 // ---------------- issue_quality_gate ----------------
-server.tool("issue_quality_gate", "Set one card's per-gate `required` flag via POST /api/issues/:id/quality-gates/:gate {required} — the only post-create way (issue_create takes gate_decisions; issue_edit refuses gate keys). PRE `plan-*` gates run before the work dispatch; POST `code-*` gates block complete. Unknown gate → 400. The board state per gate is tri-state: `required` always runs, `optional` runs WHEN this flag is true (optional is NOT off), `disabled` never runs. Optional `effort_level` overrides a `plan-*` gate's reviewer rung (null clears it). The write always succeeds and returns `{issue, applied: true, effective, reason}` — read `effective` (does the gate now run) and `reason` (why the board overrode your value), not just the 200. Pass `board` to target another board.", {
+server.tool("issue_quality_gate", "Set one card's per-gate `required` flag via POST /api/issues/:id/quality-gates/:gate {required} — the only post-create way (issue_create takes gate_decisions; issue_edit refuses gate keys). PRE `plan-*` gates run before the work dispatch; POST `code-*` gates block complete. Unknown gate → 400. The board state per gate is tri-state: `required` always runs, `optional` runs WHEN this flag is true (optional is NOT off), `disabled` never runs. Optional `effort_level` overrides a `plan-*` gate's reviewer rung (null clears it). The write always succeeds and returns `{issue, applied: true, effective, reason}` — read `effective` (does the gate now run) and `reason` (why the board overrode your value), not just the 200. Board-scoped; see `board`.", {
     id: z.string().min(1),
     gate: z.enum([
         "plan-dependency",
@@ -545,7 +562,7 @@ server.tool("issue_quality_gate", "Set one card's per-gate `required` flag via P
     ...boardField,
 }, async (args) => jsonResult(await issueQualityGate(client, args)));
 // ---------------- issue_quality_gate_verdict ----------------
-server.tool("issue_quality_gate_verdict", "Stamp an operator MANUAL quality-gate VERDICT via PATCH /api/issues/:id/quality-gates/:gate {status, message} — the same write the dashboard Gates-tab Pass / Fail / Revert controls perform (DX-1373). SIBLING of `issue_quality_gate`, not a replacement: that one flips the per-card `required` FLAG (does this gate run at all), THIS one records the VERDICT (did it pass) — the server exposes them as POST vs PATCH on the same resource and neither substitutes for the other. **Use this to close out a card you picked up with `issue_transition pickup {manual:true}`** (DX-946 operator-session self-pickup): `issue_transition complete` REFUSES 409 (`failed_gate: \"quality_gate_post\"`, `failed_post_gates[]`) while any required POST gate (`code-quality` / `code-test-quality` / `code-architecture`) is not `pass`, so without a verdict a manually-claimed card can never reach Done — it strands In Progress and its `conflict_on` / `waiting_on` edges then stall OTHER cards' dispatch. `status`: `pass` | `fail` | `pending` (revert a prior verdict, clears the message). `message` is the accountability record for the override and is REQUIRED at >= 20 characters for `pass`/`fail` (shorter → 400); it is ignored for `pending`. Record the REAL reviewer finding here, not a rubber stamp — this is a human-attributed override, stamped with the operator actor, and it is what a later reader sees instead of a reviewer dispatch. A manual verdict is a PURE row write: unlike the worker's in-dispatch gate route it fires NO side effects — a manual `fail` never blocks the card and a manual `pass` never releases a dispatch. Unknown gate → 400; status outside the three values → 400; unknown card → 404. Board-scoped; pass `board` (`<repo>:<slug>`) to target another board.", {
+server.tool("issue_quality_gate_verdict", "Stamp an operator MANUAL quality-gate VERDICT via PATCH /api/issues/:id/quality-gates/:gate {status, message} — the same write the dashboard Gates-tab Pass / Fail / Revert controls perform (DX-1373). SIBLING of `issue_quality_gate`, not a replacement: that one flips the per-card `required` FLAG (does this gate run at all), THIS one records the VERDICT (did it pass) — POST vs PATCH on the same resource, neither substitutes for the other. **Use this to close out a card you picked up with `issue_transition pickup {manual:true}`** (DX-946 operator-session self-pickup): `issue_transition complete` REFUSES 409 (`failed_gate: \"quality_gate_post\"`, `failed_post_gates[]`) while any required POST gate (`code-quality` / `code-test-quality` / `code-architecture`) is not `pass`, so without a verdict a manually-claimed card can never reach Done — it strands In Progress and its `conflict_on` / `waiting_on` edges then stall OTHER cards' dispatch. `status`: `pass` | `fail` | `pending` (revert a prior verdict, clears the message). `message` is the accountability record for the override, REQUIRED at >= 20 characters for `pass`/`fail` (shorter → 400), ignored for `pending`. Record the REAL reviewer finding, not a rubber stamp — a human-attributed override, stamped with the operator actor, standing in for a reviewer dispatch. A manual verdict is a PURE row write: no side effects — a manual `fail` never blocks the card and a manual `pass` never releases a dispatch. Unknown gate → 400; bad status → 400; unknown card → 404. Board-scoped; see `board`.", {
     id: z.string().min(1),
     gate: z.enum([
         "plan-dependency",
@@ -560,7 +577,7 @@ server.tool("issue_quality_gate_verdict", "Stamp an operator MANUAL quality-gate
     ...boardField,
 }, async (args) => jsonResult(await issueQualityGateVerdict(client, args)));
 // ---------------- issue_retro ----------------
-server.tool("issue_retro", "Replace the retro block via PUT /api/issues/:id/retro. Body: {good, bad, action_item_ids[], commits[], tests[]}. REFUSES 409 unless the card is terminal (completed_at OR cancelled_at) — retro ships when work concludes. Replace semantics: good/bad upsert; action_item_ids[] + commits[] + tests[] soft-delete prior live rows and insert with fresh ordinals. action_item_ids[] entries MUST match <PREFIX>-N. commits[] entries take {sha, subject?}. tests[] (DX-1646) is REQUIRED (empty array allowed — the \"ran no tests\" case): one row per test GROUP that ran (a whole suite/class — name the group, do NOT list individual unit tests) or per individual e2e test (kind:'e2e', listed explicitly since they are few + expensive). Each row: {name, kind:'group'|'e2e', num_tests, num_passing_tests, duration_ms} required; num_assertions + num_passing_assertions NULLABLE (vitest surfaces no assertion totals — pass null or omit).", {
+server.tool("issue_retro", "Replace the retro block via PUT /api/issues/:id/retro. Body: {good, bad, action_item_ids[], commits[], tests[]}. REFUSES 409 unless the card is terminal (completed_at OR cancelled_at) — retro ships when work concludes. Replace semantics: good/bad upsert; action_item_ids[] + commits[] + tests[] soft-delete prior live rows and insert with fresh ordinals. action_item_ids[] entries MUST match <PREFIX>-N. commits[] entries take {sha, subject?}. tests[] (DX-1646) is REQUIRED (empty array allowed — the \"ran no tests\" case): one row per test GROUP that ran (a whole suite/class — name the group, do NOT list individual unit tests) or per individual e2e test (kind:'e2e', few + expensive so listed explicitly). Each row: {name, kind:'group'|'e2e', num_tests, num_passing_tests, duration_ms} required; num_assertions + num_passing_assertions NULLABLE (vitest has no assertion totals — pass null or omit).", {
     id: z.string().min(1),
     good: z.string(),
     bad: z.string(),
@@ -590,7 +607,7 @@ server.tool("issue_retro", "Replace the retro block via PUT /api/issues/:id/retr
 // route's MAX_DECODED_BYTES (src/issues/write/attachments.ts). This package is
 // a separate published artifact and cannot import that constant, so the number
 // is restated here as prose — keep the two in sync if the backend ceiling moves.
-server.tool("issue_attach", "Attach a LOCAL file to an issue card via POST /api/issues/:id/attachments. Pass `id` (the card) and `file_path` (an ABSOLUTE path to a file on the dispatch's shared filesystem — e.g. a screenshot, exported CSV, or diagram you wrote). This MCP server reads the bytes, infers the MIME type from the extension, and uploads through the dashboard, which: stores the bytes in S3, inserts ONE danxbot-origin issue_attachments row, and auto-mirrors the file to the card's linked Trello card AND its Slack card-view thread (DX-1122 outbound projection) — no extra step needed. Board-scoped; defaults to the dispatch's board. Pass `board` (a qualified id `<repo>:<slug>`) to attach on another board (unknown board → 404). Fail-loud: a relative/empty path is rejected at the MCP boundary, and a missing/unreadable file throws BEFORE any upload (no partial S3 object, no row). 25 MB decoded ceiling (413). Returns the hydrated issue plus the new attachment id.", {
+server.tool("issue_attach", "Attach a LOCAL file to an issue card via POST /api/issues/:id/attachments. Pass `id` (the card) and `file_path` (an ABSOLUTE path to a file on the dispatch's shared filesystem — e.g. a screenshot, exported CSV, or diagram you wrote). This MCP server reads the bytes, infers the MIME type from the extension, and uploads through the dashboard, which: stores the bytes in S3, inserts ONE danxbot-origin issue_attachments row, and auto-mirrors the file to the card's linked Trello card AND its Slack card-view thread (DX-1122 outbound projection) — no extra step needed. Board-scoped; see `board`. Fail-loud: a relative/empty path is rejected at the MCP boundary, and a missing/unreadable file throws BEFORE any upload (no partial S3 object, no row). 25 MB decoded ceiling (413). Returns the hydrated issue plus the new attachment id.", {
     id: z.string().min(1),
     file_path: z
         .string()
@@ -599,11 +616,11 @@ server.tool("issue_attach", "Attach a LOCAL file to an issue card via POST /api/
     ...boardField,
 }, async (args) => jsonResult(await issueAttach(client, args)));
 // ---------------- repo_knowledge_get ----------------
-server.tool("repo_knowledge_get", "Fetch the board's working-knowledge markdown doc via GET /api/repo-knowledge (DX-1128, Story 2). Board-scoped; defaults to the dispatch's board. Pass `board` (a qualified id `<repo>:<slug>`) to read another board's doc. Returns `{ok, status, body: {content, contentHash, updatedAt, updatedBy, boardId}}` — an unset doc reads as the empty view (`content: \"\"`, `contentHash: \"\"`), NOT a 404. Ground exploratory answers in `content`; before `repo_knowledge_set`, ALWAYS `repo_knowledge_get` immediately first and pass its `contentHash` back as `base_hash` — the server's optimistic-concurrency guard rejects a stale write.", {
+server.tool("repo_knowledge_get", "Fetch the board's working-knowledge markdown doc via GET /api/repo-knowledge (DX-1128, Story 2). Board-scoped; see `board`. Returns `{ok, status, body: {content, contentHash, updatedAt, updatedBy, boardId}}` — an unset doc reads as the empty view (`content: \"\"`, `contentHash: \"\"`), NOT a 404. Ground exploratory answers in `content`; before `repo_knowledge_set`, ALWAYS `repo_knowledge_get` immediately first and pass its `contentHash` back as `base_hash` — the server's optimistic-concurrency guard rejects a stale write.", {
     ...boardField,
 }, async (args) => jsonResult(await repoKnowledgeGet(client, args)));
 // ---------------- repo_knowledge_set ----------------
-server.tool("repo_knowledge_set", 'Write the board\'s working-knowledge markdown doc via PUT /api/repo-knowledge (DX-1128, Story 2). Board-scoped; defaults to the dispatch\'s board. `base_hash` MUST be the `contentHash` from the immediately-prior `repo_knowledge_get` call ("" for the true first write, when the board has no doc yet) — the server compares it against the CURRENT hash and, on mismatch, fails loud with `{ok: false, body: {error: "stale_repo_knowledge", currentHash}}` rather than silently overwriting a concurrent write. On that refusal: re-`repo_knowledge_get`, re-merge your insight into the fresh content, and retry `repo_knowledge_set` with the new hash. On success, persists to the DB, publishes `repo-knowledge:updated` over SSE (live in the dashboard editor), and returns the new view.', {
+server.tool("repo_knowledge_set", 'Write the board\'s working-knowledge markdown doc via PUT /api/repo-knowledge (DX-1128, Story 2). Board-scoped; see `board`. `base_hash` MUST be the `contentHash` from the immediately-prior `repo_knowledge_get` call ("" for the true first write, when the board has no doc yet) — the server compares it against the CURRENT hash and, on mismatch, fails loud with `{ok: false, body: {error: "stale_repo_knowledge", currentHash}}` rather than silently overwriting a concurrent write. On that refusal: re-`repo_knowledge_get`, re-merge your insight into the fresh content, and retry `repo_knowledge_set` with the new hash. On success, persists to the DB, publishes `repo-knowledge:updated` over SSE (live in the dashboard editor), and returns the new view.', {
     content: z.string(),
     base_hash: z
         .string()
@@ -612,11 +629,11 @@ server.tool("repo_knowledge_set", 'Write the board\'s working-knowledge markdown
     ...boardField,
 }, async (args) => jsonResult(await repoKnowledgeSet(client, args)));
 // ---------------- brief_list ----------------
-server.tool("brief_list", "List the board's named Brief pages via GET /api/brief (DX-2083 / DX-2484). Board-scoped; defaults to the dispatch's board. Pass `board` (a qualified id `<repo>:<slug>`) to list another board's pages. Returns `{boardId, pages: [{slug, title, contentHash, sortOrder, updatedAt, updatedBy}]}` — metadata only, no page content (use `brief_get_page` for that). This is the list+page-shaped sibling of `repo_knowledge_get`/`repo_knowledge_set` (one board-level doc) — Brief pages are MANY named pages per board (the Goals / Architecture / Rules / Caveats tabs), keyed by `(board, slug)`. The reserved `index` slug always exists — every board carries exactly one.", {
+server.tool("brief_list", "List the board's named Brief pages via GET /api/brief (DX-2083 / DX-2484). Board-scoped; see `board`. Returns `{boardId, pages: [{slug, title, contentHash, sortOrder, updatedAt, updatedBy}]}` — metadata only, no page content (use `brief_get_page` for that). This is the list+page-shaped sibling of `repo_knowledge_get`/`repo_knowledge_set` (one board-level doc) — Brief pages are MANY named pages per board (the Goals / Architecture / Rules / Caveats tabs), keyed by `(board, slug)`. The reserved `index` slug always exists — every board carries exactly one.", {
     ...boardField,
 }, async (args) => jsonResult(await briefList(client, args)));
 // ---------------- brief_get_page ----------------
-server.tool("brief_get_page", 'Fetch one Brief page by slug via GET /api/brief/page?slug=<slug> (DX-2083 / DX-2484). Board-scoped; defaults to the dispatch\'s board. Returns `{boardId, slug, title, content, contentHash, sortOrder, updatedAt, updatedBy}` — a missing/not-yet-created page reads as the empty view (`content: ""`, `contentHash: ""`), NOT a 404, matching `repo_knowledge_get`\'s convention. Before `brief_set_page`, ALWAYS `brief_get_page` immediately first and pass its `contentHash` back as `base_hash` — the server\'s optimistic-concurrency guard rejects a stale write.', {
+server.tool("brief_get_page", 'Fetch one Brief page by slug via GET /api/brief/page?slug=<slug> (DX-2083 / DX-2484). Board-scoped; see `board`. Returns `{boardId, slug, title, content, contentHash, sortOrder, updatedAt, updatedBy}` — a missing/not-yet-created page reads as the empty view (`content: ""`, `contentHash: ""`), NOT a 404, matching `repo_knowledge_get`\'s convention. Before `brief_set_page`, ALWAYS `brief_get_page` immediately first and pass its `contentHash` back as `base_hash` — the server\'s optimistic-concurrency guard rejects a stale write.', {
     slug: z
         .string()
         .min(1)
@@ -624,7 +641,7 @@ server.tool("brief_get_page", 'Fetch one Brief page by slug via GET /api/brief/p
     ...boardField,
 }, async (args) => jsonResult(await briefGetPage(client, args)));
 // ---------------- brief_set_page ----------------
-server.tool("brief_set_page", 'Write one Brief page via PUT /api/brief/page?slug=<slug> (DX-2083 / DX-2484). Board-scoped; defaults to the dispatch\'s board. Body: `{content, title?, sortOrder?, base_hash?}` — mirrors `repo_knowledge_set`\'s optimistic-concurrency shape but targets one named page instead of the board\'s single working-knowledge doc. `base_hash` MUST be the `contentHash` from the immediately-prior `brief_get_page` call ("" for a true first write, when the page doesn\'t exist yet) — the server compares it against the CURRENT hash and, on mismatch, fails loud with `{ok: false, body: {error: "stale_brief_page", currentHash}}` rather than silently overwriting a concurrent write — re-get, re-merge, and retry on that refusal, never retry blindly or overwrite. On success, persists to the DB, publishes `brief:updated` over SSE, and returns the new view. NO delete tool is exposed on this surface — the reserved `index` slug can never be deleted through the tool surface, matching the route\'s own refusal; deleting a non-index page is dashboard-UI-only for now.', {
+server.tool("brief_set_page", 'Write one Brief page via PUT /api/brief/page?slug=<slug> (DX-2083 / DX-2484). Board-scoped; see `board`. Body: `{content, title?, sortOrder?, base_hash?}` — mirrors `repo_knowledge_set`\'s optimistic-concurrency shape but targets one named page instead of the board\'s single working-knowledge doc. `base_hash` MUST be the `contentHash` from the immediately-prior `brief_get_page` call ("" for a true first write, when the page doesn\'t exist yet) — the server compares it against the CURRENT hash and, on mismatch, fails loud with `{ok: false, body: {error: "stale_brief_page", currentHash}}` rather than silently overwriting a concurrent write — re-get, re-merge, and retry on that refusal, never retry blindly or overwrite. On success, persists to the DB, publishes `brief:updated` over SSE, and returns the new view. NO delete tool is exposed on this surface — the reserved `index` slug can never be deleted through the tool surface, matching the route\'s own refusal; deleting a non-index page is dashboard-UI-only for now.', {
     slug: z
         .string()
         .min(1)
@@ -649,7 +666,7 @@ server.tool("brief_set_page", 'Write one Brief page via PUT /api/brief/page?slug
 // also takes no plan id, but for a different reason: it MAKES a plan rather
 // than acting on one, so there is no existing plan for an id to name yet.
 server.tool("plan_list", "List every plan via GET /api/plans (DX-2683), and learn which plan THIS session is connected to. Plans are GLOBAL, not board-scoped: a plan is a named, dated set of cards an operator assembled by hand, and its cards may come from any repository. Returns `{ok, status, body: {plans: [{id, name, createdAt, cardCount, boards}], session, sessionListenerAttached}}`. `session` is your own registration — `{sessionId, title, planId, planName, firstSeenAt, lastActiveAt}` — or `null` if this process is not running inside a Claude Code session. A `planId` of null means you are connected to no plan: read any plan with `plan_get`, then `plan_connect` to the one you are working on (or ask the operator to connect you from the Plans list). `sessionListenerAttached` says whether your event listener is running: `false` while connected to a plan means you will NOT hear about its cards — call `plan_connect` again and arm the Monitor it returns. NOTE this is NOT the board Brief (`brief_list`), which is a different feature entirely.", {}, async () => jsonResult(await planList(client)));
-server.tool("plan_get", "Read a plan via GET /api/plans (DX-2683). Pass `plan_id` to read ANY plan (browsing another plan is useful and changes nothing); OMIT it to read the plan this session is connected to. Omitting it while connected to no plan fails loud with `{error: \"session_not_connected\"}` — connect first. A BARE call (no `fields`) returns ONLY the plan's cheap scalars: `{plan, boards, cardCount, bucketCounts, session, sessionListenerAttached, available_field_groups}` — no member cards, no goals/rules/caveats, no architecture body. Pass `fields` to opt into the rest, one call at a time: `cards` (member cards, PAGED: `cards_offset` (default 0) and `cards_limit` (1.." + LIST_PAGE_MAX_LIMIT + ", default " + PLAN_GET_CARDS_DEFAULT_LIMIT + ") pick the page, in card-reference order (board prefix, then card number — stable while cards are edited, so pages never repeat or skip a card unless the plan's membership changes between reads), and the response carries `cards_total` and `cards_offset` — page with cards_offset while cards_offset + cards.length < cards_total; either paging arg without `fields: [\"cards\"]` is a 400), `records` (every goal+rule+caveat, keyed by kind) or `records:goal` / `records:rule` / `records:caveat` (just that one kind — cheaper than the full union), `architecture` (`{sections: [{id, planId, contentHash, title, content, sortOrder, createdAt, updatedAt}]}`), `sessions` (every session connected to the plan). `session`/`sessionListenerAttached` (your own connection state) and `available_field_groups` ride EVERY response, gated or not. `sessionListenerAttached: false` while connected means your event listener is not running; call `plan_connect` again and arm the Monitor it returns. ALWAYS `plan_get`/`plan_get_architecture_section` immediately before `plan_update_architecture_section`/`plan_delete_architecture_section` and pass the returned `contentHash` back as `base_hash`.", {
+server.tool("plan_get", "Read a plan via GET /api/plans (DX-2683). Pass `plan_id` to read ANY plan; OMIT to read the plan this session is connected to — omitting while connected to none fails loud `{error: \"session_not_connected\"}`, connect first. A BARE call (no `fields`) returns ONLY the plan's cheap scalars: `{plan, boards, cardCount, bucketCounts, session, sessionListenerAttached, available_field_groups}` — no cards, records, or architecture body. Pass `fields` to opt into: `cards` (member cards, PAGED: `cards_offset` (default 0) and `cards_limit` (1.." + LIST_PAGE_MAX_LIMIT + ", default " + PLAN_GET_CARDS_DEFAULT_LIMIT + ") pick the page, in stable card-reference order (board prefix, then card number — pages never repeat/skip unless membership changes between reads); response carries `cards_total`/`cards_offset` — page while cards_offset + cards.length < cards_total; either paging arg without `fields: [\"cards\"]` is a 400), `records` (every goal+rule+caveat, keyed by kind) or `records:goal` / `records:rule` / `records:caveat` (one kind, cheaper), `architecture` (`{sections: [{id, planId, contentHash, title, content, sortOrder, createdAt, updatedAt}]}`), `sessions` (every session connected to the plan). `session`/`sessionListenerAttached` and `available_field_groups` ride every response regardless. `sessionListenerAttached: false` while connected means your event listener is not running; call `plan_connect` again and arm the Monitor it returns. ALWAYS `plan_get`/`plan_get_architecture_section` immediately before `plan_update_architecture_section`/`plan_delete_architecture_section` and pass the returned `contentHash` back as `base_hash`.", {
     plan_id: z
         .number()
         .int()
@@ -677,7 +694,9 @@ server.tool("plan_get", "Read a plan via GET /api/plans (DX-2683). Pass `plan_id
 server.tool("plan_create", "Create a new, empty plan via POST /api/plans (DX-2531). GLOBAL — a plan is not board-scoped, and this call adds no cards, no records, and no architecture sections; it does NOT connect any session to the new plan (call `plan_connect` separately, exactly as adding a card to a plan is its own separate step). Returns `{ok, status, body: {plan: {id, name, createdAt}}}`. Use the returned `plan.id` with `plan_connect` to start working on it, or with `plan_get({plan_id})` to browse it.", {
     name: z.string().min(1).describe("The plan's name — shown in the Plans list."),
 }, async (args) => jsonResult(await planCreate(client, args)));
-server.tool("plan_connect", "Connect THIS session to a plan via POST /api/plan-sessions/me/plan (DX-2683) — the same binding the operator's Connect action writes, through the same server-side path. A session is connected to AT MOST ONE plan (enforced by the schema, not by convention); connecting while already on another plan MOVES you, and the response says which plan you left: `{ok, status, body: {session, movedFrom: {id, name} | null}}`. `movedFrom: null` means you were on no plan, or already on this one. It can only ever bind your OWN session — `me` is resolved from the session id this server forwards, never from anything you pass. After this, every plan WRITE tool acts on this plan, and no plan id is accepted anywhere. THE REPLY ALSO CARRIES `listener: {command, persistent: true, instruction}` — arm it IMMEDIATELY with the Monitor tool (`command` as given, `persistent: true`): from then on every comment, answer, requires_human change and block/unblock on this plan's cards arrives as a notification line like `[DX-8 \"Title\" repo:board] newms87 answered: chose \"Pause E2E\" — note: \"…\"`. Never poll for these. The command carries a narrow stream ticket, not a credential; calling plan_connect again (same plan is fine) issues a new one and ends the old listener, which is how you re-arm after a session restart or after the Monitor reports it gave up. If the ticket cannot be issued the call fails with `listener_not_armed` even though the connect itself happened.", {
+server.tool("plan_connect", 
+// DX-2735: trimmed with the problem tools to stay inside the work-profile budget.
+"Connect THIS session to a plan via POST /api/plan-sessions/me/plan — the same binding the operator's Connect action writes. A session is on AT MOST ONE plan: connecting elsewhere MOVES it, and the reply says which plan it left: `{session, movedFrom: {id, name} | null}` (null = no plan, or already this one). It binds only your OWN session, resolved from the session id this server forwards. Afterwards every plan WRITE tool acts on this plan and takes no plan id. THE REPLY ALSO CARRIES `listener: {command, persistent: true, instruction}` — arm it IMMEDIATELY with the Monitor tool (`persistent: true`): every comment, answer, requires_human change and block/unblock on this plan's cards then arrives as a line like `[DX-8 \"Title\" repo:board] newms87 answered \"<problem statement>\": chose \"Pause E2E\" — note: \"…\"`. Never poll for these. The command holds a narrow stream ticket, not a credential; calling plan_connect again (same plan is fine) issues a new one and ends the old listener — how you re-arm after a restart or a give-up. If no ticket can be issued the call fails `listener_not_armed`, though the connect happened.", {
     plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
 }, async (args) => jsonResult(await planConnect(client, args, { baseUrl: config.baseUrl, packageSpec: PACKAGE_SPEC })));
 server.tool("plan_add_record", "Add a goal, rule or caveat to your connected plan (POST /api/plans/mine/records). A GOAL is an outcome the work is measured against. A RULE is a constraint that must hold while it is worked. A CAVEAT is a lasting trade-off or limitation of the ARCHITECTURE — never progress, status or a session note (those are comments on the card). `body` is ONE plain statement of at most 250 characters; the evidence, history and detail go in `context` (markdown). An overlong body is refused with a 400 naming its length. The server allocates a permanent reference (`G-1`, `R-4`, `CAV-12`). Takes no plan id; `session_not_connected` → `plan_connect` first. Returns the record plus that kind's list.", {

package/dist/listen.js

@@ -33,6 +33,7 @@
  * (`src/issues/db/issue-activity.ts`); this published package cannot import
  * danxbot source.
  */
+import { oneLine } from "./one-line.js";
 export const LISTEN_SUBCOMMAND = "listen";
 export const INITIAL_BACKOFF_MS = 1_000;
 export const MAX_BACKOFF_MS = 30_000;
@@ -66,17 +67,71 @@ export function parseListenArgs(argv) {
 function quoted(value) {
     return `"${value.text}${value.truncated ? "…" : ""}"`;
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isCappedText(value) {
+    return isRecord(value) && typeof value.text === "string" && typeof value.truncated === "boolean";
+}
+/**
+ * DX-2735 — why an event cannot be described, or `null` when it can.
+ *
+ * Checked BEFORE describing, so a malformed event is reported by what is
+ * actually wrong with it — never by whichever TypeError a missing field happens
+ * to raise (whose wording is the JS engine's, not ours). The envelope is checked
+ * for every kind; the detail only for the kinds `describe` reads, so a kind newer
+ * than this listener still produces its generic line.
+ */
+export function invalidEventReason(value) {
+    if (!isRecord(value))
+        return "the event is not an object";
+    if (typeof value.id !== "number" || !Number.isSafeInteger(value.id))
+        return "id is not an integer";
+    for (const field of ["cardId", "cardTitle", "boardId", "actor", "kind"]) {
+        if (typeof value[field] !== "string")
+            return `${field} is not a string`;
+    }
+    const d = value.detail;
+    if (!isRecord(d))
+        return "detail is not an object";
+    switch (value.kind) {
+        case "comment_added":
+            return isCappedText(d.excerpt) ? null : "detail.excerpt is not capped text";
+        case "solution_answered": {
+            const problem = d.problem;
+            if (!isRecord(problem) || typeof problem.id !== "number" || !isCappedText(problem.statement)) {
+                return "detail.problem is not {id, statement}";
+            }
+            if (d.solution === null)
+                return isCappedText(d.freeform) ? null : "detail.freeform is not capped text";
+            if (!isRecord(d.solution) || typeof d.solution.title !== "string")
+                return "detail.solution is not {title, note}";
+            return d.solution.note === null || isCappedText(d.solution.note) ? null : "detail.solution.note is not capped text";
+        }
+        case "requires_human_set":
+        case "blocked":
+            return isCappedText(d.reason) ? null : "detail.reason is not capped text";
+        default:
+            return null;
+    }
+}
+/** Only ever called on an event `invalidEventReason` accepted, so its casts are checked. */
 function describe(event) {
     const d = event.detail;
     switch (event.kind) {
         case "comment_added":
             return `${event.actor} commented: ${quoted(d.excerpt)}`;
         case "solution_answered": {
+            // DX-2735: every answer answers ONE problem on a card that may carry several,
+            // so the line names the problem — otherwise the agent cannot tell which of its
+            // questions just closed.
+            const problem = d.problem;
+            const answered = `${event.actor} answered ${quoted(problem.statement)}:`;
             const solution = d.solution;
             if (solution === null)
-                return `${event.actor} answered: ${quoted(d.freeform)}`;
+                return `${answered} ${quoted(d.freeform)}`;
             const note = solution.note === null ? "" : ` — note: ${quoted(solution.note)}`;
-            return `${event.actor} answered: chose "${solution.title}"${note}`;
+            return `${answered} chose "${solution.title}"${note}`;
         }
         case "requires_human_set":
             return `${event.actor} set requires_human: ${quoted(d.reason)}`;
@@ -92,9 +147,12 @@ function describe(event) {
             return `${event.actor}: ${event.kind}`;
     }
 }
-/** The one notification line for an event. Always a single line; throws on a malformed event. */
+/** The one notification line for an event. Always a single line; throws, naming the fault, on a malformed event. */
 export function formatActivityLine(event) {
-    return `[${event.cardId} "${event.cardTitle}" ${event.boardId}] ${describe(event)}`.replace(/\s+/g, " ");
+    const invalid = invalidEventReason(event);
+    if (invalid !== null)
+        throw new Error(`malformed activity event: ${invalid}`);
+    return oneLine(`[${event.cardId} "${event.cardTitle}" ${event.boardId}] ${describe(event)}`);
 }
 /**
  * Incremental SSE parser. Comment lines (keep-alives, the connect marker) and
@@ -165,14 +223,27 @@ export async function runListener(options, deps) {
         const id = Number(message.id);
         if (Number.isSafeInteger(id) && printed.has(id))
             return null;
+        // DX-2735: an event that is not JSON, or JSON of the wrong shape, is reported
+        // from an explicit check naming the fault — never from a TypeError thrown
+        // partway through describing it. Never silence, and never a reconnect loop on
+        // the same bad event: say so in one line and move past it.
+        let parsed;
+        let invalid;
         try {
-            deps.write(formatActivityLine(JSON.parse(message.data)));
+            parsed = JSON.parse(message.data);
+            invalid = invalidEventReason(parsed);
         }
         catch (err) {
-            // Never silence, and never a reconnect loop on the same bad event: say so
-            // in one line and move past it.
-            deps.write(`${LINE_PREFIX} could not read event ${message.id ?? "(no id)"} (${err.message}): ` +
-                `${message.data.slice(0, 300)}`.replace(/\s+/g, " "));
+            invalid = `not JSON: ${err.message}`;
+        }
+        if (invalid === null) {
+            deps.write(formatActivityLine(parsed));
+        }
+        else {
+            deps.write(`${LINE_PREFIX} could not read event ${message.id ?? "(no id)"} (${invalid}): ` +
+                // DX-2735: oneLine caps by code point, so a bad event carrying an emoji
+                // at the cut can never leave a lone surrogate in the line.
+                oneLine(message.data, 300));
         }
         if (Number.isSafeInteger(id))
             remember(id);
@@ -198,7 +269,7 @@ export async function runListener(options, deps) {
             armIdle();
             const response = await deps.fetch(options.streamUrl, { headers, signal: controller.signal });
             if (response.status >= 400 && response.status < 500 && !RETRYABLE_CLIENT_STATUSES.has(response.status)) {
-                return { kind: "refused", detail: `HTTP ${response.status} ${(await response.text()).slice(0, 300)}` };
+                return { kind: "refused", detail: `HTTP ${response.status} ${oneLine(await response.text(), 300)}` };
             }
             if (!response.ok || response.body === null) {
                 await response.body?.cancel();

package/dist/one-line.js

@@ -0,0 +1,18 @@
+/**
+ * DX-2735 — the ONE way this package renders human text into an agent-facing
+ * line: the listen notification line and the requires_human problems reminder
+ * both go through it, so they can never disagree about how a statement looks.
+ *
+ * Every whitespace run (newlines included) collapses to a single space, because
+ * a notification is one line and a reminder quotes statements inline. The
+ * optional cap counts CODE POINTS, never UTF-16 units: `String#slice` can cut
+ * an emoji or any astral character in half and leave a lone surrogate, which
+ * renders as garbage. A capped string ends with "…" so truncation is visible.
+ */
+export function oneLine(text, maxCodePoints) {
+    const collapsed = text.replace(/\s+/g, " ");
+    if (maxCodePoints === undefined)
+        return collapsed;
+    const points = Array.from(collapsed);
+    return points.length > maxCodePoints ? `${points.slice(0, maxCodePoints).join("")}…` : collapsed;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.63",
+  "version": "0.1.65",
   "description": "Stdio MCP server wrapping danxbot's dashboard /api/issues/* normalized DB-backed HTTP routes for dispatched agents (DX-704 Phase 2).",
   "license": "MIT",
   "type": "module",