@dommaker/harness 1.8.0 → 1.8.1

package/src/cli/commands/CONTEXT.md

@@ -10,6 +10,7 @@ H5（#44）起：
 ## 核心导出
 - `COMMAND_DEFINITIONS`（definitions.ts）— 全部非门禁命令定义（纯数据模块、零闭包，禁止 import 命令实现；ADR-0010）
 - 命令契约（`src/cli/command-contract.ts`，上层目录）— `CommandResult` / `CommandKind` / `CommandIO` / `processIO` / `captureIO` / `lastJsonOutput` / `log` / `logError`
+- 状态文件接缝（`src/cli/state-io.ts`，上层目录）— `.harness/.state.json` 读-改-写的唯一入口 `StateIO`（`read()`/`write()`）+ 状态类型 `HarnessState` + 缺省真实 fs 实现 `fileStateIO(projectPath)`；`check` / `status` 经可选 `stateIO` 参数注入（ADR-0026，harness#148）
 - 门禁命令共享面（`src/cli/gate-command.ts`，上层目录）— `GateDecision → CommandResult` 的唯一映射 `gateCommandResult`，加 ✓/✗ 输出骨架 `reportGateDecision` 与出错横幅 `reportGateError`。同一句失败措辞此前抄在 6 个 handler 里（「`<id>` gate denied」×6 / 「`<id>` gate error」×4），门禁特有的指标行经 `onPass`/`onFail` 闭包传入（架构评审候选1）
 - 脚手架落盘面（`src/cli/commands/scaffold.ts`）— 受管文件（managed file）三态判定 `writeManagedFile` / 一组落盘 `runPlan` + 9 个站点工厂（含对外文案）；模板正文住 `scaffold-templates.ts`，落盘注入面 `ScaffoldFileSystem` 可换内存替身（harness#132）；CI 站点工厂 `harnessCheckCiFile` 带平台维度（github / gitlab，harness#143）；两道 Git hook 工厂 `preCommitHookFile` / `prePushHookFile`（后者 harness#144，带可执行位）
 - knowledge 投影面（`src/cli/commands/knowledge-view.ts`）— 11 个 knowledge 子操作的**display model** 渲染与出口：`emitKnowledgeView`（json/人读唯一分派 + 退出码）、`announce`（取数期进度行，`--json` 下静默）、`TONE_STYLES` 角色→样式单表、维度/规则 label 与 `toneForMaturity`/`toneForScore`/`toneForSeverity` 三张映射、`resolveKnowledgeBaseDir` + `openKnowledgeStore`（路径兜底与 store 构造单点）（harness#133）

package/src/cli/commands/__tests__/check-read-count.test.ts

@@ -90,6 +90,8 @@ function fixtureRepo(): string {
   write(dir, 'src/existing.ts', 'export const a = 1;\n');
   write(dir, 'src/nested/deep.ts', 'export const d = 1;\n');
   write(dir, '.harness/logs/traces.log', '{"constraintId":"fixture","result":"pass"}\n');
+  // ADR-0026：状态文件进夹具，智能提示的状态读取随之进计数表（一次运行至多读一次）
+  write(dir, '.harness/.state.json', '{}');
   git(dir, 'add', '.');
   git(dir, 'commit', '-q', '-m', 'baseline');
   // 改一个已登记的源文件并 stage → 触发条件 module_modification
@@ -139,6 +141,7 @@ describe('一次 check 的文件读取计数闸（ADR-0023 决策 5 ①）', ()
         ['.harness/custom-constraints.yml', 1],
         ['CAPABILITIES.md', 1],
         ['.harness/logs/traces.log', 2],
+        ['.harness/.state.json', 1], // ADR-0026：智能提示经 StateIO 读状态，恰一次
         // —— 已知例外（改动需明写理由）——
         // traces.log = 2：head 50（智能提示的阈值判定，决策 3）与 tail 20（有无失败证据，
         // 决策 4）是两个不同窗口的**有界**读；并成一个窗口就等于回到整读。

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

@@ -18,6 +18,7 @@ import { execFileSync } from 'child_process';
 
 import { check, listLaws } from '../check';
 import { captureIO, type CapturingIO } from '../../command-contract';
+import type { HarnessState, StateIO } from '../../state-io';
 import { DEFAULT_TRACE_FILE } from '../../../types/trace';
 import {
   createGitEvidence,
@@ -92,6 +93,19 @@ function projectTraces(
     .map(line => JSON.parse(line));
 }
 
+/**
+ * 内存 StateIO 假件（ADR-0026）：状态相关测试经注入面驱动，不碰真文件系统。
+ * `snapshot()` 给断言用——读的是假件当前持有的状态，不是磁盘。
+ */
+function memoryStateIO(initial: HarnessState = {}): StateIO & { snapshot(): HarnessState } {
+  let state = initial;
+  return {
+    read: () => state,
+    write: (next: HarnessState) => { state = next; },
+    snapshot: () => state,
+  };
+}
+
 /** 计数 git 证据：既记录证据方法请求，也记录实际 spawn 的 git 命令（执行走真 adapter） */
 function recordingEvidence(projectPath: string): {
   evidence: GitEvidence;
@@ -482,27 +496,25 @@ describe('check command（真 git fixture）', () => {
     });
   });
 
-  describe('智能提示（真 traces.log 与状态文件）', () => {
+  describe('智能提示（真 traces.log + 注入 StateIO 假件）', () => {
     it('记录数首次达到 50 时提示，并落盘已提示状态', async () => {
       const dir = gitRepo();
       passTraces(dir, 50);
+      const stateIO = memoryStateIO();
 
-      await check({ preset: 'standard', staged: true, projectPath: dir, trigger: 'manual' }, io);
+      await check({ preset: 'standard', staged: true, projectPath: dir, trigger: 'manual', stateIO }, io);
 
       expect(io.outText()).toContain('记录已足够，运行 harness status 查看统计');
       expect(io.outText()).toContain('────────────────');
-      const state = JSON.parse(
-        fs.readFileSync(path.join(dir, '.harness', '.state.json'), 'utf-8')
-      );
-      expect(state.shownHints).toContain('trace_50');
+      expect(stateIO.snapshot().shownHints).toContain('trace_50');
     });
 
     it('已提示过的不再重复提示', async () => {
       const dir = gitRepo();
       passTraces(dir, 50);
-      write(dir, '.harness/.state.json', JSON.stringify({ shownHints: ['trace_50'] }));
+      const stateIO = memoryStateIO({ shownHints: ['trace_50'] });
 
-      await check({ preset: 'standard', staged: true, projectPath: dir, trigger: 'manual' }, io);
+      await check({ preset: 'standard', staged: true, projectPath: dir, trigger: 'manual', stateIO }, io);
 
       expect(io.outText()).not.toContain('记录已足够');
       expect(io.outText()).not.toContain('────────────────');

package/src/cli/commands/__tests__/status-extra.test.ts

@@ -3,10 +3,12 @@
  *
  * ADR-0020 起不再 mock TraceAnalyzer/TraceCollector：异常判定走真实纯函数，
  * 用例喂能真的判出异常的 trace（passRate < 0.3 → low_pass_rate）。
+ * ADR-0026 起状态文件读写经注入的 StateIO 假件，不碰（被 mock 的）fs。
  */
 
-import { status } from '../status';
-import { captureIO, type CapturingIO } from '../../command-contract';
+import { status, type StatusOptions } from '../status';
+import { captureIO, type CapturingIO, type CommandResult } from '../../command-contract';
+import type { HarnessState, StateIO } from '../../state-io';
 import * as fs from 'fs';
 import type { ExecutionTrace } from '../../../types/trace';
 
@@ -46,6 +48,21 @@ beforeEach(() => {
   io = captureIO();
 });
 
+/** 内存 StateIO 假件（ADR-0026）：缺省 fileStateIO 在全 mock 的 fs 下会吃到 trace 假数据 */
+function memoryStateIO(initial: HarnessState = {}): StateIO & { snapshot(): HarnessState } {
+  let state = initial;
+  return {
+    read: () => state,
+    write: (next: HarnessState) => { state = next; },
+    snapshot: () => state,
+  };
+}
+
+/** 全部用例经注入假件调用 status */
+function runStatus(options: StatusOptions = {}): Promise<CommandResult> {
+  return status({ stateIO: memoryStateIO(), ...options }, io);
+}
+
 describe('status command - 补充覆盖', () => {
 
   beforeEach(() => {
@@ -64,7 +81,7 @@ describe('status command - 补充覆盖', () => {
         ...repeats('no_completion_without_verification', 2, 'fail'),
       ]));
 
-      await status({ anomalies: true }, io);
+      await runStatus({ anomalies: true });
 
       const output = io.outText();
       expect(output).toContain('发现 2 个异常');
@@ -78,7 +95,7 @@ describe('status command - 补充覆盖', () => {
         { constraintId: 'test', result: 'pass' },
       ]));
 
-      await status({ anomalies: true }, io);
+      await runStatus({ anomalies: true });
 
       expect(io.outText()).toContain('✅ 未发现异常');
     });
@@ -91,7 +108,7 @@ describe('status command - 补充覆盖', () => {
         { constraintId: 'no_completion_without_verification' },
       ]));
 
-      await status({}, io);
+      await runStatus();
 
       const output = io.outText();
       expect(output).toContain('📈 约束统计:');
@@ -104,7 +121,7 @@ describe('status command - 补充覆盖', () => {
         { constraintId: 'capability_sync', level: 'guideline', result: 'pass' },
       ]));
 
-      await status({}, io);
+      await runStatus();
 
       expect(io.outText()).toContain('🟡 Guidelines:');
     });
@@ -118,7 +135,7 @@ describe('status command - 补充覆盖', () => {
         { constraintId: 'capability_sync', level: 'guideline' },
       ]));
 
-      await status({ detail: true }, io);
+      await runStatus({ detail: true });
 
       const output = io.outText();
       expect(output).toContain('📈 约束统计:');
@@ -134,7 +151,7 @@ describe('status command - 补充覆盖', () => {
         ['invalid json', JSON.stringify({ constraintId: 'valid', level: 'iron_law', timestamp: 1, result: 'pass' }), 'also invalid'].join('\n')
       );
 
-      await status({}, io);
+      await runStatus();
 
       // 应该成功处理，不会抛出异常：坏行进 stderr 告知，合法行进统计
       const output = io.outText();

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

@@ -3,10 +3,12 @@
  *
  * ADR-0020 起不再 mock TraceAnalyzer/TraceCollector：统计与异常由 trace-analyzer
  * 的模块级纯函数真算，用例喂合法 trace 行、断言真实输出。
+ * ADR-0026 起状态文件读写经注入的 StateIO 假件，不碰（被 mock 的）fs。
  */
 
-import { status } from '../status';
-import { captureIO, type CapturingIO } from '../../command-contract';
+import { status, type StatusOptions } from '../status';
+import { captureIO, type CapturingIO, type CommandResult } from '../../command-contract';
+import type { HarnessState, StateIO } from '../../state-io';
 import * as fs from 'fs';
 import type { ExecutionTrace } from '../../../types/trace';
 
@@ -42,10 +44,27 @@ function repeats(constraintId: string, n: number, result: ExecutionTrace['result
 }
 
 let io: CapturingIO;
+let stateIO: ReturnType<typeof memoryStateIO>;
 beforeEach(() => {
   io = captureIO();
+  stateIO = memoryStateIO();
 });
 
+/** 内存 StateIO 假件（ADR-0026）：状态读写走注入面，缺省 fileStateIO 在全 mock 的 fs 下会吃到 trace 假数据 */
+function memoryStateIO(initial: HarnessState = {}): StateIO & { snapshot(): HarnessState } {
+  let state = initial;
+  return {
+    read: () => state,
+    write: (next: HarnessState) => { state = next; },
+    snapshot: () => state,
+  };
+}
+
+/** 全部用例经注入假件调用 status（stateIO 可被单例覆盖以预置状态） */
+function runStatus(options: StatusOptions = {}): Promise<CommandResult> {
+  return status({ stateIO, ...options }, io);
+}
+
 describe('status command', () => {
 
   beforeEach(() => {
@@ -59,7 +78,7 @@ describe('status command', () => {
   describe('未初始化情况', () => {
     it('应该显示未初始化提示', async () => {
       mockFs.existsSync.mockReturnValue(false);
-      await status({}, io);
+      await runStatus();
       expect(io.outText()).toContain('未初始化');
     });
   });
@@ -71,7 +90,7 @@ describe('status command', () => {
         .mockReturnValueOnce(true) // .harness dir
         .mockReturnValueOnce(false); // traces file
 
-      await status({}, io);
+      await runStatus();
       expect(io.outText()).toContain('暂无 Trace');
     });
   });
@@ -83,7 +102,7 @@ describe('status command', () => {
         { constraintId: 'test2', level: 'guideline' },
       ]));
 
-      await status({}, io);
+      await runStatus();
       expect(io.outText()).toContain('记录数: 2 条');
       expect(io.outText()).toContain('📈 约束统计:');
     });
@@ -93,7 +112,7 @@ describe('status command', () => {
         { constraintId: 'no_bypass_checkpoint' },
       ]));
 
-      await status({ detail: true }, io);
+      await runStatus({ detail: true });
       expect(io.outText()).toContain('🔴 Iron Laws:');
       expect(io.outText()).toContain('✅ no_bypass_checkpoint');
       expect(io.outText()).toContain('检查: 1 | 通过: 100% | 失败: 0%');
@@ -106,7 +125,7 @@ describe('status command', () => {
         { constraintId: 'test1', result: 'fail' },
       ]));
 
-      await status({ anomalies: true }, io);
+      await runStatus({ anomalies: true });
       expect(io.outText()).toContain('发现 1 个异常');
       expect(io.outText()).toContain('  test1');
       expect(io.outText()).toContain('类型: low_pass_rate');
@@ -120,17 +139,26 @@ describe('status command', () => {
         { constraintId: 'test1', result: 'fail' },
       ]));
 
-      await status({ detail: true }, io);
+      await runStatus({ detail: true });
       expect(io.outText()).toContain('检查: 5 | 通过: 80% | 失败: 20%');
     });
   });
 
   describe('状态文件更新', () => {
-    it('应该更新 .state.json', async () => {
+    it('应该经 StateIO 写入 lastStatusRun', async () => {
+      mockFs.readFileSync.mockReturnValue(traceFile([{ constraintId: 'test' }]));
+
+      await runStatus();
+      expect(stateIO.snapshot().lastStatusRun).toBeTruthy();
+    });
+
+    it('读-改-写：已有的 shownHints 不被 status 抹掉（ADR-0026 决策 2 的行为修复）', async () => {
       mockFs.readFileSync.mockReturnValue(traceFile([{ constraintId: 'test' }]));
+      stateIO = memoryStateIO({ shownHints: ['trace_50'] });
 
-      await status({}, io);
-      expect(mockFs.writeFileSync).toHaveBeenCalled();
+      await runStatus();
+      expect(stateIO.snapshot().shownHints).toEqual(['trace_50']);
+      expect(stateIO.snapshot().lastStatusRun).toBeTruthy();
     });
   });
 
@@ -140,7 +168,7 @@ describe('status command', () => {
         { constraintId: 'test_guide', level: 'guideline' },
       ]));
 
-      await status({}, io);
+      await runStatus();
       expect(io.outText()).toContain('🟡 Guidelines:');
       expect(io.outText()).toContain('✅ test_guide');
     });
@@ -150,7 +178,7 @@ describe('status command', () => {
     it('应该显示未发现异常当无异常', async () => {
       mockFs.readFileSync.mockReturnValue(traceFile([{ constraintId: 'test' }]));
 
-      await status({ anomalies: true }, io);
+      await runStatus({ anomalies: true });
       expect(io.outText()).toContain('✅ 未发现异常');
     });
 
@@ -159,7 +187,7 @@ describe('status command', () => {
         { constraintId: 'test', result: 'fail' },
       ]));
 
-      await status({ anomalies: true }, io);
+      await runStatus({ anomalies: true });
       expect(io.outText()).toContain('当前值: 0');
       expect(io.outText()).toContain('阈值: 0.3');
       expect(io.outText()).toContain('下一步建议');
@@ -170,7 +198,7 @@ describe('status command', () => {
     it('应该显示良好建议当 trace >= 100', async () => {
       mockFs.readFileSync.mockReturnValue(traceFile(repeats('test', 100, 'pass')));
 
-      await status({}, io);
+      await runStatus();
       expect(io.outText()).toContain('记录数: 100 条');
       expect(io.outText()).toContain('状态良好');
     });
@@ -178,7 +206,7 @@ describe('status command', () => {
     it('应该显示积累数据建议当 trace < 100', async () => {
       mockFs.readFileSync.mockReturnValue(traceFile([{ constraintId: 'test' }]));
 
-      await status({}, io);
+      await runStatus();
       expect(io.outText()).toContain('继续积累数据');
     });
 
@@ -187,7 +215,7 @@ describe('status command', () => {
         { constraintId: 'test', result: 'fail' },
       ]));
 
-      await status({ anomalies: true }, io);
+      await runStatus({ anomalies: true });
       expect(io.outText()).toContain('harness status --detail');
     });
   });
@@ -199,7 +227,7 @@ describe('status command', () => {
         ...repeats('test_guide', 2, 'fail'),
       ].map(t => ({ ...t, level: 'guideline' as const }))));
 
-      await status({ detail: true }, io);
+      await runStatus({ detail: true });
       expect(io.outText()).toContain('⚠️ test_guide');
       expect(io.outText()).toContain('检查: 5 | 通过: 60% | 失败: 40%');
     });

package/src/cli/commands/check.ts

@@ -9,7 +9,6 @@
  */
 
 import chalk from 'chalk';
-import * as fs from 'fs';
 import * as path from 'path';
 import { ConstraintChecker } from '../../core/constraints/checker';
 import { IRON_LAWS, GUIDELINES, PROMPTS } from '../../core/constraints/definitions';
@@ -24,6 +23,7 @@ import { readJsonl } from '../../utils/jsonl';
 import { DEFAULT_TRACE_FILE, type ExecutionTrace } from '../../types/trace';
 import type { ConstraintResult, ConstraintTrigger } from '../../types/constraint';
 import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
+import { fileStateIO, type StateIO } from '../state-io';
 
 /** 证据行着色（与调用处所属结论块一致） */
 const EVIDENCE_PAINT = {
@@ -74,6 +74,13 @@ export interface CheckOptions {
    * 测试据此断言「同一次运行内同一项目文件至多读一次」。
    */
   runEnv?: RunEnv;
+  /**
+   * 状态文件接缝（非 CLI flag；ADR-0026）
+   *
+   * 缺省 = 真实 fs 实现（fileStateIO）。注入则 `.harness/.state.json` 的读写
+   * 走替身，测试据此不碰真文件系统。
+   */
+  stateIO?: StateIO;
 }
 
 /**
@@ -91,6 +98,7 @@ export async function check(
     // 一次 run 一份证据与观察面（#87 / ADR-0023）：入口构造，沿生效集、context、checker 向下传
     const evidence = options.evidence ?? createGitEvidence(projectPath);
     const runEnv = options.runEnv ?? createRunEnv(projectPath);
+    const stateIO = options.stateIO ?? fileStateIO(projectPath);
 
     // 生效约束集（ADR-0001）：内置 → preset → config.yml 禁用 → custom 追加 → scenes 过滤。
     // --preset 仅在没有项目自定义配置时覆盖 config.yml 的 preset（工单 23 语义：
@@ -221,7 +229,7 @@ export async function check(
     log(io, chalk.green('✅ 约束检查通过'));
 
     // 智能提示
-    const hint = await getSmartHint(projectPath);
+    const hint = await getSmartHint(projectPath, stateIO);
     if (hint) {
       log(io);
       log(io, chalk.gray('────────────────────────────────────'));
@@ -241,10 +249,12 @@ const TRACE_HINT_THRESHOLD = 50;
 
 /**
  * 智能提示：检查是否需要提示用户下一步操作
+ *
+ * 状态读写经 StateIO（ADR-0026）：读-改-写，`status` 不再把 `shownHints` 抹掉，
+ * 「首次达到阈值」的去重自此真生效。
  */
-async function getSmartHint(projectPath: string): Promise<string | null> {
+async function getSmartHint(projectPath: string, stateIO: StateIO): Promise<string | null> {
   const tracesPath = path.join(projectPath, DEFAULT_TRACE_FILE);
-  const statePath = path.join(projectPath, '.harness', '.state.json');
 
   // 只读够 TRACE_HINT_THRESHOLD 行即停（坏行照旧占位，条数口径与改前的纯计数逐字一致）——
   // traces.log 是 append-only 无上限文件，为一个比较符整读不成立
@@ -256,19 +266,12 @@ async function getSmartHint(projectPath: string): Promise<string | null> {
   if (traceCount === 0) {
     return null;
   }
-  // 读取状态
-  let state: { 
-    shownHints?: string[];
-    lastStatusRun?: string;
-    lastDiagnoseRun?: string;
-  } = {};
-  if (fs.existsSync(statePath)) {
-    state = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
-  }
+  // 读取状态（经接缝；文件缺失 → {}）
+  const state = stateIO.read();
   state.shownHints = state.shownHints || [];
-  
+
   const hints: string[] = [];
-  
+
   // 条件 1: 记录数首次达到阈值
   if (traceCount >= TRACE_HINT_THRESHOLD && !state.shownHints.includes('trace_50')) {
     hints.push('📊 记录已足够，运行 harness status 查看统计');
@@ -277,11 +280,10 @@ async function getSmartHint(projectPath: string): Promise<string | null> {
 
   // 保存状态
   if (hints.length > 0) {
-    fs.mkdirSync(path.dirname(statePath), { recursive: true });
-    fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+    stateIO.write(state);
     return hints.join('\n');
   }
-  
+
   return null;
 }
 

package/src/cli/commands/status.ts

@@ -13,6 +13,7 @@ import { DEFAULT_TRACE_FILE } from '../../types/trace';
 import type { ExecutionTrace } from '../../types/trace';
 import type { TraceSummary, TraceAnomaly } from '../../types/trace';
 import { log, logError, processIO, type CommandIO, type CommandResult } from '../command-contract';
+import { fileStateIO, type StateIO } from '../state-io';
 
 export interface StatusOptions {
   /** 项目路径 */
@@ -23,6 +24,13 @@ export interface StatusOptions {
   anomalies?: boolean;
   /** 时间范围（小时） */
   hours?: number;
+  /**
+   * 状态文件接缝（非 CLI flag；ADR-0026）
+   *
+   * 缺省 = 真实 fs 实现（fileStateIO）。注入则 `.harness/.state.json` 的读写
+   * 走替身，测试据此不碰真文件系统。
+   */
+  stateIO?: StateIO;
 }
 
 /**
@@ -32,7 +40,7 @@ export async function status(options: StatusOptions, io: CommandIO = processIO):
   const projectPath = options.projectPath || process.cwd();
   const harnessDir = path.join(projectPath, '.harness');
   const tracesPath = path.join(projectPath, DEFAULT_TRACE_FILE);
-  const statePath = path.join(harnessDir, '.state.json');
+  const stateIO = options.stateIO ?? fileStateIO(projectPath);
 
   log(io, chalk.blue('📊 Harness 状态'));
   log(io);
@@ -139,12 +147,9 @@ export async function status(options: StatusOptions, io: CommandIO = processIO):
     log(io);
   }
 
-  // 更新状态文件
-  const state = {
-    lastStatusRun: new Date().toISOString(),
-  };
-  fs.mkdirSync(path.dirname(statePath), { recursive: true });
-  fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+  // 更新状态文件：读-改-写（ADR-0026 决策 2）——不再整文件重写，
+  // 否则 check 写入的 shownHints 会被抹掉、智能提示去重失效
+  stateIO.write({ ...stateIO.read(), lastStatusRun: new Date().toISOString() });
 
   // 下一步建议
   log(io, chalk.blue('💡 下一步建议:'));

package/src/cli/state-io.ts

@@ -0,0 +1,53 @@
+/**
+ * 状态文件 IO 接缝（StateIO，ADR-0026 / harness#148）
+ *
+ * `.harness/.state.json` 是 harness **自身**的运行期状态（与 RunEnv 观察的项目上行
+ * 数据不是一类东西，RunEnv 保持 ADR-0023 的只读契约）。本模块是它读-改-写的唯一
+ * 入口：`check` 的智能提示与 `status` 两个写者都经本接缝，命令函数以可选参数注入，
+ * 缺省 = 真实 fs 实现（照 `CommandIO` 的注入模式，但不扩 `CommandIO`——输出面与
+ * 状态面是两个概念）。
+ *
+ * 落点 cli 层：两个消费者都在 cli，不进 core、不进包根导出面（零公共面变化）。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * `.harness/.state.json` 的具名类型（从 check.ts 内联类型提出，ADR-0026 决策 1）。
+ * `lastDiagnoseRun` 字段已删除——全仓零生产者零消费者（ADR-0022 口径）；
+ * 已落盘旧文件里残留该键无害，不做迁移。
+ */
+export interface HarnessState {
+  /** 已展示过的智能提示 id（去重依据） */
+  shownHints?: string[];
+  /** 最近一次 `harness status` 运行时刻（ISO 串） */
+  lastStatusRun?: string;
+}
+
+/** harness 自身运行期状态文件的可注入接缝（读-改-写的唯一入口） */
+export interface StateIO {
+  /** 文件缺失/空 → `{}`；损坏 → 现状语义（JSON.parse 抛即抛，不兜底，ADR-0026 决策 4） */
+  read(): HarnessState;
+  write(state: HarnessState): void;
+}
+
+/**
+ * 缺省真实 fs 实现：锚 projectPath（与 trace 落点同锚，#139），
+ * 状态文件路径知识只在本模块一份。
+ */
+export function fileStateIO(projectPath: string): StateIO {
+  const statePath = path.join(projectPath, '.harness', '.state.json');
+  return {
+    read(): HarnessState {
+      if (!fs.existsSync(statePath)) return {};
+      const content = fs.readFileSync(statePath, 'utf-8');
+      if (content.trim() === '') return {};
+      return JSON.parse(content);
+    },
+    write(state: HarnessState): void {
+      fs.mkdirSync(path.dirname(statePath), { recursive: true });
+      fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+    },
+  };
+}

package/src/hooks/CONTEXT.md

@@ -9,7 +9,7 @@ H5（#44）起增加两个机制（G2/G7）：
 
 ## 核心导出
 - `HookRegistry` — Hook 注册表（register/registerAll/unregister/get/getEnabled/listNames/listAll/setEnabled/clear；register 以 HookConfig 填充有效值）
-- `HookPipeline` — Hook 执行管线（注册/排序/错误隔离/采样；errorStrategy block/warn）
+- `HookPipeline` — Hook 执行管线（注册/排序/错误隔离/采样；errorStrategy block/warn；`run(phase)` 时机粒度、`runFull` 全套、`runOne(name)` 按名执行单个 hook——#167 新增：enabled:false 返回 skipped:true 记录且实现体零调用，block 失败抛错 / warn 失败返回 passed:false 记录，未知名抛错（口径同注册表闭环），采样与错误隔离复用 executeOne 单路径）
 - `assertHookRegistryClosed` — 注册表闭环双向校验（构建/测试期）
 - `HookConfig`（type）— per-hook 配置声明（enabled / errorStrategy 唯一声明点）
 - `EffectiveHook`（type）— HookDefinition + 配置填充的有效 enabled / errorStrategy（管线与注册表判定只读它）