Compare commits
1602 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| 005bcacbb2 | |||
| bd9d9f508b | |||
| a40eafa336 | |||
| e25b4fc401 | |||
| 98754352e5 | |||
| e47e71167b | |||
| ab08c3c238 | |||
| a95dd360c8 | |||
| b65710dca7 | |||
| 4612f71592 | |||
| f5a691ff07 | |||
| f9f96f69ae | |||
| 0b6cc71520 | |||
| 72c481696d | |||
| 5b792514a4 | |||
| e38b6c344b | |||
| 993295b486 | |||
| e687860824 | |||
| 82511b3d0f | |||
| f45e06fe9d | |||
| e8c123ced0 | |||
| 16d9b3a059 | |||
| 5c3ac81ed7 | |||
| 378dafeef3 | |||
| 0c2f2a5fd1 | |||
| ec7a161339 | |||
| 2a190c7700 | |||
| ed07d6a002 | |||
| 78ed3819aa | |||
| e2fc5dbfb2 | |||
| de5802e603 | |||
| d265e242f8 | |||
| 101c8a7c3d | |||
| 27e5014322 | |||
| b474ec2f5a | |||
| 7a568f80af | |||
| ad11c72016 | |||
| d813fdad5a | |||
| 68152c5dec | |||
| 1500c52d69 | |||
| 0c17559efe | |||
| 488f1fd698 | |||
| 76131e1ee6 | |||
| 8c1edf552a | |||
| 1e96a397af | |||
| ebbe926ab7 | |||
| fed84cc510 | |||
| 089e9b683b | |||
| 6953dcb8e0 | |||
| 96ee03260e | |||
| 457c789165 | |||
| a558908d83 | |||
| 0874b67b02 | |||
| a22fb064f4 | |||
| 56b73ca37c | |||
| cd45ced8b2 | |||
| 6d04954b66 | |||
| 0f3d42e0e7 | |||
| a8933b9ab3 | |||
| 44d5eae6d8 | |||
| 245b8262a2 | |||
| ea75ff3a4a | |||
| d6a54d1ca7 | |||
| 5ea795c694 | |||
| b0d08a3116 | |||
| 3273852b58 | |||
| e25dd3c531 | |||
| e8cd651bb8 | |||
| 83191daf0d | |||
| 86cdf96b28 | |||
| 846d6c6e36 | |||
| 0e3b0811fb | |||
| d5191410d2 | |||
| 9020193e4d | |||
| 0281c78d14 | |||
| 89f5fcbc16 | |||
| fcd6c69cc2 | |||
| 8117daba6e | |||
| 49964b5d64 | |||
| b6a27cc4dd | |||
| e3cc18f04e | |||
| 49d37891fe | |||
| b014bec299 | |||
| 071a350e2b | |||
| a430bca9f9 | |||
| e37dafb753 | |||
| 1de88b9b20 | |||
| aa51d5f1be | |||
| d5432d9739 | |||
| b2007553de | |||
| e820a0c87c | |||
| 3543221235 | |||
| c0842a5fb8 | |||
| 5d4676ff6b | |||
| a9041f9aa0 | |||
| d464f271bf | |||
| 64e33ae209 | |||
| 73183957ae | |||
| eed81c905a | |||
| ce0344f703 | |||
| 8d896d772d | |||
| 525f3f8836 | |||
| e3a964a73f | |||
| ce2e9dc0e5 | |||
| 9bd385d9cd | |||
| 9f367e90ca | |||
| 72a4d346d7 | |||
| 91cf86e0cd | |||
| cd8e335c3e | |||
| 9531e5c337 | |||
| 58df9029b6 | |||
| 88d9240e65 | |||
| d7c63a680f | |||
| e83b144cce | |||
| 460f1859fb | |||
| d7f72bd6c5 | |||
| 63bd094ec3 | |||
| 8a067c8d61 | |||
| ea58203b1a | |||
| 229566e839 | |||
| 19b0c0a372 | |||
| 2fbd5c9f8b | |||
| 7fcc979b59 | |||
| 6bd146395c | |||
| a75826d35a | |||
| 0b13a7ad44 | |||
| 506fbae5b9 | |||
| ac6085cc5c | |||
| 471cdf89e7 | |||
| f40f7eb95c | |||
| c062f8793f | |||
| 5cb0feba07 | |||
| 1b127da3db | |||
| 653fcbe3f1 | |||
| b612e43276 | |||
| 700ac3e2ce | |||
| 00b87e3fb9 | |||
| 3febd12063 | |||
| aaecb98671 | |||
| c5b5ec78ef | |||
| 8465886566 | |||
| 9ac35a4699 | |||
| b01b799743 | |||
| 113ec64f89 | |||
| 27b6433f7d | |||
| abe7226baa | |||
| 481e13253a | |||
| af81dcdcbc | |||
| fdbb007e21 | |||
| 922d26de09 | |||
| 6016f6554c | |||
| 4557dced58 | |||
| 6c406b2609 | |||
| 5f2a4b6385 | |||
| fbe133831f | |||
| abaf54bc46 | |||
| f1ae4d63b1 | |||
| 5f340d96a3 | |||
| 0e386f8ca3 | |||
| a0e1d2aea2 | |||
| 3991b0276e | |||
| 31f9360b9c | |||
| b8fce0113a | |||
| 3d3f8c9a66 | |||
| 98d1fc1eba | |||
| 92b0acb5c6 | |||
| 719bebe37f | |||
| a9702c1f2f | |||
| 422ed13f2e | |||
| 6e162d2536 | |||
| 868169ccb6 | |||
| a84c39d798 | |||
| a7d034acb9 | |||
| df224cc82a | |||
| ff16a80546 | |||
| ecff566bc6 | |||
| d83d39dd2d | |||
| 34328b11b9 | |||
| 2078ba0185 | |||
| 9f09912a02 | |||
| 88fee92dcb | |||
| 44ba6569b2 | |||
| 5f814a8a89 | |||
| e0b2068230 | |||
| 4a8b8b3e9d | |||
| 0fd5e91c2e | |||
| 51d3f9bc90 | |||
| c39d23a1b3 | |||
| 3e8910f573 | |||
| d004fde8ce | |||
| 5fb0f95e0c | |||
| 12ace75f15 | |||
| acb3371bbe | |||
| 7639933f99 | |||
| aed6a84abc | |||
| 388f726613 | |||
| ec2779ad1c | |||
| 4853922d55 | |||
| 5630c3ba2e | |||
| 194acd07f7 | |||
| 2c0673f5bf | |||
| af2593370a | |||
| 798f08dc98 | |||
| 0c44db8442 | |||
| 2199a08df8 | |||
| 31610254d8 | |||
| 15c978b708 | |||
| 1b022f4505 | |||
| 55e855983f | |||
| e9e11f10a0 | |||
| ff1fd7596f | |||
| f75c13013d | |||
| afbaa953e6 | |||
| 713d559c5b | |||
| 1774bb4274 | |||
| dbe275e59f | |||
| 5e54057f9e | |||
| ee44c99f28 | |||
| 840cb21fbc | |||
| b76a3bcf24 | |||
| e062f71d47 | |||
| 32a81b0257 | |||
| 105e723617 | |||
| 4fe37104aa | |||
| 9e41a4fc64 | |||
| f3af5e23fd | |||
| 5ed3a55e3a | |||
| d516a28750 | |||
| 20b13065ea | |||
| 45115ef5e4 | |||
| 2797e11080 | |||
| 500bd126a4 | |||
| fb0a7ac8cf | |||
| 7f9237e91e | |||
| 6e22149334 | |||
| ee296c332a | |||
| a9bdef6fcb | |||
| 4586bfcbea | |||
| 3d19ec9c6c | |||
| 6fda959b52 | |||
| 04c67d958e | |||
| afc51efb1b | |||
| ecc69835b8 | |||
| 3d34411e24 | |||
| 535ad7fd6a | |||
| 5108ab97b9 | |||
| 3cce40437e | |||
| 69cf298597 | |||
| b559775455 | |||
| 3d6227009d | |||
| 2efe914521 | |||
| 04852c3417 | |||
| 0c52688ff8 | |||
| 356ae263e1 | |||
| 29b1be3fd7 | |||
| 1a23aa05b0 | |||
| daee3c671f | |||
| a357cc7b18 | |||
| 4c109b3411 | |||
| 7605094623 | |||
| f9959d25c5 | |||
| 1845d8ff37 | |||
| b940f902b8 | |||
| 9caac90a62 | |||
| 24bcb9060b | |||
| 7c178038c5 | |||
| 8c693ea5de | |||
| 427a2cb7c3 | |||
| d954fb0026 | |||
| 56c579bd54 | |||
| 470be28759 | |||
| 0f5e8897e2 | |||
| e2c4993cc6 | |||
| 547afc6cf2 | |||
| fc4b0387d6 | |||
| ceacc86a88 | |||
| 00975177ad | |||
| 18d28fa472 | |||
| 6d7c8b5c25 | |||
| 111cb9248e | |||
| 06a1398196 | |||
| 11ee0f7bbf | |||
| 005a23f431 | |||
| 26a0a2845d | |||
| 65491d1b55 | |||
| 14123912d9 | |||
| b9afedfd80 | |||
| 07902aa7f4 | |||
| 0a18503054 | |||
| 38f4274c85 | |||
| dae767b085 | |||
| 7e141eaa1e | |||
| 22654a5e05 | |||
| 24bd382d48 | |||
| 2e0ceef6ae | |||
| f49d176103 | |||
| e6f7d50943 | |||
| 50dd61c039 | |||
| 402b0690c8 | |||
| 5013fbdf1f | |||
| f8cabf78bf | |||
| 846d9cd197 | |||
| 62b4825cea | |||
| b7d7a1f1ea | |||
| b383a89c5b | |||
| b832c1e669 | |||
| 90352d74c4 | |||
| ff3961ca77 | |||
| 84a0f1d1be | |||
| 26cadbb79e | |||
| adae921cd6 | |||
| bfe32bc1fa | |||
| 144986e671 | |||
| 68ed7ac95a | |||
| dae6f586ab | |||
| 5d9d880f44 | |||
| 90dd09e566 | |||
| ecd8a99335 | |||
| b2630b8148 | |||
| e2f5661760 | |||
| b09d30b48e | |||
| b26256ce44 | |||
| 95535b4fb3 | |||
| 017cf33611 | |||
| e37430a8a2 | |||
| e1aa89d244 | |||
| a7e1297805 | |||
| 04063e1bd8 | |||
| 914b8dc2d4 | |||
| aafe75e16f | |||
| 2806a8edc9 | |||
| 2edbde8071 | |||
| 762614353c | |||
| cb3135bc8c | |||
| 8ca612b7a4 | |||
| 9bc2887ee8 | |||
| df210aaeca | |||
| b8595db647 | |||
| ab8bf249cc | |||
| d488b8a324 | |||
| 00c156d75e | |||
| aedc5ed33e | |||
| 81e8d8a1b8 | |||
| d06eea3149 | |||
| 2471db9108 | |||
| a49a790a36 | |||
| bfcff168c2 | |||
| f3af8fda13 | |||
| ed241f3ab5 | |||
| dbfe87d36f | |||
| 53ef45dbd8 | |||
| d251d50472 | |||
| a12710ebc4 | |||
| 6b8fbc6ff5 | |||
| 08038d93eb | |||
| a559bbfcbf | |||
| 1e19f7759d | |||
| 46dc401736 | |||
| 5d350c6210 | |||
| 983e7328cf | |||
| 3649a83c0c | |||
| 33b5c8babf | |||
| 330e3f1d09 | |||
| 47b863fd9f | |||
| 52fb218e97 | |||
| 566df67639 | |||
| 610edb1ada | |||
| cff76d2172 | |||
| d1136ebb8d | |||
| 5f4bbdcbe0 | |||
| e019a6b78c | |||
| 587363c3ed | |||
| d9875ee460 | |||
| e55b8826fb | |||
| 194e3e18ad | |||
| 112536ba4e | |||
| 0ce3cc6ac6 | |||
| 1fe59960fb | |||
| f0f9d91396 | |||
| a2ea673822 | |||
| 708347382b | |||
| 78dd557057 | |||
| 999fca6f17 | |||
| 6ee55681a3 | |||
| 30595cfdf4 | |||
| 94b34e509f | |||
| 7a798a9e37 | |||
| 59c02ef8d1 | |||
| 444f5824d9 | |||
| b709e03023 | |||
| b3398bcace | |||
| ed50d76f4c | |||
| 285c4fa5ae | |||
| 0d02a83833 | |||
| 608e00b619 | |||
| 0a77e2af00 | |||
| 68d7a31920 | |||
| 444f97a566 | |||
| dd9f00f09f | |||
| 0c52e51463 | |||
| 13a22a994a | |||
| b63f79ff0b | |||
| bed22cd6c9 | |||
| b00470996b | |||
| a2afc03454 | |||
| 10c068c4e5 | |||
| 3a1b5d534b | |||
| f905c797cb | |||
| 098bfddef9 | |||
| 4fac73c890 | |||
| 01e1dece73 | |||
| 414ecfa2a0 | |||
| d4acb4b039 | |||
| 2b8dd5a72e | |||
| e4566b16cf | |||
| 7ed020490c | |||
| d652ab20d3 | |||
| 1c6f229cd9 | |||
| a2c9d2150d | |||
| 07512aa61f | |||
| 9293f0d21a | |||
| 36c0ed9bfa | |||
| ce26692676 | |||
| 0ab373711d | |||
| 63a7dd2de4 | |||
| 4b26180620 | |||
| ed58379da0 | |||
| b845d80ac7 | |||
| 3d4de11a95 | |||
| bdde2a3351 | |||
| 4d37167b00 | |||
| 9a9dd5241f | |||
| 00528e7df4 | |||
| 3e2e0ae5bf | |||
| 4778a54b6c | |||
| 8b66d1b0b0 | |||
| d8dc05b645 | |||
| 07ef481c51 | |||
| c60ad667da | |||
| ee1d3ac2b9 | |||
| 80cf302da5 | |||
| 027f441cae | |||
| b25b7ec0d9 | |||
| 4cc39b8b20 | |||
| 30f0ac6200 | |||
| fa933affe6 | |||
| e946d71a5e | |||
| f671d44747 | |||
| eab098a15f | |||
| 2432f4d0af | |||
| d99345fb8a | |||
| 8e210eaa09 | |||
| 9b47b76f52 | |||
| a49479948a | |||
| 3fac9f81bb | |||
| 7d458159cc | |||
| 4ed8e1a767 | |||
| 7b0267fe56 | |||
| 069e11ef08 | |||
| 4010d15ef2 | |||
| fdb942472d | |||
| d49831c387 | |||
| 7dec775add | |||
| f6bfe53848 | |||
| 89a7cfe65a | |||
| 001b3315bf | |||
| 382ac99c41 | |||
| d2f3bb04f4 | |||
| e22711acc2 | |||
| 0d382b6174 | |||
| 52fa1e22ef | |||
| 24cb6b2af0 | |||
| be67bc66bf | |||
| 720b558bbf | |||
| 0eea8aa10d | |||
| 7d245dcdce | |||
| 2dcf93a55f | |||
| 117c698f65 | |||
| f0c8a26688 | |||
| 29a78bc067 | |||
| d0ecdd6359 | |||
| 1df19f4ac8 | |||
| 004c76679e | |||
| 7058e8c13b | |||
| 42cff3a8a7 | |||
| 36dbddfa0b | |||
| 4e0b625191 | |||
| ea3da03468 | |||
| 05dcb40d5b | |||
| 2f78d4e0ff | |||
| ee65d9488d | |||
| 06f27feb3e | |||
| d413ee640a | |||
| 2a500230f5 | |||
| 0d3bdca5d9 | |||
| 34605579b8 | |||
| cf46cde1ec | |||
| 291d97a8f9 | |||
| b769916928 | |||
| 776a852965 | |||
| 9f6f2b887d | |||
| 310e58a103 | |||
| b976fa862a | |||
| 9c9a7d917d | |||
| f780d091b1 | |||
| 3201ac7611 | |||
| 9a4e1b069e | |||
| 38e39c93d1 | |||
| 39de100a34 | |||
| e113f02db1 | |||
| c4d06c55b5 | |||
| f35b768b75 | |||
| 1f135210a6 | |||
| f9869d2fa6 | |||
| b8a374f43c | |||
| a25b346ccb | |||
| f2e78ff18b | |||
| fa14d1a4ac | |||
| b827986ec8 | |||
| 69601b8f14 | |||
| 32928a83eb | |||
| 254fd20368 | |||
| 92f90bd232 | |||
| cb52872452 | |||
| a486e41068 | |||
| a7439c2e00 | |||
| 777dcf38e2 | |||
| ef552931df | |||
| df5d5903fc | |||
| ddce0f2cb0 | |||
| a3bb485634 | |||
| 85e69a9760 | |||
| 66ccb0d90b | |||
| 7bd192735a | |||
| b680d50ee8 | |||
| 508c82de66 | |||
| 281220a69b | |||
| 860ff80973 | |||
| b1e46d64fa | |||
| 1d411be20d | |||
| 676b909f15 | |||
| 1b9a5e39bc | |||
| 57b48ae574 | |||
| 49fe132be2 | |||
| 255539aa61 | |||
| 92bc84ba80 | |||
| 2f4107bfcd | |||
| 96ec4602fa | |||
| df1a4f9ca3 | |||
| e8255be534 | |||
| 90c7a2edbb | |||
| 6b2313d848 | |||
| de5481c16f | |||
| aa369713fe | |||
| bb7d9b86ab | |||
| 662f281d99 | |||
| aa62b081fb | |||
| adadb88119 | |||
| 59c319ebb4 | |||
| 1c2791f2ad | |||
| 5371cec343 | |||
| c33d859d80 | |||
| da066fd0b4 | |||
| 2d76216a00 | |||
| c864650fa0 | |||
| 9cc505b764 | |||
| 51b10aaf41 | |||
| fa34d832aa | |||
| 6468c820a3 | |||
| 1cb68bbb5c | |||
| 61f070c302 | |||
| e5751153a5 | |||
| f0d99c8141 | |||
| abae3a0559 | |||
| 2241ec9b37 | |||
| 2c1a84518f | |||
| 3574154a3b | |||
| 2d5f22ed4e | |||
| 47f642563f | |||
| f62ea168fe | |||
| e6c72550a7 | |||
| 885bf37891 | |||
| 5e75655771 | |||
| 251ca067d5 | |||
| ba3f8a2b15 | |||
| 61b77d8937 | |||
| a9074901ca | |||
| 74766df97a | |||
| ad42f02af0 | |||
| 72ffb9f748 | |||
| 763b5e56eb | |||
| e6b9de55cc | |||
| c63c3b3467 | |||
| 5088b9e175 | |||
| 21a15bcf78 | |||
| 75d3ed7981 | |||
| 1559dcd6c9 | |||
| 8f1d28f160 | |||
| 86dbd03501 | |||
| c1d7ecf421 | |||
| 76ae9da405 | |||
| c799081360 | |||
| e82e5c3876 | |||
| a7153c78fd | |||
| aa34fb8912 | |||
| 2d30339d25 | |||
| 54fc339fb0 | |||
| c62242b787 | |||
| 02d8a0a0e6 | |||
| 6b20685f8c | |||
| 83714f095c | |||
| 963c00136b | |||
| 2f4442ea13 | |||
| 2c5406ab38 | |||
| 2ed5c042d3 | |||
| eb49d62e36 | |||
| e898fc0f03 | |||
| 93ddc1e245 | |||
| 3b36f9ff59 | |||
| 8210754780 | |||
| aaa080a201 | |||
| 033989f6be | |||
| 897fe3ed1a | |||
| eee3ce08b4 | |||
| 82630271e6 | |||
| caa2afe8c5 | |||
| 8b7190c7a3 | |||
| a0bdeeb883 | |||
| 12954bbd40 | |||
| 428e66aa8a | |||
| 3cbcf358bd | |||
| bc65de4bf7 | |||
| 42a6b6533f | |||
| baee3252ca | |||
| d8cd30584f | |||
| 8744584fb6 | |||
| 4729412f8a | |||
| 0910ff430a | |||
| a638e1df73 | |||
| 5bc69f1689 | |||
| c091ad9704 | |||
| 0b6d103764 | |||
| 286a21a32f | |||
| d221fbfeac | |||
| 58f6505851 | |||
| 29568fab6c | |||
| 28ff6d7731 | |||
| db0c5d4ec8 | |||
| 9bdf861087 | |||
| 901a7d698f | |||
| 59e176743f | |||
| 2776d1694d | |||
| 3de693f1a5 | |||
| f444dca67a | |||
| 1c14caf494 | |||
| aabbefaad5 | |||
| b5033abacc | |||
| 6fd28775b6 | |||
| 9845ff3851 | |||
| 1ce01656c3 | |||
| 3f50f0389f | |||
| 7bc2586831 | |||
| 5b6c2a9519 | |||
| 01d2788134 | |||
| 76b6e029b9 | |||
| 1c8c071582 | |||
| c38030d638 | |||
| 30648af4d3 | |||
| 94a6a0f8c8 | |||
| ea22530878 | |||
| 0018508657 | |||
| 8072382dbc | |||
| d9fb8b0d97 | |||
| 3f5fd41226 | |||
| c10dd996aa | |||
| b163dadbbd | |||
| a29d2a2315 | |||
| 5d4c6b3237 | |||
| 02288f955b | |||
| fe351d3ed4 | |||
| dff9051d8c | |||
| 080a6a8693 | |||
| b93d3799c3 | |||
| 9d1d25218f | |||
| 0755291112 | |||
| 9e47b0d566 | |||
| 61ed465e99 | |||
| aa968b9662 | |||
| f901ba091d | |||
| 848f40f0c6 | |||
| 13a70bfb49 | |||
| b34d1087ca | |||
| e2977b4946 | |||
| 34694d321e | |||
| ed3a66e085 | |||
| 02e950dbc2 | |||
| 3525366485 | |||
| c20ef6e81a | |||
| 4678ac6798 | |||
| 6b07e19c34 | |||
| 31b8edb4c9 | |||
| 6c52766a27 | |||
| 43dfd375b8 | |||
| 232327d893 | |||
| fbdc6124df | |||
| 53b9602982 | |||
| a7b2fd0ae1 | |||
| dd72667c1f | |||
| 0f1ee8767c | |||
| e5258525e7 | |||
| e60e891251 | |||
| 0aec288e75 | |||
| d615a53fa1 | |||
| c40f16ba5d | |||
| 7446b7199b | |||
| fd9215ac9c | |||
| 7460454d93 | |||
| eddfd743e9 | |||
| 4cdc1c4be9 | |||
| b8071033df | |||
| 3229f13b7a | |||
| e4b3d56b70 | |||
| 5f098aa315 | |||
| bb8516380e | |||
| 155a65117c | |||
| cdff7a234e | |||
| 970ecdb8a3 | |||
| aa2815ba75 | |||
| 1a9df179a8 | |||
| d051c4ffe8 | |||
| 641645c081 | |||
| b3c95c2c3d | |||
| a25b603766 | |||
| 49d1a6cb97 | |||
| 4faf6f386e | |||
| 51fe0cea96 | |||
| 697872368a | |||
| bfde3ffecb | |||
| 7b9e43e2bd | |||
| 12e57372cd | |||
| cb6dd6d3a7 | |||
| b43f2242c5 | |||
| 8fa05d9551 | |||
| 3f0d5f0017 | |||
| 548c4ea125 | |||
| 64ab847b0a | |||
| 7c4bef6332 | |||
| 351bbc022f | |||
| 934a398be0 | |||
| 3543d9e964 | |||
| d57ce9b1be | |||
| 268046a6ab | |||
| a7dbe00c89 | |||
| 9db706946d | |||
| b1c31f93bc | |||
| 53496587be | |||
| e6d4321f6c | |||
| 58c0e64fb9 | |||
| c1b278d2ea | |||
| 461b88d4ee | |||
| 89fb819fbe | |||
| c988bd61b4 | |||
| 8581aba41f | |||
| 5a757bae1f | |||
| 72b8dd3263 | |||
| 6eea7e5522 | |||
| 1cdfda168a | |||
| 9dae3d9dd5 | |||
| edbeefe99c | |||
| 176e5b7a66 | |||
| 8a6c5102df | |||
| a87b9a4d16 | |||
| 242be1db34 | |||
| 376a5a8323 | |||
| 07674b2c20 | |||
| 4875e07f98 | |||
| b4490b4a8c | |||
| 2e44ec95ca | |||
| 24800c156b | |||
| 7da82b4748 | |||
| f56962cd8d | |||
| a924cd2647 | |||
| 20edbcdd21 | |||
| 1bc2ce89e7 | |||
| 7e7bc4a20c | |||
| 7931f8c9d3 | |||
| 2a24488a37 | |||
| 48c65b9ba4 | |||
| 0090f87351 | |||
| 7e3204a089 | |||
| a1e72d98f1 | |||
| 432b62aa08 | |||
| c3745ca03f | |||
| e42eb5b288 | |||
| 51917dfd6c | |||
| b7ec782282 | |||
| 75ae8639ab | |||
| ed9ab534f8 | |||
| 879dae4960 | |||
| 192b9feda2 | |||
| 3a77ebdb0d | |||
| 74d69fedfb | |||
| 97af00ef35 | |||
| 47c8fd2963 | |||
| b8a1a13ad0 | |||
| eb64154384 | |||
| 6d1a4a05c9 | |||
| 04904180d5 | |||
| 48e69063b8 | |||
| c7248165db | |||
| 5d10871ab5 | |||
| 4f766f7ab2 | |||
| abe30ab893 | |||
| 4c0378c2d0 | |||
| f0bd187cd7 | |||
| 62a2df4545 | |||
| b9876c17fe | |||
| 7b0e4d013e | |||
| cc51901717 | |||
| 5aabbc87bf | |||
| c3a3a9a82f | |||
| f2a4347d78 | |||
| afd7abaa5e | |||
| e1e9d03df1 | |||
| b067d8cda8 | |||
| d9fd60a714 | |||
| 38544dd2d3 | |||
| 2f0708f390 | |||
| 2600fbb254 | |||
| b5afb4c36a | |||
| 27a4f838e5 | |||
| c0f3b2fc10 | |||
| d0dd62c998 | |||
| fe7e05da5a | |||
| 92ffec7949 | |||
| e4529bee9c | |||
| 8c17462321 | |||
| 315b4da925 | |||
| 2c504133b8 | |||
| 1c031866a4 | |||
| 1598b6178e | |||
| 9f4ccbe111 | |||
| ac9566510c | |||
| d6226070db | |||
| e1d2eae7f4 | |||
| 73600d7288 | |||
| 3afbb55451 | |||
| 4b5086153a | |||
| 5bb49dc623 | |||
| ce98a50027 | |||
| 3c85562bb9 | |||
| 242f87a9b3 | |||
| 8d24f73971 | |||
| 2fc9f7212c | |||
| 31da587415 | |||
| 79e0f755e2 | |||
| fde2718a97 | |||
| a06a6dec22 | |||
| 8deef3b4ac | |||
| ba0356adae | |||
| a7a6640ea1 | |||
| 50ce373c40 | |||
| fda61ac06e | |||
| ba21a1efcd | |||
| a60bfdbc1c | |||
| f58250d0ce | |||
| 3f7d85c48e | |||
| 64454f86a8 | |||
| b62dea42fc | |||
| d01d0d421e | |||
| f2b7eb7fd2 | |||
| a921b08207 | |||
| e2c4e94cb2 | |||
| 251b0e8f02 | |||
| bac9cf9756 | |||
| 880d0c6342 | |||
| 068ab77ce3 | |||
| 4985e6a2a9 | |||
| 55235a07d8 | |||
| 96e1b364f1 | |||
| 30b0e9e0a7 | |||
| 255d5f7bb1 | |||
| 986697ab52 | |||
| fa9d487afd | |||
| fbd1b5e99d | |||
| f3eaf19f62 | |||
| 4e02971bfe | |||
| 3fd7e15255 | |||
| 2de1e7e74e | |||
| eecb0387ca | |||
| 7fc64d860a | |||
| 00c1dd2480 | |||
| f768ef3272 | |||
| cf1180734c | |||
| 727ed70ecb | |||
| 9d9c5a3352 | |||
| 2db4759c2a | |||
| 9d685c52b3 | |||
| c56b3166a0 | |||
| b6a53ef98b | |||
| c46a117088 | |||
| 121aba05ea | |||
| eb5a63edd2 | |||
| 2707cfc04e | |||
| 53a54e50dd | |||
| 2e9d9dd714 | |||
| 0681e9be17 | |||
| 2fdc75d035 | |||
| bad76b07c8 | |||
| 9dd8441f3b | |||
| 1210f8cd68 | |||
| 0f0ba7fa43 | |||
| 37078cffa9 | |||
| 30129051ad | |||
| 58055f0fac | |||
| 55ad029df2 | |||
| b89ac805d3 | |||
| 8b649682dc | |||
| 4447e89e48 | |||
| 3c522160c9 | |||
| 39bf6e6d94 | |||
| 0339a515fc | |||
| 75c3c581ef | |||
| cca16e702a | |||
| 36d9ddb6f5 | |||
| dbc8cfe854 | |||
| fffba3d454 | |||
| 2695e9b530 | |||
| 4873ee9e74 | |||
| 70e3c0b9de | |||
| 93a4da0728 | |||
| bcb04e32d4 | |||
| 37fcedc5bf | |||
| e18555be3e | |||
| 2136413dd6 | |||
| e37518db29 | |||
| 9e0a6d4d7b | |||
| aff46cd64e | |||
| 0109f97cd7 | |||
| 85f3b74d4f | |||
| bf1897b1a0 | |||
| 34468c20d7 | |||
| bedd304479 | |||
| daaa61b607 | |||
| 3422a39b6f | |||
| d2133c410f | |||
| a62992d877 | |||
| 2ecec90ec5 | |||
| 46135acab6 | |||
| 8d58dec886 | |||
| c5acadf8d3 | |||
| 0a20b6d4f6 | |||
| 58b098b89d | |||
| 564b022c93 | |||
| e8ef498977 | |||
| 4abefba032 | |||
| e8988b5192 | |||
| 4854ea0624 | |||
| d9c4e71f8d | |||
| 39163df349 | |||
| 1715c58548 | |||
| cbf007f68c | |||
| 510df4b31d | |||
| f830d764cd | |||
| e71170a2d6 | |||
| 3f2046f4be | |||
| 54ab1e4c69 | |||
| d07d108943 | |||
| e44d5bef50 | |||
| b057cc0deb | |||
| aa55d01564 | |||
| b60d921427 | |||
| 9b56738935 | |||
| 2b5e4998cc | |||
| cab71cc03e | |||
| d432fa207f | |||
| a976ef611d | |||
| 39e4e5d4f8 | |||
| 2e6f6d91cf | |||
| b405c81d10 | |||
| da5eb0d203 | |||
| 1f963024c8 | |||
| dfa2989e8b | |||
| 854a8cccda | |||
| cce83286d3 | |||
| ac71228969 | |||
| dd9da17240 | |||
| addfead4c7 | |||
| e3875d2b05 | |||
| 6326edcd5b | |||
| e78725db51 | |||
| 60bc76c876 | |||
| 7f5c3fcbbc | |||
| 6687c913e2 | |||
| a194747012 | |||
| 73f7cf1a62 | |||
| a9c15b79a0 | |||
| 155f1e873c | |||
| 0aa89d283e | |||
| 669a2833c5 | |||
| fe31d6eae5 | |||
| 35f1f5e70f | |||
| af8e7ad3d1 | |||
| 2a7018dc43 | |||
| a0945b6dae | |||
| 800f7b3031 | |||
| 8e79cb7dc8 | |||
| 6804b9496e | |||
| 50d34ce804 | |||
| 05f8136b0f | |||
| 1bc63d930c | |||
| 87049dd077 | |||
| e171260c36 | |||
| c38810e06e | |||
| 563adfbe37 | |||
| 11999981b3 | |||
| 3ea3d5427e | |||
| 06e4570e2e | |||
| 7afc08e280 | |||
| a744154bd9 | |||
| 8736402eef | |||
| 156d466703 | |||
| e95826ae60 | |||
| c264c1cda4 | |||
| ae0fba2ecd | |||
| 4cd55dd437 | |||
| 48e1e9dedc | |||
| c4ed9f1592 | |||
| 6349beaf8a | |||
| dd1a8fc203 | |||
| eb692daee2 | |||
| ad70ec6dad | |||
| a8d0a9011c | |||
| 6a553b9574 | |||
| f648f4235a | |||
| 0a664ae889 | |||
| 6862420b51 | |||
| ea0910d60d | |||
| 68f867e74b | |||
| f8958fbfe0 | |||
| 9dba8e97be | |||
| c97e4ad21b | |||
| fc5e78ba88 | |||
| 5c05520f1d | |||
| 68808e7eee | |||
| b514dcfe85 | |||
| 3a2d72a007 | |||
| e38e45579f | |||
| 0d16290e38 | |||
| 55967b5fa6 | |||
| 8363514fe9 | |||
| 415d1dc704 | |||
| c99c53202d | |||
| 22265462e0 | |||
| 20f8ba29da | |||
| 2b4c8b4cab | |||
| 93bad95bfd | |||
| c4499f3db0 | |||
| 4d5abf3bd1 | |||
| d443cf1ee3 | |||
| 53a754a1d7 | |||
| 62c67af820 | |||
| 9b1a45a993 | |||
| 9b145d488f | |||
| ed67d052aa | |||
| c51c246c36 | |||
| 3931eef451 | |||
| 8e6b2f1f12 | |||
| 98c28cc244 | |||
| 4e0e7e655d | |||
| 0f142f8da5 | |||
| 9ac89c3d50 | |||
| 8ee67ed2b7 | |||
| d008dc09f2 | |||
| 728c7b004a | |||
| 543d85238a | |||
| 59d972cc82 | |||
| c19f097ecd | |||
| 520e0e9aa5 | |||
| 728030b39a | |||
| 969002d118 | |||
| 2fb0e7be5a | |||
| 0f2cb3557f | |||
| 4eed9114e5 | |||
| 8a50a676a4 | |||
| 18dbf7b3d8 | |||
| 90d5f0039d | |||
| 59523ed21e | |||
| c61cab9ac8 | |||
| e4ac0dead0 | |||
| a040b1e882 | |||
| d6e8b7b105 | |||
| 0cb2cbabcd | |||
| 812badf8b4 | |||
| 0348b3fa1a | |||
| 8ca0a8c674 | |||
| 0ac8cad97f | |||
| a87b6cff98 | |||
| f507dcad04 | |||
| 2f105b8d60 | |||
| f87441f900 | |||
| e6c3fbcb2c | |||
| 4be32f9718 | |||
| fb9c14a269 | |||
| f98e8a84dd | |||
| 1692679985 | |||
| 3aa53d8ae6 | |||
| 366e82ead4 | |||
| ce87a519f0 | |||
| 82f4bbd91b | |||
| 499d1772be | |||
| 2062e91920 | |||
| 15fb37dc0c | |||
| 1f65b5512b | |||
| 27b5409479 | |||
| 6cdbcbc08b | |||
| 89a85f88df | |||
| 9b6303f561 | |||
| 9508838439 | |||
| 4fc00a0b89 | |||
| b2142ee620 | |||
| d15380249d | |||
| 4718baca27 | |||
| 084bc74b1c | |||
| 854eb63407 | |||
| f69ef96505 | |||
| 19888fc129 | |||
| aa0c7970bd | |||
| c1924e51ef | |||
| 0e0b17cd92 | |||
| 35f3d4401a | |||
| 7fec47f9b9 | |||
| 472b15b76d | |||
| 8252bc0114 | |||
| b6cb29f2c2 | |||
| 637a60a017 | |||
| 3213971f98 | |||
| 8c3a554641 | |||
| c82ed0e920 | |||
| 52e1f7f315 | |||
| 26f5ccde78 | |||
| 91f142e736 | |||
| e0c8209750 | |||
| 4b6eb37252 | |||
| b9fe2e2bf5 | |||
| 153a85c78f | |||
| c8eeeadd24 | |||
| 66670f4e3d | |||
| 0cc242ac1b | |||
| 60a1f5c385 | |||
| b4b84a4280 | |||
| bc066943f6 | |||
| 7b59056c3d | |||
| 333ebe58b8 | |||
| effe6393c0 | |||
| a55ecc0be6 | |||
| 023e121e1b | |||
| a08da8b266 | |||
| 6520628fef | |||
| 3a3631609c | |||
| e758bf1a91 | |||
| db88211599 | |||
| 9d0e2ad853 | |||
| 839eb6f084 | |||
| ade48c57b5 | |||
| 45ecf0798e | |||
| ee241646e7 | |||
| 4b3ac621b8 | |||
| 5331a34000 | |||
| d029f9a1ee | |||
| e6da7b0b9c | |||
| 87d5023773 | |||
| 227ef2de31 | |||
| 64eb8fc7d7 | |||
| e1ca619e96 | |||
| 1f3349065a | |||
| 6e05ed2155 | |||
| b96e9d6349 | |||
| 3a83c08746 | |||
| 6b7392adcb | |||
| 8f03747d9a | |||
| ee79e2bbc8 | |||
| 5c7969e7c8 | |||
| c180bda54b | |||
| 583da20cbd | |||
| cfb5e50904 | |||
| 1272894aea | |||
| 7eb573cf17 | |||
| 6411e94565 | |||
| e06ec11254 | |||
| c5dc8b5755 | |||
| f907c2e773 | |||
| 772996c544 | |||
| c92d2cccca | |||
| 2d8b4bb8da | |||
| 128fea7497 | |||
| d648e4a989 | |||
| 220bd39d49 | |||
| 4f5a7aa411 | |||
| 0a47b55c93 | |||
| 2ca6fac1d4 | |||
| ad9bce7185 | |||
| 7b6201cab6 | |||
| ad6118d19f | |||
| c82b528122 | |||
| eb61043c12 | |||
| b439cd82e1 | |||
| 4e122757b5 | |||
| 1157aaabfb | |||
| 82a3d3e266 | |||
| 06c938b950 | |||
| c034c43259 | |||
| d96ea9ea3c | |||
| f9d8bbc3c3 | |||
| 7a5063db5d | |||
| 31d0096949 | |||
| 9fbffbf5dd | |||
| c46a68c1c6 | |||
| fb146abfac | |||
| 4840683a26 | |||
| 5e646dfdd1 | |||
| 525f9ccb9d | |||
| 0c98931df0 | |||
| 4a1ffd17e0 | |||
| bbd56306b5 | |||
| 3070f09663 | |||
| e705fd8867 | |||
| d5a9576fff | |||
| c8c3702eb8 | |||
| 6a617f5a2c | |||
| 3f7f4e74fc | |||
| 7b10fd6e58 | |||
| d97846c60e | |||
| 0a26bcb807 | |||
| 9a260d22c0 | |||
| 14e6756a53 | |||
| 7e29dc0014 | |||
| 95fb0d03cf | |||
| 5c37027046 | |||
| 9066f477a4 | |||
| 41e91e341c | |||
| 913accfe14 | |||
| fba48f324c | |||
| 62faf321ce | |||
| 76348eac2e | |||
| 8f8d340c09 | |||
| a4fc833b2b | |||
| 59a8fe9f45 | |||
| 74f3199df1 | |||
| d2ca49bf00 | |||
| e3a6ae0e42 | |||
| bad2f0c555 | |||
| d81da4d413 | |||
| 545a57f01c | |||
| 4ab80160b6 | |||
| 2fa7040006 | |||
| 18a73b1bf1 | |||
| 6156e0b9cc | |||
| 08d4be4bae | |||
| b2ddebce7a | |||
| a61afc567d | |||
| 1f31ebd8ac | |||
| b03bfab121 | |||
| 2294916343 | |||
| c010b12c5a | |||
| 6ff139f67c | |||
| 7b0e428eec | |||
| dd7e9b9929 | |||
| 02bde923e5 | |||
| 87ffd81d21 | |||
| 2770de2744 | |||
| 058f4ca7aa | |||
| d55b1e4ad5 | |||
| 4fc822c346 | |||
| cbe99537e2 | |||
| fa54ed46b1 | |||
| 72d9a9f652 | |||
| d449c552c6 | |||
| 67e272d5ef | |||
| ec0b17b03f | |||
| 1fc7bf0f52 | |||
| 3c4cedd389 | |||
| 8dc82fcf95 | |||
| 1f8b33d485 | |||
| 1d1172098f | |||
| 58133e69fe | |||
| 37f19d1677 | |||
| 22942308f6 | |||
| eaa67bfcd9 | |||
| c04864b6f0 | |||
| 90773cfa5f | |||
| f299bf332b | |||
| 876e0afb45 | |||
| 6e2656d83d | |||
| 2ab44beca2 | |||
| 0d32cab386 | |||
| e86a0cbc0c | |||
| e4e3d8cff0 | |||
| b19ecc459e | |||
| afba2d0bbb | |||
| bf0f0c5ecf | |||
| 9efcdab4f8 | |||
| 9439d7ec5c | |||
| 0ca23f5612 | |||
| 7b93108618 | |||
| ed914030f8 | |||
| 34689413ac | |||
| 5ccb51f763 | |||
| 4132d8cf18 | |||
| 0d05c9b2d8 | |||
| 9bc6abdf91 | |||
| 2db70062dc | |||
| 35911bde8f | |||
| 4adcadcddb | |||
| 2922d70a45 | |||
| 9196aeb5c7 | |||
| 07aa4b9f83 | |||
| 9c11fefe45 | |||
| 384b1bbc63 | |||
| 4c971a7cc4 | |||
| 348abfec59 | |||
| 2556fdace9 | |||
| 6817b074bd | |||
| 46436f2ee0 | |||
| e1e99645be | |||
| 45fd66d3ab | |||
| 66b9651d68 | |||
| 7a7dc4b75d | |||
| 39a8a57b76 | |||
| 58517a0c54 | |||
| c61997f7b7 | |||
| 75c9c2718a | |||
| 1a60de25ab | |||
| 304a2ea988 | |||
| 79f6334c7f | |||
| 4ab5b629ea | |||
| afcd6801a1 | |||
| 46803b7e81 | |||
| 042f48a0f4 | |||
| e0634e52bb | |||
| 595e2f8c4b | |||
| 70cb7bd1be | |||
| c1f08668b7 | |||
| 05806b517d | |||
| 93c81c48ab | |||
| a713fd6a88 | |||
| 6e67cc59fa | |||
| 071d6cf1cd | |||
| 8e46ef69b1 | |||
| 968cc37661 | |||
| 2ca4d0f8db | |||
| 4d132e9a3c | |||
| 3f1967a24f | |||
| d2d5e10e19 | |||
| b6c14ba223 | |||
| 313e129b20 | |||
| 23af106b47 | |||
| aacfe7d3d3 | |||
| a0b8cf7882 | |||
| f5201cb638 | |||
| 14ae30a731 | |||
| f10170bf8b | |||
| 5588270e43 | |||
| b1037248a5 | |||
| c9514fe8b4 | |||
| 079c651105 | |||
| 9da3431e25 | |||
| cd2ac5d727 | |||
| 563e8cdc3c | |||
| f70bed52fe | |||
| 6a803b168b | |||
| b74268b941 | |||
| 581c8721a0 | |||
| 63369d5944 | |||
| 11804ac6aa | |||
| 4c9bc080bb | |||
| 38c64c9f12 | |||
| aa777819e8 | |||
| 8f253dae3b | |||
| 7afc59a9d7 | |||
| 42a637d718 | |||
| 79e8ce1368 | |||
| e99eef43b9 | |||
| 25967807ff | |||
| a52ebb94bf | |||
| 55bb6c12ce | |||
| 96a2d1ce7b | |||
| b4f9d42ff1 | |||
| f549f8617a | |||
| e7128656b2 | |||
| 7507b3b670 | |||
| 2d5ad7e895 | |||
| daa3a54b90 | |||
| 0581a0fec4 | |||
| e2e3fb36e7 | |||
| d41dfd0401 | |||
| 9cf48d5337 | |||
| 32b4df6985 | |||
| dcb9abf644 | |||
| 9b770e4893 | |||
| 2db7f462a9 | |||
| b06a189c05 | |||
| c52b5812e9 | |||
| b6414655d1 | |||
| 6d6876fbcf | |||
| 84d23fa95c | |||
| 5d903b4bfd | |||
| c9a2c7b704 | |||
| 0c2f37d284 | |||
| 118a7d22d3 | |||
| 56ba3b0c1a | |||
| b389b89e13 | |||
| c0423e49d6 | |||
| ae73be7e22 | |||
| 15e31607f2 | |||
| eae9a29553 | |||
| feb15e18fa | |||
| 957ecaea77 | |||
| ed774a5fc1 | |||
| b99e362a8c | |||
| d183c81497 | |||
| 89bd9e86cc | |||
| 0b5a41fbf9 | |||
| 21bd753c5b | |||
| 47c10c4565 | |||
| 3e289c95d9 | |||
| 1fa03973a3 | |||
| 329f0fd3a0 | |||
| 52da15ea2b | |||
| 09caf3576f | |||
| 7fb019914e | |||
| 5c08bc34d6 | |||
| 0fdaf926c5 | |||
| 87273e94a4 | |||
| 13d1550299 | |||
| 58402083cb | |||
| 567ff471ec | |||
| 538fbc52b9 | |||
| ac98e0e4a7 | |||
| e69eb982bc | |||
| 1c6e04c8b8 | |||
| 92867f64cd | |||
| 0301ca01c4 | |||
| 3ee136ae44 | |||
| 5b230fd013 | |||
| d2ad46c9cb | |||
| 03ee7a4a75 | |||
| 79d764e682 | |||
| 6440824f27 | |||
| e10e301582 | |||
| 1bb740a47f | |||
| 05539e2e0d | |||
| 998e295ef9 | |||
| f2fef1d32d | |||
| 7d187d22f3 | |||
| 493a652499 | |||
| 12d70586ed | |||
| ce941388a2 | |||
| b6038c4e41 | |||
| a875e11e00 | |||
| 70a1b95086 | |||
| b3d4b8fe27 | |||
| 8a80d452f2 | |||
| ce126aa1aa | |||
| 055ee752ba | |||
| 5f47b4e1d5 | |||
| ed0fea8eef | |||
| b195ba8bf1 | |||
| 7143c9daad | |||
| cfd3008615 | |||
| 41b91e2265 | |||
| 968f22b5ae | |||
| 23381b08eb | |||
| 509804da0d | |||
| cda45a931c | |||
| 23b7848be6 | |||
| 67c7c979a0 | |||
| 7a93e58f70 | |||
| 8efb1fe50f | |||
| a49a59f7ff | |||
| 8cc9a89265 | |||
| 067fa84fcb | |||
| ba903c58d2 | |||
| 62d1f5edd4 | |||
| 034356f34b | |||
| c638ad7aec | |||
| 664b35e966 | |||
| 6a85249d99 | |||
| c2792f684a | |||
| df887fa738 | |||
| 46fc4dde7c | |||
| 6fdf7d28a5 | |||
| b58916ae71 | |||
| f99537976a | |||
| 3bf00dace7 | |||
| a0ceffa2a5 | |||
| b91c2ee84d | |||
| d87b191a59 | |||
| 04420741ac | |||
| 5dfded3663 | |||
| 0cdffa4d25 | |||
| c1e4e8508a | |||
| 299862c70d | |||
| 82eb8ffd14 | |||
| 98b7bfde8f | |||
| f213dfbac5 | |||
| fc96708b90 | |||
| aebe45ef5e | |||
| 47f53cd0f7 | |||
| cef13bb354 | |||
| f1967aca68 | |||
| 8b696b9aa4 | |||
| 301e403d02 | |||
| 8812fae906 | |||
| 447653fda5 | |||
| 4593c2969a | |||
| da4d376136 | |||
| 6e95eb146d | |||
| d62857f20e | |||
| a2390754f3 | |||
| a88f74f5ac | |||
| 73d77a0cf8 | |||
| 2348e9abac | |||
| 94aa8bafbf | |||
| daf6a38fc3 | |||
| 547a9505fd | |||
| 455efdc0d1 | |||
| eebd88f232 | |||
| 658f506414 | |||
| 0de3bf903f | |||
| c1d485912c | |||
| 04a0ea384f | |||
| c26b5ab1ec | |||
| 797c5dd4fc | |||
| 7bd0b9a446 | |||
| 6820946f2b | |||
| 4d25e43c5e | |||
| 81260cdaf0 | |||
| 02921d4174 | |||
| 3bee7d5006 | |||
| 02b657cd34 | |||
| 517276ba4f | |||
| e97d30f809 | |||
| f24a653a02 | |||
| 4ec3aea918 | |||
| f6a8b2b6d9 | |||
| e90a7ba1ad | |||
| 520336646e | |||
| 126b125e9b | |||
| 0c5ea295f1 | |||
| c47d65996e | |||
| 1e5c01eb82 | |||
| fae4a2ec12 | |||
| 823834da06 | |||
| ec7ee62b36 | |||
| 275e384172 | |||
| 54b239d7f3 | |||
| 560bf4f50b | |||
| bd96cb7c03 | |||
| 19c09e0526 | |||
| c37e4e2209 | |||
| 02c2b40db4 | |||
| be58748566 | |||
| 09159d7158 | |||
| 7a5df16882 | |||
| d1ff133941 | |||
| b83c1ddf19 | |||
| bc2d7d6d5e | |||
| a2efccfa57 | |||
| a486df3e9d | |||
| f01d6bc8bd | |||
| 87f7249b82 | |||
| 380b4e9b41 | |||
| 1d2bbacb24 | |||
| c300ce2460 | |||
| fd5bd973db | |||
| c7c9f72d74 | |||
| 71653b2069 | |||
| 8a184c97ae | |||
| b18e63653c | |||
| 8a62df6bf5 | |||
| 1af11e913f | |||
| 6176f72355 | |||
| 0a9a4dc159 | |||
| 772eb3051a | |||
| 40ada0788a | |||
| d8e43bc0fc | |||
| 627921cab4 | |||
| c74ec6fc0a | |||
| a3cd9796a4 | |||
| 268200de23 | |||
| 2a0eabe8d9 | |||
| f62b6b870e | |||
| 2956997794 | |||
| 897d93d357 | |||
| 293532bb58 | |||
| db019c626f | |||
| 801dcc8233 | |||
| 6a1d5c81c3 | |||
| b37d03056c | |||
| bcbd9f455f | |||
| 6091ae0dfc |
@@ -0,0 +1,6 @@
|
||||
# This repo keeps no `AGENTS.md`
|
||||
|
||||
`~/.claude` is a checkout of this repo, so an `AGENTS.md` here would load into every other project's sessions. Where a rule names a project's `AGENTS.md`, read it here as:
|
||||
|
||||
- the project principles, the title of each decision no project principle covers, and the working rules: the head of `docs/decisions.md`, before `# Decisions`;
|
||||
- the scoring-run values: `skills/comprehension-panel/seat-prompts.md` → "claude-config's values".
|
||||
@@ -1,3 +1,4 @@
|
||||
{
|
||||
"model": "claude-opus-5-5"
|
||||
"model": "claude-opus-5-5",
|
||||
"claudeMdExcludes": ["**/.claude/CLAUDE.md"]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,17 @@
|
||||
name: CI
|
||||
on: pull_request
|
||||
|
||||
# A push to a pull request cancels that pull request's older runs; the merge gate reads only the head commit's status.
|
||||
# The group is the ref: refs/pull/<number>/head for a pull request, the branch for a push, so no two refs cancel each other's runs.
|
||||
concurrency:
|
||||
group: ci-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
tests:
|
||||
runs-on: docker-host
|
||||
steps:
|
||||
- uses: actions/checkout@v7.0.1
|
||||
with:
|
||||
fetch-depth: 0 # ci.sh bundles HEAD, which fails in a shallow clone
|
||||
- run: sh ci.sh
|
||||
+114
-6
@@ -6,31 +6,71 @@
|
||||
|
||||
!.gitattributes
|
||||
!.gitignore
|
||||
!AGENTS.md
|
||||
!CHANGELOG.md
|
||||
!CLAUDE.md
|
||||
!LICENSE.md
|
||||
!README.md
|
||||
!ci.sh
|
||||
!settings.json
|
||||
!todo.md
|
||||
|
||||
!.claude/
|
||||
!.claude/rules/
|
||||
!.claude/rules/*.md
|
||||
!.claude/settings.json
|
||||
!.gitea/
|
||||
!.gitea/workflows/
|
||||
!.gitea/workflows/*.yml
|
||||
!agents/
|
||||
!agents/*.md
|
||||
!bin/
|
||||
!bin/adf_codec/
|
||||
!bin/adf_codec/*.py
|
||||
!bin/adf_codec/node_shim/
|
||||
!bin/adf_codec/node_shim/Dockerfile
|
||||
!bin/adf_codec/node_shim/package-lock.json
|
||||
!bin/adf_codec/node_shim/package.json
|
||||
!bin/adf_codec/node_shim/shim.mjs
|
||||
!bin/agent_cycle/
|
||||
!bin/agent_cycle/*.py
|
||||
!bin/atlassian/
|
||||
!bin/atlassian/*.py
|
||||
!bin/branch_chunks/
|
||||
!bin/branch_chunks/*.py
|
||||
!bin/chunk-pr
|
||||
!bin/chunk-preflight
|
||||
!bin/chunk_driver/
|
||||
!bin/chunk_driver/*.py
|
||||
!bin/chunk_driver/project/
|
||||
!bin/chunk_driver/project/*.py
|
||||
!bin/chunk_pr/
|
||||
!bin/chunk_pr/*.py
|
||||
!bin/chunk_preflight/
|
||||
!bin/chunk_preflight/*.py
|
||||
!bin/claude_code/
|
||||
!bin/claude_code/*.py
|
||||
!bin/command-patterns
|
||||
!bin/command_lines/
|
||||
!bin/command_lines/*.py
|
||||
!bin/command_patterns/
|
||||
!bin/command_patterns/*.py
|
||||
!bin/compress-archives
|
||||
!bin/compress_archives/
|
||||
!bin/compress_archives/*.py
|
||||
!bin/deploy-release
|
||||
!bin/deploy_release/
|
||||
!bin/deploy_release/*.py
|
||||
!bin/do-epic
|
||||
!bin/do-epic-e2e
|
||||
!bin/do_epic/
|
||||
!bin/do_epic/*.py
|
||||
!bin/do_epic/backend/
|
||||
!bin/do_epic/backend/*.py
|
||||
!bin/do_epic/e2e/
|
||||
!bin/do_epic/e2e/*.py
|
||||
!bin/failure.py
|
||||
!bin/forge/
|
||||
!bin/forge/*.py
|
||||
!bin/git_cli/
|
||||
!bin/git_cli/*.py
|
||||
!bin/judge-replay
|
||||
@@ -43,26 +83,49 @@
|
||||
!bin/loop_claude/
|
||||
!bin/loop_claude/**/
|
||||
!bin/loop_claude/**/*.py
|
||||
!bin/loop-inbox
|
||||
!bin/loop_inbox/
|
||||
!bin/loop_inbox/*.py
|
||||
!bin/loop_effects/
|
||||
!bin/loop_effects/*.py
|
||||
!bin/loop_state/
|
||||
!bin/loop_state/*.py
|
||||
!bin/machine_load/
|
||||
!bin/machine_load/*.py
|
||||
!bin/markdown-section
|
||||
!bin/markdown_section/
|
||||
!bin/markdown_section/*.py
|
||||
!bin/metric-bench
|
||||
!bin/metric_bench/
|
||||
!bin/metric_bench/*.py
|
||||
!bin/model_routing/
|
||||
!bin/model_routing/*.py
|
||||
!bin/model_routing/routing-ladder.json
|
||||
!bin/mutate-changes
|
||||
!bin/mutate_changes/
|
||||
!bin/mutate_changes/*.py
|
||||
!bin/notifier/
|
||||
!bin/notifier/*.py
|
||||
!bin/notify
|
||||
!bin/plan/
|
||||
!bin/plan/*.py
|
||||
!bin/plan_store/
|
||||
!bin/plan_store/*.py
|
||||
!bin/project-config
|
||||
!bin/project-record
|
||||
!bin/project_config/
|
||||
!bin/project_config/*.py
|
||||
!bin/project_record/
|
||||
!bin/project_record/*.py
|
||||
!bin/rank_todo.py
|
||||
!bin/reading-cost
|
||||
!bin/reading_cost/
|
||||
!bin/reading_cost/*.py
|
||||
!bin/records/
|
||||
!bin/records/*.py
|
||||
!bin/record_store/
|
||||
!bin/record_store/*.py
|
||||
!bin/release_plan/
|
||||
!bin/release_plan/*.py
|
||||
!bin/repo_checks/
|
||||
!bin/repo_checks/*.py
|
||||
!bin/rest_client/
|
||||
!bin/rest_client/*.py
|
||||
!bin/review-replay
|
||||
!bin/review_replay/
|
||||
!bin/review_replay/*.py
|
||||
@@ -74,27 +137,59 @@
|
||||
!bin/rule_hook/
|
||||
!bin/rule_hook/*.py
|
||||
!bin/run-heavy
|
||||
!bin/run-tests
|
||||
!bin/run_heavy/
|
||||
!bin/run_heavy/*.py
|
||||
!bin/run_heavy/path_entry/
|
||||
!bin/run_heavy/path_entry/docker
|
||||
!bin/run_tests/
|
||||
!bin/run_tests/*.py
|
||||
!bin/rung_replay/
|
||||
!bin/rung_replay/*.py
|
||||
!bin/score-outcomes
|
||||
!bin/score_outcomes/
|
||||
!bin/score_outcomes/*.py
|
||||
!bin/settings_filter.py
|
||||
!bin/setup.cfg
|
||||
!bin/statusline.py
|
||||
!bin/subagent-rung
|
||||
!bin/subagent_rung/
|
||||
!bin/subagent_rung/*.py
|
||||
!bin/task-bench
|
||||
!bin/task_bench/
|
||||
!bin/task_bench/*.py
|
||||
!bin/task_bench/gather-prompt.md
|
||||
!bin/test_*.py
|
||||
!bin/text_files/
|
||||
!bin/text_files/*.py
|
||||
!bin/todo-item
|
||||
!bin/todo_item/
|
||||
!bin/todo_item/*.py
|
||||
!bin/touch-predictions
|
||||
!bin/touch_predictions/
|
||||
!bin/touch_predictions/*.py
|
||||
!bin/transcript_archive/
|
||||
!bin/transcript_archive/*.py
|
||||
!bin/wait-for
|
||||
!bin/wait_for/
|
||||
!bin/wait_for/*.py
|
||||
!docs/
|
||||
!docs/*.md
|
||||
!judge-field-trials/
|
||||
!judge-field-trials/*.py
|
||||
!judge-field-trials/README.md
|
||||
!presentation/
|
||||
!presentation/README.md
|
||||
!presentation/build-pdf.py
|
||||
!presentation/index.html
|
||||
!presentation/render-pdf.js
|
||||
!principles/
|
||||
!principles/*.md
|
||||
!reviewer-merge-trials/
|
||||
!reviewer-merge-trials/*-reviewer.md
|
||||
!reviewer-merge-trials/*.py
|
||||
!reviewer-merge-trials/README.md
|
||||
!reviewer-merge-trials/cases-*.json
|
||||
!rules/
|
||||
!rules/*.md
|
||||
!skills/
|
||||
@@ -104,10 +199,23 @@
|
||||
!skills/larv-review/*.md
|
||||
!skills/larv-review/standards/
|
||||
!skills/larv-review/standards/*.md
|
||||
!stability-skip-count/
|
||||
!stability-skip-count/README.md
|
||||
!stability-skip-count/count.py
|
||||
!workflow-bench/
|
||||
!workflow-bench/advisor-judge-prompt.md
|
||||
!workflow-bench/advisor-run-prompt.md
|
||||
!workflow-bench/advisor_bench.py
|
||||
!workflow-bench/bench.py
|
||||
!workflow-bench/compare-prompt.md
|
||||
!workflow-bench/compare.py
|
||||
!workflow-bench/handoff-brief-prompt.md
|
||||
!workflow-bench/handoff-resume-prompt.md
|
||||
!workflow-bench/handoff_bench.py
|
||||
!workflow-bench/review_git.py
|
||||
!workflow-bench/run-prompt.md
|
||||
!workflow-bench/setup.cfg
|
||||
!workflow-bench/test_advisor_bench.py
|
||||
!workflow-bench/test_bench.py
|
||||
!workflow-bench/test_handoff_bench.py
|
||||
!workflow-bench/test_review_git.py
|
||||
|
||||
@@ -1,79 +0,0 @@
|
||||
# Working here
|
||||
|
||||
Decisions live in `docs/decisions.md`:
|
||||
|
||||
- bin/: an outcome is an entry of a `.outcomes.md` file in loop-claude's archive, a record is a document tools or people keep entries in, and a place is what a comprehension seat names
|
||||
- bin/: the tools and their tests run on the host's Python, with no container
|
||||
- bin/: the tools support only the latest stable Python, and the tests, written in plain unittest, run on it in four pytest-xdist workers
|
||||
- chunks: a chunk takes every unblocked item of its release that fires the same review passes, whatever its purpose, and an item above R 5 ships alone
|
||||
- comprehension floor: every dimension and the overall at 7.0 or above is the target, and blocks no merge or release
|
||||
- deploy: `deploy-release --cut` cuts a release through a pull request merged fast-forward only, then tags the merged commit and moves `~/.claude` to it; the human runs it
|
||||
- deploy: `~/.claude` holds only a release, which `deploy-release` moves it to; this repo is developed in `~/code/claude-config`, where loop-claude runs its chunks like any project's
|
||||
- larv-review: within a chunk lifting a project towards the comprehension floor, work on the project's lowest-scoring dimension comes first, and the floor doesn't block anything
|
||||
- loop-claude: a `claude` that cannot start is a failed worker run, retried
|
||||
- loop-claude: a judge decides each interrupt and each quoted answer from the transcript, the README's premises, `AGENTS.md`, `docs/decisions.md`, `~/.claude/CLAUDE.md`, `~/.claude/rules/` and larv-review's standards, and holds a chunk open while an answer the human typed in it is recorded nowhere; it interrupts for a reserved choice those don't settle, or an ask that carries no recommendation
|
||||
- loop-claude: every claude it or loop-inbox opens on a terminal has `CLAUDE_CODE_SANDBOXED` set, so Claude Code skips its trust dialog, and neither tool writes `~/.claude.json`
|
||||
- loop-claude: each project's model lives in `~/.claude/loop-claude-models.json`, which only loop-claude writes
|
||||
- loop-claude: every claude it starts bypasses permissions inside its sandbox
|
||||
- loop-claude: one session per project, its id derived from the checkout's path relative to `~/code`, or to `/` outside it
|
||||
- loop-claude: the archive keeps the raw transcript, and a failed archive stops the loop
|
||||
- loop-claude: the worker's claude compacts its context before it fills a 200k window, at about 170k tokens, and `CLAUDE.md` → "Compact instructions" says what the summary keeps
|
||||
- loop-inbox: a loop-claude lists itself while it runs, and its waiting question, as files per session under `~/.local/state/loop-claude/`, and takes the first answer, from its terminal or from loop-inbox, that names that question
|
||||
- machine load: a heavy command waits for one of the machine's heavy slots, one for every 4 CPUs, which every session shares, and loop-claude starts a worker only while at least a quarter of the machine's memory is available
|
||||
- machine load: every container a session starts has a memory limit and a swap limit as large as its work needs; rule-hook's `docker-run-memory` blocks a `docker run` or `docker create` without them outside run-heavy, under which a container that lacks them gets the slot's share of three quarters of the memory; and no daemon-wide cap limits all containers together
|
||||
- principles: about seven things per level, four or five where they act on each other, more where a reader finds them by name; crossing a limit asks for a grouping or a recorded reason
|
||||
- reading cost and `score-outcomes`: each waits for 10 finished chunks before it shows a median
|
||||
- reading cost: a rise is the last 5 chunks' median above the 5 before them, and files or refreshes one plan item
|
||||
- reading cost: larv-review measures each finished chunk from loop-claude's archive and appends the figure to `docs/reading-cost.md` in the next chunk's PR
|
||||
- review: `/security-review` is the security pass of record, except where the full scan runs on the same change and replaces it
|
||||
- review: a comment is prose in any file; a branch changing only Markdown no agent follows runs only the prose pass and, for README or docs an outside reader lands on, the product-owner pass; plan rows a chunk files from a finding, re-scores or moves get no review
|
||||
- review: a fix for a 🔴 reruns the pass that found it, unless that pass is at its cap, and each pass whose row in `larv-review` §3's re-entry table the fix meets; from round 2 a pass reviews only the answers to its last round's findings and any other pass's fix that re-entered it; a fix for a 🟡, a 🟢, a ❓ or a prose finding reruns none
|
||||
- review: a pass gets at most two rounds per chunk, and the release review's architecture and principles passes five, with no more and no ask for more; the fixes answering a pass's last round merge once the gate passes
|
||||
- review: a pass skips only on a precedent: a decision, or a plan item crediting the pass, that the repo held before the chunk began
|
||||
- review: a project decision may opt every chunk out of the architect, the product-owner pass or the comprehension check, and a project opting out of the comprehension check voids code health
|
||||
- review: a project decision may suspend the comprehension check for the plan items it names
|
||||
- review: a release review fixes its findings in the release it reviews, and files under that release only a finding that needs a human answer, adds a feature or outlasts its five rounds
|
||||
- review: a reviewer or comprehension seat that rules the work below standard may ask to rerun once, one rung up, in the same round; the ruling that stands is an escalation trigger for the worker, never for the judge
|
||||
- review: a reviewer under `agents/` marks a 🔴 or 🟡 `[misread]` where the implementer misread code that had already shipped, each round title counts the marked findings, and `score-outcomes` lists them per chunk
|
||||
- review: an ask no user answers leaves the PR unmerged
|
||||
- review: each reviewer under `agents/` writes its full report into the chunk's review folder under `~/.local/state/larv-review/` and returns the worker its verdict and one line per finding; rule-hook refuses its Edit and MultiEdit, and any Write outside `~/.local/state/larv-review/`
|
||||
- review: stability and product-owner report only a defect, a broken requirement of the plan or the goals, a breach of a technical principle, or for stability a hard place the change touches; each architect finding names a later change the PR makes harder; prose runs only on a chunk that changes prose
|
||||
- review: the architecture and principles passes run only in the release review, a release's last chunk, which must land before the release is ready to cut; between releases the product-owner pass reviews changes to what consumers rely on
|
||||
- review: the comprehension check records how hard a project is to read and blocks no merge: a paired ruling against the last measured commit in the release review, and the four-seat scoring run, once when an item names the floor and twice on one head when a release's items run out
|
||||
- review: the premises chunk's whole review is the human's approval
|
||||
- review: the principles audit runs only in the release review, and reads the project whole with one auditor checking the goals and every principles file that applies
|
||||
- review: the stability pass mutation-tests the lines a chunk changes, in place of measuring test coverage
|
||||
- routing: a chunk's worker runs on the rung its item's L picks, below the project's rung too; its reviewers run on the highest of the worker's rung, the project's and the one picked by the highest E + I among the chunk's items, unless a replay lowered their pass or the branch changes only Markdown no agent follows, which reviews on the project's rung; the seats and the security pass always on the project's
|
||||
- routing: a review pass runs below the project's rung only on a rung that a replay of its rounds shows finding every 🔴 and 🟡 the project's rung finds, and only where the E + I steps no review up and the worker runs no higher than the project's rung, then even below the worker's; no pass has such a rung
|
||||
- routing: a worker delegates a task only where it needs just the task's conclusion, and each subagent runs on the rung its task's L picks from the project's rung, never below the project's rung when it files or scores todo.md items
|
||||
- routing: a worker hands a task one rung up on each escalation trigger, up to two rungs above the rung its item picks unless the human agrees, and opens the subagent's prompt with the trigger so the routing figures count it
|
||||
- routing: a worker whose run ends asking for a higher rung, citing an escalation trigger the judge finds in the transcript, steps one rung up as the judge interrupts or quotes an answer, or next cycle, up to two rungs above the rung its item picks
|
||||
- routing: loop-claude measures review rounds and unfinished verdicts per rung every 20 cycles, and calls for a routing change when, of two rungs with 5 or more chunks each, the lower took more of either than the one above, or when 5 or more subagents of one type had reports longer than the tool results they read
|
||||
- routing: on a model judge-replay covered, the judge runs on the rung a review would get from the highest E + I among its chunk's items, never below the project's rung
|
||||
- routing: one ladder of (model, effort) rungs, ordered by the Artificial Analysis Intelligence Index with Fable 5.1 at max on top; a task's L picks its worker's rung and its E + I its reviewers', by fixed steps counted from the cheapest rung of the project's model
|
||||
- routing: the worker changes rung only as a chunk starts, after every second unfinished verdict, or when the judge reports a taken-in item that picks a higher rung or an escalation trigger the worker cites
|
||||
- rule-hook: a PreToolUse hook enforces each rule a program can check, a `# rule-override <rule>: <reason>` marker overrides any rule but those `rule-hook --help` marks as taking none, and larv-review's overrides pass rules on each override before merge
|
||||
- rules/: `CLAUDE.md` holds the worker's rules that no file path can scope, and each topic's rules for the worker live in a `rules/` file that Claude Code loads by its `paths:` frontmatter
|
||||
- settings.json: Claude Code runs in auto mode with the dangerous-mode prompt skipped
|
||||
- settings.json: each machine owns its model, and git's clean filter `bin/settings_filter.py` keeps it, and Claude Code's key order, out of every commit
|
||||
- tests: each test earns its keep as the technical principles' test bullet says, and the worker takes a test's expected values from its item, never from the code
|
||||
- the repo may name bender, bender-infra and ai-sandbox
|
||||
- todo.md: one table of items, scored by the formula it states, held to its bar and ranked by `bin/rank_todo.py`, which ranks each blocker above the items it blocks; each achieve goal weighs by its position, code health first and four times as heavy while the comprehension panel's overall is under 7.0 or unmeasured, then README.md's goals; the table's order is the plan's only order
|
||||
- todo.md: only a session or subagent on the project's rung or above scores or reshapes the plan; one below it drafts new items and changes to filed ones for a subagent at or above that rung to apply and score, and removes finished ones
|
||||
- worker: a chunk's worker writes the simplest change that solves its item, test first wherever a test can check the change, and reads a technical principle only where the item, a finding or its own record names it; larv-review's reviewers hold the change to the principles and to the standards in `skills/larv-review/standards/`
|
||||
- workflow-bench/: the remote may show the bench cases' names and commit SHAs
|
||||
|
||||
## Working rules
|
||||
|
||||
- `routing-calls-raised.md` sits at the root of loop-claude's archive (`$LOOP_CLAUDE_TRANSCRIPTS`, default `~/.claude/loop-claude-transcripts`). Each of its lines is a call or a `Reset`, with a stamp. A call is new when it is stamped after the latest `Reset` and after the latest stamp that `todo.md` or `docs/decisions.md` → `routing:` cites. When there are new calls, file one `todo.md` item to settle them, or refresh the item already filed. Its detail quotes those calls with their stamps, and the routed-chunks table of `routing-figures.md` beside it, never the project names its other tables hold. A change to the ladder, its steps or the delegation rule is the human's. The chunk that settles the calls cites the latest stamp it settled in `docs/decisions.md` → `routing:`, whatever the human decided, so they are not filed again. Once a chunk that changes the ladder, its steps or the delegation rule has merged, append `- <UTC time> Reset` to `routing-calls-raised.md`: the figures then count only chunks finished after it, and its calls may be raised again.
|
||||
- When `~/.claude/settings.json` has uncommitted changes, carry them into `~/code/claude-config` on a branch of their own and merge them through a PR: Claude Code writes that file from any session, and `deploy-release` refuses to move `~/.claude` until a release holds them. Read their diff first: `git -C ~/.claude diff HEAD -- settings.json`. An empty diff means only the model or the key order changed, which `deploy-release` takes as no change. When the diff holds a credential, such as a token in `env` or `mcpServers`, ask the human to move it out of the file, and commit only once it is gone. A token in `env` moves to the shell profile; a server in `mcpServers` moves to `~/.claude.json` with `claude mcp add --scope user`.
|
||||
|
||||
## Scoring run
|
||||
|
||||
The project values for `skills/comprehension-panel/seat-prompts.md`:
|
||||
|
||||
- `{language}`: Python
|
||||
- `{kind}`: a Claude Code configuration with an agent loop and review skills
|
||||
- `{domain}`: driving headless Claude Code sessions, agent review workflows
|
||||
- `{domain docs}`: the Claude Code documentation
|
||||
- `{3am question}`: a loop-claude run exits 1 overnight after the judge returned a verdict the loop rejected, or a larv-review run looped a reviewer a third time
|
||||
+188
@@ -2,10 +2,198 @@
|
||||
|
||||
## Unreleased
|
||||
|
||||
- `task-bench`'s table prints the mean of the bugs' own head/base changes as its All change, in place of the change of the two All rows' medians, which swung up to three times as far in tokens. The All rows per side stay, so the change row is no longer their difference, and a change from before 0.15.1 can't be compared with one from after it.
|
||||
- `task-bench` now stops with a Failure on a run whose final result says `terminal_reason: "api_error"`, even where it holds no `api_error_status`, so a token the API refuses no longer lets the bench run on for hours with empty runs.
|
||||
- `task-bench`'s `--help` now says how far a bench of a commit against itself swings, in 19 cases of 20, with the default 5 bugs and 5 runs, and that a Gremlins run on a large project needs 16 GB of memory.
|
||||
|
||||
## 0.15.0
|
||||
|
||||
- `task-bench` writes `digest.md`, with each bug's decoys and up to two traces of its runs, and `task-bench gather` starts a claude on the project's rung that files a plan item for each place the digest shows to be hard, then removes the bench's folder. Each bench removes the folders earlier benches left, and `compress-archives` leaves lock files alone.
|
||||
- `task-bench` is new: it plants bugs that a Go project's tests catch, at the places the comprehension seats found hardest, and has Haiku fix each in a container at a base commit and at a head. It prints for each side how often the fix passes, with the median tokens, turns, wall time and reads before Haiku opens the file the bug is in. `task-bench --help` says how to run it.
|
||||
- larv-review now runs each command that a changed doc line says prints something and hands the real output to the product-owner and prose reviewers, so a claim about output is checked by running it.
|
||||
- `do-epic` moves a parent issue whose sub-tasks a person filed: to done by `jira-finish-transition` once every sub-task is done, and before that by the transition the new setting `jira-sub-tasks-landed-transition` names, once each sub-task is done or in one of `jira-unblocking-statuses`. The transition must lead to one of those statuses. `--dry-run` prints each such move.
|
||||
- mutate-changes now mutates the Go lines a branch changes with Gremlins, as it does Python, Rust, TypeScript and PHP, and prints each mutant the tests do not kill.
|
||||
- A project's config may set `epic-branch`, such as `epic-branch = "{epic}"`: do-epic then keeps one working branch per epic, level with the default branch by merge commits, and each chunk branches off it and merges into it without waiting for a person, even under `merge = "human"`. `chunk-pr open-epic` opens the finished epic's pull request into the default branch for a person to merge. `review-request-comment` names a comment `chunk-pr` posts after each push to ask a forge's reviewer for a review, and `jira-pull-request-open-status` and `jira-pull-request-merged-status` name the statuses do-epic moves an issue to as its pull request opens and merges.
|
||||
- `mutate-changes` mutates a Python script from its own folder where a test beside it imports it by its file name, as in `import run_harness`, so mutmut finds the tests' calls to it. A crash inside mutmut now becomes one report line that names mutmut's error, not a traceback, and the other folders still report.
|
||||
- do-epic starts an issue in Jira as its chunk starts: it assigns the issue to the account it works as, unless someone else holds it, and the new settings `jira-start-transition` and `jira-sprint-board` in its `config.toml` move the issue and add it to a board's active sprint.
|
||||
- Load no MCP server in the bench's headless `claude -p` judge and in the reviewer-merge trials' new-findings call either, so text an outsider wrote cannot reach one. A new check fails any Python file that passes `--tools` more often than `--strict-mcp-config`.
|
||||
- Load no MCP server in the six headless `claude -p` calls that deny the model tools, so text an outsider wrote cannot reach one.
|
||||
- `do-epic` starts an epic's runnable issues in order of score alone, not in Jira's backlog order. It scores each open issue that holds no scores, the ones people filed included, and comments on the issue why.
|
||||
- do-epic and `todo-item add` file issues as the Jira issue types the settings `jira-finding-type` and `jira-review-type` name, Task by default, and refuse before filing where the Jira project lacks the type, naming the types it has.
|
||||
- do-epic names the team's own label for each repo, from the `[label-repos]` table, when it tells a chunk's worker how to file a finding or a release review, and keeps `repo:<name>` for a repo the table doesn't name.
|
||||
- do-epic records a repo pick, and the summary of each sub-task it files, in the team's own spelling: a label from the `[label-repos]` table of its config, and a `sub-task-summary` template with `{label}` and `{Summary}`.
|
||||
- Add `do-epic <EPIC-KEY> --dry-run`, which prints every Jira write planning would make and each chunk that would start, and makes none of them.
|
||||
- The stability reviewer checks each parser that splits text on a separator or strips a suffix against a value that holds the separator, and reports a row the parse misplaces or drops.
|
||||
|
||||
## 0.14.0
|
||||
|
||||
- `loop-claude`'s judge stops, naming how much to cut the records by, rather than judge a prompt that leaves it less than the transcript's last 50,000 characters. A file the project's config names for two records is read once.
|
||||
- Under `merge = "human"`, `loop-claude` and `chunk-preflight` pass over an item whose ready pull request awaits a person's merge, and `loop-claude` stops, naming those pull requests, once every item left awaits one.
|
||||
- do-epic reads two new settings from a project's config: `jira-unblocking-statuses` names the statuses at which an issue unblocks the issues it blocks, and `jira-automation-moves-issues` leaves the move out of "In Progress" to the team's own automation.
|
||||
- The prose standard asks that a sentence about several named things holds for each of them.
|
||||
- `do-epic` resumes a chunk parked on `your merge` when its pull request no longer merges into its base, so the worker runs `chunk-pr merge` again to level the branch; a finished chunk in that state stays open until its pull request merges.
|
||||
- `larv-review prepare-scoring` takes the scoring run's project values from the checkout's `skills/comprehension-panel/seat-prompts.md` where the working-rules file holds no "Scoring run" section, not only where that file is missing.
|
||||
|
||||
## 0.13.0
|
||||
|
||||
- Fix loop-claude stopping after a finished chunk: its judge may now quote the worker's task as evidence, so the loop starts the next chunks instead of exiting.
|
||||
- Add the project setting `merge = "human"`, for a team that merges its own pull requests: `chunk-pr merge` then marks the pull request ready and leaves the merge to a person, and a do-epic chunk parks, shown as `awaits your merge`, until the pull request is merged.
|
||||
- do-epic reads a team's own repo labels: a `[label-repos]` table in `~/.claude-projects/do-epic/config.toml` maps each such label to its repo, such as `twu-4 = "tenant-web-ui-4"`, and do-epic reads a mapped label as it reads `repo:<name>`. An issue a person filed a sub-task under is no longer split by repo: its sub-tasks run instead, each under a label of its own, and the team closes the issue.
|
||||
- do-epic --file takes --blocked-by <KEY> and --parent <KEY>, so a chunk files the next pull request of a change as an issue that waits for the one before it; a chunk's first prompt says when to use them.
|
||||
|
||||
## 0.12.0
|
||||
|
||||
- loop-claude asks a headless claude whether a worker that went quiet before its result is stuck, and prints the verdict and appends it to stuck-workers.md, without killing anything.
|
||||
- loop-claude stops the background shells that hold a worker after its final result, once they have been quiet for a few minutes, and records each stop
|
||||
- Add `do-epic-e2e`, a command that runs `do-epic` end to end against a sandbox epic on a real Jira site and deletes the epic afterwards.
|
||||
- `do-epic <EPIC-KEY>` plans the epic before it starts chunks: it files a sub-task per repo under an open issue that changes several repos, labels each other unlabelled issue with where it is worked, asking on the terminal where the repo rule leaves that unclear, and puts the scored issues it filed in order of score.
|
||||
- loop-claude compacts a waiting worker's session 10 minutes before its hour-long prompt cache expires, where no answer to an interrupt has come and the context holds at least 60k tokens, so the resume doesn't write the whole context again.
|
||||
- do-epic gives a `do-epic-human` issue that blocks another its own window: it DMs you once through the notifier of one of the epic's repos, takes no running slot, and polls until you close the issue in Jira, when the issues it held up may start.
|
||||
- do-epic tells an epic chunk's worker how its repo ships the change: a bullet under the repo's changelog where the repo publishes something, none where its plan is in Jira, and no `--finish` for `chunk-pr merge`.
|
||||
- `do-epic <EPIC-KEY> --status` says which chunk asks you a question, and since when each parked chunk has awaited its gate.
|
||||
- do-epic moves a chunk's issue to done in Jira when the chunk finishes, and the split item it belongs to once its last sub-task is done, so no finished chunk starts again and the chunks it blocks start. It moves them by the transition `jira-finish-transition` and `jira-finish-status` name, so set both; without them a finishing chunk stops with that reason.
|
||||
- Describe do-epic in the README: its entry under Tools, and its machine settings and `repo-rule.md` under Set up a project.
|
||||
- do-epic finishes an epic: once none of its issues is open, a finishing chunk files a release review of each repo the epic changed, as an issue labelled `do-epic-release-review`, and asks you to confirm each goal. `do-epic <EPIC-KEY> --close-epic` then posts the summary piped in as a comment on the epic and closes it in Jira, by the transition `jira-finish-transition` names, to the status `jira-finish-status` names.
|
||||
- do-epic parks a chunk whose pull request waits on its checks, an approval or a new review: the chunk frees its place for the next one, its tmux window says what it awaits, and its worker goes on when the gate opens or a reviewer comments, even after a reboot. `do-epic <EPIC-KEY> --status` prints what each open issue does.
|
||||
- A chunk that `do-epic` runs files a finding about an epic goal as an issue of the epic, with `do-epic <EPIC-KEY> --file`, and records a decision in the epic's description, with `--record-decision`; its judge reads the epic's Scoring and Decisions before the repo's records.
|
||||
- Added `do-epic <EPIC-KEY>`: it runs the chunks of one Jira epic, each in its own window of the tmux session `epic-<EPIC-KEY>`. As many run at once as the line `**Max parallel chunks:** 2` in the epic's description allows, one without it; a repo takes as many as its `parallel-chunks`, and none while loop-claude runs chunks in it. loop-claude in turn starts no chunk in a checkout where do-epic runs one.
|
||||
- Refuse in rule-hook a Bash or Monitor command that waits forever: a sleeping loop with no time or count cap, and a `pgrep -f` or `pkill -f` whose pattern its own command line matches.
|
||||
- A project's config may list its team's convention files in `coding-conventions`, which larv-review's reviewer agents read beside the principles and the standards, the team's rule winning where they conflict. larv-review opens the pull request after its own review where a push to the branch starts CI, and files an item to add a mutation tool where `mutate-changes` covers none of a language. The technical principles gain rules for tests on a shared environment, "Never mock a service your own team runs" and "Don't loosen a type when refactoring"; stability-reviewer checks a change that stores a value differently; and every finding of an outside reviewer now changes the setup, a deterministic tool first.
|
||||
- do-epic's epic backends rank a child issue just before another, in Jira and in memory, and do-epic can re-rank Jira's backlog to an epic's ranking: it moves only the issues the loop filed, so each issue a person filed keeps its place, and it stops at the first rank Jira refuses and names it. Nothing calls it yet.
|
||||
- Comprehension seats run as the `comprehension-seat` agent under `agents/`, which starts without `CLAUDE.md` and the skill and agent listings, and `larv-review prepare-scoring` no longer takes `--preloaded`; after updating, launch each seat with `subagent_type: comprehension-seat`.
|
||||
- do-epic splits an epic item that changes several repos into one Jira sub-task per repo, each labelled `repo:<name>`, with a headless claude call predicting the repos from the code; the item is marked `split-by-repo` and counts as done once every sub-task is, and an issue a person filed gets a comment for the team in the epic's language. The epic backends gain `comment`, in the Jira backend and the in-memory one.
|
||||
- do-epic's epic backends read each issue's scores, its blockers and whether the loop filed it, in the Jira backend and the in-memory one; the Jira backend marks each issue it files as the loop's. Nothing calls it yet.
|
||||
- The technical principles now forbid a test that decides at run time whether to check anything, by a conditional skip, early return or catch around its assertions, and stability-reviewer flags one.
|
||||
- do-epic's scorer orders an epic's items by score, then by Blocked by: an item's Moves names a goal as `epic 1.1`, `code health` or `repo 2`, and the epic's achieve goals outweigh the achieve goals of every repo. Nothing calls it yet.
|
||||
- `todo-item add` and `todo-item edit --detail` refuse a detail whose `Touches:` list touch-predictions cannot read, and `rank_todo.py --check` fails on each item holding one, so rule-hook refuses a commit of such a plan: after updating, run `~/.claude/bin/rank_todo.py --check` in each project and fix each list it names.
|
||||
- loop-claude hands each worker's claude a Bash output ceiling of 6,000 characters that saves a longer result to a file, rule-hook refuses a Read of a session transcript under ~/.claude/projects, and review-replay takes --bash-ceiling and --read-limit to test such a limit against archived review rounds.
|
||||
- do-epic picks each epic item's repo, or that it is Claude's work or a human task, by repo-rule.md and a headless claude call, records the pick as a label on the issue and reads it back without a new call; where the rule leaves it unclear it returns a question for the human. The epic backends gain a label write.
|
||||
- judge-replay <model> --offline replays every archived verdict through a "?" rule, a decision table and a classifier trained on the archive, with no judge call, and counts the interrupts each misses.
|
||||
- do-epic finds an epic repo's checkout and project config by the repo's name, and clones a missing checkout from the host and owner of the epic's other repos, asking the human where they differ or the clone fails.
|
||||
- do-epic reads its machine-wide settings from ~/.claude-projects/do-epic/config.toml and its repo rule from repo-rule.md beside it, and refuses to start while either is missing or misspelt.
|
||||
- `project-record save` now writes a goals file kept as a Jira epic's description, except a change to `## Goals` or `## Audience`, which stays an edit in Jira.
|
||||
- Add do-epic's epic backend: one interface that reads a Jira epic's child issues and their sub-tasks, with labels, assignee, status and parent, and files new ones, met by a Jira backend and an in-memory fake that pass the same contract tests.
|
||||
- Fix for an outside reviewer's comment on a PR now ends with a change to the setup that would have caught it, in claude-config first, then the principles and standards, then the project.
|
||||
- larv-review reruns the pass that raised a 🟡 when the fix removes or loosens an assertion, changes an expected value, or skips, deletes or guards a test. Other 🟡 fixes still rerun no pass.
|
||||
- Add `markdown-section <file> <fragment>`, which prints the section of a markdown file under the heading the fragment picks, to the next heading of its level or a higher one. It fails, listing the headings, where several hold the fragment.
|
||||
- loop-claude and subagent-rung run an L 3 task one rung above the project's rung and an L 4 task two above it: on an Opus 5.5 project, Fable 5.2 at low and at medium.
|
||||
- Add `larv-review round-title <pass>`, which prints a review round commit's title prefix with the 🔴, 🟡 and misread counts taken from the round's report. rule-hook refuses a round commit whose counts differ from that report, where the report exists and can be counted; a report must head each finding `### 🔴` or `### 🟡`, optionally followed by ` [misread]`.
|
||||
- Add `workflow-bench/handoff_bench.py`, a bench of how a worker's step to a stronger model hands over the chunk, on six archived L 3 chunks. Sonnet 5.5 left five unfinished at its budget. On those, Opus 5.5 resuming Sonnet 5.5's session passed two and was partial on three, for a mean $0.68; a fresh session with a brief passed one and was partial on four, for $0.78. So a stepped worker still resumes its session.
|
||||
- todo-item edit --blocked-by sets the "is blocked by" links of a Jira issue the loop filed.
|
||||
- A `Touches:` list in the description of a Jira issue is read as one in `todo.md` is, a path or name that holds a backtick included: the Jira description spells it in backticks with no padding spaces, and the prediction reader takes that spelling too.
|
||||
- `todo-item edit --detail` and `project-record save` leave a Jira description or a Confluence page exactly as it is, with its block ids and spacing paragraphs, where the text saved is the text a read showed. An unedited save over a page a teammate saved since still refuses.
|
||||
- Add `compress-archives`, which gzips each transcript in loop-claude's archive and each file in the review folders 30 days after it last changed, keeping all of them. The tools that read those folders read a gzipped file by its plain name. A new crontab line in the README's Install section runs it daily.
|
||||
- review-replay and judge-replay keep each run, with its prompt, claude's exit code and stream, and the report they print, in a `replays/<tool>-<arguments>-<UTC stamp>/` folder of loop-claude's archive, so a replay that decided a rung can be checked and re-priced later; claude's json replies are now stream-json, whose last line is the reply.
|
||||
- loop-claude's archive keeps each judge run's prompt and json reply in a judge/ folder beside its chunk's transcripts, and names the run on a `Judge run:` line of the outcome it produced; judge-replay replays a verdict on its archived prompt where the archive holds one.
|
||||
- A plan kept as a Jira epic takes no changelog bullet: `todo-item finish` there needs neither `--changelog` nor `--no-changelog`, and refuses `--changelog`, since the issues' history is the changelog.
|
||||
|
||||
## 0.11.0
|
||||
|
||||
- `adf_codec.convert` can now convert ADF to markdown and back without losing a block's `localId` or the empty paragraphs Jira uses for spacing, so a Jira or Confluence document read and saved back unedited comes back identical: `markdown_to_adf_lossless`, `adf_to_markdown_lossless` and `adfs_to_markdown_lossless`. No tool calls them yet.
|
||||
- A config whose `plan` names a Jira epic must now set `jira-score-formula` and `jira-score-bar`, and fails to load without them. `todo-item add` scores the item by them, refuses one under the bar unless it is exempt, and ranks the new issue among the issues the loop filed: questions first, then security findings, then by score. A person's issues keep their rank.
|
||||
- `todo-item edit` and `move` work on a plan kept in a Jira epic. They change only an issue the loop filed, and never a link. Of an issue a person filed, `edit` sets only the scores, and posts the new `--comment` on the issue to tell the team why; a plan in a file takes the flag and keeps no comment.
|
||||
- A release someone else cut while it still held plan items no longer stops the loop: those items count as the next release's, `chunk-preflight` tells the worker to move them there, and `loop-claude` routes on them. Where the plan names no later release and `todo.md` named none since the cut, the loop still asks which release they belong to.
|
||||
- `project-record open` now writes the copy of a record kept outside a file under a folder of the worktree that ran it, `~/.local/state/project-record/<key>/<worktree>/`, so two chunks of one project no longer overwrite each other's unsaved edit. It also removes the folders of worktrees git no longer lists.
|
||||
- `chunk-pr merge` merges the chunks of one project on a machine one at a time, and `--finish <ID>` finishes each plan item in the chunk's turn, so `todo.md` and `CHANGELOG.md` no longer conflict between open chunks. A pull request that waits for an approval leaves the queue while it waits, and merge stops where a reviewer's comment waits for an answer.
|
||||
- `loop-claude` runs each chunk in its own window of one tmux session per project, `loop-<key>`, and needs tmux 3.2 or later. Up to the config's new optional `parallel-chunks` chunks run at once, 1 by default; a chunk starts beside the others only where its item's `Touches:` prediction overlaps none of theirs. `loop-claude <task>` starts the windows and attaches to the session, and as a chunk finishes, its loop starts the next. A window whose chunk waits for you ends its name in ` ?` and rings the bell, and the question's DM names the window. A stopped chunk keeps its window and its items until you run `loop-claude <task>` again. A chunk's claude session is named after its window, as `A <key> loop-claude item-372`. A commit in the config's folder now takes only the file it changed, as `git commit -m <title> -- <file>`. To upgrade, finish or stop every running loop-claude before `deploy-release` moves `~/.claude` to this release: a loop that reloads into it starts its project's windows afresh, and leaves its chunk's open claude session in the session picker.
|
||||
- `todo-item finish` finishes an item of a plan kept in a Jira epic: it moves the item's issue by the workflow transition, and to the status, that the config's new optional settings `jira-finish-transition` and `jira-finish-status` name, both as Jira shows them. It refuses a transition that leads to another status, or to one Jira doesn't count as done, and fails where the config sets neither.
|
||||
- Reviewers and loop-claude's judge read the review standards from the folder a project's config sets as `standards`, in place of `~/.claude/skills/larv-review/standards/`. The setting is required. To upgrade, add `standards = "~/.claude/skills/larv-review/standards"` to every config under `~/.claude-projects/` right after `deploy-release` moves `~/.claude` to this release, and not before.
|
||||
- A project's config may keep each of its five records on a Confluence Cloud page: set, for example, `decisions = "confluence:https://<site>/wiki/spaces/<space>/pages/<page ID>"`, with the credentials in the config's `env-file`. `decisions` and `comprehension-history` may name a page only where `plan` names a Jira epic. The loop reads and writes the page as markdown, so a save replaces a mention or a macro on it with plain text. It never overwrites a teammate's edit: where someone saved the page since the loop read it, `project-record save` refuses and the loop asks you.
|
||||
- `todo-item add` files an item into a plan kept in a Jira epic: a Task under the epic, under the project's Fix Version for the release, labelled `security` for a security finding and linked to each item that blocks it. Editing an issue still happens in Jira.
|
||||
- An item of the next release may predict the files and parts it will touch, under a `Touches:` line in its detail. `chunk-preflight` then names the items that may start chunks at once, and the new `touch-predictions record` keeps each prediction beside what the merged chunk touched, in the record a project's config places with `touch-predictions`.
|
||||
- CLAUDE.md, the todo-items rule, and loop-claude's worker and judge prompts and `--help` define the plan as a todo.md or a Jira epic, and say plan where todo.md was false for a Jira plan.
|
||||
- Reviewers without a shell read the plan from a listing that larv-review writes into the review folder, whichever store holds it.
|
||||
- A project's config may set `tooling-on-host = true`, so the loop runs a legacy project's language runtime, package manager, tests and task runner directly on the host.
|
||||
- A project's config may set `readability-floor` to a number from 1 to 10: the comprehension score under which code health is very important. It is 7.0 where left out.
|
||||
- A project whose plan is a Jira epic can keep its goals and audience in an epic's description too: set `goals-and-audience = "jira:https://<site>/browse/<KEY>"`. The loop only reads it, and `project-record open goals-and-audience` prints a file holding its text.
|
||||
- A project with a Jira plan can name each chunk's branch, worktree, commits and pull request by the issue key, as in `ABC-123` and `ABC-123 - …`. The README shows the three templates to set.
|
||||
- A read of a plan in a Jira epic converts every issue description in one `adf_codec` container run, however many issues the epic holds. The codec builds its image inside one of the machine's heavy slots that `run-heavy` shares, so sessions reading at once build it once.
|
||||
- A project config may name its plan as `jira:https://<site>/browse/<KEY>`: the plan is then read from the open child issues of that Jira Cloud epic, in backlog order, with the credentials in the config's `env-file`. Such a plan is only read so far: file, edit and finish its issues in Jira.
|
||||
- A new `adf_codec` package converts markdown to ADF, the rich text of Jira Cloud and Confluence, and back with `@larvit/adf-codec` 0.3.1. It runs in a pinned Node container with a memory limit and no network, and returns adf-codec's error codes as a `Failure`. No tool calls it yet.
|
||||
- The new `todo-item list [--release <version>]` prints the plan's items in the plan's order, `todo-item edit <ID>` sets an item's cells or detail, and `todo-item move <ID> --release <version>` moves it to another release; each change ranks the plan. Agents now read and change the plan's items only with `todo-item`, and the tools read the plan as it stands through one store, `bin/plan_store`, so a later backend can keep a plan outside `todo.md`. `todo-item list --release` with a bad version exits 2, and `finish <ID> --no-changelog` also drops an item no chunk built.
|
||||
- A project's config may name the language its prose is written in (`language`) and templates for its commit titles, pull request titles and branch names (`commit-title`, `pull-request-title`, `branch`), in which `{id}` stands for the plan item's ID and `{summary}` for the one-line summary. The tools and the prose reviewer follow them. On a branch that fits the `branch` template, rule-hook's new `commit-title` rule refuses a commit title that doesn't fit, and `chunk-pr` such a pull request title. While a project's config holds a fault, rule-hook refuses every commit there.
|
||||
- `chunk-pr merge` waits for a human's approval of the pull request where the project's config sets `wait-for-approval = true`: it merges once GitHub reports the pull request approved, and gives up after 90 minutes. It reads approvals on GitHub only. Set it for a client whose pull requests need another person's approval.
|
||||
- The technical principles ask for code in files and folders before `// --- name ---` banner comments. They also ask for an entry point a newcomer finds at once: the root holds it, the README and the files a tool reads only from there.
|
||||
- In a client project, the loop reads the team's own `CLAUDE.md` and `AGENTS.md` and proposes each change that aligns them with this setup in a pull request of its own. Where the team declines or doesn't answer, the loop follows the team's rule unless it breaks a project goal, and records the conflict as a decision in the `decisions` record.
|
||||
- The new `project-record open <record>` prints the file in which an agent reads and edits one of a project's five records (`decisions`, `score-anchors`, `comprehension-history`, `reading-cost` and `changelog`), and `project-record save <record>` stores the edit. Every tool now reads and writes a record the same one way, so that a later release can keep a record outside files. No config needs a change.
|
||||
- `loop-inbox` is gone. loop-claude now asks its questions only on its own terminal. A line typed there answers a question, and `/talk` opens the worker's session. The DM still tells you a loop waits. To upgrade, quit any `loop-inbox` still open and remove your `~/.local/bin/loop-inbox` link.
|
||||
- rule-hook's `run-heavy` rule also refuses a heavy command run through `uv run`, `poetry run`, `sudo` or `doas` outside `run-heavy`, such as `uv run mutmut run` or `sudo docker build`. Run it as `~/.claude/bin/run-heavy uv run mutmut run`.
|
||||
- rule-hook refuses a Read or a Grep of `~/.claude/.env` or of the `env-file` any project's config names, and a Bash command that names either or searches a folder holding either with `ag`, `grep -r` or `rg`, unless the tool skips the file as hidden or ignored, so that a worker doesn't put a credential in its transcript in passing. A command that hides the path, such as behind a glob or a variable, still goes through.
|
||||
- A project's config names the service for loop-claude's DMs: `notifier = "mattermost"` or `"slack"`, with the bot's token and the recipient in the `env-file`. To upgrade, move the Mattermost keys from `~/.claude/.env` into a file outside the checkout and the config's folder, such as `~/.claude-projects/<key>.env`, name it as `env-file` and add `notifier = "mattermost"`. A project with no `notifier` gets no DM, and `~/.claude/.env` is no longer read. A failure names each missing key and holds no token.
|
||||
- `mattermost-dm` is now `notify`, which sends through the project's `notifier`; `notify --help` names the keys.
|
||||
|
||||
## 0.10.1
|
||||
|
||||
- The routing ladder is now a file, `bin/model_routing/routing-ladder.json`, and a project may run on a ladder of its own: a `routing-ladder.json` in its config's folder, `~/.claude-projects/<key>/`, replaces the shipped ladder whole for that project, and loop-claude says so as each cycle starts. loop-claude, `subagent-rung` and rule-hook read the project's ladder; the routing figures, `judge-replay` and `review-replay` read the shipped one. `subagent-rung` now reads the config of the checkout it runs in, and exits 1 where that config or the ladder holds a fault; loop-claude stops on a faulty ladder as it does on a faulty config. `loop-claude --help` shows the file's shape, and README → Install → "Set up a project" says when to write one.
|
||||
|
||||
## 0.10.0
|
||||
|
||||
- The loop commits each change it makes to a file in the config's folder, such as a plan kept there, in that folder's git repo, titled as it titles its commits in the checkout. rule-hook ranks the plan on such a commit; before, it refused the commit.
|
||||
- Every tool, prompt, rule and skill reads and writes the plan, `AGENTS.md`, the records and the changelog at the paths the project's config names. A plan outside the checkout is read as it stands; the tools that need a file's commits say what they leave undone for it, and the loop goes on.
|
||||
- loop-claude, `rank_todo.py`, `todo-item` and rule-hook's `todo.md` checks now fail in a checkout no config names: write a config for each project, with `goals-and-audience = "checkout:README.md"` where its goals stay in its README. They read the goals and audience from the file that setting names, in place of `README.md`. `larv-review reviewer-header` names it on a `Goals and audience:` line, and the reviewers read it from there. A client's project can keep the file, named `goals.md`, in its config's folder, and void code health there as a README can.
|
||||
- Reviewers read the technical principles from the folder a project's config sets as `principles`, in place of `~/.claude/principles/`. `larv-review reviewer-header` names the folder on a `Technical principles:` line and fails where no config sets it, or the folder is missing or empty. Write a config for each project before its next review; a project that keeps today's principles sets `principles = "~/.claude/principles"`.
|
||||
- A project can now have a config, `~/.claude-projects/<key>/config.toml`, that names its checkout and the path of every file the loop keeps for it. `project-config` prints those paths, and fails naming each setting a config leaves out. README → Install → "Set up a project" shows how to write one. Every project needs one, as the first bullet says.
|
||||
- larv-review takes an item as a floor item only where its tagline opens with `Reach the comprehension floor:`. A tagline that quotes the floor elsewhere, such as in a decision title, no longer makes its chunk due a scoring run. Reword each open floor item's tagline in every project's `todo.md` to open with the phrase.
|
||||
|
||||
## 0.9.0
|
||||
|
||||
- larv-review skips stability round 2 where round 1 reported a 🔴 and every 🔴 and 🟡 asked only that a named mutant be killed or a named failing test pass, once the tests and the mutation command run clean on the fixes.
|
||||
- `review-replay` now qualifies a rung whose share of a pass's archived findings is no more than 10 points below the mean of two replays on the project's rung, over at least 8 rounds, where it misses no 🔴 that both found. It used to demand every finding the project's rung found again, which the project's rung itself failed. It tries the project's model at each lower effort first, then the ladder below. Its run on the prose pass of Opus 5.5 projects qualified no rung: Opus 5.5 at low effort found 49% against a bar of 66%.
|
||||
- loop-claude records beside each verdict, interrupt and quoted answer the claude-config release and commit that ran it, the tokens the worker, each subagent and the judge spent, by model and kind, with the list prices in force, and any typed answer of yours the judge quotes as reversing a choice the worker took on its own recommendation; `score-outcomes` counts those reversals per finished chunk.
|
||||
- `larv-review prepare-scoring` makes a scoring run's worktree and writes each seat's prompt; `record-scoring` removes both once it has recorded the run.
|
||||
- `deploy-release` moves a checkout whose `settings.json` differs from the release only by a `/model` pick or the key order Claude Code writes, and then says to pick the model again.
|
||||
- `chunk-pr merge` waits for the pull request's checks itself, allowing a minute for them to report, and no longer takes `--gate-passed`. `wait-for <file> [<pattern>]` waits for a line in a background job's log or report.
|
||||
- `chunk-pr sync` merges origin's default branch into the chunk's branch, unless the branch already holds it, then runs the rank check on `todo.md`.
|
||||
- `chunk-pr ready <title>` sets the pull request's final title as it marks the pull request ready.
|
||||
- `bin/run-tests` runs this repo's test suite as README.md → Test says, prints each failing test with its error and pytest's summary line, and saves the whole log to a file whose path it prints.
|
||||
- `command-patterns [<version>] --calls <file>` saves each Bash call of the release's chunks as a JSON line, with its chunk, pattern, seconds, sizes and text.
|
||||
- `todo-item show <ID>` prints an item's table row and detail from `todo.md`.
|
||||
- A reviewer under `agents/` can start without `CLAUDE.md`: `omitClaudeMd: true` in its frontmatter drops the file, a `SubagentStart` hook hands it the "Shared goal", "Prose" and "Vocabulary" sections, and `larv-review reviewer-header` names the project's principles file. `review-replay <pass> <model> --omit-claude-md` replays each round three times unchanged and once without `CLAUDE.md`, and a reviewer passes where it missed no more findings without the file than an unchanged replay missed. Five of the six reviewers pass and start without it: principles-auditor, stability-reviewer, prose-reviewer, product-owner-reviewer and systems-architect.
|
||||
- Add `workflow-bench/advisor_bench.py`, a bench of the advisor tool on six archived L 1 and L 2 chunks. Sonnet 5.5 alone passed all six, as Opus 5.5 at medium did, for 41% less, and its advisor ran in one of six runs, so workers stay without it.
|
||||
- loop-claude's judge on an Opus 5.5 project now runs on Opus 5.5 at xhigh in every chunk, never at medium: in replays medium sometimes closed a chunk whose worker had asked a question the README or records answer, where xhigh quoted the answer. The judge never runs on Fable 5.2 either, since each Fable 5.2 rung replayed missed an interrupt. `judge-replay` now also replays each rung above the project's that a review climbs to, and reports what each misses.
|
||||
|
||||
## 0.8.0
|
||||
|
||||
- The routing ladder now tops out at Fable 5.2, ordered by the Artificial Analysis Intelligence Index read 2026-11-11: Sonnet 5.5 at high, Opus 5.5 at medium, Fable 5.2 at low and medium, Opus 5.5 at xhigh, Fable 5.2 at high and max. On an Opus 5.5 project, L 4 workers, E + I 5 reviews and a worker's first escalation now run on Fable 5.2 at low, where they ran on Opus 5.5 at high; E + I 6 reviews on Fable 5.2 at medium, where they ran on Opus 5.5 at xhigh; E + I 7 on Opus 5.5 at xhigh, where they ran on Opus 5.5 at max; and E + I 8 on Fable 5.2 at high, where they ran on Fable 5.1 at max. On a Sonnet 5.5 project, E + I 6, 7 and 8 reviews now run on Fable 5.2 at low, Fable 5.2 at medium and Opus 5.5 at xhigh, where they ran on Opus 5.5 at high, xhigh and max. The judge climbs with the reviews. A Fable 5.2 project starts on Fable 5.2 at low. Update `~/.claude` while no loop is mid-chunk: a chunk that stepped up to Opus 5.5 at high or max, or Fable 5.1 at max, finds its rung gone and restarts on its item's rung.
|
||||
- loop-claude now sends you a Mattermost DM from a bot for each question it asks, each release ready to cut, each routing call and each stop but Ctrl-C, where `~/.claude/.env` names the server, the bot's token and your username. `bin/mattermost-dm` sends one by hand; `mattermost-dm --help` names the keys. A DM that fails is one line on loop-claude's terminal, and the loop goes on.
|
||||
- larv-review's worker now runs the project's tests and static analysis, and checks the docs for each name its change touches, before each stability round, and hands stability-reviewer the commit that passed; the reviewer doesn't run them again on it.
|
||||
- stability-reviewer, product-owner-reviewer and systems-architect have one-line descriptions, which shrinks the agent listing every session carries.
|
||||
- `mutate-changes` mutation-tests the lines a branch changes, running cargo-mutants, Infection, mutmut or Stryker by each file's language, and prints each mutant that no test kills. Where a project's README documents no mutation command of its own, larv-review now runs it before each stability round and hands stability-reviewer the mutants that survive.
|
||||
- loop-claude now asks each worker to name the items its chunk takes on one line, as in `Chunk items: 12 (L 3, E + I 5), 14 (L 2, E + I 4)`, and scores them from `todo.md` on the default branch. That line, not the judge, now sets the items loop-inbox lists, and how far an item beyond the one the chunk was routed on lifts the worker, its reviewers and the judge. The judge still reports escalations and whether a release is ready to cut.
|
||||
- `~/.claude` holds no `AGENTS.md` any more, so each session in your projects starts about 3,600 tokens smaller, and a session in `~/code/claude-config` loads its `CLAUDE.md` once instead of twice.
|
||||
- A project's `AGENTS.md` may group decision titles into project principles, and each new decision is checked against them: a principle covers it, it breaks one, or it suggests a new one for you to approve.
|
||||
- The prose reviewer now holds prose to the negation rule: write `doesn't cost anything`, never `costs nothing`, after any verb or its preposition.
|
||||
- `rule-hook` now checks files at `git commit`: each file that differs from HEAD or is untracked and not ignored, even one the commit leaves out. It holds each to `action-pin`, `image-pin`, `ignorefile-sorted` and `no-ai-attribution`, so a file a Bash command wrote is checked as an Edit or Write is. A `# rule-override` line in the file or the command overrides a breach.
|
||||
- `chunk-pr merge` now refuses while a scoring run the plan calls is unrecorded on the branch, and `larv-review needs-scoring-run` calls one after a release is cut with none.
|
||||
|
||||
## 0.7.0
|
||||
|
||||
- README's test, CI and mutation-test commands now have their own section, README → Test.
|
||||
- `rule-hook overrides` now lists the chunk's overrides when a file or folder shares the branch's name. It used to exit saying it could not read the reflog.
|
||||
- `chunk-pr clean` removes a merged chunk's worktree and local branch and fast-forwards the main checkout. It leaves a main checkout with uncommitted files, another branch or commits of its own as it was, and says why.
|
||||
- `review-replay` now replays each round at the commit with the newest author time at or before the round's time, and takes the clone's base the same way by the time the chunk began. It took the first such commit in log order, so a commit authored early but merged late, such as a dependency bump, could win over the commits the round reviewed.
|
||||
- The shared goal every project pursues, code health, now asks that code stay easy to read, change safely and debug, tomorrow and after seven years of development.
|
||||
- `rank_todo.py` now lets an item that adds a test, a gate leg or a probe name the maintain goal it guards, by how much more confident the project becomes that the goal holds, 1 to 10. Each point is worth 0.5.
|
||||
- `chunk-preflight` now quotes the detail of each item that may join the chunk, so a worker no longer opens `todo.md` to read it.
|
||||
- `command-patterns [<version>]` prints a table of the shell command patterns a release's chunks ran.
|
||||
- `deploy-release --cut` reports each step as it finishes, waits for the checks `main`'s protection requires and names them, deletes the merged release branch, and ends on one line saying the release is cut.
|
||||
- CI runs the test suite on every pull request, and `main` merges nothing until it passes.
|
||||
- `larv-review reviewer-header <pass> [--rerun]` writes the branch diff and the places into the chunk's review folder and prints the header of a reviewer's prompt: the pass, its next round, the PR, the worktree, the branch, the merge base of HEAD and the default branch, and the paths of the report, the diff and the places.
|
||||
- `chunk-pr open|ready|merge` opens a chunk's pull request as a draft, marks it ready and merges it, with `gh` or `tea` as the remote needs. It merges only with `--gate-passed`, by the first merge method the repository allows. `larv-review` and `CLAUDE.md` now tell workers to use it.
|
||||
- `score-outcomes` now gives, where most of the chunks it counts for L hold no 🔴, the share of chunks with a 🔴 at each L in place of L's rank correlation by 🔴 findings.
|
||||
- `todo-item add` now files an item in `todo.md` with one command. It takes `Next ID` as the item's ID, raises `Next ID`, writes the row and the detail it reads from stdin, and ranks the file.
|
||||
- `todo-item finish <ID>` now removes a finished item's row and detail from `todo.md`. With `--changelog <bullet>`, it also adds that bullet first under `CHANGELOG.md` → `## Unreleased`. Where a `CHANGELOG.md` exists, it refuses to run without `--changelog <bullet>` or `--no-changelog`, so no bullet is left out by mistake.
|
||||
- A worker whose review rules its work below standard now fixes it on its own rung where the fix changes only prose, a comment or docstring included. It hands the fix to a higher rung only where code, config or tests change.
|
||||
- `loop-claude`'s judge now sends a question you answered earlier in the chunk back to the worker, quoting your answer, unless the question ends with the words of your answer that leave it open. You are asked only about what your answer left open.
|
||||
- `score-outcomes` now shows, beside what each finished item's chunk measured, the size of the files and folders its tagline or detail names in backticks: how many files, and how many lines, as they stood before its chunk.
|
||||
- `workflow-bench/bench.py` now prints a failed run, such as a failed clone, as a `<run>: FAILED: …` line beside the other runs' results, in place of stopping at the first failure.
|
||||
- A scoring run under the comprehension floor of 7.0 now leaves a plan item meant to reach it. `larv-review record-scoring` follows its `Floor:` line with a `Next:` line. It says to file one ambitious refactor aimed at the lowest dimension, or to refresh the one `todo.md` already holds. The item's tagline holds `comprehension floor`, so its own chunk runs a scoring run. It goes into the release after the chunk's, so the floor doesn't hold up any release (larv-review §3 → "Floor item"). An item already in `todo.md` whose tagline holds those words counts as the open one: drop or reword it if it isn't such a refactor.
|
||||
- `loop-claude` now interrupts you less. A worker takes its own recommendation on a choice no rule reserves for you, and records it, and the judge answers an ask that carries a recommendation by quoting the rule that says so. You are still asked about a goal, a release's planned items and its cut, a change to the routing ladder, and whatever another rule asks your approval for; `CLAUDE.md` → "Working loop", "Ask, don't guess" lists them.
|
||||
- This setup's own plan now ranks items by `Score = 100 * V / (2**S + 32)`, up from 8: F, a chunk's fixed cost, is 32, about one size-5 change, fitted to ten finished chunks' tokens, so small items rank lower against large ones. `docs/decisions.md` holds the fit.
|
||||
- `loop-claude` now keeps the cycle it last measured the routing figures at, and each routing call it raised, in `routing-state.json` at the archive's root, and reads them back from there in place of `routing-figures.md` and `routing-calls-raised.md`. The two markdown files hold what they held before. From them, loop-claude now reads only a `Reset` line in `routing-calls-raised.md`, which still resets the figures. The first loop to close a cycle after the upgrade measures the figures at once. If the figures still make a call raised since the latest reset, it puts that call to you once more.
|
||||
- `loop-claude` and the routing figures no longer read a `Worker:` line written as a sentence, as versions before 0.4.0 archived. A rerun routes a chunk whose archive still ends in one afresh, and the figures leave it out of the routed chunks and charge its dollars to a row named by the sentence.
|
||||
- `score-outcomes` no longer credits a chunk's measurements to an item the chunk removed from `todo.md` without building it. Remove such an item in a commit whose title opens `Drop item 69: <why>`, or `Drop items 69, 70 and 71: <why>`, and `score-outcomes` leaves it out. Items dropped before this release still count as shipped.
|
||||
- rule-hook's `todo-rank-check` now checks a branch of this setup's repo with that branch's own `bin/rank_todo.py`, so a branch that changes `todo.md`'s shape commits without an override. Any other repo is still checked with `~/.claude`'s.
|
||||
|
||||
## 0.6.0
|
||||
|
||||
|
||||
@@ -2,30 +2,39 @@
|
||||
|
||||
## Working loop
|
||||
|
||||
How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The *next release* is the earliest one not yet cut. Other words, such as *chunk*, are defined under "Vocabulary" at the end of this file.
|
||||
How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The *next release* is the earliest one not yet cut. A rule names a project's files by their usual paths: `todo.md`, `AGENTS.md`, `CHANGELOG.md` and the files under `docs/`. Each is where the project's config puts it, which `~/.claude/bin/project-config` prints and `chunk-preflight`'s facts quote. Where the config names a Jira epic as the plan, the plan is the epic's open child issues. Read and edit a project record in the file `~/.claude/bin/project-record open <record>` prints, and run `project-record save <record>` after each edit. Other words, such as *chunk*, are defined under "Vocabulary" at the end of this file.
|
||||
|
||||
- **Until `README.md` has a `## Goals` and an `## Audience` section, writing them is the only work.** Not even planning in `todo.md`. Both are public: an outside reader judges a project by where it is heading and who it is for. Goals or an audience written anywhere else, such as `AGENTS.md` or `docs/`, do not count; the one exception is code health, which "Shared goal" below states for every project.
|
||||
- **Plan `todo.md` as one scored table, in the shape whose example `~/.claude/bin/rank_todo.py --help` shows**: every item names the release that ships it. Until `todo.md` has that shape, reshaping it is the only work, and the human approves it.
|
||||
- **Until the goals file has a `## Goals` and an `## Audience` section, writing them is the only work.** Not even planning. In a README both are public: an outside reader judges a project by where it is heading and who it is for. Goals or an audience written anywhere else, such as `AGENTS.md` or `docs/`, do not count; the one exception is code health, which "Shared goal" below states for every project.
|
||||
- **Keep a plan in `todo.md` as one scored table, in the shape whose example `~/.claude/bin/rank_todo.py --help` shows**: every item names the release that ships it. Until `todo.md` has that shape, reshaping it is the only work, and the human approves it.
|
||||
- **Read and change the plan's items only with `~/.claude/bin/todo-item`**, which lists, shows, files, edits, moves and finishes them; `todo-item --help` says how. It reads a plan in Jira as it does a file. There it edits and moves only an issue the loop filed; of an issue a person filed it sets only the scores, with `--comment` telling the team why. Two open the file itself: whoever plans a release, to compare Scores across releases, which `todo-item list` doesn't print; and whoever edits `## Scoring` or `## Renamed`, or reshapes an old table.
|
||||
- **When the next release has no items and no work has landed towards it, plan it as this chunk.** Move the highest-scoring items of later releases into it, and get the human's approval of that set before writing any code.
|
||||
- **When the next release has no items left and work has landed towards it, its release review is the chunk** (`larv-review` §3 → "Release review"). **Once that has merged and the release holds no item, the release is finished: stop.** Report what it holds and that it is ready to cut. Under `/loop`, this ends the loop. Until the human cuts it, only a security fix, or an item its release review filed, lands, into that release; never start a later release's items or plan a new one.
|
||||
- **Open every chunk with one line:** the last version cut, how many changes are unreleased (the entries under `CHANGELOG.md` → `## Unreleased`, or else the commits since the last tag), and the release this chunk ships into. A repo that publishes nothing says so once.
|
||||
- **Read the README's `## Goals` and `## Audience` before starting a chunk, unless your prompt quotes them.** The chunk's items set its scope. The goals choose between ways to deliver those items, and never add to them.
|
||||
- **Read the plan and the decisions only as far as the chunk needs.** Where your prompt quotes `chunk-preflight`'s facts, they hold the next item's L, E + I, tagline and detail, and the items that may join it; read further only what they leave out. Otherwise run `grep -n '^## Details' todo.md`, then read `todo.md` with the Read tool up to the line it prints, or whole when it prints none. Then read the details of only the items the chunk takes. `AGENTS.md` lists every decision's title. Read the entry under a title in `docs/decisions.md` only where the title leaves open what the chunk or the review needs.
|
||||
- **Work one chunk at a time, and put every item that can share its review into it.** Every review has a fixed cost, so a chunk takes the next plan item plus every other item for which three things hold: they name one release; they fire the same review passes (`larv-review` §3); and no item outside the chunk blocks one of them. The items need not share a purpose. An item whose risk R, in `todo.md`, is above 5 ships alone: it joins no chunk, and none joins it. The next plan item is the first that does not wait: an item waits while it is marked `question`, until the human answers, or while an item that blocks it is still in the plan. Tiny items, a few lines of change each, need not fire the same passes: bundle up to ten that name one release, and that no item outside the chunk blocks, into one chunk. Split a milestone into items in `todo.md` before starting it. Fix a finding in the chunk's own change within the chunk. File a finding about anything else in `todo.md`.
|
||||
- **Ask, don't guess.** Three choices are always the human's: a goal; a release, meaning the items planned into it and when it is cut; and a change to loop-claude's routing ladder, its rungs included. Any other rule that asks the human's approval reserves that choice too. Ask about a reserved choice. For any other choice, first check whether the goals already answer it. If they nearly do, propose a change to the goals and show how it answers this case: an answer settles one question, a goal settles every question like it. Otherwise take the option you would recommend, and record it with its reason: in the item's detail, or, where it governs later work, as the next sentence says. A recommendation you can give a reason for is not a guess. Ask only where you have no recommendation. Write every answer once, where it belongs, never only in chat: a goal in `README.md`, a working rule in `AGENTS.md`, a standing choice in a comment at the one place it governs, or in `docs/decisions.md` once made in more than one place. When an answer holds a goal and a choice, write the goal in the README, and record as a choice only what the goal leaves open.
|
||||
- **Bench a syntax with the people who write it.** Before a new or changed spelling of something users read or write ships — markdown, HTML, a config key, a CLI flag — a panel of fresh-context readers, seated as those users from the README's `## Audience`, picks it.
|
||||
- **Implement the simplest change that solves the item, and ship it with `/larv-review`.** Whenever a test can check the change, write that test first and see it fail. Take its expected values from the item, never from the code. larv-review's reviewers hold the change to the technical principles, and a finding against one names it. Read a file under `~/.claude/principles/` only when the item changes it, a finding or a record you write names it, or you decline a finding.
|
||||
- **Remove a finished item's row and detail from `todo.md`, and revise any decision that cites it.** If the repo publishes something others consume — a package, an image, an API — reword the item for them and move it to `CHANGELOG.md` under `## Unreleased`. A changelog is for the public, never for the next agent. Otherwise delete it; git history is the record.
|
||||
- **Where someone cut a release that still holds items, those items are the next release's.** Move them there as the chunk's first change and say so in its opening line; where `todo-item` cannot move an item, such as an issue a person filed in a Jira plan, ask the human in the chunk's summary to move it. Where the plan names no later release, ask the human which one they belong to.
|
||||
- **Open every chunk with one line:** the last version cut, how many changes are unreleased (the entries under `CHANGELOG.md` → `## Unreleased`, or else the commits since the last tag), and the release this chunk ships into. A repo that doesn't publish anything says so once.
|
||||
- **A client project's `CLAUDE.md` and `AGENTS.md` in its repo belong to its team.** Read both at the start of each chunk there. Propose each change that aligns them with this setup in a pull request of its own, never inside a chunk's; the one edit a chunk makes there is a decision's title in `AGENTS.md`. Until the team accepts a proposal, and after it declines or doesn't answer, follow the team's rule unless it breaks one of the project's goals. Record each such conflict as a decision in the `decisions` record, as `rules/decisions.md` asks: which rule you follow, why, and the open proposal's PR. Then nobody is asked twice.
|
||||
- **Read the goals file's `## Goals` and `## Audience` before starting a chunk, unless your prompt quotes them.** The chunk's items set its scope. The goals choose between ways to deliver those items, and never add to them.
|
||||
- **Read the plan and the decisions only as far as the chunk needs.** Where your prompt quotes `chunk-preflight`'s facts, they hold the next item's L, E + I, tagline and detail, and each item that may join it with its L, E + I, S, tagline and detail; run `todo-item` only for what they leave out. Otherwise run `~/.claude/bin/todo-item list`, which prints every item's row in the plan's order, without details. Then read the details of only the items the chunk takes, with `~/.claude/bin/todo-item show <ID>`, which prints an item's row and detail. `AGENTS.md` lists the project principles and the title of each decision no project principle covers. Read an entry in `docs/decisions.md` only where the project principle or the title leaves open what the chunk or the review needs. Print one entry with `~/.claude/bin/markdown-section <file> <fragment of its title>`, where `<file>` is what `~/.claude/bin/project-record open decisions` prints.
|
||||
- **Work one chunk at a time, and put every item that can share its review into it.** Every review has a fixed cost, so a chunk takes the next plan item plus every other item for which three things hold: they name one release; they fire the same review passes (`larv-review` §3); and no item outside the chunk blocks one of them. The items need not share a purpose. An item whose risk R, in the plan, is above 5 ships alone: it joins no chunk, and none joins it. The next plan item is the first that does not wait: an item waits while it is marked `question`, until the human answers, or while an item that blocks it is still in the plan. Tiny items, a few lines of change each, need not fire the same passes: bundle up to ten that name one release, and that no item outside the chunk blocks, into one chunk. Split a milestone into items in the plan before starting it. Fix a finding in the chunk's own change within the chunk. File a finding about anything else in `todo.md`.
|
||||
- **Ask, don't guess.** Three choices are always the human's: a goal; a release, meaning the items planned into it and when it is cut; and a change to loop-claude's routing ladder, its rungs included. Any other rule that asks the human's approval reserves that choice too. Ask about a reserved choice. For any other choice, first check whether the goals already answer it. If they nearly do, propose a change to the goals and show how it answers this case: an answer settles one question, a goal settles every question like it. Otherwise take the option you would recommend, and record it with its reason: in the item's detail, or, where it governs later work, as the next sentence says. A recommendation you can give a reason for is not a guess. Ask only where you have no recommendation. Write every answer once, where it belongs, never only in chat: a goal in the goals file, a working rule in `AGENTS.md`, a standing choice in a comment at the one place it governs, or in `docs/decisions.md` once made in more than one place. When an answer holds a goal and a choice, write the goal in the goals file, and record as a choice only what the goal leaves open.
|
||||
- **Bench a syntax with the people who write it.** Before a new or changed spelling of something users read or write ships — markdown, HTML, a config key, a CLI flag — a panel of fresh-context readers, seated as those users from the goals file's `## Audience`, picks it.
|
||||
- **Implement the simplest change that solves the item, and ship it with `/larv-review`.** Whenever a test can check the change, write that test first and see it fail. Take its expected values from the item, never from the code. larv-review's reviewers hold the change to the technical principles, and a finding against one names it. Read a file in the principles folder the project's config sets (`~/.claude/bin/project-config principles` prints it) only when the item changes it, a finding or a record you write names it, or you decline a finding.
|
||||
- **Change the setup for each finding an outside reviewer raises on a PR, deterministic tools first.** An outside reviewer is a forge's auto-reviewer or a human, not one of larv-review's reviewer agents. For each finding of theirs, whether you fix it or decline it, ask why our review didn't raise it first, and change the setup so it would; a fix that only answers the comment leaves the same gap open for the next chunk. Put the change in the first place that fits:
|
||||
1. A deterministic tool that would have caught it, such as a rule-hook rule, a gate check, a linter setting or `mutate-changes`: a tool catches the fault every time, and a reviewer only when it notices.
|
||||
2. A technical principle or a review standard, where a rule was missing or too vague: in claude-config's files, or in the project's own principles folder.
|
||||
3. Anything else: the reviewers' agents, `larv-review`'s text, or the project's own settings or `AGENTS.md`. A client repo's `AGENTS.md` changes by a proposal of its own, per "A client project's `CLAUDE.md` and `AGENTS.md`" above.
|
||||
|
||||
Change claude-config's files where every project gains, and the project's own only where the gap is that project's alone. In claude-config, the change is a fix of the chunk. In another project, a change to the project's own files is a fix of the chunk too, and a change to claude-config's is an item in claude-config's plan: start a worktree of claude-config off `origin/main`, run `todo-item add` in it, commit the plan file, and ship it as a pull request of its own with `chunk-pr`, since claude-config's default branch may not take a direct push. Describe the gap without the client's name, code or comment text. File a change too big for the chunk as its own item. Where no setup gap caused the finding, as when the finding is wrong, say so in the chunk's summary rather than inventing a change.
|
||||
- **Remove a finished item from the plan, and revise any decision that cites it.** If the repo publishes something others consume — a package, an image, an API — reword the item for them and move it to `CHANGELOG.md` under `## Unreleased`. A changelog is for the public, never for the next agent. Otherwise delete it; git history is the record. `~/.claude/bin/todo-item finish <ID>` removes the item with its detail, and adds the bullet you pass with `--changelog <bullet>`; it refuses while a decision cites the item. A plan kept in Jira takes no bullet, since the issues' history is its changelog: `finish` there refuses `--changelog`. A chunk finishes its items as it merges, through `chunk-pr merge --finish <ID>`, which takes the same flags (`larv-review` §5).
|
||||
- **Releases are the human's.** The version bump and the publishing credentials are theirs, whatever another rule says. Prepare everything else, so cutting a release is one decision.
|
||||
- **Open each `todo.md` item or ticket with a bold one-sentence tagline**, so the taglines alone say what a release holds. The tagline states the target state, checkable when done: an imperative verb plus what holds afterwards. A present-tense fact reads as the current state and says nothing about what to do. Add "today X" only where the direction is otherwise ambiguous. GOOD: `**Accept undefined in MetadataValue and drop such keys on output.**` BANNED: `MetadataValue accepts undefined; such keys are dropped on output`.
|
||||
- **Open each plan item or ticket with a bold one-sentence tagline**, so the taglines alone say what a release holds. The tagline states the target state, checkable when done: an imperative verb plus what holds afterwards. A present-tense fact reads as the current state and doesn't say anything about what to do. Add "today X" only where the direction is otherwise ambiguous. GOOD: `**Accept undefined in MetadataValue and drop such keys on output.**` BANNED: `MetadataValue accepts undefined; such keys are dropped on output`.
|
||||
- **File a security finding the moment it is found.** A security finding — a leaked credential, secret or PII, an auth bypass, an injection — goes under the next release, marked `security`, naming the exposure and the path it reaches. `~/.claude/bin/rank_todo.py` ranks it first in its release, after only the open questions, which wait for me. Never among additive or nice-to-have items, never only in a chunk's summary, and never as a question about where it belongs: file it, say you did, and I will unmark it if I disagree. Fixing it inside an unrelated change is a separate call — say whether it is in the blast radius.
|
||||
|
||||
## Shared goal
|
||||
|
||||
Every project pursues the achieve goal below, ranked above every achieve goal its README states. A project whose code nobody will maintain voids it with one line under `## Goals`, before the numbered goals: `**Void:** code health, since <reason>.` So does a project that opts out of the comprehension check, since the goal then has no signal. An item's Moves cell names it as in `code health by 6`, and `rank_todo.py --help` says how much it weighs.
|
||||
Every project pursues the achieve goal below, ranked above every achieve goal its goals file states. A project whose code nobody will maintain voids it with one line under `## Goals`, before the numbered goals: `**Void:** code health, since <reason>.` So does a project that opts out of the comprehension check, since the goal then has no signal. An item's Moves cell names it as in `code health by 6`, and `rank_todo.py --help` says how much it weighs.
|
||||
|
||||
**Achieve:** Code health: the code is easy to understand and change safely.
|
||||
- Signal: the comprehension panel's overall score rises, always. Under 7.0 it is very important.
|
||||
**Achieve:** Code health: the code stays easy to read, change safely and debug, tomorrow and after seven years of development.
|
||||
- Signal: the comprehension panel's overall score rises, always. Under the project's readability floor it is very important. The floor is 7.0, unless the project's config sets `readability-floor`.
|
||||
- Counter-signal: defects keep reappearing in functionality that already shipped, or reviewers raise blockers because the implementer misunderstood the current system.
|
||||
- Why: a score that rises while changes still misread the code measures the wrong thing.
|
||||
|
||||
@@ -33,7 +42,7 @@ Fewer items shipped per release is a price this goal accepts, not a counter-sign
|
||||
|
||||
## Prose
|
||||
|
||||
Everything written — chat, commit messages, comments, docs, code — is in **English**. Prose meets four priorities, in this order. When two pull against each other, the higher one wins.
|
||||
Everything written — chat, commit messages, comments, docs, code — is in **English**. Where a project's config names another `language`, which `~/.claude/bin/project-config language` prints, the prose that project's readers see is in that language instead: its docs, comments, commit messages, pull requests and tracker text. These stay English: chat, names in code, a reviewer's report, and what a tool reads, which is the fixed words of a title, such as `Answer <pass> round <n>:`, `todo.md`'s table, and a record's headings, such as `## Unreleased`. Prose meets four priorities, in this order. When two pull against each other, the higher one wins.
|
||||
|
||||
1. **Easy to understand.** A reader with little time gets it on one read: one idea per sentence, and each term explained before it is used.
|
||||
2. **Most important first**, judged by what the reader wants to know first.
|
||||
@@ -42,9 +51,9 @@ Everything written — chat, commit messages, comments, docs, code — is in **E
|
||||
|
||||
Write the thing, not an introduction to it. State what holds and stop; name a rejected alternative only where that stops a reader choosing it.
|
||||
|
||||
Write negations as people say them. BANNED: `stops nothing`, `changes nothing`, `reveals nothing`, `depends on no one`. GOOD: `doesn't stop anything`, `doesn't change anything`, `doesn't reveal anything`, `doesn't depend on anyone`.
|
||||
Write negations as people say them: after a verb, or after its preposition, write `doesn't <verb> anything` or `anyone`, never `<verb> nothing` or `no one`. BANNED: `stops nothing`, `depends on no one`, `so answering in time costs nothing`. GOOD: `doesn't stop anything`, `doesn't depend on anyone`, `so answering in time doesn't cost anything`.
|
||||
|
||||
Reviewers hold prose to the full rules, with examples: `~/.claude/skills/larv-review/standards/prose.md`.
|
||||
Reviewers hold prose to the full rules, with examples: `prose.md` in the project's review standards, which "Topic rules" below defines.
|
||||
|
||||
## Public API specs
|
||||
- Text in public API specs (OpenAPI `description`/`title` fields, in a spec file or in code, and the generated api-docs) is read by external consumers. Never leak internal references: no ticket IDs, internal URLs, repo/system code-names, "see ticket X". Describe behaviour in consumer terms. GOOD: `Deprecated alias for paymentAccountId`. BANNED: `…will be removed (ABC-123)`.
|
||||
@@ -55,33 +64,33 @@ Reviewers hold prose to the full rules, with examples: `~/.claude/skills/larv-re
|
||||
Claude Code loads a rule file when a session writes a file its `paths:` frontmatter matches, or reads one with the Read tool or `head -n`, never `sed`. After a write, it loads only once the write is done. Read a rule file before you create a file it covers.
|
||||
|
||||
- The decision log: `~/.claude/rules/decisions.md`.
|
||||
- README goals and audience: `~/.claude/rules/goals-and-audience.md`.
|
||||
- `todo.md` items, their scores and Exempt reasons: `~/.claude/rules/todo-items.md`.
|
||||
- Goals and audience: `~/.claude/rules/goals-and-audience.md`.
|
||||
- Plan items, their scores and Exempt reasons: `~/.claude/rules/todo-items.md`. Read it before you file, score, edit or move an item: a session that runs `todo-item` never opens `todo.md` itself, so the rule doesn't load.
|
||||
|
||||
The rules only reviewers apply, for quality, comments, READMEs and prose, live in `~/.claude/skills/larv-review/standards/`.
|
||||
The rules only reviewers apply, for quality, comments, READMEs and prose, are the project's review standards: the folder its config sets as `standards`, which `~/.claude/bin/project-config standards` prints.
|
||||
|
||||
## Working with the codebase
|
||||
- Always start a new git worktree when doing something in a codebase, and clean it up when done. Unless told otherwise, branch it off a freshly-updated default branch (`git fetch origin`, then base on `origin/main`), not whatever happens to be checked out.
|
||||
- Keep the project's main checkout (e.g. `~/code/log`, never a worktree) current: when it is behind `origin` — a merge landed, or a fetch shows it — run `git pull --ff-only` there instead of reporting the lag, never with `--autostash`: a dirty checkout is a finding to report, not to carry along.
|
||||
- Run a project's language runtime, package manager, and task runner through its container/tooling setup, never directly on the host unless a decision puts them there. Example: `docker compose run --rm app <tool> …`.
|
||||
- Run a project's language runtime, package manager, and task runner through its container/tooling setup, never directly on the host, unless the project's config sets `tooling-on-host = true` or a decision puts them there. Example: `docker compose run --rm app <tool> …`.
|
||||
- Tear down test containers after a run.
|
||||
- Give every container you start a memory limit and a swap limit, as large as its work needs: `--memory 4g --memory-swap 4g` on `docker run`, or `mem_limit` and `memswap_limit` in a compose file, scripts included. rule-hook checks only the `docker run` and `docker create` in your Bash commands.
|
||||
- A heavy command loads the machine for minutes: a full gate, mutation tests, an e2e run, a `docker build`. Run each one under `~/.claude/bin/run-heavy`, as in `~/.claude/bin/run-heavy ./ci.sh`. run-heavy waits for one of the heavy slots that every session on the machine shares. It also caps each container the command makes at the slot's share of memory, where the container sets no limits; give a container that needs more its own. Run it in the background, since the wait can outlast the Bash tool's timeout.
|
||||
- Delegate a task to a subagent only when you need just its conclusion: a search or read across many files, or work independent enough to run in parallel. Keep edits, and whatever you must check line by line, in your own thread: you would read a delegated diff again to check it. Score the task's L as for a `todo.md` item; a task that changes no file, such as a search, is L 1. `<model>` below is the project's model id, such as `claude-opus-5-5`: the one loop-claude's prompt names as the project's, or else your own. Launch the subagent with the model and effort of the first case that fits:
|
||||
- A heavy command loads the machine for minutes: a full gate, mutation tests, an e2e run, a `docker build`. Run each one under `~/.claude/bin/run-heavy`, as in `~/.claude/bin/run-heavy ./ci.sh`. run-heavy waits for one of the heavy slots that every session on the machine shares. It also caps each container the command makes at the slot's share of memory, where the container sets no limits; give a container that needs more its own. Run the command in the background, since run-heavy's wait can outlast the Bash tool's timeout; `~/.claude/bin/wait-for <file> [<pattern>]` waits for a line in a log the command writes.
|
||||
- Delegate a task to a subagent only when you need just its conclusion: a search or read across many files, or work independent enough to run in parallel. Keep edits, and whatever you must check line by line, in your own thread: you would read a delegated diff again to check it. Score the task's L as for a plan item; a task that changes no file, such as a search, is L 1. `<model>` below is the project's model id, such as `claude-opus-5-5`: the one loop-claude's prompt names as the project's, or else your own. Launch the subagent with the model and effort of the first case that fits:
|
||||
1. A reviewer, a comprehension seat or the security pass: those loop-claude's prompt gives it. Given none, pass no model or effort, so it runs on your model.
|
||||
2. An escalated task, below: the rung loop-claude's prompt names for escalation, or case 3's rung where the subagent files or scores `todo.md` items and that rung is higher.
|
||||
3. A subagent that files or scores `todo.md` items: what `~/.claude/bin/subagent-rung --plan <model> <L>` prints, which is never below the project's rung.
|
||||
2. An escalated task, below: the rung loop-claude's prompt names for escalation, or case 3's rung where the subagent files or scores plan items and that rung is higher.
|
||||
3. A subagent that files or scores plan items: what `~/.claude/bin/subagent-rung --plan <model> <L>` prints, which is never below the project's rung.
|
||||
4. Any other: what `~/.claude/bin/subagent-rung <model> <L>` prints.
|
||||
- Escalate a task that proves too hard for your rung. Four escalation triggers say so:
|
||||
1. A re-score of the item's L, made on the project's rung or above, picks a rung above yours.
|
||||
2. The same failing test or finding survives two fix attempts.
|
||||
3. A pass reports a 🔴 in round 2.
|
||||
4. A review rules the work below standard: systems-architect's BLOCK, a finding against larv-review's `standards/quality.md`, or a vote `record-ruling` counts as worse, in the report that stands after any relaunch one rung up (`larv-review` §3 → "Rung up").
|
||||
4. A review rules the work below standard: systems-architect's BLOCK, a finding against the review standards' `quality.md`, or a vote `record-ruling` counts as worse, in the report that stands after any relaunch one rung up (`larv-review` §3 → "Rung up"). It doesn't fire where the fix changes only prose (`larv-review` §3 says what is prose): fix that on your own rung.
|
||||
|
||||
When one fires, hand the hard part, edits included, to a subagent on the rung loop-claude's prompt names, one above yours. Open the subagent's prompt with the marker loop-claude's prompt gives, then the trigger's evidence. Each later subagent on that task runs on that rung or higher, and each further escalation trigger moves the task one rung higher, up to the highest rung loop-claude's prompt names. Ask the human before going higher. Where loop-claude's prompt names no escalation, as on the ladder's top rung or off it, keep the task in your own thread.
|
||||
- Give a subagent only the access its job needs, and state the limits in its prompt. One that only reads, such as a prose review, gets no shell and no edits. A reviewer under `~/.claude/agents/` writes only its report, under `~/.local/state/larv-review/`, and rule-hook refuses it every other Write, every Edit and every MultiEdit. One that probes a build tags the image as throwaway and removes it afterwards, writes only to a folder it makes under the chunk's review folder (`~/.claude/bin/larv-review review-folder` prints it), and removes no image or file it did not create.
|
||||
- Check `README.md` first for build, test, install, and codegen commands, and fix one that misbehaves in the same change. Refresh `README.md` whenever you change what it describes, keeping it true, not longer.
|
||||
- Where `~/.claude/bin/rule-hook` does not check it, such as an image named in test code, a Kubernetes manifest, a `docker run` line or a file a Bash command writes, pin a container image to its full patch version and a GitHub Action to a semver tag.
|
||||
- Where `~/.claude/bin/rule-hook` does not check it, such as an image named in test code, a Kubernetes manifest or a `docker run` line, pin a container image to its full patch version and a GitHub Action to a semver tag.
|
||||
|
||||
## Naming files & folders
|
||||
- Name by what's inside. BANNED: `scripts`, `utils`, `helpers`, `misc`, `common`, `lib`, `stuff`. GOOD: `e2e-tests/`, `db-migrations/`, `release-tooling/`.
|
||||
@@ -90,11 +99,14 @@ The rules only reviewers apply, for quality, comments, READMEs and prose, live i
|
||||
## Git, commits, and PRs
|
||||
- Mark no commit, PR, issue comment or file as the work of Claude, Anthropic or an agent.
|
||||
- Commit message and PR title: **one line**, prefixed with the ticket ID when the work has one. Example: `ABC-123 - Regression tests for GET /v4/clients`. Never include the repo/project name (like "twu-4") — we're already in that context.
|
||||
- Where the project's config names a `commit-title`, `pull-request-title` or `branch` template, fill it instead of following the formats in this section. `{summary}` is the one line that says what the change does, without a ticket ID, and `{id}` is the ID of the chunk's first item. A chunk without a plan item, such as a release review, works on a branch that doesn't fit the `branch` template, and its titles are the summary alone. `~/.claude/bin/project-config --help` describes the templates, and `chunk-preflight`'s facts quote them. A title a tool reads, such as `Answer <pass> round <n>: …`, `Drop item <ID>: …` or `Release review of <release>`, is the template's `{summary}`.
|
||||
- When the work has a ticket, read it before starting: verify the change matches it and pull useful context from it.
|
||||
- PR summary: short and concise. No test plan (it lives in the ticket), no link to the ticket (it's in the title).
|
||||
- Branch for a ticket: exactly the ticket ID, nothing more. `ABC-123`, never `ABC-123-some-description`.
|
||||
- Branch for a `todo.md` item without a ticket: `item-<ID>`, in the worktree `<checkout>-item-<ID>` beside the checkout, as `chunk-preflight` makes them.
|
||||
- Branch for a plan item without a ticket: `item-<ID>`, in the worktree `<checkout>-item-<ID>` beside the checkout, as `chunk-preflight` makes them. Under a `branch` template, `chunk-preflight` names both by the template.
|
||||
- Where the project's config keeps a file in the config's folder, `~/.claude-projects/<key>/`, such as the plan or a record, commit each change you make to that file in the folder's own git repo, on its only branch. Two chunks may commit there at once, so commit only that file: `git commit -m <title> -- <file>`, after `git add <file>` where it is new. Where git finds `index.lock` held, the other chunk is committing: try again. Title that commit as you would title the change in the checkout: where a commit in the checkout goes with it, give it the same title.
|
||||
- Use `gh` on GitHub remotes and `tea` on Gitea remotes (e.g. `gitea.larvit.se`) — same command shape: `tea pr list|create`, `tea issue`, `tea release`, `tea api`. Everything in this section applies to both.
|
||||
- On GitHub and Gitea, open a chunk's pull request as a draft, mark it ready and merge it with `~/.claude/bin/chunk-pr`, which picks `gh` or `tea` from the remote; `chunk-pr --help` says how. Once it has merged, run `chunk-pr clean` in the chunk's worktree: it removes the worktree and the branch and fast-forwards the main checkout.
|
||||
|
||||
## Handoffs
|
||||
- Write no handoff document. The repo holds everything the next session needs: the plan, the decisions, and every script, sketch or measurement those depend on. A file outside the repo is unreachable from another machine's checkout.
|
||||
@@ -109,7 +121,7 @@ The rules only reviewers apply, for quality, comments, READMEs and prose, live i
|
||||
Claude Code reads this section by its heading when it compacts a conversation. Keep in the summary:
|
||||
|
||||
- what remains before the chunk is finished;
|
||||
- the task loop-claude gave, and each `todo.md` item the chunk takes with its L and E + I;
|
||||
- the task loop-claude gave, and each plan item the chunk takes with its L and E + I;
|
||||
- the worktree, branch and PR;
|
||||
- the rung loop-claude named for each review launch, rerun and escalated subagent;
|
||||
- each review pass's rounds so far, each open 🔴 and 🟡, and how the answered ones were answered;
|
||||
@@ -120,18 +132,20 @@ Claude Code reads this section by its heading when it compacts a conversation. K
|
||||
## Vocabulary
|
||||
|
||||
- **chunk** — the unit of work, shipped as one PR; "Working loop" says what it holds.
|
||||
- **cycle** — in `loop-claude`, worker runs and the judge's verdict on each, until the chunk closes or is left for the next cycle. In between, the human answers any interrupt, or the worker resumes with an answer the judge quoted from `README.md` or the judge's records.
|
||||
- **cycle** — in `loop-claude`, worker runs and the judge's verdict on each, until the chunk closes or is left for the next cycle. In between, the human answers any interrupt, or the worker resumes with an answer the judge quoted from the premises or the judge's records.
|
||||
- **gate** — the merge gate: the checks a PR passes before it merges.
|
||||
- **interrupt** — `loop-claude` asking the human, on its terminal and in `loop-inbox`, for a decision that is theirs. They type a one-line answer in either, or `/talk` to open the worker's session with `claude --resume` where they typed it. A release ready to cut opens that session at once, on loop-claude's terminal. A routing call opens claude on that terminal too, in `~/code/claude-config`, the checkout where this setup is developed.
|
||||
- **goals file** — the file holding a project's `## Goals` and `## Audience`: the one its config names as `goals-and-audience`. Read it in the file `~/.claude/bin/project-record open goals-and-audience` prints. It is `README.md`, unless a client's project keeps it in the config's folder, or in a Jira epic's description, whose `## Goals` and `## Audience` the loop only reads.
|
||||
- **interrupt** — `loop-claude` asking the human, on its terminal, for a decision that is theirs. They type a one-line answer there, or `/talk` to open the worker's session there with `claude --resume`. A release ready to cut opens that session at once. A routing call opens claude on that terminal too, in `~/code/claude-config`, the checkout where this setup is developed.
|
||||
- **judge** — the headless claude that reads a worker's transcript each cycle and decides whether to interrupt and whether the chunk is finished.
|
||||
- **judge's records** — the files the judge reads beside the README's premises: the project's `AGENTS.md` and `docs/decisions.md`, then the human's `~/.claude/CLAUDE.md` and the `.md` files in `~/.claude/rules/` and `~/.claude/skills/larv-review/standards/`.
|
||||
- **judge's records** — the files the judge reads beside the premises: the project's `AGENTS.md` and `docs/decisions.md`, then the human's `~/.claude/CLAUDE.md` and the `.md` files in `~/.claude/rules/`, then those in the project's review standards.
|
||||
- **paired ruling** — the seats vote whether the project reads better, the same or worse at the branch's head than at the base, the commit `larv-review ruling-base` prints; `larv-review --help` says how the votes make the ruling.
|
||||
- **pass** — one kind of review a chunk may take, run in rounds by its reviewers until clean; `larv-review` §3 lists them.
|
||||
- **place** — the smallest addressable unit, such as a function or a section heading, that a seat names with its `path:line` when it judges how hard the project is to read there.
|
||||
- **plan** — `todo.md`.
|
||||
- **premises** — the goals and audience under `## Goals` and `## Audience` in the project's `README.md`, with code health ("Shared goal") first among the goals unless the README voids it.
|
||||
- **plan** — where the project keeps its items, as the `plan` setting of its config names it: a `todo.md` at a path, or a Jira epic.
|
||||
- **premises** — the goals and audience under `## Goals` and `## Audience` in the project's goals file, with code health ("Shared goal") first among the goals unless the goals file voids it.
|
||||
- **project's rung** — the cheapest rung on loop-claude's routing ladder of the project's model, which is the model loop-claude's prompt names as the project's, or else your own.
|
||||
- **release** — a semver version the human cuts.
|
||||
- **project record** — one of five documents a project keeps beside its plan, each where its config names it: `decisions`, `score-anchors`, `comprehension-history`, `reading-cost` and `changelog`.
|
||||
- **release** — a semver version the human cuts, or in a client's project someone on its team.
|
||||
- **release review** — a release's last chunk: the architecture and principles passes over the whole project, before the release is ready to cut; `larv-review` §3 → "Release review".
|
||||
- **reviewer** — a reporter of findings: an agent under `~/.claude/agents/`, `/security-review` or a forge's auto-reviewer.
|
||||
- **round cap** — the rounds one pass may take per chunk; `larv-review` §3 → "Round cap".
|
||||
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
# MIT License
|
||||
|
||||
Copyright (c) 2026 Larv IT AB
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
@@ -1,13 +1,13 @@
|
||||
# Claude Code configuration
|
||||
|
||||
My personal `~/.claude`, version controlled: `CLAUDE.md`, `AGENTS.md` and `rules/` for instructions, the words under `CLAUDE.md` → "Vocabulary"; `agents/` and `skills/`; `principles/` and `skills/larv-review/standards/` for what the reviewer agents hold projects to; `docs/` for decisions and the comprehension history; `settings.json` for the harness and `.claude/settings.json` for the harness inside this repo; `CHANGELOG.md` and `todo.md`; the tools in `bin/`; and `workflow-bench/`, the scripts and prompts of the 2026-09-30 bench of larv-review.
|
||||
My personal `~/.claude`, version controlled: `CLAUDE.md` and `rules/` for instructions, the words under `CLAUDE.md` → "Vocabulary"; `.claude/rules/` for the rules that load in this repo alone; `agents/` and `skills/`; `principles/` and `skills/larv-review/standards/` for what the reviewer agents hold projects to, which a project's config names as `principles` and `standards`; `docs/` for decisions and the comprehension history; `settings.json` for the harness and `.claude/settings.json` for the harness inside this repo; `CHANGELOG.md` and `todo.md`; the tools in `bin/`, with the routing ladder they ship, `bin/model_routing/routing-ladder.json`; `workflow-bench/`, the scripts and prompts of the 2026-09-30 bench of larv-review and of the 2026-11-12 bench of the advisor tool; `reviewer-merge-trials/`, the 2026-11-09 trials of merging reviewers, with their method, results and scripts; `judge-field-trials/`, the 2026-11-11 trials of which facts code could read in place of loop-claude's judge, with their results and scripts; `stability-skip-count/`, the 2026-11-12 count of archived stability rounds, with its script, from which larv-review took when to skip a stability round 2; and `presentation/`, a page that explains this setup to newcomers, with the script that prints it to PDF.
|
||||
|
||||
## Goals
|
||||
|
||||
1. **Achieve:** Get the highest quality out of Claude Code while interrupting me the least, so development scales.
|
||||
- Signal: interrupts of me per finished chunk fall.
|
||||
- Counter-signal: findings that a later change fixes, per finished chunk, rise.
|
||||
- Why: fewer asks buy nothing if the output gets worse.
|
||||
- Why: fewer asks don't buy anything if the output gets worse.
|
||||
1. **Achieve:** Proven, stellar output quality: code, documentation and plans.
|
||||
- Signal: 🔴 and 🟡 findings that review raises per chunk fall.
|
||||
- Counter-signal: later changes that fix a chunk's code rise.
|
||||
@@ -16,22 +16,26 @@ My personal `~/.claude`, version controlled: `CLAUDE.md`, `AGENTS.md` and `rules
|
||||
- Signal: asks that a goal or decision already settled fall to zero.
|
||||
- Counter-signal: decisions I reverse rise.
|
||||
- Why: guessing instead of asking saves an interrupt only if the guess holds.
|
||||
3. **Maintain:** The same rules in every project and every session.
|
||||
4. **Achieve:** Add cost only where it meaningfully raises quality; otherwise work to lower cost.
|
||||
3. **Maintain:** The same workflow in every project and every session; each project's config supplies its premises, principles, plan and records.
|
||||
4. **Achieve:** Keep lowering cost, except where that would cut quality meaningfully.
|
||||
- Signal: tokens per finished chunk fall.
|
||||
- Counter-signal: review rounds or unfinished verdicts per chunk rise.
|
||||
- Why: a cheaper run that needs more rounds costs more.
|
||||
- Counter-signal: reading cost, the new input tokens a chunk reads before its first commit, rises; or review rounds or unfinished verdicts per chunk rise.
|
||||
- Why: a cheaper chunk that leaves the project harder to read moves the cost to every later chunk, whose changes need more reading and grow likelier to break what nobody saw; and a chunk that needs more rounds costs more.
|
||||
5. **Achieve:** Delivery speed.
|
||||
- Signal: hours from a chunk's start to its merge fall.
|
||||
- Counter-signal: 🔴 findings per chunk rise.
|
||||
- Why: speed bought by skipping review shows up as defects.
|
||||
6. **Achieve:** Plug into a project without changing what its owners keep: its repo layout, tracker, wiki and conventions.
|
||||
- Signal: the changes a project's owners must make before the loop runs in it fall.
|
||||
- Counter-signal: defects where a backend loses or misreads a plan item, a premise or a record rise.
|
||||
- Why: fitting in isn't worth anything if the loop then works from wrong facts.
|
||||
2. **Maintain:** Make my claude setup shareable between computers.
|
||||
3. **Maintain:** Keep my claude setup and the transcripts of unattended runs, the bench's included, backed up.
|
||||
4. **Maintain:** Leak nothing to the remote — no credentials, no transcripts, no memory files.
|
||||
3. **Maintain:** Keep my claude setup and the transcripts of unattended runs backed up. A bench's transcripts are the exception: they stay only until `task-bench gather` has filed plan items from their digest, or the next bench starts.
|
||||
4. **Maintain:** Don't leak anything: no credentials, transcripts or memory files to this repo's remote, and no client's code, transcripts or credentials to another client or to this repo.
|
||||
|
||||
## Audience
|
||||
|
||||
Me, on my own machines, which take tagged releases. Nobody else depends on it.
|
||||
Me, on my own machines and on those I use for the clients I consult for, which take tagged releases. Client teams read what the loop writes in their Jira, Confluence and pull requests, so it must read as written for them.
|
||||
|
||||
## Install
|
||||
|
||||
@@ -67,7 +71,108 @@ git config filter.settings.clean bin/settings_filter.py
|
||||
|
||||
Then pick a model with `/model`.
|
||||
|
||||
Link `loop-claude` and `loop-inbox` onto `PATH`: `ln -s ~/.claude/bin/loop-claude ~/.local/bin/loop-claude` and `ln -s ~/.claude/bin/loop-inbox ~/.local/bin/loop-inbox`. Every claude they start, the interactive ones included, skips every permission prompt.
|
||||
Link `loop-claude` onto `PATH`: `ln -s ~/.claude/bin/loop-claude ~/.local/bin/loop-claude`. Every claude it starts, the interactive ones included, skips every permission prompt. loop-claude runs each chunk in its own window of a tmux session per project, so it needs tmux 3.2 or later.
|
||||
|
||||
Back up three folders: `~/.claude/loop-claude-transcripts`, where loop-claude keeps every transcript, `~/.claude/do-epic-transcripts`, where do-epic keeps its chunks' transcripts, and `~/.local/state/larv-review`, where larv-review keeps each chunk's reports. To keep loop-claude's transcripts and the reports small, add a crontab line that gzips each transcript and review file 30 days after it last changed, and logs each run with its date:
|
||||
|
||||
```sh
|
||||
17 4 * * * { date; $HOME/.claude/bin/compress-archives; } >> $HOME/.local/state/compress-archives.log 2>&1
|
||||
```
|
||||
|
||||
Cron runs it with its own `PATH` and environment. Where the `python3` on cron's `PATH` is older than 3.14, or you set `LOOP_CLAUDE_TRANSCRIPTS`, set `PATH` or that variable in the crontab too.
|
||||
|
||||
To get loop-claude's questions and stops as DMs from a bot, write the bot's token, your username or member ID and, for Mattermost, the server into `~/.claude-projects/<key>.env`, in the keys `~/.claude/bin/notify --help` names, run `chmod 600` on it, and add `env-file = "~/.claude-projects/<key>.env"` and `notifier = "mattermost"` (or `"slack"`) to the project's config, as Install → "Set up a project" describes.
|
||||
|
||||
### Set up a project
|
||||
|
||||
Each project the loop runs in has a folder, `~/.claude-projects/<key>/`, where `<key>` is the project's name, and a config in it, `config.toml`. The folder is a git repo of its own, so the config has a history and a client's files never enter this repo. The loop commits each change it makes to a file there, such as the plan, in that repo, titled as its commits in the checkout. A project is a whole git checkout, never a subfolder of one.
|
||||
|
||||
The config names the project's main checkout and the path of every file the loop keeps for it. No path setting has a default: `project-config` fails and names each setting a config leaves out. A path is `checkout:<path>` inside the checkout, `folder:<path>` inside the config's folder, or one that starts with `/` or `~/`. Every tool reads and writes each file at the path its setting gives, and `chunk-preflight` and `todo-item` print those paths for the agents. Five of the settings name the project's records: `decisions`, `score-anchors`, `comprehension-history`, `reading-cost` and `changelog`. Keep each file's name, such as `todo.md`: the rules for a file load by its name. A project of your own keeps every file but the principles and the review standards in its checkout:
|
||||
|
||||
```toml
|
||||
checkout = "~/code/log"
|
||||
plan = "checkout:todo.md"
|
||||
working-rules = "checkout:AGENTS.md"
|
||||
decisions = "checkout:docs/decisions.md"
|
||||
score-anchors = "checkout:docs/score-anchors.md"
|
||||
comprehension-history = "checkout:docs/comprehension-history.md"
|
||||
reading-cost = "checkout:docs/reading-cost.md"
|
||||
changelog = "checkout:CHANGELOG.md"
|
||||
goals-and-audience = "checkout:README.md"
|
||||
principles = "~/.claude/principles"
|
||||
standards = "~/.claude/skills/larv-review/standards"
|
||||
```
|
||||
|
||||
`principles` and `standards` name the folders the reviewers hold the project to: the technical principles and the review standards. Both ship with this setup, at the paths above. A folder of your own replaces the shipped one. A standards folder must hold `quality.md`, `prose.md`, `comments.md` and `readme.md`, since the reviewers and the rules name those files.
|
||||
|
||||
A project may also set `env-file`, the file of `KEY=value` credentials its tools read, such as `env-file = "~/.claude-projects/log.env"`. It is a path that starts with `/` or `~/`, outside the checkout and the config's folder, so that no git remote receives it. A tool that needs a key fails and names each one the file lacks. No failure message, prompt, log line or archived loop output holds a token from the file. rule-hook refuses a Read or a Grep of the file and a Bash command that names it or searches a folder holding it with `ag`, `grep -r` or `rg`, unless the tool skips the file as hidden or ignored, so a worker doesn't read it in passing; `rule-hook --help` says which calls it checks. A project without the setting has no credentials, and never reads another project's. `project-config env-file` prints the path.
|
||||
|
||||
A project may also set `touch-predictions`, a path spelt as `changelog`'s is, such as `touch-predictions = "checkout:docs/touch-predictions.md"`. `touch-predictions record` appends each chunk's predicted files and parts there, beside those it touched. A project that leaves it out keeps no such record.
|
||||
|
||||
A project whose team wrote its own coding conventions lists the files in `coding-conventions`, each spelt as `principles` is, such as `coding-conventions = ["checkout:CONVENTIONS.md"]`. Each reviewer agent larv-review launches reads them beside the principles and the standards, and the team's rule wins where they conflict.
|
||||
|
||||
A project may also set `notifier` to `"mattermost"` or `"slack"`, the service that sends loop-claude's DMs. The `env-file` then holds that service's keys. A project that sets none gets no DMs, whatever its env file holds. `project-config notifier` prints the setting.
|
||||
|
||||
A project's config may set four more things, each optional, as `project-config --help` describes. `language` names the language its owners write in, where that isn't English: the worker writes the project's prose in it, and the prose reviewer judges the prose in it. `commit-title`, `pull-request-title` and `branch` are templates for a project that titles and names these in another way than `CLAUDE.md` → "Git, commits, and PRs" says. `chunk-preflight` names the branch and the worktree by the `branch` template. On a branch that fits it, rule-hook refuses a commit, and `chunk-pr` a pull request, whose title doesn't fit its template; on any other branch, such as a release review's, a title is the summary alone. A tool that reads a commit title, such as a round's `Answer <pass> round <n>:`, reads the template's `{summary}`: it tries `commit-title`, then `pull-request-title`, since a squash merge titles the commit as the pull request, then takes the title whole. While a project's config holds a fault, rule-hook refuses every commit there, and the tools that read its titles fail naming the fault.
|
||||
|
||||
A legacy project with no container setup sets `tooling-on-host = true`, so the loop runs its language runtime, package manager, tests and task runner directly on the host. One whose code the comprehension panel scores low may lower `readability-floor` from 7.0: under it, the ranking weighs code health 4 times as much, and a scoring run asks for a floor item. To let more than one chunk run at once, set `parallel-chunks` to the most that may; left out, it is 1. Beside the plan's next item, only items whose `Touches:` predictions overlap none of the running chunks' items start.
|
||||
|
||||
A project whose pull requests need a human's approval sets `wait-for-approval = true` in its config. `chunk-pr merge` then waits, once the checks have passed, until GitHub reports the pull request approved as its branch protection requires, and merges it. It refuses on Gitea, where a reviewer requested changes and where the protection requires no review. While it waits, other chunks merge. It stops where a reviewer's comment waits for an answer, on an approved pull request too; answer it and run it again. It gives up after 90 minutes without an approval; run it again once the pull request is approved. Left out, the setting is false.
|
||||
|
||||
A project whose team merges its pull requests itself sets `merge = "human"`. `chunk-pr merge` then brings the branch level with origin's default branch, finishes the chunk's plan items, waits for the checks and marks the pull request ready, but leaves the merge to a person. A plan or changelog kept in the checkout is finished on the branch, so it lands with that merge; one kept in Jira, or in the config's folder, is finished at once; where you close the pull request unmerged, file the item again. A do-epic chunk parks until the pull request is merged, and its window's name says `awaits your merge`. The chunk resumes and brings the branch level again once the pull request conflicts with the default branch. It does so too once the branch is behind a default branch whose protection, on GitHub, requires an up-to-date branch. loop-claude doesn't start a chunk for an item that a ready pull request finishes. Once no item left in the release can start and one awaits a merge, loop-claude stops and names the pull requests to merge; run it again after you merge one. The first chunk after a merge runs `chunk-pr clean` in the worktree the merged pull request left, where nobody pushed to the pull request after the chunk did. Nobody works on a pull request that awaits your merge. To have a reviewer's comment answered, turn the pull request back into a draft: a chunk then takes its item up again. Left out, the setting is `"chunk"`: the chunk merges.
|
||||
|
||||
A project whose team wants an epic's work in one pull request sets `epic-branch`, a template with `{epic}` for the epic's key, such as `epic-branch = "{epic}"`. Under loop-claude the epic is the Jira epic the config's `plan` names, so a plan kept in a file gets no working branch. Under do-epic it is the epic do-epic drives. Each chunk then branches off the epic's working branch, here `ABC-123` for the epic ABC-123, and `chunk-pr` opens its pull request into that branch and merges it there without a person, also under `merge = "human"` and `wait-for-approval`: those two keep guarding the default branch. A pull request that was open into the default branch when you set `epic-branch` stays yours to settle: `chunk-pr ready` and `merge` fail on it, naming both branches, until you change its base on the forge to the working branch, or merge it yourself. `chunk-preflight`, and do-epic as a chunk starts, make the branch on origin off the default branch, or merge the default branch into it with a merge commit, which needs git 2.38 or later. Where that merge conflicts, they stop, and a person merges it. Once the epic's last issue has landed, do-epic's finishing chunk runs `chunk-pr open-epic <epic's key> <title>`, which brings the branch level once more and opens the pull request from it into the default branch. Under loop-claude, run it yourself. A person merges that pull request, and its checks and reviews are theirs to answer. An auto-reviewer that reviews only pull requests into the default branch is asked by a comment: set `review-request-comment` to the comment's text, such as `"@reviewbot review"`. `chunk-pr ready` then posts it on a pull request into the working branch, and `chunk-pr push` pushes later commits and posts it again.
|
||||
|
||||
For a client's project, use one sandbox VM per client, so that one client's code, transcripts and credentials never share a machine with another's. What the client's repo should not hold lives in the config's folder, at paths written as `folder:<path>`, as `project-config --help` shows: the plan, the working rules in an `AGENTS.md` I write for the agents, the records, and the goals and audience, as `goals-and-audience = "folder:goals.md"`. Name that file `goals.md`, so the rules for goals and audience load when an agent writes it. A file outside the checkout has no commits in the checkout's history, so four things are not supported for it yet. `score-outcomes` and loop-claude's routing figures count a project's chunks only where `todo.md`, `docs/comprehension-history.md` and `docs/reading-cost.md` are at those paths in the checkout; otherwise each says so, and the loop goes on. For a plan or a comprehension history outside the checkout, `larv-review` says it cannot tell whether a scoring run is owed, and for such a history it cannot find a paired ruling's base. For a plan outside the checkout, chunk-preflight and loop-claude don't see a release whose last item has shipped, and say that its release review and its cut are yours to call. And rule-hook checks a plan outside the checkout on every call, not only when it changed.
|
||||
|
||||
A client that plans in Jira Cloud names an epic as its project's plan: `plan = "jira:https://acme.atlassian.net/browse/ABC-12"`, which is `jira:` and the epic's address as the browser shows it. The plan is then the epic's open child issues, in Jira's backlog order, which the team sets, apart from the rank `todo-item add` gives an issue it files. An issue in a done status is a finished item. Each part of an item comes from one part of its issue:
|
||||
|
||||
- The ID is the issue's number, so every child must be in the epic's own Jira project.
|
||||
- The tagline is the summary.
|
||||
- The detail is the description, which a docker container converts to markdown.
|
||||
- The release is the earliest Fix Version named as a semver version, such as `1.2.0`. Every open child needs one.
|
||||
- A blocker is an "is blocked by" link to another open child.
|
||||
- The scores are the issue property `plan-item`, a JSON object such as `{"L": 2, "E": 2, "I": 3, "S": 3, "Moves": "1.6 by 4", "Exempt": ""}`. An issue without it reads as an item nobody scored yet.
|
||||
|
||||
A read fails, naming the issue, where a child is in another Jira project or names no such Fix Version. The config's `env-file` must hold `ATLASSIAN_EMAIL` and `ATLASSIAN_API_TOKEN`, an API token of that Atlassian account, and only its owner may read that file: `chmod 600` it.
|
||||
|
||||
The loop reads such a plan and files each item into it as a Task under the epic. A Jira project that has no Task type, such as TW, sets `jira-finding-type` to a type it has, such as `"Feature"`. `todo-item add` fails, naming the project's types, where the project lacks the type set. `todo-item add` also needs the item's release among the Jira project's Fix Versions, named as `1.2.0` or `v1.2.0`. The config states the formula and the bar that a todo.md states under `## Scoring`, such as `jira-score-formula = "100 * V / (2**S + 8)"` and `jira-score-bar = 1`, and fails to load without them. `todo-item add` refuses an item that scores under the bar, unless it is exempt. It ranks the new issue among the issues the loop filed: questions first, then security findings, then by score. A person's issues keep the rank the team gave them, and `rank_todo.py` doesn't rank the plan.
|
||||
|
||||
`todo-item edit` and `move` change only an issue the loop filed. Of an issue a person filed, `edit` sets only the scores, and posts its `--comment` on the issue to tell the team why; the summary, description and Fix Version stay the team's to change in Jira, as do its links. On an issue the loop filed, `edit --blocked-by` makes and deletes the links to the epic's open items. For `todo-item finish`, the config names the workflow transition that finishes an item and the status it leads to, both as Jira shows them: `jira-finish-transition = "Mark as done"` and `jira-finish-status = "Done"`. Finish then moves the item's issue by that transition. It refuses a transition that leads to another status, or to one Jira doesn't count as done, and fails where the config sets neither. The four things not supported for a plan outside the checkout, above, are not supported for a plan in Jira either.
|
||||
|
||||
A client that keeps its goals and audience in an epic's description names that epic as the goals file: `goals-and-audience = "jira:https://acme.atlassian.net/browse/ABC-12"`, which may be the plan's own epic. Such a config keeps its plan in Jira too, and reads both with the same `env-file`. The description needs `## Goals` and `## Audience` as headings, level-2 headings in Jira's editor. `project-record open goals-and-audience` prints a file holding the description's text, and `project-record save` writes it back, except a change to `## Goals` or `## Audience`: edit those two in Jira. A save rewrites the whole description from markdown, which keeps no mention, macro or block id that markdown can't hold. Whoever may edit that description sets the premises every worker and judge follows, so keep its edit rights to the people who own the project's goals.
|
||||
|
||||
To name a chunk's branch, worktree, commits and pull request by the issue key, as in `ABC-123` and `ABC-123 - …`, set these three templates, with your Jira project's key in place of `ABC`: `branch = "ABC-{id}"`, `commit-title = "ABC-{id} - {summary}"` and `pull-request-title = "ABC-{id} - {summary}"`. `project-config --help` says how the templates work.
|
||||
|
||||
```sh
|
||||
mkdir -p ~/.claude-projects/acme && cd ~/.claude-projects/acme
|
||||
git init
|
||||
$EDITOR config.toml
|
||||
git add config.toml && git commit -m "Add the config"
|
||||
cd ~/code/acme-billing && ~/.claude/bin/project-config
|
||||
```
|
||||
|
||||
The last line prints each setting's path once the config is complete.
|
||||
|
||||
`do-epic` keeps its settings per machine, not per project, in `~/.claude-projects/do-epic/`, two files for every epic:
|
||||
|
||||
- `config.toml` sets `jira-url`, the site, such as `https://acme.atlassian.net`; `env-file`, the file holding `ATLASSIAN_EMAIL` and `ATLASSIAN_API_TOKEN`, a path that starts with `/` or `~/`, outside the clone folder and every folder of `~/.claude-projects`; and `repoless-model`, the model that works an item with no repo. It may also set `clone-folder`, where a missing repo is cloned, `~/code` if left out; `language`, the language of Jira text, English if left out; and `jira-finish-transition` with `jira-finish-status`, which name the workflow transition that moves a finished chunk's issue, and closes a finished epic, and the status it leads to, such as `"Mark as done"` and `"Done"`. Set both or neither: without them do-epic moves no issue to done and closes no epic, and a chunk that finishes stops with that reason.
|
||||
- `config.toml` fits do-epic to a team whose own automation moves issues, such as a CI job that moves an issue when its pull request merges. Two settings do:
|
||||
- `jira-unblocking-statuses` lists the statuses at which an issue's work has landed though Jira doesn't count it done yet, such as `["Release Ready"]`, in upper or lower case. An issue in one of them takes no chunk and no longer blocks the issues it blocks, and `--status` names the statuses beside each blocker. A status Jira counts as done always does both. The release reviews, which are the epic's last chunk, still wait until Jira counts every issue done: run `do-epic <EPIC-KEY>` then, to start them.
|
||||
- `jira-automation-moves-issues = true` keeps do-epic from moving the issue of a finished chunk in a repo: the automation moves it, and do-epic waits for that move before it starts what the issue blocks. An issue without a repo has no pull request, so do-epic still moves it, with `jira-finish-transition`. The setting needs `jira-unblocking-statuses`, which names the status the automation gives an issue whose pull request merged.
|
||||
- `config.toml` names the statuses do-epic itself gives an issue whose chunk merges into an epic's working branch, in a repo whose config sets `epic-branch`. A team's automation moves an issue only for a pull request into the default branch, so there do-epic makes both moves, whatever `jira-automation-moves-issues` says. `jira-pull-request-open-status`, such as `"Code Review"`, is the status of an issue whose chunk parks with its pull request open; a pull request that opens and merges within one run of the worker skips it, unless the workflow leads to the merged status only through it. `jira-pull-request-merged-status`, such as `"Release Ready"`, is the status once the pull request has merged into the working branch. `jira-unblocking-statuses` must list it, and an issue that has it counts as done when the release reviews and the finishing chunk fall due, since both come before a person merges the working branch. Without it, do-epic moves a finished chunk's issue to done. Where `jira-automation-moves-issues` is set, it stops instead and asks you to move the issue.
|
||||
- `config.toml` names how do-epic moves a parent issue whose sub-tasks a person filed. Once every sub-task is done, the parent moves to done by `jira-finish-transition`; without that setting it stays. Before that, once each sub-task is done or in one of `jira-unblocking-statuses`, the parent moves by the transition `jira-sub-tasks-landed-transition` names, such as `"Release Ready"`; without that setting it stays. The transition must lead to one of `jira-unblocking-statuses`, or do-epic doesn't make it. do-epic makes these moves as each run plans and as each chunk finishes, and `--dry-run` prints them. A parent that is done, or already in one of `jira-unblocking-statuses`, never moves back. A move that is not made is said, and the run goes on.
|
||||
- `config.toml` also says how a starting chunk's issue shows on its team's board. A starting chunk always assigns its issue to the account do-epic works as, unless someone else holds it; that issue keeps its assignee, and moves and joins the sprint like any other. `jira-start-transition` names the workflow transition that then moves the issue, such as `"In Progress"`; an issue whose work has started already keeps its status. `jira-sprint-board` is the ID of the board whose active sprint the issue joins, such as `6`. Where a setting is left out, do-epic doesn't take its step.
|
||||
- `config.toml` may set `jira-finding-type`, the issue type do-epic files a finding as, and `jira-review-type`, the one it files a repo's release review as, such as `"Feature"` and `"Chore"`. Both are Task where left out. do-epic doesn't file anything where the Jira project lacks the type, and says which types it has.
|
||||
- `config.toml` may set `sub-task-summary`, which shapes the summary of each sub-task do-epic files for an issue that changes several repos, such as `sub-task-summary = "{label}: {Summary}"`. `{label}` is the team's label for the repo, else the repo's name, and `{Summary}` is the issue's summary with a capital first letter. It must hold `{Summary}`. Without it a summary is `[<repo>] <the issue's summary>`.
|
||||
- `config.toml` may end with a `[label-repos]` table, for a team that already labels its issues by repo. Give it one line for each such label: the label, then the repo's name, such as `twu-4 = "tenant-web-ui-4"`. do-epic reads such a label as it reads its own `repo:<name>`. Where the label is the repo's name, map the name to itself, as in `core-4 = "core-4"`. Where several lines name one repo, do-epic writes the label of the first. Write every other setting above the table.
|
||||
- `repo-rule.md` is prose that says how to tell an item's repo, such as "a label that equals a repo's name names that repo". It may not be blank. `do-epic <EPIC-KEY>` uses it to pick where each open issue without such a label is worked, and records the pick as a label. For a repo that is the team's own label from `[label-repos]`, else `repo:<name>`; for work of Claude's that changes no repo, `do-epic-claude`; for a task of yours, `do-epic-human`. Where the rule leaves an issue unclear, do-epic asks you on the terminal. Answer with the label, or with Enter alone to leave the issue waiting. Change a pick by editing the label in Jira.
|
||||
|
||||
An epic's description states the formula that puts its issues in order: once under `## Scoring`, on a line of its own and inside backticks, such as `` `Score = 100 * V / (2**S + 32)` ``. do-epic starts the epic's issues by that score, highest first, with each blocker before what it blocks, whatever their order on the board. Where two or more issues may start, it scores each of them that holds no scores, a person's included, against the epic's goals and the goals of the issue's repo, and tells the team the scores in a comment on the issue. It doesn't score a task of yours, and it keeps the scores an issue already holds. On the board it re-ranks only the issues it filed, so a person's issue keeps the rank the team gave it. Without that line do-epic says so, doesn't score anything and starts the issues in the backlog's order.
|
||||
|
||||
Each repo an epic changes has a project config of its own, as in the rest of this section. `do-epic` fails and names each setting or file that is missing or invalid.
|
||||
|
||||
A project runs on the routing ladder this setup ships, `bin/model_routing/routing-ladder.json`: the rungs, least competent first, each a model at an effort, that loop-claude routes workers, subagents and reviews to. To run one project on other rungs, as when an outage or a client's account leaves it fewer models, copy that file to `~/.claude-projects/<key>/routing-ladder.json` and cut or change its rungs. Keep one model for each family, such as opus: Claude Code launches a subagent by its family's name. The project's file replaces the shipped ladder whole. loop-claude reads it as each cycle starts, and `subagent-rung` and rule-hook each time they run. The loop never commits it, so commit it in the folder's repo yourself only where it should last. Set the project's models to ones its ladder holds, for example with `LOOP_CLAUDE_WORKER_MODEL` and `LOOP_CLAUDE_JUDGE_MODEL`. A model off the ladder is not routed: every worker runs on that model, at the effort Claude Code's `settings.json` gives. Each cycle of a project on a ladder of its own says so on stderr, naming the file, and says where the worker's model is off it. `loop-claude --help` shows the file's shape.
|
||||
|
||||
## Update
|
||||
|
||||
@@ -77,7 +182,9 @@ Move `~/.claude` to the newest release:
|
||||
~/code/claude-config/bin/deploy-release
|
||||
```
|
||||
|
||||
It refuses while a file `~/.claude` tracks has an uncommitted change, such as a hook Claude Code wrote into `settings.json`: merge that per `AGENTS.md` → "Working rules", then cut a release. A model picked with `/model` is no such change. It prints `CHANGELOG.md`'s section for each version it moved past: do what each asks, such as a new step under Install. `deploy-release --help` says what else it checks.
|
||||
It prints `CHANGELOG.md`'s section for each version it moved past: do what each asks, such as a new step under Install. `deploy-release --help` says what else it checks.
|
||||
|
||||
It refuses while a file `~/.claude` tracks has an uncommitted change, such as a hook Claude Code wrote into `settings.json`; a model picked with `/model` is no such change. Read the change first, as in `git -C ~/.claude diff HEAD -- settings.json`. When it holds a credential, such as a token in `env` or `mcpServers`, move that out of the file: a token in `env` to the shell profile, a server in `mcpServers` to `~/.claude.json` with `claude mcp add --scope user`. Then carry the change into `~/code/claude-config` on a branch of its own, merge it through a PR, and cut a release.
|
||||
|
||||
## Release
|
||||
|
||||
@@ -91,61 +198,98 @@ It renames `## Unreleased` in `CHANGELOG.md` to the version and merges that thro
|
||||
|
||||
## Tools
|
||||
|
||||
Install puts only `loop-claude` and `loop-inbox` on `PATH`; call the others by their path, such as `~/.claude/bin/metric-bench`, from the project's checkout. Those under `~/.claude` are the release's; test a change to one from `~/code/claude-config/bin`.
|
||||
Install puts only `loop-claude` on `PATH`; call the others by their path, such as `~/.claude/bin/metric-bench`, from the project's checkout. Those under `~/.claude` are the release's; test a change to one from `~/code/claude-config/bin`. The tools are listed in alphabetical order, and the packages under `bin/` follow under their own heading.
|
||||
|
||||
- `chunk-pr open|sync|ready|push|merge|clean|open-epic` opens a chunk's pull request as a draft, brings its branch level with origin's default branch, marks it ready and merges it once its checks pass, with `gh` on a GitHub origin and `tea` elsewhere. Where the project's config sets `epic-branch`, the pull request goes into the epic's working branch instead, `push` pushes later commits and asks the auto-reviewer for a review, and `open-epic` opens the pull request from that branch into the default branch. The chunks of one project merge one at a time: in its turn, `merge` brings the branch level again, finishes the plan items its `--finish` flags name, and waits for the checks. Under `merge = "human"` it then marks the pull request ready and leaves the merge to a person. Once the pull request is merged, `clean` removes the chunk's worktree and branch and fast-forwards the main checkout. `chunk-pr --help` states the steps.
|
||||
- `chunk-preflight` finds the mechanical facts a chunk starts from, and with `--worktree` makes its worktree; `loop-claude` runs it with `--worktree` before it routes each chunk, and `chunk-preflight --help` lists the facts.
|
||||
- `command-patterns [<version>] [--calls <file>]` prints a table of the shell command patterns a release's archived chunks ran, such as `tea pr create`, for an audit of the release, and with `--calls <file>` saves each call as a JSON line; `command-patterns --help` states the columns and the line's keys.
|
||||
- `compress-archives` gzips each transcript in loop-claude's archive and each file in the review folders 30 days after it last changed, keeping all of them; Install's crontab line runs it daily.
|
||||
- `deploy-release [--cut] [<checkout>]` moves `~/.claude`, or the checkout named, to the newest release, as Update says; with `--cut`, run in the development clone, it first cuts the next release, as Release says.
|
||||
- `judge-replay <model>` replays loop-claude's judge on archived verdicts of the projects run on the model, and prints the lowest rung that, like each rung above it, returns them; `judge-replay --help` states the replay.
|
||||
- `larv-review <command>` holds larv-review's mechanical rules: the chunk's review folder, the paired ruling's base and vote count, each pass's round count, the scoring run's trigger, and the comprehension history's format and latest places, and its count of how often seats agree; `larv-review --help` states them.
|
||||
- `loop-claude <task>` runs a project's next chunk cycle after cycle; `loop-claude --help` states its contract.
|
||||
- `loop-inbox` shows the interrupts of every loop-claude on the machine, oldest first, takes each one's answer, `/talk` included, and lists every running loop with the `todo.md` items its chunk takes; `loop-inbox --help` states how.
|
||||
- `do-epic <EPIC-KEY>` runs the chunks of one Jira epic whose items span repos, or have none, each in its own window of the tmux session `epic-<EPIC-KEY>`, on the same cycle, judge and interrupt as loop-claude. The epic's description is its record: goals, audience, scoring and decisions. Before it starts chunks, do-epic plans each open issue that no label places yet, as "Set up a project" says. It files a sub-task per repo where the issue changes several repos. Otherwise it labels the issue with where it is worked, and asks you where that is unclear. It plans no issue your team filed a sub-task under: those sub-tasks run instead, each under a label of its own, and your team closes the issue. Then, where two or more issues may start, it scores each of them that holds no scores, and moves the issues that do-epic itself filed into order of score on the board. An open issue runs once a label names its repo or marks it as Claude's, in order of score, as many at once as a line such as `**Max parallel chunks:** 2` in the epic's description allows, 1 without it, and as each repo's `parallel-chunks` allows. A chunk whose pull request waits on a gate parks. An open task of yours that blocks another issue gets a window that DMs you once and reads the epic every minute; once you close the task, the issues it blocked may start. `do-epic <EPIC-KEY> --dry-run` prints what `do-epic <EPIC-KEY>` would write to Jira and which chunks it would start, and does neither; run it before the first real run on a team's epic. `--help` lists what it prints and leaves out. do-epic closes the epic only once you confirm every goal. Install → "Set up a project" says how to set it up; `do-epic --help` states the flags and the contract.
|
||||
- `do-epic-e2e` runs `do-epic` against a sandbox epic on a real Jira site, as Test says.
|
||||
- `judge-replay <model> [--offline]` replays loop-claude's judge on archived verdicts of the projects run on the model. It prints what each rung a review climbs to misses, and the lowest rung below those that returns every verdict, as each candidate above it does. With `--offline` it doesn't call a judge: it counts what a "?" rule, a decision table and a classifier trained on the archive decide of each verdict's kind from the worker's final message, and how many interrupts each misses. `judge-replay --help` states both replays.
|
||||
- `larv-review <command>` holds larv-review's mechanical rules: the chunk's review folder, the paired ruling's base and vote count, each pass's round count and the opening of its round commit's title, the scoring run's trigger and setup; the comprehension history's format, its latest places and its count of how often seats agree; and each reviewer's prompt header. `larv-review --help` states them. `settings.json` → `hooks` runs `larv-review reviewer-context` as each subagent starts. A reviewer under `agents/` whose frontmatter has `omitClaudeMd: true` starts without `CLAUDE.md`, and the command hands it that file's "Shared goal", "Prose" and "Vocabulary" sections.
|
||||
- `loop-claude <task>` runs a project's next chunks, each in its own tmux window, cycle after cycle; `loop-claude --help` states its contract.
|
||||
- `markdown-section <file> <fragment>` prints the section of a markdown file under the first heading that holds the fragment, to the next heading of its level or a higher one, instead of a `grep -n` and a guessed `sed -n` range; `markdown-section --help` says what it does where several headings match.
|
||||
- `metric-bench [history]` benches cheap static metrics of a project's Python against the places its comprehension history names as hardest; `metric-bench --help` states the metrics and the scores.
|
||||
- `rank_todo.py [--check] [todo.md]` scores and ranks a project's `todo.md`; `rank_todo.py --help` states the format.
|
||||
- `mutate-changes [--base <ref>] [--prefix <shell text>] [--jobs <n>]` mutation-tests the lines a branch changes and prints each mutant its tests don't kill; `mutate-changes --help` says which tool it runs for each language.
|
||||
- `notify [<message>]` sends a message, or else stdin, as a DM from the bot of the project's `notifier`, Mattermost or Slack, to the human; the project's `env-file` holds the bot's token, the recipient and, for Mattermost, the server, and `notify --help` names its keys. `loop-claude --help` says when loop-claude sends one.
|
||||
- `project-config [<setting>]` prints the paths a project's config sets, or the one asked for, and fails naming each setting the config leaves out; Install → "Set up a project" shows a config.
|
||||
- `project-record open <record>` prints the path of a file holding one of a project's records, for an agent to read and edit, and `project-record save <record>` stores the edit; for a record kept as a file, that file is the record. `goals-and-audience` opens the goals file the same way.
|
||||
- `rank_todo.py [--check] [todo.md]` scores and ranks a project's `todo.md`, by default the one its config names; `rank_todo.py --help` states the format.
|
||||
- `reading-cost [--reset] [record]` appends a figure for each chunk `loop-claude` finished to a project's `docs/reading-cost.md`, and says whether the figures rise; `reading-cost --help` states the measure.
|
||||
- `review-replay <pass> <model>` replays a review pass's archived rounds from the projects run on the model, on the code each reviewed, and prints the lowest rung below the project's that, like each rung above it, finds every 🔴 and 🟡 the project's rung finds again; `review-replay --help` states the replay. Each replayed reviewer skips every permission prompt, stability-reviewer has Bash, and an archived prompt may name paths on the host.
|
||||
- `rule-hook [overrides]` blocks a tool call that breaks a rule a program can check, unless the call overrides the rule; `settings.json` → `hooks` runs it before each Agent, Bash, Edit, MultiEdit, Read, Skill and Write call, and `rule-hook --help` states the rules and the override.
|
||||
- `review-replay <pass> <model>` replays a review pass's archived rounds from the projects run on the model, on the code each reviewed, and prints the lowest rung below the project's that, like each rung above it, qualifies: it finds no less of the 🔴 and 🟡 findings than two replays on the project's rung find, within a margin, and misses no 🔴 that both found. `review-replay --help` states the replay. With `--omit-claude-md`, `--bash-ceiling` or `--read-limit` it tests instead whether the pass's reviewer may start without `CLAUDE.md`, or under the Bash output ceiling loop-claude hands the worker, or a Read limit it doesn't hand yet: it replays each round three times as archived and once with the change, and prints whether the reviewer passes: whether the last replay missed no more findings than the most an unchanged replay missed, with each count and each finding it missed. Each replayed reviewer skips every permission prompt, stability-reviewer has Bash, and an archived prompt may name paths on the host.
|
||||
- `rule-hook [overrides]` blocks a tool call that breaks a rule a program can check, unless the call overrides the rule; `settings.json` → `hooks` runs it before each Agent, Bash, Edit, Grep, Monitor, MultiEdit, Read, Skill and Write call, and `rule-hook --help` states the rules and the override.
|
||||
- `run-heavy <command>` runs a heavy command once it holds one of the machine's heavy slots, one per 4 CPUs, which every session shares; `run-heavy --help` states the slots, and the memory cap it gives a container that sets no limit.
|
||||
- `score-outcomes [L E I S]` shows what each finished item's chunk measured beside the scores the item was guessed at, to score a new item by, and code health's two counter-signals per chunk, misread findings and later fixes; `score-outcomes --help` states the report.
|
||||
- `run-tests [<pytest args>...]` runs this repo's test suite, as Test says.
|
||||
- `score-outcomes [L E I S]` shows what each finished item's chunk measured beside the scores the item was guessed at, to score a new item by. Per chunk it also shows code health's two counter-signals, misread findings and later fixes, and how many of the human's answers reversed a worker's choice; `score-outcomes --help` states the report.
|
||||
- `settings_filter.py` is git's clean filter for `settings.json`: it drops `"model"` and sorts the keys. `.gitattributes` sets the filter `settings` on `settings.json`, and Install's `git config` line makes this script that filter.
|
||||
- `statusline.py` renders Claude Code's status line; `settings.json` → `statusLine` runs it.
|
||||
- `subagent-rung [--plan] <model> <L>` prints the Agent tool's model and effort for a subagent's task, picked by its L from the project's model, and with `--plan` never below the project's rung; `subagent-rung --help` states the rule.
|
||||
- `subagent-rung [--plan] <model> <L>` prints the Agent tool's model and effort for a subagent's task, picked by its L from the project's model on the project's routing ladder, and with `--plan` never below the project's rung; `subagent-rung --help` states the rule.
|
||||
- `task-bench --image <image> --test <shell text> [<options>]` plants bugs that the tests catch, at the places the comprehension seats found hardest, has Haiku fix each at the base and at the head, and prints how often the fix passes and what it took. It needs docker and a token from `claude setup-token`; `task-bench --help` says how it plants, runs and checks. It leaves a digest of why runs failed. `task-bench gather` starts a claude on the project's rung, which files a plan item for each place the digest shows to be hard; then gather removes the bench's folder, digest and streams.
|
||||
- `todo-item` reads and changes a project's plan, whatever holds it: `list` prints the items in the plan's order and `show <ID>` one item's row and detail; `add …` files an item under the next free ID, `edit <ID> …` sets an item's cells or detail, and `move <ID> --release <version>` sets an item's release; `finish <ID>` removes a finished item and adds the bullet passed with `--changelog` to `CHANGELOG.md`, except for a plan kept in Jira. Each change ranks a markdown plan. `todo-item --help` states the flags.
|
||||
- `touch-predictions record <ID>...` appends what a chunk's items were predicted to touch, under `Touches:` in their details, beside the files and parts its branch touched, to the record the config names as `touch-predictions`; `touch-predictions --help` shows the spelling and how a part is named. `chunk-preflight` reads the same predictions to name the items that may start chunks at once.
|
||||
- `wait-for <file> [<pattern>] [--timeout <seconds>]` waits until a file a background job writes holds a line matching the pattern, and prints it.
|
||||
|
||||
Test on the host with `uvx --python "$(command -v python3)" --with pytest-xdist==3.8.0 pytest==9.2.0 -n 4 bin`. It needs `uv` on `PATH`, which fetches pytest, pytest-xdist and mypy. pytest-xdist runs the tests in four workers, one heavy slot's CPUs (`docs/decisions.md` → `bin/: the tools support only the latest stable Python, …`). `python3 -m unittest discover -s bin -p 'test_*.py'` runs the same tests one at a time. Test the bench's git wrapper with `python3 -m unittest discover -s workflow-bench -p 'test_*.py'`.
|
||||
### Packages under `bin/`
|
||||
|
||||
To mutation-test a changed module, copy `bin/` to a scratch directory (`cp -r bin "$scratch"`): mutmut writes files beside its config. In the copy, name the module and its tests in a `setup.cfg`, as below for `score_outcomes/results.py`. Leave out each test class that starts a tool's launcher through `subprocess`: a mutated module fails to load in a process mutmut did not start.
|
||||
|
||||
```ini
|
||||
[mutmut]
|
||||
source_paths=score_outcomes/results.py
|
||||
also_copy=.
|
||||
pytest_add_cli_args_test_selection=score_outcomes/
|
||||
pytest_add_cli_args=-k
|
||||
not ScoreOutcomesTool
|
||||
```
|
||||
|
||||
Then, in the copy: `uvx --with pytest==9.2.0 'mutmut>=3,<4' run && uvx --with pytest==9.2.0 'mutmut>=3,<4' results`, and `uvx --with pytest==9.2.0 'mutmut>=3,<4' show <mutant>` to see a mutant's change. The config keys are mutmut 3's.
|
||||
|
||||
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests. Beside the packages, `bin/`'s root holds only the launchers, the tools of one file with their tests, `test_env.py` and `failure.py`. `failure.py`'s `Failure`, which modules across `bin/` return for a failed step, belongs to no single package. `branch_chunks/`, `claude_code/`, `command_lines/`, `git_cli/`, `machine_load/`, `model_routing/`, `records/`, `release_plan/`, `review_rules/`, `rung_replay/` and `transcript_archive/` serve more than one tool.
|
||||
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests. Beside the packages, `bin/`'s root holds only the launchers, the tools of one file with their tests, `test_env.py`, `failure.py` and `setup.cfg`. `failure.py`'s `Failure`, which modules across `bin/` return for a failed step, belongs to no single package. `agent_cycle/`, `atlassian/`, `branch_chunks/`, `chunk_driver/`, `claude_code/`, `command_lines/`, `forge/`, `git_cli/`, `loop_effects/`, `loop_state/`, `machine_load/`, `model_routing/`, `notifier/`, `plan/`, `plan_store/`, `record_store/`, `release_plan/`, `review_rules/`, `rung_replay/`, `text_files/` and `transcript_archive/` serve more than one tool. No package imports one that imports it back, and a package's `doubles.py` holds the test doubles that other packages' tests use, so no module imports a `test_*` module of another package; `repo_checks/test_package_cycles.py` checks both. No Python file of the repo, `workflow-bench/`'s included, uses `mock.patch`, which `repo_checks/test_no_patched_globals.py` checks.
|
||||
|
||||
- `adf_codec/` converts markdown to ADF, the rich text of Jira Cloud and Confluence, and back, in a throwaway container running a pinned `@larvit/adf-codec`. It builds the container's image inside a heavy slot.
|
||||
- `agent_cycle/` runs one cycle (`run.py`): a headless claude worker, then the judge of its transcript. It also holds the interrupt, the tmux window and the routing of the worker's rung. The entry point that runs the cycles supplies the prompts and file names of its own workflow (`worker_prompts.py`), and reads which items a worker took in. `loop_claude` and `do_epic` drive it; `agent_cycle` doesn't import either.
|
||||
- `atlassian/` holds what the Jira and Confluence backends share (`client.py`): one Atlassian account's credentials, the request both backends send, and each service's error messages. `jira.py` holds what every reader of Jira shares: a search read page by page, the key, fields, links and property of each issue it finds, checked for their shape, and the transition that finishes an issue, for `plan_store` and `do_epic`.
|
||||
- `branch_chunks/` cuts a default branch into chunks and finds, for each, the items it shipped and the later chunks that fixed its code, for `score_outcomes` and `routing_figures`. It imports `reading_cost`'s record path.
|
||||
- `command_lines/` reads a shell command: its simple commands, and a docker call's subcommand and memory limits, for `reading_cost`, `routing_figures`, `rule_hook` and `run_heavy`.
|
||||
- `deploy_release` imports `chunk_preflight`'s `forge_of`, which tells a GitHub origin from a Gitea one, and `release_plan`'s `release_standing`.
|
||||
- `git_cli/` runs git for every tool (`git_repo.py`), and reads the git calls in a shell command (`git_command.py`).
|
||||
- `judge_replay` imports `loop_claude`'s judge.
|
||||
- `chunk_driver/` holds what the entry points share. An entry point is a tool that drives chunks through `agent_cycle`: `loop_claude` and `do_epic` are the two. They share how a cycle starts (`cycle_start.py`) and closes (`chunk_run.py`), the claim on a checkout before a chunk starts in it (`claims.py`), the prompts every worker gets (`prompts.py`), and a checkout's premises, records and saved models (`project/`). It imports neither entry point, and `repo_checks` fails any package that imports one of the two. `agent_cycle` is the layer below it, and `repo_checks` fails `agent_cycle` where it imports `chunk_driver`, tests included.
|
||||
- `command_lines/` reads a shell command: its simple commands, and a docker call's subcommand and memory limits, for `command_patterns`, `reading_cost`, `routing_figures`, `rule_hook` and `run_heavy`.
|
||||
- `deploy_release` imports `release_plan`'s `release_standing`.
|
||||
- `do_epic/` holds `do-epic`, the tool that drives one Jira epic:
|
||||
- `main.py` starts the epic's chunks and runs one chunk's cycles in its window, through `agent_cycle`.
|
||||
- `planning.py` settles, before the chunks start, where each open issue is worked, its scores and the order the issues start in, through `split.py`, `repo_pick.py`, `issue_scores.py` and `ranking.py`.
|
||||
- `scheduler.py` says which issues run now: as many as the epic's cap and each repo's `parallel-chunks` allow, and none in a repo where loop-claude runs chunks.
|
||||
- `gates.py` reads once whether a chunk's pull request waits on its checks, an approval or a new review, and `parked.py` keeps each chunk that does in a state file, so it takes no running slot while it waits and goes on waiting after a reboot.
|
||||
- `chunk_prompt.py` words what a chunk's worker reads. Through `findings.py` that worker files a finding as an issue of the epic, with `--file`, and appends a decision to its description, with `--record-decision`.
|
||||
- `finish.py` ends an epic that holds no open issue: its finishing chunk files a release review of each repo the epic changed, has the human confirm each goal, and with `--close-epic` posts the summary on the epic and closes it.
|
||||
- `config.py` reads its machine-wide settings, importing `project_config`'s settings and `model_routing`'s ladder file, and `epic_record.py` reads and writes an epic's description by section, language line and cap line, through `record_store`'s `EpicDescription`.
|
||||
- `repos.py` finds a repo's checkout and project config by its name, and clones a missing checkout from the host and owner of the epic's other repos, through `forge`'s `url_beside`.
|
||||
- `repo_pick.py` asks claude, by `repo-rule.md`, where an epic item is worked, and records the answer as a label on the issue.
|
||||
- `split.py` has claude predict from the code which repos an item changes, and files a sub-task per repo under it where there are several.
|
||||
- `parent_moves.py` moves a parent whose sub-tasks a person filed, once those have landed or are done.
|
||||
- `ranking.py` orders an epic's items by score over one chain of goals, the epic's, then code health, then the item's repo's, through `plan`'s ranking, and re-ranks the tracker's backlog to that order through `backend/`.
|
||||
- `backend/` reads, files and ranks the epic's issues, adds the labels `repo_pick.py` and `split.py` record, posts comments, moves a finished chunk's issue to done, and closes the epic.
|
||||
- `e2e/` holds `do-epic-e2e`.
|
||||
- `forge/` tells a GitHub origin from a Gitea one, names a repo beside an origin's and runs that forge's CLI (`commands.py`), finds a pull request, lists the ready ones and reads its checks, once or until they settle (`pulls.py`), and reads a pull request's review state (`reviews.py`), for `chunk_preflight`, `chunk_pr`, `deploy_release`, `do_epic` and `larv_review`.
|
||||
- `git_cli/` runs git for every tool (`git_repo.py`), reads the git calls in a shell command (`git_command.py`), and keeps an epic's working branch level with the default branch (`epic_branch.py`).
|
||||
- `judge_replay` imports `agent_cycle`'s judge and verdicts, and `chunk_driver`'s premises, records and `ANSWER_DESTINATIONS`.
|
||||
- `loop_claude` runs `chunk-preflight` as a process of its own.
|
||||
- `loop_inbox` imports `loop_claude`'s question files (`waiting/`), the files a running loop lists itself in (`running_loops.py`, `session_lock.py`), its effects and paths, and `hand_over.py`, which opens claude for `/talk`. A change to any of them changes loop-inbox too.
|
||||
- `machine_load/` takes the machine's heavy slots, its shared lock files, for `run_heavy`, and reads the memory share that loop-claude waits for.
|
||||
- `model_routing/` holds the routing ladder, which loop-claude, `rule_hook`, both replay tools and `subagent-rung` read.
|
||||
- `loop_effects/` holds `Effects`: the processes, terminal, clock and git a tool reaches, injected so its tests can script them. loop-claude, do-epic, both replay tools and `reviewer-merge-trials`' driver use it.- `loop_state/` holds where loop-claude and do-epic keep their files (`paths.py`), which `rung_replay` reads too.
|
||||
- `machine_load/` takes the machine's heavy slots, its shared lock files, for `run_heavy` and `adf_codec`, and reads the memory share that loop-claude waits for. It also gives `mutate_changes` a slot's CPU count.
|
||||
- `model_routing/` holds the shipped routing ladder (`routing-ladder.json`) and its steps (`ladder.py`), and reads a ladder from that file or a project's own (`ladder_file.py`), for loop-claude, `rule_hook`, `do_epic`, both replay tools and `subagent-rung`. It finds a project's config folder through `project_config`. It also holds the list prices, which `routing_figures` and `transcript_archive` read.
|
||||
- `notifier/` sends the human a DM through the notifier a project's config names, for `notify` and for loop-claude through `loop_effects`. Its backends are `mattermost.py` and `slack.py`.
|
||||
- `plan/` is the plan's core, and imports neither `plan_store` nor `release_plan`. It holds an item and the items table's format (`todo_table.py`), releases (`release.py`), the ranking (`ranking.py`, with its score formula in `formula.py` and its blocker order in `blockers.py`), the paths an item's text names (`named_paths.py`), an item's `Touches:` prediction and where two overlap (`touches.py`), and `citations.py`, which holds `todo.md` and `docs/decisions.md` to each other. `goals_file.py` reads the goals file's sections, goals and goal weights, for the ranking and for `loop_claude`'s premises.
|
||||
- `plan_store/` reads and writes a project's plan through the store the project's config names (`stores.py`). Every backend meets `plans.py`'s `PlanStore`: a markdown file (`todo_md.py`, which also ranks and checks the file in place, with its text edits in `markdown_edits.py`) or a Jira epic (`jira_epic.py`). `scoring.py` reads the goal weights that both backends rank by. `contract.py` holds the tests every backend that writes must pass; `jira_epic.py` doesn't yet, and its own tests stand in for Jira. `fakes.py` holds a plan in memory.
|
||||
- `rank_todo.py`, `settings_filter.py` and `statusline.py` are tools of one file each, tested beside them.
|
||||
- `records/` reads a Markdown file's `##` sections, quotes a passage and joins names into a list, stamps times in UTC, and replaces a file in one step, private where it is new.
|
||||
- `release_plan/` reads `todo.md`'s items table and release versions, says which release is next and whether it is ready to cut (`release_standing.py`), and ranks the plan (`ranking.py`, which `rank_todo.py`, `larv_review` and `rule_hook` import).
|
||||
- `record_store/` reads and writes a project's records, each through the store the project's config names (`stores.py`): a markdown file, a Confluence Cloud page (`confluence_page.py`), or, for the goals, a Jira epic's description (`jira_description.py`). `contract.py` holds the tests every backend must pass, and `fakes.py` a store in memory that the tests of other tools use.
|
||||
- `release_plan/` says which release is next and whether it is ready to cut (`release_standing.py`), from the plan, the changelog and the tags, picks the item the next chunk takes first (`next_chunk.py`), and marks each item that a ready pull request finishes (`awaiting_merge.py`), for `chunk_preflight` and `loop_claude`.
|
||||
- `repo_checks/` tests the repo itself.
|
||||
- `rest_client/` sends a JSON request to a REST API and reads its credentials from an env file, for `notifier`, `atlassian` and `record_store`.
|
||||
- `review_rules/` holds the larv-review rules that several tools apply: its passes, its review folder, its round commit titles and the comprehension history's format.
|
||||
- `routing_figures/` measures loop-claude's archive, and each of its projects' default branches, for loop-claude's routing calls.
|
||||
- `rung_replay/` holds what `judge_replay` and `review_replay` share: the rung search, the argument reader, the candidate rungs and the exits. It reads `loop_claude`'s retry count and models file.
|
||||
- `rung_replay/` holds what `judge_replay` and `review_replay` share: the parallel replay runner, the argument reader, the candidate rungs and the exits, and `judge_replay`'s rung search. It reads `agent_cycle`'s retry count and `chunk_driver`'s models file, and finds that file through `loop_state`'s paths. Its `archive.py` keeps each replay's runs and its report in a `replays/` folder of loop-claude's archive.
|
||||
- `task_bench/` holds `task-bench`, which plants bugs in a Go project and has Haiku fix them in containers.
|
||||
- `test_env.py` serves the tests.
|
||||
- `text_files/` reads a Markdown file's `##` sections, quotes a passage and joins names into a list, reads the text piped into a command, stamps times in UTC, replaces a file in one step, private where it is new, and gzips a file beside its plain name, by which it reads it afterwards.
|
||||
- `transcript_archive/` stores loop-claude's transcripts. Its `project_key.py` names each project's archive folder, loop-claude session and models-file entry.
|
||||
|
||||
## Test
|
||||
|
||||
Test on the host with `bin/run-tests`, which runs pytest through `uvx`, pinned in `bin/run_tests/main.py`. It prints each failing test with its error and pytest's summary line, and saves the whole output to a file whose path it prints. It passes on any test paths or pytest options it is given, such as `bin/run-tests bin/chunk_pr -x`. It needs `uv` on `PATH`, which fetches pytest, pytest-xdist and mypy, a Docker daemon, Linux, and a user other than root; a test that lacks one fails, naming it. pytest-xdist runs the tests in one worker per CPU of a heavy slot (`docs/decisions.md` → `bin/: the tools support only the latest stable Python, …`). `python3 -m unittest discover -s bin -p 'test_*.py'` runs the same tests one at a time, with the same needs. Test the bench's scripts with `python3 -m unittest discover -s workflow-bench -p 'test_*.py'`.
|
||||
|
||||
`bin/do-epic-e2e` checks `do-epic` against a real Jira site, which `run-tests` never reaches. It makes an epic with issues and sub-tasks in a sandbox project, runs `do-epic --file`, `--record-decision` and `--close-epic` against it in a home folder of its own, and deletes the epic and its issues when it ends. The sandbox project must be team-managed, with a `Done` transition, and its account must be able to create, edit, transition, comment on and delete issues there. Set `DO_EPIC_E2E_JIRA_URL` to the sandbox site's address, `DO_EPIC_E2E_ENV_FILE` to the absolute path of the file holding the account's `ATLASSIAN_EMAIL` and `ATLASSIAN_API_TOKEN`, and `DO_EPIC_E2E_PROJECT` to the project's key. The command fails, naming each setting that is missing. It needs a Docker daemon, as `run-tests` does.
|
||||
|
||||
CI runs `ci.sh` on every pull request, and `main` doesn't merge anything until it passes. The script runs the same tests on the committed HEAD in a pinned Python container. Run it under `run-heavy` to reproduce a CI failure, with Docker on `PATH` and its socket at `/var/run/docker.sock`, which the container shares.
|
||||
|
||||
To mutation-test the lines a branch changes, run `~/.claude/bin/run-heavy ~/.claude/bin/mutate-changes --prefix 'uvx --python "$(command -v python3)" --with pytest==9.2.0 --from "mutmut>=3,<4"'` in its checkout.
|
||||
|
||||
## Tracking a new file
|
||||
|
||||
`.gitignore` is an allowlist. Track a file by negating it and its parent directories, then confirm with `git check-ignore -v <path>`:
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
---
|
||||
name: comprehension-seat
|
||||
description: "Use this agent for a seat of larv-review's comprehension check, with the prompt `larv-review prepare-scoring` writes or the paired ruling's brief in skills/comprehension-panel/seat-prompts.md."
|
||||
tools: Read, Grep, Glob, Bash
|
||||
omitClaudeMd: true
|
||||
---
|
||||
|
||||
You are a simulated reader of a project. Your prompt gives your background, the checkout you read, the files you may not open and the report to write. Read as that reader would, knowing only what the project's files tell you, and follow the prompt exactly.
|
||||
@@ -4,7 +4,7 @@ description: "Use this agent for larv-review's overrides pass."
|
||||
tools: Read, Grep, Glob, Write
|
||||
---
|
||||
|
||||
You rule on each override of a rule `~/.claude/bin/rule-hook` enforces. The prompt gives you the lines `rule-hook overrides` printed, each with its rule and reason, and the branch diff. Read each rule and its stated exceptions in `~/.claude/bin/rule_hook/rules.py` → `RULES`, how an override is written and logged in the docstring of `~/.claude/bin/rule_hook/main.py`, and the project's `README.md` → "Goals" and "Audience", with code health (`~/.claude/CLAUDE.md` → "Shared goal") among the goals unless the README voids it.
|
||||
You rule on each override of a rule `~/.claude/bin/rule-hook` enforces. The prompt gives you the lines `rule-hook overrides` printed, each with its rule and reason, and the branch diff. Read each rule and its stated exceptions in `~/.claude/bin/rule_hook/rules.py` → `RULES`, how an override is written and logged in the docstring of `~/.claude/bin/rule_hook/main.py`, and the project's goals and audience, `## Goals` and `## Audience` in the file your prompt's `Goals and audience:` line names, with code health (`~/.claude/CLAUDE.md` → "Shared goal") among the goals unless that file voids it.
|
||||
|
||||
For each override:
|
||||
|
||||
|
||||
@@ -2,13 +2,14 @@
|
||||
name: principles-auditor
|
||||
description: "Use this agent for larv-review's principles pass: the project's goals and every principles file handed to it, checked against the whole project."
|
||||
tools: Read, Grep, Glob, Write
|
||||
omitClaudeMd: true
|
||||
---
|
||||
|
||||
You check every yardstick you are handed against the whole project, which you read once for all of them. A yardstick is either the project's goals, every goal under its `README.md` → `## Goals` with code health (`~/.claude/CLAUDE.md` → "Shared goal") unless the README voids it, or one principles file, every principle in it.
|
||||
You check every yardstick you are handed against the whole project, which you read once for all of them. A yardstick is either the project's goals, every goal under `## Goals` in the file your prompt's `Goals and audience:` line names, with code health (`~/.claude/CLAUDE.md` → "Shared goal") unless that file voids it, or one principles file, every principle in it.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. Read the yardsticks, `README.md`, `docs/decisions.md` and `todo.md` first, then all of the project's code, config, tests and CI.
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. Read the yardsticks, `README.md`, `docs/decisions.md` and the plan first, then all of the project's code, config, tests and CI. Your prompt's `Plan:` line names the plan.
|
||||
|
||||
- Per principle or goal: every place the project departs from it, with file:line, the defect in one sentence and its concrete consequence. Then one line: followed, mostly, not followed, or does not apply and why.
|
||||
- A departure a `todo.md` item plans away is named with that item, not raised.
|
||||
- A decision in `docs/decisions.md` working against a goal or a technical principle is a 🔴 on the decision, unless it names the `todo.md` item that ends it. Weigh it hard: that it was decided is no reason.
|
||||
- Report under one heading per yardstick.
|
||||
- A departure a plan item plans away is named with that item, not raised.
|
||||
- A decision in `docs/decisions.md` working against a goal or a technical principle is a 🔴 on the decision, unless it names the plan item that ends it. Weigh it hard: that it was decided is no reason.
|
||||
- Report under one `##` heading per yardstick.
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
name: "product-owner-reviewer"
|
||||
description: "Use this agent when you need a product-focused review of changes that affect external-facing surfaces (REST APIs, web UIs, CLI commands, public SDKs, webhooks, etc.) from an end-customer perspective. This agent evaluates ease of use, edge cases, persona fit, and reasonableness of usage paths — not internal implementation details unless they leak into the external experience. Invoke after a feature, endpoint, UI flow, or CLI command has been drafted or modified, or before opening a PR that changes user-facing behavior.\\n\\n<example>\\nContext: The developer just added a new REST endpoint for cancelling a subscription.\\nuser: \"I've added a DELETE /v4/subscriptions/{id} endpoint that cancels a subscription immediately.\"\\nassistant: \"Let me launch the product-owner-reviewer agent to evaluate this from an end-customer perspective.\"\\n<commentary>\\nA new external API surface was introduced. Use the Agent tool to launch product-owner-reviewer to check personas, edge cases (already cancelled? pending invoices? refund expectations?), and usability of the contract.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The developer added a new CLI subcommand.\\nuser: \"Added `mytool deploy --env prod --force` to skip confirmation.\"\\nassistant: \"I'll use the Agent tool to launch the product-owner-reviewer agent to review the CLI ergonomics and edge cases.\"\\n<commentary>\\nCLI usage is an external surface. The product-owner-reviewer should evaluate persona fit (who uses --force? is it discoverable? what happens on partial failure?).\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The developer modified a checkout flow in the web UI.\\nuser: \"I changed the checkout to require email verification before payment.\"\\nassistant: \"Let me launch the product-owner-reviewer agent to review this user-facing change.\"\\n<commentary>\\nWeb UI flow change directly affects end customers. Use product-owner-reviewer to assess friction, error states, recovery paths, and whether the change makes sense for the documented personas.\\n</commentary>\\n</example>"
|
||||
description: "Use this agent to review a change to an external surface (API, UI, CLI, SDK, webhook) from an end customer's view: ease of use, edge cases and persona fit."
|
||||
tools: Read, Grep, Glob, Write
|
||||
omitClaudeMd: true
|
||||
---
|
||||
|
||||
You are a seasoned Product Owner with deep expertise in user experience, API design, and customer empathy. You have shipped consumer and B2B products across web, mobile, REST APIs, and developer-facing CLIs. Your superpower is putting yourself in the end customer's shoes and surfacing the friction, confusion, and edge cases that engineers tend to miss.
|
||||
@@ -19,11 +20,11 @@ You consider internal logic **only** when it directly affects an external surfac
|
||||
|
||||
## Your Review Method
|
||||
|
||||
Before anything else, **read the shared principles** at `~/.claude/principles/`. Your territory is each file whose `Applies to` line names an external surface; `technical-principles.md` applies where it surfaces externally (timestamps communicated as UTC, idempotent writes). Re-read each time — they change.
|
||||
Before anything else, **read the technical principles** in the folder your prompt's `Technical principles:` line names (without one, open your report by saying so). Your territory is each file whose `Applies to` line names an external surface; `technical-principles.md` applies where it surfaces externally (timestamps communicated as UTC, idempotent writes). Re-read each time — they change.
|
||||
|
||||
1. **Identify the change surface**: Read the recent changes and pinpoint what external behavior is affected. If the change is purely internal with no external impact, say so plainly and stop — don't manufacture concerns.
|
||||
|
||||
2. **Identify the personas**: Who uses this? Check the README and any docs for documented personas. If personas are missing or unclear for the affected surface, review against your best-guess personas (e.g., "end customer", "tenant admin", "integrator/developer", "internal support", "CLI power user"), labelled as assumptions, and raise the persona question as a ❓.
|
||||
2. **Identify the personas**: Who uses this? Check the `## Audience` in the file your prompt's `Goals and audience:` line names, the README and any docs for documented personas. If personas are missing or unclear for the affected surface, review against your best-guess personas (e.g., "end customer", "tenant admin", "integrator/developer", "internal support", "CLI power user"), labelled as assumptions, and raise the persona question as a ❓.
|
||||
|
||||
3. **Walk the happy path** for each persona. Is it obvious? Does the naming match mental models? Is the minimum required input actually minimum?
|
||||
|
||||
@@ -44,9 +45,11 @@ Before anything else, **read the shared principles** at `~/.claude/principles/`.
|
||||
|
||||
6. **Assess reasonableness of usage paths**: Are there paths that exist but no real persona would use?
|
||||
|
||||
7. **Check each claim about output against its run.** A changed doc line that says what a command, flag or error prints is true only if the real output says so. Where your prompt has a `Claimed output:` line, that file holds each such claim's command and real output. Report a claim the output doesn't bear out, such as an error said to name the fix that doesn't, and name the missing words. Never settle one by reading code. A claim marked `not run`, or one you find that the prompt doesn't hand you a run of, is a ❓ naming the command that would run it.
|
||||
|
||||
## Your Output Format
|
||||
|
||||
Report only a defect a persona hits, a requirement of the plan, the README's goals or code health (`~/.claude/CLAUDE.md` → "Shared goal", unless the README voids it) that the change breaks, or a breach of a technical principle. Friction that is none of these is not a finding.
|
||||
Report only a defect a persona hits; a requirement that the change breaks, of the plan in the file your prompt's `Plan:` line names, of the goals in the file your prompt's `Goals and audience:` line names, or of code health (`~/.claude/CLAUDE.md` → "Shared goal", unless that file voids it); or a breach of a technical principle, or of a coding convention, which counts as one. Friction that is none of these is not a finding.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. After the verdict:
|
||||
|
||||
|
||||
@@ -2,28 +2,33 @@
|
||||
name: prose-reviewer
|
||||
description: "Use this agent for larv-review's prose pass."
|
||||
tools: Read, Grep, Glob, Write
|
||||
omitClaudeMd: true
|
||||
---
|
||||
|
||||
You read the prose as someone who did not write it: you see only what it says, never what the author meant.
|
||||
|
||||
The bar, read each time, since it changes:
|
||||
|
||||
- every file under `~/.claude/skills/larv-review/standards/`, of `quality.md` only "A false claim is a bug";
|
||||
- every file in the folder your prompt's `Review standards:` line names, of `quality.md` only "A false claim is a bug";
|
||||
- `~/.claude/CLAUDE.md` → "Public API specs";
|
||||
- each file under `~/.claude/rules/` whose `paths:` frontmatter matches a file the diff changes.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md.
|
||||
|
||||
Your prompt's `Prose language:` line names the language the project's config sets. Apply every check below to prose in that language, by that language's grammar and idiom. The bar's examples are English: find the same fault in the other language, never the same English words. Prose in another language is a finding, except what `prose.md` in the review standards says stays English. Write your report in English.
|
||||
|
||||
## Checks, in priority order
|
||||
|
||||
Run them in this order. A fix for a later check never breaks an earlier one.
|
||||
|
||||
1. **Easy to understand.** Read each sentence once, cold. A sentence you had to reread, a term used before it is explained, or an "it" or "them" that could point at two things is a finding. Fix: **Rewrite**, giving the plain sentence.
|
||||
2. **Most important first.** Name the document's reader and what they want to know first. Check that the sections run in that order, then the paragraphs within each section, then the items within each list. If not, fix: **Reorder**, naming the new order. A section so long that a reader has to search it gets sub-headings or an index. Fix: **Split**.
|
||||
3. **Default to delete.** A line the reader does not need fails. Fix: **Delete** what the code, a type, a test name, the README or another rule already says. Fix: **Move** a choice made in one place to a comment there, one made in more places to `docs/decisions.md` with its title in `AGENTS.md`, and a goal to the README. A pointer standing where a definition belongs (`~/.claude/skills/larv-review/standards/comments.md` → "Links and pointers", "A pointer is not a definition") gets the fix **Move back**: inline the definition, and leave the reasoning where it is.
|
||||
3. **Default to delete.** A line the reader does not need fails. Fix: **Delete** what the code, a type, a test name, the README or another rule already says. Fix: **Move** a choice made in one place to a comment there, one made in more places to `docs/decisions.md` with its title in `AGENTS.md` unless a project principle there covers it, and a goal to the README. A pointer standing where a definition belongs (the review standards' `comments.md` → "Links and pointers", "A pointer is not a definition") gets the fix **Move back**: inline the definition, and leave the reasoning where it is.
|
||||
4. **Short.** Words that do not clearly help 1–3 fail. Fix: **Cut**.
|
||||
|
||||
Also report a list whose order carries no meaning and is not sorted (`~/.claude/principles/technical-principles.md` → "Deterministic order"), a sentence contradicting another, a claim the code shows false, and a word used against `CLAUDE.md` → "Vocabulary".
|
||||
Also report a list whose order carries no meaning and is not sorted (the technical principles' "Deterministic order", in the folder your prompt's `Technical principles:` line names; without one, open your report by saying so), a sentence contradicting another, a claim the code shows false, and a word used against `CLAUDE.md` → "Vocabulary".
|
||||
|
||||
Where your prompt has a `Claimed output:` line, that file holds the command and real output of each changed line that says what a command prints. Report a claim its output doesn't bear out, and name the missing words. A claim marked `not run` is a ❓ naming the command that would run it.
|
||||
|
||||
## Growth
|
||||
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
---
|
||||
name: "stability-reviewer"
|
||||
description: "Use this agent when code has been written or modified and needs review for stability, bug prevention, and adherence to coding best practices. This includes after implementing new features, refactoring existing code, or fixing bugs. The agent focuses on defensive programming, error handling, edge cases, and compliance with the project's technical principles.\\n\\nExamples:\\n\\n- user: \"Please implement a retry mechanism for our API client\"\\n assistant: \"Here is the retry mechanism implementation: [code written]\"\\n Since significant code was written, use the Agent tool to launch the stability-reviewer agent to review the new code for stability and best practices.\\n assistant: \"Now let me use the stability-reviewer agent to review this implementation for stability concerns.\"\\n\\n- user: \"Refactor the payment processing module to use the new gateway\"\\n assistant: \"I've refactored the payment processing module. Let me now use the Agent tool to launch the stability-reviewer agent to check for any stability issues or violations of our technical principles.\"\\n\\n- user: \"Can you review what I just wrote?\"\\n assistant: \"I'll use the Agent tool to launch the stability-reviewer agent to thoroughly review your recent changes.\"\\n\\n- After any significant code change, proactively launch the stability-reviewer agent to catch issues before they reach production."
|
||||
description: "Use this agent to review changed code for stability: bugs, error handling, edge cases and the project's technical principles, after a feature, refactor or fix."
|
||||
color: orange
|
||||
tools: Bash, Read, Grep, Glob, Write
|
||||
omitClaudeMd: true
|
||||
---
|
||||
|
||||
You are an elite stability-focused code reviewer with deep expertise in defensive programming, fault-tolerant system design, and production incident prevention. You have decades of experience identifying subtle bugs, race conditions, edge cases, and architectural weaknesses that lead to outages and unexpected behavior. You think like a chaos engineer — always asking "what could go wrong?" — and like a maintainer of ten years, always asking "what will this cost to live with?" There are no bugs, and no security holes, in code that doesn't exist.
|
||||
@@ -10,15 +11,15 @@ You are an elite stability-focused code reviewer with deep expertise in defensiv
|
||||
## First Steps
|
||||
|
||||
1. **Scope the change.** You review every PR; a fresh invocation has no prior context, so determine the diff yourself. Diff the PR branch against its base (`gh pr diff`, or `git merge-base <base> HEAD` then `git diff`), and review the changed lines **plus enough surrounding code and callers** to judge correctness — read the whole changed file when practical; a diff alone hides whether a caller breaks. Read the PR description and, when the project uses an issue tracker (project-specific — check its docs) and the change references a ticket, that ticket: the diff is judged against its stated intent, and a scope mismatch in either direction is a finding — claimed-but-unimplemented, and implemented-but-unasked (#2).
|
||||
2. **Read every file under `~/.claude/principles/`**, the shared principles, and `~/.claude/skills/larv-review/standards/quality.md`. These are mandatory org guidelines; all code MUST comply with each that applies. A file's `Applies to` line says what it covers; one without the line covers every change. Re-read each time — they change. Flag violations prominently.
|
||||
3. **Read README.md, AGENTS.md and `docs/decisions.md`** in the current project for project-specific conventions, build instructions, tooling, and the accepted trade-offs a reviewer should honor rather than re-flag. Note the documented test, lint, and static-analysis commands — you will run them.
|
||||
4. **Verify, don't just read.** Run the test suite and static analysis/linters through the project's container tooling, unless a decision puts them on the host; tear down test containers afterwards. Run the full suite under `~/.claude/bin/run-heavy`. Run it in the background or with the Bash tool's longest timeout: that timeout includes the wait for a slot. A full-suite run catches broken callers that diff-reading misses. When a suspected bug is cheap to confirm, reproduce it — a scratch script, a targeted test run — before reporting it. Make scratch work with Bash, since Write is for your report alone. Put it in a directory you create for this run, and delete it when done; delete nothing else, since a directory the prompt names may hold other agents' files. Leave the working tree exactly as you found it. Anything you could not run goes in Coverage & Verification, never silently skipped.
|
||||
5. **Mutation-test the changed lines.** Run the project's documented mutation command, or else a widely deployed mutation tool for the language: cargo-mutants for Rust, Infection for PHP, mutmut for Python, Stryker for JavaScript and TypeScript. Limit it to the lines the change adds or modifies, through the tool's own option where it has one (cargo-mutants `--in-diff <diff file>`, Infection `--git-diff-lines`, Stryker `--mutate <file>:<lines>`); otherwise mutate only the changed files and keep only the mutants on changed lines. Run it through the project's tooling and run-heavy, as in step 4, on a scratch copy: the tools write files. Under run-heavy, a container that sets neither memory limit gets the slot's share, in MiB in `RUN_HEAVY_MEMORY`. Set the tool's concurrency so that its parallel test runs together fit in that share. Report its wall time and mutant count in Coverage & Verification, or why nothing was mutated. Ignore a surviving mutant that leaves behaviour unchanged, or changes only message or log text no caller or user depends on. Report one 🟡 per test to add or strengthen, naming the surviving mutants it would catch.
|
||||
2. **Read every file in the folder your prompt's `Technical principles:` line names**, and `quality.md` in the folder your prompt's `Review standards:` line names. These are mandatory guidelines; all code MUST comply with each that applies. A file's `Applies to` line says what it covers; one without the line covers every change. Re-read each time — they change. Flag violations prominently. Where your prompt lacks either line, open your report by saying so.
|
||||
3. **Read README.md, AGENTS.md and `docs/decisions.md`** in the current project for project-specific conventions, build instructions, tooling, and the accepted trade-offs a reviewer should honor rather than re-flag. Note the documented test, lint, and static-analysis commands — you run them unless your prompt hands you a passing run on the head (step 4).
|
||||
4. **Verify, don't just read.** Where your prompt hands you the commit on which the worker's run of the test suite and static analysis last passed, and it is the head, don't run them again, and say so in Coverage & Verification. Otherwise run the test suite and static analysis/linters through the project's container tooling, unless `~/.claude/bin/project-config tooling-on-host` prints true or a decision puts them on the host; tear down test containers afterwards. Run the full suite under `~/.claude/bin/run-heavy`. Run it in the background or with the Bash tool's longest timeout: that timeout includes the wait for a slot. A full-suite run catches broken callers that diff-reading misses. When a suspected bug is cheap to confirm, reproduce it — a scratch script, a targeted test run — before reporting it. Make scratch work with Bash, since Write is for your report alone. Put it in a directory you create for this run, and delete it when done; don't delete anything else, since a directory the prompt names may hold other agents' files. Leave the working tree exactly as you found it. Anything you could not run goes in Coverage & Verification, never silently skipped.
|
||||
5. **Judge the surviving mutants.** Your prompt hands you what the project's mutation command printed on the change, with the commit it ran on: the mutants of changed lines that no test kills, or the message of a run that failed. Ignore a surviving mutant that leaves behaviour unchanged, or changes only message or log text no caller or user depends on. Report one 🟡 per test to add or strengthen, naming the surviving mutants it would catch. Where the prompt doesn't hand you any output, or names a commit other than the head, run the command yourself in the change's checkout, through run-heavy as in step 4: the one the project's README documents, else `~/.claude/bin/run-heavy ~/.claude/bin/mutate-changes --prefix '<how the project runs its tools>'`. `~/.claude/bin/mutate-changes --help` says which tool it runs for each language, how to set `--jobs`, and what it prints. Mutation-test the changed code that no run mutated, in a language mutate-changes doesn't cover or where a run failed, with a widely deployed mutation tool limited to the changed lines, else with mutants you make by hand. Report the wall time and mutant count in Coverage & Verification, or why nothing was mutated.
|
||||
6. **Two passes minimum, then hunt absences.**
|
||||
- *Breadth:* every hunk in every changed file, no skimming. Track which files you have covered; batch large diffs, never truncate the review.
|
||||
- *Depth:* trace the riskiest data paths end-to-end (input → logic → persistence/response), the interactions between changed pieces, and between the change and config (timeout hierarchies, retries × idempotency, queue worker counts, env parity).
|
||||
- *Absences:* what should be in this diff but isn't — un-updated callers (grep every changed or renamed public symbol), missing migration for a model change, missing authz on a new path, missing tests, un-regenerated OpenAPI/docs, stale README/AGENTS.md, and deletions the change obsoletes but didn't make.
|
||||
- Repeat a targeted pass over the riskiest files; stop only when a pass yields nothing new.
|
||||
- Repeat a targeted pass over the riskiest files; stop only when a pass doesn't find anything new.
|
||||
|
||||
## Review Focus Areas
|
||||
|
||||
@@ -71,6 +72,7 @@ Catch behavior that is unclear or under-specified — "building in ambiguousness
|
||||
- Are there potential off-by-one errors?
|
||||
- Zero and absent are different values: `empty('0')`, `if ($amount)`, `$x ?: $default`, JS `||` conflate them one way; null coerced to `'0'` conflates them the other (a past prod bug: phantom 0-amount reversals). Both directions are findings.
|
||||
- Multibyte text (åäö): truncation, length checks, and comparisons must be mb-safe; encoding consistent end-to-end.
|
||||
- Where the change splits text on a separator or strips a suffix, look in the fixtures and a sample of the source data for a value where the separator or suffix also occurs as data, such as an address split on `,` whose last part holds a comma. Report a row the parse then misplaces or drops, silently or with only a log line.
|
||||
- Are payload and collection sizes bounded at the boundary?
|
||||
|
||||
### 6. Concurrency & State Management
|
||||
@@ -88,6 +90,7 @@ Catch behavior that is unclear or under-specified — "building in ambiguousness
|
||||
- Are consumers idempotent under at-least-once delivery (webhooks, queue retries, double-submit)? Where a duplicate would double-charge or double-send, is there an idempotency key or dedup?
|
||||
- Do DB constraints (NOT NULL, unique, FK) mirror what the code assumes, so bad data cannot arrive via another path?
|
||||
- New column on an existing table: what do existing rows contain — is null/default handled or backfilled?
|
||||
- Where the change stores a value differently, by escaping, converting or growing it: does the longest value it can now write still fit the column, counted as stored? Does every search, filter and comparison on the column still find what users type? Escaped text takes more room than the input's limit allows for, and a `LIKE` on an escaped column no longer matches an apostrophe.
|
||||
|
||||
### 8. Resources & Performance Under Production Data
|
||||
Works-on-fixtures, dies-on-volume is a stability bug.
|
||||
@@ -124,12 +127,14 @@ Every PR gets at least this sweep.
|
||||
- Was a test deleted while the behaviour it pinned remains? Flag it; restore the test.
|
||||
- Were tests and implementation changed together in a way that could mask a regression — e.g. an assertion weakened to make a test pass? Flag it; these should be separate changes.
|
||||
- Does each test earn its keep, as the technical principles' test bullet says? Look at where its expected values come from, what it asserts, what it mocks, what wording it pins, whether another test already pins the behaviour, and whether it sleeps or reads the wall clock.
|
||||
- Does a test decide at run time whether to check anything, by a conditional skip, early return or catch around its assertions, as the technical principles' test bullet forbids? Flag it.
|
||||
- Does a test that runs on a shared environment hold the rules for such a test in the technical principles' "Compose, do not entangle" → "Tests and tooling"? Does the test that covers a seam to a service the team runs mock that service, which the test bullet's "Never mock a service your own team runs" forbids?
|
||||
- Are there untestable side effects that should be refactored?
|
||||
|
||||
|
||||
## Output Format
|
||||
|
||||
Report only a defect, a requirement of the plan, the README's goals or code health (`~/.claude/CLAUDE.md` → "Shared goal", unless the README voids it) that the change breaks, a breach of a technical principle, and the places the prompt hands you. A finding that is none of these is noise, however true: leave it out.
|
||||
Report only a defect; a requirement that the change breaks, of the plan in the file your prompt's `Plan:` line names, of the goals in the file your prompt's `Goals and audience:` line names, or of code health (`~/.claude/CLAUDE.md` → "Shared goal", unless that file voids it); a breach of a technical principle, or of a coding convention, which counts as one; and the places the prompt hands you. A finding that is none of these is noise, however true: leave it out.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. After the verdict, a short **Coverage & Verification** block: what you ran (tests, static analysis, mutation — and their results), what you could not verify and why, and any files that got a lighter pass — never let silence imply coverage. Then the findings, most severe first, each with:
|
||||
- **Location**: File and line/function
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
name: systems-architect
|
||||
description: "Use this agent when designing new systems, planning major features, reviewing architectural decisions in PRs, or evaluating the high-level structure of a codebase. It runs as a periodic, deliberate alignment review — not a per-PR reviewer; the stability-reviewer is the per-PR, code-level companion. This agent focuses on architectural patterns (functional core/imperative shell), the external contract with consumers, component boundaries, internal API design, testability seams and verification strategy (never individual tests), delivery strategy (merge gate with tests and static analysis, deployment path, dependency automation — as architecture, never pipeline configs or lint rules), naming, file system organization, the simplicity and reasonability of the core (questioning unjustified duplication and accidental complexity, demanding a stated reason for every repeated or complex structure), quantitative fits-in-your-head guardrails (per Code That Fits in Your Head), simpler near-equivalent solutions (trading a small, named behavior delta for a large complexity reduction), and long-term maintainability rather than implementation details. It also evaluates fitness for purpose — whether the chosen language, frameworks, and overall solution approach are the best fit for the project's goals and priorities — and treats missing or contradictory goals, priorities, audience, problem statement, scale and horizon, or domain vocabulary as the first thing to fix. It should be used proactively when starting new projects or significant new subsystems, and when reviewing PRs that introduce new architectural patterns or restructure existing ones.\\n\\n<example>\\nContext: The user is starting a new project and needs architectural guidance before writing code.\\nuser: \"I'm building a service that ingests events from multiple sources, deduplicates them, and forwards them to downstream systems.\"\\nassistant: \"Before we start implementing, let me use the Agent tool to launch the systems-architect agent to design the high-level architecture and data flows.\"\\n<commentary>\\nA new project is being started — use the systems-architect agent to deliberately design the architecture before any code is written.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: A PR has been opened that introduces a new module or restructures existing components.\\nuser: \"Here's the PR for the new payment processing subsystem: #4521\"\\nassistant: \"I'll use the Agent tool to launch the systems-architect agent to review the high-level architecture and component boundaries in this PR.\"\\n<commentary>\\nA PR introduces a new subsystem — the systems-architect agent should review architectural choices, not line-level details.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user is adding a significant new feature that crosses multiple components.\\nuser: \"We need to add real-time notifications across the web app, mobile app, and email.\"\\nassistant: \"This crosses several system boundaries. Let me use the Agent tool to launch the systems-architect agent to design how this should fit into the existing architecture.\"\\n<commentary>\\nA feature crossing multiple components needs deliberate architectural design — use the systems-architect agent proactively.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user asks for an architecture review but the project has no clearly stated goals or priorities.\\nuser: \"Can you review the architecture of our new sync service?\"\\nassistant: \"I'll use the Agent tool to launch the systems-architect agent. Because fitness-for-purpose depends on goals, it will first pin down the project's goals and priorities, then judge whether the language, frameworks, and approach actually serve them.\"\\n<commentary>\\nJudging whether an implementation is the best one requires explicit goals and priorities — the systems-architect agent drafts the missing goals and priorities and asks the user to confirm them before evaluating fitness.\\n</commentary>\\n</example>"
|
||||
description: "Use this agent to design a system or review architecture: patterns, component boundaries, fitness for purpose and long-term maintainability, not individual PR lines."
|
||||
tools: Read, Grep, Glob, WebFetch, WebSearch, Write
|
||||
omitClaudeMd: true
|
||||
---
|
||||
You are an elite Systems Architect with decades of experience designing software systems that endure for as long as their horizon demands. Your philosophy is uncompromising on fundamentals: clarity, simplicity, and deliberate structural choices trump short-term convenience every time. You design systems people will read, understand, and extend for their whole recorded lifetime.
|
||||
|
||||
@@ -17,7 +18,7 @@ You are an elite Systems Architect with decades of experience designing software
|
||||
|
||||
**Question the requirement, not just the structure.** Complexity with a reason is not automatically worth its cost. For every complexity hotspot — reasoned or not — name the requirement that forces it and sketch the simpler design that drops or relaxes it. When a near-equivalent solution achieves almost the same result far more simply, propose the trade and name the delta precisely ("drop per-source ordering → the entire reorder buffer disappears") so the owner can accept or reject it. A small, named loss of functionality bought with a large complexity reduction is one of the best wins available — surfacing that option is your job; deciding it is the owner's.
|
||||
|
||||
**Simple to reason about, not merely simple to call.** A clean external API over a core you cannot follow to the bottom is a hollow win. Trace the key data structures and core abstractions down to their foundation and confirm the core is genuinely simple to *understand*, not just convenient to *implement against*. Hold every module to "Prefer deep modules" in `~/.claude/principles/technical-principles.md`. Complexity is dependencies + obscurity, and it surfaces as change amplification (one change touches many places) and cognitive load (a reader must hold too much in their head). Hunt both, all the way down.
|
||||
**Simple to reason about, not merely simple to call.** A clean external API over a core you cannot follow to the bottom is a hollow win. Trace the key data structures and core abstractions down to their foundation and confirm the core is genuinely simple to *understand*, not just convenient to *implement against*. Hold every module to "Prefer deep modules" in the technical principles, the folder your prompt's `Technical principles:` line names (without one, open your report by saying so). Complexity is dependencies + obscurity, and it surfaces as change amplification (one change touches many places) and cognitive load (a reader must hold too much in their head). Hunt both, all the way down.
|
||||
|
||||
**Be non-pragmatic about fundamentals.** You are deliberately uncompromising on architectural choices that shape the system for years. Do not bend on:
|
||||
- Functional core, imperative shell separation
|
||||
@@ -42,7 +43,7 @@ Short-term pragmatism on these points compounds into long-term decay. Push back
|
||||
|
||||
At every altitude — system, component, class, method — the thing in view must be graspable with the details below abstracted away. This is the fractal test: zoom in anywhere and what you see still fits. A design only comprehensible by holding two levels at once has failed it, however clean each level looks in isolation. A new developer should explain what the system does from its structure in under 30 minutes; where they cannot, find the level that fails.
|
||||
|
||||
The limits per level are the technical principle "About seven things per level" in `~/.claude/principles/technical-principles.md`. A unit over one is first a prompt to check responsibilities: if it holds several, split along the concept boundaries. If it holds one, decompose it into named steps a reader can follow one at a time, or let it stay whole for a reason the principle accepts. "Single responsibility" answers the count of responsibilities, never the count of things a reader must hold in their head. A unit past a limit with no recorded reason is a 🟡. It is a 🔴 only where you name what a reader cannot hold: the failed fractal test is the defect, never the count. A core method nobody can hold in their head is a structural finding, never style.
|
||||
The limits per level are the technical principle "About seven things per level" in the technical principles. A unit over one is first a prompt to check responsibilities: if it holds several, split along the concept boundaries. If it holds one, decompose it into named steps a reader can follow one at a time, or let it stay whole for a reason the principle accepts. "Single responsibility" answers the count of responsibilities, never the count of things a reader must hold in their head. A unit past a limit with no recorded reason is a 🟡. It is a 🔴 only where you name what a reader cannot hold: the failed fractal test is the defect, never the count. A core method nobody can hold in their head is a structural finding, never style.
|
||||
|
||||
## Operating Mode: Staged
|
||||
|
||||
@@ -51,11 +52,11 @@ You work in distinct stages. Never skip stages. Never collapse them. Goals, audi
|
||||
### Stage 0: Establish goals, audience, scale & domain language (do this first)
|
||||
You cannot judge whether an implementation is the best one without a yardstick. The yardstick is five artifacts: **the audience** (who this is for — concrete roles, not "users"), **the problem statement** (what hurts without this), **the goals and their priority order** (including which failure classes are intolerable — the correctness targets the test machinery is priced against), **the scale & horizon** (expected load and data volume in orders of magnitude, team and consumer count, and the intended lifetime — throwaway experiment / MVP / production / long-lived platform — with a promotion event, the one that graduates it and forces re-review), and **the domain glossary** — the ubiquitous language: each core domain concept, one name, one line of meaning. Every name in the design must come from it.
|
||||
|
||||
- **Gather** them — read the README, CLAUDE.md, AGENTS.md, the shared principles at `~/.claude/principles/` (org-wide constraints every design must satisfy), the relevant ticket, and any design docs. What isn't written down is a question for the user.
|
||||
- **Gather** them — read the goals and audience in the file your prompt's `Goals and audience:` line names, or in the README where the prompt has no such line; then the README, CLAUDE.md, AGENTS.md, the technical principles (constraints every design must satisfy), the relevant ticket, and any design docs. What isn't written down is a question for the user.
|
||||
- **Test** them: Is the audience concrete? Does the problem statement name the pain, not the solution? Are the goals explicit, prioritized so you know which wins when two collide, and mutually consistent? Is the horizon stated — spike or platform? Nothing is fit for a purpose whose size and lifespan are unknown. Does the glossary give each concept exactly one name?
|
||||
- **Fix first if broken.** Unless the purpose and goals are stated and consistent, surfacing the gap IS this run's deliverable: you execute one-shot and cannot pause for answers, so return a short draft of the missing artifacts plus the questions the user must answer, and stop there — design or review continues in a later invocation, once the agreed result is recorded. A missing audience, problem statement, scale & horizon, or glossary is the same fix-first gap. Never design against guessed goals, a guessed audience, or invented vocabulary — surface the ambiguity instead.
|
||||
|
||||
Output: agreed audience, problem statement, ordered goals, scale & horizon, and domain glossary. Only once these are recorded in the README do you proceed to Stage 1. The requirement never scales down; the artifacts do — a weekend spike answers all five at spike depth: five lines in a README, not five documents. Refuse to proceed without answers; never demand more depth than the recorded horizon justifies.
|
||||
Output: agreed audience, problem statement, ordered goals, scale & horizon, and domain glossary. Only once these are recorded, the audience and goals where you read them and the rest in the README, do you proceed to Stage 1. The requirement never scales down; the artifacts do — a weekend spike answers all five at spike depth: five lines in a README, not five documents. Refuse to proceed without answers; never demand more depth than the recorded horizon justifies.
|
||||
|
||||
### Stage 1: Describe
|
||||
Produce an architectural description covering:
|
||||
@@ -127,7 +128,7 @@ You review the seams that make verification possible and the strategy that uses
|
||||
- **The pyramid follows the boundaries.** Coverage is end-to-end; the pyramid decides at which layer. Each suite earns its existence by naming the failure class only it can catch and its time and determinism budget — how fast it must run and how hermetic it must be. Core logic at the bottom, real-adapter integration at the seams (the actual DB, the actual queue) in the middle, a thin hermetic e2e layer (owned clock, seeded data, faked third parties) proving the wiring on a handful of critical journeys — an e2e failure is a deployment signal, not the primary bug detector. Anything testable at a cheaper layer moves down; an inverting pyramid signals boundaries the design failed to provide. A flaky test is a missing seam and a finding, never a retry policy. Prefer sociable tests with fakes over mock-heavy solitary ones — a suite that only passes by mocking internals is pinning structure, not behavior: the missing-seam smell again.
|
||||
- **Concurrency is testable or it is untested.** Name every place two flows touch shared state, the invariant that serializes each (transaction, queue, idempotency key, ordering guarantee), and how a test forces the interleaving. A race reachable only by stress-looping is a missing seam — flag the seam as the finding; probabilistic runs are scheduled, never gating.
|
||||
- **The external contract is executably pinned.** Contract tests fail when a published shape breaks — the lock on that one-way door. Price them like the versioning machinery (The External Contract): zero consumers outside your control, defer; many, mandatory.
|
||||
- **Load targets come from Stage 0.** Load and performance tests verify the recorded scale numbers; no recorded scale, nothing to verify — fix Stage 0 first (a rig for unrecorded load is "Hunt the imagined requirement" wearing a QA hat). Data and traffic are production-shaped — a load run against a 1000-row database measures nothing. Runs are scheduled outside the merge gate (see Delivery); determinism here means a repeatable method against fixed thresholds, not identical latencies.
|
||||
- **Load targets come from Stage 0.** Load and performance tests verify the recorded scale numbers; no recorded scale, nothing to verify — fix Stage 0 first (a rig for unrecorded load is "Hunt the imagined requirement" wearing a QA hat). Data and traffic are production-shaped — a load run against a 1000-row database doesn't measure anything. Runs are scheduled outside the merge gate (see Delivery); determinism here means a repeatable method against fixed thresholds, not identical latencies.
|
||||
- **Post-deploy production suites are a designed capability.** Tagged, idempotent synthetic traffic against external surfaces only (API, UI), built once and run twice: post-deploy smoke and scheduled monitoring. It asserts liveness of the deployed surface, not logic — logic determinism lives in the pre-merge suites. Self-cleaning means expendable-by-design: a synthetic tenant or TTL-tagged data reaped out-of-band, never teardown-in-the-test, and never a delete endpoint added to the contract only for tests. Side effects are sandboxed by design — a synthetic checkout must never charge a real card — and the synthetic marking propagates through every downstream sink (telemetry, billing, analytics) so real signals stay uncontaminated; a tag that dies at the API edge is a missing seam.
|
||||
|
||||
## Delivery (the path to production is architecture)
|
||||
@@ -163,7 +164,7 @@ Focus on architectural alignment:
|
||||
- Does it add complexity that could be avoided — including by relaxing the requirement that forces it? If a simpler design gets almost the same result, name it and the behavior delta rather than accepting the complex shape as given.
|
||||
- Does it duplicate a concept that already exists instead of reusing it? (see "One concept, one implementation".)
|
||||
- Does it build generality for a scale or future the Stage 0 record doesn't name? Same weight as unreasoned duplication (see "Hunt the imagined requirement").
|
||||
- Does it push a core unit past a limit of "About seven things per level" in `~/.claude/principles/technical-principles.md`?
|
||||
- Does it push a core unit past a limit of "About seven things per level" in the technical principles?
|
||||
- Does it match the patterns documented in the README?
|
||||
- Take the language and framework as given — only reopen foundational choices when the work itself does (see Evaluating Foundational Choices).
|
||||
|
||||
@@ -177,13 +178,13 @@ This is where unjustified duplication and accidental complexity get caught. Run
|
||||
|
||||
1. **Inventory the core concepts.** List the handful of ideas the system is really built on (e.g. "the navigation menu", "a list+filter+paginate page", "a form", "the request context"). For each, find *every* place it is implemented.
|
||||
2. **One concept, one implementation — or a stated reason.** If a concept is implemented more than once, each copy must point to a concrete reason it cannot be the shared one. No reason → collapse to one. Slight, undesigned variation between copies is the signature of copy-paste drift, not deliberate design.
|
||||
3. **Trace to the bottom — and walk the long chains.** Follow the central data structures and abstractions down to their foundation. Can you hold the core in your head? Is anything obscure, implicit, or magical on the way down? A core you cannot explain to the bottom is the defect, even when every layer looks tidy. Then pick the system's key operations and follow each call chain end-to-end (entry point → … → persistence/response). Every hop must add a decision, a transformation, or a boundary that earns its keep; a pass-through layer that only forwards is change amplification plus cognitive load with no payoff — name the collapse concretely (which layer folds into which). A chain, like a unit, must fit in a head (the limit on hops in "About seven things per level" in `~/.claude/principles/technical-principles.md`).
|
||||
3. **Trace to the bottom — and walk the long chains.** Follow the central data structures and abstractions down to their foundation. Can you hold the core in your head? Is anything obscure, implicit, or magical on the way down? A core you cannot explain to the bottom is the defect, even when every layer looks tidy. Then pick the system's key operations and follow each call chain end-to-end (entry point → … → persistence/response). Every hop must add a decision, a transformation, or a boundary that earns its keep; a pass-through layer that only forwards is change amplification plus cognitive load with no payoff — name the collapse concretely (which layer folds into which). A chain, like a unit, must fit in a head (the limit on hops in "About seven things per level" in the technical principles).
|
||||
4. **Naming and placement.** If a name, or its location in the tree, does not tell a new reader what it is and where it belongs, that is a defect — not a note. Names come from the domain glossary; the hierarchy should mirror the architecture with no translation. When a subsystem has been consolidated into its own folder/namespace, confirm *every* member lives there: a collaborator stranded in the parent (typically one the refactor didn't scope in, so it predates the move) breaks the mirror as badly as a misnamed file — a finding even when nothing imports it wrongly. Check both directions: the sibling in the parent that should have moved in, and the file inside the subfolder that actually belongs to a different layer. Ask of each remaining sibling in the parent: why is this *here* and not *there* with its peers? "It predated the move" is not a reason. Enumerate what's left in the parent namespace and justify each one, rather than only inspecting the files that changed.
|
||||
5. **A flat directory is a smell at scale.** Count the files in each source directory. One folder holding many modules with no sub-structure (rule of thumb: **more than ~15–20 source files**, or a directory a newcomer can't skim to locate a concern) hides the architecture instead of mirroring it — the larger it grows, the more it costs to navigate, and "we'll group it later" never comes. This is a structural defect, not cosmetic polish: flag it and **propose a concrete grouping by concern**, naming which files go into which folder (e.g. `http/`, `auth/`, `admin/`, `plugin-host/`, `ui/`), derived from the core concepts the inventory already surfaced; co-locate tests with their module. Push for the reorganization rather than merely noting the count. The only thing that excuses a large flat tree is the project documenting it as a deliberate, reasoned deviation (and even then, re-test the reason as the file count climbs).
|
||||
6. **Price the reasoned complexity too.** Essential-looking complexity has a requirement behind it. For each hotspot that survives the steps above, name that requirement, then sketch the design without it. When a much simpler near-equivalent exists, report the trade as a finding: the simpler shape, the exact functionality delta, and the complexity saved. A requirement nobody has priced is not a decision — offer the trade once, plainly, and let the owner accept or reject it.
|
||||
7. **Hunt the imagined requirement.** The step above prices complexity a real requirement forces; this one removes complexity no requirement forces. For every abstraction, indirection, configuration point, and layer of generality, name the present, Stage 0-recorded requirement it serves. An interface with one implementation, a plugin system with one plugin, a cache or shard — or a load-testing rig — for load nobody recorded, a canary rig for a blast radius nobody recorded, "in case we swap the database" — speculative generality is the over-engineered twin of copy-paste drift: complexity nobody's requirement chose. The future that justifies flexibility must be a recorded goal or horizon, not the author's imagination — and the shorter the horizon, the harder this step cuts. Rate removals with the same severity as unreasoned duplication.
|
||||
|
||||
Respect documented deliberate deviations — a stated trade-off is a valid reason (`docs/decisions.md`), unless it works against a goal or a technical principle and names no `todo.md` item ending it. Respecting it means not re-arguing the same trade with the same facts; it does not forbid offering a materially simpler alternative the decision never considered — offer it once with the exact delta, then drop it if declined. The target is the *un*reasoned: duplication, complexity, and confusion that nobody decided and nobody can defend. "Acceptable for now", "will compound later", and "converge in a future pass" are how a small drift becomes the permanent shape of the system.
|
||||
Respect documented deliberate deviations — a stated trade-off is a valid reason (`docs/decisions.md`), unless it works against a goal or a technical principle and names no plan item ending it. Respecting it means not re-arguing the same trade with the same facts; it does not forbid offering a materially simpler alternative the decision never considered — offer it once with the exact delta, then drop it if declined. The target is the *un*reasoned: duplication, complexity, and confusion that nobody decided and nobody can defend. "Acceptable for now", "will compound later", and "converge in a future pass" are how a small drift becomes the permanent shape of the system.
|
||||
|
||||
## Communication Style
|
||||
|
||||
|
||||
@@ -0,0 +1,233 @@
|
||||
"""Converts markdown to ADF (Atlassian Document Format, the rich text of Jira Cloud and Confluence) and back.
|
||||
|
||||
It runs @larvit/adf-codec, a Node package, in a throwaway container that holds node_shim/shim.mjs; the shim's header says what its exit status means.
|
||||
|
||||
adf-codec has two pairs of calls, and each function here names the one it runs:
|
||||
- The portable pair, with no suffix, which the loop's tools use. It drops each block's localId and the empty paragraphs Jira uses for spacing, so saving a document read by it changes the document; a tool that saves one unedited sends nothing instead (`docs/decisions.md` → `project config: the loop shows a Jira description and a Confluence page as adf-codec's portable markdown, …`).
|
||||
- The lossless pair, `*_lossless`, which keeps both, so a document read and saved unedited comes back identical. Its markdown wraps every block in `!adf:` marker lines, so no tool reads by it yet.
|
||||
"""
|
||||
import contextlib
|
||||
import dataclasses
|
||||
import fcntl
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
import pathlib
|
||||
import subprocess
|
||||
import sys
|
||||
import time
|
||||
import typing
|
||||
|
||||
from failure import Failure
|
||||
from machine_load.slots import HELD, Lock, slot_count, slot_folder, usable_cpus, waited_slot
|
||||
|
||||
SHIM = pathlib.Path(__file__).resolve().parent / "node_shim"
|
||||
SHIM_FILES = ("Dockerfile", "package.json", "package-lock.json", "shim.mjs")
|
||||
# `--memory` and `--memory-swap` both take this, so the container can't swap: a document too big for it ends in a Failure.
|
||||
MEMORY = "256m"
|
||||
RUN_SECONDS = 60
|
||||
BUILD_SECONDS = 300
|
||||
REFUSED = 2
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Ran:
|
||||
status: int
|
||||
out: str
|
||||
err: str
|
||||
|
||||
|
||||
# Runs the shim in the given mode (`to-adf`, `to-markdown`, `to-adf-lossless` or `to-markdown-lossless`) on a text, or fails to run it.
|
||||
Run = typing.Callable[[str, str], Ran | Failure]
|
||||
# Runs a docker command line on a text, in at most the given seconds, or fails to run it.
|
||||
Docker = typing.Callable[[list[str], str, int], Ran | Failure]
|
||||
# Holds one of the machine's heavy slots for a with block, or yields why none could be taken.
|
||||
Slot = typing.Callable[[], typing.ContextManager[Failure | None]]
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Refused:
|
||||
"""Why adf-codec refused one of the documents handed to adfs_to_markdown, and that document's index among them."""
|
||||
index: int
|
||||
failure: Failure
|
||||
|
||||
|
||||
def image_tag(shim: pathlib.Path) -> str:
|
||||
"""A tag that changes with every file the image is built from, so an edited shim or a bumped adf-codec builds a new image."""
|
||||
digest = hashlib.sha256()
|
||||
for name in SHIM_FILES:
|
||||
digest.update((shim / name).read_bytes())
|
||||
return f"claude-config-adf-codec:{digest.hexdigest()[:12]}"
|
||||
|
||||
|
||||
def docker_args(image: str, mode: str) -> list[str]:
|
||||
return ["docker", "run", "--rm", "-i", "--memory", MEMORY, "--memory-swap", MEMORY, "--network", "none", "--read-only", image, mode]
|
||||
|
||||
|
||||
def docker(args: list[str], text: str, seconds: int) -> Ran | Failure:
|
||||
"""docker_ran with subprocess.run: the one place that starts docker as a process."""
|
||||
return docker_ran(args, text, seconds, subprocess.run)
|
||||
|
||||
|
||||
def docker_ran(args: list[str], text: str, seconds: int, call: typing.Callable[..., typing.Any]) -> Ran | Failure:
|
||||
"""Runs a docker command line through call, with text on its stdin: what it exited with and printed, or a Failure where docker is missing or takes more than seconds. call runs a command line as subprocess.run does."""
|
||||
try:
|
||||
done = call(args, input=text, capture_output=True, text=True, encoding="utf-8", timeout=seconds)
|
||||
except FileNotFoundError:
|
||||
return Failure("docker is not installed, and the adf-codec shim runs in a container")
|
||||
except subprocess.TimeoutExpired:
|
||||
return Failure(f"`{' '.join(args[:2])}` took more than {seconds} seconds")
|
||||
return Ran(done.returncode, done.stdout, done.stderr)
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def machine_slot() -> typing.Iterator[Failure | None]:
|
||||
"""heavy_slot with this process's environment, home folder, processor count, stderr, sleep and flock."""
|
||||
with heavy_slot(os.environ, pathlib.Path.home(), slot_count(usable_cpus()), lambda text: print(text, file=sys.stderr, flush=True), time.sleep, fcntl.flock) as refused:
|
||||
yield refused
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def heavy_slot(env: typing.Mapping[str, str], home: pathlib.Path, slots: int, say: typing.Callable[[str], None], sleep: typing.Callable[[float], None], lock: Lock) -> typing.Iterator[Failure | None]:
|
||||
"""Holds one of the machine's heavy slots, which run-heavy shares, for the with block, telling say where it waits for one. Under run-heavy the process already holds one, so it doesn't wait."""
|
||||
if HELD in env:
|
||||
yield None
|
||||
return
|
||||
folder = slot_folder(env, home)
|
||||
try:
|
||||
folder.mkdir(parents=True, exist_ok=True)
|
||||
_, fd = waited_slot(folder, slots, lambda: say(f"adf-codec: waiting for a heavy slot, of {slots} on this machine, in {folder}, to build the shim's image; `fuser {folder}/slot-*` names the processes that hold them"), sleep, lock)
|
||||
except OSError as failure:
|
||||
yield Failure(f"cannot take a heavy slot in {folder}: {failure.strerror}")
|
||||
return
|
||||
try:
|
||||
yield None
|
||||
finally:
|
||||
os.close(fd)
|
||||
|
||||
|
||||
def ensure_image(shim: pathlib.Path, run_docker: Docker = docker, slot: Slot = machine_slot) -> str | Failure:
|
||||
"""The tag of the image for the shim folder, built from that folder first where this machine has no image under that tag.
|
||||
|
||||
The build waits for a heavy slot. Once this process holds the slot, it inspects again, as another process may have built the image meanwhile."""
|
||||
tag = image_tag(shim)
|
||||
found = image_found(tag, run_docker)
|
||||
if found is not False:
|
||||
return tag if found is True else found
|
||||
with slot() as refused:
|
||||
if refused is not None:
|
||||
return refused
|
||||
found = image_found(tag, run_docker)
|
||||
if found is not False:
|
||||
return tag if found is True else found
|
||||
return build_image(shim, tag, run_docker)
|
||||
|
||||
|
||||
def image_found(tag: str, run_docker: Docker) -> bool | Failure:
|
||||
found = run_docker(["docker", "image", "inspect", tag], "", RUN_SECONDS)
|
||||
return found if isinstance(found, Failure) else found.status == 0
|
||||
|
||||
|
||||
def build_image(shim: pathlib.Path, tag: str, run_docker: Docker) -> str | Failure:
|
||||
ran = run_docker(["docker", "build", "--quiet", "--memory", "1g", "--memory-swap", "1g", "--tag", tag, str(shim)], "", BUILD_SECONDS)
|
||||
if isinstance(ran, Failure):
|
||||
return ran
|
||||
if ran.status != 0:
|
||||
return Failure(f"building the adf-codec shim's image failed with exit {ran.status}: {ran.err.strip()}")
|
||||
return tag
|
||||
|
||||
|
||||
def container_run(mode: str, text: str, run_docker: Docker = docker, shim: pathlib.Path = SHIM) -> Ran | Failure:
|
||||
image = ensure_image(shim, run_docker)
|
||||
if isinstance(image, Failure):
|
||||
return image
|
||||
return run_docker(docker_args(image, mode), text, RUN_SECONDS)
|
||||
|
||||
|
||||
def answer(mode: str, text: str, run: Run) -> str | Refused | Failure:
|
||||
"""What the shim printed for text, or why it gave no answer: a Refused where it named the refused document's index."""
|
||||
ran = run(mode, text)
|
||||
if isinstance(ran, Failure):
|
||||
return ran
|
||||
if ran.status == 0:
|
||||
return ran.out
|
||||
if ran.status == REFUSED:
|
||||
return refusal(ran.out)
|
||||
return Failure(f"the adf-codec shim failed with exit {ran.status}: {ran.err.strip()}")
|
||||
|
||||
|
||||
def refusal(out: str) -> Refused | Failure:
|
||||
try:
|
||||
refused = json.loads(out)
|
||||
error = refused["error"]
|
||||
where = f"line {error['position']['line']}" if "position" in error else ".".join(str(step) for step in error["path"]) or "the document"
|
||||
failure = Failure(f"adf-codec refused the input with {error['code']}: {error['message']} (at {where})")
|
||||
return Refused(refused["index"], failure) if isinstance(refused.get("index"), int) else failure
|
||||
except (ValueError, KeyError, TypeError, AttributeError):
|
||||
return Failure(f"the adf-codec shim refused with output that is not an error: {out.strip()}")
|
||||
|
||||
|
||||
def to_adf(mode: str, markdown: str, run: Run) -> dict[str, typing.Any] | Failure:
|
||||
out = answer(mode, markdown, run)
|
||||
if isinstance(out, Refused):
|
||||
return out.failure
|
||||
if isinstance(out, Failure):
|
||||
return out
|
||||
try:
|
||||
document = json.loads(out)
|
||||
except ValueError:
|
||||
return Failure(f"the adf-codec shim printed output that is not JSON: {out.strip()}")
|
||||
return document
|
||||
|
||||
|
||||
def to_markdowns(mode: str, documents: list[dict[str, typing.Any]], run: Run) -> list[str] | Refused | Failure:
|
||||
if not documents:
|
||||
return []
|
||||
out = answer(mode, json.dumps(documents), run)
|
||||
if isinstance(out, Refused) and not 0 <= out.index < len(documents):
|
||||
return Failure(f"the adf-codec shim refused a document at index {out.index}, past the {len(documents)} it was handed")
|
||||
if isinstance(out, Refused | Failure):
|
||||
return out
|
||||
try:
|
||||
texts = json.loads(out)
|
||||
except ValueError:
|
||||
texts = None
|
||||
if not isinstance(texts, list) or len(texts) != len(documents) or not all(isinstance(text, str) for text in texts):
|
||||
return Failure(f"the adf-codec shim printed output that is not a JSON array of {len(documents)} texts: {out.strip()}")
|
||||
return texts
|
||||
|
||||
|
||||
def one_markdown(texts: list[str] | Refused | Failure) -> str | Failure:
|
||||
if isinstance(texts, Refused):
|
||||
return texts.failure
|
||||
return texts if isinstance(texts, Failure) else texts[0]
|
||||
|
||||
|
||||
def markdown_to_adf(markdown: str, run: Run = container_run) -> dict[str, typing.Any] | Failure:
|
||||
"""The ADF document for the markdown, by the portable pair."""
|
||||
return to_adf("to-adf", markdown, run)
|
||||
|
||||
|
||||
def markdown_to_adf_lossless(markdown: str, run: Run = container_run) -> dict[str, typing.Any] | Failure:
|
||||
"""The ADF document for the markdown, by the lossless pair."""
|
||||
return to_adf("to-adf-lossless", markdown, run)
|
||||
|
||||
|
||||
def adfs_to_markdown(documents: list[dict[str, typing.Any]], run: Run = container_run) -> list[str] | Refused | Failure:
|
||||
"""The markdown for each ADF document, in their order, by the portable pair, from one container run, so a caller with many documents pays one container start."""
|
||||
return to_markdowns("to-markdown", documents, run)
|
||||
|
||||
|
||||
def adfs_to_markdown_lossless(documents: list[dict[str, typing.Any]], run: Run = container_run) -> list[str] | Refused | Failure:
|
||||
"""The markdown for each ADF document, in their order, by the lossless pair, from one container run."""
|
||||
return to_markdowns("to-markdown-lossless", documents, run)
|
||||
|
||||
|
||||
def adf_to_markdown(document: dict[str, typing.Any], run: Run = container_run) -> str | Failure:
|
||||
"""The markdown for the ADF document, by the portable pair."""
|
||||
return one_markdown(adfs_to_markdown([document], run))
|
||||
|
||||
|
||||
def adf_to_markdown_lossless(document: dict[str, typing.Any], run: Run = container_run) -> str | Failure:
|
||||
"""The markdown for the ADF document, by the lossless pair."""
|
||||
return one_markdown(adfs_to_markdown_lossless([document], run))
|
||||
@@ -0,0 +1,9 @@
|
||||
FROM node:24.19.0-alpine3.24
|
||||
WORKDIR /shim
|
||||
COPY package.json package-lock.json ./
|
||||
RUN npm ci --ignore-scripts --omit=dev
|
||||
COPY shim.mjs ./
|
||||
USER node
|
||||
# The deadline is inside the container, since a timeout in the caller kills only the docker client and leaves the container running.
|
||||
# It is under convert.py's RUN_SECONDS, so it fires first.
|
||||
ENTRYPOINT ["timeout", "50", "node", "shim.mjs"]
|
||||
+22
@@ -0,0 +1,22 @@
|
||||
{
|
||||
"name": "adf-codec-shim",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "adf-codec-shim",
|
||||
"dependencies": {
|
||||
"@larvit/adf-codec": "0.3.1"
|
||||
}
|
||||
},
|
||||
"node_modules/@larvit/adf-codec": {
|
||||
"version": "0.3.1",
|
||||
"resolved": "https://registry.npmjs.org/@larvit/adf-codec/-/adf-codec-0.3.1.tgz",
|
||||
"integrity": "sha512-hI15WrztaGU90nEc2+IeFj16LtqpTxb2hahdhfj/YvdFTwd2lzhdQN1MRG4/65i6FiEZR2lIlFxyIYqx6EXjvg==",
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"name": "adf-codec-shim",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"dependencies": {
|
||||
"@larvit/adf-codec": "0.3.1"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,56 @@
|
||||
// Converts between markdown and ADF with @larvit/adf-codec. The mode is the one argument:
|
||||
// to-adf stdin is markdown, stdout is the ADF document as JSON
|
||||
// to-markdown stdin is a JSON array of ADF documents, stdout a JSON array of their markdown texts, in their order
|
||||
// to-adf-lossless, to-markdown-lossless the same, through adf-codec's lossless pair in place of its portable pair
|
||||
// Exit 0: stdout holds the answer. Exit 2: adf-codec refused the input, and stdout holds {"error": {code, message, path, position?}},
|
||||
// with "index", the refused document's place in the array, beside "error" in to-markdown.
|
||||
// Exit 1: the shim could not run, and stderr says why.
|
||||
import { adfToLosslessMarkdown, adfToPortableMarkdown, losslessMarkdownToAdf, portableMarkdownToAdf } from '@larvit/adf-codec'
|
||||
|
||||
const REFUSED = 2
|
||||
|
||||
async function readStdin() {
|
||||
const chunks = []
|
||||
for await (const chunk of process.stdin) chunks.push(chunk)
|
||||
return Buffer.concat(chunks).toString('utf8')
|
||||
}
|
||||
|
||||
function refuse(refusal) {
|
||||
process.stdout.write(JSON.stringify(refusal))
|
||||
return REFUSED
|
||||
}
|
||||
|
||||
function toAdf(convert, markdown) {
|
||||
const result = convert(markdown)
|
||||
if (!result.ok) return refuse({ error: result.error })
|
||||
process.stdout.write(JSON.stringify(result.value))
|
||||
return 0
|
||||
}
|
||||
|
||||
function toMarkdown(convert, documents) {
|
||||
const texts = []
|
||||
for (const [index, document] of documents.entries()) {
|
||||
const result = convert(document)
|
||||
if (!result.ok) return refuse({ index, error: result.error })
|
||||
texts.push(result.value)
|
||||
}
|
||||
process.stdout.write(JSON.stringify(texts))
|
||||
return 0
|
||||
}
|
||||
|
||||
async function main(mode) {
|
||||
const input = await readStdin()
|
||||
if (mode === 'to-adf') return toAdf(portableMarkdownToAdf, input)
|
||||
if (mode === 'to-adf-lossless') return toAdf(losslessMarkdownToAdf, input)
|
||||
if (mode === 'to-markdown') return toMarkdown(adfToPortableMarkdown, JSON.parse(input))
|
||||
if (mode === 'to-markdown-lossless') return toMarkdown(adfToLosslessMarkdown, JSON.parse(input))
|
||||
throw new Error(`mode must be to-adf, to-adf-lossless, to-markdown or to-markdown-lossless, not ${mode}`)
|
||||
}
|
||||
|
||||
main(process.argv[2]).then(
|
||||
(code) => { process.exitCode = code },
|
||||
(failure) => {
|
||||
process.stderr.write(`${failure instanceof Error ? failure.message : failure}\n`)
|
||||
process.exitCode = 1
|
||||
},
|
||||
)
|
||||
@@ -0,0 +1,343 @@
|
||||
import contextlib
|
||||
import fcntl
|
||||
import json
|
||||
import os
|
||||
import subprocess
|
||||
|
||||
import pytest
|
||||
|
||||
from adf_codec import convert
|
||||
from failure import Failure
|
||||
from machine_load import slots
|
||||
|
||||
DOC = {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Hi"}]}]}
|
||||
|
||||
|
||||
def fake(status: int, out: str = "", err: str = ""):
|
||||
calls: list[tuple[str, str]] = []
|
||||
|
||||
def run(mode: str, text: str) -> convert.Ran:
|
||||
calls.append((mode, text))
|
||||
return convert.Ran(status, out, err)
|
||||
|
||||
run.calls = calls # type: ignore[attr-defined]
|
||||
return run
|
||||
|
||||
|
||||
def test_markdown_to_adf_returns_the_document_the_shim_printed():
|
||||
run = fake(0, json.dumps(DOC))
|
||||
assert convert.markdown_to_adf("Hi\n", run) == DOC
|
||||
assert run.calls == [("to-adf", "Hi\n")]
|
||||
|
||||
|
||||
def test_adfs_to_markdown_sends_every_document_in_one_run_and_returns_the_texts_in_order():
|
||||
run = fake(0, json.dumps(["Hi\n", "Yo\n"]))
|
||||
assert convert.adfs_to_markdown([DOC, DOC], run) == ["Hi\n", "Yo\n"]
|
||||
assert run.calls == [("to-markdown", json.dumps([DOC, DOC]))]
|
||||
|
||||
|
||||
def test_adfs_to_markdown_of_no_documents_runs_no_container():
|
||||
run = fake(1)
|
||||
assert convert.adfs_to_markdown([], run) == []
|
||||
assert run.calls == []
|
||||
|
||||
|
||||
def test_a_refused_document_names_its_index():
|
||||
refusal = {"index": 1, "error": {"code": "not-an-adf-document", "message": "no type", "path": []}}
|
||||
refused = convert.adfs_to_markdown([DOC, DOC], fake(2, json.dumps(refusal)))
|
||||
assert refused == convert.Refused(1, Failure("adf-codec refused the input with not-an-adf-document: no type (at the document)"))
|
||||
|
||||
|
||||
def test_a_refusal_whose_index_is_past_the_documents_becomes_a_failure():
|
||||
refusal = {"index": 2, "error": {"code": "not-an-adf-document", "message": "no type", "path": []}}
|
||||
failure = convert.adfs_to_markdown([DOC, DOC], fake(2, json.dumps(refusal)))
|
||||
assert failure == Failure("the adf-codec shim refused a document at index 2, past the 2 it was handed")
|
||||
|
||||
|
||||
@pytest.mark.parametrize("out", ["not json", json.dumps(["Hi\n"]), json.dumps({"0": "Hi\n"}), json.dumps(["Hi\n", 7])])
|
||||
def test_texts_that_do_not_match_the_documents_become_a_failure(out):
|
||||
failure = convert.adfs_to_markdown([DOC, DOC], fake(0, out))
|
||||
assert failure == Failure(f"the adf-codec shim printed output that is not a JSON array of 2 texts: {out}")
|
||||
|
||||
|
||||
def test_adf_to_markdown_returns_the_text_of_its_one_document():
|
||||
run = fake(0, json.dumps(["Hi\n"]))
|
||||
assert convert.adf_to_markdown(DOC, run) == "Hi\n"
|
||||
assert run.calls == [("to-markdown", json.dumps([DOC]))]
|
||||
|
||||
|
||||
def test_markdown_to_adf_lossless_runs_the_lossless_mode():
|
||||
run = fake(0, json.dumps(DOC))
|
||||
assert convert.markdown_to_adf_lossless("Hi\n", run) == DOC
|
||||
assert run.calls == [("to-adf-lossless", "Hi\n")]
|
||||
|
||||
|
||||
def test_adfs_to_markdown_lossless_sends_every_document_in_one_lossless_run():
|
||||
run = fake(0, json.dumps(["a\n", "b\n"]))
|
||||
assert convert.adfs_to_markdown_lossless([DOC, DOC], run) == ["a\n", "b\n"]
|
||||
assert run.calls == [("to-markdown-lossless", json.dumps([DOC, DOC]))]
|
||||
|
||||
|
||||
def test_adf_to_markdown_lossless_returns_the_text_of_its_one_document():
|
||||
run = fake(0, json.dumps(["a\n"]))
|
||||
assert convert.adf_to_markdown_lossless(DOC, run) == "a\n"
|
||||
assert run.calls == [("to-markdown-lossless", json.dumps([DOC]))]
|
||||
|
||||
|
||||
def test_adfs_to_markdown_lossless_names_a_refused_documents_index():
|
||||
refusal = {"index": 1, "error": {"code": "not-an-adf-document", "message": "no type", "path": []}}
|
||||
refused = convert.adfs_to_markdown_lossless([DOC, DOC], fake(2, json.dumps(refusal)))
|
||||
assert refused == convert.Refused(1, Failure("adf-codec refused the input with not-an-adf-document: no type (at the document)"))
|
||||
|
||||
|
||||
def test_adfs_to_markdown_lossless_of_no_documents_runs_no_container():
|
||||
run = fake(1)
|
||||
assert convert.adfs_to_markdown_lossless([], run) == []
|
||||
assert run.calls == []
|
||||
|
||||
|
||||
def test_a_refusal_becomes_a_failure_with_adf_codecs_code_and_message():
|
||||
refusal = {"error": {"code": "malformed-pipe-table", "message": "row has too many cells", "path": [], "position": {"line": 3, "offset": 9}}}
|
||||
failure = convert.markdown_to_adf("| a |\n", fake(2, json.dumps(refusal)))
|
||||
assert failure == Failure("adf-codec refused the input with malformed-pipe-table: row has too many cells (at line 3)")
|
||||
|
||||
|
||||
def test_a_refusal_without_a_position_names_the_path():
|
||||
refusal = {"index": 0, "error": {"code": "unsupported-node-shape", "message": "bad node", "path": ["content", 0]}}
|
||||
failure = convert.adf_to_markdown(DOC, fake(2, json.dumps(refusal)))
|
||||
assert failure == Failure("adf-codec refused the input with unsupported-node-shape: bad node (at content.0)")
|
||||
|
||||
|
||||
def test_a_shim_that_could_not_run_becomes_a_failure_with_its_stderr():
|
||||
failure = convert.adf_to_markdown(DOC, fake(1, "", "Unexpected token"))
|
||||
assert failure == Failure("the adf-codec shim failed with exit 1: Unexpected token")
|
||||
|
||||
|
||||
def test_a_shim_killed_for_memory_becomes_a_failure_with_its_exit_status():
|
||||
failure = convert.markdown_to_adf("x", fake(137))
|
||||
assert isinstance(failure, Failure) and "137" in failure.reason
|
||||
|
||||
|
||||
def test_output_that_is_not_json_becomes_a_failure():
|
||||
failure = convert.markdown_to_adf("x", fake(0, "not json"))
|
||||
assert failure == Failure("the adf-codec shim printed output that is not JSON: not json")
|
||||
|
||||
|
||||
def test_a_refusal_that_is_not_the_expected_json_becomes_a_failure():
|
||||
failure = convert.markdown_to_adf("x", fake(2, "oops"))
|
||||
assert failure == Failure("the adf-codec shim refused with output that is not an error: oops")
|
||||
|
||||
|
||||
def test_a_failure_from_the_runner_passes_through():
|
||||
def run(mode: str, text: str) -> Failure:
|
||||
return Failure("docker is not installed")
|
||||
|
||||
assert convert.markdown_to_adf("x", run) == Failure("docker is not installed")
|
||||
|
||||
|
||||
def test_the_image_tag_changes_with_the_shim_files(tmp_path):
|
||||
for name in convert.SHIM_FILES:
|
||||
(tmp_path / name).write_text("a")
|
||||
before = convert.image_tag(tmp_path)
|
||||
(tmp_path / "shim.mjs").write_text("b")
|
||||
assert convert.image_tag(tmp_path) != before
|
||||
|
||||
|
||||
def test_the_container_command_line_is_exactly_this():
|
||||
assert convert.docker_args("image:1", "to-adf") == [
|
||||
"docker", "run", "--rm", "-i", "--memory", "256m", "--memory-swap", "256m", "--network", "none", "--read-only", "image:1", "to-adf",
|
||||
]
|
||||
|
||||
|
||||
def test_a_refusal_at_the_root_says_the_document():
|
||||
refusal = {"index": 0, "error": {"code": "not-an-adf-document", "message": "no type", "path": []}}
|
||||
failure = convert.adf_to_markdown(DOC, fake(2, json.dumps(refusal)))
|
||||
assert failure == Failure("adf-codec refused the input with not-an-adf-document: no type (at the document)")
|
||||
|
||||
|
||||
def test_docker_passes_the_text_on_stdin_and_returns_the_output():
|
||||
seen = {}
|
||||
|
||||
def call(args, **kwargs):
|
||||
seen.update(kwargs, args=args)
|
||||
return subprocess.CompletedProcess(args, 3, "out", "err")
|
||||
|
||||
assert convert.docker_ran(["docker", "x"], "text", 7, call) == convert.Ran(3, "out", "err")
|
||||
assert seen == {"args": ["docker", "x"], "input": "text", "capture_output": True, "text": True, "encoding": "utf-8", "timeout": 7}
|
||||
|
||||
|
||||
def test_docker_missing_becomes_a_failure():
|
||||
def call(args, **kwargs):
|
||||
raise FileNotFoundError
|
||||
|
||||
failure = convert.docker_ran(["docker", "x"], "", 7, call)
|
||||
assert failure == Failure("docker is not installed, and the adf-codec shim runs in a container")
|
||||
|
||||
|
||||
def test_docker_that_takes_too_long_becomes_a_failure():
|
||||
def call(args, **kwargs):
|
||||
raise subprocess.TimeoutExpired(args, 7)
|
||||
|
||||
assert convert.docker_ran(["docker", "build", "x"], "", 7, call) == Failure("`docker build` took more than 7 seconds")
|
||||
|
||||
|
||||
def shim_dir(tmp_path):
|
||||
for name in convert.SHIM_FILES:
|
||||
(tmp_path / name).write_text("a")
|
||||
return tmp_path
|
||||
|
||||
|
||||
def scripted(*answers):
|
||||
lines: list[tuple[list[str], str, int]] = []
|
||||
queue = list(answers)
|
||||
|
||||
def run_docker(args, text, seconds):
|
||||
lines.append((args, text, seconds))
|
||||
return queue.pop(0)
|
||||
|
||||
run_docker.lines = lines # type: ignore[attr-defined]
|
||||
return run_docker
|
||||
|
||||
|
||||
def test_an_image_that_exists_is_not_built(tmp_path):
|
||||
run_docker = scripted(convert.Ran(0, "", ""))
|
||||
tag = convert.image_tag(shim_dir(tmp_path))
|
||||
assert convert.ensure_image(tmp_path, run_docker) == tag
|
||||
assert run_docker.lines == [(["docker", "image", "inspect", tag], "", convert.RUN_SECONDS)]
|
||||
|
||||
|
||||
class Slot:
|
||||
"""Stands in for a heavy slot: records the docker lines run while it is held, or yields the given Failure."""
|
||||
def __init__(self, run_docker, failure: Failure | None = None):
|
||||
self.run_docker, self.failure, self.held_lines = run_docker, failure, None
|
||||
|
||||
@contextlib.contextmanager
|
||||
def __call__(self):
|
||||
before = len(self.run_docker.lines)
|
||||
yield self.failure
|
||||
self.held_lines = self.run_docker.lines[before:]
|
||||
|
||||
|
||||
def test_a_missing_image_is_built_from_the_shim_folder_with_a_memory_limit_inside_a_heavy_slot(tmp_path):
|
||||
missing = convert.Ran(1, "", "")
|
||||
run_docker = scripted(missing, missing, convert.Ran(0, "", ""))
|
||||
slot = Slot(run_docker)
|
||||
tag = convert.image_tag(shim_dir(tmp_path))
|
||||
assert convert.ensure_image(tmp_path, run_docker, slot) == tag
|
||||
inspect = (["docker", "image", "inspect", tag], "", convert.RUN_SECONDS)
|
||||
build = (["docker", "build", "--quiet", "--memory", "1g", "--memory-swap", "1g", "--tag", tag, str(tmp_path)], "", convert.BUILD_SECONDS)
|
||||
assert run_docker.lines == [inspect, inspect, build]
|
||||
assert slot.held_lines == [inspect, build]
|
||||
|
||||
|
||||
def test_an_image_another_process_built_while_this_one_waited_for_a_slot_is_not_built_again(tmp_path):
|
||||
run_docker = scripted(convert.Ran(1, "", ""), convert.Ran(0, "", ""))
|
||||
tag = convert.image_tag(shim_dir(tmp_path))
|
||||
assert convert.ensure_image(tmp_path, run_docker, Slot(run_docker)) == tag
|
||||
assert len(run_docker.lines) == 2
|
||||
|
||||
|
||||
def test_a_heavy_slot_that_cannot_be_taken_fails_before_the_build(tmp_path):
|
||||
run_docker = scripted(convert.Ran(1, "", ""))
|
||||
shim_dir(tmp_path)
|
||||
down = Failure("cannot take a heavy slot in /x: Permission denied")
|
||||
assert convert.ensure_image(tmp_path, run_docker, Slot(run_docker, down)) == down
|
||||
assert len(run_docker.lines) == 1
|
||||
|
||||
|
||||
def test_a_failed_build_becomes_a_failure_with_its_stderr(tmp_path):
|
||||
run_docker = scripted(convert.Ran(1, "", ""), convert.Ran(1, "", ""), convert.Ran(5, "", "no network\n"))
|
||||
shim_dir(tmp_path)
|
||||
assert convert.ensure_image(tmp_path, run_docker, Slot(run_docker)) == Failure("building the adf-codec shim's image failed with exit 5: no network")
|
||||
|
||||
|
||||
DOWN, MISSING = Failure("docker is not installed"), convert.Ran(1, "", "")
|
||||
|
||||
|
||||
@pytest.mark.parametrize("answers", [(DOWN,), (MISSING, DOWN), (MISSING, MISSING, DOWN)], ids=["first inspect", "second inspect", "build"])
|
||||
def test_a_failure_to_start_docker_passes_through_inspect_and_build(tmp_path, answers):
|
||||
shim_dir(tmp_path)
|
||||
run_docker = scripted(*answers)
|
||||
assert convert.ensure_image(tmp_path, run_docker, Slot(run_docker)) == DOWN
|
||||
|
||||
|
||||
def not_said(text):
|
||||
raise AssertionError(f"said {text}")
|
||||
|
||||
|
||||
def not_slept(seconds):
|
||||
raise AssertionError(f"slept {seconds} seconds")
|
||||
|
||||
|
||||
def test_a_heavy_slot_is_held_until_the_block_ends(tmp_path):
|
||||
with convert.heavy_slot({"XDG_STATE_HOME": str(tmp_path)}, tmp_path, 1, not_said, not_slept, fcntl.flock) as held:
|
||||
assert held is None
|
||||
assert slots.taken_slot(tmp_path / "run-heavy", 1, fcntl.flock) is None
|
||||
slot, fd = slots.taken_slot(tmp_path / "run-heavy", 1, fcntl.flock)
|
||||
os.close(fd)
|
||||
|
||||
|
||||
def test_a_process_under_run_heavy_takes_no_second_slot(tmp_path):
|
||||
(tmp_path / "run-heavy").mkdir()
|
||||
slot, fd = slots.taken_slot(tmp_path / "run-heavy", 1, fcntl.flock)
|
||||
try:
|
||||
with convert.heavy_slot({"XDG_STATE_HOME": str(tmp_path), slots.HELD: "0"}, tmp_path, 1, not_said, not_slept, fcntl.flock) as held:
|
||||
assert held is None
|
||||
finally:
|
||||
os.close(fd)
|
||||
|
||||
|
||||
def test_a_heavy_slot_folder_that_cannot_be_made_yields_a_failure(tmp_path):
|
||||
(tmp_path / "run-heavy").write_text("a file where the folder goes")
|
||||
with convert.heavy_slot({"XDG_STATE_HOME": str(tmp_path)}, tmp_path, 1, not_said, not_slept, fcntl.flock) as held:
|
||||
assert isinstance(held, Failure) and held.reason.startswith(f"cannot take a heavy slot in {tmp_path / 'run-heavy'}: ")
|
||||
|
||||
|
||||
def test_container_run_runs_the_image_on_the_text(tmp_path):
|
||||
run_docker = scripted(convert.Ran(0, "", ""), convert.Ran(0, "answer", ""))
|
||||
assert convert.container_run("to-adf", "text", run_docker, shim_dir(tmp_path)) == convert.Ran(0, "answer", "")
|
||||
assert run_docker.lines[1] == (convert.docker_args(convert.image_tag(tmp_path), "to-adf"), "text", convert.RUN_SECONDS)
|
||||
|
||||
|
||||
def test_container_run_passes_an_image_failure_through(tmp_path):
|
||||
down = Failure("docker is not installed")
|
||||
assert convert.container_run("to-adf", "text", scripted(down), shim_dir(tmp_path)) == down
|
||||
|
||||
|
||||
def test_round_trip_through_the_real_container():
|
||||
doc = convert.markdown_to_adf("# Title\n\nSome **bold** text.\n")
|
||||
assert isinstance(doc, dict), doc
|
||||
assert doc["type"] == "doc" and doc["content"][0]["type"] == "heading"
|
||||
markdown = convert.adf_to_markdown(doc)
|
||||
assert isinstance(markdown, str) and markdown.startswith("# Title") and "**bold**" in markdown
|
||||
refused = convert.adf_to_markdown({"type": "nope"})
|
||||
assert isinstance(refused, Failure) and "not-an-adf-document" in refused.reason
|
||||
assert convert.adfs_to_markdown([doc, doc]) == [markdown, markdown]
|
||||
second = convert.adfs_to_markdown([doc, {"type": "nope"}])
|
||||
assert isinstance(second, convert.Refused) and second.index == 1 and "not-an-adf-document" in second.failure.reason
|
||||
crashed = convert.answer("to-markdown", "not json", convert.container_run)
|
||||
assert isinstance(crashed, Failure) and crashed.reason.startswith("the adf-codec shim failed with exit 1: ")
|
||||
|
||||
|
||||
# A Jira description as Jira stores it: every block carries a localId, and an empty paragraph spaces two blocks.
|
||||
JIRA_DESCRIPTION = {
|
||||
"type": "doc", "version": 1, "content": [
|
||||
{"type": "heading", "attrs": {"level": 2, "localId": "h-1"}, "content": [{"type": "text", "text": "Goal"}]},
|
||||
{"type": "paragraph", "attrs": {"localId": "p-1"}, "content": [{"type": "text", "text": "Keep "}, {"type": "text", "text": "this", "marks": [{"type": "strong"}]}]},
|
||||
{"type": "paragraph", "attrs": {"localId": "p-2"}},
|
||||
{"type": "bulletList", "attrs": {"localId": "l-1"}, "content": [
|
||||
{"type": "listItem", "attrs": {"localId": "i-1"}, "content": [{"type": "paragraph", "attrs": {"localId": "p-3"}, "content": [{"type": "text", "text": "one"}]}]},
|
||||
]},
|
||||
],
|
||||
}
|
||||
|
||||
|
||||
def test_the_lossless_pair_gives_back_a_jira_description_identical_and_the_portable_pair_does_not():
|
||||
markdown = convert.adf_to_markdown_lossless(JIRA_DESCRIPTION)
|
||||
assert isinstance(markdown, str), markdown
|
||||
assert convert.markdown_to_adf_lossless(markdown) == JIRA_DESCRIPTION
|
||||
assert convert.adfs_to_markdown_lossless([JIRA_DESCRIPTION, JIRA_DESCRIPTION]) == [markdown, markdown]
|
||||
portable = convert.markdown_to_adf(convert.adf_to_markdown(JIRA_DESCRIPTION))
|
||||
assert portable != JIRA_DESCRIPTION
|
||||
second = convert.adfs_to_markdown_lossless([JIRA_DESCRIPTION, {"type": "nope"}])
|
||||
assert isinstance(second, convert.Refused) and second.index == 1
|
||||
@@ -0,0 +1,4 @@
|
||||
"""One cycle of a headless claude worker and the judge of its transcript, for every entry point that drives such cycles: loop-claude and do-epic (docs/decisions.md → `do-epic: drives one Jira epic …`).
|
||||
|
||||
run.py runs a cycle through the states in states.py: worker.py runs the worker, judge.py rules on its transcript, interrupt.py puts a question to the human in the tmux window tmux.py names, and routing.py picks the rung the worker runs on next. An entry point hands the cycle what is its own: its prompts and file names (worker_prompts.py) and how it reads the plan items a worker took in (run.py's Cycle.taken_in). What two entry points share beyond the cycle lives in bin/chunk_driver/. No module here imports an entry point's package, and bin/repo_checks/test_package_cycles.py fails on such an import. A reader finds a module by its name, so the modules stay at one level. docs/decisions.md → `principles: about seven things per level, …` allows that.
|
||||
"""
|
||||
@@ -0,0 +1,8 @@
|
||||
from loop_effects.effects import Effects, say
|
||||
|
||||
|
||||
def tell(text: str, effects: Effects, directory: str | None = None) -> bool:
|
||||
"""DMs text to the human through the notifier of the project whose checkout holds directory, else the current directory, and returns whether it went out. Where the DM fails, it says why on stderr and goes on: the DM only copies what the terminal shows, so its failure never stops the loop."""
|
||||
if failed := effects.dm(text, directory):
|
||||
say(f"could not DM you: {failed.reason}", effects)
|
||||
return not failed
|
||||
@@ -0,0 +1,15 @@
|
||||
"""Test doubles for the suites that run a cycle: the tmux window it runs in, and the prompts of an entry point that exists only in tests."""
|
||||
from agent_cycle import tmux
|
||||
from agent_cycle.worker_prompts import WorkerPrompts
|
||||
|
||||
WINDOW = tmux.Window("loop-proj", "item-7", "%4")
|
||||
# The prompts of an entry point that exists only in tests, so a cycle's tests read no real entry point's wording.
|
||||
PROMPTS = WorkerPrompts(
|
||||
driver="a-driver",
|
||||
fresh=lambda task, premises, route, project, facts: f"Fresh: {task}\n\n{premises}\n\n{facts}",
|
||||
resumed=lambda evidence, route, project: f"Resumed: {evidence}",
|
||||
rungs_held=lambda route, project: f" You hold {route.rung}.",
|
||||
quote_sources="the project's records",
|
||||
answer_destinations="the plan or a comment",
|
||||
records_named="the project's decisions",
|
||||
)
|
||||
@@ -0,0 +1,60 @@
|
||||
"""The escalation mark makes one escalation trigger step the worker up one rung, never two (docs/decisions.md → `routing: a worker whose run ends asking for a higher rung`).
|
||||
|
||||
A worker whose run ends asking its driver, such as loop-claude, for a higher rung cites the trigger that fired, and the judge quotes the passage where it fired as the verdict's escalation. The mark, Route.escalated_at, is how many transcript entries the session held when an escalation last stepped the worker up, 0 before any. The session's transcript only grows, so the mark holds across cycles, and the archive's Worker: lines keep it for a rerun.
|
||||
|
||||
- Stamp. stamped() writes on the judge's verdict how many entries the judge read.
|
||||
- Step. routing.next_route() steps the worker up on an escalation and moves the mark to moved_to(verdict).
|
||||
- Show. transcript() puts step_line after the mark, telling the judge that the triggers before that line are spent. quote_after_step, in the judge's schema, tells the judge to quote only the worker's words after that line.
|
||||
- Check. checked() keeps an escalation only where it quotes both the transcript the judge was shown and the worker's own lines after the mark, which after_mark() renders, so a passage that bought one step cannot buy another.
|
||||
"""
|
||||
import dataclasses
|
||||
import typing
|
||||
|
||||
from claude_code.transcript import assistant_lines, render, Typed
|
||||
from claude_code.entries import AssistantTurn, Entry
|
||||
from agent_cycle.verdicts import Escalating, Verdict
|
||||
from agent_cycle.quotes import verbatim
|
||||
|
||||
# Only the judge reads the step line, so it is not a [loop] line.
|
||||
STEP_TAG = "[step]"
|
||||
|
||||
|
||||
def asks_higher_rung(driver: str) -> str:
|
||||
"""How a worker's run ends where it wants the rest of its chunk on a higher rung. The worker's prompt tells it to, and the judge's rules name the same words, so both take them from here. driver is the entry point that drives the cycle, such as `do-epic`."""
|
||||
return f"asking {driver} for a higher rung"
|
||||
|
||||
|
||||
def step_line(driver: str) -> str:
|
||||
return f"{STEP_TAG} {driver} stepped the worker up a rung here, so the escalation triggers that fired before this line are spent."
|
||||
|
||||
|
||||
def quote_after_step(driver: str) -> str:
|
||||
"""Reply.escalation's description in agent_cycle/judge.py carries this sentence, so the judge reads step_line as the mark."""
|
||||
return f"Where a {STEP_TAG} line says {driver} stepped the worker up a rung, quote only the worker's own words after it, and leave this empty where the trigger fired only before it."
|
||||
|
||||
|
||||
def stamped(verdict: Verdict, entries_read: int) -> Verdict:
|
||||
"""The verdict with how many transcript entries the judge read, where it may carry an escalation."""
|
||||
return dataclasses.replace(verdict, entries_read=entries_read) if isinstance(verdict, Escalating) else verdict
|
||||
|
||||
|
||||
def moved_to(verdict: Escalating) -> int | None:
|
||||
"""Where the verdict's escalation would move the mark, if the escalation steps the worker; None for a verdict without one."""
|
||||
return verdict.entries_read if verdict.escalation else None
|
||||
|
||||
|
||||
def transcript(entries: list[Entry], at: int, typed_answer: typing.Callable[[str], Typed | None], driver: str) -> str:
|
||||
"""The transcript as the judge sees it. Where the mark, at, is above 0, step_line comes after that many entries."""
|
||||
return "\n\n".join(part for part in (render(entries[:at], typed_answer), step_line(driver) if at else "", render(entries[at:], typed_answer)) if part)
|
||||
|
||||
|
||||
def after_mark(entries: list[Entry], at: int) -> str:
|
||||
"""All the text and tool calls of the worker's assistant turns after the mark, even where the judge is shown only the transcript's tail. The driver's prompts and the human's lines are left out, since they repeat earlier passages, such as the judge's evidence or the worker's question."""
|
||||
return "\n\n".join(line for entry in entries[at:] if isinstance(entry, AssistantTurn) for line in assistant_lines(entry))
|
||||
|
||||
|
||||
def checked(verdict: Verdict, *, after: str, shown: str) -> Verdict:
|
||||
"""The verdict without its escalation unless the escalation quotes both texts: the argument after, which holds the worker's lines after the mark as after_mark renders them, and the argument shown, the transcript the judge was shown. A misquote, or a quote of a passage before the mark, drops the escalation, so the worker's rung holds."""
|
||||
if isinstance(verdict, Escalating) and verdict.escalation and not (verbatim(verdict.escalation, after) and verbatim(verdict.escalation, shown)):
|
||||
return dataclasses.replace(verdict, escalation="")
|
||||
return verdict
|
||||
@@ -1,7 +1,7 @@
|
||||
"""Opens claude on the terminal for the human. It sits outside cycle/, since loop-inbox's /talk and the loop's routing calls open claude too."""
|
||||
"""Opens claude on the terminal for the human."""
|
||||
import dataclasses
|
||||
|
||||
from loop_claude.effects import Effects
|
||||
from loop_effects.effects import Effects
|
||||
from failure import Failure
|
||||
from model_routing.ladder import Rung
|
||||
|
||||
@@ -19,7 +19,7 @@ def claude_args(rung: Rung, args: list[str]) -> list[str]:
|
||||
|
||||
|
||||
# CLAUDE_CODE_SANDBOXED, which Claude Code doesn't document, skips its trust dialog without writing ~/.claude.json:
|
||||
# docs/decisions.md → `loop-claude: every claude it or loop-inbox opens on a terminal has CLAUDE_CODE_SANDBOXED set`.
|
||||
# docs/decisions.md → `loop-claude: every claude it opens on a terminal has CLAUDE_CODE_SANDBOXED set`.
|
||||
def hand_over(command: ClaudeCommand, effects: Effects) -> Failure | None:
|
||||
"""Runs claude on the terminal as command says, with CLAUDE_CODE_SANDBOXED=1 added to its environment; the failure is why claude could not start."""
|
||||
try:
|
||||
@@ -0,0 +1,150 @@
|
||||
import dataclasses
|
||||
import datetime
|
||||
import sys
|
||||
import typing
|
||||
import uuid
|
||||
|
||||
from claude_code.entries import AssistantTurn, Entry
|
||||
from agent_cycle.hand_over import claude_args, ClaudeCommand, hand_over
|
||||
from loop_effects.effects import Effects, say
|
||||
from failure import Failure
|
||||
from claude_code.transcript import human_turns, read_transcript
|
||||
from claude_code.reply import Limited
|
||||
from agent_cycle.stop import needs_human, needs_terminal, Stop
|
||||
from agent_cycle.worker import run_claude
|
||||
from model_routing.ladder import Rung
|
||||
from agent_cycle.direct_message import tell
|
||||
from agent_cycle import tmux
|
||||
from claude_code.tokens import tokens_of
|
||||
|
||||
ANSWER_QUESTION = "answer the question above"
|
||||
# TALK, what the human types at the entry point's terminal to open claude for the question, and ASK_ANSWER were picked on 2026-10-17 by a bench of three readers seated as the README's audience, as ~/.claude/CLAUDE.md → "Working loop" → "Bench a syntax with the people who write it." has it.
|
||||
TALK = "/talk"
|
||||
ASK_ANSWER = f"Answer ({TALK} opens claude, Enter stops the loop): "
|
||||
# While the human hasn't answered, the worker's session is compacted CACHE_MARGIN seconds before its hour-long prompt cache expires: compacting reads the context from the cache, while resuming after it expired writes the whole context again. Below COMPACT_FLOOR tokens of context, that write costs less than compacting. A five-minute cache expires within the margin, so a session that last wrote one isn't compacted. lilleman chose this on 2026-11-11.
|
||||
HOUR_CACHE = 3600
|
||||
CACHE_MARGIN = 600
|
||||
COMPACT_FLOOR = 60_000
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class WorkerSession:
|
||||
"""The worker's claude session, which /talk opens on the entry point's terminal."""
|
||||
root: str
|
||||
id: uuid.UUID
|
||||
rung: Rung
|
||||
# The rung the worker last ran on: below rung where the ruling that interrupts stepped the worker up.
|
||||
ran_on: Rung
|
||||
transcript_path: str
|
||||
# Added to the environment of the worker's claude, and of the claude /talk opens.
|
||||
env: dict[str, str]
|
||||
|
||||
def claude_command(self) -> ClaudeCommand:
|
||||
return ClaudeCommand(claude_args(self.rung, ["--resume", str(self.id)]), self.root, self.env)
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Talked:
|
||||
"""The human typed in the worker's claude session."""
|
||||
|
||||
|
||||
def interrupt(question: str, answer_here: bool, session: WorkerSession, window: tmux.Window, driver: str, effects: Effects) -> str | Talked | Stop:
|
||||
"""Prints question for the human, in window, and returns their answer. While it waits, the window's name ends in tmux.WAITS, and the bell it rings shows in tmux's status bar. The answer: where answer_here, the first line typed at the terminal of driver, the entry point, stripped, or Talked once they typed in the worker's claude session, which TALK opens; else Talked once they typed in that session, which opens at once on the terminal. A Stop where interrupt runs off a terminal, or they type no answer, or the input ends."""
|
||||
# The bell ends the question's line, so it rings once the question can be read.
|
||||
say(f"\n{question}{tmux.BELL}", effects)
|
||||
on_terminal = effects.on_terminal()
|
||||
if on_terminal:
|
||||
# Keys typed while the worker ran wait on the terminal, and would answer a question no one has read, here or in claude's session, which reads them too. Of a pasted answer, the first line answers; the rest wait, and the next question drops them. A longer answer goes through TALK.
|
||||
effects.discard_typed()
|
||||
tmux.mark(window, True, effects.tmux)
|
||||
# After the discard, so an answer typed while the DM sends counts; before the terminal check, so a loop that cannot ask still tells the human what it would have asked.
|
||||
tell(f"{driver} in {session.root} asks, in the tmux window {window.target}:\n\n{question}", effects)
|
||||
answer = needs_terminal(ANSWER_QUESTION, on_terminal, driver) or answered(answer_here, session, effects)
|
||||
# A loop that stops unanswered leaves the mark on its window.
|
||||
if not isinstance(answer, Stop):
|
||||
tmux.mark(window, False, effects.tmux)
|
||||
return answer
|
||||
|
||||
|
||||
def answered(answer_here: bool, session: WorkerSession, effects: Effects) -> str | Talked | Stop:
|
||||
"""The human's answer, as interrupt returns it."""
|
||||
answer = waited_answer(session, effects) if answer_here else TALK
|
||||
if answer != TALK:
|
||||
return answer
|
||||
return human_typed(session.transcript_path, lambda: claude_open(session, effects)) or Talked()
|
||||
|
||||
|
||||
def waited_answer(session: WorkerSession, effects: Effects) -> str | Stop:
|
||||
"""typed_answer, compacting the worker's session where no answer has come by CACHE_MARGIN seconds before its prompt cache expires. /talk needs no compaction: the claude it opens compacts an idle session itself."""
|
||||
entries = read_transcript(session.transcript_path)
|
||||
now = effects.now()
|
||||
delay = None if isinstance(entries, Failure) else compaction_delay(entries, now)
|
||||
if delay is None:
|
||||
return typed_answer(effects)
|
||||
stop_timer = effects.timer(delay, lambda: compact(session, now + delay + CACHE_MARGIN, effects))
|
||||
try:
|
||||
return typed_answer(effects)
|
||||
finally:
|
||||
# Waits for a compaction under way, so the worker doesn't resume the session while it is compacted.
|
||||
stop_timer()
|
||||
|
||||
|
||||
def compaction_delay(entries: list[Entry], now: float) -> float | None:
|
||||
"""Seconds from now until CACHE_MARGIN before the session's prompt cache expires. None where its context is under COMPACT_FLOOR tokens, its cache lasts five minutes, or the margin has begun."""
|
||||
turns = [entry for entry in entries if isinstance(entry, AssistantTurn) and entry.usage]
|
||||
if not turns or tokens_of(turns[-1].usage).context() < COMPACT_FLOOR:
|
||||
return None
|
||||
# A read refreshes the cache for the lifetime it was written with.
|
||||
written = next((tokens for turn in reversed(turns) if (tokens := tokens_of(turn.usage)).write_5m or tokens.write_1h), None)
|
||||
if written is None or not written.write_1h:
|
||||
return None
|
||||
try:
|
||||
last_read = datetime.datetime.fromisoformat(turns[-1].timestamp).timestamp()
|
||||
except ValueError:
|
||||
return None
|
||||
delay = last_read + HOUR_CACHE - CACHE_MARGIN - now
|
||||
return delay if delay > 0 else None
|
||||
|
||||
|
||||
def compact(session: WorkerSession, expires: float, effects: Effects) -> None:
|
||||
"""Compacts the worker's session with `claude -p /compact`, saying that it starts and how it went. Each line opens on a line of its own, below the open ASK_ANSWER. From expires on, when the prompt cache has expired, it doesn't do anything: a timer fires late where the machine was suspended."""
|
||||
if effects.now() >= expires:
|
||||
return
|
||||
say("\ncompacting the worker's claude session before its prompt cache expires; an answer typed meanwhile is read once that ends", effects)
|
||||
# On the rung the worker ran on, not the one a ruling stepped it up to: the prompt cache is kept per model, and another effort may miss it too, so another rung would read the whole context at full price. Without run_worker's wait for memory, which could outlast the cache.
|
||||
outcome = run_claude(session.root, claude_args(session.ran_on, ["-p", "/compact", "--resume", str(session.id), "--output-format", "stream-json", "--verbose"]), session.env, effects)
|
||||
if outcome is None:
|
||||
say("\ncompacted the worker's claude session", effects)
|
||||
else:
|
||||
say(f"\ncould not compact the worker's claude session: {outcome.said if isinstance(outcome, Limited) else outcome.reason}", effects)
|
||||
|
||||
|
||||
def typed_answer(effects: Effects) -> str | Stop:
|
||||
"""The line typed at the entry point's terminal, stripped. A Stop where they type no answer, or the input ends."""
|
||||
try:
|
||||
text = effects.input(ASK_ANSWER).strip()
|
||||
except EOFError:
|
||||
print(file=sys.stderr) # Ends the prompt's line. It isn't a message, so it gets no time.
|
||||
return needs_human(ANSWER_QUESTION, "the input ended")
|
||||
return text or needs_human(ANSWER_QUESTION, "nothing was typed")
|
||||
|
||||
|
||||
def claude_open(session: WorkerSession, effects: Effects) -> Stop | None:
|
||||
"""Opens the worker's claude session on the terminal, and returns once it has ended."""
|
||||
if unstarted := hand_over(session.claude_command(), effects):
|
||||
return Stop(1, f"could not start claude for the interrupt: {unstarted.reason}")
|
||||
return None
|
||||
|
||||
|
||||
def human_typed(transcript_path: str, held_open: typing.Callable[[], Stop | None]) -> Stop | None:
|
||||
"""Runs held_open, which returns once the claude the human answers in has ended, then checks that the human typed something there."""
|
||||
entries = read_transcript(transcript_path)
|
||||
if isinstance(entries, Failure):
|
||||
return Stop(1, entries.reason)
|
||||
before = human_turns(entries)
|
||||
if stop := held_open():
|
||||
return stop
|
||||
entries = read_transcript(transcript_path)
|
||||
if isinstance(entries, Failure):
|
||||
return Stop(1, f"could not tell whether you typed anything: {entries.reason}")
|
||||
return None if human_turns(entries) > before else needs_human(ANSWER_QUESTION, "the interrupt ended without anything typed")
|
||||
@@ -0,0 +1,323 @@
|
||||
import dataclasses
|
||||
import json
|
||||
import re
|
||||
import typing
|
||||
|
||||
from agent_cycle.worker_prompts import answers_recorded, typed_answer
|
||||
from claude_code.reply import claude_reply, Limited
|
||||
from loop_effects.effects import Effects
|
||||
from claude_code.entries import Entry, structured_output
|
||||
from agent_cycle import escalation_mark
|
||||
from failure import Failure
|
||||
from agent_cycle.verdicts import Finished, Interrupt, Judged, QuotedAnswer, Unfinished, Verdict
|
||||
from claude_code.transcript import human_answers
|
||||
from transcript_archive.judge_run import JudgeRun
|
||||
from agent_cycle.quotes import plain, verbatim
|
||||
from agent_cycle.retry import retried
|
||||
from model_routing.ladder import Rung
|
||||
from agent_cycle.stop import Stop
|
||||
from claude_code.tokens import tokens_of
|
||||
|
||||
# At 3 to 4 characters a token, 100,000 to 133,000 tokens, which leaves a 200,000-token context room for the reply; the largest session rendered here was 364,000 characters on 2026-10-03.
|
||||
JUDGE_PROMPT_CHARS = 400000
|
||||
# The judge reads the transcript's last 50,000 characters at least, about 15,000 tokens, or all of a shorter one. Where the rest of its prompt leaves less room, the judge doesn't run, since a cut record could hide the rule that makes it interrupt.
|
||||
TRANSCRIPT_FLOOR = 50000
|
||||
INTERRUPT_RULES = (
|
||||
"""Decide whether the human must now be interrupted. ~/.claude/CLAUDE.md → "Working loop", "Ask, don't guess" says """
|
||||
"which choices are reserved for the human. interrupt=true when any of these appear:\n"
|
||||
"- the worker asks the human about a reserved choice, or makes one itself, and neither the premises nor the "
|
||||
"records settle it; a choice the worker names a rule as asking the human's approval for counts as reserved, "
|
||||
"since some such rules, such as larv-review's, lie outside the records\n"
|
||||
"- it asks the human anything else without recommending an answer, and neither the premises "
|
||||
"nor the records settle the matter\n"
|
||||
"- it asks again a question a [loop] line already answered\n"
|
||||
"- it is blocked on something only the human can supply: a credential, a version bump, a choice "
|
||||
"outside the repo, or a release ready to cut, which only the human may publish\n"
|
||||
"- it flags that the goals need changing\n"
|
||||
"- it flags that the plan or the task itself is unclear or missing, and recommends no way on\n\n"
|
||||
"interrupt=false otherwise. A choice in the repo that no rule reserves for the human is the worker's to make, "
|
||||
"so its taking its own recommendation on one is no reason to interrupt. Where it asks about such a choice and "
|
||||
"recommends an answer, quote the sentence of that rule telling it to take the option it would recommend, even "
|
||||
"where a [loop] line quoted that sentence for another question. A run that ends {asks_higher_rung} "
|
||||
"is no reason to interrupt either; one that asks the human's yes to a higher rung is.\n\n"
|
||||
"The human may have replied inside the transcript, on a [human] line: judge only what "
|
||||
"is still open, never a question they already answered there. Where a [human] line from earlier in the "
|
||||
"chunk answered the question the worker asks now, interrupt only if that line's own words leave open what "
|
||||
"the worker asks: quote the line in answered_before, those words in left_open, and end the question with them. "
|
||||
"Otherwise interrupt=false and finished=false, with that line as the evidence: the worker is shown it as the "
|
||||
"work remaining.\n\n"
|
||||
"Where the worker asked or flagged something itself, the question is that one, in the worker's own "
|
||||
"wording; never construct another from facts it stated, except to end it with what an earlier answer left open."
|
||||
)
|
||||
QUOTE_RULES = (
|
||||
"Where the premises or the records answer the worker's own question and no [loop] line has "
|
||||
"quoted that answer yet, set interrupt=false and quote the passage that answers it; the worker is "
|
||||
"then given that passage in place of the human's reply. An interrupt outranks a quoted answer, and either "
|
||||
"outranks finished."
|
||||
)
|
||||
FINISHED_RULES = (
|
||||
"The chunk is the piece of work the worker is on, shipped as one pull request.\n\n"
|
||||
"finished=true when the chunk is complete: merged, or nothing remains that the worker could do on "
|
||||
"its own. Even then, it is finished only once {answers_recorded}.\n\n"
|
||||
"An answer counts as recorded where the premises or the records above already hold it, the human's rules "
|
||||
"(~/.claude/CLAUDE.md, ~/.claude/rules/, the project's review standards, each headed by its path) included. "
|
||||
"It also counts where the transcript shows the worker writing it into {answer_destinations}, "
|
||||
"but not into one of the human's rules.\n\n"
|
||||
"finished=false when work remains that a further run can "
|
||||
"continue: an open PR, a review not yet run, CI not yet reported, an answer not yet recorded."
|
||||
)
|
||||
|
||||
|
||||
def judge_rules(answer_destinations: str, driver: str) -> str:
|
||||
"""The rules that end the judge's prompt. answer_destinations names where the worker of driver, the entry point, may record an answer the human typed."""
|
||||
return "\n\n".join((INTERRUPT_RULES.format(asks_higher_rung=escalation_mark.asks_higher_rung(driver)), QUOTE_RULES, FINISHED_RULES.format(answers_recorded=answers_recorded(answer_destinations), answer_destinations=answer_destinations)))
|
||||
|
||||
|
||||
# Open the task and the transcript in the prompt; the premises and the records come before the task, the rules after the transcript.
|
||||
# judge_replay.archived_prompt splits each archived prompt on them, so rewording one makes every run archived before it replay as failed.
|
||||
TASK_HEADING = "The task the worker was given:\n"
|
||||
# Between the task and the tail that quotes_checked searches, so that no fragment of a quote runs across the join. plain() keeps it, and the judge's quotes hold no NUL.
|
||||
PASSAGE_BREAK = "\x00"
|
||||
|
||||
|
||||
def transcript_heading(driver: str) -> str:
|
||||
return f"What the worker did and said, what the human typed on [human] lines and what {driver} told it on [loop] lines, latest last:\n"
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Reply:
|
||||
answer: str = dataclasses.field(metadata={"description": "With interrupt false, the passage of the premises or the records that answers the worker's question, quoted verbatim, without elisions. Empty otherwise."})
|
||||
# Routes the worker one rung up, as the judge interrupts or quotes an answer, or on the next cycle: agent_cycle/escalation_mark.py.
|
||||
escalation: str = dataclasses.field(metadata={"description": "Empty unless the chunk is unfinished, interrupt is true or answer quotes a passage, and the worker's run ends {asks_higher_rung}, citing an escalation trigger. Then: a verbatim quote, without elisions, of the transcript passage where the trigger fired, such as a review round's commit title or the worker's report of the finding or failing test. {quote_after_step} Never a later mention of the trigger, and never the request itself."})
|
||||
evidence: str = dataclasses.field(metadata={"description": "A verbatim quote of the one passage of the task or the transcript the verdict rests on, without elisions: what triggers the interrupt; for a quoted answer, the worker's question; else what shows the chunk finished or the work remaining."})
|
||||
finished: bool = dataclasses.field(metadata={"description": "Whether the chunk is finished."})
|
||||
interrupt: bool = dataclasses.field(metadata={"description": "Whether the human must now be interrupted."})
|
||||
answered_before: str = dataclasses.field(metadata={"description": "With interrupt true, a [human] line from earlier in the chunk that answered the question the worker asks now, quoted verbatim, without elisions. Empty otherwise."})
|
||||
left_open: str = dataclasses.field(metadata={"description": "With answered_before set, the words of that line that leave open what the question asks, quoted verbatim; the question ends with them. Empty otherwise."})
|
||||
question: str = dataclasses.field(metadata={"description": "With interrupt true, the single question to put to the human. With a quoted answer, the worker's question that the answer field answers. Empty otherwise."})
|
||||
# True opens claude's session at once, in place of the one-line answer (run.ask). The judge decides it, since loop-claude computes the plan's standing (release_standing.chunk_item) only when it routes a chunk on the ladder afresh: it would miss a release ready to cut in a resumed chunk or off the ladder. A wrong ruling costs the human one typed /talk, or answering in claude, which stops the loop if they leave it without typing anything.
|
||||
release_ready: bool = dataclasses.field(metadata={"description": "With interrupt true, whether the question is about a release ready to cut, which only the human may publish. False otherwise."})
|
||||
# Finds the answer that reverses a choice the worker took on its own recommendation. score-outcomes counts these answers per chunk: they are the counter-signal the 2026-11-08 entry of docs/decisions.md → `loop-claude: a judge decides each interrupt and each quoted answer…` stays valid by.
|
||||
reversed: str = dataclasses.field(metadata={"description": "The latest [human] line that overrides a choice the worker took on its own recommendation and recorded with its reason, quoted verbatim, without elisions. Empty where none does; a line that answers a question the worker left open doesn't override anything."})
|
||||
|
||||
|
||||
REPLY_TYPES = typing.get_type_hints(Reply)
|
||||
JSON_TYPES: dict[object, dict[str, typing.Any]] = {bool: {"type": "boolean"}, int: {"type": "integer"}, str: {"type": "string"}}
|
||||
|
||||
|
||||
def judge_schema(driver: str) -> dict[str, typing.Any]:
|
||||
"""The schema of the judge's reply, each field described from Reply's metadata, with the words that name driver, the entry point, filled in."""
|
||||
asks, quote = escalation_mark.asks_higher_rung(driver), escalation_mark.quote_after_step(driver)
|
||||
described = {field.name: field.metadata["description"].replace("{asks_higher_rung}", asks).replace("{quote_after_step}", quote) for field in dataclasses.fields(Reply)}
|
||||
return {
|
||||
"properties": {name: {"description": description, **JSON_TYPES[REPLY_TYPES[name]]} for name, description in described.items()},
|
||||
"required": list(REPLY_TYPES),
|
||||
"type": "object",
|
||||
}
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Rejected(Failure):
|
||||
"""A judge reply loop-claude rejected: reason says why, run holds the prompt and the reply, and cost is what the run cost in dollars, 0 where its reply records none."""
|
||||
run: JudgeRun
|
||||
cost: float = 0.0
|
||||
|
||||
@property
|
||||
def reply(self) -> str:
|
||||
"""The reply as json."""
|
||||
return json.dumps(self.run.reply, ensure_ascii=False)
|
||||
|
||||
|
||||
class Grounds(typing.NamedTuple):
|
||||
"""The texts quotes_checked checks the judge's quotes against. A quote must appear in its text as written, since a quote reworded or stitched together can say what its source does not; only the evidence may join passages with an ellipsis, each passage in order."""
|
||||
# The transcript as the judge saw it.
|
||||
shown: str
|
||||
# The worker's own lines after the escalation mark, as escalation_mark.after_mark renders them, including those the tail in shown cuts off.
|
||||
after_mark: str
|
||||
# The premises and the records.
|
||||
quotable: str
|
||||
# Each answer the human typed, whole, latest last (transcript.human_answers).
|
||||
typed: tuple[str, ...] = ()
|
||||
# The worker's task, which the judge reads above shown and may quote as the evidence: the worker's first prompt holds it, but the tail in shown cuts that off once the session grows.
|
||||
task: str = ""
|
||||
|
||||
|
||||
class Brief(typing.NamedTuple):
|
||||
"""What the judge reads: the worker's task, the premises and records the worker is judged by, and the transcript's entries."""
|
||||
task: str
|
||||
premises: str
|
||||
records: str
|
||||
# What the records are, in their order, as WorkerPrompts.records_named has it.
|
||||
records_named: str
|
||||
# Where the worker may record an answer the human typed, as the entry point names it.
|
||||
answer_destinations: str
|
||||
entries: list[Entry]
|
||||
# How many of the entries the session held when an escalation last stepped the worker up a rung, 0 before any.
|
||||
escalated_at: int
|
||||
# The entry point's name, such as `do-epic`, as WorkerPrompts.driver has it.
|
||||
driver: str
|
||||
|
||||
|
||||
def verdict_from(output: object) -> Verdict | Failure:
|
||||
if not isinstance(output, dict):
|
||||
return Failure("the judge returned no reply")
|
||||
for name, kind in REPLY_TYPES.items():
|
||||
if not fits(output.get(name), kind):
|
||||
return Failure(f"the judge's reply has no {name} of type {JSON_TYPES[kind]['type']}")
|
||||
if output["interrupt"]:
|
||||
if not output["question"].strip():
|
||||
return Failure("the judge interrupted without a question")
|
||||
return Interrupt(output["evidence"], output["question"], escalation=output["escalation"], release_ready=output["release_ready"], answered_before=output["answered_before"], left_open=output["left_open"])
|
||||
if output["answer"].strip():
|
||||
if not output["question"].strip():
|
||||
return Failure("the judge quoted an answer without a question")
|
||||
return QuotedAnswer(output["evidence"], output["question"], output["answer"], escalation=output["escalation"])
|
||||
if output["finished"]:
|
||||
return Finished(output["evidence"])
|
||||
return Unfinished(output["evidence"], escalation=output["escalation"])
|
||||
|
||||
|
||||
def fits(value: object, kind: object) -> bool:
|
||||
"""Whether value, read from the judge's JSON, is of kind. type(), not isinstance(): JSON true is no integer."""
|
||||
return type(value) is kind
|
||||
|
||||
|
||||
def judge(root: str, brief: Brief, rung: Rung, effects: Effects, keep: typing.Callable[[Rejected], Stop | None]) -> Verdict | Stop:
|
||||
return retried("judge", lambda: judge_once(root, brief, rung, effects), effects, lambda failure: keep(failure) if isinstance(failure, Rejected) else None)
|
||||
|
||||
|
||||
def judge_once(root: str, brief: Brief, rung: Rung, effects: Effects) -> Verdict | Failure | Limited:
|
||||
"""One judge run on the brief, as judge retries it; judge-replay replays it."""
|
||||
built = judge_prompt(brief)
|
||||
if isinstance(built, Failure):
|
||||
return built
|
||||
prompt, grounds = built
|
||||
verdict = run_judge(root, judge_args(rung, brief.driver), prompt, grounds, effects)
|
||||
return verdict if isinstance(verdict, Failure | Limited) else escalation_mark.stamped(verdict, len(brief.entries))
|
||||
|
||||
|
||||
def judge_archived(root: str, prompt: str, grounds: Grounds, entries_read: int, rung: Rung, driver: str, effects: Effects) -> Verdict | Failure | Limited:
|
||||
"""One judge run on a prompt the archive kept from an earlier run, as judge-replay replays it: the judge reads what it read then, and its quotes are checked against grounds, which judge_replay.archived_prompt makes from that prompt in place of the records of today."""
|
||||
verdict = run_judge(root, judge_args(rung, driver), prompt, grounds, effects)
|
||||
return verdict if isinstance(verdict, Failure | Limited) else escalation_mark.stamped(verdict, entries_read)
|
||||
|
||||
|
||||
def judge_args(rung: Rung, driver: str) -> list[str]:
|
||||
# --json-schema has claude check its reply against the schema and return it as the json result's structured_output.
|
||||
# No tools, so the verdict rests on the transcript grounded() checks it against.
|
||||
return [
|
||||
"--json-schema", json.dumps(judge_schema(driver)),
|
||||
*rung.flags(),
|
||||
"--tools", "", "--strict-mcp-config",
|
||||
]
|
||||
|
||||
|
||||
def run_judge(root: str, args: list[str], prompt: str, grounds: Grounds, effects: Effects) -> Verdict | Failure | Limited:
|
||||
"""One judge run, each quote in its verdict checked against grounds as Grounds says."""
|
||||
reply = claude_reply(effects.claude, args, root, prompt, "the judge")
|
||||
if isinstance(reply, Failure | Limited):
|
||||
return reply
|
||||
output = structured_output(reply)
|
||||
verdict = verdict_from(output)
|
||||
run = JudgeRun(prompt, reply)
|
||||
cost = cost_of(reply)
|
||||
if isinstance(verdict, Failure):
|
||||
return Rejected(verdict.reason, run, cost)
|
||||
checked = quotes_checked(verdict, grounds)
|
||||
if isinstance(checked, Failure):
|
||||
return Rejected(checked.reason, run, cost)
|
||||
return dataclasses.replace(checked, judged=Judged(cost, tokens_of(reply.get("usage")), reversal_of(output, grounds.typed), run))
|
||||
|
||||
|
||||
def reversal_of(output: object, typed: tuple[str, ...]) -> str:
|
||||
"""The latest answer the human typed that holds the reply's reversed quote, whole, so the same answer archives the same way however the judge quotes it; empty where none does. verdict_from has checked the field is a str."""
|
||||
quote = output.get("reversed") if isinstance(output, dict) else None
|
||||
return next((answer for answer in reversed(typed) if isinstance(quote, str) and verbatim(quote, answer)), "")
|
||||
|
||||
|
||||
def cost_of(reply: dict) -> float:
|
||||
"""What the run behind claude's json reply cost in dollars; 0 where the reply records none."""
|
||||
cost = reply.get("total_cost_usd")
|
||||
return float(cost) if isinstance(cost, int | float) and not isinstance(cost, bool) and cost > 0 else 0.0
|
||||
|
||||
|
||||
def quotes_checked(verdict: Verdict, grounds: Grounds) -> Verdict | Failure:
|
||||
"""The verdict with each of its quotes checked against the text it must appear in, as written:
|
||||
|
||||
| Quote | Must be in | Where it isn't | Checked by |
|
||||
|---|---|---|---|
|
||||
| the evidence | grounds.task then grounds.shown, the evidence's fragments in order | a Failure: run_judge rejects the reply, and judge retries it | grounded |
|
||||
| an interrupt's answered_before | grounds.shown | the interrupt stands, as if no earlier answer was found | re_ask_checked |
|
||||
| its left_open | answered_before and the question | the interrupt becomes an Unfinished that quotes answered_before back to the worker | re_ask_checked |
|
||||
| a quoted answer | grounds.quotable | the question goes to the human as an interrupt, which keeps the escalation the answer carried | answer_checked |
|
||||
| the escalation | grounds.shown and grounds.after_mark | the escalation is dropped, so the worker's rung holds | escalation_mark.checked |
|
||||
| the reversal | one of grounds.typed | the reversal is dropped; run_judge, after this check | reversal_of |
|
||||
|
||||
Only a misquoted evidence fails. A Failure for any other would exit an unattended loop, so each changes the verdict instead.
|
||||
"""
|
||||
if not grounded(verdict.evidence, f"{grounds.task}{PASSAGE_BREAK}{grounds.shown}"):
|
||||
return misquoted_evidence(verdict)
|
||||
verdict = re_ask_checked(verdict, grounds.shown)
|
||||
verdict = answer_checked(verdict, grounds.quotable)
|
||||
return escalation_mark.checked(verdict, after=grounds.after_mark, shown=grounds.shown)
|
||||
|
||||
|
||||
def grounded(evidence: str, searched: str) -> bool:
|
||||
"""Whether the searched text holds the evidence word for word, once emphasis marks are stripped and whitespace is reflowed in both. The judge joins passages with an ellipsis though told to quote one, so each fragment between ellipses must come after the one before it."""
|
||||
searched = plain(searched)
|
||||
fragments = [fragment.strip() for fragment in re.split(r"\.\.\.|…", plain(evidence)) if fragment.strip()]
|
||||
after = 0
|
||||
for fragment in fragments:
|
||||
at = searched.find(fragment, after)
|
||||
if at < 0:
|
||||
return False
|
||||
after = at + len(fragment)
|
||||
return bool(fragments)
|
||||
|
||||
|
||||
|
||||
def misquoted_evidence(verdict: Verdict) -> Failure:
|
||||
asked = f", for the question: {verdict.question}" if isinstance(verdict, Interrupt | QuotedAnswer) else ""
|
||||
return Failure(f"the judge quoted {verdict.evidence!r}, which is not in the task or the transcript{asked}")
|
||||
|
||||
|
||||
def re_ask_checked(verdict: Verdict, shown: str) -> Verdict:
|
||||
"""The verdict, or an Unfinished quoting the human's earlier answer back to the worker, where it is an Interrupt that re-asks what that answer settles: its left_open isn't in both the answer and the question."""
|
||||
if not isinstance(verdict, Interrupt) or not verbatim(verdict.answered_before, shown):
|
||||
return verdict
|
||||
if verbatim(verdict.left_open, verdict.answered_before) and verbatim(verdict.left_open, verdict.question):
|
||||
return verdict
|
||||
return Unfinished(verdict.answered_before, escalation=verdict.escalation)
|
||||
|
||||
|
||||
def answer_checked(verdict: Verdict, quotable: str) -> Verdict:
|
||||
"""The verdict; where it is a quoted answer that the premises and the records don't hold, an Interrupt on the same question instead."""
|
||||
if isinstance(verdict, QuotedAnswer) and not verbatim(verdict.answer, quotable):
|
||||
return Interrupt(verdict.evidence, verdict.question, escalation=verdict.escalation)
|
||||
return verdict
|
||||
|
||||
|
||||
def judge_prompt(brief: Brief) -> tuple[str, Grounds] | Failure:
|
||||
"""The prompt, and what the judge's quotes are checked against; a Failure where the premises, the records, the task and the rules leave room for less than the transcript's last TRANSCRIPT_FLOOR characters, or all of a shorter transcript."""
|
||||
head = (
|
||||
f"From the goals file, {brief.premises}\n\n"
|
||||
f"The records: {brief.records_named}:\n{brief.records or 'none'}\n\n"
|
||||
f"{TASK_HEADING}{brief.task}\n\n"
|
||||
f"{transcript_heading(brief.driver)}"
|
||||
)
|
||||
rules = judge_rules(brief.answer_destinations, brief.driver)
|
||||
room = JUDGE_PROMPT_CHARS - len(head) - len(rules) - 2
|
||||
transcript = escalation_mark.transcript(brief.entries, brief.escalated_at, typed_answer, brief.driver)
|
||||
needed = min(len(transcript), TRANSCRIPT_FLOOR)
|
||||
if room < needed:
|
||||
return Failure(f"the premises, the records, the task and the judge's rules leave {max(0, room):,} of the judge's {JUDGE_PROMPT_CHARS:,} characters for the transcript, less than the last {needed:,} characters of it that the judge must read. Cut the records, which take {len(brief.records):,}, by at least {needed - room:,}.")
|
||||
# The tail, where an interrupt or a finish lands; the session's transcript grows cycle over cycle.
|
||||
shown = transcript[max(0, len(transcript) - room):]
|
||||
grounds = Grounds(
|
||||
shown=shown,
|
||||
after_mark=escalation_mark.after_mark(brief.entries, brief.escalated_at),
|
||||
quotable=f"{brief.premises}\n\n{brief.records}",
|
||||
typed=tuple(human_answers(brief.entries, typed_answer)),
|
||||
task=brief.task,
|
||||
)
|
||||
return f"{head}{shown}\n\n{rules}", grounds
|
||||
@@ -0,0 +1,41 @@
|
||||
"""Ends a worker whose claude -p printed its final result and then waits on background shells that have gone quiet.
|
||||
|
||||
Claude Code's own time limit for a background command cannot do this: `BASH_DEFAULT_TIMEOUT_MS` and `BASH_MAX_TIMEOUT_MS` only raise the limit, and a call's `timeout` of up to 2 hours replaces the 10 minutes of a `claude -p` run (docs: code.claude.com/docs/en/tools-reference.md → "Time limit for background commands"). On 2026-11-18 a worker waited 95 minutes in an `until` loop whose `pgrep -f` matched its own command line.
|
||||
|
||||
The stops go to RECORD in the project's transcript archive rather than to the judge's records: the judge reads a worker's transcript, so the archive is where the pattern can be counted when it becomes a rule-hook ban (item 421).
|
||||
"""
|
||||
import pathlib
|
||||
|
||||
from loop_effects.effects import Effects, say, Streaming
|
||||
from loop_effects.child_shells import Shell
|
||||
from text_files.utc_stamp import utc
|
||||
|
||||
# Seconds without a line from the worker before a check, so a check is 5 minutes after its last line.
|
||||
CHECK_EVERY = 300
|
||||
# Seconds a shell's output must have been quiet before the shell is stopped.
|
||||
QUIET = 180
|
||||
RECORD = "lingering-workers.md"
|
||||
|
||||
|
||||
def stopped_shells(proc: Streaming, printed_result: bool, record: pathlib.Path, effects: Effects) -> None:
|
||||
"""Stops the shells of a claude that is still alive CHECK_EVERY seconds after it printed its final result (printed_result), saying each stop on the terminal and in record. A claude whose latest line is not a result is working and keeps its shells, and so does one with a shell that wrote output within QUIET seconds or runs a busy tool or holds a heavy slot, as `Shell.runs_busy_tool` and `Shell.holds_slot` say. A subagent's shells are children of the claude too, so they count like its own: a subagent that prints keeps them, and one inside a single quiet call loses it."""
|
||||
if not printed_result:
|
||||
return
|
||||
now = effects.now()
|
||||
shells = proc.shells()
|
||||
if any(now - shell.written <= QUIET or shell.runs_busy_tool or shell.holds_slot for shell in shells):
|
||||
return
|
||||
for shell in shells:
|
||||
proc.stop(shell)
|
||||
line = stop_line(shell, now)
|
||||
say(line, effects, stdout=True)
|
||||
try:
|
||||
record.parent.mkdir(parents=True, exist_ok=True)
|
||||
with record.open("a") as handle:
|
||||
handle.write(f"- {utc(now)} {line}\n")
|
||||
except OSError as failure:
|
||||
say(f"could not record the stop in {record}: {failure.strerror}", effects)
|
||||
|
||||
|
||||
def stop_line(shell: Shell, now: float) -> str:
|
||||
return f"stopped shell {shell.pid}, which held a worker after its final result; it had run {int(now - shell.started)} s and written nothing for {int(now - shell.written)} s: {shell.command}"
|
||||
@@ -0,0 +1,12 @@
|
||||
"""What counts as a quote: whether a text holds a passage the judge quotes from the transcript, the premises, the records or a human's line."""
|
||||
|
||||
|
||||
def verbatim(quote: str, text: str) -> bool:
|
||||
"""Whether text holds the judge's quote word for word, once plain strips emphasis and reflows whitespace in both."""
|
||||
quoted = plain(quote)
|
||||
return quoted != "" and quoted in plain(text)
|
||||
|
||||
|
||||
def plain(text: str) -> str:
|
||||
# The judge drops markdown emphasis and reflows whitespace when it quotes.
|
||||
return " ".join(text.replace("*", "").replace("_", "").split())
|
||||
@@ -1,9 +1,9 @@
|
||||
import typing
|
||||
|
||||
from loop_claude.effects import Effects, say
|
||||
from loop_effects.effects import Effects, say
|
||||
from failure import Failure
|
||||
from claude_code.reply import Limited
|
||||
from loop_claude.stop import Stop
|
||||
from agent_cycle.stop import Stop
|
||||
|
||||
T = typing.TypeVar("T")
|
||||
|
||||
@@ -0,0 +1,167 @@
|
||||
"""Which ladder rung a chunk's worker and judge run on: docs/decisions.md → `routing:`.
|
||||
|
||||
The worker, and the session /talk opens, run on a Route (model_routing/route.py). A model off the ladder gets a route without an item, and it is never stepped.
|
||||
|
||||
- Start. The entry point finds the plan item that routes a fresh chunk, as loop_claude/routed_item.py does; first_route picks the worker's rung from its L, or the project's rung without an item.
|
||||
- Rerun. kept decides whether a rerun resumes the route its archive last names.
|
||||
- Step-up. next_route raises the route after an unfinished verdict (unfinished_route), or an interrupt or a quoted answer that carries an escalation (escalated_route); escalation_cap bounds an escalation, and agent_cycle/escalation_mark.py states the escalation mark's rule. step_up names the change where it changes the worker line, which the archive records.
|
||||
- Judge. judge_rung picks the rung of the judge of a JUDGE_REPLAYED model.
|
||||
|
||||
A step-up weighs five rungs:
|
||||
|
||||
- the project's rung: the cheapest rung of the project's model, which each L's rung is counted from, up or down;
|
||||
- item_rung: the rung the chunk started on, which the routed item's L picked;
|
||||
- the route's rung: where the worker runs now, at or above item_rung;
|
||||
- floor_rung: the lowest rung the worker may run on next, which is the route's rung, raised where an item the worker took in has an L that picks a higher one;
|
||||
- escalation_cap: ESCALATION_CAP rungs above item_rung, the highest an escalation reaches without the human's yes.
|
||||
|
||||
Each verdict then moves the rung by one rule, and the rung never falls. The rung changes seldom, since a model switch inside a session discards that session's prompt cache.
|
||||
|
||||
| Verdict | The rung goes to | Count of unfinished verdicts | Escalation mark |
|
||||
|---|---|---|---|
|
||||
| unfinished, not the UNFINISHED_PER_STEP-th, no escalation | floor_rung | one more | holds |
|
||||
| unfinished, the UNFINISHED_PER_STEP-th since the last step | one above floor_rung | restarts | moves only with an escalation |
|
||||
| unfinished with an escalation, floor_rung below the cap | one above floor_rung, once even where the count also steps | restarts | moves |
|
||||
| unfinished with an escalation, floor_rung at the cap | floor_rung, unless the count steps | one more, unless it steps | holds unless the count steps |
|
||||
| interrupt or quoted answer with an escalation, floor_rung below the cap | one above floor_rung | restarts | moves |
|
||||
| interrupt or quoted answer with an escalation, floor_rung at the cap | floor_rung | holds | holds |
|
||||
| interrupt or quoted answer without one | holds | holds | holds |
|
||||
"""
|
||||
import dataclasses
|
||||
import typing
|
||||
|
||||
from agent_cycle import escalation_mark
|
||||
from agent_cycle.verdicts import Interrupt, QuotedAnswer, Unfinished
|
||||
from model_routing.ladder import Ladder, ProjectRung, Rung
|
||||
from model_routing.route import Route
|
||||
|
||||
UNFINISHED_PER_STEP = 2
|
||||
# How many rungs above item_rung an escalation trigger takes the worker or a task without the human's yes, as escalation_cap counts them.
|
||||
ESCALATION_CAP = 2
|
||||
# The models whose cheapest rung, in a `judge-replay` run, returned every interrupt the reference judge reproduced: docs/decisions.md → `routing: on a model judge-replay covered`.
|
||||
JUDGE_REPLAYED = ("claude-opus-5-5",)
|
||||
|
||||
|
||||
class Scored(typing.Protocol):
|
||||
"""What routes a chunk: a plan item under loop-claude, an epic's issue under do-epic."""
|
||||
@property
|
||||
def id(self) -> int:
|
||||
"""The number a Route keeps as its item."""
|
||||
|
||||
@property
|
||||
def likelihood(self) -> int:
|
||||
"""Its L."""
|
||||
|
||||
@property
|
||||
def escape_and_impact(self) -> int:
|
||||
"""Its E + I."""
|
||||
|
||||
|
||||
def first_route(project: ProjectRung, item: Scored | None) -> Route:
|
||||
"""The route a chunk starts on: the rung its item's L picks from the project's rung, or the project's rung without an item."""
|
||||
if item is None:
|
||||
return Route(project.rung)
|
||||
return Route(project.worker_rung(item.likelihood), item.id, item.likelihood, item.escape_and_impact)
|
||||
|
||||
|
||||
def kept(route: Route, project: ProjectRung) -> bool:
|
||||
"""Whether a chunk keeps route: its rung is on the ladder and at or above item_rung."""
|
||||
return floor_rung(project, route) == route.rung
|
||||
|
||||
|
||||
def item_rung(project: ProjectRung, route: Route) -> Rung:
|
||||
"""The rung the route's item's L picks from the project's rung, or the project's rung itself when no item routed it. The worker may run on a rung below the project's."""
|
||||
return project.worker_rung(route.likelihood) if route.item else project.rung
|
||||
|
||||
|
||||
def floor_rung(project: ProjectRung, route: Route, likelihood_taken_in: int = 0) -> Rung:
|
||||
"""The lowest rung the worker may run on: the route's own, raised to item_rung where it is lower or off the ladder, and to the rung likelihood_taken_in picks from project. likelihood_taken_in is the highest L the worker took into the chunk, 0 for none."""
|
||||
floor = project.ladder.highest(route.rung, item_rung(project, route))
|
||||
return project.ladder.highest(floor, project.worker_rung(likelihood_taken_in)) if likelihood_taken_in else floor
|
||||
|
||||
|
||||
def escalation_rungs(project: ProjectRung, route: Route) -> tuple[Rung, ...]:
|
||||
"""The rungs an escalation trigger opens to the worker, least competent first: from one above its own up to escalation_cap; none off the ladder."""
|
||||
ladder = project.ladder
|
||||
if route.rung not in ladder.rungs:
|
||||
return ()
|
||||
return ladder.rungs[ladder.position(route.rung) + 1:ladder.position(escalation_cap(project, route)) + 1]
|
||||
|
||||
|
||||
def escalation_cap(project: ProjectRung, route: Route) -> Rung:
|
||||
"""The highest rung an escalation trigger takes the worker or a task to without the human's yes: docs/decisions.md → `routing: a worker hands a task one rung up`.
|
||||
|
||||
It counts from item_rung, the rung the chunk started on, so a step-up between cycles narrows what the worker may climb without a yes, and never widens it.
|
||||
"""
|
||||
return project.ladder.climbed(item_rung(project, route), ESCALATION_CAP)
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class StepUp:
|
||||
"""A verdict changing the route's worker line: the route the worker ran on until the verdict, and the one it runs on after. The archive names both, so the figures charge each stretch of work to its own rung."""
|
||||
before: Route
|
||||
after: Route
|
||||
|
||||
|
||||
def next_route(project: ProjectRung | None, route: Route, verdict: Unfinished | Interrupt | QuotedAnswer) -> Route:
|
||||
"""The route the worker runs on after the judge's verdict. Off the ladder, project is None, and the route holds. The rung never falls."""
|
||||
if project is None:
|
||||
return route
|
||||
if isinstance(verdict, Unfinished):
|
||||
return unfinished_route(project, route, verdict)
|
||||
return escalated_route(project, route, verdict)
|
||||
|
||||
|
||||
def unfinished_route(project: ProjectRung, route: Route, verdict: Unfinished) -> Route:
|
||||
"""The route after an unfinished verdict, as the module docstring's table says.
|
||||
|
||||
The rung rises to floor_rung, which the verdict's highest L taken in may raise. The verdict counts towards UNFINISHED_PER_STEP. Where steps says so, the rung steps once from the floor; the mark moves only where the verdict carries an escalation. Last, the route takes in the verdict's highest E + I, as Route.taking_in does.
|
||||
"""
|
||||
floor = floor_rung(project, route, verdict.taken_in.highest_likelihood)
|
||||
mark = escalation_mark.moved_to(verdict)
|
||||
escalates = mark is not None and below_cap(project, route, floor)
|
||||
counted = route.unfinished + 1
|
||||
if steps(counted, escalates):
|
||||
after = one_rung_up(project.ladder, route, floor, route.escalated_at if mark is None else mark)
|
||||
else:
|
||||
after = dataclasses.replace(route, rung=floor, unfinished=counted)
|
||||
return after.taking_in(verdict.taken_in.highest_escape_and_impact)
|
||||
|
||||
|
||||
def escalated_route(project: ProjectRung, route: Route, verdict: Interrupt | QuotedAnswer) -> Route:
|
||||
"""The route after an interrupt or a quoted answer. Without an escalation it holds, since neither is an unfinished verdict.
|
||||
|
||||
With one, the rung rises to floor_rung, which the verdict's highest L taken in may raise. Where floor_rung lies below escalation_cap, the rung steps one up from it and the mark moves, as agent_cycle/escalation_mark.py says; at the cap the rung stays on floor_rung and the mark holds.
|
||||
"""
|
||||
mark = escalation_mark.moved_to(verdict)
|
||||
if mark is None:
|
||||
return route
|
||||
floor = floor_rung(project, route, verdict.taken_in.highest_likelihood)
|
||||
return one_rung_up(project.ladder, route, floor, mark) if below_cap(project, route, floor) else dataclasses.replace(route, rung=floor)
|
||||
|
||||
|
||||
def steps(counted: int, escalates: bool) -> bool:
|
||||
"""Whether an unfinished verdict steps the rung: it is the UNFINISHED_PER_STEP-th since the last step, or it escalates below escalation_cap. Where both hold, the rung still steps once."""
|
||||
return counted >= UNFINISHED_PER_STEP or escalates
|
||||
|
||||
|
||||
def below_cap(project: ProjectRung, route: Route, floor: Rung) -> bool:
|
||||
"""Whether an escalation from floor may step the rung: floor lies below escalation_cap."""
|
||||
return project.ladder.position(floor) < project.ladder.position(escalation_cap(project, route))
|
||||
|
||||
|
||||
def step_up(before: Route, after: Route) -> StepUp | None:
|
||||
"""The step-up from before to after; None where the worker line holds, as when only the count of unfinished verdicts changed."""
|
||||
return StepUp(before, after) if after.worker_line() != before.worker_line() else None
|
||||
|
||||
|
||||
def one_rung_up(ladder: Ladder, route: Route, rung: Rung, escalated_at: int) -> Route:
|
||||
"""The route one rung above rung, with the count of unfinished verdicts restarted and the mark at escalated_at."""
|
||||
return dataclasses.replace(route, rung=ladder.stepped_up(rung), unfinished=0, escalated_at=escalated_at)
|
||||
|
||||
|
||||
def judge_rung(ladder: Ladder, judge_model: str) -> Rung:
|
||||
"""The highest of the judge model's own rungs on ladder: docs/decisions.md → `routing: on a model judge-replay covered`. A model off the ladder, or not in JUDGE_REPLAYED, gets no effort flag, so claude runs it at the effort its settings give."""
|
||||
if ladder.project_rung(judge_model) is None or judge_model not in JUDGE_REPLAYED:
|
||||
return Rung(judge_model)
|
||||
return ladder.highest(*(rung for rung in ladder.rungs if rung.model == judge_model))
|
||||
@@ -0,0 +1,250 @@
|
||||
import dataclasses
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from agent_cycle.states import Active, Archived, Closing, Ended, Event, HumanTalked, HumanTyped, Interrupting, Judging, QUOTED_ANSWERS_PER_CYCLE, Ruled, State, to_the_human, transition, TypedAnswer, WorkerRan, Working
|
||||
from transcript_archive.write import archive
|
||||
from agent_cycle.worker import AUTO_COMPACT_WINDOW, COMPACT_WINDOW, run_worker, worker_args
|
||||
from claude_code.output_limits import BASH_CEILING, BASH_CEILING_CHARACTERS
|
||||
from agent_cycle.judge import Brief, judge, Rejected
|
||||
from claude_code.session import delete_session, Session, session_open, transcript_file
|
||||
from loop_effects.effects import Effects, say
|
||||
from claude_code.entries import Entry
|
||||
from failure import Failure
|
||||
from agent_cycle.verdicts import Finished, Interrupt, Judged, QuotedAnswer, TakenIn, Unfinished, Verdict
|
||||
from agent_cycle.interrupt import interrupt, Talked, WorkerSession
|
||||
from transcript_archive.judge_run import JudgeRun
|
||||
from transcript_archive.read import last_spent
|
||||
from agent_cycle.routing import next_route, step_up, StepUp
|
||||
from transcript_archive import outcomes
|
||||
from model_routing.ladder import ProjectRung, Rung
|
||||
from claude_code.transcript import read_transcript
|
||||
from agent_cycle.retry import retried
|
||||
from model_routing.route import Route
|
||||
from agent_cycle import spend
|
||||
from agent_cycle.stop import Stop
|
||||
from agent_cycle.tmux import Window
|
||||
from model_routing import worker_rungs
|
||||
from agent_cycle.worker_prompts import WorkerPrompts
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Cycle:
|
||||
"""What a cycle runs on. run_cycle replaces the route on a ruling's step-up; nothing changes the other fields.
|
||||
|
||||
Each step reads the few fields it needs by name, so the fields stay at one level. docs/decisions.md → `principles: about seven things per level, …` allows more than seven where a reader finds them by name.
|
||||
"""
|
||||
# The claude-config release and commit the cycle runs under, such as `v0.8.0 (<sha>)`, or why they are unknown: chunk_driver/cycle_start.py's setup_version.
|
||||
config: str
|
||||
effects: Effects
|
||||
# What chunk-preflight found, or why it could not run, for a fresh worker's prompt; empty when the session was open as the cycle began.
|
||||
facts: str
|
||||
# The rung routing.judge_rung picks for the project's judge model.
|
||||
judge: Rung
|
||||
premises: str
|
||||
# The prompts and the file names of the entry point that drives the cycle.
|
||||
prompts: WorkerPrompts
|
||||
# The project's rung on the ladder that model_routing/ladder_file.py read as the cycle started; None for a model off the ladder.
|
||||
project: ProjectRung | None
|
||||
project_archive: pathlib.Path
|
||||
records: str
|
||||
root: str
|
||||
route: Route
|
||||
session: Session
|
||||
task: str
|
||||
# The plan items a transcript's worker has taken into its chunk, as the entry point reads and scores them.
|
||||
taken_in: typing.Callable[[list[Entry]], TakenIn]
|
||||
# Empty when the previous cycle's verdict was not Unfinished.
|
||||
unfinished_evidence: str
|
||||
# The tmux window the loop runs in, which an interrupt marks.
|
||||
window: Window
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Concluded:
|
||||
"""How a cycle ended: its verdict, and the route it ended on, which an interrupt's or a quoted answer's escalation may have stepped up from the route it began on."""
|
||||
verdict: Finished | Unfinished
|
||||
route: Route
|
||||
|
||||
|
||||
def run_cycle(cycle: Cycle) -> Stop | Concluded:
|
||||
state: State = Working()
|
||||
try:
|
||||
while not isinstance(state, Ended):
|
||||
event = step(cycle, state)
|
||||
if isinstance(event, Stop):
|
||||
return stopped(cycle, event, event.reason)
|
||||
# Only a ruling's step-up changes the route within a cycle, here, once rule has archived the ruling on the route before it. No transition reads the current route, so Cycle holds it, not the states.
|
||||
if isinstance(event, Ruled) and event.stepped:
|
||||
cycle = dataclasses.replace(cycle, route=event.stepped.after)
|
||||
state = transition(state, event)
|
||||
except KeyboardInterrupt:
|
||||
return stopped(cycle, Stop(130, ""), "Ctrl-C")
|
||||
return Concluded(state.verdict, cycle.route)
|
||||
|
||||
|
||||
def ruling_step_up(cycle: Cycle, verdict: Verdict) -> StepUp | None:
|
||||
"""The step-up an interrupt's or a quoted answer's escalation makes, so the work after the answer runs on the stepped route; None where the route holds. A finished or unfinished verdict steps the route only as the loop starts the next cycle."""
|
||||
return step_up(cycle.route, next_route(cycle.project, cycle.route, verdict)) if isinstance(verdict, Interrupt | QuotedAnswer) else None
|
||||
|
||||
|
||||
def stopped(cycle: Cycle, stop: Stop, why: str) -> Stop:
|
||||
return archived_stop(cycle.project_archive, cycle.session, cycle.task, cycle.route, stop, why, cycle.effects)
|
||||
|
||||
|
||||
def archived_stop(project_archive: pathlib.Path, session: Session, task: str, route: Route, stop: Stop, why: str, effects: Effects) -> Stop:
|
||||
"""stop, once archived with the route the worker holds. A failed archive exits 1 whatever the stop; when the stop was this archive failing, its reason is said once."""
|
||||
path = transcript_file(session)
|
||||
failure = archived(project_archive, path, task, outcomes.stopped(route.worker_line(), why), effects) if path else None
|
||||
return Stop(1, f"{failure.reason}\n{stop.reason}".rstrip()) if failure and failure.reason != stop.reason else stop
|
||||
|
||||
|
||||
def archived(project_archive: pathlib.Path, transcript_path: str, task: str, outcome: str, effects: Effects, judge_run: JudgeRun | None = None) -> Failure | None:
|
||||
"""transcript_archive.write.archive, stamped now and saying its notes through effects. A cycle and close.py, which has no Cycle, both archive through it."""
|
||||
return archive(project_archive, transcript_path, task, outcome, effects.now(), lambda text: say(text, effects), judge_run, replace=effects.replace_file)
|
||||
|
||||
|
||||
def step(cycle: Cycle, state: Active) -> Event | Stop:
|
||||
match state:
|
||||
case Working(answered, _, stepped):
|
||||
return work(cycle, answered, stepped)
|
||||
case Judging(transcript_path, quoted_answers):
|
||||
return rule(cycle, transcript_path, quoted_answers)
|
||||
case Interrupting(transcript_path, ruling, _, stepped_from):
|
||||
return ask(cycle, transcript_path, ruling, stepped_from)
|
||||
case Closing(transcript_path, verdict):
|
||||
return close(cycle, transcript_path, verdict)
|
||||
case _:
|
||||
typing.assert_never(state)
|
||||
|
||||
|
||||
def work(cycle: Cycle, answered: QuotedAnswer | TypedAnswer | None, stepped: bool) -> WorkerRan | Stop:
|
||||
if isinstance(answered, QuotedAnswer):
|
||||
say(f"\n=== {cycle.prompts.quote_sources} answered: {answered.question} ===\n{answered.answer}", cycle.effects, stdout=True)
|
||||
# worker_start runs inside the lambda: a failed attempt may have opened the session.
|
||||
if stop := retried("worker", lambda: run_worker(cycle.root, worker_start(cycle, answered, stepped), worker_environment(cycle), cycle.project_archive, cycle.project.rung if cycle.project else cycle.route.rung, cycle.effects), cycle.effects):
|
||||
return stop
|
||||
path = transcript_file(cycle.session)
|
||||
return WorkerRan(path) if path is not None else Stop(1, f"claude left no transcript for session {cycle.session.id}")
|
||||
|
||||
|
||||
def worker_environment(cycle: Cycle) -> dict[str, str]:
|
||||
"""The rungs the worker's claude is handed, which rule-hook holds its review launches to, the auto-compact window of its context, and the length past which it saves a Bash result to a file."""
|
||||
return {**worker_rungs.environment(cycle.project, cycle.route), AUTO_COMPACT_WINDOW: str(COMPACT_WINDOW), BASH_CEILING: str(BASH_CEILING_CHARACTERS)}
|
||||
|
||||
|
||||
def worker_session(cycle: Cycle, transcript_path: str, stepped_from: Rung | None) -> WorkerSession:
|
||||
return WorkerSession(cycle.root, cycle.session.id, cycle.route.rung, stepped_from or cycle.route.rung, transcript_path, worker_environment(cycle))
|
||||
|
||||
|
||||
def worker_start(cycle: Cycle, answered: QuotedAnswer | TypedAnswer | None, stepped: bool) -> list[str]:
|
||||
if isinstance(answered, QuotedAnswer):
|
||||
return worker_args(cycle.session, cycle.route.rung, cycle.prompts.answered(answered.question, answered.answer, cycle.route, cycle.project, stepped), resume=True)
|
||||
if isinstance(answered, TypedAnswer):
|
||||
return worker_args(cycle.session, cycle.route.rung, cycle.prompts.typed(answered.question, answered.answer, cycle.route, cycle.project, stepped), resume=True)
|
||||
if session_open(cycle.session):
|
||||
return worker_args(cycle.session, cycle.route.rung, cycle.prompts.resumed(cycle.unfinished_evidence, cycle.route, cycle.project), resume=True)
|
||||
return worker_args(cycle.session, cycle.route.rung, cycle.prompts.fresh(cycle.task, cycle.premises, cycle.route, cycle.project, cycle.facts), resume=False)
|
||||
|
||||
|
||||
def rule(cycle: Cycle, transcript_path: str, quoted_answers: int) -> Ruled | Stop:
|
||||
"""The judge's ruling. Unless it is Finished, code stamps it with the items the worker took in, as cycle.taken_in reads them. An interrupt or a quoted answer is archived as it is ruled, on the route the worker ran on until then, and then any step-up it makes, so the figures charge each stretch of work to its own rung."""
|
||||
entries = read_transcript(transcript_path)
|
||||
if isinstance(entries, Failure):
|
||||
return Stop(1, entries.reason)
|
||||
brief = Brief(
|
||||
task=cycle.task,
|
||||
premises=cycle.premises,
|
||||
records=cycle.records,
|
||||
records_named=cycle.prompts.records_named,
|
||||
answer_destinations=cycle.prompts.answer_destinations,
|
||||
entries=entries,
|
||||
escalated_at=cycle.route.escalated_at,
|
||||
driver=cycle.prompts.driver,
|
||||
)
|
||||
verdict = judge(cycle.root, brief, cycle.judge, cycle.effects, lambda rejected: keep_rejection(cycle, transcript_path, rejected))
|
||||
if isinstance(verdict, Stop):
|
||||
return verdict
|
||||
if not isinstance(verdict, Finished):
|
||||
verdict = dataclasses.replace(verdict, taken_in=cycle.taken_in(entries))
|
||||
if not isinstance(verdict, Interrupt | QuotedAnswer):
|
||||
return Ruled(verdict)
|
||||
annotation = annotation_of(cycle, transcript_path, entries, verdict.judged)
|
||||
if isinstance(annotation, Failure):
|
||||
return Stop(1, annotation.reason)
|
||||
stepped = ruling_step_up(cycle, verdict)
|
||||
if failure := archive_stepped(cycle, transcript_path, ruling_outcome(cycle, verdict, quoted_answers, annotation), stepped, verdict.judged.run):
|
||||
return Stop(1, failure.reason)
|
||||
return Ruled(verdict, stepped)
|
||||
|
||||
|
||||
def annotation_of(cycle: Cycle, transcript_path: str, entries: list[Entry], judged: Judged) -> outcomes.Annotation | Failure:
|
||||
"""What a verdict, an interrupt or a quoted answer records beside its judge lines: the setup, the stretch's spend as spend.py counts it, and the reversal the judge found."""
|
||||
since = last_spent(cycle.project_archive, transcript_path)
|
||||
if isinstance(since, Failure):
|
||||
return since
|
||||
subagents = spend.subagents(transcript_path)
|
||||
if isinstance(subagents, Failure):
|
||||
return subagents
|
||||
spent = spend.spent(since, entries, subagents, cycle.judge.model, judged.tokens)
|
||||
return outcomes.Annotation(cycle.config, outcomes.spent_block(since, spent), judged.reversed)
|
||||
|
||||
|
||||
def ruling_outcome(cycle: Cycle, ruling: Interrupt | QuotedAnswer, quoted_answers: int, annotation: outcomes.Annotation) -> str:
|
||||
"""The archive's outcome for a ruling: interrupted where it goes to the human, with the question put to them, and else answered from the premises or the records."""
|
||||
if isinstance(ruling, QuotedAnswer) and not to_the_human(ruling, quoted_answers):
|
||||
return outcomes.answered(question=ruling.question, sources=cycle.prompts.quote_sources, answer=ruling.answer, evidence=ruling.evidence, escalation=ruling.escalation, judge=str(cycle.judge), worker=cycle.route.worker_line(), judge_cost=ruling.judged.cost, annotation=annotation, judge_run=ruling.judged.run)
|
||||
return outcomes.interrupted(question_for(cycle, ruling), ruling.evidence, str(cycle.judge), ruling.escalation, cycle.route.worker_line(), judge_cost=ruling.judged.cost, annotation=annotation, judge_run=ruling.judged.run)
|
||||
|
||||
|
||||
def keep_rejection(cycle: Cycle, transcript_path: str, rejected: Rejected) -> Stop | None:
|
||||
"""Archives a judge reply loop-claude rejected, so the archive shows what the judge returned before a retry or an exit 1."""
|
||||
if unkept := archived(cycle.project_archive, transcript_path, cycle.task, outcomes.rejected(rejected.reason, rejected.reply, str(cycle.judge), judge_cost=rejected.cost, judge_run=rejected.run), cycle.effects, rejected.run):
|
||||
return Stop(1, unkept.reason)
|
||||
return None
|
||||
|
||||
|
||||
def ask(cycle: Cycle, transcript_path: str, ruling: Interrupt | QuotedAnswer, stepped_from: Rung | None) -> HumanTyped | HumanTalked | Stop:
|
||||
"""The human's answer to a ruling that rule archived as it ruled; the human's answer then grows the transcript. stepped_from is the rung the worker ran on, where the ruling stepped it up."""
|
||||
# Only the human may cut a release, so a release ready to cut opens claude's session at once.
|
||||
answer = interrupt(question_for(cycle, ruling), not (isinstance(ruling, Interrupt) and ruling.release_ready), worker_session(cycle, transcript_path, stepped_from), cycle.window, cycle.prompts.driver, cycle.effects)
|
||||
match answer:
|
||||
case Stop():
|
||||
return answer
|
||||
case Talked():
|
||||
return HumanTalked()
|
||||
# The worker gets the question it asked, not the one put to the human past the cap.
|
||||
return HumanTyped(TypedAnswer(ruling.question, answer))
|
||||
|
||||
|
||||
def archive_stepped(cycle: Cycle, transcript_path: str, outcome: str, step_up: StepUp | None, judge_run: JudgeRun | None) -> Failure | None:
|
||||
"""Archives the outcome of a ruling and the judge run that gave it, then the step-up it made, if it made one. The first failure is returned."""
|
||||
if failure := archived(cycle.project_archive, transcript_path, cycle.task, outcome, cycle.effects, judge_run):
|
||||
return failure
|
||||
return archived_step(cycle.project_archive, transcript_path, cycle.task, step_up, cycle.effects)
|
||||
|
||||
|
||||
def archived_step(project_archive: pathlib.Path, transcript_path: str, task: str, step_up: StepUp | None, effects: Effects) -> Failure | None:
|
||||
"""Archives a step-up, if there is one, as the worker line it steps to. The outcome archived before it names the route the worker ran on until then, so the figures charge each stretch of work to its own rung. Both a ruling within a cycle and an unfinished verdict between cycles archive their step-up here."""
|
||||
if step_up is None:
|
||||
return None
|
||||
return archived(project_archive, transcript_path, task, outcomes.stepped_up(step_up.after.worker_line()), effects)
|
||||
|
||||
|
||||
def question_for(cycle: Cycle, ruling: Interrupt | QuotedAnswer) -> str:
|
||||
if isinstance(ruling, Interrupt):
|
||||
return ruling.question
|
||||
return cycle.prompts.past_the_cap(ruling.question, ruling.answer, QUOTED_ANSWERS_PER_CYCLE)
|
||||
|
||||
|
||||
def close(cycle: Cycle, transcript_path: str, verdict: Finished | Unfinished) -> Archived | Stop:
|
||||
entries = read_transcript(transcript_path)
|
||||
annotation = entries if isinstance(entries, Failure) else annotation_of(cycle, transcript_path, entries, verdict.judged)
|
||||
if isinstance(annotation, Failure):
|
||||
return Stop(1, annotation.reason)
|
||||
outcome = outcomes.finished(cycle.route.worker_line(), verdict.evidence, str(cycle.judge), judge_cost=verdict.judged.cost, annotation=annotation, judge_run=verdict.judged.run) if isinstance(verdict, Finished) else outcomes.unfinished(cycle.route.worker_line(), verdict.evidence, str(cycle.judge), verdict.escalation, judge_cost=verdict.judged.cost, annotation=annotation, judge_run=verdict.judged.run)
|
||||
if failure := archived(cycle.project_archive, transcript_path, cycle.task, outcome, cycle.effects, verdict.judged.run):
|
||||
return Stop(1, failure.reason)
|
||||
if isinstance(verdict, Finished) and (failure := delete_session(cycle.session)):
|
||||
return Stop(1, failure.reason)
|
||||
return Archived()
|
||||
@@ -0,0 +1,78 @@
|
||||
"""What a stretch of the chunk's work spent, in raw tokens by model and kind, which the archive records beside each verdict, interrupt and quoted answer: docs/decisions.md → `loop-claude: each verdict records the claude-config release and commit that ran it…`.
|
||||
|
||||
A stretch runs from the previous outcome that recorded a spend, or from the chunk's start, to the ruling. It counts the worker's main thread, each subagent and the judge run that ruled, each message once. Dollars are left to be derived from the model and the tokens, at the prices recorded beside them.
|
||||
"""
|
||||
import datetime
|
||||
import json
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from claude_code.entries import AssistantTurn, Entry, messages
|
||||
from failure import Failure
|
||||
from claude_code.transcript import read_transcript
|
||||
from transcript_archive.outcomes import Spender
|
||||
from claude_code.tokens import Tokens, tokens_of
|
||||
|
||||
WORKER = "worker"
|
||||
JUDGE = "judge"
|
||||
|
||||
|
||||
class Subagent(typing.NamedTuple):
|
||||
"""A subagent's transcript, named by the agent type and the description its .meta.json gives: {"agentType": "Explore", "description": "Search the hooks", ...}."""
|
||||
name: str
|
||||
entries: list[Entry]
|
||||
|
||||
|
||||
def spent(since: str, worker: list[Entry], subagents: list[Subagent], judge_model: str, judge: Tokens) -> dict[Spender, Tokens]:
|
||||
"""The tokens each spender spent after since, a UTC stamp, or in the whole transcript where since is empty."""
|
||||
found: dict[Spender, Tokens] = {}
|
||||
for name, entries in ((WORKER, worker), *subagents):
|
||||
for model, tokens in thread_spend(entries, since).items():
|
||||
found[name, model] = found.get((name, model), Tokens()).plus(tokens)
|
||||
found[JUDGE, judge_model] = judge
|
||||
return {spender: tokens for spender, tokens in found.items() if tokens != Tokens()}
|
||||
|
||||
|
||||
def thread_spend(entries: list[Entry], since: str) -> dict[str, Tokens]:
|
||||
"""Each model's tokens in one transcript's messages written after since. Each message counts once."""
|
||||
start = moment(since) if since else None
|
||||
found: dict[str, Tokens] = {}
|
||||
for turn, *_ in messages(entry for entry in entries if isinstance(entry, AssistantTurn) and entry.model and (start is None or later(entry.timestamp, start))):
|
||||
found[turn.model] = found.get(turn.model, Tokens()).plus(tokens_of(turn.usage))
|
||||
return found
|
||||
|
||||
|
||||
def moment(stamp: str) -> datetime.datetime:
|
||||
return datetime.datetime.fromisoformat(stamp)
|
||||
|
||||
|
||||
# An outcome's stamp runs to the second, so a message written earlier in that second would count in both stretches. The worker writes none then, since the judge runs for seconds after its last message. A subagent or a /talk session still running may write one, and that message is then counted twice.
|
||||
def later(timestamp: str, start: datetime.datetime) -> bool:
|
||||
"""Whether timestamp is after start; False where it is no time, or names no time zone to compare by."""
|
||||
try:
|
||||
return moment(timestamp) > start
|
||||
except (TypeError, ValueError):
|
||||
return False
|
||||
|
||||
|
||||
def subagents(transcript_path: str) -> list[Subagent] | Failure:
|
||||
"""The subagents' transcripts Claude Code keeps beside the worker's: <session>/subagents/agent-<id>.jsonl, each with its .meta.json."""
|
||||
found = []
|
||||
for path in sorted(pathlib.Path(transcript_path.removesuffix(".jsonl"), "subagents").glob("*.jsonl")):
|
||||
entries = read_transcript(str(path))
|
||||
if isinstance(entries, Failure):
|
||||
return entries
|
||||
found.append(Subagent(subagent_name(path), entries))
|
||||
return found
|
||||
|
||||
|
||||
def subagent_name(transcript: pathlib.Path) -> str:
|
||||
"""The agent type and the quoted description; `subagent` where the meta is missing or names neither."""
|
||||
try:
|
||||
meta = json.loads(transcript.with_name(transcript.name.removesuffix(".jsonl") + ".meta.json").read_text(encoding="utf-8"))
|
||||
except (OSError, UnicodeDecodeError, ValueError):
|
||||
meta = {}
|
||||
meta = meta if isinstance(meta, dict) else {}
|
||||
# One line for the type, since a line break could forge an archive line such as `Config: `; json.dumps escapes the description's.
|
||||
kind, description = " ".join(str(meta.get("agentType") or "subagent").split()), str(meta.get("description") or "")
|
||||
return f"{kind} {json.dumps(description, ensure_ascii=False)}" if description else kind
|
||||
@@ -1,22 +1,23 @@
|
||||
import dataclasses
|
||||
|
||||
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
|
||||
from model_routing.route import Route
|
||||
from agent_cycle.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
|
||||
from model_routing.ladder import Rung
|
||||
from agent_cycle.routing import StepUp
|
||||
|
||||
# A backstop for what the judge misses, such as a reworded repeat, so the worker cannot loop unattended on answers quoted from README.md or the records.
|
||||
# A backstop for what the judge misses, such as a reworded repeat, so the worker cannot loop unattended on answers quoted from the premises or the records.
|
||||
QUOTED_ANSWERS_PER_CYCLE = 3
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class TypedAnswer:
|
||||
"""The human's answer to an interrupt, typed at loop-claude's terminal or in loop-inbox."""
|
||||
"""The human's answer to an interrupt, typed at loop-claude's terminal."""
|
||||
question: str
|
||||
answer: str
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Working:
|
||||
"""The worker runs, resumed with an answer quoted from README.md or the records, or typed by the human, when there is one."""
|
||||
"""The worker runs, resumed with an answer quoted from the premises or the records, or typed by the human, when there is one."""
|
||||
answered: QuotedAnswer | TypedAnswer | None = None
|
||||
quoted_answers: int = 0
|
||||
# Whether the ruling that brought the answer stepped the worker up a rung, so the worker is told of it.
|
||||
@@ -25,7 +26,7 @@ class Working:
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Judging:
|
||||
"""The judge rules; quoted_answers counts the questions README.md or the records answered this cycle, and an interrupt does not reset it."""
|
||||
"""The judge rules; quoted_answers counts the questions the premises or the records answered this cycle, and an interrupt does not reset it."""
|
||||
transcript_path: str
|
||||
quoted_answers: int = 0
|
||||
|
||||
@@ -36,8 +37,8 @@ class Interrupting:
|
||||
transcript_path: str
|
||||
ruling: Interrupt | QuotedAnswer
|
||||
quoted_answers: int = 0
|
||||
# Whether the ruling stepped the worker up a rung. It holds through the answer the human types, and drops on /talk.
|
||||
stepped: bool = False
|
||||
# The rung the worker ran on, where the ruling stepped it up from there; None where the rung holds. It holds through the answer the human types, and drops on /talk.
|
||||
stepped_from: Rung | None = None
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
@@ -63,8 +64,8 @@ class WorkerRan:
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Ruled:
|
||||
verdict: Verdict
|
||||
# The route an interrupt's or a quoted answer's escalation stepped the worker up to, which the cycle runs on from here; None where the route holds, and always for a finished or unfinished verdict.
|
||||
stepped_to: Route | None = None
|
||||
# The step-up an interrupt's or a quoted answer's escalation made, whose `after` the cycle runs on from here; None where the route holds, and always for a finished or unfinished verdict.
|
||||
stepped: StepUp | None = None
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
@@ -94,14 +95,14 @@ def transition(state: State, event: Event) -> State:
|
||||
match state, event:
|
||||
case Working(_, quoted_answers), WorkerRan(transcript_path):
|
||||
return Judging(transcript_path, quoted_answers)
|
||||
case Judging(transcript_path, quoted_answers), Ruled(Interrupt() | QuotedAnswer() as ruling, stepped_to) if to_the_human(ruling, quoted_answers):
|
||||
return Interrupting(transcript_path, ruling, quoted_answers, stepped_to is not None)
|
||||
case Judging(_, quoted_answers), Ruled(QuotedAnswer() as answered, stepped_to):
|
||||
return Working(answered, quoted_answers + 1, stepped_to is not None)
|
||||
case Judging(transcript_path, quoted_answers), Ruled(Interrupt() | QuotedAnswer() as ruling, stepped) if to_the_human(ruling, quoted_answers):
|
||||
return Interrupting(transcript_path, ruling, quoted_answers, stepped.before.rung if stepped else None)
|
||||
case Judging(_, quoted_answers), Ruled(QuotedAnswer() as answered, stepped):
|
||||
return Working(answered, quoted_answers + 1, stepped is not None)
|
||||
case Judging(transcript_path, _), Ruled(Finished() | Unfinished() as verdict):
|
||||
return Closing(transcript_path, verdict)
|
||||
case Interrupting(_, _, quoted_answers, stepped), HumanTyped(typed):
|
||||
return Working(typed, quoted_answers, stepped)
|
||||
case Interrupting(_, _, quoted_answers, stepped_from), HumanTyped(typed):
|
||||
return Working(typed, quoted_answers, stepped_from is not None)
|
||||
# The human worked in the worker's claude session, so the judge rules again on the transcript it leaves.
|
||||
case Interrupting(transcript_path, _, quoted_answers), HumanTalked():
|
||||
return Judging(transcript_path, quoted_answers)
|
||||
@@ -0,0 +1,20 @@
|
||||
import dataclasses
|
||||
import typing
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Stop:
|
||||
"""The entry point exits with code, printing reason."""
|
||||
code: typing.Literal[0, 1, 2, 130]
|
||||
reason: str
|
||||
|
||||
|
||||
def needs_human(need: str, blocker: str) -> Stop:
|
||||
return Stop(2, f"the human is needed to {need}, but {blocker}")
|
||||
|
||||
|
||||
def needs_terminal(need: str, on_terminal: bool, driver: str) -> Stop | None:
|
||||
"""driver is the entry point the human reruns, such as `do-epic`."""
|
||||
if on_terminal:
|
||||
return None
|
||||
return needs_human(need, f"stdin or stdout is not a terminal; rerun {driver} on a terminal")
|
||||
@@ -0,0 +1,115 @@
|
||||
"""Reports whether a worker that has gone quiet before its final result is stuck, as a headless claude judges it.
|
||||
|
||||
A worker can stall on a command that hangs, as a full test run did on a shell that ignored SIGINT (item 402). The check runs on the tick `lingering_workers` uses: CHECK_EVERY seconds after the worker's last line. It looks for two signs in each of the worker's shells. One is a shell that used no CPU since the last check and wrote no output for QUIET seconds. The other is a shell older than OLD. A shell that runs a busy tool, as `Shell.runs_busy_tool` says, shows neither sign, since waiting for a slot or a merge is work. A shell that holds a heavy slot can show them, since a hung test run holds one.
|
||||
|
||||
Where a shell shows a sign, a headless claude judges the worker from each shell's command, processes and output tail. These hold what the worker's tmux pane shows, so each chunk's loop checks its own worker, and no process watches a whole tmux session. A shell is judged again only where it used CPU since its last judgment and then went idle, so a stall that lasts all night costs one call.
|
||||
|
||||
The check only reports, on the terminal and in RECORD in the project's transcript archive. Killing the process it names waits until the recorded verdicts match what the human would have done.
|
||||
"""
|
||||
import dataclasses
|
||||
import json
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from agent_cycle.lingering_workers import CHECK_EVERY, QUIET
|
||||
from claude_code.reply import claude_reply, Limited
|
||||
from loop_effects.effects import Effects, say, Streaming
|
||||
from failure import Failure
|
||||
from model_routing.ladder import Rung
|
||||
from loop_effects.child_shells import Shell
|
||||
from claude_code.entries import structured_output
|
||||
from text_files.utc_stamp import utc
|
||||
|
||||
# Seconds after which a shell holds a worker longer than a chunk usually runs.
|
||||
OLD = 4 * 3600
|
||||
RECORD = "stuck-workers.md"
|
||||
VERDICTS = ("working", "waiting on a person", "stuck")
|
||||
SCHEMA = {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"verdict": {"enum": list(VERDICTS)},
|
||||
"process": {"type": "integer", "description": "The pid of the process that holds the worker, from the evidence."},
|
||||
"why": {"type": "string", "description": "One sentence on why that process holds it."},
|
||||
},
|
||||
"required": ["verdict", "process", "why"],
|
||||
"additionalProperties": False,
|
||||
}
|
||||
PROMPT = f"""A headless Claude Code worker hasn't printed anything for {CHECK_EVERY} seconds. Judge from its shells below whether it is `working`, `waiting on a person` or `stuck`. Name the pid of the process it waits on, and say why.
|
||||
- Working: it waits on a process that will finish, such as a test run that still writes output or uses CPU, or run-heavy waiting for a slot.
|
||||
- Waiting on a person: it waits on input or an approval only a person can give, such as a prompt read from a terminal.
|
||||
- Stuck: it waits on a process that will never finish on its own, such as a command waiting on a child that never exits.
|
||||
"""
|
||||
|
||||
|
||||
@dataclasses.dataclass
|
||||
class Watch:
|
||||
"""What checks a worker for stuck shells: the rung its investigations run on, the project's transcript archive, each shell's CPU seconds at the last check, and the CPU seconds of each shell that showed a sign at the latest judgment."""
|
||||
rung: Rung
|
||||
archive: pathlib.Path
|
||||
cpu: dict[int, float] = dataclasses.field(default_factory=dict)
|
||||
judged: dict[int, float] = dataclasses.field(default_factory=dict)
|
||||
|
||||
def check(self, proc: Streaming, root: str, effects: Effects) -> None:
|
||||
"""Has a headless claude judge the worker whose claude is proc, where a shell shows a sign and is due a judgment. The verdict, or why there is none, goes to the terminal and to RECORD."""
|
||||
now = effects.now()
|
||||
shells = proc.shells()
|
||||
before, self.cpu = self.cpu, {shell.pid: shell.cpu for shell in shells}
|
||||
signs = {shell.pid: sign for shell in shells if (sign := sign_of(shell, before.get(shell.pid), now))}
|
||||
# A shell is judged again only where it used CPU since its judgment and then went idle, so one stall costs one call, and a stall after a `working` verdict still gets one.
|
||||
if not any(shell.pid not in self.judged or self.judged[shell.pid] != shell.cpu and idle(shell, before.get(shell.pid), now) for shell in shells if shell.pid in signs):
|
||||
return
|
||||
judged = investigated(shells, self.rung, root, effects)
|
||||
if isinstance(judged, Failure):
|
||||
line = f"stuck check: could not judge whether the worker is stuck: {judged.reason}"
|
||||
else:
|
||||
self.judged = {shell.pid: shell.cpu for shell in shells if shell.pid in signs}
|
||||
line = f"stuck check: a headless claude judged the worker {judged['verdict']}, naming process {judged['process']} ({command_of(judged['process'], shells)}): {judged['why']}"
|
||||
line = " ".join(line.split()) + "".join(f"\n - {' '.join(sign.split())}" for sign in signs.values())
|
||||
say(line, effects, stdout=not isinstance(judged, Failure))
|
||||
record = self.archive / RECORD
|
||||
try:
|
||||
record.parent.mkdir(parents=True, exist_ok=True)
|
||||
with record.open("a") as handle:
|
||||
handle.write(f"- {utc(now)} {line}\n")
|
||||
except OSError as failure:
|
||||
say(f"could not record the stuck check in {record}: {failure.strerror}", effects)
|
||||
|
||||
|
||||
def sign_of(shell: Shell, cpu_before: float | None, now: float) -> str:
|
||||
"""The sign that shell may hold its worker stuck, given the CPU seconds it had used at the last check; empty where it shows none."""
|
||||
if shell.runs_busy_tool:
|
||||
return ""
|
||||
quiet = idle(shell, cpu_before, now)
|
||||
if not (quiet or now - shell.started > OLD):
|
||||
return ""
|
||||
return f"shell {shell.pid} has run {int(now - shell.started)} s and written no output for {int(now - shell.written)} s{f', and used no CPU for {CHECK_EVERY} s' if quiet else ''}: {shell.command}"
|
||||
|
||||
|
||||
def idle(shell: Shell, cpu_before: float | None, now: float) -> bool:
|
||||
"""Whether shell used no CPU since the last check, when it had used cpu_before, and wrote no output for QUIET seconds."""
|
||||
return cpu_before == shell.cpu and now - shell.written > QUIET
|
||||
|
||||
|
||||
def command_of(pid: int, shells: list[Shell]) -> str:
|
||||
"""The command line of the process pid among shells and the processes below them, as the evidence shows it; `not in the evidence` where neither holds pid, and `no command line` where its line is empty, as a defunct process's is."""
|
||||
for shell in shells:
|
||||
if shell.pid == pid:
|
||||
return shell.command
|
||||
for line in shell.processes:
|
||||
if line.startswith(f"{pid} "):
|
||||
return line.split(" ", 4)[4] or "no command line"
|
||||
return "not in the evidence"
|
||||
|
||||
|
||||
def investigated(shells: list[Shell], rung: Rung, root: str, effects: Effects) -> dict[str, typing.Any] | Failure:
|
||||
"""A headless claude's verdict on the worker holding shells, as SCHEMA has it, or why there is none. It runs without tools, so it judges only the evidence it is handed."""
|
||||
evidence = "\n\n".join(f"Shell {shell.pid}: {shell.command}\nIts processes, as pid, state, CPU and command line:\n{chr(10).join(shell.processes) or 'none'}\nThe end of its output:\n{shell.output or 'none'}" for shell in shells)
|
||||
reply = claude_reply(effects.claude, ["--json-schema", json.dumps(SCHEMA), *rung.flags(), "--tools", "", "--strict-mcp-config"], root, PROMPT + "\n" + evidence, "the stuck check")
|
||||
if isinstance(reply, Limited):
|
||||
return Failure(f"claude hit a limit: {reply.said}")
|
||||
if isinstance(reply, Failure):
|
||||
return reply
|
||||
output = structured_output(reply)
|
||||
if not (isinstance(output, dict) and output.get("verdict") in VERDICTS and isinstance(output.get("process"), int) and isinstance(output.get("why"), str)):
|
||||
return Failure(f"answered outside its schema: {output!r}")
|
||||
return output
|
||||
@@ -0,0 +1,229 @@
|
||||
import contextlib
|
||||
import dataclasses
|
||||
import io
|
||||
import json
|
||||
import pathlib
|
||||
import shutil
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
import uuid
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from loop_effects.doubles import assistant, FakeEffects, human, NOW, STAMP, Streamed
|
||||
from failure import Failure
|
||||
from agent_cycle import interrupt
|
||||
from machine_load import memory
|
||||
from loop_state import paths
|
||||
from model_routing.ladder import Rung
|
||||
from agent_cycle.stop import Stop
|
||||
from agent_cycle import tmux
|
||||
from text_files.utc_stamp import utc
|
||||
from agent_cycle.doubles import WINDOW
|
||||
|
||||
|
||||
class Interrupts(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.home = pathlib.Path(tempfile.mkdtemp())
|
||||
self.addCleanup(shutil.rmtree, self.home)
|
||||
self.paths = paths.paths_from(self.home)
|
||||
self.transcript = self.home / "t.jsonl"
|
||||
self.transcript.write_text(json.dumps(human("a")) + "\n")
|
||||
self.session = interrupt.WorkerSession(str(self.home), uuid.uuid7(), Rung("m", "high"), Rung("m", "high"), str(self.transcript), {"LOOP_CLAUDE_WORKER_RUNG": "m at high effort"})
|
||||
|
||||
def put(self, fake, answer_here=True, effects=None, question="Which one?"):
|
||||
"""interrupt's answer and what it said, without the bell it rang, which self.bells counts."""
|
||||
with contextlib.redirect_stderr(io.StringIO()) as said:
|
||||
answer = interrupt.interrupt(question, answer_here, self.session, WINDOW, "loop-claude", effects or fake.effects())
|
||||
self.bells = said.getvalue().count(tmux.BELL)
|
||||
return answer, said.getvalue().replace(tmux.BELL, "")
|
||||
|
||||
def typed_there(self, args):
|
||||
"""The claude opened on the terminal: the human types a line in the worker's session, and it ends."""
|
||||
with open(self.transcript, "a") as handle:
|
||||
handle.write(json.dumps(human("cut it")) + "\n")
|
||||
return 0
|
||||
|
||||
def worked(self, minutes_ago, written_1h=5000, read=70000, written_5m=0):
|
||||
"""Appends the worker's last message, sent minutes_ago before NOW, whose usage wrote written_1h tokens to the hour-long cache, written_5m to the five-minute one, and read read tokens from the cache."""
|
||||
said = assistant({"type": "text", "text": "Which one?"})
|
||||
said["timestamp"] = utc(NOW - minutes_ago * 60)
|
||||
said["message"] |= {"id": "msg-1", "model": "m", "usage": {"input_tokens": 2, "cache_creation": {"ephemeral_5m_input_tokens": written_5m, "ephemeral_1h_input_tokens": written_1h}, "cache_read_input_tokens": read, "output_tokens": 100}}
|
||||
with open(self.transcript, "a") as handle:
|
||||
handle.write(json.dumps(said) + "\n")
|
||||
|
||||
def fired(self, fake, answer):
|
||||
"""An input that first fires every timer started, then returns answer as the line the human typed."""
|
||||
def typed(prompt):
|
||||
for _, action in fake.timers:
|
||||
action()
|
||||
return answer
|
||||
return typed
|
||||
|
||||
def test_compacts_the_workers_session_ten_minutes_before_its_hour_long_prompt_cache_expires_and_keeps_waiting(self):
|
||||
self.worked(minutes_ago=10)
|
||||
fake = FakeEffects(streams=[Streamed(0)])
|
||||
fake.scripts["input"] = [self.fired(fake, "Use B.")]
|
||||
answer, said = self.put(fake)
|
||||
self.assertEqual(answer, "Use B.")
|
||||
self.assertEqual([delay for delay, _ in fake.timers], [40 * 60])
|
||||
self.assertEqual([what for seam, what in fake.calls if seam == "stream_claude"], [["--model", "m", "--effort", "high", "--permission-mode", "bypassPermissions", "-p", "/compact", "--resume", str(self.session.id), "--output-format", "stream-json", "--verbose"]])
|
||||
self.assertEqual(fake.worker_environments, [self.session.env])
|
||||
self.assertEqual(fake.worker_folders, [self.session.root])
|
||||
self.assertIn(f"\n{STAMP} compacting the worker's claude session before its prompt cache expires; an answer typed meanwhile is read once that ends\n\n{STAMP} compacted the worker's claude session\n", said)
|
||||
self.assertNotIn("still waiting", said)
|
||||
|
||||
def test_compacts_on_the_rung_the_worker_ran_on_where_a_ruling_stepped_it_up_and_talk_opens_claude_on_the_new_rung(self):
|
||||
self.worked(minutes_ago=10)
|
||||
self.session = dataclasses.replace(self.session, rung=Rung("n", "medium"))
|
||||
fake = FakeEffects(streams=[Streamed(0)], on_terminal_claude=[self.typed_there])
|
||||
fake.scripts["input"] = [self.fired(fake, "/talk")]
|
||||
self.assertEqual(self.put(fake)[0], interrupt.Talked())
|
||||
(compaction,), (opened,) = fake.made("stream_claude"), fake.made("claude_on_terminal")
|
||||
self.assertEqual(compaction[:4], ["--model", "m", "--effort", "high"])
|
||||
self.assertEqual(opened[:4], ["--model", "n", "--effort", "medium"])
|
||||
|
||||
def test_compacts_until_the_prompt_cache_expires_and_not_from_then_on(self):
|
||||
for name, late, compactions in (("a second before", 50 * 60 - 1, 1), ("as it expires", 50 * 60, 0)):
|
||||
with self.subTest(name):
|
||||
self.transcript.write_text(json.dumps(human("a")) + "\n")
|
||||
self.worked(minutes_ago=10)
|
||||
fake = FakeEffects(streams=[Streamed(0)])
|
||||
clock = [NOW]
|
||||
|
||||
def typed(prompt):
|
||||
clock[0] = NOW + late
|
||||
for _, action in fake.timers:
|
||||
action()
|
||||
return "Use B."
|
||||
fake.scripts["input"] = [typed]
|
||||
answer, said = self.put(fake, effects=dataclasses.replace(fake.effects(), now=lambda: clock[0]))
|
||||
self.assertEqual(answer, "Use B.")
|
||||
self.assertEqual(len(fake.made("stream_claude")), compactions)
|
||||
self.assertEqual(said.count("compact"), 2 * compactions, said)
|
||||
|
||||
def test_a_compaction_doesnt_wait_for_memory(self):
|
||||
self.worked(minutes_ago=10)
|
||||
fake = FakeEffects(streams=[Streamed(0)], free_memory=[memory.Memory(available=3, total=16)])
|
||||
fake.scripts["input"] = [self.fired(fake, "Use B.")]
|
||||
said = self.put(fake)[1]
|
||||
self.assertEqual([seam for seam, _ in fake.calls if seam in ("memory", "sleep", "stream_claude")], ["stream_claude"])
|
||||
self.assertNotIn("waiting to start the worker", said)
|
||||
|
||||
def test_an_answer_before_the_timer_fires_stops_it_and_doesnt_compact_anything(self):
|
||||
self.worked(minutes_ago=10)
|
||||
fake = FakeEffects(inputs=["Use B."])
|
||||
self.assertEqual(self.put(fake)[0], "Use B.")
|
||||
self.assertEqual([call for call in fake.calls if call[0] in ("stop_timer", "stream_claude")], [("stop_timer", 40 * 60)])
|
||||
|
||||
def test_stops_the_timer_before_talk_opens_the_workers_session(self):
|
||||
self.worked(minutes_ago=10)
|
||||
fake = FakeEffects(inputs=["/talk"], on_terminal_claude=[self.typed_there])
|
||||
self.assertEqual(self.put(fake)[0], interrupt.Talked())
|
||||
self.assertEqual([call[0] for call in fake.calls if call[0] in ("stop_timer", "claude_on_terminal")], ["stop_timer", "claude_on_terminal"])
|
||||
|
||||
def test_starts_no_timer_under_60k_tokens_of_context_past_the_margin_on_a_five_minute_cache_or_where_claude_opens_at_once(self):
|
||||
for name, minutes_ago, written_1h, written_5m, read, answer_here in (("small", 10, 5000, 0, 54997, True), ("margin begun", 50, 5000, 0, 70000, True), ("five minutes", 1, 0, 5000, 70000, True), ("nothing written", 1, 0, 0, 70000, True), ("opens at once", 10, 5000, 0, 70000, False)):
|
||||
with self.subTest(name):
|
||||
self.transcript.write_text(json.dumps(human("a")) + "\n")
|
||||
self.worked(minutes_ago, written_1h, read, written_5m)
|
||||
fake = FakeEffects(inputs=["Use B."], on_terminal_claude=[self.typed_there])
|
||||
self.put(fake, answer_here=answer_here)
|
||||
self.assertEqual(fake.timers, [])
|
||||
|
||||
def test_starts_the_timer_at_60k_tokens_of_context(self):
|
||||
self.worked(minutes_ago=10, read=54998)
|
||||
fake = FakeEffects(inputs=["Use B."])
|
||||
self.put(fake)
|
||||
self.assertEqual([delay for delay, _ in fake.timers], [40 * 60])
|
||||
|
||||
def test_starts_no_timer_where_the_transcript_cannot_be_read_and_still_asks(self):
|
||||
self.transcript.unlink()
|
||||
fake = FakeEffects(inputs=["Use B."])
|
||||
self.assertEqual(self.put(fake)[0], "Use B.")
|
||||
self.assertEqual(fake.timers, [])
|
||||
|
||||
def test_a_compaction_that_hits_a_usage_limit_says_the_limits_message_and_keeps_waiting(self):
|
||||
self.worked(minutes_ago=10)
|
||||
fake = FakeEffects(streams=[Streamed(0, {"type": "result", "api_error_status": 429, "result": "You've hit your session limit"})])
|
||||
fake.scripts["input"] = [self.fired(fake, "Use B.")]
|
||||
answer, said = self.put(fake)
|
||||
self.assertEqual(answer, "Use B.")
|
||||
self.assertIn(f"\n{STAMP} could not compact the worker's claude session: You've hit your session limit\n", said)
|
||||
|
||||
def test_a_compaction_that_fails_says_why_and_keeps_waiting(self):
|
||||
self.worked(minutes_ago=10)
|
||||
fake = FakeEffects(streams=[Streamed(1)])
|
||||
fake.scripts["input"] = [self.fired(fake, "Use B.")]
|
||||
answer, said = self.put(fake)
|
||||
self.assertEqual(answer, "Use B.")
|
||||
self.assertIn(f"\n{STAMP} could not compact the worker's claude session: claude exited 1\n", said)
|
||||
|
||||
def test_stops_off_a_terminal_before_asking(self):
|
||||
fake = FakeEffects(on_terminal=False)
|
||||
self.assertEqual(self.put(fake), (Stop(2, "the human is needed to answer the question above, but stdin or stdout is not a terminal; rerun loop-claude on a terminal"), f"\n{STAMP} Which one?\n"))
|
||||
self.assertEqual(fake.calls, [])
|
||||
|
||||
def test_dms_the_question_naming_the_project_on_a_terminal_or_off_one(self):
|
||||
for on_terminal in (True, False):
|
||||
with self.subTest(on_terminal=on_terminal):
|
||||
fake = FakeEffects(inputs=["Use B."], on_terminal=on_terminal)
|
||||
self.put(fake)
|
||||
self.assertEqual(fake.dms, [f"loop-claude in {self.home} asks, in the tmux window loop-proj:item-7:\n\nWhich one?"])
|
||||
|
||||
def test_marks_its_window_and_rings_the_bell_while_it_waits_and_clears_the_mark_once_answered(self):
|
||||
fake = FakeEffects(inputs=["Use B."])
|
||||
answer, said = self.put(fake)
|
||||
self.assertEqual(answer, "Use B.")
|
||||
self.assertEqual(self.bells, 1)
|
||||
self.assertEqual(fake.tmux_calls, [["rename-window", "-t", "%4", "item-7 ?"], ["rename-window", "-t", "%4", "item-7"]])
|
||||
|
||||
def test_a_loop_that_stops_unanswered_leaves_its_window_marked(self):
|
||||
fake = FakeEffects(on_terminal=False)
|
||||
self.put(fake)
|
||||
self.assertEqual(fake.tmux_calls, [["rename-window", "-t", "%4", "item-7 ?"]])
|
||||
|
||||
def test_drops_the_keys_typed_before_the_question_ahead_of_the_dm_so_an_answer_typed_while_it_sends_counts(self):
|
||||
fake = FakeEffects(inputs=["Use B."])
|
||||
seen = []
|
||||
effects = dataclasses.replace(fake.effects(), dm=lambda text, directory: seen.append(list(fake.calls)))
|
||||
self.assertEqual(self.put(fake, effects=effects)[0], "Use B.")
|
||||
self.assertEqual(seen, [[("discard_typed", None)]])
|
||||
|
||||
def test_says_why_a_dm_failed_and_still_takes_the_answer(self):
|
||||
fake = FakeEffects(inputs=["Use B."], dm_failures=[Failure("cannot reach https://chat.example: timed out")])
|
||||
self.assertEqual(self.put(fake), ("Use B.", f"\n{STAMP} Which one?\n{STAMP} could not DM you: cannot reach https://chat.example: timed out\n"))
|
||||
|
||||
def test_returns_the_line_typed_after_the_question_stripped_dropping_what_was_typed_before(self):
|
||||
fake = FakeEffects(inputs=[" Use B. "])
|
||||
self.assertEqual(self.put(fake), ("Use B.", f"\n{STAMP} Which one?\n"))
|
||||
self.assertEqual(fake.calls, [("discard_typed", None), ("input", "Answer (/talk opens claude, Enter stops the loop): ")])
|
||||
|
||||
def test_talks_on_talk_or_at_once_where_the_answer_is_not_asked_for_here(self):
|
||||
for typed, answer_here in (([" /talk "], True), ([], False)):
|
||||
with self.subTest(typed=typed):
|
||||
fake = FakeEffects(inputs=typed, on_terminal_claude=[self.typed_there])
|
||||
self.assertEqual(self.put(fake, answer_here)[0], interrupt.Talked())
|
||||
self.assertEqual(len(fake.made("input")), len(typed))
|
||||
self.assertEqual(fake.calls[0], ("discard_typed", None))
|
||||
|
||||
def test_stops_on_an_empty_answer_or_the_inputs_end(self):
|
||||
for typed, why, said in ((" ", "nothing was typed", ""), (EOFError(), "the input ended", "\n")):
|
||||
with self.subTest(why=why):
|
||||
self.assertEqual(self.put(FakeEffects(inputs=[typed])), (Stop(2, f"the human is needed to answer the question above, but {why}"), f"\n{STAMP} Which one?\n{said}"))
|
||||
|
||||
def test_stops_when_nothing_was_typed_in_the_session(self):
|
||||
fake = FakeEffects(inputs=["/talk"], on_terminal_claude=[0])
|
||||
stop, _ = self.put(fake)
|
||||
self.assertEqual(fake.made("claude_on_terminal")[0][:4], ["--model", "m", "--effort", "high"])
|
||||
self.assertEqual(stop, Stop(2, "the human is needed to answer the question above, but the interrupt ended without anything typed"))
|
||||
|
||||
def test_hands_the_claude_that_takes_the_terminal_the_workers_environment(self):
|
||||
fake = FakeEffects(inputs=["/talk"], on_terminal_claude=[0])
|
||||
self.put(fake)
|
||||
self.assertEqual(fake.terminal_environments, [{"LOOP_CLAUDE_WORKER_RUNG": "m at high effort", "CLAUDE_CODE_SANDBOXED": "1"}])
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,225 @@
|
||||
import dataclasses
|
||||
import json
|
||||
import pathlib
|
||||
import sys
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from loop_effects.doubles import assistant, FakeEffects, human, judged, kinds
|
||||
from failure import Failure
|
||||
from agent_cycle.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished
|
||||
from agent_cycle import judge
|
||||
from agent_cycle.doubles import PROMPTS
|
||||
from model_routing.route import Route
|
||||
from model_routing.ladder import Rung
|
||||
from agent_cycle.judge import verdict_from
|
||||
|
||||
|
||||
class Grounded(unittest.TestCase):
|
||||
def test_every_verdict_must_quote_the_transcript(self):
|
||||
self.assertTrue(judge.grounded("Needs you: x", "so.\n\nNeeds you: x\n"))
|
||||
self.assertFalse(judge.grounded("invented", "the transcript"))
|
||||
self.assertFalse(judge.grounded("", "the transcript"))
|
||||
self.assertFalse(judge.grounded(" ", "the transcript"))
|
||||
transcript = "done.\n\n**Your step:**\n```\n./run.sh\n```\nRun it."
|
||||
self.assertTrue(judge.grounded("Your step:\n```\n./run.sh\n```\nRun it.", transcript))
|
||||
self.assertTrue(judge.grounded("Your step: ``` ./run.sh ``` Run it.", transcript))
|
||||
self.assertFalse(judge.grounded("**", transcript))
|
||||
|
||||
def test_an_elided_quote_holds_when_its_fragments_appear_in_order(self):
|
||||
transcript = "**Decision for you:** security, or not.\n\nI recommend one more round of each.\n\nI recommend skipping it: it costs."
|
||||
self.assertTrue(judge.grounded("**Decision for you:** security, … ... I recommend one more round of each ... I recommend skipping it: …", transcript))
|
||||
self.assertFalse(judge.grounded("I recommend skipping it ... Decision for you", transcript))
|
||||
self.assertFalse(judge.grounded("Decision for you ... invented", transcript))
|
||||
self.assertFalse(judge.grounded("... …", transcript))
|
||||
self.assertTrue(judge.grounded("a ... b ... c", "x a b a c"))
|
||||
|
||||
|
||||
class Verdict(unittest.TestCase):
|
||||
def test_needs_every_field_the_schema_requires(self):
|
||||
self.assertEqual(verdict_from({"escalation": "", "answer": "", "interrupt": False, "evidence": "e", "finished": True, "question": "", "answered_before": "", "left_open": "", "reversed": "", "release_ready": False}), Finished("e"))
|
||||
self.assertEqual(verdict_from({"escalation": "", "answer": "", "interrupt": False, "evidence": "e", "finished": False, "question": "ignored", "answered_before": "", "left_open": "", "reversed": "", "release_ready": False}), Unfinished("e"))
|
||||
self.assertEqual(verdict_from({"escalation": "", "answer": "", "interrupt": True, "evidence": "e", "finished": True, "question": "Which one?", "answered_before": "", "left_open": "", "reversed": "", "release_ready": False}), Interrupt("e", "Which one?"))
|
||||
self.assertEqual(verdict_from({"escalation": "", "answer": "", "interrupt": True, "evidence": "e", "finished": False, "question": "Cut 0.2.0?", "answered_before": "", "left_open": "", "reversed": "", "release_ready": True}), Interrupt("e", "Cut 0.2.0?", release_ready=True))
|
||||
self.assertEqual(verdict_from({"escalation": "", "answered_before": "", "left_open": "", "reversed": "", "answer": "", "interrupt": True, "evidence": "e", "finished": False, "question": "Cut 0.2.0?"}), Failure("the judge's reply has no release_ready of type boolean"))
|
||||
self.assertEqual(verdict_from({"escalation": "", "answer": "A.", "interrupt": False, "evidence": "e", "finished": False, "question": "Which one?", "answered_before": "", "left_open": "", "reversed": "", "release_ready": False}), QuotedAnswer("e", "Which one?", "A."))
|
||||
self.assertEqual(verdict_from({"escalation": "", "answer": "A.", "interrupt": True, "evidence": "e", "finished": False, "question": "Which one?", "answered_before": "", "left_open": "", "reversed": "", "release_ready": False}), Interrupt("e", "Which one?"))
|
||||
self.assertEqual(verdict_from({"escalation": "", "answer": "A.", "interrupt": False, "evidence": "e", "finished": True, "question": "", "answered_before": "", "left_open": "", "reversed": "", "release_ready": False}), Failure("the judge quoted an answer without a question"))
|
||||
self.assertEqual(verdict_from({"escalation": "", "answer": "", "interrupt": "no", "evidence": "", "finished": True, "question": "", "answered_before": "", "left_open": "", "reversed": "", "release_ready": False}), Failure("the judge's reply has no interrupt of type boolean"))
|
||||
self.assertEqual(verdict_from({"escalation": "", "answer": "", "interrupt": False, "evidence": None, "finished": True, "question": "", "answered_before": "", "left_open": "", "reversed": "", "release_ready": False}), Failure("the judge's reply has no evidence of type string"))
|
||||
self.assertEqual(verdict_from({"escalation": "", "answer": "", "interrupt": True, "evidence": "x", "finished": False, "question": " ", "answered_before": "", "left_open": "", "reversed": "", "release_ready": False}), Failure("the judge interrupted without a question"))
|
||||
self.assertEqual(verdict_from(None), Failure("the judge returned no reply"))
|
||||
|
||||
def test_carries_the_earlier_answer_an_interrupt_names(self):
|
||||
reply = {"answer": "", "escalation": "", "interrupt": True, "evidence": "e", "finished": False, "release_ready": False, "answered_before": "Grant one more round.", "left_open": "one more", "question": "Which one?", "reversed": ""}
|
||||
self.assertEqual(verdict_from(reply), Interrupt("e", "Which one?", answered_before="Grant one more round.", left_open="one more"))
|
||||
self.assertEqual(verdict_from({**reply, "interrupt": False, "finished": True}), Finished("e"))
|
||||
|
||||
def test_takes_an_escalation_quote_on_an_unfinished_verdict(self):
|
||||
reply = {"answer": "", "escalation": "round 2: 🔴", "interrupt": False, "evidence": "e", "finished": False, "question": "", "answered_before": "", "left_open": "", "reversed": "", "release_ready": False}
|
||||
self.assertEqual(verdict_from(reply), Unfinished("e", "round 2: 🔴"))
|
||||
self.assertEqual(verdict_from({**reply, "finished": True}), Finished("e"))
|
||||
self.assertEqual(verdict_from({**reply, "escalation": None}), Failure("the judge's reply has no escalation of type string"))
|
||||
|
||||
def test_takes_an_escalation_quote_on_an_interrupt(self):
|
||||
reply = {"answer": "", "escalation": "round 2: 🔴", "interrupt": True, "evidence": "e", "finished": False, "question": "Which one?", "answered_before": "", "left_open": "", "reversed": "", "release_ready": False}
|
||||
self.assertEqual(verdict_from(reply), Interrupt("e", "Which one?", "round 2: 🔴"))
|
||||
|
||||
def test_drops_an_escalation_quote_the_transcript_does_not_hold_word_for_word_from_an_interrupt_or_an_unfinished_verdict(self):
|
||||
shown = "The agent: round 2: 🔴. Which one?"
|
||||
self.assertEqual(judge.quotes_checked(Interrupt("e", "q", "round 2: 🔴"), judge.Grounds(shown, shown, "")), Interrupt("e", "q", "round 2: 🔴"))
|
||||
self.assertEqual(judge.quotes_checked(Interrupt("e", "q", "round 2: … 🔴"), judge.Grounds(shown, shown, "")), Interrupt("e", "q"))
|
||||
self.assertEqual(judge.quotes_checked(Unfinished("e", "round 3: 🔴"), judge.Grounds(shown, shown, "")), Unfinished("e"))
|
||||
|
||||
def test_turns_an_interrupt_that_re_asks_a_human_answer_into_that_answer_quoted_back(self):
|
||||
answer = "Grant one more round; ask again if a 🔴 survives it."
|
||||
shown = f"[loop] Asked.\n\n[human] {answer}\n\n[step] Round 2: a 🔴 survived."
|
||||
grounds = judge.Grounds(shown, shown, "")
|
||||
asking = "Grant a third round? Your answer left open: a 🔴 survives it"
|
||||
kept = Interrupt("[step] Round 2", asking, answered_before=answer, left_open="a 🔴 survives it")
|
||||
self.assertEqual(judge.quotes_checked(kept, grounds), kept)
|
||||
re_asked = Interrupt("[step] Round 2", "Grant a third round?", "Round 2: a 🔴", answered_before=answer, left_open="a 🔴 survives it")
|
||||
self.assertEqual(judge.quotes_checked(re_asked, grounds), Unfinished(answer, "Round 2: a 🔴"))
|
||||
self.assertEqual(judge.quotes_checked(dataclasses.replace(kept, left_open=""), grounds), Unfinished(answer))
|
||||
self.assertEqual(judge.quotes_checked(dataclasses.replace(kept, left_open="a 🔴 survived"), grounds), Unfinished(answer))
|
||||
invented = dataclasses.replace(re_asked, answered_before="Grant two more rounds.")
|
||||
self.assertEqual(judge.quotes_checked(invented, grounds), invented)
|
||||
unnamed = Interrupt("[step] Round 2", "Grant a third round?")
|
||||
self.assertEqual(judge.quotes_checked(unnamed, grounds), unnamed)
|
||||
|
||||
def test_takes_an_escalation_quote_on_a_quoted_answer(self):
|
||||
reply = {"answer": "A.", "escalation": "round 2: 🔴", "interrupt": False, "evidence": "e", "finished": False, "question": "Which one?", "answered_before": "", "left_open": "", "reversed": "", "release_ready": False}
|
||||
self.assertEqual(verdict_from(reply), QuotedAnswer("e", "Which one?", "A.", "round 2: 🔴"))
|
||||
|
||||
def test_drops_an_escalation_quote_the_transcript_does_not_hold_word_for_word_from_a_quoted_answer(self):
|
||||
shown = "The agent: round 2: 🔴. Which one?"
|
||||
self.assertEqual(judge.quotes_checked(QuotedAnswer("e", "q", "A.", "round 2: 🔴"), judge.Grounds(shown, shown, "A.")), QuotedAnswer("e", "q", "A.", "round 2: 🔴"))
|
||||
self.assertEqual(judge.quotes_checked(QuotedAnswer("e", "q", "A.", "round 2: … 🔴"), judge.Grounds(shown, shown, "A.")), QuotedAnswer("e", "q", "A."))
|
||||
|
||||
def test_puts_a_quoted_answer_the_records_do_not_hold_to_the_human_with_the_escalation_it_carried(self):
|
||||
self.assertEqual(judge.quotes_checked(QuotedAnswer("e", "q", "not there", "round 2: 🔴"), judge.Grounds("The agent: round 2: 🔴.", "The agent: round 2: 🔴.", "A.")), Interrupt("e", "q", "round 2: 🔴"))
|
||||
|
||||
def test_puts_a_quoted_answer_the_records_do_not_hold_word_for_word_to_the_human(self):
|
||||
self.assertEqual(judge.quotes_checked(QuotedAnswer("s", "q", "not there"), judge.Grounds("shown", "shown", "the records")), Interrupt("s", "q"))
|
||||
self.assertEqual(judge.quotes_checked(QuotedAnswer("s", "q", "the records"), judge.Grounds("shown", "shown", "From the records: the records")), QuotedAnswer("s", "q", "the records"))
|
||||
|
||||
def test_drops_an_escalation_quote_found_only_in_the_transcript_entries_before_the_workers_last_step_up(self):
|
||||
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), assistant({"type": "text", "text": "round 3: 🔴"}), assistant({"type": "text", "text": "working"})]
|
||||
def judged_on(mark, escalation):
|
||||
return judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", "the project's decisions", "the plan or a comment", kinds(*entries), mark, "loop-claude"), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", escalation=escalation)]).effects())
|
||||
self.assertEqual(judged_on(0, "round 2: 🔴"), Unfinished("working", "round 2: 🔴", entries_read=3))
|
||||
self.assertEqual(judged_on(1, "round 2: 🔴"), Unfinished("working", entries_read=3))
|
||||
self.assertEqual(judged_on(1, "round 3: 🔴"), Unfinished("working", "round 3: 🔴", entries_read=3))
|
||||
self.assertEqual(judged_on(1, "round 2: 🔴\n\nround 3: 🔴"), Unfinished("working", entries_read=3))
|
||||
self.assertEqual(judged_on(3, "round 3: 🔴"), Unfinished("working", entries_read=3))
|
||||
|
||||
def test_drops_an_escalation_quote_that_only_loop_claudes_prompts_or_the_humans_lines_repeat_after_the_step_up(self):
|
||||
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), {**human("as the work remaining: round 2: 🔴"), "promptSource": "sdk"}, human("round 2: 🔴 again"), assistant({"type": "text", "text": "working"})]
|
||||
verdict = judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", "the project's decisions", "the plan or a comment", kinds(*entries), 1, "loop-claude"), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", escalation="round 2: 🔴")]).effects())
|
||||
self.assertEqual(verdict, Unfinished("working", entries_read=4))
|
||||
|
||||
def test_takes_evidence_from_before_the_workers_last_step_up(self):
|
||||
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), assistant({"type": "text", "text": "working"})]
|
||||
verdict = judge.judge_once("/r", judge.Brief("Do it.", "## Goals", "", "the project's decisions", "the plan or a comment", kinds(*entries), 1, "loop-claude"), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", evidence="round 2: 🔴")]).effects())
|
||||
self.assertEqual(verdict, Unfinished("round 2: 🔴", entries_read=2))
|
||||
|
||||
def test_takes_the_task_as_evidence_where_the_tail_it_shows_cuts_off_the_workers_first_prompt_but_no_quote_across_the_join(self):
|
||||
entries = [human("Do the next chunk. " + "x" * judge.JUDGE_PROMPT_CHARS), assistant({"type": "text", "text": "Merged."})]
|
||||
def judged_on(evidence):
|
||||
return judge.judge_once("/r", judge.Brief("Do the next chunk.", "## Goals", "", "the project's decisions", "the plan or a comment", kinds(*entries), 0, "loop-claude"), Rung("judge-model"), FakeEffects(claude=[judged("unfinished", evidence=evidence)] * 3).effects())
|
||||
self.assertEqual(judged_on("Do the next chunk."), Unfinished("Do the next chunk.", entries_read=2))
|
||||
self.assertEqual(judged_on("Do the next chunk. ... Merged."), Unfinished("Do the next chunk. ... Merged.", entries_read=2))
|
||||
self.assertIsInstance(judged_on("Do the next release."), Failure)
|
||||
self.assertIsInstance(judged_on("next chunk. xxx"), Failure)
|
||||
|
||||
|
||||
class JudgePrompt(unittest.TestCase):
|
||||
def brief(self, entries, escalated_at, answer_destinations="the plan or a comment", records=""):
|
||||
"""What the judge of a-driver reads of a transcript holding entries."""
|
||||
return judge.Brief("Do it.", "## Goals", records, "the project's decisions", answer_destinations, kinds(*entries), escalated_at, "a-driver")
|
||||
|
||||
def test_runs_with_no_tools_and_loads_no_mcp_server(self):
|
||||
args = judge.judge_args(Rung("claude-opus-5-5", "medium"), "a-driver")
|
||||
self.assertEqual(args[args.index("--tools") + 1 :], ["", "--strict-mcp-config"])
|
||||
self.assertNotIn("--mcp-config", args)
|
||||
|
||||
def test_shows_the_transcripts_tail_and_returns_what_it_showed(self):
|
||||
entries = [assistant({"type": "text", "text": "old " + "x" * judge.JUDGE_PROMPT_CHARS}), assistant({"type": "text", "text": "new"})]
|
||||
prompt, grounds = judge.judge_prompt(self.brief(entries, 0))
|
||||
self.assertTrue(grounds.shown.endswith("\n\nnew"))
|
||||
self.assertNotIn("old", grounds.shown)
|
||||
self.assertIn(grounds.shown, prompt)
|
||||
self.assertLessEqual(len(prompt), judge.JUDGE_PROMPT_CHARS)
|
||||
self.assertEqual(grounds.after_mark, "old " + "x" * judge.JUDGE_PROMPT_CHARS + "\n\nnew")
|
||||
self.assertEqual(grounds.quotable, "## Goals\n\n")
|
||||
|
||||
# A transcript longer than the floor: an old message, then the last one.
|
||||
LONG = [assistant({"type": "text", "text": "old " + "x" * judge.TRANSCRIPT_FLOOR}), assistant({"type": "text", "text": "Merged."})]
|
||||
|
||||
def overhead(self):
|
||||
"""The characters of the judge's prompt that are neither the records nor the transcript."""
|
||||
prompt, grounds = judge.judge_prompt(self.brief(self.LONG, 0, records="r"))
|
||||
return len(prompt) - len(grounds.shown) - 1
|
||||
|
||||
def test_fails_naming_the_shortfall_where_the_records_leave_less_than_the_transcripts_floor(self):
|
||||
failed = judge.judge_prompt(self.brief(self.LONG, 0, records="r" * (judge.JUDGE_PROMPT_CHARS + 1)))
|
||||
self.assertIsInstance(failed, Failure)
|
||||
for fact in ("leave 0 of the judge's 400,000", "400,001", f"{judge.TRANSCRIPT_FLOOR:,}", f"by at least {judge.TRANSCRIPT_FLOOR + self.overhead() + 1:,}"):
|
||||
with self.subTest(fact=fact):
|
||||
self.assertIn(fact, failed.reason)
|
||||
|
||||
def test_judge_once_returns_that_failure_without_starting_claude(self):
|
||||
failed = judge.judge_once("/r", self.brief(self.LONG, 0, records="r" * judge.JUDGE_PROMPT_CHARS), Rung("judge-model"), FakeEffects(claude=[]).effects())
|
||||
self.assertIsInstance(failed, Failure)
|
||||
self.assertIn(f"{judge.TRANSCRIPT_FLOOR:,}", failed.reason)
|
||||
|
||||
def test_shows_the_whole_of_a_transcript_longer_than_the_floor_where_the_records_leave_room_for_it(self):
|
||||
whole = "old " + "x" * judge.TRANSCRIPT_FLOOR + "\n\nMerged."
|
||||
prompt, grounds = judge.judge_prompt(self.brief(self.LONG, 0, records="r" * (judge.JUDGE_PROMPT_CHARS - self.overhead() - len(whole))))
|
||||
self.assertEqual(grounds.shown, whole)
|
||||
self.assertLessEqual(len(prompt), judge.JUDGE_PROMPT_CHARS)
|
||||
|
||||
def test_shows_the_floor_where_the_records_leave_exactly_that(self):
|
||||
at_floor = judge.JUDGE_PROMPT_CHARS - self.overhead() - judge.TRANSCRIPT_FLOOR
|
||||
self.assertEqual(len(judge.judge_prompt(self.brief(self.LONG, 0, records="r" * at_floor))[1].shown), judge.TRANSCRIPT_FLOOR)
|
||||
self.assertIsInstance(judge.judge_prompt(self.brief(self.LONG, 0, records="r" * (at_floor + 1))), Failure)
|
||||
|
||||
def test_shows_a_transcript_shorter_than_the_floor_whole(self):
|
||||
_, grounds = judge.judge_prompt(self.brief([assistant({"type": "text", "text": "Merged."})], 0, records="r" * (judge.JUDGE_PROMPT_CHARS - 10000)))
|
||||
self.assertEqual(grounds.shown, "Merged.")
|
||||
|
||||
def test_the_judge_prompt_and_schema_call_the_worker_the_worker(self):
|
||||
prompt, _ = judge.judge_prompt(self.brief([assistant({"type": "text", "text": "done"})], 1))
|
||||
self.assertNotRegex(prompt + json.dumps(judge.judge_schema("a-driver")), r"\b[Aa]gent")
|
||||
|
||||
def test_the_judge_prompt_names_the_entry_points_answer_destinations_in_both_rules_on_a_recorded_answer(self):
|
||||
prompt, _ = judge.judge_prompt(self.brief([assistant({"type": "text", "text": "done"})], 0, "the ledger"))
|
||||
self.assertIn("is recorded in the ledger at the one place it governs", prompt)
|
||||
self.assertIn("the worker writing it into the ledger, but not into one of the human's rules", prompt)
|
||||
|
||||
def test_shows_the_judge_where_the_worker_last_stepped_up_and_checks_an_escalation_only_after_it(self):
|
||||
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), assistant({"type": "text", "text": "round 3: 🔴"})]
|
||||
prompt, grounds = judge.judge_prompt(self.brief(entries, 1))
|
||||
self.assertRegex(prompt, "round 2: 🔴\n\n\\[step\\] [^\n]+\n\nround 3: 🔴\n\n")
|
||||
self.assertEqual(grounds.after_mark, "round 3: 🔴")
|
||||
prompt, grounds = judge.judge_prompt(self.brief(entries, 0))
|
||||
self.assertNotIn("stepped the worker up", prompt)
|
||||
self.assertEqual(grounds.shown, "round 2: 🔴\n\nround 3: 🔴")
|
||||
self.assertEqual(grounds.after_mark, "round 2: 🔴\n\nround 3: 🔴")
|
||||
|
||||
def test_drops_an_escalation_quote_from_after_the_step_up_that_the_tail_it_shows_cuts_off(self):
|
||||
entries = [assistant({"type": "text", "text": "round 2: 🔴"}), assistant({"type": "text", "text": "old " + "x" * judge.JUDGE_PROMPT_CHARS}), assistant({"type": "text", "text": "new"})]
|
||||
_, grounds = judge.judge_prompt(self.brief(entries, 1))
|
||||
self.assertEqual(judge.quotes_checked(Unfinished("e", "old x", entries_read=3), grounds), Unfinished("e", entries_read=3))
|
||||
self.assertEqual(judge.quotes_checked(Unfinished("e", "new", entries_read=3), grounds), Unfinished("e", "new", entries_read=3))
|
||||
|
||||
def test_shows_a_typed_answer_before_the_step_up_as_the_humans(self):
|
||||
typed = PROMPTS.typed("Which one?", "Use B.", Route(Rung("worker-model")), None, False)
|
||||
entries = [{**human(typed), "promptSource": "sdk"}, assistant({"type": "text", "text": "round 3: 🔴"})]
|
||||
_, grounds = judge.judge_prompt(self.brief(entries, 1))
|
||||
self.assertIn("\n\n[human] Use B.\n\n[step] ", grounds.shown)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,15 @@
|
||||
import pathlib
|
||||
import sys
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from agent_cycle import quotes
|
||||
|
||||
|
||||
class Verbatim(unittest.TestCase):
|
||||
def test_a_quote_holds_only_word_for_word_less_emphasis_and_whitespace(self):
|
||||
self.assertTrue(quotes.verbatim("Merge **ff-only**.", "Merge ff-only.\nNever squash."))
|
||||
self.assertTrue(quotes.verbatim("Merge _ff-only_.", "Merge ff-only.\nNever squash."))
|
||||
self.assertFalse(quotes.verbatim("Merge ... squash.", "Merge ff-only.\nNever squash."))
|
||||
self.assertFalse(quotes.verbatim("", "Merge ff-only."))
|
||||
@@ -0,0 +1,50 @@
|
||||
import contextlib
|
||||
import io
|
||||
import pathlib
|
||||
import sys
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from failure import Failure
|
||||
from loop_effects.doubles import FakeEffects, NOW, STAMP
|
||||
from claude_code.reply import Limited
|
||||
from agent_cycle import retry
|
||||
from agent_cycle.stop import Stop
|
||||
|
||||
|
||||
class Retried(unittest.TestCase):
|
||||
def test_retries_a_minute_apart_and_stops_on_the_third_failure(self):
|
||||
fake = FakeEffects()
|
||||
results = [Failure("one"), "done"]
|
||||
self.assertEqual(retry.retried("worker", lambda: results.pop(0), fake.effects()), "done")
|
||||
self.assertEqual(fake.calls, [("sleep", 60)])
|
||||
fake = FakeEffects()
|
||||
self.assertEqual(retry.retried("judge", lambda: Failure("no"), fake.effects()), Stop(1, "the judge failed three times running: no"))
|
||||
self.assertEqual(fake.calls, [("sleep", 60), ("sleep", 60)])
|
||||
|
||||
def test_hands_each_failure_to_the_keeper_and_stops_where_it_stops(self):
|
||||
kept = []
|
||||
def keep(failure):
|
||||
kept.append(failure)
|
||||
return Stop(1, "no room") if len(kept) == 2 else None
|
||||
fake = FakeEffects()
|
||||
self.assertEqual(retry.retried("judge", lambda: Failure("no"), fake.effects(), keep), Stop(1, "no room"))
|
||||
self.assertEqual(kept, [Failure("no")] * 2)
|
||||
self.assertEqual(fake.calls, [("sleep", 60)])
|
||||
|
||||
def test_waits_out_a_usage_limit_which_ends_a_run_of_failures(self):
|
||||
fake = FakeEffects()
|
||||
results = [Failure("one"), Failure("two"), Limited(NOW + 3600, "limit"), Failure("three"), Limited(None, "limit"), Limited(NOW - 600, "limit"), Failure("four"), Failure("five"), Failure("six")]
|
||||
self.assertEqual(retry.retried("worker", lambda: results.pop(0), fake.effects()), Stop(1, "the worker failed three times running: six"))
|
||||
self.assertEqual(fake.calls, [("sleep", 60), ("sleep", 60), ("sleep", 3720), ("sleep", 60), ("sleep", 600), ("sleep", 600), ("sleep", 60), ("sleep", 60)])
|
||||
|
||||
def test_says_what_claude_said_and_when_the_next_try_is_due(self):
|
||||
results = [Limited(NOW + 3600, "You've hit your session limit"), "done"]
|
||||
with contextlib.redirect_stderr(io.StringIO()) as said:
|
||||
retry.retried("judge", lambda: results.pop(0), FakeEffects().effects())
|
||||
self.assertEqual(said.getvalue(), f"{STAMP} the judge hit a usage limit (You've hit your session limit); retrying at <{NOW + 3720}>\n")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,109 @@
|
||||
import dataclasses
|
||||
import pathlib
|
||||
import sys
|
||||
import types
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from agent_cycle.verdicts import Interrupt, TakenIn, Unfinished
|
||||
from model_routing.ladder import ProjectRung, Rung
|
||||
from model_routing.ladder_file import read_ladder, SHIPPED
|
||||
from model_routing.route import Route
|
||||
from agent_cycle import routing
|
||||
|
||||
LADDER = read_ladder(SHIPPED)
|
||||
OPUS_PROJECT = ProjectRung(LADDER, Rung("claude-opus-5-5", "medium"))
|
||||
# The ladder's rungs around the project's: the one below it, its own, and those one to four steps up.
|
||||
SONNET = Rung("claude-sonnet-5-5", "high")
|
||||
OPUS = Rung("claude-opus-5-5", "medium")
|
||||
ONE_UP = Rung("claude-fable-5-2", "low")
|
||||
TWO_UP = Rung("claude-fable-5-2", "medium")
|
||||
THREE_UP = Rung("claude-opus-5-5", "xhigh")
|
||||
FOUR_UP = Rung("claude-fable-5-2", "high")
|
||||
|
||||
|
||||
def scored(likelihood, escape_and_impact):
|
||||
"""Item 3 with that L and E + I, as routing.Scored reads an item."""
|
||||
return types.SimpleNamespace(id=3, likelihood=likelihood, escape_and_impact=escape_and_impact)
|
||||
|
||||
|
||||
def unfinished(likelihood=0, escalated_at=None):
|
||||
"""An unfinished verdict: the worker took in an item of that L, 0 for none, and the judge found an escalation after reading escalated_at transcript entries, None for none."""
|
||||
return Unfinished("e", escalation="round 2: 🔴" if escalated_at is not None else "", taken_in=TakenIn(highest_likelihood=likelihood), entries_read=escalated_at)
|
||||
|
||||
|
||||
def interrupted(likelihood=0, escalated_at=None):
|
||||
"""An interrupt, its arguments as unfinished's."""
|
||||
return Interrupt("e", "q", escalation="round 2: 🔴" if escalated_at is not None else "", taken_in=TakenIn(highest_likelihood=likelihood), entries_read=escalated_at)
|
||||
|
||||
|
||||
class FirstRoute(unittest.TestCase):
|
||||
def test_starts_a_chunk_on_the_rung_its_items_l_picks_below_the_projects_too(self):
|
||||
self.assertEqual(routing.first_route(OPUS_PROJECT, scored(4, 5)), Route(TWO_UP, 3, 4, 5))
|
||||
self.assertEqual(routing.first_route(OPUS_PROJECT, scored(1, 5)), Route(SONNET, 3, 1, 5))
|
||||
self.assertEqual(routing.first_route(OPUS_PROJECT, None), Route(OPUS))
|
||||
|
||||
|
||||
class NextRoute(unittest.TestCase):
|
||||
def test_steps_up_a_rung_after_every_second_unfinished_verdict(self):
|
||||
once = routing.next_route(OPUS_PROJECT, Route(ONE_UP, 3, 3, 4), unfinished())
|
||||
self.assertEqual(once, Route(ONE_UP, 3, 3, 4, unfinished=1))
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, once, unfinished()), Route(TWO_UP, 3, 3, 4))
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(LADDER.rungs[-1], unfinished=1), unfinished()).rung, LADDER.rungs[-1])
|
||||
|
||||
def test_steps_up_to_the_rung_a_taken_in_items_l_picks_and_never_down(self):
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(OPUS), unfinished(4)).rung, TWO_UP)
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(THREE_UP), unfinished(4)).rung, THREE_UP)
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(OPUS, unfinished=1), unfinished(4)).rung, THREE_UP)
|
||||
|
||||
def test_steps_up_from_a_rung_below_the_projects_one_rung_at_a_time(self):
|
||||
low = Route(SONNET, 3, 1, 3, unfinished=1)
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, low, unfinished()).rung, OPUS)
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(low.rung, 3, 1, 3), unfinished()).rung, low.rung)
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(low.rung, 3, 1, 3), unfinished(3)).rung, ONE_UP)
|
||||
|
||||
def test_steps_up_a_rung_on_an_escalation_the_judge_found_up_to_two_above_the_items_rung_marking_the_transcript_entries_it_read(self):
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(TWO_UP, 3, 4, 5), unfinished(escalated_at=7)), Route(THREE_UP, 3, 4, 5, escalated_at=7))
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(THREE_UP, 3, 4, 5, escalated_at=7), unfinished(escalated_at=9)), Route(FOUR_UP, 3, 4, 5, escalated_at=9))
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(FOUR_UP, 3, 4, 5, escalated_at=9), unfinished(escalated_at=12)), Route(FOUR_UP, 3, 4, 5, unfinished=1, escalated_at=9))
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(TWO_UP, 3, 4, 5, unfinished=1), unfinished(escalated_at=7)), Route(THREE_UP, 3, 4, 5, escalated_at=7))
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(TWO_UP), unfinished(escalated_at=7)), Route(TWO_UP, unfinished=1))
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(SONNET, 3, 2, 4), unfinished(4, escalated_at=7)), Route(TWO_UP, 3, 2, 4, unfinished=1))
|
||||
|
||||
def test_keeps_the_mark_through_a_step_no_escalation_took(self):
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(ONE_UP, 3, 3, 4, unfinished=1, escalated_at=5), unfinished()), Route(TWO_UP, 3, 3, 4, escalated_at=5))
|
||||
|
||||
def test_steps_up_a_rung_as_the_judge_interrupts_up_to_two_above_the_items_rung_without_counting_an_unfinished_verdict(self):
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(TWO_UP, 3, 4, 5, unfinished=1), interrupted(escalated_at=7)), Route(THREE_UP, 3, 4, 5, escalated_at=7))
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(THREE_UP, 3, 4, 5, escalated_at=7), interrupted(escalated_at=9)), Route(FOUR_UP, 3, 4, 5, escalated_at=9))
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(FOUR_UP, 3, 4, 5, unfinished=1, escalated_at=9), interrupted(escalated_at=12)), Route(FOUR_UP, 3, 4, 5, unfinished=1, escalated_at=9))
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(SONNET, 3, 2, 4), interrupted(escalated_at=7)), Route(OPUS, 3, 2, 4, escalated_at=7))
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(TWO_UP, 3, 4, 5, unfinished=1, escalated_at=2), interrupted(4)), Route(TWO_UP, 3, 4, 5, unfinished=1, escalated_at=2))
|
||||
|
||||
def test_raises_the_worker_to_a_taken_in_items_rung_above_the_escalation_cap_without_a_step_as_the_judge_interrupts(self):
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(OPUS, 3, 1, 3, escalated_at=2), interrupted(4, escalated_at=7)), Route(TWO_UP, 3, 1, 3, escalated_at=2))
|
||||
|
||||
def test_steps_up_from_the_rung_a_taken_in_item_picks_as_the_judge_interrupts(self):
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(ONE_UP, 3, 3, 4), interrupted(4, escalated_at=7)), Route(THREE_UP, 3, 3, 4, escalated_at=7))
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(TWO_UP, 3, 4, 5), interrupted(4, escalated_at=7)), Route(THREE_UP, 3, 4, 5, escalated_at=7))
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(FOUR_UP, 3, 4, 5, unfinished=1), interrupted(4, escalated_at=7)), Route(FOUR_UP, 3, 4, 5, unfinished=1))
|
||||
|
||||
def test_a_rung_an_edit_took_off_the_ladder_counts_as_the_projects(self):
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(Rung("claude-opus-5-5", "low")), unfinished()).rung, OPUS)
|
||||
self.assertEqual(routing.next_route(OPUS_PROJECT, Route(Rung("claude-opus-5-5", "low")), unfinished(2)).rung, OPUS)
|
||||
|
||||
|
||||
class StepUp(unittest.TestCase):
|
||||
def test_names_no_step_up_where_only_the_count_of_unfinished_verdicts_changed(self):
|
||||
route = Route(OPUS, 3, 3, 4)
|
||||
self.assertIsNone(routing.step_up(route, dataclasses.replace(route, unfinished=1)))
|
||||
self.assertEqual(routing.step_up(route, route.taking_in(6)), routing.StepUp(route, route.taking_in(6)))
|
||||
|
||||
|
||||
class JudgeRung(unittest.TestCase):
|
||||
def test_runs_the_judge_of_a_replayed_model_on_its_models_highest_rung(self):
|
||||
self.assertEqual(routing.judge_rung(LADDER, "claude-opus-5-5"), THREE_UP)
|
||||
# A model off the ladder, or not replayed, gets no effort flag.
|
||||
self.assertEqual(routing.judge_rung(LADDER, "judge-model"), Rung("judge-model"))
|
||||
self.assertEqual(routing.judge_rung(LADDER, "claude-sonnet-5-5"), Rung("claude-sonnet-5-5"))
|
||||
@@ -0,0 +1,518 @@
|
||||
import contextlib
|
||||
import dataclasses
|
||||
import io
|
||||
import json
|
||||
import os
|
||||
import pathlib
|
||||
import re
|
||||
import shutil
|
||||
import stat
|
||||
import sys
|
||||
import tempfile
|
||||
import types
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from test_env import assert_not_root
|
||||
from failure import Failure
|
||||
from loop_effects.doubles import FakeEffects, human, judged, NOW, ran, STAMP, Streamed, Worker
|
||||
from agent_cycle.verdicts import Finished, Interrupt, Judged, QuotedAnswer, TakenIn, Unfinished
|
||||
from transcript_archive import outcomes, write
|
||||
from loop_state import paths
|
||||
from transcript_archive.location import project_archive
|
||||
from model_routing.ladder import ProjectRung, Rung
|
||||
from agent_cycle.doubles import PROMPTS, WINDOW
|
||||
from model_routing.ladder_file import read_ladder, SHIPPED
|
||||
from text_files.file_writes import replace_file
|
||||
from model_routing.route import Route
|
||||
from agent_cycle import routing
|
||||
from agent_cycle import run, stuck_workers, worker_prompts
|
||||
from claude_code import session
|
||||
from loop_effects.child_shells import Shell
|
||||
from agent_cycle.stop import Stop
|
||||
from text_files.utc_stamp import utc
|
||||
|
||||
|
||||
LADDER = read_ladder(SHIPPED)
|
||||
OPUS_PROJECT = ProjectRung(LADDER, Rung("claude-opus-5-5", "medium"))
|
||||
# The ladder's rungs the cycles run on, and those one and three steps up from OPUS.
|
||||
SONNET = Rung("claude-sonnet-5-5", "high")
|
||||
OPUS = Rung("claude-opus-5-5", "medium")
|
||||
ONE_UP = Rung("claude-fable-5-2", "low")
|
||||
THREE_UP = Rung("claude-opus-5-5", "xhigh")
|
||||
# How the archive records a worker that runs off the ladder.
|
||||
OFF_LADDER = '{"model": "worker-model"}'
|
||||
# The claude-config release and commit each cycle the tests run is under.
|
||||
CONFIG = "v0.8.0 (abc123)"
|
||||
# How it records routes by item 179's L of 2 and E + I of 5.
|
||||
SONNET_179 = '{"model": "claude-sonnet-5-5", "effort": "high", "item": 179, "likelihood": 2, "escape_and_impact": 5}'
|
||||
OPUS_179_AT_3 = '{"model": "claude-opus-5-5", "effort": "medium", "item": 179, "likelihood": 2, "escape_and_impact": 5, "escalated_at": 3}'
|
||||
OPUS_179_AT_6 = '{"model": "claude-opus-5-5", "effort": "medium", "item": 179, "likelihood": 2, "escape_and_impact": 5, "escalated_at": 6}'
|
||||
JUDGE_RUN_LINE = re.compile(r"^Judge run: judge/[0-9a-f]{64}\.json\n", re.MULTILINE)
|
||||
|
||||
|
||||
class QuestionFor(unittest.TestCase):
|
||||
def test_puts_an_interrupts_question_as_asked_and_a_quoted_answer_past_the_cap_with_its_quote(self):
|
||||
cycle = types.SimpleNamespace(prompts=PROMPTS)
|
||||
self.assertEqual(run.question_for(cycle, Interrupt("e", "Which one?")), "Which one?")
|
||||
self.assertEqual(run.question_for(cycle, QuotedAnswer("e", "Which one?", "A.")), "Which one?\n\nthe project's records says:\nA.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.")
|
||||
|
||||
|
||||
class Cycles(unittest.TestCase):
|
||||
def setUp(self):
|
||||
temp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(temp.cleanup)
|
||||
self.home = pathlib.Path(temp.name)
|
||||
self.paths = paths.paths_from(self.home)
|
||||
self.session = session.session_named("A proj a-driver", self.paths.claude_code_transcripts)
|
||||
self.archive = project_archive(str(self.home / "code" / "proj"), self.home, {})
|
||||
|
||||
def cycle(self, fake, records="", unfinished_evidence="", facts="- A preflight fact."):
|
||||
return run.Cycle(config=CONFIG, window=WINDOW, effects=fake.effects(), facts=facts, judge=Rung("judge-model"), premises="## Goals", project=None, project_archive=self.archive, records=records, root=str(self.home), route=Route(Rung("worker-model")), session=self.session, task="Do it.", prompts=PROMPTS, taken_in=lambda entries: TakenIn(), unfinished_evidence=unfinished_evidence)
|
||||
|
||||
def archived_outcomes(self):
|
||||
"""Each outcomes file's text without its `Judge run:` lines, which name a file by the hash of a prompt and its reply: the tests of the judge's runs check them."""
|
||||
return sorted(JUDGE_RUN_LINE.sub("", path.read_text()) for path in self.archive.glob("*/*.outcomes.md"))
|
||||
|
||||
def test_a_finished_chunk_is_archived_and_its_session_deleted(self):
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("finished")])
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake)).verdict, Finished("working"))
|
||||
self.assertEqual(self.archived_outcomes(), [f"Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: finished\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n"])
|
||||
|
||||
def test_says_where_it_archived_the_transcript(self):
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("finished")])
|
||||
with contextlib.redirect_stderr(io.StringIO()) as said:
|
||||
run.run_cycle(self.cycle(fake))
|
||||
copy, = self.archive.glob("*/*.jsonl")
|
||||
self.assertIn(f"transcript: {copy}\n", said.getvalue())
|
||||
|
||||
def test_archives_the_cost_the_judges_reply_records_beside_its_verdict(self):
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("finished", cost=0.25)])
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake)).verdict, Finished("working", judged=Judged(cost=0.25)))
|
||||
self.assertEqual(self.archived_outcomes(), [f"Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: finished\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nJudge cost: 0.2500\nWorker: {OFF_LADDER}\n"])
|
||||
self.assertIsNone(session.transcript_file(self.session))
|
||||
|
||||
def test_archives_what_the_worker_and_the_judge_spent_beside_the_verdict(self):
|
||||
worker = Worker(self.paths.claude_code_transcripts.parent, usage={"input_tokens": 1, "cache_creation": {"ephemeral_5m_input_tokens": 2, "ephemeral_1h_input_tokens": 3}, "cache_read_input_tokens": 4, "output_tokens": 5})
|
||||
answer = json.loads(judged("finished").stdout)
|
||||
fake = FakeEffects(streams=[worker], claude=[ran(json.dumps({**answer, "usage": {"input_tokens": 6, "output_tokens": 7}}))])
|
||||
run.run_cycle(self.cycle(fake))
|
||||
self.assertEqual(self.archived_outcomes(), [f"""Task: Do it.
|
||||
|
||||
2026-09-21T14:13:20Z Verdict: finished
|
||||
|
||||
Evidence:
|
||||
> working
|
||||
|
||||
Spent since the chunk began, in tokens of input, cache write 5m, cache write 1h, cache read, output:
|
||||
- worker, claude-opus-5-5: 1, 2, 3, 4, 5
|
||||
- judge, judge-model: 6, 0, 0, 0, 7
|
||||
|
||||
List prices in dollars per million tokens of input, cache write 5m, cache write 1h, cache read, output:
|
||||
- claude-opus-5-5: 4, 5, 8, 0.2, 20
|
||||
|
||||
Config: {CONFIG}
|
||||
Judge: judge-model
|
||||
Worker: {OFF_LADDER}
|
||||
"""])
|
||||
|
||||
def test_a_fresh_worker_reads_the_preflights_facts_and_a_resumed_one_does_not(self):
|
||||
worker = Worker(self.paths.claude_code_transcripts.parent)
|
||||
fake = FakeEffects(streams=[worker, worker], claude=[judged("unfinished"), judged("finished")])
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake)).verdict, Unfinished("working", entries_read=3))
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake, unfinished_evidence="working")).verdict, Finished("working"))
|
||||
fresh, resumed = (args[args.index("-p") + 1] for args in fake.made("stream_claude"))
|
||||
self.assertIn("- A preflight fact.", fresh)
|
||||
self.assertNotIn("- A preflight fact.", resumed)
|
||||
|
||||
def test_a_worker_is_handed_the_projects_rung_its_own_its_reviews_e_plus_i_and_its_compaction_window_in_its_environment(self):
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("finished")])
|
||||
cycle = dataclasses.replace(self.cycle(fake), project=OPUS_PROJECT, route=Route(Rung("claude-haiku-5-5", "max"), 163, 1, 5))
|
||||
self.assertEqual(run.run_cycle(cycle).verdict, Finished("working"))
|
||||
self.assertEqual(fake.worker_environments, [{"LOOP_CLAUDE_PROJECT_RUNG": "claude-opus-5-5 at medium effort", "LOOP_CLAUDE_WORKER_RUNG": "claude-haiku-5-5 at max effort", "LOOP_CLAUDE_ESCAPE_AND_IMPACT": "5", "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "200000", "BASH_MAX_OUTPUT_LENGTH": "6000"}])
|
||||
|
||||
def test_a_stuck_check_of_the_worker_runs_on_the_projects_rung_and_off_the_ladder_on_the_workers_own(self):
|
||||
for project, model in ((OPUS_PROJECT, "claude-opus-5-5"), (None, "claude-haiku-5-5")):
|
||||
with self.subTest(project=project):
|
||||
clock = [NOW]
|
||||
quiet = Shell(pid=7, started=NOW, command="bin/run-tests", written=NOW, runs_busy_tool=False)
|
||||
events = ({"type": "assistant", "message": {"content": []}}, None, None, {"type": "result"})
|
||||
stream = lambda args: (Worker(self.paths.claude_code_transcripts.parent)(args), Streamed(0, *events, clock=clock, held=[quiet]))[1]
|
||||
verdict = ran(json.dumps({"type": "result", "structured_output": {"verdict": "stuck", "process": 7, "why": "it waits"}}))
|
||||
fake = FakeEffects(streams=[stream], claude=[verdict, judged("finished")])
|
||||
cycle = dataclasses.replace(self.cycle(fake), project=project, route=Route(Rung("claude-haiku-5-5", "max")))
|
||||
with contextlib.redirect_stdout(io.StringIO()):
|
||||
run.run_cycle(dataclasses.replace(cycle, effects=dataclasses.replace(cycle.effects, now=lambda: clock[0])))
|
||||
[investigator, _] = [args for args, _ in fake.made("claude")]
|
||||
self.assertEqual(investigator[investigator.index("--model") + 1], model)
|
||||
self.assertEqual(fake.worker_folders, [str(self.home)])
|
||||
self.assertIn("judged the worker stuck", (self.archive / stuck_workers.RECORD).read_text())
|
||||
|
||||
def test_the_claude_an_interrupt_resumes_is_handed_the_same_rungs_as_the_worker(self):
|
||||
def answer(args):
|
||||
with open(session.transcript_file(self.session), "a") as handle:
|
||||
handle.write(json.dumps(human("the second")) + "\n")
|
||||
return 0
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("interrupt"), judged("finished")], inputs=["/talk"], on_terminal_claude=[answer])
|
||||
cycle = dataclasses.replace(self.cycle(fake), project=OPUS_PROJECT, route=Route(Rung("claude-haiku-5-5", "max"), 163, 1, 5))
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
self.assertEqual(run.run_cycle(cycle).verdict, Finished("working"))
|
||||
self.assertEqual(fake.terminal_environments, [{**environment, "CLAUDE_CODE_SANDBOXED": "1"} for environment in fake.worker_environments])
|
||||
self.assertEqual(fake.terminal_environments[0]["LOOP_CLAUDE_WORKER_RUNG"], "claude-haiku-5-5 at max effort")
|
||||
|
||||
def test_an_unfinished_chunks_transcript_is_archived_and_the_next_cycle_resumes_its_session_with_the_judges_evidence(self):
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)] * 2, claude=[judged("unfinished")] * 2)
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake)).verdict, Unfinished("working", entries_read=3))
|
||||
self.assertTrue(session.transcript_file(self.session))
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake, unfinished_evidence="working")).verdict, Unfinished("working", entries_read=4))
|
||||
workers = fake.made("stream_claude")
|
||||
self.assertIn("--session-id", workers[0])
|
||||
self.assertIn("--resume", workers[1])
|
||||
self.assertEqual(workers[1][workers[1].index("-p") + 1], "Resumed: working")
|
||||
self.assertEqual(self.archived_outcomes(), [f"Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: unfinished\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n"] * 2)
|
||||
|
||||
def test_a_cycle_stopped_by_a_failure_or_ctrl_c_archives_what_its_session_holds(self):
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[ran(code=1)] * 3)
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake)).code, 1)
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[KeyboardInterrupt()])
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake)), Stop(130, ""))
|
||||
self.assertEqual(self.archived_outcomes(), [f"Task: Do it.\n\n2026-09-21T14:13:20Z Stopped: Ctrl-C\n\nWorker: {OFF_LADDER}\n", f"Task: Do it.\n\n2026-09-21T14:13:20Z Stopped: the judge failed three times running: the judge exited 1\n\nWorker: {OFF_LADDER}\n"])
|
||||
|
||||
def test_each_judge_reply_the_loop_rejects_is_archived_with_why_beside_the_verdict_that_follows(self):
|
||||
unfilled = ran(json.dumps({"structured_output": {"interrupt": False}}))
|
||||
misquoted = judged("finished", evidence="never said")
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[unfilled, misquoted, judged("finished")])
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake)).verdict, Finished("working"))
|
||||
stamp = "2026-09-21T14:13:20Z"
|
||||
self.assertEqual(self.archived_outcomes(), [
|
||||
"Task: Do it.\n\n"
|
||||
f"{stamp} Judge reply rejected: the judge's reply has no answer of type string\n\nReply:\n> {unfilled.stdout}\n\nJudge: judge-model\n\n"
|
||||
f"{stamp} Judge reply rejected: the judge quoted 'never said', which is not in the task or the transcript\n\nReply:\n> {misquoted.stdout}\n\nJudge: judge-model\n\n"
|
||||
f"{stamp} Verdict: finished\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n"])
|
||||
|
||||
def test_archives_each_judge_runs_prompt_and_reply_beside_the_rejection_interrupt_and_verdict_it_gave(self):
|
||||
rejected, interrupted, finished = ran(json.dumps({"structured_output": {"interrupt": False}})), judged("interrupt", cost=0.25), judged("finished")
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)] * 2, claude=[rejected, interrupted, finished], inputs=["Use B."])
|
||||
with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake)).verdict, Finished("working"))
|
||||
prompts = [stdin for args, stdin in fake.made("claude")[:3]]
|
||||
[chunk] = self.archive.iterdir()
|
||||
kept = "\n".join(path.read_text() for path in chunk.glob("*.outcomes.md"))
|
||||
named = re.findall(r"^Judge run: (judge/[0-9a-f]{64}\.json)$", kept, re.MULTILINE)
|
||||
self.assertEqual(len(named), 3, kept)
|
||||
runs = [json.loads((chunk / name).read_text()) for name in named]
|
||||
replies = [json.loads(reply.stdout) for reply in (rejected, interrupted, finished)]
|
||||
self.assertEqual(sorted((found["prompt"], json.dumps(found["reply"])) for found in runs), sorted((prompt, json.dumps(reply)) for prompt, reply in zip(prompts, replies)))
|
||||
self.assertEqual(sorted(path.name for path in (chunk / "judge").iterdir()), sorted(name.removeprefix("judge/") for name in named))
|
||||
|
||||
def test_stops_when_a_judge_run_cannot_be_archived(self):
|
||||
self.archive.mkdir(parents=True)
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("finished")])
|
||||
fake.replace_file = lambda path, data: Failure("disk full") if "/judge/" in str(path) else replace_file(path, data)
|
||||
stop = run.run_cycle(self.cycle(fake))
|
||||
self.assertEqual(stop.code, 1)
|
||||
self.assertRegex(stop.reason, r"^could not archive the transcript: .*/judge/[0-9a-f]{64}\.json: disk full$")
|
||||
|
||||
def test_archives_what_each_judge_run_cost_on_an_interrupt_a_quoted_answer_and_a_rejected_misquote(self):
|
||||
for first, then, inputs in (
|
||||
(judged("interrupt", cost=0.25), judged("finished"), ["Use B."]),
|
||||
(judged("quoted", answer="Use A.", cost=0.25), judged("finished"), []),
|
||||
(judged("unfinished", cost=0.25), judged("finished"), []),
|
||||
(judged("finished", evidence="never said", cost=0.25), judged("finished"), []),
|
||||
):
|
||||
with self.subTest(first=first.stdout), tempfile.TemporaryDirectory() as archive:
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)] * 2, claude=[first, then], inputs=inputs)
|
||||
with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
|
||||
run.run_cycle(dataclasses.replace(self.cycle(fake, records="From AGENTS.md:\nUse A."), project_archive=pathlib.Path(archive)))
|
||||
kept = "".join(path.read_text() for path in pathlib.Path(archive).glob("*/*.outcomes.md"))
|
||||
self.assertEqual(kept.count("Judge cost: 0.2500\n"), 1, kept)
|
||||
self.assertIn("Judge cost: 0.2500\nJudge run: judge/", kept)
|
||||
|
||||
def test_stops_with_exit_1_where_a_subagents_transcript_cannot_be_read_for_the_spend(self):
|
||||
for verdict in ("interrupt", "finished"):
|
||||
with self.subTest(verdict=verdict), tempfile.TemporaryDirectory() as archive:
|
||||
unreadable = self.paths.claude_code_transcripts / "-fake" / str(self.session.id) / "subagents" / "agent-x.jsonl"
|
||||
unreadable.mkdir(parents=True)
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged(verdict)], inputs=["Use B."])
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
stop = run.run_cycle(dataclasses.replace(self.cycle(fake), project_archive=pathlib.Path(archive)))
|
||||
self.assertEqual((stop.code, stop.reason), (1, f"could not read the transcript {unreadable}: Is a directory"))
|
||||
shutil.rmtree(unreadable.parent.parent)
|
||||
(self.paths.claude_code_transcripts / "-fake" / f"{self.session.id}.jsonl").unlink()
|
||||
|
||||
def test_counts_the_spend_since_the_last_outcome_that_recorded_one_and_archives_the_reversal(self):
|
||||
transcript = self.paths.claude_code_transcripts / "-fake" / f"{self.session.id}.jsonl"
|
||||
transcript.parent.mkdir(parents=True)
|
||||
old = {"type": "assistant", "timestamp": "2026-09-21T14:13:19Z", "message": {"id": "old", "model": "claude-opus-5-5", "content": [], "usage": {"output_tokens": 100}}}
|
||||
new = {"type": "assistant", "timestamp": "2026-09-21T14:13:21Z", "message": {"id": "new", "model": "claude-opus-5-5", "content": [], "usage": {"output_tokens": 5}}}
|
||||
transcript.write_text("\n".join(json.dumps(entry) for entry in [{"type": "queue-operation", "timestamp": "2026-09-21T14:00:00Z"}, old, human("No, keep the old name."), new]) + "\n")
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
self.assertIsNone(write.archive(self.archive, str(transcript), "Do it.", outcomes.unfinished("w", "e", "j", "", annotation=outcomes.Annotation("c", "Spent since the chunk began, in tokens of x:\n- worker, m: 1")), NOW, replace=replace_file))
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("unfinished", reversed="No, keep the old name.")])
|
||||
run.run_cycle(self.cycle(fake))
|
||||
latest = max(self.archived_outcomes(), key=len)
|
||||
self.assertIn(f"""Reversed:
|
||||
> No, keep the old name.
|
||||
|
||||
Spent since 2026-09-21T14:13:20Z, in tokens of input, cache write 5m, cache write 1h, cache read, output:
|
||||
- worker, claude-opus-5-5: 0, 0, 0, 0, 5
|
||||
""", latest)
|
||||
|
||||
def test_stops_with_exit_1_asking_nothing_where_an_interrupt_cannot_be_archived(self):
|
||||
self.archive.parent.mkdir(parents=True)
|
||||
self.archive.write_text("")
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("interrupt")], inputs=["Use B."])
|
||||
with contextlib.redirect_stderr(io.StringIO()) as said:
|
||||
stop = run.run_cycle(self.cycle(fake))
|
||||
self.assertEqual((stop.code, stop.reason.split(":")[0]), (1, "could not archive the transcript"))
|
||||
self.assertNotIn("Which one?", said.getvalue())
|
||||
self.assertEqual(fake.made("claude_on_terminal"), [])
|
||||
|
||||
def test_stops_when_a_rejected_reply_cannot_be_archived(self):
|
||||
self.archive.parent.mkdir(parents=True)
|
||||
self.archive.write_text("")
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[ran(json.dumps({"structured_output": {"interrupt": False}})), judged("finished")])
|
||||
stop = run.run_cycle(self.cycle(fake))
|
||||
self.assertRegex(stop.reason, f"^could not archive the transcript: {self.archive}/[0-9a-f]{{64}}: Not a directory$")
|
||||
self.assertEqual(stop.code, 1)
|
||||
self.assertEqual(len(fake.made("claude")), 1)
|
||||
|
||||
def test_archives_the_judges_rejected_replies_though_it_fails_three_times_running(self):
|
||||
unfilled = ran(json.dumps({"structured_output": {"interrupt": False}}))
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[unfilled] * 3)
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake)).code, 1)
|
||||
[archived] = self.archived_outcomes()
|
||||
self.assertEqual(archived.count(f"Reply:\n> {unfilled.stdout}\n"), 3)
|
||||
self.assertIn("Stopped: the judge failed three times running", archived)
|
||||
|
||||
def test_archives_each_chunks_session_folder_replacing_a_copy_only_with_what_grew_from_it(self):
|
||||
folder = self.paths.claude_code_transcripts / "-fake" / str(self.session.id)
|
||||
(folder / "subagents" / "workflows").mkdir(parents=True)
|
||||
(folder / "subagents" / "agent-a.jsonl").write_text("a\n")
|
||||
(folder / "subagents" / "workflows" / "journal.jsonl").write_text("j\n")
|
||||
(folder / "custom-title.json").write_text("first")
|
||||
(folder.parent / f"{self.session.id}.orphaned-1.jsonl").write_text("o\n")
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)] * 3, claude=[judged("unfinished"), judged("finished"), judged("unfinished")])
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake)).verdict, Unfinished("working", entries_read=3))
|
||||
[chunk] = self.archive.iterdir()
|
||||
kept = chunk / "session" / str(self.session.id)
|
||||
self.assertEqual((chunk / "session" / f"{self.session.id}.orphaned-1.jsonl").read_text(), "o\n")
|
||||
os.utime(kept / "subagents" / "workflows" / "journal.jsonl", (0, 0))
|
||||
with open(folder / "subagents" / "agent-a.jsonl", "a") as handle:
|
||||
handle.write("more\n")
|
||||
(folder / "custom-title.json").write_text("second")
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake)).verdict, Finished("working"))
|
||||
self.assertFalse(folder.exists())
|
||||
self.assertEqual((kept / "subagents" / "agent-a.jsonl").read_text(), "a\nmore\n")
|
||||
self.assertEqual((kept / "subagents" / "workflows" / "journal.jsonl").stat().st_mtime, 0)
|
||||
self.assertEqual(sorted(path.read_text() for path in kept.glob("custom-title.json*")), ["first", "second"])
|
||||
self.assertEqual(stat.S_IMODE((kept / "subagents" / "agent-a.jsonl").stat().st_mode), 0o600)
|
||||
folder.mkdir()
|
||||
(folder / "custom-title.json").write_text("third")
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake)).verdict, Unfinished("working", entries_read=3))
|
||||
[next_chunk] = set(self.archive.iterdir()) - {chunk}
|
||||
self.assertEqual(sorted(path.read_text() for path in (next_chunk / "session" / str(self.session.id)).glob("custom-title.json*")), ["third"])
|
||||
|
||||
def test_stops_on_a_session_folder_it_cannot_read_whole(self):
|
||||
assert_not_root(self)
|
||||
locked = self.paths.claude_code_transcripts / "-fake" / str(self.session.id) / "subagents"
|
||||
locked.mkdir(parents=True)
|
||||
locked.chmod(0)
|
||||
self.addCleanup(locked.chmod, 0o700)
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("unfinished")])
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake)), Stop(1, f"could not archive the transcript: {locked}: Permission denied"))
|
||||
|
||||
def test_an_interrupt_talked_over_in_claude_is_archived_answered_and_judged_again(self):
|
||||
def answer(args):
|
||||
with open(session.transcript_file(self.session), "a") as handle:
|
||||
handle.write(json.dumps(human("the second")) + "\n")
|
||||
return 0
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("interrupt"), judged("unfinished")], inputs=["/talk"], on_terminal_claude=[answer])
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake)).verdict, Unfinished("working", entries_read=4))
|
||||
self.assertEqual(self.archived_outcomes(), [f"Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: interrupt\n\nWhich one?\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n", f"Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: unfinished\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n"])
|
||||
self.assertIn(str(self.session.id), fake.made("claude_on_terminal")[0])
|
||||
judge_prompts = [stdin for args, stdin in fake.made("claude")]
|
||||
self.assertEqual(len(judge_prompts), 2)
|
||||
self.assertNotIn("the second", judge_prompts[0])
|
||||
self.assertIn("[human] the second", judge_prompts[1])
|
||||
self.assertIn("From the goals file, ## Goals", judge_prompts[0])
|
||||
self.assertIn("writing it into the plan or a comment,", judge_prompts[0])
|
||||
self.assertIn("The task the worker was given:\nDo it.", judge_prompts[0])
|
||||
|
||||
def test_a_question_the_records_answer_resumes_the_worker_with_the_answer_three_times_a_cycle(self):
|
||||
answered = judged("quoted", answer="Use *A*.")
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)] * 4, claude=[answered] * 4, inputs=[""])
|
||||
with contextlib.redirect_stderr(io.StringIO()) as said, contextlib.redirect_stdout(io.StringIO()) as printed:
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake, records="From AGENTS.md:\nUse A.")), Stop(2, "the human is needed to answer the question above, but nothing was typed"))
|
||||
resumed = fake.made("stream_claude")[1]
|
||||
self.assertEqual(resumed[resumed.index("-p") + 1], "Your question: Which one?\n\nthe project's records answers it:\n\nUse *A*.\n\nContinue the task.")
|
||||
self.assertEqual(len(fake.made("stream_claude")), 4)
|
||||
self.assertEqual(printed.getvalue().count("=== the project's records answered: Which one? ===\nUse *A*."), 3)
|
||||
self.assertIn("Which one?\n\nthe project's records says:\nUse *A*.\n\nThose files have answered 3 questions this cycle", said.getvalue())
|
||||
quoted = f"2026-09-21T14:13:20Z Verdict: quoted answer\n\nWhich one?\n\nthe project's records says:\n> Use *A*.\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n"
|
||||
self.assertEqual(self.archived_outcomes(), [f"Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: interrupt\n\nWhich one?\n\nthe project's records says:\nUse *A*.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n\n2026-09-21T14:13:20Z Stopped: the human is needed to answer the question above, but nothing was typed\n\nWorker: {OFF_LADDER}\n", *[f"Task: Do it.\n\n{quoted}"] * 3])
|
||||
|
||||
def test_a_quoted_answer_that_cites_an_escalation_trigger_steps_the_worker_up_before_it_resumes_and_archives_the_step(self):
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)] * 2, claude=[judged("quoted", answer="Use A.", escalation="working"), judged("finished")])
|
||||
cycle = dataclasses.replace(self.cycle(fake, records="From AGENTS.md:\nUse A."), project=OPUS_PROJECT, route=Route(SONNET, 179, 2, 5))
|
||||
with contextlib.redirect_stdout(io.StringIO()):
|
||||
concluded = run.run_cycle(cycle)
|
||||
self.assertEqual(concluded.route, Route(OPUS, 179, 2, 5, escalated_at=3))
|
||||
first, resumed = fake.made("stream_claude")
|
||||
self.assertEqual([args[args.index("--effort") + 1] for args in (first, resumed)], ["high", "medium"])
|
||||
self.assertTrue(resumed[resumed.index("-p") + 1].endswith("Continue the task. Your request for a higher rung went through: a-driver runs you on claude-opus-5-5 at medium effort. The escalation triggers that fired before this step are spent. You hold claude-opus-5-5 at medium effort."))
|
||||
self.assertNotIn("went through", first[first.index("-p") + 1])
|
||||
answered = f"Verdict: quoted answer\n\nWhich one?\n\nthe project's records says:\n> Use A.\n\nEvidence:\n> working\n\nEscalation:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {SONNET_179}\n"
|
||||
stepped = f"Stepped up\n\nWorker: {OPUS_179_AT_3}\n"
|
||||
kept = "".join(self.archived_outcomes())
|
||||
self.assertIn(f"Z {answered}\n20", kept)
|
||||
self.assertIn(f"Z {stepped}", kept)
|
||||
|
||||
def test_a_quoted_answer_past_the_cap_archives_the_escalation_it_carried_with_the_interrupt_and_steps_up(self):
|
||||
steps = [judged("quoted", answer="Use A.")] * 3 + [judged("quoted", answer="Use A.", escalation="working")]
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)] * 4, claude=steps, inputs=[""])
|
||||
cycle = dataclasses.replace(self.cycle(fake, records="From AGENTS.md:\nUse A."), project=OPUS_PROJECT, route=Route(SONNET, 179, 2, 5))
|
||||
with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
|
||||
self.assertEqual(run.run_cycle(cycle), Stop(2, "the human is needed to answer the question above, but nothing was typed"))
|
||||
kept = "".join(self.archived_outcomes())
|
||||
self.assertIn(f"Evidence:\n> working\n\nEscalation:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {SONNET_179}\n", kept)
|
||||
self.assertIn(f"Stepped up\n\nWorker: {OPUS_179_AT_6}\n", kept)
|
||||
|
||||
def test_a_ruling_steps_the_route_only_on_an_escalation_from_the_rung_its_taken_in_l_picks(self):
|
||||
cycle = dataclasses.replace(self.cycle(FakeEffects()), project=OPUS_PROJECT, route=Route(ONE_UP, 3, 3, 4))
|
||||
for ruling in (Interrupt("e", "q", entries_read=3), QuotedAnswer("e", "q", "A.", entries_read=3)):
|
||||
with self.subTest(ruling=ruling):
|
||||
self.assertIsNone(run.ruling_step_up(cycle, ruling))
|
||||
self.assertEqual(run.ruling_step_up(cycle, Interrupt("e", "q", "round 2: 🔴", TakenIn(highest_likelihood=4), entries_read=3)), routing.StepUp(cycle.route, Route(THREE_UP, 3, 3, 4, escalated_at=3)))
|
||||
|
||||
def test_an_escalation_after_an_interrupt_stepped_the_worker_steps_it_again_in_the_same_cycle(self):
|
||||
streams = [Worker(self.paths.claude_code_transcripts.parent, text="round 2: 🔴"), Worker(self.paths.claude_code_transcripts.parent), Worker(self.paths.claude_code_transcripts.parent)]
|
||||
rulings = [judged("interrupt", evidence="round 2: 🔴", escalation="round 2: 🔴"), judged("quoted", answer="Use A.", escalation="working"), judged("finished")]
|
||||
fake = FakeEffects(streams=streams, claude=rulings, inputs=["Use B."])
|
||||
cycle = dataclasses.replace(self.cycle(fake, records="From AGENTS.md:\nUse A."), project=OPUS_PROJECT, route=Route(SONNET, 179, 2, 5))
|
||||
with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
|
||||
concluded = run.run_cycle(cycle)
|
||||
self.assertEqual(concluded.route, Route(ONE_UP, 179, 2, 5, escalated_at=4))
|
||||
self.assertEqual([args[args.index("--effort") + 1] for args in fake.made("stream_claude")], ["high", "medium", "low"])
|
||||
|
||||
def test_an_escalation_quoted_from_before_the_workers_last_step_up_steps_nothing_and_a_later_one_reaches_the_verdict(self):
|
||||
for escalation, verdict in (("round 2: 🔴", Unfinished("working", entries_read=4)), ("working", Unfinished("working", "working", entries_read=4))):
|
||||
with self.subTest(escalation=escalation):
|
||||
self.session = session.session_named(f"A proj {escalation} a-driver", self.paths.claude_code_transcripts)
|
||||
streams = [Worker(self.paths.claude_code_transcripts.parent, text="round 2: 🔴"), Worker(self.paths.claude_code_transcripts.parent)]
|
||||
rulings = [judged("interrupt", evidence="round 2: 🔴", escalation="round 2: 🔴"), judged("unfinished", escalation=escalation)]
|
||||
fake = FakeEffects(streams=streams, claude=rulings, inputs=["Use B."])
|
||||
cycle = dataclasses.replace(self.cycle(fake), project=OPUS_PROJECT, route=Route(SONNET, 179, 2, 5))
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
concluded = run.run_cycle(cycle)
|
||||
self.assertEqual(concluded, run.Concluded(verdict, Route(OPUS, 179, 2, 5, escalated_at=3)))
|
||||
|
||||
def test_an_answer_typed_at_the_terminal_resumes_the_worker_headless_and_the_judge_reads_it_as_the_humans(self):
|
||||
worker = Worker(self.paths.claude_code_transcripts.parent, prompted=True)
|
||||
fake = FakeEffects(streams=[worker, worker], claude=[judged("interrupt"), judged("unfinished")], inputs=["Use B."])
|
||||
with contextlib.redirect_stderr(io.StringIO()) as said:
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake)).verdict, Unfinished("working", entries_read=6))
|
||||
self.assertIn(f"\n{STAMP} Which one?\a\n", said.getvalue())
|
||||
self.assertEqual(fake.made("claude_on_terminal"), [])
|
||||
resumed = fake.made("stream_claude")[1]
|
||||
self.assertEqual(resumed[resumed.index("--resume") + 1], str(self.session.id))
|
||||
typed = resumed[resumed.index("-p") + 1]
|
||||
self.assertEqual(worker_prompts.typed_answer(typed).answer, "Use B.")
|
||||
self.assertIn("Which one?", typed)
|
||||
self.assertIn("Continue the task. The chunk is finished only once every answer the human typed in it", typed)
|
||||
judge_prompts = [stdin for args, stdin in fake.made("claude")]
|
||||
self.assertRegex(judge_prompts[1], r"(?s)\[loop\] Your question was: Which one\?.*\n\n\[human\] Use B\.\n\nworking\n\nDecide whether")
|
||||
self.assertNotIn("The human answered", judge_prompts[1])
|
||||
|
||||
def test_an_interrupt_that_steps_the_worker_up_names_its_new_rung_in_the_prompt_that_resumes_it_with_the_typed_answer(self):
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)] * 2, claude=[judged("interrupt", escalation="working"), judged("finished")], inputs=["Use B."])
|
||||
cycle = dataclasses.replace(self.cycle(fake), project=OPUS_PROJECT, route=Route(SONNET, 179, 2, 5))
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
concluded = run.run_cycle(cycle)
|
||||
self.assertEqual(concluded.route, Route(OPUS, 179, 2, 5, escalated_at=3))
|
||||
first, resumed = fake.made("stream_claude")
|
||||
self.assertEqual([args[args.index("--effort") + 1] for args in (first, resumed)], ["high", "medium"])
|
||||
typed = resumed[resumed.index("-p") + 1]
|
||||
self.assertIn("Your request for a higher rung went through: a-driver runs you on claude-opus-5-5 at medium effort.", typed)
|
||||
self.assertIn(" You hold claude-opus-5-5 at medium effort.", typed)
|
||||
self.assertNotIn("went through", first[first.index("-p") + 1])
|
||||
|
||||
def test_an_interrupt_that_steps_the_worker_up_compacts_its_session_on_the_rung_it_ran_on(self):
|
||||
usage = {"input_tokens": 2, "cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 5000}, "cache_read_input_tokens": 70000, "output_tokens": 100}
|
||||
worker = Worker(self.paths.claude_code_transcripts.parent, usage=usage, sent=utc(NOW - 600))
|
||||
fake = FakeEffects(streams=[worker, Streamed(0), worker], claude=[judged("interrupt", escalation="working"), judged("finished")])
|
||||
|
||||
def typed(prompt):
|
||||
for _, action in fake.timers:
|
||||
action()
|
||||
return "Use B."
|
||||
fake.scripts["input"] = [typed]
|
||||
cycle = dataclasses.replace(self.cycle(fake), project=OPUS_PROJECT, route=Route(SONNET, 179, 2, 5))
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
run.run_cycle(cycle)
|
||||
_, compaction, resumed = fake.made("stream_claude")
|
||||
self.assertEqual(compaction[compaction.index("-p") + 1], "/compact")
|
||||
self.assertEqual([(args[args.index("--model") + 1], args[args.index("--effort") + 1]) for args in (compaction, resumed)], [("claude-sonnet-5-5", "high"), ("claude-opus-5-5", "medium")])
|
||||
|
||||
def test_a_typed_answer_past_the_quoted_answers_cap_reaches_the_worker_with_its_own_question(self):
|
||||
worker = Worker(self.paths.claude_code_transcripts.parent)
|
||||
fake = FakeEffects(streams=[worker] * 5, claude=[judged("quoted", answer="Use A.")] * 4 + [judged("finished")], inputs=["Use B."])
|
||||
with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake, records="From AGENTS.md:\nUse A.")).verdict, Finished("working"))
|
||||
typed = fake.made("stream_claude")[4]
|
||||
self.assertIn("Your question was: Which one?\n\nContinue the task.", typed[typed.index("-p") + 1])
|
||||
self.assertNotIn("Those files have answered", typed[typed.index("-p") + 1])
|
||||
|
||||
def test_a_release_ready_to_cut_opens_claudes_session_without_asking_for_an_answer(self):
|
||||
def answer(args):
|
||||
with open(session.transcript_file(self.session), "a") as handle:
|
||||
handle.write(json.dumps(human("cut")) + "\n")
|
||||
return 0
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("interrupt", release_ready=True), judged("finished")], on_terminal_claude=[answer])
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake)).verdict, Finished("working"))
|
||||
self.assertEqual(fake.made("input"), [])
|
||||
self.assertEqual(len(fake.made("claude_on_terminal")), 1)
|
||||
|
||||
def test_stops_when_an_interrupt_cannot_be_archived(self):
|
||||
self.archive.parent.mkdir(parents=True)
|
||||
self.archive.write_text("")
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("interrupt")], inputs=["Use B."])
|
||||
stop = run.run_cycle(self.cycle(fake))
|
||||
self.assertRegex(stop.reason, f"^could not archive the transcript: {self.archive}/[0-9a-f]{{64}}: Not a directory$")
|
||||
self.assertEqual(fake.made("input"), [])
|
||||
|
||||
def test_stops_when_a_quoted_answer_cannot_be_archived(self):
|
||||
self.archive.parent.mkdir(parents=True)
|
||||
self.archive.write_text("")
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("quoted", answer="Use A.")])
|
||||
with contextlib.redirect_stdout(io.StringIO()):
|
||||
stop = run.run_cycle(self.cycle(fake, records="From AGENTS.md:\nUse A."))
|
||||
self.assertRegex(stop.reason, f"^could not archive the transcript: {self.archive}/[0-9a-f]{{64}}: Not a directory$")
|
||||
self.assertEqual(len(fake.made("stream_claude")), 1)
|
||||
|
||||
def test_an_answer_the_records_do_not_hold_is_dropped_and_the_question_goes_to_the_human(self):
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("quoted", answer="Use ... A.")], inputs=[""])
|
||||
with contextlib.redirect_stderr(io.StringIO()) as said:
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake, records="From AGENTS.md:\nUse B. Use A.")), Stop(2, "the human is needed to answer the question above, but nothing was typed"))
|
||||
self.assertEqual(len(fake.made("stream_claude")), 1)
|
||||
self.assertIn(f"\n{STAMP} Which one?\a\n", said.getvalue())
|
||||
self.assertNotIn("Use ... A.", said.getvalue())
|
||||
|
||||
def test_stops_keeping_the_transcript_when_the_finished_chunks_session_cannot_be_deleted(self):
|
||||
assert_not_root(self)
|
||||
folder = self.paths.claude_code_transcripts / "-fake" / str(self.session.id)
|
||||
(folder / "subagents").mkdir(parents=True)
|
||||
folder.chmod(0o500)
|
||||
self.addCleanup(folder.chmod, 0o700)
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("finished")])
|
||||
stop = run.run_cycle(self.cycle(fake))
|
||||
self.assertEqual(stop, Stop(1, f"could not delete {folder}: Permission denied; delete every file and folder matching {folder}*, then run it again; a run before that resumes the finished chunk's session"))
|
||||
self.assertTrue(session.session_open(self.session))
|
||||
self.assertEqual(self.archived_outcomes(), [f"Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: finished\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n\n2026-09-21T14:13:20Z Stopped: {stop.reason}\n\nWorker: {OFF_LADDER}\n"])
|
||||
|
||||
def test_stops_when_the_worker_leaves_no_transcript(self):
|
||||
fake = FakeEffects(streams=[Streamed(0)])
|
||||
self.assertEqual(run.run_cycle(self.cycle(fake)), Stop(1, f"claude left no transcript for session {self.session.id}"))
|
||||
@@ -0,0 +1,89 @@
|
||||
import json
|
||||
import pathlib
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from claude_code import entries
|
||||
from loop_effects.doubles import FakeEffects, judged, ran
|
||||
from agent_cycle import judge, spend
|
||||
from agent_cycle.verdicts import Judged, Unfinished
|
||||
from transcript_archive import outcomes
|
||||
from claude_code.tokens import Tokens, tokens_of
|
||||
|
||||
|
||||
def turn(message_id, model, at, **usage):
|
||||
return entries.AssistantTurn(message_id=message_id, model=model, timestamp=at, usage=usage)
|
||||
|
||||
|
||||
class Spend(unittest.TestCase):
|
||||
def test_reads_the_cache_writes_by_lifetime_and_counts_one_without_the_split_as_five_minutes(self):
|
||||
self.assertEqual(tokens_of({"input_tokens": 1, "cache_creation_input_tokens": 9, "cache_creation": {"ephemeral_5m_input_tokens": 2, "ephemeral_1h_input_tokens": 3}, "cache_read_input_tokens": 4, "output_tokens": 5}), Tokens(1, 2, 3, 4, 5))
|
||||
self.assertEqual(tokens_of({"input_tokens": 1, "cache_creation_input_tokens": 9}), Tokens(1, 9, 0, 0, 0))
|
||||
self.assertEqual(tokens_of(None), Tokens())
|
||||
|
||||
def test_counts_a_messages_context_as_every_prompt_token_and_no_output(self):
|
||||
self.assertEqual(Tokens(1, 2, 3, 4, 5).context(), 10)
|
||||
|
||||
def test_counts_a_message_written_in_the_stamped_second_or_without_a_readable_time_as_before_since(self):
|
||||
thread = [turn("m1", "a", "2026-11-01T10:00:01Z", output_tokens=7), turn("m2", "a", "not a time", output_tokens=3), turn("m3", "a", "2026-11-01T10:00:02Z", output_tokens=1)]
|
||||
self.assertEqual(spend.spent("2026-11-01T10:00:01Z", thread, [], "j", Tokens()), {("worker", "a"): Tokens(output=1)})
|
||||
|
||||
def test_sums_two_subagents_of_one_name_on_one_model(self):
|
||||
helpers = [spend.Subagent("Explore", [turn("s1", "b", "2026-11-01T10:00:00Z", input_tokens=3)]), spend.Subagent("Explore", [turn("s2", "b", "2026-11-01T10:00:00Z", input_tokens=4)])]
|
||||
self.assertEqual(spend.spent("", [], helpers, "j", Tokens()), {("Explore", "b"): Tokens(input=7)})
|
||||
|
||||
def test_counts_each_message_once_by_its_id_and_only_after_since(self):
|
||||
thread = [
|
||||
turn("m1", "a", "2026-11-01T10:00:00Z", output_tokens=7),
|
||||
turn("m2", "a", "2026-11-01T10:00:02Z", input_tokens=1, output_tokens=2),
|
||||
turn("m2", "a", "2026-11-01T10:00:02Z", input_tokens=1, output_tokens=2),
|
||||
turn("m3", "b", "2026-11-01T10:00:03Z", cache_read_input_tokens=5),
|
||||
]
|
||||
self.assertEqual(spend.thread_spend(thread, "2026-11-01T10:00:01Z"), {"a": Tokens(1, 0, 0, 0, 2), "b": Tokens(0, 0, 0, 5, 0)})
|
||||
self.assertEqual(spend.thread_spend(thread, ""), {"a": Tokens(1, 0, 0, 0, 9), "b": Tokens(0, 0, 0, 5, 0)})
|
||||
|
||||
def test_names_each_spender_and_leaves_out_one_that_spent_nothing(self):
|
||||
worker = [turn("m1", "a", "2026-11-01T10:00:00Z", output_tokens=7)]
|
||||
helper = spend.Subagent('Explore "Search"', [turn("s1", "b", "2026-11-01T10:00:00Z", input_tokens=3)])
|
||||
self.assertEqual(spend.spent("", worker, [helper], "j", Tokens()), {("worker", "a"): Tokens(output=7), ('Explore "Search"', "b"): Tokens(input=3)})
|
||||
self.assertEqual(spend.spent("", [], [], "j", Tokens(input=1)), {("judge", "j"): Tokens(input=1)})
|
||||
|
||||
def test_names_a_subagent_by_its_agent_type_and_description(self):
|
||||
with tempfile.TemporaryDirectory() as root:
|
||||
folder = pathlib.Path(root, "s", "subagents")
|
||||
folder.mkdir(parents=True)
|
||||
for name, meta in [("agent-a", {"agentType": "Explore", "description": "Search the hooks"}), ("agent-b", None), ("agent-c", ["Explore"]), ("agent-d", {"description": "Läs"}), ("agent-e", {"agentType": "Ex\nConfig: x"})]:
|
||||
(folder / f"{name}.jsonl").write_text(json.dumps({"type": "assistant", "message": {"id": name, "model": "m", "content": [], "usage": {"output_tokens": 1}}, "timestamp": "2026-11-01T10:00:00Z"}) + "\n")
|
||||
if meta:
|
||||
(folder / f"{name}.meta.json").write_text(json.dumps(meta))
|
||||
found = spend.subagents(str(pathlib.Path(root, "s.jsonl")))
|
||||
self.assertEqual([subagent.name for subagent in found], ['Explore "Search the hooks"', "subagent", "subagent", 'subagent "Läs"', "Ex Config: x"])
|
||||
self.assertEqual(spend.spent("", [], found[:2], "j", Tokens()), {('Explore "Search the hooks"', "m"): Tokens(output=1), ("subagent", "m"): Tokens(output=1)})
|
||||
self.assertEqual(spend.subagents(str(pathlib.Path(root, "none.jsonl"))), [])
|
||||
|
||||
def test_renders_the_spend_then_the_list_prices_of_each_model_it_knows(self):
|
||||
found = {("worker", "claude-opus-5-5"): Tokens(1, 2, 3, 4, 5), ("judge", "unpriced"): Tokens(input=6)}
|
||||
self.assertEqual(outcomes.spent_block("2026-11-01T10:00:00Z", found), """Spent since 2026-11-01T10:00:00Z, in tokens of input, cache write 5m, cache write 1h, cache read, output:
|
||||
- worker, claude-opus-5-5: 1, 2, 3, 4, 5
|
||||
- judge, unpriced: 6, 0, 0, 0, 0
|
||||
|
||||
List prices in dollars per million tokens of input, cache write 5m, cache write 1h, cache read, output:
|
||||
- claude-opus-5-5: 4, 5, 8, 0.2, 20""")
|
||||
self.assertEqual(outcomes.spent_block("", {("judge", "unpriced"): Tokens(input=6)}), "Spent since the chunk began, in tokens of input, cache write 5m, cache write 1h, cache read, output:\n- judge, unpriced: 6, 0, 0, 0, 0")
|
||||
self.assertEqual(outcomes.spent_block("", {}), "")
|
||||
|
||||
def test_keeps_the_whole_typed_answer_that_holds_the_judges_quote_and_its_tokens(self):
|
||||
shown = "[human] Use A.\n[human] No, keep the old name. Use X.\nworking: keep the new name"
|
||||
typed = ("Use A.", "No, keep the old name. Use X.")
|
||||
for quoted, kept in [("No, keep the old name. Use X.", "No, keep the old name. Use X."), ("keep the old name", "No, keep the old name. Use X."), ("Use", "No, keep the old name. Use X."), ("keep the new name", ""), ("No, keep the name.", "")]:
|
||||
with self.subTest(quoted=quoted):
|
||||
answer = json.loads(judged("unfinished", reversed=quoted).stdout)
|
||||
fake = FakeEffects(claude=[ran(json.dumps({**answer, "usage": {"input_tokens": 2, "output_tokens": 3}}))])
|
||||
self.assertEqual(judge.run_judge("/r", [], "", judge.Grounds(shown, shown, "", typed), fake.effects()), Unfinished("working", judged=Judged(tokens=Tokens(input=2, output=3), reversed=kept)))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,68 @@
|
||||
import pathlib
|
||||
import sys
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from agent_cycle.verdicts import Finished, Interrupt, QuotedAnswer, Unfinished
|
||||
from model_routing.route import Route
|
||||
from agent_cycle import routing
|
||||
from model_routing.ladder import Rung
|
||||
from agent_cycle import states
|
||||
|
||||
|
||||
TYPED = states.TypedAnswer("Which one?", "Use B.")
|
||||
|
||||
|
||||
class Transitions(unittest.TestCase):
|
||||
def test_each_state_moves_on_its_events_and_only_on_them(self):
|
||||
answered = states.Ruled(QuotedAnswer("e", "Which one?", "A."))
|
||||
legal = (
|
||||
(states.Working(), states.WorkerRan("/t"), states.Judging("/t")),
|
||||
(states.Working(QuotedAnswer("e", "Which one?", "A."), 3), states.WorkerRan("/t"), states.Judging("/t", 3)),
|
||||
(states.Judging("/t"), states.Ruled(Interrupt("e", "Which one?")), states.Interrupting("/t", Interrupt("e", "Which one?"))),
|
||||
(states.Judging("/t", 3), states.Ruled(Interrupt("e", "Which one?")), states.Interrupting("/t", Interrupt("e", "Which one?"), 3)),
|
||||
(states.Judging("/t"), answered, states.Working(QuotedAnswer("e", "Which one?", "A."), 1)),
|
||||
(states.Judging("/t", 2), answered, states.Working(QuotedAnswer("e", "Which one?", "A."), 3)),
|
||||
(states.Judging("/t", 3), answered, states.Interrupting("/t", QuotedAnswer("e", "Which one?", "A."), 3)),
|
||||
(states.Judging("/t"), states.Ruled(Finished("e")), states.Closing("/t", Finished("e"))),
|
||||
(states.Judging("/t", 3), states.Ruled(Finished("e")), states.Closing("/t", Finished("e"))),
|
||||
(states.Judging("/t"), states.Ruled(Unfinished("e")), states.Closing("/t", Unfinished("e"))),
|
||||
(states.Judging("/t", 3), states.Ruled(Unfinished("e")), states.Closing("/t", Unfinished("e"))),
|
||||
(states.Interrupting("/t", Interrupt("e", "q")), states.HumanTalked(), states.Judging("/t")),
|
||||
(states.Interrupting("/t", Interrupt("e", "q"), 3), states.HumanTalked(), states.Judging("/t", 3)),
|
||||
(states.Interrupting("/t", Interrupt("e", "q")), states.HumanTyped(TYPED), states.Working(TYPED)),
|
||||
(states.Interrupting("/t", Interrupt("e", "q"), 3), states.HumanTyped(TYPED), states.Working(TYPED, 3)),
|
||||
(states.Working(TYPED, 3), states.WorkerRan("/t"), states.Judging("/t", 3)),
|
||||
(states.Closing("/t", Finished("e")), states.Archived(), states.Ended(Finished("e"))),
|
||||
(states.Closing("/t", Unfinished("e")), states.Archived(), states.Ended(Unfinished("e"))),
|
||||
)
|
||||
for state, event, after in legal:
|
||||
with self.subTest(state=state, event=event):
|
||||
self.assertEqual(states.transition(state, event), after)
|
||||
every_state = (states.Working(), states.Working(QuotedAnswer("e", "Which one?", "A."), 3), states.Working(TYPED, 3), states.Judging("/t"), states.Judging("/t", 3), states.Interrupting("/t", Interrupt("e", "q")), states.Interrupting("/t", Interrupt("e", "q"), 3), states.Closing("/t", Finished("e")), states.Ended(Finished("e")))
|
||||
every_event = (states.WorkerRan("/t"), states.Ruled(Interrupt("e", "Which one?")), answered, states.Ruled(Finished("e")), states.Ruled(Unfinished("e")), states.HumanTalked(), states.HumanTyped(TYPED), states.Archived())
|
||||
for state in every_state:
|
||||
for event in every_event:
|
||||
if (state, event) not in [(state, event) for state, event, _ in legal]:
|
||||
with self.subTest(state=state, event=event), self.assertRaises(ValueError):
|
||||
states.transition(state, event)
|
||||
|
||||
def test_a_rulings_step_up_reaches_the_worker_it_resumes_through_the_answer_the_human_types_and_no_further(self):
|
||||
ran_on = Rung("claude-opus-5-5", "xhigh")
|
||||
stepped = routing.StepUp(Route(ran_on), Route(Rung("claude-fable-5-2", "low"), escalated_at=3))
|
||||
interrupt, quoted = Interrupt("e", "q", "round 2: 🔴"), QuotedAnswer("e", "q", "A.", "round 2: 🔴")
|
||||
for state, event, after in (
|
||||
(states.Judging("/t"), states.Ruled(quoted, stepped), states.Working(quoted, 1, True)),
|
||||
(states.Judging("/t", 3), states.Ruled(quoted, stepped), states.Interrupting("/t", quoted, 3, ran_on)),
|
||||
(states.Judging("/t"), states.Ruled(interrupt, stepped), states.Interrupting("/t", interrupt, 0, ran_on)),
|
||||
(states.Interrupting("/t", interrupt, 0, ran_on), states.HumanTyped(TYPED), states.Working(TYPED, 0, True)),
|
||||
(states.Interrupting("/t", interrupt, 0, ran_on), states.HumanTalked(), states.Judging("/t")),
|
||||
(states.Working(TYPED, 0, True), states.WorkerRan("/t"), states.Judging("/t")),
|
||||
):
|
||||
with self.subTest(state=state, event=event):
|
||||
self.assertEqual(states.transition(state, event), after)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,137 @@
|
||||
import contextlib
|
||||
import dataclasses
|
||||
import io
|
||||
import json
|
||||
import pathlib
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
from loop_effects.doubles import FakeEffects, NOW, ran, Streamed
|
||||
from model_routing.ladder import Rung
|
||||
from loop_effects.child_shells import Shell
|
||||
from agent_cycle import stuck_workers, worker
|
||||
from text_files.utc_stamp import utc
|
||||
|
||||
RUNG = Rung("claude-opus-5-5", "medium")
|
||||
ASSISTANT = {"type": "assistant", "message": {"content": []}}
|
||||
|
||||
|
||||
def verdict(said="stuck", process=8, why="pytest waits on a shell that ignores SIGINT"):
|
||||
return ran(json.dumps({"type": "result", "structured_output": {"verdict": said, "process": process, "why": why}}))
|
||||
|
||||
|
||||
def shell(pid=7, cpu=2.0, started=NOW - 1000, written=NOW - 1000, runs_busy_tool=False, processes=("8 S 2.0 s python3 -m pytest", "9 S 0.0 s sh -c trap '' INT; sleep 999"), output="collected 40 items", holds_slot=False):
|
||||
return Shell(pid=pid, started=started, command="bin/run-tests", written=written, runs_busy_tool=runs_busy_tool, cpu=cpu, processes=processes, output=output, holds_slot=holds_slot)
|
||||
|
||||
|
||||
def sign(run, quiet, idle=True):
|
||||
return f"\n - shell 7 has run {run} s and written no output for {quiet} s{', and used no CPU for 300 s' if idle else ''}: bin/run-tests"
|
||||
|
||||
|
||||
class StuckWorkers(unittest.TestCase):
|
||||
def worker_with(self, *events, held=(), replies=(), archive=None, each_check=None):
|
||||
"""Runs a worker whose claude prints events and holds the shells held, while each investigation replies in turn; returns the claude, the fake, what was said on stdout and stderr and the record's text. The archive folder is archive, or else one that doesn't exist yet, as for a project's first stop. Where each_check is given, each check finds the next of its shells alone."""
|
||||
clock = [NOW]
|
||||
streamed = Streamed(0, *events, clock=clock, held=held)
|
||||
if each_check:
|
||||
streamed.shells = lambda: [each_check.pop(0)]
|
||||
fake = FakeEffects(streams=[streamed], claude=replies)
|
||||
self.claude_folders = []
|
||||
def claude(args, cwd, stdin):
|
||||
self.claude_folders.append(cwd)
|
||||
return fake.effects().claude(args, cwd, stdin)
|
||||
effects = dataclasses.replace(fake.effects(), now=lambda: clock[0], claude=claude)
|
||||
with tempfile.TemporaryDirectory() as folder, contextlib.redirect_stdout(io.StringIO()) as said, contextlib.redirect_stderr(io.StringIO()) as failed:
|
||||
archive = archive or pathlib.Path(folder, "transcripts", "project")
|
||||
worker.run_worker("/r", [], {}, archive, RUNG, effects)
|
||||
record = archive / stuck_workers.RECORD
|
||||
return streamed, fake, said.getvalue(), failed.getvalue(), record.read_text() if record.exists() else ""
|
||||
|
||||
def test_a_silent_worker_whose_shell_used_no_cpu_since_the_last_check_is_investigated_once_and_the_verdict_said_and_recorded_without_a_kill(self):
|
||||
streamed, fake, said, _, record = self.worker_with(ASSISTANT, None, None, None, held=[shell()], replies=[verdict()])
|
||||
[(args, prompt)] = fake.made("claude")
|
||||
self.assertEqual(args[args.index("--model") + 1 :][:3], ["claude-opus-5-5", "--effort", "medium"])
|
||||
self.assertEqual(args[args.index("--tools") + 1 :][:2], ["", "--strict-mcp-config"])
|
||||
self.assertEqual(self.claude_folders, ["/r"])
|
||||
self.assertEqual(json.loads(args[args.index("--json-schema") + 1])["properties"]["verdict"]["enum"], ["working", "waiting on a person", "stuck"])
|
||||
self.assertTrue(prompt.endswith("\n\nShell 7: bin/run-tests\nIts processes, as pid, state, CPU and command line:\n8 S 2.0 s python3 -m pytest\n9 S 0.0 s sh -c trap '' INT; sleep 999\nThe end of its output:\ncollected 40 items"))
|
||||
line = "stuck check: a headless claude judged the worker stuck, naming process 8 (python3 -m pytest): pytest waits on a shell that ignores SIGINT" + sign(1600, 1600)
|
||||
self.assertEqual(said, f"<{NOW + 600}> {line}\n")
|
||||
self.assertEqual(record, f"- {utc(NOW + 600)} {line}\n")
|
||||
self.assertEqual(streamed.stopped, [])
|
||||
|
||||
def test_a_judged_shell_is_judged_again_only_after_it_used_cpu_and_went_idle_once_more(self):
|
||||
cpu = [2.0, 2.0, 2.0, 3.0, 3.0]
|
||||
_, fake, _, _, record = self.worker_with(ASSISTANT, *[None] * 5, each_check=[shell(cpu=each) for each in cpu], replies=[verdict("working", 8, "the tests run"), verdict()])
|
||||
self.assertEqual(len(fake.made("claude")), 2)
|
||||
self.assertEqual([line.split(" ")[1] for line in record.splitlines() if line.startswith("- ")], [utc(NOW + 600), utc(NOW + 1500)])
|
||||
|
||||
def test_an_old_shell_that_keeps_using_cpu_is_judged_once(self):
|
||||
_, fake, _, _, _ = self.worker_with(ASSISTANT, None, None, None, each_check=[shell(cpu=each, started=NOW - stuck_workers.OLD) for each in (2.0, 3.0, 4.0)], replies=[verdict()])
|
||||
self.assertEqual(len(fake.made("claude")), 1)
|
||||
|
||||
def test_a_shell_whose_investigation_failed_is_judged_at_the_next_check(self):
|
||||
_, fake, said, _, _ = self.worker_with(ASSISTANT, None, None, None, held=[shell()], replies=[ran(code=1, stderr="no model"), verdict()])
|
||||
self.assertEqual(len(fake.made("claude")), 2)
|
||||
self.assertIn(f"<{NOW + 900}> stuck check: a headless claude judged the worker stuck", said)
|
||||
|
||||
def test_a_named_process_without_a_command_line_is_said_so(self):
|
||||
_, _, said, _, _ = self.worker_with(ASSISTANT, None, None, held=[shell(processes=("8 Z 0.0 s ",))], replies=[verdict()])
|
||||
self.assertIn("naming process 8 (no command line):", said)
|
||||
|
||||
def test_hands_the_investigation_none_for_a_shell_without_processes_or_output(self):
|
||||
_, fake, _, _, _ = self.worker_with(ASSISTANT, None, None, held=[shell(processes=(), output="")], replies=[verdict()])
|
||||
[(_, prompt)] = fake.made("claude")
|
||||
self.assertTrue(prompt.endswith("\n\nShell 7: bin/run-tests\nIts processes, as pid, state, CPU and command line:\nnone\nThe end of its output:\nnone"))
|
||||
|
||||
def test_a_shell_older_than_a_chunk_usually_runs_is_investigated_at_the_first_check(self):
|
||||
old = [shell(pid, started=NOW - stuck_workers.OLD, written=NOW + 290) for pid in (7, 10)]
|
||||
_, fake, said, _, _ = self.worker_with(ASSISTANT, None, held=old, replies=[verdict("working", 7, "the tests still print")])
|
||||
[(_, prompt)] = fake.made("claude")
|
||||
self.assertIn("collected 40 items\n\nShell 10: bin/run-tests\n", prompt)
|
||||
self.assertIn(f"stuck check: a headless claude judged the worker working, naming process 7 (bin/run-tests): the tests still print{sign(stuck_workers.OLD + 300, 10, idle=False)}{sign(stuck_workers.OLD + 300, 10, idle=False).replace('shell 7', 'shell 10')}\n", said)
|
||||
|
||||
def test_a_shell_holding_a_heavy_slot_is_investigated_and_the_verdict_said_on_one_line_with_each_sign_under_it(self):
|
||||
_, _, said, _, _ = self.worker_with(ASSISTANT, None, None, held=[shell(holds_slot=True)], replies=[verdict(process=99, why="the tests\nhang")])
|
||||
self.assertEqual(said, f"<{NOW + 600}> stuck check: a headless claude judged the worker stuck, naming process 99 (not in the evidence): the tests hang{sign(1600, 1600)}\n")
|
||||
|
||||
def test_a_worker_whose_shells_show_no_sign_is_not_investigated(self):
|
||||
for events, held in (
|
||||
((ASSISTANT, None, None), [shell(runs_busy_tool=True)]),
|
||||
((ASSISTANT, None, None), [shell(written=NOW + 600 - stuck_workers.QUIET)]),
|
||||
((ASSISTANT, None), [shell()]),
|
||||
((ASSISTANT, None, None), []),
|
||||
(({"type": "result"}, None, None), [shell()]),
|
||||
((ASSISTANT, None), [shell(started=NOW + 300 - stuck_workers.OLD)]),
|
||||
):
|
||||
with self.subTest(events=events, held=held):
|
||||
_, fake, said, _, record = self.worker_with(*events, held=held)
|
||||
self.assertEqual((fake.made("claude"), record), ([], ""))
|
||||
|
||||
def test_a_shell_that_used_cpu_since_the_last_check_is_not_investigated(self):
|
||||
clock = [NOW]
|
||||
used = [shell(cpu=2.0), shell(cpu=2.5)]
|
||||
streamed = Streamed(0, ASSISTANT, None, None, clock=clock)
|
||||
streamed.shells = lambda: [used.pop(0)]
|
||||
fake = FakeEffects(streams=[streamed])
|
||||
with contextlib.redirect_stdout(io.StringIO()):
|
||||
worker.run_worker("/r", [], {}, pathlib.Path("/archive"), RUNG, dataclasses.replace(fake.effects(), now=lambda: clock[0]))
|
||||
self.assertEqual(fake.made("claude"), [])
|
||||
|
||||
def test_an_investigation_that_fails_or_answers_outside_the_schema_is_said_on_stderr_and_recorded(self):
|
||||
limited = ran(json.dumps({"type": "result", "api_error_status": 429, "result": "You've hit your limit"}))
|
||||
for reply, reason in ((ran(code=1, stderr="no model"), "no model"), (verdict("hung"), "answered outside its schema: {'verdict': 'hung', 'process': 8, 'why': 'pytest waits on a shell that ignores SIGINT'}"), (ran("crashed"), "the stuck check printed no json reply; its last line was: crashed"), (limited, "claude hit a limit: You've hit your limit")):
|
||||
with self.subTest(reason=reason):
|
||||
_, _, said, failed, record = self.worker_with(ASSISTANT, None, None, held=[shell()], replies=[reply])
|
||||
line = f"stuck check: could not judge whether the worker is stuck: {reason}{sign(1600, 1600)}"
|
||||
self.assertEqual((said, failed, record), ("", f"<{NOW + 600}> {line}\n", f"- {utc(NOW + 600)} {line}\n"))
|
||||
|
||||
def test_a_verdict_that_cannot_be_recorded_is_still_said_and_the_failure_said_on_stderr(self):
|
||||
with tempfile.NamedTemporaryFile() as blocker:
|
||||
_, _, said, failed, _ = self.worker_with(ASSISTANT, None, None, held=[shell()], replies=[verdict()], archive=pathlib.Path(blocker.name))
|
||||
self.assertIn("judged the worker stuck", said)
|
||||
self.assertIn(f"could not record the stuck check in {blocker.name}/{stuck_workers.RECORD}", failed)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,91 @@
|
||||
import pathlib
|
||||
import subprocess
|
||||
import sys
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from failure import Failure
|
||||
from loop_effects.doubles import FakeEffects
|
||||
from agent_cycle import tmux
|
||||
from agent_cycle.doubles import WINDOW
|
||||
|
||||
|
||||
class TmuxCommands(unittest.TestCase):
|
||||
def test_refuses_a_tmux_older_than_needed_naming_both_versions(self):
|
||||
for found, reason in (("tmux 3.2", None), ("tmux 3.8", None), ("tmux next-3.4", None), ("tmux 10.0", None),
|
||||
("tmux 3.1c", "loop-claude runs each chunk in a tmux window, and needs tmux 3.2 or later; it found tmux 3.1c"),
|
||||
("tmux 2.9a", "loop-claude runs each chunk in a tmux window, and needs tmux 3.2 or later; it found tmux 2.9a"),
|
||||
("", "loop-claude runs each chunk in a tmux window, and needs tmux 3.2 or later; it found no tmux")):
|
||||
with self.subTest(found=found):
|
||||
fake = FakeEffects(tmux_version=found)
|
||||
self.assertEqual(tmux.unusable(fake.tmux, "loop-claude"), reason)
|
||||
self.assertEqual(fake.tmux_calls, [["-V"]])
|
||||
|
||||
def test_names_the_session_for_the_project(self):
|
||||
self.assertEqual(tmux.session_name(tmux.LOOP, "claude-config"), "loop-claude-config")
|
||||
# tmux reads `.` and `:` in a target as separators.
|
||||
self.assertEqual(tmux.session_name(tmux.LOOP, "my.site:2 x"), "loop-my-site-2-x")
|
||||
self.assertEqual(tmux.session_name(tmux.LOOP, "Acme/Billing"), "loop-Acme-Billing")
|
||||
|
||||
def test_lists_the_windows_without_the_waiting_mark(self):
|
||||
fake = FakeEffects(windows="item-372 ?\t0\t@1\nitem-380\t1\t@2\nno-item\t0\t@5\n")
|
||||
self.assertEqual(tmux.listed("loop-proj", fake.tmux), [tmux.Listed("item-372", "@1", False, asks=True), tmux.Listed("item-380", "@2", True), tmux.Listed("no-item", "@5", False)])
|
||||
self.assertEqual(fake.tmux_calls, [["list-windows", "-t", "=loop-proj", "-F", "#{window_name}\t#{pane_dead}\t#{window_id}"]])
|
||||
self.assertEqual(tmux.listed("loop-proj", FakeEffects().tmux), [])
|
||||
failed = lambda args: subprocess.CompletedProcess(args, 1, "item-1\t0\t@1\n", "no server")
|
||||
self.assertEqual(tmux.listed("loop-proj", failed), [])
|
||||
|
||||
def test_the_first_window_makes_the_session_and_each_later_one_joins_it(self):
|
||||
fake = FakeEffects()
|
||||
window = tmux.Window("loop-proj", "item-7", "")
|
||||
self.assertIsNone(tmux.start_window(window, "/r", {"LOOP_CLAUDE_X": "1"}, ["/b/loop-claude", "--chunk", "item-7", "ship it;"], True, True, fake.tmux))
|
||||
self.assertIsNone(tmux.start_window(window, "/r", {}, ["/b/loop-claude"], False, True, fake.tmux))
|
||||
self.assertEqual(fake.tmux_calls, [
|
||||
["new-session", "-d", "-s", "loop-proj", "-n", "item-7", "-c", "/r", "-e", "LOOP_CLAUDE_X=1", "-P", "-F", "#{window_id}", "--", "/b/loop-claude", "--chunk", "item-7", "ship it\;"],
|
||||
["set-option", "-t", "=loop-proj:", "@loop-root", "/r"],
|
||||
["set-option", "-w", "-t", "@9", "@chunk-root", "/r"],
|
||||
["set-option", "-w", "-t", "@9", "remain-on-exit", "failed"],
|
||||
["new-window", "-d", "-t", "=loop-proj:", "-n", "item-7", "-c", "/r", "-P", "-F", "#{window_id}", "--", "/b/loop-claude"],
|
||||
["set-option", "-w", "-t", "@9", "@chunk-root", "/r"],
|
||||
["set-option", "-w", "-t", "@9", "remain-on-exit", "failed"],
|
||||
])
|
||||
|
||||
def test_says_why_tmux_started_no_window(self):
|
||||
failed = lambda args: subprocess.CompletedProcess(args, 1, "", "duplicate session: loop-proj\n")
|
||||
silent = lambda args: subprocess.CompletedProcess(args, 2, "", "")
|
||||
window = tmux.Window("loop-proj", "item-7", "")
|
||||
self.assertEqual(tmux.start_window(window, "/r", {}, ["x"], True, True, failed), Failure("tmux could not start the window loop-proj:item-7: duplicate session: loop-proj"))
|
||||
self.assertEqual(tmux.start_window(window, "/r", {}, ["x"], True, True, silent), Failure("tmux could not start the window loop-proj:item-7: it exited 2"))
|
||||
|
||||
def test_fails_where_it_cannot_mark_a_session_it_made_as_the_checkouts_but_not_where_remain_on_exit_fails(self):
|
||||
def answering(failing: str):
|
||||
def run(args):
|
||||
fails = args[:1] == ["set-option"] and failing in args
|
||||
return subprocess.CompletedProcess(args, 1 if fails else 0, "" if fails else "@9\n", "no such session\n" if fails else "")
|
||||
return run
|
||||
window = tmux.Window("loop-proj", "item-7", "")
|
||||
self.assertEqual(tmux.start_window(window, "/r", {}, ["x"], True, True, answering(tmux.OWNER)), Failure("tmux started the session loop-proj but could not mark it as this checkout's: no such session"))
|
||||
self.assertIsNone(tmux.start_window(window, "/r", {}, ["x"], True, True, answering("remain-on-exit")))
|
||||
self.assertIsNone(tmux.start_window(window, "/r", {}, ["x"], False, True, answering(tmux.OWNER)))
|
||||
|
||||
def test_reads_the_checkout_the_session_names(self):
|
||||
fake = FakeEffects(owner="/c/proj")
|
||||
self.assertEqual(tmux.owner("loop-proj", fake.tmux), "/c/proj")
|
||||
self.assertEqual(fake.tmux_calls, [["show-options", "-qv", "-t", "=loop-proj:", "@loop-root"]])
|
||||
|
||||
def test_marks_a_waiting_window_by_its_pane_and_clears_the_mark(self):
|
||||
fake = FakeEffects()
|
||||
tmux.mark(WINDOW, True, fake.tmux)
|
||||
tmux.mark(WINDOW, False, fake.tmux)
|
||||
tmux.close(tmux.Listed("item-7", "@3", True), fake.tmux)
|
||||
self.assertEqual(fake.tmux_calls, [["rename-window", "-t", "%4", "item-7 ?"], ["rename-window", "-t", "%4", "item-7"], ["kill-window", "-t", "@3"]])
|
||||
self.assertEqual(WINDOW.target, "loop-proj:item-7")
|
||||
|
||||
def test_shows_the_session_by_attaching_or_inside_tmux_by_switching(self):
|
||||
self.assertEqual(tmux.show("loop-proj", False), ["attach-session", "-t", "=loop-proj"])
|
||||
self.assertEqual(tmux.show("loop-proj", True), ["switch-client", "-t", "=loop-proj"])
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,153 @@
|
||||
import contextlib
|
||||
import dataclasses
|
||||
import io
|
||||
import json
|
||||
import pathlib
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from claude_code import entries, session
|
||||
from failure import Failure
|
||||
from loop_effects.doubles import FakeEffects, NOW, ran, Streamed
|
||||
from agent_cycle import judge, lingering_workers, worker
|
||||
from claude_code.reply import Limited
|
||||
from machine_load import memory
|
||||
from model_routing.ladder import Rung
|
||||
from loop_effects.child_shells import Shell
|
||||
from text_files.utc_stamp import utc
|
||||
|
||||
|
||||
class Limits(unittest.TestCase):
|
||||
def test_the_worker_reports_the_latest_reset_its_stream_names(self):
|
||||
rejected = [{"type": "rate_limit_event", "rate_limit_info": {"status": "rejected", "resetsAt": resets_at}} for resets_at in (NOW + 60, NOW + 600)]
|
||||
allowed = {"type": "rate_limit_event", "rate_limit_info": {"status": "allowed", "resetsAt": NOW + 9000}}
|
||||
limited = {"type": "result", "api_error_status": 429, "result": "You've hit your session limit"}
|
||||
fake = FakeEffects(streams=[Streamed(1, rejected[1], allowed, rejected[0], limited)])
|
||||
self.assertEqual(worker.run_worker("/r", [], {}, pathlib.Path("/archive"), Rung("m"), fake.effects()), Limited(NOW + 600, "You've hit your session limit"))
|
||||
|
||||
def test_a_limit_outranks_the_exit_code_and_its_message_fits_one_line(self):
|
||||
def limited(**said):
|
||||
return {"type": "result", "api_error_status": 429, **said}
|
||||
self.assertEqual(worker.worker_outcome(-9, limited(result="limit\n resets 7pm"), []), Limited(None, "limit resets 7pm"))
|
||||
self.assertEqual(worker.worker_outcome(1, limited(result=" \n"), [NOW]), Limited(NOW, "claude gave no message"))
|
||||
self.assertEqual(worker.worker_outcome(0, limited(), []), Limited(None, "claude gave no message"))
|
||||
self.assertEqual(worker.worker_outcome(0, None, [NOW]), Failure("claude exited 0 without a result event"))
|
||||
self.assertIsNone(worker.worker_outcome(0, {"type": "result"}, [NOW]))
|
||||
|
||||
def test_the_judge_reports_a_limit_whatever_its_exit_code(self):
|
||||
reply = json.dumps({"type": "result", "api_error_status": 429, "is_error": True, "result": "You've hit your session limit · resets 7:40pm (Europe/Stockholm)"})
|
||||
fake = FakeEffects(claude=[ran(reply, code=1, stderr="limited")])
|
||||
self.assertEqual(judge.run_judge("/r", [], "", judge.Grounds("", "", ""), fake.effects()), Limited(None, "You've hit your session limit · resets 7:40pm (Europe/Stockholm)"))
|
||||
|
||||
def test_reads_only_a_rejecting_events_whole_seconds(self):
|
||||
for info, want in [({"status": "rejected", "resetsAt": NOW}, NOW), ({"status": "allowed", "resetsAt": NOW}, None), ({"status": "rejected", "resetsAt": True}, None), ({"status": "rejected"}, None), ("rejected", None)]:
|
||||
with self.subTest(info=info):
|
||||
self.assertEqual(entries.rejected_until({"type": "rate_limit_event", "rate_limit_info": info}), want)
|
||||
|
||||
|
||||
class LingeringWorkers(unittest.TestCase):
|
||||
RESULT = {"type": "result"}
|
||||
|
||||
def worker_with(self, *events, held=()):
|
||||
"""Runs a worker whose claude prints events and holds shells `held`; returns the claude, what loop-claude said and the record's text."""
|
||||
clock = [NOW]
|
||||
streamed = Streamed(0, *events, clock=clock, held=held)
|
||||
fake = FakeEffects(streams=[streamed])
|
||||
effects = dataclasses.replace(fake.effects(), now=lambda: clock[0])
|
||||
with tempfile.TemporaryDirectory() as folder, contextlib.redirect_stdout(io.StringIO()) as said:
|
||||
# The archive folder of a project's first stop doesn't exist yet.
|
||||
archive = pathlib.Path(folder, "transcripts", "project")
|
||||
worker.run_worker("/r", [], {}, archive, Rung("m"), effects)
|
||||
record = archive / lingering_workers.RECORD
|
||||
return streamed, said.getvalue(), record.read_text() if record.exists() else ""
|
||||
|
||||
def shell(self, written=NOW - 1000, runs_busy_tool=False, holds_slot=False):
|
||||
return Shell(pid=7, started=NOW - 1000, command="until false; do sleep 15; done", written=written, runs_busy_tool=runs_busy_tool, holds_slot=holds_slot)
|
||||
|
||||
def test_a_worker_that_lingers_after_its_result_loses_its_quiet_shell_and_the_stop_is_said_and_recorded_in_utc(self):
|
||||
shell = self.shell()
|
||||
streamed, said, record = self.worker_with(self.RESULT, None, held=[shell])
|
||||
self.assertEqual(streamed.stopped, [shell])
|
||||
line = f"stopped shell 7, which held a worker after its final result; it had run 1300 s and written nothing for 1300 s: {shell.command}"
|
||||
self.assertEqual(said, f"<{NOW + 300}> {line}\n")
|
||||
self.assertEqual(record, f"- {utc(NOW + 300)} {line}\n")
|
||||
|
||||
def test_a_worker_keeps_its_shells_where_it_printed_after_its_result_or_printed_none_or_no_check_came_due(self):
|
||||
for events in ((self.RESULT, {"type": "assistant", "message": {"content": []}}, None), (self.RESULT,), (None,), ({"type": "assistant", "message": {"content": []}}, None)):
|
||||
with self.subTest(events=events):
|
||||
streamed, said, record = self.worker_with(*events, held=[self.shell()])
|
||||
self.assertEqual((streamed.stopped, said, record), ([], "", ""))
|
||||
|
||||
def test_a_worker_keeps_every_shell_while_one_of_them_writes_output_runs_a_busy_tool_or_holds_a_heavy_slot(self):
|
||||
for busy in (self.shell(written=NOW + 200), self.shell(runs_busy_tool=True), self.shell(holds_slot=True)):
|
||||
with self.subTest(busy=busy):
|
||||
streamed, _, _ = self.worker_with(self.RESULT, None, held=[self.shell(), busy])
|
||||
self.assertEqual(streamed.stopped, [])
|
||||
|
||||
def test_a_worker_keeps_a_shell_that_wrote_within_the_quiet_time_and_stops_one_that_wrote_before_it(self):
|
||||
# The check comes 300 s after the result, so a shell written at NOW + 300 - QUIET is the latest that is still kept.
|
||||
kept = self.shell(written=NOW + 300 - lingering_workers.QUIET)
|
||||
stopped = self.shell(written=NOW + 300 - lingering_workers.QUIET - 1)
|
||||
self.assertEqual(self.worker_with(self.RESULT, None, held=[kept])[0].stopped, [])
|
||||
self.assertEqual(self.worker_with(self.RESULT, None, held=[stopped])[0].stopped, [stopped])
|
||||
|
||||
def test_a_worker_reads_on_past_a_check_that_found_it_still_working(self):
|
||||
clock = [NOW]
|
||||
effects = dataclasses.replace(FakeEffects(streams=[Streamed(0, None, self.RESULT, clock=clock)]).effects(), now=lambda: clock[0])
|
||||
self.assertIsNone(worker.run_worker("/r", [], {}, pathlib.Path("/archive"), Rung("m"), effects))
|
||||
|
||||
def test_a_stop_that_cannot_be_recorded_is_said_on_stderr_and_every_shell_is_still_stopped(self):
|
||||
clock = [NOW]
|
||||
held = [self.shell(), self.shell()]
|
||||
streamed = Streamed(0, self.RESULT, None, clock=clock, held=held)
|
||||
effects = dataclasses.replace(FakeEffects(streams=[streamed]).effects(), now=lambda: clock[0])
|
||||
with tempfile.NamedTemporaryFile() as blocker, contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()) as failed:
|
||||
worker.run_worker("/r", [], {}, pathlib.Path(blocker.name), Rung("m"), effects)
|
||||
self.assertEqual(streamed.stopped, held)
|
||||
self.assertIn("could not record the stop", failed.getvalue())
|
||||
|
||||
def test_every_stop_of_a_check_is_recorded_though_the_archive_folder_exists_after_the_first(self):
|
||||
held = [self.shell(), self.shell()]
|
||||
_, said, record = self.worker_with(self.RESULT, None, held=held)
|
||||
self.assertEqual(record.count("stopped shell 7"), 2)
|
||||
|
||||
|
||||
class MemoryWait(unittest.TestCase):
|
||||
def test_a_worker_starts_only_once_a_quarter_of_memory_is_available(self):
|
||||
fake = FakeEffects(free_memory=[memory.Memory(available=3, total=16), memory.Memory(available=3, total=16), memory.Memory(available=4, total=16)], streams=[Streamed(0)])
|
||||
with contextlib.redirect_stderr(io.StringIO()) as said:
|
||||
self.assertIsNone(worker.run_worker("/r", [], {}, pathlib.Path("/archive"), Rung("m"), fake.effects()))
|
||||
self.assertEqual([seam for seam, _ in fake.calls], ["memory", "sleep", "memory", "sleep", "memory", "stream_claude"])
|
||||
self.assertEqual(fake.made("sleep"), [worker.MEMORY_POLL] * 2)
|
||||
self.assertEqual(said.getvalue().count("waiting"), 1, said.getvalue())
|
||||
|
||||
def test_a_worker_starts_at_once_where_memory_cannot_be_read(self):
|
||||
fake = FakeEffects(free_memory=[None], streams=[Streamed(0)])
|
||||
self.assertIsNone(worker.run_worker("/r", [], {}, pathlib.Path("/archive"), Rung("m"), fake.effects()))
|
||||
self.assertEqual([seam for seam, _ in fake.calls], ["memory", "stream_claude"])
|
||||
|
||||
|
||||
class WorkerArgs(unittest.TestCase):
|
||||
OPENED = session.session_named("A proj a-driver", pathlib.Path("/h/.claude/projects"))
|
||||
|
||||
def test_opens_a_fresh_session_by_name_and_resumes_an_open_one(self):
|
||||
fresh = worker.worker_args(self.OPENED, Rung("m"), "Do it.", resume=False)
|
||||
self.assertEqual(fresh[fresh.index("--session-id") + 1], str(self.OPENED.id))
|
||||
self.assertEqual(fresh[fresh.index("--name") + 1], "A proj a-driver")
|
||||
resumed = worker.worker_args(self.OPENED, Rung("m"), "Continue the task.", resume=True)
|
||||
self.assertEqual(resumed[resumed.index("--resume") + 1], str(self.OPENED.id))
|
||||
self.assertNotIn("--session-id", resumed)
|
||||
self.assertEqual(resumed[resumed.index("-p") + 1], "Continue the task.")
|
||||
|
||||
def test_disallows_a_wakeup_so_a_worker_that_ends_its_turn_exits(self):
|
||||
for resume in (False, True):
|
||||
with self.subTest(resume=resume):
|
||||
args = worker.worker_args(self.OPENED, Rung("m"), "Do it.", resume=resume)
|
||||
self.assertEqual(args[args.index("--disallowedTools") + 1], "ScheduleWakeup")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,33 @@
|
||||
import dataclasses
|
||||
import pathlib
|
||||
import sys
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from agent_cycle.doubles import PROMPTS
|
||||
from model_routing.route import Route
|
||||
from model_routing.ladder import Rung
|
||||
from agent_cycle import worker_prompts
|
||||
|
||||
|
||||
class TypedAnswers(unittest.TestCase):
|
||||
def test_splits_the_prompt_handing_over_the_answer_into_the_answer_on_the_line_after_its_marker_and_the_rest_and_no_other_prompt(self):
|
||||
route = Route(Rung("worker-model"))
|
||||
marked = "The human answered your question at a-driver's terminal:\nB"
|
||||
typed = worker_prompts.typed_answer(PROMPTS.typed("Which one?", "Use B.", route, None, False))
|
||||
self.assertEqual(typed.answer, "Use B.")
|
||||
self.assertTrue(typed.loop_words.startswith("Your question was: Which one?\n\nContinue the task."))
|
||||
self.assertEqual(worker_prompts.typed_answer(PROMPTS.typed(f"Which one?\n{marked}", "Use B.", route, None, False)).answer, "Use B.")
|
||||
# A ruling that stepped the worker up adds the sentences naming its new rung.
|
||||
self.assertEqual(worker_prompts.typed_answer(PROMPTS.typed("Which one?", "Use B.", Route(Rung("claude-sonnet-5-5", "high"), 179, 2, 5), None, True)).answer, "Use B.")
|
||||
self.assertIsNone(worker_prompts.typed_answer(PROMPTS.answered("Which one?", marked, route, None, False)))
|
||||
self.assertIsNone(worker_prompts.typed_answer(PROMPTS.resumed(marked, route, None)))
|
||||
|
||||
def test_the_typed_answers_prompt_names_the_entry_points_answer_destinations(self):
|
||||
ledger = dataclasses.replace(PROMPTS, answer_destinations="the ledger")
|
||||
self.assertIn("is recorded in the ledger at the one place it governs.", ledger.typed("Which one?", "Use B.", Route(Rung("worker-model")), None, False))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,163 @@
|
||||
"""The tmux commands an entry point runs: each chunk's loop runs in its own window of one tmux session, which loop-claude names for the project and do-epic for the epic (docs/decisions.md → `loop-claude: each chunk runs in its own tmux window`)."""
|
||||
import dataclasses
|
||||
import re
|
||||
import subprocess
|
||||
import typing
|
||||
|
||||
from failure import Failure
|
||||
|
||||
# Runs tmux with these arguments and returns what it printed; exit 127 where tmux cannot start.
|
||||
Tmux = typing.Callable[[list[str]], subprocess.CompletedProcess[str]]
|
||||
|
||||
# The oldest tmux that has every command and option used here. Its CHANGES file dates the newest two to 3.2: `remain-on-exit failed` and `new-session -e`.
|
||||
NEEDED = (3, 2)
|
||||
# What a window's name ends in while its chunk waits for the human. tmux's status bar shows the name, and `!` after it once the bell rang.
|
||||
WAITS = " ?"
|
||||
BELL = "\a"
|
||||
# What follows a window's name while its chunk is parked, before what its pull request waits on, as in `ABC-34 awaits an approval`. A parked chunk takes no running slot (docs/decisions.md → `do-epic: drives one Jira epic …`, "Long gates").
|
||||
PARKED = " awaits "
|
||||
# What a session's name opens with: LOOP for a project's chunks under loop-claude, EPIC for an epic's chunks under do-epic.
|
||||
LOOP = "loop"
|
||||
EPIC = "epic"
|
||||
# The session option that names the checkout whose chunks the session runs, since two checkouts' keys may map to one session name.
|
||||
OWNER = "@loop-root"
|
||||
# The window option that names the folder a window's chunk works in, so that loop-claude and every do-epic see the chunks a do-epic runs in a checkout.
|
||||
ROOT = "@chunk-root"
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Window:
|
||||
"""The tmux window a chunk's loop runs in."""
|
||||
session: str
|
||||
# Without WAITS.
|
||||
name: str
|
||||
# The ID of the loop's pane, which $TMUX_PANE holds. It targets the window whatever its name is.
|
||||
pane: str
|
||||
|
||||
@property
|
||||
def target(self) -> str:
|
||||
"""What `tmux attach -t` and `tmux select-window -t` take to reach the window."""
|
||||
return f"{self.session}:{self.name}"
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Listed:
|
||||
"""A window of the project's session, as tmux lists it."""
|
||||
# Without WAITS, and without PARKED and what follows it.
|
||||
name: str
|
||||
# tmux's ID of the window, such as `@3`.
|
||||
id: str
|
||||
# Whether its loop has exited: `remain-on-exit failed` keeps the window of a loop that failed, so its last lines stay readable.
|
||||
dead: bool
|
||||
# What its name says its parked chunk awaits, as the words after PARKED; empty for a chunk that isn't parked.
|
||||
awaits: str = ""
|
||||
# Whether its name ended in WAITS: its loop asks the human something.
|
||||
asks: bool = False
|
||||
|
||||
@property
|
||||
def parked(self) -> bool:
|
||||
return bool(self.awaits)
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Placed:
|
||||
"""A window of any session, as tmux lists it."""
|
||||
session: str
|
||||
window: Listed
|
||||
# The folder its chunk works in, as ROOT names it; empty for a window started before ROOT was set.
|
||||
root: str
|
||||
|
||||
|
||||
def unusable(run: Tmux, driver: str) -> str | None:
|
||||
"""Why driver, the entry point, cannot use this machine's tmux, naming the version found and the one needed; None where it is NEEDED or later."""
|
||||
found = run(["-V"]).stdout.strip()
|
||||
version = re.search(r"([0-9]+)\.([0-9]+)", found)
|
||||
if version and (int(version[1]), int(version[2])) >= NEEDED:
|
||||
return None
|
||||
return f"{driver} runs each chunk in a tmux window, and needs tmux {NEEDED[0]}.{NEEDED[1]} or later; it found {found or 'no tmux'}"
|
||||
|
||||
|
||||
def session_name(kind: str, key: str) -> str:
|
||||
"""The tmux session an entry point runs its chunks in: kind LOOP with a project's key, such as `loop-claude-config`, or kind EPIC with an epic's key, such as `epic-ABC-12`. tmux reads `.` and `:` in a target as separators, so every character of the key but a letter, a digit, `_` and `-` becomes a dash."""
|
||||
return f"{kind}-" + re.sub(r"[^A-Za-z0-9_-]", "-", key)
|
||||
|
||||
|
||||
def listed(session: str, run: Tmux) -> list[Listed]:
|
||||
"""The windows of session; none where tmux lists none, as while the session doesn't exist or no tmux server runs."""
|
||||
done = run(["list-windows", "-t", f"={session}", "-F", "#{window_name}\t#{pane_dead}\t#{window_id}"])
|
||||
rows = [line.split("\t") for line in done.stdout.splitlines()] if done.returncode == 0 else []
|
||||
return [as_listed(row[0], row[2], row[1]) for row in rows if len(row) == 3]
|
||||
|
||||
|
||||
def as_listed(shown: str, id: str, pane_dead: str) -> Listed:
|
||||
"""The window tmux shows under the name shown, with the ID id and `#{pane_dead}` as pane_dead."""
|
||||
name, _, awaits = shown.removesuffix(WAITS).partition(PARKED)
|
||||
return Listed(name, id, pane_dead == "1", awaits, shown.endswith(WAITS))
|
||||
|
||||
|
||||
def everywhere(run: Tmux) -> list[Placed]:
|
||||
"""The windows of every session; none where no tmux server runs."""
|
||||
done = run(["list-windows", "-a", "-F", f"#{{session_name}}\t#{{window_name}}\t#{{pane_dead}}\t#{{window_id}}\t#{{{ROOT}}}"])
|
||||
rows = [line.split("\t") for line in done.stdout.splitlines()] if done.returncode == 0 else []
|
||||
return [Placed(row[0], as_listed(row[1], row[3], row[2]), row[4]) for row in rows if len(row) == 5]
|
||||
|
||||
|
||||
def start_window(window: Window, cwd: str, env: typing.Mapping[str, str], command: list[str], first: bool, owned: bool, run: Tmux) -> Failure | None:
|
||||
"""Starts command in a new window of window's session, in cwd with env added to its environment, and leaves the client where it is. first makes the session too, and owned marks a session it makes as running the chunks of the checkout cwd. A Failure says why tmux started none, or why it could not mark the session."""
|
||||
make = ["new-session", "-d", "-s", window.session] if first else ["new-window", "-d", "-t", f"={window.session}:"]
|
||||
variables = [flag for name, value in env.items() for flag in ("-e", f"{name}={value}")]
|
||||
# tmux reads a `;` that ends an argument as the end of the command, unless a backslash precedes it.
|
||||
words = [re.sub(r";$", r"\\;", word) for word in command]
|
||||
done = run([*make, "-n", window.name, "-c", cwd, *variables, "-P", "-F", "#{window_id}", "--", *words])
|
||||
if done.returncode:
|
||||
return Failure(f"tmux could not start the window {window.target}: {done.stderr.strip() or f'it exited {done.returncode}'}")
|
||||
# set-option and show-options read a target as a pane's, so `=session` alone names no session.
|
||||
marked = run(["set-option", "-t", f"={window.session}:", OWNER, cwd]) if first and owned else None
|
||||
# A failure leaves the window unseen by loop-claude and by another epic's do-epic, which then may start a chunk beside it; the window still runs.
|
||||
run(["set-option", "-w", "-t", done.stdout.strip(), ROOT, cwd])
|
||||
# By the ID, since a window of the same name may still be closing. A failed remain-on-exit doesn't matter: a loop that fails before it is set closes its window, and its stop is still sent as a DM.
|
||||
run(["set-option", "-w", "-t", done.stdout.strip(), "remain-on-exit", "failed"])
|
||||
# Without the owner, start_chunks cannot tell this checkout's session from another's, so no further chunk may start in it.
|
||||
if marked is not None and marked.returncode:
|
||||
return Failure(f"tmux started the session {window.session} but could not mark it as this checkout's: {marked.stderr.strip() or f'it exited {marked.returncode}'}")
|
||||
return None
|
||||
|
||||
|
||||
def start_chunk(window: Window, cwd: str, env: typing.Mapping[str, str], command: list[str], windows: list[Listed], owned: bool, run: Tmux) -> list[Listed] | Failure:
|
||||
"""Starts a chunk's command in window, in place of each dead window of its name among windows, the session's; the session's windows afterwards, or why tmux started none. start_window says what cwd, env and owned do."""
|
||||
stale = [listed for listed in windows if listed.name == window.name and listed.dead]
|
||||
for listed in stale:
|
||||
close(listed, run)
|
||||
kept = [listed for listed in windows if listed not in stale]
|
||||
failed = start_window(window, cwd, env, command, not kept, owned, run)
|
||||
return failed or [*kept, Listed(window.name, "", False)]
|
||||
|
||||
|
||||
def owner(session: str, run: Tmux) -> str:
|
||||
"""The checkout whose chunks session runs, as OWNER names it; empty where it names none."""
|
||||
return run(["show-options", "-qv", "-t", f"={session}:", OWNER]).stdout.strip()
|
||||
|
||||
|
||||
def close(window: Listed, run: Tmux) -> None:
|
||||
run(["kill-window", "-t", window.id])
|
||||
|
||||
|
||||
def mark(window: Window, waits: bool, run: Tmux) -> None:
|
||||
"""Renames window to end in WAITS while its chunk waits for the human, and back once it doesn't."""
|
||||
run(["rename-window", "-t", window.pane, window.name + (WAITS if waits else "")])
|
||||
|
||||
|
||||
def park(window: Window, on: str, run: Tmux) -> None:
|
||||
"""Shows window's chunk as parked. on is what the chunk awaits, such as `an approval` or `a slot`: the name says so, and no checkout counts a window so named as a running chunk."""
|
||||
run(["rename-window", "-t", window.pane, window.name + PARKED + on])
|
||||
|
||||
|
||||
def unpark(window: Window, root: str, run: Tmux) -> None:
|
||||
"""Shows window's chunk as running again, in the folder root. The window may name another folder: one started again for a parked chunk starts in the epic's folder."""
|
||||
run(["rename-window", "-t", window.pane, window.name])
|
||||
run(["set-option", "-w", "-t", window.pane, ROOT, root])
|
||||
|
||||
|
||||
def show(session: str, inside: bool) -> list[str]:
|
||||
"""The tmux arguments that put session on the human's terminal: inside tmux the client switches to it, and outside a new client attaches."""
|
||||
return ["switch-client" if inside else "attach-session", "-t", f"={session}"]
|
||||
@@ -0,0 +1,77 @@
|
||||
"""The verdicts judge.verdict_from builds from the judge's reply; run.rule then stamps every verdict but Finished with the items the chunk takes. They sit in a module of their own, since routing.py reads them and run.py imports routing.py."""
|
||||
import dataclasses
|
||||
|
||||
from transcript_archive.judge_run import JudgeRun
|
||||
from claude_code.tokens import Tokens
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class TakenIn:
|
||||
"""The highest L, and the highest E + I, among the plan items the worker names on its latest `Chunk items:` line, as the entry point reads them (run.py's Cycle.taken_in). The item the chunk was routed on counts only where the worker names it."""
|
||||
# The highest L among them, 0 for none: an escalation steps up from the rung that L picks, and an unfinished verdict also raises the worker to it.
|
||||
highest_likelihood: int = 0
|
||||
# The highest E + I among them, 0 for none: after an unfinished verdict, it routes the next cycle's reviewers.
|
||||
highest_escape_and_impact: int = 0
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Judged:
|
||||
"""What the judge run that gave a verdict found beside it, which the cycle archives with the verdict."""
|
||||
# In dollars, as its reply records; 0 where it records none.
|
||||
cost: float = 0.0
|
||||
# Its reply's usage, on the judge's model.
|
||||
tokens: Tokens = Tokens()
|
||||
# The human's whole typed answer that holds the judge's quote of a reversal of a choice the worker took on its own recommendation; empty for none, and where no typed answer holds the quote.
|
||||
reversed: str = ""
|
||||
# The prompt it read and its reply, which the archive keeps beside the verdict. Left out of comparisons and reprs, so that equal verdicts stay equal whatever prompt they came from.
|
||||
run: JudgeRun | None = dataclasses.field(default=None, compare=False, repr=False)
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Interrupt:
|
||||
evidence: str
|
||||
question: str
|
||||
# The judge's quote showing that the worker's cited escalation trigger fired; empty for none.
|
||||
escalation: str = ""
|
||||
taken_in: TakenIn = TakenIn()
|
||||
release_ready: bool = False
|
||||
# How many transcript entries the judge read, which escalation_mark.stamped stamps. An escalation the verdict carries moves the route's mark there. None means it was never stamped, and then its escalation doesn't step the worker.
|
||||
entries_read: int | None = None
|
||||
judged: Judged = Judged()
|
||||
# The [human] line from earlier in the chunk that answered the same question, and the words of it that leave the question open; empty for none. cycle.judge.re_ask_checked turns the Interrupt into an Unfinished where the question doesn't quote them.
|
||||
answered_before: str = ""
|
||||
left_open: str = ""
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class QuotedAnswer:
|
||||
"""The worker asked a question that the premises or the records answer. The answer field quotes the passage."""
|
||||
evidence: str
|
||||
question: str
|
||||
answer: str
|
||||
# As on Interrupt.
|
||||
escalation: str = ""
|
||||
taken_in: TakenIn = TakenIn()
|
||||
entries_read: int | None = None
|
||||
judged: Judged = Judged()
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Finished:
|
||||
evidence: str
|
||||
judged: Judged = Judged()
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Unfinished:
|
||||
evidence: str
|
||||
# As on Interrupt.
|
||||
escalation: str = ""
|
||||
taken_in: TakenIn = TakenIn()
|
||||
entries_read: int | None = None
|
||||
judged: Judged = Judged()
|
||||
|
||||
|
||||
Verdict = Interrupt | QuotedAnswer | Finished | Unfinished
|
||||
# The verdicts that may carry an escalation.
|
||||
Escalating = Interrupt | QuotedAnswer | Unfinished
|
||||
@@ -1,11 +1,15 @@
|
||||
from claude_code.entries import assistant_parts, ends_stream, hit_limit, limit_said, parse_entry, rejected_until
|
||||
from loop_claude.effects import Effects, say
|
||||
import pathlib
|
||||
|
||||
from claude_code.entries import AssistantTurn, ends_stream, entry_from, hit_limit, json_object, limit_said, rejected_until
|
||||
from agent_cycle.lingering_workers import CHECK_EVERY, RECORD, stopped_shells
|
||||
from loop_effects.effects import Effects, say
|
||||
from failure import Failure
|
||||
from claude_code.reply import Limited
|
||||
from claude_code.transcript import part_line
|
||||
from machine_load.memory import ROOM_SHARE
|
||||
from model_routing.ladder import Rung
|
||||
from claude_code.session import Session
|
||||
from agent_cycle.stuck_workers import Watch
|
||||
|
||||
PRINTED_TOOL_INPUT = 160
|
||||
# Seconds between reads of the machine's memory while too little of it is available to start a worker.
|
||||
@@ -15,23 +19,39 @@ AUTO_COMPACT_WINDOW = "CLAUDE_CODE_AUTO_COMPACT_WINDOW"
|
||||
COMPACT_WINDOW = 200_000
|
||||
|
||||
|
||||
def run_worker(root: str, args: list[str], env: dict[str, str], effects: Effects) -> Failure | Limited | None:
|
||||
def run_worker(root: str, args: list[str], env: dict[str, str], project_archive: pathlib.Path, investigator: Rung, effects: Effects) -> Failure | Limited | None:
|
||||
"""Runs the worker's claude once the machine has room for it, as run_claude does with a Watch whose stuck checks run on investigator, the project's rung."""
|
||||
wait_for_memory(effects)
|
||||
return run_claude(root, args, env, effects, Watch(investigator, project_archive))
|
||||
|
||||
|
||||
def run_claude(root: str, args: list[str], env: dict[str, str], effects: Effects, watch: Watch | None = None) -> Failure | Limited | None:
|
||||
"""Runs a headless claude at once, printing what it says, and returns how it failed, or None. Where watch is given, a claude that lingers after its final result loses its quiet shells, as `lingering_workers.stopped_shells` says, each stop appended to RECORD in watch's archive; and a silent claude that has printed no result is checked for stuck shells, as `stuck_workers` says."""
|
||||
try:
|
||||
proc = effects.stream_claude(args, root, env)
|
||||
except OSError as failure:
|
||||
return Failure(f"could not start claude: {failure.strerror}")
|
||||
result: dict | None = None
|
||||
# Whether the worker's latest line is its result; a worker that prints on is working.
|
||||
printed_result = False
|
||||
resets: list[int] = []
|
||||
for raw in proc.lines():
|
||||
event = parse_entry(raw) or {}
|
||||
if ends_stream(event):
|
||||
for raw in proc.lines(CHECK_EVERY):
|
||||
if raw is None:
|
||||
if watch is not None:
|
||||
stopped_shells(proc, printed_result, watch.archive / RECORD, effects)
|
||||
if not printed_result:
|
||||
watch.check(proc, root, effects)
|
||||
continue
|
||||
event = json_object(raw) or {}
|
||||
printed_result = ends_stream(event)
|
||||
if printed_result:
|
||||
result = event
|
||||
if (resets_at := rejected_until(event)) is not None:
|
||||
resets.append(resets_at)
|
||||
for part in assistant_parts(event):
|
||||
if line := part_line(part, PRINTED_TOOL_INPUT):
|
||||
say(line, effects, stdout=True)
|
||||
if isinstance(turn := entry_from(event), AssistantTurn):
|
||||
for part in turn.parts:
|
||||
if line := part_line(part, PRINTED_TOOL_INPUT):
|
||||
say(line, effects, stdout=True)
|
||||
return worker_outcome(proc.wait(), result, resets)
|
||||
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
"""A worker's prompts: those the entry point driving the cycle words, and those that resume a worker with an answer to its question.
|
||||
|
||||
An entry point is a tool that drives cycles, such as loop-claude. It words the prompts of its own workflow and names the files of its project. WorkerPrompts holds those, so the cycle doesn't import an entry point to word a prompt.
|
||||
"""
|
||||
import dataclasses
|
||||
import re
|
||||
import typing
|
||||
|
||||
from model_routing.ladder import ProjectRung
|
||||
from model_routing.route import Route
|
||||
from claude_code.transcript import Typed
|
||||
|
||||
# Opens typed's prompt, with the answer on the line after it, so typed_answer finds the answer at the prompt's start, whatever the question holds.
|
||||
TYPED_HERE = "The human answered your question at {driver}'s terminal:"
|
||||
# Finds TYPED_HERE whatever the driver, so a transcript reads the same to every tool that renders it.
|
||||
TYPED_OPENING = re.compile(re.escape(TYPED_HERE).replace(re.escape("{driver}"), r"[\w-]+") + "\n")
|
||||
|
||||
|
||||
def answers_recorded(destinations: str) -> str:
|
||||
"""What a chunk owes each answer the human typed, before it is finished. destinations names where an answer may be recorded."""
|
||||
return f"every answer the human typed in it that a later chunk could need is recorded in {destinations} at the one place it governs"
|
||||
|
||||
|
||||
def typed_answer(prompt: str) -> Typed | None:
|
||||
"""Splits a prompt from WorkerPrompts.typed into its answer and the rest, so the judge reads the answer as the human's; None for any other prompt."""
|
||||
opening = TYPED_OPENING.match(prompt)
|
||||
if not opening:
|
||||
return None
|
||||
answer, _, rest = prompt[opening.end():].partition("\n\n")
|
||||
return Typed(rest, answer)
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class WorkerPrompts:
|
||||
"""What an entry point supplies to the prompts of its cycles."""
|
||||
# The entry point's name as the worker, the judge and the human read it, such as `do-epic`.
|
||||
driver: str
|
||||
# The prompt that starts a worker, from its task, the premises, its route, the project's rung and the facts found before the cycle.
|
||||
fresh: typing.Callable[[str, str, Route, ProjectRung | None, str], str]
|
||||
# The prompt that resumes a worker whose previous run ended before the chunk was finished, from the evidence of the unfinished verdict, if there was one.
|
||||
resumed: typing.Callable[[str, Route, ProjectRung | None], str]
|
||||
# The sentences that depend on the worker's rung, each after a space, to follow the sentence a prompt ends on.
|
||||
rungs_held: typing.Callable[[Route, ProjectRung | None], str]
|
||||
# Where the judge may quote an answer from, named as the human and the worker see them.
|
||||
quote_sources: str
|
||||
# Where the worker may record an answer the human typed.
|
||||
answer_destinations: str
|
||||
# What the records the judge reads are, in the order it reads them.
|
||||
records_named: str
|
||||
|
||||
def answered(self, question: str, answer: str, route: Route, project: ProjectRung | None, stepped: bool) -> str:
|
||||
"""stepped is whether the answer's ruling stepped the worker up."""
|
||||
return f"Your question: {question}\n\n{self.quote_sources} answers it:\n\n{answer}\n\nContinue the task.{self.stepped_to(route, project, stepped)}"
|
||||
|
||||
def typed(self, question: str, answer: str, route: Route, project: ProjectRung | None, stepped: bool) -> str:
|
||||
"""The prompt that resumes the worker with the human's answer to an interrupt. answer is one line, as the terminal reads it."""
|
||||
return f"{TYPED_HERE.format(driver=self.driver)}\n{answer}\n\nYour question was: {question}\n\nContinue the task. The chunk is finished only once {answers_recorded(self.answer_destinations)}.{self.stepped_to(route, project, stepped)}"
|
||||
|
||||
def stepped_to(self, route: Route, project: ProjectRung | None, stepped: bool) -> str:
|
||||
"""The sentences naming the worker's new rung, as resumed has them, where the ruling that brought the answer stepped the worker up; empty otherwise."""
|
||||
return f" Your request for a higher rung went through: {self.driver} runs you on {route.rung}. The escalation triggers that fired before this step are spent.{self.rungs_held(route, project)}" if stepped else ""
|
||||
|
||||
def past_the_cap(self, question: str, answer: str, cap: int) -> str:
|
||||
"""The question a quoted answer puts to the human once the cycle's quoted answers reach the cap."""
|
||||
return f"{question}\n\n{self.quote_sources} says:\n{answer}\n\nThose files have answered {cap} questions this cycle, the most allowed, so this one comes to you."
|
||||
@@ -0,0 +1,51 @@
|
||||
"""What the Jira and Confluence backends share: one Atlassian account's credentials, the request both backends send, and each service's error messages."""
|
||||
import base64
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from failure import Failure
|
||||
from rest_client import json_request
|
||||
from rest_client.env_file import read_env
|
||||
from adf_codec.convert import Refused
|
||||
|
||||
# One pair of keys for Jira and Confluence: one Atlassian account's API token opens both.
|
||||
KEYS = ("ATLASSIAN_EMAIL", "ATLASSIAN_API_TOKEN")
|
||||
# Seconds each connect and each read may wait.
|
||||
TIMEOUT = 30
|
||||
|
||||
# Sends a request with the Authorization header given, the body as JSON where there is one, and returns the JSON answer, None where the answer has no body, or a Failure saying why there is none.
|
||||
Http = typing.Callable[[str, str, str, object], object]
|
||||
ToMarkdown = typing.Callable[[list[dict[str, typing.Any]]], list[str] | Refused | Failure]
|
||||
ToAdf = typing.Callable[[str], dict[str, typing.Any] | Failure]
|
||||
|
||||
|
||||
def basic_auth(env_file: pathlib.Path) -> str | Failure:
|
||||
"""The Authorization header for the email and API token that env_file holds."""
|
||||
values = read_env(env_file, KEYS, "an API token")
|
||||
if isinstance(values, Failure):
|
||||
return values
|
||||
return "Basic " + base64.b64encode(":".join(values[key] for key in KEYS).encode()).decode()
|
||||
|
||||
|
||||
def jira_json(method: str, url: str, authorization: str, body: object) -> object:
|
||||
return json_request.http_json(method, url, authorization, body, TIMEOUT, jira_errors)
|
||||
|
||||
|
||||
def jira_errors(answer: object) -> str:
|
||||
"""Jira's messages in the JSON of an error answer; empty where it holds none."""
|
||||
if not isinstance(answer, dict):
|
||||
return ""
|
||||
messages, errors = answer.get("errorMessages"), answer.get("errors")
|
||||
found = [*(messages if isinstance(messages, list) else []), *(errors.values() if isinstance(errors, dict) else [])]
|
||||
return "; ".join(text for text in found if isinstance(text, str))
|
||||
|
||||
|
||||
def confluence_json(method: str, url: str, authorization: str, body: object) -> object:
|
||||
return json_request.http_json(method, url, authorization, body, TIMEOUT, confluence_errors)
|
||||
|
||||
|
||||
def confluence_errors(answer: object) -> str:
|
||||
"""Confluence's messages in the JSON of an error answer; empty where it holds none."""
|
||||
errors = answer.get("errors") if isinstance(answer, dict) else None
|
||||
found = [error.get("title") for error in errors if isinstance(error, dict)] if isinstance(errors, list) else [answer.get("message")] if isinstance(answer, dict) else []
|
||||
return "; ".join(text for text in found if isinstance(text, str))
|
||||
@@ -0,0 +1,204 @@
|
||||
"""What every reader of Jira Cloud's REST API version 3 shares: a search read page by page, the key, fields, "is blocked by" links and property of each issue it finds, checked for their shape, and the transition that finishes an issue."""
|
||||
import dataclasses
|
||||
import re
|
||||
import typing
|
||||
|
||||
from failure import Failure
|
||||
from project_config.settings import Finish, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION
|
||||
from atlassian.client import Http
|
||||
from text_files.markdown_text import listed
|
||||
|
||||
ISSUE_KEY = re.compile(r"([A-Z][A-Z0-9_]*)-([0-9]+)")
|
||||
PAGE = 100
|
||||
# The pages one read asks for at most, so an answer that never names a last page ends the read.
|
||||
MAX_PAGES = 100
|
||||
# The key of the status category Jira Cloud gives every done status.
|
||||
DONE = "done"
|
||||
# The hierarchyLevel of the epic issue type in the issue types Jira lists.
|
||||
EPIC_LEVEL = 1
|
||||
# How a Failure names an answer in which a field is missing or of another type.
|
||||
SHAPE = "is not in the shape Jira Cloud's REST API version 3 documents"
|
||||
# What a failed create ends with: a request Jira never answered, or answered brokenly, may still have filed the issue.
|
||||
PERHAPS_FILED = "unless Jira refused the request, the issue may exist: look under {under} before filing it again"
|
||||
# What a failed move ends with, for the same reason.
|
||||
PERHAPS_MOVED = "unless Jira refused the request, the issue may have moved: look at {key} before finishing the item again"
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Link:
|
||||
"""One "is blocked by" link of an issue."""
|
||||
# The key of the issue that blocks.
|
||||
blocker: str
|
||||
# The link's own id, which Jira deletes it by.
|
||||
id: str
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Entry:
|
||||
"""The key, fields, links and property of one issue a search finds, which every reader checks alike."""
|
||||
key: str
|
||||
# The entry's `fields`, from which each reader takes the ones it asked for.
|
||||
fields: dict[str, typing.Any]
|
||||
links: tuple[Link, ...]
|
||||
# The issue property the search asked for; empty where the issue has none. A reader checks that it is a JSON object.
|
||||
held: object
|
||||
|
||||
|
||||
def entry_of(raw: object, property_: str) -> Entry | Failure:
|
||||
"""The Entry of one issue a search finds, or which issue is not in the shape Jira documents, and how. property_ names the issue property the search asked for."""
|
||||
key = raw.get("key") if isinstance(raw, dict) else None
|
||||
if not isinstance(raw, dict) or not isinstance(key, str) or not ISSUE_KEY.fullmatch(key):
|
||||
return Failure("the search answered an issue without an issue key")
|
||||
# Each nested field is checked as Jira documents it; one missing or of another type ends the read here, as a Failure, so no later step meets it.
|
||||
fields, properties = raw.get("fields"), raw.get("properties", {})
|
||||
if not isinstance(fields, dict):
|
||||
return Failure(f"{key} {SHAPE}: its fields are no object")
|
||||
if not isinstance(properties, dict):
|
||||
return Failure(f"{key} {SHAPE}: its properties are no object")
|
||||
links = blocked_by_links(fields)
|
||||
if isinstance(links, Failure):
|
||||
return Failure(f"{key} {SHAPE}: {links.reason}")
|
||||
return Entry(key, fields, links, properties.get(property_, {}))
|
||||
|
||||
|
||||
def unshaped(key: str, failure: Exception) -> str:
|
||||
"""Why the issue named key cannot be read, for a field that is missing or of another type than Jira documents."""
|
||||
return f"{key} {SHAPE}: {failure!r}"
|
||||
|
||||
|
||||
def offer_of(raw: object) -> tuple[str, str, str, str] | None:
|
||||
"""One transition Jira offers, as its ID, its name, the name of the status it leads to and the key of that status's category; None where raw holds no such transition."""
|
||||
to = raw.get("to") if isinstance(raw, dict) else None
|
||||
category = to.get("statusCategory") if isinstance(to, dict) else None
|
||||
if not isinstance(raw, dict) or not isinstance(to, dict) or not isinstance(category, dict):
|
||||
return None
|
||||
id_, name, status, key = raw.get("id"), raw.get("name"), to.get("name"), category.get("key")
|
||||
return (id_, name, status, key) if isinstance(id_, str) and isinstance(name, str) and isinstance(status, str) and isinstance(key, str) else None
|
||||
|
||||
|
||||
def offers_of(offered: object, key: str) -> list[tuple[str, str, str, str]] | Failure:
|
||||
"""The transitions Jira offers the issue named key from its present status, each as offer_of answers one. A Failure where offered, Jira's answer, is in another shape."""
|
||||
raw = offered.get("transitions") if isinstance(offered, dict) else None
|
||||
found = [offer for each in raw if (offer := offer_of(each))] if isinstance(raw, list) else []
|
||||
if not isinstance(raw, list) or len(found) != len(raw):
|
||||
return Failure(f"Jira answered {key}'s transitions in a shape other than the one it documents")
|
||||
return found
|
||||
|
||||
|
||||
def status_category(issue: object) -> str | Failure:
|
||||
"""The key of the category of the status in Jira's answer about one issue, or how the answer is not in the shape Jira documents."""
|
||||
fields = issue.get("fields") if isinstance(issue, dict) else None
|
||||
status = fields.get("status") if isinstance(fields, dict) else None
|
||||
category = status.get("statusCategory") if isinstance(status, dict) else None
|
||||
key = category.get("key") if isinstance(category, dict) else None
|
||||
return key if isinstance(key, str) else Failure("its status category has no key that is text")
|
||||
|
||||
|
||||
def finishing_transition(site: str, key: str, finish: Finish, authorization: str, http: Http) -> str | Failure:
|
||||
"""The ID of the transition finish names, as Jira offers it now for the issue named key, which is a plan item or an epic; or why none of those offered finishes it."""
|
||||
offered = http("GET", f"{site}/rest/api/3/issue/{key}/transitions", authorization, None)
|
||||
if isinstance(offered, Failure):
|
||||
return Failure(f"cannot read {key}'s transitions: {offered.reason}")
|
||||
return transition_of(offered, key, finish)
|
||||
|
||||
|
||||
def move_refusal(site: str, key: str, transition: str, finish: Finish, authorization: str, http: Http) -> str | None:
|
||||
"""Moves the issue named key by the transition with the ID transition, which finishing_transition answered for finish. Why Jira did not take the move; None where it did."""
|
||||
moved = http("POST", f"{site}/rest/api/3/issue/{key}/transitions", authorization, {"transition": {"id": transition}})
|
||||
return f"cannot move {key} by {finish.transition!r}: {moved.reason}" if isinstance(moved, Failure) else None
|
||||
|
||||
|
||||
def transition_of(offered: object, key: str, finish: Finish) -> str | Failure:
|
||||
"""The ID of the transition finish names, among those Jira offered for the issue named key, which are the ones its present status has; or why none of them finishes the item."""
|
||||
found = offers_of(offered, key)
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
named = [each for each in found if each[1] == finish.transition]
|
||||
if not named:
|
||||
others = " and ".join(f"{name!r} to {status!r}" for _, name, status, _ in found)
|
||||
return Failure(f"{key} has no transition {finish.transition!r} from its status, " + (f"only {others}: move the issue in Jira to a status that has it, or name in `{JIRA_FINISH_TRANSITION}` one that leads to a done status" if found else "nor any other the account may make"))
|
||||
id_, _, status, category = next((each for each in named if each[2] == finish.status), named[0])
|
||||
if status != finish.status:
|
||||
return Failure(f"{key}'s transition {finish.transition!r} leads to the status {status!r}, not to {finish.status!r}, which `{JIRA_FINISH_STATUS}` names")
|
||||
# `children` reads an issue as finished by its status's category, so a move to any other category would leave the item in the plan.
|
||||
if category != DONE:
|
||||
return Failure(f"{key}'s transition {finish.transition!r} leads to the status {status!r}, which Jira doesn't count as done, so the item would stay in the plan: name a transition to a done status")
|
||||
return id_
|
||||
|
||||
|
||||
def issue_types_of(site: str, project: str, authorization: str, http: Http) -> list[dict[str, typing.Any]] | Failure:
|
||||
"""The issue types Jira lists for the project, each with a name, or why it listed none."""
|
||||
answered = http("GET", f"{site}/rest/api/3/issue/createmeta/{project}/issuetypes", authorization, None)
|
||||
if isinstance(answered, Failure):
|
||||
return Failure(f"cannot read {project}'s issue types: {answered.reason}")
|
||||
types = answered.get("issueTypes") if isinstance(answered, dict) else None
|
||||
if not isinstance(types, list) or not all(isinstance(each, dict) and isinstance(each.get("name"), str) for each in types):
|
||||
return Failure(f"Jira answered {project}'s issue types in a shape its REST API version 3 doesn't document")
|
||||
return types
|
||||
|
||||
|
||||
def issue_type_refusal(site: str, project: str, kind: str, setting: str, authorization: str, http: Http) -> str | None:
|
||||
"""Why the project can't file a new issue under an epic as the type named kind, which the setting `setting` names; None where it can."""
|
||||
types = issue_types_of(site, project, authorization, http)
|
||||
if isinstance(types, Failure):
|
||||
return types.reason
|
||||
# An issue under an epic is a standard one: Jira refuses a sub-task there, and an epic under an epic.
|
||||
names: list[str] = [each["name"] for each in types if each.get("subtask") is not True and each.get("hierarchyLevel") != EPIC_LEVEL]
|
||||
if kind in names:
|
||||
return None
|
||||
return f"{project} has no issue type {kind!r} for an issue under an epic; " + (f"it has {listed(names, 'and')}: name one in `{setting}`" if names else "it has no other type for one")
|
||||
|
||||
|
||||
def project_of(key: str) -> str:
|
||||
"""The key of the Jira project an issue key lies in."""
|
||||
return key.rpartition("-")[0]
|
||||
|
||||
|
||||
def rank_refusal(site: str, key: str, before: str, authorization: str, http: Http) -> str | None:
|
||||
"""Ranks the issue named key just before the issue named before; why Jira refused, or None where it didn't. Jira answers a rank it made with no body, and one it refused with an error, or with an entry per issue that holds the errors."""
|
||||
answer = http("PUT", f"{site}/rest/agile/1.0/issue/rank", authorization, {"issues": [key], "rankBeforeIssue": before})
|
||||
if isinstance(answer, Failure):
|
||||
return answer.reason
|
||||
entries = answer.get("entries") if isinstance(answer, dict) else None
|
||||
refused = [entry for entry in entries if isinstance(entry, dict) and entry.get("status") != 200] if isinstance(entries, list) else []
|
||||
return "; ".join(str(error) for entry in refused for error in entry.get("errors") or [f"Jira answered {entry.get('status')}"]) or None
|
||||
|
||||
|
||||
def searched(site: str, what: str, jql: str, asked: dict[str, object], authorization: str, http: Http, max_pages: int = MAX_PAGES) -> list[object] | Failure:
|
||||
"""Every issue a JQL search on site finds, page by page, up to max_pages pages. The dict asked holds the request's `fields` and `properties` lists. The text what names the issues sought, in the Failure of a search that doesn't end."""
|
||||
body: dict[str, object] = {"jql": jql, "maxResults": PAGE} | asked
|
||||
found: list[object] = []
|
||||
for _ in range(max_pages):
|
||||
page = http("POST", f"{site}/rest/api/3/search/jql", authorization, body)
|
||||
if isinstance(page, Failure):
|
||||
return page
|
||||
if not isinstance(page, dict) or not isinstance(page.get("issues"), list):
|
||||
return Failure("the search answered something other than a page of issues")
|
||||
found += page["issues"]
|
||||
if not page.get("nextPageToken"):
|
||||
return found
|
||||
body = body | {"nextPageToken": page["nextPageToken"]}
|
||||
return Failure(f"the search for {what} did not end within {max_pages} pages")
|
||||
|
||||
|
||||
def blocked_by_links(fields: dict[str, typing.Any]) -> tuple[Link, ...] | Failure:
|
||||
"""The "is blocked by" links among an issue's `issuelinks` field, or how that field is not in the shape Jira documents."""
|
||||
listed = fields.get("issuelinks")
|
||||
if not isinstance(listed, list):
|
||||
return Failure("its issuelinks are no list")
|
||||
found = []
|
||||
for link in listed:
|
||||
if not isinstance(link, dict):
|
||||
return Failure("its issuelinks hold a link that is no object")
|
||||
if "inwardIssue" not in link:
|
||||
continue
|
||||
kind = link.get("type")
|
||||
if not isinstance(kind, dict) or not isinstance(kind.get("inward"), str):
|
||||
return Failure("its issuelinks hold a link whose type names no inward text")
|
||||
if kind["inward"] != "is blocked by":
|
||||
continue
|
||||
blocker, id_ = link["inwardIssue"], link.get("id")
|
||||
if not isinstance(blocker, dict) or not isinstance(blocker.get("key"), str) or not isinstance(id_, str):
|
||||
return Failure("its issuelinks hold a link whose id or whose linked issue's key is no text")
|
||||
found.append(Link(blocker["key"], id_))
|
||||
return tuple(found)
|
||||
@@ -0,0 +1,65 @@
|
||||
import base64
|
||||
import json
|
||||
import pathlib
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from atlassian import client
|
||||
from rest_client.json_request import ErrorAnswer
|
||||
from failure import Failure
|
||||
from rest_client.doubles import Served
|
||||
|
||||
AUTHORIZATION = "Basic " + base64.b64encode(b"me@example.com:s3cret").decode()
|
||||
|
||||
|
||||
class Credentials(unittest.TestCase):
|
||||
def test_builds_basic_auth_from_the_env_files_email_and_token(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
env = pathlib.Path(temp, "acme.env")
|
||||
env.write_text("ATLASSIAN_EMAIL=me@example.com\nATLASSIAN_API_TOKEN=s3cret\n")
|
||||
env.chmod(0o600)
|
||||
self.assertEqual(client.basic_auth(env), AUTHORIZATION)
|
||||
|
||||
def test_a_missing_env_file_fails(self):
|
||||
self.assertIsInstance(client.basic_auth(pathlib.Path("/nonexistent/acme.env")), Failure)
|
||||
|
||||
|
||||
class Jira(Served):
|
||||
def test_an_error_answer_fails_with_jiras_messages_and_its_status(self):
|
||||
base = self.serve((400, b'{"errorMessages": ["One."], "errors": {"jql": "Two."}}'))
|
||||
self.assertEqual(client.jira_json("POST", f"{base}/rest/api/3/search/jql", AUTHORIZATION, {"jql": "x"}), ErrorAnswer("POST /rest/api/3/search/jql answered 400: One.; Two.", 400))
|
||||
[(_, _, headers, body)] = self.server.got # type: ignore[attr-defined]
|
||||
self.assertEqual((headers["Authorization"], json.loads(body)), (AUTHORIZATION, {"jql": "x"}))
|
||||
|
||||
def test_reads_jiras_messages_from_an_error_answer(self):
|
||||
cases = (
|
||||
({"errorMessages": ["Issue does not exist or you do not have permission to see it."], "errors": {}}, "Issue does not exist or you do not have permission to see it."),
|
||||
({"errorMessages": ["One."], "errors": {"jql": "Two."}}, "One.; Two."),
|
||||
({"errorMessages": "One.", "errors": ["Two."]}, ""),
|
||||
({"errorMessages": [7, "One."]}, "One."),
|
||||
(["One."], ""),
|
||||
)
|
||||
for answer, message in cases:
|
||||
with self.subTest(answer=answer):
|
||||
self.assertEqual(client.jira_errors(answer), message)
|
||||
|
||||
|
||||
class Confluence(Served):
|
||||
def test_an_error_answer_fails_with_confluences_messages_and_its_status(self):
|
||||
base = self.serve((409, b'{"errors": [{"status": 409, "title": "Version must be incremented"}]}'))
|
||||
self.assertEqual(client.confluence_json("PUT", f"{base}/wiki/api/v2/pages/1", AUTHORIZATION, {"version": {"number": 2}}), ErrorAnswer("PUT /wiki/api/v2/pages/1 answered 409: Version must be incremented", 409))
|
||||
[(_, _, headers, body)] = self.server.got # type: ignore[attr-defined]
|
||||
self.assertEqual((headers["Authorization"], json.loads(body)), (AUTHORIZATION, {"version": {"number": 2}}))
|
||||
|
||||
def test_reads_confluences_messages_from_an_error_answer(self):
|
||||
self.assertEqual(client.confluence_errors({"errors": [{"status": 409, "title": "Version must be incremented"}, {"title": "and more"}, "odd"]}), "Version must be incremented; and more")
|
||||
self.assertEqual(client.confluence_errors({"message": "Not Found"}), "Not Found")
|
||||
self.assertEqual(client.confluence_errors({"errors": "odd"}), "")
|
||||
self.assertEqual(client.confluence_errors(["odd"]), "")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,111 @@
|
||||
import pathlib
|
||||
import sys
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from atlassian.jira import Entry, entry_of, Link
|
||||
from failure import Failure
|
||||
from atlassian import jira
|
||||
|
||||
BLOCKED = {"id": "9", "type": {"inward": "is blocked by"}, "inwardIssue": {"key": "ABC-2"}}
|
||||
SHAPE = "ABC-1 is not in the shape Jira Cloud's REST API version 3 documents: "
|
||||
|
||||
|
||||
def raw(*links: object, **more: object) -> dict[str, object]:
|
||||
return {"key": "ABC-1", "fields": {"issuelinks": list(links)}} | more
|
||||
|
||||
|
||||
class TheHeadOfAnEntry(unittest.TestCase):
|
||||
def test_holds_the_key_the_fields_the_blocked_by_links_and_the_property_asked_for(self):
|
||||
outward = {"id": "3", "type": {"inward": "is blocked by"}, "outwardIssue": {"key": "ABC-3"}}
|
||||
relates = {"id": "4", "type": {"inward": "relates to"}, "inwardIssue": {"key": "ABC-4"}}
|
||||
found = entry_of(raw(BLOCKED, outward, relates, properties={"plan": {"L": 2}}), "plan")
|
||||
self.assertEqual(found, Entry("ABC-1", {"issuelinks": [BLOCKED, outward, relates]}, (Link("ABC-2", "9"),), {"L": 2}))
|
||||
self.assertEqual(entry_of(raw(), "plan"), Entry("ABC-1", {"issuelinks": []}, (), {}))
|
||||
|
||||
def test_finds_a_blocked_by_link_listed_after_a_link_of_another_kind(self):
|
||||
outward = {"id": "3", "type": {"inward": "is blocked by"}, "outwardIssue": {"key": "ABC-3"}}
|
||||
relates = {"id": "4", "type": {"inward": "relates to"}, "inwardIssue": {"key": "ABC-4"}}
|
||||
for other in (outward, relates):
|
||||
with self.subTest(other=other):
|
||||
self.assertEqual(jira.blocked_by_links({"issuelinks": [other, BLOCKED]}), (Link("ABC-2", "9"),))
|
||||
|
||||
def test_an_entry_without_an_issue_key_is_a_failure(self):
|
||||
for wrong in ([], {}, {"key": 7}, {"key": "abc"}):
|
||||
with self.subTest(wrong=wrong):
|
||||
self.assertEqual(entry_of(wrong, "plan"), Failure("the search answered an issue without an issue key"))
|
||||
|
||||
def test_an_entry_in_another_shape_is_a_failure_naming_the_issue_and_the_field(self):
|
||||
cases = {
|
||||
"its fields are no object": {"key": "ABC-1"},
|
||||
"its properties are no object": raw(properties=[]),
|
||||
"its issuelinks are no list": {"key": "ABC-1", "fields": {}},
|
||||
"its issuelinks hold a link that is no object": raw("link"),
|
||||
"its issuelinks hold a link whose type names no inward text": raw(BLOCKED | {"type": None}),
|
||||
"its issuelinks hold a link whose id or whose linked issue's key is no text": raw(BLOCKED | {"inwardIssue": {"key": 7}}),
|
||||
}
|
||||
for how, wrong in cases.items():
|
||||
with self.subTest(how=how):
|
||||
self.assertEqual(entry_of(wrong, "plan"), Failure(SHAPE + how))
|
||||
self.assertEqual(entry_of(raw(BLOCKED | {"id": 9}), "plan"), Failure(SHAPE + "its issuelinks hold a link whose id or whose linked issue's key is no text"))
|
||||
self.assertEqual(entry_of(raw(BLOCKED | {"inwardIssue": None}), "plan"), Failure(SHAPE + "its issuelinks hold a link whose id or whose linked issue's key is no text"))
|
||||
|
||||
def test_a_fault_in_reading_the_links_is_not_reported_as_jiras(self):
|
||||
class Faulty(dict):
|
||||
def get(self, key, default=None):
|
||||
raise TypeError("ours")
|
||||
|
||||
with self.assertRaisesRegex(TypeError, "ours"):
|
||||
entry_of({"key": "ABC-1", "fields": Faulty()}, "plan")
|
||||
|
||||
|
||||
class TheCategoryOfAnIssuesStatus(unittest.TestCase):
|
||||
def test_is_the_key_jira_gives_the_category(self):
|
||||
self.assertEqual(jira.status_category({"fields": {"status": {"statusCategory": {"key": "done"}}}}), "done")
|
||||
|
||||
def test_an_answer_in_another_shape_is_a_failure_naming_the_field(self):
|
||||
for wrong in (["ABC-1"], {}, {"fields": []}, {"fields": {}}, {"fields": {"status": "Done"}}, {"fields": {"status": {}}}, {"fields": {"status": {"statusCategory": "done"}}}, {"fields": {"status": {"statusCategory": {}}}}, {"fields": {"status": {"statusCategory": {"key": 3}}}}):
|
||||
with self.subTest(wrong=wrong):
|
||||
self.assertEqual(jira.status_category(wrong), Failure("its status category has no key that is text"))
|
||||
|
||||
|
||||
class TheRefusalOfAnIssueType(unittest.TestCase):
|
||||
TYPES = {"issueTypes": [{"name": "Feature", "subtask": False, "hierarchyLevel": 0}, {"name": "Bug", "subtask": False, "hierarchyLevel": 0}, {"name": "Epic", "subtask": False, "hierarchyLevel": 1}, {"name": "Subtask", "subtask": True, "hierarchyLevel": -1}]}
|
||||
|
||||
def refusal(self, kind: str, answer: object) -> str | None:
|
||||
asked: list[tuple[str, str, object]] = []
|
||||
|
||||
def http(method: str, url: str, authorization: str, body: object) -> object:
|
||||
asked.append((method, url, body))
|
||||
return answer
|
||||
|
||||
refused = jira.issue_type_refusal("https://acme.atlassian.net", "ABC", kind, "jira-finding-type", "Basic x", http)
|
||||
self.assertEqual(asked, [("GET", "https://acme.atlassian.net/rest/api/3/issue/createmeta/ABC/issuetypes", None)])
|
||||
return refused
|
||||
|
||||
def test_is_none_where_the_project_has_the_type(self):
|
||||
self.assertIsNone(self.refusal("Bug", self.TYPES))
|
||||
|
||||
def test_names_the_types_the_project_has_and_the_setting_where_it_lacks_the_type(self):
|
||||
self.assertEqual(self.refusal("Task", self.TYPES), "ABC has no issue type 'Task' for an issue under an epic; it has Feature and Bug: name one in `jira-finding-type`")
|
||||
|
||||
def test_a_sub_task_type_and_the_epic_type_are_not_ones_for_an_issue_under_an_epic(self):
|
||||
for kind in ("Subtask", "Epic"):
|
||||
with self.subTest(kind=kind):
|
||||
self.assertEqual(self.refusal(kind, self.TYPES), f"ABC has no issue type {kind!r} for an issue under an epic; it has Feature and Bug: name one in `jira-finding-type`")
|
||||
|
||||
def test_says_the_project_has_no_other_type_where_it_has_only_sub_task_types(self):
|
||||
self.assertEqual(self.refusal("Bug", {"issueTypes": [{"name": "Subtask", "subtask": True}]}), "ABC has no issue type 'Bug' for an issue under an epic; it has no other type for one")
|
||||
|
||||
def test_says_why_where_jira_fails(self):
|
||||
self.assertEqual(self.refusal("Bug", Failure("Jira answered 403")), "cannot read ABC's issue types: Jira answered 403")
|
||||
|
||||
def test_says_so_where_jira_answers_in_another_shape(self):
|
||||
for wrong in ([], {}, {"issueTypes": "Bug"}, {"issueTypes": [{"subtask": False}]}):
|
||||
with self.subTest(wrong=wrong):
|
||||
self.assertEqual(self.refusal("Bug", wrong), "Jira answered ABC's issue types in a shape its REST API version 3 doesn't document")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
+24
-16
@@ -4,9 +4,10 @@ import typing
|
||||
|
||||
from failure import Failure
|
||||
from review_rules.comprehension_history import HISTORY
|
||||
from release_plan.todo_table import Item, items
|
||||
from plan.todo_table import Item, items
|
||||
from reading_cost.figures import RECORD
|
||||
from records.utc_stamp import utc
|
||||
from project_config import templates
|
||||
from text_files.utc_stamp import utc
|
||||
|
||||
# The plan, and the records tools append to: none of their lines are the chunk's work.
|
||||
NOT_WORK = ("todo.md", HISTORY, RECORD)
|
||||
@@ -14,6 +15,8 @@ NOT_WORK = ("todo.md", HISTORY, RECORD)
|
||||
LOG = ("log", "--format=%x00%H %ct %at %P%x1f%h%x1f%s", "--name-only", "--diff-merges=first-parent")
|
||||
# One commit's record in LOG's output, without the NUL that opens it.
|
||||
LOG_RECORD = re.compile(r"([0-9a-f]+) ([0-9]+) ([0-9]+) ([0-9a-f ]*)\x1f([0-9a-f]+)\x1f(.*)", re.DOTALL)
|
||||
# A title opening `Drop item 69: <why>` or `Drop items 69, 70 and 71: <why>` removes those items unbuilt; only at the start, where a log skimmed by its titles shows it.
|
||||
DROP = re.compile(r"Drop items? ([0-9]+(?:, [0-9]+)*(?: and [0-9]+)?):")
|
||||
# How a chunk reached the default branch; rebase and push leave no merge commit to bound it.
|
||||
Landing = typing.Literal["merge", "rebase", "push"]
|
||||
|
||||
@@ -43,7 +46,7 @@ class Span:
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class BranchChunk(Span):
|
||||
"""A Span with two more fields: shipped holds each todo.md item its change removed, as scored before the change; fixed_by names the later chunks that fixed code it shipped, newest first."""
|
||||
"""A Span with two more fields: shipped holds each todo.md item its change removed, as scored before the change, less any item one of its commit titles drops; fixed_by names the later chunks that fixed code it shipped, newest first."""
|
||||
shipped: tuple[Item, ...]
|
||||
fixed_by: tuple[str, ...]
|
||||
|
||||
@@ -56,9 +59,9 @@ class Branch:
|
||||
owner: dict[str, int]
|
||||
|
||||
|
||||
def cut_branch(log: str) -> Branch | Failure:
|
||||
def cut_branch(log: str, titles: templates.Titles) -> Branch | Failure:
|
||||
"""The branch LOG printed, cut into chunks as chunk_log cuts its first-parent line; a commit belongs to the oldest chunk whose commits reach it."""
|
||||
commits = parsed(log)
|
||||
commits = parsed(log, titles)
|
||||
if isinstance(commits, Failure):
|
||||
return commits
|
||||
if not commits:
|
||||
@@ -69,9 +72,9 @@ def cut_branch(log: str) -> Branch | Failure:
|
||||
line.append(commits[line[-1].parents[0]])
|
||||
runs = chunk_log(line)
|
||||
owner = owners(runs, commits)
|
||||
titles: list[list[str]] = [[] for _ in runs]
|
||||
held: list[list[str]] = [[] for _ in runs]
|
||||
for commit in commits.values():
|
||||
titles[owner[commit.hash]].append(commit.title)
|
||||
held[owner[commit.hash]].append(commit.title)
|
||||
spans = []
|
||||
for index, run in enumerate(runs):
|
||||
spans.append(Span(
|
||||
@@ -80,13 +83,13 @@ def cut_branch(log: str) -> Branch | Failure:
|
||||
label=label(run[-1].short, run[0].short),
|
||||
landing=landing(run),
|
||||
merged=utc(run[0].committed),
|
||||
titles=tuple(titles[index]),
|
||||
titles=tuple(held[index]),
|
||||
))
|
||||
return Branch(commits, spans, owner)
|
||||
|
||||
|
||||
def parsed(log: str) -> dict[str, Commit] | Failure:
|
||||
"""Each commit LOG printed, by hash, in the order it printed them."""
|
||||
def parsed(log: str, titles: templates.Titles) -> dict[str, Commit] | Failure:
|
||||
"""Each commit LOG printed, by hash, in the order it printed them, its title read as its summary in titles, the project's title templates. So a round title or a `Drop item` title reads the same in every project."""
|
||||
commits = {}
|
||||
for record in log.split("\x00")[1:]:
|
||||
found = LOG_RECORD.fullmatch(record)
|
||||
@@ -94,7 +97,7 @@ def parsed(log: str) -> dict[str, Commit] | Failure:
|
||||
return Failure(f"git log printed a commit it could not read: {record[:200]!r}")
|
||||
full, committed, authored, parents, short, rest = found.groups()
|
||||
title, *files = rest.split("\n")
|
||||
commits[full] = Commit(full, short, int(committed), int(authored), tuple(parents.split()), title, tuple(name for name in files if name))
|
||||
commits[full] = Commit(full, short, int(committed), int(authored), tuple(parents.split()), titles.summary(title), tuple(name for name in files if name))
|
||||
return commits
|
||||
|
||||
|
||||
@@ -135,15 +138,20 @@ def owners(runs: list[list[Commit]], commits: dict[str, Commit]) -> dict[str, in
|
||||
return owner
|
||||
|
||||
|
||||
def shipped(before: str, after: str) -> list[Item]:
|
||||
"""Each item the todo.md before a change holds and the todo.md after it does not, as scored before; none where either holds no items table it can read."""
|
||||
def shipped(before: str, after: str, titles: tuple[str, ...] = ()) -> list[Item]:
|
||||
"""Each item the todo.md before a change holds and the todo.md after it does not, as scored before, less those a title of the change drops; none where either holds no items table it can read."""
|
||||
planned, left = items(before), items(after)
|
||||
if not isinstance(planned, list) or not isinstance(left, list):
|
||||
return []
|
||||
kept = {item.id for item in left}
|
||||
kept = {item.id for item in left} | dropped(titles)
|
||||
return sorted((item for item in planned if item.id not in kept), key=lambda item: item.id)
|
||||
|
||||
|
||||
def dropped(titles: tuple[str, ...]) -> set[int]:
|
||||
"""The IDs of the items the titles drop, each title opening as DROP reads."""
|
||||
return {int(number) for title in titles if (found := DROP.match(title)) for number in re.findall(r"[0-9]+", found[1])}
|
||||
|
||||
|
||||
def plan_revisions(branch: Branch) -> list[str]:
|
||||
"""The revisions whose todo.md shipped_by needs: for each chunk that brought a commit changing todo.md, other than the branch's oldest chunk, the commit before it and its tip."""
|
||||
changed = sorted({branch.owner[commit.hash] for commit in branch.commits.values() if "todo.md" in commit.files})
|
||||
@@ -156,11 +164,11 @@ def plan_revisions(branch: Branch) -> list[str]:
|
||||
|
||||
|
||||
def shipped_by(branch: Branch, plans: dict[str, str]) -> list[tuple[Item, ...]]:
|
||||
"""The items each of the branch's chunks shipped, in the order of its chunks. plans holds todo.md's text at each revision plan_revisions names. A chunk with a revision plans lacks changed no plan, so it shipped none."""
|
||||
"""The items each of the branch's chunks shipped, in the order of its chunks. plans holds todo.md's text at each revision plan_revisions names. A chunk with a revision plans lacks changed no plan, so it shipped none, nor an item one of its titles drops."""
|
||||
found: list[tuple[Item, ...]] = []
|
||||
for chunk in branch.chunks:
|
||||
if chunk.before is not None and chunk.before in plans and chunk.tip in plans:
|
||||
found.append(tuple(shipped(plans[chunk.before], plans[chunk.tip])))
|
||||
found.append(tuple(shipped(plans[chunk.before], plans[chunk.tip], chunk.titles)))
|
||||
else:
|
||||
found.append(())
|
||||
return found
|
||||
|
||||
@@ -5,11 +5,11 @@ import re
|
||||
import typing
|
||||
|
||||
from branch_chunks.cut import Branch, BranchChunk, NOT_WORK
|
||||
from release_plan.todo_table import Item
|
||||
from plan.todo_table import Exempt, Item
|
||||
from review_rules.round_titles import title_counts
|
||||
|
||||
# The Exempt cells, per ~/.claude/rules/todo-items.md, that mark an item fixing a defect.
|
||||
FIXES = ("defect", "security")
|
||||
FIXES: tuple[Exempt, ...] = ("defect", "security")
|
||||
HUNK = re.compile(r"@@ -([0-9]+)(?:,([0-9]+))? \+[0-9]+(?:,([0-9]+))? @@")
|
||||
BLAME_HEADER = re.compile(r"([0-9a-f]{40}|[0-9a-f]{64}) [0-9]+ [0-9]+")
|
||||
|
||||
|
||||
@@ -1,18 +1,47 @@
|
||||
import pathlib
|
||||
|
||||
from branch_chunks.fixes import blamed, fixing_changes, FixingChange, removed_work, Traced, with_fixes
|
||||
from branch_chunks.cut import BranchChunk, cut_branch, LOG, plan_revisions, shipped_by
|
||||
from branch_chunks.cut import BranchChunk, cut_branch, LOG, NOT_WORK, plan_revisions, shipped_by
|
||||
from failure import Failure
|
||||
from git_cli.git_repo import Run, text_at
|
||||
from git_cli.git_repo import git, Git, text_at
|
||||
from project_config.main import located
|
||||
from project_config.settings import ProjectConfig
|
||||
from record_store.stores import store
|
||||
from project_config import templates
|
||||
|
||||
|
||||
def branch_chunks(default: str, run: Run) -> list[BranchChunk] | Failure:
|
||||
# Where branch_chunks reads the plan and the records, by the setting that names each in a project's config.
|
||||
READ_AT = {"plan": NOT_WORK[0], "comprehension-history": NOT_WORK[1], "reading-cost": NOT_WORK[2]}
|
||||
|
||||
|
||||
def unsupported(checkout: str | None, home: pathlib.Path, run: Git = git) -> str | None:
|
||||
"""Why branch_chunks cannot tell what the chunks of checkout's project shipped, else the current directory's: its config under home puts the plan or a record where their commits are not read. None where it can, as for a checkout no config names."""
|
||||
config = located(checkout, home, run)
|
||||
if isinstance(config, Failure):
|
||||
return None
|
||||
elsewhere = [label for name, path in READ_AT.items() for label, tracked in [held(config, name)] if tracked != path]
|
||||
if not elsewhere:
|
||||
return None
|
||||
return f"the project's config puts {', '.join(elsewhere)} elsewhere than {', '.join(READ_AT.values())} in the checkout, the only paths whose commits are read so far"
|
||||
|
||||
|
||||
def held(config: ProjectConfig, name: str) -> tuple[str, str | None]:
|
||||
"""What a message calls the plan or the record that setting name names in config, and its path from the checkout's top, None where it is kept elsewhere."""
|
||||
if name == "plan":
|
||||
return config.plan_label, config.tracked(name)
|
||||
record = store(config, name)
|
||||
return record.label, record.tracked
|
||||
|
||||
|
||||
def branch_chunks(default: str, run: Git, titles: templates.Titles) -> list[BranchChunk] | Failure:
|
||||
"""Each chunk on the default branch's first-parent line, newest first, with the todo.md items it shipped and the later chunks that fixed code it shipped.
|
||||
|
||||
run must run git in the checkout's top: the diff names each path from the top, while blame and a pathspec read a path from the current directory."""
|
||||
titles holds the project's title templates, which each commit's title is read through. run must run git in the checkout's top: the diff names each path from the top, while blame and a pathspec read a path from the current directory."""
|
||||
# The -- keeps a file named like the branch from making it ambiguous.
|
||||
log = run(*LOG, default, "--")
|
||||
if isinstance(log, Failure):
|
||||
return log
|
||||
branch = cut_branch(log)
|
||||
branch = cut_branch(log, titles)
|
||||
if isinstance(branch, Failure):
|
||||
return branch
|
||||
plans = plans_at(plan_revisions(branch), run)
|
||||
@@ -23,7 +52,7 @@ def branch_chunks(default: str, run: Run) -> list[BranchChunk] | Failure:
|
||||
return traced if isinstance(traced, Failure) else with_fixes(branch, shipped, traced)
|
||||
|
||||
|
||||
def plans_at(revisions: list[str], run: Run) -> dict[str, str] | Failure:
|
||||
def plans_at(revisions: list[str], run: Git) -> dict[str, str] | Failure:
|
||||
"""todo.md's text at each revision, empty where the revision holds none."""
|
||||
plans = {}
|
||||
for revision in revisions:
|
||||
@@ -34,7 +63,7 @@ def plans_at(revisions: list[str], run: Run) -> dict[str, str] | Failure:
|
||||
return plans
|
||||
|
||||
|
||||
def traces(changes: list[FixingChange], run: Run) -> list[Traced] | Failure:
|
||||
def traces(changes: list[FixingChange], run: Git) -> list[Traced] | Failure:
|
||||
"""The commits traced_to traces for each change."""
|
||||
found = []
|
||||
for change in changes:
|
||||
@@ -45,7 +74,7 @@ def traces(changes: list[FixingChange], run: Run) -> list[Traced] | Failure:
|
||||
return found
|
||||
|
||||
|
||||
def traced_to(before: str, tip: str, run: Run) -> set[str] | Failure:
|
||||
def traced_to(before: str, tip: str, run: Git) -> set[str] | Failure:
|
||||
"""The commits that last changed each line of a chunk's work that the change from before to tip removes or rewrites."""
|
||||
# The prefixes and options keep the checkout's diff config out of the output. Only hunk headers, paths and commits are read, so a file's text that is not UTF-8 is replaced.
|
||||
diff = run("diff", "-U0", "--inter-hunk-context=0", "-M", "--no-color", "--no-ext-diff", "--no-textconv", "--ignore-submodules", "--src-prefix=a/", "--dst-prefix=b/", before, tip, errors="replace")
|
||||
|
||||
@@ -5,17 +5,18 @@ import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
import unittest.mock
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from project_config.templates import BARE, Titles
|
||||
from branch_chunks.fixes import blamed, fixing_changes, removed, removed_work, Traced, with_fixes
|
||||
from branch_chunks.cut import Branch, chunk_log, Commit, cut_branch, landing, NOT_WORK, shipped, Span
|
||||
from branch_chunks.read import branch_chunks, traced_to
|
||||
from branch_chunks.read import branch_chunks, traced_to, unsupported
|
||||
from project_config.doubles import configured
|
||||
from failure import Failure
|
||||
from git_cli.git_repo import git
|
||||
from test_env import isolated_env
|
||||
from release_plan.todo_table import Item
|
||||
from plan.todo_table import Item
|
||||
|
||||
HEADER = "| ID | Release | Exempt | Item | R | S | C | A | G | Goals | Score |\n|---|---|---|---|---|---|---|---|---|---|---|\n"
|
||||
WITHOUT_C = "| ID | Release | Exempt | Item | R | S | A | G | Goals | Score |\n|---|---|---|---|---|---|---|---|---|---|\n"
|
||||
@@ -57,6 +58,18 @@ class Shipped(unittest.TestCase):
|
||||
older = "| 4 | 0.1.0 | | **A \\| B.** | 2 | 3 | 6 | 7 | 1 | 9.0 |"
|
||||
self.assertEqual(shipped(todo(older, header=WITHOUT_C), todo(header=WITHOUT_C))[0].scores, {"R": 2, "S": 3, "A": 6, "G": 7})
|
||||
|
||||
def test_leaves_out_each_item_a_title_opening_drop_item_names(self):
|
||||
third = "| 7 | 0.1.0 | | **And that.** | 4 | 6 | 8 | 6 | 7 | 1 | 9.0 |"
|
||||
eighth = "| 8 | 0.1.0 | | **Or this.** | 4 | 6 | 8 | 6 | 7 | 1 | 9.0 |"
|
||||
before = todo(FIRST, SECOND, third, eighth)
|
||||
self.assertEqual([found.id for found in shipped(before, todo(), ("Build item 4", "Drop item 5: item 4 covers it"))], [4, 7, 8])
|
||||
self.assertEqual([found.id for found in shipped(before, todo(), ("Drop items 5, 7 and 8: moot",))], [4])
|
||||
self.assertEqual([found.id for found in shipped(before, todo(), ("Drop items 5 and 7: moot",))], [4, 8])
|
||||
|
||||
def test_ships_an_item_a_title_drops_only_mid_line_or_without_the_colon(self):
|
||||
titles = ("Keep the steps and drop item 4, with its measurement", "Drop item 5 later", "Drop item 45: another")
|
||||
self.assertEqual([found.id for found in shipped(todo(FIRST, SECOND), todo(), titles)], [4, 5])
|
||||
|
||||
def test_ships_nothing_where_either_plan_has_no_table_it_can_read(self):
|
||||
self.assertEqual(shipped(todo(FIRST), "# todo\n\n- [ ] Do it.\n"), [])
|
||||
self.assertEqual(shipped(todo(FIRST, "| x | 0.1.0 | | **Bad.** | 2 | 3 | 5 | 6 | 7 | 1 | 9.0 |"), todo()), [])
|
||||
@@ -64,15 +77,21 @@ class Shipped(unittest.TestCase):
|
||||
|
||||
class CutBranch(unittest.TestCase):
|
||||
def test_reads_a_title_that_holds_a_control_character(self):
|
||||
found = cut_branch(f"\x00{'a' * 40} 100 100 \x1faaaaaaa\x1fTake \x1e and \x1f\n\nb.py\n")
|
||||
found = cut_branch(f"\x00{'a' * 40} 100 100 \x1faaaaaaa\x1fTake \x1e and \x1f\n\nb.py\n", BARE)
|
||||
self.assertNotIsInstance(found, Failure)
|
||||
self.assertEqual([found.titles for found in found.chunks], [("Take \x1e and \x1f",)])
|
||||
|
||||
def test_reads_each_title_as_its_summary_in_the_projects_commit_title_template(self):
|
||||
log = f"\x00{'a' * 40} 100 100 {'b' * 40}\x1faaaaaaa\x1fPAY-7 - Drop item 6: moot\n\nb.py\n\x00{'b' * 40} 90 90 \x1fbbbbbbb\x1fFrom before the template\n\nb.py\n"
|
||||
found = cut_branch(log, Titles("PAY-{id} - {summary}", "{summary}"))
|
||||
self.assertNotIsInstance(found, Failure)
|
||||
self.assertEqual(sorted(title for chunk in found.chunks for title in chunk.titles), ["Drop item 6: moot", "From before the template"])
|
||||
|
||||
def test_fails_on_a_commit_it_cannot_read(self):
|
||||
self.assertIsInstance(cut_branch(f"\x00{'a' * 40} 100\x1faaaaaaa\n"), Failure)
|
||||
self.assertIsInstance(cut_branch(f"\x00{'a' * 40} 100\x1faaaaaaa\n", BARE), Failure)
|
||||
|
||||
def test_fails_on_a_log_that_holds_no_commit(self):
|
||||
self.assertIsInstance(cut_branch(""), Failure)
|
||||
self.assertIsInstance(cut_branch("", BARE), Failure)
|
||||
|
||||
|
||||
class ChunkLog(unittest.TestCase):
|
||||
@@ -184,6 +203,19 @@ class Blamed(unittest.TestCase):
|
||||
self.assertEqual(blamed(porcelain), {first, second})
|
||||
|
||||
|
||||
class Unsupported(unittest.TestCase):
|
||||
def test_says_which_files_the_config_puts_where_no_commits_are_read(self):
|
||||
checkout = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory())).resolve()
|
||||
run = functools.partial(git, env=isolated_env())
|
||||
self.assertIsNone(unsupported(str(checkout), checkout, run), "no git checkout, so no config names it")
|
||||
folder = configured(self, checkout)
|
||||
home = folder.parents[1]
|
||||
self.assertIsNone(unsupported(str(checkout), home, run))
|
||||
config = folder / "config.toml"
|
||||
config.write_text(config.read_text().replace('"checkout:todo.md"', '"folder:todo.md"').replace('"checkout:docs/reading-cost.md"', '"checkout:records/reading-cost.md"'))
|
||||
self.assertEqual(unsupported(str(checkout), home, run), f"the project's config puts {folder}/todo.md, {checkout}/records/reading-cost.md elsewhere than todo.md, docs/comprehension-history.md, docs/reading-cost.md in the checkout, the only paths whose commits are read so far")
|
||||
|
||||
|
||||
class TracedTo(unittest.TestCase):
|
||||
DIFF = "--- a/a.py\n+++ b/a.py\n@@ -2 +2 @@\n-x\n+y\n--- a/todo.md\n+++ b/todo.md\n@@ -5 +4,0 @@\n-| 6 |\n"
|
||||
|
||||
@@ -224,10 +256,9 @@ class BranchChunks(unittest.TestCase):
|
||||
self.env.pop(name)
|
||||
return self.git("rev-parse", "--short", "HEAD").strip()
|
||||
|
||||
def read(self, run=None):
|
||||
"""branch_chunks over main, run by git_repo's git, or else by run."""
|
||||
with unittest.mock.patch.dict(os.environ, self.env, clear=True):
|
||||
return branch_chunks("main", functools.partial(run or git, cwd=str(self.checkout)))
|
||||
def read(self, run=None, titles=BARE):
|
||||
"""branch_chunks over main, run by git_repo's git, or else by run, in the test's own environment."""
|
||||
return branch_chunks("main", functools.partial(run or git, cwd=str(self.checkout), env=self.env), titles)
|
||||
|
||||
def fixing_history(self):
|
||||
"""Merges seven chunks onto main, then checks out a branch off it. Returns each of main's chunks by label, with the chunks that fixed it.
|
||||
@@ -278,8 +309,22 @@ class BranchChunks(unittest.TestCase):
|
||||
self.assertEqual((found[1].tip, found[2].tip), (self.git("rev-parse", "HEAD^").strip(), self.git("rev-parse", "HEAD^^").strip()))
|
||||
self.assertEqual((found[1].before, found[2].before), (found[2].tip, None))
|
||||
|
||||
def test_a_chunk_that_drops_an_item_by_a_commit_title_does_not_ship_it(self):
|
||||
self.merge("four", "Do four", {"b.py": "x\ny\n", "todo.md": todo(SECOND, FIX)}, "2026-10-13T10:00:00Z")
|
||||
self.merge("six", "Drop item 6: item 4 fixed it", {"b.py": "x\nY\n", "todo.md": todo(SECOND)}, "2026-10-14T10:00:00Z")
|
||||
found = self.read()
|
||||
self.assertNotIsInstance(found, Failure)
|
||||
self.assertEqual([([item.id for item in found.shipped], found.fixed_by) for found in found[:2]], [([], ()), ([4], ())])
|
||||
|
||||
def test_reads_a_drop_title_through_the_projects_commit_title(self):
|
||||
self.merge("four", "Do four", {"b.py": "x\ny\n", "todo.md": todo(SECOND, FIX)}, "2026-10-13T10:00:00Z")
|
||||
self.merge("six", "PAY-6 Drop item 6: item 4 fixed it", {"b.py": "x\nY\n", "todo.md": todo(SECOND)}, "2026-10-14T10:00:00Z")
|
||||
found = self.read(titles=Titles("{summary}", "PAY-{id} {summary}"))
|
||||
self.assertNotIsInstance(found, Failure)
|
||||
self.assertEqual([[item.id for item in found.shipped] for found in found[:2]], [[], [4]])
|
||||
|
||||
def test_fails_where_git_cannot_read_the_branch(self):
|
||||
self.assertEqual(branch_chunks("main", lambda *args: Failure("no log")), Failure("no log"))
|
||||
self.assertEqual(branch_chunks("main", lambda *args: Failure("no log"), BARE), Failure("no log"))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
@@ -4,6 +4,6 @@ import sys
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
|
||||
from loop_inbox import main
|
||||
from chunk_pr import main
|
||||
|
||||
sys.exit(main.main(sys.argv[1:], pathlib.Path.home()))
|
||||
sys.exit(main.main(sys.argv[1:]))
|
||||
@@ -0,0 +1,4 @@
|
||||
"""What the entry points that drive chunks share: loop-claude and do-epic.
|
||||
|
||||
Each runs a chunk as cycles of bin/agent_cycle/. cycle_start.py starts a cycle and chunk_run.py closes it, on the Loop this_loop.py holds, once claims.py has claimed the checkout. prompts.py words what every worker is told, project/ reads a checkout's premises, records and saved models, and drivers.py names the entry points. No module here imports an entry point's package, and bin/repo_checks/test_package_cycles.py fails on such an import.
|
||||
"""
|
||||
@@ -0,0 +1,73 @@
|
||||
"""One chunk's run across its cycles, for every entry point that drives chunks: its state (Run, ChunkRun), and how a cycle closes: the run the next cycle starts from, the step-up an unfinished verdict makes archived, and the stop once a chunk has had UNFINISHED_LIMIT unfinished verdicts running."""
|
||||
import dataclasses
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from agent_cycle.run import archived_step, archived_stop, Concluded
|
||||
from agent_cycle.verdicts import Finished
|
||||
from chunk_driver.this_loop import Loop
|
||||
from agent_cycle.stop import needs_human, Stop
|
||||
from agent_cycle.routing import next_route, step_up
|
||||
from model_routing.ladder import ProjectRung
|
||||
from model_routing.route import Route
|
||||
from claude_code.session import transcript_file
|
||||
|
||||
# How many unfinished verdicts running end the loop, so a worker and a judge that disagree about a chunk cannot cycle unattended without end. A policy number, not derived from the routing steps: well above the two unfinished verdicts running that archived chunks have reached at most, and low enough that a stuck pair is stopped after six cycles. It counts every unfinished verdict, including those of cycles where the human answered an interrupt: a rerun is cheap, and a chunk that needs that many answers is worth a look. The human confirmed both the number and what it counts.
|
||||
UNFINISHED_LIMIT = 6
|
||||
|
||||
|
||||
class Run(typing.Protocol):
|
||||
"""What closing a cycle reads and replaces in an entry point's run of one chunk. ChunkRun below is one; loop-claude's LoopRun is another, since it hands the same fields on at a reload."""
|
||||
# Every run is a dataclass, which is what lets closing a cycle replace its fields.
|
||||
__dataclass_fields__: typing.ClassVar[dict[str, typing.Any]]
|
||||
|
||||
@property
|
||||
def unfinished_evidence(self) -> str: ...
|
||||
@property
|
||||
def route(self) -> Route | None: ...
|
||||
@property
|
||||
def unfinished_run(self) -> int: ...
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class ChunkRun:
|
||||
"""The run of one chunk, for an entry point that never hands it to another process, such as do-epic."""
|
||||
cycle_number: int = 0
|
||||
# The evidence of the latest unfinished verdict; empty before the chunk's first one, and once it finishes.
|
||||
unfinished_evidence: str = ""
|
||||
# Set by each unfinished verdict; None before the chunk's first one, and once it finishes.
|
||||
route: Route | None = None
|
||||
# How many unfinished verdicts the chunk has had running.
|
||||
unfinished_run: int = 0
|
||||
|
||||
|
||||
def closed_cycle[R: Run](run: R, task: str, project: ProjectRung | None, concluded: Concluded, archive_folder: pathlib.Path, driver: str, loop: Loop) -> R | Stop:
|
||||
"""The run after a cycle of driver, the entry point, concluded on the chunk's task, with the step-up archived; the stop that needs the human, archived, once the chunk has had UNFINISHED_LIMIT unfinished verdicts running."""
|
||||
after = after_verdict(run, project, concluded)
|
||||
# A finished chunk drops its route, so it has no step-up, and its run of unfinished verdicts restarts.
|
||||
if after.route is None:
|
||||
return after
|
||||
# The unfinished verdict, archived as the cycle closed, names the route its cycle ended on; the step-up names the one the next cycle runs on.
|
||||
path = transcript_file(loop.session)
|
||||
if path and (failure := archived_step(archive_folder, path, task, step_up(concluded.route, after.route), loop.effects)):
|
||||
return Stop(1, failure.reason)
|
||||
if limit := reached_limit(after, driver):
|
||||
# Archived with the route the next cycle would run on, so a rerun resumes there.
|
||||
return archived_stop(archive_folder, loop.session, task, after.route, limit, limit.reason, loop.effects)
|
||||
return after
|
||||
|
||||
|
||||
def reached_limit(run: Run, driver: str) -> Stop | None:
|
||||
"""The stop that needs the human once the run holds UNFINISHED_LIMIT unfinished verdicts running."""
|
||||
if run.unfinished_run < UNFINISHED_LIMIT:
|
||||
return None
|
||||
return needs_human("go on with the chunk", f"the judge ruled it unfinished {run.unfinished_run} cycles running; finish the chunk yourself, or rerun {driver} to give it {UNFINISHED_LIMIT} more cycles")
|
||||
|
||||
|
||||
def after_verdict[R: Run](run: R, project: ProjectRung | None, concluded: Concluded) -> R:
|
||||
"""The run the next cycle starts from. A finished chunk drops its route and its run of unfinished verdicts. An unfinished one takes the route routing.next_route makes of the route its cycle ended on, which an interrupt's or a quoted answer's escalation may have raised, and the evidence the judge gave for the verdict; and counts the verdict."""
|
||||
verdict = concluded.verdict
|
||||
if isinstance(verdict, Finished):
|
||||
return dataclasses.replace(run, route=None, unfinished_evidence="", unfinished_run=0)
|
||||
route = next_route(project, concluded.route, verdict)
|
||||
return dataclasses.replace(run, route=route, unfinished_evidence=verdict.evidence, unfinished_run=run.unfinished_run + 1)
|
||||
@@ -0,0 +1,68 @@
|
||||
"""How entry points claim a checkout before they start a chunk in it, so that two never start the same chunk and do-epic never starts one where loop-claude runs.
|
||||
|
||||
An entry point holds `starting` on `project_lock` while it lists the windows of the checkout's chunks and starts new ones. Where the lock cannot be taken, `starting` yields a Failure, and the entry point doesn't start any chunk. It starts each chunk in a tmux window with CHUNK_FLAG, and hands that window the variables named with HANDED.
|
||||
"""
|
||||
import contextlib
|
||||
import fcntl
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from failure import Failure
|
||||
from transcript_archive.project_key import project_key
|
||||
from agent_cycle import tmux
|
||||
|
||||
# Under the home folder, a folder per project key holds LOCK.
|
||||
CLAIMS = ".local/state/loop-claude"
|
||||
# The file an entry point keeps locked with flock while it lists the windows of a project's chunks and starts new ones. Two loops whose chunks finish together then don't start a chunk twice, and do-epic, which holds the same lock, never starts a chunk in a checkout while loop-claude does.
|
||||
LOCK = "starting"
|
||||
# The flag that tells the entry point in a window its chunk, as `--chunk item-372` for loop-claude and `--chunk ABC-34 ABC-12` for do-epic. Nobody types it, so no panel picked it.
|
||||
CHUNK_FLAG = "--chunk"
|
||||
# The prefix of the variables both entry points read. A window gets the tmux server's environment, not the starting terminal's, so they are handed to each window by name.
|
||||
HANDED = "LOOP_CLAUDE_"
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def starting(folder: pathlib.Path) -> typing.Iterator[Failure | None]:
|
||||
"""Holds the LOCK in folder: project_lock's for a project, or do-epic's for an epic. It yields a Failure, and doesn't hold any lock, where the file cannot be opened or locked."""
|
||||
with locked(folder / LOCK) as failure:
|
||||
yield failure
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def locked(file: pathlib.Path) -> typing.Iterator[Failure | None]:
|
||||
"""Holds a flock on file, which it makes with its folder. It yields a Failure, and doesn't hold any lock, where the file cannot be opened or locked."""
|
||||
try:
|
||||
file.parent.mkdir(parents=True, exist_ok=True)
|
||||
lock = open(file, "a")
|
||||
except OSError as failure:
|
||||
yield Failure(f"cannot lock {failure.filename or file}: {failure.strerror}")
|
||||
return
|
||||
with lock:
|
||||
try:
|
||||
fcntl.flock(lock, fcntl.LOCK_EX)
|
||||
except OSError as failure:
|
||||
yield Failure(f"cannot lock {file}: {failure.strerror}")
|
||||
return
|
||||
yield None
|
||||
|
||||
|
||||
def project_lock(root: str, home: pathlib.Path) -> pathlib.Path:
|
||||
"""The folder of the LOCK that everything starting a chunk in the checkout root holds."""
|
||||
return home / CLAIMS / project_key(root, home)
|
||||
|
||||
|
||||
def loop_session(root: str, home: pathlib.Path) -> str:
|
||||
"""The tmux session that holds the windows of loop-claude's chunks of the checkout root."""
|
||||
return tmux.session_name(tmux.LOOP, project_key(root, home))
|
||||
|
||||
|
||||
def loop_chunks(root: str, home: pathlib.Path, run: tmux.Tmux) -> list[tmux.Listed]:
|
||||
"""The windows of loop-claude's chunks that run in the checkout root. A session that runs another checkout's chunks under the same name doesn't hold any."""
|
||||
session = loop_session(root, home)
|
||||
running = [window for window in tmux.listed(session, run) if not window.dead]
|
||||
return running if running and tmux.owner(session, run) == root else []
|
||||
|
||||
|
||||
def epic_chunks(root: str, run: tmux.Tmux) -> list[tmux.Placed]:
|
||||
"""The windows of do-epic's sessions whose chunks run in the checkout root. A parked chunk doesn't run."""
|
||||
return [placed for placed in tmux.everywhere(run) if placed.session.startswith(f"{tmux.EPIC}-") and placed.root == root and not placed.window.dead and not placed.window.parked]
|
||||
@@ -0,0 +1,114 @@
|
||||
"""How a cycle starts, for every entry point that drives chunks: the models and the ladder it routes on, the route its worker runs on, and the Cycle built from them.
|
||||
|
||||
An entry point starts a cycle in this order:
|
||||
|
||||
1. It reads what it alone knows, such as the premises, the records and the task.
|
||||
2. `project_routing` or `routing_on` reads the models and the ladder.
|
||||
3. `announced_route` picks the route and prints the cycle's opening line.
|
||||
4. `cycle_of` builds the Cycle.
|
||||
|
||||
Each read is made afresh every cycle, so an edit between two cycles takes effect in the next.
|
||||
"""
|
||||
import dataclasses
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from agent_cycle.run import Cycle
|
||||
from claude_code.entries import Entry
|
||||
from failure import Failure
|
||||
from agent_cycle.routing import first_route, judge_rung, kept, Scored
|
||||
from chunk_driver.project.model_choice import get_or_ask_models, Models
|
||||
from git_cli.git_repo import Git
|
||||
from model_routing.ladder import Ladder, ProjectRung, Rung
|
||||
from transcript_archive.read import latest_worker
|
||||
from chunk_driver.this_loop import Loop
|
||||
from transcript_archive.project_key import project_key
|
||||
from model_routing.ladder_file import project_ladder_file, read_ladder
|
||||
from model_routing.route import Route, route_from
|
||||
from loop_effects.effects import say
|
||||
from agent_cycle.stop import Stop
|
||||
from agent_cycle.verdicts import TakenIn
|
||||
from claude_code.session import transcript_file
|
||||
from agent_cycle.worker_prompts import WorkerPrompts
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Routing:
|
||||
"""What a cycle routes on, as read when it started."""
|
||||
# The project's worker and judge models.
|
||||
models: Models
|
||||
ladder: Ladder
|
||||
# The file the ladder was read from: the shipped one, or the project's own.
|
||||
ladder_file: pathlib.Path
|
||||
|
||||
@property
|
||||
def project(self) -> ProjectRung | None:
|
||||
"""The project's rung on the ladder; None for a worker model off the ladder."""
|
||||
return self.ladder.project_rung(self.models.worker)
|
||||
|
||||
|
||||
def project_routing(loop: Loop, driver: str) -> Routing | Stop:
|
||||
"""The routing of the project checked out at the loop's root: its models, asked of the human where none is saved, and its ladder. The stop where one cannot be read."""
|
||||
models = get_or_ask_models(project_key(loop.root, loop.paths.home), loop.paths, loop.env, driver, loop.effects)
|
||||
if isinstance(models, Stop):
|
||||
return models
|
||||
ladder_file = project_ladder_file(loop.root, loop.paths.home)
|
||||
return Stop(1, ladder_file.reason) if isinstance(ladder_file, Failure) else routing_on(models, ladder_file)
|
||||
|
||||
|
||||
def routing_on(models: Models, ladder_file: pathlib.Path) -> Routing | Stop:
|
||||
"""The routing of models on the ladder ladder_file holds; the stop where it cannot be read."""
|
||||
ladder = read_ladder(ladder_file)
|
||||
return Stop(1, ladder.reason) if isinstance(ladder, Failure) else Routing(models, ladder, ladder_file)
|
||||
|
||||
|
||||
def announced_route(cycle_number: int, kept_route: Route | None, routing: Routing, archive_folder: pathlib.Path, item: typing.Callable[[], Scored | None], loop: Loop) -> Route:
|
||||
"""The route cycle cycle_number runs on, printed with the cycle's opening line. kept_route is the one the chunk's run holds, and item finds what routes a fresh chunk."""
|
||||
route = routed(kept_route, routing.project, routing.models.worker, lambda: archived_route(archive_folder, loop), item)
|
||||
say(f"\n=== cycle {cycle_number}, worker on {route.rung} ===", loop.effects, stdout=True)
|
||||
return route
|
||||
|
||||
|
||||
def routed(route: Route | None, project: ProjectRung | None, model: str, archived: typing.Callable[[], Route | None], item: typing.Callable[[], Scored | None]) -> Route:
|
||||
"""The route the cycle runs on. project is the project's rung, and model the project's model.
|
||||
|
||||
Where project is None, the model is off the ladder, and the worker runs on it. Otherwise the chunk keeps route, or on a rerun the route its archive last names, as routing.kept allows. Else what item finds routes the chunk afresh.
|
||||
"""
|
||||
if project is None:
|
||||
return Route(Rung(model))
|
||||
route = route or archived()
|
||||
return route if route and kept(route, project) else first_route(project, item())
|
||||
|
||||
|
||||
def archived_route(archive_folder: pathlib.Path, loop: Loop) -> Route | None:
|
||||
"""The route named by the latest verdict archived for the loop's open chunk; None for a chunk not yet judged."""
|
||||
transcript = transcript_file(loop.session)
|
||||
worker = latest_worker(archive_folder, transcript) if transcript else None
|
||||
if isinstance(worker, Failure):
|
||||
say(f"routing the chunk afresh: {worker.reason}", loop.effects)
|
||||
return None
|
||||
route = route_from(worker) if worker else None
|
||||
if worker and route is None:
|
||||
say(f"routing the chunk afresh: the archive's latest Worker: line names no route that can be read: {worker}", loop.effects)
|
||||
return route
|
||||
|
||||
|
||||
def cycle_of(loop: Loop, routing: Routing, route: Route, archive_folder: pathlib.Path, *, task: str, facts: str, premises: str, records: str, unfinished_evidence: str, prompts: WorkerPrompts, taken_in: typing.Callable[[list[Entry]], TakenIn]) -> Cycle:
|
||||
"""The cycle that runs in the loop's window on route. The keyword arguments are what the entry point alone knows; Cycle says what each is."""
|
||||
return Cycle(config=setup_version(loop.paths.claude_dir, loop.effects.git), effects=loop.effects, facts=facts, judge=judge_rung(routing.ladder, routing.models.judge), premises=premises, project=routing.project, project_archive=archive_folder, records=records, root=loop.root, route=route, session=loop.session, task=task, prompts=prompts, taken_in=taken_in, unfinished_evidence=unfinished_evidence, window=loop.window)
|
||||
|
||||
|
||||
def setup_version(claude_dir: pathlib.Path, git: Git) -> str:
|
||||
"""The release and commit of this setup that the worker's claude reads, as `v0.8.0 (<sha>)`; a commit past the latest release reads as git describe gives it, such as `v0.8.0-3-g1a2b3c4 (<sha>)`. Where git can't tell, `unknown` and why."""
|
||||
described = git("describe", "--tags", "--match", "v*", "--always", cwd=str(claude_dir))
|
||||
commit = git("rev-parse", "HEAD", cwd=str(claude_dir))
|
||||
if isinstance(described, Failure):
|
||||
return unknown_version(described)
|
||||
if isinstance(commit, Failure):
|
||||
return unknown_version(commit)
|
||||
return f"{described.strip()} ({commit.strip()})"
|
||||
|
||||
|
||||
def unknown_version(failure: Failure) -> str:
|
||||
# One line, since the archive reads the line after it as the judge's.
|
||||
return f"unknown: {' '.join(failure.reason.split())}"
|
||||
@@ -0,0 +1,16 @@
|
||||
"""Test doubles for the suites that drive a chunk: the loop of an entry point that exists only in tests."""
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from loop_effects.effects import Effects
|
||||
from chunk_driver.this_loop import Loop
|
||||
from loop_state import paths
|
||||
from claude_code import session
|
||||
from agent_cycle.doubles import WINDOW
|
||||
|
||||
|
||||
def a_loop(effects: Effects, **fields: typing.Any) -> Loop:
|
||||
"""A loop in /r on effects, with fields in place of its defaults."""
|
||||
home = pathlib.Path("/h")
|
||||
defaults = {"root": "/r", "session": session.session_named("A proj a-driver", home / ".claude" / "projects"), "paths": paths.paths_from(home), "env": {}, "launcher": pathlib.Path("/b/a-driver"), "window": WINDOW}
|
||||
return Loop(**{**defaults, **fields}, effects=effects)
|
||||
@@ -0,0 +1,3 @@
|
||||
"""The entry points that drive chunks, each by its name as its workers, its judge and the human read it. A prompt function that takes a driver takes one of these."""
|
||||
LOOP_CLAUDE = "loop-claude"
|
||||
DO_EPIC = "do-epic"
|
||||
+44
-21
@@ -5,11 +5,11 @@ import sys
|
||||
import typing
|
||||
|
||||
from claude_code.model_catalog import catalog_models
|
||||
from loop_claude.effects import Effects, say
|
||||
from chunk_driver.claims import CLAIMS, locked
|
||||
from loop_effects.effects import Effects, say
|
||||
from failure import Failure
|
||||
from loop_claude.stop import needs_human, needs_terminal, Stop
|
||||
from loop_claude.paths import Paths
|
||||
from records.file_writes import replace_json
|
||||
from agent_cycle.stop import needs_human, needs_terminal, Stop
|
||||
from loop_state.paths import Paths
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
@@ -18,38 +18,61 @@ class Models:
|
||||
worker: str
|
||||
|
||||
|
||||
def get_or_ask_models(project_key: str, paths: Paths, env: typing.Mapping[str, str], effects: Effects) -> Models | Stop:
|
||||
judge, worker = env.get("LOOP_CLAUDE_JUDGE_MODEL"), env.get("LOOP_CLAUDE_WORKER_MODEL")
|
||||
if judge and worker:
|
||||
return Models(judge, worker)
|
||||
chosen = get_or_ask_model(project_key, paths, effects)
|
||||
# The environment variables that name the judge's and the worker's model for one run, over the model saved or configured.
|
||||
JUDGE_MODEL = "LOOP_CLAUDE_JUDGE_MODEL"
|
||||
WORKER_MODEL = "LOOP_CLAUDE_WORKER_MODEL"
|
||||
# The file, in CLAIMS under the home folder, that save_model keeps locked with flock while it rereads and replaces the models file. The models file's own folder is a checkout of this setup, which takes no lock file.
|
||||
MODELS_LOCK = "models.lock"
|
||||
|
||||
|
||||
def overridden(env: typing.Mapping[str, str], default: str) -> Models:
|
||||
"""The models of a run: default, unless env names another for the judge or the worker."""
|
||||
return Models(env.get(JUDGE_MODEL) or default, env.get(WORKER_MODEL) or default)
|
||||
|
||||
|
||||
def get_or_ask_models(project_key: str, paths: Paths, env: typing.Mapping[str, str], driver: str, effects: Effects) -> Models | Stop:
|
||||
named = overridden(env, "")
|
||||
if named.judge and named.worker:
|
||||
return named
|
||||
chosen = get_or_ask_model(project_key, paths, driver, effects)
|
||||
if isinstance(chosen, Stop):
|
||||
return chosen
|
||||
return Models(judge or chosen, worker or chosen)
|
||||
return overridden(env, chosen)
|
||||
|
||||
|
||||
def get_or_ask_model(project_key: str, paths: Paths, effects: Effects) -> str | Stop:
|
||||
def get_or_ask_model(project_key: str, paths: Paths, driver: str, effects: Effects) -> str | Stop:
|
||||
saved = paths.models_file
|
||||
models = read_models_file(saved)
|
||||
if isinstance(models, Failure):
|
||||
return Stop(1, models.reason)
|
||||
if kept := models.get(project_key):
|
||||
return kept
|
||||
chosen = ask_for_model(project_key, saved, paths.model_catalog, effects)
|
||||
chosen = ask_for_model(project_key, saved, paths.model_catalog, driver, effects)
|
||||
if isinstance(chosen, Stop):
|
||||
return chosen
|
||||
# Reread: another loop may have saved its project while this one waited on the human.
|
||||
models = read_models_file(saved)
|
||||
if isinstance(models, Failure):
|
||||
return Stop(1, models.reason)
|
||||
if failure := replace_json(saved, {**models, project_key: chosen}, indent="\t", sort_keys=True):
|
||||
return Stop(1, f"could not save the model in {saved}: {failure.reason}")
|
||||
if failure := save_model(project_key, chosen, paths, effects.replace_file):
|
||||
return Stop(1, failure.reason)
|
||||
say(f"{project_key} runs on {chosen}", effects)
|
||||
return chosen
|
||||
|
||||
|
||||
def save_model(project_key: str, chosen: str, paths: Paths, replace: typing.Callable[[pathlib.Path, bytes], Failure | None]) -> Failure | None:
|
||||
"""Adds the project's model to the models file, whose only writer this is, through replace, which writes a file as replace_file does. It holds MODELS_LOCK from its read to its write, so two entry points that save at once both keep their pick."""
|
||||
saved = paths.models_file
|
||||
with locked(paths.home / CLAIMS / MODELS_LOCK) as unlocked:
|
||||
if unlocked:
|
||||
return Failure(f"could not save the model in {saved}: {unlocked.reason}")
|
||||
# Read under the lock: another entry point may have saved its project while this one waited on the human.
|
||||
models = read_models_file(saved)
|
||||
if isinstance(models, Failure):
|
||||
return models
|
||||
if failure := replace(saved, json.dumps({**models, project_key: chosen}, indent="\t", sort_keys=True).encode()):
|
||||
return Failure(f"could not save the model in {saved}: {failure.reason}")
|
||||
return None
|
||||
|
||||
|
||||
def read_models_file(saved: pathlib.Path) -> dict[str, str] | Failure:
|
||||
"""Each project's model, as the models file at saved maps them; none where there is no such file. loop-claude and the replay tools read it."""
|
||||
"""Each project's model, as the models file at saved maps them; none where there is no such file. The entry points, loop-claude and do-epic, and the replay tools read it."""
|
||||
try:
|
||||
with open(saved, encoding="utf-8") as handle:
|
||||
models = json.load(handle)
|
||||
@@ -62,8 +85,8 @@ def read_models_file(saved: pathlib.Path) -> dict[str, str] | Failure:
|
||||
return models
|
||||
|
||||
|
||||
def ask_for_model(project_key: str, saved: pathlib.Path, folder: pathlib.Path, effects: Effects) -> str | Stop:
|
||||
if stop := needs_terminal(f"pick {project_key}'s model, or merge {{\"{project_key}\": \"<model>\"}} into {saved}", effects.on_terminal()):
|
||||
def ask_for_model(project_key: str, saved: pathlib.Path, folder: pathlib.Path, driver: str, effects: Effects) -> str | Stop:
|
||||
if stop := needs_terminal(f"pick {project_key}'s model, or merge {{\"{project_key}\": \"<model>\"}} into {saved}", effects.on_terminal(), driver):
|
||||
return stop
|
||||
offered = catalog_models(folder)
|
||||
choices = [f" {number}. {label} ({model_id})" for number, (model_id, label) in enumerate(offered, 1)] or [f" no model catalog cached in {folder}"]
|
||||
@@ -0,0 +1,26 @@
|
||||
import pathlib
|
||||
|
||||
from failure import Failure
|
||||
from record_store.stores import goals_store
|
||||
from project_config.main import located
|
||||
from plan.goals_file import section
|
||||
|
||||
|
||||
def read_premises(root: str, home: pathlib.Path) -> str | Failure:
|
||||
"""Where the goals file is kept, then its ## Goals and ## Audience. The goals file is the one that the config of root's checkout, under home, names: a file or a Jira epic's description. A Failure where no config names the checkout, or the goals file cannot be read, is missing or empty, lacks a section, holds one twice or leaves one empty."""
|
||||
config = located(root, home)
|
||||
if isinstance(config, Failure):
|
||||
return Failure(f"{config.reason} - no premises.")
|
||||
goals = goals_store(config)
|
||||
text = goals.read()
|
||||
if isinstance(text, Failure):
|
||||
return Failure(f"{text.reason} - no premises.")
|
||||
if not text:
|
||||
return Failure(f"{goals.label} is missing or empty - no premises.")
|
||||
bodies: list[str] = []
|
||||
for name in ("Goals", "Audience"):
|
||||
body = section(text, name)
|
||||
if isinstance(body, Failure):
|
||||
return Failure(f"{goals.label} {body.reason} - no premises.")
|
||||
bodies.append(body)
|
||||
return f"{goals.label}:\n## Goals\n{bodies[0]}\n\n## Audience\n{bodies[1]}"
|
||||
@@ -0,0 +1,59 @@
|
||||
import pathlib
|
||||
|
||||
from failure import Failure
|
||||
from project_config.main import located
|
||||
from chunk_driver.project.text_file import read_utf8
|
||||
from record_store.stores import store
|
||||
|
||||
# The records the judge reads beside the premises, by the name that heads each, with the setting in the project's config that places it; then the human's rules below.
|
||||
WORKING_RULES = ("AGENTS.md", "working-rules")
|
||||
DECISIONS = ("docs/decisions.md", "decisions")
|
||||
RECORD_FILES = (WORKING_RULES[0], DECISIONS[0])
|
||||
# The human's rules, in the order the judge reads them: ~/.claude/CLAUDE.md, each .md file in ~/.claude/rules/,
|
||||
# then each .md file in the review standards folder the project's config sets.
|
||||
HUMAN_RULES_FILE = "CLAUDE.md"
|
||||
HUMAN_RULE_DIR = "rules"
|
||||
# How the judge's prompt names the records above, in the order it reads them.
|
||||
RECORDS_NAMED = "the project's working rules and decisions, then the human's rules for every project"
|
||||
HUMAN_RULE_NAMES = (f"~/.claude/{HUMAN_RULES_FILE}", f"~/.claude/{HUMAN_RULE_DIR}/", "the project's review standards")
|
||||
|
||||
|
||||
CONSEQUENCE = "the judge cannot read the records"
|
||||
|
||||
|
||||
def read_records(root: str | None, home: pathlib.Path, claude_dir: pathlib.Path, first: tuple[tuple[str, str], ...] = ()) -> str | Failure:
|
||||
"""The project's `AGENTS.md` and decision log, then the human's rules, CLAUDE.md first, each headed by its name. One that does not exist, or is empty, is left out. A text that several of them hold appears once, headed by all their names.
|
||||
|
||||
`AGENTS.md` is read where the config under home of root's project puts it, and the decision log from the store that config names. Each is headed by its name in RECORD_FILES wherever it is kept.
|
||||
|
||||
first holds records kept outside the project, such as the sections of a Jira epic's description, each as its heading and text: they come before the project's. A root of None is work without a checkout, which has no project records and no review standards."""
|
||||
texts: list[tuple[str, str | Failure]] = list(first)
|
||||
rules = [claude_dir / HUMAN_RULES_FILE, *sorted((claude_dir / HUMAN_RULE_DIR).glob("*.md"))]
|
||||
if root is not None:
|
||||
config = located(root, home)
|
||||
if isinstance(config, Failure):
|
||||
return Failure(f"{config.reason} - {CONSEQUENCE}.")
|
||||
rules += sorted(config.paths["standards"].glob("*.md"))
|
||||
decisions = store(config, DECISIONS[1]).read()
|
||||
texts += [(WORKING_RULES[0], file_text(config.paths[WORKING_RULES[1]])), (DECISIONS[0], Failure(f"{decisions.reason} - {CONSEQUENCE}.") if isinstance(decisions, Failure) else decisions)]
|
||||
texts += [(named(rule, home, claude_dir), file_text(rule)) for rule in rules]
|
||||
# Each text, with the names of the records that hold it: a config may keep the working rules in the decision log.
|
||||
records: dict[str, list[str]] = {}
|
||||
for heading, text in texts:
|
||||
if isinstance(text, Failure):
|
||||
return text
|
||||
if text.strip():
|
||||
records.setdefault(text.strip(), []).append(heading)
|
||||
return "\n\n".join(f"From {' and '.join(headings)}:\n{text}" for text, headings in records.items())
|
||||
|
||||
|
||||
def file_text(path: pathlib.Path) -> str | Failure:
|
||||
"""path's text, empty where no such file exists."""
|
||||
return read_utf8(str(path.parent), path.name, CONSEQUENCE) if path.exists() else ""
|
||||
|
||||
|
||||
def named(rule: pathlib.Path, home: pathlib.Path, claude_dir: pathlib.Path) -> str:
|
||||
"""rule's path as the human writes it: under ~/.claude, or ~/ for the rest of home, or else in full."""
|
||||
if rule.is_relative_to(claude_dir):
|
||||
return f"~/.claude/{rule.relative_to(claude_dir)}"
|
||||
return f"~/{rule.relative_to(home)}" if rule.is_relative_to(home) else str(rule)
|
||||
@@ -0,0 +1,165 @@
|
||||
import contextlib
|
||||
import dataclasses
|
||||
import fcntl
|
||||
import io
|
||||
import json
|
||||
import pathlib
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2]))
|
||||
|
||||
from failure import Failure
|
||||
from loop_effects.doubles import FakeEffects
|
||||
from chunk_driver.drivers import LOOP_CLAUDE
|
||||
from chunk_driver.project import model_choice
|
||||
from loop_state.paths import paths_from
|
||||
from text_files.file_writes import replace_file
|
||||
from agent_cycle.stop import Stop
|
||||
|
||||
|
||||
class Overridden(unittest.TestCase):
|
||||
def test_the_environment_names_the_judges_or_the_workers_model_over_the_default(self):
|
||||
self.assertEqual(model_choice.overridden({}, "saved"), model_choice.Models("saved", "saved"))
|
||||
self.assertEqual(model_choice.overridden({"LOOP_CLAUDE_JUDGE_MODEL": "j", "LOOP_CLAUDE_WORKER_MODEL": ""}, "saved"), model_choice.Models("j", "saved"))
|
||||
self.assertEqual(model_choice.overridden({"LOOP_CLAUDE_JUDGE_MODEL": "j", "LOOP_CLAUDE_WORKER_MODEL": "w"}, "saved"), model_choice.Models("j", "w"))
|
||||
|
||||
|
||||
class ModelsOfARun(unittest.TestCase):
|
||||
def setUp(self):
|
||||
temp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(temp.cleanup)
|
||||
self.paths = paths_from(pathlib.Path(temp.name))
|
||||
self.paths.models_file.parent.mkdir()
|
||||
|
||||
def test_a_run_that_names_both_models_reads_no_models_file_and_asks_nothing(self):
|
||||
self.paths.models_file.write_text("not json")
|
||||
fake = FakeEffects()
|
||||
env = {"LOOP_CLAUDE_JUDGE_MODEL": "j", "LOOP_CLAUDE_WORKER_MODEL": "w"}
|
||||
self.assertEqual(model_choice.get_or_ask_models("proj", self.paths, env, LOOP_CLAUDE, fake.effects()), model_choice.Models("j", "w"))
|
||||
self.assertEqual(fake.calls, [])
|
||||
|
||||
def test_a_run_that_names_one_model_takes_the_other_from_the_models_file(self):
|
||||
self.paths.models_file.write_text(json.dumps({"proj": "saved"}))
|
||||
fake = FakeEffects()
|
||||
self.assertEqual(model_choice.get_or_ask_models("proj", self.paths, {"LOOP_CLAUDE_JUDGE_MODEL": "j"}, LOOP_CLAUDE, fake.effects()), model_choice.Models("j", "saved"))
|
||||
self.assertEqual(model_choice.get_or_ask_models("proj", self.paths, {"LOOP_CLAUDE_WORKER_MODEL": "w"}, LOOP_CLAUDE, fake.effects()), model_choice.Models("saved", "w"))
|
||||
self.assertEqual(fake.calls, [])
|
||||
|
||||
def test_a_run_that_names_one_model_asks_for_the_projects_where_none_is_saved_and_saves_the_pick(self):
|
||||
fake, said = FakeEffects(inputs=["my-model"]), io.StringIO()
|
||||
with contextlib.redirect_stderr(said):
|
||||
models = model_choice.get_or_ask_models("proj", self.paths, {"LOOP_CLAUDE_JUDGE_MODEL": "j"}, LOOP_CLAUDE, fake.effects())
|
||||
self.assertEqual(models, model_choice.Models("j", "my-model"))
|
||||
self.assertEqual(json.loads(self.paths.models_file.read_text()), {"proj": "my-model"})
|
||||
self.assertIn(" proj runs on my-model\n", said.getvalue())
|
||||
|
||||
def test_off_a_terminal_it_stops_naming_the_driver_to_rerun_and_the_file_to_merge_the_model_into(self):
|
||||
fake = FakeEffects(on_terminal=False)
|
||||
stop = model_choice.get_or_ask_models("proj", self.paths, {}, LOOP_CLAUDE, fake.effects())
|
||||
assert isinstance(stop, Stop)
|
||||
self.assertEqual(stop.code, 2)
|
||||
self.assertIn(f"pick proj's model, or merge {{\"proj\": \"<model>\"}} into {self.paths.models_file}", stop.reason)
|
||||
self.assertIn(LOOP_CLAUDE, stop.reason)
|
||||
self.assertFalse(self.paths.models_file.exists())
|
||||
|
||||
def test_stops_with_exit_1_where_the_models_file_maps_no_projects_to_model_names(self):
|
||||
for held in ("[]", '{"proj": 5}', '{"proj": ""}'):
|
||||
with self.subTest(held=held):
|
||||
self.paths.models_file.write_text(held)
|
||||
stop = model_choice.get_or_ask_models("proj", self.paths, {}, LOOP_CLAUDE, FakeEffects().effects())
|
||||
self.assertEqual(stop, Stop(1, f"could not read {self.paths.models_file}: not an object mapping projects to model names"))
|
||||
|
||||
|
||||
class SavingAModel(unittest.TestCase):
|
||||
def setUp(self):
|
||||
temp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(temp.cleanup)
|
||||
self.paths = paths_from(pathlib.Path(temp.name))
|
||||
self.lock = self.paths.home / ".local/state/loop-claude/models.lock"
|
||||
|
||||
def test_adds_the_projects_model_to_those_the_file_holds(self):
|
||||
self.paths.models_file.parent.mkdir()
|
||||
self.paths.models_file.write_text(json.dumps({"other": "model-x"}))
|
||||
self.assertIsNone(model_choice.save_model("proj", "model-b", self.paths, replace_file))
|
||||
self.assertEqual(json.loads(self.paths.models_file.read_text()), {"other": "model-x", "proj": "model-b"})
|
||||
|
||||
def test_writes_the_file_for_a_human_to_merge_into_a_project_per_tab_indented_line_in_the_order_of_their_keys(self):
|
||||
self.paths.models_file.parent.mkdir()
|
||||
self.paths.models_file.write_text(json.dumps({"zebra": "model-z", "other": "model-x"}))
|
||||
self.assertIsNone(model_choice.save_model("proj", "model-b", self.paths, replace_file))
|
||||
self.assertEqual(self.paths.models_file.read_text(), '{\n\t"other": "model-x",\n\t"proj": "model-b",\n\t"zebra": "model-z"\n}')
|
||||
|
||||
def lock_is_held(self) -> bool:
|
||||
with open(self.lock, "a") as other:
|
||||
try:
|
||||
fcntl.flock(other, fcntl.LOCK_EX | fcntl.LOCK_NB)
|
||||
except BlockingIOError:
|
||||
return True
|
||||
return False
|
||||
|
||||
def test_holds_the_models_lock_from_its_read_to_its_write(self):
|
||||
self.paths.models_file.parent.mkdir()
|
||||
held = []
|
||||
|
||||
class Watched(pathlib.PosixPath):
|
||||
"""The models file, which notes whether the lock is held each time it is opened."""
|
||||
|
||||
def __fspath__(watched) -> str:
|
||||
held.append(self.lock_is_held())
|
||||
return super().__fspath__()
|
||||
|
||||
def replace(path: pathlib.Path, data: bytes) -> None:
|
||||
held.append(self.lock_is_held())
|
||||
|
||||
paths = dataclasses.replace(self.paths, models_file=Watched(self.paths.models_file))
|
||||
self.assertIsNone(model_choice.save_model("proj", "model-b", paths, replace))
|
||||
self.assertEqual(held, [True, True])
|
||||
self.assertFalse(self.lock_is_held())
|
||||
|
||||
def test_doesnt_save_anything_where_it_cannot_take_the_lock(self):
|
||||
self.paths.models_file.parent.mkdir()
|
||||
self.lock.parent.parent.mkdir(parents=True)
|
||||
self.lock.parent.write_text("")
|
||||
saved = model_choice.save_model("proj", "model-b", self.paths, replace_file)
|
||||
assert isinstance(saved, Failure)
|
||||
self.assertRegex(saved.reason, f"^could not save the model in {self.paths.models_file}: cannot lock {self.lock.parent}: \\w")
|
||||
self.assertFalse(self.paths.models_file.exists())
|
||||
|
||||
def test_a_pick_is_saved_through_save_model_alone(self):
|
||||
self.paths.models_file.parent.mkdir()
|
||||
fake, held = FakeEffects(inputs=["my-model"]), []
|
||||
|
||||
def replace(path: pathlib.Path, data: bytes) -> Failure:
|
||||
held.append(self.lock_is_held())
|
||||
return Failure("could not save")
|
||||
|
||||
fake.replace_file = replace
|
||||
self.assertEqual(model_choice.get_or_ask_model("proj", self.paths, LOOP_CLAUDE, fake.effects()), Stop(1, f"could not save the model in {self.paths.models_file}: could not save"))
|
||||
self.assertEqual(held, [True])
|
||||
|
||||
|
||||
class ModelPrompt(unittest.TestCase):
|
||||
OFFERED = [("claude-opus-5-5", "Opus 5.5"), ("claude-haiku-4-5", "Haiku 4.5")]
|
||||
|
||||
def test_reads_a_number_as_the_offered_model_and_anything_else_as_a_name(self):
|
||||
self.assertEqual(model_choice.model_picked(" 2 ", self.OFFERED), "claude-haiku-4-5")
|
||||
self.assertEqual(model_choice.model_picked("1", self.OFFERED), "claude-opus-5-5")
|
||||
self.assertEqual(model_choice.model_picked("0", self.OFFERED), Failure("pick 1 to 2"))
|
||||
self.assertEqual(model_choice.model_picked("opus", self.OFFERED), "opus")
|
||||
self.assertEqual(model_choice.model_picked("3", []), "3")
|
||||
self.assertEqual(model_choice.model_picked("3", self.OFFERED), Failure("pick 1 to 2"))
|
||||
self.assertIsNone(model_choice.model_picked(" ", self.OFFERED))
|
||||
|
||||
def test_asks_again_until_an_answer_picks_a_model(self):
|
||||
with tempfile.TemporaryDirectory() as empty:
|
||||
fake = FakeEffects(inputs=["", "my-model"])
|
||||
self.assertEqual(model_choice.ask_for_model("proj", pathlib.Path("/m.json"), pathlib.Path(empty), LOOP_CLAUDE, fake.effects()), "my-model")
|
||||
self.assertEqual(len(fake.made("input")), 2)
|
||||
fake = FakeEffects(inputs=[EOFError()])
|
||||
self.assertEqual(model_choice.ask_for_model("proj", pathlib.Path("/m.json"), pathlib.Path(empty), LOOP_CLAUDE, fake.effects()), Stop(2, "the human is needed to pick proj's model, but the input ended"))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,99 @@
|
||||
import pathlib
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2]))
|
||||
|
||||
from project_config.doubles import configured
|
||||
from failure import Failure
|
||||
from agent_cycle import judge
|
||||
from chunk_driver.project import records
|
||||
|
||||
|
||||
class Records(unittest.TestCase):
|
||||
def test_heads_each_record_by_its_name_the_humans_rules_last(self):
|
||||
with tempfile.TemporaryDirectory() as root:
|
||||
claude_md = pathlib.Path(root, "home", ".claude", "CLAUDE.md")
|
||||
config = configured(self, pathlib.Path(root), home=claude_md.parents[1]) / "config.toml"
|
||||
self.assertEqual(records.read_records(root, claude_md.parents[1], claude_md.parent), "")
|
||||
claude_md.parent.mkdir(parents=True)
|
||||
claude_md.write_text("# Global\n")
|
||||
self.assertEqual(records.read_records(root, claude_md.parents[1], claude_md.parent), "From ~/.claude/CLAUDE.md:\n# Global")
|
||||
pathlib.Path(root, "docs").mkdir()
|
||||
pathlib.Path(root, "docs", "decisions.md").write_text("# Decisions\n")
|
||||
pathlib.Path(root, "AGENTS.md").write_text("\n# Rules\n")
|
||||
self.assertEqual(records.read_records(root, claude_md.parents[1], claude_md.parent), "From AGENTS.md:\n# Rules\n\nFrom docs/decisions.md:\n# Decisions\n\nFrom ~/.claude/CLAUDE.md:\n# Global")
|
||||
pathlib.Path(claude_md.parent, "rules").mkdir()
|
||||
pathlib.Path(claude_md.parent, "rules", "todo-items.md").write_text("# Todo\n")
|
||||
pathlib.Path(claude_md.parent, "rules", "goals-and-audience.md").write_text("# Goals\n")
|
||||
pathlib.Path(claude_md.parent, "rules", "notes.txt").write_text("not a rule\n")
|
||||
pathlib.Path(claude_md.parent, "skills", "larv-review", "standards").mkdir(parents=True)
|
||||
pathlib.Path(claude_md.parent, "skills", "larv-review", "standards", "comments.md").write_text("# Comments\n")
|
||||
self.assertTrue(records.read_records(root, claude_md.parents[1], claude_md.parent).endswith("From ~/.claude/CLAUDE.md:\n# Global\n\nFrom ~/.claude/rules/goals-and-audience.md:\n# Goals\n\nFrom ~/.claude/rules/todo-items.md:\n# Todo\n\nFrom ~/.claude/skills/larv-review/standards/comments.md:\n# Comments"))
|
||||
config.write_text(config.read_text().replace('"~/.claude/skills/larv-review/standards"', '"~/review-standards"'))
|
||||
pathlib.Path(claude_md.parents[1], "review-standards").mkdir()
|
||||
pathlib.Path(claude_md.parents[1], "review-standards", "quality.md").write_text("# Ours\n")
|
||||
self.assertTrue(records.read_records(root, claude_md.parents[1], claude_md.parent).endswith("From ~/.claude/rules/todo-items.md:\n# Todo\n\nFrom ~/review-standards/quality.md:\n# Ours"), "the config's standards folder replaces the default")
|
||||
config.write_text(config.read_text().replace('"~/review-standards"', f'"{root}/standards"'))
|
||||
pathlib.Path(root, "standards").mkdir()
|
||||
pathlib.Path(root, "standards", "quality.md").write_text("# Elsewhere\n")
|
||||
self.assertTrue(records.read_records(root, claude_md.parents[1], claude_md.parent).endswith(f"From {root}/standards/quality.md:\n# Elsewhere"), "a folder outside home is named in full")
|
||||
|
||||
config.write_text(config.read_text().replace('"checkout:AGENTS.md"', '"checkout:docs/decisions.md"'))
|
||||
self.assertTrue(records.read_records(root, claude_md.parents[1], claude_md.parent).startswith("From AGENTS.md and docs/decisions.md:\n# Decisions\n\nFrom ~/.claude/CLAUDE.md:\n# Global"), "a file the config names for two records appears once")
|
||||
config.write_text(config.read_text().replace('"checkout:docs/decisions.md"', '"checkout:AGENTS.md"', 1))
|
||||
|
||||
config.write_text(config.read_text().replace('"checkout:AGENTS.md"', '"folder:AGENTS.md"').replace('"checkout:docs/decisions.md"', '"folder:log/decisions.md"'))
|
||||
self.assertTrue(records.read_records(root, claude_md.parents[1], claude_md.parent).startswith("From ~/.claude/CLAUDE.md:\n# Global"), "the checkout's AGENTS.md and docs/decisions.md are its owners'")
|
||||
pathlib.Path(config.parent, "log").mkdir()
|
||||
pathlib.Path(config.parent, "log", "decisions.md").write_text("# Ours\n")
|
||||
pathlib.Path(config.parent, "AGENTS.md").write_text("# Our rules\n")
|
||||
self.assertTrue(records.read_records(root, claude_md.parents[1], claude_md.parent).startswith("From AGENTS.md:\n# Our rules\n\nFrom docs/decisions.md:\n# Ours\n\nFrom ~/.claude/CLAUDE.md:\n# Global"))
|
||||
config.unlink()
|
||||
self.assertEqual(records.read_records(root, claude_md.parents[1], claude_md.parent), Failure(f"no config names the checkout {root}: write ~/.claude-projects/<key>/config.toml, as `project-config --help` shows - the judge cannot read the records."))
|
||||
|
||||
def test_puts_the_records_handed_in_first_and_reads_only_the_humans_rules_without_a_checkout(self):
|
||||
with tempfile.TemporaryDirectory() as root:
|
||||
claude_md = pathlib.Path(root, "home", ".claude", "CLAUDE.md")
|
||||
configured(self, pathlib.Path(root), home=claude_md.parents[1])
|
||||
claude_md.parent.mkdir(parents=True)
|
||||
claude_md.write_text("# Global\n")
|
||||
pathlib.Path(claude_md.parent, "rules").mkdir()
|
||||
pathlib.Path(claude_md.parent, "rules", "todo-items.md").write_text("# Todo\n")
|
||||
pathlib.Path(claude_md.parent, "skills", "larv-review", "standards").mkdir(parents=True)
|
||||
pathlib.Path(claude_md.parent, "skills", "larv-review", "standards", "comments.md").write_text("# Comments\n")
|
||||
pathlib.Path(root, "AGENTS.md").write_text("# Rules\n")
|
||||
first = (("the epic ABC-1's description, ## Decisions", "Squash.\n"), ("the epic ABC-1's description, ## Scoring", " \n"))
|
||||
self.assertEqual(records.read_records(root, claude_md.parents[1], claude_md.parent, first), "From the epic ABC-1's description, ## Decisions:\nSquash.\n\nFrom AGENTS.md:\n# Rules\n\nFrom ~/.claude/CLAUDE.md:\n# Global\n\nFrom ~/.claude/rules/todo-items.md:\n# Todo\n\nFrom ~/.claude/skills/larv-review/standards/comments.md:\n# Comments")
|
||||
self.assertEqual(records.read_records(None, claude_md.parents[1], claude_md.parent, first), "From the epic ABC-1's description, ## Decisions:\nSquash.\n\nFrom ~/.claude/CLAUDE.md:\n# Global\n\nFrom ~/.claude/rules/todo-items.md:\n# Todo")
|
||||
|
||||
def test_stops_on_a_record_it_cannot_read(self):
|
||||
with tempfile.TemporaryDirectory() as root:
|
||||
claude_md = pathlib.Path(root, "home", ".claude", "CLAUDE.md")
|
||||
configured(self, pathlib.Path(root), home=claude_md.parents[1])
|
||||
claude_md.mkdir(parents=True)
|
||||
self.assertEqual(records.read_records(root, claude_md.parents[1], claude_md.parent), Failure(f"CLAUDE.md in {claude_md.parent}: Is a directory - the judge cannot read the records."))
|
||||
pathlib.Path(root, "docs", "decisions.md").mkdir(parents=True)
|
||||
self.assertEqual(records.read_records(root, claude_md.parents[1], claude_md.parent), Failure(f"cannot read {root}/docs/decisions.md: Is a directory - the judge cannot read the records."))
|
||||
pathlib.Path(root, "AGENTS.md").write_bytes(b"# Rules\n\xff\n")
|
||||
self.assertEqual(records.read_records(root, claude_md.parents[1], claude_md.parent), Failure(f"AGENTS.md in {root} is not UTF-8 on line 2 - the judge cannot read the records."))
|
||||
|
||||
|
||||
def test_stops_on_a_rule_it_cannot_read(self):
|
||||
with tempfile.TemporaryDirectory() as root:
|
||||
claude_md = pathlib.Path(root, "home", ".claude", "CLAUDE.md")
|
||||
configured(self, pathlib.Path(root), home=claude_md.parents[1])
|
||||
rules = pathlib.Path(claude_md.parent, "rules")
|
||||
rules.mkdir(parents=True)
|
||||
pathlib.Path(rules, "todo-items.md").write_bytes(b"\xff\n")
|
||||
self.assertEqual(records.read_records(root, claude_md.parents[1], claude_md.parent), Failure(f"todo-items.md in {rules} is not UTF-8 on line 1 - the judge cannot read the records."))
|
||||
|
||||
|
||||
class JudgeRules(unittest.TestCase):
|
||||
def test_the_judge_prompt_names_every_rule_the_judge_reads_from_the_human(self):
|
||||
self.assertEqual([name for name in records.HUMAN_RULE_NAMES if name not in judge.judge_rules("the ledger", "a-driver")], [])
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,158 @@
|
||||
"""What every entry point says to the worker each cycle. model_routing.review_choice chooses where the reviews run. review_launches and reruns put that choice into sentences, and escalation says where escalated subagents run; rung_sentences returns the sentences of all three. An entry point places them in a chunk's first prompt, as loop-claude does in bin/loop_claude/chunk/fresh_prompt.py. rungs_held repeats them at the end of a prompt after a step-up or an unfinished verdict."""
|
||||
import functools
|
||||
import typing
|
||||
|
||||
from agent_cycle.worker_prompts import answers_recorded, WorkerPrompts
|
||||
from agent_cycle.escalation_mark import asks_higher_rung
|
||||
from model_routing.review_choice import chosen, ReviewChoice
|
||||
from model_routing.route import ESCALATION_MARKER, Route
|
||||
from agent_cycle.routing import escalation_rungs
|
||||
from chunk_driver.project.records import HUMAN_RULE_NAMES, RECORD_FILES, RECORDS_NAMED
|
||||
from review_rules.review_passes import INSTRUCTION_FILES, INSTRUCTION_FOLDERS
|
||||
from text_files.markdown_text import listed, quoted
|
||||
from model_routing.ladder import ProjectRung, Rung
|
||||
|
||||
# Where the judge may quote an answer from, named as the human and the worker see them; of the goals file the judge sees only the premises.
|
||||
QUOTE_SOURCES = listed(("the goals file's Goals and Audience", *RECORD_FILES, *HUMAN_RULE_NAMES), "or")
|
||||
# Where the worker may write an answer the human typed, so it counts as recorded.
|
||||
ANSWER_DESTINATIONS = "the goals file's Goals or Audience, " + ", ".join(RECORD_FILES) + ", the plan or a comment"
|
||||
ANSWERS_RECORDED = answers_recorded(ANSWER_DESTINATIONS)
|
||||
# How review_launches names the reviews: "each reviewer" covers every pass with an agent.
|
||||
EACH_REVIEWER = "each reviewer"
|
||||
EACH_SEAT = "each comprehension seat"
|
||||
THE_SECURITY_PASS = "the security pass's subagent"
|
||||
|
||||
|
||||
# Workers only, not CLAUDE.md, which reviewers load too: a reviewer under a like rule missed findings.
|
||||
READING_RULE = "Read in small pieces: never read more than 80 lines of a file at once, nor take a tool output over 3,000 characters into your context."
|
||||
|
||||
|
||||
|
||||
|
||||
def review_launches(route: Route, project: ProjectRung | None) -> list[str]:
|
||||
"""The sentences naming where to launch reviews, in this order, each from the function that says when it applies; none off the ladder."""
|
||||
if project is None:
|
||||
return []
|
||||
choice = chosen(project, route)
|
||||
return [*shared_launches(choice, route, project), *scan_launch(choice, route), *planning_launch(route, project), *taken_in_launches(choice), *markdown_launch(choice)]
|
||||
|
||||
|
||||
def scan_launch(choice: ReviewChoice, route: Route) -> list[str]:
|
||||
"""Where the security pass runs on another rung than the worker's, the sentence that a full scan runs only from the security pass's subagent, which shared_launches names just before: `Run a full scan only from such a subagent, since the scan's agents run on the model that starts them.`"""
|
||||
return ["Run a full scan only from such a subagent, since the scan's agents run on the model that starts them."] if choice.security != route.rung else []
|
||||
|
||||
|
||||
def planning_launch(route: Route, project: ProjectRung) -> list[str]:
|
||||
"""Where the worker runs below the project's rung, the sentence naming where to launch a subagent that files or scores plan items. On an Opus 5.5 project: `Your rung is below the project's: launch each subagent that files or scores plan items on the rung `~/.claude/bin/subagent-rung --plan claude-opus-5-5 <L>` prints.`"""
|
||||
return [f"Your rung is below the project's: launch each subagent that files or scores plan items on the rung `~/.claude/bin/subagent-rung --plan {project.rung.model} <L>` prints."] if project.ladder.position(route.rung) < project.ladder.position(project.rung) else []
|
||||
|
||||
|
||||
def markdown_launch(choice: ReviewChoice) -> list[str]:
|
||||
"""The sentence that names choice.markdown_only, the rung a reviewer runs on where the branch changes only Markdown no agent follows. It is empty where that rung is the reviewers'. rule-hook's reviewer-rung holds a launch to the same rung. On an Opus 5.5 project it ends: `launch each reviewer on the project's rung instead, with the Agent tool set to model opus, effort medium.`"""
|
||||
if choice.markdown_only == choice.reviewers:
|
||||
return []
|
||||
files = ", ".join(f"`{name}`" for name in INSTRUCTION_FILES)
|
||||
folders = listed([f"`{folder}/`" for folder in INSTRUCTION_FOLDERS], "or")
|
||||
return [f"Where your branch changes only Markdown, none of it {files} or under {folders}, launch {EACH_REVIEWER} on the project's rung instead, with the Agent tool set to {choice.markdown_only.agent_args()}."]
|
||||
|
||||
|
||||
def shared_launches(choice: ReviewChoice, route: Route, project: ProjectRung) -> list[str]:
|
||||
"""A sentence for each rung, other than the worker's, that the reviewers, the seats or the security pass run on.
|
||||
|
||||
For a worker one rung below the project's, routed by item 3 of E + I 5, they read: `Launch each reviewer with the Agent tool set to <rung>, the rung item 3's E + I of 5 picks.` and `Launch each comprehension seat and the security pass's subagent with the Agent tool set to <rung>, the project's rung.`
|
||||
"""
|
||||
together = {EACH_REVIEWER: choice.reviewers, EACH_SEAT: choice.seat, THE_SECURITY_PASS: choice.security}
|
||||
launched: dict[Rung, list[str]] = {}
|
||||
for reviews, rung in together.items():
|
||||
if rung != route.rung:
|
||||
launched.setdefault(rung, []).append(reviews)
|
||||
return [f"Launch {listed(reviews, 'and')} with the Agent tool set to {rung.agent_args()}, {rung_named(rung, route, project)}." for rung, reviews in launched.items()]
|
||||
|
||||
|
||||
def taken_in_launches(choice: ReviewChoice) -> list[str]:
|
||||
"""The sentence naming the reviewers' rung each higher E + I picks, so the worker reviews an item it takes in on that rung in the same run, since loop-claude reads a taken-in item's E + I only as the cycle ends, and routes on it from the next cycle. None where no higher E + I picks a higher rung.
|
||||
|
||||
For a worker on the project's rung, routed by an item of E + I 6, it reads: `Where an item you take into the chunk has an E + I of 7 or more, launch each reviewer with the Agent tool set to `<rung>` from 7 and `<rung>` from 8.`
|
||||
"""
|
||||
if not choice.higher:
|
||||
return []
|
||||
picks = [f"`{rung.agent_args()}` from {escape_and_impact}" for rung, escape_and_impact in choice.higher.items()]
|
||||
return [f"Where an item you take into the chunk has an E + I of {min(choice.higher.values())} or more, launch {EACH_REVIEWER} with the Agent tool set to {listed(picks, 'and')}."]
|
||||
|
||||
|
||||
def rung_named(rung: Rung, route: Route, project: ProjectRung) -> str:
|
||||
"""Why a review runs on rung: it is the project's, or the one the route's reviewed_on E + I picks, the item's or one taken in."""
|
||||
if rung == project.rung:
|
||||
return "the project's rung"
|
||||
if route.escape_and_impact_taken_in:
|
||||
return f"the rung picked by an item of E + I {route.escape_and_impact_taken_in} taken into the chunk"
|
||||
return f"the rung item {route.item}'s E + I of {route.escape_and_impact} picks"
|
||||
|
||||
|
||||
def escalation(driver: str, route: Route, project: ProjectRung | None) -> list[str]:
|
||||
"""The prompt's escalation sentences, the marker's among them. None off the ladder or on its top rung. Where escalation_rungs opens none, the worker escalates only with the human's yes.
|
||||
Else they name the rungs escalation_rungs opens to a subagent, and offer to resume the worker one rung up for the rest of the chunk, up to the highest of those rungs.
|
||||
|
||||
For a worker one rung above the project's, routed by item 3 of L 3, they read: `When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `<rung>`, one rung above yours, and on each further trigger one rung higher, up to `<rung>`; above that, ask the human first.`, `Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number.` and `Where the hard part is the rest of the chunk, end your run instead, asking loop-claude for a higher rung and naming a trigger that fired since your last step-up, if any: once the judge finds it in your transcript, the next cycle resumes you one rung up, up to `<rung>`.`
|
||||
"""
|
||||
if project is None or route.rung not in project.ladder.rungs[:-1]:
|
||||
return []
|
||||
marked = f"Open the subagent's prompt with `{ESCALATION_MARKER} <n>:`, n the trigger's number."
|
||||
rungs = [f"`{rung.agent_args()}`" for rung in escalation_rungs(project, route)]
|
||||
if not rungs:
|
||||
return [
|
||||
f"An escalation trigger in `~/.claude/CLAUDE.md` lets you hand the hard part of a task to a subagent with the Agent tool set to `{project.ladder.climbed(route.rung, 1).agent_args()}`, one rung above yours, only once the human agrees; {driver} will not resume you higher for a trigger either, so ask the human for that yes.",
|
||||
marked,
|
||||
]
|
||||
further = f", and on each further trigger one rung higher, up to {rungs[-1]}" if len(rungs) > 1 else ""
|
||||
return [
|
||||
f"When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to {rungs[0]}, one rung above yours{further}; above that, ask the human first.",
|
||||
marked,
|
||||
f"Where the hard part is the rest of the chunk, end your run instead, {asks_higher_rung(driver)} and naming a trigger that fired since your last step-up, if any: once the judge finds it in your transcript, the next cycle resumes you one rung up, up to {rungs[-1]}.",
|
||||
]
|
||||
|
||||
|
||||
def reruns(route: Route, project: ProjectRung | None) -> list[str]:
|
||||
"""The sentence naming the rung one above a reviewer's and the one above a seat's, on which each reruns when it asks, leaving out either that is already on the top rung. None off the ladder.
|
||||
|
||||
For a worker one rung below the project's, routed by an item of E + I 4, it reads: `A reviewer or comprehension seat that asks for a rerun one rung up reruns with the Agent tool set to `<rung>`.`
|
||||
"""
|
||||
if project is None or route.rung not in project.ladder.rungs:
|
||||
return []
|
||||
choice = chosen(project, route)
|
||||
launched = (("reviewer", choice.reviewers), ("comprehension seat", choice.seat))
|
||||
rerun = {name: project.ladder.climbed(rung, 1) for name, rung in launched if rung != project.ladder.rungs[-1]}
|
||||
if not rerun:
|
||||
return []
|
||||
if len(set(rerun.values())) == 1:
|
||||
return [f"A {listed(list(rerun), 'or')} that asks for a rerun one rung up reruns with the Agent tool set to `{next(iter(rerun.values())).agent_args()}`."]
|
||||
return [f"A reviewer that asks for a rerun one rung up reruns with the Agent tool set to `{rerun['reviewer'].agent_args()}`, and a comprehension seat with `{rerun['comprehension seat'].agent_args()}`."]
|
||||
|
||||
|
||||
def resumed(driver: str, naming: str, unfinished_evidence: str, route: Route, project: ProjectRung | None) -> str:
|
||||
"""naming is the sentence that asks the worker to name its chunk's items, empty where the entry point reads none. Names the worker's rung, so it learns whether its request for a higher rung went through, and the project's again, since a step-up between cycles may have taken the worker above it."""
|
||||
on = f" {driver} runs you on {route.rung}." if project else ""
|
||||
ruled = f" A judge ruled the chunk unfinished, quoting this passage of your transcript as the work remaining:\n\n{quoted(unfinished_evidence)}\n\n" if unfinished_evidence else " "
|
||||
return f"Continue the task; the previous run ended before the chunk was finished.{ruled}The chunk is finished once it is merged, or nothing remains that you could do on your own. Even then, it is finished only once {ANSWERS_RECORDED}.{naming and f' {naming}'}{on}{rungs_held(driver, route, project)}"
|
||||
|
||||
|
||||
def rung_sentences(driver: str, route: Route, project: ProjectRung | None) -> list[str]:
|
||||
"""The sentences that depend on the worker's rung: where its reviews run and rerun, and where its escalated subagents run."""
|
||||
return [*review_launches(route, project), *escalation(driver, route, project), *reruns(route, project)]
|
||||
|
||||
|
||||
def rungs_held(driver: str, route: Route, project: ProjectRung | None) -> str:
|
||||
"""rung_sentences, each after a space, to follow the sentence a prompt ends on."""
|
||||
return "".join(f" {sentence}" for sentence in rung_sentences(driver, route, project))
|
||||
|
||||
|
||||
class RecordNames(typing.NamedTuple):
|
||||
"""The names an entry point's prompts give the places that answer a question, the places that take an answer, and the records the judge reads; WorkerPrompts says what each field is."""
|
||||
quote_sources: str = QUOTE_SOURCES
|
||||
answer_destinations: str = ANSWER_DESTINATIONS
|
||||
records_named: str = RECORDS_NAMED
|
||||
|
||||
|
||||
def worker_prompts(driver: str, fresh: typing.Callable[[str, str, Route, ProjectRung | None, str], str], naming: str, names: RecordNames = RecordNames()) -> WorkerPrompts:
|
||||
"""The prompts of an entry point's cycles: its own fresh prompt, and the resumed prompt and rung sentences every entry point shares, each naming driver. resumed says what naming is. names is loop-claude's unless the entry point keeps records elsewhere, as do-epic does."""
|
||||
return WorkerPrompts(driver, fresh, functools.partial(resumed, driver, naming), functools.partial(rungs_held, driver), *names)
|
||||
@@ -0,0 +1,113 @@
|
||||
import contextlib
|
||||
import dataclasses
|
||||
import io
|
||||
import json
|
||||
import pathlib
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from chunk_driver.doubles import a_loop
|
||||
from chunk_driver import chunk_run, cycle_start
|
||||
from loop_effects.doubles import FakeEffects, NOW
|
||||
from agent_cycle.verdicts import Finished, TakenIn, Unfinished
|
||||
from transcript_archive import outcomes, write
|
||||
from model_routing.ladder import ProjectRung, Rung
|
||||
from model_routing.ladder_file import read_ladder, SHIPPED
|
||||
from text_files.file_writes import replace_file
|
||||
from model_routing.route import Route
|
||||
from agent_cycle import run
|
||||
from claude_code import session
|
||||
from agent_cycle.stop import Stop
|
||||
|
||||
OPUS_PROJECT = ProjectRung(read_ladder(SHIPPED), Rung("claude-opus-5-5", "medium"))
|
||||
|
||||
|
||||
class Steps(unittest.TestCase):
|
||||
OPUS = Rung("claude-opus-5-5", "medium")
|
||||
# The rungs an L 3 and an L 4 pick from OPUS.
|
||||
FABLE_LOW = Rung("claude-fable-5-2", "low")
|
||||
FABLE_MEDIUM = Rung("claude-fable-5-2", "medium")
|
||||
|
||||
def test_a_finished_verdict_clears_the_route_and_the_evidence(self):
|
||||
run_with = chunk_run.ChunkRun(cycle_number=1, unfinished_evidence="old", route=Route(self.OPUS))
|
||||
self.assertEqual(chunk_run.after_verdict(run_with, OPUS_PROJECT, run.Concluded(Finished("x"), run_with.route)), dataclasses.replace(run_with, route=None, unfinished_evidence=""))
|
||||
self.assertEqual(chunk_run.after_verdict(dataclasses.replace(run_with, unfinished_run=3), OPUS_PROJECT, run.Concluded(Finished("x"), run_with.route)).unfinished_run, 0)
|
||||
self.assertEqual(chunk_run.after_verdict(run_with, OPUS_PROJECT, run.Concluded(Unfinished("new", taken_in=TakenIn(highest_likelihood=4)), run_with.route)), dataclasses.replace(run_with, route=Route(self.FABLE_MEDIUM, unfinished=1), unfinished_evidence="new", unfinished_run=1))
|
||||
|
||||
def test_steps_from_the_route_its_cycle_ended_on_which_a_ruling_may_have_raised(self):
|
||||
run_with = chunk_run.ChunkRun(cycle_number=1, unfinished_evidence="", route=Route(self.OPUS, 3, 3, 4))
|
||||
raised = Route(self.FABLE_MEDIUM, 3, 3, 4, escalated_at=5)
|
||||
self.assertEqual(chunk_run.after_verdict(run_with, OPUS_PROJECT, run.Concluded(Unfinished("new"), raised)).route, dataclasses.replace(raised, unfinished=1))
|
||||
|
||||
def test_keeps_the_route_its_cycle_ended_on_off_the_ladder(self):
|
||||
off_ladder = Route(Rung("worker-model"))
|
||||
run_with = chunk_run.ChunkRun(cycle_number=1, unfinished_evidence="")
|
||||
self.assertEqual(chunk_run.after_verdict(run_with, None, run.Concluded(Unfinished("new", "round 2: 🔴", TakenIn(highest_likelihood=4), entries_read=9), off_ladder)).route, off_ladder)
|
||||
|
||||
def test_an_unfinished_verdicts_escalation_marks_the_transcript_entries_the_judge_read(self):
|
||||
run_with = chunk_run.ChunkRun(cycle_number=1, unfinished_evidence="", route=Route(self.FABLE_LOW, 3, 3, 4, escalated_at=2))
|
||||
self.assertEqual(chunk_run.after_verdict(run_with, OPUS_PROJECT, run.Concluded(Unfinished("new", "round 2: 🔴", entries_read=9), run_with.route)).route, Route(self.FABLE_MEDIUM, 3, 3, 4, escalated_at=9))
|
||||
self.assertEqual(chunk_run.after_verdict(run_with, OPUS_PROJECT, run.Concluded(Unfinished("new", entries_read=9), run_with.route)).route, Route(self.FABLE_LOW, 3, 3, 4, unfinished=1, escalated_at=2))
|
||||
|
||||
def test_archives_a_step_up_as_it_happens_so_a_rerun_resumes_on_it(self):
|
||||
with tempfile.TemporaryDirectory() as home:
|
||||
opened = session.session_named("A proj a-driver", pathlib.Path(home, "projects"))
|
||||
archive = pathlib.Path(home, "archive")
|
||||
transcript = pathlib.Path(home, "projects", "-fake", f"{opened.id}.jsonl")
|
||||
transcript.parent.mkdir(parents=True)
|
||||
transcript.write_text(json.dumps({"type": "queue-operation", "timestamp": "1"}) + "\n")
|
||||
before = Route(self.FABLE_LOW, 3, 3, 4)
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
self.assertIsNone(write.archive(archive, str(transcript), "Do it.", outcomes.unfinished(before.worker_line(), "working", "j", ""), NOW, replace=replace_file))
|
||||
after = chunk_run.closed_cycle(chunk_run.ChunkRun(cycle_number=1, unfinished_evidence=""), "Do it.", OPUS_PROJECT, run.Concluded(Unfinished("working", taken_in=TakenIn(highest_likelihood=4)), before), archive, "a-driver", a_loop(FakeEffects().effects(), session=opened))
|
||||
self.assertEqual(cycle_start.archived_route(archive, a_loop(FakeEffects().effects(), session=opened)), Route(self.FABLE_MEDIUM, 3, 3, 4))
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
chunk_run.closed_cycle(after, "Do it.", OPUS_PROJECT, run.Concluded(Finished("done"), after.route), archive, "a-driver", a_loop(FakeEffects().effects(), session=opened))
|
||||
self.assertEqual(cycle_start.archived_route(archive, a_loop(FakeEffects().effects(), session=opened)), Route(self.FABLE_MEDIUM, 3, 3, 4))
|
||||
blocked = pathlib.Path(home, "blocked")
|
||||
blocked.write_text("")
|
||||
stop = chunk_run.closed_cycle(chunk_run.ChunkRun(cycle_number=1, unfinished_evidence=""), "Do it.", OPUS_PROJECT, run.Concluded(Unfinished("working", taken_in=TakenIn(highest_likelihood=4)), before), blocked, "a-driver", a_loop(FakeEffects().effects(), session=opened))
|
||||
self.assertEqual((stop.code, stop.reason.split(":")[0]), (1, "could not archive the transcript"))
|
||||
|
||||
def outcomes_after(self, unfinished_run: int, taken_in: TakenIn) -> tuple[object, str]:
|
||||
"""What closed_cycle answers for a-driver's chunk `Do it.`, after an unfinished verdict that follows unfinished_run others, and the outcomes it archived for a transcript not archived before."""
|
||||
with tempfile.TemporaryDirectory() as home:
|
||||
opened = session.session_named("A proj a-driver", pathlib.Path(home, "projects"))
|
||||
archive = pathlib.Path(home, "archive")
|
||||
transcript = pathlib.Path(home, "projects", "-fake", f"{opened.id}.jsonl")
|
||||
transcript.parent.mkdir(parents=True)
|
||||
transcript.write_text(json.dumps({"type": "queue-operation", "timestamp": "1"}) + "\n")
|
||||
before = Route(self.FABLE_LOW, 3, 3, 4)
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
closed = chunk_run.closed_cycle(chunk_run.ChunkRun(cycle_number=1, unfinished_evidence="", unfinished_run=unfinished_run), "Do it.", OPUS_PROJECT, run.Concluded(Unfinished("working", taken_in=taken_in), before), archive, "a-driver", a_loop(FakeEffects().effects(), session=opened))
|
||||
return closed, "".join(file.read_text() for file in archive.rglob("*") if file.is_file() and file.suffix != ".jsonl")
|
||||
|
||||
def test_a_step_up_archived_first_for_its_transcript_names_the_chunks_task(self):
|
||||
closed, outcomes_kept = self.outcomes_after(0, TakenIn(highest_likelihood=4))
|
||||
self.assertEqual(closed.route.rung, self.FABLE_MEDIUM)
|
||||
self.assertIn("Do it.\n", outcomes_kept)
|
||||
|
||||
def test_the_sixth_unfinished_verdict_running_stops_for_the_human_naming_the_driver_to_rerun_and_archives_why_with_the_task(self):
|
||||
reason = "the human is needed to go on with the chunk, but the judge ruled it unfinished 6 cycles running; finish the chunk yourself, or rerun a-driver to give it 6 more cycles"
|
||||
closed, outcomes_kept = self.outcomes_after(5, TakenIn())
|
||||
self.assertEqual(closed, Stop(2, reason))
|
||||
self.assertIn("Do it.\n", outcomes_kept)
|
||||
self.assertIn(f"Stopped: {reason}\n", outcomes_kept)
|
||||
closed, outcomes_kept = self.outcomes_after(4, TakenIn())
|
||||
self.assertEqual((closed.unfinished_run, outcomes_kept), (5, ""))
|
||||
|
||||
def test_archives_a_higher_e_plus_i_taken_in_so_a_rerun_keeps_it(self):
|
||||
with tempfile.TemporaryDirectory() as home:
|
||||
opened = session.session_named("A proj a-driver", pathlib.Path(home, "projects"))
|
||||
archive = pathlib.Path(home, "archive")
|
||||
transcript = pathlib.Path(home, "projects", "-fake", f"{opened.id}.jsonl")
|
||||
transcript.parent.mkdir(parents=True)
|
||||
transcript.write_text(json.dumps({"type": "queue-operation", "timestamp": "1"}) + "\n")
|
||||
before = Route(self.FABLE_LOW, 3, 3, 4)
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
self.assertIsNone(write.archive(archive, str(transcript), "Do it.", outcomes.unfinished(before.worker_line(), "working", "j", ""), NOW, replace=replace_file))
|
||||
chunk_run.closed_cycle(chunk_run.ChunkRun(cycle_number=1, unfinished_evidence=""), "Do it.", OPUS_PROJECT, run.Concluded(Unfinished("working", taken_in=TakenIn(highest_escape_and_impact=6)), before), archive, "a-driver", a_loop(FakeEffects().effects(), session=opened))
|
||||
self.assertEqual(cycle_start.archived_route(archive, a_loop(FakeEffects().effects(), session=opened)), Route(self.FABLE_LOW, 3, 3, 4, escape_and_impact_taken_in=6))
|
||||
@@ -0,0 +1,41 @@
|
||||
import pathlib
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from failure import Failure
|
||||
from chunk_driver.claims import LOCK, starting
|
||||
|
||||
|
||||
class Starting(unittest.TestCase):
|
||||
def setUp(self) -> None:
|
||||
temp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(temp.cleanup)
|
||||
self.folder = pathlib.Path(temp.name)
|
||||
|
||||
def test_yields_none_while_it_holds_the_lock_in_a_folder_it_makes(self) -> None:
|
||||
with starting(self.folder / "state" / "proj") as failure:
|
||||
self.assertIsNone(failure)
|
||||
self.assertTrue((self.folder / "state" / "proj" / LOCK).is_file())
|
||||
|
||||
def test_yields_a_failure_naming_the_path_it_could_not_make(self) -> None:
|
||||
(self.folder / "state").write_text("", encoding="utf-8")
|
||||
with starting(self.folder / "state") as failure:
|
||||
assert isinstance(failure, Failure)
|
||||
self.assertRegex(failure.reason, f"^cannot lock {self.folder}/state: \\w")
|
||||
|
||||
def test_yields_a_failure_naming_the_lock_it_could_not_open(self) -> None:
|
||||
(self.folder / LOCK).mkdir()
|
||||
with starting(self.folder) as failure:
|
||||
assert isinstance(failure, Failure)
|
||||
self.assertRegex(failure.reason, f"^cannot lock {self.folder}/{LOCK}: \\w")
|
||||
|
||||
def test_an_error_raised_while_the_lock_is_held_is_the_callers(self) -> None:
|
||||
with self.assertRaises(OSError), starting(self.folder):
|
||||
raise OSError("not the lock's")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,204 @@
|
||||
import contextlib
|
||||
import dataclasses
|
||||
import functools
|
||||
import io
|
||||
import json
|
||||
import os
|
||||
import pathlib
|
||||
import sys
|
||||
import tempfile
|
||||
import types
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from chunk_driver.doubles import a_loop
|
||||
from project_config.doubles import configured
|
||||
from agent_cycle.run import Cycle
|
||||
from chunk_driver import cycle_start
|
||||
from failure import Failure
|
||||
from loop_effects.doubles import FakeEffects, NOW, STAMP
|
||||
from git_cli import git_repo
|
||||
from chunk_driver.project.model_choice import Models
|
||||
from transcript_archive import outcomes, write
|
||||
from loop_state.paths import paths_from
|
||||
from model_routing.ladder import ProjectRung, Rung
|
||||
from model_routing.ladder_file import read_ladder, SHIPPED
|
||||
from text_files.file_writes import replace_file
|
||||
from model_routing.route import Route, WorkerLine
|
||||
from claude_code import session
|
||||
from agent_cycle.stop import Stop
|
||||
from agent_cycle.verdicts import TakenIn
|
||||
from agent_cycle.worker_prompts import WorkerPrompts
|
||||
|
||||
OPUS_PROJECT = ProjectRung(read_ladder(SHIPPED), Rung("claude-opus-5-5", "medium"))
|
||||
|
||||
|
||||
class SetupVersion(unittest.TestCase):
|
||||
def test_names_the_release_and_the_commit_or_why_git_cannot_tell(self):
|
||||
with tempfile.TemporaryDirectory() as root:
|
||||
git = functools.partial(git_repo.git, env={**os.environ, "GIT_CONFIG_GLOBAL": os.devnull, "GIT_CONFIG_NOSYSTEM": "1", "GIT_CEILING_DIRECTORIES": root})
|
||||
gone = cycle_start.setup_version(pathlib.Path(root), git)
|
||||
self.assertRegex(gone, r"^unknown: [^\n]*not a git repository")
|
||||
for step in (["init", "-q"], ["-c", "user.name=t", "-c", "user.email=t@t", "commit", "-q", "--allow-empty", "-m", "one"]):
|
||||
self.assertIsInstance(git(*step, cwd=root), str)
|
||||
head = git("rev-parse", "HEAD", cwd=root).strip()
|
||||
self.assertEqual(cycle_start.setup_version(pathlib.Path(root), git), f"{head[:7]} ({head})")
|
||||
git("tag", "v0.1.0", cwd=root)
|
||||
self.assertEqual(cycle_start.setup_version(pathlib.Path(root), git), f"v0.1.0 ({head})")
|
||||
git("-c", "user.name=t", "-c", "user.email=t@t", "commit", "-q", "--allow-empty", "-m", "two", cwd=root)
|
||||
head = git("rev-parse", "HEAD", cwd=root).strip()
|
||||
self.assertEqual(cycle_start.setup_version(pathlib.Path(root), git), f"v0.1.0-1-g{head[:7]} ({head})")
|
||||
|
||||
def test_names_why_git_cannot_name_the_commit_on_one_line(self):
|
||||
def fake_git(*args, cwd=None):
|
||||
return Failure("fatal: bad HEAD\nhint: repair it") if args[0] == "rev-parse" else "v0.1.0\n"
|
||||
|
||||
self.assertEqual(cycle_start.setup_version(pathlib.Path("/r"), fake_git), "unknown: fatal: bad HEAD hint: repair it")
|
||||
|
||||
|
||||
class ProjectRouting(unittest.TestCase):
|
||||
def setUp(self):
|
||||
temp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(temp.cleanup)
|
||||
self.home = pathlib.Path(temp.name)
|
||||
self.paths = paths_from(self.home)
|
||||
self.checkout = self.home / "code" / "acme"
|
||||
self.checkout.mkdir(parents=True)
|
||||
self.config = configured(self, self.checkout, home=self.home)
|
||||
self.paths.models_file.parent.mkdir(exist_ok=True)
|
||||
|
||||
def routing(self, fake=None, env=None):
|
||||
return cycle_start.project_routing(a_loop((fake or FakeEffects()).effects(), root=str(self.checkout), paths=self.paths, env=env or {}), "a-driver")
|
||||
|
||||
def test_routes_on_the_projects_saved_model_and_names_the_shipped_ladder_or_the_projects_own_as_its_file(self):
|
||||
self.paths.models_file.write_text(json.dumps({"acme": "claude-opus-5-5"}))
|
||||
shipped = read_ladder(SHIPPED)
|
||||
self.assertEqual(self.routing(), cycle_start.Routing(Models("claude-opus-5-5", "claude-opus-5-5"), shipped, SHIPPED))
|
||||
self.assertEqual(self.routing(env={"LOOP_CLAUDE_JUDGE_MODEL": "j"}), cycle_start.Routing(Models("j", "claude-opus-5-5"), shipped, SHIPPED))
|
||||
own = self.config / "routing-ladder.json"
|
||||
own.write_text('[{"model": "claude-fable-5-2", "effort": "low"}]', encoding="utf-8")
|
||||
routing = self.routing()
|
||||
assert isinstance(routing, cycle_start.Routing)
|
||||
self.assertEqual((routing.ladder_file, [str(rung) for rung in routing.ladder.rungs]), (own, ["claude-fable-5-2 at low effort"]))
|
||||
|
||||
def test_stops_with_exit_1_naming_the_ladder_file_that_cannot_be_read(self):
|
||||
self.paths.models_file.write_text(json.dumps({"acme": "claude-opus-5-5"}))
|
||||
own = self.config / "routing-ladder.json"
|
||||
own.write_text("not json", encoding="utf-8")
|
||||
stop = self.routing()
|
||||
assert isinstance(stop, Stop)
|
||||
self.assertEqual(stop.code, 1)
|
||||
self.assertIn(str(own), stop.reason)
|
||||
|
||||
def test_stops_with_exit_1_naming_the_config_that_cannot_be_read(self):
|
||||
self.paths.models_file.write_text(json.dumps({"acme": "claude-opus-5-5"}))
|
||||
(self.config / "config.toml").write_text("not toml", encoding="utf-8")
|
||||
stop = self.routing()
|
||||
assert isinstance(stop, Stop)
|
||||
self.assertEqual(stop.code, 1)
|
||||
self.assertIn(str(self.config / "config.toml"), stop.reason)
|
||||
|
||||
def test_asks_for_the_model_where_none_is_saved_and_off_a_terminal_stops_naming_the_driver_to_rerun(self):
|
||||
stop = self.routing(FakeEffects(on_terminal=False))
|
||||
assert isinstance(stop, Stop)
|
||||
self.assertEqual(stop.code, 2)
|
||||
self.assertIn("pick acme's model", stop.reason)
|
||||
self.assertIn("rerun a-driver on a terminal", stop.reason)
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
self.assertEqual(self.routing(FakeEffects(inputs=["claude-opus-5-5"])), cycle_start.Routing(Models("claude-opus-5-5", "claude-opus-5-5"), read_ladder(SHIPPED), SHIPPED))
|
||||
|
||||
|
||||
class CycleStart(unittest.TestCase):
|
||||
ROUTING = cycle_start.Routing(Models("judge-model", "claude-opus-5-5"), OPUS_PROJECT.ladder, SHIPPED)
|
||||
|
||||
def test_announces_the_route_the_chunks_run_holds_and_else_the_one_its_archive_last_names(self):
|
||||
def never():
|
||||
raise AssertionError("not asked")
|
||||
|
||||
kept = Route(Rung("claude-opus-5-5", "xhigh"), 3, 4, 5)
|
||||
with tempfile.TemporaryDirectory() as home:
|
||||
opened = session.session_named("A proj a-driver", pathlib.Path(home, "projects"))
|
||||
loop = a_loop(FakeEffects().effects(), session=opened)
|
||||
archive = pathlib.Path(home, "archive")
|
||||
with contextlib.redirect_stdout(io.StringIO()) as said:
|
||||
self.assertEqual(cycle_start.announced_route(4, kept, self.ROUTING, archive, never, loop), kept)
|
||||
self.assertEqual(said.getvalue(), f"\n{STAMP} === cycle 4, worker on claude-opus-5-5 at xhigh effort ===\n")
|
||||
transcript = pathlib.Path(home, "projects", "-fake", f"{opened.id}.jsonl")
|
||||
transcript.parent.mkdir(parents=True)
|
||||
transcript.write_text(json.dumps({"type": "queue-operation", "timestamp": "1"}) + "\n")
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
self.assertIsNone(write.archive(archive, str(transcript), "Do it.", outcomes.unfinished(kept.worker_line(), "working", "j", ""), NOW, replace=replace_file))
|
||||
with contextlib.redirect_stdout(io.StringIO()):
|
||||
self.assertEqual(cycle_start.announced_route(1, None, self.ROUTING, archive, never, loop), kept)
|
||||
|
||||
def test_builds_the_cycle_from_the_loop_the_routing_and_what_the_entry_point_knows(self):
|
||||
asked = []
|
||||
|
||||
def git(*args, cwd=None):
|
||||
asked.append(cwd)
|
||||
return "v0.1.0\n" if args[0] == "describe" else "abc\n"
|
||||
|
||||
effects = dataclasses.replace(FakeEffects().effects(), git=git)
|
||||
loop, route, archive = a_loop(effects), Route(Rung("claude-opus-5-5", "xhigh"), 3, 4, 5), pathlib.Path("/t/r")
|
||||
prompts = WorkerPrompts("a-driver", lambda *args: "fresh", lambda *args: "resumed", lambda *args: "", "the sources", "the destinations", "the records named")
|
||||
def taken_in(entries):
|
||||
return TakenIn()
|
||||
|
||||
cycle = cycle_start.cycle_of(loop, self.ROUTING, route, archive, task="the task", facts="the facts", premises="the premises", records="the records", unfinished_evidence="the evidence", prompts=prompts, taken_in=taken_in)
|
||||
self.assertEqual(cycle, Cycle(config="v0.1.0 (abc)", effects=effects, facts="the facts", judge=Rung("judge-model"), premises="the premises", project=OPUS_PROJECT, project_archive=archive, records="the records", root="/r",
|
||||
route=route, session=loop.session, task="the task", prompts=prompts, taken_in=taken_in, unfinished_evidence="the evidence", window=loop.window))
|
||||
self.assertEqual(asked, ["/h/.claude", "/h/.claude"])
|
||||
|
||||
|
||||
class Routes(unittest.TestCase):
|
||||
OPUS = Rung("claude-opus-5-5", "medium")
|
||||
SONNET = Rung("claude-sonnet-5-5", "high")
|
||||
|
||||
def test_keeps_a_chunks_route_or_its_archived_one_at_or_above_the_rung_its_item_picks_and_else_routes_afresh(self):
|
||||
item = types.SimpleNamespace(id=3, likelihood=4, escape_and_impact=5)
|
||||
archived = Route(Rung("claude-opus-5-5", "xhigh"), 3, 4, 5)
|
||||
def never():
|
||||
raise AssertionError("not asked")
|
||||
self.assertEqual(cycle_start.routed(archived, None, "worker-model", never, never), Route(Rung("worker-model")))
|
||||
self.assertEqual(cycle_start.routed(archived, OPUS_PROJECT, "claude-opus-5-5", never, never), archived)
|
||||
self.assertEqual(cycle_start.routed(None, OPUS_PROJECT, "claude-opus-5-5", lambda: archived, never), archived)
|
||||
self.assertEqual(cycle_start.routed(None, OPUS_PROJECT, "claude-opus-5-5", lambda: None, lambda: item), Route(Rung("claude-fable-5-2", "medium"), 3, 4, 5))
|
||||
self.assertEqual(cycle_start.routed(Route(self.SONNET), OPUS_PROJECT, "claude-opus-5-5", never, lambda: None), Route(self.OPUS))
|
||||
cheap = Route(self.SONNET, 4, 2, 3)
|
||||
self.assertEqual(cycle_start.routed(cheap, OPUS_PROJECT, "claude-opus-5-5", never, never), cheap)
|
||||
self.assertEqual(cycle_start.routed(Route(Rung("claude-haiku-5-5", "max"), 4, 2, 3), OPUS_PROJECT, "claude-opus-5-5", never, lambda: None), Route(self.OPUS))
|
||||
|
||||
def test_resumes_on_the_archived_route_and_says_why_it_routes_afresh(self):
|
||||
with tempfile.TemporaryDirectory() as home:
|
||||
opened = session.session_named("A proj a-driver", pathlib.Path(home, "projects"))
|
||||
archive = pathlib.Path(home, "archive")
|
||||
transcript = pathlib.Path(home, "projects", "-fake", f"{opened.id}.jsonl")
|
||||
route = Route(Rung("claude-fable-5-2", "low"), 3, 4, 5)
|
||||
with contextlib.redirect_stderr(io.StringIO()) as stderr:
|
||||
self.assertIsNone(cycle_start.archived_route(archive, a_loop(FakeEffects().effects(), session=opened)))
|
||||
transcript.parent.mkdir(parents=True)
|
||||
transcript.write_text(json.dumps({"type": "queue-operation", "timestamp": "1"}) + "\n")
|
||||
self.assertIsNone(cycle_start.archived_route(archive, a_loop(FakeEffects().effects(), session=opened)))
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
self.assertIsNone(write.archive(archive, str(transcript), "Do it.", outcomes.unfinished(route.worker_line(), "working", "j", ""), NOW, replace=replace_file))
|
||||
with contextlib.redirect_stderr(stderr):
|
||||
self.assertEqual(cycle_start.archived_route(archive, a_loop(FakeEffects().effects(), session=opened)), route)
|
||||
self.assertEqual(stderr.getvalue(), "")
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
self.assertIsNone(write.archive(archive, str(transcript), "Do it.", outcomes.stepped_up(WorkerLine('{"model": "claude-opus-5-5", "rung": 3}')), NOW + 1, replace=replace_file))
|
||||
with contextlib.redirect_stderr(io.StringIO()) as stderr:
|
||||
self.assertIsNone(cycle_start.archived_route(archive, a_loop(FakeEffects().effects(), session=opened)))
|
||||
self.assertEqual(stderr.getvalue(), f'{STAMP} routing the chunk afresh: the archive\'s latest Worker: line names no route that can be read: {{"model": "claude-opus-5-5", "rung": 3}}\n')
|
||||
(chunk,) = archive.iterdir()
|
||||
chunk.chmod(0)
|
||||
try:
|
||||
with contextlib.redirect_stderr(io.StringIO()) as stderr:
|
||||
self.assertIsNone(cycle_start.archived_route(archive, a_loop(FakeEffects().effects(), session=opened)))
|
||||
finally:
|
||||
chunk.chmod(0o700)
|
||||
self.assertTrue(stderr.getvalue().startswith(f"{STAMP} routing the chunk afresh: could not read the archive"), stderr.getvalue())
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,120 @@
|
||||
import pathlib
|
||||
import sys
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from model_routing.ladder import ProjectRung, Rung
|
||||
from chunk_driver import prompts
|
||||
from model_routing.ladder_file import read_ladder, SHIPPED
|
||||
from model_routing.route import Route
|
||||
|
||||
LADDER = read_ladder(SHIPPED)
|
||||
# The ladder's rungs around the project's: the one below it, its own, and those one to three steps up.
|
||||
SONNET = Rung("claude-sonnet-5-5", "high")
|
||||
OPUS = Rung("claude-opus-5-5", "medium")
|
||||
FABLE_LOW = Rung("claude-fable-5-2", "low")
|
||||
FABLE_MEDIUM = Rung("claude-fable-5-2", "medium")
|
||||
OPUS_XHIGH = Rung("claude-opus-5-5", "xhigh")
|
||||
OPUS_PROJECT = ProjectRung(LADDER, OPUS)
|
||||
# The sentence with which an entry point that exists only here asks its worker to name the chunk's items.
|
||||
NAMING = "Name the items."
|
||||
SCAN = " Run a full scan only from such a subagent, since the scan's agents run on the model that starts them."
|
||||
SEATS = " Launch each comprehension seat and the security pass's subagent with the Agent tool set to model opus, effort medium, the project's rung."
|
||||
MARKDOWN = " Where your branch changes only Markdown, none of it `CLAUDE.md`, `AGENTS.md`, `workflow-bench/*-prompt.md` or under `agents/`, `principles/`, `rules/` or `skills/`, launch each reviewer on the project's rung instead, with the Agent tool set to model opus, effort medium."
|
||||
|
||||
|
||||
def held(route, project=OPUS_PROJECT):
|
||||
"""The rung sentences a-driver's worker reads on route, each after a space."""
|
||||
return prompts.rungs_held("a-driver", route, project)
|
||||
|
||||
|
||||
def resumed(route, project=OPUS_PROJECT):
|
||||
"""The prompt that resumes a-driver's worker on route, with no evidence of work remaining."""
|
||||
return prompts.resumed("a-driver", NAMING, "", route, project)
|
||||
|
||||
|
||||
class Resumed(unittest.TestCase):
|
||||
def test_resumes_the_worker_saying_when_the_chunk_is_finished(self):
|
||||
self.assertTrue(resumed(Route(Rung("m")), None).startswith("Continue the task; the previous run ended before the chunk was finished. The chunk is finished once"))
|
||||
|
||||
|
||||
class ReviewLaunches(unittest.TestCase):
|
||||
def test_keeps_every_review_on_the_projects_rung_while_the_worker_runs_below_it(self):
|
||||
below = held(Route(SONNET, 3, 2, 4))
|
||||
self.assertTrue(below.startswith(f" Launch each reviewer, each comprehension seat and the security pass's subagent with the Agent tool set to model opus, effort medium, the project's rung.{SCAN} Your rung is below the project's: launch each subagent that files or scores plan items on the rung `~/.claude/bin/subagent-rung --plan claude-opus-5-5 <L>` prints. Where an item you take into the chunk has an E + I of 5 or more, launch each reviewer with the Agent tool set to `model fable, effort low` from 5, `model fable, effort medium` from 6, `model opus, effort xhigh` from 7 and `model fable, effort high` from 8. When an escalation trigger"), below)
|
||||
self.assertNotIn("Launch each", held(Route(OPUS, 3, 2, 4)))
|
||||
|
||||
def test_launches_reviewers_on_the_rung_the_items_e_plus_i_picks_above_the_workers(self):
|
||||
level = held(Route(OPUS, 3, 2, 6))
|
||||
self.assertTrue(level.startswith(f" Launch each reviewer with the Agent tool set to model fable, effort medium, the rung item 3's E + I of 6 picks. Where an item you take into the chunk has an E + I of 7 or more, launch each reviewer with the Agent tool set to `model opus, effort xhigh` from 7 and `model fable, effort high` from 8.{MARKDOWN} When an escalation trigger"), level)
|
||||
below = held(Route(SONNET, 3, 2, 5))
|
||||
self.assertTrue(below.startswith(f" Launch each reviewer with the Agent tool set to model fable, effort low, the rung item 3's E + I of 5 picks.{SEATS}{SCAN} Your rung is below the project's:"), below)
|
||||
self.assertNotIn("Launch each reviewer", held(Route(FABLE_MEDIUM, 3, 4, 6)))
|
||||
|
||||
def test_names_the_reviewers_rung_each_higher_e_plus_i_an_item_taken_in_picks(self):
|
||||
taking_in = " Where an item you take into the chunk has an E + I of 5 or more, launch each reviewer with the Agent tool set to `model fable, effort low` from 5, `model fable, effort medium` from 6, `model opus, effort xhigh` from 7 and `model fable, effort high` from 8."
|
||||
self.assertTrue(held(Route(OPUS, 3, 2, 4)).startswith(f"{taking_in} When an escalation trigger"))
|
||||
self.assertIn(" Where an item you take into the chunk has an E + I of 7 or more, launch each reviewer with the Agent tool set to `model opus, effort xhigh` from 7 and `model fable, effort high` from 8.", held(Route(OPUS, 3, 2, 6)))
|
||||
self.assertIn(" Where an item you take into the chunk has an E + I of 7 or more, launch each reviewer with the Agent tool set to `model opus, effort xhigh` from 7 and `model fable, effort high` from 8.", held(Route(FABLE_MEDIUM, 3, 4, 4)))
|
||||
self.assertNotIn("Where an item you take into", held(Route(OPUS, 3, 2, 8)))
|
||||
self.assertNotIn("Where an item you take into", held(Route(Rung("m")), None))
|
||||
|
||||
def test_launches_reviewers_on_the_rung_the_highest_e_plus_i_taken_in_picks(self):
|
||||
self.assertIn(f"a-driver runs you on claude-opus-5-5 at medium effort. Launch each reviewer with the Agent tool set to model opus, effort xhigh, the rung picked by an item of E + I 7 taken into the chunk. Where an item you take into the chunk has an E + I of 8 or more, launch each reviewer with the Agent tool set to `model fable, effort high` from 8.{MARKDOWN} When an escalation trigger", resumed(Route(OPUS, 3, 2, 5, escape_and_impact_taken_in=7)))
|
||||
self.assertIn(" Launch each reviewer with the Agent tool set to model fable, effort low, the rung picked by an item of E + I 5 taken into the chunk.", held(Route(OPUS, escape_and_impact_taken_in=5)))
|
||||
|
||||
def test_keeps_seats_and_the_security_pass_on_the_projects_rung_while_the_worker_runs_above_it(self):
|
||||
above = Route(FABLE_LOW, 3, 3, 4)
|
||||
sentences = f"{SEATS}{SCAN} Where an item you take into the chunk has an E + I of 6 or more, launch each reviewer with the Agent tool set to `model fable, effort medium` from 6, `model opus, effort xhigh` from 7 and `model fable, effort high` from 8.{MARKDOWN} When an escalation trigger"
|
||||
self.assertIn(f"{prompts.ANSWERS_RECORDED}. {NAMING} a-driver runs you on claude-fable-5-2 at low effort.{sentences}", resumed(above))
|
||||
self.assertNotIn("the project's", resumed(Route(OPUS, 3, 2, 4)))
|
||||
self.assertNotIn("runs you on", resumed(Route(Rung("m")), None))
|
||||
self.assertTrue(held(above).startswith(sentences), held(above))
|
||||
|
||||
def test_lets_a_markdown_only_branch_review_on_the_projects_rung_where_the_reviewers_run_above_it(self):
|
||||
self.assertIn(MARKDOWN, held(Route(OPUS, 3, 2, 7)))
|
||||
self.assertIn(MARKDOWN, held(Route(FABLE_LOW, 3, 3, 4)))
|
||||
self.assertNotIn("only Markdown", held(Route(OPUS, 3, 2, 4)))
|
||||
|
||||
|
||||
class Escalation(unittest.TestCase):
|
||||
def test_names_the_rungs_an_escalation_trigger_lets_the_worker_hand_a_task_to_at_most_two_above_its_items(self):
|
||||
routed = held(Route(OPUS, 3, 2, 4))
|
||||
self.assertTrue(routed.startswith(" Where an item you take into the chunk has an E + I of 5 or more, launch each reviewer with the Agent tool set to `model fable, effort low` from 5, `model fable, effort medium` from 6, `model opus, effort xhigh` from 7 and `model fable, effort high` from 8. When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model fable, effort low`, one rung above yours; above that, ask the human first. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number."), routed)
|
||||
self.assertIn(" When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model fable, effort medium`, one rung above yours, and on each further trigger one rung higher, up to `model opus, effort xhigh`; above that, ask the human first. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number.", held(Route(FABLE_LOW, 3, 3, 4)))
|
||||
self.assertIn(" When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model opus, effort xhigh`, one rung above yours; above that, ask the human first. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number.", held(Route(FABLE_MEDIUM, 3, 3, 4)))
|
||||
self.assertNotIn("escalation", held(Route(Rung("claude-fable-5-2", "max"), 3, 4, 8)))
|
||||
self.assertIn(" An escalation trigger in `~/.claude/CLAUDE.md` lets you hand the hard part of a task to a subagent with the Agent tool set to `model fable, effort high`, one rung above yours, only once the human agrees; a-driver will not resume you higher for a trigger either, so ask the human for that yes.", held(Route(OPUS_XHIGH, 3, 3, 4)))
|
||||
self.assertIn("set to `model fable, effort max`, one rung above yours, only once the human agrees;", held(Route(Rung("claude-fable-5-2", "high"), 3, 4, 5)), "one rung below the top still names the rung above")
|
||||
self.assertNotIn("rerun", held(Route(Rung("claude-opus-5-5", "low"), 3, 3, 4)), "a worker off the ladder is told no rerun rung")
|
||||
self.assertIn("hand the hard part of the task to a subagent with the Agent tool set to `model fable, effort high`, one rung above yours;", held(Route(OPUS_XHIGH, 3, 4, 5)))
|
||||
self.assertNotIn("escalation", held(Route(Rung("m")), None))
|
||||
self.assertNotIn("escalation", held(Route(Rung("claude-opus-5-5", "low"), 3, 3, 4)))
|
||||
unrouted = held(Route(OPUS))
|
||||
self.assertTrue(unrouted.startswith(" Where an item you take into the chunk has an E + I of 5 or more, launch each reviewer with the Agent tool set to `model fable, effort low` from 5, `model fable, effort medium` from 6, `model opus, effort xhigh` from 7 and `model fable, effort high` from 8. When an escalation trigger in `~/.claude/CLAUDE.md` fires, hand the hard part of the task to a subagent with the Agent tool set to `model fable, effort low`, one rung above yours, and on each further trigger one rung higher, up to `model fable, effort medium`; above that, ask the human first. Open the subagent's prompt with `Escalation trigger <n>:`, n the trigger's number. Where the hard part is the rest of the chunk, end your run instead, asking a-driver for a higher rung and naming a trigger that fired since your last step-up, if any: once the judge finds it in your transcript, the next cycle resumes you one rung up, up to `model fable, effort medium`. A reviewer"), unrouted)
|
||||
|
||||
def test_offers_the_worker_a_higher_rung_for_the_rest_of_the_chunk_up_to_the_escalation_cap(self):
|
||||
offer = lambda cap: f" Where the hard part is the rest of the chunk, end your run instead, asking a-driver for a higher rung and naming a trigger that fired since your last step-up, if any: once the judge finds it in your transcript, the next cycle resumes you one rung up, up to `{cap}`."
|
||||
self.assertIn(f"`Escalation trigger <n>:`, n the trigger's number.{offer('model fable, effort low')}", held(Route(OPUS, 3, 2, 4)))
|
||||
self.assertIn(f"`Escalation trigger <n>:`, n the trigger's number.{offer('model opus, effort xhigh')}", held(Route(FABLE_LOW, 3, 3, 4)))
|
||||
self.assertNotIn("Where the hard part", held(Route(OPUS_XHIGH, 3, 3, 4)))
|
||||
|
||||
|
||||
class Reruns(unittest.TestCase):
|
||||
def test_names_the_rung_a_reviewer_or_seat_reruns_on_one_above_its_own(self):
|
||||
both = " A reviewer or comprehension seat that asks for a rerun one rung up reruns with the Agent tool set to `model fable, effort low`."
|
||||
self.assertTrue(resumed(Route(OPUS, 3, 2, 4)).endswith(both))
|
||||
self.assertTrue(resumed(Route(SONNET, 3, 2, 4)).endswith(both))
|
||||
self.assertTrue(held(Route(OPUS)).endswith(both))
|
||||
self.assertTrue(resumed(Route(FABLE_LOW, 3, 3, 4)).endswith(" A reviewer that asks for a rerun one rung up reruns with the Agent tool set to `model fable, effort medium`, and a comprehension seat with `model fable, effort low`."))
|
||||
self.assertTrue(resumed(Route(OPUS, 3, 2, 7)).endswith(" A reviewer that asks for a rerun one rung up reruns with the Agent tool set to `model fable, effort high`, and a comprehension seat with `model fable, effort low`."))
|
||||
self.assertTrue(resumed(Route(Rung("claude-fable-5-2", "max"), 3, 4, 8)).endswith(" A comprehension seat that asks for a rerun one rung up reruns with the Agent tool set to `model fable, effort low`."))
|
||||
self.assertNotIn("rerun", resumed(Route(Rung("m")), None))
|
||||
self.assertNotIn("rerun", held(Route(Rung("m", "high"), 3, 4, 5), None))
|
||||
fable = Rung("claude-fable-5-2", "max")
|
||||
self.assertNotIn("rerun", resumed(Route(fable), ProjectRung(LADDER, fable)))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,24 @@
|
||||
import dataclasses
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from loop_effects.effects import Effects
|
||||
from loop_state.paths import Paths
|
||||
from claude_code.session import Session
|
||||
from agent_cycle.tmux import Window
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Loop:
|
||||
"""What stays the same while an entry point drives one chunk in one process. loop-claude builds it once per process, so a reload builds it afresh; do-epic builds one per chunk."""
|
||||
# The checkout the loop runs in. loop-claude's LoopRun.root names it too, since a reload hands it on there.
|
||||
root: str
|
||||
# The worker's session.
|
||||
session: Session
|
||||
# The tmux window the loop runs in.
|
||||
window: Window
|
||||
paths: Paths
|
||||
env: typing.Mapping[str, str]
|
||||
# The entry point's script, beside which chunk-preflight lies; an edit of loop-claude's reloads its loop.
|
||||
launcher: pathlib.Path
|
||||
effects: Effects
|
||||
@@ -0,0 +1,70 @@
|
||||
"""The human approval that `chunk-pr merge` waits for where the project's config sets `wait-for-approval`."""
|
||||
import typing
|
||||
|
||||
from forge.reviews import APPROVED, CHANGES_REQUESTED, github_decision, REVIEW_REQUIRED, waiting_threads
|
||||
from failure import Failure
|
||||
from forge.commands import Forge, Run
|
||||
|
||||
# A human answers in hours, so merge polls once a minute and gives up after 90 minutes. That leaves half an hour for the queue and the checks inside the 2 hours a background command may run; a run that needs more is killed before the give-up message prints, and its next run goes on from what it pushed.
|
||||
POLL_SECONDS = 60
|
||||
WAIT_SECONDS = 90 * 60
|
||||
# The environment variable do-epic sets to 1 for its chunks' workers. With it, merge doesn't wait for an approval: do-epic parks the chunk and polls the forge itself, so the chunk holds no running slot meanwhile (docs/decisions.md → `do-epic: drives one Jira epic …`, "Long gates").
|
||||
PARKS = "CHUNK_PR_PARKS"
|
||||
|
||||
|
||||
def awaited(forge: Forge, wait_for_approval: bool, by_human: bool) -> bool | Failure:
|
||||
"""Whether merge waits for an approval. Never where a person merges the pull request (by_human): that person reads its approvals. Otherwise as the project config's `wait-for-approval` says; chunk-pr reads approvals on GitHub only, so a Gitea project that sets it fails, and the chunk never merges past an approval the config requires."""
|
||||
if by_human:
|
||||
return False
|
||||
if wait_for_approval and forge != "gh":
|
||||
return Failure("the project's config sets wait-for-approval, but chunk-pr reads approvals on GitHub only, so it cannot merge this pull request; ask the human to merge it")
|
||||
return wait_for_approval
|
||||
|
||||
|
||||
def approval(number: str, run: Run) -> bool | Failure:
|
||||
"""Whether GitHub reports pull request number approved, as its branch protection asks, read once: False while it still wants a review. A Failure where a reviewer requested changes, or where the protection asks for no review."""
|
||||
decision = github_decision(number, run)
|
||||
if isinstance(decision, Failure):
|
||||
return decision
|
||||
if decision == CHANGES_REQUESTED:
|
||||
return Failure(f"a reviewer requested changes on pull request {number}")
|
||||
if not decision:
|
||||
return Failure("wait-for-approval is set, but the branch protection requires no review, so GitHub reports no decision; ask the human to require a review in the protection or to set wait-for-approval to false")
|
||||
if decision not in (APPROVED, REVIEW_REQUIRED):
|
||||
return Failure(f"GitHub reports the review decision {decision!r} on pull request {number}, and chunk-pr doesn't know that decision")
|
||||
return decision == APPROVED
|
||||
|
||||
|
||||
def approved(number: str, run: Run, sleep: typing.Callable[[float], None]) -> Failure | None:
|
||||
"""None once GitHub reports pull request number approved; a Failure where `approval` fails, where a reviewer's comment waits for an answer, or where no approval came within WAIT_SECONDS."""
|
||||
for waited in range(0, WAIT_SECONDS + 1, POLL_SECONDS):
|
||||
read = approval(number, run)
|
||||
if read is True or isinstance(read, Failure):
|
||||
return None if read is True else read
|
||||
asked = unanswered(number, run)
|
||||
if asked is not None:
|
||||
return asked
|
||||
if waited < WAIT_SECONDS:
|
||||
sleep(POLL_SECONDS)
|
||||
return Failure(f"pull request {number} wasn't approved within {WAIT_SECONDS // 60} minutes; run chunk-pr merge again once it is")
|
||||
|
||||
|
||||
def left_to_park(number: str, run: Run) -> Failure:
|
||||
"""Why a merge under PARKS ends at once where pull request number passed its checks and awaits an approval, in place of waiting as `approved` does: a reviewer's comment waits for an answer, which the worker gives first, or else do-epic parks the chunk, so the worker ends its run."""
|
||||
return unanswered(number, run) or Failure(f"pull request {number} passed its checks and awaits an approval; end your run now, since do-epic parks the chunk and resumes this session once it is approved or a reviewer comments")
|
||||
|
||||
|
||||
def left_to_a_person(number: str, parks: bool) -> str:
|
||||
"""What merge prints where the project's config leaves the merge of pull request number to a person (`merge = "human"`): what the worker does now, which under PARKS is to end its run, as in `left_to_park`."""
|
||||
now = "end your run now, since do-epic parks the chunk and resumes this session once it is merged or a reviewer comments." if parks else "leave the merge to them, and report the chunk as ready to merge. Once it is merged, run chunk-pr clean in this worktree."
|
||||
return f"Marked pull request #{number} ready. It passed its checks and awaits a person's merge, since the project's config sets `merge = \"human\"`: {now}"
|
||||
|
||||
|
||||
def unanswered(number: str, run: Run) -> Failure | None:
|
||||
"""A Failure naming the files where a reviewer's comment waits for an answer on pull request number, as `waiting_threads` finds them, or saying why they cannot be read. None where no thread waits."""
|
||||
waiting = waiting_threads(number, run)
|
||||
if isinstance(waiting, Failure):
|
||||
return waiting
|
||||
if not waiting:
|
||||
return None
|
||||
return Failure(f"a reviewer's comment on pull request {number} waits for an answer, in {', '.join(waiting)}; answer it in its thread, push any fix, and run chunk-pr merge again")
|
||||
@@ -0,0 +1,764 @@
|
||||
"""Open the chunk's pull request as a draft, bring its branch level with origin's default branch, mark it ready, or merge it, with gh where origin is on GitHub and tea elsewhere; once it has merged, remove the chunk's worktree and branch.
|
||||
|
||||
usage: chunk-pr open <title> [<body>]
|
||||
chunk-pr sync
|
||||
chunk-pr ready [<title>]
|
||||
chunk-pr push
|
||||
chunk-pr merge [--finish <ID> [--changelog <bullet> | --no-changelog]]...
|
||||
chunk-pr clean
|
||||
chunk-pr open-epic <epic's key> <title> [<body>]
|
||||
|
||||
Run it in the chunk's worktree, on the chunk's branch. ready and merge act on the branch's open
|
||||
pull request only while its head is the commit checked out, so push before you run them.
|
||||
|
||||
Where the project's config sets `epic-branch` (`project-config --help`), a chunk's pull request
|
||||
goes into its epic's working branch, which chunk-preflight or do-epic recorded for the chunk's
|
||||
branch as it started or continued the chunk. There, each step below reads "origin's default
|
||||
branch" as that branch, with these differences:
|
||||
- merge merges the pull request itself, whatever `merge` and `wait-for-approval` say: those
|
||||
govern the pull request into the default branch, which open-epic opens;
|
||||
- ready and push ask for a review, where the config sets `review-request-comment`, by making
|
||||
that comment on the pull request;
|
||||
- clean still fast-forwards the main checkout to origin's default branch.
|
||||
ready and merge fail, naming both branches, where the forge merges the pull request into another
|
||||
branch than the one recorded, or than the default branch where the checkout records none. A person
|
||||
then settles which holds: they change the pull request's base on the forge, or the record, which
|
||||
is `branch.<branch>.chunk-base` in git's config.
|
||||
|
||||
open pushes the branch, setting its upstream, and opens a draft pull request into origin's
|
||||
default branch. <title> is one line, as ~/.claude/CLAUDE.md → "Git, commits, and PRs"
|
||||
says, and <body> is the pull request's summary. On a branch that fits the config's `branch`
|
||||
template, it refuses a <title> that doesn't fit the `pull-request-title` template the
|
||||
project's config names (`project-config --help`); on any other branch, as for a
|
||||
chunk with no plan item, the title may be the bare summary. It fails where no config names the checkout. Where the branch's pull request is open
|
||||
already, it opens no second one. On origin's default branch it refuses without pushing anything.
|
||||
sync fetches origin and merges its default branch into the branch checked out, where the
|
||||
branch does not hold it already, and prints which it did. Then, where the project's config
|
||||
names a todo.md that exists, it runs `rank_todo.py --check` on it and prints the result,
|
||||
failing where the check fails or no config names the checkout. On a merge conflict it names the conflicted files and leaves the merge in
|
||||
progress, to resolve and commit. On origin's default branch it refuses and doesn't fetch anything.
|
||||
ready marks the pull request ready for review. On Gitea a draft is a pull request whose title
|
||||
starts with `WIP: `, so there it drops that prefix. Given <title>, one line, which it holds
|
||||
to the template as open does, it sets that
|
||||
as the pull request's title first; where that fails, the pull request stays a draft.
|
||||
push pushes the branch, setting its upstream. Where its pull request is open and goes into an
|
||||
epic's working branch, it then asks for a review as ready does. Use it for each push
|
||||
after ready there, and wait for that review as for any other.
|
||||
merge merges the pull request in its turn: the chunks of one project on this machine take
|
||||
turns, one at a time. Run it in the background. In its turn it:
|
||||
1. fetches origin and merges its default branch into the branch, as sync does;
|
||||
2. finishes each plan item a --finish names with `todo-item finish`, passing on
|
||||
--changelog or --no-changelog (a Jira plan takes no --changelog, as todo-item says),
|
||||
and commits what that changed in the plan and the changelog, so both change only
|
||||
at merge time, on top of every chunk merged before;
|
||||
3. pushes, also where step 2 failed after step 1 brought changes in;
|
||||
4. waits for the pull request's checks, and those origin's default branch requires, to
|
||||
pass on the head; where no check reports within a minute, it takes the pull request
|
||||
as having none;
|
||||
5. merges the pull request, only while its head is still the commit checked out, so a
|
||||
push after the gate is never merged. It takes the first merge method the repository
|
||||
allows of: a merge commit, fast-forward only, a rebase followed by a merge commit, a
|
||||
rebase, a squash. GitHub offers only the merge commit, the rebase and the squash.
|
||||
Its last line names each --finish item the plan did not hold when it began: an earlier
|
||||
run finished that item, or its ID is mistyped.
|
||||
Where the project's config sets `wait-for-approval = true` (`project-config --help`), it
|
||||
merges only once GitHub reports the pull request approved as its branch protection
|
||||
requires. It waits for that outside its turn, so other chunks merge meanwhile, and takes
|
||||
a new turn once approved. In a chunk do-epic runs, which sets CHUNK_PR_PARKS=1, it
|
||||
fails at once instead of waiting: do-epic parks the chunk until the approval comes.
|
||||
Where the project's config sets `merge = "human"` (`project-config --help`), it does
|
||||
steps 1 to 4, marks the pull request ready in place of step 5, and prints that the pull
|
||||
request awaits a person's merge, exit 0. A plan or changelog in the checkout that step 2
|
||||
finished is a commit on the branch, so it lands with that merge; one in Jira, or in
|
||||
the config's folder, is finished at once. It reads no approval then, whatever
|
||||
`wait-for-approval` says. Once a person merged it, run clean.
|
||||
It stops, without merging, and says what to do before running it again:
|
||||
- on a merge conflict in step 1, naming the conflicted files, with the merge in progress;
|
||||
- where `larv-review scoring-run-owed` exits 1 after step 3, because the chunk owes a
|
||||
scoring run it has not recorded;
|
||||
- where origin's default branch has moved since the branch last recorded a paired
|
||||
ruling, since that ruling read a head that no longer merges;
|
||||
- where a check fails, or, on Gitea, where the checks have not all passed within 30
|
||||
minutes; on GitHub, gh watches them until they end;
|
||||
- where other pull requests still hold the turn after 30 minutes, naming the last;
|
||||
- with `wait-for-approval`: where a reviewer requested changes, where the protection
|
||||
requires no review, on Gitea, where it cannot read the config, and after 90 minutes
|
||||
without an approval;
|
||||
- with `wait-for-approval`, approved or not: where a reviewer's comment waits for an
|
||||
answer, which is a review thread nobody resolved whose last comment is not the pull
|
||||
request author's. Answer it in its thread and push any fix.
|
||||
A run that waits for an approval takes two turns, so it can last the 90 minutes and,
|
||||
twice, the 30 minutes in the queue and the checks. One killed before that left the
|
||||
branch pushed, so run it again.
|
||||
clean acts once the forge reports the branch's pull request merged at the commit checked out,
|
||||
by any merge method. It fetches origin, fast-forwards the main checkout to origin's
|
||||
default branch, removes the chunk's worktree, then deletes the local branch; origin's
|
||||
branch stays. Where the worktree has uncommitted or untracked files, it refuses and
|
||||
doesn't touch anything. Where the main checkout has uncommitted or untracked files, another
|
||||
branch checked out, or commits origin's default branch lacks, it leaves that as it was,
|
||||
still removes the worktree and the branch, and fails saying why.
|
||||
open-epic runs in any checkout of the repository, once the epic's last chunk has merged. It
|
||||
fetches origin and brings the working branch of the epic named level with origin's
|
||||
default branch, by a merge commit pushed to origin. Then it opens the pull request from
|
||||
that branch into the default branch, ready and titled <title>, and leaves it to a person
|
||||
to merge. Where the two don't merge cleanly it doesn't open anything and says how a
|
||||
person merges them. Where the pull request is open already, it doesn't open a second
|
||||
one. It fails where the config sets no `epic-branch`, or origin has no such branch, as
|
||||
once its pull request has merged and the forge deleted it.
|
||||
|
||||
It prints what it did, exit 0, or why it failed, exit 1.
|
||||
"""
|
||||
import contextlib
|
||||
import dataclasses
|
||||
import fcntl
|
||||
import functools
|
||||
import json
|
||||
import os
|
||||
import pathlib
|
||||
import sys
|
||||
import time
|
||||
import typing
|
||||
|
||||
from chunk_pr.approval import approval, approved, awaited, left_to_a_person, left_to_park, PARKS, unanswered
|
||||
from forge.pulls import checks_passed, merged_pull, open_pull, other_base, required_checks
|
||||
from git_cli.git_repo import CHUNK_BASE, Git
|
||||
from git_cli import epic_branch
|
||||
from failure import Failure
|
||||
from forge.commands import Forge, forge_of, gitea, Run, runner
|
||||
from atlassian.jira import ISSUE_KEY
|
||||
from project_config.main import located
|
||||
from project_config.settings import ProjectConfig
|
||||
from plan_store.plans import says_no_item
|
||||
from project_config import templates
|
||||
|
||||
BIN = pathlib.Path(__file__).resolve().parents[1]
|
||||
# How long merge waits for a check to report before it takes a pull request without any as passed: CI queues its checks within seconds of a push, and merge may run right after one.
|
||||
NO_CHECKS_SECONDS = 60
|
||||
# The file, in the git folder that every worktree of the checkout shares, that a merge keeps locked with flock for its turn: so every chunk of the project on this machine queues on it.
|
||||
QUEUE = "chunk-pr-merge-queue"
|
||||
# A turn lasts as long as its checks, which chunk-pr waits half an hour for on Gitea, so a queue still held after that is reported, not waited out.
|
||||
QUEUE_SECONDS = 30 * 60
|
||||
QUEUE_POLL_SECONDS = 10
|
||||
# The line record-ruling writes into the comprehension history, as git's -G reads it.
|
||||
RULING = "^Ruling: "
|
||||
# The project's config, loaded once per step, on the first call that needs it.
|
||||
Config = typing.Callable[[], ProjectConfig | Failure]
|
||||
USAGE = "usage: chunk-pr open <title> [<body>] | chunk-pr sync | chunk-pr ready [<title>] | chunk-pr push | chunk-pr merge [--finish <ID> [--changelog <bullet> | --no-changelog]]... | chunk-pr clean | chunk-pr open-epic <epic's key> <title> [<body>]"
|
||||
|
||||
# Each forge's merge methods in the order merge prefers them, as the repository setting that allows the method and the method's name in the forge's merge call. A merge commit and a fast-forward keep the branch's commits as they are; a rebase or a squash rewrites them.
|
||||
METHODS: dict[Forge, tuple[tuple[str, str], ...]] = {
|
||||
"gh": (("mergeCommitAllowed", "--merge"), ("rebaseMergeAllowed", "--rebase"), ("squashMergeAllowed", "--squash")),
|
||||
"tea": (("allow_merge_commits", "merge"), ("allow_fast_forward_only_merge", "fast-forward-only"), ("allow_rebase_explicit", "rebase-merge"), ("allow_rebase", "rebase"), ("allow_squash_merge", "squash")),
|
||||
}
|
||||
|
||||
|
||||
def main(argv: list[str]) -> int:
|
||||
if argv[:1] in (["-h"], ["--help"]):
|
||||
print(__doc__.strip())
|
||||
return 0
|
||||
done = step(argv, runner(os.getcwd()), functools.cache(lambda: located(os.getcwd(), pathlib.Path.home())), os.environ.get(PARKS) == "1")
|
||||
if isinstance(done, Failure):
|
||||
print(f"chunk-pr: {done.reason}", file=sys.stderr)
|
||||
return 1
|
||||
print(done)
|
||||
return 0
|
||||
|
||||
|
||||
def step(argv: list[str], run: Run, config: Config, parks: bool = False) -> str | Failure:
|
||||
"""Run the step argv names: the line to print, or a Failure. A malformed argv doesn't run anything. parks is whether a merge fails at once where it would wait for an approval (`merged`)."""
|
||||
match argv:
|
||||
case ["open", title, *body] if len(body) <= 1 and not title.startswith("-"):
|
||||
return Failure("give a title of one line") if not one_line(title) else misfit(title, run, config) or opened(title, body[0] if body else "", run)
|
||||
case ["sync"]:
|
||||
return synced(run, config)
|
||||
case ["ready", *title] if len(title) <= 1 and not any(given.startswith("-") for given in title):
|
||||
return Failure("give a title of one line") if title and not one_line(title[0]) else (misfit(title[0], run, config) if title else None) or readied(run, title[0] if title else None, config)
|
||||
# Three readers, seated as those who run `chunk-pr`, picked the spellings `push`, 3-0, and `open-epic`, 2-1.
|
||||
case ["push"]:
|
||||
return pushed(run, config)
|
||||
case ["open-epic", epic, title, *body] if len(body) <= 1 and not any(given.startswith("-") for given in (epic, title)):
|
||||
return Failure("give a title of one line") if not one_line(title) else epic_opened(epic, title, body[0] if body else "", run, config)
|
||||
case ["merge", *given]:
|
||||
finishes = finishes_of(given)
|
||||
return Failure(USAGE) if finishes is None else merged(run, config, time.sleep, finishes=finishes, parks=parks)
|
||||
case ["clean"]:
|
||||
return cleaned(run)
|
||||
return Failure(USAGE)
|
||||
|
||||
|
||||
def misfit(title: str, run: Run, config: Config) -> Failure | None:
|
||||
"""Why title doesn't fit the `pull-request-title` template the project's config names, as templates.misfits rules; None where it fits. A config that cannot be read fails, so that no pull request reaches the project's owners under a title they don't use."""
|
||||
loaded = config()
|
||||
if isinstance(loaded, Failure):
|
||||
return loaded
|
||||
branch = run(["git", "symbolic-ref", "--short", "HEAD"])
|
||||
if isinstance(branch, Failure):
|
||||
return branch
|
||||
if not templates.misfits(loaded.pull_request_title, loaded.branch, branch.strip("\n"), title):
|
||||
return None
|
||||
return Failure(f"title the pull request as the project's config asks, `{loaded.pull_request_title}`, where {{id}} is the ID of the chunk's first item; {title.strip()!r} doesn't fit")
|
||||
|
||||
|
||||
def one_line(title: str) -> bool:
|
||||
return bool(title.strip()) and "\n" not in title
|
||||
|
||||
|
||||
def answers(run: Run, *commands: list[str]) -> list[str] | Failure:
|
||||
"""What each git command printed, stripped, or the first Failure."""
|
||||
answered = [run(["git", *args]) for args in commands]
|
||||
failed = next((answer for answer in answered if isinstance(answer, Failure)), None)
|
||||
return failed if failed is not None else [str(answer).strip() for answer in answered]
|
||||
|
||||
|
||||
def checkout(run: Run) -> tuple[Forge, str, str] | Failure:
|
||||
"""The forge, the branch checked out and its head commit."""
|
||||
found = answers(run, ["remote", "get-url", "origin"], ["symbolic-ref", "--short", "HEAD"], ["rev-parse", "HEAD"])
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
origin, branch, head = found
|
||||
return forge_of(origin), branch, head
|
||||
|
||||
|
||||
def default_branch(run: Run) -> str | Failure:
|
||||
"""origin's default branch, such as main. It differs from git_cli's default_ref, which falls back to a local main or master and asks origin where nothing is recorded. A pull request's base is origin's alone, so this fails instead, and says how to record it."""
|
||||
default = run(["git", "symbolic-ref", "--short", "refs/remotes/origin/HEAD"])
|
||||
if isinstance(default, Failure):
|
||||
return Failure(f"origin records no default branch; set it with `git remote set-head origin --auto`: {default.reason}")
|
||||
return default.strip().removeprefix("origin/")
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Base:
|
||||
"""The branch a chunk's pull request merges into. to_epic says it is an epic's working branch, which the chunk merges into whatever the config says of the default branch: `merge = "human"` and `wait-for-approval` govern only the epic branch's own pull request (docs/decisions.md → `epic-branch: an epic's chunks branch off and merge into a working branch …`)."""
|
||||
branch: str
|
||||
to_epic: bool
|
||||
|
||||
|
||||
def base_of(branch: str, run: Run) -> Base | Failure:
|
||||
"""The Base of the pull request from branch: the epic's working branch the checkout records for it (`git_repo.record_chunk_base`), else origin's default branch."""
|
||||
recorded = run(["git", "config", "--get", f"branch.{branch}.{CHUNK_BASE}"])
|
||||
if not isinstance(recorded, Failure) and recorded.strip():
|
||||
return Base(recorded.strip(), True)
|
||||
default = default_branch(run)
|
||||
return default if isinstance(default, Failure) else Base(default, False)
|
||||
|
||||
|
||||
def pull(run: Run) -> tuple[Forge, str, str] | Failure:
|
||||
"""The forge, the number of the branch's open pull request at its head, and that head. A Failure where the forge merges that pull request into another branch than `base_of` names: that base says whether a person merges, so no step acts while the two differ."""
|
||||
found = checkout(run)
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
forge, branch, head = found
|
||||
number = open_pull(forge, branch, head, run)
|
||||
if number is None:
|
||||
return Failure(f"no pull request from origin's {branch} is open at {head[:12]}; push the branch, or open one with chunk-pr open")
|
||||
if isinstance(number, Failure):
|
||||
return number
|
||||
base = base_of(branch, run)
|
||||
if isinstance(base, Failure):
|
||||
return base
|
||||
return other_base(forge, number, base.branch, run) or (forge, number, head)
|
||||
|
||||
|
||||
def opened(title: str, body: str, run: Run) -> str | Failure:
|
||||
found = checkout(run)
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
forge, branch, head = found
|
||||
base = base_of(branch, run)
|
||||
if isinstance(base, Failure):
|
||||
return base
|
||||
if branch == base.branch:
|
||||
return Failure(f"{branch} is origin's default branch; open the pull request from the chunk's branch")
|
||||
pushed = run(["git", "push", "--quiet", "--set-upstream", "origin", branch])
|
||||
if isinstance(pushed, Failure):
|
||||
return pushed
|
||||
number = open_pull(forge, branch, head, run)
|
||||
if isinstance(number, str):
|
||||
return f"Pull request #{number} is open already."
|
||||
if isinstance(number, Failure):
|
||||
return number
|
||||
command = ["gh", "pr", "create"] if forge == "gh" else ["tea", "pulls", "create"]
|
||||
created = run([*command, "--draft", "--head", branch, "--base", base.branch, "--title", title, "--body" if forge == "gh" else "--description", body])
|
||||
if isinstance(created, Failure):
|
||||
return created
|
||||
number = open_pull(forge, branch, head, run)
|
||||
if number is None:
|
||||
return Failure(f"{command[0]} created the pull request, but no pull request from origin's {branch} is listed open at {head[:12]}")
|
||||
return number if isinstance(number, Failure) else f"Opened draft pull request #{number}."
|
||||
|
||||
|
||||
def synced(run: Run, config: Config) -> str | Failure:
|
||||
found = checkout(run)
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
_, branch, _ = found
|
||||
base = base_of(branch, run)
|
||||
if isinstance(base, Failure):
|
||||
return base
|
||||
if branch == base.branch:
|
||||
return Failure(f"{branch} is origin's default branch; sync the chunk's branch")
|
||||
level = levelled(run, branch, base.branch)
|
||||
if isinstance(level, Failure):
|
||||
return level
|
||||
done = f"Merged origin/{base.branch} into {branch}." if level else f"{branch} already holds origin/{base.branch}."
|
||||
loaded = config()
|
||||
if isinstance(loaded, Failure):
|
||||
return Failure(f"{done.removesuffix('.')}, but the plan to check cannot be found: {loaded.reason}")
|
||||
todo = loaded.plan_file
|
||||
# A plan in Jira is no file, and Jira's backlog ranks it.
|
||||
if todo is None or not todo.is_file():
|
||||
return done
|
||||
ranked = run([str(BIN / "rank_todo.py"), "--check", str(todo)])
|
||||
if isinstance(ranked, Failure):
|
||||
return Failure(f"{done.removesuffix('.')}, but rank_todo.py --check todo.md failed: {ranked.reason}")
|
||||
return f"{done}\nrank_todo.py --check todo.md passed."
|
||||
|
||||
|
||||
def levelled(run: Run, branch: str, base: str, resolve: str = "resolve them and commit") -> bool | Failure:
|
||||
"""Fetch origin and merge its base into branch, the one checked out: whether that brought anything in. On a conflict the merge stays in progress, and the Failure names the conflicted files and ends with resolve, the caller's words for what to do about them."""
|
||||
fetched = run(["git", "fetch", "--quiet", "origin"])
|
||||
if isinstance(fetched, Failure):
|
||||
return fetched
|
||||
behind = answers(run, ["rev-list", "--count", f"HEAD..origin/{base}"])
|
||||
if isinstance(behind, Failure):
|
||||
return behind
|
||||
if behind[0] == "0":
|
||||
return False
|
||||
merged = run(["git", "merge", "--quiet", "--no-edit", f"origin/{base}"])
|
||||
if isinstance(merged, Failure):
|
||||
conflicted = answers(run, ["diff", "--name-only", "--diff-filter=U"])
|
||||
if isinstance(conflicted, Failure) or not conflicted[0]:
|
||||
return merged
|
||||
return Failure(f"merging origin/{base} into {branch} conflicts in {', '.join(conflicted[0].splitlines())}; the merge stays in progress: {resolve}")
|
||||
return True
|
||||
|
||||
|
||||
def readied(run: Run, title: str | None, config: Config) -> str | Failure:
|
||||
"""Mark the branch's pull request ready, then ask for a review of it as `review_asked` does."""
|
||||
found = pull(run)
|
||||
marked = found if isinstance(found, Failure) else marked_ready(run, title)
|
||||
if isinstance(found, Failure) or isinstance(marked, Failure):
|
||||
return marked
|
||||
asked = review_asked(found[0], found[1], run, config)
|
||||
if isinstance(asked, Failure):
|
||||
return Failure(f"marked pull request #{found[1]} ready, but could not ask for a review: {asked.reason}")
|
||||
return f"{marked[:-1]}, and asked for a review with “{asked}”." if asked else marked
|
||||
|
||||
|
||||
def marked_ready(run: Run, title: str | None) -> str | Failure:
|
||||
found = pull(run)
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
forge, number, _ = found
|
||||
retitle = ["--title", title] if title is not None else []
|
||||
if forge == "gh":
|
||||
# gh marks a pull request ready only with `gh pr ready`, which takes no title.
|
||||
titled = run(["gh", "pr", "edit", number, *retitle]) if retitle else ""
|
||||
ready = titled if isinstance(titled, Failure) else run(["gh", "pr", "ready", number])
|
||||
else:
|
||||
ready = run(["tea", "pulls", "edit", number, *retitle, "--ready"])
|
||||
if isinstance(ready, Failure):
|
||||
return ready
|
||||
return f"Marked pull request #{number} ready, titled “{title}”." if title is not None else f"Marked pull request #{number} ready."
|
||||
|
||||
|
||||
def pushed(run: Run, config: Config) -> str | Failure:
|
||||
"""Push the branch checked out, and ask for a review of its open pull request as `review_asked` does."""
|
||||
found = checkout(run)
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
forge, branch, head = found
|
||||
sent = run(["git", "push", "--quiet", "--set-upstream", "origin", branch])
|
||||
number = sent if isinstance(sent, Failure) else open_pull(forge, branch, head, run)
|
||||
if isinstance(number, Failure):
|
||||
return number
|
||||
asked = review_asked(forge, number, run, config) if number is not None else None
|
||||
if isinstance(asked, Failure):
|
||||
return Failure(f"pushed {branch}, but could not ask for a review: {asked.reason}")
|
||||
return f"Pushed {branch}, and asked for a review of pull request #{number} with “{asked}”." if asked else f"Pushed {branch}."
|
||||
|
||||
|
||||
def review_asked(forge: Forge, number: str, run: Run, config: Config) -> str | None | Failure:
|
||||
"""Comment on the pull request numbered number with the config's `review-request-comment`, where the pull request goes into an epic's working branch: a forge's auto-reviewer may review only pull requests into the default branch unless asked. The comment made; None where the config names none or the pull request goes into the default branch."""
|
||||
branch = answers(run, ["symbolic-ref", "--short", "HEAD"])
|
||||
base = branch if isinstance(branch, Failure) else base_of(branch[0], run)
|
||||
if isinstance(base, Failure):
|
||||
return base
|
||||
if not base.to_epic:
|
||||
return None
|
||||
loaded = config()
|
||||
if isinstance(loaded, Failure) or loaded.review_request_comment is None:
|
||||
return loaded if isinstance(loaded, Failure) else None
|
||||
comment = loaded.review_request_comment
|
||||
made = run(["gh", "pr", "comment", number, "--body", comment] if forge == "gh" else ["tea", "comment", number, comment])
|
||||
return made if isinstance(made, Failure) else comment
|
||||
|
||||
|
||||
def epic_opened(epic: str, title: str, body: str, run: Run, config: Config) -> str | Failure:
|
||||
"""Bring the working branch of the epic with the key epic level with origin's default branch, then open its pull request into that branch, ready, for a person to merge."""
|
||||
if not ISSUE_KEY.fullmatch(epic):
|
||||
return Failure(f"{epic!r} is no epic's key, such as ABC-123")
|
||||
loaded = config()
|
||||
if isinstance(loaded, Failure):
|
||||
return loaded
|
||||
if loaded.epic_branch is None:
|
||||
return Failure("the project's config sets no `epic-branch`, so the epic has no branch to open a pull request from (`project-config --help`)")
|
||||
branch = templates.epic_branch(loaded.epic_branch, epic)
|
||||
found = answers(run, ["remote", "get-url", "origin"])
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
default = default_branch(run)
|
||||
if isinstance(default, Failure):
|
||||
return default
|
||||
forge = forge_of(found[0])
|
||||
git: Git = lambda *args, cwd=None, timeout=None, guarded=False, errors="strict": run(["git", *args])
|
||||
# `levelled` makes a branch origin lacks, which here would be a stray one: a mistyped key, or a branch its merge deleted.
|
||||
held = epic_branch.on_origin(branch, None, None, git)
|
||||
if not held:
|
||||
return Failure(f"origin has no branch {branch}, so no chunk of {epic} has merged into one: check the epic's key, and whether the branch's pull request merged already")
|
||||
level = held if isinstance(held, Failure) else epic_branch.levelled(branch, f"origin/{default}", run=git)
|
||||
head = level if isinstance(level, Failure) else answers(run, ["rev-parse", f"origin/{branch}"])
|
||||
number = head if isinstance(head, Failure) else open_pull(forge, branch, head[0], run)
|
||||
if isinstance(number, Failure):
|
||||
return number
|
||||
if number is not None:
|
||||
return f"{level} Pull request #{number} from {branch} is open already."
|
||||
command = ["gh", "pr", "create"] if forge == "gh" else ["tea", "pulls", "create"]
|
||||
created = run([*command, "--head", branch, "--base", default, "--title", title, "--body" if forge == "gh" else "--description", body])
|
||||
return created if isinstance(created, Failure) else f"{level} Opened the pull request from {branch} into {default}, which a person merges."
|
||||
|
||||
|
||||
def finishes_of(given: list[str]) -> list[list[str]] | None:
|
||||
"""`todo-item finish`'s arguments for each item that merge's flags name, in their order; None where the flags are malformed."""
|
||||
finishes, rest = [], given
|
||||
while rest:
|
||||
match rest:
|
||||
case ["--finish", item, "--changelog", bullet, *rest] if item.isdigit():
|
||||
finishes.append([item, "--changelog", bullet])
|
||||
case ["--finish", item, "--no-changelog", *rest] if item.isdigit():
|
||||
finishes.append([item, "--no-changelog"])
|
||||
case ["--finish", item, *rest] if item.isdigit():
|
||||
finishes.append([item])
|
||||
case _:
|
||||
return None
|
||||
return finishes
|
||||
|
||||
|
||||
def merged(run: Run, config: Config, sleep: typing.Callable[[float], None], finishes: typing.Sequence[list[str]] = (), parks: bool = False) -> str | Failure:
|
||||
"""Merge the branch's pull request in the project's merge queue. Each pass of the loop is one turn in the queue; a pull request that still wants its approval leaves the queue while it waits, so the next chunk merges meanwhile, and takes a new turn once approved. Where parks, it doesn't wait for the approval: it fails at once, as `left_to_park` says. Where the project's config leaves the merge to a person, the turn ends with the pull request ready, as `left_to_a_person` says."""
|
||||
found = pull(run)
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
forge, number, _ = found
|
||||
loaded = config()
|
||||
if isinstance(loaded, Failure):
|
||||
return loaded
|
||||
branch = answers(run, ["symbolic-ref", "--short", "HEAD"])
|
||||
base = branch if isinstance(branch, Failure) else base_of(branch[0], run)
|
||||
if isinstance(base, Failure):
|
||||
return base
|
||||
by_human = loaded.merge == "human" and not base.to_epic
|
||||
waits = awaited(forge, loaded.wait_for_approval and not base.to_epic, by_human)
|
||||
if isinstance(waits, Failure):
|
||||
return waits
|
||||
method = merge_method(forge, run)
|
||||
if isinstance(method, Failure):
|
||||
return method
|
||||
required = required_checks(forge, base.branch, run)
|
||||
if isinstance(required, Failure):
|
||||
return required
|
||||
queue = answers(run, ["rev-parse", "--path-format=absolute", "--git-common-dir"])
|
||||
if isinstance(queue, Failure):
|
||||
return queue
|
||||
absent = unplanned(run, finishes)
|
||||
if isinstance(absent, Failure):
|
||||
return absent
|
||||
file = pathlib.Path(queue[0]) / QUEUE
|
||||
pull_request = Merging(forge, number, method, base.branch, required, waits, by_human)
|
||||
while True:
|
||||
with turn(file, number, sleep) as untaken:
|
||||
taken = untaken or merge_turn(pull_request, finishes, loaded, run, sleep)
|
||||
if isinstance(taken, AwaitsMerge):
|
||||
return left_to_a_person(number, parks) + absent
|
||||
if not isinstance(taken, AwaitsApproval):
|
||||
return taken if isinstance(taken, Failure) else taken + absent
|
||||
if parks:
|
||||
return left_to_park(number, run)
|
||||
# Out of the queue, so the project's other chunks merge while this one waits.
|
||||
waited = approved(number, run, sleep)
|
||||
if isinstance(waited, Failure):
|
||||
return waited
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Merging:
|
||||
"""A pull request that merge takes turns for: its forge and number, the merge method, the branch it merges into (`Base`) with the checks that branch requires, whether it waits for an approval, and whether a person merges it."""
|
||||
forge: Forge
|
||||
number: str
|
||||
method: str
|
||||
base: str
|
||||
required: set[str]
|
||||
waits: bool
|
||||
by_human: bool
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class AwaitsApproval:
|
||||
"""The pull request passed its checks but awaits a human's approval, so merge leaves the queue until it has one."""
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class AwaitsMerge:
|
||||
"""The pull request passed its checks and is marked ready, and the project's config leaves its merge to a person."""
|
||||
|
||||
|
||||
def merge_turn(pull_request: Merging, finishes: typing.Sequence[list[str]], config: ProjectConfig, run: Run, sleep: typing.Callable[[float], None]) -> str | AwaitsApproval | AwaitsMerge | Failure:
|
||||
"""One turn in the queue: level the branch and finish its items, wait for its checks, and merge it where nothing still waits. What merged it, or why it waits or fails. A pull request a person merges is marked ready instead: its finished items are commits on its branch, so they reach the default branch with that person's merge."""
|
||||
head = levelled_and_finished(run, pull_request.base, finishes, config)
|
||||
checked = head if isinstance(head, Failure) else checks_passed(pull_request.forge, pull_request.number, head, pull_request.required, run, sleep, NO_CHECKS_SECONDS)
|
||||
if isinstance(checked, Failure):
|
||||
return checked
|
||||
if pull_request.by_human:
|
||||
marked = marked_ready(run, None)
|
||||
return marked if isinstance(marked, Failure) else AwaitsMerge()
|
||||
ready = approval(pull_request.number, run) if pull_request.waits else True
|
||||
if isinstance(ready, Failure):
|
||||
return ready
|
||||
if not ready:
|
||||
return AwaitsApproval()
|
||||
asked = unanswered(pull_request.number, run) if pull_request.waits else None
|
||||
if asked is not None:
|
||||
return asked
|
||||
# A person may have changed the pull request's base since the turn began, as while its checks ran.
|
||||
if moved := other_base(pull_request.forge, pull_request.number, pull_request.base, run):
|
||||
return moved
|
||||
if pull_request.forge == "gh":
|
||||
done = run(["gh", "pr", "merge", pull_request.number, pull_request.method, "--match-head-commit", str(head)])
|
||||
else:
|
||||
done = gitea(run, f"repos/{{owner}}/{{repo}}/pulls/{pull_request.number}/merge", f"Do={pull_request.method}", f"head_commit_id={head}")
|
||||
return done if isinstance(done, Failure) else f"Merged pull request #{pull_request.number} ({pull_request.method.removeprefix('--')})."
|
||||
|
||||
|
||||
def unplanned(run: Run, finishes: typing.Sequence[list[str]]) -> str | Failure:
|
||||
"""A sentence for merge's last line, naming each item of finishes the plan doesn't hold as merge begins: an earlier run finished it, or its ID is mistyped, and only the reader can tell which. Empty where the plan holds them all."""
|
||||
absent = []
|
||||
for finish in finishes:
|
||||
shown = run([str(BIN / "todo-item"), "show", finish[0]])
|
||||
if isinstance(shown, Failure) and not says_no_item(shown.reason, finish[0]):
|
||||
return shown
|
||||
absent += [finish[0]] if isinstance(shown, Failure) else []
|
||||
return f" The plan held no item {', '.join(absent)} when merge began, so merge left the plan as it was there." if absent else ""
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def turn(queue: pathlib.Path, number: str, sleep: typing.Callable[[float], None]) -> typing.Iterator[Failure | None]:
|
||||
"""Hold the project's merge queue as pull request number: wait until no other chunk-pr merge on this machine holds it, and free it on the way out, however that is. Gives None while it holds the queue; a Failure, without the queue, where another merge still holds it after QUEUE_SECONDS or the file cannot be opened or locked."""
|
||||
try:
|
||||
fd = os.open(queue, os.O_RDWR | os.O_CREAT, 0o644)
|
||||
except OSError as failure:
|
||||
yield Failure(f"cannot take a turn in the merge queue, {queue}: {failure.strerror}")
|
||||
return
|
||||
try:
|
||||
yield held_turn(fd, queue, number, sleep)
|
||||
finally:
|
||||
os.close(fd)
|
||||
|
||||
|
||||
def held_turn(fd: int, queue: pathlib.Path, number: str, sleep: typing.Callable[[float], None]) -> Failure | None:
|
||||
"""Lock the open queue file fd for pull request number and write its number there, for a merge that waits to name; None once held, else why it isn't."""
|
||||
try:
|
||||
for waited in range(0, QUEUE_SECONDS + 1, QUEUE_POLL_SECONDS):
|
||||
try:
|
||||
fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
|
||||
break
|
||||
except BlockingIOError:
|
||||
if waited == QUEUE_SECONDS:
|
||||
holder = os.pread(fd, 20, 0).decode(errors="replace").strip()
|
||||
return Failure(f"the merge queue stayed held for {QUEUE_SECONDS // 60} minutes, last by pull request #{holder or '?'}, so this one took no turn; run chunk-pr merge again")
|
||||
sleep(QUEUE_POLL_SECONDS)
|
||||
os.ftruncate(fd, 0)
|
||||
os.pwrite(fd, number.encode(), 0)
|
||||
except OSError as failure:
|
||||
return Failure(f"cannot take a turn in the merge queue, {queue}: {failure.strerror}")
|
||||
return None
|
||||
|
||||
|
||||
def levelled_and_finished(run: Run, base: str, finishes: typing.Sequence[list[str]], config: ProjectConfig) -> str | Failure:
|
||||
"""What merge does to the branch inside its turn, before the checks: merge origin's base into it, finish the plan items, and push. The head to merge, or why the worker must act first. Whatever it committed is pushed before it fails, so the pull request's head stays the commit checked out."""
|
||||
found = checkout(run)
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
_, branch, before = found
|
||||
moved = levelled(run, branch, base, "resolve them, commit, push, and run chunk-pr merge again")
|
||||
if isinstance(moved, Failure):
|
||||
return moved
|
||||
failed = next((failure for finish in finishes if (failure := finished(run, branch, finish, config))), None)
|
||||
head = answers(run, ["rev-parse", "HEAD"])
|
||||
if isinstance(head, Failure):
|
||||
return head
|
||||
pushed = run(["git", "push", "--quiet", "origin", branch]) if head[0] != before else ""
|
||||
if isinstance(pushed, Failure):
|
||||
return pushed
|
||||
# The scoring run is asked for only now: scoring-run-owed counts as shipped the items the committed plan no longer holds.
|
||||
owed = failed or run([str(BIN / "larv-review"), "scoring-run-owed"])
|
||||
if isinstance(owed, Failure):
|
||||
return owed
|
||||
return remeasure(run, base, config) or head[0]
|
||||
|
||||
|
||||
def finished(run: Run, branch: str, finish: list[str], config: ProjectConfig) -> Failure | None:
|
||||
"""Finish one plan item with `todo-item finish` and commit what that changed. An item the plan no longer holds was finished by an earlier run of merge, which may have stopped before its commit: so the plan and the changelog are committed either way."""
|
||||
shown = run([str(BIN / "todo-item"), "show", finish[0]])
|
||||
if isinstance(shown, Failure) and not says_no_item(shown.reason, finish[0]):
|
||||
return shown
|
||||
finishing = "" if isinstance(shown, Failure) else run([str(BIN / "todo-item"), "finish", *finish])
|
||||
if isinstance(finishing, Failure):
|
||||
return finishing
|
||||
title = templates.title_of(config.commit_title, config.branch, branch, finish[0], f"Finish item {finish[0]} in the plan")
|
||||
# Under `merge = "human"` a plan or changelog outside the checkout is finished here, before the person merges, since no run follows that merge.
|
||||
# A plan in Jira, or a changelog on a Confluence page, is no file to commit.
|
||||
records = [record for record in (config.plan_file, config.paths.get("changelog")) if record is not None and record.is_file()]
|
||||
return committed(run, title, records)
|
||||
|
||||
|
||||
def committed(run: Run, title: str, files: list[pathlib.Path]) -> Failure | None:
|
||||
"""Commit what changed in files under title, each in the git repository that holds it, and only those files: a record the config keeps in its own folder is committed there, where another chunk may commit at the same time."""
|
||||
held: dict[str, list[str]] = {}
|
||||
for file in files:
|
||||
top = run(["git", "-C", str(file.parent), "rev-parse", "--show-toplevel"])
|
||||
if isinstance(top, Failure):
|
||||
return top
|
||||
held.setdefault(top.strip(), []).append(str(file))
|
||||
for top, paths in held.items():
|
||||
changed = run(["git", "-C", top, "status", "--porcelain", "--", *paths])
|
||||
steps = [changed] if isinstance(changed, Failure) or not changed.strip() else [run(["git", "-C", top, "add", "--", *paths]), run(["git", "-C", top, "commit", "--quiet", "-m", title, "--", *paths])]
|
||||
if failed := next((step for step in steps if isinstance(step, Failure)), None):
|
||||
return failed
|
||||
return None
|
||||
|
||||
|
||||
def remeasure(run: Run, base: str, config: ProjectConfig) -> Failure | None:
|
||||
"""A Failure where origin's base has moved since the branch last recorded a paired ruling: that ruling read a head that no longer merges. None where the branch recorded none, or the project keeps its history outside the checkout."""
|
||||
history = config.paths.get("comprehension-history")
|
||||
# A history on a Confluence page is outside the checkout.
|
||||
if history is None:
|
||||
return None
|
||||
top = answers(run, ["rev-parse", "--show-toplevel"])
|
||||
if isinstance(top, Failure) or not history.resolve().is_relative_to(top[0]):
|
||||
return top if isinstance(top, Failure) else None
|
||||
ruled = answers(run, ["log", "-1", "--format=%H", "-G", RULING, f"origin/{base}..HEAD", "--", str(history)])
|
||||
if isinstance(ruled, Failure) or not ruled[0].strip():
|
||||
return ruled if isinstance(ruled, Failure) else None
|
||||
since = answers(run, ["rev-list", "--count", f"{ruled[0].strip()}..origin/{base}"])
|
||||
if isinstance(since, Failure) or since[0].strip() == "0":
|
||||
return since if isinstance(since, Failure) else None
|
||||
return Failure(f"origin/{base} moved after the branch recorded its paired ruling, and its changes are merged in and pushed; run the paired ruling again at the new head, record it, push, and run chunk-pr merge again")
|
||||
|
||||
|
||||
def merge_method(forge: Forge, run: Run) -> str | Failure:
|
||||
"""The first of METHODS[forge] that the repository's settings allow."""
|
||||
if forge == "gh":
|
||||
viewed = run(["gh", "repo", "view", "--json", ",".join(setting for setting, _ in METHODS["gh"])])
|
||||
try:
|
||||
settings = viewed if isinstance(viewed, Failure) else json.loads(viewed)
|
||||
except ValueError:
|
||||
return Failure(f"gh repo view printed no JSON: {str(viewed).strip()[:200]}")
|
||||
else:
|
||||
settings = gitea(run, "repos/{owner}/{repo}")
|
||||
if isinstance(settings, Failure):
|
||||
return settings
|
||||
allowed = next((method for setting, method in METHODS[forge] if isinstance(settings, dict) and settings.get(setting) is True), None)
|
||||
return allowed if allowed is not None else Failure(f"the repository allows none of the merge methods chunk-pr knows: {', '.join(method for _, method in METHODS[forge])}")
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Chunk:
|
||||
"""A merged chunk's worktree and branch, the main checkout of their repository, and origin's default branch."""
|
||||
worktree: str
|
||||
branch: str
|
||||
main: str
|
||||
default: str
|
||||
|
||||
|
||||
def cleaned(run: Run, at: typing.Callable[[str], Run] = runner) -> str | Failure:
|
||||
"""Remove the worktree and branch of the merged chunk run is in, and fast-forward the main checkout; at(folder) runs commands in folder, here the main checkout."""
|
||||
chunk = merged_chunk(run)
|
||||
if isinstance(chunk, Failure):
|
||||
return chunk
|
||||
at_main = at(chunk.main)
|
||||
left = kept_as_it_was(at_main, chunk.default)
|
||||
files = unsaved(run)
|
||||
if isinstance(files, Failure):
|
||||
return files
|
||||
if files:
|
||||
also = f"\nIt would also have left {chunk.main} as it was: {left}" if left else ""
|
||||
return Failure(f"left everything as it was: {chunk.worktree} has uncommitted or untracked files:\n{files}{also}")
|
||||
return removed(chunk, at_main, left)
|
||||
|
||||
|
||||
def merged_chunk(run: Run) -> Chunk | Failure:
|
||||
"""The chunk run is in, once the forge reports its pull request merged at its head. It fetches origin, so the main checkout can fast-forward to the merge."""
|
||||
found = checkout(run)
|
||||
if isinstance(found, Failure):
|
||||
return found
|
||||
forge, branch, head = found
|
||||
default = default_branch(run)
|
||||
if isinstance(default, Failure):
|
||||
return default
|
||||
folders = worktree_and_main(run)
|
||||
if isinstance(folders, Failure):
|
||||
return folders
|
||||
number = merged_pull(forge, branch, head, run)
|
||||
if number is None:
|
||||
return Failure(f"no merged pull request from {branch} at {head[:12]}, so its worktree and branch stay")
|
||||
fetched = number if isinstance(number, Failure) else run(["git", "fetch", "--quiet", "origin"])
|
||||
return fetched if isinstance(fetched, Failure) else Chunk(folders[0], branch, folders[1], default)
|
||||
|
||||
|
||||
def worktree_and_main(run: Run) -> tuple[str, str] | Failure:
|
||||
"""The worktree run is in, and the main checkout of its repository. Run in the main checkout itself, it fails."""
|
||||
folders = answers(run, ["rev-parse", "--show-toplevel"], ["worktree", "list", "--porcelain"])
|
||||
if isinstance(folders, Failure):
|
||||
return folders
|
||||
# git lists the main checkout first.
|
||||
worktree, main = folders[0], folders[1].splitlines()[0].removeprefix("worktree ")
|
||||
return Failure(f"{main} is the main checkout; run clean in the chunk's worktree") if worktree == main else (worktree, main)
|
||||
|
||||
|
||||
def unsaved(run: Run) -> str | Failure:
|
||||
"""The uncommitted and untracked files of the checkout run is in, as git status lists them; empty where there are none."""
|
||||
status = run(["git", "status", "--porcelain"])
|
||||
return status if isinstance(status, Failure) else status.rstrip()
|
||||
|
||||
|
||||
def kept_as_it_was(at_main: Run, default: str) -> str | None:
|
||||
"""Why the main checkout must not move, or None where it may fast-forward to origin's default."""
|
||||
branch = at_main(["git", "symbolic-ref", "--quiet", "--short", "HEAD"])
|
||||
if isinstance(branch, Failure) or branch.strip() != default:
|
||||
return f"it has {'no branch' if isinstance(branch, Failure) else branch.strip()} checked out, not {default}"
|
||||
files = unsaved(at_main)
|
||||
if isinstance(files, Failure):
|
||||
return files.reason
|
||||
if files:
|
||||
return f"it has uncommitted or untracked files:\n{files}"
|
||||
if isinstance(at_main(["git", "merge-base", "--is-ancestor", "HEAD", f"origin/{default}"]), Failure):
|
||||
return f"it holds commits origin/{default} lacks"
|
||||
return None
|
||||
|
||||
|
||||
def removed(chunk: Chunk, at_main: Run, left: str | None) -> str | Failure:
|
||||
"""Fast-forward the main checkout unless left says why not, then remove the chunk's worktree and branch. Every command runs in the main checkout, since the worktree is gone after the removal."""
|
||||
if left is None:
|
||||
forwarded = at_main(["git", "merge", "--quiet", "--ff-only", f"origin/{chunk.default}"])
|
||||
if isinstance(forwarded, Failure):
|
||||
return forwarded
|
||||
removal = at_main(["git", "worktree", "remove", chunk.worktree])
|
||||
# Not -d: merged_chunk found the forge's pull request merged at the branch's head. -d would compare the branch with the main checkout's HEAD or its upstream instead, and after a rebase or squash merge neither need hold its commits.
|
||||
deleted = removal if isinstance(removal, Failure) else at_main(["git", "branch", "--quiet", "-D", chunk.branch])
|
||||
if isinstance(deleted, Failure):
|
||||
return deleted
|
||||
done = f"Removed worktree {chunk.worktree} and branch {chunk.branch}"
|
||||
if left is not None:
|
||||
return Failure(f"{done}, but left {chunk.main} as it was: {left}")
|
||||
return f"{done}, and fast-forwarded {chunk.main} to origin/{chunk.default}."
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,66 +1,21 @@
|
||||
"""The pure choices the preflight's steps act on."""
|
||||
import pathlib
|
||||
import re
|
||||
|
||||
from release_plan.release_standing import chunk_item, Cut, dated_cut, LastCut, ReadyToCut, ReviewDue, Unknown, Unplanned
|
||||
from failure import Failure
|
||||
from chunk_preflight.gathered import Forge, NoItem, Plan
|
||||
from release_plan.todo_table import item_details, items, NoItemsTable
|
||||
from release_plan.release import version
|
||||
from forge.commands import Forge
|
||||
|
||||
# The command each forge's CLI lists pull requests with; pulls_command adds the flags that pick their rows and fields.
|
||||
PULLS_LIST: dict[Forge, tuple[str, ...]] = {"gh": ("gh", "pr", "list"), "tea": ("tea", "pulls", "list")}
|
||||
|
||||
|
||||
def cut_name(cut: LastCut) -> str | None:
|
||||
"""How the preflight names the last cut: the tag, or the version under its dated CHANGELOG.md heading; None where nothing is cut."""
|
||||
if cut.tag is not None:
|
||||
return None if isinstance(cut.tag, Failure) else cut.tag
|
||||
headed = dated_cut(cut.tag, cut.changelog)
|
||||
return None if headed is None else f"{version(headed)} (dated in CHANGELOG.md)"
|
||||
|
||||
|
||||
def planned(todo: str | Failure, cut: LastCut, default: str) -> Plan | NoItem:
|
||||
"""The plan in todo, the default branch's todo.md, with the item the next chunk takes first, release_standing.chunk_item's pick; else why there is none."""
|
||||
where = f"{default}'s todo.md"
|
||||
if isinstance(todo, Failure):
|
||||
return NoItem(f"{where} cannot be read: {todo.reason}.")
|
||||
found = items(todo)
|
||||
if isinstance(found, NoItemsTable):
|
||||
return NoItem(f"{where} holds no items table.")
|
||||
if isinstance(found, Failure):
|
||||
return NoItem(f"{where} cannot be read: {found.reason}.")
|
||||
if isinstance(cut.tag, Failure):
|
||||
return NoItem(f"{default}'s tags cannot be read: {cut.tag.reason}. So which release is next cannot be told. Find the next release yourself.")
|
||||
named = cut_name(cut)
|
||||
last_cut = f"the last cut, {named}" if named is not None else "the start, since no release is cut yet"
|
||||
pick = chunk_item(found, cut)
|
||||
if isinstance(pick, Cut):
|
||||
return NoItem(f"{where} files items under release {version(pick.release)}, which is not after {last_cut}; ask the human which release they belong to.")
|
||||
if isinstance(pick, Unknown):
|
||||
return NoItem(f"{where} may hold no item for the next release after {last_cut}: todo.md's texts since then, or the count of changes since then, cannot be read. Find the next release yourself.")
|
||||
if isinstance(pick, ReadyToCut | ReviewDue | Unplanned):
|
||||
upcoming = f"release {version(pick.release)}, the next after {last_cut}" if pick.release else f"the next release after {last_cut}"
|
||||
if isinstance(pick, ReviewDue):
|
||||
return NoItem(f"{where} holds no item for {upcoming}, and changes are unreleased, so that release's release review is due: no commit titled `Release review of <release>` has landed {'since the cut' if named is not None else 'yet'}. This chunk is that review, as `~/.claude/skills/larv-review/SKILL.md` → \"Release review\" says; once it merges and the release holds no item, the release is ready to cut.")
|
||||
if isinstance(pick, ReadyToCut):
|
||||
return NoItem(f"{where} holds no item for {upcoming}, and changes are unreleased, and its release review has landed, so that release is finished and ready to cut. The working loop stops here. If todo.md renamed that release instead, add `- <old release> renamed to <new release>` to todo.md's `## Renamed` section.")
|
||||
return NoItem(f"{where} holds no item for {upcoming}, and no change is unreleased, so that release is to be planned first.")
|
||||
first = pick.item
|
||||
if first is None:
|
||||
return NoItem(f"every item of release {version(pick.release)} in {where} waits." if pick.release is not None else f"{where}'s items table holds no item.")
|
||||
details = item_details(todo)
|
||||
detail = details.get(first.id, "") if isinstance(details, dict) else f"(todo.md's details cannot be read: {details.reason})"
|
||||
return Plan(found, first, f"{first.tagline}\n\n{detail}".strip())
|
||||
|
||||
|
||||
def worktree_on(porcelain: str, branch: str) -> pathlib.Path | None:
|
||||
"""The worktree on branch, in what `git worktree list --porcelain` printed; None where none is."""
|
||||
for block in porcelain.split("\n\n"):
|
||||
fields = dict(line.partition(" ")[::2] for line in block.splitlines())
|
||||
if fields.get("branch") == f"refs/heads/{branch}":
|
||||
return pathlib.Path(fields["worktree"])
|
||||
return None
|
||||
return next((path for path, on, _ in worktrees(porcelain) if on == branch), None)
|
||||
|
||||
|
||||
def worktrees(porcelain: str) -> list[tuple[pathlib.Path, str, str]]:
|
||||
"""Each worktree on a branch, in what `git worktree list --porcelain` printed: its path, its branch and its head commit."""
|
||||
blocks = [dict(line.partition(" ")[::2] for line in block.splitlines()) for block in porcelain.split("\n\n")]
|
||||
return [(pathlib.Path(fields["worktree"]), fields["branch"].removeprefix("refs/heads/"), fields.get("HEAD", "")) for fields in blocks if fields.get("branch", "").startswith("refs/heads/")]
|
||||
|
||||
|
||||
def worktree_add(branch: str, path: pathlib.Path, default: str, local: bool, pushed: bool) -> tuple[list[str], str]:
|
||||
@@ -73,19 +28,8 @@ def worktree_add(branch: str, path: pathlib.Path, default: str, local: bool, pus
|
||||
return ["worktree", "add", "--quiet", "--no-track", "-b", branch, str(path), default], f"added on the new branch {branch}, made off {default}."
|
||||
|
||||
|
||||
def forge_of(origin_url: str) -> Forge:
|
||||
return "gh" if "github.com" in origin_url else "tea"
|
||||
|
||||
|
||||
def pulls_command(forge: Forge, branch: str) -> list[str]:
|
||||
"""The command that lists open pull requests: gh only branch's, by number and URL; tea every one, by index, head and URL, for facts.open_pulls to pick branch's."""
|
||||
if forge == "gh":
|
||||
return [*PULLS_LIST["gh"], "--head", branch, "--json", "number,url", "--template", "{{range .}}{{.number}}\t{{.url}}\n{{end}}"]
|
||||
return [*PULLS_LIST["tea"], "--fields", "index,head,url", "--output", "tsv"]
|
||||
|
||||
|
||||
def named_paths(text: str, tracked: list[str]) -> list[tuple[str, int]]:
|
||||
"""Each backticked span in text, in order and once, that names a tracked file or folder, with how many of the tracked files it holds: 1 for a file."""
|
||||
spans = dict.fromkeys(span.removesuffix("/") for span in re.findall(r"`([^`\s]+)`", text))
|
||||
held = ((span, sum(path == span or path.startswith(f"{span}/") for path in tracked)) for span in spans)
|
||||
return [(span, count) for span, count in held if count]
|
||||
|
||||
@@ -1,20 +1,41 @@
|
||||
"""The lines the preflight prints, stated from what it gathered."""
|
||||
from release_plan.todo_table import bundle_candidates, BUNDLE_MAX_R, Item, ships_alone
|
||||
from chunk_preflight.choices import cut_name, PULLS_LIST
|
||||
from release_plan.release_standing import dated_cut, LastCut, unreleased_entries
|
||||
from plan.todo_table import bundle_candidates, BUNDLE_MAX_R, Item, ships_alone
|
||||
from touch_predictions.beside import chunks_beside
|
||||
from release_plan.next_chunk import cut_name, NextChunk, NoItem
|
||||
from release_plan.release_standing import dated_cut, LastCut, unreleased_entries, UNSEEN_RELEASES
|
||||
from failure import Failure
|
||||
from chunk_preflight.gathered import Forge, Gathered, ItemFacts, NamedPath, NoItem, Plan, Ran
|
||||
from records.markdown_text import quoted
|
||||
from release_plan.release import version
|
||||
from forge.commands import Forge
|
||||
from chunk_preflight.gathered import Gathered, ItemFacts, NamedPath, Ran
|
||||
from text_files.markdown_text import listed, quoted
|
||||
from chunk_preflight.choices import PULLS_LIST
|
||||
from plan.release import version
|
||||
|
||||
|
||||
# CLAUDE.md → "Working loop" lets up to ten tiny items share a chunk, so a worker never needs more. A release with 24 joinable items would otherwise put about 155 lines of detail in every prompt.
|
||||
JOINING_DETAILS = 10
|
||||
|
||||
|
||||
def render(found: Gathered) -> list[str]:
|
||||
"""One `- ` line per fact, then the item's tagline and detail, and what each tool printed."""
|
||||
"""One `- ` line per fact, then the item's tagline and detail, the detail of each item that may join its chunk, and what each tool printed."""
|
||||
note = [f"- {found.note}"] if found.note else []
|
||||
head = [*note, f"- {last_release(found.default, found.cut)}"]
|
||||
unseen = [f"- {UNSEEN_RELEASES}"] if found.plan_outside else []
|
||||
head = [*note, f"- {last_release(found.default, found.cut)}", *unseen, *merge_lines(found)]
|
||||
paths = f"- The project's config puts its files and plan at: {'; '.join(f'{setting} {path}' for setting, path in found.places.items())}."
|
||||
texts = f"- The project's config sets: {'; '.join(f'{setting} {text}' for setting, text in found.texts.items())}."
|
||||
if isinstance(found.item, NoItem):
|
||||
return [*head, f"- No plan item: {found.item.why} No worktree was made."]
|
||||
return [*head, *item_lines(found.default, found.item)]
|
||||
return [*head, f"- No plan item: {found.item.why} No worktree was made.", paths, texts]
|
||||
lines = item_lines(found.plan, found.item)
|
||||
return [*head, *lines[:2], paths, texts, *lines[2:]]
|
||||
|
||||
|
||||
def merge_lines(found: Gathered) -> list[str]:
|
||||
"""What `merge = "human"` leaves for the worker to know: each worktree a merged pull request left, the items passed over since their pull request awaits a person's merge, or why those pull requests could not be read."""
|
||||
left = [f"- The worktree {worktree.path}, on the branch {worktree.branch}, is left from pull request #{worktree.pull}, which has merged: run `~/.claude/bin/chunk-pr clean` in it as this chunk's first step." for worktree in found.left]
|
||||
items = found.item.plan.items if isinstance(found.item, ItemFacts) else []
|
||||
passed = [f"item {item.id}, by pull request {item.awaits_merge}" for item in items if item.awaits_merge]
|
||||
over = [f"- Items passed over, each finished on a branch whose ready pull request awaits a person's merge: {'; '.join(passed)}. No chunk takes one."] if passed else []
|
||||
unread = [f"- The pull requests that await a person's merge cannot be read, so no item is passed over for one: {found.merges_unread.reason}"] if found.merges_unread else []
|
||||
return [*left, *over, *unread]
|
||||
|
||||
|
||||
def last_release(default: str, release: LastCut) -> str:
|
||||
@@ -32,20 +53,44 @@ def last_release(default: str, release: LastCut) -> str:
|
||||
return f"{cut} Unreleased: {commits}; {changelog}."
|
||||
|
||||
|
||||
def item_lines(default: str, item: ItemFacts) -> list[str]:
|
||||
def item_lines(plan: str, item: ItemFacts) -> list[str]:
|
||||
first = item.plan.first
|
||||
worktree = item.worktree.reason if isinstance(item.worktree, Failure) else f"{item.worktree.path}, {item.worktree.how}"
|
||||
return [
|
||||
f"- The earliest release in {default}'s todo.md: {version(first.release)}. Its first item that does not wait: item {first.id}, {levels(first)}.",
|
||||
f"- The {'next release, after the last cut, that ' + plan + ' names' if item.plan.carried else 'earliest release in ' + plan}: {version(first.release)}. {'The item this chunk starts from, named with --item' if item.plan.named else 'Its first item that does not wait'}: item {first.id}, {levels(first)}.",
|
||||
*carried_lines(item.plan),
|
||||
f"- Worktree: {worktree}",
|
||||
f"- Open pull requests from {item.plan.branch}: {pulls_text(item.pulls, item.plan.branch)}",
|
||||
*bundled(item.plan),
|
||||
*beside(item.plan),
|
||||
*named_lines(item.named),
|
||||
f"\nItem {first.id}'s tagline and detail:\n\n{quoted(item.plan.text)}",
|
||||
*joining_details(item.plan),
|
||||
*(f"\n{printed(shown, done)}" for shown, done in item.tools),
|
||||
]
|
||||
|
||||
|
||||
def carried_lines(plan: NextChunk) -> list[str]:
|
||||
"""What the worker does about the items of a release someone cut while it held them."""
|
||||
over = plan.carried
|
||||
if over is None:
|
||||
return []
|
||||
items, count, them = (f"Items {listed([str(id_) for id_ in over.ids], 'and')} are", "they count", "them") if len(over.ids) > 1 else (f"Item {over.ids[0]} is", "it counts", "it")
|
||||
return [f"- {items} filed under a release already cut, so {count} as release {version(over.into)}'s, the next. Move {them} there as this chunk's first change, with `~/.claude/bin/todo-item move`, and say so in the chunk's opening line. Where todo-item cannot move this plan's items, as in a Jira plan, leave {them} and ask the human, in the chunk's summary, to move {them}."]
|
||||
|
||||
|
||||
def joining_details(plan: NextChunk) -> list[str]:
|
||||
"""The detail of each of the first JOINING_DETAILS items that may join the chunk, in the table's order, and what the worker lacks: an item with no detail, or the items left out."""
|
||||
joining = bundle_candidates(plan.items, plan.first)
|
||||
if not joining:
|
||||
return []
|
||||
shown, left = joining[:JOINING_DETAILS], joining[JOINING_DETAILS:]
|
||||
lines = [f"\nItem {item.id}'s detail:\n\n{quoted(detail)}" if (detail := item.detail) else f"\nItem {item.id} has no detail." for item in shown]
|
||||
if left:
|
||||
lines.append(f"\nThe details of items {listed([str(item.id) for item in left], 'and')} are not quoted: only the first {JOINING_DETAILS} are. Run `~/.claude/bin/todo-item show <ID>` for each.")
|
||||
return lines
|
||||
|
||||
|
||||
def pulls_text(pulls: tuple[Forge, Ran | Failure] | None, branch: str) -> str:
|
||||
"""Each open pull request from branch, by its number and URL, or why none can be listed. No title: on a public forge anyone may open one, and its title would reach the worker's prompt."""
|
||||
if pulls is None:
|
||||
@@ -67,16 +112,31 @@ def open_pulls(stdout: str, forge: Forge, branch: str) -> list[str]:
|
||||
return [f"#{row[0]} {row[2]}" for row in rows if len(row) == 3 and row[1] == branch]
|
||||
|
||||
|
||||
def bundled(plan: Plan) -> list[str]:
|
||||
def bundled(plan: NextChunk) -> list[str]:
|
||||
first, candidates = plan.first, bundle_candidates(plan.items, plan.first)
|
||||
if ships_alone(first):
|
||||
return [f"- Item {first.id} has R above {BUNDLE_MAX_R}, so it ships alone."]
|
||||
if not candidates:
|
||||
return [f"- No other item of release {version(first.release)} may join item {first.id}'s chunk."]
|
||||
listed = [f" - item {item.id}, {levels(item)}, S {item.scores['S']}: {item.tagline}" for item in candidates]
|
||||
listed = [f" - item {item.id}, {levels(item)}, S {item.scores.get('S', 'unscored')}: {item.tagline}" for item in candidates]
|
||||
return [f'- The items of release {version(first.release)} that may join the chunk of item {first.id}, where `~/.claude/CLAUDE.md` → "Working loop" lets them share it:', *listed]
|
||||
|
||||
|
||||
def beside(plan: NextChunk) -> list[str]:
|
||||
"""The items that may start chunks while first's runs, by touch_predictions' pick; no line where none of the release's items holds a prediction."""
|
||||
first = plan.first
|
||||
found = chunks_beside(plan.items, first)
|
||||
if found is None:
|
||||
return []
|
||||
none = f"- No item of release {version(first.release)} may start a chunk beside item {first.id}'s"
|
||||
if isinstance(found, str):
|
||||
return [f"{none}: {found}."]
|
||||
refused = f" Not beside it: {'; '.join(found.refused)}." if found.refused else ""
|
||||
if not found.picked:
|
||||
return [f"{none}.{refused}"]
|
||||
return [f"- The items of release {version(first.release)} that may start chunks beside item {first.id}'s: {', '.join(map(str, found.picked))}. None is predicted to touch a part that item {first.id} touches, or that an item earlier in this list touches. An item this chunk takes doesn't start a chunk of its own.{refused}"]
|
||||
|
||||
|
||||
def named_lines(named: list[NamedPath] | Failure) -> list[str]:
|
||||
if isinstance(named, Failure):
|
||||
return [f"- The files the item names: cannot be listed: {named.reason}"]
|
||||
@@ -98,7 +158,7 @@ def printed(shown: str, done: Ran | Failure) -> str:
|
||||
if isinstance(done, Failure):
|
||||
return f"`{shown}` {done.reason}"
|
||||
output = "\n".join(part.strip() for part in (done.stdout, done.stderr) if part.strip())
|
||||
return f"`{shown}` exited {done.code}, printing:\n\n{quoted(output)}" if output else f"`{shown}` exited {done.code}, printing nothing."
|
||||
return f"`{shown}` exited {done.code}, printing:\n\n{quoted(output)}" if output else f"`{shown}` exited {done.code}, printing no output."
|
||||
|
||||
|
||||
def levels(item: Item) -> str:
|
||||
|
||||
@@ -1,14 +1,11 @@
|
||||
"""What the preflight gathers, which facts.render states."""
|
||||
import dataclasses
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from failure import Failure
|
||||
from release_plan.todo_table import Item
|
||||
from forge.commands import Forge
|
||||
from release_plan.release_standing import LastCut
|
||||
|
||||
# The CLI that lists a forge's pull requests: gh for a github.com origin, tea for any other.
|
||||
Forge = typing.Literal["gh", "tea"]
|
||||
from release_plan.next_chunk import NextChunk, NoItem
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
@@ -19,26 +16,6 @@ class Ran:
|
||||
stderr: str
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Plan:
|
||||
"""The default branch's todo.md items, and `first`: the item the next chunk takes first."""
|
||||
items: list[Item]
|
||||
first: Item
|
||||
# first's tagline and detail.
|
||||
text: str
|
||||
|
||||
@property
|
||||
def branch(self) -> str:
|
||||
"""The branch first's worktree is on."""
|
||||
return f"item-{self.first.id}"
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class NoItem:
|
||||
"""Why the plan names no item for the next chunk, as a sentence the worker reads."""
|
||||
why: str
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Worktree:
|
||||
path: pathlib.Path
|
||||
@@ -58,7 +35,7 @@ class NamedPath:
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class ItemFacts:
|
||||
"""What the preflight found or made for the plan's first item."""
|
||||
plan: Plan
|
||||
plan: NextChunk
|
||||
worktree: Worktree | Failure
|
||||
# The forge whose CLI listed the open pull requests, and how it ran; None without an origin remote.
|
||||
pulls: tuple[Forge, Ran | Failure] | None
|
||||
@@ -67,6 +44,15 @@ class ItemFacts:
|
||||
tools: list[tuple[str, Ran | Failure]]
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class LeftWorktree:
|
||||
"""A worktree on a branch whose pull request has merged."""
|
||||
path: pathlib.Path
|
||||
branch: str
|
||||
# The merged pull request's number.
|
||||
pull: str
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Gathered:
|
||||
"""Everything the preflight read and ran, for facts.render to state."""
|
||||
@@ -77,3 +63,15 @@ class Gathered:
|
||||
cut: LastCut
|
||||
# What was found or made for the plan's first item; else why the plan names none.
|
||||
item: ItemFacts | NoItem
|
||||
# The plan that was read, as release_plan.next_chunk.plan_name names it.
|
||||
plan: str
|
||||
# Each path the project's config sets, and the epic of a plan kept in Jira, by its setting: in the item's worktree where one was made or continued, else in the checkout.
|
||||
places: dict[str, str]
|
||||
# Whether the project's config puts the plan outside the checkout, where a release whose items are all done is not seen.
|
||||
plan_outside: bool
|
||||
# The language and the templates the project's config names, by their settings.
|
||||
texts: dict[str, str]
|
||||
# Why the pull requests that await a person's merge could not be read; None where they were read or not asked for.
|
||||
merges_unread: Failure | None = None
|
||||
# The worktrees `chunk-pr clean` is still to remove.
|
||||
left: tuple[LeftWorktree, ...] = ()
|
||||
|
||||
+119
-45
@@ -1,55 +1,83 @@
|
||||
"""Find the mechanical facts a chunk starts from, so its worker starts from them; with --worktree, also make its worktree.
|
||||
|
||||
usage: chunk-preflight [--worktree]
|
||||
usage: chunk-preflight [--worktree] [--item <ID>]
|
||||
|
||||
Run it inside a project checkout. It fetches origin, when the checkout has that remote, and takes
|
||||
origin's default branch, or else the local main or master. Without --worktree, it still fetches,
|
||||
but it doesn't make a worktree or a branch, and doesn't run any tool in one. loop-claude runs it
|
||||
with --worktree at the checkout root before each chunk's first worker, before it routes the chunk,
|
||||
and quotes what it prints in the worker's prompt. It leaves the checkout as it is, and reads
|
||||
todo.md as the default branch holds it, the plan loop-claude routes on. It prints:
|
||||
todo.md as the default branch holds it, the plan loop-claude routes on. Where the project's config
|
||||
puts todo.md or CHANGELOG.md outside the checkout, it reads that file as it stands. Such a plan
|
||||
no longer names a release whose last item has shipped, so chunk-preflight doesn't see that release,
|
||||
and prints that the release reviews and the cuts are the human's to call. It prints:
|
||||
|
||||
- the last version cut: the newest v* tag on the default branch, or on a branch with no tag the
|
||||
newest version CHANGELOG.md heads `## X.Y.Z - YYYY-MM-DD`; an undated heading doesn't count.
|
||||
Then how many entries the default branch's CHANGELOG.md holds under ## Unreleased, or else how
|
||||
many commits followed the cut: the tag, or the commit that added that heading;
|
||||
- the next release and its first item that does not wait, the item loop-claude routes on, with
|
||||
its L and E + I. An item waits while it is marked question, or while an item still in todo.md
|
||||
blocks it. Where the last cut is a version x.y.z, the next release is the earliest after x.y.z
|
||||
that todo.md has named at that cut or since, less a release its ## Renamed section marks
|
||||
renamed. Where nothing is cut, it is the earliest release todo.md has ever named, less those
|
||||
renamed, so a release whose items are all done still reads as next.
|
||||
- under `merge = "human"` (`project-config --help`), each worktree beside the checkout whose pull
|
||||
request has merged, for the worker to run `chunk-pr clean` in, and each item passed over: one
|
||||
finished on the branch of an open pull request that is not a draft, where the checkout holds
|
||||
the plan. Where no item of the release can start and one awaits such a merge, it names those
|
||||
pull requests and says the working loop stops there;
|
||||
- the next release and its first item that does not wait, the item loop-claude routes on, with its L
|
||||
and E + I; with --item <ID>, the plan item of that ID instead, which loop-claude names in a window
|
||||
named for an item. An item waits while it is marked question, while an item still in todo.md
|
||||
blocks it, or while it awaits such a merge. Where the last cut is a version x.y.z, the next release is the earliest after x.y.z
|
||||
that todo.md has named at that cut or since, less a release its ## Renamed section marks renamed.
|
||||
Where nothing is cut, it is the earliest release todo.md has ever named, less those renamed, so a
|
||||
release whose items are all done still reads as next.
|
||||
Where the next release holds no item, it says so, naming it where todo.md named it since the cut:
|
||||
its release review due where changes are unreleased (the ## Unreleased entries, or else the
|
||||
commits since the cut) and no commit titled `Release review of <release>` followed the tag,
|
||||
finished and ready to cut once one did, and else to be planned first. On a branch with no tag,
|
||||
such a commit counts only where its <release> is after the version under the dated heading.
|
||||
Where todo.md's earliest release is x.y.z or earlier, it says todo.md files items under a release
|
||||
Where todo.md files items under x.y.z or earlier, someone cut a release that still held them:
|
||||
they count as the next release, the earliest after x.y.z that todo.md names or has named
|
||||
since the cut, and a line says to move them there. Where there is no such release, it says todo.md files items under a release
|
||||
already cut;
|
||||
- with --worktree, the item's worktree: a sibling of the checkout named <checkout>-item-<ID>, on
|
||||
the branch item-<ID>. It continues a worktree already on that branch; else it adds one on the
|
||||
- with --worktree, the item's worktree: a sibling of the checkout named <checkout>-<branch>,
|
||||
each / of the branch a dash, on the branch the config's `branch` template names, which is
|
||||
item-<ID> where the config names none. It continues a worktree already on that branch; else it adds one on the
|
||||
local branch, else on a new branch tracking origin's, else on a new branch off the default
|
||||
branch. Without --worktree, it prints that none was made;
|
||||
branch. Without --worktree, it prints that none was made. Where the config sets `epic-branch`
|
||||
(`project-config --help`), it first makes the working branch of the plan's epic on origin, off
|
||||
the default branch, or merges the default branch into it; a new branch is then made off that
|
||||
branch, and the checkout records that the chunk's pull request goes into it, for `chunk-pr`.
|
||||
Where the two don't merge cleanly, it makes no worktree and says how a person merges them;
|
||||
- each path the project's config sets, as `project-config` prints them in that worktree, or else
|
||||
in the checkout;
|
||||
- the language the config names for the project's prose, and its templates for commit titles,
|
||||
pull request titles and branches;
|
||||
- the open pull requests whose head is the item's branch, each by its number and URL, as gh lists
|
||||
them on a github.com origin, and else as tea does. No title reaches the output;
|
||||
- the items of that release that a chunk taking the item may take too: those that are not
|
||||
questions, that have R 5 or less, and that no item outside the chunk blocks; none where the
|
||||
item's own R is above 5;
|
||||
- the items of that release that a chunk taking the item may take too, each with its L, E + I,
|
||||
S and tagline: those that are not questions, that have R 5 or less, and that no item outside
|
||||
the chunk blocks; none where the item's own R is above 5;
|
||||
- the other items of that release that may start chunks while the item's chunk runs, then why each
|
||||
of the rest may not. An item's prediction is the bullets under a `Touches:` line in its detail,
|
||||
which `touch-predictions --help` describes. Another item may start a chunk where it doesn't
|
||||
wait and its prediction shares no part with the item's, or with that of an item picked before
|
||||
it in the plan's order. A part either prediction marks (small) doesn't count. This line is left
|
||||
out where no item of the release that doesn't wait holds a prediction. The plan and the records
|
||||
belong in no prediction, since every chunk writes them;
|
||||
- each file or folder git tracks that the item's tagline or detail names in backticks, with a
|
||||
file's lines or a folder's files, and the item's tagline and detail;
|
||||
- where it made or continued the worktree, what `rank_todo.py --check todo.md`,
|
||||
file's lines or a folder's files, then the item's tagline and detail, then the detail of each
|
||||
of the first {JOINING_DETAILS} items that may join, or that one has none;
|
||||
- where it made or continued the worktree, what `rank_todo.py --check`,
|
||||
`larv-review needs-scoring-run <ID>`, `reading-cost` and `larv-review places` print in it, each
|
||||
with its exit code. reading-cost appends to the worktree's docs/reading-cost.md, for the chunk to
|
||||
commit.
|
||||
with its exit code. reading-cost appends to docs/reading-cost.md where the project's config puts
|
||||
it: in the worktree, the chunk commits it.
|
||||
|
||||
A fact it cannot find it says it cannot, and why, and goes on. A fetch, forge CLI or tool still
|
||||
running after {timeout} seconds, or after the seconds CHUNK_PREFLIGHT_TIMEOUT sets, is stopped; a
|
||||
stopped fetch reads origin as last fetched. With no item, it makes no worktree and runs none of
|
||||
those four tools, --worktree or not.
|
||||
|
||||
Exit 1, saying why, on any argument other than --worktree, -h or --help, on a
|
||||
CHUNK_PREFLIGHT_TIMEOUT that is no number of seconds above 0, or when git cannot start or finds no
|
||||
checkout or no default branch.
|
||||
Exit 1, saying why, on any argument other than --worktree, --item with an ID, -h or --help, on a
|
||||
CHUNK_PREFLIGHT_TIMEOUT that is no number of seconds above 0, when git cannot start or finds no
|
||||
checkout or no default branch, or when no config names the checkout or its config cannot be read.
|
||||
"""
|
||||
import pathlib
|
||||
import re
|
||||
@@ -57,31 +85,42 @@ import subprocess
|
||||
import sys
|
||||
import typing
|
||||
|
||||
from git_cli.git_repo import commit_exists, default_branch, file_at, git, top
|
||||
from release_plan.release_standing import default_plan
|
||||
from git_cli.git_repo import commit_exists, default_branch, file_at, git, record_chunk_base, top
|
||||
from git_cli import epic_branch
|
||||
from failure import Failure
|
||||
from chunk_preflight.gathered import Forge, Gathered, ItemFacts, NamedPath, NoItem, Plan, Ran, Worktree
|
||||
from chunk_preflight.choices import forge_of, named_paths, planned, pulls_command, worktree_add, worktree_on
|
||||
from chunk_preflight.facts import render
|
||||
from forge.commands import Forge, forge_of, Run, runner
|
||||
from chunk_preflight.gathered import Gathered, ItemFacts, LeftWorktree, NamedPath, Ran, Worktree
|
||||
from chunk_preflight.facts import JOINING_DETAILS, render
|
||||
from project_config.main import located
|
||||
from forge.pulls import merged_pull
|
||||
from plan.named_paths import named_paths
|
||||
from release_plan.next_chunk import NextChunk, NoItem, plan_name, planned
|
||||
from release_plan.release_standing import project_plan
|
||||
from project_config.settings import ProjectConfig
|
||||
from chunk_preflight.choices import pulls_command, worktree_add, worktree_on, worktrees
|
||||
from project_config import templates
|
||||
|
||||
BIN = pathlib.Path(__file__).resolve().parents[1]
|
||||
# Each tool run in the item's worktree, {item} standing for the item's ID.
|
||||
TOOLS = (("rank_todo.py", "--check", "todo.md"), ("larv-review", "needs-scoring-run", "{item}"), ("reading-cost",), ("larv-review", "places"))
|
||||
TOOLS = (("rank_todo.py", "--check"), ("larv-review", "needs-scoring-run", "{item}"), ("reading-cost",), ("larv-review", "places"))
|
||||
# Seconds before a fetch, forge CLI or tool is stopped, so a hung one cannot keep the rest from printing; TIMEOUT_SETTING overrides it.
|
||||
TIMEOUT = 60
|
||||
TIMEOUT_SETTING = "CHUNK_PREFLIGHT_TIMEOUT"
|
||||
# The flag that makes the item's worktree and runs TOOLS in it. Three readers seated as the README's audience picked it 2-1 over --start.
|
||||
WORKTREE = "--worktree"
|
||||
# The flag that names the chunk's item. Three readers seated as the README's audience picked it 3-0 over --for, --start and a bare ID.
|
||||
ITEM = "--item"
|
||||
|
||||
|
||||
def main(argv: list[str], env: typing.Mapping[str, str]) -> int:
|
||||
if argv in (["-h"], ["--help"]):
|
||||
print(__doc__.strip().format(timeout=TIMEOUT))
|
||||
print(__doc__.strip().format(timeout=TIMEOUT, JOINING_DETAILS=JOINING_DETAILS))
|
||||
return 0
|
||||
if argv not in ([], [WORKTREE]):
|
||||
print(f"unknown arguments {' '.join(argv)}; usage: chunk-preflight [{WORKTREE}]", file=sys.stderr)
|
||||
rest = [arg for arg in argv if arg != WORKTREE]
|
||||
if len(argv) - len(rest) > 1 or not (rest == [] or (len(rest) == 2 and rest[0] == ITEM and re.fullmatch(r"[0-9]+", rest[1], re.ASCII))):
|
||||
print(f"unknown arguments {' '.join(argv)}; usage: chunk-preflight [{WORKTREE}] [{ITEM} <ID>]", file=sys.stderr)
|
||||
return 1
|
||||
printed = run(env.get(TIMEOUT_SETTING), argv == [WORKTREE])
|
||||
printed = run(env.get(TIMEOUT_SETTING), WORKTREE in argv, int(rest[1]) if rest else None)
|
||||
if isinstance(printed, Failure):
|
||||
print(printed.reason, file=sys.stderr)
|
||||
return 1
|
||||
@@ -89,13 +128,13 @@ def main(argv: list[str], env: typing.Mapping[str, str]) -> int:
|
||||
return 0
|
||||
|
||||
|
||||
def run(setting: str | None, make: bool) -> list[str] | Failure:
|
||||
"""The preflight's lines, given the setting TIMEOUT_SETTING holds and whether to make the item's worktree; a Failure where the setting is no number of seconds above 0, or git finds no checkout or no default branch."""
|
||||
def run(setting: str | None, make: bool, item_id: int | None = None) -> list[str] | Failure:
|
||||
"""The preflight's lines, given the setting TIMEOUT_SETTING holds, whether to make the item's worktree, and the ID --item names; a Failure where the setting is no number of seconds above 0, or git finds no checkout or no default branch."""
|
||||
timeout = seconds(setting)
|
||||
if isinstance(timeout, Failure):
|
||||
return timeout
|
||||
root = top()
|
||||
return root if isinstance(root, Failure) else preflight(pathlib.Path(root), timeout, make)
|
||||
return root if isinstance(root, Failure) else preflight(pathlib.Path(root), timeout, make, item_id)
|
||||
|
||||
|
||||
def seconds(setting: str | None) -> float | Failure:
|
||||
@@ -107,32 +146,58 @@ def seconds(setting: str | None) -> float | Failure:
|
||||
return Failure(f"{TIMEOUT_SETTING}={setting!r} is no number of seconds above 0")
|
||||
|
||||
|
||||
def preflight(root: pathlib.Path, timeout: float, make: bool) -> list[str] | Failure:
|
||||
def preflight(root: pathlib.Path, timeout: float, make: bool, item_id: int | None) -> list[str] | Failure:
|
||||
"""Gathers the facts step by step, each step taking what the ones before it found, and renders them; a Failure where the checkout has no default branch."""
|
||||
default = default_branch(stale_ok=True, timeout=timeout)
|
||||
if isinstance(default, Failure):
|
||||
return default
|
||||
ref, note = default
|
||||
held = default_plan(str(root), ref)
|
||||
plan = planned(held.todo, held.cut, ref)
|
||||
item = plan if isinstance(plan, NoItem) else item_facts(root, ref, plan, timeout, make)
|
||||
return render(Gathered(ref, note, held.cut, item))
|
||||
config = located(str(root), pathlib.Path.home())
|
||||
if isinstance(config, Failure):
|
||||
return config
|
||||
outside = None if config.tracked("plan") else config.plan_label
|
||||
forge_run = runner(str(root), timeout)
|
||||
held = project_plan(config, ref, str(root), forge_run=forge_run)
|
||||
plan = planned(held.plan, held.cut, ref, config.branch, outside, item_id)
|
||||
item = plan if isinstance(plan, NoItem) else item_facts(root, ref, plan, timeout, make, epic_branch_of(config))
|
||||
# A `checkout:` path lands in the worktree the chunk works in.
|
||||
made = located(str(item.worktree.path), pathlib.Path.home()) if isinstance(item, ItemFacts) and isinstance(item.worktree, Worktree) else config
|
||||
return render(Gathered(ref, note, held.cut, item, plan_name(ref, outside), (config if isinstance(made, Failure) else made).places, outside is not None, config.texts, merges_unread=held.merges_unread, left=left_worktrees(root, forge_run) if config.merge == "human" else ()))
|
||||
|
||||
|
||||
def item_facts(root: pathlib.Path, default: str, plan: Plan, timeout: float, make: bool) -> ItemFacts:
|
||||
worktree = item_worktree(root, plan.branch, default) if make else Failure(f"none made, since it ran without {WORKTREE}.")
|
||||
def epic_branch_of(config: ProjectConfig) -> str | None | Failure:
|
||||
"""The working branch of the plan's epic, as the config's `epic-branch` names it; None where the config sets none."""
|
||||
if config.epic_branch is None:
|
||||
return None
|
||||
if config.epic is None:
|
||||
return Failure("none made: the config sets `epic-branch`, but its `plan` names no Jira epic to name the branch by; chunk-preflight makes an epic's chunks only from a plan kept in Jira")
|
||||
return templates.epic_branch(config.epic_branch, config.epic.key)
|
||||
|
||||
|
||||
def item_facts(root: pathlib.Path, default: str, plan: NextChunk, timeout: float, make: bool, epic: str | None | Failure = None) -> ItemFacts:
|
||||
worktree = Failure(f"none made, since it ran without {WORKTREE}.") if not make else epic if isinstance(epic, Failure) else item_worktree(root, plan.branch, default, timeout, epic)
|
||||
path = worktree.path if isinstance(worktree, Worktree) else None
|
||||
return ItemFacts(plan, worktree, pull_listing(root, plan.branch, timeout), named_files(plan.text, path or root), tools_run(plan.first.id, path, timeout) if path else [])
|
||||
|
||||
|
||||
def item_worktree(root: pathlib.Path, branch: str, default: str) -> Worktree | Failure:
|
||||
"""The worktree on branch, made where none is; a Failure where git cannot make it, or its path holds something else."""
|
||||
def item_worktree(root: pathlib.Path, branch: str, default: str, timeout: float | None = None, epic: str | None = None) -> Worktree | Failure:
|
||||
"""The worktree on branch, made where none is; a Failure where git cannot make it, or its path holds something else.
|
||||
|
||||
epic names the working branch of the chunk's epic, where the project keeps one. The worktree then branches off that branch, which is first made on origin or brought level with default (`epic_branch.levelled`), and the checkout records that the chunk merges into it."""
|
||||
if epic is not None:
|
||||
level = epic_branch.levelled(epic, default, timeout=timeout)
|
||||
recorded = level if isinstance(level, Failure) else record_chunk_base(branch, epic)
|
||||
if isinstance(recorded, Failure):
|
||||
return Failure(f"none made: {recorded.reason}")
|
||||
made = item_worktree(root, branch, f"origin/{epic}")
|
||||
return made if isinstance(made, Failure) else Worktree(made.path, f"{made.how} {level} The chunk's pull request goes into {epic}.")
|
||||
listing = git("worktree", "list", "--porcelain")
|
||||
if isinstance(listing, Failure):
|
||||
return listing
|
||||
if (path := worktree_on(listing, branch)) is not None:
|
||||
return Worktree(path, f"continued, on the branch {branch}.")
|
||||
path = root.parent / f"{root.name}-{branch}"
|
||||
# A branch such as feature/7 would nest the worktree in a folder, so its slashes become dashes.
|
||||
path = root.parent / f"{root.name}-{branch.replace('/', '-')}"
|
||||
if path.exists():
|
||||
return Failure(f"none made, since {path} exists and holds no worktree on the branch {branch}")
|
||||
args, how = worktree_add(branch, path, default, commit_exists(f"refs/heads/{branch}"), commit_exists(f"refs/remotes/origin/{branch}"))
|
||||
@@ -140,6 +205,15 @@ def item_worktree(root: pathlib.Path, branch: str, default: str) -> Worktree | F
|
||||
return Failure(f"none made: {added.reason}") if isinstance(added, Failure) else Worktree(path, how)
|
||||
|
||||
|
||||
def left_worktrees(root: pathlib.Path, forge_run: Run) -> tuple[LeftWorktree, ...]:
|
||||
"""Each worktree but root that is on a branch whose pull request merged with the worktree's head commit as its head: under `merge = "human"` a person merges after the chunk's run has ended, so its worker never ran `chunk-pr clean`. Where the forge can't be asked, no worktree counts as left."""
|
||||
listing, url = git("worktree", "list", "--porcelain"), git("remote", "get-url", "origin")
|
||||
if isinstance(listing, Failure) or isinstance(url, Failure):
|
||||
return ()
|
||||
merged = [(path, branch, merged_pull(forge_of(url), branch, head, forge_run)) for path, branch, head in worktrees(listing) if path != root]
|
||||
return tuple(LeftWorktree(path, branch, pull) for path, branch, pull in merged if isinstance(pull, str))
|
||||
|
||||
|
||||
def pull_listing(root: pathlib.Path, branch: str, timeout: float) -> tuple[Forge, Ran | Failure] | None:
|
||||
url = git("remote", "get-url", "origin")
|
||||
if isinstance(url, Failure):
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
import contextlib
|
||||
import dataclasses
|
||||
import os
|
||||
import pathlib
|
||||
import shutil
|
||||
@@ -8,13 +10,21 @@ import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from project_config.templates import BRANCH
|
||||
from release_plan.next_chunk import CarriedOver, NoItem
|
||||
from project_config.settings import Epic, ProjectConfig
|
||||
from chunk_preflight.main import epic_branch_of, item_facts as facts_made, item_worktree, line_count, ran, seconds, TIMEOUT
|
||||
from failure import Failure
|
||||
from chunk_preflight.choices import forge_of, named_paths, planned, worktree_add
|
||||
from chunk_preflight.gathered import Gathered, ItemFacts, NamedPath, NoItem, Ran, Worktree
|
||||
from chunk_preflight.gathered import Gathered, ItemFacts, LeftWorktree, NamedPath, Ran, Worktree
|
||||
from git_cli import git_repo
|
||||
from test_env import isolated_env
|
||||
from release_plan.release_standing import LastCut
|
||||
from chunk_preflight.main import line_count, ran, seconds, TIMEOUT
|
||||
from release_plan.release_standing import LastCut, UNSEEN_RELEASES
|
||||
from release_plan.awaiting_merge import marked
|
||||
from release_plan import next_chunk
|
||||
from chunk_preflight.facts import open_pulls, render
|
||||
from plan_store.todo_md import plan_of
|
||||
from chunk_preflight.choices import worktree_add, worktree_on, worktrees
|
||||
from project_config.doubles import write_config
|
||||
|
||||
BIN = pathlib.Path(__file__).resolve().parents[1]
|
||||
README = "# Project\n\n## Goals\n\n**Void:** code health, since the plan's scores weigh goal 1 alone.\n\n1. **Achieve:** Work.\n\n## Audience\n\nMe.\n"
|
||||
@@ -49,6 +59,10 @@ Change `src/app.py`'s `run` and the files under `src`, not `gone.py`.
|
||||
SHIPPED = TODO.replace("| 3 | 0.2.0 | | | **Do the next thing.** | 2 | 2 | 3 | 5 | 3 | 1 by 9 | 56.2 |\n", "").replace("| 7 | 0.2.0 | 3 |", "| 7 | 0.2.0 | |").replace("### 3. Do the next thing.", "### 7. Do the thing after.")
|
||||
# The plan once release 0.2.0 has shipped all its items: only release 0.3.0's item 9 is left.
|
||||
LATER = TODO[:TODO.index("| 5 |")] + "| 9 | 0.3.0 | | | **Do a later thing.** | 1 | 1 | 1 | 1 | 1 | 1 by 9 | 90.0 |\n"
|
||||
# Item 9's row, the only one under release 0.3.0.
|
||||
NINTH = "| 9 | 0.3.0 | | | **Do a later thing.** | 1 | 1 | 1 | 1 | 1 | 1 by 9 | 90.0 |\n"
|
||||
# A plan whose release 0.2.0 holds item 3 alone, before release 0.3.0's item 9.
|
||||
SHIPPED_BUT_3 = TODO[:TODO.index("| 5 |")] + "| 3 | 0.2.0 | | | **Do the next thing.** | 2 | 2 | 3 | 5 | 3 | 1 by 9 | 56.2 |\n" + NINTH
|
||||
# An items table that holds no row.
|
||||
EMPTY = TODO[:TODO.index("| 5 |")]
|
||||
CHANGELOG = "# Changelog\n\n## Unreleased\n\n- One.\n - A nested line.\n- Two.\n\n## 0.1.0\n\n- Old.\n"
|
||||
@@ -83,6 +97,7 @@ class Repo:
|
||||
self.env = {**isolated_env(), "GIT_CONFIG_GLOBAL": os.devnull, "GIT_CONFIG_NOSYSTEM": "1", "HOME": str(self.temp / "home"), "PATH": str(self.fake), "LOOP_CLAUDE_TRANSCRIPTS": str(self.temp / "archive")}
|
||||
self.git(self.temp, "init", "--quiet", "--bare", "--initial-branch=main", str(self.origin))
|
||||
self.git(self.temp, "clone", "--quiet", str(self.origin), str(self.root))
|
||||
write_config(self.temp / "home", self.root)
|
||||
self.write(self.root, "README.md", README)
|
||||
self.write(self.root, "src/app.py", "def run():\n\treturn 1\n\n")
|
||||
self.commit(self.root, "start")
|
||||
@@ -124,6 +139,66 @@ class Repo:
|
||||
|
||||
|
||||
class ChunkPreflightTool(unittest.TestCase):
|
||||
def test_passes_over_an_item_whose_pull_request_awaits_a_persons_merge_and_names_a_worktree_a_merged_one_left(self):
|
||||
repo = Repo(self, origin="github.com/o/r.git")
|
||||
config = repo.temp / "home" / ".claude-projects" / "proj" / "config.toml"
|
||||
config.write_text(config.read_text() + 'merge = "human"\n')
|
||||
repo.git(repo.root, "worktree", "add", "--quiet", "-b", "item-3", str(repo.temp / "proj-item-3"), "main")
|
||||
repo.write(repo.temp / "proj-item-3", "todo.md", TODO.replace("| 3 | 0.2.0 | | | **Do the next thing.** | 2 | 2 | 3 | 5 | 3 | 1 by 9 | 56.2 |\n", ""))
|
||||
repo.commit(repo.temp / "proj-item-3", "Finish item 3 in the plan")
|
||||
ready = repo.git(repo.temp / "proj-item-3", "rev-parse", "HEAD").strip()
|
||||
repo.git(repo.root, "worktree", "add", "--quiet", "-b", "item-2", str(repo.temp / "proj-item-2"), "main")
|
||||
left = repo.git(repo.temp / "proj-item-2", "rev-parse", "HEAD").strip()
|
||||
(repo.fake / "gh").write_text(f"""#!{sys.executable}
|
||||
import sys
|
||||
args = sys.argv[1:]
|
||||
if args[:4] == ["pr", "list", "--limit", "100"]:
|
||||
print("12\\thttps://github.com/o/r/pull/12\\t{ready}\\tfalse\\tfalse")
|
||||
elif args[:6] == ["pr", "list", "--head", "item-2", "--state", "merged"]:
|
||||
print("11\\t{left}\\tfalse")
|
||||
""")
|
||||
done = repo.preflight()
|
||||
self.assertEqual(done.returncode, 0, done.stderr)
|
||||
self.assertIn(f"- The worktree {repo.temp}/proj-item-2, on the branch item-2, is left from pull request #11, which has merged: run `~/.claude/bin/chunk-pr clean` in it as this chunk's first step.\n", done.stdout)
|
||||
self.assertNotIn("proj-item-3, on the branch", done.stdout, "an open pull request leaves no worktree to clean")
|
||||
self.assertIn("No plan item: every item of release 0.2.0 in origin/main's todo.md waits. Under `merge = \"human\"`, these pull requests await a person's merge: #12 https://github.com/o/r/pull/12, which finishes item 3. The working loop stops here. Once a person has merged one, or turned one back into a draft, run loop-claude again.", done.stdout)
|
||||
(repo.fake / "gh").write_text("#!/bin/sh\necho 'not logged in' >&2\nexit 1\n")
|
||||
unread = repo.preflight()
|
||||
self.assertIn("- The pull requests that await a person's merge cannot be read, so no item is passed over for one: gh pr list: not logged in\n", unread.stdout)
|
||||
self.assertIn("Its first item that does not wait: item 3,", unread.stdout)
|
||||
|
||||
def test_reads_a_plan_outside_the_checkout_as_it_stands_and_names_where_the_config_puts_each_file(self):
|
||||
repo = Repo(self)
|
||||
folder = repo.temp / "home" / ".claude-projects" / "proj"
|
||||
config = folder / "config.toml"
|
||||
config.write_text(config.read_text().replace('"checkout:todo.md"', '"folder:todo.md"'))
|
||||
(folder / "todo.md").write_text(SHIPPED)
|
||||
done = repo.preflight("--worktree")
|
||||
self.assertEqual(done.returncode, 0, done.stderr)
|
||||
worktree = repo.temp / "proj-item-7"
|
||||
self.assertIn("item 7, L 1, E + I 2", done.stdout, "origin's todo.md still holds item 3, which the plan in the config's folder does not")
|
||||
self.assertIn(f"- The project's config puts its files and plan at: plan {folder}/todo.md; working-rules {worktree}/AGENTS.md; decisions {worktree}/docs/decisions.md; ", done.stdout)
|
||||
self.assertIn("`rank_todo.py --check` exited 0", done.stdout)
|
||||
self.assertIn(f"- {UNSEEN_RELEASES}\n", done.stdout)
|
||||
config.unlink()
|
||||
refused = repo.preflight("--worktree")
|
||||
self.assertEqual((refused.returncode, refused.stdout), (1, ""))
|
||||
self.assertIn(f"no config names the checkout {repo.root}", refused.stderr)
|
||||
|
||||
def test_names_the_branch_and_the_worktree_by_the_configs_template_and_states_the_language_and_templates(self):
|
||||
repo = Repo(self)
|
||||
repo.push_from_elsewhere("todo.md", SHIPPED)
|
||||
plain = repo.preflight()
|
||||
self.assertIn("- The project's config sets: language English; commit-title {summary}; pull-request-title {summary}; branch item-{id}.\n", plain.stdout)
|
||||
config = repo.temp / "home" / ".claude-projects" / "proj" / "config.toml"
|
||||
config.write_text(config.read_text() + 'language = "Swedish"\ncommit-title = "PAY-{id} - {summary}"\nbranch = "feature/PAY-{id}"\n')
|
||||
done = repo.preflight("--worktree")
|
||||
self.assertEqual(done.returncode, 0, done.stderr)
|
||||
worktree = repo.temp / "proj-feature-PAY-7"
|
||||
self.assertEqual(repo.git(worktree, "rev-parse", "--abbrev-ref", "HEAD").strip(), "feature/PAY-7")
|
||||
self.assertIn("- Open pull requests from feature/PAY-7: ", done.stdout)
|
||||
self.assertIn("- The project's config sets: language Swedish; commit-title PAY-{id} - {summary}; pull-request-title {summary}; branch feature/PAY-{id}.\n", done.stdout)
|
||||
|
||||
def test_reads_the_fetched_default_branchs_plan_and_makes_the_items_worktree_off_it_leaving_the_checkout_as_it_was(self):
|
||||
repo = Repo(self)
|
||||
repo.push_from_elsewhere("todo.md", SHIPPED)
|
||||
@@ -143,7 +218,7 @@ class ChunkPreflightTool(unittest.TestCase):
|
||||
"#12 https://forge/pulls/12",
|
||||
"`src/app.py`: 3 lines",
|
||||
"`src`: 1 file",
|
||||
"`rank_todo.py --check todo.md` exited 0",
|
||||
"`rank_todo.py --check` exited 0",
|
||||
"`larv-review needs-scoring-run 7` exited 0",
|
||||
"`reading-cost` exited 0",
|
||||
"`larv-review places` exited 0",
|
||||
@@ -258,8 +333,9 @@ class ChunkPreflightTool(unittest.TestCase):
|
||||
|
||||
def test_reads_origin_as_last_fetched_where_the_fetch_stalls_and_still_states_the_other_facts(self):
|
||||
repo = Repo(self)
|
||||
repo.stub_git(f'"fetch --quiet origin") exec {shutil.which("sleep")} 10;;')
|
||||
done = repo.preflight("--worktree", CHUNK_PREFLIGHT_TIMEOUT="1")
|
||||
repo.stub_git(f'"fetch --quiet origin") exec {shutil.which("sleep")} 30;;')
|
||||
# The timeout also stops `reading-cost`, so it is set well above the seconds `reading-cost` takes on a loaded runner.
|
||||
done = repo.preflight("--worktree", CHUNK_PREFLIGHT_TIMEOUT="5")
|
||||
self.assertEqual(done.returncode, 0, done.stderr)
|
||||
self.assertIn("as last fetched", done.stdout)
|
||||
self.assertIn("item 3, L 2, E + I 5", done.stdout)
|
||||
@@ -277,6 +353,29 @@ class ChunkPreflightTool(unittest.TestCase):
|
||||
self.assertFalse((repo.temp / "proj-item-3").exists())
|
||||
self.assertNotIn("item-3", repo.git(repo.root, "branch", "--list"))
|
||||
|
||||
def test_item_names_the_item_the_chunk_starts_from_in_place_of_the_plans_next(self):
|
||||
repo = Repo(self)
|
||||
for args in (["--item", "7"], ["--worktree", "--item", "7"], ["--item", "7", "--worktree"]):
|
||||
with self.subTest(args):
|
||||
done = repo.preflight(*args)
|
||||
self.assertEqual((done.returncode, done.stderr), (0, ""))
|
||||
self.assertIn("0.2.0. The item this chunk starts from, named with --item: item 7, L 1, E + I 2.", done.stdout)
|
||||
self.assertNotIn("Its first item that does not wait", done.stdout)
|
||||
self.assertTrue((repo.temp / "proj-item-7").is_dir())
|
||||
self.assertFalse((repo.temp / "proj-item-3").exists())
|
||||
|
||||
def test_item_names_no_item_where_the_plan_no_longer_holds_it(self):
|
||||
done = Repo(self).preflight("--worktree", "--item", "4")
|
||||
self.assertEqual((done.returncode, done.stderr), (0, ""))
|
||||
self.assertIn("- No plan item: origin/main's todo.md holds no item 4, the one --item names; it may have shipped. No worktree was made.", done.stdout)
|
||||
|
||||
def test_exits_1_on_an_item_that_is_no_id(self):
|
||||
for args in (["--item"], ["--item", "x"], ["--item", "7", "8"]):
|
||||
with self.subTest(args):
|
||||
done = Repo(self).preflight(*args)
|
||||
self.assertEqual((done.returncode, done.stdout), (1, ""))
|
||||
self.assertIn(f"unknown arguments {' '.join(args)}; usage: chunk-preflight [--worktree] [--item <ID>]", done.stderr)
|
||||
|
||||
def test_exits_1_on_an_argument_other_than_worktree(self):
|
||||
done = Repo(self).preflight("--start")
|
||||
self.assertEqual(done.returncode, 1)
|
||||
@@ -322,16 +421,39 @@ class ChunkPreflightTool(unittest.TestCase):
|
||||
self.assertIn("git rev-parse --show-toplevel", done.stderr)
|
||||
|
||||
|
||||
def planned(todo, *rest):
|
||||
"""next_chunk.planned for the plan a todo.md's text holds, or for the Failure given."""
|
||||
return next_chunk.planned(plan_of(todo) if isinstance(todo, str) else todo, *rest)
|
||||
|
||||
|
||||
def item_facts(todo=TODO, **fields):
|
||||
"""The facts of todo's next item, its worktree made, with fields given replacing the rest."""
|
||||
return ItemFacts(**{"plan": planned(todo, CUT, "origin/main"), "worktree": Worktree(pathlib.Path("/c/proj-item-3"), "added on the new branch item-3, made off origin/main."), "pulls": None, "named": [], "tools": [], **fields})
|
||||
return ItemFacts(**{"plan": planned(todo, CUT, "origin/main", BRANCH), "worktree": Worktree(pathlib.Path("/c/proj-item-3"), "added on the new branch item-3, made off origin/main."), "pulls": None, "named": [], "tools": [], **fields})
|
||||
|
||||
|
||||
def gathered(item, release=CUT, note=None, plan_outside=False):
|
||||
return Gathered("origin/main", note, release, item, "origin/main's todo.md", {"plan": pathlib.Path("/c/proj-item-3/todo.md"), "changelog": pathlib.Path("/c/proj-item-3/CHANGELOG.md")}, plan_outside, {"language": "English"})
|
||||
|
||||
|
||||
def rendered(item, release=CUT, note=None):
|
||||
return "\n".join(render(Gathered("origin/main", note, release, item)))
|
||||
return "\n".join(render(gathered(item, release, note)))
|
||||
|
||||
|
||||
class Render(unittest.TestCase):
|
||||
def test_reads_each_worktree_on_a_branch_from_gits_listing(self):
|
||||
porcelain = "worktree /c/proj\nHEAD aaa\nbranch refs/heads/main\n\nworktree /c/my proj-item-2\nHEAD bbb\nbranch refs/heads/item-2\n\nworktree /c/detached\nHEAD ccc\ndetached\n"
|
||||
self.assertEqual(worktrees(porcelain), [(pathlib.Path("/c/proj"), "main", "aaa"), (pathlib.Path("/c/my proj-item-2"), "item-2", "bbb")])
|
||||
self.assertEqual((worktree_on(porcelain, "item-2"), worktree_on(porcelain, "item-3")), (pathlib.Path("/c/my proj-item-2"), None))
|
||||
|
||||
def test_states_what_a_persons_merge_leaves_only_where_there_is_something(self):
|
||||
self.assertNotIn("merge", rendered(item_facts()))
|
||||
found = gathered(NoItem("the plan holds none."))
|
||||
left = dataclasses.replace(found, left=(LeftWorktree(pathlib.Path("/c/proj-item-2"), "item-2", "11"),), merges_unread=Failure("`gh pr list` exited 1: no"))
|
||||
passed = "\n".join(render(gathered(item_facts(marked(plan_of(TODO), {7: "#12 https://github.com/o/r/pull/12", 8: "#13 https://github.com/o/r/pull/13"})))))
|
||||
self.assertIn("\n- Items passed over, each finished on a branch whose ready pull request awaits a person's merge: item 7, by pull request #12 https://github.com/o/r/pull/12; item 8, by pull request #13 https://github.com/o/r/pull/13. No chunk takes one.\n", passed)
|
||||
self.assertIn("- No other item of release 0.2.0 may join item 3's chunk.", passed)
|
||||
self.assertEqual(render(left)[1:3], ["- The worktree /c/proj-item-2, on the branch item-2, is left from pull request #11, which has merged: run `~/.claude/bin/chunk-pr clean` in it as this chunk's first step.", "- The pull requests that await a person's merge cannot be read, so no item is passed over for one: `gh pr list` exited 1: no"])
|
||||
|
||||
def test_states_the_earliest_releases_first_item_its_levels_and_detail_and_each_item_that_may_join_its_chunk(self):
|
||||
said = rendered(item_facts())
|
||||
self.assertIn("origin/main's todo.md: 0.2.0", said)
|
||||
@@ -340,6 +462,47 @@ class Render(unittest.TestCase):
|
||||
self.assertIn("item 7, L 1, E + I 2, S 1: **Do the thing after.**", said)
|
||||
self.assertNotIn("item 8,", said)
|
||||
|
||||
def test_says_the_item_was_named_with_item(self):
|
||||
said = rendered(item_facts(plan=planned(TODO, CUT, "origin/main", BRANCH, None, 7)))
|
||||
self.assertIn("origin/main's todo.md: 0.2.0. The item this chunk starts from, named with --item: item 7, L 1, E + I 2.", said)
|
||||
|
||||
def test_states_each_fact_once_with_the_paths_between_the_worktree_and_the_open_pull_requests(self):
|
||||
lines = render(gathered(item_facts()))
|
||||
self.assertEqual([line.partition(":")[0] for line in lines[:6]], ["- Last version cut", "- The earliest release in origin/main's todo.md", "- Worktree", "- The project's config puts its files and plan at", "- The project's config sets", "- Open pull requests from item-3"])
|
||||
self.assertEqual([line for line in lines[6:] if line.startswith("- Open pull requests")], [])
|
||||
|
||||
def test_says_that_a_plan_outside_the_checkout_hides_a_release_whose_items_are_all_done(self):
|
||||
for item in (item_facts(), NoItem("the plan holds no item.")):
|
||||
with self.subTest(item=type(item).__name__):
|
||||
lines = render(gathered(item, plan_outside=True))
|
||||
self.assertEqual(lines[1], f"- {UNSEEN_RELEASES}")
|
||||
self.assertIn("no release review is called due and no release is called ready to cut: both are the human's to call", lines[1])
|
||||
self.assertNotIn(f"- {UNSEEN_RELEASES}", render(gathered(item)))
|
||||
|
||||
def test_quotes_the_detail_of_each_item_that_may_join_the_chunk(self):
|
||||
said = rendered(item_facts(TODO + "\n### 7. Do the thing after.\n\nTouch `src/other.py`.\n\nRun the e2e leg.\n\n### 8. Do the answered thing.\n\nNot quoted.\n"))
|
||||
self.assertIn("Item 7's detail:\n\n> Touch `src/other.py`.\n> \n> Run the e2e leg.", said)
|
||||
self.assertNotIn("Not quoted", said)
|
||||
|
||||
def test_lists_a_joining_item_nobody_scored_as_unscored(self):
|
||||
plan = item_facts().plan
|
||||
unscored = [dataclasses.replace(item, scores={}) if item.id == 7 else item for item in plan.items]
|
||||
said = rendered(item_facts(plan=dataclasses.replace(plan, items=unscored)))
|
||||
self.assertIn(" - item 7, L unscored, E + I unscored, S unscored: ", said)
|
||||
|
||||
def test_states_that_a_joining_item_has_no_detail(self):
|
||||
said = rendered(item_facts())
|
||||
self.assertIn("Item 7 has no detail.", said)
|
||||
self.assertNotIn("Item 7's detail", said)
|
||||
|
||||
def test_quotes_the_details_of_the_first_ten_joining_items_and_names_the_rest(self):
|
||||
rows = "".join(f"| {id_} | 0.2.0 | | | **Do thing {id_}.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 10.0 |\n" for id_ in range(20, 32))
|
||||
details = "".join(f"\n### {id_}. Do thing {id_}.\n\nDetail {id_}.\n" for id_ in range(7, 8)) + "".join(f"\n### {id_}. Do thing {id_}.\n\nDetail {id_}.\n" for id_ in range(20, 32))
|
||||
said = rendered(item_facts(TODO.replace("\n## Details", rows + "\n## Details") + details))
|
||||
self.assertIn("> Detail 28.", said)
|
||||
self.assertNotIn("Detail 29.", said)
|
||||
self.assertIn("The details of items 29, 30 and 31 are not quoted: only the first 10 are. Run `~/.claude/bin/todo-item show <ID>` for each.", said)
|
||||
|
||||
def test_states_the_items_worktree_or_why_none_was_made(self):
|
||||
self.assertIn("/c/proj-item-3", rendered(item_facts()))
|
||||
self.assertIn("none made: path taken", rendered(item_facts(worktree=Failure("none made: path taken"))))
|
||||
@@ -417,14 +580,83 @@ class Render(unittest.TestCase):
|
||||
self.assertIn("ls-files broke", rendered(item_facts(named=Failure("ls-files broke"))))
|
||||
|
||||
def test_states_what_each_tool_printed_and_its_exit_code(self):
|
||||
said = rendered(item_facts(tools=[("rank_todo.py --check todo.md", Ran(0, "ranked\n", "")), ("reading-cost", Ran(1, "", "")), ("larv-review needs-scoring-run 3", Ran(1, "out\n", "err\n")), ("larv-review places", Failure("could not finish: timed out"))]))
|
||||
self.assertIn("`rank_todo.py --check todo.md` exited 0", said)
|
||||
said = rendered(item_facts(tools=[("rank_todo.py --check", Ran(0, "ranked\n", "")), ("reading-cost", Ran(1, "", "")), ("larv-review needs-scoring-run 3", Ran(1, "out\n", "err\n")), ("larv-review places", Failure("could not finish: timed out"))]))
|
||||
self.assertIn("`rank_todo.py --check` exited 0", said)
|
||||
self.assertIn("> ranked", said)
|
||||
self.assertIn("`reading-cost` exited 1, printing nothing", said)
|
||||
self.assertIn("`reading-cost` exited 1, printing no output", said)
|
||||
self.assertIn("> out\n> err", said)
|
||||
self.assertIn("`larv-review places` could not finish: timed out", said)
|
||||
|
||||
|
||||
class EpicBranchWorktree(unittest.TestCase):
|
||||
"""A chunk's worktree in a project whose config names an epic's working branch, here ABC-1."""
|
||||
|
||||
def setUp(self):
|
||||
self.repo = Repo(self)
|
||||
self.enterContext(contextlib.chdir(self.repo.root))
|
||||
# item_worktree runs git in this process's environment, so the identity its merge commit needs is the checkout's own.
|
||||
for name, value in (("user.name", "t"), ("user.email", "t@example.com")):
|
||||
self.repo.git(self.repo.root, "config", name, value)
|
||||
|
||||
def test_the_first_chunk_makes_the_epic_branch_on_origin_and_branches_off_it_recording_where_it_merges(self):
|
||||
made = item_worktree(self.repo.root, "ABC-7", "origin/main", 30, "ABC-1")
|
||||
self.assertEqual(made, Worktree(self.repo.temp / "proj-ABC-7", "added on the new branch ABC-7, made off origin/ABC-1. Made origin/ABC-1 off origin/main. The chunk's pull request goes into ABC-1."))
|
||||
self.assertEqual(self.repo.git(self.repo.origin, "rev-parse", "ABC-1"), self.repo.git(self.repo.root, "rev-parse", "origin/main"))
|
||||
self.assertEqual(git_repo.default_ref(str(made.path)), "origin/ABC-1")
|
||||
|
||||
def test_a_later_chunk_branches_off_what_the_epic_branch_holds(self):
|
||||
item_worktree(self.repo.root, "ABC-7", "origin/main", 30, "ABC-1")
|
||||
first = self.repo.temp / "proj-ABC-7"
|
||||
self.repo.write(first, "src/first.py", "FIRST = 1\n")
|
||||
self.repo.commit(first, "first")
|
||||
self.repo.git(first, "push", "--quiet", "origin", "ABC-7:ABC-1")
|
||||
made = item_worktree(self.repo.root, "ABC-8", "origin/main", 30, "ABC-1")
|
||||
self.assertIn("origin/ABC-1 already holds origin/main.", made.how)
|
||||
self.assertTrue((made.path / "src/first.py").exists())
|
||||
|
||||
def test_a_default_branch_that_conflicts_with_the_epic_branch_makes_no_worktree_and_leaves_it_to_a_person(self):
|
||||
item_worktree(self.repo.root, "ABC-7", "origin/main", 30, "ABC-1")
|
||||
first = self.repo.temp / "proj-ABC-7"
|
||||
self.repo.write(first, "src/app.py", "def run():\n\treturn 2\n\n")
|
||||
self.repo.commit(first, "first")
|
||||
self.repo.git(first, "push", "--quiet", "origin", "ABC-7:ABC-1")
|
||||
self.repo.push_from_elsewhere("src/app.py", "def run():\n\treturn 3\n\n")
|
||||
made = item_worktree(self.repo.root, "ABC-8", "origin/main", 30, "ABC-1")
|
||||
self.assertIsInstance(made, Failure)
|
||||
self.assertTrue(made.reason.startswith("none made: origin/main doesn't merge into origin/ABC-1 cleanly, so a person merges it"), made.reason)
|
||||
self.assertFalse((self.repo.temp / "proj-ABC-8").exists())
|
||||
|
||||
def test_a_worktree_path_that_holds_something_else_makes_no_worktree_off_the_epic_branch(self):
|
||||
taken = self.repo.temp / "proj-ABC-7"
|
||||
taken.mkdir()
|
||||
self.assertEqual(item_worktree(self.repo.root, "ABC-7", "origin/main", 30, "ABC-1"), Failure(f"none made, since {taken} exists and holds no worktree on the branch ABC-7"))
|
||||
|
||||
def test_names_the_epic_branch_by_the_plans_epic_and_none_where_the_config_sets_no_template(self):
|
||||
config = ProjectConfig("proj", pathlib.Path("/config"), pathlib.Path("/checkout"), {}, epic=Epic("https://acme.atlassian.net", "ABC-1"), epic_branch="epic/{epic}")
|
||||
self.assertEqual(epic_branch_of(config), "epic/ABC-1")
|
||||
self.assertIsNone(epic_branch_of(dataclasses.replace(config, epic_branch=None)))
|
||||
self.assertEqual(epic_branch_of(dataclasses.replace(config, epic=None)), Failure("none made: the config sets `epic-branch`, but its `plan` names no Jira epic to name the branch by; chunk-preflight makes an epic's chunks only from a plan kept in Jira"))
|
||||
|
||||
def test_the_facts_of_an_item_put_its_worktree_on_the_epic_branch_they_are_given(self):
|
||||
facts = facts_made(self.repo.root, "origin/main", planned(TODO, CUT, "origin/main", BRANCH), 30, True, "ABC-1")
|
||||
self.assertEqual(facts.worktree.path, self.repo.temp / "proj-item-3")
|
||||
self.assertTrue(facts.worktree.how.endswith("The chunk's pull request goes into ABC-1."), facts.worktree.how)
|
||||
self.assertEqual(self.repo.git(self.repo.root, "config", "--get", "branch.item-3.chunk-base"), "ABC-1\n")
|
||||
|
||||
def test_the_facts_of_an_item_make_no_worktree_where_the_epic_branch_cannot_be_named(self):
|
||||
unnamed = Failure("none made: the plan names no epic")
|
||||
self.assertEqual(facts_made(self.repo.root, "origin/main", planned(TODO, CUT, "origin/main", BRANCH), 30, True, unnamed).worktree, unnamed)
|
||||
self.assertFalse((self.repo.temp / "proj-item-3").exists())
|
||||
|
||||
def test_the_tool_makes_no_worktree_where_the_config_sets_an_epic_branch_and_keeps_its_plan_in_a_file(self):
|
||||
config = self.repo.temp / "home" / ".claude-projects" / "proj" / "config.toml"
|
||||
config.write_text(config.read_text() + 'epic-branch = "{epic}"\n')
|
||||
done = self.repo.preflight("--worktree")
|
||||
self.assertEqual(done.returncode, 0, done.stderr)
|
||||
self.assertIn("none made: the config sets `epic-branch`, but its `plan` names no Jira epic to name the branch by", done.stdout)
|
||||
self.assertFalse((self.repo.temp / "proj-item-3").exists())
|
||||
|
||||
|
||||
class OpenPulls(unittest.TestCase):
|
||||
def test_lists_gh_rows_as_they_come_and_only_teas_rows_from_the_branch(self):
|
||||
self.assertEqual(open_pulls("12\thttps://github.com/o/r/pull/12\n14\thttps://github.com/o/r/pull/14\n", "gh", "item-3"), ["#12 https://github.com/o/r/pull/12", "#14 https://github.com/o/r/pull/14"])
|
||||
@@ -433,38 +665,48 @@ class OpenPulls(unittest.TestCase):
|
||||
|
||||
class Plans(unittest.TestCase):
|
||||
def test_picks_the_earliest_releases_first_item_that_does_not_wait_or_says_why_there_is_none(self):
|
||||
self.assertEqual(planned(TODO, CUT, "origin/main").first.id, 3)
|
||||
waits = planned(TODO.replace("| 3 | 0.2.0 | | |", "| 3 | 0.2.0 | | question |"), CUT, "origin/main")
|
||||
self.assertEqual(planned(TODO, CUT, "origin/main", BRANCH).first.id, 3)
|
||||
waits = planned(TODO.replace("| 3 | 0.2.0 | | |", "| 3 | 0.2.0 | | question |"), CUT, "origin/main", BRANCH)
|
||||
self.assertIn("waits", waits.why)
|
||||
self.assertIn("0.2.0", waits.why)
|
||||
self.assertIn("Permission denied", planned(Failure("Permission denied"), CUT, "origin/main").why)
|
||||
self.assertIn("L 'x'", planned(TODO.replace("| 2 | 2 | 3 | 5 |", "| x | 2 | 3 | 5 |"), CUT, "origin/main").why)
|
||||
self.assertIn("details cannot be read", planned(TODO + "```\n", CUT, "origin/main").text)
|
||||
self.assertIn("Permission denied", planned(Failure("Permission denied"), CUT, "origin/main", BRANCH).why)
|
||||
self.assertEqual(planned(Failure("Permission denied"), CUT, "origin/main", BRANCH).why, "origin/main's todo.md cannot be read: Permission denied.")
|
||||
self.assertEqual(planned(Failure("Permission denied"), CUT, "origin/main", BRANCH, pathlib.Path("/projects/acme/todo.md")).why, "/projects/acme/todo.md cannot be read: Permission denied.")
|
||||
self.assertIn("L 'x'", planned(TODO.replace("| 2 | 2 | 3 | 5 |", "| x | 2 | 3 | 5 |"), CUT, "origin/main", BRANCH).why)
|
||||
self.assertIn("## Details holds a fenced code block", planned(TODO + "```\n", CUT, "origin/main", BRANCH).why)
|
||||
|
||||
def test_takes_the_item_item_names_even_one_that_waits_or_says_it_left_the_plan(self):
|
||||
# Item 7 waits for item 3, which another chunk runs.
|
||||
named = planned(TODO, CUT, "origin/main", BRANCH, None, 7)
|
||||
self.assertEqual((named.first.id, named.first.tagline, named.named), (7, "**Do the thing after.**", True))
|
||||
self.assertTrue(named.text.startswith("**Do the thing after.**"), named.text)
|
||||
self.assertFalse(planned(TODO, CUT, "origin/main", BRANCH).named)
|
||||
self.assertEqual(planned(TODO, CUT, "origin/main", BRANCH, None, 4), NoItem("origin/main's todo.md holds no item 4, the one --item names; it may have shipped."))
|
||||
|
||||
def test_tells_a_plan_with_no_items_table_from_one_whose_table_holds_no_item(self):
|
||||
without = planned("", CUT, "origin/main").why
|
||||
without = planned("", CUT, "origin/main", BRANCH).why
|
||||
self.assertIn("origin/main", without)
|
||||
self.assertIn("no items table", without)
|
||||
self.assertNotIn("cannot be read", without)
|
||||
empty = planned(EMPTY, LastCut(None, "", 4, []), "origin/main").why
|
||||
empty = planned(EMPTY, LastCut(None, "", 4, []), "origin/main", BRANCH).why
|
||||
self.assertIn("holds no item", empty)
|
||||
self.assertNotIn("no items table", empty)
|
||||
|
||||
def test_names_a_release_cut_under_a_dated_heading_as_the_last_cut_on_a_branch_with_no_tag(self):
|
||||
said = planned(EMPTY, LastCut(None, "## 0.0.1 - 2026-10-03\n", 0, []), "origin/main").why
|
||||
said = planned(EMPTY, LastCut(None, "## 0.0.1 - 2026-10-03\n", 0, []), "origin/main", BRANCH).why
|
||||
self.assertIn("the next release after the last cut, 0.0.1 (dated in CHANGELOG.md)", said)
|
||||
|
||||
def test_says_the_tags_cannot_be_read_with_gits_reason_and_names_no_cut(self):
|
||||
said = planned(EMPTY, LastCut(Failure("git exited 128: not a git repository"), "", 4, []), "origin/main").why
|
||||
said = planned(EMPTY, LastCut(Failure("git exited 128: not a git repository"), "", 4, []), "origin/main", BRANCH).why
|
||||
self.assertIn("origin/main's tags cannot be read: git exited 128: not a git repository.", said)
|
||||
self.assertIn("Find the next release yourself.", said)
|
||||
self.assertNotIn("no release is cut yet", said)
|
||||
|
||||
def test_names_the_start_as_the_last_cut_where_nothing_is_cut(self):
|
||||
said = planned(EMPTY, LastCut(None, "", 4, [TODO]), "origin/main").why
|
||||
said = planned(EMPTY, LastCut(None, "", 4, [TODO]), "origin/main", BRANCH).why
|
||||
self.assertIn("release 0.2.0, the next after the start, since no release is cut yet,", said)
|
||||
self.assertIn("has landed yet.", said)
|
||||
self.assertIn("since the cut.", planned(EMPTY, LastCut(None, "## 0.1.0 - 2026-10-03\n", 4, [TODO]), "origin/main").why)
|
||||
self.assertIn("since the cut.", planned(EMPTY, LastCut(None, "## 0.1.0 - 2026-10-03\n", 4, [TODO]), "origin/main", BRANCH).why)
|
||||
|
||||
def test_finds_the_release_after_the_last_cut_finished_or_to_be_planned_where_the_plan_holds_no_item_for_it(self):
|
||||
named = "release 0.2.0, the next after the last cut, v0.1.0"
|
||||
@@ -480,47 +722,52 @@ class Plans(unittest.TestCase):
|
||||
)
|
||||
for todo, commits, todos, reviewed, fact, release in cases:
|
||||
with self.subTest(todo=todo, commits=commits, todos=todos, reviewed=reviewed):
|
||||
why = planned(todo, LastCut("v0.1.0", "", commits, todos, reviewed), "origin/main").why
|
||||
why = planned(todo, LastCut("v0.1.0", "", commits, todos, reviewed), "origin/main", BRANCH).why
|
||||
self.assertIn(fact, why)
|
||||
self.assertIn(release, why)
|
||||
|
||||
def test_says_what_todo_md_named_since_the_last_cut_cannot_be_read(self):
|
||||
self.assertIn("cannot be read", planned(LATER, LastCut("v0.1.0", "", 4, Failure("log unreadable")), "origin/main").why)
|
||||
self.assertIn("cannot be read", planned(LATER, LastCut("v0.1.0", "", 4, Failure("log unreadable")), "origin/main", BRANCH).why)
|
||||
|
||||
def test_takes_the_earliest_release_where_no_earlier_one_was_named_since_the_last_cut(self):
|
||||
self.assertEqual(planned(LATER, LastCut("v0.1.0", "", 4, [LATER]), "origin/main").first.id, 9)
|
||||
self.assertEqual(planned(LATER, LastCut("v0.1.0", "", 4, [LATER]), "origin/main", BRANCH).first.id, 9)
|
||||
|
||||
def test_counts_the_items_of_a_release_already_cut_as_the_next_releases_and_says_to_move_them(self):
|
||||
plan = planned(TODO, LastCut("v0.2.0", "", 4, []), "origin/main", BRANCH)
|
||||
self.assertEqual((plan.first.id, plan.first.release), (3, (0, 3, 0)))
|
||||
self.assertEqual({item.release for item in plan.items}, {(0, 3, 0)})
|
||||
self.assertEqual(plan.carried, CarriedOver((0, 3, 0), (5, 3, 7, 8)))
|
||||
said = rendered(dataclasses.replace(item_facts(), plan=plan), LastCut("v0.2.0", "", 4, []))
|
||||
self.assertIn("- Items 5, 3, 7 and 8 are filed under a release already cut, so they count as release 0.3.0's, the next.", said)
|
||||
self.assertIn("`~/.claude/bin/todo-item move`", said)
|
||||
self.assertIn("- The next release, after the last cut, that origin/main's todo.md names: 0.3.0. Its first item that does not wait: item 3,", said)
|
||||
self.assertNotIn("already cut", rendered(item_facts()))
|
||||
|
||||
def test_says_to_move_one_or_two_items_of_a_release_already_cut_in_the_singular_or_the_plural(self):
|
||||
cut = LastCut("v0.2.0", "", 4, [])
|
||||
for todo, ids, said in ((SHIPPED_BUT_3, (3,), "- Item 3 is filed under a release already cut, so it counts as release 0.3.0's, the next. Move it there"), (SHIPPED_BUT_3 + NINTH.replace("| 9 | 0.3.0 |", "| 4 | 0.1.0 |"), (3, 4), "- Items 3 and 4 are filed under a release already cut, so they count as release 0.3.0's, the next. Move them there")):
|
||||
with self.subTest(ids=ids):
|
||||
plan = planned(todo, cut, "origin/main", BRANCH)
|
||||
self.assertEqual(plan.carried, CarriedOver((0, 3, 0), ids))
|
||||
self.assertIn(said, rendered(dataclasses.replace(item_facts(), plan=plan), cut))
|
||||
|
||||
def test_says_the_plan_files_items_under_a_release_already_cut(self):
|
||||
why = planned(TODO, LastCut("v0.2.0", "", 4, []), "origin/main").why
|
||||
why = planned(TODO.replace(NINTH, ""), LastCut("v0.2.0", "", 4, []), "origin/main", BRANCH).why
|
||||
self.assertIn("release 0.2.0", why)
|
||||
self.assertIn("v0.2.0", why)
|
||||
self.assertIn("not after", why)
|
||||
|
||||
def test_takes_an_item_without_a_detail_as_its_tagline_alone(self):
|
||||
self.assertEqual(planned(TODO[:TODO.index("## Details")], CUT, "origin/main").text, "**Do the next thing.**")
|
||||
self.assertEqual(planned(TODO[:TODO.index("## Details")], CUT, "origin/main", BRANCH).text, "**Do the next thing.**")
|
||||
|
||||
|
||||
class Gathering(unittest.TestCase):
|
||||
def test_names_each_tracked_file_or_folder_a_backticked_span_names_once_with_its_files(self):
|
||||
cases = (
|
||||
("`src/` and `src`", ["src/app.py", "srcfoo/x.py"], [("src", 1)]),
|
||||
("`src/`", ["src/app.py", "src/b.py"], [("src", 2)]),
|
||||
("`src/app.py`, `gone.py` and `run`", ["src/app.py"], [("src/app.py", 1)]),
|
||||
)
|
||||
for text, tracked, named in cases:
|
||||
with self.subTest(text=text):
|
||||
self.assertEqual(named_paths(text, tracked), named)
|
||||
|
||||
def test_adds_the_worktree_on_the_local_branch_else_on_a_new_one_tracking_origins_else_on_a_new_one_off_the_default_branch(self):
|
||||
path = pathlib.Path("/c/proj-item-3")
|
||||
self.assertEqual(worktree_add("item-3", path, "origin/main", True, True)[0], ["worktree", "add", "--quiet", "/c/proj-item-3", "item-3"])
|
||||
self.assertEqual(worktree_add("item-3", path, "origin/main", False, True)[0], ["worktree", "add", "--quiet", "--track", "-b", "item-3", "/c/proj-item-3", "origin/item-3"])
|
||||
self.assertEqual(worktree_add("item-3", path, "origin/main", False, False)[0], ["worktree", "add", "--quiet", "--no-track", "-b", "item-3", "/c/proj-item-3", "origin/main"])
|
||||
|
||||
def test_lists_pull_requests_with_gh_on_a_github_origin_and_with_tea_elsewhere(self):
|
||||
self.assertEqual(forge_of("git@github.com:o/r.git"), "gh")
|
||||
self.assertEqual(forge_of("https://gitea.larvit.se/o/r.git"), "tea")
|
||||
|
||||
def test_reads_the_timeout_setting_as_seconds_above_0_and_else_takes_the_default(self):
|
||||
self.assertEqual(seconds(None), TIMEOUT)
|
||||
self.assertEqual(seconds("2.5"), 2.5)
|
||||
@@ -552,5 +799,33 @@ class Running(unittest.TestCase):
|
||||
self.assertIsNone(line_count(folder))
|
||||
|
||||
|
||||
class BesideTest(unittest.TestCase):
|
||||
"""The fact that names the items that may start chunks beside the next one."""
|
||||
# Items 3 and 4 touch other parts of one file, and item 6 touches what item 3 does.
|
||||
ROWS = "| 4 | 0.2.0 | | | **Do four.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 10.0 |\n| 6 | 0.2.0 | | | **Do six.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 10.0 |\n"
|
||||
DETAILS = "\nTouches:\n\n- `src/app.py`: `run`\n\n### 4. Do four.\n\nTouches:\n\n- `src/app.py`: `stop`\n\n### 6. Do six.\n\nTouches:\n\n- `src/app.py`: `run`\n"
|
||||
|
||||
def said(self, todo):
|
||||
return [line for line in rendered(item_facts(todo)).splitlines() if "beside" in line]
|
||||
|
||||
def test_names_the_items_that_may_start_chunks_beside_it_and_why_the_others_may_not(self):
|
||||
todo = TODO.replace("| 9 | 0.3.0", self.ROWS + "| 9 | 0.3.0") + self.DETAILS
|
||||
self.assertEqual(self.said(todo), ["- The items of release 0.2.0 that may start chunks beside item 3's: 4. None is predicted to touch a part that item 3 touches, or that an item earlier in this list touches. An item this chunk takes doesn't start a chunk of its own. Not beside it: item 6, which overlaps item 3 at `src/app.py` `run`."])
|
||||
|
||||
def test_names_each_item_that_may_and_stops_there_when_none_is_refused(self):
|
||||
todo = TODO.replace("| 9 | 0.3.0", self.ROWS + "| 9 | 0.3.0") + self.DETAILS.removesuffix("`run`\n") + "`other`\n"
|
||||
self.assertEqual(self.said(todo), ["- The items of release 0.2.0 that may start chunks beside item 3's: 4, 6. None is predicted to touch a part that item 3 touches, or that an item earlier in this list touches. An item this chunk takes doesn't start a chunk of its own."])
|
||||
|
||||
def test_says_when_none_may(self):
|
||||
todo = TODO.replace("| 9 | 0.3.0", self.ROWS + "| 9 | 0.3.0") + self.DETAILS.replace("`stop`", "`run`")
|
||||
self.assertEqual(self.said(todo), ["- No item of release 0.2.0 may start a chunk beside item 3's. Not beside it: item 4, which overlaps item 3 at `src/app.py` `run`; item 6, which overlaps item 3 at `src/app.py` `run`."])
|
||||
alone = TODO.replace("| 9 | 0.3.0", self.ROWS + "| 9 | 0.3.0") + "\n### 4. Do four.\n\nTouches:\n\n- `src/app.py`\n"
|
||||
self.assertEqual(self.said(alone), ["- No item of release 0.2.0 may start a chunk beside item 3's: item 3's detail has no `Touches:` list."])
|
||||
|
||||
def test_says_nothing_in_a_plan_without_predictions(self):
|
||||
self.assertEqual(self.said(TODO), [])
|
||||
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
|
||||
+165
-47
@@ -1,14 +1,161 @@
|
||||
"""Entries of Claude Code's transcripts and of its stream-json and json output."""
|
||||
import dataclasses
|
||||
import json
|
||||
import typing
|
||||
|
||||
|
||||
def parse_entry(raw: str | bytes) -> dict | None:
|
||||
def json_object(raw: str | bytes) -> dict | None:
|
||||
"""A line of JSON, such as a transcript line, a stream-json line or claude's json reply, where it is an object; None otherwise."""
|
||||
try:
|
||||
entry = json.loads(raw)
|
||||
found = json.loads(raw)
|
||||
except ValueError:
|
||||
return None
|
||||
return entry if isinstance(entry, dict) else None
|
||||
return found if isinstance(found, dict) else None
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True, kw_only=True)
|
||||
class Entry:
|
||||
"""A transcript entry, with the fields every entry may carry, each "" where it has none. Kinds no consumer tells apart, such as a compaction's boundary, parse as Entry itself. Each subclass names a kind consumers tell apart."""
|
||||
uuid: str = ""
|
||||
parent_uuid: str = ""
|
||||
timestamp: str = ""
|
||||
cwd: str = ""
|
||||
git_branch: str = ""
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True, kw_only=True)
|
||||
class UserText(Entry):
|
||||
"""The text of a "user" entry, its text blocks joined, or of a prompt the human queued while claude worked. HumanTurn, LoopPrompt and InjectedText say who wrote it."""
|
||||
text: str
|
||||
|
||||
|
||||
class HumanTurn(UserText):
|
||||
"""What the human wrote, at the prompt or while claude worked."""
|
||||
|
||||
|
||||
class LoopPrompt(UserText):
|
||||
"""What loop-claude told the worker in a -p prompt."""
|
||||
|
||||
|
||||
class InjectedText(UserText):
|
||||
"""Text Claude Code wrote into the prompt, such as a slash command, a task notification or a compaction's summary."""
|
||||
|
||||
|
||||
class Text(typing.NamedTuple):
|
||||
text: str
|
||||
|
||||
|
||||
class ToolCall(typing.NamedTuple):
|
||||
id: str
|
||||
name: str
|
||||
input: dict
|
||||
|
||||
|
||||
class ToolResult(typing.NamedTuple):
|
||||
tool_use_id: str
|
||||
text: str
|
||||
failed: bool
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True, kw_only=True)
|
||||
class AssistantTurn(Entry):
|
||||
"""An assistant entry's text and tool-call blocks, with its message's id, model and usage. Claude Code writes one entry per block of a message, so one message's usage repeats across several entries."""
|
||||
parts: tuple[Text | ToolCall, ...] = ()
|
||||
message_id: str = ""
|
||||
model: str = ""
|
||||
usage: dict = dataclasses.field(default_factory=dict)
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True, kw_only=True)
|
||||
class ToolResults(Entry):
|
||||
"""The tool results Claude Code returns in a "user" entry, or logs again with the API request that sent them."""
|
||||
results: tuple[ToolResult, ...]
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True, kw_only=True)
|
||||
class CostState(Entry):
|
||||
"""The cost in dollars Claude Code records for each model the session has called so far, the subagents' and the compactions' calls too."""
|
||||
costs: dict[str, float]
|
||||
|
||||
|
||||
def parse_entry(raw: str | bytes) -> Entry | None:
|
||||
"""A transcript line as its kind; None where it is not a JSON object."""
|
||||
found = json_object(raw)
|
||||
return None if found is None else entry_from(found)
|
||||
|
||||
|
||||
def entry_from(found: dict) -> Entry:
|
||||
"""A transcript entry, or a stream-json event, as its kind."""
|
||||
carried = Carried(uuid=field(found, "uuid"), parent_uuid=field(found, "parentUuid"), timestamp=field(found, "timestamp"), cwd=field(found, "cwd"), git_branch=field(found, "gitBranch"))
|
||||
match found.get("type"):
|
||||
case "assistant":
|
||||
return assistant_turn(found, carried)
|
||||
case "user":
|
||||
return user_entry(found, carried)
|
||||
case "cost-state":
|
||||
return cost_state(found, carried)
|
||||
# Claude Code logs each API request's last message again, and some of its tool results appear nowhere else: {"type": "api-request-blob", "hash": "…", "message": {"role": "user", "content": [{"type": "tool_result", …}, {"type": "text", …}]}}
|
||||
case "api-request-blob":
|
||||
return ToolResults(**carried, results=results_in(found))
|
||||
if (queued := queued_human_text(found)) is not None:
|
||||
return HumanTurn(**carried, text=queued)
|
||||
return Entry(**carried)
|
||||
|
||||
|
||||
class Carried(typing.TypedDict):
|
||||
"""The fields of Entry, read from any kind of entry."""
|
||||
uuid: str
|
||||
parent_uuid: str
|
||||
timestamp: str
|
||||
cwd: str
|
||||
git_branch: str
|
||||
|
||||
|
||||
# Alike in the transcript and in stream-json: {"type": "assistant", "message": {"id": "msg_01…", "model": "claude-opus-5-5", "content": [{"type": "text", "text": "ok"}], "usage": {...}}}
|
||||
def assistant_turn(found: dict, carried: Carried) -> AssistantTurn:
|
||||
message = found["message"] if isinstance(found.get("message"), dict) else {}
|
||||
usage = message.get("usage")
|
||||
parts = tuple(part for block in blocks(found) if (part := part_from(block)))
|
||||
return AssistantTurn(**carried, parts=parts, message_id=field(message, "id"), model=field(message, "model"), usage=usage if isinstance(usage, dict) else {})
|
||||
|
||||
|
||||
def user_entry(found: dict, carried: Carried) -> UserText | ToolResults:
|
||||
if results := results_in(found):
|
||||
return ToolResults(**carried, results=results)
|
||||
said = content(found)
|
||||
text = said if isinstance(said, str) else "".join(part_text(block) or "" for block in blocks(found))
|
||||
# {"type": "user", "promptSource": "sdk", "message": {"content": "Continue the task; the previous run ended before the chunk was finished."}}
|
||||
if found.get("promptSource") == "sdk" and isinstance(said, str):
|
||||
return LoopPrompt(**carried, text=text)
|
||||
return HumanTurn(**carried, text=text) if written_by_human(found) else InjectedText(**carried, text=text)
|
||||
|
||||
|
||||
def results_in(found: dict) -> tuple[ToolResult, ...]:
|
||||
return tuple(result for block in blocks(found) if (result := tool_result(block)))
|
||||
|
||||
|
||||
# {"type": "cost-state", "totalCostUSD": 40.1, "modelUsage": {"claude-opus-5-5": {"costUSD": 40.1, "outputTokens": 334504, ...}}, ...}
|
||||
def cost_state(found: dict, carried: Carried) -> CostState:
|
||||
by_model = found["modelUsage"] if isinstance(found.get("modelUsage"), dict) else {}
|
||||
return CostState(**carried, costs={model: cost for model, usage in by_model.items() if isinstance(usage, dict) and isinstance(cost := usage.get("costUSD"), (int, float))})
|
||||
|
||||
|
||||
def tool_calls(entries: typing.Iterable[Entry]) -> list[tuple[AssistantTurn, ToolCall]]:
|
||||
"""Each tool call, with the turn that made it."""
|
||||
return [(entry, part) for entry in entries if isinstance(entry, AssistantTurn) for part in entry.parts if isinstance(part, ToolCall)]
|
||||
|
||||
|
||||
def messages(entries: typing.Iterable[Entry]) -> list[list[AssistantTurn]]:
|
||||
"""The assistant turns grouped by message, in the order each message first appears. A message's usage repeats in each of its entries, so read it from the first of a group: none of 1,681 multi-entry messages in the archive of 2026-10-28 differed."""
|
||||
grouped: dict[str, list[AssistantTurn]] = {}
|
||||
for entry in entries:
|
||||
if isinstance(entry, AssistantTurn):
|
||||
grouped.setdefault(entry.message_id or entry.uuid, []).append(entry)
|
||||
return list(grouped.values())
|
||||
|
||||
|
||||
def field(found: dict, key: str) -> str:
|
||||
return value if isinstance(value := found.get(key), str) else ""
|
||||
|
||||
|
||||
def content(entry: dict) -> object:
|
||||
@@ -16,22 +163,17 @@ def content(entry: dict) -> object:
|
||||
return message.get("content") if isinstance(message, dict) else None
|
||||
|
||||
|
||||
def parts(entry: dict) -> list:
|
||||
def blocks(entry: dict) -> list:
|
||||
found = content(entry)
|
||||
return found if isinstance(found, list) else []
|
||||
|
||||
|
||||
# Alike in the transcript and in stream-json: {"type": "assistant", "message": {"content": [{"type": "text", "text": "ok"}]}}
|
||||
def assistant_parts(entry: dict) -> list:
|
||||
return parts(entry) if entry.get("type") == "assistant" else []
|
||||
|
||||
|
||||
def written_by_human(entry: dict) -> bool:
|
||||
"""Whether the human wrote a "user" entry; Claude Code writes the rest."""
|
||||
if tagged_as_injected(entry):
|
||||
return False
|
||||
text = content(entry)
|
||||
return string_by_human(entry, text) if isinstance(text, str) else blocks_by_human(parts(entry))
|
||||
return string_by_human(entry, text) if isinstance(text, str) else blocks_by_human(blocks(entry))
|
||||
|
||||
|
||||
# {"type": "user", "isMeta": true, "message": {"content": "<local-command-caveat>Caveat: ..."}}
|
||||
@@ -50,30 +192,12 @@ def string_by_human(entry: dict, text: str) -> bool:
|
||||
|
||||
|
||||
# {"type": "user", "message": {"content": [{"type": "text", "text": "merge it"}]}}
|
||||
# {"type": "user", "message": {"content": [{"tool_use_id": "toolu_01…", "type": "tool_result", "content": "hi"}]}}
|
||||
# {"type": "user", "message": {"content": [{"type": "text", "text": "[Request interrupted by user]"}]}}
|
||||
def blocks_by_human(blocks: list) -> bool:
|
||||
texts = [part_text(block) for block in blocks]
|
||||
def blocks_by_human(found: list) -> bool:
|
||||
texts = [part_text(block) for block in found]
|
||||
return bool(texts) and all(text is not None and not text.startswith("[Request interrupted") for text in texts)
|
||||
|
||||
|
||||
def human_text(entry: dict) -> str | None:
|
||||
"""What the human wrote in the entry, or None where Claude Code wrote it."""
|
||||
if (queued := queued_human_text(entry)) is not None:
|
||||
return queued
|
||||
if entry.get("type") != "user" or not written_by_human(entry):
|
||||
return None
|
||||
text = content(entry)
|
||||
return text if isinstance(text, str) else "".join(part_text(part) or "" for part in parts(entry))
|
||||
|
||||
|
||||
# {"type": "user", "promptSource": "sdk", "message": {"content": "Continue the task; the previous run ended before the chunk was finished."}}
|
||||
def loop_text(entry: dict) -> str | None:
|
||||
"""What loop-claude told the worker in a -p prompt."""
|
||||
text = content(entry)
|
||||
return text if entry.get("type") == "user" and entry.get("promptSource") == "sdk" and isinstance(text, str) else None
|
||||
|
||||
|
||||
# What the human types while claude works, written only as this entry:
|
||||
# {"type": "attachment", "attachment": {"type": "queued_command", "commandMode": "prompt", "origin": {"kind": "human"}, "prompt": "B"}}
|
||||
def queued_human_text(entry: dict) -> str | None:
|
||||
@@ -83,26 +207,20 @@ def queued_human_text(entry: dict) -> str | None:
|
||||
return prompt if isinstance(prompt := attachment.get("prompt"), str) else None
|
||||
|
||||
|
||||
# {"type": "tool_use", "id": "toolu_01…", "name": "Bash", "input": {"command": "echo hi"}}
|
||||
def part_from(block: object) -> Text | ToolCall | None:
|
||||
if (text := part_text(block)) is not None:
|
||||
return Text(text)
|
||||
if isinstance(block, dict) and block.get("type") == "tool_use" and isinstance(name := block.get("name"), str) and isinstance(arguments := block.get("input"), dict):
|
||||
return ToolCall(field(block, "id"), name, arguments)
|
||||
return None
|
||||
|
||||
|
||||
# {"type": "text", "text": "ok"}
|
||||
def part_text(part: object) -> str | None:
|
||||
return part["text"] if isinstance(part, dict) and part.get("type") == "text" and isinstance(part.get("text"), str) else None
|
||||
|
||||
|
||||
# {"type": "tool_use", "id": "toolu_01…", "name": "Bash", "input": {"command": "echo hi"}}
|
||||
def tool_call(part: object) -> tuple[object, object] | None:
|
||||
return (part.get("name"), part.get("input")) if isinstance(part, dict) and part.get("type") == "tool_use" else None
|
||||
|
||||
|
||||
def tool_use_id(part: object) -> str | None:
|
||||
return part["id"] if isinstance(part, dict) and part.get("type") == "tool_use" and isinstance(part.get("id"), str) else None
|
||||
|
||||
|
||||
class ToolResult(typing.NamedTuple):
|
||||
tool_use_id: str
|
||||
text: str
|
||||
failed: bool
|
||||
|
||||
|
||||
# {"type": "tool_result", "tool_use_id": "toolu_01…", "content": "hi"}, its content also as [{"type": "text", "text": "hi"}], and with "is_error": true where the call failed
|
||||
def tool_result(part: object) -> ToolResult | None:
|
||||
if not isinstance(part, dict) or part.get("type") != "tool_result":
|
||||
@@ -113,7 +231,7 @@ def tool_result(part: object) -> ToolResult | None:
|
||||
def result_text(content: object) -> str:
|
||||
if isinstance(content, str):
|
||||
return content
|
||||
# Claude Code may split one text across blocks, even inside a line, so the blocks join with nothing between them.
|
||||
# Claude Code may split one text across blocks, even inside a line, so the blocks join without anything between them.
|
||||
return "".join(part_text(part) or "" for part in content) if isinstance(content, list) else ""
|
||||
|
||||
|
||||
@@ -147,7 +265,7 @@ def rejected_until(event: dict) -> int | None:
|
||||
return resets_at if isinstance(resets_at, int) and not isinstance(resets_at, bool) else None
|
||||
|
||||
|
||||
# A count Claude Code left out or wrote as another type adds nothing, so one odd entry leaves the rest of a figure standing.
|
||||
# A count Claude Code left out or wrote as another type doesn't add anything, so one odd entry leaves the rest of a figure standing.
|
||||
def usage_count(usage: dict, field: str) -> int:
|
||||
"""One token count of a message's usage: {"input_tokens": 2, "cache_creation_input_tokens": 14541, "output_tokens": 8, ...}"""
|
||||
value = usage.get(field)
|
||||
|
||||
@@ -0,0 +1,10 @@
|
||||
"""The environment variables that cut what one tool result adds to a claude's context: the Bash ceiling loop-claude hands the worker's claude, and the Read limit that review-replay tests for it. Their values: docs/decisions.md → `loop-claude: the worker's claude saves a Bash result of more than 6,000 characters to a file, and rule-hook refuses a Read of a session transcript`.
|
||||
|
||||
A subagent inherits both variables, so the ceiling reaches every reviewer the worker launches."""
|
||||
|
||||
# Claude Code saves a Bash result longer than this many characters to a file, and hands the model the file's path and the first 2,000 characters. The file sits under ~/.claude/projects/<project>/<session>/tool-results/.
|
||||
BASH_CEILING = "BASH_MAX_OUTPUT_LENGTH"
|
||||
BASH_CEILING_CHARACTERS = 6_000
|
||||
# A Read of more than this many tokens fails and asks for an offset and a limit; Claude Code's default is 25,000.
|
||||
READ_LIMIT = "CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS"
|
||||
READ_LIMIT_TOKENS = 5_000
|
||||
@@ -1,10 +1,10 @@
|
||||
"""One `claude -p --output-format json` run, as loop-claude's judge and the replays start it."""
|
||||
"""One `claude -p --output-format stream-json` run, as loop-claude's judge and the replays start it."""
|
||||
import dataclasses
|
||||
import subprocess
|
||||
import typing
|
||||
|
||||
from failure import Failure
|
||||
from claude_code.entries import hit_limit, limit_said, parse_entry
|
||||
from claude_code.entries import hit_limit, json_object, limit_said
|
||||
|
||||
# Effects.claude: claude's arguments, its working directory and the prompt it reads on stdin.
|
||||
Claude = typing.Callable[[list[str], str, str], subprocess.CompletedProcess[str]]
|
||||
@@ -17,22 +17,23 @@ class Limited:
|
||||
said: str
|
||||
|
||||
|
||||
# The json reply claude_reply parses; no persistence, so its runs stay out of the session picker; no permission prompt, as no one answers it.
|
||||
HEADLESS = ["--no-session-persistence", "--output-format", "json", "--permission-mode", "bypassPermissions"]
|
||||
# No persistence, so these runs stay out of the session picker; Claude Code then writes no transcript, so stream-json, which prints one, lets a caller keep it. claude_reply reads the reply from the stream's last line. -p needs --verbose with stream-json. No permission prompt, as no one answers it.
|
||||
HEADLESS = ["--no-session-persistence", "--output-format", "stream-json", "--verbose", "--permission-mode", "bypassPermissions"]
|
||||
|
||||
|
||||
def claude_reply(claude: Claude, args: list[str], cwd: str, prompt: str, who: str) -> dict | Failure | Limited:
|
||||
"""claude's json reply to `claude -p <args>` and HEADLESS, or why there is none; who, such as "the judge", names the run in the message for a non-zero exit or a reply that is no json."""
|
||||
"""claude's reply to `claude -p <args>` and HEADLESS, the result event that ends its stream, or why there is none; who, such as "the judge", names the run in the message for a non-zero exit or a last line that isn't a json object."""
|
||||
try:
|
||||
proc = claude(["-p", *args, *HEADLESS], cwd, prompt)
|
||||
except OSError as failure:
|
||||
return Failure(f"could not start claude: {failure.strerror}")
|
||||
reply = parse_entry(proc.stdout)
|
||||
# The json output names the reset only in prose, such as "resets 7:40pm (Europe/Stockholm)", so its limit carries no reset time.
|
||||
last = proc.stdout.strip().rpartition("\n")[2]
|
||||
reply = json_object(last)
|
||||
# The result event names the reset only in prose, such as "resets 7:40pm (Europe/Stockholm)", so its limit carries no reset time; the stream's rate_limit_event holds it as a time, which nothing reads here yet.
|
||||
if reply is not None and hit_limit(reply):
|
||||
return Limited(None, limit_said(reply))
|
||||
if proc.returncode != 0:
|
||||
return Failure(proc.stderr.strip() or f"{who} exited {proc.returncode}")
|
||||
if reply is None:
|
||||
return Failure(f"{who} printed no json reply; it printed: {proc.stdout.strip() or 'nothing'}")
|
||||
return Failure(f"{who} printed no json reply; its last line was: {last or 'nothing'}")
|
||||
return reply
|
||||
|
||||
@@ -52,5 +52,5 @@ def delete_session(session: Session) -> Failure | None:
|
||||
try:
|
||||
shutil.rmtree(sibling) if os.path.isdir(sibling) else os.remove(sibling)
|
||||
except OSError as failure:
|
||||
return Failure(f"could not delete {sibling}: {failure.strerror or failure}; delete every file and folder matching {stem}*, then rerun loop-claude; a rerun before that resumes the finished chunk's session")
|
||||
return Failure(f"could not delete {sibling}: {failure.strerror or failure}; delete every file and folder matching {stem}*, then run it again; a run before that resumes the finished chunk's session")
|
||||
return None
|
||||
|
||||
@@ -18,13 +18,17 @@ def human(content):
|
||||
return {"type": "user", "message": {"content": content}}
|
||||
|
||||
|
||||
def kinds(found):
|
||||
return [entries.entry_from(entry) for entry in found]
|
||||
|
||||
|
||||
def queued(prompt, kind):
|
||||
return {"type": "attachment", "attachment": {"type": "queued_command", "commandMode": "prompt", "origin": {"kind": kind}, "prompt": prompt}}
|
||||
|
||||
|
||||
class Render(unittest.TestCase):
|
||||
def test_joins_assistant_text_tool_calls_human_turns_and_loop_prompts_labelling_a_typed_answer_the_humans_and_skips_the_rest(self):
|
||||
said = transcript.render([
|
||||
said = transcript.render(kinds([
|
||||
human("do it"),
|
||||
assistant({"type": "text", "text": "Starting."}, {"type": "tool_use", "name": "Bash", "input": {"command": "ls"}}),
|
||||
assistant({"type": "text", "text": " "}),
|
||||
@@ -35,18 +39,10 @@ class Render(unittest.TestCase):
|
||||
queued("origin/main moved", "coordinator"),
|
||||
{**human("Continue the task; the previous run stopped before it was finished."), "promptSource": "sdk"},
|
||||
{**human("Answered: use B\nYour question: A or B?"), "promptSource": "sdk"},
|
||||
], lambda prompt: transcript.Typed(*reversed(prompt.removeprefix("Answered: ").split("\n"))) if prompt.startswith("Answered: ") else None)
|
||||
]), lambda prompt: transcript.Typed(*reversed(prompt.removeprefix("Answered: ").split("\n"))) if prompt.startswith("Answered: ") else None)
|
||||
self.assertEqual(said, '[human] do it\n\nStarting.\n\n[tool Bash] {"command": "ls"}\n\n[human] yes, merge it\n\n[human] B, while you work\n\n[loop] Continue the task; the previous run stopped before it was finished.\n\n[loop] Your question: A or B?\n\n[human] use B')
|
||||
|
||||
|
||||
class Verbatim(unittest.TestCase):
|
||||
def test_a_quote_holds_only_word_for_word_less_emphasis_and_whitespace(self):
|
||||
self.assertTrue(transcript.verbatim("Merge **ff-only**.", "Merge ff-only.\nNever squash."))
|
||||
self.assertTrue(transcript.verbatim("Merge _ff-only_.", "Merge ff-only.\nNever squash."))
|
||||
self.assertFalse(transcript.verbatim("Merge ... squash.", "Merge ff-only.\nNever squash."))
|
||||
self.assertFalse(transcript.verbatim("", "Merge ff-only."))
|
||||
|
||||
|
||||
class FirstTimestampedLine(unittest.TestCase):
|
||||
def test_skips_the_lines_every_chunk_shares_and_else_takes_the_first(self):
|
||||
self.assertEqual(transcript.first_timestamped_line(b'{"type": "custom-title"}\nnot JSON\n{"timestamp": "t"}\n{"timestamp": "u"}\n'), b'{"timestamp": "t"}')
|
||||
@@ -57,15 +53,15 @@ class FirstTimestampedLine(unittest.TestCase):
|
||||
class CurrentThread(unittest.TestCase):
|
||||
def test_a_parent_cycle_ends_the_thread(self):
|
||||
looped = [{"uuid": "a", "parentUuid": "b"}, {"uuid": "b", "parentUuid": "a"}]
|
||||
self.assertEqual([entry["uuid"] for entry in transcript.current_thread(looped)], ["a", "b"])
|
||||
self.assertEqual([entry.uuid for entry in transcript.current_thread(kinds(looped))], ["a", "b"])
|
||||
|
||||
def test_entries_without_a_uuid_make_no_thread(self):
|
||||
self.assertEqual(transcript.current_thread([{"type": "summary"}]), [])
|
||||
self.assertEqual(transcript.current_thread(kinds([{"type": "summary"}])), [])
|
||||
|
||||
|
||||
class HumanTurns(unittest.TestCase):
|
||||
def test_counts_typed_turns_and_not_tool_results(self):
|
||||
self.assertEqual(transcript.human_turns([
|
||||
self.assertEqual(transcript.human_turns(kinds([
|
||||
human("typed"),
|
||||
human([{"type": "text", "text": "typed as a block"}]),
|
||||
human([{"type": "tool_result", "content": "not typed"}]),
|
||||
@@ -82,25 +78,109 @@ class HumanTurns(unittest.TestCase):
|
||||
queued("<task-notification>done</task-notification>", "task-notification"),
|
||||
{"type": "attachment", "attachment": {"type": "queued_command", "commandMode": "task-notification", "prompt": "<task-notification>done</task-notification>"}},
|
||||
assistant({"type": "text", "text": "said"}),
|
||||
]), 4)
|
||||
])), 4)
|
||||
|
||||
|
||||
class PartLine(unittest.TestCase):
|
||||
def test_renders_text_and_tool_calls_and_nothing_else(self):
|
||||
self.assertEqual(transcript.part_line({"type": "text", "text": "hi"}, 20), "hi")
|
||||
self.assertEqual(transcript.part_line({"type": "text", "text": " \n"}, 20), "")
|
||||
self.assertEqual(transcript.part_line({"type": "tool_use", "name": "Bash", "input": {"command": "x" * 500}}, 20), '[tool Bash] {"command": "xxxxxxx')
|
||||
self.assertEqual(transcript.part_line("not a part", 20), "")
|
||||
self.assertEqual(transcript.part_line({"type": "tool_use", "name": "Write", "input": {"content": "Hälsa på"}}, 40), '[tool Write] {"content": "Hälsa på"}')
|
||||
def test_renders_text_and_tool_calls_but_blank_text_as_nothing(self):
|
||||
self.assertEqual(transcript.part_line(entries.Text("hi"), 20), "hi")
|
||||
self.assertEqual(transcript.part_line(entries.Text(" \n"), 20), "")
|
||||
self.assertEqual(transcript.part_line(entries.ToolCall("toolu_1", "Bash", {"command": "x" * 500}), 20), '[tool Bash] {"command": "xxxxxxx')
|
||||
self.assertEqual(transcript.part_line(entries.ToolCall("toolu_1", "Write", {"content": "Hälsa på"}), 40), '[tool Write] {"content": "Hälsa på"}')
|
||||
|
||||
|
||||
class Parse(unittest.TestCase):
|
||||
def test_yields_only_json_objects(self):
|
||||
self.assertEqual(entries.parse_entry('{"type": "user"}'), {"type": "user"})
|
||||
self.assertIsNone(entries.parse_entry("not json"))
|
||||
self.assertEqual(entries.json_object('{"type": "user"}'), {"type": "user"})
|
||||
self.assertIsNone(entries.json_object("not json"))
|
||||
self.assertIsNone(entries.json_object("[1, 2]"))
|
||||
|
||||
def test_a_transcript_line_parses_into_its_kind(self):
|
||||
self.assertEqual(entries.parse_entry('{"type": "user", "message": {"content": "do it"}}'), entries.HumanTurn(text="do it"))
|
||||
self.assertIsNone(entries.parse_entry("[1, 2]"))
|
||||
|
||||
|
||||
class EntryKinds(unittest.TestCase):
|
||||
def test_names_who_wrote_each_user_entry_and_queued_prompt(self):
|
||||
self.assertEqual([entries.entry_from(found) for found in [
|
||||
human("typed"),
|
||||
human([{"type": "text", "text": "typed "}, {"type": "text", "text": "as blocks"}]),
|
||||
{**human("<3 merge it"), "promptSource": "typed"},
|
||||
queued("typed while claude worked", "human"),
|
||||
{**human("Continue the task."), "promptSource": "sdk"},
|
||||
{**human([{"type": "text", "text": "Continue as a block."}]), "promptSource": "sdk"},
|
||||
human("<command-name>/model</command-name>"),
|
||||
{**human("peer message"), "isMeta": True},
|
||||
{**human("<task-notification>done</task-notification>"), "promptSource": "system"},
|
||||
human([{"type": "text", "text": "[Request interrupted by user]"}]),
|
||||
human([]),
|
||||
]], [
|
||||
entries.HumanTurn(text="typed"),
|
||||
entries.HumanTurn(text="typed as blocks"),
|
||||
entries.HumanTurn(text="<3 merge it"),
|
||||
entries.HumanTurn(text="typed while claude worked"),
|
||||
entries.LoopPrompt(text="Continue the task."),
|
||||
entries.InjectedText(text="Continue as a block."),
|
||||
entries.InjectedText(text="<command-name>/model</command-name>"),
|
||||
entries.InjectedText(text="peer message"),
|
||||
entries.InjectedText(text="<task-notification>done</task-notification>"),
|
||||
entries.InjectedText(text="[Request interrupted by user]"),
|
||||
entries.InjectedText(text=""),
|
||||
])
|
||||
|
||||
def test_an_assistant_turn_keeps_its_text_and_tool_calls_and_its_message(self):
|
||||
turn = {**assistant(
|
||||
{"type": "thinking", "thinking": "hm"},
|
||||
{"type": "text", "text": "Starting."},
|
||||
{"type": "tool_use", "id": "toolu_1", "name": "Bash", "input": {"command": "ls"}},
|
||||
{"type": "tool_use", "id": "toolu_2", "name": "Bash", "input": "not arguments"},
|
||||
), "uuid": "u"}
|
||||
turn["message"] |= {"id": "msg_1", "model": "claude-opus-5-5", "usage": {"input_tokens": 2}}
|
||||
self.assertEqual(entries.entry_from(turn), entries.AssistantTurn(
|
||||
uuid="u", parts=(entries.Text("Starting."), entries.ToolCall("toolu_1", "Bash", {"command": "ls"})), message_id="msg_1", model="claude-opus-5-5", usage={"input_tokens": 2},
|
||||
))
|
||||
|
||||
def test_messages_group_the_turns_that_share_a_message_id_and_fall_back_to_the_uuid_where_there_is_none(self):
|
||||
first = entries.AssistantTurn(uuid="a", message_id="msg_1", usage={"input_tokens": 1})
|
||||
other = entries.AssistantTurn(uuid="b", message_id="msg_2")
|
||||
again = entries.AssistantTurn(uuid="c", message_id="msg_1", usage={"input_tokens": 2})
|
||||
bare = entries.AssistantTurn(uuid="d")
|
||||
self.assertEqual(entries.messages([first, entries.HumanTurn(text="hi"), other, again, bare]), [[first, again], [other], [bare]])
|
||||
|
||||
def test_parses_tool_results_and_cost_states_and_reads_queued_notifications_and_other_kinds_as_plain_entries(self):
|
||||
self.assertEqual(entries.entry_from(human([{"type": "tool_result", "tool_use_id": "toolu_1", "content": "hi", "is_error": True}])), entries.ToolResults(results=(entries.ToolResult("toolu_1", "hi", True),)))
|
||||
self.assertEqual(entries.entry_from(queued("<task-notification>done</task-notification>", "task-notification")), entries.Entry())
|
||||
self.assertEqual(entries.entry_from({"type": "system", "subtype": "compact_boundary"}), entries.Entry())
|
||||
cost_state = {"type": "cost-state", "totalCostUSD": 41.1, "modelUsage": {"claude-opus-5-5": {"costUSD": 40.1, "outputTokens": 334504}, "claude-haiku-5-5": {"costUSD": 1}, "odd": {"costUSD": "1"}, "odder": 1}}
|
||||
self.assertEqual(entries.entry_from(cost_state), entries.CostState(costs={"claude-opus-5-5": 40.1, "claude-haiku-5-5": 1}))
|
||||
self.assertEqual(entries.entry_from({"type": "cost-state", "modelUsage": []}), entries.CostState(costs={}))
|
||||
|
||||
def test_the_api_request_claude_code_logs_yields_its_tool_results_and_none_of_its_text(self):
|
||||
blob = {"type": "api-request-blob", "hash": "h", "message": {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "toolu_1", "content": "hi"}, {"type": "text", "text": "the request again"}]}}
|
||||
self.assertEqual(entries.entry_from(blob), entries.ToolResults(results=(entries.ToolResult("toolu_1", "hi", False),)))
|
||||
self.assertEqual(entries.entry_from({"type": "api-request-blob", "message": {"role": "user", "content": [{"type": "text", "text": "do it"}]}}), entries.ToolResults(results=()))
|
||||
|
||||
def test_mixed_blocks_join_only_their_text(self):
|
||||
self.assertEqual(entries.entry_from(human([{"type": "text", "text": "see "}, {"type": "image", "source": {}}, {"type": "text", "text": "this"}])), entries.InjectedText(text="see this"))
|
||||
|
||||
def test_every_kind_carries_where_and_when_it_was_written(self):
|
||||
where = {"uuid": "b", "parentUuid": "a", "timestamp": "2026-10-15T00:00:00.123Z", "cwd": "/r", "gitBranch": "item-1"}
|
||||
carried = {"uuid": "b", "parent_uuid": "a", "timestamp": "2026-10-15T00:00:00.123Z", "cwd": "/r", "git_branch": "item-1"}
|
||||
for found, kind in [
|
||||
({"type": "summary"}, entries.Entry(**carried)),
|
||||
(human("typed"), entries.HumanTurn(**carried, text="typed")),
|
||||
(queued("typed while claude worked", "human"), entries.HumanTurn(**carried, text="typed while claude worked")),
|
||||
({**human("Continue."), "promptSource": "sdk"}, entries.LoopPrompt(**carried, text="Continue.")),
|
||||
(human("<command-name>/model</command-name>"), entries.InjectedText(**carried, text="<command-name>/model</command-name>")),
|
||||
(human([{"type": "tool_result", "tool_use_id": "toolu_1", "content": "hi"}]), entries.ToolResults(**carried, results=(entries.ToolResult("toolu_1", "hi", False),))),
|
||||
(assistant(), entries.AssistantTurn(**carried)),
|
||||
({"type": "cost-state", "modelUsage": {}}, entries.CostState(**carried, costs={})),
|
||||
]:
|
||||
with self.subTest(kind=type(kind).__name__):
|
||||
self.assertEqual(entries.entry_from({**found, **where}), kind)
|
||||
self.assertEqual(entries.entry_from({"type": "summary", "uuid": 1, "parentUuid": None}), entries.Entry())
|
||||
|
||||
|
||||
class ClaudeReply(unittest.TestCase):
|
||||
@staticmethod
|
||||
def claude(*results):
|
||||
@@ -119,12 +199,19 @@ class ClaudeReply(unittest.TestCase):
|
||||
return subprocess.CompletedProcess(args, 0, "{}", "")
|
||||
|
||||
reply.claude_reply(run, ["--tools", ""], "/r", "p", "the judge")
|
||||
self.assertEqual(asked, [(["-p", "--tools", "", "--no-session-persistence", "--output-format", "json", "--permission-mode", "bypassPermissions"], "/r", "p")])
|
||||
self.assertEqual(asked, [(["-p", "--tools", "", "--no-session-persistence", "--output-format", "stream-json", "--verbose", "--permission-mode", "bypassPermissions"], "/r", "p")])
|
||||
|
||||
def test_reads_the_reply_from_the_streams_last_line(self):
|
||||
stream = "\n".join(json.dumps(event) for event in ({"type": "system", "subtype": "init"}, {"type": "assistant"}, {"type": "result", "result": "ok"}))
|
||||
self.assertEqual(reply.claude_reply(self.claude((0, stream + "\n", "")), [], "/r", "p", "the judge"), {"type": "result", "result": "ok"})
|
||||
|
||||
def test_a_stream_that_ends_in_no_json_names_only_its_last_line(self):
|
||||
self.assertEqual(reply.claude_reply(self.claude((0, '{"type": "system"}\nWarning: bye\n', "")), [], "/r", "p", "the judge"), Failure("the judge printed no json reply; its last line was: Warning: bye"))
|
||||
|
||||
def test_returns_the_json_reply_a_usage_limit_whatever_the_exit_code_or_why_there_is_none(self):
|
||||
self.assertEqual(reply.claude_reply(self.claude((0, '{"result": "ok"}', "")), [], "/r", "p", "the judge"), {"result": "ok"})
|
||||
self.assertEqual(reply.claude_reply(self.claude((0, "Warning: hook said hi\n", "")), [], "/r", "p", "the judge"), Failure("the judge printed no json reply; it printed: Warning: hook said hi"))
|
||||
self.assertEqual(reply.claude_reply(self.claude((0, "", "")), [], "/r", "p", "the judge"), Failure("the judge printed no json reply; it printed: nothing"))
|
||||
self.assertEqual(reply.claude_reply(self.claude((0, "Warning: hook said hi\n", "")), [], "/r", "p", "the judge"), Failure("the judge printed no json reply; its last line was: Warning: hook said hi"))
|
||||
self.assertEqual(reply.claude_reply(self.claude((0, "", "")), [], "/r", "p", "the judge"), Failure("the judge printed no json reply; its last line was: nothing"))
|
||||
limit = json.dumps({"type": "result", "api_error_status": 429, "result": "You've hit your limit"})
|
||||
self.assertEqual(reply.claude_reply(self.claude((1, limit, "")), [], "/r", "p", "the judge"), reply.Limited(None, "You've hit your limit"))
|
||||
self.assertEqual(reply.claude_reply(self.claude((2, "", " ")), [], "/r", "p", "the judge"), Failure("the judge exited 2"))
|
||||
|
||||
@@ -0,0 +1,32 @@
|
||||
"""The tokens a message's usage counts, by kind."""
|
||||
import dataclasses
|
||||
|
||||
from claude_code.entries import usage_count
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Tokens:
|
||||
"""Raw token counts by kind. Claude Code's usage doesn't count thinking apart from output, so output holds both."""
|
||||
input: int = 0
|
||||
write_5m: int = 0
|
||||
write_1h: int = 0
|
||||
read: int = 0
|
||||
output: int = 0
|
||||
|
||||
def context(self) -> int:
|
||||
"""The tokens of the prompt the message answered: its context."""
|
||||
return self.input + self.write_5m + self.write_1h + self.read
|
||||
|
||||
def plus(self, other: "Tokens") -> "Tokens":
|
||||
return Tokens(*(mine + theirs for mine, theirs in zip(dataclasses.astuple(self), dataclasses.astuple(other))))
|
||||
|
||||
|
||||
# {"input_tokens": 2, "cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 25919}, "cache_read_input_tokens": 10365, "output_tokens": 193, ...}
|
||||
def tokens_of(usage: object) -> Tokens:
|
||||
"""The tokens of one message's usage, or of a json reply's; none where it is no object."""
|
||||
if not isinstance(usage, dict):
|
||||
return Tokens()
|
||||
written = usage.get("cache_creation")
|
||||
# A write without the split by lifetime counts as a five-minute one.
|
||||
five, hour = (usage_count(written, "ephemeral_5m_input_tokens"), usage_count(written, "ephemeral_1h_input_tokens")) if isinstance(written, dict) else (usage_count(usage, "cache_creation_input_tokens"), 0)
|
||||
return Tokens(usage_count(usage, "input_tokens"), five, hour, usage_count(usage, "cache_read_input_tokens"), usage_count(usage, "output_tokens"))
|
||||
@@ -1,8 +1,11 @@
|
||||
import io
|
||||
import json
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from claude_code.entries import assistant_parts, human_text, loop_text, parse_entry, part_text, tool_call
|
||||
from claude_code.entries import AssistantTurn, Entry, HumanTurn, LoopPrompt, parse_entry, Text, ToolCall
|
||||
from failure import Failure
|
||||
from text_files.compressed import read_stored
|
||||
|
||||
JUDGED_TOOL_INPUT = 400
|
||||
|
||||
@@ -13,67 +16,70 @@ class Typed(typing.NamedTuple):
|
||||
answer: str
|
||||
|
||||
|
||||
def read_transcript(path: str) -> list[dict] | Failure:
|
||||
def read_transcript(path: str) -> list[Entry] | Failure:
|
||||
"""The entries of the transcript at path, or of its gzip where compress-archives gzipped it."""
|
||||
try:
|
||||
with open(path, "rb") as handle:
|
||||
return [entry for raw in handle if (entry := parse_entry(raw))]
|
||||
return [entry for raw in io.BytesIO(read_stored(pathlib.Path(path))) if (entry := parse_entry(raw))]
|
||||
except OSError as failure:
|
||||
return Failure(f"could not read the transcript {path}: {failure.strerror}")
|
||||
|
||||
|
||||
def current_thread(entries: list[dict]) -> list[dict]:
|
||||
def current_thread(entries: list[Entry]) -> list[Entry]:
|
||||
"""The entries of the transcript's current thread since its last compaction, oldest first: the newest entry with a uuid and its ancestors by parentUuid.
|
||||
|
||||
That leaves out a branch the session rewound, and the results of parallel tool calls that Claude Code chains on a side branch."""
|
||||
chained = [entry for entry in entries if isinstance(entry.get("uuid"), str)]
|
||||
by_uuid = {entry["uuid"]: entry for entry in chained}
|
||||
found: list[dict] = []
|
||||
chained = [entry for entry in entries if entry.uuid]
|
||||
by_uuid = {entry.uuid: entry for entry in chained}
|
||||
found: list[Entry] = []
|
||||
entry = chained[-1] if chained else None
|
||||
# A compaction writes {"type": "system", "subtype": "compact_boundary", "parentUuid": null, ...}, so the thread starts there; the length check stops a parent cycle.
|
||||
while entry is not None and len(found) < len(chained):
|
||||
found.append(entry)
|
||||
entry = by_uuid.get(entry.get("parentUuid"))
|
||||
entry = by_uuid.get(entry.parent_uuid)
|
||||
return found[::-1]
|
||||
|
||||
|
||||
# The lines before it, such as the session's title, are the same for every chunk of a project.
|
||||
def first_timestamped_line(raw: bytes) -> bytes:
|
||||
lines = raw.splitlines()
|
||||
return next((line for line in lines if "timestamp" in (parse_entry(line) or {})), lines[0] if lines else b"")
|
||||
return next((line for line in lines if (entry := parse_entry(line)) and entry.timestamp), lines[0] if lines else b"")
|
||||
|
||||
|
||||
def human_turns(entries: list[dict]) -> int:
|
||||
return sum(1 for entry in entries if human_text(entry) is not None)
|
||||
def human_turns(entries: list[Entry]) -> int:
|
||||
return sum(1 for entry in entries if isinstance(entry, HumanTurn))
|
||||
|
||||
|
||||
def render(entries: list[dict], typed_answer: typing.Callable[[str], Typed | None]) -> str:
|
||||
def render(entries: list[Entry], typed_answer: typing.Callable[[str], Typed | None]) -> str:
|
||||
"""The transcript as the judge reads it. typed_answer splits the answer the human typed out of a -p prompt of loop-claude's, so that answer reads as the human's, like one typed in claude."""
|
||||
lines = []
|
||||
for entry in entries:
|
||||
lines += [line for part in assistant_parts(entry) if (line := part_line(part, JUDGED_TOOL_INPUT))]
|
||||
if (text := human_text(entry)) is not None:
|
||||
lines.append("[human] " + text)
|
||||
elif (text := loop_text(entry)) is not None:
|
||||
typed = typed_answer(text)
|
||||
lines += ["[loop] " + text] if typed is None else ["[loop] " + typed.loop_words, "[human] " + typed.answer]
|
||||
if isinstance(entry, AssistantTurn):
|
||||
lines += assistant_lines(entry)
|
||||
elif isinstance(entry, HumanTurn):
|
||||
lines.append("[human] " + entry.text)
|
||||
elif isinstance(entry, LoopPrompt):
|
||||
typed = typed_answer(entry.text)
|
||||
lines += ["[loop] " + entry.text] if typed is None else ["[loop] " + typed.loop_words, "[human] " + typed.answer]
|
||||
return "\n\n".join(lines)
|
||||
|
||||
|
||||
def part_line(part: object, tool_input_chars: int) -> str:
|
||||
if (text := part_text(part)) and text.strip():
|
||||
return text
|
||||
if call := tool_call(part):
|
||||
name, arguments = call
|
||||
return f"[tool {name}] {json.dumps(arguments, ensure_ascii=False)[:tool_input_chars]}"
|
||||
return ""
|
||||
def human_answers(entries: list[Entry], typed_answer: typing.Callable[[str], Typed | None]) -> list[str]:
|
||||
"""Each answer the human typed, whole, as render shows it on a [human] line, latest last."""
|
||||
found = []
|
||||
for entry in entries:
|
||||
if isinstance(entry, HumanTurn):
|
||||
found.append(entry.text)
|
||||
elif isinstance(entry, LoopPrompt) and (typed := typed_answer(entry.text)):
|
||||
found.append(typed.answer)
|
||||
return found
|
||||
|
||||
|
||||
def verbatim(quote: str, text: str) -> bool:
|
||||
"""Whether text holds the judge's quote word for word, once plain strips emphasis and reflows whitespace in both."""
|
||||
quoted = plain(quote)
|
||||
return quoted != "" and quoted in plain(text)
|
||||
def assistant_lines(turn: AssistantTurn) -> list[str]:
|
||||
"""The turn's text and tool calls as the judge reads them."""
|
||||
return [line for part in turn.parts if (line := part_line(part, JUDGED_TOOL_INPUT))]
|
||||
|
||||
|
||||
def plain(text: str) -> str:
|
||||
# The judge drops markdown emphasis and reflows whitespace when it quotes.
|
||||
return " ".join(text.replace("*", "").replace("_", "").split())
|
||||
def part_line(part: Text | ToolCall, tool_input_chars: int) -> str:
|
||||
if isinstance(part, ToolCall):
|
||||
return f"[tool {part.name}] {json.dumps(part.input, ensure_ascii=False)[:tool_input_chars]}"
|
||||
return part.text if part.text.strip() else ""
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user