@dommaker/harness 1.2.3 → 1.4.0

package/dist/types/passes-gate.d.ts

@@ -7,11 +7,18 @@
 export interface PassesGateConfig {
     /** 是否启用 */
     enabled?: boolean;
-    /** 测试命令 */
+    /**
+     * 测试命令。缺省时走 core/validators/passes-gate.ts 的 detectTestCommand 探测：
+     * test:ci → test（排除 echo 占位脚本）→ test:e2e → test:coverage → Python 标记 → go.mod；
+     * 探不到则 fail-closed（不再兜底 'npm test'）
+     */
     testCommand?: string;
     /** 是否需要证据 */
     requireEvidence?: boolean;
-    /** 是否允许部分通过 */
+    /**
+     * 是否允许部分通过：退出码为 0 时，输出里的失败信号不再否决判定。
+     * 不赦免非零退出码（判定依据收在 core/validators/test-output.ts 的 judgeTestRun，ADR-0014）
+     */
     allowPartialPass?: boolean;
     /** 最大重试次数 */
     maxRetries?: number;
@@ -36,8 +43,6 @@ export interface TaskTestResult {
     timestamp?: Date;
     /** 失败的测试列表 */
     failures?: string[];
-    /** 覆盖率 */
-    coverage?: number;
     /** 证据路径 */
     evidence?: string;
 }
@@ -69,26 +74,6 @@ export interface DynamicTask {
     /** 测试结果 */
     testResult?: TaskTestResult;
 }
-/**
- * PassesGate 扩展接口
- *
- * 用于注册额外的测试类型（如 Puppeteer E2E）
- */
-export interface PassesGateExtension {
-    /** 扩展名称 */
-    name: string;
-    /** 扩展描述 */
-    description?: string;
-    /** 运行测试 */
-    run(workDir: string, task?: DynamicTask): Promise<TaskTestResult>;
-}
-/**
- * 扩展测试结果（包含类型标识）
- */
-export interface ExtensionTestResult extends TaskTestResult {
-    /** 测试类型（扩展名称） */
-    type?: string;
-}
 /**
  * 测试结果输入（用于 check() 方法）
  *
@@ -99,7 +84,7 @@ export interface TestResult {
     passed: boolean;
     /** 测试命令（可选，用于记录） */
     command?: string;
-    /** 覆盖率（可选） */
+    /** 覆盖率（调用方自备数据，check() 不读它、只随 testResult 原样回显；harness 不取数不执法，ADR-0015） */
     coverage?: number;
     /** 证据路径（可选） */
     evidence?: string;

package/dist/types/passes-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"passes-gate.d.ts","sourceRoot":"","sources":["../../src/types/passes-gate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"passes-gate.d.ts","sourceRoot":"","sources":["../../src/types/passes-gate.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW;IACX,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,aAAa;IACb,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B,aAAa;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,eAAe;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,WAAW;IACX,MAAM,EAAE,OAAO,CAAC;IAEhB,WAAW;IACX,OAAO,EAAE,MAAM,CAAC;IAEhB,SAAS;IACT,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,SAAS;IACT,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,eAAe;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,UAAU;IACV,SAAS,CAAC,EAAE,IAAI,CAAC;IAEjB,cAAc;IACd,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB,WAAW;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,YAAY;IACZ,MAAM,EAAE,MAAM,CAAC;IAEf,aAAa;IACb,OAAO,EAAE,OAAO,CAAC;IAEjB,WAAW;IACX,UAAU,CAAC,EAAE,cAAc,CAAC;IAE5B,WAAW;IACX,QAAQ,EAAE,MAAM,CAAC;IAEjB,WAAW;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,YAAY;IACZ,EAAE,EAAE,MAAM,CAAC;IAEX,WAAW;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,WAAW;IACX,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,WAAW;IACX,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAMD;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,eAAe;IACf,MAAM,EAAE,OAAO,CAAC;IAEhB,oBAAoB;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,eAAe;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,eAAe;IACf,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB,eAAe;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,eAAe;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,eAAe;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,kBAAkB;IAClB,EAAE,EAAE,MAAM,CAAC;IAEX,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IAEb,WAAW;IACX,OAAO,EAAE,MAAM,CAAC;IAEhB,WAAW;IACX,KAAK,EAAE,UAAU,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,eAAe;IACf,OAAO,EAAE,OAAO,CAAC;IAEjB,oBAAoB;IACpB,UAAU,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAEnC,aAAa;IACb,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB"}

package/dist/types/project-config.d.ts

@@ -31,7 +31,7 @@ export interface CustomConstraintDefinition {
     /** 是否启用（可选，默认 true） */
     enabled?: boolean;
     /**
-     * 退役元数据（#82 D6 统一落点）
+     * 退役元数据（studio#82 D6 统一落点）
      *
      * 存在即视为已退役：不进生效集、不注入 CLAUDE.md。恢复 = 删除该段。
      * 落点在 custom-constraints.yml 条目内（一处真相，不拆 config.yml 第二处）。

package/dist/types/session.d.ts

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

package/dist/types/session.d.ts.map

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

package/dist/utils/exec.d.ts

@@ -20,6 +20,16 @@ export declare function isCommandAvailable(command: string): Promise<boolean>;
  * 将单值或数组统一为数组（用于 trigger 等字段）
  */
 export declare function normalizeTriggers<T>(value: T | T[] | undefined, fallback?: T[]): T[];
+/**
+ * 判断约束是否匹配当前操作集合（#105：trigger 匹配语义单一来源）
+ *
+ * 语义 = normalizeTriggers（undefined → [] 不匹配任何操作）+ 交集判定，
+ * 任一 operation 命中任一 trigger 即匹配。checker 与 prompt 渲染共用本函数，
+ * 禁止就地重写。
+ */
+export declare function matchesTrigger<T>(constraint: {
+    trigger: T | T[] | undefined;
+}, operations: T[]): boolean;
 /**
  * 异步延迟
  */

package/dist/utils/exec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/utils/exec.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAGrC;;GAEG;AACH,eAAO,MAAM,SAAS,2BAAkB,CAAC;AAEzC;;GAEG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAU/E;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU1E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,EAC1B,QAAQ,GAAE,CAAC,EAAO,GACjB,CAAC,EAAE,CAGL;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/utils/exec.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAGrC;;GAEG;AACH,eAAO,MAAM,SAAS,2BAAkB,CAAC;AAEzC;;GAEG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAU/E;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU1E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,EAC1B,QAAQ,GAAE,CAAC,EAAO,GACjB,CAAC,EAAE,CAGL;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,UAAU,EAAE;IAAE,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,CAAA;CAAE,EAC5C,UAAU,EAAE,CAAC,EAAE,GACd,OAAO,CAGT;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/dist/utils/exec.js

@@ -42,6 +42,7 @@ exports.execAsync = void 0;
 exports.runCommand = runCommand;
 exports.isCommandAvailable = isCommandAvailable;
 exports.normalizeTriggers = normalizeTriggers;
+exports.matchesTrigger = matchesTrigger;
 exports.delay = delay;
 const child_process_1 = require("child_process");
 const util_1 = require("util");
@@ -87,6 +88,17 @@ function normalizeTriggers(value, fallback = []) {
         return fallback;
     return Array.isArray(value) ? value : [value];
 }
+/**
+ * 判断约束是否匹配当前操作集合（#105：trigger 匹配语义单一来源）
+ *
+ * 语义 = normalizeTriggers（undefined → [] 不匹配任何操作）+ 交集判定，
+ * 任一 operation 命中任一 trigger 即匹配。checker 与 prompt 渲染共用本函数，
+ * 禁止就地重写。
+ */
+function matchesTrigger(constraint, operations) {
+    const triggers = normalizeTriggers(constraint.trigger);
+    return operations.some(op => triggers.includes(op));
+}
 /**
  * 异步延迟
  */

package/dist/utils/exec.js.map

@@ -1 +1 @@
-{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../src/utils/exec.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAaH,gCAUC;AAKD,gDAUC;AAKD,8CAMC;AAKD,sBAEC;AAtDD,iDAAqC;AACrC,+BAAiC;AAEjC;;GAEG;AACU,QAAA,SAAS,GAAG,IAAA,gBAAS,EAAC,oBAAI,CAAC,CAAC;AAEzC;;GAEG;AACI,KAAK,UAAU,UAAU,CAAC,OAAe,EAAE,GAAY;IAC5D,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAA,iBAAS,EAAC,OAAO,EAAE;YAC1C,GAAG;YACH,SAAS,EAAE,IAAI,GAAG,IAAI,EAAE,aAAa;SACtC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;GAEG;AACI,KAAK,UAAU,kBAAkB,CAAC,OAAe;IACtD,IAAI,CAAC;QACH,mCAAmC;QACnC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,wDAAa,eAAe,GAAC,CAAC;QAC/D,MAAM,aAAa,GAAG,IAAA,gBAAS,EAAC,UAAU,CAAC,CAAC;QAC5C,MAAM,aAAa,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAC/B,KAA0B,EAC1B,WAAgB,EAAE;IAElB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAC;IAC3D,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC;AAED;;GAEG;AACH,SAAgB,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../src/utils/exec.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAaH,gCAUC;AAKD,gDAUC;AAKD,8CAMC;AASD,wCAMC;AAKD,sBAEC;AArED,iDAAqC;AACrC,+BAAiC;AAEjC;;GAEG;AACU,QAAA,SAAS,GAAG,IAAA,gBAAS,EAAC,oBAAI,CAAC,CAAC;AAEzC;;GAEG;AACI,KAAK,UAAU,UAAU,CAAC,OAAe,EAAE,GAAY;IAC5D,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAA,iBAAS,EAAC,OAAO,EAAE;YAC1C,GAAG;YACH,SAAS,EAAE,IAAI,GAAG,IAAI,EAAE,aAAa;SACtC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;GAEG;AACI,KAAK,UAAU,kBAAkB,CAAC,OAAe;IACtD,IAAI,CAAC;QACH,mCAAmC;QACnC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,wDAAa,eAAe,GAAC,CAAC;QAC/D,MAAM,aAAa,GAAG,IAAA,gBAAS,EAAC,UAAU,CAAC,CAAC;QAC5C,MAAM,aAAa,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAC/B,KAA0B,EAC1B,WAAgB,EAAE;IAElB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAC;IAC3D,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,cAAc,CAC5B,UAA4C,EAC5C,UAAe;IAEf,MAAM,QAAQ,GAAG,iBAAiB,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IACvD,OAAO,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;AACtD,CAAC;AAED;;GAEG;AACH,SAAgB,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/utils/file-walk.d.ts

@@ -18,12 +18,20 @@ export interface FileWalkOptions {
  * 目录不可读时静默跳过（与原各处实现行为一致）。
  */
 export declare function walkFiles(root: string, options?: FileWalkOptions): string[];
+/**
+ * 目录遍历默认跳过名单：依赖 / 旁测目录 / 构建产物。
+ *
+ * 遍历跳过口径的正本——chain 式判断（sync-docs 的 readdir 循环）与
+ * findTsSourceFiles 的 skipDirs 默认值同源，禁止再各处手抄三段 `===`。
+ * 各调用方自有的更广名单（如 AGENTS.md 目录表跳过 build/out/coverage）不并入。
+ */
+export declare const DEFAULT_SKIP_DIRS: string[];
 export interface TsSourceWalkOptions {
     /** 是否跳过 barrel 文件 index.ts，默认 false */
     skipIndex?: boolean;
     /** 是否同时收集 .tsx 文件，默认 false（只收集 .ts） */
     includeTsx?: boolean;
-    /** 跳过的目录名，默认 node_modules/__tests__/dist */
+    /** 跳过的目录名，默认 DEFAULT_SKIP_DIRS */
     skipDirs?: string[];
     /** 是否跳过 `.` 开头的条目，默认 false */
     skipHidden?: boolean;

package/dist/utils/file-walk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-walk.d.ts","sourceRoot":"","sources":["../../src/utils/file-walk.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,MAAM,WAAW,eAAe;IAC9B,uBAAuB;IACvB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,8BAA8B;IAC9B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gCAAgC;IAChC,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,EAAE,CA0B/E;AAED,MAAM,WAAW,mBAAmB;IAClC,uCAAuC;IACvC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,uCAAuC;IACvC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,8BAA8B;IAC9B,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1D,OAAO,CAOT;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,EAAE,CAa3F"}
+{"version":3,"file":"file-walk.d.ts","sourceRoot":"","sources":["../../src/utils/file-walk.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,MAAM,WAAW,eAAe;IAC9B,uBAAuB;IACvB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,8BAA8B;IAC9B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gCAAgC;IAChC,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,EAAE,CA0B/E;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,UAAwC,CAAC;AAEvE,MAAM,WAAW,mBAAmB;IAClC,uCAAuC;IACvC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,uCAAuC;IACvC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,8BAA8B;IAC9B,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1D,OAAO,CAOT;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,EAAE,CAa3F"}

package/dist/utils/file-walk.js

@@ -39,6 +39,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SKIP_DIRS = void 0;
 exports.walkFiles = walkFiles;
 exports.isTsSourceFile = isTsSourceFile;
 exports.findTsSourceFiles = findTsSourceFiles;
@@ -76,6 +77,14 @@ function walkFiles(root, options = {}) {
     }
     return results;
 }
+/**
+ * 目录遍历默认跳过名单：依赖 / 旁测目录 / 构建产物。
+ *
+ * 遍历跳过口径的正本——chain 式判断（sync-docs 的 readdir 循环）与
+ * findTsSourceFiles 的 skipDirs 默认值同源，禁止再各处手抄三段 `===`。
+ * 各调用方自有的更广名单（如 AGENTS.md 目录表跳过 build/out/coverage）不并入。
+ */
+exports.DEFAULT_SKIP_DIRS = ['node_modules', '__tests__', 'dist'];
 /**
  * 文件名是否为 TypeScript 源文件（includeTsx 时含 .tsx，排除 .d.ts 与可选 barrel index）
  *
@@ -92,7 +101,7 @@ function isTsSourceFile(name, options = {}) {
  * 递归收集 TypeScript 源文件（.ts，includeTsx 时含 .tsx，排除 .d.ts）
  */
 function findTsSourceFiles(root, options = {}) {
-    const { skipIndex = false, includeTsx = false, skipDirs = ['node_modules', '__tests__', 'dist'], skipHidden = false, } = options;
+    const { skipIndex = false, includeTsx = false, skipDirs = exports.DEFAULT_SKIP_DIRS, skipHidden = false, } = options;
     return walkFiles(root, {
         skipDirs,
         skipHidden,

package/dist/utils/file-walk.js.map

@@ -1 +1 @@
-{"version":3,"file":"file-walk.js","sourceRoot":"","sources":["../../src/utils/file-walk.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmBH,8BA0BC;AAmBD,wCAUC;AAKD,8CAaC;AA1FD,uCAAyB;AACzB,2CAA6B;AAW7B;;;;GAIG;AACH,SAAgB,SAAS,CAAC,IAAY,EAAE,UAA2B,EAAE;IACnE,MAAM,EAAE,QAAQ,GAAG,EAAE,EAAE,UAAU,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAC9D,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,IAAI,OAAoB,CAAC;IACzB,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,UAAU,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QACvD,IAAI,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,SAAS;QAE5C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;QAChD,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YAC1B,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;gBAC5C,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAaD;;;;;GAKG;AACH,SAAgB,cAAc,CAC5B,IAAY,EACZ,UAAyD,EAAE;IAE3D,MAAM,EAAE,SAAS,GAAG,KAAK,EAAE,UAAU,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;IAC1D,OAAO,CACL,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QAC/D,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;QACvB,CAAC,CAAC,SAAS,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,IAAI,KAAK,WAAW,CAAC,CAAC,CAC9D,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAAC,IAAY,EAAE,UAA+B,EAAE;IAC/E,MAAM,EACJ,SAAS,GAAG,KAAK,EACjB,UAAU,GAAG,KAAK,EAClB,QAAQ,GAAG,CAAC,cAAc,EAAE,WAAW,EAAE,MAAM,CAAC,EAChD,UAAU,GAAG,KAAK,GACnB,GAAG,OAAO,CAAC;IAEZ,OAAO,SAAS,CAAC,IAAI,EAAE;QACrB,QAAQ;QACR,UAAU;QACV,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;KAClE,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"file-walk.js","sourceRoot":"","sources":["../../src/utils/file-walk.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmBH,8BA0BC;AA4BD,wCAUC;AAKD,8CAaC;AAnGD,uCAAyB;AACzB,2CAA6B;AAW7B;;;;GAIG;AACH,SAAgB,SAAS,CAAC,IAAY,EAAE,UAA2B,EAAE;IACnE,MAAM,EAAE,QAAQ,GAAG,EAAE,EAAE,UAAU,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAC9D,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,IAAI,OAAoB,CAAC;IACzB,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,UAAU,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QACvD,IAAI,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,SAAS;QAE5C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;QAChD,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YAC1B,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;gBAC5C,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACU,QAAA,iBAAiB,GAAG,CAAC,cAAc,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;AAavE;;;;;GAKG;AACH,SAAgB,cAAc,CAC5B,IAAY,EACZ,UAAyD,EAAE;IAE3D,MAAM,EAAE,SAAS,GAAG,KAAK,EAAE,UAAU,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;IAC1D,OAAO,CACL,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QAC/D,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;QACvB,CAAC,CAAC,SAAS,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,IAAI,KAAK,WAAW,CAAC,CAAC,CAC9D,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAAC,IAAY,EAAE,UAA+B,EAAE;IAC/E,MAAM,EACJ,SAAS,GAAG,KAAK,EACjB,UAAU,GAAG,KAAK,EAClB,QAAQ,GAAG,yBAAiB,EAC5B,UAAU,GAAG,KAAK,GACnB,GAAG,OAAO,CAAC;IAEZ,OAAO,SAAS,CAAC,IAAI,EAAE;QACrB,QAAQ;QACR,UAAU;QACV,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;KAClE,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/frontmatter.d.ts

@@ -0,0 +1,73 @@
+/**
+ * markdown frontmatter 解析/序列化正本（harness#89，架构评审 2026-09-02 候选10）
+ *
+ * `---\n<yaml>\n---\n<body>` 这一种语法此前在 knowledge 域 5 个文件里手写了 7 遍，
+ * 失败语义三派并存（store 静默丢条目 / migration 记 errors / index-generator 走
+ * best-effort / sdd 不要求闭合行完整 / ingest 只 strip 会把正文 `---` 误吞）。
+ * 语法与失败走法在此一处定义，仓内不允许存在第二份副本。
+ *
+ * 语法（唯一解释）：
+ * - 开界：偏移 0 处必须正好是一行 `---`（前面有空白行则不算 frontmatter）
+ * - 闭界：其后第一个**独立成行**的 `---`（`---x`、`----`、缩进 `---` 均不作闭合）
+ * - body：闭合行之后全部内容，紧随的一个空行被吃掉（与 join 的 `---\n\n` 包裹严格对称，
+ *   保证已落盘条目 load→save 字节稳定）
+ * - meta：闭合前的行经 YAML 解析，必须是 mapping
+ * - CRLF 文件不按 frontmatter 处理（与收口前各消费方一致，本 module 不新增解释）
+ *
+ * 三种畸形输入的走法（裁决 2，用例固定在 utils/__tests__/frontmatter.test.ts）：
+ * - 缺 frontmatter（无开界）→ 'absent'
+ * - 空 meta（闭合前只有空白，含零宽块）→ 'absent'——零宽元数据块不承载信息，
+ *   与「没有 frontmatter」同走一支，消费方按无元数据路径处理（store 视为非条目、
+ *   index-generator 走 best-effort），无需上报
+ * - 未闭合（有开无闭 / 闭合行不完整）→ 'malformed' + reason 'unterminated'
+ * - meta 不是合法 YAML mapping（语法错、显式 null、标量或数组）→ 'malformed' + reason 'invalid-yaml'
+ *
+ * 消费方统一口径（裁决 2：不允许两派并存）：'malformed' 两支必须**显式上报**，
+ * 禁止静默丢数据；恢复动作按消费方语义选择并在代码里写明——
+ * 有结构化报告面的写报告（migration → result.errors），
+ * 纯扫描型的打一行 stderr（前缀 `[harness]`，与 failure/recorder.ts 的坏行告警同构）
+ * 后跳过或走 best-effort。'absent' 是合法输入，不上报。
+ *
+ * 序列化（裁决 3：收格式不收字段排序策略）：join 只负责包裹与 YAML dump 参数
+ * （lineWidth 120，与收口前 store/migration 逐字一致）；canonical 字段序是 store 的
+ * 私有策略，留在 store.toFrontmatter。
+ *
+ * 机械核查（期望命中数，均已实测）：
+ *   grep -rnE '/\^---' src --include='*.ts' | grep -v __tests__
+ *     → 期望 0 处：手写开界正则归零
+ *   grep -rn "'---'" src --include='*.ts' | grep -v __tests__
+ *     → 期望 1 处：本文件 DELIMITER
+ *   grep -rn "yaml.load(metaText)\|yaml.dump(meta," src --include='*.ts' | grep -v __tests__
+ *     → 期望 2 处：本文件 split 的 load + join 的 dump
+ * 豁免清单（不属 frontmatter，不改）：markdown 生成物里的 `---` 分隔线与表格分隔行
+ *   （init / sync-docs / report / constraints-report 模板）、doc-freshness 的章节定位正则
+ *   （`\n---` 是章节边界）、config.yml 与 checkpoint/tasks/progress 的 yaml.dump（单 YAML/JSON 文档）。
+ */
+/** 'malformed' 的两支：消费方必须逐支显式处理（口径见文件头） */
+export type FrontmatterMalformedReason = 'unterminated' | 'invalid-yaml';
+/** frontmatter 元数据（已由 split 保证是 YAML mapping） */
+export type FrontmatterMeta = Record<string, unknown>;
+export type FrontmatterSplit = {
+    state: 'ok';
+    meta: FrontmatterMeta;
+    body: string;
+} | {
+    state: 'absent';
+} | {
+    state: 'malformed';
+    reason: FrontmatterMalformedReason;
+    detail: string;
+};
+/**
+ * 解析 markdown 的 YAML frontmatter。
+ *
+ * 不抛：三种畸形输入与 YAML 非法都体现在返回值 state/reason 上，由消费方按口径处置。
+ */
+export declare function splitFrontmatter(raw: string): FrontmatterSplit;
+/**
+ * 序列化为 `---\n<yaml>---\n\n<body>`（包裹格式与收口前 store/migration 逐字一致）。
+ *
+ * meta 的键序由调用方决定（store 保 canonical 序）；本函数只做包裹与 dump 参数。
+ */
+export declare function joinFrontmatter(meta: FrontmatterMeta, body: string): string;
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/utils/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/utils/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAUH,0CAA0C;AAC1C,MAAM,MAAM,0BAA0B,GAAG,cAAc,GAAG,cAAc,CAAC;AAEzE,iDAAiD;AACjD,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEtD,MAAM,MAAM,gBAAgB,GACxB;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE,GACnB;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,0BAA0B,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/E;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAyC9D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3E"}

package/dist/utils/frontmatter.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * markdown frontmatter 解析/序列化正本（harness#89，架构评审 2026-09-02 候选10）
+ *
+ * `---\n<yaml>\n---\n<body>` 这一种语法此前在 knowledge 域 5 个文件里手写了 7 遍，
+ * 失败语义三派并存（store 静默丢条目 / migration 记 errors / index-generator 走
+ * best-effort / sdd 不要求闭合行完整 / ingest 只 strip 会把正文 `---` 误吞）。
+ * 语法与失败走法在此一处定义，仓内不允许存在第二份副本。
+ *
+ * 语法（唯一解释）：
+ * - 开界：偏移 0 处必须正好是一行 `---`（前面有空白行则不算 frontmatter）
+ * - 闭界：其后第一个**独立成行**的 `---`（`---x`、`----`、缩进 `---` 均不作闭合）
+ * - body：闭合行之后全部内容，紧随的一个空行被吃掉（与 join 的 `---\n\n` 包裹严格对称，
+ *   保证已落盘条目 load→save 字节稳定）
+ * - meta：闭合前的行经 YAML 解析，必须是 mapping
+ * - CRLF 文件不按 frontmatter 处理（与收口前各消费方一致，本 module 不新增解释）
+ *
+ * 三种畸形输入的走法（裁决 2，用例固定在 utils/__tests__/frontmatter.test.ts）：
+ * - 缺 frontmatter（无开界）→ 'absent'
+ * - 空 meta（闭合前只有空白，含零宽块）→ 'absent'——零宽元数据块不承载信息，
+ *   与「没有 frontmatter」同走一支，消费方按无元数据路径处理（store 视为非条目、
+ *   index-generator 走 best-effort），无需上报
+ * - 未闭合（有开无闭 / 闭合行不完整）→ 'malformed' + reason 'unterminated'
+ * - meta 不是合法 YAML mapping（语法错、显式 null、标量或数组）→ 'malformed' + reason 'invalid-yaml'
+ *
+ * 消费方统一口径（裁决 2：不允许两派并存）：'malformed' 两支必须**显式上报**，
+ * 禁止静默丢数据；恢复动作按消费方语义选择并在代码里写明——
+ * 有结构化报告面的写报告（migration → result.errors），
+ * 纯扫描型的打一行 stderr（前缀 `[harness]`，与 failure/recorder.ts 的坏行告警同构）
+ * 后跳过或走 best-effort。'absent' 是合法输入，不上报。
+ *
+ * 序列化（裁决 3：收格式不收字段排序策略）：join 只负责包裹与 YAML dump 参数
+ * （lineWidth 120，与收口前 store/migration 逐字一致）；canonical 字段序是 store 的
+ * 私有策略，留在 store.toFrontmatter。
+ *
+ * 机械核查（期望命中数，均已实测）：
+ *   grep -rnE '/\^---' src --include='*.ts' | grep -v __tests__
+ *     → 期望 0 处：手写开界正则归零
+ *   grep -rn "'---'" src --include='*.ts' | grep -v __tests__
+ *     → 期望 1 处：本文件 DELIMITER
+ *   grep -rn "yaml.load(metaText)\|yaml.dump(meta," src --include='*.ts' | grep -v __tests__
+ *     → 期望 2 处：本文件 split 的 load + join 的 dump
+ * 豁免清单（不属 frontmatter，不改）：markdown 生成物里的 `---` 分隔线与表格分隔行
+ *   （init / sync-docs / report / constraints-report 模板）、doc-freshness 的章节定位正则
+ *   （`\n---` 是章节边界）、config.yml 与 checkpoint/tasks/progress 的 yaml.dump（单 YAML/JSON 文档）。
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitFrontmatter = splitFrontmatter;
+exports.joinFrontmatter = joinFrontmatter;
+const yaml = __importStar(require("js-yaml"));
+/** frontmatter 界符（整行） */
+const DELIMITER = '---';
+/** 与收口前 store/migration 逐字一致的 YAML dump 行宽 */
+const DUMP_LINE_WIDTH = 120;
+/**
+ * 解析 markdown 的 YAML frontmatter。
+ *
+ * 不抛：三种畸形输入与 YAML 非法都体现在返回值 state/reason 上，由消费方按口径处置。
+ */
+function splitFrontmatter(raw) {
+    const lines = raw.split('\n');
+    if (lines[0] !== DELIMITER)
+        return { state: 'absent' };
+    const closeIndex = lines.indexOf(DELIMITER, 1);
+    if (closeIndex === -1) {
+        return {
+            state: 'malformed',
+            reason: 'unterminated',
+            detail: `开界之后缺少独立成行的 ${DELIMITER} 闭合行`,
+        };
+    }
+    const metaLines = lines.slice(1, closeIndex);
+    if (metaLines.every(line => line.trim().length === 0))
+        return { state: 'absent' };
+    const metaText = metaLines.join('\n');
+    let parsed;
+    try {
+        parsed = yaml.load(metaText);
+    }
+    catch (error) {
+        return {
+            state: 'malformed',
+            reason: 'invalid-yaml',
+            // js-yaml 的 message 带多行代码片段，detail 只取首行描述——消费方要嵌进单行报告/stderr
+            detail: (error instanceof Error ? error.message : String(error)).split('\n')[0],
+        };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return {
+            state: 'malformed',
+            reason: 'invalid-yaml',
+            detail: `frontmatter 必须是 YAML mapping，实际是 ${Array.isArray(parsed) ? 'array' : typeof parsed}`,
+        };
+    }
+    let bodyStart = closeIndex + 1;
+    if (lines[bodyStart] === '')
+        bodyStart++;
+    return { state: 'ok', meta: parsed, body: lines.slice(bodyStart).join('\n') };
+}
+/**
+ * 序列化为 `---\n<yaml>---\n\n<body>`（包裹格式与收口前 store/migration 逐字一致）。
+ *
+ * meta 的键序由调用方决定（store 保 canonical 序）；本函数只做包裹与 dump 参数。
+ */
+function joinFrontmatter(meta, body) {
+    return `${DELIMITER}\n${yaml.dump(meta, { lineWidth: DUMP_LINE_WIDTH })}${DELIMITER}\n\n${body}`;
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/utils/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/utils/frontmatter.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BH,4CAyCC;AAOD,0CAEC;AA1ED,8CAAgC;AAEhC,yBAAyB;AACzB,MAAM,SAAS,GAAG,KAAK,CAAC;AAExB,8CAA8C;AAC9C,MAAM,eAAe,GAAG,GAAG,CAAC;AAa5B;;;;GAIG;AACH,SAAgB,gBAAgB,CAAC,GAAW;IAC1C,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IAEvD,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IAC/C,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;QACtB,OAAO;YACL,KAAK,EAAE,WAAW;YAClB,MAAM,EAAE,cAAc;YACtB,MAAM,EAAE,eAAe,SAAS,MAAM;SACvC,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IAC7C,IAAI,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IAElF,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,KAAK,EAAE,WAAW;YAClB,MAAM,EAAE,cAAc;YACtB,6DAA6D;YAC7D,MAAM,EAAE,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;SAChF,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,OAAO;YACL,KAAK,EAAE,WAAW;YAClB,MAAM,EAAE,cAAc;YACtB,MAAM,EAAE,oCAAoC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,MAAM,EAAE;SAC9F,CAAC;IACJ,CAAC;IAED,IAAI,SAAS,GAAG,UAAU,GAAG,CAAC,CAAC;IAC/B,IAAI,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE;QAAE,SAAS,EAAE,CAAC;IAEzC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAyB,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AACnG,CAAC;AAED;;;;GAIG;AACH,SAAgB,eAAe,CAAC,IAAqB,EAAE,IAAY;IACjE,OAAO,GAAG,SAAS,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,eAAe,EAAE,CAAC,GAAG,SAAS,OAAO,IAAI,EAAE,CAAC;AACnG,CAAC"}

package/dist/utils/jsonl.d.ts

@@ -0,0 +1,92 @@
+/**
+ * append-only JSONL 日志读写正本（harness#82，架构评审 2026-09-02 候选3）
+ *
+ * 全仓 append-only JSONL（traces.log / failures.log / context-tracker.log /
+ * references.jsonl / sessions/<id>/events.jsonl / 外部 transcript .jsonl）的
+ * exists → read → split → parse → filter 读链与 ensureDir + append 写链
+ * 收口于此，仓内不允许存在第二份副本。
+ *
+ * 坏行策略（harness#82 裁决 1）：读入口 policy 为显式必填参数，类型层面无缺省，
+ * 每个调用点必须逐一声明 'skip' | 'throw'——既不让「静默丢数据」成为框架缺省，
+ * 也不反转既有容错调用点的语义。坏行指非空但 JSON.parse 失败的行
+ * （半写入截断、手工编辑、磁盘满等）。
+ *
+ * tail / head：只解析尾部 / 头部 N 个非空行（文件仍全量读取，parse 才是大头），
+ * 供「只看最近 K 条」的调用点避免全量 parse（check 等热路径）。
+ * countJsonlLines 供纯计数消费方（完全不 parse）。
+ *
+ * 计数去向（harness#100）：本模块是坏行计数的唯一正本，但正本≠终点——凡以 'skip'
+ * 策略读，调用点必须把 skippedLines 带到该消费面的用户可见输出（CLI 走 stderr，
+ * 结构化输出与 API 走字段），或显式记名豁免并写明理由。机器可检面：
+ * `src/utils/__tests__/jsonl-skip-disposition.test.ts`（冻结站点集合 + 要求每个读点
+ * 上方声明 `计数去向：`）。
+ *
+ * 豁免清单与机械核查（期望命中数）：
+ *   grep -rnE "JSON\.parse\((line|trimmed|l)\b" src --include='*.ts' | grep -v __tests__
+ *     → 期望 1 处：本文件 readJsonl（读链正本本体）
+ *   grep -rn "map(JSON.parse" src --include='*.ts' | grep -v __tests__
+ *     → 期望 0 处
+ *   __tests__ 下的坏行 fixture 不在核查范围。
+ * 其余裁决豁免：readIfExists（injection-writer，string|null 形态不同，#82 裁决 3）；
+ * FailureRecorder 轮换链（文件生命周期不变量，裁决 2）；
+ * 单 JSON 文档读取（package.json / .state.json / checkpoint.json / summary 等非 JSONL）。
+ */
+/**
+ * 坏行策略
+ *
+ * - 'skip'：跳过损坏行，继续解析；skippedLines 计数
+ * - 'throw'：损坏行直接上抛（沿用原抛语义的调用点显式选择）
+ */
+export type JsonlBadLinePolicy = 'skip' | 'throw';
+export interface JsonlReadResult<T> {
+    records: T[];
+    /**
+     * 被跳过的坏行数（'throw' 策略下恒为 0）
+     *
+     * 拿到它不等于告知：skip 读点必须把它带到消费面的用户可见输出或记名豁免（harness#100）
+     */
+    skippedLines: number;
+}
+export interface JsonlReadOptions {
+    /** 只解析最后 N 个非空行（尾部读取） */
+    tail?: number;
+    /** 只解析前 N 个非空行（头部读取） */
+    head?: number;
+}
+/**
+ * 读取 JSONL 文件：exists → read → split → parse → filter（正本读链）
+ *
+ * policy 必填无缺省（裁决 1）；缺文件返回空结果，不抛。
+ */
+export declare function readJsonl<T>(filePath: string, policy: JsonlBadLinePolicy, options?: JsonlReadOptions): JsonlReadResult<T>;
+/**
+ * 统计非空行数（含坏行，完全不 parse）
+ *
+ * 供只关心记录条数的调用点（如 check 智能提示）避免全量 parse；
+ * 缺文件返回 0。
+ */
+export declare function countJsonlLines(filePath: string): number;
+export interface JsonlEndsResult<T> {
+    /** 原始非空行数（合法 + 坏行），与 records.length + skippedLines 同口径 */
+    totalLines: number;
+    /** 自首向尾第一条合法记录；无合法记录为 undefined */
+    first?: T;
+    /** 自尾向首第一条合法记录；无合法记录为 undefined */
+    last?: T;
+}
+/**
+ * 只取首尾：首/末条合法记录 + 原始行数，parse 停在两端首个合法行
+ *
+ * 供只要「总数 + 首末记录」的调用点（如 TraceCollector.getStats）避免全量
+ * parse；行文本仍整读（10MB 级文本读廉价，JSON.parse 才是成本）。坏行策略
+ * 同 readJsonl：'skip' 跳过继续找，'throw' 遇坏行上抛。缺文件返回
+ * { totalLines: 0 }。
+ */
+export declare function readJsonlEnds<T>(filePath: string, policy: JsonlBadLinePolicy): JsonlEndsResult<T>;
+/**
+ * 追加一条 JSONL 记录：ensureDir + append（正本写链）
+ *
+ * 目录不存在时递归创建；value 序列化为单行 JSON + 换行。
+ */
+export declare function appendJsonl(filePath: string, value: unknown): void;
+//# sourceMappingURL=jsonl.d.ts.map

package/dist/utils/jsonl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.d.ts","sourceRoot":"","sources":["../../src/utils/jsonl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAKH;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,OAAO,CAAC;AAElD,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,OAAO,EAAE,CAAC,EAAE,CAAC;IACb;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,yBAAyB;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAWD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,kBAAkB,EAC1B,OAAO,CAAC,EAAE,gBAAgB,GACzB,eAAe,CAAC,CAAC,CAAC,CAoBpB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,mCAAmC;IACnC,IAAI,CAAC,EAAE,CAAC,CAAC;CACV;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,eAAe,CAAC,CAAC,CAAC,CAwBjG;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAMlE"}