@adamchanadam/agent-handoff-kit 0.3.9 → 0.3.11

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.
@@ -193,7 +193,7 @@ const requiredAnchors = [
193
193
  "明確 onboarding signal keywords",
194
194
  "5-step walk-through pattern",
195
195
  "Application Scenario Library",
196
- "Scenario A. 寫 / 改代碼項目",
196
+ "Scenario A. 建構系統 / 工具 / 平台 / 網站或應用",
197
197
  "Scenario B. 整理研究資料",
198
198
  "Scenario C. 整理電腦檔案",
199
199
  "Scenario D. 學寫代碼",
@@ -525,13 +525,13 @@ async function runInstall(command, root, options, version) {
525
525
  }
526
526
 
527
527
  printPlan(command, root, mode, plan, version, options.dryRun);
528
-
529
- if (options.dryRun) {
530
- console.log("\ndry-run: no files written");
531
- printDryRunExplanation(plan);
532
- if (plan.some((item) => item.action === "conflict")) process.exitCode = 1;
533
- return;
534
- }
528
+
529
+ if (options.dryRun) {
530
+ console.log("\ndry-run: no files written");
531
+ printDryRunExplanation(command, mode, plan);
532
+ if (plan.some((item) => item.action === "conflict")) process.exitCode = 1;
533
+ return;
534
+ }
535
535
 
536
536
  if (!options.yes) {
537
537
  const ok = await confirmWrite();
@@ -548,12 +548,14 @@ async function runInstall(command, root, options, version) {
548
548
  const migrationDir = path.join(root, "dev/governance_migrations", stamp);
549
549
  const backupDir = path.join(migrationDir, "backup");
550
550
 
551
- for (const item of plan) {
552
- if (item.action !== "create") continue;
553
- await mkdir(path.dirname(item.targetAbs), { recursive: true });
554
- await copyFile(item.sourceAbs, item.targetAbs);
555
- created.push(item.targetRel);
556
- }
551
+ for (const item of plan) {
552
+ if (item.action !== "create") continue;
553
+ await mkdir(path.dirname(item.targetAbs), { recursive: true });
554
+ await copyFile(item.sourceAbs, item.targetAbs);
555
+ created.push(item.targetRel);
556
+ }
557
+
558
+ await hydrateInitialOpeningPrompt(root, created);
557
559
 
558
560
  for (const item of plan) {
559
561
  if (item.action !== "merge") continue;
@@ -630,23 +632,23 @@ async function runInstall(command, root, options, version) {
630
632
  // R-031.2 v0.3.2+: printUpgradeNextSteps async (awaits inline whatsnew print).
631
633
  // R-031.3 v0.3.3+: pass preUpgradeRootVersion so whatsnew narrative reflects the
632
634
  // actual user journey (v{pre-upgrade} → v{current}), not the post-inject state.
633
- if (command === "upgrade") {
634
- await printUpgradeNextSteps(root, conflicts.length, version, preUpgradeRootVersion);
635
- } else {
636
- printInstallNextSteps(root, conflicts.length);
637
- }
635
+ if (command === "upgrade") {
636
+ await printUpgradeNextSteps(root, conflicts.length, version, preUpgradeRootVersion);
637
+ } else {
638
+ printInstallNextSteps(root, conflicts.length, mode, skippedCount);
639
+ }
638
640
 
639
641
  // R-024 upgrade.done self-check: after substantive upgrade writes, run doctor automatically.
640
642
  // The user must see whether the merged state actually reaches a clean health state.
641
643
  if (command === "upgrade" && conflicts.length === 0) {
642
644
  console.log("");
643
645
  console.log("------------------------------------------------------------");
644
- console.log("🩺 upgrade self-check: running doctor against the upgraded root");
646
+ console.log("🩺 升級後自動檢查:正在檢查升級後的資料夾");
645
647
  console.log("------------------------------------------------------------");
646
- const doctorStatus = await runDoctor(root, version, { silentCard: true });
648
+ const doctorStatus = await runDoctor(root, version, { silentCard: true, context: "upgrade-self-check" });
647
649
  if (doctorStatus !== "passed") {
648
650
  console.log("");
649
- console.log("⚠️ upgrade self-check did not pass; see doctor output above.");
651
+ console.log("⚠️ 升級後自動檢查未通過;請看上方檢查輸出。");
650
652
  console.log("📋 下一步:把上面 doctor 輸出貼給 AI,請它先按提示修補後再宣稱 upgrade 完成。");
651
653
  process.exitCode = 1;
652
654
  } else {
@@ -672,15 +674,17 @@ async function runDoctor(root, version, options = {}) {
672
674
  console.log(`${row.ok ? "ok" : "missing"} ${row.target}`);
673
675
  }
674
676
 
675
- if (missing.length > 0) {
676
- printDoctorSummary(version, root, "needs-fix", {
677
- checked: rows.length,
678
- failedKind: "missing files",
679
- failedCount: missing.length,
680
- nextStep: "先確認你是否在正確專案資料夾;如是,執行 init 或 upgrade 補回缺少檔案。"
681
- });
682
- process.exitCode = 1;
683
- return "failed";
677
+ if (missing.length > 0) {
678
+ printDoctorSummary(version, root, "needs-fix", {
679
+ checked: rows.length,
680
+ failedKind: "missing files",
681
+ failedCount: missing.length,
682
+ nextStep: missing.length === rows.length
683
+ ? "這個資料夾未安裝 Kit。若這就是你的項目資料夾,請執行:npx --yes @adamchanadam/agent-handoff-kit@latest init"
684
+ : "這個資料夾只裝了一部分 Kit 檔案。請先確認路徑;如路徑正確,執行:npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run"
685
+ });
686
+ process.exitCode = 1;
687
+ return "failed";
684
688
  }
685
689
 
686
690
  const anchorRows = await checkRequiredAnchors(root);
@@ -691,12 +695,12 @@ async function runDoctor(root, version, options = {}) {
691
695
  }
692
696
 
693
697
  if (anchorFailures.length > 0) {
694
- printDoctorSummary(version, root, "needs-fix", {
695
- checked: rows.length + anchorRows.length,
696
- failedKind: "anchor checks",
697
- failedCount: anchorFailures.length,
698
- nextStep: "執行 upgrade --dry-run 查看可否安全補齊;不要手動覆寫既有檔案。"
699
- });
698
+ printDoctorSummary(version, root, "needs-fix", {
699
+ checked: rows.length + anchorRows.length,
700
+ failedKind: "anchor checks",
701
+ failedCount: anchorFailures.length,
702
+ nextStep: "有入口檔存在,但缺少 Kit 需要的橋接段落。請執行:npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run;不要手動覆寫既有檔案。"
703
+ });
700
704
  process.exitCode = 1;
701
705
  return "failed";
702
706
  }
@@ -768,9 +772,10 @@ async function runDoctor(root, version, options = {}) {
768
772
  printVersionAlignment(versionAlignment);
769
773
  const versionNextStep = getVersionAlignmentNextStep(versionAlignment);
770
774
  const lastCloseout = await assessLastCloseout(root);
771
- printLastCloseout(lastCloseout);
772
- const projectAge = await assessProjectAge(root);
773
- printProjectAge(projectAge);
775
+ printLastCloseout(lastCloseout);
776
+ const projectAge = await assessProjectAge(root);
777
+ printProjectAge(projectAge);
778
+ const onboardingNextStep = options.context === "upgrade-self-check" ? null : getFirstUseNextStep(root, lastCloseout);
774
779
 
775
780
  const overallHealthy = credentialResult.ok;
776
781
  printDoctorSummary(version, root, overallHealthy ? "healthy" : "needs-attention", {
@@ -780,11 +785,16 @@ async function runDoctor(root, version, options = {}) {
780
785
  nextStep: !credentialResult.ok
781
786
  ? "立即從相關檔案 redact credential value + rotate 已泄露 token;credential 應該由 AI 工具自身 secure storage 管理,永不寫入 dev/* 任何檔。"
782
787
  : disciplineResult.ok
783
- ? versionNextStep ?? "繼續日常使用即可。如有新版本發佈,啟動本工具時會自動顯示升級通知。"
788
+ ? versionNextStep ?? onboardingNextStep ?? "檢查已通過。繼續使用你原本的 AI 開工方式;如剛完成一個任務,記得在 AI 對話輸入「收工」保存交接。"
784
789
  : "繼續使用;下次 closeout 時 AI 應自動執行 SESSION_LOG N 規則推進(見上面 warn 行)。如未動請要求 AI 重做 closeout。"
785
790
  });
786
- return overallHealthy ? "passed" : "failed";
787
- }
791
+ return overallHealthy ? "passed" : "failed";
792
+ }
793
+
794
+ function getFirstUseNextStep(root, lastCloseout) {
795
+ if (lastCloseout.date) return null;
796
+ return `檢查已通過。下一步不要再留在終端機;打開 Claude Code / Claude Cowork / OpenAI Codex / Google Antigravity,或任何能讀寫此資料夾的 AI 工具,貼上:Work in ${root}. I just installed agent-handoff-kit. Help me get started.`;
797
+ }
788
798
 
789
799
  // R-030 v0.3.0+: Credential leak prevention sweep. Scans dev/PROJECT_INDEX.md,
790
800
  // dev/SESSION_HANDOFF.md, dev/SESSION_LOG.md for common credential prefix patterns.
@@ -847,6 +857,20 @@ function printDoctorSummary(version, root, mode, details) {
847
857
  console.log(`🔎 剛完成:檢查 ${details.checked} 項;${mode === "healthy" ? "全部通過" : `${details.failedCount} 項未通過(${details.failedKind})`}。`);
848
858
  console.log(`🚀 下一步:${details.nextStep}`);
849
859
  }
860
+
861
+ async function hydrateInitialOpeningPrompt(root, created) {
862
+ if (!created.includes("dev/SESSION_HANDOFF.md") && !created.includes("START_NEXT_SESSION_PROMPT.txt")) return;
863
+ for (const rel of ["dev/SESSION_HANDOFF.md", "START_NEXT_SESSION_PROMPT.txt"]) {
864
+ const filePath = path.join(root, rel);
865
+ try {
866
+ const text = await readFile(filePath, "utf8");
867
+ if (!text.includes("<absolute project root>")) continue;
868
+ await writeFile(filePath, text.replaceAll("<absolute project root>", root), "utf8");
869
+ } catch {
870
+ // Leave template untouched; doctor will surface prompt mirror problems if any.
871
+ }
872
+ }
873
+ }
850
874
 
851
875
  async function checkPromptMirror(root) {
852
876
  const handoffPath = path.join(root, "dev/SESSION_HANDOFF.md");
@@ -1172,6 +1196,17 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1172
1196
  };
1173
1197
  }
1174
1198
  }
1199
+ if (targetRel === "dev/rules/onboarding.md" && command === "upgrade" && !targetText.includes("Scenario A. 建構系統 / 工具 / 平台 / 網站或應用")) {
1200
+ const mergedOnboarding = mergeOnboardingScenarioALabel(targetText);
1201
+ if (mergedOnboarding !== targetText) {
1202
+ return {
1203
+ ...base,
1204
+ action: "merge",
1205
+ reason: "update onboarding Scenario A wording from narrow coding label to broader system/tool/platform/app label",
1206
+ mergedText: mergedOnboarding
1207
+ };
1208
+ }
1209
+ }
1175
1210
  // v0.3.6+: SESSION_HANDOFF.md gains a non-destructive lifecycle consistency
1176
1211
  // field. Existing handoff content stays intact; only the missing field and
1177
1212
  // rule note are inserted around stable ack markers.
@@ -1187,12 +1222,51 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1187
1222
  mergedText: mergedHandoff
1188
1223
  };
1189
1224
  }
1190
- if ((targetRel === "CLAUDE.md" || targetRel === "GEMINI.md") && !targetText.includes("AGENTS.md")) {
1191
- return { ...base, action: "conflict", reason: "existing bridge does not route to AGENTS.md" };
1225
+ if (targetRel === "CLAUDE.md" || targetRel === "GEMINI.md") {
1226
+ if (!targetText.includes("AGENTS.md")) {
1227
+ return { ...base, action: "conflict", reason: "existing bridge does not route to AGENTS.md" };
1228
+ }
1229
+ if (looksLikeExpandedKitBridge(targetRel, targetText)) {
1230
+ return {
1231
+ ...base,
1232
+ action: "merge",
1233
+ reason: `${targetRel} appears to be an expanded Kit bridge; restore short bridge so AGENTS.md remains the single source of truth`,
1234
+ mergedText: sourceText
1235
+ };
1236
+ }
1192
1237
  }
1193
1238
  return { ...base, action: "skip", reason: "preserve existing file" };
1194
1239
  }
1195
1240
 
1241
+ function looksLikeExpandedKitBridge(targetRel, text) {
1242
+ if (text.includes("This file is a bridge only")) return false;
1243
+ if (targetRel === "CLAUDE.md") {
1244
+ return (text.includes("This file provides guidance to Claude Code") && text.includes("## Session Startup"))
1245
+ || text.includes("## Architecture")
1246
+ || text.includes("## CLI Commands")
1247
+ || text.includes("Every non-trivial task follows");
1248
+ }
1249
+ if (targetRel === "GEMINI.md") {
1250
+ return text.includes("## Architecture")
1251
+ || text.includes("## CLI Commands")
1252
+ || text.includes("Every non-trivial task follows");
1253
+ }
1254
+ return false;
1255
+ }
1256
+
1257
+ function mergeOnboardingScenarioALabel(targetText) {
1258
+ let merged = targetText;
1259
+ merged = merged.replace(
1260
+ /\*\*A\. 寫 \/ 改代碼項目\*\* —— 你有一個(?: project 的 codebase|程式項目)想長期維護/g,
1261
+ "**A. 建構系統 / 工具 / 平台 / 網站或應用** —— 你想由 AI 協助建立或長期維護一個可運作的項目"
1262
+ );
1263
+ merged = merged.replace(
1264
+ /### Scenario A\. 寫 \/ 改代碼項目/g,
1265
+ "### Scenario A. 建構系統 / 工具 / 平台 / 網站或應用"
1266
+ );
1267
+ return merged;
1268
+ }
1269
+
1196
1270
  function mergeHandoffLifecycleField(targetText) {
1197
1271
  const openingMarker = "<!-- ack:field:opening-message-matches-current-state -->";
1198
1272
  if (!targetText.includes(openingMarker)) return null;
@@ -1342,24 +1416,24 @@ async function assessLastCloseout(root) {
1342
1416
  return { date };
1343
1417
  }
1344
1418
 
1345
- function printLastCloseout(result) {
1346
- if (!result.date) {
1347
- console.log(" 📅 上次 closeout:(仲未 closeout 過。第一次完成 task 後可以講 AI「收工」)");
1348
- return;
1349
- }
1419
+ function printLastCloseout(result) {
1420
+ if (!result.date) {
1421
+ console.log(" 📅 上次收工:尚未收工過。第一次完成任務後,可以在 AI 對話輸入「收工」。");
1422
+ return;
1423
+ }
1350
1424
  const today = new Date();
1351
1425
  const closeout = new Date(result.date);
1352
1426
  const daysDiff = Math.floor((today - closeout) / (1000 * 60 * 60 * 24));
1353
- if (daysDiff < 0) {
1354
- console.log(` 📅 上次 closeout:${result.date}(日期超前?檢查系統時鐘)`);
1355
- } else if (daysDiff === 0) {
1356
- console.log(` 📅 上次 closeout:今日(${result.date})`);
1357
- } else if (daysDiff <= 30) {
1358
- console.log(` 📅 上次 closeout:${daysDiff} 日前(${result.date})`);
1359
- } else {
1360
- console.log(` 📅 上次 closeout:${daysDiff} 日前(${result.date})— 建議跑下 closeout 整理進度`);
1361
- }
1362
- }
1427
+ if (daysDiff < 0) {
1428
+ console.log(` 📅 上次收工:${result.date}(日期超前?檢查系統時鐘)`);
1429
+ } else if (daysDiff === 0) {
1430
+ console.log(` 📅 上次收工:今日(${result.date})`);
1431
+ } else if (daysDiff <= 30) {
1432
+ console.log(` 📅 上次收工:${daysDiff} 日前(${result.date})`);
1433
+ } else {
1434
+ console.log(` 📅 上次收工:${daysDiff} 日前(${result.date})— 建議輸入「收工」整理進度`);
1435
+ }
1436
+ }
1363
1437
 
1364
1438
  // R-031.2 v0.3.2+: Project age assessment. Reads the oldest folder timestamp in
1365
1439
  // dev/governance_migrations/ which records the first install date. Read-only; doctor
@@ -1622,24 +1696,36 @@ async function detectMode(root) {
1622
1696
  }
1623
1697
 
1624
1698
  function printPlan(command, root, mode, plan, version, isDryRun = false) {
1625
- printCard(version, "continuity ready", "o.o");
1626
- console.log(`command: ${command}`);
1627
- console.log(`current directory: ${process.cwd()}`);
1628
- console.log(`selected root: ${root}`);
1629
- console.log(`mode: ${mode}`);
1630
- console.log("");
1631
- const planIntro = isDryRun
1632
- ? "📋 計劃預覽:以下未執行。create 新增缺少檔案;merge 在備份後合併;skip 保留既有檔案;conflict 代表工具停手等你確認。"
1633
- : "📋 即將執行:以下是本次寫入計劃。create 新增缺少檔案;merge 會先備份再合併;skip 保留既有檔案;conflict 代表工具停手等你確認。";
1699
+ printCard(version, "continuity ready", "o.o");
1700
+ console.log(`command: ${command}`);
1701
+ console.log(`current directory: ${process.cwd()}`);
1702
+ console.log(`selected root: ${root}`);
1703
+ console.log(`mode: ${mode}`);
1704
+ console.log("");
1705
+ const planIntro = planIntroFor(command, mode, isDryRun);
1634
1706
  console.log(planIntro);
1635
- console.log("");
1707
+ console.log("");
1636
1708
  for (const action of ["create", "merge", "skip", "conflict"]) {
1637
1709
  const items = plan.filter((item) => item.action === action);
1638
1710
  console.log(`${action}: ${items.length}`);
1639
1711
  for (const item of items) console.log(` ${item.targetRel}${item.reason ? ` - ${item.reason}` : ""}`);
1640
1712
  }
1641
- console.log(`\nbackup: ${plan.filter((item) => item.action === "merge").length}`);
1642
- }
1713
+ console.log(`\nbackup: ${plan.filter((item) => item.action === "merge").length}`);
1714
+ }
1715
+
1716
+ function planIntroFor(command, mode, isDryRun) {
1717
+ const prefix = isDryRun ? "📋 預演結果:這次不會寫入檔案。" : "📋 寫入前確認:工具準備這樣處理目前資料夾。";
1718
+ if (command === "init" && mode === "first-install") {
1719
+ return `${prefix} 目前資料夾未見 Kit 檔案;工具會建立交接文件、AI 入口檔與工作規則。沒有既有檔案會被覆寫。`;
1720
+ }
1721
+ if (command === "init" && mode === "partial") {
1722
+ return `${prefix} 目前資料夾已有部分 AI 或 Kit 檔案;工具會補齊缺少檔案,保留既有檔案。安裝後可能仍要用 upgrade 補入口連接。`;
1723
+ }
1724
+ if (command === "upgrade") {
1725
+ return `${prefix} 工具會檢查既有 Kit 檔案;能安全合併才合併,不能判斷時會停手並列為 conflict。`;
1726
+ }
1727
+ return `${prefix} create 代表建立缺少檔案;merge 代表先備份再合併;skip 代表保留既有檔案;conflict 代表工具停手等你判斷。`;
1728
+ }
1643
1729
 
1644
1730
  // R-026 CLI Output Contract: install/upgrade 完成必含四項(版本/模式/剛完成/下一步)。
1645
1731
  function printInstallSummary(version, command, mode, root, counts) {
@@ -1653,36 +1739,48 @@ function printInstallSummary(version, command, mode, root, counts) {
1653
1739
  console.log(`📦 版本:v${version}`);
1654
1740
  console.log(`🛠️ 模式:${mode}`);
1655
1741
  console.log(`🔎 剛完成:${command} 命令;create ${counts.created} / merge ${counts.merged} / skip ${counts.skipped} / conflict ${counts.conflicts}。`);
1656
- if (counts.conflicts > 0) {
1742
+ if (counts.conflicts > 0) {
1657
1743
  console.log("🚀 下一步:把 migration report 或這段輸出貼給 AI,請它判斷衝突檔案怎樣處理;工具已停手,沒有覆寫 conflict 檔案。");
1658
- } else if (command === "upgrade") {
1659
- console.log("🚀 下一步:留意下方 upgrade self-check(自動跑 doctor);若全綠即升級完成。");
1660
- } else {
1661
- console.log("🚀 下一步:開新 AI 對話,按下方提示貼入 Work in <root> 一句後描述任務。");
1662
- }
1663
- }
1664
-
1665
- function printDryRunExplanation(plan) {
1666
- const conflicts = plan.filter((item) => item.action === "conflict");
1667
- console.log("✅ 這次沒有改動任何檔案。");
1668
- if (conflicts.length === 0) {
1669
- console.log("✅ 沒有發現 conflict。你仍應先看清楚 create / merge / skip 清單,再決定是否執行正式 upgrade。");
1670
- return;
1671
- }
1672
- console.log(`⚠️ 需要人工確認:有 ${conflicts.length} 個既有檔案,工具不能安全判斷怎樣合併。`);
1673
- console.log("⚠️ 這不是檔案壞掉,也沒有覆寫你的檔案。");
1674
- console.log("📋 下一步:把這段輸出貼給 AI,叫它幫你判斷要保留、合併,還是手動修改。");
1744
+ } else if (command === "upgrade") {
1745
+ console.log("🚀 下一步:留意下方升級後自動檢查;若全綠即升級完成。");
1746
+ } else if (mode === "partial" || counts.skipped > 0) {
1747
+ console.log("🚀 下一步:先看下方提示。若你原本已有 AGENTS.md 或其他 AI 規則,請先執行 upgrade --dry-run 補入口連接,再執行 doctor。");
1748
+ } else {
1749
+ console.log("🚀 下一步:不用再留在終端機。打開 AI 工具,貼下方起步句。");
1750
+ }
1751
+ }
1752
+
1753
+ function printDryRunExplanation(command, mode, plan) {
1754
+ const conflicts = plan.filter((item) => item.action === "conflict");
1755
+ console.log("✅ 這次沒有改動任何檔案。");
1756
+ if (conflicts.length === 0) {
1757
+ if (command === "init") {
1758
+ console.log("✅ 沒有發現 conflict。若這是你要安裝 Kit 的資料夾,下一步執行:");
1759
+ console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest init");
1760
+ return;
1761
+ }
1762
+ if (mode === "upgrade-existing") {
1763
+ console.log("✅ 沒有發現 conflict。若你想正式套用以上升級計劃,下一步執行:");
1764
+ console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest upgrade");
1765
+ return;
1766
+ }
1767
+ console.log("✅ 沒有發現 conflict。請按你剛才預演的命令去掉 --dry-run 後正式執行。");
1768
+ return;
1769
+ }
1770
+ console.log(`⚠️ 需要人工確認:有 ${conflicts.length} 個既有檔案,工具不能安全判斷怎樣合併。`);
1771
+ console.log("⚠️ 這不是檔案壞掉,也沒有覆寫你的檔案。");
1772
+ console.log("📋 下一步:把這段輸出貼給 AI,叫它幫你判斷要保留、合併,還是手動修改。");
1675
1773
  }
1676
1774
 
1677
- async function confirmWrite() {
1678
- const rl = createInterface({ input, output });
1679
- try {
1680
- const answer = await rl.question("Write missing Agent Handoff Kit files? Type yes to continue: ");
1681
- return answer.trim().toLowerCase() === "yes";
1682
- } finally {
1683
- rl.close();
1684
- }
1685
- }
1775
+ async function confirmWrite() {
1776
+ const rl = createInterface({ input, output });
1777
+ try {
1778
+ const answer = await rl.question("要按上面計劃寫入 / 合併 Kit 檔案嗎?輸入 yes 繼續:");
1779
+ return answer.trim().toLowerCase() === "yes";
1780
+ } finally {
1781
+ rl.close();
1782
+ }
1783
+ }
1686
1784
 
1687
1785
  async function writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir, metadataUpdated = null) {
1688
1786
  const reportPath = path.join(migrationDir, "migration-report.md");
@@ -1833,62 +1931,61 @@ function printCard(version, status, eyes) {
1833
1931
  console.log("");
1834
1932
  }
1835
1933
 
1836
- function printInstallNextSteps(root, conflictCount) {
1837
- console.log("");
1838
- console.log("============================================================");
1839
- console.log("✅ 安裝完成:下一步請在 AI 對話中操作");
1840
- console.log("============================================================");
1934
+ function printInstallNextSteps(root, conflictCount, mode = "first-install", skippedCount = 0) {
1935
+ console.log("");
1936
+ console.log("============================================================");
1937
+ if (mode === "partial" || skippedCount > 0) {
1938
+ console.log("⚠️ 已補齊缺少檔案,但仍要檢查入口連接");
1939
+ } else {
1940
+ console.log("✅ 安裝完成:下一步請在 AI 對話中操作");
1941
+ }
1942
+ console.log("============================================================");
1841
1943
  if (conflictCount > 0) {
1842
1944
  console.log("⚠️ 狀態:有既有檔案需要人工確認,詳情見 migration report。");
1843
1945
  console.log("⚠️ 這不是檔案壞掉;工具已停手,沒有覆寫 conflict 檔案。");
1844
- console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
1845
- console.log("");
1846
- }
1847
- // R-031.2 v0.3.2+: first-install checklist. It answers the user's first
1848
- // question: "is this installed and what do I do next?"
1849
- console.log("📋 如何確認安裝完成:");
1850
- console.log("");
1851
- console.log(" 1. 在 Terminal 執行 npx --yes @adamchanadam/agent-handoff-kit@latest doctor,應該見到「status: passed」");
1852
- console.log(" 2. 你的 dev/ 資料夾應該有規則、交接與工作紀錄等檔案");
1853
- console.log(" 3. 在你使用的 AI 工具(Claude Code / Codex / Gemini)開新對話,貼下面起步句");
1854
- console.log("");
1855
- console.log("⚠️ 注意:Agent Handoff Kit 是放在項目資料夾內的一組交接檔案。");
1856
- console.log(" 它沒有圖形介面,不會啟動伺服器,也不會自動替你做事;你需要在 AI 對話中使用它。");
1857
- console.log(" `npx --yes ...` 只是讓 npm 取得執行工具;不代表 doctor 會安裝或修改項目文件。");
1858
- console.log("");
1859
- console.log("------------------------------------------------------------");
1860
- console.log("⚠️ 請注意:下面文字不是 Terminal 指令。");
1861
- console.log("📋 請打開你要使用的 AI 工具,新增一段對話,貼上下面一句:");
1862
- console.log("------------------------------------------------------------");
1863
- console.log(`Work in ${root}. I just installed agent-handoff-kit. Help me get started.`);
1864
- console.log("------------------------------------------------------------");
1865
- console.log("");
1866
- console.log("🚀 AI 會主動引導你選擇情景(寫代碼 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),");
1867
- console.log(" 一步一步帶你做第一個任務(由新手引導包主動接管)。");
1868
- console.log("");
1869
- console.log("💡 之後你熟悉流程後,可改用更直接的開工句:");
1870
- console.log(` Work in ${root}. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.`);
1946
+ console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
1947
+ console.log("");
1948
+ }
1949
+ if (mode === "partial" || skippedCount > 0) {
1950
+ console.log("你原本已有部分 AI 記憶檔,工具已保留它們,沒有覆寫。");
1951
+ console.log("下一步先不要開始新任務;請在終端機執行以下預演,讓工具檢查能否安全補入口連接:");
1952
+ console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run");
1953
+ console.log("");
1954
+ console.log("如預演顯示沒有 conflict,再執行:");
1955
+ console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest upgrade");
1956
+ console.log("============================================================");
1957
+ return;
1958
+ }
1959
+ console.log("------------------------------------------------------------");
1960
+ console.log("⚠️ 下面這句不是終端機指令。");
1961
+ console.log("📋 請打開 Claude Code / Claude Cowork / OpenAI Codex / Google Antigravity,");
1962
+ console.log(" 或任何能讀寫此資料夾的 AI 工具,新增對話後貼上:");
1963
+ console.log("------------------------------------------------------------");
1964
+ console.log(`Work in ${root}. I just installed agent-handoff-kit. Help me get started.`);
1965
+ console.log("------------------------------------------------------------");
1871
1966
  console.log("");
1872
- console.log("🩺 如要檢查安裝是否完整,可在 Terminal 執行:");
1873
- console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
1967
+ console.log("🚀 AI 會先確認這個資料夾,然後帶你選擇第一個任務情景:建構系統 / 工具 / 平台 / 網站或應用、研究報告、知識庫整理、學寫代碼,或其他。");
1874
1968
  console.log("============================================================");
1875
1969
  }
1876
1970
 
1877
1971
  // R-031 v0.3.1+: Upgrade substantive next-step block. Distinct from install
1878
1972
  // (`printInstallNextSteps`) because the user is not first-time; pushing them through
1879
1973
  // the onboarding canonical phrase resets context they already have.
1880
- async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRootVersion) {
1881
- console.log("");
1882
- console.log("============================================================");
1974
+ async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRootVersion) {
1975
+ console.log("");
1976
+ console.log("============================================================");
1977
+ if (conflictCount > 0) {
1978
+ console.log("⚠️ 升級未完成:有檔案需要人工確認");
1979
+ console.log("============================================================");
1980
+ console.log("⚠️ 狀態:有既有檔案需要人工確認,詳情見 migration report。");
1981
+ console.log("⚠️ 這不是檔案壞掉;工具已停手,沒有覆寫 conflict 檔案。");
1982
+ console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
1983
+ console.log("============================================================");
1984
+ return;
1985
+ }
1883
1986
  console.log("✅ 升級完成:Kit 檔案已更新到最新版本");
1884
- console.log("============================================================");
1885
- if (conflictCount > 0) {
1886
- console.log("⚠️ 狀態:有既有檔案需要人工確認,詳情見 migration report。");
1887
- console.log("⚠️ 這不是檔案壞掉;工具已停手,沒有覆寫 conflict 檔案。");
1888
- console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
1889
- console.log("");
1890
- }
1891
- // R-031.2 v0.3.2+: Inline whatsnew summary — directly surface what changed in this
1987
+ console.log("============================================================");
1988
+ // R-031.2 v0.3.2+: Inline whatsnew summary — directly surface what changed in this
1892
1989
  // version (and any intermediate versions the user skipped).
1893
1990
  // R-031.3 v0.3.3+: fromVersion now uses pre-upgrade snapshot (captured before
1894
1991
  // inject mutated PROJECT_INDEX), so the range narrative reflects actual user
@@ -1901,7 +1998,7 @@ async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRoo
1901
1998
  console.log(`Work in ${root}. I just upgraded agent-handoff-kit. Brief me on what changed in this version and what I should pay attention to.`);
1902
1999
  console.log("------------------------------------------------------------");
1903
2000
  console.log("");
1904
- console.log("🩺 升級驗收會在下方自動跑 doctor;若全綠即升級完成。");
2001
+ console.log("🩺 升級驗收會在下方自動執行 doctor;若全綠即升級完成。");
1905
2002
  console.log("============================================================");
1906
2003
  }
1907
2004
 
@@ -2016,14 +2113,13 @@ function printUpgradeNoopShortCircuit(version, health = { handoffLifecycle: { ok
2016
2113
  if (health.handoffLifecycle?.ok) {
2017
2114
  console.log("✅ 結果:你已經是最新版本,沒有檔案需要建立或合併;用戶填寫的內容全部保留現狀。");
2018
2115
  console.log("");
2019
- console.log("🚀 下一步:繼續日常使用即可。如要檢查健康狀態,可執行:");
2020
- console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
2116
+ console.log("🚀 下一步:回到原本的 AI 對話或開工句即可;如果剛完成任務,記得在 AI 對話輸入「收工」保存交接。");
2021
2117
  console.log("");
2022
2118
  return;
2023
2119
  }
2024
2120
  console.log("⚠️ 結果:Kit 檔案已是最新版本,沒有檔案需要建立或合併;但交接狀態仍需 AI closeout 核對。");
2025
2121
  console.log("");
2026
- console.log("🚀 下一步:先跑 doctor 取得待修項,再把輸出貼給 AI;不要重裝或覆寫用戶內容。");
2122
+ console.log("🚀 下一步:先執行 doctor 取得待修項,再把輸出貼給 AI;不要重裝或覆寫用戶內容。");
2027
2123
  console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
2028
2124
  console.log("");
2029
2125
  }
@@ -2051,24 +2147,24 @@ Usage:
2051
2147
  agent-handoff-kit upgrade [--dry-run] [--yes] [--root <path>]
2052
2148
  agent-handoff-kit doctor [--root <path>]
2053
2149
 
2054
- Commands:
2055
- init Plan or install missing core files and rule packs.
2056
- upgrade Preserve existing files; merge safe core updates or report conflicts.
2057
- doctor Check required installed files.
2058
-
2059
- 中文速讀:
2060
- ✅ init 第一次安裝 Kit 文件。
2061
- 🔄 upgrade 升級既有 Kit 文件;先用 --dry-run 預演。
2062
- 🩺 doctor 檢查必要文件與交接結構是否完整。
2063
-
2064
- After install:
2065
- Do not type the shown "Work in ..." message into Terminal.
2066
- Open your AI tool, start a new chat, and paste it there.
2067
- The default post-install prompt triggers the onboarding pack — AI
2068
- will guide you through scenario selection (coding / research / knowledge /
2069
- learning / other / integrations governance) and walk you through your first task.
2150
+ Commands:
2151
+ init Plan or install missing core files and rule packs.
2152
+ upgrade Preserve existing files; merge safe core updates or report conflicts.
2153
+ doctor Check required installed files.
2070
2154
 
2071
- Terminal 範例:
2155
+ 中文速讀:
2156
+ ✅ 第一次用:先在項目資料夾執行 init。
2157
+ 🔄 已裝過:先用 upgrade --dry-run 預演,再決定是否正式升級。
2158
+ 🩺 不確定狀態:用 doctor 檢查;doctor 只檢查,不會改檔。
2159
+
2160
+ 安裝之後:
2161
+ 不要把顯示出來的 "Work in ..." 文字輸入終端機。
2162
+ 請打開 Claude Code / Claude Cowork / OpenAI Codex / Google Antigravity,
2163
+ 或任何能讀寫此資料夾的 AI 工具,新增對話後貼上那句起步句。
2164
+ 這句會啟動新手引導;AI 會先帶你選擇情境,
2165
+ 再一步一步整理第一個任務。
2166
+
2167
+ 終端機範例:
2072
2168
  npx --yes @adamchanadam/agent-handoff-kit@latest init
2073
2169
  npx --yes @adamchanadam/agent-handoff-kit@latest doctor
2074
2170
  npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
@@ -2076,12 +2172,13 @@ Terminal 範例:
2076
2172
  以上才是建議的 npx 用戶路徑。裸寫不帶 --yes / @latest 的 npx doctor
2077
2173
  不是本工具的建議用戶路徑,容易先出現 npm 自己的安裝提示。
2078
2174
 
2079
- 放在 package 名稱前的 --yes 只讓 npm 取得執行工具,避免額外出現
2080
- "Need to install" 提示。這不會令 doctor 安裝或修改項目文件;
2081
- doctor 只檢查目前的 Kit 文件。即使資料夾已有 AGENTS.md 或 dev/,
2082
- npx 仍可能只是先取得 npm 執行工具。
2175
+ 即使資料夾已有 AGENTS.md 或 dev/,電腦也未必已經有可直接執行的工具;
2176
+ npx --yes 只是先取得工具,然後才執行你指定的 init / doctor / upgrade。
2177
+
2178
+ 放在 package 名稱前的 --yes 只讓 npm 先取得執行工具,避免額外出現
2179
+ "Need to install" 提示。真正會建立項目文件的是 init;doctor 只檢查。
2083
2180
  `);
2084
2181
  console.log(`📦 版本:v${version}`);
2085
2182
  console.log(`🛠️ 模式:help ready`);
2086
- console.log(`🚀 下一步:第一次使用先跑 npx --yes ... init;既有專案升級用 npx --yes ... upgrade --dry-run;要檢查現狀用 npx --yes ... doctor。`);
2183
+ console.log(`🚀 下一步:新項目先執行 init;舊項目先執行 upgrade --dry-run;只想檢查才執行 doctor。`);
2087
2184
  }
@@ -1,13 +1,13 @@
1
1
  # v0.3.1
2
2
 
3
- ## 本版新加咗咩
3
+ ## 本版新加了甚麼
4
4
 
5
- CLI 升級流程嘅 messaging 改進 —— 你升完或者第二次跑 upgrade 嗰陣會見到唔同 output。第二次跑 upgrade(零改動)會直接短訊「你已係最新版本」,唔再印「安裝完成」+ 新手起步句嘅完整 ceremony。
5
+ 改善升級流程的提示文字。完成升級、再次執行 `upgrade`、或沒有任何檔案需要更新時,工具會顯示不同提示,避免把「已經是最新版本」誤說成「安裝完成」。
6
6
 
7
- ## 對你已有檔案嘅影響
7
+ ## 對你已有檔案的影響
8
8
 
9
- 完全冇影響。純 CLI source 改進,無 user-facing template 改動,doctor 對既有用戶仍 PASS。
9
+ 本版只調整工具輸出文字,不會改動既有項目內容,也不會改變已安裝的 Kit 文件結構。
10
10
 
11
11
  ## 建議下一步
12
12
 
13
- 跑 doctor confirm 健康即可。
13
+ 執行 `doctor` 檢查項目健康即可。