@dommaker/harness 1.8.0 → 1.9.0

package/src/CONTEXT.md

@@ -34,7 +34,7 @@
 
 | 术语 | 定义 |
 |------|------|
-| 插件 | harness 扩展点统称 = hook / checker / 门禁(Gate) / 命令(CLI)；非运行时插件容器——harness 是文件驱动 CLI、无常驻进程 |
+| 插件 | harness 扩展点统称 = checker / 门禁(Gate) / 命令(CLI)；非运行时插件容器——harness 是文件驱动 CLI、无常驻进程。hook 一族已退出扩展点统称（ADR-0027/#170 删 hooks 管线面，`src/hooks/` 只剩 bootstrap 组合根） |
 | Gate（门禁） | 统一守卫接口 `Gate{id, order, evaluate(ctx)}` → `GateDecision`；统一的是决策协议（id/order/三态），执行细节私有 |
 | GateDecision | 三态决策 `deny \| abstain \| ask`；deny 单调（下游不可改回 allow）、ask 枚举预留 fail-closed = deny |
 | GateResult | 报告结构（gate/passed/message/details/timestamp/duration），保留为报告层，不作决策 |
@@ -47,7 +47,7 @@
 | 飞轮指标（flywheel） | 知识条目的引用与消费度量（refCoverage / avgRefs / consumptionHitRate）；唯一实现 `knowledge/flywheel-metrics.ts`（包内，不进导出面），canonical 分子为过滤 synthetic 后的 genuine refs，audit D6 / knowledge stats / knowledge health 共消费（ADR-0013，#81） |
 | 测试夹具（project fixture） | 临时项目根 + 落盘声明；唯一实现 `test-setup/project-fixture.ts`（测试层，不进导出面）——`config` 槽是 `.harness/config.yml` 落点唯一正本（字符串原样落盘，畸形/脏配置用例依赖此口径），`traces` 槽/`writeProjectTraces` 是 trace 落盘唯一正本（路径锚定 `DEFAULT_TRACE_FILE`、序列化走 `appendJsonl` 生产写链，harness#108），其余文件走 `files` 相对路径；非缺省根必须经 `parentDir` **显式** opt-out（cwd 锚定用例语义），回收经 `mkdtemp-cleanup` 劫持（harness#90） |
 | 运行级观察面（run env） | 一次 `harness check` 运行内对项目上行数据的只读视图，口径 = **同一文件至多读一次、跑完即弃、不做进程级全局**；唯一实现 `core/constraints/run-env.ts`，承载 `rawConfig()` / `customConstraints(file)` / `capabilities(population)` / `traceTail(limit)` / `sourceRoots()` 五个观察口（配置与能力表的读取原进程级缓存已按 ADR-0023 决策 2 撤销），与 git 证据（#87/ADR-0021）同形：入口构造、沿调用链显式传递。与 `CheckEnv` 的分工是构造顺序决定的——`CheckEnv` 含 `context`，而 `context` 是经本观察面读文件算出的产物，故观察面只承载「不需要 context 就能造」的部分，`CheckEnv` 以 `extends RunEnv` 从它派生（ADR-0023）；`RunEnv` / `RunTarget`（= `RunEnv \| 项目根路径`）经 `./core` 以类型面导出，供消费方共享同一份读取。**只读是硬契约**：运行期状态文件的写口不走本面，走 StateIO（#148） |
-| 状态文件 IO（StateIO） | harness 自身运行期状态文件（`.harness/.state.json`）读写的可注入接缝：`read()`/`write()` 两方法、默认真实 fs 实现、命令可选参数注入（照 `CommandIO` 模式，但不扩 `CommandIO`）；收编 check 智能提示与 status 两个写者，写语义统一为**读-改-写**（现状 `status` 不读就整文件重写，会把 `check` 写的 `shownHints` 抹掉 → 提示去重失效）。决策已于 2026-09-16 当人面确认为 **ADR-0026**（票面原写 ADR-0024，该号已被 #135 占用），**代码未落**，实现票 #148；与运行级观察面（只读、项目上行数据）分工：本面管 harness 自身状态、含写 |
+| 状态文件 IO（StateIO） | harness 自身运行期状态文件（`.harness/.state.json`）读写的可注入接缝：`read()`/`write()` 两方法、默认真实 fs 实现 `fileStateIO(projectPath)`、命令可选参数注入（照 `CommandIO` 模式，但不扩 `CommandIO`）；唯一实现 `src/cli/state-io.ts`（cli 层，不进包根导出面），收编 check 智能提示与 status 两个写者，写语义统一为**读-改-写**（此前 `status` 不读就整文件重写、把 `check` 写的 `shownHints` 抹掉致提示去重失效，ADR-0026 已修）。决策 = **ADR-0026**，实现票 #148；与运行级观察面（只读、项目上行数据）分工：本面管 harness 自身状态、含写 |
 
 ## 注意事项
 - 公共包，禁止硬编码业务路径

package/src/__tests__/public-exports.test.ts

@@ -44,8 +44,6 @@ const EXPECTED_RUNTIME_EXPORTS = [
   'FileKnowledgeStore',
   'GATE_DEFINITIONS',
   'GUIDELINES',
-  'HookPipeline',
-  'HookRegistry',
   'IRON_LAWS',
   'KnowledgeAudit',
   'KnowledgeHealthScorer',
@@ -71,7 +69,6 @@ const EXPECTED_RUNTIME_EXPORTS = [
   'TraceAnalyzer',
   'TraceCollector',
   'assertGateRegistryClosed',
-  'assertHookRegistryClosed',
   'bootstrapHarness',
   'bootstrapHarnessSync',
   'checkBeforeExecution',
@@ -117,7 +114,6 @@ const EXPECTED_RUNTIME_EXPORTS = [
   'resolveGlobs',
   'runGates',
   'sanitizeExternalContent',
-  'toErrorStrategy',
   'validateAllSpecs',
   'validateSpec',
   'verifyContractPresence',
@@ -189,4 +185,34 @@ describe('包根类型面（ADR-0022 关联类型随迁）', () => {
     expect(liveCheck.allowed).toBe(true);
     expect(liveTask.command).toBe('npm test');
   });
+
+  /**
+   * ADR-0027（#170）管线面删除的可达性负钉：4 值符号 + 8 类型。
+   *
+   * 两道全量清单闸钉的是「码与名单不符」，本钉直接钉「barrel 源里不再出现这些名字」——
+   * 回灌时红名指到 barrel 本身，不必从清单 diff 反推。barrel 源形状即全可达面：
+   * `export *` 已被 `sub-barrels-explicit.test.ts` 禁到 src 下全部目录 barrel，
+   * 且 `./hooks` 不在 `package.json` 的 `exports` 内（无子路径入口可绕）。
+   */
+  const ADR0027_DELETED_SYMBOLS = [
+    'HookRegistry',
+    'HookPipeline',
+    'assertHookRegistryClosed',
+    'toErrorStrategy',
+    'HookDefinition',
+    'HookConfig',
+    'EffectiveHook',
+    'HookErrorStrategy',
+    'HookExecutionRecord',
+    'HookPhase',
+    'HookResult',
+    'PipelineResult',
+  ];
+
+  for (const rel of ['../hooks/index.ts', '../index.ts']) {
+    it(`${rel} 不再提及 ADR-0027 已删的管线面符号（保留面 bootstrapHarness* 不受影响）`, () => {
+      const source = fs.readFileSync(path.join(__dirname, rel), 'utf-8');
+      expect(ADR0027_DELETED_SYMBOLS.filter((name) => source.includes(name))).toEqual([]);
+    });
+  }
 });

package/src/__tests__/public-type-surface.test.ts

@@ -170,7 +170,6 @@ const PUBLISHED_ENTRY_TYPES: Record<string, string[]> = {
     'DocRegexCountCheck',
     'DocsSyncConfig',
     'EffectiveConfigLint',
-    'EffectiveHook',
     'ErrorClassificationRule',
     'ErrorClassifierConfig',
     'EventHandler',
@@ -189,12 +188,6 @@ const PUBLISHED_ENTRY_TYPES: Record<string, string[]> = {
     'GovernanceConfig',
     'GrepCountActual',
     'HarnessBootstrap',
-    'HookConfig',
-    'HookDefinition',
-    'HookErrorStrategy',
-    'HookExecutionRecord',
-    'HookPhase',
-    'HookResult',
     'ImportInfo',
     'IndexEntry',
     'IngestOptions',
@@ -217,7 +210,6 @@ const PUBLISHED_ENTRY_TYPES: Record<string, string[]> = {
     'PerformanceGateConfig',
     'PerformanceThresholds',
     'PhaseFormatResult',
-    'PipelineResult',
     'ProjectConfig',
     'QueryBudget',
     'QueryFilter',

package/src/cli/__tests__/state-io.test.ts

@@ -0,0 +1,50 @@
+/**
+ * fileStateIO 直测（ADR-0026）：真实 fs、临时目录，不 mock。
+ *
+ * 命令侧注入面见 check.test.ts / status.test.ts 的内存假件；
+ * 本套件只钉缺省实现自身的语义：缺失 → {}、写-读回环、损坏照现状抛、路径锚 projectPath。
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { fileStateIO } from '../state-io';
+
+describe('fileStateIO（真实 fs 缺省实现，ADR-0026）', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-state-io-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('文件缺失 → read() 返回 {}', () => {
+    expect(fileStateIO(dir).read()).toEqual({});
+  });
+
+  it('空文件（0 字节）→ read() 返回 {}（ADR-0026 决策 1「缺失/空」口径）', () => {
+    fs.mkdirSync(path.join(dir, '.harness'), { recursive: true });
+    fs.writeFileSync(path.join(dir, '.harness', '.state.json'), '');
+
+    expect(fileStateIO(dir).read()).toEqual({});
+  });
+
+  it('写-读回环：write() 自动建目录，落点锚 projectPath 下的 .harness/.state.json', () => {
+    const stateIO = fileStateIO(dir);
+    stateIO.write({ shownHints: ['trace_50'], lastStatusRun: '2026-09-17T00:00:00.000Z' });
+
+    const onDisk = path.join(dir, '.harness', '.state.json');
+    expect(fs.existsSync(onDisk)).toBe(true);
+    expect(stateIO.read()).toEqual({ shownHints: ['trace_50'], lastStatusRun: '2026-09-17T00:00:00.000Z' });
+  });
+
+  it('损坏文件照现状抛（不兜底成 {}，ADR-0026 决策 4）', () => {
+    fs.mkdirSync(path.join(dir, '.harness'), { recursive: true });
+    fs.writeFileSync(path.join(dir, '.harness', '.state.json'), 'not json');
+
+    expect(() => fileStateIO(dir).read()).toThrow();
+  });
+});

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）
@@ -46,6 +47,8 @@ H5（#44）起：
 - **一次命令运行内，同一份数据至多取一次（harness#146，#140 A 票；与 ADR-0023 同族，但不扩 `RunEnv` 公共面）**：`spec-baseline-check` 的三条验证路径（文件存在性 / 依赖 / 代码模式）一律从命令级共享索引 `createBaselineIndex(projectPath)` 取数，不再各自裸调 `fs`——全仓 `.ts`/`.js` 内容扫描一遍建成 `路径 → 内容` 表、`package.json` 读解析一次（**读取失败态同样入库**，不逐条重试）、同一落点的存在性探测只 stat 一次；逐条前置与每个关键词只在索引上重放判定。索引**懒建**（没有前置需要某类数据时该类读取一次都不发生）、**运行结束即弃**（不跨命令复用：本命令是独立命令而非 `harness check` 的子步骤，「同一口径取一次」命令内自足即够，#140 triage 裁决 5）。改前代价 = 前置条件数 × 关键词数 × 源文件数，改后与条数无关，判定/证据文案/stdout/退出码逐字不变。**驻留上界（harness#162）**：索引容量有双上限 `SOURCE_INDEX_MAX_ENTRIES = 5000` / `SOURCE_INDEX_MAX_BYTES = 64MB`——超任一上限即放弃驻留、**回落逐文件流式读**（每个关键词重扫一遍，读完即弃），峰值内存由 O(全仓源码) 回到 O(单文件)，正常规模仓保留「一次遍历」收益；取数面相应由 `sourceContents(): Map` 改为 `countFilesContaining(keyword)`，容量策略全部收在索引内部。机器可检：`__tests__/spec-baseline-read-count.test.ts`（形状照 `check-read-count.test.ts`：`readFileSync`·只读 `openSync`·`existsSync`·`readdirSync` 记件 + 整张读取表与目录扫描表逐条冻结 + 「同一份数据的同一口径至多取一次」+ N×K 缩放不变式 + 懒建不扫 + 失败态入库）+ `__tests__/spec-baseline-index-cap.test.ts`（驻留上界闸：上限内每文件至多读一遍、超条目/字节上限回落流式且判定不变）
 - **先判定「本次要什么」再决定「读什么」，且清单顺序是对外面（harness#147，#140 B 票）**：`sync-docs/index.ts` 把 CAPABILITIES.md 的**格式判定放在源码扫描之前**——capability-listing 格式的判定面是计数、不做条目级比对，模块清单在本次运行里无人消费，于是整棵源码树**一份 `.ts` 内容都不读**（改造前是无条件全树逐文件 `await readFile`，只为首行注释）。要描述的分支（file-table）照旧取描述，但 `project-reader.ts` 分两步：先按目录遍历序定清单，再经 `extractFileDescriptions()` **并发**取数（上限固定 16，按票下裁决不做成配置面）并**按原索引回填**。清单顺序对外可见（`--check` 逐行比对生成的表格、人看 diff），票下裁决是「顺序逐字保持现状、不改字典序」，故「按并发完成顺序 append」属行为漂移而非优化。读盘次数之外一切不变：判定、漂移检测、写回内容逐字保持。机器可检：`__tests__/sync-docs-read-count.test.ts`（形状照 `check-read-count.test.ts`——listing 模式 `.ts` 内容读 = 0 + file-table 反证每份文件恰读一次 + 整张读取表冻结）、`sync-docs/__tests__/module-descriptions.test.ts`（替身把「起始序」与「完成序」刻意错开：串位或重排即红，另钉上限）、`__tests__/sync-docs-module-order.test.ts`（生成表格行序 = 目录遍历序、两次运行逐字复现）
 
+- **撤登记要整行删，排版判定与修复共用一份正本（harness#171）**：`capabilities-syncer.ts` 删幽灵行此前是 `content.replace(/^\|…$/gm, '')`——`m` 下 `^…$` 只框住行内容、**不含行尾换行**，删完留一个空行；CommonMark 以空行断表，于是每撤一次登记就把一张能力表多切一刀（studio 存量攒到 40 处）。同函数末尾的 `\n{3,}→\n\n` 救不了它：删一行只产两个换行，够不着阈值（删相邻两行也不变好——只是把两刀并成一刀）。现行形状：① 删除按行 split/filter/join，行尾随之消失（CRLF 一并处理，正则尾上加 `\r?` 保持与旧 `m` 相同的匹配面）；② 排版收拢正本是 `normalizeCapabilitiesTableLayout(content)`——规则①删两侧都是表格行的空行段、规则②收掉无数据行的表头/分隔行，**表格外的段落空行不动**，且**两条规则互相制造触发点**（①吃掉两张空表之间那个空行后，②在同一轮只收得掉后一张），故**跑到不动点**：一次 `sync-docs` 必须把 `--check` 报出来的全清掉，否则下游 CI 修完还红；③ 原有的一处 `\n{3,}→\n\n` 由「增删之后」移到**收拢之后**（收掉一张夹在两段散文之间的空表本身会新产 `\n\n\n`，留在前面就漏折叠），并删掉增删分支内那份重复折叠。围栏代码块（``` / ~~~）内的行在**排版收拢一侧整体豁免**（CAPABILITIES.md 是手写文档，块内长得像表格的示例行不是脏行：不给豁免时一块「表头+分隔行」示例被判空表删掉正文、`--check` 还为此判红）——但**幽灵行删除一侧刻意不豁免**，两侧口径故意不同：登记条目由 `core/constraints/capabilities-parser` 全文扫描得出（ADR-0009），围栏内的行同样算登记项，只让删除认围栏而条目不认，块内示例引用的已删文件会永远报成幽灵条目且 `--check` 修不掉（机器可检：「围栏内示例行引用已删文件」用例同时钉收敛与「只吃掉那一行、块内其余正文留着」）。让两侧同认围栏 = 改 ADR-0009 的登记面并连带影响 docs_freshness 判定，另票裁决。`--check` 的判定面就是「它返回的内容与入参是否不同」，写模式在**增删之后**调用收拢（先收拢会误删「本轮要往空表里补新行」的表头），故 check 报得出、fix 必清得掉（不重演 2026-08-04 studio PR #44 的「check 永不收敛」）。机器可检：`__tests__/sync-docs-table-layout.test.ts`（13 例：中间行/末行/目录条目行/CRLF 四种撤登形状 + 存量脏行 check 判红后写模式转绿 + 空表收掉 + 两张空表相邻一次收干净 + 收拢后不留三连换行 + 四条反向闸「有新行不误删表头」「表格外空行不动」「代码块内空表不被收」「代码块内表格样式行不被收拢」）
+
 ## 注意事项
 - 新增命令需同步更新 CLAUDE.md / CAPABILITIES.md / src/CONTEXT.md
 - **scaffold 三态模型（harness#132 已落地）**：init/validate 的「目标在不在场→写或告知」判定（9 站点 = init 7 + validate 2，#132 收口时 8 处）收口为 scaffold 模块。术语：**managed file**（受管文件）= harness 模板拥有正本、用户可持有的落盘文件；三态 = `created`（不在场→落盘）/ `exists`（在场→告知跳过，**不细分内容是否等于模板**，内容比较是独立特性）/ `manual`（在场→打印片段请用户手工合并）。纪律：scaffold 不持有覆盖/跳过策略（`--no-git-hooks`/`--no-github-actions` 由命令层翻成 plan 列表，scaffold 只见 plan）；模板留代码内住 `scaffold-templates.ts`，不落 `templates/`（其无运行时消费者、integrity 清单不覆盖）；**打印给用户的片段必须是落盘正文的一部分**（GH Actions 站点冲突分支打印完整 workflow 全文而非 job 片段，#103 判据）；`--print-snippets` 的片段视图同判据且**由正本裁剪派生**（harness#153：`GITHUB_ACTIONS_SNIPPET` = `HARNESS_CHECK_WORKFLOW` 的 `jobs:` 段之后，形状与 GitLab 侧「打印的是落盘正文的尾巴」对仗。它曾是手抄的第二份文本，比落盘正本少 `validate` / `passes-gate` 两道门禁——照抄的用户拿到比同版本 `harness init` 弱一半的 CI；引导语随之改准为「以下正文取自 harness-check.yml 的 job 段」，`--print-snippets` 旗帜本身保留）；gitlab 形同判据由 harness#157 补齐——`printSnippets` 收 `governanceLevel`、打 `renderGitLabCiJobs(governanceLevel)`，与落盘 / 冲突分支同一个正本函数（此前打无 level 的 `GITLAB_CI_SNIPPET`，`-g` 档照抄的用户静默少拿治理与 docs 新鲜度两个任务）；CLAUDE.md/AGENTS.md 标记化幂等写（读-改-写形状）不纳入 scaffold；死选项 `-t/--type` 已随本票删除。GitLab CI 接线决议见下条；pre-push 站点已随 harness#144 落地，见「本地防线两道」条
@@ -75,3 +78,4 @@ H5（#44）起：
 - **本目录零 `process.exit` / `process.exitCode`**：kind → 退出码的唯一映射在 `bin/harness.js`（`ok`/`skip` → 0，`fail`/`usage-error` → 1，未知 kind fail-closed）。历史上两处条件式（`command --level` 按严重级、门禁按 passed）已由命令侧译成 kind；`sync-docs --check` 的漂移改由实现返回 `fail`（定义表的 `afterRun` 逃生门随之废除）
 - **输出不得直接用 console**：流式打印走 `log(io, …)` / `logError(io, …)`（`util.format` + 换行，与 console 逐字节等价，见 `src/cli/__tests__/command-contract.test.ts`）；测试断言输出用 `captureIO()`，不再 `spyOn(process, 'exit')`；`--json` 输出断言用 `lastJsonOutput(io)`（JSON.parse 正本，harness#108）。例外：`constraints retire` 交互正文仍走 console（其 `RetireIO` 只注入 readline 流），退役结果打印已接注入流
 - **#95 同型扫荡结论**：两门禁站点已修（`passes-gate` 执行/证据落 projectPath、`acceptance` 去掉 `tasksPath: './tasks.yml'` 相对默认值）。逐点判定后的豁免四处，理由与站点原文一起冻结在 `__tests__/project-path-convention.test.ts` 的豁免表：`release` 的 `pkgPath`（定义表本无 `-p`，pkgPath 就是该命令唯一的根且已逐个传给每条 `run(cmd, pkgPath)`，不构成半失效；给发布流水线新增 `-p` 属新能力）、`command` 的 `evaluate({ projectPath: process.cwd(), … })`（`CommandGate` 只做命令串正则判定、零文件读写，且该命令定义表里没有 `-p`，取 cwd 仅为满足 `GateContext` 形状，架构评审候选1）、`constraints` 的 `join(process.cwd(), 'package.json')`（报的是 harness 自身包版本，主锚 `__dirname`，cwd 仅兜底）、`core/spec/validator.ts` 的 `schemaPath: './specs/schemas'`（**确是同型病灶**：`validateAll(projectPath)` 用 projectPath 找 spec 文件、却用 cwd 找 schema；但 `validateFile`/`loadSchema` 签名里没有根，补齐要穿透整个 spec 域，留待 spec 单票收口）
+- **另知：CAPABILITIES.md 排版面两处已知限制（harness#171 未修）**：① 收拢的围栏豁免只认 ` ``` ` / `~~~` 标记行，**4 空格以上缩进的代码块不豁免**（触发条件：手写 CAPABILITIES.md 用缩进而非围栏放表格示例，块内空行会被当排版脏行收掉）——缩进 ≥4 在 CommonMark 里与「缩进表格」本身歧义，现有豁免取保守侧（宁可少动），要收口得连 `TABLE_ROW_REGEX` 的缩进上界一起定；② **module 模式下整张表被收空后，下一次写会走「无表格」分支自动补一整张目录表**（`updateCapabilitiesFile` 的 `existingFiles.length === 0` else 分支），与同文件「目录条目需人工策划登记」的约定冲突——非 #171 引入（撤登记前留下的「空行 + 表头」形状经 `parseCapabilitiesFiles` 同样解析为空集，实测两版行为一致），且登记面认不认围栏要连 ADR-0009 一起裁决，另票。

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__/registry.test.ts

@@ -15,6 +15,7 @@ import * as path from 'path';
 import { spawnSync } from 'child_process';
 import { COMMAND_DEFINITIONS, type CommandDefinition, type CommandImplRef } from '../definitions';
 import { GATE_DEFINITIONS } from '../../../gates/definitions';
+import { FileKnowledgeStore } from '../../../knowledge/store';
 
 function collectRefs(defs: CommandDefinition[]): CommandImplRef[] {
   const refs: CommandImplRef[] = [];
@@ -189,8 +190,17 @@ const hasDist = fs.existsSync(distCommands);
  * 经 NODE_OPTIONS=--require 预加载探针 spawn bin（进程退出时打印加载的
  * 命令实现模块清单）。不用 node -e（commander 在 -e 下走 eval 分支，
  * argv 解析不同，会误判位置参数）。
+ *
+ * env 用于把命令指向临时夹具（见「别名子命令」用例），第二参随调用方并入。
+ * maxBuffer 显式抬高：spawnSync 缺省 1MB，子进程 stdout 超限是被 ENOBUFS **杀掉**
+ * 而非报错——status 变 null、stderr 一句解释都没有，看着像路由崩了。2026-09-20 本机
+ * 发版即以此形状暴露（真实库 221 条 / 1.35MB JSON）。抬高上限只是别再吞掉诊断信息，
+ * **数据面隔离仍由各用例的夹具负责**，不拿它当免罪符。
  */
-function runWithModuleProbe(argv: string[]): { status: number | null; implModules: string[]; stdout: string; stderr: string } {
+function runWithModuleProbe(
+  argv: string[],
+  extraEnv: Record<string, string> = {},
+): { status: number | null; implModules: string[]; stdout: string; stderr: string } {
   const probeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-lazy-probe-'));
   const probeFile = path.join(probeDir, 'probe.js');
   fs.writeFileSync(probeFile, [
@@ -204,7 +214,8 @@ function runWithModuleProbe(argv: string[]): { status: number | null; implModule
       cwd: repoRoot,
       encoding: 'utf-8',
       timeout: 30000,
-      env: { ...process.env, NODE_OPTIONS: `--require ${probeFile}` },
+      maxBuffer: 32 * 1024 * 1024,
+      env: { ...process.env, NODE_OPTIONS: `--require ${probeFile}`, ...extraEnv },
     });
     const match = r.stderr.match(/IMPL_MODULES=(.*)/);
     return {
@@ -270,7 +281,32 @@ smoke('bin/harness.js 端到端（dist 存在时）', () => {
   });
 
   it('别名子命令解析到同一实现（knowledge ls = list，候选7）', () => {
-    const r = runWithModuleProbe(['knowledge', 'ls', '--json']);
+    // 数据面隔离：本用例判的是**路由**（别名 ls 与主名 list 命中同一实现、只加载 knowledge
+    // 侧两个模块），知识库内容纯属旁证。不指夹具时它读的是操作机的真实库（本机实测 221 条 /
+    // 1.35MB JSON），而 CI 全新 checkout 上该库为空——两侧取数规模差三个数量级，大的一侧
+    // stdout 越过 spawnSync 缺省缓冲直接被杀掉（形状见 runWithModuleProbe 注释）。
+    // 夹具目录由 src/test-setup/mkdtemp-cleanup.ts 在 afterAll 统一回收。
+    const kbDir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-smoke-kb-'));
+    new FileKnowledgeStore({ baseDir: kbDir }).save({
+      id: 'SMOKE-001',
+      type: 'guideline',
+      title: 'Smoke Fixture Entry',
+      content: '别名路由用例的夹具条目，只为了让 --json 出口有真实记录可数',
+      maturity: 'verified',
+      layer: 'project',
+      created: new Date().toISOString(),
+      lastReferenced: new Date().toISOString(),
+      contributors: ['tester'],
+      projects: ['smoke'],
+      tags: [],
+      applicablePhases: [],
+      sourceReferences: [],
+      referencedBy: [],
+      executionResults: [],
+      consumptionMode: 'reference',
+      origin: 'system',
+    });
+    const r = runWithModuleProbe(['knowledge', 'ls', '--json'], { KNOWLEDGE_BASE_DIR: kbDir });
     expect(r.status).toBe(0);
     expect(JSON.parse(r.stdout)).toHaveProperty('total');
     expect(r.implModules).toEqual([

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%');
     });