@adamchanadam/agent-handoff-kit 0.2.3 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +303 -269
- package/bin/agent-handoff-kit.mjs +1434 -1285
- package/package.json +1 -1
- package/packs/integrations.md +179 -0
- package/packs/knowledge.md +35 -31
- package/packs/onboarding.md +389 -298
- package/packs/safety.md +37 -29
- package/runtime-core/AGENTS.core.md +153 -144
- package/runtime-core/PROJECT_INDEX.md +136 -93
- package/runtime-core/RULE_PACKS.md +20 -19
- package/runtime-core/SESSION_HANDOFF.md +151 -150
|
@@ -1,1285 +1,1434 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
|
|
3
|
-
import { createInterface } from "node:readline/promises";
|
|
4
|
-
import { stdin as input, stdout as output } from "node:process";
|
|
5
|
-
import { copyFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
|
|
6
|
-
import path from "node:path";
|
|
7
|
-
import { fileURLToPath } from "node:url";
|
|
8
|
-
|
|
9
|
-
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
10
|
-
const packageRoot = path.resolve(__dirname, "..");
|
|
11
|
-
|
|
12
|
-
const mappings = [
|
|
13
|
-
["runtime-core/AGENTS.core.md", "AGENTS.md"],
|
|
14
|
-
["runtime-core/CLAUDE.md", "CLAUDE.md"],
|
|
15
|
-
["runtime-core/GEMINI.md", "GEMINI.md"],
|
|
16
|
-
["runtime-core/START_NEXT_SESSION_PROMPT.txt", "START_NEXT_SESSION_PROMPT.txt"],
|
|
17
|
-
["runtime-core/SESSION_HANDOFF.md", "dev/SESSION_HANDOFF.md"],
|
|
18
|
-
["runtime-core/SESSION_LOG.md", "dev/SESSION_LOG.md"],
|
|
19
|
-
["runtime-core/PROJECT_INDEX.md", "dev/PROJECT_INDEX.md"],
|
|
20
|
-
["runtime-core/DOC_SYNC_REGISTRY.md", "dev/DOC_SYNC_REGISTRY.md"],
|
|
21
|
-
["runtime-core/RULE_PACKS.md", "dev/RULE_PACKS.md"],
|
|
22
|
-
["runtime-core/PROJECT_DECISIONS.md", "dev/PROJECT_DECISIONS.md"],
|
|
23
|
-
["packs/safety.md", "dev/rules/safety.md"],
|
|
24
|
-
["packs/coding.md", "dev/rules/coding.md"],
|
|
25
|
-
["packs/writing.md", "dev/rules/writing.md"],
|
|
26
|
-
["packs/research.md", "dev/rules/research.md"],
|
|
27
|
-
["packs/agent-governance.md", "dev/rules/agent-governance.md"],
|
|
28
|
-
["packs/release.md", "dev/rules/release.md"],
|
|
29
|
-
["packs/knowledge.md", "dev/rules/knowledge.md"],
|
|
30
|
-
["packs/communication.md", "dev/rules/communication.md"],
|
|
31
|
-
["packs/onboarding.md", "dev/rules/onboarding.md"]
|
|
32
|
-
]
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
const
|
|
36
|
-
const
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
"
|
|
45
|
-
"dev/
|
|
46
|
-
"dev/
|
|
47
|
-
"dev/
|
|
48
|
-
"
|
|
49
|
-
"
|
|
50
|
-
"
|
|
51
|
-
"
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
"
|
|
65
|
-
"
|
|
66
|
-
"
|
|
67
|
-
"
|
|
68
|
-
"
|
|
69
|
-
"
|
|
70
|
-
"
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
"ack:section:
|
|
94
|
-
"ack:section:
|
|
95
|
-
"ack:section:
|
|
96
|
-
"ack:section:
|
|
97
|
-
"ack:section:
|
|
98
|
-
"ack:section:
|
|
99
|
-
"ack:section:
|
|
100
|
-
"
|
|
101
|
-
"
|
|
102
|
-
"
|
|
103
|
-
"
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
"
|
|
117
|
-
"
|
|
118
|
-
"
|
|
119
|
-
"
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
"
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
"Decisions
|
|
175
|
-
"
|
|
176
|
-
"
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
"
|
|
190
|
-
"
|
|
191
|
-
"
|
|
192
|
-
"
|
|
193
|
-
"
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
heading("
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
//
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
heading("
|
|
320
|
-
|
|
321
|
-
includes("
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
heading("
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
}
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
if (
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
const
|
|
451
|
-
if (
|
|
452
|
-
console.log("");
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
const
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
if (
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
});
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
}
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
: "
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
console.log(
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
}
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
}
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
const
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
}
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
})
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
}
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
const
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
}
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
}
|
|
678
|
-
}
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
};
|
|
686
|
-
}
|
|
687
|
-
|
|
688
|
-
function
|
|
689
|
-
const
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
}
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
}
|
|
788
|
-
return {
|
|
789
|
-
}
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
const
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
|
|
823
|
-
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
851
|
-
|
|
852
|
-
|
|
853
|
-
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
|
|
858
|
-
|
|
859
|
-
|
|
860
|
-
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
864
|
-
};
|
|
865
|
-
}
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
|
|
875
|
-
|
|
876
|
-
//
|
|
877
|
-
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
|
|
883
|
-
|
|
884
|
-
|
|
885
|
-
|
|
886
|
-
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
};
|
|
899
|
-
}
|
|
900
|
-
|
|
901
|
-
//
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
|
|
905
|
-
|
|
906
|
-
|
|
907
|
-
|
|
908
|
-
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
reason: "
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
920
|
-
|
|
921
|
-
|
|
922
|
-
|
|
923
|
-
|
|
924
|
-
|
|
925
|
-
|
|
926
|
-
|
|
927
|
-
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
|
|
933
|
-
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
}
|
|
937
|
-
|
|
938
|
-
|
|
939
|
-
|
|
940
|
-
//
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
|
|
944
|
-
|
|
945
|
-
|
|
946
|
-
|
|
947
|
-
|
|
948
|
-
|
|
949
|
-
|
|
950
|
-
|
|
951
|
-
|
|
952
|
-
|
|
953
|
-
|
|
954
|
-
|
|
955
|
-
|
|
956
|
-
|
|
957
|
-
|
|
958
|
-
}
|
|
959
|
-
const
|
|
960
|
-
const
|
|
961
|
-
|
|
962
|
-
|
|
963
|
-
|
|
964
|
-
|
|
965
|
-
}
|
|
966
|
-
|
|
967
|
-
|
|
968
|
-
|
|
969
|
-
|
|
970
|
-
|
|
971
|
-
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
978
|
-
|
|
979
|
-
|
|
980
|
-
|
|
981
|
-
|
|
982
|
-
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|
|
987
|
-
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
|
|
992
|
-
|
|
993
|
-
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
|
|
997
|
-
|
|
998
|
-
|
|
999
|
-
|
|
1000
|
-
|
|
1001
|
-
|
|
1002
|
-
|
|
1003
|
-
|
|
1004
|
-
|
|
1005
|
-
|
|
1006
|
-
|
|
1007
|
-
|
|
1008
|
-
|
|
1009
|
-
|
|
1010
|
-
|
|
1011
|
-
|
|
1012
|
-
|
|
1013
|
-
|
|
1014
|
-
}
|
|
1015
|
-
|
|
1016
|
-
|
|
1017
|
-
|
|
1018
|
-
|
|
1019
|
-
|
|
1020
|
-
|
|
1021
|
-
|
|
1022
|
-
|
|
1023
|
-
|
|
1024
|
-
|
|
1025
|
-
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
|
-
|
|
1029
|
-
|
|
1030
|
-
|
|
1031
|
-
|
|
1032
|
-
|
|
1033
|
-
|
|
1034
|
-
|
|
1035
|
-
|
|
1036
|
-
|
|
1037
|
-
|
|
1038
|
-
|
|
1039
|
-
|
|
1040
|
-
|
|
1041
|
-
|
|
1042
|
-
|
|
1043
|
-
|
|
1044
|
-
|
|
1045
|
-
|
|
1046
|
-
|
|
1047
|
-
|
|
1048
|
-
|
|
1049
|
-
|
|
1050
|
-
|
|
1051
|
-
|
|
1052
|
-
|
|
1053
|
-
|
|
1054
|
-
|
|
1055
|
-
|
|
1056
|
-
|
|
1057
|
-
|
|
1058
|
-
|
|
1059
|
-
|
|
1060
|
-
|
|
1061
|
-
|
|
1062
|
-
|
|
1063
|
-
|
|
1064
|
-
}
|
|
1065
|
-
|
|
1066
|
-
|
|
1067
|
-
|
|
1068
|
-
|
|
1069
|
-
|
|
1070
|
-
|
|
1071
|
-
|
|
1072
|
-
|
|
1073
|
-
|
|
1074
|
-
}
|
|
1075
|
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
|
|
1081
|
-
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
|
-
|
|
1085
|
-
|
|
1086
|
-
|
|
1087
|
-
|
|
1088
|
-
|
|
1089
|
-
|
|
1090
|
-
|
|
1091
|
-
|
|
1092
|
-
|
|
1093
|
-
|
|
1094
|
-
|
|
1095
|
-
|
|
1096
|
-
|
|
1097
|
-
|
|
1098
|
-
|
|
1099
|
-
|
|
1100
|
-
|
|
1101
|
-
|
|
1102
|
-
|
|
1103
|
-
|
|
1104
|
-
|
|
1105
|
-
|
|
1106
|
-
|
|
1107
|
-
|
|
1108
|
-
|
|
1109
|
-
|
|
1110
|
-
|
|
1111
|
-
|
|
1112
|
-
return
|
|
1113
|
-
}
|
|
1114
|
-
|
|
1115
|
-
|
|
1116
|
-
|
|
1117
|
-
|
|
1118
|
-
|
|
1119
|
-
|
|
1120
|
-
|
|
1121
|
-
|
|
1122
|
-
|
|
1123
|
-
|
|
1124
|
-
|
|
1125
|
-
|
|
1126
|
-
|
|
1127
|
-
|
|
1128
|
-
|
|
1129
|
-
|
|
1130
|
-
|
|
1131
|
-
|
|
1132
|
-
|
|
1133
|
-
}
|
|
1134
|
-
|
|
1135
|
-
|
|
1136
|
-
|
|
1137
|
-
|
|
1138
|
-
|
|
1139
|
-
|
|
1140
|
-
|
|
1141
|
-
|
|
1142
|
-
|
|
1143
|
-
|
|
1144
|
-
|
|
1145
|
-
|
|
1146
|
-
|
|
1147
|
-
|
|
1148
|
-
|
|
1149
|
-
|
|
1150
|
-
|
|
1151
|
-
|
|
1152
|
-
|
|
1153
|
-
|
|
1154
|
-
|
|
1155
|
-
|
|
1156
|
-
|
|
1157
|
-
|
|
1158
|
-
|
|
1159
|
-
|
|
1160
|
-
|
|
1161
|
-
|
|
1162
|
-
|
|
1163
|
-
|
|
1164
|
-
|
|
1165
|
-
|
|
1166
|
-
|
|
1167
|
-
|
|
1168
|
-
|
|
1169
|
-
}
|
|
1170
|
-
|
|
1171
|
-
|
|
1172
|
-
|
|
1173
|
-
|
|
1174
|
-
for (
|
|
1175
|
-
|
|
1176
|
-
|
|
1177
|
-
}
|
|
1178
|
-
|
|
1179
|
-
}
|
|
1180
|
-
|
|
1181
|
-
|
|
1182
|
-
|
|
1183
|
-
|
|
1184
|
-
|
|
1185
|
-
|
|
1186
|
-
|
|
1187
|
-
|
|
1188
|
-
|
|
1189
|
-
|
|
1190
|
-
|
|
1191
|
-
|
|
1192
|
-
|
|
1193
|
-
|
|
1194
|
-
|
|
1195
|
-
|
|
1196
|
-
|
|
1197
|
-
console.log(
|
|
1198
|
-
}
|
|
1199
|
-
|
|
1200
|
-
|
|
1201
|
-
}
|
|
1202
|
-
|
|
1203
|
-
function
|
|
1204
|
-
|
|
1205
|
-
|
|
1206
|
-
|
|
1207
|
-
|
|
1208
|
-
|
|
1209
|
-
|
|
1210
|
-
console.log(
|
|
1211
|
-
console.log("");
|
|
1212
|
-
|
|
1213
|
-
|
|
1214
|
-
|
|
1215
|
-
|
|
1216
|
-
|
|
1217
|
-
|
|
1218
|
-
|
|
1219
|
-
|
|
1220
|
-
|
|
1221
|
-
|
|
1222
|
-
|
|
1223
|
-
|
|
1224
|
-
|
|
1225
|
-
|
|
1226
|
-
|
|
1227
|
-
|
|
1228
|
-
|
|
1229
|
-
|
|
1230
|
-
|
|
1231
|
-
|
|
1232
|
-
|
|
1233
|
-
|
|
1234
|
-
|
|
1235
|
-
|
|
1236
|
-
|
|
1237
|
-
|
|
1238
|
-
|
|
1239
|
-
|
|
1240
|
-
|
|
1241
|
-
|
|
1242
|
-
|
|
1243
|
-
|
|
1244
|
-
|
|
1245
|
-
|
|
1246
|
-
|
|
1247
|
-
|
|
1248
|
-
|
|
1249
|
-
|
|
1250
|
-
|
|
1251
|
-
|
|
1252
|
-
|
|
1253
|
-
|
|
1254
|
-
|
|
1255
|
-
|
|
1256
|
-
|
|
1257
|
-
|
|
1258
|
-
|
|
1259
|
-
|
|
1260
|
-
|
|
1261
|
-
|
|
1262
|
-
|
|
1263
|
-
|
|
1264
|
-
|
|
1265
|
-
|
|
1266
|
-
|
|
1267
|
-
|
|
1268
|
-
|
|
1269
|
-
|
|
1270
|
-
|
|
1271
|
-
|
|
1272
|
-
|
|
1273
|
-
|
|
1274
|
-
|
|
1275
|
-
|
|
1276
|
-
|
|
1277
|
-
|
|
1278
|
-
|
|
1279
|
-
|
|
1280
|
-
|
|
1281
|
-
|
|
1282
|
-
|
|
1283
|
-
|
|
1284
|
-
|
|
1285
|
-
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
import { createInterface } from "node:readline/promises";
|
|
4
|
+
import { stdin as input, stdout as output } from "node:process";
|
|
5
|
+
import { copyFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
|
|
6
|
+
import path from "node:path";
|
|
7
|
+
import { fileURLToPath } from "node:url";
|
|
8
|
+
|
|
9
|
+
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
10
|
+
const packageRoot = path.resolve(__dirname, "..");
|
|
11
|
+
|
|
12
|
+
const mappings = [
|
|
13
|
+
["runtime-core/AGENTS.core.md", "AGENTS.md"],
|
|
14
|
+
["runtime-core/CLAUDE.md", "CLAUDE.md"],
|
|
15
|
+
["runtime-core/GEMINI.md", "GEMINI.md"],
|
|
16
|
+
["runtime-core/START_NEXT_SESSION_PROMPT.txt", "START_NEXT_SESSION_PROMPT.txt"],
|
|
17
|
+
["runtime-core/SESSION_HANDOFF.md", "dev/SESSION_HANDOFF.md"],
|
|
18
|
+
["runtime-core/SESSION_LOG.md", "dev/SESSION_LOG.md"],
|
|
19
|
+
["runtime-core/PROJECT_INDEX.md", "dev/PROJECT_INDEX.md"],
|
|
20
|
+
["runtime-core/DOC_SYNC_REGISTRY.md", "dev/DOC_SYNC_REGISTRY.md"],
|
|
21
|
+
["runtime-core/RULE_PACKS.md", "dev/RULE_PACKS.md"],
|
|
22
|
+
["runtime-core/PROJECT_DECISIONS.md", "dev/PROJECT_DECISIONS.md"],
|
|
23
|
+
["packs/safety.md", "dev/rules/safety.md"],
|
|
24
|
+
["packs/coding.md", "dev/rules/coding.md"],
|
|
25
|
+
["packs/writing.md", "dev/rules/writing.md"],
|
|
26
|
+
["packs/research.md", "dev/rules/research.md"],
|
|
27
|
+
["packs/agent-governance.md", "dev/rules/agent-governance.md"],
|
|
28
|
+
["packs/release.md", "dev/rules/release.md"],
|
|
29
|
+
["packs/knowledge.md", "dev/rules/knowledge.md"],
|
|
30
|
+
["packs/communication.md", "dev/rules/communication.md"],
|
|
31
|
+
["packs/onboarding.md", "dev/rules/onboarding.md"],
|
|
32
|
+
["packs/integrations.md", "dev/rules/integrations.md"]
|
|
33
|
+
];
|
|
34
|
+
|
|
35
|
+
const requiredTargets = mappings.map(([, target]) => target);
|
|
36
|
+
const managedCoreStart = "<!-- BEGIN Agent Handoff Kit managed core -->";
|
|
37
|
+
const managedCoreEnd = "<!-- END Agent Handoff Kit managed core -->";
|
|
38
|
+
|
|
39
|
+
const requiredAnchors = [
|
|
40
|
+
{
|
|
41
|
+
target: "AGENTS.md",
|
|
42
|
+
label: "startup read order",
|
|
43
|
+
snippets: [
|
|
44
|
+
"## 1. Startup Reads",
|
|
45
|
+
"dev/SESSION_HANDOFF.md",
|
|
46
|
+
"dev/SESSION_LOG.md",
|
|
47
|
+
"dev/PROJECT_INDEX.md",
|
|
48
|
+
"dev/RULE_PACKS.md",
|
|
49
|
+
"Agent Handoff Kit v<version>",
|
|
50
|
+
"continuity ready",
|
|
51
|
+
"Reachable is not the same as ingested",
|
|
52
|
+
"Do not treat unread sources as absent",
|
|
53
|
+
// R-030 v0.3.0+: forces managed-core merge on v0.2.x → v0.3.0 upgrade to propagate
|
|
54
|
+
// startup availability probe + integrations pack reference + credential separation discipline.
|
|
55
|
+
"startup availability probe",
|
|
56
|
+
"dev/rules/integrations.md",
|
|
57
|
+
"Credential separation"
|
|
58
|
+
]
|
|
59
|
+
},
|
|
60
|
+
{
|
|
61
|
+
target: "AGENTS.md",
|
|
62
|
+
label: "closeout intent and full handoff",
|
|
63
|
+
snippets: [
|
|
64
|
+
"Detect end-of-session or handoff intent",
|
|
65
|
+
"收工",
|
|
66
|
+
"wrap up",
|
|
67
|
+
"handoff",
|
|
68
|
+
"Reconcile `dev/SESSION_HANDOFF.md`",
|
|
69
|
+
"Add a concise entry to `dev/SESSION_LOG.md`",
|
|
70
|
+
"next-session opening message",
|
|
71
|
+
"fenced `text` code block",
|
|
72
|
+
"handoff saved",
|
|
73
|
+
"📋 Next session: copy and paste the whole block below",
|
|
74
|
+
"State Reconciliation Check",
|
|
75
|
+
"Do not append a new state snapshot",
|
|
76
|
+
"START_NEXT_SESSION_PROMPT.txt"
|
|
77
|
+
]
|
|
78
|
+
},
|
|
79
|
+
{
|
|
80
|
+
target: "START_NEXT_SESSION_PROMPT.txt",
|
|
81
|
+
label: "next-session prompt convenience copy",
|
|
82
|
+
snippets: [
|
|
83
|
+
"Work in ",
|
|
84
|
+
"Read in order:",
|
|
85
|
+
"dev/PROJECT_INDEX.md",
|
|
86
|
+
"If this root does not match the expected project root"
|
|
87
|
+
]
|
|
88
|
+
},
|
|
89
|
+
{
|
|
90
|
+
target: "dev/SESSION_HANDOFF.md",
|
|
91
|
+
label: "handoff workspace and opening message schema",
|
|
92
|
+
snippets: [
|
|
93
|
+
"ack:section:current-baseline",
|
|
94
|
+
"ack:section:durable-anchors",
|
|
95
|
+
"ack:section:closeout-reconciled-state",
|
|
96
|
+
"ack:section:task-understanding-summary",
|
|
97
|
+
"ack:section:active-objective",
|
|
98
|
+
"ack:section:next-priorities",
|
|
99
|
+
"ack:section:risks-blockers",
|
|
100
|
+
"ack:section:validation-qc",
|
|
101
|
+
"ack:section:workspace-identity",
|
|
102
|
+
"ack:section:sync-status",
|
|
103
|
+
"ack:section:next-task-required-reading",
|
|
104
|
+
"ack:section:state-reconciliation-check",
|
|
105
|
+
"ack:section:next-session-opening-message",
|
|
106
|
+
"📋 Next session: copy and paste the whole block below",
|
|
107
|
+
"```text",
|
|
108
|
+
"Read in order:",
|
|
109
|
+
"dev/DOC_SYNC_REGISTRY.md"
|
|
110
|
+
]
|
|
111
|
+
},
|
|
112
|
+
{
|
|
113
|
+
target: "dev/SESSION_LOG.md",
|
|
114
|
+
label: "session log event and opening message schema",
|
|
115
|
+
snippets: [
|
|
116
|
+
"Record what actually happened in the session",
|
|
117
|
+
"## Entry Template",
|
|
118
|
+
"- **QC:**",
|
|
119
|
+
"- **Sync:**",
|
|
120
|
+
"- **Log maintenance:**",
|
|
121
|
+
"### Next Session Opening Message",
|
|
122
|
+
"📋 Next session: copy and paste the whole block below",
|
|
123
|
+
"```text",
|
|
124
|
+
"Read in order:",
|
|
125
|
+
"dev/DOC_SYNC_REGISTRY.md"
|
|
126
|
+
]
|
|
127
|
+
},
|
|
128
|
+
{
|
|
129
|
+
target: "dev/SESSION_HANDOFF.md",
|
|
130
|
+
label: "handoff log archive continuity",
|
|
131
|
+
snippets: [
|
|
132
|
+
"ack:section:handoff-sufficiency-check",
|
|
133
|
+
"ack:section:state-reconciliation-check",
|
|
134
|
+
"ack:field:stale-snapshots-left",
|
|
135
|
+
"ack:field:opening-message-matches-current-state",
|
|
136
|
+
"without searching old log history",
|
|
137
|
+
"SESSION_LOG.md` carries recent evidence",
|
|
138
|
+
"do not create an archive directory by default"
|
|
139
|
+
]
|
|
140
|
+
},
|
|
141
|
+
{
|
|
142
|
+
target: "dev/SESSION_LOG.md",
|
|
143
|
+
label: "log retention and evidence schema",
|
|
144
|
+
snippets: [
|
|
145
|
+
"kept, summarized, or archived",
|
|
146
|
+
"Do not remove validation evidence",
|
|
147
|
+
"latest opening message",
|
|
148
|
+
"not current state"
|
|
149
|
+
]
|
|
150
|
+
},
|
|
151
|
+
{
|
|
152
|
+
target: "dev/PROJECT_INDEX.md",
|
|
153
|
+
label: "template version metadata",
|
|
154
|
+
snippets: [
|
|
155
|
+
"Agent Handoff Kit template version"
|
|
156
|
+
]
|
|
157
|
+
},
|
|
158
|
+
{
|
|
159
|
+
target: "dev/rules/safety.md",
|
|
160
|
+
label: "safety pack high-risk anchors",
|
|
161
|
+
snippets: [
|
|
162
|
+
"deleting, overwriting, moving, renaming",
|
|
163
|
+
"filesystem root, drive root",
|
|
164
|
+
"cmd /c rmdir",
|
|
165
|
+
"git reset --hard",
|
|
166
|
+
"external APIs, SDKs, CLIs",
|
|
167
|
+
"secret values"
|
|
168
|
+
]
|
|
169
|
+
},
|
|
170
|
+
{
|
|
171
|
+
target: "dev/PROJECT_DECISIONS.md",
|
|
172
|
+
label: "project decisions narrative anchors",
|
|
173
|
+
snippets: [
|
|
174
|
+
"Project Decisions Log",
|
|
175
|
+
"warm 資料層",
|
|
176
|
+
"AI 開工",
|
|
177
|
+
"不需要讀",
|
|
178
|
+
"AI 在收工時自動 update",
|
|
179
|
+
"Evolution Timeline",
|
|
180
|
+
"Decisions Archive",
|
|
181
|
+
"Architecture Choices",
|
|
182
|
+
"Insights & Learnings"
|
|
183
|
+
]
|
|
184
|
+
},
|
|
185
|
+
{
|
|
186
|
+
target: "dev/rules/onboarding.md",
|
|
187
|
+
label: "onboarding pack core anchors",
|
|
188
|
+
snippets: [
|
|
189
|
+
"Onboarding Pack",
|
|
190
|
+
"transient pack",
|
|
191
|
+
"明確 onboarding signal keywords",
|
|
192
|
+
"5-step walk-through pattern",
|
|
193
|
+
"Application Scenario Library",
|
|
194
|
+
"Scenario A. 寫 / 改代碼項目",
|
|
195
|
+
"Scenario B. 整理研究資料",
|
|
196
|
+
"Scenario C. 整理電腦檔案",
|
|
197
|
+
"Scenario D. 學寫代碼",
|
|
198
|
+
"Scenario E. 其他",
|
|
199
|
+
"Scenario F. 審視已裝外部工具",
|
|
200
|
+
"Tone Discipline"
|
|
201
|
+
]
|
|
202
|
+
},
|
|
203
|
+
{
|
|
204
|
+
target: "dev/rules/integrations.md",
|
|
205
|
+
label: "integrations pack core anchors",
|
|
206
|
+
snippets: [
|
|
207
|
+
"Integrations Pack",
|
|
208
|
+
"Connectors",
|
|
209
|
+
"MCPs",
|
|
210
|
+
"Plugins",
|
|
211
|
+
"Skills",
|
|
212
|
+
"機密分離原則",
|
|
213
|
+
"Source-of-truth Architecture",
|
|
214
|
+
"Cross-session Lifecycle",
|
|
215
|
+
"Connector-first default",
|
|
216
|
+
"Anti-pattern"
|
|
217
|
+
]
|
|
218
|
+
}
|
|
219
|
+
];
|
|
220
|
+
|
|
221
|
+
const schemaChecks = [
|
|
222
|
+
{
|
|
223
|
+
target: "AGENTS.md",
|
|
224
|
+
label: "core runtime uniqueness",
|
|
225
|
+
checks: [
|
|
226
|
+
{
|
|
227
|
+
label: "AGENTS.md health state is clean (single managed core, no unmarked dup, paired markers)",
|
|
228
|
+
test: (text) => assessAgentsMdHealth(text).state === "clean"
|
|
229
|
+
}
|
|
230
|
+
]
|
|
231
|
+
},
|
|
232
|
+
{
|
|
233
|
+
target: "dev/SESSION_HANDOFF.md",
|
|
234
|
+
label: "handoff required sections",
|
|
235
|
+
checks: [
|
|
236
|
+
section("current-baseline", "Current Baseline"),
|
|
237
|
+
section("durable-anchors", "Durable Anchors"),
|
|
238
|
+
section("closeout-reconciled-state", "Closeout-Reconciled State"),
|
|
239
|
+
section("task-understanding-summary", "Task Understanding Summary"),
|
|
240
|
+
section("active-objective", "Active Objective"),
|
|
241
|
+
section("next-priorities", "Next Priorities"),
|
|
242
|
+
section("next-task-required-reading", "Next Task Required Reading"),
|
|
243
|
+
section("risks-blockers", "Risks / Blockers"),
|
|
244
|
+
section("validation-qc", "Validation / QC"),
|
|
245
|
+
section("workspace-identity", "Workspace Identity"),
|
|
246
|
+
section("sync-status", "Sync Status"),
|
|
247
|
+
section("state-reconciliation-check", "State Reconciliation Check"),
|
|
248
|
+
section("handoff-sufficiency-check", "Handoff Sufficiency Check"),
|
|
249
|
+
section("next-session-opening-message", "Next Session Opening Message"),
|
|
250
|
+
marker("field", "stale-snapshots-left", "Stale snapshots left in this handoff"),
|
|
251
|
+
marker("field", "opening-message-matches-current-state", "Opening message matches current state"),
|
|
252
|
+
marker("field", "state-sections-rewritten-or-confirmed", "State sections rewritten or confirmed current"),
|
|
253
|
+
marker("field", "user-intent", "User intent:"),
|
|
254
|
+
marker("field", "task-essence", "Task essence:"),
|
|
255
|
+
marker("field", "success-criteria", "Success criteria:")
|
|
256
|
+
]
|
|
257
|
+
},
|
|
258
|
+
{
|
|
259
|
+
target: "dev/SESSION_HANDOFF.md",
|
|
260
|
+
label: "handoff opening message structure",
|
|
261
|
+
checks: [
|
|
262
|
+
includes("📋 Next session: copy and paste the whole block below"),
|
|
263
|
+
includes("```text"),
|
|
264
|
+
includes("Work in "),
|
|
265
|
+
includes("Read in order:"),
|
|
266
|
+
includes("If this root does not match the expected project root")
|
|
267
|
+
]
|
|
268
|
+
},
|
|
269
|
+
{
|
|
270
|
+
target: "dev/SESSION_LOG.md",
|
|
271
|
+
label: "session log entry fields",
|
|
272
|
+
checks: [
|
|
273
|
+
heading("Entry Template"),
|
|
274
|
+
includes("- **ID:**"),
|
|
275
|
+
includes("- **Summary:**"),
|
|
276
|
+
includes("- **Changed:**"),
|
|
277
|
+
includes("- **Done:**"),
|
|
278
|
+
includes("- **QC:**"),
|
|
279
|
+
includes("- **Sync:**"),
|
|
280
|
+
includes("- **Pending:**"),
|
|
281
|
+
includes("- **Risks:**"),
|
|
282
|
+
includes("- **Log maintenance:**")
|
|
283
|
+
]
|
|
284
|
+
},
|
|
285
|
+
{
|
|
286
|
+
target: "dev/PROJECT_INDEX.md",
|
|
287
|
+
label: "project index tables",
|
|
288
|
+
checks: [
|
|
289
|
+
heading("Stack"),
|
|
290
|
+
heading("Directory Map"),
|
|
291
|
+
heading("Entry Points"),
|
|
292
|
+
heading("Fact Base"),
|
|
293
|
+
heading("External Sources"),
|
|
294
|
+
heading("Installed Integrations"),
|
|
295
|
+
heading("Local QC Commands"),
|
|
296
|
+
heading("Workspace Identity"),
|
|
297
|
+
heading("Change Hotspots"),
|
|
298
|
+
heading("Maintenance Rule"),
|
|
299
|
+
tableHeader("Path", "Role", "Read when"),
|
|
300
|
+
tableHeader("Source", "Role", "Required before", "Access method", "Last verified"),
|
|
301
|
+
// External Sources tableHeader removed in v0.3.0 — schema accepts either 6-col legacy or 7-col v0.3.0+
|
|
302
|
+
// to support non-destructive migration (existing v0.2.x users keep their 6-col table; new installs
|
|
303
|
+
// get 7-col template with `via` column). The heading("External Sources") check above is sufficient
|
|
304
|
+
// to verify the section is structurally present.
|
|
305
|
+
tableHeader("Check", "Command", "Run before", "Last verified"),
|
|
306
|
+
tableHeader("Change type", "Likely files", "Required checks"),
|
|
307
|
+
// R-030 v0.3.0+: Installed Integrations subsection table headers
|
|
308
|
+
tableHeader("Tool", "Project Usage", "Access Scope", "Specific Instance", "Credential Location", "Declared", "Last Verified"),
|
|
309
|
+
tableHeader("Server", "Source", "Project Usage", "Credential Location", "Declared", "Last Verified"),
|
|
310
|
+
tableHeader("Name", "Bundle Content(Skills + MCP + hooks)", "When Triggered", "Last Verified"),
|
|
311
|
+
tableHeader("Name", "Source", "When Triggered", "Last Verified"),
|
|
312
|
+
tableHeader("Layer", "Surface(具體 instance)", "Role", "Write Direction")
|
|
313
|
+
]
|
|
314
|
+
},
|
|
315
|
+
{
|
|
316
|
+
target: "dev/DOC_SYNC_REGISTRY.md",
|
|
317
|
+
label: "doc sync registry status vocabulary",
|
|
318
|
+
checks: [
|
|
319
|
+
heading("Status Vocabulary"),
|
|
320
|
+
includes("confirmed"),
|
|
321
|
+
includes("unverified"),
|
|
322
|
+
includes("pending"),
|
|
323
|
+
includes("blocked"),
|
|
324
|
+
includes("not_applicable"),
|
|
325
|
+
tableHeader("Change type", "Also check/update", "Verification")
|
|
326
|
+
]
|
|
327
|
+
},
|
|
328
|
+
{
|
|
329
|
+
target: "dev/RULE_PACKS.md",
|
|
330
|
+
label: "rule pack router coverage",
|
|
331
|
+
checks: [
|
|
332
|
+
heading("Routing Rule"),
|
|
333
|
+
includes("Load the minimum set"),
|
|
334
|
+
includes("cannot weaken core safety"),
|
|
335
|
+
includes("dev/rules/safety.md"),
|
|
336
|
+
includes("dev/rules/coding.md"),
|
|
337
|
+
includes("dev/rules/research.md"),
|
|
338
|
+
includes("dev/rules/release.md"),
|
|
339
|
+
// R-029 v0.2.1+: routing table must include onboarding pack first-time signal row.
|
|
340
|
+
// Without this anchor, the upgrade flow may silently leave v0.1.X users with a
|
|
341
|
+
// stale routing table that does not route onboarding signals.
|
|
342
|
+
includes("First-time user signals"),
|
|
343
|
+
includes("dev/rules/onboarding.md"),
|
|
344
|
+
// R-030 v0.3.0+: routing table must include integrations pack row.
|
|
345
|
+
includes("dev/rules/integrations.md")
|
|
346
|
+
]
|
|
347
|
+
},
|
|
348
|
+
{
|
|
349
|
+
target: "dev/PROJECT_DECISIONS.md",
|
|
350
|
+
label: "project decisions log structure",
|
|
351
|
+
checks: [
|
|
352
|
+
heading("Evolution Timeline"),
|
|
353
|
+
heading("Decisions Archive"),
|
|
354
|
+
heading("Architecture Choices"),
|
|
355
|
+
heading("Insights & Learnings"),
|
|
356
|
+
includes("(empty)")
|
|
357
|
+
]
|
|
358
|
+
},
|
|
359
|
+
{
|
|
360
|
+
target: "dev/rules/onboarding.md",
|
|
361
|
+
label: "onboarding pack structure (新手引導包)",
|
|
362
|
+
checks: [
|
|
363
|
+
heading("Scope"),
|
|
364
|
+
heading("Load When"),
|
|
365
|
+
heading("Discipline"),
|
|
366
|
+
heading("Application Scenario Library"),
|
|
367
|
+
heading("Cross-reference to guide.html"),
|
|
368
|
+
heading("Tone Discipline"),
|
|
369
|
+
heading("Closeout")
|
|
370
|
+
]
|
|
371
|
+
},
|
|
372
|
+
{
|
|
373
|
+
target: "dev/rules/integrations.md",
|
|
374
|
+
label: "integrations pack structure (外部工具治理)",
|
|
375
|
+
checks: [
|
|
376
|
+
heading("Scope"),
|
|
377
|
+
heading("Load When"),
|
|
378
|
+
heading("Discipline"),
|
|
379
|
+
heading("Rules"),
|
|
380
|
+
heading("Checks"),
|
|
381
|
+
heading("Closeout"),
|
|
382
|
+
heading("Anti-pattern(不要做的事)"),
|
|
383
|
+
heading("Cross-reference")
|
|
384
|
+
]
|
|
385
|
+
}
|
|
386
|
+
];
|
|
387
|
+
|
|
388
|
+
main().catch((error) => {
|
|
389
|
+
console.error(`agent-handoff-kit: ${error.message}`);
|
|
390
|
+
process.exitCode = 1;
|
|
391
|
+
});
|
|
392
|
+
|
|
393
|
+
async function main() {
|
|
394
|
+
const version = await readPackageVersion();
|
|
395
|
+
await maybePrintUpdateNotice(version);
|
|
396
|
+
const { command, options } = parseArgs(process.argv.slice(2));
|
|
397
|
+
if (!command || options.help) {
|
|
398
|
+
printHelp(version);
|
|
399
|
+
return;
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
const root = path.resolve(options.root ?? process.cwd());
|
|
403
|
+
|
|
404
|
+
if (command === "init" || command === "upgrade") {
|
|
405
|
+
await runInstall(command, root, options, version);
|
|
406
|
+
return;
|
|
407
|
+
}
|
|
408
|
+
|
|
409
|
+
if (command === "doctor") {
|
|
410
|
+
await runDoctor(root, version);
|
|
411
|
+
return;
|
|
412
|
+
}
|
|
413
|
+
|
|
414
|
+
throw new Error(`unknown command "${command}"`);
|
|
415
|
+
}
|
|
416
|
+
|
|
417
|
+
function parseArgs(args) {
|
|
418
|
+
const options = {};
|
|
419
|
+
let command;
|
|
420
|
+
|
|
421
|
+
for (let i = 0; i < args.length; i += 1) {
|
|
422
|
+
const arg = args[i];
|
|
423
|
+
if (!command && !arg.startsWith("-")) {
|
|
424
|
+
command = arg;
|
|
425
|
+
continue;
|
|
426
|
+
}
|
|
427
|
+
if (arg === "--dry-run") options.dryRun = true;
|
|
428
|
+
else if (arg === "--yes" || arg === "-y") options.yes = true;
|
|
429
|
+
else if (arg === "--help" || arg === "-h") options.help = true;
|
|
430
|
+
else if (arg === "--root") options.root = args[++i];
|
|
431
|
+
else throw new Error(`unknown option "${arg}"`);
|
|
432
|
+
}
|
|
433
|
+
|
|
434
|
+
return { command, options };
|
|
435
|
+
}
|
|
436
|
+
|
|
437
|
+
async function runInstall(command, root, options, version) {
|
|
438
|
+
const mode = await detectMode(root);
|
|
439
|
+
const plan = await buildPlan(root, command);
|
|
440
|
+
printPlan(command, root, mode, plan, version);
|
|
441
|
+
|
|
442
|
+
if (options.dryRun) {
|
|
443
|
+
console.log("\ndry-run: no files written");
|
|
444
|
+
printDryRunExplanation(plan);
|
|
445
|
+
if (plan.some((item) => item.action === "conflict")) process.exitCode = 1;
|
|
446
|
+
return;
|
|
447
|
+
}
|
|
448
|
+
|
|
449
|
+
if (!options.yes) {
|
|
450
|
+
const ok = await confirmWrite();
|
|
451
|
+
if (!ok) {
|
|
452
|
+
console.log("cancelled: no files written");
|
|
453
|
+
return;
|
|
454
|
+
}
|
|
455
|
+
}
|
|
456
|
+
|
|
457
|
+
const created = [];
|
|
458
|
+
const merged = [];
|
|
459
|
+
const conflicts = plan.filter((item) => item.action === "conflict");
|
|
460
|
+
const stamp = migrationStamp();
|
|
461
|
+
const migrationDir = path.join(root, "dev/governance_migrations", stamp);
|
|
462
|
+
const backupDir = path.join(migrationDir, "backup");
|
|
463
|
+
|
|
464
|
+
for (const item of plan) {
|
|
465
|
+
if (item.action !== "create") continue;
|
|
466
|
+
await mkdir(path.dirname(item.targetAbs), { recursive: true });
|
|
467
|
+
await copyFile(item.sourceAbs, item.targetAbs);
|
|
468
|
+
created.push(item.targetRel);
|
|
469
|
+
}
|
|
470
|
+
|
|
471
|
+
for (const item of plan) {
|
|
472
|
+
if (item.action !== "merge") continue;
|
|
473
|
+
const backupPath = path.join(backupDir, item.targetRel);
|
|
474
|
+
await mkdir(path.dirname(backupPath), { recursive: true });
|
|
475
|
+
await copyFile(item.targetAbs, backupPath);
|
|
476
|
+
await writeFile(item.targetAbs, item.mergedText, "utf8");
|
|
477
|
+
merged.push(item.targetRel);
|
|
478
|
+
}
|
|
479
|
+
|
|
480
|
+
const report = await writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir);
|
|
481
|
+
const skippedCount = plan.filter((item) => item.action === "skip").length;
|
|
482
|
+
printInstallSummary(version, command, mode, root, {
|
|
483
|
+
created: created.length,
|
|
484
|
+
merged: merged.length,
|
|
485
|
+
skipped: skippedCount,
|
|
486
|
+
conflicts: conflicts.length,
|
|
487
|
+
backupRel: merged.length > 0 ? path.relative(root, backupDir) : null,
|
|
488
|
+
reportRel: path.relative(root, report)
|
|
489
|
+
});
|
|
490
|
+
printInstallNextSteps(root, conflicts.length);
|
|
491
|
+
|
|
492
|
+
// R-024 upgrade.done self-check: after upgrade writes, run doctor automatically.
|
|
493
|
+
// The user must see whether the merged state actually reaches a clean health state.
|
|
494
|
+
if (command === "upgrade" && conflicts.length === 0) {
|
|
495
|
+
console.log("");
|
|
496
|
+
console.log("------------------------------------------------------------");
|
|
497
|
+
console.log("🩺 upgrade self-check: running doctor against the upgraded root");
|
|
498
|
+
console.log("------------------------------------------------------------");
|
|
499
|
+
const doctorStatus = await runDoctor(root, version, { silentCard: true });
|
|
500
|
+
if (doctorStatus !== "passed") {
|
|
501
|
+
console.log("");
|
|
502
|
+
console.log("⚠️ upgrade self-check did not pass; see doctor output above.");
|
|
503
|
+
console.log("📋 下一步:把上面 doctor 輸出貼給 AI,請它先按提示修補後再宣稱 upgrade 完成。");
|
|
504
|
+
process.exitCode = 1;
|
|
505
|
+
}
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
if (conflicts.length > 0) process.exitCode = 1;
|
|
509
|
+
}
|
|
510
|
+
|
|
511
|
+
async function runDoctor(root, version, options = {}) {
|
|
512
|
+
if (!options.silentCard) printCard(version, "doctor ready", "o.o");
|
|
513
|
+
const rows = [];
|
|
514
|
+
for (const target of requiredTargets) {
|
|
515
|
+
rows.push({ target, ok: await exists(path.join(root, target)) });
|
|
516
|
+
}
|
|
517
|
+
|
|
518
|
+
const missing = rows.filter((row) => !row.ok);
|
|
519
|
+
console.log(`root: ${root}`);
|
|
520
|
+
console.log(`required files: ${rows.length}`);
|
|
521
|
+
for (const row of rows) {
|
|
522
|
+
console.log(`${row.ok ? "ok" : "missing"} ${row.target}`);
|
|
523
|
+
}
|
|
524
|
+
|
|
525
|
+
if (missing.length > 0) {
|
|
526
|
+
printDoctorSummary(version, root, "needs-fix", {
|
|
527
|
+
checked: rows.length,
|
|
528
|
+
failedKind: "missing files",
|
|
529
|
+
failedCount: missing.length,
|
|
530
|
+
nextStep: "先確認你是否在正確專案資料夾;如是,執行 init 或 upgrade 補回缺少檔案。"
|
|
531
|
+
});
|
|
532
|
+
process.exitCode = 1;
|
|
533
|
+
return "failed";
|
|
534
|
+
}
|
|
535
|
+
|
|
536
|
+
const anchorRows = await checkRequiredAnchors(root);
|
|
537
|
+
const anchorFailures = anchorRows.filter((row) => !row.ok);
|
|
538
|
+
console.log(`\nrequired anchors: ${anchorRows.length}`);
|
|
539
|
+
for (const row of anchorRows) {
|
|
540
|
+
console.log(`${row.ok ? "ok" : "missing"} ${row.target} (${row.label})`);
|
|
541
|
+
}
|
|
542
|
+
|
|
543
|
+
if (anchorFailures.length > 0) {
|
|
544
|
+
printDoctorSummary(version, root, "needs-fix", {
|
|
545
|
+
checked: rows.length + anchorRows.length,
|
|
546
|
+
failedKind: "anchor checks",
|
|
547
|
+
failedCount: anchorFailures.length,
|
|
548
|
+
nextStep: "執行 upgrade --dry-run 查看可否安全補齊;不要手動覆寫既有檔案。"
|
|
549
|
+
});
|
|
550
|
+
process.exitCode = 1;
|
|
551
|
+
return "failed";
|
|
552
|
+
}
|
|
553
|
+
|
|
554
|
+
const schemaRows = await checkSchema(root);
|
|
555
|
+
const schemaFailures = schemaRows.filter((row) => !row.ok);
|
|
556
|
+
console.log(`\nschema checks: ${schemaRows.length}`);
|
|
557
|
+
for (const row of schemaRows) {
|
|
558
|
+
console.log(`${row.ok ? "ok" : "missing"} ${row.target} (${row.label})`);
|
|
559
|
+
if (!row.ok && row.missing.length > 0) {
|
|
560
|
+
console.log(` missing: ${row.missing.join("; ")}`);
|
|
561
|
+
}
|
|
562
|
+
}
|
|
563
|
+
|
|
564
|
+
if (schemaFailures.length > 0) {
|
|
565
|
+
printDoctorSummary(version, root, "needs-fix", {
|
|
566
|
+
checked: rows.length + anchorRows.length + schemaRows.length,
|
|
567
|
+
failedKind: "schema checks",
|
|
568
|
+
failedCount: schemaFailures.length,
|
|
569
|
+
nextStep: "把這段 doctor 輸出貼給 AI,請它先修交接結構,不要直接重裝覆蓋。"
|
|
570
|
+
});
|
|
571
|
+
process.exitCode = 1;
|
|
572
|
+
return "failed";
|
|
573
|
+
}
|
|
574
|
+
|
|
575
|
+
const mirrorRows = await checkPromptMirror(root);
|
|
576
|
+
const mirrorFailures = mirrorRows.filter((row) => !row.ok);
|
|
577
|
+
console.log(`\nprompt mirror checks: ${mirrorRows.length}`);
|
|
578
|
+
for (const row of mirrorRows) {
|
|
579
|
+
console.log(`${row.ok ? "ok" : "missing"} ${row.target} (${row.label})`);
|
|
580
|
+
if (!row.ok && row.reason) console.log(` reason: ${row.reason}`);
|
|
581
|
+
}
|
|
582
|
+
|
|
583
|
+
if (mirrorFailures.length > 0) {
|
|
584
|
+
printDoctorSummary(version, root, "needs-fix", {
|
|
585
|
+
checked: rows.length + anchorRows.length + schemaRows.length + mirrorRows.length,
|
|
586
|
+
failedKind: "prompt mirror checks",
|
|
587
|
+
failedCount: mirrorFailures.length,
|
|
588
|
+
nextStep: "以 dev/SESSION_HANDOFF.md 的 Next Session Opening Message 為準,重生 START_NEXT_SESSION_PROMPT.txt。"
|
|
589
|
+
});
|
|
590
|
+
process.exitCode = 1;
|
|
591
|
+
return "failed";
|
|
592
|
+
}
|
|
593
|
+
|
|
594
|
+
// R-010 SESSION_LOG handoff-role discipline check (warn-only; does not change mode or exit).
|
|
595
|
+
const disciplineResult = await assessSessionLogDiscipline(root);
|
|
596
|
+
console.log(`\nSESSION_LOG 接力角色紀律: ${disciplineResult.ok ? "ok" : "warn"}`);
|
|
597
|
+
if (!disciplineResult.ok) {
|
|
598
|
+
for (const warning of disciplineResult.warnings) {
|
|
599
|
+
console.log(` warn: ${warning}`);
|
|
600
|
+
}
|
|
601
|
+
}
|
|
602
|
+
|
|
603
|
+
// R-030 v0.3.0+: credential leak prevention sweep over governance files.
|
|
604
|
+
const credentialResult = await checkInstalledIntegrationsCredentialLeak(root);
|
|
605
|
+
console.log(`Credential 機密分離 sweep: ${credentialResult.ok ? "ok" : "FAILED"}`);
|
|
606
|
+
if (!credentialResult.ok) {
|
|
607
|
+
for (const finding of credentialResult.findings) {
|
|
608
|
+
console.log(` CRITICAL: ${finding}`);
|
|
609
|
+
}
|
|
610
|
+
}
|
|
611
|
+
|
|
612
|
+
const overallHealthy = credentialResult.ok;
|
|
613
|
+
printDoctorSummary(version, root, overallHealthy ? "healthy" : "needs-attention", {
|
|
614
|
+
checked: rows.length + anchorRows.length + schemaRows.length + mirrorRows.length + 2,
|
|
615
|
+
failedKind: !credentialResult.ok ? "credential leak" : null,
|
|
616
|
+
failedCount: !credentialResult.ok ? credentialResult.findings.length : 0,
|
|
617
|
+
nextStep: !credentialResult.ok
|
|
618
|
+
? "立即從相關檔案 redact credential value + rotate 已泄露 token;credential 應該由 AI 工具自身 secure storage 管理,永不寫入 dev/* 任何檔。"
|
|
619
|
+
: disciplineResult.ok
|
|
620
|
+
? "繼續日常使用;如要升級到較新版,執行 npx @adamchanadam/agent-handoff-kit@latest upgrade。"
|
|
621
|
+
: "繼續使用;下次 closeout 時 AI 應自動執行 SESSION_LOG N 規則推進(見上面 warn 行)。如未動請要求 AI 重做 closeout。"
|
|
622
|
+
});
|
|
623
|
+
return overallHealthy ? "passed" : "failed";
|
|
624
|
+
}
|
|
625
|
+
|
|
626
|
+
// R-030 v0.3.0+: Credential leak prevention sweep. Scans dev/PROJECT_INDEX.md,
|
|
627
|
+
// dev/SESSION_HANDOFF.md, dev/SESSION_LOG.md for common credential prefix patterns.
|
|
628
|
+
// Credentials must live in OS-level secure storage or AI-tool config, never in dev/*.
|
|
629
|
+
async function checkInstalledIntegrationsCredentialLeak(root) {
|
|
630
|
+
const credentialPatterns = [
|
|
631
|
+
{ pattern: /sk-ant-[A-Za-z0-9_-]{20,}/, label: "Anthropic API key (sk-ant-)" },
|
|
632
|
+
{ pattern: /\bsk-[A-Za-z0-9_-]{20,}/, label: "OpenAI / generic sk- prefix" },
|
|
633
|
+
{ pattern: /\bntn_[A-Za-z0-9_-]{40,}/, label: "Notion Integration Token (ntn_)" },
|
|
634
|
+
{ pattern: /\bsecret_[A-Za-z0-9_-]{40,}/, label: "Notion legacy secret_ token" },
|
|
635
|
+
{ pattern: /\bya29\.[A-Za-z0-9_-]{20,}/, label: "Google OAuth access token (ya29.)" },
|
|
636
|
+
{ pattern: /\b1\/\/[A-Za-z0-9_-]{30,}/, label: "Google refresh token (1//)" },
|
|
637
|
+
{ pattern: /\bxox[abprs]-[A-Za-z0-9-]{10,}/, label: "Slack token (xoxp-/xoxb-/etc)" },
|
|
638
|
+
{ pattern: /\bghp_[A-Za-z0-9]{36}/, label: "GitHub Personal Access Token (ghp_)" },
|
|
639
|
+
{ pattern: /\bgho_[A-Za-z0-9]{36}/, label: "GitHub OAuth token (gho_)" },
|
|
640
|
+
{ pattern: /\bghs_[A-Za-z0-9]{36}/, label: "GitHub server token (ghs_)" },
|
|
641
|
+
{ pattern: /\bgithub_pat_[A-Za-z0-9_]{20,}/, label: "GitHub fine-grained PAT (github_pat_)" },
|
|
642
|
+
{ pattern: /\bsl\.[A-Za-z0-9_-]{50,}/, label: "Dropbox token (sl.)" },
|
|
643
|
+
{ pattern: /\bAKIA[A-Z0-9]{16}/, label: "AWS access key (AKIA)" },
|
|
644
|
+
{ pattern: /\bAIza[A-Za-z0-9_-]{35}/, label: "Google API key (AIza)" }
|
|
645
|
+
];
|
|
646
|
+
const targetFiles = [
|
|
647
|
+
"dev/PROJECT_INDEX.md",
|
|
648
|
+
"dev/SESSION_HANDOFF.md",
|
|
649
|
+
"dev/SESSION_LOG.md"
|
|
650
|
+
];
|
|
651
|
+
const findings = [];
|
|
652
|
+
for (const relPath of targetFiles) {
|
|
653
|
+
const absPath = path.join(root, relPath);
|
|
654
|
+
let text;
|
|
655
|
+
try {
|
|
656
|
+
text = await readFile(absPath, "utf8");
|
|
657
|
+
} catch {
|
|
658
|
+
continue;
|
|
659
|
+
}
|
|
660
|
+
for (const { pattern, label } of credentialPatterns) {
|
|
661
|
+
const match = text.match(pattern);
|
|
662
|
+
if (match) {
|
|
663
|
+
const line = text.slice(0, match.index).split("\n").length;
|
|
664
|
+
findings.push(`${relPath}:${line} — ${label} pattern matched. Remove value immediately, rotate token, and re-store credential only in AI tool secure storage.`);
|
|
665
|
+
}
|
|
666
|
+
}
|
|
667
|
+
}
|
|
668
|
+
return { ok: findings.length === 0, findings };
|
|
669
|
+
}
|
|
670
|
+
|
|
671
|
+
// R-026 CLI Output Contract: doctor 完成必含四項(版本/模式/剛做咗乜/下一步)。
|
|
672
|
+
function printDoctorSummary(version, root, mode, details) {
|
|
673
|
+
console.log("");
|
|
674
|
+
if (mode === "healthy") {
|
|
675
|
+
console.log("status: passed");
|
|
676
|
+
console.log("✅ 檢查通過:必要文件存在,基本結構完整,下次開工提示副本也與 handoff 一致。");
|
|
677
|
+
} else {
|
|
678
|
+
console.log(`status: failed (${details.failedCount} ${details.failedKind} failed)`);
|
|
679
|
+
console.log(`⚠️ 檢查未通過:${details.failedKind === "missing files" ? "有必要檔案不存在。" : details.failedKind === "anchor checks" ? "有檔案存在,但內容缺少必要段落。" : details.failedKind === "schema checks" ? "交接或索引文件結構不完整。" : "下次開工提示副本與 handoff 真源不同。"}`);
|
|
680
|
+
}
|
|
681
|
+
console.log("");
|
|
682
|
+
console.log(`📦 版本:v${version}`);
|
|
683
|
+
console.log(`🩺 模式:${mode}`);
|
|
684
|
+
console.log(`🔎 剛做咗:檢查 ${details.checked} 項;${mode === "healthy" ? "全部通過" : `${details.failedCount} 項未通過(${details.failedKind})`}。`);
|
|
685
|
+
console.log(`🚀 下一步:${details.nextStep}`);
|
|
686
|
+
}
|
|
687
|
+
|
|
688
|
+
async function checkPromptMirror(root) {
|
|
689
|
+
const handoffPath = path.join(root, "dev/SESSION_HANDOFF.md");
|
|
690
|
+
const promptPath = path.join(root, "START_NEXT_SESSION_PROMPT.txt");
|
|
691
|
+
let handoffText = "";
|
|
692
|
+
let promptText = "";
|
|
693
|
+
try {
|
|
694
|
+
handoffText = await readFile(handoffPath, "utf8");
|
|
695
|
+
} catch {
|
|
696
|
+
return [{ target: "START_NEXT_SESSION_PROMPT.txt", label: "matches handoff opening message", ok: false, reason: "handoff unreadable" }];
|
|
697
|
+
}
|
|
698
|
+
try {
|
|
699
|
+
promptText = await readFile(promptPath, "utf8");
|
|
700
|
+
} catch {
|
|
701
|
+
return [{ target: "START_NEXT_SESSION_PROMPT.txt", label: "matches handoff opening message", ok: false, reason: "prompt copy unreadable" }];
|
|
702
|
+
}
|
|
703
|
+
const openingMessage = extractOpeningMessage(handoffText);
|
|
704
|
+
if (!openingMessage) {
|
|
705
|
+
return [{ target: "START_NEXT_SESSION_PROMPT.txt", label: "matches handoff opening message", ok: false, reason: "handoff opening message missing" }];
|
|
706
|
+
}
|
|
707
|
+
const ok = normalizePrompt(promptText) === normalizePrompt(openingMessage);
|
|
708
|
+
return [{ target: "START_NEXT_SESSION_PROMPT.txt", label: "matches handoff opening message", ok, reason: ok ? "" : "convenience copy differs from dev/SESSION_HANDOFF.md" }];
|
|
709
|
+
}
|
|
710
|
+
|
|
711
|
+
function extractOpeningMessage(text) {
|
|
712
|
+
const marker = "📋 Next session: copy and paste the whole block below";
|
|
713
|
+
const markerIndex = text.indexOf(marker);
|
|
714
|
+
if (markerIndex < 0) return null;
|
|
715
|
+
const fenceStart = text.indexOf("```text", markerIndex);
|
|
716
|
+
if (fenceStart < 0) return null;
|
|
717
|
+
const contentStart = text.indexOf("\n", fenceStart);
|
|
718
|
+
const fenceEnd = text.indexOf("```", contentStart + 1);
|
|
719
|
+
if (contentStart < 0 || fenceEnd < 0) return null;
|
|
720
|
+
return text.slice(contentStart + 1, fenceEnd).trim();
|
|
721
|
+
}
|
|
722
|
+
|
|
723
|
+
function normalizePrompt(text) {
|
|
724
|
+
return text.replace(/\r\n/g, "\n").trim();
|
|
725
|
+
}
|
|
726
|
+
|
|
727
|
+
async function checkRequiredAnchors(root) {
|
|
728
|
+
const rows = [];
|
|
729
|
+
for (const rule of requiredAnchors) {
|
|
730
|
+
const filePath = path.join(root, rule.target);
|
|
731
|
+
let text = "";
|
|
732
|
+
try {
|
|
733
|
+
text = await readFile(filePath, "utf8");
|
|
734
|
+
} catch {
|
|
735
|
+
rows.push({ target: rule.target, label: rule.label, ok: false });
|
|
736
|
+
continue;
|
|
737
|
+
}
|
|
738
|
+
|
|
739
|
+
rows.push({
|
|
740
|
+
target: rule.target,
|
|
741
|
+
label: rule.label,
|
|
742
|
+
ok: rule.snippets.every((snippet) => text.includes(snippet))
|
|
743
|
+
});
|
|
744
|
+
}
|
|
745
|
+
return rows;
|
|
746
|
+
}
|
|
747
|
+
|
|
748
|
+
async function checkSchema(root) {
|
|
749
|
+
const rows = [];
|
|
750
|
+
for (const rule of schemaChecks) {
|
|
751
|
+
const filePath = path.join(root, rule.target);
|
|
752
|
+
let text = "";
|
|
753
|
+
try {
|
|
754
|
+
text = await readFile(filePath, "utf8");
|
|
755
|
+
} catch {
|
|
756
|
+
rows.push({ target: rule.target, label: rule.label, ok: false, missing: ["file unreadable"] });
|
|
757
|
+
continue;
|
|
758
|
+
}
|
|
759
|
+
const missing = rule.checks
|
|
760
|
+
.filter((check) => !check.test(text))
|
|
761
|
+
.map((check) => check.label);
|
|
762
|
+
rows.push({
|
|
763
|
+
target: rule.target,
|
|
764
|
+
label: rule.label,
|
|
765
|
+
ok: missing.length === 0,
|
|
766
|
+
missing
|
|
767
|
+
});
|
|
768
|
+
}
|
|
769
|
+
return rows;
|
|
770
|
+
}
|
|
771
|
+
|
|
772
|
+
function includes(snippet) {
|
|
773
|
+
return {
|
|
774
|
+
label: snippet,
|
|
775
|
+
test: (text) => text.includes(snippet)
|
|
776
|
+
};
|
|
777
|
+
}
|
|
778
|
+
|
|
779
|
+
function heading(title) {
|
|
780
|
+
return {
|
|
781
|
+
label: `heading: ${title}`,
|
|
782
|
+
test: (text) => new RegExp(`^## ${escapeRegExp(title)}\\s*$`, "m").test(text)
|
|
783
|
+
};
|
|
784
|
+
}
|
|
785
|
+
|
|
786
|
+
function marker(type, id, legacyText) {
|
|
787
|
+
const semanticMarker = `ack:${type}:${id}`;
|
|
788
|
+
return {
|
|
789
|
+
label: `${type}: ${id}`,
|
|
790
|
+
test: (text) => text.includes(semanticMarker) || (legacyText ? text.includes(legacyText) : false)
|
|
791
|
+
};
|
|
792
|
+
}
|
|
793
|
+
|
|
794
|
+
function section(id, legacyHeading) {
|
|
795
|
+
const check = marker("section", id, null);
|
|
796
|
+
return {
|
|
797
|
+
label: `section: ${id}`,
|
|
798
|
+
test: (text) => check.test(text) || heading(legacyHeading).test(text)
|
|
799
|
+
};
|
|
800
|
+
}
|
|
801
|
+
|
|
802
|
+
function tableHeader(...cells) {
|
|
803
|
+
const line = `| ${cells.join(" | ")} |`;
|
|
804
|
+
return {
|
|
805
|
+
label: `table: ${cells.join(" / ")}`,
|
|
806
|
+
test: (text) => text.includes(line)
|
|
807
|
+
};
|
|
808
|
+
}
|
|
809
|
+
|
|
810
|
+
async function buildPlan(root, command) {
|
|
811
|
+
const plan = [];
|
|
812
|
+
for (const [sourceRel, targetRel] of mappings) {
|
|
813
|
+
const sourceAbs = path.join(packageRoot, sourceRel);
|
|
814
|
+
const targetAbs = path.join(root, targetRel);
|
|
815
|
+
const sourceText = await readFile(sourceAbs, "utf8");
|
|
816
|
+
if (await exists(targetAbs)) {
|
|
817
|
+
const targetText = await readFile(targetAbs, "utf8");
|
|
818
|
+
plan.push(classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAbs, sourceText, targetText));
|
|
819
|
+
continue;
|
|
820
|
+
}
|
|
821
|
+
plan.push({
|
|
822
|
+
sourceRel,
|
|
823
|
+
targetRel,
|
|
824
|
+
sourceAbs,
|
|
825
|
+
targetAbs,
|
|
826
|
+
action: "create"
|
|
827
|
+
});
|
|
828
|
+
}
|
|
829
|
+
return plan;
|
|
830
|
+
}
|
|
831
|
+
|
|
832
|
+
function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAbs, sourceText, targetText) {
|
|
833
|
+
const base = { sourceRel, targetRel, sourceAbs, targetAbs };
|
|
834
|
+
if (targetText === sourceText) return { ...base, action: "skip", reason: "already current" };
|
|
835
|
+
if (command !== "upgrade") return { ...base, action: "skip", reason: "init preserves existing files" };
|
|
836
|
+
if (targetRel === "AGENTS.md") {
|
|
837
|
+
const health = assessAgentsMdHealth(targetText);
|
|
838
|
+
if (health.state === "conflict") {
|
|
839
|
+
return {
|
|
840
|
+
...base,
|
|
841
|
+
action: "conflict",
|
|
842
|
+
reason: `AGENTS.md managed-core markers are unpaired or duplicated (starts=${health.evidence.managedStart}, ends=${health.evidence.managedEnd})`
|
|
843
|
+
};
|
|
844
|
+
}
|
|
845
|
+
if (health.state === "needs-merge") {
|
|
846
|
+
return {
|
|
847
|
+
...base,
|
|
848
|
+
action: "merge",
|
|
849
|
+
reason: health.evidence.reason === "sandwich: managed marker + unmarked stale core"
|
|
850
|
+
? "replace sandwich dup core (managed marker + unmarked stale core present)"
|
|
851
|
+
: health.evidence.reason === "legacy duplicate cores"
|
|
852
|
+
? "replace duplicated legacy Agent Handoff Kit cores"
|
|
853
|
+
: "add managed core while preserving existing AGENTS.md content",
|
|
854
|
+
mergedText: mergeManagedBlock(targetText, sourceText)
|
|
855
|
+
};
|
|
856
|
+
}
|
|
857
|
+
// state === "clean": may still need legacy-core replacement or anchor catch-up
|
|
858
|
+
if (health.evidence?.upgradeable === "legacy-core") {
|
|
859
|
+
return {
|
|
860
|
+
...base,
|
|
861
|
+
action: "merge",
|
|
862
|
+
reason: "replace unmarked legacy Agent Handoff Kit core with managed-marker block",
|
|
863
|
+
mergedText: mergeManagedBlock(targetText, sourceText)
|
|
864
|
+
};
|
|
865
|
+
}
|
|
866
|
+
if (hasRequiredAnchor(targetRel, targetText)) {
|
|
867
|
+
return { ...base, action: "skip", reason: "managed core clean and required anchors present" };
|
|
868
|
+
}
|
|
869
|
+
return {
|
|
870
|
+
...base,
|
|
871
|
+
action: "merge",
|
|
872
|
+
reason: "add managed core while preserving existing AGENTS.md content",
|
|
873
|
+
mergedText: mergeManagedBlock(targetText, sourceText)
|
|
874
|
+
};
|
|
875
|
+
}
|
|
876
|
+
// R-029 v0.2.0+: RULE_PACKS.md is a routing table, not a user customization target.
|
|
877
|
+
// Stale v0.1.X versions miss the "First-time user signals" onboarding routing row.
|
|
878
|
+
// Force-refresh during upgrade so R-029 onboarding routing propagates to existing users.
|
|
879
|
+
// Any user-added custom routing rows will be lost on upgrade — this is by design;
|
|
880
|
+
// RULE_PACKS.md is treated as a maintainer-owned routing table, similar to the
|
|
881
|
+
// AGENTS.md managed-core block. User customizations belong in pack rule files
|
|
882
|
+
// (packs/*.md), not in the routing table.
|
|
883
|
+
if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("First-time user signals")) {
|
|
884
|
+
return {
|
|
885
|
+
...base,
|
|
886
|
+
action: "merge",
|
|
887
|
+
reason: "refresh stale routing table to include v0.2.0+ rows (新手引導 signal routing)",
|
|
888
|
+
mergedText: sourceText
|
|
889
|
+
};
|
|
890
|
+
}
|
|
891
|
+
// R-030 v0.3.0+: dev/RULE_PACKS.md must also include integrations pack routing row.
|
|
892
|
+
if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("dev/rules/integrations.md")) {
|
|
893
|
+
return {
|
|
894
|
+
...base,
|
|
895
|
+
action: "merge",
|
|
896
|
+
reason: "refresh stale routing table to include v0.3.0+ rows (Integration governance routing)",
|
|
897
|
+
mergedText: sourceText
|
|
898
|
+
};
|
|
899
|
+
}
|
|
900
|
+
// R-030 v0.3.0+: dev/PROJECT_INDEX.md gets ## Installed Integrations section auto-inserted before
|
|
901
|
+
// ## Local QC Commands on upgrade if missing. NON-DESTRUCTIVE: existing ## External Sources content
|
|
902
|
+
// is fully preserved (including any user-filled rows). User can later manually add the `via` column
|
|
903
|
+
// to External Sources rows (or AI can guide that incremental migration during a later session).
|
|
904
|
+
if (targetRel === "dev/PROJECT_INDEX.md" && command === "upgrade" && !targetText.includes("## Installed Integrations")) {
|
|
905
|
+
// Extract just the ## Installed Integrations block from source (not touching External Sources).
|
|
906
|
+
const sourceInstalledMatch = sourceText.match(/(## Installed Integrations[\s\S]*?)(?=## Local QC Commands)/);
|
|
907
|
+
if (sourceInstalledMatch && targetText.includes("## Local QC Commands")) {
|
|
908
|
+
const installedBlock = sourceInstalledMatch[1];
|
|
909
|
+
return {
|
|
910
|
+
...base,
|
|
911
|
+
action: "merge",
|
|
912
|
+
reason: "insert ## Installed Integrations section template before ## Local QC Commands (R-030 Integration governance migration; existing External Sources content preserved non-destructively)",
|
|
913
|
+
mergedText: targetText.replace("## Local QC Commands", installedBlock + "## Local QC Commands")
|
|
914
|
+
};
|
|
915
|
+
}
|
|
916
|
+
}
|
|
917
|
+
// R-030 v0.3.0+: dev/rules/onboarding.md gets ### Scenario F block auto-inserted before
|
|
918
|
+
// ## Cross-reference to guide.html on upgrade if missing. NON-DESTRUCTIVE: existing Scenarios A-E
|
|
919
|
+
// content and any user customization preserved. Step 1 micro-question additions to Scenarios A-E
|
|
920
|
+
// are NOT auto-migrated (user-customizable inline sample wording, not anchor-enforced); users get
|
|
921
|
+
// those on fresh install only or can manually patch following CHANGELOG migration guidance.
|
|
922
|
+
if (targetRel === "dev/rules/onboarding.md" && command === "upgrade" && !targetText.includes("Scenario F. 審視已裝外部工具")) {
|
|
923
|
+
const sourceScenarioFMatch = sourceText.match(/(### Scenario F\. 審視已裝外部工具[\s\S]*?)(?=## Cross-reference to guide\.html)/);
|
|
924
|
+
if (sourceScenarioFMatch && targetText.includes("## Cross-reference to guide.html")) {
|
|
925
|
+
const scenarioFBlock = sourceScenarioFMatch[1];
|
|
926
|
+
return {
|
|
927
|
+
...base,
|
|
928
|
+
action: "merge",
|
|
929
|
+
reason: "insert ### Scenario F block before ## Cross-reference to guide.html (R-030 onboarding pack migration; existing Scenarios A-E content preserved non-destructively)",
|
|
930
|
+
mergedText: targetText.replace("## Cross-reference to guide.html", scenarioFBlock + "## Cross-reference to guide.html")
|
|
931
|
+
};
|
|
932
|
+
}
|
|
933
|
+
}
|
|
934
|
+
if ((targetRel === "CLAUDE.md" || targetRel === "GEMINI.md") && !targetText.includes("AGENTS.md")) {
|
|
935
|
+
return { ...base, action: "conflict", reason: "existing bridge does not route to AGENTS.md" };
|
|
936
|
+
}
|
|
937
|
+
return { ...base, action: "skip", reason: "preserve existing file" };
|
|
938
|
+
}
|
|
939
|
+
|
|
940
|
+
// R-010 SESSION_LOG handoff-role discipline (warn-only doctor check).
|
|
941
|
+
// Returns { ok, warnings } where:
|
|
942
|
+
// - ok: true if no warnings triggered
|
|
943
|
+
// - warnings: array of Chinese, actionable warning strings
|
|
944
|
+
// Thresholds (all warn-only; doctor exit unaffected):
|
|
945
|
+
// - H2 entry count ≥ 11 → warn (archive boundary; AI closeout flow should auto-advance)
|
|
946
|
+
// - H2 entry count ≥ 25 → warn (severe drift; suggest AI re-do closeout)
|
|
947
|
+
// - line count ≥ 1500 → warn (anomalous entry size; safety net)
|
|
948
|
+
async function assessSessionLogDiscipline(root) {
|
|
949
|
+
const logPath = path.join(root, "dev/SESSION_LOG.md");
|
|
950
|
+
let text = "";
|
|
951
|
+
try {
|
|
952
|
+
text = await readFile(logPath, "utf8");
|
|
953
|
+
} catch {
|
|
954
|
+
return { ok: false, warnings: ["dev/SESSION_LOG.md unreadable; discipline check skipped"] };
|
|
955
|
+
}
|
|
956
|
+
|
|
957
|
+
const warnings = [];
|
|
958
|
+
const entryMatches = text.match(/^## \d{4}-\d{2}-\d{2}/gm) || [];
|
|
959
|
+
const entryCount = entryMatches.length;
|
|
960
|
+
const lineCount = text.split("\n").length;
|
|
961
|
+
|
|
962
|
+
if (entryCount >= 25) {
|
|
963
|
+
warnings.push(`SESSION_LOG entry count = ${entryCount}(嚴重超過 N=11+ archive 邊界;接力角色紀律下,AI closeout flow 應該已自動推進 N 規則,如未動請要求 AI 重做 closeout)`);
|
|
964
|
+
} else if (entryCount >= 11) {
|
|
965
|
+
warnings.push(`SESSION_LOG entry count = ${entryCount}(達 N=11+ archive 邊界;下次 closeout 時 AI 應自動執行 N 規則推進,如未動請提醒)`);
|
|
966
|
+
}
|
|
967
|
+
|
|
968
|
+
if (lineCount >= 1500) {
|
|
969
|
+
warnings.push(`SESSION_LOG line count = ${lineCount}(超過 1500 安全網閾值;可能 entry 異常長)`);
|
|
970
|
+
}
|
|
971
|
+
|
|
972
|
+
return { ok: warnings.length === 0, warnings };
|
|
973
|
+
}
|
|
974
|
+
|
|
975
|
+
// R-024 唯一真源:AGENTS.md 健康判斷合三為一函數。
|
|
976
|
+
// Returns { state, evidence } where state ∈ { clean, needs-merge, conflict }.
|
|
977
|
+
// - clean: structurally healthy
|
|
978
|
+
// * exactly one paired managed-core marker block with no unmarked title outside it, OR
|
|
979
|
+
// * no managed marker and exactly one core title (fresh-init legacy form)
|
|
980
|
+
// - needs-merge: stale state that upgrade must replace
|
|
981
|
+
// * managed marker pair plus unmarked title outside it (sandwich), or
|
|
982
|
+
// * no managed marker with two or more title duplicates, or
|
|
983
|
+
// * no managed marker and no title at all (file exists but Kit core absent)
|
|
984
|
+
// - conflict: structural breakage
|
|
985
|
+
// * managed-core markers unpaired or duplicated
|
|
986
|
+
function assessAgentsMdHealth(text) {
|
|
987
|
+
const managedStartCount = countOccurrences(text, managedCoreStart);
|
|
988
|
+
const managedEndCount = countOccurrences(text, managedCoreEnd);
|
|
989
|
+
|
|
990
|
+
if (managedStartCount !== managedEndCount || managedStartCount > 1) {
|
|
991
|
+
return {
|
|
992
|
+
state: "conflict",
|
|
993
|
+
evidence: {
|
|
994
|
+
managedStart: managedStartCount,
|
|
995
|
+
managedEnd: managedEndCount,
|
|
996
|
+
reason: "managed-core markers unpaired or duplicated"
|
|
997
|
+
}
|
|
998
|
+
};
|
|
999
|
+
}
|
|
1000
|
+
|
|
1001
|
+
let managedRange = null;
|
|
1002
|
+
if (managedStartCount === 1) {
|
|
1003
|
+
const start = text.indexOf(managedCoreStart);
|
|
1004
|
+
const endStart = text.indexOf(managedCoreEnd, start);
|
|
1005
|
+
if (endStart < 0 || endStart < start) {
|
|
1006
|
+
return {
|
|
1007
|
+
state: "conflict",
|
|
1008
|
+
evidence: {
|
|
1009
|
+
managedStart: managedStartCount,
|
|
1010
|
+
managedEnd: managedEndCount,
|
|
1011
|
+
reason: "managed-core end marker missing or before start"
|
|
1012
|
+
}
|
|
1013
|
+
};
|
|
1014
|
+
}
|
|
1015
|
+
managedRange = { start, end: endStart + managedCoreEnd.length };
|
|
1016
|
+
}
|
|
1017
|
+
|
|
1018
|
+
// Only count real top-level headings (line-anchored), not inline mentions inside backticks.
|
|
1019
|
+
const titlePositions = locateCoreTitlePositions(text);
|
|
1020
|
+
|
|
1021
|
+
const titlesOutsideManaged = titlePositions.filter((pos) =>
|
|
1022
|
+
!managedRange || pos < managedRange.start || pos >= managedRange.end
|
|
1023
|
+
);
|
|
1024
|
+
|
|
1025
|
+
// Case A: managed marker pair present
|
|
1026
|
+
if (managedStartCount === 1) {
|
|
1027
|
+
if (titlesOutsideManaged.length > 0) {
|
|
1028
|
+
const unmarkedRange = computeUnmarkedRange(text, titlesOutsideManaged[0], managedRange);
|
|
1029
|
+
return {
|
|
1030
|
+
state: "needs-merge",
|
|
1031
|
+
evidence: {
|
|
1032
|
+
managedStart: 1,
|
|
1033
|
+
titleCount: titlePositions.length,
|
|
1034
|
+
unmarkedTitleCount: titlesOutsideManaged.length,
|
|
1035
|
+
unmarkedRange,
|
|
1036
|
+
reason: "sandwich: managed marker + unmarked stale core"
|
|
1037
|
+
}
|
|
1038
|
+
};
|
|
1039
|
+
}
|
|
1040
|
+
return {
|
|
1041
|
+
state: "clean",
|
|
1042
|
+
evidence: {
|
|
1043
|
+
managedStart: 1,
|
|
1044
|
+
titleCount: titlePositions.length,
|
|
1045
|
+
reason: "single managed core, no unmarked dup"
|
|
1046
|
+
}
|
|
1047
|
+
};
|
|
1048
|
+
}
|
|
1049
|
+
|
|
1050
|
+
// Case B: no managed marker
|
|
1051
|
+
if (titlePositions.length === 1) {
|
|
1052
|
+
// Structurally healthy (single heading, no dup), but upgrade should still replace
|
|
1053
|
+
// this legacy core form with a managed-marker block. doctor passes; upgrade merges.
|
|
1054
|
+
return {
|
|
1055
|
+
state: "clean",
|
|
1056
|
+
evidence: {
|
|
1057
|
+
managedStart: 0,
|
|
1058
|
+
titleCount: 1,
|
|
1059
|
+
upgradeable: "legacy-core",
|
|
1060
|
+
legacyRange: computeUnmarkedRange(text, titlePositions[0], null),
|
|
1061
|
+
reason: "single legacy core, no managed marker"
|
|
1062
|
+
}
|
|
1063
|
+
};
|
|
1064
|
+
}
|
|
1065
|
+
if (titlePositions.length > 1) {
|
|
1066
|
+
return {
|
|
1067
|
+
state: "needs-merge",
|
|
1068
|
+
evidence: {
|
|
1069
|
+
managedStart: 0,
|
|
1070
|
+
titleCount: titlePositions.length,
|
|
1071
|
+
unmarkedTitleCount: titlePositions.length,
|
|
1072
|
+
unmarkedRange: computeUnmarkedRange(text, titlePositions[0], null),
|
|
1073
|
+
reason: "legacy duplicate cores"
|
|
1074
|
+
}
|
|
1075
|
+
};
|
|
1076
|
+
}
|
|
1077
|
+
return {
|
|
1078
|
+
state: "needs-merge",
|
|
1079
|
+
evidence: {
|
|
1080
|
+
managedStart: 0,
|
|
1081
|
+
titleCount: 0,
|
|
1082
|
+
reason: "no Kit core present"
|
|
1083
|
+
}
|
|
1084
|
+
};
|
|
1085
|
+
}
|
|
1086
|
+
|
|
1087
|
+
// Locate Kit core titles that are real top-level headings (line-anchored).
|
|
1088
|
+
// This intentionally excludes inline mentions like `# Agent Handoff Kit Core Runtime`
|
|
1089
|
+
// inside backticks or prose, so the assess function only reacts to real duplicate headings.
|
|
1090
|
+
function locateCoreTitlePositions(text) {
|
|
1091
|
+
const regex = /(^|\n)# Agent Handoff Kit Core Runtime(?=\r?\n|$)/g;
|
|
1092
|
+
const positions = [];
|
|
1093
|
+
let match;
|
|
1094
|
+
while ((match = regex.exec(text)) !== null) {
|
|
1095
|
+
const headingStart = match.index + (match[1] === "\n" ? 1 : 0);
|
|
1096
|
+
positions.push(headingStart);
|
|
1097
|
+
}
|
|
1098
|
+
return positions;
|
|
1099
|
+
}
|
|
1100
|
+
|
|
1101
|
+
function computeUnmarkedRange(text, titleStart, managedRange) {
|
|
1102
|
+
const titleNeedle = "# Agent Handoff Kit Core Runtime";
|
|
1103
|
+
const terminal = "keep the core within budget.";
|
|
1104
|
+
const terminalIndex = text.indexOf(terminal, titleStart);
|
|
1105
|
+
if (terminalIndex >= 0 && (!managedRange || terminalIndex < managedRange.start || terminalIndex >= managedRange.end)) {
|
|
1106
|
+
return { start: titleStart, end: terminalIndex + terminal.length };
|
|
1107
|
+
}
|
|
1108
|
+
const afterTitle = titleStart + titleNeedle.length;
|
|
1109
|
+
const remainder = text.slice(afterTitle);
|
|
1110
|
+
// Find next real top-level heading that is NOT another Kit core heading.
|
|
1111
|
+
const nextTopLevel = remainder.search(/\n# (?!Agent Handoff Kit Core Runtime(?=\r?\n|$))/);
|
|
1112
|
+
if (nextTopLevel < 0) return { start: titleStart, end: text.length };
|
|
1113
|
+
return { start: titleStart, end: afterTitle + nextTopLevel + 1 };
|
|
1114
|
+
}
|
|
1115
|
+
|
|
1116
|
+
function mergeManagedBlock(targetText, sourceText) {
|
|
1117
|
+
const block = `${managedCoreStart}\n${sourceText.trim()}\n${managedCoreEnd}`;
|
|
1118
|
+
|
|
1119
|
+
// Strip every unmarked / legacy core range first; iterate to handle multiple legacy stacks.
|
|
1120
|
+
let working = targetText;
|
|
1121
|
+
for (let i = 0; i < 5; i += 1) {
|
|
1122
|
+
const probe = assessAgentsMdHealth(working);
|
|
1123
|
+
const range = probe.evidence?.unmarkedRange ?? probe.evidence?.legacyRange;
|
|
1124
|
+
if (!range) break;
|
|
1125
|
+
const before = working.slice(0, range.start).trimEnd();
|
|
1126
|
+
const after = working.slice(range.end).trimStart();
|
|
1127
|
+
working = before + (before && after ? "\n\n" : before ? "\n" : "") + after;
|
|
1128
|
+
}
|
|
1129
|
+
|
|
1130
|
+
const existingBlock = new RegExp(`${escapeRegExp(managedCoreStart)}[\\s\\S]*?${escapeRegExp(managedCoreEnd)}`);
|
|
1131
|
+
if (existingBlock.test(working)) {
|
|
1132
|
+
return `${working.replace(existingBlock, block).trimEnd()}\n`;
|
|
1133
|
+
}
|
|
1134
|
+
if (working.trim().length === 0) return `${block}\n`;
|
|
1135
|
+
return `${working.trimEnd()}\n\n${block}\n`;
|
|
1136
|
+
}
|
|
1137
|
+
|
|
1138
|
+
function countOccurrences(text, needle) {
|
|
1139
|
+
return text.split(needle).length - 1;
|
|
1140
|
+
}
|
|
1141
|
+
|
|
1142
|
+
function escapeRegExp(text) {
|
|
1143
|
+
return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
1144
|
+
}
|
|
1145
|
+
|
|
1146
|
+
function hasRequiredAnchor(targetRel, text) {
|
|
1147
|
+
return requiredAnchors
|
|
1148
|
+
.filter((rule) => rule.target === targetRel)
|
|
1149
|
+
.every((rule) => rule.snippets.every((snippet) => text.includes(snippet)));
|
|
1150
|
+
}
|
|
1151
|
+
|
|
1152
|
+
async function detectMode(root) {
|
|
1153
|
+
const hasAgents = await exists(path.join(root, "AGENTS.md"));
|
|
1154
|
+
const hasProjectIndex = await exists(path.join(root, "dev/PROJECT_INDEX.md"));
|
|
1155
|
+
const hasDocSync = await exists(path.join(root, "dev/DOC_SYNC_REGISTRY.md"));
|
|
1156
|
+
if (!hasAgents && !hasProjectIndex && !hasDocSync) return "first-install";
|
|
1157
|
+
if (hasAgents && hasProjectIndex && hasDocSync) return "upgrade-existing";
|
|
1158
|
+
if (hasAgents) {
|
|
1159
|
+
const text = await readFile(path.join(root, "AGENTS.md"), "utf8");
|
|
1160
|
+
if (text.includes("SESSION_HANDOFF") || text.includes("SESSION_LOG")) return "migrate-monolith";
|
|
1161
|
+
}
|
|
1162
|
+
return "partial";
|
|
1163
|
+
}
|
|
1164
|
+
|
|
1165
|
+
function printPlan(command, root, mode, plan, version) {
|
|
1166
|
+
printCard(version, "continuity ready", "o.o");
|
|
1167
|
+
console.log(`command: ${command}`);
|
|
1168
|
+
console.log(`current directory: ${process.cwd()}`);
|
|
1169
|
+
console.log(`selected root: ${root}`);
|
|
1170
|
+
console.log(`mode: ${mode}`);
|
|
1171
|
+
console.log("");
|
|
1172
|
+
console.log("📋 計劃預覽:以下未執行。create 新增缺少檔案;merge 在備份後合併;skip 保留既有檔案;conflict 代表工具停手等你確認。");
|
|
1173
|
+
console.log("");
|
|
1174
|
+
for (const action of ["create", "merge", "skip", "conflict"]) {
|
|
1175
|
+
const items = plan.filter((item) => item.action === action);
|
|
1176
|
+
console.log(`${action}: ${items.length}`);
|
|
1177
|
+
for (const item of items) console.log(` ${item.targetRel}${item.reason ? ` - ${item.reason}` : ""}`);
|
|
1178
|
+
}
|
|
1179
|
+
console.log(`\nbackup: ${plan.filter((item) => item.action === "merge").length}`);
|
|
1180
|
+
}
|
|
1181
|
+
|
|
1182
|
+
// R-026 CLI Output Contract: install/upgrade 完成必含四項(版本/模式/剛做咗乜/下一步)。
|
|
1183
|
+
function printInstallSummary(version, command, mode, root, counts) {
|
|
1184
|
+
console.log(`\n✅ created: ${counts.created}`);
|
|
1185
|
+
console.log(`🔀 merged: ${counts.merged}`);
|
|
1186
|
+
console.log(`⏭️ skipped existing: ${counts.skipped}`);
|
|
1187
|
+
console.log(`${counts.conflicts > 0 ? "⚠️ " : "✅ "}conflict: ${counts.conflicts}`);
|
|
1188
|
+
if (counts.backupRel) console.log(`💾 backup: ${counts.backupRel}`);
|
|
1189
|
+
if (counts.reportRel) console.log(`📄 migration report: ${counts.reportRel}`);
|
|
1190
|
+
console.log("");
|
|
1191
|
+
console.log(`📦 版本:v${version}`);
|
|
1192
|
+
console.log(`🛠️ 模式:${mode}`);
|
|
1193
|
+
console.log(`🔎 剛做咗:${command} 命令;create ${counts.created} / merge ${counts.merged} / skip ${counts.skipped} / conflict ${counts.conflicts}。`);
|
|
1194
|
+
if (counts.conflicts > 0) {
|
|
1195
|
+
console.log("🚀 下一步:把 migration report 或這段輸出貼給 AI,請它判斷 conflict 點處理;工具已停手,沒有覆寫 conflict 檔案。");
|
|
1196
|
+
} else if (command === "upgrade") {
|
|
1197
|
+
console.log("🚀 下一步:留意下方 upgrade self-check(自動跑 doctor);若全綠即升級完成。");
|
|
1198
|
+
} else {
|
|
1199
|
+
console.log("🚀 下一步:開新 AI 對話,按下方提示貼入 Work in <root> 一句後描述任務。");
|
|
1200
|
+
}
|
|
1201
|
+
}
|
|
1202
|
+
|
|
1203
|
+
function printDryRunExplanation(plan) {
|
|
1204
|
+
const conflicts = plan.filter((item) => item.action === "conflict");
|
|
1205
|
+
console.log("✅ 這次沒有改動任何檔案。");
|
|
1206
|
+
if (conflicts.length === 0) {
|
|
1207
|
+
console.log("✅ 沒有發現 conflict。你仍應先看清楚 create / merge / skip 清單,再決定是否執行正式 upgrade。");
|
|
1208
|
+
return;
|
|
1209
|
+
}
|
|
1210
|
+
console.log(`⚠️ 需要人工確認:有 ${conflicts.length} 個既有檔案,工具不能安全判斷怎樣合併。`);
|
|
1211
|
+
console.log("⚠️ 這不是檔案壞掉,也沒有覆寫你的檔案。");
|
|
1212
|
+
console.log("📋 下一步:把這段輸出貼給 AI,叫它幫你判斷要保留、合併,還是手動修改。");
|
|
1213
|
+
}
|
|
1214
|
+
|
|
1215
|
+
async function confirmWrite() {
|
|
1216
|
+
const rl = createInterface({ input, output });
|
|
1217
|
+
try {
|
|
1218
|
+
const answer = await rl.question("Write missing Agent Handoff Kit files? Type yes to continue: ");
|
|
1219
|
+
return answer.trim().toLowerCase() === "yes";
|
|
1220
|
+
} finally {
|
|
1221
|
+
rl.close();
|
|
1222
|
+
}
|
|
1223
|
+
}
|
|
1224
|
+
|
|
1225
|
+
async function writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir) {
|
|
1226
|
+
const reportPath = path.join(migrationDir, "migration-report.md");
|
|
1227
|
+
await mkdir(migrationDir, { recursive: true });
|
|
1228
|
+
const skipped = plan.filter((item) => item.action === "skip").map((item) => item.targetRel);
|
|
1229
|
+
const text = [
|
|
1230
|
+
"# Agent Handoff Kit Migration Report",
|
|
1231
|
+
"",
|
|
1232
|
+
`Command: ${command}`,
|
|
1233
|
+
`Mode: ${mode}`,
|
|
1234
|
+
`Root: ${root}`,
|
|
1235
|
+
`Created: ${new Date().toISOString()}`,
|
|
1236
|
+
"",
|
|
1237
|
+
"## Created",
|
|
1238
|
+
...listOrNone(created),
|
|
1239
|
+
"",
|
|
1240
|
+
"## Merged",
|
|
1241
|
+
...listOrNone(merged),
|
|
1242
|
+
"",
|
|
1243
|
+
"## Skipped Existing",
|
|
1244
|
+
...listOrNone(skipped),
|
|
1245
|
+
"",
|
|
1246
|
+
"## Conflicts",
|
|
1247
|
+
...listOrNone(conflicts.map((item) => `${item.targetRel} - ${item.reason}`)),
|
|
1248
|
+
"",
|
|
1249
|
+
"## Backup",
|
|
1250
|
+
merged.length > 0 ? `- ${path.relative(root, backupDir)}` : "- none",
|
|
1251
|
+
"",
|
|
1252
|
+
"## Notes",
|
|
1253
|
+
"- Existing files are preserved unless the installer can perform a bounded merge.",
|
|
1254
|
+
"- Files that cannot be safely merged are reported as conflicts and are not overwritten."
|
|
1255
|
+
].join("\n");
|
|
1256
|
+
await writeFile(reportPath, `${text}\n`, "utf8");
|
|
1257
|
+
return reportPath;
|
|
1258
|
+
}
|
|
1259
|
+
|
|
1260
|
+
function migrationStamp() {
|
|
1261
|
+
return new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
|
|
1262
|
+
}
|
|
1263
|
+
|
|
1264
|
+
async function readPackageVersion() {
|
|
1265
|
+
try {
|
|
1266
|
+
const text = await readFile(path.join(packageRoot, "package.json"), "utf8");
|
|
1267
|
+
return JSON.parse(text).version ?? "version unverified";
|
|
1268
|
+
} catch {
|
|
1269
|
+
return "version unverified";
|
|
1270
|
+
}
|
|
1271
|
+
}
|
|
1272
|
+
|
|
1273
|
+
async function maybePrintUpdateNotice(currentVersion) {
|
|
1274
|
+
if (shouldSkipUpdateCheck()) return;
|
|
1275
|
+
if (!isStableSemver(currentVersion)) return;
|
|
1276
|
+
|
|
1277
|
+
const latestVersion = await fetchLatestVersion();
|
|
1278
|
+
if (!latestVersion || !isStableSemver(latestVersion)) return;
|
|
1279
|
+
if (compareSemver(latestVersion, currentVersion) <= 0) return;
|
|
1280
|
+
|
|
1281
|
+
printUpdateNotice(currentVersion, latestVersion);
|
|
1282
|
+
}
|
|
1283
|
+
|
|
1284
|
+
function shouldSkipUpdateCheck() {
|
|
1285
|
+
if (process.env.AGENT_HANDOFF_KIT_NO_UPDATE_CHECK === "1") return true;
|
|
1286
|
+
if (process.env.AGENT_HANDOFF_KIT_UPDATE_CHECK_FORCE === "1") return false;
|
|
1287
|
+
if (process.env.CI) return true;
|
|
1288
|
+
if ((process.env.npm_lifecycle_event ?? "").startsWith("qa:")) return true;
|
|
1289
|
+
return false;
|
|
1290
|
+
}
|
|
1291
|
+
|
|
1292
|
+
async function fetchLatestVersion() {
|
|
1293
|
+
if (process.env.AGENT_HANDOFF_KIT_UPDATE_MOCK_LATEST) {
|
|
1294
|
+
return process.env.AGENT_HANDOFF_KIT_UPDATE_MOCK_LATEST;
|
|
1295
|
+
}
|
|
1296
|
+
const url = process.env.AGENT_HANDOFF_KIT_UPDATE_REGISTRY_URL
|
|
1297
|
+
?? "https://registry.npmjs.org/@adamchanadam%2Fagent-handoff-kit/latest";
|
|
1298
|
+
const timeoutMs = Number.parseInt(process.env.AGENT_HANDOFF_KIT_UPDATE_TIMEOUT_MS ?? "1200", 10);
|
|
1299
|
+
const controller = new AbortController();
|
|
1300
|
+
const timer = setTimeout(() => controller.abort(), Number.isFinite(timeoutMs) ? timeoutMs : 1200);
|
|
1301
|
+
try {
|
|
1302
|
+
const response = await fetch(url, {
|
|
1303
|
+
headers: { accept: "application/vnd.npm.install-v1+json, application/json" },
|
|
1304
|
+
signal: controller.signal
|
|
1305
|
+
});
|
|
1306
|
+
if (!response.ok) return null;
|
|
1307
|
+
const data = await response.json();
|
|
1308
|
+
return typeof data.version === "string" ? data.version : null;
|
|
1309
|
+
} catch {
|
|
1310
|
+
return null;
|
|
1311
|
+
} finally {
|
|
1312
|
+
clearTimeout(timer);
|
|
1313
|
+
}
|
|
1314
|
+
}
|
|
1315
|
+
|
|
1316
|
+
function isStableSemver(version) {
|
|
1317
|
+
return /^\d+\.\d+\.\d+$/.test(version);
|
|
1318
|
+
}
|
|
1319
|
+
|
|
1320
|
+
function compareSemver(left, right) {
|
|
1321
|
+
const leftParts = left.split(".").map((part) => Number.parseInt(part, 10));
|
|
1322
|
+
const rightParts = right.split(".").map((part) => Number.parseInt(part, 10));
|
|
1323
|
+
for (let i = 0; i < 3; i += 1) {
|
|
1324
|
+
if (leftParts[i] > rightParts[i]) return 1;
|
|
1325
|
+
if (leftParts[i] < rightParts[i]) return -1;
|
|
1326
|
+
}
|
|
1327
|
+
return 0;
|
|
1328
|
+
}
|
|
1329
|
+
|
|
1330
|
+
function printUpdateNotice(currentVersion, latestVersion) {
|
|
1331
|
+
const releaseUrl = "https://github.com/Adamchanadam/agent-handoff-kit/releases/latest";
|
|
1332
|
+
const command = "npx @adamchanadam/agent-handoff-kit@latest <command>";
|
|
1333
|
+
const lines = [
|
|
1334
|
+
`✨ 有新版可用:${currentVersion} -> ${latestVersion}`,
|
|
1335
|
+
`如要使用最新版,執行:${command}`,
|
|
1336
|
+
"",
|
|
1337
|
+
"如果你是全域安裝:",
|
|
1338
|
+
"npm install -g @adamchanadam/agent-handoff-kit",
|
|
1339
|
+
"",
|
|
1340
|
+
"完整 release notes:",
|
|
1341
|
+
releaseUrl
|
|
1342
|
+
];
|
|
1343
|
+
const width = Math.max(...lines.map((line) => visibleLength(line))) + 2;
|
|
1344
|
+
console.log(`╭${"─".repeat(width)}╮`);
|
|
1345
|
+
for (const line of lines) {
|
|
1346
|
+
console.log(`│ ${line}${" ".repeat(width - visibleLength(line) - 1)}│`);
|
|
1347
|
+
}
|
|
1348
|
+
console.log(`╰${"─".repeat(width)}╯`);
|
|
1349
|
+
console.log("");
|
|
1350
|
+
}
|
|
1351
|
+
|
|
1352
|
+
function visibleLength(text) {
|
|
1353
|
+
return [...text].length;
|
|
1354
|
+
}
|
|
1355
|
+
|
|
1356
|
+
function printCard(version, status, eyes) {
|
|
1357
|
+
console.log(` /\\_/\\ Agent Handoff Kit v${version}`);
|
|
1358
|
+
console.log(` ( ${eyes} ) ${status}`);
|
|
1359
|
+
console.log(" > ^ <");
|
|
1360
|
+
console.log("");
|
|
1361
|
+
}
|
|
1362
|
+
|
|
1363
|
+
function printInstallNextSteps(root, conflictCount) {
|
|
1364
|
+
console.log("");
|
|
1365
|
+
console.log("============================================================");
|
|
1366
|
+
console.log("✅ 安裝完成:下一步請在 AI 對話中操作");
|
|
1367
|
+
console.log("============================================================");
|
|
1368
|
+
if (conflictCount > 0) {
|
|
1369
|
+
console.log("⚠️ 狀態:有既有檔案需要人工確認,詳情見 migration report。");
|
|
1370
|
+
console.log("⚠️ 這不是檔案壞掉;工具已停手,沒有覆寫 conflict 檔案。");
|
|
1371
|
+
console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
|
|
1372
|
+
console.log("");
|
|
1373
|
+
}
|
|
1374
|
+
console.log("⚠️ 請注意:下面文字不是 Terminal 指令。");
|
|
1375
|
+
console.log("📋 請打開你要使用的 AI 工具,新增一段對話,貼上下面一句:");
|
|
1376
|
+
console.log("------------------------------------------------------------");
|
|
1377
|
+
console.log(`Work in ${root}. I just installed agent-handoff-kit. Help me get started.`);
|
|
1378
|
+
console.log("------------------------------------------------------------");
|
|
1379
|
+
console.log("");
|
|
1380
|
+
console.log("🚀 AI 會主動引導你選擇情景(寫代碼 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),");
|
|
1381
|
+
console.log(" 一步一步帶你做第一個任務(由新手引導包主動接管)。");
|
|
1382
|
+
console.log("");
|
|
1383
|
+
console.log("💡 之後 session(你已熟悉 v2 之後)可改用更直接 prompt:");
|
|
1384
|
+
console.log(` Work in ${root}. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.`);
|
|
1385
|
+
console.log("");
|
|
1386
|
+
console.log("🩺 如要檢查安裝是否完整,可在 Terminal 執行:");
|
|
1387
|
+
console.log(" npx @adamchanadam/agent-handoff-kit doctor");
|
|
1388
|
+
console.log("============================================================");
|
|
1389
|
+
}
|
|
1390
|
+
|
|
1391
|
+
function listOrNone(items) {
|
|
1392
|
+
if (items.length === 0) return ["- none"];
|
|
1393
|
+
return items.map((item) => `- ${item}`);
|
|
1394
|
+
}
|
|
1395
|
+
|
|
1396
|
+
async function exists(filePath) {
|
|
1397
|
+
try {
|
|
1398
|
+
await stat(filePath);
|
|
1399
|
+
return true;
|
|
1400
|
+
} catch {
|
|
1401
|
+
return false;
|
|
1402
|
+
}
|
|
1403
|
+
}
|
|
1404
|
+
|
|
1405
|
+
function printHelp(version) {
|
|
1406
|
+
printCard(version, "continuity ready", "o.o");
|
|
1407
|
+
console.log(`Agent Handoff Kit
|
|
1408
|
+
|
|
1409
|
+
Usage:
|
|
1410
|
+
agent-handoff-kit init [--dry-run] [--yes] [--root <path>]
|
|
1411
|
+
agent-handoff-kit upgrade [--dry-run] [--yes] [--root <path>]
|
|
1412
|
+
agent-handoff-kit doctor [--root <path>]
|
|
1413
|
+
|
|
1414
|
+
Commands:
|
|
1415
|
+
init Plan or install missing core files and rule packs.
|
|
1416
|
+
upgrade Preserve existing files; merge safe core updates or report conflicts.
|
|
1417
|
+
doctor Check required installed files.
|
|
1418
|
+
|
|
1419
|
+
中文速讀:
|
|
1420
|
+
✅ init 第一次安裝 Kit 文件。
|
|
1421
|
+
🔄 upgrade 升級既有 Kit 文件;先用 --dry-run 預演。
|
|
1422
|
+
🩺 doctor 檢查必要文件與交接結構是否完整。
|
|
1423
|
+
|
|
1424
|
+
After install:
|
|
1425
|
+
Do not type the shown "Work in ..." message into Terminal.
|
|
1426
|
+
Open your AI tool, start a new chat, and paste it there.
|
|
1427
|
+
The default post-install prompt triggers the onboarding pack — AI
|
|
1428
|
+
will guide you through scenario selection (coding / research / knowledge /
|
|
1429
|
+
learning / other / integrations governance) and walk you through your first task.
|
|
1430
|
+
`);
|
|
1431
|
+
console.log(`📦 版本:v${version}`);
|
|
1432
|
+
console.log(`🛠️ 模式:help ready`);
|
|
1433
|
+
console.log(`🚀 下一步:第一次使用先跑 init;既有專案升級用 upgrade --dry-run;要檢查現狀用 doctor。`);
|
|
1434
|
+
}
|