@adrata/adrata-mcp 1.0.8 → 1.0.30

package/tools/work-hub/audit.js

@@ -13,9 +13,9 @@ const TERMINAL_STAGES = new Set(['production', 'deep backlog']);
 // has actually taken a pass and therefore require both an end-to-end owner and
 // a current handler.
 const ACTIVE_STAGES = new Set(['aligning', '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']);
+// Acceptance and release still require executable facts, but do not require
+// an active build/QA handler. Stage placement alone is not delivery evidence.
+const EXECUTABLE_STAGES = new Set(['up next', ...ACTIVE_STAGES, 'ready to ship', 'production']);
 
 function normalized(value) {
   return String(value ?? '')
@@ -51,9 +51,14 @@ export function deliveryContradictions(evidence) {
 
 /**
  * @param {Array<object>} boards Full board payloads from GET /work-boards/{id}.
- * @param {{now?: Date|string|number}} options
+ * @param {{now?: Date|string|number, expectedBoards?: number}} options
+ *   `expectedBoards` is how many boards the caller LISTED, before any of their
+ *   detail reads failed. Pass it whenever the two numbers can differ; it is the
+ *   only way this function can tell "every board is clean" from "most boards
+ *   never arrived". It defaults to the number handed in, so a caller that reads
+ *   boards by another route is not forced to invent one.
  */
-export function auditWorkHubBoards(boards, { now = new Date() } = {}) {
+export function auditWorkHubBoards(boards, { now = new Date(), expectedBoards } = {}) {
   const nowMs = new Date(now).getTime();
   const findings = [];
   const perBoard = [];
@@ -61,13 +66,61 @@ export function auditWorkHubBoards(boards, { now = new Date() } = {}) {
   let openCards = 0;
   let activeCards = 0;
 
+  // A scan with nothing in it is the one result this audit must never report as
+  // health. `trustworthy` is derived from an empty finding list, so a workspace
+  // that returned no boards — or whose board reads all failed — would otherwise
+  // read exactly like a workspace whose every card is in order, and read that
+  // way in the confident words below. The repo has this failure written down
+  // (`scripts/check-context-stores.sh` refuses to "pass vacuously"); this is the
+  // same floor, in the same shape.
+  const expected = Number.isFinite(expectedBoards) ? expectedBoards : boards.length;
+  if (boards.length === 0) {
+    findings.push({
+      boardId: null,
+      boardName: null,
+      code: expected > 0 ? 'boards_unreadable' : 'no_boards_read',
+      itemId: null,
+      title: null,
+      stage: null,
+      detail:
+        expected > 0
+          ? `All ${expected} listed board(s) failed to read. This audit covered nothing.`
+          : 'No board was returned, so nothing was audited. An empty scan is not a clean scan.',
+    });
+  } else if (expected > boards.length) {
+    findings.push({
+      boardId: null,
+      boardName: null,
+      code: 'boards_unreadable',
+      itemId: null,
+      title: null,
+      stage: null,
+      detail: `${expected - boards.length} of ${expected} listed board(s) failed to read and were not audited. The findings below cover ${boards.length} board(s) only.`,
+    });
+  }
+
   for (const board of boards) {
     const columns = new Map((board.columns ?? []).map((column) => [column.id, column]));
     const boardFindings = [];
-    const items = board.items ?? [];
+    // An absent `items` is NOT an empty board. Collapsing the two is how a
+    // partial payload comes to certify a board nobody actually read.
+    const itemsUnreadable = !Array.isArray(board.items);
+    const items = itemsUnreadable ? [] : board.items;
     totalCards += items.length;
 
-    if (board.truncated === true) {
+    if (itemsUnreadable) {
+      boardFindings.push({
+        code: 'board_items_unreadable',
+        itemId: null,
+        title: null,
+        detail: 'This board payload carried no card list, so none of its cards were audited.',
+      });
+    }
+
+    if (
+      board.truncated === true ||
+      (!itemsUnreadable && Number.isInteger(board.itemCount) && board.itemCount > items.length)
+    ) {
       boardFindings.push({
         code: 'board_truncated',
         itemId: null,
@@ -89,13 +142,19 @@ export function auditWorkHubBoards(boards, { now = new Date() } = {}) {
       const add = (code, detail) =>
         boardFindings.push({ code, itemId: item.id, title: item.title, stage, detail });
 
+      if (!column || !normalized(column.name)) {
+        add(
+          'card_stage_unreadable',
+          'The card has no resolvable stage, so its readiness requirements could not be audited.'
+        );
+      }
       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) {
+        } else if (!Number.isInteger(item.criteria?.total) || item.criteria.total < 0) {
           add('criteria_not_measured', 'This read did not include acceptance-criteria status.');
         }
         if (!item.kind)
@@ -142,7 +201,13 @@ export function auditWorkHubBoards(boards, { now = new Date() } = {}) {
   for (const finding of findings) counts[finding.code] = (counts[finding.code] ?? 0) + 1;
 
   const priorityOrder = [
+    // Coverage first, always. A finding about a card is worth reading only once
+    // you know which cards were in the scan at all.
+    'no_boards_read',
+    'boards_unreadable',
+    'board_items_unreadable',
     'board_truncated',
+    'card_stage_unreadable',
     'unowned_active_card',
     'unhandled_active_pass',
     'missing_acceptance_criteria',
@@ -158,6 +223,7 @@ export function auditWorkHubBoards(boards, { now = new Date() } = {}) {
     trustworthy: findings.length === 0,
     generatedAt: new Date(nowMs).toISOString(),
     boards: boards.length,
+    boardsExpected: expected,
     totalCards,
     openCards,
     activeCards,

package/tools/work-hub/criteria-quality.js

@@ -0,0 +1,212 @@
+/**
+ * Can a second person falsify this criterion?
+ *
+ * # Why this exists
+ *
+ * A Starfield criterion is four fields — where, given, when, then — and the
+ * server checks exactly three things about each part: it is not blank, it is
+ * under 600 characters, and it is not a pasted transcript
+ * (`criteria/edit.rs::validate_part`). Every one of those is a check on the
+ * STRING. None of them is a check on whether the sentence says something a
+ * reviewer could disagree with.
+ *
+ * So `thenText: "it works correctly"` is a valid criterion today. It will be
+ * ticked, it will count toward `met`, and at the QA gate it will be graded on
+ * WHO ticked it and in WHICH dwell — both of which can be perfectly in order
+ * while the sentence itself remains unfalsifiable. The independence machinery
+ * in `criteria/rule.rs` is strong and this is the gap underneath it: it
+ * guarantees that a different pair of hands checked the criterion, not that the
+ * criterion could have failed.
+ *
+ * The rubric this borrows from is the repo's own `task-validation` skill
+ * (`.claude/skills/task-validation/references/task-rubrics.md`, metric 6,
+ * "Acceptance Criteria Quality"), which names the failure directly:
+ *
+ *     BAD (Score: 50):
+ *     - "Button looks good" (subjective)
+ *     - "Works correctly" (vague)
+ *     - "Performance is acceptable" (unmeasurable)
+ *
+ * That rubric has never run: it scores YAML task files by hand and is wired to
+ * no command, no hook and no CI job. What follows is the checkable third of it,
+ * moved to the place where criteria are actually written.
+ *
+ * # What it deliberately does NOT do
+ *
+ * It does not score. `audit_work_hub` says in its own description that it "does
+ * not award a vanity score", and that judgement holds here: a criterion graded
+ * 72/100 tells a reader nothing they can act on, and the only recorded run of
+ * the SPOQ rubric in this repo scored nine consecutive tasks 98/100 — a number
+ * that had stopped distinguishing between them. Findings are named or absent.
+ *
+ * It does not block. `describeMissingBody` states the argument already: "a
+ * refused capture is how work stops reaching the board at all." These are
+ * advisory notes returned beside a dry-run preview and beside a criteria read,
+ * where a person or an agent is already deciding what to write.
+ *
+ * # Why the patterns are anchored
+ *
+ * Every rule below matches a WHOLE normalised field, or a whole word for
+ * placeholders. A substring rule would fire on "the row saves successfully and
+ * the toast names the new owner", which is a good criterion containing a weak
+ * word. The cost of that false positive is an author learning to ignore the
+ * notes, which is worse than the check not existing. When in doubt these rules
+ * stay silent.
+ */
+
+/** Lowercase, collapse whitespace, drop trailing punctuation. */
+function normalise(value) {
+  return String(value ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, ' ')
+    .replace(/[.!]+$/, '');
+}
+
+// The article is optional because the rubric's own worked example is the
+// article-less form — "Button looks good" — and an author writing a weak
+// criterion is exactly the author who drops it.
+const SUBJECT =
+  '(?:it|this|(?:the )?(?:app|feature|page|screen|button|toggle|flow|ui|component|form|list|modal|panel|view|result|change|fix|thing))';
+
+/**
+ * A `then` that asserts nothing observable.
+ *
+ * Anchored whole-string, so "the toggle works" fires and "the toggle works on a
+ * cold reload and the label reads Dark" does not.
+ */
+const UNFALSIFIABLE_THEN = [
+  new RegExp(
+    `^${SUBJECT}? ?(?:works|work|is working|works correctly|works properly|works as expected|functions correctly|functions as expected)$`
+  ),
+  new RegExp(
+    `^${SUBJECT}? ?(?:behaves|performs|renders|displays|loads|responds) (?:correctly|properly|as expected|fine|ok|okay)$`
+  ),
+  new RegExp(
+    `^${SUBJECT}? ?(?:is|looks|seems) (?:good|right|correct|fine|ok|okay|acceptable|reasonable|as expected|better|improved)$`
+  ),
+  new RegExp(`^${SUBJECT}? ?(?:is|are)? ?(?:successful|success|succeeds|passes|passed)$`),
+  /^(?:everything|all of it|all) (?:works|is fine|is ok|is okay|is correct|looks good)$/,
+  /^no (?:errors|issues|problems|regressions|bugs)(?: (?:occur|appear|are seen|are observed|are present))?$/,
+  /^(?:performance|it) (?:is|feels) (?:acceptable|fast|good|fine|snappy|better|improved)$/,
+  /^(?:there (?:is|are) )?no (?:visual )?(?:change|changes|difference|differences)$/,
+];
+
+/**
+ * A `where` that names no surface.
+ *
+ * The field asks for a "Surface, environment, account, or role". A bare
+ * environment ("staging", "production") is a legitimate answer and is NOT
+ * listed here; a whole-product noun is not an answer at all, because it does
+ * not tell the next reviewer where to stand.
+ */
+const UNLOCATED_WHERE = [
+  /^(?:the )?(?:app|application|product|system|platform|site|website|service|ui|frontend|front end|backend|back end|client|server)$/,
+  /^(?:the )?(?:code|codebase|repo|repository|source)$/,
+  // `n/a` and friends are deliberately absent: PLACEHOLDER already names them,
+  // and one field earning two findings for one word reads as the check
+  // stuttering rather than as two problems.
+  /^(?:it|this|there|here|everywhere|anywhere|all surfaces|any surface|none|various)$/,
+];
+
+/** Text nobody has written yet, left in a field that is required to be written. */
+// WIP limit(s) names the board feature, not unfinished prose. Exempt only that
+// noun phrase; bare WIP and separate placeholders in the same field still fire.
+const PLACEHOLDER =
+  /(?:^|[^a-z0-9])(?:tbd|tba|todo|fixme|wip(?![\s-]+limits?\b)|xxx|placeholder|n\/a)(?:[^a-z0-9]|$)|\?{3,}|<[^>]{0,40}>/i;
+
+const PART_LABELS = {
+  whereText: 'where',
+  givenText: 'given',
+  whenText: 'when',
+  thenText: 'then',
+};
+
+/**
+ * Inspect one criterion. Returns zero or more findings; never throws.
+ *
+ * @param {{whereText?: string, givenText?: string, whenText?: string, thenText?: string}} criterion
+ * @param {{ordinal?: number, id?: string}} context
+ */
+export function inspectCriterion(criterion, { ordinal = null, id = null } = {}) {
+  const findings = [];
+  const at = { criterionId: id, ordinal };
+
+  const thenText = normalise(criterion?.thenText);
+  if (thenText && UNFALSIFIABLE_THEN.some((pattern) => pattern.test(thenText))) {
+    findings.push({
+      ...at,
+      code: 'unfalsifiable_then',
+      field: 'thenText',
+      text: String(criterion.thenText).trim(),
+      detail:
+        'The observable result asserts nothing a reviewer could disagree with, so this criterion cannot fail. Name what is on the screen or in the response — a value, a count, a state, an exact message.',
+    });
+  }
+
+  const whereText = normalise(criterion?.whereText);
+  if (whereText && UNLOCATED_WHERE.some((pattern) => pattern.test(whereText))) {
+    findings.push({
+      ...at,
+      code: 'unlocated_where',
+      field: 'whereText',
+      text: String(criterion.whereText).trim(),
+      detail:
+        'This names the whole product rather than a place to stand. Give the surface, environment, account, or role the next reviewer should check it on.',
+    });
+  }
+
+  for (const [field, label] of Object.entries(PART_LABELS)) {
+    const raw = criterion?.[field];
+    if (typeof raw === 'string' && raw.trim() && PLACEHOLDER.test(raw)) {
+      findings.push({
+        ...at,
+        code: 'placeholder_text',
+        field,
+        text: raw.trim(),
+        detail: `The ${label} clause still carries a placeholder. A criterion nobody has finished writing cannot be executed by somebody who did not write the code.`,
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Inspect a whole list.
+ *
+ * The `vacuous` flag exists because `clean` is derived from an empty finding
+ * list, and an empty INPUT produces an empty finding list too. A caller that
+ * read `clean` alone would report a card with no criteria at all as a card
+ * whose criteria are in order — the same false green the board audit's
+ * coverage floor exists to stop.
+ *
+ * @param {Array<object>} criteria
+ */
+export function inspectCriteria(criteria) {
+  const list = Array.isArray(criteria) ? criteria : [];
+  const findings = [];
+  for (const [index, criterion] of list.entries()) {
+    findings.push(
+      ...inspectCriterion(criterion, { ordinal: index + 1, id: criterion?.id ?? null })
+    );
+  }
+  return {
+    checked: list.length,
+    vacuous: list.length === 0,
+    clean: list.length > 0 && findings.length === 0,
+    findings,
+  };
+}
+
+/**
+ * The one-line advisory a tool puts beside its own payload, or `undefined` when
+ * there is nothing to say. `undefined` rather than a cheerful "all good" so the
+ * note only ever appears when it carries information.
+ */
+export function describeCriteriaQuality(criteria) {
+  const report = inspectCriteria(criteria);
+  if (report.vacuous || report.clean) return undefined;
+  const codes = [...new Set(report.findings.map((finding) => finding.code))].join(', ');
+  return `${report.findings.length} of ${report.checked} criterion check(s) look unexecutable (${codes}). These are advisory, not a refusal: see \`criteriaQuality.findings\`. A criterion that cannot fail is not a definition of done.`;
+}

package/toolsets/communications.js

@@ -7,6 +7,34 @@
 
 import { z } from 'zod';
 import { md, mdError, table, formatDate } from '../output-formatter.js';
+import { validateApiBridgeRequest } from '../api-bridge.js';
+import { governedWriteArgs, previewMarkdown } from '../governance/governed-args.js';
+
+// The real handlers create a fresh row before enqueueing. A failed enqueue
+// returns non-2xx, which the shared middleware does not cache as completed;
+// its 24h in-progress reservation still blocks same-key retries. Neither
+// handler has durable request/job deduplication after expiry or a new key.
+// Do not turn the old dead routes into outbound side effects until that
+// failed-first-attempt contract is repaired and independently replayed.
+const REPLAY_BLOCKER = 'Live calls and SMS are unavailable through this tool until durable request/job replay is verified. '
+  + 'The API inserts a record before queueing; an enqueue failure can leave a partial result and a 24-hour in-progress key. '
+  + 'A new or expired key can duplicate that work. Nothing was sent; do not bypass this hold with the raw API bridge.';
+
+function previewCommunication(args, heading, request) {
+  try {
+    const validation = validateApiBridgeRequest({ ...args, method: request.method, path: request.path });
+    if (validation.dryRun) {
+      return md(previewMarkdown(heading, {
+        ...validation, wouldSend: false, body: request.body, notes: request.notes, blocked: true, reason: REPLAY_BLOCKER,
+        fix: 'Backend durable request/job replay and independent failed-first-attempt verification are required.',
+        note: 'Approval fields do not lift this safety hold. This tool currently provides previews only.',
+      }, { executionAvailable: false }));
+    }
+    return { ...mdError(`${heading} unavailable`, REPLAY_BLOCKER), isError: true };
+  } catch (err) {
+    return { ...mdError(`${heading} refused`, err.message), isError: true };
+  }
+}
 
 export function register(server, api, AUTH) {
 
@@ -15,52 +43,19 @@ export function register(server, api, AUTH) {
   // -----------------------------------------------------------------------
   server.tool(
     'make_call',
-    'Dial a number via connected telephony provider. Initiates the call and returns a call ID for tracking. Use get_call_transcript after the call to get the AI summary.',
+    'Preview a call request. Live execution is held until durable request/job replay is verified; approval does not bypass the hold.',
     {
       phoneNumber: z.string().describe('Phone number to dial'),
       personId: z.string().optional().describe('Person ID for CRM linking'),
       companyId: z.string().optional().describe('Company ID for CRM linking'),
-      notes: z.string().optional().describe('Pre-call notes or talking points'),
+      notes: z.string().optional().describe('Pre-call notes shown in this preview only; not persisted or sent to the calling API'),
+      ...governedWriteArgs(z),
     },
-    async (args) => {
-      try {
-        const result = await api('POST', '/api/v1/calls', {
-          body: {
-            phoneNumber: args.phoneNumber,
-            personId: args.personId,
-            companyId: args.companyId,
-            notes: args.notes,
-          },
-        });
-
-        const c = result?.data || result || {};
-        let text = `## Call Initiated\n\n`;
-        text += `- **To:** ${args.phoneNumber}\n`;
-        text += `- **Call ID:** ${c.id || c.callId || '\u2014'}\n`;
-        text += `- **Status:** ${c.status || 'Connecting...'}\n`;
-        if (args.personId) text += `- **Linked to person:** ${args.personId}\n`;
-        if (args.notes) text += `\n### Talking Points\n${args.notes}\n`;
-        text += '\nAfter the call, use `get_call_transcript` to get the AI summary.\n';
-
-        // Log action
-        if (args.personId) {
-          await api('POST', '/api/v1/actions', {
-            body: {
-              title: `Call to ${args.phoneNumber}`,
-              type: 'call',
-              personId: args.personId,
-              companyId: args.companyId,
-              status: 'IN_PROGRESS',
-              metadata: { callId: c.id || c.callId, phoneNumber: args.phoneNumber },
-            },
-          }).catch(() => {});
-        }
-
-        return md(text);
-      } catch (err) {
-        return mdError('Call failed', err.message);
-      }
-    }
+    async (args) => previewCommunication(args, 'Call request', {
+      method: 'POST', path: '/api/v1/calling/dial',
+      body: { phoneNumber: args.phoneNumber, personId: args.personId, companyId: args.companyId },
+      notes: args.notes,
+    })
   );
 
   // -----------------------------------------------------------------------
@@ -68,34 +63,17 @@ export function register(server, api, AUTH) {
   // -----------------------------------------------------------------------
   server.tool(
     'send_sms',
-    'Send a text message via connected telephony provider (Twilio/Vonage). Links to CRM for tracking.',
+    'Preview an SMS request. Live execution is held until durable request/job replay is verified; approval does not bypass the hold.',
     {
       to: z.string().describe('Recipient phone number'),
       message: z.string().describe('SMS message text'),
       personId: z.string().optional().describe('Person ID for CRM linking'),
+      ...governedWriteArgs(z),
     },
-    async (args) => {
-      try {
-        const result = await api('POST', '/api/v1/sms', {
-          body: {
-            to: args.to,
-            message: args.message,
-            personId: args.personId,
-          },
-        });
-
-        const r = result?.data || result || {};
-        let text = `## SMS Sent\n\n`;
-        text += `- **To:** ${args.to}\n`;
-        text += `- **Message:** ${args.message}\n`;
-        text += `- **Status:** ${r.status || 'Sent'}\n`;
-        if (r.id) text += `- **ID:** ${r.id}\n`;
-
-        return md(text);
-      } catch (err) {
-        return mdError('SMS failed', err.message);
-      }
-    }
+    async (args) => previewCommunication(args, 'SMS request', {
+      method: 'POST', path: '/api/v1/sms/send',
+      body: { toNumber: args.to, body: args.message, personId: args.personId },
+    })
   );
 
   // -----------------------------------------------------------------------

package/toolsets/spaces.js

@@ -182,8 +182,17 @@ export function describeCount({ found, of, noun, ofNoun, shapeRecognized = true,
     typeof of === 'number'
       ? `${found} of ${of} ${ofNoun ?? noun}`
       : `${found} ${noun}${truncated ? ' (page limit reached — more exist)' : ''}`;
+  // Three DIFFERENT zeros, and they lead a reader to three different actions. The first two
+  // used to be exchanged: a zero measured against rows elsewhere announced the workspace was
+  // empty, and a zero measured against a stated zero denominator announced there was no
+  // denominator. Each contradicted the count printed immediately before it, which is why
+  // neither was caught — the number was right and only the sentence was wrong, and the
+  // sentence is the part that gets acted on.
   if (found === 0 && typeof of === 'number' && of > 0) {
-    return `${base}. The store is reachable and genuinely empty for this workspace — this is a real zero, not a failed read.`;
+    return `${base}. The store does hold ${of} ${ofNoun ?? noun} — none of them match this scope. This is a real zero for this filter, NOT an empty store; widen the scope rather than reporting that there is nothing.`;
+  }
+  if (found === 0 && of === 0) {
+    return `${base}. The denominator was read and it is zero: the store is reachable and holds nothing for this workspace at all. This is an UNWRITTEN store, not evidence that the thing being counted does not happen.`;
   }
   if (found === 0) {
     return `${base}. Zero rows AND no denominator available, so this cannot distinguish an empty workspace from an undeployed store — say so rather than reporting "none".`;