@adrata/adrata-mcp 1.0.19 → 1.0.40

package/README.md

@@ -268,6 +268,9 @@ All free tools plus:
 | `research_person` | Composite: deep person research |
 | `discover_prospects` | Composite: find new prospects |
 | `get_next_contacts` | Composite: next best contacts to reach |
+| `commit_lead_to_outbound` | Governed: commit a lead above the /targets line — Pipeline's Outbound stage |
+| `release_lead_from_outbound` | Governed: take a lead back out of Outbound |
+| `list_outbound_leads` | Who is committed to Outbound right now |
 | `get_competitive_intel` | Composite: competitive analysis |
 | `get_meeting_brief` | Composite: pre-meeting intelligence |
 | `get_deal_coaching` | Composite: deal coaching insights |

package/access/tiers.js

@@ -27,6 +27,12 @@ export const TOOL_TIERS = {
   // or reach a second workspace from the CLI at all.
   list_workspaces: TIERS.ENTERPRISE,
   switch_workspace: TIERS.ENTERPRISE,
+  // Provisioning a customer's workspace: reading who is seated, and seating
+  // somebody with the onboarding link that reaches them. Enterprise because it
+  // is workspace administration -- the API separately requires the connected
+  // user to be a workspace admin and answers 403 otherwise.
+  list_workspace_seats: TIERS.ENTERPRISE,
+  create_onboarding_link: TIERS.ENTERPRISE,
   adrata_api_catalog: TIERS.FREE,
   paper_app_audit: TIERS.FREE,
   adrata_desktop_app_audit: TIERS.FREE,
@@ -220,6 +226,7 @@ export const TOOL_TIERS = {
   list_work_boards: TIERS.ENTERPRISE,
   list_source_control_connections: TIERS.ENTERPRISE,
   get_source_control_connection_events: TIERS.ENTERPRISE,
+  bind_repository_to_board: TIERS.ENTERPRISE,
   get_work_item_delivery_evidence: TIERS.ENTERPRISE,
   audit_work_hub: TIERS.ENTERPRISE,
   list_work_item_acceptance_criteria: TIERS.ENTERPRISE,
@@ -235,6 +242,7 @@ export const TOOL_TIERS = {
   record_work_item_qa_failure_and_release: TIERS.ENTERPRISE,
   requeue_work_item_qa_after_fix: TIERS.ENTERPRISE,
   get_work_item_history: TIERS.ENTERPRISE,
+  get_work_item_field_changes: TIERS.ENTERPRISE,
   get_work_item_comments: TIERS.ENTERPRISE,
   get_work_board_rollup: TIERS.ENTERPRISE,
   list_work_board_rollups: TIERS.ENTERPRISE,
@@ -243,6 +251,8 @@ export const TOOL_TIERS = {
   attach_work_item_qa_evidence: TIERS.ENTERPRISE,
   verify_work_item_qa_evidence_playback: TIERS.ENTERPRISE,
   move_work_item: TIERS.ENTERPRISE,
+  preview_work_item_acceptance_reaffirmation: TIERS.ENTERPRISE,
+  reaffirm_work_item_current_acceptance: TIERS.ENTERPRISE,
   transfer_work_item_between_boards: TIERS.ENTERPRISE,
   set_work_item_tag: TIERS.ENTERPRISE,
   block_work_item: TIERS.ENTERPRISE,
@@ -258,6 +268,11 @@ export const TOOL_TIERS = {
   unsatisfy_work_item_acceptance_criterion: TIERS.ENTERPRISE,
   comment_on_work_item: TIERS.ENTERPRISE,
   flag_work_item: TIERS.ENTERPRISE,
+  // Retiring a card and bringing it back. Same reasoning as every board write:
+  // these change a real workspace record.
+  archive_work_item: TIERS.ENTERPRISE,
+  delete_work_item: TIERS.ENTERPRISE,
+  unarchive_work_item: TIERS.ENTERPRISE,
   // The containers above the cards, and the "add this to the roadmap" verb.
   // Same reasoning as every board tool: scopes are real workspace records.
   list_work_scopes: TIERS.ENTERPRISE,
@@ -411,6 +426,18 @@ export const TOOL_TIERS = {
   // get_speedrun_list already mapped above
   discover_prospects: TIERS.PRO,
   get_next_contacts: TIERS.PRO,
+  // The Outbound trio, registered in `toolsets/prospecting.js` beside `get_next_contacts` and
+  // named in its header alongside it. They arrived on the desktop branch while this tier map
+  // grew on main, so neither side could see the gap: the registry had three tools this table
+  // did not, and `getToolTier` falls back to ENTERPRISE for anything unlisted -- which would
+  // have quietly put a PRO workspace's own Outbound moves behind the top tier rather than
+  // erroring. The exhaustiveness test is what refuses the fallback, and it is right to.
+  //
+  // PRO, matching the toolset they ship in: committing a lead to Outbound IS the pipeline move
+  // for a person, so it belongs with the prospecting reads that lead to it, not above them.
+  commit_lead_to_outbound: TIERS.PRO,
+  list_outbound_leads: TIERS.PRO,
+  release_lead_from_outbound: TIERS.PRO,
 
   // --- COMPOSITE TOOLSETS: intelligence (pro tier) ---
   get_competitive_intel: TIERS.PRO,

package/api-bridge.js

@@ -298,6 +298,12 @@ const PATH_WRITE_SCOPES = [
   ['/api/v1/contacts', 'write:people'],
   ['/api/v1/people', 'write:people'],
   ['/api/v1/leads', 'write:people'],
+  // Lead lists — including the marker-owned Outbound list that /targets and
+  // Pipeline share — are gated by the API on read:speedrun for reads AND
+  // writes (scope_guard/mod.rs: `path.starts_with("/lead-lists")`). Naming it
+  // here turns the preview's "unknown (no mapping for this path)" into the
+  // scope the server actually checks.
+  ['/api/v1/lead-lists', 'read:speedrun'],
   ['/api/v1/agent-tasks', 'write:tasks'],
   ['/api/v1/tasks', 'write:tasks'],
   ['/api/v1/actions', 'write:actions'],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adrata/adrata-mcp",
-  "version": "1.0.19",
-  "description": "Adrata MCP Server \u2014 connect Claude Code, Codex, Gemini, Cursor, and other AI tools to your CRM. 80+ tools for companies, people, deals, actions, buyer groups, warm intros, webhooks, intelligence, and more.",
+  "version": "1.0.40",
+  "description": "Adrata MCP Server \u2014 connect Claude Code, Codex, Gemini, Cursor, and other AI tools to your CRM. About 275 tools registered at startup for companies, people, deals, actions, buyer groups, warm intros, webhooks and intelligence, plus 65 more behind eight named toolsets you load with enable_toolset.",
   "type": "module",
   "main": "server.js",
   "bin": {
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "start": "node server.js",
-    "test": "node --test analytics.test.js server.test.js api-bridge.test.js http/edge-block.test.js http/rate-limit.test.js audit-flush.test.js buyer-group-writes.test.js note-writes.test.js mcp-spec.test.js packaging.test.js product-profile.test.js security.test.js tool-annotations.test.js toolsets.test.js toolsets/communications.test.js access/auth.test.js access/oauth-callback.test.js access/oauth-session.test.js access/oauth-capabilities.test.js access/oauth-scope-grantability.test.js scripts/local-dev-server.test.js tools/competitive-coverage.test.js tools/describe-count.test.js tools/email-tools.test.js tools/scheduling.test.js tools/work-board-tools.test.js tools/work-hub/audit.test.js tools/work-hub/criteria-quality.test.js tools/roadmap-tools.test.js tools/source-control/connection-tools.test.js governance/money.test.js http/rate-limit-policy.test.js"
+    "test": "node --test analytics.test.js server.test.js api-bridge.test.js http/edge-block.test.js http/rate-limit.test.js audit-flush.test.js buyer-group-writes.test.js note-writes.test.js mcp-spec.test.js packaging.test.js product-profile.test.js security.test.js security.cap-contract.test.js tool-annotations.test.js toolsets.test.js toolsets/communications.test.js toolsets/prospecting.test.js access/auth.test.js access/oauth-callback.test.js access/oauth-session.test.js access/oauth-capabilities.test.js access/oauth-scope-grantability.test.js scripts/local-dev-server.test.js tools/competitive-coverage.test.js tools/describe-count.test.js tools/email-tools.test.js tools/scheduling.test.js tools/work-board-tools.test.js tools/work-hub/audit.test.js tools/work-hub/field-changes.test.js tools/work-hub/criteria-quality.test.js tools/roadmap-tools.test.js tools/provisioning/onboarding-tools.test.js tools/source-control/connection-tools.test.js governance/money.test.js http/rate-limit-policy.test.js"
   },
   "keywords": [
     "mcp",

package/security.js

@@ -143,18 +143,169 @@ export function rateLimitResponse(retryAfterMs) {
 // 2. Input Validation
 // ---------------------------------------------------------------------------
 
+/**
+ * Length caps for TOP-LEVEL string tool arguments, by argument name.
+ *
+ * `applySecurityLayer` wraps every tool this server registers, so these caps
+ * are the FIRST thing any argument meets — before Zod, before the handler,
+ * before the API. Until 2026-09-05 they TRUNCATED, silently, and the tool then
+ * returned success: a card flag ended mid-word at exactly 1000 characters
+ * ("Do not substitute API SHA or bounce the card merely t") and the
+ * prohibition was gone for every subsequent reader including its author.
+ *
+ * Every comparable cap in the Rust API refuses instead — comments 2000,
+ * criterion parts 600, engineering-proof fields 600, reviewer model 120,
+ * evidence summary 600 — several enforced twice, once in the handler and
+ * again as a database CHECK. So every caller already handles a refusal. This
+ * layer was the only one that cut, and it ran first, which is why the cut was
+ * invisible from both ends.
+ */
+const DEFAULT_STRING_CAP = 1000;
+
+/**
+ * The API's own cap on a card comment, and on every free-text `reason` that
+ * routes through `validate_body`: flag, block, dependency, sharing, QA-flow
+ * note. Rust calls it `MAX_COMMENT_BODY_CHARS`
+ * (`code/api/crates/routes-gtm/src/work_boards/mod.rs`).
+ *
+ * `security.cap-contract.test.js` reads that constant out of the Rust
+ * source and fails if this number ever drops below it, because THAT is the
+ * divergence this whole change is about: a cap here that sits below the cap
+ * downstream cuts a value the API would have accepted, and the API never gets
+ * to refuse it.
+ */
+const API_COMMENT_BODY_CAP = 2000;
+
+/**
+ * Sanity ceiling for an argument that carries a document or a data file rather
+ * than prose (a CSV to import, a knowledge file's markdown, a paper's HTML).
+ * Deliberately far above any product rule: the point is to bound the transport,
+ * and to let the API be the layer that says how big a document may be.
+ */
+const BULK_PAYLOAD_CAP = 1_000_000;
+
+const STRING_CAPS_BY_KEY = {
+  // Long-form prose the API caps far lower anyway (a comment body is refused
+  // at 2000). 10000 here is a sanity ceiling, not the product rule.
+  body: 10000,
+  message: 10000,
+  description: 10000,
+
+  // The reason family. These were the DANGEROUS truncations and the reason
+  // this cap exists as its own class:
+  //
+  //   flag_work_item.reason          API cap 2000 — a 1000-cut value was
+  //                                  ACCEPTED truncated. This is the flag
+  //                                  defect: a prohibition ended mid-word at
+  //                                  exactly 1000 characters and read as
+  //                                  complete to every later reader.
+  //   block_work_item.reason         API cap 2000 — same shape.
+  //   move_work_item.reason          NO API cap at all, so nothing downstream
+  //   transfer_...between_boards     could ever catch the cut. Permanently and
+  //                                  silently shortened to 1000.
+  //   every X-Adrata-Reason header   NO API cap anywhere in Rust
+  //   (api-bridge.js)                (presence-only). Same silence.
+  //
+  // Raising these to the API's own 2000 is what keeps this change from
+  // trading a silent cut for a refusal of honest input: a 1400-character
+  // reason is legitimate, the API accepts it, and until now this layer cut it.
+  reason: API_COMMENT_BODY_CAP,
+
+  // `auditReason` is the same field family under a different name: the shared
+  // `moneyWrite` envelope (server.js) spreads it into EVERY money write, so it
+  // was the one reason-shaped argument the first version of this table missed.
+  auditReason: API_COMMENT_BODY_CAP,
+
+  // `record_work_item_qa_failure_and_release.details` is composed into a flag
+  // reason (`"QA criterion failure (<id>): " + details`) and so lands under
+  // the same 2000 API cap. A 1000-character cut plus that ~14-character prefix
+  // stayed comfortably under 2000, which is exactly why the "~1,014 characters,
+  // 200 OK" measurement was silent. Known rough edge: a `details` near 2000
+  // composes to over 2000 and the API refuses the composed value with its own
+  // message. That is a refusal rather than a silence, which is the property
+  // this change is about.
+  details: API_COMMENT_BODY_CAP,
+
+  // Search terms. A query longer than this is a paste, not a search.
+  query: 500,
+  search: 500,
+
+  // --- Payloads, not prose ---
+  //
+  // These carry a document or a data file, and at the old 1000 default they
+  // were the WORST instances of the truncation: `bulk_import`/`manage_data`
+  // took a CSV — any real one is past 1000 in its first few rows — cut it to
+  // 1000, imported the fragment, and reported success. A partial import that
+  // announces itself as complete is harder to notice than a lost sentence.
+  //
+  // The ceiling here is a transport sanity bound, NOT a product rule. This
+  // layer has no business deciding how large a knowledge file may be; the API
+  // owns that, and it can refuse. What this layer must never again do is
+  // decide it silently.
+  csvData: BULK_PAYLOAD_CAP,
+  content: BULK_PAYLOAD_CAP,
+};
+
+/** The cap that applies to a top-level string argument named `key`. */
+export function maxLengthForKey(key) {
+  return Object.prototype.hasOwnProperty.call(STRING_CAPS_BY_KEY, key)
+    ? STRING_CAPS_BY_KEY[key]
+    : DEFAULT_STRING_CAP;
+}
+
+/**
+ * The refusal text. It names the actual length, the cap, and how much to cut,
+ * because the caller is usually an agent that can shorten and retry — and it
+ * says plainly that nothing was written, since the whole point of the defect
+ * this replaces was a caller believing a truncated write had landed.
+ */
+export function overLengthMessage(field, length, maxLength) {
+  return `Parameter "${field}" is ${length} characters and the cap is ${maxLength} — `
+    + `remove ${length - maxLength}. Nothing was written: the value was refused whole `
+    + `rather than cut, so shorten it and call again.`;
+}
+
 /**
  * Common validation schemas for tool parameters.
  * These wrap and tighten the existing Zod schemas.
  */
 export const validators = {
-  /** Sanitize a string — strip control characters, limit length. */
-  sanitizeString(value, maxLength = 1000) {
-    if (typeof value !== 'string') return value;
-    // Strip control characters except newline/tab
-    // eslint-disable-next-line no-control-regex
-    const cleaned = value.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '');
-    return cleaned.slice(0, maxLength);
+  /**
+   * Strip control characters, and REFUSE a string longer than `maxLength`.
+   *
+   * Returns `{ value, error }` rather than a bare string on purpose. Until
+   * 2026-09-05 this ended `return cleaned.slice(0, maxLength)` — the value was
+   * cut, `validateToolInput` still reported `valid: true`, and the write went
+   * on to return 200. The object shape means a caller cannot use the result as
+   * a string without noticing, so the refusal cannot be dropped the way the
+   * silent slice was.
+   *
+   * Length is counted in CODE POINTS (`[...cleaned].length`), matching the
+   * Rust API's `chars().count()` downstream rather than UTF-16 code units, so
+   * a value this layer accepts is not one the next layer measures differently.
+   */
+  sanitizeString(value, maxLength = DEFAULT_STRING_CAP, field = 'value') {
+    if (typeof value !== 'string') return { value, error: null };
+    // Vertical tab (0x0B) and form feed (0x0C) ARE whitespace: they separate
+    // words. Deleting them outright fuses the tokens either side into one —
+    // "evidence<VT>01M1RAMY" becomes "evidence01M1RAMY" — and that is worse to
+    // read than a truncation, because the sentence still looks complete, so a
+    // reader has no tell at all. They collapse to a space. Every other control
+    // character in the class is not a separator, so removing it stays correct.
+    //
+    // Tab (0x09), newline (0x0A) and carriage return (0x0D) sit outside both
+    // classes and pass through untouched, as they always have.
+    const cleaned = value
+      // eslint-disable-next-line no-control-regex
+      .replace(/[\x0B\x0C]/g, ' ')
+      // eslint-disable-next-line no-control-regex
+      .replace(/[\x00-\x08\x0E-\x1F\x7F]/g, '');
+    // Measured AFTER stripping: control characters must not eat the budget.
+    const length = [...cleaned].length;
+    if (length > maxLength) {
+      return { value: cleaned, error: overLengthMessage(field, length, maxLength) };
+    }
+    return { value: cleaned, error: null };
   },
 
   /** Validate that a string doesn't contain obvious injection patterns. */
@@ -223,13 +374,15 @@ export function validateToolInput(toolName, args) {
         continue;
       }
 
-      // Sanitize string values
-      const maxLen = key === 'body' || key === 'message' || key === 'description'
-        ? 10000
-        : key === 'query' || key === 'search'
-          ? 500
-          : 1000;
-      sanitized[key] = validators.sanitizeString(value, maxLen);
+      // Sanitize string values. An over-long value is REFUSED, not cut:
+      // see the cap table above for why this layer used to truncate silently.
+      const { value: cleaned, error: lengthError } =
+        validators.sanitizeString(value, maxLengthForKey(key), key);
+      if (lengthError) {
+        errors.push(lengthError);
+        continue;
+      }
+      sanitized[key] = cleaned;
 
       // Validate specific field types
       if (key === 'id' || key.endsWith('Id')) {

package/server.js

@@ -55,6 +55,7 @@ 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 { registerProvisioningTools } from './tools/provisioning/onboarding-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';
@@ -2394,7 +2395,29 @@ registerWorkBoardTools(server, {
   getGrantedScope: () => loadTokens()?.scope,
 });
 
-registerSourceControlTools(server, { z, api, ok });
+registerSourceControlTools(server, {
+  z,
+  api,
+  ok,
+  validateApiBridgeRequest,
+  buildMutationHeaders,
+  getGrantedScope: () => loadTokens()?.scope,
+});
+
+// Seating a customer's people and minting the onboarding link an AE hands them.
+// The first path from MCP that can actually finish: `invite_user` through
+// `adrata_ai_tool_execute` refuses every machine principal at the confirmation
+// step (ai_crm_tools/mod.rs:427), so the bridge could preview a seat forever and
+// create none. See tools/provisioning.js for why this is one tool and not two.
+registerProvisioningTools(server, {
+  z,
+  api,
+  ok,
+  validateApiBridgeRequest,
+  buildMutationHeaders,
+  getGrantedScope: () => loadTokens()?.scope,
+  getWorkspaceId: () => loadTokens()?.workspaceId ?? AUTH?.workspaceId ?? null,
+});
 
 // The containers above the cards, and the "add this to the roadmap" verb
 // (company/decisions/2026-08-06-spoq-roadmap-sync.md).

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.19",
+  "version": "1.0.40",
   "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.19",
+      "version": "1.0.40",
       "transport": {
         "type": "stdio"
       },

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

@@ -13,7 +13,14 @@ 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.
+their operating procedure. Read the current amendment at
+`company/decisions/2026-09-04-complete-quality-gates-and-instant-interactions.md`
+and the card contract at
+`company/playbooks/engineering/card-readiness-and-evidence-contract.md`.
+Every required criterion/configuration must pass: failed, blocked, skipped,
+missing, stale, unknown, or flaky results block completion. Do not use a human
+acknowledgement or legacy unknown-author exception to clear an incomplete gate.
+No visible UI changes are authorized by the quality audit.
 
 ## Establish the real queue
 
@@ -171,8 +178,14 @@ does not establish that the screen is visually correct.
   `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.
+  It defaults to the canonical deployment on both halves — the canonical API for
+  the card and `https://adrata.com` for the bundle — and serves that origin's own
+  response policy, so whether a recording plays is decided by the deployed
+  `media-src` rather than by no policy at all. Record the returned session
+  fingerprint, the deployed app build, AND the `Deployed security policy served
+  by this bridge` line in the playback evidence, then close the bridge. If that
+  line is the WARNING instead, the bridge sent no policy and the playback it
+  showed says nothing about the deployed one.
 
 ## Manage cards as outcomes, not bug counters
 

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

@@ -36,22 +36,34 @@ implementation-and-submit path below.
    available here, and the reviewer's comment is usually the one thing that
    would have stopped you.
 
-**A card carrying a `flag` is not workable.** The flag means somebody has already
-found a problem with the card ITSELF — unclear scope, no repro, a blocked
-dependency, a question waiting on an answer — and its `reason` says which. It is
-a different claim from the tag, which is only about urgency: a flagged Critical
-card is still not something to start on. Read the comments for the surrounding
-argument and pick a different card, unless you are the person who can answer it.
-If you resolve it, clear the flag with `flag_work_item` (`flagged: false`) and
-say what resolved it. Anyone may clear one, which is exactly why every clear is
-recorded as a comment.
-
-If the card is not workable — no repro, no expected behaviour, ambiguous scope —
-**flag it** with `flag_work_item` and the one question that would unblock it,
-then stop. Do not invent the missing half. Flagging is what turns "I could not
-work this" into something the next person sees before they pick it up, rather
-than a sentence in your report that nobody reads. An unworkable card is a triage
-problem, not a coding problem.
+**Read the flag's reason and `blocksClaim` separately.** A flag preserves a
+finding; `blocksClaim` says whether an agent can take the work. An ordinary
+failed test, fixture repair or deploy prerequisite that an agent can resolve
+stays claimable with `blocksClaim: false`. Keep the finding visible while
+repairing it. Urgency still comes from the tag, not the flag.
+
+Use `blocksClaim: true` only for an explicit prerequisite agents cannot satisfy,
+such as owner authorization, vendor consent or a product decision. Read its
+comments and take another workable card until that prerequisite is satisfied.
+When the field is absent, inspect the deployed API and tool contract: older
+versions treat every flag as blocking. Do not clear an unresolved finding to
+work around an old claim gate; record the release dependency instead.
+
+When the finding is resolved, use `flag_work_item` (`flagged: false`) with the
+`expectedFlagGeneration` captured for that finding and a concrete resolution
+reason. A stale-generation refusal means a newer finding must be read and
+resolved; substituting its generation without doing that loses the newer
+failure. If the generation is absent, do not invent one or claim the older
+client supplied concurrent-update protection. Record the release/client
+prerequisite. For a deployed QA repair, use `requeue_work_item_qa_after_fix` with the
+actual failed/deployed builds and `repairedFlagGeneration`, after proving the
+fix's relevant blobs are deployed. Clearing a flag is not a QA pass.
+
+If a missing repro, expected behavior or scope decision prevents work, record
+what is missing and the next action on the card. Set a blocking flag only when
+the prerequisite needs someone outside the agent work loop. Do not invent the
+missing half, and do not turn an ordinary engineering failure into an owner
+decision.
 
 ## Claim it, in the same move, FIRST
 
@@ -77,8 +89,10 @@ Three reasons, and the third is the real one:
 Reuse the same `idempotencyKey` if the call fails and you retry. The server
 replays rather than appending a second transition.
 
-**If the claim is refused**, the card already belongs to somebody: pick a
-different one. `force: true` exists — it takes the card over and demands a reason
+**If the claim is refused**, read its actual reason. Another worker, missing
+scope, readiness requirements or an older deployed gate can each refuse a claim.
+Resolve an agent-repairable prerequisite or pick another workable card; do not
+treat every refusal as proof of ownership. `force: true` exists — it takes the card over and demands a reason
 saying why — but it is for a card whose owner is genuinely gone, not for working
 around a refusal. Taking someone's card because it was convenient is the one move
 on this board that costs trust permanently. If you use it, say so in your report,
@@ -114,27 +128,22 @@ Two things to carry back to the card:
   session), so the next person at aligning can ask you what you meant; what it
   must not arrive with is a list of outcomes nobody can check.
 
-## Tick what you ran
-
-Before you move the card on, tick the criteria you actually executed, with
-`satisfy_work_item_acceptance_criterion` and the evidence in `note` — a build
-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`. 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,
-put it on the card with `comment_on_work_item` first.
+## Record builder readiness
+
+Before QA1 entry, record the exact deployed build, implementation and test
+blobs, executed checks, failures and replay instructions in the builder
+handoff. Leave acceptance criteria **unmet and unverified** for independent QA,
+as required by `AGENTS.md` and the recorded staging QA standard. Readiness means
+deployed, testable and free of known card-specific failure; a missing fixture,
+failing relevant check or unexplained runtime failure keeps the card in its
+build column.
+
+The builder releases its build claim at handoff and does not consume a QA-pass
+lease or credential. A fresh independent reviewer follows `qa-the-card`; a
+fixer never certifies its own repair. If an earlier unsupported tick needs to
+be cleared, preserve its evidence in a comment before using
+`unsatisfy_work_item_acceptance_criterion` through the governed current-stage
+claim procedure.
 
 ## Submit it
 

package/tool-annotations.js

@@ -38,6 +38,13 @@ const DOMAIN_OVERRIDES = {
   who_am_i: 'workspace',
   get_current_user: 'workspace',
 
+  // Provisioning: seating a user and minting the onboarding link that reaches
+  // them. Categorised 'workspace' rather than given a category of their own —
+  // these are workspace administration, and the profile that can administer a
+  // workspace is the one that should see them.
+  list_workspace_seats: 'workspace',
+  create_onboarding_link: 'workspace',
+
   // Governed API bridge.
   // Broad backwards-compatible escape hatches stay on the unprofiled Adrata
   // server. Product profiles use the namespace-bound capability bridge below.
@@ -241,10 +248,20 @@ const IDEMPOTENT_WRITES = new Set([
   // comment, criterion, or card.
   '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',
+  // Retiring an already-retired card is REFUSED with a 409 rather than
+  // replayed, so the reason of the first retirement cannot be silently
+  // overwritten — which makes a retry with the same key land on the same state.
+  // The restore is a plain clear of the same five columns.
+  'archive_work_item', 'unarchive_work_item',
   // A repeat block is the same edge (the pair is unique), and a repeat
   // unblock deletes a row that is already gone. Neither compounds.
   'block_work_item', 'unblock_work_item',
   'add_work_item_acceptance_criterion',
+  // (delete_work_item needs no entry here either: DESTRUCTIVE_PATTERN matches
+  // the `delete_` prefix, so a host confirmation-gates it on its NAME. That is
+  // the whole reason the destructive branch is a separate tool rather than a
+  // `kind` argument on archive_work_item — a switch inside a safe-sounding name
+  // would be gated by nothing.)
   // Reclassifying is a PUT of the whole routing decision, not an append:
   // replaying the same key rewrites the criterion to the same route and the
   // server's receipt table records one change, never a second one.