@adamchanadam/agent-handoff-kit 0.3.1 → 0.3.3

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.3` 已正式發佈到 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
 
@@ -467,6 +467,23 @@ async function runInstall(command, root, options, version) {
467
467
  return;
468
468
  }
469
469
 
470
+ // R-031.3 v0.3.3+: For upgrade scenarios, capture pre-upgrade root template version
471
+ // before the create/merge/inject loops mutate PROJECT_INDEX. This snapshot is later
472
+ // passed to printWhatsnew so the version range narrative reflects the actual user
473
+ // journey (v{pre-upgrade} → v{current CLI}), not the post-inject state which would
474
+ // make printWhatsnew see fromVersion == toVersion and skip the summary entirely.
475
+ let preUpgradeRootVersion = null;
476
+ if (command === "upgrade") {
477
+ try {
478
+ const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
479
+ const text = await readFile(indexPath, "utf8");
480
+ const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
481
+ if (m) preUpgradeRootVersion = m[1];
482
+ } catch {
483
+ // ignore
484
+ }
485
+ }
486
+
470
487
  printPlan(command, root, mode, plan, version);
471
488
 
472
489
  if (options.dryRun) {
@@ -498,6 +515,31 @@ async function runInstall(command, root, options, version) {
498
515
  created.push(item.targetRel);
499
516
  }
500
517
 
518
+ // R-031.3 v0.3.3+: Inject current CLI version into PROJECT_INDEX template version
519
+ // metadata row — triggers for both fresh install AND upgrade substantive scenarios.
520
+ // The metadata row tracks template structure version (maintainer-owned), distinct
521
+ // from user content rows (External Sources / Fact Base etc.) which R-016 protects.
522
+ // Without inject on upgrade, user just upgraded but doctor's "項目狀態速覽"
523
+ // immediately prints "root 落後 CLI" — contradicting the just-completed upgrade
524
+ // narrative. Compare-semver guard prevents downgrade overwrite (e.g. someone
525
+ // running an older CLI). User content rows are preserved untouched.
526
+ if (command === "upgrade" || created.includes("dev/PROJECT_INDEX.md")) {
527
+ const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
528
+ try {
529
+ const text = await readFile(indexPath, "utf8");
530
+ const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
531
+ if (m && isStableSemver(m[1]) && compareSemver(m[1], version) < 0) {
532
+ const updated = text.replace(
533
+ /\| Agent Handoff Kit template version \| [\d.]+ \|/,
534
+ `| Agent Handoff Kit template version | ${version} |`
535
+ );
536
+ await writeFile(indexPath, updated, "utf8");
537
+ }
538
+ } catch {
539
+ // ignore — doctor anchor (R-016) only checks row existence, not specific value.
540
+ }
541
+ }
542
+
501
543
  for (const item of plan) {
502
544
  if (item.action !== "merge") continue;
503
545
  const backupPath = path.join(backupDir, item.targetRel);
@@ -532,11 +574,12 @@ async function runInstall(command, root, options, version) {
532
574
  reportRel: path.relative(root, report)
533
575
  });
534
576
 
535
- // R-031 v0.3.1+: install vs upgrade narrative split. Upgrade substantive uses
536
- // "升級完成" framing (not "安裝完成") and offers optional review prompt instead of
537
- // pushing first-time onboarding canonical phrase.
577
+ // R-031 v0.3.1+: install vs upgrade narrative split.
578
+ // R-031.2 v0.3.2+: printUpgradeNextSteps async (awaits inline whatsnew print).
579
+ // R-031.3 v0.3.3+: pass preUpgradeRootVersion so whatsnew narrative reflects the
580
+ // actual user journey (v{pre-upgrade} → v{current}), not the post-inject state.
538
581
  if (command === "upgrade") {
539
- printUpgradeNextSteps(root, conflicts.length);
582
+ await printUpgradeNextSteps(root, conflicts.length, version, preUpgradeRootVersion);
540
583
  } else {
541
584
  printInstallNextSteps(root, conflicts.length);
542
585
  }
@@ -661,6 +704,18 @@ async function runDoctor(root, version, options = {}) {
661
704
  }
662
705
  }
663
706
 
707
+ // R-031.2 v0.3.2+: 項目狀態速覽 —— 三向 version 對比 + 距上次 closeout 幾耐 +
708
+ // 項目首次安裝距今幾耐。從用戶跑 doctor 嗰刻嘅 mental state 出發(confirm health /
709
+ // suspect drift / curious about version / continuity awareness),唔等用戶 ask AI。
710
+ console.log("");
711
+ console.log("項目狀態速覽:");
712
+ const versionAlignment = await assessVersionAlignment(root, version);
713
+ printVersionAlignment(versionAlignment);
714
+ const lastCloseout = await assessLastCloseout(root);
715
+ printLastCloseout(lastCloseout);
716
+ const projectAge = await assessProjectAge(root);
717
+ printProjectAge(projectAge);
718
+
664
719
  const overallHealthy = credentialResult.ok;
665
720
  printDoctorSummary(version, root, overallHealthy ? "healthy" : "needs-attention", {
666
721
  checked: rows.length + anchorRows.length + schemaRows.length + mirrorRows.length + 2,
@@ -989,6 +1044,137 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
989
1044
  return { ...base, action: "skip", reason: "preserve existing file" };
990
1045
  }
991
1046
 
1047
+ // R-031.2 v0.3.2+: Version alignment assessment for doctor "項目狀態速覽".
1048
+ // Compares CLI version (running), root template metadata version (in dev/PROJECT_INDEX.md),
1049
+ // and npm latest. Surfaces drift awareness because previous design relied on startup
1050
+ // maybePrintUpdateNotice which silently fails when npx auto-fetches latest (CLI version
1051
+ // equals npm latest, so the notice never triggers, leaving user root drift invisible).
1052
+ async function assessVersionAlignment(root, cliVersion) {
1053
+ const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
1054
+ let rootVersion = null;
1055
+ try {
1056
+ const text = await readFile(indexPath, "utf8");
1057
+ const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
1058
+ if (m) rootVersion = m[1];
1059
+ } catch {
1060
+ // file missing or unreadable; rootVersion stays null
1061
+ }
1062
+
1063
+ let npmLatest = null;
1064
+ try {
1065
+ npmLatest = await fetchLatestVersion();
1066
+ } catch {
1067
+ // network failure; npmLatest stays null
1068
+ }
1069
+
1070
+ return { cliVersion, rootVersion, npmLatest };
1071
+ }
1072
+
1073
+ function printVersionAlignment(result) {
1074
+ const { cliVersion, rootVersion, npmLatest } = result;
1075
+ if (rootVersion === null) {
1076
+ console.log(` 📦 版本:CLI v${cliVersion} / root metadata 缺失(曾經手動編輯?)/ npm latest ${npmLatest ? "v" + npmLatest : "無法查詢"}`);
1077
+ return;
1078
+ }
1079
+ if (npmLatest === null) {
1080
+ console.log(` 📦 版本:CLI v${cliVersion} / root v${rootVersion} / npm latest 無法查詢(網絡可能不通)`);
1081
+ return;
1082
+ }
1083
+ const aligned = cliVersion === rootVersion && rootVersion === npmLatest;
1084
+ if (aligned) {
1085
+ console.log(` 📦 版本:CLI / root / npm latest 三向對齊 v${cliVersion} ✅`);
1086
+ return;
1087
+ }
1088
+ console.log(` 📦 版本:CLI v${cliVersion} / root v${rootVersion} / npm latest v${npmLatest}`);
1089
+ if (npmLatest && compareSemver(npmLatest, cliVersion) > 0) {
1090
+ console.log(` npm 有新版(v${npmLatest});可執行:npx @adamchanadam/agent-handoff-kit@latest upgrade`);
1091
+ } else if (cliVersion !== rootVersion) {
1092
+ console.log(` 你 root template metadata 同 CLI 唔對齊;兩個版本仍相容 doctor 仍 PASS;如想對齊:npx @adamchanadam/agent-handoff-kit@latest upgrade`);
1093
+ }
1094
+ }
1095
+
1096
+ // R-031.2 v0.3.2+: Last closeout assessment. Reads dev/SESSION_HANDOFF.md "Last Updated:"
1097
+ // line (strict format, reliable). Falls back to dev/SESSION_LOG.md first H2 date if
1098
+ // HANDOFF missing or unparseable.
1099
+ async function assessLastCloseout(root) {
1100
+ const handoffPath = path.join(root, "dev/SESSION_HANDOFF.md");
1101
+ let date = null;
1102
+ try {
1103
+ const text = await readFile(handoffPath, "utf8");
1104
+ const m = text.match(/Last Updated:\s*(\d{4}-\d{2}-\d{2})/);
1105
+ if (m) date = m[1];
1106
+ } catch {
1107
+ // ignore
1108
+ }
1109
+
1110
+ if (!date) {
1111
+ const logPath = path.join(root, "dev/SESSION_LOG.md");
1112
+ try {
1113
+ const text = await readFile(logPath, "utf8");
1114
+ const m = text.match(/^## (\d{4}-\d{2}-\d{2})/m);
1115
+ if (m) date = m[1];
1116
+ } catch {
1117
+ // ignore
1118
+ }
1119
+ }
1120
+
1121
+ return { date };
1122
+ }
1123
+
1124
+ function printLastCloseout(result) {
1125
+ if (!result.date) {
1126
+ console.log(" 📅 上次 closeout:(仲未 closeout 過。第一次完成 task 後可以講 AI「收工」)");
1127
+ return;
1128
+ }
1129
+ const today = new Date();
1130
+ const closeout = new Date(result.date);
1131
+ const daysDiff = Math.floor((today - closeout) / (1000 * 60 * 60 * 24));
1132
+ if (daysDiff < 0) {
1133
+ console.log(` 📅 上次 closeout:${result.date}(日期超前?檢查系統時鐘)`);
1134
+ } else if (daysDiff === 0) {
1135
+ console.log(` 📅 上次 closeout:今日(${result.date})`);
1136
+ } else if (daysDiff <= 30) {
1137
+ console.log(` 📅 上次 closeout:${daysDiff} 日前(${result.date})`);
1138
+ } else {
1139
+ console.log(` 📅 上次 closeout:${daysDiff} 日前(${result.date})— 建議跑下 closeout 整理進度`);
1140
+ }
1141
+ }
1142
+
1143
+ // R-031.2 v0.3.2+: Project age assessment. Reads the oldest folder timestamp in
1144
+ // dev/governance_migrations/ which records the first install date. Read-only; doctor
1145
+ // remains side-effect-free (no new write logic).
1146
+ async function assessProjectAge(root) {
1147
+ const migrationsDir = path.join(root, "dev/governance_migrations");
1148
+ try {
1149
+ const entries = await readdir(migrationsDir);
1150
+ const timestamps = entries.filter((name) => /^\d{8}T\d{6}Z$/.test(name)).sort();
1151
+ if (timestamps.length === 0) return { firstInstall: null };
1152
+ const oldest = timestamps[0];
1153
+ // Format: 20260423T112233Z → 2026-04-23
1154
+ const year = oldest.slice(0, 4);
1155
+ const month = oldest.slice(4, 6);
1156
+ const day = oldest.slice(6, 8);
1157
+ return { firstInstall: `${year}-${month}-${day}` };
1158
+ } catch {
1159
+ return { firstInstall: null };
1160
+ }
1161
+ }
1162
+
1163
+ function printProjectAge(result) {
1164
+ if (!result.firstInstall) {
1165
+ console.log(" 🌱 項目首次安裝距今:未知(dev/governance_migrations/ 未有 timestamp)");
1166
+ return;
1167
+ }
1168
+ const today = new Date();
1169
+ const firstInstall = new Date(result.firstInstall);
1170
+ const daysDiff = Math.floor((today - firstInstall) / (1000 * 60 * 60 * 24));
1171
+ if (daysDiff === 0) {
1172
+ console.log(` 🌱 項目首次安裝距今:今日(${result.firstInstall})`);
1173
+ } else {
1174
+ console.log(` 🌱 項目首次安裝距今:${daysDiff} 日(自 ${result.firstInstall})`);
1175
+ }
1176
+ }
1177
+
992
1178
  // R-010 SESSION_LOG handoff-role discipline (warn-only doctor check).
993
1179
  // Returns { ok, warnings } where:
994
1180
  // - ok: true if no warnings triggered
@@ -1423,6 +1609,19 @@ function printInstallNextSteps(root, conflictCount) {
1423
1609
  console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
1424
1610
  console.log("");
1425
1611
  }
1612
+ // R-031.2 v0.3.2+: 「點 confirm 你裝啱咗」mini-checklist,直接答用戶第一次安裝後嘅
1613
+ // anxiety「我裝啱咗嗎」。三個具體 verify step + 一句講清本工具係 background harness
1614
+ // (冇 GUI、冇 server、需要連住 AI tool 先見到實際 value)。
1615
+ console.log("📋 點 confirm 你裝啱咗:");
1616
+ console.log("");
1617
+ console.log(" 1. 跑 npx @adamchanadam/agent-handoff-kit doctor 應該見到「status: passed」");
1618
+ console.log(" 2. 你 dev/ folder 應該有起碼 14 個檔(rules / SESSION_HANDOFF / SESSION_LOG 等)");
1619
+ console.log(" 3. 喺你 AI tool(Claude Code / Codex / Gemini)開新對話,貼下面起步句先見到實際 value");
1620
+ console.log("");
1621
+ console.log("⚠️ 注意:Agent Handoff Kit 只係 background harness —— 喺你 project folder 入面嘅幾類檔案。");
1622
+ console.log(" 冇 GUI、唔 run server、唔自動做嘢。你需要連住至少一個 AI tool 嘅對話,AI 先會讀依啲檔案做正事。");
1623
+ console.log("");
1624
+ console.log("------------------------------------------------------------");
1426
1625
  console.log("⚠️ 請注意:下面文字不是 Terminal 指令。");
1427
1626
  console.log("📋 請打開你要使用的 AI 工具,新增一段對話,貼上下面一句:");
1428
1627
  console.log("------------------------------------------------------------");
@@ -1443,7 +1642,7 @@ function printInstallNextSteps(root, conflictCount) {
1443
1642
  // R-031 v0.3.1+: Upgrade substantive next-step block. Distinct from install
1444
1643
  // (`printInstallNextSteps`) because the user is not first-time; pushing them through
1445
1644
  // the onboarding canonical phrase resets context they already have.
1446
- function printUpgradeNextSteps(root, conflictCount) {
1645
+ async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRootVersion) {
1447
1646
  console.log("");
1448
1647
  console.log("============================================================");
1449
1648
  console.log("✅ 升級完成:管治架構檔案已更新到最新版本");
@@ -1454,6 +1653,12 @@ function printUpgradeNextSteps(root, conflictCount) {
1454
1653
  console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
1455
1654
  console.log("");
1456
1655
  }
1656
+ // R-031.2 v0.3.2+: Inline whatsnew summary — directly surface what changed in this
1657
+ // version (and any intermediate versions the user skipped).
1658
+ // R-031.3 v0.3.3+: fromVersion now uses pre-upgrade snapshot (captured before
1659
+ // inject mutated PROJECT_INDEX), so the range narrative reflects actual user
1660
+ // journey instead of degenerate v{current} → v{current}.
1661
+ await printWhatsnew(root, version, preUpgradeRootVersion);
1457
1662
  console.log("📋 如你正在進行中的工作 session 已熟悉 Agent Handoff Kit,繼續使用原本的開工方式即可,無需重新做新手引導。");
1458
1663
  console.log("");
1459
1664
  console.log("💡 如想了解本版本新加了甚麼功能,可選用以下開工句(非強制):");
@@ -1465,6 +1670,95 @@ function printUpgradeNextSteps(root, conflictCount) {
1465
1670
  console.log("============================================================");
1466
1671
  }
1467
1672
 
1673
+ // R-031.2 v0.3.2+: Print whatsnew summaries for the version range crossed by this
1674
+ // upgrade. fromVersion = user root template metadata version (the state before
1675
+ // upgrade; R-016 preserves this row so it still reflects the prior state after
1676
+ // upgrade finishes). toVersion = current CLI version. Range is exclusive-fromVersion
1677
+ // inclusive-toVersion. Limit to first + last when crossing > 3 versions (elide middle).
1678
+ async function printWhatsnew(root, toVersion, fromVersionOverride) {
1679
+ // R-031.3 v0.3.3+: fromVersion sourced from explicit override (pre-upgrade snapshot)
1680
+ // when called from upgrade flow; falls back to reading current PROJECT_INDEX
1681
+ // template version row otherwise.
1682
+ let fromVersion = fromVersionOverride ?? null;
1683
+ if (!fromVersion) {
1684
+ const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
1685
+ try {
1686
+ const text = await readFile(indexPath, "utf8");
1687
+ const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
1688
+ if (m) fromVersion = m[1];
1689
+ } catch {
1690
+ return;
1691
+ }
1692
+ }
1693
+ if (!fromVersion || !isStableSemver(fromVersion) || compareSemver(fromVersion, toVersion) >= 0) {
1694
+ return;
1695
+ }
1696
+
1697
+ const whatsnewDir = path.join(packageRoot, "docs/whatsnew");
1698
+ let entries = [];
1699
+ try {
1700
+ entries = await readdir(whatsnewDir);
1701
+ } catch {
1702
+ console.log(`💡 本版 release notes:https://github.com/Adamchanadam/agent-handoff-kit/releases/tag/v${toVersion}`);
1703
+ console.log("");
1704
+ return;
1705
+ }
1706
+
1707
+ const relevant = entries
1708
+ .filter((name) => /^v\d+\.\d+\.\d+\.md$/.test(name))
1709
+ .map((name) => name.replace(/^v/, "").replace(/\.md$/, ""))
1710
+ .filter((v) => compareSemver(v, fromVersion) > 0 && compareSemver(v, toVersion) <= 0)
1711
+ .sort((a, b) => compareSemver(a, b));
1712
+
1713
+ if (relevant.length === 0) {
1714
+ console.log(`💡 本版 release notes:https://github.com/Adamchanadam/agent-handoff-kit/releases`);
1715
+ console.log(` (v${fromVersion} → v${toVersion} 跨版本嘅完整變更見 GitHub Release 全列表)`);
1716
+ console.log("");
1717
+ return;
1718
+ }
1719
+
1720
+ // R-031.3 v0.3.3+: Deep range narrative — if fromVersion considerably older than
1721
+ // the oldest available whatsnew, explicitly tell user this is a multi-version
1722
+ // upgrade where older changelog only lives on GitHub Release (not shipped).
1723
+ // Heuristic: deep range if fromVersion's major < oldest's major, or same major
1724
+ // but minor differs by ≥ 1 (i.e. fromVersion is at least one minor release older
1725
+ // than the oldest available whatsnew).
1726
+ const oldestAvailable = relevant[0];
1727
+ const [fromMajor, fromMinor] = fromVersion.split(".").map((n) => Number.parseInt(n, 10));
1728
+ const [oldMajor, oldMinor] = oldestAvailable.split(".").map((n) => Number.parseInt(n, 10));
1729
+ const isDeepRange = (fromMajor < oldMajor) || (fromMajor === oldMajor && fromMinor < oldMinor);
1730
+ if (isDeepRange) {
1731
+ console.log(`💡 注意:本次升級 v${fromVersion} → v${toVersion} 跨度較大;本工具 release notes 庫只 cover 由 v${oldestAvailable} 起嘅 ${relevant.length} 個版本。較舊版本(v${fromVersion} 至 v${oldestAvailable} 之前)嘅完整變更見:`);
1732
+ console.log(` https://github.com/Adamchanadam/agent-handoff-kit/releases`);
1733
+ console.log("");
1734
+ }
1735
+
1736
+ console.log(`📰 本次升級涵蓋 ${relevant.length} 個版本嘅 release notes(${isDeepRange ? `由 v${oldestAvailable} 起` : `v${fromVersion} → v${toVersion}`}):`);
1737
+ console.log("");
1738
+
1739
+ const toShow = relevant.length <= 3 ? relevant : [relevant[0], relevant[relevant.length - 1]];
1740
+ const elidedCount = relevant.length > 3 ? relevant.length - 2 : 0;
1741
+
1742
+ for (let i = 0; i < toShow.length; i += 1) {
1743
+ const v = toShow[i];
1744
+ const filePath = path.join(whatsnewDir, `v${v}.md`);
1745
+ try {
1746
+ const content = await readFile(filePath, "utf8");
1747
+ console.log(content.trimEnd());
1748
+ console.log("");
1749
+ if (i === 0 && elidedCount > 0) {
1750
+ console.log(` ⋯ 中間 ${elidedCount} 個版本嘅 release notes 略;完整列表見 https://github.com/Adamchanadam/agent-handoff-kit/releases ⋯`);
1751
+ console.log("");
1752
+ }
1753
+ } catch {
1754
+ console.log(`(v${v} release notes 檔缺失,見 https://github.com/Adamchanadam/agent-handoff-kit/releases/tag/v${v})`);
1755
+ console.log("");
1756
+ }
1757
+ }
1758
+ console.log("------------------------------------------------------------");
1759
+ console.log("");
1760
+ }
1761
+
1468
1762
  // R-031 v0.3.1+: Upgrade no-op short-circuit. When the user runs upgrade on a root
1469
1763
  // already at latest version (skip all / create 0 / merge 0 / conflict 0), print a
1470
1764
  // 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 健康,順便試吓本版新加嘅「項目狀態速覽」。
@@ -0,0 +1,13 @@
1
+ # v0.3.3
2
+
3
+ ## 本版新加咗咩
4
+
5
+ 修補 v0.3.2 用戶實測揭發嘅兩個 narrative coherence bug。升級流程之後 doctor 唔再矛盾講「root 落後 CLI,建議 upgrade」——升完就對齊。跨多版本嘅升級(譬如 v0.1.x 直接升 v0.3.3),whatsnew summary 會明文話你跨度較大,並指你睇 GitHub Release 攞較舊版本嘅完整變更。
6
+
7
+ ## 對你已有檔案嘅影響
8
+
9
+ 完全冇影響 user content。Upgrade 之後 `dev/PROJECT_INDEX.md` 嘅「Agent Handoff Kit template version」一行會自動 update 為當前 CLI 版本(呢一行屬 template metadata,唔屬你填嘅內容);其他 row(譬如 External Sources、Fact Base、Workspace Identity)保持不變。
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.3",
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
  ],