@dommaker/harness 1.3.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (532) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +0 -2
  3. package/bin/harness.js +86 -32
  4. package/dist/cli/command-contract.d.ts +83 -0
  5. package/dist/cli/command-contract.d.ts.map +1 -0
  6. package/dist/cli/command-contract.js +66 -0
  7. package/dist/cli/command-contract.js.map +1 -0
  8. package/dist/cli/commands/acceptance.d.ts +3 -2
  9. package/dist/cli/commands/acceptance.d.ts.map +1 -1
  10. package/dist/cli/commands/acceptance.js +28 -24
  11. package/dist/cli/commands/acceptance.js.map +1 -1
  12. package/dist/cli/commands/analyze-sessions.d.ts +2 -1
  13. package/dist/cli/commands/analyze-sessions.d.ts.map +1 -1
  14. package/dist/cli/commands/analyze-sessions.js +25 -24
  15. package/dist/cli/commands/analyze-sessions.js.map +1 -1
  16. package/dist/cli/commands/check.d.ts +14 -2
  17. package/dist/cli/commands/check.d.ts.map +1 -1
  18. package/dist/cli/commands/check.js +104 -61
  19. package/dist/cli/commands/check.js.map +1 -1
  20. package/dist/cli/commands/command.d.ts +5 -1
  21. package/dist/cli/commands/command.d.ts.map +1 -1
  22. package/dist/cli/commands/command.js +26 -17
  23. package/dist/cli/commands/command.js.map +1 -1
  24. package/dist/cli/commands/constraints-report.d.ts +2 -1
  25. package/dist/cli/commands/constraints-report.d.ts.map +1 -1
  26. package/dist/cli/commands/constraints-report.js +37 -33
  27. package/dist/cli/commands/constraints-report.js.map +1 -1
  28. package/dist/cli/commands/constraints-retire.d.ts +6 -5
  29. package/dist/cli/commands/constraints-retire.d.ts.map +1 -1
  30. package/dist/cli/commands/constraints-retire.js +50 -52
  31. package/dist/cli/commands/constraints-retire.js.map +1 -1
  32. package/dist/cli/commands/constraints.d.ts +2 -1
  33. package/dist/cli/commands/constraints.d.ts.map +1 -1
  34. package/dist/cli/commands/constraints.js +10 -27
  35. package/dist/cli/commands/constraints.js.map +1 -1
  36. package/dist/cli/commands/contract.d.ts +3 -2
  37. package/dist/cli/commands/contract.d.ts.map +1 -1
  38. package/dist/cli/commands/contract.js +45 -42
  39. package/dist/cli/commands/contract.js.map +1 -1
  40. package/dist/cli/commands/definitions.d.ts +11 -11
  41. package/dist/cli/commands/definitions.d.ts.map +1 -1
  42. package/dist/cli/commands/definitions.js +27 -219
  43. package/dist/cli/commands/definitions.js.map +1 -1
  44. package/dist/cli/commands/failure.d.ts +5 -4
  45. package/dist/cli/commands/failure.d.ts.map +1 -1
  46. package/dist/cli/commands/failure.js +31 -25
  47. package/dist/cli/commands/failure.js.map +1 -1
  48. package/dist/cli/commands/init.d.ts +7 -5
  49. package/dist/cli/commands/init.d.ts.map +1 -1
  50. package/dist/cli/commands/init.js +147 -211
  51. package/dist/cli/commands/init.js.map +1 -1
  52. package/dist/cli/commands/knowledge.d.ts +17 -30
  53. package/dist/cli/commands/knowledge.d.ts.map +1 -1
  54. package/dist/cli/commands/knowledge.js +183 -273
  55. package/dist/cli/commands/knowledge.js.map +1 -1
  56. package/dist/cli/commands/passes-gate.d.ts +8 -2
  57. package/dist/cli/commands/passes-gate.d.ts.map +1 -1
  58. package/dist/cli/commands/passes-gate.js +44 -66
  59. package/dist/cli/commands/passes-gate.js.map +1 -1
  60. package/dist/cli/commands/performance.d.ts +2 -1
  61. package/dist/cli/commands/performance.d.ts.map +1 -1
  62. package/dist/cli/commands/performance.js +20 -18
  63. package/dist/cli/commands/performance.js.map +1 -1
  64. package/dist/cli/commands/posteval-plan.d.ts +5 -1
  65. package/dist/cli/commands/posteval-plan.d.ts.map +1 -1
  66. package/dist/cli/commands/posteval-plan.js +26 -15
  67. package/dist/cli/commands/posteval-plan.js.map +1 -1
  68. package/dist/cli/commands/release.d.ts +6 -1
  69. package/dist/cli/commands/release.d.ts.map +1 -1
  70. package/dist/cli/commands/release.js +69 -59
  71. package/dist/cli/commands/release.js.map +1 -1
  72. package/dist/cli/commands/report.d.ts +2 -1
  73. package/dist/cli/commands/report.d.ts.map +1 -1
  74. package/dist/cli/commands/report.js +9 -5
  75. package/dist/cli/commands/report.js.map +1 -1
  76. package/dist/cli/commands/review.d.ts +3 -2
  77. package/dist/cli/commands/review.d.ts.map +1 -1
  78. package/dist/cli/commands/review.js +33 -29
  79. package/dist/cli/commands/review.js.map +1 -1
  80. package/dist/cli/commands/sdd.d.ts +2 -1
  81. package/dist/cli/commands/sdd.d.ts.map +1 -1
  82. package/dist/cli/commands/sdd.js +7 -5
  83. package/dist/cli/commands/sdd.js.map +1 -1
  84. package/dist/cli/commands/security.d.ts +3 -2
  85. package/dist/cli/commands/security.d.ts.map +1 -1
  86. package/dist/cli/commands/security.js +29 -26
  87. package/dist/cli/commands/security.js.map +1 -1
  88. package/dist/cli/commands/spec-baseline-check.d.ts +2 -1
  89. package/dist/cli/commands/spec-baseline-check.d.ts.map +1 -1
  90. package/dist/cli/commands/spec-baseline-check.js +15 -11
  91. package/dist/cli/commands/spec-baseline-check.js.map +1 -1
  92. package/dist/cli/commands/spec.d.ts +7 -2
  93. package/dist/cli/commands/spec.d.ts.map +1 -1
  94. package/dist/cli/commands/spec.js +61 -51
  95. package/dist/cli/commands/spec.js.map +1 -1
  96. package/dist/cli/commands/status.d.ts +2 -1
  97. package/dist/cli/commands/status.d.ts.map +1 -1
  98. package/dist/cli/commands/status.js +57 -53
  99. package/dist/cli/commands/status.js.map +1 -1
  100. package/dist/cli/commands/sync-docs/agents-syncer.d.ts.map +1 -1
  101. package/dist/cli/commands/sync-docs/agents-syncer.js +5 -2
  102. package/dist/cli/commands/sync-docs/agents-syncer.js.map +1 -1
  103. package/dist/cli/commands/sync-docs/context-syncer.d.ts.map +1 -1
  104. package/dist/cli/commands/sync-docs/context-syncer.js +3 -2
  105. package/dist/cli/commands/sync-docs/context-syncer.js.map +1 -1
  106. package/dist/cli/commands/sync-docs/index.d.ts +2 -1
  107. package/dist/cli/commands/sync-docs/index.d.ts.map +1 -1
  108. package/dist/cli/commands/sync-docs/index.js +68 -88
  109. package/dist/cli/commands/sync-docs/index.js.map +1 -1
  110. package/dist/cli/commands/sync-docs/project-reader.d.ts +6 -1
  111. package/dist/cli/commands/sync-docs/project-reader.d.ts.map +1 -1
  112. package/dist/cli/commands/sync-docs/project-reader.js +14 -16
  113. package/dist/cli/commands/sync-docs/project-reader.js.map +1 -1
  114. package/dist/cli/commands/update-user-model.d.ts +9 -3
  115. package/dist/cli/commands/update-user-model.d.ts.map +1 -1
  116. package/dist/cli/commands/update-user-model.js +56 -61
  117. package/dist/cli/commands/update-user-model.js.map +1 -1
  118. package/dist/cli/commands/validate.d.ts +4 -3
  119. package/dist/cli/commands/validate.d.ts.map +1 -1
  120. package/dist/cli/commands/validate.js +28 -26
  121. package/dist/cli/commands/validate.js.map +1 -1
  122. package/dist/cli/session-mining/transcript.d.ts +7 -1
  123. package/dist/cli/session-mining/transcript.d.ts.map +1 -1
  124. package/dist/cli/session-mining/transcript.js +21 -14
  125. package/dist/cli/session-mining/transcript.js.map +1 -1
  126. package/dist/context/session-manager.d.ts.map +1 -1
  127. package/dist/context/session-manager.js +19 -32
  128. package/dist/context/session-manager.js.map +1 -1
  129. package/dist/core/constraints/agent-prompt-renderer.d.ts.map +1 -1
  130. package/dist/core/constraints/agent-prompt-renderer.js +1 -4
  131. package/dist/core/constraints/agent-prompt-renderer.js.map +1 -1
  132. package/dist/core/constraints/capabilities-parser.d.ts +24 -7
  133. package/dist/core/constraints/capabilities-parser.d.ts.map +1 -1
  134. package/dist/core/constraints/capabilities-parser.js +32 -28
  135. package/dist/core/constraints/capabilities-parser.js.map +1 -1
  136. package/dist/core/constraints/capabilities-reconcile.d.ts +67 -0
  137. package/dist/core/constraints/capabilities-reconcile.d.ts.map +1 -0
  138. package/dist/core/constraints/capabilities-reconcile.js +105 -0
  139. package/dist/core/constraints/capabilities-reconcile.js.map +1 -0
  140. package/dist/core/constraints/checker.d.ts +21 -43
  141. package/dist/core/constraints/checker.d.ts.map +1 -1
  142. package/dist/core/constraints/checker.js +68 -117
  143. package/dist/core/constraints/checker.js.map +1 -1
  144. package/dist/core/constraints/checkers/capability-sync.d.ts +20 -8
  145. package/dist/core/constraints/checkers/capability-sync.d.ts.map +1 -1
  146. package/dist/core/constraints/checkers/capability-sync.js +66 -77
  147. package/dist/core/constraints/checkers/capability-sync.js.map +1 -1
  148. package/dist/core/constraints/checkers/context-doc-sync.d.ts +4 -2
  149. package/dist/core/constraints/checkers/context-doc-sync.d.ts.map +1 -1
  150. package/dist/core/constraints/checkers/context-doc-sync.js +13 -22
  151. package/dist/core/constraints/checkers/context-doc-sync.js.map +1 -1
  152. package/dist/core/constraints/checkers/docs-freshness.d.ts.map +1 -1
  153. package/dist/core/constraints/checkers/docs-freshness.js +49 -66
  154. package/dist/core/constraints/checkers/docs-freshness.js.map +1 -1
  155. package/dist/core/constraints/checkers/governance-presence.d.ts +2 -2
  156. package/dist/core/constraints/checkers/governance-presence.d.ts.map +1 -1
  157. package/dist/core/constraints/checkers/governance-presence.js +7 -28
  158. package/dist/core/constraints/checkers/governance-presence.js.map +1 -1
  159. package/dist/core/constraints/checkers/index.d.ts +2 -2
  160. package/dist/core/constraints/checkers/index.d.ts.map +1 -1
  161. package/dist/core/constraints/checkers/index.js +2 -1
  162. package/dist/core/constraints/checkers/index.js.map +1 -1
  163. package/dist/core/constraints/checkers/no-test-simplification.d.ts.map +1 -1
  164. package/dist/core/constraints/checkers/no-test-simplification.js +4 -3
  165. package/dist/core/constraints/checkers/no-test-simplification.js.map +1 -1
  166. package/dist/core/constraints/checkers/types.d.ts +43 -4
  167. package/dist/core/constraints/checkers/types.d.ts.map +1 -1
  168. package/dist/core/constraints/checkers/types.js +33 -0
  169. package/dist/core/constraints/checkers/types.js.map +1 -1
  170. package/dist/core/constraints/context-builder.d.ts +15 -14
  171. package/dist/core/constraints/context-builder.d.ts.map +1 -1
  172. package/dist/core/constraints/context-builder.js +32 -96
  173. package/dist/core/constraints/context-builder.js.map +1 -1
  174. package/dist/core/constraints/doc-freshness/runner.d.ts.map +1 -1
  175. package/dist/core/constraints/doc-freshness/runner.js +2 -1
  176. package/dist/core/constraints/doc-freshness/runner.js.map +1 -1
  177. package/dist/core/constraints/git-evidence.d.ts +60 -0
  178. package/dist/core/constraints/git-evidence.d.ts.map +1 -0
  179. package/dist/core/constraints/git-evidence.js +88 -0
  180. package/dist/core/constraints/git-evidence.js.map +1 -0
  181. package/dist/core/constraints/injection-drift.d.ts +3 -20
  182. package/dist/core/constraints/injection-drift.d.ts.map +1 -1
  183. package/dist/core/constraints/injection-drift.js +10 -57
  184. package/dist/core/constraints/injection-drift.js.map +1 -1
  185. package/dist/core/constraints/injection-writer.d.ts +113 -0
  186. package/dist/core/constraints/injection-writer.d.ts.map +1 -0
  187. package/dist/core/constraints/injection-writer.js +228 -0
  188. package/dist/core/constraints/injection-writer.js.map +1 -0
  189. package/dist/core/constraints/usage-report.d.ts +22 -1
  190. package/dist/core/constraints/usage-report.d.ts.map +1 -1
  191. package/dist/core/constraints/usage-report.js +27 -20
  192. package/dist/core/constraints/usage-report.js.map +1 -1
  193. package/dist/core/index.d.ts +2 -2
  194. package/dist/core/index.d.ts.map +1 -1
  195. package/dist/core/index.js +4 -2
  196. package/dist/core/index.js.map +1 -1
  197. package/dist/core/project-config-loader.d.ts +32 -1
  198. package/dist/core/project-config-loader.d.ts.map +1 -1
  199. package/dist/core/project-config-loader.js +39 -9
  200. package/dist/core/project-config-loader.js.map +1 -1
  201. package/dist/core/validators/passes-gate.d.ts +15 -64
  202. package/dist/core/validators/passes-gate.d.ts.map +1 -1
  203. package/dist/core/validators/passes-gate.js +84 -222
  204. package/dist/core/validators/passes-gate.js.map +1 -1
  205. package/dist/core/validators/test-output.d.ts +58 -0
  206. package/dist/core/validators/test-output.d.ts.map +1 -0
  207. package/dist/core/validators/test-output.js +109 -0
  208. package/dist/core/validators/test-output.js.map +1 -0
  209. package/dist/failure/recorder.d.ts +6 -0
  210. package/dist/failure/recorder.d.ts.map +1 -1
  211. package/dist/failure/recorder.js +12 -8
  212. package/dist/failure/recorder.js.map +1 -1
  213. package/dist/gates/acceptance.d.ts +1 -48
  214. package/dist/gates/acceptance.d.ts.map +1 -1
  215. package/dist/gates/acceptance.js +6 -38
  216. package/dist/gates/acceptance.js.map +1 -1
  217. package/dist/gates/checker-gate.d.ts +2 -1
  218. package/dist/gates/checker-gate.d.ts.map +1 -1
  219. package/dist/gates/checker-gate.js +11 -13
  220. package/dist/gates/checker-gate.js.map +1 -1
  221. package/dist/gates/command.d.ts.map +1 -1
  222. package/dist/gates/command.js +10 -22
  223. package/dist/gates/command.js.map +1 -1
  224. package/dist/gates/contract.d.ts.map +1 -1
  225. package/dist/gates/contract.js +22 -61
  226. package/dist/gates/contract.js.map +1 -1
  227. package/dist/gates/performance.d.ts.map +1 -1
  228. package/dist/gates/performance.js +13 -31
  229. package/dist/gates/performance.js.map +1 -1
  230. package/dist/gates/review.d.ts.map +1 -1
  231. package/dist/gates/review.js +21 -53
  232. package/dist/gates/review.js.map +1 -1
  233. package/dist/gates/security.d.ts.map +1 -1
  234. package/dist/gates/security.js +14 -32
  235. package/dist/gates/security.js.map +1 -1
  236. package/dist/gates/types.d.ts +28 -5
  237. package/dist/gates/types.d.ts.map +1 -1
  238. package/dist/gates/types.js +38 -1
  239. package/dist/gates/types.js.map +1 -1
  240. package/dist/hooks/bootstrap.d.ts +2 -0
  241. package/dist/hooks/bootstrap.d.ts.map +1 -1
  242. package/dist/hooks/bootstrap.js +5 -2
  243. package/dist/hooks/bootstrap.js.map +1 -1
  244. package/dist/index.d.ts +1 -2
  245. package/dist/index.d.ts.map +1 -1
  246. package/dist/index.js.map +1 -1
  247. package/dist/knowledge/audit.d.ts +7 -2
  248. package/dist/knowledge/audit.d.ts.map +1 -1
  249. package/dist/knowledge/audit.js +59 -79
  250. package/dist/knowledge/audit.js.map +1 -1
  251. package/dist/knowledge/flywheel-metrics.d.ts +39 -0
  252. package/dist/knowledge/flywheel-metrics.d.ts.map +1 -0
  253. package/dist/knowledge/flywheel-metrics.js +47 -0
  254. package/dist/knowledge/flywheel-metrics.js.map +1 -0
  255. package/dist/knowledge/import.d.ts.map +1 -1
  256. package/dist/knowledge/import.js +4 -14
  257. package/dist/knowledge/import.js.map +1 -1
  258. package/dist/knowledge/index-generator.d.ts.map +1 -1
  259. package/dist/knowledge/index-generator.js +17 -14
  260. package/dist/knowledge/index-generator.js.map +1 -1
  261. package/dist/knowledge/ingest.d.ts.map +1 -1
  262. package/dist/knowledge/ingest.js +9 -4
  263. package/dist/knowledge/ingest.js.map +1 -1
  264. package/dist/knowledge/migration.d.ts.map +1 -1
  265. package/dist/knowledge/migration.js +11 -8
  266. package/dist/knowledge/migration.js.map +1 -1
  267. package/dist/knowledge/reference-tracker.d.ts.map +1 -1
  268. package/dist/knowledge/reference-tracker.js +12 -9
  269. package/dist/knowledge/reference-tracker.js.map +1 -1
  270. package/dist/knowledge/store.d.ts +15 -0
  271. package/dist/knowledge/store.d.ts.map +1 -1
  272. package/dist/knowledge/store.js +59 -10
  273. package/dist/knowledge/store.js.map +1 -1
  274. package/dist/monitoring/context-tracker.d.ts.map +1 -1
  275. package/dist/monitoring/context-tracker.js +11 -20
  276. package/dist/monitoring/context-tracker.js.map +1 -1
  277. package/dist/monitoring/index.d.ts +1 -1
  278. package/dist/monitoring/index.d.ts.map +1 -1
  279. package/dist/monitoring/index.js +1 -2
  280. package/dist/monitoring/index.js.map +1 -1
  281. package/dist/monitoring/trace-analyzer.d.ts +15 -0
  282. package/dist/monitoring/trace-analyzer.d.ts.map +1 -1
  283. package/dist/monitoring/trace-analyzer.js +19 -2
  284. package/dist/monitoring/trace-analyzer.js.map +1 -1
  285. package/dist/monitoring/traces.d.ts +21 -2
  286. package/dist/monitoring/traces.d.ts.map +1 -1
  287. package/dist/monitoring/traces.js +38 -29
  288. package/dist/monitoring/traces.js.map +1 -1
  289. package/dist/release/index.d.ts +2 -2
  290. package/dist/release/index.d.ts.map +1 -1
  291. package/dist/release/index.js +1 -5
  292. package/dist/release/index.js.map +1 -1
  293. package/dist/sdd/index-generator.js +10 -11
  294. package/dist/sdd/index-generator.js.map +1 -1
  295. package/dist/test-setup/project-fixture.d.ts +48 -0
  296. package/dist/test-setup/project-fixture.d.ts.map +1 -0
  297. package/dist/test-setup/project-fixture.js +106 -0
  298. package/dist/test-setup/project-fixture.js.map +1 -0
  299. package/dist/types/constraint.d.ts +8 -18
  300. package/dist/types/constraint.d.ts.map +1 -1
  301. package/dist/types/constraint.js +6 -1
  302. package/dist/types/constraint.js.map +1 -1
  303. package/dist/types/passes-gate.d.ts +10 -25
  304. package/dist/types/passes-gate.d.ts.map +1 -1
  305. package/dist/types/project-config.d.ts +1 -1
  306. package/dist/types/session.d.ts +6 -5
  307. package/dist/types/session.d.ts.map +1 -1
  308. package/dist/types/trace.d.ts +9 -0
  309. package/dist/types/trace.d.ts.map +1 -1
  310. package/dist/utils/exec.d.ts +10 -0
  311. package/dist/utils/exec.d.ts.map +1 -1
  312. package/dist/utils/exec.js +12 -0
  313. package/dist/utils/exec.js.map +1 -1
  314. package/dist/utils/file-walk.d.ts +9 -1
  315. package/dist/utils/file-walk.d.ts.map +1 -1
  316. package/dist/utils/file-walk.js +10 -1
  317. package/dist/utils/file-walk.js.map +1 -1
  318. package/dist/utils/frontmatter.d.ts +73 -0
  319. package/dist/utils/frontmatter.d.ts.map +1 -0
  320. package/dist/utils/frontmatter.js +141 -0
  321. package/dist/utils/frontmatter.js.map +1 -0
  322. package/dist/utils/jsonl.d.ts +92 -0
  323. package/dist/utils/jsonl.d.ts.map +1 -0
  324. package/dist/utils/jsonl.js +166 -0
  325. package/dist/utils/jsonl.js.map +1 -0
  326. package/dist/utils/package-version.d.ts +16 -0
  327. package/dist/utils/package-version.d.ts.map +1 -0
  328. package/dist/utils/package-version.js +63 -0
  329. package/dist/utils/package-version.js.map +1 -0
  330. package/package.json +1 -1
  331. package/src/CONTEXT.md +8 -2
  332. package/src/__tests__/acceptance-gate.test.ts +3 -1
  333. package/src/__tests__/checker-extra.test.ts +7 -1218
  334. package/src/__tests__/context-files-resolution.test.ts +116 -0
  335. package/src/__tests__/effective-constraints.test.ts +10 -13
  336. package/src/__tests__/exec.test.ts +35 -1
  337. package/src/__tests__/layering.test.ts +152 -0
  338. package/src/__tests__/passes-gate-extra.test.ts +0 -145
  339. package/src/__tests__/passes-gate.test.ts +130 -101
  340. package/src/__tests__/skip-semantics.test.ts +5 -9
  341. package/src/cli/__tests__/command-contract.test.ts +170 -0
  342. package/src/cli/command-contract.ts +108 -0
  343. package/src/cli/commands/CONTEXT.md +23 -8
  344. package/src/cli/commands/__tests__/acceptance.test.ts +40 -33
  345. package/src/cli/commands/__tests__/analyze-sessions.test.ts +35 -29
  346. package/src/cli/commands/__tests__/bin-exit-mapping.test.ts +107 -0
  347. package/src/cli/commands/__tests__/check-drift.test.ts +27 -34
  348. package/src/cli/commands/__tests__/check-skip-output.test.ts +21 -24
  349. package/src/cli/commands/__tests__/check.test.ts +448 -378
  350. package/src/cli/commands/__tests__/command.test.ts +85 -70
  351. package/src/cli/commands/__tests__/constraints-report.test.ts +100 -71
  352. package/src/cli/commands/__tests__/constraints-retire.test.ts +152 -95
  353. package/src/cli/commands/__tests__/contract.test.ts +27 -34
  354. package/src/cli/commands/__tests__/failure.test.ts +31 -34
  355. package/src/cli/commands/__tests__/init-injection.test.ts +58 -28
  356. package/src/cli/commands/__tests__/init.test.ts +77 -48
  357. package/src/cli/commands/__tests__/knowledge-flywheel-consistency.test.ts +108 -0
  358. package/src/cli/commands/__tests__/knowledge.test.ts +69 -43
  359. package/src/cli/commands/__tests__/passes-gate.test.ts +43 -45
  360. package/src/cli/commands/__tests__/performance.test.ts +22 -23
  361. package/src/cli/commands/__tests__/posteval-plan.test.ts +39 -38
  362. package/src/cli/commands/__tests__/project-path-anchoring.test.ts +157 -0
  363. package/src/cli/commands/__tests__/project-path-convention.test.ts +231 -0
  364. package/src/cli/commands/__tests__/registry.test.ts +75 -35
  365. package/src/cli/commands/__tests__/release.test.ts +209 -80
  366. package/src/cli/commands/__tests__/report-extra.test.ts +16 -16
  367. package/src/cli/commands/__tests__/report.test.ts +25 -25
  368. package/src/cli/commands/__tests__/review.test.ts +33 -31
  369. package/src/cli/commands/__tests__/security.test.ts +23 -27
  370. package/src/cli/commands/__tests__/spec-baseline-check.test.ts +20 -20
  371. package/src/cli/commands/__tests__/spec.test.ts +41 -29
  372. package/src/cli/commands/__tests__/status-extra.test.ts +18 -18
  373. package/src/cli/commands/__tests__/status-skipped-lines.test.ts +72 -0
  374. package/src/cli/commands/__tests__/status.test.ts +34 -34
  375. package/src/cli/commands/__tests__/sync-docs-agents.test.ts +77 -78
  376. package/src/cli/commands/__tests__/sync-docs.test.ts +72 -74
  377. package/src/cli/commands/__tests__/update-user-model.test.ts +97 -34
  378. package/src/cli/commands/__tests__/validate.test.ts +27 -29
  379. package/src/cli/commands/acceptance.ts +35 -24
  380. package/src/cli/commands/analyze-sessions.ts +25 -24
  381. package/src/cli/commands/check.ts +127 -66
  382. package/src/cli/commands/command.ts +30 -17
  383. package/src/cli/commands/constraints-report.ts +37 -34
  384. package/src/cli/commands/constraints-retire.ts +58 -55
  385. package/src/cli/commands/constraints.ts +10 -27
  386. package/src/cli/commands/contract.ts +51 -42
  387. package/src/cli/commands/definitions.ts +34 -227
  388. package/src/cli/commands/failure.ts +33 -26
  389. package/src/cli/commands/init.ts +166 -220
  390. package/src/cli/commands/knowledge.ts +192 -289
  391. package/src/cli/commands/passes-gate.ts +58 -68
  392. package/src/cli/commands/performance.ts +23 -18
  393. package/src/cli/commands/posteval-plan.ts +29 -15
  394. package/src/cli/commands/release.ts +70 -59
  395. package/src/cli/commands/report.ts +9 -5
  396. package/src/cli/commands/review.ts +39 -29
  397. package/src/cli/commands/sdd.ts +7 -5
  398. package/src/cli/commands/security.ts +35 -26
  399. package/src/cli/commands/spec-baseline-check.ts +16 -11
  400. package/src/cli/commands/spec.ts +66 -53
  401. package/src/cli/commands/status.ts +59 -53
  402. package/src/cli/commands/sync-docs/agents-syncer.ts +5 -2
  403. package/src/cli/commands/sync-docs/context-syncer.ts +3 -2
  404. package/src/cli/commands/sync-docs/index.ts +73 -100
  405. package/src/cli/commands/sync-docs/project-reader.ts +17 -18
  406. package/src/cli/commands/update-user-model.ts +64 -61
  407. package/src/cli/commands/validate.ts +31 -25
  408. package/src/cli/session-mining/__tests__/transcript.test.ts +118 -0
  409. package/src/cli/session-mining/transcript.ts +26 -8
  410. package/src/context/session-manager.ts +19 -33
  411. package/src/core/CONTEXT.md +10 -6
  412. package/src/core/constraints/__tests__/capabilities-reconcile.test.ts +200 -0
  413. package/src/core/constraints/__tests__/capability-counts.test.ts +94 -0
  414. package/src/core/constraints/__tests__/git-evidence.test.ts +208 -0
  415. package/src/core/constraints/__tests__/injection-drift.test.ts +3 -10
  416. package/src/core/constraints/__tests__/injection-writer.test.ts +231 -0
  417. package/src/core/constraints/__tests__/trace-injection.test.ts +71 -0
  418. package/src/core/constraints/__tests__/usage-report.test.ts +112 -0
  419. package/src/core/constraints/agent-prompt-renderer.ts +2 -6
  420. package/src/core/constraints/capabilities-parser.ts +53 -35
  421. package/src/core/constraints/capabilities-reconcile.ts +166 -0
  422. package/src/core/constraints/checker.ts +82 -133
  423. package/src/core/constraints/checkers/__tests__/capability-sync.test.ts +273 -0
  424. package/src/core/constraints/checkers/__tests__/check-outcome.test.ts +176 -0
  425. package/src/core/constraints/checkers/__tests__/context-doc-sync.test.ts +77 -0
  426. package/src/core/constraints/checkers/__tests__/docs-freshness.test.ts +126 -0
  427. package/src/{__tests__ → core/constraints/checkers/__tests__}/governance-presence.test.ts +83 -9
  428. package/src/core/constraints/checkers/__tests__/iron-flags.test.ts +50 -0
  429. package/src/core/constraints/checkers/__tests__/no-bypass-checkpoint.test.ts +76 -0
  430. package/src/{__tests__ → core/constraints/checkers/__tests__}/no-hardcoded-credentials.test.ts +4 -3
  431. package/src/core/constraints/checkers/__tests__/no-test-simplification.test.ts +58 -0
  432. package/src/core/constraints/checkers/__tests__/three-state-consistency.test.ts +153 -0
  433. package/src/core/constraints/checkers/capability-sync.ts +75 -96
  434. package/src/core/constraints/checkers/context-doc-sync.ts +15 -25
  435. package/src/core/constraints/checkers/docs-freshness.ts +54 -70
  436. package/src/core/constraints/checkers/governance-presence.ts +7 -25
  437. package/src/core/constraints/checkers/index.ts +9 -2
  438. package/src/core/constraints/checkers/no-test-simplification.ts +4 -3
  439. package/src/core/constraints/checkers/types.ts +60 -4
  440. package/src/core/constraints/context-builder.ts +39 -91
  441. package/src/core/constraints/doc-freshness/runner.ts +2 -1
  442. package/src/core/constraints/git-evidence.ts +120 -0
  443. package/src/core/constraints/injection-drift.ts +13 -60
  444. package/src/core/constraints/injection-writer.ts +212 -0
  445. package/src/core/constraints/usage-report.ts +36 -17
  446. package/src/core/index.ts +4 -2
  447. package/src/core/project-config-loader.ts +49 -9
  448. package/src/core/validators/__tests__/passes-gate.test.ts +2 -56
  449. package/src/core/validators/__tests__/test-output.test.ts +372 -0
  450. package/src/core/validators/passes-gate.ts +86 -248
  451. package/src/core/validators/test-output.ts +128 -0
  452. package/src/failure/__tests__/recorder.test.ts +168 -0
  453. package/src/failure/recorder.ts +12 -10
  454. package/src/gates/CONTEXT.md +7 -4
  455. package/src/gates/__tests__/acceptance-types-single-source.test.ts +68 -0
  456. package/src/gates/__tests__/acceptance.test.ts +4 -86
  457. package/src/gates/__tests__/checker-gate.test.ts +24 -0
  458. package/src/gates/__tests__/effective-gates.test.ts +3 -8
  459. package/src/gates/__tests__/test-verdict-consistency.test.ts +140 -0
  460. package/src/gates/acceptance.ts +19 -84
  461. package/src/gates/checker-gate.ts +12 -15
  462. package/src/gates/command.ts +10 -16
  463. package/src/gates/contract.ts +22 -61
  464. package/src/gates/performance.ts +10 -22
  465. package/src/gates/review.ts +21 -41
  466. package/src/gates/security.ts +10 -22
  467. package/src/gates/types.ts +70 -5
  468. package/src/hooks/CONTEXT.md +1 -1
  469. package/src/hooks/bootstrap.ts +5 -2
  470. package/src/index.ts +0 -4
  471. package/src/knowledge/CONTEXT.md +8 -3
  472. package/src/knowledge/__tests__/audit-labels.test.ts +44 -0
  473. package/src/knowledge/__tests__/flywheel-metrics.test.ts +135 -0
  474. package/src/knowledge/__tests__/import.test.ts +44 -0
  475. package/src/knowledge/__tests__/index-generator.test.ts +53 -0
  476. package/src/knowledge/__tests__/ingest.test.ts +85 -0
  477. package/src/knowledge/__tests__/migration.test.ts +47 -0
  478. package/src/knowledge/__tests__/reference-tracker.test.ts +16 -0
  479. package/src/knowledge/__tests__/store.test.ts +194 -0
  480. package/src/knowledge/audit.ts +67 -71
  481. package/src/knowledge/flywheel-metrics.ts +71 -0
  482. package/src/knowledge/import.ts +4 -18
  483. package/src/knowledge/index-generator.ts +19 -14
  484. package/src/knowledge/ingest.ts +9 -4
  485. package/src/knowledge/migration.ts +11 -8
  486. package/src/knowledge/reference-tracker.ts +12 -8
  487. package/src/knowledge/store.ts +64 -11
  488. package/src/monitoring/CONTEXT.md +8 -3
  489. package/src/monitoring/__tests__/skipped-lines-report.test.ts +178 -0
  490. package/src/monitoring/__tests__/traces.test.ts +57 -0
  491. package/src/monitoring/context-tracker.ts +11 -23
  492. package/src/monitoring/index.ts +1 -1
  493. package/src/monitoring/trace-analyzer.ts +21 -2
  494. package/src/monitoring/traces.ts +39 -36
  495. package/src/release/CONTEXT.md +1 -0
  496. package/src/release/__tests__/barrel.test.ts +60 -0
  497. package/src/release/index.ts +2 -13
  498. package/src/sdd/__tests__/index-generator.test.ts +71 -0
  499. package/src/sdd/index-generator.ts +9 -9
  500. package/src/test-setup/__tests__/project-fixture.test.ts +178 -0
  501. package/src/test-setup/project-fixture.ts +87 -0
  502. package/src/tools/CONTEXT.md +6 -0
  503. package/src/tools/__tests__/registry.test.ts +221 -0
  504. package/src/types/__tests__/types.test.ts +4 -5
  505. package/src/types/constraint.ts +16 -27
  506. package/src/types/passes-gate.ts +10 -30
  507. package/src/types/project-config.ts +1 -1
  508. package/src/types/session.ts +5 -5
  509. package/src/types/trace.ts +10 -0
  510. package/src/utils/__tests__/frontmatter.test.ts +206 -0
  511. package/src/utils/__tests__/jsonl-skip-disposition.test.ts +175 -0
  512. package/src/utils/__tests__/jsonl.test.ts +187 -0
  513. package/src/utils/__tests__/package-version.test.ts +97 -0
  514. package/src/utils/exec.ts +15 -0
  515. package/src/utils/file-walk.ts +11 -2
  516. package/src/utils/frontmatter.ts +121 -0
  517. package/src/utils/jsonl.ts +167 -0
  518. package/src/utils/package-version.ts +27 -0
  519. package/dist/cli/commands/doc-freshness-check.d.ts +0 -53
  520. package/dist/cli/commands/doc-freshness-check.d.ts.map +0 -1
  521. package/dist/cli/commands/doc-freshness-check.js +0 -352
  522. package/dist/cli/commands/doc-freshness-check.js.map +0 -1
  523. package/dist/types/index.d.ts +0 -14
  524. package/dist/types/index.d.ts.map +0 -1
  525. package/dist/types/index.js +0 -39
  526. package/dist/types/index.js.map +0 -1
  527. package/src/__tests__/long-running.test.ts +0 -17
  528. package/src/__tests__/passes-gate-extension.test.ts +0 -151
  529. package/src/cli/commands/__tests__/doc-freshness-check.test.ts +0 -168
  530. package/src/cli/commands/doc-freshness-check.ts +0 -386
  531. package/src/spec/CONTEXT.md +0 -11
  532. package/src/types/index.ts +0 -47
package/dist/utils/frontmatter.d.ts ADDED
@@ -0,0 +1,73 @@
1
+ /**
2
+ * markdown frontmatter 解析/序列化正本（harness#89，架构评审 2026-09-02 候选10）
3
+ *
4
+ * `---\n<yaml>\n---\n<body>` 这一种语法此前在 knowledge 域 5 个文件里手写了 7 遍，
5
+ * 失败语义三派并存（store 静默丢条目 / migration 记 errors / index-generator 走
6
+ * best-effort / sdd 不要求闭合行完整 / ingest 只 strip 会把正文 `---` 误吞）。
7
+ * 语法与失败走法在此一处定义，仓内不允许存在第二份副本。
8
+ *
9
+ * 语法（唯一解释）：
10
+ * - 开界：偏移 0 处必须正好是一行 `---`（前面有空白行则不算 frontmatter）
11
+ * - 闭界：其后第一个**独立成行**的 `---`（`---x`、`----`、缩进 `---` 均不作闭合）
12
+ * - body：闭合行之后全部内容，紧随的一个空行被吃掉（与 join 的 `---\n\n` 包裹严格对称，
13
+ * 保证已落盘条目 load→save 字节稳定）
14
+ * - meta：闭合前的行经 YAML 解析，必须是 mapping
15
+ * - CRLF 文件不按 frontmatter 处理（与收口前各消费方一致，本 module 不新增解释）
16
+ *
17
+ * 三种畸形输入的走法（裁决 2，用例固定在 utils/__tests__/frontmatter.test.ts）：
18
+ * - 缺 frontmatter（无开界）→ 'absent'
19
+ * - 空 meta（闭合前只有空白，含零宽块）→ 'absent'——零宽元数据块不承载信息，
20
+ * 与「没有 frontmatter」同走一支，消费方按无元数据路径处理（store 视为非条目、
21
+ * index-generator 走 best-effort），无需上报
22
+ * - 未闭合（有开无闭 / 闭合行不完整）→ 'malformed' + reason 'unterminated'
23
+ * - meta 不是合法 YAML mapping（语法错、显式 null、标量或数组）→ 'malformed' + reason 'invalid-yaml'
24
+ *
25
+ * 消费方统一口径（裁决 2：不允许两派并存）：'malformed' 两支必须**显式上报**，
26
+ * 禁止静默丢数据；恢复动作按消费方语义选择并在代码里写明——
27
+ * 有结构化报告面的写报告（migration → result.errors），
28
+ * 纯扫描型的打一行 stderr（前缀 `[harness]`，与 failure/recorder.ts 的坏行告警同构）
29
+ * 后跳过或走 best-effort。'absent' 是合法输入，不上报。
30
+ *
31
+ * 序列化（裁决 3：收格式不收字段排序策略）：join 只负责包裹与 YAML dump 参数
32
+ * （lineWidth 120，与收口前 store/migration 逐字一致）；canonical 字段序是 store 的
33
+ * 私有策略，留在 store.toFrontmatter。
34
+ *
35
+ * 机械核查（期望命中数，均已实测）：
36
+ * grep -rnE '/\^---' src --include='*.ts' | grep -v __tests__
37
+ * → 期望 0 处：手写开界正则归零
38
+ * grep -rn "'---'" src --include='*.ts' | grep -v __tests__
39
+ * → 期望 1 处：本文件 DELIMITER
40
+ * grep -rn "yaml.load(metaText)\|yaml.dump(meta," src --include='*.ts' | grep -v __tests__
41
+ * → 期望 2 处：本文件 split 的 load + join 的 dump
42
+ * 豁免清单（不属 frontmatter，不改）：markdown 生成物里的 `---` 分隔线与表格分隔行
43
+ * （init / sync-docs / report / constraints-report 模板）、doc-freshness 的章节定位正则
44
+ * （`\n---` 是章节边界）、config.yml 与 checkpoint/tasks/progress 的 yaml.dump（单 YAML/JSON 文档）。
45
+ */
46
+ /** 'malformed' 的两支：消费方必须逐支显式处理（口径见文件头） */
47
+ export type FrontmatterMalformedReason = 'unterminated' | 'invalid-yaml';
48
+ /** frontmatter 元数据（已由 split 保证是 YAML mapping） */
49
+ export type FrontmatterMeta = Record<string, unknown>;
50
+ export type FrontmatterSplit = {
51
+ state: 'ok';
52
+ meta: FrontmatterMeta;
53
+ body: string;
54
+ } | {
55
+ state: 'absent';
56
+ } | {
57
+ state: 'malformed';
58
+ reason: FrontmatterMalformedReason;
59
+ detail: string;
60
+ };
61
+ /**
62
+ * 解析 markdown 的 YAML frontmatter。
63
+ *
64
+ * 不抛：三种畸形输入与 YAML 非法都体现在返回值 state/reason 上，由消费方按口径处置。
65
+ */
66
+ export declare function splitFrontmatter(raw: string): FrontmatterSplit;
67
+ /**
68
+ * 序列化为 `---\n<yaml>---\n\n<body>`（包裹格式与收口前 store/migration 逐字一致）。
69
+ *
70
+ * meta 的键序由调用方决定（store 保 canonical 序）；本函数只做包裹与 dump 参数。
71
+ */
72
+ export declare function joinFrontmatter(meta: FrontmatterMeta, body: string): string;
73
+ //# sourceMappingURL=frontmatter.d.ts.map
package/dist/utils/frontmatter.d.ts.map ADDED
@@ -0,0 +1 @@
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 ADDED
@@ -0,0 +1,141 @@
1
+ "use strict";
2
+ /**
3
+ * markdown frontmatter 解析/序列化正本（harness#89，架构评审 2026-09-02 候选10）
4
+ *
5
+ * `---\n<yaml>\n---\n<body>` 这一种语法此前在 knowledge 域 5 个文件里手写了 7 遍，
6
+ * 失败语义三派并存（store 静默丢条目 / migration 记 errors / index-generator 走
7
+ * best-effort / sdd 不要求闭合行完整 / ingest 只 strip 会把正文 `---` 误吞）。
8
+ * 语法与失败走法在此一处定义，仓内不允许存在第二份副本。
9
+ *
10
+ * 语法（唯一解释）：
11
+ * - 开界：偏移 0 处必须正好是一行 `---`（前面有空白行则不算 frontmatter）
12
+ * - 闭界：其后第一个**独立成行**的 `---`（`---x`、`----`、缩进 `---` 均不作闭合）
13
+ * - body：闭合行之后全部内容，紧随的一个空行被吃掉（与 join 的 `---\n\n` 包裹严格对称，
14
+ * 保证已落盘条目 load→save 字节稳定）
15
+ * - meta：闭合前的行经 YAML 解析，必须是 mapping
16
+ * - CRLF 文件不按 frontmatter 处理（与收口前各消费方一致，本 module 不新增解释）
17
+ *
18
+ * 三种畸形输入的走法（裁决 2，用例固定在 utils/__tests__/frontmatter.test.ts）：
19
+ * - 缺 frontmatter（无开界）→ 'absent'
20
+ * - 空 meta（闭合前只有空白，含零宽块）→ 'absent'——零宽元数据块不承载信息，
21
+ * 与「没有 frontmatter」同走一支，消费方按无元数据路径处理（store 视为非条目、
22
+ * index-generator 走 best-effort），无需上报
23
+ * - 未闭合（有开无闭 / 闭合行不完整）→ 'malformed' + reason 'unterminated'
24
+ * - meta 不是合法 YAML mapping（语法错、显式 null、标量或数组）→ 'malformed' + reason 'invalid-yaml'
25
+ *
26
+ * 消费方统一口径（裁决 2：不允许两派并存）：'malformed' 两支必须**显式上报**，
27
+ * 禁止静默丢数据；恢复动作按消费方语义选择并在代码里写明——
28
+ * 有结构化报告面的写报告（migration → result.errors），
29
+ * 纯扫描型的打一行 stderr（前缀 `[harness]`，与 failure/recorder.ts 的坏行告警同构）
30
+ * 后跳过或走 best-effort。'absent' 是合法输入，不上报。
31
+ *
32
+ * 序列化（裁决 3：收格式不收字段排序策略）：join 只负责包裹与 YAML dump 参数
33
+ * （lineWidth 120，与收口前 store/migration 逐字一致）；canonical 字段序是 store 的
34
+ * 私有策略，留在 store.toFrontmatter。
35
+ *
36
+ * 机械核查（期望命中数，均已实测）：
37
+ * grep -rnE '/\^---' src --include='*.ts' | grep -v __tests__
38
+ * → 期望 0 处：手写开界正则归零
39
+ * grep -rn "'---'" src --include='*.ts' | grep -v __tests__
40
+ * → 期望 1 处：本文件 DELIMITER
41
+ * grep -rn "yaml.load(metaText)\|yaml.dump(meta," src --include='*.ts' | grep -v __tests__
42
+ * → 期望 2 处：本文件 split 的 load + join 的 dump
43
+ * 豁免清单（不属 frontmatter，不改）：markdown 生成物里的 `---` 分隔线与表格分隔行
44
+ * （init / sync-docs / report / constraints-report 模板）、doc-freshness 的章节定位正则
45
+ * （`\n---` 是章节边界）、config.yml 与 checkpoint/tasks/progress 的 yaml.dump（单 YAML/JSON 文档）。
46
+ */
47
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
48
+ if (k2 === undefined) k2 = k;
49
+ var desc = Object.getOwnPropertyDescriptor(m, k);
50
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
51
+ desc = { enumerable: true, get: function() { return m[k]; } };
52
+ }
53
+ Object.defineProperty(o, k2, desc);
54
+ }) : (function(o, m, k, k2) {
55
+ if (k2 === undefined) k2 = k;
56
+ o[k2] = m[k];
57
+ }));
58
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
59
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
60
+ }) : function(o, v) {
61
+ o["default"] = v;
62
+ });
63
+ var __importStar = (this && this.__importStar) || (function () {
64
+ var ownKeys = function(o) {
65
+ ownKeys = Object.getOwnPropertyNames || function (o) {
66
+ var ar = [];
67
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
68
+ return ar;
69
+ };
70
+ return ownKeys(o);
71
+ };
72
+ return function (mod) {
73
+ if (mod && mod.__esModule) return mod;
74
+ var result = {};
75
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
76
+ __setModuleDefault(result, mod);
77
+ return result;
78
+ };
79
+ })();
80
+ Object.defineProperty(exports, "__esModule", { value: true });
81
+ exports.splitFrontmatter = splitFrontmatter;
82
+ exports.joinFrontmatter = joinFrontmatter;
83
+ const yaml = __importStar(require("js-yaml"));
84
+ /** frontmatter 界符（整行） */
85
+ const DELIMITER = '---';
86
+ /** 与收口前 store/migration 逐字一致的 YAML dump 行宽 */
87
+ const DUMP_LINE_WIDTH = 120;
88
+ /**
89
+ * 解析 markdown 的 YAML frontmatter。
90
+ *
91
+ * 不抛：三种畸形输入与 YAML 非法都体现在返回值 state/reason 上，由消费方按口径处置。
92
+ */
93
+ function splitFrontmatter(raw) {
94
+ const lines = raw.split('\n');
95
+ if (lines[0] !== DELIMITER)
96
+ return { state: 'absent' };
97
+ const closeIndex = lines.indexOf(DELIMITER, 1);
98
+ if (closeIndex === -1) {
99
+ return {
100
+ state: 'malformed',
101
+ reason: 'unterminated',
102
+ detail: `开界之后缺少独立成行的 ${DELIMITER} 闭合行`,
103
+ };
104
+ }
105
+ const metaLines = lines.slice(1, closeIndex);
106
+ if (metaLines.every(line => line.trim().length === 0))
107
+ return { state: 'absent' };
108
+ const metaText = metaLines.join('\n');
109
+ let parsed;
110
+ try {
111
+ parsed = yaml.load(metaText);
112
+ }
113
+ catch (error) {
114
+ return {
115
+ state: 'malformed',
116
+ reason: 'invalid-yaml',
117
+ // js-yaml 的 message 带多行代码片段，detail 只取首行描述——消费方要嵌进单行报告/stderr
118
+ detail: (error instanceof Error ? error.message : String(error)).split('\n')[0],
119
+ };
120
+ }
121
+ if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
122
+ return {
123
+ state: 'malformed',
124
+ reason: 'invalid-yaml',
125
+ detail: `frontmatter 必须是 YAML mapping，实际是 ${Array.isArray(parsed) ? 'array' : typeof parsed}`,
126
+ };
127
+ }
128
+ let bodyStart = closeIndex + 1;
129
+ if (lines[bodyStart] === '')
130
+ bodyStart++;
131
+ return { state: 'ok', meta: parsed, body: lines.slice(bodyStart).join('\n') };
132
+ }
133
+ /**
134
+ * 序列化为 `---\n<yaml>---\n\n<body>`（包裹格式与收口前 store/migration 逐字一致）。
135
+ *
136
+ * meta 的键序由调用方决定（store 保 canonical 序）；本函数只做包裹与 dump 参数。
137
+ */
138
+ function joinFrontmatter(meta, body) {
139
+ return `${DELIMITER}\n${yaml.dump(meta, { lineWidth: DUMP_LINE_WIDTH })}${DELIMITER}\n\n${body}`;
140
+ }
141
+ //# sourceMappingURL=frontmatter.js.map
package/dist/utils/frontmatter.js.map ADDED
@@ -0,0 +1 @@
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 ADDED
@@ -0,0 +1,92 @@
1
+ /**
2
+ * append-only JSONL 日志读写正本（harness#82，架构评审 2026-09-02 候选3）
3
+ *
4
+ * 全仓 append-only JSONL（traces.log / failures.log / context-tracker.log /
5
+ * references.jsonl / sessions/<id>/events.jsonl / 外部 transcript .jsonl）的
6
+ * exists → read → split → parse → filter 读链与 ensureDir + append 写链
7
+ * 收口于此，仓内不允许存在第二份副本。
8
+ *
9
+ * 坏行策略（harness#82 裁决 1）：读入口 policy 为显式必填参数，类型层面无缺省，
10
+ * 每个调用点必须逐一声明 'skip' | 'throw'——既不让「静默丢数据」成为框架缺省，
11
+ * 也不反转既有容错调用点的语义。坏行指非空但 JSON.parse 失败的行
12
+ * （半写入截断、手工编辑、磁盘满等）。
13
+ *
14
+ * tail / head：只解析尾部 / 头部 N 个非空行（文件仍全量读取，parse 才是大头），
15
+ * 供「只看最近 K 条」的调用点避免全量 parse（check 等热路径）。
16
+ * countJsonlLines 供纯计数消费方（完全不 parse）。
17
+ *
18
+ * 计数去向（harness#100）：本模块是坏行计数的唯一正本，但正本≠终点——凡以 'skip'
19
+ * 策略读，调用点必须把 skippedLines 带到该消费面的用户可见输出（CLI 走 stderr，
20
+ * 结构化输出与 API 走字段），或显式记名豁免并写明理由。机器可检面：
21
+ * `src/utils/__tests__/jsonl-skip-disposition.test.ts`（冻结站点集合 + 要求每个读点
22
+ * 上方声明 `计数去向：`）。
23
+ *
24
+ * 豁免清单与机械核查（期望命中数）：
25
+ * grep -rnE "JSON\.parse\((line|trimmed|l)\b" src --include='*.ts' | grep -v __tests__
26
+ * → 期望 1 处：本文件 readJsonl（读链正本本体）
27
+ * grep -rn "map(JSON.parse" src --include='*.ts' | grep -v __tests__
28
+ * → 期望 0 处
29
+ * __tests__ 下的坏行 fixture 不在核查范围。
30
+ * 其余裁决豁免：readIfExists（injection-writer，string|null 形态不同，#82 裁决 3）；
31
+ * FailureRecorder 轮换链（文件生命周期不变量，裁决 2）；
32
+ * 单 JSON 文档读取（package.json / .state.json / checkpoint.json / summary 等非 JSONL）。
33
+ */
34
+ /**
35
+ * 坏行策略
36
+ *
37
+ * - 'skip'：跳过损坏行，继续解析；skippedLines 计数
38
+ * - 'throw'：损坏行直接上抛（沿用原抛语义的调用点显式选择）
39
+ */
40
+ export type JsonlBadLinePolicy = 'skip' | 'throw';
41
+ export interface JsonlReadResult<T> {
42
+ records: T[];
43
+ /**
44
+ * 被跳过的坏行数（'throw' 策略下恒为 0）
45
+ *
46
+ * 拿到它不等于告知：skip 读点必须把它带到消费面的用户可见输出或记名豁免（harness#100）
47
+ */
48
+ skippedLines: number;
49
+ }
50
+ export interface JsonlReadOptions {
51
+ /** 只解析最后 N 个非空行（尾部读取） */
52
+ tail?: number;
53
+ /** 只解析前 N 个非空行（头部读取） */
54
+ head?: number;
55
+ }
56
+ /**
57
+ * 读取 JSONL 文件：exists → read → split → parse → filter（正本读链）
58
+ *
59
+ * policy 必填无缺省（裁决 1）；缺文件返回空结果，不抛。
60
+ */
61
+ export declare function readJsonl<T>(filePath: string, policy: JsonlBadLinePolicy, options?: JsonlReadOptions): JsonlReadResult<T>;
62
+ /**
63
+ * 统计非空行数（含坏行，完全不 parse）
64
+ *
65
+ * 供只关心记录条数的调用点（如 check 智能提示）避免全量 parse；
66
+ * 缺文件返回 0。
67
+ */
68
+ export declare function countJsonlLines(filePath: string): number;
69
+ export interface JsonlEndsResult<T> {
70
+ /** 原始非空行数（合法 + 坏行），与 records.length + skippedLines 同口径 */
71
+ totalLines: number;
72
+ /** 自首向尾第一条合法记录；无合法记录为 undefined */
73
+ first?: T;
74
+ /** 自尾向首第一条合法记录；无合法记录为 undefined */
75
+ last?: T;
76
+ }
77
+ /**
78
+ * 只取首尾：首/末条合法记录 + 原始行数，parse 停在两端首个合法行
79
+ *
80
+ * 供只要「总数 + 首末记录」的调用点（如 TraceCollector.getStats）避免全量
81
+ * parse；行文本仍整读（10MB 级文本读廉价，JSON.parse 才是成本）。坏行策略
82
+ * 同 readJsonl：'skip' 跳过继续找，'throw' 遇坏行上抛。缺文件返回
83
+ * { totalLines: 0 }。
84
+ */
85
+ export declare function readJsonlEnds<T>(filePath: string, policy: JsonlBadLinePolicy): JsonlEndsResult<T>;
86
+ /**
87
+ * 追加一条 JSONL 记录：ensureDir + append（正本写链）
88
+ *
89
+ * 目录不存在时递归创建；value 序列化为单行 JSON + 换行。
90
+ */
91
+ export declare function appendJsonl(filePath: string, value: unknown): void;
92
+ //# sourceMappingURL=jsonl.d.ts.map
package/dist/utils/jsonl.d.ts.map ADDED
@@ -0,0 +1 @@
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 ADDED
@@ -0,0 +1,166 @@
1
+ "use strict";
2
+ /**
3
+ * append-only JSONL 日志读写正本（harness#82，架构评审 2026-09-02 候选3）
4
+ *
5
+ * 全仓 append-only JSONL（traces.log / failures.log / context-tracker.log /
6
+ * references.jsonl / sessions/<id>/events.jsonl / 外部 transcript .jsonl）的
7
+ * exists → read → split → parse → filter 读链与 ensureDir + append 写链
8
+ * 收口于此，仓内不允许存在第二份副本。
9
+ *
10
+ * 坏行策略（harness#82 裁决 1）：读入口 policy 为显式必填参数，类型层面无缺省，
11
+ * 每个调用点必须逐一声明 'skip' | 'throw'——既不让「静默丢数据」成为框架缺省，
12
+ * 也不反转既有容错调用点的语义。坏行指非空但 JSON.parse 失败的行
13
+ * （半写入截断、手工编辑、磁盘满等）。
14
+ *
15
+ * tail / head：只解析尾部 / 头部 N 个非空行（文件仍全量读取，parse 才是大头），
16
+ * 供「只看最近 K 条」的调用点避免全量 parse（check 等热路径）。
17
+ * countJsonlLines 供纯计数消费方（完全不 parse）。
18
+ *
19
+ * 计数去向（harness#100）：本模块是坏行计数的唯一正本，但正本≠终点——凡以 'skip'
20
+ * 策略读，调用点必须把 skippedLines 带到该消费面的用户可见输出（CLI 走 stderr，
21
+ * 结构化输出与 API 走字段），或显式记名豁免并写明理由。机器可检面：
22
+ * `src/utils/__tests__/jsonl-skip-disposition.test.ts`（冻结站点集合 + 要求每个读点
23
+ * 上方声明 `计数去向：`）。
24
+ *
25
+ * 豁免清单与机械核查（期望命中数）：
26
+ * grep -rnE "JSON\.parse\((line|trimmed|l)\b" src --include='*.ts' | grep -v __tests__
27
+ * → 期望 1 处：本文件 readJsonl（读链正本本体）
28
+ * grep -rn "map(JSON.parse" src --include='*.ts' | grep -v __tests__
29
+ * → 期望 0 处
30
+ * __tests__ 下的坏行 fixture 不在核查范围。
31
+ * 其余裁决豁免：readIfExists（injection-writer，string|null 形态不同，#82 裁决 3）；
32
+ * FailureRecorder 轮换链（文件生命周期不变量，裁决 2）；
33
+ * 单 JSON 文档读取（package.json / .state.json / checkpoint.json / summary 等非 JSONL）。
34
+ */
35
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
36
+ if (k2 === undefined) k2 = k;
37
+ var desc = Object.getOwnPropertyDescriptor(m, k);
38
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
39
+ desc = { enumerable: true, get: function() { return m[k]; } };
40
+ }
41
+ Object.defineProperty(o, k2, desc);
42
+ }) : (function(o, m, k, k2) {
43
+ if (k2 === undefined) k2 = k;
44
+ o[k2] = m[k];
45
+ }));
46
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
47
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
48
+ }) : function(o, v) {
49
+ o["default"] = v;
50
+ });
51
+ var __importStar = (this && this.__importStar) || (function () {
52
+ var ownKeys = function(o) {
53
+ ownKeys = Object.getOwnPropertyNames || function (o) {
54
+ var ar = [];
55
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
56
+ return ar;
57
+ };
58
+ return ownKeys(o);
59
+ };
60
+ return function (mod) {
61
+ if (mod && mod.__esModule) return mod;
62
+ var result = {};
63
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
64
+ __setModuleDefault(result, mod);
65
+ return result;
66
+ };
67
+ })();
68
+ Object.defineProperty(exports, "__esModule", { value: true });
69
+ exports.readJsonl = readJsonl;
70
+ exports.countJsonlLines = countJsonlLines;
71
+ exports.readJsonlEnds = readJsonlEnds;
72
+ exports.appendJsonl = appendJsonl;
73
+ const fs = __importStar(require("fs"));
74
+ const path = __importStar(require("path"));
75
+ /** exists → read → split → filter 空行的公共前缀（正本唯一一份） */
76
+ function readNonEmptyLines(filePath) {
77
+ if (!fs.existsSync(filePath))
78
+ return [];
79
+ return fs
80
+ .readFileSync(filePath, 'utf-8')
81
+ .split('\n')
82
+ .filter(line => line.trim().length > 0);
83
+ }
84
+ /**
85
+ * 读取 JSONL 文件：exists → read → split → parse → filter（正本读链）
86
+ *
87
+ * policy 必填无缺省（裁决 1）；缺文件返回空结果，不抛。
88
+ */
89
+ function readJsonl(filePath, policy, options) {
90
+ let lines = readNonEmptyLines(filePath);
91
+ if (options?.head !== undefined) {
92
+ lines = options.head > 0 ? lines.slice(0, options.head) : [];
93
+ }
94
+ if (options?.tail !== undefined) {
95
+ lines = options.tail > 0 ? lines.slice(-options.tail) : [];
96
+ }
97
+ const records = [];
98
+ let skippedLines = 0;
99
+ for (const line of lines) {
100
+ try {
101
+ records.push(JSON.parse(line));
102
+ }
103
+ catch (error) {
104
+ if (policy === 'throw')
105
+ throw error;
106
+ skippedLines++;
107
+ }
108
+ }
109
+ return { records, skippedLines };
110
+ }
111
+ /**
112
+ * 统计非空行数（含坏行，完全不 parse）
113
+ *
114
+ * 供只关心记录条数的调用点（如 check 智能提示）避免全量 parse；
115
+ * 缺文件返回 0。
116
+ */
117
+ function countJsonlLines(filePath) {
118
+ return readNonEmptyLines(filePath).length;
119
+ }
120
+ /**
121
+ * 只取首尾：首/末条合法记录 + 原始行数，parse 停在两端首个合法行
122
+ *
123
+ * 供只要「总数 + 首末记录」的调用点（如 TraceCollector.getStats）避免全量
124
+ * parse；行文本仍整读（10MB 级文本读廉价，JSON.parse 才是成本）。坏行策略
125
+ * 同 readJsonl：'skip' 跳过继续找，'throw' 遇坏行上抛。缺文件返回
126
+ * { totalLines: 0 }。
127
+ */
128
+ function readJsonlEnds(filePath, policy) {
129
+ const lines = readNonEmptyLines(filePath);
130
+ let first;
131
+ for (let i = 0; i < lines.length; i++) {
132
+ try {
133
+ first = JSON.parse(lines[i]);
134
+ break;
135
+ }
136
+ catch (error) {
137
+ if (policy === 'throw')
138
+ throw error;
139
+ }
140
+ }
141
+ let last;
142
+ for (let i = lines.length - 1; i >= 0; i--) {
143
+ try {
144
+ last = JSON.parse(lines[i]);
145
+ break;
146
+ }
147
+ catch (error) {
148
+ if (policy === 'throw')
149
+ throw error;
150
+ }
151
+ }
152
+ return { totalLines: lines.length, first, last };
153
+ }
154
+ /**
155
+ * 追加一条 JSONL 记录：ensureDir + append（正本写链）
156
+ *
157
+ * 目录不存在时递归创建；value 序列化为单行 JSON + 换行。
158
+ */
159
+ function appendJsonl(filePath, value) {
160
+ const dir = path.dirname(filePath);
161
+ if (!fs.existsSync(dir)) {
162
+ fs.mkdirSync(dir, { recursive: true });
163
+ }
164
+ fs.appendFileSync(filePath, JSON.stringify(value) + '\n', 'utf-8');
165
+ }
166
+ //# sourceMappingURL=jsonl.js.map
package/dist/utils/jsonl.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"jsonl.js","sourceRoot":"","sources":["../../src/utils/jsonl.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CH,8BAwBC;AAQD,0CAEC;AAmBD,sCAwBC;AAOD,kCAMC;AApID,uCAAyB;AACzB,2CAA6B;AA2B7B,qDAAqD;AACrD,SAAS,iBAAiB,CAAC,QAAgB;IACzC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,CAAC;IACxC,OAAO,EAAE;SACN,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC;SAC/B,KAAK,CAAC,IAAI,CAAC;SACX,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,SAAgB,SAAS,CACvB,QAAgB,EAChB,MAA0B,EAC1B,OAA0B;IAE1B,IAAI,KAAK,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IACxC,IAAI,OAAO,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC;QAChC,KAAK,GAAG,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/D,CAAC;IACD,IAAI,OAAO,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC;QAChC,KAAK,GAAG,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7D,CAAC;IAED,MAAM,OAAO,GAAQ,EAAE,CAAC;IACxB,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,MAAM,KAAK,OAAO;gBAAE,MAAM,KAAK,CAAC;YACpC,YAAY,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;AACnC,CAAC;AAED;;;;;GAKG;AACH,SAAgB,eAAe,CAAC,QAAgB;IAC9C,OAAO,iBAAiB,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC;AAC5C,CAAC;AAWD;;;;;;;GAOG;AACH,SAAgB,aAAa,CAAI,QAAgB,EAAE,MAA0B;IAC3E,MAAM,KAAK,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAE1C,IAAI,KAAoB,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAM,CAAC;YAClC,MAAM;QACR,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,MAAM,KAAK,OAAO;gBAAE,MAAM,KAAK,CAAC;QACtC,CAAC;IACH,CAAC;IAED,IAAI,IAAmB,CAAC;IACxB,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAM,CAAC;YACjC,MAAM;QACR,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,MAAM,KAAK,OAAO;gBAAE,MAAM,KAAK,CAAC;QACtC,CAAC;IACH,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,SAAgB,WAAW,CAAC,QAAgB,EAAE,KAAc;IAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;IACD,EAAE,CAAC,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;AACrE,CAAC"}
package/dist/utils/package-version.d.ts ADDED
@@ -0,0 +1,16 @@
1
+ /**
2
+ * harness 包版本读取正本（#102，架构评审 A3）
3
+ *
4
+ * 「harness 包版本」此前散在四处五种写法（constraints.ts 带 cwd 兜底、init.ts
5
+ * require 与内联各一份、injection-drift.ts / constraints-retire.ts __dirname
6
+ * 相对路径）。其中 cwd 兜底在 harness 装进消费者 node_modules 且相对路径失败时
7
+ * 会读到**消费者自己的版本号**——这是本模块要消灭的 bug。语义在此一处定义：
8
+ *
9
+ * - 只读本模块自身的 package.json（__dirname 相对；src 与 dist 目录深度一致，
10
+ * 两种加载方式命中同一份清单）；
11
+ * - 无 cwd 兜底——cwd 的 package.json 是消费者项目的，不是 harness 的；
12
+ * - 清单缺失/损坏/无 version 字段 → 'unknown'（沿用收口前各处一致语义）。
13
+ */
14
+ /** 读取 harness 包版本；读不到（缺失/损坏/无 version 字段）返回 'unknown' */
15
+ export declare function getHarnessPackageVersion(): string;
16
+ //# sourceMappingURL=package-version.d.ts.map
package/dist/utils/package-version.d.ts.map ADDED
@@ -0,0 +1 @@
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"}
package/dist/utils/package-version.js ADDED
@@ -0,0 +1,63 @@
1
+ "use strict";
2
+ /**
3
+ * harness 包版本读取正本（#102，架构评审 A3）
4
+ *
5
+ * 「harness 包版本」此前散在四处五种写法（constraints.ts 带 cwd 兜底、init.ts
6
+ * require 与内联各一份、injection-drift.ts / constraints-retire.ts __dirname
7
+ * 相对路径）。其中 cwd 兜底在 harness 装进消费者 node_modules 且相对路径失败时
8
+ * 会读到**消费者自己的版本号**——这是本模块要消灭的 bug。语义在此一处定义：
9
+ *
10
+ * - 只读本模块自身的 package.json（__dirname 相对；src 与 dist 目录深度一致，
11
+ * 两种加载方式命中同一份清单）；
12
+ * - 无 cwd 兜底——cwd 的 package.json 是消费者项目的，不是 harness 的；
13
+ * - 清单缺失/损坏/无 version 字段 → 'unknown'（沿用收口前各处一致语义）。
14
+ */
15
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
16
+ if (k2 === undefined) k2 = k;
17
+ var desc = Object.getOwnPropertyDescriptor(m, k);
18
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
19
+ desc = { enumerable: true, get: function() { return m[k]; } };
20
+ }
21
+ Object.defineProperty(o, k2, desc);
22
+ }) : (function(o, m, k, k2) {
23
+ if (k2 === undefined) k2 = k;
24
+ o[k2] = m[k];
25
+ }));
26
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
27
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
28
+ }) : function(o, v) {
29
+ o["default"] = v;
30
+ });
31
+ var __importStar = (this && this.__importStar) || (function () {
32
+ var ownKeys = function(o) {
33
+ ownKeys = Object.getOwnPropertyNames || function (o) {
34
+ var ar = [];
35
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
36
+ return ar;
37
+ };
38
+ return ownKeys(o);
39
+ };
40
+ return function (mod) {
41
+ if (mod && mod.__esModule) return mod;
42
+ var result = {};
43
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
44
+ __setModuleDefault(result, mod);
45
+ return result;
46
+ };
47
+ })();
48
+ Object.defineProperty(exports, "__esModule", { value: true });
49
+ exports.getHarnessPackageVersion = getHarnessPackageVersion;
50
+ const fs = __importStar(require("fs"));
51
+ const path = __importStar(require("path"));
52
+ /** 读取 harness 包版本；读不到（缺失/损坏/无 version 字段）返回 'unknown' */
53
+ function getHarnessPackageVersion() {
54
+ try {
55
+ const pkgPath = path.join(__dirname, '..', '..', 'package.json');
56
+ const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
57
+ return typeof pkg.version === 'string' && pkg.version ? pkg.version : 'unknown';
58
+ }
59
+ catch {
60
+ return 'unknown';
61
+ }
62
+ }
63
+ //# sourceMappingURL=package-version.js.map
package/dist/utils/package-version.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"package-version.js","sourceRoot":"","sources":["../../src/utils/package-version.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAMH,4DAQC;AAZD,uCAAyB;AACzB,2CAA6B;AAE7B,yDAAyD;AACzD,SAAgB,wBAAwB;IACtC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;QACjE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QAC1D,OAAO,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAClF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dommaker/harness",
3
- "version": "1.3.0",
3
+ "version": "1.5.0",
4
4
  "description": "通用工程约束框架 - 铁律系统、检查点验证、测试门控",
5
5
  "keywords": [
6
6
  "harness",
package/src/CONTEXT.md CHANGED
@@ -19,7 +19,8 @@
19
19
  | failure/ | 错误分类、失败记录 |
20
20
  | context/ | 会话管理、token 预算、压缩、知识注入 |
21
21
  | spec/ | （空目录）@spec 注释检查已删（ADR-0003）；spec 故事见 core/spec/validator + SpecAcceptanceGate |
22
- | cli/commands/ | 24 个 CLI 子命令 |
22
+ | cli/commands/ | 23 个 CLI 子命令 |
23
+ | test-setup/ | 测试夹具层：`project-fixture` 构造临时项目根（config/traces/files 声明式落盘，非缺省根显式 opt-out）、`mkdtemp-cleanup` 统一回收 |
23
24
  | tools/ | 工具定义 |
24
25
 
25
26
  ## 依赖关系
@@ -38,8 +39,13 @@
38
39
  | GateDecision | 三态决策 `deny \| abstain \| ask`；deny 单调（下游不可改回 allow）、ask 枚举预留 fail-closed = deny |
39
40
  | GateResult | 报告结构（gate/passed/message/details/timestamp/duration），保留为报告层，不作决策 |
40
41
  | 守卫 guard | 仅 dsh 借鉴语境（工具管线单调守卫），不进入 harness 命名 |
41
- | 回滚 | 分工：版本化回退（单段——yml 数据文件 git 版本化，删段恢复）+ 提案回滚（多段 inverse，挂 #82 D6） |
42
+ | 回滚 | 分工：版本化回退（单段——yml 数据文件 git 版本化，删段恢复）+ 提案回滚（多段 inverse，挂 studio#82 D6） |
42
43
  | 文件驱动 CLI | yml 状态真值 + 一次性进程、无常驻生命周期；故不引 dispose 链（止步档 1） |
44
+ | 对照（reconcile） | CAPABILITIES.md 声明与源码实况的双向一致性判定（代码→文档查漏登，文档→代码查幽灵）；唯一实现 `core/constraints/capabilities-reconcile.ts`，capability_sync / docs_freshness / sync-docs 共消费（ADR-0009） |
45
+ | 判定证据（evidence） | checker 随判定一并返回的路径级依据（`CheckDetail{pass, evidence}`，harness#119/ADR-0016）；文案由 checker 措辞、消费端只打印，出口 = `ConstraintResult` / CLI 输出 / trace / 铁律异常文案。不是第四种统计态：**违规** = 与本次变更有因果（进 pass/fail 分母），**提示** = `pass:true` + evidence（仓库级漂移等无因果缺口，只露出不拦） |
46
+ | 测试产物解读（test-output） | 从测试运行器 stdout 读出「过了没 / 哪些失败 / 覆盖率」的判定；唯一实现 `core/validators/test-output.ts`（包内，不进导出面），passes-gate / acceptance 共消费（ADR-0012）。两门禁判定依据不一致待 #93 裁决，覆盖率取数归属待 #94 裁决 |
47
+ | 飞轮指标（flywheel） | 知识条目的引用与消费度量（refCoverage / avgRefs / consumptionHitRate）；唯一实现 `knowledge/flywheel-metrics.ts`（包内，不进导出面），canonical 分子为过滤 synthetic 后的 genuine refs，audit D6 / knowledge stats / knowledge health 共消费（ADR-0013，#81） |
48
+ | 测试夹具（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） |
43
49
 
44
50
  ## 注意事项
45
51
  - 公共包，禁止硬编码业务路径
package/src/__tests__/acceptance-gate.test.ts CHANGED
@@ -3,7 +3,9 @@
3
3
  */
4
4
 
5
5
  import { describe, it, expect, beforeAll, afterAll, beforeEach } from '@jest/globals';
6
- import { SpecAcceptanceGate, createSpecAcceptanceGate } from '../gates/acceptance';
6
+ import { SpecAcceptanceGate } from '../gates/acceptance';
7
+ // 工厂与公共面同一 seam：gates/index 是唯一出口（harness#101）
8
+ import { createSpecAcceptanceGate } from '../gates/index';
7
9
  import * as fs from 'fs';
8
10
  import * as path from 'path';
9
11
  import * as yaml from 'js-yaml';