@adamchanadam/agent-handoff-kit 0.1.5 → 0.1.7
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 +2 -2
- package/bin/agent-handoff-kit.mjs +310 -31
- package/package.json +4 -3
- package/runtime-core/AGENTS.core.md +11 -1
- package/runtime-core/PROJECT_INDEX.md +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
狀態:`v0.1.
|
|
3
|
+
狀態:`v0.1.7` 已正式發佈到 GitHub 與 npm。這是早期可用版本,尚未宣稱所有需求已完成。
|
|
4
4
|
|
|
5
5
|

|
|
6
6
|
|
|
@@ -201,7 +201,7 @@ GitHub Pages 上的新手介紹頁 `agent-handoff-kit-intro.html` 由原始碼
|
|
|
201
201
|
|
|
202
202
|
## 目前限制
|
|
203
203
|
|
|
204
|
-
- `v0.1.
|
|
204
|
+
- `v0.1.7` 是 GitHub 與 npm 同步發佈版本。
|
|
205
205
|
- 這是早期可用版本,尚未宣稱完整穩定。
|
|
206
206
|
- 升級合併仍是窄範圍策略,不是完整的複雜合併工具。
|
|
207
207
|
- `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
|
|
@@ -162,6 +162,16 @@ const requiredAnchors = [
|
|
|
162
162
|
];
|
|
163
163
|
|
|
164
164
|
const schemaChecks = [
|
|
165
|
+
{
|
|
166
|
+
target: "AGENTS.md",
|
|
167
|
+
label: "core runtime uniqueness",
|
|
168
|
+
checks: [
|
|
169
|
+
{
|
|
170
|
+
label: "AGENTS.md health state is clean (single managed core, no unmarked dup, paired markers)",
|
|
171
|
+
test: (text) => assessAgentsMdHealth(text).state === "clean"
|
|
172
|
+
}
|
|
173
|
+
]
|
|
174
|
+
},
|
|
165
175
|
{
|
|
166
176
|
target: "dev/SESSION_HANDOFF.md",
|
|
167
177
|
label: "handoff required sections",
|
|
@@ -356,18 +366,38 @@ async function runInstall(command, root, options, version) {
|
|
|
356
366
|
}
|
|
357
367
|
|
|
358
368
|
const report = await writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir);
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
369
|
+
const skippedCount = plan.filter((item) => item.action === "skip").length;
|
|
370
|
+
printInstallSummary(version, command, mode, root, {
|
|
371
|
+
created: created.length,
|
|
372
|
+
merged: merged.length,
|
|
373
|
+
skipped: skippedCount,
|
|
374
|
+
conflicts: conflicts.length,
|
|
375
|
+
backupRel: merged.length > 0 ? path.relative(root, backupDir) : null,
|
|
376
|
+
reportRel: path.relative(root, report)
|
|
377
|
+
});
|
|
365
378
|
printInstallNextSteps(root, conflicts.length);
|
|
379
|
+
|
|
380
|
+
// R-024 upgrade.done self-check: after upgrade writes, run doctor automatically.
|
|
381
|
+
// The user must see whether the merged state actually reaches a clean health state.
|
|
382
|
+
if (command === "upgrade" && conflicts.length === 0) {
|
|
383
|
+
console.log("");
|
|
384
|
+
console.log("------------------------------------------------------------");
|
|
385
|
+
console.log("🩺 upgrade self-check: running doctor against the upgraded root");
|
|
386
|
+
console.log("------------------------------------------------------------");
|
|
387
|
+
const doctorStatus = await runDoctor(root, version, { silentCard: true });
|
|
388
|
+
if (doctorStatus !== "passed") {
|
|
389
|
+
console.log("");
|
|
390
|
+
console.log("⚠️ upgrade self-check did not pass; see doctor output above.");
|
|
391
|
+
console.log("📋 下一步:把上面 doctor 輸出貼給 AI,請它先按提示修補後再宣稱 upgrade 完成。");
|
|
392
|
+
process.exitCode = 1;
|
|
393
|
+
}
|
|
394
|
+
}
|
|
395
|
+
|
|
366
396
|
if (conflicts.length > 0) process.exitCode = 1;
|
|
367
397
|
}
|
|
368
398
|
|
|
369
|
-
async function runDoctor(root, version) {
|
|
370
|
-
printCard(version, "doctor ready", "o.o");
|
|
399
|
+
async function runDoctor(root, version, options = {}) {
|
|
400
|
+
if (!options.silentCard) printCard(version, "doctor ready", "o.o");
|
|
371
401
|
const rows = [];
|
|
372
402
|
for (const target of requiredTargets) {
|
|
373
403
|
rows.push({ target, ok: await exists(path.join(root, target)) });
|
|
@@ -381,11 +411,14 @@ async function runDoctor(root, version) {
|
|
|
381
411
|
}
|
|
382
412
|
|
|
383
413
|
if (missing.length > 0) {
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
414
|
+
printDoctorSummary(version, root, "needs-fix", {
|
|
415
|
+
checked: rows.length,
|
|
416
|
+
failedKind: "missing files",
|
|
417
|
+
failedCount: missing.length,
|
|
418
|
+
nextStep: "先確認你是否在正確專案資料夾;如是,執行 init 或 upgrade 補回缺少檔案。"
|
|
419
|
+
});
|
|
387
420
|
process.exitCode = 1;
|
|
388
|
-
return;
|
|
421
|
+
return "failed";
|
|
389
422
|
}
|
|
390
423
|
|
|
391
424
|
const anchorRows = await checkRequiredAnchors(root);
|
|
@@ -396,11 +429,14 @@ async function runDoctor(root, version) {
|
|
|
396
429
|
}
|
|
397
430
|
|
|
398
431
|
if (anchorFailures.length > 0) {
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
432
|
+
printDoctorSummary(version, root, "needs-fix", {
|
|
433
|
+
checked: rows.length + anchorRows.length,
|
|
434
|
+
failedKind: "anchor checks",
|
|
435
|
+
failedCount: anchorFailures.length,
|
|
436
|
+
nextStep: "執行 upgrade --dry-run 查看可否安全補齊;不要手動覆寫既有檔案。"
|
|
437
|
+
});
|
|
402
438
|
process.exitCode = 1;
|
|
403
|
-
return;
|
|
439
|
+
return "failed";
|
|
404
440
|
}
|
|
405
441
|
|
|
406
442
|
const schemaRows = await checkSchema(root);
|
|
@@ -414,11 +450,14 @@ async function runDoctor(root, version) {
|
|
|
414
450
|
}
|
|
415
451
|
|
|
416
452
|
if (schemaFailures.length > 0) {
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
453
|
+
printDoctorSummary(version, root, "needs-fix", {
|
|
454
|
+
checked: rows.length + anchorRows.length + schemaRows.length,
|
|
455
|
+
failedKind: "schema checks",
|
|
456
|
+
failedCount: schemaFailures.length,
|
|
457
|
+
nextStep: "把這段 doctor 輸出貼給 AI,請它先修交接結構,不要直接重裝覆蓋。"
|
|
458
|
+
});
|
|
420
459
|
process.exitCode = 1;
|
|
421
|
-
return;
|
|
460
|
+
return "failed";
|
|
422
461
|
}
|
|
423
462
|
|
|
424
463
|
const mirrorRows = await checkPromptMirror(root);
|
|
@@ -430,15 +469,40 @@ async function runDoctor(root, version) {
|
|
|
430
469
|
}
|
|
431
470
|
|
|
432
471
|
if (mirrorFailures.length > 0) {
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
472
|
+
printDoctorSummary(version, root, "needs-fix", {
|
|
473
|
+
checked: rows.length + anchorRows.length + schemaRows.length + mirrorRows.length,
|
|
474
|
+
failedKind: "prompt mirror checks",
|
|
475
|
+
failedCount: mirrorFailures.length,
|
|
476
|
+
nextStep: "以 dev/SESSION_HANDOFF.md 的 Next Session Opening Message 為準,重生 START_NEXT_SESSION_PROMPT.txt。"
|
|
477
|
+
});
|
|
436
478
|
process.exitCode = 1;
|
|
437
|
-
return;
|
|
479
|
+
return "failed";
|
|
438
480
|
}
|
|
439
481
|
|
|
440
|
-
|
|
441
|
-
|
|
482
|
+
printDoctorSummary(version, root, "healthy", {
|
|
483
|
+
checked: rows.length + anchorRows.length + schemaRows.length + mirrorRows.length,
|
|
484
|
+
failedKind: null,
|
|
485
|
+
failedCount: 0,
|
|
486
|
+
nextStep: "繼續日常使用;如要升級到較新版,執行 npx @adamchanadam/agent-handoff-kit@latest upgrade。"
|
|
487
|
+
});
|
|
488
|
+
return "passed";
|
|
489
|
+
}
|
|
490
|
+
|
|
491
|
+
// R-026 CLI Output Contract: doctor 完成必含四項(版本/模式/剛做咗乜/下一步)。
|
|
492
|
+
function printDoctorSummary(version, root, mode, details) {
|
|
493
|
+
console.log("");
|
|
494
|
+
if (mode === "healthy") {
|
|
495
|
+
console.log("status: passed");
|
|
496
|
+
console.log("✅ 檢查通過:必要文件存在,基本結構完整,下次開工提示副本也與 handoff 一致。");
|
|
497
|
+
} else {
|
|
498
|
+
console.log(`status: failed (${details.failedCount} ${details.failedKind} failed)`);
|
|
499
|
+
console.log(`⚠️ 檢查未通過:${details.failedKind === "missing files" ? "有必要檔案不存在。" : details.failedKind === "anchor checks" ? "有檔案存在,但內容缺少必要段落。" : details.failedKind === "schema checks" ? "交接或索引文件結構不完整。" : "下次開工提示副本與 handoff 真源不同。"}`);
|
|
500
|
+
}
|
|
501
|
+
console.log("");
|
|
502
|
+
console.log(`📦 版本:v${version}`);
|
|
503
|
+
console.log(`🩺 模式:${mode}`);
|
|
504
|
+
console.log(`🔎 剛做咗:檢查 ${details.checked} 項;${mode === "healthy" ? "全部通過" : `${details.failedCount} 項未通過(${details.failedKind})`}。`);
|
|
505
|
+
console.log(`🚀 下一步:${details.nextStep}`);
|
|
442
506
|
}
|
|
443
507
|
|
|
444
508
|
async function checkPromptMirror(root) {
|
|
@@ -590,11 +654,42 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
|
|
|
590
654
|
if (targetText === sourceText) return { ...base, action: "skip", reason: "already current" };
|
|
591
655
|
if (command !== "upgrade") return { ...base, action: "skip", reason: "init preserves existing files" };
|
|
592
656
|
if (targetRel === "AGENTS.md") {
|
|
593
|
-
|
|
657
|
+
const health = assessAgentsMdHealth(targetText);
|
|
658
|
+
if (health.state === "conflict") {
|
|
659
|
+
return {
|
|
660
|
+
...base,
|
|
661
|
+
action: "conflict",
|
|
662
|
+
reason: `AGENTS.md managed-core markers are unpaired or duplicated (starts=${health.evidence.managedStart}, ends=${health.evidence.managedEnd})`
|
|
663
|
+
};
|
|
664
|
+
}
|
|
665
|
+
if (health.state === "needs-merge") {
|
|
666
|
+
return {
|
|
667
|
+
...base,
|
|
668
|
+
action: "merge",
|
|
669
|
+
reason: health.evidence.reason === "sandwich: managed marker + unmarked stale core"
|
|
670
|
+
? "replace sandwich dup core (managed marker + unmarked stale core present)"
|
|
671
|
+
: health.evidence.reason === "legacy duplicate cores"
|
|
672
|
+
? "replace duplicated legacy Agent Handoff Kit cores"
|
|
673
|
+
: "add managed core while preserving existing AGENTS.md content",
|
|
674
|
+
mergedText: mergeManagedBlock(targetText, sourceText)
|
|
675
|
+
};
|
|
676
|
+
}
|
|
677
|
+
// state === "clean": may still need legacy-core replacement or anchor catch-up
|
|
678
|
+
if (health.evidence?.upgradeable === "legacy-core") {
|
|
679
|
+
return {
|
|
680
|
+
...base,
|
|
681
|
+
action: "merge",
|
|
682
|
+
reason: "replace unmarked legacy Agent Handoff Kit core with managed-marker block",
|
|
683
|
+
mergedText: mergeManagedBlock(targetText, sourceText)
|
|
684
|
+
};
|
|
685
|
+
}
|
|
686
|
+
if (hasRequiredAnchor(targetRel, targetText)) {
|
|
687
|
+
return { ...base, action: "skip", reason: "managed core clean and required anchors present" };
|
|
688
|
+
}
|
|
594
689
|
return {
|
|
595
690
|
...base,
|
|
596
691
|
action: "merge",
|
|
597
|
-
reason: "
|
|
692
|
+
reason: "add managed core while preserving existing AGENTS.md content",
|
|
598
693
|
mergedText: mergeManagedBlock(targetText, sourceText)
|
|
599
694
|
};
|
|
600
695
|
}
|
|
@@ -604,11 +699,171 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
|
|
|
604
699
|
return { ...base, action: "skip", reason: "preserve existing file" };
|
|
605
700
|
}
|
|
606
701
|
|
|
702
|
+
// R-024 唯一真源:AGENTS.md 健康判斷合三為一函數。
|
|
703
|
+
// Returns { state, evidence } where state ∈ { clean, needs-merge, conflict }.
|
|
704
|
+
// - clean: structurally healthy
|
|
705
|
+
// * exactly one paired managed-core marker block with no unmarked title outside it, OR
|
|
706
|
+
// * no managed marker and exactly one core title (fresh-init legacy form)
|
|
707
|
+
// - needs-merge: stale state that upgrade must replace
|
|
708
|
+
// * managed marker pair plus unmarked title outside it (sandwich), or
|
|
709
|
+
// * no managed marker with two or more title duplicates, or
|
|
710
|
+
// * no managed marker and no title at all (file exists but Kit core absent)
|
|
711
|
+
// - conflict: structural breakage
|
|
712
|
+
// * managed-core markers unpaired or duplicated
|
|
713
|
+
function assessAgentsMdHealth(text) {
|
|
714
|
+
const managedStartCount = countOccurrences(text, managedCoreStart);
|
|
715
|
+
const managedEndCount = countOccurrences(text, managedCoreEnd);
|
|
716
|
+
|
|
717
|
+
if (managedStartCount !== managedEndCount || managedStartCount > 1) {
|
|
718
|
+
return {
|
|
719
|
+
state: "conflict",
|
|
720
|
+
evidence: {
|
|
721
|
+
managedStart: managedStartCount,
|
|
722
|
+
managedEnd: managedEndCount,
|
|
723
|
+
reason: "managed-core markers unpaired or duplicated"
|
|
724
|
+
}
|
|
725
|
+
};
|
|
726
|
+
}
|
|
727
|
+
|
|
728
|
+
let managedRange = null;
|
|
729
|
+
if (managedStartCount === 1) {
|
|
730
|
+
const start = text.indexOf(managedCoreStart);
|
|
731
|
+
const endStart = text.indexOf(managedCoreEnd, start);
|
|
732
|
+
if (endStart < 0 || endStart < start) {
|
|
733
|
+
return {
|
|
734
|
+
state: "conflict",
|
|
735
|
+
evidence: {
|
|
736
|
+
managedStart: managedStartCount,
|
|
737
|
+
managedEnd: managedEndCount,
|
|
738
|
+
reason: "managed-core end marker missing or before start"
|
|
739
|
+
}
|
|
740
|
+
};
|
|
741
|
+
}
|
|
742
|
+
managedRange = { start, end: endStart + managedCoreEnd.length };
|
|
743
|
+
}
|
|
744
|
+
|
|
745
|
+
// Only count real top-level headings (line-anchored), not inline mentions inside backticks.
|
|
746
|
+
const titlePositions = locateCoreTitlePositions(text);
|
|
747
|
+
|
|
748
|
+
const titlesOutsideManaged = titlePositions.filter((pos) =>
|
|
749
|
+
!managedRange || pos < managedRange.start || pos >= managedRange.end
|
|
750
|
+
);
|
|
751
|
+
|
|
752
|
+
// Case A: managed marker pair present
|
|
753
|
+
if (managedStartCount === 1) {
|
|
754
|
+
if (titlesOutsideManaged.length > 0) {
|
|
755
|
+
const unmarkedRange = computeUnmarkedRange(text, titlesOutsideManaged[0], managedRange);
|
|
756
|
+
return {
|
|
757
|
+
state: "needs-merge",
|
|
758
|
+
evidence: {
|
|
759
|
+
managedStart: 1,
|
|
760
|
+
titleCount: titlePositions.length,
|
|
761
|
+
unmarkedTitleCount: titlesOutsideManaged.length,
|
|
762
|
+
unmarkedRange,
|
|
763
|
+
reason: "sandwich: managed marker + unmarked stale core"
|
|
764
|
+
}
|
|
765
|
+
};
|
|
766
|
+
}
|
|
767
|
+
return {
|
|
768
|
+
state: "clean",
|
|
769
|
+
evidence: {
|
|
770
|
+
managedStart: 1,
|
|
771
|
+
titleCount: titlePositions.length,
|
|
772
|
+
reason: "single managed core, no unmarked dup"
|
|
773
|
+
}
|
|
774
|
+
};
|
|
775
|
+
}
|
|
776
|
+
|
|
777
|
+
// Case B: no managed marker
|
|
778
|
+
if (titlePositions.length === 1) {
|
|
779
|
+
// Structurally healthy (single heading, no dup), but upgrade should still replace
|
|
780
|
+
// this legacy core form with a managed-marker block. doctor passes; upgrade merges.
|
|
781
|
+
return {
|
|
782
|
+
state: "clean",
|
|
783
|
+
evidence: {
|
|
784
|
+
managedStart: 0,
|
|
785
|
+
titleCount: 1,
|
|
786
|
+
upgradeable: "legacy-core",
|
|
787
|
+
legacyRange: computeUnmarkedRange(text, titlePositions[0], null),
|
|
788
|
+
reason: "single legacy core, no managed marker"
|
|
789
|
+
}
|
|
790
|
+
};
|
|
791
|
+
}
|
|
792
|
+
if (titlePositions.length > 1) {
|
|
793
|
+
return {
|
|
794
|
+
state: "needs-merge",
|
|
795
|
+
evidence: {
|
|
796
|
+
managedStart: 0,
|
|
797
|
+
titleCount: titlePositions.length,
|
|
798
|
+
unmarkedTitleCount: titlePositions.length,
|
|
799
|
+
unmarkedRange: computeUnmarkedRange(text, titlePositions[0], null),
|
|
800
|
+
reason: "legacy duplicate cores"
|
|
801
|
+
}
|
|
802
|
+
};
|
|
803
|
+
}
|
|
804
|
+
return {
|
|
805
|
+
state: "needs-merge",
|
|
806
|
+
evidence: {
|
|
807
|
+
managedStart: 0,
|
|
808
|
+
titleCount: 0,
|
|
809
|
+
reason: "no Kit core present"
|
|
810
|
+
}
|
|
811
|
+
};
|
|
812
|
+
}
|
|
813
|
+
|
|
814
|
+
// Locate Kit core titles that are real top-level headings (line-anchored).
|
|
815
|
+
// This intentionally excludes inline mentions like `# Agent Handoff Kit Core Runtime`
|
|
816
|
+
// inside backticks or prose, so the assess function only reacts to real duplicate headings.
|
|
817
|
+
function locateCoreTitlePositions(text) {
|
|
818
|
+
const regex = /(^|\n)# Agent Handoff Kit Core Runtime(?=\r?\n|$)/g;
|
|
819
|
+
const positions = [];
|
|
820
|
+
let match;
|
|
821
|
+
while ((match = regex.exec(text)) !== null) {
|
|
822
|
+
const headingStart = match.index + (match[1] === "\n" ? 1 : 0);
|
|
823
|
+
positions.push(headingStart);
|
|
824
|
+
}
|
|
825
|
+
return positions;
|
|
826
|
+
}
|
|
827
|
+
|
|
828
|
+
function computeUnmarkedRange(text, titleStart, managedRange) {
|
|
829
|
+
const titleNeedle = "# Agent Handoff Kit Core Runtime";
|
|
830
|
+
const terminal = "keep the core within budget.";
|
|
831
|
+
const terminalIndex = text.indexOf(terminal, titleStart);
|
|
832
|
+
if (terminalIndex >= 0 && (!managedRange || terminalIndex < managedRange.start || terminalIndex >= managedRange.end)) {
|
|
833
|
+
return { start: titleStart, end: terminalIndex + terminal.length };
|
|
834
|
+
}
|
|
835
|
+
const afterTitle = titleStart + titleNeedle.length;
|
|
836
|
+
const remainder = text.slice(afterTitle);
|
|
837
|
+
// Find next real top-level heading that is NOT another Kit core heading.
|
|
838
|
+
const nextTopLevel = remainder.search(/\n# (?!Agent Handoff Kit Core Runtime(?=\r?\n|$))/);
|
|
839
|
+
if (nextTopLevel < 0) return { start: titleStart, end: text.length };
|
|
840
|
+
return { start: titleStart, end: afterTitle + nextTopLevel + 1 };
|
|
841
|
+
}
|
|
842
|
+
|
|
607
843
|
function mergeManagedBlock(targetText, sourceText) {
|
|
608
844
|
const block = `${managedCoreStart}\n${sourceText.trim()}\n${managedCoreEnd}`;
|
|
845
|
+
|
|
846
|
+
// Strip every unmarked / legacy core range first; iterate to handle multiple legacy stacks.
|
|
847
|
+
let working = targetText;
|
|
848
|
+
for (let i = 0; i < 5; i += 1) {
|
|
849
|
+
const probe = assessAgentsMdHealth(working);
|
|
850
|
+
const range = probe.evidence?.unmarkedRange ?? probe.evidence?.legacyRange;
|
|
851
|
+
if (!range) break;
|
|
852
|
+
const before = working.slice(0, range.start).trimEnd();
|
|
853
|
+
const after = working.slice(range.end).trimStart();
|
|
854
|
+
working = before + (before && after ? "\n\n" : before ? "\n" : "") + after;
|
|
855
|
+
}
|
|
856
|
+
|
|
609
857
|
const existingBlock = new RegExp(`${escapeRegExp(managedCoreStart)}[\\s\\S]*?${escapeRegExp(managedCoreEnd)}`);
|
|
610
|
-
if (existingBlock.test(
|
|
611
|
-
|
|
858
|
+
if (existingBlock.test(working)) {
|
|
859
|
+
return `${working.replace(existingBlock, block).trimEnd()}\n`;
|
|
860
|
+
}
|
|
861
|
+
if (working.trim().length === 0) return `${block}\n`;
|
|
862
|
+
return `${working.trimEnd()}\n\n${block}\n`;
|
|
863
|
+
}
|
|
864
|
+
|
|
865
|
+
function countOccurrences(text, needle) {
|
|
866
|
+
return text.split(needle).length - 1;
|
|
612
867
|
}
|
|
613
868
|
|
|
614
869
|
function escapeRegExp(text) {
|
|
@@ -641,7 +896,7 @@ function printPlan(command, root, mode, plan, version) {
|
|
|
641
896
|
console.log(`selected root: ${root}`);
|
|
642
897
|
console.log(`mode: ${mode}`);
|
|
643
898
|
console.log("");
|
|
644
|
-
console.log("📋
|
|
899
|
+
console.log("📋 計劃預覽:以下未執行。create 新增缺少檔案;merge 在備份後合併;skip 保留既有檔案;conflict 代表工具停手等你確認。");
|
|
645
900
|
console.log("");
|
|
646
901
|
for (const action of ["create", "merge", "skip", "conflict"]) {
|
|
647
902
|
const items = plan.filter((item) => item.action === action);
|
|
@@ -651,6 +906,27 @@ function printPlan(command, root, mode, plan, version) {
|
|
|
651
906
|
console.log(`\nbackup: ${plan.filter((item) => item.action === "merge").length}`);
|
|
652
907
|
}
|
|
653
908
|
|
|
909
|
+
// R-026 CLI Output Contract: install/upgrade 完成必含四項(版本/模式/剛做咗乜/下一步)。
|
|
910
|
+
function printInstallSummary(version, command, mode, root, counts) {
|
|
911
|
+
console.log(`\n✅ created: ${counts.created}`);
|
|
912
|
+
console.log(`🔀 merged: ${counts.merged}`);
|
|
913
|
+
console.log(`⏭️ skipped existing: ${counts.skipped}`);
|
|
914
|
+
console.log(`${counts.conflicts > 0 ? "⚠️ " : "✅ "}conflict: ${counts.conflicts}`);
|
|
915
|
+
if (counts.backupRel) console.log(`💾 backup: ${counts.backupRel}`);
|
|
916
|
+
if (counts.reportRel) console.log(`📄 migration report: ${counts.reportRel}`);
|
|
917
|
+
console.log("");
|
|
918
|
+
console.log(`📦 版本:v${version}`);
|
|
919
|
+
console.log(`🛠️ 模式:${mode}`);
|
|
920
|
+
console.log(`🔎 剛做咗:${command} 命令;create ${counts.created} / merge ${counts.merged} / skip ${counts.skipped} / conflict ${counts.conflicts}。`);
|
|
921
|
+
if (counts.conflicts > 0) {
|
|
922
|
+
console.log("🚀 下一步:把 migration report 或這段輸出貼給 AI,請它判斷 conflict 點處理;工具已停手,沒有覆寫 conflict 檔案。");
|
|
923
|
+
} else if (command === "upgrade") {
|
|
924
|
+
console.log("🚀 下一步:留意下方 upgrade self-check(自動跑 doctor);若全綠即升級完成。");
|
|
925
|
+
} else {
|
|
926
|
+
console.log("🚀 下一步:開新 AI 對話,按下方提示貼入 Work in <root> 一句後描述任務。");
|
|
927
|
+
}
|
|
928
|
+
}
|
|
929
|
+
|
|
654
930
|
function printDryRunExplanation(plan) {
|
|
655
931
|
const conflicts = plan.filter((item) => item.action === "conflict");
|
|
656
932
|
console.log("✅ 這次沒有改動任何檔案。");
|
|
@@ -874,4 +1150,7 @@ After install:
|
|
|
874
1150
|
Open your AI tool, start a new chat, paste the shown Work in ... message,
|
|
875
1151
|
then describe your task in normal language.
|
|
876
1152
|
`);
|
|
1153
|
+
console.log(`📦 版本:v${version}`);
|
|
1154
|
+
console.log(`🛠️ 模式:help ready`);
|
|
1155
|
+
console.log(`🚀 下一步:第一次使用先跑 init;既有專案升級用 upgrade --dry-run;要檢查現狀用 doctor。`);
|
|
877
1156
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@adamchanadam/agent-handoff-kit",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.7",
|
|
4
4
|
"description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -19,10 +19,11 @@
|
|
|
19
19
|
"qa:prototype": "node scripts/check-public-prototype.mjs",
|
|
20
20
|
"qa:packs": "node scripts/check-pack-scenarios.mjs",
|
|
21
21
|
"qa:upgrade": "node scripts/check-upgrade-safety.mjs",
|
|
22
|
-
"qa:release": "node scripts/check-release-readiness.mjs"
|
|
22
|
+
"qa:release": "node scripts/check-release-readiness.mjs",
|
|
23
|
+
"qa:fixtures": "node scripts/generate-upgrade-fixtures.mjs"
|
|
23
24
|
},
|
|
24
25
|
"engines": {
|
|
25
26
|
"node": ">=18"
|
|
26
27
|
},
|
|
27
28
|
"license": "MIT"
|
|
28
|
-
}
|
|
29
|
+
}
|
|
@@ -48,6 +48,16 @@ External skill flows, subagents, task plans, or another tool's "finish" step do
|
|
|
48
48
|
|
|
49
49
|
For high-risk work, pause after PLAN. High-risk means destructive operations, ambiguous target, external systems, release/publish, or broad multi-file change.
|
|
50
50
|
|
|
51
|
+
## 2.1 Upgrade Done Contract
|
|
52
|
+
|
|
53
|
+
`agent-handoff-kit upgrade` is considered complete only when all of the following hold. The CLI enforces this contract; do not declare upgrade success without it.
|
|
54
|
+
|
|
55
|
+
1. `AGENTS.md` health state is `clean`: exactly one `# Agent Handoff Kit Core Runtime` heading, exactly one paired managed-core marker block, and no unmarked stale core ranges. Sandwich states (managed marker plus an unmarked stale core) are not clean; the installer must replace the stale ranges, not skip.
|
|
56
|
+
2. The CLI runs `doctor` automatically against the upgraded root after writes complete. `doctor` must report `status: passed` across required files, anchors, schema checks, and prompt mirror checks.
|
|
57
|
+
3. The migration report records every action taken, with backup paths for merged files.
|
|
58
|
+
|
|
59
|
+
If any check fails, the upgrade did not finish; resolve the failure (or hand the failure output to the user) before reporting completion. This contract is the single source of truth for upgrade success; downstream QA scripts and release-grade QA derive their assertions from it.
|
|
60
|
+
|
|
51
61
|
## 3. Safety Boundaries
|
|
52
62
|
|
|
53
63
|
Do not delete, reset, overwrite, bulk-move, or publish without explicit user approval.
|
|
@@ -112,4 +122,4 @@ If a pack, skill, subagent plan, demo workspace, or external workflow produces i
|
|
|
112
122
|
|
|
113
123
|
## Core Complexity Rule
|
|
114
124
|
|
|
115
|
-
New default-core rules are allowed only when they apply to most sessions, protect safety or continuity, cannot live in a pack or registry, and keep the core within budget.
|
|
125
|
+
New default-core rules are allowed only when they apply to most sessions, protect safety or continuity, cannot live in a pack or registry, and keep the core within budget.
|
|
@@ -6,7 +6,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
|
|
|
6
6
|
|
|
7
7
|
| Field | Value | Last verified |
|
|
8
8
|
|---|---|---|
|
|
9
|
-
| Agent Handoff Kit template version | 0.1.
|
|
9
|
+
| Agent Handoff Kit template version | 0.1.7 | package prototype |
|
|
10
10
|
| Runtime | TBD | TBD |
|
|
11
11
|
| Framework | TBD | TBD |
|
|
12
12
|
| Package manager | TBD | TBD |
|