@dommaker/harness 1.2.3 → 1.4.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 (550) hide show
  1. package/CHANGELOG.md +15 -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 +76 -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 +30 -215
  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 +33 -26
  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 +21 -15
  53. package/dist/cli/commands/knowledge.d.ts.map +1 -1
  54. package/dist/cli/commands/knowledge.js +237 -199
  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 +73 -77
  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 +31 -16
  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 +2 -1
  115. package/dist/cli/commands/update-user-model.d.ts.map +1 -1
  116. package/dist/cli/commands/update-user-model.js +31 -45
  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/completion-checkers/index.d.ts +3 -3
  127. package/dist/completion-checkers/index.js +3 -3
  128. package/dist/completion-checkers/phase-format.d.ts +1 -1
  129. package/dist/completion-checkers/phase-format.js +2 -2
  130. package/dist/completion-checkers/phase-format.js.map +1 -1
  131. package/dist/completion-checkers/tdd-chain.d.ts +1 -1
  132. package/dist/completion-checkers/tdd-chain.js +2 -2
  133. package/dist/completion-checkers/tdd-chain.js.map +1 -1
  134. package/dist/completion-checkers/types.d.ts +5 -5
  135. package/dist/completion-checkers/types.d.ts.map +1 -1
  136. package/dist/completion-checkers/types.js +2 -2
  137. package/dist/context/session-manager.d.ts.map +1 -1
  138. package/dist/context/session-manager.js +19 -32
  139. package/dist/context/session-manager.js.map +1 -1
  140. package/dist/core/constraints/agent-prompt-renderer.d.ts.map +1 -1
  141. package/dist/core/constraints/agent-prompt-renderer.js +1 -4
  142. package/dist/core/constraints/agent-prompt-renderer.js.map +1 -1
  143. package/dist/core/constraints/capabilities-parser.d.ts +24 -7
  144. package/dist/core/constraints/capabilities-parser.d.ts.map +1 -1
  145. package/dist/core/constraints/capabilities-parser.js +32 -28
  146. package/dist/core/constraints/capabilities-parser.js.map +1 -1
  147. package/dist/core/constraints/capabilities-reconcile.d.ts +67 -0
  148. package/dist/core/constraints/capabilities-reconcile.d.ts.map +1 -0
  149. package/dist/core/constraints/capabilities-reconcile.js +105 -0
  150. package/dist/core/constraints/capabilities-reconcile.js.map +1 -0
  151. package/dist/core/constraints/checker.d.ts +21 -43
  152. package/dist/core/constraints/checker.d.ts.map +1 -1
  153. package/dist/core/constraints/checker.js +64 -115
  154. package/dist/core/constraints/checker.js.map +1 -1
  155. package/dist/core/constraints/checkers/capability-sync.d.ts +4 -3
  156. package/dist/core/constraints/checkers/capability-sync.d.ts.map +1 -1
  157. package/dist/core/constraints/checkers/capability-sync.js +29 -69
  158. package/dist/core/constraints/checkers/capability-sync.js.map +1 -1
  159. package/dist/core/constraints/checkers/context-doc-sync.d.ts +4 -2
  160. package/dist/core/constraints/checkers/context-doc-sync.d.ts.map +1 -1
  161. package/dist/core/constraints/checkers/context-doc-sync.js +13 -22
  162. package/dist/core/constraints/checkers/context-doc-sync.js.map +1 -1
  163. package/dist/core/constraints/checkers/docs-freshness.d.ts.map +1 -1
  164. package/dist/core/constraints/checkers/docs-freshness.js +37 -63
  165. package/dist/core/constraints/checkers/docs-freshness.js.map +1 -1
  166. package/dist/core/constraints/checkers/governance-presence.d.ts +2 -2
  167. package/dist/core/constraints/checkers/governance-presence.d.ts.map +1 -1
  168. package/dist/core/constraints/checkers/governance-presence.js +7 -28
  169. package/dist/core/constraints/checkers/governance-presence.js.map +1 -1
  170. package/dist/core/constraints/checkers/no-test-simplification.d.ts.map +1 -1
  171. package/dist/core/constraints/checkers/no-test-simplification.js +4 -3
  172. package/dist/core/constraints/checkers/no-test-simplification.js.map +1 -1
  173. package/dist/core/constraints/checkers/types.d.ts +2 -2
  174. package/dist/core/constraints/context-builder.d.ts +15 -14
  175. package/dist/core/constraints/context-builder.d.ts.map +1 -1
  176. package/dist/core/constraints/context-builder.js +32 -96
  177. package/dist/core/constraints/context-builder.js.map +1 -1
  178. package/dist/core/constraints/doc-freshness/runner.d.ts.map +1 -1
  179. package/dist/core/constraints/doc-freshness/runner.js +2 -1
  180. package/dist/core/constraints/doc-freshness/runner.js.map +1 -1
  181. package/dist/core/constraints/git-evidence.d.ts +60 -0
  182. package/dist/core/constraints/git-evidence.d.ts.map +1 -0
  183. package/dist/core/constraints/git-evidence.js +88 -0
  184. package/dist/core/constraints/git-evidence.js.map +1 -0
  185. package/dist/core/constraints/injection-drift.d.ts +3 -20
  186. package/dist/core/constraints/injection-drift.d.ts.map +1 -1
  187. package/dist/core/constraints/injection-drift.js +10 -57
  188. package/dist/core/constraints/injection-drift.js.map +1 -1
  189. package/dist/core/constraints/injection-writer.d.ts +113 -0
  190. package/dist/core/constraints/injection-writer.d.ts.map +1 -0
  191. package/dist/core/constraints/injection-writer.js +228 -0
  192. package/dist/core/constraints/injection-writer.js.map +1 -0
  193. package/dist/core/constraints/usage-report.d.ts +22 -1
  194. package/dist/core/constraints/usage-report.d.ts.map +1 -1
  195. package/dist/core/constraints/usage-report.js +27 -20
  196. package/dist/core/constraints/usage-report.js.map +1 -1
  197. package/dist/core/index.d.ts +2 -2
  198. package/dist/core/index.d.ts.map +1 -1
  199. package/dist/core/index.js +4 -2
  200. package/dist/core/index.js.map +1 -1
  201. package/dist/core/project-config-loader.d.ts +32 -1
  202. package/dist/core/project-config-loader.d.ts.map +1 -1
  203. package/dist/core/project-config-loader.js +39 -9
  204. package/dist/core/project-config-loader.js.map +1 -1
  205. package/dist/core/validators/passes-gate.d.ts +15 -64
  206. package/dist/core/validators/passes-gate.d.ts.map +1 -1
  207. package/dist/core/validators/passes-gate.js +84 -222
  208. package/dist/core/validators/passes-gate.js.map +1 -1
  209. package/dist/core/validators/test-output.d.ts +58 -0
  210. package/dist/core/validators/test-output.d.ts.map +1 -0
  211. package/dist/core/validators/test-output.js +109 -0
  212. package/dist/core/validators/test-output.js.map +1 -0
  213. package/dist/failure/recorder.d.ts +7 -1
  214. package/dist/failure/recorder.d.ts.map +1 -1
  215. package/dist/failure/recorder.js +13 -9
  216. package/dist/failure/recorder.js.map +1 -1
  217. package/dist/gates/acceptance.d.ts +1 -48
  218. package/dist/gates/acceptance.d.ts.map +1 -1
  219. package/dist/gates/acceptance.js +6 -38
  220. package/dist/gates/acceptance.js.map +1 -1
  221. package/dist/gates/checker-gate.d.ts.map +1 -1
  222. package/dist/gates/checker-gate.js +6 -11
  223. package/dist/gates/checker-gate.js.map +1 -1
  224. package/dist/gates/command.d.ts.map +1 -1
  225. package/dist/gates/command.js +10 -22
  226. package/dist/gates/command.js.map +1 -1
  227. package/dist/gates/contract.d.ts.map +1 -1
  228. package/dist/gates/contract.js +22 -61
  229. package/dist/gates/contract.js.map +1 -1
  230. package/dist/gates/performance.d.ts.map +1 -1
  231. package/dist/gates/performance.js +13 -31
  232. package/dist/gates/performance.js.map +1 -1
  233. package/dist/gates/review.d.ts.map +1 -1
  234. package/dist/gates/review.js +21 -53
  235. package/dist/gates/review.js.map +1 -1
  236. package/dist/gates/security.d.ts.map +1 -1
  237. package/dist/gates/security.js +14 -32
  238. package/dist/gates/security.js.map +1 -1
  239. package/dist/gates/types.d.ts +28 -5
  240. package/dist/gates/types.d.ts.map +1 -1
  241. package/dist/gates/types.js +38 -1
  242. package/dist/gates/types.js.map +1 -1
  243. package/dist/hooks/bootstrap.d.ts +2 -0
  244. package/dist/hooks/bootstrap.d.ts.map +1 -1
  245. package/dist/hooks/bootstrap.js +5 -2
  246. package/dist/hooks/bootstrap.js.map +1 -1
  247. package/dist/index.d.ts +4 -3
  248. package/dist/index.d.ts.map +1 -1
  249. package/dist/index.js +13 -4
  250. package/dist/index.js.map +1 -1
  251. package/dist/knowledge/audit.d.ts +7 -2
  252. package/dist/knowledge/audit.d.ts.map +1 -1
  253. package/dist/knowledge/audit.js +59 -79
  254. package/dist/knowledge/audit.js.map +1 -1
  255. package/dist/knowledge/flywheel-metrics.d.ts +39 -0
  256. package/dist/knowledge/flywheel-metrics.d.ts.map +1 -0
  257. package/dist/knowledge/flywheel-metrics.js +47 -0
  258. package/dist/knowledge/flywheel-metrics.js.map +1 -0
  259. package/dist/knowledge/import.d.ts.map +1 -1
  260. package/dist/knowledge/import.js +4 -14
  261. package/dist/knowledge/import.js.map +1 -1
  262. package/dist/knowledge/index-generator.d.ts.map +1 -1
  263. package/dist/knowledge/index-generator.js +18 -15
  264. package/dist/knowledge/index-generator.js.map +1 -1
  265. package/dist/knowledge/ingest.d.ts.map +1 -1
  266. package/dist/knowledge/ingest.js +9 -4
  267. package/dist/knowledge/ingest.js.map +1 -1
  268. package/dist/knowledge/migration.d.ts.map +1 -1
  269. package/dist/knowledge/migration.js +11 -8
  270. package/dist/knowledge/migration.js.map +1 -1
  271. package/dist/knowledge/reference-tracker.d.ts.map +1 -1
  272. package/dist/knowledge/reference-tracker.js +12 -9
  273. package/dist/knowledge/reference-tracker.js.map +1 -1
  274. package/dist/knowledge/store.d.ts +15 -0
  275. package/dist/knowledge/store.d.ts.map +1 -1
  276. package/dist/knowledge/store.js +59 -10
  277. package/dist/knowledge/store.js.map +1 -1
  278. package/dist/monitoring/context-tracker.d.ts.map +1 -1
  279. package/dist/monitoring/context-tracker.js +11 -20
  280. package/dist/monitoring/context-tracker.js.map +1 -1
  281. package/dist/monitoring/index.d.ts +1 -1
  282. package/dist/monitoring/index.d.ts.map +1 -1
  283. package/dist/monitoring/index.js +1 -2
  284. package/dist/monitoring/index.js.map +1 -1
  285. package/dist/monitoring/trace-analyzer.d.ts +15 -0
  286. package/dist/monitoring/trace-analyzer.d.ts.map +1 -1
  287. package/dist/monitoring/trace-analyzer.js +19 -2
  288. package/dist/monitoring/trace-analyzer.js.map +1 -1
  289. package/dist/monitoring/traces.d.ts +21 -2
  290. package/dist/monitoring/traces.d.ts.map +1 -1
  291. package/dist/monitoring/traces.js +38 -29
  292. package/dist/monitoring/traces.js.map +1 -1
  293. package/dist/release/index.d.ts +3 -0
  294. package/dist/release/index.d.ts.map +1 -0
  295. package/dist/release/index.js +7 -0
  296. package/dist/release/index.js.map +1 -0
  297. package/dist/release/integrity.d.ts +65 -0
  298. package/dist/release/integrity.d.ts.map +1 -0
  299. package/dist/release/integrity.js +151 -0
  300. package/dist/release/integrity.js.map +1 -0
  301. package/dist/sdd/index-generator.js +10 -11
  302. package/dist/sdd/index-generator.js.map +1 -1
  303. package/dist/test-setup/project-fixture.d.ts +48 -0
  304. package/dist/test-setup/project-fixture.d.ts.map +1 -0
  305. package/dist/test-setup/project-fixture.js +106 -0
  306. package/dist/test-setup/project-fixture.js.map +1 -0
  307. package/dist/types/constraint.d.ts +0 -18
  308. package/dist/types/constraint.d.ts.map +1 -1
  309. package/dist/types/constraint.js.map +1 -1
  310. package/dist/types/failure.d.ts +7 -0
  311. package/dist/types/failure.d.ts.map +1 -1
  312. package/dist/types/failure.js +8 -1
  313. package/dist/types/failure.js.map +1 -1
  314. package/dist/types/passes-gate.d.ts +10 -25
  315. package/dist/types/passes-gate.d.ts.map +1 -1
  316. package/dist/types/project-config.d.ts +1 -1
  317. package/dist/types/session.d.ts +6 -5
  318. package/dist/types/session.d.ts.map +1 -1
  319. package/dist/utils/exec.d.ts +10 -0
  320. package/dist/utils/exec.d.ts.map +1 -1
  321. package/dist/utils/exec.js +12 -0
  322. package/dist/utils/exec.js.map +1 -1
  323. package/dist/utils/file-walk.d.ts +9 -1
  324. package/dist/utils/file-walk.d.ts.map +1 -1
  325. package/dist/utils/file-walk.js +10 -1
  326. package/dist/utils/file-walk.js.map +1 -1
  327. package/dist/utils/frontmatter.d.ts +73 -0
  328. package/dist/utils/frontmatter.d.ts.map +1 -0
  329. package/dist/utils/frontmatter.js +141 -0
  330. package/dist/utils/frontmatter.js.map +1 -0
  331. package/dist/utils/jsonl.d.ts +92 -0
  332. package/dist/utils/jsonl.d.ts.map +1 -0
  333. package/dist/utils/jsonl.js +166 -0
  334. package/dist/utils/jsonl.js.map +1 -0
  335. package/dist/utils/package-version.d.ts +16 -0
  336. package/dist/utils/package-version.d.ts.map +1 -0
  337. package/dist/utils/package-version.js +63 -0
  338. package/dist/utils/package-version.js.map +1 -0
  339. package/package.json +1 -1
  340. package/src/CONTEXT.md +7 -2
  341. package/src/__tests__/acceptance-gate.test.ts +3 -1
  342. package/src/__tests__/checker-extra.test.ts +7 -1218
  343. package/src/__tests__/context-files-resolution.test.ts +116 -0
  344. package/src/__tests__/effective-constraints.test.ts +10 -13
  345. package/src/__tests__/exec.test.ts +35 -1
  346. package/src/__tests__/failure-recorder.test.ts +9 -0
  347. package/src/__tests__/layering.test.ts +152 -0
  348. package/src/__tests__/passes-gate-extra.test.ts +0 -145
  349. package/src/__tests__/passes-gate.test.ts +142 -106
  350. package/src/__tests__/public-exports.test.ts +3 -0
  351. package/src/__tests__/skip-semantics.test.ts +5 -9
  352. package/src/cli/__tests__/command-contract.test.ts +170 -0
  353. package/src/cli/command-contract.ts +108 -0
  354. package/src/cli/commands/CONTEXT.md +22 -7
  355. package/src/cli/commands/__tests__/acceptance.test.ts +40 -33
  356. package/src/cli/commands/__tests__/analyze-sessions.test.ts +35 -29
  357. package/src/cli/commands/__tests__/bin-exit-mapping.test.ts +101 -0
  358. package/src/cli/commands/__tests__/check-drift.test.ts +27 -34
  359. package/src/cli/commands/__tests__/check-skip-output.test.ts +21 -24
  360. package/src/cli/commands/__tests__/check.test.ts +378 -382
  361. package/src/cli/commands/__tests__/command.test.ts +85 -70
  362. package/src/cli/commands/__tests__/constraints-report.test.ts +100 -71
  363. package/src/cli/commands/__tests__/constraints-retire.test.ts +152 -95
  364. package/src/cli/commands/__tests__/contract.test.ts +27 -34
  365. package/src/cli/commands/__tests__/failure.test.ts +31 -34
  366. package/src/cli/commands/__tests__/init-injection.test.ts +58 -28
  367. package/src/cli/commands/__tests__/init.test.ts +77 -48
  368. package/src/cli/commands/__tests__/knowledge-flywheel-consistency.test.ts +108 -0
  369. package/src/cli/commands/__tests__/knowledge.test.ts +96 -38
  370. package/src/cli/commands/__tests__/passes-gate.test.ts +43 -45
  371. package/src/cli/commands/__tests__/performance.test.ts +22 -23
  372. package/src/cli/commands/__tests__/posteval-plan.test.ts +39 -38
  373. package/src/cli/commands/__tests__/project-path-anchoring.test.ts +157 -0
  374. package/src/cli/commands/__tests__/project-path-convention.test.ts +169 -0
  375. package/src/cli/commands/__tests__/registry.test.ts +69 -35
  376. package/src/cli/commands/__tests__/release.test.ts +224 -74
  377. package/src/cli/commands/__tests__/report-extra.test.ts +16 -16
  378. package/src/cli/commands/__tests__/report.test.ts +25 -25
  379. package/src/cli/commands/__tests__/review.test.ts +33 -31
  380. package/src/cli/commands/__tests__/security.test.ts +23 -27
  381. package/src/cli/commands/__tests__/spec-baseline-check.test.ts +20 -20
  382. package/src/cli/commands/__tests__/spec.test.ts +41 -29
  383. package/src/cli/commands/__tests__/status-extra.test.ts +18 -18
  384. package/src/cli/commands/__tests__/status-skipped-lines.test.ts +72 -0
  385. package/src/cli/commands/__tests__/status.test.ts +34 -34
  386. package/src/cli/commands/__tests__/sync-docs-agents.test.ts +108 -86
  387. package/src/cli/commands/__tests__/sync-docs.test.ts +72 -74
  388. package/src/cli/commands/__tests__/update-user-model.test.ts +62 -33
  389. package/src/cli/commands/__tests__/validate.test.ts +27 -29
  390. package/src/cli/commands/acceptance.ts +35 -24
  391. package/src/cli/commands/analyze-sessions.ts +25 -24
  392. package/src/cli/commands/check.ts +88 -65
  393. package/src/cli/commands/command.ts +30 -17
  394. package/src/cli/commands/constraints-report.ts +37 -34
  395. package/src/cli/commands/constraints-retire.ts +58 -55
  396. package/src/cli/commands/constraints.ts +10 -27
  397. package/src/cli/commands/contract.ts +51 -42
  398. package/src/cli/commands/definitions.ts +37 -223
  399. package/src/cli/commands/failure.ts +35 -27
  400. package/src/cli/commands/init.ts +166 -220
  401. package/src/cli/commands/knowledge.ts +250 -203
  402. package/src/cli/commands/passes-gate.ts +58 -68
  403. package/src/cli/commands/performance.ts +23 -18
  404. package/src/cli/commands/posteval-plan.ts +29 -15
  405. package/src/cli/commands/release.ts +75 -78
  406. package/src/cli/commands/report.ts +9 -5
  407. package/src/cli/commands/review.ts +39 -29
  408. package/src/cli/commands/sdd.ts +7 -5
  409. package/src/cli/commands/security.ts +35 -26
  410. package/src/cli/commands/spec-baseline-check.ts +16 -11
  411. package/src/cli/commands/spec.ts +66 -53
  412. package/src/cli/commands/status.ts +59 -53
  413. package/src/cli/commands/sync-docs/agents-syncer.ts +31 -15
  414. package/src/cli/commands/sync-docs/context-syncer.ts +3 -2
  415. package/src/cli/commands/sync-docs/index.ts +73 -100
  416. package/src/cli/commands/sync-docs/project-reader.ts +17 -18
  417. package/src/cli/commands/update-user-model.ts +33 -45
  418. package/src/cli/commands/validate.ts +31 -25
  419. package/src/cli/session-mining/__tests__/transcript.test.ts +118 -0
  420. package/src/cli/session-mining/transcript.ts +26 -8
  421. package/src/completion-checkers/CONTEXT.md +1 -1
  422. package/src/completion-checkers/__tests__/contract-presence.test.ts +1 -1
  423. package/src/completion-checkers/__tests__/phase-format.test.ts +1 -1
  424. package/src/completion-checkers/__tests__/tdd-chain.test.ts +2 -2
  425. package/src/completion-checkers/index.ts +3 -3
  426. package/src/completion-checkers/phase-format.ts +2 -2
  427. package/src/completion-checkers/tdd-chain.ts +2 -2
  428. package/src/completion-checkers/types.ts +5 -5
  429. package/src/context/session-manager.ts +19 -33
  430. package/src/core/CONTEXT.md +9 -6
  431. package/src/core/constraints/__tests__/capabilities-reconcile.test.ts +200 -0
  432. package/src/core/constraints/__tests__/capability-counts.test.ts +94 -0
  433. package/src/core/constraints/__tests__/git-evidence.test.ts +208 -0
  434. package/src/core/constraints/__tests__/injection-drift.test.ts +3 -10
  435. package/src/core/constraints/__tests__/injection-writer.test.ts +231 -0
  436. package/src/core/constraints/__tests__/trace-injection.test.ts +71 -0
  437. package/src/core/constraints/__tests__/usage-report.test.ts +112 -0
  438. package/src/core/constraints/agent-prompt-renderer.ts +2 -6
  439. package/src/core/constraints/capabilities-parser.ts +53 -35
  440. package/src/core/constraints/capabilities-reconcile.ts +166 -0
  441. package/src/core/constraints/checker.ts +75 -130
  442. package/src/core/constraints/checkers/__tests__/capability-sync.test.ts +214 -0
  443. package/src/core/constraints/checkers/__tests__/context-doc-sync.test.ts +77 -0
  444. package/src/core/constraints/checkers/__tests__/docs-freshness.test.ts +117 -0
  445. package/src/{__tests__ → core/constraints/checkers/__tests__}/governance-presence.test.ts +83 -9
  446. package/src/core/constraints/checkers/__tests__/iron-flags.test.ts +50 -0
  447. package/src/core/constraints/checkers/__tests__/no-bypass-checkpoint.test.ts +76 -0
  448. package/src/{__tests__ → core/constraints/checkers/__tests__}/no-hardcoded-credentials.test.ts +4 -3
  449. package/src/core/constraints/checkers/__tests__/no-test-simplification.test.ts +58 -0
  450. package/src/core/constraints/checkers/__tests__/three-state-consistency.test.ts +145 -0
  451. package/src/core/constraints/checkers/capability-sync.ts +29 -88
  452. package/src/core/constraints/checkers/context-doc-sync.ts +15 -25
  453. package/src/core/constraints/checkers/docs-freshness.ts +40 -69
  454. package/src/core/constraints/checkers/governance-presence.ts +7 -25
  455. package/src/core/constraints/checkers/no-test-simplification.ts +4 -3
  456. package/src/core/constraints/checkers/types.ts +2 -2
  457. package/src/core/constraints/context-builder.ts +39 -91
  458. package/src/core/constraints/doc-freshness/runner.ts +2 -1
  459. package/src/core/constraints/git-evidence.ts +120 -0
  460. package/src/core/constraints/injection-drift.ts +13 -60
  461. package/src/core/constraints/injection-writer.ts +212 -0
  462. package/src/core/constraints/usage-report.ts +36 -17
  463. package/src/core/index.ts +4 -2
  464. package/src/core/project-config-loader.ts +49 -9
  465. package/src/core/validators/__tests__/passes-gate.test.ts +2 -56
  466. package/src/core/validators/__tests__/test-output.test.ts +372 -0
  467. package/src/core/validators/passes-gate.ts +86 -248
  468. package/src/core/validators/test-output.ts +128 -0
  469. package/src/failure/__tests__/recorder.test.ts +168 -0
  470. package/src/failure/recorder.ts +13 -11
  471. package/src/gates/CONTEXT.md +6 -3
  472. package/src/gates/__tests__/acceptance-types-single-source.test.ts +68 -0
  473. package/src/gates/__tests__/acceptance.test.ts +4 -86
  474. package/src/gates/__tests__/effective-gates.test.ts +3 -8
  475. package/src/gates/__tests__/test-verdict-consistency.test.ts +140 -0
  476. package/src/gates/acceptance.ts +19 -84
  477. package/src/gates/checker-gate.ts +8 -7
  478. package/src/gates/command.ts +10 -16
  479. package/src/gates/contract.ts +22 -61
  480. package/src/gates/performance.ts +10 -22
  481. package/src/gates/review.ts +21 -41
  482. package/src/gates/security.ts +10 -22
  483. package/src/gates/types.ts +70 -5
  484. package/src/hooks/CONTEXT.md +1 -1
  485. package/src/hooks/bootstrap.ts +5 -2
  486. package/src/index.ts +11 -6
  487. package/src/knowledge/CONTEXT.md +8 -3
  488. package/src/knowledge/__tests__/audit-labels.test.ts +44 -0
  489. package/src/knowledge/__tests__/flywheel-metrics.test.ts +135 -0
  490. package/src/knowledge/__tests__/import.test.ts +44 -0
  491. package/src/knowledge/__tests__/index-generator.test.ts +55 -2
  492. package/src/knowledge/__tests__/ingest.test.ts +85 -0
  493. package/src/knowledge/__tests__/migration.test.ts +47 -0
  494. package/src/knowledge/__tests__/reference-tracker.test.ts +16 -0
  495. package/src/knowledge/__tests__/store.test.ts +194 -0
  496. package/src/knowledge/audit.ts +67 -71
  497. package/src/knowledge/flywheel-metrics.ts +71 -0
  498. package/src/knowledge/import.ts +4 -18
  499. package/src/knowledge/index-generator.ts +20 -15
  500. package/src/knowledge/ingest.ts +9 -4
  501. package/src/knowledge/migration.ts +11 -8
  502. package/src/knowledge/reference-tracker.ts +12 -8
  503. package/src/knowledge/store.ts +64 -11
  504. package/src/monitoring/CONTEXT.md +8 -3
  505. package/src/monitoring/__tests__/skipped-lines-report.test.ts +178 -0
  506. package/src/monitoring/__tests__/traces.test.ts +57 -0
  507. package/src/monitoring/context-tracker.ts +11 -23
  508. package/src/monitoring/index.ts +1 -1
  509. package/src/monitoring/trace-analyzer.ts +21 -2
  510. package/src/monitoring/traces.ts +39 -36
  511. package/src/release/CONTEXT.md +24 -0
  512. package/src/release/__tests__/barrel.test.ts +60 -0
  513. package/src/release/__tests__/integrity.test.ts +157 -0
  514. package/src/release/index.ts +2 -0
  515. package/src/release/integrity.ts +141 -0
  516. package/src/sdd/__tests__/index-generator.test.ts +71 -0
  517. package/src/sdd/index-generator.ts +9 -9
  518. package/src/test-setup/__tests__/project-fixture.test.ts +178 -0
  519. package/src/test-setup/project-fixture.ts +87 -0
  520. package/src/tools/CONTEXT.md +6 -0
  521. package/src/tools/__tests__/registry.test.ts +221 -0
  522. package/src/types/__tests__/types.test.ts +4 -5
  523. package/src/types/constraint.ts +0 -25
  524. package/src/types/failure.ts +8 -0
  525. package/src/types/passes-gate.ts +10 -30
  526. package/src/types/project-config.ts +1 -1
  527. package/src/types/session.ts +5 -5
  528. package/src/utils/__tests__/frontmatter.test.ts +206 -0
  529. package/src/utils/__tests__/jsonl-skip-disposition.test.ts +175 -0
  530. package/src/utils/__tests__/jsonl.test.ts +187 -0
  531. package/src/utils/__tests__/package-version.test.ts +97 -0
  532. package/src/utils/exec.ts +15 -0
  533. package/src/utils/file-walk.ts +11 -2
  534. package/src/utils/frontmatter.ts +121 -0
  535. package/src/utils/jsonl.ts +167 -0
  536. package/src/utils/package-version.ts +27 -0
  537. package/dist/cli/commands/doc-freshness-check.d.ts +0 -53
  538. package/dist/cli/commands/doc-freshness-check.d.ts.map +0 -1
  539. package/dist/cli/commands/doc-freshness-check.js +0 -352
  540. package/dist/cli/commands/doc-freshness-check.js.map +0 -1
  541. package/dist/types/index.d.ts +0 -14
  542. package/dist/types/index.d.ts.map +0 -1
  543. package/dist/types/index.js +0 -39
  544. package/dist/types/index.js.map +0 -1
  545. package/src/__tests__/long-running.test.ts +0 -17
  546. package/src/__tests__/passes-gate-extension.test.ts +0 -151
  547. package/src/cli/commands/__tests__/doc-freshness-check.test.ts +0 -168
  548. package/src/cli/commands/doc-freshness-check.ts +0 -386
  549. package/src/spec/CONTEXT.md +0 -11
  550. package/src/types/index.ts +0 -47
package/src/types/session.ts CHANGED
@@ -81,9 +81,10 @@ export interface TaskListJson {
81
81
  }
82
82
 
83
83
  /**
84
- * 动态任务定义
84
+ * 动态任务定义（模块内类型：包根同名导出是 types/passes-gate 版，此处仅
85
+ * TaskListJson/SessionInfo 结构引用；原 Extended* 别名导出已随 #85 删除）
85
86
  */
86
- export interface DynamicTask {
87
+ interface DynamicTask {
87
88
  id: string;
88
89
  name?: string;
89
90
  category?: string;
@@ -101,14 +102,13 @@ export interface DynamicTask {
101
102
  }
102
103
 
103
104
  /**
104
- * 测试结果
105
+ * 测试结果（模块内类型，理由同 DynamicTask）
105
106
  */
106
- export interface TaskTestResult {
107
+ interface TaskTestResult {
107
108
  passed: boolean;
108
109
  command: string;
109
110
  output?: string;
110
111
  failures?: string[];
111
- coverage?: number;
112
112
  timestamp: Date;
113
113
  evidence?: string;
114
114
  }
package/src/utils/__tests__/frontmatter.test.ts ADDED
@@ -0,0 +1,206 @@
1
+ /**
2
+ * markdown frontmatter 解析/序列化正本测试（harness#89，架构评审 2026-09-02 候选10）
3
+ *
4
+ * 三种畸形输入（缺 frontmatter / 未闭合 / 空 meta）与 YAML 非法的走法在本文件显式固定，
5
+ * 各消费方（store / migration / knowledge index / sdd index / ingest）只允许复用这套判定。
6
+ */
7
+
8
+ import { splitFrontmatter, joinFrontmatter } from '../frontmatter';
9
+
10
+ describe('splitFrontmatter — 合法 frontmatter 块', () => {
11
+ it('解析 meta + body：与 store/migration 既有写盘格式（---\\n<yaml>---\\n\\n<body>）互认', () => {
12
+ const raw = '---\nid: DEC-001\ntype: decision\n---\n\nBody line\n';
13
+ const result = splitFrontmatter(raw);
14
+ expect(result.state).toBe('ok');
15
+ if (result.state !== 'ok') return;
16
+ expect(result.meta).toEqual({ id: 'DEC-001', type: 'decision' });
17
+ expect(result.body).toBe('Body line\n');
18
+ });
19
+
20
+ it('闭合行之后无空行时正文原样保留', () => {
21
+ const result = splitFrontmatter('---\na: 1\n---\nBody\n');
22
+ expect(result.state).toBe('ok');
23
+ if (result.state !== 'ok') return;
24
+ expect(result.body).toBe('Body\n');
25
+ });
26
+
27
+ it('只吃闭合后的一个空行（与 join 的 `---\\n\\n` 包裹严格对称）', () => {
28
+ const result = splitFrontmatter('---\na: 1\n---\n\n\nBody\n');
29
+ expect(result.state).toBe('ok');
30
+ if (result.state !== 'ok') return;
31
+ expect(result.body).toBe('\nBody\n');
32
+ });
33
+
34
+ it('闭合行即文件末尾（无尾随换行）→ body 为空串，仍是合法块', () => {
35
+ const result = splitFrontmatter('---\na: 1\n---');
36
+ expect(result.state).toBe('ok');
37
+ if (result.state !== 'ok') return;
38
+ expect(result.meta).toEqual({ a: 1 });
39
+ expect(result.body).toBe('');
40
+ });
41
+
42
+ it('正文中的 --- 分隔线不被误吞：闭合取第一个独立 --- 行', () => {
43
+ const result = splitFrontmatter('---\na: 1\n---\n\nx\n\n---\n\ny\n');
44
+ expect(result.state).toBe('ok');
45
+ if (result.state !== 'ok') return;
46
+ expect(result.meta).toEqual({ a: 1 });
47
+ expect(result.body).toBe('x\n\n---\n\ny\n');
48
+ });
49
+
50
+ it('meta 内缩进的 --- 是块标量内容，不算闭合行', () => {
51
+ const result = splitFrontmatter('---\nnote: |\n ---\nb: 2\n---\nBody\n');
52
+ expect(result.state).toBe('ok');
53
+ if (result.state !== 'ok') return;
54
+ expect(result.meta).toEqual({ note: '---\n', b: 2 });
55
+ expect(result.body).toBe('Body\n');
56
+ });
57
+
58
+ it('闭合必须是整行：--- 后带内容的行（含 ---- 长分隔线）不作闭合', () => {
59
+ const result = splitFrontmatter('---\na: 1\n---broken\n----\nBody\n');
60
+ expect(result.state).toBe('malformed');
61
+ if (result.state !== 'malformed') return;
62
+ expect(result.reason).toBe('unterminated');
63
+ });
64
+ });
65
+
66
+ describe('splitFrontmatter — 三种畸形输入 + YAML 非法（一处定义）', () => {
67
+ it('缺 frontmatter：首行不是 --- → absent', () => {
68
+ expect(splitFrontmatter('# Title\n\nBody\n')).toEqual({ state: 'absent' });
69
+ });
70
+
71
+ it('缺 frontmatter：首行 --- 之前还有空白 → absent（起点必须在偏移 0）', () => {
72
+ expect(splitFrontmatter('\n---\na: 1\n---\nBody\n')).toEqual({ state: 'absent' });
73
+ });
74
+
75
+ it('空 meta：零宽元数据块 → absent（不承载信息，与收口前 store 丢条目的走法一致）', () => {
76
+ expect(splitFrontmatter('---\n---\n\nBody\n')).toEqual({ state: 'absent' });
77
+ });
78
+
79
+ it('空 meta：仅空白行 → absent', () => {
80
+ expect(splitFrontmatter('---\n\n \n---\nBody\n')).toEqual({ state: 'absent' });
81
+ });
82
+
83
+ it('未闭合：有开无闭 → malformed/unterminated', () => {
84
+ const result = splitFrontmatter('---\nid: X\ntitle: Y\n');
85
+ expect(result.state).toBe('malformed');
86
+ if (result.state !== 'malformed') return;
87
+ expect(result.reason).toBe('unterminated');
88
+ expect(result.detail).toContain('---');
89
+ });
90
+
91
+ it('YAML 语法错误 → malformed/invalid-yaml，detail 可定位', () => {
92
+ const result = splitFrontmatter('---\na: [1,\n---\nBody\n');
93
+ expect(result.state).toBe('malformed');
94
+ if (result.state !== 'malformed') return;
95
+ expect(result.reason).toBe('invalid-yaml');
96
+ expect(result.detail.length).toBeGreaterThan(0);
97
+ expect(result.detail).not.toContain('\n');
98
+ });
99
+
100
+ it('meta 是标量而非 mapping → malformed/invalid-yaml（消费方禁止再写 meta.id 式钻取）', () => {
101
+ const result = splitFrontmatter('---\njust a string\n---\nBody\n');
102
+ expect(result.state).toBe('malformed');
103
+ if (result.state !== 'malformed') return;
104
+ expect(result.reason).toBe('invalid-yaml');
105
+ });
106
+
107
+ it('meta 是数组 → malformed/invalid-yaml', () => {
108
+ const result = splitFrontmatter('---\n- a\n- b\n---\nBody\n');
109
+ expect(result.state).toBe('malformed');
110
+ if (result.state !== 'malformed') return;
111
+ expect(result.reason).toBe('invalid-yaml');
112
+ });
113
+
114
+ it('meta 是显式 null（`~`）→ malformed/invalid-yaml（与空白 meta 的 absent 区分）', () => {
115
+ const result = splitFrontmatter('---\n~\n---\nBody\n');
116
+ expect(result.state).toBe('malformed');
117
+ if (result.state !== 'malformed') return;
118
+ expect(result.reason).toBe('invalid-yaml');
119
+ });
120
+
121
+ it('CRLF 文件不按 frontmatter 处理 → absent（与收口前各消费方一致，不新增解释）', () => {
122
+ expect(splitFrontmatter('---\r\na: 1\r\n---\r\nBody\r\n')).toEqual({ state: 'absent' });
123
+ });
124
+ });
125
+
126
+ describe('joinFrontmatter', () => {
127
+ it('包裹格式与收口前逐字一致：`---\\n` + yaml.dump + `---\\n\\n` + body', () => {
128
+ expect(joinFrontmatter({ id: 'X' }, 'Body\n')).toBe('---\nid: X\n---\n\nBody\n');
129
+ });
130
+
131
+ it('空 body 也保留闭合后的空行分隔', () => {
132
+ expect(joinFrontmatter({ a: 1 }, '')).toBe('---\na: 1\n---\n\n');
133
+ });
134
+
135
+ it('按传入对象的键序落盘：排序策略留在消费方（裁决：收格式不收字段排序）', () => {
136
+ expect(joinFrontmatter({ b: 1, a: 2 }, '')).toBe('---\nb: 1\na: 2\n---\n\n');
137
+ });
138
+
139
+ it('dump 用 lineWidth 120：100 字符标量不折行（非 js-yaml 缺省 80）', () => {
140
+ const joined = joinFrontmatter({ title: 'a'.repeat(100) }, '');
141
+ expect(joined.split('\n')[1]).toBe(`title: ${'a'.repeat(100)}`);
142
+ });
143
+
144
+ it('dump 用 lineWidth 120：200 字符标量按 120 折行（非不折行）', () => {
145
+ const joined = joinFrontmatter({ title: 'a'.repeat(200) }, '');
146
+ expect(joined).toContain('title: >-\n');
147
+ });
148
+ });
149
+
150
+ describe('join ↔ split 往返闭环（已落盘条目不产生 diff 噪声）', () => {
151
+ const realisticMeta = {
152
+ id: 'PIT-001',
153
+ type: 'pitfall',
154
+ title: '端口不匹配: 3001 -> "API" 的三种走法',
155
+ maturity: 'verified',
156
+ layer: 'system',
157
+ created: '2026-05-28T00:00:00.000Z',
158
+ lastReferenced: '',
159
+ contributors: ['agent'],
160
+ projects: [],
161
+ tags: ['port', 'events'],
162
+ applicablePhases: ['IMPLEMENT'],
163
+ sourceReferences: [{ workflow: 'wf', timestamp: '2026-05-28T00:00:00.000Z' }],
164
+ referencedBy: [],
165
+ executionResults: [],
166
+ consumptionMode: 'reference',
167
+ origin: 'agent',
168
+ };
169
+
170
+ function roundTripIsStable(body: string): void {
171
+ const first = joinFrontmatter(realisticMeta, body);
172
+ const parsed = splitFrontmatter(first);
173
+ expect(parsed.state).toBe('ok');
174
+ if (parsed.state !== 'ok') return;
175
+ expect(parsed.meta).toEqual(realisticMeta);
176
+ expect(parsed.body).toBe(body);
177
+ expect(joinFrontmatter(parsed.meta, parsed.body)).toBe(first);
178
+ }
179
+
180
+ it('真实条目 meta + 正文：join → split → join 字节稳定', () => {
181
+ roundTripIsStable('根因：端口不一致。\n\n## 处置\n显式指定 API_PORT\n');
182
+ });
183
+
184
+ it('空正文稳定', () => {
185
+ roundTripIsStable('');
186
+ });
187
+
188
+ it('正文首行即 --- 分隔线时稳定（不误吞、不重复包裹）', () => {
189
+ roundTripIsStable('---\n\n附录\n');
190
+ });
191
+
192
+ it('正文含超长行时稳定', () => {
193
+ roundTripIsStable(`${'x'.repeat(300)}\n`);
194
+ });
195
+
196
+ it('meta 含被 120 折行的长标量时往返仍字节稳定（load→save 无 diff 噪声）', () => {
197
+ const meta = { ...realisticMeta, title: Array.from({ length: 40 }, (_, i) => `word${i}`).join(' ') };
198
+ const first = joinFrontmatter(meta, 'Body\n');
199
+ expect(first).toContain('title: >-\n');
200
+ const parsed = splitFrontmatter(first);
201
+ expect(parsed.state).toBe('ok');
202
+ if (parsed.state !== 'ok') return;
203
+ expect(parsed.meta).toEqual(meta);
204
+ expect(joinFrontmatter(parsed.meta, parsed.body)).toBe(first);
205
+ });
206
+ });
package/src/utils/__tests__/jsonl-skip-disposition.test.ts ADDED
@@ -0,0 +1,175 @@
1
+ /**
2
+ * skip 读点的「计数去向」守护（harness#100）
3
+ *
4
+ * 契约原则（正本见 `src/monitoring/CONTEXT.md` 与 `src/cli/commands/CONTEXT.md`「约定」段）：
5
+ * **凡以 `skip` 策略读 JSONL，坏行计数必须到达该消费面的用户可见输出，或在该调用点
6
+ * 显式记名豁免并写明理由。** 静默吞掉「数据不全」不是一种可选项。
7
+ *
8
+ * 本文件把这句原则变成机器可检面，三道闸：
9
+ * 1. 每个 `readJsonl` 调用点都判得出坏行策略——判不出（策略走变量、参数形状超出识别窗口）
10
+ * 即形状逃逸，失败并交人裁决，不给静默漏判留口子
11
+ * 2. skip 读点集合冻结（`EXPECTED_SKIP_READ_SITES`）：新增读点即失败；
12
+ * 读点消失却不删条目也失败（豁免不烂成化石，与 #95 同一手法）
13
+ * 3. 每个读点上方 6 行内必须有 `计数去向：` 声明（透传到哪儿 / 为何豁免），且声明与本读点
14
+ * 之间不得夹着另一个读点——邻居的声明不顶替，缺失即失败
15
+ *
16
+ * `throw` 策略不产计数，故不要求去向声明；但新增 throw 调用点必须在下文那条断言里逐个点名
17
+ * 裁决——否则「改成 throw 就免掉告知」成了原则的绕行通道。`src/utils/jsonl.ts` 本身是策略
18
+ * 定义处，排除。
19
+ * `readJsonlEnds`（首尾读取）同样是 skip 读点，纳入同一识别正则——否则它成为本契约的
20
+ * 绕行通道（harness#114）。
21
+ * `countJsonlLines` 的纯行数站点（如 `check` 的提示计数）不 parse、不产坏行计数，也不在本表内
22
+ * ——它把损坏行算进条数的问题属口径变更，#100 明确不做。
23
+ */
24
+
25
+ import * as fs from 'fs';
26
+ import * as path from 'path';
27
+
28
+ const SRC_ROOT = path.join(__dirname, '..', '..');
29
+
30
+ /** 读点上方声明计数去向的标记（写在坏行策略注释里，与调用点同一处） */
31
+ const DISPOSITION_MARKER = /计数去向[:：]/;
32
+
33
+ /** 声明与读点的最大距离（行数）：只认紧贴读点的那段注释 */
34
+ const DECLARATION_LOOKBACK_LINES = 6;
35
+
36
+ /** 判定策略时从读点行向下拼几行（覆盖参数换行的调用形状） */
37
+ const POLICY_WINDOW_LINES = 6;
38
+
39
+ /**
40
+ * 冻结的 skip 读点集合：文件（仓库相对路径）→ 读点数。
41
+ * 每个读点的去向理由在调用点注释里，此表只钉「有哪些点、各几处」。
42
+ */
43
+ const EXPECTED_SKIP_READ_SITES: Record<string, number> = {
44
+ 'src/cli/commands/status.ts': 1,
45
+ 'src/cli/session-mining/transcript.ts': 1,
46
+ 'src/context/session-manager.ts': 2,
47
+ 'src/core/constraints/context-builder.ts': 2,
48
+ 'src/core/constraints/usage-report.ts': 1,
49
+ 'src/failure/recorder.ts': 1,
50
+ 'src/knowledge/reference-tracker.ts': 1,
51
+ 'src/monitoring/context-tracker.ts': 1,
52
+ 'src/monitoring/traces.ts': 2,
53
+ };
54
+
55
+ function listTsFiles(dir: string): string[] {
56
+ const found: string[] = [];
57
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
58
+ const full = path.join(dir, entry.name);
59
+ if (entry.isDirectory()) {
60
+ if (entry.name === '__tests__') continue;
61
+ found.push(...listTsFiles(full));
62
+ } else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {
63
+ found.push(full);
64
+ }
65
+ }
66
+ return found.sort();
67
+ }
68
+
69
+ /** 仓库相对路径（跨机器稳定） */
70
+ function repoPath(abs: string): string {
71
+ return path.relative(path.join(SRC_ROOT, '..'), abs).split(path.sep).join('/');
72
+ }
73
+
74
+ interface CallSite {
75
+ /** 1-based 行号 */
76
+ line: number;
77
+ snippet: string;
78
+ /** 策略判不出 = unknown（形状超出本守卫的识别能力，必须由人裁决而非静默漏判） */
79
+ policy: 'skip' | 'throw' | 'unknown';
80
+ }
81
+
82
+ /**
83
+ * 找出一个文件里所有 readJsonl 调用点并判出坏行策略。
84
+ * 调用参数可能换行，故从 `readJsonl` 起拼若干行再判：先遇到 `'skip'` 记 skip、
85
+ * 先遇到 `'throw'` 记 throw，两者都不出现记 unknown。
86
+ */
87
+ function callSites(file: string): CallSite[] {
88
+ const raw = fs.readFileSync(file, 'utf-8').split('\n');
89
+ const sites: CallSite[] = [];
90
+
91
+ for (let i = 0; i < raw.length; i++) {
92
+ const trimmed = raw[i].trim();
93
+ if (!/readJsonl(?:Ends)?\s*[<(]/.test(trimmed)) continue;
94
+ // 注释行里的示例不是站点（策略定义处 src/utils/jsonl.ts 已整体排除）
95
+ if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) continue;
96
+
97
+ const joined = raw.slice(i, i + POLICY_WINDOW_LINES).join(' ');
98
+ const skipIdx = joined.indexOf("'skip'");
99
+ const throwIdx = joined.indexOf("'throw'");
100
+ const policy: CallSite['policy'] =
101
+ skipIdx === -1 && throwIdx === -1
102
+ ? 'unknown'
103
+ : throwIdx !== -1 && (skipIdx === -1 || throwIdx < skipIdx)
104
+ ? 'throw'
105
+ : 'skip';
106
+
107
+ sites.push({ line: i + 1, snippet: trimmed, policy });
108
+ }
109
+ return sites;
110
+ }
111
+
112
+ describe('skip 读点的计数去向契约（harness#100）', () => {
113
+ const sourceFiles = listTsFiles(SRC_ROOT).filter(
114
+ f => repoPath(f) !== 'src/utils/jsonl.ts'
115
+ );
116
+ const sitesByFile = new Map<string, CallSite[]>();
117
+ for (const file of sourceFiles) {
118
+ const sites = callSites(file);
119
+ if (sites.length > 0) sitesByFile.set(repoPath(file), sites);
120
+ }
121
+
122
+ it('每个 readJsonl 调用点都判得出策略（判不出即形状逃逸，需人来补识别规则）', () => {
123
+ const unknown = [...sitesByFile.entries()].flatMap(([rel, sites]) =>
124
+ sites.filter(s => s.policy === 'unknown').map(s => `${rel}:${s.line} ${s.snippet}`)
125
+ );
126
+
127
+ expect(unknown).toEqual([]);
128
+ });
129
+
130
+ it('skip 读点集合 = 冻结表（新增即失败；站点消失却不删条目也失败）', () => {
131
+ const expected = Object.entries(EXPECTED_SKIP_READ_SITES)
132
+ .filter(([, count]) => count > 0)
133
+ .sort(([a], [b]) => a.localeCompare(b));
134
+ const observed = [...sitesByFile.entries()]
135
+ .map(([rel, sites]) => [rel, sites.filter(s => s.policy === 'skip').length] as [string, number])
136
+ .filter(([, count]) => count > 0)
137
+ .sort(([a], [b]) => a.localeCompare(b));
138
+
139
+ expect(observed).toEqual(expected);
140
+ });
141
+
142
+ it('每个 skip 读点都记名声明计数去向（透传目标或豁免理由）', () => {
143
+ const undeclared: string[] = [];
144
+
145
+ for (const [rel, sites] of sitesByFile) {
146
+ const raw = fs.readFileSync(path.join(SRC_ROOT, '..', rel), 'utf-8').split('\n');
147
+ for (const site of sites.filter(s => s.policy === 'skip')) {
148
+ const windowStart = Math.max(0, site.line - 1 - DECLARATION_LOOKBACK_LINES);
149
+ // 邻居读点的声明不得顶替：声明之后到本读点之间不能再有其它 readJsonl 调用点
150
+ const prevSiteLine = sites
151
+ .filter(s => s.line < site.line)
152
+ .map(s => s.line)
153
+ .reduce((max, line) => Math.max(max, line), 0);
154
+ const searchFrom = Math.max(windowStart, prevSiteLine);
155
+ const above = raw.slice(searchFrom, site.line - 1).join('\n');
156
+
157
+ if (!DISPOSITION_MARKER.test(above)) {
158
+ undeclared.push(`${rel}:${site.line} ${site.snippet}`);
159
+ }
160
+ }
161
+ }
162
+
163
+ expect(undeclared).toEqual([]);
164
+ });
165
+
166
+ it('策略为 throw 的调用点不产计数，目前为零（出现即需逐个裁决）', () => {
167
+ const throwSites = [...sitesByFile.entries()].flatMap(([rel, sites]) =>
168
+ sites.filter(s => s.policy === 'throw').map(s => `${rel}:${s.line}`)
169
+ );
170
+
171
+ // 'throw' 是 #82 裁决 1 保留的显式选项，但全仓当前无调用点；
172
+ // 新增时必须在此逐个点名裁决，不允许悄悄多出一条「不需要告知」的策略
173
+ expect(throwSites).toEqual([]);
174
+ });
175
+ });
package/src/utils/__tests__/jsonl.test.ts ADDED
@@ -0,0 +1,187 @@
1
+ /**
2
+ * JSONL 读写正本测试（harness#82）
3
+ */
4
+
5
+ import * as fs from 'fs';
6
+ import * as os from 'os';
7
+ import * as path from 'path';
8
+ import { readJsonl, countJsonlLines, readJsonlEnds, appendJsonl } from '../jsonl';
9
+
10
+ interface Row {
11
+ n: number;
12
+ }
13
+
14
+ const CORRUPT = '{"n":2,"broken';
15
+
16
+ describe('readJsonl', () => {
17
+ let dir: string;
18
+
19
+ beforeEach(() => {
20
+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-jsonl-'));
21
+ });
22
+
23
+ afterEach(() => {
24
+ fs.rmSync(dir, { recursive: true, force: true });
25
+ });
26
+
27
+ function write(name: string, lines: string[]): string {
28
+ const filePath = path.join(dir, name);
29
+ fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf-8');
30
+ return filePath;
31
+ }
32
+
33
+ it('按文件顺序解析全部合法行', () => {
34
+ const filePath = write('ok.jsonl', ['{"n":1}', '{"n":2}', '{"n":3}']);
35
+ const { records, skippedLines } = readJsonl<Row>(filePath, 'skip');
36
+ expect(records.map(r => r.n)).toEqual([1, 2, 3]);
37
+ expect(skippedLines).toBe(0);
38
+ });
39
+
40
+ it('缺文件返回空结果，不抛', () => {
41
+ expect(readJsonl<Row>(path.join(dir, 'missing.jsonl'), 'skip')).toEqual({
42
+ records: [],
43
+ skippedLines: 0,
44
+ });
45
+ });
46
+
47
+ it('空文件与纯空白行返回空结果', () => {
48
+ const empty = write('empty.jsonl', []);
49
+ const blank = write('blank.jsonl', ['', ' ', '\t']);
50
+ expect(readJsonl<Row>(empty, 'skip').records).toEqual([]);
51
+ expect(readJsonl<Row>(blank, 'skip').records).toEqual([]);
52
+ });
53
+
54
+ it("policy 'skip'：坏行计数、合法行照常返回", () => {
55
+ const filePath = write('dirty.jsonl', ['{"n":1}', CORRUPT, '', '{"n":3}']);
56
+ const { records, skippedLines } = readJsonl<Row>(filePath, 'skip');
57
+ expect(records.map(r => r.n)).toEqual([1, 3]);
58
+ expect(skippedLines).toBe(1);
59
+ });
60
+
61
+ it("policy 'throw'：坏行上抛", () => {
62
+ const filePath = write('dirty.jsonl', ['{"n":1}', CORRUPT]);
63
+ expect(() => readJsonl<Row>(filePath, 'throw')).toThrow(SyntaxError);
64
+ });
65
+
66
+ it('读入口无策略缺省值：不传 policy 编译期即失败（裁决 1，@ts-expect-error 固定）', () => {
67
+ // @ts-expect-error policy 为显式必填参数，缺省必须在编译期失败
68
+ const result = readJsonl<Row>(path.join(dir, 'unused.jsonl'));
69
+ expect(result.records).toEqual([]);
70
+ });
71
+
72
+ it('tail：只解析最后 N 个非空行', () => {
73
+ const filePath = write('tail.jsonl', ['{"n":1}', '{"n":2}', CORRUPT, '{"n":4}']);
74
+ const { records, skippedLines } = readJsonl<Row>(filePath, 'skip', { tail: 2 });
75
+ expect(records.map(r => r.n)).toEqual([4]);
76
+ expect(skippedLines).toBe(1);
77
+ });
78
+
79
+ it('head：只解析前 N 个非空行', () => {
80
+ const filePath = write('head.jsonl', ['{"n":1}', CORRUPT, '{"n":3}', '{"n":4}']);
81
+ const { records, skippedLines } = readJsonl<Row>(filePath, 'skip', { head: 2 });
82
+ expect(records.map(r => r.n)).toEqual([1]);
83
+ expect(skippedLines).toBe(1);
84
+ });
85
+
86
+ it('tail/head 超过总行数时取全部', () => {
87
+ const filePath = write('small.jsonl', ['{"n":1}']);
88
+ expect(readJsonl<Row>(filePath, 'skip', { tail: 10 }).records).toHaveLength(1);
89
+ expect(readJsonl<Row>(filePath, 'skip', { head: 10 }).records).toHaveLength(1);
90
+ });
91
+ });
92
+
93
+ describe('countJsonlLines', () => {
94
+ let dir: string;
95
+
96
+ beforeEach(() => {
97
+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-jsonl-'));
98
+ });
99
+
100
+ afterEach(() => {
101
+ fs.rmSync(dir, { recursive: true, force: true });
102
+ });
103
+
104
+ it('计非空行数（含坏行），缺文件为 0', () => {
105
+ const filePath = path.join(dir, 'c.jsonl');
106
+ fs.writeFileSync(filePath, ['{"n":1}', CORRUPT, '', ' '].join('\n') + '\n', 'utf-8');
107
+ expect(countJsonlLines(filePath)).toBe(2);
108
+ expect(countJsonlLines(path.join(dir, 'missing.jsonl'))).toBe(0);
109
+ });
110
+ });
111
+
112
+ describe('readJsonlEnds', () => {
113
+ let dir: string;
114
+
115
+ beforeEach(() => {
116
+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-jsonl-'));
117
+ });
118
+
119
+ afterEach(() => {
120
+ fs.rmSync(dir, { recursive: true, force: true });
121
+ });
122
+
123
+ function write(name: string, lines: string[]): string {
124
+ const filePath = path.join(dir, name);
125
+ fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf-8');
126
+ return filePath;
127
+ }
128
+
129
+ it('取首/末条合法记录 + 原始行数（含坏行）', () => {
130
+ const filePath = write('ends.jsonl', ['{"n":1}', CORRUPT, '{"n":3}']);
131
+ expect(readJsonlEnds<Row>(filePath, 'skip')).toEqual({
132
+ totalLines: 3,
133
+ first: { n: 1 },
134
+ last: { n: 3 },
135
+ });
136
+ });
137
+
138
+ it('首/末行坏时跳过坏行取最近的合法记录', () => {
139
+ const filePath = write('dirty-ends.jsonl', [CORRUPT, '{"n":2}', '{"n":3}', CORRUPT]);
140
+ const result = readJsonlEnds<Row>(filePath, 'skip');
141
+ expect(result.first).toEqual({ n: 2 });
142
+ expect(result.last).toEqual({ n: 3 });
143
+ expect(result.totalLines).toBe(4);
144
+ });
145
+
146
+ it("policy 'throw'：首端遇坏行上抛", () => {
147
+ const filePath = write('throw.jsonl', [CORRUPT, '{"n":2}']);
148
+ expect(() => readJsonlEnds<Row>(filePath, 'throw')).toThrow();
149
+ });
150
+
151
+ it('缺文件 / 全坏行返回无首末记录', () => {
152
+ expect(readJsonlEnds<Row>(path.join(dir, 'missing.jsonl'), 'skip')).toEqual({ totalLines: 0 });
153
+
154
+ const filePath = write('all-bad.jsonl', [CORRUPT, CORRUPT]);
155
+ expect(readJsonlEnds<Row>(filePath, 'skip')).toEqual({ totalLines: 2 });
156
+ });
157
+ });
158
+
159
+ describe('appendJsonl', () => {
160
+ let dir: string;
161
+
162
+ beforeEach(() => {
163
+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-jsonl-'));
164
+ });
165
+
166
+ afterEach(() => {
167
+ fs.rmSync(dir, { recursive: true, force: true });
168
+ });
169
+
170
+ it('目录不存在时递归创建并追加单行 JSON', () => {
171
+ const filePath = path.join(dir, 'a', 'b', 'log.jsonl');
172
+ appendJsonl(filePath, { n: 1 });
173
+ appendJsonl(filePath, { n: 2 });
174
+
175
+ expect(countJsonlLines(filePath)).toBe(2);
176
+ const lines = fs.readFileSync(filePath, 'utf-8').split('\n');
177
+ expect(lines[0]).toBe('{"n":1}');
178
+ expect(lines[1]).toBe('{"n":2}');
179
+ expect(lines[2]).toBe('');
180
+ });
181
+
182
+ it('与 readJsonl 构成读写闭环', () => {
183
+ const filePath = path.join(dir, 'roundtrip.jsonl');
184
+ appendJsonl(filePath, { n: 7 });
185
+ expect(readJsonl<Row>(filePath, 'skip').records).toEqual([{ n: 7 }]);
186
+ });
187
+ });