@dommaker/harness 1.2.3 → 1.4.0

package/src/{__tests__ → core/constraints/checkers/__tests__}/no-hardcoded-credentials.test.ts

@@ -1,16 +1,17 @@
 /**
- * no_hardcoded_credentials checker 测试（ADR-0001）
+ * no_hardcoded_credentials 检查器旁测（ADR-0001）
  *
  * 注意：测试夹具中的假凭证一律用字符串拼接构造，
  * 避免本文件自身被凭证扫描（含 harness 自身 staged diff）命中。
+ * 测试面 = evaluate(env)（架构评审候选4，自 src/__tests__/ 就近迁入）。
  */
 
 import { describe, it, expect } from '@jest/globals';
 import {
   noHardcodedCredentials,
   containsHardcodedCredential,
-} from '../core/constraints/checkers/no-hardcoded-credentials';
-import type { CheckEnv } from '../core/constraints/checkers';
+} from '../no-hardcoded-credentials';
+import type { CheckEnv } from '../types';
 
 function makeEnv(stagedDiff: string): CheckEnv {
   return {

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

@@ -0,0 +1,58 @@
+/**
+ * no_test_simplification 检查器旁测（架构评审候选4，ADR-0009 同模式）
+ *
+ * 测试面 = ConstraintCheck.evaluate(env)：判定只吃 stagedDiff 文本，
+ * 证据经 providers 注入（旧 facade 测用真实非 git 目录触发 IO 失败，
+ * 旁测直接让 provider 抛错表达同一语义）。自 checker-extra.test.ts 迁入。
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import { noTestSimplification } from '../no-test-simplification';
+import { buildCheckEnv } from '../types';
+import type { ConstraintContext } from '../../../../types/constraint';
+
+function evaluate(diff: string | (() => Promise<string>)) {
+  const context: ConstraintContext = { operation: 'test_creation', projectPath: '/nonexistent' };
+  const stagedDiff = typeof diff === 'function' ? diff : async () => diff;
+  return noTestSimplification.evaluate(
+    buildCheckEnv(context, {
+      stagedDiff,
+      stagedDiffNames: async () => '',
+      srcScan: () => [],
+    })
+  );
+}
+
+describe('no_test_simplification', () => {
+  it('删除 test/it/describe → fail', async () => {
+    expect(await evaluate('--- a/x.test.ts\n+++ b/x.test.ts\n@@\n-  test("gone", () => {});\n')).toBe(false);
+    expect(await evaluate('-  it("gone", () => {});')).toBe(false);
+    expect(await evaluate('-describe("suite", () => {});')).toBe(false);
+  });
+
+  it('删除 expect → fail', async () => {
+    expect(await evaluate('-    expect(x).toBe(y);')).toBe(false);
+  });
+
+  it('删除注释掉的 test → fail', async () => {
+    expect(await evaluate('-  // test pending case')).toBe(false);
+  });
+
+  it('仅新增/上下文行 → pass', async () => {
+    expect(
+      await evaluate('--- a/x.test.ts\n+++ b/x.test.ts\n@@\n+  test("added", () => {});\n   expect(1).toBe(1);\n')
+    ).toBe(true);
+  });
+
+  it('空 diff → pass', async () => {
+    expect(await evaluate('')).toBe(true);
+  });
+
+  it('git diff 失败 → 默认通过（fail-open，自 facade 测迁入）', async () => {
+    expect(
+      await evaluate(async () => {
+        throw new Error('not a git repository');
+      })
+    ).toBe(true);
+  });
+});

package/src/core/constraints/checkers/__tests__/three-state-consistency.test.ts

@@ -0,0 +1,145 @@
+/**
+ * context_files 三态对照测试（工单 84）
+ *
+ * 同一组 fixture 同时跑 context_doc_sync 与 docs_freshness 两条约束，
+ * 钉死 triage 裁决口径：未配置 / enabled 但无目标 → 约束 checker 一律 skip
+ * （ADR-0001 存在性探测同构）；enabled 且非空 → 两条约束按同一组 dirs
+ * 评估且判定一致。
+ *
+ * 附带 docs_freshness 评估段的行为变更钉子：enabled 但无目标 → skip，
+ * 不再静默放行（此前返回 true）。
+ * 项目根由 src/test-setup/project-fixture 声明式构造（回收仍走 mkdtemp-cleanup）。
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import { contextDocSync } from '../context-doc-sync';
+import { docsFreshness } from '../docs-freshness';
+import { buildCheckEnv } from '../types';
+import { collectSourceFiles } from '../../capabilities-reconcile';
+import { createProjectFixture } from '../../../../test-setup/project-fixture';
+import type { ConstraintContext } from '../../../../types/constraint';
+
+const TABLE_HEAD = '| 模块 | 文件 | 说明 |\n|------|------|------|\n';
+
+interface Fixture {
+  configYml?: string;
+  contextMdDirs?: string[];
+  files?: string[];
+  capabilitiesBody?: string;
+}
+
+function setupDir(name: string, fixture: Fixture = {}): string {
+  return createProjectFixture({
+    name: `three-state-${name}`,
+    config: fixture.configYml,
+    files: {
+      ...Object.fromEntries((fixture.files ?? []).map(f => [f, 'export const x = 1;'])),
+      ...Object.fromEntries((fixture.contextMdDirs ?? []).map(d => [`${d}/CONTEXT.md`, `# ${d}\n`])),
+      ...(fixture.capabilitiesBody === undefined
+        ? {}
+        : { 'CAPABILITIES.md': `# Capabilities\n\n${fixture.capabilitiesBody}` }),
+    },
+  });
+}
+
+const CTX_FILES = (enabled: boolean, dirs?: string[]) =>
+  `governance:\n  context_files:\n    enabled: ${enabled}\n` +
+  (dirs ? `    required_dirs: [${dirs.map(d => `'${d}'`).join(', ')}]\n` : '');
+
+function evalContextDocSync(dir: string) {
+  const context: ConstraintContext = { operation: 'module_modification', projectPath: dir };
+  return contextDocSync.evaluate(buildCheckEnv(context, 'none'));
+}
+
+function evalDocsFreshness(dir: string) {
+  const context: ConstraintContext = { operation: 'file_modification', projectPath: dir };
+  return docsFreshness.evaluate(
+    buildCheckEnv(context, {
+      stagedDiff: async () => '',
+      stagedDiffNames: async () => '',
+      srcScan: (root: string) => collectSourceFiles(dir, [root]),
+    })
+  );
+}
+
+/** 同一 fixture 上两条约束的判定必须一致（对照断言） */
+async function expectBoth(dir: string, verdict: true | false | 'skip'): Promise<void> {
+  expect(await evalContextDocSync(dir)).toBe(verdict);
+  expect(await evalDocsFreshness(dir)).toBe(verdict);
+}
+
+describe('context_files 三态对照 — context_doc_sync vs docs_freshness（工单 84）', () => {
+  it('未配置（无 config.yml）→ 双双 skip', async () => {
+    await expectBoth(setupDir('no-config'), 'skip');
+  });
+
+  it('governance.context_files 段缺失 → 双双 skip', async () => {
+    await expectBoth(setupDir('no-section', { configYml: 'preset: standard\n' }), 'skip');
+  });
+
+  it('enabled: false（约定未采用）→ 双双 skip', async () => {
+    await expectBoth(setupDir('disabled', { configYml: CTX_FILES(false, ['src']) }), 'skip');
+  });
+
+  it('enabled 但 required_dirs 缺失（约定已立但无目标）→ 双双 skip', async () => {
+    await expectBoth(setupDir('no-dirs', { configYml: CTX_FILES(true) }), 'skip');
+  });
+
+  it('enabled 但 required_dirs 为空数组 → 双双 skip', async () => {
+    await expectBoth(setupDir('empty-dirs', { configYml: CTX_FILES(true, []) }), 'skip');
+  });
+
+  it('enabled 但 required_dirs 含非字符串项（脏配置）→ 双双 skip 而非抛错', async () => {
+    await expectBoth(
+      setupDir('dirty-dirs', {
+        configYml: 'governance:\n  context_files:\n    enabled: true\n    required_dirs: [1, null]\n',
+      }),
+      'skip'
+    );
+  });
+
+  it('enabled 且非空 + CONTEXT.md 齐全 → 双双 pass（同一组 dirs 同一判定）', async () => {
+    await expectBoth(
+      setupDir('all-present', {
+        configYml: CTX_FILES(true, ['src', 'bin']),
+        contextMdDirs: ['src', 'bin'],
+      }),
+      true
+    );
+  });
+
+  it('enabled 且非空 + CONTEXT.md 缺失 → 双双 fail', async () => {
+    await expectBoth(
+      setupDir('missing-doc', { configYml: CTX_FILES(true, ['src', 'bin']) }),
+      false
+    );
+  });
+});
+
+describe('docs_freshness 评估段 skip 行为变更（工单 84：约定已立但无目标不再静默放行）', () => {
+  it('doc_freshness.checks 已配 + enabled 但 required_dirs 缺失 → skip（原为 true）', async () => {
+    const dir = setupDir('checks-plus-empty', {
+      configYml:
+        'governance:\n  doc_freshness:\n    checks:\n      - type: changelog_version\n  context_files:\n    enabled: true\n',
+    });
+    expect(await evalDocsFreshness(dir)).toBe('skip');
+  });
+
+  it('enabled 但空 + CAPABILITIES.md 健康 → skip（原为 true）', async () => {
+    const dir = setupDir('caps-healthy', {
+      configYml: CTX_FILES(true),
+      files: ['src/module.ts'],
+      capabilitiesBody: `${TABLE_HEAD}| module | src/module.ts | module |`,
+    });
+    expect(await evalDocsFreshness(dir)).toBe('skip');
+  });
+
+  it('enabled 但空 + CAPABILITIES.md 幽灵条目 → 仍 fail（Step 1 文件表判定不因 context_files 受影响）', async () => {
+    const dir = setupDir('caps-ghost', {
+      configYml: CTX_FILES(true),
+      files: ['src/old.ts'],
+      capabilitiesBody: `${TABLE_HEAD}| old | src/old.ts | 活 |\n| 遗魂 | src/gone/ | 已删 |`,
+    });
+    expect(await evalDocsFreshness(dir)).toBe(false);
+  });
+});

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

@@ -5,11 +5,12 @@
  *   1. Git diff 增量 — 当前变更的非测试文件是否在文档中有记录
  *   2. 全量扫描 — 源码根下所有源文件是否都在 CAPABILITIES.md 中（T-058）
  *
- * 覆盖判定两步统一（isCoveredBy）：目录条目（以 / 结尾）前缀匹配，
- * 文件条目精确匹配或路径边界后缀匹配。module 模式下目录条目参与覆盖，
- * 未覆盖文件按源码根下第一级子目录聚合。
+ * 覆盖/漏登判定不在本文件实现，统一走 capabilities-reconcile（ADR-0009）：
+ * 目录条目（以 / 结尾）前缀匹配，文件条目精确匹配或路径边界后缀匹配；
+ * module 模式下目录条目参与覆盖，未覆盖文件按源码根下第一级子目录聚合。
  *
  * 清单格式（计数行，mode=listing 或嗅探命中）无文件表可核对，直接放行；
+ * 「有表格但零条目」不得放行，无表格的散文文档保持历史放行；
  * 检查异常时 fail-open 但输出 console.warn 保留可观测性。
  *
  * ADR-0001 存在性探测：项目根无 CAPABILITIES.md（未采用该约定）时返回 'skip'，
@@ -18,33 +19,12 @@
 
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
-import {
-  aggregateToSourceSubdir,
-  isCapabilityListingFormat,
-  parseCapabilitiesEntries,
-} from '../capabilities-parser';
+import { isCapabilityListingFormat } from '../capabilities-parser';
 import { getCapabilitiesMode } from '../../project-config-loader';
 import { detectSourceRoots } from '../../../utils/detect-source-roots';
+import { reconcileCapabilities, significantCodeChanges } from '../capabilities-reconcile';
 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) {
@@ -55,15 +35,6 @@ export const capabilitySync: ConstraintCheck = {
     }
     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 content = readFileSync(capabilitiesPath, 'utf-8');
       const capabilitiesMode = getCapabilitiesMode(projectPath);
 
@@ -72,64 +43,34 @@ export const capabilitySync: ConstraintCheck = {
         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);
+      const sourceRoots = detectSourceRoots(projectPath);
+      const population: string[] = [];
+      for (const root of sourceRoots) {
+        if (existsSync(join(projectPath, root))) {
+          population.push(...env.srcScan(root));
+        }
+      }
 
-      // ── 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.')
-      );
+      const diffNames = (await env.stagedDiffNames()).split('\n').filter(Boolean);
+      const verdict = reconcileCapabilities({
+        content,
+        populationFiles: population,
+        changedFiles: significantCodeChanges(diffNames),
+        sourceRoots,
+      });
 
-      // 每个变更文件都必须被覆盖（every；some 会让一个命中掩盖其余漏网）
-      if (
-        significantChanges.length > 0 &&
-        (entries.length > 0 || hasTable) &&
-        !significantChanges.every((changed: string) => isCoveredBy(entries, changed))
-      ) {
-        return false;
-      }
+      // 零条目门槛：有表格但什么都没登记时不得直接放行
+      const gateOpen = verdict.coverageEntries.length === 0 && !verdict.hasTable;
+      if (gateOpen) return true;
+
+      // ── Step 1: Git diff 增量检查（每个变更文件都必须被覆盖）──
+      if (verdict.uncoveredChanges.length > 0) return false;
 
       // ── Step 2: 全量源码根扫描（T-058 修复核心）──
       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 (!isCoveredBy(listedFiles, file)) {
-                return false;
-              }
-            }
-          }
-        }
+        if (verdict.uncoveredDirs.length > 0) return false;
+      } else if (verdict.uncoveredFiles.length > 0) {
+        return false;
       }
 
       return true;

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

@@ -1,43 +1,33 @@
 /**
  * context_doc_sync：关键目录必须有 CONTEXT.md（工单 21）
  *
- * ADR-0001 存在性探测：项目未配置 governance.context_files 约定
- * （未启用或无 required_dirs）时返回 'skip'，不计 pass/fail。
+ * ADR-0001 存在性探测 + context_files 三态统一口径（工单 84）：
+ * 未配置 / enabled 但无目标（required_dirs 缺失或空）→ 一律 'skip'，
+ * 不计 pass/fail，与 docs_freshness 同构；判定只走 resolveContextFiles
+ * 访问器，不做 governance 手写钻取。
  */
 
 import { existsSync } from 'fs';
 import { join } from 'path';
-import { loadRawProjectConfig } from '../../project-config-loader';
+import { resolveContextFiles } 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 'skip'; // 未配置 context_files 约定，跳过评估
-      }
-
-      const requiredDirs = contextFiles.required_dirs as string[];
-      if (requiredDirs.length === 0) {
-        return 'skip'; // 无目标目录，约定未生效
-      }
+    const resolution = resolveContextFiles(projectPath);
+    if (resolution.state !== 'enabled') {
+      return 'skip'; // 未配置或约定已立但无目标，跳过评估
+    }
 
-      for (const dir of requiredDirs) {
-        const contextPath = join(projectPath, dir, 'CONTEXT.md');
-        if (!existsSync(contextPath)) {
-          return false;
-        }
+    for (const dir of resolution.dirs) {
+      const contextPath = join(projectPath, dir, 'CONTEXT.md');
+      if (!existsSync(contextPath)) {
+        return false;
       }
-
-      return true;
-    } catch {
-      return 'skip'; // 配置不存在或解析失败 = 无法判定约定，跳过
     }
+
+    return true;
   },
 };

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

@@ -9,11 +9,12 @@
 
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
-import { loadRawProjectConfig } from '../../project-config-loader';
+import { getGovernanceConfig, resolveContextFiles } 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';
+import { reconcileCapabilities } from '../capabilities-reconcile';
+import type { DocFreshnessCheck } from '../../../types/project-config';
+import type { ConstraintCheck, CheckEnv } from './types';
 
 /**
  * 内置默认文档新鲜度检查配置
@@ -30,45 +31,31 @@ function getBuiltInDocFreshnessConfig(): DocFreshnessCheck[] {
 }
 
 /**
- * CAPABILITIES.md 文件表新鲜度：列出的文件路径必须仍存在。
- * 多根查找：支持不同项目的源码根（harness=src/, studio=apps/api/src/ 等）。
- * 无表格行（能力清单格式）时跳过。
+ * CAPABILITIES.md 文件表新鲜度：登记的条目（文件与目录）必须仍存在（ADR-0009 口径从严）。
+ * 判定逻辑统一走 capabilities-reconcile；多根查找支持不同项目的源码根
+ * （harness=src/, studio=apps/api/src/ 等）。无表格（能力清单格式）时自然零幽灵。
  */
-function checkCapabilitiesFreshness(projectPath: string): boolean {
+function findDeadCapabilityEntries(projectPath: string, env: CheckEnv): string[] {
   try {
     const capabilitiesPath = join(projectPath, 'CAPABILITIES.md');
-    if (!existsSync(capabilitiesPath)) return true;
+    if (!existsSync(capabilitiesPath)) return [];
     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;
+    const population: string[] = [];
+    for (const root of sourceRoots) {
+      if (existsSync(join(projectPath, root))) population.push(...env.srcScan(root));
     }
 
-    return true;
+    const verdict = reconcileCapabilities({
+      content,
+      populationFiles: population,
+      sourceRoots,
+      fileExists: (rel) => existsSync(join(projectPath, rel)),
+    });
+    return verdict.deadEntries;
   } catch {
-    return true;
+    return [];
   }
 }
 
@@ -77,7 +64,7 @@ function checkCapabilitiesFreshness(projectPath: string): boolean {
  *
  * 判定信号（任一命中即视为采用了文档新鲜度约定）：
  * - 配置了 governance.doc_freshness.checks
- * - 配置了 governance.context_files（enabled + 非空 required_dirs）
+ * - 配置了 governance.context_files 且约定有效（enabled + 非空 required_dirs）
  * - 项目根存在 CAPABILITIES.md
  * - 项目根存在 CHANGELOG.md / CHANGELOG
  *
@@ -89,26 +76,12 @@ function hasFreshnessTargets(projectPath: string): boolean {
     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 {
-    // 配置不可读视为无配置
+  const governance = getGovernanceConfig(projectPath);
+  if (governance?.doc_freshness?.checks && governance.doc_freshness.checks.length > 0) {
+    return true;
   }
 
-  return false;
+  return resolveContextFiles(projectPath).state === 'enabled';
 }
 
 export const docsFreshness: ConstraintCheck = {
@@ -119,26 +92,24 @@ export const docsFreshness: ConstraintCheck = {
     // ADR-0001 存在性探测：项目无任何 freshness 配置/目标 → skip（不计 pass/fail）
     if (!hasFreshnessTargets(projectPath)) return 'skip';
 
-    // Step 1: 文件表格式 — 检查列出的文件是否还存在
-    if (!checkCapabilitiesFreshness(projectPath)) return false;
+    // Step 1: 文件表格式 — 登记的条目（文件+目录）是否仍存在（ADR-0009）
+    const deadEntries = findDeadCapabilityEntries(projectPath, env);
+    if (deadEntries.length > 0) {
+      // 报出具体条目：此前只返回 false，CLI 只能打印通用提示，
+      // 幽灵条目 basename 碰撞时 sync-docs 也不剔除，用户无从定位（2026-08-08 studio CI 4 连红）
+      console.error(`[docs_freshness] CAPABILITIES.md 登记的条目不存在: ${deadEntries.join(', ')}`);
+      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 freshnessConfig = getGovernanceConfig(projectPath)?.doc_freshness;
+
+      // context_files 三态统一口径（工单 84）：约定已立但无目标（enabled 但
+      // required_dirs 缺失/空）→ skip，与 context_doc_sync 同构；不再静默放行
+      const contextFiles = resolveContextFiles(projectPath);
+      if (contextFiles.state === 'enabled-empty') return 'skip';
+      const requiredDirs = contextFiles.state === 'enabled' ? contextFiles.dirs : undefined;
 
       const runner = new FreshnessRunner();
       let results: FreshnessCheckResult[];

package/src/core/constraints/checkers/governance-presence.ts

@@ -10,42 +10,24 @@
  * 不强制迁移；两处都没有才报违规。
  */
 
-import { readFileSync } from 'fs';
 import { join } from 'path';
 import { loadRawProjectConfig } from '../../project-config-loader';
+import { hasGovernanceContract, hasPreserveBlock, readIfExists } from '../injection-writer';
 import type { ConstraintCheck } from './types';
 
 /** 治理契约 PRESERVE 段名（ADR 落点模型约定） */
 export const GOVERNANCE_PRESERVE_NAME = 'governance';
 
-const GOVERNANCE_BEGIN_RE = /^<!-- PRESERVE:governance -->\s*$/m;
-
-/** AGENTS.md 是否存在非空 PRESERVE:governance 块（标记须独占一行，与 preserve-block.ts 同语义） */
+/** AGENTS.md 是否存在非空 PRESERVE:governance 块（切片判定收口 injection-writer.hasPreserveBlock，#83） */
 export function hasGovernancePreserveBlock(agentsMdPath: string): boolean {
-  let content: string;
-  try {
-    content = readFileSync(agentsMdPath, 'utf-8');
-  } catch {
-    return false;
-  }
-  const beginMatch = GOVERNANCE_BEGIN_RE.exec(content);
-  if (!beginMatch) return false;
-  const rest = content.slice(beginMatch.index + beginMatch[0].length);
-  const endIdx = rest.indexOf(`<!-- /PRESERVE:${GOVERNANCE_PRESERVE_NAME} -->`);
-  if (endIdx === -1) return false;
-  // 块体（首尾标记之间）去空白后非空才算「在场」
-  return rest.slice(0, endIdx).trim().length > 0;
+  const content = readIfExists(agentsMdPath);
+  return content !== null && hasPreserveBlock(content, GOVERNANCE_PRESERVE_NAME);
 }
 
-/** CLAUDE.md 是否存在治理块（与 agents-syncer getGovernanceInfo 同判定，旧模型仓豁免） */
+/** CLAUDE.md 是否有治理契约在场（判定收口 injection-writer.hasGovernanceContract，#83；旧模型仓豁免） */
 export function hasClaudeGovernance(claudeMdPath: string): boolean {
-  let content: string;
-  try {
-    content = readFileSync(claudeMdPath, 'utf-8');
-  } catch {
-    return false;
-  }
-  return /^##\s+Governance Rules/m.test(content) || content.includes('HARNESS_CONSTRAINTS_START');
+  const content = readIfExists(claudeMdPath);
+  return content !== null && hasGovernanceContract(content);
 }
 
 export const governancePresence: ConstraintCheck = {