@adrata/adrata-mcp 1.0.0

package/tools/work-board-tools.js

@@ -0,0 +1,758 @@
+/**
+ * Work-board tools for the Adrata MCP Server.
+ *
+ * These let a coding agent (Claude Code, Codex, Cursor, …) read and reorganise
+ * a Starfield board through the SAME governed endpoints the UI calls. There is
+ * no second path into the data: `/api/v1/work-boards`, `/api/v1/work-items`,
+ * and `/api/v1/work-board-rollups` are the only surface, so workspace scoping,
+ * validation, and the transactional move all hold identically whether a human
+ * dragged the card or an agent moved it.
+ *
+ * Reads (list boards, read a board, read a card, read a roll-up) are ordinary.
+ *
+ * WRITES ARE NOT. Moving a card and changing a tag are the exact case the
+ * repo's workspace rules exist for — an agent reorganising somebody's backlog —
+ * so they follow the same contract as every other governed write here:
+ *
+ *   dryRun defaults to TRUE. A live write needs dryRun:false AND approved:true
+ *   AND a reason AND an idempotencyKey.
+ *
+ * The idempotency key is not ceremony. A retried move that appended a second
+ * transition would make the card look like it had bounced between columns, and
+ * the stage timer and any cycle-time reporting are derived from exactly those
+ * rows. Reuse the same key on retry and the server replays instead.
+ *
+ * Tier: enterprise (OAuth workspace connection), same as the other tools that
+ * read and mutate real workspace records.
+ */
+
+/**
+ * Reasons that are technically present and practically worthless.
+ *
+ * The board's own drag default used to be "Moved to another column", and a
+ * history full of that line is worse than an empty one: it looks like an audit
+ * trail, so nobody goes looking for the real answer. These are the ones an agent
+ * reaches for when it has nothing to say — and an agent that has just done the
+ * work always has something to say.
+ */
+const PLACEHOLDER_REASONS = new Set([
+  'move',
+  'moved',
+  'moving',
+  'moving card',
+  'moved card',
+  'moved to another column',
+  'move to another column',
+  'column change',
+  'board update',
+  'agent move',
+  'update',
+  'updated',
+  'change',
+  'changes',
+  'fix',
+  'fixed',
+  'done',
+  'complete',
+  'completed',
+  'finished',
+  'wip',
+  'work in progress',
+  'triage',
+  'triaged',
+  'cleanup',
+  'housekeeping',
+  'as requested',
+  'per request',
+  'no reason',
+  'n/a',
+  'na',
+  'test',
+  'testing',
+]);
+
+/** The shortest reason that could plausibly name a branch, a PR, or a change. */
+const MIN_AUDITABLE_REASON = 12;
+
+/**
+ * Why this reason would be useless in the card's history, or `null` if it is
+ * fine.
+ *
+ * The governed contract already REQUIRES a reason; this is about the reason
+ * being worth the row it is stored on. `work_item_column_history.reason` is
+ * rendered on the card, and it is the only thing that answers "why did this take
+ * a week" three weeks later — the branch name will not.
+ *
+ * An empty reason is deliberately NOT this function's business: the bridge
+ * validator refuses that with its own message, and duplicating it here would
+ * give two different errors for one mistake.
+ */
+export function describeUnauditableReason(reason) {
+  const trimmed = String(reason ?? '').trim();
+  if (!trimmed) return null;
+
+  const normalized = trimmed
+    .toLowerCase()
+    .replace(/[.!]+$/, '')
+    .replace(/\s+/g, ' ');
+  const advice =
+    'Say what a human will need: a branch name, a PR link, or one line naming what changed and how it was verified — e.g. "Fixed the N+1 in the export query on fix/export-n1; added a test at 10k rows, suite green".';
+
+  if (PLACEHOLDER_REASONS.has(normalized)) {
+    return `"${trimmed}" is a placeholder, not a reason. It restates the move the history already records. ${advice}`;
+  }
+  if (trimmed.length < MIN_AUDITABLE_REASON) {
+    return `"${trimmed}" is too short to audit. ${advice}`;
+  }
+  return null;
+}
+
+/**
+ * Why a card with no body will not be workable, or `null` if it has one.
+ *
+ * Deliberately the weakest possible check. The card model says a Task carries
+ * acceptance criteria — the artifact with two consumers, the build spec for the
+ * agent and the test plan for QA — and today those criteria live in `body`,
+ * because there is no `acceptance_criteria` column yet. But "does this prose
+ * contain acceptance criteria" is a judgement, not a pattern: a regex looking
+ * for the word would pass a heading with nothing under it and fail a perfectly
+ * good "the Export button is disabled while an export is running". Asserting it
+ * either way would be the tool inventing a verdict.
+ *
+ * A MISSING body is a fact, so that is what this reports — as a note on the
+ * dry-run preview, where a human is already deciding, and never as a refusal.
+ * Blocking a thin capture is how a card ends up not written down at all, which
+ * is worse than a thin one.
+ */
+export function describeMissingBody(body) {
+  if (String(body ?? '').trim()) return undefined;
+  return 'This card would arrive with a title and nothing else. A card is the unit of QA sign-off, so with no body it carries no acceptance criteria — nobody can validate it and no agent can build from it. Add the criteria to `body` (one checkable outcome per line), or say in the body what is still unknown.';
+}
+
+/**
+ * Register the work-board tools.
+ *
+ * @param {McpServer} server - the MCP server instance (already tier-gated)
+ * @param {object} deps - { z, api, ok, validateApiBridgeRequest, buildMutationHeaders }
+ */
+export function registerWorkBoardTools(
+  server,
+  { z, api, ok, validateApiBridgeRequest, buildMutationHeaders }
+) {
+  const GOVERNED_NOTE =
+    ' Governed write: previews by default. A live write requires dryRun:false plus approved:true, a reason, and an idempotencyKey (reuse the SAME key on retry — a duplicate move would read as the card having bounced between columns).';
+
+  // =========================================================================
+  // READS
+  // =========================================================================
+
+  server.tool(
+    'list_my_work_items',
+    `The cards that are YOURS, across every board in the workspace, ordered the way a developer actually picks: escalated first (the top band of each card's OWN scheme — a P1 is never equated with a Critical), then by the board's own left-to-right flow so the earliest active stage comes first, then longest-waiting. Cards in a terminal column (Production, Deep backlog) sink to the bottom, because nothing should be picked up from them.
+
+"Yours" is TWO things: cards you OWN (you are the assignee, carrying it end to end) and cards whose CURRENT PASS you hold (you took it at a stage — the QA case). Both appear here, and each card carries assignee and handler so you can tell which of the two put it in front of you. A QA person owns none of the cards they are testing, so a queue keyed only on the assignee would tell them they had no work while four cards sat on their bench.
+
+"You" is resolved from the authenticated token. There is deliberately NO parameter naming a user, and the endpoint refuses one rather than ignoring it — otherwise one agent could read another developer's queue through the very tool meant to keep them off each other's cards. To see somebody else's work, read their board with get_work_board.
+
+Start here for "what should I work on". With includeUnassigned it also returns the cards nobody owns AND nobody is handling, which are the ones free to take (move_work_item with claim:true).`,
+    {
+      includeUnassigned: z
+        .boolean()
+        .optional()
+        .describe(
+          'Also return the cards nobody owns and nobody is handling — the pool that is genuinely free. Use it when your own queue is empty, instead of pulling whole boards and eyeballing them. Note this is NOT "free QA passes": a card an engineer owns, waiting untaken in a QA column, is free to HANDLE but not free to own, so it stays off this list — read the QA columns with get_work_board for those.'
+        ),
+      boardId: z.string().optional().describe('Narrow to one board. Omit for every board.'),
+      limit: z
+        .number()
+        .optional()
+        .describe('Cap each list. Defaults to 50; a queue that needs a second page is not a queue.'),
+    },
+    async (args) => {
+      const params = new URLSearchParams();
+      if (args.includeUnassigned === true) params.set('includeUnassigned', 'true');
+      if (args.boardId) params.set('boardId', args.boardId);
+      if (args.limit !== undefined) params.set('limit', String(args.limit));
+      const query = params.toString();
+      const data = await api(
+        'GET',
+        `/api/v1/work-items/assigned-to-me${query ? `?${query}` : ''}`
+      );
+      const queue = data?.data || {};
+      const mine = queue.assignedToMe || [];
+      return ok({
+        me: queue.me,
+        count: mine.length,
+        assignedToMe: mine,
+        unassigned: queue.unassigned,
+        // An empty queue is a fact, not a failure — and the two empty answers
+        // mean different things to whoever asked.
+        note:
+          mine.length === 0
+            ? args.includeUnassigned
+              ? 'You own nothing and are handling no passes. The unassigned list is what is free to take.'
+              : 'You own nothing and are handling no passes. Call again with includeUnassigned:true to see what is free to take.'
+            : undefined,
+      });
+    }
+  );
+
+  server.tool(
+    'list_work_boards',
+    'List the work boards in the connected workspace. Returns each board id, name, the company it is run for (if any), and the tag scheme its cards are read under. Start here — every other board tool needs an id from this list.',
+    {},
+    async () => {
+      const data = await api('GET', '/api/v1/work-boards');
+      const boards = data?.data || [];
+      return ok({
+        count: boards.length,
+        boards,
+        // An empty list is a fact, not a failure. Say which one it is so the
+        // agent does not report "no work" when it simply has no boards yet.
+        note: boards.length === 0 ? 'This workspace has no boards yet.' : undefined,
+      });
+    }
+  );
+
+  server.tool(
+    'get_work_board',
+    'Read one board whole: its columns (each with its own staleness policy) and every card on it. The card list carries columnId, enteredColumnAt, position, and the stored tag — everything needed to reason about what is stale and what matters.',
+    {
+      boardId: z.string().describe('Board id from list_work_boards.'),
+    },
+    async (args) => {
+      const data = await api('GET', `/api/v1/work-boards/${encodeURIComponent(args.boardId)}`);
+      const board = data?.data;
+      return ok({
+        board,
+        // Staleness is a property of the COLUMN, not the board — three days in
+        // Triage is alarming, three days in In review is a Tuesday. Say so, or
+        // an agent will apply one threshold across the whole board.
+        howToReadStaleness:
+          'Each column carries its own agingAfterHours/staleAfterHours. A MISSING bound means the column never ages (a Done column) — it does not mean zero. Compare a card\'s enteredColumnAt against ITS OWN column\'s policy.',
+      });
+    }
+  );
+
+  server.tool(
+    'get_work_item',
+    'Read one card by id: title, body, product, assignee, reporter, creator, its stored tag, and how long it has been in its current column. THREE DIFFERENT PEOPLE can appear on a card and they answer different questions: `assignee` is who is doing it (and changes hands over the card\'s life), `reporterPersonId` is the customer who asked (only on a card ingested from email), and `createdBy` is the teammate who wrote the card — resolved to a name, never changing, and the person to ask what the card meant. An absent `createdBy` means the card predates creator tracking, not that nobody made it.',
+    {
+      itemId: z.string().describe('Card id.'),
+    },
+    async (args) => {
+      const data = await api('GET', `/api/v1/work-items/${encodeURIComponent(args.itemId)}`);
+      return ok({ item: data?.data });
+    }
+  );
+
+  server.tool(
+    'get_work_item_history',
+    'Read a card\'s column transitions, newest first: which column it came from, which it went to, when it entered and left, who moved it, and why. This is the audit trail the stage timer is derived from — use it to answer "how long did this actually take" rather than guessing from the current column.',
+    {
+      itemId: z.string().describe('Card id.'),
+    },
+    async (args) => {
+      const data = await api(
+        'GET',
+        `/api/v1/work-items/${encodeURIComponent(args.itemId)}/history`
+      );
+      const transitions = data?.data || [];
+      return ok({ count: transitions.length, transitions });
+    }
+  );
+
+  server.tool(
+    'get_work_board_rollup',
+    'Read several boards as one prioritisation view. Pass "all" for the implicit roll-up of every board in the workspace (it has no membership rows, so a board created a minute ago is already in it), or a roll-up id for a curated one. Each slice keeps its own board, company, staleness policy, and tag scheme — cards are ranked WITHIN their own scheme and never translated across schemes, so a P1 is never silently equated with a Critical.',
+    {
+      rollupId: z
+        .string()
+        .optional()
+        .describe('Roll-up id, or "all" (the default) for every board in the workspace.'),
+    },
+    async (args) => {
+      const rollupId = args.rollupId || 'all';
+      const data = await api(
+        'GET',
+        `/api/v1/work-board-rollups/${encodeURIComponent(rollupId)}`
+      );
+      return ok({ rollup: data?.data });
+    }
+  );
+
+  server.tool(
+    'list_work_board_rollups',
+    'List the curated roll-ups in the workspace. The implicit "all boards" roll-up is NOT in this list because it has no row — read it with get_work_board_rollup using rollupId "all".',
+    {},
+    async () => {
+      const data = await api('GET', '/api/v1/work-board-rollups');
+      const rollups = data?.data || [];
+      return ok({ count: rollups.length, rollups });
+    }
+  );
+
+  server.tool(
+    'get_work_item_comments',
+    'Read what people have SAID about a card, oldest first: each comment\'s author, body, and timestamp. READ THIS BEFORE STARTING WORK, alongside get_work_item_history. The history says which columns a card passed through; the comments say WHY — a card that came back from QA has the reviewer\'s reason here, and repeating a rejected approach is the most expensive mistake available on this board. A comment marked withdrawn is still returned with its text: its author took the claim back, but somebody may already have acted on it, so it is context and not noise. If the card carries a `flag`, the reason it was raised is in this thread too.',
+    {
+      itemId: z.string().describe('Card id.'),
+    },
+    async (args) => {
+      const data = await api(
+        'GET',
+        `/api/v1/work-items/${encodeURIComponent(args.itemId)}/comments`
+      );
+      const comments = data?.data || [];
+      return ok({
+        count: comments.length,
+        comments,
+        howToRead:
+          'Oldest first, so the thread reads forwards. Read `bodyText` — it is `body` with every @-mention resolved to a name. `body` is the STORED form and carries `<@userId>` tokens; keep it only if you intend to edit the comment, since saving `bodyText` back would turn every mention into a literal name. `withdrawnAt` means the author retracted it — the text is kept because somebody may have acted on it. `edited` means the text changed after posting. `mentions` lists the workspace members the comment names.',
+      });
+    }
+  );
+
+  // =========================================================================
+  // WRITES
+  // =========================================================================
+
+  server.tool(
+    'move_work_item',
+    `Move a card to another column on the same board — and, with claim:true, pick it up in the same action. The server does this in ONE transaction: it closes the card's open dwell, appends the transition to the history, records you as the handler of the pass the card is now on, and updates the card. Dropping a card into the column it is already in is a REORDER and deliberately does not restamp the stage timer.
+
+A card carries TWO people and they are not interchangeable. The OWNER (assignee) is whoever carries the card end to end — the engineer who builds it, and the person a QA bounce sends it back to. The HANDLER is whoever took the pass the card is on right now, which at a QA gate is the tester and nowhere else is usually the owner. claim:true always takes the pass; it takes ownership ONLY of a card nobody owns. So a QA pick-up on an engineer's card leaves the engineer owning it, which is what makes the two-gate flow work at all.
+
+This is both halves of the developer loop. Claiming is a parameter and not a second tool on purpose: picking a card up is one act, and a separate "assign" call is the one that gets skipped — leaving a card in an active column with no owner, which is the exact finding the board's unassigned glyph exists to shout about.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id to move.'),
+      toColumnId: z
+        .string()
+        .describe('Target column id. Must be a column on the SAME board — get it from get_work_board.'),
+      position: z
+        .number()
+        .optional()
+        .describe('Sort position within the target column. Omit to append to the end.'),
+      claim: z
+        .boolean()
+        .optional()
+        .describe(
+          'Pick this card up as part of this move: it records YOU as the handler of the pass the card lands on, and makes you the owner only if the card has no owner. "You" is resolved from the authenticated token — there is no way to claim on somebody else\'s behalf. Use it whenever you are picking work up. Taking a pass on a card SOMEBODY ELSE OWNS is allowed and normal (that is a QA pick-up) and leaves their ownership alone; taking a pass somebody else is already HOLDING is refused (see force). Re-claiming a pass you already hold is a no-op, not an error. The handler is written to the card\'s open dwell, so a same-column claim works too — that is how you take a pass on a card already sitting in your stage.'
+        ),
+      force: z
+        .boolean()
+        .optional()
+        .describe(
+          'Take over a pass SOMEBODY ELSE IS HOLDING. Requires claim:true and a reason saying why — the reason is the only record that person will have of losing the pass mid-stage. It does NOT take the card off its owner: reassigning a card is the assignee field on update_work_item, a deliberate act, never a side effect of a move. Do not reach for this to work around a refusal; a pass somebody is running is theirs.'
+        ),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false for a live move.'),
+      approved: z.boolean().optional().describe('Required true for a live move.'),
+      reason: z
+        .string()
+        .optional()
+        .describe(
+          'Required for a live move, and it must be worth reading: a branch name, a PR link, or one line saying what changed and how it was verified. Stored on the transition row and rendered in the card\'s history, so it is what a human reads in three weeks asking why this took a week. Placeholder reasons ("moved", "update") are refused.'
+        ),
+      idempotencyKey: z
+        .string()
+        .optional()
+        .describe('Required for a live move. Reuse the SAME key on retry; the server replays.'),
+    },
+    async (args) => {
+      if (args.force === true && args.claim !== true) {
+        return ok({
+          error: true,
+          message:
+            'force only means anything alongside claim:true — it is the override for taking a card over from another person, not a general "ignore checks" flag. Drop it, or set claim:true if you really are picking this card up.',
+        });
+      }
+      const unauditable = args.dryRun === false ? describeUnauditableReason(args.reason) : null;
+      if (unauditable) return ok({ error: true, message: unauditable });
+
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/move`;
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+      });
+      if (preview?.dryRun) {
+        return ok({
+          ...preview,
+          wouldMove: {
+            itemId: args.itemId,
+            toColumnId: args.toColumnId,
+            position: args.position,
+            claim: args.claim === true,
+            force: args.force === true,
+          },
+        });
+      }
+
+      const data = await api('POST', path, {
+        body: {
+          toColumnId: args.toColumnId,
+          position: args.position,
+          reason: args.reason,
+          idempotencyKey: args.idempotencyKey,
+          // Sent only when asked for, so an ordinary move carries no opinion
+          // about the assignee at all.
+          claim: args.claim === true ? true : undefined,
+          force: args.force === true ? true : undefined,
+        },
+        headers: buildMutationHeaders(args),
+      });
+      const item = data?.data;
+      return ok({
+        moved: true,
+        claimed: args.claim === true,
+        // Read back from the server rather than echoed from the request, because
+        // the two halves of a claim are decided server-side and an agent that
+        // assumed "claimed" meant "mine now" would report a QA pick-up as having
+        // taken the card off the engineer.
+        owner: item?.assignee ?? null,
+        handler: item?.handler ?? null,
+        item,
+      });
+    }
+  );
+
+  server.tool(
+    'set_work_item_tag',
+    `Set a card's URGENCY tag. The scheme must be one the board reads (severity | priority | impact) and the source must be human, model, or rules. A "model" tag REQUIRES a confidence: the board drops a low-confidence model tag, and a model tag with no confidence cannot be held to that floor, so it would be trusted by default — backwards. This does NOT say what kind of work the card is — that is a separate field; use set_work_item_kind, and note that setting one never disturbs the other.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id.'),
+      schemeId: z
+        .enum(['severity', 'priority', 'impact'])
+        .describe(
+          'Urgency vocabulary. Use the board\'s own tagScheme unless deliberately changing it. "kind" is no longer a scheme — it is a field, set with set_work_item_kind.'
+        ),
+      optionId: z
+        .string()
+        .describe(
+          'Option within the scheme — e.g. critical | non-critical, p0..p3, all-customers | some-customers | internal-only.'
+        ),
+      source: z
+        .enum(['human', 'model', 'rules'])
+        .describe(
+          'Who decided. An agent classifying a card is "model" — claiming "human" would launder a guess as a person\'s judgement.'
+        ),
+      confidence: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe('0-1. REQUIRED when source is "model".'),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false for a live change.'),
+      approved: z.boolean().optional().describe('Required true for a live change.'),
+      reason: z.string().optional().describe('Required for a live change: why this tag.'),
+      idempotencyKey: z.string().optional().describe('Required for a live change.'),
+    },
+    async (args) => {
+      if (args.source === 'model' && args.confidence === undefined) {
+        return ok({
+          error: true,
+          message:
+            'confidence is required when source is "model". Without it the tag cannot be held to the board\'s confidence floor, so it would be trusted by default.',
+        });
+      }
+
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}`;
+      const preview = validateApiBridgeRequest({
+        method: 'PATCH',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+      });
+      if (preview?.dryRun) {
+        return ok({
+          ...preview,
+          wouldTag: {
+            itemId: args.itemId,
+            schemeId: args.schemeId,
+            optionId: args.optionId,
+            source: args.source,
+            confidence: args.confidence,
+          },
+        });
+      }
+
+      const data = await api('PATCH', path, {
+        body: {
+          tag: {
+            schemeId: args.schemeId,
+            optionId: args.optionId,
+            source: args.source,
+            confidence: args.confidence,
+          },
+        },
+        headers: buildMutationHeaders(args),
+      });
+      return ok({ tagged: true, item: data?.data });
+    }
+  );
+
+  server.tool(
+    'set_work_item_kind',
+    `Set what KIND of work a card is: bug, story, or chore. This is a FIELD on the card, not a tag — it is orthogonal to urgency, so a card can be a bug AND Critical, and setting the kind never touches the tag (or the assignee, product, or body).
+
+Pass kind:null to clear it back to UNTYPED. Untyped is a real state and is NOT the same as "chore": a card nobody has categorised has no category, and recording chore would put a decision on the record that nobody made. If you do not know what a card is, leave it alone or clear it — do not guess.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id.'),
+      kind: z
+        .enum(['bug', 'story', 'chore'])
+        .nullable()
+        .describe(
+          'bug | story | chore, or null to clear it back to untyped. "story", not "feature" — that was the old tag-scheme spelling and the API rejects it.'
+        ),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false for a live change.'),
+      approved: z.boolean().optional().describe('Required true for a live change.'),
+      reason: z.string().optional().describe('Required for a live change: why this kind.'),
+      idempotencyKey: z.string().optional().describe('Required for a live change.'),
+    },
+    async (args) => {
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}`;
+      const preview = validateApiBridgeRequest({
+        method: 'PATCH',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+      });
+      if (preview?.dryRun) {
+        return ok({
+          ...preview,
+          wouldSetKind: { itemId: args.itemId, kind: args.kind ?? null },
+        });
+      }
+
+      const data = await api('PATCH', path, {
+        // `kind` is always present in this body and is either a value or an
+        // explicit null. That is deliberate: the server reads three states, and
+        // omitting the key would mean "leave it alone" — which is the one thing
+        // a tool whose entire job is setting the kind must never send.
+        body: { kind: args.kind ?? null },
+        headers: buildMutationHeaders(args),
+      });
+      return ok({ kindSet: true, item: data?.data });
+    }
+  );
+
+  server.tool(
+    'create_work_item',
+    `Create a card on a board. Lands in the named column, or the board's first column when none is given.
+
+WRITE THE ACCEPTANCE CRITERIA IN \`body\`. A card is the unit of QA sign-off, so a card that does not say what "done" means cannot be validated by QA and cannot be built from by the next agent — those are the two readers of the same list. There is no separate criteria field yet: the criteria live in \`body\`, under a short "Acceptance criteria" heading, one checkable outcome per line. If you cannot write them, you do not yet understand the card well enough to file it as workable — file it with what you DO know and say in the body that the criteria are missing, rather than inventing outcomes nobody agreed to.
+
+ONE CARD IS ONE QA JUDGEMENT. If your criteria list needs QA to make more than one call ("follows the OS theme" AND "the toggle persists" AND "every surface is restyled"), that is several cards, not one — a bounce from a multi-outcome card names nothing actionable. Implementation steps ("create a React hook", "rename the CSS variables") are never cards; they are lines inside one.
+
+YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from your authenticated token — there is no parameter for it, and a body naming one is REFUSED rather than ignored, on the same rule as list_my_work_items. Creating is also not claiming: a new card arrives unassigned unless you name an owner, and you pick work up by moving it into an active column with move_work_item(claim:true), which is the act that also starts the stage timer honestly.${GOVERNED_NOTE}`,
+    {
+      boardId: z.string().describe('Board id from list_work_boards.'),
+      title: z.string().describe('What the card is. Keep it a statement of the work, not a label.'),
+      body: z
+        .string()
+        .optional()
+        .describe(
+          'The request in full AND its acceptance criteria — what QA will validate this against, one checkable outcome per line under an "Acceptance criteria" heading. Repro steps for a bug go here too. Markdown; an implementation checklist belongs here rather than in sub-cards, because there are none by design.'
+        ),
+      product: z.string().optional().describe('Product tag — orthogonal to the board.'),
+      kind: z
+        .enum(['bug', 'story', 'chore'])
+        .optional()
+        .describe(
+          'What kind of work this is. OMIT IT unless the card plainly says: an absent kind means untyped, which is honest, where a guess is indistinguishable from a person\'s judgement once it is on the record. Change it later with set_work_item_kind.'
+        ),
+      columnId: z.string().optional().describe('Target column. Defaults to the board\'s first.'),
+      assigneeUserId: z
+        .string()
+        .optional()
+        .describe(
+          'Workspace user who will do the work. OMIT IT unless somebody has actually agreed to own this — creating a card is not claiming it, and an unowned card in the backlog is the normal state of a backlog. Do not put yourself here to mark "I filed this": the card already records its creator.'
+        ),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to create it.'),
+      approved: z.boolean().optional().describe('Required true for a live create.'),
+      reason: z.string().optional().describe('Required for a live create.'),
+      idempotencyKey: z.string().optional().describe('Required for a live create.'),
+    },
+    async (args) => {
+      const path = `/api/v1/work-boards/${encodeURIComponent(args.boardId)}/items`;
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+      });
+      if (preview?.dryRun) {
+        return ok({
+          ...preview,
+          wouldCreate: { boardId: args.boardId, title: args.title, kind: args.kind },
+          // A statement of FACT about the body, not a guess about its contents.
+          // "Does this text contain acceptance criteria" is not something a
+          // regex can answer honestly, and a heuristic that half-answered it
+          // would either block a legitimate one-line capture or bless a body
+          // with a heading and nothing under it. What IS checkable is that
+          // there is no body at all — a title-only card, which cannot be QA'd
+          // and cannot be built from. Said in the preview, where a human is
+          // already deciding whether to approve, and never blocking: a refused
+          // capture is how work stops reaching the board at all.
+          note: describeMissingBody(args.body),
+        });
+      }
+
+      const data = await api('POST', path, {
+        body: {
+          title: args.title,
+          body: args.body,
+          product: args.product,
+          // Undefined when the caller named no kind, so the key is dropped from
+          // the JSON and the card is stored untyped rather than defaulted.
+          kind: args.kind,
+          columnId: args.columnId,
+          assigneeUserId: args.assigneeUserId,
+        },
+        headers: buildMutationHeaders(args),
+      });
+      return ok({ created: true, item: data?.data });
+    }
+  );
+  server.tool(
+    'comment_on_work_item',
+    `Say something on a card: a question, a finding, or the reason a QA pass sent it back. This is the ONLY place to put a fact that contradicts the card — the ship-the-card skill tells you to say so on the card rather than silently fixing something else, and this is where that goes. Do NOT overwrite the card's body to make the point: the body is the original request, and rewriting it destroys the evidence of what was actually asked for.
+
+A comment is deliberately small: no threading, no reactions, no formatting. One author, one paragraph, in order.
+
+TO @-MENTION SOMEBODY, write the token \`<@userId>\` in the body — the id comes from the card's assignee, its history, or list_my_work_items. Anything else you type is literal text: writing "@noah" mentions nobody, which is deliberate. A mention means "see this" and NOTHING more — it does not assign the card, add a watcher, or raise a flag. Only workspace members resolve; a token naming anyone else stays as text and notifies no one.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id.'),
+      body: z
+        .string()
+        .describe(
+          'What you want to say. Plain text; newlines are kept. Capped at 2000 characters — longer than that belongs in the card description or a linked document. Use `<@userId>` to @-mention a workspace member; bare "@name" is literal text and mentions nobody.'
+        ),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to post it.'),
+      approved: z.boolean().optional().describe('Required true for a live post.'),
+      reason: z
+        .string()
+        .optional()
+        .describe('Required for a live post: why you are commenting. This is the audit reason, NOT the comment — the comment is `body`.'),
+      idempotencyKey: z
+        .string()
+        .optional()
+        .describe(
+          'Required for a live post. Reuse the SAME key on retry: a replayed comment is just the same paragraph twice, which reads as you being emphatic rather than as a retry.'
+        ),
+    },
+    async (args) => {
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/comments`;
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+      });
+      if (preview?.dryRun) {
+        return ok({ ...preview, wouldComment: { itemId: args.itemId, body: args.body } });
+      }
+
+      const data = await api('POST', path, {
+        body: { body: args.body, idempotencyKey: args.idempotencyKey },
+        headers: buildMutationHeaders(args),
+      });
+      return ok({ commented: true, comment: data?.data });
+    }
+  );
+
+  server.tool(
+    'flag_work_item',
+    `Flag a card as having a problem WITH THE CARD — unclear scope, no repro, a blocked dependency, a question waiting on an answer — or clear a flag once it is resolved. A flagged card is drawn differently on the board so nobody picks it up by mistake.
+
+A FLAG IS NOT A TAG. The tag says how urgent the WORK is; a flag says the CARD is not fit to be worked. If a card is merely important, use set_work_item_tag. If you cannot start because something is missing, flag it.
+
+THE REASON IS REQUIRED IN BOTH DIRECTIONS, and it is not the audit reason — it is the text a human reads on the card. Raising says what is wrong; clearing says what resolved it. Anyone may clear a flag, which only works because both directions are recorded as a comment on the card.
+
+This is what the ship-the-card skill means by "an unworkable card is a triage problem, not a coding problem": flag it, say the one question that would unblock it, and stop.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id.'),
+      flagged: z
+        .boolean()
+        .describe('true raises the flag; false clears it. Raising an already-flagged card replaces the reason.'),
+      reason: z
+        .string()
+        .describe(
+          'REQUIRED. Raising: what is wrong with the card. Clearing: what resolved it. Shown on the card and appended to its comment thread — write it for the person who will read it, not for a log.'
+        ),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to change the flag.'),
+      approved: z.boolean().optional().describe('Required true for a live change.'),
+      idempotencyKey: z
+        .string()
+        .optional()
+        .describe('Required for a live change. Reuse the SAME key on retry — the flag also appends a comment.'),
+    },
+    async (args) => {
+      if (!args.reason || !args.reason.trim()) {
+        return ok({
+          error: true,
+          message:
+            'reason is required to flag or to clear. A flag with nothing written on it stops work without saying how to restart it, and a flag anyone can silently clear is a flag nobody trusts.',
+        });
+      }
+
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/flag`;
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        // The flag's own reason doubles as the governed audit reason. They are
+        // genuinely the same fact here — unlike a comment, where the audit
+        // reason explains the write and `body` is the content.
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+      });
+      if (preview?.dryRun) {
+        return ok({
+          ...preview,
+          wouldFlag: { itemId: args.itemId, flagged: args.flagged, reason: args.reason },
+        });
+      }
+
+      const data = await api('POST', path, {
+        body: {
+          flagged: args.flagged,
+          reason: args.reason,
+          idempotencyKey: args.idempotencyKey,
+        },
+        headers: buildMutationHeaders({ ...args, reason: args.reason }),
+      });
+      return ok({ flagged: args.flagged, item: data?.data });
+    }
+  );
+}
+
+/** Tool names registered here, for the tier map and the toolset manifest. */
+export const WORK_BOARD_TOOL_NAMES = [
+  'list_my_work_items',
+  'list_work_boards',
+  'get_work_board',
+  'get_work_item',
+  'get_work_item_history',
+  'get_work_board_rollup',
+  'list_work_board_rollups',
+  'move_work_item',
+  'set_work_item_tag',
+  'set_work_item_kind',
+  'create_work_item',
+  'get_work_item_comments',
+  'comment_on_work_item',
+  'flag_work_item',
+];