@openprd/cli 0.1.10 → 0.1.18

package/src/discovery.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { analyzePrdSnapshot, buildPrdSnapshot, formatVersionId } from './prd-core.js';
 import { formatProductTypeDisplay } from './product-type-copy.js';
 import { analyzeOpenSpecTaskVolumes } from './openspec/tasks.js';
-import { legacyOpenSpecDiscoveryDir, openPrdDiscoveryDir, readDiscoveryConfig } from './openspec/paths.js';
+import { openPrdDiscoveryDir, readDiscoveryConfig } from './openspec/paths.js';
 import { appendJsonl, cjoin, exists, readJson, readJsonl, writeJson, writeText } from './fs-utils.js';
 import { collectSourceInventory, shouldIgnoreSourceDirectory } from './source-inventory.js';
 import { compactTimestamp, timestamp } from './time.js';
@@ -391,13 +391,7 @@ async function openspecDiscoveryWorkspaceImpl(projectRoot, options = {}, depende
 }
 
 async function loadOpenSpecDiscoveryRun(projectRoot) {
-  let discoveryRoot = openPrdDiscoveryDir(projectRoot);
-  if (!(await exists(cjoin(discoveryRoot, 'current.json')))) {
-    const legacyRoot = legacyOpenSpecDiscoveryDir(projectRoot);
-    if (await exists(cjoin(legacyRoot, 'current.json'))) {
-      discoveryRoot = legacyRoot;
-    }
-  }
+  const discoveryRoot = openPrdDiscoveryDir(projectRoot);
   const currentPath = cjoin(discoveryRoot, 'current.json');
   if (!(await exists(currentPath))) {
     throw new Error(`Missing OpenPrd discovery state: ${currentPath}`);

package/src/docs-compact.js

@@ -0,0 +1,125 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  DOC_MEGA_LINE_CHARS,
+  DOC_STALE_VERSION_THRESHOLD,
+  STANDARD_DOCS,
+  STANDARD_DOCS_ROOT,
+  analyzeDocQuality,
+  analyzeDocStaleness,
+} from './standards.js';
+
+const PREVIEW_CHARS = 80;
+const MAX_LINE_SUGGESTIONS_PER_DOC = 8;
+
+function lineSuggestion(lineNumber, line) {
+  const preview = Array.from(line.trim()).slice(0, PREVIEW_CHARS).join('');
+  const separators = (line.match(/[；;。]/gu) ?? []).length;
+  const hint = separators >= 2
+    ? `含 ${separators + 1} 个句段，建议拆成分点列表（每点一行）`
+    : '建议拆成小节或分点，删除重复叙述';
+  return {
+    line: lineNumber,
+    chars: Array.from(line).length,
+    preview: `${preview}…`,
+    hint,
+  };
+}
+
+export async function docsCompactWorkspace(projectRoot, options = {}) {
+  const resolvedRoot = path.resolve(projectRoot);
+  const docs = [];
+  let totalMegaLines = 0;
+
+  for (const doc of STANDARD_DOCS) {
+    const docPath = path.join(resolvedRoot, STANDARD_DOCS_ROOT, doc.fileName);
+    const text = await fs.readFile(docPath, 'utf8').catch(() => null);
+    if (text === null) {
+      continue;
+    }
+    const relativePath = path.relative(resolvedRoot, docPath);
+    const quality = analyzeDocQuality(relativePath, text);
+    const lines = text.split('\n');
+    const suggestions = [];
+    lines.forEach((line, index) => {
+      if (Array.from(line).length > DOC_MEGA_LINE_CHARS && suggestions.length < MAX_LINE_SUGGESTIONS_PER_DOC) {
+        suggestions.push(lineSuggestion(index + 1, line));
+      }
+    });
+    totalMegaLines += quality.megaLines;
+
+    const entry = {
+      ...quality,
+      suggestions,
+      status: quality.megaLines > 0 ? 'needs-compaction' : 'ok',
+    };
+
+    if (doc.fileName === 'prd.md') {
+      const stat = await fs.stat(docPath).catch(() => null);
+      if (stat) {
+        const staleness = await analyzeDocStaleness(resolvedRoot, stat.mtimeMs);
+        entry.versionsBehind = staleness.versionsBehind;
+        entry.totalVersions = staleness.totalVersions;
+        if (staleness.versionsBehind > DOC_STALE_VERSION_THRESHOLD) {
+          entry.status = entry.status === 'needs-compaction' ? 'needs-compaction-and-backfill' : 'needs-backfill';
+        }
+      }
+    }
+
+    docs.push(entry);
+  }
+
+  const needsAttention = docs.filter((doc) => doc.status !== 'ok');
+  const recommendations = [];
+  if (needsAttention.length > 0) {
+    recommendations.push('压缩原则：同一事实只保留一处最新版本；把巨行拆成分点；过时段落直接删除而不是追加“更新：”。');
+    recommendations.push('压缩后运行 openprd standards . --verify 确认警告消除，再运行 openprd dev-check . 收口。');
+  }
+  for (const doc of needsAttention) {
+    if (doc.status.includes('backfill')) {
+      recommendations.push(`${doc.path}: 已落后 ${doc.versionsBehind} 个 requirement 版本，需要按最新已确认需求回填基线，再删除已失效内容。`);
+    }
+    if (doc.megaLines > 0) {
+      recommendations.push(`${doc.path}: ${doc.megaLines} 行巨行（阈值 ${DOC_MEGA_LINE_CHARS} 字符），按 suggestions 列出的行号拆分。`);
+    }
+  }
+
+  return {
+    ok: true,
+    action: 'docs-compact',
+    projectRoot: resolvedRoot,
+    docsRoot: STANDARD_DOCS_ROOT,
+    analyzedDocs: docs.length,
+    docsNeedingAttention: needsAttention.length,
+    totalMegaLines,
+    docs,
+    recommendations,
+  };
+}
+
+export function printDocsCompactResult(result, json) {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`docs/basic 压缩体检: ${result.docsNeedingAttention === 0 ? '健康' : `${result.docsNeedingAttention} 个文档需要处理`}`);
+  console.log(`- 已分析文档: ${result.analyzedDocs}`);
+  console.log(`- 巨行总数（> ${DOC_MEGA_LINE_CHARS} 字符）: ${result.totalMegaLines}`);
+  for (const doc of result.docs) {
+    if (doc.status === 'ok') {
+      console.log(`- ${doc.path}: 健康（${doc.lines} 行，平均 ${doc.avgLineChars} 字符/行）`);
+      continue;
+    }
+    console.log(`- ${doc.path}: ${doc.status}（${doc.lines} 行，巨行 ${doc.megaLines}，最长 ${doc.maxLineChars} 字符${doc.versionsBehind != null ? `，落后 ${doc.versionsBehind} 版本` : ''}）`);
+    for (const suggestion of doc.suggestions) {
+      console.log(`  · L${suggestion.line}（${suggestion.chars} 字符）: ${suggestion.preview}`);
+      console.log(`    ${suggestion.hint}`);
+    }
+  }
+  if (result.recommendations.length > 0) {
+    console.log('建议:');
+    for (const item of result.recommendations) {
+      console.log(`- ${item}`);
+    }
+  }
+}

package/src/execution-strategy.js

@@ -85,7 +85,7 @@ function inferParallelGroup(text, type, phase) {
 
 function inferWriteScope(parallelGroup) {
   const scopeByGroup = {
-    governance: ['openprd/changes/**', '.openprd/**'],
+    governance: ['.openprd/changes/**', '.openprd/**'],
     contracts: ['src/**', 'test/**', 'docs/basic/backend-structure.md'],
     domain: ['src/**', 'test/**'],
     surface: ['src/cli/**', 'src/**', 'test/**'],

package/src/fleet.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { cjoin, exists, writeJson } from './fs-utils.js';
+import { hasLegacyOpenPrdArtifacts } from './openspec/migration.js';
 import { SOURCE_INVENTORY_IGNORE_DIRS } from './source-inventory.js';
 import { timestamp } from './time.js';
 import { readWorkspaceRegistry, upsertWorkspaceRegistryEntry } from './workspace-registry.js';
@@ -33,6 +34,7 @@ const FLEET_PROJECT_MARKERS = [
   'Makefile',
 ];
 const FLEET_AGENT_MARKERS = ['.codex', '.claude', '.cursor', 'AGENTS.md', 'CLAUDE.md'];
+const FLEET_LEGACY_OPENPRD_MARKER = 'openprd-legacy-artifacts';
 
 function normalizeCsvList(value) {
   if (!value) {
@@ -73,7 +75,7 @@ function pathWithinRoot(rootPath, candidatePath) {
 }
 
 function classifyFleetMarkers(markers) {
-  if (markers.includes('.openprd')) {
+  if (markers.includes('.openprd') || markers.includes(FLEET_LEGACY_OPENPRD_MARKER)) {
     return 'openprd-workspace';
   }
   if (markers.some((marker) => FLEET_AGENT_MARKERS.includes(marker))) {
@@ -107,7 +109,11 @@ function plannedFleetAction(category, options) {
 async function detectFleetMarkers(projectPath) {
   const entries = await fs.readdir(projectPath, { withFileTypes: true }).catch(() => []);
   const names = new Set(entries.map((entry) => entry.name));
-  return FLEET_PROJECT_MARKERS.filter((marker) => names.has(marker));
+  const markers = FLEET_PROJECT_MARKERS.filter((marker) => names.has(marker));
+  if (!markers.includes('.openprd') && await hasLegacyOpenPrdArtifacts(projectPath)) {
+    markers.push(FLEET_LEGACY_OPENPRD_MARKER);
+  }
+  return markers;
 }
 
 async function scanFleetProjects(rootPath, options = {}) {
@@ -199,7 +205,7 @@ async function collectRegistryFleetScope(rootPath, options, registry) {
       path: entry.workspaceRoot,
       relativePath: path.relative(root, entry.workspaceRoot) || '.',
       category: 'openprd-workspace',
-      markers: ['.openprd'],
+      markers: ['.openprd', ...(await hasLegacyOpenPrdArtifacts(entry.workspaceRoot) ? [FLEET_LEGACY_OPENPRD_MARKER] : [])],
       discoverySource: 'registry',
       registryKnown: true,
       registryEntry: entry,

package/src/guide.js

@@ -0,0 +1,227 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const PLACEHOLDER_TEXT = /^待(补充|澄清|确认)/u;
+
+export const GUIDE_STAGES = [
+  {
+    id: 'clarify',
+    title: '需求澄清',
+    description: '把要解决的问题、目标用户和这次的目标讲清楚。',
+    nextAction: '把想法直接告诉 Agent：要解决什么问题、给谁用、这次想达成什么。Agent 会用 openprd capture 记录下来。',
+  },
+  {
+    id: 'draft',
+    title: '需求摘要',
+    description: '把已确认的信息整理成一份可评审的 PRD 草稿。',
+    nextAction: '让 Agent 运行 openprd synthesize，生成 PRD 草稿和评审页面。',
+  },
+  {
+    id: 'review',
+    title: '评审确认',
+    description: '打开 review.html，逐块确认主流程、功能、护栏和风险。',
+    nextAction: '打开评审页面逐块看完，用底部按钮告诉 Agent「认可并继续」或「需要调整」。',
+  },
+  {
+    id: 'direction',
+    title: '交互方向选择',
+    description: '界面类需求会给出 2 到 4 个交互稿方向，选定一个再继续。',
+    nextAction: '在评审页面或画布里比较各方向，点「选这个方向」把选择发回 Agent。',
+  },
+  {
+    id: 'tasks',
+    title: '任务拆解',
+    description: '把已确认的需求拆成一份带验证要求的任务清单。',
+    nextAction: '让 Agent 运行 openprd change . --generate 生成变更提案和任务清单。',
+  },
+  {
+    id: 'build',
+    title: '实现执行',
+    description: 'Agent 按任务清单实现，每个任务完成后留下验证证据。',
+    nextAction: '让 Agent 按任务清单继续实现；你可以随时问「现在做到哪一步了」。',
+  },
+  {
+    id: 'wrapup',
+    title: '验证收口',
+    description: '运行质量门禁，确认全部任务完成且验证通过。',
+    nextAction: '让 Agent 运行 openprd quality . --verify 和 openprd run . --verify 收口。',
+  },
+];
+
+async function readJson(filePath) {
+  const text = await fs.readFile(filePath, 'utf8').catch(() => null);
+  if (text === null) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function taskProgressFromMarkdown(text) {
+  const done = (text.match(/^\s*-\s*\[x\]/gim) ?? []).length;
+  const open = (text.match(/^\s*-\s*\[ \]/gim) ?? []).length;
+  return { done, total: done + open };
+}
+
+async function latestQualityReadiness(projectRoot) {
+  const reportsDir = path.join(projectRoot, '.openprd', 'quality', 'reports');
+  const entries = await fs.readdir(reportsDir).catch(() => []);
+  const evalReports = entries.filter((name) => name.startsWith('eval-') && name.endsWith('.json')).sort();
+  if (evalReports.length === 0) return null;
+  const latest = await readJson(path.join(reportsDir, evalReports[evalReports.length - 1]));
+  return latest?.readiness ?? null;
+}
+
+export async function guideWorkspace(projectRoot) {
+  const resolvedRoot = path.resolve(projectRoot);
+  const stateDir = path.join(resolvedRoot, '.openprd', 'state');
+  const current = await readJson(path.join(stateDir, 'current.json'));
+  const changesState = await readJson(path.join(stateDir, 'changes.json'));
+
+  const problemStatement = String(current?.problemStatement ?? '').trim();
+  const clarified = problemStatement.length > 0 && !PLACEHOLDER_TEXT.test(problemStatement);
+
+  const prdVersion = Number(current?.prdVersion ?? 0);
+  const drafted = clarified && prdVersion >= 1;
+
+  const reviewStatus = current?.reviewStatus ?? null;
+  const reviewConfirmed = drafted && reviewStatus?.status === 'confirmed';
+
+  let designDirections = null;
+  const versionId = reviewStatus?.versionId ?? null;
+  if (versionId) {
+    const snapshot = await readJson(path.join(stateDir, 'versions', `${versionId}.json`));
+    const block = snapshot?.reviewPresentation?.designDirections;
+    if (block && Array.isArray(block.directions) && block.directions.length > 0) {
+      designDirections = block.directions;
+    }
+  }
+  const directionApplicable = designDirections !== null;
+  const directionChosen = Boolean(reviewStatus?.designDirection?.id);
+
+  const activeChange = changesState?.activeChange ?? null;
+  let taskProgress = null;
+  if (activeChange) {
+    const tasksText = await fs.readFile(
+      path.join(resolvedRoot, '.openprd', 'changes', activeChange, 'tasks.md'),
+      'utf8',
+    ).catch(() => null);
+    if (tasksText !== null) {
+      taskProgress = taskProgressFromMarkdown(tasksText);
+    }
+  }
+  const tasksReady = reviewConfirmed && taskProgress !== null && taskProgress.total > 0;
+  const buildDone = tasksReady && taskProgress.done === taskProgress.total;
+
+  const readiness = await latestQualityReadiness(resolvedRoot);
+  const wrappedUp = buildDone && readiness?.productionReady === true;
+
+  const completion = {
+    clarify: clarified,
+    draft: drafted,
+    review: reviewConfirmed,
+    direction: directionApplicable ? directionChosen : null,
+    tasks: tasksReady,
+    build: buildDone,
+    wrapup: wrappedUp,
+  };
+
+  const stages = [];
+  let currentStage = null;
+  for (let index = 0; index < GUIDE_STAGES.length; index += 1) {
+    const spec = GUIDE_STAGES[index];
+    const completed = completion[spec.id];
+    let status;
+    if (spec.id === 'direction' && !directionApplicable) {
+      status = 'skipped';
+    } else if (completed) {
+      status = 'done';
+    } else if (currentStage === null) {
+      status = 'current';
+      currentStage = spec.id;
+    } else {
+      status = 'pending';
+    }
+
+    let detail = null;
+    if (spec.id === 'clarify' && clarified) {
+      detail = '问题定义已记录。';
+    } else if (spec.id === 'draft' && drafted) {
+      detail = `已生成第 ${prdVersion} 版需求摘要。`;
+    } else if (spec.id === 'review' && reviewStatus) {
+      detail = reviewConfirmed ? `评审版本 ${versionId} 已确认。` : `评审版本 ${versionId} 等待确认。`;
+    } else if (spec.id === 'direction') {
+      if (!directionApplicable) {
+        detail = '本次需求不涉及界面方向选择，自动跳过。';
+      } else if (directionChosen) {
+        detail = `已选定方向「${reviewStatus.designDirection.title ?? reviewStatus.designDirection.id}」。`;
+      } else {
+        detail = `${designDirections.length} 个交互方向等待选择。`;
+      }
+    } else if (spec.id === 'tasks' && activeChange && taskProgress) {
+      detail = `变更 ${activeChange} 已有 ${taskProgress.total} 个任务。`;
+    } else if (spec.id === 'build' && taskProgress) {
+      detail = `任务进度 ${taskProgress.done}/${taskProgress.total}。`;
+    } else if (spec.id === 'wrapup' && readiness && buildDone) {
+      detail = readiness.productionReady ? '质量门禁已通过。' : '质量门禁尚未全部通过。';
+    }
+
+    stages.push({
+      id: spec.id,
+      index: index + 1,
+      title: spec.title,
+      description: spec.description,
+      status,
+      detail,
+    });
+  }
+
+  if (currentStage === null) {
+    currentStage = 'wrapup';
+  }
+  const currentSpec = GUIDE_STAGES.find((spec) => spec.id === currentStage);
+  const currentEntry = stages.find((stage) => stage.id === currentStage);
+
+  return {
+    ok: true,
+    action: 'guide',
+    projectRoot: resolvedRoot,
+    totalStages: GUIDE_STAGES.length,
+    currentStage: {
+      id: currentStage,
+      index: currentEntry?.index ?? GUIDE_STAGES.length,
+      title: currentSpec?.title ?? '验证收口',
+    },
+    nextAction: currentEntry?.status === 'done' ? '全部阶段已完成，可以开始下一个需求。' : currentSpec?.nextAction ?? null,
+    reviewPath: reviewStatus?.entryPath ?? reviewStatus?.reviewPath ?? null,
+    stages,
+  };
+}
+
+export function printGuideResult(result, json) {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`OpenPrd 流程指引: 第 ${result.currentStage.index}/${result.totalStages} 步 · ${result.currentStage.title}`);
+  for (const stage of result.stages) {
+    const marker = stage.status === 'done'
+      ? '[完成]'
+      : stage.status === 'current'
+        ? '[当前]'
+        : stage.status === 'skipped'
+          ? '[跳过]'
+          : '[待办]';
+    console.log(`${marker} ${stage.index}. ${stage.title} — ${stage.description}`);
+    if (stage.detail) {
+      console.log(`       ${stage.detail}`);
+    }
+  }
+  if (result.nextAction) {
+    console.log(`下一步: ${result.nextAction}`);
+  }
+  if (result.reviewPath) {
+    console.log(`评审页面: ${result.reviewPath}`);
+  }
+}