@openprd/cli 0.1.10 → 0.1.18

package/src/quality-visual-review.js

@@ -18,6 +18,15 @@ function inferVisualReviewMode(value) {
   if (normalized.includes('visual-parallel-board') || normalized.includes('parallel-board') || normalized.includes('experiment-board')) {
     return 'parallel-board';
   }
+  if (normalized.includes('visual-verification-board') || normalized.includes('verification-board') || normalized.includes('screenshot-evidence-board') || normalized.includes('screenshot-board')) {
+    return 'verification-board';
+  }
+  if (normalized.includes('visual-alignment-board') || normalized.includes('alignment-board') || normalized.includes('grid-alignment')) {
+    return 'alignment-board';
+  }
+  if (normalized.includes('visual-centering-board') || normalized.includes('centering-board') || normalized.includes('center-board')) {
+    return 'centering-board';
+  }
   if (normalized.includes('visual-before-after') || normalized.includes('before-after')) {
     return 'before-after';
   }
@@ -73,6 +82,9 @@ export async function listVisualReviewArtifacts(projectRoot) {
         metadataPath: entry.relativePath,
         mode: inferredMode,
         labels: payload.labels ?? existing.labels ?? null,
+        alignmentScope: payload.alignmentScope ?? existing.alignmentScope ?? null,
+        centering: payload.centering ?? existing.centering ?? null,
+        groups: Array.isArray(payload.groups) ? payload.groups : (existing.groups ?? null),
         generatedAt: payload.generatedAt ?? existing.generatedAt ?? null,
         mtimeMs: stat?.mtimeMs ?? existing.mtimeMs ?? 0,
       });
@@ -138,29 +150,186 @@ export function detectVisualReview({ policy, activeChangeContext, activeTasks, v
     'parallel board',
     'parallel experiment',
     'experiment board',
-    'evidence board',
     '并行实验',
     '并行方向',
     '多方向实验',
     '方案对比板',
-    '证据板',
+  ];
+  const verificationTokens = [
+    'verification board',
+    'verification-board',
+    'screenshot board',
+    'screenshot-evidence-board',
+    'visual-verification-board',
+    'computer screenshot',
+    'computer use screenshot',
+    'browser screenshot',
+    'playwright screenshot',
+    'screencapture',
+    '普通截图',
+    '实测截图',
+    '截图实测',
+    '截图证据',
+    '截图验收',
+    'Computer 实测',
+    'Browser 实测',
+    '运行态截图',
+  ];
+  const alignmentTokens = [
+    'alignment board',
+    'alignment-board',
+    'grid alignment',
+    'grid-alignment',
+    'baseline',
+    'baseline spread',
+    'same slot',
+    'repeated card',
+    'homogeneous card',
+    'list card',
+    'card grid',
+    'table layout',
+    '对齐辅助线',
+    '辅助线',
+    '网格对齐',
+    '基线',
+    '坐标偏差',
+    '同构',
+    '重复单元',
+    '相同槽位',
+    '相同文案类型',
+    '列表卡片',
+    '卡片列表',
+    '卡片网格',
+    '网格卡片',
+    '网格列表',
+    '列表网格',
+    '表格',
+    '排版对齐',
+    '排版漂移',
+    '布局漂移',
+    '对齐有问题',
+    '对齐问题',
+    '对齐不准',
+    '对不齐',
+    '不对齐',
+    '没有对齐',
+    '没对齐',
+    '左右偏差',
+    '上下偏差',
+    '横向偏差',
+    '竖向偏差',
+  ];
+  const centeringTokens = [
+    'centering board',
+    'centering-board',
+    'center board',
+    'center-board',
+    'visual-centering-board',
+    'canvas center',
+    'visual centroid',
+    'bbox center',
+    'bounding box center',
+    'active bounds',
+    'single element',
+    'inside centered',
+    'internal centering',
+    'logo center',
+    'logo centered',
+    'logo internal',
+    'icon center',
+    'icon centered',
+    'icon internal',
+    'avatar center',
+    'badge center',
+    'button graphic',
+    '内部居中',
+    '内部不居中',
+    '居中判定',
+    '居中识别',
+    '居中评估',
+    '视觉重心',
+    '主体外接框',
+    '外接框中心',
+    '画布中心',
+    '单元素',
+    '单个元素',
+    '单一元素',
+    '图标内部',
+    '图片内部',
+    '素材内部',
+    '按钮图形',
+    '偏心',
+    '不居中',
+    '没居中',
+    '左偏',
+    '右偏',
+    '上飘',
+    '下沉',
+  ];
+  const contentSlotAlignmentTokens = [
+    'content slot',
+    'internal slot',
+    'same slot',
+    'title slot',
+    'price slot',
+    'button slot',
+    'card content',
+    'repeated card',
+    'homogeneous card',
+    'list card',
+    'card grid',
+    '标题',
+    '副标题',
+    '描述',
+    '正文',
+    '标签',
+    '状态',
+    '价格',
+    '按钮',
+    '操作区',
+    '图标',
+    '内容槽位',
+    '内部槽位',
+    '相同槽位',
+    '相同文案类型',
+    '相同组件槽位',
+    '列表卡片',
+    '卡片列表',
+    '卡片网格',
+    '网格卡片',
+    '网格列表',
+    '列表网格',
   ];
   const expectsReferenceCompare = includesAny(haystack, referenceTokens);
   const expectsFocusBoard = includesAny(haystack, focusTokens);
   const expectsParallelBoard = includesAny(haystack, parallelTokens);
+  const expectsVerificationBoard = includesAny(haystack, verificationTokens);
+  const expectsAlignmentBoard = includesAny(haystack, alignmentTokens);
+  const expectsCenteringBoard = includesAny(haystack, centeringTokens);
+  const expectsContentSlotAlignment = expectsAlignmentBoard && includesAny(haystack, contentSlotAlignmentTokens);
   const referenceArtifacts = visualArtifacts.filter((artifact) => artifact.mode === 'reference-actual');
   const beforeAfterArtifacts = visualArtifacts.filter((artifact) => artifact.mode === 'before-after');
   const focusArtifacts = visualArtifacts.filter((artifact) => artifact.mode === 'focus-board');
   const parallelArtifacts = visualArtifacts.filter((artifact) => artifact.mode === 'parallel-board');
+  const verificationArtifacts = visualArtifacts.filter((artifact) => artifact.mode === 'verification-board');
+  const alignmentArtifacts = visualArtifacts.filter((artifact) => artifact.mode === 'alignment-board');
+  const centeringArtifacts = visualArtifacts.filter((artifact) => artifact.mode === 'centering-board');
+  const contentSlotAlignmentArtifacts = alignmentArtifacts.filter(hasContentSlotAlignmentEvidence);
   let matchingArtifacts;
-  if (expectsParallelBoard) {
+  if (expectsCenteringBoard) {
+    matchingArtifacts = centeringArtifacts;
+  } else if (expectsAlignmentBoard) {
+    matchingArtifacts = alignmentArtifacts;
+  } else if (expectsVerificationBoard) {
+    matchingArtifacts = verificationArtifacts;
+  } else if (expectsParallelBoard) {
     matchingArtifacts = parallelArtifacts;
   } else if (expectsFocusBoard) {
     matchingArtifacts = focusArtifacts;
   } else if (expectsReferenceCompare) {
     matchingArtifacts = referenceArtifacts;
   } else {
-    matchingArtifacts = [...referenceArtifacts, ...beforeAfterArtifacts, ...focusArtifacts, ...parallelArtifacts];
+    matchingArtifacts = [...referenceArtifacts, ...beforeAfterArtifacts, ...focusArtifacts, ...parallelArtifacts, ...verificationArtifacts, ...alignmentArtifacts, ...centeringArtifacts];
   }
   const evidenceSources = matchingArtifacts.slice(0, 12).map((artifact) => ({
     path: artifact.path,
@@ -170,15 +339,31 @@ export function detectVisualReview({ policy, activeChangeContext, activeTasks, v
         ? 'visual-review/before-after'
         : artifact.mode === 'focus-board'
           ? 'visual-review/focus-board'
-          : 'visual-review/parallel-board',
+          : artifact.mode === 'parallel-board'
+            ? 'visual-review/parallel-board'
+            : artifact.mode === 'verification-board'
+              ? 'visual-review/verification-board'
+              : artifact.mode === 'alignment-board'
+                ? 'visual-review/alignment-board'
+                : 'visual-review/centering-board',
   }));
   const warnings = [];
+  const missingContentSlotAlignment = relevant
+    && expectsContentSlotAlignment
+    && alignmentArtifacts.length > 0
+    && contentSlotAlignmentArtifacts.length === 0;
 
   if (relevant && matchingArtifacts.length === 0) {
     warnings.push(
-      expectsParallelBoard
+      expectsCenteringBoard
+        ? '检测到 logo、图标、头像、徽标、图片或按钮图形等单个元素的内部居中/视觉重心语义，但未看到本次内部居中证据板。单张截图或主观“看起来居中”不能替代画布中心、主体外接框和视觉重心偏移量测。'
+        : expectsAlignmentBoard
+        ? '检测到同构列表、卡片、网格、表格或对齐反馈语义，但未看到本次对齐辅助线证据板。新功能开发中只要有重复同构单元，也应同时量测容器轨道和内部内容槽位的坐标偏差。'
+        : expectsParallelBoard
         ? '检测到界面视觉改动且用户在比较多方向实验，但未看到本次并行实验证据板。'
-        : expectsFocusBoard
+        : expectsVerificationBoard
+          ? '检测到普通截图、Computer/Browser 实测或运行态截图语义，但未看到本次截图实测证据板。普通截图只能作为原始素材，不能单独替代视觉收口拼图。'
+          : expectsFocusBoard
           ? '检测到界面视觉改动且用户在关注局部细节，但未看到本次局部焦点证据板。'
           : expectsReferenceCompare
         ? '检测到界面视觉改动且已有参考图/设计稿语义，但未看到本次“效果图 / 实现截图”对比证据。'
@@ -190,24 +375,46 @@ export function detectVisualReview({ policy, activeChangeContext, activeTasks, v
     warnings.push('当前有视觉证据，但局部细节仍建议补一份局部焦点证据板，方便围绕编号区域复核。');
   } else if (relevant && expectsParallelBoard && parallelArtifacts.length === 0 && matchingArtifacts.length > 0) {
     warnings.push('当前有视觉证据，但多方向实验仍建议补一份并行实验证据板，把方案和指标放到同一板里审查。');
+  } else if (relevant && expectsVerificationBoard && verificationArtifacts.length === 0 && matchingArtifacts.length > 0) {
+    warnings.push('当前有视觉证据，但普通截图或 Computer 实测仍建议补一份截图实测证据板，把截图、实测路径和检查点拼到同一张图里。');
+  } else if (relevant && expectsAlignmentBoard && alignmentArtifacts.length === 0 && matchingArtifacts.length > 0) {
+    warnings.push('当前有视觉证据，但同构列表、卡片、网格或表格仍建议补一份对齐辅助线证据板，把相同槽位的 spread 放到同一张图里。');
+  } else if (relevant && expectsCenteringBoard && centeringArtifacts.length === 0 && matchingArtifacts.length > 0) {
+    warnings.push('当前有视觉证据，但单元素内部居中仍建议补一份内部居中证据板，把画布中心、主体外接框和视觉重心偏移放到同一张图里。');
+  } else if (missingContentSlotAlignment) {
+    warnings.push('当前只看到对齐辅助线证据板，但没有看到标题、副标题、描述、标签、状态、价格、按钮或图标等内部内容槽位量测。卡片/列表/网格不能只量外框、列宽或行顶。');
   }
 
   const summary = !relevant
     ? '当前场景未要求视觉评审证据'
     : matchingArtifacts.length > 0
-      ? (
-          expectsParallelBoard
+        ? (
+          missingContentSlotAlignment
+            ? '已找到对齐辅助线证据板，但缺少内部内容槽位量测'
+            : expectsCenteringBoard
+            ? `已找到 ${matchingArtifacts.length} 份内部居中证据板`
+            : expectsAlignmentBoard
+            ? `已找到 ${matchingArtifacts.length} 份对齐辅助线证据板`
+            : expectsParallelBoard
             ? `已找到 ${matchingArtifacts.length} 份并行实验证据板`
-            : expectsFocusBoard
+            : expectsVerificationBoard
+              ? `已找到 ${matchingArtifacts.length} 份截图实测证据板`
+              : expectsFocusBoard
               ? `已找到 ${matchingArtifacts.length} 份局部焦点证据板`
               : expectsReferenceCompare
             ? `已找到 ${matchingArtifacts.length} 份效果图 / 实现截图对比证据`
-            : `已找到 ${matchingArtifacts.length} 份视觉对比、局部焦点或修改前后自检证据`
+            : `已找到 ${matchingArtifacts.length} 份视觉对比、局部焦点、截图实测或修改前后自检证据`
         )
       : (
-          expectsParallelBoard
+          expectsCenteringBoard
+            ? '未找到本次内部居中证据板'
+            : expectsAlignmentBoard
+            ? '未找到本次对齐辅助线证据板'
+            : expectsParallelBoard
             ? '未找到本次并行实验证据板'
-            : expectsFocusBoard
+            : expectsVerificationBoard
+              ? '未找到本次截图实测证据板'
+              : expectsFocusBoard
               ? '未找到本次局部焦点证据板'
               : expectsReferenceCompare
             ? '未找到本次效果图 / 实现截图对比证据'
@@ -215,13 +422,19 @@ export function detectVisualReview({ policy, activeChangeContext, activeTasks, v
         );
 
   return {
-    status: !relevant || matchingArtifacts.length > 0 ? 'pass' : 'needs-evidence',
+    status: !relevant || (matchingArtifacts.length > 0 && !missingContentSlotAlignment) ? 'pass' : 'needs-evidence',
     relevant,
     expectsReferenceCompare,
     expectsFocusBoard,
     expectsParallelBoard,
+    expectsVerificationBoard,
+    expectsAlignmentBoard,
+    expectsCenteringBoard,
+    expectsContentSlotAlignment,
     artifacts: visualArtifacts,
     matchingArtifacts,
+    contentSlotAlignmentArtifacts,
+    centeringArtifacts,
     warnings,
     evidence: {
       present: matchingArtifacts.length > 0,
@@ -231,6 +444,36 @@ export function detectVisualReview({ policy, activeChangeContext, activeTasks, v
   };
 }
 
+function hasContentSlotAlignmentEvidence(artifact) {
+  const haystack = JSON.stringify([
+    artifact.path,
+    artifact.metadataPath,
+    artifact.labels,
+    artifact.alignmentScope,
+    artifact.groups,
+  ]).toLowerCase();
+  return [
+    'content-slot',
+    'content slot',
+    'internal slot',
+    '内容槽位',
+    '内部槽位',
+    '相同槽位',
+    '相同文案类型',
+    '相同组件槽位',
+    '标题',
+    '副标题',
+    '描述',
+    '正文',
+    '标签',
+    '状态',
+    '价格',
+    '按钮',
+    '操作区',
+    '图标',
+  ].some((token) => haystack.includes(String(token).toLowerCase()));
+}
+
 export {
   VISUAL_REVIEW_DIR,
   VISUAL_REVIEW_SCHEMA,

package/src/quality.js

@@ -108,13 +108,20 @@ const EVIDENCE_TOKENS = {
   'test-strategy': ['test-layer', 'test-size', 'test-scope', 'evidence-plan', 'testing pyramid', '测试策略', '测试分流', '单元测试', '集成测试', '端到端'],
   smoke: ['smoke', 'e2e', 'playwright', 'cypress', 'main flow', 'happy path', '冒烟', '主流程'],
   'feature-coverage': ['feature coverage', 'acceptance', 'tasks done', 'openprd tasks', '验收', '功能覆盖', '任务完成'],
-  'visual-review': ['visual-compare', 'visual-before-after', 'visual-focus-board', 'visual-parallel-board', 'reference-actual', 'before-after', 'focus-board', 'parallel-board', '效果图', '实现截图', '修改前', '修改后', '视觉对比', '局部焦点证据板', '并行实验证据板'],
+  'visual-review': ['visual-compare', 'visual-before-after', 'visual-focus-board', 'visual-parallel-board', 'visual-verification-board', 'visual-alignment-board', 'visual-centering-board', 'reference-actual', 'before-after', 'focus-board', 'parallel-board', 'verification-board', 'alignment-board', 'centering-board', 'center-board', '效果图', '实现截图', '修改前', '修改后', '视觉对比', '局部焦点证据板', '并行实验证据板', '截图实测证据板', '对齐辅助线证据板', '内部居中证据板', '内容槽位', '内部槽位', '视觉重心', '主体外接框', '画布中心', '偏心'],
   'normal-performance': ['performance', 'perf', 'benchmark', 'latency', 'p95', 'lighthouse', 'k6', '性能', '耗时'],
   'extreme-performance': ['extreme', 'stress', 'load test', 'large-data', 'pressure', 'k6', '压力', '极端', '大数据'],
   knowledge: ['quality learn', 'incident', 'pattern', 'skill', '复盘', '经验', '沉淀'],
   growth: ['growth ledger', 'completion checkpoint', 'openprd grow', 'workflow-gotcha', 'code-extension', '自我成长', '账本', '候选'],
 };
 
+const DIAGNOSTIC_SURFACE_LABELS = {
+  'runtime-events': '运行事件记录',
+  timeline: '问题时间线',
+  'root-cause-candidates': '根因排查线索',
+  'diagnostic-report': '诊断报告',
+};
+
 function qualityPath(projectRoot, relativePath) {
   return cjoin(projectRoot, relativePath);
 }
@@ -246,6 +253,10 @@ function defaultQualityConfig() {
       ledgerPath: OPENPRD_GROWTH_LEDGER,
       completionCheckpointRequired: true,
     },
+    reports: {
+      retentionMaxReports: 60,
+      retentionEnabled: true,
+    },
   };
 }
 
@@ -294,6 +305,10 @@ function normalizeQualityConfig(config = {}) {
       ...defaults.growth,
       ...(config.growth ?? {}),
     },
+    reports: {
+      ...defaults.reports,
+      ...(config.reports ?? {}),
+    },
   };
 }
 
@@ -435,8 +450,7 @@ async function readActiveChangeContext(projectRoot, activeChange) {
     return { activeChange: null, files: [], text: '' };
   }
   const roots = [
-    cjoin('openprd', 'changes', activeChange),
-    cjoin('openspec', 'changes', activeChange),
+    cjoin('.openprd', 'changes', activeChange),
   ];
   const files = [];
   async function walk(root, dir) {
@@ -606,18 +620,21 @@ function buildEvidenceLedger({ evidenceFiles, activeTasks, observability, busine
     };
   }
   if (observability.status === 'pass') {
-    const observabilitySignals = [
-      ...observability.centralizedTools,
-      ...(observability.diagnosticSurfaces ?? []),
-    ];
+    const toolCount = observability.centralizedTools.length;
+    const surfaceLabels = (observability.diagnosticSurfaces ?? [])
+      .map((surface) => DIAGNOSTIC_SURFACE_LABELS[surface] ?? surface);
+    const signalSummary = [
+      toolCount > 0 ? `${toolCount} 类日志或追踪工具` : '',
+      surfaceLabels.length > 0 ? `${surfaceLabels.length} 类诊断记录` : '',
+    ].filter(Boolean).join('和');
     ledger.traceability = {
       ...ledger.traceability,
       present: true,
       sources: [
         ...ledger.traceability.sources,
-        { path: 'project-observability-signals', source: observabilitySignals.join(', ') || 'observability' },
+        { path: '项目内的日志与追踪配置', source: signalSummary ? `检测到${signalSummary}` : '日志追踪检查' },
       ].slice(0, 12),
-      summary: `检测到 ${observability.correlationFields.length} 个链路关联字段${observability.diagnosticSurfaces?.length ? `；诊断面: ${observability.diagnosticSurfaces.join(', ')}` : ''}`,
+      summary: `出问题时可以追查：检测到 ${observability.correlationFields.length} 个追踪线索${surfaceLabels.length > 0 ? `，并留有${surfaceLabels.join('、')}` : ''}`,
     };
   }
   if (!businessGuardrails.riskDetected || businessGuardrails.status === 'pass') {
@@ -641,8 +658,8 @@ function buildEvidenceLedger({ evidenceFiles, activeTasks, observability, busine
         ...knowledge.candidates.slice(0, 3).map((candidate) => ({ path: candidate, source: 'openprd-knowledge-candidate' })),
       ].slice(0, 12),
       summary: knowledge.candidates.length > 0
-        ? `已有 ${knowledge.skills.length} 个项目经验 Skill，命中 ${knowledge.adoption?.totals?.hit ?? 0} / 引用 ${knowledge.adoption?.totals?.referenced ?? 0} / 注入 ${knowledge.adoption?.totals?.injected ?? 0}，另有 ${knowledge.candidates.length} 个待确认 candidate`
-        : `已有 ${knowledge.skills.length} 个项目经验 Skill，命中 ${knowledge.adoption?.totals?.hit ?? 0} / 引用 ${knowledge.adoption?.totals?.referenced ?? 0} / 注入 ${knowledge.adoption?.totals?.injected ?? 0}`,
+        ? `已沉淀 ${knowledge.skills.length} 条项目经验，近期被实际复用 ${knowledge.adoption?.totals?.referenced ?? 0} 次，另有 ${knowledge.candidates.length} 条经验草案等确认`
+        : `已沉淀 ${knowledge.skills.length} 条项目经验，近期被实际复用 ${knowledge.adoption?.totals?.referenced ?? 0} 次`,
     };
   } else if (knowledge.candidates.length > 0) {
     ledger.knowledge = {
@@ -652,7 +669,7 @@ function buildEvidenceLedger({ evidenceFiles, activeTasks, observability, busine
         ...ledger.knowledge.sources,
         ...knowledge.candidates.slice(0, 6).map((candidate) => ({ path: candidate, source: 'openprd-knowledge-candidate' })),
       ].slice(0, 12),
-      summary: `已有 ${knowledge.candidates.length} 个待确认 knowledge candidate`,
+      summary: `已有 ${knowledge.candidates.length} 条经验草案等确认，确认后会成为可复用的项目经验`,
     };
   }
   if (growth?.summary) {
@@ -666,7 +683,7 @@ function buildEvidenceLedger({ evidenceFiles, activeTasks, observability, busine
           ...ledger.growth.sources,
           { path: growth.ledgerPath ?? OPENPRD_GROWTH_LEDGER, source: 'openprd-growth-ledger' },
         ].slice(0, 12),
-        summary: `growth 账本已有 ${growth.summary.eventCount ?? 0} 条事件，其中 completion checkpoint ${completionCheckpoints} 条`,
+        summary: `成长记录已有 ${growth.summary.eventCount ?? 0} 条，其中收尾检查记录 ${completionCheckpoints} 条`,
       };
     }
   }
@@ -894,7 +911,9 @@ async function readActiveTasks(projectRoot) {
     return { activeChange: null, total: 0, done: 0, pending: 0, blocked: 0, tasks: [] };
   }
   const taskFiles = [];
-  for (const root of [cjoin('openprd', 'changes', activeChange), cjoin('openspec', 'changes', activeChange)]) {
+  for (const root of [
+    cjoin('.openprd', 'changes', activeChange),
+  ]) {
     const dir = cjoin(projectRoot, root);
     const entries = await fs.readdir(dir).catch(() => []);
     for (const entry of entries) {
@@ -1273,7 +1292,35 @@ async function buildQualityReport(projectRoot, config, options = {}) {
   };
 }
 
-async function writeReport(projectRoot, report) {
+export async function pruneQualityReports(projectRoot, retainedReports, config) {
+  const retention = config?.reports ?? {};
+  if (retention.retentionEnabled === false) {
+    return { pruned: 0 };
+  }
+  const maxReports = Number.isInteger(retention.retentionMaxReports) && retention.retentionMaxReports > 0
+    ? retention.retentionMaxReports
+    : 60;
+  const reportsDir = qualityPath(projectRoot, QUALITY_REPORTS_DIR);
+  const entries = await fs.readdir(reportsDir).catch(() => []);
+  const keepBases = new Set(
+    retainedReports.slice(0, maxReports).map((item) => String(item.reportId ?? '').replace(/[^a-zA-Z0-9._-]/g, '_')),
+  );
+  let pruned = 0;
+  for (const name of entries) {
+    const match = name.match(/^(eval-[a-zA-Z0-9._-]+)\.(json|html)$/);
+    if (!match) {
+      continue;
+    }
+    if (keepBases.has(match[1])) {
+      continue;
+    }
+    await fs.rm(cjoin(reportsDir, name), { force: true }).catch(() => {});
+    pruned += 1;
+  }
+  return { pruned };
+}
+
+async function writeReport(projectRoot, report, config = null) {
   await ensureQualityDirs(projectRoot);
   const reportBase = report.id.replace(/[^a-zA-Z0-9._-]/g, '_');
   const jsonPath = qualityPath(projectRoot, cjoin(QUALITY_REPORTS_DIR, `${reportBase}.json`));
@@ -1294,7 +1341,8 @@ async function writeReport(projectRoot, report) {
     ...(Array.isArray(index.reports) ? index.reports.filter((item) => item.reportId !== report.id) : []),
   ].slice(0, 100);
   await writeJson(indexPath, { version: 1, updatedAt: timestamp(), reports });
-  return { jsonPath, htmlPath, indexPath };
+  const retention = await pruneQualityReports(projectRoot, reports, config ?? normalizeQualityConfig());
+  return { jsonPath, htmlPath, indexPath, prunedReports: retention.pruned };
 }
 
 export async function initQualityWorkspace(projectRoot, options = {}) {
@@ -1339,7 +1387,7 @@ export async function verifyQualityWorkspace(projectRoot, options = {}) {
   await ensureQualityDirs(projectRoot);
   const initialReport = await buildQualityReport(projectRoot, config);
   let report = initialReport;
-  let paths = await writeReport(projectRoot, report);
+  let paths = await writeReport(projectRoot, report, config);
   const knowledgeSignal = {
     kind: 'quality-verify',
     ok: report.readiness.productionReady,
@@ -1398,7 +1446,7 @@ export async function verifyQualityWorkspace(projectRoot, options = {}) {
       reason: 'reusable-knowledge-artifact-already-exists',
     };
   report = await buildQualityReport(projectRoot, config, { reportId: initialReport.id });
-  paths = await writeReport(projectRoot, report);
+  paths = await writeReport(projectRoot, report, config);
   const strict = options.strict === true;
   const blocking = (strict || config.enforcement === 'blocking') && !report.readiness.productionReady;
   const featureCoverageOnly = report.readiness.failingGates.length === 0

package/src/review-presentation.js

@@ -48,6 +48,32 @@ export const REVIEW_PRESENTATION_TEMPLATE = {
       USER_CHANGE_SUMMARY_GUIDE.panelExamples.risk,
     ],
   },
+  designDirections: {
+    note: '可选；只有需求涉及界面/页面/交互时提供。先用 imagegen 生成 3 个差异足够大的交互稿，把图片放到 .openprd/design/active/ 后写入路径；不涉及界面时删除本字段。',
+    directions: [
+      {
+        id: 'direction-1',
+        title: '15 字以内方向名',
+        image: '.openprd/design/active/direction-1.png',
+        summary: '30 字以内一句话说明这个方向的核心体验',
+        tradeoff: '30 字以内说明取舍或适用场景',
+      },
+      {
+        id: 'direction-2',
+        title: '15 字以内方向名',
+        image: '.openprd/design/active/direction-2.png',
+        summary: '30 字以内一句话说明这个方向的核心体验',
+        tradeoff: '30 字以内说明取舍或适用场景',
+      },
+      {
+        id: 'direction-3',
+        title: '15 字以内方向名',
+        image: '.openprd/design/active/direction-3.png',
+        summary: '30 字以内一句话说明这个方向的核心体验',
+        tradeoff: '30 字以内说明取舍或适用场景',
+      },
+    ],
+  },
 };
 
 export function buildReviewPresentationTemplatePayload() {
@@ -182,6 +208,39 @@ function stableStringify(value) {
   return JSON.stringify(value);
 }
 
+const ACTIVE_ARTIFACT_RETAIN_VERSIONS = 12;
+
+export async function archiveStaleActiveArtifacts(projectRoot, options = {}) {
+  const retain = Number.isInteger(options.retain) && options.retain > 0
+    ? options.retain
+    : ACTIVE_ARTIFACT_RETAIN_VERSIONS;
+  const activeDir = path.join(projectRoot, '.openprd', 'artifacts', 'active');
+  const archiveDir = path.join(projectRoot, '.openprd', 'artifacts', 'archive');
+  const entries = await fs.readdir(activeDir, { withFileTypes: true }).catch(() => []);
+  const versioned = entries
+    .filter((entry) => entry.isDirectory() && /^v\d{4}-/.test(entry.name))
+    .map((entry) => entry.name)
+    .sort();
+  const stale = versioned.slice(0, Math.max(0, versioned.length - retain));
+  if (stale.length === 0) {
+    return { archived: [] };
+  }
+  await fs.mkdir(archiveDir, { recursive: true });
+  const archived = [];
+  for (const name of stale) {
+    const from = path.join(activeDir, name);
+    const to = path.join(archiveDir, name);
+    try {
+      await fs.rm(to, { recursive: true, force: true });
+      await fs.rename(from, to);
+      archived.push(name);
+    } catch {
+      // 归档失败不阻断评审生成
+    }
+  }
+  return { archived };
+}
+
 async function renderValidatedReviewPresentation(projectRoot, snapshot) {
   const workspaceRoot = path.join(projectRoot, '.openprd');
   const canonicalReview = canonicalReviewPath({ workspaceRoot }, snapshot.versionId);
@@ -191,6 +250,7 @@ async function renderValidatedReviewPresentation(projectRoot, snapshot) {
     snapshot,
     projectRelease: buildReleaseLedgerSummary(releaseLedger.ledger),
   }));
+  await archiveStaleActiveArtifacts(projectRoot).catch(() => null);
 
   const versionIndexPath = path.join(workspaceRoot, 'state', 'version-index.json');
   const versionIndex = await readJson(versionIndexPath);