@openprd/cli 0.1.9 → 0.1.10

package/src/workspace-core.js

@@ -20,6 +20,28 @@ const CORE_TEMPLATE_FILES = [
   'README.md',
   'README_EN.md',
   'config.yaml',
+  'design/README.md',
+  'design/README_EN.md',
+  'design/anti-slop.md',
+  'design/lenses/frontend-lenses.md',
+  'design/themes/theme-catalog.json',
+  'design/layouts/layout-catalog.json',
+  'design/components/component-catalog.md',
+  'design/recipes/product-launch.md',
+  'design/recipes/content-experience.md',
+  'design/recipes/operational-tool.md',
+  'design/checklists/ui-quality-gate.md',
+  'design/assets/surface-presets.md',
+  'design/templates/README.md',
+  'design/templates/README_EN.md',
+  'design/templates/content-home.html',
+  'design/templates/product-launch.html',
+  'design/templates/ops-dashboard.html',
+  'design/active/facts-sheet.md',
+  'design/active/asset-spec.md',
+  'design/active/image-preflight.md',
+  'design/active/direction-plan.md',
+  'design/active/selected-direction.md',
   'schema/prd.schema.yaml',
   'schema/diagram-architecture.schema.yaml',
   'schema/diagram-product-flow.schema.yaml',
@@ -60,6 +82,28 @@ const CORE_TEMPLATE_FILES = [
 const WORKSPACE_SEED_REFRESH_FILES = [
   'README.md',
   'README_EN.md',
+  'design/README.md',
+  'design/README_EN.md',
+  'design/anti-slop.md',
+  'design/lenses/frontend-lenses.md',
+  'design/themes/theme-catalog.json',
+  'design/layouts/layout-catalog.json',
+  'design/components/component-catalog.md',
+  'design/recipes/product-launch.md',
+  'design/recipes/content-experience.md',
+  'design/recipes/operational-tool.md',
+  'design/checklists/ui-quality-gate.md',
+  'design/assets/surface-presets.md',
+  'design/templates/README.md',
+  'design/templates/README_EN.md',
+  'design/templates/content-home.html',
+  'design/templates/product-launch.html',
+  'design/templates/ops-dashboard.html',
+  'design/active/facts-sheet.md',
+  'design/active/asset-spec.md',
+  'design/active/image-preflight.md',
+  'design/active/direction-plan.md',
+  'design/active/selected-direction.md',
   'schema/prd.schema.yaml',
   'schema/diagram-architecture.schema.yaml',
   'schema/diagram-product-flow.schema.yaml',
@@ -87,6 +131,9 @@ const WORKSPACE_SEED_REFRESH_FILES = [
 ];
 const WORKSPACE_SEED_COPY_IGNORE = new Set([
   'artifacts',
+  'benchmarks/.DS_Store',
+  'benchmarks/evidence',
+  'benchmarks/inbox',
   'discovery',
   'growth',
   'harness',
@@ -99,6 +146,8 @@ const WORKSPACE_SEED_COPY_IGNORE = new Set([
   'engagements/active/architecture-diagram.html',
   'engagements/active/architecture-diagram.json',
   'engagements/active/architecture-diagram.mmd',
+  'engagements/active/brainstorm.html',
+  'engagements/active/brainstorm.json',
   'engagements/active/decision-log.md',
   'engagements/active/product-flow-diagram.html',
   'engagements/active/product-flow-diagram.json',
@@ -326,6 +375,7 @@ function buildWorkflowTaskGraph(snapshot = null, analysis = null, options = {})
   const isSynthesized = Boolean(snapshot?.digest || prdVersion > 0);
   const isFrozen = snapshot?.status === 'frozen';
   const isHandedOff = snapshot?.status === 'handed_off';
+  const brainstormDone = Boolean(snapshot?.brainstormMeta?.generatedAt || snapshot?.brainstormMeta?.artifactId);
   const isInterviewComplete = Boolean(
     snapshot?.sections?.problem?.problemStatement
     && snapshot?.sections?.users?.primaryUsers?.length
@@ -347,6 +397,13 @@ function buildWorkflowTaskGraph(snapshot = null, analysis = null, options = {})
   const clarifyGateActive = Boolean(clarificationState?.shouldAskUser);
 
   const workflow = [
+    {
+      id: 'brainstorm',
+      label: 'brainstorm',
+      kind: 'workflow-step',
+      status: brainstormDone ? 'done' : 'ready',
+      dependsOn: [],
+    },
     {
       id: 'clarify',
       label: 'clarify',
@@ -435,6 +492,13 @@ function buildWorkflowTaskGraph(snapshot = null, analysis = null, options = {})
       status: 'ready',
       dependsOn: [],
     },
+    {
+      id: 'brainstorm-file',
+      label: 'brainstorm.html',
+      kind: 'artifact',
+      status: brainstormDone ? 'done' : 'ready',
+      dependsOn: ['brainstorm'],
+    },
     {
       id: 'open-questions',
       label: 'open-questions.md',
@@ -560,6 +624,7 @@ function buildWorkflowTaskGraph(snapshot = null, analysis = null, options = {})
       })),
     ],
     edges: [
+      { from: 'brainstorm', to: 'brainstorm-file', relation: 'produces' },
       { from: 'clarify', to: 'classify', relation: 'unblocks' },
       { from: 'classify', to: 'interview', relation: 'enables' },
       { from: 'interview', to: 'synthesize', relation: 'enables' },
@@ -667,6 +732,15 @@ async function ensureWorkspaceSkeleton(projectRoot, options = {}) {
   await fs.mkdir(cjoin(workspaceRoot, 'artifacts', 'archive'), { recursive: true });
   await fs.mkdir(cjoin(workspaceRoot, 'learning', 'archive'), { recursive: true });
   await fs.mkdir(cjoin(workspaceRoot, 'quality', 'reports'), { recursive: true });
+  await fs.mkdir(cjoin(workspaceRoot, 'design', 'lenses'), { recursive: true });
+  await fs.mkdir(cjoin(workspaceRoot, 'design', 'themes'), { recursive: true });
+  await fs.mkdir(cjoin(workspaceRoot, 'design', 'layouts'), { recursive: true });
+  await fs.mkdir(cjoin(workspaceRoot, 'design', 'components'), { recursive: true });
+  await fs.mkdir(cjoin(workspaceRoot, 'design', 'recipes'), { recursive: true });
+  await fs.mkdir(cjoin(workspaceRoot, 'design', 'checklists'), { recursive: true });
+  await fs.mkdir(cjoin(workspaceRoot, 'design', 'assets'), { recursive: true });
+  await fs.mkdir(cjoin(workspaceRoot, 'design', 'templates'), { recursive: true });
+  await fs.mkdir(cjoin(workspaceRoot, 'design', 'active'), { recursive: true });
   await fs.mkdir(cjoin(workspaceRoot, 'growth'), { recursive: true });
   await fs.mkdir(cjoin(workspaceRoot, 'knowledge', 'incidents'), { recursive: true });
   await fs.mkdir(cjoin(workspaceRoot, 'knowledge', 'patterns'), { recursive: true });
@@ -735,6 +809,17 @@ async function migrateWorkspaceConfig(projectRoot, changes) {
       ...(seed.quality ?? {}),
       ...(current.quality ?? {}),
     },
+    design: {
+      ...(seed.design ?? {}),
+      ...(current.design ?? {}),
+      enabled: current.design?.enabled ?? seed.design?.enabled ?? true,
+      frameworkRoot: current.design?.frameworkRoot ?? seed.design?.frameworkRoot ?? '.openprd/design',
+      templateRoot: current.design?.templateRoot ?? seed.design?.templateRoot ?? '.openprd/design/templates',
+      activeArtifacts: {
+        ...(seed.design?.activeArtifacts ?? {}),
+        ...(current.design?.activeArtifacts ?? {}),
+      },
+    },
     supportedProductTypes: seed.supportedProductTypes,
     templateInheritance: seed.templateInheritance,
     workflow: seed.workflow,
@@ -918,6 +1003,15 @@ async function migrateWorkspaceSkeleton(projectRoot, options = {}) {
   await fs.mkdir(cjoin(workspaceRoot, 'artifacts', 'archive'), { recursive: true });
   await fs.mkdir(cjoin(workspaceRoot, 'learning', 'archive'), { recursive: true });
   await fs.mkdir(cjoin(workspaceRoot, 'quality', 'reports'), { recursive: true });
+  await fs.mkdir(cjoin(workspaceRoot, 'design', 'lenses'), { recursive: true });
+  await fs.mkdir(cjoin(workspaceRoot, 'design', 'themes'), { recursive: true });
+  await fs.mkdir(cjoin(workspaceRoot, 'design', 'layouts'), { recursive: true });
+  await fs.mkdir(cjoin(workspaceRoot, 'design', 'components'), { recursive: true });
+  await fs.mkdir(cjoin(workspaceRoot, 'design', 'recipes'), { recursive: true });
+  await fs.mkdir(cjoin(workspaceRoot, 'design', 'checklists'), { recursive: true });
+  await fs.mkdir(cjoin(workspaceRoot, 'design', 'assets'), { recursive: true });
+  await fs.mkdir(cjoin(workspaceRoot, 'design', 'templates'), { recursive: true });
+  await fs.mkdir(cjoin(workspaceRoot, 'design', 'active'), { recursive: true });
   await fs.mkdir(cjoin(workspaceRoot, 'growth'), { recursive: true });
   await fs.mkdir(cjoin(workspaceRoot, 'knowledge', 'incidents'), { recursive: true });
   await fs.mkdir(cjoin(workspaceRoot, 'knowledge', 'patterns'), { recursive: true });
@@ -1020,6 +1114,8 @@ async function loadWorkspace(projectRoot, options = {}) {
     activeFlows: cjoin(workspaceRoot, 'engagements', 'active', 'flows.md'),
     activeRoles: cjoin(workspaceRoot, 'engagements', 'active', 'roles.md'),
     activeHandoff: cjoin(workspaceRoot, 'engagements', 'active', 'handoff.md'),
+    activeBrainstormHtml: cjoin(workspaceRoot, 'engagements', 'active', 'brainstorm.html'),
+    activeBrainstormState: cjoin(workspaceRoot, 'engagements', 'active', 'brainstorm.json'),
     activeReviewHtml: cjoin(workspaceRoot, 'engagements', 'active', 'review.html'),
     reviewsDir: cjoin(workspaceRoot, 'reviews'),
     artifactsActiveDir: cjoin(workspaceRoot, 'artifacts', 'active'),
@@ -1033,6 +1129,24 @@ async function loadWorkspace(projectRoot, options = {}) {
     qualityReportsDir: cjoin(workspaceRoot, 'quality', 'reports'),
     qualityReportIndex: cjoin(workspaceRoot, 'quality', 'reports', 'index.json'),
     qualityReportLatest: cjoin(workspaceRoot, 'quality', 'reports', 'latest.json'),
+    designRoot: cjoin(workspaceRoot, 'design'),
+    designReadme: cjoin(workspaceRoot, 'design', 'README.md'),
+    designLenses: cjoin(workspaceRoot, 'design', 'lenses', 'frontend-lenses.md'),
+    designThemes: cjoin(workspaceRoot, 'design', 'themes', 'theme-catalog.json'),
+    designLayouts: cjoin(workspaceRoot, 'design', 'layouts', 'layout-catalog.json'),
+    designComponents: cjoin(workspaceRoot, 'design', 'components', 'component-catalog.md'),
+    designChecklist: cjoin(workspaceRoot, 'design', 'checklists', 'ui-quality-gate.md'),
+    designAntiSlop: cjoin(workspaceRoot, 'design', 'anti-slop.md'),
+    designTemplatesRoot: cjoin(workspaceRoot, 'design', 'templates'),
+    designTemplatesReadme: cjoin(workspaceRoot, 'design', 'templates', 'README.md'),
+    designContentHomeTemplate: cjoin(workspaceRoot, 'design', 'templates', 'content-home.html'),
+    designProductLaunchTemplate: cjoin(workspaceRoot, 'design', 'templates', 'product-launch.html'),
+    designOpsDashboardTemplate: cjoin(workspaceRoot, 'design', 'templates', 'ops-dashboard.html'),
+    designFactsSheet: cjoin(workspaceRoot, 'design', 'active', 'facts-sheet.md'),
+    designAssetSpec: cjoin(workspaceRoot, 'design', 'active', 'asset-spec.md'),
+    designImagePreflight: cjoin(workspaceRoot, 'design', 'active', 'image-preflight.md'),
+    designDirectionPlan: cjoin(workspaceRoot, 'design', 'active', 'direction-plan.md'),
+    designSelectedDirection: cjoin(workspaceRoot, 'design', 'active', 'selected-direction.md'),
     growthDir: cjoin(workspaceRoot, 'growth'),
     growthCandidates: cjoin(workspaceRoot, 'growth', 'candidates.jsonl'),
     growthAccepted: cjoin(workspaceRoot, 'growth', 'accepted.json'),
@@ -1122,6 +1236,13 @@ const USER_CLARIFICATION_PATHS = new Set([
   'problem.problemStatement',
   'problem.whyNow',
   'users.primaryUsers',
+  'validation.community',
+  'validation.seedUsers',
+  'validation.currentAlternative',
+  'validation.manualPath',
+  'validation.commitmentSignals',
+  'validation.firstValidationStep',
+  'validation.defaultAlivePlan',
   'goals.goals',
   'goals.successMetrics',
   'scope.inScope',
@@ -1162,6 +1283,13 @@ const FIELD_PATH_TO_STATE_KEY = {
   'users.primaryUsers': 'primaryUsers',
   'users.secondaryUsers': 'secondaryUsers',
   'users.stakeholders': 'stakeholders',
+  'validation.community': 'community',
+  'validation.seedUsers': 'seedUsers',
+  'validation.currentAlternative': 'currentAlternative',
+  'validation.manualPath': 'manualPath',
+  'validation.commitmentSignals': 'commitmentSignals',
+  'validation.firstValidationStep': 'firstValidationStep',
+  'validation.defaultAlivePlan': 'defaultAlivePlan',
   'goals.goals': 'goals',
   'goals.successMetrics': 'successMetrics',
   'goals.acceptanceGoals': 'acceptanceGoals',
@@ -1598,6 +1726,11 @@ function coerceCapturedValue(pathString, rawValue, append = false) {
     'users.primaryUsers',
     'users.secondaryUsers',
     'users.stakeholders',
+    'validation.community',
+    'validation.seedUsers',
+    'validation.manualPath',
+    'validation.commitmentSignals',
+    'validation.defaultAlivePlan',
     'goals.goals',
     'goals.successMetrics',
     'goals.acceptanceGoals',
@@ -1867,8 +2000,11 @@ function buildClarificationPlan(snapshot, analysis) {
   const mustAsk = analysis.missingFields.filter((field) => USER_CLARIFICATION_PATHS.has(field.path));
   const derived = analysis.missingFields.filter((field) => !USER_CLARIFICATION_PATHS.has(field.path));
   const kickoffQuestions = [
+    { id: 'problem.problemStatement', label: '核心问题', prompt: '我们要解决什么问题？' },
     { id: 'project-overview', label: '项目轮廓', prompt: '这件事主要是给谁用的，他们会在什么场景下最先感受到价值？' },
+    { id: 'current-alternative', label: '当前替代', prompt: '他们现在主要靠什么办法、流程或替代品在解决这个问题？' },
     { id: 'first-slice', label: '首版切片', prompt: '如果先做第一版，最值得先让用户完成什么关键动作？' },
+    { id: 'validation-loop', label: '验证闭环', prompt: '如果先不做完整产品，最容易先找谁验证、先怎么手工交付、什么真实承诺最能证明值得继续？' },
     { id: 'guardrails', label: '保护项', prompt: '这轮明确先不做什么，或者哪些既有体验、流程和业务结果不能被影响？' },
   ];
   return {
@@ -2003,6 +2139,7 @@ export {
   coerceCapturedValue,
   computeWorkspaceDigest,
   CORE_TEMPLATE_FILES,
+  USER_CLARIFICATION_PATHS,
   deriveGateLabels,
   detectWorkspaceScenario,
   ensureWorkspaceSkeleton,

package/src/workspace-workflow.js

@@ -11,12 +11,16 @@ import { assertReviewPresentationReady, getReviewPresentationGate } from './revi
 import { syncSessionBindingFromReview, syncSessionBindingFromSnapshot } from './session-binding.js';
 import { timestamp } from './time.js';
 import { generateWorkUnitId, normalizeWorkUnitId, readWorkUnitBinding, resolveTargetRoot, writeWorkUnitBinding } from './work-unit.js';
-import { appendDecision, appendOpenQuestions, appendProgress, appendWorkflowEvent, buildClarificationPlan, buildClarificationState, buildCurrentStateSnapshot, buildWorkflowTaskGraph, CAPTURE_SOURCES, coerceCapturedValue, deriveGateLabels, detectWorkspaceScenario, extractMarkdownSection, FIELD_PATH_TO_STATE_KEY, isSupportedProductType, loadCurrentLaneSnapshot, loadLatestVersionSnapshot, loadWorkspace, normalizeVersionId, persistWorkspaceCurrentState, readActiveRequirementLane, readVersionIndex, readVersionSnapshot, renderFlowDoc, renderHandoffDoc, renderRolesDoc, resolveActiveTemplatePack, resolveCurrentProductType, validateWorkspace, writeVersionIndex, writeVersionSnapshot } from './workspace-core.js';
+import { appendDecision, appendOpenQuestions, appendProgress, appendWorkflowEvent, buildClarificationPlan, buildClarificationState, buildCurrentStateSnapshot, buildWorkflowTaskGraph, CAPTURE_SOURCES, coerceCapturedValue, deriveGateLabels, detectWorkspaceScenario, extractMarkdownSection, FIELD_PATH_TO_STATE_KEY, isSupportedProductType, loadCurrentLaneSnapshot, loadLatestVersionSnapshot, loadWorkspace, normalizeVersionId, persistWorkspaceCurrentState, readActiveRequirementLane, readVersionIndex, readVersionSnapshot, renderFlowDoc, renderHandoffDoc, renderRolesDoc, resolveActiveTemplatePack, resolveCurrentProductType, USER_CLARIFICATION_PATHS, validateWorkspace, writeVersionIndex, writeVersionSnapshot } from './workspace-core.js';
 
 function requirementGatePath(projectRoot) {
   return path.join(projectRoot, '.openprd', 'harness', 'requirement-gate.json');
 }
 
+function normalizedText(value) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim();
+}
+
 const PRD_REVIEW_STATUSES = ['pending-confirmation', 'confirmed', 'needs-revision'];
 const CURRENT_SNAPSHOT_CACHE_KEYS = [
   'versionId',
@@ -30,6 +34,7 @@ const CURRENT_SNAPSHOT_CACHE_KEYS = [
 const REVIEW_PRESENTATION_RELEVANT_FIELD_PREFIXES = [
   'problem.',
   'users.',
+  'validation.',
   'goals.',
   'scope.',
   'scenarios.',
@@ -56,6 +61,13 @@ const REVIEW_PRESENTATION_RELEVANT_OVERRIDE_KEYS = new Set([
   'primaryUsers',
   'secondaryUsers',
   'stakeholders',
+  'community',
+  'seedUsers',
+  'currentAlternative',
+  'manualPath',
+  'commitmentSignals',
+  'firstValidationStep',
+  'defaultAlivePlan',
   'goals',
   'successMetrics',
   'acceptanceGoals',
@@ -109,6 +121,13 @@ const SYNTHESIZE_CONTENT_OVERRIDE_KEYS = new Set([
   'primaryUsers',
   'secondaryUsers',
   'stakeholders',
+  'community',
+  'seedUsers',
+  'currentAlternative',
+  'manualPath',
+  'commitmentSignals',
+  'firstValidationStep',
+  'defaultAlivePlan',
   'goals',
   'successMetrics',
   'acceptanceGoals',
@@ -157,6 +176,29 @@ const SYNTHESIZE_CONTENT_OVERRIDE_KEYS = new Set([
   'evalPlan',
 ]);
 
+function buildBrainstormSuggestion({ currentState, analysis, clarification, requirementGate }) {
+  const promptPreview = String(requirementGate?.promptPreview ?? '');
+  const explicit = /(脑暴|brainstorm|帮忙梳理|梳理一下|梳理下|先想清楚)/iu.test(promptPreview);
+  const missingRequiredFields = Number(analysis?.missingRequiredFields ?? 0);
+  const noProblemStatement = !normalizedText(currentState?.problemStatement);
+  const noPrimaryUsers = !Array.isArray(currentState?.primaryUsers) || currentState.primaryUsers.length === 0;
+  const shouldSuggest = explicit || (clarification?.shouldAskUser && missingRequiredFields >= 4) || (noProblemStatement && noPrimaryUsers && missingRequiredFields >= 3);
+  if (!shouldSuggest) {
+    return { recommended: false };
+  }
+  const reasons = [];
+  if (explicit) reasons.push('用户当前更像是在请求先梳理业务方向');
+  if (missingRequiredFields >= 4) reasons.push(`还有 ${missingRequiredFields} 个关键信息未确认`);
+  if (noProblemStatement) reasons.push('问题定义还不够稳定');
+  if (noPrimaryUsers) reasons.push('核心用户和场景还没锁定');
+  return {
+    recommended: true,
+    explicitTrigger: explicit,
+    reason: reasons.join('；'),
+    suggestedCommand: 'openprd brainstorm . --open',
+  };
+}
+
 function normalizePrdReviewStatus(status) {
   return PRD_REVIEW_STATUSES.includes(status) ? status : 'pending-confirmation';
 }
@@ -192,6 +234,36 @@ function requirementGateReferenceTimestamp(gate) {
   return gate?.confirmedAt ?? gate?.updatedAt ?? gate?.openedAt ?? null;
 }
 
+function requirementNextActionBlocksSynthesize(nextAction) {
+  return nextAction === 'clarify-user' || nextAction === 'classify' || nextAction === 'interview';
+}
+
+function gateHasClarificationConfirmation(gate) {
+  return Boolean(gate?.clarificationConfirmedAt || gate?.status === 'clarification-confirmed');
+}
+
+function latestConfirmedClarificationCaptureTimestamp(currentState) {
+  const timestamps = Object.entries(currentState?.captureMeta ?? {})
+    .filter(([field, entry]) => USER_CLARIFICATION_PATHS.has(field) && entry?.source === 'user-confirmed')
+    .map(([, entry]) => entry?.capturedAt)
+    .filter(Boolean)
+    .map(String);
+  return timestamps.length > 0 ? timestamps.sort().at(-1) : null;
+}
+
+function hasDerivedClarificationCaptureSince(currentState, gateAt) {
+  const reference = String(gateAt || '');
+  return Object.entries(currentState?.captureMeta ?? {}).some(([field, entry]) => {
+    if (!USER_CLARIFICATION_PATHS.has(field)) {
+      return false;
+    }
+    if (!entry?.capturedAt || String(entry.capturedAt) < reference) {
+      return false;
+    }
+    return Boolean(entry.source) && entry.source !== 'user-confirmed' && !NON_SEMANTIC_CAPTURE_SOURCES.has(entry.source);
+  });
+}
+
 function gateQuestionLimit(gate, fallback) {
   const raw = Number(gate?.approvalPolicy?.maxClarificationQuestions);
   if (!Number.isFinite(raw) || raw <= 0) {
@@ -210,7 +282,23 @@ function ensureFreshRequirementStateForSynthesize({ gate, currentState, override
   }
   const capturedAt = latestCaptureTimestamp(currentState);
   if (capturedAt && String(capturedAt) >= String(gateAt)) {
-    return;
+    if (!gateHasClarificationConfirmation(gate)) {
+      return;
+    }
+    const confirmedCaptureAt = latestConfirmedClarificationCaptureTimestamp(currentState);
+    const hasDerivedCapture = hasDerivedClarificationCaptureSince(currentState, gateAt);
+    if (confirmedCaptureAt && String(confirmedCaptureAt) >= String(gateAt) && !hasDerivedCapture) {
+      return;
+    }
+    throw new Error([
+      'OpenPrd 已阻止 synthesize：当前需求摘要虽已确认，但 current.json 还没有把本轮确认内容稳定写回。',
+      hasDerivedCapture
+        ? '检测到本轮仍有 user clarification 字段被写成 agent-inferred / project-derived；请先改用 openprd capture 按 canonical 字段路径并以 user-confirmed 写回，再继续 synthesize。'
+        : '请先用 openprd capture 按 canonical 字段路径并以 user-confirmed 写回本轮确认事实，再继续 synthesize。',
+      hasSynthesizeContentOverrides(overrides)
+        ? 'partial override 不能替代这一步 requirement write-back。'
+        : null,
+    ].filter(Boolean).join(' '));
   }
   throw new Error([
     'OpenPrd 已阻止 synthesize：当前有新的需求入口，但 current.json 还没有记录本轮确认答案。',
@@ -220,6 +308,27 @@ function ensureFreshRequirementStateForSynthesize({ gate, currentState, override
   ].join(' '));
 }
 
+async function ensureRequirementLaneReadyForSynthesize(ws) {
+  const guidance = await computeWorkspaceGuidance(ws, { questionLimit: 5 });
+  const missingRequiredFields = Number(guidance.analysis?.missingRequiredFields ?? 0);
+  const lacksProductType = !guidance.analysis?.productType;
+  const blockedByStructuredGap = guidance.nextAction === 'classify'
+    || guidance.nextAction === 'interview'
+    || (guidance.nextAction === 'clarify-user' && (lacksProductType || missingRequiredFields > 0));
+  if (!blockedByStructuredGap) {
+    return;
+  }
+  throw new Error([
+    'OpenPrd 已阻止 synthesize：当前 requirement lane 还没有离开需求补齐阶段。',
+    `当前下一步仍是 ${guidance.nextAction}。`,
+    guidance.reason ? `原因: ${guidance.reason}` : null,
+    guidance.suggestedCommand ? `建议先执行: ${guidance.suggestedCommand}。` : null,
+    Array.isArray(guidance.suggestedQuestions) && guidance.suggestedQuestions.length > 0
+      ? `优先补齐: ${guidance.suggestedQuestions.slice(0, 2).join('；')}。`
+      : null,
+  ].filter(Boolean).join(' '));
+}
+
 function resolveReviewPaths(ws, snapshot) {
   const canonicalReview = canonicalReviewPath(ws, snapshot.versionId);
   const activeReviewEntry = defaultReviewArtifactPath(ws);
@@ -383,7 +492,6 @@ function detectRequirementIntakeComplexity(gate) {
   ];
   const simpleConcretePatterns = [
     /按钮|文案|颜色|圆角|位置|间距|字号|图标|标题|空格|标点|错别字|拼写|label|copy/i,
-    /红圈|描边|边框|卡片|平铺|去掉|去除|移除|隐藏|对齐|留白|背景/,
     /从.+(改到|移到|移动到|换到|变成|改成|改为).+/,
   ];
   const reasons = [];
@@ -505,6 +613,37 @@ function collectProjectRiskProbes(gate, snapshot) {
   return probes;
 }
 
+function buildValidationFraming(sections = {}) {
+  const validation = sections.validation ?? {};
+  return {
+    community: shortList(validation.community, '需要先确认第一批最容易触达的社区、渠道或人群。'),
+    seedUsers: shortList(validation.seedUsers, '需要先确认第一批具体先找谁聊、先服务谁。'),
+    currentAlternative: shortList(validation.currentAlternative, '需要先确认他们现在主要靠什么替代方案在解决。'),
+    manualPath: shortList(validation.manualPath, '需要先确认不做完整产品时先怎么手工交付价值。'),
+    commitmentSignals: shortList(validation.commitmentSignals, '需要先确认什么真实承诺能证明不是口头兴趣。'),
+    firstValidationStep: shortList(validation.firstValidationStep, '需要先确认最低成本先做哪一步验证。'),
+    defaultAlivePlan: shortList(validation.defaultAlivePlan, '需要先确认验证阶段怎样先活下来。'),
+  };
+}
+
+function hasSatisfiedConfirmedClarificationWriteback({ gate, currentState, analysis, hasProductType }) {
+  if (!gateHasClarificationConfirmation(gate)) {
+    return false;
+  }
+  if (!hasProductType || Number(analysis?.missingRequiredFields ?? 0) > 0) {
+    return false;
+  }
+  const gateAt = requirementGateReferenceTimestamp(gate);
+  if (!gateAt) {
+    return false;
+  }
+  const confirmedCaptureAt = latestConfirmedClarificationCaptureTimestamp(currentState);
+  if (!confirmedCaptureAt || String(confirmedCaptureAt) < String(gateAt)) {
+    return false;
+  }
+  return !hasDerivedClarificationCaptureSince(currentState, gateAt);
+}
+
 function buildProjectFraming({ gate, snapshot, scenario, productType }) {
   const sections = snapshot.sections ?? {};
   const guardrailHints = [
@@ -512,6 +651,7 @@ function buildProjectFraming({ gate, snapshot, scenario, productType }) {
     ...normalizeTextList(sections.constraints?.dependencies),
   ];
   const riskProbes = collectProjectRiskProbes(gate, snapshot);
+  const validationFraming = buildValidationFraming(sections);
   return {
     audience: shortList(
       sections.users?.primaryUsers,
@@ -524,6 +664,7 @@ function buildProjectFraming({ gate, snapshot, scenario, productType }) {
     nonGoals: shortList(sections.scope?.outOfScope, '需要先确认本轮先不做什么。'),
     guardrails: shortList(guardrailHints, '需要先确认哪些现有能力、数据、流程或体验不能被破坏。'),
     architectureSignals: summarizeArchitectureSignals(gate, snapshot),
+    validationFraming,
     riskProbes,
     riskProbeSummary: shortList(riskProbes, '当前没有明显命中额外风险探针。'),
   };
@@ -553,7 +694,7 @@ function describeProductLensFocus(productType) {
 function requirementTypeDisplay(gate) {
   const tier = String(gate?.intent?.requirementTier ?? '').toLowerCase();
   if (tier === 'l0') {
-    return '快速修正（L0）';
+    return '直接处理（L0）';
   }
   if (tier === 'l1') {
     return '现有功能优化（L1）';
@@ -800,6 +941,7 @@ function buildInlineClarification({ clarification, reflection, presentation }) {
   const prompt = reflection?.promptPreview || '本轮需求';
   const projectContext = reflection?.projectContext ?? {};
   const projectFraming = projectContext.projectFraming ?? {};
+  const validationFraming = projectFraming.validationFraming ?? {};
   const productType = projectContext.productType;
   const primaryQuestion = clarification.mustAskUser[0] ?? null;
   const followUpQuestions = clarification.mustAskUser.slice(1, presentation.mode === 'inline' ? 2 : 3);
@@ -830,6 +972,12 @@ function buildInlineClarification({ clarification, reflection, presentation }) {
     `- 第一版先让用户做到：${projectFraming.firstSlice ?? '待确认'}。`,
     `- 这轮先不碰：${projectFraming.nonGoals ?? '待确认'}。`,
     `- 必须守住：${projectFraming.guardrails ?? '待确认'}。`,
+    `- 第一批最容易触达：${validationFraming.community ?? '待确认'}。`,
+    `- 当前主要替代：${validationFraming.currentAlternative ?? '待确认'}。`,
+    `- 先怎么手工交付：${validationFraming.manualPath ?? '待确认'}。`,
+    `- 什么承诺才算真需求：${validationFraming.commitmentSignals ?? '待确认'}。`,
+    `- 最低成本先验证：${validationFraming.firstValidationStep ?? '待确认'}。`,
+    `- 怎么先活下来：${validationFraming.defaultAlivePlan ?? '待确认'}。`,
   ];
   if (projectFraming.architectureSignals) {
     lines.push(`- 这次更可能会影响：${projectFraming.architectureSignals}。`);
@@ -950,6 +1098,11 @@ async function buildRequirementIntakeReflection({ projectRoot, ws, snapshot, ana
     productType: snapshot.productType ?? resolveCurrentProductType(ws),
   });
   const lensQuestion = buildLensReflectionQuestion(snapshot.productType ?? resolveCurrentProductType(ws));
+  const validationLoopQuestion = reflectionQuestion(
+    'validation-loop',
+    '验证与创业闭环',
+    '请确认第一批最容易触达的社区或用户是谁、他们现在靠什么替代、如果先不做完整产品怎么手工交付、什么真实承诺最能证明值得继续，以及最低成本验证和先活下来底线是什么。'
+  );
   const needsDeliveryShapeQuestion = !needsInterfaceSketch
     && (
       projectFraming.riskProbes.length > 0
@@ -959,6 +1112,7 @@ async function buildRequirementIntakeReflection({ projectRoot, ws, snapshot, ana
     ? [
         reflectionQuestion('intent', '意图与目标', '请确认我理解得对不对：这次主要是谁在什么场景下遇到什么问题，第一版最想先改善什么结果？'),
         lensQuestion,
+        validationLoopQuestion,
         reflectionQuestion('project-context', '项目影响范围', '结合当前项目，请确认第一版最小可用切片是什么；哪些已有模块、入口、流程或历史需求必须复用，哪些可以调整？'),
         reflectionQuestion('scope-quality', '范围与验收', '请确认这次先做到哪一步就算有价值；哪些这轮先不动；哪些老用户习惯、现有业务结果或交付节奏不能被影响？'),
         needsInterfaceSketch
@@ -1011,6 +1165,7 @@ async function buildRequirementIntakeReflection({ projectRoot, ws, snapshot, ana
           `当前产品：${productName}；当前产品场景：${formatProductTypeDisplay(productType, { fallback: '待确认' })}；已记录问题：${currentProblem}`,
           `当前范围线索：${currentScope}`,
           `首轮画像：用户群体=${projectFraming.audience}；产品形态=${projectFraming.productShape}；第一版先做=${projectFraming.firstSlice}`,
+          `验证闭环：可触达人群=${projectFraming.validationFraming?.community}；当前替代=${projectFraming.validationFraming?.currentAlternative}；手工路径=${projectFraming.validationFraming?.manualPath}`,
           activeChange ? `仍有 active change：${activeChange.activeChange}（${activeChange.status}），需要和本轮需求分开评估。` : '当前没有检测到 active change 冲突。',
         ],
       },
@@ -1020,6 +1175,7 @@ async function buildRequirementIntakeReflection({ projectRoot, ws, snapshot, ana
         findings: [
           `仍需确认的信息：${shortList(missing, '暂无明显缺口')}`,
           `边界与约束：先不做=${projectFraming.nonGoals}；不能破坏=${projectFraming.guardrails}`,
+          `商业验证：承诺信号=${projectFraming.validationFraming?.commitmentSignals}；低成本验证=${projectFraming.validationFraming?.firstValidationStep}；先活下来=${projectFraming.validationFraming?.defaultAlivePlan}`,
           needsInterfaceSketch ? '需求看起来涉及界面或流程，需要先给用户确认草图或关键操作路径。' : `影响环节：${projectFraming.architectureSignals}`,
           `业务提醒：${projectFraming.riskProbeSummary}`,
           '进入实现前必须保留范围、非目标、异常路径和验收证据。',
@@ -1058,6 +1214,12 @@ function renderRequirementIntakeReflection(reflection) {
     `| 第一版先做 | ${escapeMarkdownTableCell(reflection.projectContext.projectFraming?.firstSlice ?? '待补充')} |`,
     `| 暂不处理 | ${escapeMarkdownTableCell(reflection.projectContext.projectFraming?.nonGoals ?? '待补充')} |`,
     `| 不能破坏 | ${escapeMarkdownTableCell(reflection.projectContext.projectFraming?.guardrails ?? '待补充')} |`,
+    `| 可触达人群 | ${escapeMarkdownTableCell(reflection.projectContext.projectFraming?.validationFraming?.community ?? '待补充')} |`,
+    `| 当前替代 | ${escapeMarkdownTableCell(reflection.projectContext.projectFraming?.validationFraming?.currentAlternative ?? '待补充')} |`,
+    `| 手工路径 | ${escapeMarkdownTableCell(reflection.projectContext.projectFraming?.validationFraming?.manualPath ?? '待补充')} |`,
+    `| 承诺信号 | ${escapeMarkdownTableCell(reflection.projectContext.projectFraming?.validationFraming?.commitmentSignals ?? '待补充')} |`,
+    `| 最低成本验证 | ${escapeMarkdownTableCell(reflection.projectContext.projectFraming?.validationFraming?.firstValidationStep ?? '待补充')} |`,
+    `| 先活下来 | ${escapeMarkdownTableCell(reflection.projectContext.projectFraming?.validationFraming?.defaultAlivePlan ?? '待补充')} |`,
     `| 影响环节 | ${escapeMarkdownTableCell(reflection.projectContext.projectFraming?.architectureSignals ?? '待补充')} |`,
     `| 业务提醒 | ${escapeMarkdownTableCell(reflection.projectContext.projectFraming?.riskProbeSummary ?? '待补充')} |`,
     '',
@@ -1091,6 +1253,7 @@ function buildRequirementIntakeDepth(gate, reflection = null) {
   const fallbackLayers = [
     reflectionQuestion('product-context', '用户 / 产品形态 / 问题', '先确认：这是给谁用的、它更像个人产品 / 团队流程 / Agent 协作中的哪一种、为什么现在值得解决？'),
     reflectionQuestion('product-outcome', '第一版切片 / 目标 / 成功标准', '请确认第一版最小可用切片是什么；解决后用户先能完成什么，用什么业务结果或验收标准判断有效？'),
+    reflectionQuestion('product-validation', '验证闭环 / 承诺信号', '请确认第一批最容易触达的社区或用户是谁、他们现在靠什么替代、如果先不做完整产品怎么手工交付、什么真实承诺最能证明值得继续，以及最低成本验证和先活下来底线是什么。'),
     reflectionQuestion('product-flow', '范围 / 非目标 / 异常路径', '请拆出本轮先做什么、不做什么、哪些既有行为不能被破坏，以及关键失败路径和恢复方式。'),
     reflectionQuestion(
       'product-detail',
@@ -1226,11 +1389,15 @@ async function synthesizeWorkspace(projectRoot, overrides = {}) {
   if (!(await exists(ws.workspaceRoot))) {
     throw new Error(`Missing workspace: ${ws.workspaceRoot}`);
   }
+  const requirementGate = await readActiveRequirementGate(projectRoot);
   ensureFreshRequirementStateForSynthesize({
-    gate: await readActiveRequirementGate(projectRoot),
+    gate: requirementGate,
     currentState: ws.data.currentState ?? {},
     overrides,
   });
+  if (requirementGate?.active && gateHasClarificationConfirmation(requirementGate)) {
+    await ensureRequirementLaneReadyForSynthesize(ws);
+  }
 
   const versionIndex = await readVersionIndex(ws);
   const nextVersionNumber = overrides.versionNumber ?? (versionIndex.length > 0
@@ -1911,6 +2078,12 @@ async function computeWorkspaceGuidance(ws, options = {}) {
   const scenario = await detectWorkspaceScenario(ws.projectRoot, ws, versionIndex);
   const requirementGate = await readActiveRequirementGate(ws.projectRoot);
   const intakeSatisfiedByReview = prdReviewState.status === 'confirmed' && analysis.missingRequiredFields === 0;
+  const intakeSatisfiedByConfirmedWriteback = hasSatisfiedConfirmedClarificationWriteback({
+    gate: requirementGate,
+    currentState,
+    analysis,
+    hasProductType,
+  });
   const intakeReflection = await buildRequirementIntakeReflection({
     projectRoot: ws.projectRoot,
     ws,
@@ -1927,7 +2100,9 @@ async function computeWorkspaceGuidance(ws, options = {}) {
     captureMeta: currentState.captureMeta ?? {},
     prdReviewState,
     limit: Number(options.questionLimit ?? 5),
-  }), requirementGate, intakeReflection, { satisfied: intakeSatisfiedByReview });
+  }), requirementGate, intakeReflection, {
+    satisfied: intakeSatisfiedByReview || intakeSatisfiedByConfirmedWriteback,
+  });
 
   let nextAction = 'synthesize';
   let reason = 'PRD 可以合成为第一个版本。';
@@ -1987,6 +2162,12 @@ async function computeWorkspaceGuidance(ws, options = {}) {
 
   const taskGraph = buildWorkflowTaskGraph(analysisSnapshot, analysis, { diagramState, prdReviewState, clarificationState: clarification });
   const gates = deriveGateLabels({ nextAction, diagramState, clarification });
+  const brainstormSuggestion = buildBrainstormSuggestion({
+    currentState,
+    analysis,
+    clarification,
+    requirementGate,
+  });
 
   return {
     versionIndex,
@@ -2002,6 +2183,7 @@ async function computeWorkspaceGuidance(ws, options = {}) {
     suggestedCommand,
     suggestedQuestions,
     gates,
+    brainstormSuggestion,
   };
 }
 
@@ -2065,7 +2247,8 @@ async function nextWorkspace(projectRoot) {
       currentGate: gates.currentGate,
       upcomingGate: gates.upcomingGate,
     },
-    workflow: ['clarify', 'classify', 'interview', 'synthesize', 'diagram', 'review', 'freeze', 'handoff'],
+    brainstormSuggestion: guidance.brainstormSuggestion,
+    workflow: ['brainstorm', 'clarify', 'classify', 'interview', 'synthesize', 'diagram', 'review', 'freeze', 'handoff'],
   };
 }
 

package/.openprd/benchmarks/evidence/milvus-io-ai-code-review-gets-better-when-models-debate-claude-vs-gemini-vs-code.md

@@ -1,14 +0,0 @@
-# milvus.io/ai-code-review-gets-better-when-models-debate-claude-vs-gemini-vs-codex-vs-qwen-vs-minimax.md
-
-- ID: milvus-io-ai-code-review-gets-better-when-models-debate-claude-vs-gemini-vs-code
-- 状态: approved
-- 场景: agent-harness, pr-review-harness
-- 触发: 设计 Agent harness、长程任务、状态持久化、验证门禁或人工接管；设计 merge 前高风险复核、独立 reviewer 交叉验证、误报过滤、reviewer agreement 或 merge recommendation
-- 不适用: 普通 PRD / 产品流程设计；与 CLI 无关的一次性 UI 视觉问题；默认给每个低风险 PR 拉起多 reviewer 并行审查
-- 研究方式: official_page_first
-- 来源: https://milvus.io/ar/blog/ai-code-review-gets-better-when-models-debate-claude-vs-gemini-vs-codex-vs-qwen-vs-minimax.md
-
-## 备注
-
-AI code review / PR review harness；reviewer agreement、交叉验证、误报过滤、hallucination filter、merge recommendation
-