@jacfrost/autopm 0.0.1

package/src/autopm/opportunities-commands.js

@@ -0,0 +1,859 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  PM_WRITER_STAGE,
+  VENTURE_SIGNAL_LATEST_PATH,
+  normalizeVentureRunId,
+} from '../venture-signal/contracts.js';
+import { getDefaultFreeVentureSourceBundle } from '../venture-signal/default-sources.js';
+import {
+  buildVentureRefreshStatusRecord,
+  createDefaultVentureRefreshPolicy,
+  createOptInFreeSourceRefreshPolicy,
+  loadVentureRefreshPolicyState,
+  persistVentureRefreshPolicy,
+  persistVentureRefreshStatus,
+  readVentureRefreshStatus,
+  VENTURE_REFRESH_POLICY_PATH,
+  VENTURE_REFRESH_STATUS_PATH,
+} from '../venture-signal/policy.js';
+import { runVentureSignalWriter } from '../venture-signal/runner.js';
+import { SECRET_LOOKING_PATTERN } from '../venture-signal/schemas.js';
+
+export const OPPORTUNITIES_COMMAND_NAME = 'opportunities';
+
+const DEFAULT_NOW = '2026-05-18T12:00:00.000Z';
+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}$/;
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function uniqueCodes(values) {
+  return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))];
+}
+
+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 diagnostic(code, message, details = {}, severity = 'info', category = 'guided-workflow') {
+  return {
+    code,
+    severity,
+    category,
+    message: redactSensitiveText(message),
+    timestamp: new Date().toISOString(),
+    details: Object.fromEntries(Object.entries(details).map(([key, value]) => [key, typeof value === 'string' ? redactSensitiveText(value) : value])),
+  };
+}
+
+function isBenignPmWriterDiagnostic(entry) {
+  return entry?.category === 'stage-execution-status'
+    && typeof entry?.code === 'string'
+    && entry.code.endsWith('-not-sector-memo');
+}
+
+function isWarningDiagnostic(entry) {
+  return (entry?.severity === 'warning' || entry?.status === 'warn') && !isBenignPmWriterDiagnostic(entry);
+}
+
+function isErrorDiagnostic(entry) {
+  return entry?.severity === 'error' || entry?.status === 'error';
+}
+
+function parseOpportunitiesArgs(args) {
+  const tokens = normalizeArgs(args).split(/\s+/).filter(Boolean);
+  const state = {
+    json: false,
+    help: false,
+    refresh: false,
+    pipeline: false,
+    topic: undefined,
+    runId: undefined,
+    errors: [],
+    freeTextParts: [],
+  };
+
+  if (tokens[0] === 'auto') {
+    state.auto = true;
+    state.autoAction = undefined;
+    for (let index = 1; index < tokens.length; index += 1) {
+      const token = tokens[index];
+      if (token === '--json') {
+        state.json = true;
+        continue;
+      }
+      if (token === 'status' || token === 'on' || token === 'off') {
+        if (state.autoAction !== undefined) state.errors.push('Only one opportunities policy action may be provided.');
+        else state.autoAction = token;
+        continue;
+      }
+      if (token.startsWith('--')) {
+        state.errors.push(`Unsupported flag: ${safeFlagName(token)}`);
+        continue;
+      }
+      state.errors.push('Unknown auto policy argument: [redacted-argument]');
+    }
+    state.autoAction ??= 'status';
+    return state;
+  }
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === '--json') {
+      state.json = true;
+      continue;
+    }
+    if (token === '--refresh') {
+      state.refresh = true;
+      continue;
+    }
+    if (token === '--pipeline' || token === '--legacy-pm-writer') {
+      state.pipeline = 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 === '--topic') {
+      const parts = [];
+      let next = index + 1;
+      while (next < tokens.length && !tokens[next].startsWith('--')) {
+        parts.push(tokens[next]);
+        next += 1;
+      }
+      if (parts.length === 0) state.errors.push('Flag --topic requires non-empty text.');
+      else {
+        state.topic = parts.join(' ');
+        index = next - 1;
+      }
+      continue;
+    }
+    if (token.startsWith('--topic=')) {
+      const value = token.slice('--topic='.length).trim();
+      if (value === '') state.errors.push('Flag --topic requires non-empty text.');
+      else state.topic = value;
+      continue;
+    }
+    if (token.startsWith('--')) {
+      state.errors.push(`Unsupported flag: ${safeFlagName(token)}`);
+      continue;
+    }
+    state.freeTextParts.push(token);
+  }
+
+  if (state.freeTextParts.length > 0) {
+    state.errors.push('Unknown argument: [redacted-argument]');
+  }
+  delete state.freeTextParts;
+
+  return state;
+}
+
+function usageText() {
+  return [
+    'Usage:',
+    '  /opportunities                              - open the AI-first opportunity research workflow',
+    '  /opportunities <natural-language request>   - ask the AI to intake world information and discover opportunities',
+    '  /opportunities --pipeline [--refresh]        - internal deterministic PM Writer compatibility path',
+  ].join('\n');
+}
+
+function baseEnvelope(fields = {}) {
+  const warnings = Array.isArray(fields.warnings) ? fields.warnings : [];
+  const errors = Array.isArray(fields.errors) ? fields.errors : [];
+  return {
+    command: OPPORTUNITIES_COMMAND_NAME,
+    implemented: true,
+    delegatedLegacyCommand: null,
+    status: fields.status ?? (errors.length > 0 ? 'error' : warnings.length > 0 ? 'warn' : '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,
+    diagnostics: Array.isArray(fields.diagnostics) ? fields.diagnostics : [],
+    durableStateChanged: fields.durableStateChanged === true,
+    safeNextAction: fields.safeNextAction ?? null,
+    nextAction: fields.nextAction ?? fields.safeNextAction?.command ?? null,
+    ...fields.extra,
+  };
+}
+
+function argumentFailure(messages) {
+  const errors = messages.map((message) => diagnostic('CLI_ARG_INVALID', message, { usage: usageText() }, 'error', 'argument-validation'));
+  return baseEnvelope({
+    status: 'error',
+    errors,
+    durableStateChanged: false,
+    safeNextAction: { command: '/opportunities', reason: 'Retry with supported /opportunities flags or natural-language world-intake intent.' },
+    extra: { usage: usageText() },
+  });
+}
+
+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'));
+}
+
+async function readLatest(projectRoot) {
+  return readJsonArtifact(projectRoot, VENTURE_SIGNAL_LATEST_PATH);
+}
+
+function freshnessDecision(latest, { refresh = false } = {}) {
+  if (refresh) {
+    return { refreshNeeded: true, refreshReason: 'explicit-refresh', latestUsable: false, freshnessStatus: latest?.freshness?.status ?? 'unknown' };
+  }
+  if (!isPlainObject(latest)) {
+    return { refreshNeeded: true, refreshReason: 'latest-unavailable', latestUsable: false, freshnessStatus: 'unknown' };
+  }
+  if (latest.stage !== PM_WRITER_STAGE) {
+    return { refreshNeeded: true, refreshReason: 'latest-stage-not-pm-writer', latestUsable: false, freshnessStatus: latest.freshness?.status ?? 'unknown' };
+  }
+  if (latest.status === 'error') {
+    return { refreshNeeded: true, refreshReason: 'latest-error', latestUsable: false, freshnessStatus: latest.freshness?.status ?? 'unknown' };
+  }
+  if (latest.freshness?.status === 'stale') {
+    return { refreshNeeded: true, refreshReason: 'latest-stale', latestUsable: false, freshnessStatus: latest.freshness.status };
+  }
+  return { refreshNeeded: false, refreshReason: 'fresh-pm-writer-latest', latestUsable: true, freshnessStatus: latest.freshness?.status ?? 'unknown' };
+}
+
+function defaultGuidedSourceRecords(params = {}) {
+  if (Array.isArray(params.sourceRecords)) return clone(params.sourceRecords);
+  return [];
+}
+
+function defaultGuidedSourceBundle(params = {}) {
+  if (isPlainObject(params.sourceBundle)) return params.sourceBundle;
+  return getDefaultFreeVentureSourceBundle();
+}
+
+function safeRecommendationSummary(recommendation) {
+  return {
+    recommendationId: recommendation.recommendationId,
+    recommendationType: recommendation.recommendationType,
+    marketTrendId: recommendation.marketTrendId,
+    title: recommendation.title,
+    thesis: recommendation.thesis,
+    confidence: recommendation.confidence,
+    risk: recommendation.risk,
+    evidenceRefCount: Array.isArray(recommendation.evidenceRefs) ? recommendation.evidenceRefs.length : 0,
+    skepticRefCount: Array.isArray(recommendation.skepticRefs) ? recommendation.skepticRefs.length : 0,
+    evidenceRefs: recommendation.evidenceRefs ?? [],
+    skepticRefs: recommendation.skepticRefs ?? [],
+    nextActions: recommendation.nextActions ?? [],
+    mvpValidationExperiments: recommendation.mvpValidationExperiments ?? [],
+  };
+}
+
+function topicHaystackForRecommendation(recommendation) {
+  return [
+    recommendation.recommendationId,
+    recommendation.recommendationType,
+    recommendation.marketTrendId,
+    recommendation.title,
+    recommendation.thesis,
+    recommendation.targetUser,
+    recommendation.whyNow,
+    ...(recommendation.evidenceRefs ?? []).flatMap((ref) => [ref.signalId, ref.signalType, ref.signalPath, ref.sourceId]),
+    ...(recommendation.skepticRefs ?? []).flatMap((ref) => [ref.challengeId, ref.challengeType, ref.challengedClaim]),
+  ].filter((value) => typeof value === 'string').join(' ').toLowerCase();
+}
+
+function topicFilterFor(topic, recommendations) {
+  const normalized = typeof topic === 'string' ? topic.trim().toLowerCase() : '';
+  if (normalized === '') {
+    return {
+      requested: false,
+      topic: null,
+      mode: 'none',
+      matchedRecommendationIds: [],
+      filteredOutRecommendationIds: [],
+    };
+  }
+  const terms = normalized.split(/\s+/).filter(Boolean);
+  const matched = recommendations.filter((recommendation) => {
+    const haystack = topicHaystackForRecommendation(recommendation);
+    return terms.every((term) => haystack.includes(term));
+  });
+  const effectiveMatches = matched.length > 0 ? matched : recommendations;
+  return {
+    requested: true,
+    topic,
+    normalizedTopic: normalized,
+    mode: matched.length > 0 ? 'matched-summary-filter' : 'hint-only-no-match',
+    matchedRecommendationIds: matched.map((recommendation) => recommendation.recommendationId),
+    filteredOutRecommendationIds: recommendations
+      .filter((recommendation) => !effectiveMatches.includes(recommendation))
+      .map((recommendation) => recommendation.recommendationId),
+  };
+}
+
+function summarizeOutputs({ result, latest = null, topic, source }) {
+  const dailyRadar = result.dailyRadar;
+  const sectorMemos = Array.isArray(result.sectorMemos) ? result.sectorMemos : [];
+  const recommendations = Array.isArray(dailyRadar?.recommendations) ? dailyRadar.recommendations : [];
+  const topicFilter = topicFilterFor(topic, recommendations);
+  const returnedRecommendations = topicFilter.requested && topicFilter.matchedRecommendationIds.length > 0
+    ? recommendations.filter((recommendation) => topicFilter.matchedRecommendationIds.includes(recommendation.recommendationId))
+    : recommendations;
+  const returnedMarketTrendIds = new Set(returnedRecommendations.map((recommendation) => recommendation.marketTrendId));
+  const returnedMemos = topicFilter.requested && topicFilter.matchedRecommendationIds.length > 0
+    ? sectorMemos.filter((memo) => returnedMarketTrendIds.has(memo.marketTrendId))
+    : sectorMemos;
+
+  return {
+    runId: result.runId,
+    role: result.role ?? PM_WRITER_STAGE,
+    stage: result.stage ?? PM_WRITER_STAGE,
+    stageStatuses: result.stageStatuses ?? dailyRadar?.roleStageTrace?.stageStatuses ?? latest?.stageStatuses ?? null,
+    latestPath: VENTURE_SIGNAL_LATEST_PATH,
+    latestPromoted: source === 'refresh' ? result.latestPromoted === true : true,
+    previousLatestPreserved: source === 'refresh' ? result.previousLatestPreserved === true : true,
+    writerPaths: result.writerPaths ?? latest?.writerPaths ?? {
+      summary: result.summaryPath ?? latest?.summaryPath ?? null,
+      diagnostics: result.diagnosticsPath ?? latest?.diagnosticsPath ?? null,
+      dailyRadarJson: dailyRadar?.artifactPath ?? latest?.dailyRadarPath ?? null,
+      sectorMemoJson: sectorMemos[0]?.artifactPath ?? null,
+    },
+    topicFilter,
+    radar: dailyRadar ? {
+      path: dailyRadar.artifactPath,
+      title: dailyRadar.title,
+      summary: dailyRadar.summary,
+      generatedAt: dailyRadar.generatedAt,
+      totalRecommendationCount: recommendations.length,
+      returnedRecommendationCount: returnedRecommendations.length,
+      alertCandidateCount: Array.isArray(dailyRadar.alertCandidates) ? dailyRadar.alertCandidates.length : 0,
+      mvpValidationExperimentCount: Array.isArray(dailyRadar.mvpValidationExperiments) ? dailyRadar.mvpValidationExperiments.length : 0,
+      sourceTraceCoverage: dailyRadar.roleStageTrace?.sourceTraceCoverage ?? null,
+      roleStageTrace: dailyRadar.roleStageTrace ?? null,
+      recommendations: returnedRecommendations.map(safeRecommendationSummary),
+    } : null,
+    sectorMemos: returnedMemos.map((memo) => ({
+      path: memo.artifactPath,
+      marketTrendId: memo.marketTrendId,
+      sectorName: memo.sectorName,
+      executiveSummary: memo.executiveSummary,
+      generatedAt: memo.generatedAt,
+      template: memo.template,
+      roleStageTrace: memo.roleStageTrace,
+      evidenceRefCount: Array.isArray(memo.evidenceRefs) ? memo.evidenceRefs.length : 0,
+      skepticRefCount: Array.isArray(memo.skepticRefs) ? memo.skepticRefs.length : 0,
+      recommendations: (memo.recommendations ?? []).map(safeRecommendationSummary),
+      mvpValidationExperiments: memo.mvpValidationExperiments ?? [],
+    })),
+    alertCandidates: dailyRadar?.alertCandidates ?? result.alertCandidates ?? [],
+    safeActions: uniqueCodes(returnedRecommendations.flatMap((recommendation) => (recommendation.nextActions ?? []).map((action) => action.label))),
+    safety: dailyRadar?.safety ?? result.safety ?? null,
+  };
+}
+
+function diagnosticsForWorkflow({ decision, executionPlan, stageStatuses, topicFilter, artifactPathsRead, artifactPathsWritten, source }) {
+  const diagnostics = [];
+  diagnostics.push(diagnostic(
+    'opportunities-freshness-decision',
+    `Guided opportunities workflow selected ${decision.refreshNeeded ? 'refresh' : 'latest PM Writer artifacts'} because ${decision.refreshReason}.`,
+    { refreshNeeded: decision.refreshNeeded, refreshReason: decision.refreshReason, freshnessStatus: decision.freshnessStatus, source },
+    decision.refreshNeeded ? 'warning' : 'info',
+    'freshness-decision',
+  ));
+  diagnostics.push(diagnostic(
+    'opportunities-stage-execution-plan',
+    'Guided opportunities workflow recorded the stage execution plan.',
+    { executionPlan },
+    'info',
+    'stage-execution-plan',
+  ));
+  diagnostics.push(diagnostic(
+    'opportunities-stage-statuses',
+    'Guided opportunities workflow captured current stage statuses.',
+    { stageStatuses: stageStatuses ?? {} },
+    Object.values(stageStatuses ?? {}).includes('error') ? 'error' : 'info',
+    'stage-execution-status',
+  ));
+  diagnostics.push(diagnostic(
+    'opportunities-topic-filter',
+    topicFilter.requested
+      ? `Guided opportunities workflow applied topic filter hint: ${topicFilter.mode}.`
+      : 'Guided opportunities workflow ran without a topic filter hint.',
+    topicFilter,
+    topicFilter.mode === 'hint-only-no-match' ? 'warning' : 'info',
+    'topic-filter',
+  ));
+  diagnostics.push(diagnostic(
+    'opportunities-artifact-trace',
+    'Guided opportunities workflow recorded artifact paths read and written.',
+    { readCount: artifactPathsRead.length, writtenCount: artifactPathsWritten.length },
+    'info',
+    'artifact-trace',
+  ));
+  diagnostics.push(diagnostic(
+    'opportunities-safe-next-action',
+    'Guided opportunities workflow returned safe next-action messaging only.',
+    { command: '/opportunities' },
+    'info',
+    'safe-next-action',
+  ));
+  return diagnostics;
+}
+
+async function refreshPmWriterArtifacts({ projectRoot, runId, now, sourceRecords, sourceBundle }) {
+  const normalizedRunId = typeof runId === 'string' && runId.trim() !== ''
+    ? normalizeVentureRunId(runId)
+    : `opportunities-${Date.now()}`;
+  return runVentureSignalWriter({
+    rootDir: projectRoot,
+    runId: normalizedRunId,
+    now: now ?? DEFAULT_NOW,
+    sourceBundle: defaultGuidedSourceBundle({ sourceBundle, sourceRecords }),
+    sourceRecords: defaultGuidedSourceRecords({ sourceRecords }),
+    includePaidExtensions: false,
+  });
+}
+
+function policySummaryFromEvaluation(evaluation) {
+  return {
+    policyPath: VENTURE_REFRESH_POLICY_PATH,
+    statusPath: VENTURE_REFRESH_STATUS_PATH,
+    status: evaluation.status,
+    mode: evaluation.mode,
+    refreshAllowed: evaluation.refreshAllowed,
+    refreshScope: evaluation.refreshScope,
+    allowedAccessModes: evaluation.allowedAccessModes ?? [],
+    cooldown: evaluation.cooldown,
+    requiresExplicitOptIn: evaluation.policy?.requiresExplicitOptIn === true,
+    freeSourceOnlyEnforced: true,
+    diagnostics: evaluation.diagnostics ?? [],
+  };
+}
+
+function latestAttemptFromStatus(statusArtifact) {
+  return isPlainObject(statusArtifact?.lastRefreshAttempt) ? statusArtifact.lastRefreshAttempt : null;
+}
+
+function autoPolicyEnvelope({ action, policyState, statusArtifact = null, statusRead = null, artifactPathsWritten = [], errors = [], warnings = [], durableStateChanged = false }) {
+  const evaluation = policyState.evaluation;
+  const policyErrors = (evaluation.diagnostics ?? []).filter((entry) => entry.severity === 'error' || entry.status === 'rejected');
+  const policyWarnings = (evaluation.diagnostics ?? []).filter((entry) => entry.severity === 'warning' || entry.status === 'warn');
+  const readWarnings = statusRead?.error ? [statusRead.error] : [];
+  const allErrors = [...policyErrors, ...errors];
+  const allWarnings = [...policyWarnings, ...readWarnings, ...warnings];
+  const artifactPathsRead = uniqueCodes([
+    ...(policyState.artifactPathsRead ?? []),
+    ...(statusRead?.artifactPathsRead ?? []),
+  ]);
+
+  return baseEnvelope({
+    status: allErrors.length > 0 ? 'error' : allWarnings.length > 0 ? 'warn' : 'ok',
+    artifactPathsRead,
+    artifactPathsWritten: uniqueCodes(artifactPathsWritten),
+    warnings: allWarnings,
+    errors: allErrors,
+    diagnostics: [...(evaluation.diagnostics ?? []), ...readWarnings, ...warnings, ...errors],
+    durableStateChanged,
+    safeNextAction: {
+      command: action === 'on' ? '/loop tick' : '/opportunities enable bounded free-source opportunity refresh when useful',
+      reason: action === 'on'
+        ? 'Heartbeat can now run a bounded default free-source refresh when venture latest is stale or missing and cooldown permits.'
+        : 'Opt in only if proactive local venture refresh is desired; default behavior remains suggest-only.',
+    },
+    extra: {
+      auto: {
+        action,
+        persisted: policyState.persisted === true,
+        policy: policySummaryFromEvaluation(evaluation),
+        lastRefreshAttempt: latestAttemptFromStatus(statusArtifact),
+        statusArtifact,
+      },
+    },
+  });
+}
+
+export function executeOpportunitiesAutoPolicyCommand(action, { projectRoot = process.cwd(), now = new Date() } = {}) {
+  const initialPolicyState = loadVentureRefreshPolicyState({ projectRoot, now });
+  const statusRead = readVentureRefreshStatus({ projectRoot });
+  let policyState = initialPolicyState;
+  let artifactPathsWritten = [];
+  let errors = [];
+  let durableStateChanged = false;
+
+  if (action === 'on' || action === 'off') {
+    const lastRefreshAt = typeof initialPolicyState.evaluation?.cooldown?.lastRefreshAt === 'string'
+      ? initialPolicyState.evaluation.cooldown.lastRefreshAt
+      : null;
+    const nextPolicy = action === 'on'
+      ? createOptInFreeSourceRefreshPolicy({ lastRefreshAt })
+      : createDefaultVentureRefreshPolicy({ lastRefreshAt });
+    const persisted = persistVentureRefreshPolicy({ projectRoot, policy: nextPolicy, now });
+    artifactPathsWritten.push(...persisted.artifactPathsWritten);
+    if (!persisted.ok) errors.push(persisted.error);
+    policyState = loadVentureRefreshPolicyState({ projectRoot, now });
+    durableStateChanged = persisted.ok;
+  }
+
+  const shouldPersistStatus = action === 'on' || action === 'off' || policyState.persisted === true || policyState.evaluation.ok === false;
+  let statusArtifact = statusRead.status;
+  if (shouldPersistStatus) {
+    statusArtifact = buildVentureRefreshStatusRecord({
+      now,
+      action: `auto-${action}`,
+      policyEvaluation: policyState.evaluation,
+      lastRefreshAttempt: latestAttemptFromStatus(statusRead.status),
+      skippedReason: policyState.evaluation.refreshAllowed ? null : policyState.evaluation.status,
+      artifactPathsWritten,
+      diagnostics: errors,
+    });
+    const persistedStatus = persistVentureRefreshStatus({ projectRoot, statusRecord: statusArtifact });
+    artifactPathsWritten.push(...persistedStatus.artifactPathsWritten);
+    if (!persistedStatus.ok) errors.push(persistedStatus.error);
+    durableStateChanged = durableStateChanged || persistedStatus.ok;
+  }
+
+  return autoPolicyEnvelope({
+    action,
+    policyState,
+    statusArtifact,
+    statusRead,
+    artifactPathsWritten,
+    errors,
+    durableStateChanged,
+  });
+}
+
+export function runAgenticOpportunitiesWorkflow(params = {}) {
+  const topic = typeof params.topic === 'string' && params.topic.trim() !== '' ? params.topic.trim() : null;
+  const requestedRefresh = params.refresh === true;
+  const executionPlan = [
+    'world-intake',
+    'ai-sensemaking',
+    'ai-opportunity-hypotheses',
+    'ai-skeptic-review',
+    'ai-pm-opportunity-brief',
+    'script-validation-redaction-persistence',
+  ];
+  const diagnostics = [
+    diagnostic(
+      'opportunities-ai-first-boundary',
+      'AutoPM opportunities is AI-first: scripts validate and preserve evidence; AI owns judgment.',
+      { deterministicScoresAreFinalJudgment: false, scriptsOwnJudgment: false, aiOwnsJudgment: true },
+      'info',
+      'agentic-workflow-boundary',
+    ),
+    diagnostic(
+      'opportunities-world-intake-required',
+      'World information must be collected with built-in web_search/fetch_content before opportunity conclusions are generated.',
+      { requestedRefresh, topic, acceptedInputs: ['built-in web_search/fetch_content', 'operator-provided evidence', 'local product context', 'existing artifacts as evidence only'] },
+      requestedRefresh ? 'warning' : 'info',
+      'world-intake',
+    ),
+    diagnostic(
+      'opportunities-deterministic-pipeline-demoted',
+      'Deterministic Venture Signal / PM Writer outputs are compatibility evidence, not final opportunity recommendations.',
+      { compatibilityCommand: '/opportunities --pipeline', disallowedFirstStep: 'deterministic-pm-writer-refresh' },
+      'info',
+      'deterministic-pipeline-boundary',
+    ),
+  ];
+
+  return baseEnvelope({
+    status: requestedRefresh ? 'warn' : 'ok',
+    diagnostics,
+    warnings: diagnostics.filter((entry) => entry.severity === 'warning'),
+    durableStateChanged: false,
+    safeNextAction: {
+      command: '/opportunities <market, customer, or trend focus>',
+      reason: 'Start with built-in web_search/fetch_content, then let AI frame, challenge, and brief opportunities before any local artifact write.',
+    },
+    extra: {
+      runId: params.runId ?? null,
+      stage: 'ai-opportunity-research',
+      workflow: {
+        source: 'ai-first',
+        refreshReason: requestedRefresh ? 'operator-requested-world-intake-not-script-refresh' : 'agentic-opportunity-research',
+        executionPlan,
+        topicFilter: topic ? { requested: true, topic, mode: 'ai-semantic-frame' } : { requested: false, topic: null, mode: 'none' },
+        judgmentOwner: 'ai',
+        scriptRole: 'validation-redaction-persistence-only',
+        deterministicPipeline: 'demoted-to-evidence-substrate',
+      },
+      worldIntake: {
+        required: true,
+        authorizedSourcesNeeded: true,
+        acceptedSourceKinds: ['built-in web_search/fetch_content', 'operator-provided evidence', 'local files', 'existing Venture artifacts as evidence only'],
+        conclusionGenerated: false,
+        reason: 'AI should collect live world-intake evidence with built-in web tools before producing a brief.',
+      },
+      opportunityBrief: null,
+    },
+  });
+}
+
+async function readPmWriterArtifactsFromLatest(projectRoot, latest) {
+  const writerPaths = latest.writerPaths ?? {};
+  const summaryPath = writerPaths.summary ?? latest.summaryPath;
+  const diagnosticsPath = writerPaths.diagnostics ?? latest.diagnosticsPath;
+  const dailyRadarPath = writerPaths.dailyRadarJson ?? latest.dailyRadarPath;
+  const sectorMemoPath = writerPaths.sectorMemoJson ?? null;
+  const paths = [summaryPath, diagnosticsPath, dailyRadarPath, sectorMemoPath].filter((value) => typeof value === 'string' && value.length > 0);
+  const [summary, diagnosticsArtifact, dailyRadar, sectorMemo] = await Promise.all([
+    summaryPath ? readJsonArtifact(projectRoot, summaryPath) : null,
+    diagnosticsPath ? readJsonArtifact(projectRoot, diagnosticsPath) : null,
+    dailyRadarPath ? readJsonArtifact(projectRoot, dailyRadarPath) : null,
+    sectorMemoPath ? readJsonArtifact(projectRoot, sectorMemoPath) : null,
+  ]);
+  return {
+    runId: latest.runId,
+    role: latest.role,
+    stage: latest.stage,
+    status: latest.status,
+    stageStatuses: latest.stageStatuses ?? dailyRadar?.roleStageTrace?.stageStatuses ?? null,
+    writerPaths: {
+      ...writerPaths,
+      summary: summaryPath,
+      diagnostics: diagnosticsPath,
+      dailyRadarJson: dailyRadarPath,
+      sectorMemoJson: sectorMemoPath,
+    },
+    summaryPath,
+    diagnosticsPath,
+    summary,
+    dailyRadar,
+    sectorMemos: sectorMemo ? [sectorMemo] : [],
+    alertCandidates: dailyRadar?.alertCandidates ?? [],
+    diagnostics: diagnosticsArtifact?.diagnostics ?? summary?.diagnostics ?? [],
+    artifactPathsRead: [VENTURE_SIGNAL_LATEST_PATH, ...paths],
+  };
+}
+
+export async function runGuidedOpportunitiesWorkflow(params = {}) {
+  const projectRoot = typeof params.projectRoot === 'string' && params.projectRoot.trim() !== '' ? params.projectRoot : process.cwd();
+  const artifactPathsRead = [];
+  let latest = null;
+  let latestReadError = null;
+
+  try {
+    latest = await readLatest(projectRoot);
+    artifactPathsRead.push(VENTURE_SIGNAL_LATEST_PATH);
+  } catch (error) {
+    latestReadError = error;
+  }
+
+  const decision = freshnessDecision(latest, { refresh: params.refresh === true });
+  if (latestReadError && decision.refreshReason === 'latest-unavailable') {
+    decision.latestReadError = latestReadError instanceof Error ? latestReadError.message : String(latestReadError);
+  }
+
+  try {
+    const executionPlan = decision.refreshNeeded
+      ? ['collector', 'normalizer', 'analyst', 'skeptic', PM_WRITER_STAGE]
+      : ['read-latest', PM_WRITER_STAGE];
+    const source = decision.refreshNeeded ? 'refresh' : 'latest';
+    const result = decision.refreshNeeded
+      ? await refreshPmWriterArtifacts({
+        projectRoot,
+        runId: params.runId,
+        now: params.now,
+        sourceRecords: params.sourceRecords,
+        sourceBundle: params.sourceBundle,
+      })
+      : await readPmWriterArtifactsFromLatest(projectRoot, latest);
+
+    const readPaths = uniqueCodes([
+      ...artifactPathsRead,
+      ...(result.artifactPathsRead ?? []),
+      ...(source === 'refresh' ? result.summary?.artifacts?.read ?? [] : []),
+    ]);
+    const writtenPaths = source === 'refresh' ? result.written ?? [] : [];
+    const summaries = summarizeOutputs({ result, latest, topic: params.topic, source });
+    const workflowDiagnostics = diagnosticsForWorkflow({
+      decision,
+      executionPlan,
+      stageStatuses: summaries.stageStatuses,
+      topicFilter: summaries.topicFilter,
+      artifactPathsRead: readPaths,
+      artifactPathsWritten: writtenPaths,
+      source,
+    });
+    const writerDiagnostics = Array.isArray(result.diagnostics) ? result.diagnostics : [];
+    const allDiagnostics = [...workflowDiagnostics, ...writerDiagnostics];
+    const warnings = allDiagnostics.filter(isWarningDiagnostic);
+    const errors = allDiagnostics.filter(isErrorDiagnostic);
+
+    return baseEnvelope({
+      status: errors.length > 0 ? 'error' : warnings.length > 0 ? 'warn' : 'ok',
+      generatedAt: result.summary?.completedAt ?? result.dailyRadar?.generatedAt ?? latest?.updatedAt,
+      artifactPathsRead: readPaths,
+      artifactPathsWritten: writtenPaths,
+      warnings,
+      errors,
+      diagnostics: allDiagnostics,
+      durableStateChanged: writtenPaths.length > 0,
+      safeNextAction: {
+        command: summaries.sectorMemos.length > 0 ? '/opportunities focus on <market, customer, or validation question>' : '/opportunities find new opportunities from current product context',
+        reason: summaries.sectorMemos.length > 0
+          ? 'Review evidence and Skeptic traces before running the listed validation experiments.'
+          : 'Refresh PM Writer artifacts if no sector memo matched the topic hint.',
+      },
+      extra: {
+        workflow: {
+          source,
+          freshnessDecision: decision,
+          executionPlan,
+          refreshReason: decision.refreshReason,
+          topicFilter: summaries.topicFilter,
+        },
+        ...summaries,
+      },
+    });
+  } catch (error) {
+    const errorDiagnostic = diagnostic(
+      error?.name === 'AbortError' ? 'OPPORTUNITIES_WORKFLOW_ABORTED' : 'OPPORTUNITIES_WORKFLOW_FAILED',
+      'Guided opportunities workflow failed before returning PM Writer outputs.',
+      { reason: error instanceof Error ? error.message : String(error), refreshReason: decision.refreshReason },
+      'error',
+      'workflow-failure',
+    );
+    return baseEnvelope({
+      status: 'error',
+      artifactPathsRead,
+      errors: [errorDiagnostic],
+      diagnostics: [errorDiagnostic],
+      durableStateChanged: false,
+      safeNextAction: { command: '/opportunities find new opportunities from current product context', reason: 'Retry with a full default free-source refresh after inspecting the workflow failure.' },
+      extra: {
+        runId: params.runId ?? null,
+        stage: PM_WRITER_STAGE,
+        workflow: { source: 'error', freshnessDecision: decision, executionPlan: [], refreshReason: decision.refreshReason },
+      },
+    });
+  }
+}
+
+export function opportunitiesCommandCompletions(prefix = '') {
+  const trimmed = normalizeArgs(prefix).toLowerCase();
+  return [
+    { value: '', label: 'open', description: 'Open the conversational AutoPM opportunities workflow' },
+  ].filter((completion) => completion.value.toLowerCase().startsWith(trimmed));
+}
+
+export function compactOpportunitiesText(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';
+  const recommendations = result.radar?.recommendations ?? [];
+  const memos = result.sectorMemos ?? [];
+  if (result.auto) {
+    return [
+      `AutoPM opportunities auto: ${result.status ?? 'unknown'}`,
+      `action: ${result.auto.action ?? 'status'}`,
+      `mode: ${result.auto.policy?.mode ?? 'unknown'}`,
+      `policyStatus: ${result.auto.policy?.status ?? 'unknown'}`,
+      `refreshAllowed: ${result.auto.policy?.refreshAllowed === true}`,
+      `cooldown: ${result.auto.policy?.cooldown?.status ?? 'unknown'}`,
+      `cooldownRemainingMs: ${result.auto.policy?.cooldown?.remainingMs ?? 0}`,
+      `lastRefreshAttempt: ${result.auto.lastRefreshAttempt?.status ?? 'none'}`,
+      `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');
+  }
+  return [
+    `AutoPM opportunities: ${result.status ?? 'unknown'}`,
+    `runId: ${result.runId ?? 'none'}`,
+    `source: ${result.workflow?.source ?? 'unknown'}`,
+    `refreshReason: ${result.workflow?.refreshReason ?? 'unknown'}`,
+    `topicFilter: ${result.workflow?.topicFilter?.mode ?? 'none'}`,
+    `radarPath: ${result.radar?.path ?? 'none'}`,
+    `recommendations: ${recommendations.length}`,
+    `sectorMemos: ${memos.length}`,
+    `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');
+}
+
+export function createOpportunitiesCommandHandler() {
+  return async function handleOpportunitiesCommand(args, ctx = {}) {
+    const parsed = parseOpportunitiesArgs(args);
+    if (parsed.help) {
+      return baseEnvelope({
+        status: parsed.errors.length > 0 ? 'error' : 'ok',
+        errors: parsed.errors.length > 0 ? [diagnostic('CLI_ARG_INVALID', parsed.errors.join('\n'), { usage: usageText() }, 'error', 'argument-validation')] : [],
+        durableStateChanged: false,
+        safeNextAction: { command: '/opportunities', reason: 'Run the AI-first opportunities workflow.' },
+        extra: { usage: usageText() },
+      });
+    }
+    if (parsed.errors.length > 0) return argumentFailure(parsed.errors);
+
+    const projectRoot = typeof ctx?.cwd === 'string' && ctx.cwd.trim() !== '' ? ctx.cwd : process.cwd();
+    if (parsed.auto === true) {
+      return executeOpportunitiesAutoPolicyCommand(parsed.autoAction, { projectRoot });
+    }
+    if (parsed.pipeline === true) {
+      return runGuidedOpportunitiesWorkflow({
+        projectRoot,
+        refresh: parsed.refresh,
+        topic: parsed.topic,
+        runId: parsed.runId,
+      });
+    }
+    return runAgenticOpportunitiesWorkflow({
+      projectRoot,
+      refresh: parsed.refresh,
+      topic: parsed.topic,
+      runId: parsed.runId,
+    });
+  };
+}