@reproapp/mcp 0.0.3 → 0.0.6

package/README.md

@@ -39,12 +39,24 @@ Custom Repro deployment:
 
 The installed binary is `repro-mcp`.
 
+## Agent Rules
+
+When a user asks about Repro sessions, requests, traces, privacy policies, or app configuration, the AI client must use the Repro MCP tools only. It must not write local scripts, call Repro HTTP APIs directly, read cached Repro auth files, or patch policy JSON outside the MCP tool surface.
+
+Privacy policy updates are intentionally handle-based:
+
+- Use `inspect_privacy_policy` or `list_privacy_policy_blockers` first.
+- For one policy statement, pass the exact `statementSid` to `update_privacy_policy`.
+- For all currently listed blockers, pass the returned `blockerSetId` to `update_privacy_policy`.
+- Broad natural-language updates such as "make all blockers keep exact" are read-only/dry-run unless they include a `blockerSetId` or exact statement ids.
+- `KEEP_EXACT` on sensitive or raw-text review statements requires `force=true` and a human reason.
+
 ## Configuration
 
 Built-in defaults:
 
-- `REPRO_AI_BASE_URL=http://10.116.0.4`
-- `REPRO_API_BASE_URL=http://10.116.0.5/api`
+- `REPRO_AI_BASE_URL=https://repro-ai-u8lhw.ondigitalocean.app`
+- `REPRO_API_BASE_URL=https://repro-api-d7288.ondigitalocean.app/api`
 - `REPRO_WEB_BASE_URL=https://getrepro.io`
 
 Optional:
@@ -181,3 +193,7 @@ npm run start:stdio
 - `get_trace`
 - `get_action_path`
 - `get_function_candidates`
+- `inspect_privacy_policy`
+- `list_privacy_policy_blockers`
+- `update_privacy_policy`
+- `approve_privacy_policy`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reproapp/mcp",
-  "version": "0.0.3",
+  "version": "0.0.6",
   "description": "Repro MCP server for AI-assisted debugging and privacy policy workflows",
   "license": "MIT",
   "type": "commonjs",

package/src/index.js

@@ -2,6 +2,7 @@
 'use strict';
 
 const childProcess = require('node:child_process');
+const crypto = require('node:crypto');
 const fs = require('node:fs');
 const http = require('node:http');
 const os = require('node:os');
@@ -11,13 +12,20 @@ const SERVER_NAME = 'repro-mcp';
 const SERVER_VERSION = '0.0.1';
 const SUPPORTED_PROTOCOL_VERSION = '2024-11-05';
 const JSON_RPC_VERSION = '2.0';
-const DEFAULT_REPRO_AI_BASE_URL = 'http://10.116.0.4';
-const DEFAULT_REPRO_API_BASE_URL = 'http://10.116.0.5/api';
+const SERVER_INSTRUCTIONS = [
+  'For Repro-scoped questions about sessions, requests, traces, privacy policies, apps, or configuration, use the Repro MCP tools only.',
+  'Do not create local scripts, read cached Repro auth files, or call Repro HTTP APIs directly for Repro data or policy workflows.',
+  'For privacy policy writes, inspect first and then use exact statementSid(s) or blockerSetId. Broad natural-language policy update queries are read-only.',
+].join(' ');
+const DEFAULT_REPRO_AI_BASE_URL = 'https://repro-ai-u8lhw.ondigitalocean.app';
+const DEFAULT_REPRO_API_BASE_URL = 'https://repro-api-d7288.ondigitalocean.app/api';
 const DEFAULT_REPRO_WEB_BASE_URL = 'https://getrepro.io';
 loadEnvironmentFiles(process.env);
 const DEBUG_LOG_PATH = process.env.REPRO_MCP_DEBUG_LOG;
 const DEFAULT_AUTH_TIMEOUT_MS = 2 * 60 * 1000;
 const DEFAULT_AUTH_POLL_INTERVAL_MS = 1500;
+const PRIVACY_BLOCKER_SET_TTL_MS = 15 * 60 * 1000;
+const privacyBlockerSets = new Map();
 const LOCAL_TOOL_DEFINITIONS = [
   {
     name: 'resolve_scope',
@@ -82,10 +90,28 @@ const LOCAL_TOOL_DEFINITIONS = [
       additionalProperties: true,
     },
   },
+  {
+    name: 'list_privacy_policy_blockers',
+    description:
+      'Read-only Repro privacy review workflow tool. Lists unresolved privacy policy blockers for an app/environment and returns a blockerSetId that must be used for safe bulk updates. Use this instead of direct API calls, scripts, or broad update queries when a user asks about Repro policy blockers.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tenantId: { type: 'string' },
+        appId: { type: 'string' },
+        environment: { type: 'string' },
+        state: { type: 'string', enum: ['active', 'pending', 'approved'] },
+        query: { type: 'string' },
+        includeTechnical: { type: 'boolean' },
+        openUi: { type: 'boolean' },
+      },
+      additionalProperties: true,
+    },
+  },
   {
     name: 'update_privacy_policy',
     description:
-      'Find matching privacy policy statements from a high-level query or statement id, show a policy diff, and optionally stage/apply/approve changes. Prefer keep exact for known non-sensitive values or regex-assisted raw-text hints for sensitive formats; drop unsafe values; use safe partial mask only as a last-resort unknown-shape fallback.',
+      'Safely stage/apply Repro privacy policy decisions. Apply/approve requires exact statementSid(s) or a blockerSetId returned by inspect_privacy_policy/list_privacy_policy_blockers; broad natural-language queries are dry-run only. KEEP_EXACT on sensitive-looking statements requires force=true plus a human reason. Never use direct Repro API scripts for policy changes.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -103,6 +129,7 @@ const LOCAL_TOOL_DEFINITIONS = [
           type: 'array',
           items: { type: 'string' },
         },
+        blockerSetId: { type: 'string' },
         decision: {
           type: 'string',
           enum: ['SAFE_PARTIAL_MASK', 'KEEP_EXACT', 'DROP', 'REGEX_ASSISTED'],
@@ -123,6 +150,9 @@ const LOCAL_TOOL_DEFINITIONS = [
         apply: { type: 'boolean' },
         approve: { type: 'boolean' },
         allowMultiple: { type: 'boolean' },
+        force: { type: 'boolean' },
+        reason: { type: 'string' },
+        overrideReason: { type: 'string' },
         openUi: { type: 'boolean' },
       },
       required: ['decision'],
@@ -1072,6 +1102,7 @@ async function handleRpcMessage(message, config, client, getTools) {
           name: SERVER_NAME,
           version: SERVER_VERSION,
         },
+        instructions: SERVER_INSTRUCTIONS,
       },
     };
   }
@@ -1183,7 +1214,7 @@ async function executeTool(params, config, client, getTools) {
 }
 
 function formatLocalToolContentText(name, value) {
-  if (name === 'inspect_privacy_policy') {
+  if (name === 'inspect_privacy_policy' || name === 'list_privacy_policy_blockers') {
     const text = renderPolicyInspectionText(value);
     if (text) return text;
   }
@@ -1221,6 +1252,17 @@ async function executeLocalTool(name, input, config, client) {
   if (name === 'inspect_privacy_policy') {
     return inspectPrivacyPolicy(input, config, client);
   }
+  if (name === 'list_privacy_policy_blockers') {
+    return inspectPrivacyPolicy(
+      {
+        ...input,
+        query: optionalNonEmptyString(input.query) || 'all privacy policy review blockers',
+        includeTechnical: true,
+      },
+      config,
+      client,
+    );
+  }
   if (name === 'update_privacy_policy') {
     return updatePrivacyPolicy(input, config, client);
   }
@@ -1662,6 +1704,10 @@ function renderPolicyInspectionText(value) {
     lines.push(`Summary: ${value.summary}`);
   }
   lines.push(`Privacy Studio: ${value.ui?.url ?? 'unavailable'}`);
+  if (value.blockerSet?.id) {
+    lines.push(`Blocker set: ${value.blockerSet.id} (${value.blockerSet.count} statement(s), expires ${value.blockerSet.expiresAt})`);
+    lines.push('Use blockerSetId with update_privacy_policy for safe bulk changes.');
+  }
   const blockers = Array.isArray(value.policyBlockers) ? value.policyBlockers : [];
   if (blockers.length > 0) {
     lines.push('', `Policy Blockers (${blockers.length})`);
@@ -1733,6 +1779,7 @@ function renderPolicyBlockerTextLines(blocker) {
     `  choices: ${choices}`,
     `  surfaces: ${surfaces}`,
     `  reason: ${blocker?.reason ?? blocker?.reviewReason ?? 'n/a'}`,
+    ...(blocker?.technical?.statementSid ? [`  statementSid: ${blocker.technical.statementSid}`] : []),
     `  UI: ${blocker?.ui?.url ?? 'unavailable'}`,
   ];
 }
@@ -1782,13 +1829,26 @@ async function inspectPrivacyPolicy(input, config, client) {
   const contradictions = findSameLeafPolicyContradictions(statements, matchedLeaves);
   const uiQuery = query || contradictions[0]?.leaf || '';
   const ui = buildPrivacyStudioUi(config, appId, selection.environmentId, uiQuery, input.openUi === true);
+  const blockerStatements = blockerQuery
+    ? matches.map((match) => match.statement).filter(isReviewBlockerStatement)
+    : matches.map((match) => match.statement).filter(isReviewBlockerStatement);
   const policyBlockers = buildPolicyBlockerSummaries(
-    blockerQuery ? matches.map((match) => match.statement) : matches.map((match) => match.statement).filter(isReviewBlockerStatement),
+    blockerStatements,
     config,
     appId,
     selection.environmentId,
     { includeTechnical },
   );
+  const blockerSet = policyBlockers.length
+    ? rememberPrivacyBlockerSet({
+        tenantId: optionalNonEmptyString(input.tenantId) || config.defaultTenantId || null,
+        appId,
+        environment: selection.environmentId,
+        state: selection.state,
+        query,
+        statements: blockerStatements,
+      })
+    : null;
   if (ui.openRequested) {
     try {
       await openUrl(ui.url);
@@ -1814,8 +1874,10 @@ async function inspectPrivacyPolicy(input, config, client) {
       policyBlockers,
       contradictions,
       ui,
+      blockerSet,
     }),
     policyBlockers,
+    blockerSet,
     matches: matches.map((match) => formatPolicyMatch(match.statement, match.score, { includeTechnical })),
     contradictions,
     rawTextHints: summarizeRawTextHints(selection.policy, query),
@@ -1854,7 +1916,30 @@ async function updatePrivacyPolicy(input, config, client) {
 
   const query = policyInspectionQuery(input);
   const statements = flattenPrivacyStatements(selection.policy);
-  const selectedStatements = selectStatementsForPolicyUpdate(statements, input, query);
+  const blockerSetSelection = resolvePrivacyBlockerSetSelection(input, {
+    tenantId: optionalNonEmptyString(input.tenantId) || config.defaultTenantId || null,
+    appId,
+    environment: selection.environmentId,
+    state: selection.state,
+  });
+  if (blockerSetSelection?.error) {
+    return {
+      status: 'blocked',
+      code: blockerSetSelection.error.code,
+      appId,
+      environment: selection.environmentId,
+      state: selection.state,
+      summary: blockerSetSelection.error.message,
+      ui: buildPrivacyStudioUi(config, appId, selection.environmentId, query, input.openUi === true),
+      nextStep: 'Run inspect_privacy_policy or list_privacy_policy_blockers again, then pass the returned blockerSetId.',
+    };
+  }
+  const selectedStatements = selectStatementsForPolicyUpdate(
+    statements,
+    input,
+    query,
+    blockerSetSelection?.statementSids,
+  );
   const explicitSelection = updateInputHasExplicitStatementSelection(input);
   if (!selectedStatements.length) {
     return {
@@ -1867,16 +1952,39 @@ async function updatePrivacyPolicy(input, config, client) {
       matches: rankPolicyStatementMatches(statements, input, query).slice(0, 8).map((match) => formatPolicyMatch(match.statement, match.score, { includeTechnical: true })),
     };
   }
-  if (apply && !explicitSelection && selectedStatements.length !== 1 && input.allowMultiple !== true) {
+  if (blockerSetSelection && selectedStatements.length !== blockerSetSelection.statementSids.length) {
     return {
-      status: 'needs_confirmation',
+      status: 'blocked',
+      code: 'STALE_BLOCKER_SET',
       appId,
       environment: selection.environmentId,
       state: selection.state,
-      summary: `The query matched ${selectedStatements.length} statements. Pass statementSids or allowMultiple=true before applying.`,
+      summary: `The blockerSetId references ${blockerSetSelection.statementSids.length} statement(s), but only ${selectedStatements.length} still exist in the current policy.`,
       ui: buildPrivacyStudioUi(config, appId, selection.environmentId, query, input.openUi === true),
       matches: selectedStatements.map((statement) => formatPolicyMatch(statement, 0, { includeTechnical: true })),
-      proposed: buildPolicyUpdateDiff(selection.policy, selectedStatements, decision, input.rawTextHints),
+      nextStep: 'Run inspect_privacy_policy or list_privacy_policy_blockers again, then retry with the new blockerSetId.',
+    };
+  }
+  const safety = validatePrivacyPolicyUpdateSafety({
+    input,
+    selectedStatements,
+    decision,
+    explicitSelection,
+    apply,
+  });
+  if (safety.blocked) {
+    return {
+      status: 'blocked',
+      code: safety.code,
+      appId,
+      environment: selection.environmentId,
+      state: selection.state,
+      summary: safety.summary,
+      ui: buildPrivacyStudioUi(config, appId, selection.environmentId, query, input.openUi === true),
+      matches: selectedStatements.map((statement) => formatPolicyMatch(statement, 0, { includeTechnical: true })),
+      proposed: safeBuildPolicyUpdateDiff(selection.policy, selectedStatements, decision, input.rawTextHints),
+      safety,
+      nextStep: safety.nextStep,
     };
   }
 
@@ -1908,6 +2016,8 @@ async function updatePrivacyPolicy(input, config, client) {
       ui,
       matches: selectedStatements.map((statement) => formatPolicyMatch(statement, 0, { includeTechnical: true })),
       diff: mutation.diff,
+      blockerSetId: blockerSetSelection?.id,
+      safety,
       nextStep: approve
         ? 'Run again with apply=true to stage the update and approve=true to approve it after API validation.'
         : 'Run again with apply=true to stage the pending policy update.',
@@ -1962,6 +2072,8 @@ async function updatePrivacyPolicy(input, config, client) {
       : `Staged pending privacy policy update for ${selectedStatements.length} statement(s).`,
     ui,
     diff: mutation.diff,
+    blockerSetId: blockerSetSelection?.id,
+    safety,
     api: {
       staged: true,
       approved: approve,
@@ -2072,12 +2184,21 @@ function normalizePolicyUpdateDecision(value) {
 function updateInputHasExplicitStatementSelection(input) {
   return Boolean(
     optionalNonEmptyString(input.statementSid) ||
+      optionalNonEmptyString(input.blockerSetId) ||
       (Array.isArray(input.statementSids) && input.statementSids.some((sid) => optionalNonEmptyString(sid))),
   );
 }
 
-function selectStatementsForPolicyUpdate(statements, input, query) {
+function selectStatementsForPolicyUpdate(statements, input, query, selectionSids) {
   const explicitSids = new Set();
+  if (Array.isArray(selectionSids)) {
+    for (const sid of selectionSids) {
+      const normalized = optionalNonEmptyString(sid);
+      if (normalized) {
+        explicitSids.add(normalized);
+      }
+    }
+  }
   const single = optionalNonEmptyString(input.statementSid);
   if (single) {
     explicitSids.add(single);
@@ -2099,10 +2220,215 @@ function selectStatementsForPolicyUpdate(statements, input, query) {
     .map((match) => match.statement);
 }
 
+function cleanupExpiredPrivacyBlockerSets(now = Date.now()) {
+  for (const [id, record] of privacyBlockerSets.entries()) {
+    if (!record?.expiresAt || record.expiresAt <= now) {
+      privacyBlockerSets.delete(id);
+    }
+  }
+}
+
+function rememberPrivacyBlockerSet({ tenantId, appId, environment, state, query, statements }) {
+  cleanupExpiredPrivacyBlockerSets();
+  const statementSids = mergeUniqueStrings(
+    (statements ?? []).map((statement) => String(statement?.sid ?? '')).filter(Boolean),
+  );
+  const createdAt = Date.now();
+  const payload = {
+    v: 1,
+    tenantId: tenantId || null,
+    appId,
+    environment,
+    state,
+    queryHash: crypto.createHash('sha256').update(query || '').digest('hex').slice(0, 12),
+    statementSids,
+    createdAt,
+    expiresAt: createdAt + PRIVACY_BLOCKER_SET_TTL_MS,
+  };
+  const encodedPayload = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
+  const checksum = crypto.createHash('sha256').update(encodedPayload).digest('hex').slice(0, 16);
+  const id = `PBS_${encodedPayload}.${checksum}`;
+  const record = {
+    id,
+    tenantId: payload.tenantId,
+    appId: payload.appId,
+    environment: payload.environment,
+    state: payload.state,
+    query: query || null,
+    statementSids,
+    createdAt,
+    expiresAt: payload.expiresAt,
+  };
+  privacyBlockerSets.set(id, record);
+  return {
+    id,
+    count: statementSids.length,
+    statementSids,
+    expiresAt: new Date(record.expiresAt).toISOString(),
+    expiresInMs: PRIVACY_BLOCKER_SET_TTL_MS,
+    updateContract:
+      'Pass this blockerSetId to update_privacy_policy. Repro MCP will apply only this exact set; broad query writes are rejected.',
+  };
+}
+
+function resolvePrivacyBlockerSetSelection(input, expected) {
+  const id = optionalNonEmptyString(input.blockerSetId);
+  if (!id) {
+    return null;
+  }
+  cleanupExpiredPrivacyBlockerSets();
+  const record = decodePrivacyBlockerSetId(id) || privacyBlockerSets.get(id);
+  if (!record) {
+    return {
+      error: {
+        code: 'UNKNOWN_BLOCKER_SET',
+        message: 'Unknown, expired, or malformed blockerSetId.',
+      },
+    };
+  }
+  if (record.expiresAt <= Date.now()) {
+    return {
+      error: {
+        code: 'EXPIRED_BLOCKER_SET',
+        message: 'The blockerSetId has expired.',
+      },
+    };
+  }
+  const mismatches = [];
+  if (record.appId !== expected.appId) mismatches.push(`appId ${record.appId}`);
+  if (record.environment !== expected.environment) mismatches.push(`environment ${record.environment}`);
+  if (record.state !== expected.state) mismatches.push(`state ${record.state}`);
+  if (record.tenantId && expected.tenantId && record.tenantId !== expected.tenantId) {
+    mismatches.push(`tenantId ${record.tenantId}`);
+  }
+  if (mismatches.length) {
+    return {
+      error: {
+        code: 'BLOCKER_SET_SCOPE_MISMATCH',
+        message: `blockerSetId ${id} belongs to a different policy scope: ${mismatches.join(', ')}.`,
+      },
+    };
+  }
+  return {
+    id,
+    statementSids: record.statementSids,
+    record,
+  };
+}
+
+function decodePrivacyBlockerSetId(id) {
+  if (!id.startsWith('PBS_')) {
+    return null;
+  }
+  const encoded = id.slice(4);
+  const separator = encoded.lastIndexOf('.');
+  if (separator <= 0) {
+    return null;
+  }
+  const encodedPayload = encoded.slice(0, separator);
+  const checksum = encoded.slice(separator + 1);
+  const expectedChecksum = crypto.createHash('sha256').update(encodedPayload).digest('hex').slice(0, 16);
+  if (checksum !== expectedChecksum) {
+    return null;
+  }
+  try {
+    const payload = JSON.parse(Buffer.from(encodedPayload, 'base64url').toString('utf8'));
+    if (
+      payload?.v !== 1 ||
+      !Array.isArray(payload.statementSids) ||
+      !optionalNonEmptyString(payload.appId) ||
+      !optionalNonEmptyString(payload.environment) ||
+      !optionalNonEmptyString(payload.state) ||
+      typeof payload.expiresAt !== 'number'
+    ) {
+      return null;
+    }
+    return {
+      id,
+      tenantId: optionalNonEmptyString(payload.tenantId) || null,
+      appId: payload.appId,
+      environment: payload.environment,
+      state: payload.state,
+      statementSids: mergeUniqueStrings(payload.statementSids),
+      createdAt: typeof payload.createdAt === 'number' ? payload.createdAt : 0,
+      expiresAt: payload.expiresAt,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function validatePrivacyPolicyUpdateSafety({ input, selectedStatements, decision, explicitSelection, apply }) {
+  const highRiskKeepExact = decision === 'KEEP_EXACT'
+    ? selectedStatements.filter(isHighRiskKeepExactStatement)
+    : [];
+  const safety = {
+    blocked: false,
+    explicitSelection,
+    selectedStatementCount: selectedStatements.length,
+    highRiskKeepExact: highRiskKeepExact.slice(0, 20).map((statement) =>
+      formatPolicyStatementSummary(statement, { includeTechnical: true }),
+    ),
+  };
+
+  if (apply && !explicitSelection) {
+    return {
+      ...safety,
+      blocked: true,
+      code: 'EXACT_SELECTION_REQUIRED',
+      summary:
+        'For safety, update_privacy_policy will not apply a broad natural-language query. Use statementSid(s), or run inspect_privacy_policy/list_privacy_policy_blockers and pass the returned blockerSetId.',
+      nextStep:
+        'Run list_privacy_policy_blockers for the app/environment, then call update_privacy_policy with blockerSetId or exact statementSids.',
+    };
+  }
+
+  if (apply && highRiskKeepExact.length > 0) {
+    const reason = optionalNonEmptyString(input.reason) || optionalNonEmptyString(input.overrideReason);
+    if (input.force !== true || !reason) {
+      return {
+        ...safety,
+        blocked: true,
+        code: 'KEEP_EXACT_REQUIRES_FORCE_REASON',
+        summary:
+          `KEEP_EXACT would preserve ${highRiskKeepExact.length} sensitive or raw-text review statement(s). Pass force=true and a human reason only after confirming the data is safe to retain exactly.`,
+        nextStep:
+          'Use REGEX_ASSISTED or DROP for sensitive/raw text. To intentionally keep exact, retry with force=true and reason describing why exact retention is acceptable.',
+      };
+    }
+    safety.overrideReason = reason;
+  }
+
+  return safety;
+}
+
+function isHighRiskKeepExactStatement(statement) {
+  const action = statement?.apply?.action;
+  if (action === 'DROP' || action === 'TOKENIZE') {
+    return true;
+  }
+  const review = statement?.meta?.review;
+  if (review?.status === 'REQUIRES_DECISION') {
+    return true;
+  }
+  const haystack = policyStatementHaystack(statement);
+  return /secret|token|password|passwd|credential|authorization|auth|cookie|setcookie|api[_-]?key|apikey|bearer|webhook|private[_-]?key|connection[_-]?string|card|cvv|cvc|pan|payment|ssn|email|phone|address|fullname|full[_-]?name|contact|accountid|account[_-]?id|session/i.test(haystack);
+}
+
 function buildPolicyUpdateDiff(policy, statements, decision, rawTextHintsInput) {
   return mutatePrivacyPolicy(policy, statements, decision, rawTextHintsInput).diff;
 }
 
+function safeBuildPolicyUpdateDiff(policy, statements, decision, rawTextHintsInput) {
+  try {
+    return buildPolicyUpdateDiff(policy, statements, decision, rawTextHintsInput);
+  } catch (error) {
+    return {
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
 function mutatePrivacyPolicy(policy, selectedStatements, decision, rawTextHintsInput) {
   const clonedPolicy = cloneJson(policy) ?? {};
   const selectedSids = new Set(selectedStatements.map((statement) => String(statement?.sid ?? '')).filter(Boolean));
@@ -2702,7 +3028,7 @@ function suggestedPolicyBlockerNextStep(statement) {
   return 'Resolve this review decision before approval.';
 }
 
-function buildPolicyInspectionAnswerGuide({ query, blockerQuery, policyBlockers, contradictions, ui }) {
+function buildPolicyInspectionAnswerGuide({ query, blockerQuery, policyBlockers, contradictions, ui, blockerSet }) {
   const blockerLines = policyBlockers.map((blocker) => {
     const mode = blocker.currentPolicy.rawTextMode || blocker.currentPolicy.descendantRawTextMode || blocker.currentPolicy.action || 'UNKNOWN';
     return `${blocker.label}: current ${blocker.currentPolicy.action}${mode && mode !== blocker.currentPolicy.action ? ` / ${mode}` : ''}; recommendation ${blocker.recommendation || 'review'}; UI ${blocker.ui.url}`;
@@ -2720,6 +3046,10 @@ function buildPolicyInspectionAnswerGuide({ query, blockerQuery, policyBlockers,
     blockerLines,
     contradictionLines: contradictions.map((contradiction) => contradiction.message),
     privacyStudioUrl: ui?.url ?? null,
+    blockerSetId: blockerSet?.id ?? null,
+    updateRule: blockerSet?.id
+      ? 'For bulk blocker updates, call update_privacy_policy with blockerSetId. Do not use broad query apply.'
+      : 'For policy writes, use update_privacy_policy with exact statementSid(s). Do not use direct Repro API scripts.',
   };
 }