@dommaker/harness 0.16.8 → 0.17.0

package/src/core/CONTEXT.md

@@ -1,10 +1,11 @@
 # core/
 
 ## 职责
-约束引擎核心：三层约束系统(Iron Laws / Guidelines / Tips)、检查点验证器(CSO/passes-gate)、会话管理、Spec 验证器、项目配置加载。
+约束引擎核心：check/prompt 二元约束系统（ADR-0001）、生效集合并（effective-constraints）、检查点验证器(CSO/passes-gate)、会话管理、Spec 验证器、项目配置加载。
 
 ## 核心导出
-- `constraints/` — 约束定义(IRON_LAWS/GUIDELINES/TIPS) + 检查引擎(ConstraintChecker) + 拦截器(ConstraintInterceptor) + 缓存(CheckCache)
+- `constraints/` — 约束定义(IRON_LAWS/GUIDELINES/PROMPTS；TIPS 已退役为空表) + 检查引擎(ConstraintChecker) + 拦截器(ConstraintInterceptor) + 缓存(CheckCache) + 注入渲染(injection-renderer)/漂移校验(injection-drift)/使用统计(usage-report)
+- `effective-constraints.ts` — `getEffectiveConstraints(projectRoot)`：全仓唯一生效集来源（内置 → preset → config.yml 禁用 → custom 追加 → scenes 过滤）；`lintEffectiveConfig` 配置诊断
 - `validators/` — checkpoints、passes-gate、CSO 验证器
 - `session/` — 会话管理
 - `spec/validator` — SpecValidator
@@ -17,10 +18,12 @@
 - 依赖 `src/monitoring/traces` TraceCollector
 
 ## 约定
-- 约束定义在 `constraints/definitions.ts`，不在运行时代码中定义
+- 约束定义在 `constraints/definitions/{iron-laws,guidelines,prompts}.ts`，不在运行时代码中定义
+- check 层必须带真实 checker（注册表闭环，引用未注册 checker 构建报错）
 - Iron Law 违规必须 throw ConstraintViolationError
 - 检查器使用单例模式(ConstraintChecker.getInstance())
 
 ## 注意事项
 - 零 Token 成本：所有分析纯文件操作，无 LLM 调用
-- 约束配置支持 .harness/config.yml 自定义合并
+- 约束配置支持 .harness/config.yml 自定义合并（preset 真实生效）
+- 存在性探测约束（capability_sync/docs_freshness/context_doc_sync）在约定文件缺失时 skip，不计 pass/fail

package/src/core/constraints/__tests__/injection-drift.test.ts

@@ -0,0 +1,164 @@
+/**
+ * 注入漂移校验测试（ADR-0001 决策 7，P6）
+ *
+ * - 三类漂移各自检出：版本 / 内容（条目级 missing/extra）/ 重复章节
+ * - 无漂移静默；无标记段 = 未注入不算漂移；CLAUDE.md 不存在不算漂移
+ * - config.yml 变更后未重跑 init → 内容漂移（extra）
+ *
+ * 使用真实临时目录（getEffectiveConstraints 读真实 fs）。
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { detectInjectionDrift, INJECTION_DRIFT_FIX_HINT } from '../injection-drift';
+import {
+  renderConstraintsSection,
+  CONSTRAINTS_START_MARKER,
+} from '../injection-renderer';
+import { getEffectiveConstraints } from '../../effective-constraints';
+
+const TEST_VERSION = '9.9.9-test';
+
+function makeTmpProject(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'harness-drift-test-'));
+}
+
+/** 写入与当前生效集完全一致的注入段（版本 TEST_VERSION） */
+function writeSyncedClaudeMd(root: string, extra = ''): string {
+  const section =
+    '## Governance Rules\n' + renderConstraintsSection(getEffectiveConstraints(root), TEST_VERSION);
+  const content = `# Test Project\n\n${section}${extra}`;
+  fs.writeFileSync(path.join(root, 'CLAUDE.md'), content, 'utf-8');
+  return content;
+}
+
+describe('detectInjectionDrift', () => {
+  it('无漂移：注入段与期望渲染一致 → hasDrift=false', () => {
+    const root = makeTmpProject();
+    writeSyncedClaudeMd(root);
+
+    const drift = detectInjectionDrift(root, TEST_VERSION);
+
+    expect(drift.notInjected).toBe(false);
+    expect(drift.hasDrift).toBe(false);
+    expect(drift.versionDrift).toBeUndefined();
+    expect(drift.contentDrift).toBeUndefined();
+    expect(drift.duplicateHeading).toBe(false);
+    expect(drift.fixHint).toContain('npx harness init');
+    expect(drift.fixHint).toBe(INJECTION_DRIFT_FIX_HINT);
+  });
+
+  it('版本漂移：标记段版本号改旧 → versionDrift', () => {
+    const root = makeTmpProject();
+    const synced = writeSyncedClaudeMd(root);
+    fs.writeFileSync(
+      path.join(root, 'CLAUDE.md'),
+      synced.replace(`<!-- version: ${TEST_VERSION} -->`, '<!-- version: 0.0.1-old -->'),
+      'utf-8'
+    );
+
+    const drift = detectInjectionDrift(root, TEST_VERSION);
+
+    expect(drift.hasDrift).toBe(true);
+    expect(drift.versionDrift).toEqual({ expected: TEST_VERSION, actual: '0.0.1-old' });
+    expect(drift.contentDrift).toBeUndefined();
+  });
+
+  it('内容漂移：手改标记段内一条 → 原条目 missing、改后条目 extra', () => {
+    const root = makeTmpProject();
+    const synced = writeSyncedClaudeMd(root);
+    const originalLine = synced.split('\n').find(l => l.startsWith('- **'))!;
+    const editedLine = originalLine.replace(/: .+$/, ': 手工篡改的注入文本');
+    fs.writeFileSync(
+      path.join(root, 'CLAUDE.md'),
+      synced.replace(originalLine, editedLine),
+      'utf-8'
+    );
+
+    const drift = detectInjectionDrift(root, TEST_VERSION);
+
+    expect(drift.hasDrift).toBe(true);
+    expect(drift.versionDrift).toBeUndefined();
+    expect(drift.contentDrift).toBeDefined();
+    expect(drift.contentDrift!.missing).toEqual([originalLine]);
+    expect(drift.contentDrift!.extra).toEqual([editedLine]);
+  });
+
+  it('内容漂移：config.yml 变更后未重跑 init → 被禁条目成为 extra', () => {
+    const root = makeTmpProject();
+    writeSyncedClaudeMd(root);
+    // 注入后禁用一条 prompt，但不重跑 init
+    fs.mkdirSync(path.join(root, '.harness'), { recursive: true });
+    fs.writeFileSync(
+      path.join(root, '.harness', 'config.yml'),
+      'constraints:\n  no_fuzzy_completion_claim:\n    enabled: false\n',
+      'utf-8'
+    );
+
+    const drift = detectInjectionDrift(root, TEST_VERSION);
+
+    expect(drift.hasDrift).toBe(true);
+    expect(drift.contentDrift).toBeDefined();
+    expect(drift.contentDrift!.missing).toEqual([]);
+    expect(drift.contentDrift!.extra).toHaveLength(1);
+    expect(drift.contentDrift!.extra[0]).toContain('no_fuzzy_completion_claim');
+  });
+
+  it('重复章节：标记段之外还有一个 ## Governance Rules 标题 → duplicateHeading', () => {
+    const root = makeTmpProject();
+    writeSyncedClaudeMd(root, '\n## Governance Rules\n\n旧版遗留的同名章节\n');
+
+    const drift = detectInjectionDrift(root, TEST_VERSION);
+
+    expect(drift.duplicateHeading).toBe(true);
+    expect(drift.hasDrift).toBe(true);
+  });
+
+  it('无标记段 = 未注入，不算漂移', () => {
+    const root = makeTmpProject();
+    fs.writeFileSync(path.join(root, 'CLAUDE.md'), '# Test Project\n\n## Governance Rules\n\n用户自写内容\n', 'utf-8');
+
+    const drift = detectInjectionDrift(root, TEST_VERSION);
+
+    expect(drift.notInjected).toBe(true);
+    expect(drift.hasDrift).toBe(false);
+  });
+
+  it('CLAUDE.md 不存在 = 未注入，不算漂移', () => {
+    const root = makeTmpProject();
+
+    const drift = detectInjectionDrift(root, TEST_VERSION);
+
+    expect(drift.notInjected).toBe(true);
+    expect(drift.hasDrift).toBe(false);
+  });
+
+  it('默认版本参数读 package.json：与真实版本一致的注入段无版本漂移', () => {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const realVersion = require('../../../../package.json').version as string;
+    const root = makeTmpProject();
+    const section =
+      '## Governance Rules\n' + renderConstraintsSection(getEffectiveConstraints(root), realVersion);
+    fs.writeFileSync(path.join(root, 'CLAUDE.md'), section, 'utf-8');
+
+    const drift = detectInjectionDrift(root);
+
+    expect(drift.versionDrift).toBeUndefined();
+    expect(drift.hasDrift).toBe(false);
+  });
+
+  it('标记段含 ' + CONSTRAINTS_START_MARKER + ' 但版本行缺失 → versionDrift actual=(缺失)', () => {
+    const root = makeTmpProject();
+    const synced = writeSyncedClaudeMd(root);
+    fs.writeFileSync(
+      path.join(root, 'CLAUDE.md'),
+      synced.replace(`<!-- version: ${TEST_VERSION} -->\n`, ''),
+      'utf-8'
+    );
+
+    const drift = detectInjectionDrift(root, TEST_VERSION);
+
+    expect(drift.versionDrift).toEqual({ expected: TEST_VERSION, actual: '(缺失)' });
+  });
+});

package/src/core/constraints/__tests__/interceptor.test.ts

@@ -24,6 +24,7 @@ describe('ConstraintInterceptor', () => {
 
   const mockIronLaw = {
     id: 'test_iron_law',
+    kind: 'check' as const,
     rule: 'Test Iron Law',
     message: 'Test iron law message',
     level: 'iron_law' as const,
@@ -34,6 +35,7 @@ describe('ConstraintInterceptor', () => {
 
   const mockGuideline = {
     id: 'test_guideline',
+    kind: 'check' as const,
     rule: 'Test Guideline',
     message: 'Test guideline message',
     level: 'guideline' as const,
@@ -63,6 +65,7 @@ describe('ConstraintInterceptor', () => {
       ironLaws: { test_iron_law: mockIronLaw },
       guidelines: { test_guideline: mockGuideline },
       tips: {},
+      prompts: {},
     });
   });
 
@@ -200,6 +203,7 @@ describe('ConstraintInterceptor', () => {
         ironLaws: {},
         guidelines: {},
         tips: {},
+        prompts: {},
       });
 
       const result = await interceptor.intercept('code_implementation', mockContext);

package/src/core/constraints/capabilities-parser.ts

@@ -68,3 +68,31 @@ export function readCapabilitiesEntries(capabilitiesPath: string, options: Capab
     return [];
   }
 }
+
+/**
+ * 检测 CAPABILITIES.md 是否使用能力清单格式（计数行），而非文件表格格式
+ *
+ * 清单格式没有文件表可核对，计数由 sync-docs 自动维护，
+ * checker 与 sync-docs 都应按此跳过条目级比对。
+ */
+export function isCapabilityListingFormat(content: string): boolean {
+  // 能力清单格式特征：包含 "CLI Commands (N)" / "Iron Laws (N)" 等计数行
+  return /CLI Commands\s*\(\d+\)/.test(content) ||
+    /Iron Laws?\s*\(\d+\)/.test(content) ||
+    /Guidelines?\s*\(\d+\)/.test(content);
+}
+
+/**
+ * 未覆盖文件的聚合目录（module 模式）
+ *
+ * 规则：取源码根下的第一级子目录（root=src、file=src/core/foo.ts → src/core/）；
+ * 源码根直接下的文件聚到根（file=src/foo.ts → src/）。
+ */
+export function aggregateToSourceSubdir(root: string, file: string): string {
+  if (!root) return file;
+  const prefix = root.endsWith('/') ? root : root + '/';
+  const rest = file.startsWith(prefix) ? file.slice(prefix.length) : file;
+  const idx = rest.indexOf('/');
+  if (idx === -1) return prefix;
+  return prefix + rest.slice(0, idx) + '/';
+}

package/src/core/constraints/checker.ts

@@ -1,10 +1,10 @@
 /**
  * 约束检查引擎
- * 
- * 三层约束体系检查：
- * - Iron Laws：检查失败立即抛出异常
- * - Guidelines：检查失败记录警告
- * - Tips：检查失败记录提示
+ *
+ * kind 二元模型（ADR-0001）：
+ * - check · Iron Laws：检查失败立即抛出异常
+ * - check · Guidelines：检查失败记录警告
+ * - prompt：不执行 checker，仅参与注入
  */
 
 import {
@@ -17,14 +17,14 @@ import {
   ConstraintViolationError,
 } from '../../types/constraint';
 import type { ExecutionTrace } from '../../types/trace';
-import { IRON_LAWS, GUIDELINES, TIPS } from './definitions';
+import { IRON_LAWS, GUIDELINES, TIPS, PROMPTS } from './definitions';
 import type { MergedConstraintsConfig } from '../../types/project-config';
 import { normalizeTriggers } from '../../utils/exec';
 import { runCommand } from '../../utils/exec';
 import { join, relative } from 'path';
 import { CheckCache } from './check-cache';
 import { findTsSourceFiles } from '../../utils/file-walk';
-import { getConstraintCheck, type CheckEnv } from './checkers';
+import { getConstraintCheck, type CheckEnv, type CheckOutcome } from './checkers';
 
 /**
  * 例外名称 → ConstraintContext 中布尔字段的映射
@@ -158,11 +158,12 @@ export class ConstraintChecker {
     ironLaws: Record<string, Constraint & { check: (ctx: ConstraintContext) => Promise<ConstraintResult> }>;
     guidelines: Record<string, Constraint & { check: (ctx: ConstraintContext) => Promise<ConstraintResult> }>;
     tips: Record<string, Constraint & { check: (ctx: ConstraintContext) => Promise<ConstraintResult> }>;
+    prompts: Record<string, Constraint & { check: (ctx: ConstraintContext) => Promise<ConstraintResult> }>;
   } {
     const config = customConfig ?? this.customConfig;
     const source = config
-      ? { ironLaws: config.ironLaws, guidelines: config.guidelines, tips: config.tips }
-      : { ironLaws: IRON_LAWS, guidelines: GUIDELINES, tips: TIPS };
+      ? { ironLaws: config.ironLaws, guidelines: config.guidelines, tips: config.tips, prompts: config.prompts ?? PROMPTS }
+      : { ironLaws: IRON_LAWS, guidelines: GUIDELINES, tips: TIPS, prompts: PROMPTS };
 
     // Wire unified check() method on every constraint
     const wire = (constraints: Record<string, Constraint>) => {
@@ -171,7 +172,12 @@ export class ConstraintChecker {
       }
       return constraints as Record<string, Constraint & { check: (ctx: ConstraintContext) => Promise<ConstraintResult> }>;
     };
-    return { ironLaws: wire(source.ironLaws), guidelines: wire(source.guidelines), tips: wire(source.tips) };
+    return {
+      ironLaws: wire(source.ironLaws),
+      guidelines: wire(source.guidelines),
+      tips: wire(source.tips),
+      prompts: wire(source.prompts),
+    };
   }
 
   /**
@@ -181,6 +187,17 @@ export class ConstraintChecker {
     constraint: Constraint,
     context: ConstraintContext
   ): Promise<ConstraintResult> {
+    // prompt 类约束不参与 checker 执行（ADR-0001：仅参与注入）
+    if (constraint.kind === 'prompt') {
+      return {
+        id: constraint.id,
+        level: constraint.level,
+        satisfied: true,
+        constraint,
+        checkedAt: new Date(),
+      };
+    }
+
     // 检查例外条件（仅 Guidelines 有效）
     if (constraint.level === 'guideline' && constraint.exceptions) {
       if (this.checkException(constraint, context)) {
@@ -195,8 +212,22 @@ export class ConstraintChecker {
       }
     }
 
-    // 检查前置条件
-    const satisfied = await this.checkPrecondition(constraint, context);
+    // 检查前置条件（'skip' = 约定未采用/证据未接线：satisfied 置 true 但不计 pass/fail）
+    const outcome = await this.checkPrecondition(constraint, context);
+
+    if (outcome === 'skip') {
+      return {
+        id: constraint.id,
+        level: constraint.level,
+        satisfied: true,
+        skipped: true,
+        constraint,
+        message: `约束 ${constraint.id} 跳过评估（约定未采用或证据未接线）`,
+        checkedAt: new Date(),
+      };
+    }
+
+    const satisfied = outcome;
 
     return {
       id: constraint.id,
@@ -228,6 +259,7 @@ export class ConstraintChecker {
         return 'error';
       case 'guideline':
         return 'warning';
+      case 'prompt':
       case 'tip':
         return 'info';
       default:
@@ -237,10 +269,14 @@ export class ConstraintChecker {
 
   /**
    * 判断约束是否匹配当前触发条件
+   *
+   * context.operation 为主触发条件，context.extraTriggers 为次级推断
+   * （ADR-0001：pre-commit 代码变更附加 code_implementation），任一命中即匹配。
    */
-  private matchesTrigger(constraint: Constraint, operation: ConstraintTrigger): boolean {
+  private matchesTrigger(constraint: Constraint, context: ConstraintContext): boolean {
     const triggers = normalizeTriggers<ConstraintTrigger>(constraint.trigger);
-    return triggers.includes(operation);
+    const operations = [context.operation, ...(context.extraTriggers ?? [])];
+    return operations.some(op => triggers.includes(op));
   }
 
   /**
@@ -256,7 +292,7 @@ export class ConstraintChecker {
       constraintId: constraint.id,
       level: constraint.level,
       timestamp: Date.now(),
-      result: checkResult.satisfied ? 'pass' : 'fail',
+      result: checkResult.skipped ? 'skip' : checkResult.satisfied ? 'pass' : 'fail',
       operation: context.operation,
       severity: this.getSeverity(constraint.level),
       exceptionApplied: checkResult.message?.includes('豁免')
@@ -270,14 +306,20 @@ export class ConstraintChecker {
   /**
    * 检查约束前置条件（工单 21：分发至 checkers/ 注册表）
    *
-   * 未注册的约束默认通过（保持历史 default 分支语义）。
+   * 注册表闭环（ADR-0001）：kind='check' 未注册 checker 直接抛错，
+   * 不再有"未注册默认通过"路径；kind='prompt' 在 check() 入口已短路。
    */
   private async checkPrecondition(
     constraint: Constraint,
     context: ConstraintContext
-  ): Promise<boolean> {
+  ): Promise<CheckOutcome> {
     const impl = getConstraintCheck(constraint.id);
-    if (!impl) return true;
+    if (!impl) {
+      throw new Error(
+        `[harness] 约束 "${constraint.id}" (kind='check') 未注册 checker，拒绝静默通过。` +
+        `请在 checkers/ 注册实现，或将约束改为 kind='prompt'。`
+      );
+    }
 
     const projectPath = context.projectPath || process.cwd();
     const env: CheckEnv = {
@@ -309,8 +351,9 @@ export class ConstraintChecker {
     ironLaws: Constraint[];
     guidelines: Constraint[];
     tips: Constraint[];
+    prompts: Constraint[];
   } {
-    const trigger = context.operation;
+    const operations = [context.operation, ...(context.extraTriggers ?? [])];
     const constraints = this.getConstraints(customConfig);
 
     const filterByTrigger = (constraintSet: Record<string, Constraint>): Constraint[] => {
@@ -318,7 +361,7 @@ export class ConstraintChecker {
         const triggers = Array.isArray(constraint.trigger)
           ? constraint.trigger
           : [constraint.trigger];
-        return triggers.includes(trigger);
+        return operations.some(op => triggers.includes(op));
       });
     };
 
@@ -326,6 +369,7 @@ export class ConstraintChecker {
       ironLaws: filterByTrigger(constraints.ironLaws),
       guidelines: filterByTrigger(constraints.guidelines),
       tips: filterByTrigger(constraints.tips),
+      prompts: filterByTrigger(constraints.prompts),
     };
   }
 
@@ -362,7 +406,7 @@ export class ConstraintChecker {
 
       // 1. Iron Laws: 必须全部通过
       for (const constraint of Object.values(constraints.ironLaws)) {
-        if (!this.matchesTrigger(constraint, context.operation)) continue;
+        if (!this.matchesTrigger(constraint, context)) continue;
 
         const checkResult = await this.check(constraint, context);
         result.ironLaws.push(checkResult);
@@ -376,7 +420,7 @@ export class ConstraintChecker {
 
       // 2. Guidelines: 记录警告
       for (const constraint of Object.values(constraints.guidelines)) {
-        if (!this.matchesTrigger(constraint, context.operation)) continue;
+        if (!this.matchesTrigger(constraint, context)) continue;
 
         const checkResult = await this.check(constraint, context);
         result.guidelines.push(checkResult);
@@ -389,7 +433,7 @@ export class ConstraintChecker {
 
       // 3. Tips: 仅记录
       for (const constraint of Object.values(constraints.tips)) {
-        if (!this.matchesTrigger(constraint, context.operation)) continue;
+        if (!this.matchesTrigger(constraint, context)) continue;
 
         const checkResult = await this.check(constraint, context);
         result.tips.push(checkResult);
@@ -434,7 +478,7 @@ export class ConstraintChecker {
       const constraints = this.getConstraints(customConfig);
 
       for (const constraint of Object.values(constraints.ironLaws)) {
-        if (!this.matchesTrigger(constraint, context.operation)) continue;
+        if (!this.matchesTrigger(constraint, context)) continue;
         const checkResult = await this.check(constraint, context);
         result.ironLaws.push(checkResult);
         this.recordTrace(traceCollector, constraint, checkResult, context);
@@ -442,7 +486,7 @@ export class ConstraintChecker {
       }
 
       for (const constraint of Object.values(constraints.guidelines)) {
-        if (!this.matchesTrigger(constraint, context.operation)) continue;
+        if (!this.matchesTrigger(constraint, context)) continue;
         const checkResult = await this.check(constraint, context);
         result.guidelines.push(checkResult);
         this.recordTrace(traceCollector, constraint, checkResult, context);
@@ -450,7 +494,7 @@ export class ConstraintChecker {
       }
 
       for (const constraint of Object.values(constraints.tips)) {
-        if (!this.matchesTrigger(constraint, context.operation)) continue;
+        if (!this.matchesTrigger(constraint, context)) continue;
         const checkResult = await this.check(constraint, context);
         result.tips.push(checkResult);
         this.recordTrace(traceCollector, constraint, checkResult, context);
@@ -475,7 +519,7 @@ export class ConstraintChecker {
     customConfig?: MergedConstraintsConfig | null
   ): Promise<void> {
     const constraints = this.getConstraints(customConfig);
-    const operations = normalizeTriggers(context.operation);
+    const operations = [context.operation, ...(context.extraTriggers ?? [])];
 
     for (const constraint of Object.values(constraints.ironLaws)) {
       if (!normalizeTriggers(constraint.trigger).some((t) => operations.includes(t))) continue;
@@ -505,7 +549,8 @@ export async function checkConstraint(
   const constraint =
     constraints.ironLaws[constraintId] ||
     constraints.guidelines[constraintId] ||
-    constraints.tips[constraintId];
+    constraints.tips[constraintId] ||
+    constraints.prompts[constraintId];
 
   if (!constraint) {
     return {

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

@@ -4,18 +4,55 @@
  * 两步验证：
  *   1. Git diff 增量 — 当前变更的非测试文件是否在文档中有记录
  *   2. 全量扫描 — 源码根下所有源文件是否都在 CAPABILITIES.md 中（T-058）
+ *
+ * 覆盖判定两步统一（isCoveredBy）：目录条目（以 / 结尾）前缀匹配，
+ * 文件条目精确匹配或路径边界后缀匹配。module 模式下目录条目参与覆盖，
+ * 未覆盖文件按源码根下第一级子目录聚合。
+ *
+ * 清单格式（计数行，mode=listing 或嗅探命中）无文件表可核对，直接放行；
+ * 检查异常时 fail-open 但输出 console.warn 保留可观测性。
+ *
+ * ADR-0001 存在性探测：项目根无 CAPABILITIES.md（未采用该约定）时返回 'skip'，
+ * 不计 pass/fail，避免在未采用约定的项目上全量误报。
  */
 
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
-import { readCapabilitiesEntries } from '../capabilities-parser';
+import {
+  aggregateToSourceSubdir,
+  isCapabilityListingFormat,
+  parseCapabilitiesEntries,
+} from '../capabilities-parser';
+import { getCapabilitiesMode } from '../../project-config-loader';
 import { detectSourceRoots } from '../../../utils/detect-source-roots';
 import type { ConstraintCheck } from './types';
 
+/** markdown 表格分隔行（|------|------|）：区分「无表格的散文文档」与「有表格但零条目」 */
+const TABLE_SEPARATOR_REGEX = /^\s*\|[\s:|-]+\|\s*$/m;
+
+/**
+ * 变更文件是否被条目覆盖
+ *
+ * 目录条目（以 / 结尾）前缀匹配；文件条目精确匹配或路径边界后缀匹配
+ * （兼容 basename 条目，但拒绝 xfoo.ts 命中 foo.ts、docs/src/foo.tsx 命中 src/foo.ts
+ * 这类 endsWith/includes 模糊匹配造成的碰撞）
+ */
+function isCoveredBy(entries: string[], changed: string): boolean {
+  return entries.some((listed) =>
+    listed.endsWith('/')
+      ? changed.startsWith(listed)
+      : changed === listed || changed.endsWith('/' + listed)
+  );
+}
+
 export const capabilitySync: ConstraintCheck = {
   id: 'capability_sync',
   async evaluate(env) {
     const projectPath = env.projectPath;
+    // ADR-0001 存在性探测：项目未采用 CAPABILITIES.md 约定 → skip（不计 pass/fail）
+    if (!existsSync(join(projectPath, 'CAPABILITIES.md'))) {
+      return 'skip';
+    }
     try {
       const capabilitiesPath = join(projectPath, 'CAPABILITIES.md');
       if (!existsSync(capabilitiesPath)) {
@@ -27,35 +64,67 @@ export const capabilitySync: ConstraintCheck = {
         return changedCodeFiles.length === 0;
       }
 
-      const listedFiles = readCapabilitiesEntries(capabilitiesPath, { secondColumnOnly: true });
+      const content = readFileSync(capabilitiesPath, 'utf-8');
+      const capabilitiesMode = getCapabilitiesMode(projectPath);
+
+      // 清单格式（计数行）没有文件表可核对，计数由 sync-docs 维护，直接放行
+      if (capabilitiesMode === 'listing' || isCapabilityListingFormat(content)) {
+        return true;
+      }
+
+      const listedFiles = parseCapabilitiesEntries(content, { secondColumnOnly: true });
+      // module 模式下目录条目同样构成覆盖依据，与 step 2 判定对齐
+      const entries =
+        capabilitiesMode === 'module'
+          ? parseCapabilitiesEntries(content, { includeDirs: true })
+          : listedFiles;
+      // 有表格但零条目 = 文档什么都没登记，不得直接放行；无表格的散文文档保持历史放行
+      const hasTable = TABLE_SEPARATOR_REGEX.test(content);
 
       // ── 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')
       );
+      const significantChanges = changedCodeFiles.filter(
+        (f: string) => !f.includes('__tests__') && !f.includes('.test.') && !f.includes('.spec.')
+      );
 
-      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;
-        }
+      // 每个变更文件都必须被覆盖（every；some 会让一个命中掩盖其余漏网）
+      if (
+        significantChanges.length > 0 &&
+        (entries.length > 0 || hasTable) &&
+        !significantChanges.every((changed: string) => isCoveredBy(entries, changed))
+      ) {
+        return false;
       }
 
       // ── Step 2: 全量源码根扫描（T-058 修复核心）──
-      if (listedFiles.length > 0) {
+      if (capabilitiesMode === 'module') {
+        // module 模式：目录条目参与覆盖（isCoveredBy 统一判定）；
+        // 未覆盖文件按源码根下第一级子目录聚合，任一组非空即失败
+        if (entries.length > 0 || hasTable) {
+          const uncoveredDirs = new Set<string>();
+          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 (!isCoveredBy(entries, file)) {
+                  uncoveredDirs.add(aggregateToSourceSubdir(root, file));
+                }
+              }
+            }
+          }
+          if (uncoveredDirs.size > 0) return false;
+        }
+      } else if (listedFiles.length > 0 || hasTable) {
         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)) {
+              if (!isCoveredBy(listedFiles, file)) {
                 return false;
               }
             }
@@ -64,8 +133,10 @@ export const capabilitySync: ConstraintCheck = {
       }
 
       return true;
-    } catch {
-      return true; // 检查失败，默认通过
+    } catch (err) {
+      // fail-open 语义保留，但必须可观测：静默吞错会让解析 bug 变成「永远通过」
+      console.warn('[capability_sync] 检查执行异常，默认放行：', err);
+      return true;
     }
   },
 };