@adrata/adrata-mcp 1.0.19 → 1.0.40

package/tools/work-board-tools.js

@@ -1,3 +1,4 @@
+import { registerWorkItemFieldChanges } from './work-hub/field-changes.js';
 import { auditWorkHubBoards, deliveryContradictions } from './work-hub/audit.js';
 import { describeCriteriaQuality, inspectCriteria } from './work-hub/criteria-quality.js';
 import { createHash } from 'node:crypto';
@@ -184,6 +185,88 @@ 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.';
 }
 
+/**
+ * Why a card with no product will not reach a QA lane, or `undefined` if it has
+ * one.
+ *
+ * `product` reads like an optional label and is not one. Every QA drain claims
+ * for ONE exact product, and the dispatcher selects on `i.product = $4` — SQL
+ * equality against NULL is not true, so an unclassified card is not ranked last
+ * or shown late, it is absent from every product queue at once while each of
+ * them reports itself empty. Measured 2026-09-08 on the Adrata board: 3 of 7
+ * cards in Staging QA2 carried no product, a product-scoped census returned 0
+ * workable, and those three were the only workable cards there.
+ *
+ * Advisory rather than a refusal, on the same argument `describeMissingBody`
+ * makes: a refused capture is how work stops reaching the board at all. The
+ * preview is where the author is already deciding, and this is the cheapest
+ * moment the omission is ever visible.
+ */
+/**
+ * The population, the exclusions, and which exclusions are themselves suspect.
+ *
+ * Returned whether or not a card was claimed. Shaped as counts plus the cards
+ * behind them, because a total is the last thing to trust and a reader who
+ * doubts the summary needs the rows.
+ */
+export function describeEmptyQueue(census) {
+  const finished = census?.skippedFinished ?? [];
+  const unrouted = census?.unroutedProduct ?? [];
+  return {
+    considered: census?.considered ?? 0,
+    truncated: census?.truncated === true,
+    skippedFinishedCount: finished.length,
+    skippedFinished: finished,
+    unroutedProductCount: unrouted.length,
+    unroutedProduct: unrouted,
+  };
+}
+
+/**
+ * What a lane should DO about an empty answer.
+ *
+ * Ordered by what changes the lane's next action, most actionable first. The
+ * unrouted clause comes before the flat "nothing remains" sentence on purpose:
+ * a gate holding unclassified cards is NOT empty, and saying it is would be the
+ * same false all-clear in new words.
+ */
+export function emptyQueueNote(product, qaGate, skippedBlocked, census) {
+  const parts = [];
+  const finished = census?.skippedFinished?.length ?? 0;
+  const unrouted = census?.unroutedProduct?.length ?? 0;
+  const considered = census?.considered ?? 0;
+
+  if (skippedBlocked?.length) {
+    parts.push(
+      `${skippedBlocked.length} card(s) in this gate are blocked by another card. Do not re-claim — read the blockers in skippedBlocked.`
+    );
+  }
+  if (finished) {
+    parts.push(
+      `${finished} card(s) were skipped because every acceptance criterion is already verified in this dwell. They are DONE, not pending — do not re-run a pass on them; they are listed in census.skippedFinished for whoever advances them.`
+    );
+  }
+  if (unrouted) {
+    parts.push(
+      `${unrouted} card(s) stand in ${qaGate} with NO product set. They are invisible to every product-scoped lane at once, including this one — this gate is unrouted, not empty. Set a product on them (they are listed in census.unroutedProduct) rather than concluding there is no work here.`
+    );
+  }
+  if (census?.truncated) {
+    parts.push(
+      'The candidate window was full, so the ranking saw only its first page; this census describes that page, not the whole gate.'
+    );
+  }
+  if (!parts.length) {
+    return `No eligible unclaimed ${product} ${qaGate} pass remains on any visible board: ${considered} candidate(s) were considered and none was excluded. Pick another lane.`;
+  }
+  return `No workable ${product} ${qaGate} pass was handed out. ${considered} candidate(s) considered. ${parts.join(' ')}`;
+}
+
+export function describeMissingProduct(product) {
+  if (String(product ?? '').trim()) return undefined;
+  return 'This card would arrive with no `product`. QA lanes drain ONE exact product at a time and select on an exact match, so a card without one is invisible to every lane at once rather than merely deprioritised — and each of those queues reports itself empty. Set `product` unless you intend this card to be worked by hand.';
+}
+
 /**
  * Make the created card's own criteria counter agree with the criteria returned
  * beside it.
@@ -267,6 +350,7 @@ export function registerWorkBoardTools(
     uploadQaEvidenceFile = uploadLocalQaEvidenceFile,
   }
 ) {
+  registerWorkItemFieldChanges(server, { z, api, ok });
   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.
@@ -274,7 +358,7 @@ export function registerWorkBoardTools(
   // public id and the handler adds the three private headers at the last hop.
   const workerLeaseCapabilities = new Map();
 
-  function rememberWorkerLease(itemId, grant, claimIdempotencyKey) {
+  function rememberWorkerLease(itemId, grant, claimIdempotencyKey, workerLabel) {
     if (!grant?.leaseId || !grant?.leaseToken || !Number.isInteger(grant?.fencingToken)) {
       throw new Error('The API returned an incomplete worker-lease grant; no capability was stored.');
     }
@@ -283,18 +367,32 @@ export function registerWorkBoardTools(
       leaseToken: grant.leaseToken,
       fencingToken: grant.fencingToken,
       claimIdempotencyKey,
+      workerLabel,
     });
     const { leaseToken: _secret, fencingToken: _fence, qaRequirements, currentCriteria, ...lease } =
       grant;
     return { lease, qaRequirements, currentCriteria };
   }
 
-  function conflictingHeldCard(itemId, claimIdempotencyKey) {
+  // ONE PASS PER WORKER, NOT PER PROCESS. A fleet runs many QA lanes through a
+  // single connector, so scanning every capability in the map made lane A's
+  // card refuse lane B — naming a card lane B had never seen and telling it to
+  // "transition or release" a peer's pass. That serialises the parallel QA
+  // drain the atomic claim exists to make safe, and it does so silently: the
+  // refusal reads exactly like ordinary contention for one card.
+  //
+  // The worker is what the guard was always about, and `workerLabel` is how a
+  // worker names itself. A capability stored without one cannot be attributed,
+  // so it still conflicts — an unattributable hold fails toward refusing, which
+  // costs a retry, rather than toward a double hold, which costs a lost lease.
+  function conflictingHeldCard(itemId, claimIdempotencyKey, workerLabel) {
     for (const [heldItemId, capability] of workerLeaseCapabilities) {
       const sameCard = itemId != null && heldItemId === itemId;
       const sameClaim =
         claimIdempotencyKey != null && capability.claimIdempotencyKey === claimIdempotencyKey;
-      if (!sameCard && !sameClaim) return heldItemId;
+      const sameWorker =
+        capability.workerLabel == null || capability.workerLabel === workerLabel;
+      if (!sameCard && !sameClaim && sameWorker) return heldItemId;
     }
     return null;
   }
@@ -511,7 +609,7 @@ Start here for "what should I work on". With includeUnassigned it also returns t
       idempotencyKey: z.string().optional(),
     },
     async (args) => {
-      const heldItemId = conflictingHeldCard(args.itemId, args.idempotencyKey);
+      const heldItemId = conflictingHeldCard(args.itemId, args.idempotencyKey, args.workerLabel);
       if (heldItemId) {
         return ok({
           error: true,
@@ -547,7 +645,7 @@ Start here for "what should I work on". With includeUnassigned it also returns t
         body,
         headers: buildMutationHeaders(args),
       });
-      const visible = rememberWorkerLease(args.itemId, data?.data, args.idempotencyKey);
+      const visible = rememberWorkerLease(args.itemId, data?.data, args.idempotencyKey, args.workerLabel);
       return ok({ claimed: true, ...visible });
     }
   );
@@ -567,7 +665,7 @@ Start here for "what should I work on". With includeUnassigned it also returns t
       idempotencyKey: z.string().optional(),
     },
     async (args) => {
-      const heldItemId = conflictingHeldCard(null, args.idempotencyKey);
+      const heldItemId = conflictingHeldCard(null, args.idempotencyKey, args.workerLabel);
       if (heldItemId) {
         return ok({
           error: true,
@@ -611,24 +709,42 @@ Start here for "what should I work on". With includeUnassigned it also returns t
       const outcome = data?.data ?? {};
       const selected = outcome.claimed;
       const skippedBlocked = outcome.skippedBlocked ?? [];
+      const census = outcome.census ?? {};
       if (!selected) {
-        // The empty-handed case is two different situations and a lane acts on
-        // them differently: an empty gate means pick another lane, while a
-        // fully-blocked one means go and look at the blockers.
+        // The empty-handed case is FOUR different situations and a lane acts on
+        // them differently: an empty gate means pick another lane; a
+        // fully-blocked one means go and look at the blockers; a gate whose
+        // work is all verified means the drain is finished; and cards with no
+        // product mean the queue is not empty at all, it is unrouted.
+        //
+        // So this answer shows its working rather than asserting a conclusion.
+        // A signal that can tell a worker to STOP has to be contradictable —
+        // this factory has already believed "there is genuinely nothing to pick
+        // up" once, from a count that could not be wrong out loud, while 211 of
+        // 212 claims sat on cards that had left the column.
         return ok({
           claimed: false,
           qaGate: args.qaGate,
           product: args.product,
           skippedBlocked,
-          note: skippedBlocked.length
-            ? `No workable ${args.product} ${args.qaGate} pass remains: ${skippedBlocked.length} card(s) in this gate are blocked by another card. Do not re-claim — look at the blockers listed in skippedBlocked.`
-            : `No eligible unclaimed ${args.product} ${args.qaGate} pass remains on any visible board.`,
+          census: describeEmptyQueue(census),
+          note: emptyQueueNote(args.product, args.qaGate, skippedBlocked, census),
         });
       }
-      const visible = rememberWorkerLease(selected.workItemId, selected.grant, args.idempotencyKey);
+      const visible = rememberWorkerLease(
+        selected.workItemId,
+        selected.grant,
+        args.idempotencyKey,
+        args.workerLabel
+      );
       return ok({
         claimed: true,
         skippedBlocked,
+        // Reported on the winning path as well. Three finished cards and two
+        // unrouted ones in this gate are a board finding whoever is reading,
+        // and a lane that only sees them on the empty pass learns about them
+        // last -- by which point it has no reason to look.
+        census: describeEmptyQueue(census),
         workItemId: selected.workItemId,
         boardId: selected.boardId,
         boardName: selected.boardName,
@@ -727,10 +843,11 @@ Start here for "what should I work on". With includeUnassigned it also returns t
 
   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}`,
+    `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 for the next worker to diagnose, repair, deploy and independently retest. Ordinary failure and dependency handoffs remain claimable. Set blocksClaim:true only for an explicit prerequisite no agent can satisfy, such as owner consent or a vendor credential. Both paths release the lease only after the failure is durably recorded; a claimable handoff is not a QA pass. 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']),
+      blocksClaim: z.boolean().optional().default(false).describe('Stop pickup only for an explicit prerequisite no agent can satisfy. Ordinary failed work remains claimable for repair and retest.'),
       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),
@@ -748,7 +865,7 @@ Start here for "what should I work on". With includeUnassigned it also returns t
       const preview = validateApiBridgeRequest({
         method: 'POST',
         path: `/api/v1/work-items/${encodeURIComponent(args.itemId)}/comments`,
-        body: { disposition: args.disposition, criterionId: args.criterionId, details: args.details },
+        body: { disposition: args.disposition, criterionId: args.criterionId, details: args.details, blocksClaim: args.blocksClaim === true },
         dryRun: args.dryRun, approved: args.approved, reason: args.reason,
         idempotencyKey: args.idempotencyKey, grantedScope: getGrantedScope(),
       });
@@ -760,10 +877,11 @@ Start here for "what should I work on". With includeUnassigned it also returns t
             disposition: args.disposition,
             criterionId: args.criterionId ?? null,
             details: args.details,
+            blocksClaim: args.blocksClaim === true,
           },
-          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.',
+          note: args.blocksClaim === true
+            ? 'The card will be flagged in place and withheld from pickup until the explicit prerequisite is resolved.'
+            : 'The card will stay in place, retain its failure reason, and remain claimable for repair and retest after this pass is released.',
         });
       }
       const leaseHeaders = workerLeaseHeaders(args.itemId);
@@ -776,11 +894,11 @@ Start here for "what should I work on". With includeUnassigned it also returns t
       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 },
+      // Preserve the contradiction before un-ticking or releasing. Ordinary
+      // failures remain claimable so another worker can repair them; only an
+      // explicitly requested hold blocks pickup. Child writes are idempotent.
+      const recordedFlag = await api('POST', `/api/v1/work-items/${encodeURIComponent(args.itemId)}/flag`, {
+        body: { flagged: true, reason: flagReason, blocksClaim: args.blocksClaim === true, idempotencyKey: recordKey },
         headers: mutationHeadersForItem({ ...args, idempotencyKey: recordKey }, args.itemId),
       });
       if (args.disposition === 'failed_criterion') {
@@ -798,8 +916,10 @@ Start here for "what should I work on". With includeUnassigned it also returns t
         recorded: true,
         disposition: args.disposition,
         requeued: false,
-        blocked: true,
+        blocked: args.blocksClaim === true,
+        claimable: args.blocksClaim !== true,
         waitingForFix: args.disposition === 'failed_criterion',
+        flagGeneration: recordedFlag?.data?.recordedFlagGeneration ?? null,
         releaseKind,
         ...release,
       });
@@ -808,9 +928,10 @@ Start here for "what should I work on". With includeUnassigned it also returns t
 
   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}`,
+    `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 or certify the card; it clears the resolved hold or failure handoff before a fresh independent 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.'),
+      repairedFlagGeneration: z.string().min(1).describe('The flag.generation captured for the failure actually repaired. Never substitute a newer flag generation without resolving that failure.'),
       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.'),
@@ -830,6 +951,9 @@ Start here for "what should I work on". With includeUnassigned it also returns t
       if (!args.details?.trim()) {
         return ok({ error: true, message: 'details must name the ancestry check and deployment/fix reference.' });
       }
+      if (!args.repairedFlagGeneration?.trim()) {
+        return ok({ error: true, message: 'repairedFlagGeneration is required. Read and resolve the current failure before retrying; never substitute a newer generation for an older repair.' });
+      }
       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({
@@ -837,13 +961,13 @@ Start here for "what should I work on". With includeUnassigned it also returns t
         reason: args.reason, idempotencyKey: args.idempotencyKey, grantedScope: getGrantedScope(),
       });
       if (preview.dryRun) {
-        return ok({ ...preview, wouldRequeue: { itemId: args.itemId, failedBuildSha: args.failedBuildSha, deployedBuildSha: args.deployedBuildSha } });
+        return ok({ ...preview, wouldRequeue: { itemId: args.itemId, failedBuildSha: args.failedBuildSha, deployedBuildSha: args.deployedBuildSha, repairedFlagGeneration: args.repairedFlagGeneration } });
       }
       const data = await api('POST', path, {
-        body: { flagged: false, reason: clearReason, idempotencyKey: args.idempotencyKey },
+        body: { flagged: false, reason: clearReason, expectedFlagGeneration: args.repairedFlagGeneration, idempotencyKey: args.idempotencyKey },
         headers: buildMutationHeaders(args),
       });
-      return ok({ requeued: true, item: data?.data, failedBuildSha: args.failedBuildSha, deployedBuildSha: args.deployedBuildSha });
+      return ok({ requeued: true, item: data?.data, failedBuildSha: args.failedBuildSha, deployedBuildSha: args.deployedBuildSha, repairedFlagGeneration: args.repairedFlagGeneration });
     }
   );
 
@@ -1253,6 +1377,41 @@ Start here for "what should I work on". With includeUnassigned it also returns t
     }
   );
 
+  server.tool(
+    'preview_work_item_acceptance_reaffirmation',
+    'Read the exact current criterion definitions and preserved independent QA evidence for a legacy human-accepted Ready to Ship card. Returns a content digest for a separate explicit owner decision. Original acceptance scope remains unknown; this never repairs missing QA.',
+    { itemId: z.string() },
+    async (args) => {
+      const data = await api('GET', `/api/v1/work-items/${encodeURIComponent(args.itemId)}/acceptance-reaffirmation`);
+      return ok(data?.data);
+    }
+  );
+
+  server.tool(
+    'reaffirm_work_item_current_acceptance',
+    `Record a separate owner approval of the exact CURRENT scope and existing QA evidence from preview_work_item_acceptance_reaffirmation. Only the authenticated delegated OAuth owner can do this. The original legacy acceptance receipt stays unchanged and its original scope stays unknown. This neither verifies criteria nor fills missing QA receipts. Use only on the owner's explicit instruction after reviewing the preview and limitation.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string(), historyId: z.string(), originalReceiptId: z.string(),
+      contentSha256: z.string().regex(/^[0-9a-f]{64}$/),
+      acknowledgeOriginalScopeUnknown: z.literal(true),
+      receivingBuildSha: z.string().regex(/^[0-9a-f]{40}$/),
+      expiresAt: z.number().int(),
+      dryRun: z.boolean().optional(), approved: z.boolean().optional(),
+      reason: z.string().optional(), idempotencyKey: z.string().optional(),
+    },
+    async (args) => {
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/acceptance-reaffirmation`;
+      const preview = validateApiBridgeRequest({ method: 'POST', path, dryRun: args.dryRun,
+        approved: args.approved, reason: args.reason, idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope() });
+      const { dryRun: _dryRun, ...body } = args;
+      if (preview?.dryRun) return ok({ ...preview, wouldReaffirm: body,
+        limitation: 'Original legacy acceptance scope remains unknown. This is a separate current acceptance.' });
+      const data = await api('POST', path, { body, headers: buildMutationHeaders(args) });
+      return ok({ reaffirmed: true, receipt: data?.data });
+    }
+  );
+
   server.tool(
     'move_work_item',
     `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.
@@ -1285,6 +1444,20 @@ QA PASSES ARE THE EXCEPTION. An executable QA worker must hold the process-priva
         ),
       dryRun: z.boolean().optional().describe('Defaults to true. Set false for a live move.'),
       approved: z.boolean().optional().describe('Required true for a live move.'),
+      presenceAttestation: z.string().optional().describe('Single-use human-minted presence token. This remains separate from owner delegation.'),
+      ownerApproval: z.object({
+        approved: z.literal(true),
+        itemId: z.string(),
+        toColumnId: z.string(),
+        idempotencyKey: z.string(),
+        acceptanceReceiptId: z.string(),
+        reaffirmationReceiptId: z.string().optional().describe('Separate current acceptance receipt for legacy original scope; never a backfilled original receipt.'),
+        reviewedBuildSha: z.string().regex(/^[0-9a-f]{40}$/),
+        receivingBuildSha: z.string().regex(/^[0-9a-f]{40}$/),
+        expiresAt: z.number().int(),
+      }).strict().optional().describe(
+        'Explicit owner-delegated Production request. Use only after the owner approves this exact card, destination, accepted QA2 closing receipt and reviewed delivery build. Expires within five minutes. Server requires the authenticated owner’s delegated OAuth credential and preserves species agent. This is delegated authority, not cryptographic proof of human presence. receivingBuildSha is the live API build; reviewedBuildSha is the separately reviewed component build and must match receipt.commitSha.'
+      ),
       reason: z
         .string()
         .optional()
@@ -1407,6 +1580,8 @@ QA PASSES ARE THE EXCEPTION. An executable QA worker must hold the process-priva
             claim: args.claim === true,
             force: args.force === true,
             receipt: args.receipt !== undefined,
+            ownerApproval: args.ownerApproval,
+            presenceAttestation: args.presenceAttestation !== undefined,
           },
           wip: projectColumnWip({
             limit: target.wipLimit,
@@ -1474,6 +1649,8 @@ QA PASSES ARE THE EXCEPTION. An executable QA worker must hold the process-priva
           acknowledgeUnmetCriteria:
             args.acknowledgeUnmetCriteria === true ? true : undefined,
           receipt: args.receipt,
+          ownerApproval: args.ownerApproval,
+          presenceAttestation: args.presenceAttestation,
         },
         headers: mutationHeadersForItem(args, args.itemId),
       });
@@ -1484,11 +1661,25 @@ QA PASSES ARE THE EXCEPTION. An executable QA worker must hold the process-priva
       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
+        // Read back from the SERVER, never `args.receipt !== undefined`. That
+        // echo reported the request rather than the answer, and the two
+        // disagree in all three directions: `receipt: {}` points at nothing and
+        // the server grades it `server_recorded`; offering no receipt at all
+        // still writes a `server_recorded` row, so `false` was wrong; and a
+        // REORDER writes no receipt whatsoever, because the API guards the
+        // write with `if changed_column` — yet a receipt passed alongside one
+        // still reported `true`.
+        //
+        // Still a BOOLEAN and still never the receipt's contents: repeating a
         // session pointer back into a conversation transcript is the leak this
         // whole field is shaped to avoid.
-        receiptRecorded: args.receipt !== undefined,
+        receiptRecorded: data?.receiptEvidenceSource != null,
+        // Whether that receipt points at anything, which is a different
+        // question from whether one exists — and it is the one the gaps query
+        // asks. `attested` only when the caller's references actually carried a
+        // value; `server_recorded` when the server wrote the row on its own
+        // observation; null when no receipt was written for this call.
+        receiptEvidenceSource: data?.receiptEvidenceSource ?? null,
         // 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
@@ -1605,7 +1796,12 @@ QA PASSES ARE THE EXCEPTION. An executable QA worker must hold the process-priva
       return ok({
         transferred: true,
         identityPreserved: true,
-        receiptRecorded: args.receipt !== undefined,
+        // The server's verdict, not an echo of the request. See the move tool
+        // above for why those differ. A transfer always changes board AND
+        // column, so unlike a move it always writes a receipt — but whether
+        // that receipt points at anything is still the server's call.
+        receiptRecorded: data?.receiptEvidenceSource != null,
+        receiptEvidenceSource: data?.receiptEvidenceSource ?? null,
         item: data?.data,
       });
     }
@@ -1941,6 +2137,9 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
           // capture is how work stops reaching the board at all.
           note: describeMissingBody(args.body),
           readinessNote: describeMissingAcceptanceCriteria(args.acceptanceCriteria),
+          // A missing product is not a missing label: it is the difference
+          // between a card a QA lane can be handed and one no lane can see.
+          routingNote: describeMissingProduct(args.product),
           // Advisory, and only ever present when it has something to say. The
           // preview is where an author is already deciding whether to approve,
           // and a criterion that cannot fail is cheapest to fix before the card
@@ -2564,25 +2763,34 @@ TO @-MENTION SOMEBODY, write the token \`<@userId>\` in the body — the id come
 
   server.tool(
     'flag_work_item',
-    `Flag a card as having a problem WITH THE CARD — unclear scope, no repro, a blocked dependency, a question waiting on an answer — or clear a flag once it is resolved. A flagged card is drawn differently on the board so nobody picks it up by mistake.
+    `Flag unresolved work for the next repair and retest, or clear a flag once its reason is resolved. Ordinary failures remain visible and claimable.
+
+A FLAG IS NOT A TAG. The tag says how urgent the work is; a flag records an unresolved problem. If a card is merely important, use set_work_item_tag.
 
-A FLAG IS NOT A TAG. The tag says how urgent the WORK is; a flag says the CARD is not fit to be worked. If a card is merely important, use set_work_item_tag. If you cannot start because something is missing, flag it.
+THE REASON IS REQUIRED IN BOTH DIRECTIONS, and it is not the audit reason — it is the text read on the card. Raising says what failed, what you tried, and what remains to check; clearing says what resolved it. Agents may clear a resolved flag without a human handoff. Both directions append a comment, preserving the original failure and its resolution.
 
-THE REASON IS REQUIRED IN BOTH DIRECTIONS, and it is not the audit reason — it is the text a human reads on the card. Raising says what is wrong; clearing says what resolved it. Anyone may clear a flag, which only works because both directions are recorded as a comment on the card.
+A FLAG HANDS THE CARD ON; IT DOES NOT HIDE IT. A failed test or an unsuccessful first repair is not an external hold. Leave it claimable so the next agent can investigate, repair, and independently retest. Clearing a flag does not certify acceptance criteria or replace either QA gate.
 
-This is what the ship-the-card skill means by "an unworkable card is a triage problem, not a coding problem": flag it, say the one question that would unblock it, and stop.${GOVERNED_NOTE}`,
+PASS blocksClaim:true ONLY FOR AN EXPLICIT PREREQUISITE AGENTS CANNOT SATISFY — owner authorization, vendor consent, or a product decision. The hold remains until that prerequisite is satisfied and the flag is cleared with a resolution reason. Do not turn an ordinary test failure into an owner decision.${GOVERNED_NOTE}`,
     {
       itemId: z.string().describe('Card id.'),
       flagged: z
         .boolean()
         .describe(
-          'true raises the flag; false clears it. Raising an already-flagged card replaces the reason.'
+          'true raises the flag; false clears it. Raising an already-flagged card replaces the reason, and that is an EDIT rather than a second flag: the card carries a lifetime count of how many times it has been flagged (drawn on the board as a stack of one, two, three, or three-plus pennants), and only an unflagged card becoming flagged increments it. So narrowing a live flag costs nothing, and a card showing four pennants really has been through the loop four times.'
         ),
       reason: z
         .string()
         .describe(
           'REQUIRED. Raising: what is wrong with the card. Clearing: what resolved it. Shown on the card and appended to its comment thread — write it for the person who will read it, not for a log.'
         ),
+      expectedFlagGeneration: z.string().optional().describe('Required when clearing: flag.generation captured for the failure actually resolved. A stale generation is refused; inspect and resolve the newer flag before another clear.'),
+      blocksClaim: z
+        .boolean()
+        .optional()
+        .describe(
+          'Whether this flag prevents claims. OMITTED MEANS FALSE: ordinary failed work remains claimable for repair and independent retest. Pass true only for an explicit prerequisite agents cannot satisfy, such as owner authorization or vendor consent. Clear after that prerequisite is satisfied, recording the resolution. Ignored when clearing.'
+        ),
       dryRun: z.boolean().optional().describe('Defaults to true. Set false to change the flag.'),
       approved: z.boolean().optional().describe('Required true for a live change.'),
       idempotencyKey: z
@@ -2597,10 +2805,13 @@ This is what the ship-the-card skill means by "an unworkable card is a triage pr
         return ok({
           error: true,
           message:
-            'reason is required to flag or to clear. A flag with nothing written on it stops work without saying how to restart it, and a flag anyone can silently clear is a flag nobody trusts.',
+            'reason is required to flag or to clear. Record the unresolved problem when raising and what resolved it when clearing; both become card history.',
         });
       }
 
+      if (!args.flagged && !args.expectedFlagGeneration?.trim()) {
+        return ok({ error: true, message: 'Clearing requires expectedFlagGeneration from the failure actually resolved. Read and resolve the current flag before retrying.' });
+      }
       const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/flag`;
       const preview = validateApiBridgeRequest({
         method: 'POST',
@@ -2617,25 +2828,220 @@ This is what the ship-the-card skill means by "an unworkable card is a triage pr
       if (preview?.dryRun) {
         return ok({
           ...preview,
-          wouldFlag: { itemId: args.itemId, flagged: args.flagged, reason: args.reason },
+          wouldFlag: {
+            itemId: args.itemId,
+            flagged: args.flagged,
+            expectedFlagGeneration: args.expectedFlagGeneration,
+            reason: args.reason,
+            // Shown in the rehearsal because it decides whether the card
+            // disappears from every queue, which is the consequence a reader
+            // most needs to see before approving the write.
+            blocksClaim: args.flagged ? (args.blocksClaim ?? false) : true,
+          },
         });
       }
 
       const data = await api('POST', path, {
         body: {
           flagged: args.flagged,
+          expectedFlagGeneration: args.expectedFlagGeneration,
           reason: args.reason,
           idempotencyKey: args.idempotencyKey,
+          // Match the preview explicitly: ordinary failures remain claimable.
+          // Clearing ignores this field on the server.
+          blocksClaim: args.flagged ? (args.blocksClaim ?? false) : true,
         },
         headers: buildMutationHeaders({ ...args, reason: args.reason }),
       });
       return ok({ flagged: args.flagged, item: data?.data });
     }
   );
+
+  // ── Retiring a card ──────────────────────────────────────────────────────
+  //
+  // Three tools rather than one with a `kind` switch, and the split is
+  // deliberate. `delete_` is matched by tool-annotations' DESTRUCTIVE_PATTERN,
+  // so naming the destructive branch as its own tool is what gets a host to
+  // confirmation-gate it. A single `archive_work_item({ kind: 'deleted' })`
+  // would hide the destructive path behind a name classified as safe.
+
+  const RETIRE_NOTE = `WHAT THIS IS NOT. Do not use move_work_item to Backlog or Deep backlog to retire a card. Those are PARKING: work still intended, later — it stays in every count, which is correct for parked work and wrong for work nobody will ever do. Retiring is the other thing, and it is the only one that takes the card out of the numbers.
+
+NOTHING IS DESTROYED. The card keeps its board, its column, its column history, its acceptance criteria and its QA evidence. It stays readable by get_work_item and it comes back with unarchive_work_item. The exclusion is a read filter, never a row removal — QA receipts bind to those column dwells and deleting them would leave every receipt on the card unexplainable.${GOVERNED_NOTE}`;
+
+  server.tool(
+    'archive_work_item',
+    `Retire a card: done with, wrong, obsolete, or superseded. It leaves every active count — the board's own size, the roll-up, the personal queue, velocity, capacity, the roadmap's card counts, the criterion standings — and stops being offered to a QA lane.
+
+This is the COMMON case and it is recoverable. Reach for it whenever a card should stop being counted; if you find yourself wanting to hide a card by moving it somewhere nobody looks, this is the tool you actually wanted.
+
+${RETIRE_NOTE}`,
+    {
+      itemId: z.string().describe('Card id.'),
+      reason: z
+        .string()
+        .describe(
+          'REQUIRED. Why this work will not be done. Shown on the card and appended to its comment thread — write it for the person who finds the card in six months and wonders what happened to it. "obsolete" is not an answer; "superseded by <card>, the API changed under it" is.'
+        ),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to retire the card.'),
+      approved: z.boolean().optional().describe('Required true for a live change.'),
+      idempotencyKey: z
+        .string()
+        .optional()
+        .describe(
+          'Required for a live change. Reuse the SAME key on retry — retiring also appends a comment.'
+        ),
+    },
+    async (args) => {
+      if (!args.reason || !args.reason.trim()) {
+        return ok({
+          error: true,
+          message:
+            'reason is required. A card that disappears from the board with nothing written on it is exactly what archiving exists to replace.',
+        });
+      }
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/archive`;
+      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,
+          wouldArchive: { itemId: args.itemId, kind: 'archived', reason: args.reason },
+        });
+      }
+      const data = await api('POST', path, {
+        body: { reason: args.reason, kind: 'archived', idempotencyKey: args.idempotencyKey },
+        headers: buildMutationHeaders({ ...args, reason: args.reason }),
+      });
+      return ok({ archived: true, kind: 'archived', item: data?.data });
+    }
+  );
+
+  server.tool(
+    'delete_work_item',
+    `Retire a card as DELETED rather than archived. Rare, and deliberate.
+
+PREFER archive_work_item. The two do the same thing to the numbers; the difference is what the record says about the decision, and "archived" is the honest word for almost every card. Use this only when the card should never have existed — a duplicate, a mis-filed capture, something created by an integration by mistake.
+
+IT IS STILL A SOFT DELETE. The row survives and unarchive_work_item brings it back. That is not a loophole: this board is the audit record behind a two-gate QA process, and a hard delete would cascade away the column history that every QA receipt binds to.
+
+YOU MUST ECHO THE CARD'S EXACT TITLE in confirmTitle. Read the card first with get_work_item; do not guess it from the id or from a list you are half sure of. The echo is the whole safeguard — it is what makes this something you cannot do by accident inside a loop.
+
+${RETIRE_NOTE}`,
+    {
+      itemId: z.string().describe('Card id.'),
+      confirmTitle: z
+        .string()
+        .describe(
+          "REQUIRED. The card's title, exactly as get_work_item returns it. A mismatch is refused and nothing is written."
+        ),
+      reason: z
+        .string()
+        .describe('REQUIRED. Why this card should never have existed.'),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to delete the card.'),
+      approved: z.boolean().optional().describe('Required true for a live change.'),
+      idempotencyKey: z.string().optional().describe('Required for a live change.'),
+    },
+    async (args) => {
+      if (!args.reason || !args.reason.trim()) {
+        return ok({ error: true, message: 'reason is required to delete a card.' });
+      }
+      if (!args.confirmTitle || !args.confirmTitle.trim()) {
+        return ok({
+          error: true,
+          message:
+            "confirmTitle is required and must match the card's exact title. Read the card with get_work_item first — the echo is the only thing standing between a deliberate delete and an accidental one.",
+        });
+      }
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/archive`;
+      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,
+          wouldDelete: {
+            itemId: args.itemId,
+            kind: 'deleted',
+            reason: args.reason,
+            confirmTitle: args.confirmTitle,
+          },
+        });
+      }
+      const data = await api('POST', path, {
+        body: {
+          reason: args.reason,
+          kind: 'deleted',
+          confirmTitle: args.confirmTitle,
+          idempotencyKey: args.idempotencyKey,
+        },
+        headers: buildMutationHeaders({ ...args, reason: args.reason }),
+      });
+      return ok({ archived: true, kind: 'deleted', item: data?.data });
+    }
+  );
+
+  server.tool(
+    'unarchive_work_item',
+    `Bring a retired card back into circulation, whichever verb retired it — archived or deleted. It rejoins every count exactly where it left, in the same column, with its whole history intact.
+
+As easy as retiring it was, on purpose: a retirement nobody could undo would make a mistaken one permanent, and that is the failure the confirmation on delete_work_item exists to prevent in the first place.
+
+THE REASON IS REQUIRED HERE TOO — what changed. Anyone can bring a card back, which only works if bringing it back leaves a record.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id. Find retired cards with the board archived-items read.'),
+      reason: z.string().describe('REQUIRED. What changed — why this work is wanted again.'),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to restore the card.'),
+      approved: z.boolean().optional().describe('Required true for a live change.'),
+      idempotencyKey: z.string().optional().describe('Required for a live change.'),
+    },
+    async (args) => {
+      if (!args.reason || !args.reason.trim()) {
+        return ok({
+          error: true,
+          message:
+            'reason is required to restore a card. Anyone can bring a card back, which only works if bringing it back leaves a record.',
+        });
+      }
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/unarchive`;
+      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, wouldUnarchive: { itemId: args.itemId, reason: args.reason } });
+      }
+      const data = await api('POST', path, {
+        body: { reason: args.reason, idempotencyKey: args.idempotencyKey },
+        headers: buildMutationHeaders({ ...args, reason: args.reason }),
+      });
+      return ok({ archived: false, item: data?.data });
+    }
+  );
 }
 
 /** Tool names registered here, for the tier map and the toolset manifest. */
 export const WORK_BOARD_TOOL_NAMES = [
+  'preview_work_item_acceptance_reaffirmation',
+  'reaffirm_work_item_current_acceptance',
   'list_my_work_items',
   'list_work_boards',
   'get_work_board',
@@ -2649,6 +3055,7 @@ export const WORK_BOARD_TOOL_NAMES = [
   'record_work_item_qa_failure_and_release',
   'requeue_work_item_qa_after_fix',
   'get_work_item_history',
+  'get_work_item_field_changes',
   'get_work_item_delivery_evidence',
   'audit_work_hub',
   'list_work_item_acceptance_criteria',
@@ -2674,6 +3081,9 @@ export const WORK_BOARD_TOOL_NAMES = [
   'get_work_item_comments',
   'comment_on_work_item',
   'flag_work_item',
+  'archive_work_item',
+  'delete_work_item',
+  'unarchive_work_item',
   'block_work_item',
   'unblock_work_item',
 ];