@dommaker/harness 0.19.0 → 1.1.0

package/src/cli/commands/sync-docs/capabilities-syncer.ts

@@ -1,18 +1,14 @@
 /**
- * CAPABILITIES.md 同步器（工单 22）
+ * CAPABILITIES.md 文件表格同步器（工单 22）
  *
- * 支持两种格式：
- * - 文件表格格式：模块/文件/说明三列表格，增删行维护
- * - 能力清单格式：计数行（CLI Commands (N) 等），FreshnessRunner 校验与刷新
+ * 只负责文件表格格式：模块/文件/说明三列表格，增删行维护。
+ * 能力清单格式（计数行）的解析与计数已收敛到 core/constraints/capabilities-parser（H2 O10-R3）。
  */
 
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import { IRON_LAWS, GUIDELINES, TIPS } from '../../../core/constraints/definitions';
-import { isCapabilityListingFormat, readCapabilitiesEntries } from '../../../core/constraints/capabilities-parser';
-import { FreshnessRunner } from '../../../core/constraints/doc-freshness/runner';
+import { readCapabilitiesEntries } from '../../../core/constraints/capabilities-parser';
 import type { CapabilitiesMode } from '../../../core/project-config-loader';
-import type { DocFreshnessCheck } from '../../../types/project-config';
 import type { ModuleInfo, SyncResult } from './project-reader';
 
 /**
@@ -33,108 +29,6 @@ export async function parseCapabilitiesFiles(capabilitiesPath: string): Promise<
   return files;
 }
 
-/**
- * 检测 CAPABILITIES.md 是否使用能力清单格式（计数行），而非文件表格格式
- *
- * @deprecated 实现已收敛到 core/constraints/capabilities-parser（与工单 19-B 同方向），
- * 此处保留 re-export 兼容现有调用方
- */
-export { isCapabilityListingFormat };
-
-/**
- * 构建 CAPABILITIES.md 能力清单格式的检查配置
- */
-function buildCapabilityChecks(): DocFreshnessCheck[] {
-  return [
-    {
-      type: 'doc_regex_count',
-      doc: 'CAPABILITIES.md',
-      label: 'CLI Commands',
-      pattern: 'CLI Commands\\s*\\((\\d+)\\)',
-      actual: { kind: 'dir_count', path: 'src/cli/commands', extension: '.ts', exclude: ['index.ts'] },
-    },
-    {
-      type: 'doc_regex_count',
-      doc: 'CAPABILITIES.md',
-      label: 'Quality Gates',
-      pattern: 'Quality Gates?\\s*\\((\\d+)\\)',
-      actual: { kind: 'dir_count', path: 'src/gates', extension: '.ts', exclude: ['index.ts', 'types.ts'] },
-    },
-    {
-      type: 'doc_regex_count',
-      doc: 'CAPABILITIES.md',
-      label: 'Iron Laws',
-      pattern: 'Iron Laws?\\s*\\((\\d+)\\)',
-      actual: { kind: 'const_count', value: Object.keys(IRON_LAWS).length },
-    },
-    {
-      type: 'doc_regex_count',
-      doc: 'CAPABILITIES.md',
-      label: 'Guidelines',
-      pattern: 'Guidelines?\\s*\\((\\d+)\\)',
-      actual: { kind: 'const_count', value: Object.keys(GUIDELINES).length },
-    },
-    {
-      type: 'doc_regex_count',
-      doc: 'CAPABILITIES.md',
-      label: 'Tips',
-      pattern: 'Tips?\\s*\\((\\d+)\\)',
-      actual: { kind: 'const_count', value: Object.keys(TIPS).length },
-    },
-  ];
-}
-
-/**
- * 使用 FreshnessRunner 检查能力清单计数是否与代码一致（--check 模式）
- */
-export function checkCapabilityCounts(
-  projectPath: string
-): { match: boolean; mismatches: string[] } {
-  const runner = new FreshnessRunner();
-  const checks = buildCapabilityChecks();
-  const results = runner.runAll({ checks }, projectPath);
-
-  const mismatches: string[] = [];
-  for (const r of results) {
-    if (!r.pass && r.message) {
-      mismatches.push(r.message);
-    }
-  }
-
-  return { match: mismatches.length === 0, mismatches };
-}
-
-/**
- * 更新 CAPABILITIES.md 中的能力清单计数（write 模式）
- *
- * 使用 FreshnessRunner 获取实际计数，然后 regex 替换文档计数行。
- */
-export function updateCapabilityCounts(content: string, projectPath: string): string {
-  const runner = new FreshnessRunner();
-
-  const cliCount = runner.countFromDir('src/cli/commands', '.ts', ['index.ts'], projectPath);
-  const gateCount = runner.countFromDir('src/gates', '.ts', ['index.ts', 'types.ts'], projectPath);
-  const ironCount = Object.keys(IRON_LAWS).length;
-  const guideCount = Object.keys(GUIDELINES).length;
-  const tipsCount = Object.keys(TIPS).length;
-
-  const replacements: [RegExp, string][] = [
-    [/CLI Commands\s*\(\d+\)/, `CLI Commands (${cliCount})`],
-    [/Quality Gates?\s*\(\d+\)/, `Quality Gates (${gateCount})`],
-    [/Iron Laws?\s*\(\d+\)/, `Iron Laws (${ironCount})`],
-    [/Guidelines?\s*\(\d+\)/, `Guidelines (${guideCount})`],
-    [/Tips?\s*\(\d+\)/, `Tips (${tipsCount})`],
-  ];
-
-  for (const [regex, replacement] of replacements) {
-    if (regex.test(content)) {
-      content = content.replace(regex, replacement);
-    }
-  }
-
-  return content;
-}
-
 /**
  * 更新 CAPABILITIES.md 文件
  *

package/src/cli/commands/sync-docs/index.ts

@@ -6,7 +6,7 @@
  *
  * 实现拆分：
  * - project-reader.ts       项目信息读取（package.json/config.yml/源码扫描）
- * - capabilities-syncer.ts  CAPABILITIES.md 两种格式的对比与维护
+ * - capabilities-syncer.ts  CAPABILITIES.md 文件表格格式的对比与维护（能力清单格式解析/计数走 core/constraints/capabilities-parser）
  * - context-syncer.ts       CONTEXT.md 模板生成/发现/过时判定
  * - agents-syncer.ts        AGENTS.md 生成
  * - preserve-block.ts       PRESERVE 标记块提取与组合
@@ -16,16 +16,19 @@ import chalk from 'chalk';
 import * as fs from 'fs/promises';
 import { existsSync } from 'fs';
 import * as path from 'path';
-import { aggregateToSourceSubdir, readCapabilitiesEntries } from '../../../core/constraints/capabilities-parser';
+import {
+  aggregateToSourceSubdir,
+  readCapabilitiesEntries,
+  isCapabilityListingFormat,
+  checkCapabilityCounts,
+  updateCapabilityCounts,
+} from '../../../core/constraints/capabilities-parser';
 import { detectSourceRoots } from '../../../utils/detect-source-roots';
 import { getCapabilitiesMode } from '../../../core/project-config-loader';
 import { getSourceDirs, scanSourceModules, getRequiredContextDirs } from './project-reader';
 import type { ModuleInfo, SyncResult } from './project-reader';
 import {
   parseCapabilitiesFiles,
-  isCapabilityListingFormat,
-  checkCapabilityCounts,
-  updateCapabilityCounts,
   updateCapabilitiesFile,
   compactCapabilitiesContent,
 } from './capabilities-syncer';

package/src/completion-checkers/CONTEXT.md

@@ -0,0 +1,25 @@
+# completion-checkers/
+
+## 职责
+WU 收尾软观测三纯判定函数（T7-E1，studio#160）：tdd-chain 引用链 / phase-format subject 结构 / contract-presence 契约在场。纯函数，不碰文件系统与 git，commits 由调用方（studio completion-gates 第四段守卫，T7-E2）供给。
+
+## 核心导出
+- `verifyTddChain(commits, config)`（`tdd-chain.ts`）——实现 commit 须带 trailer `Tested-By: <sha>`（`TESTED_BY_RE` 写死）；被引 sha 须在本提交集内、位置在前、文件清单命中 test_globs；`Tests: none`（`TESTS_NONE_RE`）→ waiver；纯测试/纯非代码 commit 天然免检
+- `verifyPhaseFormat(commits, config)`（`phase-format.ts`）——非 merge commit subject 命中 `PHASE_SUBJECT_RE`（`^phase\([a-z0-9-]+\):\s+\S`，写死）；merge commit 记违规（`CommitInput.isMerge` 优先，缺省 subject 启发式）
+- `verifyContractPresence(type, context, config)`（`contract-presence.ts`）——yml contracts 清单查表，无表项 = skip；类型→判定方法映射是代码不是配置（review → `context.reviewReport` 在场）；清单内无判定方法 = violation（配置与代码失配）
+- `CompletionCheckersConfig`（`types.ts`）——enabled 总开关 / checkers 各开关 / testGlobs / noncodeGlobs / contracts；协议格式不进配置
+- `classifyCommitFiles` / `resolveGlobs`（`classify.ts`）——文件分类，tdd-chain 与 phase-format 共享口径
+- `matchGlob` / `matchAnyGlob` / `DEFAULT_TEST_GLOBS` / `DEFAULT_NONCODE_GLOBS`（`glob-match.ts`）——轻量 glob 匹配（`**`/`*`/`?`）
+
+## 依赖关系
+- 无内部依赖（纯函数模块，自包含）
+
+## 约定
+- 与 ConstraintCheck 闭环注册表无关：直接 export，禁止注册进 checkers/index.ts
+- verdict 四态：pass / violation / waiver（豁免放行，commit 级）/ skip（不适用，不记台账）
+- 新增契约类型 = `CONTRACT_JUDGMENTS` 加一条映射 + 测试
+- 协议格式（Tested-By、Tests: none、phase 结构）写死为机制本体，不得配置化
+
+## 注意事项
+- commits 输入有序（base..HEAD 升序），位置判定比索引不比时间戳
+- Tested-By 引用支持 7-40 位 sha 前缀匹配

package/src/completion-checkers/__tests__/contract-presence.test.ts

@@ -0,0 +1,44 @@
+/**
+ * verifyContractPresence 测试（studio#160 验收：契约标记缺失 / 无表项 skip）
+ */
+
+import { verifyContractPresence } from '../contract-presence';
+
+describe('verifyContractPresence', () => {
+  it('无表项类型 → skip（不算违规）', () => {
+    const result = verifyContractPresence('review', {}, { contracts: [] });
+    expect(result.verdict).toBe('skip');
+    expect(result.detail).toContain('无 contracts 表项');
+  });
+
+  it('contracts 缺省（未配置）→ skip', () => {
+    expect(verifyContractPresence('review', { reviewReport: {} }).verdict).toBe('skip');
+  });
+
+  it('review 在场（reviewReport 已解析）→ pass', () => {
+    const result = verifyContractPresence(
+      'review',
+      { reviewReport: { verdict: 'pass' } },
+      { contracts: ['review'] },
+    );
+    expect(result.verdict).toBe('pass');
+  });
+
+  it.each([undefined, null])('review 契约标记缺失（reviewReport=%s）→ violation', (reviewReport) => {
+    const result = verifyContractPresence('review', { reviewReport }, { contracts: ['review'] });
+    expect(result.verdict).toBe('violation');
+    expect(result.detail).toContain('契约标记缺失');
+  });
+
+  it('类型在清单内但无判定方法注册 → violation（配置与代码失配）', () => {
+    const result = verifyContractPresence('unknown-type', {}, { contracts: ['unknown-type'] });
+    expect(result.verdict).toBe('violation');
+    expect(result.detail).toContain('无判定方法注册');
+  });
+
+  it('checker 关闭 → skip', () => {
+    expect(
+      verifyContractPresence('review', {}, { contracts: ['review'], checkers: { contractPresence: false } }).verdict,
+    ).toBe('skip');
+  });
+});

package/src/completion-checkers/__tests__/phase-format.test.ts

@@ -0,0 +1,60 @@
+/**
+ * verifyPhaseFormat 测试（studio#160 验收：subject 不合规 / merge commit 违规）
+ */
+
+import { verifyPhaseFormat } from '../phase-format';
+import type { CommitInput } from '../types';
+
+const sha = (n: number) => n.toString(16).padStart(40, '0');
+
+function commit(partial: Partial<CommitInput> & { sha: string }): CommitInput {
+  return { subject: 'phase(impl): x', body: '', files: ['src/a.ts'], ...partial };
+}
+
+describe('verifyPhaseFormat', () => {
+  it('合规 subject → pass', () => {
+    const commits = [
+      commit({ sha: sha(1), subject: 'phase(test): add chain tests' }),
+      commit({ sha: sha(2), subject: 'phase(impl-2): wire it' }),
+    ];
+    const result = verifyPhaseFormat(commits);
+    expect(result.verdict).toBe('pass');
+  });
+
+  it.each([
+    'feat: not a phase subject',
+    'phase: missing scope',
+    'phase(Impl): uppercase scope',
+    'phase(impl):missing space after colon',
+    'phase(impl): ',
+  ])('subject 不合规 → violation：%s', (subject) => {
+    const result = verifyPhaseFormat([commit({ sha: sha(1), subject })]);
+    expect(result.verdict).toBe('violation');
+    expect(result.commits[0].reason).toContain('subject 不合规');
+  });
+
+  it('merge commit（显式 isMerge）→ violation', () => {
+    const result = verifyPhaseFormat([commit({ sha: sha(1), isMerge: true })]);
+    expect(result.verdict).toBe('violation');
+    expect(result.commits[0].reason).toContain('merge commit');
+  });
+
+  it('merge commit（isMerge 缺省时 subject 启发式）→ violation', () => {
+    const result = verifyPhaseFormat([
+      commit({ sha: sha(1), subject: "Merge branch 'w/x'" }),
+    ]);
+    expect(result.verdict).toBe('violation');
+  });
+
+  it('显式 isMerge=false 覆盖 subject 启发式', () => {
+    const result = verifyPhaseFormat([
+      commit({ sha: sha(1), subject: 'Merge 字样但非 merge', isMerge: false }),
+    ]);
+    // subject 不含 phase 结构，仍因 subject 违规——但不应记 merge 违规
+    expect(result.commits[0].reason).not.toContain('merge commit');
+  });
+
+  it('checker 关闭 → skip', () => {
+    expect(verifyPhaseFormat([commit({ sha: sha(1) })], { checkers: { phaseFormat: false } }).verdict).toBe('skip');
+  });
+});

package/src/completion-checkers/__tests__/tdd-chain.test.ts

@@ -0,0 +1,99 @@
+/**
+ * verifyTddChain 测试（studio#160 验收：伪造引用三形态 / Tests: none waiver / 免检分类）
+ */
+
+import { verifyTddChain } from '../tdd-chain';
+import type { CommitInput } from '../types';
+
+const sha = (n: number) => n.toString(16).padStart(40, '0');
+
+function commit(partial: Partial<CommitInput> & { sha: string }): CommitInput {
+  return { subject: 'phase(impl): x', body: '', files: ['src/a.ts'], ...partial };
+}
+
+describe('verifyTddChain', () => {
+  it('合法引用链 → pass（测试 commit 在前，实现 commit 引用它）', () => {
+    const commits = [
+      commit({ sha: sha(1), files: ['src/a.test.ts'], subject: 'phase(test): add test' }),
+      commit({ sha: sha(2), files: ['src/a.ts'], body: 'impl\n\nTested-By: ' + sha(1) }),
+    ];
+    const result = verifyTddChain(commits);
+    expect(result.verdict).toBe('pass');
+    expect(result.commits.map((c) => c.verdict)).toEqual(['skip', 'pass']);
+  });
+
+  it('短 sha（7 位前缀）引用可命中', () => {
+    const commits = [
+      commit({ sha: sha(1), files: ['__tests__/a.ts'] }),
+      commit({ sha: sha(2), body: 'Tested-By: ' + sha(1).slice(0, 7) }),
+    ];
+    expect(verifyTddChain(commits).verdict).toBe('pass');
+  });
+
+  it('伪造引用：sha 不在提交集内 → violation', () => {
+    const commits = [commit({ sha: sha(2), body: 'Tested-By: ' + sha(9) })];
+    const result = verifyTddChain(commits);
+    expect(result.verdict).toBe('violation');
+    expect(result.commits[0].reason).toContain('不在本 WU 提交集内');
+  });
+
+  it('伪造引用：被引 commit 位置在本 commit 之后 → violation', () => {
+    const commits = [
+      commit({ sha: sha(2), body: 'Tested-By: ' + sha(1) }),
+      commit({ sha: sha(1), files: ['src/a.test.ts'] }),
+    ];
+    const result = verifyTddChain(commits);
+    expect(result.verdict).toBe('violation');
+    expect(result.commits[0].reason).toContain('位置不在本 commit 之前');
+  });
+
+  it('伪造引用：被引 commit 文件清单不含测试文件 → violation', () => {
+    const commits = [
+      commit({ sha: sha(1), files: ['src/b.ts'] }),
+      commit({ sha: sha(2), body: 'Tested-By: ' + sha(1) }),
+    ];
+    const result = verifyTddChain(commits);
+    expect(result.verdict).toBe('violation');
+    expect(result.commits[1].reason).toContain('未命中 test_globs');
+  });
+
+  it('缺 Tested-By trailer → violation', () => {
+    const result = verifyTddChain([commit({ sha: sha(1) })]);
+    expect(result.verdict).toBe('violation');
+    expect(result.commits[0].reason).toContain('缺 Tested-By trailer');
+  });
+
+  it('Tests: none trailer → waiver（放行，不算 violation）', () => {
+    const result = verifyTddChain([commit({ sha: sha(1), body: 'chore\n\nTests: none' })]);
+    expect(result.verdict).toBe('pass');
+    expect(result.commits[0].verdict).toBe('waiver');
+  });
+
+  it('纯测试 commit 与纯非代码 commit 天然免检', () => {
+    const commits = [
+      commit({ sha: sha(1), files: ['src/a.test.ts'] }),
+      commit({ sha: sha(2), files: ['README.md', 'docs/guide.md'] }),
+    ];
+    const result = verifyTddChain(commits);
+    expect(result.verdict).toBe('pass');
+    expect(result.commits.every((c) => c.verdict === 'skip')).toBe(true);
+  });
+
+  it('混合 commit（代码+测试同 commit）仍需引用链', () => {
+    const commits = [commit({ sha: sha(1), files: ['src/a.ts', 'src/a.test.ts'] })];
+    expect(verifyTddChain(commits).verdict).toBe('violation');
+  });
+
+  it('自定义 test_globs / noncode_globs 生效', () => {
+    const commits = [commit({ sha: sha(1), files: ['assets/logo.png'] })];
+    const withGlob = verifyTddChain(commits, { noncodeGlobs: ['**/*.png'] });
+    expect(withGlob.commits[0].verdict).toBe('skip');
+    expect(verifyTddChain(commits).commits[0].verdict).toBe('violation');
+  });
+
+  it('checker 关闭 / 总开关关闭 → skip', () => {
+    const commits = [commit({ sha: sha(1) })];
+    expect(verifyTddChain(commits, { checkers: { tddChain: false } }).verdict).toBe('skip');
+    expect(verifyTddChain(commits, { enabled: false }).verdict).toBe('skip');
+  });
+});

package/src/completion-checkers/classify.ts

@@ -0,0 +1,47 @@
+/**
+ * commit 文件分类（tdd-chain 与 phase-format 共享同一份分类结果，Q4 定稿）
+ *
+ * - 纯非代码（全部命中 noncode_globs）与纯测试（全部命中 test_globs）commit 天然免检
+ * - 混合 commit 只要触到代码文件即需走引用链
+ * - 空文件清单按免检处理
+ */
+
+import type { CommitInput, CompletionCheckersConfig } from './types';
+import { DEFAULT_NONCODE_GLOBS, DEFAULT_TEST_GLOBS, matchAnyGlob } from './glob-match';
+
+/** 单 commit 文件分类结果 */
+export interface CommitFileClassification {
+  /** 无代码文件（纯测试 / 纯非代码 / 空清单）→ 天然免检 */
+  exempt: boolean;
+  /** 文件清单命中 test_globs（被引 commit 须满足） */
+  hasTests: boolean;
+}
+
+/** 从配置取 glob（缺省落默认） */
+export function resolveGlobs(config: CompletionCheckersConfig): { testGlobs: string[]; noncodeGlobs: string[] } {
+  return {
+    testGlobs: config.testGlobs ?? DEFAULT_TEST_GLOBS,
+    noncodeGlobs: config.noncodeGlobs ?? DEFAULT_NONCODE_GLOBS,
+  };
+}
+
+/** 分类单 commit 的文件清单 */
+export function classifyCommitFiles(
+  commit: CommitInput,
+  testGlobs: string[],
+  noncodeGlobs: string[],
+): CommitFileClassification {
+  if (commit.files.length === 0) {
+    return { exempt: true, hasTests: false };
+  }
+  let hasTests = false;
+  let hasCode = false;
+  for (const file of commit.files) {
+    if (matchAnyGlob(file, testGlobs)) {
+      hasTests = true;
+    } else if (!matchAnyGlob(file, noncodeGlobs)) {
+      hasCode = true;
+    }
+  }
+  return { exempt: !hasCode, hasTests };
+}

package/src/completion-checkers/contract-presence.ts

@@ -0,0 +1,40 @@
+/**
+ * contract-presence：通用契约在场引擎（Q5 定稿）
+ *
+ * - 按 yml contracts 类型清单查表：类型不在清单内 = skip（不算违规）
+ * - 类型 → 判定方法的映射是代码不是配置（CONTRACT_JUDGMENTS）；
+ *   首个活跃条目 review → context.reviewReport 在场（studio agent-loop 已解析字段，不重复解析）
+ * - 类型在清单内但无判定方法注册 = violation（暴露配置与代码失配）
+ */
+
+import type { CompletionCheckersConfig, ContractPresenceContext, ContractPresenceResult } from './types';
+
+/** 类型 → 判定方法映射（代码，不是配置）。新增契约类型 = 在此加一条 + 测试 */
+const CONTRACT_JUDGMENTS: Record<string, (context: ContractPresenceContext) => boolean> = {
+  review: (context) => context.reviewReport != null,
+};
+
+/** 契约在场判定 */
+export function verifyContractPresence(
+  type: string,
+  context: ContractPresenceContext,
+  config: CompletionCheckersConfig = {},
+): ContractPresenceResult {
+  if (config.enabled === false || config.checkers?.contractPresence === false) {
+    return { checker: 'contract-presence', verdict: 'skip', detail: 'checker 已禁用' };
+  }
+  if (!(config.contracts ?? []).includes(type)) {
+    return { checker: 'contract-presence', verdict: 'skip', detail: `类型 ${type} 无 contracts 表项` };
+  }
+  const judge = CONTRACT_JUDGMENTS[type];
+  if (!judge) {
+    return {
+      checker: 'contract-presence',
+      verdict: 'violation',
+      detail: `类型 ${type} 已在 contracts 声明但无判定方法注册（配置与代码失配）`,
+    };
+  }
+  return judge(context)
+    ? { checker: 'contract-presence', verdict: 'pass' }
+    : { checker: 'contract-presence', verdict: 'violation', detail: `类型 ${type} 契约标记缺失` };
+}

package/src/completion-checkers/glob-match.ts

@@ -0,0 +1,54 @@
+/**
+ * 轻量 glob 匹配（支持 `**`、`*`、`?`），用于 commits 文件清单分类。
+ * 不匹配文件系统，纯字符串判定。
+ */
+
+/** 默认测试文件 glob（Q2 定稿） */
+export const DEFAULT_TEST_GLOBS = ['**/*.test.ts', '**/*.spec.ts', '**/__tests__/**'];
+
+/** 默认非代码文件 glob（兜底；权威清单由 yml noncode_globs 供给） */
+export const DEFAULT_NONCODE_GLOBS = ['**/*.md', '**/*.mdx', '**/*.txt', 'docs/**'];
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+}
+
+/** glob → 锚定正则。前缀 `**` + `/` 匹配零或多段路径；`*` 不跨 `/`；`?` 匹配单个非 `/` 字符 */
+function globToRegExp(glob: string): RegExp {
+  let re = '';
+  let i = 0;
+  while (i < glob.length) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        if (glob[i + 2] === '/') {
+          re += '(?:[^/]+/)*';
+          i += 3;
+        } else {
+          re += '.*';
+          i += 2;
+        }
+      } else {
+        re += '[^/]*';
+        i += 1;
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+      i += 1;
+    } else {
+      re += escapeRegExp(c);
+      i += 1;
+    }
+  }
+  return new RegExp('^' + re + '$');
+}
+
+/** 单 glob 匹配 */
+export function matchGlob(file: string, glob: string): boolean {
+  return globToRegExp(glob).test(file);
+}
+
+/** 命中任一 glob */
+export function matchAnyGlob(file: string, globs: string[]): boolean {
+  return globs.some((g) => matchGlob(file, g));
+}

package/src/completion-checkers/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Completion Checkers（T7-E1，studio#160）
+ *
+ * WU 收尾软观测三件套——纯判定函数库：
+ * - verifyTddChain：实现 commit 的 Tested-By 引用链验证
+ * - verifyPhaseFormat：phase(...) subject 结构验证
+ * - verifyContractPresence：通用契约在场引擎
+ *
+ * 与 ConstraintCheck 闭环注册表无关：直接 export，不注册、不碰 checkers/index.ts。
+ * 函数不碰文件系统与 git；commits 由调用方（studio 第四段守卫，T7-E2）供给。
+ */
+
+export * from './types';
+export { DEFAULT_TEST_GLOBS, DEFAULT_NONCODE_GLOBS, matchGlob, matchAnyGlob } from './glob-match';
+export { classifyCommitFiles, resolveGlobs } from './classify';
+export type { CommitFileClassification } from './classify';
+export { verifyTddChain, TESTED_BY_RE, TESTS_NONE_RE } from './tdd-chain';
+export { verifyPhaseFormat, PHASE_SUBJECT_RE } from './phase-format';
+export { verifyContractPresence } from './contract-presence';

package/src/completion-checkers/phase-format.ts

@@ -0,0 +1,48 @@
+/**
+ * phase-format：WU 提交 subject 的 phase 结构验证（Q4 定稿）
+ *
+ * 协议（正则写死在函数里，不进配置）：
+ * - 全部非 merge commit 的 subject 命中 `^phase\([a-z0-9-]+\):\s+\S`
+ * - merge commit 出现即记违规
+ * - 阶段名不维护词表不查
+ * - 文件分类口径与 tdd-chain 共享（classify.ts），本 checker 不做免检——subject 结构要求覆盖全部非 merge commit
+ */
+
+import type { CommitInput, CommitVerdict, CompletionCheckersConfig, PhaseFormatResult } from './types';
+
+/** phase subject 结构（写死） */
+export const PHASE_SUBJECT_RE = /^phase\([a-z0-9-]+\):\s+\S/;
+
+/** merge commit 的 subject 启发式（调用方未显式给 isMerge 时兜底） */
+const MERGE_SUBJECT_RE = /^Merge\s/;
+
+/** 判定 merge commit：优先 isMerge 显式字段，缺省按 subject 启发式 */
+function isMergeCommit(commit: CommitInput): boolean {
+  return commit.isMerge ?? MERGE_SUBJECT_RE.test(commit.subject);
+}
+
+/** phase 格式验证 */
+export function verifyPhaseFormat(
+  commits: CommitInput[],
+  config: CompletionCheckersConfig = {},
+): PhaseFormatResult {
+  if (config.enabled === false || config.checkers?.phaseFormat === false) {
+    return { checker: 'phase-format', verdict: 'skip', commits: [] };
+  }
+
+  const verdicts: CommitVerdict[] = commits.map((commit) => {
+    if (isMergeCommit(commit)) {
+      return { sha: commit.sha, verdict: 'violation', reason: 'WU 提交集内出现 merge commit' };
+    }
+    if (!PHASE_SUBJECT_RE.test(commit.subject)) {
+      return { sha: commit.sha, verdict: 'violation', reason: `subject 不合规：${commit.subject}` };
+    }
+    return { sha: commit.sha, verdict: 'pass' };
+  });
+
+  return {
+    checker: 'phase-format',
+    verdict: verdicts.some((v) => v.verdict === 'violation') ? 'violation' : 'pass',
+    commits: verdicts,
+  };
+}

package/src/completion-checkers/tdd-chain.ts

@@ -0,0 +1,63 @@
+/**
+ * tdd-chain：实现 commit 的测试引用链验证（Q2/Q3 定稿）
+ *
+ * 协议（写死为机制本体，不进配置）：
+ * - 实现 commit 必须带 trailer `Tested-By: <sha>`
+ * - 被引 sha 须 a) 在本 WU 提交集内 b) 序列位置在本 commit 之前（比位置不比时间戳）c) 其文件清单命中 test_globs
+ * - 豁免：trailer `Tests: none` → waiver（放行记台账）；纯非代码/纯测试 commit 天然免检
+ */
+
+import type { CommitInput, CommitVerdict, CompletionCheckersConfig, TddChainResult } from './types';
+import { classifyCommitFiles, resolveGlobs } from './classify';
+
+/** Tested-By 引用协议（写死） */
+export const TESTED_BY_RE = /^Tested-By:\s*([0-9a-f]{7,40})\s*$/gim;
+
+/** Tests: none 豁免协议（写死） */
+export const TESTS_NONE_RE = /^Tests:\s*none\s*$/im;
+
+/** 引用链验证：伪造引用（不存在 / 位置在后 / 不含测试文件）一律记 violation */
+export function verifyTddChain(
+  commits: CommitInput[],
+  config: CompletionCheckersConfig = {},
+): TddChainResult {
+  if (config.enabled === false || config.checkers?.tddChain === false) {
+    return { checker: 'tdd-chain', verdict: 'skip', commits: [] };
+  }
+
+  const { testGlobs, noncodeGlobs } = resolveGlobs(config);
+  // 文件分类一次性算好，与同批 commit 的其他 checker 共享口径
+  const classifications = commits.map((c) => classifyCommitFiles(c, testGlobs, noncodeGlobs));
+
+  const verdicts: CommitVerdict[] = commits.map((commit, i) => {
+    if (classifications[i].exempt) {
+      return { sha: commit.sha, verdict: 'skip', reason: '纯测试/纯非代码 commit，天然免检' };
+    }
+    if (TESTS_NONE_RE.test(commit.body)) {
+      return { sha: commit.sha, verdict: 'waiver', reason: 'Tests: none 显式豁免' };
+    }
+    TESTED_BY_RE.lastIndex = 0;
+    const m = TESTED_BY_RE.exec(commit.body);
+    if (!m) {
+      return { sha: commit.sha, verdict: 'violation', reason: '缺 Tested-By trailer 且未声明 Tests: none' };
+    }
+    const ref = m[1].toLowerCase();
+    const j = commits.findIndex((c) => c.sha.toLowerCase().startsWith(ref));
+    if (j === -1) {
+      return { sha: commit.sha, verdict: 'violation', reason: `Tested-By 引用 ${ref} 不在本 WU 提交集内` };
+    }
+    if (j >= i) {
+      return { sha: commit.sha, verdict: 'violation', reason: `Tested-By 引用 ${ref} 位置不在本 commit 之前` };
+    }
+    if (!classifications[j].hasTests) {
+      return { sha: commit.sha, verdict: 'violation', reason: `被引 commit ${ref} 文件清单未命中 test_globs` };
+    }
+    return { sha: commit.sha, verdict: 'pass' };
+  });
+
+  return {
+    checker: 'tdd-chain',
+    verdict: verdicts.some((v) => v.verdict === 'violation') ? 'violation' : 'pass',
+    commits: verdicts,
+  };
+}