@openprd/cli 0.1.0 → 0.1.8

package/src/self-update.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
-export const DEFAULT_SELF_UPDATE_SOURCE = 'git+https://github.com/mileson/openprd.git';
+export const DEFAULT_SELF_UPDATE_SOURCE = '@openprd/cli@latest';
 
 const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const DEFAULT_PACKAGE_ROOT = path.resolve(MODULE_DIR, '..');

package/src/session-binding.js

@@ -1,10 +1,12 @@
 import path from 'node:path';
 import { readJson, writeJson } from './fs-utils.js';
+import { upsertSessionRegistryEntry } from './session-registry.js';
 import { timestamp } from './time.js';
 
 const OPENPRD_HARNESS_DIR = path.join('.openprd', 'harness');
 const OPENPRD_HARNESS_REQUIREMENT_GATE = path.join(OPENPRD_HARNESS_DIR, 'requirement-gate.json');
 const OPENPRD_HARNESS_SESSION_BINDINGS_DIR = path.join(OPENPRD_HARNESS_DIR, 'session-bindings');
+const OPENPRD_STATE_CURRENT = path.join('.openprd', 'state', 'current.json');
 
 function normalizeSessionId(sessionId) {
   const text = String(sessionId ?? '').trim();
@@ -27,6 +29,20 @@ async function readLegacyRequirementGate(projectRoot) {
   return readJson(path.join(projectRoot, OPENPRD_HARNESS_REQUIREMENT_GATE)).catch(() => null);
 }
 
+async function readWorkspaceCurrentState(projectRoot) {
+  return readJson(path.join(projectRoot, OPENPRD_STATE_CURRENT)).catch(() => null);
+}
+
+async function resolveBindingSessionId(projectRoot, options = {}, legacyGate = null) {
+  const workspaceCurrentState = await readWorkspaceCurrentState(projectRoot);
+  return normalizeSessionId(
+    options.sessionId
+      ?? options.currentSessionId
+      ?? workspaceCurrentState?.laneSessionId
+      ?? legacyGate?.sessionId
+  );
+}
+
 async function readSessionBinding(projectRoot, sessionId) {
   const filePath = sessionBindingPath(projectRoot, sessionId);
   if (!filePath) {
@@ -52,6 +68,27 @@ async function upsertSessionBinding(projectRoot, sessionId, patch = {}) {
     updatedAt: patch.updatedAt ?? timestamp(),
   };
   await writeJson(filePath, next);
+  await upsertSessionRegistryEntry(projectRoot, normalized, {
+    laneKind: patch.laneKind ?? previous?.laneKind ?? 'requirement',
+    tool: patch.tool ?? previous?.tool ?? 'codex',
+    threadId: patch.threadId ?? previous?.threadId ?? null,
+    changeId: patch.changeId ?? next.changeId ?? null,
+    taskHandle: patch.taskHandle ?? next.taskHandle ?? null,
+    workUnitId: patch.workUnitId ?? next.workUnitId ?? null,
+    versionId: patch.versionId ?? next.versionId ?? null,
+    digest: patch.digest ?? next.digest ?? null,
+    title: patch.title ?? next.title ?? null,
+    targetRoot: patch.targetRoot ?? next.targetRoot ?? null,
+    promptPreview: patch.promptPreview ?? next.promptPreview ?? null,
+    reviewStatus: patch.reviewStatus ?? next.reviewStatus ?? null,
+    gateStatus: patch.gateStatus ?? next.gateStatus ?? null,
+    gateActive: patch.gateActive ?? next.gateActive ?? false,
+    bindingPath: filePath,
+    statePath: normalized
+      ? path.join(projectRoot, '.openprd', 'harness', 'session-states', `${normalized.replace(/[^A-Za-z0-9._-]/g, '_')}.json`)
+      : null,
+    updatedAt: next.updatedAt,
+  });
   return {
     ...next,
     path: filePath,
@@ -60,7 +97,7 @@ async function upsertSessionBinding(projectRoot, sessionId, patch = {}) {
 
 async function syncSessionBindingFromSnapshot(projectRoot, snapshot, options = {}) {
   const legacyGate = await readLegacyRequirementGate(projectRoot);
-  const sessionId = normalizeSessionId(options.sessionId ?? legacyGate?.sessionId);
+  const sessionId = await resolveBindingSessionId(projectRoot, options, legacyGate);
   if (!sessionId || !snapshot?.versionId) {
     return null;
   }
@@ -84,7 +121,7 @@ async function syncSessionBindingFromSnapshot(projectRoot, snapshot, options = {
 
 async function syncSessionBindingFromReview(projectRoot, snapshot, options = {}) {
   const legacyGate = await readLegacyRequirementGate(projectRoot);
-  const sessionId = normalizeSessionId(options.sessionId ?? legacyGate?.sessionId);
+  const sessionId = await resolveBindingSessionId(projectRoot, options, legacyGate);
   if (!sessionId || !snapshot?.versionId) {
     return null;
   }
@@ -107,7 +144,7 @@ async function syncSessionBindingFromReview(projectRoot, snapshot, options = {})
 
 async function syncSessionBindingFromChange(projectRoot, changeId, options = {}) {
   const legacyGate = await readLegacyRequirementGate(projectRoot);
-  const sessionId = normalizeSessionId(options.sessionId ?? legacyGate?.sessionId);
+  const sessionId = await resolveBindingSessionId(projectRoot, options, legacyGate);
   if (!sessionId || !changeId) {
     return null;
   }

package/src/session-registry.js

@@ -0,0 +1,159 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { appendJsonl, cjoin, exists, readJsonl } from './fs-utils.js';
+import { timestamp } from './time.js';
+import { resolveOpenPrdHome } from './workspace-registry.js';
+
+const OPENPRD_SESSION_REGISTRY = cjoin('registry', 'sessions.jsonl');
+
+function normalizeSessionId(sessionId) {
+  const text = String(sessionId ?? '').trim();
+  return text || null;
+}
+
+function sessionRegistryFilePath(options = {}) {
+  return cjoin(resolveOpenPrdHome(options), OPENPRD_SESSION_REGISTRY);
+}
+
+function normalizeSessionRegistryEntry(entry) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    return null;
+  }
+  const sessionId = normalizeSessionId(entry.sessionId);
+  const workspaceRoot = entry.workspaceRoot ? path.resolve(String(entry.workspaceRoot)) : null;
+  if (!sessionId || !workspaceRoot) {
+    return null;
+  }
+  const realpath = entry.realpath ? path.resolve(String(entry.realpath)) : workspaceRoot;
+  const lastUpdatedAt = entry.lastUpdatedAt ?? entry.updatedAt ?? entry.recordedAt ?? null;
+  const firstRegisteredAt = entry.firstRegisteredAt ?? entry.recordedAt ?? lastUpdatedAt;
+  return {
+    version: 1,
+    sessionId,
+    workspaceRoot,
+    realpath,
+    laneKind: entry.laneKind ? String(entry.laneKind) : 'requirement',
+    tool: entry.tool ? String(entry.tool) : null,
+    threadId: entry.threadId ? String(entry.threadId) : null,
+    changeId: entry.changeId ? String(entry.changeId) : null,
+    taskHandle: entry.taskHandle ? String(entry.taskHandle) : null,
+    workUnitId: entry.workUnitId ? String(entry.workUnitId) : null,
+    versionId: entry.versionId ? String(entry.versionId) : null,
+    digest: entry.digest ? String(entry.digest) : null,
+    title: entry.title ? String(entry.title) : null,
+    targetRoot: entry.targetRoot ? path.resolve(String(entry.targetRoot)) : null,
+    promptPreview: entry.promptPreview ? String(entry.promptPreview) : null,
+    reviewStatus: entry.reviewStatus ? String(entry.reviewStatus) : null,
+    gateStatus: entry.gateStatus ? String(entry.gateStatus) : null,
+    gateActive: entry.gateActive === true,
+    statePath: entry.statePath ? path.resolve(String(entry.statePath)) : null,
+    bindingPath: entry.bindingPath ? path.resolve(String(entry.bindingPath)) : null,
+    firstRegisteredAt,
+    lastRegisteredAt: entry.lastRegisteredAt ?? entry.recordedAt ?? lastUpdatedAt,
+    lastUpdatedAt,
+  };
+}
+
+async function readSessionRegistry(options = {}) {
+  const home = resolveOpenPrdHome(options);
+  const registryPath = sessionRegistryFilePath({ openprdHome: home });
+  const events = await readJsonl(registryPath).catch(() => []);
+  const currentBySession = new Map();
+  for (const event of events) {
+    const entry = normalizeSessionRegistryEntry(event);
+    if (!entry) {
+      continue;
+    }
+    currentBySession.set(entry.sessionId, entry);
+  }
+  const entries = Array.from(currentBySession.values())
+    .sort((left, right) => left.sessionId.localeCompare(right.sessionId));
+  const staleEntries = [];
+  for (const entry of entries) {
+    const workspaceExists = await exists(entry.workspaceRoot);
+    if (!workspaceExists) {
+      staleEntries.push({
+        ...entry,
+        reason: 'missing-workspace',
+      });
+      continue;
+    }
+    const markerExists = await exists(cjoin(entry.workspaceRoot, '.openprd'));
+    if (!markerExists) {
+      staleEntries.push({
+        ...entry,
+        reason: 'missing-openprd-marker',
+      });
+    }
+  }
+  return {
+    home,
+    registryPath,
+    totalEvents: events.length,
+    entries,
+    staleEntries,
+  };
+}
+
+async function readSessionRegistryEntry(sessionId, options = {}) {
+  const normalized = normalizeSessionId(sessionId);
+  if (!normalized) {
+    return null;
+  }
+  const registry = await readSessionRegistry(options);
+  return registry.entries.find((entry) => entry.sessionId === normalized) ?? null;
+}
+
+async function upsertSessionRegistryEntry(projectRoot, sessionId, patch = {}, options = {}) {
+  const normalized = normalizeSessionId(sessionId);
+  if (!normalized) {
+    return null;
+  }
+  const registry = await readSessionRegistry(options);
+  const workspaceRoot = path.resolve(projectRoot);
+  const realpath = await fs.realpath(workspaceRoot).catch(() => workspaceRoot);
+  const existing = registry.entries.find((entry) => entry.sessionId === normalized) ?? null;
+  const recordedAt = options.recordedAt ?? timestamp();
+  const entry = normalizeSessionRegistryEntry({
+    ...existing,
+    sessionId: normalized,
+    workspaceRoot,
+    realpath,
+    laneKind: patch.laneKind ?? existing?.laneKind ?? 'requirement',
+    tool: patch.tool ?? existing?.tool ?? null,
+    threadId: patch.threadId ?? existing?.threadId ?? null,
+    changeId: patch.changeId ?? existing?.changeId ?? null,
+    taskHandle: patch.taskHandle ?? existing?.taskHandle ?? null,
+    workUnitId: patch.workUnitId ?? existing?.workUnitId ?? null,
+    versionId: patch.versionId ?? existing?.versionId ?? null,
+    digest: patch.digest ?? existing?.digest ?? null,
+    title: patch.title ?? existing?.title ?? null,
+    targetRoot: patch.targetRoot ?? existing?.targetRoot ?? null,
+    promptPreview: patch.promptPreview ?? existing?.promptPreview ?? null,
+    reviewStatus: patch.reviewStatus ?? existing?.reviewStatus ?? null,
+    gateStatus: patch.gateStatus ?? existing?.gateStatus ?? null,
+    gateActive: patch.gateActive ?? existing?.gateActive ?? false,
+    statePath: patch.statePath ?? existing?.statePath ?? null,
+    bindingPath: patch.bindingPath ?? existing?.bindingPath ?? null,
+    firstRegisteredAt: existing?.firstRegisteredAt ?? recordedAt,
+    lastRegisteredAt: recordedAt,
+    lastUpdatedAt: patch.updatedAt ?? recordedAt,
+    recordedAt,
+  });
+  await appendJsonl(registry.registryPath, entry);
+  return {
+    home: registry.home,
+    registryPath: registry.registryPath,
+    entry,
+    status: existing ? 'updated' : 'created',
+    knownTotal: existing ? registry.entries.length : registry.entries.length + 1,
+  };
+}
+
+export {
+  normalizeSessionId,
+  readSessionRegistry,
+  readSessionRegistryEntry,
+  sessionRegistryFilePath,
+  upsertSessionRegistryEntry,
+};

package/src/standards.js

@@ -815,10 +815,12 @@ export async function checkStandardsWorkspace(projectRoot, options = {}) {
       continue;
     }
     const text = await readText(docPath);
-    if (!text.includes(`# ${doc.title}`)) {
+    if (options.docsContent !== false && !text.includes(`# ${doc.title}`)) {
       errors.push(`${relativePath} 缺少标题: ${doc.title}`);
     }
-    validateTextSections(relativePath, text, doc.sections, errors);
+    if (options.docsContent !== false) {
+      validateTextSections(relativePath, text, doc.sections, errors);
+    }
     if (hasProjectSource && !openPrdToolProject && options.docsContent !== false && DOC_PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(text))) {
       errors.push(`${relativePath} 仍包含模板占位内容，必须更新为当前项目事实。`);
     }
@@ -861,7 +863,7 @@ export async function checkStandardsWorkspace(projectRoot, options = {}) {
   checks.push(`Manual templates: ${templateFiles.filter((file) => file.exists).length}/${STANDARD_TEMPLATE_FILES.length}.`);
   const lineConfig = config?.developmentStandards?.codeFileLines ?? DEFAULT_DEVELOPMENT_STANDARDS.codeFileLines;
   checks.push(`Development standards: code files ok <= ${lineConfig.okMax} lines, attention <= ${lineConfig.attentionMax} lines.`);
-  checks.push(`Growth layer: ${config?.growth?.enabled === false ? 'disabled' : 'enabled'} with user review required before applying candidates.`);
+  checks.push(`Growth layer: ${config?.growth?.enabled === false ? 'disabled' : 'enabled'}; code-extension candidates can auto-apply, remaining candidates stay in wrap-up review.`);
 
   return {
     ok: errors.length === 0,

package/src/test-strategy.js

@@ -0,0 +1,386 @@
+const TEST_LAYER_LABELS = {
+  unit: '单元测试',
+  integration: '集成测试',
+  e2e: '端到端测试',
+  manual: '人工审查',
+  smoke: '冒烟测试',
+  visual: '视觉对比',
+  performance: '性能测试',
+  security: '安全验证',
+  weapp: '小程序实测',
+  none: '无需专项测试',
+};
+
+const TEST_SIZE_LABELS = {
+  small: '小规模',
+  medium: '中规模',
+  large: '大规模',
+  manual: '人工',
+  advisory: '提示型',
+  none: '无',
+};
+
+const TEST_SCOPE_LABELS = {
+  isolated: '局部逻辑',
+  module: '模块边界',
+  contract: '契约边界',
+  'cli-contract': '命令行契约',
+  'api-contract': '接口契约',
+  'user-flow': '用户主路径',
+  'visual-flow': '视觉路径',
+  'weapp-runtime': '小程序运行态',
+  performance: '性能基线',
+  security: '安全边界',
+  governance: '治理流程',
+  docs: '文档审查',
+  none: '无',
+};
+
+export const TEST_STRATEGY_METADATA_KEYS = [
+  'test-layer',
+  'test-size',
+  'test-scope',
+  'evidence',
+  'evidence-plan',
+  'upgrade-reason',
+  'waiver',
+  'waiver-reason',
+];
+
+export const TEST_LAYER_VALUES = Object.keys(TEST_LAYER_LABELS);
+export const TEST_SIZE_VALUES = Object.keys(TEST_SIZE_LABELS);
+export const TEST_SCOPE_VALUES = Object.keys(TEST_SCOPE_LABELS);
+
+function normalizeToken(value) {
+  return String(value ?? '').trim().toLowerCase();
+}
+
+function splitValues(value) {
+  return String(value ?? '')
+    .split(',')
+    .map((item) => normalizeToken(item))
+    .filter(Boolean);
+}
+
+function includesAny(text, patterns) {
+  return patterns.some((pattern) => pattern.test(text));
+}
+
+const WEAPP_MENTION_PATTERNS = [/weapp|微信小程序|小程序|微信开发者工具/];
+const WEAPP_VALIDATION_ACTION_PATTERNS = [
+  /测试|验证|实测|复现|截图|日志|抓日志|抓包|网络请求|network|运行态|开发者工具自动化|从\s*0\s*到\s*1|冷启动|全流程/,
+];
+
+function firstKnown(values, allowed, fallback) {
+  return values.find((value) => allowed.includes(value)) ?? fallback;
+}
+
+export function normalizeTestLayers(value) {
+  const layers = splitValues(value).filter((layer) => TEST_LAYER_VALUES.includes(layer));
+  return [...new Set(layers)];
+}
+
+export function labelTestLayer(layer) {
+  return TEST_LAYER_LABELS[normalizeToken(layer)] ?? layer ?? '未指定';
+}
+
+export function labelTestSize(size) {
+  return TEST_SIZE_LABELS[normalizeToken(size)] ?? size ?? '未指定';
+}
+
+export function labelTestScope(scope) {
+  return TEST_SCOPE_LABELS[normalizeToken(scope)] ?? scope ?? '未指定';
+}
+
+export function describeTestStrategy(strategy) {
+  const layers = (strategy.layers ?? []).map(labelTestLayer).join(' + ') || '未指定';
+  const size = labelTestSize(strategy.size);
+  const scope = labelTestScope(strategy.scope);
+  const evidence = strategy.evidencePlan || strategy.evidence || '未指定证据';
+  return `${layers} / ${size} / ${scope}；证据：${evidence}`;
+}
+
+export function inferTestStrategyForTask(task = {}) {
+  const type = normalizeToken(task.type ?? task.metadata?.type ?? task.metadata?.category ?? task.metadata?.kind);
+  const phase = normalizeToken(task.phase);
+  const text = [
+    task.id,
+    task.title,
+    task.done,
+    task.verify,
+    task.metadata?.done,
+    task.metadata?.verify,
+  ].map((value) => String(value ?? '')).join('\n').toLowerCase();
+
+  if (type === 'governance' || phase.includes('governance')) {
+    return {
+      layers: ['manual'],
+      size: 'manual',
+      scope: 'governance',
+      evidencePlan: task.verify ?? task.metadata?.verify ?? 'openprd change . --validate --change <change-id>',
+      upgradeReason: '治理任务以结构校验、评审确认和变更状态证据为主',
+      inferred: true,
+    };
+  }
+
+  if (type === 'documentation' || /docs\/basic|readme|文档|说明书|documentation|docs/i.test(text)) {
+    return {
+      layers: ['manual'],
+      size: 'manual',
+      scope: 'docs',
+      evidencePlan: task.verify ?? task.metadata?.verify ?? 'openprd standards . --verify',
+      upgradeReason: '文档任务以标准校验和人工审查证据为主',
+      inferred: true,
+    };
+  }
+
+  if (includesAny(text, WEAPP_MENTION_PATTERNS) && includesAny(text, WEAPP_VALIDATION_ACTION_PATTERNS)) {
+    return {
+      layers: ['integration', 'weapp'],
+      size: 'large',
+      scope: 'weapp-runtime',
+      evidencePlan: '小程序运行态截图、日志、网络请求或其他本地验证证据 + 本任务 verify 命令',
+      upgradeReason: '明确要求小程序运行态证据，需要本地运行态验证',
+      inferred: true,
+    };
+  }
+
+  if (includesAny(text, [/visual|视觉|截图|界面|页面|组件|样式|browser|playwright|cypress|e2e|端到端|用户主路径|主流程/])) {
+    return {
+      layers: ['integration', 'e2e'],
+      size: 'large',
+      scope: includesAny(text, [/visual|视觉|截图|样式/]) ? 'visual-flow' : 'user-flow',
+      evidencePlan: '主流程自动化、截图或 visual-compare 证据 + 本任务 verify 命令',
+      upgradeReason: '触达用户可见路径，需要端到端或视觉级证据',
+      inferred: true,
+    };
+  }
+
+  if (includesAny(text, [/perf|performance|性能|压力|stress|load|baseline|基线/])) {
+    return {
+      layers: ['integration', 'performance'],
+      size: 'large',
+      scope: 'performance',
+      evidencePlan: '性能基线、压力数据或 benchmark 报告 + 本任务 verify 命令',
+      upgradeReason: '触达性能或容量边界，需要专项验证证据',
+      inferred: true,
+    };
+  }
+
+  if (includesAny(text, [/security|权限|越权|身份|token|secret|敏感|安全|额度|滥用|成本|限流|并发/])) {
+    return {
+      layers: ['integration', 'security'],
+      size: 'medium',
+      scope: 'security',
+      evidencePlan: '正向路径 + 越权、额度、并发或敏感信息负向验证',
+      upgradeReason: '触达权限、安全、成本或滥用边界，需要至少集成级证据',
+      inferred: true,
+    };
+  }
+
+  if (includesAny(text, [/api|cli|command|契约|contract|schema|json|输出|参数|quality|loop|tasks|agent|hook|skill|生成物|报告/])) {
+    return {
+      layers: ['unit', 'integration'],
+      size: 'medium',
+      scope: includesAny(text, [/api|接口/]) ? 'api-contract' : 'cli-contract',
+      evidencePlan: '单元测试锁定规则 + 集成或命令行契约验证',
+      upgradeReason: '触达 CLI/API/Agent 契约或生成物，需要中间层验证',
+      inferred: true,
+    };
+  }
+
+  if (type === 'verification' || phase.includes('verification') || includesAny(text, [/验证|测试|回归|边界|失败|异常|验收/])) {
+    return {
+      layers: ['integration'],
+      size: 'medium',
+      scope: 'module',
+      evidencePlan: task.verify ?? task.metadata?.verify ?? '本任务 verify 命令与测试报告',
+      upgradeReason: '验证任务默认需要能覆盖模块边界的证据',
+      inferred: true,
+    };
+  }
+
+  return {
+    layers: ['unit'],
+    size: 'small',
+    scope: 'isolated',
+    evidencePlan: task.verify ?? task.metadata?.verify ?? '最小相关单元测试或局部命令验证',
+    upgradeReason: '默认从最小足够证据开始，触达用户主路径或契约时再升级',
+    inferred: true,
+  };
+}
+
+export function taskTestStrategy(task = {}) {
+  const metadata = task.metadata ?? {};
+  const inferred = inferTestStrategyForTask(task);
+  const explicitLayers = normalizeTestLayers(metadata['test-layer']);
+  const rawSize = normalizeToken(metadata['test-size']);
+  const rawScope = normalizeToken(metadata['test-scope']);
+  return {
+    layers: explicitLayers.length > 0 ? explicitLayers : inferred.layers,
+    size: TEST_SIZE_VALUES.includes(rawSize) ? rawSize : inferred.size,
+    scope: TEST_SCOPE_VALUES.includes(rawScope) ? rawScope : inferred.scope,
+    evidence: metadata.evidence ?? null,
+    evidencePlan: metadata['evidence-plan'] ?? inferred.evidencePlan,
+    upgradeReason: metadata['upgrade-reason'] ?? inferred.upgradeReason,
+    waiver: metadata.waiver ?? metadata['waiver-reason'] ?? null,
+    inferred: explicitLayers.length === 0 || !TEST_SIZE_VALUES.includes(rawSize) || !TEST_SCOPE_VALUES.includes(rawScope),
+  };
+}
+
+export function formatTaskTestStrategyMetadata(task = {}) {
+  const strategy = inferTestStrategyForTask(task);
+  return [
+    `test-layer: ${strategy.layers.join(', ')}`,
+    `test-size: ${strategy.size}`,
+    `test-scope: ${strategy.scope}`,
+    `evidence-plan: ${strategy.evidencePlan}`,
+    `upgrade-reason: ${strategy.upgradeReason}`,
+  ];
+}
+
+export function validateTaskTestStrategy(task = {}) {
+  const metadata = task.metadata ?? {};
+  const errors = [];
+  if (metadata['test-layer']) {
+    const rawLayers = splitValues(metadata['test-layer']);
+    const invalid = rawLayers.filter((layer) => !TEST_LAYER_VALUES.includes(layer));
+    if (invalid.length > 0) {
+      errors.push(`test-layer 包含无效取值 ${invalid.join(', ')}；允许值: ${TEST_LAYER_VALUES.join(', ')}`);
+    }
+  }
+  if (metadata['test-size']) {
+    const size = normalizeToken(metadata['test-size']);
+    if (!TEST_SIZE_VALUES.includes(size)) {
+      errors.push(`test-size 无效: ${metadata['test-size']}；允许值: ${TEST_SIZE_VALUES.join(', ')}`);
+    }
+  }
+  if (metadata['test-scope']) {
+    const scope = normalizeToken(metadata['test-scope']);
+    if (!TEST_SCOPE_VALUES.includes(scope)) {
+      errors.push(`test-scope 无效: ${metadata['test-scope']}；允许值: ${TEST_SCOPE_VALUES.join(', ')}`);
+    }
+  }
+  const layers = normalizeTestLayers(metadata['test-layer']);
+  const hasWaiver = Boolean(metadata.waiver || metadata['waiver-reason']);
+  const hasEvidencePlan = Boolean(metadata['evidence-plan'] || metadata.evidence);
+  if ((layers.length > 0 || metadata['test-size'] || metadata['test-scope']) && !hasEvidencePlan && !hasWaiver) {
+    errors.push('已声明测试策略，但缺少 evidence-plan/evidence 或 waiver/waiver-reason。');
+  }
+  return errors;
+}
+
+export function summarizeTaskTestStrategies(tasks = []) {
+  const layerCounts = Object.fromEntries(TEST_LAYER_VALUES.map((layer) => [layer, 0]));
+  const sizeCounts = Object.fromEntries(TEST_SIZE_VALUES.map((size) => [size, 0]));
+  const scopeCounts = Object.fromEntries(TEST_SCOPE_VALUES.map((scope) => [scope, 0]));
+  const taskStrategies = [];
+  let explicit = 0;
+  let inferred = 0;
+  let evidencePlanned = 0;
+  let evidencePresent = 0;
+  let waiverCount = 0;
+
+  for (const task of tasks) {
+    const strategy = taskTestStrategy(task);
+    if (strategy.inferred) {
+      inferred += 1;
+    } else {
+      explicit += 1;
+    }
+    if (strategy.evidencePlan) {
+      evidencePlanned += 1;
+    }
+    if (strategy.evidence) {
+      evidencePresent += 1;
+    }
+    if (strategy.waiver) {
+      waiverCount += 1;
+    }
+    for (const layer of strategy.layers) {
+      layerCounts[layer] = (layerCounts[layer] ?? 0) + 1;
+    }
+    sizeCounts[strategy.size] = (sizeCounts[strategy.size] ?? 0) + 1;
+    scopeCounts[strategy.scope] = (scopeCounts[strategy.scope] ?? 0) + 1;
+    taskStrategies.push({
+      id: task.id ?? null,
+      title: task.title ?? null,
+      done: Boolean(task.checked ?? task.done),
+      source: task.relativePath ?? task.source ?? null,
+      line: task.lineNumber ?? task.line ?? null,
+      layers: strategy.layers,
+      size: strategy.size,
+      scope: strategy.scope,
+      evidence: strategy.evidence,
+      evidencePlan: strategy.evidencePlan,
+      waiver: strategy.waiver,
+      upgradeReason: strategy.upgradeReason,
+      inferred: strategy.inferred,
+      description: describeTestStrategy(strategy),
+    });
+  }
+
+  const total = taskStrategies.length;
+  const e2eLike = (layerCounts.e2e ?? 0) + (layerCounts.visual ?? 0) + (layerCounts.weapp ?? 0);
+  const midLayer = (layerCounts.integration ?? 0) + (layerCounts.smoke ?? 0) + (layerCounts.security ?? 0);
+  const unitLayer = layerCounts.unit ?? 0;
+  const warnings = [];
+  if (total > 0 && e2eLike > 0 && unitLayer === 0 && midLayer === 0) {
+    warnings.push('检测到端到端/视觉/小程序证据，但缺少单元或集成层承接，存在倒金字塔风险。');
+  }
+  if (total > 0 && explicit === 0) {
+    warnings.push('当前任务尚未显式声明测试策略，quality 将使用风险推导结果。');
+  }
+  if (total > 0 && evidencePlanned < total && waiverCount === 0) {
+    warnings.push('部分任务缺少 evidence-plan/evidence 或明确豁免理由。');
+  }
+
+  return {
+    total,
+    explicit,
+    inferred,
+    evidencePlanned,
+    evidencePresent,
+    waiverCount,
+    layerCounts,
+    sizeCounts,
+    scopeCounts,
+    tasks: taskStrategies,
+    warnings,
+    recommendations: [
+      '小范围逻辑优先使用单元测试，触达 CLI/API/Agent 契约时升级到集成或契约验证。',
+      '触达用户主路径、页面、小程序、发布或跨系统链路时，保留端到端、截图或运行态证据。',
+      '70/20/10 只作为健康形状参考，不作为硬性比例门禁；实际以风险和本次证据为准。',
+    ],
+  };
+}
+
+export function detectTestStrategyCapabilities({ scripts = {}, files = [], dependencyNames = [] } = {}) {
+  const scriptEntries = Object.entries(scripts);
+  const commandText = scriptEntries.map(([name, command]) => `${name}: ${command}`).join('\n');
+  const fileText = files.map((file) => file.path ?? file).join('\n');
+  const depsText = dependencyNames.join('\n');
+  const haystack = `${commandText}\n${fileText}\n${depsText}`.toLowerCase();
+  const commandNames = {
+    unit: [/unit|node --test|vitest|jest|mocha|pytest/],
+    integration: [/integration|contract|api:test|test:api|test:int/],
+    e2e: [/e2e|playwright|cypress|test:ui/],
+    smoke: [/smoke/],
+    visual: [/visual|screenshot|storybook|chromatic/],
+    performance: [/perf|performance|load|stress|k6|lighthouse|autocannon|wrk/],
+    security: [/security|audit|sast|semgrep|trivy/],
+    weapp: [/weapp|微信小程序|小程序/],
+  };
+  return Object.fromEntries(Object.entries(commandNames).map(([layer, patterns]) => {
+    const commands = scriptEntries
+      .filter(([name, command]) => patterns.some((pattern) => pattern.test(`${name}: ${command}`.toLowerCase())))
+      .map(([name, command]) => `${name}: ${command}`);
+    const present = commands.length > 0 || patterns.some((pattern) => pattern.test(haystack));
+    return [layer, { present, commands }];
+  }));
+}
+
+export function choosePrimaryTestLayer(task = {}) {
+  const strategy = taskTestStrategy(task);
+  return firstKnown(strategy.layers, TEST_LAYER_VALUES, 'unit');
+}