@smartergpt/lexrunner 1.0.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 (1433) hide show
  1. package/.changes/ci-debug-added.txt +1 -0
  2. package/.changeset/tsconfig-solution-build.md +5 -0
  3. package/.editorconfig +9 -0
  4. package/.env.example +8 -0
  5. package/.github/COST_EFFICIENCY.md +60 -0
  6. package/.github/ISSUE_TEMPLATE/bug_report.md +28 -0
  7. package/.github/ISSUE_TEMPLATE/epic.yml +123 -0
  8. package/.github/ISSUE_TEMPLATE/feature_request.md +26 -0
  9. package/.github/ISSUE_TEMPLATE/issue-A1-gate-input-validation.md +380 -0
  10. package/.github/ISSUE_TEMPLATE/issue-B1-scope-validation.md +509 -0
  11. package/.github/ISSUE_TEMPLATE/issue-C1-command-whitelist.md +463 -0
  12. package/.github/ISSUE_TEMPLATE/subtask.yml +153 -0
  13. package/.github/PULL_REQUEST_TEMPLATE.md +9 -0
  14. package/.github/copilot-instructions-old.md +429 -0
  15. package/.github/copilot-instructions.md +33 -0
  16. package/.github/instructions/tests.instructions.md +10 -0
  17. package/.github/workflows/auto-delete-merged-branches.yml +103 -0
  18. package/.github/workflows/benchmarks.yml +72 -0
  19. package/.github/workflows/ci-debug.yml +33 -0
  20. package/.github/workflows/ci.yml +167 -0
  21. package/.github/workflows/cli-smoke-test.yml +345 -0
  22. package/.github/workflows/copilot-setup-steps.yml +20 -0
  23. package/.github/workflows/frame-emission-gate.yml +242 -0
  24. package/.github/workflows/project-auto.yml +24 -0
  25. package/.github/workflows/release.yml +260 -0
  26. package/.github/workflows/slow-cli-tests.yml +37 -0
  27. package/.github/workflows/tag-guard.yml +44 -0
  28. package/.husky/pre-commit +1 -0
  29. package/.nvmrc +2 -0
  30. package/.prettierignore +28 -0
  31. package/.prettierrc.json +10 -0
  32. package/.smartergpt/CONTROL_DECK_VISION.md +226 -0
  33. package/.smartergpt/allowed-commands.json +41 -0
  34. package/.smartergpt/allowed-commands.strict.json +56 -0
  35. package/.smartergpt/deliverables/.live.md +426 -0
  36. package/.smartergpt/deliverables/ISSUE_STATUS_2025-12-28.md +193 -0
  37. package/.smartergpt/deliverables/_research/snapshot-contract-feedback/ADR_DISCUSSION.md +379 -0
  38. package/.smartergpt/deliverables/_research/snapshot-contract-feedback/Answer_claude-haiku.md +109 -0
  39. package/.smartergpt/deliverables/_research/snapshot-contract-feedback/Answer_gemini-flash.md +42 -0
  40. package/.smartergpt/deliverables/_research/snapshot-contract-feedback/Answer_gpt-codex-mini.md +19 -0
  41. package/.smartergpt/deliverables/_research/snapshot-contract-feedback/Answer_raptor-mini.md +37 -0
  42. package/.smartergpt/deliverables/_research/snapshot-contract-feedback/Question.md +37 -0
  43. package/.smartergpt/deliverables/merge-weave-04469e41-24ba-4ed5-b0ff-13c7ea12858d.ndjson +2 -0
  44. package/.smartergpt/deps.yml +3 -0
  45. package/.smartergpt/docs/fanout-templates.md +213 -0
  46. package/.smartergpt/docs/merge-weave-interventions.md +261 -0
  47. package/.smartergpt/docs/test-fix-patterns.md +240 -0
  48. package/.smartergpt/fanout-templates.yml +263 -0
  49. package/.smartergpt/gates.yml +9 -0
  50. package/.smartergpt/intent.md +1 -0
  51. package/.smartergpt/issues/QOL-001-analysis-script-filtering.md +36 -0
  52. package/.smartergpt/issues/QOL-002-log-retention-policy.md +92 -0
  53. package/.smartergpt/issues/QOL-003-realtime-console-feedback.md +44 -0
  54. package/.smartergpt/issues/QOL-004-governance-report-cli.md +44 -0
  55. package/.smartergpt/issues/QOL-005-schema-versioning.md +46 -0
  56. package/.smartergpt/issues/QOL-006-debug-verbose-mode.md +45 -0
  57. package/.smartergpt/issues/QOL-COMPLETION-REPORT.md +359 -0
  58. package/.smartergpt/issues/QOL-REVIEW-SUMMARY.md +111 -0
  59. package/.smartergpt/issues/QOL-ROADMAP.md +71 -0
  60. package/.smartergpt/merge-policy.yml +41 -0
  61. package/.smartergpt/merge-weave-policy.yml +255 -0
  62. package/.smartergpt/o1.json +0 -0
  63. package/.smartergpt/o2.json +0 -0
  64. package/.smartergpt/personas/eager-pm.md +123 -0
  65. package/.smartergpt/personas/example.md +81 -0
  66. package/.smartergpt/personas/senior-dev.md +107 -0
  67. package/.smartergpt/profile.yml +2 -0
  68. package/.smartergpt/prompts/create-project.md +112 -0
  69. package/.smartergpt/prompts/idea.md +64 -0
  70. package/.smartergpt/pull-request-template.md +25 -0
  71. package/.smartergpt/schemas/behavior-rule.schema.d.ts +54 -0
  72. package/.smartergpt/schemas/behavior-rule.schema.js +56 -0
  73. package/.smartergpt/schemas/behavior-rule.schema.json +105 -0
  74. package/.smartergpt/schemas/behavior-rule.schema.ts +60 -0
  75. package/.smartergpt/schemas/execution-plan-v1.d.ts +47 -0
  76. package/.smartergpt/schemas/execution-plan-v1.js +22 -0
  77. package/.smartergpt/schemas/execution-plan-v1.json +113 -0
  78. package/.smartergpt/schemas/execution-plan-v1.ts +32 -0
  79. package/.smartergpt/schemas/execution-plan.schema.json +116 -0
  80. package/.smartergpt/schemas/feature-spec-v0.d.ts +13 -0
  81. package/.smartergpt/schemas/feature-spec-v0.js +12 -0
  82. package/.smartergpt/schemas/feature-spec-v0.json +58 -0
  83. package/.smartergpt/schemas/feature-spec-v0.ts +16 -0
  84. package/.smartergpt/schemas/feature-spec.schema.json +111 -0
  85. package/.smartergpt/schemas/gates.schema.d.ts +48 -0
  86. package/.smartergpt/schemas/gates.schema.js +20 -0
  87. package/.smartergpt/schemas/gates.schema.json +47 -0
  88. package/.smartergpt/schemas/gates.schema.ts +26 -0
  89. package/.smartergpt/schemas/idea.schema.json +81 -0
  90. package/.smartergpt/schemas/runner.scope.schema.d.ts +54 -0
  91. package/.smartergpt/schemas/runner.scope.schema.js +28 -0
  92. package/.smartergpt/schemas/runner.scope.schema.json +75 -0
  93. package/.smartergpt/schemas/runner.scope.schema.ts +36 -0
  94. package/.smartergpt/schemas/runner.stack.schema.d.ts +40 -0
  95. package/.smartergpt/schemas/runner.stack.schema.js +21 -0
  96. package/.smartergpt/schemas/runner.stack.schema.json +51 -0
  97. package/.smartergpt/schemas/runner.stack.schema.ts +27 -0
  98. package/.smartergpt/scope.yml +11 -0
  99. package/.smartergpt/stack.yml +16 -0
  100. package/.smartergpt/test-fix-patterns.yml +106 -0
  101. package/.tool-versions +13 -0
  102. package/AGENTS.md +402 -0
  103. package/CHANGELOG.md +256 -0
  104. package/CLAUDE.md +484 -0
  105. package/CONTRIBUTING.md +345 -0
  106. package/EAGER_PM_FANOUT_ANALYSIS.md +283 -0
  107. package/FAQ.md +292 -0
  108. package/FIXTURE_LIBRARY_SUMMARY.md +327 -0
  109. package/IMPLEMENTATION_SUMMARY.md +222 -0
  110. package/LICENSE +21 -0
  111. package/MANUAL_TEST_GUIDE.md +229 -0
  112. package/MCP-ALIGNMENT-SUMMARY.md +261 -0
  113. package/MCP-CONFIG.md +125 -0
  114. package/MERGE_WEAVE_QUICKSTART.md +450 -0
  115. package/MERGE_WEAVE_SUMMARY.md +259 -0
  116. package/MERGE_WEAVE_USAGE_GUIDE.md +368 -0
  117. package/NOTICE.md +43 -0
  118. package/README.mcp.md +770 -0
  119. package/README.md +1069 -0
  120. package/TEST_INFRASTRUCTURE_ASSESSMENT.md +225 -0
  121. package/bootstrap-lexrunner.sh +396 -0
  122. package/dist/api-7H7SJZIX.js +15 -0
  123. package/dist/api-U3X2WA6D.js +15 -0
  124. package/dist/audit-2TZ2LU72.js +60 -0
  125. package/dist/audit-5HH5BMKI.js +60 -0
  126. package/dist/audit-6K5K333I.js +60 -0
  127. package/dist/audit-DYQWS57J.js +60 -0
  128. package/dist/audit-JBWZ2GZ2.js +60 -0
  129. package/dist/audit-SJF3434D.js +60 -0
  130. package/dist/audit-TICGGVX5.js +60 -0
  131. package/dist/audit-YOBB27PY.js +60 -0
  132. package/dist/autopilot-3GAVXWWC.js +45 -0
  133. package/dist/autopilot-43NOYVQA.js +45 -0
  134. package/dist/autopilot-4UA3OWLU.js +45 -0
  135. package/dist/autopilot-54TK5CCG.js +45 -0
  136. package/dist/autopilot-5BHC2UQT.js +45 -0
  137. package/dist/autopilot-ABZUCVGY.js +45 -0
  138. package/dist/autopilot-ACJZP47Y.js +45 -0
  139. package/dist/autopilot-AL5F5AUS.js +46 -0
  140. package/dist/autopilot-BO67FWUC.js +45 -0
  141. package/dist/autopilot-BR6W4GEX.js +45 -0
  142. package/dist/autopilot-FOR2UKRY.js +45 -0
  143. package/dist/autopilot-GDTTXHEQ.js +45 -0
  144. package/dist/autopilot-GEAMFZBM.js +45 -0
  145. package/dist/autopilot-HDMBRZE6.js +45 -0
  146. package/dist/autopilot-IKI2Y6S4.js +44 -0
  147. package/dist/autopilot-ILTBWWOL.js +46 -0
  148. package/dist/autopilot-KI3MXIFI.js +44 -0
  149. package/dist/autopilot-LWNPZC3J.js +45 -0
  150. package/dist/autopilot-LXPJ4ZXF.js +45 -0
  151. package/dist/autopilot-MDIFIONK.js +46 -0
  152. package/dist/autopilot-NW3LDP6M.js +45 -0
  153. package/dist/autopilot-OKTSCG35.js +45 -0
  154. package/dist/autopilot-OR5PF5PD.js +45 -0
  155. package/dist/autopilot-PE65SBGN.js +45 -0
  156. package/dist/autopilot-PW7I4B6W.js +45 -0
  157. package/dist/autopilot-QMLBL5P6.js +45 -0
  158. package/dist/autopilot-QSN6ZU5O.js +45 -0
  159. package/dist/autopilot-R7EZJOGI.js +46 -0
  160. package/dist/autopilot-T544CPPD.js +44 -0
  161. package/dist/autopilot-TNQB6VGJ.js +44 -0
  162. package/dist/autopilot-UVIYCR6K.js +45 -0
  163. package/dist/autopilot-W3ZTTSH3.js +45 -0
  164. package/dist/autopilot-XPKWOFXO.js +44 -0
  165. package/dist/autopilot-XRX4QWRM.js +44 -0
  166. package/dist/autopilot-Y3BAGNI5.js +44 -0
  167. package/dist/autopilot-ZE64XW2K.js +44 -0
  168. package/dist/chunk-2ESYSVXG.js +48 -0
  169. package/dist/chunk-2VR554P7.js +668 -0
  170. package/dist/chunk-37DOWIVT.js +1084 -0
  171. package/dist/chunk-3DU2DWUP.js +400 -0
  172. package/dist/chunk-3DVXIZFM.js +11166 -0
  173. package/dist/chunk-3FABZF4V.js +811 -0
  174. package/dist/chunk-4FFGNTAV.js +515 -0
  175. package/dist/chunk-4GEC4HC3.js +11221 -0
  176. package/dist/chunk-4RVZNLD4.js +628 -0
  177. package/dist/chunk-55VWJYZY.js +39 -0
  178. package/dist/chunk-5CGWZH5X.js +340 -0
  179. package/dist/chunk-5QKWKK4M.js +11794 -0
  180. package/dist/chunk-5Z3XHND7.js +11755 -0
  181. package/dist/chunk-6A4IE3TI.js +302 -0
  182. package/dist/chunk-6KK5JFFE.js +106 -0
  183. package/dist/chunk-6YC2VSLE.js +11252 -0
  184. package/dist/chunk-7C4K2SHD.js +668 -0
  185. package/dist/chunk-ANXY4RGA.js +11091 -0
  186. package/dist/chunk-ASHKNUBR.js +11312 -0
  187. package/dist/chunk-B3OYDPOP.js +11793 -0
  188. package/dist/chunk-DBH7SQ2S.js +1084 -0
  189. package/dist/chunk-DEI7A5B4.js +11449 -0
  190. package/dist/chunk-DM4GHY3J.js +92 -0
  191. package/dist/chunk-EQKFCZLH.js +9823 -0
  192. package/dist/chunk-FAIJPBT5.js +40 -0
  193. package/dist/chunk-FDDKUDXR.js +11166 -0
  194. package/dist/chunk-FEAR6ETG.js +438 -0
  195. package/dist/chunk-FNBAHK5V.js +72 -0
  196. package/dist/chunk-FXL74C73.js +523 -0
  197. package/dist/chunk-GLJEDX4L.js +10247 -0
  198. package/dist/chunk-GTP4OHD7.js +1107 -0
  199. package/dist/chunk-HIHH7IVO.js +10557 -0
  200. package/dist/chunk-I3VXUVCB.js +10474 -0
  201. package/dist/chunk-I6BIFVWI.js +10519 -0
  202. package/dist/chunk-I72TRUTJ.js +1084 -0
  203. package/dist/chunk-J5B5KT2F.js +368 -0
  204. package/dist/chunk-JMTULZ66.js +11743 -0
  205. package/dist/chunk-JXIQ7HCK.js +11166 -0
  206. package/dist/chunk-K6HVPBDP.js +10692 -0
  207. package/dist/chunk-KBT5Y666.js +521 -0
  208. package/dist/chunk-LETPROKG.js +11092 -0
  209. package/dist/chunk-LLMY2BZF.js +1084 -0
  210. package/dist/chunk-NMNL4US2.js +1084 -0
  211. package/dist/chunk-O2XRP7JK.js +10247 -0
  212. package/dist/chunk-OGPWLFFO.js +11201 -0
  213. package/dist/chunk-OQJUWTZV.js +51 -0
  214. package/dist/chunk-PJRWPLQ6.js +669 -0
  215. package/dist/chunk-PYRVUCJR.js +370 -0
  216. package/dist/chunk-Q6Y524KH.js +669 -0
  217. package/dist/chunk-QF7DM5VW.js +106 -0
  218. package/dist/chunk-QGM4M3NI.js +37 -0
  219. package/dist/chunk-QIIELFTL.js +1107 -0
  220. package/dist/chunk-QUW6N7GR.js +10264 -0
  221. package/dist/chunk-QZASNLQX.js +11223 -0
  222. package/dist/chunk-RMN4IAWO.js +11808 -0
  223. package/dist/chunk-RN5NHU37.js +11465 -0
  224. package/dist/chunk-RNG3RILO.js +11755 -0
  225. package/dist/chunk-RSA6DEB4.js +9748 -0
  226. package/dist/chunk-RURYWSMX.js +10524 -0
  227. package/dist/chunk-SUEXK5U7.js +11201 -0
  228. package/dist/chunk-TVUF55OH.js +11807 -0
  229. package/dist/chunk-U5MMENCP.js +456 -0
  230. package/dist/chunk-U62I2R2D.js +434 -0
  231. package/dist/chunk-UHFMFO54.js +21 -0
  232. package/dist/chunk-UNZBDSEU.js +11166 -0
  233. package/dist/chunk-UOATTNQP.js +334 -0
  234. package/dist/chunk-UZFYNSMJ.js +334 -0
  235. package/dist/chunk-VP37GLU6.js +1084 -0
  236. package/dist/chunk-W6WDKBWO.js +11453 -0
  237. package/dist/chunk-XBKUFNVF.js +10745 -0
  238. package/dist/chunk-XOLVQTIE.js +670 -0
  239. package/dist/chunk-XVFTBVDS.js +257 -0
  240. package/dist/chunk-YABA7DB6.js +11091 -0
  241. package/dist/chunk-YWCJX5KL.js +10557 -0
  242. package/dist/chunk-Z5GP7FSR.js +309 -0
  243. package/dist/chunk-ZBT3DATZ.js +296 -0
  244. package/dist/chunk-ZDBAZXUQ.js +11201 -0
  245. package/dist/chunk-ZEMABYS4.js +92 -0
  246. package/dist/chunk-ZOA4HT7P.js +662 -0
  247. package/dist/cli.cjs +40431 -0
  248. package/dist/cli.d.cts +2709 -0
  249. package/dist/cli.d.ts +2709 -0
  250. package/dist/cli.js +21149 -0
  251. package/dist/commandValidator-42OUDFZ4.js +140 -0
  252. package/dist/commandValidator-7LQHTYL5.js +140 -0
  253. package/dist/commandValidator-AT5OYZFC.js +142 -0
  254. package/dist/commandValidator-DH3CX2OW.js +140 -0
  255. package/dist/commandValidator-GCQC7H4A.js +140 -0
  256. package/dist/commandValidator-K6VWB6O3.js +140 -0
  257. package/dist/commandValidator-L6WNDBYB.js +129 -0
  258. package/dist/commandValidator-O3KSNXD2.js +140 -0
  259. package/dist/commandValidator-ZHMUA5RQ.js +140 -0
  260. package/dist/constraints-M52FVL2X.js +11 -0
  261. package/dist/dist-CSOR2BL2.js +1144 -0
  262. package/dist/dist-PKOIS5NZ.js +1144 -0
  263. package/dist/fileAnalysis-3VMDDJ6I.js +9 -0
  264. package/dist/fileAnalysis-4QLHUT44.js +9 -0
  265. package/dist/fileAnalysis-H6M2Z7ZC.js +9 -0
  266. package/dist/fileAnalysis-HMI7IL6S.js +9 -0
  267. package/dist/fileAnalysis-JHABOPUQ.js +9 -0
  268. package/dist/gateMapping-E5MGNJH5.js +17 -0
  269. package/dist/jsonEnvelope-R4SWKX2N.js +62 -0
  270. package/dist/mergeTreeSimulator-ATOPJ3DU.js +11 -0
  271. package/dist/mergeTreeSimulator-AYUK4TZT.js +11 -0
  272. package/dist/mergeTreeSimulator-BBWJUQBK.js +11 -0
  273. package/dist/mergeTreeSimulator-DJJDRB5N.js +11 -0
  274. package/dist/mergeTreeSimulator-X4BA647P.js +11 -0
  275. package/dist/planDiff-37QHCPKO.js +109 -0
  276. package/dist/planDiff-BQHIUARB.js +109 -0
  277. package/dist/planDiff-QOK6KNB7.js +111 -0
  278. package/dist/planDiff-RXR4CWFS.js +109 -0
  279. package/dist/planDiff-W2BTH2MU.js +109 -0
  280. package/dist/planHistory-4J3Q6AJ3.js +126 -0
  281. package/dist/planHistory-DQRSB2Y7.js +118 -0
  282. package/dist/planHistory-GLCXP6AB.js +126 -0
  283. package/dist/planHistory-SMNRLEKG.js +126 -0
  284. package/dist/planHistory-UO4WZ6GO.js +126 -0
  285. package/dist/planReview-7BWVLABC.js +377 -0
  286. package/dist/planReview-7VB3OYKZ.js +385 -0
  287. package/dist/planReview-FAIBIAE6.js +377 -0
  288. package/dist/planReview-FXQBDNKJ.js +376 -0
  289. package/dist/planReview-HO4YYETA.js +377 -0
  290. package/dist/planReview-I26EKCUK.js +376 -0
  291. package/dist/planReview-JBOAJHSU.js +377 -0
  292. package/dist/planReview-SCNZWC6B.js +376 -0
  293. package/dist/planReview-TU7LMZIY.js +376 -0
  294. package/dist/planViewer-2YZCPVDM.js +155 -0
  295. package/dist/planViewer-72WZFUTU.js +154 -0
  296. package/dist/planViewer-G546TVHV.js +154 -0
  297. package/dist/planViewer-I7ZHNJQF.js +150 -0
  298. package/dist/planViewer-IRXHOY5U.js +155 -0
  299. package/dist/planViewer-IX2ICW45.js +154 -0
  300. package/dist/planViewer-PDWPUOP6.js +155 -0
  301. package/dist/planViewer-PEOADAGZ.js +155 -0
  302. package/dist/planViewer-PFYDEG6V.js +150 -0
  303. package/dist/planViewer-UIPOSRVW.js +151 -0
  304. package/dist/planViewer-V2JUKV7Q.js +154 -0
  305. package/dist/sarif-46TKOOJZ.js +9 -0
  306. package/dist/sarif-63JKTFFI.js +9 -0
  307. package/dist/sarif-CIYIWUNC.js +9 -0
  308. package/dist/sarif-OGAGDL6B.js +9 -0
  309. package/dist/sarif-XIREI5B5.js +9 -0
  310. package/dist/security-3V6FKJDA.js +423 -0
  311. package/dist/security-4JMEUM56.js +423 -0
  312. package/dist/security-QHPEWY5G.js +423 -0
  313. package/dist/security-V2LAL5TP.js +415 -0
  314. package/dist/security-WTASK6T6.js +423 -0
  315. package/dist/security-XE4GHVJD.js +423 -0
  316. package/dist/security-XLXM3UHT.js +423 -0
  317. package/dist/security-YDLHSMVY.js +441 -0
  318. package/dist/security-ZDAEZF7D.js +423 -0
  319. package/dist/signing-3EI734L4.js +14 -0
  320. package/dist/signing-5G7K6JXJ.js +14 -0
  321. package/dist/signing-7DK7SABM.js +14 -0
  322. package/dist/signing-JJJOUGCW.js +14 -0
  323. package/dist/signing-OAJ3MXGA.js +14 -0
  324. package/dist/verify-5F6PUXUQ.js +62 -0
  325. package/dist/verify-5ILURHV2.js +62 -0
  326. package/dist/verify-MRDZJUGO.js +62 -0
  327. package/dist/verify-SCUHB3SA.js +62 -0
  328. package/dist/verify-YZRHN2D3.js +62 -0
  329. package/docs/1.0.0-vertical-slice.md +214 -0
  330. package/docs/ADR-007-INTEGRATION-SUMMARY.md +232 -0
  331. package/docs/ALIASING_FOR_LEXRUNNER.md +709 -0
  332. package/docs/ALIASING_FOR_RUNNER.md +552 -0
  333. package/docs/AX.md +317 -0
  334. package/docs/CHECKPOINT_RESUME.md +208 -0
  335. package/docs/CLI_VERBS.md +219 -0
  336. package/docs/CONFLICT_DETECTION.md +198 -0
  337. package/docs/DISCIPLINED_FAILURE.md +224 -0
  338. package/docs/ENVIRONMENT_QUALITY.md +155 -0
  339. package/docs/ERROR_CODES.md +528 -0
  340. package/docs/EVENT_SCHEMA.md +659 -0
  341. package/docs/EXE-012-investigation-summary.md +300 -0
  342. package/docs/GATE_ATTESTATION_GUIDE.md +237 -0
  343. package/docs/JSON_OUTPUT_SCHEMAS.md +347 -0
  344. package/docs/LEXRUNNER_ALIASING.md +444 -0
  345. package/docs/LEX_INTEGRATION.md +83 -0
  346. package/docs/LEX_PUBLIC_API.md +306 -0
  347. package/docs/LICENSING.md +119 -0
  348. package/docs/MCP-CLI-PARITY.md +410 -0
  349. package/docs/MCP-MIGRATION.md +258 -0
  350. package/docs/MCP-PARITY.md +234 -0
  351. package/docs/MEMORY_TOOLS.md +278 -0
  352. package/docs/MERGE_WEAVE_SETUP.md +643 -0
  353. package/docs/MIGRATION_v0.1.md +760 -0
  354. package/docs/NAMING_CONVENTIONS.md +82 -0
  355. package/docs/PERSONA_FOUNDATION.md +124 -0
  356. package/docs/PHASE3_MEMORY_GUIDE.md +122 -0
  357. package/docs/PLAN_LOCK.md +114 -0
  358. package/docs/README.md +289 -0
  359. package/docs/RUNNER_LIFECYCLE.md +257 -0
  360. package/docs/SAFETY_MECHANISMS.md +325 -0
  361. package/docs/SECURITY_IMPLEMENTATION.md +535 -0
  362. package/docs/TERMS.md +34 -0
  363. package/docs/TOKEN_TRACKING.md +162 -0
  364. package/docs/WORKFLOW_GUIDANCE.md +277 -0
  365. package/docs/adr/ADR-000-product-naming-and-branding.md +115 -0
  366. package/docs/adr/ADR-001-plan-json-frozen-input.md +68 -0
  367. package/docs/adr/ADR-002-two-track-separation.md +84 -0
  368. package/docs/adr/ADR-003-gate-uniform-execution.md +69 -0
  369. package/docs/adr/ADR-004-runner-state-model.md +75 -0
  370. package/docs/adr/ADR-005-merge-pyramid-ordering.md +87 -0
  371. package/docs/adr/ADR-006-schema-versioning-semver.md +81 -0
  372. package/docs/adr/ADR-007-task-snapshot-contract.md +503 -0
  373. package/docs/adr/ADR-008-lex-packaging.md +243 -0
  374. package/docs/adr/ADR-009-ax-test-output-adapters.md +440 -0
  375. package/docs/adr/README.md +32 -0
  376. package/docs/advanced-cli.md +436 -0
  377. package/docs/agent-stall-detection.md +278 -0
  378. package/docs/architecture/executors.md +190 -0
  379. package/docs/architecture.md +316 -0
  380. package/docs/attestation/AX-SHARED-PLEDGE.md +83 -0
  381. package/docs/attestation/AX-SHARED-PLEDGE_v1.0.0.md +99 -0
  382. package/docs/attestation/AX-SHARED-PLEDGE_v1.0.0_VERIFICATION.md +115 -0
  383. package/docs/attestation/Lex_Guff_Version_Contract_Pact_v1.0.0.md +181 -0
  384. package/docs/attestation/README.md +87 -0
  385. package/docs/attestation/ax_pledge_2025-12-02.ots +0 -0
  386. package/docs/attestation/ax_pledge_timestamp_response.tsr +0 -0
  387. package/docs/attestation/copilot_summarization_2025-12-01.ots +0 -0
  388. package/docs/attestation/copilot_summarization_2025-12-01_VERIFICATION.md +100 -0
  389. package/docs/attestation/copilot_summarization_behavior_observation_2025-12-01.md +85 -0
  390. package/docs/attestation/copilot_summarization_screenshot_2025-12-01.png +0 -0
  391. package/docs/attestation/employment_separation_2025-11-26.ots +0 -0
  392. package/docs/attestation/employment_timestamp_response.tsr +0 -0
  393. package/docs/attestation/freetsa_cacert.pem +45 -0
  394. package/docs/attestation/freetsa_tsa.crt +45 -0
  395. package/docs/attestation/lex_employment_separation_2025-11-26.md +85 -0
  396. package/docs/attestation/lex_employment_separation_2025-11-26_VERIFICATION.md +126 -0
  397. package/docs/attestation/patent/2025-12-07-shadow-governance-pct-draft.md +350 -0
  398. package/docs/attestation/patent/2025-12-07-shadow-governance-pct-draft.md.ots +0 -0
  399. package/docs/attestation/patent/2025-12-07-shadow-governance-pct-draft_VERIFICATION.md +130 -0
  400. package/docs/attestation/patent/README.md +75 -0
  401. package/docs/attestation/patent/fig1_write_path.svg +58 -0
  402. package/docs/attestation/patent/fig2_read_normalize_rollup.svg +92 -0
  403. package/docs/attestation/timestamp_response.tsr +0 -0
  404. package/docs/attribution-README.md +264 -0
  405. package/docs/audit-compliance.md +283 -0
  406. package/docs/audit-outputs.md +1213 -0
  407. package/docs/audit-sdk.md +1134 -0
  408. package/docs/autopilot-levels.md +368 -0
  409. package/docs/autopilot.md +288 -0
  410. package/docs/ci-cd-integration.md +580 -0
  411. package/docs/ci-integration-guide.md +369 -0
  412. package/docs/ci-version-validation.md +198 -0
  413. package/docs/cli-mcp-weave-reporting.md +462 -0
  414. package/docs/cli.md +2262 -0
  415. package/docs/cluster-gates-rollback.md +222 -0
  416. package/docs/command-creation-guide.md +485 -0
  417. package/docs/command-whitelist.md +490 -0
  418. package/docs/commands/idea.md +253 -0
  419. package/docs/config.md +245 -0
  420. package/docs/conflict-clustering.md +225 -0
  421. package/docs/conflict-predictor.md +359 -0
  422. package/docs/context-diet.md +249 -0
  423. package/docs/counter-examples.md +199 -0
  424. package/docs/create-project.md +211 -0
  425. package/docs/deliverables-generator.md +299 -0
  426. package/docs/deliverables-management.md +474 -0
  427. package/docs/dependency-parser.md +354 -0
  428. package/docs/determinism.md +299 -0
  429. package/docs/diffgraph-planner.md +1211 -0
  430. package/docs/dogfood/README.md +33 -0
  431. package/docs/dogfood/wave-3-results.md +303 -0
  432. package/docs/dogfood-merge-weave-script.md +224 -0
  433. package/docs/enterprise-onboarding.md +291 -0
  434. package/docs/environment-variables.md +625 -0
  435. package/docs/error-recovery.md +466 -0
  436. package/docs/errors.md +288 -0
  437. package/docs/executor-authoring.md +854 -0
  438. package/docs/executor-decoupling.md +410 -0
  439. package/docs/front-end-capture-pipeline.md +312 -0
  440. package/docs/gate-report-examples.md +380 -0
  441. package/docs/gates.md +319 -0
  442. package/docs/github-automation.md +128 -0
  443. package/docs/governance-metrics.md +368 -0
  444. package/docs/integrations/README.md +588 -0
  445. package/docs/interactive-plan-review.md +493 -0
  446. package/docs/issue-orchestration.md +256 -0
  447. package/docs/lex_ax_session_key_rememberings_v0.1.md +195 -0
  448. package/docs/lexrunner-v1-summary.md +246 -0
  449. package/docs/lexrunner-v2-contract.md +404 -0
  450. package/docs/lexrunner-v2-migration-plan.md +388 -0
  451. package/docs/lexrunner-v2-salvage-map.md +355 -0
  452. package/docs/lexsona-rules.md +154 -0
  453. package/docs/merge-weave-analysis.md +403 -0
  454. package/docs/merge-weave-quickstart.md +770 -0
  455. package/docs/merge-weave-state-machine.md +390 -0
  456. package/docs/migration-guide.md +529 -0
  457. package/docs/monitoring-examples.md +470 -0
  458. package/docs/monitoring-implementation.md +252 -0
  459. package/docs/orchestration.md +234 -0
  460. package/docs/performance-scale.md +359 -0
  461. package/docs/plan-generation.md +407 -0
  462. package/docs/profile-resolution.md +455 -0
  463. package/docs/prompts.md +427 -0
  464. package/docs/quickstart.md +546 -0
  465. package/docs/release-process.md +310 -0
  466. package/docs/sample-prompts/merge-weave/cli-merge-weave-kickoff.md +274 -0
  467. package/docs/sample-prompts/merge-weave/mcp-merge-weave-kickoff.md +480 -0
  468. package/docs/sample-prompts/merge-weave/standalone-merge-weave-kickoff.md +237 -0
  469. package/docs/schemas.md +359 -0
  470. package/docs/scope-validation.md +444 -0
  471. package/docs/security/rotation-guide.md +325 -0
  472. package/docs/specs/Meeting_Control_Stack_Concept_v0.1.0.md +417 -0
  473. package/docs/specs/git-feature-flag-redesign.md +321 -0
  474. package/docs/specs/lex-pr-brief-behavior.md +269 -0
  475. package/docs/specs/smartergpt-structure-v1.md +705 -0
  476. package/docs/specs/task-brief-v0.1.md +224 -0
  477. package/docs/store-architecture.md +61 -0
  478. package/docs/templates/CONTRIBUTING-merge-weave-section.md +33 -0
  479. package/docs/templates/gates.example.yml +109 -0
  480. package/docs/templates/plan.example.json +77 -0
  481. package/docs/thesis/00-EVOLUTION-NOTES.md +383 -0
  482. package/docs/thesis/01-CORE-THESIS.md +285 -0
  483. package/docs/thesis/02-TURN-COST.md +498 -0
  484. package/docs/thesis/03-PERMISSION-TO-FAIL.md +581 -0
  485. package/docs/thesis/04-CROSS-MODEL-CONTINUITY.md +517 -0
  486. package/docs/thesis/05-RULE-FILE-SPEC.md +732 -0
  487. package/docs/thesis/06-CAPABILITY-TIERS.md +723 -0
  488. package/docs/thesis/07-ROBERT-FIELD-REPORT.md +433 -0
  489. package/docs/thesis/08-IMPLEMENTATION-GUIDE.md +1093 -0
  490. package/docs/thesis/09-METRICS-AND-TELEMETRY.md +793 -0
  491. package/docs/thesis/10-FAILURE-MODES.md +716 -0
  492. package/docs/thesis/README.md +151 -0
  493. package/docs/thesis/lex_governance-collab_systems_paper_draft.md +952 -0
  494. package/docs/thesis/lex_governance-collab_systems_paper_draft.pdf +0 -0
  495. package/docs/tool-grounded/READINESS_ANALYSIS.md +527 -0
  496. package/docs/tool-grounded/enforcement.md +361 -0
  497. package/docs/tool-grounded/tool-grounded-a-view-from-the-inside.md +437 -0
  498. package/docs/tool-grounded/tool-grounded-prompt.md +122 -0
  499. package/docs/tool-grounded/tool-grounded-run-centric.md +474 -0
  500. package/docs/troubleshooting-planner.md +910 -0
  501. package/docs/troubleshooting.md +745 -0
  502. package/docs/tutorials/README.md +201 -0
  503. package/docs/tutorials/diffgraph-planner/01-simple-stack.md +460 -0
  504. package/docs/tutorials/diffgraph-planner/02-diamond-pattern.md +431 -0
  505. package/docs/tutorials/diffgraph-planner/03-large-batch.md +525 -0
  506. package/docs/tutorials/diffgraph-planner/04-fixing-cycles.md +526 -0
  507. package/docs/tutorials/diffgraph-planner/05-hybrid-workflow.md +555 -0
  508. package/docs/tutorials/quick-merge-pyramid.md +364 -0
  509. package/docs/tutorials/video-scripts/01-getting-started.md +286 -0
  510. package/docs/tutorials/video-scripts/02-understanding-dependencies.md +376 -0
  511. package/docs/weave-contract.md +116 -0
  512. package/docs/weave-execution-log.md +153 -0
  513. package/docs/workflows/README.md +139 -0
  514. package/docs/workflows/enterprise.md +545 -0
  515. package/docs/workflows/small-team.md +398 -0
  516. package/docs/workflows/solo-developer.md +419 -0
  517. package/dogfood-merge-weave.sh +122 -0
  518. package/examples/README.md +22 -0
  519. package/examples/WORKING_EXAMPLE.md +309 -0
  520. package/examples/analyze-pr-files.js +100 -0
  521. package/examples/autopilot-level4-example.md +234 -0
  522. package/examples/cluster-gates-demo.sh +178 -0
  523. package/examples/complete-security-workflow.ts +248 -0
  524. package/examples/error-recovery/README.md +202 -0
  525. package/examples/executor-manifest.example.yaml +81 -0
  526. package/examples/front-end-capture-pipeline/README.md +99 -0
  527. package/examples/front-end-capture-pipeline/create-project-example.sh +83 -0
  528. package/examples/front-end-capture-pipeline/idea-dark-mode.json +14 -0
  529. package/examples/front-end-capture-pipeline/idea-example.sh +57 -0
  530. package/examples/front-end-capture-pipeline/manual-test-checklist.md +426 -0
  531. package/examples/gates/README.md +165 -0
  532. package/examples/gates/lint-gate.sh +40 -0
  533. package/examples/gates/lint-gate.ts +99 -0
  534. package/examples/gates/test-runner.ts +113 -0
  535. package/examples/gates/vuln-scanner.ts +95 -0
  536. package/examples/github-integration/README.md +111 -0
  537. package/examples/github-integration/example-plan.json +95 -0
  538. package/examples/performance-config.md +388 -0
  539. package/examples/profile-setup/.gitignore.template +66 -0
  540. package/examples/profile-setup/.smartergpt-example/README.md +190 -0
  541. package/examples/profile-setup/.smartergpt.local-example/README.md +365 -0
  542. package/examples/profile-setup/README.md +492 -0
  543. package/examples/profile-setup/cross-repo-prompts/README.md +606 -0
  544. package/examples/safety-framework-demo.ts +130 -0
  545. package/examples/safety-mechanisms-example.ts +191 -0
  546. package/examples/sample-plan.json +87 -0
  547. package/examples/sample-stack.yml +66 -0
  548. package/examples/sarif/README.md +224 -0
  549. package/examples/scope-validation-demo.ts +199 -0
  550. package/examples/security-integration.ts +293 -0
  551. package/examples/token-tracking-example.ts +71 -0
  552. package/executors/senior-dev/ARCHITECTURE.md +182 -0
  553. package/executors/senior-dev/MEMORY_INTEGRATION.md +236 -0
  554. package/executors/senior-dev/QUICK_START.md +145 -0
  555. package/executors/senior-dev/README.md +76 -0
  556. package/executors/senior-dev/examples/sample-review-session.md +228 -0
  557. package/executors/senior-dev/executor-manifest.yaml +79 -0
  558. package/executors/senior-dev/prompts/code-review.prompt.md +78 -0
  559. package/executors/senior-dev/prompts/mentorship-feedback.prompt.md +97 -0
  560. package/executors/senior-dev/prompts/pattern-recognition.prompt.md +80 -0
  561. package/executors/senior-dev/prompts/pr-analysis.prompt.md +75 -0
  562. package/executors/senior-dev/scripts/capture-review-frame.sh +129 -0
  563. package/executors/senior-dev/scripts/prepare-review-context.sh +61 -0
  564. package/executors/senior-dev/scripts/recall-context.sh +87 -0
  565. package/lexrunner-launcher.sh +12 -0
  566. package/mcp-config-example.json +14 -0
  567. package/mcp-server.mjs +1221 -0
  568. package/merge-weave-current-prs.md +170 -0
  569. package/merge-weave-dogfood.json +46 -0
  570. package/merge-weave-plan.json +56 -0
  571. package/package.json +140 -0
  572. package/procedures/merge-weave-main.yaml +90 -0
  573. package/procedures/pr-review.yaml +68 -0
  574. package/project/README.md +50 -0
  575. package/prompts/tool-grounded-mode.md +185 -0
  576. package/schemas/allowed-commands.schema.json +108 -0
  577. package/schemas/audit-events.schema.json +138 -0
  578. package/schemas/audit-events.v1.0.0.schema.json +138 -0
  579. package/schemas/edit-plan.schema.json +80 -0
  580. package/schemas/executor-manifest.schema.json +236 -0
  581. package/schemas/flake-report.schema.json +95 -0
  582. package/schemas/gate-report.schema.json +85 -0
  583. package/schemas/gates/build.schema.json +32 -0
  584. package/schemas/gates/coverage.schema.json +42 -0
  585. package/schemas/gates/lint.schema.json +34 -0
  586. package/schemas/gates/security-scan.schema.json +33 -0
  587. package/schemas/gates/test.schema.json +35 -0
  588. package/schemas/next-option.schema.json +60 -0
  589. package/schemas/persona-snapshot.schema.json +66 -0
  590. package/schemas/plan.schema.json +300 -0
  591. package/schemas/status-response.schema.json +193 -0
  592. package/scripts/README.md +354 -0
  593. package/scripts/analyze-governance-logs.mjs +51 -0
  594. package/scripts/benchmark-ci.ts +339 -0
  595. package/scripts/check-determinism.sh +23 -0
  596. package/scripts/check-license-compliance.mjs +319 -0
  597. package/scripts/check-release-drift.mjs +81 -0
  598. package/scripts/ci-debug.sh +24 -0
  599. package/scripts/ci-smoke.mjs +304 -0
  600. package/scripts/create-sample-repo.sh +245 -0
  601. package/scripts/dogfood-merge-weave.sh +552 -0
  602. package/scripts/gen_mcp_servers.py +252 -0
  603. package/scripts/generate-executor-manifest-schema.ts +30 -0
  604. package/scripts/generate-flake-schema.ts +32 -0
  605. package/scripts/generate-gate-schema.ts +32 -0
  606. package/scripts/generate-plan-schema.ts +30 -0
  607. package/scripts/generate-run-schemas.ts +69 -0
  608. package/scripts/load-prompt.mjs +147 -0
  609. package/scripts/merge-weave-wrapper.sh +445 -0
  610. package/scripts/merge-weave.sh +489 -0
  611. package/scripts/metrics-template.ts +134 -0
  612. package/scripts/package-lex.sh +267 -0
  613. package/scripts/quick-start-merge-weave.sh +218 -0
  614. package/scripts/release-prepare.ts +350 -0
  615. package/scripts/rotate-secrets-example.ts +134 -0
  616. package/scripts/test-lexsona-shadow.mjs +100 -0
  617. package/scripts/validate-manifests.ts +188 -0
  618. package/scripts/verify-audit-phase2.js +175 -0
  619. package/src/ai/README.md +456 -0
  620. package/src/ai/conflictStrategy.ts +223 -0
  621. package/src/ai/conflictStrategyCache.ts +164 -0
  622. package/src/ai/conflictStrategyPrompt.ts +128 -0
  623. package/src/ai/conflictStrategySchema.ts +165 -0
  624. package/src/ai/heuristicFallback.ts +162 -0
  625. package/src/ai/index.ts +64 -0
  626. package/src/ai/riskScoring.ts +174 -0
  627. package/src/aliases/index.ts +16 -0
  628. package/src/aliases/resolver.ts +212 -0
  629. package/src/audit/context.ts +284 -0
  630. package/src/audit/emitter.ts +685 -0
  631. package/src/audit/events.ts +210 -0
  632. package/src/audit/gateMatrix.ts +158 -0
  633. package/src/audit/index.ts +44 -0
  634. package/src/audit/manifest.ts +78 -0
  635. package/src/audit/profiles.ts +93 -0
  636. package/src/audit/redaction.ts +216 -0
  637. package/src/audit/sarif.ts +213 -0
  638. package/src/audit/schema/events.ts +366 -0
  639. package/src/audit/schema/manifest.ts +47 -0
  640. package/src/audit/schema.ts +159 -0
  641. package/src/audit/sdk/index.ts +145 -0
  642. package/src/audit/sdk/types.ts +88 -0
  643. package/src/audit/sidecar.ts +111 -0
  644. package/src/audit/signing.ts +521 -0
  645. package/src/autopilot/README.md +113 -0
  646. package/src/autopilot/artifacts.ts +287 -0
  647. package/src/autopilot/base.ts +132 -0
  648. package/src/autopilot/deliverables.ts +392 -0
  649. package/src/autopilot/index.ts +29 -0
  650. package/src/autopilot/level1.ts +187 -0
  651. package/src/autopilot/level2.ts +262 -0
  652. package/src/autopilot/level3.ts +263 -0
  653. package/src/autopilot/level4.ts +393 -0
  654. package/src/autopilot/safety/README.md +512 -0
  655. package/src/autopilot/safety/SafetyFramework.ts +634 -0
  656. package/src/autopilot/safety/index.ts +16 -0
  657. package/src/autopilot/types.ts +250 -0
  658. package/src/budget/index.ts +56 -0
  659. package/src/budget/manager.ts +547 -0
  660. package/src/budget/schema.ts +305 -0
  661. package/src/budget/tracker.ts +155 -0
  662. package/src/cache/issue-cache.ts +150 -0
  663. package/src/cli/command-map.ts +221 -0
  664. package/src/cli/commands/gate/test.ts +214 -0
  665. package/src/cli/exitHandler.ts +98 -0
  666. package/src/cli/flags.ts +123 -0
  667. package/src/cli/formatSuggestions.ts +202 -0
  668. package/src/cli/formatters.ts +294 -0
  669. package/src/cli/jsonEnvelope.ts +152 -0
  670. package/src/cli/output.ts +61 -0
  671. package/src/cli/runnerLifecycle.ts +118 -0
  672. package/src/cli-audit.ts +76 -0
  673. package/src/cli-security.ts +114 -0
  674. package/src/cli.ts +1231 -0
  675. package/src/commands/audit/index.ts +5 -0
  676. package/src/commands/audit/verify.ts +87 -0
  677. package/src/commands/autopilot.ts +131 -0
  678. package/src/commands/budget.ts +327 -0
  679. package/src/commands/bulkOps.ts +204 -0
  680. package/src/commands/completion.ts +287 -0
  681. package/src/commands/config/validate.ts +428 -0
  682. package/src/commands/config.ts +368 -0
  683. package/src/commands/counterExamples.ts +104 -0
  684. package/src/commands/create-project.ts +338 -0
  685. package/src/commands/discover.ts +192 -0
  686. package/src/commands/doctor.ts +436 -0
  687. package/src/commands/execute.ts +558 -0
  688. package/src/commands/explain.ts +157 -0
  689. package/src/commands/fanout-analyze.ts +684 -0
  690. package/src/commands/fanout-harvest.ts +328 -0
  691. package/src/commands/fanout-monitor.ts +224 -0
  692. package/src/commands/gateAttest.ts +95 -0
  693. package/src/commands/gateImport.ts +142 -0
  694. package/src/commands/gateImportChecks.ts +208 -0
  695. package/src/commands/gateReport.ts +184 -0
  696. package/src/commands/governanceCleanup.ts +171 -0
  697. package/src/commands/governanceReport.ts +497 -0
  698. package/src/commands/guards.ts +50 -0
  699. package/src/commands/idea.ts +281 -0
  700. package/src/commands/init.ts +414 -0
  701. package/src/commands/issues.ts +165 -0
  702. package/src/commands/merge.ts +677 -0
  703. package/src/commands/mergeOrder.ts +68 -0
  704. package/src/commands/metrics.ts +232 -0
  705. package/src/commands/migrateProfile.ts +187 -0
  706. package/src/commands/orchestrate/analyze-issues.ts +203 -0
  707. package/src/commands/orchestrate/assign-batch.ts +204 -0
  708. package/src/commands/orchestrate/generate-deliverables.ts +66 -0
  709. package/src/commands/orchestrate/pinToolchain.ts +102 -0
  710. package/src/commands/orchestrate/plan-batch.ts +119 -0
  711. package/src/commands/orchestrate/predict-conflicts.ts +210 -0
  712. package/src/commands/orchestrate.ts +186 -0
  713. package/src/commands/plan.ts +403 -0
  714. package/src/commands/planDiff.ts +56 -0
  715. package/src/commands/planReview.ts +112 -0
  716. package/src/commands/planViewer.ts +180 -0
  717. package/src/commands/preview-constraints.ts +97 -0
  718. package/src/commands/query.ts +313 -0
  719. package/src/commands/report.ts +56 -0
  720. package/src/commands/retry.ts +60 -0
  721. package/src/commands/schema.ts +128 -0
  722. package/src/commands/security.ts +140 -0
  723. package/src/commands/seniorDev.ts +326 -0
  724. package/src/commands/status.ts +97 -0
  725. package/src/commands/tokenReport.ts +167 -0
  726. package/src/commands/validation.ts +66 -0
  727. package/src/commands/weave-checkpoints.ts +145 -0
  728. package/src/commands/weave-fanout.ts +273 -0
  729. package/src/commands/weave-policy.ts +277 -0
  730. package/src/commands/weave.ts +518 -0
  731. package/src/config/localOverlay.ts +167 -0
  732. package/src/config/pathResolver.ts +106 -0
  733. package/src/config/profileResolver.ts +194 -0
  734. package/src/config/promptsResolver.ts +312 -0
  735. package/src/config/rulesResolver.ts +257 -0
  736. package/src/config/schemas.ts +142 -0
  737. package/src/core/bootstrap.ts +287 -0
  738. package/src/core/enterprise.ts +453 -0
  739. package/src/core/errorRecovery.ts +509 -0
  740. package/src/core/githubPlan.ts +282 -0
  741. package/src/core/inputs.ts +314 -0
  742. package/src/core/multiRepoPlan.ts +353 -0
  743. package/src/core/plan.ts +106 -0
  744. package/src/core/snapshot.ts +189 -0
  745. package/src/errors/adapters.ts +897 -0
  746. package/src/errors/index.ts +231 -0
  747. package/src/executionState.ts +356 -0
  748. package/src/executors/README_FRAME_CONTRACT.md +446 -0
  749. package/src/executors/frameContract.ts +270 -0
  750. package/src/executors/guardrailEnforcement.ts +294 -0
  751. package/src/executors/seniorDev/core.ts +548 -0
  752. package/src/executors/seniorDev/index.ts +30 -0
  753. package/src/executors/seniorDev/types.ts +176 -0
  754. package/src/executors/toolBudget.ts +194 -0
  755. package/src/fanout/analyzer.ts +735 -0
  756. package/src/fanout/github-adapter.ts +262 -0
  757. package/src/fanout/harvest.ts +517 -0
  758. package/src/fanout/monitor.ts +350 -0
  759. package/src/fanout/types.ts +428 -0
  760. package/src/frames/controller.ts +160 -0
  761. package/src/frames/emitter.ts +455 -0
  762. package/src/frames/index.ts +58 -0
  763. package/src/frames/storage.ts +203 -0
  764. package/src/frames/types.ts +258 -0
  765. package/src/gates/checkRunConverter.ts +91 -0
  766. package/src/gates/test/adapters/errors.ts +32 -0
  767. package/src/gates/test/adapters/index.ts +36 -0
  768. package/src/gates/test/adapters/interface.ts +63 -0
  769. package/src/gates/test/adapters/jest-json.ts +370 -0
  770. package/src/gates/test/adapters/junit-xml.ts +400 -0
  771. package/src/gates/test/adapters/registry.ts +149 -0
  772. package/src/gates/test/adapters/vitest-json.ts +339 -0
  773. package/src/gates/test/enrichment/failureId.ts +74 -0
  774. package/src/gates/test/enrichment/index.ts +25 -0
  775. package/src/gates/test/enrichment/nextActions.ts +322 -0
  776. package/src/gates/test/enrichment/rerunTemplates.ts +105 -0
  777. package/src/gates/test/enrichment/signature.ts +58 -0
  778. package/src/gates/test/enrichment/stackParser.ts +149 -0
  779. package/src/gates/test/enrichment/types.ts +67 -0
  780. package/src/gates/test/formatters/markdown.spec.ts +942 -0
  781. package/src/gates/test/formatters/markdown.ts +296 -0
  782. package/src/gates/test/index.ts +54 -0
  783. package/src/gates/test/schema.spec.ts +372 -0
  784. package/src/gates/test/schema.ts +327 -0
  785. package/src/gates/validator.ts +92 -0
  786. package/src/gates.ts +1022 -0
  787. package/src/git/operations.ts +592 -0
  788. package/src/git/parseRemote.ts +22 -0
  789. package/src/github/api.ts +584 -0
  790. package/src/github/batch-ops.ts +215 -0
  791. package/src/github/client.ts +647 -0
  792. package/src/github/contextDiet.ts +205 -0
  793. package/src/github/diffHunks.ts +285 -0
  794. package/src/github/index.ts +11 -0
  795. package/src/github/minimalContext.ts +212 -0
  796. package/src/github/minimalContextClient.ts +105 -0
  797. package/src/github/symbolMap.ts +370 -0
  798. package/src/github/types.ts +166 -0
  799. package/src/governance/index.ts +42 -0
  800. package/src/governance/mcpStatus.ts +258 -0
  801. package/src/governance/timeoutAdjustment.ts +149 -0
  802. package/src/governance/turnCostSummary.ts +182 -0
  803. package/src/hooks/events.ts +374 -0
  804. package/src/hooks/index.ts +8 -0
  805. package/src/hostility/checks.ts +408 -0
  806. package/src/hostility/index.ts +108 -0
  807. package/src/hostility/score.ts +143 -0
  808. package/src/interactive/planDiff.ts +168 -0
  809. package/src/interactive/planHistory.ts +205 -0
  810. package/src/interactive/planReview.ts +531 -0
  811. package/src/learning/counter-example.ts +174 -0
  812. package/src/learning/prompts.ts +107 -0
  813. package/src/learning/storage.ts +230 -0
  814. package/src/lexsona/client.ts +367 -0
  815. package/src/lexsona/index.ts +44 -0
  816. package/src/lexsona/logger.ts +408 -0
  817. package/src/lexsona/types.ts +177 -0
  818. package/src/mcp/DEPRECATED.md +33 -0
  819. package/src/mcp/server.ts +3587 -0
  820. package/src/mcp/types/guided-response.ts +95 -0
  821. package/src/mcp/types.ts +468 -0
  822. package/src/mcp/workflow/state-machine.ts +277 -0
  823. package/src/mergeEligibility.ts +355 -0
  824. package/src/mergeOrder.ts +170 -0
  825. package/src/metrics/export.ts +472 -0
  826. package/src/metrics/index.ts +35 -0
  827. package/src/metrics/turncost.ts +284 -0
  828. package/src/monitoring/README.md +222 -0
  829. package/src/monitoring/audit.ts +98 -0
  830. package/src/monitoring/cache.ts +121 -0
  831. package/src/monitoring/dashboards/grafana-dashboard.json +172 -0
  832. package/src/monitoring/errorRecovery.ts +334 -0
  833. package/src/monitoring/errors.ts +105 -0
  834. package/src/monitoring/fileLogger.ts +194 -0
  835. package/src/monitoring/hallucinations.ts +45 -0
  836. package/src/monitoring/health.ts +171 -0
  837. package/src/monitoring/index.ts +16 -0
  838. package/src/monitoring/lock.ts +158 -0
  839. package/src/monitoring/logger.ts +178 -0
  840. package/src/monitoring/metrics.ts +245 -0
  841. package/src/monitoring/profiler.ts +156 -0
  842. package/src/monitoring/tokenLogger.ts +141 -0
  843. package/src/orchestrate/analyzer.ts +461 -0
  844. package/src/orchestrate/index.ts +6 -0
  845. package/src/orchestrate/types.ts +65 -0
  846. package/src/orchestration/README.md +480 -0
  847. package/src/orchestration/agentAssigner.ts +206 -0
  848. package/src/orchestration/batchPlanner.ts +201 -0
  849. package/src/orchestration/conflictClustering.ts +344 -0
  850. package/src/orchestration/conflictGraph.ts +63 -0
  851. package/src/orchestration/conflictPredictor.ts +170 -0
  852. package/src/orchestration/deliverablesGenerator.ts +345 -0
  853. package/src/orchestration/determinism.ts +232 -0
  854. package/src/orchestration/index.ts +45 -0
  855. package/src/orchestration/mergeTreeSimulator.ts +137 -0
  856. package/src/orchestration/mis.ts +123 -0
  857. package/src/orchestration/toolchainManifest.ts +169 -0
  858. package/src/orchestration/types.ts +103 -0
  859. package/src/performance.README.md +99 -0
  860. package/src/performance.ts +279 -0
  861. package/src/planner/README.md +215 -0
  862. package/src/planner/dependencyParser.ts +404 -0
  863. package/src/planner/dependencyScoring.ts +346 -0
  864. package/src/planner/fileAnalysis.ts +693 -0
  865. package/src/planner/index.ts +41 -0
  866. package/src/planner/scopeValidator.ts +308 -0
  867. package/src/planner/types.ts +80 -0
  868. package/src/planner/validation.ts +493 -0
  869. package/src/preview/constraints.ts +333 -0
  870. package/src/procedures/index.ts +47 -0
  871. package/src/procedures/loader.ts +252 -0
  872. package/src/procedures/schema.ts +191 -0
  873. package/src/procedures/stateMachine.ts +160 -0
  874. package/src/procedures/types.ts +178 -0
  875. package/src/receipts/emit.ts +354 -0
  876. package/src/receipts/index.ts +48 -0
  877. package/src/receipts/schema.ts +227 -0
  878. package/src/report/aggregate.ts +160 -0
  879. package/src/runs/artifacts.ts +315 -0
  880. package/src/runs/attribution.ts +132 -0
  881. package/src/runs/context.ts +54 -0
  882. package/src/runs/decisions.ts +407 -0
  883. package/src/runs/enforcement.ts +395 -0
  884. package/src/runs/failures.ts +517 -0
  885. package/src/runs/index.ts +141 -0
  886. package/src/runs/manager.ts +910 -0
  887. package/src/runs/statusBuilder.ts +233 -0
  888. package/src/runs/storage.ts +290 -0
  889. package/src/runs/types.ts +216 -0
  890. package/src/schema/flakeReport.ts +74 -0
  891. package/src/schema/gateMapping.ts +107 -0
  892. package/src/schema/gateReport.ts +236 -0
  893. package/src/schema/weaveLock.ts +51 -0
  894. package/src/schema.ts +313 -0
  895. package/src/schemas/executorManifest.ts +204 -0
  896. package/src/schemas/feature-spec-v0.ts +40 -0
  897. package/src/schemas/persona.ts +162 -0
  898. package/src/schemas/project.ts +91 -0
  899. package/src/schemas/runCentric.ts +402 -0
  900. package/src/schemas/task-contract.ts +626 -0
  901. package/src/schemas/vacuumReadyPrompt.ts +128 -0
  902. package/src/sdk/index.ts +113 -0
  903. package/src/sdk/parser.ts +101 -0
  904. package/src/sdk/query.ts +315 -0
  905. package/src/sdk/validator.ts +114 -0
  906. package/src/security/README.md +496 -0
  907. package/src/security/authentication.ts +173 -0
  908. package/src/security/authorization.ts +348 -0
  909. package/src/security/commandValidator.ts +195 -0
  910. package/src/security/compliance.ts +688 -0
  911. package/src/security/index.ts +85 -0
  912. package/src/security/policy.ts +399 -0
  913. package/src/security/sarif.ts +179 -0
  914. package/src/security/scanning.ts +362 -0
  915. package/src/security/secrets.ts +520 -0
  916. package/src/shared/git/index.ts +30 -0
  917. package/src/shared/git/runGit.ts +281 -0
  918. package/src/shared/git/runtime.ts +66 -0
  919. package/src/snapshot/builder.ts +229 -0
  920. package/src/snapshot/index.ts +8 -0
  921. package/src/store/CONTRACT.md +189 -0
  922. package/src/store/README.md +22 -0
  923. package/src/store/index.ts +99 -0
  924. package/src/store/inmemory/index.ts +10 -0
  925. package/src/store/inmemory/run-store.ts +268 -0
  926. package/src/store/postgres/.gitkeep +0 -0
  927. package/src/store/run-store.ts +405 -0
  928. package/src/store/sqlite/index.ts +7 -0
  929. package/src/store/sqlite/run-store.ts +525 -0
  930. package/src/store/sqlite/schema.sql +67 -0
  931. package/src/telemetry/frames.ts +179 -0
  932. package/src/telemetry/index.ts +5 -0
  933. package/src/tiers/index.ts +34 -0
  934. package/src/tiers/metrics.ts +156 -0
  935. package/src/tiers/schema.ts +95 -0
  936. package/src/tiers/suggest.ts +183 -0
  937. package/src/types/guardrails.ts +452 -0
  938. package/src/types/index.ts +42 -0
  939. package/src/util/canonicalJson.ts +29 -0
  940. package/src/util/colorControl.ts +46 -0
  941. package/src/util/envUtils.ts +139 -0
  942. package/src/util/hash.ts +69 -0
  943. package/src/util/lockHash.ts +90 -0
  944. package/src/util/minHeap.ts +108 -0
  945. package/src/util/progress.ts +89 -0
  946. package/src/util/tokenEstimator.ts +55 -0
  947. package/src/utils/fingerprint.ts +105 -0
  948. package/src/utils/paths.ts +209 -0
  949. package/src/utils/tokens.ts +151 -0
  950. package/src/utils/validation.ts +53 -0
  951. package/src/verification/diff-applier.ts +60 -0
  952. package/src/verification/engine-verifier.ts +171 -0
  953. package/src/verification/errors.ts +30 -0
  954. package/src/verification/index.ts +13 -0
  955. package/src/weave/audit/index.ts +17 -0
  956. package/src/weave/audit/logger.ts +206 -0
  957. package/src/weave/authority/evaluator.ts +660 -0
  958. package/src/weave/authority/index.ts +30 -0
  959. package/src/weave/authority/schema.ts +292 -0
  960. package/src/weave/checkpoint/index.ts +7 -0
  961. package/src/weave/checkpoint/storage.ts +223 -0
  962. package/src/weave/checkpoint/types.ts +121 -0
  963. package/src/weave/checkpoint/utils.ts +207 -0
  964. package/src/weave/clusterGates.ts +366 -0
  965. package/src/weave/draftPR.ts +214 -0
  966. package/src/weave/executor/d1-executor.ts +822 -0
  967. package/src/weave/executor/d2-executor.ts +381 -0
  968. package/src/weave/executor/index.ts +24 -0
  969. package/src/weave/executor/types.ts +135 -0
  970. package/src/weave/fanout/generator.ts +186 -0
  971. package/src/weave/fanout/index.ts +51 -0
  972. package/src/weave/fanout/loader.ts +134 -0
  973. package/src/weave/fanout/matcher.ts +239 -0
  974. package/src/weave/fanout/schema.ts +178 -0
  975. package/src/weave/frameHelper.ts +126 -0
  976. package/src/weave/gateFailureHandler.ts +405 -0
  977. package/src/weave/index.ts +89 -0
  978. package/src/weave/lockFile.ts +193 -0
  979. package/src/weave/mergeHelpers.ts +377 -0
  980. package/src/weave/mergeWeaveSequential.ts +282 -0
  981. package/src/weave/metrics/calculator.ts +362 -0
  982. package/src/weave/metrics/index.ts +44 -0
  983. package/src/weave/metrics/logger.ts +291 -0
  984. package/src/weave/metrics/schema.ts +505 -0
  985. package/src/weave/planner/index.ts +23 -0
  986. package/src/weave/planner/planner.ts +411 -0
  987. package/src/weave/planner/types.ts +181 -0
  988. package/src/weave/policy/index.ts +63 -0
  989. package/src/weave/policy/loader.ts +148 -0
  990. package/src/weave/policy/schema.ts +290 -0
  991. package/src/weave/post-merge-checks.ts +220 -0
  992. package/src/weave/preflightConflicts.ts +375 -0
  993. package/src/weave/receiptHelper.ts +287 -0
  994. package/src/weave/recovery.ts +232 -0
  995. package/src/weave/resolutionGuidance.ts +173 -0
  996. package/src/weave/stateMachine.ts +426 -0
  997. package/src/weave/testfix/applier.ts +195 -0
  998. package/src/weave/testfix/index.ts +18 -0
  999. package/src/weave/testfix/loader.ts +116 -0
  1000. package/src/weave/testfix/matcher.ts +158 -0
  1001. package/src/weave/testfix/schema.ts +218 -0
  1002. package/src/weave/types.ts +305 -0
  1003. package/src/weave/utils/copilot-completion.ts +76 -0
  1004. package/test-mcp-dogfood.mjs +128 -0
  1005. package/test-mcp.mjs +116 -0
  1006. package/tests/README.md +155 -0
  1007. package/tests/advanced-cli-e2e.spec.ts +218 -0
  1008. package/tests/agentAssigner.spec.ts +261 -0
  1009. package/tests/ai-conflict-strategy-cache.spec.ts +254 -0
  1010. package/tests/ai-conflict-strategy-risk.spec.ts +287 -0
  1011. package/tests/ai-conflict-strategy-schema.spec.ts +252 -0
  1012. package/tests/ai-conflict-strategy.spec.ts +442 -0
  1013. package/tests/aliases/resolver.spec.ts +238 -0
  1014. package/tests/audit/context.spec.ts +283 -0
  1015. package/tests/audit/emitter.spec.ts +347 -0
  1016. package/tests/audit/gateMatrix.spec.ts +335 -0
  1017. package/tests/audit/integration.spec.ts +236 -0
  1018. package/tests/audit/redaction.spec.ts +290 -0
  1019. package/tests/audit/sarif-integration.spec.ts +303 -0
  1020. package/tests/audit/sarif.spec.ts +458 -0
  1021. package/tests/audit/schema-events.spec.ts +421 -0
  1022. package/tests/audit/schema.spec.ts +434 -0
  1023. package/tests/audit/sdk-integration.spec.ts +598 -0
  1024. package/tests/audit/sdk.spec.ts +318 -0
  1025. package/tests/audit/signing-integration.spec.ts +276 -0
  1026. package/tests/audit/signing.spec.ts +350 -0
  1027. package/tests/audit-signing.spec.ts +406 -0
  1028. package/tests/audit-verify-cli.spec.ts +176 -0
  1029. package/tests/autopilot-e2e-level3-4.spec.ts +741 -0
  1030. package/tests/autopilot-integration.spec.ts +274 -0
  1031. package/tests/autopilot-level1.spec.ts +449 -0
  1032. package/tests/autopilot-level2.spec.ts +188 -0
  1033. package/tests/autopilot-level3.spec.ts +266 -0
  1034. package/tests/autopilot-level4.spec.ts +454 -0
  1035. package/tests/autopilot.spec.ts +379 -0
  1036. package/tests/ax-error-adapters.spec.ts +580 -0
  1037. package/tests/batch-planner.spec.ts +500 -0
  1038. package/tests/benchmark-infrastructure.spec.ts +445 -0
  1039. package/tests/benchmarks/README.md +103 -0
  1040. package/tests/benchmarks/baselines/baseline.json +127 -0
  1041. package/tests/benchmarks/core/dependencyResolver.bench.ts +128 -0
  1042. package/tests/benchmarks/core/planParser.bench.ts +114 -0
  1043. package/tests/benchmarks/core/topologicalSort.bench.ts +102 -0
  1044. package/tests/benchmarks/index.ts +36 -0
  1045. package/tests/benchmarks/io/fileOperations.bench.ts +132 -0
  1046. package/tests/benchmarks/io/gitOperations.bench.ts +99 -0
  1047. package/tests/benchmarks/utils/graphGenerator.ts +201 -0
  1048. package/tests/benchmarks/utils/reporter.ts +231 -0
  1049. package/tests/benchmarks/workflows/endToEnd.bench.ts +132 -0
  1050. package/tests/bootstrap.test.ts +319 -0
  1051. package/tests/budget-tracker.spec.ts +279 -0
  1052. package/tests/bulkOps.spec.ts +166 -0
  1053. package/tests/bulletproof-determinism.test.ts +223 -0
  1054. package/tests/canonicalJson.test.ts +130 -0
  1055. package/tests/checkRunConverter.spec.ts +357 -0
  1056. package/tests/cli/commands/gate/test.spec.ts +564 -0
  1057. package/tests/cli/emit-frames-flag.spec.ts +117 -0
  1058. package/tests/cli/exitHandler.spec.ts +314 -0
  1059. package/tests/cli/flags.spec.ts +223 -0
  1060. package/tests/cli/formatters.spec.ts +513 -0
  1061. package/tests/cli/output.spec.ts +221 -0
  1062. package/tests/cli-autopilot.spec.ts +170 -0
  1063. package/tests/cli-budget-guards.spec.ts +210 -0
  1064. package/tests/cli-color-control.spec.ts +334 -0
  1065. package/tests/cli-deliverables-generator.spec.ts +185 -0
  1066. package/tests/cli-determinism.spec.ts +496 -0
  1067. package/tests/cli-init-enterprise.spec.ts +294 -0
  1068. package/tests/cli-init-json.spec.ts +154 -0
  1069. package/tests/cli-init-local.spec.ts +159 -0
  1070. package/tests/cli-json-envelope.spec.ts +140 -0
  1071. package/tests/cli-json.spec.ts +408 -0
  1072. package/tests/cli-orchestrate-plan-batch.spec.ts +329 -0
  1073. package/tests/cli-orchestrate.spec.ts +231 -0
  1074. package/tests/cli-plan-generation.spec.ts +367 -0
  1075. package/tests/cli-plan-review.spec.ts +300 -0
  1076. package/tests/cli-progress.spec.ts +193 -0
  1077. package/tests/cli-ux-enhancements.spec.ts +213 -0
  1078. package/tests/cliJsonPurity.spec.ts +437 -0
  1079. package/tests/cliSuggestDeps.spec.ts +360 -0
  1080. package/tests/cluster-gates-rollback.spec.ts +353 -0
  1081. package/tests/command-validator-integration.spec.ts +305 -0
  1082. package/tests/command-validator.spec.ts +380 -0
  1083. package/tests/commands/autopilot.spec.ts +124 -0
  1084. package/tests/commands/config-validate.spec.ts +301 -0
  1085. package/tests/commands/config.spec.ts +311 -0
  1086. package/tests/commands/create-project.spec.ts +90 -0
  1087. package/tests/commands/doctor.spec.ts +57 -0
  1088. package/tests/commands/execute.spec.ts +293 -0
  1089. package/tests/commands/gateAttest.spec.ts +172 -0
  1090. package/tests/commands/gateImport.spec.ts +176 -0
  1091. package/tests/commands/gateReport.spec.ts +130 -0
  1092. package/tests/commands/guards.spec.ts +114 -0
  1093. package/tests/commands/idea.spec.ts +177 -0
  1094. package/tests/commands/merge.spec.ts +166 -0
  1095. package/tests/commands/plan.spec.ts +123 -0
  1096. package/tests/commands/query.spec.ts +294 -0
  1097. package/tests/commands/report.spec.ts +54 -0
  1098. package/tests/commands/retry.spec.ts +300 -0
  1099. package/tests/commands/schema.spec.ts +136 -0
  1100. package/tests/commands/validation.spec.ts +229 -0
  1101. package/tests/completion.spec.ts +133 -0
  1102. package/tests/config-inspect.spec.ts +202 -0
  1103. package/tests/conflictClustering-e2e.spec.ts +278 -0
  1104. package/tests/conflictClustering.spec.ts +550 -0
  1105. package/tests/conflictGraph.spec.ts +126 -0
  1106. package/tests/conflictPredictor.spec.ts +238 -0
  1107. package/tests/deliverables-generator.spec.ts +329 -0
  1108. package/tests/deliverables.spec.ts +381 -0
  1109. package/tests/dependencyParser-github.spec.ts +244 -0
  1110. package/tests/dependencyParser.spec.ts +386 -0
  1111. package/tests/dependencyScoring.spec.ts +668 -0
  1112. package/tests/deterministic-applicable.test.ts +156 -0
  1113. package/tests/deterministic-build.test.ts +172 -0
  1114. package/tests/deterministic-simple.test.ts +32 -0
  1115. package/tests/discover-suggest-integration.spec.ts +340 -0
  1116. package/tests/dogfood-merge-weave-script.spec.ts +150 -0
  1117. package/tests/e2e/planner.spec.ts +596 -0
  1118. package/tests/e2e-comprehensive.test.ts +500 -0
  1119. package/tests/e2e-determinism.test.ts +293 -0
  1120. package/tests/e2e-synthetic-6pr-weave.spec.ts +329 -0
  1121. package/tests/enterprise-init.spec.ts +350 -0
  1122. package/tests/envUtils.spec.ts +267 -0
  1123. package/tests/error-handling.test.ts +104 -0
  1124. package/tests/error-recovery.spec.ts +451 -0
  1125. package/tests/execution-plan-v1.test.ts +257 -0
  1126. package/tests/executionState-loadGateResults.spec.ts +267 -0
  1127. package/tests/executionState.test.ts +169 -0
  1128. package/tests/executors/README.md +100 -0
  1129. package/tests/executors/frameContract-integration.spec.ts +324 -0
  1130. package/tests/executors/frameContract.spec.ts +531 -0
  1131. package/tests/executors/guardrailEnforcement.spec.ts +424 -0
  1132. package/tests/executors/lifecycle.spec.ts +313 -0
  1133. package/tests/executors/toolBudget.spec.ts +473 -0
  1134. package/tests/feature-spec-v0.test.ts +145 -0
  1135. package/tests/fileAnalysis.spec.ts +946 -0
  1136. package/tests/fingerprint.spec.ts +100 -0
  1137. package/tests/fixtures/README.md +380 -0
  1138. package/tests/fixtures/deliverables/batch-example-plan.json +62 -0
  1139. package/tests/fixtures/executors/README.md +57 -0
  1140. package/tests/fixtures/executors/index.ts +9 -0
  1141. package/tests/fixtures/executors/mock-executor.ts +204 -0
  1142. package/tests/fixtures/executors/registry.ts +51 -0
  1143. package/tests/fixtures/executors/types.ts +95 -0
  1144. package/tests/fixtures/fixtures.spec.ts +307 -0
  1145. package/tests/fixtures/gates/configs.ts +234 -0
  1146. package/tests/fixtures/gates/results.ts +234 -0
  1147. package/tests/fixtures/harvest-bundle-fixture.json +87 -0
  1148. package/tests/fixtures/index.ts +219 -0
  1149. package/tests/fixtures/invalid/plans.ts +178 -0
  1150. package/tests/fixtures/jest/all-passing.json +71 -0
  1151. package/tests/fixtures/jest/snapshot-failures.json +66 -0
  1152. package/tests/fixtures/jest/some-failing.json +100 -0
  1153. package/tests/fixtures/jest/with-location.json +84 -0
  1154. package/tests/fixtures/junit/cdata-messages.xml +29 -0
  1155. package/tests/fixtures/junit/multiple-suites.xml +30 -0
  1156. package/tests/fixtures/junit/single-suite.xml +17 -0
  1157. package/tests/fixtures/junit/with-errors.xml +19 -0
  1158. package/tests/fixtures/junit/with-skipped.xml +18 -0
  1159. package/tests/fixtures/npm-audit.json +32 -0
  1160. package/tests/fixtures/plan.bad-schema.json +5 -0
  1161. package/tests/fixtures/plan.bad-unknown-dep.json +10 -0
  1162. package/tests/fixtures/plan.ci-gates.json +36 -0
  1163. package/tests/fixtures/plan.complex-cycle.json +22 -0
  1164. package/tests/fixtures/plan.cycle.json +14 -0
  1165. package/tests/fixtures/plan.deep-chain.json +95 -0
  1166. package/tests/fixtures/plan.dogfood-execute.json +36 -0
  1167. package/tests/fixtures/plan.gates.json +30 -0
  1168. package/tests/fixtures/plan.integration-pyramid.json +56 -0
  1169. package/tests/fixtures/plan.orphans.json +22 -0
  1170. package/tests/fixtures/plan.parallel.json +30 -0
  1171. package/tests/fixtures/plan.tiny.json +18 -0
  1172. package/tests/fixtures/plan.wide-parallel.json +75 -0
  1173. package/tests/fixtures/plan.with-failures.json +26 -0
  1174. package/tests/fixtures/plan.with-vuln.json +25 -0
  1175. package/tests/fixtures/planner/cross-module.json +101 -0
  1176. package/tests/fixtures/planner/cycle-error.json +56 -0
  1177. package/tests/fixtures/planner/diamond-pattern.json +74 -0
  1178. package/tests/fixtures/planner/empty-repo.json +9 -0
  1179. package/tests/fixtures/planner/file-overlap-heavy.json +110 -0
  1180. package/tests/fixtures/planner/invalid-pr.json +25 -0
  1181. package/tests/fixtures/planner/merge-conflicts.json +42 -0
  1182. package/tests/fixtures/planner/mixed-deps.json +101 -0
  1183. package/tests/fixtures/planner/self-dependency.json +24 -0
  1184. package/tests/fixtures/planner/simple-stack.json +79 -0
  1185. package/tests/fixtures/planner/single-pr.json +25 -0
  1186. package/tests/fixtures/planner/stale-pr.json +40 -0
  1187. package/tests/fixtures/plans/complex.ts +201 -0
  1188. package/tests/fixtures/plans/diamond.ts +115 -0
  1189. package/tests/fixtures/plans/linear.ts +74 -0
  1190. package/tests/fixtures/plans/simple.ts +61 -0
  1191. package/tests/fixtures/prs/basic.ts +175 -0
  1192. package/tests/fixtures/prs/withDeps.ts +197 -0
  1193. package/tests/fixtures/scan-results-clean.sarif +15 -0
  1194. package/tests/fixtures/scan-results.sarif +74 -0
  1195. package/tests/fixtures/scenarios/mergeWorkflows.ts +300 -0
  1196. package/tests/fixtures/scenarios/syntheticWeave.ts +351 -0
  1197. package/tests/fixtures/snapshot/package.json +5 -0
  1198. package/tests/fixtures/snapshot/sample.ts +21 -0
  1199. package/tests/fixtures/utils/cleanup.ts +81 -0
  1200. package/tests/fixtures/utils/mockGitHub.ts +219 -0
  1201. package/tests/fixtures/utils/tempDir.ts +109 -0
  1202. package/tests/fixtures/verification/expected-verification.json +16 -0
  1203. package/tests/fixtures/verification/receipt.json +31 -0
  1204. package/tests/fixtures/verification/snapshot.json +44 -0
  1205. package/tests/fixtures/vitest/all-passing.json +67 -0
  1206. package/tests/fixtures/vitest/complex-nested-suites.json +98 -0
  1207. package/tests/fixtures/vitest/some-failing.json +98 -0
  1208. package/tests/fixtures/vitest/with-coverage.json +97 -0
  1209. package/tests/fixtures-usage-examples.spec.ts +304 -0
  1210. package/tests/flakeReport.spec.ts +267 -0
  1211. package/tests/frames/ci-gate-integration.spec.ts +331 -0
  1212. package/tests/frames/controller.spec.ts +165 -0
  1213. package/tests/frames/emitter.spec.ts +371 -0
  1214. package/tests/frames/idempotency.spec.ts +177 -0
  1215. package/tests/frames/storage.spec.ts +346 -0
  1216. package/tests/frames/types.spec.ts +249 -0
  1217. package/tests/frames/v2-schema-integration.spec.ts +435 -0
  1218. package/tests/gate-working-directory.spec.ts +204 -0
  1219. package/tests/gateMapping.spec.ts +161 -0
  1220. package/tests/gateReportIntegration.spec.ts +175 -0
  1221. package/tests/gateReportValidation.spec.ts +452 -0
  1222. package/tests/gates/test/adapters/jest-json.spec.ts +372 -0
  1223. package/tests/gates/test/adapters/junit-xml.spec.ts +421 -0
  1224. package/tests/gates/test/adapters/registry.spec.ts +376 -0
  1225. package/tests/gates/test/adapters/vitest-json.spec.ts +455 -0
  1226. package/tests/gates/test/enrichment/failureId.spec.ts +131 -0
  1227. package/tests/gates/test/enrichment/nextActions.spec.ts +365 -0
  1228. package/tests/gates/test/enrichment/rerunTemplates.spec.ts +187 -0
  1229. package/tests/gates/test/enrichment/signature.spec.ts +163 -0
  1230. package/tests/gates/test/enrichment/stackParser.spec.ts +203 -0
  1231. package/tests/gates/turncost-integration.spec.ts +221 -0
  1232. package/tests/gates/validation-integration.spec.ts +147 -0
  1233. package/tests/gates/validator.spec.ts +200 -0
  1234. package/tests/gates.test.ts +255 -0
  1235. package/tests/gatesWithPolicy.hostilityTimeoutAdjustment.spec.ts +156 -0
  1236. package/tests/git-operations-receipts.spec.ts +121 -0
  1237. package/tests/git-operations.test.ts +152 -0
  1238. package/tests/git-runtime.spec.ts +175 -0
  1239. package/tests/github-api.labels.spec.ts +21 -0
  1240. package/tests/github-api.test.ts +85 -0
  1241. package/tests/github-context-diet.spec.ts +441 -0
  1242. package/tests/github-diff-hunks.spec.ts +387 -0
  1243. package/tests/github-integration.spec.ts +774 -0
  1244. package/tests/github-minimal-context.spec.ts +338 -0
  1245. package/tests/github-symbol-map.spec.ts +414 -0
  1246. package/tests/githubClient.spec.ts +123 -0
  1247. package/tests/governance/mcpStatus.spec.ts +276 -0
  1248. package/tests/governance/timeoutAdjustment.spec.ts +149 -0
  1249. package/tests/governance/turnCostSummary.spec.ts +188 -0
  1250. package/tests/governance-retention.spec.ts +151 -0
  1251. package/tests/governance-wrapper-delegation.spec.ts +148 -0
  1252. package/tests/guardrails.spec.ts +860 -0
  1253. package/tests/hash.test.ts +83 -0
  1254. package/tests/helpers/cli.ts +23 -0
  1255. package/tests/helpers/getStd.ts +1 -0
  1256. package/tests/helpers/makeGate.ts +19 -0
  1257. package/tests/helpers/plannerTestHelpers.ts +314 -0
  1258. package/tests/hooks/events.spec.ts +518 -0
  1259. package/tests/hostility/checks.spec.ts +295 -0
  1260. package/tests/hostility/integration.spec.ts +123 -0
  1261. package/tests/hostility/score.spec.ts +175 -0
  1262. package/tests/init.spec.ts +270 -0
  1263. package/tests/integration/hipaa-encryption.spec.ts +148 -0
  1264. package/tests/integration/lex-smoke-test.spec.ts +328 -0
  1265. package/tests/integration-e2e.test.ts +244 -0
  1266. package/tests/integration-matrix.test.ts +409 -0
  1267. package/tests/interPRConflicts.spec.ts +254 -0
  1268. package/tests/interactive-plan-history.spec.ts +255 -0
  1269. package/tests/interactive-plan-review.spec.ts +287 -0
  1270. package/tests/issue-analyzer.spec.ts +593 -0
  1271. package/tests/lexsona-integration.spec.ts +311 -0
  1272. package/tests/localOverlay.spec.ts +203 -0
  1273. package/tests/lockHash.spec.ts +167 -0
  1274. package/tests/mcp-auth-errors.spec.ts +190 -0
  1275. package/tests/mcp-contracts.spec.ts +290 -0
  1276. package/tests/mcp-gates-external-plan.spec.ts +146 -0
  1277. package/tests/mcp-granular-tools.spec.ts +208 -0
  1278. package/tests/mcp-runstore-integration.spec.ts +334 -0
  1279. package/tests/mcp-scope-integration.spec.ts +318 -0
  1280. package/tests/mcp-task-handoff.spec.ts +320 -0
  1281. package/tests/mcp-workflow-guide.spec.ts +53 -0
  1282. package/tests/mcp.test.ts +151 -0
  1283. package/tests/merge-conflict-detection.spec.ts +260 -0
  1284. package/tests/mergeEligibility.test.ts +201 -0
  1285. package/tests/mergeLockHash.spec.ts +158 -0
  1286. package/tests/mergeOrder-with-fixtures.spec.ts +215 -0
  1287. package/tests/mergeOrder.test.ts +108 -0
  1288. package/tests/mergeTreeSimulator.spec.ts +145 -0
  1289. package/tests/metrics/export.spec.ts +446 -0
  1290. package/tests/metrics/turncost.spec.ts +309 -0
  1291. package/tests/metrics-template.spec.ts +137 -0
  1292. package/tests/migrateProfile.spec.ts +254 -0
  1293. package/tests/mis.spec.ts +202 -0
  1294. package/tests/monitoring-audit.spec.ts +181 -0
  1295. package/tests/monitoring-cache.spec.ts +331 -0
  1296. package/tests/monitoring-error-recovery.spec.ts +236 -0
  1297. package/tests/monitoring-errors.spec.ts +193 -0
  1298. package/tests/monitoring-fileLogger.spec.ts +319 -0
  1299. package/tests/monitoring-health.spec.ts +152 -0
  1300. package/tests/monitoring-lock.spec.ts +308 -0
  1301. package/tests/monitoring-logger.spec.ts +157 -0
  1302. package/tests/monitoring-metrics.spec.ts +158 -0
  1303. package/tests/monitoring-profiler.spec.ts +197 -0
  1304. package/tests/orchestration-determinism.spec.ts +204 -0
  1305. package/tests/parseRemote.spec.ts +25 -0
  1306. package/tests/pathResolver.spec.ts +122 -0
  1307. package/tests/paths.spec.ts +68 -0
  1308. package/tests/performance.spec.ts +322 -0
  1309. package/tests/pipeline-determinism.spec.ts +597 -0
  1310. package/tests/plan-tier-integration.spec.ts +184 -0
  1311. package/tests/precedence-resolution.spec.ts +682 -0
  1312. package/tests/preflightConflicts.spec.ts +205 -0
  1313. package/tests/procedures/keystone-policy.spec.ts +296 -0
  1314. package/tests/procedures/loader.spec.ts +585 -0
  1315. package/tests/procedures/pr-review.spec.ts +321 -0
  1316. package/tests/profileResolver.spec.ts +375 -0
  1317. package/tests/progress-indicators.spec.ts +139 -0
  1318. package/tests/promptsResolver.spec.ts +443 -0
  1319. package/tests/public-api.spec.ts +272 -0
  1320. package/tests/query.spec.ts +170 -0
  1321. package/tests/receipts.spec.ts +463 -0
  1322. package/tests/release-prepare.spec.ts +268 -0
  1323. package/tests/report.test.ts +335 -0
  1324. package/tests/resolutionGuidance.spec.ts +160 -0
  1325. package/tests/rotate-secrets-example.spec.ts +198 -0
  1326. package/tests/rulesResolver.spec.ts +232 -0
  1327. package/tests/runGit.spec.ts +229 -0
  1328. package/tests/runner-lifecycle-integration.spec.ts +283 -0
  1329. package/tests/runs/artifacts.spec.ts +367 -0
  1330. package/tests/runs/decisions.spec.ts +495 -0
  1331. package/tests/runs/enforcement.spec.ts +555 -0
  1332. package/tests/runs/failures.spec.ts +554 -0
  1333. package/tests/runs/manager-runstore-integration.spec.ts +455 -0
  1334. package/tests/runs/manager.spec.ts +678 -0
  1335. package/tests/runs-manager.spec.ts +485 -0
  1336. package/tests/safety-acceptance.spec.ts +278 -0
  1337. package/tests/safety-enhanced.spec.ts +329 -0
  1338. package/tests/safety-framework.spec.ts +427 -0
  1339. package/tests/safety-guards-integration.spec.ts +213 -0
  1340. package/tests/safety-integration.spec.ts +278 -0
  1341. package/tests/sarif-parser.spec.ts +148 -0
  1342. package/tests/schema.test.ts +88 -0
  1343. package/tests/schemas/behavior-rule.spec.ts +366 -0
  1344. package/tests/schemas/executorManifest.spec.ts +441 -0
  1345. package/tests/schemas/persona-integration.spec.ts +62 -0
  1346. package/tests/schemas/persona.spec.ts +172 -0
  1347. package/tests/schemas/project.spec.ts +247 -0
  1348. package/tests/schemas/run-store.spec.ts +553 -0
  1349. package/tests/schemas/runCentric.spec.ts +463 -0
  1350. package/tests/schemas/vacuumReadyPrompt.spec.ts +515 -0
  1351. package/tests/scope-github-auto-detection.spec.ts +200 -0
  1352. package/tests/scopeValidator.spec.ts +497 -0
  1353. package/tests/security-authentication.spec.ts +42 -0
  1354. package/tests/security-authorization.spec.ts +350 -0
  1355. package/tests/security-cli.spec.ts +264 -0
  1356. package/tests/security-compliance.spec.ts +334 -0
  1357. package/tests/security-policy.spec.ts +295 -0
  1358. package/tests/security-scanning.spec.ts +349 -0
  1359. package/tests/security-secrets.spec.ts +401 -0
  1360. package/tests/store/create-run-store.spec.ts +185 -0
  1361. package/tests/store/inmemory/run-store.spec.ts +533 -0
  1362. package/tests/store/sqlite/run-store.spec.ts +849 -0
  1363. package/tests/telemetry/frames.spec.ts +120 -0
  1364. package/tests/tiers.spec.ts +466 -0
  1365. package/tests/token-usage.spec.ts +309 -0
  1366. package/tests/toolchain-manifest.spec.ts +145 -0
  1367. package/tests/unified-budget.spec.ts +713 -0
  1368. package/tests/unit/cache/issue-cache.spec.ts +131 -0
  1369. package/tests/unit/fanout/analyzer-integration.spec.ts +398 -0
  1370. package/tests/unit/fanout/analyzer.spec.ts +605 -0
  1371. package/tests/unit/fanout/github-adapter.spec.ts +203 -0
  1372. package/tests/unit/fanout/harvest.spec.ts +93 -0
  1373. package/tests/unit/fanout/monitor.spec.ts +297 -0
  1374. package/tests/unit/fanout/types.spec.ts +308 -0
  1375. package/tests/unit/github/batch-ops.spec.ts +179 -0
  1376. package/tests/unit/learning/counter-example.spec.ts +168 -0
  1377. package/tests/unit/learning/storage.spec.ts +154 -0
  1378. package/tests/unit/preview/constraints.spec.ts +429 -0
  1379. package/tests/unit/runs/attribution.spec.ts +204 -0
  1380. package/tests/unit/schemas/task-contract.spec.ts +483 -0
  1381. package/tests/unit/snapshot/builder.spec.ts +389 -0
  1382. package/tests/unit/verification/engine-verifier.spec.ts +279 -0
  1383. package/tests/unit/weave/authority-evaluator.spec.ts +404 -0
  1384. package/tests/unit/weave/authority-schema.spec.ts +199 -0
  1385. package/tests/unit/weave/auto-undraft-integration.spec.ts +349 -0
  1386. package/tests/unit/weave/copilot-completion.spec.ts +182 -0
  1387. package/tests/unit/weave/d1-executor.spec.ts +269 -0
  1388. package/tests/unit/weave/d2-executor.spec.ts +334 -0
  1389. package/tests/unit/weave/fanout-generator.spec.ts +365 -0
  1390. package/tests/unit/weave/fanout-matcher.spec.ts +320 -0
  1391. package/tests/unit/weave/fanout-schema.spec.ts +221 -0
  1392. package/tests/unit/weave/mergeWeaveSequential.spec.ts +268 -0
  1393. package/tests/unit/weave/metrics-calculator.spec.ts +212 -0
  1394. package/tests/unit/weave/metrics-logger.spec.ts +233 -0
  1395. package/tests/unit/weave/metrics-schema.spec.ts +383 -0
  1396. package/tests/unit/weave/multi-repo-plan.spec.ts +221 -0
  1397. package/tests/unit/weave/planner.spec.ts +227 -0
  1398. package/tests/unit/weave/post-merge-checks.spec.ts +342 -0
  1399. package/tests/unit/weave/recovery.spec.ts +306 -0
  1400. package/tests/unit/weave/testfix/applier.spec.ts +364 -0
  1401. package/tests/unit/weave/testfix/e2e.spec.ts +273 -0
  1402. package/tests/unit/weave/testfix/integration.spec.ts +128 -0
  1403. package/tests/unit/weave/testfix/matcher.spec.ts +321 -0
  1404. package/tests/unit/weave/testfix/schema.spec.ts +298 -0
  1405. package/tests/utils/fingerprint.spec.ts +251 -0
  1406. package/tests/utils/paths.spec.ts +284 -0
  1407. package/tests/utils/tokens.spec.ts +210 -0
  1408. package/tests/utils/validation.spec.ts +215 -0
  1409. package/tests/utils-validation.spec.ts +80 -0
  1410. package/tests/validate-manifests.spec.ts +231 -0
  1411. package/tests/validation.spec.ts +501 -0
  1412. package/tests/vuln-gate.spec.ts +341 -0
  1413. package/tests/weave/adr007-integration.spec.ts +309 -0
  1414. package/tests/weave/checkpoint/cli-integration.spec.ts +118 -0
  1415. package/tests/weave/checkpoint/storage.spec.ts +302 -0
  1416. package/tests/weave/checkpoint/utils.spec.ts +223 -0
  1417. package/tests/weave/frameHelper.spec.ts +423 -0
  1418. package/tests/weave/gateFailureHandler.spec.ts +249 -0
  1419. package/tests/weave/lockFile.spec.ts +387 -0
  1420. package/tests/weave/mergeHelpers.spec.ts +173 -0
  1421. package/tests/weave/receiptHelper.spec.ts +261 -0
  1422. package/tests/weave/stateMachine.spec.ts +436 -0
  1423. package/tests/weave-contract.test.ts +517 -0
  1424. package/tests/weave-e2e.spec.ts +279 -0
  1425. package/tests/weaveLock.spec.ts +136 -0
  1426. package/tests/workflow-state-machine.spec.ts +274 -0
  1427. package/tests/write-protection.spec.ts +213 -0
  1428. package/tsconfig.json +18 -0
  1429. package/tsup.config.ts +12 -0
  1430. package/vitest.benchmark.config.ts +17 -0
  1431. package/vitest.config.ts +28 -0
  1432. package/vitest.git.config.ts +12 -0
  1433. package/vitest.slow-cli.config.ts +28 -0
@@ -0,0 +1,952 @@
1
+ # Coordination Cost Compression in Human–AI Collaboration:
2
+
3
+ # A Governance-First Architecture
4
+
5
+ **Authors:**
6
+ Joseph Gustavson¹ · ORCID: [0009-0001-0669-0749](https://orcid.org/0009-0001-0669-0749)
7
+ with AI Co-Authors: Claude Opus 4.5 (Anthropic) as "Opie", GPT-5.1 (OpenAI) as "Lex"
8
+
9
+ ¹ Independent Researcher
10
+
11
+ ---
12
+
13
+ ## Abstract
14
+
15
+ Large Language Model (LLM)-based agents are increasingly deployed in software engineering workflows, yet productivity gains remain inconsistent. Current approaches emphasize model capability—larger parameters, longer context windows, more sophisticated reasoning—as the primary lever for improvement. We propose an alternative thesis: **coordination cost compression**, not capability amplification, is the primary determinant of effective human–AI collaboration.
16
+
17
+ We introduce a governance-first architecture comprising five core constructs: (1) **Turn Cost** as a composite metric for interaction overhead, (2) **environmental hostility** as a framework for understanding agent failure modes, (3) **governance primitives** encoded as machine-readable rule files, (4) **cross-model continuity** through externalized state, and (5) **capability tiers** for task-appropriate model allocation.
18
+
19
+ We present preliminary empirical validation through a case study ("Robert") demonstrating that minimal governance infrastructure (~1.2KB of contracts) can reduce Turn Cost by 62% and renegotiation rates from 34% to 8% across multiple LLM providers. We situate our work within the broader literature on multi-agent systems, human–AI teaming, and coordination theory, and explicitly acknowledge the limitations of single-case validation, potential observer effects, and the need for controlled studies.
20
+
21
+ Our contribution is theoretical and architectural: we offer a falsifiable framework for understanding human–AI collaboration that shifts focus from model capability to environmental design. We do not claim to have solved human–AI collaboration; we claim to have identified a productive axis for investigation.
22
+
23
+ **Keywords:** Human–AI collaboration, multi-agent systems, coordination cost, governance, software engineering, LLM agents
24
+
25
+ ---
26
+
27
+ ## 1. Introduction
28
+
29
+ ### 1.1 The Capability Trap
30
+
31
+ The dominant paradigm in LLM-based agent design assumes a direct relationship between model capability and task performance:
32
+
33
+ $$\text{Performance} \propto f(\text{ModelCapability})$$
34
+
35
+ This assumption drives substantial investment in larger models, longer context windows, and more sophisticated reasoning architectures [1, 2]. Yet empirical observations suggest diminishing returns: the productivity jump from GPT-3.5 to GPT-4 was substantial; subsequent improvements, while meaningful, have not produced equivalent step-changes in practitioner productivity [3, 4].
36
+
37
+ More troubling, practitioners report that "stronger" models often require _more_ careful prompting, _more_ context management, and _more_ human intervention to achieve consistent results. This paradox suggests that the limiting factor may not be model capability per se.
38
+
39
+ ### 1.2 The Coordination Cost Hypothesis
40
+
41
+ We propose an alternative framing:
42
+
43
+ > **Thesis:** In human–AI collaborative systems, productivity is primarily constrained by _coordination cost_—the overhead of establishing shared context, disambiguating intent, recovering from misunderstandings, and verifying outputs—rather than by raw model capability.
44
+
45
+ Formally, we define effective productivity as:
46
+
47
+ $$\text{EffectiveProductivity} = \frac{\text{ValueDelivered}}{\text{TokenCost} + \text{CoordinationCost}}$$
48
+
49
+ Current optimization efforts focus almost exclusively on the denominator's first term (token efficiency through better models). We argue the second term—coordination cost—is often larger and more tractable.
50
+
51
+ ### 1.3 Contribution and Scope
52
+
53
+ This paper makes the following contributions:
54
+
55
+ 1. **Theoretical framework:** We introduce _coordination cost compression_ as an organizing principle for human–AI system design, distinct from capability amplification.
56
+
57
+ 2. **Formal constructs:** We define _Turn Cost_, _environmental hostility_, _governance primitives_, and _capability tiers_ as measurable quantities with operational definitions.
58
+
59
+ 3. **Architectural proposal:** We describe a governance-first architecture that aims to reduce coordination cost through explicit contracts, externalized state, and tiered task allocation.
60
+
61
+ 4. **Preliminary validation:** We present a case study demonstrating feasibility and quantifying effects under controlled conditions.
62
+
63
+ **Explicit scope boundaries:** We do not claim to have created autonomous agents, solved general AI alignment, or replaced human engineers. We do not predict model evolution or propose AGI-relevant techniques. Our scope is narrow: improving the efficiency of human–AI collaboration in software engineering tasks.
64
+
65
+ ### 1.4 Framework Overview
66
+
67
+ Figure 1 illustrates the relationships between our core constructs:
68
+
69
+ ```
70
+ ┌─────────────────────────────────────────────────────────────────────────┐
71
+ │ GOVERNANCE LAYER │
72
+ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
73
+ │ │ Contracts │ │ Receipts │ │ Capability │ │
74
+ │ │ (invariants, │ │ (decisions, │ │ Tiers │ │
75
+ │ │ boundaries) │ │ rationale) │ │ (Sr/Mid/Jr) │ │
76
+ │ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │
77
+ └───────────┼─────────────────────┼─────────────────────┼─────────────────┘
78
+ │ │ │
79
+ ▼ ▼ ▼
80
+ ┌─────────────────────────────────────────────────────────────────────────┐
81
+ │ MECHANISM LAYER │
82
+ │ │
83
+ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
84
+ │ │ Reduced │ │ Cross-Model │ │ Structured │ │
85
+ │ │ Renegotiation │ │ Continuity │ │ Escalation │ │
86
+ │ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
87
+ └────────────┼──────────────────────┼──────────────────────┼──────────────┘
88
+ │ │ │
89
+ └──────────────────────┼──────────────────────┘
90
+
91
+ ┌─────────────────────────────────────────────────────────────────────────┐
92
+ │ EFFECT LAYER │
93
+ │ │
94
+ │ ┌─────────────────────────────────────────────────────────────────┐ │
95
+ │ │ TURN COST COMPRESSION │ │
96
+ │ │ │ │
97
+ │ │ TurnCost = λL + γC + ρR + τT + αA │ │
98
+ │ │ ↓ ↓ ↓ ↓ ↓ │ │
99
+ │ │ ─ ─ ─ ─ ─ │ │
100
+ │ │ (each component reduced by governance mechanisms) │ │
101
+ │ └─────────────────────────────────────────────────────────────────┘ │
102
+ └─────────────────────────────────────────────────────────────────────────┘
103
+
104
+
105
+ ┌─────────────────────────────────────────────────────────────────────────┐
106
+ │ HYPOTHESIS │
107
+ │ │
108
+ │ "Coordination cost compression, not capability amplification, │
109
+ │ is the primary determinant of effective human–AI collaboration." │
110
+ │ │
111
+ │ TESTABLE PREDICTION: Governance quality predicts productivity │
112
+ │ better than model capability (controlling for task complexity). │
113
+ └─────────────────────────────────────────────────────────────────────────┘
114
+
115
+ Legend:
116
+ ───────
117
+ Contracts → Reduced Renegotiation: Explicit invariants mean fewer
118
+ clarification turns
119
+ Receipts → Cross-Model Continuity: Externalized state survives
120
+ session/model boundaries
121
+ Tiers → Structured Escalation: Tasks matched to capability,
122
+ reducing wasted cycles
123
+ ```
124
+
125
+ _Figure 1: Unifying framework showing how governance constructs (top) produce mechanisms (middle) that compress Turn Cost components (effect), supporting the central hypothesis (bottom)._
126
+
127
+ ---
128
+
129
+ ## 2. Related Work
130
+
131
+ ### 2.1 Multi-Agent Systems and Coordination
132
+
133
+ The study of multi-agent coordination has deep roots in distributed systems and game theory [5, 6]. Classic work on multi-agent systems (MAS) established fundamental challenges: achieving coherent behavior without central control, managing shared resources, and handling partial observability [7].
134
+
135
+ Recent surveys on LLM-based multi-agent systems identify coordination mechanisms as a critical open problem. Tran et al. [8] characterize collaboration mechanisms along dimensions of actors, types (cooperation/competition/coopetition), structures (peer-to-peer/centralized/distributed), and coordination protocols. Our work contributes to the "coordination protocols" dimension by proposing explicit governance artifacts as coordination mechanisms.
136
+
137
+ Wang et al. [9] survey multi-agent collaboration and note that most current systems rely on implicit coordination through shared context or role-based prompting. We argue this is insufficient for production software engineering, where coordination failures have concrete costs (bugs, security vulnerabilities, integration failures).
138
+
139
+ ### 2.2 Human–AI Teaming
140
+
141
+ Research on human–AI collaboration has identified persistent challenges in hybrid teams. Studies of human–AI teaming in field settings show that productivity gains are inconsistent and context-dependent [10]. Factors affecting success include task structure, feedback mechanisms, and the ability to establish shared mental models [11].
142
+
143
+ The concept of "environmental hostility" we introduce relates to prior work on automation brittleness and human factors in automated systems [12]. When environments provide unclear constraints, ambiguous feedback, or punitive error dynamics, both human and AI performance degrades.
144
+
145
+ Importantly, several empirical studies have found that human–AI teams sometimes underperform humans alone [13], particularly when coordination costs exceed productivity gains. This finding supports our thesis that coordination cost, not capability, is often the binding constraint.
146
+
147
+ ### 2.3 Coordination Theory
148
+
149
+ Malone and Crowston's coordination theory [14] provides a foundational framework for understanding coordination as "managing dependencies between activities." They identify coordination mechanisms including shared representations, communication protocols, and group decision procedures.
150
+
151
+ Our governance primitives can be understood as coordination mechanisms in this sense: they manage dependencies by making constraints explicit, reducing disambiguation requirements, and providing recovery protocols. The "rule file" artifact we propose is a shared representation that reduces coordination overhead by externalizing expectations.
152
+
153
+ ### 2.4 LLM Agent Architectures
154
+
155
+ Recent work on LLM agent architectures has explored various approaches to improving reliability: chain-of-thought prompting [15], tool use [16], and multi-agent debate [17]. Most of this work focuses on the agent's internal reasoning process.
156
+
157
+ We propose that external governance—constraints and expectations defined _outside_ the model—may be more robust than internal reasoning improvements. This is consistent with findings that prompt engineering has diminishing returns and that behavioral steering through system instructions is fragile [18].
158
+
159
+ ### 2.5 Positioning Our Contribution
160
+
161
+ Our work differs from prior multi-agent research in several ways:
162
+
163
+ | Dimension | Typical MAS Approach | Our Approach |
164
+ | ---------------------- | ---------------------------------------------- | --------------------------------------------- |
165
+ | Coordination mechanism | Implicit (shared context) or negotiation-based | Explicit governance artifacts |
166
+ | Optimization target | Task completion rate, accuracy | Turn Cost (interaction overhead) |
167
+ | State management | Agent-internal memory | Externalized receipts and contracts |
168
+ | Model assumptions | Fixed model per agent | Model-agnostic, supports hot-swapping |
169
+ | Human role | Supervisor or absent | Collaborative partner with explicit interface |
170
+
171
+ We are not the first to propose explicit coordination mechanisms for AI systems, but we believe we are among the first to: (a) formalize _Turn Cost_ as a composite metric, (b) treat governance as a first-class, versionable artifact, and (c) empirically measure the effects on human–AI interaction patterns.
172
+
173
+ ---
174
+
175
+ ## 3. Theoretical Framework
176
+
177
+ ### 3.1 Turn Cost: A Composite Metric
178
+
179
+ We define a **Turn** as a complete cycle of human–agent interaction:
180
+
181
+ 1. Human provides input (context, instruction, feedback)
182
+ 2. Agent processes and acts
183
+ 3. Human reviews and responds
184
+
185
+ This differs from token-centric metrics (cost per 1K tokens) or API-centric metrics (latency per call). A Turn is a semantic unit of work with measurable properties.
186
+
187
+ #### 3.1.1 Why Turns, Not Tokens?
188
+
189
+ Existing LLM benchmarks optimize for task completion accuracy or per-token efficiency. This overlooks a critical observation from practice: **interaction overhead often exceeds token cost by an order of magnitude.**
190
+
191
+ Consider a typical software engineering task:
192
+
193
+ - Token cost: 5,000 tokens at $0.03/1K = $0.15
194
+ - Human attention cost: 10 minutes at $50/hr = $8.33
195
+
196
+ The ratio is 55:1. Even a 50% reduction in token cost saves $0.075; a 50% reduction in interaction turns saves $4.17. This asymmetry motivates our focus on Turns rather than Tokens.
197
+
198
+ Furthermore, Turns are the natural unit of _coordination failure_. Each Turn represents an opportunity for misalignment, clarification, or recovery. Token costs are linear; Turn costs compound through cascading misunderstandings.
199
+
200
+ #### 3.1.2 Formal Definition
201
+
202
+ **Definition 3.1 (Turn Cost):** The total overhead incurred in a single Turn, comprising:
203
+
204
+ $$\text{TurnCost} = \lambda L + \gamma C + \rho R + \tau T + \alpha A$$
205
+
206
+ Where:
207
+
208
+ - $L$ = **Latency**: Raw time waiting for model response
209
+ - $C$ = **Context Reset**: Tokens required to re-establish context after session boundary or model switch
210
+ - $R$ = **Prompt Renegotiation**: Additional turns required to clarify misunderstood instructions
211
+ - $T$ = **Token Bloat**: Tokens consumed beyond minimum necessary due to poor coordination
212
+ - $A$ = **Attention Switch**: Human cognitive cost of context-switching to manage the agent
213
+
214
+ The weights $\lambda, \gamma, \rho, \tau, \alpha$ reflect context-specific costs. We propose default weights based on observed practitioner behavior:
215
+
216
+ | Component | Symbol | Default Weight | Rationale |
217
+ | ---------------- | ------ | -------------- | ------------------------------------ |
218
+ | Latency | λ | 0.1 | Tolerable in async workflows |
219
+ | Context Reset | γ | 0.2 | Significant but bounded by artifacts |
220
+ | Renegotiation | ρ | 0.3 | High cost due to cascading effects |
221
+ | Token Bloat | τ | 0.1 | Low marginal cost per token |
222
+ | Attention Switch | α | 0.3 | Highest marginal cost (human time) |
223
+
224
+ These weights are calibration suggestions, not universal constants. Organizations should derive weights empirically from their cost structures.
225
+
226
+ #### 3.1.3 Theoretical Grounding
227
+
228
+ Turn Cost connects to established coordination theory [14]. Malone and Crowston's interdependence taxonomy identifies three coordination mechanisms:
229
+
230
+ - **Managing shared resources** → maps to Token Bloat (shared API context window)
231
+ - **Managing producer/consumer relationships** → maps to Renegotiation (intent alignment)
232
+ - **Managing simultaneity constraints** → maps to Attention Switch (human/agent synchronization)
233
+
234
+ Our formalization makes these abstract dependencies concrete and measurable.
235
+
236
+ **Claim 3.1:** In most software engineering contexts with skilled human operators, the effective cost ordering is:
237
+
238
+ $$\text{AttentionSwitch} > \text{Renegotiation} > \text{ContextReset} > \text{TokenBloat} > \text{Latency}$$
239
+
240
+ This ordering implies that optimizations reducing human intervention (fewer turns, less renegotiation) yield greater returns than optimizations reducing per-turn latency or token count.
241
+
242
+ ### 3.2 Environmental Hostility
243
+
244
+ We propose that agent performance degrades in proportion to _environmental hostility_, not (primarily) model capacity.
245
+
246
+ **Definition 3.2 (Environmental Hostility):** The degree to which an environment impedes effective agent operation through:
247
+
248
+ - Unclear or implicit constraints
249
+ - Opaque requirements (unstated expectations)
250
+ - Unbounded problem surfaces
251
+ - Missing receipts and traceability
252
+ - Punitive error dynamics (failures trigger cascading costs)
253
+ - Fragmented state (context spread across sessions/tools)
254
+ - Model switches without continuity protocols
255
+
256
+ **Claim 3.2:** A progressively de-hostilized environment enables consistent agent behavior across model capabilities. Formally:
257
+
258
+ $$\text{AgentReliability} = g(\text{EnvironmentQuality}, \text{ModelCapability})$$
259
+
260
+ Where $\frac{\partial g}{\partial \text{EnvironmentQuality}} > \frac{\partial g}{\partial \text{ModelCapability}}$ in typical software engineering contexts.
261
+
262
+ This claim is falsifiable: if model capability dominates, we would expect reliability to vary primarily with model choice, not environment design. Our case study provides preliminary evidence for the alternative.
263
+
264
+ ### 3.3 Governance Primitives
265
+
266
+ Governance primitives are explicit, machine-readable artifacts that reduce environmental hostility by making constraints, expectations, and protocols visible.
267
+
268
+ **Definition 3.3 (Governance Primitive):** A structured artifact that specifies:
269
+
270
+ 1. **Constraints**: What the agent must/must not do
271
+ 2. **Permissions**: What the agent is authorized to do
272
+ 3. **Uncertainty Protocol**: How to handle ambiguity
273
+ 4. **Receipt Protocol**: How to document decisions and actions
274
+ 5. **Escalation Triggers**: When to involve human judgment
275
+
276
+ We specify governance primitives as YAML/JSON files with a defined schema:
277
+
278
+ ```yaml
279
+ # Example: Minimal governance contract
280
+ schemaVersion: "1.0.0"
281
+ kind: AgentContract
282
+
283
+ constraints:
284
+ must:
285
+ - "Follow existing patterns in neighboring code"
286
+ - "Create reversible changes when uncertain"
287
+ must_not:
288
+ - "Force push to protected branches"
289
+ - "Bypass CI gates"
290
+
291
+ permissions:
292
+ can: ["create_file", "modify_file", "run_tests"]
293
+ cannot: ["merge_to_main", "modify_contracts"]
294
+
295
+ uncertainty:
296
+ allowed: true
297
+ expression: "explicit_marker"
298
+ protocol: "reversible_moves_with_receipts"
299
+
300
+ receipts:
301
+ required: true
302
+ format: "structured_yaml"
303
+ fields: ["action", "rationale", "confidence", "reversibility"]
304
+ ```
305
+
306
+ **Design constraints:**
307
+
308
+ - Maximum size: 4KB (ensures quick ingestion, discourages over-specification)
309
+ - Versioned: Changes tracked, diffs reviewable
310
+ - Testable: Compliance verifiable through automated gates
311
+ - Role-scoped: Different contracts for different agent capabilities
312
+
313
+ ### 3.4 Permission to Fail with Discipline
314
+
315
+ A key governance principle is **permission to fail with discipline**: agents may express uncertainty and make errors, provided they do so transparently, reversibly, and with structured documentation.
316
+
317
+ **Definition 3.4 (Disciplined Failure):** A failure mode where:
318
+
319
+ 1. Uncertainty is stated explicitly before action
320
+ 2. Actions taken are reversible (or flagged as non-reversible)
321
+ 3. Receipts document the decision chain
322
+ 4. Recovery path is proposed or escalation triggered
323
+
324
+ This contrasts with two failure modes common in LLM agents:
325
+
326
+ - **Confidence inflation**: Agent produces incorrect output confidently, human doesn't verify, error propagates
327
+ - **Paralysis**: Agent refuses to act without certainty, progress stalls
328
+
329
+ The discipline component is essential: permission to fail is not permission to be sloppy. The protocol requires structured uncertainty expression and bounded recovery costs.
330
+
331
+ ### 3.5 Cross-Model Continuity
332
+
333
+ **Claim 3.3:** Session state that enables collaboration is not internal model state (hidden vectors, attention patterns) but _externalized governance and receipts_.
334
+
335
+ If this claim holds, then model switches—GPT-4 to Claude, Claude to Haiku—should not require substantial re-onboarding, provided governance artifacts and receipts are preserved.
336
+
337
+ **Definition 3.5 (Cross-Model Continuity):** The property that agent behavior remains consistent across model switches when:
338
+
339
+ 1. Governance contracts are stable
340
+ 2. Receipts from prior work are accessible
341
+ 3. Shared vocabulary is documented
342
+ 4. Current task state is explicit
343
+
344
+ This has architectural implications: session state should be stored in version-controlled files, not in API-specific memory features or prompt caches.
345
+
346
+ ### 3.6 Capability Tiers
347
+
348
+ Not all tasks require the same agent capability. We propose a tiered classification:
349
+
350
+ | Tier | Role | Example Tasks | Characteristics |
351
+ | ---------- | --------------------------- | ------------------------------------------------ | ------------------------------------ |
352
+ | **Senior** | Design, critique, decide | Architecture decisions, API design, code review | Requires judgment, handles ambiguity |
353
+ | **Mid** | Implement, extend, refactor | Feature implementation, bug fixes, migrations | Clear scope, established patterns |
354
+ | **Junior** | Verify, instrument, lint | Test coverage, formatting, documentation updates | Deterministic, low-risk |
355
+
356
+ **Claim 3.4:** Matching task tier to model capability reduces overall Turn Cost by avoiding both over-allocation (expensive models on trivial tasks) and under-allocation (failures requiring escalation).
357
+
358
+ This is operationalizable: we can measure escalation rates, retry counts, and effective cost per task tier.
359
+
360
+ ---
361
+
362
+ ## 4. Architecture
363
+
364
+ ### 4.1 System Overview
365
+
366
+ The proposed architecture comprises four layers:
367
+
368
+ ```
369
+ ┌─────────────────────────────────────────────┐
370
+ │ Human Interface Layer │
371
+ │ (IDE integration, chat, review interface) │
372
+ ├─────────────────────────────────────────────┤
373
+ │ Governance Layer │
374
+ │ (Contracts, receipts, escalation logic) │
375
+ ├─────────────────────────────────────────────┤
376
+ │ Agent Layer │
377
+ │ (Model interface, tier routing, gates) │
378
+ ├─────────────────────────────────────────────┤
379
+ │ Artifact Layer │
380
+ │ (Files, VCS, structured storage) │
381
+ └─────────────────────────────────────────────┘
382
+ ```
383
+
384
+ ### 4.2 Governance Layer
385
+
386
+ The governance layer is the novel contribution. It:
387
+
388
+ 1. **Loads contracts** from version-controlled files (`.lex/rules/*.yaml`)
389
+ 2. **Validates compliance** before and after agent actions
390
+ 3. **Generates receipts** documenting decisions and outcomes
391
+ 4. **Manages escalation** when uncertainty exceeds thresholds
392
+ 5. **Tracks Turn Cost** components for optimization
393
+
394
+ Contracts are ingested at session start and validated incrementally. Violations trigger immediate feedback (not deferred to human review).
395
+
396
+ ### 4.3 Agent Layer
397
+
398
+ The agent layer is deliberately thin:
399
+
400
+ - Routes tasks to appropriate capability tier
401
+ - Provides model-agnostic interface (same governance works across providers)
402
+ - Enforces gate checks (lint, type, test) before accepting output
403
+ - Does not maintain internal session state beyond current turn
404
+
405
+ This thinness is intentional: complexity in the agent layer tends to be brittle, provider-specific, and hard to audit. We push complexity into the governance layer where it can be versioned and tested.
406
+
407
+ ### 4.4 Artifact Layer
408
+
409
+ All state lives in the artifact layer:
410
+
411
+ - **Contracts**: Governance specifications
412
+ - **Receipts**: Decision logs, action records
413
+ - **Frames**: Episodic memory (what happened, what was learned)
414
+ - **Code**: The actual work product
415
+
416
+ This design choice supports cross-model continuity: when switching models, only the agent layer changes. Governance and artifacts persist.
417
+
418
+ ---
419
+
420
+ ## 5. Case Study: The Robert Experiment
421
+
422
+ ### 5.1 Experimental Design
423
+
424
+ To provide preliminary validation of our framework, we conducted a controlled experiment in late 2025.
425
+
426
+ **Setup:**
427
+
428
+ - "Robert" was a minimal agent with:
429
+ - On-disk memory (file-based storage)
430
+ - A single contracts file (~1.2KB, reproduced in Appendix A)
431
+ - Standard model API access (no custom tooling)
432
+
433
+ - Robert explicitly lacked:
434
+ - Sophisticated orchestration
435
+ - Custom memory systems
436
+ - Provider-specific features
437
+ - Complex tool chains
438
+
439
+ **Models used:**
440
+
441
+ - GPT-5.1 as "Lex" (primary implementation)
442
+ - Claude Sonnet 4.5 as "Claude" (cross-model validation)
443
+ - Claude Haiku 4.5 as "Ku" (low-tier verification)
444
+
445
+ _Note: Model names reflect those available at time of experiment (late 2025)._
446
+
447
+ **Tasks:**
448
+
449
+ 1. Implement OAuth2 PKCE flow (feature implementation)
450
+ 2. Design a reusable form validation component (API design)
451
+ 3. Continue interrupted work from previous session (continuity test)
452
+
453
+ ### 5.2 Measurements
454
+
455
+ We measured Turn Cost components and compared to a baseline (same tasks, same models, no governance contracts). _Tokens per feature_ measures total API tokens consumed to complete a task, including all turns.
456
+
457
+ | Metric | Robert (with contracts) | Baseline (no contracts) | Δ |
458
+ | -------------------- | ----------------------- | ----------------------- | ---- |
459
+ | Turns per PR | 2.3 | 6.1 | -62% |
460
+ | Renegotiation rate | 8% | 34% | -76% |
461
+ | Context reset tokens | 180 | 650 | -72% |
462
+ | Human interventions | 2 | 11 | -82% |
463
+ | Tokens per feature | 12,400 | 28,600 | -57% |
464
+
465
+ ### 5.3 Observations
466
+
467
+ **Cross-model continuity:** When switching from GPT-5.1 (Lex) to Claude Sonnet 4.5 (Claude) mid-task:
468
+
469
+ - Claude read receipts left by GPT-5
470
+ - No re-briefing was required
471
+ - Work quality remained consistent
472
+ - Context restored in ~200 tokens (vs. ~650 in baseline)
473
+
474
+ **Uncertainty handling:** Robert expressed uncertainty multiple times:
475
+
476
+ - "Not sure if 80% TTL is optimal for token refresh"
477
+ - "This regex may not handle all international formats"
478
+
479
+ Each uncertainty was documented in receipts, accompanied by reversible implementation, and flagged for review. No uncertainty caused project delays or cascading failures.
480
+
481
+ **Governance sufficiency:** The 1.2KB contracts file was sufficient for:
482
+
483
+ - Keeping agent aligned with project expectations
484
+ - Enabling productive work without constant supervision
485
+ - Maintaining quality standards across sessions and models
486
+
487
+ ### 5.4 Limitations and Threats to Validity
488
+
489
+ We explicitly acknowledge significant limitations:
490
+
491
+ **Internal validity:**
492
+
493
+ - N=1 (single case study)
494
+ - Potential Hawthorne effect (experimenter was also the human collaborator)
495
+ - No randomization of task order or model assignment
496
+ - Baseline was constructed, not a true A/B test
497
+
498
+ **External validity:**
499
+
500
+ - Single domain (TypeScript/Node.js software engineering)
501
+ - Highly skilled human operator (may not generalize to novices)
502
+ - Codebase was moderately well-structured (may not generalize to legacy systems)
503
+ - Tasks were chosen to be representative, but selection bias is possible
504
+
505
+ **Construct validity:**
506
+
507
+ - Turn Cost components measured via logs, not independent observation
508
+ - "Human interventions" operationalized as git commits with human-authored changes, may miss other forms
509
+
510
+ **What we can and cannot claim:**
511
+
512
+ - ✓ Feasibility: The architecture is implementable
513
+ - ✓ Measurable effects: Turn Cost metrics changed in the predicted direction
514
+ - ✗ Generalizability: Unknown without broader replication
515
+ - ✗ Causality: Confounds not controlled
516
+
517
+ We present this as hypothesis-generating, not hypothesis-confirming evidence.
518
+
519
+ ---
520
+
521
+ ## 6. Evaluation Framework
522
+
523
+ ### 6.1 Operationalizing Turn Cost
524
+
525
+ For practical deployment, we propose measuring:
526
+
527
+ **Primary metrics:**
528
+
529
+ - `turn_count`: Number of human–agent interaction cycles per task
530
+ - `renegotiation_rate`: Proportion of turns that are clarification-only
531
+ - `context_reset_tokens`: Tokens required after session/model boundaries
532
+ - `escalation_rate`: Proportion of tasks requiring tier upgrade
533
+
534
+ **Derived metrics:**
535
+ $$\text{EffectiveTurnCost} = w_1 \cdot \text{turn\_count} + w_2 \cdot \text{renegotiation\_rate} + w_3 \cdot \frac{\text{context\_reset\_tokens}}{100}$$
536
+
537
+ Weights should be calibrated per-organization based on relative costs.
538
+
539
+ ### 6.2 Economic Analysis
540
+
541
+ The economic case for coordination cost compression:
542
+
543
+ **Traditional optimization (reduce token cost):**
544
+
545
+ - Assume 10% token reduction through better prompting
546
+ - At $0.03/1K tokens, 10K tokens/task: saves $0.03/task
547
+ - At 100 tasks/month: $3 savings
548
+
549
+ **Coordination cost optimization (reduce Turn Cost):**
550
+
551
+ - Assume 50% reduction in turns (our case study showed 62%)
552
+ - At 5 min/turn human time, $50/hr human cost: each turn costs $4.17
553
+ - At 6 turns/task baseline → 3 turns: saves $12.50/task
554
+ - At 100 tasks/month: $1,250 savings
555
+
556
+ The 400:1 ratio suggests coordination cost is the higher-leverage optimization target.
557
+
558
+ #### 6.2.1 Model Assumptions and Sensitivity Analysis
559
+
560
+ The above analysis rests on several assumptions that warrant examination:
561
+
562
+ **Key assumptions:**
563
+
564
+ | Assumption | Value Used | Range in Practice | Sensitivity |
565
+ | ----------------- | ---------- | ----------------- | ------------- |
566
+ | Human hourly rate | $50/hr | $25–$200/hr | Linear impact |
567
+ | Time per turn | 5 min | 2–15 min | Linear impact |
568
+ | Token cost | $0.03/1K | $0.001–$0.10/1K | Low impact |
569
+ | Turn reduction | 50% | 20–70% | Linear impact |
570
+ | Task frequency | 100/month | 10–1000/month | Linear impact |
571
+
572
+ **Sensitivity to human cost:** At $25/hr (junior developer), the coordination savings fall to $625/month, ratio ~208:1 vs. token optimization. At $200/hr (senior consultant), coordination savings rise to $5,000/month, ratio ~1,667:1. The directionality of our recommendation holds across the realistic range.
573
+
574
+ **Sensitivity to turn reduction:** If governance achieves only 20% turn reduction (conservative), coordination savings fall to $500/month—still ~167:1 vs. token optimization. Below ~5% turn reduction, the investment in governance infrastructure may not pay back.
575
+
576
+ **Boundary conditions where our model weakens:**
577
+
578
+ 1. **High-volume, low-touch tasks:** For tasks requiring <2 turns baseline, coordination overhead is already minimal; token optimization may dominate.
579
+
580
+ 2. **Extremely low human cost:** In contexts where human attention cost approaches zero (e.g., hobbyist projects with unlimited time), token cost becomes proportionally more important.
581
+
582
+ 3. **Rapidly changing token economics:** If token costs drop by 10× (as they have historically), the ratio shifts—but human costs have not shown comparable compression.
583
+
584
+ **Not modeled:** This analysis excludes governance creation and maintenance costs. A complete economic analysis would amortize contract development (~4 hours initial, ~30 min/week maintenance) over task volume. For teams completing >50 tasks/month, amortized governance cost is <$2/task.
585
+
586
+ ### 6.3 What Would Falsify This Framework?
587
+
588
+ A framework's value lies partly in its falsifiability. Our framework would be challenged by:
589
+
590
+ 1. **Evidence that model capability dominates:** If controlled studies showed that model choice explains >80% of variance in productivity while governance explains <10%, our thesis would be weakened.
591
+
592
+ 2. **Governance overhead exceeding benefits:** If contract creation/maintenance costs exceed Turn Cost reductions, the architecture is not cost-effective.
593
+
594
+ 3. **Ceiling effects:** If well-prompted ungoverned agents achieve similar Turn Cost metrics, governance adds complexity without benefit.
595
+
596
+ 4. **Scalability failures:** If governance contracts become unwieldy beyond ~10 rules, the architecture doesn't scale.
597
+
598
+ We do not yet have data to rule out these alternatives.
599
+
600
+ ### 6.4 Methodological Recommendations for Replication
601
+
602
+ To support rigorous testing of our framework, we propose the following experimental designs:
603
+
604
+ #### 6.4.1 Controlled Comparison Study
605
+
606
+ **Design:** Within-subjects, counterbalanced A/B comparison.
607
+
608
+ **Participants:** 20+ software engineers with varying LLM experience.
609
+
610
+ **Conditions:**
611
+
612
+ - A: Governance-first (contracts, receipts, tiers)
613
+ - B: Standard prompting (well-crafted but no governance artifacts)
614
+
615
+ **Tasks:** Standardized set of 10 software engineering tasks (bug fixes, feature additions, refactoring) across multiple complexity levels.
616
+
617
+ **Measurements:**
618
+
619
+ - Primary: Turns per task, renegotiation rate, context reset tokens
620
+ - Secondary: Task completion rate, code quality (automated metrics), participant satisfaction
621
+ - Covariates: Prior LLM experience, programming expertise, task complexity rating
622
+
623
+ **Controls:**
624
+
625
+ - Same model for both conditions
626
+ - Randomized task order
627
+ - Counterbalanced condition order across participants
628
+ - Independent coding of "renegotiation" by multiple raters
629
+
630
+ **Statistical approach:** Mixed-effects regression with participant and task as random effects, condition as fixed effect.
631
+
632
+ **Power analysis:** To detect a 30% reduction in turns (our conservative estimate), with α=0.05 and power=0.80, requires N=18 participants completing 8 tasks each.
633
+
634
+ #### 6.4.2 Longitudinal Case Studies
635
+
636
+ **Design:** Multiple-case, multiple-team observational study.
637
+
638
+ **Participants:** 3–5 development teams adopting governance framework.
639
+
640
+ **Duration:** 6 months minimum, with measurements at baseline, 1 month, 3 months, 6 months.
641
+
642
+ **Measurements:**
643
+
644
+ - Quantitative: Turn Cost components (logged automatically)
645
+ - Qualitative: Team interviews, governance artifact evolution, escalation patterns
646
+
647
+ **Analysis:** Cross-case synthesis, time-series analysis of Turn Cost trends.
648
+
649
+ #### 6.4.3 Ablation Studies
650
+
651
+ To isolate the contribution of each governance component:
652
+
653
+ | Study | Manipulated Component | Prediction |
654
+ | ----- | ---------------------------------- | -------------------------------------------- |
655
+ | A1 | Contracts only (no receipts) | Partial Turn Cost reduction |
656
+ | A2 | Receipts only (no contracts) | Improved continuity, unchanged renegotiation |
657
+ | A3 | Tiers only (no contracts/receipts) | Reduced escalation overhead |
658
+ | A4 | Full governance | Maximum Turn Cost reduction |
659
+
660
+ **Prediction:** Full governance > sum of individual components (interaction effects from coherent system).
661
+
662
+ #### 6.4.4 Minimum Viable Replication
663
+
664
+ For researchers with limited resources, a minimal replication protocol:
665
+
666
+ 1. **Sample:** 5 participants, 5 tasks each
667
+ 2. **Conditions:** Governance vs. standard (within-subjects)
668
+ 3. **Metrics:** Turn count, self-reported renegotiation, total time
669
+ 4. **Analysis:** Paired t-test or Wilcoxon signed-rank
670
+
671
+ Even N=5 with moderate effect size (d=0.8) achieves power=0.70, sufficient for preliminary replication.
672
+
673
+ ---
674
+
675
+ ## 7. Discussion
676
+
677
+ ### 7.1 Theoretical Implications
678
+
679
+ If coordination cost compression is indeed a productive axis for human–AI system design, several implications follow:
680
+
681
+ **For researchers:** Benchmarks should include coordination metrics (turns, renegotiations, context resets), not just task completion accuracy. A model that completes 95% of tasks but requires 10 turns per task may be less practical than one completing 90% in 2 turns.
682
+
683
+ **For practitioners:** Investment in governance infrastructure may yield higher returns than investment in model upgrades. The marginal cost of better prompts decreases; the marginal cost of governance scales linearly with artifact maintenance.
684
+
685
+ **For model developers:** Features supporting explicit governance (structured constraint ingestion, receipt generation, uncertainty expression) may be more valuable than raw capability improvements.
686
+
687
+ ### 7.2 Relationship to Other Approaches
688
+
689
+ **Prompt engineering:** Governance primitives can be seen as structured, versionable, testable prompt engineering. The key difference is persistence and auditability.
690
+
691
+ **Fine-tuning:** Governance operates at inference time and requires no model modification. It is complementary to, not competitive with, fine-tuning approaches.
692
+
693
+ **Multi-agent debate:** Our architecture supports multi-agent configurations but doesn't require them. Governance coordinates human–agent and agent–agent interactions uniformly.
694
+
695
+ **Retrieval-augmented generation (RAG):** Governance is orthogonal to RAG. Contracts specify _how_ retrieved information should be used, not _what_ information to retrieve.
696
+
697
+ ### 7.3 Challenges and Open Problems
698
+
699
+ Our architecture faces several significant challenges that warrant further research:
700
+
701
+ #### 7.3.1 Contract Evolution and Drift
702
+
703
+ How do contracts co-evolve with codebases? We currently rely on manual updates; automated drift detection is an open problem.
704
+
705
+ Specific challenges:
706
+
707
+ - **Staleness detection:** Contracts may reference patterns or files that no longer exist
708
+ - **Implicit constraint violations:** Code changes may satisfy the letter of contracts while violating their spirit
709
+ - **Version synchronization:** When contracts span multiple repositories or systems, consistency is difficult to maintain
710
+
711
+ Potential research directions include static analysis of contract–code alignment and LLM-assisted contract validation.
712
+
713
+ #### 7.3.2 Tier Assignment and Task Classification
714
+
715
+ Matching tasks to capability tiers currently requires human judgment. Automated task classification would improve scalability.
716
+
717
+ The core challenge is that task complexity is multi-dimensional:
718
+
719
+ - _Technical complexity_: depth of domain knowledge required
720
+ - _Coordination complexity_: number of stakeholders and dependencies
721
+ - _Ambiguity_: clarity of success criteria
722
+ - _Risk_: potential impact of errors
723
+
724
+ A comprehensive tier assignment system would need to model all four dimensions, likely requiring task-specific training data.
725
+
726
+ #### 7.3.3 Cross-Organization Generalization
727
+
728
+ Our contracts are project-specific. Domain-general governance patterns remain to be identified.
729
+
730
+ Questions include:
731
+
732
+ - Are there universal invariants (e.g., "never delete production data") that transfer across domains?
733
+ - Can contracts be parameterized or templated for reuse?
734
+ - What level of abstraction balances generalization with practical utility?
735
+
736
+ #### 7.3.4 Security and Adversarial Robustness
737
+
738
+ Malicious contracts could in principle encode harmful behavior. Contract validation and sandboxing are necessary but not yet formalized.
739
+
740
+ Attack surfaces include:
741
+
742
+ - **Injection attacks:** Contracts containing prompts that override safety guidelines
743
+ - **Exfiltration:** Contracts that direct agents to leak sensitive information through receipts
744
+ - **Denial of service:** Contracts with contradictory constraints that cause infinite loops
745
+
746
+ Mitigation strategies require formal verification techniques adapted for natural language constraints—a nascent research area.
747
+
748
+ #### 7.3.5 Relationship to AI Alignment
749
+
750
+ Our governance architecture operates at the _behavioral_ level, specifying what agents should do rather than what they should value. This is complementary to, but distinct from, AI alignment research concerned with goal specification and value learning.
751
+
752
+ Key tensions:
753
+
754
+ - **Interpretability:** Governance assumes agents can interpret and follow constraints. If models develop subtle misinterpretations, governance may provide false assurance.
755
+ - **Capability amplification risk:** Better coordination may enable more capable systems, potentially amplifying alignment failures.
756
+ - **Human oversight sufficiency:** We assume humans can verify agent outputs. As tasks grow more complex, this assumption weakens.
757
+
758
+ We do not claim governance solves alignment. We claim it addresses a different problem (coordination) that becomes increasingly important as alignment research matures.
759
+
760
+ #### 7.3.6 Cognitive Floor Effects
761
+
762
+ There may exist a "cognitive floor" below which governance cannot improve performance—a minimum model capability required to interpret and follow contracts. Preliminary observations suggest this floor is lower than expected (mid-tier models follow simple contracts reliably), but systematic mapping of capability requirements is needed.
763
+
764
+ ### 7.4 Ethical Considerations
765
+
766
+ We have endeavored to be honest about limitations and avoid overclaiming. Specific ethical notes:
767
+
768
+ - We do not claim AI "consciousness" or "understanding"; our framework treats agents as sophisticated tools.
769
+ - We acknowledge that productivity gains may affect labor markets; we do not offer policy recommendations.
770
+ - Human oversight remains essential in our architecture; we are not proposing autonomous operation.
771
+ - The framework could in principle be misused (e.g., governance that encodes harmful goals); this is true of any infrastructure and requires ongoing attention.
772
+
773
+ ---
774
+
775
+ ## 8. Limitations
776
+
777
+ Beyond those noted in §5.4, we acknowledge:
778
+
779
+ 1. **Single-author development:** The architecture was developed primarily by one team. Independent replication is needed.
780
+
781
+ 2. **Software engineering scope:** Generalization to other domains (content creation, research, customer service) is unknown.
782
+
783
+ 3. **LLM generation specificity:** Current LLMs may have properties that make governance particularly effective (e.g., high instruction-following fidelity). Future model architectures may differ.
784
+
785
+ 4. **Measurement challenges:** Turn Cost components (especially Attention Switch) are difficult to measure precisely. Our operationalizations may miss important variance.
786
+
787
+ 5. **Selection effects:** Practitioners who adopt explicit governance may differ systematically from those who don't, confounding comparisons.
788
+
789
+ ---
790
+
791
+ ## 9. Conclusion
792
+
793
+ We have proposed _coordination cost compression_ as an organizing principle for human–AI collaborative systems, contrasting it with the dominant _capability amplification_ paradigm. We introduced formal constructs—Turn Cost, environmental hostility, governance primitives—and described an architecture that operationalizes these concepts.
794
+
795
+ Preliminary evidence from a case study suggests the approach is feasible and produces measurable effects in the predicted direction. However, this evidence is limited, and substantial work remains:
796
+
797
+ - Controlled experiments with multiple teams and tasks
798
+ - Cross-domain replication
799
+ - Longitudinal studies of governance evolution
800
+ - Tooling for governance authoring and validation
801
+ - Theoretical refinement based on empirical findings
802
+
803
+ We offer this framework not as a solution but as a hypothesis: that human–AI collaboration is primarily a coordination problem, not a capability problem, and that explicit governance is a tractable intervention. We invite others to test, extend, challenge, and refine this hypothesis.
804
+
805
+ ---
806
+
807
+ ## References
808
+
809
+ [1] Brown, T., et al. (2020). "Language Models are Few-Shot Learners." _NeurIPS 2020_.
810
+
811
+ [2] OpenAI. (2023). "GPT-4 Technical Report." arXiv:2303.08774.
812
+
813
+ [3] Anthropic. (2024). "The Claude 3 Model Family." Technical Report.
814
+
815
+ [4] Zamfirescu-Pereira, J. D., et al. (2023). "Why Johnny Can't Prompt: How Non-AI Experts Try (and Fail) to Design LLM Prompts." _CHI '23_.
816
+
817
+ [5] Wooldridge, M. (2009). _An Introduction to MultiAgent Systems_. Wiley.
818
+
819
+ [6] Shoham, Y., & Leyton-Brown, K. (2008). _Multiagent Systems: Algorithmic, Game-Theoretic, and Logical Foundations_. Cambridge University Press.
820
+
821
+ [7] Jennings, N. R. (2000). "On Agent-Based Software Engineering." _Artificial Intelligence_ 117(2).
822
+
823
+ [8] Tran, K.-T., et al. (2025). "Multi-Agent Collaboration Mechanisms: A Survey of LLMs." arXiv:2501.06322.
824
+
825
+ [9] Wang, L., et al. (2024). "A Survey on Large Language Model based Autonomous Agents." _Frontiers of Computer Science_.
826
+
827
+ [10] Noy, S., & Zhang, W. (2023). "Experimental Evidence on the Productivity Effects of Generative Artificial Intelligence." _Science_ 381(6654).
828
+
829
+ [11] Bansal, G., et al. (2021). "Does the Whole Exceed its Parts? The Effect of AI Explanations on Complementary Team Performance." _CHI '21_.
830
+
831
+ [12] Bainbridge, L. (1983). "Ironies of Automation." _Automatica_ 19(6).
832
+
833
+ [13] Gaube, S., et al. (2021). "Do as AI say: susceptibility in deployment of clinical decision-aids." _NPJ Digital Medicine_ 4(1).
834
+
835
+ [14] Malone, T. W., & Crowston, K. (1994). "The Interdisciplinary Study of Coordination." _ACM Computing Surveys_ 26(1).
836
+
837
+ [15] Wei, J., et al. (2022). "Chain-of-Thought Prompting Elicits Reasoning in Large Language Models." _NeurIPS 2022_.
838
+
839
+ [16] Schick, T., et al. (2023). "Toolformer: Language Models Can Teach Themselves to Use Tools." arXiv:2302.04761.
840
+
841
+ [17] Du, Y., et al. (2023). "Improving Factuality and Reasoning in Language Models through Multiagent Debate." arXiv:2305.14325.
842
+
843
+ [18] Schulhoff, S., et al. (2023). "Ignore This Title and HackAPrompt: Exposing Systemic Vulnerabilities of LLMs through a Global Scale Prompt Hacking Competition." arXiv:2311.16119.
844
+
845
+ ---
846
+
847
+ ## Appendix A: Robert's Contracts File
848
+
849
+ ```yaml
850
+ # robert.contracts.yaml
851
+ # Size: ~1.2KB
852
+
853
+ session:
854
+ name: "Robert"
855
+ role: "Senior Implementation Engineer"
856
+
857
+ constraints:
858
+ must:
859
+ - "Follow existing patterns in neighboring code"
860
+ - "Propose minimal, coherent diffs"
861
+ - "Add test coverage for new functionality"
862
+ - "Create reversible changes when uncertain"
863
+
864
+ must_not:
865
+ - "Force push"
866
+ - "Bypass CI"
867
+ - "Merge to protected branches"
868
+ - "Generate git commit in test code"
869
+
870
+ permissions:
871
+ can:
872
+ - "Create and modify files in src/"
873
+ - "Create and modify test files"
874
+ - "Read any file in repository"
875
+
876
+ cannot:
877
+ - "Modify CONTRACT.md files"
878
+ - "Change canon/ directory"
879
+ - "Access production credentials"
880
+
881
+ uncertainty:
882
+ allowed: true
883
+ expression: "State uncertainty openly in comments"
884
+ actions:
885
+ - "Make reversible moves when unsure"
886
+ - "Leave receipts of decisions"
887
+ - "Treat failure as data, not disaster"
888
+
889
+ receipts:
890
+ location: ".robert/receipts/"
891
+ format: "yaml"
892
+ required_fields:
893
+ - action
894
+ - timestamp
895
+ - files_affected
896
+ - rationale
897
+ - confidence
898
+ ```
899
+
900
+ ---
901
+
902
+ ## Appendix B: Turn Cost Measurement Protocol
903
+
904
+ For replication, we measured Turn Cost components as follows:
905
+
906
+ | Component | Measurement Method |
907
+ | ---------------- | ------------------------------------------------------------------- |
908
+ | Latency | Timestamp difference between request send and response complete |
909
+ | Context Reset | Token count in first message after session/model boundary |
910
+ | Renegotiation | Binary flag: did this turn produce progress or only clarification? |
911
+ | Token Bloat | Difference between actual tokens and estimated minimum |
912
+ | Attention Switch | Time from response received to human action (git commit, next turn) |
913
+
914
+ "Progress" was operationalized as: code change, test addition, or documentation update accepted without reversion.
915
+
916
+ ---
917
+
918
+ ## Author's Note
919
+
920
+ This paper was co-authored by Joseph Gustavson (human, ORCID: 0009-0001-0669-0749) and AI collaborators: Claude Opus 4.5 from Anthropic (operating as "Opie") and GPT-5.1 from OpenAI (operating as "Lex").
921
+
922
+ **Attribution of contributions:**
923
+
924
+ - _Conceptual framework_: Developed collaboratively through extended dialogue (human + AI)
925
+ - _Case study design and execution_: Human-led, AI-assisted
926
+ - _Literature review_: AI-led with human curation and verification
927
+ - _Writing_: AI-drafted, human-reviewed and edited
928
+ - _Data collection_: Human (from logs and git history)
929
+ - _Critical evaluation_: Collaborative
930
+
931
+ **Statement of responsibility:**
932
+
933
+ Joseph Gustavson takes responsibility for:
934
+
935
+ - Accuracy of empirical claims
936
+ - Appropriateness of literature citations
937
+ - Ethical review and compliance
938
+ - Final editorial decisions
939
+
940
+ The AI collaborators cannot take legal or academic responsibility for the content. Their contributions are acknowledged as substantial but instrumentally authored.
941
+
942
+ **Conflict of interest:** The author is developing open-source tooling (Lex, lexrunner) based on the architecture described. This may create bias toward favorable interpretation of results.
943
+
944
+ **Data availability:** The contracts file (Appendix A) is fully reproduced. Raw logs from the case study will be made available upon reasonable request, subject to redaction of proprietary code.
945
+
946
+ ---
947
+
948
+ _Submitted for consideration as working paper / preprint. Not yet peer-reviewed._
949
+
950
+ _Version: Draft 1.2, December 2025_
951
+ _Revision 1.1: Strengthened Turn Cost positioning, expanded challenges section, added economic sensitivity analysis, included methodological recommendations for replication._
952
+ _Revision 1.2: Corrected economic analysis arithmetic, updated model names to reflect actual availability, fixed citation metadata._