@adamchanadam/agent-handoff-kit 0.3.1 → 0.3.2

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.1` 已正式發佈到 GitHub 與 npm。這是早期可用版本,仍在持續完善中。
3
+ 狀態:`v0.3.2` 已正式發佈到 GitHub 與 npm。這是早期可用版本,仍在持續完善中。
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
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  import { createInterface } from "node:readline/promises";
4
4
  import { stdin as input, stdout as output } from "node:process";
5
- import { copyFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
5
+ import { copyFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
6
6
  import path from "node:path";
7
7
  import { fileURLToPath } from "node:url";
8
8
 
@@ -498,6 +498,29 @@ async function runInstall(command, root, options, version) {
498
498
  created.push(item.targetRel);
499
499
  }
500
500
 
501
+ // R-031.2 v0.3.2+: For freshly-created PROJECT_INDEX (fresh install), inject the
502
+ // current CLI version into the template version metadata row. Template ships with
503
+ // a hardcoded historical version (0.1.7) which is preserved by R-016 during upgrades
504
+ // but should NOT confuse a fresh installer about which version they just installed.
505
+ // Only triggers when PROJECT_INDEX was just created (not preserved/merged).
506
+ if (created.includes("dev/PROJECT_INDEX.md")) {
507
+ const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
508
+ try {
509
+ const text = await readFile(indexPath, "utf8");
510
+ const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
511
+ if (m && isStableSemver(m[1]) && compareSemver(m[1], version) < 0) {
512
+ const updated = text.replace(
513
+ /\| Agent Handoff Kit template version \| [\d.]+ \|/,
514
+ `| Agent Handoff Kit template version | ${version} |`
515
+ );
516
+ await writeFile(indexPath, updated, "utf8");
517
+ }
518
+ } catch {
519
+ // ignore — fresh install will still pass doctor because the anchor (R-016) only
520
+ // checks for the row's existence, not a specific version.
521
+ }
522
+ }
523
+
501
524
  for (const item of plan) {
502
525
  if (item.action !== "merge") continue;
503
526
  const backupPath = path.join(backupDir, item.targetRel);
@@ -535,8 +558,9 @@ async function runInstall(command, root, options, version) {
535
558
  // R-031 v0.3.1+: install vs upgrade narrative split. Upgrade substantive uses
536
559
  // "升級完成" framing (not "安裝完成") and offers optional review prompt instead of
537
560
  // pushing first-time onboarding canonical phrase.
561
+ // R-031.2 v0.3.2+: printUpgradeNextSteps now async (awaits inline whatsnew print).
538
562
  if (command === "upgrade") {
539
- printUpgradeNextSteps(root, conflicts.length);
563
+ await printUpgradeNextSteps(root, conflicts.length, version);
540
564
  } else {
541
565
  printInstallNextSteps(root, conflicts.length);
542
566
  }
@@ -661,6 +685,18 @@ async function runDoctor(root, version, options = {}) {
661
685
  }
662
686
  }
663
687
 
688
+ // R-031.2 v0.3.2+: 項目狀態速覽 —— 三向 version 對比 + 距上次 closeout 幾耐 +
689
+ // 項目首次安裝距今幾耐。從用戶跑 doctor 嗰刻嘅 mental state 出發(confirm health /
690
+ // suspect drift / curious about version / continuity awareness),唔等用戶 ask AI。
691
+ console.log("");
692
+ console.log("項目狀態速覽:");
693
+ const versionAlignment = await assessVersionAlignment(root, version);
694
+ printVersionAlignment(versionAlignment);
695
+ const lastCloseout = await assessLastCloseout(root);
696
+ printLastCloseout(lastCloseout);
697
+ const projectAge = await assessProjectAge(root);
698
+ printProjectAge(projectAge);
699
+
664
700
  const overallHealthy = credentialResult.ok;
665
701
  printDoctorSummary(version, root, overallHealthy ? "healthy" : "needs-attention", {
666
702
  checked: rows.length + anchorRows.length + schemaRows.length + mirrorRows.length + 2,
@@ -989,6 +1025,137 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
989
1025
  return { ...base, action: "skip", reason: "preserve existing file" };
990
1026
  }
991
1027
 
1028
+ // R-031.2 v0.3.2+: Version alignment assessment for doctor "項目狀態速覽".
1029
+ // Compares CLI version (running), root template metadata version (in dev/PROJECT_INDEX.md),
1030
+ // and npm latest. Surfaces drift awareness because previous design relied on startup
1031
+ // maybePrintUpdateNotice which silently fails when npx auto-fetches latest (CLI version
1032
+ // equals npm latest, so the notice never triggers, leaving user root drift invisible).
1033
+ async function assessVersionAlignment(root, cliVersion) {
1034
+ const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
1035
+ let rootVersion = null;
1036
+ try {
1037
+ const text = await readFile(indexPath, "utf8");
1038
+ const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
1039
+ if (m) rootVersion = m[1];
1040
+ } catch {
1041
+ // file missing or unreadable; rootVersion stays null
1042
+ }
1043
+
1044
+ let npmLatest = null;
1045
+ try {
1046
+ npmLatest = await fetchLatestVersion();
1047
+ } catch {
1048
+ // network failure; npmLatest stays null
1049
+ }
1050
+
1051
+ return { cliVersion, rootVersion, npmLatest };
1052
+ }
1053
+
1054
+ function printVersionAlignment(result) {
1055
+ const { cliVersion, rootVersion, npmLatest } = result;
1056
+ if (rootVersion === null) {
1057
+ console.log(` 📦 版本:CLI v${cliVersion} / root metadata 缺失(曾經手動編輯?)/ npm latest ${npmLatest ? "v" + npmLatest : "無法查詢"}`);
1058
+ return;
1059
+ }
1060
+ if (npmLatest === null) {
1061
+ console.log(` 📦 版本:CLI v${cliVersion} / root v${rootVersion} / npm latest 無法查詢(網絡可能不通)`);
1062
+ return;
1063
+ }
1064
+ const aligned = cliVersion === rootVersion && rootVersion === npmLatest;
1065
+ if (aligned) {
1066
+ console.log(` 📦 版本:CLI / root / npm latest 三向對齊 v${cliVersion} ✅`);
1067
+ return;
1068
+ }
1069
+ console.log(` 📦 版本:CLI v${cliVersion} / root v${rootVersion} / npm latest v${npmLatest}`);
1070
+ if (npmLatest && compareSemver(npmLatest, cliVersion) > 0) {
1071
+ console.log(` npm 有新版(v${npmLatest});可執行:npx @adamchanadam/agent-handoff-kit@latest upgrade`);
1072
+ } else if (cliVersion !== rootVersion) {
1073
+ console.log(` 你 root template metadata 同 CLI 唔對齊;兩個版本仍相容 doctor 仍 PASS;如想對齊:npx @adamchanadam/agent-handoff-kit@latest upgrade`);
1074
+ }
1075
+ }
1076
+
1077
+ // R-031.2 v0.3.2+: Last closeout assessment. Reads dev/SESSION_HANDOFF.md "Last Updated:"
1078
+ // line (strict format, reliable). Falls back to dev/SESSION_LOG.md first H2 date if
1079
+ // HANDOFF missing or unparseable.
1080
+ async function assessLastCloseout(root) {
1081
+ const handoffPath = path.join(root, "dev/SESSION_HANDOFF.md");
1082
+ let date = null;
1083
+ try {
1084
+ const text = await readFile(handoffPath, "utf8");
1085
+ const m = text.match(/Last Updated:\s*(\d{4}-\d{2}-\d{2})/);
1086
+ if (m) date = m[1];
1087
+ } catch {
1088
+ // ignore
1089
+ }
1090
+
1091
+ if (!date) {
1092
+ const logPath = path.join(root, "dev/SESSION_LOG.md");
1093
+ try {
1094
+ const text = await readFile(logPath, "utf8");
1095
+ const m = text.match(/^## (\d{4}-\d{2}-\d{2})/m);
1096
+ if (m) date = m[1];
1097
+ } catch {
1098
+ // ignore
1099
+ }
1100
+ }
1101
+
1102
+ return { date };
1103
+ }
1104
+
1105
+ function printLastCloseout(result) {
1106
+ if (!result.date) {
1107
+ console.log(" 📅 上次 closeout:(仲未 closeout 過。第一次完成 task 後可以講 AI「收工」)");
1108
+ return;
1109
+ }
1110
+ const today = new Date();
1111
+ const closeout = new Date(result.date);
1112
+ const daysDiff = Math.floor((today - closeout) / (1000 * 60 * 60 * 24));
1113
+ if (daysDiff < 0) {
1114
+ console.log(` 📅 上次 closeout:${result.date}(日期超前?檢查系統時鐘)`);
1115
+ } else if (daysDiff === 0) {
1116
+ console.log(` 📅 上次 closeout:今日(${result.date})`);
1117
+ } else if (daysDiff <= 30) {
1118
+ console.log(` 📅 上次 closeout:${daysDiff} 日前(${result.date})`);
1119
+ } else {
1120
+ console.log(` 📅 上次 closeout:${daysDiff} 日前(${result.date})— 建議跑下 closeout 整理進度`);
1121
+ }
1122
+ }
1123
+
1124
+ // R-031.2 v0.3.2+: Project age assessment. Reads the oldest folder timestamp in
1125
+ // dev/governance_migrations/ which records the first install date. Read-only; doctor
1126
+ // remains side-effect-free (no new write logic).
1127
+ async function assessProjectAge(root) {
1128
+ const migrationsDir = path.join(root, "dev/governance_migrations");
1129
+ try {
1130
+ const entries = await readdir(migrationsDir);
1131
+ const timestamps = entries.filter((name) => /^\d{8}T\d{6}Z$/.test(name)).sort();
1132
+ if (timestamps.length === 0) return { firstInstall: null };
1133
+ const oldest = timestamps[0];
1134
+ // Format: 20260423T112233Z → 2026-04-23
1135
+ const year = oldest.slice(0, 4);
1136
+ const month = oldest.slice(4, 6);
1137
+ const day = oldest.slice(6, 8);
1138
+ return { firstInstall: `${year}-${month}-${day}` };
1139
+ } catch {
1140
+ return { firstInstall: null };
1141
+ }
1142
+ }
1143
+
1144
+ function printProjectAge(result) {
1145
+ if (!result.firstInstall) {
1146
+ console.log(" 🌱 項目首次安裝距今:未知(dev/governance_migrations/ 未有 timestamp)");
1147
+ return;
1148
+ }
1149
+ const today = new Date();
1150
+ const firstInstall = new Date(result.firstInstall);
1151
+ const daysDiff = Math.floor((today - firstInstall) / (1000 * 60 * 60 * 24));
1152
+ if (daysDiff === 0) {
1153
+ console.log(` 🌱 項目首次安裝距今:今日(${result.firstInstall})`);
1154
+ } else {
1155
+ console.log(` 🌱 項目首次安裝距今:${daysDiff} 日(自 ${result.firstInstall})`);
1156
+ }
1157
+ }
1158
+
992
1159
  // R-010 SESSION_LOG handoff-role discipline (warn-only doctor check).
993
1160
  // Returns { ok, warnings } where:
994
1161
  // - ok: true if no warnings triggered
@@ -1423,6 +1590,19 @@ function printInstallNextSteps(root, conflictCount) {
1423
1590
  console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
1424
1591
  console.log("");
1425
1592
  }
1593
+ // R-031.2 v0.3.2+: 「點 confirm 你裝啱咗」mini-checklist,直接答用戶第一次安裝後嘅
1594
+ // anxiety「我裝啱咗嗎」。三個具體 verify step + 一句講清本工具係 background harness
1595
+ // (冇 GUI、冇 server、需要連住 AI tool 先見到實際 value)。
1596
+ console.log("📋 點 confirm 你裝啱咗:");
1597
+ console.log("");
1598
+ console.log(" 1. 跑 npx @adamchanadam/agent-handoff-kit doctor 應該見到「status: passed」");
1599
+ console.log(" 2. 你 dev/ folder 應該有起碼 14 個檔(rules / SESSION_HANDOFF / SESSION_LOG 等)");
1600
+ console.log(" 3. 喺你 AI tool(Claude Code / Codex / Gemini)開新對話,貼下面起步句先見到實際 value");
1601
+ console.log("");
1602
+ console.log("⚠️ 注意:Agent Handoff Kit 只係 background harness —— 喺你 project folder 入面嘅幾類檔案。");
1603
+ console.log(" 冇 GUI、唔 run server、唔自動做嘢。你需要連住至少一個 AI tool 嘅對話,AI 先會讀依啲檔案做正事。");
1604
+ console.log("");
1605
+ console.log("------------------------------------------------------------");
1426
1606
  console.log("⚠️ 請注意:下面文字不是 Terminal 指令。");
1427
1607
  console.log("📋 請打開你要使用的 AI 工具,新增一段對話,貼上下面一句:");
1428
1608
  console.log("------------------------------------------------------------");
@@ -1443,7 +1623,7 @@ function printInstallNextSteps(root, conflictCount) {
1443
1623
  // R-031 v0.3.1+: Upgrade substantive next-step block. Distinct from install
1444
1624
  // (`printInstallNextSteps`) because the user is not first-time; pushing them through
1445
1625
  // the onboarding canonical phrase resets context they already have.
1446
- function printUpgradeNextSteps(root, conflictCount) {
1626
+ async function printUpgradeNextSteps(root, conflictCount, version) {
1447
1627
  console.log("");
1448
1628
  console.log("============================================================");
1449
1629
  console.log("✅ 升級完成:管治架構檔案已更新到最新版本");
@@ -1454,6 +1634,11 @@ function printUpgradeNextSteps(root, conflictCount) {
1454
1634
  console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
1455
1635
  console.log("");
1456
1636
  }
1637
+ // R-031.2 v0.3.2+: Inline whatsnew summary — directly surface what changed in this
1638
+ // version (and any intermediate versions the user skipped), without requiring the
1639
+ // user to ask AI separately. Treats user as collaborator who deserves to know what's
1640
+ // shipped, not reactive recipient who must opt-in to discovery.
1641
+ await printWhatsnew(root, version);
1457
1642
  console.log("📋 如你正在進行中的工作 session 已熟悉 Agent Handoff Kit,繼續使用原本的開工方式即可,無需重新做新手引導。");
1458
1643
  console.log("");
1459
1644
  console.log("💡 如想了解本版本新加了甚麼功能,可選用以下開工句(非強制):");
@@ -1465,6 +1650,74 @@ function printUpgradeNextSteps(root, conflictCount) {
1465
1650
  console.log("============================================================");
1466
1651
  }
1467
1652
 
1653
+ // R-031.2 v0.3.2+: Print whatsnew summaries for the version range crossed by this
1654
+ // upgrade. fromVersion = user root template metadata version (the state before
1655
+ // upgrade; R-016 preserves this row so it still reflects the prior state after
1656
+ // upgrade finishes). toVersion = current CLI version. Range is exclusive-fromVersion
1657
+ // inclusive-toVersion. Limit to first + last when crossing > 3 versions (elide middle).
1658
+ async function printWhatsnew(root, toVersion) {
1659
+ const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
1660
+ let fromVersion = null;
1661
+ try {
1662
+ const text = await readFile(indexPath, "utf8");
1663
+ const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
1664
+ if (m) fromVersion = m[1];
1665
+ } catch {
1666
+ return;
1667
+ }
1668
+ if (!fromVersion || !isStableSemver(fromVersion) || compareSemver(fromVersion, toVersion) >= 0) {
1669
+ return;
1670
+ }
1671
+
1672
+ const whatsnewDir = path.join(packageRoot, "docs/whatsnew");
1673
+ let entries = [];
1674
+ try {
1675
+ entries = await readdir(whatsnewDir);
1676
+ } catch {
1677
+ console.log(`💡 本版 release notes:https://github.com/Adamchanadam/agent-handoff-kit/releases/tag/v${toVersion}`);
1678
+ console.log("");
1679
+ return;
1680
+ }
1681
+
1682
+ const relevant = entries
1683
+ .filter((name) => /^v\d+\.\d+\.\d+\.md$/.test(name))
1684
+ .map((name) => name.replace(/^v/, "").replace(/\.md$/, ""))
1685
+ .filter((v) => compareSemver(v, fromVersion) > 0 && compareSemver(v, toVersion) <= 0)
1686
+ .sort((a, b) => compareSemver(a, b));
1687
+
1688
+ if (relevant.length === 0) {
1689
+ console.log(`💡 本版 release notes:https://github.com/Adamchanadam/agent-handoff-kit/releases`);
1690
+ console.log(` (v${fromVersion} → v${toVersion} 跨版本嘅完整變更見 GitHub Release 全列表)`);
1691
+ console.log("");
1692
+ return;
1693
+ }
1694
+
1695
+ console.log(`📰 本次升級(v${fromVersion} → v${toVersion})涵蓋 ${relevant.length} 個版本嘅 release notes:`);
1696
+ console.log("");
1697
+
1698
+ const toShow = relevant.length <= 3 ? relevant : [relevant[0], relevant[relevant.length - 1]];
1699
+ const elidedCount = relevant.length > 3 ? relevant.length - 2 : 0;
1700
+
1701
+ for (let i = 0; i < toShow.length; i += 1) {
1702
+ const v = toShow[i];
1703
+ const filePath = path.join(whatsnewDir, `v${v}.md`);
1704
+ try {
1705
+ const content = await readFile(filePath, "utf8");
1706
+ console.log(content.trimEnd());
1707
+ console.log("");
1708
+ if (i === 0 && elidedCount > 0) {
1709
+ console.log(` ⋯ 中間 ${elidedCount} 個版本嘅 release notes 略;完整列表見 https://github.com/Adamchanadam/agent-handoff-kit/releases ⋯`);
1710
+ console.log("");
1711
+ }
1712
+ } catch {
1713
+ console.log(`(v${v} release notes 檔缺失,見 https://github.com/Adamchanadam/agent-handoff-kit/releases/tag/v${v})`);
1714
+ console.log("");
1715
+ }
1716
+ }
1717
+ console.log("------------------------------------------------------------");
1718
+ console.log("");
1719
+ }
1720
+
1468
1721
  // R-031 v0.3.1+: Upgrade no-op short-circuit. When the user runs upgrade on a root
1469
1722
  // already at latest version (skip all / create 0 / merge 0 / conflict 0), print a
1470
1723
  // short factual message and return. Saves disk (no migration report) + reduces noise
@@ -0,0 +1,13 @@
1
+ # v0.3.1
2
+
3
+ ## 本版新加咗咩
4
+
5
+ CLI 升級流程嘅 messaging 改進 —— 你升完或者第二次跑 upgrade 嗰陣會見到唔同 output。第二次跑 upgrade(零改動)會直接短訊「你已係最新版本」,唔再印「安裝完成」+ 新手起步句嘅完整 ceremony。
6
+
7
+ ## 對你已有檔案嘅影響
8
+
9
+ 完全冇影響。純 CLI source 改進,無 user-facing template 改動,doctor 對既有用戶仍 PASS。
10
+
11
+ ## 建議下一步
12
+
13
+ 跑 doctor confirm 健康即可。
@@ -0,0 +1,13 @@
1
+ # v0.3.2
2
+
3
+ ## 本版新加咗咩
4
+
5
+ Doctor 同 init 命令加入「項目狀態速覽」+「點 confirm 你裝啱咗」。Doctor 跑完會印你嘅版本對齊狀況(CLI / root template / npm latest 三向比較)、上次 closeout 距今幾耐、項目首次安裝距今幾耐。Init 完會印 mini-checklist 答「我裝啱咗嗎」嘅 anxiety,並講清本工具係 background harness(需要連住 AI tool 先見到實際 value)。Upgrade 完會直接 inline print 本版同跨版本嘅 whatsnew 摘要(即你而家睇緊呢段),唔等你 ask AI。
6
+
7
+ ## 對你已有檔案嘅影響
8
+
9
+ 完全冇影響。純 CLI source 改進,無 user-facing template 改動,doctor 對既有用戶仍 PASS。
10
+
11
+ ## 建議下一步
12
+
13
+ 跑 doctor confirm 健康,順便試吓本版新加嘅「項目狀態速覽」。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.1",
3
+ "version": "0.3.2",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -10,6 +10,7 @@
10
10
  "bin/",
11
11
  "runtime-core/",
12
12
  "packs/",
13
+ "docs/whatsnew/",
13
14
  "README.md",
14
15
  "LICENSE"
15
16
  ],