@adrata/adrata-mcp 1.0.0 → 1.0.2

package/tools/work-board-tools.js

@@ -1,3 +1,5 @@
+import { auditWorkHubBoards, deliveryContradictions } from './work-hub/audit.js';
+
 /**
  * Work-board tools for the Adrata MCP Server.
  *
@@ -110,14 +112,9 @@ export function describeUnauditableReason(reason) {
 /**
  * Why a card with no body will not be workable, or `null` if it has one.
  *
- * Deliberately the weakest possible check. The card model says a Task carries
- * acceptance criteria — the artifact with two consumers, the build spec for the
- * agent and the test plan for QA — and today those criteria live in `body`,
- * because there is no `acceptance_criteria` column yet. But "does this prose
- * contain acceptance criteria" is a judgement, not a pattern: a regex looking
- * for the word would pass a heading with nothing under it and fail a perfectly
- * good "the Export button is disabled while an export is running". Asserting it
- * either way would be the tool inventing a verdict.
+ * The body is working context: request, evidence, repro, constraints. The
+ * executable definition of done lives in first-class acceptance-criteria rows
+ * and has its own check below, so prose is never regex-classified as criteria.
  *
  * A MISSING body is a fact, so that is what this reports — as a note on the
  * dry-run preview, where a human is already deciding, and never as a refusal.
@@ -126,18 +123,35 @@ export function describeUnauditableReason(reason) {
  */
 export function describeMissingBody(body) {
   if (String(body ?? '').trim()) return undefined;
-  return 'This card would arrive with a title and nothing else. A card is the unit of QA sign-off, so with no body it carries no acceptance criteria — nobody can validate it and no agent can build from it. Add the criteria to `body` (one checkable outcome per line), or say in the body what is still unknown.';
+  return 'This card would arrive with a title and no working context. Add the request, evidence, or repro to `body`, or say what is still unknown. Acceptance criteria are separate first-class records in `acceptanceCriteria`.';
+}
+
+export function describeMissingAcceptanceCriteria(criteria) {
+  if (Array.isArray(criteria) && criteria.length > 0) return undefined;
+  return 'This card would have no executable acceptance criteria. It can be captured, but it is not ready for build or QA until at least one where/when/then criterion is added.';
+}
+
+/** One target stage's WIP state before and after a proposed move. */
+export function projectColumnWip({ limit, count, cardAlreadyThere, truncated = false }) {
+  const projected = count + (cardAlreadyThere ? 0 : 1);
+  return {
+    limit: limit ?? null,
+    current: count,
+    projected,
+    overLimit: limit == null ? false : projected > limit,
+    completeCount: !truncated,
+  };
 }
 
 /**
  * Register the work-board tools.
  *
  * @param {McpServer} server - the MCP server instance (already tier-gated)
- * @param {object} deps - { z, api, ok, validateApiBridgeRequest, buildMutationHeaders }
+ * @param {object} deps - { z, api, ok, validateApiBridgeRequest, buildMutationHeaders, getGrantedScope }
  */
 export function registerWorkBoardTools(
   server,
-  { z, api, ok, validateApiBridgeRequest, buildMutationHeaders }
+  { z, api, ok, validateApiBridgeRequest, buildMutationHeaders, getGrantedScope = () => undefined }
 ) {
   const GOVERNED_NOTE =
     ' Governed write: previews by default. A live write requires dryRun:false plus approved:true, a reason, and an idempotencyKey (reuse the SAME key on retry — a duplicate move would read as the card having bounced between columns).';
@@ -262,6 +276,54 @@ Start here for "what should I work on". With includeUnassigned it also returns t
     }
   );
 
+  server.tool(
+    'get_work_item_delivery_evidence',
+    `Read the four facts that must never be collapsed into one status: the card's workflow column, linked pull-request state, exact-SHA staging presence, and exact-SHA production presence. Use this before calling a card shipped or treating the Production column as proof. Unknown means Adrata has no trustworthy evidence; it never means the work is absent. This tool is read-only and does not move the card.`,
+    {
+      itemId: z.string().describe('Card id.'),
+    },
+    async (args) => {
+      const data = await api(
+        'GET',
+        `/api/v1/work-items/${encodeURIComponent(args.itemId)}/delivery-evidence`
+      );
+      const evidence = data?.data;
+      const contradictions = deliveryContradictions(evidence);
+      return ok({ evidence, contradictions });
+    }
+  );
+
+  server.tool(
+    'list_work_item_acceptance_criteria',
+    'Read the ordered, executable definition of done for one card. Each criterion says where to check, any starting state, what action to perform, and the observable result. A zero-length list is a finding: nobody has stated how QA can decide the card is done.',
+    { itemId: z.string().describe('Card id.') },
+    async (args) => {
+      const data = await api(
+        'GET',
+        `/api/v1/work-items/${encodeURIComponent(args.itemId)}/acceptance-criteria`
+      );
+      const criteria = data?.data ?? [];
+      return ok({ count: criteria.length, criteria });
+    }
+  );
+
+  server.tool(
+    'audit_work_hub',
+    `Audit every visible Starfield board as an operating ledger. Returns named findings for active cards without owners, active passes without handlers, missing definitions of done, missing work types or context, stale stages, and truncated reads. It does not award a vanity score and it does not mutate anything. A clean result means the board has the minimum workflow facts required to operate from it; deployment truth remains a separate exact-SHA fact available through get_work_item_delivery_evidence.`,
+    {},
+    async () => {
+      const listed = await api('GET', '/api/v1/work-boards');
+      const refs = listed?.data ?? [];
+      const boards = await Promise.all(
+        refs.map(async (board) => {
+          const detail = await api('GET', `/api/v1/work-boards/${encodeURIComponent(board.id)}`);
+          return detail?.data;
+        })
+      );
+      return ok(auditWorkHubBoards(boards.filter(Boolean)));
+    }
+  );
+
   server.tool(
     'get_work_board_rollup',
     'Read several boards as one prioritisation view. Pass "all" for the implicit roll-up of every board in the workspace (it has no membership rows, so a board created a minute ago is already in it), or a roll-up id for a curated one. Each slice keeps its own board, company, staleness policy, and tag scheme — cards are ranked WITHIN their own scheme and never translated across schemes, so a P1 is never silently equated with a Critical.',
@@ -317,6 +379,103 @@ Start here for "what should I work on". With includeUnassigned it also returns t
   // WRITES
   // =========================================================================
 
+  server.tool(
+    'set_work_board_archived',
+    `Hide or restore a board in the workspace catalogue without deleting anything. Archived boards disappear from normal board lists and roll-ups, but their cards, history, releases, QA flows, memberships, and evidence remain intact. Use this for obsolete, duplicate, or no-longer-operated boards; never manufacture a release or delete cards merely to clean up the board chooser.${GOVERNED_NOTE}`,
+    {
+      boardId: z.string().describe('Board id from list_work_boards.'),
+      archived: z.boolean().describe('true hides the board; false restores it.'),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false for a live change.'),
+      approved: z.boolean().optional().describe('Required true for a live change.'),
+      reason: z.string().optional().describe('Required for a live change: why this board is being hidden or restored.'),
+      idempotencyKey: z.string().optional().describe('Required for a live change.'),
+    },
+    async (args) => {
+      const path = `/api/v1/work-boards/${encodeURIComponent(args.boardId)}/archived`;
+      const preview = validateApiBridgeRequest({
+        method: 'PATCH',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) {
+        const data = await api('GET', `/api/v1/work-boards/${encodeURIComponent(args.boardId)}`);
+        const board = data?.data;
+        const terminalNames = new Set(['production', 'deep backlog']);
+        const activeCount = (board?.items ?? []).filter((item) => {
+          const column = board?.columns?.find((candidate) => candidate.id === item.columnId);
+          return column && !terminalNames.has(String(column.name).trim().toLowerCase());
+        }).length;
+        return ok({
+          ...preview,
+          wouldSetBoardArchived: {
+            boardId: args.boardId,
+            boardName: board?.name,
+            archived: args.archived,
+            visibleItemCount: board?.itemCount ?? (board?.items ?? []).length,
+            activeItemCount: activeCount,
+            completeCount: board?.truncated !== true,
+          },
+        });
+      }
+
+      const data = await api('PATCH', path, {
+        body: { archived: args.archived },
+        headers: buildMutationHeaders(args),
+      });
+      return ok({ boardArchiveStateSet: true, ...data?.data });
+    }
+  );
+
+  server.tool(
+    'set_work_board_column_wip_limit',
+    `Set or clear one board column's visible WIP ceiling. Exceeding the ceiling never blocks a move: the board renders the measured count and limit in red so daily Aligning can answer for it. Only a workspace admin may change this operating policy. Production and Deep backlog cannot have limits because they are output and parking columns, not work centres.${GOVERNED_NOTE}`,
+    {
+      boardId: z.string().describe('Board id from list_work_boards.'),
+      columnId: z.string().describe('Column id from get_work_board.'),
+      wipLimit: z
+        .number()
+        .int()
+        .positive()
+        .nullable()
+        .describe('Positive ceiling, or null to clear it (unlimited).'),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to change it.'),
+      approved: z.boolean().optional().describe('Required true for a live change.'),
+      reason: z.string().optional().describe('Required for a live change: why this capacity is right.'),
+      idempotencyKey: z.string().optional().describe('Required for a live change. Reuse on retry.'),
+    },
+    async (args) => {
+      const unauditable = args.dryRun === false ? describeUnauditableReason(args.reason) : null;
+      if (unauditable) return ok({ error: true, message: unauditable });
+
+      const path = `/api/v1/work-boards/${encodeURIComponent(args.boardId)}/columns/${encodeURIComponent(args.columnId)}/wip-limit`;
+      const preview = validateApiBridgeRequest({
+        method: 'PATCH',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) {
+        return ok({
+          ...preview,
+          wouldSet: { boardId: args.boardId, columnId: args.columnId, wipLimit: args.wipLimit },
+        });
+      }
+
+      const data = await api('PATCH', path, {
+        body: { wipLimit: args.wipLimit },
+        headers: buildMutationHeaders(args),
+      });
+      return ok({ updated: true, column: data?.data });
+    }
+  );
+
   server.tool(
     'move_work_item',
     `Move a card to another column on the same board — and, with claim:true, pick it up in the same action. The server does this in ONE transaction: it closes the card's open dwell, appends the transition to the history, records you as the handler of the pass the card is now on, and updates the card. Dropping a card into the column it is already in is a REORDER and deliberately does not restamp the stage timer.
@@ -343,7 +502,7 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
         .boolean()
         .optional()
         .describe(
-          'Take over a pass SOMEBODY ELSE IS HOLDING. Requires claim:true and a reason saying why — the reason is the only record that person will have of losing the pass mid-stage. It does NOT take the card off its owner: reassigning a card is the assignee field on update_work_item, a deliberate act, never a side effect of a move. Do not reach for this to work around a refusal; a pass somebody is running is theirs.'
+          'Take over a pass SOMEBODY ELSE IS HOLDING. Requires claim:true and a reason saying why — the reason is the only record that person will have of losing the pass mid-stage. It does NOT take the card off its owner: reassigning a card is a deliberate edit to its assignee, never a side effect of a move — and there is no board tool here that does it, so reassignment is a human act on the board (or an explicit PATCH via adrata_api_request). Do not reach for this to work around a refusal; a pass somebody is running is theirs.'
         ),
       dryRun: z.boolean().optional().describe('Defaults to true. Set false for a live move.'),
       approved: z.boolean().optional().describe('Required true for a live move.'),
@@ -377,8 +536,29 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
         approved: args.approved,
         reason: args.reason,
         idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
       });
       if (preview?.dryRun) {
+        const itemData = await api(
+          'GET',
+          `/api/v1/work-items/${encodeURIComponent(args.itemId)}`
+        );
+        const item = itemData?.data;
+        const boardData = await api(
+          'GET',
+          `/api/v1/work-boards/${encodeURIComponent(item.boardId)}`
+        );
+        const board = boardData?.data;
+        const target = board?.columns?.find((column) => column.id === args.toColumnId);
+        if (!target) {
+          return ok({
+            error: true,
+            message: 'toColumnId is not a column on this card\'s board.',
+          });
+        }
+        const count = (board.items ?? []).filter(
+          (candidate) => candidate.columnId === args.toColumnId
+        ).length;
         return ok({
           ...preview,
           wouldMove: {
@@ -388,6 +568,12 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
             claim: args.claim === true,
             force: args.force === true,
           },
+          wip: projectColumnWip({
+            limit: target.wipLimit,
+            count,
+            cardAlreadyThere: item.columnId === args.toColumnId,
+            truncated: board.truncated === true,
+          }),
         });
       }
 
@@ -467,6 +653,7 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
         approved: args.approved,
         reason: args.reason,
         idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
       });
       if (preview?.dryRun) {
         return ok({
@@ -523,6 +710,7 @@ Pass kind:null to clear it back to UNTYPED. Untyped is a real state and is NOT t
         approved: args.approved,
         reason: args.reason,
         idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
       });
       if (preview?.dryRun) {
         return ok({
@@ -547,7 +735,7 @@ Pass kind:null to clear it back to UNTYPED. Untyped is a real state and is NOT t
     'create_work_item',
     `Create a card on a board. Lands in the named column, or the board's first column when none is given.
 
-WRITE THE ACCEPTANCE CRITERIA IN \`body\`. A card is the unit of QA sign-off, so a card that does not say what "done" means cannot be validated by QA and cannot be built from by the next agent — those are the two readers of the same list. There is no separate criteria field yet: the criteria live in \`body\`, under a short "Acceptance criteria" heading, one checkable outcome per line. If you cannot write them, you do not yet understand the card well enough to file it as workable — file it with what you DO know and say in the body that the criteria are missing, rather than inventing outcomes nobody agreed to.
+ACCEPTANCE CRITERIA ARE FIRST-CLASS RECORDS, not prose buried in \`body\`. Use \`acceptanceCriteria\` for the executable definition of done: where to check, any starting state, what action to perform, and the observable result. The card and every criterion are replay-safe under one idempotency-key family, so a retry after a partial failure cannot duplicate either. If you cannot write criteria, capture what you know in \`body\`; the preview will mark the card as not ready rather than inventing outcomes nobody agreed to.
 
 ONE CARD IS ONE QA JUDGEMENT. If your criteria list needs QA to make more than one call ("follows the OS theme" AND "the toggle persists" AND "every surface is restyled"), that is several cards, not one — a bounce from a multi-outcome card names nothing actionable. Implementation steps ("create a React hook", "rename the CSS variables") are never cards; they are lines inside one.
 
@@ -559,7 +747,20 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
         .string()
         .optional()
         .describe(
-          'The request in full AND its acceptance criteria — what QA will validate this against, one checkable outcome per line under an "Acceptance criteria" heading. Repro steps for a bug go here too. Markdown; an implementation checklist belongs here rather than in sub-cards, because there are none by design.'
+          'The request, evidence, and repro/context. Markdown. The executable definition of done belongs in acceptanceCriteria, not in this prose.'
+        ),
+      acceptanceCriteria: z
+        .array(
+          z.object({
+            whereText: z.string().describe('Surface, environment, account, or role to check.'),
+            givenText: z.string().optional().describe('Starting state, when one is required.'),
+            whenText: z.string().describe('Action the verifier performs.'),
+            thenText: z.string().describe('Observable result that must follow.'),
+          })
+        )
+        .optional()
+        .describe(
+          'Executable definition of done. One independently checkable outcome per entry. Omit only for a thin capture that is not ready to build.'
         ),
       product: z.string().optional().describe('Product tag — orthogonal to the board.'),
       kind: z
@@ -589,11 +790,17 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
         approved: args.approved,
         reason: args.reason,
         idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
       });
       if (preview?.dryRun) {
         return ok({
           ...preview,
-          wouldCreate: { boardId: args.boardId, title: args.title, kind: args.kind },
+          wouldCreate: {
+            boardId: args.boardId,
+            title: args.title,
+            kind: args.kind,
+            acceptanceCriteria: args.acceptanceCriteria ?? [],
+          },
           // A statement of FACT about the body, not a guess about its contents.
           // "Does this text contain acceptance criteria" is not something a
           // regex can answer honestly, and a heuristic that half-answered it
@@ -604,6 +811,7 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
           // already deciding whether to approve, and never blocking: a refused
           // capture is how work stops reaching the board at all.
           note: describeMissingBody(args.body),
+          readinessNote: describeMissingAcceptanceCriteria(args.acceptanceCriteria),
         });
       }
 
@@ -620,7 +828,61 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
         },
         headers: buildMutationHeaders(args),
       });
-      return ok({ created: true, item: data?.data });
+      const item = data?.data;
+      const criteria = [];
+      for (const [index, criterion] of (args.acceptanceCriteria ?? []).entries()) {
+        const criterionKey = `${args.idempotencyKey}:criterion:${index + 1}`;
+        const result = await api(
+          'POST',
+          `/api/v1/work-items/${encodeURIComponent(item.id)}/acceptance-criteria`,
+          {
+            body: criterion,
+            headers: buildMutationHeaders({
+              ...args,
+              idempotencyKey: criterionKey,
+            }),
+          }
+        );
+        criteria.push(result?.data);
+      }
+      return ok({ created: true, item, criteria });
+    }
+  );
+
+  server.tool(
+    'add_work_item_acceptance_criterion',
+    `Add one executable acceptance criterion to a card. This is grooming, not a comment: write where the check runs, the action, and the observable result. The server keeps criteria ordered and auditable.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id.'),
+      whereText: z.string().describe('Surface, environment, account, or role to check.'),
+      givenText: z.string().optional().describe('Starting state, when one is required.'),
+      whenText: z.string().describe('Action the verifier performs.'),
+      thenText: z.string().describe('Observable result that must follow.'),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to add it.'),
+      approved: z.boolean().optional().describe('Required true for a live write.'),
+      reason: z.string().optional().describe('Required for a live write: why this criterion is being added.'),
+      idempotencyKey: z.string().optional().describe('Required for a live write. Reuse on retry.'),
+    },
+    async (args) => {
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/acceptance-criteria`;
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        ...args,
+        grantedScope: getGrantedScope(),
+      });
+      const criterion = {
+        whereText: args.whereText,
+        givenText: args.givenText,
+        whenText: args.whenText,
+        thenText: args.thenText,
+      };
+      if (preview?.dryRun) return ok({ ...preview, wouldAdd: { itemId: args.itemId, criterion } });
+      const data = await api('POST', path, {
+        body: criterion,
+        headers: buildMutationHeaders(args),
+      });
+      return ok({ added: true, criterion: data?.data });
     }
   );
   server.tool(
@@ -659,6 +921,7 @@ TO @-MENTION SOMEBODY, write the token \`<@userId>\` in the body — the id come
         approved: args.approved,
         reason: args.reason,
         idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
       });
       if (preview?.dryRun) {
         return ok({ ...preview, wouldComment: { itemId: args.itemId, body: args.body } });
@@ -718,6 +981,7 @@ This is what the ship-the-card skill means by "an unworkable card is a triage pr
         // reason explains the write and `body` is the content.
         reason: args.reason,
         idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
       });
       if (preview?.dryRun) {
         return ok({
@@ -746,12 +1010,18 @@ export const WORK_BOARD_TOOL_NAMES = [
   'get_work_board',
   'get_work_item',
   'get_work_item_history',
+  'get_work_item_delivery_evidence',
+  'audit_work_hub',
+  'list_work_item_acceptance_criteria',
   'get_work_board_rollup',
   'list_work_board_rollups',
+  'set_work_board_archived',
+  'set_work_board_column_wip_limit',
   'move_work_item',
   'set_work_item_tag',
   'set_work_item_kind',
   'create_work_item',
+  'add_work_item_acceptance_criterion',
   'get_work_item_comments',
   'comment_on_work_item',
   'flag_work_item',

package/tools/work-hub/audit.js

@@ -0,0 +1,162 @@
+/**
+ * Pure operating-health projection for Starfield boards.
+ *
+ * A board is trustworthy when its workflow claims are backed by the minimum
+ * facts needed to act: ownership, a work type, a definition of done, and a
+ * current stage. Delivery evidence is deliberately added separately because a
+ * column is not a deployment receipt.
+ */
+
+const TERMINAL_STAGES = new Set(['production', 'deep backlog']);
+// Up Next is the deliberately unowned pull buffer. Triage/Aligning are capture
+// and grooming, where thin cards are allowed. Only these stages mean somebody
+// has actually taken a pass and therefore require both an end-to-end owner and
+// a current handler.
+const ACTIVE_STAGES = new Set(['in progress', 'staging qa1', 'staging qa2']);
+// A card crossing the cut line into Up Next must be executable. Production is
+// included because historical evidence does not stop mattering after release.
+const EXECUTABLE_STAGES = new Set(['up next', ...ACTIVE_STAGES, 'production']);
+
+function normalized(value) {
+  return String(value ?? '').trim().toLowerCase();
+}
+
+function hoursSince(iso, nowMs) {
+  const entered = Date.parse(iso);
+  if (!Number.isFinite(entered)) return null;
+  return Math.max(0, (nowMs - entered) / 3_600_000);
+}
+
+export function deliveryContradictions(evidence) {
+  const contradictions = [];
+  const workflowStage = normalized(evidence?.workflow?.columnName);
+  if (workflowStage === 'production' && evidence?.production?.state !== 'live') {
+    contradictions.push({
+      code: 'production_column_without_live_evidence',
+      message:
+        'The card is in Production, but exact-SHA production evidence is not live. Treat the column as a workflow claim, not a deployment receipt.',
+    });
+  }
+  if (evidence?.production?.state === 'live' && workflowStage !== 'production') {
+    contradictions.push({
+      code: 'live_evidence_outside_production_column',
+      message:
+        'Exact-SHA production evidence is live, but the workflow card has not reached Production.',
+    });
+  }
+  return contradictions;
+}
+
+/**
+ * @param {Array<object>} boards Full board payloads from GET /work-boards/{id}.
+ * @param {{now?: Date|string|number}} options
+ */
+export function auditWorkHubBoards(boards, { now = new Date() } = {}) {
+  const nowMs = new Date(now).getTime();
+  const findings = [];
+  const perBoard = [];
+  let totalCards = 0;
+  let openCards = 0;
+  let activeCards = 0;
+
+  for (const board of boards) {
+    const columns = new Map((board.columns ?? []).map((column) => [column.id, column]));
+    const boardFindings = [];
+    const items = board.items ?? [];
+    totalCards += items.length;
+
+    if (board.truncated === true) {
+      boardFindings.push({
+        code: 'board_truncated',
+        itemId: null,
+        title: null,
+        detail: `The board returned ${items.length} of ${board.itemCount ?? 'an unknown number of'} cards.`,
+      });
+    }
+
+    for (const item of items) {
+      const column = columns.get(item.columnId);
+      const stage = column?.name ?? 'Unknown';
+      const stageKey = normalized(stage);
+      const isTerminal = TERMINAL_STAGES.has(stageKey);
+      const isActive = ACTIVE_STAGES.has(stageKey);
+      const mustBeExecutable = EXECUTABLE_STAGES.has(stageKey);
+      if (!isTerminal) openCards += 1;
+      if (isActive) activeCards += 1;
+
+      const add = (code, detail) =>
+        boardFindings.push({ code, itemId: item.id, title: item.title, stage, detail });
+
+      if (mustBeExecutable && !String(item.body ?? '').trim()) {
+        add('missing_body', 'The card crossed the cut line without working context.');
+      }
+      if (mustBeExecutable) {
+        if (item.criteria?.total === 0) {
+          add('missing_acceptance_criteria', 'Nobody has stated a checkable definition of done.');
+        } else if (item.criteria === undefined) {
+          add('criteria_not_measured', 'This read did not include acceptance-criteria status.');
+        }
+        if (!item.kind) add('missing_kind', 'The card is not classified as a story, bug, or chore.');
+      }
+      if (isActive && !item.assigneeUserId) {
+        add('unowned_active_card', 'The card is active but has no end-to-end owner.');
+      }
+      if (isActive && !item.handler) {
+        add('unhandled_active_pass', 'The active build or QA pass has no handler.');
+      }
+
+      const staleAfter = column?.staleness?.staleAfterHours;
+      const ageHours = hoursSince(item.enteredColumnAt, nowMs);
+      if (!isTerminal && Number.isFinite(staleAfter) && ageHours !== null && ageHours > staleAfter) {
+        add(
+          'stale_open_card',
+          `The card has spent ${Math.floor(ageHours)}h in ${stage}; this column is stale after ${staleAfter}h.`
+        );
+      }
+    }
+
+    findings.push(...boardFindings.map((finding) => ({ boardId: board.id, boardName: board.name, ...finding })));
+    perBoard.push({
+      boardId: board.id,
+      boardName: board.name,
+      cards: items.length,
+      activeCards: items.filter((item) => {
+        const stage = columns.get(item.columnId)?.name;
+        return ACTIVE_STAGES.has(normalized(stage));
+      }).length,
+      findings: boardFindings.length,
+    });
+  }
+
+  const counts = {};
+  for (const finding of findings) counts[finding.code] = (counts[finding.code] ?? 0) + 1;
+
+  const priorityOrder = [
+    'board_truncated',
+    'unowned_active_card',
+    'unhandled_active_pass',
+    'missing_acceptance_criteria',
+    'stale_open_card',
+    'missing_body',
+    'missing_kind',
+    'criteria_not_measured',
+  ];
+  const rank = new Map(priorityOrder.map((code, index) => [code, index]));
+  findings.sort((a, b) => (rank.get(a.code) ?? 99) - (rank.get(b.code) ?? 99));
+
+  return {
+    trustworthy: findings.length === 0,
+    generatedAt: new Date(nowMs).toISOString(),
+    boards: boards.length,
+    totalCards,
+    openCards,
+    activeCards,
+    counts,
+    perBoard,
+    findings,
+    interpretation:
+      findings.length === 0
+        ? 'Every returned card has the minimum facts required to operate from this hub. Delivery truth must still be read from exact-SHA evidence.'
+        : 'The hub is not yet trustworthy as an operating ledger. Work the findings in order; do not infer completion from column position.',
+  };
+}