@adamchanadam/agent-handoff-kit 0.3.3 → 0.3.5
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 +237 -127
- package/docs/whatsnew/v0.3.4.md +17 -0
- package/docs/whatsnew/v0.3.5.md +20 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
狀態:目前版本為 `v0.3.5`。這是早期可用版本,仍在持續完善中。
|
|
4
4
|
|
|
5
5
|

|
|
6
6
|
|
|
@@ -239,7 +239,7 @@ Agent Handoff Kit 同 [Adam-AI-Instructions](https://github.com/prompt-templates
|
|
|
239
239
|
|
|
240
240
|
## 目前限制
|
|
241
241
|
|
|
242
|
-
- `v0.3.
|
|
242
|
+
- 目前版本為 `v0.3.5`。
|
|
243
243
|
- 這是早期可用版本,仍在持續完善中。
|
|
244
244
|
- 升級合併屬窄範圍策略,不是完整的複雜合併工具。
|
|
245
245
|
- `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
|
|
@@ -434,6 +434,25 @@ function parseArgs(args) {
|
|
|
434
434
|
return { command, options };
|
|
435
435
|
}
|
|
436
436
|
|
|
437
|
+
// R-031.3 v0.3.4+: Helper to detect if PROJECT_INDEX template version metadata
|
|
438
|
+
// row is stale relative to current CLI version. Used by plan-time no-op detection
|
|
439
|
+
// guard to ensure metadata-only stale roots still trigger the upgrade ceremony
|
|
440
|
+
// (otherwise plan-time short-circuit returns before inject can run).
|
|
441
|
+
async function needsProjectIndexVersionInject(root, command, version) {
|
|
442
|
+
if (command !== "upgrade") return false;
|
|
443
|
+
try {
|
|
444
|
+
const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
|
|
445
|
+
const text = await readFile(indexPath, "utf8");
|
|
446
|
+
const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
|
|
447
|
+
if (m && isStableSemver(m[1]) && compareSemver(m[1], version) < 0) {
|
|
448
|
+
return true;
|
|
449
|
+
}
|
|
450
|
+
} catch {
|
|
451
|
+
// ignore — silent if PROJECT_INDEX missing or unreadable
|
|
452
|
+
}
|
|
453
|
+
return false;
|
|
454
|
+
}
|
|
455
|
+
|
|
437
456
|
async function runInstall(command, root, options, version) {
|
|
438
457
|
const mode = await detectMode(root);
|
|
439
458
|
const plan = await buildPlan(root, command);
|
|
@@ -446,10 +465,17 @@ async function runInstall(command, root, options, version) {
|
|
|
446
465
|
const planMergeCount = plan.filter((item) => item.action === "merge").length;
|
|
447
466
|
const planConflictCount = plan.filter((item) => item.action === "conflict").length;
|
|
448
467
|
const planSkipCount = plan.filter((item) => item.action === "skip").length;
|
|
468
|
+
// R-031.3 v0.3.4+: metadata-only stale guard. If PROJECT_INDEX template version
|
|
469
|
+
// row is stale but structure is fully current (all v0.2.0+ files already present),
|
|
470
|
+
// plan create/merge/conflict are all 0 — but inject still needs to run. Without
|
|
471
|
+
// this guard, plan-time short-circuit returns before inject can fire, leaving
|
|
472
|
+
// root on stale version forever.
|
|
473
|
+
const projectIndexVersionNeedsInject = await needsProjectIndexVersionInject(root, command, version);
|
|
449
474
|
const isUpgradeNoopAtPlanTime = command === "upgrade"
|
|
450
475
|
&& planCreateCount === 0
|
|
451
476
|
&& planMergeCount === 0
|
|
452
|
-
&& planConflictCount === 0
|
|
477
|
+
&& planConflictCount === 0
|
|
478
|
+
&& !projectIndexVersionNeedsInject;
|
|
453
479
|
|
|
454
480
|
if (isUpgradeNoopAtPlanTime) {
|
|
455
481
|
printCard(version, "continuity ready", "o.o");
|
|
@@ -484,7 +510,7 @@ async function runInstall(command, root, options, version) {
|
|
|
484
510
|
}
|
|
485
511
|
}
|
|
486
512
|
|
|
487
|
-
printPlan(command, root, mode, plan, version);
|
|
513
|
+
printPlan(command, root, mode, plan, version, options.dryRun);
|
|
488
514
|
|
|
489
515
|
if (options.dryRun) {
|
|
490
516
|
console.log("\ndry-run: no files written");
|
|
@@ -515,14 +541,24 @@ async function runInstall(command, root, options, version) {
|
|
|
515
541
|
created.push(item.targetRel);
|
|
516
542
|
}
|
|
517
543
|
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
544
|
+
for (const item of plan) {
|
|
545
|
+
if (item.action !== "merge") continue;
|
|
546
|
+
const backupPath = path.join(backupDir, item.targetRel);
|
|
547
|
+
await mkdir(path.dirname(backupPath), { recursive: true });
|
|
548
|
+
await copyFile(item.targetAbs, backupPath);
|
|
549
|
+
await writeFile(item.targetAbs, item.mergedText, "utf8");
|
|
550
|
+
merged.push(item.targetRel);
|
|
551
|
+
}
|
|
552
|
+
|
|
553
|
+
// R-031.3 v0.3.4+: Inject current CLI version into PROJECT_INDEX template version
|
|
554
|
+
// metadata row — placed AFTER the merge loop to avoid the ordering bug where merge
|
|
555
|
+
// overwrites inject. Merge writes item.mergedText computed at plan-build phase
|
|
556
|
+
// (which contains the pre-inject stale version row); if inject ran before merge,
|
|
557
|
+
// merge would silently revert it. R-016 still protected: only the metadata row
|
|
558
|
+
// mutates, user content rows (External Sources / Fact Base etc.) preserved.
|
|
559
|
+
// The captured metadataUpdated object is passed to writeMigrationReport so the
|
|
560
|
+
// audit trail records this mutation alongside file create/merge operations.
|
|
561
|
+
let metadataUpdated = null;
|
|
526
562
|
if (command === "upgrade" || created.includes("dev/PROJECT_INDEX.md")) {
|
|
527
563
|
const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
|
|
528
564
|
try {
|
|
@@ -534,37 +570,39 @@ async function runInstall(command, root, options, version) {
|
|
|
534
570
|
`| Agent Handoff Kit template version | ${version} |`
|
|
535
571
|
);
|
|
536
572
|
await writeFile(indexPath, updated, "utf8");
|
|
573
|
+
metadataUpdated = {
|
|
574
|
+
file: "dev/PROJECT_INDEX.md",
|
|
575
|
+
field: "Agent Handoff Kit template version",
|
|
576
|
+
from: m[1],
|
|
577
|
+
to: version
|
|
578
|
+
};
|
|
537
579
|
}
|
|
538
580
|
} catch {
|
|
539
581
|
// ignore — doctor anchor (R-016) only checks row existence, not specific value.
|
|
540
582
|
}
|
|
541
583
|
}
|
|
542
584
|
|
|
543
|
-
for (const item of plan) {
|
|
544
|
-
if (item.action !== "merge") continue;
|
|
545
|
-
const backupPath = path.join(backupDir, item.targetRel);
|
|
546
|
-
await mkdir(path.dirname(backupPath), { recursive: true });
|
|
547
|
-
await copyFile(item.targetAbs, backupPath);
|
|
548
|
-
await writeFile(item.targetAbs, item.mergedText, "utf8");
|
|
549
|
-
merged.push(item.targetRel);
|
|
550
|
-
}
|
|
551
|
-
|
|
552
585
|
const skippedCount = plan.filter((item) => item.action === "skip").length;
|
|
553
586
|
|
|
554
587
|
// R-031 v0.3.1+: scenario branching. Upgrade no-op (零改動) short-circuits — skip
|
|
555
588
|
// migration report, self-check doctor, install banner, onboarding canonical phrase.
|
|
556
589
|
// Prevents misleading "安裝完成" framing when user is just verifying they are latest.
|
|
590
|
+
// R-031.3 v0.3.4+: also short-circuit only when metadata is current. If only the
|
|
591
|
+
// metadata row was stale (counts 0/0/0 but metadataUpdated truthy), user just
|
|
592
|
+
// received a substantive upgrade — proceed through full ceremony so doctor
|
|
593
|
+
// self-check confirms the inject result.
|
|
557
594
|
const isUpgradeNoop = command === "upgrade"
|
|
558
595
|
&& created.length === 0
|
|
559
596
|
&& merged.length === 0
|
|
560
|
-
&& conflicts.length === 0
|
|
597
|
+
&& conflicts.length === 0
|
|
598
|
+
&& !metadataUpdated;
|
|
561
599
|
|
|
562
600
|
if (isUpgradeNoop) {
|
|
563
601
|
printUpgradeNoopShortCircuit(version);
|
|
564
602
|
return;
|
|
565
603
|
}
|
|
566
604
|
|
|
567
|
-
const report = await writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir);
|
|
605
|
+
const report = await writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir, metadataUpdated);
|
|
568
606
|
printInstallSummary(version, command, mode, root, {
|
|
569
607
|
created: created.length,
|
|
570
608
|
merged: merged.length,
|
|
@@ -589,16 +627,19 @@ async function runInstall(command, root, options, version) {
|
|
|
589
627
|
if (command === "upgrade" && conflicts.length === 0) {
|
|
590
628
|
console.log("");
|
|
591
629
|
console.log("------------------------------------------------------------");
|
|
592
|
-
console.log("🩺 upgrade self-check: running doctor against the upgraded root");
|
|
630
|
+
console.log("🩺 upgrade self-check: running doctor against the upgraded root");
|
|
593
631
|
console.log("------------------------------------------------------------");
|
|
594
632
|
const doctorStatus = await runDoctor(root, version, { silentCard: true });
|
|
595
|
-
if (doctorStatus !== "passed") {
|
|
596
|
-
console.log("");
|
|
597
|
-
console.log("⚠️ upgrade self-check did not pass; see doctor output above.");
|
|
598
|
-
console.log("📋 下一步:把上面 doctor 輸出貼給 AI,請它先按提示修補後再宣稱 upgrade 完成。");
|
|
599
|
-
process.exitCode = 1;
|
|
600
|
-
}
|
|
601
|
-
|
|
633
|
+
if (doctorStatus !== "passed") {
|
|
634
|
+
console.log("");
|
|
635
|
+
console.log("⚠️ upgrade self-check did not pass; see doctor output above.");
|
|
636
|
+
console.log("📋 下一步:把上面 doctor 輸出貼給 AI,請它先按提示修補後再宣稱 upgrade 完成。");
|
|
637
|
+
process.exitCode = 1;
|
|
638
|
+
} else {
|
|
639
|
+
console.log("");
|
|
640
|
+
console.log("✅ 升級驗收完成:doctor 已通過;可以繼續使用這個項目。");
|
|
641
|
+
}
|
|
642
|
+
}
|
|
602
643
|
|
|
603
644
|
if (conflicts.length > 0) process.exitCode = 1;
|
|
604
645
|
}
|
|
@@ -709,9 +750,10 @@ async function runDoctor(root, version, options = {}) {
|
|
|
709
750
|
// suspect drift / curious about version / continuity awareness),唔等用戶 ask AI。
|
|
710
751
|
console.log("");
|
|
711
752
|
console.log("項目狀態速覽:");
|
|
712
|
-
const versionAlignment = await assessVersionAlignment(root, version);
|
|
713
|
-
printVersionAlignment(versionAlignment);
|
|
714
|
-
const
|
|
753
|
+
const versionAlignment = await assessVersionAlignment(root, version);
|
|
754
|
+
printVersionAlignment(versionAlignment);
|
|
755
|
+
const versionNextStep = getVersionAlignmentNextStep(versionAlignment);
|
|
756
|
+
const lastCloseout = await assessLastCloseout(root);
|
|
715
757
|
printLastCloseout(lastCloseout);
|
|
716
758
|
const projectAge = await assessProjectAge(root);
|
|
717
759
|
printProjectAge(projectAge);
|
|
@@ -722,11 +764,11 @@ async function runDoctor(root, version, options = {}) {
|
|
|
722
764
|
failedKind: !credentialResult.ok ? "credential leak" : null,
|
|
723
765
|
failedCount: !credentialResult.ok ? credentialResult.findings.length : 0,
|
|
724
766
|
nextStep: !credentialResult.ok
|
|
725
|
-
? "立即從相關檔案 redact credential value + rotate 已泄露 token;credential 應該由 AI 工具自身 secure storage 管理,永不寫入 dev/* 任何檔。"
|
|
726
|
-
: disciplineResult.ok
|
|
727
|
-
? "繼續日常使用即可。如有新版本發佈,啟動本工具時會自動顯示升級通知。"
|
|
728
|
-
: "繼續使用;下次 closeout 時 AI 應自動執行 SESSION_LOG N 規則推進(見上面 warn 行)。如未動請要求 AI 重做 closeout。"
|
|
729
|
-
});
|
|
767
|
+
? "立即從相關檔案 redact credential value + rotate 已泄露 token;credential 應該由 AI 工具自身 secure storage 管理,永不寫入 dev/* 任何檔。"
|
|
768
|
+
: disciplineResult.ok
|
|
769
|
+
? versionNextStep ?? "繼續日常使用即可。如有新版本發佈,啟動本工具時會自動顯示升級通知。"
|
|
770
|
+
: "繼續使用;下次 closeout 時 AI 應自動執行 SESSION_LOG N 規則推進(見上面 warn 行)。如未動請要求 AI 重做 closeout。"
|
|
771
|
+
});
|
|
730
772
|
return overallHealthy ? "passed" : "failed";
|
|
731
773
|
}
|
|
732
774
|
|
|
@@ -775,8 +817,8 @@ async function checkInstalledIntegrationsCredentialLeak(root) {
|
|
|
775
817
|
return { ok: findings.length === 0, findings };
|
|
776
818
|
}
|
|
777
819
|
|
|
778
|
-
// R-026 CLI Output Contract: doctor
|
|
779
|
-
function printDoctorSummary(version, root, mode, details) {
|
|
820
|
+
// R-026 CLI Output Contract: doctor 完成必含四項(版本/模式/剛完成/下一步)。
|
|
821
|
+
function printDoctorSummary(version, root, mode, details) {
|
|
780
822
|
console.log("");
|
|
781
823
|
if (mode === "healthy") {
|
|
782
824
|
console.log("status: passed");
|
|
@@ -785,12 +827,12 @@ function printDoctorSummary(version, root, mode, details) {
|
|
|
785
827
|
console.log(`status: failed (${details.failedCount} ${details.failedKind} failed)`);
|
|
786
828
|
console.log(`⚠️ 檢查未通過:${details.failedKind === "missing files" ? "有必要檔案不存在。" : details.failedKind === "anchor checks" ? "有檔案存在,但內容缺少必要段落。" : details.failedKind === "schema checks" ? "交接或索引文件結構不完整。" : "下次開工提示副本與 handoff 真源不同。"}`);
|
|
787
829
|
}
|
|
788
|
-
console.log("");
|
|
789
|
-
console.log(`📦 版本:v${version}`);
|
|
790
|
-
console.log(`🩺 模式:${mode}`);
|
|
791
|
-
console.log(`🔎
|
|
792
|
-
console.log(`🚀 下一步:${details.nextStep}`);
|
|
793
|
-
}
|
|
830
|
+
console.log("");
|
|
831
|
+
console.log(`📦 版本:v${version}`);
|
|
832
|
+
console.log(`🩺 模式:${mode}`);
|
|
833
|
+
console.log(`🔎 剛完成:檢查 ${details.checked} 項;${mode === "healthy" ? "全部通過" : `${details.failedCount} 項未通過(${details.failedKind})`}。`);
|
|
834
|
+
console.log(`🚀 下一步:${details.nextStep}`);
|
|
835
|
+
}
|
|
794
836
|
|
|
795
837
|
async function checkPromptMirror(root) {
|
|
796
838
|
const handoffPath = path.join(root, "dev/SESSION_HANDOFF.md");
|
|
@@ -936,7 +978,7 @@ async function buildPlan(root, command) {
|
|
|
936
978
|
return plan;
|
|
937
979
|
}
|
|
938
980
|
|
|
939
|
-
function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAbs, sourceText, targetText) {
|
|
981
|
+
function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAbs, sourceText, targetText) {
|
|
940
982
|
const base = { sourceRel, targetRel, sourceAbs, targetAbs };
|
|
941
983
|
if (targetText === sourceText) return { ...base, action: "skip", reason: "already current" };
|
|
942
984
|
if (command !== "upgrade") return { ...base, action: "skip", reason: "init preserves existing files" };
|
|
@@ -980,30 +1022,34 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
|
|
|
980
1022
|
mergedText: mergeManagedBlock(targetText, sourceText)
|
|
981
1023
|
};
|
|
982
1024
|
}
|
|
983
|
-
// R-029
|
|
984
|
-
//
|
|
985
|
-
//
|
|
986
|
-
|
|
987
|
-
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
return {
|
|
992
|
-
...base,
|
|
993
|
-
action: "merge",
|
|
994
|
-
reason: "
|
|
995
|
-
mergedText:
|
|
996
|
-
};
|
|
997
|
-
}
|
|
998
|
-
// R-030 v0.3.0+: dev/RULE_PACKS.md must also include integrations pack routing row.
|
|
999
|
-
if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("
|
|
1000
|
-
|
|
1001
|
-
|
|
1002
|
-
action: "merge"
|
|
1003
|
-
|
|
1004
|
-
|
|
1005
|
-
|
|
1006
|
-
|
|
1025
|
+
// R-029/R-030: RULE_PACKS.md is a routing table, but upgrade still preserves
|
|
1026
|
+
// user-added rows. Missing maintainer rows are merged into the existing table
|
|
1027
|
+
// instead of replacing the whole file.
|
|
1028
|
+
if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("First-time user signals")) {
|
|
1029
|
+
const mergedRulePacks = mergeRulePacksRows(targetText, sourceText);
|
|
1030
|
+
if (!mergedRulePacks) {
|
|
1031
|
+
return { ...base, action: "conflict", reason: "RULE_PACKS.md routing table header was changed; manual merge required to preserve custom rows" };
|
|
1032
|
+
}
|
|
1033
|
+
return {
|
|
1034
|
+
...base,
|
|
1035
|
+
action: "merge",
|
|
1036
|
+
reason: "merge missing v0.2.0+ routing rows while preserving existing custom rows (新手引導 signal routing)",
|
|
1037
|
+
mergedText: mergedRulePacks
|
|
1038
|
+
};
|
|
1039
|
+
}
|
|
1040
|
+
// R-030 v0.3.0+: dev/RULE_PACKS.md must also include integrations pack routing row.
|
|
1041
|
+
if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("External tool integrations")) {
|
|
1042
|
+
const mergedRulePacks = mergeRulePacksRows(targetText, sourceText);
|
|
1043
|
+
if (!mergedRulePacks) {
|
|
1044
|
+
return { ...base, action: "conflict", reason: "RULE_PACKS.md routing table header was changed; manual merge required to preserve custom rows" };
|
|
1045
|
+
}
|
|
1046
|
+
return {
|
|
1047
|
+
...base,
|
|
1048
|
+
action: "merge",
|
|
1049
|
+
reason: "merge missing v0.3.0+ routing rows while preserving existing custom rows (Integration governance routing)",
|
|
1050
|
+
mergedText: mergedRulePacks
|
|
1051
|
+
};
|
|
1052
|
+
}
|
|
1007
1053
|
// R-030 v0.3.0+: dev/PROJECT_INDEX.md gets ## Installed Integrations section auto-inserted before
|
|
1008
1054
|
// ## Local QC Commands on upgrade if missing. NON-DESTRUCTIVE: existing ## External Sources content
|
|
1009
1055
|
// is fully preserved (including any user-filled rows). User can later manually add the `via` column
|
|
@@ -1041,10 +1087,46 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
|
|
|
1041
1087
|
if ((targetRel === "CLAUDE.md" || targetRel === "GEMINI.md") && !targetText.includes("AGENTS.md")) {
|
|
1042
1088
|
return { ...base, action: "conflict", reason: "existing bridge does not route to AGENTS.md" };
|
|
1043
1089
|
}
|
|
1044
|
-
return { ...base, action: "skip", reason: "preserve existing file" };
|
|
1045
|
-
}
|
|
1046
|
-
|
|
1047
|
-
|
|
1090
|
+
return { ...base, action: "skip", reason: "preserve existing file" };
|
|
1091
|
+
}
|
|
1092
|
+
|
|
1093
|
+
function mergeRulePacksRows(targetText, sourceText) {
|
|
1094
|
+
const requiredPacks = [
|
|
1095
|
+
"dev/rules/onboarding.md",
|
|
1096
|
+
"dev/rules/integrations.md"
|
|
1097
|
+
];
|
|
1098
|
+
const sourceRows = sourceText
|
|
1099
|
+
.split(/\r?\n/)
|
|
1100
|
+
.filter((line) => line.startsWith("|") && requiredPacks.some((pack) => line.includes(pack)));
|
|
1101
|
+
if (sourceRows.length === 0) return targetText;
|
|
1102
|
+
|
|
1103
|
+
const lines = targetText.split(/\r?\n/);
|
|
1104
|
+
const tableStart = lines.findIndex((line) => line.trim() === "| Task signal | Pack | Purpose |");
|
|
1105
|
+
if (tableStart < 0) return null;
|
|
1106
|
+
|
|
1107
|
+
let tableEnd = tableStart;
|
|
1108
|
+
while (tableEnd < lines.length && lines[tableEnd].startsWith("|")) tableEnd++;
|
|
1109
|
+
|
|
1110
|
+
const before = lines.slice(0, tableStart);
|
|
1111
|
+
const table = lines.slice(tableStart, tableEnd);
|
|
1112
|
+
const after = lines.slice(tableEnd);
|
|
1113
|
+
const sourceRowsToApply = sourceRows.filter((row) => {
|
|
1114
|
+
if (row.includes("dev/rules/onboarding.md")) return !targetText.includes("First-time user signals");
|
|
1115
|
+
if (row.includes("dev/rules/integrations.md")) return !targetText.includes("External tool integrations");
|
|
1116
|
+
return false;
|
|
1117
|
+
});
|
|
1118
|
+
if (sourceRowsToApply.length === 0) return targetText;
|
|
1119
|
+
|
|
1120
|
+
const merged = [
|
|
1121
|
+
...before,
|
|
1122
|
+
...table,
|
|
1123
|
+
...sourceRowsToApply,
|
|
1124
|
+
...after
|
|
1125
|
+
];
|
|
1126
|
+
return merged.join("\n");
|
|
1127
|
+
}
|
|
1128
|
+
|
|
1129
|
+
// R-031.2 v0.3.2+: Version alignment assessment for doctor "項目狀態速覽".
|
|
1048
1130
|
// Compares CLI version (running), root template metadata version (in dev/PROJECT_INDEX.md),
|
|
1049
1131
|
// and npm latest. Surfaces drift awareness because previous design relied on startup
|
|
1050
1132
|
// maybePrintUpdateNotice which silently fails when npx auto-fetches latest (CLI version
|
|
@@ -1070,29 +1152,45 @@ async function assessVersionAlignment(root, cliVersion) {
|
|
|
1070
1152
|
return { cliVersion, rootVersion, npmLatest };
|
|
1071
1153
|
}
|
|
1072
1154
|
|
|
1073
|
-
function printVersionAlignment(result) {
|
|
1074
|
-
const { cliVersion, rootVersion, npmLatest } = result;
|
|
1075
|
-
if (rootVersion === null) {
|
|
1076
|
-
console.log(` 📦
|
|
1077
|
-
return;
|
|
1078
|
-
}
|
|
1079
|
-
if (npmLatest === null) {
|
|
1080
|
-
console.log(` 📦
|
|
1081
|
-
return;
|
|
1082
|
-
}
|
|
1083
|
-
const aligned = cliVersion === rootVersion && rootVersion === npmLatest;
|
|
1084
|
-
if (aligned) {
|
|
1085
|
-
console.log(` 📦
|
|
1086
|
-
return;
|
|
1087
|
-
}
|
|
1088
|
-
console.log(` 📦
|
|
1089
|
-
if (npmLatest && compareSemver(npmLatest, cliVersion) > 0) {
|
|
1090
|
-
console.log(` npm 有新版(v${npmLatest}
|
|
1091
|
-
|
|
1092
|
-
|
|
1093
|
-
|
|
1094
|
-
|
|
1095
|
-
|
|
1155
|
+
function printVersionAlignment(result) {
|
|
1156
|
+
const { cliVersion, rootVersion, npmLatest } = result;
|
|
1157
|
+
if (rootVersion === null) {
|
|
1158
|
+
console.log(` 📦 版本:工具 v${cliVersion} / 項目版本記錄缺失(可能曾經手動編輯)/ npm latest ${npmLatest ? "v" + npmLatest : "無法查詢"}`);
|
|
1159
|
+
return;
|
|
1160
|
+
}
|
|
1161
|
+
if (npmLatest === null) {
|
|
1162
|
+
console.log(` 📦 版本:工具 v${cliVersion} / 項目記錄 v${rootVersion} / npm latest 無法查詢(網絡可能不通)`);
|
|
1163
|
+
return;
|
|
1164
|
+
}
|
|
1165
|
+
const aligned = cliVersion === rootVersion && rootVersion === npmLatest;
|
|
1166
|
+
if (aligned) {
|
|
1167
|
+
console.log(` 📦 版本:工具 / 項目記錄 / npm latest 三向對齊 v${cliVersion} ✅`);
|
|
1168
|
+
return;
|
|
1169
|
+
}
|
|
1170
|
+
console.log(` 📦 版本:工具 v${cliVersion} / 項目記錄 v${rootVersion} / npm latest v${npmLatest}`);
|
|
1171
|
+
if (npmLatest && compareSemver(npmLatest, cliVersion) > 0) {
|
|
1172
|
+
console.log(` npm 有新版(v${npmLatest});doctor 只檢查不修改。要升級時先執行:npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run`);
|
|
1173
|
+
console.log(" --dry-run 只預覽、不寫入;確認計劃沒問題後,再去掉 --dry-run 正式升級。");
|
|
1174
|
+
} else if (cliVersion !== rootVersion) {
|
|
1175
|
+
console.log(" 項目內記錄的 Kit 版本與目前工具版本不同;doctor 只檢查不修改。要對齊時先執行:npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run");
|
|
1176
|
+
console.log(" --dry-run 只預覽、不寫入;確認計劃沒問題後,再去掉 --dry-run 正式升級。");
|
|
1177
|
+
}
|
|
1178
|
+
}
|
|
1179
|
+
|
|
1180
|
+
function getVersionAlignmentNextStep(result) {
|
|
1181
|
+
const { cliVersion, rootVersion, npmLatest } = result;
|
|
1182
|
+
if (npmLatest && compareSemver(npmLatest, cliVersion) > 0) {
|
|
1183
|
+
return `檢查已通過,但 npm 有新版 v${npmLatest}。doctor 沒有修改檔案;建議先執行 npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run。--dry-run 只預覽、不寫入;確認計劃沒問題後,再去掉 --dry-run 正式升級。`;
|
|
1184
|
+
}
|
|
1185
|
+
if (rootVersion === null) {
|
|
1186
|
+
return "檢查已通過,但項目版本記錄缺失。doctor 沒有修改檔案;建議先執行 npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run。--dry-run 只預覽、不寫入;確認只會補齊工具維護的版本記錄後,再去掉 --dry-run 正式升級。";
|
|
1187
|
+
}
|
|
1188
|
+
if (cliVersion !== rootVersion) {
|
|
1189
|
+
return "檢查已通過,但項目版本記錄未與目前工具對齊。doctor 沒有修改檔案;建議先執行 npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run。--dry-run 只預覽、不寫入;確認後再去掉 --dry-run 正式升級。";
|
|
1190
|
+
}
|
|
1191
|
+
return null;
|
|
1192
|
+
}
|
|
1193
|
+
|
|
1096
1194
|
// R-031.2 v0.3.2+: Last closeout assessment. Reads dev/SESSION_HANDOFF.md "Last Updated:"
|
|
1097
1195
|
// line (strict format, reliable). Falls back to dev/SESSION_LOG.md first H2 date if
|
|
1098
1196
|
// HANDOFF missing or unparseable.
|
|
@@ -1400,14 +1498,17 @@ async function detectMode(root) {
|
|
|
1400
1498
|
return "partial";
|
|
1401
1499
|
}
|
|
1402
1500
|
|
|
1403
|
-
function printPlan(command, root, mode, plan, version) {
|
|
1501
|
+
function printPlan(command, root, mode, plan, version, isDryRun = false) {
|
|
1404
1502
|
printCard(version, "continuity ready", "o.o");
|
|
1405
1503
|
console.log(`command: ${command}`);
|
|
1406
1504
|
console.log(`current directory: ${process.cwd()}`);
|
|
1407
1505
|
console.log(`selected root: ${root}`);
|
|
1408
1506
|
console.log(`mode: ${mode}`);
|
|
1409
1507
|
console.log("");
|
|
1410
|
-
|
|
1508
|
+
const planIntro = isDryRun
|
|
1509
|
+
? "📋 計劃預覽:以下未執行。create 新增缺少檔案;merge 在備份後合併;skip 保留既有檔案;conflict 代表工具停手等你確認。"
|
|
1510
|
+
: "📋 即將執行:以下是本次寫入計劃。create 新增缺少檔案;merge 會先備份再合併;skip 保留既有檔案;conflict 代表工具停手等你確認。";
|
|
1511
|
+
console.log(planIntro);
|
|
1411
1512
|
console.log("");
|
|
1412
1513
|
for (const action of ["create", "merge", "skip", "conflict"]) {
|
|
1413
1514
|
const items = plan.filter((item) => item.action === action);
|
|
@@ -1417,20 +1518,20 @@ function printPlan(command, root, mode, plan, version) {
|
|
|
1417
1518
|
console.log(`\nbackup: ${plan.filter((item) => item.action === "merge").length}`);
|
|
1418
1519
|
}
|
|
1419
1520
|
|
|
1420
|
-
// R-026 CLI Output Contract: install/upgrade
|
|
1421
|
-
function printInstallSummary(version, command, mode, root, counts) {
|
|
1521
|
+
// R-026 CLI Output Contract: install/upgrade 完成必含四項(版本/模式/剛完成/下一步)。
|
|
1522
|
+
function printInstallSummary(version, command, mode, root, counts) {
|
|
1422
1523
|
console.log(`\n✅ created: ${counts.created}`);
|
|
1423
1524
|
console.log(`🔀 merged: ${counts.merged}`);
|
|
1424
1525
|
console.log(`⏭️ skipped existing: ${counts.skipped}`);
|
|
1425
1526
|
console.log(`${counts.conflicts > 0 ? "⚠️ " : "✅ "}conflict: ${counts.conflicts}`);
|
|
1426
1527
|
if (counts.backupRel) console.log(`💾 backup: ${counts.backupRel}`);
|
|
1427
1528
|
if (counts.reportRel) console.log(`📄 migration report: ${counts.reportRel}`);
|
|
1428
|
-
console.log("");
|
|
1429
|
-
console.log(`📦 版本:v${version}`);
|
|
1430
|
-
console.log(`🛠️ 模式:${mode}`);
|
|
1431
|
-
console.log(`🔎
|
|
1529
|
+
console.log("");
|
|
1530
|
+
console.log(`📦 版本:v${version}`);
|
|
1531
|
+
console.log(`🛠️ 模式:${mode}`);
|
|
1532
|
+
console.log(`🔎 剛完成:${command} 命令;create ${counts.created} / merge ${counts.merged} / skip ${counts.skipped} / conflict ${counts.conflicts}。`);
|
|
1432
1533
|
if (counts.conflicts > 0) {
|
|
1433
|
-
console.log("🚀 下一步:把 migration report 或這段輸出貼給 AI
|
|
1534
|
+
console.log("🚀 下一步:把 migration report 或這段輸出貼給 AI,請它判斷衝突檔案怎樣處理;工具已停手,沒有覆寫 conflict 檔案。");
|
|
1434
1535
|
} else if (command === "upgrade") {
|
|
1435
1536
|
console.log("🚀 下一步:留意下方 upgrade self-check(自動跑 doctor);若全綠即升級完成。");
|
|
1436
1537
|
} else {
|
|
@@ -1460,7 +1561,7 @@ async function confirmWrite() {
|
|
|
1460
1561
|
}
|
|
1461
1562
|
}
|
|
1462
1563
|
|
|
1463
|
-
async function writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir) {
|
|
1564
|
+
async function writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir, metadataUpdated = null) {
|
|
1464
1565
|
const reportPath = path.join(migrationDir, "migration-report.md");
|
|
1465
1566
|
await mkdir(migrationDir, { recursive: true });
|
|
1466
1567
|
const skipped = plan.filter((item) => item.action === "skip").map((item) => item.targetRel);
|
|
@@ -1484,12 +1585,22 @@ async function writeMigrationReport(root, command, mode, plan, created, merged,
|
|
|
1484
1585
|
"## Conflicts",
|
|
1485
1586
|
...listOrNone(conflicts.map((item) => `${item.targetRel} - ${item.reason}`)),
|
|
1486
1587
|
"",
|
|
1588
|
+
// R-031.3 v0.3.4+: metadata updates are tracked separately from file create/merge
|
|
1589
|
+
// because they mutate specific rows inside an otherwise user-owned file rather
|
|
1590
|
+
// than replacing or merging the file as a whole. Audit trail completeness
|
|
1591
|
+
// requires this section even when create/merge/conflict counts are all 0.
|
|
1592
|
+
"## Metadata Updates",
|
|
1593
|
+
metadataUpdated
|
|
1594
|
+
? `- ${metadataUpdated.file}: ${metadataUpdated.field} ${metadataUpdated.from} → ${metadataUpdated.to}`
|
|
1595
|
+
: "- none",
|
|
1596
|
+
"",
|
|
1487
1597
|
"## Backup",
|
|
1488
1598
|
merged.length > 0 ? `- ${path.relative(root, backupDir)}` : "- none",
|
|
1489
1599
|
"",
|
|
1490
1600
|
"## Notes",
|
|
1491
1601
|
"- Existing files are preserved unless the installer can perform a bounded merge.",
|
|
1492
|
-
"- Files that cannot be safely merged are reported as conflicts and are not overwritten."
|
|
1602
|
+
"- Files that cannot be safely merged are reported as conflicts and are not overwritten.",
|
|
1603
|
+
"- Metadata Updates section tracks row-level mutations (R-031.3) distinct from file-level changes."
|
|
1493
1604
|
].join("\n");
|
|
1494
1605
|
await writeFile(reportPath, `${text}\n`, "utf8");
|
|
1495
1606
|
return reportPath;
|
|
@@ -1609,17 +1720,16 @@ function printInstallNextSteps(root, conflictCount) {
|
|
|
1609
1720
|
console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
|
|
1610
1721
|
console.log("");
|
|
1611
1722
|
}
|
|
1612
|
-
// R-031.2 v0.3.2+:
|
|
1613
|
-
//
|
|
1614
|
-
|
|
1615
|
-
console.log("
|
|
1616
|
-
console.log("");
|
|
1617
|
-
console.log("
|
|
1618
|
-
console.log("
|
|
1619
|
-
console.log("
|
|
1620
|
-
console.log("");
|
|
1621
|
-
console.log("
|
|
1622
|
-
console.log(" 冇 GUI、唔 run server、唔自動做嘢。你需要連住至少一個 AI tool 嘅對話,AI 先會讀依啲檔案做正事。");
|
|
1723
|
+
// R-031.2 v0.3.2+: first-install checklist. It answers the user's first
|
|
1724
|
+
// question: "is this installed and what do I do next?"
|
|
1725
|
+
console.log("📋 如何確認安裝完成:");
|
|
1726
|
+
console.log("");
|
|
1727
|
+
console.log(" 1. 在 Terminal 執行 npx @adamchanadam/agent-handoff-kit doctor,應該見到「status: passed」");
|
|
1728
|
+
console.log(" 2. 你的 dev/ 資料夾應該有規則、交接與工作紀錄等檔案");
|
|
1729
|
+
console.log(" 3. 在你使用的 AI 工具(Claude Code / Codex / Gemini)開新對話,貼下面起步句");
|
|
1730
|
+
console.log("");
|
|
1731
|
+
console.log("⚠️ 注意:Agent Handoff Kit 是放在項目資料夾內的一組交接檔案。");
|
|
1732
|
+
console.log(" 它沒有圖形介面,不會啟動伺服器,也不會自動替你做事;你需要在 AI 對話中使用它。");
|
|
1623
1733
|
console.log("");
|
|
1624
1734
|
console.log("------------------------------------------------------------");
|
|
1625
1735
|
console.log("⚠️ 請注意:下面文字不是 Terminal 指令。");
|
|
@@ -1631,7 +1741,7 @@ function printInstallNextSteps(root, conflictCount) {
|
|
|
1631
1741
|
console.log("🚀 AI 會主動引導你選擇情景(寫代碼 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),");
|
|
1632
1742
|
console.log(" 一步一步帶你做第一個任務(由新手引導包主動接管)。");
|
|
1633
1743
|
console.log("");
|
|
1634
|
-
console.log("💡
|
|
1744
|
+
console.log("💡 之後你熟悉流程後,可改用更直接的開工句:");
|
|
1635
1745
|
console.log(` Work in ${root}. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.`);
|
|
1636
1746
|
console.log("");
|
|
1637
1747
|
console.log("🩺 如要檢查安裝是否完整,可在 Terminal 執行:");
|
|
@@ -1645,7 +1755,7 @@ function printInstallNextSteps(root, conflictCount) {
|
|
|
1645
1755
|
async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRootVersion) {
|
|
1646
1756
|
console.log("");
|
|
1647
1757
|
console.log("============================================================");
|
|
1648
|
-
console.log("✅
|
|
1758
|
+
console.log("✅ 升級完成:Kit 檔案已更新到最新版本");
|
|
1649
1759
|
console.log("============================================================");
|
|
1650
1760
|
if (conflictCount > 0) {
|
|
1651
1761
|
console.log("⚠️ 狀態:有既有檔案需要人工確認,詳情見 migration report。");
|
|
@@ -1659,7 +1769,7 @@ async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRoo
|
|
|
1659
1769
|
// inject mutated PROJECT_INDEX), so the range narrative reflects actual user
|
|
1660
1770
|
// journey instead of degenerate v{current} → v{current}.
|
|
1661
1771
|
await printWhatsnew(root, version, preUpgradeRootVersion);
|
|
1662
|
-
console.log("📋
|
|
1772
|
+
console.log("📋 如你正在進行中的工作對話已熟悉 Agent Handoff Kit,繼續使用原本的開工方式即可,無需重新做新手引導。");
|
|
1663
1773
|
console.log("");
|
|
1664
1774
|
console.log("💡 如想了解本版本新加了甚麼功能,可選用以下開工句(非強制):");
|
|
1665
1775
|
console.log("------------------------------------------------------------");
|
|
@@ -1712,7 +1822,7 @@ async function printWhatsnew(root, toVersion, fromVersionOverride) {
|
|
|
1712
1822
|
|
|
1713
1823
|
if (relevant.length === 0) {
|
|
1714
1824
|
console.log(`💡 本版 release notes:https://github.com/Adamchanadam/agent-handoff-kit/releases`);
|
|
1715
|
-
console.log(` (v${fromVersion} → v${toVersion}
|
|
1825
|
+
console.log(` (v${fromVersion} → v${toVersion} 跨版本的完整變更見 GitHub Release 全列表)`);
|
|
1716
1826
|
console.log("");
|
|
1717
1827
|
return;
|
|
1718
1828
|
}
|
|
@@ -1728,12 +1838,12 @@ async function printWhatsnew(root, toVersion, fromVersionOverride) {
|
|
|
1728
1838
|
const [oldMajor, oldMinor] = oldestAvailable.split(".").map((n) => Number.parseInt(n, 10));
|
|
1729
1839
|
const isDeepRange = (fromMajor < oldMajor) || (fromMajor === oldMajor && fromMinor < oldMinor);
|
|
1730
1840
|
if (isDeepRange) {
|
|
1731
|
-
console.log(`💡 注意:本次升級 v${fromVersion} → v${toVersion}
|
|
1841
|
+
console.log(`💡 注意:本次升級 v${fromVersion} → v${toVersion} 跨度較大;本工具的版本說明只涵蓋由 v${oldestAvailable} 起的 ${relevant.length} 個版本。較舊版本(v${fromVersion} 至 v${oldestAvailable} 之前)的完整變更見:`);
|
|
1732
1842
|
console.log(` https://github.com/Adamchanadam/agent-handoff-kit/releases`);
|
|
1733
1843
|
console.log("");
|
|
1734
1844
|
}
|
|
1735
1845
|
|
|
1736
|
-
console.log(`📰 本次升級涵蓋 ${relevant.length}
|
|
1846
|
+
console.log(`📰 本次升級涵蓋 ${relevant.length} 個版本的版本說明(${isDeepRange ? `由 v${oldestAvailable} 起` : `v${fromVersion} → v${toVersion}`}):`);
|
|
1737
1847
|
console.log("");
|
|
1738
1848
|
|
|
1739
1849
|
const toShow = relevant.length <= 3 ? relevant : [relevant[0], relevant[relevant.length - 1]];
|
|
@@ -1747,7 +1857,7 @@ async function printWhatsnew(root, toVersion, fromVersionOverride) {
|
|
|
1747
1857
|
console.log(content.trimEnd());
|
|
1748
1858
|
console.log("");
|
|
1749
1859
|
if (i === 0 && elidedCount > 0) {
|
|
1750
|
-
console.log(` ⋯ 中間 ${elidedCount}
|
|
1860
|
+
console.log(` ⋯ 中間 ${elidedCount} 個版本的版本說明略;完整列表見 https://github.com/Adamchanadam/agent-handoff-kit/releases ⋯`);
|
|
1751
1861
|
console.log("");
|
|
1752
1862
|
}
|
|
1753
1863
|
} catch {
|
|
@@ -1768,7 +1878,7 @@ function printUpgradeNoopShortCircuit(version) {
|
|
|
1768
1878
|
console.log("");
|
|
1769
1879
|
console.log(`📦 版本:v${version}`);
|
|
1770
1880
|
console.log("🛠️ 模式:upgrade-existing");
|
|
1771
|
-
console.log("🔎
|
|
1881
|
+
console.log("🔎 剛完成:檢查所有 Kit 檔案的狀態(含 AGENTS.md、dev/SESSION_HANDOFF.md、dev/PROJECT_INDEX.md 等)。");
|
|
1772
1882
|
console.log("✅ 結果:你已經是最新版本,沒有檔案需要建立或合併;用戶填寫的內容全部保留現狀。");
|
|
1773
1883
|
console.log("");
|
|
1774
1884
|
console.log("🚀 下一步:繼續日常使用即可。如要檢查健康狀態,可執行:");
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# v0.3.4
|
|
2
|
+
|
|
3
|
+
## 本版新加咗咩
|
|
4
|
+
|
|
5
|
+
本版修補升級後版本敘事不一致的問題。既有專案執行 `upgrade` 後,`dev/PROJECT_INDEX.md` 內的「Agent Handoff Kit template version」資料列會在合併完成後再更新為目前 CLI 版本,避免先更新、後又被舊合併結果覆蓋。
|
|
6
|
+
|
|
7
|
+
升級工具也會辨認「只有版本資料列過期」的情況。即使沒有新增檔案、沒有合併檔案、沒有衝突,只要這一列仍是舊版本,就不會誤報「已經是最新版本,沒有檔案需要建立或合併」。
|
|
8
|
+
|
|
9
|
+
## 對你已有檔案嘅影響
|
|
10
|
+
|
|
11
|
+
本版只會更新 `dev/PROJECT_INDEX.md` 的 template version metadata。這一列屬工具維護的模板資料,不是你填寫的項目內容。你在 External Sources、Fact Base、Workspace Identity 等表格中填過的內容仍會保留。
|
|
12
|
+
|
|
13
|
+
升級紀錄也新增 metadata section,會寫明這次是否更新了版本資料列,方便日後追溯。
|
|
14
|
+
|
|
15
|
+
## 建議下一步
|
|
16
|
+
|
|
17
|
+
執行 `upgrade` 後再執行 `doctor`。若 `doctor` 顯示 `status: passed`,並且項目狀態速覽不再提示 root 落後 CLI,即代表這次熱修已生效。
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# v0.3.5
|
|
2
|
+
|
|
3
|
+
## 本版新加了甚麼
|
|
4
|
+
|
|
5
|
+
- `upgrade` 補齊 `dev/RULE_PACKS.md` 時會保留用戶自訂 rows,不再用整份模板覆寫。
|
|
6
|
+
- 如 `dev/RULE_PACKS.md` 的 routing table 表頭已被改動,工具會回報衝突並停手,不會猜測合併。
|
|
7
|
+
- `doctor` 明確說明自己只檢查、不修改;版本不齊時會先建議 `upgrade --dry-run`。
|
|
8
|
+
- `init` / `upgrade` / `doctor` 的提示文字更清楚,方便非技術新手分清 Terminal 檢查與 AI 對話下一步。
|
|
9
|
+
|
|
10
|
+
## 對你已有檔案的影響
|
|
11
|
+
|
|
12
|
+
- 既有用戶內容應保留。
|
|
13
|
+
- `dev/RULE_PACKS.md` 只會補 Kit 需要的 routing rows;你自己新增的任務路由 rows 應保留。
|
|
14
|
+
- 如果你手動改過 routing table 表頭,升級可能會停在衝突狀態,等你或 AI 判斷怎樣合併。
|
|
15
|
+
|
|
16
|
+
## 建議下一步
|
|
17
|
+
|
|
18
|
+
- 已安裝舊版的專案,先執行 `npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run`。
|
|
19
|
+
- 預演結果沒有衝突後,再執行 `npx @adamchanadam/agent-handoff-kit@latest upgrade`。
|
|
20
|
+
- 升級後執行 `npx @adamchanadam/agent-handoff-kit@latest doctor`,確認狀態通過。
|