@jacfrost/autopm 0.0.1

package/src/venture-signal/pm-writer.js

@@ -0,0 +1,984 @@
+import {
+  analystDiagnosticsPath,
+  analystRunSummaryPath,
+  analystTrendScorePath,
+  analystTrendScoresPath,
+  pmWriterAlertCandidatesPath,
+  pmWriterDailyRadarPath,
+  pmWriterDiagnosticsPath,
+  pmWriterMvpExperimentsPath,
+  pmWriterRecommendationsPath,
+  pmWriterRunSummaryPath,
+  pmWriterSectorMemoPath,
+  skepticChallengePath,
+  skepticChallengesPath,
+  skepticDiagnosticsPath,
+  skepticRunSummaryPath,
+} from './contracts.js';
+import {
+  INVESTMENT_ADVICE_PATTERN,
+  PM_WRITER_ROLE,
+  PM_WRITER_STAGE,
+  SCHEMA_VERSION,
+  SECRET_LOOKING_PATTERN,
+} from './schemas.js';
+import { slugify } from './taxonomy.js';
+
+const DEFAULT_NOW = '2026-05-18T12:00:00.000Z';
+const SECRET_LOOKING_REGEX = new RegExp(SECRET_LOOKING_PATTERN);
+const INVESTMENT_ADVICE_REGEX = new RegExp(INVESTMENT_ADVICE_PATTERN, 'i');
+const STRONG_OPPORTUNITY_SCORE = 1.0;
+const WATCHLIST_OPPORTUNITY_SCORE = 0.45;
+const ALERT_MOMENTUM_THRESHOLD = 0.6;
+const ALERT_BUBBLE_RISK_THRESHOLD = 0.65;
+
+const RISK_LEVEL_WEIGHT = Object.freeze({ low: 0, medium: 1, high: 2 });
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function asArray(value) {
+  if (value === undefined || value === null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+function compactWhitespace(value) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim();
+}
+
+function sanitizeAnalysisText(value, fallback = 'PM Writer recorded bounded product-research guidance.') {
+  let sanitized = compactWhitespace(value).replace(SECRET_LOOKING_REGEX, '[redacted]');
+  if (sanitized === '') sanitized = fallback;
+  if (INVESTMENT_ADVICE_REGEX.test(sanitized)) sanitized = fallback;
+  return sanitized;
+}
+
+function safeCode(value, fallback = 'pm-writer') {
+  return slugify(String(value ?? fallback), { fallback, maxLength: 96 }) || fallback;
+}
+
+function normalizeTimestamp(value, fallback = DEFAULT_NOW) {
+  if (typeof value !== 'string' || value.trim() === '') return fallback;
+  const parsed = Date.parse(value);
+  if (Number.isNaN(parsed)) return fallback;
+  return new Date(parsed).toISOString();
+}
+
+function clamp(value, min = 0, max = 1) {
+  if (!Number.isFinite(value)) return min;
+  return Math.min(max, Math.max(min, value));
+}
+
+function roundScore(value) {
+  return Math.round(clamp(value, -1, 1) * 10000) / 10000;
+}
+
+function roundConfidence(value) {
+  return Math.round(clamp(value, 0, 0.9) * 10000) / 10000;
+}
+
+function roundRankScore(value) {
+  if (!Number.isFinite(value)) return 0;
+  return Math.round(value * 10000) / 10000;
+}
+
+function uniqueSorted(values) {
+  return [...new Set(values
+    .filter((value) => typeof value === 'string' && value.trim() !== '')
+    .map((value) => value.trim()))]
+    .sort((a, b) => a.localeCompare(b, 'en', { sensitivity: 'base' }));
+}
+
+function collectTrendScores(input) {
+  if (Array.isArray(input)) return input;
+  if (!isPlainObject(input)) return [];
+  if (Array.isArray(input.trendScores)) return input.trendScores;
+  if (Array.isArray(input.scores)) return input.scores;
+  if (isPlainObject(input.trendScoresArtifact) && Array.isArray(input.trendScoresArtifact.trendScores)) return input.trendScoresArtifact.trendScores;
+  if (isPlainObject(input.summary) && Array.isArray(input.summary.trendScores)) return input.summary.trendScores;
+  if (isPlainObject(input.scoredRunSummary) && Array.isArray(input.scoredRunSummary.trendScores)) return input.scoredRunSummary.trendScores;
+  return [];
+}
+
+function collectSkepticChallenges(input) {
+  if (!isPlainObject(input)) return [];
+  if (Array.isArray(input.skepticChallenges)) return input.skepticChallenges;
+  if (Array.isArray(input.challenges)) return input.challenges;
+  if (isPlainObject(input.challengesArtifact) && Array.isArray(input.challengesArtifact.challenges)) return input.challengesArtifact.challenges;
+  if (isPlainObject(input.summary) && Array.isArray(input.summary.skepticChallenges)) return input.summary.skepticChallenges;
+  if (isPlainObject(input.scoredRunSummary) && Array.isArray(input.scoredRunSummary.skepticChallenges)) return input.scoredRunSummary.skepticChallenges;
+  return [];
+}
+
+function runIdFor(input, trendScores, options) {
+  if (typeof options.runId === 'string' && options.runId.trim() !== '') return options.runId.trim();
+  if (isPlainObject(input) && typeof input.runId === 'string' && input.runId.trim() !== '') return input.runId.trim();
+  const fromTrend = trendScores.find((trendScore) => typeof trendScore?.runId === 'string' && trendScore.runId.trim() !== '');
+  return fromTrend?.runId ?? 'venture-signal-pm-writer';
+}
+
+function safetyMetadata() {
+  return {
+    noInvestmentAdvice: true,
+    purpose: 'product-research',
+    disclaimer: 'Directional product research only; not investment guidance.',
+    prohibitedUses: ['buy-sell-hold', 'fundraising-targeting', 'portfolio-allocation', 'price-prediction'],
+  };
+}
+
+function confidenceLabel(score) {
+  if (score >= 0.7) return 'high';
+  if (score >= 0.45) return 'medium';
+  return 'low';
+}
+
+function maxRiskLevel(levels) {
+  const candidates = levels.filter((level) => Object.hasOwn(RISK_LEVEL_WEIGHT, level));
+  return candidates.sort((a, b) => RISK_LEVEL_WEIGHT[b] - RISK_LEVEL_WEIGHT[a])[0] ?? 'low';
+}
+
+function challengesByTrend(challenges) {
+  const grouped = new Map();
+  for (const challenge of challenges) {
+    const trendId = challenge?.targetMarketTrendId;
+    if (typeof trendId !== 'string' || trendId.trim() === '') continue;
+    if (!grouped.has(trendId)) grouped.set(trendId, []);
+    grouped.get(trendId).push(challenge);
+  }
+  for (const [trendId, entries] of grouped.entries()) {
+    grouped.set(trendId, entries.sort((a, b) => String(a.challengeType).localeCompare(String(b.challengeType)) || String(a.challengeId).localeCompare(String(b.challengeId))));
+  }
+  return grouped;
+}
+
+function allSignalRefs(trendScore) {
+  return asArray(trendScore?.components)
+    .flatMap((component) => asArray(component?.signalRefs))
+    .filter(isPlainObject);
+}
+
+function uniqueSignalRefs(refs, limit = 6) {
+  const byId = new Map();
+  for (const ref of refs.filter(isPlainObject)) {
+    const key = typeof ref.signalId === 'string' && ref.signalId.trim() !== ''
+      ? ref.signalId
+      : JSON.stringify(ref);
+    if (!byId.has(key)) byId.set(key, ref);
+  }
+  return [...byId.values()]
+    .sort((a, b) => (b.strength ?? 0) - (a.strength ?? 0) || String(a.signalId).localeCompare(String(b.signalId)))
+    .slice(0, limit)
+    .map(clone);
+}
+
+function componentNamed(trendScore, componentName) {
+  return asArray(trendScore?.components).find((component) => component?.component === componentName) ?? null;
+}
+
+function adjustedConfidenceFor(trendScore, challenges) {
+  const originalScore = typeof trendScore?.confidence?.score === 'number' ? trendScore.confidence.score : 0.45;
+  const challengedScores = challenges
+    .map((challenge) => challenge?.confidence?.score)
+    .filter((score) => typeof score === 'number' && Number.isFinite(score));
+  const adjustedScore = roundConfidence(Math.min(originalScore, ...challengedScores));
+  const challengeReasons = uniqueSorted(challenges.flatMap((challenge) => asArray(challenge?.confidence?.downgradeReasons)));
+  const originalReasons = asArray(trendScore?.confidence?.downgradeReasons);
+  const downgradeReasons = uniqueSorted([...originalReasons, ...challengeReasons].map((reason) => sanitizeAnalysisText(reason)));
+  return {
+    label: confidenceLabel(adjustedScore),
+    score: adjustedScore,
+    rationale: challenges.length > 0
+      ? 'Confidence reflects the lowest Skeptic-adjusted challenge score before PM Writer ranking.'
+      : sanitizeAnalysisText(trendScore?.confidence?.rationale, 'Confidence reflects transparent Analyst evidence before PM Writer ranking.'),
+    downgraded: challenges.length > 0 || trendScore?.confidence?.downgraded === true,
+    downgradeReasons,
+    overclaimRisk: maxRiskLevel([
+      trendScore?.confidence?.overclaimRisk,
+      ...challenges.map((challenge) => challenge?.confidence?.overclaimRisk),
+      ...challenges.map((challenge) => challenge?.bubbleRisk?.level),
+    ]),
+  };
+}
+
+function skepticRefsFor(challenges, runId) {
+  return challenges.map((challenge) => ({
+    challengeId: safeCode(challenge.challengeId, `challenge-${challenge.targetMarketTrendId}`),
+    challengePath: typeof challenge.artifactPath === 'string' && challenge.artifactPath.trim() !== ''
+      ? challenge.artifactPath
+      : skepticChallengePath(runId, safeCode(challenge.challengeId, `challenge-${challenge.targetMarketTrendId}`)),
+    challengeType: challenge.challengeType,
+    targetTrendScoreId: challenge.targetTrendScoreId,
+    targetMarketTrendId: challenge.targetMarketTrendId,
+    challengedClaim: sanitizeAnalysisText(challenge.challengedClaim, 'Skeptic review narrowed this product-research claim.'),
+    counterEvidenceRefs: uniqueSignalRefs(asArray(challenge.counterEvidence), 4),
+  }));
+}
+
+function riskFor({ trendScore, evidenceRefs, skepticRefs, challenges }) {
+  const challengeDrivers = challenges.slice(0, 4).map((challenge) => ({
+    driverId: safeCode(`risk-${challenge.targetMarketTrendId}-${challenge.challengeType}`, 'risk-driver'),
+    source: 'skeptic',
+    rationale: sanitizeAnalysisText(challenge?.bubbleRisk?.rationale ?? challenge?.challengedClaim),
+    evidenceRefs: uniqueSignalRefs(asArray(challenge.counterEvidence), 3),
+    skepticRefs: skepticRefs.filter((ref) => ref.challengeId === challenge.challengeId),
+  }));
+
+  const analystDriver = {
+    driverId: safeCode(`analyst-${trendScore.marketTrendId}-evidence-quality`, 'analyst-driver'),
+    source: 'analyst',
+    rationale: sanitizeAnalysisText(trendScore?.sourceConcentration?.rationale ?? trendScore?.freshness?.rationale ?? 'Analyst evidence quality informs PM Writer risk.'),
+    evidenceRefs: uniqueSignalRefs(evidenceRefs, 3),
+    skepticRefs: [],
+  };
+
+  const drivers = challengeDrivers.length > 0 ? challengeDrivers : [analystDriver];
+  const level = maxRiskLevel([
+    trendScore?.confidence?.overclaimRisk,
+    ...challenges.map((challenge) => challenge?.bubbleRisk?.level),
+  ]);
+  return {
+    level,
+    rationale: level === 'high'
+      ? 'Skeptic review found high product-discovery risk that must be resolved before prototype work.'
+      : level === 'medium'
+        ? 'Skeptic review found material assumptions that should shape validation work.'
+        : 'Known risks are bounded enough for a narrow validation step.',
+    drivers,
+  };
+}
+
+function trendLabel(trendScore) {
+  return String(trendScore?.marketTrendId ?? 'opportunity')
+    .split('-')
+    .filter(Boolean)
+    .map((part) => part.slice(0, 1).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+function targetUserFor(trendScore) {
+  const customerComponent = componentNamed(trendScore, 'customer-pull');
+  return customerComponent?.budgetEvidencePresent
+    ? `Budget-owning operators evaluating ${trendLabel(trendScore).toLowerCase()} workflows.`
+    : `Operators tracking ${trendLabel(trendScore).toLowerCase()} pains before budget proof is visible.`;
+}
+
+function recommendationTypeFor(opportunityScore, riskLevel) {
+  if (opportunityScore >= STRONG_OPPORTUNITY_SCORE && riskLevel !== 'high') return 'opportunity-hypothesis';
+  if (opportunityScore >= WATCHLIST_OPPORTUNITY_SCORE) return 'watchlist';
+  return 'deprioritize';
+}
+
+function experimentTypeFor(recommendationType, challenges) {
+  if (challenges.some((challenge) => challenge.challengeType === 'missing-budget-evidence')) return 'sales-discovery';
+  if (recommendationType === 'watchlist') return 'landing-page-smoke-test';
+  return 'concierge-pilot';
+}
+
+function makeExperiment({ runId, trendScore, recommendationId, recommendationType, evidenceRefs, skepticRefs, confidence, risk, challenges }) {
+  const experimentType = experimentTypeFor(recommendationType, challenges);
+  const label = trendLabel(trendScore);
+  return {
+    experimentId: safeCode(`exp-${trendScore.marketTrendId}-${experimentType}`, 'experiment'),
+    recommendationId,
+    experimentType,
+    title: sanitizeAnalysisText(`Validate ${label} with a narrow customer-discovery loop.`),
+    hypothesis: sanitizeAnalysisText(`Qualified operators will describe a repeated ${label.toLowerCase()} pain and a current workaround.`),
+    method: experimentType === 'sales-discovery'
+      ? sanitizeAnalysisText('Run five structured discovery interviews with budget-owning operators and capture current workaround evidence.')
+      : sanitizeAnalysisText('Publish a focused problem statement and recruit operators for follow-up discovery.'),
+    metric: sanitizeAnalysisText('Count qualified operators who confirm urgency, current workaround, and owner accountability.'),
+    successThreshold: sanitizeAnalysisText('Three qualified operators confirm the same urgent workflow and a credible owner for follow-up.'),
+    durationDays: recommendationType === 'opportunity-hypothesis' ? 14 : 21,
+    evidenceRefs: clone(evidenceRefs),
+    skepticRefs: clone(skepticRefs),
+    confidence: clone(confidence),
+    risk: clone(risk),
+    safety: safetyMetadata(),
+  };
+}
+
+function makeNextActions(recommendationType, trendScore) {
+  const label = trendLabel(trendScore);
+  if (recommendationType === 'opportunity-hypothesis') {
+    return [{
+      actionId: safeCode(`validate-${trendScore.marketTrendId}`, 'validate-opportunity'),
+      label: sanitizeAnalysisText(`Prepare discovery script for ${label} and recruit five qualified operators.`),
+      owner: 'operator',
+      rationale: 'Human review should verify the evidence trace before any prototype work.',
+      safeAction: true,
+    }];
+  }
+  return [{
+    actionId: safeCode(`watch-${trendScore.marketTrendId}`, 'watch-opportunity'),
+    label: sanitizeAnalysisText(`Keep ${label} on the watchlist until Skeptic blockers narrow.`),
+    owner: 'human-review',
+    rationale: 'A lightweight review prevents overcommitting to a fragile signal.',
+    safeAction: true,
+  }];
+}
+
+function makeRecommendation({ runId, trendScore, challenges }) {
+  const evidenceRefs = uniqueSignalRefs(allSignalRefs(trendScore), 6);
+  const skepticRefs = skepticRefsFor(challenges, runId);
+  const confidence = adjustedConfidenceFor(trendScore, challenges);
+  const preliminaryRisk = riskFor({ trendScore, evidenceRefs, skepticRefs, challenges });
+  const opportunityScore = roundRankScore((trendScore?.score ?? 0) + confidence.score);
+  const recommendationType = recommendationTypeFor(opportunityScore, preliminaryRisk.level);
+  const recommendationId = safeCode(`rec-${trendScore.marketTrendId}-${recommendationType}`, 'recommendation');
+  const risk = riskFor({ trendScore, evidenceRefs, skepticRefs, challenges });
+  const experiment = makeExperiment({
+    runId,
+    trendScore,
+    recommendationId,
+    recommendationType,
+    evidenceRefs,
+    skepticRefs,
+    confidence,
+    risk,
+    challenges,
+  });
+
+  return {
+    recommendationId,
+    recommendationType,
+    marketTrendId: trendScore.marketTrendId,
+    title: recommendationType === 'opportunity-hypothesis'
+      ? sanitizeAnalysisText(`Explore ${trendLabel(trendScore)} as a product-discovery wedge.`)
+      : sanitizeAnalysisText(`Watch ${trendLabel(trendScore)} until validation evidence improves.`),
+    thesis: recommendationType === 'opportunity-hypothesis'
+      ? sanitizeAnalysisText(`The combined Analyst score and Skeptic-adjusted confidence make ${trendLabel(trendScore)} the clearest current PM opportunity.`)
+      : sanitizeAnalysisText(`${trendLabel(trendScore)} has visible signal activity but needs more validation before a PM commitment.`),
+    targetUser: sanitizeAnalysisText(targetUserFor(trendScore)),
+    whyNow: sanitizeAnalysisText(`Current public evidence gives ${trendLabel(trendScore)} an opportunity score of ${opportunityScore}.`),
+    evidenceRefs,
+    skepticRefs,
+    confidence,
+    risk,
+    mvpValidationExperiments: [experiment],
+    nextActions: makeNextActions(recommendationType, trendScore),
+    safety: safetyMetadata(),
+    _pmWriterRankScore: opportunityScore,
+  };
+}
+
+function publicRecommendation(recommendation) {
+  const result = clone(recommendation);
+  delete result._pmWriterRankScore;
+  return result;
+}
+
+function bubbleRiskRawScore(trendScore) {
+  return componentNamed(trendScore, 'bubble-risk')?.rawScore ?? 0;
+}
+
+function makeAlertCandidates({ trendScore, recommendation, challenges }) {
+  const alerts = [];
+  if ((trendScore?.score ?? 0) >= ALERT_MOMENTUM_THRESHOLD) {
+    alerts.push({
+      alertId: safeCode(`alert-${trendScore.marketTrendId}-momentum`, 'alert'),
+      marketTrendId: trendScore.marketTrendId,
+      title: sanitizeAnalysisText(`${trendLabel(trendScore)} crossed the PM Writer momentum review threshold.`),
+      severity: 'warning',
+      trigger: {
+        metric: 'momentum-score',
+        operator: 'gte',
+        threshold: ALERT_MOMENTUM_THRESHOLD,
+        windowDays: 7,
+        rationale: 'PM review should run when a transparent Analyst score remains elevated in the current window.',
+      },
+      evidenceRefs: clone(recommendation.evidenceRefs),
+      skepticRefs: clone(recommendation.skepticRefs),
+      confidence: clone(recommendation.confidence),
+      safety: safetyMetadata(),
+    });
+  }
+
+  const rawBubbleRisk = bubbleRiskRawScore(trendScore);
+  if (rawBubbleRisk >= ALERT_BUBBLE_RISK_THRESHOLD || challenges.some((challenge) => challenge?.bubbleRisk?.level === 'high')) {
+    alerts.push({
+      alertId: safeCode(`alert-${trendScore.marketTrendId}-bubble-risk`, 'alert'),
+      marketTrendId: trendScore.marketTrendId,
+      title: sanitizeAnalysisText(`${trendLabel(trendScore)} needs risk review before PM action.`),
+      severity: 'warning',
+      trigger: {
+        metric: 'bubble-risk',
+        operator: 'gte',
+        threshold: ALERT_BUBBLE_RISK_THRESHOLD,
+        windowDays: 7,
+        rationale: 'A risk alert is useful when bubble-risk evidence or high Skeptic blockers are present.',
+      },
+      evidenceRefs: clone(recommendation.evidenceRefs),
+      skepticRefs: clone(recommendation.skepticRefs),
+      confidence: clone(recommendation.confidence),
+      safety: safetyMetadata(),
+    });
+  }
+  return alerts;
+}
+
+function sourceTraceCoverageFor(recommendations) {
+  const evidenceRefCount = recommendations.reduce((total, recommendation) => total + recommendation.evidenceRefs.length, 0);
+  const skepticRefCount = recommendations.reduce((total, recommendation) => total + recommendation.skepticRefs.length, 0);
+  const uncoveredRecommendationIds = recommendations
+    .filter((recommendation) => recommendation.evidenceRefs.length === 0 || recommendation.skepticRefs.length === 0)
+    .map((recommendation) => recommendation.recommendationId);
+  return {
+    evidenceRefCount,
+    skepticRefCount,
+    recommendationsWithEvidence: recommendations.filter((recommendation) => recommendation.evidenceRefs.length > 0).length,
+    recommendationsWithSkepticReview: recommendations.filter((recommendation) => recommendation.skepticRefs.length > 0).length,
+    uncoveredRecommendationIds,
+  };
+}
+
+function roleStageTraceFor({ input, runId, now, status, recommendations }) {
+  const artifacts = isPlainObject(input?.summary?.artifacts) ? input.summary.artifacts : {};
+  const stageStatuses = isPlainObject(input?.summary?.stageStatuses) ? input.summary.stageStatuses : {};
+  return {
+    runId,
+    role: PM_WRITER_ROLE,
+    stage: PM_WRITER_STAGE,
+    stageStatuses: {
+      collector: input?.collectorStatus ?? 'ok',
+      normalizer: input?.normalizerStatus ?? 'ok',
+      analyst: stageStatuses.analyst ?? input?.analystStatus ?? input?.summary?.status ?? 'ok',
+      skeptic: stageStatuses.skeptic ?? input?.skepticStatus ?? input?.status ?? 'ok',
+      pmWriter: status,
+    },
+    inputArtifacts: {
+      trendScores: artifacts.trendScores ?? analystTrendScoresPath(runId),
+      skepticChallenges: artifacts.skepticChallenges ?? artifacts.skepticChallengedClaims ?? skepticChallengesPath(runId),
+      analystSummary: artifacts.analystSummary ?? analystRunSummaryPath(runId),
+      skepticSummary: artifacts.skepticSummary ?? skepticRunSummaryPath(runId),
+    },
+    sourceTraceCoverage: sourceTraceCoverageFor(recommendations),
+    staleInputs: asArray(input?.staleInputs).filter(isPlainObject).map(clone),
+    generatedAt: now,
+  };
+}
+
+function safeDiagnosticDetails(details = {}) {
+  const result = {};
+  if (typeof details.outputType === 'string') result.outputType = details.outputType;
+  if (typeof details.recommendationType === 'string') result.recommendationType = details.recommendationType;
+  if (typeof details.alertMetric === 'string') result.alertMetric = details.alertMetric;
+  if (typeof details.alertOperator === 'string') result.alertOperator = details.alertOperator;
+  if (typeof details.templateId === 'string') result.templateId = details.templateId;
+  if (typeof details.reason === 'string' && details.reason.trim() !== '') result.reason = sanitizeAnalysisText(details.reason);
+  return result;
+}
+
+function diagnostic({ runId, recommendationId, alertId, marketTrendId, category, code, message, now, status = 'ok', severity = 'info', details = {} }) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    runId,
+    ...(typeof recommendationId === 'string' && recommendationId.trim() !== '' ? { recommendationId } : {}),
+    ...(typeof alertId === 'string' && alertId.trim() !== '' ? { alertId } : {}),
+    ...(typeof marketTrendId === 'string' && marketTrendId.trim() !== '' ? { marketTrendId } : {}),
+    role: PM_WRITER_ROLE,
+    stage: PM_WRITER_STAGE,
+    status,
+    severity,
+    category,
+    code: safeCode(code, category),
+    message: sanitizeAnalysisText(message),
+    emittedAt: now,
+    artifactPath: pmWriterDiagnosticsPath(runId),
+    redacted: false,
+    ...(Object.keys(safeDiagnosticDetails(details)).length > 0 ? { details: safeDiagnosticDetails(details) } : {}),
+  };
+}
+
+function diagnosticsForOutputs({ runId, now, recommendations, selectedRecommendation, sectorMemos, alertCandidates, roleStageTrace, hiddenRecommendations }) {
+  const diagnostics = [];
+  diagnostics.push(diagnostic({
+    runId,
+    recommendationId: selectedRecommendation.recommendationId,
+    marketTrendId: selectedRecommendation.marketTrendId,
+    category: 'stage-execution-status',
+    code: 'top-opportunity-selected',
+    message: 'PM Writer selected the top opportunity by Analyst score plus Skeptic-adjusted confidence.',
+    now,
+    details: {
+      outputType: 'opportunity-recommendations',
+      recommendationType: selectedRecommendation.recommendationType,
+      reason: `Rank score ${selectedRecommendation._pmWriterRankScore} selected for daily radar and sector memo.`,
+    },
+  }));
+
+  for (const recommendation of hiddenRecommendations) {
+    diagnostics.push(diagnostic({
+      runId,
+      recommendationId: recommendation.recommendationId,
+      marketTrendId: recommendation.marketTrendId,
+      category: 'stage-execution-status',
+      code: `${recommendation.marketTrendId}-not-sector-memo`,
+      message: 'PM Writer kept a non-top opportunity in radar but did not create a sector memo.',
+      now,
+      details: {
+        outputType: 'sector-memo',
+        recommendationType: recommendation.recommendationType,
+        reason: 'Only the top ranked opportunity receives a sector memo in this guided workflow.',
+      },
+    }));
+  }
+
+  for (const recommendation of recommendations) {
+    diagnostics.push(diagnostic({
+      runId,
+      recommendationId: recommendation.recommendationId,
+      marketTrendId: recommendation.marketTrendId,
+      category: 'evidence-coverage',
+      code: `${recommendation.marketTrendId}-evidence-covered`,
+      message: 'PM Writer recommendation includes normalized source evidence links.',
+      now,
+      status: recommendation.evidenceRefs.length > 0 ? 'ok' : 'warn',
+      severity: recommendation.evidenceRefs.length > 0 ? 'info' : 'warning',
+      details: {
+        outputType: 'opportunity-recommendations',
+        recommendationType: recommendation.recommendationType,
+        reason: `${recommendation.evidenceRefs.length} evidence references attached.`,
+      },
+    }));
+    diagnostics.push(diagnostic({
+      runId,
+      recommendationId: recommendation.recommendationId,
+      marketTrendId: recommendation.marketTrendId,
+      category: 'skeptic-trace-coverage',
+      code: `${recommendation.marketTrendId}-skeptic-trace-covered`,
+      message: 'PM Writer recommendation includes Skeptic challenge trace references.',
+      now,
+      status: recommendation.skepticRefs.length > 0 ? 'ok' : 'warn',
+      severity: recommendation.skepticRefs.length > 0 ? 'info' : 'warning',
+      details: {
+        outputType: 'opportunity-recommendations',
+        recommendationType: recommendation.recommendationType,
+        reason: `${recommendation.skepticRefs.length} Skeptic references attached.`,
+      },
+    }));
+    diagnostics.push(diagnostic({
+      runId,
+      recommendationId: recommendation.recommendationId,
+      marketTrendId: recommendation.marketTrendId,
+      category: 'safe-next-action',
+      code: `${recommendation.marketTrendId}-safe-next-actions`,
+      message: 'PM Writer emitted safe PM next actions only.',
+      now,
+      details: {
+        outputType: 'mvp-validation-experiments',
+        recommendationType: recommendation.recommendationType,
+        reason: `${recommendation.nextActions.length} safe actions and ${recommendation.mvpValidationExperiments.length} validation experiments generated.`,
+      },
+    }));
+  }
+
+  for (const alert of alertCandidates) {
+    diagnostics.push(diagnostic({
+      runId,
+      alertId: alert.alertId,
+      marketTrendId: alert.marketTrendId,
+      category: 'alert-trigger-validity',
+      code: `${alert.alertId}-trigger-valid`,
+      message: 'PM Writer alert candidate matched a supported trigger rule.',
+      now,
+      details: {
+        outputType: 'alert-candidates',
+        alertMetric: alert.trigger.metric,
+        alertOperator: alert.trigger.operator,
+        reason: `Trigger threshold ${alert.trigger.threshold} matched for ${alert.trigger.metric}.`,
+      },
+    }));
+  }
+
+  diagnostics.push(diagnostic({
+    runId,
+    category: 'source-trace-coverage',
+    code: 'source-trace-coverage-summarized',
+    message: 'PM Writer summarized source trace coverage for downstream guided workflow agents.',
+    now,
+    status: roleStageTrace.sourceTraceCoverage.uncoveredRecommendationIds.length === 0 ? 'ok' : 'warn',
+    severity: roleStageTrace.sourceTraceCoverage.uncoveredRecommendationIds.length === 0 ? 'info' : 'warning',
+    details: {
+      outputType: 'daily-radar',
+      reason: `${roleStageTrace.sourceTraceCoverage.evidenceRefCount} evidence refs and ${roleStageTrace.sourceTraceCoverage.skepticRefCount} Skeptic refs are traceable.`,
+    },
+  }));
+  diagnostics.push(diagnostic({
+    runId,
+    category: 'stale-prior-stage',
+    code: roleStageTrace.staleInputs.length > 0 ? 'stale-prior-stage-detected' : 'prior-stage-freshness-checked',
+    message: roleStageTrace.staleInputs.length > 0
+      ? 'PM Writer detected stale prior-stage inputs before rendering outputs.'
+      : 'PM Writer checked prior-stage freshness before rendering outputs.',
+    now,
+    status: roleStageTrace.staleInputs.length > 0 ? 'warn' : 'ok',
+    severity: roleStageTrace.staleInputs.length > 0 ? 'warning' : 'info',
+    details: {
+      outputType: 'daily-radar',
+      reason: `${roleStageTrace.staleInputs.length} stale prior-stage inputs recorded.`,
+    },
+  }));
+  diagnostics.push(diagnostic({
+    runId,
+    category: 'template-validation',
+    code: 'sector-memo-template-valid',
+    message: 'PM Writer sector memo template rendered with required sections.',
+    now,
+    status: sectorMemos.length > 0 ? 'ok' : 'warn',
+    severity: sectorMemos.length > 0 ? 'info' : 'warning',
+    details: {
+      outputType: 'sector-memo',
+      templateId: 'sector-memo-v1',
+      reason: `${sectorMemos.length} sector memo templates validated.`,
+    },
+  }));
+  diagnostics.push(diagnostic({
+    runId,
+    category: 'artifact-validation',
+    code: 'json-and-markdown-rendered',
+    message: 'PM Writer rendered machine-readable JSON artifacts and deterministic Markdown views.',
+    now,
+    details: {
+      outputType: 'daily-radar',
+      reason: 'Daily radar JSON, sector memo JSON, and Markdown renderers completed.',
+    },
+  }));
+  diagnostics.push(diagnostic({
+    runId,
+    category: 'unsupported-recommendation-field',
+    code: 'unsupported-fields-filtered',
+    message: 'PM Writer emitted only schema-supported recommendation fields.',
+    now,
+    details: {
+      outputType: 'opportunity-recommendations',
+      reason: 'Internal rank metadata is removed before JSON promotion.',
+    },
+  }));
+
+  return diagnostics;
+}
+
+function makeDailyRadar({ runId, now, recommendations, alertCandidates, experiments, roleStageTrace }) {
+  const strongCount = recommendations.filter((recommendation) => recommendation.recommendationType === 'opportunity-hypothesis').length;
+  const watchCount = recommendations.filter((recommendation) => recommendation.recommendationType === 'watchlist').length;
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    radarId: safeCode(`radar-${runId}`, 'daily-radar'),
+    runId,
+    role: PM_WRITER_ROLE,
+    stage: PM_WRITER_STAGE,
+    title: 'Daily PM opportunity radar.',
+    summary: sanitizeAnalysisText(`${strongCount} strong opportunity and ${watchCount} watchlist opportunity are ready for guided PM review.`),
+    recommendations: recommendations.map(publicRecommendation),
+    alertCandidates: clone(alertCandidates),
+    mvpValidationExperiments: clone(experiments),
+    roleStageTrace,
+    safety: safetyMetadata(),
+    artifactPath: pmWriterDailyRadarPath(runId),
+    generatedAt: now,
+  };
+}
+
+function makeSectorMemo({ runId, now, recommendation, roleStageTrace }) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    memoId: safeCode(`memo-${recommendation.marketTrendId}`, 'sector-memo'),
+    runId,
+    role: PM_WRITER_ROLE,
+    stage: PM_WRITER_STAGE,
+    marketTrendId: recommendation.marketTrendId,
+    sectorName: sanitizeAnalysisText(trendLabel({ marketTrendId: recommendation.marketTrendId })),
+    executiveSummary: sanitizeAnalysisText(`${trendLabel({ marketTrendId: recommendation.marketTrendId })} is the top ranked PM Writer opportunity after Skeptic review.`),
+    recommendations: [publicRecommendation(recommendation)],
+    evidenceRefs: clone(recommendation.evidenceRefs),
+    skepticRefs: clone(recommendation.skepticRefs),
+    confidence: clone(recommendation.confidence),
+    risk: clone(recommendation.risk),
+    mvpValidationExperiments: clone(recommendation.mvpValidationExperiments),
+    template: {
+      templateId: 'sector-memo-v1',
+      templateVersion: 'v1',
+      validated: true,
+    },
+    roleStageTrace,
+    safety: safetyMetadata(),
+    artifactPath: pmWriterSectorMemoPath(runId, recommendation.marketTrendId),
+    generatedAt: now,
+  };
+}
+
+function markdownList(values) {
+  return values.length > 0 ? values.map((value) => `- ${value}`).join('\n') : '- None recorded.';
+}
+
+export function renderDailyRadarMarkdown(dailyRadar) {
+  const recommendationLines = dailyRadar.recommendations.map((recommendation, index) => {
+    const evidenceIds = recommendation.evidenceRefs.map((ref) => ref.signalId).join(', ');
+    const skepticIds = recommendation.skepticRefs.map((ref) => ref.challengeId).join(', ');
+    return `${index + 1}. **${recommendation.title}** (${recommendation.recommendationType}) — confidence ${recommendation.confidence.score}; evidence: ${evidenceIds}; skeptic review: ${skepticIds}`;
+  });
+  const alertLines = dailyRadar.alertCandidates.map((alert) => `${alert.alertId}: ${alert.trigger.metric} ${alert.trigger.operator} ${alert.trigger.threshold}`);
+  return [
+    `# ${dailyRadar.title}`,
+    '',
+    `Generated: ${dailyRadar.generatedAt}`,
+    '',
+    '## Summary',
+    dailyRadar.summary,
+    '',
+    '## Recommendations',
+    recommendationLines.length > 0 ? recommendationLines.join('\n') : '- None recorded.',
+    '',
+    '## Alert Candidates',
+    markdownList(alertLines),
+    '',
+    '## Source Trace Coverage',
+    `Evidence refs: ${dailyRadar.roleStageTrace.sourceTraceCoverage.evidenceRefCount}; Skeptic refs: ${dailyRadar.roleStageTrace.sourceTraceCoverage.skepticRefCount}.`,
+    '',
+    dailyRadar.safety.disclaimer,
+  ].join('\n');
+}
+
+export function renderSectorMemoMarkdown(sectorMemo) {
+  const recommendation = sectorMemo.recommendations[0];
+  const evidenceLines = sectorMemo.evidenceRefs.map((ref) => `${ref.signalId} (${ref.signalType}) -> ${ref.signalPath}`);
+  const skepticLines = sectorMemo.skepticRefs.map((ref) => `${ref.challengeId}: ${ref.challengeType} — ${ref.challengedClaim}`);
+  const experimentLines = sectorMemo.mvpValidationExperiments.map((experiment) => `${experiment.experimentId}: ${experiment.method} Success: ${experiment.successThreshold}`);
+  const actionLines = recommendation.nextActions.map((action) => `${action.actionId}: ${action.label}`);
+  return [
+    `# Sector Memo: ${sectorMemo.sectorName}`,
+    '',
+    '## Executive Summary',
+    sectorMemo.executiveSummary,
+    '',
+    '## Recommendation',
+    `${recommendation.title} (${recommendation.recommendationType})`,
+    '',
+    '## Evidence Trace',
+    markdownList(evidenceLines),
+    '',
+    '## Skeptic Review',
+    markdownList(skepticLines),
+    '',
+    '## MVP Validation',
+    markdownList(experimentLines),
+    '',
+    '## Safe Next Actions',
+    markdownList(actionLines),
+    '',
+    sectorMemo.safety.disclaimer,
+  ].join('\n');
+}
+
+function analystSummaryPathFor(input, runId) {
+  return isPlainObject(input?.summary?.artifacts) && typeof input.summary.artifacts.analystSummary === 'string'
+    ? input.summary.artifacts.analystSummary
+    : analystRunSummaryPath(runId);
+}
+
+function analystDiagnosticsPathFor(input, runId) {
+  return isPlainObject(input?.summary?.artifacts) && typeof input.summary.artifacts.analystDiagnostics === 'string'
+    ? input.summary.artifacts.analystDiagnostics
+    : analystDiagnosticsPath(runId);
+}
+
+function skepticSummaryPathFor(input, runId) {
+  return isPlainObject(input?.summary?.artifacts) && typeof input.summary.artifacts.skepticSummary === 'string'
+    ? input.summary.artifacts.skepticSummary
+    : skepticRunSummaryPath(runId);
+}
+
+function skepticDiagnosticsPathFor(input, runId) {
+  return isPlainObject(input?.summary?.artifacts) && typeof input.summary.artifacts.skepticDiagnostics === 'string'
+    ? input.summary.artifacts.skepticDiagnostics
+    : skepticDiagnosticsPath(runId);
+}
+
+export function writePmWriterOutputs(input = {}, options = {}) {
+  const trendScores = collectTrendScores(input).map(clone);
+  const skepticChallenges = collectSkepticChallenges(input).map(clone);
+  const runId = runIdFor(input, trendScores, options);
+  const now = normalizeTimestamp(options.now ?? input?.now, DEFAULT_NOW);
+  const groupedChallenges = challengesByTrend(skepticChallenges);
+
+  const recommendations = trendScores
+    .map((trendScore) => makeRecommendation({
+      runId,
+      trendScore,
+      challenges: groupedChallenges.get(trendScore.marketTrendId) ?? [],
+    }))
+    .filter((recommendation) => recommendation.evidenceRefs.length > 0 && recommendation.skepticRefs.length > 0)
+    .sort((a, b) => b._pmWriterRankScore - a._pmWriterRankScore || a.marketTrendId.localeCompare(b.marketTrendId));
+
+  if (recommendations.length === 0) {
+    throw new Error('PM Writer requires at least one trend with evidence refs and Skeptic trace refs.');
+  }
+
+  const selectedRecommendation = recommendations[0];
+  const hiddenRecommendations = recommendations.slice(1);
+  const alertCandidates = recommendations.flatMap((recommendation) => {
+    const trendScore = trendScores.find((candidate) => candidate.marketTrendId === recommendation.marketTrendId);
+    return makeAlertCandidates({
+      trendScore,
+      recommendation,
+      challenges: groupedChallenges.get(recommendation.marketTrendId) ?? [],
+    });
+  });
+  const experiments = recommendations.flatMap((recommendation) => recommendation.mvpValidationExperiments).map(clone);
+  const roleStageTrace = roleStageTraceFor({ input, runId, now, status: 'ok', recommendations });
+  const sectorMemos = [makeSectorMemo({ runId, now, recommendation: selectedRecommendation, roleStageTrace })];
+  const dailyRadar = makeDailyRadar({ runId, now, recommendations, alertCandidates, experiments, roleStageTrace });
+  const diagnostics = diagnosticsForOutputs({
+    runId,
+    now,
+    recommendations,
+    selectedRecommendation,
+    sectorMemos,
+    alertCandidates,
+    roleStageTrace,
+    hiddenRecommendations,
+  });
+  const status = diagnostics.some((entry) => entry.status === 'warn' || entry.severity === 'warning') ? 'warn' : 'ok';
+  dailyRadar.roleStageTrace.stageStatuses.pmWriter = status;
+  for (const memo of sectorMemos) memo.roleStageTrace.stageStatuses.pmWriter = status;
+
+  const diagnosticsArtifact = {
+    schemaVersion: SCHEMA_VERSION,
+    runId,
+    role: PM_WRITER_ROLE,
+    stage: PM_WRITER_STAGE,
+    generatedAt: now,
+    artifactPath: pmWriterDiagnosticsPath(runId),
+    diagnostics,
+  };
+
+  const read = uniqueSorted([
+    analystSummaryPathFor(input, runId),
+    analystDiagnosticsPathFor(input, runId),
+    analystTrendScoresPath(runId),
+    skepticSummaryPathFor(input, runId),
+    skepticDiagnosticsPathFor(input, runId),
+    isPlainObject(input?.summary?.artifacts) && typeof input.summary.artifacts.skepticChallenges === 'string'
+      ? input.summary.artifacts.skepticChallenges
+      : skepticChallengesPath(runId),
+    ...trendScores.map((trendScore) => trendScore.artifactPath ?? analystTrendScorePath(runId, trendScore.marketTrendId)),
+    ...skepticChallenges.map((challenge) => challenge.artifactPath).filter(Boolean),
+  ]);
+  const written = uniqueSorted([
+    pmWriterRunSummaryPath(runId),
+    pmWriterDiagnosticsPath(runId),
+    pmWriterDailyRadarPath(runId),
+    pmWriterRecommendationsPath(runId),
+    pmWriterAlertCandidatesPath(runId),
+    pmWriterMvpExperimentsPath(runId),
+    ...sectorMemos.map((memo) => memo.artifactPath),
+  ]);
+
+  const summary = {
+    schemaVersion: SCHEMA_VERSION,
+    runId,
+    role: PM_WRITER_ROLE,
+    stage: PM_WRITER_STAGE,
+    status,
+    startedAt: now,
+    completedAt: now,
+    counts: {
+      recommendationsWritten: recommendations.length,
+      sectorMemosWritten: sectorMemos.length,
+      alertsCandidateCount: alertCandidates.length,
+      experimentsWritten: experiments.length,
+      evidenceRefs: roleStageTrace.sourceTraceCoverage.evidenceRefCount,
+      skepticRefs: roleStageTrace.sourceTraceCoverage.skepticRefCount,
+      templateValidationFailures: diagnostics.filter((entry) => entry.category === 'template-validation' && entry.status !== 'ok').length,
+    },
+    artifacts: {
+      analystSummary: analystSummaryPathFor(input, runId),
+      analystDiagnostics: analystDiagnosticsPathFor(input, runId),
+      skepticSummary: skepticSummaryPathFor(input, runId),
+      skepticDiagnostics: skepticDiagnosticsPathFor(input, runId),
+      summary: pmWriterRunSummaryPath(runId),
+      diagnostics: pmWriterDiagnosticsPath(runId),
+      dailyRadar: pmWriterDailyRadarPath(runId),
+      recommendations: pmWriterRecommendationsPath(runId),
+      alertCandidates: pmWriterAlertCandidatesPath(runId),
+      mvpExperiments: pmWriterMvpExperimentsPath(runId),
+      sectorMemos: sectorMemos.map((memo) => memo.artifactPath),
+      read,
+      written,
+    },
+    diagnostics,
+    safety: safetyMetadata(),
+  };
+
+  const recommendationsArtifact = {
+    schemaVersion: SCHEMA_VERSION,
+    runId,
+    role: PM_WRITER_ROLE,
+    stage: PM_WRITER_STAGE,
+    generatedAt: now,
+    artifactPath: pmWriterRecommendationsPath(runId),
+    recommendations: dailyRadar.recommendations,
+  };
+  const alertCandidatesArtifact = {
+    schemaVersion: SCHEMA_VERSION,
+    runId,
+    role: PM_WRITER_ROLE,
+    stage: PM_WRITER_STAGE,
+    generatedAt: now,
+    artifactPath: pmWriterAlertCandidatesPath(runId),
+    alertCandidates,
+  };
+  const mvpExperimentsArtifact = {
+    schemaVersion: SCHEMA_VERSION,
+    runId,
+    role: PM_WRITER_ROLE,
+    stage: PM_WRITER_STAGE,
+    generatedAt: now,
+    artifactPath: pmWriterMvpExperimentsPath(runId),
+    mvpValidationExperiments: experiments,
+  };
+
+  const markdown = {
+    dailyRadar: renderDailyRadarMarkdown(dailyRadar),
+    sectorMemos: new Map(sectorMemos.map((memo) => [memo.marketTrendId, renderSectorMemoMarkdown(memo)])),
+  };
+
+  const files = new Map();
+  files.set(summary.artifacts.summary, summary);
+  files.set(diagnosticsArtifact.artifactPath, diagnosticsArtifact);
+  files.set(dailyRadar.artifactPath, dailyRadar);
+  files.set(recommendationsArtifact.artifactPath, recommendationsArtifact);
+  files.set(alertCandidatesArtifact.artifactPath, alertCandidatesArtifact);
+  files.set(mvpExperimentsArtifact.artifactPath, mvpExperimentsArtifact);
+  for (const memo of sectorMemos) files.set(memo.artifactPath, memo);
+
+  return {
+    runId,
+    role: PM_WRITER_ROLE,
+    stage: PM_WRITER_STAGE,
+    status,
+    recommendations: dailyRadar.recommendations,
+    alertCandidates,
+    mvpValidationExperiments: experiments,
+    dailyRadar,
+    sectorMemos,
+    diagnostics,
+    diagnosticsArtifact,
+    recommendationsArtifact,
+    alertCandidatesArtifact,
+    mvpExperimentsArtifact,
+    summary,
+    files,
+    markdown,
+    safety: safetyMetadata(),
+  };
+}
+
+export const generatePmWriterOutputs = writePmWriterOutputs;
+export const renderPmWriterOutputs = writePmWriterOutputs;
+export const runPmWriter = writePmWriterOutputs;