@dommaker/harness 1.3.0 → 1.5.0

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

@@ -0,0 +1,273 @@
+/**
+ * capability_sync 检查器旁测（ADR-0009 / 架构评审候选4）
+ *
+ * 测试面 = ConstraintCheck.evaluate(env)：证据经 EvidenceProviders 注入，
+ * 不再绕 engine facade（checker.check）与真实 git staging。
+ * 自 checker-extra.test.ts 迁入并改写驱动方式；断言语义逐条保持。
+ * 项目根由 src/test-setup/project-fixture 声明式构造（回收仍走 mkdtemp-cleanup）。
+ */
+
+import { describe, it, expect, jest } from '@jest/globals';
+import { capabilitySync } from '../capability-sync';
+import { buildCheckEnv, normalizeCheckOutcome, type CheckEnv, type CheckOutcome } 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';
+
+function setupDir(
+  name: string,
+  capContent: string,
+  files: string[] = [],
+  mode?: 'file' | 'module'
+): string {
+  return createProjectFixture({
+    name: `cap-sync-${name}`,
+    config: mode ? `governance:\n  capabilities:\n    mode: ${mode}\n` : undefined,
+    files: {
+      'CAPABILITIES.md': capContent,
+      ...Object.fromEntries(files.map(f => [f, 'export const x = 1;'])),
+    },
+  });
+}
+
+/** stub staged 清单；srcScan 缺省走真实 fs（与被检文件一致），传 scan 则按根覆写 */
+function makeEnv(
+  projectPath: string,
+  staged: string[],
+  scan?: Record<string, string[]>
+): CheckEnv {
+  const context: ConstraintContext = { operation: 'commit', projectPath };
+  return buildCheckEnv(context, {
+    stagedDiff: async () => '',
+    stagedDiffNames: async () => staged.join('\n'),
+    srcScan: (root: string) =>
+      scan ? scan[root] ?? [] : collectSourceFiles(projectPath, [root]),
+  });
+}
+
+/** 判定归一：boolean 与 CheckDetail 两种返回形状统一断言（harness#119） */
+const passed = (outcome: CheckOutcome): boolean => normalizeCheckOutcome(outcome).satisfied;
+/** 证据行拼成单串，便于按路径断言 */
+const evidenceText = (outcome: CheckOutcome): string =>
+  normalizeCheckOutcome(outcome).evidence.join('\n');
+
+describe('capability_sync — skip 与文档格式门槛', () => {
+  it('无 CAPABILITIES.md → skip（ADR-0001 存在性探测，有无变更都一样）', async () => {
+    const dir = createProjectFixture({ name: 'cap-sync-none' });
+    expect(await capabilitySync.evaluate(makeEnv(dir, []))).toBe('skip');
+    expect(await capabilitySync.evaluate(makeEnv(dir, ['src/foo.ts']))).toBe('skip');
+  });
+
+  it('散文文档（无表格）+ 有变更 → 放行（历史语义）', async () => {
+    const dir = setupDir('prose', '# Capabilities\n\n- Feature: test', ['feature.ts']);
+    expect(passed(await capabilitySync.evaluate(makeEnv(dir, ['feature.ts'])))).toBe(true);
+  });
+
+  it('清单格式（计数行）→ 放行，计数由 sync-docs 维护', async () => {
+    const dir = setupDir('listing', '# Capabilities\n\n## CLI Commands (25)\ncheck, validate\n');
+    expect(passed(await capabilitySync.evaluate(makeEnv(dir, ['src/foo.ts'])))).toBe(true);
+  });
+
+  it('有表格但零条目 + 有变更 → 不得放行（step1 拦下，证据点名变更文件）', async () => {
+    const dir = setupDir('empty-table', `# Capabilities\n\n${TABLE_HEAD}`);
+    const outcome = await capabilitySync.evaluate(makeEnv(dir, ['src/foo.ts']));
+    expect(passed(outcome)).toBe(false);
+    expect(evidenceText(outcome)).toContain('src/foo.ts');
+  });
+
+  it('有表格但零条目 + 源码有文件 → 文档退化门拦下（不靠 step2 兜，harness#119）', async () => {
+    const dir = setupDir('empty-table-scan', `# Capabilities\n\n${TABLE_HEAD}`, ['src/foo.ts']);
+    const outcome = await capabilitySync.evaluate(makeEnv(dir, []));
+    expect(passed(outcome)).toBe(false);
+    expect(evidenceText(outcome)).toContain('零条目');
+  });
+
+  it('有表格但零条目 + 源码无文件 → 放行（门限定「确有可登记对象」，不扩大 fail 面）', async () => {
+    const dir = setupDir('empty-table-nosrc', `# Capabilities\n\n${TABLE_HEAD}`);
+    expect(passed(await capabilitySync.evaluate(makeEnv(dir, [])))).toBe(true);
+  });
+});
+
+describe('capability_sync — step1 增量覆盖（唯一判违规处，harness#119）', () => {
+  const run = (dir: string, staged: string[]) =>
+    capabilitySync.evaluate(makeEnv(dir, staged, {}));
+
+  it('变更文件未被登记 → 失败，且证据点名该文件', async () => {
+    const dir = setupDir('step1-uncovered', `# C\n\n${TABLE_HEAD}| 旧 | old/module.ts | 旧 |\n`);
+    const outcome = await run(dir, ['new-module.ts']);
+    expect(passed(outcome)).toBe(false);
+    expect(evidenceText(outcome)).toContain('new-module.ts');
+  });
+
+  it('变更文件按登记路径覆盖 → 通过', async () => {
+    const dir = setupDir('step1-covered', `# C\n\n${TABLE_HEAD}| foo | src/foo.ts | foo |\n`);
+    expect(passed(await run(dir, ['src/foo.ts']))).toBe(true);
+  });
+
+  it('每个变更文件都必须被覆盖（every 而非 some）', async () => {
+    const dir = setupDir('step1-every', `# C\n\n${TABLE_HEAD}| foo | src/foo.ts | foo |\n`);
+    const outcome = await run(dir, ['src/foo.ts', 'scripts/bar.ts']);
+    expect(passed(outcome)).toBe(false);
+    expect(evidenceText(outcome)).toContain('scripts/bar.ts');
+  });
+
+  it('后缀碰撞不覆盖：xfoo.ts 不被 foo.ts 条目覆盖', async () => {
+    const dir = setupDir('step1-endswith', `# C\n\n${TABLE_HEAD}| foo | foo.ts | foo |\n`);
+    expect(passed(await run(dir, ['web/xfoo.ts']))).toBe(false);
+  });
+
+  it('子串误配不覆盖：docs/src/foo.tsx 不被 src/foo.ts 条目覆盖', async () => {
+    const dir = setupDir('step1-includes', `# C\n\n${TABLE_HEAD}| foo | src/foo.ts | foo |\n`);
+    expect(passed(await run(dir, ['docs/src/foo.tsx']))).toBe(false);
+  });
+
+  it('basename 条目按路径边界后缀覆盖（src/foo.ts 被 foo.ts 覆盖）', async () => {
+    const dir = setupDir('step1-suffix-ok', `# C\n\n${TABLE_HEAD}| foo | foo.ts | foo |\n`);
+    expect(passed(await run(dir, ['src/foo.ts']))).toBe(true);
+  });
+
+  it('测试文件与非代码变更不参与 step1', async () => {
+    const dir = setupDir('step1-noncode', `# C\n\n${TABLE_HEAD}| foo | src/foo.ts | foo |\n`);
+    expect(
+      passed(await run(dir, ['src/__tests__/foo.test.ts', 'docs/readme.md', 'package.json']))
+    ).toBe(true);
+  });
+});
+
+describe('capability_sync — step2 全量覆盖（file 模式：只提示，不判违规）', () => {
+  it('全部源文件已登记 → 通过且无提示', async () => {
+    const dir = setupDir(
+      'step2-ok',
+      `# C\n\n${TABLE_HEAD}| foo | src/foo.ts | foo |\n`,
+      ['src/foo.ts']
+    );
+    const outcome = await capabilitySync.evaluate(makeEnv(dir, []));
+    expect(passed(outcome)).toBe(true);
+    expect(evidenceText(outcome)).toBe('');
+  });
+
+  it('有未登记源文件 → 仍通过，但提示点名该文件（harness#119 归位）', async () => {
+    const dir = setupDir(
+      'step2-missing',
+      `# C\n\n${TABLE_HEAD}| foo | src/foo.ts | foo |\n`,
+      ['src/foo.ts', 'src/unlisted.ts']
+    );
+    const outcome = await capabilitySync.evaluate(makeEnv(dir, []));
+    expect(passed(outcome)).toBe(true);
+    const evidence = evidenceText(outcome);
+    expect(evidence).toContain('src/unlisted.ts');
+    expect(evidence).toContain('仓库级漂移');
+    expect(evidence).toContain('sync-docs');
+  });
+
+  it('basename 条目同样按边界后缀覆盖 step2（step1/step2 语义一致）', async () => {
+    const dir = setupDir(
+      'step2-basename',
+      `# C\n\n${TABLE_HEAD}| foo | foo.ts | foo |\n`,
+      ['src/foo.ts']
+    );
+    expect(passed(await capabilitySync.evaluate(makeEnv(dir, [])))).toBe(true);
+  });
+
+  it('不同路径同后缀文件不被误覆盖（lib/foo.ts 不覆盖 src/foo.ts）→ 记为漂移', async () => {
+    const dir = setupDir(
+      'step2-boundary',
+      `# C\n\n${TABLE_HEAD}| foo | lib/foo.ts | foo |\n`,
+      ['src/foo.ts']
+    );
+    const outcome = await capabilitySync.evaluate(makeEnv(dir, []));
+    expect(passed(outcome)).toBe(true);
+    expect(evidenceText(outcome)).toContain('src/foo.ts');
+  });
+
+  it('step1 优先：变更未登记时判违规，证据是变更文件而非仓库漂移清单', async () => {
+    const dir = setupDir(
+      'step1-beats-step2',
+      `# C\n\n${TABLE_HEAD}| foo | src/foo.ts | foo |\n`,
+      ['src/foo.ts', 'src/drifted.ts']
+    );
+    const outcome = await capabilitySync.evaluate(makeEnv(dir, ['src/new.ts']));
+    expect(passed(outcome)).toBe(false);
+    expect(evidenceText(outcome)).toContain('src/new.ts');
+    expect(evidenceText(outcome)).not.toContain('src/drifted.ts');
+  });
+
+  it('漂移项超过 10 个 → 证据截断并给出全量查看入口', async () => {
+    const files = ['src/foo.ts', ...Array.from({ length: 12 }, (_, i) => `src/drift${i}.ts`)];
+    const dir = setupDir('step2-truncate', `# C\n\n${TABLE_HEAD}| foo | src/foo.ts | foo |\n`, files);
+    const outcome = await capabilitySync.evaluate(makeEnv(dir, []));
+    expect(passed(outcome)).toBe(true);
+    const lines = normalizeCheckOutcome(outcome).evidence;
+    expect(lines).toHaveLength(12); // 说明行 + 10 条 + 截断行
+    expect(lines[lines.length - 1]).toContain('另 2 项');
+  });
+});
+
+describe('capability_sync — module 模式（未覆盖聚合为目录形状）', () => {
+  it('目录条目覆盖源文件 → 通过', async () => {
+    const dir = setupDir(
+      'mod-covered',
+      `# C\n\n${TABLE_HEAD}| 核心 | src/core/ | 核心 |\n`,
+      ['src/core/foo.ts', 'src/core/bar.ts'],
+      'module'
+    );
+    expect(passed(await capabilitySync.evaluate(makeEnv(dir, [])))).toBe(true);
+  });
+
+  it('文件条目精确匹配也算覆盖', async () => {
+    const dir = setupDir(
+      'mod-file-entry',
+      `# C\n\n${TABLE_HEAD}| foo | src/core/foo.ts | foo |\n`,
+      ['src/core/foo.ts'],
+      'module'
+    );
+    expect(passed(await capabilitySync.evaluate(makeEnv(dir, [])))).toBe(true);
+  });
+
+  it('新目录未登记 → 不判违规，提示按目录聚合', async () => {
+    const dir = setupDir(
+      'mod-uncovered',
+      `# C\n\n${TABLE_HEAD}| 核心 | src/core/ | 核心 |\n`,
+      ['src/core/foo.ts', 'src/newdir/bar.ts'],
+      'module'
+    );
+    const outcome = await capabilitySync.evaluate(makeEnv(dir, []));
+    expect(passed(outcome)).toBe(true);
+    const evidence = evidenceText(outcome);
+    expect(evidence).toContain('未登记模块目录');
+    expect(evidence).toContain('src/newdir/');
+    expect(evidence).not.toContain('src/newdir/bar.ts');
+  });
+
+  it('module 模式文件条目按边界后缀覆盖（step1/step2 同规则）', async () => {
+    const dir = setupDir(
+      'mod-suffix',
+      `# C\n\n${TABLE_HEAD}| foo | foo.ts | foo |\n`,
+      ['src/foo.ts'],
+      'module'
+    );
+    expect(passed(await capabilitySync.evaluate(makeEnv(dir, [])))).toBe(true);
+  });
+});
+
+describe('capability_sync — fail-open 可观测', () => {
+  it('证据读取异常时放行但输出 warn，且异常原因进 evidence', async () => {
+    const dir = setupDir('failopen', `# C\n\n${TABLE_HEAD}| foo | src/foo.ts | foo |\n`);
+    const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    const env: CheckEnv = {
+      ...makeEnv(dir, []),
+      stagedDiffNames: async () => {
+        throw new Error('git boom');
+      },
+    };
+    const outcome = await capabilitySync.evaluate(env);
+    // fail-open 语义不变（仍不拦），但「因异常而通过」必须留痕：warn 只进本地 stderr
+    expect(passed(outcome)).toBe(true);
+    expect(evidenceText(outcome)).toContain('git boom');
+    expect(evidenceText(outcome)).toContain('fail-open');
+    expect(warnSpy).toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+});

package/src/core/constraints/checkers/__tests__/check-outcome.test.ts

@@ -0,0 +1,176 @@
+/**
+ * 检查结果证据通道测试（harness#119）
+ *
+ * 背景：checker 只回 `boolean | 'skip'`，fail 的具体原因（哪个文件没登记）在 CLI
+ * 与 trace 两头都无处落脚——capability_sync 连红 22 次而无人能说出红在哪。
+ * 本套件锁住新接缝：CheckDetail（pass + evidence）经 normalizeCheckOutcome
+ * 归一后，落到 ConstraintResult.evidence 与 ExecutionTrace.evidence。
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+import { ConstraintChecker } from '../../checker';
+import { normalizeCheckOutcome } from '../types';
+import { createProjectFixture } from '../../../../test-setup/project-fixture';
+import type { ExecutionTrace } from '../../../../types/trace';
+import { ConstraintViolationError } from '../../../../types/constraint';
+import type { Constraint, ConstraintResult } from '../../../../types/constraint';
+import type { MergedConstraintsConfig } from '../../../../types/project-config';
+
+const CAPABILITY_SYNC: Constraint = {
+  id: 'capability_sync',
+  kind: 'check',
+  level: 'guideline',
+  rule: 'CODE CHANGES MUST UPDATE CAPABILITIES.MD',
+  message: '核心模块变更必须同步功能清单',
+  trigger: ['module_modification'],
+  enforcement: 'update-capabilities',
+};
+
+/** 声明式夹具（harness#90）：CAPABILITIES.md + 源文件，无 git，staged 证据自然为空 */
+function fixture(name: string, files: Record<string, string>): string {
+  return createProjectFixture({ name: `cap-sync-${name}`, files });
+}
+
+describe('normalizeCheckOutcome — 三态 + 证据归一', () => {
+  it('boolean 兼容旧形状：true → satisfied / false → violated，evidence 空', () => {
+    expect(normalizeCheckOutcome(true)).toEqual({ satisfied: true, skipped: false, evidence: [] });
+    expect(normalizeCheckOutcome(false)).toEqual({ satisfied: false, skipped: false, evidence: [] });
+  });
+
+  it("'skip' → skipped 且不记证据", () => {
+    expect(normalizeCheckOutcome('skip')).toEqual({ satisfied: true, skipped: true, evidence: [] });
+  });
+
+  it('CheckDetail 透传 pass 与 evidence；缺省 evidence 归一为空数组', () => {
+    expect(normalizeCheckOutcome({ pass: false, evidence: ['a.ts'] })).toEqual({
+      satisfied: false,
+      skipped: false,
+      evidence: ['a.ts'],
+    });
+    expect(normalizeCheckOutcome({ pass: true })).toEqual({
+      satisfied: true,
+      skipped: false,
+      evidence: [],
+    });
+  });
+});
+
+/** 只含 capability_sync 的生效集：一次 run 一条 trace，不牵动其他约束 */
+function onlyCapabilitySync(): MergedConstraintsConfig {
+  return {
+    ironLaws: {},
+    guidelines: { capability_sync: CAPABILITY_SYNC },
+    prompts: {},
+    disabled: [],
+    custom: [],
+  };
+}
+
+/** 跑一次 checkConstraints，返回 capability_sync 的结果与它那条 trace */
+async function runGuideline(dir: string): Promise<{
+  result: ConstraintResult;
+  trace: ExecutionTrace;
+}> {
+  const traces: ExecutionTrace[] = [];
+  const checker = new ConstraintChecker({ record: (t) => traces.push(t) });
+  const run = await checker.checkConstraints(
+    { operation: 'module_modification', projectPath: dir },
+    onlyCapabilitySync()
+  );
+  const result = run.guidelines.find(r => r.id === 'capability_sync')!;
+  const trace = traces.find(t => t.constraintId === 'capability_sync')!;
+  return { result, trace };
+}
+
+/** 需要真 git 的用例专用手写根：夹具不建 git，而 staged 分区只能由真仓库产生 */
+function gitProjectRoot(files: Record<string, string>): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-evidence-git-'));
+  for (const [rel, content] of Object.entries(files)) {
+    const target = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content, 'utf-8');
+  }
+  execFileSync('git', ['init', '-q'], { cwd: dir });
+  execFileSync('git', ['config', 'user.email', 'fixture@example.com'], { cwd: dir });
+  execFileSync('git', ['config', 'user.name', 'Fixture'], { cwd: dir });
+  execFileSync('git', ['add', '.'], { cwd: dir });
+  execFileSync('git', ['commit', '-q', '-m', 'baseline'], { cwd: dir });
+  return dir;
+}
+
+describe('capability_sync 证据经编排层落到 ConstraintResult 与 trace', () => {
+  it('满足但存在仓库级未登记文件 → satisfied=true，evidence 带路径，trace 记 pass', async () => {
+    const dir = fixture('hint', {
+      'CAPABILITIES.md': '| 模块 | 文件 | 说明 |\n|------|------|------|\n| foo | src/foo.ts | foo |\n',
+      'src/foo.ts': 'export const a = 1;\n',
+      'src/unlisted.ts': 'export const b = 2;\n',
+    });
+
+    const { result, trace } = await runGuideline(dir);
+
+    expect(result.satisfied).toBe(true);
+    expect(result.skipped).toBeUndefined();
+    expect(result.evidence?.join('\n')).toContain('unlisted.ts');
+    expect(trace.result).toBe('pass');
+    expect(trace.evidence?.join('\n')).toContain('unlisted.ts');
+  });
+
+  it('违规（staged 新文件未登记）→ satisfied=false，evidence 指出该文件，trace 记 fail', async () => {
+    const dir = gitProjectRoot({
+      'CAPABILITIES.md': '| 模块 | 文件 | 说明 |\n|------|------|------|\n| foo | src/foo.ts | foo |\n',
+      'src/foo.ts': 'export const a = 1;\n',
+    });
+    fs.writeFileSync(path.join(dir, 'src/brand-new.ts'), 'export const c = 3;\n');
+    execFileSync('git', ['add', '--', 'src/brand-new.ts'], { cwd: dir });
+
+    const { result, trace } = await runGuideline(dir);
+
+    expect(result.satisfied).toBe(false);
+    expect(result.evidence?.join('\n')).toContain('src/brand-new.ts');
+    expect(trace.result).toBe('fail');
+    expect(trace.evidence?.join('\n')).toContain('src/brand-new.ts');
+  });
+
+  it('skip 不携带证据（未评估不得留下证据行）', async () => {
+    const dir = fixture('no-convention', { 'README.md': '# no capabilities convention\n' });
+
+    const { result, trace } = await runGuideline(dir);
+
+    expect(result.skipped).toBe(true);
+    expect(result.evidence).toBeUndefined();
+    expect(trace.result).toBe('skip');
+    expect(trace.evidence).toBeUndefined();
+  });
+});
+
+describe('证据随铁律异常外溢（CLI catch 分支只打印 error.message）', () => {
+  it('ConstraintViolationError 文案带出证据行', () => {
+    const error = new ConstraintViolationError({
+      id: 'docs_freshness',
+      level: 'iron_law',
+      satisfied: false,
+      message: '文档新鲜度检查未通过',
+      evidence: ['CAPABILITIES.md 登记的条目不存在:', 'src/gone.ts'],
+      checkedAt: new Date(),
+    });
+
+    expect(error.message).toContain('文档新鲜度检查未通过');
+    expect(error.message).toContain('src/gone.ts');
+  });
+
+  it('无证据时文案保持原样（旧消费方断言不受影响）', () => {
+    const error = new ConstraintViolationError({
+      id: 'no_test_simplification',
+      level: 'iron_law',
+      satisfied: false,
+      message: '禁止简化测试绕过困难',
+      checkedAt: new Date(),
+    });
+
+    expect(error.message).toBe('禁止简化测试绕过困难');
+  });
+});

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

@@ -0,0 +1,77 @@
+/**
+ * context_doc_sync 检查器旁测（架构评审候选4，ADR-0009 同模式）
+ *
+ * 测试面 = ConstraintCheck.evaluate(env)：项目目录为真实 fs 临时目录，
+ * 证据经 buildCheckEnv 注入（本检查器只用 projectPath，证据走 'none'）。
+ * 自 checker-extra.test.ts 迁入并告别 engine facade；三态收紧——
+ * facade 下 skip 表现为 satisfied:true，旁测直接钉 'skip'。
+ * 项目根由 src/test-setup/project-fixture 声明式构造（回收仍走 mkdtemp-cleanup）。
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import { contextDocSync } from '../context-doc-sync';
+import { buildCheckEnv } from '../types';
+import { createProjectFixture } from '../../../../test-setup/project-fixture';
+import type { ConstraintContext } from '../../../../types/constraint';
+
+function setupDir(
+  name: string,
+  configYml: string | null,
+  contextMdDirs: string[] = []
+): string {
+  return createProjectFixture({
+    name: `ctx-doc-sync-${name}`,
+    config: configYml ?? undefined,
+    files: Object.fromEntries(contextMdDirs.map(d => [`${d}/CONTEXT.md`, `# ${d}\n`])),
+  });
+}
+
+function evaluate(dir: string) {
+  const context: ConstraintContext = { operation: 'module_modification', projectPath: dir };
+  return contextDocSync.evaluate(buildCheckEnv(context, 'none'));
+}
+
+const CTX_FILES = (enabled: boolean, dirs?: string[]) =>
+  `governance:\n  context_files:\n    enabled: ${enabled}\n` +
+  (dirs ? `    required_dirs: [${dirs.map(d => `'${d}'`).join(', ')}]\n` : '');
+
+describe('context_doc_sync — skip 门槛（ADR-0001 存在性探测）', () => {
+  it('无 .harness/config.yml → skip', async () => {
+    expect(await evaluate(setupDir('no-config', null))).toBe('skip');
+  });
+
+  it('配置无 governance.context_files → skip', async () => {
+    expect(await evaluate(setupDir('no-section', 'preset: standard\n'))).toBe('skip');
+  });
+
+  it('enabled: false → skip（facade 旧断言 satisfied:true 的真实语义）', async () => {
+    expect(await evaluate(setupDir('disabled', CTX_FILES(false, ['src'])))).toBe('skip');
+  });
+
+  it('enabled 但 required_dirs 缺失/非数组/空 → skip', async () => {
+    expect(await evaluate(setupDir('no-dirs', CTX_FILES(true)))).toBe('skip');
+    expect(await evaluate(setupDir('empty-dirs', CTX_FILES(true, [])))).toBe('skip');
+    expect(
+      await evaluate(
+        setupDir('bad-dirs', 'governance:\n  context_files:\n    enabled: true\n    required_dirs: src\n')
+      )
+    ).toBe('skip');
+  });
+});
+
+describe('context_doc_sync — 判定', () => {
+  it('required_dirs 全部有 CONTEXT.md → pass', async () => {
+    const dir = setupDir('all-present', CTX_FILES(true, ['src', 'bin']), ['src', 'bin']);
+    expect(await evaluate(dir)).toBe(true);
+  });
+
+  it('任一目录缺 CONTEXT.md → fail', async () => {
+    const dir = setupDir('one-missing', CTX_FILES(true, ['src', 'bin']), ['src']);
+    expect(await evaluate(dir)).toBe(false);
+  });
+
+  it('配置解析失败 → skip（不炸不报）', async () => {
+    const dir = setupDir('bad-yaml', 'governance: [\n  broken: {{\n');
+    expect(await evaluate(dir)).toBe('skip');
+  });
+});

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

@@ -0,0 +1,126 @@
+/**
+ * docs_freshness 检查器旁测（ADR-0009 / 架构评审候选4）
+ *
+ * 测试面 = ConstraintCheck.evaluate(env)。幽灵判定走 capabilities-reconcile：
+ * 文件与目录条目都查（口径从严）；无约定文件 → skip。
+ * 项目根由 src/test-setup/project-fixture 声明式构造（回收仍走 mkdtemp-cleanup）。
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import * as fs from 'fs';
+import * as path from 'path';
+import { docsFreshness } from '../docs-freshness';
+import { buildCheckEnv, normalizeCheckOutcome, type CheckOutcome } 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';
+
+/** 证据行拼成单串，便于按路径断言（harness#119） */
+const evidenceText = (outcome: CheckOutcome): string =>
+  normalizeCheckOutcome(outcome).evidence.join('\n');
+
+function setupProject(name: string, files: string[]): string {
+  return createProjectFixture({
+    name: `docs-fresh-${name}`,
+    files: Object.fromEntries(files.map(f => [f, 'export const x = 1;'])),
+  });
+}
+
+function makeEnv(projectPath: string): ReturnType<typeof buildCheckEnv> {
+  const context: ConstraintContext = { operation: 'file_modification', projectPath };
+  return buildCheckEnv(context, {
+    stagedDiff: async () => '',
+    stagedDiffNames: async () => '',
+    srcScan: (root: string) => collectSourceFiles(projectPath, [root]),
+  });
+}
+
+function writeCap(dir: string, body: string): void {
+  fs.writeFileSync(path.join(dir, 'CAPABILITIES.md'), `# Capabilities\n\n${body}`);
+}
+
+describe('docs_freshness — 存在性探测（ADR-0001）', () => {
+  it('无 CAPABILITIES.md/CHANGELOG/配置 → skip，不计 pass/fail', async () => {
+    const dir = setupProject('none', ['src/module.ts']);
+    expect(await docsFreshness.evaluate(makeEnv(dir))).toBe('skip');
+  });
+});
+
+describe('docs_freshness — 幽灵判定（文档→代码方向）', () => {
+  it('散文文档（无表格）→ 通过', async () => {
+    const dir = setupProject('no-table', []);
+    writeCap(dir, 'No table here.');
+    expect(await docsFreshness.evaluate(makeEnv(dir))).toBe(true);
+  });
+
+  it('登记的文件全部存在 → 通过', async () => {
+    const dir = setupProject('valid', ['src/old.ts', 'src/new.ts']);
+    writeCap(
+      dir,
+      `${TABLE_HEAD}| old | src/old.ts | old |\n| new | src/new.ts | new |`
+    );
+    expect(await docsFreshness.evaluate(makeEnv(dir))).toBe(true);
+  });
+
+  it('登记的文件已删除 → 失败并点名条目', async () => {
+    const dir = setupProject('ghost-file', ['src/old.ts']);
+    writeCap(
+      dir,
+      `${TABLE_HEAD}| old | src/old.ts | old |\n| deleted | src/deleted.ts | deleted |`
+    );
+    const outcome = await docsFreshness.evaluate(makeEnv(dir));
+    expect(normalizeCheckOutcome(outcome).satisfied).toBe(false);
+    expect(evidenceText(outcome)).toContain('src/deleted.ts');
+  });
+
+  it('登记的目录条目已消失 → 失败（ADR-0009 口径从严，文件+目录都查）', async () => {
+    const dir = setupProject('ghost-dir', ['src/core/foo.ts']);
+    writeCap(
+      dir,
+      `${TABLE_HEAD}| 核心 | src/core/ | 核心 |\n| 遗魂 | src/gone/ | 已删目录 |`
+    );
+    const outcome = await docsFreshness.evaluate(makeEnv(dir));
+    expect(normalizeCheckOutcome(outcome).satisfied).toBe(false);
+    expect(evidenceText(outcome)).toContain('src/gone/');
+  });
+
+  it('登记的目录条目仍存在 → 通过', async () => {
+    const dir = setupProject('dir-alive', ['src/core/foo.ts']);
+    writeCap(dir, `${TABLE_HEAD}| 核心 | src/core/ | 核心 |`);
+    expect(await docsFreshness.evaluate(makeEnv(dir))).toBe(true);
+  });
+
+  it('basename 碰撞场景：全路径幽灵即使同名文件存活仍被报出（2026-08-08 事故回归）', async () => {
+    const dir = setupProject('collision', ['src/agents/routes.ts']);
+    writeCap(
+      dir,
+      `${TABLE_HEAD}| routes | src/agents/routes.ts | 活 |\n| 旧路由 | src/agent-configs/routes.ts | 已删 |`
+    );
+    const outcome = await docsFreshness.evaluate(makeEnv(dir));
+    expect(normalizeCheckOutcome(outcome).satisfied).toBe(false);
+    expect(evidenceText(outcome)).toContain('src/agent-configs/routes.ts');
+  });
+});
+
+describe('docs_freshness — 内置 Runner 检查（changelog/context）', () => {
+  it('无 CHANGELOG 但有 CAPABILITIES.md 且条目健康 → 通过', async () => {
+    const dir = setupProject('runner-ok', ['src/module.ts']);
+    writeCap(dir, `${TABLE_HEAD}| module | src/module.ts | module |`);
+    expect(await docsFreshness.evaluate(makeEnv(dir))).toBe(true);
+  });
+
+  it('CHANGELOG 版本与 package.json 漂移 → 失败', async () => {
+    const dir = setupProject('ver-drift', ['src/module.ts']);
+    writeCap(dir, `${TABLE_HEAD}| module | src/module.ts | module |`);
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      JSON.stringify({ name: 'x', version: '2.0.0' })
+    );
+    fs.writeFileSync(path.join(dir, 'CHANGELOG.md'), '## [1.0.0] - 2026-01-01\n\n- old\n');
+    const outcome = await docsFreshness.evaluate(makeEnv(dir));
+    expect(normalizeCheckOutcome(outcome).satisfied).toBe(false);
+    expect(evidenceText(outcome)).toContain('1.0.0 !== package.json 版本 2.0.0');
+  });
+});