@adrata/adrata-mcp 1.0.1 → 1.0.3

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.',
+  };
+}

package/toolsets/crm.js

@@ -9,6 +9,23 @@ import { z } from 'zod';
 import {
   md, mdError, table, formatEntityTimeline, formatDate,
 } from '../output-formatter.js';
+import {
+  governedWriteArgs, governedWriteNote, isLiveWrite, runGovernedMarkdownWrite,
+  enrichCostLine, COMPANY_ENRICH_COST_SENTENCE, PERSON_ENRICH_COST_SENTENCE,
+} from '../governance/governed-args.js';
+
+/**
+ * The `manage_*` tools are composites: one tool, one `action` argument, reads
+ * and writes side by side. Only the write actions are governed — a `get`,
+ * `list`, `search` or `timeline` must keep working exactly as before, with no
+ * new required arguments and no preview step.
+ *
+ * This is the list of actions that mutate. Everything not in it is a read.
+ */
+const WRITE_ACTIONS = new Set([
+  'create', 'update', 'delete', 'enrich', 'complete',
+  'bulk_delete', 'add_member', 'update_member', 'remove_member',
+]);
 
 export function register(server, api, AUTH) {
 
@@ -17,7 +34,10 @@ export function register(server, api, AUTH) {
   // -----------------------------------------------------------------------
   server.tool(
     'manage_company',
-    'Full CRUD for companies: create, read, update, delete, enrich, and view activity timeline. One tool for all company operations.',
+    'Full CRUD for companies: create, read, update, delete, enrich, and view activity timeline. One tool for all company operations.'
+    + ' Reads (get/search/timeline) run directly. create/update/delete/enrich are governed writes.'
+    + COMPANY_ENRICH_COST_SENTENCE
+    + governedWriteNote('write:companies'),
     {
       action: z.enum(['create', 'get', 'update', 'delete', 'enrich', 'timeline', 'search']).describe('Operation'),
       id: z.string().optional().describe('Company ID (for get/update/delete/enrich/timeline)'),
@@ -28,6 +48,7 @@ export function register(server, api, AUTH) {
       status: z.string().optional().describe('ACTIVE, PROSPECT, CUSTOMER, CHURNED'),
       customFields: z.record(z.unknown()).optional().describe('Custom fields (JSONB merged)'),
       query: z.string().optional().describe('Search query (for search action)'),
+      ...governedWriteArgs(z),
     },
     async (args) => {
       try {
@@ -40,9 +61,20 @@ export function register(server, api, AUTH) {
             if (args.website) body.website = args.website;
             if (args.status) body.status = args.status;
             if (args.customFields) body.customFields = args.customFields;
-            const result = await api('POST', '/api/v1/companies', { body });
-            const c = result?.data || result;
-            return md(`## Company Created\n\n- **Name:** ${c.name || args.name}\n- **ID:** ${c.id || '\u2014'}\n- **Status:** ${c.status || 'PROSPECT'}\n`);
+            return runGovernedMarkdownWrite(
+              api, args,
+              {
+                method: 'POST',
+                path: '/api/v1/companies',
+                body,
+                heading: 'Create Company',
+                preview: { entity: 'company', operation: 'create', fields: Object.keys(body) },
+              },
+              (result) => {
+                const c = result?.data || result || {};
+                return `## Company Created\n\n- **Name:** ${c.name || args.name}\n- **ID:** ${c.id || '\u2014'}\n- **Status:** ${c.status || 'PROSPECT'}\n`;
+              },
+            );
           }
           case 'get': {
             const c = await api('GET', `/api/v1/companies/${args.id}`);
@@ -64,16 +96,46 @@ export function register(server, api, AUTH) {
             if (args.website) body.website = args.website;
             if (args.status) body.status = args.status;
             if (args.customFields) body.customFields = args.customFields;
-            await api('PATCH', `/api/v1/companies/${args.id}`, { body });
-            return md(`## Company Updated\n\nID: ${args.id}\nFields updated: ${Object.keys(body).join(', ')}\n`);
+            return runGovernedMarkdownWrite(
+              api, args,
+              {
+                method: 'PATCH',
+                path: `/api/v1/companies/${args.id}`,
+                body,
+                heading: 'Update Company',
+                preview: { entity: 'company', entityId: args.id, operation: 'update', fields: Object.keys(body) },
+              },
+              () => `## Company Updated\n\nID: ${args.id}\nFields updated: ${Object.keys(body).join(', ')}\n`,
+            );
           }
           case 'delete': {
-            await api('DELETE', `/api/v1/companies/${args.id}`);
-            return md(`## Company Deleted\n\nID: ${args.id}\n`);
+            return runGovernedMarkdownWrite(
+              api, args,
+              {
+                method: 'DELETE',
+                path: `/api/v1/companies/${args.id}`,
+                heading: 'Delete Company',
+                preview: { entity: 'company', entityId: args.id, operation: 'soft-delete' },
+              },
+              () => `## Company Deleted\n\nID: ${args.id}\n`,
+            );
           }
           case 'enrich': {
-            await api('POST', `/api/v1/companies/${args.id}/enrich`);
-            return md(`## Enrichment Triggered\n\nCompany ID: ${args.id}\nData will be available shortly.\n`);
+            return runGovernedMarkdownWrite(
+              api, args,
+              {
+                method: 'POST',
+                path: `/api/v1/companies/${args.id}/enrich`,
+                heading: 'Enrich Company',
+                preview: {
+                  entity: 'company',
+                  entityId: args.id,
+                  operation: 'enrich',
+                  cost: enrichCostLine('company'),
+                },
+              },
+              () => `## Enrichment Triggered\n\nCompany ID: ${args.id}\nCost: ${enrichCostLine('company')}\nData will be available shortly.\n`,
+            );
           }
           case 'timeline': {
             const [company, actions] = await Promise.all([

package/toolsets/prospecting.js

@@ -12,6 +12,89 @@ import {
   formatQualification, formatCompanyResearch, formatPersonResearch,
   formatSpeedrunList, formatNextContacts, table, signalEmoji, formatDate, daysSince,
 } from '../output-formatter.js';
+import {
+  governedWriteArgs, governedWriteNote, isLiveWrite, missingLiveWriteFields,
+  previewMarkdown, enrichCostLine,
+  COMPANY_ENRICH_COST_SENTENCE, PERSON_ENRICH_COST_SENTENCE,
+} from '../governance/governed-args.js';
+import { governedWrite } from '../api-bridge.js';
+
+/**
+ * Run the enrichment leg of a research tool through the governed-write
+ * contract and render the outcome as a Markdown section.
+ *
+ * `research_company` / `research_person` are read tools with one write inside
+ * them: a POST to `/enrich`, which spends real Coresignal credits. They used to
+ * fire that POST on every call with no preview, no audit reason and no
+ * idempotency key — while the IDENTICAL endpoint reached through
+ * `enrich_company` / `enrich_person` in server.js previewed and refused.
+ *
+ * So the reads still run and still produce the report. The enrich is withheld
+ * by default and reported as withheld, with the credit cost named, rather than
+ * being silently skipped — a research report that quietly lost its enrichment
+ * would be worse than one that spent the credits.
+ *
+ * @returns `{ enrichment, section }` — `enrichment` is the live result (or an
+ *          empty object when nothing was executed) so the report renders
+ *          identically either way.
+ */
+async function governedEnrich(api, args, { method, path, kind, subjectId }) {
+  if (isLiveWrite(args)) {
+    const missing = missingLiveWriteFields(args);
+    if (missing.length > 0) {
+      return {
+        enrichment: {},
+        section:
+          `\n---\n\n## Enrichment refused — nothing was spent\n\n` +
+          `A live enrichment write is missing: ${missing.join(', ')}.\n\n` +
+          `- **Would have called:** ${method} ${path}\n` +
+          `- **Cost if executed:** ${enrichCostLine(kind)}\n\n` +
+          `Re-call with \`dryRun:false\` plus ${missing.join(', ')}.\n`,
+      };
+    }
+  }
+
+  try {
+    const outcome = await governedWrite(api, args, {
+      method,
+      path,
+      preview: {
+        entity: kind,
+        entityId: subjectId,
+        operation: 'enrich',
+        cost: enrichCostLine(kind),
+      },
+    });
+
+    if (outcome.dryRun) {
+      return {
+        enrichment: {},
+        section:
+          `\n---\n\n${previewMarkdown('Enrichment', outcome.preview)}` +
+          `\nThe research above was assembled from reads only. No vendor credits were spent.\n`,
+      };
+    }
+
+    return {
+      enrichment: outcome.result || {},
+      section:
+        `\n---\n\n## Enrichment executed\n\n` +
+        `- **Call:** ${method} ${path}\n` +
+        `- **Cost:** ${enrichCostLine(kind)}\n` +
+        `- **Reason:** ${args.reason}\n` +
+        `- **Idempotency key:** ${args.idempotencyKey}\n`,
+    };
+  } catch (err) {
+    return {
+      enrichment: {},
+      section:
+        `\n---\n\n## Enrichment not performed\n\n` +
+        `- **Attempted:** ${method} ${path}\n` +
+        `- **Error:** ${err.message}\n` +
+        `\nThe research above was assembled from reads only.\n`,
+    };
+  }
+}
 
 export function register(server, api, AUTH) {
 
@@ -63,10 +146,14 @@ export function register(server, api, AUTH) {
   // -----------------------------------------------------------------------
   server.tool(
     'research_company',
-    'Deep research report on a company: firmographics, tech stack, funding, news, competitors, intent signals. Orchestrates 5+ API calls into a structured report.',
+    'Deep research report on a company: firmographics, tech stack, funding, news, competitors, intent signals. Orchestrates 5+ API calls into a structured report.'
+    + ' The reads always run. The enrichment leg is a governed write:'
+    + COMPANY_ENRICH_COST_SENTENCE
+    + governedWriteNote('write:companies'),
     {
       companyId: z.string().optional().describe('Company ID'),
       name: z.string().optional().describe('Company name to search'),
+      ...governedWriteArgs(z),
     },
     async (args) => {
       try {
@@ -86,14 +173,22 @@ export function register(server, api, AUTH) {
           return mdError('Provide companyId or name');
         }
 
-        // Parallel enrichment
-        const [enrichment, signals, competitors] = await Promise.all([
-          api('POST', `/api/v1/companies/${companyId}/enrich`).catch(() => ({})),
+        // Reads run unconditionally. The enrich POST is a governed write and
+        // previews by default, so a research call costs zero vendor credits
+        // unless the caller explicitly authorised the spend.
+        const [signals, competitors] = await Promise.all([
           api('GET', '/api/v1/intent-signals', { params: { companyId } }).catch(() => ({ data: [] })),
           api('GET', '/api/v1/competitors', { params: { companyId } }).catch(() => ({ data: [] })),
         ]);
 
-        return md(formatCompanyResearch(company, enrichment, signals, competitors));
+        const { enrichment, section } = await governedEnrich(api, args, {
+          method: 'POST',
+          path: `/api/v1/companies/${companyId}/enrich`,
+          kind: 'company',
+          subjectId: companyId,
+        });
+
+        return md(formatCompanyResearch(company, enrichment, signals, competitors) + section);
       } catch (err) {
         return mdError('Research failed', err.message);
       }
@@ -105,11 +200,15 @@ export function register(server, api, AUTH) {
   // -----------------------------------------------------------------------
   server.tool(
     'research_person',
-    'Deep research on a person: professional profile, communication preferences, intro paths, recent activity. Orchestrates 3+ API calls.',
+    'Deep research on a person: professional profile, communication preferences, intro paths, recent activity. Orchestrates 3+ API calls.'
+    + ' The reads always run. The enrichment leg is a governed write:'
+    + PERSON_ENRICH_COST_SENTENCE
+    + governedWriteNote('write:people'),
     {
       personId: z.string().optional().describe('Person ID'),
       name: z.string().optional().describe('Person name to search'),
       email: z.string().optional().describe('Email to search by'),
+      ...governedWriteArgs(z),
     },
     async (args) => {
       try {
@@ -132,13 +231,20 @@ export function register(server, api, AUTH) {
           return mdError('Provide personId, name, or email');
         }
 
-        // Parallel: enrichment + actions
-        const [enrichment, actions] = await Promise.all([
-          api('POST', `/api/v1/people/${personId}/enrich`).catch(() => ({})),
-          api('GET', '/api/v1/actions', { params: { personId, limit: 10, page: 1 } }).catch(() => ({ data: [] })),
-        ]);
+        // Reads run unconditionally; the enrich POST is governed and previews
+        // by default. A Coresignal collect is 20 credits per person, so an
+        // ungoverned research call was a per-invocation vendor charge.
+        const actions = await api('GET', '/api/v1/actions', { params: { personId, limit: 10, page: 1 } })
+          .catch(() => ({ data: [] }));
+
+        const { enrichment, section } = await governedEnrich(api, args, {
+          method: 'POST',
+          path: `/api/v1/people/${personId}/enrich`,
+          kind: 'person',
+          subjectId: personId,
+        });
 
-        return md(formatPersonResearch(person, enrichment, actions));
+        return md(formatPersonResearch(person, enrichment, actions) + section);
       } catch (err) {
         return mdError('Research failed', err.message);
       }