@adrata/adrata-mcp 1.0.1 → 1.0.3

package/tools/work-board-tools.js

@@ -1,3 +1,5 @@
+import { auditWorkHubBoards, deliveryContradictions } from './work-hub/audit.js';
+
 /**
  * Work-board tools for the Adrata MCP Server.
  *
@@ -110,14 +112,9 @@ export function describeUnauditableReason(reason) {
 /**
  * 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.
+ * The body is working context: request, evidence, repro, constraints. The
+ * executable definition of done lives in first-class acceptance-criteria rows
+ * and has its own check below, so prose is never regex-classified as criteria.
  *
  * 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.
@@ -126,18 +123,48 @@ export function describeUnauditableReason(reason) {
  */
 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.';
+  return 'This card would arrive with a title and no working context. Add the request, evidence, or repro to `body`, or say what is still unknown. Acceptance criteria are separate first-class records in `acceptanceCriteria`.';
+}
+
+export function describeMissingAcceptanceCriteria(criteria) {
+  if (Array.isArray(criteria) && criteria.length > 0) return undefined;
+  return 'This card would have no executable acceptance criteria. It can be captured, but it is not ready for build or QA until at least one where/when/then criterion is added.';
+}
+
+/**
+ * The satisfaction sub-resource of one criterion, POSTed to tick and DELETEd to
+ * un-tick.
+ *
+ * One function for both verbs because they address the SAME resource: a tick
+ * and its removal that disagreed about the path would fail asymmetrically —
+ * ticks landing and un-ticks 404ing — which is the failure that leaves a board
+ * with checkboxes nobody can clear.
+ */
+export function criterionSatisfactionPath(itemId, criterionId) {
+  return `/api/v1/work-items/${encodeURIComponent(itemId)}/acceptance-criteria/${encodeURIComponent(criterionId)}/satisfaction`;
+}
+
+/** One target stage's WIP state before and after a proposed move. */
+export function projectColumnWip({ limit, count, cardAlreadyThere, truncated = false }) {
+  const projected = count + (cardAlreadyThere ? 0 : 1);
+  return {
+    limit: limit ?? null,
+    current: count,
+    projected,
+    overLimit: limit == null ? false : projected > limit,
+    completeCount: !truncated,
+  };
 }
 
 /**
  * Register the work-board tools.
  *
  * @param {McpServer} server - the MCP server instance (already tier-gated)
- * @param {object} deps - { z, api, ok, validateApiBridgeRequest, buildMutationHeaders }
+ * @param {object} deps - { z, api, ok, validateApiBridgeRequest, buildMutationHeaders, getGrantedScope }
  */
 export function registerWorkBoardTools(
   server,
-  { z, api, ok, validateApiBridgeRequest, buildMutationHeaders }
+  { z, api, ok, validateApiBridgeRequest, buildMutationHeaders, getGrantedScope = () => undefined }
 ) {
   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).';
@@ -262,6 +289,54 @@ Start here for "what should I work on". With includeUnassigned it also returns t
     }
   );
 
+  server.tool(
+    'get_work_item_delivery_evidence',
+    `Read the four facts that must never be collapsed into one status: the card's workflow column, linked pull-request state, exact-SHA staging presence, and exact-SHA production presence. Use this before calling a card shipped or treating the Production column as proof. Unknown means Adrata has no trustworthy evidence; it never means the work is absent. This tool is read-only and does not move the card.`,
+    {
+      itemId: z.string().describe('Card id.'),
+    },
+    async (args) => {
+      const data = await api(
+        'GET',
+        `/api/v1/work-items/${encodeURIComponent(args.itemId)}/delivery-evidence`
+      );
+      const evidence = data?.data;
+      const contradictions = deliveryContradictions(evidence);
+      return ok({ evidence, contradictions });
+    }
+  );
+
+  server.tool(
+    'list_work_item_acceptance_criteria',
+    'Read the ordered, executable definition of done for one card. Each criterion says where to check, any starting state, what action to perform, and the observable result. A zero-length list is a finding: nobody has stated how QA can decide the card is done.',
+    { itemId: z.string().describe('Card id.') },
+    async (args) => {
+      const data = await api(
+        'GET',
+        `/api/v1/work-items/${encodeURIComponent(args.itemId)}/acceptance-criteria`
+      );
+      const criteria = data?.data ?? [];
+      return ok({ count: criteria.length, criteria });
+    }
+  );
+
+  server.tool(
+    'audit_work_hub',
+    `Audit every visible Starfield board as an operating ledger. Returns named findings for active cards without owners, active passes without handlers, missing definitions of done, missing work types or context, stale stages, and truncated reads. It does not award a vanity score and it does not mutate anything. A clean result means the board has the minimum workflow facts required to operate from it; deployment truth remains a separate exact-SHA fact available through get_work_item_delivery_evidence.`,
+    {},
+    async () => {
+      const listed = await api('GET', '/api/v1/work-boards');
+      const refs = listed?.data ?? [];
+      const boards = await Promise.all(
+        refs.map(async (board) => {
+          const detail = await api('GET', `/api/v1/work-boards/${encodeURIComponent(board.id)}`);
+          return detail?.data;
+        })
+      );
+      return ok(auditWorkHubBoards(boards.filter(Boolean)));
+    }
+  );
+
   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.',
@@ -317,6 +392,103 @@ Start here for "what should I work on". With includeUnassigned it also returns t
   // WRITES
   // =========================================================================
 
+  server.tool(
+    'set_work_board_archived',
+    `Hide or restore a board in the workspace catalogue without deleting anything. Archived boards disappear from normal board lists and roll-ups, but their cards, history, releases, QA flows, memberships, and evidence remain intact. Use this for obsolete, duplicate, or no-longer-operated boards; never manufacture a release or delete cards merely to clean up the board chooser.${GOVERNED_NOTE}`,
+    {
+      boardId: z.string().describe('Board id from list_work_boards.'),
+      archived: z.boolean().describe('true hides the board; false restores 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 board is being hidden or restored.'),
+      idempotencyKey: z.string().optional().describe('Required for a live change.'),
+    },
+    async (args) => {
+      const path = `/api/v1/work-boards/${encodeURIComponent(args.boardId)}/archived`;
+      const preview = validateApiBridgeRequest({
+        method: 'PATCH',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) {
+        const data = await api('GET', `/api/v1/work-boards/${encodeURIComponent(args.boardId)}`);
+        const board = data?.data;
+        const terminalNames = new Set(['production', 'deep backlog']);
+        const activeCount = (board?.items ?? []).filter((item) => {
+          const column = board?.columns?.find((candidate) => candidate.id === item.columnId);
+          return column && !terminalNames.has(String(column.name).trim().toLowerCase());
+        }).length;
+        return ok({
+          ...preview,
+          wouldSetBoardArchived: {
+            boardId: args.boardId,
+            boardName: board?.name,
+            archived: args.archived,
+            visibleItemCount: board?.itemCount ?? (board?.items ?? []).length,
+            activeItemCount: activeCount,
+            completeCount: board?.truncated !== true,
+          },
+        });
+      }
+
+      const data = await api('PATCH', path, {
+        body: { archived: args.archived },
+        headers: buildMutationHeaders(args),
+      });
+      return ok({ boardArchiveStateSet: true, ...data?.data });
+    }
+  );
+
+  server.tool(
+    'set_work_board_column_wip_limit',
+    `Set or clear one board column's visible WIP ceiling. Exceeding the ceiling never blocks a move: the board renders the measured count and limit in red so daily Aligning can answer for it. Only a workspace admin may change this operating policy. Production and Deep backlog cannot have limits because they are output and parking columns, not work centres.${GOVERNED_NOTE}`,
+    {
+      boardId: z.string().describe('Board id from list_work_boards.'),
+      columnId: z.string().describe('Column id from get_work_board.'),
+      wipLimit: z
+        .number()
+        .int()
+        .positive()
+        .nullable()
+        .describe('Positive ceiling, or null to clear it (unlimited).'),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to change it.'),
+      approved: z.boolean().optional().describe('Required true for a live change.'),
+      reason: z.string().optional().describe('Required for a live change: why this capacity is right.'),
+      idempotencyKey: z.string().optional().describe('Required for a live change. Reuse on retry.'),
+    },
+    async (args) => {
+      const unauditable = args.dryRun === false ? describeUnauditableReason(args.reason) : null;
+      if (unauditable) return ok({ error: true, message: unauditable });
+
+      const path = `/api/v1/work-boards/${encodeURIComponent(args.boardId)}/columns/${encodeURIComponent(args.columnId)}/wip-limit`;
+      const preview = validateApiBridgeRequest({
+        method: 'PATCH',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) {
+        return ok({
+          ...preview,
+          wouldSet: { boardId: args.boardId, columnId: args.columnId, wipLimit: args.wipLimit },
+        });
+      }
+
+      const data = await api('PATCH', path, {
+        body: { wipLimit: args.wipLimit },
+        headers: buildMutationHeaders(args),
+      });
+      return ok({ updated: true, column: data?.data });
+    }
+  );
+
   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.
@@ -343,7 +515,7 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
         .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.'
+          '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 a deliberate edit to its assignee, never a side effect of a move — and there is no board tool here that does it, so reassignment is a human act on the board (or an explicit PATCH via adrata_api_request). 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.'),
@@ -377,8 +549,29 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
         approved: args.approved,
         reason: args.reason,
         idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
       });
       if (preview?.dryRun) {
+        const itemData = await api(
+          'GET',
+          `/api/v1/work-items/${encodeURIComponent(args.itemId)}`
+        );
+        const item = itemData?.data;
+        const boardData = await api(
+          'GET',
+          `/api/v1/work-boards/${encodeURIComponent(item.boardId)}`
+        );
+        const board = boardData?.data;
+        const target = board?.columns?.find((column) => column.id === args.toColumnId);
+        if (!target) {
+          return ok({
+            error: true,
+            message: 'toColumnId is not a column on this card\'s board.',
+          });
+        }
+        const count = (board.items ?? []).filter(
+          (candidate) => candidate.columnId === args.toColumnId
+        ).length;
         return ok({
           ...preview,
           wouldMove: {
@@ -388,6 +581,12 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
             claim: args.claim === true,
             force: args.force === true,
           },
+          wip: projectColumnWip({
+            limit: target.wipLimit,
+            count,
+            cardAlreadyThere: item.columnId === args.toColumnId,
+            truncated: board.truncated === true,
+          }),
         });
       }
 
@@ -467,6 +666,7 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
         approved: args.approved,
         reason: args.reason,
         idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
       });
       if (preview?.dryRun) {
         return ok({
@@ -523,6 +723,7 @@ Pass kind:null to clear it back to UNTYPED. Untyped is a real state and is NOT t
         approved: args.approved,
         reason: args.reason,
         idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
       });
       if (preview?.dryRun) {
         return ok({
@@ -547,7 +748,7 @@ Pass kind:null to clear it back to UNTYPED. Untyped is a real state and is NOT t
     '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.
+ACCEPTANCE CRITERIA ARE FIRST-CLASS RECORDS, not prose buried in \`body\`. Use \`acceptanceCriteria\` for the executable definition of done: where to check, any starting state, what action to perform, and the observable result. The card and every criterion are replay-safe under one idempotency-key family, so a retry after a partial failure cannot duplicate either. If you cannot write criteria, capture what you know in \`body\`; the preview will mark the card as not ready 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.
 
@@ -559,7 +760,20 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
         .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.'
+          'The request, evidence, and repro/context. Markdown. The executable definition of done belongs in acceptanceCriteria, not in this prose.'
+        ),
+      acceptanceCriteria: z
+        .array(
+          z.object({
+            whereText: z.string().describe('Surface, environment, account, or role to check.'),
+            givenText: z.string().optional().describe('Starting state, when one is required.'),
+            whenText: z.string().describe('Action the verifier performs.'),
+            thenText: z.string().describe('Observable result that must follow.'),
+          })
+        )
+        .optional()
+        .describe(
+          'Executable definition of done. One independently checkable outcome per entry. Omit only for a thin capture that is not ready to build.'
         ),
       product: z.string().optional().describe('Product tag — orthogonal to the board.'),
       kind: z
@@ -589,11 +803,17 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
         approved: args.approved,
         reason: args.reason,
         idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
       });
       if (preview?.dryRun) {
         return ok({
           ...preview,
-          wouldCreate: { boardId: args.boardId, title: args.title, kind: args.kind },
+          wouldCreate: {
+            boardId: args.boardId,
+            title: args.title,
+            kind: args.kind,
+            acceptanceCriteria: args.acceptanceCriteria ?? [],
+          },
           // 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
@@ -604,6 +824,7 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
           // already deciding whether to approve, and never blocking: a refused
           // capture is how work stops reaching the board at all.
           note: describeMissingBody(args.body),
+          readinessNote: describeMissingAcceptanceCriteria(args.acceptanceCriteria),
         });
       }
 
@@ -620,9 +841,217 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
         },
         headers: buildMutationHeaders(args),
       });
-      return ok({ created: true, item: data?.data });
+      const item = data?.data;
+      const criteria = [];
+      for (const [index, criterion] of (args.acceptanceCriteria ?? []).entries()) {
+        const criterionKey = `${args.idempotencyKey}:criterion:${index + 1}`;
+        const result = await api(
+          'POST',
+          `/api/v1/work-items/${encodeURIComponent(item.id)}/acceptance-criteria`,
+          {
+            body: criterion,
+            headers: buildMutationHeaders({
+              ...args,
+              idempotencyKey: criterionKey,
+            }),
+          }
+        );
+        criteria.push(result?.data);
+      }
+      return ok({ created: true, item, criteria });
     }
   );
+
+  server.tool(
+    'add_work_item_acceptance_criterion',
+    `Add one executable acceptance criterion to a card. This is grooming, not a comment: write where the check runs, the action, and the observable result. The server keeps criteria ordered and auditable.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id.'),
+      whereText: z.string().describe('Surface, environment, account, or role to check.'),
+      givenText: z.string().optional().describe('Starting state, when one is required.'),
+      whenText: z.string().describe('Action the verifier performs.'),
+      thenText: z.string().describe('Observable result that must follow.'),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to add it.'),
+      approved: z.boolean().optional().describe('Required true for a live write.'),
+      reason: z.string().optional().describe('Required for a live write: why this criterion is being added.'),
+      idempotencyKey: z.string().optional().describe('Required for a live write. Reuse on retry.'),
+    },
+    async (args) => {
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/acceptance-criteria`;
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        ...args,
+        grantedScope: getGrantedScope(),
+      });
+      const criterion = {
+        whereText: args.whereText,
+        givenText: args.givenText,
+        whenText: args.whenText,
+        thenText: args.thenText,
+      };
+      if (preview?.dryRun) return ok({ ...preview, wouldAdd: { itemId: args.itemId, criterion } });
+      const data = await api('POST', path, {
+        body: criterion,
+        headers: buildMutationHeaders(args),
+      });
+      return ok({ added: true, criterion: data?.data });
+    }
+  );
+
+  server.tool(
+    'satisfy_work_item_acceptance_criterion',
+    `Tick one acceptance criterion, with the evidence that made you believe it. This is the act that turns a checklist into proof: a criterion nobody ticks is indistinguishable from one nobody ran, and a board full of untouched checkboxes reports the same thing whether the work was verified or abandoned.
+
+WHERE YOU TICK FROM DECIDES WHAT THE TICK IS WORTH, and it is not a permission you can ask for. The grade is derived on every read from the card's CURRENT column and from who you are:
+
+  • \`verified\` — ticked while the card stands in a QA stage ("Staging QA1" or "Staging QA2"), by somebody who neither wrote the criterion nor owns the card.
+  • \`claimed\` — everything else. Ticked in a build column, or ticked at a QA gate by the card's owner or by the person who authored the check. A real and useful state: it says the work is believed done. It is self-assessment, and the board never counts it as verification.
+
+So the engineer who built the card CANNOT verify their own work, and neither can whoever wrote the criterion — not because the tick is refused, but because it grades as \`claimed\` however it is worded. Nothing here fails on that account; you get the criterion back carrying a grade, and the grade may not be the one you expected. If you want \`verified\`, the card has to be standing at a QA gate and somebody else has to be doing the ticking.
+
+TICK WHAT YOU RAN, not what you believe. The card face prints met over total; the QA exit gate reads the VERIFIED count. So a card whose boxes were all ticked by its own author reads 5/5 on the face and still stops the gate — which is the design working. Ticking without running the check converts an honest "we shipped with two open" into a false "all met", and the false version is the one that gets believed later.
+
+FIRST TICK WINS. The server records the ticker, the column and the note only where they were empty, so a second person ticking an already-ticked box cannot overwrite the first person's evidence, and re-ticking is a no-op rather than an upgrade. To re-tick under different circumstances, un-tick it first with unsatisfy_work_item_acceptance_criterion — that clears the ticker, the column and the note together, so the next tick cannot inherit somebody else's evidence.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id.'),
+      criterionId: z
+        .string()
+        .describe('Criterion id from list_work_item_acceptance_criteria — the `id`, not the `ordinal`.'),
+      note: z
+        .string()
+        .optional()
+        .describe(
+          'OPTIONAL, and the most useful field here: the evidence. A build number, a PR or run link, or the caveat that makes the tick honest ("only checked on Safari"). Stored on the criterion and shown beside it, so it is what a release review reads instead of taking the tick on trust. Omit it when there is genuinely nothing to add — an invented note is worse than none.'
+        ),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to record the tick.'),
+      approved: z.boolean().optional().describe('Required true for a live tick.'),
+      reason: z
+        .string()
+        .optional()
+        .describe(
+          'Required for a live tick: the audit reason — how you checked this, not what the criterion already says. The evidence a human reads on the card is `note`.'
+        ),
+      idempotencyKey: z
+        .string()
+        .optional()
+        .describe('Required for a live tick. Reuse the SAME key on retry.'),
+    },
+    async (args) => {
+      const unauditable = args.dryRun === false ? describeUnauditableReason(args.reason) : null;
+      if (unauditable) return ok({ error: true, message: unauditable });
+
+      const path = criterionSatisfactionPath(args.itemId, args.criterionId);
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) {
+        return ok({
+          ...preview,
+          wouldSatisfy: {
+            itemId: args.itemId,
+            criterionId: args.criterionId,
+            note: args.note ?? null,
+          },
+          // Said in the preview because the preview is where a caller decides
+          // whether to go live, and the one thing it CANNOT tell them is the
+          // answer they want. Predicting the grade here would need the card's
+          // current column and the criterion's author, and a prediction made
+          // from a stale read is worse than an honest refusal to predict.
+          gradeIsDerived:
+            'The grade is computed at read time from the column this card is standing in and from who you are, so this preview cannot tell you which you will get. Ticking from a QA stage, as somebody who is neither the criterion\'s author nor the card\'s owner, grades `verified`; anything else grades `claimed`.',
+        });
+      }
+
+      const data = await api('POST', path, {
+        // The note is the only field this endpoint takes, and it is optional:
+        // `SatisfyCriterionRequest` defaults it, so an omitted note is a valid
+        // body rather than a missing one. Sending `{}` is deliberate — a tick
+        // with nothing to add must stay recordable, because the alternative is
+        // an agent inventing evidence to satisfy a required field.
+        body: args.note === undefined ? {} : { note: args.note },
+        headers: buildMutationHeaders(args),
+      });
+      const criterion = data?.data;
+      return ok({
+        satisfied: true,
+        criterion,
+        // The grade is the answer, and it is the server's to give. Echoing an
+        // optimistic "verified" from the request would be this tool asserting
+        // the exact fact the grading rule exists to withhold.
+        grade: criterion?.grade,
+        ...(criterion?.grade === 'claimed'
+          ? {
+              gradeNote:
+                'Recorded as `claimed`, not `verified`: either the card was not standing in a QA stage, or you wrote this criterion or own the card. That is the rule working rather than a failure — the tick stands and the card face counts it. Verification needs a QA stage and a different pair of hands.',
+            }
+          : {}),
+      });
+    }
+  );
+
+  server.tool(
+    'unsatisfy_work_item_acceptance_criterion',
+    `Un-tick one acceptance criterion, back to \`unmet\`. Use it when the check turns out not to hold, when it was ticked against the wrong build, or when it was ticked from a build column and has to be re-run at the gate to count as verified.
+
+This exists so that ticking is safe to do. A box nobody can clear is a box people hesitate to tick, and that hesitation is exactly how a board ends up with a full checklist that nobody has ever touched — so shipping the tick without its counterpart would have left the same problem in a new shape.
+
+It clears the WHOLE circumstance together — the ticker, the column, the note and the timestamp — never just the timestamp. Otherwise the next tick would inherit somebody else's evidence: a criterion re-ticked in Aligning would keep reading as verified in QA1, attributed to a person who was not there. So the cost is real, and it is the note: the first ticker's evidence is gone. If it is worth keeping, put it on the card with comment_on_work_item BEFORE you clear it.
+
+Anyone who can see the card may un-tick, including somebody undoing another person's tick. The audit reason is the only record of why, so write it for them.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id.'),
+      criterionId: z
+        .string()
+        .describe('Criterion id from list_work_item_acceptance_criteria — the `id`, not the `ordinal`.'),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to clear the tick.'),
+      approved: z.boolean().optional().describe('Required true for a live change.'),
+      reason: z
+        .string()
+        .optional()
+        .describe(
+          'Required for a live change: why this tick is coming off — the check failed on a later build, it was run against the wrong environment, it needs re-running at the gate. This is the only record the original ticker will have of losing their evidence.'
+        ),
+      idempotencyKey: z
+        .string()
+        .optional()
+        .describe('Required for a live change. Reuse the SAME key on retry.'),
+    },
+    async (args) => {
+      const unauditable = args.dryRun === false ? describeUnauditableReason(args.reason) : null;
+      if (unauditable) return ok({ error: true, message: unauditable });
+
+      const path = criterionSatisfactionPath(args.itemId, args.criterionId);
+      const preview = validateApiBridgeRequest({
+        method: 'DELETE',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) {
+        return ok({
+          ...preview,
+          wouldUnsatisfy: { itemId: args.itemId, criterionId: args.criterionId },
+          clears:
+            'The ticker, the column the tick happened in, the evidence note, and the timestamp — all four together, so a later tick cannot inherit this one. Copy the note onto the card first if it is worth keeping.',
+        });
+      }
+
+      const data = await api('DELETE', path, { headers: buildMutationHeaders(args) });
+      const criterion = data?.data;
+      return ok({ unsatisfied: true, criterion, grade: criterion?.grade });
+    }
+  );
+
   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.
@@ -659,6 +1088,7 @@ TO @-MENTION SOMEBODY, write the token \`<@userId>\` in the body — the id come
         approved: args.approved,
         reason: args.reason,
         idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
       });
       if (preview?.dryRun) {
         return ok({ ...preview, wouldComment: { itemId: args.itemId, body: args.body } });
@@ -718,6 +1148,7 @@ This is what the ship-the-card skill means by "an unworkable card is a triage pr
         // reason explains the write and `body` is the content.
         reason: args.reason,
         idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
       });
       if (preview?.dryRun) {
         return ok({
@@ -746,12 +1177,20 @@ export const WORK_BOARD_TOOL_NAMES = [
   'get_work_board',
   'get_work_item',
   'get_work_item_history',
+  'get_work_item_delivery_evidence',
+  'audit_work_hub',
+  'list_work_item_acceptance_criteria',
   'get_work_board_rollup',
   'list_work_board_rollups',
+  'set_work_board_archived',
+  'set_work_board_column_wip_limit',
   'move_work_item',
   'set_work_item_tag',
   'set_work_item_kind',
   'create_work_item',
+  'add_work_item_acceptance_criterion',
+  'satisfy_work_item_acceptance_criterion',
+  'unsatisfy_work_item_acceptance_criterion',
   'get_work_item_comments',
   'comment_on_work_item',
   'flag_work_item',