Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
6a3bf5a71a
|
||
|
|
0218e4ec89
|
||
|
|
ce70d4f3ee
|
||
|
|
83613d902a
|
||
|
|
1026d5e3b6
|
||
|
|
ee4c3f9c16
|
||
|
|
21de660ae1
|
||
|
|
52b027955b
|
||
|
|
e2917420fb
|
||
|
|
c226c4f686
|
||
|
|
9e2cf252ac
|
||
|
|
9fe446a426
|
||
|
|
20d81258ac
|
||
|
|
053ed58c08
|
||
|
|
546e5cd6ef
|
||
|
|
2f802e04a4
|
||
|
|
124d2033fc
|
||
|
|
46372b51d5
|
||
|
|
db36d853ce
|
||
|
|
4b97ac5841
|
||
|
|
e909aee155
|
||
|
|
564339e1aa
|
||
|
|
e45fee9bc9
|
||
|
|
4cdb5996c5
|
||
|
|
4657ff2646
|
||
|
|
703d5376bb
|
||
|
|
dd80500e7a
|
||
|
|
1e21aa975d
|
||
|
|
66b63260e9
|
||
|
|
470015483e
|
||
|
|
42f0688f84
|
||
|
|
b6f7059212
|
||
|
|
88afd1ebc9
|
||
|
|
a4a4e97f07
|
||
|
|
4bc0d54341
|
||
|
|
dabe0b4f7c
|
||
|
|
28733c8522
|
||
|
|
4b1ae4babf
|
||
|
|
50b75f6987
|
||
|
|
0c8b673615
|
||
|
|
ef62dcc97a
|
||
|
|
82cfc1de5b
|
||
|
|
983f462740
|
||
|
|
46edda9961
|
||
|
|
3dcc8da0de
|
||
|
|
a2972ac5d6
|
||
|
|
85e6f8eb40
|
||
|
|
55077620bb
|
||
|
|
400699cfbb
|
||
|
|
a0385a56c7
|
||
|
|
22aee72679
|
||
|
|
ff58c8e39b
|
||
|
|
25007e8316
|
||
|
|
b9dd744f8c
|
||
|
|
a91df7ec1f
|
||
|
|
5712c9c4e6
|
||
|
|
1f5163092b
|
||
|
|
4e1f1b3c4d
|
||
|
|
1b8eb362d2
|
||
|
|
7903a0e225
|
||
|
|
3a700cddfa
|
||
|
|
0238f247e5
|
||
|
|
e594ec3780
|
||
|
|
200c6d0928
|
||
|
|
0dbf241106
|
||
|
|
af753290e7
|
||
|
|
a6644c20cd
|
||
|
|
4877362223
|
||
|
|
0335872701
|
||
|
|
eb9d470ba8
|
||
|
|
a3d32e92e5
|
||
|
|
deb3865d75
|
||
|
|
6d97f62929
|
||
|
|
18d1e07a21
|
||
|
|
cf249d7643
|
||
|
|
66220e1752
|
||
|
|
93c9eb51f3
|
||
|
|
e787a79af4
|
||
|
|
777b17acf7
|
||
|
|
02df83ccb7
|
||
|
|
68d81fbbd0
|
||
|
|
75c3d2b096
|
||
|
|
e898acedc8
|
||
|
|
b89d9e0f05
|
||
|
|
58858f0d92
|
||
|
|
8b64ab0afe
|
||
|
|
e8366683a9
|
||
|
|
99a3d675a8
|
||
|
|
a69a0ea942
|
||
|
|
9cd31e48ca
|
||
|
|
998c72f8d3
|
||
|
|
7a311a3c74
|
||
|
|
e78cb1e63e
|
||
|
|
14e2474a49
|
||
|
|
86192e8053
|
||
|
|
990cd9408c
|
||
|
|
c7ce32df3e
|
||
|
|
5d620461fe
|
||
|
|
411632548c
|
||
|
|
a262151cb9
|
||
|
|
a8d1de8b5e
|
||
|
|
9f830db510
|
||
|
|
80129b7dd6
|
||
|
|
48c28b36ba
|
||
|
|
c5382a8476
|
||
|
|
eed9101d5b
|
||
|
|
cdfdf3a756
|
||
|
|
1d329bad35
|
||
|
|
f5c566bcab
|
||
|
|
90090922e1
|
||
|
|
a8f1fc9ea3
|
||
|
|
a9621b91cd
|
||
|
|
c7fabbee25
|
||
|
|
b7b6078939
|
||
|
|
39bfde195c
|
||
|
|
67ae6afec1
|
||
|
|
b314968328
|
||
|
|
432e6280d6
|
||
|
|
236d0b678a
|
||
|
|
5f45cdebb5
|
||
|
|
bfe28f6750
|
||
|
|
44a7d59acf
|
||
|
|
7148579544
|
||
|
|
6eea6aaffa
|
||
|
|
dc4cd29c83
|
||
|
|
87ed8a2e15
|
||
|
|
855e8ceb3b
|
||
|
|
7a9f507e2d
|
||
|
|
104854da2a
|
||
|
|
3225396cf1
|
||
|
|
811cab57ac
|
||
|
|
3a965e2a4f
|
||
|
|
7d664d7efb
|
||
|
|
92fbcd7a28
|
||
|
|
5edf58fd68
|
||
|
|
da1795c597
|
||
|
|
a18a4f7500
|
||
|
|
7ab209fa7e
|
||
|
|
97fbc35ee4
|
||
|
|
7d6f22d227
|
||
|
|
0451545220
|
||
|
|
5c02207d48
|
||
|
|
e784adbd7a
|
||
|
|
d3678869d2
|
||
|
|
6c287b48e6
|
||
|
|
bbd3c39ef1
|
||
|
|
2096ae8267
|
||
|
|
a1ec538a87
|
||
|
|
45b9295cb7
|
||
|
|
e7d3ed72e4
|
||
|
|
82f5afaa6d
|
||
|
|
2f95dfb67d
|
||
|
|
fb732974f5
|
||
|
|
81c59d7fac
|
||
|
|
a2b82b4c25
|
||
|
|
21dfb56e50
|
||
|
|
41f44c43a1
|
||
|
|
ca4b039cb4
|
||
|
|
841c6aea16
|
||
|
|
fb330f350d
|
||
|
|
6516477b20
|
||
|
|
9d8e4f68ab
|
||
|
|
3653376221
|
||
|
|
925365b245
|
||
|
|
5b3ae6abde
|
||
|
|
ecf4e6b95a
|
||
|
|
6a17951a3a
|
||
|
|
0cfa701f5c
|
||
|
|
a5ba2c994f
|
||
|
|
5e9e551fbb
|
||
|
|
5810c49260
|
||
|
|
e2df9cbd0a
|
||
|
|
806c82bda3
|
||
|
|
39929b9e48
|
||
|
|
f4b7652ae7
|
||
|
|
1def83a43f
|
||
|
|
6d54952cbb
|
||
|
|
757c3016ae
|
||
|
|
a0ee8e3f2e
|
||
|
|
3eb976ef83
|
||
|
|
47a340bf79
|
||
|
|
cdd636d5aa
|
||
|
|
4c54d250f6
|
||
|
|
f9ac9229d5
|
||
|
|
0d9e2d1cd8
|
||
|
|
e389e1a21e
|
||
|
|
73e32f016a
|
||
|
|
6b7f6f2731
|
||
|
|
f5be0d60dd
|
||
|
|
851cb78b04
|
||
|
|
f183a397cb
|
||
|
|
f49ba6bd66
|
||
|
|
8dba4e6dec
|
||
|
|
c26eeda939
|
||
|
|
e6a2a16bba
|
||
|
|
6cc8107ebb
|
||
|
|
8c3464163d
|
||
|
|
8d89f47d6b
|
||
|
|
260732f400
|
||
|
|
55e477794e
|
||
|
|
3ff1649322
|
||
|
|
bdc457d11e
|
||
|
|
500d02be78
|
||
|
|
0cd9cefd76
|
||
|
|
0a770ed171
|
||
|
|
0d13b919da
|
||
|
|
63a1750936
|
||
|
|
d0118756d7
|
||
|
|
f4c304cfba
|
||
|
|
afaea346ee
|
||
|
|
68e8552f0d
|
||
|
|
b25676b612
|
||
|
|
60c0f19e63
|
||
|
|
65e6bafb23
|
||
|
|
1c191b4ee0
|
||
|
|
892ed291b9
|
||
|
|
c5f24ec914
|
||
|
|
aefb4e486b
|
||
|
|
7c7129eefb
|
||
|
|
db346b159d
|
||
|
|
a3d4b751b9
|
||
|
|
f3a379add1
|
||
|
|
d7741d6088
|
||
|
|
27df64f8b0
|
||
|
|
8890c9ac3e
|
||
|
|
fb281c192a
|
||
|
|
fc6f614408
|
||
|
|
40526b077f
|
||
|
|
061227708d
|
||
|
|
a04fd3834d | ||
|
|
a4fbaaf84c | ||
|
|
606da1aee5
|
||
|
|
228f17d98a | ||
|
|
3c1ecc8087
|
||
|
|
29e263ab23
|
||
|
|
fbc9ed21e7 | ||
|
|
76be7b87b2 | ||
|
|
804d306f75
|
||
|
|
782daf8bbb | ||
|
|
5baef8805d | ||
|
|
82ca9613c7
|
||
|
|
4e9745d5c6
|
||
|
|
ea64d84696 | ||
|
|
2bec268b29 | ||
|
|
5b282c9efe | ||
|
|
7b295df8ff
|
||
|
|
607bfddd0e | ||
|
|
779b036d95 | ||
|
|
27e997e0d9 | ||
|
|
433ea390a6
|
||
|
|
ff8615b090
|
||
|
|
14da38b9b7
|
||
|
|
017a1d56e2 | ||
|
|
af02cbe832 | ||
|
|
38d9cca84a | ||
|
|
cdae23d7e9 | ||
|
|
1ae6d39680 | ||
|
|
07e4e8f727 | ||
|
|
98941c20a0
|
||
|
|
fe8afb18d0
|
||
|
|
3f092c0704
|
||
|
|
f156150a8b
|
||
|
|
9dd55646bb
|
||
|
|
6a7f8b4847 | ||
|
|
1c5915f521
|
||
|
|
864240fd61 | ||
|
|
1730938e03 | ||
|
|
2a73a37d27 | ||
|
|
4694406434 | ||
|
|
b8c394767c | ||
|
|
604d615d7a | ||
|
|
77db59141c
|
||
|
|
eabd7c8884
|
||
|
|
7ffbf0435c
|
||
|
|
8082e200f2
|
||
|
|
b234a85090
|
||
|
|
37ea698a28 | ||
|
|
bc429cd351 | ||
|
|
75044ee4c0 | ||
|
|
914a5f9b03 | ||
|
|
a7a411bd4b | ||
|
|
9ac8a60999 | ||
|
|
04975db9a1
|
||
|
|
b97eb45275
|
||
|
|
658a4cb50e
|
||
|
|
5a98c313e0
|
||
|
|
f92c5b4536
|
||
|
|
c54d328f0d
|
||
|
|
161e8f95bf
|
||
|
|
c155bb24ba
|
||
|
|
0033933a58
|
||
|
|
a9aacab79d
|
||
|
|
dcc12582ce
|
||
|
|
4728c8c253
|
||
|
|
255e0c7ee0
|
||
|
|
bc16b74c93
|
||
|
|
44237b448b
|
||
|
|
e5e968780f
|
||
|
|
31578e8857
|
||
|
|
f3f90f3224
|
||
|
|
8aa3540fa7
|
||
|
|
52549c1bab
|
||
|
|
f7c3e1788c
|
||
|
|
5ea115746c
|
||
|
|
12a25faf31 | ||
|
|
c9a8e21759 | ||
|
|
28a6ac8b98
|
||
|
|
73860b26d2 | ||
|
|
9ca3432f8e | ||
|
|
1b53c5787e | ||
|
|
b509397e8d | ||
|
|
721e6332ed
|
||
|
|
cc49fecc77
|
||
|
|
c3e64e5485 | ||
|
|
13ec693726
|
||
|
|
e3ffefdc7d
|
||
|
|
04798b990a
|
||
|
|
0e889977c0
|
||
|
|
47e3d8d837 | ||
|
|
9a9629400e | ||
|
|
0525edd3bb
|
||
|
|
82313e4af5
|
||
|
|
e34941b1eb
|
||
|
|
67c9b7a00a
|
||
|
|
20ffe63367
|
||
|
|
bcbd09fc08
|
||
|
|
a3fdbddfc0
|
||
|
|
70eef0ec99
|
||
|
|
96236b6186
|
||
|
|
e75d5c8ade
|
||
|
|
f44db54948
|
||
|
|
44b52c54c0
|
||
|
|
ec79c8123e
|
||
|
|
4b0adac674
|
||
|
|
dc2c3b983f
|
||
|
|
e3dc7fc2e9
|
||
|
|
2ae471398b
|
||
|
|
6437c8009c
|
||
|
|
f9b6077595
|
||
|
|
00f62a5772
|
||
|
|
3db75f9e28
|
||
|
|
f27e9853cc
|
||
|
|
561863613f
|
||
|
|
fce5fab2a1
|
||
|
|
3b840d7847
|
||
|
|
8e5d4e8061
|
||
|
|
c98666d6b7
|
||
|
|
055f2da9cd
|
||
|
|
fd14b8d358
|
||
|
|
2365e5ede9
|
||
|
|
c9248a251a
|
||
|
|
eb4b2fab5a
|
||
|
|
e0eb1dfdb7
|
||
|
|
031291a4bf
|
||
|
|
618b22db15
|
||
|
|
fc50b026cf
|
||
|
|
e9f5d136b4
|
||
|
|
403d5f8427
|
||
|
|
5539835dd6
|
||
|
|
b16dd6add4
|
||
|
|
a053d98d7c
|
||
|
|
f5a04ce8c5
|
||
|
|
9616dd72ce
|
||
|
|
6871abd7ee
|
||
|
|
32fcbf1a2b
|
||
|
|
632ceb0f85
|
||
|
|
5414405ceb
|
||
|
|
cdbdbbc72d | ||
|
|
2a04abb84e
|
||
|
|
98f5af3eef
|
||
|
|
d1b1bac4fb
|
||
|
|
45b368af2e
|
||
|
|
0f6448c048
|
||
|
|
b15858adc9
|
||
|
|
1ef576ca7b
|
||
|
|
50cb0b4276
|
||
|
|
472478cf83
|
||
|
|
90c7d137fb
|
||
|
|
2d51cf5106
|
||
|
|
1167f8a51e
|
||
|
|
17e6e66e72
|
||
|
|
fa76f4c994
|
||
|
|
21a523bd35
|
||
|
|
db377380a0
|
||
|
|
81fcea7a03
|
||
|
|
011d22c24c
|
||
|
|
83c8614418
|
||
|
|
ac98b68bda
|
||
|
|
ad63692781
|
||
|
|
090b220d25
|
||
|
|
514219b6a5
|
||
|
|
6a5ba67cf5
|
||
|
|
c09ece6064
|
||
|
|
43ba64684e
|
||
|
|
67fa57008e
|
||
|
|
074ebbd931
|
||
|
|
10d23e3e06
|
||
|
|
6a4e1964f6
|
||
|
|
5939ef6ff1
|
||
|
|
1d9eff6529
|
||
|
|
6ae7f319cb
|
||
|
|
260e9fc46e
|
||
|
|
52b5740c39
|
||
|
|
d11a0cd245
|
||
|
|
860b2c85e0
|
||
|
|
af7577625f
|
||
|
|
617a312ed5
|
||
|
|
a7d202fb04
|
||
|
|
2a52508a5d
|
||
|
|
98fb9dfddf
|
||
|
|
64bb195700
|
||
|
|
c8a46fd9e7
|
||
|
|
93db9a6395
|
||
|
|
89808d0719
|
||
|
|
ef99b7d74e
|
||
|
|
62ddbea0c1
|
||
|
|
b548cabcbf
|
||
|
|
8f37cc79cd
|
||
|
|
031521550a
|
||
|
|
3b67ef746f | ||
|
|
18838105f0
|
||
|
|
d70596f4bf | ||
|
|
a9878c329d | ||
|
|
558659bcf4 | ||
|
|
00e7603932 | ||
|
|
33f7323eb0 | ||
|
|
184038a918
|
||
|
|
8cb76092b6 | ||
|
|
49d7619ba3
|
||
|
|
ae53e83ff3 | ||
|
|
ef84e18f46
|
||
|
|
cf1be16763
|
||
|
|
cc8428643a
|
||
|
|
70251ff3ce | ||
|
|
76dc34a17c
|
||
|
|
a6a0c7c11e
|
||
|
|
f759387eb7
|
||
|
|
21b3591da1
|
||
|
|
e9937ded6b
|
||
|
|
bd1acdd0cc
|
||
|
|
a2c6341544
|
||
|
|
cb3372ac76
|
||
|
|
48e605a545
|
||
|
|
9a4e59f0e0
|
||
|
|
820beda72f
|
||
|
|
c6f70de82d
|
||
|
|
f37f6e2453
|
||
|
|
f7a999e317
|
||
|
|
45494d5b43
|
||
|
|
9ca9545847
|
||
|
|
fa14e7da80
|
||
|
|
12eea5eee3
|
||
|
|
ef623f6c68
|
||
|
|
ee2d19d011
|
||
|
|
53c6b3e413
|
||
|
|
d58125c0bc
|
||
|
|
029198ff61
|
||
|
|
0b08fc5242
|
||
|
|
93609c7ab3
|
||
|
|
461d3dc1f7
|
||
|
|
94f79177a2
|
||
|
|
9169e9db09
|
||
|
|
0d0cd09124
|
||
|
|
0dc5bf9a9b
|
||
|
|
ca107f6977
|
||
|
|
4dad1415e6
|
||
|
|
5bf0a696c6
|
||
|
|
7a8d948fcb
|
||
|
|
d90f7d48d0
|
||
|
|
c5a43f21aa
|
||
|
|
d3fbb0842f
|
||
|
|
dafd426316
|
||
|
|
bec374aa92
|
||
|
|
85b21578d8
|
||
|
|
03c25e7214
|
||
|
|
c30624a59e
|
||
|
|
3cf025fb4a
|
||
|
|
81b784876b
|
||
|
|
6c42f64bfa | ||
|
|
d74216c6b7
|
||
|
|
0b7ce448ab
|
||
|
|
2fb8c09a00
|
||
|
|
0442f1849f
|
||
|
|
cf049797b0
|
||
|
|
18e6fe6af6
|
||
|
|
e8a84d3e41
|
||
|
|
c5f4541cbf
|
||
|
|
369e5038ca
|
||
|
|
66862a1bab
|
||
|
|
25dcdb2d19
|
||
|
|
1830a89898
|
||
|
|
6e718e165a
|
||
|
|
0a37b551f5
|
||
|
|
864b87faa6
|
||
|
|
d55d8580cf
|
||
|
|
63229d1711
|
||
|
|
56044476fc | ||
|
|
796bfd0045
|
||
|
|
abcb72a76a
|
||
|
|
443a7a501b
|
||
|
|
88e86776e8
|
||
|
|
e10bb161fe
|
||
|
|
3b525b7482
|
||
|
|
c2cc10ebfa
|
||
|
|
2f8076d7f8
|
||
|
|
c180a2debb
|
||
|
|
5356745968
|
||
|
|
5b5059615b
|
||
|
|
bca1f3b412 | ||
|
|
3af96fd818
|
||
|
|
1043982529
|
||
|
|
6abfe32540 | ||
|
|
1f9807a99c
|
||
|
|
b2edf1fa8b
|
||
|
|
bb897e76b8 | ||
|
|
07062352b4 | ||
|
|
856c15858b
|
||
|
|
69a46249cc
|
||
|
|
6f10ecc04f
|
||
|
|
d6ca6a72a5
|
||
|
|
243832fee6
|
||
|
|
e8c2c844a8
|
||
|
|
6220387ed6
|
||
|
|
efd3eb2854
|
||
|
|
c78063eba0 | ||
|
|
0e931485a0
|
||
|
|
1bf536d4ab
|
||
|
|
2181b5fd08
|
||
|
|
a4a7c96da6
|
||
|
|
a7f6e517ad
|
||
|
|
812d9004a7
|
||
|
|
ebc6dd67e6
|
||
|
|
949457689c
|
||
|
|
0cb035555f
|
||
|
|
a5974d0ea0
|
||
|
|
1ea15462c0
|
||
|
|
9d8f364af1
|
||
|
|
c87b0c31e1 | ||
|
|
c5802cf86d | ||
|
|
4f2338810b | ||
|
|
f8da67348c | ||
|
|
003771ca48 | ||
|
|
f7926cde15 | ||
|
|
3a05b3ecd0 | ||
|
|
6031a7a14b | ||
|
|
ad9ec16844 | ||
|
|
3977eaad68 | ||
|
|
3b6de96782 | ||
|
|
decc86fd08 | ||
|
|
5485dc4690 | ||
|
|
57865b51f4 | ||
|
|
0a1aa8b3c2 | ||
|
|
7c8114bc55 | ||
|
|
aa57377c7f | ||
|
|
8aa65bc7b4 | ||
|
|
a781fde566 | ||
|
|
3b372b4a91 | ||
|
|
066522cf5d | ||
|
|
ec9bf5feb2 | ||
|
|
dfb37fb4f2 | ||
|
|
86c2909a57 | ||
|
|
b5482857f8 | ||
|
|
0c137d9319 | ||
|
|
59827b19bd | ||
|
|
34179f0f9f | ||
|
|
9c193aeebb | ||
|
|
1cd8955d23 | ||
|
|
004e38b8eb | ||
|
|
c5991a560e | ||
|
|
04ce0f9056 | ||
|
|
e5cb0ac00b | ||
|
|
abe4c488cf | ||
|
|
973541f344 | ||
|
|
3c4b7b5877 | ||
|
|
8fbfb3c99f | ||
|
|
3b33d164c7 | ||
|
|
292597660f | ||
|
|
ba3a26af3c | ||
|
|
4bb473c0b0 | ||
|
|
c3d49cbc6c | ||
|
|
e831edb005 | ||
|
|
3db2654188 | ||
|
|
afdb4b203f | ||
|
|
6f57d38669 | ||
|
|
d60995af43 | ||
|
|
472d9d8b10 | ||
|
|
11b89354a6 | ||
|
|
8150df8d81 | ||
|
|
b8e080301c | ||
|
|
2d87e9f587 | ||
|
|
749baa3e5d | ||
|
|
90deba8472 | ||
|
|
9498fad064 | ||
|
|
6ca5c7f851 | ||
|
|
dfce3360b2 | ||
|
|
58629ea03a | ||
|
|
5b3b88ed3d | ||
|
|
62dbac9247 | ||
|
|
a8aad28239 | ||
|
|
9d633855f4 | ||
|
|
56ac50931e | ||
|
|
3e437d4275 | ||
|
|
c9951c085c | ||
|
|
59c6f0e4c0 | ||
|
|
9460f51e07 | ||
|
|
3ac5b97706 | ||
|
|
1add0fca32 | ||
|
|
0d8c48cbf4 | ||
|
|
e41b7606d6 | ||
|
|
ad2ceaaec2 | ||
|
|
c3b636bf72 | ||
|
|
98acd6aad0 | ||
|
|
8f7743c73d | ||
|
|
60a19ab15e | ||
|
|
dc1e45ff82 | ||
|
|
5fefd1902f | ||
|
|
45ed5b2faf | ||
|
|
f0fac7899f | ||
|
|
c7e12b56d0 | ||
|
|
087aa45349 | ||
|
|
4cc22ac5e0 | ||
|
|
7f0ecaa192 | ||
|
|
a203cbc03b | ||
|
|
17c07a31fe | ||
|
|
87100c4aba | ||
|
|
5498c97e3d | ||
|
|
3ff6867e84 | ||
|
|
7c050eef14 | ||
|
|
d98abad8bb | ||
|
|
9e92beb4cc | ||
|
|
ca597c3678 | ||
|
|
63476393d7 | ||
|
|
9d930436c5 | ||
|
|
be0f6f5ab7 | ||
|
|
66daa071a5 | ||
|
|
ca44b9e6bb | ||
|
|
da7efa3f4e | ||
|
|
4de8882ef5 | ||
|
|
c00a90c9ca | ||
|
|
c4c50ea70d | ||
|
|
c578c8e954 | ||
|
|
e85719f2d2 | ||
|
|
4dca007003 | ||
|
|
d7d1bd4556 | ||
|
|
dc26daeebe | ||
|
|
f727d54d75 | ||
|
|
6f8371a7bf | ||
|
|
fff689312d | ||
|
|
b701f60a99 | ||
|
|
6ba6a595b8 | ||
|
|
6cd9c4a7d8 | ||
|
|
816ce2e1f8 | ||
|
|
19570ad4bb | ||
|
|
5212a4d913 | ||
|
|
46f0643cf5 | ||
|
|
656feab2a4 | ||
|
|
0611e00330 | ||
|
|
128d5e0a82 | ||
|
|
c6187b7c23 | ||
|
|
afd6669877 | ||
|
|
7bf007bb58 | ||
|
|
92a74e4b7d | ||
|
|
0880e6a01c | ||
|
|
4a889991bd | ||
|
|
89bb4eb46b | ||
|
|
f3c7555195 | ||
|
|
79f3895923 | ||
|
|
837cd91501 | ||
|
|
5112ce896b | ||
|
|
7715d6b23b | ||
|
|
373032e330 | ||
|
|
6a69fb760a | ||
|
|
4cc7573b27 | ||
|
|
1d7fd6aab3 | ||
|
|
c04a18d387 | ||
|
|
abf485b9ef | ||
|
|
0245c4e455 | ||
|
|
fa00f74af5 | ||
|
|
2f9ed7adca | ||
|
|
4f2e1c3687 | ||
|
|
2d2ca156d8 | ||
|
|
f8c3dbedf2 | ||
|
|
17354de8fe | ||
|
|
7066a6fd46 | ||
|
|
20595a70b4 | ||
|
|
568f7adf52 | ||
|
|
74e34fb07a | ||
|
|
e6d765d233 | ||
|
|
4250a31ff9 | ||
|
|
ad19271c6c | ||
|
|
b774b68ed4 | ||
|
|
8eaf7b00c3 | ||
|
|
59eecd956d | ||
|
|
e2f9388071 | ||
|
|
6c095e5ac6 | ||
|
|
274acfe6f5 | ||
|
|
f1eda629a8 | ||
|
|
5602534ba9 | ||
|
|
bc9b9952cd | ||
|
|
7f5a73d97d | ||
|
|
02a4ac0629 | ||
|
|
ab78f5c909 | ||
|
|
c9c552a1bd | ||
|
|
c24b055cf3 | ||
|
|
72052fe186 | ||
|
|
0f14378363 | ||
|
|
551220eccc | ||
|
|
287f8d71dd | ||
|
|
390e89aefb | ||
|
|
18e21661b2 | ||
|
|
8af19c79f4 | ||
|
|
b7cda2b2fe | ||
|
|
c86b8659e5 | ||
|
|
de3b41b70d | ||
|
|
5aa0aead4d | ||
|
|
0dae907dad | ||
|
|
59e3de62db | ||
|
|
6c2ab54f65 | ||
|
|
be47311883 | ||
|
|
1e9659c7a2 | ||
|
|
ca73d02804 | ||
|
|
5f827b6e19 | ||
|
|
7d9c40d79d | ||
|
|
33da08bce5 | ||
|
|
f2b8681611 | ||
|
|
fc609171ca | ||
|
|
2399da1f8d | ||
|
|
d699b9afba | ||
|
|
7a03e003a1 | ||
|
|
340223de2e | ||
|
|
54697c6e17 | ||
|
|
18eed1fb96 | ||
|
|
55c201e7c1 | ||
|
|
54a78175b4 | ||
|
|
cae19ca42e | ||
|
|
d4558c15d3 | ||
|
|
75c1dbf83c | ||
|
|
536155752c | ||
|
|
958561d255 | ||
|
|
7cd62232ef | ||
|
|
32b73c3a28 | ||
|
|
b0137d6181 | ||
|
|
a776de8b8f | ||
|
|
b577b02eb6 | ||
|
|
b006b1c943 | ||
|
|
4241dbf817 | ||
|
|
0ccd1793e3 | ||
|
|
29aad11bed | ||
|
|
6e33004ef2 | ||
|
|
afca2c164f | ||
|
|
c7e2160582 | ||
|
|
849e24757d | ||
|
|
e143362479 | ||
|
|
4146600579 | ||
|
|
a04afe8d4e | ||
|
|
550bb60691 | ||
|
|
df54db239d | ||
|
|
de532ca299 | ||
|
|
d7fc4e1fe9 | ||
|
|
e8a60c4abd | ||
|
|
1f8a9964c1 | ||
|
|
aabe8f7a80 | ||
|
|
fe9bdefc62 | ||
|
|
205d0ec976 | ||
|
|
e9ecc84064 | ||
|
|
3b7193c207 | ||
|
|
84cb0eb3fd | ||
|
|
d9fda2338f | ||
|
|
64acc0e97a | ||
|
|
8d2307d12d | ||
|
|
8c128592bd | ||
|
|
39430d78ae | ||
|
|
9c9aefd296 | ||
|
|
e63489829e | ||
|
|
87bc53c278 | ||
|
|
5bdf68594d | ||
|
|
f6988916d8 | ||
|
|
aaccbcf984 | ||
|
|
f9e3c4eaa4 | ||
|
|
97195bf2ac | ||
|
|
c787db7e07 | ||
|
|
12b5022a4f | ||
|
|
8c98f20f0e | ||
|
|
9e334c3627 | ||
|
|
66f06a1878 | ||
|
|
6d7f341de5 | ||
|
|
7973feceb0 | ||
|
|
8ccac46fc9 | ||
|
|
b70e791fed | ||
|
|
1a57aa7216 | ||
|
|
102355aba5 | ||
|
|
9a08048744 | ||
|
|
793569f6e1 | ||
|
|
ffafc3a989 | ||
|
|
951acb8088 | ||
|
|
afc0c0319b | ||
|
|
522dfa5703 | ||
|
|
332e444397 | ||
|
|
959e1e0520 | ||
|
|
d8572e17e6 | ||
|
|
b2f720cc2b | ||
|
|
c7fc55a0ef | ||
|
|
e84dd0f7e2 | ||
|
|
1624353b2b | ||
|
|
5e7b51710c | ||
|
|
97466ad27d | ||
|
|
90c5f5075a | ||
|
|
4e97975862 | ||
|
|
64e398112f | ||
|
|
2a5b50346c | ||
|
|
6ff09f92a5 | ||
|
|
07c8bf310d | ||
|
|
dc6c4826bc | ||
|
|
d915a24f4d | ||
|
|
267528efba | ||
|
|
ad827e34bb | ||
|
|
69b8c482c1 | ||
|
|
aac77950f2 | ||
|
|
614ab1e6fa | ||
|
|
2e6c493487 | ||
|
|
2ca7c9b2b9 | ||
|
|
b395eec893 | ||
|
|
5675284b08 | ||
|
|
cbe998b598 | ||
|
|
fc0dd41092 | ||
|
|
2f8d375692 | ||
|
|
8ed814cbf7 | ||
|
|
852dd4f6c7 | ||
|
|
88514a444b | ||
|
|
e33adbb12f | ||
|
|
ae178f1be0 | ||
|
|
d1b7a21b9b | ||
|
|
bf4fde5f7d | ||
|
|
6194a51ed0 | ||
|
|
4847fb0b77 | ||
|
|
fd241a59cc | ||
|
|
0f0f048380 | ||
|
|
974c93498a | ||
|
|
92bc0f692f | ||
|
|
7b2af3348d | ||
|
|
89cbbfc871 | ||
|
|
e955c45ba8 | ||
|
|
1ed8d4f543 | ||
|
|
19e5dcd9d0 | ||
|
|
caafdb266f | ||
|
|
412d73e7e1 | ||
|
|
76c0e4dd1b | ||
|
|
b8b223c87c | ||
|
|
9d3ea208ef | ||
|
|
5a55196572 | ||
|
|
35e9d5d64e | ||
|
|
b47f768076 | ||
|
|
6630b0c9bf | ||
|
|
1b2a8eec7c | ||
|
|
31da6dc7c2 | ||
|
|
d873cb5476 | ||
|
|
5179bc81b7 | ||
|
|
26e3d2bff2 | ||
|
|
61ee5fd3a7 | ||
|
|
0eecc95aac | ||
|
|
3bb8f73c6a | ||
|
|
890361468d | ||
|
|
889856aa81 | ||
|
|
63adbc71ef | ||
|
|
d876c150eb | ||
|
|
3202386eaa | ||
|
|
eade816ee0 | ||
|
|
f9861d3ea5 | ||
|
|
580108dd7f | ||
|
|
30105666e2 | ||
|
|
8d0d707d3e | ||
|
|
c94a943854 | ||
|
|
12685e264d | ||
|
|
1e56219bbe | ||
|
|
ab43c4e337 | ||
|
|
02d4e162b8 | ||
|
|
cc4f20ce30 | ||
|
|
10e1207242 | ||
|
|
24c3f7e857 | ||
|
|
a76c54d1ac | ||
|
|
9fea68815e | ||
|
|
9ff62f2cc4 | ||
|
|
3f0fd7409d | ||
|
|
bb8f716abd | ||
|
|
4201512912 | ||
|
|
409b5e6e54 | ||
|
|
490532643e | ||
|
|
b6f4481038 | ||
|
|
227a991388 | ||
|
|
18bb7b7dcb | ||
|
|
d40ba948e9 | ||
|
|
7f5fbe4135 | ||
|
|
86d4066084 | ||
|
|
912f5e99ff | ||
|
|
1d4278c5d2 | ||
|
|
3871b820d9 | ||
|
|
18d36b00bc | ||
|
|
5e62f8311f | ||
|
|
8e0614436b | ||
|
|
68b8e5d00a | ||
|
|
a202c280d8 | ||
|
|
ff5cab992b | ||
|
|
46f3c881ec | ||
|
|
a54fec0b43 | ||
|
|
f2a1aedbc2 | ||
|
|
fbe0742ef6 | ||
|
|
a0524c0cf3 | ||
|
|
bc7f4390b1 | ||
|
|
e5520ae4e5 | ||
|
|
06014f4a39 | ||
|
|
addd9b8f14 | ||
|
|
0d78e26e8d | ||
|
|
bc291255e8 | ||
|
|
5aba9b8707 | ||
|
|
6c555adb79 | ||
|
|
3eca2ef5df | ||
|
|
491c1fa683 | ||
|
|
4fe217ef0e | ||
|
|
872958127a | ||
|
|
32735a2ab1 | ||
|
|
f300b96251 | ||
|
|
b1d38bb7b7 | ||
|
|
0af9ac496e | ||
|
|
fd30a24079 | ||
|
|
0749f45054 | ||
|
|
168ddde0dd | ||
|
|
0d6d5e7dd3 | ||
|
|
27c70d8e24 | ||
|
|
0275e9e75f | ||
|
|
c618b30013 | ||
|
|
cbb2e823da | ||
|
|
113da1cd4b | ||
|
|
a9ae4ab3f1 | ||
|
|
3be983c650 | ||
|
|
7b680f8ac6 | ||
|
|
b6057a0a11 | ||
|
|
3bebdb2af7 | ||
|
|
dd80fcb337 | ||
|
|
2b523fe7e0 | ||
|
|
39e33e75a3 | ||
|
|
991b40047a | ||
|
|
39e44e9da9 | ||
|
|
499898a4fc | ||
|
|
de7571f91e | ||
|
|
fd8d2c1941 | ||
|
|
e953fc8891 | ||
|
|
b9d28418e8 | ||
|
|
3f46d2ec33 | ||
|
|
81f1be388e | ||
|
|
4b921227c5 | ||
|
|
c0bd7bb6a3 | ||
|
|
0cec2ec16d | ||
|
|
7120cf52a2 | ||
|
|
cc9151425f | ||
|
|
c744928e07 | ||
|
|
6529613496 | ||
|
|
010c8b28dd | ||
|
|
198702010f | ||
|
|
ffffaa9fe6 | ||
|
|
90b7d28627 | ||
|
|
d8b4e04861 | ||
|
|
8c1756d312 | ||
|
|
5989f0b45f | ||
|
|
846626fabf | ||
|
|
7768fa808d | ||
|
|
39c3c47ea2 | ||
|
|
f5770fdc6e | ||
|
|
b4595bf8bb | ||
|
|
8e3711b73c | ||
|
|
55deeaa88c | ||
|
|
f10199f0b6 | ||
|
|
eb6aaca1f5 | ||
|
|
9167c861d6 | ||
|
|
2d1bbb6e6a | ||
|
|
d82e316f9b | ||
|
|
33f5290015 | ||
|
|
aa1e2ca660 | ||
|
|
86600c3884 | ||
|
|
c6c7a44c5b | ||
|
|
0652ded616 | ||
|
|
2d3b6d0d87 | ||
|
|
b25263308b | ||
|
|
1410fbc565 | ||
|
|
c72c443090 | ||
|
|
6f29790b76 | ||
|
|
d936609188 | ||
|
|
8aa59bdb51 | ||
|
|
f0eee80ab7 | ||
|
|
7f9486fff1 | ||
|
|
e9f45eeb8b | ||
|
|
127e5e70a0 | ||
|
|
334787c140 | ||
|
|
2cdf3b2c85 | ||
|
|
bf14695eab | ||
|
|
a4da914994 | ||
|
|
fefbe19011 | ||
|
|
a2ade2ee42 | ||
|
|
2e7158a760 | ||
|
|
1cd0ed22f5 | ||
|
|
db982f2d93 | ||
|
|
44a10943c3 | ||
|
|
055e0250bd | ||
|
|
48dc39a3d5 | ||
|
|
f45ea9e0aa | ||
|
|
ab16bc673d | ||
|
|
7b504f9ed6 | ||
|
|
9d7287c647 | ||
|
|
c80d4750a8 | ||
|
|
e579b908f3 | ||
|
|
01acb97f96 | ||
|
|
7986ccb3f7 | ||
|
|
e452451926 | ||
|
|
9b7e7fc221 | ||
|
|
42ba637935 | ||
|
|
6aced84146 | ||
|
|
05987f04e2 | ||
|
|
32642af4a9 | ||
|
|
62ee8a0381 | ||
|
|
30216dd367 | ||
|
|
cbc4cf309d | ||
|
|
4217a50874 | ||
|
|
a8a27eb4a4 | ||
|
|
8410271fdb | ||
|
|
fe97e92dd2 | ||
|
|
9ab0121af0 | ||
|
|
6132c12835 | ||
|
|
cb48a27d16 | ||
|
|
3953a3a06c | ||
|
|
139338cf34 | ||
|
|
41cd938748 | ||
|
|
3229de9b3b | ||
|
|
dcc201e7bb | ||
|
|
1b8abd3509 | ||
|
|
7ebf842c5c | ||
|
|
74699fcd21 | ||
|
|
f8b061c314 | ||
|
|
c5158edb6c | ||
|
|
9ad270b9a4 | ||
|
|
51328c9585 | ||
|
|
aa1ca9e653 | ||
|
|
cb29967e7b | ||
|
|
474fd59759 | ||
|
|
40ee9ffafa | ||
|
|
939b912889 | ||
|
|
83aa17cf8b | ||
|
|
9cdae5642e | ||
|
|
dcf2972f26 | ||
|
|
f96c44d092 | ||
|
|
f537d5f8cd | ||
|
|
c833b651a9 | ||
|
|
062f5332a0 | ||
|
|
d9fe384fd9 | ||
|
|
8a7220f5e9 | ||
|
|
5b9ff6fa47 | ||
|
|
66b22f4833 | ||
|
|
acec5d392d | ||
|
|
59be81c7f6 | ||
|
|
c0ac39b8da | ||
|
|
7b19935a14 | ||
|
|
fa7d0d83c1 | ||
|
|
7542e3b15e | ||
|
|
6412e6d116 | ||
|
|
b1dbe519b0 | ||
|
|
3103f87b71 | ||
|
|
8664e8cd97 | ||
|
|
9e566e7278 | ||
|
|
f02a3b6d02 | ||
|
|
bf6f3512b1 | ||
|
|
00112ae205 | ||
|
|
8001c893bd | ||
|
|
0e25291d47 | ||
|
|
68fb3a7e19 | ||
|
|
541575a073 | ||
|
|
d4d24cb1db | ||
|
|
20cb2fd99d | ||
|
|
4fd6efb7f0 | ||
|
|
9eabc624ee | ||
|
|
01418b7e81 | ||
|
|
cac763a339 | ||
|
|
0dde93e57e | ||
|
|
7435b6efe5 | ||
|
|
796c7a711b | ||
|
|
4ac9fd852f | ||
|
|
06d6293a9d | ||
|
|
0c904fb9ef | ||
|
|
59645969ee | ||
|
|
acacdfdab5 | ||
|
|
2090c41960 | ||
|
|
e5a67b8ff0 | ||
|
|
8e6dfd785f | ||
|
|
b9547b01a8 | ||
|
|
0720e9629c | ||
|
|
bb67bd77f1 | ||
|
|
8ecda341e0 | ||
|
|
dee78a876a | ||
|
|
33ccfb2505 | ||
|
|
0330a65054 | ||
|
|
4eb9c20c0c | ||
|
|
1f4910a651 | ||
|
|
150bfd4605 | ||
|
|
3bf64933b0 | ||
|
|
94d2f98cc0 | ||
|
|
2df2f72fc2 | ||
|
|
8a3ba32c5a | ||
|
|
f34f60f9c7 | ||
|
|
8540c9f7c8 | ||
|
|
3014db85e7 | ||
|
|
aea7c5c9f1 | ||
|
|
c792c552cf | ||
|
|
a71f1e0817 | ||
|
|
76905c8ec6 | ||
|
|
85d8b771f0 | ||
|
|
d31a950daa | ||
|
|
f765e23812 | ||
|
|
d66dca44e0 | ||
|
|
b8f8f9a272 | ||
|
|
e128f82e11 | ||
|
|
daab5732e8 | ||
|
|
eb5703b7dd | ||
|
|
ce5fc3e226 | ||
|
|
c2a649ded4 | ||
|
|
1b0a89ca2e | ||
|
|
1441585e06 | ||
|
|
f3576342b6 | ||
|
|
ede2102c60 | ||
|
|
16d98dd47c | ||
|
|
7aca31b18f | ||
|
|
e97f1fa609 | ||
|
|
62f0baba36 | ||
|
|
40fa6f9d7d | ||
|
|
6ce605d6ea | ||
|
|
feba855326 | ||
|
|
47f75f71a7 | ||
|
|
4e060ce5ef | ||
|
|
e2e24f9d56 | ||
|
|
5aa5c2a6c8 | ||
|
|
41b2daed0c | ||
|
|
e0a79b3990 | ||
|
|
e2d6b75b10 | ||
|
|
b4be999777 | ||
|
|
5c3bf0b642 | ||
|
|
be2b897149 | ||
|
|
f5a39cfb9b | ||
|
|
f5a6fa5b32 | ||
|
|
93ec6d916b | ||
|
|
c36fb29683 | ||
|
|
cac0f43b58 | ||
|
|
805364f201 | ||
|
|
3b2a3a7630 | ||
|
|
bf29d3640e | ||
|
|
de15bffc2f | ||
|
|
1377e7ebf2 | ||
|
|
d53ebbda95 | ||
|
|
b227df3c3f | ||
|
|
a3e0e5c1bb | ||
|
|
116f8a10fb | ||
|
|
116b03534f | ||
|
|
b697a12b89 | ||
|
|
7b64699ff1 | ||
|
|
1598b3cc74 | ||
|
|
212742e880 | ||
|
|
6693e60f6f | ||
|
|
c097e50405 | ||
|
|
ccbc9c7844 | ||
|
|
948a8d34fd | ||
|
|
e078b5c4bc | ||
|
|
4a24c0b31f | ||
|
|
e988d3cc40 | ||
|
|
cd20aeadad | ||
|
|
1bb7ba1248 | ||
|
|
fdafec3d9d | ||
|
|
0fcf792db3 | ||
|
|
9cd52dd9aa | ||
|
|
5290dab199 | ||
|
|
e17c7895e4 | ||
|
|
e4ea2eaabc | ||
|
|
12b9a57404 | ||
|
|
514c6cf61c | ||
|
|
bef0ecea3a | ||
|
|
5bb5d9b660 | ||
|
|
f30405ea2b | ||
|
|
f9efae8a5e | ||
|
|
819cfc655b | ||
|
|
5afe5bcf99 | ||
|
|
0c25b2f4a6 | ||
|
|
252895e01c | ||
|
|
3ea49c7e07 | ||
|
|
66a27bd7ef | ||
|
|
b070ce4715 | ||
|
|
84b581fde6 | ||
|
|
af5e11a734 | ||
|
|
522ced45ff | ||
|
|
79d7f2fa68 | ||
|
|
eb3ee14a0e | ||
|
|
6ed6b28d02 | ||
|
|
2f4e9bbe14 | ||
|
|
3057f054b2 | ||
|
|
a4e7ea8cc3 | ||
|
|
c812192800 | ||
|
|
81121d03b0 | ||
|
|
e5f03587c9 | ||
|
|
c25e70a588 | ||
|
|
b97c79aa0b | ||
|
|
2d2c39f9e5 | ||
|
|
673a5bc2ce | ||
|
|
df5ee243b1 | ||
|
|
71fa670512 | ||
|
|
d91ab1ab0f | ||
|
|
1eb05f0d24 | ||
|
|
a49e939609 | ||
|
|
e76e2fd317 | ||
|
|
2418a81a9e | ||
|
|
c4a441d1c3 | ||
|
|
c5c145f325 | ||
|
|
3683ce9082 | ||
|
|
80dc6ec8d0 | ||
|
|
12d6585586 | ||
|
|
53916b0f96 | ||
|
|
badbbf84bd | ||
|
|
d98352d003 | ||
|
|
542bd88040 | ||
|
|
81384939a2 | ||
|
|
c8ed5619c6 | ||
|
|
3b79155602 | ||
|
|
552ee93a47 | ||
|
|
7bf429b599 | ||
|
|
0792f0ba84 | ||
|
|
02ab747ca9 | ||
|
|
c53a98ee87 | ||
|
|
1e4aa8badc | ||
|
|
1e76c99b48 | ||
|
|
ff9b6c7196 | ||
|
|
7680dc5079 | ||
|
|
d0370ed9f7 | ||
|
|
7e3b3dbd78 | ||
|
|
6b71dc8108 | ||
|
|
307f2fc9e2 | ||
|
|
455de3d799 | ||
|
|
4e74ed37b4 | ||
|
|
7ef58293be | ||
|
|
27c9647a13 | ||
|
|
89541eb3b0 | ||
|
|
3a3a714cc4 | ||
|
|
b107e4452a | ||
|
|
2b514cb526 | ||
|
|
630c30de79 | ||
|
|
a69b3455d3 | ||
|
|
ddf8383784 | ||
|
|
c1bbeba18f | ||
|
|
1f99fb592e | ||
|
|
aae01431b4 | ||
|
|
3c99f69fee | ||
|
|
b7fd13923a | ||
|
|
0a47a95cc3 | ||
|
|
ef8d9af469 | ||
|
|
549f36a1f2 | ||
|
|
187e6e81ee | ||
|
|
e60ad551f0 | ||
|
|
a0617ad437 | ||
|
|
411736fdaa | ||
|
|
bea6567933 | ||
|
|
d6b693a9b2 | ||
|
|
b8bedf4d7b | ||
|
|
5c53dfb91b | ||
|
|
e0cbbc0895 | ||
|
|
40dd546564 | ||
|
|
b89d8cbab2 | ||
|
|
4b62912343 | ||
|
|
8a8c8cf7e9 | ||
|
|
201529414b | ||
|
|
3da1f918a4 | ||
|
|
f8d8e5b1e2 | ||
|
|
826d4849df | ||
|
|
0a18bfe21b | ||
|
|
5976b94fbc | ||
|
|
698548d6ef | ||
|
|
d0584279e5 | ||
|
|
62f248fd2c | ||
|
|
8f2750a266 | ||
|
|
2ea7f7cd38 | ||
|
|
75b3810856 | ||
|
|
30419532ba | ||
|
|
fff67838e0 | ||
|
|
15ebe24927 | ||
|
|
b2c1629925 | ||
|
|
0e8fcf70a0 | ||
|
|
4673b435b7 | ||
|
|
1e062fd7f0 | ||
|
|
74a3ec925c | ||
|
|
4944ec8473 | ||
|
|
204b65a0e3 | ||
|
|
cbedb8a504 | ||
|
|
a8dbab0cff | ||
|
|
789ff73fe9 | ||
|
|
5176938e95 | ||
|
|
69a1ee677d | ||
|
|
b3cf2c59a8 | ||
|
|
8ebaeb6d38 | ||
|
|
ce58768e6b | ||
|
|
d49918ae76 | ||
|
|
8cb5391035 | ||
|
|
ab9db7cfe3 | ||
|
|
3d02d1d2d9 | ||
|
|
e503263317 | ||
|
|
a012f1ad37 | ||
|
|
17b6fa7245 | ||
|
|
1d02c7e3e6 | ||
|
|
7892c927ce | ||
|
|
209f2b4adb | ||
|
|
28bb4b4483 | ||
|
|
8d73280633 | ||
|
|
c654ba7cd1 | ||
|
|
0fc8535d87 | ||
|
|
a355f13a03 | ||
|
|
cf34d03476 | ||
|
|
f9896f509d | ||
|
|
9f3ad773cd | ||
|
|
c0586e465c | ||
|
|
4fd53d3f44 | ||
|
|
a9991f6d91 | ||
|
|
e20860fcab | ||
|
|
378797ef6e | ||
|
|
f555b9171b | ||
|
|
9c20a8f2e0 | ||
|
|
84050080a7 | ||
|
|
7a6603078a | ||
|
|
07adab1eda | ||
|
|
7f2fd08840 | ||
|
|
2d55f9ead2 | ||
|
|
9431201d32 | ||
|
|
3a90225da1 | ||
|
|
68d0fe9055 | ||
|
|
0f0795e6f1 | ||
|
|
1628cbc312 | ||
|
|
b26de90e38 | ||
|
|
087ce10b86 | ||
|
|
799632339f | ||
|
|
bf73f96de5 | ||
|
|
bfebdec1bf | ||
|
|
e084c55fcc | ||
|
|
2998a2ed13 | ||
|
|
34077cb4ca | ||
|
|
4295bf6e46 | ||
|
|
955e366b9c | ||
|
|
d4d3a1ea7e | ||
|
|
2f8a91010f | ||
|
|
9f3e8285b5 | ||
|
|
add33fb3d9 | ||
|
|
0df1c41362 | ||
|
|
35a23d5ca1 | ||
|
|
0acf7981d9 | ||
|
|
abf3ae0ff9 | ||
|
|
65fbb3e1aa | ||
|
|
24c5fc86db | ||
|
|
794b818f4c | ||
|
|
57660a19b5 | ||
|
|
de6497dd14 | ||
|
|
dd8729bcf7 | ||
|
|
8c81661e01 | ||
|
|
261a50bc40 | ||
|
|
cf8868b744 | ||
|
|
dff26fe98b | ||
|
|
83cc810e94 | ||
|
|
1a26bf06b5 | ||
|
|
24df173a31 | ||
|
|
b38b3f6961 | ||
|
|
47558078ce | ||
|
|
2f6c53090e | ||
|
|
01f9b5986b | ||
|
|
d5e07333fa | ||
|
|
515c2edf2f | ||
|
|
77723baf75 | ||
|
|
b9787cebbe | ||
|
|
9e4ec516c9 | ||
|
|
add2546e54 | ||
|
|
3f494b4247 | ||
|
|
c73ff313ea | ||
|
|
886a151341 | ||
|
|
8ba067ce32 | ||
|
|
e0db40963e | ||
|
|
70322bd5fb | ||
|
|
fe30a02072 | ||
|
|
6a8481f203 | ||
|
|
22a4dcf46a | ||
|
|
6ee7321e6b | ||
|
|
1510c41254 | ||
|
|
895a04047d | ||
|
|
c9099e6f04 | ||
|
|
c76b973ea8 | ||
|
|
a8d0c82da7 | ||
|
|
d12e46dc38 | ||
|
|
e46eeb67dd | ||
|
|
3072ba595f | ||
|
|
720cd7a6f0 | ||
|
|
dfff9f6b11 | ||
|
|
ae99b47581 | ||
|
|
eeccb2e995 | ||
|
|
4efb835eed | ||
|
|
880a898ecb | ||
|
|
fba2d4ee09 | ||
|
|
666a034202 | ||
|
|
a5279bb187 | ||
|
|
c885eb5bec | ||
|
|
e45d69ef58 | ||
|
|
a2a6ab3dfb | ||
|
|
a5d747df72 | ||
|
|
2aea980a01 | ||
|
|
0e45001b2e | ||
|
|
e192308c90 | ||
|
|
06b8aeebeb | ||
|
|
cc5e0076af | ||
|
|
40d1062e08 | ||
|
|
56f2bf8a5d | ||
|
|
90399f5025 | ||
|
|
b5edf2986e | ||
|
|
1f01293f8c | ||
|
|
7efc96bf70 | ||
|
|
5b3441c553 | ||
|
|
5a3a693582 | ||
|
|
55bb4223c2 | ||
|
|
0e580dd979 | ||
|
|
9ccfc020f7 | ||
|
|
755f367ca0 | ||
|
|
153dfc094c | ||
|
|
37c6a71343 | ||
|
|
9d7b8d9814 | ||
|
|
b693065d09 | ||
|
|
3433bc7068 | ||
|
|
be541d6aee | ||
|
|
3a8879e6e9 | ||
|
|
b47e3a0b70 | ||
|
|
9a8c5722fa | ||
|
|
3b07bcb19f | ||
|
|
d82651222a | ||
|
|
647b9bcce7 | ||
|
|
2ae46582a8 | ||
|
|
38219a7035 | ||
|
|
510172480b | ||
|
|
785053c470 | ||
|
|
f27aafbd66 | ||
|
|
5b42e4cba9 | ||
|
|
1e435e9224 | ||
|
|
a4317f2660 | ||
|
|
7c011e8bf7 | ||
|
|
07d4fcb627 | ||
|
|
81f430de58 | ||
|
|
bf33ec9535 | ||
|
|
c486fe291c | ||
|
|
7d795fdd4f | ||
|
|
794c7ac8c6 | ||
|
|
d8d6d7318b | ||
|
|
e0701b18a3 | ||
|
|
9dd39c9d24 | ||
|
|
bf1a4ec6d7 | ||
|
|
0754c5e0da | ||
|
|
1936d9c353 | ||
|
|
44695b1846 | ||
|
|
35e72d81ff | ||
|
|
7e98ca254c | ||
|
|
6078dc1565 | ||
|
|
75988204d5 | ||
|
|
1a3fbe042e | ||
|
|
cb6b8618c2 | ||
|
|
0cbb65c684 | ||
|
|
e10980dc33 | ||
|
|
3360cddb5a | ||
|
|
c30844180b | ||
|
|
4ebde6b315 | ||
|
|
58150a920d | ||
|
|
5719cd51cb | ||
|
|
d0fd78e6a9 | ||
|
|
c167358118 | ||
|
|
7cf0db7e9a | ||
|
|
4d00884ea5 | ||
|
|
239cde9c2b | ||
|
|
030b4ed176 | ||
|
|
a8a118c1b8 | ||
|
|
780bc44d82 | ||
|
|
f0fe550a35 | ||
|
|
152c8b85a2 | ||
|
|
0d3ec4f127 | ||
|
|
703692ca7a | ||
|
|
8f8e732b3a | ||
|
|
61ecc14327 | ||
|
|
66167571cb | ||
|
|
aacec67c24 | ||
|
|
0adc165c4c | ||
|
|
483f50d030 | ||
|
|
27d9d7b397 | ||
|
|
eb624e53c6 | ||
|
|
9d7a7df496 | ||
|
|
c4b2bf5db7 |
No files matched your search
@@ -1,247 +0,0 @@
|
||||
---
|
||||
name: archie-agent-fleet
|
||||
description: >-
|
||||
Run a bounded fleet of coding agents across archie-core's backlog without
|
||||
flooding review. Load when fanning work out into parallel lanes, waves,
|
||||
worktrees or subagents on this repository; when a lane worktree dies with the
|
||||
unknown-agent error for `cp-writer`; or when deciding what every lane call must
|
||||
carry, which gate evidence to demand, and how a lane's scoped test command
|
||||
should be shaped here. Carries archie-specific fleet facts only; the method
|
||||
lives in the user-scope high-throughput-programming skill.
|
||||
---
|
||||
|
||||
# Run an agent fleet on archie-core
|
||||
|
||||
This skill carries the facts about _this repository_. It deliberately does not
|
||||
restate the process.
|
||||
|
||||
## Where the method lives
|
||||
|
||||
The how is the user-scope skill `high-throughput-programming` at
|
||||
`~/.agents/skills/high-throughput-programming/`: doctrine, pipeline shape, the
|
||||
interview that scaffolds a run, the pi-subagents ceilings and traps, `scripts/`,
|
||||
`templates/` and `references/`. Read its `INTERVIEW.md` before scaffolding a run;
|
||||
never scaffold one from memory.
|
||||
|
||||
**Precedence.** That skill is normative for method; this one is normative for
|
||||
archie's facts. If they disagree about the process, it wins. If they disagree
|
||||
about this repository — a path, an invariant, a gate — this one wins, because the
|
||||
method skill is repository-agnostic by construction.
|
||||
|
||||
Route runtime facts to `archie-run-and-operate`, toolchain facts to
|
||||
`archie-build-and-env`, and dependency/boundary rules to
|
||||
`archie-architecture-contract`.
|
||||
|
||||
## Invariants every lane call must carry
|
||||
|
||||
State these as facts to each lane, not as advice. Each one has cost a real run.
|
||||
|
||||
| Invariant | Why it matters to a lane |
|
||||
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| **The control plane fails closed.** A stored resource that will not validate stops `archied` starting, and nothing bypasses the control plane at boot. Resource history is the only in-band remedy, and it needs the State Store up. | A lane touching the boot path, a stored resource kind, or the recovery commands is a risk-routed lane for the operator's eyes, not a gate-and-merge lane. Evidence: `docs/architecture/safe-change-and-recovery.md` ("Database settings: degrade paths and recovery"). |
|
||||
| **`internal/webui` must not reach `internal/domain/workflow`.** Go imports are atomic: one reference relinks the whole daemon runtime into the UI binary. | `cmd/archie-ui/architecture_test.go` measures the linked binary (`go list -deps .`), not the imports, and fails on anything under `internal/domain/workflow`. `internal/domain/workflow/task` is a named `gateExceptions` entry that must stay linked — it carries only contract and view types, and a stale exception fails the test in both directions. The same test's gate also excludes `internal/app/archied` from the UI binary, so a helper needed by both the daemon and the `cmd/` binaries belongs in `internal/infrastructure/configuration` (which already owns path resolution), never in `archied`. |
|
||||
| **The task DB has one owner.** The task tables are served by the standalone `cmd/archie-state-store` process alone. No second listener, no in-process serving path in the daemon or Gateway. | `boot.openStateStore` (`internal/app/archied/state_store.go`) is the only place the task store is built, and it holds the `state-store` Postgres ownership lock for the process's life — a second State Store on the same database fails there rather than merely being discouraged. Offline maintenance belongs in subcommands of that binary, never a new `cmd/` entry (`docs/architecture/organisation.md#process-boundaries`). |
|
||||
| **Never commit `.beads/`.** Bead state moves through Dolt; `issues.jsonl` and `interactions.jsonl` are local-only. | A lane that stages `.beads/` pollutes its diff. Closing a bead is not commit-worthy on its own. |
|
||||
| **Generated assets are LAW.** `ui/dist/` and the schema outputs (`docs/data/generated/contracts.json`). | Incorporate them into the commit that shifted them. Never revert, regenerate away, or leave them out. |
|
||||
| **Scratch goes to `/tmp` only.** Never the working tree. | `worktree.CommitAll` stages with go-git's `AddWithOptions{All: true}` (`internal/worktree/worktree.go:502`), which does **not** honour `.gitignore`. An untracked scratch file in a lane worktree is swept onto the task branch. The task brief lives in `.git/task.json` for exactly this reason. |
|
||||
| **A config field must survive the control-plane round trip or it does nothing.** A field added to `MCPServer` (or any projected settings type) must be carried in three sites: `mcpServerSettings` and `seedTools` in `internal/app/controlplane/tool_settings.go`, and `runtimeToolConfigFrom` in `runtime_config.go`. | The control plane rebuilds the whole resource from that projection, so a field missing there is silently dropped whenever a control plane is configured: the setting parses, appears in the dashboard, and has no effect. `TestToolSettingsProjectionCarriesEveryMCPServerField` reflects over `MCPServer` and fails on an omitted field, in both directions (seed and layering) — but it covers that type only; every other mirrored type (`minimaxSettings`, ...) is still hand-mirrored. Adding the field to just `internal/config` is the `xrux`/`parallel_tool_calls` failure shape. |
|
||||
| **Dependency direction is `cmd -> app -> {domain, infrastructure}`**, with infrastructure implementing domain contracts. | A lane that needs a new edge says so before writing it. The `internal/{logging,events,eventbus,policy,taskstate}` cross-cutting packages import zero internal packages. Source: `docs/architecture/organisation.md`. |
|
||||
|
||||
## The canonical gate
|
||||
|
||||
```bash
|
||||
~/.agents/skills/high-throughput-programming/scripts/gate-evidence.sh \
|
||||
<worktree> '<scoped test cmd>' <base>
|
||||
```
|
||||
|
||||
Run it on the host, per lane. It executes the scoped tests, then a module-wide
|
||||
build (`go build ./...`) and the linter (`golangci-lint run ./...`), and emits
|
||||
JSON for the harness to use as the child's structured output.
|
||||
|
||||
The two extra checks are required, not optional. `go test ./pkg/...` compiles
|
||||
only that package, so a changed constructor signature or interface passes its own
|
||||
lane and breaks the next package to merge. That shape has bitten twice here: one
|
||||
lane changed a constructor's signature, passed its own gate, and failed three
|
||||
packages the moment it merged; formatting and lint drifted the same way, and only
|
||||
the repository gate saw it. Both failures are paid for inside the lane when the
|
||||
gate runs the build and the linter, and at merge when it does not.
|
||||
|
||||
Gate the **candidate** before `main` moves. Check the merge candidate out
|
||||
detached — or gate the lane branch — and advance the ref only on a green result:
|
||||
gating after a fast-forward lands the failure on the branch of record and leaves
|
||||
only fix-forward or reset as exits. The lane brief must name the linter as well,
|
||||
`golangci-lint run ./<package>/...` beside the scoped tests, because a scoped
|
||||
test run cannot see a complexity or style limit and `task check` is where that
|
||||
failure otherwise surfaces — once it is already merged.
|
||||
|
||||
A copy of the script under `.pi/control-plane-run/` is that run's disposable
|
||||
state and may lag the skill's version. The skill's copy is the one to trust.
|
||||
|
||||
## Shape a lane's test command like this
|
||||
|
||||
Name every package the change can reach, plus `go vet` on the same set:
|
||||
|
||||
```bash
|
||||
go test ./internal/app/controlplane/... ./internal/domain/applystatus/... -count=1 \
|
||||
&& go vet ./internal/app/controlplane/... ./internal/domain/applystatus/...
|
||||
```
|
||||
|
||||
Real examples, from the worked example's `lanes.json`:
|
||||
|
||||
| Lane surface | Scoped command |
|
||||
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| CLI subcommands and the State Store contract | `go test ./cmd/... ./internal/infrastructure/staterpc/... -count=1 && go vet ./cmd/...` |
|
||||
| Workflow registry and the agent worker | `go test ./internal/domain/workflow/... ./internal/app/agentworker/... -count=1 && go vet ./internal/domain/workflow/...` |
|
||||
| Config decoding and daemon boot | `go test ./internal/infrastructure/configuration/... ./internal/app/archied/... -count=1 && go vet ./internal/infrastructure/configuration/... ./internal/app/archied/...` |
|
||||
|
||||
`task check` is the _serial full gate_ — fmt, proto checks, `docs:check`, vet,
|
||||
lint, build, `go test ./...`, the tools tests and the dashboard tests. The merge
|
||||
train owns it. Never run it in a lane, and never two at once: it saturates the
|
||||
host.
|
||||
|
||||
"Never two at once" includes gates you did not start. More than one agent session
|
||||
works in this checkout, so before the merge train gates, check who holds it:
|
||||
|
||||
```bash
|
||||
ps -ef | grep -E '[t]ask check|[t]ask ' | grep -v grep
|
||||
```
|
||||
|
||||
A concurrent gate is not merely slow. Both runs regenerate
|
||||
`docs/data/generated/contracts.json` and `ui/dist`, so a contended result is
|
||||
worthless in either direction — neither run's verdict tells you anything about
|
||||
the tree. Wait for the host to be quiet and bound the wait: still held after
|
||||
about twenty minutes means report the contention rather than gate anyway.
|
||||
|
||||
The train integrates **local** `main`. Nothing in the gate consults `origin`, and
|
||||
the version stamp comes from `git describe --tags` against local tags, so
|
||||
unpushed commits neither block nor invalidate a gate run — the remote can lag
|
||||
and does, since the maintainer pushes when inclined.
|
||||
|
||||
## The agent-discovery trap
|
||||
|
||||
A lane worktree is a **sibling** of the repository (`/work/apps/cp-<lane>`), not a
|
||||
directory inside it. pi discovers project-scope agents under `<cwd>/.pi/agents/`,
|
||||
so a child launched in a lane worktree does not see them and dies with
|
||||
`Unknown agent: cp-writer`.
|
||||
|
||||
Fix it once per worktree:
|
||||
|
||||
```bash
|
||||
mkdir -p /work/apps/cp-<lane>/.pi
|
||||
ln -sfn /work/apps/archie-core/.pi/agents /work/apps/cp-<lane>/.pi/agents
|
||||
```
|
||||
|
||||
`.pi/` is gitignored, so the worktree stays clean and the symlink cannot reach a
|
||||
commit. This costs an hour to rediscover.
|
||||
|
||||
## Peer sessions over intercom
|
||||
|
||||
A fleet here can also run as **sibling sessions** coordinated over `intercom` —
|
||||
a peer per lane — rather than pi-subagents children under one orchestrator.
|
||||
These facts are peer-specific, and each has cost a real run.
|
||||
|
||||
- **Name the channel in the brief.** A peer's knowledge of how to report lives in
|
||||
its context, not its configuration. Write "report to <peer> over intercom" as
|
||||
an instruction; a convention that is only assumed evaporates.
|
||||
- **A compaction erases conventions, not just facts.** A peer that compacts
|
||||
mid-task keeps its task state and loses its transport: it reverts to
|
||||
addressing its operator, and the coordinator reads that as idleness or death.
|
||||
**Peer silence is not evidence of either** — ask for a one-line ack over the
|
||||
channel before concluding anything. Re-priming restores the channel; the
|
||||
transport itself survives compaction intact.
|
||||
- **Match the task's shape to the session's window, not its strength.** A sweep
|
||||
over hundreds of items needs the largest window available; a bounded hard
|
||||
artifact (a PRD, a conformance review, a design decision) belongs in a smaller,
|
||||
reasoning-strong session. A wide task in a small window stalls the task — too
|
||||
wide is not the same as too hard, and it is the coordinator's assignment error,
|
||||
not the peer's failure.
|
||||
- **Checkpoint at ~70%, never compact mid-task.** A terse ledger sent to the
|
||||
coordinator before the window fills survives; one reconstructed afterwards
|
||||
loses exactly the identifiers — bead IDs, exact counts — that made it worth
|
||||
having. Instruct every long-running peer to report and stop there.
|
||||
- **One writer per resource.** Exactly one session writes the tracker. Two
|
||||
writers produce double-closes, contradictory verdicts, and counts nobody can
|
||||
reconcile. When a sweep changes hands, the successor re-derives them rather
|
||||
than inheriting the predecessor's ledger as fact.
|
||||
|
||||
## Traps worth carrying
|
||||
|
||||
- **`touch` does not invalidate a Task source.** Task hashes file _content_, so a
|
||||
stale-binary probe has to change bytes. `task build` now tracks `ui/dist/**`,
|
||||
the generated dashboard the binary embeds, which is why the merge train still
|
||||
runs `task build --force` before the gate.
|
||||
- **`GATEWAY_VERSION` and `RUNTIME_VERSION` come from `git describe`**, which no
|
||||
file checksum can invalidate: an empty commit moves the stamp while `task
|
||||
build` still reports the binary up to date, shipping the old value. Tracked as
|
||||
`archie-core-pdq2`.
|
||||
- **The lane gate cannot see `tools/` or the contract schema.** `tools/` is
|
||||
a separate Go module that reaches `internal/` through `docsgen`, and
|
||||
`docs/data/generated/contracts.json` is generated from wire types such as
|
||||
`agentexec.Request`. A lane that adds an import to a package `tools/`
|
||||
reaches, or changes a wire type, passes its own gate and fails
|
||||
`task check` on a missing `tools/go.sum` entry or a stale schema. Such a
|
||||
lane runs `go -C tools mod tidy` and `task docs:generate` and commits both.
|
||||
Adding or editing a page under `docs/` — a PRD included — changes
|
||||
`docs/data/generated/dev-docs.json`, which gains or loses a page: regenerate it
|
||||
and commit it in the same commit, or `docs:artifact:check` fails. That failure
|
||||
lands on `main`, not in the lane, if the ref moves first.
|
||||
- **Untracked files in the shared checkout are other sessions'.** prdlint
|
||||
scratch (`docs/prds/rules.jsonl`), editor state, and gate-written artifacts
|
||||
appear and vanish under a lane. Never chase, add, stage or commit them: a
|
||||
merge train's scope is its own lanes' files, and nothing else.
|
||||
|
||||
## codegraph answers symbol questions cheaply
|
||||
|
||||
The maintainer's `codegraph` MCP server indexes this repository. Prefer it to
|
||||
grep or whole-file reading for "who calls X", "is this dead", "what does this
|
||||
change touch": it enumerates call sites that a grep only summarises, and labels
|
||||
each caller's confidence so interface fan-out is not mistaken for direct calls.
|
||||
|
||||
- **`pr_impact <base> <head>`** lists changed symbols with per-symbol caller and
|
||||
test counts. Read `interface_dispatch` and the inferred tests alongside
|
||||
`test_count`: a method reached through an interface reports a low direct test
|
||||
count while many indirect tests reach it, and the compact line alone invites
|
||||
the wrong conclusion.
|
||||
- **It is a derived cache.** `scip-go` and tree-sitter rebuild it, and a query
|
||||
indexes the revisions it names, so a cold query is slow and losing the index
|
||||
costs a rebuild rather than data. `list_repositories` reports the indexed
|
||||
revision — compare it with the tree before trusting a default-revision answer.
|
||||
- **Stagger heavy queries.** Concurrent sessions share one instance, and
|
||||
**name-based** `symbol_context` is what locks: it returns `database is locked`
|
||||
or times out, while the same symbol **by id** returns immediately. Query
|
||||
serially and retry rather than assuming a hang.
|
||||
- **Report problems one line at a time** in
|
||||
`/work/apps/codegraph/data/feedback.jsonl` — one JSON object per line, keys
|
||||
`date`, `repo`, `task`, `tools`, `helped`, `missed`, `wrong`, `slow`. A raw
|
||||
newline inside a string makes the line invalid and breaks every reader; a
|
||||
multi-line entry corrupted that file once. Validate, append, never rewrite.
|
||||
|
||||
## Tracker conventions
|
||||
|
||||
`bd` is the only tracker; no markdown TODO lists, no local trackers.
|
||||
|
||||
```bash
|
||||
bd show <id> # before working an item — the brief may describe a tree that has moved
|
||||
bd update <id> --claim
|
||||
bd close <id> # after the work lands, not when it commits
|
||||
```
|
||||
|
||||
Bead state moves through Dolt, never through git commits on this repository. The
|
||||
Dolt remote is pushed explicitly (`bd dolt push`) and never assumed to be in sync.
|
||||
|
||||
## Run artifacts are evidence, not documentation
|
||||
|
||||
`.pi/control-plane-run/` holds a run's scaffold, lane plan, prompts, scripts and
|
||||
gate output. It is gitignored and disposable. Treat it as run evidence only: a
|
||||
fact worth keeping goes into this skill or `docs/`, not into a
|
||||
run directory the next clean deletes.
|
||||
|
||||
## Worked example
|
||||
|
||||
`references/worked-example/` is the control-plane backlog run of September 2026,
|
||||
committed verbatim: the filled orchestrator prompt, four lane briefs, three
|
||||
sub-prompts, and the three agent definitions with their project invariants
|
||||
inlined. Read it for the level of detail a good brief carries.
|
||||
|
||||
Its scripts are the snapshot's, not the current ones. The user-scope skill's
|
||||
`scripts/` and `templates/` are normative and win any disagreement.
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "Archie Agent Fleet"
|
||||
short_description: "Run bounded agent fleets on archie-core"
|
||||
default_prompt: "Use $archie-agent-fleet to fan work out across lanes on this repository, carrying the fleet invariants, the gate evidence it needs, and the worktree agent-discovery fix."
|
||||
@@ -1,474 +0,0 @@
|
||||
# Mission: clear the archie-core control-plane backlog with a bounded high-throughput fleet
|
||||
|
||||
> **Where this file's paths point.** This is the committed copy of a live run.
|
||||
> Paths under `.pi/control-plane-run/` (sections 6, 9, 10) name that run's own
|
||||
> disposable copies of `wave0.js`, `wave2.js`, `review.js` and
|
||||
> `gate-evidence.sh`; they are gitignored run state and may lag the skill's
|
||||
> normative versions in `~/.agents/skills/high-throughput-programming/`. The
|
||||
> skill is the one to trust. Paths under `/work/apps/archie-core` and
|
||||
> repo-relative source paths are unchanged.
|
||||
|
||||
You are the orchestrator. You do not write production code yourself. You run
|
||||
waves of subagents through the `subagent` tool, verify their work against git
|
||||
evidence rather than their reports, and land finished slices on `main`.
|
||||
|
||||
Repository: `/work/apps/archie-core`, branch `main`, working tree clean at
|
||||
start. Gate: `task check`. Tracker: `bd`. Read `CLAUDE.md` and
|
||||
`docs/architecture/organisation.md` before Wave 1.
|
||||
|
||||
---
|
||||
|
||||
## 1. Hard rules
|
||||
|
||||
1. **One top-level `subagent` call per wave.** Every child launches inside that
|
||||
call's `workflowScript`. Never open a second top-level orchestration while a
|
||||
wave is running.
|
||||
2. **Read-only fans out wide. Writers do not.** Recon and review children are
|
||||
cheap and parallel. Writer children are bounded by file overlap and by this
|
||||
machine (16 cores), not by the spawn budget.
|
||||
3. **At most one `task check` at a time, ever.** It compiles 117 Go packages,
|
||||
runs the full test suite and the Node dashboard tests, and saturates the
|
||||
machine. Writer children run package-scoped tests only. The full gate belongs
|
||||
to the merge train in Wave 4, which is strictly serial.
|
||||
4. **A worker's report is not evidence.** Accept a lane only on: the handoff
|
||||
manifest path, `git -C <worktree> status --short`, `git log --oneline`, and
|
||||
`git diff --stat` against the lane's own base. A bead marked closed with no
|
||||
commits means the work did not happen.
|
||||
5. **No suppression.** Children may not add `//nolint`, `t.Skip`, build tags
|
||||
that exclude a failing test, or delete an assertion to make a gate pass. Say
|
||||
this in every writer and fix task. A child that suppresses gets its lane
|
||||
reverted, not patched.
|
||||
6. **Formatting is law.** Adopt `task fmt` output verbatim. Never revert a
|
||||
linter or formatter diff.
|
||||
7. **Zero patch stacking.** Two failed fixes on the same logic block means the
|
||||
block gets rewritten, not patched a third time. This is a `CLAUDE.md` rule
|
||||
and it applies to children.
|
||||
8. **Do not push.** Commit gate-clean work to `main` in the captain checkout.
|
||||
Sam pushes manually and does not always announce it, so never assume a commit
|
||||
is local or remote without checking `git log origin/main..main`.
|
||||
9. **No `.beads/` commits.** Bead state moves through Dolt. Closing a bead is
|
||||
not commit-worthy on its own.
|
||||
10. **Scratch stays out of the tree.** Children write scratch to `/tmp` only.
|
||||
`.pi/` is gitignored; nothing else you create may land in a commit.
|
||||
11. **Separation of duties.** No agent merges, closes or approves its own work.
|
||||
Writers write, reviewers review, and you alone run the merge train. You do
|
||||
not write production code; if you find yourself editing a lane's files, the
|
||||
lane was scoped wrong.
|
||||
12. **Every wave ends with an adversarial review pass** before the next wave
|
||||
starts. Reviewers are read-only, parallel and cheap; a defect caught at the
|
||||
end of the wave that produced it costs one lane, and the same defect caught
|
||||
three waves later costs the tree.
|
||||
|
||||
---
|
||||
|
||||
## 2. Ground truth: do not spend agents rediscovering this
|
||||
|
||||
This came from the session that just ended. Treat it as fact.
|
||||
|
||||
- `docs/prds/runtime-control-plane.md` is Approved and is the spec. Its resource
|
||||
surface, YAML workflow definitions, identity-backed attribution and audit
|
||||
trail are already built.
|
||||
- **Restore is not its own command.** A revision carries its value, so restoring
|
||||
replays it through the ordinary replace. Do not add a rollback RPC.
|
||||
- **Dashboard writes attribute to `identity.SystemID`.** One shared bearer
|
||||
token, no per-user session. `webAudit` in `internal/webui/api_identities.go`
|
||||
is the only source. Named attribution needs a dashboard login first.
|
||||
- **`internal/webui` must not link the workflow engine.** It decodes definitions
|
||||
with the projection types in `internal/domain/workflow/task`.
|
||||
`cmd/archie-ui`'s deletion gate fails if anything reaches
|
||||
`internal/domain/workflow`.
|
||||
- Shipped defaults ride `ResourceDescriptor.defaults_json`. The API is fixed at
|
||||
four operations, so defaults get no REST route.
|
||||
- `archie-messaging` fails closed when the State Store is unreachable. The
|
||||
database is authoritative for channel settings. File config is not a fallback.
|
||||
- **The control plane fails closed with no way back.** A stored value that will
|
||||
not validate stops `archied` starting. Nothing bypasses the control plane at
|
||||
boot. `docs/architecture/safe-change-and-recovery.md` records this posture.
|
||||
Resource history is the only in-band remedy and needs the State Store up.
|
||||
- **`task check` will not catch a field the server stopped sending.** Optional
|
||||
chaining made a dead dashboard banner typecheck silently;
|
||||
`delivery-snapshot.sh` scanned for a symbol its composition root no longer
|
||||
calls. Both fixed in `85f0fd0b`. When a server-side field is deleted, grep the
|
||||
dashboard and the snapshot scripts by name. Add this to every review task.
|
||||
- **Reload re-reads the database layer and can fail.** `boot.runtimeConfig` is
|
||||
the one layering call; the SIGHUP callback makes the same call over the
|
||||
document it just resolved (`9af013eb`). A new database-owned layer goes in
|
||||
`runtimeConfig` and nowhere else.
|
||||
- **Apply status lives on the State Store contract, not the control plane.**
|
||||
`PutApplyStatus`/`ListApplyStatus` are administrative, keyed on
|
||||
`(process, kind)`, replaced in place, re-stamped every 30s, stale at 90s, and
|
||||
a stale record renders as "Not reporting", never as current. `applystatus.New`
|
||||
refuses a process name `Processes()` does not list.
|
||||
- Five commits are local as of 2026-09-21: `731a9a06`, `1dd0d874`, `d9dd7885`,
|
||||
`9accf112`, `d38e27fd`. `archie-core-pskb` is closed. There is no post-commit
|
||||
hook; `core.hooksPath` is `.beads/hooks` and those are beads shims.
|
||||
|
||||
---
|
||||
|
||||
## 3. The backlog
|
||||
|
||||
Seven ready beads carry the `control-plane` label. Their real shape is what
|
||||
decides the lanes, and it is not the same as their titles.
|
||||
|
||||
| Bead | Title shape | Primary surface |
|
||||
| ------------------ | -------------------------------------------------------- | ------------------------------------------------------------- |
|
||||
| `archie-core-nwa0` | check a live replacement before switching to it | live apply path + apply-status surface |
|
||||
| `archie-core-fwmp` | let plugins register workflow step types | `workflow.BuiltinStepRegistry()` and all five call sites |
|
||||
| `archie-core-8szi` | registered steps covering the deleted `.archie` gate | `internal/domain/workflow/steps.go`, needs fwmp's answer |
|
||||
| `archie-core-6zw0` | offline backup/restore/validate/rollback for `archie.db` | new `cmd/` binary + state-store infrastructure |
|
||||
| `archie-core-i3qm` | stop TOML blocking State Store startup | `internal/app/archied/control_plane.go`, bootstrap validation |
|
||||
| `archie-core-xrux` | `ApplyOverlayValues` is dead, confirm the file overlay | `internal/infrastructure/configuration/loader.go`, `apply.go` |
|
||||
| `archie-core-eju6` | end-to-end restart test for a database-backed change | test only, proves the whole loop |
|
||||
|
||||
Three couplings you already know about, and Wave 0 exists to find the rest:
|
||||
|
||||
- **fwmp is the shared shape.** It changes the registry every call site
|
||||
hardcodes (`app/agentworker/task_execution.go:319,:335`,
|
||||
`app/controlplane/workflow_definitions.go:26,:33`,
|
||||
`app/controlplane/client.go:41`) and the validating side and the executing
|
||||
side must resolve it identically. 8szi has nothing to register against until
|
||||
fwmp lands. These two are never concurrent writers.
|
||||
- **xrux decides i3qm's blast radius.** xrux is an investigation with two
|
||||
opposite outcomes: either the file overlay zeroes omitted map fields, in which
|
||||
case `foldOverrides` moves there and it is a live bug, or it does not, in
|
||||
which case `apply.go`, `apply_test.go` and `Loader.ApplyOverlay` are deleted.
|
||||
Both land in the same package i3qm rewrites. One lane owns both, in that
|
||||
order. `archie-core-xrux` is a trap, not a cleanup. Read the bead before
|
||||
deleting `apply.go`.
|
||||
- **eju6 proves the others.** It goes last, against everything merged.
|
||||
|
||||
---
|
||||
|
||||
## 4. Models: resolve before Wave 0
|
||||
|
||||
Run `subagent({ action: "models" })` first and pick exact `provider/id` strings.
|
||||
Bare ids resolve only when unique. Then print the table you resolved and use it.
|
||||
|
||||
| Tier | Used by | Pick |
|
||||
| ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Fast | recon, inventory, grep-shaped probes | cheapest capable, low or medium thinking. Default `ollama/deepseek-v4.1-flash:cloud`. |
|
||||
| Strong | writers, integrator | best reasoning model authenticated here, high thinking. Prefer a `deepseek-v4-pro` class id if `models` lists one. |
|
||||
| Review | reviewers, oracle | a **different family** from the writer that produced the diff. Model diversity catches different failure modes; it does not rescue an ambiguous prompt. |
|
||||
|
||||
If a tier cannot be resolved, say so and fall back to the session default rather
|
||||
than inventing an id. Provider 429s return from that model; do not kill a rate
|
||||
limited child, it keeps its context and recovers.
|
||||
|
||||
---
|
||||
|
||||
## 5. Concurrency: the numbers that actually bind
|
||||
|
||||
Defaults in this install (`pi-subagents` 0.70.0) are not 64.
|
||||
|
||||
- `globalConcurrencyLimit` defaults to **20** concurrent children per run. Set
|
||||
it explicitly on each top-level call.
|
||||
- `maxSubagentSpawnsPerRun` defaults to **64** cumulative admissions per run
|
||||
tree, never refunded. Retries and fix passes spend it too.
|
||||
- **Each wave is its own top-level run, so each wave gets its own budget.** This
|
||||
is why the mission is split into waves rather than one giant script.
|
||||
- `runs.lanes` is capped at 32 lanes, 16 stages per lane, 64 stages total.
|
||||
|
||||
Per-wave dials:
|
||||
|
||||
| Wave | Shape | `globalConcurrencyLimit` | `maxSubagentSpawnsPerRun` |
|
||||
| -------------- | ------------------------------------------------------------------------ | ------------------------ | ------------------------- |
|
||||
| 0 recon | `runs.all`, read-only | 32 | 64 |
|
||||
| 0R audit | `review.js`, angles `claims` | 16 | 24 |
|
||||
| 1 shape-first | one writer plus one probe | 2 | 8 |
|
||||
| 1R review | `review.js`, full angle set, one target | 12 | 16 |
|
||||
| 2 writer lanes | `runs.lanes`, one worktree each | 4 | 32 |
|
||||
| 2R review | `review.js`, full angle set, four targets | 24 | 48 |
|
||||
| 3 fix pass | `runs.lanes`, retained writers | 4 | 24 |
|
||||
| 4 merge train | serial, one `task check` at a time | 1 | 8 |
|
||||
| 4R post-merge | `review.js` on merged `main`, angles `boundary`, `deadfield`, `contract` | 8 | 12 |
|
||||
| 5 eju6 | one lane, then its own review | 2 | 12 |
|
||||
|
||||
Do not set a hard `toolBudget` or a tight `usageBudget` on any writer, fix
|
||||
worker, or reviewer with edit authority: the default budget blocks read and
|
||||
search tools rather than mutation tools, which leaves a half-written tree. Bound
|
||||
writers with `timeoutMs` plus `checkpointBeforeDeadlineMs` instead. Hard caps
|
||||
are fine on explicitly read-only children.
|
||||
|
||||
---
|
||||
|
||||
## 5a. The constraint is review, not generation
|
||||
|
||||
Generation is no longer the bottleneck and has not been for a while. The
|
||||
measured evidence is consistent: agent-authored changes take far longer to reach
|
||||
a first review, merge at a lower rate than human-authored ones, and raise more
|
||||
issues per change; one randomized study found experienced developers 19% slower
|
||||
with agent tooling while expecting to be faster. Feature-branch throughput rises
|
||||
while main-branch throughput falls. Adding writer lanes past what review can
|
||||
absorb does not raise throughput, it grows a queue, and queued work ages badly
|
||||
because the tree moves underneath it.
|
||||
|
||||
Act on that as follows.
|
||||
|
||||
- **WIP is capped by review, not by cores.** Four writer lanes exist because
|
||||
four is what the review pass and the merge train can absorb per cycle. Do not
|
||||
raise it to use spare concurrency.
|
||||
- **Put the judgement upstream.** Before a writer starts, its task must carry
|
||||
intent, acceptance criteria and non-goals, so verification has an external
|
||||
reference. "Does this do what it was supposed to do" is checkable; "does this
|
||||
look right" is not, and fluent output passes a read-through scan regardless of
|
||||
whether it is correct.
|
||||
- **Spend the effort on the verifier, not the prompt.** A parallel fleet is only
|
||||
as good as the check that decides whether its output is right. A better test
|
||||
is worth more than a better instruction.
|
||||
- **Every handoff carries evidence.** Intent, non-goals, files touched with a
|
||||
reason each, alternatives rejected, commands actually run with pasted output,
|
||||
the test that would fail first, and known limitations. A report that only
|
||||
describes its own diff is not evidence.
|
||||
- **Deterministic gates run before any reviewer looks.** `gate-evidence.sh` runs
|
||||
the lane's tests on the host and emits JSON that becomes the child's
|
||||
structured output, and it fails the lane on added `//nolint`, `t.Skip`, ignore
|
||||
build tags, removed tests or removed assertions. Gate gaming is cheap to
|
||||
detect and expensive to miss, so detect it mechanically rather than asking a
|
||||
reviewer to notice.
|
||||
- **Keep batches small.** Generation being cheap is a reason for smaller
|
||||
changes, not bigger ones. A lane whose diff passes roughly 400 changed lines
|
||||
gets split at a coherent boundary.
|
||||
- **Route risk, do not review uniformly.** These surfaces get Sam's eyes before
|
||||
merge, named explicitly in your report: the fail-closed boot path
|
||||
(`boot.runtimeConfig`, bootstrap validation), the State Store wire contract
|
||||
and its error sentinels, task-scoped grants and credentials, anything that
|
||||
writes or migrates `archie.db`, and the release or CI surface. Everything else
|
||||
merges on gate plus reviewer verdict, with a sample called out for him to
|
||||
spot-check.
|
||||
- **Watch the right numbers.** Report per wave: reviewer findings raised versus
|
||||
accepted, lanes blocked by gate versus by review, rework passes per lane, and
|
||||
wall-clock from lane start to merged. Lines written and beads closed measure
|
||||
how fast the queue fills.
|
||||
|
||||
---
|
||||
|
||||
## 6. Wave 0: recon fanout (read-only, wide)
|
||||
|
||||
One top-level call, `async: true`,
|
||||
`workflowScriptPath: ".pi/control-plane-run/wave0.js"`.
|
||||
|
||||
Three probes per bead, plus four cross-cutting probes: 25 children, all
|
||||
`cp-recon`, all read-only, all returning structured output. The probe text is
|
||||
composed inside `wave0.js`; do not retype it.
|
||||
|
||||
Per bead:
|
||||
|
||||
- **spec** — extract the exact PRD clauses the bead must satisfy, with line
|
||||
anchors, and the acceptance criteria the gate can actually check.
|
||||
- **blast** — trace every call site, consumer and test of the symbols the bead
|
||||
names. Return package paths and file paths, not prose.
|
||||
- **tests** — inventory the tests that already cover this surface and name the
|
||||
one test that would fail first if the change were wrong.
|
||||
|
||||
Cross-cutting:
|
||||
|
||||
- **overlap** — for all seven beads, the set of packages and files each one must
|
||||
modify, in one table.
|
||||
- **gate-cost** — time `task build` and
|
||||
`go test ./internal/app/controlplane/...` and report wall-clock, so Wave 2
|
||||
timeouts are measured rather than guessed.
|
||||
- **dead-field** — grep `ui/src/` and `scripts/delivery-snapshot.sh` for every
|
||||
control-plane field name the server sends today, and flag any the server no
|
||||
longer sends. This is the failure class `task check` cannot see.
|
||||
- **contract-pairs** — find every place the validating side (State Store) and
|
||||
the executing side (archie-agent) must agree on the same vocabulary, and name
|
||||
the single test that would tie each pair together.
|
||||
|
||||
Every probe returns `structuredOutput` matching the schema in `wave0.js`. Long
|
||||
findings go to a file via `outputMode: "file-only"`; do not pull transcripts
|
||||
into your context.
|
||||
|
||||
**Do not let a recon child draw the conclusion.** A scout that measures
|
||||
correctly can still land the wrong call, and its write-up reads confident either
|
||||
way. Take their facts, make the call yourself.
|
||||
|
||||
---
|
||||
|
||||
## 7. Checkpoint A: lane plan, then stop
|
||||
|
||||
Build the conflict matrix from the `overlap` probe and the per-bead `blast`
|
||||
results. Two beads may be concurrent writers only if their file sets are
|
||||
disjoint. Directory names are not evidence of disjointness: check the imports.
|
||||
|
||||
Then report to Sam, in under 30 lines:
|
||||
|
||||
- the matrix, as bead by bead package intersections;
|
||||
- the proposed lanes, and which beads you are deliberately serializing;
|
||||
- any bead whose description no longer matches the tree, with the commit that
|
||||
moved underneath it;
|
||||
- the measured gate cost and the timeouts you derived from it;
|
||||
- anything in Wave 0 that contradicts section 2.
|
||||
|
||||
Wait for approval before Wave 1. This is the only mandatory stop.
|
||||
|
||||
---
|
||||
|
||||
## 8. Wave 1: shape-first, serial
|
||||
|
||||
Land the shared shape before anything forks against it. Five workers each adding
|
||||
a field to one struct produced eight cleanup commits on this repo in July; the
|
||||
merge cost scales with shared-file overlap, not worker count.
|
||||
|
||||
Sub-prompts for both children are in `prompts/wave1.md`.
|
||||
|
||||
1. **fwmp** alone: one `cp-writer`, `worktree: true`, red-green, gate
|
||||
`go test ./internal/domain/workflow/... ./internal/app/controlplane/... ./internal/app/agentworker/...`.
|
||||
Requirement: one contract test asserting the validating registry and the
|
||||
executing registry resolve the same step vocabulary. Two sides that each pass
|
||||
their own tests and disagree with each other is the exact failure this bead
|
||||
exists to prevent.
|
||||
2. Merge fwmp through the Wave 4 train immediately, before Wave 2 starts. Wave 2
|
||||
branches from the merged shape.
|
||||
3. **xrux investigation** runs concurrently with fwmp, because it is read-only
|
||||
until it has a verdict: one `cp-recon` writes a characterisation test in a
|
||||
scratch worktree that answers the single question, does `Loader.overlayFile`
|
||||
zero omitted fields of a map-valued entry. It returns the verdict and the
|
||||
test, and nothing else. The verdict decides the i3qm lane's stages.
|
||||
|
||||
---
|
||||
|
||||
## 9. Wave 2: bounded writer lanes
|
||||
|
||||
One top-level call, `runs.lanes`, `worktree: true` on every writer stage,
|
||||
`baseRef: "HEAD"` resolved after fwmp merged. Four lanes, concurrency 4.
|
||||
|
||||
| Lane | Beads | Stages |
|
||||
| ---------- | -------------- | ----------------------------------------------- |
|
||||
| `live` | nwa0 | red, green, self-gate, challenge |
|
||||
| `recovery` | 6zw0 | red, green, self-gate, challenge |
|
||||
| `steps` | 8szi | red, green, self-gate, challenge |
|
||||
| `config` | xrux then i3qm | verdict-apply, red, green, self-gate, challenge |
|
||||
|
||||
Stage contract, enforced by `wave2.js` and the `cp-writer` agent definition:
|
||||
|
||||
- **red**: write the failing table-driven test first, run it, and paste the
|
||||
failure. Verify the failure comes from an assertion, not a compile error. A
|
||||
test that cannot fail for an interesting reason is noise in the gate.
|
||||
- **green**: minimal implementation that satisfies the failing test.
|
||||
- **self-gate**: a typed `gate` pointed at
|
||||
`.pi/control-plane-run/gate-evidence.sh`, which runs the lane's package-scoped
|
||||
test command on the host and returns JSON that becomes the child's
|
||||
`structuredOutput`: branch, sha, changed files, uncommitted files, test exit
|
||||
and tail, plus the gate-gaming counters. Never `task check`. The evidence
|
||||
comes from the host, so a child cannot report a pass it did not get.
|
||||
- **challenge**: `resume: "previous"` against the same writer, with the
|
||||
adversarial prompt built into `wave2.js`'s challenge stage. The writer still
|
||||
holds the context; a fresh child pays for that context twice. Only resume a
|
||||
child `children.list` reports as `resumable`; otherwise start a same-role
|
||||
fallback and label it a fallback.
|
||||
|
||||
Each lane's writer also returns the evidence handoff in `wave2.js`: intent,
|
||||
non-goals, files with reasons, alternatives rejected, commands run with pasted
|
||||
output, the test that would fail first, and known limitations. A lane whose diff
|
||||
passes roughly 400 changed lines stops at a coherent boundary and reports what
|
||||
remains rather than growing further.
|
||||
|
||||
Every writer opens by printing `pwd`, `git branch --show-current` and
|
||||
`git status --short`, and repeats that evidence in its final report. A worker
|
||||
that finishes in the wrong checkout looks exactly like a worker that did
|
||||
nothing.
|
||||
|
||||
A failed stage blocks only its lane. Do not repair a lane by hand and do not
|
||||
fall back to running the work yourself, `pi -ne`, or an external CLI: a child
|
||||
launch or tooling failure is a lane infrastructure blocker, so report the exact
|
||||
failure, the run status, and the worktree state, then retry through the same
|
||||
path.
|
||||
|
||||
---
|
||||
|
||||
## 10. Review after every wave
|
||||
|
||||
`.pi/control-plane-run/review.js`, read-only `cp-reviewer` children on a
|
||||
different model family from the producer, one child per angle per target. The
|
||||
angles live in that script: `bead`, `invariant`, `contract`, `deadfield`,
|
||||
`boundary`, `operator`, `tests`, `gaming`, `intent`, plus `claims` for auditing
|
||||
recon findings.
|
||||
|
||||
| After | Targets | Angles |
|
||||
| ------ | ----------------------------- | ----------------------------------- |
|
||||
| Wave 0 | the recon findings themselves | `claims` |
|
||||
| Wave 1 | `cp/shape` | full set |
|
||||
| Wave 2 | the four lane branches | full set |
|
||||
| Wave 4 | merged `main` | `boundary`, `deadfield`, `contract` |
|
||||
| Wave 5 | the eju6 branch | `tests`, `operator`, `intent` |
|
||||
|
||||
The Wave 0 audit is the cheapest of these and catches the most: a recon child
|
||||
that measures correctly can still carry a wrong conclusion into your lane plan,
|
||||
and its write-up reads confident either way. Feed the audit the claims your lane
|
||||
plan is about to rest on, and check the load-bearing ones before Checkpoint A,
|
||||
not after.
|
||||
|
||||
Reviewers label findings P0/P1/P2 by evidence, not by severity language, carry
|
||||
`file:line` with a quoted proof, and end with one of `Merge verdict: BLOCK`,
|
||||
`Merge verdict: OK`, `Merge verdict: OK with notes`. Prose is never parsed for
|
||||
control flow: you decide the lane's fate from the findings.
|
||||
|
||||
Fixes go back to that lane's retained writer, batched into one pass, not one
|
||||
child per finding. Resume only a writer `children.list` reports as `resumable`;
|
||||
otherwise start a same-role fallback and label it as a fallback. A second failed
|
||||
fix on the same logic block means the lane is reverted and requeued, not patched
|
||||
again.
|
||||
|
||||
Count the pass as complete only when every angle returned. A missing angle is an
|
||||
unreviewed axis, not a clean one.
|
||||
|
||||
---
|
||||
|
||||
## 11. Wave 4: merge train, strictly serial
|
||||
|
||||
The procedure, with the exact commands, is in `prompts/wave4-merge-train.md`.
|
||||
One branch at a time, in dependency order, in the captain checkout at
|
||||
`/work/apps/archie-core`. Per branch:
|
||||
|
||||
1. `git merge-base --is-ancestor main <branch>`. A stale branch computed its
|
||||
deletions against code that has since changed; rebase or re-derive, never
|
||||
merge it as is.
|
||||
2. Apply the lane's handoff patch.
|
||||
3. `task check`, once, alone. Nothing else runs while it does.
|
||||
4. On failure: one fix pass through the lane's writer with the real output. On a
|
||||
second failure, revert the lane and requeue it; do not stack a third patch.
|
||||
5. Commit with a conventional scope (`feat(controlplane): ...`,
|
||||
`fix(config): ...`). Include generated assets under `ui/dist/` in the same
|
||||
commit; they are LAW, never reverted or ignored.
|
||||
6. `bd close <id>`. Do not stage `.beads/`.
|
||||
7. Verify it landed: `git log --oneline -1`, then `git branch --no-merged main`.
|
||||
Done has three states: no commits, committed and unmerged, merged. Only the
|
||||
third counts.
|
||||
|
||||
Your own edits get the same gate as the children's. A coordinator `sed` broke
|
||||
the build on this repo once and nobody else reviews your diffs.
|
||||
|
||||
---
|
||||
|
||||
## 12. Wave 5: eju6
|
||||
|
||||
Sub-prompt in `prompts/wave5-eju6.md`. Last, against merged `main`. One lane: an
|
||||
end-to-end test that drives a change through the API, restarts a process, and
|
||||
asserts the change survived. Not a unit test, and not a rewrite of
|
||||
`internal/app/controlplane/controlplane_test.go`, which covers seeding and
|
||||
catalogue only. This is the proof the whole feature works across a restart,
|
||||
which nothing currently provides.
|
||||
|
||||
If it fails, that is a finding about the feature, not about the test. Report it
|
||||
and stop rather than weakening the assertion.
|
||||
|
||||
---
|
||||
|
||||
## 13. Final report
|
||||
|
||||
- Beads closed, with the commit that closed each one.
|
||||
- Beads deliberately not attempted, and why.
|
||||
- `task check` result on final `main`, quoted, not summarised.
|
||||
- Every branch still unmerged, and whether it holds work.
|
||||
- Commits now local and unpushed (`git log --oneline origin/main..main`), stated
|
||||
as fact without pushing.
|
||||
- Anything you found that contradicts `docs/prds/runtime-control-plane.md` or
|
||||
section 2 of this prompt, filed as a new bead.
|
||||
- New beads for identified debt or follow-ups, filed via `bd`.
|
||||
- The wave metrics: per wave, reviewer findings raised versus accepted, lanes
|
||||
blocked by the gate versus by review, rework passes per lane, and wall-clock
|
||||
from lane start to merged. Say which stage was the constraint in practice and
|
||||
whether it matched the prediction that review would be.
|
||||
- The risk-routed surfaces that changed and need Sam's eyes: the fail-closed
|
||||
boot path, the State Store wire contract and error sentinels, grants and
|
||||
credentials, anything touching `archie.db`, and the release or CI surface.
|
||||
@@ -1,43 +0,0 @@
|
||||
# Worked example: archie-core control plane, September 2026
|
||||
|
||||
A real run, frozen partway through, kept verbatim so the shapes can be read
|
||||
rather than re-derived. It is repository-specific on purpose: the value is in
|
||||
seeing how much project knowledge a good brief carries.
|
||||
|
||||
**Its scripts are the snapshot's, not the current ones.** This directory was
|
||||
captured mid-run, so the scripts in it predate fixes the skill's own lessons
|
||||
describe — the typed-gate boolean trap, the post-fix re-gate and re-review, the
|
||||
P2 handling, the build and lint checks in the gate.
|
||||
`~/.agents/skills/high-throughput-programming/scripts/` and
|
||||
`~/.agents/skills/high-throughput-programming/templates/` are normative; if this
|
||||
directory disagrees with them, they win. Read the briefs, the lane plan and the
|
||||
merge-train procedure here. Do not copy the scripts.
|
||||
|
||||
The method this run followed lives in the user-scope skill
|
||||
`~/.agents/skills/high-throughput-programming/`; it is normative for method. This
|
||||
repository's `archie-agent-fleet` skill is normative for facts about archie-core.
|
||||
A run in another repository uses that skill's `templates/` plus its own filled-in
|
||||
briefs — none of the archie specifics here transfer.
|
||||
|
||||
Seven tracker items, one shared shape, four lanes, a review pass after every
|
||||
wave, a serial merge train.
|
||||
|
||||
| File | Note |
|
||||
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `00-orchestrator.md` | The filled orchestrator prompt. Section 2 is the project's ground truth, section 5a the review-is-the-constraint doctrine, section 10 the review cadence. |
|
||||
| `lanes.json` | Lane briefs carrying intent, traps and `file:line` premises. Read one to see the level of detail a brief needs. |
|
||||
| `prompts/wave1.md` | The shared shape, plus an investigation whose verdict gated another lane. |
|
||||
| `prompts/wave4-merge-train.md` | The serial merge procedure with the project's own hazards in it. |
|
||||
| `agents/` | The three agent definitions with project invariants inlined. |
|
||||
|
||||
No scripts are copied here. This run's `wave0.js`, `wave2.js`, `review.js` and
|
||||
`gate-evidence.sh` became `templates/recon.js`, `templates/lanes.js`,
|
||||
`templates/review.js` and `scripts/gate-evidence.sh` in the user-scope skill;
|
||||
those are normative, and this directory's stale copies were deleted so there is
|
||||
exactly one of each to keep current.
|
||||
|
||||
What this run's Wave 0 actually caught, which is the argument for recon before
|
||||
fanout: three of the seven items had premises that no longer matched the tree,
|
||||
including one whose target file did not exist under the name the item used, one
|
||||
whose anchor had moved commits earlier, and one whose scope could not reach the
|
||||
clause it cited. All three would have produced confidently wrong lanes.
|
||||
@@ -1,105 +0,0 @@
|
||||
# Control-plane backlog run: how to drive it
|
||||
|
||||
This is the committed copy of a real run. Its originals lived in
|
||||
`/work/apps/archie-core/.pi/control-plane-run/`, which is gitignored, disposable
|
||||
run state whose live copies may have moved on since. Nothing here is load
|
||||
bearing at runtime.
|
||||
|
||||
The method is not here. The pipeline shape, the concurrency ceilings, the
|
||||
pi-subagents traps, and the `scripts/` and `templates/` this file names all live
|
||||
in the user-scope skill `~/.agents/skills/high-throughput-programming/`, and that
|
||||
skill is normative for method. This copy is normative only for what the run
|
||||
looked like on this repository; the archie-specific facts themselves live in the
|
||||
parent `archie-agent-fleet` skill. A run in another repository uses that skill's
|
||||
`templates/` plus its own filled-in briefs.
|
||||
|
||||
## Files
|
||||
|
||||
| File | What it is |
|
||||
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `00-orchestrator.md` | The prompt you give pi. It owns the waves, the ceilings and the verification rules. |
|
||||
| _(the scripts)_ | This run's `wave0.js`, `wave2.js`, `review.js` and `gate-evidence.sh` are **not copied here**: they live on as `templates/recon.js`, `templates/lanes.js`, `templates/review.js` and `scripts/gate-evidence.sh` under `~/.agents/skills/high-throughput-programming/`, which are normative. The snapshot's copies were stale, so they were deleted rather than duplicated. |
|
||||
| `lanes.json` | Lane definitions: worktree paths, branches, beads, scoped test commands, briefs. Fill in the model id. |
|
||||
| `prompts/wave1.md` | fwmp shape-first writer, and the xrux verdict probe. |
|
||||
| `prompts/wave4-merge-train.md` | The serial merge procedure and the landing checks. |
|
||||
| `prompts/wave5-eju6.md` | The end-to-end restart test. |
|
||||
| `agents/cp-recon.md`, `agents/cp-writer.md`, `agents/cp-reviewer.md` | Project-scope agent definitions, as the run used them from `.pi/agents/`; these committed copies sit beside this file. |
|
||||
|
||||
## Start it
|
||||
|
||||
```fish
|
||||
cd /work/apps/archie-core
|
||||
pi "$(cat .pi/control-plane-run/00-orchestrator.md)"
|
||||
```
|
||||
|
||||
The `.pi/control-plane-run/` path is the run's own state directory, not this
|
||||
copy. Interactive is the right mode here: Checkpoint A after Wave 0 is a real
|
||||
stop and wants you in the loop. `/subagents-fleet` opens the live inspector,
|
||||
`/subagents-doctor` checks the install.
|
||||
|
||||
## Before Wave 2
|
||||
|
||||
Create the durable worktrees yourself. Managed `worktree: true` children capture
|
||||
a patch and then remove the worktree, which a resumed challenge stage cannot
|
||||
edit, so the lanes use operator-created worktrees plus per-child `cwd`.
|
||||
|
||||
```fish
|
||||
for lane in live recovery steps config
|
||||
git -C /work/apps/archie-core worktree add ../cp-$lane -b cp/$lane
|
||||
end
|
||||
```
|
||||
|
||||
A lane worktree is a **sibling** of the repository, so `.pi/agents/` inside the
|
||||
repository is not discovered from it. Link it per worktree or the children fail
|
||||
with `Unknown agent: cp-writer`:
|
||||
|
||||
```fish
|
||||
for lane in live recovery steps config
|
||||
mkdir -p /work/apps/cp-$lane/.pi
|
||||
ln -sfn /work/apps/archie-core/.pi/agents /work/apps/cp-$lane/.pi/agents
|
||||
end
|
||||
```
|
||||
|
||||
Then fill `model` in `lanes.json` from what `subagent({ action: "models" })`
|
||||
resolves, and pass it as `args`.
|
||||
|
||||
## Ceilings worth knowing before you tune anything
|
||||
|
||||
This install is `pi-subagents` **0.70.0**, matching your clone except for four
|
||||
doc files. Two 0.69/0.70 features are load bearing here: typed gates
|
||||
(`gate: { command, output: "json" }` turns a host command's JSON stdout into the
|
||||
child's `structuredOutput`) and `allowedAgents`, which can stop a reviewer
|
||||
launching a writer if you want separation of duties enforced rather than
|
||||
instructed.
|
||||
|
||||
- `globalConcurrencyLimit` defaults to **20**, not 64. Set it per top-level call.
|
||||
- `maxSubagentSpawnsPerRun` defaults to **64** cumulative admissions per run
|
||||
tree, never refunded, so retries spend it. Each wave is a separate top-level
|
||||
run precisely so each gets its own budget.
|
||||
- `runs.lanes` caps at 32 lanes, 16 stages per lane, 64 stages total.
|
||||
- `gate` is rejected on a retained `resume` item, which is why the challenge
|
||||
stage runs its tests through `bash` instead.
|
||||
- A typed gate cannot be combined with `outputSchema` on the same child, so the
|
||||
writer stages carry the gate and the reviewers carry the schema.
|
||||
- Host steps have no per-step `cwd`, which is why `gate-evidence.sh` takes the
|
||||
worktree path as its first argument instead of relying on one.
|
||||
|
||||
## Why the fleet is not 64 writers
|
||||
|
||||
64 concurrent children is comfortable for read-only work and pointless for
|
||||
writers here. Two limits bite first:
|
||||
|
||||
1. **Overlap.** Merge cost scales with shared file overlap, not worker count.
|
||||
Seven beads reduce to four genuinely disjoint lanes plus one shared shape
|
||||
that has to land alone first. Five workers each adding a field to one struct
|
||||
cost eight cleanup commits on this repo in July.
|
||||
2. **The machine.** 16 cores, 117 Go packages, and `task check` also runs the
|
||||
dashboard tests. One full gate saturates the host, so the gate is serialised
|
||||
into the merge train and writers run package-scoped tests.
|
||||
|
||||
The throughput comes from recon and review: 25 recon children, then a review
|
||||
pass after every wave at up to 36 children, all read-only, all cheap, all
|
||||
genuinely parallel. The writers stay at four because that is what the
|
||||
repository's coupling and the review pass can absorb. The measured literature is
|
||||
consistent that review, not generation, is where agent-heavy pipelines stall, so
|
||||
spare concurrency goes into checking rather than into more lanes.
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
name: cp-recon
|
||||
description:
|
||||
Read-only recon on archie-core. Traces call sites, extracts spec clauses,
|
||||
inventories tests. Returns citations, never conclusions.
|
||||
tools: read, grep, find, ls, bash
|
||||
excludeTools: write, edit
|
||||
acceptanceRole: read-only
|
||||
completionGuard: false
|
||||
inheritProjectContext: true
|
||||
inheritGlobalContext: false
|
||||
inheritSkills: false
|
||||
thinking: high
|
||||
systemPromptMode: replace
|
||||
---
|
||||
|
||||
You are a read-only investigator in the archie-core Go repository. You measure;
|
||||
you do not decide.
|
||||
|
||||
Rules:
|
||||
|
||||
- Never edit, write, stage, commit, or run anything that mutates the tree.
|
||||
`bash` is for `git log`, `grep`, `go list`, `bd show`, and timing commands
|
||||
only.
|
||||
- Every claim carries `file:line`. A claim without a citation is not a finding,
|
||||
it is a guess.
|
||||
- Report facts. The orchestrator draws the conclusion. Do not recommend a course
|
||||
of action unless you were asked for one, and never close or reopen a bead.
|
||||
- Grep first, then read only the lines that matter. Do not pull whole packages
|
||||
into context.
|
||||
- Directory and bead names are not evidence of coupling. Check the imports.
|
||||
- `ARCHITECTURE.md` and `CLAUDE.md` are stale by construction in this repo. The
|
||||
tree is the only evidence of current state; when a doc and the code disagree,
|
||||
report both and say which file you read.
|
||||
- If your task's premise is false, say so plainly as your first line instead of
|
||||
answering the question you were asked.
|
||||
|
||||
Finish with your structured output. Keep prose under 40 lines; long inventories
|
||||
belong in your output file.
|
||||
@@ -1,48 +0,0 @@
|
||||
---
|
||||
name: cp-reviewer
|
||||
description:
|
||||
Read-only adversarial reviewer for one archie-core lane and one angle.
|
||||
Evidence-labelled findings and a single merge verdict.
|
||||
tools: read, grep, find, ls, bash
|
||||
excludeTools: write, edit
|
||||
acceptanceRole: read-only
|
||||
completionGuard: false
|
||||
inheritProjectContext: true
|
||||
inheritGlobalContext: false
|
||||
inheritSkills: false
|
||||
thinking: high
|
||||
systemPromptMode: replace
|
||||
---
|
||||
|
||||
You review one lane of archie-core work from one angle. You did not write this
|
||||
code and you do not fix it.
|
||||
|
||||
Start from `git diff main..<branch>` and `git diff --stat main..<branch>`.
|
||||
Review the diff, never the writer's transcript: the transcript costs context and
|
||||
carries almost no signal.
|
||||
|
||||
What you are looking for, in order:
|
||||
|
||||
1. Behaviour the change dropped while keeping the shape. Refactors lose guards.
|
||||
Read every new or changed doc comment: one that describes a silent fallback
|
||||
is usually a confession.
|
||||
2. A claim in the diff that the code does not support.
|
||||
3. A test that restates an assignment or a constant instead of failing for an
|
||||
interesting reason.
|
||||
4. Two sides that must agree and have no test tying them together.
|
||||
|
||||
Rules:
|
||||
|
||||
- Read-only. Do not edit, stage, commit, or fix. Propose the fix in words.
|
||||
- Every finding carries `file:line` and a quoted proof.
|
||||
- Label by evidence, not by how bad it sounds: P0 breaks a user-reachable path
|
||||
or an invariant, P1 is a real defect with a bounded blast radius, P2 is worth
|
||||
fixing but not now.
|
||||
- "No finding" is a valid and useful answer. Do not manufacture findings to look
|
||||
thorough.
|
||||
- `task check` passing is not evidence of correctness: it cannot see a field the
|
||||
server stopped sending, because optional chaining makes a dead dashboard
|
||||
binding typecheck.
|
||||
|
||||
End with exactly one line: `Merge verdict: BLOCK`, `Merge verdict: OK`, or
|
||||
`Merge verdict: OK with notes`.
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
name: cp-writer
|
||||
description:
|
||||
Implementation worker for archie-core lanes. Red-green TDD in an isolated
|
||||
worktree, package-scoped gate, no suppression.
|
||||
tools: read, write, edit, grep, find, ls, bash
|
||||
acceptanceRole: writer
|
||||
inheritProjectContext: true
|
||||
inheritGlobalContext: false
|
||||
inheritSkills: false
|
||||
thinking: high
|
||||
timeoutMs: 5400000
|
||||
systemPromptMode: replace
|
||||
---
|
||||
|
||||
You implement one lane of work in the archie-core Go repository, inside your own
|
||||
git worktree.
|
||||
|
||||
Open every run by printing `pwd`, `git branch --show-current` and
|
||||
`git status --short`, and repeat all three in your final report. A worker that
|
||||
finishes in the wrong checkout looks exactly like one that did nothing.
|
||||
|
||||
Method:
|
||||
|
||||
1. Read the bead with `bd show <id>`, then `CLAUDE.md` and
|
||||
`docs/architecture/organisation.md`.
|
||||
2. Red: write the failing table-driven test first. Run it. Paste the failure.
|
||||
Confirm it fails on an assertion, not a compile error. A test that cannot
|
||||
fail for an interesting reason is noise in the gate.
|
||||
3. Green: the minimal implementation that satisfies the test.
|
||||
4. Run your lane's scoped test command. Never run `task check`: it saturates the
|
||||
machine and the merge train owns it.
|
||||
5. Commit on your lane branch with a conventional-commit subject scoped by
|
||||
package (`feat(controlplane): ...`).
|
||||
|
||||
Hard rules:
|
||||
|
||||
- Fix invalid state at the producer, not with a defensive check at the consumer.
|
||||
- Never suppress: no `//nolint`, no `t.Skip`, no build tag that hides a failing
|
||||
test, no deleted assertion. If a lint is wrong, leave it failing and say why.
|
||||
- Adopt `task fmt` output verbatim. Never revert a formatter or linter diff.
|
||||
- Two failed fixes on the same logic block means you rewrite the block, not
|
||||
patch it a third time. Prefer a clean 20-line rewrite over a 5-line band-aid.
|
||||
- Dependency flow is `cmd -> app -> {domain, infrastructure}`, with
|
||||
infrastructure implementing domain contracts. Nothing in `internal/webui` may
|
||||
reach `internal/domain/workflow`.
|
||||
- Do not widen scope. Work not asked for is a finding to report, not work to do.
|
||||
- Do not merge, do not push, do not touch `.beads/`, do not edit the main
|
||||
checkout.
|
||||
- Scratch files live in `/tmp`. Never in the working tree.
|
||||
- If the bead describes a world the tree no longer has, stop and report that
|
||||
instead of implementing it.
|
||||
|
||||
Your final report states: the commit sha, changed files, the scoped test command
|
||||
and its result, what you deliberately did not do, and any residual risk.
|
||||
@@ -1,38 +0,0 @@
|
||||
{
|
||||
"model": "REPLACE_WITH_STRONG_TIER_ID",
|
||||
"timeoutMs": 5400000,
|
||||
"lanes": [
|
||||
{
|
||||
"key": "live",
|
||||
"dir": "/work/apps/cp-live",
|
||||
"branch": "cp/live",
|
||||
"beads": ["archie-core-nwa0"],
|
||||
"test": "go test ./internal/app/controlplane/... ./internal/domain/applystatus/... -count=1 && go vet ./internal/app/controlplane/... ./internal/domain/applystatus/...",
|
||||
"brief": "Wave 0 and its claims audit corrected this bead's premise, and the correction is the work. There is not one live apply path, there are two, and the PRD clause (Archie starts and checks a replacement before switching, and if the check fails the old one keeps running) applies to both. (1) workflow-execution-settings is applied on a watch (internal/app/archied/control_plane.go:94) and reports apply status at :118. (2) personas is also watched and applied live in the same process (internal/app/archied/gateway_runtime.go:37 watch, :79-86 apply) and reports NO apply status at all, so personas is the live-watched kind that widens this bead. Correction to the earlier version of this brief: workflow-definitions is not applied by a daemon watch, but do not read that as \"no watch anywhere\" -- the webui streams it at internal/webui/api_control_plane.go:139, which is a generic SSE passthrough for any kind. That is a read path, not a component-replacement path, so it does not widen nwa0. What the audit also established: the hard-coded nil at control_plane.go:118 is inert (no path in applyWorkflowExecutionSettings can fail), so do not build the bead around \"the report path cannot carry a rejection\"; that framing is wrong. Order of work: add the build-and-probe step to the live apply path, retain the previous component when the check fails, and report the failure through the apply-status surface. Decide explicitly whether personas gets the same treatment in this bead or a follow-up bead; if it is a follow-up, file the bead rather than half-wiring it. Do NOT fix the watch-reconnect defect opportunistically: it is filed separately as archie-core-yrmr, and a defect found by a review pass must not be silently repaired inside another lane. Apply status is on the State Store contract, not the control plane: PutApplyStatus/ListApplyStatus are administrative, keyed on (process, kind), replaced in place, re-stamped every 30s, stale at 90s, and a stale record renders as \"Not reporting\", never as current. applystatus.New refuses a process name Processes() does not list, deliberately: an invented name would read as a process that is not running, which the PRD blesses as legitimate, so the failure would be invisible."
|
||||
},
|
||||
{
|
||||
"key": "recovery",
|
||||
"dir": "/work/apps/cp-recovery",
|
||||
"branch": "cp/recovery",
|
||||
"beads": ["archie-core-6zw0"],
|
||||
"test": "go test ./cmd/... ./internal/infrastructure/staterpc/... -count=1 && go vet ./cmd/...",
|
||||
"brief": "DECIDED: subcommands of cmd/archie-state-store (backup, restore, validate, rollback). Not a new binary. Sam's standing rule, restated 2026-09-21 and now recorded in docs/architecture/organisation.md#process-boundaries: a cmd/ entry is a process boundary, earned only when a surface fails independently of the rest of the fleet or when that process may need to run in more than one location (HA pair, NAT traversal, separate host). Operational commands over a surface an existing binary already owns are subcommands of it. Do not reopen this. Two premise corrections from Wave 0 that change the work. First, the file is <dir>/archie.db-tasks.sqlite (cmd/archie-state-store/main.go:290-292, asserted at main_test.go:435-439), not archie.db, so a command that operates on 'archie.db' by name operates on nothing. Second, part of this already exists in shell: scripts/archie-update-install:189 takes a sqlite3 .backup of the task database and describes it as the watchdog's only route back from a forward schema migration. That makes this bead partly consolidation. The subcommand becomes the one authoritative implementation and the install script calls it, rather than a Go path and a shell path that drift apart. Changing that script is in scope for this lane; the watchdog's refusal semantics (an update that cannot back up must not start) must survive the change unchanged. The command operates on the database file directly with the State Store stopped, refuses to run against a live store, and adds no rollback RPC: a revision carries its value and restoring replays it through the ordinary replace."
|
||||
},
|
||||
{
|
||||
"key": "steps",
|
||||
"dir": "/work/apps/cp-steps",
|
||||
"branch": "cp/steps",
|
||||
"beads": ["archie-core-8szi"],
|
||||
"test": "go test ./internal/domain/workflow/... ./internal/app/agentworker/... -count=1 && go vet ./internal/domain/workflow/...",
|
||||
"brief": "internal/domain/workflow/steps.go:215 and :227 hard-error on legacy .archie/stages/*.go and .archie/gate.go and tell the operator to migrate to a registered YAML workflow step, but BuiltinStepRegistry() only exposes the six shipped workflows' own stages, so there is nothing to migrate to. Identify what the removed hooks actually did and land the equivalent as registered step types. This lane starts only after archie-core-fwmp has merged, and registers against the extension point fwmp created. Do not re-open the registry design."
|
||||
},
|
||||
{
|
||||
"key": "config",
|
||||
"dir": "/work/apps/cp-config",
|
||||
"branch": "cp/config",
|
||||
"beads": ["archie-core-xrux", "archie-core-i3qm"],
|
||||
"test": "go test ./internal/infrastructure/configuration/... ./internal/app/archied/... -count=1 && go vet ./internal/infrastructure/configuration/... ./internal/app/archied/...",
|
||||
"brief": "Two beads in order, one package owner. First archie-core-xrux. The verdict is already measured with evidence (Wave 0R claims audit c6) and it is ZEROES: the -config-overlay file path silently drops every field a partial map-valued entry omits, which is exactly the archie-core-e2e2 hazard, and it is user-reachable because deployments/dev.toml is the documented -config-overlay argument and sets [services.state] target/listen, while the base config.toml is where [services.state].target_token lives -- so the overlay drops the token. The red stage is a committed characterization test through the production entry point (Loader.Resolve / -config-overlay) that loads a config with a populated map-valued entry, overlays a file setting one sibling key, and asserts the omitted keys survive; it fails today. Then move apply.go's foldOverrides (apply.go:60) onto the file overlay path (loader.go:161-194, decode at :176) so it passes. Do NOT delete apply.go, apply_test.go or Loader.ApplyOverlay: the hazard they were written for is live on that path. No dotted-path field merge is wanted beyond this guard, because the control plane replaces whole documents. Then archie-core-i3qm, whose anchor and scope the audit corrected. control_plane.go:13 is a blank line (the doc comment is :14-18); the calls moved to :20 (RuntimeConfig) and :27 (configuration.Validate) in 9accf112. More importantly the PRD clause names State Store startup, and state_store.go:75-104 never calls runtimeConfig: it reaches Loader.finalize via bootstrap.go:263 (the loader.Resolve call site, not finalize itself) and loader.go:341-346, where Validate runs. Scope correction: that file-only Validate runs before loadRuntimeConfig for ALL THREE binaries (main.go:358, gateway.go:61, state_store.go:78), so it is not state-store-specific; and a value that is valid alone but invalid only after the DB merge never blocks the state store at all, because it is imported unvalidated at state_store.go:104 and fails later in the daemon's loadRuntimeConfig (control_plane.go:27). Reduce the bootstrap document to the fields the PRD lists (database path, listen addresses, credentials, TLS, encryption-key references) and stop validating the migrated surface at startup, so a stale TOML value in a database-owned field cannot fail boot. boot.runtimeConfig is the one layering call and the SIGHUP callback makes the same call: if you add a database-owned layer, add it there and nowhere else."
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -1,73 +0,0 @@
|
||||
# Wave 1 sub-prompt: shape first
|
||||
|
||||
**One child. fwmp alone.** Nothing else runs until it merges, and Wave 2
|
||||
branches from the merged shape.
|
||||
|
||||
xrux is no longer a Wave 1 probe. Its verdict is already measured with evidence
|
||||
(Wave 0R claims audit c6) and the answer is **ZEROES**. Re-measuring buys
|
||||
nothing, so the characterisation test is folded into the `config` lane's red
|
||||
stage, where it is committed and the evidence lives in the tree rather than in a
|
||||
transcript. See the `config` brief in `lanes.json`.
|
||||
|
||||
---
|
||||
|
||||
## fwmp: the shared shape (cp-writer, worktree `/work/apps/cp-shape`, branch `cp/shape`)
|
||||
|
||||
Gate:
|
||||
`go test ./internal/domain/workflow/... ./internal/app/controlplane/... ./internal/app/agentworker/... -count=1`
|
||||
|
||||
```text
|
||||
Bead archie-core-fwmp. Run `bd show archie-core-fwmp` first.
|
||||
|
||||
docs/prds/runtime-control-plane.md:95 says plugins can add step types. Today every
|
||||
call site hardcodes workflow.BuiltinStepRegistry():
|
||||
internal/app/agentworker/task_execution.go:319 and :335,
|
||||
internal/app/controlplane/workflow_definitions.go:26 and :33, and
|
||||
internal/app/controlplane/client.go:41. The step vocabulary is closed to the six
|
||||
shipped workflows.
|
||||
|
||||
Verified by the Wave 0 claims audit, so treat as fact and do not re-derive:
|
||||
- Those are exactly five non-test call sites, plus five test call sites.
|
||||
- BuiltinStepRegistry() is defined at internal/domain/workflow/definition.go:149 and
|
||||
is built only from legacyBuiltinWorkflows() (definition.go:181).
|
||||
- StepRegistry is a plain `map[string]StepFactory` (definition.go:32). There is no
|
||||
merge/widen function; BuiltinStepRegistry() is itself the only registration site.
|
||||
- All five production call sites pass the identical function, so nothing diverges
|
||||
today. The gap is the absence of a guard, not a live defect.
|
||||
|
||||
Deliver: a registry assembled from the plugin set, resolved identically on both
|
||||
sides.
|
||||
|
||||
The load-bearing constraint is not the extension point, it is agreement. The
|
||||
validating side is the State Store; the executing side is archie-agent. A
|
||||
definition that validates and then fails to compile at run time is the failure
|
||||
this bead exists to prevent, and it is exactly the failure two packages that each
|
||||
pass their own tests produce. No test today ties the two sides: no test file
|
||||
imports both internal/app/controlplane and internal/app/agentworker. Your change
|
||||
is not done until one test asserts that both sides resolve the same step
|
||||
vocabulary from the same plugin set. Write that test first and let it fail for the
|
||||
right reason.
|
||||
|
||||
Do NOT edit internal/domain/workflow/definition_test.go:8
|
||||
TestParseDefinitionRejectsUnsafeDefinitions. The audit established it is not an
|
||||
obstacle: its pin is name-exact ("shell" at :11, implement.prepare's own factory at
|
||||
:12), so a settings-bearing plugin step type under any other name passes it
|
||||
unchanged. Adding a step type is archie-core-8szi's lane, not this one.
|
||||
|
||||
Do NOT fix the workflow-version pin opportunistically. The audit found it is never
|
||||
persisted over gRPC and its digest guard is dead in production; that is filed as
|
||||
archie-core-zf8h and gets its own lane and Sam's eyes. Report it if you touch it,
|
||||
do not repair it here.
|
||||
|
||||
Before adding a plugin engine surface, satisfy
|
||||
ARCHITECTURE.md#plugin-engine-rule-strict.
|
||||
|
||||
This is the shape every other lane branches from, so it lands alone and it lands
|
||||
first. Do not implement any step type; archie-core-8szi does that afterwards
|
||||
against what you build. Do not widen scope to the .archie gate behaviour.
|
||||
|
||||
Working contract: print pwd, git branch --show-current and git status --short
|
||||
before editing and repeat them in your report. Red then green. Package-scoped
|
||||
tests only, never `task check`. No //nolint, no t.Skip, no deleted assertions.
|
||||
Adopt `task fmt` verbatim. Commit on cp/shape with a conventional subject.
|
||||
```
|
||||
-66
@@ -1,66 +0,0 @@
|
||||
# Wave 4: merge train
|
||||
|
||||
Serial. You run this yourself in the captain checkout at
|
||||
`/work/apps/archie-core`. No subagent owns `main`, and only one `task check`
|
||||
exists at a time.
|
||||
|
||||
Order: `cp/shape` (already merged in Wave 1), then `cp/config`, `cp/live`,
|
||||
`cp/recovery`, `cp/steps`. Config goes early because it owns the bootstrap path
|
||||
the others boot through.
|
||||
|
||||
## Per branch
|
||||
|
||||
```bash
|
||||
BR=cp/live
|
||||
|
||||
git -C /work/apps/archie-core status --short # must be clean
|
||||
git merge-base --is-ancestor main $BR && echo "stale: rebase required"
|
||||
git log --oneline main..$BR
|
||||
git diff --stat main..$BR
|
||||
```
|
||||
|
||||
A branch that predates a merge computed its deletions against code that has
|
||||
since changed. On this repo a stale branch's diff deleted 460 lines of
|
||||
`internal/config` that read as tidy relocation and would have reverted another
|
||||
lane's decomposition. Rebase it or re-derive the work. Never merge a diff whose
|
||||
deletions were computed against code that has moved.
|
||||
|
||||
Then:
|
||||
|
||||
1. `git merge --no-ff $BR` (or apply the lane's handoff patch if the lane ran in
|
||||
a managed worktree).
|
||||
2. `task build --force`, then `task check`, once, alone. Nothing else runs on
|
||||
this machine while it does. The force-build is required until
|
||||
archie-core-hhgw lands: `task build`'s sources are Go-only
|
||||
(Taskfile.yml:325), so a ui/dist-only change does not retrigger it and a
|
||||
stale embedded dashboard would ship (Wave 0R audit c10).
|
||||
3. On failure: one fix pass back to that lane's retained writer with the real
|
||||
output pasted in, not a summary. On a second failure, `git reset --hard` the
|
||||
merge, requeue the lane, and move to the next branch. Do not stack a third
|
||||
patch, and do not fix it yourself unless the fix is one line and obvious.
|
||||
4. Commit generated assets in the same commit. `ui/dist/` and schema outputs are
|
||||
LAW: never regenerated away, never reverted, never left out.
|
||||
5. `bd close <id>` for each bead the branch delivered. Do not stage `.beads/`,
|
||||
and never create a commit whose only content is beads bookkeeping.
|
||||
|
||||
## Landing check, every time
|
||||
|
||||
```bash
|
||||
git log --oneline -3
|
||||
git branch --no-merged main
|
||||
git log --oneline origin/main..main
|
||||
```
|
||||
|
||||
Done has three states: no commits, committed and unmerged, merged. Only the
|
||||
third counts. A closed bead is what a worker believed, not what landed.
|
||||
|
||||
## Your own edits
|
||||
|
||||
A coordinator `sed` rename on this repo once produced `&fakeStore{fakeStore{` in
|
||||
six places and broke the build. Your edits get the same gate as the children's,
|
||||
and nobody else reviews them.
|
||||
|
||||
## Do not push
|
||||
|
||||
Sam pushes manually and does not always announce it. Report what is unpushed as
|
||||
fact. If `git log origin/main..main` is long, say how long; do not act on it.
|
||||
@@ -1,53 +0,0 @@
|
||||
# Wave 5: eju6, the end-to-end restart test
|
||||
|
||||
One lane, one `cp-writer`, against merged `main`. This is the only bead that
|
||||
proves the feature rather than adding to it, so it runs last and alone.
|
||||
|
||||
Gate: `cd <worktree> && go test ./internal/app/controlplane/... -count=1`, then
|
||||
`task check` through the merge train as usual.
|
||||
|
||||
```text
|
||||
Bead archie-core-eju6. Run `bd show archie-core-eju6` first.
|
||||
|
||||
docs/prds/runtime-control-plane.md ("First implementation") lists an end-to-end
|
||||
restart test as a deliverable and there is none.
|
||||
internal/app/controlplane/controlplane_test.go covers seeding and catalog only.
|
||||
No test drives a change through the API, restarts a process, and asserts the
|
||||
change survived.
|
||||
|
||||
Deliver that test: a real end-to-end check, not a unit test, and not a rewrite
|
||||
of the existing file.
|
||||
|
||||
It must, in one test:
|
||||
1. write a settings change through the control-plane API, as the dashboard
|
||||
would, attributing to identity.SystemID;
|
||||
2. observe the change land in the audit trail as an ordinary edit;
|
||||
3. restart the process that consumes it;
|
||||
4. assert the process came back on the stored value, not the file value;
|
||||
5. assert the apply-status row for that process reports the version it
|
||||
applied, and that a record older than 90 seconds reads as "not reporting"
|
||||
rather than as current.
|
||||
|
||||
Facts you need and must not re-derive:
|
||||
- boot.runtimeConfig is the single layering call, and the SIGHUP reload makes
|
||||
the same call over the document it just resolved (9af013eb). A reload cannot
|
||||
revert a database-owned setting to its file value, and that is the property
|
||||
under test.
|
||||
- Execution budgets arrive on a watch, not a resource query, so boot records
|
||||
the last settings it applied and the reload re-applies them from there.
|
||||
- PutApplyStatus/ListApplyStatus are administrative on the State Store
|
||||
contract: a task-scoped grant is denied both by the deny-by-default arm of
|
||||
authorizesTaskScopedCall. Your harness needs the administrative token.
|
||||
- Rows are keyed on (process, kind) and replaced in place; every process
|
||||
re-stamps every 30 seconds.
|
||||
- The control plane fails closed: a stored value that will not validate stops
|
||||
archied starting.
|
||||
|
||||
If the test fails, that is a finding about the feature, not about the test.
|
||||
Report the failure with the output and stop. Do not weaken an assertion, do not
|
||||
add a retry loop to paper over a race, and do not mark it t.Skip.
|
||||
|
||||
If a real end-to-end restart cannot be driven in-process, say so explicitly and
|
||||
describe what harness it would need, rather than substituting a unit test that
|
||||
asserts less and claims the bead.
|
||||
```
|
||||
@@ -1,246 +0,0 @@
|
||||
---
|
||||
name: archie-architecture-contract
|
||||
description: >-
|
||||
Protect Archie's load-bearing architecture while placing, implementing, or
|
||||
reviewing behaviour. Load this skill before changing daemon composition,
|
||||
domains, workflows, task lifecycle, agent execution, messaging, work intake,
|
||||
identity, memory, configuration, plugins, policies, persistence, NATS/RPC,
|
||||
containers, or process boundaries; use it when deciding where new code
|
||||
belongs, enforcing dependency direction, separating current runtime truth
|
||||
from the approved target and open migration decisions, or ensuring every
|
||||
behaviour has one authoritative path. Route proof of duplication, dead-code
|
||||
disposition, production reachability, and maintainability to
|
||||
archie-technical-accountability.
|
||||
---
|
||||
|
||||
# Archie Architecture Contract
|
||||
|
||||
Treat architecture as executable safety policy. Preserve one understandable
|
||||
owner and one production path for each behaviour.
|
||||
|
||||
## Read status before code
|
||||
|
||||
| Label | Meaning | Authority |
|
||||
| ------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| **CURRENT** | Behaviour present in live code and production composition as of 2026-09-18. | Code, tests, and `internal/app/archied` wiring (`cmd/archied/main.go` is a thin dispatcher) |
|
||||
| **APPROVED TARGET** | Direction an implementation must approach, but which may not exist on disk. | `docs/prds/01-project-management.md` and documents whose status says approved |
|
||||
| **OPEN** | A migration or API decision no implementer may invent locally. | `docs/architecture/migration-decisions.md` and documents marked in progress or under design |
|
||||
|
||||
> **Do not implement target prose as though it describes current code.**
|
||||
> Before treating a target package as available, prove that it exists and is
|
||||
> used from a production entry point. As of 2026-09-18 `internal/domain/`,
|
||||
> `internal/eventbus/`, `internal/infrastructure/`, and `internal/app/` exist;
|
||||
> `internal/policy/` does not, and `internal/domain/{agent,identity}` remain
|
||||
> APPROVED TARGET only.
|
||||
|
||||
Resolve apparent disagreement in this order:
|
||||
|
||||
1. Read live code and production composition for CURRENT behaviour.
|
||||
2. Read `docs/prds/01-project-management.md` for APPROVED TARGET ownership.
|
||||
3. Read the focused decision document for the selected behaviour.
|
||||
4. Read `docs/architecture/migration-decisions.md` for OPEN work.
|
||||
5. Stop and use `archie-architecture-planning-campaign` if a required semantic
|
||||
decision remains open.
|
||||
|
||||
Route to `archie-domain-reference` for glossary and
|
||||
`archie-config-and-flags` for config enumeration.
|
||||
|
||||
Two skills this document routes to are parked outside this checkout, under
|
||||
`/work/apps/archie-skills-parked/`: `archie-technical-accountability` and
|
||||
`archie-architecture-planning-campaign`. If your session has not loaded them,
|
||||
treat each routing target as a manual escalation step rather than a live skill.
|
||||
Also: `cmd/archied/main.go` is a thin dispatcher; the wiring lives in
|
||||
`internal/app/archied/`.
|
||||
|
||||
## Know the CURRENT system
|
||||
|
||||
Do not simplify these facts into the target model:
|
||||
|
||||
| Concern | CURRENT runtime truth on 2026-09-18 | Evidence |
|
||||
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
||||
| Composition | `cmd/archied/main.go` dispatches to `internal/app/archied.Run()`, which performs construction and wiring in `bootstrap.go`. | `cmd/archied/main.go`; `internal/app/archied/` |
|
||||
| Durable work | `task.Task` combines forge/chat source data, workflow position, output, retry, identity, and PR state. | `internal/domain/workflow/task/task.go`; `internal/domain/storecontract/storecontract.go` |
|
||||
| Workflow | `internal/domain/workflow` routes a `task.Task` into a `map[string]Workflow`, mutates a broad `TaskContext` through sequential stages. | `internal/domain/workflow/workflow.go` |
|
||||
| Agent-stage boundary | Versioned `agentexec.Request`/`Result` carries one autonomous stage; validation correlates task, attempt, and stage. | `internal/agentexec/protocol.go` |
|
||||
| Container handoff | `internal/taskrun` carries entire task plus `config.Repo` and `config.TaskConfig`; `internal/app/agentworker` owns routing and sequencing while its NATS adapter owns wire mechanics. | `internal/taskrun/taskrun.go`; `internal/app/agentworker/`; `internal/infrastructure/agenttransport/nats/` |
|
||||
| Git ownership | Daemon-owned worktree operations clone, commit, push, diff, and clean up. | `internal/worktree/`; `internal/domain/workflow/steps.go`; `docs/architecture/agent-system.md` |
|
||||
| Enforcement | Gates, read-only/protected paths, TDD inverted test gates, and diff caps are represented outside prompt prose. | `internal/gate/`; `internal/domain/workflow/{agent,tdd,steps}.go` |
|
||||
| Configuration | `internal/config.Config`, `IdentityConfig`, `Repo`, and task snapshots mix input decoding with runtime concerns. Decoding itself lives in `internal/infrastructure/configuration`. | `internal/config/config.go`; `internal/infrastructure/configuration/` |
|
||||
| Identity | Configured names and bot usernames act as process-local identity keys. There is no durable Identity domain. | `internal/daemon/daemon.go`; `internal/domain/storecontract/storecontract.go`; `internal/gateway/session.go` |
|
||||
| Messaging | `internal/gateway` contains both the `Message` struct flow and richer `MessageEvent`; channel routing and task control are mixed with conversational behaviour. | `internal/gateway/{gateway,messageevent,tasks}.go`; `internal/channels/` |
|
||||
| Plugins | `plugin.Plugin` exposes only `Name` and `Version`; current loading interprets operator-installed Go files with Yaegi. | `internal/plugin/plugin.go` |
|
||||
| Processes | Agent modes include in-process, subprocess, and NATS. Optional containers add a distinct boundary with known gaps. | `internal/config/config.go`; `internal/app/archied/`; `docs/architecture/organisation.md` |
|
||||
|
||||
### Interpret the current lifecycle honestly
|
||||
|
||||
Use these CURRENT status values:
|
||||
|
||||
```text
|
||||
queued, running, waiting_human, pr_open, merged,
|
||||
parked, dead, rejected, closed_wont_do
|
||||
```
|
||||
|
||||
The intended flow includes queue/claim, workflow stages, human wait/resume, PR
|
||||
reconciliation, parking/retry/exhaustion, and crash recovery. Read
|
||||
`internal/domain/workflow/task/task.go`, `internal/daemon/daemon.go`, and
|
||||
`internal/domain/workflow/workflow.go` before changing a transition.
|
||||
|
||||
`Store.Transition(ctx, taskID, from, to, detail)` now guards on `from`
|
||||
(`WHERE id=? AND status=?`, returning `store.ErrStaleTransition` on mismatch)
|
||||
and runs the status update plus the transition-history insert in one
|
||||
transaction (`internal/infrastructure/postgres/store.go`). The sentinel crosses the State Store
|
||||
gRPC boundary via `mapError`/`unmapError` in
|
||||
`internal/infrastructure/staterpc/values.go`; its canonical message string is
|
||||
part of the wire contract. Earlier non-atomic behaviour is the settled fix,
|
||||
not an open design.
|
||||
|
||||
## Preserve the load-bearing invariants
|
||||
|
||||
| Invariant | Required action | Status and source |
|
||||
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
||||
| The model never runs git | Keep clone, branch, commit, push, diff, and cleanup in deterministic workspace/worktree steps. | CURRENT: `docs/architecture/agent-system.md`; `internal/worktree/` |
|
||||
| Deterministic constraints outrank prompts | Enforce gates, protected paths, read-only stages, test protection, and change caps outside model instructions. | CURRENT: `docs/architecture/agent-system.md`; `internal/gate/`; `internal/domain/workflow/` |
|
||||
| Agent execution is a data boundary | Send bounded, versioned input; validate correlated output before applying it. | CURRENT foundation: `internal/agentexec/protocol.go`; `docs/architecture/agent-system.md` |
|
||||
| Every workflow ends explicitly | Preserve terminal outcome or visible park. Preserve crash recovery of interrupted `running` work. | CURRENT: `internal/domain/workflow/workflow.go`; `internal/infrastructure/postgres/store.go` |
|
||||
| Generic plugins stay metadata-only | Keep `plugin.Plugin` at `Name()`/`Version()`. Behaviour on typed capability interface with owning `Registry`/`Manager`. | CURRENT-enforced rule: `internal/plugin/architecture_test.go` |
|
||||
| Capability engines own lifecycle | Give resource-owning engines explicit start/health/stop semantics and failure isolation. | APPROVED rule: `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict` |
|
||||
| Trust is explicit | Treat trusted operator-installed in-process code, repository code, out-of-process integrations, and container-isolated code as different trust classes. | APPROVED rule: `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict` |
|
||||
| Infrastructure stays replaceable | Keep forge, persistence, workspace, transport, container, and model details behind behaviour-owned contracts. | APPROVED TARGET: `docs/architecture/dependencies-and-contracts.md` |
|
||||
| Same-repository execution serialises by default | Preserve default unless explicit scheduling policy permits concurrency. | CURRENT: `internal/config/config.go`; `internal/daemon/daemon.go` |
|
||||
|
||||
Run the mechanical plugin guard after changing any plugin or `*Engine`
|
||||
interface:
|
||||
|
||||
```bash
|
||||
go test ./internal/plugin -count=1
|
||||
```
|
||||
|
||||
## Apply the APPROVED TARGET
|
||||
|
||||
Apply ownership rules to migration plans and new seams. Not CURRENT until
|
||||
production wiring proves the cutover.
|
||||
|
||||
### Keep dependency direction inward
|
||||
|
||||
```text
|
||||
domain and shared application contracts <- infrastructure implementations
|
||||
^
|
||||
|
|
||||
application composition
|
||||
```
|
||||
|
||||
1. Put cohesive behaviour, vocabulary, state, commands, events, policies,
|
||||
runtime settings, and required service interfaces with its owning domain.
|
||||
2. Make infrastructure implement domain-required interfaces and translate
|
||||
external representations.
|
||||
3. Let only `internal/app` choose concrete implementations and connect domains.
|
||||
4. Keep `cmd/*` limited to process input and invoking composition.
|
||||
5. Use an owned command, event, or approved shared contract across domains.
|
||||
6. Never let one domain mutate another domain's state or call its internals.
|
||||
|
||||
Sources: `docs/architecture/organisation.md`,
|
||||
`docs/architecture/dependencies-and-contracts.md`.
|
||||
|
||||
### Separate interaction, admission, assistance, and execution
|
||||
|
||||
```text
|
||||
channel-neutral Message -> Agent turn -> optional proposed work
|
||||
-> Work Intake -> AcceptedWorkRequest -> Workflow selects version -> WorkflowExecution
|
||||
```
|
||||
|
||||
- **Messaging** owns canonical messages, conversations, branches, channel correlation, delivery.
|
||||
- **Agent** owns persistent assistant, continuity, specialisation, memory.
|
||||
- **Work Intake** owns admission, validation, routing, accepted-work-request handoff.
|
||||
- **Workflow** owns versioned definitions, steps, executions, attempts, outcomes.
|
||||
|
||||
Do not equate external issue/message with WorkflowExecution; do not let Work
|
||||
Intake create one directly.
|
||||
|
||||
Sources: `docs/architecture/migration-decisions.md`,
|
||||
`docs/architecture/agent-system.md`, `docs/architecture/messaging-and-work-intake.md`.
|
||||
|
||||
### Separate identity, Agent, conversation, and memory
|
||||
|
||||
Use immutable `IdentityID` for target attribution. Keep Identity separate from
|
||||
Agent. Four fixed memory scopes:
|
||||
|
||||
| Scope | Visibility |
|
||||
| ----------------------- | ------------------------------------------ |
|
||||
| Global shared | Shared across Archie |
|
||||
| Agent-wide | One Agent across users; private by default |
|
||||
| User-wide | One user across authorised Agents |
|
||||
| Agent-user relationship | Exactly one Agent and one user |
|
||||
|
||||
Do not use conversation branching as a fifth memory scope.
|
||||
|
||||
Sources: `docs/architecture/identity.md`, `docs/architecture/agent-system.md`,
|
||||
`docs/architecture/migration-decisions.md`.
|
||||
|
||||
### Dissolve global runtime configuration
|
||||
|
||||
Treat `internal/config` as migration source inventory:
|
||||
|
||||
- move file/env/overlay/secret decoding to `internal/infrastructure/configuration`;
|
||||
- let each domain or plugin own typed runtime settings;
|
||||
- translate external DTOs in `internal/app`;
|
||||
- never pass complete application config into a domain;
|
||||
- classify each behavioural value as invariant, runtime setting, policy value,
|
||||
derived value, or runtime state.
|
||||
|
||||
Source: `docs/architecture/configuration.md`.
|
||||
|
||||
## Place new behaviour deliberately
|
||||
|
||||
| Behaviour | Target owner/location | Decision gate |
|
||||
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
||||
| Persistent actor lifecycle and attribution | `internal/domain/identity` | Do not mix authentication/access policy into Identity. |
|
||||
| Persistent assistant behaviour and continuity | `internal/domain/agent` | Keep model/provider replaceable; do not fold Workflow into Agent. |
|
||||
| Workflow definitions, steps, executions, attempts, outcomes | `internal/domain/workflow` | Preserve version ownership and one authoritative lifecycle. |
|
||||
| Canonical messages, conversations, branches, delivery | `internal/domain/messaging` | Keep platform IDs as external correlation. |
|
||||
| Admission and deterministic routing of proposed durable work | `internal/domain/workintake` | Emit an accepted request; do not construct execution state. |
|
||||
| Generic plugin identity/discovery/compatibility/lifecycle | `internal/domain/plugin` | Keep generic contract metadata-only. |
|
||||
| Capability-specific plugin behaviour | Owning domain's typed registry/manager | Never add behaviour to `plugin.Plugin`. |
|
||||
| Broker-neutral publication/subscription mechanics | `internal/eventbus` | Keep message meaning and schemas with their domain. |
|
||||
| Shared policy evaluation/evidence mechanics | No current package. `internal/policy` was the planned location; as of 2026-09-18 policy lives inside playbook bindings (`playbooks/`, `internal/domain/eda/playbook`) and `internal/gate/`. | Keep policy vocabulary, evaluators, and consequences with consuming domain. |
|
||||
| NATS, PostgreSQL, forge, config decoding, external SDK adapters | `internal/infrastructure/<capability>` | Implement a narrow owner-defined contract; translate at boundary. |
|
||||
| Construction, cross-domain connection, startup/shutdown | `internal/app/archied` or `internal/app/agentworker` | Keep `cmd/*` thin; define health and shutdown order. |
|
||||
| Deploy assembly | `deployments/<assembly>` | Do not move application behaviour into deployment files. |
|
||||
| Unreviewed memory/tools/workspace/gate/storage/web/RPC/scheduling | **OPEN** | Run `archie-architecture-planning-campaign`. |
|
||||
|
||||
## Confront known weak points
|
||||
|
||||
| Weak point on 2026-09-18 | Required response |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
|
||||
| `TaskContext` is a mutable service bag with config, services, policy, scratch state. | Design narrow step inputs and staged removal. |
|
||||
| Workflow lifecycle split across store, daemon, workflow, gateway, worker. | Trace every writer and reader before changing status. |
|
||||
| State changes and transition history were non-atomic and `from` was advisory — **settled** in `internal/infrastructure/postgres`: `Transition` guards on the current status and writes status plus history in one transaction. | Keep every status writer behind `Transition`; do not reintroduce a raw `UPDATE tasks SET status`. |
|
||||
| In-process and container paths put orchestration on different sides of process boundary. | Decide which path survives before extending both. |
|
||||
| Identity uses strings; task uniqueness/NATS dedup omit identity. | Don't promise multi-identity ownership until canonical IDs migrate. |
|
||||
| Container RPC uses root forge/worktree, not task owner's identity. | Known trust/correctness defect — not identity-isolated. |
|
||||
| Missing `task.json` makes `archie-agent` join shared queue. | Fail closed before treating as isolated. |
|
||||
| Subprocess uses daemon user and host access. | Not a security boundary. |
|
||||
| Gateway formerly duplicated lifecycle strings, competing message contracts. | No third contract or direct lifecycle mutation path; status constants live in `internal/domain/workflow`. |
|
||||
| Global config and `IdentityConfig` combine unrelated owners. | Don't rename global structure or add `Extra` map. |
|
||||
| Memory has fixed scope requirements but OPEN final placement/migration. | Preserve scope isolation; focused design before moving. |
|
||||
| Tests can make unused/duplicate code appear legitimate. | Prove production reachability from composition. |
|
||||
|
||||
## Control every architecture-affecting change
|
||||
|
||||
| Class | Action |
|
||||
| ------------------------ | ------------------------------------------------------------------------------------------ |
|
||||
| Current-path repair | Stay inside current owner, preserve invariants. |
|
||||
| Migration slice | Record current/target owner, contracts, compatibility adapter, cutover, deletion criteria. |
|
||||
| New/changed architecture | Stop; run `archie-architecture-planning-campaign` until approved. |
|
||||
|
||||
Trace with evidence:
|
||||
|
||||
```bash
|
||||
rg -n '<constructor>|<interface>|<method>' cmd internal
|
||||
go list -deps ./cmd/archied | rg 'github.com/samcharles93/archie-core/internal/'
|
||||
gopls references path/to/file.go:<line>:<column>
|
||||
```
|
||||
|
||||
Use `gopls references` or another AST-aware reference query when interfaces,
|
||||
embedding, generated symbols, or same-named methods make text search ambiguous.
|
||||
Trace from `cmd/archied/main.go` into `internal/app/archied.Run()`; the wiring
|
||||
itself is in `internal/app/archied/bootstrap.go`.
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "Archie Architecture Contract"
|
||||
short_description: "Protect Archie load-bearing architecture decisions"
|
||||
default_prompt: "Use $archie-architecture-contract to place and review this change without violating current or target architecture."
|
||||
@@ -1,251 +0,0 @@
|
||||
---
|
||||
name: archie-build-and-env
|
||||
description: Recreate, inspect, and troubleshoot Archie Core's development, build, test, documentation, and container toolchains. Use when onboarding a checkout; diagnosing Go, Task, golangci-lint, gofumpt, Docker/Compose, NATS, GPG, cache, temporary-directory, listener, or network failures; comparing local work with repository automation; or proving which build surfaces a command actually covers. Load this before running task check in an unfamiliar or restricted environment because that gate rewrites files and omits several independent surfaces.
|
||||
---
|
||||
|
||||
# Build and verify the Archie environment
|
||||
|
||||
Recreate the environment as independently verified surfaces. Do not turn a
|
||||
passing root-module command into a claim that the tools module, documentation
|
||||
site, race detector, linter, or container images also passed.
|
||||
|
||||
All volatile observations are snapshots from **2026-09-18** (HEAD `2e1e1549`).
|
||||
|
||||
## Name the surfaces
|
||||
|
||||
| Term | Meaning here |
|
||||
| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
|
||||
| Repository root | Directory containing `go.mod`, `Taskfile.yml`, and `CLAUDE.md`. |
|
||||
| Runtime module | Root Go module `github.com/samcharles93/archie-core`. |
|
||||
| Tools module | Independent nested Go module under `tools/`. |
|
||||
| Docs | Markdown and generated JSON under `docs/`; an external Astro website renders and deploys the generated artifacts. |
|
||||
| Cold cache | Dependency cache not yet containing required modules/packages. |
|
||||
| Restricted sandbox | May allow file reads but deny loopback listeners, container engine, or writes to default caches. |
|
||||
|
||||
No root `README*` or `CONTRIBUTING*` file exists. Begin with:
|
||||
|
||||
```bash
|
||||
sed -n '1,240p' CLAUDE.md
|
||||
ls docs/architecture/
|
||||
task --list
|
||||
```
|
||||
|
||||
## Inventory requirements before installing anything
|
||||
|
||||
```bash
|
||||
go version
|
||||
go env GOTOOLCHAIN GOVERSION GOOS GOARCH CGO_ENABLED GOTMPDIR GOCACHE GOMODCACHE
|
||||
task --version; golangci-lint version; gofumpt -version
|
||||
node --version; npm --version # UI only; docs need no Node toolchain
|
||||
docker --version; docker compose version
|
||||
git --version; gpg --version
|
||||
```
|
||||
|
||||
Classify a missing command as an environment prerequisite. Bootstrap (verified
|
||||
2026-09-19): Go ≥ 1.27.0, Task ≥ 3.x, gofumpt v0.11.0, golangci-lint 2.13.2,
|
||||
Node 24.x for the `ui/` frontend.
|
||||
|
||||
`task fmt` runs `go fix` and then `golangci-lint fmt`; `task lint` uses the
|
||||
same binary and `.golangci.yml`, so its gofumpt, goimports, and gci rules have
|
||||
one owner and the writer converges the checker. Standalone `gofumpt` remains
|
||||
only for generated protobuf contracts in `tools/proto.sh`.
|
||||
|
||||
The three Yaegi secret-engine examples carry `//go:build ignore`. goimports
|
||||
cannot type-check them and deletes a genuinely used `internal/secret` import,
|
||||
so `.golangci.yml` excludes those exact files from the formatter set. Their
|
||||
runtime loading remains covered by `internal/secret/engines_test.go`.
|
||||
|
||||
| Surface | Repository declaration | Installed snapshot | Interpretation |
|
||||
| ------------- | ----------------------------------------------------- | --------------------------------------- | ------------------------------------------------------- |
|
||||
| Runtime Go | `go 1.27.0` in `go.mod` | Go 1.27.0, linux/amd64 | Requires at least declared Go level. |
|
||||
| Tools Go | `go 1.27.0` in `tools/go.mod` | Same Go 1.27.0 binary | Toolchain must satisfy both modules. |
|
||||
| Task | Taskfile schema `version: "3"` | Task 3.48.0 | Installed version is environment fact. |
|
||||
| gofumpt | Generated protobuf formatting; pinned in `Dockerfile` | v0.11.0 | Not the ordinary source formatter. |
|
||||
| golangci-lint | v2 config in `.golangci.yml`; pinned in `Dockerfile` | 2.13.2 | Owns ordinary formatting and lint checks. |
|
||||
| Node | `ui/` frontend build | 26.9.0 / npm 11.19.1 | No `engines`/`packageManager` field. Docs need no Node. |
|
||||
| Containers | Compose commands in `Taskfile.yml` | Podman-backed, unusable in this sandbox | Verify CLI, Compose plugin, daemon/socket separately. |
|
||||
|
||||
## Prepare writable caches in a restricted sandbox
|
||||
|
||||
```bash
|
||||
go env GOTMPDIR GOCACHE GOMODCACHE GOPATH
|
||||
df -T /tmp
|
||||
```
|
||||
|
||||
If any default is read-only:
|
||||
|
||||
```bash
|
||||
export ARCHIE_GOTMPDIR=/tmp/archie-core-gotmp
|
||||
export ARCHIE_GOCACHE=/tmp/archie-core-gocache
|
||||
export ARCHIE_GOMODCACHE=/tmp/archie-core-gomodcache
|
||||
export ARCHIE_GOPATH=/tmp/archie-core-gopath
|
||||
export ARCHIE_LINT_CACHE=/tmp/archie-core-golangci
|
||||
mkdir -p "$ARCHIE_GOTMPDIR" "$ARCHIE_GOCACHE" "$ARCHIE_GOMODCACHE" \
|
||||
"$ARCHIE_GOPATH" "$ARCHIE_LINT_CACHE"
|
||||
```
|
||||
|
||||
Prefix Go commands:
|
||||
|
||||
```bash
|
||||
env GOTMPDIR="$ARCHIE_GOTMPDIR" GOCACHE="$ARCHIE_GOCACHE" \
|
||||
GOMODCACHE="$ARCHIE_GOMODCACHE" GOPATH="$ARCHIE_GOPATH" \
|
||||
go test ./internal/config/... -count=1
|
||||
```
|
||||
|
||||
Populate cold cache only with network authorised:
|
||||
|
||||
```bash
|
||||
env ... go mod download; env ... go -C tools mod download
|
||||
```
|
||||
|
||||
## Recreate the root Go surface
|
||||
|
||||
```bash
|
||||
test -f go.mod && test -f cmd/archied/main.go && test -f cmd/archie-agent/main.go
|
||||
go list -m
|
||||
go build -o /tmp/archie-core-archied ./cmd/archied
|
||||
go build -o /tmp/archie-core-agent ./cmd/archie-agent
|
||||
go test ./internal/config/... -count=1
|
||||
go vet ./...
|
||||
golangci-lint run ./...
|
||||
```
|
||||
|
||||
## Understand exactly what Task runs
|
||||
|
||||
| Task | Exact effect |
|
||||
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `task fmt` | `go fix ./...`, then `golangci-lint fmt` — both may rewrite source. |
|
||||
| `task vet` | `go vet ./...` in the runtime module. |
|
||||
| `task lint` | `golangci-lint run ./...`. |
|
||||
| `task build` | Builds both commands into `bin/`. |
|
||||
| `task test` | `go test -short ./...` in the runtime module, test cache on. `task test:full` is the uncached run including wall-clock-bound tests. |
|
||||
| `task check` | `fmt` + `proto:lint` + `proto:check` + `docs:check` + `vet` + `lint` + `build` + `test` + `test:tools` + `test:ui`. |
|
||||
| `task clean` | Recursively removes `bin/`; destructive. |
|
||||
| `task docker-build` | `docker compose build agent` only. |
|
||||
|
||||
`task check` is the definitive gate but omits race tests, `task vuln`, and
|
||||
`task docker-build`. Its docs step, `docs:check`, verifies committed generated
|
||||
data and never renders anything: there is still no documentation build.
|
||||
|
||||
Two of its steps check committed artifacts rather than the build, so both fail
|
||||
on work that is correct but unstaged, and both read as a broken generator:
|
||||
|
||||
- `proto:check` regenerates, then runs `git diff --exit-code -- internal/contracts`
|
||||
and rejects untracked files there. After any `.proto` edit,
|
||||
`git add internal/contracts proto` before the gate. The failure prints the
|
||||
regenerated diff, which looks like generation produced something unexpected.
|
||||
- `ui:check` compares `ui/dist` against a fresh build of `ui/src` and fails when
|
||||
they differ. `task check` never rebuilds the bundle: run `task ui` after any
|
||||
`ui/src` change and commit the result with that change.
|
||||
|
||||
Run only in an authorised writable worktree. For a read-only ordinary-source
|
||||
preview, use `golangci-lint fmt --diff`.
|
||||
|
||||
## Verify the tools module separately
|
||||
|
||||
No `go.work`. Root `go test ./...` does not enter `tools/`.
|
||||
|
||||
```text
|
||||
module github.com/samcharles93/archie-core/tools
|
||||
replace github.com/samcharles93/archie-core => ../
|
||||
```
|
||||
|
||||
```bash
|
||||
go -C tools test -mod=readonly ./... -count=1
|
||||
```
|
||||
|
||||
`-mod=readonly` is mandatory on every `go -C tools` command. The `replace`
|
||||
forces the tools build list to satisfy the root module's requirements, so a
|
||||
root dependency bump leaves tools stale, and a writable command repairs
|
||||
`tools/go.mod` and `tools/go.sum` in place, dirtying the tree with an
|
||||
unrelated diff. Pass the flag explicitly: a global `GOFLAGS=-mod=mod` in
|
||||
`go env` beats the toolchain default. A failure here means run
|
||||
`go -C tools mod tidy` and commit that on its own. `task check` runs this via
|
||||
`task test:tools`.
|
||||
|
||||
Generate documentation to temp file:
|
||||
|
||||
```bash
|
||||
go -C tools run -mod=readonly ./docsgen --repo-root .. --out /tmp/archie-core-contracts.json
|
||||
cmp --silent docs/data/generated/contracts.json /tmp/archie-core-contracts.json
|
||||
```
|
||||
|
||||
2026-09-18 run wrote 11 schemas. The committed output was stale since
|
||||
`4b340d2b` and was regenerated the same day; `cmp` now passes. `task docs:check`
|
||||
now runs inside `task check`, so this drift fails the gate instead of waiting to
|
||||
be found by hand. `docsgen all` does not exist yet.
|
||||
|
||||
Prefer the task over the raw commands:
|
||||
|
||||
```bash
|
||||
task docs:check # non-destructive; fails loudly and names the Go type
|
||||
task docs:generate # rewrites the committed artifact; review the diff
|
||||
```
|
||||
|
||||
## Documentation needs no build
|
||||
|
||||
`docs/` is Markdown read directly in the repository, an editor, or the forge's
|
||||
file view. Nothing builds, renders, or publishes it.
|
||||
|
||||
The VitePress site (`docs/.vitepress/`, `docs/package.json`, the pnpm lockfile),
|
||||
its landing page, and `.github/workflows/docs.yml` were removed on 2026-09-12 as
|
||||
an unnecessary build step. Git no longer tracks any `docs/node_modules` entries.
|
||||
|
||||
Do not `pnpm install` under `docs/`; it has no package manifest. See
|
||||
`docs/architecture/generated-documentation.md`, "Rendering and publishing".
|
||||
|
||||
Commit `4cb0577` cleaned up accidentally committed `.gotmp`; `.gotmp/` now ignored.
|
||||
|
||||
## Treat container setup as a networked, privileged surface
|
||||
|
||||
```bash
|
||||
test -e .dockerignore || echo ".dockerignore is absent"
|
||||
rg -n '^(FROM|[[:space:]]*image:)|@latest|:latest|setup_24.x' \
|
||||
Dockerfile Dockerfile.archied docker-compose.yml
|
||||
```
|
||||
|
||||
`.dockerignore` exists (421 bytes) and excludes `.git`, `.task`, `.claude`,
|
||||
`.codex`, `.crew`, `.agents`, `.references`, `bin/`, `dist/`, `docs/`,
|
||||
`node_modules/`, root-built `archied`/`archie-agent`, and local config. Both
|
||||
Dockerfiles still run `COPY . .` on top of it. Floating inputs: Go builder tags
|
||||
omit patch/digest; Ubuntu base images omit digests; agent installs multiple
|
||||
`@latest` Go tools; Node from moving `setup_24.x` channel.
|
||||
|
||||
`task docker-build` needs registry/network and functioning Compose.
|
||||
`task docker-up` starts the Compose-managed NATS service and binds ports
|
||||
4222/8222. The host daemon and its Docker-socket access are outside Compose.
|
||||
|
||||
## Separate environment failures from code failures
|
||||
|
||||
| Signature | Classify and branch |
|
||||
| ------------------------------------------------------------------- | ------------------------------------------------------------ |
|
||||
| `go: creating work dir: mkdir /work/tmp/...: read-only file system` | Set task-specific `GOTMPDIR`. |
|
||||
| `open .../.cache/go-build/...: read-only file system` | Set writable `GOCACHE`. |
|
||||
| `open .../pkg/mod/cache/...tmp: read-only file system` | Set writable `GOMODCACHE` and `GOPATH`. |
|
||||
| `listen ...: socket: operation not permitted` | Re-run on host with loopback sockets. |
|
||||
| `Unable to start NATS Server in Go Routine` after ~10s | Test whether local listeners permitted. |
|
||||
| `cannot auto-sign commit` | Ambient `commit.gpgSign=true`; fixtures set `gpgsign=false`. |
|
||||
| `EAI_AGAIN` for `registry.npmjs.org` | Dependency retrieval failed. |
|
||||
| `Podman configuration ... read-only file system` | Container backend cannot initialise. |
|
||||
| `TestRunWrapsExternalCommand ... Run() = "\n"` | Focused code failure in `internal/skillscript`. |
|
||||
|
||||
For hermetic test diagnosis:
|
||||
|
||||
```bash
|
||||
env GIT_CONFIG_GLOBAL=/dev/null go test ./internal/worktree/... ./internal/worktreerpc/... -count=1
|
||||
```
|
||||
|
||||
## Use the complete validation matrix
|
||||
|
||||
| Evidence | Command | Current snapshot |
|
||||
| --------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Focused Go behaviour | `go test ./pkg/... -run '^TestName$' -count=1 -v` | Use first. |
|
||||
| Root unit/integration suite | `go test ./... -count=1` | Restricted sandbox fails listener-dependent packages. |
|
||||
| Root race suite | `go test -race ./... -count=1` | Not run by `task check`. |
|
||||
| Vet | `go vet ./...` | Passed on 2026-09-18. |
|
||||
| Lint | `golangci-lint run ./...` | Not re-run on 2026-09-18; a focused `--enable-only=dupl ./internal/...` run reported 0 issues. Re-run before quoting a total. |
|
||||
| Build | `go build -o /tmp/... ./cmd/archied` and `cmd/archie-agent` | Both passed on 2026-09-18. |
|
||||
| Tools tests | `go -C tools test -mod=readonly ./... -count=1` | Passed on 2026-09-18. |
|
||||
| Generated contract parity | Temp docsgen output + `cmp --silent` | Passed for 11 schemas on 2026-09-18, after regenerating a file stale since `4b340d2b`. |
|
||||
| Container build | `task docker-build` | Not verified in restricted environment. |
|
||||
| Repository gate | `task check` | See `archie-diagnostics-and-tooling` for the dated snapshot. |
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "Archie Build and Environment"
|
||||
short_description: "Recreate and verify the Archie toolchain"
|
||||
default_prompt: "Use $archie-build-and-env to recreate a clean Archie development environment and verify every build surface."
|
||||
@@ -1,232 +0,0 @@
|
||||
---
|
||||
name: archie-codebase-discovery
|
||||
description: "Trace Archie behaviour and blast radius through Go source, types, state, persistence, transports, consumers, tests, configuration, production composition, and target architecture. Load before changing or planning a non-trivial feature, refactor, config field, interface, persistence path, workflow, channel, plugin, or agent execution path; also load to investigate duplicate behaviour, hidden dead code, constructor bypasses, package dependencies, decoded-but-unwired configuration, or uncertainty about what a symbol actually affects."
|
||||
---
|
||||
|
||||
# Discover the Archie codebase
|
||||
|
||||
Use evidence from the current checkout to explain a behaviour before changing it.
|
||||
Volatile tool facts below were verified on **2026-09-18**.
|
||||
|
||||
**Composition roots**: `cmd/archied/main.go` (thin dispatcher) →
|
||||
`internal/app/archied.Run()`, and `internal/app/agentworker` (invoked by
|
||||
`cmd/archie-agent/main.go`). Do not treat `cmd/*` as the wiring site.
|
||||
**Production wiring**: a path selected by a shipped entrypoint — not a
|
||||
constructor, decoder, or passing unit test. **State owner**: component with
|
||||
authority to validate and persist a state transition.
|
||||
|
||||
## Establish a reproducible baseline
|
||||
|
||||
```sh
|
||||
go version; go env GOMOD GOWORK GOOS GOARCH
|
||||
gopls version; golangci-lint version; staticcheck -version
|
||||
```
|
||||
|
||||
As of 2026-09-18: Go 1.27.0, gopls 0.23.0, golangci-lint 2.13.2,
|
||||
staticcheck 2026.2.1. Use `gopls call_hierarchy` (no `go tool callgraph`;
|
||||
`go tool` lists only asm, cgo, compile, cover, fix, link, preprofile, vet).
|
||||
|
||||
Writable caches when defaults are read-only:
|
||||
|
||||
```sh
|
||||
export GOCACHE="${TMPDIR:-/tmp}/archie-discovery-gocache"
|
||||
export GOLANGCI_LINT_CACHE="${TMPDIR:-/tmp}/archie-discovery-lint"
|
||||
export GOTMPDIR="${TMPDIR:-/tmp}"
|
||||
export GOPROXY=off GOFLAGS=-mod=readonly
|
||||
```
|
||||
|
||||
Module boundaries (root and `tools/` are separate):
|
||||
|
||||
```sh
|
||||
find . -name go.mod -not -path './.git/*' -not -path './node_modules/*'
|
||||
go list -m -f '{{.Path}} {{.GoVersion}}'
|
||||
go -C tools list -mod=readonly -m -f '{{.Path}} {{.GoVersion}}'
|
||||
```
|
||||
|
||||
## Build the behaviour trace
|
||||
|
||||
Write: behaviour, observable input, expected output, state that may change, modes.
|
||||
|
||||
| Step | Find | Required evidence |
|
||||
| ---: | ------------------- | ------------------------------------------------------------------------ |
|
||||
| 1 | Entrypoint | `main`, handler, poller, RPC subject, or tool registration |
|
||||
| 2 | Construction | Constructor and every direct struct literal |
|
||||
| 3 | Contract | Interface, wire type, command, event, or public method crossed |
|
||||
| 4 | Implementation | All type-valid implementations, selected per mode |
|
||||
| 5 | State owner | Function validating transition, owning concurrency/transaction rules |
|
||||
| 6 | Persistence | Store adapter, schema/key/document, serialisation, reload/recovery |
|
||||
| 7 | Event/transport | Publish/send and subscribe/receive, subject/framing, timeout, retry, ack |
|
||||
| 8 | Consumer | Callers and downstream readers |
|
||||
| 9 | Tests | Unit, integration, contract, architecture, production-composition |
|
||||
| 10 | Configuration | Decode, default, validation, normalisation, composition-root consumption |
|
||||
| 11 | Target architecture | Current-to-target mapping in `docs/prds/`; label gaps |
|
||||
|
||||
Start at these verified anchors:
|
||||
|
||||
| Concern | Current anchor |
|
||||
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Resident daemon | `cmd/archied/main.go` → `internal/app/archied.Run()` (`internal/app/archied/main.go`) → `daemon.Daemon` |
|
||||
| Sandboxed worker | `cmd/archie-agent/main.go` → `internal/app/agentworker/`; NATS boundary in `internal/infrastructure/agenttransport/nats/` |
|
||||
| Task orchestration | `internal/daemon/daemon.go`, `internal/domain/workflow/` |
|
||||
| Task contracts | `internal/domain/storecontract/storecontract.go` (`TaskStore`) |
|
||||
| Production task persistence | `internal/infrastructure/postgres/`; built in `internal/app/archied/state_store.go` |
|
||||
| RPC split | `internal/{taskrun,natsrpc,forgerpc,worktreerpc}/` plus `internal/infrastructure/staterpc/` (gRPC State Store) |
|
||||
| Chat and channels | `internal/gateway/`, `internal/channels/` |
|
||||
| Configuration | `internal/config/`, `internal/infrastructure/configuration/`, `config.example.toml`, `deployments/*.toml` |
|
||||
| Target map | `docs/prds/01-project-management.md` and linked `docs/architecture/*.md` |
|
||||
|
||||
## Use syntax, type, and call evidence
|
||||
|
||||
### Map packages before reading files
|
||||
|
||||
```sh
|
||||
go list -f '{{.ImportPath}}|go={{join .GoFiles ","}}|tests={{join .TestGoFiles ","}}' ./internal/infrastructure/postgres
|
||||
go list -json ./internal/infrastructure/postgres
|
||||
.agents/skills/archie-codebase-discovery/scripts/package-edges.sh ./internal/...
|
||||
```
|
||||
|
||||
### Resolve symbols with gopls
|
||||
|
||||
1-indexed `file:line:column`:
|
||||
|
||||
```sh
|
||||
gopls symbols internal/domain/storecontract/storecontract.go
|
||||
gopls definition cmd/archied/main.go:27:14
|
||||
gopls references -d internal/domain/storecontract/storecontract.go:33:2
|
||||
gopls implementation internal/domain/storecontract/storecontract.go:33:2
|
||||
gopls call_hierarchy internal/domain/storecontract/storecontract.go:33:2
|
||||
go doc ./internal/domain/storecontract.TaskStore
|
||||
go test ./internal/infrastructure/postgres -list '.'
|
||||
```
|
||||
|
||||
### Generate AST candidates for construction
|
||||
|
||||
```sh
|
||||
.agents/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.sh Daemon .
|
||||
.agents/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.sh -tests Task .
|
||||
```
|
||||
|
||||
Confirms candidates with `gopls definition` or `gopls references`. Pass
|
||||
`-tests` to expose test-only construction.
|
||||
|
||||
## Run focused discovery recipes
|
||||
|
||||
### Find duplicate behaviour paths
|
||||
|
||||
```sh
|
||||
golangci-lint run --enable-only=dupl ./internal/...
|
||||
rg -n 'Transition\(|PublishTask\(|ClaimNext\(|StatusWaitingHuman' cmd internal
|
||||
```
|
||||
|
||||
Trace each candidate to entrypoint and state owner. `dupl` finds similar syntax,
|
||||
not two different implementations of one responsibility.
|
||||
|
||||
### Find unused-but-compiled code
|
||||
|
||||
```sh
|
||||
staticcheck -checks=U1000 ./internal/...
|
||||
```
|
||||
|
||||
For every suspect: `gopls references -d`; search init, reflection/Yaegi, tags,
|
||||
RPC subjects, plugin manifests, string dispatch; check build tags/OS files;
|
||||
search both composition roots. `U1000` does not prove exported/reflection/wire
|
||||
targets are dead.
|
||||
|
||||
### Find interface implementations
|
||||
|
||||
```sh
|
||||
gopls implementation
|
||||
rg -n 'var _ .*=' --glob '*.go' cmd internal
|
||||
```
|
||||
|
||||
Trace which implementation the composition root selects for each mode.
|
||||
|
||||
### Find struct-field consumers
|
||||
|
||||
`gopls references -d` on field declaration, not common name. Trace assignments
|
||||
and reads separately. Follow `ForTask`/`ToConfig` copies. Check JSON/TOML/YAML
|
||||
tags. Compare production and `_test.go` references.
|
||||
|
||||
### Detect constructor bypasses
|
||||
|
||||
Run `scan-go-type-syntax.sh Type .`. Inspect struct literals outside owning
|
||||
package. Compare validation/defaulting in constructors with direct literals.
|
||||
Use `gopls references` on constructor and type.
|
||||
|
||||
### Prove package dependency direction
|
||||
|
||||
```sh
|
||||
.agents/skills/archie-codebase-discovery/scripts/package-edges.sh ./internal/...
|
||||
go list -deps -json <pattern>
|
||||
```
|
||||
|
||||
### Find decoded-but-unused configuration
|
||||
|
||||
Prove: `file/key → decoder → default → validation → normalisation/copy →
|
||||
composition-root read → concrete component → observable behaviour`.
|
||||
|
||||
```sh
|
||||
rg -n 'toml:"|yaml:"|json:"' internal/config
|
||||
rg -n 'Resolve|Overlay|Dir|finalize|ForTask|ToConfig' internal/infrastructure/configuration internal/app/archied
|
||||
gopls references -d <exact-field>
|
||||
```
|
||||
|
||||
Decoding lives in `internal/infrastructure/configuration`, not `internal/config`.
|
||||
`configuration.New(log)` returns a `Loader`; the composition root in
|
||||
`internal/app/archied/bootstrap.go` calls `Loader.Resolve` (with `Loader.Overlay`
|
||||
and `Loader.Dir` for overlay/`conf.d` inputs). There is no `config.Load` or
|
||||
`config.LoadDir`.
|
||||
|
||||
### Prove production composition
|
||||
|
||||
1. Start at `internal/app/archied/main.go` (`Run`), entered from
|
||||
`cmd/archied/main.go`.
|
||||
2. Record config condition per branch.
|
||||
3. Follow concrete construction into `daemon.Daemon` and gateway start.
|
||||
4. For container/NATS behaviour, trace `cmd/archie-agent/main.go` into
|
||||
`internal/app/agentworker` and `internal/infrastructure/agenttransport/nats`.
|
||||
5. Trace both sides of every RPC/transport and error/timeout paths.
|
||||
6. Read contract/architecture tests.
|
||||
7. Confirm deploy inputs in Compose and CI.
|
||||
|
||||
### Trace persistence
|
||||
|
||||
Treat `internal/domain/storecontract` as the application contract and
|
||||
`internal/infrastructure/postgres` as the production adapter behind it; the
|
||||
schema is `internal/infrastructure/postgres/migrations/` and the queries are
|
||||
sqlc-generated from `queries/`.
|
||||
|
||||
```sh
|
||||
gopls implementation internal/domain/storecontract/storecontract.go:33:2
|
||||
rg -n 'CREATE TABLE|CREATE INDEX' internal/infrastructure/postgres/migrations
|
||||
```
|
||||
|
||||
## Reject false confidence
|
||||
|
||||
| Weak evidence | Why it fails | Required correction |
|
||||
| ---------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- |
|
||||
| One `rg` result | Misses interface dispatch, aliases, generated registration, reflection | Use gopls, AST candidates, package edges, composition |
|
||||
| Green unit test | May bypass config, lifecycle, transport | Add composition/contract/integration evidence |
|
||||
| Fake client and server agree | Both mirror same wrong framing/subject/state assumption | Compare independent spec or real boundary fixture |
|
||||
| High coverage | Does not establish ownership, maintainability, mode selection | Trace authority and production selection |
|
||||
| Constructor exists | Does not prove callers use it | Find struct literals and type-aware references |
|
||||
| Config field decodes | Does not prove executable reads it | Complete config-to-observable chain |
|
||||
| Target PRD says it | Not necessarily current code | Cite current implementation and label gap |
|
||||
|
||||
## Produce the discovery handoff
|
||||
|
||||
1. **Behaviour trace:** path:line, symbol, current responsibility per traversal step.
|
||||
2. **Mode matrix:** mode/config branch → concrete implementation → state store
|
||||
→ transport → consumer.
|
||||
3. **State and authority:** owner, copies, persistence, transition rules, recovery.
|
||||
4. **Blast radius:** callers, consumers, tests, config, deploy wiring, docs,
|
||||
compatibility paths.
|
||||
5. **Duplication/deprecation ledger:** each candidate, live/dead evidence,
|
||||
replacement, objective removal gate.
|
||||
6. **Current-to-target gap:** current fact, target PRD, migration implication.
|
||||
7. **Unknowns:** exact command, output/blocker, next evidence needed.
|
||||
|
||||
Do not propose implementation until the trace answers: what entrypoint selects
|
||||
this path, which component owns state, which parallel/older path the feature
|
||||
replaces, which production modes and persisted data must remain compatible,
|
||||
which evidence would falsify current understanding.
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "Archie Codebase Discovery"
|
||||
short_description: "Trace Archie behavior from entrypoint to production"
|
||||
default_prompt: "Use $archie-codebase-discovery to trace this behavior through production wiring before proposing a change."
|
||||
@@ -1,36 +0,0 @@
|
||||
#!/bin/sh
|
||||
set -eu
|
||||
|
||||
if [ "$#" -gt 1 ]; then
|
||||
printf '%s\n' "usage: $0 [go-package-pattern]" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
command -v go >/dev/null 2>&1 || {
|
||||
printf '%s\n' "error: go is required" >&2
|
||||
exit 127
|
||||
}
|
||||
|
||||
pattern=${1:-./...}
|
||||
cache_root=${ARCHIE_DISCOVERY_CACHE:-"${TMPDIR:-/tmp}/archie-codebase-discovery"}
|
||||
mkdir -p "$cache_root/go-build" "$cache_root/tmp"
|
||||
|
||||
export GOCACHE="$cache_root/go-build"
|
||||
export GOTMPDIR="$cache_root/tmp"
|
||||
export GOPROXY=off
|
||||
export GOFLAGS=-mod=readonly
|
||||
|
||||
module_path=$(go list -m -f '{{.Path}}')
|
||||
|
||||
go list -f '{{.ImportPath}}{{range .Imports}}{{printf "\t%s" .}}{{end}}' "$pattern" |
|
||||
awk -F ' ' -v module="$module_path" '
|
||||
{
|
||||
from = $1
|
||||
for (i = 2; i <= NF; i++) {
|
||||
if ($i == module || index($i, module "/") == 1) {
|
||||
printf "%s -> %s\n", from, $i
|
||||
}
|
||||
}
|
||||
}
|
||||
' |
|
||||
LC_ALL=C sort -u
|
||||
@@ -1,176 +0,0 @@
|
||||
// Command scan-go-type-syntax reports syntax-level construction candidates for
|
||||
// a named Go type. It deliberately uses only the standard library and never
|
||||
// writes to the inspected tree.
|
||||
package main
|
||||
|
||||
import (
|
||||
"bufio"
|
||||
"flag"
|
||||
"fmt"
|
||||
"go/ast"
|
||||
"go/parser"
|
||||
"go/token"
|
||||
"io/fs"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"sort"
|
||||
"strings"
|
||||
)
|
||||
|
||||
type finding struct {
|
||||
path string
|
||||
line int
|
||||
column int
|
||||
kind string
|
||||
detail string
|
||||
}
|
||||
|
||||
func main() {
|
||||
includeTests := flag.Bool("tests", false, "include *_test.go files")
|
||||
flag.Usage = func() {
|
||||
fmt.Fprintf(flag.CommandLine.Output(), "usage: %s [-tests] TypeName [root]\n", os.Args[0])
|
||||
flag.PrintDefaults()
|
||||
}
|
||||
flag.Parse()
|
||||
if flag.NArg() < 1 || flag.NArg() > 2 {
|
||||
flag.Usage()
|
||||
os.Exit(2)
|
||||
}
|
||||
|
||||
typeName := flag.Arg(0)
|
||||
root := "."
|
||||
if flag.NArg() == 2 {
|
||||
root = flag.Arg(1)
|
||||
}
|
||||
if !token.IsIdentifier(typeName) {
|
||||
fmt.Fprintf(os.Stderr, "error: %q is not a Go identifier\n", typeName)
|
||||
os.Exit(2)
|
||||
}
|
||||
|
||||
results, err := scan(root, typeName, *includeTests)
|
||||
if err != nil {
|
||||
fmt.Fprintf(os.Stderr, "error: %v\n", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
|
||||
out := bufio.NewWriter(os.Stdout)
|
||||
defer out.Flush()
|
||||
fmt.Fprintln(out, "kind\tlocation\tdetail")
|
||||
for _, result := range results {
|
||||
fmt.Fprintf(out, "%s\t%s:%d:%d\t%s\n",
|
||||
result.kind, result.path, result.line, result.column, result.detail)
|
||||
}
|
||||
}
|
||||
|
||||
func scan(root, typeName string, includeTests bool) ([]finding, error) {
|
||||
fset := token.NewFileSet()
|
||||
var results []finding
|
||||
|
||||
err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
|
||||
if walkErr != nil {
|
||||
return walkErr
|
||||
}
|
||||
if entry.IsDir() {
|
||||
if path == root {
|
||||
return nil
|
||||
}
|
||||
name := entry.Name()
|
||||
if strings.HasPrefix(name, ".") || name == "node_modules" ||
|
||||
name == "vendor" || name == "bin" {
|
||||
return filepath.SkipDir
|
||||
}
|
||||
return nil
|
||||
}
|
||||
if filepath.Ext(path) != ".go" {
|
||||
return nil
|
||||
}
|
||||
if !includeTests && strings.HasSuffix(path, "_test.go") {
|
||||
return nil
|
||||
}
|
||||
|
||||
file, err := parser.ParseFile(fset, path, nil, 0)
|
||||
if err != nil {
|
||||
return fmt.Errorf("parse %s: %w", path, err)
|
||||
}
|
||||
|
||||
ast.Inspect(file, func(node ast.Node) bool {
|
||||
switch node := node.(type) {
|
||||
case *ast.TypeSpec:
|
||||
if node.Name.Name == typeName {
|
||||
results = appendFinding(results, fset, node.Name.Pos(),
|
||||
path, "declaration", "type "+node.Name.Name)
|
||||
}
|
||||
case *ast.CompositeLit:
|
||||
if matchesType(node.Type, typeName) {
|
||||
results = appendFinding(results, fset, node.Type.Pos(),
|
||||
path, "literal", "direct composite literal of "+typeName)
|
||||
}
|
||||
case *ast.FuncDecl:
|
||||
if returnsType(node.Type.Results, typeName) {
|
||||
results = appendFinding(results, fset, node.Name.Pos(),
|
||||
path, "returns-type", "func "+node.Name.Name)
|
||||
}
|
||||
}
|
||||
return true
|
||||
})
|
||||
return nil
|
||||
})
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
sort.Slice(results, func(i, j int) bool {
|
||||
left, right := results[i], results[j]
|
||||
if left.path != right.path {
|
||||
return left.path < right.path
|
||||
}
|
||||
if left.line != right.line {
|
||||
return left.line < right.line
|
||||
}
|
||||
if left.column != right.column {
|
||||
return left.column < right.column
|
||||
}
|
||||
return left.kind < right.kind
|
||||
})
|
||||
return results, nil
|
||||
}
|
||||
|
||||
func appendFinding(results []finding, fset *token.FileSet, pos token.Pos, path, kind, detail string) []finding {
|
||||
position := fset.Position(pos)
|
||||
return append(results, finding{
|
||||
path: filepath.ToSlash(path),
|
||||
line: position.Line,
|
||||
column: position.Column,
|
||||
kind: kind,
|
||||
detail: detail,
|
||||
})
|
||||
}
|
||||
|
||||
func returnsType(fields *ast.FieldList, typeName string) bool {
|
||||
if fields == nil {
|
||||
return false
|
||||
}
|
||||
for _, field := range fields.List {
|
||||
if matchesType(field.Type, typeName) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
func matchesType(expr ast.Expr, typeName string) bool {
|
||||
switch expr := expr.(type) {
|
||||
case *ast.Ident:
|
||||
return expr.Name == typeName
|
||||
case *ast.SelectorExpr:
|
||||
return expr.Sel.Name == typeName
|
||||
case *ast.StarExpr:
|
||||
return matchesType(expr.X, typeName)
|
||||
case *ast.IndexExpr:
|
||||
return matchesType(expr.X, typeName)
|
||||
case *ast.IndexListExpr:
|
||||
return matchesType(expr.X, typeName)
|
||||
default:
|
||||
return false
|
||||
}
|
||||
}
|
||||
@@ -1,13 +0,0 @@
|
||||
#!/bin/sh
|
||||
set -eu
|
||||
|
||||
script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
|
||||
cache_root=${ARCHIE_DISCOVERY_CACHE:-"${TMPDIR:-/tmp}/archie-codebase-discovery"}
|
||||
mkdir -p "$cache_root/go-build" "$cache_root/tmp"
|
||||
|
||||
export GOCACHE="$cache_root/go-build"
|
||||
export GOTMPDIR="$cache_root/tmp"
|
||||
export GOPROXY=off
|
||||
export GOFLAGS=-mod=readonly
|
||||
|
||||
exec go run "$script_dir/scan-go-type-syntax.go" "$@"
|
||||
@@ -1,61 +0,0 @@
|
||||
#!/bin/sh
|
||||
set -u
|
||||
|
||||
usage() {
|
||||
printf '%s\n' "usage: $0 file.go:line:column" >&2
|
||||
exit 2
|
||||
}
|
||||
|
||||
[ "$#" -eq 1 ] || usage
|
||||
position=$1
|
||||
|
||||
command -v go >/dev/null 2>&1 || {
|
||||
printf '%s\n' "error: go is required" >&2
|
||||
exit 127
|
||||
}
|
||||
command -v gopls >/dev/null 2>&1 || {
|
||||
printf '%s\n' "error: gopls is required" >&2
|
||||
exit 127
|
||||
}
|
||||
|
||||
case "$position" in
|
||||
*.go:[1-9]*:[1-9]*) ;;
|
||||
*) usage ;;
|
||||
esac
|
||||
|
||||
cache_root=${ARCHIE_DISCOVERY_CACHE:-"${TMPDIR:-/tmp}/archie-codebase-discovery"}
|
||||
mkdir -p "$cache_root/go-build" "$cache_root/xdg" "$cache_root/tmp" || exit 1
|
||||
|
||||
export GOCACHE="$cache_root/go-build"
|
||||
export XDG_CACHE_HOME="$cache_root/xdg"
|
||||
export GOTMPDIR="$cache_root/tmp"
|
||||
export GOPROXY=off
|
||||
export GOFLAGS=-mod=readonly
|
||||
|
||||
gomod=$(go env GOMOD)
|
||||
if [ "$gomod" = "/dev/null" ] || [ -z "$gomod" ]; then
|
||||
printf '%s\n' "error: run from inside a Go module" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
run_query() {
|
||||
label=$1
|
||||
shift
|
||||
printf '\n== %s ==\n' "$label"
|
||||
if output=$(gopls "$@" 2>&1); then
|
||||
printf '%s\n' "$output"
|
||||
return 0
|
||||
else
|
||||
printf '%s\n' "$output"
|
||||
printf '%s\n' "(query is not applicable at this position, or failed)"
|
||||
return 1
|
||||
fi
|
||||
}
|
||||
|
||||
successful=0
|
||||
run_query "definition" definition "$position" && successful=$((successful + 1))
|
||||
run_query "references (including declaration)" references -d "$position" && successful=$((successful + 1))
|
||||
run_query "implementations" implementation "$position" && successful=$((successful + 1))
|
||||
run_query "call hierarchy" call_hierarchy "$position" && successful=$((successful + 1))
|
||||
|
||||
[ "$successful" -gt 0 ]
|
||||
@@ -1,266 +0,0 @@
|
||||
---
|
||||
name: archie-config-and-flags
|
||||
description: Trace, add, rename, deprecate, or debug Archie configuration and command-line flags from external input through defaults, validation, overlays, environment and secret handling, worker snapshots, deployment passthrough, and the production consumer. Use for internal/config, config.example.toml, deployments/*.toml, docker-compose.yml, archied or archie-agent flags, multi-identity settings, mode-parity questions, and reports of a setting that parses but has no effect.
|
||||
---
|
||||
|
||||
# Trace Archie configuration and flags
|
||||
|
||||
Treat configuration as a dataflow, not as a struct inventory. Prove every
|
||||
claimed setting has an input, normalisation path, composition seam, and runtime
|
||||
consumer.
|
||||
|
||||
Current evidence date: **2026-09-18** for the matrix below. Entries added later
|
||||
carry their own date inline.
|
||||
|
||||
Use these status terms exactly:
|
||||
|
||||
| Status | Meaning |
|
||||
| ------------------------------- | ---------------------------------------------------------------------------------- |
|
||||
| **production-wired** | A real entrypoint decodes or accepts the value and a runtime consumer uses it. |
|
||||
| **partially-wired** | Some modes, scopes, or fields consume it, but parity is incomplete. |
|
||||
| **test/library-only** | An API and tests exist, but no current binary selects it. |
|
||||
| **decoded-but-unwired** | Decoding/defaulting succeeds, but no production consumer uses the effective value. |
|
||||
| **external-production-unknown** | The repository does not contain the deployed effective value. |
|
||||
|
||||
Never upgrade a status merely because decoding tests pass.
|
||||
|
||||
## Trace one setting before editing it
|
||||
|
||||
1. Find every external spelling, Go field, flag, environment name, example, and
|
||||
deployment reference.
|
||||
2. Identify the selected loader or flag set.
|
||||
3. Read `finalize` and any consumer-side defaults.
|
||||
4. Follow copies across `ForTask`, `ToConfig`, NATS messages, subprocess
|
||||
env selection, container env construction, and identity overlays.
|
||||
5. Find the production composition site and final behaviour-changing read.
|
||||
6. Find tests for decoding, defaulting, invalid input, production composition,
|
||||
and mode parity.
|
||||
7. Check `config.example.toml`, `deployments/*.toml`, `docker-compose.yml`, and
|
||||
deployment environment passthrough.
|
||||
8. Assign one status from the table above.
|
||||
|
||||
```bash
|
||||
rg -n 'Resolve|Overlay|Dir|ForTask|ToConfig|flag\.' \
|
||||
internal/infrastructure/configuration internal/config internal/app/archied cmd/archie-agent
|
||||
rg -n 'FIELD_NAME|external_key|ENV_NAME' \
|
||||
--glob '*.go' --glob '*.toml' --glob '*.yml' --glob '*.yaml' .
|
||||
```
|
||||
|
||||
## Select the real input path
|
||||
|
||||
| Input path | Current behaviour | Status |
|
||||
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
|
||||
| `archied -config PATH` | Defaults to `$XDG_CONFIG_HOME/archie/config.toml`, or `$HOME/.config/archie/config.toml`; `internal/app/archied/bootstrap.go` builds `configuration.New(log)` and calls `Loader.Resolve`. | production-wired |
|
||||
| `archied -config-overlay PATH` | Resolves a file or directory overlay through the same loader. Omitted overlay fields retain base values. This is the only overlay: the dashboard runtime overlay and its SQLite store were deleted when the control plane took over settings writes. | production-wired |
|
||||
| `configuration.Loader.Dir(base, overlay)` | Supports main YAML/TOML plus feature YAML and `conf.d`; no current entrypoint calls it. | test/library-only |
|
||||
| `config.Load(path)`, `config.LoadDir(...)` | Removed. The old `internal/config` package-level helpers no longer exist; decoding is `Loader`-based. | not applicable |
|
||||
| `config.example.toml` | Load-tested example, not a deployed configuration. | test/library-only |
|
||||
| `deployments/docker-nats-stack.toml` | Complete host-daemon configuration for the Compose-managed NATS service. It is copied into the operator's config directory; Compose does not mount it. | supported-example |
|
||||
| Operator config and environment | Lives outside the repository; contents are deployment-specific. | external-production-unknown |
|
||||
|
||||
Both TOML and YAML decoding are non-strict at the field level. Add explicit
|
||||
compatibility and typo tests; never use "the file loaded" as evidence that a
|
||||
key took effect.
|
||||
|
||||
A registered service client always resolves to a non-empty target, so
|
||||
`Services.Get(name).Target != ""` proves nothing. `RegisterService` in
|
||||
`internal/config/servicespec.go` supplies the fallback (`127.0.0.1:9090` for
|
||||
the State Store, `127.0.0.1:8585` for the Gateway), which means a guard written
|
||||
as "only dial when configured" dials always, and a test that sets no target
|
||||
reaches for a real process on the developer's machine. Gate on an explicit
|
||||
flag or on the dial succeeding, and give a binary its own
|
||||
`-<service>-target` flag so tests can point it at a fake.
|
||||
|
||||
## Inventory CLI flags
|
||||
|
||||
### Public binaries
|
||||
|
||||
| Binary | Flag | Default and effect |
|
||||
| -------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `archied` | `-config PATH` | Computed config path described above. |
|
||||
| `archied` | `-config-overlay PATH` | Empty; overlay only fields explicitly present in second TOML. |
|
||||
| `archied` | `-once` | `false`; run one poll/process cycle and exit. |
|
||||
| `archied` | `-requeue ID` | `0`; values greater than zero requeue one parked/waiting task, then exit unless `-once` also set. |
|
||||
| `archie-agent` | `-nats-url URL` | Empty; takes precedence over `NATS_URL`. Missing both is fatal. |
|
||||
| `archie-agent` | `-consumer NAME` | `archie-agent`; names the JetStream durable consumer. |
|
||||
| both | `-quickchecks N` | Incidental flag registered by `github.com/traefik/yaegi/stdlib` importing `testing/quick`; default `100`. Treat as unowned candidate defect. |
|
||||
|
||||
The standalone agent always reads its token from `NATS_TOKEN`; there is no
|
||||
token flag.
|
||||
|
||||
### Internal codesearch helper
|
||||
|
||||
`archied workspace-codesearch` bypasses daemon configuration before normal flag
|
||||
parsing:
|
||||
|
||||
| Subcommand | Required flags | Optional flags |
|
||||
| ------------ | ---------------------- | ------------------------------- |
|
||||
| `build` | `--root`, `--index` | none |
|
||||
| `candidates` | `--index`, `--pattern` | `--literal`, `--case-sensitive` |
|
||||
|
||||
Do not expose these helper flags as daemon settings.
|
||||
|
||||
## Read the current wiring matrix
|
||||
|
||||
### Root daemon and capability settings
|
||||
|
||||
| Keys | Default, validation, and consumer | Status |
|
||||
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
|
||||
| `work_dir`, `state_dir` | Derive from `$XDG_DATA_HOME/archie`, else `$HOME/.local/share/archie`; explicit `~` paths are home-expanded. `state_dir` holds the embedded NATS store and endpoint file, task logs and the readiness disk target. | production-wired |
|
||||
| `skills_dir` | Empty falls back to `work_dir` for startup workflow registry. Also the skills store `kitrun.Launcher` mounts read-only at a Kit's `agent-skills@1` path, read live per launch; empty withholds the mount. | partially-wired |
|
||||
| `plugin_dir` | Empty disables daemon plugin loading; configured directory loaded in `internal/app/archied`. | production-wired |
|
||||
| `poll_interval` | Default `60s`; root poll loop uses it, identities may override only interval. | production-wired |
|
||||
| `label` | No default or validation; used for `dispatch.trigger = "label"` or `"either"`. | production-wired |
|
||||
| `max_retries` | Default `3`; repository value greater than zero overrides. | production-wired |
|
||||
| `bot_user`, `bot_email` | Single-identity requires `bot_user`; email defaults by forge type. | production-wired |
|
||||
| `forge.type`, `host`, `token` | Type defaults `github`, host defaults `https://github.com`; only `github` and `gitea` validate. | production-wired |
|
||||
| `dispatch.trigger` | Default `assignee`; validates `assignee`, `label`, or `either`. | production-wired |
|
||||
| `dispatch.ack_reaction` | Default `eyes`; case-insensitive `off` normalises to empty. | production-wired |
|
||||
| `dispatch.labels.*` | Missing keys default independently to `agent:*`. | production-wired |
|
||||
| `models.<role>` | Workflow stages read requested role then fall back to `builder`; triage judge falls back `triage` to `planner`. | production-wired |
|
||||
| `providers.<name>.class`, `api_key_env`, `base_url` | Builds ai-sdk catalogue. `base_url` rejects parse errors, userinfo, query, and fragment. | production-wired |
|
||||
| `budgets.max_steps`, `max_tokens`, `wall_clock`, `gate_max_failures` | No loader defaults; `Budgets` documents zero as disabling. | production-wired |
|
||||
| `review.precision_gate`, `review.approve_before_post` | 2026-10-02: one control-plane resource `review-settings` (`internal/app/controlplane/review_settings.go`), seeded from `[review]`; the stored document outranks the file, layers field-by-field into `cfg.Review` (`runtimeConfigFrom`), and is watched live (`archie/control_plane.go`). Reaches a run through `Daemon.configFor` → `ForTask` → `TaskContext.Cfg`; the dashboard writes it on the Review settings page. | production-wired |
|
||||
| `diff_cap_lines` | Zero replaced by `400` in `finalize`; `StageDiffCap` treats `<= 0` as disabled. TOML zero cannot disable; negative value does. | production-wired |
|
||||
| `web.listen` | Empty becomes `127.0.0.1:8484`; literal `off` disables. No authentication. | production-wired |
|
||||
| `notify.webhook` | Empty disables; feasibility workflow POSTs human-decision notifications when set. | production-wired |
|
||||
| `nats.url`, `token_env` | Empty URL keeps the in-process path. Configured token variable must be non-empty. | production-wired |
|
||||
| `containers.*` | See dedicated table below. | production-wired |
|
||||
| `chat.*` | See channel table below. | production-wired |
|
||||
| `memory.provider`, `provider_config` | Feature YAML decodes these; `internal/app/archied` always starts built-in file provider at `work_dir/memory`. | decoded-but-unwired |
|
||||
| `tools.mcp_servers` | `internal/app/archied` registers daemon-side MCP providers. Empty transport becomes `stdio`; only `stdio` accepted. `url` decoded but unused. | partially-wired |
|
||||
| `indexing.index_dir`, `indexing.db_path` | `finalize` derives paths under `work_dir`; no entrypoint constructs `internal/indexing.Manager` (the exported `NewManager` exists but has no production caller). | decoded-but-unwired |
|
||||
| `extra` / unknown `conf.d` values | Test/library-only `Loader.Dir` stores untyped data; no core production consumer. | decoded-but-unwired |
|
||||
| `[identities.forge].intake`, `.webhook_secret`, `.webhook_addr` | 2026-09-22: these parse because `IdentityConfig` embeds `Forge` (`internal/config/config.go:573`), while every read is the root `[forge]` block (`validate.go`, `defaults.go`, `bootstrap.go`). Wiring them is the intake migration, tracked as `archie-core-1786637497036-275-8838629e`. | partially-wired |
|
||||
|
||||
**Three shapes of an unwired field.** All three read as working from the file
|
||||
alone, and only the first two are defects - so establish which shape you are
|
||||
looking at before reporting one:
|
||||
|
||||
1. **not-consumed.** Decoded and normalised, but no production consumer uses the
|
||||
effective value (`memory.provider` and `indexing.*` above; per-identity intake
|
||||
was this shape until 2026-09-22, when the configuration was made to reject it
|
||||
rather than accept it).
|
||||
2. **not-projected.** A read exists, but at a layer that does not own the
|
||||
effective copy, so editing the wrong layer does nothing. Direction matters as
|
||||
much as presence: for most `[chat.*]` keys the stored resource outranks the
|
||||
file, so writing a new file value is a no-op once a resource exists. A file
|
||||
key in that position is a **seed**, not the contract.
|
||||
3. **deliberately-not-projected.** File-only by design and therefore
|
||||
indistinguishable from a dropped field to an auditor unless the projection
|
||||
says so in a comment. `runtimeChatConfigFrom` reads
|
||||
`Telegram.UpdateCheckCommand`/`UpdateInstallCommand` from `base` rather than
|
||||
from the stored resource, on purpose. Check for that comment before filing a
|
||||
defect.
|
||||
|
||||
### Repository settings
|
||||
|
||||
| Keys | Effective behaviour | Status |
|
||||
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- |
|
||||
| `owner`, `name` | Required for every declared repo. Single-identity config with zero repos loads but polls nothing. | production-wired |
|
||||
| `base` | `BaseBranch()` maps empty to `main`, but `daemon.process` pre-clones with raw `repo.Base`. Set it explicitly. | partially-wired |
|
||||
| `gate` | Argv arrays run in order. Empty entries skipped. TDD inverts last non-empty command as repro test by convention. | production-wired |
|
||||
| `protect` | Path suffixes enforced by agent runner; not prompt-only rule. | production-wired |
|
||||
| `ecosystem`, `preflight`, `test_glob` | Resolved preflight/test-glob treats empty ecosystem as Go. Container storage receives raw ecosystem. Go/Python/Node/Rust have defaults; `custom` or unknown yields none. | partially-wired |
|
||||
| `persistent_storage` | Controls Docker-backed per-repo volume setup; no equivalent without container storage. | partially-wired |
|
||||
| `max_retries` | Values greater than zero override global; zero or negative falls back to global. | production-wired |
|
||||
| `allow_concurrent` | Root repo entries affect dispatcher. `allowConcurrentFor` does not inspect identity repo lists. | partially-wired |
|
||||
|
||||
### Container settings
|
||||
|
||||
| Key | Effective behaviour |
|
||||
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
|
||||
| `image` | Required at boot. Read by the container pool on every acquire (`containerLiveSettings` -> `Pool.current`, archie-core-zfb0.2), so a stored change applies without a restart. |
|
||||
| `max_concurrency` | Zero means no limit. Read by the pool per acquire and applied to the daemon's running task dispatcher on publish (`ResizeTaskDispatcher`). |
|
||||
| `max_uptime` | Default `60m` at boot; caps container lifetime. Read by the pool per acquire, so a stored change reaps the next container under the new cap. |
|
||||
| `volume_ttl` | Default `72h` only when enabled; negative rejected. Re-read per cleanup cycle. |
|
||||
| `pull_policy` | Default `missing` at boot. Pool code recognises `missing` and `always`; other strings silently skip pre-pull. Read by the pool per acquire. |
|
||||
| `registry_auth` | `SecretRef` (file-owned, `json:"-"`). Resolved at boot by `archied`'s `resolveRegistryAuth` and passed to `container.Config.RegistryAuth`; the pool base64url-encodes it into the `X-Registry-Auth` header (`internal/container/pool.go`'s `registryAuthHeader`). Zero ref = anonymous pull. Unresolvable/empty credential or an unencodable one warns and pulls anonymously rather than failing the pool. A half-named ref is refused by `configuration.validateContainers`. `container-runtime-policies` cannot carry a secret ref, so this stays boot-resolved and requires-restart, unlike `image`/`pull_policy`. |
|
||||
| `network` | Empty uses best-effort self-network detection at boot; the repository overlay pins `archie-core_default`. Read by the pool per acquire, falling back to the boot-resolved network when the live value is empty. |
|
||||
| `profiles` | Named agent execution environments (image or Kit); resolved per task dispatch (`ContainerConfig.Profile`). Own control-plane resource `agent-profiles` (`json:"-"` on the field so `container-runtime-policies` never carries it), `ApplyMode: live`. |
|
||||
| `credentials` | Maps a Kit `credential@1` service to a secret (`config.CredentialBinding`). Own control-plane resource `credential-bindings`, `ApplyMode: live`, `json:"-"` on the field. `kitrun.Launcher` reads it fresh from the live `config.Holder` on every `Launch`, never a value captured at boot -- see `internal/infrastructure/kitrun/launcher.go`'s `resolveCredentials`. A binding alone grants nothing; see `org`/`granted_credentials` below. |
|
||||
| `org` / `granted_credentials` (root and per-identity) | An identity's org and the `credentials` service names it may resolve. `daemon.runKitTask` reads both fresh per dispatch (`d.configFor(task)`) and passes them to `kitrun.Request`; `config.ContainerConfig.BoundCredentials` computes the declared (Kit) ∩ granted (identity) ∩ org-matched intersection -- neither declared nor granted widens the other. |
|
||||
|
||||
### Channel settings
|
||||
|
||||
| Keys | Effective behaviour |
|
||||
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| `chat.models` | Optional interactive catalogue; empty falls back to workflow model references. |
|
||||
| `chat.telegram.token` | Unset disables Telegram; otherwise a secret reference resolved at channel start. |
|
||||
| `chat.telegram.allowed_user_ids` | Empty denies every sender; IDs match Telegram sender IDs, not chat IDs. |
|
||||
| `chat.telegram.update_check_command`, `update_install_command` | Argv arrays; check enables update status; install further enables approved installation. |
|
||||
| `chat.email.listen_addr`, `relay_addr` | Empty listen disables SMTP; relay configures outbound replies. |
|
||||
| `chat.webhook_addr` | Empty disables; malformed host/port falls back inside `parseListenAddr`. |
|
||||
|
||||
Telegram `/restart` re-runs same TOML overlay load, then replaces only gateway
|
||||
token and allowed-user list. Every other file setting is startup-only.
|
||||
|
||||
A stored `channel-settings` change is reconciled live by `archie-messaging`:
|
||||
on a new version it re-resolves the file, layers the store over it, and restarts
|
||||
only the channel whose transport settings changed (Telegram token/allowlist,
|
||||
email relay, webhook route/secret). `chat.email.listen_addr` and
|
||||
`chat.webhook_addr` are bound listen addresses, so those changes, and enabling
|
||||
or disabling a channel, are reported outstanding and take effect on restart.
|
||||
|
||||
## Treat multi-identity as partially wired
|
||||
|
||||
`finalize` requires each identity's `name`, `bot_user`, non-empty repos, forge
|
||||
type, and `SecretRef` token. `internal/app/archied` builds an identity forge
|
||||
client and worktree manager.
|
||||
|
||||
Do not infer complete isolation:
|
||||
|
||||
- `internal/app/archied` resolves root forge client before all identity runners.
|
||||
- Identity `name`, forge, repos, poll interval, bot user, bot email have
|
||||
production reads. Identity bot email not defaulted despite comment.
|
||||
- Identity `models`, `providers`, `dispatch`, `budgets`, `notify`, and
|
||||
`diff_cap_lines` decode but workflows still receive root `Config`.
|
||||
- Identity polling reads root `dispatch`, `label`, and `bot_user`.
|
||||
- Container task snapshots and provider maps come from root config; task RPC
|
||||
servers are root-forge/root-worktree.
|
||||
- Root-only concurrency lookup ignores identity repo `allow_concurrent`.
|
||||
|
||||
Classify multi-identity changes field by field. Never label aggregate
|
||||
`IdentityConfig` production-wired.
|
||||
|
||||
## Preserve worker and secret boundaries
|
||||
|
||||
`Config.ForTask` creates a detached root snapshot: models, budgets, the
|
||||
retry/remediation cap (`MaxRetries`), dispatch, diff cap, notification, and
|
||||
forge host. `TaskConfig.ToConfig` reconstructs
|
||||
only those fields. Forge tokens, provider values, NATS credential references,
|
||||
repos, and infrastructure settings do not enter `TaskConfig`.
|
||||
|
||||
Every credential except `nats.token_env` is a `{engine, key}` secret
|
||||
reference; the flat `token_env` aliases for forge, artifacts and Telegram are
|
||||
removed. A stale alias in a file is reported at startup as an unrecognised key
|
||||
(`bootstrap.go`), not silently ignored.
|
||||
|
||||
| Source | Archied | Subprocess | Agent container / standalone worker |
|
||||
| ------------------------------------------ | --------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------- |
|
||||
| Forge `token = {engine="env", key="X"}` | Resolves `X`; empty is fatal. | Not forwarded. | Not forwarded; forge ops proxy to daemon. |
|
||||
| Provider `api_key_env = "X"` | Runtime reads `X`. | Auto-allowlists selected provider's `X`. | Daemon forwards each present provider variable under original name. |
|
||||
| `nats.token_env = "X"` | Reads `X`; empty fatal when configured. | Not agent subprocess setting. | Daemon maps to fixed `NATS_TOKEN`; worker also reads `NATS_URL`. |
|
||||
| Telegram `token = {engine="env", key="X"}` | Resolves `X`. | Not forwarded. | Not forwarded. |
|
||||
|
||||
`internal/app/archied` creates `secret.NewRegistry`, which registers only the
|
||||
`env` engine. Non-env `SecretRef` values are not production-wired.
|
||||
|
||||
The host supervisor or launch shell supplies daemon secrets. Compose supplies
|
||||
no `archied` environment because the daemon is not a Compose service.
|
||||
|
||||
## Follow the approved target
|
||||
|
||||
Current code puts infrastructure paths, domain policy, channel settings,
|
||||
secrets, execution settings, repository associations, and extension data in one
|
||||
mutable `config.Config`. Treat this as a current load-bearing weakness, not a
|
||||
pattern to copy.
|
||||
|
||||
`docs/architecture/configuration.md` is approved as of 2026-07-28:
|
||||
|
||||
- move file/env/secret/overlay loading to private
|
||||
`internal/infrastructure/configuration` input boundary;
|
||||
- translate inputs in `internal/app`;
|
||||
- give each domain/plugin typed owned settings and validation;
|
||||
- dissolve `internal/config` rather than rename the global model;
|
||||
- split `Repo` and `IdentityConfig` by actual capability ownership.
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "Archie Config and Flags"
|
||||
short_description: "Trace Archie configuration from input to runtime"
|
||||
default_prompt: "Use $archie-config-and-flags to trace this Archie setting or CLI flag from declaration through production wiring."
|
||||
@@ -1,235 +0,0 @@
|
||||
---
|
||||
name: archie-debugging-playbook
|
||||
description: Project-specific symptom-to-evidence triage for archie-core. Load this skill when Archied hangs, parks a task, loses or duplicates work, cannot reach NATS or an agent container, rejects configuration or secrets, shows stale Telegram or dashboard state, loses streamed text, fails MCP startup, reports task-state surprises, degrades an optional feature, or when Go tests disagree between a sandbox, editor, CI, and the host. Use it to separate environment failures from code regressions and to choose the next exact diagnostic.
|
||||
---
|
||||
|
||||
# Debug Archie from evidence
|
||||
|
||||
**current** = 2026-09-18 verified (HEAD `2e1e1549`); **fixed history** =
|
||||
regression patterns; **open** = verified gap.
|
||||
|
||||
**Composition root**: `cmd/archied/main.go` → `internal/app/archied.Run()`;
|
||||
wiring lives in `internal/app/archied/bootstrap.go`. **Core NATS
|
||||
request/reply**: direct subject + reply inbox. **JetStream**: persisted stream
|
||||
`ARCHIE_TASKS`. **State Store**: gRPC (`internal/infrastructure/staterpc`), not
|
||||
NATS.
|
||||
**Environment failure**: test/process cannot use host resource (listener, tmp,
|
||||
Docker). **Code regression**: behaviour fails where prerequisites available.
|
||||
|
||||
## Run the first-ten-minutes protocol
|
||||
|
||||
Do not begin with `task check` (mutates via `gofumpt -w .`/`go fix ./...`).
|
||||
Compile, then run:
|
||||
|
||||
```bash
|
||||
GIT_CONFIG_GLOBAL=/dev/null go test ./PATH/TO/PACKAGE -run '^TestName$' -count=1 -v
|
||||
```
|
||||
|
||||
Classify: compile-only, listener failure, read-only tmp, code regression.
|
||||
|
||||
- Behavioural assertion with the prerequisite available: code regression.
|
||||
|
||||
Use this symptom index:
|
||||
|
||||
| Symptom | First boundary | Go to |
|
||||
| ----------------------------------------------------- | ----------------------------------- | --------------------------------------- |
|
||||
| `Run() = "\n"` in `TestRunWrapsExternalCommand` | Skill-script test command shape | Fixed history — passes since 2026-09-16 |
|
||||
| Embedded NATS panics before a test assertion | Listener permission | Test environment |
|
||||
| `nats: no responders available for request` | Core NATS subscription | NATS request/reply |
|
||||
| Agent reply timeout | JetStream request, inbox, or worker | NATS request/reply |
|
||||
| Queue looks empty while NATS reports an error | `Client.Fetch` batch error | NATS request/reply |
|
||||
| Config test passes but daemon ignores the field | Composition/wiring | Configuration |
|
||||
| Daemon has an env var but container does not | Compose or `containerEnv` | Configuration |
|
||||
| Telegram reply hangs on the first token | Stream consumer | Streaming |
|
||||
| MCP unit tests pass but a real server hangs | Framing mirror | MCP |
|
||||
| Telegram shows old commands | Token-scoped Telegram state | Telegram |
|
||||
| Transition succeeds from the wrong state | Store semantics | Database/state |
|
||||
| Dashboard skips events but task state is correct | Bounded event buffers | Events |
|
||||
| Search works but never becomes indexed | Missing production wiring | Optional features |
|
||||
| Agent container cannot resolve `nats` | Docker network | Containers |
|
||||
| `agent.mode = "subprocess"` fails at protocol startup | Worker binary mismatch | Subprocess mode |
|
||||
|
||||
## Separate test-environment failures from regressions
|
||||
|
||||
```bash
|
||||
go version
|
||||
go env GOTMPDIR GOCACHE GOPATH GOMODCACHE GOENV
|
||||
```
|
||||
|
||||
Listener-dependent tests include embedded NATS, `httptest.NewServer`, and SMTP
|
||||
listeners:
|
||||
|
||||
```bash
|
||||
rg -n 'httptest\.NewServer|net\.Listen|RunRandClientPortServer|RunServer' \
|
||||
--glob '*_test.go' cmd internal
|
||||
```
|
||||
|
||||
Do not attribute go-git commit failures to GPG without checking the
|
||||
repository-local mitigation. `worktree.Manager.setIdentity` pins
|
||||
`commit.gpgsign=false`. Isolate ambient global config:
|
||||
|
||||
```bash
|
||||
GIT_CONFIG_GLOBAL=/dev/null go test ./internal/worktree -count=1
|
||||
```
|
||||
|
||||
## Confirm the skill-script regression stays fixed
|
||||
|
||||
The `TestRunWrapsExternalCommand` failure (`Run() = "\n"`) was a test bug, not
|
||||
a product bug: `exec.CommandContext(ctx, "sh", "-c", "echo", "wrapped")`
|
||||
passes `wrapped` as shell `$0`, so only `echo` ran. It failed from commit
|
||||
`308c199` and **passes as of 2026-09-16**. Re-run it to confirm the fix has not
|
||||
regressed; a failure now is a new defect, not this one.
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-skillscript-gocache \
|
||||
GIT_CONFIG_GLOBAL=/dev/null go test ./internal/skillscript \
|
||||
-run '^TestRunWrapsExternalCommand$' -count=1 -v
|
||||
```
|
||||
|
||||
## Triage NATS request/reply and JetStream
|
||||
|
||||
| Surface | Subject or resource | Bound/current behaviour |
|
||||
| ----------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| Task discovery | `archie.task.>` in `ARCHIE_TASKS` | Work-queue retention; daemon durable `archie-daemon`; max deliver 3 |
|
||||
| Per-stage agent request | `archie.agent.<task>.request` | Reply inbox in `X-Archie-Reply`; wall-clock budget or 30m |
|
||||
| Full task handoff | `archie.taskrun.<task-id>` | Core request/reply; no-responder retry 20s every 250ms |
|
||||
| Store RPC | gRPC State Store (`internal/infrastructure/staterpc`) | Client timeout 60s (`rpcTimeout` in `internal/app/agentworker/worker.go`); task-scoped grants for Update/Transition/InsertEvent only |
|
||||
| Forge RPC | `archie.forge.*` | Error travels in a JSON envelope |
|
||||
| Worktree RPC | `archie.worktree.prepare`, `.push` | Server default handler bound 15m |
|
||||
| Discovery dedup | `Nats-Msg-Id: archie:<owner>/<repo>/<issue>` | JetStream duplicate window 2m |
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
docker compose logs --since=10m nats
|
||||
docker compose exec -T nats wget -q -O - http://localhost:8222/healthz
|
||||
```
|
||||
|
||||
Branch on `no responders`: container startup lag if responder appears within 20s;
|
||||
inspect agent's network/environment if every task exhausts window; confirm
|
||||
`registerTaskRPCServers` if only RPC calls time out.
|
||||
|
||||
**Fixed history:** auto-detection once put task containers on default bridge;
|
||||
explicit `containers.network` plus warning logs now fence that path.
|
||||
|
||||
Check semantics: republishing same owner/repo/issue within 2m is dedup'd; reply
|
||||
inbox auto-unsubscribes after one response; `Client.Fetch` must inspect
|
||||
`batch.Error()`; an empty poll reports `eventbus.ErrNoMessage` rather than
|
||||
`(nil, nil)`.
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-nats-unit-gocache \
|
||||
go test ./internal/infrastructure/eventbus/nats -run 'TestPublishUniqueSuppressesDuplicateKeyOnWorkQueueStream' -count=1 -v
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-agent-unit-gocache \
|
||||
go test ./internal/agentexec -run '^TestToolSetHandler' -count=1 -v
|
||||
```
|
||||
|
||||
## Trace configuration from source to behaviour
|
||||
|
||||
Trace: `cmd/archied` (`internal/app/archied/bootstrap.go`) reads
|
||||
`-config`/`-config-overlay` → `configuration.New(log)` + `Loader.Resolve`
|
||||
decodes, `finalize` defaults/validates → secrets resolve → composition root
|
||||
constructs service → Compose/subprocess/`containerEnv` propagate → consumer.
|
||||
|
||||
```bash
|
||||
rg -n 'Loader\.(Resolve|Overlay|Dir)|configuration\.' internal/app/archied internal/infrastructure/configuration
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-config-gocache \
|
||||
go test ./internal/infrastructure/configuration \
|
||||
-run 'Test(ResolveSelectsFileFormatsAndDirectories|LoadForgeTokenEnvBackwardCompat)' -count=1 -v
|
||||
```
|
||||
|
||||
The `config.Load`/`config.LoadDir` helpers are gone; decoding is
|
||||
`Loader`-based. A YAML field decoding correctly without a composition-root read
|
||||
is a wiring gap, not a parser bug.
|
||||
|
||||
For environment failures:
|
||||
|
||||
- The host supervisor supplies the daemon environment; inspect its unit or
|
||||
launch environment rather than Compose.
|
||||
- `containerEnv` translates configured NATS token name into `NATS_TOKEN` and
|
||||
forwards configured provider key variables.
|
||||
|
||||
Do not print secret values.
|
||||
|
||||
## Diagnose streaming, MCP, and Telegram
|
||||
|
||||
### Streaming
|
||||
|
||||
Must drain `stream.FullStream`, collect `core.StreamPartTextDelta`, check
|
||||
`FinishReason`. `TextStream` is best-effort. **Fixed history:** consuming
|
||||
`TextStream` while `FullStream` unread deadlocked every reply.
|
||||
|
||||
### MCP
|
||||
|
||||
Stdio framing is one compact JSON-RPC object per line. Stale
|
||||
`internal/tools/mcp/types.go` comment mentions `Content-Length` — not the
|
||||
implemented contract.
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-mcp-gocache \
|
||||
go test ./internal/tools/mcp \
|
||||
-run 'Test(ReadMessage|WriteMessage|StdioTransportBadFraming)' -count=1 -v
|
||||
```
|
||||
|
||||
Test helper and client share the same `readMessage`/`writeMessage` — can mirror
|
||||
mistakes. With `npx`:
|
||||
|
||||
```bash
|
||||
ARCHIE_TEST_DESKTOP_COMMANDER=1 env GOTMPDIR=/tmp \
|
||||
GOCACHE=/tmp/archie-mcp-integration-gocache \
|
||||
go test ./internal/tools/provider/mcp \
|
||||
-run '^TestDesktopCommanderClientCompatibility$' -count=1 -v
|
||||
```
|
||||
|
||||
Gate: non-empty discovery with `start_process`, `interact_with_process`,
|
||||
`read_process_output`.
|
||||
|
||||
### Telegram
|
||||
|
||||
Three command scopes in `internal/channels/telegram/commands.go`: default, all
|
||||
private chats, all group chats. Narrower scope shadows default; state keyed by
|
||||
bot token. Empty `allowed_user_ids` denies everyone.
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-telegram-gocache \
|
||||
go test ./internal/channels/telegram \
|
||||
-run 'Test(SenderAllowlistFailsClosed|IsSenderAllowed|SessionManagementCommandsArePublished)$' \
|
||||
-count=1 -v
|
||||
```
|
||||
|
||||
**Fixed history:** publishing only default left ~60 old Hermes commands visible.
|
||||
|
||||
## Diagnose state, events, containers, and optional features
|
||||
|
||||
### Database and transitions
|
||||
|
||||
`internal/infrastructure/postgres.Store.Transition` owns task state changes and
|
||||
transition history: it guards on `from`, returning
|
||||
`storecontract.ErrStaleTransition`, and writes status plus history in one transaction.
|
||||
When state is surprising: read `TaskByID` before/after caller; trace every
|
||||
`Transition`, `Requeue`, `RecoverStale`, `Update` — and remember the daemon
|
||||
exposes these over the gRPC State Store, not NATS.
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-state-gocache go test ./internal/infrastructure/postgres -count=1 # needs Docker
|
||||
```
|
||||
|
||||
### Events
|
||||
|
||||
DB sink buffer 256; SSE client buffers 64. Drop counter not read in production.
|
||||
Dashboard gap can coexist with correct task state.
|
||||
|
||||
### Containers, worktrees, and subprocess mode
|
||||
|
||||
Container-mode: clones on host, mounts `/data/worktree`, writes `.git/task.json`,
|
||||
dedicated `archie.taskrun.<id>` subscription. **Open:** container RPC is
|
||||
root-identity-bound; `SubprocessRunner` expects stdin JSON protocol.
|
||||
|
||||
### Optional feature degradation
|
||||
|
||||
| Feature | Current failure behaviour |
|
||||
| --------------------- | --------------------------------------------------------------------------------------------- |
|
||||
| Daemon plugins | Warn and skip |
|
||||
| Invalid MCP config | Warn and continue |
|
||||
| Skill catalogue | Warn, continue without tool |
|
||||
| Worktree augmentation | Log error, use startup registry |
|
||||
| Workspace indexing | **Open:** `indexing.NewManager` exists but has no production caller in `internal/app/archied` |
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "Archie Debugging Playbook"
|
||||
short_description: "Diagnose Archie failures from symptoms"
|
||||
default_prompt: "Use $archie-debugging-playbook to diagnose this Archie failure from symptoms and evidence."
|
||||
@@ -1,265 +0,0 @@
|
||||
---
|
||||
name: archie-diagnostics-and-tooling
|
||||
description: "Measure Archie codebase maintainability, Go package dependency shape, configuration consumption, production composition, test and delivery-gate drift, tracked-artifact hygiene, coverage, races, and runtime evidence. Load when establishing a dated baseline, finding large or complex functions, investigating duplicate or dead-path candidates, checking whether configuration reaches an entrypoint, comparing architecture before and after a refactor, or replacing an eyeballed quality claim with reproducible numbers."
|
||||
---
|
||||
|
||||
# Measure Archie instead of eyeballing it
|
||||
|
||||
Collect evidence before judging quality. Keep collection read-only, save raw
|
||||
output, state what each metric cannot prove.
|
||||
|
||||
Volatile facts and numeric snapshots below were verified on **2026-09-18**
|
||||
(HEAD `2e1e1549`).
|
||||
|
||||
Route to `archie-codebase-discovery` for semantic traces,
|
||||
`archie-config-and-flags` for config enumeration,
|
||||
`archie-debugging-playbook` for live failures.
|
||||
|
||||
## Define the measurement terms
|
||||
|
||||
- **Baseline:** dated raw output tied to a commit, toolchain, command, and
|
||||
environment.
|
||||
- **Candidate:** a machine-found item requiring semantic confirmation.
|
||||
- **Production composition:** concrete construction selected by a shipped
|
||||
entrypoint. Principal: `cmd/archied/main.go` → `internal/app/archied.Run()`.
|
||||
- **Fan-in:** number of packages in the same module that directly import a
|
||||
package.
|
||||
- **Fan-out:** number of packages in the same module that a package directly
|
||||
imports.
|
||||
- **Physical line:** a newline-delimited source line, including comments and
|
||||
blanks.
|
||||
- **Syntactic complexity:** this skill's approximation: one plus `if`, loop,
|
||||
non-default case, communication clause, `&&`, and `||` nodes.
|
||||
|
||||
## Establish a reproducible snapshot
|
||||
|
||||
```sh
|
||||
export LC_ALL=C
|
||||
export GOCACHE=/tmp/archie-diagnostics-gocache
|
||||
export GOTMPDIR=/tmp
|
||||
export XDG_CACHE_HOME=/tmp/archie-diagnostics-xdg
|
||||
export GOLANGCI_LINT_CACHE=/tmp/archie-diagnostics-lint
|
||||
export GOPROXY=off
|
||||
export GOFLAGS=-mod=readonly
|
||||
|
||||
skill=.agents/skills/archie-diagnostics-and-tooling
|
||||
stamp=$(date -u +%Y%m%dT%H%M%SZ)
|
||||
evidence_dir=/tmp/archie-diagnostics-"$stamp"
|
||||
mkdir -p "$evidence_dir"
|
||||
|
||||
git rev-parse --verify HEAD >"$evidence_dir/revision.txt"
|
||||
git status --short >>"$evidence_dir/revision.txt"
|
||||
go version >"$evidence_dir/tools.txt"
|
||||
gopls version >>"$evidence_dir/tools.txt"
|
||||
golangci-lint version >>"$evidence_dir/tools.txt"
|
||||
staticcheck -version >>"$evidence_dir/tools.txt"
|
||||
|
||||
go run "$skill/scripts/source-metrics.go" -root . >"$evidence_dir/source.tsv"
|
||||
go run "$skill/scripts/config-use-candidates.go" -root . >"$evidence_dir/config.tsv"
|
||||
"$skill/scripts/package-shape.sh" . >"$evidence_dir/packages-root.tsv"
|
||||
"$skill/scripts/package-shape.sh" tools >"$evidence_dir/packages-tools.tsv"
|
||||
"$skill/scripts/delivery-snapshot.sh" >"$evidence_dir/delivery.tsv"
|
||||
```
|
||||
|
||||
Both filesystem-walking scripts (`source-metrics.go`,
|
||||
`config-use-candidates.go`) skip `.worktrees/`, which holds live git worktrees
|
||||
nested inside the repo root. Each is a near-complete copy of the module, so
|
||||
walking them multiplies every count by the number of checkout worktrees. If a
|
||||
new nested-checkout convention appears, extend `excludedDirectory` in both;
|
||||
`.git/info/exclude` does not help, because the scripts walk the filesystem
|
||||
rather than `git ls-files`. `package-shape.sh` reads `go list`, so it is immune.
|
||||
|
||||
## Use the bundled reports
|
||||
|
||||
### Measure source shape
|
||||
|
||||
```sh
|
||||
go run "$skill/scripts/source-metrics.go" -root . -top 30
|
||||
```
|
||||
|
||||
Read its tab-separated schema:
|
||||
|
||||
| Record | Columns after record name |
|
||||
| --------- | --------------------------------------------------------------------------------------------------------------- |
|
||||
| `META` | key, value |
|
||||
| `METRIC` | module, metric, integer |
|
||||
| `PACKAGE` | module, directory, production files, test files, generated files, production lines, test lines, generated lines |
|
||||
| `HOTSPOT` | module, file, declaration line, symbol, body-span lines, statement nodes, approximate syntactic complexity |
|
||||
|
||||
The defaults (80 body lines, complexity 15) mirror numeric triage points in
|
||||
`.golangci.yml`. They do **not** implement `funlen` or `cyclop`. Run configured
|
||||
linters for authoritative findings:
|
||||
|
||||
```sh
|
||||
golangci-lint run --enable-only=funlen,gocognit,gocyclo,cyclop,maintidx,nestif ./internal/...
|
||||
```
|
||||
|
||||
If a hotspot shrinks, verify that responsibility moved to a cohesive owner.
|
||||
Moving the same work into unowned helpers is not improvement.
|
||||
|
||||
### Measure package shape
|
||||
|
||||
```sh
|
||||
"$skill/scripts/package-shape.sh" . >"$evidence_dir/packages-root.tsv"
|
||||
"$skill/scripts/package-shape.sh" tools >"$evidence_dir/packages-tools.tsv"
|
||||
awk -F ' ' '$1=="PACKAGE" {print $3 "\t" $4 "\t" $2}' "$evidence_dir/packages-root.tsv" |
|
||||
sort -nr -k1,1 -k2,2 |
|
||||
sed -n '1,20p'
|
||||
```
|
||||
|
||||
Read `PACKAGE package fan_in fan_out` and `EDGE from -> to` rows. High fan-in
|
||||
signals change risk; high fan-out signals orchestration. The report contains
|
||||
only direct, intra-module imports.
|
||||
|
||||
### Find configuration-consumption candidates
|
||||
|
||||
```sh
|
||||
go run "$skill/scripts/config-use-candidates.go" -root . >"$evidence_dir/config.tsv"
|
||||
rg 'candidate-no-(selector-outside-config|entrypoint-selector)' "$evidence_dir/config.tsv"
|
||||
```
|
||||
|
||||
Read each `CONFIG_FIELD` row as path, line, Type.Field, tags, same-name
|
||||
definition count, config-package selectors, cmd selectors, other-production
|
||||
selectors, test selectors, generated selectors, candidate status. The report
|
||||
finds named fields with `toml`/`yaml`/`json` tags in `internal/config`, then
|
||||
counts selectors with the same **spelling**. It is deliberately fast and not
|
||||
type-aware.
|
||||
|
||||
Only `candidate-no-selector-outside-config` is a signal.
|
||||
`candidate-no-entrypoint-selector` fires for ~180 of 196 rows because the
|
||||
script looks for selectors only in `cmd/`, and most fields are read from the
|
||||
composition root under `internal/app/archied`. Even the signal row has false
|
||||
positives: a field consumed by **spelling** rather than by a Go selector
|
||||
(`LegacyEnabled` via the reload allowlist map, `ReloadStatus.*` via JSON
|
||||
marshalling) reports zero. Confirm each candidate by hand before calling a
|
||||
field dead.
|
||||
|
||||
For every candidate: run `gopls references -d` on the exact field identifier;
|
||||
trace decode → default → validation → normalisation/copy → composition-root read
|
||||
→ concrete component → observable behaviour.
|
||||
|
||||
### Measure delivery and hygiene drift
|
||||
|
||||
```sh
|
||||
"$skill/scripts/delivery-snapshot.sh" >"$evidence_dir/delivery.tsv"
|
||||
```
|
||||
|
||||
Read: `SURFACE axis scope literal_count` as literal text evidence;
|
||||
`HYGIENE metric count` as tracked-path candidates; `MODULE path` as discovered
|
||||
Go module boundaries. The snapshot compares Task, GitHub CI, and
|
||||
composition-root anchors under `internal/app/archied`.
|
||||
|
||||
Composition-root anchors must name the file that actually does the wiring.
|
||||
`cmd/archied/main.go` is a thin dispatcher that routes to
|
||||
`internal/app/archied`; anchoring on it yields a silent `0` for every row,
|
||||
which reads as "no composition root" rather than "wrong file". A zero here is
|
||||
evidence about the anchor, not about production.
|
||||
|
||||
Inspect hygiene candidates directly:
|
||||
|
||||
```sh
|
||||
git ls-files |
|
||||
rg '(^|/)(node_modules|bin|dist|\.gotmp)(/|$)|\.(exe|test|out)$'
|
||||
git ls-files -s | awk '$1=="120000" {print}'
|
||||
```
|
||||
|
||||
## Investigate duplication and hidden dead paths
|
||||
|
||||
```sh
|
||||
golangci-lint run --enable-only=dupl ./internal/...
|
||||
```
|
||||
|
||||
```sh
|
||||
staticcheck -checks=U1000 ./internal/...
|
||||
```
|
||||
|
||||
On 2026-09-18, the focused `dupl` command reported zero issues. Two code paths
|
||||
can implement the same responsibility with different syntax.
|
||||
|
||||
For every candidate: name the externally visible operation; search all
|
||||
entrypoints and modes; use `gopls call_hierarchy`, `gopls references -d`, and
|
||||
AST construction scan; check interfaces, registrations, reflection, build tags,
|
||||
OS files, and wire names; identify what a new feature supersedes; record
|
||||
production-only, test-only, compatibility, generated, and unreachable paths
|
||||
separately.
|
||||
|
||||
As of 2026-09-18, `Taskfile.yml` defines no `deadcode` task and `go tool` lists
|
||||
no dead-code analyser.
|
||||
|
||||
## Collect test, race, coverage, and runtime evidence
|
||||
|
||||
```sh
|
||||
go test ./internal/infrastructure/postgres -count=1 -coverprofile=/tmp/archie-store.cover
|
||||
go tool cover -func=/tmp/archie-store.cover
|
||||
go test -race ./internal/infrastructure/postgres -count=1
|
||||
```
|
||||
|
||||
As of 2026-09-18, the package reported 78.6% statement coverage and passed its
|
||||
race run.
|
||||
|
||||
```sh
|
||||
docker compose logs nats >"$evidence_dir/nats.log"
|
||||
journalctl --user -u archied >"$evidence_dir/archied.log"
|
||||
curl -fsS http://localhost:8222/healthz >"$evidence_dir/nats-health.txt"
|
||||
```
|
||||
|
||||
Run only when local Compose stack is in scope.
|
||||
|
||||
## Compare before and after
|
||||
|
||||
Predict exact deltas before changing code. Collect a second snapshot with the
|
||||
same script revision, flags, environment, and toolchain:
|
||||
|
||||
```sh
|
||||
after_dir=/tmp/archie-diagnostics-after
|
||||
mkdir -p "$after_dir"
|
||||
go run "$skill/scripts/source-metrics.go" -root . >"$after_dir/source.tsv"
|
||||
go run "$skill/scripts/config-use-candidates.go" -root . >"$after_dir/config.tsv"
|
||||
"$skill/scripts/package-shape.sh" . >"$after_dir/packages-root.tsv"
|
||||
"$skill/scripts/delivery-snapshot.sh" >"$after_dir/delivery.tsv"
|
||||
|
||||
diff -u "$evidence_dir/source.tsv" "$after_dir/source.tsv"
|
||||
diff -u "$evidence_dir/config.tsv" "$after_dir/config.tsv"
|
||||
diff -u "$evidence_dir/packages-root.tsv" "$after_dir/packages-root.tsv"
|
||||
diff -u "$evidence_dir/delivery.tsv" "$after_dir/delivery.tsv"
|
||||
```
|
||||
|
||||
If output differs from prediction: confirm checkout, dirty state, script
|
||||
revision, flags, toolchain; explain each delta; branch to semantic discovery
|
||||
when a count cannot explain behaviour. Reject a "better" metric that moved
|
||||
duplication, hid a path, or weakened a gate.
|
||||
|
||||
## Dated current snapshot
|
||||
|
||||
The bundled scripts measured this checkout on 2026-09-18 (HEAD `2e1e1549`).
|
||||
These are post-fix numbers: earlier runs of the same scripts reported roughly
|
||||
3x these file and line counts because they walked `.worktrees/`.
|
||||
|
||||
| Observation | Unstable value |
|
||||
| --------------------------------------------------------------- | -----------------------: |
|
||||
| Root production/test/generated Go files | 408 / 402 / 9 |
|
||||
| Root production/test/generated physical lines | 74,752 / 95,264 / 12,774 |
|
||||
| `internal/app/archied.Run` body span / approximate complexity | 97 / 19 |
|
||||
| Root internal packages / direct internal edges | 110 / 316 |
|
||||
| Tagged config field rows | 194 |
|
||||
| Tracked paths / tracked `node_modules` paths / tracked symlinks | 1,088 / 0 / 1 |
|
||||
| `.dockerignore` present | 1 |
|
||||
|
||||
`source-metrics.go` and `git ls-files` reconcile here: 408 + 9 generated
|
||||
production files and 402 test files, plus the `tools` module's 5 / 2 / 0,
|
||||
against 422 non-test and 403 test tracked files. The single extra file is an
|
||||
untracked probe under `.local/issue-tracker/probes/`.
|
||||
|
||||
The scripts count themselves: the skill's own Go files contribute 640 of those
|
||||
production lines. Editing a bundled script therefore moves
|
||||
`production_physical_lines` on its own, so re-baseline after any script change
|
||||
rather than reading the delta as a change in the product code.
|
||||
|
||||
The delivery snapshot found no Taskfile literals for race; docs now has 6 and
|
||||
the `tools` module 7, both grown by wiring `task docs:check` into the gate;
|
||||
GitHub `go gate` 4 and container publish 3; and non-zero literals for all five
|
||||
composition-root anchors under `internal/app/archied`.
|
||||
|
||||
The focused test
|
||||
`go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v`
|
||||
failed on 2026-07-28 with `Run() = "\n"` and **passes** as of 2026-09-16.
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "Archie Diagnostics and Tooling"
|
||||
short_description: "Measure maintainability, wiring, and delivery drift"
|
||||
default_prompt: "Use $archie-diagnostics-and-tooling to collect a dated, reproducible evidence baseline before changing Archie."
|
||||
@@ -1,283 +0,0 @@
|
||||
// Command config-use-candidates reports syntax-level selector evidence for
|
||||
// tagged fields declared by internal/config. Results are candidates, not proof
|
||||
// that a field is wired, live, or dead.
|
||||
package main
|
||||
|
||||
import (
|
||||
"flag"
|
||||
"fmt"
|
||||
"go/ast"
|
||||
"go/parser"
|
||||
"go/token"
|
||||
"io/fs"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"reflect"
|
||||
"sort"
|
||||
"strconv"
|
||||
"strings"
|
||||
)
|
||||
|
||||
type fieldDefinition struct {
|
||||
path string
|
||||
line int
|
||||
typeName string
|
||||
fieldName string
|
||||
tags string
|
||||
duplicates int
|
||||
}
|
||||
|
||||
type referenceCounts struct {
|
||||
config int
|
||||
entrypoint int
|
||||
production int
|
||||
test int
|
||||
generated int
|
||||
}
|
||||
|
||||
func main() {
|
||||
root := flag.String("root", ".", "repository root to inspect")
|
||||
flag.Parse()
|
||||
|
||||
absoluteRoot, err := filepath.Abs(*root)
|
||||
if err != nil {
|
||||
fail(2, "resolve root: %v", err)
|
||||
}
|
||||
info, err := os.Stat(absoluteRoot)
|
||||
if err != nil {
|
||||
fail(2, "inspect root: %v", err)
|
||||
}
|
||||
if !info.IsDir() {
|
||||
fail(2, "root is not a directory: %s", absoluteRoot)
|
||||
}
|
||||
|
||||
fset := token.NewFileSet()
|
||||
fields, err := readFieldDefinitions(absoluteRoot, fset)
|
||||
if err != nil {
|
||||
fail(1, "%v", err)
|
||||
}
|
||||
if len(fields) == 0 {
|
||||
fail(1, "no tagged fields found under internal/config")
|
||||
}
|
||||
|
||||
nameCounts := map[string]int{}
|
||||
for _, field := range fields {
|
||||
nameCounts[field.fieldName]++
|
||||
}
|
||||
for index := range fields {
|
||||
fields[index].duplicates = nameCounts[fields[index].fieldName]
|
||||
}
|
||||
|
||||
references := map[string]*referenceCounts{}
|
||||
for name := range nameCounts {
|
||||
references[name] = &referenceCounts{}
|
||||
}
|
||||
if err := countSelectors(absoluteRoot, fset, references); err != nil {
|
||||
fail(1, "%v", err)
|
||||
}
|
||||
|
||||
sort.Slice(fields, func(i, j int) bool {
|
||||
if fields[i].typeName != fields[j].typeName {
|
||||
return fields[i].typeName < fields[j].typeName
|
||||
}
|
||||
if fields[i].fieldName != fields[j].fieldName {
|
||||
return fields[i].fieldName < fields[j].fieldName
|
||||
}
|
||||
if fields[i].path != fields[j].path {
|
||||
return fields[i].path < fields[j].path
|
||||
}
|
||||
return fields[i].line < fields[j].line
|
||||
})
|
||||
|
||||
fmt.Println("META\tschema\tarchie-config-use-candidates/v1")
|
||||
fmt.Println("META\tmeaning\tselector-name counts are heuristic candidates; confirm exact fields with gopls references and production composition")
|
||||
for _, field := range fields {
|
||||
count := references[field.fieldName]
|
||||
status := "candidate-selector-seen-in-entrypoint"
|
||||
switch {
|
||||
case count.production == 0 && count.entrypoint == 0:
|
||||
status = "candidate-no-selector-outside-config"
|
||||
case count.entrypoint == 0:
|
||||
status = "candidate-no-entrypoint-selector"
|
||||
}
|
||||
fmt.Printf(
|
||||
"CONFIG_FIELD\t%s\t%d\t%s.%s\t%s\t%d\t%d\t%d\t%d\t%d\t%d\t%s\n",
|
||||
field.path,
|
||||
field.line,
|
||||
field.typeName,
|
||||
field.fieldName,
|
||||
field.tags,
|
||||
field.duplicates,
|
||||
count.config,
|
||||
count.entrypoint,
|
||||
count.production,
|
||||
count.test,
|
||||
count.generated,
|
||||
status,
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
func readFieldDefinitions(root string, fset *token.FileSet) ([]fieldDefinition, error) {
|
||||
configDir := filepath.Join(root, "internal", "config")
|
||||
info, err := os.Stat(configDir)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("inspect internal/config: %w", err)
|
||||
}
|
||||
if !info.IsDir() {
|
||||
return nil, fmt.Errorf("internal/config is not a directory")
|
||||
}
|
||||
|
||||
var fields []fieldDefinition
|
||||
err = filepath.WalkDir(configDir, func(path string, entry fs.DirEntry, walkErr error) error {
|
||||
if walkErr != nil {
|
||||
return walkErr
|
||||
}
|
||||
if entry.IsDir() || filepath.Ext(entry.Name()) != ".go" || strings.HasSuffix(entry.Name(), "_test.go") {
|
||||
return nil
|
||||
}
|
||||
body, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
file, err := parser.ParseFile(fset, path, body, parser.ParseComments)
|
||||
if err != nil {
|
||||
return fmt.Errorf("parse %s: %w", path, err)
|
||||
}
|
||||
relative, err := filepath.Rel(root, path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
relative = filepath.ToSlash(relative)
|
||||
for _, declaration := range file.Decls {
|
||||
general, ok := declaration.(*ast.GenDecl)
|
||||
if !ok || general.Tok != token.TYPE {
|
||||
continue
|
||||
}
|
||||
for _, specification := range general.Specs {
|
||||
typeSpec, ok := specification.(*ast.TypeSpec)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
structType, ok := typeSpec.Type.(*ast.StructType)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
for _, field := range structType.Fields.List {
|
||||
tags, ok := configTags(field.Tag)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
for _, name := range field.Names {
|
||||
fields = append(fields, fieldDefinition{
|
||||
path: relative,
|
||||
line: fset.Position(name.Pos()).Line,
|
||||
typeName: typeSpec.Name.Name,
|
||||
fieldName: name.Name,
|
||||
tags: tags,
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return nil
|
||||
})
|
||||
return fields, err
|
||||
}
|
||||
|
||||
func configTags(literal *ast.BasicLit) (string, bool) {
|
||||
if literal == nil {
|
||||
return "", false
|
||||
}
|
||||
raw, err := strconv.Unquote(literal.Value)
|
||||
if err != nil {
|
||||
return "", false
|
||||
}
|
||||
tag := reflect.StructTag(raw)
|
||||
var parts []string
|
||||
for _, key := range []string{"toml", "yaml", "json"} {
|
||||
value, ok := tag.Lookup(key)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
parts = append(parts, key+"="+value)
|
||||
}
|
||||
return strings.Join(parts, ";"), len(parts) > 0
|
||||
}
|
||||
|
||||
func countSelectors(root string, fset *token.FileSet, references map[string]*referenceCounts) error {
|
||||
return filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
|
||||
if walkErr != nil {
|
||||
return walkErr
|
||||
}
|
||||
relative, err := filepath.Rel(root, path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
relative = filepath.ToSlash(relative)
|
||||
if entry.IsDir() {
|
||||
if relative != "." && excludedDirectory(relative, entry.Name()) {
|
||||
return filepath.SkipDir
|
||||
}
|
||||
return nil
|
||||
}
|
||||
if filepath.Ext(entry.Name()) != ".go" {
|
||||
return nil
|
||||
}
|
||||
body, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
file, err := parser.ParseFile(fset, path, body, parser.ParseComments)
|
||||
if err != nil {
|
||||
return fmt.Errorf("parse %s: %w", relative, err)
|
||||
}
|
||||
generated := ast.IsGenerated(file)
|
||||
isTest := strings.HasSuffix(entry.Name(), "_test.go")
|
||||
inConfig := strings.HasPrefix(relative, "internal/config/")
|
||||
inEntrypoint := strings.HasPrefix(relative, "cmd/")
|
||||
|
||||
ast.Inspect(file, func(node ast.Node) bool {
|
||||
selector, ok := node.(*ast.SelectorExpr)
|
||||
if !ok {
|
||||
return true
|
||||
}
|
||||
count := references[selector.Sel.Name]
|
||||
if count == nil {
|
||||
return true
|
||||
}
|
||||
switch {
|
||||
case generated:
|
||||
count.generated++
|
||||
case isTest:
|
||||
count.test++
|
||||
case inConfig:
|
||||
count.config++
|
||||
case inEntrypoint:
|
||||
count.entrypoint++
|
||||
default:
|
||||
count.production++
|
||||
}
|
||||
return true
|
||||
})
|
||||
return nil
|
||||
})
|
||||
}
|
||||
|
||||
// excludedDirectory reports whether a walked directory is outside the module.
|
||||
//
|
||||
// ".worktrees" holds live git worktrees of this same repository, nested inside
|
||||
// the root. countSelectors walks the whole root, so without this every selector
|
||||
// count is multiplied by the number of checkout worktrees.
|
||||
func excludedDirectory(_, name string) bool {
|
||||
switch name {
|
||||
case ".git", ".claude", ".references", "node_modules", "vendor", ".gotmp", ".worktrees":
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
func fail(code int, format string, arguments ...any) {
|
||||
fmt.Fprintf(os.Stderr, "config-use-candidates: "+format+"\n", arguments...)
|
||||
os.Exit(code)
|
||||
}
|
||||
@@ -1,95 +0,0 @@
|
||||
#!/bin/sh
|
||||
set -eu
|
||||
|
||||
if [ "$#" -ne 0 ]; then
|
||||
printf '%s\n' "usage: delivery-snapshot.sh" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
for tool in git rg sed wc; do
|
||||
command -v "$tool" >/dev/null 2>&1 || {
|
||||
printf 'delivery-snapshot: %s is required\n' "$tool" >&2
|
||||
exit 127
|
||||
}
|
||||
done
|
||||
|
||||
script_dir=$(CDPATH= cd "$(dirname "$0")" && pwd)
|
||||
repo_root=$(CDPATH= cd "$script_dir/../../../.." && pwd)
|
||||
if [ ! -f "$repo_root/go.mod" ] || [ ! -f "$repo_root/Taskfile.yml" ]; then
|
||||
printf 'delivery-snapshot: expected Archie repository root at %s\n' "$repo_root" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
temporary=$(mktemp -d "${TMPDIR:-/tmp}/archie-delivery-snapshot.XXXXXX")
|
||||
trap 'rm -rf "$temporary"' EXIT HUP INT TERM
|
||||
cd "$repo_root"
|
||||
|
||||
printf '%s\n' "META schema archie-delivery-snapshot/v1"
|
||||
|
||||
scan_literal() {
|
||||
axis=$1
|
||||
scope=$2
|
||||
pattern=$3
|
||||
shift 3
|
||||
result="$temporary/$axis"
|
||||
if rg -n --no-heading --color never -e "$pattern" "$@" >"$result"; then
|
||||
:
|
||||
else
|
||||
status=$?
|
||||
if [ "$status" -ne 1 ]; then
|
||||
printf 'delivery-snapshot: scan failed for %s\n' "$axis" >&2
|
||||
exit "$status"
|
||||
fi
|
||||
fi
|
||||
count=$(wc -l <"$result" | sed 's/[[:space:]]//g')
|
||||
printf 'SURFACE\t%s\t%s\t%s\n' "$axis" "$scope" "$count"
|
||||
}
|
||||
|
||||
scan_literal task_format taskfile 'gofumpt[[:space:]]+-w|go fix' Taskfile.yml
|
||||
scan_literal task_vet taskfile 'go vet' Taskfile.yml
|
||||
scan_literal task_build taskfile 'go build|task:[[:space:]]+build' Taskfile.yml
|
||||
scan_literal task_test taskfile 'go test|task:[[:space:]]+test' Taskfile.yml
|
||||
scan_literal task_lint taskfile 'golangci-lint|task:[[:space:]]+lint' Taskfile.yml
|
||||
scan_literal task_race taskfile 'go test[^#\n]*-race|-race[^#\n]*go test' Taskfile.yml
|
||||
scan_literal task_tools_module taskfile 'go -C tools|cd tools|task:[[:space:]]+tools' Taskfile.yml
|
||||
scan_literal task_docs taskfile 'docsgen|docs:generate|docs:check' Taskfile.yml
|
||||
|
||||
# One CI surface: .github/workflows. The Gitea workflow was dropped in dd9bddc2
|
||||
# ("ci: build and push images to GHCR, drop the Gitea workflow"), so scanning
|
||||
# .gitea/workflows aborted the whole snapshot under `set -eu`.
|
||||
scan_literal github_go_gate github-workflows 'go test|go vet|go build|golangci-lint|task[[:space:]]+check' .github/workflows
|
||||
scan_literal github_container_publish github-workflows 'docker build|docker push|docker/build-push-action|docker login' .github/workflows
|
||||
|
||||
# Composition root. cmd/archied/main.go is now a ~30-line dispatcher that only
|
||||
# routes to internal/app/archied, so anchoring on it reported a silent zero for
|
||||
# every row below -- which reads as "no composition root" rather than "wrong
|
||||
# file". The wiring lives in internal/app/archied.
|
||||
scan_literal production_config_resolve composition-root 'configuration\.New\(' internal/app/archied
|
||||
scan_literal production_config_load composition-root 'loadConfig\(|loadRuntimeConfig\(' internal/app/archied
|
||||
scan_literal production_task_store composition-root 'openStateStore\(' internal/app/archied
|
||||
scan_literal production_daemon composition-root '&daemon\.Daemon\{' internal/app/archied
|
||||
scan_literal production_rpc_servers composition-root 'registerTaskRPCServers\(' internal/app/archied
|
||||
|
||||
git ls-files >"$temporary/tracked"
|
||||
tracked_total=$(wc -l <"$temporary/tracked" | sed 's/[[:space:]]//g')
|
||||
tracked_node_modules=$(rg -c '(^|/)node_modules(/|$)' "$temporary/tracked" || true)
|
||||
tracked_artifacts=$(rg -c '(^|/)(node_modules|bin|dist|\.gotmp)(/|$)|\.(exe|test|out)$' "$temporary/tracked" || true)
|
||||
tracked_symlinks=$(git ls-files -s | awk '$1 == "120000" {count++} END {print count + 0}')
|
||||
|
||||
printf 'HYGIENE\ttracked_paths\t%s\n' "$tracked_total"
|
||||
printf 'HYGIENE\ttracked_node_modules_paths\t%s\n' "${tracked_node_modules:-0}"
|
||||
printf 'HYGIENE\ttracked_artifact_candidates\t%s\n' "${tracked_artifacts:-0}"
|
||||
printf 'HYGIENE\ttracked_symlinks\t%s\n' "$tracked_symlinks"
|
||||
if [ -f .dockerignore ]; then
|
||||
printf '%s\n' "HYGIENE dockerignore_present 1"
|
||||
else
|
||||
printf '%s\n' "HYGIENE dockerignore_present 0"
|
||||
fi
|
||||
|
||||
find . \
|
||||
\( -path './.git' -o -path './.claude' -o -path './.references' -o -name node_modules -o -name .worktrees \) -prune -o \
|
||||
-name go.mod -print |
|
||||
LC_ALL=C sort |
|
||||
while IFS= read -r module; do
|
||||
printf 'MODULE\t%s\n' "$module"
|
||||
done
|
||||
@@ -1,86 +0,0 @@
|
||||
#!/bin/sh
|
||||
set -eu
|
||||
|
||||
if [ "$#" -gt 1 ]; then
|
||||
printf '%s\n' "usage: $0 [module-directory-relative-to-repo]" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
command -v go >/dev/null 2>&1 || {
|
||||
printf '%s\n' "package-shape: go is required" >&2
|
||||
exit 127
|
||||
}
|
||||
command -v awk >/dev/null 2>&1 || {
|
||||
printf '%s\n' "package-shape: awk is required" >&2
|
||||
exit 127
|
||||
}
|
||||
|
||||
script_dir=$(CDPATH= cd "$(dirname "$0")" && pwd)
|
||||
repo_root=$(CDPATH= cd "$script_dir/../../../.." && pwd)
|
||||
module_relative=${1:-.}
|
||||
module_root="$repo_root/$module_relative"
|
||||
edge_helper="$repo_root/.agents/skills/archie-codebase-discovery/scripts/package-edges.sh"
|
||||
|
||||
if [ ! -f "$module_root/go.mod" ]; then
|
||||
printf 'package-shape: no go.mod at %s\n' "$module_root" >&2
|
||||
exit 2
|
||||
fi
|
||||
if [ ! -x "$edge_helper" ]; then
|
||||
printf 'package-shape: required sibling helper is missing or not executable: %s\n' "$edge_helper" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
temporary=$(mktemp -d "${TMPDIR:-/tmp}/archie-package-shape.XXXXXX")
|
||||
trap 'rm -rf "$temporary"' EXIT HUP INT TERM
|
||||
mkdir -p "$temporary/cache" "$temporary/build-tmp"
|
||||
|
||||
export GOCACHE="$temporary/cache"
|
||||
export GOTMPDIR="$temporary/build-tmp"
|
||||
export GOPROXY=off
|
||||
export GOFLAGS="-mod=readonly -buildvcs=false"
|
||||
export ARCHIE_DISCOVERY_CACHE="$temporary/discovery"
|
||||
|
||||
(
|
||||
cd "$module_root"
|
||||
go list ./... | LC_ALL=C sort
|
||||
) >"$temporary/packages"
|
||||
if (
|
||||
cd "$module_root"
|
||||
"$edge_helper" ./...
|
||||
) >"$temporary/edges" 2>"$temporary/edge-stderr"; then
|
||||
# The sibling helper sets its own GOFLAGS and can trigger a harmless,
|
||||
# nondeterministic temporary filename when GOMODCACHE is read-only.
|
||||
# Preserve the warning while normalizing only that filename suffix.
|
||||
sed 's/\.info[0-9][0-9]*\.tmp/.info<TEMP>.tmp/' "$temporary/edge-stderr" >&2
|
||||
else
|
||||
status=$?
|
||||
cat "$temporary/edge-stderr" >&2
|
||||
exit "$status"
|
||||
fi
|
||||
(
|
||||
cd "$module_root"
|
||||
go list -m -f '{{.Path}}'
|
||||
) >"$temporary/module"
|
||||
|
||||
module_path=$(sed -n '1p' "$temporary/module")
|
||||
printf '%s\n' "META schema archie-package-shape/v1"
|
||||
printf 'META\tmodule\t%s\n' "$module_path"
|
||||
|
||||
awk -F ' ' '
|
||||
NR == FNR {
|
||||
packages[$0] = 1
|
||||
next
|
||||
}
|
||||
{
|
||||
split($0, edge, " -> ")
|
||||
outbound[edge[1]]++
|
||||
inbound[edge[2]]++
|
||||
}
|
||||
END {
|
||||
for (packageName in packages) {
|
||||
printf "PACKAGE\t%s\t%d\t%d\n", packageName, inbound[packageName] + 0, outbound[packageName] + 0
|
||||
}
|
||||
}
|
||||
' "$temporary/packages" "$temporary/edges" | LC_ALL=C sort
|
||||
|
||||
awk '{printf "EDGE\t%s\n", $0}' "$temporary/edges"
|
||||
@@ -1,357 +0,0 @@
|
||||
// Command source-metrics emits deterministic, syntax-derived Go source metrics.
|
||||
// It never writes to the inspected tree and uses only the Go standard library.
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"flag"
|
||||
"fmt"
|
||||
"go/ast"
|
||||
"go/parser"
|
||||
"go/token"
|
||||
"io/fs"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"sort"
|
||||
"strings"
|
||||
)
|
||||
|
||||
type counts struct {
|
||||
productionFiles int
|
||||
testFiles int
|
||||
generatedFiles int
|
||||
productionLines int
|
||||
testLines int
|
||||
generatedLines int
|
||||
functions int
|
||||
methods int
|
||||
}
|
||||
|
||||
type packageCounts struct {
|
||||
module string
|
||||
path string
|
||||
productionFiles int
|
||||
testFiles int
|
||||
generatedFiles int
|
||||
productionLines int
|
||||
testLines int
|
||||
generatedLines int
|
||||
}
|
||||
|
||||
type hotspot struct {
|
||||
module string
|
||||
path string
|
||||
line int
|
||||
symbol string
|
||||
spanLines int
|
||||
statements int
|
||||
complexity int
|
||||
}
|
||||
|
||||
func main() {
|
||||
root := flag.String("root", ".", "repository root to inspect")
|
||||
top := flag.Int("top", 30, "maximum hotspot rows; zero means all")
|
||||
largeLines := flag.Int("large-lines", 80, "minimum body span for a hotspot")
|
||||
complexity := flag.Int("complexity", 15, "minimum approximate syntactic complexity for a hotspot")
|
||||
includeTests := flag.Bool("include-test-hotspots", false, "include test functions in hotspot rows")
|
||||
flag.Parse()
|
||||
|
||||
if *top < 0 || *largeLines < 1 || *complexity < 1 {
|
||||
fail(2, "top must be non-negative; thresholds must be positive")
|
||||
}
|
||||
|
||||
absoluteRoot, err := filepath.Abs(*root)
|
||||
if err != nil {
|
||||
fail(2, "resolve root: %v", err)
|
||||
}
|
||||
info, err := os.Stat(absoluteRoot)
|
||||
if err != nil {
|
||||
fail(2, "inspect root: %v", err)
|
||||
}
|
||||
if !info.IsDir() {
|
||||
fail(2, "root is not a directory: %s", absoluteRoot)
|
||||
}
|
||||
|
||||
modules := map[string]*counts{}
|
||||
packages := map[string]*packageCounts{}
|
||||
var hotspots []hotspot
|
||||
fset := token.NewFileSet()
|
||||
|
||||
err = filepath.WalkDir(absoluteRoot, func(path string, entry fs.DirEntry, walkErr error) error {
|
||||
if walkErr != nil {
|
||||
return walkErr
|
||||
}
|
||||
relative, err := filepath.Rel(absoluteRoot, path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
relative = filepath.ToSlash(relative)
|
||||
if entry.IsDir() {
|
||||
if relative != "." && excludedDirectory(relative, entry.Name()) {
|
||||
return filepath.SkipDir
|
||||
}
|
||||
return nil
|
||||
}
|
||||
if filepath.Ext(entry.Name()) != ".go" {
|
||||
return nil
|
||||
}
|
||||
|
||||
body, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
file, err := parser.ParseFile(fset, path, body, parser.ParseComments)
|
||||
if err != nil {
|
||||
return fmt.Errorf("parse %s: %w", relative, err)
|
||||
}
|
||||
|
||||
module := moduleFor(relative)
|
||||
moduleCounts := modules[module]
|
||||
if moduleCounts == nil {
|
||||
moduleCounts = &counts{}
|
||||
modules[module] = moduleCounts
|
||||
}
|
||||
dir := filepath.ToSlash(filepath.Dir(relative))
|
||||
packageKey := module + "\x00" + dir
|
||||
pkg := packages[packageKey]
|
||||
if pkg == nil {
|
||||
pkg = &packageCounts{module: module, path: dir}
|
||||
packages[packageKey] = pkg
|
||||
}
|
||||
|
||||
lines := physicalLines(body)
|
||||
generated := ast.IsGenerated(file)
|
||||
isTest := strings.HasSuffix(entry.Name(), "_test.go")
|
||||
switch {
|
||||
case generated:
|
||||
moduleCounts.generatedFiles++
|
||||
moduleCounts.generatedLines += lines
|
||||
pkg.generatedFiles++
|
||||
pkg.generatedLines += lines
|
||||
case isTest:
|
||||
moduleCounts.testFiles++
|
||||
moduleCounts.testLines += lines
|
||||
pkg.testFiles++
|
||||
pkg.testLines += lines
|
||||
default:
|
||||
moduleCounts.productionFiles++
|
||||
moduleCounts.productionLines += lines
|
||||
pkg.productionFiles++
|
||||
pkg.productionLines += lines
|
||||
}
|
||||
|
||||
for _, declaration := range file.Decls {
|
||||
function, ok := declaration.(*ast.FuncDecl)
|
||||
if !ok || function.Body == nil {
|
||||
continue
|
||||
}
|
||||
if function.Recv == nil {
|
||||
moduleCounts.functions++
|
||||
} else {
|
||||
moduleCounts.methods++
|
||||
}
|
||||
if generated || (isTest && !*includeTests) {
|
||||
continue
|
||||
}
|
||||
|
||||
start := fset.Position(function.Body.Lbrace).Line
|
||||
end := fset.Position(function.Body.Rbrace).Line
|
||||
row := hotspot{
|
||||
module: module,
|
||||
path: relative,
|
||||
line: fset.Position(function.Pos()).Line,
|
||||
symbol: symbolName(function),
|
||||
spanLines: end - start + 1,
|
||||
statements: statementNodes(function.Body),
|
||||
complexity: syntacticComplexity(function.Body),
|
||||
}
|
||||
if row.spanLines >= *largeLines || row.complexity >= *complexity {
|
||||
hotspots = append(hotspots, row)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
})
|
||||
if err != nil {
|
||||
fail(1, "%v", err)
|
||||
}
|
||||
|
||||
fmt.Println("META\tschema\tarchie-source-metrics/v1")
|
||||
fmt.Printf("META\tthresholds\tlarge_lines=%d;syntactic_complexity=%d;top=%d\n", *largeLines, *complexity, *top)
|
||||
|
||||
moduleNames := sortedKeys(modules)
|
||||
for _, module := range moduleNames {
|
||||
value := modules[module]
|
||||
emitMetric(module, "production_go_files", value.productionFiles)
|
||||
emitMetric(module, "test_go_files", value.testFiles)
|
||||
emitMetric(module, "generated_go_files", value.generatedFiles)
|
||||
emitMetric(module, "production_physical_lines", value.productionLines)
|
||||
emitMetric(module, "test_physical_lines", value.testLines)
|
||||
emitMetric(module, "generated_physical_lines", value.generatedLines)
|
||||
emitMetric(module, "functions", value.functions)
|
||||
emitMetric(module, "methods", value.methods)
|
||||
}
|
||||
|
||||
packageRows := make([]*packageCounts, 0, len(packages))
|
||||
for _, row := range packages {
|
||||
packageRows = append(packageRows, row)
|
||||
}
|
||||
sort.Slice(packageRows, func(i, j int) bool {
|
||||
if packageRows[i].module != packageRows[j].module {
|
||||
return packageRows[i].module < packageRows[j].module
|
||||
}
|
||||
return packageRows[i].path < packageRows[j].path
|
||||
})
|
||||
for _, row := range packageRows {
|
||||
fmt.Printf(
|
||||
"PACKAGE\t%s\t%s\t%d\t%d\t%d\t%d\t%d\t%d\n",
|
||||
row.module,
|
||||
row.path,
|
||||
row.productionFiles,
|
||||
row.testFiles,
|
||||
row.generatedFiles,
|
||||
row.productionLines,
|
||||
row.testLines,
|
||||
row.generatedLines,
|
||||
)
|
||||
}
|
||||
|
||||
sort.Slice(hotspots, func(i, j int) bool {
|
||||
if hotspots[i].spanLines != hotspots[j].spanLines {
|
||||
return hotspots[i].spanLines > hotspots[j].spanLines
|
||||
}
|
||||
if hotspots[i].complexity != hotspots[j].complexity {
|
||||
return hotspots[i].complexity > hotspots[j].complexity
|
||||
}
|
||||
if hotspots[i].path != hotspots[j].path {
|
||||
return hotspots[i].path < hotspots[j].path
|
||||
}
|
||||
if hotspots[i].line != hotspots[j].line {
|
||||
return hotspots[i].line < hotspots[j].line
|
||||
}
|
||||
return hotspots[i].symbol < hotspots[j].symbol
|
||||
})
|
||||
if *top > 0 && len(hotspots) > *top {
|
||||
hotspots = hotspots[:*top]
|
||||
}
|
||||
for _, row := range hotspots {
|
||||
fmt.Printf(
|
||||
"HOTSPOT\t%s\t%s\t%d\t%s\t%d\t%d\t%d\n",
|
||||
row.module,
|
||||
row.path,
|
||||
row.line,
|
||||
row.symbol,
|
||||
row.spanLines,
|
||||
row.statements,
|
||||
row.complexity,
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
// excludedDirectory reports whether a walked directory is outside the module.
|
||||
//
|
||||
// ".worktrees" holds live git worktrees of this same repository, nested inside
|
||||
// the root. Each is a near-complete copy of the module, so walking them
|
||||
// multiplies every count by the number of checkout worktrees and floods the
|
||||
// HOTSPOT and PACKAGE rows with duplicates of the same declarations.
|
||||
func excludedDirectory(_, name string) bool {
|
||||
switch name {
|
||||
case ".git", ".claude", ".references", "node_modules", "vendor", ".gotmp", ".worktrees":
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
func moduleFor(relative string) string {
|
||||
if relative == "tools" || strings.HasPrefix(relative, "tools/") {
|
||||
return "tools"
|
||||
}
|
||||
return "root"
|
||||
}
|
||||
|
||||
func physicalLines(body []byte) int {
|
||||
if len(body) == 0 {
|
||||
return 0
|
||||
}
|
||||
lines := bytes.Count(body, []byte{'\n'})
|
||||
if body[len(body)-1] != '\n' {
|
||||
lines++
|
||||
}
|
||||
return lines
|
||||
}
|
||||
|
||||
func symbolName(function *ast.FuncDecl) string {
|
||||
if function.Recv == nil || len(function.Recv.List) == 0 {
|
||||
return function.Name.Name
|
||||
}
|
||||
return receiverName(function.Recv.List[0].Type) + "." + function.Name.Name
|
||||
}
|
||||
|
||||
func receiverName(expression ast.Expr) string {
|
||||
switch value := expression.(type) {
|
||||
case *ast.Ident:
|
||||
return value.Name
|
||||
case *ast.StarExpr:
|
||||
return "*" + receiverName(value.X)
|
||||
case *ast.IndexExpr:
|
||||
return receiverName(value.X)
|
||||
case *ast.IndexListExpr:
|
||||
return receiverName(value.X)
|
||||
default:
|
||||
return "receiver"
|
||||
}
|
||||
}
|
||||
|
||||
func statementNodes(node ast.Node) int {
|
||||
count := 0
|
||||
ast.Inspect(node, func(candidate ast.Node) bool {
|
||||
statement, ok := candidate.(ast.Stmt)
|
||||
if !ok {
|
||||
return true
|
||||
}
|
||||
switch statement.(type) {
|
||||
case *ast.BlockStmt, *ast.EmptyStmt:
|
||||
default:
|
||||
count++
|
||||
}
|
||||
return true
|
||||
})
|
||||
return count
|
||||
}
|
||||
|
||||
func syntacticComplexity(node ast.Node) int {
|
||||
value := 1
|
||||
ast.Inspect(node, func(candidate ast.Node) bool {
|
||||
switch item := candidate.(type) {
|
||||
case *ast.IfStmt, *ast.ForStmt, *ast.RangeStmt, *ast.CommClause:
|
||||
value++
|
||||
case *ast.CaseClause:
|
||||
if len(item.List) > 0 {
|
||||
value++
|
||||
}
|
||||
case *ast.BinaryExpr:
|
||||
if item.Op == token.LAND || item.Op == token.LOR {
|
||||
value++
|
||||
}
|
||||
}
|
||||
return true
|
||||
})
|
||||
return value
|
||||
}
|
||||
|
||||
func sortedKeys(values map[string]*counts) []string {
|
||||
keys := make([]string, 0, len(values))
|
||||
for key := range values {
|
||||
keys = append(keys, key)
|
||||
}
|
||||
sort.Strings(keys)
|
||||
return keys
|
||||
}
|
||||
|
||||
func emitMetric(module, name string, value int) {
|
||||
fmt.Printf("METRIC\t%s\t%s\t%d\n", module, name, value)
|
||||
}
|
||||
|
||||
func fail(code int, format string, arguments ...any) {
|
||||
fmt.Fprintf(os.Stderr, "source-metrics: "+format+"\n", arguments...)
|
||||
os.Exit(code)
|
||||
}
|
||||
@@ -1,201 +0,0 @@
|
||||
---
|
||||
name: archie-docs-and-writing
|
||||
description: Maintain Archie's documentation of record and write durable architecture decisions, migration plans, parity matrices, incident and dead-end records, feature ownership and deprecation records, operational runbooks, and documentation reviews. Use when deciding where an Archie fact belongs; reconciling code with `CLAUDE.md`, `docs/architecture`, `docs/prds`, `docs/archive`, or generated contracts; changing `tools/docsgen`; documenting a feature so future maintainers can find its owners, consumers, invariants, superseded paths, deletion gates, evidence, and rollback; or checking documentation authority, drift, links, copied content, and source-artifact hygiene.
|
||||
---
|
||||
|
||||
# Maintain Archie documentation
|
||||
|
||||
Write one durable record for each decision or behaviour. Separate what runs now
|
||||
from what Archie has approved as its destination.
|
||||
|
||||
Route to `archie-architecture-planning-campaign` for ownership/boundary
|
||||
decisions (parked outside this checkout, under
|
||||
`/work/apps/archie-skills-parked/`),
|
||||
`archie-architecture-contract` for invariants,
|
||||
`archie-codebase-discovery` for live entry points,
|
||||
`archie-failure-archaeology` for incidents,
|
||||
`archie-config-and-flags`, `archie-build-and-env`, or `archie-run-and-operate`
|
||||
for runtime/operations facts.
|
||||
|
||||
## Use the authority vocabulary
|
||||
|
||||
Define a **record of authority** as the one canonical location whose owner may
|
||||
change a claim.
|
||||
|
||||
| State | Meaning | Permitted wording |
|
||||
| ----------------- | -------------------------------------------------------------------------------- | ---------------------------------------------- |
|
||||
| `CURRENT` | Verified behaviour in checked-out code, tests, composition, or executable config | "Currently does" |
|
||||
| `APPROVED TARGET` | Normative destination approved in architecture index | "Must become"; never "currently does" |
|
||||
| `OPEN` | Investigation, candidate, or unresolved decision | "Candidate", "unknown", or "requires decision" |
|
||||
| `HISTORICAL` | Prior design, incident, dead end, or superseded choice | "Previously did" |
|
||||
| `GENERATED` | Derivative output produced from owned source definition | "Generated from"; never hand-edit |
|
||||
| `EXTERNAL` | Fact held outside repository, such as deployed config or host state | Date, name verifier, give re-check command |
|
||||
|
||||
When `CURRENT` conflicts with `APPROVED TARGET`, preserve both and state the
|
||||
migration delta.
|
||||
|
||||
## Use the repository authority map
|
||||
|
||||
Verified on 2026-09-18:
|
||||
|
||||
| Location | Role | Discipline |
|
||||
| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
||||
| Live Go code, tests, `Taskfile.yml`, executable config parsing, composition under `internal/app/` (entered from `cmd/`) | `CURRENT` execution evidence | Trace producers and consumers; tests prove only asserted behaviour |
|
||||
| `CLAUDE.md` | Current contributor and safety protocol plus compact architecture orientation | Verify operational claims against code and `Taskfile.yml`; `AGENTS.md` is a symlink to it |
|
||||
| `docs/prds/01-project-management.md` | Index and approved foundation for target architecture | Add or change target decisions in the focused document it names |
|
||||
| `docs/architecture/*.md` | Focused target decisions, active review procedure, migration inventory | Read each file's status |
|
||||
| `docs/architecture/migration-decisions.md` | `OPEN` migration inventory constrained by approved decisions | Close a question only after code-grounded review |
|
||||
| `docs/archive/` | `HISTORICAL` material | Mine rationale and failure evidence |
|
||||
| `CHANGELOG.md` | Release stream and packaged runtime input | One file holds every release; `internal/releaseannounce` parses version headings |
|
||||
| `tools/docsgen` | Current, partial generator in nested `tools` Go module | Treat its flags and tests—not planned PRD commands—as executable truth |
|
||||
| `docs/data/generated/contracts.json` | Current working-tree `GENERATED` output | Regenerate; never edit by hand |
|
||||
| `docs/` | Markdown sources and generated JSON for the external Astro website | This repository generates and validates artifacts; the website repository renders and deploys them |
|
||||
|
||||
The repository root has no `README.md` or `CONTRIBUTING.md` as of 2026-09-18.
|
||||
|
||||
## Choose one destination
|
||||
|
||||
1. State the reader's question.
|
||||
2. Identify the owner of the behaviour or decision.
|
||||
3. Find the existing record of authority.
|
||||
4. Extend that record or link to it. Do not make a second canonical table.
|
||||
5. If no owner exists, route the ownership decision through the architecture campaign.
|
||||
6. If the fact is generated, change the owned source definition and generator.
|
||||
7. If the fact is external, date it and name the exact observation command.
|
||||
|
||||
| Content | Destination |
|
||||
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Cross-cutting approved architecture index | `docs/prds/01-project-management.md` |
|
||||
| New capability with no settled design yet (CLAUDE.md's "write a decisive doc before coding") | New `docs/prds/<capability>.md` — use the PRD template in `references/templates.md`, which folds in a multi-agent execution breakdown so the sub-issues can be picked up without re-deriving the design |
|
||||
| Focused domain or requirement decision | Matching `docs/architecture/*.md` file |
|
||||
| Unresolved migration question | `docs/architecture/migration-decisions.md` |
|
||||
| Contributor protocol that must load before work | `CLAUDE.md` |
|
||||
| Runtime/API/config reference derivable from code | Domain-owned registry/type, then `tools/docsgen` output |
|
||||
| Repository documentation prose | `docs/`, linking back to authority with repository-relative paths |
|
||||
| Shipped release behaviour | Matching component changelog; keep `CHANGELOG.md` as two-component index |
|
||||
| Superseded design retained for context | `docs/archive/`, with historical status |
|
||||
| Incident or rejected approach | `archie-failure-archaeology`'s chronology |
|
||||
|
||||
Do not duplicate a package map across `CLAUDE.md`, a PRD, and
|
||||
the site. Name the authoritative map and link to it.
|
||||
|
||||
## Write for future change
|
||||
|
||||
Every architecture, feature, or migration record must answer:
|
||||
|
||||
- **Responsibility:** What cohesive job exists?
|
||||
- **Owner:** Which domain, application boundary, or infrastructure adapter owns
|
||||
its meaning and mutable state?
|
||||
- **Boundaries:** What is explicitly inside and outside?
|
||||
- **Consumers:** Which entry points, interfaces, commands, events, config, and
|
||||
processes depend on it?
|
||||
- **Invariants:** What must remain true, and where is each enforced?
|
||||
- **Superseded path:** Which older mechanism becomes redundant?
|
||||
- **Deletion gate:** What observable proof permits removal?
|
||||
- **Evidence:** Which symbols, tests, commands, and runtime observations support
|
||||
the record?
|
||||
- **Rollback:** How can behaviour and data return safely?
|
||||
- **Unresolved questions:** What remains `OPEN`?
|
||||
|
||||
Name one owner for every mutable record. A new path is incomplete until the
|
||||
document says whether each older path remains, delegates, migrates, or is
|
||||
deleted.
|
||||
|
||||
## Cite evidence without freezing line numbers
|
||||
|
||||
Prefer: repository-relative path plus exact Go symbol, test name, config key,
|
||||
workflow job/step, or Markdown heading; a relative Markdown link to the record
|
||||
of authority; the command that re-discovers the evidence.
|
||||
|
||||
Write `internal/agentexec.Request` and `tools/docsgen.currentContractTypes`.
|
||||
Distinguish evidence strength:
|
||||
|
||||
1. Runtime composition and executable behaviour.
|
||||
2. Tests that exercise the relevant production seam.
|
||||
3. Approved target decision.
|
||||
4. Comments and summaries corroborated by the first three.
|
||||
5. Historical or external notes, explicitly dated.
|
||||
|
||||
## Maintain component changelogs
|
||||
|
||||
Keep every release's notes in `CHANGELOG.md`; a release is one version, and
|
||||
the components' entries are labelled sections inside it.
|
||||
`Dockerfile.archied` copies it to `/usr/share/archie/`, and
|
||||
`internal/releaseannounce.changelogSection` parses a version heading.
|
||||
|
||||
Version-heading format is settled as of 2026-09-18: the changelog uses
|
||||
`## [1.27.0]` with no `v` prefix, `changelogSection` searches for
|
||||
`## [<version>]`, and `.github/workflows/deploy.yml` gates each release tag with
|
||||
`grep -q "^## \[$ver\]" CHANGELOG.md`. The earlier
|
||||
`vX.Y.Z`-vs-`X.Y.Z` contradiction involved `.gitea/workflows/deploy.yml`, which
|
||||
was dropped (`dd9bddc2 ci: build and push images to GHCR, drop the Gitea
|
||||
workflow`), so that question is `HISTORICAL`, not `OPEN`. The remaining guard is
|
||||
the CI shell gate plus `internal/releaseannounce`'s announcer tests
|
||||
(`TestAnnouncerReportsMissingReleaseSectionWithoutAdvancingState`); the old
|
||||
`cmd/archied.TestChangelogsTrackGatewayAndRuntimeIndependently` no longer exists.
|
||||
|
||||
## Maintain generated contracts
|
||||
|
||||
Current behaviour, verified 2026-09-18:
|
||||
|
||||
- Tool path is `tools/docsgen`, not `tools/cmd/docsgen`.
|
||||
- Separate Go module replacing root module with `../`.
|
||||
- Accepts `--repo-root` and `--out`, plus a `check` subcommand that compares
|
||||
against the committed artifact without writing. No implemented `data`,
|
||||
`asyncapi`, or `all` subcommands.
|
||||
- `currentContractTypes` publishes three top-level contracts and collects
|
||||
referenced schemas into one JSON object.
|
||||
- Default output is `docs/data/generated/contracts.json`.
|
||||
|
||||
```bash
|
||||
GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools test -mod=readonly ./docsgen -count=1
|
||||
task docs:check # fails loudly, and names the Go type behind each mismatch
|
||||
```
|
||||
|
||||
`docsgen check` and the `docs:generate`/`docs:check` tasks are implemented, and
|
||||
`task check` runs `docs:check` — generated drift is gated. `docsgen data`,
|
||||
`docsgen asyncapi`, and `docsgen all` remain `APPROVED TARGET`.
|
||||
|
||||
The check is deliberately non-destructive: it generates into a temporary
|
||||
directory, so a failing gate never rewrites the artifact it judges. Fix a
|
||||
failure with `task docs:generate` and commit the result with the code change
|
||||
that shifted the contract surface.
|
||||
|
||||
## Maintain documentation consumed by the external Astro website
|
||||
|
||||
`docs/` holds Markdown sources and generated JSON consumed by the Astro website
|
||||
at `offloaded.dev/docs/`. The website is maintained outside this repository.
|
||||
This repository owns artifact generation and drift checks; it does not build,
|
||||
preview, or deploy the website.
|
||||
|
||||
| Surface | Current state |
|
||||
| ---------------- | ---------------------------------------------------------------------- |
|
||||
| Content | Markdown under `docs/` and generated JSON under `docs/data/generated/` |
|
||||
| Rendering | External Astro website consumes generated artifacts |
|
||||
| Build and deploy | Owned by the Astro website repository |
|
||||
| Local checks | `task docs:check`, `task docs:artifact:check`, and `task news:check` |
|
||||
|
||||
The repository checks artifact drift, not the external site's rendered routes or
|
||||
links. Verify those in the website repository.
|
||||
|
||||
```bash
|
||||
# every relative markdown link target that does not resolve
|
||||
grep -rhoE '\]\([^)#]+' docs --include=*.md | sed -E 's/^\]\(//' | sort -u
|
||||
```
|
||||
|
||||
### Enforce source-artifact hygiene
|
||||
|
||||
Git tracks no `node_modules` entries or website build output. The external Astro
|
||||
repository owns its installed dependencies and generated site files.
|
||||
|
||||
```bash
|
||||
git ls-files | grep -c node_modules # expect 0
|
||||
ls docs/package.json docs/pnpm-lock.yaml 2>&1 # expect: No such file
|
||||
ls .github/workflows/ # expect deploy.yml only
|
||||
```
|
||||
|
||||
Historical mentions of VitePress in `docs/architecture/` are deliberate — they
|
||||
record what was removed. A grep for the word alone is not a failure signal.
|
||||
|
||||
Never stage dependency installs, renderer output, generator scratch files,
|
||||
credentials, absolute paths, wall-clock data, or machine-specific values.
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "Archie Docs and Writing"
|
||||
short_description: "Maintain authoritative Archie documentation"
|
||||
default_prompt: "Use $archie-docs-and-writing to write or update an authoritative Archie design, migration, incident, ownership, or operations document."
|
||||
@@ -1,485 +0,0 @@
|
||||
# Archie durable-writing templates
|
||||
|
||||
Use one template at a time. Replace every angle-bracket prompt. Remove unused
|
||||
sections. Keep facts, decisions, and open questions visibly separate.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Architecture decision record](#architecture-decision-record)
|
||||
- [Migration plan and parity matrix](#migration-plan-and-parity-matrix)
|
||||
- [Incident or dead-end record](#incident-or-dead-end-record)
|
||||
- [Feature ownership and deprecation record](#feature-ownership-and-deprecation-record)
|
||||
- [Operational runbook](#operational-runbook)
|
||||
- [Documentation change review](#documentation-change-review)
|
||||
- [PRD: open capability design with multi-agent execution](#prd-open-capability-design-with-multi-agent-execution)
|
||||
|
||||
## Architecture decision record
|
||||
|
||||
```markdown
|
||||
# <Decision title>
|
||||
|
||||
**Status:** Proposed | Approved | Superseded by <link>
|
||||
**Date:** YYYY-MM-DD
|
||||
**Owner:** <domain or application boundary>
|
||||
**Record of authority:** <this document or existing focused document>
|
||||
**Change-control reference:** <issue/review identifier>
|
||||
|
||||
## Decision
|
||||
|
||||
<One unambiguous normative statement.>
|
||||
|
||||
## Problem and scope
|
||||
|
||||
<Describe the problem, the included behavior, and explicit non-goals.>
|
||||
|
||||
## Current evidence
|
||||
|
||||
| Claim | Evidence |
|
||||
| ------------------ | ------------------------------------- |
|
||||
| <CURRENT behavior> | `<path>` — `<symbol/test/config key>` |
|
||||
|
||||
## Constraints and invariants
|
||||
|
||||
- <Invariant and where it is enforced>
|
||||
|
||||
## Consumers and boundaries
|
||||
|
||||
| Consumer | Contract used | Failure effect |
|
||||
| ----------------------------- | ------------------------------ | -------------- |
|
||||
| <entry point/package/process> | <interface/command/event/data> | <effect> |
|
||||
|
||||
## Options considered
|
||||
|
||||
| Option | Benefits | Costs and risks | Evidence | Result |
|
||||
| -------- | --------- | --------------- | -------------------- | ------------------- |
|
||||
| <option> | <benefit> | <cost> | <measurement/source> | Accepted / Rejected |
|
||||
|
||||
## Consequences
|
||||
|
||||
<State new responsibilities, dependency direction, state ownership, and
|
||||
operational effects.>
|
||||
|
||||
## Supersession and deletion
|
||||
|
||||
- Superseded path: `<path/symbol>` or none
|
||||
- Compatibility owner: <owner or none>
|
||||
- Deletion gate: <observable proof>
|
||||
- Architecture test: <test or OPEN>
|
||||
|
||||
## Rollback
|
||||
|
||||
<State how code, behavior, and data return safely.>
|
||||
|
||||
## Open questions
|
||||
|
||||
| Question | Owner | Evidence required | Decision deadline/gate |
|
||||
| --------------- | ------- | ----------------- | ---------------------- |
|
||||
| <OPEN question> | <owner> | <measurement> | <gate> |
|
||||
|
||||
## Validation
|
||||
|
||||
- `<exact command>` — expected <observable result>
|
||||
```
|
||||
|
||||
## Migration plan and parity matrix
|
||||
|
||||
```markdown
|
||||
# <Capability> migration plan
|
||||
|
||||
**Status:** Proposed | Approved | In progress | Complete
|
||||
**Date:** YYYY-MM-DD
|
||||
**Owner:** <domain>
|
||||
**Source authority:** <approved target decision>
|
||||
**Current baseline:** <code paths and runtime composition>
|
||||
|
||||
## Outcome
|
||||
|
||||
<Describe the final single authoritative path and what becomes easier to
|
||||
change.>
|
||||
|
||||
## Current-path inventory
|
||||
|
||||
| Operation | Entry point | Owner today | State/data touched | Consumers | Disposition |
|
||||
| ----------- | --------------- | ------------ | ------------------ | ----------- | ----------------------------- |
|
||||
| <operation> | `<path.Symbol>` | <owner/none> | <state> | <consumers> | Keep / Adapt / Merge / Delete |
|
||||
|
||||
## Parity matrix
|
||||
|
||||
| Behavior | Current evidence | Target owner/path | Required parity | Test or observation | Status |
|
||||
| ---------- | ------------------- | ----------------- | --------------- | ------------------- | ------ |
|
||||
| <behavior> | `<test/symbol/log>` | <target> | <exact result> | `<command>` | OPEN |
|
||||
|
||||
Include success, validation failure, retry, cancellation, crash recovery,
|
||||
authorization, persistence, event emission, and shutdown where applicable.
|
||||
|
||||
## Dependency and data movement
|
||||
|
||||
| From | To | Adapter/backfill | Consistency rule | Rollback |
|
||||
| -------- | -------- | ---------------- | ---------------- | -------- |
|
||||
| <source> | <target> | <mechanism> | <invariant> | <method> |
|
||||
|
||||
## Slices and gates
|
||||
|
||||
### Slice 1 — <small vertical outcome>
|
||||
|
||||
- Change: <bounded change>
|
||||
- Expected evidence: <number/result predicted before implementation>
|
||||
- Command: `<exact command>`
|
||||
- Pass: <observable result>
|
||||
- Branch if not: <diagnostic route>
|
||||
- Legacy path after slice: Active / Delegating / Read-only / Removable
|
||||
|
||||
<Repeat for each independently reviewable slice.>
|
||||
|
||||
## Cutover
|
||||
|
||||
1. <Prepare compatibility/data>
|
||||
2. <Change production composition>
|
||||
3. <Observe explicit health/parity signals>
|
||||
4. <Disable legacy entry>
|
||||
5. <Delete only after the deletion gate>
|
||||
|
||||
## Deletion gates
|
||||
|
||||
| Legacy path | Replacement proof | Consumer-zero proof | Data proof | Removal test |
|
||||
| --------------- | ----------------- | ------------------- | ---------- | ------------ |
|
||||
| `<path.Symbol>` | <proof> | <search/inventory> | <proof> | `<command>` |
|
||||
|
||||
## Rollback and stop conditions
|
||||
|
||||
- Roll back when: <condition>
|
||||
- Restore: <code/config/data sequence>
|
||||
- Preserve for diagnosis: <artifacts>
|
||||
|
||||
## Remaining open decisions
|
||||
|
||||
| Decision | Owner | Evidence needed | Blocks |
|
||||
| -------- | ------- | --------------- | --------------- |
|
||||
| <OPEN> | <owner> | <evidence> | <slice/cutover> |
|
||||
```
|
||||
|
||||
## Incident or dead-end record
|
||||
|
||||
````markdown
|
||||
# <Symptom or rejected approach>
|
||||
|
||||
**Status:** Resolved | Mitigated | Rejected | Reopened
|
||||
**Observed:** YYYY-MM-DD
|
||||
**Last verified:** YYYY-MM-DD
|
||||
**Owner:** <capability>
|
||||
**Related changes:** <commit/issue/PR identifiers>
|
||||
|
||||
## Symptom and impact
|
||||
|
||||
<State the observable failure, affected path, and cost. Do not begin with the
|
||||
proposed fix.>
|
||||
|
||||
## Reproduction
|
||||
|
||||
```text
|
||||
<exact non-secret command or event sequence>
|
||||
```
|
||||
|
||||
Expected: <result>
|
||||
Observed: <result>
|
||||
|
||||
## Investigation chronology
|
||||
|
||||
| Time/order | Hypothesis | Prediction | Evidence | Result |
|
||||
| ---------- | ------------ | ---------------------- | -------------------- | -------------------- |
|
||||
| 1 | <hypothesis> | <expected observation> | `<command/log/test>` | Confirmed / Rejected |
|
||||
|
||||
## Root cause
|
||||
|
||||
<Name the owning code path and causal mechanism. Separate cause from trigger.>
|
||||
|
||||
## Attempted or rejected fixes
|
||||
|
||||
| Fix | Why plausible | Evidence against it | Status |
|
||||
| ---------- | ------------- | ----------------------- | ------------------- |
|
||||
| <approach> | <reason> | <test/runtime evidence> | Rejected / Reverted |
|
||||
|
||||
## Resolution and invariant
|
||||
|
||||
- Resolution: <what changed>
|
||||
- Preserved invariant: <what must not regress>
|
||||
- Regression test: `<test name/path>`
|
||||
- Operational signal: <log/metric/state>
|
||||
|
||||
## Reopen condition
|
||||
|
||||
<State the evidence that would justify revisiting the settled result.>
|
||||
````
|
||||
|
||||
## Feature ownership and deprecation record
|
||||
|
||||
```markdown
|
||||
# <Feature/capability> ownership
|
||||
|
||||
**Status:** Current | Migrating | Deprecated | Removed
|
||||
**Date:** YYYY-MM-DD
|
||||
**Behavior owner:** <domain>
|
||||
**State owner:** <domain/repository>
|
||||
**Composition owner:** <application boundary>
|
||||
|
||||
## Responsibility and non-responsibilities
|
||||
|
||||
- Owns: <cohesive behavior>
|
||||
- Does not own: <adjacent concerns>
|
||||
|
||||
## Complete path
|
||||
|
||||
| Layer | Path/symbol | Responsibility |
|
||||
| ----------- | --------------- | -------------- |
|
||||
| Entry | `<path.Symbol>` | <role> |
|
||||
| Domain | `<path.Symbol>` | <role> |
|
||||
| State | `<path.Symbol>` | <role> |
|
||||
| Adapter | `<path.Symbol>` | <role> |
|
||||
| Composition | `<path.Symbol>` | <role> |
|
||||
|
||||
## Consumers
|
||||
|
||||
| Consumer | Contract | Configuration | Test evidence |
|
||||
| ---------- | ---------------------- | ------------- | ------------- |
|
||||
| <consumer> | <interface/event/data> | <key or none> | `<test>` |
|
||||
|
||||
## Invariants and failures
|
||||
|
||||
| Invariant | Enforcement | Failure behavior | Test |
|
||||
| ----------- | --------------- | ---------------- | -------- |
|
||||
| <invariant> | `<path.Symbol>` | <result> | `<test>` |
|
||||
|
||||
## Duplicate and superseded paths
|
||||
|
||||
| Path | Same operation? | Disposition | Deletion gate |
|
||||
| --------------- | -------------------------- | ---------------------------------- | ------------- |
|
||||
| `<path.Symbol>` | Yes / No, because <reason> | Keep / Delegate / Migrate / Delete | <proof> |
|
||||
|
||||
## Change checklist
|
||||
|
||||
- [ ] Trace every entry point and consumer.
|
||||
- [ ] Decide whether the feature deprecates earlier work.
|
||||
- [ ] Keep one owner for mutable state.
|
||||
- [ ] Add failure-path and architecture tests.
|
||||
- [ ] Prove the replacement before deleting the old path.
|
||||
- [ ] Update generated reference from owned definitions.
|
||||
```
|
||||
|
||||
## Operational runbook
|
||||
|
||||
```markdown
|
||||
# Operate <service/capability>
|
||||
|
||||
**Status:** Current
|
||||
**Last verified:** YYYY-MM-DD
|
||||
**Environment:** <local/staging/production>
|
||||
**Owner:** <operator/capability>
|
||||
**External sources:** <host/config/dashboard; no secrets>
|
||||
|
||||
## Purpose and safety boundary
|
||||
|
||||
<State what this runbook operates and what requires separate authorization.>
|
||||
|
||||
## Preconditions
|
||||
|
||||
- <access/tool/config precondition>
|
||||
- Secret names only; never secret values
|
||||
|
||||
## Start or change
|
||||
|
||||
1. Run `<exact command>`.
|
||||
2. Expect `<observable output/state>` within `<bounded interval>`.
|
||||
3. If `<alternate result>`, stop and route to `<diagnostic branch>`.
|
||||
|
||||
## Health and outputs
|
||||
|
||||
| Signal | Location/command | Healthy result | Unhealthy branch |
|
||||
| -------- | ---------------- | -------------- | ---------------- |
|
||||
| <signal> | `<command/path>` | <result> | <action> |
|
||||
|
||||
## Rollback
|
||||
|
||||
1. <Restore previous code/config/data>
|
||||
2. Run `<health command>`.
|
||||
3. Preserve <logs/artifacts> for incident review.
|
||||
|
||||
## Known failure modes
|
||||
|
||||
| Symptom | First measurement | Likely seam | Next runbook |
|
||||
| --------- | ----------------- | ----------- | ------------------- |
|
||||
| <symptom> | `<command>` | <boundary> | <sibling skill/doc> |
|
||||
|
||||
## Provenance
|
||||
|
||||
- External fact observed by <who/how> on YYYY-MM-DD.
|
||||
- Re-check: `<one-line command>`
|
||||
```
|
||||
|
||||
## Documentation change review
|
||||
|
||||
```markdown
|
||||
# Documentation review: <scope>
|
||||
|
||||
**Date:** YYYY-MM-DD
|
||||
**Reviewer:** <name/session>
|
||||
**Changed authority:** <path or none>
|
||||
|
||||
## Classification
|
||||
|
||||
| Claim/change | State | Owner | Evidence |
|
||||
| ------------ | -------------------------------------------------------------------- | ------- | ---------------------------- |
|
||||
| <claim> | CURRENT / APPROVED TARGET / OPEN / HISTORICAL / GENERATED / EXTERNAL | <owner> | `<path.Symbol/test/command>` |
|
||||
|
||||
## Findings
|
||||
|
||||
| Severity | Location | Problem | Evidence | Required correction |
|
||||
| ---------------------------- | -------------- | --------- | ---------- | ------------------- |
|
||||
| Blocking / Important / Minor | <heading/path> | <problem> | <evidence> | <fix> |
|
||||
|
||||
## Authority and duplication checks
|
||||
|
||||
- [ ] One record of authority owns each claim.
|
||||
- [ ] Current and target behavior are separated.
|
||||
- [ ] Open questions remain visibly open.
|
||||
- [ ] Historical material is not used normatively.
|
||||
- [ ] Generated output was not hand-edited.
|
||||
- [ ] Symbols and headings replace durable line-number citations.
|
||||
|
||||
## Maintainability checks
|
||||
|
||||
- [ ] Responsibility, owner, boundaries, consumers, and invariants are explicit.
|
||||
- [ ] Superseded paths and deletion gates are named.
|
||||
- [ ] Evidence, rollback, and unresolved questions are actionable.
|
||||
- [ ] A zero-context engineer can locate the complete feature path.
|
||||
|
||||
## Validation evidence
|
||||
|
||||
| Command | Expected | Observed |
|
||||
| ----------------- | -------- | -------- |
|
||||
| `<exact command>` | <result> | <result> |
|
||||
|
||||
## Residual uncertainty
|
||||
|
||||
<List unverified external facts, unavailable environments, or still-open
|
||||
decisions. Never convert them into implied acceptance.>
|
||||
```
|
||||
|
||||
## PRD: open capability design with multi-agent execution
|
||||
|
||||
For `docs/prds/*.md` — CLAUDE.md's "no settled design exists" doc. The point
|
||||
of this template is that a cheaper/faster model can implement straight from
|
||||
it without re-deriving architecture: every decision the epic left open gets
|
||||
made here, not deferred again, and every file an implementer touches is
|
||||
named before any bead is picked up. `docs/prds/image-capability-contract.md`
|
||||
is the worked example this template was extracted from — read it once for
|
||||
the shape before writing a new PRD from a blank page.
|
||||
|
||||
The three failure modes this template exists to prevent:
|
||||
|
||||
- **Deferred decisions posing as scope.** "Hosted provider implementation is
|
||||
a separate bead" is not a design decision, it's a missing one. If an open
|
||||
question blocks an implementer, decide it here, in the PRD — not "this bead
|
||||
will decide it later," which is how the same question gets re-opened by
|
||||
every bead that touches it.
|
||||
- **Assumed gaps.** Before writing a section for "what's missing," grep for
|
||||
it. `image-capability-contract.md`'s delivery section exists mostly because
|
||||
the pipeline it needed already shipped for video — the section reports
|
||||
that, instead of specifying new plumbing nothing required.
|
||||
- **Task lists a model can't execute standalone.** A subtask is not "wire the
|
||||
delivery path"; it's the file, the interface it must satisfy, and the
|
||||
existing call site that already proves the pattern (`internal/tools/minimax/tool.go`,
|
||||
not "a tool like the video one").
|
||||
|
||||
```markdown
|
||||
# <Capability> capability design
|
||||
|
||||
Epic: `<bd id>` / GitHub `#<epic number>` ("<epic title>").
|
||||
|
||||
<One paragraph: what shipped already and is settled (link its section
|
||||
below), what this document newly decides, and what stays explicitly
|
||||
out of scope. If a prior narrower doc already covers part of this
|
||||
capability, say so and extend it — do not start a second document for
|
||||
the same epic.>
|
||||
|
||||
## Problem
|
||||
|
||||
<What's missing today, with the exact "grep and found nothing" evidence,
|
||||
not an assertion.>
|
||||
|
||||
## Design
|
||||
|
||||
<The settled contract/type shape. Code blocks over prose where a type
|
||||
signature says more than describing it would.>
|
||||
|
||||
## <Sub-feature N> (`#<issue>`)
|
||||
|
||||
One section per sibling bead the epic lists as separate scope. Each one:
|
||||
|
||||
- **Decision, not a deferral.** If the epic or a prior doc left this open,
|
||||
decide it here and say why in one paragraph, citing what's actually in
|
||||
the tree (a similar client already in the codebase, an existing config
|
||||
convention, an interface already proven by another feature). "Decide and
|
||||
record which at that bead's own design-doc step" is the sentence this
|
||||
template exists to stop someone from writing twice.
|
||||
- **Call site**, named exactly: `<package/file>`, the function/type it adds
|
||||
or extends, and the existing analogous call site it follows (never "a
|
||||
handler like the others" — name the actual one).
|
||||
- **Reuse check.** Grep before specifying new plumbing. State what already
|
||||
exists and what's actually new, the way a delivery pipeline already
|
||||
proven by one media type doesn't need re-inventing for a second.
|
||||
- **Error/failure mapping**, as a table, when the sub-feature crosses a
|
||||
provider/backend boundary: condition → contract error, so an implementer
|
||||
never invents a new sentinel mid-way through.
|
||||
- **Testing.** What's fakeable vs. what needs a real backend, and which
|
||||
gate (`task check` vs. a documented manual smoke command) each belongs to.
|
||||
|
||||
## Call site inventory
|
||||
|
||||
| concern | file | change |
|
||||
| --------- | -------- | ------------------------------------------------------------------ |
|
||||
| <concern> | `<path>` | done (`#<issue>`) / new (`#<issue>`) / none — already handles this |
|
||||
|
||||
Every file any sub-feature touches, old or new, in one table — so an
|
||||
implementer greps this instead of re-deriving it, and a reviewer can tell
|
||||
at a glance whether a PR touched something the design didn't name.
|
||||
|
||||
## Execution: multi-agent team breakdown
|
||||
|
||||
One row per sub-feature section above. This is what turns the design into
|
||||
something a `/council`-style review or a cheaper/faster implementer model
|
||||
can run against directly instead of needing the full design re-explained.
|
||||
|
||||
| sub-feature | issue | implementer scope | suggested council lenses | why |
|
||||
| ----------- | ---------- | --------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <name> | `#<issue>` | <the call-site inventory rows this bead owns> | `lens-<key>`, `lens-<key>` | <one clause: what that lens actually catches for this slice — e.g. lens-contract for a new provider error-mapping table, lens-operator for a backend-down failure path, lens-deletionist when the section's whole point is "don't rebuild what exists", lens-boundary for a new domain/infra split, lens-maintainer for a new user-facing state machine> |
|
||||
|
||||
Pick lenses from the five in `.claude/workflows/council.js`
|
||||
(`boundary`, `contract`, `deletionist`, `operator`, `maintainer`) by what the
|
||||
slice actually risks getting wrong, not all five by default — a
|
||||
generate-and-poll HTTP client mostly risks failure-mode gaps
|
||||
(`lens-operator`), not domain-boundary violations. Run `/council` with
|
||||
`--lenses <picked>` once the implementation is gate-clean, before opening
|
||||
the PR for human review, same as any other open-decision residue at the
|
||||
end of a session.
|
||||
|
||||
An implementer working one row needs only: this doc's matching sub-feature
|
||||
section, the call-site inventory, and the linked issue's acceptance
|
||||
criteria. It should not need the rest of the epic's history — that's the
|
||||
signal the PRD is thorough enough to hand to a faster/cheaper model.
|
||||
|
||||
## File and link the beads
|
||||
|
||||
For each sub-feature issue already filed against the epic (or newly filed
|
||||
if the epic didn't pre-file its sub-issues):
|
||||
|
||||
- Issue body links back to this doc's matching section by heading, not by
|
||||
restating the design — `bd update <id> --description` and, if the issue
|
||||
also lives on the forge, keep both current (check whether this repo's
|
||||
sync command actually propagates a description edit before trusting it
|
||||
updated both; direct edit on both sides is the fallback).
|
||||
- Issue keeps its own acceptance criteria as the authoritative "done"
|
||||
check — the PRD section is how, the issue's criteria are whether.
|
||||
- Add the suggested lenses from the Execution table as a line on the issue
|
||||
itself, so picking it up needs no round-trip back to this doc to know
|
||||
which `/council` lenses to run before it's done.
|
||||
```
|
||||
@@ -1,242 +0,0 @@
|
||||
---
|
||||
name: archie-domain-reference
|
||||
description: "Use when naming, designing, reviewing, documenting, tracing, or migrating Archie concepts such as Agent, Identity, user, Message, Conversation, work intake, WorkflowExecution, plugin engines, channels, events, policy, forge, worktrees, or gates; when current task/gateway/store vocabulary conflicts with the approved architecture; or when a feature risks crossing domain ownership boundaries. Provides project-specific current-to-target mappings, ownership rules, lifecycle language, and glossary checks. Do not use for database API mechanics, general code tracing, config enumeration, debugging, or operations."
|
||||
---
|
||||
|
||||
# Archie Domain Reference
|
||||
|
||||
Use one meaning for each noun. Keep external-system words at adapters, keep
|
||||
domain meaning with its owner, and mark migration state explicitly.
|
||||
|
||||
## Classify every statement
|
||||
|
||||
As of 2026-09-18, Archie is partway through the domain migration: some approved
|
||||
target packages now exist and are production-wired (`internal/domain/messaging`,
|
||||
`internal/domain/workflow`, `internal/domain/workintake`, `internal/app`,
|
||||
`internal/eventbus`, `internal/infrastructure`), while others remain target-only
|
||||
(`internal/domain/agent`, `internal/domain/identity`, `internal/policy`). Never
|
||||
blend the two.
|
||||
|
||||
| Label | Meaning | Evidence rule |
|
||||
| ------------------- | ----------------------------------------------------- | ---------------------------------------------------------- |
|
||||
| **CURRENT** | Behaviour present in live code and tests | Cite defining type/function and production caller or test. |
|
||||
| **APPROVED TARGET** | Normative rule in approved foundation document | Cite exact PRD. Do not claim implemented. |
|
||||
| **OPEN/CANDIDATE** | Deferred API, owner, package, migration, or behaviour | Preserve open question. |
|
||||
| **ARCHIVED** | Historical context under `docs/archive/` | Use only for archaeology. |
|
||||
|
||||
Start design notes with status sentences:
|
||||
|
||||
```text
|
||||
CURRENT: task.Task persists one mutable Stage string.
|
||||
APPROVED TARGET: WorkflowExecution records StepExecution history.
|
||||
OPEN: the exact schema and Go API for that history.
|
||||
```
|
||||
|
||||
Read status markers:
|
||||
|
||||
```bash
|
||||
sed -n '1,180p' docs/prds/01-project-management.md
|
||||
rg -n '^\*\*Status:\*\*|^## Decisions still required' docs/architecture
|
||||
```
|
||||
|
||||
## Use the canonical actor vocabulary
|
||||
|
||||
| Term | Archie meaning | State and owner |
|
||||
| -------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Identity** | Durable actor reference for ownership, attribution, routing, commands, events, audit. | **APPROVED TARGET:** `internal/domain/identity`. **CURRENT:** configured names and empty strings act as identifiers. |
|
||||
| **User** | Person represented as `user` kind of Identity. | **APPROVED TARGET:** Identity domain. |
|
||||
| **Agent** | Persistent assistant with acting IdentityID, specialisation, instructions, capability context, memory. | **CONFIRMED TARGET:** Agent and Identity separate aggregates; `internal/domain/agent` confirmed in `migration-decisions.md`. |
|
||||
| **Model invocation** | One call through LLM provider/runtime. Replaceable execution machinery. | **CURRENT:** runtime packages. **TARGET:** infrastructure behind Agent-owned behaviour. |
|
||||
| **System identity** | One permanent actor for startup, migration, supervision, rollback. | **APPROVED TARGET:** a real IdentityID. |
|
||||
|
||||
Apply: record acting Agent identity and initiating user identity separately;
|
||||
never authorise because two mutable strings match; never rename Agent when only
|
||||
model/provider/display name changes; never pool two Agents' memory.
|
||||
|
||||
```bash
|
||||
rg -n 'type IdentityConfig|type IdentityRunner|Identity string|BotUser string' internal/config internal/daemon internal/infrastructure/postgres internal/gateway
|
||||
```
|
||||
|
||||
## Use the canonical interaction vocabulary
|
||||
|
||||
| Term | Archie meaning | State and owner |
|
||||
| ------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Channel** | External interaction source (Telegram, email, webhook, forge). | **CURRENT:** `internal/channels` extends `gateway.Gateway`. **TARGET:** infrastructure adapter for Messaging. |
|
||||
| **Adapter** | Boundary code translating external payloads into owned contracts. | **TARGET RULE:** infrastructure implements domain-owned interfaces. |
|
||||
| **Gateway** | Current technical interface/router and package — not approved domain vocabulary. | **CURRENT ONLY:** `internal/gateway`, `internal/channels`. |
|
||||
| **ChannelBindingID** | Stable reference connecting Agent to channel binding. | **APPROVED TARGET INPUT:** part of Conversation identity. |
|
||||
| **Message** | Immutable application record with MessageID and typed content. Platform IDs are external correlations. | **CURRENT:** `internal/domain/messaging.Message`/`MessageID`; `gateway.MessageEvent` is a richer event type beside it. |
|
||||
| **Conversation** | AgentID + UserIdentityID + ChannelBindingID + ExternalConversationID + ThreadID. | **CONFIRMED TARGET, partly current:** `internal/domain/messaging.Conversation`/`ConversationID` exist; the gateway session store still lacks canonical Agent/user IDs. |
|
||||
| **Conversation branch** | Child conversation from one immutable parent message. | **CONFIRMED TARGET.** No current implementation. |
|
||||
| **Work Intake** | Admission, validation, routing boundary between interaction and durable workflow-backed work. | **CONFIRMED TARGET, current package:** `internal/domain/workintake` exists. |
|
||||
| **Accepted work request** | Channel-neutral handoff after Work Intake accepts proposed outcome. | **TARGET HANDOFF:** Agent System consumes it, selects Workflow version, creates WorkflowExecution. |
|
||||
|
||||
Do not equate an inbound Message with work. An Agent may answer, use
|
||||
capabilities, retain information, or propose work without creating a
|
||||
WorkflowExecution.
|
||||
|
||||
Target flow:
|
||||
|
||||
```text
|
||||
external payload -> channel adapter -> canonical Message and Conversation
|
||||
-> selected Agent turn -> optional proposed work -> Work Intake admission
|
||||
-> accepted work request -> Agent System selects Workflow version -> WorkflowExecution
|
||||
```
|
||||
|
||||
Do not describe current `/spawn` as this target. It directly creates a
|
||||
`task.Task` with synthetic forge issue number.
|
||||
|
||||
```bash
|
||||
rg -n 'type Message struct|type MessageEvent struct|ToLegacy|type Conversation struct|CreateTask|EnqueueChatTask|synthetic' internal/domain/messaging internal/gateway internal/infrastructure/postgres internal/app/archied
|
||||
```
|
||||
|
||||
## Use the canonical execution vocabulary
|
||||
|
||||
| Term | Archie meaning | Current representation |
|
||||
| ------------------------ | --------------------------------------------------- | -------------------------------------------------------------------------------- |
|
||||
| **Workflow** | Reusable, versioned definition. | `workflow.Workflow` is named `[]Stage` without durable version model. |
|
||||
| **WorkflowExecution** | One durable execution of one Workflow version. | `task.Task` is migration baseline. |
|
||||
| **WorkflowStep** | One defined operation. | `workflow.Stage` is closest definition. |
|
||||
| **StepExecution** | Durable record of one step's execution and outcome. | Missing; `task.Task.Stage` is one mutable string. |
|
||||
| **Attempt** | Retry within same WorkflowExecution. | `task.Task.Attempt`/`RetryCount` must become explicit attempt history. |
|
||||
| **Agent step execution** | One bounded model-backed WorkflowStep invocation. | `agentexec.Request`/`Result` correlate TaskID, Attempt, Stage, protocol version. |
|
||||
|
||||
Use `WorkflowExecution` in domain contracts, architecture, generated reference.
|
||||
Retain `task` only for Task build tool, forge product nouns in adapters,
|
||||
informal prose.
|
||||
|
||||
### Interpret the current lifecycle exactly
|
||||
|
||||
**CURRENT** `task.Task` states:
|
||||
|
||||
```text
|
||||
queued -> running
|
||||
running -> waiting_human | pr_open | merged | parked | closed_wont_do
|
||||
waiting_human -> queued | closed_wont_do
|
||||
parked -> queued | dead
|
||||
pr_open -> merged | rejected
|
||||
running after crash -> queued
|
||||
```
|
||||
|
||||
Do not claim enforced. `Store.Transition` now guards on `from`
|
||||
(→ `storecontract.ErrStaleTransition`) and writes status plus
|
||||
history in one transaction; the sentinel crosses the State Store gRPC boundary.
|
||||
See `internal/infrastructure/postgres/store.go`.
|
||||
|
||||
```bash
|
||||
rg -n 'Status[A-Za-z]+|func \(s \*Store\) Transition|func \(s \*Store\) Requeue|RecoverStale' internal/infrastructure/postgres internal/domain/workflow internal/gateway
|
||||
```
|
||||
|
||||
## Keep memory scope separate from conversation scope
|
||||
|
||||
| Scope | Address and visibility |
|
||||
| --------------------------- | --------------------------------------------------------- |
|
||||
| **Global shared** | Intentionally visible across Archie. |
|
||||
| **Agent-wide** | Owned by one Agent, private by default even across users. |
|
||||
| **User-wide** | One user across authorised Agents. |
|
||||
| **Agent-user relationship** | Addressed by both AgentID and User IdentityID. |
|
||||
|
||||
Conversation branch is not a fifth memory scope. Scope mechanics **OPEN** beyond
|
||||
these constraints.
|
||||
|
||||
Current `MemoryProvider` initialises with session ID, contains no explicit
|
||||
AgentID, User IdentityID, or scope parameter. Built-in provider separates
|
||||
`MEMORY.md` and `USER.md` under one directory — not the four-scope target model.
|
||||
|
||||
```bash
|
||||
rg -n 'type MemoryProvider|Initialize\(|type Config struct|MEMORY.md|USER.md|AgentID|IdentityID|Scope' internal/memory
|
||||
```
|
||||
|
||||
## Distinguish extension terms
|
||||
|
||||
| Term | Meaning |
|
||||
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Plugin** | Removable module with identity, metadata, compatibility, lifecycle. Generic `plugin.Plugin` must remain metadata-only. |
|
||||
| **Capability family** | One cohesive typed behaviour owned by its domain or approved manager/registry. |
|
||||
| **Engine** | Typed, lifecycle-managed capability family with owning Registry or Manager. |
|
||||
| **Host** | Current cross-family lifecycle/manifest coordinator in `internal/plugin`. Must not become service locator. |
|
||||
|
||||
Give plugin only narrow typed registrars and explicitly supplied contracts.
|
||||
|
||||
```bash
|
||||
go test ./internal/plugin -run 'Test(EngineFamilyInspectionRejectsInvalidShapes|PluginInterfaceExists)' -count=1
|
||||
```
|
||||
|
||||
## Distinguish ownership and boundary terms
|
||||
|
||||
| Term | Archie-specific rule |
|
||||
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Domain** | Own one cohesive responsibility: vocabulary, state, rules, operations, commands, events, policies, runtime settings, required service contracts. |
|
||||
| **Command** | Request an action. Receiving domain owns contract and decides result. |
|
||||
| **Domain event** | Record something that happened. Publishing domain owns schema. |
|
||||
| **Event bus** | Broker-neutral delivery/lifecycle contract. `internal/eventbus` exists and is production-wired. |
|
||||
| **Observability event** | `internal/events.Event` projection input. Bounded in-process bus may drop. Not authoritative state. |
|
||||
| **Policy** | Typed rule evaluated through shared mechanics. Consuming domain owns vocabulary. |
|
||||
| **Infrastructure** | Implements domain-owned ports, translates DBs, brokers, SDKs, files, containers. |
|
||||
| **Application composition** | Chooses implementations, translates config, connects contracts, orders startup/shutdown. Current and target: `internal/app`; `cmd/*` stays process-input-only. |
|
||||
|
||||
As of 2026-09-18, `internal/domain`, `internal/eventbus`,
|
||||
`internal/infrastructure`, and `internal/app` exist; only `internal/policy`
|
||||
does not. `internal/domain/agent` and `internal/domain/identity` are still
|
||||
target-only.
|
||||
|
||||
```bash
|
||||
for p in internal/domain internal/eventbus internal/policy internal/infrastructure internal/app; do test -d "$p" && echo "$p CURRENT" || echo "$p TARGET-ONLY"; done
|
||||
```
|
||||
|
||||
## Distinguish forge, repository, workspace, gate, and agent boundaries
|
||||
|
||||
| Term | Owns | Must not own |
|
||||
| ---------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------- |
|
||||
| **Forge** | External code-host ops: issues, comments, labels, PRs, reactions. | Workflow lifecycle, canonical identity, work admission. |
|
||||
| **Repository** | External source repo identity and repo-specific policy. | Mutable execution workspace or WorkflowExecution identity. |
|
||||
| **Worktree/workspace** | Isolated files, branch, diff, commit, push, cleanup for one execution. | Agent/domain identity or forge issue lifecycle. |
|
||||
| **Gate** | Deterministic evidence and constraints over execution. | Prompt advice model may waive. |
|
||||
| **Agent execution boundary** | Versioned, validated data entering/leaving one unprivileged stage. | Daemon internals, forge tokens, direct git, workflow orchestration. |
|
||||
|
||||
Model never runs git directly. Worktree operations are daemon-owned.
|
||||
|
||||
## Map current names before adding or migrating behaviour
|
||||
|
||||
| Current name/path | Target meaning | Migration warning |
|
||||
| ---------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
||||
| `config.IdentityConfig.Name` | Canonical IdentityID plus separate bindings | Do not preserve mutable display name as ID. |
|
||||
| `config.IdentityConfig.BotUser` | Forge/Git or channel external binding | Not Conversation or Agent identity. |
|
||||
| `daemon.IdentityRunner` | Composition of identity-correlated capabilities | Currently service bundle, not Identity aggregate. |
|
||||
| `gateway.MessageEvent` | Canonical Messaging Message | Choose one immutable typed contract; `internal/domain/messaging.Message` is the target. |
|
||||
| gateway session context | Conversation metadata | Add canonical Agent/user/binding ownership. |
|
||||
| forge `Issue` or future Jira item | Channel message or external artifact | Preserve native reference in adapter. |
|
||||
| gateway `/spawn` and `TaskCreator` | Proposed/accepted work handoff | Work Intake admits; Agent System creates execution. |
|
||||
| `store.Task` | WorkflowExecution | Preserve every field intentionally; the type now lives at `internal/domain/workflow/task.Task`. |
|
||||
| `workflow.Workflow` | Versioned Workflow definition | Add identity/version ownership before parity. |
|
||||
| `workflow.Stage` | WorkflowStep definition | A definition is not execution history. |
|
||||
| mutable `Task.Stage` | Derived position plus StepExecution records | Deletion requires proven history parity. |
|
||||
| `task.Task.Attempt`, `RetryCount` | Attempt history and retry evidence | Keep worker delivery retries distinct. |
|
||||
| `workflow.TaskContext` | Execution state plus narrow step ports | Remove global config/service bag. |
|
||||
| `events.Event` and `Bus` | Projections fed by authoritative domain events | Current drops acceptable for observability, not state. |
|
||||
| `cmd/archied` wiring | `internal/app/archied` composition | Keep `cmd/*` process-input-only. |
|
||||
| NATS/RPC/store/forge/worktree | Infrastructure adapters | Process boundaries don't decide domain ownership. |
|
||||
|
||||
`migration-decisions.md` leaves memory, tools, workspaces, gates, storage,
|
||||
events, web UI, containers, RPC, release management, scheduling pending.
|
||||
|
||||
## Recognise terminology-driven bugs
|
||||
|
||||
| Incorrect shortcut | Resulting bug |
|
||||
| ------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| "A forge issue is a Task" | Chat needs synthetic issues; uniqueness/dedup stay forge-shaped. |
|
||||
| "Agent and Identity are same config object" | Model/persona changes alter attribution; mutable string equality becomes access control. |
|
||||
| "Every Message is work" | Conversational turns forced through durable workflow lifecycle. |
|
||||
| "Accepted request is already a WorkflowExecution" | Intake bypasses version selection and constructs invalid state. |
|
||||
| "Stage is StepExecution" | Overwriting one string destroys step outcomes and audit history. |
|
||||
| "NATS retry is another Attempt" | Transport availability changes domain retry counts. |
|
||||
| "Event bus owns events" | Broker subjects become domain vocabulary; meaning drifts by consumer. |
|
||||
| "Branch is a memory scope" | Returning to parent hides/duplicates durable learning. |
|
||||
| "Engine means another generic plugin hook" | Capability ownership becomes untyped; plugins gain service-locator access. |
|
||||
| "Configuration owns the feature" | Cross-concern config becomes de facto domain. |
|
||||
|
||||
Reject in review: a second parallel model without bounded cutover; status string
|
||||
copied into consumer; mutable display name as durable ID; service bag passed
|
||||
into domain/plugin/WorkflowStep; lifecycle state written by adapter/UI/transport;
|
||||
domain importing concrete persistence/NATS/forge SDK/container/config DTO types;
|
||||
test proving only new path while old production path remains active.
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "Archie Domain Reference"
|
||||
short_description: "Use Archie terminology without boundary mistakes"
|
||||
default_prompt: "Use $archie-domain-reference to classify these Archie concepts and map current code terms to their approved target owners."
|
||||
@@ -1,230 +0,0 @@
|
||||
---
|
||||
name: archie-failure-archaeology
|
||||
description: "Reconstruct archie-core failures, dead ends, reversals, rejected fixes, and branch-only repairs from read-only git history and live call sites. Use when a symptom resembles a past production outage, deadlock, retry loop, protocol mismatch, configuration regression, worktree/cache fault, unsafe cleanup, linter semantic change, artifact leak, or recurring baseline repair; also use before reviving an old approach, declaring a fix reverted, or deciding whether a repair is current, settled, conditional, superseded, open, or merely a candidate."
|
||||
---
|
||||
|
||||
# Archie failure archaeology
|
||||
|
||||
Stop the project from paying twice for the same lesson. Reconstruct what
|
||||
happened from checked-out code, tests, configuration, and commit graph.
|
||||
Treat commit prose as a lead, not proof. Preserve uncertainty.
|
||||
|
||||
All volatile observations are dated **2026-09-18** (HEAD `2e1e1549`); the merge-shape
|
||||
section under Step 4 is dated **2026-09-20** (HEAD `1b0133d7`).
|
||||
|
||||
Route to `archie-debugging-playbook` for active symptoms,
|
||||
`archie-codebase-discovery` for deep caller tracing.
|
||||
|
||||
## Use the status taxonomy exactly
|
||||
|
||||
| Status | Meaning |
|
||||
| ------------------- | ------------------------------------------------------------------------------------ |
|
||||
| `settled` (`fixed`) | The failure, cause, resolution, and live replacement are proven. |
|
||||
| `current` | The checked-out authoritative path still contains the behaviour or contradiction. |
|
||||
| `open` | The defect is evidenced, but no accepted and integrated resolution. |
|
||||
| `conditional` | A fix is proven only for the named configuration, execution mode, peer, or assembly. |
|
||||
| `superseded` | A mechanism was intentionally replaced. |
|
||||
| `candidate` | A branch, proposal, or partial implementation may help but is not accepted. |
|
||||
|
||||
Never use `settled` to mean "a fix commit exists."
|
||||
|
||||
## Run the archaeology workflow
|
||||
|
||||
### 1. Freeze the observation point
|
||||
|
||||
```sh
|
||||
git rev-parse HEAD
|
||||
git status --short
|
||||
git log -1 --date=iso-strict --format='%H %ad %s'
|
||||
git branch -a --no-color --no-merged HEAD
|
||||
```
|
||||
|
||||
### 2. Name the exact symptom
|
||||
|
||||
Capture: first wrong observable result; last confirmed-good boundary; process
|
||||
mode; active config and deployment assembly; whether deterministic,
|
||||
load-dependent, or production-only.
|
||||
|
||||
### 3. Trace current behaviour before history
|
||||
|
||||
```sh
|
||||
rg -n '<symptom|symbol|setting|error>' cmd internal config*.toml docker-compose.yml docs
|
||||
git log --all --date=iso-strict --format='%H %ad %s' -- <affected-paths>
|
||||
git blame -L <start>,<end> -- <live-file>
|
||||
```
|
||||
|
||||
### 4. Prove the historical transition
|
||||
|
||||
```sh
|
||||
git show --no-ext-diff --format=fuller --stat <commit>
|
||||
git show --no-ext-diff -U80 <commit> -- <affected-paths>
|
||||
.agents/skills/archie-failure-archaeology/scripts/on-main.sh <commit>
|
||||
git branch -a --contains <commit>
|
||||
```
|
||||
|
||||
#### `--is-ancestor` is blind to squash and rebase merges
|
||||
|
||||
`git merge-base --is-ancestor` answers a topology question: is this exact commit
|
||||
object an ancestor. **Squash and merge** always mints a new commit, and **Rebase
|
||||
and merge** mints new ones whenever the branch had to be replayed, so both
|
||||
orphan the SHA a branch holds. `git branch -a --contains` and
|
||||
`git branch -r --no-merged` are blind in the same way.
|
||||
|
||||
As of **2026-09-20** (`origin/main` `1b0133d7`) this repository squash-merges —
|
||||
the last fifteen merged pull requests are all squashes, so the raw check is a
|
||||
false negative for every one of them. It was sound for everything merged up to
|
||||
**2026-09-18**, which used merge commits.
|
||||
|
||||
Use `scripts/on-main.sh`, which keeps `--is-ancestor` as the offline fast path
|
||||
and otherwise asks the GitHub API, where merge state is recorded independently
|
||||
of the commit graph:
|
||||
|
||||
```sh
|
||||
.agents/skills/archie-failure-archaeology/scripts/on-main.sh <ref> [base-ref]
|
||||
```
|
||||
|
||||
`<base-ref>` defaults to `origin/main`; name `gitea/main` or `HEAD` when that is
|
||||
the trunk you mean, and `git fetch` first so the fast path is not stale.
|
||||
|
||||
| Exit | Meaning |
|
||||
| ---- | -------------------------------------------------------------------------- |
|
||||
| `0` | Ancestor of `<base-ref>`, or recorded in a merged pull request — landed |
|
||||
| `1` | On GitHub, in no merged pull request — not landed |
|
||||
| `2` | Bad ref, no `gh`, offline, never pushed — **undetermined, not a negative** |
|
||||
|
||||
Branch on the code explicitly; `if on-main.sh <ref>; then` folds `2` into "not
|
||||
landed", which is the error this helper exists to prevent. It answers "did _this
|
||||
ref_ land", not "did this work land" — a change reimplemented on another branch
|
||||
still reads `not-landed` for the original commit.
|
||||
|
||||
Read parent version when failure is semantic:
|
||||
|
||||
```sh
|
||||
git show <commit>^:<path>
|
||||
git show <commit>:<path>
|
||||
```
|
||||
|
||||
Require all six fields in an incident packet:
|
||||
|
||||
| Field | Required content |
|
||||
| ------------------ | --------------------------------------------------------- |
|
||||
| Symptom | Operator, user, test, or protocol observation |
|
||||
| Attempted solution | What was tried before or during the failure |
|
||||
| Root cause | The violated contract or mistaken assumption |
|
||||
| Evidence | Commit, live path, test, trace, or production observation |
|
||||
| Current status | One taxonomy value, dated when volatile |
|
||||
| Settled rule | A constraint future work must preserve |
|
||||
|
||||
### 5. Reproduce narrowly, then route
|
||||
|
||||
```sh
|
||||
env GOCACHE=/tmp/archie-archaeology-gocache GOTMPDIR=/tmp go test ./internal/<package> -run '^TestName$' -count=1 -v
|
||||
```
|
||||
|
||||
If current behaviour differs from chronicle, update the packet.
|
||||
|
||||
## Match symptoms to known incidents
|
||||
|
||||
| Symptom | Start with |
|
||||
| ---------------------------------------------------------------------- | --------------------------------------------------------- |
|
||||
| `nats: no responders available for request` only from agent containers | Container network incident |
|
||||
| Daemon crash-loops after config/schema work | SecretRef compatibility and Compose passthrough incidents |
|
||||
| Stream shows empty cursor or first token, then hangs | FullStream/TextStream incident |
|
||||
| MCP unit tests pass but real SDK server hangs | MCP framing and mirrored-peer incident |
|
||||
| Telegram shows old commands after menu update | Telegram server-side scope incident |
|
||||
| Tool discovery deadlocks, aliases mutate, or bad plugin hides rest | Tool-registry adversarial findings |
|
||||
| Hidden `<memory>` content appears at end of truncated stream | Scrubber `Flush` leak |
|
||||
| Broad lint cleanup compiles poorly while tests pass | Autofix, `nilerr`, and `308c199` incidents |
|
||||
| Reused worktree is stale, half-prepared, or coupled to expired objects | Worktree/askpass/cache history |
|
||||
| Repeated `fix: baseline gate repair` commits or parked tasks cycle | Baseline, no-op, and retry-loop incidents |
|
||||
| CI cannot resolve `/work/apps/...` | Local module replacement incident |
|
||||
| Build caches or dependency trees appear in diff | `.gotmp` and `node_modules` incidents |
|
||||
| `diff_cap_lines = 0` still behaves as 400 | Diff-cap zero contradiction |
|
||||
|
||||
## Chronicle: work intake and retry loops
|
||||
|
||||
| Incident and date | Symptom | Root cause | Evidence and status | Settled rule |
|
||||
| ------------------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
||||
| Label auto-claim, 2026-07-22 | >80 labelled issues enrolled under label polling. | Label polling means eligibility, not hint. | `519882f` changed the Compose profile to `assignee`; that file was deleted (`cbb7929e`) and survives as `deployments/docker-nats-stack.toml`, which sets `trigger = "assignee"`. `internal/config/config.go` defaults to `assignee` but permits `label` and `either`. **Status:** `settled`. | Default to assignee-driven pickup. Label/either are deliberate bulk enrolment. |
|
||||
| Baseline-red park storm, 2026-07-23 onward | Task parks on gate failure that existed before its feature work. | Parking/retrying cannot change pre-existing failure; auto-repair mixes repository repair into feature scope. | `b2482af` made `StageBaselineGate` launch builder instead of parking. Nine repair commits in history. **Status:** `current` mitigation and architecture weak point. | Measure untouched baseline first. Track baseline repair as explicit change. |
|
||||
| Passed build with zero changes, 2026-07-23 | Commit-push reports "no changes," parks, retries, repeats. | "Passed with no changes" lacked terminal domain outcome. | `62c0df1` introduced no-op detection; `2bf42bd` set `Outcome`. `TestStageCommitPushClosesIssueWhenBuildNoChanges`. **Status:** `settled`. | Model no-op as explicit terminal result. |
|
||||
| Infinite parked-task retry, 2026-07-23 | Removing parked label repeatedly requeues with no terminal bound. | Retry count not durable or capped. | `a8fdb50` added persisted `retry_count`, global/per-repo `max_retries`, and `dead`. **Status:** `settled`. | Every autonomous retry needs durable attempt state, explicit bound, terminal state, and operator-visible reason. |
|
||||
|
||||
## Chronicle: runtime and peer contracts
|
||||
|
||||
| Incident and date | Symptom | Root cause | Evidence and status | Settled rule |
|
||||
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| Container network auto-detection, 2026-07-27 | Every container task returns `nats: no responders`. | `selfNetwork` inspected hostnamed container, silently fell back to default bridge. | `37cf089` records incident, adds `containers.network`; `2ac306b` pins `archie-core_default`. **Status:** `conditional`. | Make cross-container network membership explicit in deployment. |
|
||||
| SecretRef schema crash-loop, 2026-07-27 | Both identities demand `ARCHIE_GITHUB_TOKEN` despite Gitea config. | Removing old `token_env` field let TOML ignore deployed value. `1f8588d` restored precedence-compatible fallback; a later `308c199` removed the `Forge.TokenEnv` declaration while `finalize` still referenced it. | **Status: `retired`** as of 2026-09-24 — the `token_env` alias is removed; a stale key is now reported at startup as unrecognised (`bootstrap.go` UnknownKeys warning), which is the observability this entry waited for. | Never drop a credential key without the unknown-key warning in place. |
|
||||
| Compose secret omission, 2026-07-27 | Config names valid env var, container sees it empty. | Compose forwards only listed environment entries. | `22fc0ef`, `d0624b7`. **Status:** `conditional`. | Trace every secret from config key to host value to Compose passthrough to process lookup. |
|
||||
| FullStream/TextStream deadlock, 2026-07-27 | Streamed Telegram reply renders empty cursor, typing never clears. | ai-sdk makes `FullStream` authoritative and backpressured; `TextStream` is best-effort. | `6a0bd27`. **Status:** `settled` with regression-test gap. | Drain authoritative stream through close. |
|
||||
| MCP Content-Length framing and mirrored fake, 2026-07-26 to 2026-07-27 | Internal MCP tests pass while official-SDK servers do not. | MCP stdio uses newline-delimited JSON. Test subprocess called same helpers, mirroring the same wrong protocol. | Compare `f2768eb:internal/tools/mcp/framing.go` with `dda4cde`. **Status:** `settled`. | For wire contracts, test raw canonical frames and independently implemented peer. |
|
||||
| Telegram command scopes persist by bot token, 2026-07-27 | Startup reports eight commands published, DMs show ~60 old Hermes commands. | Telegram chooses most specific scope; older scopes survive redeploys. | `cec0f3e` adds menu and deny-by-default; `576c7f5` publishes all three scopes. **Status:** `settled`. | Inventory and overwrite every relevant server-side scope. |
|
||||
| NATS fetch error looked like empty queue, 2026-07-27 | Consumer receives zero messages, treats JetStream failure as "no work." | Batch error state not checked after channel closed. | `0d09a2e` repro; `78a9145` merged through `21ceef0`. **Status:** `settled`. | Check terminal iterator/batch error state even when data channel is empty. |
|
||||
|
||||
## Chronicle: implementation and tooling traps
|
||||
|
||||
| Incident and date | Symptom | Root cause | Status |
|
||||
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Tool registry passed first implementation but held eight defects, 2026-07-26 | Availability can deadlock; schemas mutate after registration; discovery stops at first bad source; literal extraction wrong. | Callbacks ran under `RLock`, copies shallow/shared, parsing partial, matching broad, discovery fail-fast. | `9f6c36c` lists all eight fixes. **Settled.** Never call extension code under registry lock. Clone nested data. Parse complete grammar. Isolate discovery failures. |
|
||||
| Memory scrubber `Flush` leak, 2026-07-26 | Stream ending inside `...secret</mem` emits buffered hidden memory to visible response. | Pending bytes did not retain whether captured inside `<memory>` block. | `b4aaaf0`. **Settled.** Test every streaming state at EOF. Flush is security boundary. |
|
||||
| Linter autofix shadowing, 2026-07-28 | 24-file "style" pass stops compiling. | `gocritic` changed `ctx, cancel = context.WithTimeout(...)` to `:=` inside conditional, shadowing context. | `9b44bac`. **Settled.** Treat autofix output as authored behaviour. |
|
||||
| All eleven `nilerr` findings semantic false positives, 2026-07-28 | Mechanical "fixes" would return Go errors while tests pass, breaking model correction, chat, NATS envelopes, clean shutdown, indexing. | Linter cannot see failures carried as text, envelopes, shutdown signals, or skipped entries. | `86cfc19`. **Settled.** Review semantic channels one site at a time. |
|
||||
| Broad checkpoint hid unresolved merge conflict, 2026-07-27 | Literal conflict marker reached committed source. | Unrelated surfaces combined without whole-diff conflict scan. | `4429ae5`. **Settled.** Keep commits cohesive. |
|
||||
|
||||
### Preserve the eight tool-registry review lessons
|
||||
|
||||
| Defect fixed in `9f6c36c` | Required review question |
|
||||
| -------------------------------------------------- | ------------------------------------------------------ |
|
||||
| `Available` evaluated `CheckFn` under `RLock` | Can a callback re-enter or block while lock is held? |
|
||||
| `Register` stored caller references | Can caller mutate registered state afterward? |
|
||||
| `Clone` copied nested schema maps/slices shallowly | Is every mutable layer detached? |
|
||||
| `stringLit` mishandled escapes/backticks | Does parsing follow Go literal semantics? |
|
||||
| `intLit` omitted negative/hex/octal/binary forms | Are all supported numeric forms handled or rejected? |
|
||||
| `Discover` aborted on first error | Can one bad extension hide healthy extensions? |
|
||||
| `isRegisterCall` matched too broadly | Is the exact receiver/call shape proven? |
|
||||
| `schemaLit` accepted only string values | Are booleans, integers, arrays, nested maps preserved? |
|
||||
|
||||
## Chronicle: worktree and repository state reversals
|
||||
|
||||
| Step and date | Symptom | Root cause | Settled rule |
|
||||
| ---------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
||||
| Existing worktree skipped, 2026-07-23 | `Prepare` returned when `.git` existed. | Existence did not prove freshness or completed preparation. Later replaced `.git` readiness with sentinel. | Define completed-state marker and revalidate remote/base/branch state on reuse. |
|
||||
| Sentinel outside `.git`, 2026-07-24 | `.archie-prepared` marked setup; go-git `Add(All)` doesn't honour exclude. | Orchestration metadata needs to be outside tracked worktree by construction. | Put sentinel at `.git/archie-prepared`. |
|
||||
| Askpass rewritten each call, 2026-07-24 | Token-emitting shell script rewritten for every git command. | Comment wasn't invariant; no test checked mtime. Later removed shell git and askpass entirely. | Prefer in-process credentials. |
|
||||
| Bare object cache, 2026-07-24 | `--reference-if-able --dissociate` plus TTL to accelerate clones. | go-git has no `--dissociate` equivalent; expiring cache would corrupt active worktrees. | Never accept clone acceleration making task correctness depend on expiring cache. |
|
||||
| Shell git replaced by go-git, 2026-07-28 | Port exposed host GPG inheritance, sentinel tracking, merge-base diff semantics. | RPC handlers used `context.Background`, making in-process clones unbounded. | Audit every adapter and cancellation boundary after replacing killable subprocess with in-process I/O. |
|
||||
|
||||
## Chronicle: cleanup, artifacts, and contradictory policy
|
||||
|
||||
| Incident and date | Symptom | Root cause | Status | Settled rule |
|
||||
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
|
||||
| Tracked `.gotmp`, 2026-07-27 | Build-cache binaries, generated `_testmain.go`, `.git-askpass` appear in commits. | Workaround path not ignored before use. | `4cb0577` removes artifacts and adds `.gotmp/` to `.gitignore`. **Settled.** | Put caches outside repo or ignore before first command. |
|
||||
| Tracked `docs/node_modules`, 2026-07-28 | Hundreds of pnpm symlink entries become repository content. | `docs/node_modules` neither ignored nor excluded from commit. | 237 entries at that time; the VitePress site was removed (`84b32694`) and `git ls-files | grep -c node_modules` is now **0**. **Settled.** | Track lockfiles, never installed trees. |
|
||||
| `308c199` cleanup regression, 2026-07-28 | `TestRunWrapsExternalCommand` returns `"\n"` instead of `"wrapped\n"`; forge compatibility removed again; dependency artifacts added. | Semantic edits classified and reviewed as cleanup. | The focused skillscript test **passes** as of 2026-09-16. **Settled.** | No commit is "cleanup" for gating purposes. |
|
||||
| `diff_cap_lines = 0` contradiction, introduced at project start | Operators set zero expecting unlimited, but decoded config becomes 400. | `finalize` converts zero to default 400; same sentinel means both "unset" and "unlimited." | **Current/open** contradiction. | Never overload zero value with both defaulting and explicit policy. |
|
||||
|
||||
## Keep unmerged work as dated candidates
|
||||
|
||||
As of **2026-09-18**, the six `fix/4x` and `feat/5x`/`feat/75` candidate
|
||||
branches recorded here on 2026-07-28 no longer exist on either remote —
|
||||
`git branch -r --no-merged HEAD` reports only `gitea/main` (and the Dolt helper
|
||||
ref). Treat their concerns as `superseded` unless a live branch re-raises one.
|
||||
|
||||
| Former candidate branch | Claimed concern |
|
||||
| ---------------------------------------------------------------------------- | ---------------------------------------- |
|
||||
| `origin/fix/43-loaddir-no-timeout-around-yaegi-eval-can-hang-daemon-startup` | Bound Yaegi evaluation during `LoadDir` |
|
||||
| `origin/fix/45-skillscriptrun-ignores-context-cannot-be-canceledtimed-out` | Make skill scripts cancellable |
|
||||
| `origin/fix/48-transition-ignores-from-status-guard-allowing-lost-updates` | Enforce expected source state atomically |
|
||||
| `origin/fix/52-handlesse-silently-swallows-eventssince-backlog-fetch-errors` | Surface SSE backlog query errors |
|
||||
| `origin/feat/51-no-test-coverage-for-stagestats-query` | Add `StageStats` query coverage |
|
||||
| `origin/feat/75-add-mcp-client-capabilities-to-archied-and-archie-agent` | Wire MCP through both execution modes |
|
||||
|
||||
Verify candidate state:
|
||||
|
||||
```sh
|
||||
git branch -r --no-merged HEAD
|
||||
git log -1 --date=iso-strict --format='%H %ad %s' <branch>
|
||||
git diff --stat HEAD...<branch>
|
||||
.agents/skills/archie-failure-archaeology/scripts/on-main.sh <branch> HEAD
|
||||
```
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "Archie Failure Archaeology"
|
||||
short_description: "Avoid repeating Archie failure history"
|
||||
default_prompt: "Use $archie-failure-archaeology to trace this symptom through Archies proven incidents before proposing a fix."
|
||||
@@ -1,113 +0,0 @@
|
||||
#!/bin/sh
|
||||
# on-main.sh -- did this ref land on the trunk, even when it was squash- or
|
||||
# rebase-merged?
|
||||
#
|
||||
# `git merge-base --is-ancestor` answers a topology question: is this exact
|
||||
# commit object an ancestor. GitHub's "Squash and merge" always mints a new
|
||||
# commit, and "Rebase and merge" mints new commits whenever the branch had to
|
||||
# be replayed, so both orphan the SHA your branch holds. The raw check then
|
||||
# reports a landed repair as never-landed, and `git branch -a --contains` is
|
||||
# blind in exactly the same way.
|
||||
#
|
||||
# This wrapper keeps `--is-ancestor` as the offline fast path and falls back to
|
||||
# the GitHub API, which records merge state independently of the commit graph.
|
||||
#
|
||||
# usage: on-main.sh [-q] <ref> [base-ref]
|
||||
#
|
||||
# <ref> commit, tag, or branch to test
|
||||
# [base-ref] trunk to test against (default: origin/main)
|
||||
# -q print nothing; report through the exit code only
|
||||
#
|
||||
# exit 0 landed on <base-ref>, by ancestry or by a merged pull request
|
||||
# exit 1 not landed: known to GitHub, but in no merged pull request
|
||||
# exit 2 undetermined: bad ref, no gh, offline, or never pushed to GitHub
|
||||
# exit 127 git is missing
|
||||
#
|
||||
# exit 2 is not a negative. Branch on the code explicitly; `if on-main.sh <ref>`
|
||||
# folds it into "not landed", which is the error this helper exists to prevent.
|
||||
|
||||
set -eu
|
||||
|
||||
quiet=0
|
||||
while [ "$#" -gt 0 ]; do
|
||||
case "$1" in
|
||||
-q | --quiet)
|
||||
quiet=1
|
||||
shift
|
||||
;;
|
||||
--)
|
||||
shift
|
||||
break
|
||||
;;
|
||||
-*)
|
||||
printf 'on-main: unknown option %s\n' "$1" >&2
|
||||
printf '%s\n' 'usage: on-main.sh [-q] <ref> [base-ref]' >&2
|
||||
exit 2
|
||||
;;
|
||||
*)
|
||||
break
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
if [ "$#" -lt 1 ] || [ "$#" -gt 2 ]; then
|
||||
printf '%s\n' 'usage: on-main.sh [-q] <ref> [base-ref]' >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
ref=$1
|
||||
base=${2:-origin/main}
|
||||
|
||||
say() {
|
||||
[ "$quiet" -eq 1 ] || printf '%s\n' "$1"
|
||||
}
|
||||
|
||||
command -v git >/dev/null 2>&1 || {
|
||||
printf '%s\n' 'on-main: git is required' >&2
|
||||
exit 127
|
||||
}
|
||||
|
||||
sha=$(git rev-parse --verify --quiet "${ref}^{commit}") || {
|
||||
say "undetermined: $ref does not resolve to a commit in this repository"
|
||||
exit 2
|
||||
}
|
||||
|
||||
git rev-parse --verify --quiet "${base}^{commit}" >/dev/null 2>&1 || {
|
||||
say "undetermined: base ref $base does not resolve; fetch it, or name the trunk explicitly"
|
||||
exit 2
|
||||
}
|
||||
|
||||
if git merge-base --is-ancestor "$sha" "$base" 2>/dev/null; then
|
||||
say "landed: $sha is an ancestor of $base (topology)"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Not an ancestor. The SHA may still have landed if GitHub rewrote it at merge
|
||||
# time, so ask the service that recorded the merge rather than the commit graph.
|
||||
command -v gh >/dev/null 2>&1 || {
|
||||
say "undetermined: $sha is not an ancestor of $base, and gh is absent, so a squash or rebase merge cannot be ruled out"
|
||||
exit 2
|
||||
}
|
||||
|
||||
merged=$(
|
||||
gh api "repos/{owner}/{repo}/commits/$sha/pulls" \
|
||||
--jq '[.[] | select(.merged_at != null)] | length' 2>/dev/null
|
||||
) || {
|
||||
say "undetermined: $sha is not an ancestor of $base, and GitHub could not answer for it (offline, unauthenticated, or never pushed)"
|
||||
exit 2
|
||||
}
|
||||
|
||||
case "$merged" in
|
||||
'' | *[!0-9]*)
|
||||
say "undetermined: GitHub returned an unreadable answer for $sha"
|
||||
exit 2
|
||||
;;
|
||||
0)
|
||||
say "not-landed: $sha is not an ancestor of $base and belongs to no merged pull request"
|
||||
exit 1
|
||||
;;
|
||||
*)
|
||||
say "landed: $sha is not an ancestor of $base, but GitHub records it in $merged merged pull request(s) -- a squash or rebase merge rewrote the SHA"
|
||||
exit 0
|
||||
;;
|
||||
esac
|
||||
@@ -1,215 +0,0 @@
|
||||
---
|
||||
name: archie-run-and-operate
|
||||
description: "Run and observe Archie safely with a host daemon and the repository's Docker Compose NATS service. Use when starting or stopping archied, running an archie-agent NATS worker, checking readiness, following logs, locating task state/worktrees/memory/container volumes, understanding inprocess/subprocess/NATS execution, inspecting the image pipeline, or planning an operational rollback without changing architecture."
|
||||
---
|
||||
|
||||
# Run and operate Archie
|
||||
|
||||
Use this runbook to operate the implementation that exists on **2026-09-18**
|
||||
(HEAD `2e1e1549`). Treat source and tests as current; treat `docs/archive/` as
|
||||
history.
|
||||
|
||||
## Define the process shapes
|
||||
|
||||
| Term | Meaning here |
|
||||
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `archied` | Resident orchestrator. Owns config, forge credentials, worktrees, gateways, dashboard, optional NATS/Docker orchestration. |
|
||||
| `archie-agent` | Long-running NATS worker. Consumes per-stage `archie.agent.>` requests and full-task `archie.taskrun.>` requests. Not a stdin/stdout worker. |
|
||||
| Stage request | One autonomous workflow stage sent on `archie.agent.<task-id>.request`. |
|
||||
| Full-task handoff | A whole workflow sent on core NATS subject `archie.taskrun.<task-id>` to a task container. |
|
||||
| Work directory | `work_dir`: task clones plus memory and candidate index artifacts. |
|
||||
| State directory | `state_dir` (default `~/.local/share/archie`): embedded NATS store, task logs. Task, event, capture and conversation data live in the PostgreSQL database `database_url` names. |
|
||||
|
||||
## Apply the operational safety boundary
|
||||
|
||||
Assume every daemon start can change local and external state.
|
||||
|
||||
- Obtain explicit authority for config, forge identity, repositories, NATS
|
||||
account, Docker host, and deployment host before starting.
|
||||
- Never use production tokens for a smoke test.
|
||||
- Do not call `archied -once` as a dry run. It accepts invitations, verifies
|
||||
push access, polls the forge, enqueues/labels work, reconciles PRs, processes
|
||||
tasks, and then exits.
|
||||
- Do not expose the dashboard publicly. It has no authentication, and
|
||||
`POST /api/tasks/clear` deletes terminal task records.
|
||||
- Do not print secret values. Record environment-variable **names**, config
|
||||
checksums, image digests, and paths instead.
|
||||
- Stop with `Ctrl-C`, `SIGTERM`, or Compose. Do not use `SIGKILL` unless graceful
|
||||
shutdown has demonstrably failed.
|
||||
|
||||
There is no config-only or dry-run flag.
|
||||
|
||||
## Know the command surfaces
|
||||
|
||||
### `archied`
|
||||
|
||||
| Flag | Exact behaviour |
|
||||
| ------------------------ | -------------------------------------------------------------------------------------------------- |
|
||||
| `-config <path>` | Load base TOML. Default: `$XDG_CONFIG_HOME/archie/config.toml`, or `~/.config/archie/config.toml`. |
|
||||
| `-config-overlay <path>` | Decode a second TOML file into the base config before defaults and validation. |
|
||||
| `-once` | Run startup plus one poll/process cycle, then exit. This changes state. |
|
||||
| `-requeue <task-id>` | Requeue a parked/waiting task, then exit unless `-once` is also set. This changes state. |
|
||||
|
||||
### `archie-agent`
|
||||
|
||||
| Flag or environment | Exact behaviour |
|
||||
| ------------------- | --------------------------------------------------------------- |
|
||||
| `-nats-url <url>` | Select NATS; falls back to `NATS_URL`. One of them is required. |
|
||||
| `NATS_TOKEN` | Optional NATS token read directly by the worker. |
|
||||
|
||||
Both linked binaries may also display Go's `-quickchecks` flag from
|
||||
`testing/quick`; it is not an Archie operations control.
|
||||
|
||||
## Execution mode
|
||||
|
||||
| Config shape | What runs |
|
||||
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `[nats]` absent (embedded) or `url` set (external) | `archied` polls and claims through the State Store, prepares a worktree, spawns one task-scoped agent container and sends the whole workflow on `archie.taskrun.<id>`. There is no other execution mode. |
|
||||
|
||||
## Run a local foreground daemon
|
||||
|
||||
```bash
|
||||
task build
|
||||
task --list
|
||||
./bin/archied -h
|
||||
./bin/archie-agent -h
|
||||
```
|
||||
|
||||
Choose an explicitly approved config:
|
||||
|
||||
```bash
|
||||
ARCHIE_CONFIG=/absolute/path/to/config.toml
|
||||
test -r "$ARCHIE_CONFIG"
|
||||
./bin/archied -config "$ARCHIE_CONFIG"
|
||||
```
|
||||
|
||||
Expect JSON logs on stderr. Require: `nats connected` when `[nats]` configured;
|
||||
`workflow registry built`; `memory manager started`; `web ui listening` unless
|
||||
`web.listen = "off"`; gateway-start messages for configured channels;
|
||||
`archied running` after startup verification. Absence of `archied running` means
|
||||
startup did not complete. The daemon has no HTTP health endpoint.
|
||||
|
||||
Stop with `Ctrl-C`. The signal cancels active work, waits for dispatch
|
||||
goroutines, stops capability and memory managers, removes Archie-labelled
|
||||
containers, closes NATS, and closes its store connections.
|
||||
|
||||
## Run a standalone NATS worker
|
||||
|
||||
```bash
|
||||
NATS_URL=nats://127.0.0.1:4222 ./bin/archie-agent
|
||||
```
|
||||
|
||||
Require both `nats connected` and `archie-agent ready`. Stop with `Ctrl-C`.
|
||||
Do not use this to test subprocess mode.
|
||||
|
||||
## Run the repository Compose stack
|
||||
|
||||
| Repository command | Actual scope |
|
||||
| ------------------- | -------------------------------------------------------------------------------- |
|
||||
| `task docker-build` | Build only the `agent` image from `Dockerfile`. |
|
||||
| `task docker-up` | Start the Compose-managed NATS service. The profiled agent entry is not started. |
|
||||
| `task docker-logs` | Follow the NATS service logs. |
|
||||
| `task docker-down` | Run `docker compose down`. Does not request volume deletion. |
|
||||
|
||||
Prefer the narrow start:
|
||||
|
||||
```bash
|
||||
docker compose up -d nats
|
||||
```
|
||||
|
||||
Read-only observations:
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
docker compose logs --tail=200 nats
|
||||
docker compose exec -T nats wget -q -O - http://localhost:8222/healthz
|
||||
```
|
||||
|
||||
```bash
|
||||
curl -fsS http://127.0.0.1:8484/api/summary
|
||||
curl -fsS http://127.0.0.1:8484/api/tasks
|
||||
```
|
||||
|
||||
Wait for the NATS healthcheck, then start `archied` on the host. Require the
|
||||
configured host supervisor to report it running and verify the dashboard API
|
||||
as the daemon readiness gate.
|
||||
|
||||
Stop with:
|
||||
|
||||
```bash
|
||||
task docker-down
|
||||
```
|
||||
|
||||
Never add `-v` during routine shutdown. The Compose `agent` service is a
|
||||
build-profile image definition, not a long-running service. Actual task workers
|
||||
are spawned by the host `archied` process through `/var/run/docker.sock`.
|
||||
|
||||
## Locate output and durable state
|
||||
|
||||
| Output or state | Current destination |
|
||||
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Daemon logs | JSON on host stderr; the configured host supervisor captures them. |
|
||||
| Agent logs | JSON on worker/container stderr. Task containers use `AutoRemove`. |
|
||||
| Tasks and events | PostgreSQL (`database_url`), served by `archie-state-store`. |
|
||||
| Chat sessions and messages | PostgreSQL (`database_url`), served by `archie-gateway`. |
|
||||
| Default task worktree | `<work_dir>/<owner>-<repo>/issue-<number>`; default root `~/.local/share/archie/work`. |
|
||||
| Identity worktree | `<work_dir>/identity-<identity>/<owner>-<repo>/issue-<number>`. |
|
||||
| Container worktree | Host worktree bind-mounted read/write at `/data/worktree`; `task.json` written under `.git/` so the agent's commit cannot sweep it onto the task branch. |
|
||||
| Built-in memory | `<work_dir>/memory/MEMORY.md` and `<work_dir>/memory/USER.md`. |
|
||||
| Telegram update state | `<work_dir>/telegram-update-deferrals.json` plus hashed `release-announcements-*.json`. |
|
||||
| Codesearch candidates | Defaults derive as `<work_dir>/indexes` and `<work_dir>/workspace-indexes.db`; no `indexing.Manager` construction found in daemon composition root. |
|
||||
| Optional repository volume | `archie-repo-<owner>-<repo>` mounted at `/data/repo`. |
|
||||
| Ecosystem cache volumes | `archie-cache-go`, `archie-cache-node`, etc., mounted below `/data/cache`. No code sets tool cache env vars to those mount paths. |
|
||||
| NATS data | Compose declares `nats_data:/data`; NATS command does not set a store directory. |
|
||||
|
||||
Compose runs NATS only; `archied` and all configured state paths remain on the
|
||||
host. The host daemon talks to the local Docker socket directly and bind-mounts
|
||||
each task worktree into the agent container it creates.
|
||||
|
||||
## Understand NATS and container observation
|
||||
|
||||
The `ARCHIE_TASKS` JetStream stream uses file storage and work-queue retention
|
||||
for `archie.task.>` and `archie.agent.>`.
|
||||
|
||||
| Plane | Subjects and behaviour |
|
||||
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Discovery | `archie.task.bug`, `.feature`, `.bootstrap`, or `.default`; daemon durable consumer `archie-daemon`, 5-min ack wait, max 3 deliveries. |
|
||||
| Per-stage requests | `archie.agent.<id>.request`; worker durable consumer defaults to `archie-agent`, 30-min ack wait, max 3 deliveries; response address in `X-Archie-Reply`. |
|
||||
| Container task | Core NATS request/reply on `archie.taskrun.<id>`. Task container reads `/data/worktree/.git/task.json` and creates dedicated subscription; shared worker uses queue group `archie-taskrun-workers`. |
|
||||
| Privileged RPC | Store operations go to the gRPC State Store (`internal/infrastructure/staterpc`, task-scoped grants); forge and worktree operations return to `archied` over core NATS subjects in `internal/forgerpc` and `internal/worktreerpc`. |
|
||||
|
||||
Set `containers.network` explicitly. `deployments/docker-nats-stack.toml` uses
|
||||
`archie-core_default`. Auto-detection inspects the daemon container; on failure,
|
||||
workers join Docker's default bridge and cannot resolve `nats`. Initial
|
||||
`ErrNoResponders` is retried for 20s at 250ms intervals.
|
||||
|
||||
If `nats.token_env` is configured, `archied` refuses startup when that variable
|
||||
is empty. It injects the resolved value as `NATS_TOKEN` into task containers.
|
||||
It forwards only configured provider-key variables.
|
||||
|
||||
## Fence current operational limitations
|
||||
|
||||
Open limitations until code/tests prove otherwise:
|
||||
|
||||
- `subprocess` + default `archie-agent` is protocol-incompatible.
|
||||
- Container RPC uses root forge/worktree for every identity.
|
||||
- Container orphan recovery lacks daemon-instance label.
|
||||
- `max_uptime` only bounds `Pool.Acquire` create/start; no lifetime timer.
|
||||
- Container workflow builds `TaskContext` without event bus.
|
||||
- SSE clients drop when channel full; replay at most 200 events.
|
||||
- Dashboard unauthenticated, includes mutating clear endpoint.
|
||||
|
||||
## Understand deployment and rollback seams
|
||||
|
||||
`.github/workflows/deploy.yml` gates on the release tags, then builds/pushes
|
||||
`archied:latest` and `archie-agent:latest` plus a versioned
|
||||
`linux/amd64` distribution zip attached to a GitHub Release. It injects
|
||||
component versions into labels/metadata and runs the quality gate before the
|
||||
Docker builds. The Gitea workflow that used to be the production build path was
|
||||
dropped (`dd9bddc2`); `deployments/*.toml` are the supported profiles.
|
||||
|
||||
Before promotion: record running image IDs/digests; config checksums (no
|
||||
secrets); task counts via safe GET; take backups with `archie-state-store backup`.
|
||||
|
||||
No complete rollback command exists, no versioned image tags. Restoring a binary
|
||||
does not undo forge changes, task transitions, or data-format changes.
|
||||
@@ -1,4 +0,0 @@
|
||||
interface:
|
||||
display_name: "Run and Operate Archie"
|
||||
short_description: "Run Archie safely and locate its operational state"
|
||||
default_prompt: "Use $archie-run-and-operate to start Archie locally, inspect its runtime state, and stop it safely."
|
||||
@@ -1,102 +0,0 @@
|
||||
---
|
||||
name: archie-web-ui
|
||||
description: "Develop, review, or redesign archie-core's dashboard web UI (ui/). Load when adding or changing Vue components, pages, views, styling, theming, layout, or interaction patterns under ui/src; when auditing UI accessibility or contrast; or when porting design prototypes (e.g. React mockups) into the Vue dashboard. Carries stack facts, design-system rules, and the operational-tool tone required here."
|
||||
---
|
||||
|
||||
# Web UI development (ui/)
|
||||
|
||||
Archie's dashboard is an **operational supervision tool** for senior developers
|
||||
watching an autonomous orchestrator: quiet, dense, scannable, work-focused.
|
||||
Not editorial, not marketing, not playful. Every rule below serves that.
|
||||
|
||||
## Stack facts (do not fight these)
|
||||
|
||||
- Vue 3 SFCs + TypeScript, Vite, Pinia, vue-router.
|
||||
- Tailwind CSS v4 via `@tailwindcss/vite`; `@custom-variant dark` keyed on the
|
||||
`[data-theme]` attribute; shadcn-vue + reka-ui for primitives;
|
||||
`@lucide/vue` for icons; IBM Plex Sans for UI, IBM Plex Mono for every
|
||||
machine value (Graphite theme, `docs/design/ui-redesign/`).
|
||||
- `ui/src/components/ui/` is CLI-installed only; never hand-edit it. Order of
|
||||
preference for a missing component: stock shadcn-vue (`npx shadcn-vue add`;
|
||||
reka-ui names differ, e.g. chip input is Tags input), another shadcn-vue
|
||||
registry (e.g. inspira-ui), then a new item in the sibling
|
||||
`archie-component-registry` repo, installed from its `public/r/<item>.json`.
|
||||
The CLI prompts to overwrite stock primitives an item depends on: answer no.
|
||||
To update an installed registry item, delete its `components/ui/<item>/`
|
||||
folder and add it again; never pass `--overwrite`, which also rewrites the
|
||||
stock components listed in its `registryDependencies`.
|
||||
If `npm install` fails with `EALLOWSCRIPTS`, run the CLI with
|
||||
`NPM_CONFIG_USERCONFIG=/dev/null`.
|
||||
- Features live in `ui/src/<feature>/` with colocated `.js`/`.css`. Extract a
|
||||
helper to `ui/src/base/` only on the **second distinct consumer**.
|
||||
- `ui/dist/` is committed and generated — never hand-edit it, never ignore it
|
||||
(see the header comment in `ui/src/style.css` for why builds are
|
||||
content-coupled to the bundle).
|
||||
- Gates: `task ui` (build), `task test:ui` (node --test over DOM-building
|
||||
primitives in `ui/test/`), `vue-tsc` via `npm run typecheck`. `task check`
|
||||
includes all of them.
|
||||
- The dashboard is a LAW asset built from `ui/dist` — a Go-side embed. A UI
|
||||
change is not done until `task ui` regenerates it and the commit carries it.
|
||||
|
||||
## Design-system rules
|
||||
|
||||
- **Tokens only.** Semantic CSS variables from `ui/src/style.css`
|
||||
(`--primary`, `--ok`, `--muted`, ...). Never a raw hex in a component, never
|
||||
a hue-named token. Dark is default; light defines the same variable set and
|
||||
is a first-class theme, not an afterthought. Density is a single knob
|
||||
(`[data-density="compact"]` tightens the spacing scale) — do not add
|
||||
per-component density conditionals.
|
||||
- **Icons, not text-as-decoration.** Buttons for clear commands use lucide
|
||||
icons (icon-only where the symbol is familiar, with a tooltip naming it);
|
||||
segmented controls for modes, toggles/checkboxes for binary settings,
|
||||
selects/menus for option sets, tabs for views.
|
||||
- **Cards 8px radius or less; no cards inside cards;** page sections are
|
||||
full-width bands or unframed layouts, not floating cards. No gradient orbs,
|
||||
bokeh blobs, or decorative backgrounds.
|
||||
- **Stable dimensions.** Tables, tiles, toolbars, sparklines, and icon buttons
|
||||
get fixed/constrained sizing so dynamic content (long titles, loading
|
||||
states, big numbers) cannot shift layout. Text never overflows its
|
||||
container on any viewport; wrap or downsize before it can.
|
||||
- **No viewport-scaled font sizes, no negative letter-spacing.**
|
||||
- **No one-note palettes.** If a screen reads as a single hue family
|
||||
(e.g. all-violet), rebalance with neutrals and status colours rather than
|
||||
more of the accent.
|
||||
- **No in-app prose explaining the app** — no help text describing features,
|
||||
keyboard shortcuts, or how to use a control. If a control needs explaining,
|
||||
redesign the control.
|
||||
- **No landing pages.** Every route opens the working experience directly.
|
||||
|
||||
## Tone & content
|
||||
|
||||
- Match copy to the domain: state names, gate results, timings, token counts —
|
||||
concrete operational nouns, not conversational flourishes. A header states
|
||||
system status ("Cluster operational · 4 awaiting intervention"), not a
|
||||
greeting.
|
||||
- Every human-actionable state (parked, gate failed, needs review) shows the
|
||||
reason inline and links to the exact place to act on it (the failing log,
|
||||
the gate output) — never just a status label.
|
||||
- High-frequency background telemetry is grouped/summarised in activity feeds
|
||||
("session-memory · 24 background cycles"), with high-signal events
|
||||
(stage finished, gate failure, task parked) visually elevated.
|
||||
|
||||
## Accessibility bar
|
||||
|
||||
- WCAG AA minimum on all text: secondary/metadata labels must clear 4.5:1
|
||||
against their actual background — audit the token, not the element. If a
|
||||
muted token fails, fix the token value (one file), not individual spots.
|
||||
- Log output, hashes, and code are monospace in a strict grid; do not put
|
||||
rounded pill badges inside raw log lines (breaks monospace alignment).
|
||||
Truncated stack traces fold into expandable blocks.
|
||||
- Controls that filter or toggle (log level, wrap, follow, search) live in a
|
||||
sticky toolbar inside the pane they affect.
|
||||
|
||||
## Porting design prototypes
|
||||
|
||||
External mockups (Gemini, Figma, React `.tsx` prototypes) are **specs, not
|
||||
code**. This app is Vue; translate layout, hierarchy, and interaction
|
||||
decisions into SFCs using shadcn-vue primitives and existing tokens. Mock data
|
||||
in a prototype proves nothing — verify the pattern against real task/log/diff
|
||||
shapes before building around it. A prototype proposing new information
|
||||
architecture (e.g. splitting the task view into a master-detail pane) is an
|
||||
open design question for the maintainer. Web UI design is not tracked in
|
||||
`docs/prds/`; record the decision on the bead and in `docs/design/`.
|
||||
@@ -1,89 +0,0 @@
|
||||
# Dolt database (managed by Dolt, not git)
|
||||
dolt/
|
||||
embeddeddolt/
|
||||
proxieddb/
|
||||
|
||||
# Runtime files
|
||||
bd.sock
|
||||
bd.sock.startlock
|
||||
sync-state.json
|
||||
last-touched
|
||||
.exclusive-lock
|
||||
|
||||
# Daemon runtime (lock, log, pid)
|
||||
daemon.*
|
||||
|
||||
# Push state (runtime, per-machine)
|
||||
push-state.json
|
||||
|
||||
# Lock files (various runtime locks)
|
||||
*.lock
|
||||
|
||||
# Credential key (encryption key for federation peer auth — never commit)
|
||||
.beads-credential-key
|
||||
|
||||
# Local version tracking (prevents upgrade notification spam after git ops)
|
||||
.local_version
|
||||
|
||||
proxied_server_client_info.json
|
||||
|
||||
# Worktree redirect file (contains relative path to main repo's .beads/)
|
||||
# Must not be committed as paths would be wrong in other clones
|
||||
redirect
|
||||
|
||||
# Sync state (local-only, per-machine)
|
||||
# These files are machine-specific and should not be shared across clones
|
||||
.sync.lock
|
||||
|
||||
# Workspace operation gate (internal/workspacegate): physical-root gate
|
||||
# files live beside the guarded root inside .beads (e.g. dolt.gate.lock)
|
||||
*.gate.lock*
|
||||
export-state/
|
||||
export-state.json
|
||||
last_pull
|
||||
|
||||
# Ephemeral store (SQLite - wisps/molecules, intentionally not versioned)
|
||||
ephemeral.sqlite3
|
||||
ephemeral.sqlite3-journal
|
||||
ephemeral.sqlite3-wal
|
||||
ephemeral.sqlite3-shm
|
||||
|
||||
# Dolt server management (auto-started by bd)
|
||||
dolt-server.pid
|
||||
dolt-server.log
|
||||
dolt-server.lock
|
||||
dolt-server.port
|
||||
dolt-server.activity
|
||||
|
||||
# Debug-mode pprof artifacts (written when dolt.debug: true in config.yaml)
|
||||
dolt-pprof/
|
||||
|
||||
# Corrupt backup directories (created by bd doctor --fix recovery)
|
||||
*.corrupt.backup/
|
||||
|
||||
# issues.jsonl is deliberately TRACKED (see export.git-add in config.yaml).
|
||||
# Dolt remains the authoritative store and GitHub the external issue surface;
|
||||
# the tracked export exists so issue state is readable and recoverable from a
|
||||
# plain git clone, without a Dolt server. Removing it from this file is what
|
||||
# tracks it -- do NOT add a "!issues.jsonl" negation, which would override the
|
||||
# fork protection in .git/info/exclude (see the note at the end of this file).
|
||||
#
|
||||
# Backups stay local: they are point-in-time copies of the same data.
|
||||
backup/
|
||||
|
||||
# Per-project environment file (Dolt connection config, GH#2520)
|
||||
.env
|
||||
|
||||
# Legacy files (from pre-Dolt versions)
|
||||
*.db
|
||||
*.db?*
|
||||
*.db-journal
|
||||
*.db-wal
|
||||
*.db-shm
|
||||
db.sqlite
|
||||
bd.db
|
||||
# NOTE: Do NOT add negation patterns here.
|
||||
# They would override fork protection in .git/info/exclude.
|
||||
# Config files (metadata.json, config.yaml) are tracked by git by default
|
||||
# since no pattern above ignores them.
|
||||
# config.yaml
|
||||
@@ -1,85 +0,0 @@
|
||||
# Beads - AI-Native Issue Tracking
|
||||
|
||||
Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code.
|
||||
|
||||
## What is Beads?
|
||||
|
||||
Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git.
|
||||
|
||||
**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Essential Commands
|
||||
|
||||
```bash
|
||||
# Create new issues
|
||||
bd create "Add user authentication"
|
||||
|
||||
# View all issues
|
||||
bd list
|
||||
|
||||
# View issue details
|
||||
bd show <issue-id>
|
||||
|
||||
# Update issue status
|
||||
bd update <issue-id> --claim
|
||||
bd update <issue-id> --status done
|
||||
|
||||
# Sync with Dolt remote
|
||||
bd dolt push
|
||||
```
|
||||
|
||||
### Working with Issues
|
||||
|
||||
Issues in Beads are:
|
||||
|
||||
- **Git-native**: Stored in Dolt database with version control and branching
|
||||
- **AI-friendly**: CLI-first design works perfectly with AI coding agents
|
||||
- **Branch-aware**: Issues can follow your branch workflow
|
||||
- **Sync-ready**: Uses Dolt remotes for backup and team sharing
|
||||
|
||||
## Why Beads?
|
||||
|
||||
✨ **AI-Native Design**
|
||||
|
||||
- Built specifically for AI-assisted development workflows
|
||||
- CLI-first interface works seamlessly with AI coding agents
|
||||
- No context switching to web UIs
|
||||
|
||||
🚀 **Developer Focused**
|
||||
|
||||
- Issues live in your repo, right next to your code
|
||||
- Works offline, syncs when you push
|
||||
- Fast, lightweight, and stays out of your way
|
||||
|
||||
🔧 **Git Integration**
|
||||
|
||||
- Dolt-native sync via bd dolt push / bd dolt pull
|
||||
- Branch-aware issue tracking
|
||||
- Dolt-native three-way merge resolution
|
||||
|
||||
## Get Started with Beads
|
||||
|
||||
Try Beads in your own projects:
|
||||
|
||||
```bash
|
||||
# Install Beads
|
||||
curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
|
||||
|
||||
# Initialize in your repo
|
||||
bd init
|
||||
|
||||
# Create your first issue
|
||||
bd create "Try out Beads"
|
||||
```
|
||||
|
||||
## Learn More
|
||||
|
||||
- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
|
||||
- **Quick Start Guide**: Run `bd quickstart`
|
||||
- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
|
||||
|
||||
---
|
||||
|
||||
_Beads: Issue tracking that moves at the speed of thought_ ⚡
|
||||
@@ -1,80 +0,0 @@
|
||||
# Beads Configuration File
|
||||
# This file configures default behavior for all bd commands in this repository
|
||||
# All settings can also be set via environment variables (BD_* prefix)
|
||||
# or overridden with command-line flags
|
||||
|
||||
# Issue prefix for this repository (used by bd init)
|
||||
# If not set, bd init will auto-detect from directory name
|
||||
# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
|
||||
# issue-prefix: ""
|
||||
|
||||
# Use no-db mode: JSONL-only, no Dolt database
|
||||
# When true, .beads/issues.jsonl is the only local store
|
||||
# no-db: false
|
||||
|
||||
# Enable JSON output by default
|
||||
# json: false
|
||||
|
||||
# Feedback title formatting for mutating commands (create/update/close/dep/edit)
|
||||
# 0 = hide titles, N > 0 = truncate to N characters
|
||||
# output:
|
||||
# title-length: 255
|
||||
|
||||
# Default actor for audit trails (overridden by BEADS_ACTOR or --actor)
|
||||
# actor: ""
|
||||
|
||||
# Optional JSONL sidecar for explicit agent/tool interaction audit records.
|
||||
# Issue history is always recorded in the database and is visible with
|
||||
# bd history <id> --events; this only controls .beads/interactions.jsonl.
|
||||
# audit:
|
||||
# enabled: false
|
||||
|
||||
# Export events (audit trail) to .beads/events.jsonl on each flush/sync
|
||||
# When enabled, new events are appended incrementally using a high-water mark.
|
||||
# Use 'bd export --events' to trigger manually regardless of this setting.
|
||||
# events-export: false
|
||||
|
||||
# Multi-repo configuration (experimental - bd-307)
|
||||
# Allows hydrating from multiple repositories and routing writes to the correct database
|
||||
# repos:
|
||||
# primary: "." # Primary repo (where this database lives)
|
||||
# additional: # Additional repos to hydrate from (read-only)
|
||||
# - ~/beads-planning # Personal planning repo
|
||||
# - ~/work-planning # Work planning repo
|
||||
|
||||
# Dolt-native backup (periodic backup for off-machine recovery)
|
||||
# This is full database backup only. Cross-machine sync uses Dolt remotes.
|
||||
# backup:
|
||||
# enabled: false # Disable auto-backup entirely
|
||||
# interval: 15m # Minimum time between auto-backups
|
||||
# git-push: false # Disable git push (backup locally only)
|
||||
# git-repo: "" # Separate git repo for backups (default: project repo)
|
||||
|
||||
# Optional JSONL auto-export for viewers, interchange, and issue-level migration.
|
||||
# Disabled by default; enable only when an integration needs fresh .beads/issues.jsonl.
|
||||
# Use relative paths under .beads/ for JSONL import/export filenames.
|
||||
export:
|
||||
auto: false
|
||||
path: issues.jsonl
|
||||
interval: 60s
|
||||
# issues.jsonl/interactions.jsonl are .gitignore'd local-only files --
|
||||
# Dolt (synced via sync.remote) is the source of truth. Leave auto off
|
||||
# and git-add off; do not re-track these in git.
|
||||
git-add: false
|
||||
import:
|
||||
path: issues.jsonl
|
||||
# Integration settings (access with 'bd config get/set')
|
||||
# Non-secret keys (stored in the database):
|
||||
# - jira.url, jira.project
|
||||
# - linear.team_id
|
||||
# - github.org, github.repo
|
||||
#
|
||||
# Secret keys (stored in this file but prefer env vars to avoid git exposure):
|
||||
# - linear.api_key → use LINEAR_API_KEY env var instead
|
||||
# - github.token → use GITHUB_TOKEN env var instead
|
||||
sync.remote: "git+https://github.com/samcharles93/archie-core.git"
|
||||
dolt:
|
||||
shared-server: false
|
||||
auto-commit: "on"
|
||||
audit:
|
||||
enabled: true
|
||||
@@ -1,33 +0,0 @@
|
||||
#!/usr/bin/env sh
|
||||
# --- BEGIN BEADS INTEGRATION v1.2.2 ---
|
||||
# This section is managed by beads. Do not remove these markers.
|
||||
if command -v bd >/dev/null 2>&1; then
|
||||
export BD_GIT_HOOK=1
|
||||
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
|
||||
_bd_used_perl=0
|
||||
if command -v timeout >/dev/null 2>&1; then
|
||||
timeout "$_bd_timeout" bd hooks run post-checkout "$@"
|
||||
_bd_exit=$?
|
||||
elif command -v gtimeout >/dev/null 2>&1; then
|
||||
gtimeout "$_bd_timeout" bd hooks run post-checkout "$@"
|
||||
_bd_exit=$?
|
||||
elif command -v perl >/dev/null 2>&1; then
|
||||
_bd_used_perl=1
|
||||
perl -e 'alarm shift; exec @ARGV' "$_bd_timeout" bd hooks run post-checkout "$@"
|
||||
_bd_exit=$?
|
||||
else
|
||||
echo >&2 "beads: hook 'post-checkout' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
|
||||
bd hooks run post-checkout "$@"
|
||||
_bd_exit=$?
|
||||
fi
|
||||
if [ $_bd_exit -eq 124 ] || { [ $_bd_used_perl -eq 1 ] && [ $_bd_exit -eq 142 ]; }; then
|
||||
echo >&2 "beads: hook 'post-checkout' timed out after ${_bd_timeout}s — continuing without beads"
|
||||
_bd_exit=0
|
||||
fi
|
||||
if [ $_bd_exit -eq 3 ]; then
|
||||
echo >&2 "beads: database not initialized — skipping hook 'post-checkout'"
|
||||
_bd_exit=0
|
||||
fi
|
||||
if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
|
||||
fi
|
||||
# --- END BEADS INTEGRATION v1.2.2 ---
|
||||
@@ -1,33 +0,0 @@
|
||||
#!/usr/bin/env sh
|
||||
# --- BEGIN BEADS INTEGRATION v1.2.2 ---
|
||||
# This section is managed by beads. Do not remove these markers.
|
||||
if command -v bd >/dev/null 2>&1; then
|
||||
export BD_GIT_HOOK=1
|
||||
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
|
||||
_bd_used_perl=0
|
||||
if command -v timeout >/dev/null 2>&1; then
|
||||
timeout "$_bd_timeout" bd hooks run post-merge "$@"
|
||||
_bd_exit=$?
|
||||
elif command -v gtimeout >/dev/null 2>&1; then
|
||||
gtimeout "$_bd_timeout" bd hooks run post-merge "$@"
|
||||
_bd_exit=$?
|
||||
elif command -v perl >/dev/null 2>&1; then
|
||||
_bd_used_perl=1
|
||||
perl -e 'alarm shift; exec @ARGV' "$_bd_timeout" bd hooks run post-merge "$@"
|
||||
_bd_exit=$?
|
||||
else
|
||||
echo >&2 "beads: hook 'post-merge' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
|
||||
bd hooks run post-merge "$@"
|
||||
_bd_exit=$?
|
||||
fi
|
||||
if [ $_bd_exit -eq 124 ] || { [ $_bd_used_perl -eq 1 ] && [ $_bd_exit -eq 142 ]; }; then
|
||||
echo >&2 "beads: hook 'post-merge' timed out after ${_bd_timeout}s — continuing without beads"
|
||||
_bd_exit=0
|
||||
fi
|
||||
if [ $_bd_exit -eq 3 ]; then
|
||||
echo >&2 "beads: database not initialized — skipping hook 'post-merge'"
|
||||
_bd_exit=0
|
||||
fi
|
||||
if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
|
||||
fi
|
||||
# --- END BEADS INTEGRATION v1.2.2 ---
|
||||
@@ -1,33 +0,0 @@
|
||||
#!/usr/bin/env sh
|
||||
# --- BEGIN BEADS INTEGRATION v1.2.2 ---
|
||||
# This section is managed by beads. Do not remove these markers.
|
||||
if command -v bd >/dev/null 2>&1; then
|
||||
export BD_GIT_HOOK=1
|
||||
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
|
||||
_bd_used_perl=0
|
||||
if command -v timeout >/dev/null 2>&1; then
|
||||
timeout "$_bd_timeout" bd hooks run pre-commit "$@"
|
||||
_bd_exit=$?
|
||||
elif command -v gtimeout >/dev/null 2>&1; then
|
||||
gtimeout "$_bd_timeout" bd hooks run pre-commit "$@"
|
||||
_bd_exit=$?
|
||||
elif command -v perl >/dev/null 2>&1; then
|
||||
_bd_used_perl=1
|
||||
perl -e 'alarm shift; exec @ARGV' "$_bd_timeout" bd hooks run pre-commit "$@"
|
||||
_bd_exit=$?
|
||||
else
|
||||
echo >&2 "beads: hook 'pre-commit' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
|
||||
bd hooks run pre-commit "$@"
|
||||
_bd_exit=$?
|
||||
fi
|
||||
if [ $_bd_exit -eq 124 ] || { [ $_bd_used_perl -eq 1 ] && [ $_bd_exit -eq 142 ]; }; then
|
||||
echo >&2 "beads: hook 'pre-commit' timed out after ${_bd_timeout}s — continuing without beads"
|
||||
_bd_exit=0
|
||||
fi
|
||||
if [ $_bd_exit -eq 3 ]; then
|
||||
echo >&2 "beads: database not initialized — skipping hook 'pre-commit'"
|
||||
_bd_exit=0
|
||||
fi
|
||||
if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
|
||||
fi
|
||||
# --- END BEADS INTEGRATION v1.2.2 ---
|
||||
@@ -1,33 +0,0 @@
|
||||
#!/usr/bin/env sh
|
||||
# --- BEGIN BEADS INTEGRATION v1.2.2 ---
|
||||
# This section is managed by beads. Do not remove these markers.
|
||||
if command -v bd >/dev/null 2>&1; then
|
||||
export BD_GIT_HOOK=1
|
||||
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
|
||||
_bd_used_perl=0
|
||||
if command -v timeout >/dev/null 2>&1; then
|
||||
timeout "$_bd_timeout" bd hooks run pre-push "$@"
|
||||
_bd_exit=$?
|
||||
elif command -v gtimeout >/dev/null 2>&1; then
|
||||
gtimeout "$_bd_timeout" bd hooks run pre-push "$@"
|
||||
_bd_exit=$?
|
||||
elif command -v perl >/dev/null 2>&1; then
|
||||
_bd_used_perl=1
|
||||
perl -e 'alarm shift; exec @ARGV' "$_bd_timeout" bd hooks run pre-push "$@"
|
||||
_bd_exit=$?
|
||||
else
|
||||
echo >&2 "beads: hook 'pre-push' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
|
||||
bd hooks run pre-push "$@"
|
||||
_bd_exit=$?
|
||||
fi
|
||||
if [ $_bd_exit -eq 124 ] || { [ $_bd_used_perl -eq 1 ] && [ $_bd_exit -eq 142 ]; }; then
|
||||
echo >&2 "beads: hook 'pre-push' timed out after ${_bd_timeout}s — continuing without beads"
|
||||
_bd_exit=0
|
||||
fi
|
||||
if [ $_bd_exit -eq 3 ]; then
|
||||
echo >&2 "beads: database not initialized — skipping hook 'pre-push'"
|
||||
_bd_exit=0
|
||||
fi
|
||||
if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
|
||||
fi
|
||||
# --- END BEADS INTEGRATION v1.2.2 ---
|
||||
@@ -1,33 +0,0 @@
|
||||
#!/usr/bin/env sh
|
||||
# --- BEGIN BEADS INTEGRATION v1.2.2 ---
|
||||
# This section is managed by beads. Do not remove these markers.
|
||||
if command -v bd >/dev/null 2>&1; then
|
||||
export BD_GIT_HOOK=1
|
||||
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
|
||||
_bd_used_perl=0
|
||||
if command -v timeout >/dev/null 2>&1; then
|
||||
timeout "$_bd_timeout" bd hooks run prepare-commit-msg "$@"
|
||||
_bd_exit=$?
|
||||
elif command -v gtimeout >/dev/null 2>&1; then
|
||||
gtimeout "$_bd_timeout" bd hooks run prepare-commit-msg "$@"
|
||||
_bd_exit=$?
|
||||
elif command -v perl >/dev/null 2>&1; then
|
||||
_bd_used_perl=1
|
||||
perl -e 'alarm shift; exec @ARGV' "$_bd_timeout" bd hooks run prepare-commit-msg "$@"
|
||||
_bd_exit=$?
|
||||
else
|
||||
echo >&2 "beads: hook 'prepare-commit-msg' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
|
||||
bd hooks run prepare-commit-msg "$@"
|
||||
_bd_exit=$?
|
||||
fi
|
||||
if [ $_bd_exit -eq 124 ] || { [ $_bd_used_perl -eq 1 ] && [ $_bd_exit -eq 142 ]; }; then
|
||||
echo >&2 "beads: hook 'prepare-commit-msg' timed out after ${_bd_timeout}s — continuing without beads"
|
||||
_bd_exit=0
|
||||
fi
|
||||
if [ $_bd_exit -eq 3 ]; then
|
||||
echo >&2 "beads: database not initialized — skipping hook 'prepare-commit-msg'"
|
||||
_bd_exit=0
|
||||
fi
|
||||
if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
|
||||
fi
|
||||
# --- END BEADS INTEGRATION v1.2.2 ---
|
||||
@@ -1,8 +0,0 @@
|
||||
{
|
||||
"database": "dolt",
|
||||
"backend": "dolt",
|
||||
"dolt_mode": "embedded",
|
||||
"dolt_database": "archie_core",
|
||||
"project_id": "e8a66150-1f5f-42d2-8653-dcf8463cef74",
|
||||
"last_bd_version": "1.2.2"
|
||||
}
|
||||
+6
-1
@@ -10,7 +10,12 @@
|
||||
bin/
|
||||
dist/
|
||||
docs/
|
||||
node_modules/
|
||||
tmp/
|
||||
.playwright-mcp/
|
||||
# A trailing-slash pattern matches only the context root, so this is written to
|
||||
# match a node_modules at any depth: ui/node_modules alone is 200MB and the
|
||||
# agent image compiles Go, which needs none of it.
|
||||
**/node_modules/
|
||||
|
||||
# Stray host-built binaries committed at the repo root.
|
||||
/archied
|
||||
|
||||
+158
-290
@@ -1,27 +1,11 @@
|
||||
# Builds and pushes the archied and archie-agent images to GHCR on every
|
||||
# merge to main. Mirrors .gitea/workflows/deploy.yml, which remains the
|
||||
# production build path against git.catlow.cloud until that's cut over.
|
||||
name: deploy
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
tags: ["archied/v*", "archie/v*", "v*"]
|
||||
tags: ["v*"]
|
||||
|
||||
# Rapid successive pushes to main (a release commit right after its
|
||||
# preceding fix, say) previously queued a full gate+build for each one,
|
||||
# several minutes apiece, with no caching -- so a burst of pushes left
|
||||
# three deploys racing in parallel for the same runner capacity. Only the
|
||||
# last one's images matter (each job pushes its image tags), so cancel a
|
||||
# superseded run rather than let it fight for resources it can't use.
|
||||
#
|
||||
# Keyed on the commit, not github.ref: `git push --follow-tags` pushes
|
||||
# main plus both archied/v* and archie/v* tags in one go, and all three
|
||||
# refs point at the same commit -- on.push matches branches and tags
|
||||
# both, so a single release push otherwise fires three redundant builds
|
||||
# of identical content that a ref-keyed group can't see as the same work.
|
||||
concurrency:
|
||||
group: deploy-${{ github.sha }}
|
||||
group: deploy-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
permissions:
|
||||
@@ -29,303 +13,181 @@ permissions:
|
||||
packages: write
|
||||
|
||||
jobs:
|
||||
gate:
|
||||
runs-on: ubuntu-latest
|
||||
plan:
|
||||
runs-on: self-hosted
|
||||
outputs:
|
||||
archied_version: ${{ steps.release_tag.outputs.archied_version }}
|
||||
sha: ${{ steps.release_tag.outputs.sha }}
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
|
||||
|
||||
- name: Resolve the release
|
||||
id: release_tag
|
||||
run: |
|
||||
echo "archied_version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
|
||||
echo "sha=$(git rev-parse "${GITHUB_REF}^{commit}")" >> "$GITHUB_OUTPUT"
|
||||
|
||||
gate:
|
||||
needs: plan
|
||||
runs-on: self-hosted
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
# Read the release from the commit, not from github.ref. One release
|
||||
# push carries main and both tags at the same SHA, and only one of
|
||||
# those refs survives the concurrency group, so a ref-derived version
|
||||
# is whatever won the race. The tag at HEAD is the same either way.
|
||||
- name: Resolve archied tag at HEAD
|
||||
id: release_tag
|
||||
run: |
|
||||
version="$(git tag --points-at HEAD --list 'archied/v*' --list 'v*' | sed -e 's|^archied/v||' -e 's|^v||' | sort -V | tail -1)"
|
||||
echo "archied_version=$version" >> "$GITHUB_OUTPUT"
|
||||
if [ -n "$version" ]; then
|
||||
echo "archied release at HEAD: $version"
|
||||
else
|
||||
echo "no release tag at HEAD; distribution zip will be skipped"
|
||||
fi
|
||||
|
||||
- name: Set up Go
|
||||
uses: actions/setup-go@v5
|
||||
uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff
|
||||
with:
|
||||
go-version-file: go.mod
|
||||
cache: false
|
||||
|
||||
- uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1
|
||||
with:
|
||||
package_json_file: ui/package.json
|
||||
|
||||
- name: Set up Node
|
||||
uses: actions/setup-node@v4
|
||||
uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
|
||||
with:
|
||||
node-version: "22"
|
||||
node-version: "24"
|
||||
|
||||
- name: Install quality tools
|
||||
run: |
|
||||
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.2
|
||||
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@$(cat .golangci-version)
|
||||
go install mvdan.cc/gofumpt@v0.11.0
|
||||
go install github.com/go-task/task/v3/cmd/task@v3.48.0
|
||||
|
||||
- name: Install protobuf tools
|
||||
run: bash tools/proto.sh install
|
||||
|
||||
# The backup/restore tests shell out to pg_dump/pg_restore against a
|
||||
# postgres:18 testcontainer; the runner's stock client is older and
|
||||
# refuses the server version.
|
||||
- name: Install PostgreSQL 18 client
|
||||
run: |
|
||||
sudo install -d /usr/share/postgresql-common/pgdg
|
||||
sudo curl --fail --silent --show-error --location \
|
||||
https://www.postgresql.org/media/keys/ACCC4CF8.asc \
|
||||
--output /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc
|
||||
. /etc/os-release
|
||||
echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt ${VERSION_CODENAME}-pgdg main" \
|
||||
| sudo tee /etc/apt/sources.list.d/pgdg.list
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y --no-install-recommends postgresql-client-18
|
||||
echo "/usr/lib/postgresql/18/bin" >> $GITHUB_PATH
|
||||
|
||||
- name: Ensure contract baseline ref
|
||||
run: |
|
||||
if ! git show-ref --verify --quiet refs/heads/main; then
|
||||
git branch main origin/main
|
||||
fi
|
||||
|
||||
- name: Install ripgrep
|
||||
run: sudo apt-get update && sudo apt-get install -y --no-install-recommends ripgrep
|
||||
- name: Verify unprivileged user namespaces
|
||||
run: unshare --user --map-root-user --net true
|
||||
|
||||
- name: Pull test container images
|
||||
run: docker pull alpine:3
|
||||
|
||||
- name: Quality gate
|
||||
env:
|
||||
RELEASE_VERSION: ${{ needs.plan.outputs.archied_version }}
|
||||
run: |
|
||||
go fix ./...
|
||||
golangci-lint fmt
|
||||
task check dist TEST_FLAGS=-count=1 VERSION="$RELEASE_VERSION"
|
||||
git diff --exit-code
|
||||
bash tools/proto.sh lint
|
||||
bash tools/proto.sh check
|
||||
go vet ./...
|
||||
golangci-lint run ./...
|
||||
go build ./...
|
||||
go test ./... -count=1
|
||||
|
||||
- name: Vulnerability scan
|
||||
run: |
|
||||
go install golang.org/x/vuln/cmd/govulncheck@latest
|
||||
go install golang.org/x/vuln/cmd/govulncheck@v1.9.0
|
||||
govulncheck ./...
|
||||
|
||||
# The dashboard suite runs in CI too, or it only ever runs when
|
||||
# someone remembers to; the Go steps above never touch it.
|
||||
- name: Dashboard tests
|
||||
run: |
|
||||
npm ci --prefix ui || npm install --prefix ui
|
||||
npm test --prefix ui
|
||||
- name: Package the release binaries
|
||||
# tar keeps the executable bit, which an uploaded artifact drops.
|
||||
run: tar -cf release-binaries.tar dist
|
||||
|
||||
- name: Release tags must match changelogs
|
||||
run: |
|
||||
set -e
|
||||
fail=0
|
||||
for tag in $(git tag --points-at HEAD); do
|
||||
case "$tag" in
|
||||
v*)
|
||||
ver="${tag#v}"
|
||||
echo " release tag $tag -> looking for [$ver] in CHANGELOG.md"
|
||||
grep -q "^## \\[$ver\\]" CHANGELOG.md || {
|
||||
echo " FAIL: CHANGELOG.md has no [$ver] section"
|
||||
fail=1
|
||||
}
|
||||
;;
|
||||
archied/v* | archie/v*)
|
||||
# Legacy per-component tags. History is not re-tagged, and the
|
||||
# merged CHANGELOG.md carries every component's versions, so the
|
||||
# section is found there rather than in a component file.
|
||||
ver="${tag#*/v}"
|
||||
echo " legacy tag $tag -> looking for [$ver] in CHANGELOG.md"
|
||||
grep -q "^## \\[$ver\\]" CHANGELOG.md || {
|
||||
echo " FAIL: CHANGELOG.md has no [$ver] section"
|
||||
fail=1
|
||||
}
|
||||
;;
|
||||
esac
|
||||
done
|
||||
if [ $fail -ne 0 ]; then
|
||||
echo
|
||||
echo "A release tag points at this commit but its changelog does not"
|
||||
echo "describe that version. Run: task release:prepare VERSION=<ver>"
|
||||
echo "edit the generated notes, then: task release VERSION=<ver>"
|
||||
exit 1
|
||||
fi
|
||||
if ! git tag --points-at HEAD | grep -qE '^(v[0-9]|archied/v|archie/v)' ; then
|
||||
echo "This commit is not a release, so the images are published as :edge and sha-<sha>; :latest keeps naming the newest release."
|
||||
fi
|
||||
- name: Upload the release binaries
|
||||
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
|
||||
with:
|
||||
name: release-binaries
|
||||
path: release-binaries.tar
|
||||
if-no-files-found: error
|
||||
retention-days: 1
|
||||
|
||||
build-and-push:
|
||||
needs: gate
|
||||
runs-on: ubuntu-latest
|
||||
archied-image:
|
||||
needs: [plan, gate]
|
||||
runs-on: self-hosted
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
# Deliberately NOT `github.sha`. On a tag push that is the ref's OBJECT id,
|
||||
# and every release tag in this repo is annotated — measured, 80 of 80
|
||||
# `archied/v*` and `archie/v*` tags are tag objects — so it names something
|
||||
# that cannot be checked out. `archied/v1.36.0` is an instance: it points at
|
||||
# 6720bc42 (a tag object) and dereferences to commit c25f8d39. The producer
|
||||
# is right to create annotated tags; the consumer stops guessing.
|
||||
- name: Resolve the commit this ref points at
|
||||
id: commit
|
||||
run: |
|
||||
sha="$(git rev-parse "${GITHUB_REF}^{commit}")"
|
||||
echo "sha=$sha" >> "$GITHUB_OUTPUT"
|
||||
echo "short=${sha:0:12}" >> "$GITHUB_OUTPUT"
|
||||
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
|
||||
|
||||
- name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v3
|
||||
uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f
|
||||
with:
|
||||
# One named builder that is never removed, so the Dockerfiles' cache
|
||||
# mounts are still there on the next run. Removing it at the end of
|
||||
# a job would take it from under another run that is building.
|
||||
name: archie-ci
|
||||
cleanup: false
|
||||
|
||||
- name: Log in to GHCR
|
||||
run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
|
||||
|
||||
- name: Resolve component versions
|
||||
id: versions
|
||||
run: |
|
||||
GATEWAY_TAG="$(git tag --points-at HEAD --list 'archied/v*' | sort -V | tail -1)"
|
||||
RUNTIME_TAG="$(git tag --points-at HEAD --list 'archie/v*' | sort -V | tail -1)"
|
||||
# One release stream: a `v*` tag covers the whole release, so it names
|
||||
# both components' versions. Legacy per-component tags still win where
|
||||
# they exist, because history is not re-tagged.
|
||||
RELEASE_TAG="$(git tag --points-at HEAD --list 'v*' | sort -V | tail -1)"
|
||||
GATEWAY_VERSION="${GATEWAY_TAG#archied/}"
|
||||
RUNTIME_VERSION="${RUNTIME_TAG#archie/}"
|
||||
[ -n "$GATEWAY_VERSION" ] || GATEWAY_VERSION="${RELEASE_TAG#v}"
|
||||
[ -n "$RUNTIME_VERSION" ] || RUNTIME_VERSION="${RELEASE_TAG#v}"
|
||||
# `dev+<sha>` is what a build that is NOT a release reports, and it is
|
||||
# honest now that such a build no longer publishes :latest: the version
|
||||
# names the commit it came from, and the sha-<sha> tag makes it
|
||||
# restorable. Before, this same string reached :latest minutes after a
|
||||
# release and made the release's own stamping read as dev
|
||||
# (archie-core-i5nb). (On an untagged push GITHUB_SHA IS the commit —
|
||||
# the tag case is handled by the dereference above.)
|
||||
[ -n "$GATEWAY_VERSION" ] || GATEWAY_VERSION="dev+${GITHUB_SHA:0:12}"
|
||||
[ -n "$RUNTIME_VERSION" ] || RUNTIME_VERSION="dev+${GITHUB_SHA:0:12}"
|
||||
# Keep the raw tag presence separate from the version fallback: a
|
||||
# LEGACY gateway-only release (archied/v* and no archie/v*) must not
|
||||
# rebuild the runtime image as dev. A one-stream `v*` release is not
|
||||
# gateway-only -- one version covers the runtime too -- so it does
|
||||
# rebuild it, and release_tag is what tells the two apart.
|
||||
echo "gateway_tag=$GATEWAY_TAG" >> "$GITHUB_OUTPUT"
|
||||
echo "runtime_tag=$RUNTIME_TAG" >> "$GITHUB_OUTPUT"
|
||||
echo "release_tag=$RELEASE_TAG" >> "$GITHUB_OUTPUT"
|
||||
echo "gateway=$GATEWAY_VERSION" >> "$GITHUB_OUTPUT"
|
||||
echo "runtime=$RUNTIME_VERSION" >> "$GITHUB_OUTPUT"
|
||||
# :latest names the newest RELEASE, so only a commit that IS one
|
||||
# publishes it. A push to main publishes :edge (mutable, newest main)
|
||||
# and sha-<sha> (immutable) instead. That is what stops a release's
|
||||
# :latest stamping from being overwritten minutes later by the next
|
||||
# ordinary commit, which left a host reporting dev and made the update
|
||||
# path unable to tell current from stale (archie-core-i5nb).
|
||||
#
|
||||
# `if` blocks rather than `[ -n "$X" ] && echo`: the latter returns
|
||||
# non-zero when the test fails, and these steps run under `set -e`.
|
||||
{
|
||||
echo "archied_tags<<EOF"
|
||||
if [ -n "$RELEASE_TAG" ]; then
|
||||
echo "ghcr.io/samcharles93/archied:latest"
|
||||
fi
|
||||
echo "ghcr.io/samcharles93/archied:edge"
|
||||
echo "ghcr.io/samcharles93/archied:sha-${{ steps.commit.outputs.sha }}"
|
||||
echo "EOF"
|
||||
} >> "$GITHUB_OUTPUT"
|
||||
- name: Log in to the Gitea registry
|
||||
run: echo "${{ secrets.DEPLOY_TOKEN }}" | docker login git.catlow.cloud -u "${{ github.actor }}" --password-stdin
|
||||
|
||||
- name: Build and push archied
|
||||
uses: docker/build-push-action@v6
|
||||
uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8
|
||||
with:
|
||||
context: .
|
||||
file: Dockerfile.archied
|
||||
push: true
|
||||
tags: ${{ steps.versions.outputs.archied_tags }}
|
||||
tags: |
|
||||
git.catlow.cloud/sam/archied:v${{ needs.plan.outputs.archied_version }}
|
||||
git.catlow.cloud/sam/archied:sha-${{ needs.plan.outputs.sha }}
|
||||
build-args: |
|
||||
GATEWAY_VERSION=${{ steps.versions.outputs.gateway }}
|
||||
RUNTIME_VERSION=${{ steps.versions.outputs.runtime }}
|
||||
GATEWAY_VERSION=${{ needs.plan.outputs.archied_version }}
|
||||
RUNTIME_VERSION=${{ needs.plan.outputs.archied_version }}
|
||||
cache-from: type=gha,scope=archied
|
||||
cache-to: type=gha,mode=max,scope=archied
|
||||
|
||||
agent-image:
|
||||
needs: [plan, gate]
|
||||
outputs:
|
||||
agent_digest: ${{ steps.agent.outputs.digest }}
|
||||
runs-on: self-hosted
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
|
||||
|
||||
- name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f
|
||||
with:
|
||||
# One named builder that is never removed, so the Dockerfiles' cache
|
||||
# mounts are still there on the next run. Removing it at the end of
|
||||
# a job would take it from under another run that is building.
|
||||
name: archie-ci
|
||||
cleanup: false
|
||||
|
||||
- name: Log in to the Gitea registry
|
||||
run: echo "${{ secrets.DEPLOY_TOKEN }}" | docker login git.catlow.cloud -u "${{ github.actor }}" --password-stdin
|
||||
|
||||
- name: Build and push archie-agent
|
||||
if: steps.versions.outputs.runtime_tag != '' || steps.versions.outputs.release_tag != ''
|
||||
uses: docker/build-push-action@v6
|
||||
id: agent
|
||||
uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8
|
||||
with:
|
||||
context: .
|
||||
file: Dockerfile
|
||||
push: true
|
||||
tags: |
|
||||
ghcr.io/samcharles93/archie-agent:latest
|
||||
ghcr.io/samcharles93/archie-agent:sha-${{ steps.commit.outputs.sha }}
|
||||
git.catlow.cloud/sam/archie-agent:v${{ needs.plan.outputs.archied_version }}
|
||||
git.catlow.cloud/sam/archie-agent:sha-${{ needs.plan.outputs.sha }}
|
||||
build-args: |
|
||||
RUNTIME_VERSION=${{ steps.versions.outputs.runtime }}
|
||||
RUNTIME_VERSION=${{ needs.plan.outputs.archied_version }}
|
||||
cache-from: type=gha,scope=archie-agent
|
||||
cache-to: type=gha,mode=max,scope=archie-agent
|
||||
|
||||
# Packages every host-run binary (archied, archie-gateway,
|
||||
# archie-state-store, archie-ui, archie-messaging, archie-playbooks) as a
|
||||
# linux/amd64 zip for a
|
||||
# non-Docker install. Independent of build-and-push: it never touches the
|
||||
# archied/archie-agent image jobs, and a gateway-only release (no
|
||||
# archie/v* tag) still produces this zip -- it's keyed to the archied tag
|
||||
# alone. archie-agent is deliberately excluded: it only ever runs inside
|
||||
# the Docker image build-and-push already publishes, never as a host
|
||||
# binary (archie-core-8cda.4.7.1).
|
||||
dist-zip:
|
||||
needs: gate
|
||||
# Not gated on github.ref. A release is pushed as main plus both tags at
|
||||
# one SHA, the concurrency group below collapses those into a single run,
|
||||
# and the survivor is whichever ref happened to start last -- for
|
||||
# v1.23.0 that was refs/heads/main, so this job was skipped and no zip
|
||||
# was ever produced. Resolve the tag from the commit instead of trusting
|
||||
# the ref that won the race, and skip only when there is genuinely no
|
||||
# archied tag at HEAD.
|
||||
if: needs.gate.outputs.archied_version != ''
|
||||
runs-on: ubuntu-latest
|
||||
# Least privilege: the workflow default is contents:read, and only this
|
||||
# job needs to write, to create the Release and attach the zip to it.
|
||||
permissions:
|
||||
contents: write
|
||||
needs: [plan, gate, archied-image, agent-image]
|
||||
runs-on: self-hosted
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Go
|
||||
uses: actions/setup-go@v5
|
||||
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
|
||||
with:
|
||||
go-version-file: go.mod
|
||||
fetch-depth: 0
|
||||
|
||||
# The gate built these from the tree it checked; nothing is compiled here.
|
||||
- name: Download the release binaries
|
||||
uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
|
||||
with:
|
||||
name: release-binaries
|
||||
|
||||
- name: Unpack the release binaries
|
||||
run: tar -xf release-binaries.tar
|
||||
|
||||
- name: Resolve archied version
|
||||
id: version
|
||||
run: echo "version=${{ needs.gate.outputs.archied_version }}" >> "$GITHUB_OUTPUT"
|
||||
|
||||
- name: Build linux/amd64 binaries
|
||||
env:
|
||||
GOOS: linux
|
||||
GOARCH: amd64
|
||||
CGO_ENABLED: "0"
|
||||
run: |
|
||||
set -e
|
||||
# Every process in the documented deployment ships in the zip, and
|
||||
# every one of them carries the archied version it was cut from:
|
||||
# they are one release, and an operator matching binaries by eye
|
||||
# needs each to say so.
|
||||
#
|
||||
# That claim is load-bearing and this list is the whole of it: the
|
||||
# v1.30.0 messaging extraction moved Telegram/email/webhook out of
|
||||
# archied and nothing added archie-messaging here, so a host install
|
||||
# ran on with a dead Telegram bot and no error anywhere
|
||||
# (archie-core-1c01). TestDistZipShipsEveryHostCommand fails if this
|
||||
# list and the copy list below stop matching the commands in cmd/.
|
||||
ldflags="-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion=${{ steps.version.outputs.version }} -X github.com/samcharles93/archie-core/internal/app/archied.runtimeVersion=${{ steps.version.outputs.version }} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary -X github.com/samcharles93/archie-core/internal/buildinfo.Version=${{ steps.version.outputs.version }} -X github.com/samcharles93/archie-core/internal/buildinfo.Runtime=${{ steps.version.outputs.version }}"
|
||||
mkdir -p dist
|
||||
for cmd in archied archie-gateway archie-state-store archie-ui archie-messaging archie-playbooks; do
|
||||
go build -ldflags "$ldflags" -o "dist/$cmd" "./cmd/$cmd"
|
||||
done
|
||||
run: echo "version=${{ needs.plan.outputs.archied_version }}" >> "$GITHUB_OUTPUT"
|
||||
|
||||
- name: Assemble distribution zip
|
||||
id: zip
|
||||
@@ -333,63 +195,69 @@ jobs:
|
||||
set -e
|
||||
name="archie-core-archied-v${{ steps.version.outputs.version }}-linux-amd64"
|
||||
mkdir -p "$name"
|
||||
cp dist/archied dist/archie-gateway dist/archie-state-store dist/archie-ui dist/archie-messaging dist/archie-playbooks "$name/"
|
||||
cp deployments/INSTRUCTIONS.md CHANGELOG.md "$name/"
|
||||
# README.md doesn't exist yet in this repo; include it once it does
|
||||
# rather than fail the release on its absence.
|
||||
for cmd in $(jq -r '.required_topology.units[], .required_topology.binaries[]?' release.json); do
|
||||
cp "dist/$cmd" "$name/"
|
||||
done
|
||||
cp deployments/INSTRUCTIONS.md "$name/"
|
||||
digest='${{ needs.agent-image.outputs.agent_digest }}'
|
||||
test -n "$digest"
|
||||
jq --arg image "git.catlow.cloud/sam/archie-agent@$digest" '. + {agent_image: $image}' release.json > "$name/release.json"
|
||||
[ -f README.md ] && cp README.md "$name/"
|
||||
zip -r "$name.zip" "$name"
|
||||
echo "name=$name" >> "$GITHUB_OUTPUT"
|
||||
|
||||
- name: Upload distribution zip
|
||||
uses: actions/upload-artifact@v4
|
||||
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
|
||||
with:
|
||||
name: ${{ steps.zip.outputs.name }}
|
||||
path: ${{ steps.zip.outputs.name }}.zip
|
||||
retention-days: 90
|
||||
|
||||
# A Release is what an operator can actually download from; the
|
||||
# artifact above is reachable only from the run's page, behind an
|
||||
# Actions login, and expires after 90 days. Until this step existed the
|
||||
# zip was produced and then stranded -- the only Release on this repo
|
||||
# (archied/v1.22.0) was created by hand and carries no asset at all.
|
||||
#
|
||||
# Attached to the *archied* tag because the zip is named and versioned
|
||||
# for archied, and `--follow-tags` pushes both tags at one commit.
|
||||
# --generate-notes is deliberately not used: the changelog section is
|
||||
# the release's own reviewed prose, and the tag/changelog gate above
|
||||
# already guarantees it describes this version.
|
||||
- name: Publish GitHub Release with the distribution zip
|
||||
- name: Log in to the Gitea registry
|
||||
run: echo "${{ secrets.DEPLOY_TOKEN }}" | docker login git.catlow.cloud -u "${{ github.actor }}" --password-stdin
|
||||
|
||||
- name: Publish the signed release
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
ARCHIE_RELEASE_SEED: ${{ secrets.RELEASE_SIGNING_KEY }}
|
||||
run: |
|
||||
set -e
|
||||
tag="archied/v${{ steps.version.outputs.version }}"
|
||||
version="${{ steps.version.outputs.version }}"
|
||||
# The release body is this version's changelog section, not the whole
|
||||
# file: from its "## [x.y.z]" heading to the next "## [" heading.
|
||||
# Extracting rather than inlining keeps the changelog the single
|
||||
# source of truth, and the tag/changelog gate above has already
|
||||
# proven that section exists.
|
||||
prerelease=false
|
||||
case "$version" in *-*) prerelease=true ;; esac
|
||||
./dist/archied release publish -source git.catlow.cloud/sam/archie \
|
||||
-version "$version" -prerelease="$prerelease" \
|
||||
-zip "${{ steps.zip.outputs.name }}.zip" \
|
||||
-agent-image "git.catlow.cloud/sam/archie-agent@${{ needs.agent-image.outputs.agent_digest }}" \
|
||||
-changelog "https://git.catlow.cloud/sam/archie/releases/tag/v$version"
|
||||
|
||||
- name: Publish the Gitea release notes
|
||||
env:
|
||||
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
|
||||
run: |
|
||||
set -e
|
||||
tag="v${{ steps.version.outputs.version }}"
|
||||
version="${{ steps.version.outputs.version }}"
|
||||
prerelease=false
|
||||
case "$version" in *-*) prerelease=true ;; esac
|
||||
notes="$(mktemp)"
|
||||
awk -v hdr="## [$version]" '
|
||||
index($0, hdr) == 1 { printing = 1 }
|
||||
printing && /^## \[/ && index($0, hdr) != 1 { exit }
|
||||
printing { print }
|
||||
' CHANGELOG.md > "$notes"
|
||||
if ! [ -s "$notes" ]; then
|
||||
echo "no [$version] section extracted from CHANGELOG.md" >&2
|
||||
exit 1
|
||||
fi
|
||||
# Idempotent: --clobber replaces the asset and leaves the notes
|
||||
# alone, so a re-run of this job (a retried or superseded deploy)
|
||||
# cannot fail on an existing Release or duplicate the zip.
|
||||
if gh release view "$tag" >/dev/null 2>&1; then
|
||||
gh release upload "$tag" "${{ steps.zip.outputs.name }}.zip" --clobber
|
||||
else
|
||||
gh release create "$tag" \
|
||||
--title "archied v$version" \
|
||||
--notes-file "$notes" \
|
||||
"${{ steps.zip.outputs.name }}.zip"
|
||||
fi
|
||||
echo "published $tag with ${{ steps.zip.outputs.name }}.zip"
|
||||
previous="$(git describe --tags --abbrev=0 --match 'v*' "$tag^" 2>/dev/null || true)"
|
||||
git log --no-merges --format='- %s' ${previous:+"$previous.."}"$tag" > "$notes"
|
||||
api="https://git.catlow.cloud/api/v1"
|
||||
repo="sam/archie"
|
||||
auth="Authorization: token $DEPLOY_TOKEN"
|
||||
curl -sf -X DELETE -H "$auth" "$api/repos/$repo/releases/tags/$tag" >/dev/null || true
|
||||
curl -sf -X POST -H "$auth" -H "Content-Type: application/json" \
|
||||
-d "$(jq -n --arg tag "$tag" --arg name "Archie v$version" --arg body "$(cat "$notes")" \
|
||||
--argjson prerelease "$prerelease" \
|
||||
'{tag_name: $tag, name: $name, body: $body, draft: false, prerelease: $prerelease}')" \
|
||||
"$api/repos/$repo/releases" >/dev/null
|
||||
echo "published release notes for $tag"
|
||||
|
||||
- name: Link the packages to this repository
|
||||
env:
|
||||
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
|
||||
run: |
|
||||
for name in archied archie-agent archie; do
|
||||
curl -sS -o /dev/null -X POST -H "Authorization: token $DEPLOY_TOKEN" \
|
||||
"https://git.catlow.cloud/api/v1/packages/sam/container/$name/-/link/archie" || true
|
||||
done
|
||||
@@ -0,0 +1,43 @@
|
||||
name: promote
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
version:
|
||||
description: "published release to move stable to, such as 1.63.0"
|
||||
required: true
|
||||
type: string
|
||||
|
||||
concurrency:
|
||||
group: promote
|
||||
cancel-in-progress: true
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
packages: write
|
||||
|
||||
jobs:
|
||||
promote:
|
||||
runs-on: self-hosted
|
||||
steps:
|
||||
- name: Log in to the Gitea registry
|
||||
run: echo "${{ secrets.DEPLOY_TOKEN }}" | docker login git.catlow.cloud -u "${{ github.actor }}" --password-stdin
|
||||
|
||||
- name: Fetch the release's archied
|
||||
env:
|
||||
VERSION: ${{ inputs.version }}
|
||||
run: |
|
||||
set -e
|
||||
image="git.catlow.cloud/sam/archied:v$VERSION"
|
||||
docker pull -q "$image"
|
||||
container="$(docker create "$image")"
|
||||
docker cp "$container:/usr/local/bin/archied" "$RUNNER_TEMP/archied"
|
||||
docker rm "$container" >/dev/null
|
||||
|
||||
- name: Promote to stable
|
||||
env:
|
||||
VERSION: ${{ inputs.version }}
|
||||
run: |
|
||||
"$RUNNER_TEMP/archied" release promote \
|
||||
-version "$VERSION" \
|
||||
-latest git.catlow.cloud/sam/archied,git.catlow.cloud/sam/archie-agent
|
||||
@@ -2,8 +2,6 @@ name: Quality
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
branches: [main]
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
@@ -14,47 +12,41 @@ concurrency:
|
||||
|
||||
jobs:
|
||||
check:
|
||||
runs-on: ubuntu-latest
|
||||
runs-on: archie-quality
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- uses: actions/setup-go@v5
|
||||
- name: Verify unprivileged user namespaces
|
||||
run: unshare --user --map-root-user --net true
|
||||
|
||||
- uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff
|
||||
with:
|
||||
go-version-file: go.mod
|
||||
|
||||
- uses: actions/setup-node@v4
|
||||
- uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1
|
||||
with:
|
||||
package_json_file: ui/package.json
|
||||
|
||||
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
|
||||
with:
|
||||
node-version: "24"
|
||||
cache: npm
|
||||
cache-dependency-path: ui/package-lock.json
|
||||
|
||||
- name: Install quality tools
|
||||
run: |
|
||||
go install github.com/go-task/task/v3/cmd/task@v3.48.0
|
||||
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.2
|
||||
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@$(cat .golangci-version)
|
||||
go install mvdan.cc/gofumpt@v0.11.0
|
||||
bash tools/proto.sh install
|
||||
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y --no-install-recommends ripgrep
|
||||
sudo install -d /usr/share/postgresql-common/pgdg
|
||||
sudo curl --fail --silent --show-error --location \
|
||||
https://www.postgresql.org/media/keys/ACCC4CF8.asc \
|
||||
--output /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc
|
||||
|
||||
. /etc/os-release
|
||||
echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt ${VERSION_CODENAME}-pgdg main" \
|
||||
| sudo tee /etc/apt/sources.list.d/pgdg.list
|
||||
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y --no-install-recommends postgresql-client-18
|
||||
|
||||
echo "/usr/lib/postgresql/18/bin" >> $GITHUB_PATH
|
||||
|
||||
pg_dump --version
|
||||
pg_restore --version
|
||||
- uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830
|
||||
with:
|
||||
path: ~/.cache/golangci-lint
|
||||
key: golangci-lint-${{ hashFiles('.golangci-version', '.golangci.yml', 'go.sum') }}-${{ github.sha }}
|
||||
restore-keys: |
|
||||
golangci-lint-${{ hashFiles('.golangci-version', '.golangci.yml', 'go.sum') }}-
|
||||
golangci-lint-
|
||||
|
||||
- name: Ensure contract baseline ref
|
||||
run: |
|
||||
@@ -64,5 +56,5 @@ jobs:
|
||||
|
||||
- name: Run definitive gate
|
||||
run: |
|
||||
task check
|
||||
task --concurrency 1 check
|
||||
git diff --exit-code
|
||||
@@ -0,0 +1,55 @@
|
||||
name: release
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
release:
|
||||
description: "major, minor, patch, or an exact version such as 1.57.0"
|
||||
required: true
|
||||
default: minor
|
||||
|
||||
concurrency:
|
||||
group: release
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
cut:
|
||||
runs-on: self-hosted
|
||||
steps:
|
||||
- name: Check DEPLOY_TOKEN is configured
|
||||
env:
|
||||
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
|
||||
run: |
|
||||
if [ -z "$DEPLOY_TOKEN" ]; then
|
||||
echo "::error::DEPLOY_TOKEN is not set for this repository, so the release cannot push its tag. Set the secret here, or dispatch the release from the Gitea primary."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
- name: Checkout
|
||||
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
|
||||
with:
|
||||
ref: main
|
||||
fetch-depth: 0
|
||||
token: ${{ secrets.DEPLOY_TOKEN }}
|
||||
|
||||
- name: Set up Go
|
||||
uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff
|
||||
with:
|
||||
go-version-file: go.mod
|
||||
cache: false
|
||||
|
||||
- name: Install Task
|
||||
run: go install github.com/go-task/task/v3/cmd/task@v3.48.0
|
||||
|
||||
- name: Cut the release
|
||||
env:
|
||||
RELEASE: ${{ inputs.release }}
|
||||
run: |
|
||||
git config user.name "Sam Catlow"
|
||||
git config user.email "sam@catlow.tech"
|
||||
task release RELEASE="$RELEASE"
|
||||
|
||||
- name: Push the release
|
||||
run: git push origin "$(git describe --exact-match --match 'v*' HEAD)"
|
||||
+8
-11
@@ -1,6 +1,7 @@
|
||||
/archied
|
||||
/archie-agent
|
||||
/bin/
|
||||
/dist/
|
||||
.task/
|
||||
*.db
|
||||
.references/
|
||||
@@ -25,21 +26,14 @@ config.production.toml
|
||||
/ui/node_modules/
|
||||
/ui/.vite/
|
||||
/ui/*.tsbuildinfo
|
||||
# ui/dist IS committed: the Go build must not need a Node toolchain.
|
||||
/ui/dist/
|
||||
|
||||
# air live-reload
|
||||
/.air/
|
||||
/tmp/
|
||||
|
||||
# Beads / Dolt files (added by bd init)
|
||||
.dolt/
|
||||
.beads-credential-key
|
||||
.beads/proxieddb/
|
||||
*.gate.lock*
|
||||
.impeccable/
|
||||
.serena/
|
||||
.beads/issues.jsonl
|
||||
.beads/interactions.jsonl
|
||||
.mcp.json
|
||||
|
||||
# gh CLI state (~/.local/state/gh) mistakenly created inside the tree
|
||||
@@ -47,10 +41,13 @@ config.production.toml
|
||||
__pycache__/
|
||||
*.pyc
|
||||
|
||||
# Local site build output.
|
||||
/site/
|
||||
|
||||
# Locally-trusted development certificates (mkcert and friends). The private
|
||||
# key is generated per machine and must never be committed.
|
||||
*.pem
|
||||
*.key
|
||||
|
||||
# Local symlink to the archipelago marketplace repo
|
||||
/archipelago
|
||||
.agents-run/
|
||||
/.pnpm-store/
|
||||
deployments/archie/.build/
|
||||
@@ -0,0 +1 @@
|
||||
v2.14.0
|
||||
+77
-7
@@ -29,6 +29,7 @@ linters:
|
||||
- nestif
|
||||
|
||||
# Architecture
|
||||
- depguard
|
||||
- importas
|
||||
- interfacebloat
|
||||
|
||||
@@ -41,6 +42,7 @@ linters:
|
||||
- errorlint
|
||||
- fatcontext
|
||||
- forcetypeassert
|
||||
- gosec
|
||||
- makezero
|
||||
- nilerr
|
||||
- nilnesserr
|
||||
@@ -61,6 +63,74 @@ linters:
|
||||
- usetesting
|
||||
|
||||
settings:
|
||||
# Each service links only its own composition: services reach each other
|
||||
# through their gRPC contracts, never another service's packages.
|
||||
depguard:
|
||||
rules:
|
||||
gateway-service:
|
||||
files: ["**/internal/app/archiegateway/**"]
|
||||
deny:
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/daemon", desc: "the daemon is another service"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/webui", desc: "the web UI is another service"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/app/archied", desc: "the daemon is another service"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/app/statestore", desc: "reach the State Store through its contract"}
|
||||
state-store-service:
|
||||
files: ["**/internal/app/statestore/**"]
|
||||
deny:
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/daemon", desc: "the daemon is another service"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/webui", desc: "the web UI is another service"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/gateway", desc: "the Gateway is another service"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/app/archied", desc: "the daemon is another service"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/app/archiegateway", desc: "the Gateway is another service"}
|
||||
- {pkg: "github.com/nats-io", desc: "the State Store serves gRPC only"}
|
||||
dashboard-service:
|
||||
files: ["**/internal/webui/**", "**/internal/app/archieui/**", "**/cmd/archie-ui/**"]
|
||||
deny:
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/container", desc: "only the daemon owns containers"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/agentexec", desc: "only the daemon owns containers"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/app/archied", desc: "the daemon is another service"}
|
||||
messaging-service:
|
||||
files: ["**/internal/app/archiemessaging/**", "**/cmd/archie-messaging/**"]
|
||||
deny:
|
||||
- {pkg: "github.com/jackc/pgx", desc: "reach the State Store through its contract"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/infrastructure/postgres", desc: "reach the State Store through its contract"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/infrastructure/controlplanestore", desc: "reach the State Store through its contract"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/domain/workflow", desc: "the workflow engine is the daemon's"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/agentexec", desc: "agent execution is the daemon's"}
|
||||
# The single binary replaces the services slice by slice. It never
|
||||
# imports their packages, so each old path can be deleted outright.
|
||||
single-binary:
|
||||
files: ["**/cmd/archie/**", "**/internal/app/archie/**", "**/internal/platform/**", "**/modules/**"]
|
||||
deny:
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/app/archied", desc: "an old service; move what you need into a module"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/app/statestore", desc: "an old service; move what you need into a module"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/app/archiegateway", desc: "an old service; move what you need into a module"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/app/archiemessaging", desc: "an old service; move what you need into a module"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/app/archieui", desc: "an old service; move what you need into a module"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/app/servicekit", desc: "old service plumbing"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/daemon", desc: "old service code; move what you need into a module"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/gateway", desc: "old service code; move what you need into a module"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/webui", desc: "old service code; move what you need into a module"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/domain", desc: "old domain code; move what you need into a module"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/infrastructure", desc: "old infrastructure; move what you need into a module"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/contracts/state", desc: "an internal service contract being deleted"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/contracts/gateway", desc: "an internal service contract being deleted"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/contracts/daemon", desc: "an internal service contract being deleted"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/contracts/controlplane", desc: "an internal service contract being deleted"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/contracts/messaging", desc: "an internal service contract being deleted"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/contracts/logging", desc: "an internal service contract being deleted"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/contracts/forge", desc: "an internal service contract being deleted"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/contracts/channel", desc: "an internal service contract being deleted"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/config", desc: "the single binary has its own bootstrap config"}
|
||||
- {pkg: "github.com/nats-io", desc: "the single binary has no message bus"}
|
||||
shared:
|
||||
files: ["**/internal/app/servicekit/**"]
|
||||
deny:
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/daemon", desc: "shared code must not pull in a service"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/webui", desc: "shared code must not pull in a service"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/app/archied", desc: "shared code must not pull in a service"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/app/archiegateway", desc: "shared code must not pull in a service"}
|
||||
- {pkg: "github.com/samcharles93/archie-core/internal/app/statestore", desc: "shared code must not pull in a service"}
|
||||
cyclop:
|
||||
max-complexity: 15
|
||||
dupl:
|
||||
@@ -85,12 +155,19 @@ linters:
|
||||
- HACK
|
||||
- BUG
|
||||
|
||||
gosec:
|
||||
excludes:
|
||||
- G104 # errcheck covers unchecked errors
|
||||
- G115 # integer conversions are bounded where they occur
|
||||
- G204 # running commands is what the tools and workflow steps do
|
||||
- G304 # file paths come from configuration and confined worktrees
|
||||
interfacebloat:
|
||||
max: 8
|
||||
|
||||
sloglint:
|
||||
no-mixed-args: true
|
||||
key-naming-case: snake
|
||||
context: scope
|
||||
|
||||
exclusions:
|
||||
generated: lax
|
||||
@@ -103,7 +180,6 @@ linters:
|
||||
- ui/node_modules
|
||||
presets:
|
||||
- comments
|
||||
- std-error-handling
|
||||
- common-false-positives
|
||||
- legacy
|
||||
rules:
|
||||
@@ -142,12 +218,6 @@ formatters:
|
||||
custom-order: true
|
||||
exclusions:
|
||||
generated: strict
|
||||
# These Yaegi programs sit behind //go:build ignore, so a formatter cannot
|
||||
# type-check them: rewriting their imports deletes the genuinely used
|
||||
# internal/secret import and the interpreter can no longer load them.
|
||||
# Excluded from every formatter so adding one cannot reintroduce that.
|
||||
paths:
|
||||
- ^examples/secret-engines/(age|sops|vault)\.go$
|
||||
|
||||
issues:
|
||||
# 0 = report everything. The defaults (50 per linter, 3 per message)
|
||||
|
||||
@@ -1,4 +0,0 @@
|
||||
# Generated output: only its generator writes it, and the gate byte-checks it.
|
||||
docs/data/generated/
|
||||
internal/contracts/
|
||||
ui/dist/
|
||||
-2314
File diff suppressed because it is too large.
Load diff
@@ -1,417 +1,263 @@
|
||||
# AGENTS.md
|
||||
|
||||
Guidance for any coding agent working in this repository.
|
||||
|
||||
Keep every rule here harness-agnostic: name the required behaviour, not the tool
|
||||
that provides it (e.g. "spawn a fresh reviewer that did not write the code", not
|
||||
a specific sub-command).
|
||||
|
||||
## Code Quality & Refactoring Standards
|
||||
|
||||
- **Zero Patch Stacking:** Never apply more than two sequential fixes to the
|
||||
same logic block. If a solution fails twice, scrap the block and rewrite it
|
||||
cleanly.
|
||||
- **Root-Cause Fixes:** Fix invalid state at the producer, not via defensive
|
||||
checks at the consumer.
|
||||
- **Architectural Simplicity:** Prefer a complete 20-line rewrite over a 5-line
|
||||
band-aid that adds conditional complexity or obscures intent.
|
||||
- **Revert on Flail:** If an implementation becomes convoluted to satisfy edge
|
||||
cases, discard the approach and select a simpler design.
|
||||
Rules for any agent working in this repository. Short on purpose: every rule
|
||||
here changes a decision. If a rule stops changing decisions, delete it.
|
||||
|
||||
## What this is
|
||||
|
||||
**archied** is a resident daemon that polls a forge (GitHub, Gitea) for issues
|
||||
assigned/labelled to it, works each one in an isolated git worktree through a
|
||||
routed workflow (bootstrap / implement / TDD / feasibility), and opens pull
|
||||
requests for human review.
|
||||
**archie-core** is event-driven agentic automation. An event (an alert, a
|
||||
webhook, a schedule, a chat message, an issue) is matched to a workflow, the
|
||||
workflow runs an agent whose every action is judged before it runs, and the
|
||||
result lands somewhere for review or action. A repository is an optional input
|
||||
to a workflow, not the point of the product. A forge is one of many inputs or
|
||||
outputs; core code never assumes one.
|
||||
|
||||
Architecture of record lives in `docs/architecture/` -- `organisation.md` for
|
||||
the package map, `agent-system.md` for the workflow-execution lifecycle and its
|
||||
invariants, `plugins-and-extensions.md` for engine families. Read it before
|
||||
making non-trivial changes. Key invariants: env-enforced gates, model never runs
|
||||
git, and agent execution functions as a strict data boundary. Before adding a new
|
||||
plugin engine, satisfy
|
||||
`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`.
|
||||
## Layout
|
||||
|
||||
Before changing an area (frontend UI, agent, workflows, daemon, State Store,
|
||||
control plane), read its page in `docs/development/`: it names every layer the
|
||||
change must reach. This is not optional colour reading -- archie-core is built
|
||||
as an extensible, customisable surface, not a fixed product, so a change that
|
||||
looks complete inside one package routinely is not: a new setting that never
|
||||
reaches the control-plane schema descriptor and dashboard parses but never
|
||||
renders, is never editable, and never live-applies, exactly like a config
|
||||
field with no consumer. The dev-docs page for the area is where that
|
||||
cross-layer reach is written down; read it before starting, not after
|
||||
something downstream turns out silently unwired. This applies whether the
|
||||
work is yours directly or handed to a subagent or crew worker -- carry the
|
||||
relevant docs/development page into their prompt, the same way a bead ID is
|
||||
carried; "figure out what else needs updating" left implicit is exactly the
|
||||
gap this note exists to close.
|
||||
Main is becoming one binary, `archie`. The design is ARCHITECTURE.md in the
|
||||
private sam/archie-product repo, and the work is epic #1977. New work goes
|
||||
there:
|
||||
|
||||
## Scope Discipline
|
||||
- `cmd/archie` parses flags and calls `internal/app/archie`, the composition
|
||||
root.
|
||||
- Each module is `modules/<name>/`: an API package and an `internal/` directory
|
||||
nothing outside the module can import. Modules reach each other only through
|
||||
API packages, own their schema and tables, and keep no state only in memory.
|
||||
- `internal/platform/` holds the few leaf packages every module may use.
|
||||
- The new code never imports the old services' packages (depguard enforces it).
|
||||
Old code moves: `git mv` it into the module that owns it, then adapt it.
|
||||
While an old service still imports it, copy it instead, name the source
|
||||
path in the commit, and delete the old copy with its service.
|
||||
MIGRATION.md in sam/archie-product gives every old package a destination and
|
||||
a verdict. Writing a replacement from scratch, or deleting an old package,
|
||||
needs the maintainer's verdict on its row. Before building anything an old
|
||||
package already does, read that package and carry its behaviour.
|
||||
|
||||
`docs/architecture/` is authoritative for settled design.
|
||||
`docs/architecture/migration-decisions.md` is the open decision register for the
|
||||
domain migration.
|
||||
### The services being replaced
|
||||
|
||||
- **Settled design exists** → Implement it immediately with a diff. Do not
|
||||
produce design prose. If a small detail is missing, ask the maintainer
|
||||
directly.
|
||||
- **No settled design exists (or open in `migration-decisions.md`)** → Write a
|
||||
decisive, 1-page design doc before coding. Land new capabilities in
|
||||
`docs/prds/` and migration questions in
|
||||
`docs/architecture/migration-decisions.md`. Promote to `docs/architecture/`
|
||||
only after implementation lands.
|
||||
- **Strictly Prohibited:** Ownership ledgers, field-level inventories,
|
||||
current-state traces, parity matrices for their own sake, and
|
||||
planning/refactor tracking issues.
|
||||
- **Solo Project Context:** Prefer the smallest workable change over extensive
|
||||
defensive scaffolding.
|
||||
- **Verify handed-over input before acting on it.** An export, transcript, or
|
||||
artifact that is empty, missing, or truncated is a blocking fact: report it
|
||||
before starting work that assumes its contents. Never reconstruct the intent
|
||||
from the working tree instead.
|
||||
- **PRD writing:** Read and follow `docs/prds/RULES.md` before creating or
|
||||
editing a PRD.
|
||||
The six services below are deleted slice by slice as the binary replaces them,
|
||||
each only once MIGRATION.md has a verdict for every package it holds. Don't
|
||||
add features to them; fix them only when a bug blocks work.
|
||||
|
||||
## Deployment Model
|
||||
Each service is a gRPC contract in `proto/<service>/v1`, generated into
|
||||
`internal/contracts/<service>/v1`, and one binary in `cmd/` that parses flags
|
||||
and calls its composition root in `internal/app/<service>`.
|
||||
|
||||
- **Systemd is optional:** `deployments/` holds supported profiles
|
||||
(`single-forge-github.toml`, `multi-forge-github-gitea.toml`,
|
||||
`local-ollama-standalone.toml`, `docker-nats-stack.toml`,
|
||||
`systemd-user-service.md`). Never assume a systemd unit exists.
|
||||
- **Chat filesystem confinement:** Builtin tools default to workspace jail via
|
||||
`SetPathConfinement(!unrestricted)`. Unrestricted access requires
|
||||
`[chat] unrestricted_filesystem = true`.
|
||||
- **NATS endpoint immutability:** The daemon passes agent containers its startup
|
||||
connection URL (`d.ConnectedNATS.URL`). Containers and daemon must resolve
|
||||
this address. Embedded mode binds to the Docker bridge gateway. A SIGHUP
|
||||
reload of `nats.url` logs an error requiring restart to prevent split-brain
|
||||
delivery.
|
||||
- **Container pull policy:** `containers.pull_policy` must be `"missing"`
|
||||
(default) or `"always"`. Private registries need `containers.registry_auth`
|
||||
(a `SecretRef` resolving to a `registry.AuthConfig` JSON document); without it
|
||||
the pull is anonymous and a private registry answers 401. Refresh explicitly
|
||||
via `docker compose pull agent`.
|
||||
- **Docker Compose:** `docker-compose.yml` carries optional external NATS and
|
||||
the `agent` build stanza. The agent uses a `build` profile so `up -d nats`
|
||||
never starts it as a persistent service.
|
||||
- **Config path:** Runtime configuration lives at
|
||||
`${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`. Nothing in the working
|
||||
tree is load-bearing at runtime.
|
||||
| Binary | Serves | Dials |
|
||||
| --- | --- | --- |
|
||||
| `archie-state-store` | State Store and Control Plane contracts; owns the task and control-plane tables | PostgreSQL |
|
||||
| `archie-gateway` | Chat contract; owns the conversation tables | State Store, PostgreSQL |
|
||||
| `archied` | Daemon contract; scheduling, workflow runs, task containers | State Store, Gateway, Messaging, NATS |
|
||||
| `archie-messaging` | Messaging contract; external channel frontends | State Store, Gateway |
|
||||
| `archie-ui` | Dashboard HTTP API (`internal/webui`) and the embedded SPA | State Store, Gateway, Daemon, Messaging |
|
||||
| `archie-agent` | The worker inside each task container | NATS |
|
||||
|
||||
## Release Process
|
||||
Forge, channel and secret-engine contracts are extension boundaries, not
|
||||
services: a core binary starts the extension as a plugin process and dials it.
|
||||
`archied` also runs the State Store's backup and restore during a host update.
|
||||
|
||||
See `RELEASING.md`. Most sessions touch only `archied`, making releases
|
||||
gateway-only (`RUNTIME=skip`) by default. Skip untouched components
|
||||
automatically and note it in the handoff.
|
||||
`internal/domain` holds behaviour and interfaces; `internal/infrastructure`
|
||||
implements them. Every instruction sent to a model is a file in
|
||||
`internal/prompts`, read through that package; never inline a prompt in code.
|
||||
Dashboard work follows `ui/CLAUDE.md`. Workflow YAML and its step vocabulary
|
||||
are in `WORKFLOWS.md`; the server catalogue is authoritative.
|
||||
|
||||
## Build & Test
|
||||
## Authority
|
||||
|
||||
Commands are defined in `Taskfile.yml` (requires Go 1.27.0,
|
||||
[Task](https://taskfile.dev), `gofumpt`, `golangci-lint`, Node/npm, and a
|
||||
running Docker daemon: Postgres tests start `postgres:18` through
|
||||
testcontainers via `internal/infrastructure/postgres/pgtest`).
|
||||
`golangci-lint` is the single writer for ordinary Go formatting; standalone
|
||||
`gofumpt` formats generated protobuf contracts only.
|
||||
When sources disagree, the higher one wins:
|
||||
|
||||
1. The maintainer's instruction in this session.
|
||||
2. This file.
|
||||
3. The code as it is in the tree.
|
||||
4. Gitea issues (`tea issues view <n>`): the plan for a piece of work.
|
||||
5. Everything else (memories, comments, old docs) is a hint. Verify it against
|
||||
the code before acting on it.
|
||||
|
||||
## Working with the maintainer
|
||||
|
||||
- **A clear direction is the go-ahead.** Do it in the same turn. Do not restate
|
||||
the plan, offer options, or ask "shall I proceed?". Stop only for destructive
|
||||
or outward-facing actions (deleting data, pushing, touching a live host).
|
||||
- **Push back when it matters.** If a request competes with something clearly
|
||||
more urgent (a bug that loses work, a failure that shows nothing, a security
|
||||
gap, a broken setup path), or looks like the wrong call, say so once in a
|
||||
sentence or two and suggest whether it belongs in the backlog. Then do what
|
||||
was asked: don't repeat the point or hold work back on your own judgement.
|
||||
- **Post outside the repo only when told.** Chat, tickets and any external
|
||||
service get a message only on the maintainer's instruction.
|
||||
- **Report, don't narrate.** Final replies say what changed, what was verified,
|
||||
and anything blocked, in a few lines. No preamble, no recap of the request, no
|
||||
closing offers of more help. Leave out what the maintainer can see or infer:
|
||||
a clean tree, unpushed commits, a passing gate (commits imply it), and steps
|
||||
skipped that the task never asked for. Name a skipped step only when the
|
||||
task required it.
|
||||
|
||||
## How to decide
|
||||
|
||||
- **Broken comes first.** A bug that blocks or loses work goes ahead of new
|
||||
features. Fix the cause. When that's a bigger job, unblock with a small change
|
||||
first and file the proper fix rather than stopping there.
|
||||
- **Cheapest option first.** Before building, consider the smallest change that
|
||||
solves the problem, including changing configuration or deleting something.
|
||||
A new mechanism (RPC, process, binary, abstraction, config field, tool) is
|
||||
fine when it's the right design; say why the smaller option wasn't enough.
|
||||
- **Delete before adding.** Unused code, dead paths, fallbacks nobody takes and
|
||||
features nobody runs get removed, not maintained. Solo project, single user:
|
||||
breaking changes need no compatibility shims.
|
||||
- **Finish before starting.** Prefer completing a half-built feature end to end
|
||||
over starting a new one.
|
||||
- **Modules own their API and tables.** A module reaches another only through
|
||||
its API package, never its tables or `internal/`. The only real process
|
||||
boundaries are extensions and the runner. A new command is a subcommand of
|
||||
`archie`.
|
||||
- **No compensating tools.** Do not write a linter, checker or generator to
|
||||
enforce something a simpler design would make unnecessary. Fix the design.
|
||||
- **A setting must work end to end.** A config field that parses but has no
|
||||
consumer is a bug. Settings are edited through the control plane (API and
|
||||
dashboard), never by requiring a server login.
|
||||
- **Ask only for real decisions.** Product direction and trade-offs the
|
||||
maintainer owns are questions. Everything with a conventional answer is not:
|
||||
decide, do it, say what you chose.
|
||||
|
||||
## Code
|
||||
|
||||
- Idiomatic Go. Small functions, explicit errors, no package-level mutable
|
||||
state, no god objects. Each feature wires itself; a composition root only
|
||||
calls those constructors in order.
|
||||
- Dependencies point inward: `cmd → app → {domain, infrastructure}`,
|
||||
`infrastructure` implements `domain` interfaces, `domain` imports neither.
|
||||
`cmd/` parses flags and calls `app`, nothing else.
|
||||
- Fix invalid state where it is produced, not with checks where it is consumed.
|
||||
- Log through the service's injected `*slog.Logger` with the `...Context`
|
||||
methods, so lines carry the OpenTelemetry trace id. Never the global `slog`.
|
||||
- If a fix fails twice, throw the block away and rewrite it simply.
|
||||
- Comments say why, briefly. No migration history, phase names or issue
|
||||
narration in code.
|
||||
- Generated files (protobuf, sqlc) are regenerated and committed
|
||||
with the change that caused them, never hand-edited.
|
||||
|
||||
## Tests
|
||||
|
||||
The default for a change is no new test. Write one only when:
|
||||
|
||||
- something actually broke: write the test that reproduces it, see it fail on
|
||||
the assertion, then fix; or
|
||||
- the change alters one of these seams: State Store SQL semantics (transition
|
||||
guards, idempotent dispatch, cancellation), security boundaries (HMAC, grants,
|
||||
path confinement, egress, secrets), the workflow step contract, or the
|
||||
import-boundary rules.
|
||||
|
||||
A test that exists must catch a real regression, survive refactoring, run fast,
|
||||
and be cheap to keep. Never test wiring, constants, defaults, struct shapes,
|
||||
fakes, or call order. Prefer making an invalid state unrepresentable to testing
|
||||
that it is rejected.
|
||||
|
||||
How to write one:
|
||||
|
||||
- **Prove it.** Run the new test against the code before the fix and see it
|
||||
fail. A test that passes either way proves nothing: delete it. When a bug
|
||||
can't be reproduced deterministically (a race, say), fix it with an API that
|
||||
rules it out and don't add a test.
|
||||
- **One table per behaviour.** Extend the table instead of adding a second test.
|
||||
Name the test after the behaviour, and say in its comment what regression it
|
||||
guards.
|
||||
- **Same gate as production.** Tests pass golangci-lint, gosec included, with no
|
||||
exclusions for test files. Fix what the linter finds. A fixture that has to
|
||||
look like a secret (a key the redaction must catch, a URL with a password the
|
||||
parser must reject) uses a plainly fake value and a `//nolint:gosec` saying
|
||||
what it tests.
|
||||
- **Isolated.** Use `t.TempDir()` and `t.Setenv`, never host state. A test that
|
||||
commits with git sets `GIT_CONFIG_GLOBAL` to `os.DevNull`. No test opens a
|
||||
real database or needs Docker: test SQL semantics at the interceptor or domain
|
||||
level with fakes. Files are written `0o600`, or `0o700` for a script.
|
||||
- **Shared setup in helpers.** When several tests repeat the same setup, put it
|
||||
in a helper in a `_test.go` file, never in production code.
|
||||
|
||||
## Invariants
|
||||
|
||||
These protect users. Do not weaken them without the maintainer's say-so.
|
||||
|
||||
- A crash loses no accepted work, and a restart resumes every run. Work is
|
||||
acknowledged only once it is durable. A missing dependency is reported
|
||||
unhealthy and retried, never a reason to exit.
|
||||
- The model never runs git. Commits and pushes go through the daemon.
|
||||
- The daemon's own credentials never enter an agent container. Containers get
|
||||
task-scoped grants that are revoked when the task ends.
|
||||
- Webhook HMAC is verified before the payload is parsed.
|
||||
- Task briefs go in `<worktree>/.git/task.json`, never the worktree root.
|
||||
- NATS: task and RPC replies use `msg.Respond`; flush after registering a
|
||||
responder; `ARCHIE_TASKS` is a work queue, so never bind overlapping
|
||||
consumers.
|
||||
- `ai-sdk` `FullStream` must be drained completely.
|
||||
|
||||
## Build and gate
|
||||
|
||||
```bash
|
||||
task build # build archied and archie-agent binaries into bin/
|
||||
task test # go test -short ./... (cached; task test:full runs everything uncached)
|
||||
task test:ui # dashboard node tests (DOM-building primitives)
|
||||
task ui # build dashboard into ui/dist (LAW asset)
|
||||
task fmt # go fix ./... && golangci-lint fmt
|
||||
task vet # go vet ./...
|
||||
task lint # golangci-lint run ./...
|
||||
task check # fmt + proto:lint + proto:check + docs:check + vet + lint + build + test + test:tools + test:ui (The Definitive Gate)
|
||||
task dev # archied live-reload + Vite HMR together on :5173
|
||||
task build # binaries into bin/
|
||||
task test # go test -short ./...
|
||||
task ui # dashboard into ui/dist
|
||||
task check # the gate
|
||||
|
||||
go test -short ./internal/domain/workflow -run TestName # one test
|
||||
task dev # every service + Vite at http://localhost:5173, from deployments/dev.toml
|
||||
task e2e:up # seeded local stack; task e2e:check -- all runs the browser checks
|
||||
```
|
||||
|
||||
Single package/test runs:
|
||||
`task proto:generate`, `task db:generate` and `task openapi:generate` write
|
||||
the committed generated output for `proto/`, `internal/infrastructure/postgres/`
|
||||
and `api/openapi.yaml`; `task check` runs their check variants and rejects stale
|
||||
output. The e2e stack is not part of the gate.
|
||||
|
||||
Requires Go 1.27, Task, golangci-lint, Node, pnpm and Docker. Adopt `task fmt` and
|
||||
`go fix` output as-is.
|
||||
|
||||
- `task check` gates the commit: `task check && git commit ...`. Never claim a
|
||||
gate result you did not just produce on that exact tree; if the gate could not
|
||||
run, say what you did verify.
|
||||
- Commit finished work without asking. Stage only your own paths and commit in
|
||||
the same command. Conventional Commits scoped by package, short messages. Push
|
||||
every commit as soon as it is made; a local-only commit is not acceptable.
|
||||
- Never commit binaries, build output, scratch files or `.references/`. Scratch
|
||||
goes in `/tmp`.
|
||||
- Runtime config lives at `${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`.
|
||||
Nothing in the working tree is read at runtime. Systemd is optional.
|
||||
- Releases: `RELEASING.md`.
|
||||
|
||||
## Issues (Gitea)
|
||||
|
||||
Work is tracked as issues on the primary remote, never in Markdown TODO files.
|
||||
GitHub is a read-only mirror; do not open, close or comment there.
|
||||
|
||||
```bash
|
||||
go test ./internal/domain/workflow/... -run TestName -v -count=1
|
||||
tea issues list -r sam/archie --state open --labels critical
|
||||
tea issues view 497
|
||||
tea issues edit 497 --add-labels in-progress --add-assignees sam
|
||||
tea comment 497 "what changed, and what was run"
|
||||
tea issues close 497
|
||||
```
|
||||
|
||||
## Repository Hygiene
|
||||
- An issue is the plan: what is wrong or wanted, and how you know it is done.
|
||||
Keep it to that.
|
||||
- Labels carry state: a type (`bug`, `feature`, `task`, `chore`, `epic`,
|
||||
`decision`, `discovery`), a priority (`critical`, `high`, `medium`, `low`), `in-progress`
|
||||
and `deferred`. Open/closed is the issue state, not a label.
|
||||
- An epic's children are its dependencies: link each one as it is filed (Gitea
|
||||
MCP `issue_write` `add_dependency`, the epic `blocked_by` the child), plus any
|
||||
real blocker between children. No `epic/<slug>` label; the dependencies are
|
||||
the link, and the only place the web UI shows an epic's children.
|
||||
- `tea` drops labels on `issues create` and `edit --add-labels`. Label through
|
||||
the Gitea MCP connector, by label ID: it resolves names from the first 50
|
||||
labels only.
|
||||
- Cite the issue number in commits and comments.
|
||||
- `tea issues list --labels` silently ignores an unknown name and returns every
|
||||
issue. Check the count is plausible before trusting a filtered list.
|
||||
- The API caps `limit` at 50 regardless of what you pass.
|
||||
- No host names, IPs, paths, PIDs or credentials in an issue: the text outlives
|
||||
the change that wrote it.
|
||||
- File follow-up work you find as an issue. Do not fix it in passing.
|
||||
|
||||
- **Generated assets are LAW:** Never modify, revert, or ignore generated files
|
||||
in `ui/dist/` or schema outputs. Incorporate them into relevant commits.
|
||||
- **Ignored paths:** Never commit build artifacts, binaries (`/bin/`,
|
||||
`/archied`), DB files, working screenshots, `.references/`, or
|
||||
`node_modules/`.
|
||||
- **Scratch files:** Place scratch files strictly in `/tmp` or the harness
|
||||
scratch space. Never put scratch files in the working tree
|
||||
(`worktree.CommitAll` will stage them).
|
||||
- **Conventional Commits:** Scope by package: `feat(webui): ...`,
|
||||
`fix(build): ...`, `chore(release): ...`.
|
||||
- **Commit policy:** Commit finished, gate-clean changes (`task check`
|
||||
passing) without asking. Push only when instructed.
|
||||
## Changing this file
|
||||
|
||||
## Organisation (Strict Domain-Driven Architecture)
|
||||
|
||||
`docs/architecture/organisation.md` is authoritative. Do not follow flat
|
||||
structures found in legacy packages.
|
||||
|
||||
### Layers and Ownership
|
||||
|
||||
- `internal/domain/<area>/`: Domain logic, entities, state machines, commands,
|
||||
events, and required contracts (interfaces). Never imports infrastructure or
|
||||
app.
|
||||
- `internal/infrastructure/<service>/`: Implementations of domain contracts
|
||||
(persistence, forge clients, external transports, config loading).
|
||||
- `internal/app/<application>/`: Dependency injection, wiring domain to
|
||||
infrastructure, lifecycle management, and shutdown ordering.
|
||||
- `cmd/<binary>/`: CLI flag parsing, OS signal traps, and entry point routing
|
||||
only. No domain wiring.
|
||||
|
||||
### Invariants
|
||||
|
||||
- **Dependency Flow:** `cmd → app → {domain, infrastructure}`, with
|
||||
`infrastructure → domain` implementing contracts. Downward/inward dependencies
|
||||
only.
|
||||
- **Cross-Cutting Packages:** `logging`, `events`, `eventbus`, `policy`,
|
||||
`taskstate` sit directly under `internal/`. They may be imported by any layer,
|
||||
but **must import zero internal packages**. No `shared/`, `utils/`, or
|
||||
`common/` catch-alls.
|
||||
- **File Layout:** One file per API concern (`api_tasks.go`, `api_logs.go`). A
|
||||
package owns its on-disk format end-to-end (e.g. `internal/logging` defines
|
||||
and reads its format; transport layers do not parse).
|
||||
- **Frontend:** Features live in `ui/src/<feature>/` with colocated `.js` and
|
||||
`.css`. Extract to `ui/src/base/` only on the second distinct consumer.
|
||||
|
||||
## Per-Package Invariants & Traps
|
||||
|
||||
- **Config fields (cross-cutting): a field that parses is not a field that works.**
|
||||
A knob added to a struct the extensible surface reuses _parses_ everywhere
|
||||
without taking effect anywhere, and a knob read from the wrong layer is just
|
||||
as invisible: a file key is only a seed once a stored resource outranks it.
|
||||
Before adding or reusing a config field, name its consumer, and reject the
|
||||
configuration when there is none - which is what this repo now does for
|
||||
per-identity `forge.intake`. Two documents carry the detail:
|
||||
`.agents/skills/archie-config-and-flags` holds the wiring matrix, the
|
||||
decoded-but-unwired ledger and the three shapes an unwired field can take;
|
||||
`docs/architecture/configuration.md` is the authority on the config model and
|
||||
its reloadability criterion.
|
||||
|
||||
- **`internal/channels/telegram/`:**
|
||||
- The long-polling worker must call `dropPendingUpdates(ctx, b)` before
|
||||
`b.Start(ctx)` and on `/restart`.
|
||||
- Always publish command menus to `default`, `all_private_chats`, and
|
||||
`all_group_chats` simultaneously via `commands.go` to avoid scope shadowing
|
||||
from legacy registrations.
|
||||
|
||||
- **`ai-sdk` Streaming:** `FullStream` writes synchronously and MUST be drained
|
||||
completely to prevent producer deadlocks. Do not rely on `TextStream` (drops
|
||||
deltas).
|
||||
- **NATS Invariants:**
|
||||
- `ARCHIE_TASKS` uses `jetstream.WorkQueuePolicy`. Do not bind overlapping
|
||||
consumer filters; use `Fetch` on existing durables instead of new `Subscribe`
|
||||
calls.
|
||||
- RPC and task responses must use core NATS `msg.Respond` to write to ephemeral
|
||||
`_INBOX.*` subjects, not `eventbus.Publisher`.
|
||||
- Always flush connections (`nc.Flush()`) immediately after registering
|
||||
responders to avoid race conditions on initial requests.
|
||||
|
||||
- **`internal/gateway/` Chat Prompt:** System prompt `<tools>` blocks are
|
||||
rendered strictly from the active `core.ToolSet`. Never decouple prompt tool
|
||||
definitions from passed runtime tools.
|
||||
- **`internal/container/pool.go` (`WriteTaskJSON`):** Write task briefs to
|
||||
`<worktree>/.git/task.json`. Never place them in the worktree root (`go-git`
|
||||
`Add{All:true}` ignores `.gitignore` and leaks root files into branch
|
||||
commits).
|
||||
- **MCP Providers:** Daemon registers providers as optional via
|
||||
`providerRegistry.RegisterOptional`. Missing or failed providers log warnings
|
||||
and degrade health without terminating the process.
|
||||
- **`internal/infrastructure/staterpc/` (State Store gRPC contract):**
|
||||
Authority is `docs/prds/state-store-contract.md` (rev. 2e) -- read it before
|
||||
changing this package or its callers.
|
||||
- The proto (`proto/state/v1/state.proto`, service `StateStoreService`,
|
||||
package `statev1` in `internal/contracts/state/v1/`) is one gRPC service
|
||||
fronting every ratified store contract, including grant management; the Go
|
||||
consumer facades
|
||||
stay narrow (`workflow.Store`, `store.TaskStore`, etc., all ≤8 methods
|
||||
except the `TaskStore` composite) via `staterpc.Client`'s multiple `var _`
|
||||
assertions -- never add a Go interface method without a matching RPC.
|
||||
- Error sentinels (`store.ErrStaleTransition`, `ErrBindingNotFound`, ...)
|
||||
cross the wire via `mapError`/`unmapError` in `values.go`, matched on
|
||||
`(code, exact canonical message)`. Changing a canonical message string
|
||||
breaks `errors.Is` on the client without changing behaviour visibly --
|
||||
treat those message constants as part of the wire contract.
|
||||
- The State Store is a standalone process (`cmd/archie-state-store`, run via
|
||||
`archied.RunStateStore`) -- the daemon and Gateway never own the task
|
||||
tables or serve this service in-process; `boot.openStateStore` in
|
||||
`internal/app/archied/state_store.go` is the only place the task store
|
||||
is built. Never add a second listener for the same
|
||||
service, and never reintroduce an in-process serving path in the
|
||||
daemon/Gateway (`TestOpenStoresNeverOwnsTaskDB` guards this).
|
||||
- Per-task credentials are scoped, not just authenticated: `daemon.
|
||||
StateStoreGrantIssuer` (`staterpc.GrantIssuer`) registers a fresh
|
||||
task-scoped grant at the remote State Store via `RegisterTaskGrant` before
|
||||
`ContainerPool.Acquire` and revokes it via `RevokeTaskGrant` on `Release`
|
||||
(`acquireTaskContainer`/`process` in `internal/daemon/daemon.go`). Fails
|
||||
closed (parks the task) if a State Store is configured but no issuer is
|
||||
wired -- it must never fall back to forwarding the daemon's own
|
||||
administrative token. Server-side, `staterpc.TaskGrants.UnaryInterceptor`
|
||||
authorises a task-scoped token for only `Update`/`Transition`/`InsertEvent`
|
||||
on its own task ID; every other RPC (including `RegisterTaskGrant`/
|
||||
`RevokeTaskGrant` themselves and the streaming capture RPCs) requires the
|
||||
administrative token.
|
||||
- `archie-agent` has exactly one `workflow.Store` path: gRPC via
|
||||
`staterpc.Client` (`agenttransport/nats.Transport.Store`), using the
|
||||
`STATE_STORE_URL`/`STATE_STORE_TOKEN` env the daemon injects. The legacy
|
||||
NATS `storerpc` transport is deleted (`internal/storerpc` no longer
|
||||
exists); do not reintroduce a dual-path selection.
|
||||
- `store.BindingDispatcher.RecordDispatch` takes no `*sql.Tx` (dropped in
|
||||
`.4.2` -- it cannot cross a gRPC boundary; production always passed `nil`).
|
||||
Do not reintroduce a transaction parameter on a producer-owned store
|
||||
interface that a remote adapter must also implement.
|
||||
- **`internal/forge/webhook/` (forge webhook receiver):**
|
||||
- Verify HMAC (`webhookguard.VerifyHMAC` against `X-Hub-Signature-256`) before
|
||||
parsing the payload, never after -- an unverified body must not reach
|
||||
`github.ParseWebHook`.
|
||||
- Do not give the webhook-built `workintake.TaskEnvelope` a delivery-source-
|
||||
specific idempotency key. `IdempotencyKey()` is keyed on `owner/repo/number`
|
||||
only so a webhook-delivered issue and a later poll of the same issue dedup
|
||||
against each other via `PublishUnique`; adding an event ID or timestamp to
|
||||
the key defeats that and reintroduces poll/webhook double-dispatch.
|
||||
- Webhook intake refuses to start when `[[identities]]` is configured (one
|
||||
receiver, one dispatch config). Do not silently enable it for multi-identity
|
||||
deployments without first building per-identity routing -- see
|
||||
`docs/architecture/messaging-and-work-intake.md`'s "Intake provenance"
|
||||
section.
|
||||
- **`internal/domain/embedding/` + `internal/infrastructure/embedding/`:**
|
||||
Embedding client contract + implementation. Config-driven exactly like chat
|
||||
model roles: `models.embedding = "provider/model"` plus a `[providers.*]`
|
||||
entry. `infrastructure/embedding.New` degrades to `(nil, false)` -- never an
|
||||
error -- for a missing role, unknown provider, unsupported class, or
|
||||
unresolved credential; wired as an optional capability in
|
||||
`bootstrap.go`'s `setupEmbeddings`. Only provider classes matching
|
||||
`config.Provider`'s shape are supported (openai, gemini, ollama, cohere,
|
||||
mistral) -- azure needs a `Deployment` field this config type doesn't have.
|
||||
- **`internal/domain/sampling/`:** The curator `Sampler` interface (see
|
||||
`docs/prds/curator-sampler-wave1.md`) plus four pure, deterministic
|
||||
strategies (recency, staleness, random, all). No curator consumes a
|
||||
`Sampler` yet -- `curator.Registrar` is untouched by this package.
|
||||
|
||||
## Development Protocol
|
||||
|
||||
1. **Red (Failing Test):** For behaviour with real logic, branching, or a
|
||||
contract, write failing table-driven tests first against target behaviour.
|
||||
Verify the failure originates from test assertions, not compilation errors.
|
||||
Do not write tests that restate an assignment or a constant: a test that
|
||||
cannot fail for an interesting reason is noise in the gate.
|
||||
- **A test is a maintenance liability, not free insurance.** Every test
|
||||
added is code the project now carries forever: it must compile, it must
|
||||
keep passing as the code around it changes, and someone reads it during
|
||||
every future change to that area. Write one because a real regression
|
||||
would slip through without it, not because the function was touched.
|
||||
- **Never pin a literal end-user config value, database row, or settings
|
||||
document as the thing under test.** Test the validation rule, the
|
||||
migration's shape, or the round-trip contract -- not one operator's
|
||||
specific `config.toml` value, a hand-picked DB fixture that mirrors real
|
||||
data, or a setting's current default. Those change for reasons that have
|
||||
nothing to do with a regression, and a test pinned to one breaks on
|
||||
every such change, which is cost with no signal.
|
||||
- **Test-only helpers, fakes and fixtures live in `_test.go` files (or a
|
||||
package no production `.go` file imports), never in a file the binary
|
||||
ships.** `go build` does not compile `_test.go` files into the binary,
|
||||
but an exported "test helper" living in a regular source file compiles
|
||||
into every binary that imports the package, whether or not a test ever
|
||||
runs. If a helper must be shared across packages, put it behind a
|
||||
build-tagged or `_test.go`-suffixed file in an `xtest`-style package,
|
||||
not behind a normal export.
|
||||
- **Coverage is not the goal.** A codebase that grows mostly because tests
|
||||
multiplied faster than the feature they cover is a symptom, not
|
||||
progress -- prefer fewer, sharper tests over one per line changed.
|
||||
2. **Green (Implementation):** Implement minimal code to satisfy the failing
|
||||
tests.
|
||||
3. **Quality Gate:** Run `task check`.
|
||||
- **The gate gates the commit.** Let the gate's exit status decide whether
|
||||
the commit runs, as one conditional chain (`check && commit && push`).
|
||||
Writing them as separate statements on one command line makes the gate
|
||||
decorative: nothing reads its status but the operator, and a failure is
|
||||
discovered after it has already been pushed.
|
||||
- **Never assert a gate result you have not just produced on that exact
|
||||
tree.** A commit message outlives the tree it describes, and "verified"
|
||||
is read by people who were not there. If the tree moved, describe the
|
||||
change and let the run speak.
|
||||
4. **Formatting is LAW:** Adopt all formatting and simplification changes from
|
||||
`task fmt` (`go fix` + the configured golangci-lint formatters) verbatim.
|
||||
Never revert or fight canonical linter/formatter diffs.
|
||||
5. **No standing adversarial-review pass (for contributors):** Do not spawn a
|
||||
separate fresh-context reviewer pass on every change as a matter of course.
|
||||
Red-green TDD plus `task check` is the gate; a manual adversarial pass is
|
||||
opt-in per request — ask before running one. This is the rule for a human or
|
||||
agent _contributor_. Separately, archied runs its own PR review pipeline
|
||||
(`docs/prds/pr-review-agent.md`) before it opens a PR of its own — see that
|
||||
PRD's Triggers section ("archie's own PRs"). It supersedes the older
|
||||
single-reviewer stage `docs/architecture/adversarial-review.md` described
|
||||
(`repo.review_enabled` no longer exists). The two paths are distinct: you
|
||||
run a manual pass when asked; archied runs its own before it opens a PR.
|
||||
6. **Linter Guard:**
|
||||
|
||||
- When using `errorlint` fixes, ensure boolean predicates (e.g.
|
||||
`exitErr.ExitCode() == 1`) are retained alongside `errors.As`.
|
||||
- When extracting loops/conditionals, verify slice mutations and pointer
|
||||
semantics do not duplicate elements.
|
||||
|
||||
## Issue Tracking (Beads)
|
||||
|
||||
All task management is tracked via **bd (beads)**. Do not write local Markdown
|
||||
TODO lists or use non-Beads trackers.
|
||||
|
||||
### Commands
|
||||
|
||||
```bash
|
||||
bd ready # List unclaimed work
|
||||
bd show <id> # View issue details
|
||||
bd update <id> --claim # Claim an issue
|
||||
bd close <id> # Mark issue complete
|
||||
bd remember # Persist cross-session architectural facts
|
||||
```
|
||||
|
||||
- Run `bd prime` to inspect full engine context.
|
||||
- Use `bd remember` for knowledge retention. Do not write to root `MEMORY.md`
|
||||
files.
|
||||
- Issues live in a local Dolt DB, synced to its own `git+` remote via
|
||||
`bd dolt push`/`bd dolt pull`. `.beads/issues.jsonl` and
|
||||
`.beads/interactions.jsonl` are local-only export/audit files
|
||||
(`.gitignore`d, `export.auto: false`) -- never `git add` them and never
|
||||
create a commit whose only content is beads bookkeeping. Bead state moves
|
||||
through Dolt, not through git commits on this repo.
|
||||
- **A bead never carries production instance detail.** No operator host name,
|
||||
hostname, IP or port, filesystem path, PID, or credential -- in the body
|
||||
_or_ the title, since both sync to the Dolt remote and are therefore
|
||||
published. Write the mechanism and the evidence shape instead ("a production
|
||||
host", "the State Store target", "the host's `config.toml`"), and put the
|
||||
host-specific facts in the operator's memos instance, which the bead may
|
||||
point at. This is the same class of rule as never committing a credential:
|
||||
the tracker is not a private store.
|
||||
|
||||
## Session Completion Protocol
|
||||
|
||||
1. **Log remaining work:** File new items via `bd` for identified debt or
|
||||
follow-up tasks.
|
||||
2. **Run gate:** Verify `task check` passes completely clean.
|
||||
3. **Update tracker:** Close finished issues via `bd close <id>`. This alone
|
||||
is not commit-worthy -- do not stage or commit `.beads/` for it.
|
||||
4. **Commit:** Only for actual code/doc changes, scoped to the files that
|
||||
changed.
|
||||
|
||||
```bash
|
||||
git add <scoped-files>
|
||||
git commit -m "feat(scope): description"
|
||||
```
|
||||
|
||||
5. **Sync & Push Policy:** Do not push to git remotes or run `bd dolt push`
|
||||
unless explicitly instructed.
|
||||
6. **Handoff:** Report changed files, gate verification results, and active
|
||||
issue states.
|
||||
|
||||
## Maintaining this file
|
||||
|
||||
Keep this file for knowledge useful to almost every future agent session in this project.
|
||||
Do not repeat what the codebase already shows; point to the authoritative file or command instead.
|
||||
Prefer rewriting or pruning existing entries over appending new ones.
|
||||
When updating this file, preserve this bar for all agents and keep entries concise.
|
||||
A rule is added only after a real failure it would have prevented, and it must
|
||||
say which decision it changes. Remove rules that no longer change decisions.
|
||||
Keep it short enough to read in full every session.
|
||||
+38
-22
@@ -2,32 +2,33 @@
|
||||
# Pre-installs system tools agents can't install themselves (no apt, no sudo).
|
||||
# Language packages are installed at runtime via uv/npm/go.
|
||||
#
|
||||
# Build: docker build -t archie-agent:latest .
|
||||
# This image is launched only by archied with a daemon-written task brief,
|
||||
# task worktree mount, and authenticated NATS environment.
|
||||
# Build: task image:agent (or docker build --build-arg RUNTIME_VERSION=<ver>)
|
||||
# A build that names no version stamps none, and the agent reports dev.
|
||||
|
||||
# ── builder ───────────────────────────────────────────────────────────
|
||||
# ── builder ──
|
||||
FROM golang:1.27-trixie AS builder
|
||||
ARG RUNTIME_VERSION=dev
|
||||
WORKDIR /src
|
||||
COPY go.mod go.sum ./
|
||||
RUN go mod download
|
||||
# Cache mounts keep modules and compiled packages on the build daemon; without
|
||||
# them COPY . . makes every commit a cold compile.
|
||||
RUN --mount=type=cache,target=/go/pkg/mod go mod download
|
||||
COPY . .
|
||||
RUN CGO_ENABLED=0 go build \
|
||||
RUN --mount=type=cache,target=/go/pkg/mod \
|
||||
--mount=type=cache,target=/root/.cache/go-build \
|
||||
CGO_ENABLED=0 go build \
|
||||
-ldflags "-X github.com/samcharles93/archie-core/internal/app/agentworker.version=${RUNTIME_VERSION} -X github.com/samcharles93/archie-core/internal/installtype.buildType=container" \
|
||||
-o /usr/local/bin/archie-agent ./cmd/archie-agent/
|
||||
|
||||
# Same Debian release as the runtime, so glibc matches.
|
||||
FROM node:24-trixie-slim AS node
|
||||
|
||||
# ── runtime ───────────────────────────────────────────────────────────
|
||||
# ── runtime ──
|
||||
FROM debian:trixie-slim
|
||||
ARG RUNTIME_VERSION=dev
|
||||
LABEL org.opencontainers.image.version="${RUNTIME_VERSION}"
|
||||
|
||||
ENV DEBIAN_FRONTEND=noninteractive
|
||||
|
||||
# build-essential is for agents building native npm/Python extensions.
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
ca-certificates \
|
||||
curl \
|
||||
@@ -41,7 +42,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
openssh-client \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# ── Node.js 24 ────────────────────────────────────────────────────────
|
||||
# ── Node.js 24 ──
|
||||
COPY --from=node /usr/local/bin/node /usr/local/bin/node
|
||||
COPY --from=node /usr/local/include/node /usr/local/include/node
|
||||
COPY --from=node /usr/local/lib/node_modules /usr/local/lib/node_modules
|
||||
@@ -50,7 +51,7 @@ RUN ln -s ../lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm && \
|
||||
npm install -g pnpm typescript tsx esbuild stylelint htmlhint && \
|
||||
npm cache clean --force
|
||||
|
||||
# ── Go ────────────────────────────────────────────────────────────────
|
||||
# ── Go ──
|
||||
# Reuse the builder's toolchain so the runtime Go can't drift from the one
|
||||
# archie-agent was compiled with.
|
||||
COPY --from=builder /usr/local/go /usr/local/go
|
||||
@@ -58,15 +59,15 @@ ENV GOPATH="/go"
|
||||
# /go/bin must be on PATH or anything `go install` puts there is unreachable.
|
||||
ENV PATH="/usr/local/go/bin:/go/bin:${PATH}"
|
||||
|
||||
# Pinned release binaries. Building these with `go install` pulled ~2GB of
|
||||
# module and build cache into the image. delve is omitted because it ships no
|
||||
# prebuilt binary; `go install ...@latest` at runtime if an agent needs it.
|
||||
#
|
||||
# golangci-lint owns ordinary source formatting and lint checks. Standalone
|
||||
# gofumpt is retained for generated protobuf contracts in tools/proto.sh.
|
||||
ARG GOLANGCI_LINT_VERSION=2.13.2
|
||||
ARG GOLANGCI_LINT_VERSION=2.14.0
|
||||
ARG GOFUMPT_VERSION=0.11.0
|
||||
ARG BUF_VERSION=1.72.0
|
||||
# Pinned to the versions tools/proto.sh installs; buf generate shells out to them.
|
||||
ARG PROTOC_GEN_GO_VERSION=1.36.11
|
||||
ARG PROTOC_GEN_GO_GRPC_VERSION=1.6.2
|
||||
# Repository gates run `task`; fetching it per run parks the task when the
|
||||
# download fails.
|
||||
ARG TASK_VERSION=3.54.0
|
||||
|
||||
RUN curl -fsSL "https://github.com/golangci/golangci-lint/releases/download/v${GOLANGCI_LINT_VERSION}/golangci-lint-${GOLANGCI_LINT_VERSION}-linux-amd64.tar.gz" \
|
||||
| tar -xz -C /usr/local/bin --strip-components=1 \
|
||||
@@ -75,17 +76,32 @@ RUN curl -fsSL "https://github.com/golangci/golangci-lint/releases/download/v${G
|
||||
"https://github.com/mvdan/gofumpt/releases/download/v${GOFUMPT_VERSION}/gofumpt_v${GOFUMPT_VERSION}_linux_amd64" && \
|
||||
curl -fsSL -o /usr/local/bin/buf \
|
||||
"https://github.com/bufbuild/buf/releases/download/v${BUF_VERSION}/buf-Linux-x86_64" && \
|
||||
chmod +x /usr/local/bin/gofumpt /usr/local/bin/buf
|
||||
curl -fsSL "https://github.com/go-task/task/releases/download/v${TASK_VERSION}/task_linux_amd64.tar.gz" \
|
||||
| tar -xz -C /usr/local/bin task && \
|
||||
chmod +x /usr/local/bin/gofumpt /usr/local/bin/buf && \
|
||||
GOBIN=/usr/local/bin go install "google.golang.org/protobuf/cmd/protoc-gen-go@v${PROTOC_GEN_GO_VERSION}" && \
|
||||
GOBIN=/usr/local/bin go install "google.golang.org/grpc/cmd/protoc-gen-go-grpc@v${PROTOC_GEN_GO_GRPC_VERSION}" && \
|
||||
go clean -cache -modcache
|
||||
|
||||
# ── Python via uv ─────────────────────────────────────────────────────
|
||||
# uv manages its own interpreters — no apt Python, no deadsnakes PPA. One
|
||||
# version is the default; agents can `uv python install <other>` on demand.
|
||||
ARG PYTHON_VERSION=3.14
|
||||
RUN curl -fsSL https://astral.sh/uv/install.sh | sh
|
||||
ENV PATH="/root/.local/bin:${PATH}"
|
||||
RUN uv python install --default "${PYTHON_VERSION}" && rm -rf /root/.cache/uv
|
||||
|
||||
# Point each toolchain at its cache volume (internal/storage). Unset, pnpm puts
|
||||
# its store on the worktree's filesystem, inside the repository the agent commits.
|
||||
ENV GOMODCACHE=/data/cache/go/mod \
|
||||
GOCACHE=/data/cache/go/build \
|
||||
npm_config_cache=/data/cache/node \
|
||||
npm_config_store_dir=/data/cache/pnpm \
|
||||
DENO_DIR=/data/cache/deno \
|
||||
BUN_INSTALL_CACHE_DIR=/data/cache/bun \
|
||||
PIP_CACHE_DIR=/data/cache/pip \
|
||||
UV_CACHE_DIR=/data/cache/pip \
|
||||
CARGO_HOME=/data/cache/cargo
|
||||
|
||||
COPY --from=builder /usr/local/bin/archie-agent /usr/local/bin/archie-agent
|
||||
|
||||
# The daemon injects NATS_URL and, when configured, NATS_TOKEN.
|
||||
# The daemon injects NATS_URL.
|
||||
ENTRYPOINT ["archie-agent"]
|
||||
+20
-21
@@ -1,29 +1,30 @@
|
||||
# archied — the archie daemon, built as a standalone container.
|
||||
# archied — the archie daemon
|
||||
# Run via docker compose alongside NATS.
|
||||
|
||||
FROM node:24-trixie-slim AS dashboard
|
||||
WORKDIR /src/ui
|
||||
RUN corepack enable
|
||||
COPY ui/package.json ui/pnpm-lock.yaml ui/pnpm-workspace.yaml ./
|
||||
RUN pnpm install --frozen-lockfile
|
||||
COPY ui/ ./
|
||||
RUN pnpm run build
|
||||
|
||||
FROM golang:1.27-trixie AS builder
|
||||
WORKDIR /src
|
||||
COPY go.mod go.sum ./
|
||||
RUN go mod download
|
||||
# Cache mounts keep modules and compiled packages on the build daemon; without
|
||||
# them COPY . . makes every commit a cold compile.
|
||||
RUN --mount=type=cache,target=/go/pkg/mod go mod download
|
||||
COPY . .
|
||||
COPY --from=dashboard /src/ui/dist ./ui/dist
|
||||
ARG GATEWAY_VERSION=dev
|
||||
ARG RUNTIME_VERSION=dev
|
||||
RUN CGO_ENABLED=0 go build \
|
||||
-ldflags "-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion=${GATEWAY_VERSION} -X github.com/samcharles93/archie-core/internal/app/archied.runtimeVersion=${RUNTIME_VERSION} -X github.com/samcharles93/archie-core/internal/installtype.buildType=container" \
|
||||
RUN --mount=type=cache,target=/go/pkg/mod \
|
||||
--mount=type=cache,target=/root/.cache/go-build \
|
||||
CGO_ENABLED=0 go build \
|
||||
-ldflags "-X github.com/samcharles93/archie-core/internal/buildinfo.Version=${GATEWAY_VERSION} -X github.com/samcharles93/archie-core/internal/buildinfo.Runtime=${RUNTIME_VERSION} -X github.com/samcharles93/archie-core/internal/installtype.buildType=container" \
|
||||
-o /usr/local/bin/archied ./cmd/archied/
|
||||
# archied is static, but this can't be scratch: in inprocess mode the daemon
|
||||
# runs agent tools itself, and the shell tool invokes bash; codesearch shells
|
||||
# to git. Worktrees don't count — internal/worktree uses go-git. This image
|
||||
# is not part of the current deployment (docker-compose.yml only builds
|
||||
# Dockerfile, the agent image; archied runs on the host under systemd), but
|
||||
# if it's ever used in inprocess mode, grep needs ripgrep on PATH -- it is
|
||||
# no longer embedded in the binary.
|
||||
#
|
||||
# No Node: the builtin tools (read/write/edit/find/grep/shell/test) cover what
|
||||
# desktop-commander did. Any npx-launched MCP stdio server will now fail to
|
||||
# start, and a failed provider rolls back the tool-provider family and exits
|
||||
# the daemon — so remove tools.mcp_servers entries needing npx before
|
||||
# deploying this image.
|
||||
|
||||
FROM debian:trixie-slim
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
ca-certificates git && \
|
||||
@@ -33,8 +34,6 @@ ARG GATEWAY_VERSION=dev
|
||||
ARG RUNTIME_VERSION=dev
|
||||
LABEL org.opencontainers.image.version="${GATEWAY_VERSION}"
|
||||
LABEL cloud.catlow.archie.runtime-version="${RUNTIME_VERSION}"
|
||||
# One release stream: CHANGELOG.md carries every release section, with each
|
||||
# component's detail as a labelled section inside it. The per-component files
|
||||
# this used to copy were deleted with the split release.
|
||||
COPY CHANGELOG.md /usr/share/archie/CHANGELOG.md
|
||||
|
||||
|
||||
ENTRYPOINT ["archied"]
|
||||
@@ -1,17 +1,5 @@
|
||||
NOTICE
|
||||
|
||||
This product includes software derived from PR-AF
|
||||
(https://github.com/Agent-Field/pr-af), Copyright AgentField,
|
||||
licensed under the Apache License, Version 2.0.
|
||||
|
||||
Derived portions: internal/domain/workflow/prreview -- the unified diff
|
||||
parser, change clustering, blast radius, evidence extraction, scoring,
|
||||
deduplication, line mapping and review-event selection.
|
||||
|
||||
PR-AF declares the Apache License, Version 2.0 in its pyproject.toml and
|
||||
ships no license file. A copy of the License is available at
|
||||
https://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
This product includes software from the Cedar project
|
||||
(https://github.com/cedar-policy/cedar), Copyright Amazon.com, Inc. or its
|
||||
affiliates, licensed under the Apache License, Version 2.0, as implemented by
|
||||
|
||||
@@ -1,6 +1,9 @@
|
||||
[](https://github.com/samcharles93/archie-core/actions/workflows/quality.yml)
|
||||
|
||||
# Archie
|
||||
<h1>
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="assets/brand/archie-wordmark-dark.svg">
|
||||
<img alt="Archie" src="assets/brand/archie-wordmark.svg" height="56">
|
||||
</picture>
|
||||
</h1>
|
||||
|
||||
**Event-driven Agentic Automation**
|
||||
|
||||
@@ -14,12 +17,8 @@ network operations, service management, and software delivery. You define the
|
||||
process and the access it requires; agents work through its stages, using the
|
||||
context of each event to decide how to accomplish the task.
|
||||
|
||||
Archie is under active development. The model below describes the project's
|
||||
approved direction, with implementation progressing across event automation and
|
||||
organisation access control. The
|
||||
[event automation design](docs/prds/event-automation.md) and
|
||||
[organisations and access design](docs/prds/orgs-and-access.md) describe those
|
||||
capabilities and their delivery stages.
|
||||
Archie is under active development and not every capability below is
|
||||
finished.
|
||||
|
||||
## From an event to an outcome
|
||||
|
||||
@@ -77,35 +76,16 @@ Workflows can also call other workflows and pass data between them. Each called
|
||||
workflow has its own run and agent profile. A caller can wait for the result or
|
||||
continue while the called workflow runs independently.
|
||||
|
||||
See the
|
||||
[firewall investigation example](examples/workflows/firewall-investigate.yaml)
|
||||
for a workflow that uses typed inputs, a network investigator profile, and no
|
||||
The archipelago marketplace's `workflows/firewall` package is an example of a
|
||||
workflow that uses typed inputs, a network investigator profile, and no
|
||||
repository.
|
||||
|
||||
## Organisations, identities, and controlled execution
|
||||
## Identities and controlled execution
|
||||
|
||||
The approved access model organises automation into **organisations** and
|
||||
**workspaces**. An organisation owns its members, agent identities, secrets,
|
||||
profiles, and workflows. Workspaces group sources, mappings, bindings, and runs
|
||||
by team responsibility or environment, such as network operations in production.
|
||||
Each organisation can enable the default workflows it needs and add its own.
|
||||
|
||||
Agents act as their own identities. A workflow names the identity it runs as;
|
||||
secrets and permissions are granted to that identity. Starting an agent is an
|
||||
audited action, with a record of the workflow and the event or member that
|
||||
initiated it.
|
||||
|
||||
The design combines roles for routine administration with attribute-based
|
||||
policies for resources and execution context. Policies apply from the instance
|
||||
through the organisation, workspace, identity, workflow, and individual object.
|
||||
Lower levels can narrow access, and a denial takes precedence. Organisation and
|
||||
workspace policy also determines which actions require approval from another
|
||||
member.
|
||||
|
||||
Authorised runs receive credentials scoped to their identity, workspace, and
|
||||
work. Event data supplies the task's inputs; it cannot grant additional access.
|
||||
The [organisations and access design](docs/prds/orgs-and-access.md) defines this
|
||||
model; it remains an active implementation area.
|
||||
Agents act as their own identities, with secrets and permissions granted to
|
||||
that identity. Runs receive credentials scoped to their task; event data
|
||||
supplies inputs and cannot grant access. Organisations, workspaces and
|
||||
policy-based access control are in progress.
|
||||
|
||||
## Building and operating automations
|
||||
|
||||
@@ -114,69 +94,69 @@ and task activity. The intended authoring path starts with a real payload or an
|
||||
example: identify its structure, map the fields you need, select a workflow, and
|
||||
approve the binding.
|
||||
|
||||
Sources default to signed delivery. The event automation design also allows an
|
||||
explicitly approved unsigned source for systems that cannot sign payloads, with
|
||||
that status visible to operators. Binding changes require re-approval before
|
||||
they can dispatch work.
|
||||
Sources default to signed delivery; an unsigned source must be explicitly
|
||||
approved. Binding changes require re-approval before they can dispatch work.
|
||||
|
||||
Playbooks and extension points provide additional orchestration through
|
||||
workflows, modules, channels, and forges. The
|
||||
[playbook engine design](docs/prds/eda-playbook-engine.md) describes how
|
||||
registered capabilities become actions that event rules can call.
|
||||
## Run it on a server
|
||||
|
||||
## Develop locally
|
||||
You need x86_64 Linux with curl and unzip, Docker (agents and the bundled
|
||||
PostgreSQL run in containers) and a model: local [Ollama](https://ollama.com)
|
||||
or a hosted provider API key.
|
||||
|
||||
The repository requires Go 1.27, [Task](https://taskfile.dev/), Node.js and npm,
|
||||
and Docker with a running daemon. The development stack starts PostgreSQL 18
|
||||
through Docker Compose. Install the Go formatting and lint tools listed in
|
||||
[CLAUDE.md](CLAUDE.md#build--test) before running the full quality gate.
|
||||
1. **Install.**
|
||||
|
||||
```bash
|
||||
task dev
|
||||
```
|
||||
```bash
|
||||
curl -fsSL https://offloaded.dev/install.sh | bash
|
||||
```
|
||||
|
||||
Open <http://localhost:5173> for the dashboard with Vite hot reload. `task dev`
|
||||
starts the daemon, Gateway, State Store, UI service, and frontend development
|
||||
server; it uses [`deployments/dev.toml`](deployments/dev.toml) as a local
|
||||
configuration overlay. Set credentials and other required settings in your local
|
||||
Archie configuration as needed.
|
||||
It downloads the latest release, verifies its checksum, installs the five
|
||||
services into `~/.local/bin` and runs `archied setup`. Setup asks for the
|
||||
PostgreSQL URL (leave it blank for a bundled database with a generated
|
||||
password), a model provider and key, and a forge (choose **none** for
|
||||
event-driven automation only). Answers go to `~/.config/archie/config.toml`
|
||||
and secrets to `~/.config/archie/env`. The installer then starts the
|
||||
bundled PostgreSQL with Docker Compose and installs and starts systemd user
|
||||
units. Pass options with `| bash -s -- --help`; `--from-source` builds a
|
||||
checkout instead. Re-run `archied setup` at any time to change the answers.
|
||||
|
||||
Useful checks:
|
||||
Extensions run in an unprivileged user namespace. Ubuntu 23.10 and later
|
||||
block these by default; on such a host the installer prints an AppArmor
|
||||
profile that allows them for the Archie binaries only, to install with
|
||||
`sudo`.
|
||||
|
||||
```bash
|
||||
task build # build the service and agent binaries in bin/
|
||||
task test # run the short Go test suite
|
||||
task check # run the repository quality gate
|
||||
```
|
||||
2. **Check it is up.**
|
||||
|
||||
## Deploy
|
||||
```bash
|
||||
systemctl --user status archied archie-state-store archie-gateway archie-ui archie-messaging
|
||||
curl -s http://127.0.0.1:8485/health/detailed
|
||||
```
|
||||
|
||||
Start with the [deployment examples](deployments/README.md). They cover a single
|
||||
GitHub forge, multiple GitHub and Gitea identities, local Ollama, and an
|
||||
external NATS stack. Copy a suitable template to
|
||||
`${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`, then set its repository,
|
||||
model, credential, and service settings for your environment. The examples
|
||||
describe the required PostgreSQL connection and how to start each process. A
|
||||
[systemd user service guide](deployments/systemd-user-service.md) is available,
|
||||
but systemd is optional.
|
||||
3. **Open the dashboard** at <http://127.0.0.1:8484>. It binds loopback by
|
||||
default; tunnel to it (`ssh -L 8484:127.0.0.1:8484 server`) or see
|
||||
[deployments](deployments/README.md#running-the-dashboard) to expose it
|
||||
with a token.
|
||||
|
||||
4. **Automate your first event** with
|
||||
[Your first playbook](docs/guides/first-playbook.md): send a webhook, map
|
||||
its fields, bind it to a workflow and watch the task run.
|
||||
|
||||
To write the config by hand instead, start from
|
||||
[`deployments/standalone.toml`](deployments/standalone.toml) (no forge) or
|
||||
another [deployment template](deployments/README.md).
|
||||
|
||||
## Develop
|
||||
|
||||
`task dev` starts every service with Vite hot reload at
|
||||
<http://localhost:5173>, using [`deployments/dev.toml`](deployments/dev.toml).
|
||||
`task check` is the quality gate; [AGENTS.md](AGENTS.md) lists its tools.
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Event automation](docs/prds/event-automation.md) — sources, schemas,
|
||||
mappings, bindings, workflows, and agent profiles.
|
||||
- [Organisations and access](docs/prds/orgs-and-access.md) — tenancy,
|
||||
identities, permissions, approvals, and audit.
|
||||
- [Playbook engine](docs/prds/eda-playbook-engine.md) — event rules and
|
||||
extensible actions.
|
||||
- [Architecture decisions](docs/prds/01-project-management.md) — approved design
|
||||
and open migration questions.
|
||||
- [Development guides](docs/development/index.md) — change checklists by area.
|
||||
- [Deployment examples](deployments/README.md) — configuration templates and
|
||||
operating notes.
|
||||
- [Release process](RELEASING.md) — how releases are built and published.
|
||||
- [Your first playbook](docs/guides/first-playbook.md)
|
||||
- [Deployment examples](deployments/README.md)
|
||||
- [Release process](RELEASING.md)
|
||||
|
||||
Contributions should follow [AGENTS.md](AGENTS.md), including its testing,
|
||||
generated-file, and commit rules.
|
||||
Contributions follow [AGENTS.md](AGENTS.md).
|
||||
|
||||
## License
|
||||
|
||||
|
||||
+43
-116
@@ -1,129 +1,56 @@
|
||||
# Releasing
|
||||
|
||||
One release stream. `CHANGELOG.md` carries every release section, one generated
|
||||
page per version describes it, and one tag names the release. A release is one
|
||||
version covering whatever changed; the components' entries are labelled sections
|
||||
inside it (`### archied`, `### archie-agent`), not separate numbers or separate
|
||||
pages.
|
||||
|
||||
The host bundle ships six processes — `archied`, `archie-gateway`,
|
||||
`archie-state-store`, `archie-ui`, `archie-messaging`, `archie-playbooks` — and
|
||||
one version covers all of them. `archie-agent`, the per-task sandboxed runtime,
|
||||
ships as a container image and its changes are the `## [version]` release's
|
||||
`### archie-agent` section.
|
||||
|
||||
`tools/release.sh` decides which commits a release carries from the package
|
||||
closure of **every shipped binary**, not from commit-message guessing: a change
|
||||
to a package only the messaging service, state store, playbook runner or UI
|
||||
links still lands in the changelog. Read its header comment for how it
|
||||
partitions commits and enforces `main`-only, clean-tree releases.
|
||||
|
||||
## What justifies a version
|
||||
|
||||
`task release:preview VERSION=X.Y.Z` shows exactly what would land, before
|
||||
anything is written. A commit set that justifies no version produces no version:
|
||||
`release.sh` exits **3** with "nothing to release" rather than inventing one, so
|
||||
a pipeline can finish green without tagging.
|
||||
|
||||
Most sessions touch the gateway side (daemon, gateway, web UI, chat, messaging)
|
||||
and leave the agent runtime alone. That is no longer a per-component `skip`
|
||||
decision — one version covers the release — but a runtime code change being
|
||||
merged to `main` is still not the same as it being in production: the
|
||||
`archie-agent` image is rebuilt by the release, and a host that runs the agent
|
||||
must pull the new image (`docker compose pull agent`) to get it.
|
||||
|
||||
## What the notes are for
|
||||
|
||||
**Release notes describe the reader's experience of what shipped.** The test is
|
||||
the reader, not whether a sentence is negative:
|
||||
|
||||
- A capability that **never existed** leaves no expectation to correct, so a
|
||||
note about it reads as a feature to someone who never had the thing — out.
|
||||
- **The implementation's journey** — what was rebuilt, what a guard finally
|
||||
covers, what a browser API refuses to surface — is not the reader's experience
|
||||
either — out.
|
||||
- A capability that **shipped but is not yet wired** _is_ the reader's
|
||||
experience, so it belongs, worded as a caveat on the capability and paired
|
||||
with the behaviour that compensates for it.
|
||||
|
||||
Design constraints and withheld capabilities belong in `docs/architecture/`,
|
||||
where implementers look, because there they are requirements rather than news.
|
||||
Do not apply this mechanically: deleting a caveat a reader needs misleads them,
|
||||
which is the failure this rule exists to prevent.
|
||||
One `v*` tag names a release. One version covers every process in the host
|
||||
bundle (`archied`, `archie-gateway`, `archie-state-store`, `archie-ui`,
|
||||
`archie-messaging`) and the `archie-agent` image. Nothing is released from a
|
||||
laptop.
|
||||
|
||||
## Cutting a release
|
||||
|
||||
```bash
|
||||
task release:preview VERSION=1.3.0 # preview what would land
|
||||
task release:prepare VERSION=1.3.0 # write the section into CHANGELOG.md, uncommitted
|
||||
# edit CHANGELOG.md -- generated notes are a starting point, not the release
|
||||
task release VERSION=1.3.0 # commit + annotated tag
|
||||
git push origin main --follow-tags # CI stamps images with real versions
|
||||
```
|
||||
|
||||
`release:prepare` emits bare commit subjects; they are a starting point. Rewrite
|
||||
them to say what a reader gets, per "What the notes are for" above.
|
||||
|
||||
Pushing is a separate, explicit step — never push without confirming first (see
|
||||
the repo's general "check before doing anything hard to reverse" rule). The
|
||||
deploy workflow reads tags pointing at `HEAD`; pushing the commit without its
|
||||
tag gets images stamped `dev`.
|
||||
|
||||
### After a release, `main` and the working branch have diverged
|
||||
|
||||
The release commit lands on `main` — `tools/release.sh` refuses to run anywhere
|
||||
else — while the working branch keeps advancing. So after every release, `main`
|
||||
is ahead by exactly that commit and the branch is ahead by however far it has
|
||||
moved: **neither tip is an ancestor of the other**, and `--ff-only` fails in
|
||||
both directions. That refusal reads as "the tree is not ready" when in fact the
|
||||
tree is fine.
|
||||
|
||||
Merge the release commit into the branch first, so any conflict is resolved on
|
||||
the branch, where it is reversible and nobody is reading the tip:
|
||||
|
||||
```bash
|
||||
git merge main # on the branch
|
||||
git merge --ff-only <branch> # then, in whichever worktree holds main
|
||||
```
|
||||
|
||||
Confirm which worktree holds `main` with `git worktree list` before the
|
||||
`--ff-only`. A detached worktree sitting at the same commit will accept it and
|
||||
move nothing, which looks like success.
|
||||
Dispatch the **release** workflow (`.github/workflows/release.yml`) with
|
||||
`major`, `minor`, `patch` or an exact version. It runs `task release` on
|
||||
`main`, which refuses a dirty tree or an existing tag and then tags `vx.y.z`,
|
||||
and pushes the tag with `DEPLOY_TOKEN`. A push made with the job token
|
||||
wouldn't start other workflows, so the user token is what lets the tag start
|
||||
the deploy.
|
||||
|
||||
## What a release publishes
|
||||
|
||||
Tagging one version produces, from a single `deploy` run:
|
||||
The tag push runs `deploy.yml`:
|
||||
|
||||
- **Container images** — `ghcr.io/samcharles93/archied:latest` and
|
||||
`ghcr.io/samcharles93/archie-agent:latest`. The runtime image is rebuilt by
|
||||
the release, so runtime commits merged to `main` do not reach a running
|
||||
sandbox until the host pulls the new image.
|
||||
- **`:latest` names the newest release, not the newest commit.** A push to
|
||||
`main` that is not a release publishes `archied:edge` (mutable, tracking
|
||||
`main`) and `archied:sha-<commit>` (immutable) instead, so a release's
|
||||
`:latest` stamping is not overwritten minutes later by the next ordinary
|
||||
commit. A host that runs releases follows `:latest`; a host that tracks `main`
|
||||
follows `:edge`.
|
||||
- **A GitHub Release with a distribution zip** — `dist-zip` builds every process
|
||||
the reference deployment runs (`archied`, `archie-gateway`,
|
||||
`archie-state-store`, `archie-ui`, `archie-messaging`, `archie-playbooks`) for
|
||||
linux/amd64, packs them with `deployments/INSTRUCTIONS.md` and `CHANGELOG.md`,
|
||||
and attaches the zip to the Release. The Release body is that version's
|
||||
`## [version]` section of `CHANGELOG.md`.
|
||||
- **Gate.** `task check dist TEST_FLAGS=-count=1` and `govulncheck`. The
|
||||
binaries the zip ships are built in the same run, so nothing is compiled
|
||||
again after the gate.
|
||||
- **Images.** `archied:v<version>` and `archie-agent:v<version>`, plus
|
||||
`sha-<commit>` tags. `:latest` moves only on promotion.
|
||||
- **The signed release.** `archied release publish` signs a statement
|
||||
(version, issued_at, zip digest, agent image by digest) with
|
||||
`RELEASE_SIGNING_KEY` and pushes it with the distribution zip to
|
||||
`git.catlow.cloud/sam/archie` as `v<version>` and `next`. It never moves
|
||||
`stable`.
|
||||
- **The release page** on Gitea, listing the commit subjects since the
|
||||
previous tag. The statement links to it.
|
||||
|
||||
The zip is also uploaded as an Actions artifact, but that is a backup copy:
|
||||
artifacts expire after 90 days and need an Actions login to download. The
|
||||
Release asset is the durable, operator-reachable one.
|
||||
Actions run the workflow from the tagged commit, so a fix to `deploy.yml`
|
||||
reaches a release only if it is an ancestor of the tag. Cut a new release
|
||||
rather than committing the fix on top of a tagged one.
|
||||
|
||||
## Gate
|
||||
## Promote
|
||||
|
||||
CI (`deploy.yml`) runs `task check` before building images, then verifies any
|
||||
release tag at `HEAD` has a matching `[version]` section in `CHANGELOG.md`. A
|
||||
tag with no changelog entry is a hard failure. No tags at `HEAD` is a warning,
|
||||
not a failure — images get stamped `dev`.
|
||||
Dispatch the **promote** workflow (`.github/workflows/promote.yml`) with a
|
||||
`version`. It retags `stable` to that release and moves the `archied` and
|
||||
`archie-agent` images' `:latest` to it. Promotion refuses a prerelease and a
|
||||
release issued before the one `stable` names, the same replay rule hosts
|
||||
enforce. The same thing by hand:
|
||||
|
||||
One consequence worth knowing when a release commit needs amending: GitHub
|
||||
Actions runs the workflow **from the commit that triggered it**, so a fix to
|
||||
`deploy.yml` only takes effect for a release if it is an ancestor of the tagged
|
||||
commit. Delete and re-cut the tag (`git tag -d`, `task release`) rather than
|
||||
committing the fix on top of an already-tagged release.
|
||||
```bash
|
||||
archied release promote -version 1.63.0 \
|
||||
-latest git.catlow.cloud/sam/archied,git.catlow.cloud/sam/archie-agent
|
||||
```
|
||||
|
||||
## Secrets
|
||||
|
||||
| Name | Used by |
|
||||
|---|---|
|
||||
| `DEPLOY_TOKEN` | release, deploy, promote: the registry push, the tag push and the package links |
|
||||
| `RELEASE_SIGNING_KEY` | deploy: signs the release statement |
|
||||
+194
-196
@@ -2,17 +2,40 @@ version: "3"
|
||||
|
||||
vars:
|
||||
BIN_DIR: "bin"
|
||||
# The version a build reports: the nearest tag with the distance and commit,
|
||||
# or a bare commit when the checkout has no tags (a shallow clone). A build
|
||||
# should not answer "dev" only because the caller did not name a version.
|
||||
VERSION:
|
||||
sh: git describe --tags --always --dirty 2>/dev/null | sed 's/^v//' || echo dev
|
||||
|
||||
tasks:
|
||||
default:
|
||||
desc: List available tasks
|
||||
cmds:
|
||||
- task --list
|
||||
|
||||
fmt:
|
||||
desc: Fix and format Go source
|
||||
desc: Fix and format Go source with the gate's configured formatters
|
||||
cmds:
|
||||
- go fix ./...
|
||||
# One go fix pass is not a fixpoint: it applies each fixer once, to the
|
||||
# parse it started with, so a rewrite made by one fixer is only fixed up
|
||||
# by the next pass. stditerators turns `for i := range t.NumField()` into
|
||||
# a field iterator that copies its loop variable, and forvar deletes that
|
||||
# copy on the following pass -- leaving the copy behind for copyloopvar
|
||||
# to reject. Apply passes until a dry run reports nothing left to fix,
|
||||
# and fail rather than hand the lint step a tree it must reject.
|
||||
- |
|
||||
set -eu
|
||||
converged=false
|
||||
for pass in 1 2 3 4 5 6 7 8 9 10; do
|
||||
go fix ./...
|
||||
if go fix -diff ./... >/dev/null; then
|
||||
converged=true
|
||||
break
|
||||
fi
|
||||
done
|
||||
if [ "$converged" != true ]; then
|
||||
echo "go fix still rewrites the tree after 10 passes" >&2
|
||||
exit 1
|
||||
fi
|
||||
# This must use the same engine and configuration as task lint. Running
|
||||
# standalone gofumpt cannot reproduce gci's custom import grouping, so it
|
||||
# can leave a tree that the gate rejects.
|
||||
- golangci-lint fmt
|
||||
|
||||
proto:install:
|
||||
@@ -41,46 +64,23 @@ tasks:
|
||||
- task: db:generate
|
||||
- git diff --exit-code -- internal/infrastructure/postgres/postgresdb
|
||||
|
||||
openapi:generate:
|
||||
desc: Write the API's OpenAPI document to api/openapi.yaml
|
||||
cmds:
|
||||
- mkdir -p api
|
||||
- go run ./cmd/archie openapi > api/openapi.yaml
|
||||
|
||||
openapi:check:
|
||||
desc: Regenerate the OpenAPI document and reject uncommitted differences
|
||||
cmds:
|
||||
- task: openapi:generate
|
||||
- git diff --exit-code -- api/openapi.yaml
|
||||
|
||||
proto:check:
|
||||
desc: Regenerate contracts and reject uncommitted generated differences
|
||||
cmds:
|
||||
- bash tools/proto.sh check
|
||||
|
||||
docs:generate:
|
||||
desc: Regenerate the committed contract reference from Archie-owned types
|
||||
cmds:
|
||||
- go -C tools run -mod=readonly ./docsgen --repo-root ..
|
||||
|
||||
docs:check:
|
||||
desc: Verify the committed contract reference matches Archie-owned types
|
||||
cmds:
|
||||
- go -C tools run -mod=readonly ./docsgen check --repo-root ..
|
||||
|
||||
docs:prds:
|
||||
desc: Reject session-bound writing in docs/prds
|
||||
cmds:
|
||||
- go -C tools run -mod=readonly ./prdlint --repo-root ..
|
||||
|
||||
news:
|
||||
desc: Regenerate the release data artifacts from the changelog
|
||||
cmds:
|
||||
- go -C tools run -mod=readonly ./newsgen --repo-root ..
|
||||
|
||||
news:check:
|
||||
desc: Verify the committed release notes match the changelog
|
||||
cmds:
|
||||
- go -C tools run -mod=readonly ./newsgen check --repo-root ..
|
||||
|
||||
docs:artifact:
|
||||
desc: Regenerate the canonical docs artifacts from the Markdown sources
|
||||
cmds:
|
||||
- go -C tools run -mod=readonly ./docsite --repo-root ..
|
||||
|
||||
docs:artifact:check:
|
||||
desc: Verify the committed docs artifacts match the Markdown sources
|
||||
cmds:
|
||||
- go -C tools run -mod=readonly ./docsite check --repo-root ..
|
||||
|
||||
vet:
|
||||
desc: Run go vet
|
||||
cmds:
|
||||
@@ -90,33 +90,6 @@ tasks:
|
||||
desc: Run golangci-lint
|
||||
cmds:
|
||||
- golangci-lint run ./...
|
||||
- task: lint:tools
|
||||
|
||||
lint:tools:
|
||||
desc: Run golangci-lint over the tools module
|
||||
dir: tools
|
||||
cmds:
|
||||
- golangci-lint run ./...
|
||||
|
||||
lint:playbooks:
|
||||
desc: Validate playbook bindings
|
||||
cmds:
|
||||
- go run ./cmd/archie-playbooks lint -dir ./playbooks
|
||||
|
||||
vuln:
|
||||
desc: Scan for known vulnerabilities (requires network access)
|
||||
cmds:
|
||||
- govulncheck ./...
|
||||
|
||||
deadcode:
|
||||
desc: Report unreachable production functions (advisory)
|
||||
cmds:
|
||||
- go run golang.org/x/tools/cmd/deadcode@latest -test=false ./cmd/...
|
||||
|
||||
reachaudit:
|
||||
desc: Classify unreachable code against tracked work (advisory)
|
||||
cmds:
|
||||
- python3 tools/reachaudit/reachaudit.py --repo . {{.CLI_ARGS}}
|
||||
|
||||
ui:deps:
|
||||
desc: Install dashboard dependencies
|
||||
@@ -125,45 +98,56 @@ tasks:
|
||||
run: once
|
||||
dir: ui
|
||||
cmds:
|
||||
- npm install --no-audit --no-fund
|
||||
- pnpm install --frozen-lockfile
|
||||
|
||||
ui:
|
||||
desc: Build the dashboard into ui/dist (committed; the Go build embeds it)
|
||||
desc: Build the dashboard into ui/dist, which the Go build embeds
|
||||
# check builds the dashboard and then build depends on it again; a second
|
||||
# build empties ui/dist under the Go steps that embed it.
|
||||
run: once
|
||||
dir: ui
|
||||
deps: [ui:deps]
|
||||
cmds:
|
||||
- npm run build
|
||||
|
||||
ui:check:
|
||||
desc: Rebuild the dashboard into a temporary directory and reject a stale ui/dist
|
||||
deps: [ui:deps]
|
||||
cmds:
|
||||
- bash tools/uidist.sh check
|
||||
- pnpm run build
|
||||
|
||||
test:ui:
|
||||
desc: Test and type-check the dashboard
|
||||
dir: ui
|
||||
deps: [ui:deps]
|
||||
cmds:
|
||||
- npm test
|
||||
- npm run typecheck
|
||||
|
||||
webhook:send:
|
||||
desc: Send a test event to the dashboard's capture intake (--help for kinds)
|
||||
cmds:
|
||||
- bash tools/webhook-send.sh {{.CLI_ARGS}}
|
||||
- pnpm test
|
||||
- pnpm run typecheck
|
||||
|
||||
bench:prreview:
|
||||
desc: Review or rescore the Martian benchmark (-- -review-model PROVIDER/MODEL -classification-model PROVIDER/MODEL; --help for flags)
|
||||
desc: Run the PR review benchmark on the configured models and write docs/benchmarks/pr-review-*.md (-- -model ALIAS -judge-model REF; --help for flags)
|
||||
cmds:
|
||||
- go run ./cmd/archie-prbench {{.CLI_ARGS}}
|
||||
- go run ./cmd/archied prbench {{.CLI_ARGS}}
|
||||
|
||||
dev:
|
||||
desc: Run development services and Vite at http://localhost:5173
|
||||
deps: [dev:daemon, dev:gateway, dev:state-store, dev:dashboard, dev:ui]
|
||||
deps: [dev:daemon, dev:gateway, dev:messaging, dev:state-store, dev:dashboard, dev:ui]
|
||||
|
||||
dev:tls:
|
||||
desc: Issue the development CA and service certificates deployments/dev.toml names
|
||||
status:
|
||||
- test -f tmp/dev-tls/archie-ui.pem
|
||||
cmds:
|
||||
- |
|
||||
# Task containers reach the State Store over the Docker bridge, which
|
||||
# services may only do over TLS.
|
||||
set -eu
|
||||
d=tmp/dev-tls
|
||||
mkdir -p "$d"
|
||||
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes -days 3650 \
|
||||
-subj /CN=archie-dev-ca -keyout "$d/ca-key.pem" -out "$d/ca.pem" 2>/dev/null
|
||||
for s in archied archie-gateway archie-messaging archie-state-store archie-ui; do
|
||||
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes -days 3650 \
|
||||
-subj "/CN=$s" -addext "subjectAltName=DNS:$s" -addext extendedKeyUsage=serverAuth,clientAuth \
|
||||
-CA "$d/ca.pem" -CAkey "$d/ca-key.pem" -keyout "$d/$s-key.pem" -out "$d/$s.pem" 2>/dev/null
|
||||
done
|
||||
|
||||
dev:postgres:
|
||||
desc: Start PostgreSQL and wait for readiness
|
||||
desc: Start PostgreSQL, wait for readiness, provision the database roles
|
||||
cmds:
|
||||
- docker compose up -d postgres
|
||||
- |
|
||||
@@ -177,18 +161,31 @@ tasks:
|
||||
done
|
||||
echo "postgres did not become healthy within 60s" >&2
|
||||
exit 1
|
||||
- |
|
||||
# docker-compose.yml creates the dev database with a superuser named
|
||||
# archie; provision the least-privilege roles deployments/dev.toml
|
||||
# points at. Idempotent, so this also upgrades a volume created before
|
||||
# the role split.
|
||||
go run ./cmd/archie-state-store provision \
|
||||
-admin-url "postgres://archie:archie@127.0.0.1:5432/archie?sslmode=disable" \
|
||||
-runtime-url "postgres://archie_runtime:archie@127.0.0.1:5432/archie?sslmode=disable" \
|
||||
-migration-url "postgres://archie_migrator:archie@127.0.0.1:5432/archie?sslmode=disable"
|
||||
|
||||
dev:wait-state:
|
||||
internal: true
|
||||
cmds:
|
||||
- |
|
||||
# Services read their settings from the State Store at boot and exit
|
||||
# if it is not up yet, so wait for its port ([services.state] in
|
||||
# deployments/dev.toml).
|
||||
for _ in $(seq 1 120); do nc -z 127.0.0.1 9091 && exit 0; sleep 1; done
|
||||
echo "state store did not come up on 127.0.0.1:9091 within 120s" >&2
|
||||
exit 1
|
||||
|
||||
dev:daemon:
|
||||
desc: Run archied with live reload
|
||||
cmds:
|
||||
- |
|
||||
# The daemon and Gateway read their settings from the State Store at
|
||||
# boot and exit if it is not up yet; it starts only once PostgreSQL
|
||||
# is healthy, so wait for its port ([services.state] in
|
||||
# deployments/dev.toml) first.
|
||||
for _ in $(seq 1 120); do nc -z 127.0.0.1 9091 && exit 0; sleep 1; done
|
||||
echo "state store did not come up on 127.0.0.1:9091 within 120s" >&2
|
||||
exit 1
|
||||
- task: dev:wait-state
|
||||
- air -build.args_bin="-config-overlay,deployments/dev.toml"
|
||||
|
||||
dev:dashboard:
|
||||
@@ -198,61 +195,68 @@ tasks:
|
||||
|
||||
dev:state-store:
|
||||
desc: Run the State Store with development PostgreSQL
|
||||
deps: [dev:postgres]
|
||||
deps: [dev:postgres, dev:tls]
|
||||
cmds:
|
||||
- go run ./cmd/archie-state-store -config-overlay deployments/dev.toml
|
||||
|
||||
dev:gateway:
|
||||
desc: Run the development Gateway
|
||||
cmds:
|
||||
- |
|
||||
# The daemon and Gateway read their settings from the State Store at
|
||||
# boot and exit if it is not up yet; it starts only once PostgreSQL
|
||||
# is healthy, so wait for its port ([services.state] in
|
||||
# deployments/dev.toml) first.
|
||||
for _ in $(seq 1 120); do nc -z 127.0.0.1 9091 && exit 0; sleep 1; done
|
||||
echo "state store did not come up on 127.0.0.1:9091 within 120s" >&2
|
||||
exit 1
|
||||
- task: dev:wait-state
|
||||
- go run ./cmd/archie-gateway -config-overlay deployments/dev.toml
|
||||
|
||||
dev:messaging:
|
||||
desc: Run the development Messaging Service
|
||||
cmds:
|
||||
- task: dev:wait-state
|
||||
- go run ./cmd/archie-messaging -config-overlay deployments/dev.toml
|
||||
|
||||
dev:ui:
|
||||
desc: Run Vite (requires the dashboard backend)
|
||||
dir: ui
|
||||
cmds:
|
||||
- npm install --no-audit --no-fund
|
||||
- npm run dev
|
||||
- pnpm install
|
||||
- pnpm run dev
|
||||
|
||||
dev:mobile:
|
||||
desc: Serve the dashboard on your LAN (token-protected) for phone viewing
|
||||
deps:
|
||||
- ui
|
||||
e2e:up:
|
||||
desc: Start the local stack without Docker (PostgreSQL 18, services, Vite) and seed it
|
||||
cmds:
|
||||
- cmd: |
|
||||
IP=$(hostname -I | awk '{print $1}')
|
||||
TOKEN_FILE="${XDG_DATA_HOME:-$HOME/.local/share}/archie/web-token"
|
||||
go run ./cmd/archie-ui -listen 0.0.0.0:8484 -token-file "$TOKEN_FILE" &
|
||||
UI_PID=$!
|
||||
sleep 2
|
||||
TOKEN=$(cat "$TOKEN_FILE" 2>/dev/null)
|
||||
URL="http://$IP:8484/?t=$TOKEN"
|
||||
echo "Phone URL: $URL"
|
||||
echo "$URL" | qrencode -t ANSIUTF8
|
||||
trap "kill $UI_PID 2>/dev/null" EXIT
|
||||
wait $UI_PID
|
||||
- bash e2e/stack.sh start
|
||||
- bash e2e/seed.sh
|
||||
|
||||
e2e:down:
|
||||
desc: Stop the local e2e stack
|
||||
cmds:
|
||||
- bash e2e/stack.sh stop
|
||||
|
||||
e2e:check:
|
||||
desc: List browser checks; use -- all or -- CHECK to run, add --headed to watch
|
||||
cmds:
|
||||
- node e2e/run.cjs {{.CLI_ARGS}}
|
||||
|
||||
build:
|
||||
desc: Build archie services and agent binaries
|
||||
deps: [ui]
|
||||
# Static, like the binaries a release ships, so `dist` reuses these
|
||||
# compiled packages and only links again.
|
||||
env:
|
||||
CGO_ENABLED: "0"
|
||||
vars:
|
||||
GATEWAY_VERSION: '{{.GATEWAY_VERSION | default "dev"}}'
|
||||
RUNTIME_VERSION: '{{.RUNTIME_VERSION | default "dev"}}'
|
||||
GATEWAY_VERSION: '{{.GATEWAY_VERSION | default .VERSION}}'
|
||||
RUNTIME_VERSION: '{{.RUNTIME_VERSION | default .VERSION}}'
|
||||
SERVICE_LDFLAGS: >-
|
||||
-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion={{.GATEWAY_VERSION}}
|
||||
-X github.com/samcharles93/archie-core/internal/app/archied.runtimeVersion={{.RUNTIME_VERSION}}
|
||||
-X github.com/samcharles93/archie-core/internal/installtype.buildType=binary
|
||||
-X github.com/samcharles93/archie-core/internal/buildinfo.Version={{.GATEWAY_VERSION}}
|
||||
-X github.com/samcharles93/archie-core/internal/buildinfo.Runtime={{.RUNTIME_VERSION}}
|
||||
sources:
|
||||
- Taskfile.yml
|
||||
- "**/*.go"
|
||||
# Files the binaries embed.
|
||||
- "internal/**/*.sql"
|
||||
- "internal/**/*.yaml"
|
||||
- "internal/**/*.json"
|
||||
- "internal/**/*.tpl"
|
||||
- "internal/**/*.md"
|
||||
- go.mod
|
||||
- go.sum
|
||||
- "ui/dist/**"
|
||||
@@ -263,100 +267,94 @@ tasks:
|
||||
- "{{.BIN_DIR}}/archie-ui"
|
||||
- "{{.BIN_DIR}}/archie-messaging"
|
||||
- "{{.BIN_DIR}}/archie-agent"
|
||||
- "{{.BIN_DIR}}/archie"
|
||||
cmds:
|
||||
# One flag set for every service, matching scripts/archie-update-install
|
||||
# and the release workflow, so each binary reports the same version.
|
||||
- for: [archied, archie-gateway, archie-state-store, archie-ui, archie-messaging]
|
||||
cmd: go build -ldflags "{{.SERVICE_LDFLAGS}}" -o {{.BIN_DIR}}/{{.ITEM}} ./cmd/{{.ITEM}}
|
||||
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/app/agentworker.version={{.RUNTIME_VERSION}} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-agent ./cmd/archie-agent
|
||||
# One flag set for every service, matching the release workflow, so each
|
||||
# binary reports the same version.
|
||||
- for: [archie, archied, archie-gateway, archie-state-store, archie-ui, archie-messaging]
|
||||
cmd: go build -trimpath -ldflags "{{.SERVICE_LDFLAGS}}" -o {{.BIN_DIR}}/{{.ITEM}} ./cmd/{{.ITEM}}
|
||||
- go build -trimpath -ldflags "-X github.com/samcharles93/archie-core/internal/app/agentworker.version={{.RUNTIME_VERSION}} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-agent ./cmd/archie-agent
|
||||
|
||||
dist:
|
||||
desc: Build the linux/amd64 binaries a release ships into dist/ (VERSION=1.2.3; needs jq)
|
||||
deps: [ui]
|
||||
env:
|
||||
GOOS: linux
|
||||
GOARCH: amd64
|
||||
CGO_ENABLED: "0"
|
||||
vars:
|
||||
DIST_LDFLAGS: >-
|
||||
-X github.com/samcharles93/archie-core/internal/installtype.buildType=binary
|
||||
-X github.com/samcharles93/archie-core/internal/buildinfo.Version={{.VERSION}}
|
||||
-X github.com/samcharles93/archie-core/internal/buildinfo.Runtime={{.VERSION}}
|
||||
-X github.com/samcharles93/archie-core/internal/app/agentworker.version={{.VERSION}}
|
||||
cmds:
|
||||
# release.json names what a release ships, so the zip and this build
|
||||
# cannot disagree. The compiler flags match `build`, so after the gate
|
||||
# has built bin/ this only links.
|
||||
- |
|
||||
set -eu
|
||||
mkdir -p dist
|
||||
for cmd in $(jq -r '.required_topology.units[], .required_topology.binaries[]?' release.json); do
|
||||
go build -trimpath -ldflags "{{.DIST_LDFLAGS}}" -o "dist/$cmd" "./cmd/$cmd"
|
||||
done
|
||||
|
||||
test:
|
||||
desc: Run short Go tests with caching
|
||||
desc: Run Go tests; the release gate passes TEST_FLAGS=-count=1
|
||||
cmds:
|
||||
- go test -short ./...
|
||||
- go test {{.TEST_FLAGS | default "-short"}} ./...
|
||||
|
||||
test:full:
|
||||
desc: Run the whole Go test suite uncached, including the wall-clock-bound tests
|
||||
image:agent:
|
||||
desc: Build the agent image stamped with this checkout's version
|
||||
# Compose owns the image build; this only supplies the version, which a
|
||||
# plain `docker build` has no way to learn from a context that excludes .git.
|
||||
cmds:
|
||||
- go test ./... -count=1
|
||||
|
||||
test:tools:
|
||||
desc: Run the nested tools module suite, refusing to rewrite its go.mod
|
||||
cmds:
|
||||
- go -C tools test -mod=readonly ./... -count=1
|
||||
- RUNTIME_VERSION={{.VERSION}} docker compose build agent
|
||||
|
||||
check:
|
||||
desc: Run the full quality gate
|
||||
# Finish mutations before starting parallel checks.
|
||||
cmds:
|
||||
# Node packages land under ui/, which `go test ./...` walks: installing
|
||||
# them while the parallel checks scan the tree makes a lockfile update
|
||||
# delete Go sources mid-walk. Install first, then fan out. Every Go step
|
||||
# embeds ui/dist, so the dashboard is built before any of them.
|
||||
- task: ui
|
||||
- task: fmt
|
||||
- task: proto:check
|
||||
- task: db:check
|
||||
- task: openapi:check
|
||||
- task: check:readonly
|
||||
|
||||
check:readonly:
|
||||
internal: true
|
||||
deps:
|
||||
- task: proto:lint
|
||||
- task: docs:check
|
||||
- task: docs:prds
|
||||
- task: news:check
|
||||
- task: docs:artifact:check
|
||||
- task: vet
|
||||
- task: lint
|
||||
- task: build
|
||||
- task: test
|
||||
- task: test:tools
|
||||
- task: test:ui
|
||||
- task: ui:check
|
||||
|
||||
contract:
|
||||
desc: Report contract conformance (advisory)
|
||||
cmds:
|
||||
- go -C tools run ./contractaudit --repo-root ..
|
||||
|
||||
release:preview:
|
||||
desc: "Show the release notes that would be generated (VERSION=1.2.0)"
|
||||
cmds:
|
||||
- tools/release.sh --version {{.VERSION}} --dry-run
|
||||
requires:
|
||||
vars: [VERSION]
|
||||
|
||||
release:prepare:
|
||||
desc: Prepare changelog notes for editing (VERSION=1.2.0)
|
||||
cmds:
|
||||
- tools/release.sh --version {{.VERSION}} --prepare
|
||||
requires:
|
||||
vars: [VERSION]
|
||||
|
||||
release:
|
||||
desc: Commit and tag the prepared release (VERSION=1.2.0)
|
||||
cmds:
|
||||
- tools/release.sh --version {{.VERSION}} --tag
|
||||
desc: "Tag main as a release (RELEASE=major|minor|patch|1.2.3)"
|
||||
requires:
|
||||
vars: [VERSION]
|
||||
|
||||
clean:
|
||||
desc: Remove build artifacts
|
||||
vars: [RELEASE]
|
||||
cmds:
|
||||
- rm -rf {{.BIN_DIR}}
|
||||
|
||||
docker-build:
|
||||
desc: Build the archie-agent sandbox image
|
||||
cmds:
|
||||
- docker compose build agent
|
||||
|
||||
docker-up:
|
||||
desc: Start the optional external NATS service via docker compose
|
||||
cmds:
|
||||
- docker compose up -d nats
|
||||
|
||||
docker-down:
|
||||
desc: Stop the docker compose stack
|
||||
cmds:
|
||||
- docker compose down
|
||||
|
||||
docker-logs:
|
||||
desc: Follow the NATS container logs
|
||||
cmds:
|
||||
- docker compose logs -f nats
|
||||
- |
|
||||
set -euo pipefail
|
||||
die() { echo "release: $*" >&2; exit 1; }
|
||||
[ "$(git rev-parse --abbrev-ref HEAD)" = main ] || die "releases are cut from main"
|
||||
[ -z "$(git status --porcelain)" ] || die "the working tree is dirty"
|
||||
last="$(git tag --list 'v*' --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1 || true)"
|
||||
IFS=. read -r major minor patch <<<"${last#v}"
|
||||
case "{{.RELEASE}}" in
|
||||
major) version="$((major + 1)).0.0" ;;
|
||||
minor) version="$major.$((minor + 1)).0" ;;
|
||||
patch) version="$major.$minor.$((patch + 1))" ;;
|
||||
*) version="$(echo "{{.RELEASE}}" | sed 's/^v//')" ;;
|
||||
esac
|
||||
echo "$version" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$' || die "$version is not a version"
|
||||
! git rev-parse -q --verify "refs/tags/v$version" >/dev/null || die "v$version already exists"
|
||||
git tag -a "v$version" -m "v$version"
|
||||
echo "tagged v$version"
|
||||
+334
@@ -0,0 +1,334 @@
|
||||
# Workflow definitions
|
||||
|
||||
A workflow is a YAML document: an id, what it declares to whatever starts it,
|
||||
and an ordered list of steps. Definitions are stored in the control plane's
|
||||
`workflow-definitions` resource and edited on the dashboard's Workflows page
|
||||
(the Canvas and YAML tabs edit the same document). The shipped workflows are in
|
||||
`internal/domain/workflow/shipped/`.
|
||||
|
||||
The server is the authority. It serves the step vocabulary, including each step
|
||||
type's settings schema, in the `workflow-definitions` catalog entry
|
||||
(`x-step-types`), and validates every definition when it is saved. This file
|
||||
describes that vocabulary; when they disagree, the catalog wins.
|
||||
|
||||
```yaml
|
||||
id: implement
|
||||
repository: required
|
||||
inputs:
|
||||
pr_number: {type: number, required: true}
|
||||
steps:
|
||||
- type: repo.prepare
|
||||
- id: plan
|
||||
type: agent.run
|
||||
settings:
|
||||
read_only: true
|
||||
mission: |
|
||||
Plan this change: {{ task.prompt }}
|
||||
- id: build
|
||||
type: agent.run
|
||||
settings:
|
||||
gate: repository
|
||||
mission: "Implement it following this plan: {{ steps.plan.summary }}"
|
||||
- type: repo.commit
|
||||
settings: {message: "{{ task.title }}", push: true, if_empty: complete}
|
||||
- type: repo.open-pr
|
||||
settings: {body: "{{ steps.build.summary }}"}
|
||||
```
|
||||
|
||||
## The workflow
|
||||
|
||||
| Field | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `id` | text | The workflow's name. Required, unique. |
|
||||
| `steps` | list | The steps, run in order. At least one. |
|
||||
| `repository` | `required` \| `optional` \| `none` | `required` (the default) clones the task's repository into a worktree. `optional` clones one when the run names a repository and uses a scratch workspace otherwise. `none` never clones; only steps that run without a repository may be used. |
|
||||
| `inputs` | mapping | Named, typed values whatever starts the run must supply: `{type, required}`, where type is `string`, `number`, `bool`, `object`, `array` or `any`. Steps read them as `{{ inputs.<name> }}`. |
|
||||
| `outputs` | mapping | Named, typed results the run writes once each (same shape as inputs). A required output the run never writes parks it. A calling workflow reads them. |
|
||||
| `profile` | text | The container profile (`[containers.profiles]`) the run's agents use. Resolved when the task is dispatched. |
|
||||
| `identity` | text | The identity every run acts as, whatever started it. Empty runs as the starter. |
|
||||
|
||||
## A step
|
||||
|
||||
| Field | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `type` | text | The step type (below). |
|
||||
| `id` | text | Names the step so later steps can read its result. Unique in the workflow; letters, digits, `-` and `_`. The run records the step under this name. |
|
||||
| `settings` | mapping | The step type's settings. String settings may contain references. |
|
||||
| `when` | condition | Skip the step unless the condition holds. |
|
||||
| `on_failure` | `park` \| `continue` | `park` (the default) stops the run for an operator. `continue` records the failure and moves on. |
|
||||
| `retry` | mapping | `attempts` (1 to 10) and `backoff` (a duration such as `30s`). A failed step runs again before `on_failure` applies. |
|
||||
| `parallel` | mapping | Instead of `type`: named branches, each a list of steps, run at the same time. |
|
||||
|
||||
### References
|
||||
|
||||
Any string setting may contain `{{ path }}`, replaced when the step runs:
|
||||
|
||||
| Path | Value |
|
||||
|---|---|
|
||||
| `task.title`, `task.body` | The issue or chat request. |
|
||||
| `task.prompt` | The title and body framed for an agent mission. |
|
||||
| `task.repository` | `owner/name`. |
|
||||
| `task.kind` | What the task came from, as prose: `GitHub issue` or `chat-originated task`. |
|
||||
| `task.issue`, `task.pr` | Issue and pull request numbers. |
|
||||
| `task.plan` | The plan a `workflow.approve` step handed over (an approved PRD). |
|
||||
| `task.review` | The review comments a remediation round addresses. |
|
||||
| `inputs.<name>` | A declared input; an undeclared one is refused at save. |
|
||||
| `steps.<id>.summary` | What an earlier step reported, e.g. an agent's finish summary or a gate's output. |
|
||||
| `steps.<id>.result.<field>` | A field of an earlier agent's structured result, or an output of an earlier `workflow.call` that waits. A field the agent's `result` schema or the callee's `outputs` does not declare is refused at save. |
|
||||
|
||||
Only earlier steps may be referenced; a reference to a later or unknown step is
|
||||
refused when the definition is saved. A value that does not exist at run time
|
||||
(for instance, a step that was skipped) renders empty.
|
||||
|
||||
### Conditions
|
||||
|
||||
`when` is a reference path, written without braces:
|
||||
|
||||
- `steps.assess.result.fit` holds when the value is true, a non-empty string other than `false`, or a non-zero number.
|
||||
- `!steps.assess.result.fit` holds when it does not.
|
||||
- `steps.classify.result.workflow == tdd` and `!=` compare the value as text.
|
||||
|
||||
### Parallel branches
|
||||
|
||||
```yaml
|
||||
- id: research
|
||||
parallel:
|
||||
code: [{id: code, type: agent.run, settings: {mission: ..., read_only: true}}]
|
||||
docs: [{id: docs, type: agent.run, settings: {mission: ..., read_only: true}}]
|
||||
- type: agent.run
|
||||
settings: {mission: "{{ steps.code.summary }} {{ steps.docs.summary }}"}
|
||||
```
|
||||
|
||||
Branches share one worktree, so only read-only `agent.run` and `workflow.call`
|
||||
steps may run in them. A branch sees the steps before the parallel step and its
|
||||
own earlier steps, never a sibling's. Every branch's results are visible after
|
||||
it. Parallel steps do not nest, and need at least two branches.
|
||||
|
||||
### How a run ends
|
||||
|
||||
A run ends at the first step that sets an outcome: `workflow.finish`,
|
||||
`workflow.handoff`, `workflow.approve`, `repo.open-pr`, `repo.commit` with
|
||||
`if_empty: complete`, or `review.reply`. A run that reaches the end of its steps
|
||||
completes, with the last step's summary as its detail. A step that fails parks
|
||||
the run unless it continues on failure.
|
||||
|
||||
A parked run can be retried from a top-level step instead of from the start.
|
||||
The steps before it are skipped and their results stay available to
|
||||
references. The resume point is named by the step's id (else its type), so
|
||||
give an id to any step whose type appears twice. A run with a repository
|
||||
resumes only on its pushed branch: work an earlier step did not push is not
|
||||
there.
|
||||
|
||||
## Step types
|
||||
|
||||
### `agent.run`
|
||||
|
||||
_runs without a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `extra_rules` | text | Appended to the agent system prompt. |
|
||||
| `gate` | `repository` \| `test-failure` | Hold the agent to the repository gate before it may finish; test-failure requires the tests to fail. |
|
||||
| `mission` | text | What the agent is asked to do. May reference {{ task.* }}, {{ inputs.* }} and {{ steps.<id>.* }}. |
|
||||
| `protect_tests` | bool | Write-block the repository test files. |
|
||||
| `read_only` | bool | Restrict the agent to read-only tools. |
|
||||
| `result` | mapping | A JSON Schema object the agent must return; later steps read it as steps.<id>.result. |
|
||||
| `model` | text | The model alias that runs the agent, e.g. default or fast. Empty means default. |
|
||||
|
||||
### `command.run`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `level` | `error` \| `warn` | error stops the run on a failing command; warn reports it and continues. |
|
||||
| `run` | list of mapping | The commands to run in order; the first failure ends the step. |
|
||||
|
||||
### `repo.commit`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `if_empty` | `fail` \| `skip` \| `complete` | fail stops the run, skip moves on, complete closes the issue and ends the run. |
|
||||
| `message` | text | The commit message. |
|
||||
| `push` | bool | Push the branch after committing. |
|
||||
| `reference` | `Fixes` \| `Implements` \| `Refs` | How the commit links to the task issue. |
|
||||
|
||||
Hooks never run. The commit is created by go-git, which ignores `.git/hooks`
|
||||
and `core.hooksPath`, and the agent never runs git, so `pre-commit`,
|
||||
`commit-msg` and `prepare-commit-msg` in the checkout are inert files. A
|
||||
repository whose rules live only in a hook — a formatter, a secret scanner,
|
||||
commitlint, a DCO trailer — gets a commit that does not satisfy them: the run
|
||||
reports success and the pull request fails the check afterwards. Put the same
|
||||
commands in `command.run` or the repository gate, which both run in the task
|
||||
container before this step.
|
||||
|
||||
### `repo.open-pr`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `body` | text | The pull request description. |
|
||||
| `review` | bool | Review the change first; a blocking finding parks the task instead of opening the PR. |
|
||||
|
||||
### `repo.prepare`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `branch` | `fresh` \| `task` | fresh starts a new branch from the base; task resumes the branch this task pushed. |
|
||||
|
||||
### `repo.tooling`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
No settings. It runs the repository policy's `tooling` commands, in order, in
|
||||
the task worktree — the installs a gate needs and the container does not ship
|
||||
(protoc plugins, linters, generators). A repository that declares none installs
|
||||
nothing and the step succeeds. Place it after `repo.prepare` and before any
|
||||
`gate.*` step: a failing install fails the step with the command and its output
|
||||
and says the gate did not run, so a missing toolchain is not read as a red
|
||||
repository.
|
||||
|
||||
### `gate.diff-rules`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `rules` | list of mapping | Patterns the change must not match. |
|
||||
|
||||
### `gate.repository`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `expect` | `pass` \| `test-failure` | pass requires every gate command to pass; test-failure requires the test command to fail. |
|
||||
| `repair` | bool | Let the builder fix a failing gate before the step fails. |
|
||||
|
||||
### `forge.close-issue`
|
||||
|
||||
_runs without a repository._
|
||||
|
||||
No settings.
|
||||
|
||||
### `forge.comment`
|
||||
|
||||
_runs without a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `body` | text | The comment text. |
|
||||
| `on` | `issue` \| `pr` | Comment on the issue or the pull request. Empty means issue. |
|
||||
|
||||
### `message.send`
|
||||
|
||||
_runs without a repository._
|
||||
|
||||
Sends text to one chat on a messaging channel the workflow's organisation owns,
|
||||
and a package's workflow may not send. A test run records the message instead
|
||||
of sending it.
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `channel` | text | The messaging channel to send through. |
|
||||
| `chat_id` | text | The channel's identifier for the chat. |
|
||||
| `text` | text | The message. References are filled in. |
|
||||
|
||||
A scheduled message is a schedule bound to a workflow whose only step is
|
||||
`message.send`.
|
||||
|
||||
### `workflow.approve`
|
||||
|
||||
_runs without a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `plan` | text | What the operator decides on; the next workflow reads it as task.plan. |
|
||||
| `then` | text | The workflow the task runs once approved. |
|
||||
|
||||
### `review.pr`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
No settings.
|
||||
|
||||
### `review.reply`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `body` | text | The reply to the review. |
|
||||
|
||||
### `review.start-round`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
No settings.
|
||||
|
||||
### `workflow.call`
|
||||
|
||||
_runs without a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `inputs` | mapping | Callee input names mapped to scalar literals or `inputs.<name>` references to caller inputs. |
|
||||
| `outputs` | mapping | Callee output names mapped to `outputs.<name>` references to caller outputs; requires `wait: true`. |
|
||||
| `wait` | bool | Wait for the child run to finish before continuing. |
|
||||
| `workflow` | text | The workflow to start as a child run. |
|
||||
|
||||
The step must declare an `id`: the step's id is the key of the call it starts,
|
||||
so a retry of that call site returns the child already started instead of
|
||||
starting a second one.
|
||||
|
||||
### `workflow.finish`
|
||||
|
||||
_runs without a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `detail` | text | What the operator reads about the outcome. |
|
||||
| `status` | `completed` \| `parked` \| `waiting_approval` \| `declined` | How the run ends. Empty means completed. |
|
||||
|
||||
### `workflow.handoff`
|
||||
|
||||
_runs without a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `detail` | text | Why the task was handed off. |
|
||||
| `workflow` | text | The workflow the task is requeued under. |
|
||||
|
||||
`command.run` commands are `{name, argv, expect_failure}`: `argv` is the
|
||||
program and its arguments, and `expect_failure` requires a non-zero exit.
|
||||
|
||||
`gate.diff-rules` rules are `{id, level, pattern, path, exclude_path, message}`:
|
||||
`level` (`error` blocks, `warn` reports) and `pattern` (an RE2 expression matched
|
||||
against each added line) are required; `path` and `exclude_path` are RE2
|
||||
expressions that limit which files the rule applies to.
|
||||
|
||||
## What starts a workflow
|
||||
|
||||
- **Issues**, by label: the Issue routing setting lists label to workflow rules
|
||||
(first match wins) and a default for the rest. It starts as `bug` runs
|
||||
`tdd`, `feature` runs `feasibility`, anything else runs `triage`, which
|
||||
classifies it and hands off.
|
||||
- **Event bindings**: a webhook source mapped onto a workflow and its inputs
|
||||
(Events page).
|
||||
- **Schedules**: each firing is captured on the reserved `schedule` source as
|
||||
a `Schedule fired` event (`schedule_id`, `name`, `scheduled_for`,
|
||||
`fired_at`). A schedule trigger is a binding on that source using the
|
||||
`schedule-fired` mapping, filtered to one `schedule_id`. A firing starts at
|
||||
most one task per binding.
|
||||
- **Playbooks**: a trigger (issue labels) and actions that dispatch
|
||||
workflows.
|
||||
- **Other workflows**: `workflow.call` (a child run), `workflow.handoff` (the
|
||||
same task, requeued), `workflow.approve` (once approved).
|
||||
- **By hand**: the New task form, or Run on the Workflows page.
|
||||
|
||||
The canvas Start node lists the triggers of each workflow.
|
||||
+3451
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><rect width="512" height="512" rx="112" fill="#0e0f10"/><g fill="#51a580" transform="translate(96 96) scale(13.333) translate(-0 -0)"><path d="M2 21h4l8-18h-4z"/><path d="M14.9 5.03 22 21h-4l-5.1-11.47z"/><path d="M10.47 15h3.06l1.11 2.5H9.36z"/></g></svg>
|
||||
|
After Width: | Height: | Size: 319 B |
@@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#51a580"><path d="M2 21h4l8-18h-4z"/><path d="M14.9 5.03 22 21h-4l-5.1-11.47z"/><path d="M10.47 15h3.06l1.11 2.5H9.36z"/></svg>
|
||||
|
After Width: | Height: | Size: 194 B |
@@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 630"><rect width="1200" height="630" fill="#0e0f10"/><svg x="320" y="209.6153846153846" width="560" height="150.76923076923077" viewBox="-4 21.4 312 84"><g fill="#51a580" transform="translate(-7.7555555555555555 18.56666666666667) scale(3.8777777777777778)"><path d="M2 21h4l8-18h-4z"/><path d="M14.9 5.03 22 21h-4l-5.1-11.47z"/><path d="M10.47 15h3.06l1.11 2.5H9.36z"/></g><path fill="#e8e6e1" d="M99.76 68L99.76 100L86.96 100L86.96 47.80L99.76 47.80L99.76 58.60L100.26 58.60Q100.96 55.80 102.61 53.35Q104.26 50.90 107.11 49.35Q109.96 47.80 114.06 47.80L116.86 47.80L116.86 59.90L112.86 59.90Q108.56 59.90 105.61 60.75Q102.66 61.60 101.21 63.35Q99.76 65.10 99.76 68M145.86 101.20Q134.26 101.20 128.01 93.80Q121.76 86.40 121.76 73.80Q121.76 61.30 128.01 53.95Q134.26 46.60 145.86 46.60Q153.76 46.60 158.91 50.10Q164.06 53.60 166.36 59.80L155.86 64.50Q154.96 61.20 152.46 59.05Q149.96 56.90 145.86 56.90Q140.56 56.90 137.86 60.25Q135.16 63.60 135.16 69.20L135.16 78.70Q135.16 84.10 137.86 87.50Q140.56 90.90 145.86 90.90Q150.36 90.90 152.91 88.55Q155.46 86.20 156.86 82.70L166.66 87.40Q164.16 94.30 158.81 97.75Q153.46 101.20 145.86 101.20M188.36 100L175.56 100L175.56 26L188.36 26L188.36 56.50L188.86 56.50Q190.46 52.30 193.91 49.45Q197.36 46.60 203.46 46.60Q211.46 46.60 215.81 51.95Q220.16 57.30 220.16 67L220.16 100L207.36 100L207.36 68.30Q207.36 62.80 205.36 59.95Q203.36 57.10 198.76 57.10Q196.16 57.10 193.76 58.05Q191.36 59 189.86 60.85Q188.36 62.70 188.36 65.50M239.76 40.20Q235.86 40.20 234.06 38.35Q232.26 36.50 232.26 33.80L232.26 31.80Q232.26 29 234.06 27.20Q235.86 25.40 239.76 25.40Q243.66 25.40 245.46 27.20Q247.26 29 247.26 31.80L247.26 33.80Q247.26 36.50 245.46 38.35Q243.66 40.20 239.76 40.20M246.16 100L233.36 100L233.36 47.80L246.16 47.80M280.96 101.20Q273.26 101.20 267.76 97.85Q262.26 94.50 259.31 88.35Q256.36 82.20 256.36 73.80Q256.36 65.60 259.26 59.45Q262.16 53.30 267.56 49.95Q272.96 46.60 280.56 46.60Q288.76 46.60 294.01 50.20Q299.26 53.80 301.81 59.75Q304.36 65.70 304.36 72.90L304.36 77.10L269.66 77.10L269.66 78.40Q269.66 84 272.86 87.50Q276.06 91 282.36 91Q287.06 91 290.16 88.95Q293.26 86.90 295.66 83.90L302.56 91.60Q299.36 95.90 293.81 98.55Q288.26 101.20 280.96 101.20M280.76 56.20Q277.36 56.20 274.86 57.75Q272.36 59.30 271.01 62.05Q269.66 64.80 269.66 68.40L269.66 69.20L291.06 69.20L291.06 68.30Q291.06 64.60 289.86 61.95Q288.66 59.30 286.36 57.75Q284.06 56.20 280.76 56.20"/></svg><g fill="#a8a59f" transform="translate(224.91199999999998 460.38461538461536)"><path transform="translate(0.00 0)" d="M18.70-23.73L18.70-21.22L11.15-21.22L11.15 0L8.30 0L8.30-21.22L0.75-21.22L0.75-23.73"/><path transform="translate(19.45 0)" d="M5.61 0L2.89 0L2.89-25.16L5.61-25.16L5.61-14.69L5.75-14.69Q6.39-16.18 7.57-17.07Q8.74-17.95 10.71-17.95Q13.43-17.95 15.01-16.20Q16.59-14.45 16.59-11.25L16.59 0L13.87 0L13.87-10.78Q13.87-13.12 12.87-14.31Q11.87-15.50 9.89-15.50Q8.81-15.50 7.82-15.15Q6.83-14.79 6.22-14.04Q5.61-13.29 5.61-12.17"/><path transform="translate(38.76 0)" d="M9.49 0.41Q7.11 0.41 5.34-0.73Q3.57-1.87 2.58-3.93Q1.60-5.98 1.60-8.77Q1.60-11.56 2.58-13.62Q3.57-15.67 5.34-16.81Q7.11-17.95 9.49-17.95Q11.83-17.95 13.53-16.85Q15.23-15.74 16.15-13.80Q17.07-11.87 17.07-9.38L17.07-8.09L4.45-8.09L4.45-7.28Q4.45-5 5.83-3.49Q7.21-1.97 9.66-1.97Q11.32-1.97 12.56-2.75Q13.80-3.54 14.48-5L16.42-3.60Q15.57-1.84 13.77-0.71Q11.97 0.41 9.49 0.41M9.49-15.67Q8.02-15.67 6.89-14.99Q5.75-14.31 5.10-13.11Q4.45-11.90 4.45-10.37L4.45-10.13L14.14-10.13L14.14-10.51Q14.14-12.07 13.57-13.23Q12.99-14.38 11.93-15.03Q10.88-15.67 9.49-15.67"/><path transform="translate(57.43 0)" d=""/><path transform="translate(65.45 0)" d="M17.17-2.38L17.17 0L15.64 0Q14.55 0 13.87-0.46Q13.19-0.92 12.89-1.73Q12.68-2.24 12.61-2.86L12.44-2.86Q11.90-1.26 10.56-0.42Q9.21 0.41 7.38 0.41Q4.59 0.41 3.04-1.02Q1.50-2.45 1.50-4.90Q1.50-6.56 2.31-7.70Q3.13-8.84 4.78-9.44Q6.43-10.03 8.98-10.03L12.44-10.03L12.44-11.76Q12.44-13.63 11.42-14.62Q10.40-15.61 8.30-15.61Q6.73-15.61 5.64-14.89Q4.56-14.18 3.84-12.99L2.21-14.52Q2.92-15.91 4.49-16.93Q6.05-17.95 8.43-17.95Q11.59-17.95 13.38-16.39Q15.16-14.82 15.16-12.04L15.16-2.38L17.17-2.38M12.44-5.10L12.44-7.99L8.84-7.99Q6.53-7.99 5.44-7.31Q4.35-6.63 4.35-5.34L4.35-4.62Q4.35-3.33 5.30-2.62Q6.26-1.90 7.82-1.90Q9.18-1.90 10.22-2.33Q11.25-2.75 11.85-3.49Q12.44-4.22 12.44-5.10"/><path transform="translate(83.61 0)" d="M17.68 1.94Q17.68 3.74 16.73 4.91Q15.78 6.09 13.89 6.65Q12 7.21 9.18 7.21Q6.46 7.21 4.74 6.70Q3.03 6.19 2.24 5.22Q1.46 4.25 1.46 2.89Q1.46 1.46 2.21 0.65Q2.96-0.17 4.25-0.51L4.25-0.88Q3.50-1.26 3.09-1.85Q2.69-2.45 2.69-3.33Q2.69-4.66 3.54-5.36Q4.39-6.05 5.71-6.39L5.71-6.53Q4.15-7.28 3.28-8.67Q2.41-10.06 2.41-11.90Q2.41-13.70 3.23-15.06Q4.05-16.42 5.54-17.19Q7.04-17.95 9.01-17.95Q9.96-17.95 10.79-17.78Q11.63-17.61 12.34-17.27L12.34-17.58Q12.34-18.60 12.82-19.26Q13.29-19.92 14.38-19.92L17-19.92L17-17.54L13.67-17.54L13.67-16.42Q14.62-15.61 15.15-14.45Q15.67-13.29 15.67-11.90Q15.67-Line truncated
|
||||
|
After Width: | Height: | Size: 20 KiB |
@@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="-4 21.40 312 84" role="img" aria-label="Archie"><title>Archie</title><g fill="#51a580" transform="translate(-7.7555555555555555 18.56666666666667) scale(3.8777777777777778)"><path d="M2 21h4l8-18h-4z"/><path d="M14.9 5.03 22 21h-4l-5.1-11.47z"/><path d="M10.47 15h3.06l1.11 2.5H9.36z"/></g><path fill="#e8e6e1" d="M99.76 68L99.76 100L86.96 100L86.96 47.80L99.76 47.80L99.76 58.60L100.26 58.60Q100.96 55.80 102.61 53.35Q104.26 50.90 107.11 49.35Q109.96 47.80 114.06 47.80L116.86 47.80L116.86 59.90L112.86 59.90Q108.56 59.90 105.61 60.75Q102.66 61.60 101.21 63.35Q99.76 65.10 99.76 68M145.86 101.20Q134.26 101.20 128.01 93.80Q121.76 86.40 121.76 73.80Q121.76 61.30 128.01 53.95Q134.26 46.60 145.86 46.60Q153.76 46.60 158.91 50.10Q164.06 53.60 166.36 59.80L155.86 64.50Q154.96 61.20 152.46 59.05Q149.96 56.90 145.86 56.90Q140.56 56.90 137.86 60.25Q135.16 63.60 135.16 69.20L135.16 78.70Q135.16 84.10 137.86 87.50Q140.56 90.90 145.86 90.90Q150.36 90.90 152.91 88.55Q155.46 86.20 156.86 82.70L166.66 87.40Q164.16 94.30 158.81 97.75Q153.46 101.20 145.86 101.20M188.36 100L175.56 100L175.56 26L188.36 26L188.36 56.50L188.86 56.50Q190.46 52.30 193.91 49.45Q197.36 46.60 203.46 46.60Q211.46 46.60 215.81 51.95Q220.16 57.30 220.16 67L220.16 100L207.36 100L207.36 68.30Q207.36 62.80 205.36 59.95Q203.36 57.10 198.76 57.10Q196.16 57.10 193.76 58.05Q191.36 59 189.86 60.85Q188.36 62.70 188.36 65.50M239.76 40.20Q235.86 40.20 234.06 38.35Q232.26 36.50 232.26 33.80L232.26 31.80Q232.26 29 234.06 27.20Q235.86 25.40 239.76 25.40Q243.66 25.40 245.46 27.20Q247.26 29 247.26 31.80L247.26 33.80Q247.26 36.50 245.46 38.35Q243.66 40.20 239.76 40.20M246.16 100L233.36 100L233.36 47.80L246.16 47.80M280.96 101.20Q273.26 101.20 267.76 97.85Q262.26 94.50 259.31 88.35Q256.36 82.20 256.36 73.80Q256.36 65.60 259.26 59.45Q262.16 53.30 267.56 49.95Q272.96 46.60 280.56 46.60Q288.76 46.60 294.01 50.20Q299.26 53.80 301.81 59.75Q304.36 65.70 304.36 72.90L304.36 77.10L269.66 77.10L269.66 78.40Q269.66 84 272.86 87.50Q276.06 91 282.36 91Q287.06 91 290.16 88.95Q293.26 86.90 295.66 83.90L302.56 91.60Q299.36 95.90 293.81 98.55Q288.26 101.20 280.96 101.20M280.76 56.20Q277.36 56.20 274.86 57.75Q272.36 59.30 271.01 62.05Q269.66 64.80 269.66 68.40L269.66 69.20L291.06 69.20L291.06 68.30Q291.06 64.60 289.86 61.95Q288.66 59.30 286.36 57.75Q284.06 56.20 280.76 56.20"/></svg>
|
||||
|
After Width: | Height: | Size: 2.3 KiB |
@@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="-4 21.40 312 84" role="img" aria-label="Archie"><title>Archie</title><g fill="currentColor" transform="translate(-7.7555555555555555 18.56666666666667) scale(3.8777777777777778)"><path d="M2 21h4l8-18h-4z"/><path d="M14.9 5.03 22 21h-4l-5.1-11.47z"/><path d="M10.47 15h3.06l1.11 2.5H9.36z"/></g><path fill="currentColor" d="M99.76 68L99.76 100L86.96 100L86.96 47.80L99.76 47.80L99.76 58.60L100.26 58.60Q100.96 55.80 102.61 53.35Q104.26 50.90 107.11 49.35Q109.96 47.80 114.06 47.80L116.86 47.80L116.86 59.90L112.86 59.90Q108.56 59.90 105.61 60.75Q102.66 61.60 101.21 63.35Q99.76 65.10 99.76 68M145.86 101.20Q134.26 101.20 128.01 93.80Q121.76 86.40 121.76 73.80Q121.76 61.30 128.01 53.95Q134.26 46.60 145.86 46.60Q153.76 46.60 158.91 50.10Q164.06 53.60 166.36 59.80L155.86 64.50Q154.96 61.20 152.46 59.05Q149.96 56.90 145.86 56.90Q140.56 56.90 137.86 60.25Q135.16 63.60 135.16 69.20L135.16 78.70Q135.16 84.10 137.86 87.50Q140.56 90.90 145.86 90.90Q150.36 90.90 152.91 88.55Q155.46 86.20 156.86 82.70L166.66 87.40Q164.16 94.30 158.81 97.75Q153.46 101.20 145.86 101.20M188.36 100L175.56 100L175.56 26L188.36 26L188.36 56.50L188.86 56.50Q190.46 52.30 193.91 49.45Q197.36 46.60 203.46 46.60Q211.46 46.60 215.81 51.95Q220.16 57.30 220.16 67L220.16 100L207.36 100L207.36 68.30Q207.36 62.80 205.36 59.95Q203.36 57.10 198.76 57.10Q196.16 57.10 193.76 58.05Q191.36 59 189.86 60.85Q188.36 62.70 188.36 65.50M239.76 40.20Q235.86 40.20 234.06 38.35Q232.26 36.50 232.26 33.80L232.26 31.80Q232.26 29 234.06 27.20Q235.86 25.40 239.76 25.40Q243.66 25.40 245.46 27.20Q247.26 29 247.26 31.80L247.26 33.80Q247.26 36.50 245.46 38.35Q243.66 40.20 239.76 40.20M246.16 100L233.36 100L233.36 47.80L246.16 47.80M280.96 101.20Q273.26 101.20 267.76 97.85Q262.26 94.50 259.31 88.35Q256.36 82.20 256.36 73.80Q256.36 65.60 259.26 59.45Q262.16 53.30 267.56 49.95Q272.96 46.60 280.56 46.60Q288.76 46.60 294.01 50.20Q299.26 53.80 301.81 59.75Q304.36 65.70 304.36 72.90L304.36 77.10L269.66 77.10L269.66 78.40Q269.66 84 272.86 87.50Q276.06 91 282.36 91Q287.06 91 290.16 88.95Q293.26 86.90 295.66 83.90L302.56 91.60Q299.36 95.90 293.81 98.55Q288.26 101.20 280.96 101.20M280.76 56.20Q277.36 56.20 274.86 57.75Q272.36 59.30 271.01 62.05Q269.66 64.80 269.66 68.40L269.66 69.20L291.06 69.20L291.06 68.30Q291.06 64.60 289.86 61.95Q288.66 59.30 286.36 57.75Q284.06 56.20 280.76 56.20"/></svg>
|
||||
|
After Width: | Height: | Size: 2.3 KiB |
@@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="-4 21.40 312 84" role="img" aria-label="Archie"><title>Archie</title><g fill="#51a580" transform="translate(-7.7555555555555555 18.56666666666667) scale(3.8777777777777778)"><path d="M2 21h4l8-18h-4z"/><path d="M14.9 5.03 22 21h-4l-5.1-11.47z"/><path d="M10.47 15h3.06l1.11 2.5H9.36z"/></g><path fill="#1f1f1d" d="M99.76 68L99.76 100L86.96 100L86.96 47.80L99.76 47.80L99.76 58.60L100.26 58.60Q100.96 55.80 102.61 53.35Q104.26 50.90 107.11 49.35Q109.96 47.80 114.06 47.80L116.86 47.80L116.86 59.90L112.86 59.90Q108.56 59.90 105.61 60.75Q102.66 61.60 101.21 63.35Q99.76 65.10 99.76 68M145.86 101.20Q134.26 101.20 128.01 93.80Q121.76 86.40 121.76 73.80Q121.76 61.30 128.01 53.95Q134.26 46.60 145.86 46.60Q153.76 46.60 158.91 50.10Q164.06 53.60 166.36 59.80L155.86 64.50Q154.96 61.20 152.46 59.05Q149.96 56.90 145.86 56.90Q140.56 56.90 137.86 60.25Q135.16 63.60 135.16 69.20L135.16 78.70Q135.16 84.10 137.86 87.50Q140.56 90.90 145.86 90.90Q150.36 90.90 152.91 88.55Q155.46 86.20 156.86 82.70L166.66 87.40Q164.16 94.30 158.81 97.75Q153.46 101.20 145.86 101.20M188.36 100L175.56 100L175.56 26L188.36 26L188.36 56.50L188.86 56.50Q190.46 52.30 193.91 49.45Q197.36 46.60 203.46 46.60Q211.46 46.60 215.81 51.95Q220.16 57.30 220.16 67L220.16 100L207.36 100L207.36 68.30Q207.36 62.80 205.36 59.95Q203.36 57.10 198.76 57.10Q196.16 57.10 193.76 58.05Q191.36 59 189.86 60.85Q188.36 62.70 188.36 65.50M239.76 40.20Q235.86 40.20 234.06 38.35Q232.26 36.50 232.26 33.80L232.26 31.80Q232.26 29 234.06 27.20Q235.86 25.40 239.76 25.40Q243.66 25.40 245.46 27.20Q247.26 29 247.26 31.80L247.26 33.80Q247.26 36.50 245.46 38.35Q243.66 40.20 239.76 40.20M246.16 100L233.36 100L233.36 47.80L246.16 47.80M280.96 101.20Q273.26 101.20 267.76 97.85Q262.26 94.50 259.31 88.35Q256.36 82.20 256.36 73.80Q256.36 65.60 259.26 59.45Q262.16 53.30 267.56 49.95Q272.96 46.60 280.56 46.60Q288.76 46.60 294.01 50.20Q299.26 53.80 301.81 59.75Q304.36 65.70 304.36 72.90L304.36 77.10L269.66 77.10L269.66 78.40Q269.66 84 272.86 87.50Q276.06 91 282.36 91Q287.06 91 290.16 88.95Q293.26 86.90 295.66 83.90L302.56 91.60Q299.36 95.90 293.81 98.55Q288.26 101.20 280.96 101.20M280.76 56.20Q277.36 56.20 274.86 57.75Q272.36 59.30 271.01 62.05Q269.66 64.80 269.66 68.40L269.66 69.20L291.06 69.20L291.06 68.30Q291.06 64.60 289.86 61.95Q288.66 59.30 286.36 57.75Q284.06 56.20 280.76 56.20"/></svg>
|
||||
|
After Width: | Height: | Size: 2.3 KiB |
@@ -1,110 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"go/ast"
|
||||
"go/parser"
|
||||
"go/token"
|
||||
"path/filepath"
|
||||
"strconv"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestCommandBoundary(t *testing.T) {
|
||||
paths, err := filepath.Glob("*.go")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
for _, path := range paths {
|
||||
if !strings.HasSuffix(path, "_test.go") && path != "main.go" {
|
||||
t.Errorf("cmd/archie-agent contains substantive production file %q; runtime ownership belongs in internal/app/agentworker", path)
|
||||
}
|
||||
}
|
||||
|
||||
file, err := parser.ParseFile(token.NewFileSet(), "main.go", nil, 0)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
const (
|
||||
projectInternal = "github.com/samcharles93/archie-core/internal/"
|
||||
appImport = projectInternal + "app/agentworker"
|
||||
)
|
||||
appIdent := "agentworker"
|
||||
for _, imported := range file.Imports {
|
||||
path, err := strconv.Unquote(imported.Path.Value)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if strings.HasPrefix(path, projectInternal) && path != appImport {
|
||||
t.Errorf("cmd/archie-agent imports substantive internal package %q; only %q is allowed", path, appImport)
|
||||
}
|
||||
if path == appImport && imported.Name != nil {
|
||||
if imported.Name.Name == "." || imported.Name.Name == "_" {
|
||||
t.Errorf("cmd/archie-agent imports %q with unsupported alias %q", appImport, imported.Name.Name)
|
||||
} else {
|
||||
appIdent = imported.Name.Name
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
allowedFunctions := map[string]bool{
|
||||
"main": true,
|
||||
"run": true,
|
||||
"runCommand": true,
|
||||
"natsConnectionSettings": true,
|
||||
"runRelay": true,
|
||||
"runMCP": true,
|
||||
}
|
||||
for _, declaration := range file.Decls {
|
||||
function, ok := declaration.(*ast.FuncDecl)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
if function.Recv != nil || !allowedFunctions[function.Name.Name] {
|
||||
t.Errorf("cmd/archie-agent main.go declares unexpected function %q; orchestration belongs in internal/app/agentworker", function.Name.Name)
|
||||
}
|
||||
delete(allowedFunctions, function.Name.Name)
|
||||
}
|
||||
for name := range allowedFunctions {
|
||||
t.Errorf("cmd/archie-agent main.go is missing intended process function %q", name)
|
||||
}
|
||||
|
||||
var runFunction *ast.FuncDecl
|
||||
for _, declaration := range file.Decls {
|
||||
function, ok := declaration.(*ast.FuncDecl)
|
||||
if ok && function.Name.Name == "run" {
|
||||
runFunction = function
|
||||
break
|
||||
}
|
||||
}
|
||||
if runFunction == nil {
|
||||
t.Fatal("cmd/archie-agent has no run function")
|
||||
}
|
||||
|
||||
workerCalls := 0
|
||||
ast.Inspect(runFunction.Body, func(node ast.Node) bool {
|
||||
call, ok := node.(*ast.CallExpr)
|
||||
if !ok {
|
||||
return true
|
||||
}
|
||||
callee, ok := call.Fun.(*ast.Ident)
|
||||
if !ok || callee.Name != "runCommand" {
|
||||
return true
|
||||
}
|
||||
for _, argument := range call.Args {
|
||||
selector, ok := argument.(*ast.SelectorExpr)
|
||||
if !ok || selector.Sel.Name != "Run" {
|
||||
continue
|
||||
}
|
||||
pkg, ok := selector.X.(*ast.Ident)
|
||||
if ok && pkg.Name == appIdent {
|
||||
workerCalls++
|
||||
}
|
||||
}
|
||||
return true
|
||||
})
|
||||
if workerCalls != 1 {
|
||||
t.Fatalf("cmd/archie-agent run passes agentworker.Run to runCommand %d times, want exactly 1", workerCalls)
|
||||
}
|
||||
}
|
||||
+29
-47
@@ -3,6 +3,7 @@ package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/base64"
|
||||
"errors"
|
||||
"flag"
|
||||
"fmt"
|
||||
@@ -15,6 +16,8 @@ import (
|
||||
"syscall"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/app/agentworker"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/egress"
|
||||
"github.com/samcharles93/archie-core/internal/logging"
|
||||
)
|
||||
|
||||
type workerRunner func(context.Context, agentworker.Settings, *slog.Logger) error
|
||||
@@ -31,29 +34,36 @@ func runCommand(args []string, getenv func(string) string, stderr io.Writer, run
|
||||
if len(args) > 0 && args[0] == "relay" {
|
||||
return runRelay(args[1:], stderr, agentworker.RunRelay)
|
||||
}
|
||||
if len(args) > 0 && args[0] == "mcp" {
|
||||
return runMCP(args[1:], stderr, agentworker.RunCaptureMCP)
|
||||
}
|
||||
flags := flag.NewFlagSet("archie-agent", flag.ContinueOnError)
|
||||
flags.SetOutput(stderr)
|
||||
natsURLFlag := flags.String("nats-url", "", "NATS server URL (defaults to NATS_URL)")
|
||||
stateStoreURLFlag := flags.String("state-store-url", "", "State Store gRPC target (defaults to STATE_STORE_URL; required -- the legacy NATS storerpc path is deleted)")
|
||||
stateStoreTokenFlag := flags.String("state-store-token", "", "State Store bearer token (defaults to STATE_STORE_TOKEN)")
|
||||
showVersion := flags.Bool("version", false, "print the version and exit")
|
||||
if err := flags.Parse(args); err != nil {
|
||||
if errors.Is(err, flag.ErrHelp) {
|
||||
return 0
|
||||
}
|
||||
return 2
|
||||
}
|
||||
// The release and its updater read this line to prove a shipped
|
||||
// archie-agent belongs to the release being installed.
|
||||
if *showVersion {
|
||||
fmt.Printf("archie-agent %s\n", agentworker.Version())
|
||||
return 0
|
||||
}
|
||||
|
||||
natsURL, natsToken := natsConnectionSettings(*natsURLFlag, getenv)
|
||||
natsURL := *natsURLFlag
|
||||
if natsURL == "" {
|
||||
fmt.Fprintln(stderr, "error: -nats-url or NATS_URL is required")
|
||||
natsURL = getenv("NATS_URL")
|
||||
}
|
||||
if natsURL == "" {
|
||||
_, _ = fmt.Fprintln(stderr, "error: -nats-url or NATS_URL is required")
|
||||
flags.Usage()
|
||||
return 1
|
||||
}
|
||||
|
||||
log := slog.New(slog.NewJSONHandler(stderr, nil))
|
||||
log := slog.New(logging.WithTrace(slog.NewJSONHandler(stderr, nil)))
|
||||
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
|
||||
defer stop()
|
||||
|
||||
@@ -62,7 +72,7 @@ func runCommand(args []string, getenv func(string) string, stderr io.Writer, run
|
||||
stateStoreURL = getenv("STATE_STORE_URL")
|
||||
}
|
||||
if stateStoreURL == "" {
|
||||
fmt.Fprintln(stderr, "error: -state-store-url or STATE_STORE_URL is required (the legacy NATS storerpc path is deleted)")
|
||||
_, _ = fmt.Fprintln(stderr, "error: -state-store-url or STATE_STORE_URL is required (the legacy NATS storerpc path is deleted)")
|
||||
flags.Usage()
|
||||
return 1
|
||||
}
|
||||
@@ -71,25 +81,26 @@ func runCommand(args []string, getenv func(string) string, stderr io.Writer, run
|
||||
stateStoreToken = getenv("STATE_STORE_TOKEN")
|
||||
}
|
||||
|
||||
stateStoreCA, err := base64.StdEncoding.DecodeString(getenv("STATE_STORE_CA_BASE64"))
|
||||
if err != nil {
|
||||
_, _ = fmt.Fprintf(stderr, "error: STATE_STORE_CA_BASE64: %v\n", err)
|
||||
return 1
|
||||
}
|
||||
|
||||
if err := runWorker(ctx, agentworker.Settings{
|
||||
NATSURL: natsURL,
|
||||
NATSToken: natsToken,
|
||||
StateStoreTarget: stateStoreURL,
|
||||
StateStoreToken: stateStoreToken,
|
||||
StateStoreCA: stateStoreCA,
|
||||
ModelProxy: getenv(egress.ModelProxyEnv),
|
||||
ModelProxyHosts: egress.ParseHosts(getenv(egress.ModelProxyHostsEnv)),
|
||||
ModelProxyCA: getenv(egress.ModelProxyCAEnv),
|
||||
}, log); err != nil {
|
||||
return 1
|
||||
}
|
||||
return 0
|
||||
}
|
||||
|
||||
func natsConnectionSettings(flagURL string, getenv func(string) string) (url, token string) {
|
||||
url = flagURL
|
||||
if url == "" {
|
||||
url = getenv("NATS_URL")
|
||||
}
|
||||
return url, getenv("NATS_TOKEN")
|
||||
}
|
||||
|
||||
type relayServer func(ctx context.Context, forwards map[string]string) error
|
||||
|
||||
// runRelay is the sandbox egress relay: the container on both a sandbox's
|
||||
@@ -123,43 +134,14 @@ func runRelay(args []string, stderr io.Writer, serve relayServer) int {
|
||||
return 2
|
||||
}
|
||||
if len(forwards) == 0 {
|
||||
fmt.Fprintln(stderr, "error: at least one -forward is required")
|
||||
_, _ = fmt.Fprintln(stderr, "error: at least one -forward is required")
|
||||
flags.Usage()
|
||||
return 1
|
||||
}
|
||||
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
|
||||
defer stop()
|
||||
if err := serve(ctx, forwards); err != nil {
|
||||
fmt.Fprintln(stderr, "error:", err)
|
||||
return 1
|
||||
}
|
||||
return 0
|
||||
}
|
||||
|
||||
type mcpServer func(ctx context.Context, specPath, capturesPath string) error
|
||||
|
||||
// runMCP serves a stage's capture tools to a harness over stdio. The
|
||||
// harness starts it, so it runs as the harness user and holds no secrets.
|
||||
func runMCP(args []string, stderr io.Writer, serve mcpServer) int {
|
||||
flags := flag.NewFlagSet("archie-agent mcp", flag.ContinueOnError)
|
||||
flags.SetOutput(stderr)
|
||||
spec := flags.String("spec", "", "JSON file listing the stage's capture tools")
|
||||
captures := flags.String("captures", "", "file accepted capture calls are appended to")
|
||||
if err := flags.Parse(args); err != nil {
|
||||
if errors.Is(err, flag.ErrHelp) {
|
||||
return 0
|
||||
}
|
||||
return 2
|
||||
}
|
||||
if *spec == "" || *captures == "" {
|
||||
fmt.Fprintln(stderr, "error: -spec and -captures are required")
|
||||
flags.Usage()
|
||||
return 1
|
||||
}
|
||||
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
|
||||
defer stop()
|
||||
if err := serve(ctx, *spec, *captures); err != nil {
|
||||
fmt.Fprintln(stderr, "error:", err)
|
||||
_, _ = fmt.Fprintln(stderr, "error:", err)
|
||||
return 1
|
||||
}
|
||||
return 0
|
||||
|
||||
@@ -1,54 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"maps"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestRunRelay(t *testing.T) {
|
||||
noServe := func(t *testing.T) relayServer {
|
||||
return func(context.Context, map[string]string) error {
|
||||
t.Error("the relay served despite a usage error")
|
||||
return nil
|
||||
}
|
||||
}
|
||||
for name, args := range map[string][]string{
|
||||
"no forward": {},
|
||||
"a forward with no =": {"-forward", "127.0.0.1:0"},
|
||||
"a forward with no port": {"-forward", "=172.17.0.1:3129"},
|
||||
"one listen address used": {"-forward", ":3128=a:1", "-forward", ":3128=b:2"},
|
||||
} {
|
||||
t.Run(name+" is a usage error", func(t *testing.T) {
|
||||
var stderr bytes.Buffer
|
||||
if code := runRelay(args, &stderr, noServe(t)); code == 0 {
|
||||
t.Fatalf("exit 0, want a usage error; stderr %q", stderr.String())
|
||||
}
|
||||
})
|
||||
}
|
||||
t.Run("every forward is served", func(t *testing.T) {
|
||||
var got map[string]string
|
||||
serve := func(_ context.Context, forwards map[string]string) error {
|
||||
got = forwards
|
||||
return nil
|
||||
}
|
||||
args := []string{"-forward", ":3128=172.17.0.1:3129", "-forward", ":4222=172.17.0.1:4222"}
|
||||
if code := runRelay(args, &bytes.Buffer{}, serve); code != 0 {
|
||||
t.Fatalf("exit %d, want 0", code)
|
||||
}
|
||||
want := map[string]string{":3128": "172.17.0.1:3129", ":4222": "172.17.0.1:4222"}
|
||||
if !maps.Equal(got, want) {
|
||||
t.Fatalf("served %v, want %v", got, want)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
func TestRelaySubcommandRoutes(t *testing.T) {
|
||||
var stderr bytes.Buffer
|
||||
code := runCommand([]string{"relay"}, func(string) string { return "" }, &stderr, nil)
|
||||
if code != 1 || !strings.Contains(stderr.String(), "-forward") {
|
||||
t.Fatalf("relay subcommand exit %d stderr %q; want the relay's own usage error", code, stderr.String())
|
||||
}
|
||||
}
|
||||
@@ -1,134 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"errors"
|
||||
"log/slog"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/app/agentworker"
|
||||
)
|
||||
|
||||
func TestRunCommandPreservesCLIExitSemantics(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
args []string
|
||||
getenv func(string) string
|
||||
worker workerRunner
|
||||
wantCode int
|
||||
}{
|
||||
{name: "help", args: []string{"-h"}},
|
||||
{name: "flag parse error", args: []string{"-unknown"}, wantCode: 2},
|
||||
{name: "removed consumer flag", args: []string{"-consumer", "legacy"}, wantCode: 2},
|
||||
{name: "missing NATS URL", wantCode: 1},
|
||||
{name: "missing state store URL", args: []string{"-nats-url", "nats://test"}, wantCode: 1},
|
||||
{
|
||||
name: "worker failure",
|
||||
args: []string{"-nats-url", "nats://test", "-state-store-url", "127.0.0.1:9090"},
|
||||
worker: func(context.Context, agentworker.Settings, *slog.Logger) error {
|
||||
return errors.New("worker failed")
|
||||
},
|
||||
wantCode: 1,
|
||||
},
|
||||
{
|
||||
name: "success",
|
||||
args: []string{"-nats-url", "nats://test", "-state-store-url", "127.0.0.1:9090"},
|
||||
worker: func(context.Context, agentworker.Settings, *slog.Logger) error {
|
||||
return nil
|
||||
},
|
||||
},
|
||||
}
|
||||
for _, test := range tests {
|
||||
t.Run(test.name, func(t *testing.T) {
|
||||
getenv := test.getenv
|
||||
if getenv == nil {
|
||||
getenv = func(string) string { return "" }
|
||||
}
|
||||
worker := test.worker
|
||||
if worker == nil {
|
||||
worker = func(context.Context, agentworker.Settings, *slog.Logger) error {
|
||||
t.Fatal("worker called")
|
||||
return nil
|
||||
}
|
||||
}
|
||||
if got := runCommand(test.args, getenv, &bytes.Buffer{}, worker); got != test.wantCode {
|
||||
t.Fatalf("runCommand() = %d, want %d", got, test.wantCode)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestRunCommandRequiresNATSURL(t *testing.T) {
|
||||
var stderr bytes.Buffer
|
||||
called := false
|
||||
code := runCommand(nil, func(string) string { return "" }, &stderr, func(context.Context, agentworker.Settings, *slog.Logger) error {
|
||||
called = true
|
||||
return nil
|
||||
})
|
||||
if code != 1 || called {
|
||||
t.Fatalf("(code, worker called) = (%d, %v), want (1, false)", code, called)
|
||||
}
|
||||
for _, want := range []string{"error: -nats-url or NATS_URL is required", "Usage of archie-agent:"} {
|
||||
if !strings.Contains(stderr.String(), want) {
|
||||
t.Fatalf("stderr %q does not contain %q", stderr.String(), want)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestRunCommandMapsWorkerOutcomeToExitStatus(t *testing.T) {
|
||||
workerErr := errors.New("startup failed")
|
||||
tests := []struct {
|
||||
name string
|
||||
workerErr error
|
||||
wantCode int
|
||||
}{
|
||||
{name: "success"},
|
||||
{name: "worker failure", workerErr: workerErr, wantCode: 1},
|
||||
}
|
||||
for _, test := range tests {
|
||||
t.Run(test.name, func(t *testing.T) {
|
||||
var stderr bytes.Buffer
|
||||
code := runCommand([]string{"-nats-url", "nats://flag"}, func(string) string { return "token" }, &stderr, func(_ context.Context, settings agentworker.Settings, _ *slog.Logger) error {
|
||||
if settings.NATSURL != "nats://flag" || settings.NATSToken != "token" {
|
||||
t.Fatalf("settings = %#v", settings)
|
||||
}
|
||||
return test.workerErr
|
||||
})
|
||||
if code != test.wantCode {
|
||||
t.Fatalf("code = %d, want %d", code, test.wantCode)
|
||||
}
|
||||
if test.workerErr != nil && stderr.Len() != 0 {
|
||||
t.Fatalf("stderr = %q, want command not to duplicate application logging", stderr.String())
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestNATSConnectionSettings(t *testing.T) {
|
||||
getenv := func(name string) string {
|
||||
switch name {
|
||||
case "NATS_URL":
|
||||
return "nats://nats.example:4222"
|
||||
case "NATS_TOKEN":
|
||||
return "test-nats-token"
|
||||
default:
|
||||
return ""
|
||||
}
|
||||
}
|
||||
|
||||
t.Run("container environment", func(t *testing.T) {
|
||||
url, token := natsConnectionSettings("", getenv)
|
||||
if url != "nats://nats.example:4222" || token != "test-nats-token" {
|
||||
t.Fatalf("natsConnectionSettings() = (%q, %q)", url, token)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("flag URL takes precedence", func(t *testing.T) {
|
||||
url, token := natsConnectionSettings("nats://flag.example:4222", getenv)
|
||||
if url != "nats://flag.example:4222" || token != "test-nats-token" {
|
||||
t.Fatalf("natsConnectionSettings() = (%q, %q)", url, token)
|
||||
}
|
||||
})
|
||||
}
|
||||
@@ -9,7 +9,7 @@ import (
|
||||
"os/signal"
|
||||
"syscall"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/app/archied"
|
||||
"github.com/samcharles93/archie-core/internal/app/archiegateway"
|
||||
"github.com/samcharles93/archie-core/internal/buildinfo"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
|
||||
)
|
||||
@@ -17,17 +17,16 @@ import (
|
||||
func main() { os.Exit(run()) }
|
||||
|
||||
func run() int {
|
||||
var options archied.GatewayOptions
|
||||
var options archiegateway.Options
|
||||
showVersion := buildinfo.RegisterVersionFlag("archie-gateway")
|
||||
flag.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory")
|
||||
flag.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory")
|
||||
flag.StringVar(&options.Listen, "listen", "", "gateway gRPC listen address (defaults to [services.gateway].listen, else 127.0.0.1:8585)")
|
||||
flag.StringVar(&options.Token, "token", "", "Bearer [REDACTED] required for a non-loopback listener (defaults to [services.gateway].target_token)")
|
||||
flag.Parse()
|
||||
showVersion()
|
||||
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
|
||||
defer stop()
|
||||
if err := archied.RunGateway(ctx, options); err != nil {
|
||||
if err := archiegateway.Run(ctx, options); err != nil {
|
||||
fmt.Fprintln(os.Stderr, err)
|
||||
return 1
|
||||
}
|
||||
|
||||
@@ -1,163 +0,0 @@
|
||||
// This file enforces the objective half of the Messaging Service deletion gate
|
||||
// (docs/prds/messaging-service-boundary.md, "Deletion Gate and Verification"): the
|
||||
// linked binary carries no state-store, daemon, workflow, forge, gateway or
|
||||
// dashboard runtime. Go imports are atomic, so a single reference to a type living
|
||||
// beside a runtime relinks the runtime, and the severance holds only while
|
||||
// something re-measures it. That is exactly how this package came to link the
|
||||
// SQLite driver, the workflow engine and agentexec through one import of
|
||||
// internal/app/controlplane (archie-core-1ng1).
|
||||
|
||||
package main
|
||||
|
||||
import (
|
||||
"os/exec"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
const modulePath = "github.com/samcharles93/archie-core/"
|
||||
|
||||
// bannedCategory is one class of runtime the Messaging Service must not link.
|
||||
// The names are the PRD's wording; the prefixes are how that class appears in
|
||||
// this module.
|
||||
type bannedCategory struct {
|
||||
name string
|
||||
prefixes []string
|
||||
}
|
||||
|
||||
// deletionGate is the PRD's list, one entry per category it names. Two deliberate
|
||||
// absences:
|
||||
//
|
||||
// - internal/channels is NOT here. The Messaging Service hosts those adapters;
|
||||
// it is the process they live in, not a consumer of them.
|
||||
// - internal/gatewayrpc needs no exception. It is the Gateway's contract, not
|
||||
// its runtime, and it does not sit under the internal/gateway prefix -- the
|
||||
// check below would catch it if it ever did.
|
||||
var deletionGate = []bannedCategory{
|
||||
{"state store", []string{
|
||||
"modernc.org/sqlite",
|
||||
"github.com/jackc/pgx",
|
||||
modulePath + "internal/infrastructure/postgres",
|
||||
}},
|
||||
{"daemon runtime", []string{
|
||||
modulePath + "internal/daemon",
|
||||
modulePath + "internal/app/archied",
|
||||
modulePath + "internal/container",
|
||||
modulePath + "internal/worktree",
|
||||
}},
|
||||
{"workflow engine", []string{
|
||||
modulePath + "internal/domain/workflow",
|
||||
modulePath + "internal/agentexec",
|
||||
modulePath + "internal/taskrun",
|
||||
}},
|
||||
{"forge client", []string{
|
||||
modulePath + "internal/forge",
|
||||
modulePath + "internal/forgerpc",
|
||||
}},
|
||||
{"gateway runtime", []string{
|
||||
modulePath + "internal/gateway",
|
||||
}},
|
||||
// The PRD names "Direct LLM providers, model runtimes" among what the
|
||||
// Messaging Service must not own or link. These are the in-module
|
||||
// infrastructure packages that construct one; building either here means
|
||||
// a model-provider credential is in the messaging process.
|
||||
{"model providers", []string{
|
||||
modulePath + "internal/infrastructure/transcription",
|
||||
modulePath + "internal/infrastructure/embedding",
|
||||
}},
|
||||
{"dashboard", []string{
|
||||
modulePath + "internal/webui",
|
||||
}},
|
||||
}
|
||||
|
||||
// gateExceptions are packages under a banned prefix that carry only contract,
|
||||
// vocabulary or view types, so linking them is the intended end state rather
|
||||
// than a tolerated leak. internal/domain/workflow/task is the Task status and
|
||||
// view vocabulary the Messaging Service renders; its own dependency set holds
|
||||
// none of the banned runtimes, which is what makes the exception defensible
|
||||
// rather than a hole. cmd/archie-ui/architecture_test.go carries the same entry
|
||||
// for the same reason.
|
||||
//
|
||||
// Each one must stay linked: an exception nothing needs any more is a hole in
|
||||
// the fence, so this list is checked in both directions.
|
||||
var gateExceptions = []string{
|
||||
modulePath + "internal/domain/workflow/task",
|
||||
}
|
||||
|
||||
// under reports whether importPath is prefix or a package below it.
|
||||
func under(importPath, prefix string) bool {
|
||||
return importPath == prefix || strings.HasPrefix(importPath, prefix+"/")
|
||||
}
|
||||
|
||||
func TestMessagingProcessLinksNoRuntimeItOnlyDials(t *testing.T) {
|
||||
listed, err := exec.CommandContext(t.Context(), "go", "list", "-deps", ".").CombinedOutput()
|
||||
if err != nil {
|
||||
t.Fatalf("go list -deps .: %v\n%s", err, listed)
|
||||
}
|
||||
|
||||
linked := make(map[string]bool, len(gateExceptions))
|
||||
for importPath := range strings.FieldsSeq(string(listed)) {
|
||||
if excepted(importPath, linked) {
|
||||
continue
|
||||
}
|
||||
if category, banned := bannedLink(importPath); banned {
|
||||
t.Errorf("archie-messaging links %s (%s); the Messaging Service reaches that capability over a contract, never in-process (docs/prds/messaging-service-boundary.md, deletion gate)", importPath, category)
|
||||
}
|
||||
}
|
||||
for _, exception := range gateExceptions {
|
||||
if !linked[exception] {
|
||||
t.Errorf("%s is excepted from the deletion gate but is no longer linked; drop the exception instead of leaving its prefix open", exception)
|
||||
}
|
||||
}
|
||||
// A gate that cannot fail, and a `go list` that returns nothing usable, both
|
||||
// read as a pass. This pins the one thing the loop above assumes.
|
||||
if !strings.Contains(string(listed), modulePath+"cmd/archie-messaging") {
|
||||
t.Fatal("go list -deps returned a list that does not even name this package: the gate asserted nothing")
|
||||
}
|
||||
}
|
||||
|
||||
// bannedLink reports the deletion-gate category importPath falls under, or
|
||||
// ("", false). Classifying a single package is the rule the unit test below
|
||||
// pins, so the gate can be exercised without a live `go list`.
|
||||
func bannedLink(importPath string) (category string, banned bool) {
|
||||
for _, c := range deletionGate {
|
||||
for _, prefix := range c.prefixes {
|
||||
if under(importPath, prefix) {
|
||||
return c.name, true
|
||||
}
|
||||
}
|
||||
}
|
||||
return "", false
|
||||
}
|
||||
|
||||
// TestDeletionGateBansModelProviderCapabilities pins the PRD category that the
|
||||
// voice-transcription violation slipped past: the link gate would not flag
|
||||
// anything merely because the process built an LLM client, so the capability
|
||||
// packages are named explicitly. gatewayrpc is checked as the negative, since
|
||||
// it is the permitted contract and must not be swept up by the internal/
|
||||
// infrastructure/ prefix.
|
||||
func TestDeletionGateBansModelProviderCapabilities(t *testing.T) {
|
||||
for _, pkg := range []string{
|
||||
modulePath + "internal/infrastructure/transcription",
|
||||
modulePath + "internal/infrastructure/embedding",
|
||||
} {
|
||||
if _, banned := bannedLink(pkg); !banned {
|
||||
t.Errorf("bannedLink(%q) = not banned; the Messaging Service must not construct a model-provider capability in-process", pkg)
|
||||
}
|
||||
}
|
||||
if category, banned := bannedLink(modulePath + "internal/infrastructure/gatewayrpc"); banned {
|
||||
t.Errorf("bannedLink(gatewayrpc) = %q; the Gateway contract is permitted", category)
|
||||
}
|
||||
}
|
||||
|
||||
// excepted reports whether importPath sits under an excepted package, recording
|
||||
// the ones actually linked so a stale exception fails.
|
||||
func excepted(importPath string, linked map[string]bool) bool {
|
||||
for _, exception := range gateExceptions {
|
||||
if under(importPath, exception) {
|
||||
linked[exception] = true
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
@@ -1,433 +0,0 @@
|
||||
// The link gate in architecture_test.go measures which packages the Messaging
|
||||
// binary links. It cannot see a process that links nothing new but still reads
|
||||
// a decoded configuration value it is not allowed to own -- which is exactly
|
||||
// how voice transcription was wired into the Messaging Service while a green
|
||||
// link gate watched: internal/app/archiemessaging/config.go built an LLM
|
||||
// transcriber from [models].transcription and [providers.*], both of which
|
||||
// docs/prds/messaging-service-boundary.md reserves to the model-owning process.
|
||||
//
|
||||
// This file closes that shape of hole: it scans the Messaging Service's own
|
||||
// production sources for a read of a top-level config section the PRD forbids,
|
||||
// so re-adding the projection field fails here rather than shipping green.
|
||||
|
||||
package main
|
||||
|
||||
import (
|
||||
"go/ast"
|
||||
"go/parser"
|
||||
"go/token"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// messagingAppDir is the Messaging Service's application package, relative to
|
||||
// this package's directory (go test runs with the package dir as cwd).
|
||||
const messagingAppDir = "../../internal/app/archiemessaging"
|
||||
|
||||
// bannedConfigFields are the top-level config.Config fields the Messaging
|
||||
// Service must never read, by Go field name. The PRD's "Configuration
|
||||
// Ownership" section permits [chat.*], [services.*], [secrets] and the
|
||||
// path/identity keys the process needs to locate itself; every entry here is a
|
||||
// capability another process owns. internal/config's field names are the
|
||||
// concrete keys, because that is what a Go read names.
|
||||
var bannedConfigFields = map[string]bool{
|
||||
"Forge": true, // [forge]
|
||||
"Repos": true, // [repos]
|
||||
"Models": true, // [models]
|
||||
"Providers": true, // [providers]
|
||||
"Containers": true, // [containers]
|
||||
"NATS": true, // [nats]
|
||||
// [runners] has no top-level field in internal/config today; if one is
|
||||
// added its own name must be listed here with it.
|
||||
}
|
||||
|
||||
// configReadOffenders returns the banned "<holder>.<Field>" config reads in
|
||||
// src, in source order. A holder is anything the file gives the
|
||||
// internal/config.Config type: an explicitly typed parameter, var, receiver or
|
||||
// struct field, a short variable declaration or inferred var whose right-hand
|
||||
// side resolves to one ("cfg := doc.Config"), or a range variable over a slice
|
||||
// of them. The type is tracked by name because a name is what a Go read
|
||||
// selects on. A config value returned by a call this file does not declare is
|
||||
// outside a syntactic rule and stays untracked.
|
||||
func configReadOffenders(src []byte) []string {
|
||||
fset := token.NewFileSet()
|
||||
file, err := parser.ParseFile(fset, "config.go", src, parser.SkipObjectResolution)
|
||||
if err != nil {
|
||||
// A file that does not parse is reported as an offender rather than
|
||||
// ignored: silently skipping it would make this gate blind exactly
|
||||
// when the tree is broken.
|
||||
return []string{"parse error: " + err.Error()}
|
||||
}
|
||||
kinds := configKinds(file)
|
||||
|
||||
var offenders []string
|
||||
ast.Inspect(file, func(n ast.Node) bool {
|
||||
sel, ok := n.(*ast.SelectorExpr)
|
||||
if !ok || !bannedConfigFields[sel.Sel.Name] {
|
||||
return true
|
||||
}
|
||||
switch base := sel.X.(type) {
|
||||
case *ast.Ident:
|
||||
if kinds[base.Name] == configValue {
|
||||
offenders = append(offenders, base.Name+"."+sel.Sel.Name)
|
||||
}
|
||||
case *ast.SelectorExpr:
|
||||
// doc.Config, or the config-typed struct field h.cfg. Config is
|
||||
// named by configuration.Document in another package, so it
|
||||
// cannot come out of the kinds map; treat a selected Config as
|
||||
// a config holder unconditionally.
|
||||
if base.Sel.Name == "Config" || kinds[base.Sel.Name] == configValue {
|
||||
offenders = append(offenders, base.Sel.Name+"."+sel.Sel.Name)
|
||||
}
|
||||
}
|
||||
return true
|
||||
})
|
||||
return offenders
|
||||
}
|
||||
|
||||
// configKind is how an identifier or expression reaches a config.Config value.
|
||||
type configKind int
|
||||
|
||||
const (
|
||||
notConfig configKind = iota // not a config value
|
||||
configValue // config.Config
|
||||
configSlice // []config.Config, [N]config.Config or map[K]config.Config
|
||||
)
|
||||
|
||||
// configKinds resolves the identifiers in file that hold a config.Config, in
|
||||
// two passes because an inferred holder's source must be classified before the
|
||||
// holder's own name can be.
|
||||
func configKinds(file *ast.File) map[string]configKind {
|
||||
kinds := map[string]configKind{}
|
||||
ast.Inspect(file, func(n ast.Node) bool {
|
||||
switch node := n.(type) {
|
||||
case *ast.FuncDecl:
|
||||
classifyFields(node.Recv, kinds)
|
||||
classifyFields(node.Type.Params, kinds)
|
||||
case *ast.ValueSpec:
|
||||
classifyNames(node.Type, node.Names, kinds)
|
||||
case *ast.StructType:
|
||||
for _, field := range node.Fields.List {
|
||||
classifyNames(field.Type, field.Names, kinds)
|
||||
}
|
||||
}
|
||||
return true
|
||||
})
|
||||
// Inferred holders: a single source-order pass suffices because Go
|
||||
// requires a name to be declared before it is referenced.
|
||||
ast.Inspect(file, func(n ast.Node) bool {
|
||||
switch node := n.(type) {
|
||||
case *ast.AssignStmt:
|
||||
if node.Tok != token.DEFINE {
|
||||
return true
|
||||
}
|
||||
classifyValues(node.Lhs, node.Rhs, kinds)
|
||||
case *ast.ValueSpec:
|
||||
// An explicit type was handled above; here only "var cfg =
|
||||
// doc.Config", which infers the same way a := does.
|
||||
if node.Type != nil {
|
||||
return true
|
||||
}
|
||||
names := make([]ast.Expr, len(node.Names))
|
||||
for i, name := range node.Names {
|
||||
names[i] = name
|
||||
}
|
||||
classifyValues(names, node.Values, kinds)
|
||||
case *ast.RangeStmt:
|
||||
if exprKind(node.X, kinds) != configSlice {
|
||||
return true
|
||||
}
|
||||
if id, ok := node.Value.(*ast.Ident); ok {
|
||||
kinds[id.Name] = configValue
|
||||
}
|
||||
}
|
||||
return true
|
||||
})
|
||||
return kinds
|
||||
}
|
||||
|
||||
// classifyValues records each lhs identifier that resolves to a config kind of
|
||||
// the rhs expression in the same position. A shorter lhs or rhs is fine;
|
||||
// position is what pairs a name with its value.
|
||||
func classifyValues(lhs, rhs []ast.Expr, kinds map[string]configKind) {
|
||||
for i, target := range lhs {
|
||||
if i >= len(rhs) {
|
||||
return
|
||||
}
|
||||
id, ok := target.(*ast.Ident)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
if kind := exprKind(rhs[i], kinds); kind != notConfig {
|
||||
kinds[id.Name] = kind
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// classifyFields records every named field in fields whose type holds a
|
||||
// config.Config.
|
||||
func classifyFields(fields *ast.FieldList, kinds map[string]configKind) {
|
||||
if fields == nil {
|
||||
return
|
||||
}
|
||||
for _, field := range fields.List {
|
||||
classifyNames(field.Type, field.Names, kinds)
|
||||
}
|
||||
}
|
||||
|
||||
// classifyNames records names as holding the config kind of typ.
|
||||
func classifyNames(typ ast.Expr, names []*ast.Ident, kinds map[string]configKind) {
|
||||
kind := typeKind(typ)
|
||||
if kind == notConfig {
|
||||
return
|
||||
}
|
||||
for _, name := range names {
|
||||
kinds[name.Name] = kind
|
||||
}
|
||||
}
|
||||
|
||||
// exprKind resolves the config kind of an expression from the identifiers
|
||||
// already classified in kinds.
|
||||
func exprKind(expr ast.Expr, kinds map[string]configKind) configKind {
|
||||
switch e := expr.(type) {
|
||||
case *ast.Ident:
|
||||
return kinds[e.Name]
|
||||
case *ast.SelectorExpr:
|
||||
// doc.Config of a configuration.Document, or a struct field the file
|
||||
// declared as config.Config.
|
||||
if e.Sel.Name == "Config" {
|
||||
return configValue
|
||||
}
|
||||
return kinds[e.Sel.Name]
|
||||
case *ast.CompositeLit:
|
||||
return typeKind(e.Type)
|
||||
case *ast.StarExpr:
|
||||
return exprKind(e.X, kinds)
|
||||
case *ast.UnaryExpr:
|
||||
return exprKind(e.X, kinds)
|
||||
case *ast.ParenExpr:
|
||||
return exprKind(e.X, kinds)
|
||||
case *ast.IndexExpr:
|
||||
if exprKind(e.X, kinds) == configSlice {
|
||||
return configValue
|
||||
}
|
||||
}
|
||||
return notConfig
|
||||
}
|
||||
|
||||
// typeKind reports the config kind a type expression names: config.Config, or
|
||||
// a slice, array or map whose element is one.
|
||||
func typeKind(expr ast.Expr) configKind {
|
||||
switch t := expr.(type) {
|
||||
case *ast.ArrayType:
|
||||
if isConfigType(t.Elt) {
|
||||
return configSlice
|
||||
}
|
||||
case *ast.MapType:
|
||||
// A map's range value is its element; classify the map itself as a
|
||||
// slice-like source so a range over it yields config values.
|
||||
if isConfigType(t.Value) {
|
||||
return configSlice
|
||||
}
|
||||
case *ast.StarExpr:
|
||||
return typeKind(t.X)
|
||||
case *ast.ParenExpr:
|
||||
return typeKind(t.X)
|
||||
}
|
||||
if isConfigType(expr) {
|
||||
return configValue
|
||||
}
|
||||
return notConfig
|
||||
}
|
||||
|
||||
// isConfigType reports whether expr names internal/config's Config type,
|
||||
// directly or behind a pointer.
|
||||
func isConfigType(expr ast.Expr) bool {
|
||||
switch t := expr.(type) {
|
||||
case *ast.SelectorExpr:
|
||||
id, ok := t.X.(*ast.Ident)
|
||||
return ok && id.Name == "config" && t.Sel.Name == "Config"
|
||||
case *ast.StarExpr:
|
||||
return isConfigType(t.X)
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// TestMessagingReadsNoBannedConfigSection is the live gate: every production
|
||||
// source file in the Messaging Service's application package is scanned, and a
|
||||
// read of a PRD-forbidden section fails the build.
|
||||
func TestMessagingReadsNoBannedConfigSection(t *testing.T) {
|
||||
entries, err := os.ReadDir(messagingAppDir)
|
||||
if err != nil {
|
||||
t.Fatalf("read %s: %v", messagingAppDir, err)
|
||||
}
|
||||
scanned := 0
|
||||
for _, entry := range entries {
|
||||
name := entry.Name()
|
||||
if entry.IsDir() || !strings.HasSuffix(name, ".go") || strings.HasSuffix(name, "_test.go") {
|
||||
continue
|
||||
}
|
||||
src, err := os.ReadFile(filepath.Join(messagingAppDir, name))
|
||||
if err != nil {
|
||||
t.Fatalf("read %s: %v", name, err)
|
||||
}
|
||||
scanned++
|
||||
for _, offender := range configReadOffenders(src) {
|
||||
t.Errorf("%s reads %s; the Messaging Service must not read or decode that section (docs/prds/messaging-service-boundary.md, Configuration Ownership) -- the capability belongs to the model-owning process, reached over a contract", name, offender)
|
||||
}
|
||||
}
|
||||
// A gate that read no files would pass silently. Pin that it scanned the
|
||||
// package it names.
|
||||
if scanned == 0 {
|
||||
t.Fatalf("no production .go files found in %s: the gate asserted nothing", messagingAppDir)
|
||||
}
|
||||
}
|
||||
|
||||
// TestConfigReadRuleCatchesTheOldWiring proves the rule fails on a synthetic
|
||||
// copy of the shape that shipped: a projection built by reading
|
||||
// [models].transcription and [providers.*]. Without this, the live gate's rule
|
||||
// could rot into a no-op and still report a pass.
|
||||
func TestConfigReadRuleCatchesTheOldWiring(t *testing.T) {
|
||||
const reverted = `package archiemessaging
|
||||
|
||||
import (
|
||||
"github.com/samcharles93/archie-core/internal/config"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/transcription"
|
||||
)
|
||||
|
||||
func project(cfg config.Config) projection {
|
||||
return projection{
|
||||
models: cfg.Models,
|
||||
providers: cfg.Providers,
|
||||
}
|
||||
}
|
||||
|
||||
func setupTranscriber(cfg config.Config) {
|
||||
_, _ = transcription.New(cfg.Models, cfg.Providers, transcription.Options{})
|
||||
}
|
||||
`
|
||||
got := configReadOffenders([]byte(reverted))
|
||||
want := []string{"cfg.Models", "cfg.Providers", "cfg.Models", "cfg.Providers"}
|
||||
if strings.Join(got, ",") != strings.Join(want, ",") {
|
||||
t.Fatalf("configReadOffenders() = %v, want %v", got, want)
|
||||
}
|
||||
}
|
||||
|
||||
// TestConfigReadRuleCatchesInferredHolders covers the holder shapes the first
|
||||
// cut of this rule missed. It only saw a config.Config written out as a
|
||||
// parameter or var type, so a value reached through an inferred short
|
||||
// variable declaration ("cfg := doc.Config") or held in a struct field
|
||||
// ("h.cfg.Models") left the forbidden [models]/[providers] read intact while
|
||||
// the rule saw no holder to blame. Each case here fails red against that rule:
|
||||
// the live gate would have reported a pass with the violation still shipping.
|
||||
func TestConfigReadRuleCatchesInferredHolders(t *testing.T) {
|
||||
cases := []struct {
|
||||
name string
|
||||
src string
|
||||
want []string
|
||||
}{
|
||||
{
|
||||
name: "short var decl from a Document's Config field",
|
||||
src: `package archiemessaging
|
||||
|
||||
import "github.com/samcharles93/archie-core/internal/infrastructure/configuration"
|
||||
|
||||
func f(doc configuration.Document) {
|
||||
cfg := doc.Config
|
||||
_ = cfg.Models
|
||||
}
|
||||
`,
|
||||
want: []string{"cfg.Models"},
|
||||
},
|
||||
{
|
||||
name: "inferred var without an explicit type",
|
||||
src: `package archiemessaging
|
||||
|
||||
import "github.com/samcharles93/archie-core/internal/infrastructure/configuration"
|
||||
|
||||
func f(doc configuration.Document) {
|
||||
var cfg = doc.Config
|
||||
_ = cfg.Models
|
||||
}
|
||||
`,
|
||||
want: []string{"cfg.Models"},
|
||||
},
|
||||
{
|
||||
name: "short var decl inherits config type from another holder",
|
||||
src: `package archiemessaging
|
||||
|
||||
import "github.com/samcharles93/archie-core/internal/config"
|
||||
|
||||
func f(cfg config.Config) {
|
||||
other := cfg
|
||||
_ = other.Providers
|
||||
}
|
||||
`,
|
||||
want: []string{"other.Providers"},
|
||||
},
|
||||
{
|
||||
name: "config held in a struct field",
|
||||
src: `package archiemessaging
|
||||
|
||||
import "github.com/samcharles93/archie-core/internal/config"
|
||||
|
||||
type holder struct {
|
||||
cfg config.Config
|
||||
}
|
||||
|
||||
func f(h holder) {
|
||||
_ = h.cfg.Providers
|
||||
}
|
||||
`,
|
||||
want: []string{"cfg.Providers"},
|
||||
},
|
||||
{
|
||||
name: "range variable over a slice of config",
|
||||
src: `package archiemessaging
|
||||
|
||||
import "github.com/samcharles93/archie-core/internal/config"
|
||||
|
||||
func f(cfgs []config.Config) {
|
||||
for _, cfg := range cfgs {
|
||||
_ = cfg.Models
|
||||
}
|
||||
}
|
||||
`,
|
||||
want: []string{"cfg.Models"},
|
||||
},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
got := configReadOffenders([]byte(tc.src))
|
||||
if strings.Join(got, ",") != strings.Join(tc.want, ",") {
|
||||
t.Fatalf("configReadOffenders() = %v, want %v", got, tc.want)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestConfigReadRuleAllowsThePermittedKeys proves the rule is not a blanket
|
||||
// ban on config access: the sections the PRD does permit keep passing, and a
|
||||
// nested chat field is not mistaken for a top-level one.
|
||||
func TestConfigReadRuleAllowsThePermittedKeys(t *testing.T) {
|
||||
const permitted = `package archiemessaging
|
||||
|
||||
import "github.com/samcharles93/archie-core/internal/config"
|
||||
|
||||
func project(cfg config.Config) projection {
|
||||
return projection{
|
||||
telegram: cfg.Chat.Telegram,
|
||||
email: cfg.Chat.Email,
|
||||
gateway: cfg.Services.Get("gateway").Target,
|
||||
workDir: cfg.WorkDir,
|
||||
botUser: cfg.BotUser,
|
||||
healthURL: cfg.Health.URL(),
|
||||
}
|
||||
}
|
||||
`
|
||||
if got := configReadOffenders([]byte(permitted)); len(got) != 0 {
|
||||
t.Fatalf("configReadOffenders(permitted) = %v, want none", got)
|
||||
}
|
||||
}
|
||||
@@ -23,9 +23,8 @@ func run() int {
|
||||
flag.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory")
|
||||
flag.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory")
|
||||
flag.StringVar(&options.Gateway.Target, "gateway-target", "", "archie-gateway gRPC address (defaults to [services.gateway].target, else 127.0.0.1:8585)")
|
||||
flag.StringVar(&options.Gateway.Token, "gateway-token", "", "bearer token presented to archie-gateway")
|
||||
flag.StringVar(&options.StateStore.Target, "state-store-target", "", "archie-state-store gRPC address (defaults to [services.state].target)")
|
||||
flag.StringVar(&options.StateStore.Token, "state-store-token", "", "bearer token presented to archie-state-store")
|
||||
flag.StringVar(&options.Listen, "listen", "", "MessagingService gRPC listen address (defaults to [services.messaging].listen)")
|
||||
flag.DurationVar(&options.DependencyTimeout, "dependency-timeout", 0, "readiness probe timeout (default 5s)")
|
||||
flag.DurationVar(&options.ShutdownTimeout, "shutdown-timeout", 0, "shutdown timeout (default 5s)")
|
||||
flag.Parse()
|
||||
|
||||
@@ -1,153 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"net"
|
||||
"os"
|
||||
"os/exec"
|
||||
"path/filepath"
|
||||
"runtime"
|
||||
"strings"
|
||||
"syscall"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"google.golang.org/grpc"
|
||||
|
||||
controlpb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1"
|
||||
"github.com/samcharles93/archie-core/internal/domain/messaging"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/gatewayrpc"
|
||||
)
|
||||
|
||||
func repoRoot(t *testing.T) string {
|
||||
t.Helper()
|
||||
_, file, _, ok := runtime.Caller(0)
|
||||
if !ok {
|
||||
t.Fatal("runtime.Caller failed")
|
||||
}
|
||||
dir := filepath.Dir(file)
|
||||
for {
|
||||
if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil {
|
||||
return dir
|
||||
}
|
||||
parent := filepath.Dir(dir)
|
||||
if parent == dir {
|
||||
t.Fatal("could not find repo root")
|
||||
}
|
||||
dir = parent
|
||||
}
|
||||
}
|
||||
|
||||
func buildBinary(t *testing.T) string {
|
||||
t.Helper()
|
||||
bin := filepath.Join(t.TempDir(), "archie-messaging")
|
||||
cmd := exec.CommandContext(t.Context(), "go", "build", "-o", bin, "./cmd/archie-messaging")
|
||||
cmd.Dir = repoRoot(t)
|
||||
if out, err := cmd.CombinedOutput(); err != nil {
|
||||
t.Fatalf("go build archie-messaging: %v\n%s", err, string(out))
|
||||
}
|
||||
return bin
|
||||
}
|
||||
|
||||
type fakeChatServer struct {
|
||||
messaging.ChatContract
|
||||
}
|
||||
|
||||
func (f *fakeChatServer) Snapshot(ctx context.Context) (messaging.ChatSnapshot, error) {
|
||||
return messaging.ChatSnapshot{}, nil
|
||||
}
|
||||
|
||||
func startTestGateway(t *testing.T) (target string, cleanup func()) {
|
||||
t.Helper()
|
||||
lis, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", "127.0.0.1:0")
|
||||
if err != nil {
|
||||
t.Fatalf("net.Listen: %v", err)
|
||||
}
|
||||
srv := grpc.NewServer()
|
||||
gatewayrpc.RegisterServer(srv, &fakeChatServer{})
|
||||
go func() {
|
||||
_ = srv.Serve(lis)
|
||||
}()
|
||||
return lis.Addr().String(), func() {
|
||||
srv.GracefulStop()
|
||||
_ = lis.Close()
|
||||
}
|
||||
}
|
||||
|
||||
// fakeControlPlane serves the empty channel-settings resource the Messaging
|
||||
// Service reads at startup. The database is authoritative for channel
|
||||
// settings, so the process refuses to start without a State Store to read.
|
||||
type fakeControlPlane struct {
|
||||
controlpb.UnimplementedControlPlaneServiceServer
|
||||
}
|
||||
|
||||
func (f *fakeControlPlane) Catalog(context.Context, *controlpb.CatalogRequest) (*controlpb.CatalogResponse, error) {
|
||||
return &controlpb.CatalogResponse{}, nil
|
||||
}
|
||||
|
||||
func (f *fakeControlPlane) Query(_ context.Context, request *controlpb.QueryRequest) (*controlpb.QueryResponse, error) {
|
||||
return &controlpb.QueryResponse{Resource: &controlpb.Resource{Kind: request.GetKind(), Version: 1, ValueJson: []byte("{}")}}, nil
|
||||
}
|
||||
|
||||
func startTestStateStore(t *testing.T) (target string, cleanup func()) {
|
||||
t.Helper()
|
||||
lis, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", "127.0.0.1:0")
|
||||
if err != nil {
|
||||
t.Fatalf("net.Listen: %v", err)
|
||||
}
|
||||
srv := grpc.NewServer()
|
||||
controlpb.RegisterControlPlaneServiceServer(srv, &fakeControlPlane{})
|
||||
go func() {
|
||||
_ = srv.Serve(lis)
|
||||
}()
|
||||
return lis.Addr().String(), func() {
|
||||
srv.GracefulStop()
|
||||
_ = lis.Close()
|
||||
}
|
||||
}
|
||||
|
||||
func TestBinaryHelp(t *testing.T) {
|
||||
bin := buildBinary(t)
|
||||
cmd := exec.CommandContext(t.Context(), bin, "-help")
|
||||
out, err := cmd.CombinedOutput()
|
||||
// flag.ExitOnError or flag help returns exit 0 or 2 depending on standard library
|
||||
if !strings.Contains(string(out), "gateway-target") {
|
||||
t.Fatalf("help output missing gateway-target flag: %v\n%s", err, string(out))
|
||||
}
|
||||
}
|
||||
|
||||
func TestBinaryStartsAndShutsDownCleanly(t *testing.T) {
|
||||
bin := buildBinary(t)
|
||||
gatewayTarget, cleanup := startTestGateway(t)
|
||||
defer cleanup()
|
||||
stateStoreTarget, stopStateStore := startTestStateStore(t)
|
||||
defer stopStateStore()
|
||||
|
||||
cmd := exec.CommandContext(t.Context(), bin, "-gateway-target", gatewayTarget, "-state-store-target", stateStoreTarget)
|
||||
if err := cmd.Start(); err != nil {
|
||||
t.Fatalf("cmd.Start: %v", err)
|
||||
}
|
||||
|
||||
// Allow the process to start up.
|
||||
time.Sleep(200 * time.Millisecond)
|
||||
|
||||
// Send SIGTERM to shut down gracefully.
|
||||
if err := cmd.Process.Signal(syscall.SIGTERM); err != nil {
|
||||
t.Fatalf("send SIGTERM: %v", err)
|
||||
}
|
||||
|
||||
errCh := make(chan error, 1)
|
||||
go func() {
|
||||
errCh <- cmd.Wait()
|
||||
}()
|
||||
|
||||
select {
|
||||
case err := <-errCh:
|
||||
if err != nil {
|
||||
t.Fatalf("process exited with error on SIGTERM: %v", err)
|
||||
}
|
||||
case <-time.After(3 * time.Second):
|
||||
_ = cmd.Process.Kill()
|
||||
t.Fatal("process did not exit in time after SIGTERM")
|
||||
}
|
||||
}
|
||||
@@ -1,122 +0,0 @@
|
||||
// Command archie-playbooks is the standalone playbook tool for archie-core,
|
||||
// shaped like gopls: one binary, multiple invocation modes. It validates
|
||||
// playbook YAML binding files against the same schema the daemon loads at
|
||||
// startup, so a pre-merge check can never disagree with runtime validation.
|
||||
//
|
||||
// It ships two modes: lint for CI, and serve, a language server that
|
||||
// publishes the same findings as editor diagnostics. Both call the loaders
|
||||
// the daemon runs.
|
||||
//
|
||||
// A finding about one binding key leads with the key's file:line; a file
|
||||
// that does not parse is reported by path with the YAML parser's message.
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"flag"
|
||||
"fmt"
|
||||
"io"
|
||||
"os"
|
||||
"os/signal"
|
||||
"syscall"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/app/archieplaybooks"
|
||||
"github.com/samcharles93/archie-core/internal/buildinfo"
|
||||
)
|
||||
|
||||
func main() {
|
||||
os.Exit(run(os.Args[1:], os.Stderr))
|
||||
}
|
||||
|
||||
func run(args []string, stderr io.Writer) int {
|
||||
// Subcommand table from day one (gopls shape): each mode owns its flag
|
||||
// set and returns an exit code. Adding serve/lsp later is a new entry
|
||||
// here, not a restructuring.
|
||||
commands := map[string]func([]string, io.Writer) int{
|
||||
"lint": runLint,
|
||||
"serve": runServe,
|
||||
}
|
||||
|
||||
if len(args) > 0 && (args[0] == "-version" || args[0] == "--version") {
|
||||
buildinfo.Print("archie-playbooks")
|
||||
return 0
|
||||
}
|
||||
|
||||
if len(args) == 0 {
|
||||
fmt.Fprintln(stderr, "usage: archie-playbooks <command> [args]")
|
||||
fmt.Fprintln(stderr, "commands:")
|
||||
for name := range commands {
|
||||
fmt.Fprintf(stderr, " %s\n", name)
|
||||
}
|
||||
return 2
|
||||
}
|
||||
|
||||
cmd, ok := commands[args[0]]
|
||||
if !ok {
|
||||
fmt.Fprintf(stderr, "archie-playbooks: unknown command %q\n", args[0])
|
||||
return 2
|
||||
}
|
||||
return cmd(args[1:], stderr)
|
||||
}
|
||||
|
||||
// runLint validates routing binding directories (-dir) and an EDA playbook
|
||||
// directory (-eda-dir) against the loaders the daemon runs at startup.
|
||||
// Exit codes: 0 clean, 1 findings, 2 usage error.
|
||||
func runLint(args []string, stderr io.Writer) int {
|
||||
flags := flag.NewFlagSet("archie-playbooks lint", flag.ContinueOnError)
|
||||
flags.SetOutput(stderr)
|
||||
var dirs multiFlag
|
||||
flags.Var(&dirs, "dir", "routing binding directory to lint (repeatable)")
|
||||
edaDir := flags.String("eda-dir", "", "EDA playbook directory to lint (the daemon's eda_playbook_dir)")
|
||||
if err := flags.Parse(args); err != nil {
|
||||
return 2 // flag.ContinueOnError already printed the message
|
||||
}
|
||||
if len(dirs) == 0 && *edaDir == "" {
|
||||
fmt.Fprintln(stderr, "lint: at least one -dir or an -eda-dir is required")
|
||||
flags.Usage()
|
||||
return 2
|
||||
}
|
||||
|
||||
code := 0
|
||||
if len(dirs) > 0 {
|
||||
code = max(code, archieplaybooks.Lint(dirs, stderr).ExitCode)
|
||||
}
|
||||
if *edaDir != "" {
|
||||
code = max(code, archieplaybooks.LintEDA(*edaDir, stderr).ExitCode)
|
||||
}
|
||||
return code
|
||||
}
|
||||
|
||||
// runServe runs the language server on stdin/stdout until the editor
|
||||
// disconnects or the process is signalled.
|
||||
func runServe(args []string, stderr io.Writer) int {
|
||||
if len(args) > 0 {
|
||||
fmt.Fprintln(stderr, "serve: takes no arguments; the editor speaks LSP on stdin/stdout")
|
||||
return 2
|
||||
}
|
||||
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
|
||||
defer stop()
|
||||
if err := archieplaybooks.Serve(ctx, stdio{}); err != nil {
|
||||
fmt.Fprintln(stderr, "serve:", err)
|
||||
return 1
|
||||
}
|
||||
return 0
|
||||
}
|
||||
|
||||
// stdio joins stdin and stdout into the one stream the language server reads
|
||||
// and writes.
|
||||
type stdio struct{}
|
||||
|
||||
func (stdio) Read(p []byte) (int, error) { return os.Stdin.Read(p) }
|
||||
func (stdio) Write(p []byte) (int, error) { return os.Stdout.Write(p) }
|
||||
func (stdio) Close() error { return os.Stdin.Close() }
|
||||
|
||||
// multiFlag collects repeated -dir flags.
|
||||
type multiFlag []string
|
||||
|
||||
func (m *multiFlag) String() string { return fmt.Sprint([]string(*m)) }
|
||||
|
||||
func (m *multiFlag) Set(v string) error {
|
||||
*m = append(*m, v)
|
||||
return nil
|
||||
}
|
||||
@@ -1,88 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// TestRunUnknownCommandExits2: an unrecognised subcommand is a usage error.
|
||||
func TestRunUnknownCommandExits2(t *testing.T) {
|
||||
var stderr bytes.Buffer
|
||||
if code := run([]string{"frobnicate"}, &stderr); code != 2 {
|
||||
t.Fatalf("run(unknown) = %d, want 2", code)
|
||||
}
|
||||
if !strings.Contains(stderr.String(), "unknown command") {
|
||||
t.Fatalf("stderr = %q, want unknown-command message", stderr.String())
|
||||
}
|
||||
}
|
||||
|
||||
// TestRunNoCommandExits2: no subcommand is a usage error with the command
|
||||
// table printed (the gopls-shaped dispatch surface).
|
||||
func TestRunNoCommandExits2(t *testing.T) {
|
||||
var stderr bytes.Buffer
|
||||
if code := run(nil, &stderr); code != 2 {
|
||||
t.Fatalf("run(nil) = %d, want 2", code)
|
||||
}
|
||||
if !strings.Contains(stderr.String(), "lint") {
|
||||
t.Fatalf("stderr = %q, want lint listed in usage", stderr.String())
|
||||
}
|
||||
}
|
||||
|
||||
// TestRunLintCleanExits0: lint over a valid directory exits 0.
|
||||
func TestRunLintCleanExits0(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
writeFile(t, filepath.Join(dir, "routes.yaml"), "bug: tdd\n")
|
||||
|
||||
var stderr bytes.Buffer
|
||||
if code := run([]string{"lint", "-dir", dir}, &stderr); code != 0 {
|
||||
t.Fatalf("run(lint clean) = %d, want 0; stderr=%q", code, stderr.String())
|
||||
}
|
||||
}
|
||||
|
||||
// TestRunLintCollisionExits1: a cross-directory collision exits 1 and names
|
||||
// the colliding key.
|
||||
func TestRunLintCollisionExits1(t *testing.T) {
|
||||
dirA := t.TempDir()
|
||||
dirB := t.TempDir()
|
||||
writeFile(t, filepath.Join(dirA, "a.yaml"), "security: security-review\n")
|
||||
writeFile(t, filepath.Join(dirB, "b.yaml"), "security: other-security\n")
|
||||
|
||||
var stderr bytes.Buffer
|
||||
if code := run([]string{"lint", "-dir", dirA, "-dir", dirB}, &stderr); code != 1 {
|
||||
t.Fatalf("run(lint collision) = %d, want 1; stderr=%q", code, stderr.String())
|
||||
}
|
||||
if !strings.Contains(stderr.String(), "security") {
|
||||
t.Fatalf("stderr = %q, want the colliding label named", stderr.String())
|
||||
}
|
||||
}
|
||||
|
||||
// TestRunLintNoDirsExits2: lint without any -dir is a usage error.
|
||||
func TestRunLintNoDirsExits2(t *testing.T) {
|
||||
var stderr bytes.Buffer
|
||||
if code := run([]string{"lint"}, &stderr); code != 2 {
|
||||
t.Fatalf("run(lint no dirs) = %d, want 2", code)
|
||||
}
|
||||
}
|
||||
|
||||
func writeFile(t *testing.T, path, content string) {
|
||||
t.Helper()
|
||||
if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
|
||||
t.Fatalf("write %s: %v", path, err)
|
||||
}
|
||||
}
|
||||
|
||||
// -eda-dir alone is a complete lint request, and its findings set the exit
|
||||
// code.
|
||||
func TestRunLintEDADir(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
if err := os.WriteFile(filepath.Join(dir, "pb.yaml"), []byte("trigger:\n kind: bug\nactions:\n - position: module\n kind: nope\n"), 0o600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var stderr bytes.Buffer
|
||||
if code := run([]string{"lint", "-eda-dir", dir}, &stderr); code != 1 {
|
||||
t.Fatalf("run(lint -eda-dir) = %d, want 1; stderr: %s", code, stderr.String())
|
||||
}
|
||||
}
|
||||
@@ -1,48 +0,0 @@
|
||||
// Command archie-prbench scores the PR reviewer on the Martian
|
||||
// Code-Review-Bench problems. See docs/prds/pr-review-agent.md, Verification.
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"flag"
|
||||
"fmt"
|
||||
"os"
|
||||
"os/signal"
|
||||
"strings"
|
||||
"syscall"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/app/prbench"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
|
||||
)
|
||||
|
||||
func main() { os.Exit(run()) }
|
||||
|
||||
func run() int {
|
||||
var opts prbench.Options
|
||||
var problems string
|
||||
flag.StringVar(&opts.Config, "config", configuration.DefaultConfigPath(), "configuration file whose providers serve the reviewer and judge")
|
||||
flag.StringVar(&opts.Fixtures, "findings", "", "directory of <problem id>.json findings to rescore; omit to review live")
|
||||
flag.StringVar(&opts.ReviewModel, "review-model", "", "provider/model for the review role in live runs")
|
||||
flag.StringVar(&opts.ClassifyModel, "classification-model", "", "provider/model for the classification role in live runs")
|
||||
flag.StringVar(&opts.JudgeModel, "judge-model", "anthropic/claude-sonnet-4.6", "provider/model of the independent judge")
|
||||
flag.StringVar(&opts.Out, "out", "bin/prbench-results", "directory for per-problem results and summary.json")
|
||||
flag.StringVar(&opts.Resume, "resume", "", "reuse complete results from a previous run with the same models")
|
||||
flag.StringVar(&problems, "problems", "", "comma-separated problem ids (default: all)")
|
||||
flag.IntVar(&opts.Concurrency, "concurrency", 4, "problems judged at once")
|
||||
flag.Parse()
|
||||
opts.GitHubToken = os.Getenv("GH_TOKEN")
|
||||
if opts.GitHubToken == "" {
|
||||
opts.GitHubToken = os.Getenv("GITHUB_TOKEN")
|
||||
}
|
||||
if problems != "" {
|
||||
opts.Problems = strings.Split(problems, ",")
|
||||
}
|
||||
|
||||
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
|
||||
defer stop()
|
||||
if _, err := prbench.Run(ctx, opts, os.Stdout); err != nil {
|
||||
fmt.Fprintln(os.Stderr, "archie-prbench:", err)
|
||||
return 1
|
||||
}
|
||||
return 0
|
||||
}
|
||||
@@ -1,6 +1,5 @@
|
||||
// Command archie-state-store hosts the State Store's gRPC contract and is the
|
||||
// only process that owns the PostgreSQL stores behind it. See
|
||||
// docs/prds/state-store-contract.md §5, §9 and §11.
|
||||
// only process that owns the PostgreSQL stores behind it.
|
||||
package main
|
||||
|
||||
import (
|
||||
@@ -12,7 +11,7 @@ import (
|
||||
"strings"
|
||||
"syscall"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/app/archied"
|
||||
"github.com/samcharles93/archie-core/internal/app/statestore"
|
||||
"github.com/samcharles93/archie-core/internal/buildinfo"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
|
||||
)
|
||||
@@ -20,29 +19,34 @@ import (
|
||||
func main() { os.Exit(run()) }
|
||||
|
||||
func run() int {
|
||||
// A leading non-flag argument selects a recovery subcommand; anything else,
|
||||
// A leading non-flag argument selects a subcommand; anything else,
|
||||
// including no arguments at all, serves the State Store contract. An
|
||||
// unrecognised word is refused rather than ignored, so a mistyped recovery
|
||||
// command never leaves an operator watching a server start instead.
|
||||
// unrecognised word is refused rather than ignored, so a mistyped command
|
||||
// never leaves an operator watching a server start instead.
|
||||
if args := os.Args[1:]; statestore.IsProvisionArgs(args) {
|
||||
return statestore.RunProvision(context.Background(), args[1:], os.Stdout, os.Stderr)
|
||||
}
|
||||
if args := os.Args[1:]; statestore.IsAccessResetArgs(args) {
|
||||
return statestore.RunAccessReset(context.Background(), args[2:], os.Stderr)
|
||||
}
|
||||
if args := os.Args[1:]; len(args) > 0 && !strings.HasPrefix(args[0], "-") {
|
||||
return runRecovery(args, os.Stdout, os.Stderr)
|
||||
}
|
||||
var options archied.StateStoreOptions
|
||||
var options statestore.Options
|
||||
showVersion := buildinfo.RegisterVersionFlag("archie-state-store")
|
||||
flag.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory")
|
||||
flag.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory")
|
||||
flag.StringVar(&options.Listen, "listen", "", "state store gRPC listen address (defaults to [services.state].listen, else 127.0.0.1:9090)")
|
||||
flag.StringVar(&options.Token, "token", "", "bearer token required for a non-loopback listener (defaults to [services.state].target_token)")
|
||||
flag.StringVar(&options.ReadyAddr, "ready-addr", "", "optional readiness HTTP listen address (e.g. 127.0.0.1:9091)")
|
||||
flag.Usage = func() {
|
||||
fmt.Fprintf(flag.CommandLine.Output(), "usage: archie-state-store [flags] # serve the State Store gRPC contract\n\noffline recovery: archie-state-store <backup|restore|validate|rollback|import> -h\n\n")
|
||||
_, _ = fmt.Fprintf(flag.CommandLine.Output(), "usage: archie-state-store [flags] # serve the State Store gRPC contract\n\ndatabase roles: archie-state-store provision -h\noffline recovery: archie-state-store <backup|restore|validate|rollback> -h | access reset -h\n\n")
|
||||
flag.PrintDefaults()
|
||||
}
|
||||
flag.Parse()
|
||||
showVersion()
|
||||
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
|
||||
defer stop()
|
||||
if err := archied.RunStateStore(ctx, options); err != nil {
|
||||
if err := statestore.Run(ctx, options); err != nil {
|
||||
fmt.Fprintln(os.Stderr, err)
|
||||
return 1
|
||||
}
|
||||
|
||||
@@ -1,10 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"os"
|
||||
"testing"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest"
|
||||
)
|
||||
|
||||
func TestMain(m *testing.M) { os.Exit(pgtest.Main(m)) }
|
||||
@@ -1,627 +0,0 @@
|
||||
// Package main smoke-tests the standalone archie-state-store process by
|
||||
// building the real binary, running it against a minimal config on the
|
||||
// loopback interface, and driving it through the State Store gRPC contract
|
||||
// exactly the way a consumer (archied, archie-gateway, archie-agent) does.
|
||||
//
|
||||
// This is the .4.7 end-to-end verification for
|
||||
// docs/prds/state-store-contract.md (rev. 2c): it proves the process owns the
|
||||
// task store, serves the combined task/event/capture
|
||||
// surface over one gRPC service, preserves error-sentinel fidelity across the
|
||||
// wire, honours a per-call deadline, survives a restart/recovery cycle, and
|
||||
// is the sole owner of the store. See §5 (binary layout), §6 (handoff),
|
||||
// §7 (error semantics), §11 (remote adapter) and §12 step 7/8 (single owner).
|
||||
|
||||
package main
|
||||
|
||||
import (
|
||||
"bufio"
|
||||
"bytes"
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"net"
|
||||
"net/http"
|
||||
"os"
|
||||
"os/exec"
|
||||
"path/filepath"
|
||||
"runtime"
|
||||
"strings"
|
||||
"sync"
|
||||
"syscall"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"google.golang.org/grpc"
|
||||
"google.golang.org/grpc/credentials/insecure"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/domain/binding"
|
||||
"github.com/samcharles93/archie-core/internal/domain/mapping"
|
||||
"github.com/samcharles93/archie-core/internal/domain/storecontract"
|
||||
"github.com/samcharles93/archie-core/internal/events"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
|
||||
)
|
||||
|
||||
// repoRoot walks up from the test's source directory to find the module root
|
||||
// (where go.mod lives). The test runs in the package directory
|
||||
// (cmd/archie-state-store), so the module root is above it; walking keeps the
|
||||
// result correct regardless of the harness working directory.
|
||||
func repoRoot(t *testing.T) string {
|
||||
t.Helper()
|
||||
_, file, _, ok := runtime.Caller(0)
|
||||
if !ok {
|
||||
t.Fatal("cannot determine test source path")
|
||||
}
|
||||
dir := filepath.Dir(file)
|
||||
for {
|
||||
if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil {
|
||||
return dir
|
||||
}
|
||||
parent := filepath.Dir(dir)
|
||||
if parent == dir {
|
||||
t.Fatal("go.mod not found above test source")
|
||||
}
|
||||
dir = parent
|
||||
}
|
||||
}
|
||||
|
||||
// buildBinary compiles ./cmd/archie-state-store into dir and returns the path.
|
||||
// This is the real binary the smoke test exercises, not a test double -- the
|
||||
// point of .4.7 is to verify the actual process.
|
||||
func buildBinary(t *testing.T, dir string) string {
|
||||
t.Helper()
|
||||
bin := filepath.Join(dir, "archie-state-store")
|
||||
cmd := exec.CommandContext(t.Context(), "go", "build", "-o", bin, "./cmd/archie-state-store")
|
||||
cmd.Dir = repoRoot(t)
|
||||
cmd.Env = os.Environ()
|
||||
out, err := cmd.CombinedOutput()
|
||||
if err != nil {
|
||||
t.Fatalf("go build archie-state-store: %v\n%s", err, out)
|
||||
}
|
||||
if _, err := os.Stat(bin); err != nil {
|
||||
t.Fatalf("built binary not found: %v", err)
|
||||
}
|
||||
return bin
|
||||
}
|
||||
|
||||
// writeMinimalConfig writes a config.toml that passes configuration.Validate
|
||||
// while keeping the process minimal: the standalone binary takes its gRPC
|
||||
// listen address from -listen or [services.state].listen, never from the
|
||||
// target, so the config only needs the fields validation requires plus the
|
||||
// database_url it owns. The
|
||||
// forge token resolves from an env var, so no real credential is needed.
|
||||
func writeMinimalConfig(t *testing.T, dir string) string {
|
||||
t.Helper()
|
||||
return writeConfigFor(t, dir, pgtest.URL(t))
|
||||
}
|
||||
|
||||
// writeConfigFor is writeMinimalConfig naming the database at url.
|
||||
func writeConfigFor(t *testing.T, dir, url string) string {
|
||||
t.Helper()
|
||||
cfg := filepath.Join(dir, "config.toml")
|
||||
content := fmt.Sprintf(`bot_user = "archie-bot"
|
||||
database_url = %q
|
||||
[forge]
|
||||
type = "github"
|
||||
host = "https://github.example.com"
|
||||
token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN" }
|
||||
[[repos]]
|
||||
owner = "acme"
|
||||
name = "widget"
|
||||
`, url)
|
||||
if err := os.WriteFile(cfg, []byte(content), 0o600); err != nil {
|
||||
t.Fatalf("write config: %v", err)
|
||||
}
|
||||
return cfg
|
||||
}
|
||||
|
||||
// writeConfigWithServiceListen is writeMinimalConfig plus the
|
||||
// [services.state] block that lets a test supply the listen address through
|
||||
// configuration instead of the -listen flag.
|
||||
func writeConfigWithServiceListen(t *testing.T, dir string) string {
|
||||
t.Helper()
|
||||
cfg := writeMinimalConfig(t, dir)
|
||||
f, err := os.OpenFile(cfg, os.O_APPEND|os.O_WRONLY, 0o600)
|
||||
if err != nil {
|
||||
t.Fatalf("open config to append: %v", err)
|
||||
}
|
||||
defer func() {
|
||||
if err := f.Close(); err != nil {
|
||||
t.Fatalf("close config: %v", err)
|
||||
}
|
||||
}()
|
||||
if _, err := f.WriteString("\n[services.state]\nlisten = \"127.0.0.1:0\"\n"); err != nil {
|
||||
t.Fatalf("append [services.state]: %v", err)
|
||||
}
|
||||
return cfg
|
||||
}
|
||||
|
||||
// syncBuffer is a concurrency-safe buffer for a subprocess's stdout/stderr:
|
||||
// the os/exec goroutine writes while the test goroutine reads (to parse the
|
||||
// log and to report it on failure). A plain strings.Builder races under
|
||||
// -race, so both paths take the mutex.
|
||||
type syncBuffer struct {
|
||||
mu sync.Mutex
|
||||
b bytes.Buffer
|
||||
}
|
||||
|
||||
func (s *syncBuffer) Write(p []byte) (int, error) {
|
||||
s.mu.Lock()
|
||||
defer s.mu.Unlock()
|
||||
return s.b.Write(p)
|
||||
}
|
||||
|
||||
func (s *syncBuffer) String() string {
|
||||
s.mu.Lock()
|
||||
defer s.mu.Unlock()
|
||||
return s.b.String()
|
||||
}
|
||||
|
||||
// stateStoreProcess wraps a running archie-state-store subprocess plus the
|
||||
// addresses it bound. addr is the gRPC listen address; readyAddr is the
|
||||
// readiness HTTP surface. It is stopped gracefully on cleanup by SIGTERM, the
|
||||
// signal the systemd unit ("Restart=on-failure") and the daemon use to drain
|
||||
// the server.
|
||||
type stateStoreProcess struct {
|
||||
cmd *exec.Cmd
|
||||
addr string
|
||||
readyAddr string
|
||||
log *syncBuffer
|
||||
}
|
||||
|
||||
// startStateStoreProcess starts bin with config, waiting for the gRPC listener
|
||||
// to come up and the readiness surface to answer /healthz. It parses the
|
||||
// binary's stderr log for the bound addresses because --listen 127.0.0.1:0
|
||||
// lets the process choose ephemeral ports, and the real address (not the
|
||||
// configured one) is what a consumer must dial.
|
||||
func startStateStoreProcess(t *testing.T, bin, cfg string) *stateStoreProcess {
|
||||
t.Helper()
|
||||
return startStateStore(t, bin, cfg, "127.0.0.1:0", "")
|
||||
}
|
||||
|
||||
// startStateStore is startStateStoreProcess with the listener topology and
|
||||
// bearer token exposed: the token-protected, non-loopback listener is the
|
||||
// topology every container-mode deployment profile uses
|
||||
// (docs/prds/state-store-contract.md §9), where the server installs the
|
||||
// credential interceptors on both the unary and the streaming surface.
|
||||
func startStateStore(t *testing.T, bin, cfg, listen, token string) *stateStoreProcess {
|
||||
t.Helper()
|
||||
args := []string{"-config", cfg, "-ready-addr", "127.0.0.1:0"}
|
||||
if listen != "" {
|
||||
// An empty listen means "pass no -listen at all". A test uses that to
|
||||
// prove the bound address came from [services.state].listen.
|
||||
args = append(args, "-listen", listen)
|
||||
}
|
||||
if token != "" {
|
||||
// An explicit -token wins over [services.state].target_token and the
|
||||
// STATE_STORE_TOKEN secret, so the process authenticates callers with
|
||||
// exactly this value.
|
||||
args = append(args, "-token", token)
|
||||
}
|
||||
cmd := exec.CommandContext(t.Context(), bin, args...)
|
||||
cmd.Env = append(os.Environ(), "ARCHIE_GITHUB_TOKEN=test-token")
|
||||
var log syncBuffer
|
||||
cmd.Stderr = &log
|
||||
cmd.Stdout = &log
|
||||
if err := cmd.Start(); err != nil {
|
||||
t.Fatalf("start state store: %v", err)
|
||||
}
|
||||
p := &stateStoreProcess{cmd: cmd, log: &log}
|
||||
t.Cleanup(func() { p.stop(t) })
|
||||
|
||||
// Recover the ephemeral ports from the JSON log lines the binary emits.
|
||||
deadline := time.Now().Add(15 * time.Second)
|
||||
for time.Now().Before(deadline) {
|
||||
if p.parseAddrs() {
|
||||
break
|
||||
}
|
||||
if cmd.ProcessState != nil {
|
||||
t.Fatalf("state store exited early:\n%s", log.String())
|
||||
}
|
||||
time.Sleep(25 * time.Millisecond)
|
||||
}
|
||||
if p.addr == "" || p.readyAddr == "" {
|
||||
t.Fatalf("did not recover bound addresses from log:\n%s", log.String())
|
||||
}
|
||||
|
||||
// The readiness surface is the liveness signal the runbook uses; poll it
|
||||
// until it answers (the gRPC listener may come up a tick ahead of it).
|
||||
deadline = time.Now().Add(15 * time.Second)
|
||||
req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, "http://"+p.readyAddr+"/healthz", nil)
|
||||
if err != nil {
|
||||
t.Fatalf("build readiness request: %v", err)
|
||||
}
|
||||
for time.Now().Before(deadline) {
|
||||
if resp, err := http.DefaultClient.Do(req); err == nil {
|
||||
_ = resp.Body.Close()
|
||||
if resp.StatusCode == http.StatusOK {
|
||||
return p
|
||||
}
|
||||
}
|
||||
time.Sleep(25 * time.Millisecond)
|
||||
}
|
||||
t.Fatalf("readiness /healthz never became healthy:\n%s", log.String())
|
||||
return nil
|
||||
}
|
||||
|
||||
// parseAddrs scans the captured log for the bound gRPC and readiness
|
||||
// addresses. The binary logs "archie-state-store running" with the gRPC addr
|
||||
// and "state store readiness listening" with the HTTP addr.
|
||||
func (p *stateStoreProcess) parseAddrs() bool {
|
||||
if p.addr != "" && p.readyAddr != "" {
|
||||
return true
|
||||
}
|
||||
scanner := bufio.NewScanner(strings.NewReader(p.log.String()))
|
||||
for scanner.Scan() {
|
||||
line := scanner.Text()
|
||||
var rec map[string]any
|
||||
if err := json.Unmarshal([]byte(line), &rec); err != nil {
|
||||
continue
|
||||
}
|
||||
if msg, _ := rec["msg"].(string); msg == "archie-state-store running" {
|
||||
if addr, ok := rec["addr"].(string); ok && addr != "" && p.addr == "" {
|
||||
p.addr = addr
|
||||
}
|
||||
}
|
||||
if msg, _ := rec["msg"].(string); msg == "state store readiness listening" {
|
||||
if addr, ok := rec["addr"].(string); ok && addr != "" && p.readyAddr == "" {
|
||||
p.readyAddr = strings.TrimPrefix(addr, "http://")
|
||||
}
|
||||
}
|
||||
}
|
||||
return p.addr != "" && p.readyAddr != ""
|
||||
}
|
||||
|
||||
// stop drains the process with SIGTERM and waits for it to exit. This is the
|
||||
// same graceful-stop path serveStateStore's signal handling implements.
|
||||
func (p *stateStoreProcess) stop(t *testing.T) {
|
||||
t.Helper()
|
||||
if p.cmd.Process == nil {
|
||||
return
|
||||
}
|
||||
_ = p.cmd.Process.Signal(syscall.SIGTERM)
|
||||
done := make(chan struct{})
|
||||
go func() { _ = p.cmd.Wait(); close(done) }()
|
||||
select {
|
||||
case <-done:
|
||||
case <-time.After(10 * time.Second):
|
||||
_ = p.cmd.Process.Kill()
|
||||
<-done
|
||||
}
|
||||
}
|
||||
|
||||
// contract is the combined consumer surface a daemon/gateway/agent mixes: the
|
||||
// task lifecycle + events surface (storecontract.TaskStore) and the capture surface.
|
||||
// Mapping/binding/dispatch is exercised separately in
|
||||
// TestStateStoreRealProcessRemoteSurfaces via the concrete Client, which
|
||||
// asserts against each narrow interface at compile time.
|
||||
type contract interface {
|
||||
storecontract.TaskStore
|
||||
storecontract.CaptureStore
|
||||
}
|
||||
|
||||
// dial opens a gRPC connection to the state store process and wraps it in the
|
||||
// remote contract adapter, exactly as the daemon/gateway/agent consumer does
|
||||
// (internal/infrastructure/staterpc.Client).
|
||||
func dial(t *testing.T, addr string) contract {
|
||||
t.Helper()
|
||||
conn, err := grpc.NewClient("passthrough:///"+addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
|
||||
if err != nil {
|
||||
t.Fatalf("dial %s: %v", addr, err)
|
||||
}
|
||||
t.Cleanup(func() { _ = conn.Close() })
|
||||
return staterpc.NewClient(conn)
|
||||
}
|
||||
|
||||
// capture builds a CapturedEvent without pulling the whole store field set
|
||||
// into every call site.
|
||||
func capture(source, body string) storecontract.CapturedEvent {
|
||||
return storecontract.CapturedEvent{Source: source, Body: body, Authenticated: true}
|
||||
}
|
||||
|
||||
// TestStateStoreRealProcessSmoke exercises the actual archie-state-store
|
||||
// binary end-to-end: the combined task/event/capture view through one consumer
|
||||
// adapter, error-sentinel fidelity across the wire, the not-found-as-(nil,nil)
|
||||
// convention, and single-owner SQLite (the binary owns the one archie.db file
|
||||
// and the consumer dials gRPC without opening any store file).
|
||||
//
|
||||
// It also takes its listen address from [services.state].listen rather than
|
||||
// -listen, so the startup path every deployment uses is covered by the process
|
||||
// that exercises the most: before that key existed the address came from a flag
|
||||
// default with no config key, so a host whose port was already taken could
|
||||
// only be retargeted by passing -listen and
|
||||
// hand-writing an overlay whose target matched -- and the failure read as a
|
||||
// code fault, "address already in use" in the store and a gRPC handshake error
|
||||
// in every client.
|
||||
func TestStateStoreRealProcessSmoke(t *testing.T) {
|
||||
if testing.Short() {
|
||||
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
|
||||
}
|
||||
t.Parallel()
|
||||
dir := t.TempDir()
|
||||
bin := buildBinary(t, dir)
|
||||
cfg := writeConfigWithServiceListen(t, dir)
|
||||
st := startStateStore(t, bin, cfg, "", "")
|
||||
if st.addr == "" {
|
||||
t.Fatalf("no bound gRPC address in the log:\n%s", st.log.String())
|
||||
}
|
||||
if !strings.Contains(st.log.String(), `"listen":"127.0.0.1:0"`) {
|
||||
t.Fatalf("the resolved listen was not the configured address:\n%s", st.log.String())
|
||||
}
|
||||
cl := dial(t, st.addr)
|
||||
|
||||
ctx := t.Context()
|
||||
|
||||
// Combined task/event/capture view: a task, an event on that task, and an
|
||||
// unrelated capture written through one consumer, read back across all
|
||||
// three surfaces in a single pass (the dashboard/observability read path).
|
||||
task, err := cl.EnqueueChatTask(ctx, "acme", "widget", "verify state store", "body", "implement", "", nil)
|
||||
if err != nil || task == nil {
|
||||
t.Fatalf("EnqueueChatTask = %+v, %v", task, err)
|
||||
}
|
||||
if err := cl.Transition(ctx, task.ID, task.Status, "running", "smoke started"); err != nil {
|
||||
t.Fatalf("Transition: %v", err)
|
||||
}
|
||||
if _, err := cl.InsertEvent(ctx, events.Event{Kind: "stage_finish", TaskID: task.ID, Attempt: 1, Data: map[string]any{"duration_ms": 12.0}}); err != nil {
|
||||
t.Fatalf("InsertEvent: %v", err)
|
||||
}
|
||||
// R4's document is stored as an event, so the real process must round-trip
|
||||
// it with its nested structure and its attempt key intact: the standalone
|
||||
// State Store owns the only copy, and a lost field here is a Config tab
|
||||
// that reads a run it cannot describe. The key is the daemon's own
|
||||
// (internal/daemon/daemon.go writes "document"), asserted by name below.
|
||||
if _, err := cl.InsertEvent(ctx, events.Event{
|
||||
Kind: events.KindConfigCaptured, TaskID: task.ID, Attempt: 1,
|
||||
Data: map[string]any{
|
||||
"schema": events.ConfigCapturedSchema,
|
||||
"document": map[string]any{"bot_user": "archie", "models": map[string]any{"implement": "anthropic/claude"}},
|
||||
},
|
||||
}); err != nil {
|
||||
t.Fatalf("InsertEvent config_captured: %v", err)
|
||||
}
|
||||
if capID, err := cl.InsertCapture(ctx, capture("sentry", `{"id":1}`), 0, 0); err != nil || capID == "" {
|
||||
t.Fatalf("InsertCapture = (%q, %v)", capID, err)
|
||||
}
|
||||
|
||||
got, err := cl.TaskByID(ctx, task.ID)
|
||||
if err != nil || got == nil || got.ID != task.ID || got.Status != "running" {
|
||||
t.Fatalf("TaskByID after transition = %+v, %v", got, err)
|
||||
}
|
||||
evs, err := cl.TaskEvents(ctx, task.ID)
|
||||
if err != nil || len(evs) != 2 || evs[0].Kind != "stage_finish" {
|
||||
t.Fatalf("TaskEvents = %+v, %v", evs, err)
|
||||
}
|
||||
if evs[0].Attempt != 1 {
|
||||
t.Errorf("TaskEvents attempt = %d, want 1 across the real process", evs[0].Attempt)
|
||||
}
|
||||
if evs[1].Kind != events.KindConfigCaptured || evs[1].Attempt != 1 || evs[1].Data["schema"] != events.ConfigCapturedSchema {
|
||||
t.Errorf("config_captured event = %+v, want its kind, attempt and schema preserved", evs[1])
|
||||
}
|
||||
if _, renamed := evs[1].Data["config"]; renamed {
|
||||
t.Error(`the document crossed under "config"; the producer writes it under "document"`)
|
||||
}
|
||||
if len(evs[1].Data) != 2 {
|
||||
t.Errorf("config_captured data keys = %v, want exactly schema and document", evs[1].Data)
|
||||
}
|
||||
if doc, ok := evs[1].Data["document"].(map[string]any); !ok || doc["bot_user"] != "archie" {
|
||||
t.Errorf("config_captured payload = %#v, want the decoded document under its own key", evs[1].Data)
|
||||
}
|
||||
if caps, err := cl.ListCaptures(ctx, 10); err != nil || len(caps) != 1 || caps[0].Source != "sentry" {
|
||||
t.Fatalf("ListCaptures = %+v, %v", caps, err)
|
||||
}
|
||||
if counts, err := cl.StatusCounts(ctx); err != nil || counts["running"] != 1 {
|
||||
t.Fatalf("StatusCounts = %+v, %v", counts, err)
|
||||
}
|
||||
|
||||
t.Run("error_sentinel_fidelity", func(t *testing.T) {
|
||||
// A stale transition must rehydrate to storecontract.ErrStaleTransition across
|
||||
// the wire (§7). Because the binary is up and we dialed it, a sentinel
|
||||
// mismatch here would surface as a transport error, so a pass proves
|
||||
// the gRPC mapError/unmapError round-trip, not just the in-process
|
||||
// adapter.
|
||||
err := cl.Transition(ctx, task.ID, "queued", "merged", "")
|
||||
if !errors.Is(err, storecontract.ErrStaleTransition) {
|
||||
t.Fatalf("stale Transition = %v, want storecontract.ErrStaleTransition", err)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("not_found_is_not_error", func(t *testing.T) {
|
||||
// Reading a missing task returns (nil, nil), never a NotFound gRPC
|
||||
// error (§7's found=false-not-error convention).
|
||||
missing, err := cl.TaskByID(ctx, task.ID+999999)
|
||||
if err != nil || missing != nil {
|
||||
t.Fatalf("TaskByID missing = (%+v, %v), want (nil, nil)", missing, err)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("serves_from_postgres_only", func(t *testing.T) {
|
||||
// The binary serves every store from database_url: no SQLite file
|
||||
// appears in its directory.
|
||||
for _, name := range []string{"archie.db", "archie.db-tasks.sqlite", "archie.db-eda.sqlite"} {
|
||||
if _, err := os.Stat(filepath.Join(dir, name)); err == nil {
|
||||
t.Fatalf("state store created %s; it serves from Postgres only", name)
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
// TestStateStoreRealProcessDeadline verifies the per-call deadline behaviour
|
||||
// the state store contract requires (§6 StoreTimeout): a consumer context that
|
||||
// is cancelled before the call completes must surface a deadline/cancel error
|
||||
// rather than hang or silently succeed.
|
||||
func TestStateStoreRealProcessDeadline(t *testing.T) {
|
||||
if testing.Short() {
|
||||
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
|
||||
}
|
||||
t.Parallel()
|
||||
dir := t.TempDir()
|
||||
bin := buildBinary(t, dir)
|
||||
cfg := writeMinimalConfig(t, dir)
|
||||
st := startStateStoreProcess(t, bin, cfg)
|
||||
cl := dial(t, st.addr)
|
||||
|
||||
ctx, cancel := context.WithCancel(t.Context())
|
||||
cancel()
|
||||
_, err := cl.StatusCounts(ctx)
|
||||
if err == nil {
|
||||
t.Fatal("StatusCounts on a cancelled context returned nil; expected a deadline/cancel error")
|
||||
}
|
||||
if !errors.Is(err, context.Canceled) && !errors.Is(err, context.DeadlineExceeded) {
|
||||
t.Fatalf("StatusCounts cancelled = %v, want context.Canceled or DeadlineExceeded", err)
|
||||
}
|
||||
}
|
||||
|
||||
// TestStateStoreRealProcessRestartRecovery starts the process, writes a task,
|
||||
// stops it (SIGTERM), restarts it on the same config, and verifies the
|
||||
// task and its events were recovered from the on-disk SQLite -- the
|
||||
// restart/recovery path the runbook relies on when archie-state-store is
|
||||
// restarted as a service.
|
||||
func TestStateStoreRealProcessRestartRecovery(t *testing.T) {
|
||||
if testing.Short() {
|
||||
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
|
||||
}
|
||||
t.Parallel()
|
||||
dir := t.TempDir()
|
||||
bin := buildBinary(t, dir)
|
||||
cfg := writeMinimalConfig(t, dir)
|
||||
|
||||
first := startStateStoreProcess(t, bin, cfg)
|
||||
s1 := dial(t, first.addr)
|
||||
task, err := s1.EnqueueChatTask(t.Context(), "acme", "widget", "survive restart", "body", "implement", "", nil)
|
||||
if err != nil || task == nil {
|
||||
t.Fatalf("first EnqueueChatTask = %+v, %v", task, err)
|
||||
}
|
||||
if _, err := s1.InsertEvent(t.Context(), events.Event{Kind: "run_started", TaskID: task.ID}); err != nil {
|
||||
t.Fatalf("first InsertEvent: %v", err)
|
||||
}
|
||||
first.stop(t)
|
||||
|
||||
// Restart on the same config; the SQLite file persists on disk.
|
||||
second := startStateStoreProcess(t, bin, cfg)
|
||||
s2 := dial(t, second.addr)
|
||||
|
||||
got, err := s2.TaskByID(t.Context(), task.ID)
|
||||
if err != nil || got == nil || got.Title != "survive restart" {
|
||||
t.Fatalf("TaskByID after restart = %+v, %v", got, err)
|
||||
}
|
||||
if evs, err := s2.TaskEvents(t.Context(), task.ID); err != nil || len(evs) != 1 {
|
||||
t.Fatalf("TaskEvents after restart = %+v, %v", evs, err)
|
||||
}
|
||||
// Stale-running work reopened on a fresh process is recovered by
|
||||
// RecoverStale, which must return without error on the restarted store.
|
||||
if _, err := s2.RecoverStale(t.Context()); err != nil {
|
||||
t.Fatalf("RecoverStale after restart: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// TestStateStoreRealProcessTokenProtectedCaptureStream is the capture-batch
|
||||
// regression against the real binary: the token-protected, non-loopback
|
||||
// listener topology a container-mode deployment uses, read through the
|
||||
// production client wiring (staterpc.Dial) the daemon and the dashboard both
|
||||
// use. The reads the batch needs are server-streaming RPCs, whose metadata
|
||||
// the unary-only client interceptor never saw -- so before the fix this
|
||||
// failed with PermissionDenied, and no unary fallback existed to take. 20 x
|
||||
// 256 KiB is 5 MiB, past gRPC's 4 MiB unary cap, so the batch also proves the
|
||||
// streams still carry it.
|
||||
func TestStateStoreRealProcessTokenProtectedCaptureStream(t *testing.T) {
|
||||
if testing.Short() {
|
||||
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
|
||||
}
|
||||
t.Parallel()
|
||||
const token = "operator-secret-token"
|
||||
dir := t.TempDir()
|
||||
bin := buildBinary(t, dir)
|
||||
cfg := writeMinimalConfig(t, dir)
|
||||
st := startStateStore(t, bin, cfg, "0.0.0.0:0", token)
|
||||
|
||||
// The listener advertises the wildcard address it bound; a consumer dials
|
||||
// the host address it can reach, which is this host's loopback.
|
||||
_, port, err := net.SplitHostPort(st.addr)
|
||||
if err != nil {
|
||||
t.Fatalf("parse bound address %q: %v", st.addr, err)
|
||||
}
|
||||
cl, cleanup, err := staterpc.Dial("127.0.0.1:"+port, token)
|
||||
if err != nil {
|
||||
t.Fatalf("dial token-protected state store: %v", err)
|
||||
}
|
||||
t.Cleanup(cleanup)
|
||||
|
||||
ctx := t.Context()
|
||||
body := strings.Repeat("x", 256<<10)
|
||||
for range 20 {
|
||||
if _, err := cl.InsertCapture(ctx, capture("large", body), 0, 0); err != nil {
|
||||
t.Fatalf("InsertCapture: %v", err)
|
||||
}
|
||||
}
|
||||
captures, err := cl.ListCaptures(ctx, 20)
|
||||
if err != nil {
|
||||
t.Fatalf("ListCaptures over a token-protected listener: %v", err)
|
||||
}
|
||||
if len(captures) != 20 {
|
||||
t.Fatalf("got %d captures, want 20", len(captures))
|
||||
}
|
||||
for _, c := range captures {
|
||||
if c.Body != body {
|
||||
t.Fatal("capture body truncated")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestStateStoreRealProcessRemoteSurfaces exercises the capture/mapping/
|
||||
// binding surfaces the standalone process fronts (the daemon/webui surfaces
|
||||
// swapped to the adapter in .4.4/.4.5), proving one process serves the full
|
||||
// combined contract a consumer mixes.
|
||||
func TestStateStoreRealProcessRemoteSurfaces(t *testing.T) {
|
||||
if testing.Short() {
|
||||
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
|
||||
}
|
||||
t.Parallel()
|
||||
dir := t.TempDir()
|
||||
bin := buildBinary(t, dir)
|
||||
cfg := writeMinimalConfig(t, dir)
|
||||
st := startStateStoreProcess(t, bin, cfg)
|
||||
|
||||
conn, err := grpc.NewClient("passthrough:///"+st.addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
|
||||
if err != nil {
|
||||
t.Fatalf("dial: %v", err)
|
||||
}
|
||||
t.Cleanup(func() { _ = conn.Close() })
|
||||
cl := staterpc.NewClient(conn)
|
||||
|
||||
ctx := t.Context()
|
||||
mappingID, err := cl.InsertMapping(ctx, mapping.Mapping{Name: "m1", Fields: []mapping.Field{{Name: "a", Path: "a", Type: mapping.TypeString}}})
|
||||
if err != nil || mappingID == "" {
|
||||
t.Fatalf("InsertMapping = (%q, %v)", mappingID, err)
|
||||
}
|
||||
if got, err := cl.GetMapping(ctx, mappingID); err != nil || got == nil || got.Name != "m1" {
|
||||
t.Fatalf("GetMapping = %+v, %v", got, err)
|
||||
}
|
||||
bindingID, err := cl.InsertBinding(ctx, binding.Binding{
|
||||
Name: "b1", Matcher: binding.Matcher{Source: "sentry"}, MappingID: mappingID,
|
||||
Workflow: "implement",
|
||||
})
|
||||
if err != nil || bindingID == "" {
|
||||
t.Fatalf("InsertBinding = (%q, %v)", bindingID, err)
|
||||
}
|
||||
// A binding starts as draft and must be edited (draft -> pending_approval)
|
||||
// then approved (pending_approval -> armed) before it is armed for a
|
||||
// source. Drive the state machine so ArmedBindingsForSource returns it.
|
||||
if err := cl.UpdateBinding(ctx, binding.Binding{
|
||||
ID: bindingID, Name: "b1", Matcher: binding.Matcher{Source: "sentry"},
|
||||
MappingID: mappingID, Workflow: "implement", Owner: "acme", Repo: "widget",
|
||||
}); err != nil {
|
||||
t.Fatalf("UpdateBinding: %v", err)
|
||||
}
|
||||
if err := cl.ApproveBinding(ctx, bindingID); err != nil {
|
||||
t.Fatalf("ApproveBinding: %v", err)
|
||||
}
|
||||
if armed, err := cl.ArmedBindingsForSource(ctx, "sentry"); err != nil || len(armed) != 1 || armed[0].ID != bindingID {
|
||||
t.Fatalf("ArmedBindingsForSource = %+v, %v", armed, err)
|
||||
}
|
||||
// Remote surfaces share error-sentinel fidelity on the wire too.
|
||||
missing := mapping.Mapping{ID: "rabsent00000000", Name: "x", Fields: []mapping.Field{{Name: "a", Path: "a", Type: mapping.TypeString}}}
|
||||
if err := cl.UpdateMapping(ctx, missing); !errors.Is(err, storecontract.ErrMappingNotFound) {
|
||||
t.Fatalf("UpdateMapping missing = %v, want ErrMappingNotFound", err)
|
||||
}
|
||||
}
|
||||
@@ -7,14 +7,14 @@ import (
|
||||
"fmt"
|
||||
"io"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/app/archied"
|
||||
"github.com/samcharles93/archie-core/internal/app/statestore"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
|
||||
)
|
||||
|
||||
// recoveryUsage is the whole flag surface of the offline recovery commands.
|
||||
// They are subcommands of this binary rather than a recovery binary of their
|
||||
// own: offline database maintenance belongs to the process that owns the file
|
||||
// and its path layout (docs/architecture/organisation.md#process-boundaries).
|
||||
// and its path layout.
|
||||
const recoveryUsage = `usage: archie-state-store <command> [flags]
|
||||
|
||||
With no command, archie-state-store serves the State Store gRPC contract.
|
||||
@@ -47,22 +47,22 @@ the daemon boots with, which names the database.
|
||||
// 1 the operation failed, 2 the command line was wrong.
|
||||
func runRecovery(args []string, stdout, stderr io.Writer) int {
|
||||
if len(args) == 0 {
|
||||
fmt.Fprint(stderr, recoveryUsage)
|
||||
_, _ = fmt.Fprint(stderr, recoveryUsage)
|
||||
return 2
|
||||
}
|
||||
command := args[0]
|
||||
options := archied.StateStoreRecoveryOptions{Operation: command}
|
||||
options := statestore.RecoveryOptions{Operation: command}
|
||||
switch command {
|
||||
case archied.RecoveryBackup, archied.RecoveryRestore, archied.RecoveryValidate, archied.RecoveryRollback:
|
||||
case statestore.RecoveryBackup, statestore.RecoveryRestore, statestore.RecoveryValidate, statestore.RecoveryRollback:
|
||||
default:
|
||||
fmt.Fprintf(stderr, "archie-state-store: unknown command %q\n\n", command)
|
||||
fmt.Fprint(stderr, recoveryUsage)
|
||||
_, _ = fmt.Fprintf(stderr, "archie-state-store: unknown command %q\n\n", command)
|
||||
_, _ = fmt.Fprint(stderr, recoveryUsage)
|
||||
return 2
|
||||
}
|
||||
|
||||
flags := flag.NewFlagSet("archie-state-store "+command, flag.ContinueOnError)
|
||||
flags.SetOutput(stderr)
|
||||
flags.Usage = func() { fmt.Fprint(stderr, recoveryUsage) }
|
||||
flags.Usage = func() { _, _ = fmt.Fprint(stderr, recoveryUsage) }
|
||||
flags.StringVar(&options.Out, "out", "", "snapshot file backup writes")
|
||||
flags.StringVar(&options.From, "from", "", "snapshot file restore reads")
|
||||
flags.StringVar(&options.Kind, "kind", "", "control-plane resource kind rollback replays")
|
||||
@@ -80,15 +80,15 @@ func runRecovery(args []string, stdout, stderr io.Writer) int {
|
||||
return 2
|
||||
}
|
||||
if flags.NArg() > 0 {
|
||||
fmt.Fprintf(stderr, "archie-state-store %s: unexpected argument %q\n", command, flags.Arg(0))
|
||||
_, _ = fmt.Fprintf(stderr, "archie-state-store %s: unexpected argument %q\n", command, flags.Arg(0))
|
||||
return 2
|
||||
}
|
||||
|
||||
summary, err := archied.RunStateStoreRecovery(context.Background(), options)
|
||||
summary, err := statestore.RunRecovery(context.Background(), options)
|
||||
if err != nil {
|
||||
fmt.Fprintf(stderr, "archie-state-store %s: %v\n", command, err)
|
||||
_, _ = fmt.Fprintf(stderr, "archie-state-store %s: %v\n", command, err)
|
||||
return 1
|
||||
}
|
||||
fmt.Fprintln(stdout, summary)
|
||||
_, _ = fmt.Fprintln(stdout, summary)
|
||||
return 0
|
||||
}
|
||||
@@ -1,43 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// Without -db every recovery command targets the configured PostgreSQL
|
||||
// database, so each one accepts -config and refuses, naming the key, when the
|
||||
// configuration names no database.
|
||||
func TestRecoveryWithoutDBUsesTheConfiguredDatabase(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
configPath := writeMinimalConfig(t, dir)
|
||||
raw, err := os.ReadFile(configPath)
|
||||
if err != nil {
|
||||
t.Fatalf("read config: %v", err)
|
||||
}
|
||||
var kept []string
|
||||
for line := range strings.Lines(string(raw)) {
|
||||
if !strings.HasPrefix(line, "database_url") {
|
||||
kept = append(kept, line)
|
||||
}
|
||||
}
|
||||
if err := os.WriteFile(configPath, []byte(strings.Join(kept, "")), 0o600); err != nil {
|
||||
t.Fatalf("write config: %v", err)
|
||||
}
|
||||
tests := [][]string{
|
||||
{"backup", "-out", filepath.Join(dir, "snapshot.dump")},
|
||||
{"restore", "-from", filepath.Join(dir, "snapshot.dump")},
|
||||
{"validate"},
|
||||
{"rollback", "-kind", "settings"},
|
||||
}
|
||||
for _, args := range tests {
|
||||
t.Run(args[0], func(t *testing.T) {
|
||||
code, _, stderr := runRecoveryCmd(t, append(args, "-config", configPath)...)
|
||||
if code != 1 || !strings.Contains(stderr, "database_url") {
|
||||
t.Fatalf("%s exited %d, stderr %q; want 1 naming database_url", args[0], code, stderr)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -1,486 +0,0 @@
|
||||
// Package main tests the offline recovery subcommands of archie-state-store
|
||||
// against the PostgreSQL database the configuration names. They are the
|
||||
// operator's only path back when the control plane's stored settings will not
|
||||
// validate, because the daemon fails closed: the in-band remedy (replay an
|
||||
// earlier revision while the State Store is up) is unavailable in exactly the
|
||||
// case that needs it.
|
||||
//
|
||||
// The tests drive the subcommands the way an operator does -- through
|
||||
// runRecovery -- rather than through the internal helpers, so the flag surface
|
||||
// and the exit codes are part of what is verified.
|
||||
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strconv"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/app/archied"
|
||||
"github.com/samcharles93/archie-core/internal/app/controlplane"
|
||||
"github.com/samcharles93/archie-core/internal/domain/storecontract"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/postgres"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps"
|
||||
)
|
||||
|
||||
// runRecoveryCmd runs one subcommand the way main does and returns its exit
|
||||
// code with both streams captured.
|
||||
func runRecoveryCmd(t *testing.T, args ...string) (int, string, string) {
|
||||
t.Helper()
|
||||
var stdout, stderr bytes.Buffer
|
||||
code := runRecovery(args, &stdout, &stderr)
|
||||
return code, stdout.String(), stderr.String()
|
||||
}
|
||||
|
||||
// recoveryFixture writes a config naming a fresh migrated database and returns
|
||||
// it with the task database on that database.
|
||||
func recoveryFixture(t *testing.T) (string, *pgstore.TaskDB) {
|
||||
t.Helper()
|
||||
url := pgtest.URL(t)
|
||||
configPath := writeConfigFor(t, t.TempDir(), url)
|
||||
return configPath, pgstore.On(pgstore.PoolAt(t, url))
|
||||
}
|
||||
|
||||
// seedTask writes one task so the database holds more than its settings.
|
||||
func seedTask(t *testing.T, st *pgstore.TaskDB, title string) {
|
||||
t.Helper()
|
||||
if _, err := st.EnqueueChatTask(t.Context(), "acme", "widget", title, "body", "implement", "", nil); err != nil {
|
||||
t.Fatalf("seed task %q: %v", title, err)
|
||||
}
|
||||
}
|
||||
|
||||
// execRaw runs one statement against the database the way an operator editing
|
||||
// a broken store would, bypassing every check the store applies.
|
||||
func execRaw(t *testing.T, st *pgstore.TaskDB, statement string) {
|
||||
t.Helper()
|
||||
if _, err := st.Pool.Exec(t.Context(), statement); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRecoveryValidateAcceptsAHealthyStore(t *testing.T) {
|
||||
configPath, st := recoveryFixture(t)
|
||||
seedTask(t, st, "healthy")
|
||||
seedStoreResources(t, st, configPath)
|
||||
|
||||
code, stdout, stderr := runRecoveryCmd(t, "validate", "-config", configPath)
|
||||
if code != 0 {
|
||||
t.Fatalf("validate exited %d: %s", code, stderr)
|
||||
}
|
||||
if !strings.Contains(stdout, "schema version") {
|
||||
t.Errorf("validate must report the schema version it verified; stdout = %q", stdout)
|
||||
}
|
||||
// The count is part of what the operator reads, and a check that reports
|
||||
// "0 stored resources" for a store full of them is worse than no check.
|
||||
if count := storedResourceCount(t, stdout); count == 0 {
|
||||
t.Errorf("validate reported no stored resources for a seeded store; stdout = %q", stdout)
|
||||
}
|
||||
}
|
||||
|
||||
// validate's verdict is only useful if it is the daemon's verdict. Boot refuses
|
||||
// on configuration.Validate over the file config with every stored resource
|
||||
// layered onto it (internal/app/archied/control_plane.go), not on the write
|
||||
// path's own per-resource decode, and the two disagree: the write path accepts
|
||||
// a scheduling policy boot rejects.
|
||||
func TestRecoveryValidateRunsTheGateBootRuns(t *testing.T) {
|
||||
configPath, st := recoveryFixture(t)
|
||||
seedStoreResources(t, st, configPath)
|
||||
|
||||
// The control: a store seeded from this config is one the daemon boots on.
|
||||
code, _, stderr := runRecoveryCmd(t, "validate", "-config", configPath)
|
||||
if code != 0 {
|
||||
t.Fatalf("validate exited %d on a store the daemon starts on: %s", code, stderr)
|
||||
}
|
||||
|
||||
// The upgrade case: a release defines a kind the store does not hold yet,
|
||||
// and validate runs before the State Store has started again. The State
|
||||
// Store seeds the kind it is missing, so the store is not the reason the
|
||||
// daemon would refuse to start.
|
||||
execRaw(t, st, `DELETE FROM resources WHERE kind='provider-settings'`)
|
||||
code, stdout, stderr := runRecoveryCmd(t, "validate", "-config", configPath)
|
||||
if code != 0 {
|
||||
t.Fatalf("validate refused a store missing a kind the State Store seeds; stderr = %q", stderr)
|
||||
}
|
||||
if count := storedResourceCount(t, stdout); count == 0 {
|
||||
t.Errorf("validate must still check the kinds the store does hold; stdout = %q", stdout)
|
||||
}
|
||||
|
||||
// A hand-edited value, or an older revision of one: the write path's own
|
||||
// validator never inspects dispatch.trigger, so only the config gate
|
||||
// catches it, and the daemon exits 1 on it (validateDispatch).
|
||||
execRaw(t, st, `UPDATE resources SET value='{"poll_interval":"1m","max_retries":3,"dispatch":{"trigger":"bogus"}}' WHERE kind='scheduling-policy'`)
|
||||
code, stdout, stderr = runRecoveryCmd(t, "validate", "-config", configPath)
|
||||
if code == 0 {
|
||||
t.Fatalf("validate accepted a stored policy the daemon refuses to boot with; stdout = %q", stdout)
|
||||
}
|
||||
if !strings.Contains(stderr, "dispatch.trigger") {
|
||||
t.Errorf("refusal must name what boot rejects; stderr = %q", stderr)
|
||||
}
|
||||
}
|
||||
|
||||
// A database the State Store never seeded holds no kinds at all. Its next
|
||||
// start seeds every kind from this same config, so archied layers those seeds
|
||||
// and starts: refusing it would send an operator to restore a snapshot for a
|
||||
// database the daemon boots on perfectly well.
|
||||
func TestRecoveryValidateAcceptsAnUnseededDatabase(t *testing.T) {
|
||||
configPath, _ := recoveryFixture(t)
|
||||
code, stdout, stderr := runRecoveryCmd(t, "validate", "-config", configPath)
|
||||
if code != 0 {
|
||||
t.Fatalf("validate refused a store the State Store would seed on its next start; stderr = %q", stderr)
|
||||
}
|
||||
if !strings.Contains(stdout, "0 stored resources validate") {
|
||||
t.Errorf("validate must report that there was nothing stored to check; stdout = %q", stdout)
|
||||
}
|
||||
}
|
||||
|
||||
// The subcommands advertise -h as the way to read their flags, and the serve
|
||||
// path in the same binary exits 0 for the same request, so a script probing the
|
||||
// recovery surface must not read a requested help as a failure.
|
||||
func TestRecoveryHelpExitsZero(t *testing.T) {
|
||||
commands := []string{archied.RecoveryBackup, archied.RecoveryRestore, archied.RecoveryValidate, archied.RecoveryRollback}
|
||||
for _, command := range commands {
|
||||
code, _, stderr := runRecoveryCmd(t, command, "-h")
|
||||
if code != 0 {
|
||||
t.Errorf("%s -h exited %d, want 0; stderr = %q", command, code, stderr)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// validate diagnoses a deployment; it is not the deployment. Resolving the boot
|
||||
// config must not create, append to, or rotate the daemon's log file or the
|
||||
// directory it lives in: a line stamped component="daemon" in archied's log is
|
||||
// indistinguishable from the daemon having written it.
|
||||
func TestRecoveryValidateLeavesTheDaemonLogAlone(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
configPath, logFile := writeConfigWithLogFile(t, dir)
|
||||
code, _, stderr := runRecoveryCmd(t, "validate", "-config", configPath)
|
||||
if code != 0 {
|
||||
t.Fatalf("validate exited %d: %s", code, stderr)
|
||||
}
|
||||
if _, err := os.Stat(logFile); !os.IsNotExist(err) {
|
||||
t.Fatalf("validate touched the daemon's log file %s (stat err = %v)", logFile, err)
|
||||
}
|
||||
if _, err := os.Stat(filepath.Dir(logFile)); !os.IsNotExist(err) {
|
||||
t.Errorf("validate created the log directory %s (stat err = %v)", filepath.Dir(logFile), err)
|
||||
}
|
||||
}
|
||||
|
||||
// validate's verdict is the daemon's verdict only if it reads the configuration
|
||||
// the daemon reads, and with no -config it reads whatever the one shared
|
||||
// helper resolves. The resolution rule itself is pinned where it lives
|
||||
// (internal/infrastructure/configuration); what only this test can pin is that
|
||||
// the command takes its default from that helper rather than deriving it.
|
||||
//
|
||||
// A relative XDG_CONFIG_HOME is the case that separates the two: the command
|
||||
// has to resolve ${XDG_CONFIG_HOME}/archie/config.toml relative to its working
|
||||
// directory, and a second derivation through os.UserConfigDir rejects a
|
||||
// relative value outright, leaving the command with no config to answer about.
|
||||
func TestRecoveryDefaultConfigResolvesWhereTheDaemonReads(t *testing.T) {
|
||||
// The second layout is the teeth: the command has to read the config at the
|
||||
// resolved path, not merely find some config somewhere under the config home.
|
||||
// A resolution that drifts finds nothing and validate has no verdict.
|
||||
tests := []struct {
|
||||
name string
|
||||
configDir string // relative to $XDG_CONFIG_HOME
|
||||
wantOK bool
|
||||
}{
|
||||
{name: "$XDG_CONFIG_HOME/archie/config.toml", configDir: "archie", wantOK: true},
|
||||
{name: "a config elsewhere in the config home is not the default", configDir: "wrong-place"},
|
||||
}
|
||||
for _, tc := range tests {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
t.Chdir(root)
|
||||
t.Setenv("XDG_CONFIG_HOME", "xdg")
|
||||
|
||||
configDir := filepath.Join(root, "xdg", tc.configDir)
|
||||
if err := os.MkdirAll(configDir, 0o700); err != nil {
|
||||
t.Fatalf("create %s: %v", configDir, err)
|
||||
}
|
||||
url := pgtest.URL(t)
|
||||
pgstore.PoolAt(t, url)
|
||||
configPath := writeConfigFor(t, configDir, url)
|
||||
code, stdout, stderr := runRecoveryCmd(t, "validate")
|
||||
if !tc.wantOK {
|
||||
if code == 0 {
|
||||
t.Fatalf("validate exited 0 with no config at the resolved path %s: %s", configPath, stdout)
|
||||
}
|
||||
return
|
||||
}
|
||||
if code != 0 {
|
||||
t.Fatalf("validate with no -config exited %d, so it did not read %s: %s", code, configPath, stderr)
|
||||
}
|
||||
if !strings.Contains(stdout, "stored resources validate") {
|
||||
t.Errorf("validate reported %q, want the verdict on the database the resolved config names", stdout)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// validate exists to answer "would archied start against this database". A
|
||||
// stored value that both gates refuse -- the write path stops it at Decode
|
||||
// (workflow.ExecutionSettings.Validate rejects a negative limit) and boot stops
|
||||
// on it too -- can only get here by bypassing the write path, which is exactly
|
||||
// the state the operator has no path back from.
|
||||
func TestRecoveryValidateRefusesWhatTheDaemonRefuses(t *testing.T) {
|
||||
configPath, st := recoveryFixture(t)
|
||||
seedResource(t, st, controlplane.WorkflowExecutionSettingsKind,
|
||||
`{"max_model_tool_steps":-1,"max_runtime_seconds":60,"max_consecutive_gate_failures":3}`, "hand-edited")
|
||||
code, _, stderr := runRecoveryCmd(t, "validate", "-config", configPath)
|
||||
if code == 0 {
|
||||
t.Fatal("validate accepted a stored resource the write path would refuse")
|
||||
}
|
||||
if !strings.Contains(stderr, controlplane.WorkflowExecutionSettingsKind) {
|
||||
t.Errorf("refusal must name the resource kind; stderr = %q", stderr)
|
||||
}
|
||||
}
|
||||
|
||||
// rollback is the one operation that closes the documented gap: with the State
|
||||
// Store stopped, it replays the value an earlier revision recorded through the
|
||||
// ordinary replace, so no rollback RPC is needed and the rollback itself is
|
||||
// audited as one more revision.
|
||||
func TestRecoveryRollbackReplaysTheRevisionThroughReplace(t *testing.T) {
|
||||
configPath, st := recoveryFixture(t)
|
||||
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"anthropic/claude"}`, "first")
|
||||
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"openai/gpt"}`, "second")
|
||||
|
||||
code, stdout, stderr := runRecoveryCmd(t, "rollback", "-config", configPath, "-kind", controlplane.ModelRoleAssignmentsKind)
|
||||
if code != 0 {
|
||||
t.Fatalf("rollback exited %d: %s", code, stderr)
|
||||
}
|
||||
if !strings.Contains(stdout, controlplane.ModelRoleAssignmentsKind) {
|
||||
t.Errorf("rollback must name the resource it replayed; stdout = %q", stdout)
|
||||
}
|
||||
resource, err := st.Resource(t.Context(), storecontract.DefaultOrgID, controlplane.ModelRoleAssignmentsKind)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if string(resource.Value) != `{"implement":"anthropic/claude"}` {
|
||||
t.Errorf("resource value = %s, want the first revision's value", resource.Value)
|
||||
}
|
||||
if resource.Version != 3 {
|
||||
t.Errorf("resource version = %d, want a new revision (3) rather than a rewrite of the old one", resource.Version)
|
||||
}
|
||||
history, err := st.ResourceHistory(t.Context(), storecontract.DefaultOrgID, controlplane.ModelRoleAssignmentsKind, 0)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if len(history) != 3 {
|
||||
t.Fatalf("history has %d revisions, want the rollback recorded as the third", len(history))
|
||||
}
|
||||
if history[0].Source != archied.OfflineRollbackSource {
|
||||
t.Errorf("newest revision source = %q, want %q so the rollback is auditable", history[0].Source, archied.OfflineRollbackSource)
|
||||
}
|
||||
}
|
||||
|
||||
// The revision to restore may be named, which is how an operator reaches past
|
||||
// the most recent change without replaying it first.
|
||||
func TestRecoveryRollbackRestoresANamedRevision(t *testing.T) {
|
||||
configPath, st := recoveryFixture(t)
|
||||
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"anthropic/claude"}`, "first")
|
||||
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"openai/gpt"}`, "second")
|
||||
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"google/gemini"}`, "third")
|
||||
|
||||
code, _, stderr := runRecoveryCmd(t, "rollback", "-config", configPath, "-kind", controlplane.ModelRoleAssignmentsKind, "-revision", "1")
|
||||
if code != 0 {
|
||||
t.Fatalf("rollback exited %d: %s", code, stderr)
|
||||
}
|
||||
resource, err := st.Resource(t.Context(), storecontract.DefaultOrgID, controlplane.ModelRoleAssignmentsKind)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if string(resource.Value) != `{"implement":"anthropic/claude"}` {
|
||||
t.Errorf("resource value = %s, want the value recorded at revision 1", resource.Value)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRecoveryRollbackRefusesWhatItCannotReplay(t *testing.T) {
|
||||
newStore := func(t *testing.T, revisions int) (string, *pgstore.TaskDB) {
|
||||
t.Helper()
|
||||
configPath, st := recoveryFixture(t)
|
||||
for i := range revisions {
|
||||
value := `{"implement":"anthropic/claude"}`
|
||||
if i > 0 {
|
||||
value = `{"implement":"openai/gpt"}`
|
||||
}
|
||||
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, value, "seed")
|
||||
}
|
||||
return configPath, st
|
||||
}
|
||||
|
||||
t.Run("unknown_kind", func(t *testing.T) {
|
||||
configPath, _ := newStore(t, 2)
|
||||
code, _, stderr := runRecoveryCmd(t, "rollback", "-config", configPath, "-kind", "not-a-resource")
|
||||
if code == 0 {
|
||||
t.Fatal("rollback of an unknown resource kind succeeded")
|
||||
}
|
||||
if !strings.Contains(stderr, "not-a-resource") {
|
||||
t.Errorf("refusal must name the kind; stderr = %q", stderr)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("no_earlier_revision", func(t *testing.T) {
|
||||
configPath, _ := newStore(t, 1)
|
||||
code, _, stderr := runRecoveryCmd(t, "rollback", "-config", configPath, "-kind", controlplane.ModelRoleAssignmentsKind)
|
||||
if code == 0 {
|
||||
t.Fatal("rollback with no earlier revision succeeded")
|
||||
}
|
||||
if !strings.Contains(stderr, "no earlier revision") {
|
||||
t.Errorf("refusal must say there is nothing to roll back to; stderr = %q", stderr)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("current_revision", func(t *testing.T) {
|
||||
configPath, _ := newStore(t, 2)
|
||||
code, _, stderr := runRecoveryCmd(t, "rollback", "-config", configPath, "-kind", controlplane.ModelRoleAssignmentsKind, "-revision", "2")
|
||||
if code == 0 {
|
||||
t.Fatal("rollback of the current revision succeeded")
|
||||
}
|
||||
if !strings.Contains(stderr, "is the current version") {
|
||||
t.Errorf("refusal must say the revision is already the current value; stderr = %q", stderr)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("live_state_store", func(t *testing.T) {
|
||||
configPath, st := newStore(t, 2)
|
||||
claim, err := postgres.AcquireOwnership(t.Context(), st.Pool, postgres.OwnerStateStore)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
t.Cleanup(func() { _ = claim.Release(t.Context()) })
|
||||
code, _, stderr := runRecoveryCmd(t, "rollback", "-config", configPath, "-kind", controlplane.ModelRoleAssignmentsKind)
|
||||
if code == 0 {
|
||||
t.Fatal("rollback against a live State Store succeeded")
|
||||
}
|
||||
if !strings.Contains(stderr, "stop the State Store") {
|
||||
t.Errorf("refusal must say to stop the State Store; stderr = %q", stderr)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
// A positional argument that is not a subcommand used to be ignored, leaving
|
||||
// an operator who mistyped a command watching a server start instead.
|
||||
func TestRecoveryRejectsAnUnknownSubcommand(t *testing.T) {
|
||||
var stdout, stderr bytes.Buffer
|
||||
code := runRecovery([]string{"backp", "-out", "x"}, &stdout, &stderr)
|
||||
if code == 0 {
|
||||
t.Fatal("an unknown subcommand exited 0")
|
||||
}
|
||||
if !strings.Contains(stderr.String(), "backp") {
|
||||
t.Errorf("refusal must name the unknown subcommand; stderr = %q", stderr.String())
|
||||
}
|
||||
}
|
||||
|
||||
// writeConfigWithLogFile is writeMinimalConfig plus the daemon's durable log
|
||||
// destination, which only the daemon may bring into existence.
|
||||
func writeConfigWithLogFile(t *testing.T, dir string) (string, string) {
|
||||
t.Helper()
|
||||
url := pgtest.URL(t)
|
||||
pgstore.PoolAt(t, url)
|
||||
configPath := writeConfigFor(t, dir, url)
|
||||
logFile := filepath.Join(dir, "logs", "archied.log")
|
||||
f, err := os.OpenFile(configPath, os.O_APPEND|os.O_WRONLY, 0o600)
|
||||
if err != nil {
|
||||
t.Fatalf("open config to append: %v", err)
|
||||
}
|
||||
defer func() {
|
||||
if err := f.Close(); err != nil {
|
||||
t.Fatalf("close config: %v", err)
|
||||
}
|
||||
}()
|
||||
if _, err := fmt.Fprintf(f, "\n[log]\nfile = %q\n", logFile); err != nil {
|
||||
t.Fatalf("append [log]: %v", err)
|
||||
}
|
||||
return configPath, logFile
|
||||
}
|
||||
|
||||
// seedStoreResources seeds the store the way the State Store seeds it at boot,
|
||||
// from the same config file the operator hands validate: the command's verdict
|
||||
// is about the pair, and a store whose settings never matched the config is a
|
||||
// state boot does not recognise either.
|
||||
//
|
||||
// The seeding builds its control-plane server from the shared provider set
|
||||
// (internal/infrastructure/workflowsteps), which is what every composition root
|
||||
// registers -- including openStateStoreControlPlane, the root helper the
|
||||
// recovery path uses. This test cannot call that unexported helper, so it
|
||||
// registers the same set itself rather than an empty manager: the definitions
|
||||
// are decoded with the vocabulary the served path validates against, which is
|
||||
// what makes the seeded values the ones validate is asked about.
|
||||
func seedStoreResources(t *testing.T, st *pgstore.TaskDB, configPath string) {
|
||||
t.Helper()
|
||||
doc, err := configuration.New(nil).Resolve(configPath, "")
|
||||
if err != nil {
|
||||
t.Fatalf("resolve %s: %v", configPath, err)
|
||||
}
|
||||
steps, err := workflowsteps.NewManager()
|
||||
if err != nil {
|
||||
t.Fatalf("register workflow step vocabulary: %v", err)
|
||||
}
|
||||
server, err := controlplane.NewServer(st, steps)
|
||||
if err != nil {
|
||||
t.Fatalf("build control plane server: %v", err)
|
||||
}
|
||||
_, skipped, err := server.ImportConfig(t.Context(), doc.Config)
|
||||
if err != nil {
|
||||
t.Fatalf("seed store resources: %v", err)
|
||||
}
|
||||
if len(skipped) > 0 {
|
||||
// This helper stands in for the State Store's own seeding, which seeds
|
||||
// every kind it can and leaves the rest absent. A skipped kind here
|
||||
// would mean the fixture store is missing a resource it claims to hold,
|
||||
// and the verdict under test would be about a different store.
|
||||
t.Fatalf("seed store resources: %d kind(s) refused: %+v", len(skipped), skipped)
|
||||
}
|
||||
}
|
||||
|
||||
// storedResourceCount reads the count validate reports out of its summary line.
|
||||
func storedResourceCount(t *testing.T, stdout string) int {
|
||||
t.Helper()
|
||||
before, found := strings.CutSuffix(stdout, " stored resources validate\n")
|
||||
if !found {
|
||||
t.Fatalf("no resource count in %q", stdout)
|
||||
}
|
||||
fields := strings.Fields(before)
|
||||
count, err := strconv.Atoi(fields[len(fields)-1])
|
||||
if err != nil {
|
||||
t.Fatalf("resource count in %q: %v", stdout, err)
|
||||
}
|
||||
return count
|
||||
}
|
||||
|
||||
// seedResource writes one revision of a control-plane resource through the
|
||||
// store, the way the control plane's replace does. The request ID is derived
|
||||
// from the label and the revision it produces: the store deduplicates a
|
||||
// repeated request ID, so a fixed one would make the second write of a series
|
||||
// a silent no-op.
|
||||
func seedResource(t *testing.T, st *pgstore.TaskDB, kind, value, label string) {
|
||||
t.Helper()
|
||||
current, err := st.Resource(t.Context(), storecontract.DefaultOrgID, kind)
|
||||
expected := int64(0)
|
||||
if err == nil {
|
||||
expected = current.Version
|
||||
}
|
||||
var document any
|
||||
if err := json.Unmarshal([]byte(value), &document); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
encoded, err := json.Marshal(document)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if _, err := st.PutResource(t.Context(), storecontract.ResourceWrite{
|
||||
OrgID: storecontract.DefaultOrgID,
|
||||
Kind: kind, Value: encoded, Actor: label, Source: "test",
|
||||
RequestID: fmt.Sprintf("%s-%d", label, expected+1), ExpectedVersion: expected,
|
||||
}); err != nil {
|
||||
t.Fatalf("seed resource %s: %v", kind, err)
|
||||
}
|
||||
}
|
||||
@@ -1,153 +0,0 @@
|
||||
// This file enforces the objective half of the UI Service deletion gate
|
||||
// (docs/prds/ui-service-boundary.md, "The deletion gate is objective"). The
|
||||
// composition half -- no config.Holder, no concrete task store, no Gateway
|
||||
// runtime type -- is pinned by internal/app/archieui's
|
||||
// TestComposeUIServerHoldsNoDaemonState. This pins the claim that test cannot
|
||||
// see: that the linked binary carries no daemon runtime at all. Go imports
|
||||
// are atomic, so a single reference to a type living beside a runtime relinks
|
||||
// the runtime, and the severance holds only while something re-measures it.
|
||||
|
||||
package main
|
||||
|
||||
import (
|
||||
"os/exec"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
const modulePath = "github.com/samcharles93/archie-core/"
|
||||
|
||||
// bannedCategory is one class of runtime the UI process must not link. The
|
||||
// names are the PRD's wording; the prefixes are how that class appears in
|
||||
// this module.
|
||||
type bannedCategory struct {
|
||||
name string
|
||||
prefixes []string
|
||||
}
|
||||
|
||||
var deletionGate = []bannedCategory{
|
||||
{"SQL/store implementation", []string{
|
||||
"modernc.org/sqlite",
|
||||
"github.com/jackc/pgx",
|
||||
modulePath + "internal/infrastructure/postgres",
|
||||
}},
|
||||
{"daemon runtime", []string{
|
||||
modulePath + "internal/daemon",
|
||||
modulePath + "internal/app/archied",
|
||||
modulePath + "internal/container",
|
||||
modulePath + "internal/worktree",
|
||||
modulePath + "internal/worktreerpc",
|
||||
}},
|
||||
{"workflow engine", []string{
|
||||
modulePath + "internal/domain/workflow",
|
||||
modulePath + "internal/taskrun",
|
||||
modulePath + "internal/agentexec",
|
||||
}},
|
||||
{"forge client", []string{
|
||||
modulePath + "internal/forge",
|
||||
modulePath + "internal/forgerpc",
|
||||
}},
|
||||
{"channel runtime", []string{
|
||||
modulePath + "internal/channels",
|
||||
}},
|
||||
{"model runtime", []string{
|
||||
modulePath + "internal/gateway",
|
||||
modulePath + "internal/infrastructure/modelcatalog",
|
||||
modulePath + "internal/domain/embedding",
|
||||
modulePath + "internal/infrastructure/embedding",
|
||||
}},
|
||||
{"secret runtime", []string{
|
||||
modulePath + "internal/secret",
|
||||
}},
|
||||
{"agent tooling", []string{
|
||||
modulePath + "internal/tools",
|
||||
modulePath + "internal/skill",
|
||||
modulePath + "internal/skillscript",
|
||||
modulePath + "internal/yaegiutil",
|
||||
modulePath + "internal/plugin",
|
||||
}},
|
||||
{"memory and curator runtime", []string{
|
||||
modulePath + "internal/domain/memory",
|
||||
modulePath + "internal/infrastructure/memory",
|
||||
modulePath + "internal/domain/curator",
|
||||
modulePath + "internal/infrastructure/sessioncurator",
|
||||
modulePath + "internal/infrastructure/skillcurator",
|
||||
}},
|
||||
{"broker transport", []string{
|
||||
modulePath + "internal/eventbus",
|
||||
modulePath + "internal/infrastructure/eventbus",
|
||||
modulePath + "internal/natsrpc",
|
||||
}},
|
||||
}
|
||||
|
||||
// bannedExact is banned as a package rather than as a subtree. Nothing may
|
||||
// reach the database through the UI process, but database/sql/driver and its
|
||||
// support package arrive from github.com/google/uuid's Valuer/Scanner methods
|
||||
// and bring no driver with them.
|
||||
var bannedExact = map[string]string{
|
||||
"database/sql": "SQL/store implementation",
|
||||
}
|
||||
|
||||
// gateExceptions are packages under a banned prefix that carry only contract,
|
||||
// vocabulary or view types. The severance moved the UI's references here so
|
||||
// the parent runtime would stop linking, which makes them the intended end
|
||||
// state rather than a tolerated leak.
|
||||
//
|
||||
// Each one must stay linked. An exception the UI no longer needs is a hole in
|
||||
// the fence, so this list is checked in both directions.
|
||||
var gateExceptions = []string{
|
||||
modulePath + "internal/channels/status",
|
||||
modulePath + "internal/domain/workflow/task",
|
||||
}
|
||||
|
||||
// under reports whether importPath is prefix or a package below it.
|
||||
func under(importPath, prefix string) bool {
|
||||
return importPath == prefix || strings.HasPrefix(importPath, prefix+"/")
|
||||
}
|
||||
|
||||
func TestUIProcessLinksNoDaemonRuntime(t *testing.T) {
|
||||
listed, err := exec.CommandContext(t.Context(), "go", "list", "-deps", ".").CombinedOutput()
|
||||
if err != nil {
|
||||
t.Fatalf("go list -deps .: %v\n%s", err, listed)
|
||||
}
|
||||
|
||||
linkedExceptions := make(map[string]bool, len(gateExceptions))
|
||||
for importPath := range strings.FieldsSeq(string(listed)) {
|
||||
if excepted(importPath, linkedExceptions) {
|
||||
continue
|
||||
}
|
||||
if category, banned := bannedExact[importPath]; banned {
|
||||
reportLink(t, importPath, category)
|
||||
}
|
||||
for _, category := range deletionGate {
|
||||
for _, prefix := range category.prefixes {
|
||||
if under(importPath, prefix) {
|
||||
reportLink(t, importPath, category.name)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
for _, exception := range gateExceptions {
|
||||
if !linkedExceptions[exception] {
|
||||
t.Errorf("%s is excepted from the deletion gate but is no longer linked; drop the exception instead of leaving its prefix open", exception)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func reportLink(t *testing.T, importPath, category string) {
|
||||
t.Helper()
|
||||
t.Errorf("archie-ui links %s (%s); the UI process reaches that capability over a contract, never in-process (docs/prds/ui-service-boundary.md, deletion gate)", importPath, category)
|
||||
}
|
||||
|
||||
// excepted reports whether importPath is allowed past the gate, recording
|
||||
// which exception admitted it so a stale one is reported.
|
||||
func excepted(importPath string, linked map[string]bool) bool {
|
||||
for _, exception := range gateExceptions {
|
||||
if under(importPath, exception) {
|
||||
linked[exception] = true
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
@@ -3,8 +3,6 @@
|
||||
// contracts. It is the .5.2 companion to archie-gateway and
|
||||
// archie-state-store: a thin main that parses process inputs and hands them
|
||||
// to archieui.Run.
|
||||
//
|
||||
// See docs/prds/ui-service-boundary.md for the ratified boundary.
|
||||
package main
|
||||
|
||||
import (
|
||||
@@ -29,17 +27,13 @@ func run() int {
|
||||
flag.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory (only [services.*] targets and [web] are read)")
|
||||
flag.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory")
|
||||
flag.StringVar(&options.Listen, "listen", "", "dashboard HTTP listen address (defaults to [web].listen, else 127.0.0.1:8484)")
|
||||
flag.StringVar(&options.Token, "token", "", "dashboard token; required for a non-loopback listener")
|
||||
flag.StringVar(&options.TokenFile, "token-file", "", "file holding the dashboard token, minted on first use")
|
||||
flag.StringVar(&options.OidcIssuer, "oidc-issuer", "", "identity provider issuer URL; requests must then carry a token it signed")
|
||||
flag.StringVar(&options.OidcAudience, "oidc-audience", "", "audience (resource identifier) this dashboard accepts tokens for; required with -oidc-issuer")
|
||||
flag.StringVar(&options.OidcClientID, "oidc-client-id", "", "provider client id for browser sign-in; omitted means no sign-in flow")
|
||||
flag.StringVar(&options.OidcClientSecretEnv, "oidc-client-secret-env", "", "name of the environment variable holding the sign-in client secret")
|
||||
flag.StringVar(&options.OidcRedirectURL, "oidc-redirect-url", "", "callback URL registered at the provider (path must be /oauth2/callback)")
|
||||
flag.StringVar(&options.Gateway.Target, "gateway-target", "", "archie-gateway gRPC address (defaults to [services.gateway].target)")
|
||||
flag.StringVar(&options.Gateway.Token, "gateway-token", "", "bearer token presented to archie-gateway")
|
||||
flag.StringVar(&options.State.Target, "state-target", "", "archie-state-store gRPC address (defaults to [services.state].target)")
|
||||
flag.StringVar(&options.State.Token, "state-token", "", "bearer token presented to archie-state-store")
|
||||
flag.DurationVar(&options.DependencyTimeout, "dependency-timeout", 0, "per-dependency readiness probe timeout (default 5s)")
|
||||
flag.DurationVar(&options.EventPollInterval, "event-poll-interval", 0, "how often the activity feed polls the State Store for new events (default 1s)")
|
||||
// BoolFunc rather than BoolVar so an unset flag stays distinguishable
|
||||
|
||||
@@ -1,960 +0,0 @@
|
||||
// Package main's smoke test runs the real archie-ui binary against a State
|
||||
// Store and a Gateway reached over loopback gRPC, and drives it through HTTP
|
||||
// the way an operator's browser does.
|
||||
//
|
||||
// The in-process suite (internal/app/archieui) proves the composition; this
|
||||
// proves the process: flags and configuration file, listener bind, dashboard
|
||||
// token, SPA assets, streamed chat, an operator task action crossing to the
|
||||
// Gateway, the degradations the PRD ratified, dependency loss while running,
|
||||
// and a clean SIGTERM. See docs/prds/ui-service-boundary.md, migration
|
||||
// sequence step 6.
|
||||
|
||||
package main
|
||||
|
||||
import (
|
||||
"bufio"
|
||||
"bytes"
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"io"
|
||||
"log/slog"
|
||||
"net"
|
||||
"net/http"
|
||||
"os"
|
||||
"os/exec"
|
||||
"path/filepath"
|
||||
"runtime"
|
||||
"strings"
|
||||
"sync"
|
||||
"syscall"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"google.golang.org/grpc"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/config"
|
||||
"github.com/samcharles93/archie-core/internal/domain/health"
|
||||
"github.com/samcharles93/archie-core/internal/domain/messaging"
|
||||
"github.com/samcharles93/archie-core/internal/domain/storecontract"
|
||||
"github.com/samcharles93/archie-core/internal/domain/taskactions"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/gatewayrpc"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
|
||||
"github.com/samcharles93/archie-core/internal/taskstate"
|
||||
"github.com/samcharles93/archie-core/internal/webui"
|
||||
)
|
||||
|
||||
const dashboardToken = "smoke-token"
|
||||
|
||||
// fakeGateway stands in for the archie-gateway process. The dashboard only
|
||||
// needs the Gateway to answer, stream, and accept an operator action, so the
|
||||
// rest satisfy messaging.ChatContract without pretending to do more.
|
||||
type fakeGateway struct {
|
||||
mu sync.Mutex
|
||||
actions []string
|
||||
}
|
||||
|
||||
func (f *fakeGateway) Snapshot(context.Context) (messaging.ChatSnapshot, error) {
|
||||
return messaging.ChatSnapshot{
|
||||
Sessions: []messaging.SessionContext{{
|
||||
SessionID: "s1",
|
||||
Source: messaging.SessionSource{Platform: "web", ChannelID: "dash"},
|
||||
}},
|
||||
Models: []string{"test/model"},
|
||||
ActiveModel: "test/model",
|
||||
ActivePersonas: map[string]string{},
|
||||
CancellationAvailable: true,
|
||||
}, nil
|
||||
}
|
||||
|
||||
func (f *fakeGateway) GetSession(context.Context, string) (messaging.SessionContext, bool, error) {
|
||||
return messaging.SessionContext{}, false, nil
|
||||
}
|
||||
|
||||
func (f *fakeGateway) RecentMessages(context.Context, string, int) ([]messaging.Message, error) {
|
||||
return nil, nil
|
||||
}
|
||||
|
||||
func (f *fakeGateway) RecentTurns(context.Context, string, int) ([]messaging.TurnRecord, error) {
|
||||
return nil, nil
|
||||
}
|
||||
|
||||
func (f *fakeGateway) Route(context.Context, messaging.Inbound) (messaging.ChatReply, error) {
|
||||
return messaging.ChatReply{Text: "routed", SessionID: "s1"}, nil
|
||||
}
|
||||
|
||||
// Stream emits the contract's documented order: started, a delta, then done.
|
||||
//
|
||||
// A turn that used a tool emits its tool event between the delta and the done,
|
||||
// which is where the Gateway's own stream reports completed tool activity.
|
||||
// Whether the dashboard renders it is the operator's setting, carried to this
|
||||
// process only by the published configuration projection (GitHub #821).
|
||||
func (f *fakeGateway) Stream(ctx context.Context, in messaging.Inbound) (<-chan messaging.ChatEvent, error) {
|
||||
events := make(chan messaging.ChatEvent, 4)
|
||||
go func() {
|
||||
defer close(events)
|
||||
turn := []messaging.ChatEvent{
|
||||
{Kind: "started", SessionID: "s1"},
|
||||
{Kind: "delta", Text: "hello " + in.Message.Text, SessionID: "s1"},
|
||||
{Kind: "done", SessionID: "s1"},
|
||||
}
|
||||
if in.Message.Text == toolCallPrompt {
|
||||
turn = []messaging.ChatEvent{
|
||||
{Kind: "started", SessionID: "s1"},
|
||||
{Kind: "tool", SessionID: "s1", Tool: messaging.ToolCallEvent{
|
||||
ID: "call-1", Name: "read_file", Parameters: `{"path":"main.go"}`,
|
||||
Output: "package main",
|
||||
}},
|
||||
{Kind: "delta", Text: "read it", SessionID: "s1"},
|
||||
{Kind: "done", SessionID: "s1"},
|
||||
}
|
||||
}
|
||||
for _, event := range turn {
|
||||
select {
|
||||
case events <- event:
|
||||
case <-ctx.Done():
|
||||
return
|
||||
}
|
||||
}
|
||||
}()
|
||||
return events, nil
|
||||
}
|
||||
|
||||
// toolCallPrompt is the message this suite sends when it wants the fake
|
||||
// Gateway to report a completed tool call in the turn.
|
||||
const toolCallPrompt = "read main.go"
|
||||
|
||||
func (f *fakeGateway) Cancel(context.Context, string) (messaging.ChatCancellation, error) {
|
||||
return messaging.ChatCancellation{Cancelled: true}, nil
|
||||
}
|
||||
|
||||
func (f *fakeGateway) SetPersona(context.Context, string, string) (bool, error) { return false, nil }
|
||||
|
||||
func (f *fakeGateway) ApplyTaskAction(context.Context, string, int64, taskstate.Action, taskactions.ActionPayload) (messaging.TaskActionResult, error) {
|
||||
return messaging.TaskActionResult{}, nil
|
||||
}
|
||||
|
||||
func (f *fakeGateway) ApplyOperatorTaskAction(_ context.Context, actor taskactions.Actor, id int64, action taskstate.Action, _ taskactions.ActionPayload) (messaging.TaskActionResult, error) {
|
||||
f.mu.Lock()
|
||||
defer f.mu.Unlock()
|
||||
f.actions = append(f.actions, fmt.Sprintf("%d:%s", id, action))
|
||||
return messaging.TaskActionResult{TaskID: id, Action: string(action)}, nil
|
||||
}
|
||||
|
||||
func (f *fakeGateway) applied() []string {
|
||||
f.mu.Lock()
|
||||
defer f.mu.Unlock()
|
||||
return append([]string(nil), f.actions...)
|
||||
}
|
||||
|
||||
// repoRoot walks up from this test's source directory to the module root, so
|
||||
// the build works regardless of the harness working directory.
|
||||
func repoRoot(t *testing.T) string {
|
||||
t.Helper()
|
||||
_, file, _, ok := runtime.Caller(0)
|
||||
if !ok {
|
||||
t.Fatal("cannot determine test source path")
|
||||
}
|
||||
dir := filepath.Dir(file)
|
||||
for {
|
||||
if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil {
|
||||
return dir
|
||||
}
|
||||
parent := filepath.Dir(dir)
|
||||
if parent == dir {
|
||||
t.Fatal("go.mod not found above test source")
|
||||
}
|
||||
dir = parent
|
||||
}
|
||||
}
|
||||
|
||||
func buildUIBinary(t *testing.T, dir string) string {
|
||||
t.Helper()
|
||||
bin := filepath.Join(dir, "archie-ui")
|
||||
cmd := exec.CommandContext(t.Context(), "go", "build", "-o", bin, "./cmd/archie-ui")
|
||||
cmd.Dir = repoRoot(t)
|
||||
cmd.Env = os.Environ()
|
||||
if out, err := cmd.CombinedOutput(); err != nil {
|
||||
t.Fatalf("go build archie-ui: %v\n%s", err, out)
|
||||
}
|
||||
return bin
|
||||
}
|
||||
|
||||
// syncBuffer is a concurrency-safe sink for the subprocess's stderr: the
|
||||
// os/exec goroutine writes while the test reads it to recover the bound
|
||||
// address and to report it on failure.
|
||||
type syncBuffer struct {
|
||||
mu sync.Mutex
|
||||
b bytes.Buffer
|
||||
}
|
||||
|
||||
func (s *syncBuffer) Write(p []byte) (int, error) {
|
||||
s.mu.Lock()
|
||||
defer s.mu.Unlock()
|
||||
return s.b.Write(p)
|
||||
}
|
||||
|
||||
func (s *syncBuffer) String() string {
|
||||
s.mu.Lock()
|
||||
defer s.mu.Unlock()
|
||||
return s.b.String()
|
||||
}
|
||||
|
||||
// serveGRPC runs register against a fresh loopback listener, returning the
|
||||
// dial target and a stop func so a test can take the dependency away.
|
||||
func serveGRPC(t *testing.T, register func(grpc.ServiceRegistrar)) (target string, stop func()) {
|
||||
t.Helper()
|
||||
listener, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", "127.0.0.1:0")
|
||||
if err != nil {
|
||||
t.Fatalf("listen: %v", err)
|
||||
}
|
||||
server := grpc.NewServer()
|
||||
register(server)
|
||||
go func() { _ = server.Serve(listener) }()
|
||||
t.Cleanup(server.Stop)
|
||||
return listener.Addr().String(), server.Stop
|
||||
}
|
||||
|
||||
// writeUIConfig writes the config.toml an operator would keep: the service
|
||||
// endpoints the UI dials live in it, so the process is started without
|
||||
// -gateway-target or -state-target and has to read them itself. The rest is
|
||||
// what configuration validation requires of any archie config file.
|
||||
func writeUIConfig(t *testing.T, dir, stateTarget, gatewayTarget string) string {
|
||||
t.Helper()
|
||||
path := filepath.Join(dir, "config.toml")
|
||||
content := fmt.Sprintf(`bot_user = "archie-bot"
|
||||
[forge]
|
||||
type = "github"
|
||||
host = "https://github.example.com"
|
||||
token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN" }
|
||||
[[repos]]
|
||||
owner = "acme"
|
||||
name = "widget"
|
||||
[services.state]
|
||||
target = %q
|
||||
[services.gateway]
|
||||
target = %q
|
||||
`, stateTarget, gatewayTarget)
|
||||
if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
|
||||
t.Fatalf("write ui config: %v", err)
|
||||
}
|
||||
return path
|
||||
}
|
||||
|
||||
// uiProcess is a running archie-ui, plus the address it actually bound.
|
||||
type uiProcess struct {
|
||||
cmd *exec.Cmd
|
||||
addr string
|
||||
log *syncBuffer
|
||||
}
|
||||
|
||||
func startUIProcess(t *testing.T, bin, cfg string) *uiProcess {
|
||||
t.Helper()
|
||||
// The process outlives t.Context() deliberately: that context is
|
||||
// cancelled just before cleanups run, which would SIGKILL archie-ui out
|
||||
// from under the graceful-shutdown check in stop. Cancelling this one is
|
||||
// registered first, so it runs last and only backstops a process that
|
||||
// ignored SIGTERM.
|
||||
ctx, cancel := context.WithCancel(context.WithoutCancel(t.Context()))
|
||||
t.Cleanup(cancel)
|
||||
cmd := exec.CommandContext(
|
||||
ctx, bin,
|
||||
"-config", cfg,
|
||||
"-listen", "127.0.0.1:0",
|
||||
"-token", dashboardToken,
|
||||
)
|
||||
cmd.Env = append(os.Environ(), "ARCHIE_GITHUB_TOKEN=test-token")
|
||||
var log syncBuffer
|
||||
cmd.Stderr = &log
|
||||
cmd.Stdout = &log
|
||||
if err := cmd.Start(); err != nil {
|
||||
t.Fatalf("start archie-ui: %v", err)
|
||||
}
|
||||
p := &uiProcess{cmd: cmd, log: &log}
|
||||
t.Cleanup(func() { p.stop(t) })
|
||||
|
||||
// -listen 127.0.0.1:0 means the kernel picks the port, so the bound
|
||||
// address comes back out of the process's own startup log.
|
||||
deadline := time.Now().Add(20 * time.Second)
|
||||
for time.Now().Before(deadline) && p.addr == "" {
|
||||
if cmd.ProcessState != nil {
|
||||
t.Fatalf("archie-ui exited early:\n%s", log.String())
|
||||
}
|
||||
p.parseAddr()
|
||||
if p.addr == "" {
|
||||
time.Sleep(25 * time.Millisecond)
|
||||
}
|
||||
}
|
||||
if p.addr == "" {
|
||||
t.Fatalf("did not recover the bound address from the log:\n%s", log.String())
|
||||
}
|
||||
waitHealthy(t, p)
|
||||
return p
|
||||
}
|
||||
|
||||
func (p *uiProcess) parseAddr() {
|
||||
scanner := bufio.NewScanner(strings.NewReader(p.log.String()))
|
||||
for scanner.Scan() {
|
||||
var record map[string]any
|
||||
if err := json.Unmarshal(scanner.Bytes(), &record); err != nil {
|
||||
continue
|
||||
}
|
||||
if msg, _ := record["msg"].(string); msg != "archie-ui running" {
|
||||
continue
|
||||
}
|
||||
if addr, ok := record["addr"].(string); ok && addr != "" {
|
||||
p.addr = addr
|
||||
return
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func waitHealthy(t *testing.T, p *uiProcess) {
|
||||
t.Helper()
|
||||
deadline := time.Now().Add(20 * time.Second)
|
||||
for time.Now().Before(deadline) {
|
||||
req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, "http://"+p.addr+"/healthz", nil)
|
||||
if err != nil {
|
||||
t.Fatalf("build liveness request: %v", err)
|
||||
}
|
||||
if resp, err := http.DefaultClient.Do(req); err == nil {
|
||||
_ = resp.Body.Close()
|
||||
if resp.StatusCode == http.StatusOK {
|
||||
return
|
||||
}
|
||||
}
|
||||
time.Sleep(25 * time.Millisecond)
|
||||
}
|
||||
t.Fatalf("/healthz never answered:\n%s", p.log.String())
|
||||
}
|
||||
|
||||
// stop ends the process the way a service manager does and reports a
|
||||
// non-graceful exit, which is how a shutdown-ordering regression surfaces.
|
||||
func (p *uiProcess) stop(t *testing.T) {
|
||||
t.Helper()
|
||||
if p.cmd.Process == nil || p.cmd.ProcessState != nil {
|
||||
return
|
||||
}
|
||||
if err := p.cmd.Process.Signal(syscall.SIGTERM); err != nil {
|
||||
t.Errorf("SIGTERM archie-ui: %v", err)
|
||||
return
|
||||
}
|
||||
done := make(chan error, 1)
|
||||
go func() { done <- p.cmd.Wait() }()
|
||||
select {
|
||||
case err := <-done:
|
||||
if err != nil {
|
||||
t.Errorf("archie-ui exited %v after SIGTERM, want a clean shutdown:\n%s", err, p.log.String())
|
||||
}
|
||||
case <-time.After(20 * time.Second):
|
||||
_ = p.cmd.Process.Kill()
|
||||
t.Errorf("archie-ui did not exit within 20s of SIGTERM:\n%s", p.log.String())
|
||||
}
|
||||
}
|
||||
|
||||
// reply is one dashboard response, already read and closed. The assertions
|
||||
// want the status and the bytes rather than a live body, and handing back a
|
||||
// closed value keeps the close where the read is.
|
||||
type reply struct {
|
||||
status int
|
||||
header http.Header
|
||||
body []byte
|
||||
}
|
||||
|
||||
func (r reply) cookies() []*http.Cookie {
|
||||
return (&http.Response{Header: r.header}).Cookies()
|
||||
}
|
||||
|
||||
// dashboard is a browser-shaped client for the running process.
|
||||
type dashboard struct {
|
||||
t *testing.T
|
||||
base string
|
||||
client *http.Client
|
||||
}
|
||||
|
||||
// noRedirect returns a dashboard that reports a redirect rather than
|
||||
// following it, so an exchange can be inspected instead of chased. Following
|
||||
// it here would land on the clean URL without the cookie jar a browser has.
|
||||
func (d dashboard) noRedirect() dashboard {
|
||||
d.client = &http.Client{CheckRedirect: func(*http.Request, []*http.Request) error {
|
||||
return http.ErrUseLastResponse
|
||||
}}
|
||||
return d
|
||||
}
|
||||
|
||||
func (d dashboard) do(req *http.Request) reply {
|
||||
d.t.Helper()
|
||||
client := d.client
|
||||
if client == nil {
|
||||
client = http.DefaultClient
|
||||
}
|
||||
resp, err := client.Do(req)
|
||||
if err != nil {
|
||||
d.t.Fatalf("%s %s: %v", req.Method, req.URL.Path, err)
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
body, err := io.ReadAll(resp.Body)
|
||||
if err != nil {
|
||||
d.t.Fatalf("read %s: %v", req.URL.Path, err)
|
||||
}
|
||||
return reply{status: resp.StatusCode, header: resp.Header, body: body}
|
||||
}
|
||||
|
||||
func (d dashboard) request(method, path, body string, authorized bool) *http.Request {
|
||||
d.t.Helper()
|
||||
var reader io.Reader = http.NoBody
|
||||
if body != "" {
|
||||
reader = strings.NewReader(body)
|
||||
}
|
||||
req, err := http.NewRequestWithContext(d.t.Context(), method, d.base+path, reader)
|
||||
if err != nil {
|
||||
d.t.Fatalf("build %s %s: %v", method, path, err)
|
||||
}
|
||||
if authorized {
|
||||
req.Header.Set("Authorization", "Bearer "+dashboardToken)
|
||||
}
|
||||
if body != "" {
|
||||
req.Header.Set("Content-Type", "application/json")
|
||||
req.Header.Set("X-Archie-CSRF", "1")
|
||||
}
|
||||
return req
|
||||
}
|
||||
|
||||
func (d dashboard) get(path string) reply {
|
||||
d.t.Helper()
|
||||
return d.do(d.request(http.MethodGet, path, "", true))
|
||||
}
|
||||
|
||||
// chatFrame is one `data: {...}` frame of the chat stream, decoded into the
|
||||
// fields this suite reads. The UI process only ever receives these over HTTP,
|
||||
// so asserting on them is asserting on what the browser is handed.
|
||||
type chatFrame struct {
|
||||
Type string `json:"type"`
|
||||
Text string `json:"text"`
|
||||
Tool string `json:"tool"`
|
||||
}
|
||||
|
||||
// streamChat runs one chat turn over the real HTTP stream and returns every
|
||||
// frame up to and including the terminating done.
|
||||
func streamChat(t *testing.T, d dashboard, prompt string) []chatFrame {
|
||||
t.Helper()
|
||||
body, err := json.Marshal(map[string]string{"text": prompt, "channel_id": "dash"})
|
||||
if err != nil {
|
||||
t.Fatalf("encode the chat turn: %v", err)
|
||||
}
|
||||
resp, err := http.DefaultClient.Do(d.request(http.MethodPost, "/api/chat/stream", string(body), true))
|
||||
if err != nil {
|
||||
t.Fatalf("POST /api/chat/stream: %v", err)
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
if resp.StatusCode != http.StatusOK {
|
||||
t.Fatalf("POST /api/chat/stream = %d, want 200", resp.StatusCode)
|
||||
}
|
||||
var frames []chatFrame
|
||||
scanner := bufio.NewScanner(resp.Body)
|
||||
for scanner.Scan() {
|
||||
payload, ok := strings.CutPrefix(scanner.Text(), "data: ")
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
var frame chatFrame
|
||||
if err := json.Unmarshal([]byte(payload), &frame); err != nil {
|
||||
t.Fatalf("decode stream frame %q: %v", payload, err)
|
||||
}
|
||||
frames = append(frames, frame)
|
||||
if frame.Type == "done" {
|
||||
break
|
||||
}
|
||||
}
|
||||
if err := scanner.Err(); err != nil {
|
||||
t.Fatalf("read the chat stream: %v", err)
|
||||
}
|
||||
return frames
|
||||
}
|
||||
|
||||
// seedStore fills a real task database and publishes the configuration
|
||||
// projection, so everything the dashboard renders arrives over the wire from
|
||||
// a store this process never opens.
|
||||
//
|
||||
// The document is rendered by webui.BuildConfigView -- the same function the
|
||||
// daemon calls -- from a config.Config rather than hand-written as a
|
||||
// ConfigView. A suite that hand-writes the document cannot catch a producer
|
||||
// that forgets to publish a field, which is the failure mode this covers:
|
||||
// chat.show_tool_calls, the operator name and the channel flag all reach the
|
||||
// extracted process through this projection and nowhere else (GitHub #821).
|
||||
func seedStore(t *testing.T, dir string) *pgstore.TaskDB {
|
||||
t.Helper()
|
||||
st := pgstore.Open(t)
|
||||
t.Cleanup(func() { _ = st.Close() })
|
||||
|
||||
if _, err := st.EnqueueIssue(t.Context(), "acme", "widget", 7, "smoke task", "body", "", ""); err != nil {
|
||||
t.Fatalf("seed task: %v", err)
|
||||
}
|
||||
tasks, err := st.Tasks(t.Context(), 10)
|
||||
if err != nil || len(tasks) != 1 {
|
||||
t.Fatalf("seeded tasks = %d (%v), want 1", len(tasks), err)
|
||||
}
|
||||
seeded := tasks[0]
|
||||
seeded.PRNumber = 34
|
||||
if err := st.Update(t.Context(), &seeded); err != nil {
|
||||
t.Fatalf("record PR number: %v", err)
|
||||
}
|
||||
|
||||
publishConfig(t, st, daemonConfig(true))
|
||||
return st
|
||||
}
|
||||
|
||||
// daemonConfig is the configuration the daemon would hold for this smoke run.
|
||||
// showToolCalls is the setting the chat page's expansion is gated on.
|
||||
func daemonConfig(showToolCalls bool) config.Config {
|
||||
return config.Config{
|
||||
BotUser: "archie-bot",
|
||||
Forge: config.Forge{Type: "github", Host: "https://github.example.com"},
|
||||
Repos: []config.Repo{{Owner: "acme", Name: "widget", Base: "main"}},
|
||||
Chat: config.ChatConfig{
|
||||
ShowToolCalls: showToolCalls,
|
||||
Operator: "Sam",
|
||||
WebhookAddr: "127.0.0.1:9099",
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
// publishConfig renders cfg the way the daemon's configuration owner does and
|
||||
// writes the result to the store the UI process reads it back from. The UI
|
||||
// process holds no configuration, so this is the only path by which a setting
|
||||
// reaches its pages.
|
||||
func publishConfig(t *testing.T, st *pgstore.TaskDB, cfg config.Config) {
|
||||
t.Helper()
|
||||
document, err := json.Marshal(webui.BuildConfigView(webui.ConfigViewInput{Config: cfg}))
|
||||
if err != nil {
|
||||
t.Fatalf("render the configuration projection: %v", err)
|
||||
}
|
||||
if err := st.PutConfigSnapshot(t.Context(), storecontract.ConfigSnapshot{
|
||||
Schema: webui.ConfigViewSchema, Document: document,
|
||||
}); err != nil {
|
||||
t.Fatalf("publish config snapshot: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// TestUIProcessLinksMultiIdentityTaskRowsToTheirOwningForge drives the real
|
||||
// binary against a State Store holding a multi-identity deployment's
|
||||
// projection. Task rows in such a deployment used to render no link at all:
|
||||
// the projection carried the default identity's forge alone, so the renderer
|
||||
// withheld rather than pointing every row at the wrong forge
|
||||
// (archie-core-pv6t). With per-identity forges published, each row is
|
||||
// attributed to the identity that owns it, by identity name first and repo
|
||||
// ownership second.
|
||||
//
|
||||
// Its own store and process: it publishes a different projection than the
|
||||
// single-identity smoke test, and republishing over a shared one would rewire
|
||||
// that test's page underneath it.
|
||||
func TestUIProcessLinksMultiIdentityTaskRowsToTheirOwningForge(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
st := pgstore.Open(t)
|
||||
t.Cleanup(func() { _ = st.Close() })
|
||||
|
||||
// One task carrying its identity (name resolves it), one without an
|
||||
// identity but on a repo only the Gitea identity owns (ownership
|
||||
// resolves it), and one on a repo both identities claim (ambiguous, so
|
||||
// it falls back to the default forge).
|
||||
for _, seed := range []struct {
|
||||
owner, repo, identity string
|
||||
number int
|
||||
}{
|
||||
{owner: "acme", repo: "widget", identity: "gitea-bot", number: 7},
|
||||
{owner: "beta", repo: "svc", number: 8},
|
||||
{owner: "acme", repo: "shared", number: 9},
|
||||
} {
|
||||
if _, err := st.EnqueueIssue(t.Context(), seed.owner, seed.repo, seed.number, "seeded", "body", "", seed.identity); err != nil {
|
||||
t.Fatalf("seed %s/%s: %v", seed.owner, seed.repo, err)
|
||||
}
|
||||
}
|
||||
|
||||
published, err := json.Marshal(webui.ConfigView{
|
||||
Identity: webui.IdentityView{BotUser: "archie-bot", ForgeType: "github", ForgeHost: "https://github.example.com"},
|
||||
MultiIdentity: true,
|
||||
Identities: []webui.ForgeIdentityView{
|
||||
{
|
||||
Name: "gitea-bot", ForgeType: "gitea", ForgeHost: "https://gitea.example.com",
|
||||
Repos: []webui.ForgeRepoView{{Owner: "acme", Name: "widget"}, {Owner: "acme", Name: "shared"}},
|
||||
},
|
||||
{
|
||||
Name: "github-bot", ForgeType: "github", ForgeHost: "https://github.example.com",
|
||||
Repos: []webui.ForgeRepoView{{Owner: "beta", Name: "svc"}, {Owner: "acme", Name: "shared"}},
|
||||
},
|
||||
},
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := st.PutConfigSnapshot(t.Context(), storecontract.ConfigSnapshot{
|
||||
Schema: webui.ConfigViewSchema, Document: published,
|
||||
}); err != nil {
|
||||
t.Fatalf("publish config snapshot: %v", err)
|
||||
}
|
||||
|
||||
stateTarget, stopState := serveGRPC(t, func(r grpc.ServiceRegistrar) {
|
||||
eda := pgstore.EDA(t, nil)
|
||||
staterpc.RegisterServer(r, staterpc.Deps{
|
||||
Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st,
|
||||
Log: slog.New(slog.DiscardHandler),
|
||||
})
|
||||
})
|
||||
defer stopState()
|
||||
gatewayTarget, stopGateway := serveGRPC(t, func(r grpc.ServiceRegistrar) {
|
||||
gatewayrpc.RegisterServer(r, &fakeGateway{})
|
||||
})
|
||||
defer stopGateway()
|
||||
|
||||
ui := startUIProcess(t, buildUIBinary(t, dir), writeUIConfig(t, dir, stateTarget, gatewayTarget))
|
||||
d := dashboard{t: t, base: "http://" + ui.addr}
|
||||
|
||||
got := d.get("/api/tasks")
|
||||
if got.status != http.StatusOK {
|
||||
t.Fatalf("GET /api/tasks = %d (%s), want 200", got.status, got.body)
|
||||
}
|
||||
var rows []struct {
|
||||
Owner string `json:"owner"`
|
||||
Repo string `json:"repo"`
|
||||
IssueNumber int `json:"issue_number"`
|
||||
RepoURL string `json:"repo_url"`
|
||||
IssueURL string `json:"issue_url"`
|
||||
}
|
||||
if err := json.Unmarshal(got.body, &rows); err != nil {
|
||||
t.Fatalf("decode task rows: %v (%s)", err, got.body)
|
||||
}
|
||||
if len(rows) != 3 {
|
||||
t.Fatalf("task rows = %d, want the 3 seeded behind the State Store (%s)", len(rows), got.body)
|
||||
}
|
||||
|
||||
want := map[string]string{
|
||||
"acme/widget#7": "https://gitea.example.com/acme/widget/issues/7",
|
||||
"beta/svc#8": "https://github.example.com/beta/svc/issues/8",
|
||||
"acme/shared#9": "https://github.example.com/acme/shared/issues/9",
|
||||
}
|
||||
for _, row := range rows {
|
||||
key := fmt.Sprintf("%s/%s#%d", row.Owner, row.Repo, row.IssueNumber)
|
||||
expected, ok := want[key]
|
||||
if !ok {
|
||||
t.Errorf("unexpected row %q (%s)", key, got.body)
|
||||
continue
|
||||
}
|
||||
if row.RepoURL == "" || row.IssueURL != expected {
|
||||
t.Errorf("row %s links = %q, %q; want %q", key, row.RepoURL, row.IssueURL, expected)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestUIProcessServesTheDashboardAgainstLiveDependencies(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
st := seedStore(t, dir)
|
||||
gateway := &fakeGateway{}
|
||||
|
||||
stateTarget, stopState := serveGRPC(t, func(r grpc.ServiceRegistrar) {
|
||||
eda := pgstore.EDA(t, nil)
|
||||
staterpc.RegisterServer(r, staterpc.Deps{
|
||||
Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st,
|
||||
Log: slog.New(slog.DiscardHandler),
|
||||
})
|
||||
})
|
||||
gatewayTarget, _ := serveGRPC(t, func(r grpc.ServiceRegistrar) {
|
||||
gatewayrpc.RegisterServer(r, gateway)
|
||||
})
|
||||
|
||||
ui := startUIProcess(t, buildUIBinary(t, dir), writeUIConfig(t, dir, stateTarget, gatewayTarget))
|
||||
d := dashboard{t: t, base: "http://" + ui.addr}
|
||||
|
||||
t.Run("liveness stays unauthenticated", func(t *testing.T) {
|
||||
for _, path := range []string{"/healthz", "/health"} {
|
||||
if got := d.do(d.request(http.MethodGet, path, "", false)); got.status != http.StatusOK {
|
||||
t.Errorf("GET %s = %d without a token, want 200: probes must not need the dashboard token", path, got.status)
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("an unauthenticated API request is refused", func(t *testing.T) {
|
||||
if got := d.do(d.request(http.MethodGet, "/api/tasks", "", false)); got.status != http.StatusUnauthorized {
|
||||
t.Errorf("GET /api/tasks = %d without a token, want 401", got.status)
|
||||
}
|
||||
wrong := d.request(http.MethodGet, "/api/tasks", "", false)
|
||||
wrong.Header.Set("Authorization", "Bearer not-the-token")
|
||||
if got := d.do(wrong); got.status != http.StatusUnauthorized {
|
||||
t.Errorf("GET /api/tasks = %d with a wrong token, want 401", got.status)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("the token in the URL is exchanged for a cookie", func(t *testing.T) {
|
||||
got := d.noRedirect().do(d.request(http.MethodGet, "/?t="+dashboardToken, "", false))
|
||||
if got.status != http.StatusSeeOther {
|
||||
t.Fatalf("GET /?t=<token> = %d, want 303 onto the clean URL", got.status)
|
||||
}
|
||||
var carried bool
|
||||
for _, cookie := range got.cookies() {
|
||||
if cookie.Value == dashboardToken && cookie.HttpOnly {
|
||||
carried = true
|
||||
}
|
||||
}
|
||||
if !carried {
|
||||
t.Errorf("no HttpOnly cookie carried the token; it would stay in browser history (%v)", got.cookies())
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("task rows carry forge links from the published projection", func(t *testing.T) {
|
||||
got := d.get("/api/tasks")
|
||||
if got.status != http.StatusOK {
|
||||
t.Fatalf("GET /api/tasks = %d (%s), want 200", got.status, got.body)
|
||||
}
|
||||
var rows []struct {
|
||||
ID int64 `json:"id"`
|
||||
RepoURL string `json:"repo_url"`
|
||||
IssueURL string `json:"issue_url"`
|
||||
PRURL string `json:"pr_url"`
|
||||
}
|
||||
if err := json.Unmarshal(got.body, &rows); err != nil {
|
||||
t.Fatalf("decode task rows: %v (%s)", err, got.body)
|
||||
}
|
||||
if len(rows) != 1 {
|
||||
t.Fatalf("task rows = %d, want the 1 seeded behind the State Store (%s)", len(rows), got.body)
|
||||
}
|
||||
const repoURL = "https://github.example.com/acme/widget"
|
||||
if rows[0].RepoURL != repoURL || rows[0].IssueURL != repoURL+"/issues/7" || rows[0].PRURL != repoURL+"/pull/34" {
|
||||
t.Errorf("forge links = %q, %q, %q; want them built from the daemon's published projection, since this process holds no configuration of its own",
|
||||
rows[0].RepoURL, rows[0].IssueURL, rows[0].PRURL)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("the SPA and its assets are served", func(t *testing.T) {
|
||||
index := d.get("/")
|
||||
if index.status != http.StatusOK || !bytes.Contains(bytes.ToLower(index.body), []byte("<!doctype html")) {
|
||||
t.Errorf("GET / = %d serving %d bytes; want the embedded index.html", index.status, len(index.body))
|
||||
}
|
||||
for path, wantType := range map[string]string{
|
||||
"/assets/index.js": "javascript",
|
||||
"/assets/index.css": "css",
|
||||
} {
|
||||
asset := d.get(path)
|
||||
if asset.status != http.StatusOK {
|
||||
t.Errorf("GET %s = %d, want the embedded asset", path, asset.status)
|
||||
continue
|
||||
}
|
||||
if contentType := asset.header.Get("Content-Type"); !strings.Contains(contentType, wantType) {
|
||||
t.Errorf("GET %s Content-Type = %q, want %s", path, contentType, wantType)
|
||||
}
|
||||
if len(asset.body) == 0 {
|
||||
t.Errorf("GET %s served an empty body", path)
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("chat streams over the Gateway contract", func(t *testing.T) {
|
||||
req := d.request(http.MethodPost, "/api/chat/stream", `{"text":"there","channel_id":"dash"}`, true)
|
||||
resp, err := http.DefaultClient.Do(req)
|
||||
if err != nil {
|
||||
t.Fatalf("POST /api/chat/stream: %v", err)
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
if resp.StatusCode != http.StatusOK {
|
||||
t.Fatalf("POST /api/chat/stream = %d, want 200", resp.StatusCode)
|
||||
}
|
||||
if contentType := resp.Header.Get("Content-Type"); !strings.Contains(contentType, "text/event-stream") {
|
||||
t.Fatalf("stream Content-Type = %q, want text/event-stream", contentType)
|
||||
}
|
||||
var kinds []string
|
||||
var text string
|
||||
scanner := bufio.NewScanner(resp.Body)
|
||||
for scanner.Scan() {
|
||||
payload, ok := strings.CutPrefix(scanner.Text(), "data: ")
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
var frame struct {
|
||||
Type string `json:"type"`
|
||||
Text string `json:"text"`
|
||||
}
|
||||
if err := json.Unmarshal([]byte(payload), &frame); err != nil {
|
||||
t.Fatalf("decode stream frame %q: %v", payload, err)
|
||||
}
|
||||
kinds = append(kinds, frame.Type)
|
||||
if frame.Type == "delta" {
|
||||
text += frame.Text
|
||||
}
|
||||
if frame.Type == "done" {
|
||||
break
|
||||
}
|
||||
}
|
||||
if strings.Join(kinds, ",") != "started,delta,done" {
|
||||
t.Errorf("stream frames = %v, want started,delta,done in order", kinds)
|
||||
}
|
||||
if text != "hello there" {
|
||||
t.Errorf("streamed text = %q, want the Gateway's reply relayed verbatim", text)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("the daemon's show_tool_calls setting decides whether tool calls reach the chat page", func(t *testing.T) {
|
||||
// The chat page expands a completed tool call only when the frame
|
||||
// arrives, and this process has no [chat] section of its own: the
|
||||
// setting reaches it through the published projection alone. A turn
|
||||
// streamed with the setting off must carry no tool frame, and one
|
||||
// streamed with it on must carry the tool the Gateway reported
|
||||
// (GitHub #821).
|
||||
//
|
||||
// Each case republishes before streaming, the way a config reload
|
||||
// does; the default is restored afterwards so a later subtest does
|
||||
// not inherit whichever case ran last.
|
||||
tests := []struct {
|
||||
name string
|
||||
showTools bool
|
||||
wantFrame bool
|
||||
}{
|
||||
{name: "off", showTools: false, wantFrame: false},
|
||||
{name: "on", showTools: true, wantFrame: true},
|
||||
}
|
||||
for _, tc := range tests {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
publishConfig(t, st, daemonConfig(tc.showTools))
|
||||
|
||||
frames := streamChat(t, d, toolCallPrompt)
|
||||
var sawTool bool
|
||||
for _, frame := range frames {
|
||||
if frame.Tool == "read_file" {
|
||||
sawTool = true
|
||||
}
|
||||
if frame.Type == "done" {
|
||||
break
|
||||
}
|
||||
}
|
||||
if sawTool != tc.wantFrame {
|
||||
t.Errorf("show_tool_calls=%v produced tool frame = %v, want %v; frames = %+v",
|
||||
tc.showTools, sawTool, tc.wantFrame, frames)
|
||||
}
|
||||
})
|
||||
}
|
||||
publishConfig(t, st, daemonConfig(true))
|
||||
})
|
||||
|
||||
t.Run("an operator task action crosses to the Gateway", func(t *testing.T) {
|
||||
listed := d.get("/api/tasks")
|
||||
var rows []struct {
|
||||
ID int64 `json:"id"`
|
||||
}
|
||||
if err := json.Unmarshal(listed.body, &rows); err != nil || len(rows) != 1 {
|
||||
t.Fatalf("decode task rows: %v (%s)", err, listed.body)
|
||||
}
|
||||
path := fmt.Sprintf("/api/tasks/%d/action", rows[0].ID)
|
||||
action := string(taskstate.ActionCancel)
|
||||
if got := d.do(d.request(http.MethodPost, path, `{"action":"`+action+`"}`, true)); got.status != http.StatusOK {
|
||||
t.Fatalf("POST %s = %d (%s), want 200", path, got.status, got.body)
|
||||
}
|
||||
want := fmt.Sprintf("%d:%s", rows[0].ID, action)
|
||||
if applied := gateway.applied(); len(applied) != 1 || applied[0] != want {
|
||||
t.Errorf("Gateway saw %v, want exactly [%s]: the UI must not mutate task state itself", applied, want)
|
||||
}
|
||||
|
||||
// The same action without the CSRF header is refused, so a
|
||||
// cross-site form post cannot drive the daemon.
|
||||
noCSRF := d.request(http.MethodPost, path, "", true)
|
||||
noCSRF.Body = io.NopCloser(strings.NewReader(`{"action":"` + action + `"}`))
|
||||
noCSRF.Header.Set("Content-Type", "application/json")
|
||||
if got := d.do(noCSRF); got.status != http.StatusForbidden {
|
||||
t.Errorf("POST %s without the CSRF header = %d, want 403", path, got.status)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("capture intake is served without the dashboard token", func(t *testing.T) {
|
||||
accepted := d.do(d.request(http.MethodPost, "/webhooks/capture/demo", "", false))
|
||||
if accepted.status != http.StatusAccepted {
|
||||
t.Fatalf("POST /webhooks/capture/demo = %d (%s), want 202: this process is the only listener serving intake after the cutover", accepted.status, accepted.body)
|
||||
}
|
||||
listed := d.get("/api/captures")
|
||||
if listed.status != http.StatusOK || !strings.Contains(string(listed.body), `"enabled":true`) {
|
||||
t.Errorf("GET /api/captures = %d (%s), want the capture list over the State Store", listed.status, listed.body)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("routes with no owner degrade explicitly", func(t *testing.T) {
|
||||
// The daemon's log feed is host-local and has no contract, so the
|
||||
// page reports itself off rather than erroring
|
||||
// (docs/prds/ui-service-boundary.md, route family table).
|
||||
logs := d.get("/api/logs")
|
||||
if logs.status != http.StatusOK || !strings.Contains(string(logs.body), `"disabled":true`) {
|
||||
t.Errorf("GET /api/logs = %d (%s), want an explicit disabled report", logs.status, logs.body)
|
||||
}
|
||||
if version := d.get("/api/version"); version.status != http.StatusNotImplemented {
|
||||
t.Errorf("GET /api/version = %d, want 501: host-local update reporting stays with the daemon", version.status)
|
||||
}
|
||||
|
||||
// Configuration renders from the published snapshot, and this
|
||||
// process is not a second writer.
|
||||
rendered := d.get("/api/config")
|
||||
if rendered.status != http.StatusOK {
|
||||
t.Fatalf("GET /api/config = %d (%s), want 200", rendered.status, rendered.body)
|
||||
}
|
||||
var view webui.ConfigView
|
||||
if err := json.Unmarshal(rendered.body, &view); err != nil {
|
||||
t.Fatalf("decode config view: %v (%s)", err, rendered.body)
|
||||
}
|
||||
if view.Identity.BotUser != "archie-bot" {
|
||||
t.Errorf("config view = %s, want the published projection rendered read-only", rendered.body)
|
||||
}
|
||||
if got := d.do(d.request(http.MethodPatch, "/api/config", `{}`, true)); got.status != http.StatusMethodNotAllowed {
|
||||
t.Errorf("PATCH /api/config = %d, want 405: configuration is read here and written through the control plane", got.status)
|
||||
}
|
||||
|
||||
// The setup checklist reads the same projection. It reported
|
||||
// nothing here while it needed a live config.Holder this process
|
||||
// never receives (archie-core-ml30).
|
||||
setup := d.get("/api/setup")
|
||||
if setup.status != http.StatusOK {
|
||||
t.Fatalf("GET /api/setup = %d (%s), want 200", setup.status, setup.body)
|
||||
}
|
||||
var checklist struct {
|
||||
Steps []struct {
|
||||
Title string `json:"title"`
|
||||
Done bool `json:"done"`
|
||||
} `json:"steps"`
|
||||
Operator string `json:"operator"`
|
||||
}
|
||||
if err := json.Unmarshal(setup.body, &checklist); err != nil {
|
||||
t.Fatalf("decode setup checklist: %v (%s)", err, setup.body)
|
||||
}
|
||||
if len(checklist.Steps) == 0 {
|
||||
t.Errorf("setup checklist is empty; the published projection carries what it reads (%s)", setup.body)
|
||||
}
|
||||
if checklist.Operator != "Sam" {
|
||||
t.Errorf("setup operator = %q, want the published name", checklist.Operator)
|
||||
}
|
||||
for _, step := range checklist.Steps {
|
||||
if step.Title == "Connect a repository" && !step.Done {
|
||||
t.Errorf("checklist says no repository is connected; the projection publishes one (%s)", setup.body)
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
// Last: taking the State Store away is not reversible for this process.
|
||||
t.Run("losing a dependency degrades readiness without failing liveness", func(t *testing.T) {
|
||||
healthy := d.get("/health/detailed")
|
||||
if healthy.status != http.StatusOK {
|
||||
t.Fatalf("GET /health/detailed = %d (%s), want 200", healthy.status, healthy.body)
|
||||
}
|
||||
var report health.Report
|
||||
if err := json.Unmarshal(healthy.body, &report); err != nil {
|
||||
t.Fatalf("decode readiness: %v (%s)", err, healthy.body)
|
||||
}
|
||||
if report.Status != health.StatusOK {
|
||||
t.Fatalf("readiness = %s with both dependencies up, want ok (%s)", report.Status, healthy.body)
|
||||
}
|
||||
|
||||
stopState()
|
||||
degraded := d.get("/health/detailed")
|
||||
if err := json.Unmarshal(degraded.body, &report); err != nil {
|
||||
t.Fatalf("decode readiness after outage: %v (%s)", err, degraded.body)
|
||||
}
|
||||
if report.Status == health.StatusOK {
|
||||
t.Errorf("readiness stayed ok with the State Store stopped (%s)", degraded.body)
|
||||
}
|
||||
if live := d.do(d.request(http.MethodGet, "/healthz", "", false)); live.status != http.StatusOK {
|
||||
t.Errorf("GET /healthz = %d during a dependency outage, want 200: liveness must not imply dependency readiness", live.status)
|
||||
}
|
||||
})
|
||||
}
|
||||
@@ -1,10 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"os"
|
||||
"testing"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest"
|
||||
)
|
||||
|
||||
func TestMain(m *testing.M) { os.Exit(pgtest.Main(m)) }
|
||||
@@ -0,0 +1,53 @@
|
||||
// Command archie is the single Archie binary. It parses flags and hands over to
|
||||
// the composition root.
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"flag"
|
||||
"fmt"
|
||||
"os"
|
||||
"os/signal"
|
||||
"syscall"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/app/archie"
|
||||
"github.com/samcharles93/archie-core/internal/buildinfo"
|
||||
)
|
||||
|
||||
func main() {
|
||||
if err := run(); err != nil {
|
||||
fmt.Fprintln(os.Stderr, "archie:", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
}
|
||||
|
||||
func run() error {
|
||||
configPath := flag.String("config", archie.DefaultConfigPath(), "path to the bootstrap config file")
|
||||
newIdentity := flag.Bool("new-age-identity", false, "print a new age identity for age_identity and exit")
|
||||
showVersion := buildinfo.RegisterVersionFlag("archie")
|
||||
flag.Usage = func() {
|
||||
_, _ = fmt.Fprintln(flag.CommandLine.Output(), "usage: archie [flags]\n archie openapi print the API's OpenAPI document")
|
||||
flag.PrintDefaults()
|
||||
}
|
||||
flag.Parse()
|
||||
showVersion()
|
||||
if *newIdentity {
|
||||
return archie.NewAgeIdentity(os.Stdout)
|
||||
}
|
||||
switch flag.Arg(0) {
|
||||
case "":
|
||||
case "openapi":
|
||||
doc, err := archie.Document()
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
_, err = os.Stdout.Write(doc)
|
||||
return err
|
||||
default:
|
||||
return fmt.Errorf("unknown command %q", flag.Arg(0))
|
||||
}
|
||||
|
||||
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
|
||||
defer stop()
|
||||
return archie.Run(ctx, *configPath)
|
||||
}
|
||||
Loaded 100 of 3200 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user