@dommaker/harness 1.3.0 → 1.4.0

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"}

package/dist/utils/jsonl.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * 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）。
+ */
+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.readJsonl = readJsonl;
+exports.countJsonlLines = countJsonlLines;
+exports.readJsonlEnds = readJsonlEnds;
+exports.appendJsonl = appendJsonl;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** exists → read → split → filter 空行的公共前缀（正本唯一一份） */
+function readNonEmptyLines(filePath) {
+    if (!fs.existsSync(filePath))
+        return [];
+    return fs
+        .readFileSync(filePath, 'utf-8')
+        .split('\n')
+        .filter(line => line.trim().length > 0);
+}
+/**
+ * 读取 JSONL 文件：exists → read → split → parse → filter（正本读链）
+ *
+ * policy 必填无缺省（裁决 1）；缺文件返回空结果，不抛。
+ */
+function readJsonl(filePath, policy, options) {
+    let lines = readNonEmptyLines(filePath);
+    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) : [];
+    }
+    const records = [];
+    let skippedLines = 0;
+    for (const line of lines) {
+        try {
+            records.push(JSON.parse(line));
+        }
+        catch (error) {
+            if (policy === 'throw')
+                throw error;
+            skippedLines++;
+        }
+    }
+    return { records, skippedLines };
+}
+/**
+ * 统计非空行数（含坏行，完全不 parse）
+ *
+ * 供只关心记录条数的调用点（如 check 智能提示）避免全量 parse；
+ * 缺文件返回 0。
+ */
+function countJsonlLines(filePath) {
+    return readNonEmptyLines(filePath).length;
+}
+/**
+ * 只取首尾：首/末条合法记录 + 原始行数，parse 停在两端首个合法行
+ *
+ * 供只要「总数 + 首末记录」的调用点（如 TraceCollector.getStats）避免全量
+ * parse；行文本仍整读（10MB 级文本读廉价，JSON.parse 才是成本）。坏行策略
+ * 同 readJsonl：'skip' 跳过继续找，'throw' 遇坏行上抛。缺文件返回
+ * { totalLines: 0 }。
+ */
+function readJsonlEnds(filePath, policy) {
+    const lines = readNonEmptyLines(filePath);
+    let first;
+    for (let i = 0; i < lines.length; i++) {
+        try {
+            first = JSON.parse(lines[i]);
+            break;
+        }
+        catch (error) {
+            if (policy === 'throw')
+                throw error;
+        }
+    }
+    let last;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+            last = JSON.parse(lines[i]);
+            break;
+        }
+        catch (error) {
+            if (policy === 'throw')
+                throw error;
+        }
+    }
+    return { totalLines: lines.length, first, last };
+}
+/**
+ * 追加一条 JSONL 记录：ensureDir + append（正本写链）
+ *
+ * 目录不存在时递归创建；value 序列化为单行 JSON + 换行。
+ */
+function appendJsonl(filePath, value) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.appendFileSync(filePath, JSON.stringify(value) + '\n', 'utf-8');
+}
+//# sourceMappingURL=jsonl.js.map

package/dist/utils/jsonl.js.map

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

package/dist/utils/package-version.d.ts

@@ -0,0 +1,16 @@
+/**
+ * harness 包版本读取正本（#102，架构评审 A3）
+ *
+ * 「harness 包版本」此前散在四处五种写法（constraints.ts 带 cwd 兜底、init.ts
+ * require 与内联各一份、injection-drift.ts / constraints-retire.ts __dirname
+ * 相对路径）。其中 cwd 兜底在 harness 装进消费者 node_modules 且相对路径失败时
+ * 会读到**消费者自己的版本号**——这是本模块要消灭的 bug。语义在此一处定义：
+ *
+ * - 只读本模块自身的 package.json（__dirname 相对；src 与 dist 目录深度一致，
+ *   两种加载方式命中同一份清单）；
+ * - 无 cwd 兜底——cwd 的 package.json 是消费者项目的，不是 harness 的；
+ * - 清单缺失/损坏/无 version 字段 → 'unknown'（沿用收口前各处一致语义）。
+ */
+/** 读取 harness 包版本；读不到（缺失/损坏/无 version 字段）返回 'unknown' */
+export declare function getHarnessPackageVersion(): string;
+//# sourceMappingURL=package-version.d.ts.map

package/dist/utils/package-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-version.d.ts","sourceRoot":"","sources":["../../src/utils/package-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,yDAAyD;AACzD,wBAAgB,wBAAwB,IAAI,MAAM,CAQjD"}