@openprd/cli 0.1.0 → 0.1.8

package/src/quality.js

@@ -2,10 +2,21 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { cjoin, exists, readJson, readText, writeJson, writeText } from './fs-utils.js';
 import { renderQualityEvalArtifact } from './html-artifacts.js';
+import { parseOpenSpecTaskDeps } from './openspec/tasks.js';
 import { renderExperienceSkill, resolveQualityLearningSource } from './quality-learning.js';
 import {
+  detectTestStrategyCapabilities,
+  summarizeTaskTestStrategies,
+} from './test-strategy.js';
+import {
+  detectVisualReview,
+  listVisualReviewArtifacts,
+} from './quality-visual-review.js';
+import {
+  buildKnowledgeAdoptionSummary,
   deriveKnowledgeNames,
   ensureKnowledgeWorkspace,
+  listKnowledgeCandidates,
   KNOWLEDGE_CANDIDATES_DIR,
   KNOWLEDGE_DRAFTS_DIR,
   markKnowledgeCandidatePromoted,
@@ -13,6 +24,10 @@ import {
   recordKnowledgeReviewSignal,
   reviewKnowledgeWorkspace,
 } from './knowledge.js';
+import {
+  OPENPRD_GROWTH_LEDGER,
+  recordGrowthCheckpointWorkspace,
+} from './growth.js';
 import { timestamp } from './time.js';
 
 const QUALITY_DIR = cjoin('.openprd', 'quality');
@@ -74,11 +89,14 @@ const QUALITY_GATE_IDS = [
   'traceability',
   'redaction',
   'business-guardrails',
+  'test-strategy',
   'smoke',
   'feature-coverage',
+  'visual-review',
   'normal-performance',
   'extreme-performance',
   'knowledge',
+  'growth',
 ];
 
 const EVIDENCE_EXTENSIONS = new Set(['.json', '.md', '.txt', '.log', '.xml', '.html', '.csv']);
@@ -87,11 +105,14 @@ const EVIDENCE_TOKENS = {
   traceability: ['trace_id', 'span_id', 'request_id', 'task_id', 'error_id', 'trace verified', '链路', '追踪'],
   redaction: ['redaction', 'redact', 'mask', 'masked', 'pii', 'secret', 'token redacted', '脱敏', '敏感字段'],
   'business-guardrails': ['quota', 'rate limit', 'abuse', 'budget', 'kill switch', 'cost_usd', '额度', '限流', '滥用', '止损'],
+  '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', '效果图', '实现截图', '修改前', '修改后', '视觉对比', '局部焦点证据板', '并行实验证据板'],
   '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', '自我成长', '账本', '候选'],
 };
 
 function qualityPath(projectRoot, relativePath) {
@@ -126,6 +147,7 @@ function defaultQualityConfig() {
       currentEvidenceRequired: true,
       evidenceSources: [
         '.openprd/harness/test-reports',
+        '.openprd/harness/visual-reviews',
         '.openprd/quality/evidence',
         'test-results',
         'tests/reports',
@@ -133,8 +155,8 @@ function defaultQualityConfig() {
       ],
       scenarioProfiles: {
         core: ['smoke', 'feature-coverage'],
-        frontend: ['smoke'],
-        desktop: ['smoke'],
+        frontend: ['smoke', 'visual-review'],
+        desktop: ['smoke', 'visual-review'],
         backend: ['smoke', 'traceability'],
         businessCost: ['business-guardrails'],
         security: ['redaction'],
@@ -219,6 +241,11 @@ function defaultQualityConfig() {
       draftDir: '.openprd/knowledge/drafts',
       abstractionRequired: true,
     },
+    growth: {
+      enabled: true,
+      ledgerPath: OPENPRD_GROWTH_LEDGER,
+      completionCheckpointRequired: true,
+    },
   };
 }
 
@@ -263,6 +290,10 @@ function normalizeQualityConfig(config = {}) {
       ...defaults.knowledge,
       ...(config.knowledge ?? {}),
     },
+    growth: {
+      ...defaults.growth,
+      ...(config.growth ?? {}),
+    },
   };
 }
 
@@ -481,7 +512,32 @@ function detectScenarioTags({ activeChangeContext, activeTasks, businessGuardrai
   return [...tags];
 }
 
-function buildQualityPolicy({ config, activeChangeContext, activeTasks, businessGuardrails }) {
+function isSubstantiveCompletionFile(relativePath) {
+  const normalized = String(relativePath ?? '').split(path.sep).join('/');
+  if (!normalized) {
+    return false;
+  }
+  if (/^(src|app|lib|server|scripts|test|tests|templates)\//.test(normalized)) {
+    return true;
+  }
+  return ['package.json', 'README.md', 'AGENTS.md'].includes(normalized);
+}
+
+function detectCompletionState({ files, activeTasks, evidenceFiles }) {
+  const substantiveFiles = files.filter((file) => isSubstantiveCompletionFile(file.path));
+  const hasEvidence = evidenceFiles.length > 0;
+  const activeTaskLedgerSettled = !activeTasks.activeChange || Number(activeTasks.pending ?? 0) === 0;
+  const postCompletionRequired = substantiveFiles.length > 0 && hasEvidence && activeTaskLedgerSettled;
+  return {
+    postCompletionRequired,
+    substantiveFiles: substantiveFiles.slice(0, 12).map((file) => file.path),
+    substantiveFileCount: substantiveFiles.length,
+    activeTaskLedgerSettled,
+    hasEvidence,
+  };
+}
+
+function buildQualityPolicy({ config, activeChangeContext, activeTasks, businessGuardrails, completionState }) {
   const scenarioTags = detectScenarioTags({ activeChangeContext, activeTasks, businessGuardrails });
   const profiles = config.evalHarness.scenarioProfiles ?? defaultQualityConfig().evalHarness.scenarioProfiles;
   const required = new Set();
@@ -508,6 +564,14 @@ function buildQualityPolicy({ config, activeChangeContext, activeTasks, business
   if (!config.knowledge.enabled) {
     required.delete('knowledge');
   }
+  if (completionState?.postCompletionRequired) {
+    if (config.knowledge.enabled) {
+      required.add('knowledge');
+    }
+    if (config.growth?.enabled && config.growth?.completionCheckpointRequired !== false) {
+      required.add('growth');
+    }
+  }
   return {
     scenarioTags,
     requiredGates: QUALITY_GATE_IDS.filter((gate) => required.has(gate)),
@@ -516,7 +580,7 @@ function buildQualityPolicy({ config, activeChangeContext, activeTasks, business
   };
 }
 
-function buildEvidenceLedger({ evidenceFiles, activeTasks, observability, businessGuardrails, knowledge }) {
+function buildEvidenceLedger({ evidenceFiles, activeTasks, observability, businessGuardrails, knowledge, growth, visualReview }) {
   const ledger = Object.fromEntries(QUALITY_GATE_IDS.map((gate) => {
     const tokens = EVIDENCE_TOKENS[gate] ?? [];
     const matches = evidenceFiles
@@ -577,8 +641,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.candidates.length} 个待确认 candidate`
-        : `已有 ${knowledge.skills.length} 个项目经验 Skill`,
+        ? `已有 ${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}`,
     };
   } else if (knowledge.candidates.length > 0) {
     ledger.knowledge = {
@@ -591,9 +655,44 @@ function buildEvidenceLedger({ evidenceFiles, activeTasks, observability, busine
       summary: `已有 ${knowledge.candidates.length} 个待确认 knowledge candidate`,
     };
   }
+  if (growth?.summary) {
+    const lifecycleCount = Number(growth.summary.lifecycleCount ?? 0);
+    const completionCheckpoints = Number(growth.summary.completionCheckpoints ?? 0);
+    if (lifecycleCount > 0 || completionCheckpoints > 0) {
+      ledger.growth = {
+        ...ledger.growth,
+        present: true,
+        sources: [
+          ...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} 条`,
+      };
+    }
+  }
+  if (visualReview?.evidence) {
+    ledger['visual-review'] = {
+      ...ledger['visual-review'],
+      ...visualReview.evidence,
+    };
+  }
   return ledger;
 }
 
+function describeFeatureCoverageLedger(activeTasks = {}) {
+  const total = Number(activeTasks.total ?? 0);
+  const done = Number(activeTasks.done ?? 0);
+  const pending = Number(activeTasks.pending ?? 0);
+  const blocked = Number(activeTasks.blocked ?? 0);
+  if (pending <= 0) {
+    return null;
+  }
+  const progress = total > 0 ? `${done}/${total}` : `${done}`;
+  const changeLabel = activeTasks.activeChange ? `当前变更 ${activeTasks.activeChange}` : '当前任务账本';
+  const blockedText = blocked > 0 ? `，其中 ${blocked} 个因依赖阻塞` : '';
+  return `${changeLabel} 仍有 ${pending} 个未完成任务（已完成 ${progress}${blockedText}）。这通常表示任务账本尚未收口或覆盖证据未补齐，不等于当前实现失败。`;
+}
+
 function detectObservability({ config, files, texts, packageJson }) {
   const { dependencyNames } = packageSignals(packageJson);
   const haystack = [
@@ -667,6 +766,8 @@ function detectEvalHarness({ config, files, texts, packageJson, activeTasks }) {
   const scriptEntries = Object.entries(scripts);
   const commandText = scriptEntries.map(([name, command]) => `${name}: ${command}`).join('\n');
   const hasTest = scriptEntries.some(([name]) => /(^|:)(test|check)$/.test(name)) || includesAny(commandText, ['node --test', 'vitest', 'jest', 'pytest']);
+  const testStrategy = summarizeTaskTestStrategies(activeTasks.tasks ?? []);
+  const testCapabilities = detectTestStrategyCapabilities({ scripts, files, dependencyNames });
   const smokeCommands = scriptEntries
     .filter(([name, command]) => /smoke|e2e|playwright|cypress|test:ui/i.test(`${name} ${command}`))
     .map(([name, command]) => `${name}: ${command}`);
@@ -693,11 +794,17 @@ function detectEvalHarness({ config, files, texts, packageJson, activeTasks }) {
     warnings.push('未检测到极端数据 fixtures 或压力场景数据。');
   }
   if (activeTasks.total > 0 && activeTasks.pending > 0) {
-    warnings.push(`当前任务清单仍有 ${activeTasks.pending} 个未完成条目，功能覆盖不能判定为完整。`);
+    warnings.push(describeFeatureCoverageLedger(activeTasks) ?? `当前任务清单仍有 ${activeTasks.pending} 个未完成条目，功能覆盖不能判定为完整。`);
   }
+  warnings.push(...testStrategy.warnings);
   return {
     status: hasSmoke && hasPerf && hasExtremeFixtures && activeTasks.pending === 0 ? 'pass' : 'needs-attention',
     hasUnitOrCommandTests: hasTest,
+    testStrategy: {
+      status: testStrategy.total === 0 || testStrategy.warnings.length > 0 ? 'needs-attention' : 'pass',
+      ...testStrategy,
+      capabilities: testCapabilities,
+    },
     smoke: {
       present: hasSmoke,
       commands: smokeCommands,
@@ -800,28 +907,65 @@ async function readActiveTasks(projectRoot) {
   for (const relativePath of taskFiles) {
     const text = await readText(cjoin(projectRoot, relativePath)).catch(() => '');
     const lines = text.split(/\r?\n/);
+    let currentTask = null;
     for (let index = 0; index < lines.length; index += 1) {
       const match = lines[index].match(/^\s*-\s+\[([ xX~-])\]\s+(.+)$/);
       if (match) {
         const done = /x/i.test(match[1]);
         const blocked = match[1] === '~' || /blocked|阻塞/i.test(match[2]);
-        tasks.push({
-          title: match[2].trim(),
+        const title = match[2].trim();
+        const structured = title.match(/^(T\d{3}\.\d+)\s+(.+)$/);
+        currentTask = {
+          id: structured?.[1] ?? null,
+          title: structured?.[2]?.trim() ?? title,
           done,
           blocked,
           source: relativePath,
           line: index + 1,
-        });
+          metadata: {},
+        };
+        tasks.push(currentTask);
+        continue;
+      }
+      const metadataMatch = lines[index].match(/^\s{2,}-\s+([a-z0-9_-]+):\s*(.*)$/i);
+      if (currentTask && metadataMatch) {
+        currentTask.metadata[metadataMatch[1].toLowerCase()] = metadataMatch[2].trim();
       }
     }
   }
+  const taskById = new Map(tasks.filter((task) => task.id).map((task) => [task.id, task]));
+  const blockedTasks = tasks
+    .filter((task) => !task.done)
+    .map((task) => {
+      const deps = parseOpenSpecTaskDeps(task.metadata?.deps);
+      const missing = [];
+      const incomplete = [];
+      for (const depId of deps) {
+        const dependency = taskById.get(depId);
+        if (!dependency) {
+          missing.push(depId);
+          continue;
+        }
+        if (!dependency.done) {
+          incomplete.push(depId);
+        }
+      }
+      return {
+        task,
+        deps,
+        missing,
+        incomplete,
+        ready: missing.length === 0 && incomplete.length === 0,
+      };
+    })
+    .filter((item) => !item.ready);
   return {
     activeChange,
     total: tasks.length,
     done: tasks.filter((task) => task.done).length,
-    pending: tasks.filter((task) => !task.done && !task.blocked).length,
-    blocked: tasks.filter((task) => task.blocked).length,
-    tasks: tasks.slice(0, 50),
+    pending: tasks.filter((task) => !task.done).length,
+    blocked: blockedTasks.length,
+    tasks,
   };
 }
 
@@ -843,7 +987,7 @@ async function listKnowledgeFiles(projectRoot) {
   return collected;
 }
 
-function detectKnowledge({ config, knowledgeFiles }) {
+function detectKnowledge({ config, knowledgeFiles, candidateState, knowledgeIndex, completionState }) {
   const skillDir = config.knowledge.skillDir ?? '.openprd/knowledge/skills';
   const candidateDir = config.knowledge.candidateDir ?? KNOWLEDGE_CANDIDATES_DIR;
   const draftDir = config.knowledge.draftDir ?? KNOWLEDGE_DRAFTS_DIR;
@@ -851,30 +995,53 @@ function detectKnowledge({ config, knowledgeFiles }) {
     .filter((file) => file.path.startsWith(skillDir.replace(/\//g, path.sep)) || file.path.startsWith(skillDir))
     .filter((file) => file.path.endsWith('SKILL.md'))
     .map((file) => file.path);
-  const candidates = knowledgeFiles
+  const candidateFiles = knowledgeFiles
     .filter((file) => file.path.startsWith(candidateDir.replace(/\//g, path.sep)) || file.path.startsWith(candidateDir))
     .filter((file) => file.path.endsWith('candidate.json'))
     .map((file) => file.path);
+  const pendingCandidates = (candidateState?.pending ?? []).map((candidate) => candidate.path).filter(Boolean);
+  const reviewedCandidates = (candidateState?.reviewed ?? []).map((candidate) => candidate.path).filter(Boolean);
   const drafts = knowledgeFiles
     .filter((file) => file.path.startsWith(draftDir.replace(/\//g, path.sep)) || file.path.startsWith(draftDir))
     .filter((file) => file.path.endsWith('SKILL.md'))
     .map((file) => file.path);
   const incidents = knowledgeFiles.filter((file) => /\.openprd[\\/]knowledge[\\/]incidents[\\/].+\.json$/.test(file.path));
+  const adoption = buildKnowledgeAdoptionSummary(Array.isArray(knowledgeIndex?.skills) ? knowledgeIndex.skills : []);
   const warnings = [];
-  if (config.knowledge.enabled && skills.length === 0) {
+  const hasReusableArtifact = skills.length > 0 || pendingCandidates.length > 0 || Number(candidateState?.counts?.total ?? 0) > 0;
+  if (config.knowledge.enabled && skills.length === 0 && !hasReusableArtifact) {
     warnings.push('项目级经验 skill 库尚为空；首次问题修复后应沉淀抽象经验。');
   }
-  if (config.knowledge.enabled && candidates.length > 0) {
-    warnings.push(`当前有 ${candidates.length} 个待确认 knowledge candidate；本轮收工前应决定是否 promote 为正式项目经验。`);
+  if (config.knowledge.enabled && pendingCandidates.length > 0) {
+    warnings.push(`当前有 ${pendingCandidates.length} 个待确认 knowledge candidate；本轮收工前应决定 promote、reject 或 archive。`);
+  }
+  if (config.knowledge.enabled && completionState?.postCompletionRequired && !hasReusableArtifact) {
+    warnings.push('本次已经达到可交付状态，但还没有自动生成 knowledge candidate；收工前至少保留一条可审查的项目经验草案。');
+  }
+  if (config.knowledge.enabled && skills.length > 0 && adoption.totals.referenced === 0) {
+    warnings.push('项目级经验 skill 已产出，但还没有任何 run-context 引用记录；优先接入自动命中与注入链路。');
   }
   return {
-    status: !config.knowledge.enabled || skills.length > 0 ? 'pass' : 'needs-attention',
+    status: !config.knowledge.enabled || hasReusableArtifact ? 'pass' : 'needs-attention',
     enabled: config.knowledge.enabled,
     skillDir,
     candidateDir,
     draftDir,
     skills,
-    candidates,
+    candidates: pendingCandidates,
+    candidateFiles,
+    candidateCounts: candidateState?.counts ?? {
+      total: candidateFiles.length,
+      pending: pendingCandidates.length,
+      promoted: 0,
+      rejected: 0,
+      archived: 0,
+      reviewed: reviewedCandidates.length,
+      byStatus: {},
+    },
+    reviewedCandidates,
+    candidateDetails: candidateState?.candidates ?? [],
+    adoption,
     drafts,
     incidents: incidents.map((file) => file.path),
     recommendations: [
@@ -886,6 +1053,39 @@ function detectKnowledge({ config, knowledgeFiles }) {
   };
 }
 
+function detectGrowth({ config, growthLedger, completionState }) {
+  const summary = growthLedger?.summary ?? {};
+  const lifecycleCount = Number(summary.observed ?? 0)
+    + Number(summary.manualApplied ?? 0)
+    + Number(summary.autoApplied ?? 0)
+    + Number(summary.reconciledAutoApplied ?? 0)
+    + Number(summary.rejected ?? 0)
+    + Number(summary.skipped ?? 0);
+  const completionCheckpoints = Number(summary.completionCheckpoints ?? 0);
+  const eventCount = Number(summary.eventCount ?? 0);
+  const warnings = [];
+  if (config.growth?.enabled && completionState?.postCompletionRequired && completionCheckpoints === 0 && lifecycleCount === 0) {
+    warnings.push('本次已经达到可交付状态，但 .openprd/growth 还没有任何收工账本记录；至少补一条 completion checkpoint 或 growth 观察事件。');
+  }
+  if (config.growth?.enabled && completionState?.postCompletionRequired && completionCheckpoints > 0 && lifecycleCount === 0) {
+    warnings.push('已记录完成检查点，但还没有新增 growth candidate；如果本轮形成了新的偏好、规则或工作流经验，收工前补一条 observe。');
+  }
+  return {
+    status: !config.growth?.enabled || !completionState?.postCompletionRequired || completionCheckpoints > 0 || lifecycleCount > 0
+      ? 'pass'
+      : 'needs-attention',
+    enabled: config.growth?.enabled !== false,
+    ledgerPath: config.growth?.ledgerPath ?? OPENPRD_GROWTH_LEDGER,
+    summary: {
+      eventCount,
+      lifecycleCount,
+      completionCheckpoints,
+      current: summary.current ?? { total: 0, pending: 0, applied: 0, rejected: 0 },
+    },
+    warnings,
+  };
+}
+
 function buildGate({ id, label, baseStatus, baseWarnings, policy, evidenceLedger }) {
   const required = policy.requiredGates.includes(id);
   const evidence = evidenceLedger[id] ?? { present: false, sources: [], summary: '未找到本次执行证据' };
@@ -909,7 +1109,7 @@ function buildGate({ id, label, baseStatus, baseWarnings, policy, evidenceLedger
   };
 }
 
-function buildGates({ observability, evalHarness, businessGuardrails, knowledge, policy, evidenceLedger }) {
+function buildGates({ observability, evalHarness, businessGuardrails, knowledge, growth, visualReview, policy, evidenceLedger }) {
   return [
     buildGate({
       id: 'traceability',
@@ -935,6 +1135,14 @@ function buildGates({ observability, evalHarness, businessGuardrails, knowledge,
       policy,
       evidenceLedger,
     }),
+    buildGate({
+      id: 'test-strategy',
+      label: '分层测试策略',
+      baseStatus: evalHarness.testStrategy.status,
+      baseWarnings: evalHarness.testStrategy.warnings,
+      policy,
+      evidenceLedger,
+    }),
     buildGate({
       id: 'smoke',
       label: '冒烟测试体系',
@@ -947,7 +1155,17 @@ function buildGates({ observability, evalHarness, businessGuardrails, knowledge,
       id: 'feature-coverage',
       label: '任务与功能覆盖',
       baseStatus: evalHarness.featureCoverage.activeTasks.pending === 0 ? 'pass' : 'needs-attention',
-      baseWarnings: evalHarness.featureCoverage.activeTasks.pending === 0 ? [] : ['仍有未完成任务或缺少任务覆盖证据。'],
+      baseWarnings: evalHarness.featureCoverage.activeTasks.pending === 0
+        ? []
+        : [describeFeatureCoverageLedger(evalHarness.featureCoverage.activeTasks) ?? '仍有未完成任务或缺少任务覆盖证据。'],
+      policy,
+      evidenceLedger,
+    }),
+    buildGate({
+      id: 'visual-review',
+      label: '视觉对比与自检',
+      baseStatus: visualReview.status,
+      baseWarnings: visualReview.warnings,
       policy,
       evidenceLedger,
     }),
@@ -975,6 +1193,14 @@ function buildGates({ observability, evalHarness, businessGuardrails, knowledge,
       policy,
       evidenceLedger,
     }),
+    buildGate({
+      id: 'growth',
+      label: '自我成长账本',
+      baseStatus: growth.status,
+      baseWarnings: growth.warnings,
+      policy,
+      evidenceLedger,
+    }),
   ];
 }
 
@@ -982,8 +1208,8 @@ async function loadPackageJson(projectRoot) {
   return readJson(cjoin(projectRoot, 'package.json')).catch(() => null);
 }
 
-async function buildQualityReport(projectRoot, config) {
-  const id = reportId();
+async function buildQualityReport(projectRoot, config, options = {}) {
+  const id = options.reportId ?? reportId();
   const normalizedConfig = normalizeQualityConfig(config);
   const files = await walkProject(projectRoot);
   const texts = await readProjectTexts(projectRoot, files);
@@ -991,26 +1217,33 @@ async function buildQualityReport(projectRoot, config) {
   const activeTasks = await readActiveTasks(projectRoot);
   const activeChangeContext = await readActiveChangeContext(projectRoot, activeTasks.activeChange);
   const evidenceFiles = await readEvidenceFiles(projectRoot, normalizedConfig);
+  const visualArtifacts = await listVisualReviewArtifacts(projectRoot);
   const knowledgeFiles = await listKnowledgeFiles(projectRoot);
+  const knowledgeIndex = await readJson(qualityPath(projectRoot, KNOWLEDGE_INDEX)).catch(() => ({ version: 1, skills: [] }));
+  const growthLedger = await readJson(qualityPath(projectRoot, normalizedConfig.growth?.ledgerPath ?? OPENPRD_GROWTH_LEDGER)).catch(() => null);
+  const completionState = detectCompletionState({ files, activeTasks, evidenceFiles });
   const observability = detectObservability({ config: normalizedConfig, files, texts, packageJson });
   const evalHarness = detectEvalHarness({ config: normalizedConfig, files, texts, packageJson, activeTasks });
   const businessGuardrails = detectBusinessGuardrails({ config: normalizedConfig, files, texts, packageJson });
-  const knowledge = detectKnowledge({ config: normalizedConfig, knowledgeFiles });
-  const policy = buildQualityPolicy({ config: normalizedConfig, activeChangeContext, activeTasks, businessGuardrails });
-  const evidenceLedger = buildEvidenceLedger({ evidenceFiles, activeTasks, observability, businessGuardrails, knowledge });
-  const gates = buildGates({ observability, evalHarness, businessGuardrails, knowledge, policy, evidenceLedger });
+  const candidateState = await listKnowledgeCandidates(projectRoot, { status: 'all' }).catch(() => null);
+  const knowledge = detectKnowledge({ config: normalizedConfig, knowledgeFiles, candidateState, knowledgeIndex, completionState });
+  const growth = detectGrowth({ config: normalizedConfig, growthLedger, completionState });
+  const policy = buildQualityPolicy({ config: normalizedConfig, activeChangeContext, activeTasks, businessGuardrails, completionState });
+  const visualReview = detectVisualReview({ policy, activeChangeContext, activeTasks, visualArtifacts, includesAny });
+  const evidenceLedger = buildEvidenceLedger({ evidenceFiles, activeTasks, observability, businessGuardrails, knowledge, growth, visualReview });
+  const gates = buildGates({ observability, evalHarness, businessGuardrails, knowledge, growth, visualReview, policy, evidenceLedger });
   const blockingStatuses = new Set(['fail']);
   const attentionStatuses = new Set(['needs-attention', 'needs-evidence']);
   const readiness = {
     ok: !gates.some((gate) => blockingStatuses.has(gate.status)),
     productionReady: !gates.some((gate) => attentionStatuses.has(gate.status) || blockingStatuses.has(gate.status)),
-    enforcement: config.enforcement,
+    enforcement: normalizedConfig.enforcement,
     failingGates: gates.filter((gate) => blockingStatuses.has(gate.status)).map((gate) => gate.id),
     attentionGates: gates.filter((gate) => attentionStatuses.has(gate.status)).map((gate) => gate.id),
   };
   evalHarness.executionEvidence = {
     sources: evidenceFiles.map((file) => ({ path: file.path, source: file.source, size: file.size })).slice(0, 120),
-    ledger: Object.fromEntries(['smoke', 'feature-coverage', 'normal-performance', 'extreme-performance'].map((gate) => [gate, evidenceLedger[gate]])),
+    ledger: Object.fromEntries(['test-strategy', 'smoke', 'feature-coverage', 'visual-review', 'normal-performance', 'extreme-performance'].map((gate) => [gate, evidenceLedger[gate]])),
   };
   return {
     version: 1,
@@ -1032,7 +1265,10 @@ async function buildQualityReport(projectRoot, config) {
     observability,
     evalHarness,
     businessGuardrails,
+    visualReview,
     knowledge,
+    growth,
+    completionState,
     configSnapshot: normalizedConfig,
   };
 }
@@ -1101,31 +1337,73 @@ export async function verifyQualityWorkspace(projectRoot, options = {}) {
   }
   const config = normalizeQualityConfig(await readJson(configPath));
   await ensureQualityDirs(projectRoot);
-  const report = await buildQualityReport(projectRoot, config);
-  const paths = await writeReport(projectRoot, report);
+  const initialReport = await buildQualityReport(projectRoot, config);
+  let report = initialReport;
+  let paths = await writeReport(projectRoot, report);
   const knowledgeSignal = {
     kind: 'quality-verify',
     ok: report.readiness.productionReady,
     productionReady: report.readiness.productionReady,
     attentionGates: report.readiness.attentionGates,
+    touchedFiles: report.completionState?.substantiveFiles ?? [],
     summary: `quality ${report.summary.status}`,
   };
   await recordKnowledgeReviewSignal(projectRoot, knowledgeSignal).catch(() => null);
+  const growthCheckpoint = report.completionState?.postCompletionRequired && config.growth?.enabled !== false
+    ? await recordGrowthCheckpointWorkspace(projectRoot, {
+      outcome: 'quality-verify',
+      reason: report.evalHarness?.featureCoverage?.activeTasks?.activeChange
+        ?? report.completionState?.substantiveFiles?.slice(0, 4).join('|')
+        ?? 'quality-post-completion',
+      changed: report.completionState?.substantiveFiles ?? [],
+    }).catch((error) => ({
+      ok: false,
+      action: 'growth-checkpoint',
+      projectRoot,
+      recorded: false,
+      errors: [error instanceof Error ? error.message : String(error)],
+    }))
+    : {
+      ok: true,
+      action: 'growth-checkpoint',
+      projectRoot,
+      recorded: false,
+      skipped: true,
+      reason: 'completion-checkpoint-not-required',
+    };
   const reviewSource = (await exists(qualityPath(projectRoot, OPENPRD_HARNESS_TURN_STATE)))
     ? OPENPRD_HARNESS_TURN_STATE
     : paths.jsonPath;
-  const knowledgeReview = await reviewKnowledgeWorkspace(projectRoot, {
-    from: reviewSource,
-    signal: knowledgeSignal,
-    requiredCorrelationFields: config.observability.requiredCorrelationFields,
-  }).catch((error) => ({
-    ok: false,
-    action: 'quality-knowledge-review',
-    skipped: false,
-    errors: [error instanceof Error ? error.message : String(error)],
-  }));
+  const shouldAutoReviewKnowledge = Boolean(
+    report.completionState?.postCompletionRequired
+      && (report.knowledge?.skills?.length ?? 0) === 0
+      && Number(report.knowledge?.candidateCounts?.total ?? 0) === 0
+  );
+  const knowledgeReview = shouldAutoReviewKnowledge
+    ? await reviewKnowledgeWorkspace(projectRoot, {
+      from: reviewSource,
+      signal: knowledgeSignal,
+      touchedFiles: report.completionState?.substantiveFiles ?? [],
+      requiredCorrelationFields: config.observability.requiredCorrelationFields,
+    }).catch((error) => ({
+      ok: false,
+      action: 'quality-knowledge-review',
+      skipped: false,
+      errors: [error instanceof Error ? error.message : String(error)],
+    }))
+    : {
+      ok: true,
+      action: 'quality-knowledge-review',
+      skipped: true,
+      reason: 'reusable-knowledge-artifact-already-exists',
+    };
+  report = await buildQualityReport(projectRoot, config, { reportId: initialReport.id });
+  paths = await writeReport(projectRoot, report);
   const strict = options.strict === true;
   const blocking = (strict || config.enforcement === 'blocking') && !report.readiness.productionReady;
+  const featureCoverageOnly = report.readiness.failingGates.length === 0
+    && report.readiness.attentionGates.length === 1
+    && report.readiness.attentionGates[0] === 'feature-coverage';
   return {
     ok: !blocking,
     action: 'quality-verify',
@@ -1134,8 +1412,16 @@ export async function verifyQualityWorkspace(projectRoot, options = {}) {
     reportPath: paths.jsonPath,
     htmlPath: paths.htmlPath,
     indexPath: paths.indexPath,
+    growthCheckpoint,
     knowledgeReview,
-    errors: blocking ? ['Quality readiness is not production-ready; one or more required gates need evidence or attention.'] : [],
+    errors: blocking
+      ? [
+        featureCoverageOnly
+          ? (describeFeatureCoverageLedger(report.evalHarness?.featureCoverage?.activeTasks ?? null)
+            ?? '当前 feature-coverage 账本尚未收口，不等于当前实现失败。')
+          : 'Quality readiness is not production-ready; one or more required gates need evidence or attention.',
+      ]
+      : [],
   };
 }