@openprd/cli 0.1.10 → 0.1.18

package/src/openspec/migration.js

@@ -0,0 +1,168 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  LEGACY_OPENPRD_ACCEPTED_SPEC_ROOT,
+  LEGACY_OPENPRD_ARCHIVE_CHANGE_ROOT,
+  LEGACY_OPENPRD_CHANGE_ROOT,
+  OPENPRD_ACCEPTED_SPEC_ROOT,
+  OPENPRD_ARCHIVE_CHANGE_ROOT,
+  OPENPRD_CHANGE_ROOT,
+} from './constants.js';
+
+function cjoin(...parts) {
+  return path.join(...parts);
+}
+
+async function exists(filePath) {
+  return fs.access(filePath).then(() => true).catch(() => false);
+}
+
+function relativeProjectPath(projectRoot, filePath) {
+  return path.relative(projectRoot, filePath) || '.';
+}
+
+async function removeDirectoryIfEmpty(dirPath) {
+  const entries = await fs.readdir(dirPath).catch(() => null);
+  if (entries && entries.length === 0) {
+    await fs.rmdir(dirPath);
+    return true;
+  }
+  return false;
+}
+
+async function sameFileContent(leftPath, rightPath) {
+  const [left, right] = await Promise.all([
+    fs.readFile(leftPath),
+    fs.readFile(rightPath),
+  ]);
+  return left.equals(right);
+}
+
+async function movePath(sourcePath, targetPath) {
+  await fs.mkdir(path.dirname(targetPath), { recursive: true });
+  try {
+    await fs.rename(sourcePath, targetPath);
+  } catch (error) {
+    if (error?.code !== 'EXDEV') {
+      throw error;
+    }
+    const stat = await fs.stat(sourcePath);
+    await fs.cp(sourcePath, targetPath, { recursive: stat.isDirectory(), force: false, errorOnExist: true });
+    await fs.rm(sourcePath, { recursive: stat.isDirectory(), force: true });
+  }
+}
+
+async function mergeLegacyTree(projectRoot, sourcePath, targetPath, changes) {
+  const sourceStat = await fs.stat(sourcePath).catch(() => null);
+  if (!sourceStat) {
+    return { migrated: 0, conflicts: 0 };
+  }
+
+  const targetStat = await fs.stat(targetPath).catch(() => null);
+  if (!targetStat) {
+    await movePath(sourcePath, targetPath);
+    changes.push({
+      path: relativeProjectPath(projectRoot, targetPath),
+      from: relativeProjectPath(projectRoot, sourcePath),
+      status: 'migrated',
+    });
+    return { migrated: 1, conflicts: 0 };
+  }
+
+  if (sourceStat.isDirectory() && targetStat.isDirectory()) {
+    let migrated = 0;
+    let conflicts = 0;
+    const entries = await fs.readdir(sourcePath, { withFileTypes: true });
+    for (const entry of entries) {
+      const sourceChild = cjoin(sourcePath, entry.name);
+      const targetChild = cjoin(targetPath, entry.name);
+      const result = await mergeLegacyTree(projectRoot, sourceChild, targetChild, changes);
+      migrated += result.migrated;
+      conflicts += result.conflicts;
+    }
+    if (await removeDirectoryIfEmpty(sourcePath)) {
+      changes.push({
+        path: relativeProjectPath(projectRoot, sourcePath),
+        status: 'removed-empty-legacy-dir',
+      });
+    }
+    return { migrated, conflicts };
+  }
+
+  if (sourceStat.isFile() && targetStat.isFile() && await sameFileContent(sourcePath, targetPath)) {
+    await fs.rm(sourcePath, { force: true });
+    changes.push({
+      path: relativeProjectPath(projectRoot, sourcePath),
+      target: relativeProjectPath(projectRoot, targetPath),
+      status: 'removed-duplicate-legacy-file',
+    });
+    return { migrated: 0, conflicts: 0 };
+  }
+
+  changes.push({
+    path: relativeProjectPath(projectRoot, sourcePath),
+    target: relativeProjectPath(projectRoot, targetPath),
+    status: 'conflict-kept-legacy',
+  });
+  return { migrated: 0, conflicts: 1 };
+}
+
+export async function hasLegacyOpenPrdArtifacts(projectRoot) {
+  const roots = [
+    cjoin(projectRoot, ...LEGACY_OPENPRD_CHANGE_ROOT),
+    cjoin(projectRoot, ...LEGACY_OPENPRD_ACCEPTED_SPEC_ROOT),
+    cjoin(projectRoot, ...LEGACY_OPENPRD_ARCHIVE_CHANGE_ROOT),
+  ];
+  for (const root of roots) {
+    if (await exists(root)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export async function migrateLegacyOpenPrdArtifacts(projectRoot) {
+  const legacyRoot = cjoin(projectRoot, 'openprd');
+  const changes = [];
+  let migrated = 0;
+  let conflicts = 0;
+
+  const pairs = [
+    [LEGACY_OPENPRD_CHANGE_ROOT, OPENPRD_CHANGE_ROOT],
+    [LEGACY_OPENPRD_ACCEPTED_SPEC_ROOT, OPENPRD_ACCEPTED_SPEC_ROOT],
+    [LEGACY_OPENPRD_ARCHIVE_CHANGE_ROOT, OPENPRD_ARCHIVE_CHANGE_ROOT],
+  ];
+
+  for (const [legacyParts, targetParts] of pairs) {
+    const result = await mergeLegacyTree(
+      projectRoot,
+      cjoin(projectRoot, ...legacyParts),
+      cjoin(projectRoot, ...targetParts),
+      changes,
+    );
+    migrated += result.migrated;
+    conflicts += result.conflicts;
+  }
+
+  if (await exists(legacyRoot)) {
+    await removeDirectoryIfEmpty(cjoin(legacyRoot, 'archive')).catch(() => false);
+    if (await removeDirectoryIfEmpty(legacyRoot).catch(() => false)) {
+      changes.push({ path: 'openprd', status: 'removed-empty-legacy-root' });
+    } else if (changes.length > 0) {
+      changes.push({ path: 'openprd', status: 'legacy-root-kept-nonempty' });
+    }
+  }
+
+  return {
+    ok: conflicts === 0,
+    action: 'migrate-legacy-openprd-artifacts',
+    projectRoot,
+    migrated,
+    conflicts,
+    changed: changes.length > 0,
+    changes,
+    errors: conflicts > 0
+      ? ['旧 openprd 目录中存在与 .openprd 目标路径同名但内容不同的文件，已保留旧文件等待人工处理。']
+      : [],
+  };
+}

package/src/openspec/paths.js

@@ -1,9 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import {
-  LEGACY_OPENSPEC_CHANGE_ROOT,
-  LEGACY_OPENSPEC_DISCOVERY_CONFIG_PATH,
-  LEGACY_OPENSPEC_DISCOVERY_DIR,
   OPENPRD_ACCEPTED_SPEC_ROOT,
   OPENPRD_ARCHIVE_CHANGE_ROOT,
   OPENPRD_CHANGE_ROOT,
@@ -23,34 +20,18 @@ export function openPrdDiscoveryDir(projectRoot) {
   return cjoin(projectRoot, ...OPENPRD_DISCOVERY_DIR);
 }
 
-export function legacyOpenSpecDiscoveryDir(projectRoot) {
-  return cjoin(projectRoot, ...LEGACY_OPENSPEC_DISCOVERY_DIR);
-}
-
 export function openPrdDiscoveryConfigPath(projectRoot) {
   return cjoin(projectRoot, ...OPENPRD_DISCOVERY_CONFIG_PATH);
 }
 
-export function legacyOpenSpecDiscoveryConfigPath(projectRoot) {
-  return cjoin(projectRoot, ...LEGACY_OPENSPEC_DISCOVERY_CONFIG_PATH);
-}
-
 export async function readDiscoveryConfig(projectRoot, readJson) {
-  const primary = openPrdDiscoveryConfigPath(projectRoot);
-  const legacy = legacyOpenSpecDiscoveryConfigPath(projectRoot);
-  return (await readJson(primary).catch(() => null))
-    ?? (await readJson(legacy).catch(() => null))
-    ?? {};
+  return (await readJson(openPrdDiscoveryConfigPath(projectRoot)).catch(() => null)) ?? {};
 }
 
 export function openPrdChangeRoot(projectRoot) {
   return cjoin(projectRoot, ...OPENPRD_CHANGE_ROOT);
 }
 
-export function legacyOpenSpecChangeRoot(projectRoot) {
-  return cjoin(projectRoot, ...LEGACY_OPENSPEC_CHANGE_ROOT);
-}
-
 export function openPrdAcceptedSpecRoot(projectRoot) {
   return cjoin(projectRoot, ...OPENPRD_ACCEPTED_SPEC_ROOT);
 }
@@ -62,7 +43,6 @@ export function openPrdArchiveChangeRoot(projectRoot) {
 export async function resolveChangeDir(projectRoot, changeId) {
   const candidates = [
     cjoin(openPrdChangeRoot(projectRoot), changeId),
-    cjoin(legacyOpenSpecChangeRoot(projectRoot), changeId),
     cjoin(openPrdArchiveChangeRoot(projectRoot), changeId),
   ];
   for (const candidate of candidates) {
@@ -76,7 +56,6 @@ export async function resolveChangeDir(projectRoot, changeId) {
 export async function listChangeDirs(projectRoot) {
   const roots = [
     { root: openPrdChangeRoot(projectRoot), source: 'openprd', archived: false },
-    { root: legacyOpenSpecChangeRoot(projectRoot), source: 'legacy-openspec', archived: false },
     { root: openPrdArchiveChangeRoot(projectRoot), source: 'openprd-archive', archived: true },
   ];
   const changes = [];

package/src/prd-core.js

@@ -242,11 +242,26 @@ export function buildPrdSnapshot(ws, options = {}) {
     validation: {
       community: normalizeArray(pickValue(options.community, state.community)),
       seedUsers: normalizeArray(pickValue(options.seedUsers, state.seedUsers)),
+      communityFit: normalizeArray(pickValue(options.communityFit, state.communityFit)),
       currentAlternative: pickValue(options.currentAlternative, state.currentAlternative, state.asIs),
+      painEvidence: normalizeArray(pickValue(options.painEvidence, state.painEvidence)),
       manualPath: normalizeArray(pickValue(options.manualPath, state.manualPath)),
+      manualPlaybook: normalizeArray(pickValue(options.manualPlaybook, state.manualPlaybook)),
       commitmentSignals: normalizeArray(pickValue(options.commitmentSignals, state.commitmentSignals)),
       firstValidationStep: pickValue(options.firstValidationStep, state.firstValidationStep, state.nextStep),
       defaultAlivePlan: normalizeArray(pickValue(options.defaultAlivePlan, state.defaultAlivePlan)),
+      paymentProof: normalizeArray(pickValue(options.paymentProof, state.paymentProof)),
+      mvpSlice: pickValue(options.mvpSlice, state.mvpSlice),
+      weekendTest: pickValue(options.weekendTest, state.weekendTest),
+      smallestExecution: normalizeArray(pickValue(options.smallestExecution, state.smallestExecution)),
+      productizeGate: normalizeArray(pickValue(options.productizeGate, state.productizeGate)),
+      firstCustomerPath: normalizeArray(pickValue(options.firstCustomerPath, state.firstCustomerPath)),
+      pricingHypothesis: pickValue(options.pricingHypothesis, state.pricingHypothesis),
+      customerOneProfitability: pickValue(options.customerOneProfitability, state.customerOneProfitability),
+      growthDiscipline: normalizeArray(pickValue(options.growthDiscipline, state.growthDiscipline)),
+      reversibility: pickValue(options.reversibility, state.reversibility),
+      customerTruth: pickValue(options.customerTruth, state.customerTruth),
+      valuesFit: pickValue(options.valuesFit, state.valuesFit),
     },
     scope: {
       inScope: normalizeArray(pickValue(options.inScope, state.inScope)),
@@ -283,7 +298,7 @@ export function buildPrdSnapshot(ws, options = {}) {
     handoff: {
       owner: pickValue(options.handoffOwner, state.handoffOwner, owner),
       nextStep: pickValue(options.nextStep, state.nextStep, '评审已生成的 PRD，并准备交接。'),
-      targetSystem: pickValue(options.targetSystem, state.targetSystem, 'OpenSpec'),
+      targetSystem: pickValue(options.targetSystem, state.targetSystem, 'OpenPrd'),
     },
     typeSpecific: buildTypeSpecificSection(productType, state, options),
   };
@@ -379,11 +394,26 @@ export function renderPrdMarkdown(snapshot) {
     renderSection('验证与创业闭环', [
       ['可触达社区', sections.validation.community],
       ['第一批种子用户', sections.validation.seedUsers],
+      ['社区契合与触达依据', sections.validation.communityFit],
       ['当前替代方案', sections.validation.currentAlternative],
+      ['痛点与替代证据', sections.validation.painEvidence],
       ['手工交付路径', sections.validation.manualPath],
+      ['手工作战卡', sections.validation.manualPlaybook],
       ['承诺信号', sections.validation.commitmentSignals],
       ['首个低成本验证', sections.validation.firstValidationStep],
       ['先活下来方案', sections.validation.defaultAlivePlan],
+      ['付费验证信号', sections.validation.paymentProof],
+      ['第一版只做一件事', sections.validation.mvpSlice],
+      ['周末级验证', sections.validation.weekendTest],
+      ['最小工具桥接', sections.validation.smallestExecution],
+      ['产品化门槛', sections.validation.productizeGate],
+      ['第一批客户路径', sections.validation.firstCustomerPath],
+      ['初始收费假设', sections.validation.pricingHypothesis],
+      ['客户 1 盈利路径', sections.validation.customerOneProfitability],
+      ['销售与增长纪律', sections.validation.growthDiscipline],
+      ['可逆性判断', sections.validation.reversibility],
+      ['客户真问题校验', sections.validation.customerTruth],
+      ['价值观一致性', sections.validation.valuesFit],
     ]),
     renderSection('范围与非目标', [
       ['范围内', sections.scope.inScope],
@@ -477,6 +507,32 @@ const BUSINESS_GUARDRAIL_FIELD_DESCRIPTORS = [
   { section: 'businessGuardrails', path: 'businessGuardrails.stopLossActions', label: '止损动作', prompt: '触发异常后，应该降级、暂停、关闭哪些能力，谁来处理？' },
 ];
 
+
+const VALIDATION_REQUIRED_FIELD_DESCRIPTORS = [
+  { section: 'validation', path: 'validation.community', label: '第一批可触达人群', prompt: '第一批最容易触达的社区、渠道或人群是谁？' },
+  { section: 'validation', path: 'validation.seedUsers', label: '种子用户', prompt: '至少 3 到 10 个最该先找的人是谁？' },
+  { section: 'validation', path: 'validation.communityFit', label: '社区契合', prompt: '你为什么算这个社区里的自己人？你现在是否已经在真实参与或贡献，他们为什么愿意先相信你？' },
+  { section: 'validation', path: 'validation.currentAlternative', label: '当前替代方案', prompt: '用户现在主要靠什么替代方案、流程或人工方式在解决？' },
+  { section: 'validation', path: 'validation.painEvidence', label: '痛点证据', prompt: '这个问题到底有多痛，用户已经在为更差的办法花什么时间或金钱？' },
+  { section: 'validation', path: 'validation.manualPath', label: '手工交付路径', prompt: '如果先不做完整产品，怎么靠手工服务或半自动流程把价值跑出来？' },
+  { section: 'validation', path: 'validation.manualPlaybook', label: '手工作战卡', prompt: '触发条件、步骤、工具、耗时和交接点分别是什么？' },
+  { section: 'validation', path: 'validation.commitmentSignals', label: '承诺信号', prompt: '什么真实承诺最能证明这不是口头兴趣？' },
+  { section: 'validation', path: 'validation.firstValidationStep', label: '最低成本验证', prompt: '最低成本先验证哪一步最关键？' },
+  { section: 'validation', path: 'validation.defaultAlivePlan', label: '先活下来方案', prompt: '验证阶段怎样不把成本、复杂度和维护负担一下子做爆？' },
+  { section: 'validation', path: 'validation.paymentProof', label: '付费验证信号', prompt: '有没有 10 个样本、3/10 付费意愿或更强交易信号？' },
+  { section: 'validation', path: 'validation.mvpSlice', label: '一件事 MVP', prompt: '第一版到底只做哪一件事？' },
+  { section: 'validation', path: 'validation.weekendTest', label: '周末级验证', prompt: '能不能压成周末级 MVP、顾问式试跑或更轻验证？' },
+  { section: 'validation', path: 'validation.smallestExecution', label: '最小工具桥接', prompt: '能不能先用 spreadsheet、表单或 no-code 工具把第一版跑起来？如果必须开始做产品，也只自动化最重复的一步并先压成 forms / lists / CRUD 骨架；不要先为假想中的未来客户造复杂能力。' },
+  { section: 'validation', path: 'validation.productizeGate', label: '产品化门槛', prompt: '达到什么条件才允许继续产品化或加功能？先服务今天已经存在的重复需求，不要提前为未来规模开壳。' },
+  { section: 'validation', path: 'validation.firstCustomerPath', label: '第一批客户路径', prompt: '第一批客户最现实的触达顺序是什么？' },
+  { section: 'validation', path: 'validation.pricingHypothesis', label: '初始收费假设', prompt: '从第一个客户开始准备怎么收费？' },
+  { section: 'validation', path: 'validation.customerOneProfitability', label: '客户 1 盈利路径', prompt: '第一个客户如何覆盖时间和交付成本？' },
+  { section: 'validation', path: 'validation.growthDiscipline', label: '增长纪律', prompt: '销售、launch 和增长阶段准备守哪些纪律？' },
+  { section: 'validation', path: 'validation.reversibility', label: '可逆性', prompt: '如果结果一般，这条路是否容易回退？是否在逼你做重招聘、长期绑定或重平台化这类不可逆决策？' },
+  { section: 'validation', path: 'validation.customerTruth', label: '客户真问题', prompt: '这更像在解决客户真问题，还是满足内部冲动？' },
+  { section: 'validation', path: 'validation.valuesFit', label: '价值观一致性', prompt: '这条路是否符合团队想坚持的价值观和长期经营方式？如果连续这样做 3 到 5 年，你还愿意住在这套业务里吗？' },
+];
+
 const TYPE_REQUIRED_FIELD_DESCRIPTORS = {
   consumer: [
     { section: 'consumer', path: 'typeSpecific.fields.persona', label: '用户画像', prompt: '目标用户画像是什么？' },
@@ -535,8 +591,49 @@ function isMissingPrdValue(value) {
   return false;
 }
 
-export function getRequiredFieldDescriptors(productType) {
+function needsValidationLoop(snapshot) {
+  const sections = snapshot?.sections ?? {};
+  const validation = sections.validation ?? {};
+  const explicitValidationSignals = [
+    validation.community,
+    validation.seedUsers,
+    validation.communityFit,
+    validation.painEvidence,
+    validation.manualPath,
+    validation.manualPlaybook,
+    validation.commitmentSignals,
+    validation.defaultAlivePlan,
+    validation.paymentProof,
+    validation.mvpSlice,
+    validation.weekendTest,
+    validation.smallestExecution,
+    validation.productizeGate,
+    validation.firstCustomerPath,
+    validation.pricingHypothesis,
+    validation.customerOneProfitability,
+    validation.growthDiscipline,
+    validation.reversibility,
+    validation.customerTruth,
+    validation.valuesFit,
+  ];
+  if (explicitValidationSignals.some((value) => !isMissingPrdValue(value))) {
+    return true;
+  }
+  const text = flattenForSearch({
+    problem: sections.problem,
+    goals: sections.goals,
+    scope: sections.scope,
+    requirements: sections.requirements,
+    risks: sections.risks,
+  });
+  return /(创业|脑暴|brainstorm|0\s*(到|to)\s*1|值不值得|worth doing|种子用户|第一批(客户|用户)|社区|workaround|手工交付|顾问式|一件事\s*mvp|周末级|首批成交|default alive|productize|no-code|spreadsheet|first customer)/iu.test(text);
+}
+
+export function getRequiredFieldDescriptors(productType, options = {}) {
   const descriptors = [...BASE_REQUIRED_FIELD_DESCRIPTORS];
+  if (options.includeValidation) {
+    descriptors.push(...VALIDATION_REQUIRED_FIELD_DESCRIPTORS);
+  }
   if (TYPE_REQUIRED_FIELD_DESCRIPTORS[productType]) {
     descriptors.push(...TYPE_REQUIRED_FIELD_DESCRIPTORS[productType]);
   }
@@ -568,7 +665,8 @@ export function needsBusinessGuardrails(snapshot) {
 
 export function analyzePrdSnapshot(snapshot) {
   const productType = snapshot.productType ?? null;
-  const descriptors = getRequiredFieldDescriptors(productType);
+  const includeValidation = needsValidationLoop(snapshot);
+  const descriptors = getRequiredFieldDescriptors(productType, { includeValidation });
   if (needsBusinessGuardrails(snapshot)) {
     descriptors.push(...BUSINESS_GUARDRAIL_FIELD_DESCRIPTORS);
   }
@@ -596,6 +694,7 @@ export function analyzePrdSnapshot(snapshot) {
 
   return {
     productType,
+    includeValidation,
     totalRequiredFields,
     completedRequiredFields,
     missingRequiredFields: missingFields.length,

package/src/quality-html-artifact.js

@@ -517,13 +517,38 @@ function exceptionItems(report) {
     }));
 }
 
+const EVIDENCE_SOURCE_LABELS = {
+  'openprd-tasks': '任务清单',
+  'project-scan': '项目扫描',
+  'openprd-knowledge': '项目经验库',
+  'openprd-knowledge-candidate': '待确认经验草案',
+  'openprd-growth-ledger': '成长记录',
+  'openprd-test-report': '测试报告',
+  'openprd-visual-review': '视觉对比记录',
+  evidence: '证据文件',
+};
+
+const EVIDENCE_PATH_LABELS = {
+  'no-active-change': '当前没有进行中的需求改动',
+  'no-cost-risk-detected': '本次没有发现成本相关风险',
+  'business-guardrails-evidence': '成本与滥用护栏证据',
+};
+
+function evidenceSourceLabel(source) {
+  return EVIDENCE_SOURCE_LABELS[source] ?? source;
+}
+
+function evidencePathLabel(path) {
+  return EVIDENCE_PATH_LABELS[path] ?? path;
+}
+
 function evidenceItems(report) {
   return evidenceRows(report)
     .filter((row) => !row.empty)
     .slice(0, 5)
     .map((row) => ({
       summary: gateDisplay(row.gate),
-      detail: `${row.source}，${row.path}`,
+      detail: `${evidenceSourceLabel(row.source)}，${evidencePathLabel(row.path)}`,
     }));
 }
 
@@ -573,8 +598,8 @@ function environmentItems(report) {
     {
       summary: '成长账本',
       detail: Number(growth.summary?.eventCount ?? 0) > 0
-        ? `已记录 ${growth.summary.eventCount} 条事件，completion checkpoint ${growth.summary.completionCheckpoints ?? 0} 条`
-        : '当前还没有成长账本事件；完成态至少应留下 checkpoint 或候选',
+        ? `已记录 ${growth.summary.eventCount} 条成长事件，其中收尾检查记录 ${growth.summary.completionCheckpoints ?? 0} 条`
+        : '当前还没有成长记录；收尾前至少应留下一条收尾检查记录或经验草案',
     },
   ];
 }
@@ -692,8 +717,8 @@ function tableRowsForEvidence(report) {
   return evidenceRows(report).map((row) => `
     <tr>
       <td>${escapeHtml(gateDisplay(row.gate))}</td>
-      <td>${escapeHtml(row.source)}</td>
-      <td><code>${escapeHtml(row.path)}</code></td>
+      <td>${escapeHtml(evidenceSourceLabel(row.source))}</td>
+      <td><code>${escapeHtml(evidencePathLabel(row.path))}</code></td>
       <td>${row.gate.required ? '本期必测' : '按风险确认'}</td>
     </tr>
   `).join('\n');