@adrata/adrata-mcp 1.0.3 → 1.0.7

package/server.js

@@ -31,6 +31,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { readFileSync } from 'node:fs';
 import {
   authenticate,
   reauthenticate,
@@ -41,6 +42,7 @@ import {
 import { TIERS } from './access/tiers.js';
 import { findCompany, findPerson } from './tools/free-search.js';
 import { applySecurityLayer } from './security.js';
+import { describeEdgeBlock } from './edge-block.js';
 import { registerMemoryTools, wrapWithEventLogging, registerProfileResource } from './tools/memory.js';
 import { registerBillingTools } from './tools/billing.js';
 import { registerMorningBrief } from './tools/morning-brief.js';
@@ -50,13 +52,15 @@ import { connectWorkspace, disconnectWorkspace, getConnectionStatus, getValidTok
 import { registerEnterpriseTools } from './tools/enterprise-tools.js';
 import { registerEmailTools } from './tools/email-tools.js';
 import { registerWorkBoardTools } from './tools/work-board-tools.js';
+import { registerSourceControlTools } from './tools/source-control/connection-tools.js';
 import { registerRoadmapTools } from './tools/roadmap-tools.js';
 import { registerPaperTools } from './tools/paper-tools.js';
 import { register as registerAlwaysLoadedTools } from './toolsets/revenue/always-loaded.js';
 import { register as registerExtensibilityTools } from './toolsets/extensibility.js';
 import { registerSpaceTools } from './toolsets/spaces.js';
+import { composeCompetitorIntel, composeCustomerSignals } from './toolsets/revenue/competitive-coverage.js';
 import { getDemoAvailability, scheduleDemo, scheduleMeeting } from './tools/scheduling.js';
-import { registerAnalytics } from './analytics.js';
+import { registerAnalytics, wrapWithAnalytics } from './analytics.js';
 import {
   apiBridgeCatalog,
   buildMutationHeaders,
@@ -131,7 +135,7 @@ async function api(method, path, { params, body, headers: extraHeaders } = {}) {
   const auth = currentAuth();
   assertOAuthIssuerMatchesTarget(auth, API_BASE);
   let currentToken = auth.token;
-  if (auth.source === 'stored') {
+  if (auth.source === 'stored' || auth.source === 'stored_pool') {
     let freshToken;
     try {
       freshToken = await getValidToken(API_BASE);
@@ -177,7 +181,7 @@ async function api(method, path, { params, body, headers: extraHeaders } = {}) {
   };
 
   let res = await request(currentToken);
-  if (res.status === 401 && auth.source === 'stored') {
+  if (res.status === 401 && (auth.source === 'stored' || auth.source === 'stored_pool')) {
     let refreshedToken;
     try {
       refreshedToken = await getValidToken(API_BASE, { forceRefresh: true });
@@ -214,6 +218,18 @@ async function api(method, path, { params, body, headers: extraHeaders } = {}) {
   try { data = JSON.parse(text); } catch { data = { raw: text }; }
 
   if (!res.ok) {
+    // An HTML body cannot have come from the API — every AppError serialises as
+    // JSON — so it means the request was refused in front of us. Saying so is
+    // the whole point: a bare 403 is indistinguishable from insufficient_scope,
+    // and reading it as a token problem is what starts a needless reconnect.
+    const edge = describeEdgeBlock({
+      status: res.status,
+      text,
+      method,
+      path,
+      requestBody: body,
+    });
+    if (edge) throw new Error(edge);
     throw new Error(`API ${method} ${path} → ${res.status}: ${JSON.stringify(data).slice(0, 200)}`);
   }
   return data;
@@ -297,8 +313,12 @@ const moneyWrite = {
  * to start, which is the exact failure this whole surface keeps producing.
  */
 const SERVER_NAME = process.env.ADRATA_MCP_SERVER_NAME?.trim() || '@adrata/adrata-mcp';
+const PACKAGE_VERSION = JSON.parse(
+  readFileSync(new URL('./package.json', import.meta.url), 'utf8')
+).version;
 
-const server = new McpServer({ name: SERVER_NAME, version: '1.0.0' });
+function createMcpServer() {
+const server = new McpServer({ name: SERVER_NAME, version: PACKAGE_VERSION });
 
 // ---------------------------------------------------------------------------
 // Tier-gating wrapper
@@ -367,6 +387,26 @@ wrapWithEventLogging(server, api, AUTH);
 // Must be applied AFTER tier-gating and event logging wrappers above.
 applySecurityLayer(server, currentAuth, api);
 
+// ---------------------------------------------------------------------------
+// Analytics wrapper
+// ---------------------------------------------------------------------------
+// MUST be installed here — after the wrappers above, and BEFORE the first
+// server.tool(...) call below. It monkey-patches `server.tool`, so it can only
+// instrument FUTURE registrations. It used to be installed from
+// registerAnalytics() ~1975 lines further down, which put 227 of the 254 tools
+// this server exposes ahead of it: trackToolInvocation and recordSessionTool
+// could not fire for 89% of the surface, and get_mcp_analytics reported
+// tool_invocations.total: 0 as though it were a measurement.
+//
+// The cost is deliberate and worth naming: every counted invocation now also
+// fire-and-forget POSTs a `tool_invocation` event, roughly doubling the writes
+// on /api/v1/mcp/events (the event-logging wrapper above already posts one per
+// call for the whole surface). ADRATA_TELEMETRY=off disables both.
+//
+// registerAnalytics() still calls this; the wrapper is idempotent, so the later
+// call is a no-op rather than a second layer.
+wrapWithAnalytics(server, api, currentAuth, checkToolAccess);
+
 // ===== WORKSPACE CONNECTION: OAuth 2.0 (available at all tiers) =====
 
 server.tool('connect_workspace',
@@ -381,7 +421,18 @@ server.tool('connect_workspace',
       AUTH = reauthenticate();
       return ok(result);
     } catch (err) {
-      return ok({ error: true, message: err.message, hint: 'Make sure your browser is accessible and try again.' });
+      // `invalid_scope` is not a browser problem, and saying it is costs real
+      // time: it means the authorization server rejected one of the scopes we
+      // asked for, which in practice means the deployed API is running behind
+      // this client. The whole request is refused, so read-only will still
+      // connect — that asymmetry is the tell.
+      const hint = /invalid_scope/.test(err.message ?? '')
+        ? 'The API rejected a requested scope, so it granted nothing — this is NOT a browser problem. '
+          + 'The deployed API is probably behind this client. Compare them: '
+          + 'curl -s ' + API_BASE + '/health | jq -r .build_sha  '
+          + 'Read-only connect_workspace() should still work; use it to keep going.'
+        : 'Make sure your browser is accessible and try again.';
+      return ok({ error: true, message: err.message, hint });
     }
   });
 
@@ -412,7 +463,7 @@ server.tool('workspace_status',
     // answer from a diagnostic: it sends someone to reconnect a connection that
     // was never the problem, and it is the tool a connect flow tells you to run
     // to confirm the setup worked.
-    const usingStoredSession = AUTH.source === 'stored';
+    const usingStoredSession = AUTH.source === 'stored' || AUTH.source === 'stored_pool';
     const stored = await getConnectionStatus(API_BASE);
 
     // AUTH.workspaceId is only populated when the workspace was pinned via env
@@ -452,8 +503,11 @@ server.tool('workspace_status',
       return ok({
         ...stored,
         tier: stored.connected ? AUTH.tier : TIERS.FREE,
-        credential: 'stored OAuth session (~/.adrata/tokens.json)',
+        credential: AUTH.source === 'stored_pool'
+          ? `dedicated OAuth session for named identity pool ${AUTH.identityPool}`
+          : 'stored OAuth session (~/.adrata/tokens.json)',
         authSource: AUTH.source,
+        identityPool: AUTH.identityPool || null,
         apiBase: API_BASE,
         workspaceId,
         workspaceName,
@@ -521,7 +575,7 @@ function assertProductCapability(capability, requested) {
 }
 
 async function resolveExactCapability(reference) {
-  const response = await api('GET', '/api/v1/ai/crm-tools/capabilities/describe', {
+  const response = await api('GET', '/api/v1/ai-crm-tools/capabilities/describe', {
     params: { ref: reference },
   });
   return assertProductCapability(response?.capability ?? response?.data?.capability, reference);
@@ -539,7 +593,7 @@ server.tool('search_capabilities',
     if (PRODUCT_NAMESPACE && requestedNamespace && requestedNamespace !== PRODUCT_NAMESPACE) {
       throw new Error(`${SERVER_NAME} search is fixed to the ${PRODUCT_NAMESPACE} namespace.`);
     }
-    return ok(await api('GET', '/api/v1/ai/crm-tools/capabilities/search', {
+    return ok(await api('GET', '/api/v1/ai-crm-tools/capabilities/search', {
       params: {
         q: args.query,
         namespace: PRODUCT_NAMESPACE || requestedNamespace,
@@ -581,7 +635,7 @@ server.tool('run_capability',
     if (args.idempotencyKey) headers['idempotency-key'] = args.idempotencyKey;
     if (args.reason) headers['x-adrata-reason'] = args.reason;
     if (args.confirmSpend === true) headers['x-adrata-approved'] = 'true';
-    return ok(await api('POST', '/api/v1/ai/crm-tools/execute', { body, headers }));
+    return ok(await api('POST', '/api/v1/ai-crm-tools/execute', { body, headers }));
   });
 
 server.tool('adrata_api_catalog',
@@ -1756,7 +1810,7 @@ server.tool('get_intent_signals', 'Get buying intent signals for a company.',
 // are workspace-scoped from the token; filter by subject (a company or person),
 // source, signal type, or minimum score, and page with the returned cursor.
 server.tool('list_customer_signals',
-  'List first-party customer signals (the store live plays fire from) for the workspace, or scope to one company/person via subjectType + subjectId. Distinct from get_intent_signals (third-party intent).',
+  'List first-party customer signals (the store live plays fire from) for the workspace, or scope to one company/person via subjectType + subjectId. Distinct from get_intent_signals (third-party intent). Always relay the returned `coverage`: an empty result is checked against the unfiltered workspace, so a real zero is distinguished from a store nothing has ever written to.',
   {
     subjectType: z.enum(['company', 'person']).optional().describe('Scope to a subject kind; pair with subjectId'),
     subjectId: z.string().optional().describe('Company or person ID to scope signals to'),
@@ -1768,11 +1822,31 @@ server.tool('list_customer_signals',
     limit: z.number().optional().describe('Page size (default 50, max 500)'),
     cursor: z.string().optional().describe('Opaque cursor from a previous page'),
   },
-  async (a) => ok(await api('GET', '/api/v1/customer-signals', { params: {
-    subjectType: a.subjectType, subjectId: a.subjectId, source: a.source,
-    signalType: a.signalType, minScore: a.minScore, since: a.since,
-    until: a.until, limit: a.limit || 50, cursor: a.cursor,
-  } })));
+  async (a) => {
+    const filtersApplied = {
+      subjectType: a.subjectType, subjectId: a.subjectId, source: a.source,
+      signalType: a.signalType, minScore: a.minScore, since: a.since, until: a.until,
+    };
+    const payload = await api('GET', '/api/v1/customer-signals', { params: {
+      ...filtersApplied, limit: a.limit || 50, cursor: a.cursor,
+    } });
+
+    // The probe is spent ONLY on the ambiguous case. Rows returned means the store is
+    // demonstrably written to and the count speaks for itself; an empty array is the reading a
+    // seller cannot interpret, and one extra request is what separates "no signals match these
+    // filters" from "nothing has ever been ingested".
+    const empty = Array.isArray(payload?.items) ? payload.items.length === 0 : undefined;
+    let workspaceProbePayload;
+    if (empty === true) {
+      try {
+        workspaceProbePayload = await api('GET', '/api/v1/customer-signals', { params: { limit: 1 } });
+      } catch {
+        workspaceProbePayload = null;
+      }
+    }
+
+    return ok(composeCustomerSignals({ payload, filtersApplied, workspaceProbePayload }));
+  });
 
 server.tool('get_deal_authority', 'Get authority mapping and stakeholder analysis for a deal.',
   { opportunityId: z.string() },
@@ -1781,9 +1855,39 @@ server.tool('get_deal_authority', 'Get authority mapping and stakeholder analysi
     params: { opportunityId: a.opportunityId },
   })));
 
-server.tool('get_competitor_intel', 'Get competitive intelligence for a company.',
+server.tool('get_competitor_intel',
+  'Competitive intelligence for ONE company: the competitor mentions attributed to that account, plus the workspace-wide competitor definitions they are scored against. Always relay the returned `coverage` — it says which half is company-scoped and which is workspace-wide, and states whether a zero is a real zero or an unconfigured store. `/api/v1/competitors` is a workspace configuration list and takes no company filter; the company-scoped evidence lives at `/api/v1/competitors/mentions?companyId=`.',
   { companyId: z.string() },
-  async (a) => ok(await api('GET', `/api/v1/competitors`, { params: { companyId: a.companyId } })));
+  async (a) => {
+    // The definition list is workspace-scoped by construction. Sending `companyId` to it — as
+    // this tool used to — got the parameter silently discarded and returned the same answer for
+    // every company. The two reads are separate because their SCOPES are separate.
+    const definitionsPayload = await api('GET', '/api/v1/competitors');
+
+    let mentionsPayload;
+    let workspaceMentionsPayload;
+    let mentionsUnavailable = false;
+    try {
+      mentionsPayload = await api('GET', '/api/v1/competitors/mentions', {
+        params: { companyId: a.companyId, limit: 50 },
+      });
+      // The denominator. One extra cheap request buys the difference between "this account is
+      // quiet" and "nothing has ever been scanned".
+      workspaceMentionsPayload = await api('GET', '/api/v1/competitors/mentions', {
+        params: { limit: 1 },
+      });
+    } catch {
+      mentionsUnavailable = true;
+    }
+
+    return ok(composeCompetitorIntel({
+      companyId: a.companyId,
+      definitionsPayload,
+      mentionsPayload,
+      workspaceMentionsPayload,
+      mentionsUnavailable,
+    }));
+  });
 
 // ===== ANALYTICS =====
 
@@ -2266,6 +2370,8 @@ registerWorkBoardTools(server, {
   getGrantedScope: () => loadTokens()?.scope,
 });
 
+registerSourceControlTools(server, { z, api, ok });
+
 // The containers above the cards, and the "add this to the roadmap" verb
 // (company/decisions/2026-08-06-spoq-roadmap-sync.md).
 registerRoadmapTools(server, {
@@ -2323,7 +2429,7 @@ server.tool('schedule_meeting',
 // Tracks tool invocations, search queries, tier gates, conversions, sessions.
 // Builds on top of existing event logging — adds classification and dashboards.
 // ADRATA_TELEMETRY=off disables all tracking. PII is hashed before storage.
-registerAnalytics(server, { z, api, auth: AUTH, ok, checkToolAccess });
+registerAnalytics(server, { z, api, auth: currentAuth, ok, checkToolAccess });
 
 // ===== COMPOSITE TOOLSETS =====
 // 42 composite tools organized into 7 toolsets with dynamic discovery.
@@ -2344,6 +2450,9 @@ registerExtensibilityTools(server, api, AUTH);
 // Service" got nothing, while the app answered it fine.
 registerSpaceTools(server, { z, api, ok });
 
+return server;
+}
+
 // ---------------------------------------------------------------------------
 // Start
 // ---------------------------------------------------------------------------
@@ -2353,11 +2462,12 @@ const TRANSPORT_MODE = (process.env.ADRATA_MCP_TRANSPORT || 'stdio').toLowerCase
 if (TRANSPORT_MODE === 'http' || TRANSPORT_MODE === 'sse') {
   // Streamable HTTP transport — single POST /mcp endpoint that can upgrade to SSE
   const { startHttpTransport } = await import('./transport-http.js');
-  await startHttpTransport(server, {
+  await startHttpTransport(createMcpServer, {
     runWithAuthContext,
   });
 } else {
   // Default: stdio transport (backward compatible)
+  const server = createMcpServer();
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }

package/server.json

@@ -3,7 +3,7 @@
   "name": "com.adrata/adrata-mcp",
   "description": "Adrata revenue-intelligence MCP server: companies, people, opportunities, actions, buyer groups, enrichment, email, and workspace operations for AI agents.",
   "status": "active",
-  "version": "1.0.0",
+  "version": "1.0.7",
   "websiteUrl": "https://adrata.com/developers",
   "repository": {
     "url": "https://github.com/adrata/adrata",
@@ -15,7 +15,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@adrata/adrata-mcp",
-      "version": "1.0.0",
+      "version": "1.0.7",
       "transport": {
         "type": "stdio"
       },
@@ -31,6 +31,18 @@
           "description": "Enterprise OAuth 2.1 access token, audience-bound to the Adrata MCP resource (RFC 8707).",
           "isRequired": false,
           "isSecret": true
+        },
+        {
+          "name": "ADRATA_MCP_IDENTITY_POOL",
+          "description": "Optional named worker identity (for example qa1 or qa2). Named pools fail closed and only use their dedicated stored OAuth session.",
+          "isRequired": false,
+          "isSecret": false
+        },
+        {
+          "name": "ADRATA_MCP_CONFIG_DIR",
+          "description": "OAuth storage directory. Required and non-default when ADRATA_MCP_IDENTITY_POOL is set.",
+          "isRequired": false,
+          "isSecret": false
         }
       ]
     }

package/skills/qa-the-card/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: qa-the-card
+description: Deeply verify a Starfield card in Staging QA1 or Staging QA2, fix defects and rerun evidence until clean, then leave an auditable AI-to-human handoff without claiming deployment. Use when asked to QA, review, verify, sign off, or clear cards from a QA column.
+---
+
+# QA the card
+
+QA is an engineering pass, not a documentation pass. Reproduce every acceptance
+claim, attack the implementation beyond the happy path, fix defects in scope,
+and repeat until the card is genuinely ready for the next accountable reviewer.
+
+The workflow semantics are fixed by
+`company/decisions/2026-08-29-two-gate-ai-qa-human-production.md`; the required
+evidence loop is fixed by
+`company/decisions/2026-08-29-recorded-staging-qa-standard.md`. This skill is
+their operating procedure.
+
+## Establish the real queue
+
+1. Read every active board or the all-boards roll-up before announcing a count.
+   A card's `product` may differ from the board holding it, so inspect both the
+   Adrata board and Adrata-labelled cards on another board. Re-read the queue
+   during a long session and at every deployment checkpoint because new cards
+   can arrive while QA is running. Report the delta, not only the new total.
+2. Limit mutations to the QA scope the user named. Read each card, its full
+   stage history, comments, acceptance criteria, flag, linked pull request, and
+   exact-SHA delivery evidence before testing it.
+3. Do not infer missing history from a sparse screen. Confirm the transition
+   rows through the governed API. A card created directly in an old QA column
+   may honestly have only one transition.
+4. Audit the criteria themselves. Each must describe an observable outcome and
+   be executable at the current gate. Add or correct missing coverage before
+   calling the card clean; never turn a vague criterion green by interpreting it
+   generously.
+5. Missing independent QA evidence by itself is expected at QA1 entry and never
+   justifies a bounce. Do not report a vague “missing evidence path”: name the
+   allegedly missing product route, fixture, credential, artifact location, or
+   current-dwell QA receipt, and resolve relative artifact paths against the
+   owning worktree or durable location before declaring them absent. If the
+   executable prerequisite truly is missing, keep the card in QA and run the
+   same-card fix-and-retest loop; if only the independent receipt is missing,
+   start the pass.
+
+## Preserve independent gates
+
+- QA1 and QA2 are separate passes over separate column-history dwells. A prior
+  checkbox or receipt is evidence to inspect, not a substitute for rerunning it.
+- An agent's QA2 credential must differ from the criterion author and the agent
+  credential whose clean receipt opened QA1. Never impersonate a human to bypass
+  this rule. A human may perform the final acceptance even when they own or
+  authored the card.
+- **Take that credential from a QA lane, and take a different one per
+  worktree.** Staging seeds twenty-four of them — `qa-lane-1@adrata.test`
+  through `qa-lane-24@adrata.test`, lanes 1-18 `admin` and 19-24 `seller`.
+  There are deliberately more lanes than the fleet can drive, so a tester
+  never queues behind an identity:
+
+  ```bash
+  node scripts/qa-staging-lane.mjs --list            # every lane and its role
+  node scripts/qa-staging-lane.mjs <lane> --write-env  # this worktree's tests/e2e/.env
+  ```
+
+  The rule above is unsatisfiable with one shared login, and the failure is
+  silent rather than loud: every recording is the same actor, so cards get
+  honestly CLAIMED and none can be legitimately VERIFIED. Sharing a lane
+  between two live agents is the same defect wearing a different hat — they
+  share a session, a workspace switch and a chat history, so one lane's
+  navigation lands in another lane's recording. Record the lane on the receipt,
+  so "a different credential" is a checkable claim rather than an assertion.
+  The accounts come from the non-production boot seed
+  (`code/api/crates/schema/src/seeds/non_prod.rs`) and exist only on staging
+  and local; they cannot be created in production.
+- For non-trivial QA2 work, use at least one independent adversarial reviewer
+  when subagents are authorized and available. Parallelize separable surfaces
+  such as UI, backend/security, and migration/deployment behavior. Give each
+  reviewer a bounded target and avoid concurrent edits to the same files.
+- Multiple reviewers may find and challenge defects, but they do not assemble a
+  synthetic gate from partial identities. One eligible second-agent credential
+  must rerun or confirm every current criterion so the final QA2 receipt is
+  coherent and the badge can be derived honestly.
+- Stagger expensive Rust builds on the shared Mac. More concurrent compilers can
+  make verification slower and can exhaust disk; an independent final result
+  must use the reviewer's own target artifacts and show any new test by name.
+
+## Run the fix-and-retest loop
+
+For every criterion:
+
+1. Write down the observable, the environment, and the strongest practical way
+   to falsify it. Source inspection alone is not a pass.
+2. Reproduce the behavior before changing code when the deployed failure is
+   observable. Preserve the failing request, console output, screenshot, video,
+   trace, or exact database/API result.
+3. Exercise the happy path, boundary conditions, failure states, authorization
+   boundaries, retries/idempotency, and a realistic regression path. For a
+   migration, prove both representative old state and transactional rerun. For
+   a deployment, prove the exact deployed SHA and behavior during replacement,
+   not only the final steady state.
+4. If anything fails, fix it within the same card when passing the card's
+   existing acceptance outcome necessarily requires that fix. Add the narrowest
+   regression test that would have caught it, rerun the focused suite, then rerun
+   the broader affected contracts. Do not merely describe a defect and stop
+   while a safe in-scope fix remains.
+5. Repeat adversarial review after the fix. A first green rerun is evidence, not
+   automatic sign-off.
+
+Keep the card in its QA column throughout this loop unless the user or board
+policy explicitly asks for a bounce. Never hide an incomplete pass by moving it
+forward.
+
+## Visual QA requires visual evidence
+
+Use Playwright for every user-facing change. A DOM assertion or source review
+does not establish that the screen is visually correct.
+
+- Record a WebM video of the real interaction and take screenshots of the states
+  that decide the criterion. Enable action annotations or chapter markers when
+  they make the recording easier for the human reviewer to follow.
+- Measure duration, MIME type, size, and hash from the finalized media file
+  before upload. Never declare the interaction stopwatch as the video duration:
+  recorder startup/finalization can make those values differ. Reject the
+  receipt when a checkpoint falls outside the measured media duration or the
+  declared metadata does not match the finalized file.
+- In QA2, inspect the QA1 recording as prior evidence, then record a new QA2
+  replay. Keep both attached to their exact gate and column-history dwell. Never
+  reuse, replace, or relabel the QA1 media as QA2 evidence.
+- Give each concurrent QA agent an isolated synthetic account or an explicit
+  exclusive lease on the shared account. For stateful journeys, create and read
+  back a unique server resource (for example, a conversation id) and address it
+  directly; never rely on the newest active resource. An unexpected request,
+  turn, or mutation from outside the recorded browser makes the run ambiguous
+  and therefore a failure, not evidence.
+- Inspect the rendered screenshots yourself at the target viewport. Check
+  alignment, clipping, wrapping, whitespace, stacking, focus, disabled/loading
+  behavior, and whether badges and controls line up with neighboring content.
+- Capture the browser console, page errors, failed requests, and the relevant
+  network responses. Distinguish an expected simulated failure from an
+  unexpected product error.
+- Cover normal, empty, loading, error, and recovery states when they exist. Test
+  both hosted Starfield and the packaged desktop app when both ship the changed
+  renderer.
+- When governed QA evidence is available, attach the screenshot/video to the
+  card's exact open QA dwell with the environment and build SHA. Until that
+  surface is deployed, retain the files and record their paths or durable run
+  links without pretending they were attached.
+- Reopen both uploaded gate recordings before handoff. Prove each fresh
+  short-lived URL loads and that each video can play, seek, and enter
+  fullscreen; an upload response alone is not a media pass.
+- A staging QA lane and the canonical board may intentionally use separate data
+  planes. Do not copy a production card into staging, reuse the builder's browser
+  credential, or put an OAuth bearer or presigned media URL in the transcript.
+  Run `npm run --silent qa:canonical-card-review -- <card-id>` under the fresh
+  reviewer's named `ADRATA_MCP_IDENTITY_POOL` and dedicated
+  `ADRATA_MCP_CONFIG_DIR`. It opens the exact deployed product bundle through a
+  one-use, read-only loopback session: upstream reads keep the QA OAuth identity,
+  writes fail locally, and private media capabilities remain process-private.
+  Record the returned session fingerprint and the deployed app build in the
+  playback evidence, then close the bridge.
+
+## Manage cards as outcomes, not bug counters
+
+- A defect required to satisfy the current card stays on that card. Fix it and
+  retest there; do not create a new Up Next card merely because QA found it.
+- Create a separate card only for an independently releasable outcome outside
+  the current acceptance scope. Search the whole board first. If a likely
+  duplicate already exists, identify the pair and let a human collapse it; do
+  not delete or merge cards on your own judgement.
+- A new card needs a concrete title, reproduction/context, first-class
+  acceptance criteria, and no invented assignee. Move it through the ordinary
+  workflow instead of placing it directly in a protected QA or done column.
+- Keep findings, fixes, and evidence on the canonical card. Do not rewrite the
+  original body to make the request match what was discovered.
+
+## Promotion and the human handoff
+
+Local verification comes before CI. Keep incomplete pull requests draft, seek
+an independent code review for consequential fixes, make the PR ready only
+after local evidence is clean, and merge only after the applicable protected
+checks pass. Verify the cumulative staging deployment rather than treating a
+merge as deployment proof.
+
+When QA2 is clean:
+
+1. Tick only criteria actually executed in the current dwell, with concise
+   evidence naming commands or run links, exact counts, environment, build SHA,
+   and any material caveat.
+2. Add one concise final card comment summarizing the fixes and the last clean
+   rerun. Comments preserve the audit trail; they never replace the fix.
+3. Confirm the derived `Ready for review` badge appears and aligns correctly in
+   both the card and detail view. Never edit an emoji into the title; a derived
+   badge disappears correctly after a bounce.
+4. Leave the card in Staging QA2. An agent must not move it to Ready to Ship or
+   Production. Ready to Ship is the human's acceptance of both AI receipts.
+5. Treat Production as a separate claim: the approved release is live, its exact
+   delivery evidence is known, and release notes may now include it. A board
+   column alone is not exact-SHA proof.
+
+If the badge does not appear, identity is ambiguous, evidence belongs to an old
+dwell, a criterion is open, CI is incomplete, or the deployed behavior differs,
+the card is not ready. Fix the cause and rerun; never use an override to make the
+handoff look complete.
+
+## Report while working
+
+Keep the human informed with concrete state: current QA2 count, cards clean,
+cards in fix/retest, newly found defects, and deployment/desktop readiness. Do
+not announce that the app is ready to inspect until the required API migration,
+hosted build, packaged desktop version, relaunch, and final Playwright video pass
+are actually complete.
+
+At handoff report:
+
+- card and current column;
+- criteria executed and the final evidence;
+- defects found, fixes made, and independent review result;
+- exact staging/production/desktop build state;
+- whether the `Ready for review` badge is visible;
+- any genuinely separate follow-up card.

package/skills/ship-the-card/SKILL.md

@@ -9,6 +9,10 @@ This is the loop a coding agent actually runs: read a card, do the work, move
 the card. The part people get wrong is the last step — work that lands with the
 board untouched is work nobody can see.
 
+If the card is already in Staging QA1 or Staging QA2, use `qa-the-card` instead.
+QA is a fresh independent verification and fix-and-retest loop, not the ordinary
+implementation-and-submit path below.
+
 ## Pick up
 
 1. `list_my_work_items` — **start here.** It answers "what is mine", across every
@@ -118,15 +122,15 @@ number, a run link, the caveat that makes it honest. An untouched checkbox says
 nothing about whether the check passed; it says nobody has been near it, which
 is the same thing an abandoned card says.
 
-Ticking from a build column records `claimed`, not `verified`, and so does
-ticking your own card at a QA gate. That is the rule, not a refusal: the grade
-is derived from where the card was standing and who you are, and the engineer
-who built the thing cannot verify it. Tick anyway — `claimed` is a real state
-that says the work is believed done, and it is what QA reads before deciding
-what to re-run. What you must not do is tick a box you did not execute to make
-the count look better: the QA gate reads `verified`, so it stops either way, and
-all the false tick achieves is turning an honest "shipped with two open" into a
-claim somebody later believes.
+Ticking from a build column records `claimed`, not `verified`. At a QA gate, an
+authenticated human may verify even when they own the card or authored the
+criterion: the human is the accountable exception when one person operates the
+workspace. An agent verifies only when its credential differs from the
+criterion author, and QA2 requires a different agent credential from the one
+whose clean receipt opened QA1. One AI cannot certify both gates. Tick anyway
+when the result is `claimed` — it is a real state that says the work is believed
+done and tells QA what to rerun. Never tick a box you did not execute merely to
+improve the count.
 
 If a tick turns out to be wrong, `unsatisfy_work_item_acceptance_criterion`
 takes it off. It clears the note with it, so if the evidence is worth keeping,
@@ -151,11 +155,11 @@ The tool refuses placeholder reasons — "moved", "update", "Moved to another
 column" — on purpose: a history full of those looks like an audit trail, so
 nobody goes looking for the real answer, which is worse than no history at all.
 
-**Do not move a card into the terminal column** — `Production` on a default
-board, or whatever the last column is called on this one. That is a human's call:
-the person who reported it, or the reviewer. An agent marking its own work
-complete is the one move on this board that nobody can trust. Stop at the review
-or QA column and say it is ready.
+**Do not move a card into `Ready to Ship` or `Production`.** Ready to Ship is the
+human's final acceptance of both AI QA receipts. Production is a separate,
+stronger claim that the release is actually live and eligible for release
+notes. In QA1, an independent agent may advance a clean card to QA2; in QA2,
+document the second pass and leave the `🏁 Ready for review` card for the human reviewer.
 
 ## Writes
 

package/tool-annotations.js

@@ -239,15 +239,22 @@ const IDEMPOTENT_WRITES = new Set([
   // Every Starfield board write is governed by a required idempotency key.
   // Retrying the same key replays; it never appends a second transition,
   // comment, criterion, or card.
-  'move_work_item', 'set_work_board_column_wip_limit', 'set_work_item_tag', 'set_work_item_kind',
+  'move_work_item', 'transfer_work_item_between_boards', 'set_work_board_column_wip_limit', 'set_work_item_tag', 'set_work_item_kind',
   'create_work_item', 'comment_on_work_item', 'flag_work_item',
   'add_work_item_acceptance_criterion',
   // Ticking and un-ticking are both genuinely idempotent, and for different
   // reasons worth keeping straight: a repeat tick is a no-op because the server
   // only writes the ticker, column and note where they were empty, and a repeat
   // un-tick clears columns that are already NULL. Neither can compound.
-  'satisfy_work_item_acceptance_criterion',
+  'satisfy_work_item_acceptance_criterion', 'record_work_item_criterion_engineering_proof',
   'unsatisfy_work_item_acceptance_criterion',
+  'claim_work_item_qa_pass',
+  'claim_next_work_item_qa_pass',
+  'heartbeat_work_item_qa_pass',
+  'attach_work_item_qa_evidence',
+  'verify_work_item_qa_evidence_playback',
+  'record_work_item_qa_failure_and_release',
+  'requeue_work_item_qa_after_fix',
 ]);
 
 // Non-read tools that create new state / have side effects each call.
@@ -261,6 +268,7 @@ const NON_IDEMPOTENT_WRITES = new Set([
   'warmup_email', 'schedule_demo', 'schedule_meeting', 'connect_workspace',
   'enable_toolset', 'track_conversion', 'log_interaction', 'test_webhook',
   'replay_webhook_delivery', 'upgrade_account',
+  'release_work_item_qa_pass',
 ]);
 
 // Tools that reach beyond the workspace (external enrichment, web, providers).