thumbgate 1.27.18 → 1.27.20

package/scripts/tool-contract-validator.js

@@ -0,0 +1,76 @@
+'use strict';
+
+/**
+ * Tool Contract Validator
+ * Validates tool arguments against the tool's inputSchema.
+ */
+function validateToolContract(schema, args) {
+  const errors = [];
+  if (!schema) return { valid: true, errors };
+
+  if (schema.type === 'object') {
+    if (typeof args !== 'object' || args === null || Array.isArray(args)) {
+      errors.push(`Expected object, got ${args === null ? 'null' : Array.isArray(args) ? 'array' : typeof args}`);
+      return { valid: false, errors };
+    }
+
+    // Check required fields
+    if (Array.isArray(schema.required)) {
+      for (const req of schema.required) {
+        if (args[req] === undefined || args[req] === null || args[req] === '') {
+          errors.push(`Missing required parameter: '${req}'`);
+        }
+      }
+    }
+
+    // Check properties
+    if (schema.properties) {
+      for (const [key, propSchema] of Object.entries(schema.properties)) {
+        const value = args[key];
+        if (value === undefined || value === null) continue; // Optional field not provided
+
+        const valType = typeof value;
+        if (propSchema.type === 'string') {
+          if (valType !== 'string') {
+            errors.push(`Parameter '${key}' must be a string (got ${valType})`);
+          } else if (Array.isArray(propSchema.enum)) {
+            if (!propSchema.enum.includes(value)) {
+              errors.push(`Parameter '${key}' must be one of [${propSchema.enum.join(', ')}] (got '${value}')`);
+            }
+          }
+        } else if (propSchema.type === 'number') {
+          if (valType !== 'number' || isNaN(value)) {
+            errors.push(`Parameter '${key}' must be a number (got ${valType})`);
+          }
+        } else if (propSchema.type === 'boolean') {
+          if (valType !== 'boolean') {
+            errors.push(`Parameter '${key}' must be a boolean (got ${valType})`);
+          }
+        } else if (propSchema.type === 'array') {
+          if (!Array.isArray(value)) {
+            errors.push(`Parameter '${key}' must be an array (got ${valType})`);
+          }
+        } else if (propSchema.type === 'object') {
+          if (valType !== 'object' || value === null || Array.isArray(value)) {
+            errors.push(`Parameter '${key}' must be an object (got ${valType})`);
+          } else {
+            // Recurse for nested objects
+            const subRes = validateToolContract(propSchema, value);
+            if (!subRes.valid) {
+              for (const err of subRes.errors) {
+                errors.push(`Parameter '${key}': ${err}`);
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+module.exports = { validateToolContract };

package/scripts/tool-registry.js

@@ -1,10 +1,23 @@
 #!/usr/bin/env node
 'use strict';
 
+// Human-readable display title from a snake_case tool name.
+// e.g. "capture_feedback" -> "Capture Feedback". The Claude Connectors Directory
+// requires every tool to carry BOTH a title and a readOnlyHint/destructiveHint.
+function humanizeTitle(name) {
+  return String(name || '')
+    .split(/[_-]+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
 function readOnlyTool(tool) {
   return {
     ...tool,
+    title: tool.title || humanizeTitle(tool.name),
     annotations: {
+      title: tool.title || humanizeTitle(tool.name),
       readOnlyHint: true,
     },
   };
@@ -13,12 +26,40 @@ function readOnlyTool(tool) {
 function destructiveTool(tool) {
   return {
     ...tool,
+    title: tool.title || humanizeTitle(tool.name),
     annotations: {
+      title: tool.title || humanizeTitle(tool.name),
       destructiveHint: true,
     },
   };
 }
 
+const GOAL_CONTRACT_SCHEMA = {
+  type: 'object',
+  description: 'Optional agent handoff contract. Use this when a worker/orchestrator/reviewer loop needs explicit done criteria before a done/fixed/shipped claim is allowed.',
+  properties: {
+    goal: { type: 'string', description: 'The operator-visible goal this claim is trying to close.' },
+    doneWhen: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'Human-readable acceptance criteria for the task.',
+    },
+    proveBy: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'Tracked action ids required before the claim can pass, such as tests_passed, review_completed, ci_green, deploy_verified, or operator_approved.',
+    },
+    mustNotChange: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'Protected areas or constraints the agents must preserve while completing the goal.',
+    },
+    workerAgent: { type: 'string', description: 'Agent responsible for implementation.' },
+    reviewerAgent: { type: 'string', description: 'Agent responsible for independent verification.' },
+    orchestratorAgent: { type: 'string', description: 'Agent responsible for routing and deciding whether done can be claimed.' },
+  },
+};
+
 const TOOLS = [
   readOnlyTool({
     name: 'capture_feedback',
@@ -120,6 +161,19 @@ const TOOLS = [
       required: ['toolName'],
     },
   }),
+  readOnlyTool({
+    name: 'ai_component_inventory',
+    description: 'Scan a project for AI/ML provider SDKs, agent frameworks, vector databases, Vertex/Gemini/Dialogflow CX usage, and model artifacts. Returns evidence suitable for enterprise AI inventory and ML-BOM review.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        rootDir: { type: 'string', description: 'Project root to scan. Defaults to the current process working directory.' },
+        format: { type: 'string', enum: ['summary', 'json', 'cyclonedx'], description: 'Response format. summary is compact text; json returns ThumbGate inventory; cyclonedx returns ML-BOM JSON.' },
+        maxFiles: { type: 'number', description: 'Maximum files to scan (default 2500).' },
+        includeSnippets: { type: 'boolean', description: 'Include matched source snippets in evidence. Defaults true.' },
+      },
+    },
+  }),
   readOnlyTool({
     name: 'search_thumbgate',
     description: 'Search raw ThumbGate state across feedback logs, ContextFS memory, prevention rules, and imported policy documents.',
@@ -371,6 +425,24 @@ const TOOLS = [
       },
     },
   }),
+  readOnlyTool({
+    name: 'suggest_fix',
+    description: 'Suggest corrective actions for a described failure by searching the lesson DB and prevention rules. Returns up to 3 ranked suggestions with their source. Call this when something goes wrong and you need guidance on what to do next.',
+    inputSchema: {
+      type: 'object',
+      required: ['context'],
+      properties: {
+        context: {
+          type: 'string',
+          description: 'Description of what went wrong or what the agent is trying to fix.',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of suggestions to return (default 3, max 5).',
+        },
+      },
+    },
+  }),
   readOnlyTool({
     name: 'infer_lesson_from_history',
     description: 'Perform autonomous inference on chat history to identify why a failure occurred and what rule should be recorded.',
@@ -417,6 +489,7 @@ const TOOLS = [
         bundleId: { type: 'string' },
         partnerProfile: { type: 'string' },
         delegationMode: { type: 'string', enum: ['off', 'auto', 'sequential'] },
+        enforcePlanQuality: { type: 'boolean' },
         approved: { type: 'boolean' },
         repoPath: { type: 'string' },
       },
@@ -758,6 +831,17 @@ const TOOLS = [
           items: { type: 'string' },
           description: 'Optional protected-file globs that require explicit approval before editing or publishing',
         },
+        workflowContract: {
+          type: 'object',
+          description: 'Optional deterministic workflow run contract. Supports workflowId, allowedBranches, blockedActions, requiredEvidence, and completionGate.',
+          properties: {
+            workflowId: { type: 'string' },
+            allowedBranches: { type: 'array', items: { type: 'string' } },
+            blockedActions: { type: 'array', items: { type: 'string' } },
+            requiredEvidence: { type: 'array', items: { type: 'string' } },
+            completionGate: { type: 'string' },
+          },
+        },
         repoPath: { type: 'string', description: 'Optional repo root used when evaluating git diff scope' },
         localOnly: { type: 'boolean', description: 'When true, also marks the task as local-only' },
         clear: { type: 'boolean', description: 'Clear the current task scope instead of setting one' },
@@ -835,6 +919,56 @@ const TOOLS = [
       },
     },
   }),
+  destructiveTool({
+    name: 'detect_noop',
+    title: 'Detect No-op Action',
+    description: 'Detect whether a tool call was a no-op (state unchanged) or identical to a prior attempt in the session — a cheap repeat-loop signal. Records the action attempt state for repeat detection.',
+    inputSchema: {
+      type: 'object',
+      required: ['actionId'],
+      properties: {
+        actionId: { type: 'string', description: 'Stable identifier for the action being checked (e.g. the file path or command being attempted)' },
+        kind: { type: 'string', enum: ['file', 'command'], description: 'Action kind: file edit/write or command execution' },
+        filePath: { type: 'string', description: 'Path of the file the action targets (file kind)' },
+        beforeContent: { type: 'string', description: 'File content before the action (file kind)' },
+        afterContent: { type: 'string', description: 'File content after the action (file kind)' },
+        exitCode: { type: 'number', description: 'Command exit code (command kind)' },
+        stdout: { type: 'string', description: 'Command stdout (command kind)' },
+        stderr: { type: 'string', description: 'Command stderr (command kind)' },
+        sessionId: { type: 'string', description: 'Optional session id used to scope repeat-attempt detection' },
+      },
+    },
+  }),
+  destructiveTool({
+    name: 'record_action_receipt',
+    title: 'Record Action Receipt',
+    description: 'Pair a tracked tool call with its outcome (diff, exit code, test result) so a promoted lesson encodes "this action -> this outcome", not just a thumbs signal. Appends to the action-receipts log.',
+    inputSchema: {
+      type: 'object',
+      required: ['actionId'],
+      properties: {
+        actionId: { type: 'string', description: 'Identifier of the tracked action this receipt pairs with' },
+        toolName: { type: 'string', description: 'Name of the tool that was invoked' },
+        toolInput: { type: 'object', description: 'Structured input the tool was called with' },
+        diff: { type: 'string', description: 'Optional unified diff or change summary produced by the action' },
+        exitCode: { type: 'number', description: 'Optional command exit code outcome' },
+        testOutcome: { type: 'string', description: 'Optional test outcome (e.g. passed, failed, 12/12)' },
+        stateHash: { type: 'string', description: 'Optional post-action state hash (from detect_noop)' },
+      },
+    },
+  }),
+  readOnlyTool({
+    name: 'get_action_receipts',
+    title: 'Get Action Receipts',
+    description: 'Read outcome-paired action receipts. Returns the receipt for a specific actionId, or the most recent receipts when no actionId is given.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        actionId: { type: 'string', description: 'Optional action id to fetch the matching receipt for' },
+        limit: { type: 'number', description: 'Max number of recent receipts to return when no actionId is given (default 20)' },
+      },
+    },
+  }),
   readOnlyTool({
     name: 'verify_claim',
     description: 'Check whether a claim has enough tracked evidence before the agent asserts it.',
@@ -843,6 +977,7 @@ const TOOLS = [
       required: ['claim'],
       properties: {
         claim: { type: 'string', description: 'The claim text to verify' },
+        goalContract: GOAL_CONTRACT_SCHEMA,
       },
     },
   }),
@@ -1291,6 +1426,7 @@ const TOOLS = [
         claim: { type: 'string', description: 'The completion claim text to verify (e.g. "Fix shipped", "Tests passing")' },
         mode: { type: 'string', enum: ['blocking', 'advisory'], description: 'blocking (default) returns blocking=true when evidence missing; advisory returns blocking=false' },
         sessionId: { type: 'string', description: 'Optional session id to associate with the gate decision' },
+        goalContract: GOAL_CONTRACT_SCHEMA,
       },
     },
   }),
@@ -1348,8 +1484,40 @@ const TOOLS = [
       },
     },
   }),
+  destructiveTool({
+    name: 'parallel_workflow',
+    description: 'Execute a parallel, multi-step subtask workflow to resolve an objective like a security audit, performance benchmark, or repository inspection.',
+    inputSchema: {
+      type: 'object',
+      required: ['objective'],
+      properties: {
+        objective: { type: 'string', description: 'The objective to plan and execute (e.g. security audit, performance benchmark)' },
+        concurrency: { type: 'number', description: 'Maximum parallel subtasks (default 3)' },
+        timeoutMs: { type: 'number', description: 'Timeout in milliseconds (default 60000)' },
+      },
+    },
+  }),
 ];
 
+// Normalize at export: guarantee EVERY tool carries a human-readable title and a
+// readOnlyHint/destructiveHint annotation (both required by the Connectors
+// Directory; the #1 rejection cause is missing annotations). Tools defined as
+// plain objects (not via readOnlyTool/destructiveTool) are backfilled here:
+// title from the name, and a conservative destructiveHint when no hint is set
+// (so an un-hinted tool is gated rather than silently treated as read-only).
+const NORMALIZED_TOOLS = TOOLS.map((tool) => {
+  const title = tool.title || humanizeTitle(tool.name);
+  const existing = tool.annotations || {};
+  const hasHint = existing.readOnlyHint === true || existing.destructiveHint === true;
+  const annotations = {
+    title,
+    ...existing,
+    ...(hasHint ? {} : { destructiveHint: true }),
+  };
+  return { ...tool, title, annotations };
+});
+
 module.exports = {
-  TOOLS,
+  TOOLS: NORMALIZED_TOOLS,
+  humanizeTitle,
 };

package/scripts/trajectory-scorer.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Trajectory Scorer — Strategic Drift Detection.
+ *
+ * Measures the "Semantic Distance" between the original user intent 
+ * (from primer.md) and the current set of changed files.
+ *
+ * If the agent modifies too many unrelated files, it triggers a safety block.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+function getTrajectoryScore(options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  const primerPath = path.join(projectRoot, 'primer.md');
+
+  if (!fs.existsSync(primerPath)) return { score: 0, isDrifting: false, drift: false };
+
+  const intent = fs.readFileSync(primerPath, 'utf8').toLowerCase();
+  
+  // Get currently modified files (unstaged + staged)
+  let changedFiles = options.changedFiles;
+  if (!changedFiles) {
+    try {
+      const output = execSync('git diff --name-only HEAD', { cwd: projectRoot, encoding: 'utf8' });
+      changedFiles = output.split('\n').filter(f => f.trim());
+    } catch {
+      return { score: 0, isDrifting: false, drift: false };
+    }
+  }
+
+  if (changedFiles.length === 0) return { score: 0, isDrifting: false, drift: false };
+
+  // Calculate drift: How many changed files are NOT mentioned in the intent?
+  let driftCount = 0;
+  for (const file of changedFiles) {
+    const base = path.basename(file).toLowerCase();
+    if (!intent.includes(base)) {
+      driftCount++;
+    }
+  }
+
+  const driftRatio = driftCount / changedFiles.length;
+  const isDrifting = driftRatio > 0.6 && changedFiles.length > 3;
+
+  return {
+    score: Number((1 - driftRatio).toFixed(2)),
+    changedCount: changedFiles.length,
+    driftCount,
+    isDrifting,
+    message: isDrifting 
+      ? `🚫 THUMBGATE: Strategic Drift Detected. You have modified ${changedFiles.length} files, but ${driftCount} of them were not mentioned in the original intent. Please refocus or update the intent.`
+      : null
+  };
+}
+
+module.exports = {
+  getTrajectoryScore
+};

package/scripts/vector-store.js

@@ -172,6 +172,30 @@ async function embedWithGemini(text, options = {}) {
   return values.map(Number);
 }
 
+async function embedWithCoreAI(text, options = {}) {
+  if (process.platform !== 'darwin') {
+    throw new Error('Core AI is only supported on macOS');
+  }
+  const endpoint = process.env.THUMBGATE_COREAI_ENDPOINT || 'http://localhost:8088';
+  try {
+    const res = await fetch(`${endpoint}/embed`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ text, options }),
+      signal: AbortSignal.timeout(2000),
+    });
+    if (res.ok) {
+      const payload = await res.json();
+      if (Array.isArray(payload.embedding)) {
+        return payload.embedding.map(Number);
+      }
+    }
+  } catch (err) {
+    throw new Error(`Core AI local service unavailable: ${err.message}`);
+  }
+  throw new Error('Core AI local service did not return a valid embedding');
+}
+
 async function embed(text, options = {}) {
   if (process.env.THUMBGATE_VECTOR_STUB_EMBED === 'true') {
     // Deterministic 384-dim unit vector: first element = 1.0, rest = 0.0
@@ -180,6 +204,26 @@ async function embed(text, options = {}) {
     return stub;
   }
   const geminiConfig = resolveGeminiEmbeddingConfig();
+  if (geminiConfig.provider === 'coreai') {
+    try {
+      const vector = await embedWithCoreAI(text, options);
+      _lastEmbeddingProfile = {
+        generatedAt: new Date().toISOString(),
+        source: 'local-coreai',
+        activeProfile: {
+          id: 'coreai',
+          model: 'Core AI local model',
+          outputDimensionality: vector.length,
+          task: options.task || 'code retrieval',
+          rationale: 'Local Core AI Apple Silicon accelerated path.',
+        },
+        fallbackUsed: false,
+      };
+      return vector;
+    } catch (coreaiError) {
+      console.warn(`Core AI embedding failed, falling back to local: ${coreaiError.message}`);
+    }
+  }
   if (geminiConfig.enabled) {
     try {
       const vector = await embedWithGemini(text, options);
@@ -312,6 +356,7 @@ function setGeminiEmbedderForTests(loader) {
 module.exports = {
   upsertFeedback,
   searchSimilar,
+  embed,
   TABLE_NAME,
   getEmbeddingConfig,
   getLastEmbeddingProfile,

package/scripts/verify-marketing-pages-deployed.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * verify-marketing-pages-deployed.js — post-deploy probe for top-level
+ * marketing pages.
+ *
+ * Reads `config/post-deploy-marketing-pages.json` and curls every entry
+ * against the live production URL (default
+ * https://thumbgate-production.up.railway.app, overridable via
+ * THUMBGATE_PROD_URL env or --prod-url=…). Each response body must
+ * contain the configured sentinel string and must not contain any configured
+ * `mustNotContain` strings. Any mismatch fails the run and the route is
+ * included in the failure summary.
+ *
+ * Intended to run as a workflow step in .github/workflows/deploy-verify.yml
+ * after the version sentinel check, so the marketing surface is verified
+ * in the same gate as /health and /dashboard. Adding a new marketing
+ * page? Add it to the JSON manifest — no workflow edit required.
+ *
+ * Modes:
+ *   --json    machine-readable report on stdout, suitable for piping
+ *             into the GitHub Actions PR comment step.
+ *   --quiet   suppress per-route lines; only print the final summary.
+ *
+ * Exit code is 0 when every page passes, 1 if any sentinel is missing
+ * or any route returns non-200.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_PROD_URL = 'https://thumbgate-production.up.railway.app';
+const DEFAULT_TIMEOUT_MS = 12000;
+const DEFAULT_MANIFEST_PATH = path.resolve(__dirname, '..', 'config', 'post-deploy-marketing-pages.json');
+
+function parseArgs(argv = []) {
+  const out = {
+    prodUrl: process.env.THUMBGATE_PROD_URL || DEFAULT_PROD_URL,
+    manifestPath: DEFAULT_MANIFEST_PATH,
+    json: false,
+    quiet: false,
+    timeoutMs: DEFAULT_TIMEOUT_MS,
+  };
+  for (const arg of argv) {
+    if (arg === '--json') out.json = true;
+    else if (arg === '--quiet') out.quiet = true;
+    else if (arg.startsWith('--prod-url=')) out.prodUrl = arg.slice('--prod-url='.length);
+    else if (arg.startsWith('--manifest=')) out.manifestPath = arg.slice('--manifest='.length);
+    else if (arg.startsWith('--timeout-ms=')) {
+      const n = Number(arg.slice('--timeout-ms='.length));
+      if (Number.isFinite(n) && n > 0) out.timeoutMs = n;
+    }
+  }
+  return out;
+}
+
+function loadManifest(manifestPath) {
+  const raw = fs.readFileSync(manifestPath, 'utf-8');
+  const parsed = JSON.parse(raw);
+  if (!Array.isArray(parsed.pages) || parsed.pages.length === 0) {
+    throw new Error(`Manifest has no pages: ${manifestPath}`);
+  }
+  for (const entry of parsed.pages) {
+    if (typeof entry.route !== 'string' || !entry.route.startsWith('/')) {
+      throw new Error(`Invalid route in manifest: ${JSON.stringify(entry)}`);
+    }
+    if (typeof entry.sentinel !== 'string' || entry.sentinel.length === 0) {
+      throw new Error(`Invalid sentinel for route ${entry.route}`);
+    }
+    if (entry.mustNotContain != null) {
+      if (!Array.isArray(entry.mustNotContain) || entry.mustNotContain.some((value) => typeof value !== 'string' || value.length === 0)) {
+        throw new Error(`Invalid mustNotContain for route ${entry.route}`);
+      }
+    }
+    if (entry.userAgent != null && (typeof entry.userAgent !== 'string' || entry.userAgent.length === 0)) {
+      throw new Error(`Invalid userAgent for route ${entry.route}`);
+    }
+  }
+  return parsed;
+}
+
+async function probePage({ prodUrl, route, sentinel, mustNotContain = [], userAgent, fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  if (typeof fetchImpl !== 'function') {
+    return { route, ok: false, error: 'fetch_unavailable' };
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const url = `${prodUrl.replace(/\/$/, '')}${route}`;
+    const res = await fetchImpl(url, {
+      signal: controller.signal,
+      headers: {
+        // A real browser-shaped UA so bot-deflection interstitials do not
+        // trigger; this probe is meant to verify the buyer-facing surface.
+        'User-Agent': userAgent || 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36',
+        Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+      },
+    });
+    const body = await res.text().catch(() => '');
+    const sentinelPresent = body.includes(sentinel);
+    const forbiddenPresent = Array.isArray(mustNotContain)
+      ? mustNotContain.filter((value) => body.includes(value))
+      : [];
+    return {
+      route,
+      url,
+      status: res.status,
+      ok: res.ok && sentinelPresent && forbiddenPresent.length === 0,
+      sentinelPresent,
+      forbiddenPresent,
+      bytes: body.length,
+    };
+  } catch (error) {
+    return {
+      route,
+      ok: false,
+      error: error?.name === 'AbortError' ? `timeout_after_${timeoutMs}ms` : (error?.message || String(error)),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function runVerification({ prodUrl, manifestPath, fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const manifest = loadManifest(manifestPath);
+  const results = [];
+  // Sequential is fine — manifest has <20 entries; parallelism would
+  // be over-engineered and would risk masking a per-route rate-limit signal.
+  for (const entry of manifest.pages) {
+    // eslint-disable-next-line no-await-in-loop
+    const result = await probePage({
+      prodUrl,
+      route: entry.route,
+      sentinel: entry.sentinel,
+      mustNotContain: entry.mustNotContain,
+      userAgent: entry.userAgent,
+      fetchImpl,
+      timeoutMs,
+    });
+    results.push({ ...result, sentinel: entry.sentinel, description: entry.description });
+  }
+  const passed = results.filter((r) => r.ok);
+  const failed = results.filter((r) => !r.ok);
+  return {
+    generatedAt: new Date().toISOString(),
+    prodUrl,
+    manifestVersion: manifest.version,
+    totalRoutes: results.length,
+    passedCount: passed.length,
+    failedCount: failed.length,
+    verdict: failed.length === 0 ? 'pass' : 'fail',
+    results,
+  };
+}
+
+function renderHuman(report, { quiet = false } = {}) {
+  const lines = [];
+  if (!quiet) {
+    for (const r of report.results) {
+      if (r.ok) {
+        lines.push(`✅ ${r.route.padEnd(20)}  HTTP ${r.status}  bytes=${r.bytes}  sentinel-OK`);
+      } else if (r.error) {
+        lines.push(`❌ ${r.route.padEnd(20)}  ERROR ${r.error}`);
+      } else if (!r.sentinelPresent) {
+        lines.push(`❌ ${r.route.padEnd(20)}  HTTP ${r.status}  sentinel MISSING (expected: ${JSON.stringify(r.sentinel)})`);
+      } else if (Array.isArray(r.forbiddenPresent) && r.forbiddenPresent.length > 0) {
+        lines.push(`❌ ${r.route.padEnd(20)}  HTTP ${r.status}  forbidden content PRESENT (${r.forbiddenPresent.map((value) => JSON.stringify(value)).join(', ')})`);
+      } else {
+        lines.push(`❌ ${r.route.padEnd(20)}  HTTP ${r.status}`);
+      }
+    }
+  }
+  lines.push(`\nSummary: ${report.passedCount}/${report.totalRoutes} pages passed against ${report.prodUrl} (verdict: ${report.verdict.toUpperCase()})`);
+  return lines.join('\n');
+}
+
+async function main(argv) {
+  const args = parseArgs(argv);
+  let report;
+  try {
+    report = await runVerification({
+      prodUrl: args.prodUrl,
+      manifestPath: args.manifestPath,
+      timeoutMs: args.timeoutMs,
+    });
+  } catch (error) {
+    process.stderr.write(`verify-marketing-pages-deployed FAILED: ${error.message}\n`);
+    process.exit(2);
+  }
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  } else {
+    process.stdout.write(`${renderHuman(report, { quiet: args.quiet })}\n`);
+  }
+  process.exitCode = report.verdict === 'pass' ? 0 : 1;
+}
+
+module.exports = {
+  DEFAULT_PROD_URL,
+  DEFAULT_TIMEOUT_MS,
+  DEFAULT_MANIFEST_PATH,
+  parseArgs,
+  loadManifest,
+  probePage,
+  runVerification,
+  renderHuman,
+};
+
+if (path.resolve(process.argv[1] || '') === path.resolve(__filename)) {
+  main(process.argv.slice(2));
+}