@dommaker/harness 1.3.0 → 1.5.0

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

@@ -108,7 +108,16 @@ export interface ConstraintResult {
   
   /** 消息 */
   message?: string;
-  
+
+  /**
+   * 证据行（harness#119）
+   *
+   * checker 经 CheckDetail 返回的具体判定依据（如未登记的文件路径）。
+   * 违规时随 message 一并展示；满足但非空时为「提示」（不进 pass/fail 统计）。
+   * skip 恒为空——未评估不得留下证据行。
+   */
+  evidence?: string[];
+
   /** 建议操作 */
   requiredAction?: string;
   
@@ -177,39 +186,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;
 }
 
 /**
@@ -219,7 +203,12 @@ export class ConstraintViolationError extends Error {
   public readonly result: ConstraintResult;
 
   constructor(result: ConstraintResult) {
-    super(result.message || 'Constraint violation');
+    // 铁律违规在 checkConstraints 处直接 throw，CLI 的结构化输出块走不到这里，
+    // error.message 是判定证据唯一的外溢面（harness#119）
+    const detail = result.evidence?.length
+      ? `：\n${result.evidence.map((line) => `  - ${line}`).join('\n')}`
+      : '';
+    super(`${result.message || 'Constraint violation'}${detail}`);
     this.name = 'ConstraintViolationError';
     this.result = result;
   }

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 第二处）。

package/src/types/session.ts

@@ -81,9 +81,10 @@ export interface TaskListJson {
 }
 
 /**
- * 动态任务定义
+ * 动态任务定义（模块内类型：包根同名导出是 types/passes-gate 版，此处仅
+ * TaskListJson/SessionInfo 结构引用；原 Extended* 别名导出已随 #85 删除）
  */
-export interface DynamicTask {
+interface DynamicTask {
   id: string;
   name?: string;
   category?: string;
@@ -101,14 +102,13 @@ export interface DynamicTask {
 }
 
 /**
- * 测试结果
+ * 测试结果（模块内类型，理由同 DynamicTask）
  */
-export interface TaskTestResult {
+interface TaskTestResult {
   passed: boolean;
   command: string;
   output?: string;
   failures?: string[];
-  coverage?: number;
   timestamp: Date;
   evidence?: string;
 }

package/src/types/trace.ts

@@ -19,6 +19,8 @@ export const DEFAULT_TRACE_FILE = '.harness/logs/traces.log';
  * - 只记录核心字段（零 Token）
  * - 不记录代码片段（需要时从 git diff 获取）
  * - 不记录决策路径（需要时从 execution logs 获取）
+ * - 例外（harness#119）：判定证据允许记录——路径级依据不是代码片段，
+ *   而没有它，一条恒红的约束在统计侧根本无法回答「红在哪」
  */
 export interface ExecutionTrace {
   // ========================================
@@ -53,6 +55,14 @@ export interface ExecutionTrace {
   /** 会话 ID（用于追踪同一会话的多次检查） */
   sessionId?: string;
 
+  /**
+   * 判定证据行（harness#119）
+   *
+   * 只落 checker 给出的路径级依据（如未登记文件清单），由 checker 截断条数；
+   * 不落 pass 结果的空数组，避免无信息记录膨胀 JSONL。
+   */
+  evidence?: string[];
+
   // ========================================
   // 用户响应（可选，用于诊断）
   // ========================================

package/src/utils/__tests__/frontmatter.test.ts

@@ -0,0 +1,206 @@
+/**
+ * markdown frontmatter 解析/序列化正本测试（harness#89，架构评审 2026-09-02 候选10）
+ *
+ * 三种畸形输入（缺 frontmatter / 未闭合 / 空 meta）与 YAML 非法的走法在本文件显式固定，
+ * 各消费方（store / migration / knowledge index / sdd index / ingest）只允许复用这套判定。
+ */
+
+import { splitFrontmatter, joinFrontmatter } from '../frontmatter';
+
+describe('splitFrontmatter — 合法 frontmatter 块', () => {
+  it('解析 meta + body：与 store/migration 既有写盘格式（---\\n<yaml>---\\n\\n<body>）互认', () => {
+    const raw = '---\nid: DEC-001\ntype: decision\n---\n\nBody line\n';
+    const result = splitFrontmatter(raw);
+    expect(result.state).toBe('ok');
+    if (result.state !== 'ok') return;
+    expect(result.meta).toEqual({ id: 'DEC-001', type: 'decision' });
+    expect(result.body).toBe('Body line\n');
+  });
+
+  it('闭合行之后无空行时正文原样保留', () => {
+    const result = splitFrontmatter('---\na: 1\n---\nBody\n');
+    expect(result.state).toBe('ok');
+    if (result.state !== 'ok') return;
+    expect(result.body).toBe('Body\n');
+  });
+
+  it('只吃闭合后的一个空行（与 join 的 `---\\n\\n` 包裹严格对称）', () => {
+    const result = splitFrontmatter('---\na: 1\n---\n\n\nBody\n');
+    expect(result.state).toBe('ok');
+    if (result.state !== 'ok') return;
+    expect(result.body).toBe('\nBody\n');
+  });
+
+  it('闭合行即文件末尾（无尾随换行）→ body 为空串，仍是合法块', () => {
+    const result = splitFrontmatter('---\na: 1\n---');
+    expect(result.state).toBe('ok');
+    if (result.state !== 'ok') return;
+    expect(result.meta).toEqual({ a: 1 });
+    expect(result.body).toBe('');
+  });
+
+  it('正文中的 --- 分隔线不被误吞：闭合取第一个独立 --- 行', () => {
+    const result = splitFrontmatter('---\na: 1\n---\n\nx\n\n---\n\ny\n');
+    expect(result.state).toBe('ok');
+    if (result.state !== 'ok') return;
+    expect(result.meta).toEqual({ a: 1 });
+    expect(result.body).toBe('x\n\n---\n\ny\n');
+  });
+
+  it('meta 内缩进的 --- 是块标量内容，不算闭合行', () => {
+    const result = splitFrontmatter('---\nnote: |\n  ---\nb: 2\n---\nBody\n');
+    expect(result.state).toBe('ok');
+    if (result.state !== 'ok') return;
+    expect(result.meta).toEqual({ note: '---\n', b: 2 });
+    expect(result.body).toBe('Body\n');
+  });
+
+  it('闭合必须是整行：--- 后带内容的行（含 ---- 长分隔线）不作闭合', () => {
+    const result = splitFrontmatter('---\na: 1\n---broken\n----\nBody\n');
+    expect(result.state).toBe('malformed');
+    if (result.state !== 'malformed') return;
+    expect(result.reason).toBe('unterminated');
+  });
+});
+
+describe('splitFrontmatter — 三种畸形输入 + YAML 非法（一处定义）', () => {
+  it('缺 frontmatter：首行不是 --- → absent', () => {
+    expect(splitFrontmatter('# Title\n\nBody\n')).toEqual({ state: 'absent' });
+  });
+
+  it('缺 frontmatter：首行 --- 之前还有空白 → absent（起点必须在偏移 0）', () => {
+    expect(splitFrontmatter('\n---\na: 1\n---\nBody\n')).toEqual({ state: 'absent' });
+  });
+
+  it('空 meta：零宽元数据块 → absent（不承载信息，与收口前 store 丢条目的走法一致）', () => {
+    expect(splitFrontmatter('---\n---\n\nBody\n')).toEqual({ state: 'absent' });
+  });
+
+  it('空 meta：仅空白行 → absent', () => {
+    expect(splitFrontmatter('---\n\n \n---\nBody\n')).toEqual({ state: 'absent' });
+  });
+
+  it('未闭合：有开无闭 → malformed/unterminated', () => {
+    const result = splitFrontmatter('---\nid: X\ntitle: Y\n');
+    expect(result.state).toBe('malformed');
+    if (result.state !== 'malformed') return;
+    expect(result.reason).toBe('unterminated');
+    expect(result.detail).toContain('---');
+  });
+
+  it('YAML 语法错误 → malformed/invalid-yaml，detail 可定位', () => {
+    const result = splitFrontmatter('---\na: [1,\n---\nBody\n');
+    expect(result.state).toBe('malformed');
+    if (result.state !== 'malformed') return;
+    expect(result.reason).toBe('invalid-yaml');
+    expect(result.detail.length).toBeGreaterThan(0);
+    expect(result.detail).not.toContain('\n');
+  });
+
+  it('meta 是标量而非 mapping → malformed/invalid-yaml（消费方禁止再写 meta.id 式钻取）', () => {
+    const result = splitFrontmatter('---\njust a string\n---\nBody\n');
+    expect(result.state).toBe('malformed');
+    if (result.state !== 'malformed') return;
+    expect(result.reason).toBe('invalid-yaml');
+  });
+
+  it('meta 是数组 → malformed/invalid-yaml', () => {
+    const result = splitFrontmatter('---\n- a\n- b\n---\nBody\n');
+    expect(result.state).toBe('malformed');
+    if (result.state !== 'malformed') return;
+    expect(result.reason).toBe('invalid-yaml');
+  });
+
+  it('meta 是显式 null（`~`）→ malformed/invalid-yaml（与空白 meta 的 absent 区分）', () => {
+    const result = splitFrontmatter('---\n~\n---\nBody\n');
+    expect(result.state).toBe('malformed');
+    if (result.state !== 'malformed') return;
+    expect(result.reason).toBe('invalid-yaml');
+  });
+
+  it('CRLF 文件不按 frontmatter 处理 → absent（与收口前各消费方一致，不新增解释）', () => {
+    expect(splitFrontmatter('---\r\na: 1\r\n---\r\nBody\r\n')).toEqual({ state: 'absent' });
+  });
+});
+
+describe('joinFrontmatter', () => {
+  it('包裹格式与收口前逐字一致：`---\\n` + yaml.dump + `---\\n\\n` + body', () => {
+    expect(joinFrontmatter({ id: 'X' }, 'Body\n')).toBe('---\nid: X\n---\n\nBody\n');
+  });
+
+  it('空 body 也保留闭合后的空行分隔', () => {
+    expect(joinFrontmatter({ a: 1 }, '')).toBe('---\na: 1\n---\n\n');
+  });
+
+  it('按传入对象的键序落盘：排序策略留在消费方（裁决：收格式不收字段排序）', () => {
+    expect(joinFrontmatter({ b: 1, a: 2 }, '')).toBe('---\nb: 1\na: 2\n---\n\n');
+  });
+
+  it('dump 用 lineWidth 120：100 字符标量不折行（非 js-yaml 缺省 80）', () => {
+    const joined = joinFrontmatter({ title: 'a'.repeat(100) }, '');
+    expect(joined.split('\n')[1]).toBe(`title: ${'a'.repeat(100)}`);
+  });
+
+  it('dump 用 lineWidth 120：200 字符标量按 120 折行（非不折行）', () => {
+    const joined = joinFrontmatter({ title: 'a'.repeat(200) }, '');
+    expect(joined).toContain('title: >-\n');
+  });
+});
+
+describe('join ↔ split 往返闭环（已落盘条目不产生 diff 噪声）', () => {
+  const realisticMeta = {
+    id: 'PIT-001',
+    type: 'pitfall',
+    title: '端口不匹配: 3001 -> "API" 的三种走法',
+    maturity: 'verified',
+    layer: 'system',
+    created: '2026-05-28T00:00:00.000Z',
+    lastReferenced: '',
+    contributors: ['agent'],
+    projects: [],
+    tags: ['port', 'events'],
+    applicablePhases: ['IMPLEMENT'],
+    sourceReferences: [{ workflow: 'wf', timestamp: '2026-05-28T00:00:00.000Z' }],
+    referencedBy: [],
+    executionResults: [],
+    consumptionMode: 'reference',
+    origin: 'agent',
+  };
+
+  function roundTripIsStable(body: string): void {
+    const first = joinFrontmatter(realisticMeta, body);
+    const parsed = splitFrontmatter(first);
+    expect(parsed.state).toBe('ok');
+    if (parsed.state !== 'ok') return;
+    expect(parsed.meta).toEqual(realisticMeta);
+    expect(parsed.body).toBe(body);
+    expect(joinFrontmatter(parsed.meta, parsed.body)).toBe(first);
+  }
+
+  it('真实条目 meta + 正文：join → split → join 字节稳定', () => {
+    roundTripIsStable('根因：端口不一致。\n\n## 处置\n显式指定 API_PORT\n');
+  });
+
+  it('空正文稳定', () => {
+    roundTripIsStable('');
+  });
+
+  it('正文首行即 --- 分隔线时稳定（不误吞、不重复包裹）', () => {
+    roundTripIsStable('---\n\n附录\n');
+  });
+
+  it('正文含超长行时稳定', () => {
+    roundTripIsStable(`${'x'.repeat(300)}\n`);
+  });
+
+  it('meta 含被 120 折行的长标量时往返仍字节稳定（load→save 无 diff 噪声）', () => {
+    const meta = { ...realisticMeta, title: Array.from({ length: 40 }, (_, i) => `word${i}`).join(' ') };
+    const first = joinFrontmatter(meta, 'Body\n');
+    expect(first).toContain('title: >-\n');
+    const parsed = splitFrontmatter(first);
+    expect(parsed.state).toBe('ok');
+    if (parsed.state !== 'ok') return;
+    expect(parsed.meta).toEqual(meta);
+    expect(joinFrontmatter(parsed.meta, parsed.body)).toBe(first);
+  });
+});