@adrata/adrata-mcp 1.0.8 → 1.0.30

package/tools/work-board-tools.js

@@ -1,4 +1,5 @@
 import { auditWorkHubBoards, deliveryContradictions } from './work-hub/audit.js';
+import { describeCriteriaQuality, inspectCriteria } from './work-hub/criteria-quality.js';
 import { createHash } from 'node:crypto';
 import { readFile, stat } from 'node:fs/promises';
 import { basename, resolve } from 'node:path';
@@ -273,7 +274,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.');
     }
@@ -282,18 +283,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;
   }
@@ -510,7 +525,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,
@@ -546,7 +561,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 });
     }
   );
@@ -566,7 +581,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,
@@ -624,7 +639,12 @@ Start here for "what should I work on". With includeUnassigned it also returns t
             : `No eligible unclaimed ${args.product} ${args.qaGate} pass remains on any visible board.`,
         });
       }
-      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,
@@ -881,7 +901,7 @@ Start here for "what should I work on". With includeUnassigned it also returns t
 
   server.tool(
     'list_work_item_acceptance_criteria',
-    'Read the ordered, executable definition of done for one card. Each criterion says where to check, any starting state, what action to perform, and the observable result. A zero-length list is a finding: nobody has stated how QA can decide the card is done.',
+    'Read the ordered, executable definition of done for one card. Each criterion says where to check, any starting state, what action to perform, and the observable result. A zero-length list is a finding: nobody has stated how QA can decide the card is done. `criteriaQuality` names criteria that cannot fail as written — an unfalsifiable result, a location that is not a place to stand, an unfinished clause. Correct those before executing them; a criterion turned green by reading it generously is worth less than an open one.',
     { itemId: z.string().describe('Card id.') },
     async (args) => {
       const data = await api(
@@ -889,7 +909,7 @@ Start here for "what should I work on". With includeUnassigned it also returns t
         `/api/v1/work-items/${encodeURIComponent(args.itemId)}/acceptance-criteria`
       );
       const criteria = data?.data ?? [];
-      return ok({ count: criteria.length, criteria });
+      return ok({ count: criteria.length, criteria, criteriaQuality: inspectCriteria(criteria) });
     }
   );
 
@@ -909,7 +929,7 @@ Start here for "what should I work on". With includeUnassigned it also returns t
 
   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.`,
+    `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, truncated reads, and boards that could not be read at all. It does not award a vanity score and it does not mutate anything. A clean result means every board it COULD read has the minimum workflow facts required to operate from it — read \`boards\` against \`boardsExpected\` before treating it as coverage. Deployment truth remains a separate exact-SHA fact available through get_work_item_delivery_evidence.`,
     {},
     async () => {
       const listed = await api('GET', '/api/v1/work-boards');
@@ -920,7 +940,11 @@ Start here for "what should I work on". With includeUnassigned it also returns t
           return detail?.data;
         })
       );
-      return ok(auditWorkHubBoards(boards.filter(Boolean)));
+      // `refs.length` travels with the payload so a board whose detail read came
+      // back empty is REPORTED as unread rather than silently dropped by the
+      // filter. Auditing one of four boards and saying "trustworthy" is the
+      // single-board coverage claim this repo already warns about.
+      return ok(auditWorkHubBoards(boards.filter(Boolean), { expectedBoards: refs.length }));
     }
   );
 
@@ -1479,11 +1503,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
@@ -1600,7 +1638,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,
       });
     }
@@ -1853,10 +1896,12 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
       acceptanceCriteria: z
         .array(
           z.object({
-            whereText: z.string().describe('Surface, environment, account, or role to check.'),
+            whereText: z.string().describe(
+        'Surface, environment, account, or role to check. A place the next reviewer can stand, not the whole product — "the app" tells them nothing.'
+      ),
             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.'),
+            thenText: z.string().describe('Observable result that must follow. Name a checkable value, count, state, or exact message. A criterion that cannot fail cannot establish completion.'),
             verificationRoute: z
               .enum(['product', 'engineering', 'both'])
               .describe(
@@ -1934,6 +1979,11 @@ 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),
+          // 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
+          // exists rather than after QA has tried to execute it.
+          criteriaQualityNote: describeCriteriaQuality(args.acceptanceCriteria),
         });
       }
 
@@ -1980,10 +2030,12 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
     `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.'),
+      whereText: z.string().describe(
+        'Surface, environment, account, or role to check. A place the next reviewer can stand, not the whole product — "the app" tells them nothing.'
+      ),
       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.'),
+      thenText: z.string().describe('Observable result that must follow. Name a checkable value, count, state, or exact message. A criterion that cannot fail cannot establish completion.'),
       verificationRoute: z
         .enum(['product', 'engineering', 'both'])
         .describe(
@@ -2025,7 +2077,12 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
         verificationRoute: args.verificationRoute,
         engineeringReason: args.engineeringReason,
       };
-      if (preview?.dryRun) return ok({ ...preview, wouldAdd: { itemId: args.itemId, criterion } });
+      if (preview?.dryRun)
+        return ok({
+          ...preview,
+          wouldAdd: { itemId: args.itemId, criterion },
+          criteriaQualityNote: describeCriteriaQuality([criterion]),
+        });
       const data = await api('POST', path, {
         body: criterion,
         headers: buildMutationHeaders(args),
@@ -2112,6 +2169,158 @@ The server refuses the change when the card is standing at a QA gate AND you are
     }
   );
 
+  server.tool(
+    'edit_work_item_acceptance_criterion',
+    `Rewrite the WORDS of one existing acceptance criterion — its \`whereText\`, \`whenText\`, \`thenText\` or \`givenText\`. Use it when a criterion says the wrong thing: its \`whereText\` names a surface this card does not own, its \`thenText\` asks for something no observation could measure, or it cites a count, fixture or file name that has since changed and would now fail a reviewer who is looking at the right thing.
+
+REWRITING ANY OF THE FOUR TEXTS CLEARS THE CRITERION'S SATISFACTION. The ticker, the column, the note, the dwell and the evidence link are all set back to NULL, and the card drops below its gate. That is deliberate and it is not a bug to work around: a tick is evidence about a SENTENCE, and the moment the sentence changes the evidence no longer refers to anything. Reordering alone does not clear it — only a change to the words does. So edit at grooming, before a pass has spent anything; editing a verified criterion costs a real recorded journey.
+
+WHAT THIS TOOL MUST NOT BE USED FOR, and it is the only way it can do damage: narrowing a criterion because the product is failing it. If the product does not do what the criterion says, the fix is the product, or a bounce naming the criterion — never a sentence rewritten until today's behaviour passes. Afterwards a laundered criterion is indistinguishable from one that always said that, except in the receipt, so the receipt is the only thing standing between this tool and a definition of done that quietly tracks whatever was built.
+
+PREFER THIS TO DELETION WHENEVER THE INTENT IS REAL. Most criteria that look impossible are merely mis-scoped — they ask this card to establish something the whole board owns. Rewriting keeps the intent on the record where a reader can still see what was wanted; deleting throws it away.${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`.'
+        ),
+      whereText: z
+        .string()
+        .optional()
+        .describe('New WHERE: the surface or system a reviewer looks at. Omit to leave unchanged.'),
+      whenText: z
+        .string()
+        .optional()
+        .describe('New WHEN: the action the reviewer takes. Omit to leave unchanged.'),
+      thenText: z
+        .string()
+        .optional()
+        .describe(
+          'New THEN: the observable result. Must be something a reviewer could see and ' +
+          'disagree about. Omit to leave unchanged.'
+        ),
+      givenText: z
+        .string()
+        .optional()
+        .describe('New GIVEN: the precondition. Omit to leave unchanged.'),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to apply it.'),
+      approved: z.boolean().optional().describe('Required true for a live write.'),
+      reason: z
+        .string()
+        .optional()
+        .describe(
+          'Required for a live write: what the criterion said, what it will say, and why ' +
+          'the old wording could not be reviewed as written.'
+        ),
+      idempotencyKey: z.string().optional().describe('Required for a live write. Reuse on retry.'),
+    },
+    async (args) => {
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/acceptance-criteria/${encodeURIComponent(args.criterionId)}`;
+      const preview = validateApiBridgeRequest({
+        method: 'PATCH',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      // Only the parts the caller actually named. An absent key means "leave this
+      // column exactly as it is" on the server; sending all four would clear the
+      // criterion's satisfaction even for a caller who changed one word.
+      const edit = {};
+      if (args.whereText !== undefined) edit.whereText = args.whereText;
+      if (args.whenText !== undefined) edit.whenText = args.whenText;
+      if (args.thenText !== undefined) edit.thenText = args.thenText;
+      if (args.givenText !== undefined) edit.givenText = args.givenText;
+      if (Object.keys(edit).length === 0) {
+        return ok({
+          edited: false,
+          refused:
+            'No new text was given, so there is nothing to change. Name at least one of ' +
+            'whereText, whenText, thenText or givenText.',
+        });
+      }
+      if (preview?.dryRun) {
+        return ok({
+          ...preview,
+          wouldEdit: { itemId: args.itemId, criterionId: args.criterionId, edit },
+          warning:
+            'Applying this CLEARS any existing satisfaction on this criterion — ticker, ' +
+            'column, note and evidence link — because the sentence the evidence referred ' +
+            'to will no longer exist.',
+        });
+      }
+      const data = await api('PATCH', path, {
+        body: edit,
+        headers: buildMutationHeaders(args),
+      });
+      return ok({ edited: true, criterion: data?.data });
+    }
+  );
+
+  server.tool(
+    'delete_work_item_acceptance_criterion',
+    `PERMANENTLY REMOVE one acceptance criterion from a card, taking its history with it. Reach for this ONLY when a criterion is unsatisfiable BY CONSTRUCTION — when no evidence any reviewer could gather would ever discharge it. That is not a high bar being enforced; it is a card that can never leave its gate, and it costs a full pass every time a lane draws it and discovers why.
+
+TWO SHAPES QUALIFY, and both were measured on this board:
+
+GATE-AS-CRITERION. Its subject is the exit condition of the whole gate or the whole board rather than this card's own deliverable — "every criterion on every QA card carries a fresh receipt", "every card in QA2 is verified". A card cannot verify the queue it is standing in, and a criterion requiring a later gate to have run cannot be discharged from the earlier one.
+
+PRODUCTION-CERTIFICATION. Its \`whereText\` is the production build after protected merge and deploy. Agents never move a card to Production and never certify production — that is the human owner's act by design — so no QA pass can discharge it at any level of effort. The observation is real and belongs in an acceptance note for the owner, not in a row that gates a QA lane.
+
+WHAT DOES NOT QUALIFY, which is most of what will tempt you: a criterion that is merely hard, currently failing, blocked on a fixture you do not have, or blocked on an environment that is down. Every one of those is a BOUNCE or a BLOCKER — cheap, reversible, and visible to whoever can clear it. Deletion is none of those things. "I could not satisfy it" and "it cannot be satisfied" are different claims, and only the second one is this tool.
+
+TRY \`edit_work_item_acceptance_criterion\` FIRST. In practice most impossible-looking criteria have real intent and an impossible SCOPE: rewriting one to the part this card actually owns keeps the intent legible to the next reader, where deleting erases the fact that the definition of done was ever larger. Delete when the intent itself does not belong on this card — not when its wording is wrong.
+
+Say in \`reason\` which of the two shapes it is and what a reviewer would have had to produce, because after this call nothing downstream can reconstruct what was removed.${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`. ' +
+          'Read the card first: ordinals shift as rows are removed, ids do not.'
+        ),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to delete it.'),
+      approved: z.boolean().optional().describe('Required true for a live write.'),
+      reason: z
+        .string()
+        .optional()
+        .describe(
+          'Required for a live write: which shape of unsatisfiable-by-construction this is ' +
+          '(gate-as-criterion or production-certification) and what a reviewer would have ' +
+          'had to produce. This is the only surviving record of what was removed.'
+        ),
+      idempotencyKey: z.string().optional().describe('Required for a live write. Reuse on retry.'),
+    },
+    async (args) => {
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/acceptance-criteria/${encodeURIComponent(args.criterionId)}`;
+      const preview = validateApiBridgeRequest({
+        method: 'DELETE',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) {
+        return ok({
+          ...preview,
+          wouldDelete: { itemId: args.itemId, criterionId: args.criterionId },
+          warning:
+            "This is irreversible and takes the criterion's history with it. Confirm from " +
+            'list_work_item_acceptance_criteria that this id is the row you mean — ordinals ' +
+            'shift when a row is removed, ids do not.',
+        });
+      }
+      const data = await api('DELETE', path, { headers: buildMutationHeaders(args) });
+      return ok({ deleted: true, remaining: data?.data });
+    }
+  );
+
   server.tool(
     'satisfy_work_item_acceptance_criterion',
     `Tick one acceptance criterion with the evidence you actually observed.
@@ -2277,14 +2486,14 @@ Anyone who can see the card may un-tick, including somebody undoing another pers
 
   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}`,
+    `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 runtime smoke. Local CLI or isolated runtime checks must declare local; they do not establish a staging deployment or a product user journey. 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']),
+      environment: z.enum(['local', 'staging', 'production']).describe('Where the evidence actually ran; local evidence must never be relabelled staging or 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.'),
+      buildSha: z.string().regex(/^[0-9a-f]{40}$/).describe('Exact tested 40-character commit SHA; declare deployment only when actually tested there.'),
       stagingSmoke: z.string().describe('The narrowest honest staging/runtime smoke performed.'),
       proofs: z
         .array(
@@ -2399,7 +2608,11 @@ A FLAG IS NOT A TAG. The tag says how urgent the WORK is; a flag says the CARD i
 
 THE REASON IS REQUIRED IN BOTH DIRECTIONS, and it is not the audit reason — it is the text a human reads on the card. Raising says what is wrong; clearing says what resolved it. Anyone may clear a flag, which only works because both directions are recorded as a comment on the card.
 
-This is what the ship-the-card skill means by "an unworkable card is a triage problem, not a coding problem": flag it, say the one question that would unblock it, and stop.${GOVERNED_NOTE}`,
+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.
+
+A FLAG HANDS THE CARD ON; IT DOES NOT HIDE IT. Raising one leaves the card claimable, so another agent picks it up, reads your reason, and tries — and reflags with what it learned if it fails too. That loop is the point: write the reason for the next agent, not for a log. Say what you tried and what you ruled out, because they will otherwise re-derive it.
+
+PASS blocksClaim:true ONLY FOR A BLOCKER NO AGENT CAN SATISFY — an owner credential, a vendor consent, a product decision. That takes the card out of every reviewer's queue until somebody clears it by hand, so it is the wrong answer for "the test failed" or "I could not work out why". If another agent could plausibly get further, leave it claimable.${GOVERNED_NOTE}`,
     {
       itemId: z.string().describe('Card id.'),
       flagged: z
@@ -2412,6 +2625,12 @@ This is what the ship-the-card skill means by "an unworkable card is a triage pr
         .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.'
         ),
+      blocksClaim: z
+        .boolean()
+        .optional()
+        .describe(
+          'Whether this flag stops anyone picking the card up. OMITTED MEANS FALSE — the card stays claimable and another agent can try, which is what a flag is for. Pass true only for a blocker no agent can satisfy (an owner credential, a vendor consent, a decision); that hides the card until somebody clears the flag by hand. Ignored when clearing — clearing always restores the blocking default.'
+        ),
       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
@@ -2446,7 +2665,15 @@ 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,
+            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,
+          },
         });
       }
 
@@ -2455,12 +2682,196 @@ This is what the ship-the-card skill means by "an unworkable card is a triage pr
           flagged: args.flagged,
           reason: args.reason,
           idempotencyKey: args.idempotencyKey,
+          // Sent only when the caller named it, so an older API that does not
+          // know the field is not handed one, and the server's own default
+          // (blocking) remains the single source of that decision.
+          ...(args.blocksClaim === undefined ? {} : { blocksClaim: args.blocksClaim }),
         },
         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. */
@@ -2495,12 +2906,17 @@ export const WORK_BOARD_TOOL_NAMES = [
   'create_work_item',
   'add_work_item_acceptance_criterion',
   'classify_work_item_acceptance_criterion',
+  'edit_work_item_acceptance_criterion',
+  'delete_work_item_acceptance_criterion',
   'satisfy_work_item_acceptance_criterion',
   'record_work_item_criterion_engineering_proof',
   'unsatisfy_work_item_acceptance_criterion',
   'get_work_item_comments',
   'comment_on_work_item',
   'flag_work_item',
+  'archive_work_item',
+  'delete_work_item',
+  'unarchive_work_item',
   'block_work_item',
   'unblock_work_item',
 ];