@thehammer/danx-dashboard-mcp 0.1.131 → 0.1.132

package/dist/handlers.js

@@ -413,6 +413,39 @@ function argCheckers(tool, mode) {
         },
     };
 }
+/**
+ * Every action-dispatched tool's args carry these three regardless of
+ * `action` — never action-specific, so every per-action allow-list passed to
+ * `refuseInapplicableFields` is unioned with this rather than repeating it.
+ */
+const STRUCTURAL_ACTION_FIELDS = ["id", "action", "board"];
+/**
+ * DX-3310 (code-review nit) — a field the caller sent that means nothing for
+ * the chosen `action` used to be silently ignored: `issue_solution`'s `add`
+ * built its `content` object from `title`/`body`/`pro`/`con`/`recommended`
+ * regardless of action, then simply never read it on `remove`/`add_step`/etc,
+ * and `issue_problem`'s `remove` never looked at `statement`/`context`/
+ * `solutions` at all. Either way the caller got a 200 with the field quietly
+ * discarded — no different from a typo. Refused loud instead, mirroring
+ * `argCheckers`' own wording: every ACTUALLY-SUPPLIED (`!== undefined`) key
+ * outside the action's own allow-list (plus `STRUCTURAL_ACTION_FIELDS`,
+ * always allowed) is named in one error, so a caller fixes every offending
+ * field in one round trip rather than one at a time.
+ */
+// A9 (code-review fix) — takes `object` rather than `Record<string, unknown>`
+// so every caller (each with its own specific `*Args` interface, no index
+// signature) passes `args` directly, with no `as unknown as Record<...>`
+// bridge cast at the call site. `Object.entries` reads the key/value pairs
+// without needing an index signature on the input type either.
+function refuseInapplicableFields(tool, mode, args, allowed) {
+    const offending = Object.entries(args)
+        .filter(([key, value]) => value !== undefined && !STRUCTURAL_ACTION_FIELDS.includes(key) && !allowed.has(key))
+        .map(([key]) => key)
+        .sort();
+    if (offending.length > 0) {
+        throw new Error(`${tool} ${mode} refuses fields that do not apply to this action: ${offending.join(", ")}`);
+    }
+}
 export async function issueComment(client, args) {
     const idEnc = encodeURIComponent(args.id);
     const board = args.board;
@@ -614,10 +647,25 @@ export async function issueChecklist(client, args) {
  *
  * No answer action, for the reason `issueSolution` gives.
  */
+/**
+ * DX-3310 (nit) — per-action allow-list for `refuseInapplicableFields`.
+ * `id`/`action`/`board` are structural and never listed (every action takes
+ * them). `type` is listed under `edit` even though it can never actually be
+ * SENT there (see the dedicated throw below) — that keeps the generic
+ * refusal from firing first with a less specific message than the one that
+ * already names the real reason.
+ */
+const PROBLEM_ACTION_FIELDS = {
+    list: [],
+    add: ["statement", "context", "type", "summary", "solutions"],
+    edit: ["problem_id", "base_hash", "statement", "context", "summary", "type"],
+    remove: ["problem_id", "base_hash"],
+};
 export async function issueProblem(client, args) {
     const idEnc = encodeURIComponent(args.id);
     const board = args.board;
     const need = argCheckers("issue_problem", `action=${args.action}`);
+    refuseInapplicableFields("issue_problem", `action=${args.action}`, args, new Set(PROBLEM_ACTION_FIELDS[args.action]));
     switch (args.action) {
         case "list":
             return client.request({ method: "GET", path: `/${idEnc}/problems`, board });
@@ -693,11 +741,24 @@ export async function issueProblem(client, args) {
  * question could release the very stop it set to wait for a human. The operator
  * answers in the dashboard.
  */
+const SOLUTION_ACTION_FIELDS = {
+    add: ["title", "body", "pro", "con", "recommended", "steps"],
+    edit: ["solution_id", "base_hash", "title", "body", "pro", "con", "recommended", "steps", "steps_base_hash"],
+    remove: ["solution_id", "base_hash"],
+    add_step: ["solution_id", "title", "description", "parent_step_id", "position"],
+    edit_step: ["solution_id", "step_id", "base_hash", "title", "description"],
+    remove_step: ["solution_id", "step_id", "base_hash"],
+};
 export async function issueSolution(client, args) {
     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");
+    // DX-3310 (nit) — `problem_id` is unioned in here rather than listed in
+    // every `SOLUTION_ACTION_FIELDS` entry: unlike `issue_problem` (where it
+    // only applies to edit/remove), `issue_solution` requires it for every
+    // action (checked above), so it is structural FOR THIS TOOL specifically.
+    refuseInapplicableFields("issue_solution", `action=${args.action}`, args, new Set(["problem_id", ...SOLUTION_ACTION_FIELDS[args.action]]));
     const base = `/${encodeURIComponent(args.id)}/problems/${problemId}/solutions`;
     const board = args.board;
     const content = {};

package/dist/index.js

@@ -338,14 +338,14 @@ const boardField = {
         .string()
         .min(1)
         .optional()
-        .describe("Target another board by its qualified id `<repo>:<slug>`; omit for this dispatch's board. Unknown → 404."),
+        .describe("Board 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 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. Style rules: see issue_comment\'s `text` param.';
+const TITLE_DESCRIBE = 'Short, specific label naming the domain (e.g. "Guest checkout rejects gift-card carts"). Never generic ("Fix bug", "Follow-up").';
+const SUMMARY_DESCRIBE = "1–3 plain-language sentences, no markdown/jargon: what the card is and why it matters. Always shown, never collapsed — not a second title, not a teaser.";
+const DESCRIPTION_DESCRIBE = 'The full body ("Context"): evidence, examples, technical detail; markdown, collapsed by default. Operator questions go in issue_problem. Style: see issue_comment\'s `text` param.';
 // DX-3335 — condensed from the now-deleted danxbot:comment-style skill (PLN-11
 // R-16: fold a skill's rule into the tool description it governs rather than
 // require a separate load). Shared by every prose-writing field below so an
@@ -355,7 +355,7 @@ const MARKDOWN_STYLE_DESCRIBE = "Renders as markdown here. Use `##`/`###` header
 strictTool("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 — a card needs a human exactly when this is > 0), ac, comments, retro, dependencies, triage, 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 (highest priority=most urgent first), repo_name asc, numeric-id tiebreaker. `limit`/`offset` page (uncapped by default). DX-3113 — `include_closed` defaults to FALSE: a bare call silently excludes every Done/Cancelled card (leaf AND container alike). The response always carries `total` (the full count matching every filter except limit/offset — compare against `issues.length` to tell an exhausted list from a truncated one) and, whenever `include_closed` was not explicitly `true`, `closed_excluded` (how many additional terminal cards the default withheld — re-call with `include_closed: true` to see them). issue_get reads one card in full.", {
+"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 — a card needs a human exactly when this is > 0), ac, comments, retro, dependencies, triage, 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 (highest=most urgent first), repo_name asc, numeric-id tiebreaker. `limit`/`offset` page (uncapped by default). DX-3113 — `include_closed` defaults to FALSE: a bare call silently excludes every Done/Cancelled card (leaf AND container alike). The response always carries `total` (the full count matching every filter except limit/offset — compare against `issues.length` to tell an exhausted list from a truncated one) and, whenever `include_closed` was not explicitly `true`, `closed_excluded` (how many additional terminal cards the default withheld — re-call with `include_closed: true` to see them). issue_get reads one card in full.", {
     filter: z
         .object({
         q: z.string().optional(),
@@ -389,7 +389,7 @@ strictTool("issue_list",
 strictTool("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[] — a card needs a human exactly when open_problem_count > 0), ac (acceptance criteria + checklists), comments (see `comments_limit`/`comments_offset` below), retro, dependencies (waiting_on/conflict_on/blocked), triage (history + ICE), 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, plans (every plan this card is on, `{id, ref, name}[]` via `plan_cards` — `ref` is the plan's `PLN-<id>`). The `comments` group returns a PAGE ANCHORED AT THE NEWEST COMMENT: `comments_offset` counts back from the newest comment (offset 0 = the most recent comments_limit comments), and `comments_total` is the card's real total comment count, so `comments_offset + comments.length < comments_total` means older comments remain — page forward with `comments_offset` to reach them; a long-running card's decisive history (what was tried, measured, rejected or reverted) often lives past the first page. WITHIN a page, comments are ordered CHRONOLOGICALLY (oldest first, newest last) — the same order every other comment read in this API uses; only the WINDOW you request is anchored at the newest end, not the array itself. `comments_limit`/`comments_offset` apply to the SINGLE-id form only (no per-card paging in the batch form — naming either alongside `ids` is refused). Single form: unknown id → 404. Batch form: `{issues: [...], not_found: [...ids]}` — an unknown or deleted id never fails the call.", {
+"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[] — a card needs a human exactly when open_problem_count > 0), ac (acceptance criteria + checklists), comments (see `comments_limit`/`comments_offset` below), retro, dependencies (waiting_on/conflict_on/blocked), triage (history + ICE), 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, plans (every plan this card is on, `{id, ref, name}[]` via `plan_cards` — `ref` is the plan's `PLN-<id>`). The `comments` group PAGES ANCHORED AT THE NEWEST COMMENT: `comments_offset` counts back from it (offset 0 = the most recent comments_limit comments); `comments_total` is the real total, so `comments_offset + comments.length < comments_total` means older comments remain — page forward to reach them; a long-running card's decisive history often lives past the first page. WITHIN a page, comments stay CHRONOLOGICAL (oldest first) — same order as every other comment read; only the requested WINDOW is anchored at the newest end. `comments_limit`/`comments_offset` apply to the SINGLE-id form only (naming either alongside `ids` is refused). 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
@@ -403,7 +403,7 @@ strictTool("issue_get",
         .optional()
         .describe("Single-id form only. How many comments the page holds (server default 20), the window anchored at the " +
         "NEWEST comment. An out-of-range value (server max 200) is refused by the server with its own 400, " +
-        "never silently clamped here. Requires `fields` to include `comments`."),
+        "never silently clamped here. Requires `fields:[\"comments\"]`."),
     comments_offset: z
         .number()
         .int()
@@ -415,8 +415,8 @@ strictTool("issue_get",
     ...boardField,
 }, async (args) => jsonResult(await issueGet(client, args)));
 // ---------------- issue_create ----------------
-strictTool("issue_create", '`plan` is REQUIRED on every create (DX-3006): pass "mine" to put the card on THIS session\'s connected plan, or null when it deliberately belongs to no plan. There is no default and no inference — a card that names no plan is one nobody following the work can see, which is why the answer has to be given rather than omitted. "mine" while this session is on no plan is refused (409 session_not_connected) and creates NO card; a plan id is not accepted (a card is only ever created onto your own connected plan). This replaces the plan_add_card follow-up at creation time; plan_add_card remains for putting an EXISTING card on a plan. ' +
-    '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. `quality_gates` names the gates this card carries BEYOND the board\'s default set for its type — one `{gate, note?}` each. Omit it for just the board defaults; a gate you do not name simply is not on the card (there is no optional gate and nothing fails closed for going unnamed). Add one later with `issue_quality_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.', {
+strictTool("issue_create", '`plan` REQUIRED on every create (DX-3006, no default/inference): "mine" puts the card on THIS session\'s connected plan; null = deliberately no plan. "mine" while connected to none is refused (409 session_not_connected), creating NO card; a plan id is not accepted — a card is only ever created onto your own connected plan. Replaces the plan_add_card follow-up at creation time; plan_add_card still exists for putting an EXISTING card on a plan. ' +
+    'Create a card via POST /api/issues. Board-scoped; see `board`. type=Epic REQUIRES non-empty phase_children[] (epic + 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, no follow-up transition needed. Not valid on Epic; unknown name/id → 400. `quality_gates` names the gates this card carries BEYOND the board\'s default set for its type — `{gate, note?}` each; omit for just the board defaults (an unnamed gate is simply not on the card; add one later with `issue_quality_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),
@@ -428,7 +428,7 @@ strictTool("issue_create", '`plan` is REQUIRED on every create (DX-3006): pass "
     plan: z
         .literal("mine")
         .nullable()
-        .describe('"mine" = attach to the plan THIS session is connected to; null = deliberately no plan. REQUIRED — decide per card. A plan id is not accepted: a card is only ever created onto your own connected plan, so there is no id to name.'),
+        .describe('REQUIRED, decide per card — see tool description. "mine" = this session\'s connected plan; null = deliberately none; no plan id accepted.'),
     parent_id: z.string().nullable().optional(),
     ac: z.array(z.object({ title: z.string().min(1) }).strict()).optional(),
     effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
@@ -479,7 +479,7 @@ strictTool("issue_create", '`plan` is REQUIRED on every create (DX-3006): pass "
     priority: z
         .union([z.enum(PRIORITY_TIER_WORDS), z.number()])
         .optional()
-        .describe('A tier word ("lowest"=0–1…"critical"=5–6; higher number = more urgent, prefer tier word) or number in [0,6); higher numbers are more urgent. Omit for the route\'s own default.'),
+        .describe('Tier word ("lowest"…"critical", prefer this) or number in [0,6); higher = more urgent. Omit for the route\'s own default.'),
     // DX-3238 — `assigned_agent` is DELIBERATELY left undeclared here, unlike
     // `priority` above. The route accepts it (`ALLOWED_CREATE_KEYS`,
     // create.ts:39-56) but it only matters for the create→`list_id`-lands-
@@ -495,7 +495,7 @@ strictTool("issue_create", '`plan` is REQUIRED on every create (DX-3006): pass "
     ...boardField,
 }, async (args) => jsonResult(await issueCreate(client, args, config.board)));
 // ---------------- issue_edit ----------------
-strictTool("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, blocked) is refused 400 with offending_keys[] naming the right tool: issue_transition / issue_triage / issue_comment / issue_dependency / issue_problem / 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` (tier word: "lowest"–"critical", or number 0–6; higher = more urgent, prefer tier word) is the ONLY way to set priority; a "Priority:" line 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.', {
+strictTool("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, blocked) is refused 400 with offending_keys[] naming the right tool: issue_transition / issue_triage / issue_comment / issue_dependency / issue_problem / issue_retro. `type`: Story/Bug/Chore = eligible for autonomous pickup; Task or a container (Epic/Feature) removes that eligibility. `priority` (tier word "lowest"–"critical", or number 0–6, higher = more urgent) is the ONLY way to set priority; a "Priority:" line does nothing. CHECKLISTS: each item has one status `incomplete|failing|passing|cancelled|deferred`; `deferred` (work done, real-world check outstanding) REQUIRES `detail`; 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) — the card\'s optimistic-concurrency token — is 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` with `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
@@ -516,7 +516,7 @@ strictTool("issue_edit", 'Patch a card via PATCH /api/issues/:id/edit. ALLOWED k
         status: z
             .enum(CHECKLIST_ITEM_STATUSES)
             .optional()
-            .describe("Optional full status; omitted → from `checked`. `deferred` REQUIRES a non-empty `detail`; a 📡 item can never be `passing`."),
+            .describe("Optional full status; omitted → from `checked`. See tool description for the deferred/📡 rules."),
         detail: z
             .string()
             .optional()
@@ -543,7 +543,7 @@ strictTool("issue_edit", 'Patch a card via PATCH /api/issues/:id/edit. ALLOWED k
     priority: z
         .union([z.enum(PRIORITY_TIER_WORDS), z.number()])
         .optional()
-        .describe('A tier word ("lowest"=0–1…"critical"=5–6; higher number = more urgent, prefer tier word) or number in [0,6); higher numbers are more urgent. The only way to set priority.'),
+        .describe('Tier word ("lowest"…"critical", prefer this) or number in [0,6); higher = more urgent — see tool description for why this is the only way to set it.'),
     list_id: z.string().min(1).nullable().optional(),
     triage_enabled: z
         .boolean()
@@ -602,7 +602,7 @@ const CHECKLIST_ITEM_INPUT = z
     status: z.enum(CHECKLIST_ITEM_STATUSES).optional(),
 })
     .strict();
-strictTool("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.", {
+strictTool("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; `deferred` = work done but 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",
@@ -638,22 +638,20 @@ const STEP_INPUT = z.lazy(() => z
         .int()
         .positive()
         .optional()
-        .describe("present -> this node IS an existing step (matched on this id, 400 if it does not resolve to a live " +
-        "child of this exact parent scope — a supplied id is NEVER claimed by the positional/title fallback " +
-        "below); absent -> matched against unclaimed siblings by TITLE (first unclaimed match, in order), else " +
-        "created new. An id-less MIDDLE insert recreates every later id-less sibling's row unless you send ids " +
-        "for the ones you want preserved — send ids whenever an existing step's identity matters (checked " +
-        "progress, a later single-step edit)."),
+        .describe("present -> matches an existing step by this id (400 if not a live child of this exact parent scope, " +
+        "never claimed by the fallback below); absent -> matches the first unclaimed same-titled sibling " +
+        "under the same parent, else creates new (title-based, never positional — keeps later id-less " +
+        "siblings' ids intact on a middle insert). Send ids anyway when identity matters (checked progress, " +
+        "a later edit) or siblings share a title."),
     title: z
         .string()
         .min(1)
-        .describe("one imperative line, the thing to do — labels (\"1.\", \"2a\") are DERIVED on read and must never appear " +
-        "in the title itself."),
+        .describe("one imperative line — labels (\"1.\", \"2a\") are DERIVED on read, never put one in the title."),
     description: z.string().nullable().optional().describe("markdown detail, or null/omitted for none"),
     steps: z.array(STEP_INPUT).optional().describe("this step's own children, nested — refused past 3 levels total"),
 })
     .strict());
-strictTool("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) OR an action only a person can carry out, each with its own solutions/answers — one problem per question. OPEN = not yet answered; the card needs a human exactly while open_problem_count > 0 — there is no separate flag to set, adding a problem IS putting the card in front of a human. list → live problems in order, each {id, statement, context, type, summary, content_hash, open, solutions[], decisions[]}; add {statement, context?, type?, summary?, solutions?} → problem_id + solution_ids in one transaction (zero solutions is valid: the operator answers free-form) plus `problems_reminder: {open_problem_count, instruction}` naming each open problem's solution count; edit :pid {base_hash, statement, context?, summary?}; remove :pid {base_hash} — always allowed, even as the card's last open problem (removing it just means the card no longer needs a human). A stale base_hash → 409 `stale_problem` with currentHash + currentProblem: merge, then retry. No answer action — the operator answers in the dashboard. `statement` is capped at 200 characters (a 400 names the actual length otherwise): write it as ONE plain sentence (a question for a question, the deed itself for an action), and put any investigation detail in `context` (markdown, no cap) instead of running it on. Good: statement \"Which cache should we use?\", context \"Redis fits the read-heavy path; see benchmark in #123. Memcached is simpler ops but no persistence.\" Bad: statement \"We looked at Redis vs Memcached, ran benchmarks showing Redis 3x faster on reads, but Memcached has simpler ops and we're not sure persistence matters here since the cache is fully rebuildable from Postgres...\" (too long, refused — move it to context). Every problem is also a `type`, with a `summary` distinct from `context`: read BOTH fields' own descriptions below before your first `add` — together they teach which type this is, and the three-field split (`statement` / `summary` / `context`) an action actually needs.", {
+strictTool("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) OR an action only a person can carry out, each with its own solutions/answers — one problem per question. OPEN = not yet answered; the card needs a human exactly while open_problem_count > 0 — no separate flag, adding a problem IS putting the card in front of a human. list → live problems in order, each {id, statement, context, type, summary, content_hash, open, solutions[], decisions[]}; add {statement, context?, type?, summary?, solutions?} → problem_id + solution_ids in one transaction (zero solutions is valid: the operator answers free-form) plus `problems_reminder: {open_problem_count, instruction}` naming each open problem's solution count; edit :pid {base_hash, statement, context?, summary?}; remove :pid {base_hash} — always allowed, even as the card's last open problem (removing it just means the card no longer needs a human). Stale base_hash → 409 `stale_problem` with currentHash + currentProblem: merge, then retry. No answer action — the operator answers in the dashboard. `statement` capped at 200 characters (400 names the actual length otherwise): ONE plain sentence, with investigation detail in `context` (markdown, no cap) instead — e.g. statement \"Which cache should we use?\", context \"Redis fits the read-heavy path; see benchmark in #123.\" not a run-on statement. Every problem also has a `type` with a `summary` distinct from `context` — read both fields' descriptions before your first `add`.", {
     id: z.string().min(1),
     action: z.enum(["list", "add", "edit", "remove"]),
     problem_id: z.number().int().positive().optional().describe("edit/remove"),
@@ -662,9 +660,7 @@ strictTool("issue_problem", "A card's PROBLEMS via /api/issues/:id/problems[/:pi
         .string()
         .min(1)
         .optional()
-        .describe("add/edit; ONE plain sentence, at most 200 characters. For a question: the question itself. For an action: " +
-        "WHAT IS TO BE DONE — the deed itself, never phrased as a question (\"Rotate the staging DB credential\", " +
-        "not \"Should we rotate it?\")."),
+        .describe("add/edit; ONE plain sentence, at most 200 characters — see `type` below for question vs action phrasing."),
     context: z
         .string()
         .nullable()
@@ -676,67 +672,58 @@ strictTool("issue_problem", "A card's PROBLEMS via /api/issues/:id/problems[/:pi
     type: z
         .enum(["question", "action"])
         .optional()
-        .describe("add only. Before you raise this problem, apply the test: could I do this myself if I tried harder, and is the " +
-        "only thing missing a decision? If yes, this is a \"question\": statement is the question itself (one plain " +
-        "sentence); summary (optional) is why it matters; context is the evidence behind it; solutions[] are " +
-        "candidate ANSWERS, each with its own pro/con, and the operator is done the moment they pick one. If the " +
-        "blocker is access, credentials, hardware, a human's authority, or a system you genuinely cannot reach, " +
-        "this is an \"action\": statement is WHAT IS TO BE DONE — the deed itself, never phrased as a question " +
-        "(\"Rotate the staging DB credential\", not \"Should we rotate it?\"); summary is REQUIRED and MUST say " +
-        "WHY THE ACTION IS NEEDED AND WHY YOU CANNOT DO IT YOURSELF — that sentence is what tells the operator this " +
-        "is not you being lazy (an add with no summary is refused 400); context is whatever additional detail the " +
-        "person needs to carry it out; solutions[] are the possible ROUTES a person could take (e.g. \"rotate by " +
-        "hand in the console\" vs \"run the provisioning script\" vs \"ask the vendor\"), and EACH ONE MUST CARRY " +
-        "AT LEAST ONE STEP (refused 400 otherwise) — an action with no procedure is not yet actionable. Omitted " +
-        "defaults to \"question\" — decide deliberately every time."),
+        .describe("add only. Test: could I do this myself if I tried harder, missing only a decision? Yes → \"question\": " +
+        "statement is the question (one plain sentence); summary optional; context is the evidence; solutions[] " +
+        "are candidate ANSWERS with pro/con, done once the operator picks one. Blocker is access, credentials, " +
+        "hardware, a human's authority, or a system you genuinely cannot reach → \"action\": statement is WHAT " +
+        "IS TO BE DONE — the deed, never a question (\"Rotate the staging DB credential\", not \"Should we " +
+        "rotate it?\"); summary REQUIRED — WHY NEEDED AND WHY YOU CANNOT DO IT YOURSELF (no summary → 400, " +
+        "proves this isn't laziness); context is detail for the person carrying it out; solutions[] are the " +
+        "possible ROUTES, EACH MUST CARRY AT LEAST ONE STEP (400 otherwise). Omitted defaults to \"question\" " +
+        "— decide deliberately."),
     summary: z
         .string()
         .nullable()
         .optional()
-        .describe("add/edit. Plain text, 1-3 sentences — never markdown detail (that's `context`'s job). For a question: " +
-        "optional, why it matters. For an action: REQUIRED and non-empty — why the action is needed AND why you " +
-        "(the agent raising it) cannot do it yourself; omitting it on an action add is refused 400 naming this " +
-        "field, and an edit that would clear it on a live action problem is refused the same way. add: sent only " +
-        "when given (omit/null on a question means none). edit: omit to keep the stored summary, null to clear it " +
-        "(refused if the problem is a live action)."),
+        .describe("add/edit. Plain text, 1-3 sentences — never markdown (that's `context`'s job). Required+non-empty for an " +
+        "action problem (why needed + why you can't do it yourself — see `type`; refused 400 if missing on add or " +
+        "cleared on a live action edit); optional for a question. add: sent only when given (omit/null on a " +
+        "question means none). edit: omit keeps the stored summary, null clears it."),
     solutions: z
         .array(z.object({ title: z.string().min(1), ...SOLUTION_FIELDS, steps: z.array(STEP_INPUT).optional() }).strict())
         .optional()
-        .describe("add only; fields as issue_solution add, INCLUDING steps (S6/AC 35332) — an ACTION problem's inline " +
+        .describe("add only; fields as issue_solution add, INCLUDING steps — an ACTION problem's inline " +
         "solutions must each carry at least one step (refused 400 otherwise); a QUESTION's may carry any number, " +
         "including none."),
     ...boardField,
 }, async (args) => jsonResult(await issueProblem(client, args)));
 // ---------------- issue_solution ----------------
-strictTool("issue_solution", "One problem's options via /api/issues/:id/problems/:pid/solutions[/:sid], AND (DX-3310) one solution's individual " +
-    "procedure steps via .../solutions/:sid/steps[/:stepId]; `problem_id` is REQUIRED (from issue_problem list/add; " +
+strictTool("issue_solution", "One problem's options via /api/issues/:id/problems/:pid/solutions[/:sid], plus (DX-3310) a solution's own " +
+    "procedure steps via .../solutions/:sid/steps[/:stepId]; `problem_id` REQUIRED (from issue_problem list/add; " +
     "another problem's solution id → 404). add {title, body?, pro?, con?, recommended?, steps?}: title names the " +
-    "option/route, body is its markdown detail, pro/con the case for and against, `steps` is its WHOLE procedure " +
-    "authored in one call — an ordered array of {title, description?, steps?}, nestable to 3 levels (a 4th is refused " +
-    "400 naming the offending step and the limit). AC 35332 — under an ACTION problem, `steps` must be non-empty " +
-    "(refused 400 otherwise); under a QUESTION it may be omitted or empty. Labels (\"1\", \"2a\", \"2a.i\") are " +
-    "ALWAYS DERIVED on read from position — never put one in a title yourself. edit :sid {base_hash, ...only the " +
-    "changed fields, steps?, steps_base_hash?}: `steps` omitted leaves the stored procedure untouched, an explicit " +
-    "array (including [], refused if it would leave an action's solution with zero steps) DIFFS against it — send " +
-    "back an existing step's `id` (read from the card) to keep it (even while retitling/reordering it) and omit " +
-    "`id` for a genuinely new step; any existing step you don't include gets removed, and an id-less MIDDLE insert " +
-    "recreates every later id-less sibling's row unless you send ids for the ones whose identity matters. " +
-    "`steps_base_hash` is REQUIRED whenever `steps` is sent — the solution's current `steps_hash` (read it off the " +
-    "card first); a stale value → 409 `stale_steps` carrying the current tree, so a step added/removed since your " +
-    "read is never silently dropped. NEVER resend the whole tree just to fix one word — see add_step/edit_step/" +
-    "remove_step below. 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's words are frozen (409 — add a new one instead), and so is its " +
-    "WHOLE PROCEDURE — every steps route below also refuses once a decision has chosen this solution.\n\n" +
-    "Granular single-step actions — change ONE step without resending the tree: add_step {solution_id, title, " +
-    "description?, parent_step_id?, position?} — title is ONE imperative line, never a label like \"1.\" or \"2a\" " +
-    "(derived on read); parent_step_id omitted/null = top-level; position is 1-indexed among the parent's current " +
-    "live children, omitted = append, and a position beyond the current sibling count is refused (400), never " +
-    "silently clamped to append; nesting past depth 3 → 400. edit_step {solution_id, step_id, base_hash, title?, " +
-    "description?} — never moves a step (no parent_step_id/position here). remove_step {solution_id, step_id, " +
-    "base_hash} — soft-deletes it AND its own live children; refused (409) if this solution belongs to an ACTION " +
-    "problem and removing it would leave zero live steps. A stale base_hash on a step → 409 `stale_step` with " +
-    "currentHash + currentStep (carrying its real derived `label`).", {
+    "option, body/pro/con its markdown detail and case for/against; `steps` authors the WHOLE procedure in one " +
+    "call — {title, description?, steps?}[], nestable to 3 levels (4th refused 400, naming the step + limit). " +
+    "ACTION problem: `steps` must be non-empty (400 otherwise); QUESTION: may be omitted/empty. Labels " +
+    "(\"1\", \"2a\", \"2a.i\") are DERIVED on read from position — never put one in a title. edit :sid {base_hash, " +
+    "...changed fields, steps?, steps_base_hash?}: `steps` omitted leaves the procedure untouched; an explicit " +
+    "array (incl. [], refused if it leaves an action's solution with zero steps) DIFFS against it — send an " +
+    "existing step's `id` to keep it (even while retitling/reordering), omit `id` for a new step; any existing " +
+    "step left out is removed. An id-less node matches the first unclaimed same-titled sibling under the same " +
+    "parent (never positional), so an id-less MIDDLE insert keeps later id-less siblings' ids — send ids anyway " +
+    "when identity matters. `steps_base_hash` REQUIRED whenever `steps` is sent — the solution's current " +
+    "`steps_hash`; stale → 409 `stale_steps` with the current tree. Never resend the whole tree to fix one word " +
+    "— use add_step/edit_step/remove_step below. remove :sid {base_hash}: stale → 409 `stale_solution` with " +
+    "currentHash + currentSolution, merge and retry. At most ONE live recommended per problem — a second → 409 " +
+    "naming `recommended_solution_id`. A CHOSEN option's words and WHOLE PROCEDURE are frozen (409 — add a new " +
+    "one instead); every steps route below refuses once a decision has chosen this solution.\n\n" +
+    "Granular single-step actions, no tree resend: add_step {solution_id, title, description?, parent_step_id?, " +
+    "position?} — title is one imperative line (labels derived, never typed); parent_step_id omitted/null = " +
+    "top-level; position 1-indexed among current live children, omitted = append, beyond sibling count → 400 " +
+    "(never clamped); nesting past depth 3 → 400. edit_step {solution_id, step_id, base_hash, title?, " +
+    "description?} — never moves a step. remove_step {solution_id, step_id, base_hash} — soft-deletes it and " +
+    "its live children; refused 409 if this solution belongs to an ACTION problem and removing it leaves zero " +
+    "live steps. Stale base_hash on a step → 409 `stale_step` with currentHash + currentStep (real derived " +
+    "`label`).", {
     id: z.string().min(1),
     action: z.enum(["add", "edit", "remove", "add_step", "edit_step", "remove_step"]),
     problem_id: z.number().int().positive(),
@@ -768,7 +755,7 @@ strictTool("issue_solution", "One problem's options via /api/issues/:id/problems
     ...boardField,
 }, async (args) => jsonResult(await issueSolution(client, args)));
 // ---------------- issue_dependency ----------------
-strictTool("issue_dependency", 'Dependency CRUD via /api/issues/:id/dependencies[/:did]. action=add → POST {kind, target_id, reason} where kind ∈ {depends_on, conflict_on}. depends_on adds are CYCLE-CHECKED (BFS from target back to source — 409 if loop). Idempotent: re-adding a live triple returns the existing id. Self-loops refuse 409. action=remove → DELETE /:did. The server REQUIRES the literal reason="recorded_in_error" on removal (encodes "removal means NOT related, never satisfied") — this MCP boundary hardcodes it, so callers do not pass reason on remove. This is the ONLY mechanism the dispatch picker enforces to sequence one card after another — leaving a card at a Review/held status (e.g. an issue_triage "keep" verdict) is NOT a substitute and provides no cross-card ordering protection.', {
+strictTool("issue_dependency", 'Dependency CRUD via /api/issues/:id/dependencies[/:did]. action=add → POST {kind, target_id, reason} where kind ∈ {depends_on, conflict_on}. depends_on adds are CYCLE-CHECKED (BFS from target back to source — 409 if loop). Idempotent: re-adding a live triple returns the existing id. Self-loops refuse 409. action=remove → DELETE /:did. The server REQUIRES the literal reason="recorded_in_error" on removal (encodes "removal means NOT related, never satisfied"); this MCP boundary hardcodes it, so callers do not pass reason on remove. This is the ONLY mechanism the dispatch picker enforces to sequence one card after another — leaving a card at Review/held (e.g. an issue_triage "keep" verdict) is NOT a substitute.', {
     id: z.string().min(1),
     action: z.enum(["add", "remove"]),
     kind: z.enum(["depends_on", "conflict_on"]).optional(),
@@ -805,7 +792,7 @@ strictTool("issue_quality_gate", "Put one quality gate ON a card, or take it OFF
     ...boardField,
 }, async (args) => jsonResult(await issueQualityGate(client, args)));
 // ---------------- issue_quality_gate_verdict ----------------
-strictTool("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 puts a gate ON or OFF the card (does this gate apply 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`.", {
+strictTool("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 puts a gate ON or OFF the card (does this gate apply 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}`**: `issue_transition complete` REFUSES 409 (`failed_gate: \"quality_gate_post\"`, `failed_post_gates[]`) while any required POST gate is not `pass` — without a verdict a manually-claimed card strands In Progress, stalling other cards via its `conflict_on`/`waiting_on` edges. `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 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",
@@ -820,13 +807,13 @@ strictTool("issue_quality_gate_verdict", "Stamp an operator MANUAL quality-gate
     ...boardField,
 }, async (args) => jsonResult(await issueQualityGateVerdict(client, args)));
 // ---------------- issue_retro ----------------
-strictTool("issue_retro", "Replace the retro block via PUT /api/issues/:id/retro. Body: {good, bad, correctable_danxbot_problem, correctable_danxbot_problem_description, 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). `correctable_danxbot_problem` (DX-2794) is REQUIRED on every write, like tests[] — ANSWER IT HONESTLY: did THIS dispatch hit a problem in danxbot's own code or configuration (not merely \"this card was hard\") that danxbot could change so it stops happening? true REQUIRES a non-empty `correctable_danxbot_problem_description` naming the problem; false REQUIRES the description be empty. A true+described retro is read by a deterministic, no-LLM check and starts exactly one automated repair (fixes the problem or files a ready card) — this is the ONLY reliable channel for a danxbot defect found mid-dispatch to actually get fixed, so do not default to false out of haste.", {
+strictTool("issue_retro", "Replace the retro block via PUT /api/issues/:id/retro. Body: {good, bad, correctable_danxbot_problem, correctable_danxbot_problem_description, 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, never 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). `correctable_danxbot_problem` (DX-2794) is REQUIRED on every write, like tests[] — ANSWER HONESTLY: did THIS dispatch hit a problem in danxbot's own code or configuration (not merely \"this card was hard\") that danxbot could change so it stops happening? true REQUIRES a non-empty `correctable_danxbot_problem_description` naming the problem; false REQUIRES the description be empty. A true+described retro is read by a deterministic, no-LLM check and starts exactly one automated repair (fixes the problem or files a ready card) — the ONLY reliable channel for a danxbot defect found mid-dispatch to get fixed, so do not default to false out of haste.", {
     id: z.string().min(1),
-    good: z.string().describe("Free-form markdown (prose or a list — pick whichever reads fastest, they render identically). Style rules: see issue_comment's `text` param."),
-    bad: z.string().describe("Free-form markdown (prose or a list — pick whichever reads fastest, they render identically). Style rules: see issue_comment's `text` param."),
+    good: z.string().describe("Free-form markdown (prose or list, they render identically). Style: see issue_comment's `text` param."),
+    bad: z.string().describe("Free-form markdown (prose or list, they render identically). Style: see issue_comment's `text` param."),
     correctable_danxbot_problem: z
         .boolean()
-        .describe("Required. Did this dispatch hit a problem in danxbot's OWN code/configuration (not \"this card was hard\") that danxbot could change so it stops happening? Answer explicitly every time — never left at a default."),
+        .describe("Required every time, answered honestly — see tool description. Determines whether the description field below must be filled or must be empty."),
     correctable_danxbot_problem_description: z
         .string()
         .describe("Required. Non-empty (naming the concrete problem) when correctable_danxbot_problem is true; must be empty when it is false."),
@@ -920,7 +907,7 @@ strictTool("plan_list", "List every plan via GET /api/plans (DX-2683), and learn
         .optional()
         .describe("Filter to one computed status: awaiting-session, planning, building, complete. Omit for every plan."),
 }, async (args) => jsonResult(await planList(client, args)));
-strictTool("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, status, session, sessionListenerAttached, available_field_groups}` — no cards, records, or architecture body. `plan` carries `{id, ref, name, createdAt}`; `ref` is the plan's short reference (`PLN-<id>`) — cite that, not the bare id. `status` (DX-2834) is computed fresh on every read, never stored — see `plan_list` for the four values and what each means. 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), `events` (DX-2987/DX-3027 — the plan's durable event ledger: every human action and every bridge message recorded on it, cursor-paged newest first via `events_limit` (1.." + PLAN_GET_EVENTS_MAX_LIMIT + ", default " + PLAN_GET_EVENTS_DEFAULT_LIMIT + ") and `events_before` (an opaque cursor — pass a previous page's `next_cursor` to read older; omit for the newest page); filter with `events_kinds` (one or more of " + PLAN_EVENT_KINDS.join(", ") + "), `events_origin` (one of " + PLAN_EVENT_ORIGINS.join(", ") + "), `events_writer` (exact writer name); every `events_*` param without `fields: [\"events\"]` is a 400, same as the `cards_*` params above; response carries `events: {items: [{id, at, kind, writer, origin, originSessionId, targetSessionId, cardId, cardTitle, boardId, detail}], next_cursor}` — `next_cursor` is `null` on the last page; an event on a card whose board you cannot read is left out, plan-level events are always visible). `session`/`sessionListenerAttached` and `available_field_groups` ride every response regardless. `sessionListenerAttached` is `false` for a few seconds right after `plan_connect` while the plugin's event bridge starts; still `false` after that while connected means the plan's card events are not reaching you — tell the operator. 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`.", {
+strictTool("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, status, session, sessionListenerAttached, available_field_groups}` — no cards, records, or architecture body. `plan` carries `{id, ref, name, createdAt}`; `ref` is the plan's short reference (`PLN-<id>`) — cite that, not the bare id. `status` (DX-2834) is computed fresh on every read, never stored — see `plan_list` for the four values and what each means. 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); 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), `events` (DX-2987/DX-3027 — the plan's durable event ledger, every human action + bridge message, cursor-paged newest first via `events_limit` (1.." + PLAN_GET_EVENTS_MAX_LIMIT + ", default " + PLAN_GET_EVENTS_DEFAULT_LIMIT + ") and `events_before` (a previous page's `next_cursor`; omit for the newest page); filter with `events_kinds` (one+, see its enum), `events_origin` (one, see its enum), `events_writer` (exact name); every `events_*` param without `fields: [\"events\"]` is a 400, same as `cards_*` above; response carries `events: {items: [{id, at, kind, writer, origin, originSessionId, targetSessionId, cardId, cardTitle, boardId, detail}], next_cursor}` — `next_cursor` null on the last page; an event on an unreadable board is left out, plan-level events always visible). `session`/`sessionListenerAttached`/`available_field_groups` ride every response regardless. `sessionListenerAttached` is `false` for a few seconds right after `plan_connect` while the event bridge starts; still `false` after that while connected means plan events aren't reaching you — tell the operator. 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()
@@ -936,39 +923,39 @@ strictTool("plan_get", "Read a plan via GET /api/plans (DX-2683). Pass `plan_id`
         .int()
         .nonnegative()
         .optional()
-        .describe("Where the `cards` page starts (default 0). Requires `fields` to include `cards`. Page with cards_offset while cards_offset + cards.length < cards_total."),
+        .describe("Where the `cards` page starts (default 0). Requires `fields:[\"cards\"]`. Page with cards_offset while cards_offset + cards.length < cards_total."),
     cards_limit: z
         .number()
         .int()
         .positive()
         .max(LIST_PAGE_MAX_LIMIT)
         .optional()
-        .describe("How many cards one page holds, 1.." + LIST_PAGE_MAX_LIMIT + " (default " + PLAN_GET_CARDS_DEFAULT_LIMIT + "). Requires `fields` to include `cards`."),
+        .describe("How many cards one page holds, 1.." + LIST_PAGE_MAX_LIMIT + " (default " + PLAN_GET_CARDS_DEFAULT_LIMIT + "). Requires `fields:[\"cards\"]`."),
     events_limit: z
         .number()
         .int()
         .positive()
         .max(PLAN_GET_EVENTS_MAX_LIMIT)
         .optional()
-        .describe("DX-3027 — how many ledger events one page holds, 1.." + PLAN_GET_EVENTS_MAX_LIMIT + " (default " + PLAN_GET_EVENTS_DEFAULT_LIMIT + "). Requires `fields` to include `events`."),
+        .describe("DX-3027 — how many ledger events one page holds, 1.." + PLAN_GET_EVENTS_MAX_LIMIT + " (default " + PLAN_GET_EVENTS_DEFAULT_LIMIT + "). Requires `fields:[\"events\"]`."),
     events_before: z
         .string()
         .min(1)
         .optional()
-        .describe("DX-3027 — an opaque cursor from a previous page's `next_cursor`. Omit for the newest page. Requires `fields` to include `events`."),
+        .describe("an opaque cursor from a previous page's `next_cursor`. Omit for the newest page. Requires `fields:[\"events\"]`."),
     events_kinds: z
         .array(z.enum(PLAN_EVENT_KINDS))
         .optional()
-        .describe("DX-3027 — only these event kinds. Omit for every kind. Requires `fields` to include `events`."),
+        .describe("only these event kinds. Omit for every kind. Requires `fields:[\"events\"]`."),
     events_origin: z
         .enum(PLAN_EVENT_ORIGINS)
         .optional()
-        .describe("DX-3027 — only events with this origin. Omit for every origin. Requires `fields` to include `events`."),
+        .describe("only events with this origin. Omit for every origin. Requires `fields:[\"events\"]`."),
     events_writer: z
         .string()
         .min(1)
         .optional()
-        .describe("DX-3027 — only events with this exact writer name. Omit for every writer. Requires `fields` to include `events`."),
+        .describe("only events with this exact writer name. Omit for every writer. Requires `fields:[\"events\"]`."),
 }, async (args) => jsonResult(await planGet(client, args)));
 strictTool("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, ref, name, createdAt}}}` — `ref` is the plan's short reference (`PLN-<id>`). 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."),
@@ -1038,9 +1025,9 @@ strictTool("plan_update_note", 'Edit a plan note, via PATCH /api/plans/:plan_id/
     content_hash: z.string().describe("The note's `contentHash` from your last read. Required."),
     title: z.string().min(1).optional().describe("New title, at most 60 characters. Omit to keep the stored title."),
     body: z.string().min(1).optional().describe("New wrap-up, at most 250 characters. Omit to keep the stored body."),
-    card_ids: z.array(z.string().min(1)).optional().describe("REPLACES the whole link set when sent (with record_refs/section_ids)."),
-    record_refs: z.array(z.string().min(1)).optional().describe("REPLACES the whole link set when sent (with card_ids/section_ids)."),
-    section_ids: z.array(z.number().int().positive()).optional().describe("REPLACES the whole link set when sent (with card_ids/record_refs)."),
+    card_ids: z.array(z.string().min(1)).optional().describe("Part of the link-set group — see tool description."),
+    record_refs: z.array(z.string().min(1)).optional().describe("Part of the link-set group — see tool description."),
+    section_ids: z.array(z.number().int().positive()).optional().describe("Part of the link-set group — see tool description."),
 }, async (args) => jsonResult(await planUpdateNote(client, args)));
 strictTool("plan_delete_note", 'Soft-delete a plan note, via DELETE /api/plans/:plan_id/notes/:note_id (DX-2915). `content_hash` must be the note\'s `contentHash` from your last read; a stale hash deletes nothing and returns `{error: "stale_plan_note", currentHash, currentTitle, currentBody, currentLinks}` — the same shape `plan_update_note` uses. TAKES AN EXPLICIT `plan_id`, same reason as `plan_add_note`. Unknown plan, unknown note, or an already-deleted note → 404. DX-3072 — returns `{notes_count}`, the plan\'s remaining live note count, not the latest page.', {
     plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
@@ -1125,7 +1112,7 @@ strictTool("failure_category_update", "Patch an existing failure category via PA
     expectedRate: expectedRateField,
 }, async (args) => jsonResult(await failureCategoryUpdate(client, args)));
 // ---------------- dispatch_transcript_search (DX-3221) ----------------
-strictTool("dispatch_transcript_search", "Search or tail ANOTHER dispatch's stored JSONL session transcript via the existing durable GET /api/dispatches/:id/logs sink (DX-1682/DX-1484) — every worker dispatch's raw transcript lines are already captured there today, so this adds no new server route, only in-process search/windowing. Use this instead of trying to Read a session transcript file directly: it needs no filesystem access to `~/.claude/projects/` (an ordinary authenticated HTTP call, so it never touches worktree-guard or CLAUDE.md Core Principle 5's worktree boundary), and it fixes what Read structurally cannot — Read paginates by LINE, and one persisted JSONL entry can itself be a single line far past Read's 25000-token cap with no way to sub-page inside it; this tool does the string/regex search itself and only ever returns a bounded excerpt AROUND a match, never the whole line. With `pattern`: returns up to `maxMatches` matching lines (case-insensitive regex), each as a windowed excerpt of up to `contextChars` characters centered on the first match. Without `pattern`: returns the most recent `tail` lines instead, each capped at `contextChars` characters (a `truncated: true` flag marks a capped excerpt either way — never a caller-visible error the way an oversized Read would throw). `dispatchId` is a real `dispatches.id` — exactly the ids a failure-repair card's own body already lists under \"dispatches that hit it\".", {
+strictTool("dispatch_transcript_search", "Search or tail ANOTHER dispatch's stored JSONL session transcript via GET /api/dispatches/:id/logs (DX-1682/DX-1484/DX-3221) — no new server route, only in-process search/windowing over the transcript already captured there. Prefer this over reading the transcript file directly: no filesystem access needed, and a single JSONL entry can be far longer than a line-based file read can sub-page — this tool searches the string itself and returns only a bounded excerpt AROUND a match, never the whole line. With `pattern`: returns up to `maxMatches` matching lines (case-insensitive regex), each a windowed excerpt of up to `contextChars` characters centered on the first match. Without `pattern`: returns the most recent `tail` lines instead, each capped at `contextChars`. `truncated: true` marks a capped excerpt either way, never a thrown error. `dispatchId` is a real `dispatches.id` — exactly the ids a failure-repair card's own body already lists under \"dispatches that hit it\".", {
     dispatchId: z.string().min(1).describe("The dispatch id whose transcript to search — from a failure-repair card's own body, or any other dispatch id you already have."),
     pattern: z.string().min(1).optional().describe("Case-insensitive regex tested against each raw JSONL line. Omit to get a tail read of the most recent lines instead."),
     tail: z.number().int().positive().optional().describe("Only used when `pattern` is omitted. How many of the most recent lines to return. Defaults to 20, capped at 200."),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.131",
+  "version": "0.1.132",
   "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",