@dommaker/harness 1.2.3 → 1.4.0

package/src/test-setup/__tests__/project-fixture.test.ts

@@ -0,0 +1,178 @@
+/**
+ * project-fixture 构造 API 测试（架构评审 2026-09-02 候选11 / harness#90）
+ *
+ * 钉死三条契约：
+ * 1) 缺省根 = os.tmpdir()，`config` 槽位逐字节落 `.harness/config.yml`（不做 YAML 往返——
+ *    被检代码大量用例是畸形/脏配置，原样落盘是硬需求）；
+ * 2) 非缺省根必须经 parentDir **显式**声明（cwd 锚定用例的前置约束，不隐式继承默认根）；
+ * 3) 建出的根由 mkdtemp 劫持登记 = 用例结束自动清理，且 name 形状可被超龄兜底清扫识别。
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { createProjectFixture, writeProjectConfig, writeProjectTraces } from '../project-fixture';
+import { isRegisteredTmpDir } from '../mkdtemp-cleanup';
+import { DEFAULT_TRACE_FILE } from '../../types/trace';
+
+/** mkdtemp-cleanup.ts 的超龄清扫签名（name 不合规的夹具目录漏网后永不被扫） */
+const SWEEP_SIGNATURE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*-[A-Za-z0-9]{6}$/;
+
+describe('createProjectFixture — 根与 config 槽位', () => {
+  it('缺省根在 os.tmpdir()，config 逐字节落 .harness/config.yml', () => {
+    const root = createProjectFixture({ name: 'pfx-default', config: 'preset: standard\n' });
+
+    expect(path.dirname(root)).toBe(os.tmpdir());
+    expect(fs.readFileSync(path.join(root, '.harness', 'config.yml'), 'utf-8')).toBe('preset: standard\n');
+  });
+
+  it('省略 config → 不写 .harness/config.yml（存在性探测类用例依赖此语义）', () => {
+    const root = createProjectFixture({ name: 'pfx-no-config' });
+
+    expect(fs.existsSync(path.join(root, '.harness', 'config.yml'))).toBe(false);
+    expect(fs.existsSync(path.join(root, '.harness'))).toBe(false);
+  });
+
+  it('config 为空字符串仍算声明（falsy 不得退化为“不写”）', () => {
+    const root = createProjectFixture({ name: 'pfx-empty-config', config: '' });
+
+    expect(fs.readFileSync(path.join(root, '.harness', 'config.yml'), 'utf-8')).toBe('');
+  });
+
+  it('files 按相对路径落盘，父目录自动创建', () => {
+    const root = createProjectFixture({
+      name: 'pfx-files',
+      files: {
+        'src/core/foo.ts': 'export const x = 1;',
+        'src/CONTEXT.md': '# src\n',
+        '.harness/custom-constraints.yml': 'custom_constraints: {}\n',
+      },
+    });
+
+    expect(fs.readFileSync(path.join(root, 'src/core/foo.ts'), 'utf-8')).toBe('export const x = 1;');
+    expect(fs.readFileSync(path.join(root, 'src/CONTEXT.md'), 'utf-8')).toBe('# src\n');
+    // 通用槽位不得踩 config 正本路径：两者共存时各写各的
+    expect(fs.readFileSync(path.join(root, '.harness/custom-constraints.yml'), 'utf-8')).toBe(
+      'custom_constraints: {}\n'
+    );
+    expect(fs.existsSync(path.join(root, '.harness/config.yml'))).toBe(false);
+  });
+
+  it('config 与 files 同时声明 → 两侧都落盘', () => {
+    const root = createProjectFixture({
+      name: 'pfx-both',
+      config: 'preset: relaxed\n',
+      files: { 'CAPABILITIES.md': '# Capabilities\n' },
+    });
+
+    expect(fs.readFileSync(path.join(root, '.harness/config.yml'), 'utf-8')).toBe('preset: relaxed\n');
+    expect(fs.readFileSync(path.join(root, 'CAPABILITIES.md'), 'utf-8')).toBe('# Capabilities\n');
+  });
+});
+
+describe('createProjectFixture — 显式 opt-out 根', () => {
+  it('parentDir 声明的根落在该父目录下，而非缺省 tmpdir', () => {
+    const parent = createProjectFixture({ name: 'pfx-parent' });
+    const root = createProjectFixture({ name: 'pfx-child', parentDir: parent });
+
+    expect(path.dirname(root)).toBe(parent);
+    expect(root.startsWith(path.join(parent, 'pfx-child-'))).toBe(true);
+  });
+
+  it('parentDir: process.cwd() → 根落在仓库工作目录（cwd 锚定套件依赖的正是这条语义）', () => {
+    const root = createProjectFixture({ name: 'pfx-cwd-anchor', parentDir: process.cwd() });
+    try {
+      expect(path.dirname(root)).toBe(process.cwd());
+      expect(fs.existsSync(root)).toBe(true);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('opt-out 用例仍被 mkdtemp 劫持登记（自动清理不依赖调用方手动 rm）', () => {
+    const parent = createProjectFixture({ name: 'pfx-optout-parent' });
+    const root = createProjectFixture({ name: 'pfx-optout-child', parentDir: parent });
+
+    expect(isRegisteredTmpDir(root)).toBe(true);
+  });
+
+  it('缺省根同样登记，且目录名符合超龄清扫签名（漏网目录可被兜底扫掉）', () => {
+    const root = createProjectFixture({ name: 'pfx-sweepable' });
+
+    expect(isRegisteredTmpDir(root)).toBe(true);
+    expect(SWEEP_SIGNATURE.test(path.basename(root))).toBe(true);
+  });
+
+  it('name 形状不合规（大写/下划线/空）→ 抛错，不静默产出扫不掉的目录', () => {
+    expect(() => createProjectFixture({ name: 'Pfx-Bad' })).toThrow(/name/);
+    expect(() => createProjectFixture({ name: 'pfx_bad' })).toThrow(/name/);
+    expect(() => createProjectFixture({ name: '' })).toThrow(/name/);
+  });
+});
+
+describe('writeProjectConfig — config 落盘唯一正本', () => {
+  it('根下无 .harness 时自动建目录并写入', () => {
+    const root = createProjectFixture({ name: 'pfx-writer' });
+
+    writeProjectConfig(root, 'gates:\n  order:\n    - security\n');
+
+    expect(fs.readFileSync(path.join(root, '.harness', 'config.yml'), 'utf-8')).toBe(
+      'gates:\n  order:\n    - security\n'
+    );
+  });
+
+  it('已有 config 时覆盖写（用例内后续改配置不叠加旧内容）', () => {
+    const root = createProjectFixture({ name: 'pfx-rewrite', config: 'preset: standard\n' });
+
+    writeProjectConfig(root, 'preset: relaxed\n');
+
+    expect(fs.readFileSync(path.join(root, '.harness', 'config.yml'), 'utf-8')).toBe('preset: relaxed\n');
+  });
+});
+
+describe('traces 槽位 / writeProjectTraces — trace 落盘正本（harness#108）', () => {
+  it('traces 槽位逐条落 DEFAULT_TRACE_FILE，缺省字段补齐（level/timestamp/result）', () => {
+    const root = createProjectFixture({
+      name: 'pfx-traces',
+      traces: [{ constraintId: 'c1', result: 'fail' }],
+    });
+
+    const lines = fs.readFileSync(path.join(root, DEFAULT_TRACE_FILE), 'utf-8').trim().split('\n');
+    expect(lines).toHaveLength(1);
+    expect(JSON.parse(lines[0])).toEqual({
+      level: 'guideline',
+      timestamp: 1700000000000,
+      result: 'fail',
+      constraintId: 'c1',
+    });
+  });
+
+  it('traces 槽位缺省 → 不写 trace 文件（traceFileExists=false 用例依赖此语义）', () => {
+    const root = createProjectFixture({ name: 'pfx-no-traces' });
+
+    expect(fs.existsSync(path.join(root, DEFAULT_TRACE_FILE))).toBe(false);
+  });
+
+  it('writeProjectTraces 空数组仍落空文件（traceFileExists=true、零记录语义）', () => {
+    const root = createProjectFixture({ name: 'pfx-empty-traces' });
+
+    writeProjectTraces(root, []);
+
+    expect(fs.existsSync(path.join(root, DEFAULT_TRACE_FILE))).toBe(true);
+    expect(fs.readFileSync(path.join(root, DEFAULT_TRACE_FILE), 'utf-8')).toBe('');
+  });
+
+  it('writeProjectTraces 覆盖写：用例内重写不叠加旧记录', () => {
+    const root = createProjectFixture({
+      name: 'pfx-rewrite-traces',
+      traces: [{ constraintId: 'old' }],
+    });
+
+    writeProjectTraces(root, [{ constraintId: 'new' }]);
+
+    const lines = fs.readFileSync(path.join(root, DEFAULT_TRACE_FILE), 'utf-8').trim().split('\n');
+    expect(lines).toHaveLength(1);
+    expect(JSON.parse(lines[0]).constraintId).toBe('new');
+  });
+});

package/src/test-setup/project-fixture.ts

@@ -0,0 +1,87 @@
+/**
+ * 测试项目夹具构造 API（架构评审 2026-09-02 候选11 / harness#90）
+ *
+ * 职责：建一个临时项目根并按声明落 fixture，替掉散在各测试套件的
+ * `mkdtempSync + mkdir('.harness') + writeFileSync('config.yml')` 手写组合。
+ *
+ * 设计口径（triage 裁决）：
+ * - **语义声明**而非文件树声明：`config`/`traces` 是独立槽位（`.harness/config.yml`
+ *   与 `DEFAULT_TRACE_FILE` 的形状正本只有这里知道），其余文件走 `files` 相对路径。
+ *   constraints/knowledge 槽位随后续票补。
+ * - `config` 只收字符串、原样落盘：被检代码大量用例是畸形/脏配置（`governance: [`、
+ *   `required_dirs: [1, null]`、未知 preset 名），YAML 往返会把这些用例抹平。
+ * - 非缺省根必须经 `parentDir` **显式**声明：默认根统一为 tmpdir，
+ *   路径锚定生产代码的用例（cwd 锚定）靠 opt-out 保持原语义，不隐式继承。
+ * - 清理不在本模块做：根经 `fs.mkdtempSync` 创建，由 ./mkdtemp-cleanup 的劫持在
+ *   afterAll 统一回收（setupFilesAfterEnv 已全局装载）。
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { DEFAULT_TRACE_FILE, type ExecutionTrace } from '../types/trace';
+import { appendJsonl } from '../utils/jsonl';
+
+/** config.yml 相对项目根的落点（全仓唯一处，测试与生产读取口径在此对齐） */
+const CONFIG_REL = path.join('.harness', 'config.yml');
+
+/** name 只允许小写字母数字与连字符——见 mkdtemp-cleanup 的超龄清扫签名，大写/下划线会让漏网目录永不被扫 */
+const NAME_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+export interface ProjectFixtureDecl {
+  /** 用例标签，进入 mkdtemp 前缀（残留目录可定位到用例）；小写连字符 */
+  name: string;
+  /** `.harness/config.yml` 内容，原样落盘；省略 = 不写该文件（未采用约定语义） */
+  config?: string;
+  /**
+   * trace 槽位（harness#108）：落 `DEFAULT_TRACE_FILE` 的 JSONL 记录；
+   * 省略 = 不写该文件（traceFileExists=false 语义）。缺省字段补齐见 writeProjectTraces
+   */
+  traces?: Partial<ExecutionTrace>[];
+  /** 其余文件：相对路径 → 内容，父目录自动创建 */
+  files?: Record<string, string>;
+  /** 显式 opt-out：临时根的父目录，缺省 `os.tmpdir()`；cwd 锚定用例传 `process.cwd()` */
+  parentDir?: string;
+}
+
+/** 写入（或覆盖）项目根的 `.harness/config.yml`——用例内后续改配置走这里，不再手拼路径 */
+export function writeProjectConfig(projectRoot: string, content: string): void {
+  const target = path.join(projectRoot, CONFIG_REL);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, content, 'utf-8');
+}
+
+/**
+ * 写入（或覆盖）项目根的 trace 文件——路径锚定生产正本 DEFAULT_TRACE_FILE，
+ * 序列化走生产写链 appendJsonl（harness#108：测试不再手拼路径与 JSONL 形状，
+ * 生产端改格式时测试随之失真可见而非静默脱节）。
+ *
+ * 缺省字段补齐 level/timestamp/result（与原各套件 writeTraces 的口径一致），
+ * 调用方按需覆盖。覆盖语义：先清空再逐条 append；空数组仍落空文件
+ * （traceFileExists=true、零记录）。
+ */
+export function writeProjectTraces(projectRoot: string, traces: Partial<ExecutionTrace>[]): void {
+  const target = path.join(projectRoot, DEFAULT_TRACE_FILE);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, '', 'utf-8');
+  for (const t of traces) {
+    appendJsonl(target, { level: 'guideline', timestamp: 1700000000000, result: 'pass', ...t });
+  }
+}
+
+/** 建临时项目根并落声明式 fixture，返回根路径 */
+export function createProjectFixture(decl: ProjectFixtureDecl): string {
+  if (!NAME_RE.test(decl.name)) {
+    throw new Error(`project-fixture: name 必须是小写连字符标签（收到 "${decl.name}"），否则残留目录无法被超龄清扫识别`);
+  }
+  const parent = decl.parentDir ?? os.tmpdir();
+  const root = fs.mkdtempSync(path.join(parent, `${decl.name}-`));
+  if (decl.config !== undefined) writeProjectConfig(root, decl.config);
+  if (decl.traces !== undefined) writeProjectTraces(root, decl.traces);
+  for (const [rel, content] of Object.entries(decl.files ?? {})) {
+    const target = path.join(root, rel);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content, 'utf-8');
+  }
+  return root;
+}

package/src/tools/CONTEXT.md

@@ -13,6 +13,12 @@
 ## 约定
 - 工具定义目录路径由 paths 模块解析
 - `definitions/` 为静态能力目录，构建时复制到 dist
+- **yml 目录是正本、`registry.json` 是派生索引**（#91 裁决）：二者一致性由 `__tests__/registry.test.ts`
+  按 ADR-0009 的 reconcile 形状守（双向集合对照 + 条目 path 指向存在的 yml + `name` 与 yml 内 `name` 一致）。
+  新增能力 = 先落 yml，再补 registry 条目，缺一即测试红。**不做 yml schema 校验**——那等于替 studio 定能力契约。
+  `rollback` 重名 ×2（std/deploy 与 std/governance）是既有事实，进豁免名单；重名是否合法另票裁决。
+- `paths.ts` 单变方**不是**假 seam（#91 裁决）：它是包根公开导出（`src/index.ts`，由 public-exports 测试钉住），
+  实际消费方是 studio 外部仓，本仓内无第二调用方属预期形状，留任
 
 ## 注意事项
 - 旧工具注册表/核心工具/加载器/类型定义已随 H1（#40）删除，仅保留路径管理与能力目录

package/src/tools/__tests__/registry.test.ts

@@ -0,0 +1,221 @@
+/**
+ * tools 能力目录 registry 完整性测试（架构评审 2026-09-02 候选12 / harness#91）
+ *
+ * `src/tools/definitions/` 是随包发布的数据（package.json files 含 src），studio 经包根
+ * 公开导出消费（`getToolsDir` / `getRegistryPath`）——此前代码半边有 public-exports 钉住导出面，
+ * 数据半边零测试：幽灵项 / 漏登项 / path 悬空 / name 漂移都没人守。
+ * 这是 ADR-0002「注册型能力一律定义即注册 + 构建期闭环」唯一没覆盖的一类注册表。
+ *
+ * 裁决（#91 triage）：
+ * - **yml 目录是正本**，registry.json 是派生索引 → 对照方向 = 双向集合一致
+ * - **不做 yml schema 校验**（那等于替 studio 定能力契约，破坏面外溢到 studio）
+ * - `rollback` 重名 ×2（std/deploy 与 std/governance）是既有事实，进豁免名单；
+ *   重名本身是否合法另票裁决 → 名单外的任何新重名一律红
+ *
+ * 判定形状参照 ADR-0009 的 reconcile：读声明 → 对照文件系统 → 产出双向差异清单，
+ * 失败信息一次报全（不逐条断言到第一个错就停）。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { getRegistryPath, getToolsDir } from '../paths';
+import { walkFiles } from '../../utils/file-walk';
+import { createProjectFixture } from '../../test-setup/project-fixture';
+
+/** registry.json 条目（只取本测试关心的两字段，schema 校验是 out of scope） */
+interface RegistryEntry {
+  name: string;
+  path: string;
+}
+
+/** 一个 tools 定义目录的读取结果：派生索引声明 + 正本文件清单 + 正本内 name */
+interface DefinitionsSnapshot {
+  /** registry.json 声明的条目 */
+  entries: RegistryEntry[];
+  /** definitions/ 下实际存在的 yml（相对定义根，`/` 分隔） */
+  ymlPaths: string[];
+  /** yml 内 name（相对路径 → name；读不到/非字符串 → null） */
+  ymlNames: Record<string, string | null>;
+}
+
+/** 双向漂移清单（ADR-0009 形状：一次产出全部判定，消费方按需取用） */
+interface RegistryDrift {
+  /** 幽灵项：registry 登记了磁盘上不存在的 yml（含 path 悬空） */
+  ghostPaths: string[];
+  /** 漏登项：磁盘上的 yml 未被 registry 任何条目引用 */
+  unregisteredPaths: string[];
+  /** name 漂移：registry.name 与 yml 内 name 不一致（含 yml 缺 name） */
+  nameMismatches: string[];
+  /** 重名：同 name 被多条条目使用（排序） */
+  duplicateNames: string[];
+}
+
+/** 既有事实豁免：#91 裁决保留的重名，名单外新增即红 */
+const KNOWN_DUPLICATE_NAMES = ['rollback'];
+
+const EMPTY_DRIFT: RegistryDrift = {
+  ghostPaths: [],
+  unregisteredPaths: [],
+  nameMismatches: [],
+  duplicateNames: [],
+};
+
+/** 读一个定义目录：registry.json 声明 + yml 正本清单与其中的 name（相对路径统一 `/` 分隔） */
+function readDefinitions(definitionsDir: string): DefinitionsSnapshot {
+  const registry = JSON.parse(fs.readFileSync(path.join(definitionsDir, 'registry.json'), 'utf-8')) as {
+    tools: RegistryEntry[];
+  };
+  const ymlPaths = walkFiles(definitionsDir, { filter: name => name.endsWith('.yml') })
+    .map(full => path.relative(definitionsDir, full).split(path.sep).join('/'))
+    .sort();
+  const ymlNames: Record<string, string | null> = {};
+  for (const rel of ymlPaths) {
+    const doc = yaml.load(fs.readFileSync(path.join(definitionsDir, rel), 'utf-8')) as
+      | { name?: unknown }
+      | undefined;
+    ymlNames[rel] = typeof doc?.name === 'string' ? doc.name : null;
+  }
+  return { entries: registry.tools, ymlPaths, ymlNames };
+}
+
+/** 双向对照（纯判定，不做 IO——ADR-0009 同口径） */
+function reconcileRegistry(snapshot: DefinitionsSnapshot): RegistryDrift {
+  const ymlSet = new Set(snapshot.ymlPaths);
+  const declaredPaths = new Set<string>();
+  const seenNames = new Set<string>();
+  const duplicateNames = new Set<string>();
+  const ghostPaths: string[] = [];
+  const nameMismatches: string[] = [];
+
+  for (const entry of snapshot.entries) {
+    declaredPaths.add(entry.path);
+    if (!ymlSet.has(entry.path)) {
+      ghostPaths.push(entry.path);
+      continue; // 正本不存在，name 无从对照（幽灵项已含该条）
+    }
+    const ymlName = snapshot.ymlNames[entry.path];
+    if (ymlName !== entry.name) {
+      nameMismatches.push(
+        `${entry.path}: registry="${entry.name}" ${ymlName === null ? 'yml=<缺失>' : `yml="${ymlName}"`}`
+      );
+    }
+    if (seenNames.has(entry.name)) duplicateNames.add(entry.name);
+    seenNames.add(entry.name);
+  }
+
+  return {
+    ghostPaths: ghostPaths.sort(),
+    unregisteredPaths: snapshot.ymlPaths.filter(p => !declaredPaths.has(p)).sort(),
+    nameMismatches: nameMismatches.sort(),
+    duplicateNames: [...duplicateNames].sort(),
+  };
+}
+
+/** 临时定义根夹具（经 project-fixture 建根，afterAll 由 mkdtemp-cleanup 回收） */
+function makeDefinitionsFixture(
+  label: string,
+  tools: RegistryEntry[],
+  ymls: Record<string, string>
+): string {
+  const files: Record<string, string> = {
+    'definitions/registry.json': JSON.stringify({ tools }, null, 2),
+  };
+  for (const [rel, content] of Object.entries(ymls)) files[`definitions/${rel}`] = content;
+  return path.join(createProjectFixture({ name: `tools-registry-${label}`, files }), 'definitions');
+}
+
+const CLEAN_TOOLS: RegistryEntry[] = [
+  { name: 'code/parse', path: 'core/code/parse.yml' },
+  { name: 'deploy/rollback', path: 'std/deploy/rollback.yml' },
+];
+const CLEAN_YMLS = {
+  'core/code/parse.yml': 'name: code/parse\ndescription: parse\n',
+  'std/deploy/rollback.yml': 'name: deploy/rollback\ndescription: rollback\n',
+};
+
+describe('tools registry 完整性 — 判定形状（ADR-0009 reconcile）', () => {
+  it('干净夹具：双向零漂移（不误报）', () => {
+    const snapshot = readDefinitions(makeDefinitionsFixture('clean', CLEAN_TOOLS, CLEAN_YMLS));
+    expect(reconcileRegistry(snapshot)).toEqual(EMPTY_DRIFT);
+  });
+
+  it('幽灵项 / path 悬空：registry 登记磁盘不存在的 yml → 红（闭环失败方向 1）', () => {
+    const snapshot = readDefinitions(
+      makeDefinitionsFixture('ghost', [...CLEAN_TOOLS, { name: 'ghost/item', path: 'std/ghost/item.yml' }], CLEAN_YMLS)
+    );
+    expect(reconcileRegistry(snapshot).ghostPaths).toEqual(['std/ghost/item.yml']);
+  });
+
+  it('漏登项：yml 存在但 registry 未登记 → 红（闭环失败方向 2）', () => {
+    const snapshot = readDefinitions(
+      makeDefinitionsFixture(
+        'missing',
+        CLEAN_TOOLS,
+        { ...CLEAN_YMLS, 'std/unlisted/new-tool.yml': 'name: unlisted/new-tool\n' }
+      )
+    );
+    expect(reconcileRegistry(snapshot).unregisteredPaths).toEqual(['std/unlisted/new-tool.yml']);
+  });
+
+  it('name 漂移：registry.name 与 yml 内 name 不一致 → 红', () => {
+    const snapshot = readDefinitions(
+      makeDefinitionsFixture('name-drift', CLEAN_TOOLS, {
+        ...CLEAN_YMLS,
+        'core/code/parse.yml': 'name: code/renamed\ndescription: parse\n',
+      })
+    );
+    expect(reconcileRegistry(snapshot).nameMismatches).toEqual([
+      'core/code/parse.yml: registry="code/parse" yml="code/renamed"',
+    ]);
+  });
+
+  it('yml 缺 name 字段 → 计入 name 漂移（不做 schema 校验，但 name 是对照锚点）', () => {
+    const snapshot = readDefinitions(
+      makeDefinitionsFixture('name-absent', CLEAN_TOOLS, {
+        ...CLEAN_YMLS,
+        'core/code/parse.yml': 'description: parse\n',
+      })
+    );
+    expect(reconcileRegistry(snapshot).nameMismatches).toEqual([
+      'core/code/parse.yml: registry="code/parse" yml=<缺失>',
+    ]);
+  });
+
+  it('豁免名单外的新重名 → 红（rollback 重名合法性另票裁决，#91）', () => {
+    const snapshot = readDefinitions(
+      makeDefinitionsFixture(
+        'dup',
+        [...CLEAN_TOOLS, { name: 'deploy/rollback', path: 'std/governance/rollback.yml' }],
+        { ...CLEAN_YMLS, 'std/governance/rollback.yml': 'name: deploy/rollback\n' }
+      )
+    );
+    expect(reconcileRegistry(snapshot).duplicateNames).toEqual(['deploy/rollback']);
+  });
+});
+
+describe('tools registry 完整性 — 真实数据（definitions/ 随包发布）', () => {
+  const snapshot = readDefinitions(getToolsDir());
+
+  it('yml 正本与 registry 派生索引双向一致：无幽灵、无漏登、path 全部指向存在的 yml', () => {
+    const drift = reconcileRegistry(snapshot);
+    expect({ ...drift, duplicateNames: drift.duplicateNames.filter(n => !KNOWN_DUPLICATE_NAMES.includes(n)) })
+      .toEqual(EMPTY_DRIFT);
+  });
+
+  it('重名豁免名单钉死：当前唯一重名 = rollback ×2，名单变化即红', () => {
+    expect(reconcileRegistry(snapshot).duplicateNames).toEqual(KNOWN_DUPLICATE_NAMES);
+  });
+
+  it('src/tools/CONTEXT.md 声明的 yml 计数与实际一致', () => {
+    const contextSource = fs.readFileSync(path.join(getToolsDir(), '..', 'CONTEXT.md'), 'utf-8');
+    const declared = contextSource.match(/(\d+) 个 yml/);
+    expect(declared).not.toBeNull();
+    expect(Number(declared?.[1])).toBe(snapshot.ymlPaths.length);
+  });
+
+  it('包根公开导出的两个路径入口指向存在的 definitions/ 与 registry.json（studio 消费面）', () => {
+    expect(fs.existsSync(getToolsDir())).toBe(true);
+    expect(fs.existsSync(getRegistryPath())).toBe(true);
+  });
+});

package/src/types/__tests__/types.test.ts

@@ -1,14 +1,13 @@
 /**
- * src/types 模块导出覆盖测试
+ * src/types 类型层行为测试
  */
 
 import { describe, it, expect } from '@jest/globals';
 
-// 从 barrel index.ts 导入，覆盖 re-export 行
-import { ConstraintViolationError } from '..';
+import { ConstraintViolationError } from '../constraint';
 
-describe('types barrel exports', () => {
-  it('ConstraintViolationError 应该可从 index 导入', () => {
+describe('ConstraintViolationError 导出', () => {
+  it('ConstraintViolationError 应该可导入', () => {
     expect(ConstraintViolationError).toBeDefined();
     expect(typeof ConstraintViolationError).toBe('function');
   });

package/src/types/constraint.ts

@@ -177,39 +177,14 @@ export interface ConstraintContext {
   /** 是否已进行复用检查 */
   hasReuseCheck?: boolean;
   
-  /** 复用检查结果 */
-  reuseCheckResult?: {
-    existingCapabilities: string[];
-    canReuse: boolean;
-    reuseRecommendation: string;
-  };
-  
   /** 是否只处理单个任务（用于 incremental_progress） */
   hasSingleTask?: boolean;
   
-  /** 是否已验证外部能力（对应约束已降级为 prompt，字段保留兼容） */
-  hasExternalCapabilityVerification?: boolean;
-
-  /** 是否已对比需求验证（review 变体已并入主约束，字段保留兼容） */
-  hasRequirementReview?: boolean;
-
   /** 是否有需求文档（用于 no_implementation_without_requirement） */
   hasRequirement?: boolean;
 
-  /** 是否在 worktree 中执行（对应约束已移出内置，字段保留兼容） */
-  hasWorktree?: boolean;
-
   /** worktree 路径（用于 worktree 相关检查） */
   worktreePath?: string;
-
-  /** 完成声明文本（对应检查已并入 prompt 层，字段保留兼容） */
-  completionClaimText?: string;
-
-  /** 是否完成两阶段审查（对应约束已移出内置，字段保留兼容） */
-  hasTwoStageReview?: boolean;
-
-  /** 执行上下文 */
-  executionContext?: any;
 }
 
 /**

package/src/types/failure.ts

@@ -5,6 +5,14 @@
  * 不包含业务逻辑，只定义数据结构
  */
 
+/**
+ * 默认 failure 日志路径（相对项目根目录）
+ *
+ * 读写双方必须统一引用此常量（DEFAULT_TRACE_FILE 同款先例）；
+ * 自定义路径时向 FailureRecorder 传入自定 logFile
+ */
+export const DEFAULT_FAILURE_LOG_FILE = '.harness/logs/failures.log';
+
 /**
  * 错误类型枚举
  */

package/src/types/passes-gate.ts

@@ -9,13 +9,20 @@ export interface PassesGateConfig {
   /** 是否启用 */
   enabled?: boolean;
   
-  /** 测试命令 */
+  /**
+   * 测试命令。缺省时走 core/validators/passes-gate.ts 的 detectTestCommand 探测：
+   * test:ci → test（排除 echo 占位脚本）→ test:e2e → test:coverage → Python 标记 → go.mod；
+   * 探不到则 fail-closed（不再兜底 'npm test'）
+   */
   testCommand?: string;
   
   /** 是否需要证据 */
   requireEvidence?: boolean;
   
-  /** 是否允许部分通过 */
+  /**
+   * 是否允许部分通过：退出码为 0 时，输出里的失败信号不再否决判定。
+   * 不赦免非零退出码（判定依据收在 core/validators/test-output.ts 的 judgeTestRun，ADR-0014）
+   */
   allowPartialPass?: boolean;
   
   /** 最大重试次数 */
@@ -50,9 +57,6 @@ export interface TaskTestResult {
   /** 失败的测试列表 */
   failures?: string[];
   
-  /** 覆盖率 */
-  coverage?: number;
-  
   /** 证据路径 */
   evidence?: string;
 }
@@ -94,30 +98,6 @@ export interface DynamicTask {
   testResult?: TaskTestResult;
 }
 
-/**
- * PassesGate 扩展接口
- * 
- * 用于注册额外的测试类型（如 Puppeteer E2E）
- */
-export interface PassesGateExtension {
-  /** 扩展名称 */
-  name: string;
-  
-  /** 扩展描述 */
-  description?: string;
-  
-  /** 运行测试 */
-  run(workDir: string, task?: DynamicTask): Promise<TaskTestResult>;
-}
-
-/**
- * 扩展测试结果（包含类型标识）
- */
-export interface ExtensionTestResult extends TaskTestResult {
-  /** 测试类型（扩展名称） */
-  type?: string;
-}
-
 // ========================================
 // AS-006: 纯约束验证接口
 // ========================================
@@ -134,7 +114,7 @@ export interface TestResult {
   /** 测试命令（可选，用于记录） */
   command?: string;
 
-  /** 覆盖率（可选） */
+  /** 覆盖率（调用方自备数据，check() 不读它、只随 testResult 原样回显；harness 不取数不执法，ADR-0015） */
   coverage?: number;
 
   /** 证据路径（可选） */

package/src/types/project-config.ts

@@ -41,7 +41,7 @@ export interface CustomConstraintDefinition {
   enabled?: boolean;
 
   /**
-   * 退役元数据（#82 D6 统一落点）
+   * 退役元数据（studio#82 D6 统一落点）
    *
    * 存在即视为已退役：不进生效集、不注入 CLAUDE.md。恢复 = 删除该段。
    * 落点在 custom-constraints.yml 条目内（一处真相，不拆 config.yml 第二处）。