@adrata/adrata-mcp 1.0.3 → 1.0.7

package/tools/work-board-tools.js

@@ -1,4 +1,56 @@
 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;
+const QA_STAGE_NAMES = new Set(['staging qa1', 'staging qa2']);
+
+function isQaStageName(name) {
+  return QA_STAGE_NAMES.has(String(name ?? '').trim().toLowerCase());
+}
+
+/** 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 +183,45 @@ 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.';
 }
 
+/**
+ * Make the created card's own criteria counter agree with the criteria returned
+ * beside it.
+ *
+ * Criteria are written by a second call, AFTER `POST /items` has already
+ * answered. So the card snapshot in that answer was serialized before the rows
+ * existed and its derived `criteria.total` reads 0 — while the array a few
+ * lines below it in the same response holds the rows that were just committed.
+ * Two fields of one response, disagreeing.
+ *
+ * That is not cosmetic. An agent reading `item.criteria.total` from a create it
+ * just made concludes the card has NO executable definition of done, at exactly
+ * the moment the board exists to prevent that, and then either reports the card
+ * as not ready for build or re-adds criteria that already exist. The correct
+ * data is in the same response a few lines lower, which is what makes it
+ * invisible.
+ *
+ * The repair is a fresh read of the card rather than a locally patched number,
+ * because the counter is derived server-side and the server is the only party
+ * that can state it. The read is skipped entirely when no criteria were written
+ * — there is no stale counter to repair, and the create path should not spend a
+ * request proving that.
+ *
+ * A failed read-back must NOT turn a create that succeeded into an error: the
+ * card and its criteria are on the record either way. In that one case the
+ * count is reconciled from the rows this function is holding, which is a fact it
+ * already has rather than a guess.
+ */
+export async function reconcileCriteriaCount(api, item, criteria) {
+  if (!item?.id || criteria.length === 0) return item;
+  try {
+    const fresh = await api('GET', `/api/v1/work-items/${encodeURIComponent(item.id)}`);
+    if (fresh?.data?.criteria) return fresh.data;
+  } catch {
+    // Fall through to the local reconciliation below.
+  }
+  return { ...item, criteria: { ...(item.criteria ?? {}), total: criteria.length } };
+}
+
 /**
  * The satisfaction sub-resource of one criterion, POSTed to tick and DELETEd to
  * un-tick.
@@ -164,10 +255,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
@@ -193,7 +389,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();
@@ -201,10 +399,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({
@@ -256,14 +451,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.'),
     },
@@ -273,6 +468,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.',
@@ -320,6 +876,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.`,
@@ -348,10 +918,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 });
     }
   );
@@ -369,7 +936,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.'),
     },
@@ -383,7 +950,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.',
       });
     }
   );
@@ -392,6 +959,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}`,
@@ -400,7 +1136,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) => {
@@ -457,7 +1196,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) => {
@@ -491,16 +1233,18 @@ Start here for "what should I work on". With includeUnassigned it also returns t
 
   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.
+    `Move a card to another column on the same board — and, outside QA, use claim:true to pick it up in the same action. The server does this in ONE transaction: it closes the card's open dwell, appends the transition to the history, records you as the handler of the pass the card is now on, and updates the card. Dropping a card into the column it is already in is a REORDER and deliberately does not restamp the stage timer.
 
 A card carries TWO people and they are not interchangeable. The OWNER (assignee) is whoever carries the card end to end — the engineer who builds it, and the person a QA bounce sends it back to. The HANDLER is whoever took the pass the card is on right now, which at a QA gate is the tester and nowhere else is usually the owner. claim:true always takes the pass; it takes ownership ONLY of a card nobody owns. So a QA pick-up on an engineer's card leaves the engineer owning it, which is what makes the two-gate flow work at all.
 
-This is both halves of the developer loop. Claiming is a parameter and not a second tool on purpose: picking a card up is one act, and a separate "assign" call is the one that gets skipped — leaving a card in an active column with no owner, which is the exact finding the board's unassigned glyph exists to shout about.${GOVERNED_NOTE}`,
+QA PASSES ARE THE EXCEPTION. An executable QA worker must hold the process-private lease and fencing capability before it can write in Staging QA1 or Staging QA2. Use claim_work_item_qa_pass (or claim_next_work_item_qa_pass) after the card is in QA; never use move_work_item(claim:true) to take a QA pass. This connector refuses that legacy shape locally instead of sending an unfenced write the API must reject.${GOVERNED_NOTE}`,
     {
       itemId: z.string().describe('Card id to move.'),
       toColumnId: z
         .string()
-        .describe('Target column id. Must be a column on the SAME board — get it from get_work_board.'),
+        .describe(
+          'Target column id. Must be a column on the SAME board — get it from get_work_board.'
+        ),
       position: z
         .number()
         .optional()
@@ -509,7 +1253,7 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
         .boolean()
         .optional()
         .describe(
-          'Pick this card up as part of this move: it records YOU as the handler of the pass the card lands on, and makes you the owner only if the card has no owner. "You" is resolved from the authenticated token — there is no way to claim on somebody else\'s behalf. Use it whenever you are picking work up. Taking a pass on a card SOMEBODY ELSE OWNS is allowed and normal (that is a QA pick-up) and leaves their ownership alone; taking a pass somebody else is already HOLDING is refused (see force). Re-claiming a pass you already hold is a no-op, not an error. The handler is written to the card\'s open dwell, so a same-column claim works too — that is how you take a pass on a card already sitting in your stage.'
+          'Pick this card up as part of a NON-QA move: it records YOU as the handler of the pass the card lands on, and makes you the owner only if the card has no owner. "You" is resolved from the authenticated token — there is no way to claim on somebody else\'s behalf. Staging QA1 and Staging QA2 use claim_work_item_qa_pass instead because every executable QA write must carry a process-private lease and fence. Taking a non-QA pass somebody else is already HOLDING is refused (see force). Re-claiming a non-QA pass you already hold is a no-op, not an error.'
         ),
       force: z
         .boolean()
@@ -529,6 +1273,57 @@ 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.'),
+      acknowledgeUnmetCriteria: z
+        .boolean()
+        .optional()
+        .describe(
+          'Record an explicit override for moving a card FORWARD out of Staging QA1 or Staging QA2 with acceptance criteria still unverified. The first such move is always refused (409) naming what is open; sending this is the acknowledgement itself, and the server stores the count on the transition row where a release review reads it later. IT IS A HUMAN ACT: the API refuses it to a program (403) before it reads the flag, so an agent setting it gets a refusal rather than a waiver. It is also NOT how a card gets parked — moving a card to Backlog or Deep backlog is a different kind of move and needs no override at all.'
+        ),
+      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) {
@@ -552,10 +1347,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',
@@ -566,12 +1358,24 @@ 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(
           (candidate) => candidate.columnId === args.toColumnId
         ).length;
+        if (args.claim === true && isQaStageName(target.name)) {
+          return ok({
+            ...preview,
+            blocked: true,
+            code: 'qa_pass_requires_worker_lease_claim',
+            message:
+              item.columnId === args.toColumnId
+                ? `Card ${args.itemId} is already in ${target.name}. Use claim_work_item_qa_pass to take this exact QA dwell atomically; move_work_item cannot create or retain the required private lease fence.`
+                : `Move card ${args.itemId} into ${target.name} without claim:true, then use claim_work_item_qa_pass to take the new QA dwell atomically. move_work_item cannot create or retain the required private lease fence.`,
+            wouldSend: false,
+          });
+        }
         return ok({
           ...preview,
           wouldMove: {
@@ -580,6 +1384,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,
@@ -590,6 +1395,46 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
         });
       }
 
+      // The generic move claim predates executable QA worker leases. It can
+      // name a handler, but it cannot return and retain the bearer/fence that
+      // every later agent write in a QA dwell must prove. Sending that legacy
+      // shape now produces an opaque 409 and leaves no claimed pass. Resolve
+      // the target before the mutation and direct the worker to the dedicated
+      // atomic lease endpoint instead. The API fence remains mandatory.
+      if (args.claim === true) {
+        const itemData = await api('GET', `/api/v1/work-items/${encodeURIComponent(args.itemId)}`);
+        const item = itemData?.data;
+        const boardData = item?.boardId
+          ? await api('GET', `/api/v1/work-boards/${encodeURIComponent(item.boardId)}`)
+          : null;
+        const target = boardData?.data?.columns?.find(
+          (column) => column.id === args.toColumnId
+        );
+        if (isQaStageName(target?.name)) {
+          return ok({
+            error: true,
+            code: 'qa_pass_requires_worker_lease_claim',
+            message:
+              item?.columnId === args.toColumnId
+                ? `Card ${args.itemId} is already in ${target.name}. Use claim_work_item_qa_pass to take this exact QA dwell atomically; move_work_item cannot create or retain the required private lease fence.`
+                : `Move card ${args.itemId} into ${target.name} without claim:true, then use claim_work_item_qa_pass to take the new QA dwell atomically. move_work_item cannot create or retain the required private lease fence.`,
+          });
+        }
+      }
+
+      // 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,
@@ -600,13 +1445,28 @@ 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,
+          // The API's documented escape hatch, which this connector used to
+          // drop on the floor: the field was never in the body, so a person
+          // driving the board through MCP could be refused a QA exit and had
+          // no way to record the override the refusal told them to send.
+          acknowledgeUnmetCriteria:
+            args.acknowledgeUnmetCriteria === 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
@@ -618,6 +1478,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}`,
@@ -746,9 +1717,9 @@ 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.
+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. Author the proof route at the same time: \`verificationRoute\` is REQUIRED on every criterion, because an omitted route silently became \`product\` and that is what a browser recording is then demanded for. Use \`engineering\`/\`both\` with a plain-language \`engineeringReason\` when no meaningful product-person retest exists. 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.
 
@@ -769,6 +1740,24 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
             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.'),
+            verificationRoute: z
+              .enum(['product', 'engineering', 'both'])
+              .describe(
+                'REQUIRED. How this criterion gets proved. `product` needs a ' +
+                'signed-in browser recording; `engineering` needs executed code/' +
+                'test/runtime proof; `both` needs BOTH and is the STRICTEST of ' +
+                'the three, not a compromise. Choose from what the thenText ' +
+                'says: can a browser DISPLAY the result? Then product. Is the ' +
+                'result an ECS task definition, a migration receipt, a CI leg, ' +
+                'an HTTP status contract, a log record, a vendor invoice or a ' +
+                'test suite? Then engineering.'
+              ),
+            engineeringReason: z
+              .string()
+              .optional()
+              .describe(
+                'Required for engineering or both: why no meaningful product-person retest exists.'
+              ),
           })
         )
         .optional()
@@ -780,9 +1769,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()
@@ -858,22 +1850,46 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
         );
         criteria.push(result?.data);
       }
-      return ok({ created: true, item, criteria });
+      return ok({
+        created: true,
+        item: await reconcileCriteriaCount(api, item, criteria),
+        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}`,
+    `Add one executable acceptance criterion to a card. This is grooming, not a comment: write where the check runs, the action, the observable result, and its proof route. verificationRoute is REQUIRED -- an omitted route silently became product, which then demands a browser recording for a criterion about a CI job. engineering and both require a plain-language engineeringReason. The server stores the criterion and its initial route audit receipt atomically.${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.'),
+      verificationRoute: z
+        .enum(['product', 'engineering', 'both'])
+        .describe(
+          'REQUIRED. How this criterion gets proved. `product` needs a signed-in ' +
+          'browser recording; `engineering` needs executed code/test/runtime ' +
+          'proof; `both` needs BOTH and is the STRICTEST of the three, not a ' +
+          'compromise. Choose from what the thenText says: can a browser ' +
+          'DISPLAY the result? Then product. Is the result an ECS task ' +
+          'definition, a migration receipt, a CI leg, an HTTP status contract, ' +
+          'a log record, a vendor invoice or a test suite? Then engineering.'
+        ),
+      engineeringReason: z
+        .string()
+        .optional()
+        .describe(
+          'Required for engineering or both: why no meaningful product-person retest exists.'
+        ),
       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) => {
@@ -889,6 +1905,8 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
         givenText: args.givenText,
         whenText: args.whenText,
         thenText: args.thenText,
+        verificationRoute: args.verificationRoute,
+        engineeringReason: args.engineeringReason,
       };
       if (preview?.dryRun) return ok({ ...preview, wouldAdd: { itemId: args.itemId, criterion } });
       const data = await api('POST', path, {
@@ -901,23 +1919,29 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
 
   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.
+    `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:
 
-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 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.
 
-  • \`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.
+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.
 
-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.
+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.
 
-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}`,
+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`.'),
+        .describe(
+          'Criterion id from list_work_item_acceptance_criteria — the `id`, not the `ordinal`.'
+        ),
       note: z
         .string()
         .optional()
@@ -965,7 +1989,7 @@ FIRST TICK WINS. The server records the ticker, the column and the note only whe
           // 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`.',
+            '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.',
         });
       }
 
@@ -976,7 +2000,7 @@ FIRST TICK WINS. The server records the ticker, the column and the note only whe
         // 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),
+        headers: mutationHeadersForItem(args, args.itemId),
       });
       const criterion = data?.data;
       return ok({
@@ -989,7 +2013,7 @@ FIRST TICK WINS. The server records the ticker, the column and the note only whe
         ...(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.',
+                '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.',
             }
           : {}),
       });
@@ -1009,7 +2033,9 @@ Anyone who can see the card may un-tick, including somebody undoing another pers
       itemId: z.string().describe('Card id.'),
       criterionId: z
         .string()
-        .describe('Criterion id from list_work_item_acceptance_criteria — the `id`, not the `ordinal`.'),
+        .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
@@ -1046,12 +2072,78 @@ Anyone who can see the card may un-tick, including somebody undoing another pers
         });
       }
 
-      const data = await api('DELETE', path, { headers: buildMutationHeaders(args) });
+      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.
@@ -1071,7 +2163,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()
@@ -1115,7 +2209,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(
@@ -1126,7 +2222,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()) {
@@ -1176,20 +2274,33 @@ 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',