@dommaker/harness 0.16.8 → 0.17.0

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

@@ -1,5 +1,8 @@
 /**
  * context_doc_sync：关键目录必须有 CONTEXT.md（工单 21）
+ *
+ * ADR-0001 存在性探测：项目未配置 governance.context_files 约定
+ * （未启用或无 required_dirs）时返回 'skip'，不计 pass/fail。
  */
 
 import { existsSync } from 'fs';
@@ -17,10 +20,14 @@ export const contextDocSync: ConstraintCheck = {
       const contextFiles = governance?.context_files as Record<string, unknown> | undefined;
 
       if (!contextFiles?.enabled || !Array.isArray(contextFiles.required_dirs)) {
-        return true; // 未配置，跳过
+        return 'skip'; // 未配置 context_files 约定，跳过评估
       }
 
       const requiredDirs = contextFiles.required_dirs as string[];
+      if (requiredDirs.length === 0) {
+        return 'skip'; // 无目标目录，约定未生效
+      }
+
       for (const dir of requiredDirs) {
         const contextPath = join(projectPath, dir, 'CONTEXT.md');
         if (!existsSync(contextPath)) {
@@ -30,7 +37,7 @@ export const contextDocSync: ConstraintCheck = {
 
       return true;
     } catch {
-      return true; // 配置不存在或解析失败，跳过
+      return 'skip'; // 配置不存在或解析失败 = 无法判定约定，跳过
     }
   },
 };

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

@@ -1,6 +1,7 @@
 /**
  * docs_freshness：CAPABILITIES.md 文件表 + 能力清单格式 + CLAUDE.md + CHANGELOG（工单 21）
  *
+ * 0. 存在性探测（ADR-0001）：项目无任何 freshness 配置/目标时 skip，不计 pass/fail
  * 1. 文件表格式：CAPABILITIES.md 中列出的文件必须仍存在（防过期引用）
  * 2. 能力清单格式：FreshnessRunner 配置驱动检查
  * 3. 无配置时注入内置默认配置（等价旧硬编码行为）
@@ -71,11 +72,53 @@ function checkCapabilitiesFreshness(projectPath: string): boolean {
   }
 }
 
+/**
+ * ADR-0001 存在性探测：项目是否存在任何 freshness 配置/检查目标。
+ *
+ * 判定信号（任一命中即视为采用了文档新鲜度约定）：
+ * - 配置了 governance.doc_freshness.checks
+ * - 配置了 governance.context_files（enabled + 非空 required_dirs）
+ * - 项目根存在 CAPABILITIES.md
+ * - 项目根存在 CHANGELOG.md / CHANGELOG
+ *
+ * 全部缺失 → 项目未采用该约定，调用方应 skip 而非评估内置默认配置。
+ */
+function hasFreshnessTargets(projectPath: string): boolean {
+  if (existsSync(join(projectPath, 'CAPABILITIES.md'))) return true;
+  if (existsSync(join(projectPath, 'CHANGELOG.md')) || existsSync(join(projectPath, 'CHANGELOG'))) {
+    return true;
+  }
+
+  try {
+    const raw = loadRawProjectConfig(projectPath);
+    const governance = raw?.governance as Record<string, unknown> | undefined;
+
+    const freshnessConfig = governance?.doc_freshness as DocFreshnessConfig | undefined;
+    if (freshnessConfig?.checks && freshnessConfig.checks.length > 0) return true;
+
+    const contextFiles = governance?.context_files as Record<string, unknown> | undefined;
+    if (
+      contextFiles?.enabled &&
+      Array.isArray(contextFiles.required_dirs) &&
+      (contextFiles.required_dirs as string[]).length > 0
+    ) {
+      return true;
+    }
+  } catch {
+    // 配置不可读视为无配置
+  }
+
+  return false;
+}
+
 export const docsFreshness: ConstraintCheck = {
   id: 'docs_freshness',
   async evaluate(env) {
     const projectPath = env.projectPath;
 
+    // ADR-0001 存在性探测：项目无任何 freshness 配置/目标 → skip（不计 pass/fail）
+    if (!hasFreshnessTargets(projectPath)) return 'skip';
+
     // Step 1: 文件表格式 — 检查列出的文件是否还存在
     if (!checkCapabilitiesFreshness(projectPath)) return false;
 

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

@@ -1,104 +1,71 @@
 /**
  * 约束检查器注册表（工单 21）
  *
- * checker.ts 编排层通过 getConstraintCheck(id) 查找实现，
- * 未注册的约束默认通过（保持历史 default 分支语义）。
+ * checker.ts 编排层通过 getConstraintCheck(id) 查找实现。
+ *
+ * 注册表闭环（ADR-0001）：模块加载时校验全部 kind='check' 的内置约束
+ * 都有已注册 checker，且注册表中没有无对应 check 定义的孤儿实现；
+ * 任一不满足即抛错（加载期失败，不许静默 pass）。
  */
 
 import type { ConstraintCheck } from './types';
+import { getAllConstraints } from '../definitions';
 
 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';
+import { noHardcodedCredentials } from './no-hardcoded-credentials';
 
 const CHECKS: ConstraintCheck[] = [
   // Iron Laws
-  noBypassCheckpoint,
-  noSelfApproval,
   noCompletionWithoutVerification,
-  noTestSimplification,
   incrementalProgress,
-  verifyExternalCapability,
-  noImplementationWithoutRequirementReview,
   noImplementationWithoutRequirement,
-  preferWorktree,
-  noFuzzyCompletionClaim,
-  noClaimWithoutEvidence,
-  noDeleteWithoutContext,
-  noPerformativeAgreement,
-  twoStageReviewRequired,
+  noTestSimplification,
+  docsFreshness,
   // Guidelines
-  noFixWithoutRootCause,
-  noCodeWithoutTest,
-  noAnyType,
-  simplestSolutionFirst,
-  noCreationWithoutReuseCheck,
+  noHardcodedCredentials,
+  noBypassCheckpoint,
   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]));
 
+// ========================================
+// 注册表闭环校验（加载期）
+// ========================================
+
+const checkConstraints = getAllConstraints().filter(c => c.kind === 'check');
+
+for (const c of checkConstraints) {
+  if (!registry.has(c.id)) {
+    throw new Error(
+      `[harness] 约束注册表闭环校验失败：kind='check' 的约束 "${c.id}" 未注册 checker。` +
+      `请在 checkers/ 中实现并注册，或将该约束降级为 kind='prompt'。`
+    );
+  }
+}
+
+for (const id of registry.keys()) {
+  if (!checkConstraints.some(c => c.id === id)) {
+    throw new Error(
+      `[harness] 约束注册表闭环校验失败：checker "${id}" 没有对应的 kind='check' 约束定义。` +
+      `请在 definitions/ 中补齐定义，或从注册表移除。`
+    );
+  }
+}
+
 /**
- * 按约束 ID 查找检查实现；未注册返回 undefined（编排层默认通过）
+ * 按约束 ID 查找检查实现；未注册返回 undefined
+ * （编排层对 kind='check' 未注册的情况抛错，kind='prompt' 不查表）
  */
 export function getConstraintCheck(id: string): ConstraintCheck | undefined {
   return registry.get(id);
@@ -111,4 +78,4 @@ export function registeredCheckCount(): number {
   return registry.size;
 }
 
-export type { ConstraintCheck, CheckEnv } from './types';
+export type { ConstraintCheck, CheckEnv, CheckOutcome } from './types';

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

@@ -1,62 +1,26 @@
 /**
  * 铁律层轻量检查（工单 21）：纯上下文证据标志判定，无 I/O
+ *
+ * ADR-0001 后仅存活的三个 flag：hasVerificationEvidence / hasSingleTask / hasRequirement
+ *
+ * 三态语义（ADR-0001 防爆措施）：
+ * - undefined = flag 未接线 → skip（不评估，CLI pre-commit 等路径不误报违规）
+ * - 显式 false → fail；true → pass
  */
 
-import { contextFlag } from './types';
+import { contextEvidenceFlag } from './types';
 
-export const noSelfApproval = contextFlag(
-  'no_self_approval',
-  ctx => ctx.hasTest === true
-);
-
-export const noCompletionWithoutVerification = contextFlag(
+export const noCompletionWithoutVerification = contextEvidenceFlag(
   'no_completion_without_verification',
-  ctx => ctx.hasVerificationEvidence === true
+  ctx => ctx.hasVerificationEvidence
 );
 
-export const incrementalProgress = contextFlag(
+export const incrementalProgress = contextEvidenceFlag(
   'incremental_progress',
-  // undefined = 未验证 → Iron Law 必须显式确认
-  ctx => ctx.hasSingleTask === true
-);
-
-export const verifyExternalCapability = contextFlag(
-  'verify_external_capability',
-  ctx => ctx.hasExternalCapabilityVerification === true
+  ctx => ctx.hasSingleTask
 );
 
-export const noImplementationWithoutRequirementReview = contextFlag(
-  'no_implementation_without_requirement_review',
-  ctx => ctx.hasRequirementReview === true
-);
-
-export const noImplementationWithoutRequirement = contextFlag(
+export const noImplementationWithoutRequirement = contextEvidenceFlag(
   '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
+  ctx => ctx.hasRequirement
 );

package/src/core/constraints/checkers/no-hardcoded-credentials.ts

@@ -0,0 +1,93 @@
+/**
+ * no_hardcoded_credentials：硬编码凭证扫描（ADR-0001：shell 扫描逻辑接入真 checker）
+ *
+ * 扫描 staged diff 的新增行（无 staged diff 时退化为变更文件内容），
+ * 命中常见私钥/密码/token 模式即 fail。
+ *
+ * 模板文件（.example/.sample/.template）与占位符值（your_xxx、process.env 引用等）豁免。
+ */
+
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import type { ConstraintCheck } from './types';
+
+/** 私钥/令牌指纹模式（命中即违规，无例外） */
+const FINGERPRINT_PATTERNS: RegExp[] = [
+  // PEM 私钥头
+  /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY(?: BLOCK)?-----/,
+  // AWS Access Key ID
+  /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/,
+  // GitHub token
+  /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}\b/,
+  /\bgithub_pat_[A-Za-z0-9_]{20,}\b/,
+  // Slack token
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/,
+  // Google API key
+  /\bAIza[0-9A-Za-z_-]{35}\b/,
+];
+
+/** 通用赋值模式：password/secret/token/api key = "字面量"（不要求前词边界，覆盖 dbPassword 等 camelCase） */
+const ASSIGNMENT_PATTERN =
+  /(?:password|passwd|secret|api[_-]?key|access[_-]?token|auth[_-]?token)\b\s*[:=]\s*['"][^'"\n]{8,}['"]/i;
+
+/** 占位符/环境变量引用等明显非真实值 */
+const PLACEHOLDER_PATTERN =
+  /process\.env|your[_-]|<[^>]+>|\$\{|xxx+|placeholder|example|changeme|dummy|fake|test/i;
+
+/** 允许占位符的模板文件后缀 */
+const TEMPLATE_SUFFIXES = ['.example', '.sample', '.template', '.dist'];
+
+function isTemplateFile(file: string): boolean {
+  return TEMPLATE_SUFFIXES.some(s => file.endsWith(s));
+}
+
+/** 判定一段文本是否包含硬编码凭证 */
+export function containsHardcodedCredential(text: string): boolean {
+  for (const line of text.split('\n')) {
+    // 占位符/环境变量引用行整体豁免（your_xxx、process.env、示例值等）
+    if (PLACEHOLDER_PATTERN.test(line)) continue;
+    for (const pattern of FINGERPRINT_PATTERNS) {
+      if (pattern.test(line)) return true;
+    }
+    if (ASSIGNMENT_PATTERN.test(line)) return true;
+  }
+  return false;
+}
+
+export const noHardcodedCredentials: ConstraintCheck = {
+  id: 'no_hardcoded_credentials',
+  evaluate: async (env) => {
+    const files = (env.context.changedFiles || []).filter(f => !isTemplateFile(f));
+
+    // 1) staged diff 新增行
+    let scanned = false;
+    try {
+      const diff = await env.stagedDiff();
+      const added = diff
+        .split('\n')
+        .filter(l => l.startsWith('+') && !l.startsWith('+++'))
+        .map(l => l.slice(1))
+        .join('\n');
+      if (added.trim().length > 0) {
+        scanned = true;
+        if (containsHardcodedCredential(added)) return false;
+      }
+    } catch {
+      // diff 不可用 → 退化为文件内容扫描
+    }
+
+    // 2) 变更文件内容（diff 为空或不可用时）
+    if (!scanned) {
+      for (const file of files) {
+        try {
+          const content = readFileSync(join(env.projectPath, file), 'utf-8');
+          if (containsHardcodedCredential(content)) return false;
+        } catch {
+          // 文件不可读（已删除/二进制）→ 跳过
+        }
+      }
+    }
+
+    return true;
+  },
+};

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

@@ -26,14 +26,22 @@ export interface CheckEnv {
   srcScan(root: string): string[];
 }
 
+/**
+ * 检查结果三态（ADR-0001 存在性探测 / flag 未接线）：
+ * - true = 满足（pass）
+ * - false = 违反（fail）
+ * - 'skip' = 未评估（项目未采用对应约定，或证据 flag 未接线），不计 pass/fail
+ */
+export type CheckOutcome = boolean | 'skip';
+
 /**
  * 单条约束检查实现
  */
 export interface ConstraintCheck {
   /** 约束 ID（与 definitions 一致） */
   id: string;
-  /** 检查主体：true = 满足 */
-  evaluate(env: CheckEnv): Promise<boolean> | boolean;
+  /** 检查主体：true = 满足；false = 违反；'skip' = 未评估 */
+  evaluate(env: CheckEnv): Promise<CheckOutcome> | CheckOutcome;
 }
 
 /**
@@ -47,8 +55,22 @@ export function contextFlag(
 }
 
 /**
- * 构造恒通过检查（promptInjection 驱动 / 仅提示类约束）
+ * 构造证据标志检查（ADR-0001：flag 未接线 = skip 而非 fail）
+ *
+ * - flag === undefined：调用方未接线该证据 → 'skip'（不评估，不误报违规）
+ * - flag === false：显式无证据 → fail
+ * - flag === true：有证据 → pass
  */
-export function alwaysPass(id: string): ConstraintCheck {
-  return { id, evaluate: () => true };
+export function contextEvidenceFlag(
+  id: string,
+  pick: (context: ConstraintContext) => boolean | undefined
+): ConstraintCheck {
+  return {
+    id,
+    evaluate: (env) => {
+      const value = pick(env.context);
+      if (value === undefined) return 'skip';
+      return value;
+    },
+  };
 }

package/src/core/constraints/context-builder.ts

@@ -11,6 +11,7 @@ import * as path from 'path';
 import { execSync } from 'child_process';
 import { execAsync } from '../../utils/exec';
 import { detectSourceRoots } from '../../utils/detect-source-roots';
+import { DEFAULT_TRACE_FILE } from '../../types/trace';
 import type { ConstraintContext, ConstraintTrigger } from '../../types/constraint';
 
 /**
@@ -58,21 +59,31 @@ export function isNewDirectory(headDirs: Set<string> | null, filePath: string):
   return !headDirs.has(path.dirname(filePath));
 }
 
+/**
+ * 代码文件扩展名（ADR-0001：code_implementation 推断信号）
+ *
+ * 纯文档/配置（.md/.json/.yml 等）不算代码变更。
+ */
+const CODE_FILE_REGEX = /\.(?:ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|cpp|cc|c|h|vue|svelte)$/i;
+
 /**
  * 检测触发条件
+ *
+ * ADR-0001：变更包含代码文件时，在主推断之外附加 code_implementation
+ * （返回数组 [主推断, 'code_implementation']；主推断逻辑保持不变）。
  */
 export function detectTrigger(
   changedFiles: string[],
   options: { trigger?: ConstraintTrigger; projectPath?: string }
-): ConstraintTrigger {
+): ConstraintTrigger | ConstraintTrigger[] {
   if (options.trigger) return options.trigger;
 
   // 根据变更文件推断触发条件
-  // 注意：不自动推断 code_implementation——那是 caller 的语义判断。
-  // pre-commit 无法区分"模板编辑"和"逻辑实现"，保守使用 file_modification。
   const hasTestChange = changedFiles.some(f =>
     f.includes('.test.') || f.includes('.spec.') || f.includes('__tests__')
   );
+  // pre-commit 场景下变更含代码文件 → 附加 code_implementation 推断
+  const hasCodeChange = changedFiles.some(f => CODE_FILE_REGEX.test(f));
   const projectPath = options.projectPath || process.cwd();
   const sourceRoots = detectSourceRoots(projectPath);
   const hasModuleChange = changedFiles.some(f =>
@@ -84,23 +95,22 @@ export function detectTrigger(
     isNewDirectory(headDirs, f)
   );
 
-  if (hasTestChange && !hasModuleChange) return 'test_creation';
-  if (hasModuleCreation) return 'module_creation';
-  if (hasModuleChange) return 'module_modification';
+  let primary: ConstraintTrigger;
+  if (hasTestChange && !hasModuleChange) primary = 'test_creation';
+  else if (hasModuleCreation) primary = 'module_creation';
+  else if (hasModuleChange) primary = 'module_modification';
+  else primary = 'file_modification';
 
-  return 'file_modification';
+  return hasCodeChange ? [primary, 'code_implementation'] : primary;
 }
 
 /**
  * 检测是否有失败的测试记录
- * 扫描 .harness/traces/ 中最近的 trace 记录
+ * 扫描 trace 文件（DEFAULT_TRACE_FILE）中最近的记录
  */
 export async function detectFailingTest(projectPath: string): Promise<boolean> {
   try {
-    const tracesDir = path.join(projectPath, '.harness', 'traces');
-    if (!fs.existsSync(tracesDir)) return false;
-
-    const traceFile = path.join(tracesDir, 'execution.log');
+    const traceFile = path.join(projectPath, DEFAULT_TRACE_FILE);
     if (!fs.existsSync(traceFile)) return false;
 
     const content = fs.readFileSync(traceFile, 'utf-8');
@@ -146,14 +156,11 @@ export function detectRootCauseInvestigation(projectPath: string): boolean {
 
 /**
  * 检测是否有验证证据
- * 检查 .harness/traces/ 中最近的成功验证记录
+ * 检查 trace 文件（DEFAULT_TRACE_FILE）中最近的成功验证记录
  */
 export async function detectVerificationEvidence(projectPath: string): Promise<boolean> {
   try {
-    const tracesDir = path.join(projectPath, '.harness', 'traces');
-    if (!fs.existsSync(tracesDir)) return false;
-
-    const traceFile = path.join(tracesDir, 'execution.log');
+    const traceFile = path.join(projectPath, DEFAULT_TRACE_FILE);
     if (!fs.existsSync(traceFile)) return false;
 
     const content = fs.readFileSync(traceFile, 'utf-8');
@@ -245,10 +252,12 @@ export async function buildConstraintContext(options: {
 }): Promise<ConstraintContext> {
   const projectPath = options.projectPath || process.cwd();
   const changedFiles = await getChangedFiles(options.staged, options.projectPath);
-  const trigger = detectTrigger(changedFiles, { trigger: options.trigger, projectPath });
+  const inferred = detectTrigger(changedFiles, { trigger: options.trigger, projectPath });
+  const triggers = Array.isArray(inferred) ? inferred : [inferred];
 
   return {
-    operation: trigger,
+    operation: triggers[0],
+    extraTriggers: triggers.slice(1),
     projectPath,
     changedFiles,
     hasTest: changedFiles.some(f => f.includes('.test.') || f.includes('.spec.')),