@adamchanadam/agent-handoff-kit 0.3.2 → 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.2` 已正式發佈到 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
 
@@ -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,12 +515,15 @@ async function runInstall(command, root, options, version) {
498
515
  created.push(item.targetRel);
499
516
  }
500
517
 
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")) {
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")) {
507
527
  const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
508
528
  try {
509
529
  const text = await readFile(indexPath, "utf8");
@@ -516,8 +536,7 @@ async function runInstall(command, root, options, version) {
516
536
  await writeFile(indexPath, updated, "utf8");
517
537
  }
518
538
  } 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.
539
+ // ignore — doctor anchor (R-016) only checks row existence, not specific value.
521
540
  }
522
541
  }
523
542
 
@@ -555,12 +574,12 @@ async function runInstall(command, root, options, version) {
555
574
  reportRel: path.relative(root, report)
556
575
  });
557
576
 
558
- // R-031 v0.3.1+: install vs upgrade narrative split. Upgrade substantive uses
559
- // "升級完成" framing (not "安裝完成") and offers optional review prompt instead of
560
- // pushing first-time onboarding canonical phrase.
561
- // R-031.2 v0.3.2+: printUpgradeNextSteps now async (awaits inline whatsnew print).
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.
562
581
  if (command === "upgrade") {
563
- await printUpgradeNextSteps(root, conflicts.length, version);
582
+ await printUpgradeNextSteps(root, conflicts.length, version, preUpgradeRootVersion);
564
583
  } else {
565
584
  printInstallNextSteps(root, conflicts.length);
566
585
  }
@@ -1623,7 +1642,7 @@ function printInstallNextSteps(root, conflictCount) {
1623
1642
  // R-031 v0.3.1+: Upgrade substantive next-step block. Distinct from install
1624
1643
  // (`printInstallNextSteps`) because the user is not first-time; pushing them through
1625
1644
  // the onboarding canonical phrase resets context they already have.
1626
- async function printUpgradeNextSteps(root, conflictCount, version) {
1645
+ async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRootVersion) {
1627
1646
  console.log("");
1628
1647
  console.log("============================================================");
1629
1648
  console.log("✅ 升級完成:管治架構檔案已更新到最新版本");
@@ -1635,10 +1654,11 @@ async function printUpgradeNextSteps(root, conflictCount, version) {
1635
1654
  console.log("");
1636
1655
  }
1637
1656
  // 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);
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);
1642
1662
  console.log("📋 如你正在進行中的工作 session 已熟悉 Agent Handoff Kit,繼續使用原本的開工方式即可,無需重新做新手引導。");
1643
1663
  console.log("");
1644
1664
  console.log("💡 如想了解本版本新加了甚麼功能,可選用以下開工句(非強制):");
@@ -1655,15 +1675,20 @@ async function printUpgradeNextSteps(root, conflictCount, version) {
1655
1675
  // upgrade; R-016 preserves this row so it still reflects the prior state after
1656
1676
  // upgrade finishes). toVersion = current CLI version. Range is exclusive-fromVersion
1657
1677
  // 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;
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
+ }
1667
1692
  }
1668
1693
  if (!fromVersion || !isStableSemver(fromVersion) || compareSemver(fromVersion, toVersion) >= 0) {
1669
1694
  return;
@@ -1692,7 +1717,23 @@ async function printWhatsnew(root, toVersion) {
1692
1717
  return;
1693
1718
  }
1694
1719
 
1695
- console.log(`📰 本次升級(v${fromVersion} → v${toVersion})涵蓋 ${relevant.length} 個版本嘅 release notes:`);
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}`}):`);
1696
1737
  console.log("");
1697
1738
 
1698
1739
  const toShow = relevant.length <= 3 ? relevant : [relevant[0], relevant[relevant.length - 1]];
@@ -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.2",
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": {