@adrata/adrata-mcp 1.0.2 → 1.0.6

package/tools/work-board-tools.js

@@ -1,4 +1,51 @@
 import { auditWorkHubBoards, deliveryContradictions } from './work-hub/audit.js';
+import { createHash } from 'node:crypto';
+import { readFile, stat } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+
+const MAX_QA_IMAGE_BYTES = 10 * 1024 * 1024;
+const MAX_QA_VIDEO_BYTES = 100 * 1024 * 1024;
+
+/** Read evidence bytes locally without ever putting them in the MCP transcript. */
+export async function loadLocalQaEvidenceFile(filePath) {
+  const absolute = resolve(String(filePath || ''));
+  const safeName = basename(absolute);
+  try {
+    const info = await stat(absolute);
+    if (!info.isFile()) throw new Error('not_a_regular_file');
+    if (info.size <= 0 || info.size > MAX_QA_VIDEO_BYTES) {
+      throw new Error('outside_supported_size');
+    }
+    const bytes = await readFile(absolute);
+    return {
+      bytes,
+      fileName: safeName,
+      sizeBytes: bytes.byteLength,
+      sha256: createHash('sha256').update(bytes).digest('hex'),
+    };
+  } catch (error) {
+    const code = error?.code || error?.message || 'unreadable';
+    throw new Error(`Could not read QA evidence file "${safeName}": ${code}`);
+  }
+}
+
+/** PUT to the private presigned target while keeping its URL and headers process-private. */
+export async function uploadLocalQaEvidenceFile(ticket, bytes, fetchImpl = globalThis.fetch) {
+  if (!ticket?.uploadUrl || !ticket?.headers || typeof fetchImpl !== 'function') {
+    throw new Error('The API returned an incomplete private QA evidence upload capability.');
+  }
+  const response = await fetchImpl(ticket.uploadUrl, {
+    method: 'PUT',
+    headers: {
+      ...ticket.headers,
+      'Content-Length': String(bytes.byteLength),
+    },
+    body: bytes,
+  });
+  if (!response.ok) {
+    throw new Error(`Private QA evidence upload failed with HTTP ${response.status}.`);
+  }
+}
 
 /**
  * Work-board tools for the Adrata MCP Server.
@@ -131,6 +178,19 @@ export function describeMissingAcceptanceCriteria(criteria) {
   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);
@@ -151,10 +211,115 @@ export function projectColumnWip({ limit, count, cardAlreadyThere, truncated = f
  */
 export function registerWorkBoardTools(
   server,
-  { z, api, ok, validateApiBridgeRequest, buildMutationHeaders, getGrantedScope = () => undefined }
+  {
+    z,
+    api,
+    ok,
+    validateApiBridgeRequest,
+    buildMutationHeaders,
+    getGrantedScope = () => undefined,
+    loadQaEvidenceFile = loadLocalQaEvidenceFile,
+    uploadQaEvidenceFile = uploadLocalQaEvidenceFile,
+  }
 ) {
   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).';
+  // Capability material belongs to this MCP process, not to the model transcript.
+  // A winning claim stores it here; heartbeat/release address the card by its
+  // public id and the handler adds the three private headers at the last hop.
+  const workerLeaseCapabilities = new Map();
+
+  function rememberWorkerLease(itemId, grant, claimIdempotencyKey) {
+    if (!grant?.leaseId || !grant?.leaseToken || !Number.isInteger(grant?.fencingToken)) {
+      throw new Error('The API returned an incomplete worker-lease grant; no capability was stored.');
+    }
+    workerLeaseCapabilities.set(itemId, {
+      leaseId: grant.leaseId,
+      leaseToken: grant.leaseToken,
+      fencingToken: grant.fencingToken,
+      claimIdempotencyKey,
+    });
+    const { leaseToken: _secret, fencingToken: _fence, qaRequirements, currentCriteria, ...lease } =
+      grant;
+    return { lease, qaRequirements, currentCriteria };
+  }
+
+  function conflictingHeldCard(itemId, claimIdempotencyKey) {
+    for (const [heldItemId, capability] of workerLeaseCapabilities) {
+      const sameCard = itemId != null && heldItemId === itemId;
+      const sameClaim =
+        claimIdempotencyKey != null && capability.claimIdempotencyKey === claimIdempotencyKey;
+      if (!sameCard && !sameClaim) return heldItemId;
+    }
+    return null;
+  }
+
+  function workerLeaseHeaders(itemId) {
+    const capability = workerLeaseCapabilities.get(itemId);
+    if (!capability) return null;
+    return {
+      'x-adrata-worker-lease': capability.leaseId,
+      'x-adrata-worker-token': capability.leaseToken,
+      'x-adrata-worker-fence': String(capability.fencingToken),
+    };
+  }
+
+  function mutationHeadersForItem(args, itemId) {
+    return {
+      ...buildMutationHeaders(args),
+      ...(workerLeaseHeaders(itemId) ?? {}),
+    };
+  }
+
+  function requiredWorkerLeaseHeaders(itemId) {
+    const headers = workerLeaseHeaders(itemId);
+    if (!headers) {
+      throw new Error(
+        `No process-private QA lease capability is held for ${itemId}. Claim this card's current QA pass in this MCP session before recording engineering proof.`
+      );
+    }
+    return headers;
+  }
+
+  // A caller may legitimately use the API maximum (255 characters). Appending
+  // an operation suffix would then turn every child write into a 400 and leave
+  // a composite half-finished. Hash the caller key into short, deterministic,
+  // endpoint-specific keys instead. The original key never leaves this process
+  // through a child request.
+  function childIdempotencyKey(baseKey, operation) {
+    const digest = createHash('sha256').update(String(baseKey)).digest('hex');
+    return `qa-${operation}-${digest}`;
+  }
+
+  async function releaseHeldPass(args, releaseKind, leaseHeaders) {
+    const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/worker-lease/release`;
+    try {
+      const data = await api('POST', path, {
+        body: { releaseKind },
+        headers: { ...buildMutationHeaders(args), ...leaseHeaders },
+      });
+      workerLeaseCapabilities.delete(args.itemId);
+      return { workerLease: data?.data, recoveredAfterResponseLoss: false };
+    } catch (releaseError) {
+      // A successful release whose HTTP response was lost is already safe on
+      // the server. Confirm the public state before retaining a phantom local
+      // capability that would prevent this worker from taking its next card.
+      try {
+        const current = await api(
+          'GET',
+          `/api/v1/work-items/${encodeURIComponent(args.itemId)}/worker-lease`
+        );
+        if (!current?.data) {
+          workerLeaseCapabilities.delete(args.itemId);
+          return { workerLease: null, recoveredAfterResponseLoss: true };
+        }
+      } catch {
+        // Preserve the original release error; an unavailable status read is
+        // not evidence that the lease did or did not close.
+      }
+      throw releaseError;
+    }
+  }
 
   // =========================================================================
   // READS
@@ -180,7 +345,9 @@ Start here for "what should I work on". With includeUnassigned it also returns t
       limit: z
         .number()
         .optional()
-        .describe('Cap each list. Defaults to 50; a queue that needs a second page is not a queue.'),
+        .describe(
+          'Cap each list. Defaults to 50; a queue that needs a second page is not a queue.'
+        ),
     },
     async (args) => {
       const params = new URLSearchParams();
@@ -188,10 +355,7 @@ Start here for "what should I work on". With includeUnassigned it also returns t
       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 data = await api('GET', `/api/v1/work-items/assigned-to-me${query ? `?${query}` : ''}`);
       const queue = data?.data || {};
       const mine = queue.assignedToMe || [];
       return ok({
@@ -243,14 +407,14 @@ Start here for "what should I work on". With includeUnassigned it also returns t
         // 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.',
+          "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.',
+    "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.'),
     },
@@ -260,6 +424,367 @@ Start here for "what should I work on". With includeUnassigned it also returns t
     }
   );
 
+  server.tool(
+    'get_work_item_worker_lease',
+    'Read who, if anyone, is actively running this card’s current QA pass. Returns the accountable teammate, declared agent/session labels, and Live or Stalled freshness. It never returns the bearer token, fencing value, or credential identity.',
+    { itemId: z.string().describe('Card id.') },
+    async (args) => {
+      const data = await api(
+        'GET',
+        `/api/v1/work-items/${encodeURIComponent(args.itemId)}/worker-lease`
+      );
+      return ok({ workerLease: data?.data ?? null });
+    }
+  );
+
+  server.tool(
+    'get_work_item_worker_activity',
+    'Read the human-readable worker lifecycle for one card: claim, conflict, renewal, stall, release, handoff, and audited takeover. Entries carry only public teammate/agent/session labels and timestamps; capability and credential material never appear.',
+    { itemId: z.string().describe('Card id.') },
+    async (args) => {
+      const data = await api(
+        'GET',
+        `/api/v1/work-items/${encodeURIComponent(args.itemId)}/worker-lease-events`
+      );
+      const events = data?.data ?? [];
+      return ok({ count: events.length, events });
+    }
+  );
+
+  server.tool(
+    'claim_work_item_qa_pass',
+    `Take one named card’s current Staging QA1 or Staging QA2 pass without changing its durable owner. A winning response includes the current acceptance criteria and the recorded-QA rules you must follow. The bearer and fence stay process-private; later heartbeat and release tools use them without putting them in the conversation.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id.'),
+      agentName: z.enum(['claude-code', 'codex', 'grok', 'human']),
+      runLabel: z.string().describe('Concise public session label, not a transcript or secret.'),
+      workerLabel: z.string().describe('Concise public worker label, not a transcript or secret.'),
+      takeoverStalled: z.boolean().optional().default(false),
+      dryRun: z.boolean().optional().default(true),
+      approved: z.boolean().optional().default(false),
+      reason: z.string().optional(),
+      idempotencyKey: z.string().optional(),
+    },
+    async (args) => {
+      const heldItemId = conflictingHeldCard(args.itemId, args.idempotencyKey);
+      if (heldItemId) {
+        return ok({
+          error: true,
+          message: `This MCP worker already holds card ${heldItemId}. Transition or release it before claiming another pass.`,
+        });
+      }
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/worker-lease/claim`;
+      const body = {
+        agentName: args.agentName,
+        runLabel: args.runLabel,
+        workerLabel: args.workerLabel,
+        takeoverStalled: args.takeoverStalled === true,
+        idempotencyKey: args.idempotencyKey,
+      };
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        body,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview.dryRun) {
+        return ok({
+          dryRun: true,
+          action: `Take the current QA pass for card ${args.itemId}`,
+          note: 'No lease was created. Confirm to claim this pass atomically.',
+        });
+      }
+      const data = await api('POST', path, {
+        body,
+        headers: buildMutationHeaders(args),
+      });
+      const visible = rememberWorkerLease(args.itemId, data?.data, args.idempotencyKey);
+      return ok({ claimed: true, ...visible });
+    }
+  );
+
+  server.tool(
+    'claim_next_work_item_qa_pass',
+    `Atomically choose and take the first workable QA pass for ONE exact product in ONE requested gate across every board this worker can see. Product is read from the card, never inferred from the board that happens to hold it. QA1 and QA2 pools must name their gate explicitly; a QA1 drain can never consume QA2 work and vice versa. Concurrent sessions receive distinct cards; one MCP worker holds at most one pass at a time. An empty result means no eligible pass remains in that product/gate. The response returns the selected board and card, explains the selection, and carries the exact acceptance criteria and recorded-QA requirements. Capability material stays inside this MCP process.${GOVERNED_NOTE}`,
+    {
+      qaGate: z.enum(['Staging QA1', 'Staging QA2']).describe('Exact gate this worker pool is allowed to drain.'),
+      product: z.string().min(1).max(120).describe('Exact card product to drain, such as Adrata or Starfield, across all visible boards.'),
+      agentName: z.enum(['claude-code', 'codex', 'grok', 'human']),
+      runLabel: z.string().describe('Concise public session label, not a transcript or secret.'),
+      workerLabel: z.string().describe('Concise public worker label, not a transcript or secret.'),
+      dryRun: z.boolean().optional().default(true),
+      approved: z.boolean().optional().default(false),
+      reason: z.string().optional(),
+      idempotencyKey: z.string().optional(),
+    },
+    async (args) => {
+      const heldItemId = conflictingHeldCard(null, args.idempotencyKey);
+      if (heldItemId) {
+        return ok({
+          error: true,
+          message: `This MCP worker already holds card ${heldItemId}. Transition or release it before claiming another pass.`,
+        });
+      }
+      const path = '/api/v1/work-boards/worker-leases/claim-next';
+      const body = {
+        qaGate: args.qaGate,
+        product: args.product,
+        agentName: args.agentName,
+        runLabel: args.runLabel,
+        workerLabel: args.workerLabel,
+        takeoverStalled: false,
+        idempotencyKey: args.idempotencyKey,
+      };
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        body,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview.dryRun) {
+        return ok({
+          dryRun: true,
+          action: `Atomically take the first workable ${args.product} ${args.qaGate} pass across all visible boards`,
+          note: 'No card was claimed. Confirm to select and claim one pass.',
+        });
+      }
+      const data = await api('POST', path, {
+        body,
+        headers: buildMutationHeaders(args),
+      });
+      const selected = data?.data;
+      if (!selected) {
+        return ok({ claimed: false, qaGate: args.qaGate, product: args.product, note: `No eligible unclaimed ${args.product} ${args.qaGate} pass remains on any visible board.` });
+      }
+      const visible = rememberWorkerLease(selected.workItemId, selected.grant, args.idempotencyKey);
+      return ok({
+        claimed: true,
+        workItemId: selected.workItemId,
+        boardId: selected.boardId,
+        boardName: selected.boardName,
+        title: selected.title,
+        product: selected.product,
+        selectionReason: selected.selectionReason,
+        ...visible,
+      });
+    }
+  );
+
+  server.tool(
+    'heartbeat_work_item_qa_pass',
+    `Keep the current MCP session’s claimed QA pass Live. The private bearer and fence are attached inside this process; they are never accepted as tool arguments or returned in the result.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id returned by a winning claim in this MCP session.'),
+      dryRun: z.boolean().optional().default(true),
+      approved: z.boolean().optional().default(false),
+      reason: z.string().optional(),
+      idempotencyKey: z.string().optional(),
+    },
+    async (args) => {
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/worker-lease/heartbeat`;
+      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({
+          dryRun: true,
+          action: `Keep card ${args.itemId} actively held by this worker`,
+          note: 'The lease expiry is unchanged until this write is confirmed.',
+        });
+      }
+      const headers = workerLeaseHeaders(args.itemId);
+      if (!headers) {
+        return ok({
+          error: true,
+          message: 'This MCP session has no capability for that card. Claim the QA pass first.',
+        });
+      }
+      const data = await api('POST', path, {
+        headers: { ...buildMutationHeaders(args), ...headers },
+      });
+      return ok({ workerLease: data?.data });
+    }
+  );
+
+  server.tool(
+    'release_work_item_qa_pass',
+    `Release or hand off the current MCP session’s QA pass. This closes the active lease but does not change the card’s durable owner. The private capability is supplied from process memory and removed after a successful release.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id returned by a winning claim in this MCP session.'),
+      releaseKind: z.enum(['released', 'handoff']).optional().default('released'),
+      dryRun: z.boolean().optional().default(true),
+      approved: z.boolean().optional().default(false),
+      reason: z.string().optional(),
+      idempotencyKey: z.string().optional(),
+    },
+    async (args) => {
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/worker-lease/release`;
+      const body = { releaseKind: args.releaseKind ?? 'released' };
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        body,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview.dryRun) {
+        return ok({
+          dryRun: true,
+          action: `${body.releaseKind === 'handoff' ? 'Hand off' : 'Release'} card ${args.itemId}`,
+          note: 'The active worker remains unchanged until this write is confirmed.',
+        });
+      }
+      const leaseHeaders = workerLeaseHeaders(args.itemId);
+      if (!leaseHeaders) {
+        return ok({
+          error: true,
+          message: 'This MCP session has no capability for that card. Nothing was released.',
+        });
+      }
+      const release = await releaseHeldPass(args, body.releaseKind, leaseHeaders);
+      return ok({ released: true, releaseKind: body.releaseKind, ...release });
+    }
+  );
+
+  server.tool(
+    'record_work_item_qa_failure_and_release',
+    `Durably record why the current QA pass cannot proceed, then safely release the process-private lease without moving the card. A failed criterion is flagged first, un-ticked, and left on the same QA card waiting for a fix and deployed build; it is NOT immediately reclaimable against the unchanged build. A dependency blocker is flagged in place. Both paths release the lease only after the durable safety state exists, so claim-next skips the card until an explicit requeue. This is one governed recovery recipe, not a new bug card and not a QA bounce.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card currently claimed by this MCP worker.'),
+      disposition: z.enum(['failed_criterion', 'blocked_dependency']),
+      criterionId: z.string().optional().describe('Required for failed_criterion; the exact acceptance criterion contradicted.'),
+      details: z.string().describe('Concrete observed failure or blocker and the recovery needed. Stored on the card.'),
+      dryRun: z.boolean().optional().default(true),
+      approved: z.boolean().optional().default(false),
+      reason: z.string().optional(),
+      idempotencyKey: z.string().optional().describe('Required live base key; child writes derive stable endpoint-specific keys.'),
+    },
+    async (args) => {
+      if (!args.details?.trim()) {
+        return ok({ error: true, message: 'details must name the observed failure or blocker.' });
+      }
+      if (args.disposition === 'failed_criterion' && !args.criterionId) {
+        return ok({ error: true, message: 'criterionId is required for a failed criterion.' });
+      }
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path: `/api/v1/work-items/${encodeURIComponent(args.itemId)}/comments`,
+        body: { disposition: args.disposition, criterionId: args.criterionId, details: args.details },
+        dryRun: args.dryRun, approved: args.approved, reason: args.reason,
+        idempotencyKey: args.idempotencyKey, grantedScope: getGrantedScope(),
+      });
+      if (preview.dryRun) {
+        return ok({
+          ...preview,
+          wouldRecordQaFailure: {
+            itemId: args.itemId,
+            disposition: args.disposition,
+            criterionId: args.criterionId ?? null,
+            details: args.details,
+          },
+          note: args.disposition === 'failed_criterion'
+            ? 'The card will stay in its QA column, be flagged and un-ticked, then release the pass while waiting for a fixed deployed build.'
+            : 'The card will be flagged in place and the pass handed off.',
+        });
+      }
+      const leaseHeaders = workerLeaseHeaders(args.itemId);
+      if (!leaseHeaders) {
+        return ok({ error: true, message: 'This MCP session has no capability for that card. Nothing was recorded or released.' });
+      }
+      const recordKey = childIdempotencyKey(args.idempotencyKey, 'record');
+      const untickKey = childIdempotencyKey(args.idempotencyKey, 'untick');
+      const releaseKey = childIdempotencyKey(args.idempotencyKey, 'release');
+      const flagReason = args.disposition === 'failed_criterion'
+        ? `QA criterion failure (${args.criterionId}): ${args.details.trim()} Waiting for a fixed deployed build before requeue.`
+        : args.details.trim();
+      // Flag first. If this composite is interrupted after any following step,
+      // claim-next still cannot put another worker into a hot loop on the same
+      // broken build. Every child is endpoint-idempotent, so a retry continues.
+      await api('POST', `/api/v1/work-items/${encodeURIComponent(args.itemId)}/flag`, {
+        body: { flagged: true, reason: flagReason, idempotencyKey: recordKey },
+        headers: mutationHeadersForItem({ ...args, idempotencyKey: recordKey }, args.itemId),
+      });
+      if (args.disposition === 'failed_criterion') {
+        await api('DELETE', criterionSatisfactionPath(args.itemId, args.criterionId), {
+          headers: mutationHeadersForItem({ ...args, idempotencyKey: untickKey }, args.itemId),
+        });
+      }
+      const releaseKind = args.disposition === 'failed_criterion' ? 'released' : 'handoff';
+      const release = await releaseHeldPass(
+        { ...args, idempotencyKey: releaseKey },
+        releaseKind,
+        leaseHeaders
+      );
+      return ok({
+        recorded: true,
+        disposition: args.disposition,
+        requeued: false,
+        blocked: true,
+        waitingForFix: args.disposition === 'failed_criterion',
+        releaseKind,
+        ...release,
+      });
+    }
+  );
+
+  server.tool(
+    'requeue_work_item_qa_after_fix',
+    `Clear a failed QA card’s waiting-for-fix flag only after a different exact build has been deployed and its relationship to the failed build has been checked. This does not claim the card; it makes the same card eligible for a fresh QA pass. The clear reason durably records both SHAs and the fix/deployment reference. The worker must verify ancestry in source control before calling this tool; this endpoint rejects the unchanged SHA but does not pretend to be a Git ancestry oracle.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Flagged QA card left in place by record_work_item_qa_failure_and_release.'),
+      failedBuildSha: z.string().length(40).describe('Exact lowercase 40-character SHA of the build that failed.'),
+      deployedBuildSha: z.string().length(40).describe('Exact lowercase 40-character SHA of the newer deployed descendant build.'),
+      details: z.string().describe('How ancestry and deployment were verified, including the fix PR or deployment reference.'),
+      dryRun: z.boolean().optional().default(true),
+      approved: z.boolean().optional().default(false),
+      reason: z.string().optional(),
+      idempotencyKey: z.string().optional(),
+    },
+    async (args) => {
+      const exactSha = (value) => /^[0-9a-f]{40}$/.test(value ?? '');
+      if (!exactSha(args.failedBuildSha) || !exactSha(args.deployedBuildSha)) {
+        return ok({ error: true, message: 'Both build SHAs must be exact lowercase 40-character Git SHAs.' });
+      }
+      if (args.failedBuildSha === args.deployedBuildSha) {
+        return ok({ error: true, message: 'The unchanged failed build cannot be requeued.' });
+      }
+      if (!args.details?.trim()) {
+        return ok({ error: true, message: 'details must name the ancestry check and deployment/fix reference.' });
+      }
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/flag`;
+      const clearReason = `QA requeue: deployed ${args.deployedBuildSha} after failed ${args.failedBuildSha}. ${args.details.trim()}`;
+      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, wouldRequeue: { itemId: args.itemId, failedBuildSha: args.failedBuildSha, deployedBuildSha: args.deployedBuildSha } });
+      }
+      const data = await api('POST', path, {
+        body: { flagged: false, reason: clearReason, idempotencyKey: args.idempotencyKey },
+        headers: buildMutationHeaders(args),
+      });
+      return ok({ requeued: true, item: data?.data, failedBuildSha: args.failedBuildSha, deployedBuildSha: args.deployedBuildSha });
+    }
+  );
+
   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.',
@@ -307,6 +832,20 @@ Start here for "what should I work on". With includeUnassigned it also returns t
     }
   );
 
+  server.tool(
+    'list_work_item_qa_evidence',
+    'Read the durable image/video QA receipts attached to one card. Returns governed metadata and availability, never a presigned content URL or storage capability. Use the card UI to review playback; use attach_work_item_qa_evidence to add a fresh receipt.',
+    { itemId: z.string().describe('Card id.') },
+    async (args) => {
+      const data = await api(
+        'GET',
+        `/api/v1/work-items/${encodeURIComponent(args.itemId)}/qa-evidence`
+      );
+      const evidence = data?.data ?? [];
+      return ok({ count: evidence.length, evidence });
+    }
+  );
+
   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.`,
@@ -335,10 +874,7 @@ Start here for "what should I work on". With includeUnassigned it also returns t
     },
     async (args) => {
       const rollupId = args.rollupId || 'all';
-      const data = await api(
-        'GET',
-        `/api/v1/work-board-rollups/${encodeURIComponent(rollupId)}`
-      );
+      const data = await api('GET', `/api/v1/work-board-rollups/${encodeURIComponent(rollupId)}`);
       return ok({ rollup: data?.data });
     }
   );
@@ -356,7 +892,7 @@ Start here for "what should I work on". With includeUnassigned it also returns t
 
   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.',
+    "Read what people have SAID about a card, newest 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.'),
     },
@@ -370,7 +906,7 @@ Start here for "what should I work on". With includeUnassigned it also returns t
         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.',
+          'Newest first, matching the Activity timeline. 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.',
       });
     }
   );
@@ -379,6 +915,175 @@ Start here for "what should I work on". With includeUnassigned it also returns t
   // WRITES
   // =========================================================================
 
+  server.tool(
+    'attach_work_item_qa_evidence',
+    `Attach one finalized local image or video to the card's CURRENT claimed QA dwell. This is the whole governed flow: the MCP process reads and hashes the local file, asks Adrata for a private upload capability, uploads the bytes directly, renews the worker lease, finalizes server-side verification, and returns only the durable receipt. File bytes, the local path, presigned URLs, upload headers, lease bearer, and fence never enter the conversation. Claim the pass first and keep recordings synthetic/redacted.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id returned by this MCP session’s winning QA claim.'),
+      criterionId: z.string().optional().describe('Acceptance criterion this recording proves. Required by the API when the card has criteria.'),
+      filePath: z.string().describe('Local path to the finalized PNG, JPEG, WebP, GIF, MP4, or WebM. The path and bytes stay process-private.'),
+      mimeType: z.enum(['image/png', 'image/jpeg', 'image/webp', 'image/gif', 'video/mp4', 'video/webm']),
+      environment: z.enum(['local', 'staging', 'production']),
+      declaredBuildSha: z.string().describe('Exact lowercase 40-character deployed Git SHA tested by this recording.'),
+      declaredReviewerAgent: z.string().describe('Agent/runtime declaration shown on the receipt; never invent an unknown value.'),
+      declaredReviewerModel: z.string().describe('Model declaration shown on the receipt; use an honest unrecorded label rather than guessing.'),
+      outcome: z.enum(['pass', 'fail']),
+      summary: z.string().describe('Short synthetic-safe result summary. Never paste a transcript, token, customer data, or sensitive URL.'),
+      durationMs: z.number().int().positive().optional().describe('Final media duration for video, measured from the finalized file; omit for images.'),
+      checkpoints: z.array(z.object({
+        offsetMs: z.number().int().nonnegative(),
+        label: z.string(),
+      })).optional().describe('Ordered video checkpoints beginning at 0; omit for images.'),
+      consoleErrorCount: z.number().int().nonnegative(),
+      pageErrorCount: z.number().int().nonnegative(),
+      networkErrorCount: z.number().int().nonnegative(),
+      redactionConfirmed: z.literal(true).describe('Confirms synthetic/approved data and no visible credentials, tokens, customer data, or sensitive query values.'),
+      dryRun: z.boolean().optional().default(true),
+      approved: z.boolean().optional().default(false),
+      reason: z.string().optional().describe('Required for a live attachment: what journey was recorded and why it belongs on this criterion.'),
+      idempotencyKey: z.string().optional().describe('Required for a live attachment. Reuse the SAME key on retry.'),
+    },
+    async (args) => {
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/qa-evidence/uploads`;
+      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,
+          wouldAttachQaEvidence: {
+            itemId: args.itemId,
+            criterionId: args.criterionId ?? null,
+            fileName: basename(String(args.filePath || '')),
+            mimeType: args.mimeType,
+            environment: args.environment,
+            declaredBuildSha: args.declaredBuildSha,
+            outcome: args.outcome,
+          },
+          note: 'The local file has not been read or uploaded. Its path and bytes will remain process-private after approval.',
+        });
+      }
+
+      const leaseHeaders = workerLeaseHeaders(args.itemId);
+      if (!leaseHeaders) {
+        return ok({
+          error: true,
+          message: 'This MCP session has no capability for that card. Claim the QA pass before attaching evidence.',
+        });
+      }
+      const local = await loadQaEvidenceFile(args.filePath);
+      const maxBytes = args.mimeType.startsWith('image/')
+        ? MAX_QA_IMAGE_BYTES
+        : MAX_QA_VIDEO_BYTES;
+      if (local.sizeBytes <= 0 || local.sizeBytes > maxBytes) {
+        throw new Error(`QA ${args.mimeType.startsWith('image/') ? 'image' : 'video'} exceeds its governed size limit.`);
+      }
+      const request = {
+        acceptanceCriterionId: args.criterionId ?? null,
+        environment: args.environment,
+        declaredBuildSha: args.declaredBuildSha,
+        fileName: local.fileName,
+        mimeType: args.mimeType,
+        sizeBytes: local.sizeBytes,
+        sha256: local.sha256,
+        declaredReviewerAgent: args.declaredReviewerAgent,
+        declaredReviewerModel: args.declaredReviewerModel,
+        outcome: args.outcome,
+        summary: args.summary,
+        declaredDurationMs: args.durationMs ?? null,
+        checkpoints: args.checkpoints ?? [],
+        declaredConsoleErrorCount: args.consoleErrorCount,
+        declaredPageErrorCount: args.pageErrorCount,
+        declaredNetworkErrorCount: args.networkErrorCount,
+        redactionConfirmed: args.redactionConfirmed === true,
+      };
+      const initiateHeaders = { ...buildMutationHeaders(args), ...leaseHeaders };
+      const initiated = await api('POST', path, { body: request, headers: initiateHeaders });
+      const ticket = initiated?.data;
+      if (!ticket?.id || !ticket?.uploadUrl || !ticket?.headers) {
+        throw new Error('The API returned an incomplete private QA evidence upload capability.');
+      }
+
+      const heartbeatPath = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/worker-lease/heartbeat`;
+      // Initiation owns the caller's replay key. Heartbeat and completion are
+      // separate resources with their own server-side retry semantics, so they
+      // receive only the private lease capability rather than reusing one
+      // Idempotency-Key across three endpoints.
+      await api('POST', heartbeatPath, { headers: leaseHeaders });
+      try {
+        await uploadQaEvidenceFile(ticket, local.bytes);
+      } catch {
+        throw new Error(`QA evidence ${ticket.id} could not be uploaded to private storage.`);
+      }
+      await api('POST', heartbeatPath, { headers: leaseHeaders });
+
+      let completed;
+      try {
+        completed = await api(
+          'POST',
+          `/api/v1/work-items/${encodeURIComponent(args.itemId)}/qa-evidence/${encodeURIComponent(ticket.id)}/complete`,
+          { headers: leaseHeaders }
+        );
+      } catch {
+        throw new Error(`QA evidence ${ticket.id} could not be finalized by Adrata.`);
+      }
+      return ok({ attached: true, evidence: completed?.data });
+    }
+  );
+
+  server.tool(
+    'verify_work_item_qa_evidence_playback',
+    `Record the separate fact that you REOPENED an already-uploaded QA video in the card UI and personally observed it load, play, seek, and enter fullscreen. Upload completion proves stored bytes only; never call this tool from an upload response or without exercising all four controls. The receipt is bound to the current claimed QA dwell and server-authenticated credential. In QA2 you may verify the current QA2 recording or the recording from the immediately preceding QA1 dwell.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id currently claimed by this MCP worker.'),
+      evidenceId: z.string().describe('Video evidence receipt id actually reopened in the signed-in card UI.'),
+      contentLoaded: z.literal(true).describe('True only after the video rendered usable media.'),
+      playStarted: z.literal(true).describe('True only after playback visibly started.'),
+      seekCompleted: z.literal(true).describe('True only after seeking to another point completed.'),
+      fullscreenEntered: z.literal(true).describe('True only after the video entered native or in-page fullscreen.'),
+      dryRun: z.boolean().optional().default(true),
+      approved: z.boolean().optional().default(false),
+      reason: z.string().optional().describe('Required live audit reason naming the playback review.'),
+      idempotencyKey: z.string().optional().describe('Required live key. Reuse the SAME key only for the same playback review.'),
+    },
+    async (args) => {
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/qa-evidence/${encodeURIComponent(args.evidenceId)}/playback-verifications`;
+      const body = {
+        contentLoaded: args.contentLoaded,
+        playStarted: args.playStarted,
+        seekCompleted: args.seekCompleted,
+        fullscreenEntered: args.fullscreenEntered,
+      };
+      const preview = validateApiBridgeRequest({
+        method: 'POST', path, body, dryRun: args.dryRun, approved: args.approved,
+        reason: args.reason, idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview.dryRun) {
+        return ok({
+          ...preview,
+          wouldVerifyPlayback: { itemId: args.itemId, evidenceId: args.evidenceId },
+          note: 'No receipt was written. Confirm only after the signed-in video loaded, played, sought, and entered fullscreen.',
+        });
+      }
+      const leaseHeaders = workerLeaseHeaders(args.itemId);
+      if (!leaseHeaders) {
+        return ok({ error: true, message: 'This MCP session has no capability for that card. Claim the QA pass before recording playback.' });
+      }
+      const data = await api('POST', path, {
+        body,
+        headers: { ...buildMutationHeaders(args), ...leaseHeaders },
+      });
+      return ok({ playbackVerification: data?.data });
+    }
+  );
+
   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}`,
@@ -387,7 +1092,10 @@ Start here for "what should I work on". With includeUnassigned it also returns t
       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.'),
+      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) => {
@@ -444,7 +1152,10 @@ Start here for "what should I work on". With includeUnassigned it also returns t
         .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.'),
+      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) => {
@@ -487,7 +1198,9 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
       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.'),
+        .describe(
+          'Target column id. Must be a column on the SAME board — get it from get_work_board.'
+        ),
       position: z
         .number()
         .optional()
@@ -516,6 +1229,51 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
         .string()
         .optional()
         .describe('Required for a live move. Reuse the SAME key on retry; the server replays.'),
+      receipt: z
+        .object({
+          commitSha: z
+            .string()
+            .optional()
+            .describe('The commit or merge SHA the claim rests on — 7 to 40 hex characters.'),
+          pullRequestNumber: z.number().int().optional().describe('The PR number.'),
+          pullRequestUrl: z.string().optional().describe('The PR URL (https).'),
+          repositoryFullName: z.string().optional().describe('owner/name.'),
+          ciProvider: z
+            .enum(['github_actions', 'gitlab_ci', 'local'])
+            .optional()
+            .describe(
+              'Which system the run id belongs to. Required alongside ciRunId: an id with no provider names no API to re-fetch it from. `local` is first-class — evidence from a local verification run belongs here rather than in a second mechanism.'
+            ),
+          ciRunId: z
+            .string()
+            .optional()
+            .describe(
+              'The CI or test run BY ID, so a reader can re-fetch it instead of believing you.'
+            ),
+          ciRunUrl: z
+            .string()
+            .optional()
+            .describe('Where to fetch it, when the URL is not derivable.'),
+          environment: z
+            .enum(['local', 'staging', 'production'])
+            .optional()
+            .describe('Where the check ran, if it ran against a running system.'),
+          verifiedUrl: z.string().optional().describe('The exact URL that was checked.'),
+          sessionRef: z
+            .string()
+            .optional()
+            .describe(
+              'A POINTER to your session — an id or a hash. NEVER its contents. Letters, digits, dot, underscore, colon and hyphen only, 8 to 128 characters; anything carrying a space or a newline is refused by the server AND by the column. Do not put transcript text, message bodies, tool output, or anything you were told in confidence anywhere in this receipt.'
+            ),
+          sessionRefKind: z
+            .enum(['claude_session_id', 'codex_session_id', 'sha256'])
+            .optional()
+            .describe('What kind of pointer sessionRef is. Required alongside it.'),
+        })
+        .optional()
+        .describe(
+          'The STRUCTURED evidence this move rests on, stored beside the reason rather than instead of it. Every field is a REFERENCE somebody can re-check without trusting you: a SHA verified against main, a run id re-fetched from the vendor. There is deliberately no field for a sentence — that is what `reason` is for. Send it whenever the move rests on something that landed; a move with no receipt is counted as a move that named no merge commit, which is a real and useful answer.'
+        ),
     },
     async (args) => {
       if (args.force === true && args.claim !== true) {
@@ -539,10 +1297,7 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
         grantedScope: getGrantedScope(),
       });
       if (preview?.dryRun) {
-        const itemData = await api(
-          'GET',
-          `/api/v1/work-items/${encodeURIComponent(args.itemId)}`
-        );
+        const itemData = await api('GET', `/api/v1/work-items/${encodeURIComponent(args.itemId)}`);
         const item = itemData?.data;
         const boardData = await api(
           'GET',
@@ -553,7 +1308,7 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
         if (!target) {
           return ok({
             error: true,
-            message: 'toColumnId is not a column on this card\'s board.',
+            message: "toColumnId is not a column on this card's board.",
           });
         }
         const count = (board.items ?? []).filter(
@@ -567,6 +1322,7 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
             position: args.position,
             claim: args.claim === true,
             force: args.force === true,
+            receipt: args.receipt !== undefined,
           },
           wip: projectColumnWip({
             limit: target.wipLimit,
@@ -577,6 +1333,19 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
         });
       }
 
+      // A same-column move is only a reorder: the QA dwell and server lease
+      // remain open. Read the source immediately before the governed write so
+      // this process drops its capability only when the move truly transitions
+      // columns. A stale capability is still rejected by the server fence, but
+      // prematurely forgetting a live one would strand the claimed pass.
+      let sourceColumnId = null;
+      if (workerLeaseCapabilities.has(args.itemId)) {
+        const beforeMove = await api(
+          'GET',
+          `/api/v1/work-items/${encodeURIComponent(args.itemId)}`
+        );
+        sourceColumnId = beforeMove?.data?.columnId ?? null;
+      }
       const data = await api('POST', path, {
         body: {
           toColumnId: args.toColumnId,
@@ -587,13 +1356,22 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
           // about the assignee at all.
           claim: args.claim === true ? true : undefined,
           force: args.force === true ? true : undefined,
+          receipt: args.receipt,
         },
-        headers: buildMutationHeaders(args),
+        headers: mutationHeadersForItem(args, args.itemId),
       });
       const item = data?.data;
+      if (sourceColumnId !== args.toColumnId) {
+        workerLeaseCapabilities.delete(args.itemId);
+      }
       return ok({
         moved: true,
         claimed: args.claim === true,
+        // Echoed as a BOOLEAN, never as the receipt's contents. What the agent
+        // needs to know is whether the evidence was accepted; repeating a
+        // session pointer back into a conversation transcript is the leak this
+        // whole field is shaped to avoid.
+        receiptRecorded: args.receipt !== undefined,
         // 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
@@ -605,6 +1383,117 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
     }
   );
 
+  server.tool(
+    'transfer_work_item_between_boards',
+    `Transfer one existing card identity to a column on another operating board. This is NOT a copy and NOT a workflow promotion: the server keeps the work-item id and every item-linked comment, criterion, task, QA-evidence row, release link and SCM link; closes the old board dwell; and opens the destination dwell in one transaction. Use move_work_item for a column on the same board. A transfer needs BOTH destination ids so a column from a different board cannot be attached accidentally.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Existing card id. It is preserved; no new card is created.'),
+      toBoardId: z.string().describe('Destination operating-board id from list_work_boards.'),
+      toColumnId: z
+        .string()
+        .describe('Destination column id from get_work_board(toBoardId). Must belong to toBoardId.'),
+      position: z
+        .number()
+        .optional()
+        .describe('Sort position within the target column. Omit to append.'),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false for a live transfer.'),
+      approved: z.boolean().optional().describe('Required true for a live transfer.'),
+      reason: z
+        .string()
+        .optional()
+        .describe('Required for a live transfer: why this operating board is canonical.'),
+      idempotencyKey: z
+        .string()
+        .optional()
+        .describe('Required for a live transfer. Reuse the SAME key on retry.'),
+      receipt: z
+        .object({
+          commitSha: z.string().optional(),
+          pullRequestNumber: z.number().int().optional(),
+          pullRequestUrl: z.string().optional(),
+          repositoryFullName: z.string().optional(),
+          ciProvider: z.enum(['github_actions', 'gitlab_ci', 'local']).optional(),
+          ciRunId: z.string().optional(),
+          ciRunUrl: z.string().optional(),
+          environment: z.enum(['local', 'staging', 'production']).optional(),
+          verifiedUrl: z.string().optional(),
+          sessionRef: z.string().optional(),
+          sessionRefKind: z
+            .enum(['claude_session_id', 'codex_session_id', 'sha256'])
+            .optional(),
+        })
+        .optional()
+        .describe('Optional structured references supporting the reconciliation decision.'),
+    },
+    async (args) => {
+      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)}/transfer`;
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) {
+        const [itemData, boardData] = await Promise.all([
+          api('GET', `/api/v1/work-items/${encodeURIComponent(args.itemId)}`),
+          api('GET', `/api/v1/work-boards/${encodeURIComponent(args.toBoardId)}`),
+        ]);
+        const item = itemData?.data;
+        const board = boardData?.data;
+        if (item?.boardId === args.toBoardId) {
+          return ok({
+            error: true,
+            message: 'The card already belongs to toBoardId; use move_work_item for same-board movement.',
+          });
+        }
+        const target = board?.columns?.find((column) => column.id === args.toColumnId);
+        if (!target) {
+          return ok({
+            error: true,
+            message: 'toColumnId is not a visible column on toBoardId.',
+          });
+        }
+        return ok({
+          ...preview,
+          wouldTransfer: {
+            itemId: args.itemId,
+            fromBoardId: item?.boardId,
+            toBoardId: args.toBoardId,
+            toColumnId: args.toColumnId,
+            position: args.position,
+            receipt: args.receipt !== undefined,
+          },
+          identityPreserved: true,
+          freshDestinationDwellRequired: true,
+        });
+      }
+
+      const data = await api('POST', path, {
+        body: {
+          toBoardId: args.toBoardId,
+          toColumnId: args.toColumnId,
+          position: args.position,
+          reason: args.reason,
+          idempotencyKey: args.idempotencyKey,
+          receipt: args.receipt,
+        },
+        headers: buildMutationHeaders(args),
+      });
+      return ok({
+        transferred: true,
+        identityPreserved: true,
+        receiptRecorded: args.receipt !== undefined,
+        item: data?.data,
+      });
+    }
+  );
+
   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}`,
@@ -733,7 +1622,7 @@ Pass kind:null to clear it back to UNTYPED. Untyped is a real state and is NOT t
 
   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.
+    `Create a card on a board. Lands in the named column, or in Backlog on a standard board when none is given.
 
 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.
 
@@ -767,9 +1656,12 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
         .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.'
+          "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.'),
+      columnId: z
+        .string()
+        .optional()
+        .describe('Target column. Defaults to Backlog on a standard board.'),
       assigneeUserId: z
         .string()
         .optional()
@@ -860,7 +1752,10 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
       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.'),
+      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) => {
@@ -885,6 +1780,234 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
       return ok({ added: true, criterion: data?.data });
     }
   );
+
+  server.tool(
+    'satisfy_work_item_acceptance_criterion',
+    `Tick one acceptance criterion with the evidence you actually observed.
+
+WHERE AND WHEN 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 QA PASS and your server-derived credential:
+
+  • \`verified\` — ticked during the card's CURRENT visit to Staging QA1 or Staging QA2 by an authenticated human, or by an agent credential distinct from the criterion author. In Staging QA2, that agent must also differ from the agent whose clean receipt opened Staging QA1.
+  • \`claimed\` — everything else: a build-column tick, an earlier-pass tick, an agent checking its own criterion, the same AI trying to certify both gates, or legacy evidence with no provable credential identity.
+
+EACH QA GATE IS ITS OWN GATE. A receipt belongs to the exact visit it was made in, not to the column's name. So a criterion verified in Staging QA1 reads \`claimed\` once the card reaches Staging QA2, and a card bounced out of QA1 and sent back needs checking again. This is not the board losing your evidence — the earlier pass stays in the card's activity and transition history. It is the board refusing to let one test present itself as two.
+
+The human path is deliberately accountable rather than artificially independent: a sole human reviewer may verify a card they own or a criterion they wrote. The two-AI path remains independent by credential, and one AI cannot impersonate two passes. Nothing fails when a tick grades as \`claimed\`; inspect the returned grade and leave the card where the actual evidence supports it.
+
+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.
+
+THE LATEST TICK IS THE ONE THAT COUNTS, and it REPLACES the one before it. The server writes the ticker, the credential, the column, the pass and the note in one statement, so a second tick overwrites the first — including its note. That is what makes two gates two gates: the QA2 reviewer re-ticks the same box to record their own pass, and a tick that could not be replaced would leave QA2 permanently reading QA1's receipt.
+
+The cost is real and it is the note: re-ticking discards the previous ticker's evidence, and the criterion row only ever shows its current pass. If that evidence is worth keeping, put it on the card with comment_on_work_item BEFORE you re-tick. Do not re-tick a box merely to attach your name to somebody else's finished check.${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 exact QA dwell and authenticated credential, so this preview cannot tell you which you will get. A human may verify an authored or owned card. An agent must differ from the criterion author; in Staging QA2 it must also differ from the agent whose clean Staging QA1 receipt opened the pass.',
+        });
+      }
+
+      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: mutationHeadersForItem(args, args.itemId),
+      });
+      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`: this is the independence rule working rather than a failure. The tick was outside this exact QA dwell, its authenticated agent credential authored the criterion, or its Staging QA2 credential did not differ from the agent that passed Staging QA1. The evidence remains recorded, but it does not open this gate.',
+            }
+          : {}),
+      });
+    }
+  );
+
+  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: mutationHeadersForItem(args, args.itemId),
+      });
+      const criterion = data?.data;
+      return ok({ unsatisfied: true, criterion, grade: criterion?.grade });
+    }
+  );
+
+  server.tool(
+    'record_work_item_criterion_engineering_proof',
+    `Record a structured, non-media Engineering verified receipt for one criterion in its current QA dwell. Use this only when the criterion is explicitly routed engineering or both. It records the exact build, environment, outcome, named code/test/configuration/data/runtime references, and the narrowest honest staging smoke. It does not upload an image or video and must never be described as a visual or user-journey pass. QA2 requires a different authenticated credential from the passing QA1 engineering receipt.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id.'),
+      criterionId: z.string().describe('Criterion id, not its display ordinal.'),
+      environment: z.enum(['staging', 'production']),
+      outcome: z.enum(['pass', 'fail']),
+      summary: z.string().describe('Short result summary; no raw logs or transcript content.'),
+      buildSha: z.string().regex(/^[0-9a-f]{40}$/).describe('Exact deployed 40-character commit SHA.'),
+      stagingSmoke: z.string().describe('The narrowest honest staging/runtime smoke performed.'),
+      proofs: z
+        .array(
+          z.object({
+            proofType: z.enum(['code', 'test', 'configuration', 'data', 'runtime']),
+            name: z.string(),
+            resultReference: z.string(),
+          })
+        )
+        .min(1),
+      declaredReviewerModel: z
+        .string()
+        .max(120)
+        .describe('Exact model used for this review, explicitly declared; never guessed.'),
+      dryRun: z.boolean().optional().describe('Defaults to true.'),
+      approved: z.boolean().optional().describe('Required true for a live receipt.'),
+      reason: z.string().optional().describe('Required audit reason for a live receipt.'),
+      idempotencyKey: z.string().optional().describe('Required for live writes; 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-items/${encodeURIComponent(args.itemId)}/acceptance-criteria/${encodeURIComponent(args.criterionId)}/engineering-proof`;
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      const receipt = {
+        environment: args.environment,
+        outcome: args.outcome,
+        summary: args.summary,
+        buildSha: args.buildSha,
+        stagingSmoke: args.stagingSmoke,
+        proofs: args.proofs,
+        declaredReviewerModel: args.declaredReviewerModel,
+        idempotencyKey: args.idempotencyKey,
+      };
+      if (preview?.dryRun) return ok({ ...preview, wouldRecord: receipt });
+      const data = await api('POST', path, {
+        body: receipt,
+        headers: {
+          ...buildMutationHeaders(args),
+          ...requiredWorkerLeaseHeaders(args.itemId),
+        },
+      });
+      return ok({ recorded: true, engineeringProof: 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.
@@ -904,7 +2027,9 @@ TO @-MENTION SOMEBODY, write the token \`<@userId>\` in the body — the id come
       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`.'),
+        .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()
@@ -948,7 +2073,9 @@ This is what the ship-the-card skill means by "an unworkable card is a triage pr
       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.'),
+        .describe(
+          'true raises the flag; false clears it. Raising an already-flagged card replaces the reason.'
+        ),
       reason: z
         .string()
         .describe(
@@ -959,7 +2086,9 @@ This is what the ship-the-card skill means by "an unworkable card is a triage pr
       idempotencyKey: z
         .string()
         .optional()
-        .describe('Required for a live change. Reuse the SAME key on retry — the flag also appends a comment.'),
+        .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()) {
@@ -1009,19 +2138,34 @@ export const WORK_BOARD_TOOL_NAMES = [
   'list_work_boards',
   'get_work_board',
   'get_work_item',
+  'get_work_item_worker_lease',
+  'get_work_item_worker_activity',
+  'claim_work_item_qa_pass',
+  'claim_next_work_item_qa_pass',
+  'heartbeat_work_item_qa_pass',
+  'release_work_item_qa_pass',
+  'record_work_item_qa_failure_and_release',
+  'requeue_work_item_qa_after_fix',
   'get_work_item_history',
   'get_work_item_delivery_evidence',
   'audit_work_hub',
   'list_work_item_acceptance_criteria',
+  'list_work_item_qa_evidence',
   'get_work_board_rollup',
   'list_work_board_rollups',
   'set_work_board_archived',
   'set_work_board_column_wip_limit',
+  'attach_work_item_qa_evidence',
+  'verify_work_item_qa_evidence_playback',
   'move_work_item',
+  'transfer_work_item_between_boards',
   'set_work_item_tag',
   'set_work_item_kind',
   'create_work_item',
   'add_work_item_acceptance_criterion',
+  'satisfy_work_item_acceptance_criterion',
+  'record_work_item_criterion_engineering_proof',
+  'unsatisfy_work_item_acceptance_criterion',
   'get_work_item_comments',
   'comment_on_work_item',
   'flag_work_item',