@adamchanadam/agent-handoff-kit 0.3.4 → 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 CHANGED
@@ -1,6 +1,6 @@
1
1
  # Agent Handoff Kit
2
2
 
3
- 狀態:`v0.3.4` 已正式發佈到 GitHub 與 npm。這是早期可用版本,仍在持續完善中。
3
+ 狀態:目前版本為 `v0.3.5`。這是早期可用版本,仍在持續完善中。
4
4
 
5
5
  ![Agent Handoff Kit 主視覺](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-main-visual2.png)
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.0` 是 GitHub 與 npm 同步發佈版本。
242
+ - 目前版本為 `v0.3.5`。
243
243
  - 這是早期可用版本,仍在持續完善中。
244
244
  - 升級合併屬窄範圍策略,不是完整的複雜合併工具。
245
245
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
@@ -510,7 +510,7 @@ async function runInstall(command, root, options, version) {
510
510
  }
511
511
  }
512
512
 
513
- printPlan(command, root, mode, plan, version);
513
+ printPlan(command, root, mode, plan, version, options.dryRun);
514
514
 
515
515
  if (options.dryRun) {
516
516
  console.log("\ndry-run: no files written");
@@ -627,16 +627,19 @@ async function runInstall(command, root, options, version) {
627
627
  if (command === "upgrade" && conflicts.length === 0) {
628
628
  console.log("");
629
629
  console.log("------------------------------------------------------------");
630
- console.log("🩺 upgrade self-check: running doctor against the upgraded root");
630
+ console.log("🩺 upgrade self-check: running doctor against the upgraded root");
631
631
  console.log("------------------------------------------------------------");
632
632
  const doctorStatus = await runDoctor(root, version, { silentCard: true });
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
- }
639
- }
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
+ }
640
643
 
641
644
  if (conflicts.length > 0) process.exitCode = 1;
642
645
  }
@@ -747,9 +750,10 @@ async function runDoctor(root, version, options = {}) {
747
750
  // suspect drift / curious about version / continuity awareness),唔等用戶 ask AI。
748
751
  console.log("");
749
752
  console.log("項目狀態速覽:");
750
- const versionAlignment = await assessVersionAlignment(root, version);
751
- printVersionAlignment(versionAlignment);
752
- const lastCloseout = await assessLastCloseout(root);
753
+ const versionAlignment = await assessVersionAlignment(root, version);
754
+ printVersionAlignment(versionAlignment);
755
+ const versionNextStep = getVersionAlignmentNextStep(versionAlignment);
756
+ const lastCloseout = await assessLastCloseout(root);
753
757
  printLastCloseout(lastCloseout);
754
758
  const projectAge = await assessProjectAge(root);
755
759
  printProjectAge(projectAge);
@@ -760,11 +764,11 @@ async function runDoctor(root, version, options = {}) {
760
764
  failedKind: !credentialResult.ok ? "credential leak" : null,
761
765
  failedCount: !credentialResult.ok ? credentialResult.findings.length : 0,
762
766
  nextStep: !credentialResult.ok
763
- ? "立即從相關檔案 redact credential value + rotate 已泄露 token;credential 應該由 AI 工具自身 secure storage 管理,永不寫入 dev/* 任何檔。"
764
- : disciplineResult.ok
765
- ? "繼續日常使用即可。如有新版本發佈,啟動本工具時會自動顯示升級通知。"
766
- : "繼續使用;下次 closeout 時 AI 應自動執行 SESSION_LOG N 規則推進(見上面 warn 行)。如未動請要求 AI 重做 closeout。"
767
- });
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
+ });
768
772
  return overallHealthy ? "passed" : "failed";
769
773
  }
770
774
 
@@ -813,8 +817,8 @@ async function checkInstalledIntegrationsCredentialLeak(root) {
813
817
  return { ok: findings.length === 0, findings };
814
818
  }
815
819
 
816
- // R-026 CLI Output Contract: doctor 完成必含四項(版本/模式/剛做咗乜/下一步)。
817
- function printDoctorSummary(version, root, mode, details) {
820
+ // R-026 CLI Output Contract: doctor 完成必含四項(版本/模式/剛完成/下一步)。
821
+ function printDoctorSummary(version, root, mode, details) {
818
822
  console.log("");
819
823
  if (mode === "healthy") {
820
824
  console.log("status: passed");
@@ -823,12 +827,12 @@ function printDoctorSummary(version, root, mode, details) {
823
827
  console.log(`status: failed (${details.failedCount} ${details.failedKind} failed)`);
824
828
  console.log(`⚠️ 檢查未通過:${details.failedKind === "missing files" ? "有必要檔案不存在。" : details.failedKind === "anchor checks" ? "有檔案存在,但內容缺少必要段落。" : details.failedKind === "schema checks" ? "交接或索引文件結構不完整。" : "下次開工提示副本與 handoff 真源不同。"}`);
825
829
  }
826
- console.log("");
827
- console.log(`📦 版本:v${version}`);
828
- console.log(`🩺 模式:${mode}`);
829
- console.log(`🔎 剛做咗:檢查 ${details.checked} 項;${mode === "healthy" ? "全部通過" : `${details.failedCount} 項未通過(${details.failedKind})`}。`);
830
- console.log(`🚀 下一步:${details.nextStep}`);
831
- }
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
+ }
832
836
 
833
837
  async function checkPromptMirror(root) {
834
838
  const handoffPath = path.join(root, "dev/SESSION_HANDOFF.md");
@@ -974,7 +978,7 @@ async function buildPlan(root, command) {
974
978
  return plan;
975
979
  }
976
980
 
977
- function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAbs, sourceText, targetText) {
981
+ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAbs, sourceText, targetText) {
978
982
  const base = { sourceRel, targetRel, sourceAbs, targetAbs };
979
983
  if (targetText === sourceText) return { ...base, action: "skip", reason: "already current" };
980
984
  if (command !== "upgrade") return { ...base, action: "skip", reason: "init preserves existing files" };
@@ -1018,30 +1022,34 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1018
1022
  mergedText: mergeManagedBlock(targetText, sourceText)
1019
1023
  };
1020
1024
  }
1021
- // R-029 v0.2.0+: RULE_PACKS.md is a routing table, not a user customization target.
1022
- // Stale v0.1.X versions miss the "First-time user signals" onboarding routing row.
1023
- // Force-refresh during upgrade so R-029 onboarding routing propagates to existing users.
1024
- // Any user-added custom routing rows will be lost on upgrade — this is by design;
1025
- // RULE_PACKS.md is treated as a maintainer-owned routing table, similar to the
1026
- // AGENTS.md managed-core block. User customizations belong in pack rule files
1027
- // (packs/*.md), not in the routing table.
1028
- if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("First-time user signals")) {
1029
- return {
1030
- ...base,
1031
- action: "merge",
1032
- reason: "refresh stale routing table to include v0.2.0+ rows (新手引導 signal routing)",
1033
- mergedText: sourceText
1034
- };
1035
- }
1036
- // R-030 v0.3.0+: dev/RULE_PACKS.md must also include integrations pack routing row.
1037
- if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("dev/rules/integrations.md")) {
1038
- return {
1039
- ...base,
1040
- action: "merge",
1041
- reason: "refresh stale routing table to include v0.3.0+ rows (Integration governance routing)",
1042
- mergedText: sourceText
1043
- };
1044
- }
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
+ }
1045
1053
  // R-030 v0.3.0+: dev/PROJECT_INDEX.md gets ## Installed Integrations section auto-inserted before
1046
1054
  // ## Local QC Commands on upgrade if missing. NON-DESTRUCTIVE: existing ## External Sources content
1047
1055
  // is fully preserved (including any user-filled rows). User can later manually add the `via` column
@@ -1079,10 +1087,46 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1079
1087
  if ((targetRel === "CLAUDE.md" || targetRel === "GEMINI.md") && !targetText.includes("AGENTS.md")) {
1080
1088
  return { ...base, action: "conflict", reason: "existing bridge does not route to AGENTS.md" };
1081
1089
  }
1082
- return { ...base, action: "skip", reason: "preserve existing file" };
1083
- }
1084
-
1085
- // R-031.2 v0.3.2+: Version alignment assessment for doctor "項目狀態速覽".
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 "項目狀態速覽".
1086
1130
  // Compares CLI version (running), root template metadata version (in dev/PROJECT_INDEX.md),
1087
1131
  // and npm latest. Surfaces drift awareness because previous design relied on startup
1088
1132
  // maybePrintUpdateNotice which silently fails when npx auto-fetches latest (CLI version
@@ -1108,29 +1152,45 @@ async function assessVersionAlignment(root, cliVersion) {
1108
1152
  return { cliVersion, rootVersion, npmLatest };
1109
1153
  }
1110
1154
 
1111
- function printVersionAlignment(result) {
1112
- const { cliVersion, rootVersion, npmLatest } = result;
1113
- if (rootVersion === null) {
1114
- console.log(` 📦 版本:CLI v${cliVersion} / root metadata 缺失(曾經手動編輯?)/ npm latest ${npmLatest ? "v" + npmLatest : "無法查詢"}`);
1115
- return;
1116
- }
1117
- if (npmLatest === null) {
1118
- console.log(` 📦 版本:CLI v${cliVersion} / root v${rootVersion} / npm latest 無法查詢(網絡可能不通)`);
1119
- return;
1120
- }
1121
- const aligned = cliVersion === rootVersion && rootVersion === npmLatest;
1122
- if (aligned) {
1123
- console.log(` 📦 版本:CLI / root / npm latest 三向對齊 v${cliVersion} ✅`);
1124
- return;
1125
- }
1126
- console.log(` 📦 版本:CLI v${cliVersion} / root v${rootVersion} / npm latest v${npmLatest}`);
1127
- if (npmLatest && compareSemver(npmLatest, cliVersion) > 0) {
1128
- console.log(` npm 有新版(v${npmLatest});可執行:npx @adamchanadam/agent-handoff-kit@latest upgrade`);
1129
- } else if (cliVersion !== rootVersion) {
1130
- console.log(` 你 root template metadata 同 CLI 唔對齊;兩個版本仍相容 doctor 仍 PASS;如想對齊:npx @adamchanadam/agent-handoff-kit@latest upgrade`);
1131
- }
1132
- }
1133
-
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
+
1134
1194
  // R-031.2 v0.3.2+: Last closeout assessment. Reads dev/SESSION_HANDOFF.md "Last Updated:"
1135
1195
  // line (strict format, reliable). Falls back to dev/SESSION_LOG.md first H2 date if
1136
1196
  // HANDOFF missing or unparseable.
@@ -1438,14 +1498,17 @@ async function detectMode(root) {
1438
1498
  return "partial";
1439
1499
  }
1440
1500
 
1441
- function printPlan(command, root, mode, plan, version) {
1501
+ function printPlan(command, root, mode, plan, version, isDryRun = false) {
1442
1502
  printCard(version, "continuity ready", "o.o");
1443
1503
  console.log(`command: ${command}`);
1444
1504
  console.log(`current directory: ${process.cwd()}`);
1445
1505
  console.log(`selected root: ${root}`);
1446
1506
  console.log(`mode: ${mode}`);
1447
1507
  console.log("");
1448
- console.log("📋 計劃預覽:以下未執行。create 新增缺少檔案;merge 在備份後合併;skip 保留既有檔案;conflict 代表工具停手等你確認。");
1508
+ const planIntro = isDryRun
1509
+ ? "📋 計劃預覽:以下未執行。create 新增缺少檔案;merge 在備份後合併;skip 保留既有檔案;conflict 代表工具停手等你確認。"
1510
+ : "📋 即將執行:以下是本次寫入計劃。create 新增缺少檔案;merge 會先備份再合併;skip 保留既有檔案;conflict 代表工具停手等你確認。";
1511
+ console.log(planIntro);
1449
1512
  console.log("");
1450
1513
  for (const action of ["create", "merge", "skip", "conflict"]) {
1451
1514
  const items = plan.filter((item) => item.action === action);
@@ -1455,20 +1518,20 @@ function printPlan(command, root, mode, plan, version) {
1455
1518
  console.log(`\nbackup: ${plan.filter((item) => item.action === "merge").length}`);
1456
1519
  }
1457
1520
 
1458
- // R-026 CLI Output Contract: install/upgrade 完成必含四項(版本/模式/剛做咗乜/下一步)。
1459
- function printInstallSummary(version, command, mode, root, counts) {
1521
+ // R-026 CLI Output Contract: install/upgrade 完成必含四項(版本/模式/剛完成/下一步)。
1522
+ function printInstallSummary(version, command, mode, root, counts) {
1460
1523
  console.log(`\n✅ created: ${counts.created}`);
1461
1524
  console.log(`🔀 merged: ${counts.merged}`);
1462
1525
  console.log(`⏭️ skipped existing: ${counts.skipped}`);
1463
1526
  console.log(`${counts.conflicts > 0 ? "⚠️ " : "✅ "}conflict: ${counts.conflicts}`);
1464
1527
  if (counts.backupRel) console.log(`💾 backup: ${counts.backupRel}`);
1465
1528
  if (counts.reportRel) console.log(`📄 migration report: ${counts.reportRel}`);
1466
- console.log("");
1467
- console.log(`📦 版本:v${version}`);
1468
- console.log(`🛠️ 模式:${mode}`);
1469
- console.log(`🔎 剛做咗:${command} 命令;create ${counts.created} / merge ${counts.merged} / skip ${counts.skipped} / conflict ${counts.conflicts}。`);
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}。`);
1470
1533
  if (counts.conflicts > 0) {
1471
- console.log("🚀 下一步:把 migration report 或這段輸出貼給 AI,請它判斷 conflict 點處理;工具已停手,沒有覆寫 conflict 檔案。");
1534
+ console.log("🚀 下一步:把 migration report 或這段輸出貼給 AI,請它判斷衝突檔案怎樣處理;工具已停手,沒有覆寫 conflict 檔案。");
1472
1535
  } else if (command === "upgrade") {
1473
1536
  console.log("🚀 下一步:留意下方 upgrade self-check(自動跑 doctor);若全綠即升級完成。");
1474
1537
  } else {
@@ -1657,17 +1720,16 @@ function printInstallNextSteps(root, conflictCount) {
1657
1720
  console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
1658
1721
  console.log("");
1659
1722
  }
1660
- // R-031.2 v0.3.2+: 「點 confirm 你裝啱咗」mini-checklist,直接答用戶第一次安裝後嘅
1661
- // anxiety「我裝啱咗嗎」。三個具體 verify step + 一句講清本工具係 background harness
1662
- // (冇 GUI、冇 server、需要連住 AI tool 先見到實際 value)。
1663
- console.log("📋 點 confirm 你裝啱咗:");
1664
- console.log("");
1665
- console.log(" 1. 跑 npx @adamchanadam/agent-handoff-kit doctor 應該見到「status: passed」");
1666
- console.log(" 2. 你 dev/ folder 應該有起碼 14 個檔(rules / SESSION_HANDOFF / SESSION_LOG 等)");
1667
- console.log(" 3. 喺你 AI tool(Claude Code / Codex / Gemini)開新對話,貼下面起步句先見到實際 value");
1668
- console.log("");
1669
- console.log("⚠️ 注意:Agent Handoff Kit 只係 background harness —— 喺你 project folder 入面嘅幾類檔案。");
1670
- 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 對話中使用它。");
1671
1733
  console.log("");
1672
1734
  console.log("------------------------------------------------------------");
1673
1735
  console.log("⚠️ 請注意:下面文字不是 Terminal 指令。");
@@ -1679,7 +1741,7 @@ function printInstallNextSteps(root, conflictCount) {
1679
1741
  console.log("🚀 AI 會主動引導你選擇情景(寫代碼 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),");
1680
1742
  console.log(" 一步一步帶你做第一個任務(由新手引導包主動接管)。");
1681
1743
  console.log("");
1682
- console.log("💡 之後 session(你已熟悉 v2 之後)可改用更直接 prompt:");
1744
+ console.log("💡 之後你熟悉流程後,可改用更直接的開工句:");
1683
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.`);
1684
1746
  console.log("");
1685
1747
  console.log("🩺 如要檢查安裝是否完整,可在 Terminal 執行:");
@@ -1693,7 +1755,7 @@ function printInstallNextSteps(root, conflictCount) {
1693
1755
  async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRootVersion) {
1694
1756
  console.log("");
1695
1757
  console.log("============================================================");
1696
- console.log("✅ 升級完成:管治架構檔案已更新到最新版本");
1758
+ console.log("✅ 升級完成:Kit 檔案已更新到最新版本");
1697
1759
  console.log("============================================================");
1698
1760
  if (conflictCount > 0) {
1699
1761
  console.log("⚠️ 狀態:有既有檔案需要人工確認,詳情見 migration report。");
@@ -1707,7 +1769,7 @@ async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRoo
1707
1769
  // inject mutated PROJECT_INDEX), so the range narrative reflects actual user
1708
1770
  // journey instead of degenerate v{current} → v{current}.
1709
1771
  await printWhatsnew(root, version, preUpgradeRootVersion);
1710
- console.log("📋 如你正在進行中的工作 session 已熟悉 Agent Handoff Kit,繼續使用原本的開工方式即可,無需重新做新手引導。");
1772
+ console.log("📋 如你正在進行中的工作對話已熟悉 Agent Handoff Kit,繼續使用原本的開工方式即可,無需重新做新手引導。");
1711
1773
  console.log("");
1712
1774
  console.log("💡 如想了解本版本新加了甚麼功能,可選用以下開工句(非強制):");
1713
1775
  console.log("------------------------------------------------------------");
@@ -1760,7 +1822,7 @@ async function printWhatsnew(root, toVersion, fromVersionOverride) {
1760
1822
 
1761
1823
  if (relevant.length === 0) {
1762
1824
  console.log(`💡 本版 release notes:https://github.com/Adamchanadam/agent-handoff-kit/releases`);
1763
- console.log(` (v${fromVersion} → v${toVersion} 跨版本嘅完整變更見 GitHub Release 全列表)`);
1825
+ console.log(` (v${fromVersion} → v${toVersion} 跨版本的完整變更見 GitHub Release 全列表)`);
1764
1826
  console.log("");
1765
1827
  return;
1766
1828
  }
@@ -1776,12 +1838,12 @@ async function printWhatsnew(root, toVersion, fromVersionOverride) {
1776
1838
  const [oldMajor, oldMinor] = oldestAvailable.split(".").map((n) => Number.parseInt(n, 10));
1777
1839
  const isDeepRange = (fromMajor < oldMajor) || (fromMajor === oldMajor && fromMinor < oldMinor);
1778
1840
  if (isDeepRange) {
1779
- console.log(`💡 注意:本次升級 v${fromVersion} → v${toVersion} 跨度較大;本工具 release notes 庫只 cover 由 v${oldestAvailable} 起嘅 ${relevant.length} 個版本。較舊版本(v${fromVersion} 至 v${oldestAvailable} 之前)嘅完整變更見:`);
1841
+ console.log(`💡 注意:本次升級 v${fromVersion} → v${toVersion} 跨度較大;本工具的版本說明只涵蓋由 v${oldestAvailable} 起的 ${relevant.length} 個版本。較舊版本(v${fromVersion} 至 v${oldestAvailable} 之前)的完整變更見:`);
1780
1842
  console.log(` https://github.com/Adamchanadam/agent-handoff-kit/releases`);
1781
1843
  console.log("");
1782
1844
  }
1783
1845
 
1784
- console.log(`📰 本次升級涵蓋 ${relevant.length} 個版本嘅 release notes(${isDeepRange ? `由 v${oldestAvailable} 起` : `v${fromVersion} → v${toVersion}`}):`);
1846
+ console.log(`📰 本次升級涵蓋 ${relevant.length} 個版本的版本說明(${isDeepRange ? `由 v${oldestAvailable} 起` : `v${fromVersion} → v${toVersion}`}):`);
1785
1847
  console.log("");
1786
1848
 
1787
1849
  const toShow = relevant.length <= 3 ? relevant : [relevant[0], relevant[relevant.length - 1]];
@@ -1795,7 +1857,7 @@ async function printWhatsnew(root, toVersion, fromVersionOverride) {
1795
1857
  console.log(content.trimEnd());
1796
1858
  console.log("");
1797
1859
  if (i === 0 && elidedCount > 0) {
1798
- console.log(` ⋯ 中間 ${elidedCount} 個版本嘅 release notes 略;完整列表見 https://github.com/Adamchanadam/agent-handoff-kit/releases ⋯`);
1860
+ console.log(` ⋯ 中間 ${elidedCount} 個版本的版本說明略;完整列表見 https://github.com/Adamchanadam/agent-handoff-kit/releases ⋯`);
1799
1861
  console.log("");
1800
1862
  }
1801
1863
  } catch {
@@ -1816,7 +1878,7 @@ function printUpgradeNoopShortCircuit(version) {
1816
1878
  console.log("");
1817
1879
  console.log(`📦 版本:v${version}`);
1818
1880
  console.log("🛠️ 模式:upgrade-existing");
1819
- console.log("🔎 剛做咗:檢查所有管治架構檔案的狀態(含 AGENTS.md、dev/SESSION_HANDOFF.md、dev/PROJECT_INDEX.md 等)。");
1881
+ console.log("🔎 剛完成:檢查所有 Kit 檔案的狀態(含 AGENTS.md、dev/SESSION_HANDOFF.md、dev/PROJECT_INDEX.md 等)。");
1820
1882
  console.log("✅ 結果:你已經是最新版本,沒有檔案需要建立或合併;用戶填寫的內容全部保留現狀。");
1821
1883
  console.log("");
1822
1884
  console.log("🚀 下一步:繼續日常使用即可。如要檢查健康狀態,可執行:");
@@ -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`,確認狀態通過。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.4",
3
+ "version": "0.3.5",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {