@thehammer/danx-dashboard-mcp 0.1.219 → 0.1.221

package/dist/index.js

@@ -89,6 +89,7 @@ import { planConnect, danxbotApi, danxbotApiList, danxbotApiSpec, attachFile, DA
 import { bodyValueSchema, queryValueSchema } from "./types.js";
 import { termsAcceptanceCallHalt, termsHaltFor } from "./terms-halt.js";
 import { danxbotApiExamplesText } from "./danxbot-api-examples.js";
+import { assertWithinTextLimit } from "./text-limit.js";
 import { registerLifecycleTools, applyLifecycleVisibility, readLifecycleUrlsFromEnv, } from "./lifecycle.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -220,61 +221,39 @@ function readSessionConfig() {
     return { id };
 }
 /**
- * DX-3465 (PLN-11 R-25) — the ONE home for prose that used to be repeated
- * (or would otherwise need repeating) on every per-operation tool this
- * server exposes, now that `danxbot_api` is the generic surface for
- * everything that is not agent-specific (R-25). Read this before your first
- * `danxbot_api` call.
+ * DX-3465 (PLN-11 R-25) — the conventions shared by every `danxbot_api` call,
+ * stated once here instead of on each tool.
  *
- * Per-tool descriptions stay minimal — this block is where the shared rules
- * live, once.
+ * DX-4318 — this block is the ONE home of the stale-hash rule and of the
+ * writing standard (PLN-11 R-24): it is the only text every caller of these
+ * tools receives (operator sessions, their sub-agents, every dispatch
+ * profile). It was 3,916 characters and Claude Code delivered the first
+ * 2,048, so both rules were cut from every session. `assertWithinTextLimit`
+ * below refuses a block that would be cut again. Behaviour only, no rationale.
  */
 const SERVER_INSTRUCTIONS = `\
-danx-dashboard-mcp — reach the dashboard API through danxbot_api; find a route with danxbot_api_list; discover
-its shape through danxbot_api_spec.
+Conventions for every \`danxbot_api\` call. Find a route with \`danxbot_api_list\` and its exact shape with
+\`danxbot_api_spec\`.
 
-UNIFORM RESOURCE SHAPE. Most dashboard resources (cards, plans, records, comments, problems, ...) follow the
-same four verbs:
-  - list   GET  <collection>            — filter/sort/limit/offset; the default row is minimal scalars,
-                                           opt into more with \`fields\`.
-  - get    GET  <collection>/:id        — one resource; \`fields\` opts into relations/heavy data the same way.
-  - create POST <collection>            — the resource's own required fields; a 400 names any missing/invalid one.
-  - update PATCH/PUT <collection>/:id   — send only the fields you are changing; most resources require the
-                                           concurrency token below when the edit touches contested text fields.
-                                           A card is the exception: PATCH /api/issues/<id>/edit.
-  - delete DELETE <collection>/:id      — usually a soft-delete; the resource's own docs say so.
-Don't know the route for what you need to do? Call \`danxbot_api_list()\` — it lists exactly the routes your
-credential may call, one line each. Then call \`danxbot_api_spec({endpoints: ["METHOD /path/template"]})\` for the
-EXACT current shape of the one(s) you picked, before calling them through \`danxbot_api\` — request/response
-schema, required permission, and every documented error envelope. Never guess a field name or a route path.
+RESOURCES. Most collections take GET (list) and POST (create); a single resource (\`<collection>/<id>\`) takes
+GET, PATCH or PUT (send only the fields you change) and DELETE. A card is edited at
+\`PATCH /api/issues/<id>/edit\`. A list or get answers scalars only: name each relation or heavy field you need in
+the \`fields\` query tree. \`GET /api/resources/<resource>/fields\` lists the names.
 
-ALWAYS PASS \`fields\`. The default response for a list/get route is minimal — scalars only, no relations, no
-heavy text. Every resource that supports it takes a \`fields\` query param (a JSON field tree) that opts into exactly what you need. Passing nothing and then being surprised a field is
-missing is a caller bug, not a server one — check the spec for the resource's own field vocabulary.
+STALE HASH. A write to contested text (a card's title, description or checklists, a plan record, a problem) sends
+back the \`content_hash\` or \`base_hash\` you read from that resource. A stale hash is refused 409 with the current
+hash and content: merge your change into that and retry with the fresh hash.
 
-THE STALE-HASH RULE. A write that touches contested text (a card's title/description/checklists, a plan
-record, a problem, ...) is optimistic-concurrency guarded by a \`content_hash\` / \`base_hash\` you must have read
-FIRST (from the same resource's own \`get\`/\`list\` response) and send back unchanged. A stale hash 409s with the
-CURRENT hash and CURRENT content in the body — re-read, merge, retry with the fresh hash. Never retry blindly
-with the same stale value, and never omit the hash hoping the write "just works" — omission is refused exactly
-like a stale value on any route that requires one.
+REFUSALS. A 4xx body is \`{error, ...}\`, and its other fields name the fix: \`offending_keys\`, \`failed_gate\`,
+\`unresolved_items\`, \`did_you_mean\`. Read it before you retry.
 
-A 4XX BODY NAMES THE FIX. Every refusal is structured, never a bare string: \`{error, ...extra}\`, where the
-extra fields tell you exactly what to do next — \`offending_keys\` (an unknown/invalid field, by name),
-\`failed_gate\` (which lifecycle/dispatch gate blocked a transition), \`currentHash\`/\`currentContent\` (a stale-
-hash 409, ready to merge from), \`unresolved_items\` (which checklist items still block completion). Read the
-body before retrying — the shape is the same one \`danxbot_api_spec\` documents per route, so a persistent 4xx
-you don't understand means re-checking the spec, not repeating the same call.
-
-WRITING STANDARD — for any tool that writes prose onto a card, plan record, or problem (title, summary,
-description, context, a problem's statement, a solution's body, ...). The reader is new to the subject and has
-not read, and will not read, the code or docs: what you write IS their documentation. Define any term a
-newcomer would not know where it first appears. Open with plain background — what the thing is, why it exists,
-what is wrong or what the choice changes — before evidence or technical detail. Cite ids/SHAs/paths precisely
-rather than describing them vaguely ("the migration file" → the actual filename). Be brief: the goal is less to
-read, not more, not a transcript of your reasoning. A summary/title alone must let the reader decide without
-opening the description.
+WRITING STANDARD, for every title, summary, description, comment, problem, solution and plan record you write. The
+reader is new to the subject and will not read the code or docs: what you write is their documentation. Open with
+plain background (what the thing is, why it exists, what is wrong or what the choice changes) before evidence.
+Define each term a newcomer would not know. Cite exact ids, SHAs and paths. Be brief: less to read, never a
+transcript of your reasoning. A title or summary alone must let the reader decide.
 `;
+assertWithinTextLimit("the server instructions", SERVER_INSTRUCTIONS);
 export const server = new McpServer({
     name: "danx-dashboard-mcp",
     version: "0.1.0",
@@ -309,6 +288,8 @@ function jsonResult(value) {
  * set, exactly like the dashboard's own `parseFilterObject` refusal.
  */
 function strictTool(name, description, shape, cb) {
+    // DX-4318 — the one registration path, so no tool can ship a description an agent would receive cut.
+    assertWithinTextLimit(`the "${name}" tool description`, description);
     return server.registerTool(name, { description, inputSchema: z.object(shape).strict() }, cb);
 }
 // ---------------- lifecycle tool set (DX-3465 / PLN-11 R-25) ----------------
@@ -342,15 +323,11 @@ const boardField = {
 // `danxbot_api({method:"GET", path:"/api/resources/<resource>/fields"})`
 // instead; the route and its response shape are unchanged.
 // ---------------- danxbot_api (DX-3465, PLN-11 R-25) ----------------
-strictTool("danxbot_api", "Call any dashboard API route your credential may reach. `method` + `path` (a FULL path, e.g. " +
-    '"/api/issues/DX-1/transition" — substitute real ids yourself, never a route template with `:id` in it) + ' +
-    // DX-3997 — `reminders[]` also relays the dashboard's own listener reminder
-    // to a plan-connected session; the reminder's text explains itself.
-    "optional `query`/`body`. The response is the route's JSON body verbatim, `reminders[]` included when the " +
-    "route attaches one. `board` overrides this dispatch's configured board for a board-scoped route only. " +
-    "See this server's own instructions (shown once, at connect) " +
-    "for the shared resource shape, the stale-hash rule, and how to read a refusal — don't know the route? call " +
-    "`danxbot_api_list` first. " +
+strictTool("danxbot_api", 
+// DX-3997 — `reminders[]` also relays the dashboard's own listener reminder
+// to a plan-connected session; the reminder's text explains itself.
+"Call any dashboard API route your credential may reach. The answer is the route's JSON body: act on its " +
+    "`reminders[]` when present. " +
     // DX-4015 — the ONE statement of which writes need a spec call first; the
     // `work` profile's spec-first sentence defers to this list. A shown write
     // is copied from its example (3 of 3 canary sessions did, with zero 4xx).
@@ -367,7 +344,7 @@ strictTool("danxbot_api", "Call any dashboard API route your credential may reac
         .describe('Full path starting with "/api/" — never a route template.'),
     // DX-3465 — a query value may be a scalar, a field TREE (a plain
     // object, e.g. `{"description":true,"comments":{"limit":20}}` — see
-    // SERVER_INSTRUCTIONS below and the OpenAPI spec's `fields` schema), or
+    // SERVER_INSTRUCTIONS above and the OpenAPI spec's `fields` schema), or
     // an array of scalars (e.g. `ids` on the batch-get route).
     // `DashboardHttpClient#buildUrl` JSON-encodes a plain object but
     // comma-joins an array, matching the two shapes the server actually
@@ -401,22 +378,18 @@ async (args) => {
     return jsonResult(await listenerReminder.apply(result));
 });
 // ---------------- danxbot_api_list (DX-3465 A5, PLN-11 R-25) ----------------
-strictTool("danxbot_api_list", "Lists the dashboard API routes your credential may call right now — `[{method, path, summary, permission}]`, " +
-    "one line each, in the route TEMPLATE form `danxbot_api_spec` also expects (e.g. " +
-    '`"POST /api/issues/:id/transition"`). This is how you find the route for something you need to do: a ' +
-    "route listed here is always callable by you; one that isn't never appears (DX-3528 filters through the " +
-    "SAME permission check the dashboard enforces on every request, so this list can never drift from what " +
-    "you can actually call). No arguments. Call this when you don't already know the route, then " +
-    "`danxbot_api_spec({endpoints})` for the exact contract of the one(s) you picked, then `danxbot_api` to " +
-    "call it.", {}, async () => jsonResult(await danxbotApiList(client)));
+strictTool("danxbot_api_list", 
+// DX-3528 — the list is filtered by the same permission check every request takes.
+"Lists the dashboard API routes your credential may call: `[{method, path, summary, permission}]`, each " +
+    "`path` a route template (`/api/issues/:id/transition`), the form `danxbot_api_spec` takes. A route not " +
+    "listed is not callable by you.", {}, async () => jsonResult(await danxbotApiList(client)));
 // ---------------- danxbot_api_spec (DX-3465, PLN-11 R-25) ----------------
-strictTool("danxbot_api_spec", "The exact OpenAPI 3.1 contract (DX-3527) for one or more routes — request/response shape, required " +
-    "permission, and every documented error envelope. `endpoints` (REQUIRED, non-empty): an array of " +
-    '`"METHOD /path/template"` strings (e.g. `"POST /api/issues/:id/transition"`, the route TEMPLATE form, ' +
-    "unlike `danxbot_api`'s own `path` which is a real path with real ids — the same form `danxbot_api_list` " +
-    "reports). A requested endpoint this dashboard does not serve, or that your credential may not call, is " +
-    "refused loud (never silently dropped or silently included) — see the response for which. Don't know which " +
-    "endpoints to name? call `danxbot_api_list` first.", {
+strictTool("danxbot_api_spec", 
+// DX-3527 — the contract is generated from the route table.
+"The OpenAPI 3.1 contract for the routes you name: request and response shape, required permission and " +
+    'every documented error. `endpoints`: `"METHOD /path/template"` strings as `danxbot_api_list` reports them ' +
+    '(e.g. `"POST /api/issues/:id/transition"`), never a real path with ids. An endpoint the dashboard does ' +
+    "not serve, or your credential may not call, is refused and named.", {
     endpoints: z.array(z.string().min(1)).min(1),
 }, async (args) => jsonResult(await danxbotApiSpec(client, args)));
 // ---------------- attach_file (DX-3465 A4, checklist item 36140) ----------------
@@ -429,18 +402,12 @@ strictTool("danxbot_api_spec", "The exact OpenAPI 3.1 contract (DX-3527) for one
 // out plus a role-by-role grant, see `tool-defs.ts`'s `MCP_SERVER_OPT_IN_TOOLS`
 // — a role needs local-file-upload only when it deals with files an agent
 // might hold locally, e.g. the Slack recovery agent's CSV path).
-strictTool("attach_file", "Attach a LOCAL file to a card: `card_id` + `path` (an ABSOLUTE path on the dispatch's shared filesystem). " +
-    "Reads the bytes INSIDE this MCP server process and uploads them — the file's bytes never pass through " +
-    "your own context/transcript. Infers MIME from the extension unless you pass `content_type`; defaults " +
-    "`filename` to the path's basename unless you pass one. Stores in S3, inserts one attachment row, auto-" +
-    "mirrors to the card's linked Trello card and Slack thread. Board-scoped; see `board`. Fail-loud: a " +
-    "relative/empty path is rejected before any upload; a missing/unreadable file throws before any upload " +
-    "(no partial S3 object or row). 25 MB decoded ceiling (413). Returns `{issue, attachment_id, s3_key}` — " +
-    "find the attachment in `issue.attachments` by `attachment_id` to read its permanent, non-expiring `url`. " +
-    "That url can be embedded in ANY markdown field (a problem's statement/context, a comment, a plan record, " +
-    "a solution body) as `![description](url)` — the dashboard renders it inline as a thumbnail. Use whenever " +
-    "a screenshot or a local file judges something faster than prose, or replaces pasting a large CSV/log " +
-    "straight into a card field.", {
+strictTool("attach_file", "Attach a LOCAL file to a card. This server reads and uploads the bytes, so they never pass through your " +
+    "context. The attachment mirrors to the card's linked Trello card and Slack thread. 25 MB limit (413). " +
+    "Returns `{issue, attachment_id, s3_key}`: the entry of `issue.attachments` with that `attachment_id` " +
+    "carries a permanent `url`: embed it in any markdown field as `![description](url)` and it renders " +
+    "inline. Use it when a screenshot or file judges something faster than prose, or instead of pasting a " +
+    "large CSV or log into a card field.", {
     card_id: z.string().min(1).describe("The card id to attach the file to."),
     path: z
         .string()
@@ -461,14 +428,21 @@ strictTool("attach_file", "Attach a LOCAL file to a card: `card_id` + `path` (an
 // a different reason: it MAKES a plan rather than acting on one, so there is
 // no existing plan for an id to name yet.
 strictTool("plan_connect", 
-// DX-2735: trimmed with the problem tools to stay inside the work-profile budget.
-"Connect THIS session to a plan. ONE CALL IS ENOUGH TO START: the reply carries `{session, movedFrom, browserInstruction, briefing, listenerHealth, missedEvents}` — `missedEvents` is `{events, omitted}`: the operator events on this plan that no session had been told about before you connected, oldest first, capped to the newest few (`omitted` counts the older ones left out) — read them before anything else. `browserInstruction` is a server-built action to take NOW: it names the plan's URL and tells you to open it (in-app browser if you have one, else default), keep that tab open for the whole session without navigating it away, and use a different tab for your own browsing — the operator's tab for following and talking to you. Returned on every connect, including a re-connect, so it doubles as the post-context-loss reminder. `briefing` is every goal/rule/caveat (ref+body), every architecture section (id+title), the plan's own ref/name/status, a first page of open cards (id/type/status/title/openProblemCount/assignedAgent) with a `morePagesHint` when more exist, and the closed-card count — usually replacing the plan read + card batch-read a fresh session used to need. A session is on AT MOST ONE plan: connecting elsewhere MOVES it, and `movedFrom: {id, name} | null` says which plan it left (null = no plan, or already this one). Binds only your OWN session, resolved from the session id this server forwards; afterwards a `danxbot_api` call to a `/api/plans/mine/...` route (there is no dedicated plan-write tool) acts on this plan and takes no plan id. `listenerHealth` reports the event bridge's state — `null` (no session), or `{attached, state: \"unattached\"|\"credential_mismatch\"|\"healthy\", nextStep}` naming a concrete fix per unhealthy state (same shape the plan list/get routes report). Once healthy, every comment, answer, problem added and block/unblock on this plan's cards reaches the session unpolled, relayed by the plugin's event bridge as a line like `[DX-8 \"Title\" repo:board] newms87 answered \"<statement>\": chose \"Pause E2E\"`. An action the operator DECLINES arrives as `... rejected the action \"<title>\" for \"<statement>\" — reason: \"<note>\". Do not perform it; re-plan from the reason` (a decision with `outcome: \"rejected\"` — never treat it as work done). Pass `title` (call `get_session({session_id:\"self\"})` first and forward its `title` verbatim) so the dashboard shows the same name Claude does — this server cannot read it itself. The response's `reminders[]` (when present) carries the mantra — read and follow it. To LEAVE: `{plan_id: <current plan>, disconnect: true}` returns `{session, leftPlan}`; a wrong plan is a 409.", {
+// DX-4318 — states only what to do with the reply. What it used to add arrives where it is used: a rejected
+// action's rule in the event line itself (`listen.ts`), the mantra in the reply's own `reminders[]` text.
+"Connect THIS session to a plan; one call is enough to start. The reply carries `missedEvents` (operator " +
+    "events on the plan that no session had been told about, oldest first: read them first), " +
+    "`browserInstruction` (do it now), `briefing` (the plan's goals, rules, caveats, architecture section " +
+    "titles and a first page of open cards) and `listenerHealth` (when its `state` is not `healthy`, do its " +
+    "`nextStep`). A session is on at most one plan: connecting elsewhere moves it, and `movedFrom` names the " +
+    "plan it left. Afterwards a `danxbot_api` call to a `/api/plans/mine/...` route acts on this plan and " +
+    "takes no plan id.", {
     plan_id: z.number().int().positive().describe("The plan id, from the plans list (`danxbot_api` `GET /api/plans`)."),
     title: z
         .string()
         .min(1)
         .optional()
-        .describe("THIS session's own Claude session title — from `get_session({session_id:\"self\"}).title`, passed verbatim, never invented or derived from the repo/cwd. Stored on your session's row: a title different from what is already stored UPDATES it; omit to leave the stored title untouched. Not this plan's name. At most 200 characters — an overlong title is refused with a 400 naming its length."),
+        .describe('This session\'s own Claude title: `get_session({session_id:"self"}).title`, verbatim, never invented and never the plan\'s name. Omit to keep the stored title.'),
     disconnect: z.boolean().optional().describe("true = leave `plan_id` (your current plan); no `title`."),
 }, 
 // DX-2862 — the connect is also the moment this session's event bridge learns

package/dist/lifecycle.js

@@ -181,10 +181,10 @@ export function registerLifecycleTools(strictTool) {
             "cancelled = agent voluntarily abandons the dispatch (does NOT cancel the card — transition it first); " +
             "critical_failure = environment broken in a way that affects every dispatch (MCP tools not loading, " +
             "Bash unavailable, Claude auth missing) — halts the poller until a human clears it; " +
-            "waiting_on_dependency = genuinely blocked on a card that must land on another board/repo — file that " +
-            "change as a card on the right board, add a depends_on edge from yours to it, commit your own WIP, " +
-            "transition yours rollback_pickup, then end with this status (never complete/ready/archive/review, " +
-            "which delete your branch)."),
+            // DX-4318 — the steps live in each profile that grants this ending (`work` and `failure-repair`,
+            // `required-profiles.yaml`), never repeated here.
+            "waiting_on_dependency = blocked on a card that must land on another board or repo: do your " +
+            "profile's steps for work that needs another repo or board's change first."),
         summary: z
             .string()
             .describe("Brief summary of what happened. For failed, why the dispatch stopped, " +
@@ -213,16 +213,16 @@ export function registerLifecycleTools(strictTool) {
         };
     });
     // ---------------- danxbot_slack_reply ----------------
-    const slackReply = strictTool("danxbot_slack_reply", "Post the FINAL user-facing reply to the originating Slack thread. Call exactly once per dispatch, " +
-        "immediately before danxbot_complete. Optionally attach result files via files[] (absolute paths of files on YOUR own " +
-        "disk — their bytes are uploaded, so this works whichever host the dashboard runs on) — text + attachments " +
-        "land as ONE atomic thread post. For intermediate " +
-        "progress use danxbot_slack_post_update instead.", {
+    const slackReply = strictTool("danxbot_slack_reply", 
+    // DX-4253 — no ordering against another tool here: the Slack persona (`src/agent/persona.ts`) and the
+    // `slack-agent` profile own the order (reply, link, attach, complete).
+    "Post the final user-facing reply to the originating Slack thread, once per dispatch. Files in `files[]` " +
+        "post with the text as one thread message. For progress updates use danxbot_slack_post_update.", {
         text: z.string().describe("The final reply text to post to the Slack thread."),
         files: z
             .array(z.string())
             .optional()
-            .describe("Optional absolute paths of files on your own disk to attach; their bytes are uploaded."),
+            .describe("Absolute paths of your own files to attach; bytes are uploaded."),
     }, async (args) => {
         const url = readLifecycleUrlsFromEnv().slackReply;
         if (!url)
@@ -350,27 +350,21 @@ export function registerLifecycleTools(strictTool) {
         return { content: [{ type: "text", text: JSON.stringify(result) }] };
     });
     // ---------------- quality_gate_complete (absorbs quality_gate_skip, DX-3394 problem 1682) ----------------
-    const qualityGateComplete = strictTool("quality_gate_complete", "Sign off a registered quality gate. NEVER visible to (or callable by) the WORK dispatch that authored " +
-        "the diff — DX-3741: every gate, PLAN or CODE, runs as its OWN independent gate-reviewer dispatch, so " +
-        "seeing this tool at all means you ARE that reviewer, not the author. Two flavors by the gate's PHASE: " +
-        "(PLAN, e.g. plan-architecture) — reviews the CARD's plan before any code exists; this call is your " +
-        "dispatch's TERMINAL call: status='pass' releases the dispatch (the picker launches the next gate or " +
-        "the work agent); status='fail' BLOCKS the card (your message becomes the reason) and stops the " +
-        "dispatch (do NOT follow up with danxbot_complete); status='retry' — the fixer loop: you edited the " +
-        "card into a sounder plan and want a fresh pass. (CODE, e.g. code-quality) — reviews `git diff " +
-        "origin/main...HEAD` on the author's `card/<id>` branch, already pushed to origin; this call is ALSO " +
-        "your dispatch's TERMINAL call: report every finding via `findings[]`; status='fail' releases the " +
-        "dispatch and — BELOW the per-gate review-pass cap — does NOT block the card: the author's WORK " +
-        "session, re-dispatched, reads your findings, fixes them, and calls request_code_review again, which " +
-        "re-dispatches every requested code gate fresh; AT the cap (3 review passes, the runaway backstop) a " +
-        "'fail' DOES block the card instead, exactly like a PLAN-phase fail — you are not told which round " +
-        "this is, so sign 'fail' on the findings alone and let the dispatcher enforce the cap; " +
-        "status='pass' releases the dispatch toward the next requested code gate or back to WORK to finalize; " +
-        "status='retry' is PLAN-phase only, refused here. status='skipped' — the gate is OBVIOUSLY " +
-        "UNNECESSARY for this diff (a single-line / docs-only change, or nothing in this gate's lane): use " +
-        `\`message\` as the mandatory justification (≥${QUALITY_GATE_SKIP_REASON_MIN_CHARS} chars, the ` +
-        "permanent accountability record a human will read) — never skip to dodge a real review. You never " +
-        "edit files and never transition the card yourself, on either phase.", {
+    const qualityGateComplete = strictTool("quality_gate_complete", 
+    // DX-3741 — every gate runs as its own gate-reviewer dispatch, the only one that sees this tool. DX-4318 —
+    // what a status does, per phase; how to review (read-only, no transition) is the gate-reviewer profile's
+    // (`required-profiles.yaml`). The "3-pass cap" mirrors CODE_GATE_MAX_REVIEW_PASSES
+    // (`src/issues/quality-gates/registry.ts`), which this separately published package cannot import;
+    // `src/tokens/tool-defs.test.ts` compares the two.
+    "Sign off the quality gate you are reviewing. It is your dispatch's TERMINAL call: never follow it with " +
+        "danxbot_complete. PLAN gate: `pass` releases the card to the next gate or the work agent; `fail` blocks " +
+        "the card with `message` as the reason; `retry` means you edited the card into a sounder plan and want " +
+        "a fresh pass. CODE gate: report every finding in `findings[]`; `fail` returns the findings to the " +
+        "author, who fixes them and requests review again, and at the 3-pass cap blocks the card instead (sign " +
+        "on the findings alone; the dispatcher enforces the cap); `pass` releases toward the next code gate or " +
+        "the author's finalize; `retry` is refused. `skipped`: the gate obviously does not apply to this diff " +
+        "(one line, docs only, nothing in its lane), with `message` as the mandatory justification of at least " +
+        `${QUALITY_GATE_SKIP_REASON_MIN_CHARS} characters; never skip to dodge a real review.`, {
         gate: z.string().describe("Registered gate name, e.g. 'plan-architecture' or 'code-quality'."),
         status: z.enum(["pass", "fail", "retry", "skipped"]),
         message: z

package/dist/text-limit.js

@@ -0,0 +1,24 @@
+/**
+ * DX-4318 — Claude Code delivers at most 2,048 characters (string length, not
+ * bytes) of an MCP server's instructions and of each tool description, then
+ * appends `… [truncated]`; nothing fails. Measured 2026-10-03 on three texts
+ * of this server, each cut at index 2,048. The limit here keeps 48 characters
+ * of headroom under that cut.
+ *
+ * Whether Claude Code also cuts a parameter description is unverified: none
+ * is long enough to show it. The package test holds them to the same limit, so
+ * the question stays moot.
+ */
+export const MCP_TEXT_LIMIT_CHARS = 2000;
+/**
+ * Refuses a text an agent would receive cut. Called where each text is
+ * registered, so an over-long one stops the module from loading: the package
+ * tests, the `tool-defs.json` generator and the publish boot check all fail
+ * on it.
+ */
+export function assertWithinTextLimit(label, text) {
+    if (text.length > MCP_TEXT_LIMIT_CHARS) {
+        throw new Error(`[danx-dashboard-mcp] ${label} is ${text.length} characters, over the ${MCP_TEXT_LIMIT_CHARS}-character limit: ` +
+            `Claude Code would cut it and the agent would never see the rest. Shorten it.`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.219",
+  "version": "0.1.221",
   "description": "Stdio MCP server fronting danxbot's dashboard API for agents (operator sessions and dispatched workers alike): the generic danxbot_api/danxbot_api_list/danxbot_api_spec tools reach any route the caller's credential may call, plus dedicated agent-specific tools (plan_connect, danxbot_complete, and other per-dispatch lifecycle callbacks) (DX-3465, PLN-11 R-25).",
   "license": "MIT",
   "type": "module",