@dommaker/harness 0.16.9 → 0.17.1

package/src/cli/commands/check.ts

@@ -1,8 +1,9 @@
 /**
  * harness check 命令
  *
- * 检查约束是否满足（三层：Iron Laws / Guidelines / Tips）
- * 工单 23：触发条件与证据检测迁至 core/constraints/context-builder；--preset 接入 applyPreset
+ * 检查约束是否满足（check 层：Iron Laws / Guidelines；prompt 层仅注入不检查）
+ * 工单 23：触发条件与证据检测迁至 core/constraints/context-builder；--preset 经 mergeConstraints 生效
+ * ADR-0001：约束集统一走 mergeConstraints 生效集链路（preset/config 禁用/custom/scenes）
  */
 
 import chalk from 'chalk';
@@ -10,10 +11,11 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { constraintChecker } from '../../core/constraints/checker';
 import { getTraceCollector } from '../../monitoring/traces';
-import { IRON_LAWS, GUIDELINES, TIPS } from '../../core/constraints/definitions';
+import { IRON_LAWS, GUIDELINES, PROMPTS } from '../../core/constraints/definitions';
 import { ProjectConfigLoader } from '../../core/project-config-loader';
 import { buildConstraintContext } from '../../core/constraints/context-builder';
-import { applyPreset } from '../../presets';
+import { detectInjectionDrift } from '../../core/constraints/injection-drift';
+import { DEFAULT_TRACE_FILE } from '../../types/trace';
 import type { ConstraintTrigger } from '../../types/constraint';
 
 export interface CheckOptions {
@@ -41,13 +43,22 @@ export async function check(options: CheckOptions): Promise<void> {
     configLoader.load();
     constraintChecker.setTraceRecorder(getTraceCollector());
 
-    if (configLoader.hasCustomConfig()) {
-      const merged = configLoader.mergeConstraints();
-      constraintChecker.setCustomConfig(merged);
+    // 生效约束集（ADR-0001）：内置 → preset → config.yml 禁用 → custom 追加 → scenes 过滤。
+    // --preset 仅在没有项目自定义配置时覆盖 config.yml 的 preset（保持工单 23 语义：
+    // 项目自定义配置优先于 CLI 预设）。
+    const merged = configLoader.hasCustomConfig()
+      ? configLoader.mergeConstraints()
+      : configLoader.mergeConstraints({ preset: options.preset || 'standard' });
+    constraintChecker.setCustomConfig(merged);
+    if (merged.custom.length > 0) {
       console.log(chalk.gray(`自定义约束: ${merged.custom.length} 条`));
-      if (merged.disabled.length > 0) {
-        console.log(chalk.gray(`已禁用约束: ${merged.disabled.join(', ')}`));
-      }
+    }
+    if (merged.disabled.length > 0) {
+      console.log(chalk.gray(`已禁用约束: ${merged.disabled.join(', ')}`));
+    }
+    const unknownIds = merged.unknownIds ?? [];
+    if (unknownIds.length > 0) {
+      console.log(chalk.yellow(`⚠️  配置中存在未知约束 id（已忽略，可清理）: ${unknownIds.join(', ')}`));
     }
 
     // 构建上下文（工单 23：触发条件与证据检测收敛至 core/constraints/context-builder）
@@ -60,28 +71,26 @@ export async function check(options: CheckOptions): Promise<void> {
     if (changedFiles.length > 0) {
       console.log(chalk.gray(`变更文件: ${changedFiles.length} 个`));
     }
-    console.log(chalk.gray(`触发条件: ${context.operation}`));
-
-    // 预设（工单 23：--preset 真正生效；项目自定义配置优先于预设）
-    let presetConfig;
-    if (!configLoader.hasCustomConfig()) {
-      try {
-        presetConfig = applyPreset(options.preset || 'standard');
-      } catch {
-        presetConfig = undefined; // 未知预设名回退内置全集
-      }
-    }
+    console.log(chalk.gray(`触发条件: ${[context.operation, ...(context.extraTriggers ?? [])].join(', ')}`));
 
     // 执行三层检查
-    const result = await constraintChecker.checkConstraints(context, presetConfig);
+    const result = await constraintChecker.checkConstraints(context);
 
     // 输出结果
     console.log();
 
+    // skipped（约定未采用/证据未接线）单独列示，不进 pass/fail 统计（ADR-0001）
+    const skippedResults = [
+      ...result.ironLaws,
+      ...result.guidelines,
+      ...result.tips,
+    ].filter(r => r.skipped);
+
     // Iron Laws
-    const ironLawViolations = result.ironLaws.filter(r => !r.satisfied);
-    if (ironLawViolations.length === 0 && result.ironLaws.length > 0) {
-      console.log(chalk.green(`✅ 铁律: 全部通过 (${result.ironLaws.length} 条)`));
+    const evaluatedIronLaws = result.ironLaws.filter(r => !r.skipped);
+    const ironLawViolations = evaluatedIronLaws.filter(r => !r.satisfied);
+    if (ironLawViolations.length === 0 && evaluatedIronLaws.length > 0) {
+      console.log(chalk.green(`✅ 铁律: 全部通过 (${evaluatedIronLaws.length} 条)`));
     } else if (ironLawViolations.length > 0) {
       console.log(chalk.red(`❌ 铁律违规: ${ironLawViolations.length} 条`));
       ironLawViolations.forEach(r => {
@@ -104,8 +113,9 @@ export async function check(options: CheckOptions): Promise<void> {
         }
       });
     } else if (result.guidelines.length > 0) {
-      const passedGuidelines = result.guidelines.filter(r => r.satisfied).length;
-      console.log(chalk.green(`✅ 指导原则: ${passedGuidelines}/${result.guidelines.length} 通过`));
+      const evaluatedGuidelines = result.guidelines.filter(r => !r.skipped);
+      const passedGuidelines = evaluatedGuidelines.filter(r => r.satisfied).length;
+      console.log(chalk.green(`✅ 指导原则: ${passedGuidelines}/${evaluatedGuidelines.length} 通过`));
     }
 
     // Tips
@@ -118,6 +128,36 @@ export async function check(options: CheckOptions): Promise<void> {
       });
     }
 
+    // Skipped：约定未采用 / 证据未接线，未评估（不计通过/失败）
+    if (skippedResults.length > 0) {
+      console.log(chalk.gray(`⏭️  跳过评估: ${skippedResults.length} 条（约定未采用或证据未接线，不计通过/失败）`));
+      skippedResults.forEach(r => {
+        console.log(chalk.gray(`   - ${r.id}`));
+      });
+    }
+
+    // 注入漂移校验（ADR-0001 决策 7）：黄色警告块，不改 exit code、不影响门禁结果。
+    // 无漂移/未注入零输出；漂移检测自身异常静默吞掉，绝不影响 check。
+    try {
+      const drift = detectInjectionDrift(projectPath);
+      if (drift.hasDrift) {
+        console.log();
+        console.log(chalk.yellow('⚠️  检测到 CLAUDE.md 约束注入漂移（仅警告，不阻断）:'));
+        if (drift.versionDrift) {
+          console.log(chalk.yellow(`   ⚠️⚠️ 注入段版本 (${drift.versionDrift.actual}) ≠ 已安装 harness 版本 (${drift.versionDrift.expected})：agent 上下文中的规则与已安装 harness 版本不一致`));
+        }
+        if (drift.contentDrift) {
+          console.log(chalk.yellow(`   内容漂移: 缺失 ${drift.contentDrift.missing.length} 条 / 多余 ${drift.contentDrift.extra.length} 条（条目级差异见 harness constraints report）`));
+        }
+        if (drift.duplicateHeading) {
+          console.log(chalk.yellow('   检测到重复的 "## Governance Rules" 章节'));
+        }
+        console.log(chalk.yellow(`   修复: ${drift.fixHint}`));
+      }
+    } catch {
+      // 漂移检测失败不影响 check 结果
+    }
+
     console.log();
     console.log(chalk.green('✅ 约束检查通过'));
 
@@ -140,7 +180,7 @@ export async function check(options: CheckOptions): Promise<void> {
  * 智能提示：检查是否需要提示用户下一步操作
  */
 async function getSmartHint(projectPath: string): Promise<string | null> {
-  const tracesPath = path.join(projectPath, '.harness', 'traces', 'execution.log');
+  const tracesPath = path.join(projectPath, DEFAULT_TRACE_FILE);
   const statePath = path.join(projectPath, '.harness', '.state.json');
   
   // 检查 trace 文件是否存在
@@ -172,13 +212,7 @@ async function getSmartHint(projectPath: string): Promise<string | null> {
     state.shownHints.push('trace_50');
   }
   
-  // 条件 2: 记录数达到 100 且从未运行过诊断
-  if (traceCount >= 100 && !state.lastDiagnoseRun && !state.shownHints.includes('flow_suggest')) {
-    hints.push('💡 数据充足，建议运行 harness flow 查看诊断');
-    state.shownHints.push('flow_suggest');
-  }
-  
-  // 条件 3: 检查异常趋势（简单检查绕过率）
+  // 条件 2: 检查异常趋势（简单检查绕过率）
   const bypassCount = lines.filter(line => {
     try {
       const trace = JSON.parse(line);
@@ -231,9 +265,9 @@ export function listLaws(): void {
     console.log();
   });
 
-  // Tips
-  console.log(chalk.blue('🔵 提示 (Tips) - 信息性，可忽略:\n'));
-  Object.values(TIPS).forEach(constraint => {
+  // Prompts（ADR-0001：纯注入层，不执行检查）
+  console.log(chalk.blue('🔵 提示 (Prompts) - 纯文本注入，不参与检查:\n'));
+  Object.values(PROMPTS).forEach(constraint => {
     console.log(chalk.blue(`  ${constraint.id}`));
     console.log(chalk.gray(`    ${constraint.rule}`));
     console.log(chalk.gray(`    ${constraint.message}`));

package/src/cli/commands/constraints-report.ts

@@ -0,0 +1,234 @@
+/**
+ * harness constraints report —— 约束使用报告（ADR-0001 决策 3/4）
+ *
+ * 只读。面向"人审约束"场景：
+ * - check 层统计表（total/pass/fail/skip、fail 率、首次/最近触发）
+ * - 退役候选诊断（零触发/零拦截/不可评估/高噪），retire 交互模式的数据源
+ * - 当前生效 prompt 注入清单
+ * - 配置健康（unknownIds 残留提示）
+ * - --export [file]：脱敏 markdown 摘要（不含项目路径）
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import chalk from 'chalk';
+import {
+  buildConstraintsUsageReport,
+  DEFAULT_DIAGNOSE_THRESHOLDS,
+  type ConstraintsUsageReport,
+  type ConstraintUsageStats,
+  type DiagnoseThresholds,
+  type RetireCandidate,
+} from '../../core/constraints/usage-report';
+import { getConstraintsMeta } from './constraints';
+import { detectInjectionDrift, type InjectionDrift } from '../../core/constraints/injection-drift';
+
+export interface ConstraintsReportOptions {
+  projectPath?: string;
+  /** --export [file]：true = 默认路径；string = 指定文件 */
+  export?: boolean | string;
+  json?: boolean;
+  /** 零拦截候选的最小评估样本数 */
+  zeroInterceptMin?: number;
+  /** 高噪候选 fail 率阈值 */
+  noiseFailRate?: number;
+  /** 高噪候选最小评估样本数 */
+  noiseMinTotal?: number;
+}
+
+const CANDIDATE_KIND_LABEL: Record<RetireCandidate['kind'], string> = {
+  zero_trigger: '零触发',
+  unevaluable: '不可评估',
+  high_noise: '高噪',
+  zero_intercept: '零拦截',
+};
+
+function formatTime(ts: number | undefined): string {
+  return ts === undefined ? '-' : new Date(ts).toISOString().slice(0, 10);
+}
+
+function formatPct(rate: number): string {
+  return `${Math.round(rate * 100)}%`;
+}
+
+/**
+ * 渲染统计表（纯文本行，供 console 与 export 共用单行内容）
+ */
+function renderStatsRow(s: ConstraintUsageStats): string {
+  return `${s.id}  total=${s.total} pass=${s.pass} fail=${s.fail} skip=${s.skip} fail率=${formatPct(s.failRate)} 首次=${formatTime(s.firstAt)} 最近=${formatTime(s.lastAt)}`;
+}
+
+/**
+ * 渲染脱敏 markdown 摘要（ADR-0001 决策 4）
+ *
+ * 脱敏约束：不含 projectPath 等本地敏感信息；
+ * 内容为 harness 版本、日期、统计表、候选清单、配置健康。
+ */
+export function renderExportMarkdown(
+  report: ConstraintsUsageReport,
+  version: string,
+  now: Date = new Date()
+): string {
+  const lines: string[] = [];
+  lines.push('# Harness Constraints Report');
+  lines.push('');
+  lines.push(`- harness 版本: ${version}`);
+  lines.push(`- 日期: ${now.toISOString().slice(0, 10)}`);
+  lines.push('');
+
+  lines.push('## 统计表（check 层）');
+  lines.push('');
+  lines.push('| id | total | pass | fail | skip | fail 率 | 首次触发 | 最近触发 |');
+  lines.push('| --- | ---: | ---: | ---: | ---: | ---: | --- | --- |');
+  for (const s of report.stats) {
+    lines.push(
+      `| ${s.id} | ${s.total} | ${s.pass} | ${s.fail} | ${s.skip} | ${formatPct(s.failRate)} | ${formatTime(s.firstAt)} | ${formatTime(s.lastAt)} |`
+    );
+  }
+  lines.push('');
+
+  lines.push('## 退役候选');
+  lines.push('');
+  if (report.candidates.length === 0) {
+    lines.push('（无候选）');
+  } else {
+    for (const c of report.candidates) {
+      lines.push(`- [${CANDIDATE_KIND_LABEL[c.kind]}] \`${c.id}\` — ${c.reason}`);
+    }
+  }
+  lines.push('');
+
+  if (report.lint.unknownIds.length > 0) {
+    lines.push('## 配置健康');
+    lines.push('');
+    for (const id of report.lint.unknownIds) {
+      lines.push(`- config.yml 中禁用了不存在/已移除的约束 id: \`${id}\``);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * 渲染"注入漂移"小节的文本行（ADR-0001 决策 7：详细条目级差异进 report）
+ *
+ * 返回纯文本行数组（不含 chalk 着色），调用方逐行 console.log。
+ */
+export function renderInjectionDriftLines(drift: InjectionDrift): string[] {
+  const lines: string[] = [];
+  if (drift.notInjected) {
+    lines.push('  CLAUDE.md 无约束注入标记段（未注入，不算漂移）；可运行 npx harness init 注入');
+    if (drift.duplicateHeading) {
+      lines.push('  另检测到多个 "## Governance Rules" 标题（历史遗留重复章节），建议手工清理后重跑 npx harness init');
+    }
+    return lines;
+  }
+  if (!drift.hasDrift) {
+    lines.push('  无漂移');
+    return lines;
+  }
+  if (drift.versionDrift) {
+    lines.push(`  版本漂移: 注入段版本 (${drift.versionDrift.actual}) ≠ 当前 harness 版本 (${drift.versionDrift.expected})`);
+  }
+  if (drift.contentDrift) {
+    lines.push('  内容漂移（条目级差异）:');
+    for (const l of drift.contentDrift.missing) {
+      lines.push(`    缺失: ${l}`);
+    }
+    for (const l of drift.contentDrift.extra) {
+      lines.push(`    多余: ${l}`);
+    }
+  }
+  if (drift.duplicateHeading) {
+    lines.push('  重复章节: 标记段之外还存在另一个 "## Governance Rules" 标题');
+  }
+  lines.push(`  修复: ${drift.fixHint}`);
+  return lines;
+}
+
+/**
+ * CLI handler: harness constraints report
+ */
+export async function constraintsReport(options: ConstraintsReportOptions = {}): Promise<void> {
+  const projectRoot = options.projectPath || process.cwd();
+  const thresholds: Partial<DiagnoseThresholds> = {};
+  if (options.zeroInterceptMin !== undefined) thresholds.zeroInterceptMinEvaluated = options.zeroInterceptMin;
+  if (options.noiseFailRate !== undefined) thresholds.highNoiseFailRate = options.noiseFailRate;
+  if (options.noiseMinTotal !== undefined) thresholds.highNoiseMinEvaluated = options.noiseMinTotal;
+
+  const report = buildConstraintsUsageReport(projectRoot, thresholds);
+
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  console.log(chalk.blue('📊 约束使用报告'));
+  if (!report.traceFileExists) {
+    console.log(chalk.gray('   （trace 文件不存在，全部按零触发统计）'));
+  }
+  console.log();
+
+  // 统计表
+  console.log(chalk.bold('统计表（check 层）:'));
+  for (const s of report.stats) {
+    console.log(`  ${renderStatsRow(s)}`);
+  }
+  console.log();
+
+  // 候选诊断
+  console.log(chalk.bold(`退役候选（${report.candidates.length} 条，阈值: 零拦截≥${thresholds.zeroInterceptMinEvaluated ?? DEFAULT_DIAGNOSE_THRESHOLDS.zeroInterceptMinEvaluated} 次评估, 高噪 fail率>${Math.round((thresholds.highNoiseFailRate ?? DEFAULT_DIAGNOSE_THRESHOLDS.highNoiseFailRate) * 100)}% 且 ≥${thresholds.highNoiseMinEvaluated ?? DEFAULT_DIAGNOSE_THRESHOLDS.highNoiseMinEvaluated} 次评估）:`));
+  if (report.candidates.length === 0) {
+    console.log(chalk.green('  （无候选）'));
+  } else {
+    for (const c of report.candidates) {
+      console.log(`  [${CANDIDATE_KIND_LABEL[c.kind]}] ${c.id} — ${c.reason}`);
+    }
+    console.log(chalk.gray('  可运行 `harness constraints retire` 交互式处理候选'));
+  }
+  console.log();
+
+  // 注入清单
+  console.log(chalk.bold(`当前生效 prompt 注入（${report.activePromptIds.length} 条）:`));
+  for (const id of report.activePromptIds) {
+    console.log(`  ${id}`);
+  }
+  console.log();
+
+  // 配置健康
+  if (report.lint.unknownIds.length > 0) {
+    console.log(chalk.yellow('⚠️  配置健康:'));
+    for (const id of report.lint.unknownIds) {
+      console.log(chalk.yellow(`  config.yml 中禁用了不存在/已移除的约束 id: ${id}（残留配置，建议清理）`));
+    }
+    console.log();
+  }
+
+  // 注入漂移（ADR-0001 决策 7：条目级差异 + 修复指引；--export 摘要不含本地漂移状态）
+  console.log(chalk.bold('注入漂移:'));
+  const drift = detectInjectionDrift(projectRoot);
+  for (const line of renderInjectionDriftLines(drift)) {
+    console.log(drift.hasDrift ? chalk.yellow(line) : line);
+  }
+  console.log();
+
+  // --export
+  if (options.export !== undefined && options.export !== false) {
+    const version = getConstraintsMeta().version;
+    const now = new Date();
+    const markdown = renderExportMarkdown(report, version, now);
+
+    let exportPath: string;
+    if (typeof options.export === 'string' && options.export.length > 0) {
+      exportPath = path.isAbsolute(options.export) ? options.export : path.join(projectRoot, options.export);
+    } else {
+      const date = now.toISOString().slice(0, 10).replace(/-/g, '');
+      exportPath = path.join(projectRoot, '.harness', 'reports', `constraints-${date}.md`);
+    }
+
+    fs.mkdirSync(path.dirname(exportPath), { recursive: true });
+    fs.writeFileSync(exportPath, markdown, 'utf-8');
+    console.log(chalk.green(`✅ 脱敏报告已导出: ${exportPath}`));
+  }
+}