@jacfrost/autopm 0.0.1

package/src/autopm/venture-commands.js

@@ -0,0 +1,1707 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  ANALYST_STAGE,
+  COLLECTOR_STAGE,
+  NORMALIZER_STAGE,
+  PM_WRITER_STAGE,
+  SKEPTIC_STAGE,
+  VENTURE_SIGNAL_LATEST_PATH,
+  analystRunSummaryPath,
+  analystTrendScoresPath,
+  collectorDiagnosticsPath,
+  collectorRunSummaryPath,
+  normalizeVentureEntityId,
+  normalizeVentureRunId,
+  normalizerAliasesPath,
+  normalizerCompaniesPath,
+  normalizerDiagnosticsIndexPath,
+  normalizerDiagnosticsPath,
+  normalizerInvestorsPath,
+  normalizerRunSummaryPath,
+  normalizerSignalsPath,
+  normalizerTaxonomyMappingsPath,
+  normalizerTrendsPath,
+  pmWriterDailyRadarPath,
+  pmWriterDiagnosticsPath,
+  pmWriterRunSummaryPath,
+  pmWriterSectorMemoPath,
+} from '../venture-signal/contracts.js';
+import { getDefaultFreeVentureSourceBundle } from '../venture-signal/default-sources.js';
+import {
+  analysisAnalystDiagnosticsPath,
+  analysisSkepticChallengedClaimsPath,
+  analysisSkepticDiagnosticsPath,
+  analysisSkepticReviewPath,
+  runVentureSignalAnalysis,
+  runVentureSignalCollector,
+  runVentureSignalNormalizer,
+} from '../venture-signal/runner.js';
+import { SECRET_LOOKING_PATTERN } from '../venture-signal/schemas.js';
+
+export const VENTURE_COMMAND_NAME = 'venture';
+export const VENTURE_SOURCES_TOOL_NAME = 'venture_signal_sources';
+export const VENTURE_RUN_TOOL_NAME = 'venture_signal_run';
+export const VENTURE_NORMALIZE_TOOL_NAME = 'venture_signal_normalize';
+export const VENTURE_ANALYZE_TOOL_NAME = 'venture_signal_analyze';
+export const VENTURE_LATEST_TOOL_NAME = 'venture_signal_latest';
+export const VENTURE_INSPECT_COLLECTOR_TOOL_NAME = 'venture_signal_inspect_collector';
+export const VENTURE_INSPECT_NORMALIZER_TOOL_NAME = 'venture_signal_inspect_normalizer';
+export const VENTURE_INSPECT_ANALYST_TOOL_NAME = 'venture_signal_inspect_analyst';
+export const VENTURE_INSPECT_SKEPTIC_TOOL_NAME = 'venture_signal_inspect_skeptic';
+export const VENTURE_RADAR_TOOL_NAME = 'venture_signal_radar';
+export const VENTURE_MEMO_TOOL_NAME = 'venture_signal_memo';
+
+const SECRET_LOOKING_REGEX = new RegExp(SECRET_LOOKING_PATTERN, 'g');
+const SECRET_FLAG_NAME_PATTERN = /(?:^|[-_])(api[-_]?key|authorization|auth[-_]?token|access[-_]?token|refresh[-_]?token|secret|password|passwd|credential|token)(?:$|[-_])/i;
+const SAFE_FLAG_NAME_PATTERN = /^--[A-Za-z][A-Za-z0-9-]{0,63}$/;
+const DEFAULT_NOW = '2026-05-18T12:00:00.000Z';
+
+const DEFAULT_FREE_SOURCE_RECORDS = Object.freeze([]);
+const DEFAULT_FREE_ANALYSIS_SOURCE_RECORDS = Object.freeze([]);
+
+
+export const VENTURE_SOURCES_TOOL_PARAMETERS = Object.freeze({
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    projectRoot: { type: 'string', description: 'Project root to inspect. Source listing is static and does not mutate the workspace.' },
+  },
+});
+
+export const VENTURE_RUN_TOOL_PARAMETERS = Object.freeze({
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    projectRoot: { type: 'string', description: 'Project root where .autopm/venture-signal Collector artifacts should be written.' },
+    runId: { type: 'string', description: 'Optional safe Collector run ID. Defaults to a generated collector-* ID.' },
+    now: { type: 'string', description: 'Optional ISO timestamp for deterministic local tests.' },
+    sourceRecords: {
+      type: 'array',
+      description: 'Optional authorized public source records. When omitted, the tool records source availability but does not synthesize evidence.',
+      items: { type: 'object', additionalProperties: true },
+    },
+  },
+});
+
+export const VENTURE_NORMALIZE_TOOL_PARAMETERS = Object.freeze({
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    projectRoot: { type: 'string', description: 'Project root where .autopm/venture-signal Collector and Normalizer artifacts should be written.' },
+    runId: { type: 'string', description: 'Optional safe Normalizer run ID. Defaults to a generated normalizer-* ID.' },
+    now: { type: 'string', description: 'Optional ISO timestamp for deterministic local tests.' },
+    sourceBundle: {
+      type: 'object',
+      description: 'Optional authorized public source bundle metadata. Defaults to the built-in free source bundle.',
+      additionalProperties: true,
+    },
+    sourceRecords: {
+      type: 'array',
+      description: 'Optional authorized public source records. When omitted, the tool records source availability but does not synthesize evidence.',
+      items: { type: 'object', additionalProperties: true },
+    },
+  },
+});
+
+export const VENTURE_ANALYZE_TOOL_PARAMETERS = Object.freeze({
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    projectRoot: { type: 'string', description: 'Project root where .autopm/venture-signal Collector, Normalizer, Analyst, and Skeptic artifacts should be written.' },
+    runId: { type: 'string', description: 'Optional safe Analysis run ID. Defaults to a generated analysis-* ID.' },
+    now: { type: 'string', description: 'Optional ISO timestamp for deterministic local tests.' },
+    sourceBundle: {
+      type: 'object',
+      description: 'Optional authorized public source bundle metadata. Defaults to the built-in free source bundle.',
+      additionalProperties: true,
+    },
+    sourceRecords: {
+      type: 'array',
+      description: 'Optional authorized public source records. When omitted, the tool records source availability but does not synthesize evidence.',
+      items: { type: 'object', additionalProperties: true },
+    },
+  },
+});
+
+export const VENTURE_LATEST_TOOL_PARAMETERS = Object.freeze({
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    projectRoot: { type: 'string', description: 'Project root containing .autopm/venture-signal/latest.json.' },
+  },
+});
+
+export const VENTURE_INSPECT_COLLECTOR_TOOL_PARAMETERS = Object.freeze({
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    projectRoot: { type: 'string', description: 'Project root containing Venture Signal Collector artifacts.' },
+    runId: { type: 'string', description: 'Optional safe Collector run ID. When omitted, latest.json selects the run.' },
+    stage: { type: 'string', enum: [COLLECTOR_STAGE], description: 'Stage to inspect with this Collector-specific tool.', default: COLLECTOR_STAGE },
+  },
+});
+
+export const VENTURE_INSPECT_NORMALIZER_TOOL_PARAMETERS = Object.freeze({
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    projectRoot: { type: 'string', description: 'Project root containing Venture Signal Normalizer artifacts.' },
+    runId: { type: 'string', description: 'Optional safe Normalizer run ID. When omitted, latest.json must select a Normalizer run.' },
+    stage: { type: 'string', enum: [NORMALIZER_STAGE], description: 'Stage to inspect with this Normalizer-specific tool.', default: NORMALIZER_STAGE },
+  },
+});
+
+export const VENTURE_INSPECT_ANALYST_TOOL_PARAMETERS = Object.freeze({
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    projectRoot: { type: 'string', description: 'Project root containing Venture Signal Analyst artifacts.' },
+    runId: { type: 'string', description: 'Optional safe Analysis run ID. When omitted, latest.json must select an Analyst/Skeptic analysis run.' },
+    stage: { type: 'string', enum: [ANALYST_STAGE], description: 'Stage to inspect with this Analyst-specific tool.', default: ANALYST_STAGE },
+  },
+});
+
+export const VENTURE_INSPECT_SKEPTIC_TOOL_PARAMETERS = Object.freeze({
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    projectRoot: { type: 'string', description: 'Project root containing Venture Signal Skeptic artifacts.' },
+    runId: { type: 'string', description: 'Optional safe Analysis run ID. When omitted, latest.json must select a Skeptic analysis run.' },
+    stage: { type: 'string', enum: [SKEPTIC_STAGE], description: 'Stage to inspect with this Skeptic-specific tool.', default: SKEPTIC_STAGE },
+  },
+});
+
+export const VENTURE_RADAR_TOOL_PARAMETERS = Object.freeze({
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    projectRoot: { type: 'string', description: 'Project root containing PM Writer daily radar artifacts.' },
+    runId: { type: 'string', description: 'Optional safe PM Writer run ID. When omitted, latest.json must select a PM Writer run.' },
+  },
+});
+
+export const VENTURE_MEMO_TOOL_PARAMETERS = Object.freeze({
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    projectRoot: { type: 'string', description: 'Project root containing PM Writer sector memo artifacts.' },
+    runId: { type: 'string', description: 'Optional safe PM Writer run ID. When omitted, latest.json must select a PM Writer run.' },
+    marketTrendId: { type: 'string', description: 'Optional PM Writer market trend ID. When omitted, latest.json selects the primary sector memo path.' },
+  },
+});
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function normalizeArgs(args) {
+  return typeof args === 'string' ? args.trim() : '';
+}
+
+function safeFlagName(value) {
+  const raw = String(value ?? '');
+  const equalsIndex = raw.indexOf('=');
+  const name = equalsIndex >= 0 ? raw.slice(0, equalsIndex) : raw;
+  if (!SAFE_FLAG_NAME_PATTERN.test(name) || SECRET_FLAG_NAME_PATTERN.test(name)) return '--[redacted]';
+  return name;
+}
+
+function redactSensitiveText(value) {
+  return String(value ?? '')
+    .replace(SECRET_LOOKING_REGEX, '[redacted]')
+    .replace(/([A-Z0-9_]*(?:API[-_]?KEY|AUTH(?:ORIZATION)?|ACCESS[-_]?TOKEN|REFRESH[-_]?TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|TOKEN)[A-Z0-9_]*\s*[=:]\s*)[^\s,;)}\]]+/gi, '$1[redacted]');
+}
+
+function uniqueCodes(values) {
+  return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))];
+}
+
+function diagnostic(code, message, details = {}, severity = 'error') {
+  return {
+    code,
+    severity,
+    message: redactSensitiveText(message),
+    timestamp: new Date().toISOString(),
+    details: Object.fromEntries(Object.entries(details).map(([key, value]) => [key, typeof value === 'string' ? redactSensitiveText(value) : value])),
+  };
+}
+
+function baseEnvelope(subcommand, fields = {}) {
+  const warnings = Array.isArray(fields.warnings) ? fields.warnings : [];
+  const errors = Array.isArray(fields.errors) ? fields.errors : [];
+  return {
+    command: VENTURE_COMMAND_NAME,
+    subcommand,
+    implemented: true,
+    delegatedLegacyCommand: null,
+    status: fields.status ?? (errors.length > 0 ? 'error' : 'ok'),
+    generatedAt: fields.generatedAt ?? new Date().toISOString(),
+    artifactPathsRead: Array.isArray(fields.artifactPathsRead) ? fields.artifactPathsRead : [],
+    artifactPathsWritten: Array.isArray(fields.artifactPathsWritten) ? fields.artifactPathsWritten : [],
+    warningCodes: Array.isArray(fields.warningCodes) ? fields.warningCodes : uniqueCodes(warnings.map((warning) => warning?.code)),
+    errorCodes: Array.isArray(fields.errorCodes) ? fields.errorCodes : uniqueCodes(errors.map((error) => error?.code)),
+    warnings,
+    errors,
+    durableStateChanged: fields.durableStateChanged === true,
+    safeNextAction: fields.safeNextAction ?? null,
+    nextAction: fields.nextAction ?? fields.safeNextAction?.command ?? null,
+    ...fields.extra,
+  };
+}
+
+function commandUsageText() {
+  return [
+    'Venture Signal diagnostics are internal tool surfaces. Use /opportunities for the operator workflow.',
+    'Internal tool surfaces:',
+    `  ${VENTURE_SOURCES_TOOL_NAME}                    - list the default free Venture Signal source bundle`,
+    `  ${VENTURE_RUN_TOOL_NAME}                        - run local Collector intake with supplied authorized source records`,
+    `  ${VENTURE_NORMALIZE_TOOL_NAME}                  - run local Collector intake plus Normalizer artifacts`,
+    `  ${VENTURE_ANALYZE_TOOL_NAME}                    - run Collector, Normalizer, Signal Analyst, and Skeptic artifacts`,
+    `  ${VENTURE_LATEST_TOOL_NAME}                     - read .autopm/venture-signal/latest.json`,
+    `  ${VENTURE_RADAR_TOOL_NAME}                      - inspect PM Writer daily radar output`,
+    `  ${VENTURE_MEMO_TOOL_NAME}                       - inspect the primary PM Writer sector memo output`,
+    `  ${VENTURE_INSPECT_COLLECTOR_TOOL_NAME}          - inspect latest Collector summary and diagnostics`,
+    `  ${VENTURE_INSPECT_NORMALIZER_TOOL_NAME}         - inspect latest Normalizer summary, diagnostics, and aggregates`,
+    `  ${VENTURE_INSPECT_ANALYST_TOOL_NAME}            - inspect latest Analyst score components, warnings, and diagnostics`,
+    `  ${VENTURE_INSPECT_SKEPTIC_TOOL_NAME}            - inspect latest Skeptic challenges, confidence adjustments, and diagnostics`,
+  ].join('\n');
+}
+
+function inspectToolNameForStage(stage) {
+  if (stage === NORMALIZER_STAGE) return VENTURE_INSPECT_NORMALIZER_TOOL_NAME;
+  if (stage === ANALYST_STAGE) return VENTURE_INSPECT_ANALYST_TOOL_NAME;
+  if (stage === SKEPTIC_STAGE) return VENTURE_INSPECT_SKEPTIC_TOOL_NAME;
+  return VENTURE_INSPECT_COLLECTOR_TOOL_NAME;
+}
+
+function parseVentureArgs(args) {
+  const tokens = normalizeArgs(args).split(/\s+/).filter(Boolean);
+  const state = {
+    subcommand: null,
+    json: false,
+    help: false,
+    runId: undefined,
+    stage: undefined,
+    marketTrendId: undefined,
+    errors: [],
+  };
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === '--json') {
+      state.json = true;
+      continue;
+    }
+    if (token === 'help' || token === '-h' || token === '--help') {
+      state.help = true;
+      continue;
+    }
+    if (token === '--run-id') {
+      const value = tokens[index + 1];
+      if (typeof value !== 'string' || value.trim() === '' || value.startsWith('--')) {
+        state.errors.push('Flag --run-id requires a non-empty value.');
+      } else {
+        state.runId = value.trim();
+        index += 1;
+      }
+      continue;
+    }
+    if (token.startsWith('--run-id=')) {
+      const value = token.slice('--run-id='.length).trim();
+      if (value === '') state.errors.push('Flag --run-id requires a non-empty value.');
+      else state.runId = value;
+      continue;
+    }
+    if (token === '--stage') {
+      const value = tokens[index + 1];
+      if (typeof value !== 'string' || value.trim() === '' || value.startsWith('--')) {
+        state.errors.push('Flag --stage requires a non-empty value.');
+      } else {
+        state.stage = value.trim();
+        index += 1;
+      }
+      continue;
+    }
+    if (token.startsWith('--stage=')) {
+      const value = token.slice('--stage='.length).trim();
+      if (value === '') state.errors.push('Flag --stage requires a non-empty value.');
+      else state.stage = value;
+      continue;
+    }
+    if (token === '--market-trend-id') {
+      const value = tokens[index + 1];
+      if (typeof value !== 'string' || value.trim() === '' || value.startsWith('--')) {
+        state.errors.push('Flag --market-trend-id requires a non-empty value.');
+      } else {
+        state.marketTrendId = value.trim();
+        index += 1;
+      }
+      continue;
+    }
+    if (token.startsWith('--market-trend-id=')) {
+      const value = token.slice('--market-trend-id='.length).trim();
+      if (value === '') state.errors.push('Flag --market-trend-id requires a non-empty value.');
+      else state.marketTrendId = value;
+      continue;
+    }
+    if (token.startsWith('--')) {
+      state.errors.push(`Unsupported flag: ${safeFlagName(token)}`);
+      continue;
+    }
+    if (['sources', 'run', 'normalize', 'analyze', 'latest', 'inspect', 'radar', 'memo'].includes(token)) {
+      if (state.subcommand && state.subcommand !== token) {
+        state.errors.push('Unexpected subcommand: [redacted-subcommand]');
+      } else {
+        state.subcommand = token;
+      }
+      continue;
+    }
+    state.errors.push('Unknown subcommand: [redacted-subcommand]');
+  }
+
+  state.subcommand ??= state.help ? 'help' : 'sources';
+  if (state.runId && !['run', 'normalize', 'analyze', 'inspect', 'radar', 'memo'].includes(state.subcommand)) {
+    state.errors.push(`Unsupported flag for ${state.subcommand}: --run-id`);
+  }
+  if (state.stage && state.subcommand !== 'inspect') {
+    state.errors.push(`Unsupported flag for ${state.subcommand}: --stage`);
+  }
+  if (state.marketTrendId && state.subcommand !== 'memo') {
+    state.errors.push(`Unsupported flag for ${state.subcommand}: --market-trend-id`);
+  }
+  if (state.subcommand === 'inspect' && ![COLLECTOR_STAGE, NORMALIZER_STAGE, ANALYST_STAGE, SKEPTIC_STAGE].includes(state.stage ?? COLLECTOR_STAGE)) {
+    state.errors.push('CLI_ARG_STAGE_UNSUPPORTED: Venture Signal inspect supports stage collector, normalizer, analyst, or skeptic.');
+  }
+
+  return state;
+}
+
+function summarizeSource(source) {
+  return {
+    sourceId: source.sourceId,
+    name: source.name,
+    category: source.category,
+    kind: source.kind,
+    optionality: source.optionality,
+    enabled: source.enabled !== false,
+    access: {
+      mode: source.access?.mode ?? 'unknown',
+      requiresCredential: source.access?.requiresCredential === true,
+      networkAccess: source.access?.networkAccess === true,
+      credentialEnvKey: source.access?.credentialEnvKey ?? null,
+      complianceNote: source.access?.complianceNote ?? null,
+      documentationUrl: source.access?.documentationUrl ?? null,
+    },
+    rights: {
+      status: source.rights?.status ?? 'unknown',
+      attributionRequired: source.rights?.attributionRequired === true,
+      termsUrl: source.rights?.termsUrl ?? null,
+      lastReviewedAt: source.rights?.lastReviewedAt ?? null,
+    },
+    freshnessExpectation: source.freshnessExpectation ?? null,
+    adapter: {
+      name: source.adapter?.name ?? null,
+      version: source.adapter?.version ?? null,
+      pollingEnabled: source.adapter?.config?.polling?.enabled === true,
+    },
+  };
+}
+
+export function listVentureSources() {
+  const bundle = getDefaultFreeVentureSourceBundle();
+  const sources = bundle.sources.map(summarizeSource);
+  const paidExtensions = bundle.paidExtensions.map(summarizeSource);
+  return baseEnvelope('sources', {
+    status: 'ok',
+    durableStateChanged: false,
+    safeNextAction: { command: VENTURE_RUN_TOOL_NAME, reason: 'Run the local Collector with supplied authorized source records when artifacts are needed.' },
+    extra: {
+      bundleId: bundle.bundleId,
+      schemaVersion: bundle.schemaVersion,
+      model: bundle.model,
+      sourceCounts: {
+        free: sources.length,
+        required: sources.filter((source) => source.optionality === 'required').length,
+        optional: sources.filter((source) => source.optionality === 'optional').length,
+        paidExtensions: paidExtensions.length,
+        requiringCredentialsInDefaultFreeBundle: sources.filter((source) => source.access.requiresCredential).length,
+      },
+      accessModes: uniqueCodes(sources.map((source) => source.access.mode)).sort(),
+      rightsStatuses: uniqueCodes(sources.map((source) => source.rights.status)).sort(),
+      sources,
+      paidExtensions,
+      credentialRequired: false,
+      paidCredentialRequired: false,
+      compliance: {
+        defaultBundle: 'free-public-and-operator-provided-only',
+        paidExtensions: 'disabled-extension-metadata-only',
+      },
+    },
+  });
+}
+
+function runRecords(params = {}) {
+  return Array.isArray(params.sourceRecords) ? params.sourceRecords : clone(DEFAULT_FREE_SOURCE_RECORDS);
+}
+
+function analysisRunRecords(params = {}) {
+  return Array.isArray(params.sourceRecords)
+    ? params.sourceRecords
+    : clone([...DEFAULT_FREE_SOURCE_RECORDS, ...DEFAULT_FREE_ANALYSIS_SOURCE_RECORDS]);
+}
+
+export async function runVentureCollectorCommand(params = {}) {
+  try {
+    const result = await runVentureSignalCollector({
+      rootDir: params.projectRoot,
+      runId: params.runId,
+      now: params.now ?? DEFAULT_NOW,
+      sourceRecords: runRecords(params),
+      sourceBundle: getDefaultFreeVentureSourceBundle(),
+      includePaidExtensions: false,
+    });
+    return baseEnvelope('run', {
+      status: result.status,
+      generatedAt: result.summary?.completedAt,
+      artifactPathsRead: [],
+      artifactPathsWritten: result.written,
+      warningCodes: result.status === 'warn' ? uniqueCodes(result.diagnostics.filter((entry) => entry.severity === 'warning').map((entry) => entry.code)) : [],
+      errorCodes: result.status === 'error' ? uniqueCodes(result.diagnostics.filter((entry) => entry.severity === 'error').map((entry) => entry.code)) : [],
+      warnings: result.diagnostics.filter((entry) => entry.severity === 'warning'),
+      errors: result.diagnostics.filter((entry) => entry.severity === 'error'),
+      durableStateChanged: result.written.length > 0,
+      safeNextAction: { command: VENTURE_INSPECT_COLLECTOR_TOOL_NAME, reason: 'Inspect Collector diagnostics and latest promotion before downstream stages consume artifacts.' },
+      extra: {
+        runId: result.runId,
+        role: result.role,
+        stage: result.stage,
+        summaryPath: result.summaryPath,
+        diagnosticsPath: result.diagnosticsPath,
+        latestPath: result.latestPath,
+        latestPromoted: result.latestPromoted,
+        previousLatestPreserved: result.previousLatestPreserved,
+        sourceCounts: result.summary?.sourceCounts ?? null,
+        accessModes: result.summary?.accessModes ?? [],
+        rightsStatuses: result.summary?.rightsStatuses ?? [],
+      },
+    });
+  } catch (error) {
+    const code = error?.name === 'AbortError' ? 'VENTURE_COLLECTOR_RUN_ABORTED' : 'VENTURE_COLLECTOR_RUN_FAILED';
+    return baseEnvelope('run', {
+      status: 'error',
+      errors: [diagnostic(code, 'Venture Signal Collector run failed before producing a complete result.', { reason: error instanceof Error ? error.message : String(error) })],
+      durableStateChanged: false,
+      safeNextAction: { command: VENTURE_SOURCES_TOOL_NAME, reason: 'Inspect source bundle and retry with a safe run ID.' },
+      extra: { runId: null, latestPromoted: false },
+    });
+  }
+}
+
+function normalizerAggregatePaths(runId) {
+  const normalizedRunId = normalizeVentureRunId(runId);
+  return {
+    companies: normalizerCompaniesPath(normalizedRunId),
+    investors: normalizerInvestorsPath(normalizedRunId),
+    trends: normalizerTrendsPath(normalizedRunId),
+    signals: normalizerSignalsPath(normalizedRunId),
+    aliases: normalizerAliasesPath(normalizedRunId),
+    taxonomyMappings: normalizerTaxonomyMappingsPath(normalizedRunId),
+    diagnosticsIndex: normalizerDiagnosticsIndexPath(normalizedRunId),
+  };
+}
+
+export async function runVentureNormalizerCommand(params = {}) {
+  try {
+    const result = await runVentureSignalNormalizer({
+      rootDir: params.projectRoot,
+      runId: params.runId,
+      now: params.now ?? DEFAULT_NOW,
+      sourceRecords: runRecords(params),
+      sourceBundle: isPlainObject(params.sourceBundle) ? params.sourceBundle : getDefaultFreeVentureSourceBundle(),
+      includePaidExtensions: false,
+    });
+    const warnings = result.diagnostics.filter((entry) => entry.severity === 'warning');
+    const errors = result.diagnostics.filter((entry) => entry.severity === 'error');
+    return baseEnvelope('normalize', {
+      status: result.status,
+      generatedAt: result.summary?.completedAt,
+      artifactPathsRead: [],
+      artifactPathsWritten: result.written,
+      warningCodes: uniqueCodes(warnings.map((entry) => entry.code)),
+      errorCodes: uniqueCodes(errors.map((entry) => entry.code)),
+      warnings,
+      errors,
+      durableStateChanged: result.written.length > 0,
+      safeNextAction: { command: VENTURE_INSPECT_NORMALIZER_TOOL_NAME, reason: 'Inspect Normalizer diagnostics, duplicate-resolution decisions, and aggregate artifacts before scoring.' },
+      extra: {
+        runId: result.runId,
+        role: result.role,
+        stage: result.stage,
+        stageStatuses: result.stageStatuses,
+        summaryPath: result.summaryPath,
+        diagnosticsPath: result.diagnosticsPath,
+        aggregatePaths: {
+          ...result.aggregatePaths,
+          aliases: normalizerAliasesPath(result.runId),
+          taxonomyMappings: normalizerTaxonomyMappingsPath(result.runId),
+        },
+        latestPath: result.latestPath,
+        latestPromoted: result.latestPromoted,
+        previousLatestPreserved: result.previousLatestPreserved,
+        normalizerCounts: result.summary?.counts ?? null,
+      },
+    });
+  } catch (error) {
+    const code = error?.name === 'AbortError' ? 'VENTURE_NORMALIZER_RUN_ABORTED' : 'VENTURE_NORMALIZER_RUN_FAILED';
+    return baseEnvelope('normalize', {
+      status: 'error',
+      errors: [diagnostic(code, 'Venture Signal Normalizer run failed before producing a complete result.', { reason: error instanceof Error ? error.message : String(error) })],
+      durableStateChanged: false,
+      safeNextAction: { command: VENTURE_RUN_TOOL_NAME, reason: 'Create and inspect a valid Collector run before retrying normalization.' },
+      extra: { runId: null, latestPromoted: false, normalizerCounts: null },
+    });
+  }
+}
+
+function diagnosticIsWarning(entry) {
+  return entry?.severity === 'warning' || entry?.status === 'warn';
+}
+
+function diagnosticIsError(entry) {
+  return entry?.severity === 'error' || entry?.status === 'error';
+}
+
+function trendScoreSummary(trendScore) {
+  return {
+    marketTrendId: trendScore?.marketTrendId ?? null,
+    rank: trendScore?.rank ?? null,
+    score: trendScore?.score ?? null,
+    confidenceScore: trendScore?.confidence?.score ?? null,
+    confidenceDowngraded: trendScore?.confidence?.downgraded === true,
+    downgradeReasons: Array.isArray(trendScore?.confidence?.downgradeReasons) ? trendScore.confidence.downgradeReasons : [],
+    artifactPath: trendScore?.artifactPath ?? null,
+    componentCount: Array.isArray(trendScore?.components) ? trendScore.components.length : 0,
+    missingEvidenceWarnings: Array.isArray(trendScore?.components)
+      ? trendScore.components.flatMap((component) => Array.isArray(component?.missingEvidenceWarnings) ? component.missingEvidenceWarnings : [])
+      : [],
+  };
+}
+
+function challengeTypeCounts(challenges) {
+  const counts = {};
+  for (const challenge of challenges) {
+    const type = typeof challenge?.challengeType === 'string' && challenge.challengeType.length > 0 ? challenge.challengeType : 'unknown';
+    counts[type] = (counts[type] ?? 0) + 1;
+  }
+  return counts;
+}
+
+export async function runVentureAnalysisCommand(params = {}) {
+  try {
+    const result = await runVentureSignalAnalysis({
+      rootDir: params.projectRoot,
+      runId: params.runId,
+      now: params.now ?? DEFAULT_NOW,
+      sourceRecords: analysisRunRecords(params),
+      sourceBundle: isPlainObject(params.sourceBundle) ? params.sourceBundle : getDefaultFreeVentureSourceBundle(),
+      includePaidExtensions: false,
+    });
+    const allDiagnostics = [...(result.analystDiagnostics ?? []), ...(result.skepticDiagnostics ?? [])];
+    const warnings = allDiagnostics.filter(diagnosticIsWarning);
+    const errors = allDiagnostics.filter(diagnosticIsError);
+    const trendScoreSummaries = Array.isArray(result.summary?.trendScores)
+      ? result.summary.trendScores.map(trendScoreSummary)
+      : [];
+    const challengedClaims = Array.isArray(result.challengedClaims) ? result.challengedClaims : [];
+    return baseEnvelope('analyze', {
+      status: result.status,
+      generatedAt: result.summary?.completedAt,
+      artifactPathsRead: [],
+      artifactPathsWritten: result.written,
+      warningCodes: uniqueCodes(warnings.map((entry) => entry.code)),
+      errorCodes: uniqueCodes(errors.map((entry) => entry.code)),
+      warnings,
+      errors,
+      durableStateChanged: result.written.length > 0,
+      safeNextAction: { command: VENTURE_INSPECT_SKEPTIC_TOOL_NAME, reason: 'Inspect Skeptic challenges, confidence adjustments, bubble-risk rationale, and safety language before PM recommendations.' },
+      extra: {
+        runId: result.runId,
+        role: result.role,
+        stage: result.stage,
+        stageStatuses: result.stageStatuses,
+        summaryPath: result.summaryPath,
+        diagnosticsPath: result.diagnosticsPath,
+        analystPaths: result.analystPaths,
+        skepticPaths: result.skepticPaths,
+        latestPath: result.latestPath,
+        latestPromoted: result.latestPromoted,
+        previousLatestPreserved: result.previousLatestPreserved,
+        analysisCounts: result.analystSummary?.counts ?? null,
+        skepticCounts: {
+          challengedClaims: challengedClaims.length,
+          confidenceAdjustments: Array.isArray(result.confidenceAdjustments) ? result.confidenceAdjustments.length : 0,
+          diagnostics: Array.isArray(result.skepticDiagnostics) ? result.skepticDiagnostics.length : 0,
+        },
+        trendScoreSummaries,
+        challengeTypeCounts: challengeTypeCounts(challengedClaims),
+        safety: result.summary?.safety ?? null,
+      },
+    });
+  } catch (error) {
+    const code = error?.name === 'AbortError' ? 'VENTURE_ANALYSIS_RUN_ABORTED' : 'VENTURE_ANALYSIS_RUN_FAILED';
+    return baseEnvelope('analyze', {
+      status: 'error',
+      errors: [diagnostic(code, 'Venture Signal Analysis run failed before producing a complete result.', { reason: error instanceof Error ? error.message : String(error) })],
+      durableStateChanged: false,
+      safeNextAction: { command: VENTURE_NORMALIZE_TOOL_NAME, reason: 'Create and inspect valid Normalizer artifacts before retrying analysis.' },
+      extra: { runId: null, latestPromoted: false, analysisCounts: null, skepticCounts: null },
+    });
+  }
+}
+
+async function readJsonArtifact(projectRoot, relativePath) {
+  const root = path.resolve(typeof projectRoot === 'string' && projectRoot.trim() !== '' ? projectRoot : process.cwd());
+  const destination = path.resolve(root, relativePath);
+  if (destination !== root && !destination.startsWith(`${root}${path.sep}`)) {
+    throw new TypeError(`Refusing to read Venture artifact outside project root: ${relativePath}.`);
+  }
+  return JSON.parse(await readFile(destination, 'utf8'));
+}
+
+export async function readVentureLatest(params = {}) {
+  try {
+    const latest = await readJsonArtifact(params.projectRoot, VENTURE_SIGNAL_LATEST_PATH);
+    const stage = [COLLECTOR_STAGE, NORMALIZER_STAGE, ANALYST_STAGE, SKEPTIC_STAGE, PM_WRITER_STAGE].includes(latest.stage) ? latest.stage : COLLECTOR_STAGE;
+    const safeNextCommand = stage === PM_WRITER_STAGE ? VENTURE_RADAR_TOOL_NAME : inspectToolNameForStage(stage);
+    const safeNextReason = stage === PM_WRITER_STAGE ? 'Inspect the PM Writer daily radar behind latest.json.' : `Inspect the ${stage} summary and diagnostics behind latest.json.`;
+    return baseEnvelope('latest', {
+      status: latest.status ?? 'ok',
+      generatedAt: latest.updatedAt,
+      artifactPathsRead: [VENTURE_SIGNAL_LATEST_PATH],
+      durableStateChanged: false,
+      safeNextAction: { command: safeNextCommand, reason: safeNextReason },
+      extra: {
+        latestPath: VENTURE_SIGNAL_LATEST_PATH,
+        latest,
+        runId: latest.runId,
+        stage: latest.stage,
+        summaryPath: latest.summaryPath,
+        diagnosticsPath: latest.diagnosticsPath,
+        sourceCounts: latest.sourceCounts,
+        freshness: latest.freshness,
+        promotion: latest.promotion,
+      },
+    });
+  } catch (error) {
+    const code = 'VENTURE_LATEST_UNAVAILABLE';
+    return baseEnvelope('latest', {
+      status: 'error',
+      artifactPathsRead: [VENTURE_SIGNAL_LATEST_PATH],
+      errors: [diagnostic(code, 'Venture Signal latest artifact is unavailable or malformed.', { reason: error instanceof Error ? error.message : String(error) })],
+      durableStateChanged: false,
+      safeNextAction: { command: VENTURE_RUN_TOOL_NAME, reason: 'Create a Collector run before reading latest state.' },
+      extra: { latestPath: VENTURE_SIGNAL_LATEST_PATH, latest: null },
+    });
+  }
+}
+
+function pmWriterLatestAllowed(latest) {
+  if (!isPlainObject(latest) || latest.stage !== PM_WRITER_STAGE) {
+    throw new TypeError(`Latest Venture Signal pointer is ${latest?.stage ?? 'unknown'}, not pm-writer.`);
+  }
+}
+
+function pmWriterDiagnosticsSummary(diagnosticsArtifact) {
+  const diagnostics = Array.isArray(diagnosticsArtifact?.diagnostics) ? diagnosticsArtifact.diagnostics : [];
+  const warnings = diagnostics.filter(diagnosticIsWarning);
+  const errors = diagnostics.filter(diagnosticIsError);
+  return {
+    diagnostics,
+    warnings,
+    errors,
+    warningCodes: uniqueCodes(warnings.map((entry) => entry.code)),
+    errorCodes: uniqueCodes(errors.map((entry) => entry.code)),
+    diagnosticCounts: {
+      total: diagnostics.length,
+      info: diagnostics.filter((entry) => entry.severity === 'info' || entry.status === 'info').length,
+      warning: warnings.length,
+      error: errors.length,
+      redacted: diagnostics.filter((entry) => entry.redacted === true).length,
+    },
+  };
+}
+
+function summarizePmWriterRecommendation(recommendation) {
+  return {
+    recommendationId: recommendation?.recommendationId ?? null,
+    recommendationType: recommendation?.recommendationType ?? null,
+    marketTrendId: recommendation?.marketTrendId ?? null,
+    title: recommendation?.title ?? null,
+    confidence: recommendation?.confidence ?? null,
+    risk: recommendation?.risk ?? null,
+    evidenceRefCount: Array.isArray(recommendation?.evidenceRefs) ? recommendation.evidenceRefs.length : 0,
+    skepticRefCount: Array.isArray(recommendation?.skepticRefs) ? recommendation.skepticRefs.length : 0,
+    nextActions: Array.isArray(recommendation?.nextActions) ? recommendation.nextActions : [],
+  };
+}
+
+async function resolvePmWriterInspectionPaths(projectRoot, runId) {
+  const artifactPathsRead = [];
+  let latest = null;
+  let normalizedRunId = runId;
+  if (typeof normalizedRunId !== 'string' || normalizedRunId.trim() === '') {
+    latest = await readJsonArtifact(projectRoot, VENTURE_SIGNAL_LATEST_PATH);
+    artifactPathsRead.push(VENTURE_SIGNAL_LATEST_PATH);
+    pmWriterLatestAllowed(latest);
+    normalizedRunId = latest.runId;
+  }
+  normalizedRunId = normalizeVentureRunId(normalizedRunId);
+  return { latest, runId: normalizedRunId, artifactPathsRead };
+}
+
+export async function inspectVentureRadar(params = {}) {
+  try {
+    const projectRoot = params.projectRoot;
+    const resolved = await resolvePmWriterInspectionPaths(projectRoot, params.runId);
+    const latest = resolved.latest;
+    const runId = resolved.runId;
+    const summaryPath = latest?.writerPaths?.summary ?? latest?.summaryPath ?? pmWriterRunSummaryPath(runId);
+    const diagnosticsPath = latest?.writerPaths?.diagnostics ?? latest?.diagnosticsPath ?? pmWriterDiagnosticsPath(runId);
+    const radarPath = latest?.writerPaths?.dailyRadarJson ?? latest?.dailyRadarPath ?? pmWriterDailyRadarPath(runId);
+    const summary = await readJsonArtifact(projectRoot, summaryPath);
+    const diagnosticsArtifact = await readJsonArtifact(projectRoot, diagnosticsPath);
+    const dailyRadar = await readJsonArtifact(projectRoot, radarPath);
+    const pathsRead = [...resolved.artifactPathsRead, summaryPath, diagnosticsPath, radarPath];
+    const diagnosticsSummary = pmWriterDiagnosticsSummary(diagnosticsArtifact);
+    const recommendations = Array.isArray(dailyRadar.recommendations) ? dailyRadar.recommendations : [];
+
+    return baseEnvelope('radar', {
+      status: summary.status ?? dailyRadar.status ?? (diagnosticsSummary.errors.length > 0 ? 'error' : diagnosticsSummary.warnings.length > 0 ? 'warn' : 'ok'),
+      generatedAt: dailyRadar.generatedAt ?? summary.completedAt,
+      artifactPathsRead: pathsRead,
+      warningCodes: diagnosticsSummary.warningCodes,
+      errorCodes: diagnosticsSummary.errorCodes,
+      warnings: diagnosticsSummary.warnings,
+      errors: diagnosticsSummary.errors,
+      durableStateChanged: false,
+      safeNextAction: { command: VENTURE_MEMO_TOOL_NAME, reason: 'Inspect the primary PM Writer sector memo after reviewing daily radar recommendation traces.' },
+      extra: {
+        runId,
+        role: PM_WRITER_STAGE,
+        stage: PM_WRITER_STAGE,
+        latest,
+        summaryPath,
+        diagnosticsPath,
+        radarPath,
+        writerPaths: latest?.writerPaths ?? summary.artifacts ?? null,
+        stageStatuses: dailyRadar.roleStageTrace?.stageStatuses ?? summary.stageStatuses ?? latest?.stageStatuses ?? null,
+        sourceTraceCoverage: dailyRadar.roleStageTrace?.sourceTraceCoverage ?? null,
+        radar: dailyRadar,
+        recommendationSummaries: recommendations.map(summarizePmWriterRecommendation),
+        alertCandidateCount: Array.isArray(dailyRadar.alertCandidates) ? dailyRadar.alertCandidates.length : 0,
+        mvpValidationExperimentCount: Array.isArray(dailyRadar.mvpValidationExperiments) ? dailyRadar.mvpValidationExperiments.length : 0,
+        diagnosticCounts: diagnosticsSummary.diagnosticCounts,
+        diagnostics: diagnosticsArtifact,
+        summary,
+      },
+    });
+  } catch (error) {
+    const code = 'VENTURE_RADAR_INSPECT_FAILED';
+    return baseEnvelope('radar', {
+      status: 'error',
+      errors: [diagnostic(code, 'Venture Signal PM Writer daily radar inspection failed.', { reason: error instanceof Error ? error.message : String(error) })],
+      durableStateChanged: false,
+      safeNextAction: { command: '/opportunities', reason: 'Use the AI-first opportunities workflow to decide whether PM Writer artifacts are needed as evidence before inspecting daily radar output.' },
+      extra: { stage: PM_WRITER_STAGE, runId: null, radar: null, summary: null, diagnostics: null },
+    });
+  }
+}
+
+export async function inspectVentureMemo(params = {}) {
+  try {
+    const projectRoot = params.projectRoot;
+    const resolved = await resolvePmWriterInspectionPaths(projectRoot, params.runId);
+    const latest = resolved.latest;
+    const runId = resolved.runId;
+    const summaryPath = latest?.writerPaths?.summary ?? latest?.summaryPath ?? pmWriterRunSummaryPath(runId);
+    const diagnosticsPath = latest?.writerPaths?.diagnostics ?? latest?.diagnosticsPath ?? pmWriterDiagnosticsPath(runId);
+    const summary = await readJsonArtifact(projectRoot, summaryPath);
+    const diagnosticsArtifact = await readJsonArtifact(projectRoot, diagnosticsPath);
+    let memoPath = latest?.writerPaths?.sectorMemoJson ?? null;
+    if (typeof params.marketTrendId === 'string' && params.marketTrendId.trim() !== '') {
+      memoPath = pmWriterSectorMemoPath(runId, normalizeVentureEntityId(params.marketTrendId, 'venture signal market trend id'));
+    }
+    if (typeof memoPath !== 'string' || memoPath.trim() === '') {
+      const sectorMemos = Array.isArray(summary.artifacts?.sectorMemos) ? summary.artifacts.sectorMemos : [];
+      memoPath = sectorMemos[0];
+    }
+    if (typeof memoPath !== 'string' || memoPath.trim() === '') {
+      throw new TypeError('PM Writer sector memo path is unavailable.');
+    }
+    const sectorMemo = await readJsonArtifact(projectRoot, memoPath);
+    const pathsRead = [...resolved.artifactPathsRead, summaryPath, diagnosticsPath, memoPath];
+    const diagnosticsSummary = pmWriterDiagnosticsSummary(diagnosticsArtifact);
+
+    return baseEnvelope('memo', {
+      status: summary.status ?? sectorMemo.status ?? (diagnosticsSummary.errors.length > 0 ? 'error' : diagnosticsSummary.warnings.length > 0 ? 'warn' : 'ok'),
+      generatedAt: sectorMemo.generatedAt ?? summary.completedAt,
+      artifactPathsRead: pathsRead,
+      warningCodes: diagnosticsSummary.warningCodes,
+      errorCodes: diagnosticsSummary.errorCodes,
+      warnings: diagnosticsSummary.warnings,
+      errors: diagnosticsSummary.errors,
+      durableStateChanged: false,
+      safeNextAction: { command: '/opportunities <natural language request>', reason: 'Use the AI-first opportunities workflow for a topic-focused follow-up after inspecting memo evidence and Skeptic traces.' },
+      extra: {
+        runId,
+        role: PM_WRITER_STAGE,
+        stage: PM_WRITER_STAGE,
+        latest,
+        summaryPath,
+        diagnosticsPath,
+        memoPath,
+        writerPaths: latest?.writerPaths ?? summary.artifacts ?? null,
+        marketTrendId: sectorMemo.marketTrendId,
+        sectorName: sectorMemo.sectorName,
+        sourceTraceCoverage: sectorMemo.roleStageTrace?.sourceTraceCoverage ?? null,
+        memo: sectorMemo,
+        recommendationSummaries: (sectorMemo.recommendations ?? []).map(summarizePmWriterRecommendation),
+        mvpValidationExperimentCount: Array.isArray(sectorMemo.mvpValidationExperiments) ? sectorMemo.mvpValidationExperiments.length : 0,
+        diagnosticCounts: diagnosticsSummary.diagnosticCounts,
+        diagnostics: diagnosticsArtifact,
+        summary,
+      },
+    });
+  } catch (error) {
+    const code = 'VENTURE_MEMO_INSPECT_FAILED';
+    return baseEnvelope('memo', {
+      status: 'error',
+      errors: [diagnostic(code, 'Venture Signal PM Writer sector memo inspection failed.', { reason: error instanceof Error ? error.message : String(error) })],
+      durableStateChanged: false,
+      safeNextAction: { command: '/opportunities', reason: 'Use the AI-first opportunities workflow to decide whether PM Writer artifacts are needed as evidence before inspecting sector memo output.' },
+      extra: { stage: PM_WRITER_STAGE, runId: null, memo: null, summary: null, diagnostics: null },
+    });
+  }
+}
+
+export async function inspectVentureCollector(params = {}) {
+  try {
+    const stage = params.stage ?? COLLECTOR_STAGE;
+    if (stage !== COLLECTOR_STAGE) {
+      throw new TypeError('Unsupported Venture Signal stage for Collector inspection; use --stage collector.');
+    }
+
+    let runId = params.runId;
+    let latest = null;
+    const artifactPathsRead = [];
+    if (typeof runId !== 'string' || runId.trim() === '') {
+      latest = await readJsonArtifact(params.projectRoot, VENTURE_SIGNAL_LATEST_PATH);
+      artifactPathsRead.push(VENTURE_SIGNAL_LATEST_PATH);
+      runId = latest.runId;
+    }
+    const normalizedRunId = normalizeVentureRunId(runId);
+    const summaryPath = collectorRunSummaryPath(normalizedRunId);
+    const diagnosticsPath = collectorDiagnosticsPath(normalizedRunId);
+    const summary = await readJsonArtifact(params.projectRoot, summaryPath);
+    const diagnosticsArtifact = await readJsonArtifact(params.projectRoot, diagnosticsPath);
+    artifactPathsRead.push(summaryPath, diagnosticsPath);
+    const diagnostics = Array.isArray(diagnosticsArtifact.diagnostics) ? diagnosticsArtifact.diagnostics : [];
+    const warningEntries = diagnostics.filter((entry) => entry.severity === 'warning');
+    const errorEntries = diagnostics.filter((entry) => entry.severity === 'error');
+
+    return baseEnvelope('inspect', {
+      status: summary.status ?? (errorEntries.length > 0 ? 'error' : warningEntries.length > 0 ? 'warn' : 'ok'),
+      generatedAt: summary.completedAt ?? diagnosticsArtifact.generatedAt,
+      artifactPathsRead,
+      warningCodes: uniqueCodes(warningEntries.map((entry) => entry.code)),
+      errorCodes: uniqueCodes(errorEntries.map((entry) => entry.code)),
+      warnings: warningEntries,
+      errors: errorEntries,
+      durableStateChanged: false,
+      safeNextAction: { command: VENTURE_LATEST_TOOL_NAME, reason: 'Use latest.json as the stable downstream pointer after Collector inspection passes.' },
+      extra: {
+        stage: COLLECTOR_STAGE,
+        runId: normalizedRunId,
+        latest,
+        summaryPath,
+        diagnosticsPath,
+        summary,
+        diagnostics: diagnosticsArtifact,
+        diagnosticCounts: {
+          total: diagnostics.length,
+          info: diagnostics.filter((entry) => entry.severity === 'info').length,
+          warning: warningEntries.length,
+          error: errorEntries.length,
+          redacted: diagnostics.filter((entry) => entry.redacted === true).length,
+        },
+      },
+    });
+  } catch (error) {
+    const code = 'VENTURE_COLLECTOR_INSPECT_FAILED';
+    return baseEnvelope('inspect', {
+      status: 'error',
+      errors: [diagnostic(code, 'Venture Signal Collector inspection failed.', { reason: error instanceof Error ? error.message : String(error) })],
+      durableStateChanged: false,
+      safeNextAction: { command: VENTURE_RUN_TOOL_NAME, reason: 'Create a valid Collector run before inspection.' },
+      extra: { stage: COLLECTOR_STAGE, runId: null, summary: null, diagnostics: null },
+    });
+  }
+}
+
+export async function inspectVentureNormalizer(params = {}) {
+  try {
+    const stage = params.stage ?? NORMALIZER_STAGE;
+    if (stage !== NORMALIZER_STAGE) {
+      throw new TypeError('Unsupported Venture Signal stage for Normalizer inspection; use --stage normalizer.');
+    }
+
+    let runId = params.runId;
+    let latest = null;
+    const artifactPathsRead = [];
+    if (typeof runId !== 'string' || runId.trim() === '') {
+      latest = await readJsonArtifact(params.projectRoot, VENTURE_SIGNAL_LATEST_PATH);
+      artifactPathsRead.push(VENTURE_SIGNAL_LATEST_PATH);
+      if (latest.stage !== NORMALIZER_STAGE) {
+        throw new TypeError(`Latest Venture Signal pointer is ${latest.stage ?? 'unknown'}, not normalizer.`);
+      }
+      runId = latest.runId;
+    }
+
+    const normalizedRunId = normalizeVentureRunId(runId);
+    const summaryPath = normalizerRunSummaryPath(normalizedRunId);
+    const diagnosticsPath = normalizerDiagnosticsPath(normalizedRunId);
+    const aggregatePaths = normalizerAggregatePaths(normalizedRunId);
+    const summary = await readJsonArtifact(params.projectRoot, summaryPath);
+    const diagnosticsArtifact = await readJsonArtifact(params.projectRoot, diagnosticsPath);
+    const companies = await readJsonArtifact(params.projectRoot, aggregatePaths.companies);
+    const investors = await readJsonArtifact(params.projectRoot, aggregatePaths.investors);
+    const trends = await readJsonArtifact(params.projectRoot, aggregatePaths.trends);
+    const signals = await readJsonArtifact(params.projectRoot, aggregatePaths.signals);
+    const aliases = await readJsonArtifact(params.projectRoot, aggregatePaths.aliases);
+    const taxonomyMappings = await readJsonArtifact(params.projectRoot, aggregatePaths.taxonomyMappings);
+    const diagnosticsIndex = await readJsonArtifact(params.projectRoot, aggregatePaths.diagnosticsIndex);
+    artifactPathsRead.push(
+      summaryPath,
+      diagnosticsPath,
+      aggregatePaths.companies,
+      aggregatePaths.investors,
+      aggregatePaths.trends,
+      aggregatePaths.signals,
+      aggregatePaths.aliases,
+      aggregatePaths.taxonomyMappings,
+      aggregatePaths.diagnosticsIndex,
+    );
+
+    const diagnostics = Array.isArray(diagnosticsArtifact.diagnostics) ? diagnosticsArtifact.diagnostics : [];
+    const warningEntries = diagnostics.filter((entry) => entry.severity === 'warning');
+    const errorEntries = diagnostics.filter((entry) => entry.severity === 'error');
+
+    return baseEnvelope('inspect', {
+      status: summary.status ?? (errorEntries.length > 0 ? 'error' : warningEntries.length > 0 ? 'warn' : 'ok'),
+      generatedAt: summary.completedAt ?? diagnosticsArtifact.generatedAt,
+      artifactPathsRead,
+      warningCodes: uniqueCodes(warningEntries.map((entry) => entry.code)),
+      errorCodes: uniqueCodes(errorEntries.map((entry) => entry.code)),
+      warnings: warningEntries,
+      errors: errorEntries,
+      durableStateChanged: false,
+      safeNextAction: { command: VENTURE_LATEST_TOOL_NAME, reason: 'Use latest.json as the stable Normalizer pointer before scoring or analyst stages.' },
+      extra: {
+        stage: NORMALIZER_STAGE,
+        runId: normalizedRunId,
+        latest,
+        summaryPath,
+        diagnosticsPath,
+        aggregatePaths,
+        normalizerCounts: summary.counts ?? null,
+        summary,
+        diagnostics: diagnosticsArtifact,
+        diagnosticsIndex,
+        companies,
+        investors,
+        trends,
+        signals,
+        aliases,
+        taxonomyMappings,
+        diagnosticCounts: {
+          total: diagnostics.length,
+          info: diagnostics.filter((entry) => entry.severity === 'info').length,
+          warning: warningEntries.length,
+          error: errorEntries.length,
+          redacted: diagnostics.filter((entry) => entry.redacted === true).length,
+        },
+      },
+    });
+  } catch (error) {
+    const code = 'VENTURE_NORMALIZER_INSPECT_FAILED';
+    return baseEnvelope('inspect', {
+      status: 'error',
+      errors: [diagnostic(code, 'Venture Signal Normalizer inspection failed.', { reason: error instanceof Error ? error.message : String(error) })],
+      durableStateChanged: false,
+      safeNextAction: { command: VENTURE_NORMALIZE_TOOL_NAME, reason: 'Create a valid Normalizer run before inspection.' },
+      extra: { stage: NORMALIZER_STAGE, runId: null, summary: null, diagnostics: null, aggregatePaths: null },
+    });
+  }
+}
+
+function analysisLatestAllowed(latest, stages, label) {
+  if (!isPlainObject(latest)) return;
+  if (!stages.includes(latest.stage)) {
+    throw new TypeError(`Latest Venture Signal pointer is ${latest.stage ?? 'unknown'}, not ${label}.`);
+  }
+}
+
+export async function inspectVentureAnalyst(params = {}) {
+  try {
+    const stage = params.stage ?? ANALYST_STAGE;
+    if (stage !== ANALYST_STAGE) {
+      throw new TypeError('Unsupported Venture Signal stage for Analyst inspection; use --stage analyst.');
+    }
+
+    let runId = params.runId;
+    let latest = null;
+    const artifactPathsRead = [];
+    if (typeof runId !== 'string' || runId.trim() === '') {
+      latest = await readJsonArtifact(params.projectRoot, VENTURE_SIGNAL_LATEST_PATH);
+      artifactPathsRead.push(VENTURE_SIGNAL_LATEST_PATH);
+      analysisLatestAllowed(latest, [ANALYST_STAGE, SKEPTIC_STAGE], 'an Analyst/Skeptic analysis run');
+      runId = latest.runId;
+    }
+
+    const normalizedRunId = normalizeVentureRunId(runId);
+    const summaryPath = analystRunSummaryPath(normalizedRunId);
+    const diagnosticsPath = analysisAnalystDiagnosticsPath(normalizedRunId);
+    const trendScoresPath = analystTrendScoresPath(normalizedRunId);
+    const summary = await readJsonArtifact(params.projectRoot, summaryPath);
+    const diagnosticsArtifact = await readJsonArtifact(params.projectRoot, diagnosticsPath);
+    const trendScores = await readJsonArtifact(params.projectRoot, trendScoresPath);
+    artifactPathsRead.push(summaryPath, diagnosticsPath, trendScoresPath);
+
+    const diagnostics = Array.isArray(diagnosticsArtifact.diagnostics) ? diagnosticsArtifact.diagnostics : [];
+    const warningEntries = diagnostics.filter(diagnosticIsWarning);
+    const errorEntries = diagnostics.filter(diagnosticIsError);
+    const trendScoreRecords = Array.isArray(trendScores.trendScores) ? trendScores.trendScores : [];
+
+    return baseEnvelope('inspect', {
+      status: summary.status ?? (errorEntries.length > 0 ? 'error' : warningEntries.length > 0 ? 'warn' : 'ok'),
+      generatedAt: summary.completedAt ?? diagnosticsArtifact.generatedAt,
+      artifactPathsRead,
+      warningCodes: uniqueCodes(warningEntries.map((entry) => entry.code)),
+      errorCodes: uniqueCodes(errorEntries.map((entry) => entry.code)),
+      warnings: warningEntries,
+      errors: errorEntries,
+      durableStateChanged: false,
+      safeNextAction: { command: VENTURE_INSPECT_SKEPTIC_TOOL_NAME, reason: 'Compare Analyst score components against Skeptic challenges before PM output.' },
+      extra: {
+        stage: ANALYST_STAGE,
+        runId: normalizedRunId,
+        latest,
+        summaryPath,
+        diagnosticsPath,
+        trendScoresPath,
+        analystCounts: summary.counts ?? null,
+        scoreArtifactPaths: summary.artifacts?.trendScoreArtifacts ?? [],
+        trendScoreSummaries: trendScoreRecords.map(trendScoreSummary),
+        confidenceDowngradeSummary: {
+          downgradedTrendCount: trendScoreRecords.filter((trendScore) => trendScore?.confidence?.downgraded === true).length,
+          downgradeReasons: uniqueCodes(trendScoreRecords.flatMap((trendScore) => Array.isArray(trendScore?.confidence?.downgradeReasons) ? trendScore.confidence.downgradeReasons : [])),
+        },
+        summary,
+        diagnostics: diagnosticsArtifact,
+        trendScores,
+        diagnosticCounts: {
+          total: diagnostics.length,
+          info: diagnostics.filter((entry) => entry.severity === 'info' || entry.status === 'info').length,
+          warning: warningEntries.length,
+          error: errorEntries.length,
+          redacted: diagnostics.filter((entry) => entry.redacted === true).length,
+        },
+      },
+    });
+  } catch (error) {
+    const code = 'VENTURE_ANALYST_INSPECT_FAILED';
+    return baseEnvelope('inspect', {
+      status: 'error',
+      errors: [diagnostic(code, 'Venture Signal Analyst inspection failed.', { reason: error instanceof Error ? error.message : String(error) })],
+      durableStateChanged: false,
+      safeNextAction: { command: VENTURE_ANALYZE_TOOL_NAME, reason: 'Create a valid Analysis run before Analyst inspection.' },
+      extra: { stage: ANALYST_STAGE, runId: null, summary: null, diagnostics: null, trendScores: null },
+    });
+  }
+}
+
+export async function inspectVentureSkeptic(params = {}) {
+  try {
+    const stage = params.stage ?? SKEPTIC_STAGE;
+    if (stage !== SKEPTIC_STAGE) {
+      throw new TypeError('Unsupported Venture Signal stage for Skeptic inspection; use --stage skeptic.');
+    }
+
+    let runId = params.runId;
+    let latest = null;
+    const artifactPathsRead = [];
+    if (typeof runId !== 'string' || runId.trim() === '') {
+      latest = await readJsonArtifact(params.projectRoot, VENTURE_SIGNAL_LATEST_PATH);
+      artifactPathsRead.push(VENTURE_SIGNAL_LATEST_PATH);
+      analysisLatestAllowed(latest, [SKEPTIC_STAGE], 'a Skeptic analysis run');
+      runId = latest.runId;
+    }
+
+    const normalizedRunId = normalizeVentureRunId(runId);
+    const reviewPath = analysisSkepticReviewPath(normalizedRunId);
+    const diagnosticsPath = analysisSkepticDiagnosticsPath(normalizedRunId);
+    const challengedClaimsPath = analysisSkepticChallengedClaimsPath(normalizedRunId);
+    const review = await readJsonArtifact(params.projectRoot, reviewPath);
+    const diagnosticsArtifact = await readJsonArtifact(params.projectRoot, diagnosticsPath);
+    const challengedClaims = await readJsonArtifact(params.projectRoot, challengedClaimsPath);
+    artifactPathsRead.push(reviewPath, diagnosticsPath, challengedClaimsPath);
+
+    const diagnostics = Array.isArray(diagnosticsArtifact.diagnostics) ? diagnosticsArtifact.diagnostics : [];
+    const warningEntries = diagnostics.filter(diagnosticIsWarning);
+    const errorEntries = diagnostics.filter(diagnosticIsError);
+    const challenges = Array.isArray(challengedClaims.challenges) ? challengedClaims.challenges : [];
+    const trendScoreRecords = Array.isArray(review.trendScores) ? review.trendScores : [];
+
+    return baseEnvelope('inspect', {
+      status: review.stageStatuses?.skeptic ?? review.status ?? (errorEntries.length > 0 ? 'error' : warningEntries.length > 0 ? 'warn' : 'ok'),
+      generatedAt: review.completedAt ?? diagnosticsArtifact.generatedAt,
+      artifactPathsRead,
+      warningCodes: uniqueCodes(warningEntries.map((entry) => entry.code)),
+      errorCodes: uniqueCodes(errorEntries.map((entry) => entry.code)),
+      warnings: warningEntries,
+      errors: errorEntries,
+      durableStateChanged: false,
+      safeNextAction: { command: VENTURE_LATEST_TOOL_NAME, reason: 'Use latest.json as the stable analysis pointer before PM Writer output.' },
+      extra: {
+        stage: SKEPTIC_STAGE,
+        runId: normalizedRunId,
+        latest,
+        summaryPath: reviewPath,
+        diagnosticsPath,
+        challengedClaimsPath,
+        skepticPaths: {
+          review: reviewPath,
+          challengedClaims: challengedClaimsPath,
+          diagnostics: diagnosticsPath,
+          challengeArtifacts: challenges.map((challenge) => challenge.artifactPath).filter(Boolean),
+        },
+        skepticCounts: {
+          challengedClaims: challenges.length,
+          confidenceAdjustments: challenges.length,
+          diagnostics: diagnostics.length,
+        },
+        challengeTypeCounts: challengeTypeCounts(challenges),
+        trendScoreSummaries: trendScoreRecords.map(trendScoreSummary),
+        confidenceAdjustments: challenges.map((challenge) => ({
+          marketTrendId: challenge.targetMarketTrendId,
+          challengeId: challenge.challengeId,
+          challengeType: challenge.challengeType,
+          adjustedConfidenceScore: challenge.confidence?.score ?? null,
+          downgradeReasons: Array.isArray(challenge.confidence?.downgradeReasons) ? challenge.confidence.downgradeReasons : [],
+        })),
+        review,
+        summary: review,
+        diagnostics: diagnosticsArtifact,
+        challengedClaims,
+        diagnosticCounts: {
+          total: diagnostics.length,
+          info: diagnostics.filter((entry) => entry.severity === 'info' || entry.status === 'info').length,
+          warning: warningEntries.length,
+          error: errorEntries.length,
+          redacted: diagnostics.filter((entry) => entry.redacted === true).length,
+        },
+      },
+    });
+  } catch (error) {
+    const code = 'VENTURE_SKEPTIC_INSPECT_FAILED';
+    return baseEnvelope('inspect', {
+      status: 'error',
+      errors: [diagnostic(code, 'Venture Signal Skeptic inspection failed.', { reason: error instanceof Error ? error.message : String(error) })],
+      durableStateChanged: false,
+      safeNextAction: { command: VENTURE_ANALYZE_TOOL_NAME, reason: 'Create a valid Analysis run before Skeptic inspection.' },
+      extra: { stage: SKEPTIC_STAGE, runId: null, summary: null, diagnostics: null, challengedClaims: null },
+    });
+  }
+}
+
+function argumentFailure(messages, subcommand = 'sources') {
+  const errors = messages.map((message) => {
+    const codeMatch = /^([A-Z0-9_]+):/.exec(message);
+    return diagnostic(codeMatch?.[1] ?? 'CLI_ARG_INVALID', message.replace(/^([A-Z0-9_]+):\s*/, ''), { usage: commandUsageText() });
+  });
+  return baseEnvelope(subcommand, {
+    status: 'error',
+    errors,
+    durableStateChanged: false,
+    safeNextAction: { command: VENTURE_SOURCES_TOOL_NAME, reason: 'Review supported Venture Signal tool inputs.' },
+  });
+}
+
+function compactText(result) {
+  const warningCodes = Array.isArray(result.warningCodes) && result.warningCodes.length > 0 ? result.warningCodes.join(', ') : 'none';
+  const errorCodes = Array.isArray(result.errorCodes) && result.errorCodes.length > 0 ? result.errorCodes.join(', ') : 'none';
+  return [
+    `AutoPM venture: ${result.status ?? 'unknown'}`,
+    `subcommand: ${result.subcommand ?? 'unknown'}`,
+    `implemented: ${result.implemented === true}`,
+    `runId: ${result.runId ?? result.latest?.runId ?? 'none'}`,
+    `stage: ${result.stage ?? result.latest?.stage ?? 'none'}`,
+    `summaryPath: ${result.summaryPath ?? 'none'}`,
+    `diagnosticsPath: ${result.diagnosticsPath ?? 'none'}`,
+    `latestPath: ${result.latestPath ?? VENTURE_SIGNAL_LATEST_PATH}`,
+    `artifactPathsRead: ${Array.isArray(result.artifactPathsRead) && result.artifactPathsRead.length > 0 ? result.artifactPathsRead.join(', ') : 'none'}`,
+    `artifactPathsWritten: ${Array.isArray(result.artifactPathsWritten) && result.artifactPathsWritten.length > 0 ? result.artifactPathsWritten.join(', ') : 'none'}`,
+    `warnings: ${warningCodes}`,
+    `errors: ${errorCodes}`,
+    `durableStateChanged: ${result.durableStateChanged === true}`,
+    `safeNextAction: ${result.safeNextAction?.command ?? 'none'}`,
+  ].join('\n');
+}
+
+function resolveProjectRoot(ctx, explicitProjectRoot) {
+  if (typeof explicitProjectRoot === 'string' && explicitProjectRoot.trim() !== '') return explicitProjectRoot;
+  if (typeof ctx?.cwd === 'string' && ctx.cwd.trim() !== '') return ctx.cwd;
+  return process.cwd();
+}
+
+export function ventureCommandCompletions(prefix = '') {
+  const trimmed = normalizeArgs(prefix).toLowerCase();
+  return [
+    { value: 'sources', label: 'sources', description: 'List the default free Venture Signal source bundle' },
+    { value: 'run', label: 'run', description: 'Run local Collector intake using supplied authorized source records' },
+    { value: 'run --run-id', label: 'run --run-id', description: 'Run Collector intake with a deterministic run ID' },
+    { value: 'normalize', label: 'normalize', description: 'Run local Collector intake plus Normalizer artifacts' },
+    { value: 'normalize --run-id', label: 'normalize --run-id', description: 'Run Normalizer with a deterministic run ID' },
+    { value: 'analyze', label: 'analyze', description: 'Run Collector, Normalizer, Signal Analyst, and Skeptic artifacts' },
+    { value: 'analyze --run-id', label: 'analyze --run-id', description: 'Run Analysis with a deterministic run ID' },
+    { value: 'latest', label: 'latest', description: 'Read the stable Venture Signal latest pointer' },
+    { value: 'radar', label: 'radar', description: 'Inspect PM Writer daily radar output for the latest run' },
+    { value: 'memo', label: 'memo', description: 'Inspect the primary PM Writer sector memo output for the latest run' },
+    { value: 'inspect --stage collector', label: 'inspect collector', description: 'Inspect Collector summary and diagnostics for latest run' },
+    { value: 'inspect --stage normalizer', label: 'inspect normalizer', description: 'Inspect Normalizer diagnostics and aggregate artifacts for latest run' },
+    { value: 'inspect --stage analyst', label: 'inspect analyst', description: 'Inspect Analyst score components and diagnostics for latest analysis run' },
+    { value: 'inspect --stage skeptic', label: 'inspect skeptic', description: 'Inspect Skeptic challenges and diagnostics for latest analysis run' },
+    { value: 'help', label: 'help', description: 'Show Venture Signal command usage' },
+  ].filter((completion) => completion.value.toLowerCase().startsWith(trimmed));
+}
+
+export function createVentureCommandHandler() {
+  return async function handleVentureCommand(args, ctx = {}) {
+    const parsed = parseVentureArgs(args);
+    if (parsed.help) {
+      return baseEnvelope('help', {
+        status: parsed.errors.length > 0 ? 'error' : 'ok',
+        errors: parsed.errors.length > 0 ? [diagnostic('CLI_ARG_INVALID', parsed.errors.join('\n'), { usage: commandUsageText() })] : [],
+        durableStateChanged: false,
+        extra: { usage: commandUsageText() },
+      });
+    }
+    if (parsed.errors.length > 0) {
+      return argumentFailure(parsed.errors, parsed.subcommand);
+    }
+
+    const projectRoot = resolveProjectRoot(ctx);
+    if (parsed.subcommand === 'sources') return listVentureSources({ projectRoot });
+    if (parsed.subcommand === 'run') return runVentureCollectorCommand({ projectRoot, runId: parsed.runId });
+    if (parsed.subcommand === 'normalize') return runVentureNormalizerCommand({ projectRoot, runId: parsed.runId });
+    if (parsed.subcommand === 'analyze') return runVentureAnalysisCommand({ projectRoot, runId: parsed.runId });
+    if (parsed.subcommand === 'latest') return readVentureLatest({ projectRoot });
+    if (parsed.subcommand === 'radar') return inspectVentureRadar({ projectRoot, runId: parsed.runId });
+    if (parsed.subcommand === 'memo') return inspectVentureMemo({ projectRoot, runId: parsed.runId, marketTrendId: parsed.marketTrendId });
+    if (parsed.subcommand === 'inspect') {
+      const stage = parsed.stage ?? COLLECTOR_STAGE;
+      if (stage === NORMALIZER_STAGE) return inspectVentureNormalizer({ projectRoot, runId: parsed.runId, stage });
+      if (stage === ANALYST_STAGE) return inspectVentureAnalyst({ projectRoot, runId: parsed.runId, stage });
+      if (stage === SKEPTIC_STAGE) return inspectVentureSkeptic({ projectRoot, runId: parsed.runId, stage });
+      return inspectVentureCollector({ projectRoot, runId: parsed.runId, stage });
+    }
+    return argumentFailure(['Unknown subcommand: [redacted-subcommand]'], parsed.subcommand);
+  };
+}
+
+function ensureNotAborted(signal, operation) {
+  if (signal?.aborted) {
+    const error = new Error(`${operation} aborted before execution.`);
+    error.name = 'AbortError';
+    throw error;
+  }
+}
+
+function toolResult(result) {
+  return {
+    content: [{ type: 'text', text: compactText(result) }],
+    isError: result.status === 'error',
+    details: result,
+  };
+}
+
+export function createVentureToolDefinitions() {
+  return [
+    {
+      name: VENTURE_SOURCES_TOOL_NAME,
+      label: 'Venture Signal Sources',
+      description: 'List the built-in default free Venture Signal source bundle and disabled paid extension metadata. No credentials, network, or workspace mutation are required.',
+      promptSnippet: 'List default free Venture Signal Collector sources before running intake',
+      promptGuidelines: [
+        'Use this before Venture Collector runs to inspect source access modes, rights status, optionality, and paid extension boundaries.',
+        'Do not request paid credentials for the default free source bundle; paid extensions are disabled metadata only.',
+      ],
+      parameters: VENTURE_SOURCES_TOOL_PARAMETERS,
+      async execute(_toolCallId, params, signal) {
+        try {
+          ensureNotAborted(signal, VENTURE_SOURCES_TOOL_NAME);
+          return toolResult(listVentureSources({ projectRoot: resolveProjectRoot(null, params?.projectRoot) }));
+        } catch (error) {
+          return toolResult(argumentFailure([error instanceof Error ? error.message : String(error)], 'sources'));
+        }
+      },
+    },
+    {
+      name: VENTURE_RUN_TOOL_NAME,
+      label: 'Venture Signal Collector Run',
+      description: 'Run local Venture Signal Collector intake and persist run-scoped Collector artifacts with safe latest promotion for ok/warn runs.',
+      promptSnippet: 'Run Venture Signal Collector and inspect summary, diagnostics, and latest promotion artifacts',
+      promptGuidelines: [
+        'Use caller-provided authorized public sourceRecords when available; otherwise preserve source diagnostics without synthesized evidence.',
+        'Inspect details.warningCodes, details.errorCodes, details.artifactPathsWritten, and details.latestPromoted before downstream use.',
+      ],
+      parameters: VENTURE_RUN_TOOL_PARAMETERS,
+      async execute(_toolCallId, params = {}, signal) {
+        try {
+          ensureNotAborted(signal, VENTURE_RUN_TOOL_NAME);
+          const result = await runVentureCollectorCommand({
+            projectRoot: resolveProjectRoot(null, params.projectRoot),
+            runId: params.runId,
+            now: params.now,
+            sourceRecords: params.sourceRecords,
+          });
+          ensureNotAborted(signal, VENTURE_RUN_TOOL_NAME);
+          return toolResult(result);
+        } catch (error) {
+          return toolResult(baseEnvelope('run', {
+            status: 'error',
+            errors: [diagnostic(
+              error?.name === 'AbortError' ? 'VENTURE_COLLECTOR_RUN_ABORTED' : 'VENTURE_COLLECTOR_RUN_FAILED',
+              'Venture Signal Collector tool execution failed before producing a complete result.',
+              { reason: error instanceof Error ? error.message : String(error) },
+            )],
+            durableStateChanged: false,
+            safeNextAction: { command: VENTURE_RUN_TOOL_NAME, reason: 'Retry the Collector run after resolving the tool failure.' },
+          }));
+        }
+      },
+    },
+    {
+      name: VENTURE_NORMALIZE_TOOL_NAME,
+      label: 'Venture Signal Normalizer Run',
+      description: 'Run local Venture Signal Collector intake plus Normalizer artifact generation, validation, aggregate persistence, and safe latest promotion.',
+      promptSnippet: 'Run Venture Signal Normalizer and inspect normalized companies, investors, market trends, signals, aliases, taxonomy mappings, and diagnostics',
+      promptGuidelines: [
+        'Use caller-provided authorized public source records and matching source bundle metadata when available; otherwise preserve source diagnostics without synthesized evidence.',
+        'Inspect details.normalizerCounts, details.aggregatePaths, details.warningCodes, details.errorCodes, and details.latestPromoted before scoring or analyst stages.',
+      ],
+      parameters: VENTURE_NORMALIZE_TOOL_PARAMETERS,
+      async execute(_toolCallId, params = {}, signal) {
+        try {
+          ensureNotAborted(signal, VENTURE_NORMALIZE_TOOL_NAME);
+          const result = await runVentureNormalizerCommand({
+            projectRoot: resolveProjectRoot(null, params.projectRoot),
+            runId: params.runId,
+            now: params.now,
+            sourceBundle: params.sourceBundle,
+            sourceRecords: params.sourceRecords,
+          });
+          ensureNotAborted(signal, VENTURE_NORMALIZE_TOOL_NAME);
+          return toolResult(result);
+        } catch (error) {
+          return toolResult(baseEnvelope('normalize', {
+            status: 'error',
+            errors: [diagnostic(
+              error?.name === 'AbortError' ? 'VENTURE_NORMALIZER_RUN_ABORTED' : 'VENTURE_NORMALIZER_RUN_FAILED',
+              'Venture Signal Normalizer tool execution failed before producing a complete result.',
+              { reason: error instanceof Error ? error.message : String(error) },
+            )],
+            durableStateChanged: false,
+            safeNextAction: { command: VENTURE_NORMALIZE_TOOL_NAME, reason: 'Retry the Normalizer run after resolving the tool failure.' },
+          }));
+        }
+      },
+    },
+    {
+      name: VENTURE_ANALYZE_TOOL_NAME,
+      label: 'Venture Signal Analysis Run',
+      description: 'Run local Venture Signal Collector, Normalizer, Signal Analyst scoring, and Skeptic challenge generation with validated persistence and safe latest promotion.',
+      promptSnippet: 'Run Venture Signal Analyst and Skeptic stages, then inspect score components and challenged claims',
+      promptGuidelines: [
+        'Use caller-provided authorized public source records and matching source bundle metadata when available; otherwise preserve source diagnostics without synthesized evidence.',
+        'Inspect details.analystPaths, details.skepticPaths, details.trendScoreSummaries, details.challengeTypeCounts, warningCodes, errorCodes, and latestPromoted before PM Writer output.',
+      ],
+      parameters: VENTURE_ANALYZE_TOOL_PARAMETERS,
+      async execute(_toolCallId, params = {}, signal) {
+        try {
+          ensureNotAborted(signal, VENTURE_ANALYZE_TOOL_NAME);
+          const result = await runVentureAnalysisCommand({
+            projectRoot: resolveProjectRoot(null, params.projectRoot),
+            runId: params.runId,
+            now: params.now,
+            sourceBundle: params.sourceBundle,
+            sourceRecords: params.sourceRecords,
+          });
+          ensureNotAborted(signal, VENTURE_ANALYZE_TOOL_NAME);
+          return toolResult(result);
+        } catch (error) {
+          return toolResult(baseEnvelope('analyze', {
+            status: 'error',
+            errors: [diagnostic(
+              error?.name === 'AbortError' ? 'VENTURE_ANALYSIS_RUN_ABORTED' : 'VENTURE_ANALYSIS_RUN_FAILED',
+              'Venture Signal Analysis tool execution failed before producing a complete result.',
+              { reason: error instanceof Error ? error.message : String(error) },
+            )],
+            durableStateChanged: false,
+            safeNextAction: { command: VENTURE_ANALYZE_TOOL_NAME, reason: 'Retry Analysis after resolving the tool failure.' },
+          }));
+        }
+      },
+    },
+    {
+      name: VENTURE_LATEST_TOOL_NAME,
+      label: 'Venture Signal Latest',
+      description: 'Read the stable .autopm/venture-signal/latest.json pointer for the latest promotable Collector run.',
+      promptSnippet: 'Read Venture Signal latest.json before consuming Collector artifacts',
+      promptGuidelines: [
+        'Use this to find the current Collector run and freshness/promotion status.',
+        'If missing or malformed, run venture_signal_run before downstream stages consume artifacts.',
+      ],
+      parameters: VENTURE_LATEST_TOOL_PARAMETERS,
+      async execute(_toolCallId, params = {}, signal) {
+        try {
+          ensureNotAborted(signal, VENTURE_LATEST_TOOL_NAME);
+          return toolResult(await readVentureLatest({ projectRoot: resolveProjectRoot(null, params.projectRoot) }));
+        } catch (error) {
+          return toolResult(baseEnvelope('latest', {
+            status: 'error',
+            errors: [diagnostic(
+              error?.name === 'AbortError' ? 'VENTURE_LATEST_ABORTED' : 'VENTURE_LATEST_FAILED',
+              'Venture Signal latest tool execution failed before producing a complete result.',
+              { reason: error instanceof Error ? error.message : String(error) },
+            )],
+            durableStateChanged: false,
+            safeNextAction: { command: VENTURE_LATEST_TOOL_NAME, reason: 'Retry latest inspection after resolving the tool failure.' },
+            extra: { latestPath: VENTURE_SIGNAL_LATEST_PATH, latest: null },
+          }));
+        }
+      },
+    },
+    {
+      name: VENTURE_RADAR_TOOL_NAME,
+      label: 'Venture Signal PM Writer Radar Inspect',
+      description: 'Inspect PM Writer daily radar output selected by latest.json or an explicit runId, including recommendation trace coverage and diagnostics.',
+      promptSnippet: 'Inspect PM Writer daily radar recommendation traces and diagnostics for the latest opportunity workflow run',
+      promptGuidelines: [
+        'Use this after /opportunities or PM Writer generation when an agent needs low-level daily radar evidence paths.',
+        'Check details.sourceTraceCoverage, details.recommendationSummaries, details.warningCodes, details.errorCodes, and details.artifactPathsRead before relying on recommendations.',
+      ],
+      parameters: VENTURE_RADAR_TOOL_PARAMETERS,
+      async execute(_toolCallId, params = {}, signal) {
+        try {
+          ensureNotAborted(signal, VENTURE_RADAR_TOOL_NAME);
+          return toolResult(await inspectVentureRadar({
+            projectRoot: resolveProjectRoot(null, params.projectRoot),
+            runId: params.runId,
+          }));
+        } catch (error) {
+          return toolResult(baseEnvelope('radar', {
+            status: 'error',
+            errors: [diagnostic(
+              error?.name === 'AbortError' ? 'VENTURE_RADAR_INSPECT_ABORTED' : 'VENTURE_RADAR_INSPECT_FAILED',
+              'Venture Signal PM Writer radar inspection tool execution failed before producing a complete result.',
+              { reason: error instanceof Error ? error.message : String(error) },
+            )],
+            durableStateChanged: false,
+            safeNextAction: { command: VENTURE_RADAR_TOOL_NAME, reason: 'Retry PM Writer radar inspection after resolving the tool failure.' },
+            extra: { stage: PM_WRITER_STAGE, runId: null, radar: null, diagnostics: null },
+          }));
+        }
+      },
+    },
+    {
+      name: VENTURE_MEMO_TOOL_NAME,
+      label: 'Venture Signal PM Writer Memo Inspect',
+      description: 'Inspect PM Writer sector memo output selected by latest.json, runId, or marketTrendId, including evidence and Skeptic traces.',
+      promptSnippet: 'Inspect PM Writer sector memo evidence, Skeptic traces, MVP validation experiments, and diagnostics',
+      promptGuidelines: [
+        'Use this after /opportunities or venture_signal_radar when an agent needs low-level sector memo evidence paths.',
+        'Check details.memo, details.recommendationSummaries, details.sourceTraceCoverage, warningCodes, errorCodes, and safeNextAction before proposing follow-up work.',
+      ],
+      parameters: VENTURE_MEMO_TOOL_PARAMETERS,
+      async execute(_toolCallId, params = {}, signal) {
+        try {
+          ensureNotAborted(signal, VENTURE_MEMO_TOOL_NAME);
+          return toolResult(await inspectVentureMemo({
+            projectRoot: resolveProjectRoot(null, params.projectRoot),
+            runId: params.runId,
+            marketTrendId: params.marketTrendId,
+          }));
+        } catch (error) {
+          return toolResult(baseEnvelope('memo', {
+            status: 'error',
+            errors: [diagnostic(
+              error?.name === 'AbortError' ? 'VENTURE_MEMO_INSPECT_ABORTED' : 'VENTURE_MEMO_INSPECT_FAILED',
+              'Venture Signal PM Writer memo inspection tool execution failed before producing a complete result.',
+              { reason: error instanceof Error ? error.message : String(error) },
+            )],
+            durableStateChanged: false,
+            safeNextAction: { command: VENTURE_MEMO_TOOL_NAME, reason: 'Retry PM Writer memo inspection after resolving the tool failure.' },
+            extra: { stage: PM_WRITER_STAGE, runId: null, memo: null, diagnostics: null },
+          }));
+        }
+      },
+    },
+    {
+      name: VENTURE_INSPECT_COLLECTOR_TOOL_NAME,
+      label: 'Venture Signal Collector Inspect',
+      description: 'Inspect a Venture Signal Collector summary and diagnostics artifact selected by runId or latest.json.',
+      promptSnippet: 'Inspect Venture Signal Collector diagnostic codes and artifact paths for the latest run',
+      promptGuidelines: [
+        'Use this before normalizer, analyst, skeptic, or PM writer stages consume Collector outputs.',
+        'Check diagnosticCounts, warningCodes, errorCodes, redacted diagnostics, and latest promotion state.',
+      ],
+      parameters: VENTURE_INSPECT_COLLECTOR_TOOL_PARAMETERS,
+      async execute(_toolCallId, params = {}, signal) {
+        try {
+          ensureNotAborted(signal, VENTURE_INSPECT_COLLECTOR_TOOL_NAME);
+          return toolResult(await inspectVentureCollector({
+            projectRoot: resolveProjectRoot(null, params.projectRoot),
+            runId: params.runId,
+            stage: params.stage ?? COLLECTOR_STAGE,
+          }));
+        } catch (error) {
+          return toolResult(baseEnvelope('inspect', {
+            status: 'error',
+            errors: [diagnostic(
+              error?.name === 'AbortError' ? 'VENTURE_COLLECTOR_INSPECT_ABORTED' : 'VENTURE_COLLECTOR_INSPECT_FAILED',
+              'Venture Signal Collector inspection tool execution failed before producing a complete result.',
+              { reason: error instanceof Error ? error.message : String(error) },
+            )],
+            durableStateChanged: false,
+            safeNextAction: { command: VENTURE_INSPECT_COLLECTOR_TOOL_NAME, reason: 'Retry Collector inspection after resolving the tool failure.' },
+            extra: { stage: COLLECTOR_STAGE, runId: null, summary: null, diagnostics: null },
+          }));
+        }
+      },
+    },
+    {
+      name: VENTURE_INSPECT_NORMALIZER_TOOL_NAME,
+      label: 'Venture Signal Normalizer Inspect',
+      description: 'Inspect a Venture Signal Normalizer summary, diagnostics, aliases, taxonomy mappings, and aggregate entity artifacts selected by runId or latest.json.',
+      promptSnippet: 'Inspect Venture Signal Normalizer diagnostic codes, merge decisions, aggregate artifact paths, and normalized artifacts for the latest run',
+      promptGuidelines: [
+        'Use this after venture_signal_normalize and before scoring, analyst, skeptic, or PM writer stages consume Normalizer outputs.',
+        'Check normalizerCounts, diagnosticCounts, warningCodes, errorCodes, aggregatePaths, duplicate/merge decisions, and validation diagnostics.',
+      ],
+      parameters: VENTURE_INSPECT_NORMALIZER_TOOL_PARAMETERS,
+      async execute(_toolCallId, params = {}, signal) {
+        try {
+          ensureNotAborted(signal, VENTURE_INSPECT_NORMALIZER_TOOL_NAME);
+          return toolResult(await inspectVentureNormalizer({
+            projectRoot: resolveProjectRoot(null, params.projectRoot),
+            runId: params.runId,
+            stage: params.stage ?? NORMALIZER_STAGE,
+          }));
+        } catch (error) {
+          return toolResult(baseEnvelope('inspect', {
+            status: 'error',
+            errors: [diagnostic(
+              error?.name === 'AbortError' ? 'VENTURE_NORMALIZER_INSPECT_ABORTED' : 'VENTURE_NORMALIZER_INSPECT_FAILED',
+              'Venture Signal Normalizer inspection tool execution failed before producing a complete result.',
+              { reason: error instanceof Error ? error.message : String(error) },
+            )],
+            durableStateChanged: false,
+            safeNextAction: { command: VENTURE_INSPECT_NORMALIZER_TOOL_NAME, reason: 'Retry Normalizer inspection after resolving the tool failure.' },
+            extra: { stage: NORMALIZER_STAGE, runId: null, summary: null, diagnostics: null, aggregatePaths: null },
+          }));
+        }
+      },
+    },
+    {
+      name: VENTURE_INSPECT_ANALYST_TOOL_NAME,
+      label: 'Venture Signal Analyst Inspect',
+      description: 'Inspect Venture Signal Analyst score components, contribution diagnostics, freshness, source concentration, and confidence downgrades selected by runId or latest.json.',
+      promptSnippet: 'Inspect Analyst scoring diagnostics and trend score component paths for the latest analysis run',
+      promptGuidelines: [
+        'Use this after venture_signal_analyze and before PM writer stages consume score components.',
+        'Check analystCounts, trendScoreSummaries, confidenceDowngradeSummary, diagnosticCounts, warningCodes, and scoreArtifactPaths.',
+      ],
+      parameters: VENTURE_INSPECT_ANALYST_TOOL_PARAMETERS,
+      async execute(_toolCallId, params = {}, signal) {
+        try {
+          ensureNotAborted(signal, VENTURE_INSPECT_ANALYST_TOOL_NAME);
+          return toolResult(await inspectVentureAnalyst({
+            projectRoot: resolveProjectRoot(null, params.projectRoot),
+            runId: params.runId,
+            stage: params.stage ?? ANALYST_STAGE,
+          }));
+        } catch (error) {
+          return toolResult(baseEnvelope('inspect', {
+            status: 'error',
+            errors: [diagnostic(
+              error?.name === 'AbortError' ? 'VENTURE_ANALYST_INSPECT_ABORTED' : 'VENTURE_ANALYST_INSPECT_FAILED',
+              'Venture Signal Analyst inspection tool execution failed before producing a complete result.',
+              { reason: error instanceof Error ? error.message : String(error) },
+            )],
+            durableStateChanged: false,
+            safeNextAction: { command: VENTURE_INSPECT_ANALYST_TOOL_NAME, reason: 'Retry Analyst inspection after resolving the tool failure.' },
+            extra: { stage: ANALYST_STAGE, runId: null, summary: null, diagnostics: null, trendScores: null },
+          }));
+        }
+      },
+    },
+    {
+      name: VENTURE_INSPECT_SKEPTIC_TOOL_NAME,
+      label: 'Venture Signal Skeptic Inspect',
+      description: 'Inspect Venture Signal Skeptic challenged claims, negative evidence, bubble-risk rationale, confidence adjustments, diagnostics, and safe next actions selected by runId or latest.json.',
+      promptSnippet: 'Inspect Skeptic challenge diagnostics and confidence adjustment paths for the latest analysis run',
+      promptGuidelines: [
+        'Use this after venture_signal_analyze and before PM writer stages produce recommendations.',
+        'Check skepticCounts, challengeTypeCounts, confidenceAdjustments, warningCodes, challengedClaimsPath, and no-investment-advice safety metadata.',
+      ],
+      parameters: VENTURE_INSPECT_SKEPTIC_TOOL_PARAMETERS,
+      async execute(_toolCallId, params = {}, signal) {
+        try {
+          ensureNotAborted(signal, VENTURE_INSPECT_SKEPTIC_TOOL_NAME);
+          return toolResult(await inspectVentureSkeptic({
+            projectRoot: resolveProjectRoot(null, params.projectRoot),
+            runId: params.runId,
+            stage: params.stage ?? SKEPTIC_STAGE,
+          }));
+        } catch (error) {
+          return toolResult(baseEnvelope('inspect', {
+            status: 'error',
+            errors: [diagnostic(
+              error?.name === 'AbortError' ? 'VENTURE_SKEPTIC_INSPECT_ABORTED' : 'VENTURE_SKEPTIC_INSPECT_FAILED',
+              'Venture Signal Skeptic inspection tool execution failed before producing a complete result.',
+              { reason: error instanceof Error ? error.message : String(error) },
+            )],
+            durableStateChanged: false,
+            safeNextAction: { command: VENTURE_INSPECT_SKEPTIC_TOOL_NAME, reason: 'Retry Skeptic inspection after resolving the tool failure.' },
+            extra: { stage: SKEPTIC_STAGE, runId: null, summary: null, diagnostics: null, challengedClaims: null },
+          }));
+        }
+      },
+    },
+  ];
+}
+
+export function createVentureToolResult(result) {
+  return toolResult(result);
+}
+
+export function compactVentureText(result) {
+  return compactText(result);
+}