@dommaker/harness 0.16.6 → 0.16.8

package/src/core/constraints/checkers/always-pass.ts

@@ -0,0 +1,22 @@
+/**
+ * 恒通过检查组（工单 21）
+ *
+ * 行为类约束由 promptInjection 注入驱动 + 事后检查，检查器侧恒通过；
+ * Tips 仅作信息提示。这些约束无独立检查逻辑，故集中一处。
+ */
+
+import { alwaysPass } from './types';
+
+// Mnilax guidelines + first-principles（injectPrompt=true，行为层，事后检查）
+export const surgicalChangesOnly = alwaysPass('surgical_changes_only');
+export const noModelForDeterministic = alwaysPass('no_model_for_deterministic');
+export const noConflictBlending = alwaysPass('no_conflict_blending');
+export const readBeforeWrite = alwaysPass('read_before_write');
+export const followConventions = alwaysPass('follow_conventions');
+export const firstPrinciplesFirst = alwaysPass('first_principles_first');
+export const fixTheProblemNotTheGate = alwaysPass('fix_the_problem_not_the_gate');
+export const diagnosisToFixGate = alwaysPass('diagnosis_to_fix_gate');
+
+// Tips — 总是通过（仅提示）
+export const readmeRequired = alwaysPass('readme_required');
+export const docRequiredForPublicApi = alwaysPass('doc_required_for_public_api');

package/src/core/constraints/checkers/capability-sync.ts

@@ -0,0 +1,71 @@
+/**
+ * capability_sync：CAPABILITIES.md 与代码同步检查（工单 21）
+ *
+ * 两步验证：
+ *   1. Git diff 增量 — 当前变更的非测试文件是否在文档中有记录
+ *   2. 全量扫描 — 源码根下所有源文件是否都在 CAPABILITIES.md 中（T-058）
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { readCapabilitiesEntries } from '../capabilities-parser';
+import { detectSourceRoots } from '../../../utils/detect-source-roots';
+import type { ConstraintCheck } from './types';
+
+export const capabilitySync: ConstraintCheck = {
+  id: 'capability_sync',
+  async evaluate(env) {
+    const projectPath = env.projectPath;
+    try {
+      const capabilitiesPath = join(projectPath, 'CAPABILITIES.md');
+      if (!existsSync(capabilitiesPath)) {
+        // 检查是否有代码变更，无变更则跳过
+        const diff = await env.stagedDiffNames();
+        const changedCodeFiles = diff.split('\n').filter(
+          (f: string) => f.endsWith('.ts') || f.endsWith('.tsx') || f.endsWith('.js')
+        );
+        return changedCodeFiles.length === 0;
+      }
+
+      const listedFiles = readCapabilitiesEntries(capabilitiesPath, { secondColumnOnly: true });
+
+      // ── Step 1: Git diff 增量检查 ──
+      const diff = await env.stagedDiffNames();
+      const changedCodeFiles = diff.split('\n').filter(
+        (f: string) => f.endsWith('.ts') || f.endsWith('.tsx') || f.endsWith('.js')
+      );
+
+      if (changedCodeFiles.length > 0 && listedFiles.length > 0) {
+        const significantChanges = changedCodeFiles.filter(
+          (f: string) => !f.includes('__tests__') && !f.includes('.test.') && !f.includes('.spec.')
+        );
+
+        if (significantChanges.length > 0) {
+          const covered = significantChanges.some((changed: string) =>
+            listedFiles.some((listed: string) => changed.endsWith(listed) || changed.includes(listed))
+          );
+          if (!covered) return false;
+        }
+      }
+
+      // ── Step 2: 全量源码根扫描（T-058 修复核心）──
+      if (listedFiles.length > 0) {
+        const sourceRoots = detectSourceRoots(projectPath);
+        for (const root of sourceRoots) {
+          const srcDir = join(projectPath, root);
+          if (existsSync(srcDir)) {
+            for (const file of env.srcScan(root)) {
+              if (!listedFiles.includes(file)) {
+                return false;
+              }
+            }
+          }
+        }
+      }
+
+      return true;
+    } catch {
+      return true; // 检查失败，默认通过
+    }
+  },
+};

package/src/core/constraints/checkers/context-doc-sync.ts

@@ -0,0 +1,36 @@
+/**
+ * context_doc_sync：关键目录必须有 CONTEXT.md（工单 21）
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { loadRawProjectConfig } from '../../project-config-loader';
+import type { ConstraintCheck } from './types';
+
+export const contextDocSync: ConstraintCheck = {
+  id: 'context_doc_sync',
+  async evaluate(env) {
+    const projectPath = env.projectPath;
+    try {
+      const config = loadRawProjectConfig(projectPath) ?? {};
+      const governance = config.governance as Record<string, unknown> | undefined;
+      const contextFiles = governance?.context_files as Record<string, unknown> | undefined;
+
+      if (!contextFiles?.enabled || !Array.isArray(contextFiles.required_dirs)) {
+        return true; // 未配置，跳过
+      }
+
+      const requiredDirs = contextFiles.required_dirs as string[];
+      for (const dir of requiredDirs) {
+        const contextPath = join(projectPath, dir, 'CONTEXT.md');
+        if (!existsSync(contextPath)) {
+          return false;
+        }
+      }
+
+      return true;
+    } catch {
+      return true; // 配置不存在或解析失败，跳过
+    }
+  },
+};

package/src/core/constraints/checkers/docs-freshness.ts

@@ -0,0 +1,116 @@
+/**
+ * docs_freshness：CAPABILITIES.md 文件表 + 能力清单格式 + CLAUDE.md + CHANGELOG（工单 21）
+ *
+ * 1. 文件表格式：CAPABILITIES.md 中列出的文件必须仍存在（防过期引用）
+ * 2. 能力清单格式：FreshnessRunner 配置驱动检查
+ * 3. 无配置时注入内置默认配置（等价旧硬编码行为）
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { loadRawProjectConfig } from '../../project-config-loader';
+import { FreshnessRunner, type FreshnessCheckResult } from '../doc-freshness/runner';
+import { detectSourceRoots } from '../../../utils/detect-source-roots';
+import type { DocFreshnessConfig, DocFreshnessCheck } from '../../../types/project-config';
+import type { ConstraintCheck } from './types';
+
+/**
+ * 内置默认文档新鲜度检查配置
+ *
+ * 等价旧硬编码行为；仅当项目未提供 governance.doc_freshness 配置时使用。
+ */
+function getBuiltInDocFreshnessConfig(): DocFreshnessCheck[] {
+  return [
+    // CONTEXT.md 存在性 — key directories must have CONTEXT.md
+    { type: 'context_docs' },
+    // CHANGELOG 版本 vs package.json 版本 — prevents version drift
+    { type: 'changelog_version' },
+  ];
+}
+
+/**
+ * CAPABILITIES.md 文件表新鲜度：列出的文件路径必须仍存在。
+ * 多根查找：支持不同项目的源码根（harness=src/, studio=apps/api/src/ 等）。
+ * 无表格行（能力清单格式）时跳过。
+ */
+function checkCapabilitiesFreshness(projectPath: string): boolean {
+  try {
+    const capabilitiesPath = join(projectPath, 'CAPABILITIES.md');
+    if (!existsSync(capabilitiesPath)) return true;
+    const content = readFileSync(capabilitiesPath, 'utf-8');
+
+    const listedFiles: string[] = [];
+    const tableRowRegex = /^\|[^|]+\|\s*([^|]+?\.(?:ts|tsx|js|jsx))\s*\|/gm;
+    let match;
+    while ((match = tableRowRegex.exec(content)) !== null) {
+      listedFiles.push(match[1].trim());
+    }
+
+    if (listedFiles.length === 0) return true;
+
+    const sourceRoots = detectSourceRoots(projectPath);
+    const fileExists = (file: string): boolean => {
+      if (existsSync(join(projectPath, file))) return true;
+      for (const root of sourceRoots) {
+        if (existsSync(join(projectPath, root, file))) return true;
+      }
+      return false;
+    };
+
+    const missing = listedFiles.filter(f => !fileExists(f));
+    if (missing.length > 0) {
+      // 报出具体文件名：此前只返回 false，CLI 只能打印通用提示，
+      // 幽灵条目 basename 碰撞时 sync-docs 也不剔除，用户无从定位（2026-08-08 studio CI 4 连红）
+      console.error(`[docs_freshness] CAPABILITIES.md 列出的文件不存在: ${missing.join(', ')}`);
+      return false;
+    }
+
+    return true;
+  } catch {
+    return true;
+  }
+}
+
+export const docsFreshness: ConstraintCheck = {
+  id: 'docs_freshness',
+  async evaluate(env) {
+    const projectPath = env.projectPath;
+
+    // Step 1: 文件表格式 — 检查列出的文件是否还存在
+    if (!checkCapabilitiesFreshness(projectPath)) return false;
+
+    // Step 2: 能力清单格式 + CLAUDE.md + CHANGELOG — 通过 FreshnessRunner
+    try {
+      let freshnessConfig: DocFreshnessConfig | undefined;
+      let requiredDirs: string[] | undefined;
+
+      try {
+        const raw = loadRawProjectConfig(projectPath);
+        const governance = raw?.governance as Record<string, unknown> | undefined;
+        freshnessConfig = governance?.doc_freshness as DocFreshnessConfig | undefined;
+
+        const contextFiles = governance?.context_files as Record<string, unknown> | undefined;
+        if (contextFiles?.enabled && Array.isArray(contextFiles.required_dirs)) {
+          requiredDirs = contextFiles.required_dirs as string[];
+        }
+      } catch {
+        // 配置解析失败，使用默认
+      }
+
+      const runner = new FreshnessRunner();
+      let results: FreshnessCheckResult[];
+
+      if (freshnessConfig?.checks && freshnessConfig.checks.length > 0) {
+        results = runner.runAll(freshnessConfig, projectPath, { requiredDirs });
+      } else {
+        results = runner.runAll({ checks: getBuiltInDocFreshnessConfig() }, projectPath, { requiredDirs });
+      }
+
+      if (!results.every(r => r.pass)) return false;
+    } catch {
+      // FreshnessRunner 失败不影响整体
+    }
+
+    return true;
+  },
+};

package/src/core/constraints/checkers/guideline-flags.ts

@@ -0,0 +1,30 @@
+/**
+ * 指导原则层轻量检查（工单 21）：纯上下文证据标志判定，无 I/O
+ */
+
+import { contextFlag } from './types';
+
+export const noFixWithoutRootCause = contextFlag(
+  'no_fix_without_root_cause',
+  ctx => ctx.hasRootCauseInvestigation === true
+);
+
+export const noCodeWithoutTest = contextFlag(
+  'no_code_without_test',
+  ctx => ctx.hasFailingTest === true
+);
+
+export const simplestSolutionFirst = contextFlag(
+  'simplest_solution_first',
+  ctx => ctx.hasReuseCheck === true
+);
+
+export const noCreationWithoutReuseCheck = contextFlag(
+  'no_creation_without_reuse_check',
+  ctx => ctx.hasReuseCheck === true
+);
+
+export const noSkillWithoutTest = contextFlag(
+  'no_skill_without_test',
+  ctx => ctx.hasTest === true
+);

package/src/core/constraints/checkers/index.ts

@@ -0,0 +1,114 @@
+/**
+ * 约束检查器注册表（工单 21）
+ *
+ * checker.ts 编排层通过 getConstraintCheck(id) 查找实现，
+ * 未注册的约束默认通过（保持历史 default 分支语义）。
+ */
+
+import type { ConstraintCheck } from './types';
+
+import {
+  noSelfApproval,
+  noCompletionWithoutVerification,
+  incrementalProgress,
+  verifyExternalCapability,
+  noImplementationWithoutRequirementReview,
+  noImplementationWithoutRequirement,
+  preferWorktree,
+  noClaimWithoutEvidence,
+  noDeleteWithoutContext,
+  twoStageReviewRequired,
+} from './iron-flags';
+import {
+  noFixWithoutRootCause,
+  noCodeWithoutTest,
+  simplestSolutionFirst,
+  noCreationWithoutReuseCheck,
+  noSkillWithoutTest,
+} from './guideline-flags';
+import {
+  surgicalChangesOnly,
+  noModelForDeterministic,
+  noConflictBlending,
+  readBeforeWrite,
+  followConventions,
+  firstPrinciplesFirst,
+  fixTheProblemNotTheGate,
+  diagnosisToFixGate,
+  readmeRequired,
+  docRequiredForPublicApi,
+} from './always-pass';
+import { noBypassCheckpoint } from './no-bypass-checkpoint';
+import { noTestSimplification } from './no-test-simplification';
+import { noFuzzyCompletionClaim } from './no-fuzzy-completion-claim';
+import { noPerformativeAgreement } from './no-performative-agreement';
+import { noExcusePatterns } from './no-excuse-patterns';
+import { noAnyType } from './no-any-type';
+import { capabilitySync } from './capability-sync';
+import { noSimplificationWithoutApproval } from './no-simplification-without-approval';
+import { testCoverageRequired } from './test-coverage';
+import { contextDocSync } from './context-doc-sync';
+import { docsFreshness } from './docs-freshness';
+import { yagniCheck } from './yagni';
+
+const CHECKS: ConstraintCheck[] = [
+  // Iron Laws
+  noBypassCheckpoint,
+  noSelfApproval,
+  noCompletionWithoutVerification,
+  noTestSimplification,
+  incrementalProgress,
+  verifyExternalCapability,
+  noImplementationWithoutRequirementReview,
+  noImplementationWithoutRequirement,
+  preferWorktree,
+  noFuzzyCompletionClaim,
+  noClaimWithoutEvidence,
+  noDeleteWithoutContext,
+  noPerformativeAgreement,
+  twoStageReviewRequired,
+  // Guidelines
+  noFixWithoutRootCause,
+  noCodeWithoutTest,
+  noAnyType,
+  simplestSolutionFirst,
+  noCreationWithoutReuseCheck,
+  capabilitySync,
+  noSimplificationWithoutApproval,
+  noSkillWithoutTest,
+  testCoverageRequired,
+  contextDocSync,
+  docsFreshness,
+  noExcusePatterns,
+  yagniCheck,
+  // 行为类（promptInjection 驱动）恒通过
+  surgicalChangesOnly,
+  noModelForDeterministic,
+  noConflictBlending,
+  readBeforeWrite,
+  followConventions,
+  firstPrinciplesFirst,
+  fixTheProblemNotTheGate,
+  diagnosisToFixGate,
+  // Tips
+  readmeRequired,
+  docRequiredForPublicApi,
+];
+
+const registry = new Map<string, ConstraintCheck>(CHECKS.map(c => [c.id, c]));
+
+/**
+ * 按约束 ID 查找检查实现；未注册返回 undefined（编排层默认通过）
+ */
+export function getConstraintCheck(id: string): ConstraintCheck | undefined {
+  return registry.get(id);
+}
+
+/**
+ * 已注册的检查实现数量（诊断/测试用）
+ */
+export function registeredCheckCount(): number {
+  return registry.size;
+}
+
+export type { ConstraintCheck, CheckEnv } from './types';

package/src/core/constraints/checkers/iron-flags.ts

@@ -0,0 +1,62 @@
+/**
+ * 铁律层轻量检查（工单 21）：纯上下文证据标志判定，无 I/O
+ */
+
+import { contextFlag } from './types';
+
+export const noSelfApproval = contextFlag(
+  'no_self_approval',
+  ctx => ctx.hasTest === true
+);
+
+export const noCompletionWithoutVerification = contextFlag(
+  'no_completion_without_verification',
+  ctx => ctx.hasVerificationEvidence === true
+);
+
+export const incrementalProgress = contextFlag(
+  'incremental_progress',
+  // undefined = 未验证 → Iron Law 必须显式确认
+  ctx => ctx.hasSingleTask === true
+);
+
+export const verifyExternalCapability = contextFlag(
+  'verify_external_capability',
+  ctx => ctx.hasExternalCapabilityVerification === true
+);
+
+export const noImplementationWithoutRequirementReview = contextFlag(
+  'no_implementation_without_requirement_review',
+  ctx => ctx.hasRequirementReview === true
+);
+
+export const noImplementationWithoutRequirement = contextFlag(
+  'no_implementation_without_requirement',
+  ctx => ctx.hasRequirement === true
+);
+
+export const preferWorktree = contextFlag(
+  'prefer_worktree',
+  ctx => ctx.hasWorktree === true
+);
+
+export const noClaimWithoutEvidence = contextFlag(
+  'no_claim_without_evidence',
+  ctx =>
+    ctx.hasVerificationEvidence === true ||
+    (ctx.taskDescription || '').includes('test') ||
+    ctx.hasTest === true
+);
+
+export const noDeleteWithoutContext = contextFlag(
+  'no_delete_without_context',
+  ctx =>
+    ctx.hasRequirementReview === true ||
+    ctx.hasRequirement === true ||
+    ctx.isExistingDesign === true
+);
+
+export const twoStageReviewRequired = contextFlag(
+  'two_stage_review_required',
+  ctx => ctx.hasTwoStageReview === true
+);

package/src/core/constraints/checkers/no-any-type.ts

@@ -0,0 +1,42 @@
+/**
+ * no_any_type：变更 TS 文件不得出现 `: any`（工单 21）
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import type { ConstraintCheck } from './types';
+
+export const noAnyType: ConstraintCheck = {
+  id: 'no_any_type',
+  async evaluate(env) {
+    try {
+      const changedFiles = env.context.changedFiles || [];
+      const filesToCheck = changedFiles.filter(
+        f => f.endsWith('.ts') || f.endsWith('.tsx')
+      );
+
+      if (filesToCheck.length === 0) {
+        return true; // 无 TS 文件变更
+      }
+
+      for (const file of filesToCheck) {
+        if (!existsSync(file)) continue;
+        try {
+          const content = readFileSync(file, 'utf-8');
+          // 检查 : any（排除注释和字符串）
+          for (const line of content.split('\n')) {
+            if (line.trim().startsWith('//') || line.trim().startsWith('*')) continue;
+            if (line.includes(': any') && !line.includes('// ') && !line.includes('/*')) {
+              return false; // 发现 any 类型
+            }
+          }
+        } catch {
+          // 文件读取失败，忽略
+        }
+      }
+
+      return true;
+    } catch {
+      return true; // 检查失败，默认通过
+    }
+  },
+};

package/src/core/constraints/checkers/no-bypass-checkpoint.ts

@@ -0,0 +1,40 @@
+/**
+ * no_bypass_checkpoint：检查变更文件内容是否有 skip/bypass 关键词（工单 21）
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import type { ConstraintCheck } from './types';
+
+const BYPASS_PATTERNS = [
+  /\.skip\(/,            // Jest/Vitest skip
+  /\.bypass\s*=/,        // bypass flag
+  /skip:\s*true/,        // skip option
+  /bypass\s*checkpoint/, // explicit bypass
+  /\/\/\s*skip/,         // comment skip
+];
+
+export const noBypassCheckpoint: ConstraintCheck = {
+  id: 'no_bypass_checkpoint',
+  async evaluate(env) {
+    const changedFiles = env.context.changedFiles || [];
+    if (changedFiles.length === 0) {
+      return true; // 无变更文件，默认通过
+    }
+
+    for (const file of changedFiles) {
+      if (!existsSync(file)) continue;
+      try {
+        const content = readFileSync(file, 'utf-8');
+        for (const pattern of BYPASS_PATTERNS) {
+          if (pattern.test(content)) {
+            return false; // 发现 bypass 关键词
+          }
+        }
+      } catch {
+        // 文件读取失败，忽略
+      }
+    }
+
+    return true;
+  },
+};

package/src/core/constraints/checkers/no-excuse-patterns.ts

@@ -0,0 +1,24 @@
+/**
+ * no_excuse_patterns：完成声明不得包含借口模式（工单 21）
+ */
+
+import type { ConstraintCheck } from './types';
+
+const EXCUSE_PATTERNS = [
+  /稍后修复/,
+  /小问题/,
+  /不影响功能/,
+  /以后再说/,
+  /先这样/,
+  /临时方案/,
+  /暂时这样/,
+];
+
+export const noExcusePatterns: ConstraintCheck = {
+  id: 'no_excuse_patterns',
+  evaluate(env) {
+    const text = env.context.completionClaimText || env.context.taskDescription || '';
+    if (!text) return true;
+    return !EXCUSE_PATTERNS.some(p => p.test(text));
+  },
+};

package/src/core/constraints/checkers/no-fuzzy-completion-claim.ts

@@ -0,0 +1,33 @@
+/**
+ * no_fuzzy_completion_claim：完成声明不得包含模糊词（工单 21）
+ */
+
+import type { ConstraintCheck } from './types';
+
+const FUZZY_PATTERNS = [
+  /应该没问题/,
+  /应该可以/,
+  /大概/,
+  /可能/,
+  /好像/,
+  /似乎/,
+  /差不多/,
+  /基本完成/,
+  /大部分/,
+  // audit-learned (2026-05-18): unverified completion claims
+  /我记得删[过掉]了/,
+  /之前说删了/,
+  /已删除.*但/,
+  /大部分实现/,
+  /大部分完成/,
+  /已修复.*但/,
+];
+
+export const noFuzzyCompletionClaim: ConstraintCheck = {
+  id: 'no_fuzzy_completion_claim',
+  evaluate(env) {
+    const text = env.context.completionClaimText || '';
+    if (!text) return true; // 没有文本时默认通过（由其他检查覆盖）
+    return !FUZZY_PATTERNS.some(p => p.test(text));
+  },
+};

package/src/core/constraints/checkers/no-performative-agreement.ts

@@ -0,0 +1,22 @@
+/**
+ * no_performative_agreement：表演性同意辅助检查（工单 21）
+ *
+ * 主要由 promptInjection 驱动，此处做辅助检查。
+ */
+
+import type { ConstraintCheck } from './types';
+
+const PERFORMATIVE_START = /^(好的[，,]*\s*我[来去]做|明白了[，,]*|没问题[，,]*|ok[，,]*\s*i.?ll)/i;
+
+export const noPerformativeAgreement: ConstraintCheck = {
+  id: 'no_performative_agreement',
+  evaluate(env) {
+    const text = env.context.taskDescription || '';
+    if (!text) return true;
+    // 以表演性模式开头且总长度很短 → 视为表演性同意
+    if (PERFORMATIVE_START.test(text) && text.length < 100) {
+      return false;
+    }
+    return true;
+  },
+};

package/src/core/constraints/checkers/no-simplification-without-approval.ts

@@ -0,0 +1,29 @@
+/**
+ * no_simplification_without_approval：staged diff 不得含简化关键词（工单 21）
+ */
+
+import type { ConstraintCheck } from './types';
+
+const SIMPLIFICATION_PATTERNS = [
+  /removed\s*test/i,
+  /simplified\s*logic/i,
+  /removed\s*validation/i,
+  /skip\s*check/i,
+];
+
+export const noSimplificationWithoutApproval: ConstraintCheck = {
+  id: 'no_simplification_without_approval',
+  async evaluate(env) {
+    try {
+      const diff = await env.stagedDiff();
+      for (const pattern of SIMPLIFICATION_PATTERNS) {
+        if (pattern.test(diff)) {
+          return false; // 发现简化关键词
+        }
+      }
+      return true;
+    } catch {
+      return true; // 检查失败，默认通过
+    }
+  },
+};

package/src/core/constraints/checkers/no-test-simplification.ts

@@ -0,0 +1,28 @@
+/**
+ * no_test_simplification：检查 staged diff 是否删除了测试（工单 21）
+ */
+
+import type { ConstraintCheck } from './types';
+
+const DELETED_TEST_PATTERNS = [
+  /^-\s*(test|it|describe)\s*\(/, // 删除 test/it/describe
+  /^-\s*expect\s*\(/,              // 删除 expect
+  /^-\s*\/\/\s*test/,              // 删除注释的 test
+];
+
+export const noTestSimplification: ConstraintCheck = {
+  id: 'no_test_simplification',
+  async evaluate(env) {
+    try {
+      const diff = await env.stagedDiff();
+      for (const pattern of DELETED_TEST_PATTERNS) {
+        if (pattern.test(diff)) {
+          return false; // 发现删除测试
+        }
+      }
+      return true;
+    } catch {
+      return true; // git 命令失败，默认通过
+    }
+  },
+};