@dommaker/harness 1.7.0 → 1.8.1

package/dist/utils/jsonl.js

@@ -12,9 +12,12 @@
  * 也不反转既有容错调用点的语义。坏行指非空但 JSON.parse 失败的行
  * （半写入截断、手工编辑、磁盘满等）。
  *
- * tail / head：只解析尾部 / 头部 N 个非空行（文件仍全量读取，parse 才是大头），
- * 供「只看最近 K 条」的调用点避免全量 parse（check 等热路径）。
- * countJsonlLines 供纯计数消费方（完全不 parse）。
+ * tail：从文件末尾倒着分块 seek，只把够数的尾部行读进内存。2026-09-14 量数据推翻本文件
+ * 早先「文件仍全量读取，parse 才是大头」的断言：6.7MB / 32723 行的 traces.log 上，
+ * 完全不 parse 的整读单次仍 16.6–21.1ms——成本在 split('\n') 与空白行过滤。
+ * head：从文件头正向分块读，够数即停——供「有没有至少 N 条」这类阈值消费方，不再为
+ * 一个比较符把全文捞进内存。
+ * 两者同给或都不给时才整读后截断（head→tail 顺序即既有语义）。
  *
  * 计数去向（harness#100）：本模块是坏行计数的唯一正本，但正本≠终点——凡以 'skip'
  * 策略读，调用点必须把 skippedLines 带到该消费面的用户可见输出（CLI 走 stderr，
@@ -67,7 +70,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readJsonl = readJsonl;
-exports.countJsonlLines = countJsonlLines;
+exports.readJsonlWindow = readJsonlWindow;
 exports.readJsonlEnds = readJsonlEnds;
 exports.appendJsonl = appendJsonl;
 const fs = __importStar(require("fs"));
@@ -81,19 +84,111 @@ function readNonEmptyLines(filePath) {
         .split('\n')
         .filter(line => line.trim().length > 0);
 }
+/** tail 倒读的分块大小：trace 行约 200B，一块即够几十行 */
+const TAIL_CHUNK_BYTES = 64 * 1024;
+/** head 正读的分块大小 */
+const HEAD_CHUNK_BYTES = 64 * 1024;
 /**
- * 读取 JSONL 文件：exists → read → split → parse → filter（正本读链）
+ * 从文件头正向分块读，只返回前 want 个非空行（够数即停，不整读）
  *
- * policy 必填无缺省（裁决 1）；缺文件返回空结果，不抛。
+ * 与「整读后 slice(0, want)」逐字同语义：行以 `\n` 界定，末块无尾换行时整段收尾算一行，
+ * 纯空白行不计数。块边界切在多字节字符中间时，残段按字节留在缓冲里等下一块拼齐再解码。
+ * 供「有没有至少 N 条记录」这类阈值消费方——它要的是够不够，不是总数。
  */
-function readJsonl(filePath, policy, options) {
-    let lines = readNonEmptyLines(filePath);
-    if (options?.head !== undefined) {
-        lines = options.head > 0 ? lines.slice(0, options.head) : [];
+function readHeadNonEmptyLines(filePath, want) {
+    if (want <= 0)
+        return [];
+    if (!fs.existsSync(filePath))
+        return [];
+    const fd = fs.openSync(filePath, 'r');
+    try {
+        const size = fs.fstatSync(fd).size;
+        const kept = [];
+        let acc = Buffer.alloc(0);
+        let pos = 0;
+        while (kept.length < want) {
+            const end = Math.min(size, pos + HEAD_CHUNK_BYTES);
+            if (end > pos) {
+                const chunk = Buffer.alloc(end - pos);
+                fs.readSync(fd, chunk, 0, end - pos, pos);
+                acc = Buffer.concat([acc, chunk]);
+            }
+            let cursor = 0;
+            for (let i = 0; i < acc.length && kept.length < want; i++) {
+                if (acc[i] !== 0x0a)
+                    continue;
+                const line = acc.subarray(cursor, i).toString('utf-8');
+                if (line.trim().length > 0)
+                    kept.push(line);
+                cursor = i + 1;
+            }
+            if (end >= size) {
+                // 读到文件末尾：最后一段没有换行收尾，但它就是一行
+                if (kept.length < want && cursor < acc.length) {
+                    const last = acc.subarray(cursor).toString('utf-8');
+                    if (last.trim().length > 0)
+                        kept.push(last);
+                }
+                break;
+            }
+            pos = end;
+            acc = acc.subarray(cursor);
+        }
+        return kept;
     }
-    if (options?.tail !== undefined) {
-        lines = options.tail > 0 ? lines.slice(-options.tail) : [];
+    finally {
+        fs.closeSync(fd);
     }
+}
+/**
+ * 从文件末尾倒着分块读，只返回末尾 want 个非空行（文件顺序）
+ *
+ * 与「整读后 slice(-want)」逐字同语义：行以 `\n` 界定，末行允许无换行，`\r` 随行进文本，
+ * 纯空白行不计数。左侧残段（块边界切在多字节字符中间）不解码，按字节留到下一轮——
+ * UTF-8 的多字节序列不含 0x0a，故按 `\n` 切字节再解码不会破坏字符。
+ */
+function readTailNonEmptyLines(filePath, want) {
+    if (want <= 0)
+        return [];
+    if (!fs.existsSync(filePath))
+        return [];
+    const fd = fs.openSync(filePath, 'r');
+    try {
+        let pos = fs.fstatSync(fd).size;
+        let acc = Buffer.alloc(0);
+        for (;;) {
+            const start = Math.max(0, pos - TAIL_CHUNK_BYTES);
+            if (pos > start) {
+                const chunk = Buffer.alloc(pos - start);
+                fs.readSync(fd, chunk, 0, pos - start, start);
+                acc = Buffer.concat([chunk, acc]);
+            }
+            pos = start;
+            const lines = [];
+            let cursor = pos === 0 ? 0 : -1;
+            for (let i = 0; i < acc.length; i++) {
+                if (acc[i] !== 0x0a)
+                    continue;
+                if (cursor >= 0)
+                    lines.push(acc.subarray(cursor, i).toString('utf-8'));
+                cursor = i + 1;
+            }
+            if (cursor >= 0 && cursor < acc.length)
+                lines.push(acc.subarray(cursor).toString('utf-8'));
+            const kept = lines
+                .filter(line => line.trim().length > 0)
+                .slice(-want);
+            // 已到文件头 → 全部行都在手里；否则末尾 want 个非空行已凑齐，左侧只可能是更早的行
+            if (pos === 0 || kept.length >= want)
+                return kept;
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** parse 非空行文本（读链的末段；坏行策略同 readJsonl） */
+function parseJsonlLines(lines, policy) {
     const records = [];
     let skippedLines = 0;
     for (const line of lines) {
@@ -109,13 +204,45 @@ function readJsonl(filePath, policy, options) {
     return { records, skippedLines };
 }
 /**
- * 统计非空行数（含坏行，完全不 parse）
+ * 读取 JSONL 文件：exists → read → split → parse → filter（正本读链）
  *
- * 供只关心记录条数的调用点（如 check 智能提示）避免全量 parse；
- * 缺文件返回 0。
+ * policy 必填无缺省（裁决 1）；缺文件返回空结果，不抛。
+ * 只给 head 走有界正读、只给 tail 走倒读 seek；两者同给或都不给走整读后截断
+ * （head→tail 的截断顺序即既有语义）。
  */
-function countJsonlLines(filePath) {
-    return readNonEmptyLines(filePath).length;
+function readJsonl(filePath, policy, options) {
+    let lines;
+    if (options?.head !== undefined && options.tail === undefined) {
+        lines = readHeadNonEmptyLines(filePath, options.head);
+    }
+    else if (options?.tail !== undefined && options.head === undefined) {
+        lines = readTailNonEmptyLines(filePath, options.tail);
+    }
+    else {
+        lines = applyHeadTail(readNonEmptyLines(filePath), options);
+    }
+    return parseJsonlLines(lines, policy);
+}
+function readJsonlWindow(filePath, policy, maxLines) {
+    const lines = readTailNonEmptyLines(filePath, maxLines);
+    return {
+        take: (limit) => {
+            if (limit > maxLines) {
+                throw new Error(`尾部窗口上限 ${maxLines} 行，无法取 ${limit} 行——建窗口时按最大消费方取值，或改上限（不静默少给）`);
+            }
+            return parseJsonlLines(limit > 0 ? lines.slice(-limit) : [], policy);
+        },
+    };
+}
+/** 整读路径上的 head → tail 截断（顺序即既有语义：先截头再截尾） */
+function applyHeadTail(lines, options) {
+    if (options?.head !== undefined) {
+        lines = options.head > 0 ? lines.slice(0, options.head) : [];
+    }
+    if (options?.tail !== undefined) {
+        lines = options.tail > 0 ? lines.slice(-options.tail) : [];
+    }
+    return lines;
 }
 /**
  * 只取首尾：首/末条合法记录 + 原始行数，parse 停在两端首个合法行

package/dist/utils/jsonl.js.map

@@ -1 +1 @@
-{"version":3,"file":"jsonl.js","sourceRoot":"","sources":["../../src/utils/jsonl.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"jsonl.js","sourceRoot":"","sources":["../../src/utils/jsonl.ts"],"names":[],"mappings":"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"}

package/dist/utils/numeric-flag.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 数值旗帜装配解析器（harness#154；口径正本 = src/cli/commands/CONTEXT.md
+ * 「数值旗帜装配口径（harness#152）」条目，本模块是该条目指名的唯一解析器）
+ *
+ * 背景：commander 给到命令侧的数值旗帜恒是字符串（`defaultValue: '50'` 也是），
+ * 数值只在装配点转一次，转不出来必须 fail-loud——下游兜底多是 `??`/`||`，
+ * NaN 穿透后比较恒 false，一道质量判定被静默关掉而退出码仍是 0（#152 病灶）。
+ * `parseInt`/`parseFloat` 不可用：它们前缀截断（'30abc'→30、'1e2'→1）同属静默误读。
+ *
+ * 两个消费形（同一条判定规则，不建第二套解析器）：
+ * - `requireNumericFlag`：定义表 `mapActionArgs` 装配点用，脏值抛 `NumericFlagError`，
+ *   bin/harness.js 捕获后映射 usage-error（非零退出）；
+ * - `parseNumericFlag`：命令模块入口装配点用（knowledge/failure/passes-gate），
+ *   返回值判别，就地 `logError` + `usage-error`。
+ */
+/** 数值形：int = 非负整数；float = 非负十进制（不收指数/符号/前后缀） */
+export type NumericFlagKind = 'int' | 'float';
+/** 装配结果：`ok: false` = 脏输入，由装配点 fail-loud（不得往判定槽塞 NaN） */
+export type NumericFlagAssembly = {
+    ok: true;
+    value?: number;
+} | {
+    ok: false;
+    raw: string;
+};
+/**
+ * 装配窄化：`undefined` = 未传（落下游缺省）；`'0'` 是显式零值，不当「未传」兜掉。
+ * 规则与 #152 `assembleShortContentThreshold` 同源：trim 后全数字（float 允许一段小数），
+ * 溢出 double 上限（→ Infinity）同脏值处理。
+ */
+export declare function parseNumericFlag(raw: string | undefined, kind: NumericFlagKind): NumericFlagAssembly;
+/** 报错文案模板：点名旗帜与原值（可定位），int/float 措辞一致收敛 */
+export declare function numericFlagMessage(flag: string, raw: string, kind: NumericFlagKind): string;
+/** 定义表装配失败的专用错误：bin/harness.js 凭它映射 usage-error（非零退出） */
+export declare class NumericFlagError extends Error {
+    constructor(message: string);
+}
+/**
+ * 定义表 `mapActionArgs` 装配点用：脏值抛 `NumericFlagError`。
+ * 定义表是纯数据模块，返回不了 CommandResult；退出码映射唯一出口在 bin，
+ * 故以抛出表达失败、bin 就地捕获映射，不新增第二条失败通道。
+ */
+export declare function requireNumericFlag(flag: string, raw: string | undefined, kind: NumericFlagKind): number | undefined;
+//# sourceMappingURL=numeric-flag.d.ts.map

package/dist/utils/numeric-flag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numeric-flag.d.ts","sourceRoot":"","sources":["../../src/utils/numeric-flag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,gDAAgD;AAChD,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,OAAO,CAAC;AAE9C,yDAAyD;AACzD,MAAM,MAAM,mBAAmB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5F;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,eAAe,GAAG,mBAAmB,CAQpG;AAED,2CAA2C;AAC3C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,CAE3F;AAED,yDAAyD;AACzD,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,IAAI,EAAE,eAAe,GACpB,MAAM,GAAG,SAAS,CAIpB"}

package/dist/utils/numeric-flag.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * 数值旗帜装配解析器（harness#154；口径正本 = src/cli/commands/CONTEXT.md
+ * 「数值旗帜装配口径（harness#152）」条目，本模块是该条目指名的唯一解析器）
+ *
+ * 背景：commander 给到命令侧的数值旗帜恒是字符串（`defaultValue: '50'` 也是），
+ * 数值只在装配点转一次，转不出来必须 fail-loud——下游兜底多是 `??`/`||`，
+ * NaN 穿透后比较恒 false，一道质量判定被静默关掉而退出码仍是 0（#152 病灶）。
+ * `parseInt`/`parseFloat` 不可用：它们前缀截断（'30abc'→30、'1e2'→1）同属静默误读。
+ *
+ * 两个消费形（同一条判定规则，不建第二套解析器）：
+ * - `requireNumericFlag`：定义表 `mapActionArgs` 装配点用，脏值抛 `NumericFlagError`，
+ *   bin/harness.js 捕获后映射 usage-error（非零退出）；
+ * - `parseNumericFlag`：命令模块入口装配点用（knowledge/failure/passes-gate），
+ *   返回值判别，就地 `logError` + `usage-error`。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NumericFlagError = void 0;
+exports.parseNumericFlag = parseNumericFlag;
+exports.numericFlagMessage = numericFlagMessage;
+exports.requireNumericFlag = requireNumericFlag;
+/**
+ * 装配窄化：`undefined` = 未传（落下游缺省）；`'0'` 是显式零值，不当「未传」兜掉。
+ * 规则与 #152 `assembleShortContentThreshold` 同源：trim 后全数字（float 允许一段小数），
+ * 溢出 double 上限（→ Infinity）同脏值处理。
+ */
+function parseNumericFlag(raw, kind) {
+    if (raw === undefined)
+        return { ok: true };
+    const text = raw.trim();
+    const pattern = kind === 'int' ? /^\d+$/ : /^\d+(\.\d+)?$/;
+    if (!pattern.test(text))
+        return { ok: false, raw };
+    const value = Number(text);
+    if (!Number.isFinite(value))
+        return { ok: false, raw };
+    return { ok: true, value };
+}
+/** 报错文案模板：点名旗帜与原值（可定位），int/float 措辞一致收敛 */
+function numericFlagMessage(flag, raw, kind) {
+    return `错误：${flag} 需要非负${kind === 'int' ? '整数' : '数值'}，收到 "${raw}"`;
+}
+/** 定义表装配失败的专用错误：bin/harness.js 凭它映射 usage-error（非零退出） */
+class NumericFlagError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NumericFlagError';
+    }
+}
+exports.NumericFlagError = NumericFlagError;
+/**
+ * 定义表 `mapActionArgs` 装配点用：脏值抛 `NumericFlagError`。
+ * 定义表是纯数据模块，返回不了 CommandResult；退出码映射唯一出口在 bin，
+ * 故以抛出表达失败、bin 就地捕获映射，不新增第二条失败通道。
+ */
+function requireNumericFlag(flag, raw, kind) {
+    const result = parseNumericFlag(raw, kind);
+    if (!result.ok)
+        throw new NumericFlagError(numericFlagMessage(flag, result.raw, kind));
+    return result.value;
+}
+//# sourceMappingURL=numeric-flag.js.map

package/dist/utils/numeric-flag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"numeric-flag.js","sourceRoot":"","sources":["../../src/utils/numeric-flag.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAaH,4CAQC;AAGD,gDAEC;AAeD,gDAQC;AAzCD;;;;GAIG;AACH,SAAgB,gBAAgB,CAAC,GAAuB,EAAE,IAAqB;IAC7E,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IAC3C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACxB,MAAM,OAAO,GAAG,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;IAC3D,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IACnD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IACvD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED,2CAA2C;AAC3C,SAAgB,kBAAkB,CAAC,IAAY,EAAE,GAAW,EAAE,IAAqB;IACjF,OAAO,MAAM,IAAI,QAAQ,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,QAAQ,GAAG,GAAG,CAAC;AACtE,CAAC;AAED,yDAAyD;AACzD,MAAa,gBAAiB,SAAQ,KAAK;IACzC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AALD,4CAKC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB,CAChC,IAAY,EACZ,GAAuB,EACvB,IAAqB;IAErB,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,IAAI,gBAAgB,CAAC,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;IACvF,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dommaker/harness",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "description": "通用工程约束框架 - 铁律系统、检查点验证、测试门控",
   "keywords": [
     "harness",

package/src/CONTEXT.md

@@ -4,7 +4,7 @@
 通用工程约束框架的 TypeScript 核心代码。定义约束系统、检查点验证、质量门控、知识基础设施。
 
 ## 核心导出 (dist/)
-- `index.ts`: 显式公共导出清单（ADR-0003，禁 export *）
+- `index.ts`: 显式公共导出清单（ADR-0003，禁 export *；harness#137 起该禁令由 `src/__tests__/sub-barrels-explicit.test.ts` 扩到 src 下全部目录 barrel，豁免逐文件记名）
 - `core/index.ts`: 核心约束引擎
 - `presets/index.ts`: 预设纯数据（strict/standard/relaxed；筛选逻辑统一在 core mergeConstraints）
 - `context/index.ts`: 上下文管理
@@ -41,13 +41,16 @@
 | 守卫 guard | 仅 dsh 借鉴语境（工具管线单调守卫），不进入 harness 命名 |
 | 回滚 | 分工：版本化回退（单段——yml 数据文件 git 版本化，删段恢复）+ 提案回滚（多段 inverse，挂 studio#82 D6） |
 | 文件驱动 CLI | yml 状态真值 + 一次性进程、无常驻生命周期；故不引 dispose 链（止步档 1） |
-| 对照（reconcile） | CAPABILITIES.md 声明与源码实况的双向一致性判定（代码→文档查漏登，文档→代码查幽灵）；唯一实现 `core/constraints/capabilities-reconcile.ts`，capability_sync / docs_freshness / sync-docs 共消费（ADR-0009） |
+| 对照（reconcile） | CAPABILITIES.md 声明与源码实况的双向一致性判定（代码→文档查漏登，文档→代码查幽灵）；唯一实现 `core/constraints/capabilities-reconcile.ts`，capability_sync / docs_freshness / sync-docs 共消费（ADR-0009）。一次 check run 内只算一次，经 `RunEnv.capabilities()` 供给两 checker（ADR-0023 决策 4） |
 | 判定证据（evidence） | checker 随判定一并返回的路径级依据（`CheckDetail{pass, evidence}`，harness#119/ADR-0016）；文案由 checker 措辞、消费端只打印，出口 = `ConstraintResult` / CLI 输出 / trace / 铁律异常文案。不是第四种统计态：**违规** = 与本次变更有因果（进 pass/fail 分母），**提示** = `pass:true` + evidence（仓库级漂移等无因果缺口，只露出不拦） |
 | 测试产物解读（test-output） | 从测试运行器 stdout 读出「过了没 / 哪些失败 / 覆盖率」的判定；唯一实现 `core/validators/test-output.ts`（包内，不进导出面），passes-gate / acceptance 共消费（ADR-0012）。两门禁判定依据不一致待 #93 裁决，覆盖率取数归属待 #94 裁决 |
 | 飞轮指标（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 实现 `fileStateIO(projectPath)`、命令可选参数注入（照 `CommandIO` 模式，但不扩 `CommandIO`）；唯一实现 `src/cli/state-io.ts`（cli 层，不进包根导出面），收编 check 智能提示与 status 两个写者，写语义统一为**读-改-写**（此前 `status` 不读就整文件重写、把 `check` 写的 `shownHints` 抹掉致提示去重失效，ADR-0026 已修）。决策 = **ADR-0026**，实现票 #148；与运行级观察面（只读、项目上行数据）分工：本面管 harness 自身状态、含写 |
 
 ## 注意事项
 - 公共包，禁止硬编码业务路径
 - 约束定义在 `core/constraints/definitions/{iron-laws,guidelines,prompts}.ts`，不应在运行时代码中定义
 - `bin/` 只有 CLI 入口发布到 npm
+- `__tests__` 的文件系统夹具根一律经 `fs.mkdtempSync` 取每轮唯一目录（缺省父目录 = tmpdir；被测语义本身是 cwd 相对解析的，才显式 opt-out 留在 cwd），固定名会在并发/被 kill 的运行之间互删或被复用成脏夹具；闸 = `__tests__/test-fixture-hygiene.test.ts`（harness#145）

package/src/__tests__/acceptance-gate.test.ts

@@ -8,15 +8,18 @@ import { SpecAcceptanceGate } from '../gates/acceptance';
 import { createSpecAcceptanceGate } from '../gates/index';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 import * as yaml from 'js-yaml';
 
 describe('SpecAcceptanceGate', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-acceptance');
-  const tasksFile = path.join(tempDir, 'tasks.yml');
-  const customTasksFile = path.join(tempDir, 'custom-tasks.yml');
+  let tempDir: string;
+  let tasksFile: string;
+  let customTasksFile: string;
 
   beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-acceptance-'));
+    tasksFile = path.join(tempDir, 'tasks.yml');
+    customTasksFile = path.join(tempDir, 'custom-tasks.yml');
   });
 
   afterAll(() => {

package/src/__tests__/checker-extra.test.ts

@@ -18,15 +18,16 @@ import { contextEvidenceFlag } from '../core/constraints/checkers/types';
 import type { ConstraintContext } from '../types/constraint';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 import { execSync } from 'child_process';
 
 describe('ConstraintChecker - 补充覆盖', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-checker-extra');
+  let tempDir: string;
   const checker = ConstraintChecker.getInstance();
 
   beforeAll(() => {
     // 创建临时 git 仓库
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-checker-extra-'));
     execSync('git init', { cwd: tempDir });
     execSync('git config user.email "test@test.com"', { cwd: tempDir });
     execSync('git config user.name "Test"', { cwd: tempDir });

package/src/__tests__/checker.test.ts

@@ -9,16 +9,17 @@
 import { ConstraintChecker, checkConstraint } from '../core/constraints/checker';
 import { PROMPTS } from '../core/constraints/definitions';
 import type { ConstraintContext } from '../types/constraint';
-import { writeFileSync, mkdirSync, rmSync } from 'fs';
+import { writeFileSync, rmSync, mkdtempSync } from 'fs';
 import { join } from 'path';
+import { tmpdir } from 'os';
 
 describe('ConstraintChecker', () => {
   const checker = ConstraintChecker.getInstance();
-  const tempDir = join(process.cwd(), 'temp-test-checker');
+  let tempDir: string;
 
   beforeAll(() => {
     // 创建临时测试目录
-    mkdirSync(tempDir, { recursive: true });
+    tempDir = mkdtempSync(join(tmpdir(), 'temp-test-checker-'));
   });
 
   afterAll(() => {

package/src/__tests__/checkpoint.test.ts

@@ -4,15 +4,16 @@
 
 import { describe, it, expect, beforeAll, afterAll } from '@jest/globals';
 import { CheckpointValidator } from '../core/validators/checkpoint';
-import { mkdirSync, rmSync, writeFileSync } from 'fs';
+import { rmSync, writeFileSync, mkdtempSync } from 'fs';
 import { join } from 'path';
+import { tmpdir } from 'os';
 
 describe('CheckpointValidator', () => {
-  const tempDir = join(process.cwd(), 'temp-test-checkpoint');
+  let tempDir: string;
   let validator: CheckpointValidator;
 
   beforeAll(async () => {
-    mkdirSync(tempDir, { recursive: true });
+    tempDir = mkdtempSync(join(tmpdir(), 'temp-test-checkpoint-'));
     validator = CheckpointValidator.getInstance();
     // 创建测试文件
     writeFileSync(join(tempDir, 'test.txt'), 'hello world');
@@ -568,34 +569,50 @@ describe('CheckpointValidator', () => {
       afterEach(() => { globalThis.fetch = fetch; });
 
       it('fetch 网络错误应该返回失败', async () => {
-        globalThis.fetch = (() => Promise.reject(new Error('Network error'))) as any;
+        const attempts: string[] = [];
+        globalThis.fetch = ((url: string) => {
+          attempts.push(String(url));
+          return Promise.reject(new Error('Network error'));
+        }) as any;
+        const waits: number[] = [];
         const result = await CheckpointValidator.getInstance().validate(
           {
             id: 'cp-hs-fail',
             checks: [{ id: 'c-hs-fail', type: 'http_status', config: { url: 'https://example.com', expectedStatus: 200 } }],
           },
-          { workdir: tempDir, projectPath: tempDir }
+          // 注入零等待 sleep：重试语义照旧断言，不再真烧 2+4+6s（工单 #136）
+          { workdir: tempDir, projectPath: tempDir, sleep: async (ms: number) => { waits.push(ms); } }
         );
         expect(result.passed).toBe(false);
         expect(result.checks[0].message).toContain('请求失败');
-      }, 20_000); // retry logic adds 2+4+6s delay
+        expect(attempts).toHaveLength(4);
+        expect(waits).toEqual([2000, 4000, 6000]);
+      });
     });
 
     describe('http_body 请求失败', () => {
       afterEach(() => { globalThis.fetch = fetch; });
 
       it('fetch 网络错误应该返回失败', async () => {
-        globalThis.fetch = (() => Promise.reject(new Error('Network error'))) as any;
+        const attempts: string[] = [];
+        globalThis.fetch = ((url: string) => {
+          attempts.push(String(url));
+          return Promise.reject(new Error('Network error'));
+        }) as any;
+        const waits: number[] = [];
         const result = await CheckpointValidator.getInstance().validate(
           {
             id: 'cp-hb-fail',
             checks: [{ id: 'c-hb-fail', type: 'http_body', config: { url: 'https://example.com', expected: 'test' } }],
           },
-          { workdir: tempDir, projectPath: tempDir }
+          // 注入零等待 sleep：重试语义照旧断言，不再真烧 2+4+6s（工单 #136）
+          { workdir: tempDir, projectPath: tempDir, sleep: async (ms: number) => { waits.push(ms); } }
         );
         expect(result.passed).toBe(false);
         expect(result.checks[0].message).toContain('请求失败');
-      }, 20_000);
+        expect(attempts).toHaveLength(4);
+        expect(waits).toEqual([2000, 4000, 6000]);
+      });
     });
 
     describe('output_contains JSON 输出', () => {

package/src/__tests__/context-files-resolution.test.ts

@@ -2,16 +2,17 @@
  * resolveContextFiles 三态访问器测试（工单 84）
  *
  * 测试面 = project-config-loader 上的 governance.context_files 访问器：
- * 未配置 / enabled 但无目标 / enabled 且非空 三态可分辨；访问器基于
- * loadRawProjectConfig 的进程级 memoize，不触发第二次 yaml 解析。
- * 临时目录由 src/test-setup/mkdtemp-cleanup.ts 统一回收。
+ * 未配置 / enabled 但无目标 / enabled 且非空 三态可分辨；访问器的 config.yml
+ * 读取由运行级观察面供给（ADR-0023 决策 2：同一枚 RunEnv 内不触发第二次解析，
+ * 进程级缓存已撤销）。临时目录由 src/test-setup/mkdtemp-cleanup.ts 统一回收。
  */
 
 import { describe, it, expect, jest } from '@jest/globals';
 import * as fs from 'fs';
 import * as path from 'path';
 import { resolveContextFiles, loadRawProjectConfig } from '../core/project-config-loader';
-import { createProjectFixture } from '../test-setup/project-fixture';
+import { createRunEnv } from '../core/constraints/run-env';
+import { createProjectFixture, writeProjectConfig } from '../test-setup/project-fixture';
 
 // ts-jest 的 namespace 导入属性不可重定义（jest.spyOn 会抛），改为只包一层
 // readFileSync 的部分 mock——其余 fs 能力用真实实现，fixture 搭建不受影响。
@@ -94,23 +95,36 @@ describe('resolveContextFiles — 三态分辨率（工单 84 triage 裁决口
   });
 });
 
-describe('resolveContextFiles — memoize 语义（工单 84：不引入第二次解析）', () => {
-  it('访问器多次调用 + 直接读 raw 共享单次 config.yml 读取', () => {
+describe('resolveContextFiles — 运行级 memoize 语义（ADR-0023 决策 2：撤销进程级缓存）', () => {
+  const configReads = () =>
+    readSpy.mock.calls.filter(call =>
+      String(call[0]).endsWith(path.join('.harness', 'config.yml'))
+    ).length;
+
+  it('同一枚观察面内多次访问共享单次 config.yml 读取', () => {
     const dir = setupProject('memo', CTX_FILES(true, ['src']));
-    const configReads = () =>
-      readSpy.mock.calls.filter(call =>
-        String(call[0]).endsWith(path.join('.harness', 'config.yml'))
-      ).length;
+    const env = createRunEnv(dir);
 
     readSpy.mockClear();
     expect(configReads()).toBe(0); // 探针有效：fixture 搭建不读 config
 
-    resolveContextFiles(dir);
+    resolveContextFiles(env);
     expect(configReads()).toBe(1); // 首次真读取+解析
 
-    resolveContextFiles(dir);
-    resolveContextFiles(dir);
-    loadRawProjectConfig(dir);
-    expect(configReads()).toBe(1); // 复用进程级 memoize，无第二次解析
+    resolveContextFiles(env);
+    resolveContextFiles(env);
+    loadRawProjectConfig(env);
+    expect(configReads()).toBe(1); // run 内复用同一份解析结果，无第二次解析
+  });
+
+  it('只传路径 = 一次性读取：同一路径先改后读必须读到新内容', () => {
+    const dir = setupProject('fresh', CTX_FILES(true, ['src']));
+
+    expect(resolveContextFiles(dir)).toEqual({ state: 'enabled', dirs: ['src'] });
+
+    writeProjectConfig(dir, CTX_FILES(false, ['src']));
+    // 旧进程级缓存按 mtime/size 判新鲜，同一次运行内「先改后读」照样读到老内容；
+    // 撤销缓存后每次调用自造一枚用完即弃的观察面，读到的必然是当下内容
+    expect(resolveContextFiles(dir)).toEqual({ state: 'unconfigured' });
   });
 });