@dommaker/harness 1.6.0 → 1.8.0

package/src/cli/commands/__tests__/command.test.ts

@@ -6,12 +6,12 @@
  */
 
 import { executeCommand } from '../command';
-import { createCommandGate, getCommandRiskLevel } from '../../../gates';
+import { createCommandGate } from '../../../gates';
 import { captureIO, type CapturingIO } from '../../command-contract';
+import { decide, fakeGate } from './gate-decision';
 
 jest.mock('../../../gates', () => ({
   createCommandGate: jest.fn(),
-  getCommandRiskLevel: jest.fn(),
   DEFAULT_COMMAND_BLACKLIST: [
     { id: 'rule-1', level: 'block', message: 'No rm -rf', category: 'destructive', pattern: 'rm -rf' },
     { id: 'rule-2', level: 'warn', message: 'No DROP TABLE', category: 'database', pattern: 'DROP TABLE' },
@@ -27,10 +27,21 @@ jest.mock('chalk', () => ({
 }));
 
 const mockCreateGate = createCommandGate as jest.MockedFunction<typeof createCommandGate>;
-const mockGetRisk = getCommandRiskLevel as jest.MockedFunction<typeof getCommandRiskLevel>;
 
-function mockGate(check: jest.Mock): void {
-  mockCreateGate.mockReturnValue({ check } as any);
+/**
+ * 替身工厂：命令穿过统一接口，替身产决策而非裸报告。
+ * `--level` 与默认分支共用这一台实例（#135），故等级也从替身上取。
+ */
+function mockGate(
+  report: { passed: boolean; message: string; details?: Record<string, any> },
+  level: 'high' | 'medium' | 'low' = 'low',
+): { evaluate: jest.Mock; getRiskLevel: jest.Mock } {
+  const gate = {
+    ...fakeGate(decide('command', report.passed, report.message, report.details)),
+    getRiskLevel: jest.fn().mockReturnValue(level),
+  };
+  mockCreateGate.mockReturnValue(gate as any);
+  return gate;
 }
 
 /** 从捕获输出里取第一条可解析为该形状的 JSON 行 */
@@ -86,7 +97,7 @@ describe('command command', () => {
 
   describe('default mode', () => {
     it('放行：ok，打印 ✓', async () => {
-      mockGate(jest.fn().mockResolvedValue({ passed: true, message: 'OK' }));
+      mockGate({ passed: true, message: 'OK' });
 
       const result = await executeCommand('safe-cmd', {}, io);
 
@@ -95,7 +106,7 @@ describe('command command', () => {
     });
 
     it('拒绝：fail + 裁决原因，打印 ✗', async () => {
-      mockGate(jest.fn().mockResolvedValue({ passed: false, message: 'Blocked' }));
+      mockGate({ passed: false, message: 'Blocked' });
 
       const result = await executeCommand('rm -rf /', {}, io);
 
@@ -104,7 +115,7 @@ describe('command command', () => {
     });
 
     it('--json 输出裁决详情', async () => {
-      mockGate(jest.fn().mockResolvedValue({ passed: true, message: 'OK', details: {} }));
+      mockGate({ passed: true, message: 'OK', details: {} });
 
       await executeCommand('cmd', { json: true }, io);
 
@@ -119,8 +130,7 @@ describe('command command', () => {
 
   describe('--level', () => {
     it('low：ok，打印等级', async () => {
-      mockGetRisk.mockReturnValue('low');
-      mockGate(jest.fn().mockResolvedValue({ passed: true, message: 'OK' }));
+      mockGate({ passed: true, message: 'OK' }, 'low');
 
       const result = await executeCommand('safe-cmd', { level: true }, io);
 
@@ -129,8 +139,7 @@ describe('command command', () => {
     });
 
     it('high：fail + 等级原因（严重级条件式译成 kind）', async () => {
-      mockGetRisk.mockReturnValue('high');
-      mockGate(jest.fn().mockResolvedValue({ passed: true, message: 'OK' }));
+      mockGate({ passed: true, message: 'OK' }, 'high');
 
       const result = await executeCommand('rm -rf /', { level: true }, io);
 
@@ -138,9 +147,7 @@ describe('command command', () => {
     });
 
     it('high 等级不再执行黑名单裁决分支', async () => {
-      const mockCheck = jest.fn().mockResolvedValue({ passed: true, message: 'OK' });
-      mockGetRisk.mockReturnValue('high');
-      mockGate(mockCheck);
+      mockGate({ passed: true, message: 'OK' }, 'high');
 
       const result = await executeCommand('rm -rf /', { level: true }, io);
 
@@ -150,8 +157,7 @@ describe('command command', () => {
     });
 
     it('--json 输出等级', async () => {
-      mockGetRisk.mockReturnValue('medium');
-      mockGate(jest.fn().mockResolvedValue({ passed: true, message: 'OK' }));
+      mockGate({ passed: true, message: 'OK' }, 'medium');
 
       await executeCommand('cmd', { level: true, json: true }, io);
 
@@ -160,5 +166,15 @@ describe('command command', () => {
         command: 'cmd',
       });
     });
+
+    it('#135：等级取自本命令创建的那台实例，全程只创建一次', async () => {
+      const gate = mockGate({ passed: false, message: 'Blocked' }, 'high');
+
+      const result = await executeCommand('danger-cmd', { level: true }, io);
+
+      expect(gate.getRiskLevel).toHaveBeenCalledWith('danger-cmd');
+      expect(mockCreateGate).toHaveBeenCalledTimes(1);
+      expect(result).toEqual({ kind: 'fail', reason: expect.stringContaining('risk level is high') });
+    });
   });
 });

package/src/cli/commands/__tests__/constraints-retire.test.ts

@@ -313,6 +313,58 @@ describe('retireConstraint 执行逻辑', () => {
   });
 });
 
+describe('落盘字节与装载次数冻结（harness#137）', () => {
+  /**
+   * YAML 读-改-写两段合并成 `setYamlEntry` 属内部重构：对外产物逐字不得漂移
+   * （票验收 6）。故此处钉的是**字节**而非 yaml.load 后的对象——键序、缩进、
+   * 行宽 120 的折叠口径、注释丢弃后的形态都在断言范围内。
+   */
+  it('内置退役落 config.yml：逐字节冻结', () => {
+    const root = createProjectFixture({
+      name: 'harness-retire-test',
+      config: '# 项目配置\npreset: standard\nscenes:\n  - llm-app\n',
+    });
+
+    retireConstraint(root, 'capability_sync', { reason: '逐字节冻结', now: FIXED_NOW });
+
+    expect(fs.readFileSync(path.join(root, '.harness', 'config.yml'), 'utf-8')).toBe(
+      'preset: standard\nscenes:\n  - llm-app\nconstraints:\n  capability_sync:\n    enabled: false\n' +
+        "    retired:\n      at: '2026-08-08T12:00:00.000Z'\n      reason: 逐字节冻结\n" +
+        '      stats:\n        total: 0\n        fail: 0\n        failRate: 0\n'
+    );
+  });
+
+  it('custom 退役落 custom-constraints.yml：逐字节冻结（规则原文保留、retired 段追加在末尾）', () => {
+    const root = createProjectFixture({ name: 'harness-retire-test' });
+    writeCustom(root, `# 自定义约束\n${CUSTOM_YML}`);
+
+    retireConstraint(root, 'my_custom_rule', { reason: '逐字节冻结', now: FIXED_NOW });
+
+    expect(fs.readFileSync(path.join(root, '.harness', 'custom-constraints.yml'), 'utf-8')).toBe(
+      'custom_constraints:\n  my_custom_rule:\n    level: iron_law\n    rule: 禁止引入 X\n' +
+        '    message: X 已由平台能力替代\n    promptInjection: 禁止引入 X\n' +
+        "    retired:\n      at: '2026-08-08T12:00:00.000Z'\n      reason: 逐字节冻结\n" +
+        '      stats:\n        total: 0\n        fail: 0\n        failRate: 0\n'
+    );
+  });
+
+  it('一次 retireConstraint 只装载一次项目配置（此前 custom 路径走 3 次 load）', async () => {
+    const { ProjectConfigLoader } = await import('../../../core/project-config-loader');
+    const loadSpy = jest.spyOn(ProjectConfigLoader.prototype, 'load');
+    const root = createProjectFixture({ name: 'harness-retire-test' });
+    writeCustom(root, CUSTOM_YML);
+    loadSpy.mockClear();
+
+    retireConstraint(root, 'my_custom_rule', { now: FIXED_NOW });
+    expect(loadSpy).toHaveBeenCalledTimes(1);
+
+    loadSpy.mockClear();
+    retireConstraint(root, 'my_custom_rule', { now: new Date('2026-08-09T00:00:00.000Z') });
+    expect(loadSpy).toHaveBeenCalledTimes(1);
+    loadSpy.mockRestore();
+  });
+});
+
 describe('constraintsRetire 非交互直达', () => {
   it('无 --yes 直达：报错 + 非零退出码 + 不落盘任何文件（#24 人确认闸门）', async () => {
     const root = createProjectFixture({ name: 'harness-retire-test' });

package/src/cli/commands/__tests__/context-syncer.test.ts

@@ -0,0 +1,141 @@
+/**
+ * sync-docs 的 CONTEXT.md 落点测试（harness#150）
+ *
+ * #132 把 init/validate 的脚手架三态收进 scaffold 模块，但 sync-docs 的
+ * `createContextMd` 是票口径外的第 9 处同形写手：自带一份 CONTEXT.md 模板正文，
+ * 与正本 `renderContextDoc` 已漂移。本票把它改消费正本（contextDocFile + runPlan）。
+ *
+ * 这里零真实文件系统（注入内存 fs 替身，手法照 scaffold.test.ts）钉三件事：
+ * 1. 对撞：同一目录经 init（contextDocFile）与 sync-docs（createContextMd）生成的
+ *    CONTEXT.md 骨架逐字相同（两条路径归一到单一正本）。
+ * 2. 正本文案：并入副本独有的两行引导、四节占位取 HTML 注释形。
+ * 3. 只在缺失时写：present → exists 分支不覆盖，正常 contextMissing 只走 created。
+ */
+
+import * as path from 'path';
+import chalk from 'chalk';
+import { captureIO, type CapturingIO } from '../../command-contract';
+import { contextDocFile, type ScaffoldFileSystem } from '../scaffold';
+import { createContextMd } from '../sync-docs/context-syncer';
+
+jest.mock('chalk', () => ({
+  blue: jest.fn((s: string) => s),
+  yellow: jest.fn((s: string) => s),
+  green: jest.fn((s: string) => s),
+  gray: jest.fn((s: string) => s),
+  red: jest.fn((s: string) => s),
+  cyan: jest.fn((s: string) => s),
+  bold: jest.fn((s: string) => s),
+}));
+
+/** 内存 fs 替身：写盘内容、建过的目录可断言 */
+class MemoryFs implements ScaffoldFileSystem {
+  readonly files = new Map<string, string>();
+  readonly dirs: string[] = [];
+
+  seed(target: string, content: string): void {
+    this.files.set(target, content);
+  }
+  async exists(target: string): Promise<boolean> {
+    return this.files.has(target);
+  }
+  async mkdir(dir: string): Promise<void> {
+    this.dirs.push(dir);
+  }
+  async writeFile(target: string, content: string): Promise<void> {
+    this.files.set(target, content);
+  }
+  async chmod(): Promise<void> {
+    /* CONTEXT.md 无权限位 */
+  }
+}
+
+const PROJECT = '/srv/project';
+const USER_CONTENT = '# src\n\n我自己写的，不许覆盖\n';
+
+/**
+ * CONTEXT.md 骨架正文的冻结字面量（harness#158）：正本 `renderContextDoc('src')` 被改必红。
+ * 上面的对撞闸只证明「init 与 sync-docs 同源」——两侧一起漂它看不见（复审 M3：给正本
+ * 加一行 → 60/60 全绿）。骨架正文整体由此处逐字钉住，改骨架必须显式改这份字面量。
+ */
+const CONTEXT_MD_SKELETON = `# src
+
+> 此文件描述 src 目录的职责和上下文
+> 请阅读本目录的源代码，然后填写以下各节。
+> 如果使用 AI 编码助手，将本文件内容作为 prompt 请求它分析并填写。
+
+## 职责
+
+<!-- 本目录的核心职责是什么 -->
+
+## 核心导出
+
+<!-- 本目录对外暴露的主要模块/函数 -->
+
+## 依赖关系
+
+<!-- 本目录依赖哪些其他模块，谁依赖本目录 -->
+
+## 注意事项
+
+<!-- 开发时需要注意的约束或约定 -->
+`;
+
+let fs: MemoryFs;
+let io: CapturingIO;
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  fs = new MemoryFs();
+  io = captureIO();
+});
+
+describe('createContextMd 消费 scaffold 正本（harness#150）', () => {
+  it('对撞：sync-docs 落点与 init 站点生成的骨架逐字相同', async () => {
+    await expect(createContextMd(PROJECT, 'src', io, fs)).resolves.toBe('created');
+    const written = fs.files.get(path.join(PROJECT, 'src', 'CONTEXT.md'));
+
+    // init 侧经由同一个 contextDocFile 工厂落盘（见 init.ts 的 contextDocPlan）——
+    // 两侧共用单一正本，任何一份偷偷漂移都会在这里撞红
+    expect(written).toBe(contextDocFile(PROJECT, 'src').content);
+  });
+
+  it('骨架正文逐字冻结：正本 renderContextDoc 被改必红（#158，M3 假闸补钉）', () => {
+    expect(contextDocFile(PROJECT, 'src').content).toBe(CONTEXT_MD_SKELETON);
+  });
+
+  it('正本文案钉住：并入的两行引导 + 注释形占位（散文式提问已消失）', async () => {
+    const content = contextDocFile(PROJECT, 'src').content;
+
+    expect(content).toContain('> 请阅读本目录的源代码，然后填写以下各节。');
+    expect(content).toContain(
+      '> 如果使用 AI 编码助手，将本文件内容作为 prompt 请求它分析并填写。',
+    );
+    expect(content).toContain('<!-- 本目录的核心职责是什么 -->');
+    expect(content).not.toContain('本目录的核心职责是？');
+  });
+
+  it('缺失才写：present → exists 分支，用户内容一字节不动', async () => {
+    const target = path.join(PROJECT, 'src', 'CONTEXT.md');
+    fs.seed(target, USER_CONTENT);
+
+    await expect(createContextMd(PROJECT, 'src', io, fs)).resolves.toBe('exists');
+
+    expect(fs.files.get(target)).toBe(USER_CONTENT);
+    expect(fs.dirs).toEqual([]);
+    expect(printed(io)).toEqual(['src/CONTEXT.md 已存在']);
+    expect(chalk.gray).toHaveBeenCalledWith('src/CONTEXT.md 已存在');
+  });
+
+  it('created 态：绿字文案由 runPlan 打印，与 init 落盘态同源', async () => {
+    await createContextMd(PROJECT, 'src', io, fs);
+
+    expect(printed(io)).toEqual(['✅ 已创建 src/CONTEXT.md']);
+    expect(chalk.green).toHaveBeenCalledWith('✅ 已创建 src/CONTEXT.md');
+  });
+});
+
+/** stdout 每次写入的文本（去掉 log 补的换行） */
+function printed(capture: CapturingIO): string[] {
+  return capture.outRecords().map(chunk => chunk.replace(/\n$/, ''));
+}

package/src/cli/commands/__tests__/contract.test.ts

@@ -4,6 +4,7 @@
 
 import { contract, validateSchema } from '../contract';
 import { captureIO, type CapturingIO } from '../../command-contract';
+import { decide, fakeGate, throwingGate } from './gate-decision';
 import * as fs from 'fs/promises';
 import { ContractGate } from '../../../gates/contract';
 
@@ -14,7 +15,7 @@ jest.mock('fs/promises', () => ({
 
 jest.mock('../../../gates/contract', () => ({
   ContractGate: jest.fn().mockImplementation(() => ({
-    check: jest.fn(),
+    evaluate: jest.fn(),
   })),
 }));
 
@@ -46,16 +47,15 @@ describe('contract command', () => {
   describe('contract', () => {
     it('should print success when check passes', async () => {
       mockFs.access.mockResolvedValue(undefined);
-      const mockCheck = jest.fn().mockResolvedValue({
-        passed: true,
-        message: 'ok',
-        details: { endpoints: 10, breakingChanges: false },
-      });
-      MockGate.mockImplementation(() => ({ check: mockCheck }) as any);
+      MockGate.mockImplementation(() =>
+        fakeGate(decide('contract', true, 'ok', { endpoints: 10, breakingChanges: false })) as any
+      );
 
       const result = await contract({}, io);
 
       expect(io.outText()).toContain('契约门控检查通过');
+      expect(io.outText()).toContain('   端点数: 10');
+      expect(io.outText()).toContain('   破坏性变更: 无');
       expect(result.kind).toBe('ok');
     });
 
@@ -70,31 +70,31 @@ describe('contract command', () => {
 
     it('should print failure and exit 1 when check fails', async () => {
       mockFs.access.mockResolvedValue(undefined);
-      const mockCheck = jest.fn().mockResolvedValue({
-        passed: false,
-        message: 'validation errors',
-        details: {
-          errors: ['missing field X', 'invalid type Y'],
-          breakingChanges: [{ type: 'removed', path: '/api/v1/users' }],
-        },
-      });
-      MockGate.mockImplementation(() => ({ check: mockCheck }) as any);
+      MockGate.mockImplementation(() =>
+        fakeGate(
+          decide('contract', false, 'validation errors', {
+            errors: ['missing field X', 'invalid type Y'],
+            breakingChanges: [{ type: 'removed', path: '/api/v1/users' }],
+          })
+        ) as any
+      );
 
       const result = await contract({}, io);
 
       expect(io.outText()).toContain('契约门控检查失败');
-      expect(result.kind).toBe('fail');
+      expect(io.outText()).toContain('  - missing field X');
+      expect(io.outText()).toContain('  - removed: /api/v1/users');
+      expect(result).toEqual({ kind: 'fail', reason: 'contract gate denied: validation errors' });
     });
 
     it('should handle thrown errors and exit 1', async () => {
       mockFs.access.mockResolvedValue(undefined);
-      const mockCheck = jest.fn().mockRejectedValue(new Error('gate error'));
-      MockGate.mockImplementation(() => ({ check: mockCheck }) as any);
+      MockGate.mockImplementation(() => throwingGate(new Error('gate error')) as any);
 
       const result = await contract({}, io);
 
       expect(io.outText()).toContain('契约门控检查出错');
-      expect(result.kind).toBe('fail');
+      expect(result).toEqual({ kind: 'fail', reason: 'contract gate error: gate error' });
     });
   });
 

package/src/cli/commands/__tests__/failure.test.ts

@@ -5,9 +5,10 @@
 import * as fs from 'fs';
 import { captureIO, type CapturingIO } from '../../command-contract';
 import * as path from 'path';
+import * as os from 'os';
 import { FailureRecorder } from '../../../failure/recorder';
-import { ErrorType, FailureLevel } from '../../../failure/types';
-import type { FailureRecord } from '../../../failure/types';
+import { ErrorType, FailureLevel } from '../../../types/failure';
+import type { FailureRecord } from '../../../types/failure';
 
 // Mock FailureRecorder
 jest.mock('../../../failure/recorder');
@@ -18,7 +19,7 @@ beforeEach(() => {
 });
 
 describe('failure CLI commands', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-failure-cli');
+  let tempDir: string;
   let mockRecorderInstance: {
     record: jest.Mock;
     getHistory: jest.Mock;
@@ -39,7 +40,7 @@ describe('failure CLI commands', () => {
   };
 
   beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-failure-cli-'));
   });
 
   afterAll(() => {

package/src/cli/commands/__tests__/gate-decision.ts

@@ -0,0 +1,30 @@
+/**
+ * 门禁命令测试的决策替身
+ *
+ * 命令的唯一入口是 `evaluate()`，所以替身是「产一枚决策的假门禁」——
+ * 映射与报告构造器用真实现（decisionFromResult / gateResult），
+ * 六个命令的测试因此不需要 git、gh 或真扫描。
+ */
+
+import { decisionFromResult } from '../../../gates/decision';
+import { gateResult } from '../../../gates/types';
+import type { GateDecision } from '../../../gates/types';
+
+export function decide(
+  gateId: string,
+  passed: boolean,
+  message: string,
+  details?: Record<string, any>
+): GateDecision {
+  return decisionFromResult(gateResult(gateId, passed, message, Date.now(), details));
+}
+
+/** 恒产同一枚决策的假门禁（evaluate 记录调用参数，供断言上下文） */
+export function fakeGate(decision: GateDecision): { evaluate: jest.Mock } {
+  return { evaluate: jest.fn().mockResolvedValue(decision) };
+}
+
+/** evaluate 直接抛出的假门禁：命令出错分支测的是门禁之外的失败（git / fs） */
+export function throwingGate(error: unknown): { evaluate: jest.Mock } {
+  return { evaluate: jest.fn().mockRejectedValue(error) };
+}

package/src/cli/commands/__tests__/init-dead-options.test.ts

@@ -0,0 +1,50 @@
+/**
+ * init 死选项 `-t/--type` 已删除（harness#132 grilling 落定）
+ *
+ * `-t, --type <type>` 自始只有定义表一条与 `InitOptions.type` 一个字段，全仓无读取方——
+ * `harness init -t nextjs-app` 恒不生效。scaffold 收口时按 ADR-0018 判据（只执法有真实现的
+ * 维度）连旗帜与字段一并删除。手法同 passes-gate-dead-options.test.ts：编译期
+ * `@ts-expect-error` 钉字段不存在 + 运行期钉定义表旗帜面。
+ */
+
+import { COMMAND_DEFINITIONS } from '../definitions';
+import type { InitOptions } from '../init';
+
+const initCommand = COMMAND_DEFINITIONS.find(d => d.command === 'init');
+
+describe('init 的 -t/--type 已删除（#132）', () => {
+  it('定义表已注册 init（前提）', () => {
+    expect(initCommand).toBeDefined();
+  });
+
+  it('init 旗帜面逐字冻结，不含 --type', () => {
+    expect((initCommand?.options || []).map(o => o.flags)).toEqual([
+      '-p, --preset <preset>',
+      '-g, --governance <level>',
+      '--project-path <path>',
+      '--no-git-hooks',
+      '--ci <platform>',
+      '--no-github-actions',
+      '--print-snippets',
+    ]);
+  });
+
+  it('InitOptions 的 type 字段已从类型面消失（编译期钉）', () => {
+    // @ts-expect-error -t/--type 无实现，随 #132 从 InitOptions 删除
+    const removed: InitOptions = { preset: 'standard', type: 'nextjs-app' };
+    expect(removed).toBeDefined();
+  });
+
+  it('活旗帜仍可赋值（防止删多）', () => {
+    const live: InitOptions = {
+      preset: 'strict',
+      governance: 'minimal',
+      projectPath: '/tmp/p',
+      gitHooks: false,
+      githubActions: false,
+      ci: 'gitlab',
+      printSnippets: true,
+    };
+    expect(Object.keys(live)).toHaveLength(7);
+  });
+});

package/src/cli/commands/__tests__/init-governance-io.test.ts

@@ -0,0 +1,139 @@
+/**
+ * 治理链路的 io 注入不逃逸（harness#149）
+ *
+ * setupGovernance 手握 io，却在两个调用点把它丢了（`setupClaudeMdOutputStyle(projectPath)`
+ * / `setupGovernanceConstraints(projectPath)`），被调方一律 `io: CommandIO = processIO`
+ * 兜成真实 stdout。真机输出正常，但注入面的测试看不见那 14 条提示——`⚠️ …标记残缺…`
+ * 这类唯一提示写坏了没有测试会红。
+ *
+ * 本文件不 mock 任何 IO：在临时目录里真跑 init，断言治理段提示落在**注入面**。
+ * 改造前这些断言逐条为红（文本逃到了 process.stdout）。
+ */
+
+import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { init, type InitOptions } from '../init';
+import { captureIO, type CapturingIO } from '../../command-contract';
+
+jest.mock('chalk', () => ({
+  blue: jest.fn((s: string) => s),
+  yellow: jest.fn((s: string) => s),
+  green: jest.fn((s: string) => s),
+  gray: jest.fn((s: string) => s),
+  red: jest.fn((s: string) => s),
+  cyan: jest.fn((s: string) => s),
+  bold: jest.fn((s: string) => s),
+}));
+
+const INIT_SOURCE = fsSync.readFileSync(path.join(__dirname, '..', 'init.ts'), 'utf-8');
+
+const INIT_OPTIONS: Partial<InitOptions> = { preset: 'standard', governance: 'standard' };
+
+/** 真临时工程根：带 .git 与 src/，让 init 走完治理链路而不必先落别的文件 */
+async function makeProject(files: Record<string, string> = {}): Promise<string> {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'harness-governance-io-'));
+  await fs.mkdir(path.join(root, 'src'));
+  await fs.writeFile(path.join(root, 'src', 'index.ts'), 'export const x = 1;\n');
+  await fs.mkdir(path.join(root, '.git'));
+  for (const [rel, content] of Object.entries(files)) {
+    await fs.writeFile(path.join(root, rel), content, 'utf-8');
+  }
+  return root;
+}
+
+async function runInit(files: Record<string, string>): Promise<CapturingIO> {
+  const root = await makeProject(files);
+  roots.push(root);
+  const io = captureIO();
+  expect(await init({ ...INIT_OPTIONS, projectPath: root } as InitOptions, io)).toEqual({ kind: 'ok' });
+  return io;
+}
+
+const roots: string[] = [];
+
+afterAll(async () => {
+  await Promise.all(roots.map(root => fs.rm(root, { recursive: true, force: true })));
+});
+
+describe('init 治理链路的提示落在注入面（harness#149）', () => {
+  it('Output Style 段（setupClaudeMdOutputStyle 调用点曾丢 io）：写入提示进捕获 stdout', async () => {
+    const io = await runInit({ 'CLAUDE.md': '# CLAUDE.md\n\n项目说明\n' });
+    expect(io.outText()).toContain('✅ 已在 CLAUDE.md 顶部写入 Output Style 段');
+  });
+
+  it('治理契约追加到既有 AGENTS.md：`已追加治理契约` 进捕获 stdout', async () => {
+    const io = await runInit({ 'AGENTS.md': '# AGENTS.md\n\n既有导读\n' });
+    expect(io.outText()).toContain('✅ 已追加治理契约 PRESERVE:governance 段到 AGENTS.md');
+  });
+
+  it('标记残缺（唯一提示）：`标记残缺…请人工修复` 进捕获 stdout', async () => {
+    const io = await runInit({ 'AGENTS.md': '# AGENTS.md\n\n<!-- PRESERVE:governance -->\n残缺段\n' });
+    expect(io.outText()).toContain('⚠️  AGENTS.md 中 PRESERVE:governance 标记残缺（只有单边），跳过治理契约写入，请人工修复');
+  });
+
+  // #158 补钉：这类提示在 init.ts 实测有四处，#149 只钉住上面一条——其余三处各补一条
+  // 捕获面断言。四处分支不同文件/不同段位，fixture 各自单建，不共用残缺文件。
+
+  it('标记残缺四处之二：CLAUDE.md 的 HARNESS_OUTPUT_STYLE 单边 → Output Style 注入告警', async () => {
+    const io = await runInit({ 'CLAUDE.md': '# CLAUDE.md\n\n<!-- HARNESS_OUTPUT_STYLE_START -->\n半残段\n' });
+    expect(io.outText()).toContain('⚠️  CLAUDE.md 中 HARNESS_OUTPUT_STYLE 标记残缺（单边或乱序），跳过 Output Style 注入，请人工修复');
+  });
+
+  it('标记残缺四处之三：AGENTS.md 的 PRESERVE 段内 HARNESS_CONSTRAINTS 单边 → 段内告警', async () => {
+    const broken = [
+      '# AGENTS.md',
+      '',
+      '<!-- PRESERVE:governance -->',
+      '手写契约',
+      '',
+      '<!-- HARNESS_CONSTRAINTS_START -->',
+      '半残注入',
+      '<!-- /PRESERVE:governance -->',
+      '',
+    ].join('\n');
+    const io = await runInit({ 'AGENTS.md': broken });
+    expect(io.outText()).toContain('⚠️  AGENTS.md PRESERVE:governance 段内 HARNESS_CONSTRAINTS 标记残缺（单边或乱序），跳过治理契约写入，请人工修复');
+  });
+
+  it('标记残缺四处之四：CLAUDE.md 的 HARNESS_CONSTRAINTS 单边 → 治理约束注入告警（旧模型仓落点）', async () => {
+    const io = await runInit({ 'CLAUDE.md': '# CLAUDE.md\n\n<!-- HARNESS_CONSTRAINTS_START -->\n半残段\n' });
+    expect(io.outText()).toContain('⚠️  CLAUDE.md 中 HARNESS_CONSTRAINTS 标记残缺（单边或乱序），跳过治理约束注入，请人工修复');
+  });
+
+  it('新仓创建 AGENTS.md 治理段：创建提示进捕获 stdout', async () => {
+    const io = await runInit({});
+    expect(io.outText()).toContain('✅ 已创建 AGENTS.md 并写入治理契约 PRESERVE:governance 段');
+  });
+});
+
+describe('writer 层 io 必传（源形状闸，防缺省兜底再回来）', () => {
+  it('init.ts 里 `io: CommandIO = processIO` 只剩 init() 一处（对外入口保留缺省）', () => {
+    const sites = INIT_SOURCE.split('\n').filter(line => line.includes('io: CommandIO = processIO'));
+    expect(sites).toHaveLength(1);
+    expect(sites[0]).toMatch(/^export async function init\(/);
+  });
+
+  it('三个 writer 与落点路由的 io 均为必传形参', () => {
+    for (const writer of [
+      'setupClaudeMdOutputStyle',
+      'setupAgentsMdConstraints',
+      'setupClaudeMdConstraints',
+      'setupGovernanceConstraints',
+    ]) {
+      expect(INIT_SOURCE).toMatch(
+        new RegExp(`export async function ${writer}\\(projectPath: string, io: CommandIO\\)`),
+      );
+    }
+  });
+
+  it('setupGovernance 的调用点逐个传 io（不留裸 projectPath 调用）', () => {
+    const governanceBody = INIT_SOURCE.slice(
+      INIT_SOURCE.indexOf('async function setupGovernance('),
+      INIT_SOURCE.indexOf('/**\n * 目录 CONTEXT.md 骨架的 plan'),
+    );
+    expect(governanceBody).toMatch(/await setupClaudeMdOutputStyle\(projectPath, io\)/);
+    expect(governanceBody).toMatch(/await setupGovernanceConstraints\(projectPath, io\)/);
+  });
+});