@adamchanadam/agent-handoff-kit 0.3.2 → 0.3.4

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.4` 已正式發佈到 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
 
@@ -434,6 +434,25 @@ function parseArgs(args) {
434
434
  return { command, options };
435
435
  }
436
436
 
437
+ // R-031.3 v0.3.4+: Helper to detect if PROJECT_INDEX template version metadata
438
+ // row is stale relative to current CLI version. Used by plan-time no-op detection
439
+ // guard to ensure metadata-only stale roots still trigger the upgrade ceremony
440
+ // (otherwise plan-time short-circuit returns before inject can run).
441
+ async function needsProjectIndexVersionInject(root, command, version) {
442
+ if (command !== "upgrade") return false;
443
+ try {
444
+ const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
445
+ const text = await readFile(indexPath, "utf8");
446
+ const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
447
+ if (m && isStableSemver(m[1]) && compareSemver(m[1], version) < 0) {
448
+ return true;
449
+ }
450
+ } catch {
451
+ // ignore — silent if PROJECT_INDEX missing or unreadable
452
+ }
453
+ return false;
454
+ }
455
+
437
456
  async function runInstall(command, root, options, version) {
438
457
  const mode = await detectMode(root);
439
458
  const plan = await buildPlan(root, command);
@@ -446,10 +465,17 @@ async function runInstall(command, root, options, version) {
446
465
  const planMergeCount = plan.filter((item) => item.action === "merge").length;
447
466
  const planConflictCount = plan.filter((item) => item.action === "conflict").length;
448
467
  const planSkipCount = plan.filter((item) => item.action === "skip").length;
468
+ // R-031.3 v0.3.4+: metadata-only stale guard. If PROJECT_INDEX template version
469
+ // row is stale but structure is fully current (all v0.2.0+ files already present),
470
+ // plan create/merge/conflict are all 0 — but inject still needs to run. Without
471
+ // this guard, plan-time short-circuit returns before inject can fire, leaving
472
+ // root on stale version forever.
473
+ const projectIndexVersionNeedsInject = await needsProjectIndexVersionInject(root, command, version);
449
474
  const isUpgradeNoopAtPlanTime = command === "upgrade"
450
475
  && planCreateCount === 0
451
476
  && planMergeCount === 0
452
- && planConflictCount === 0;
477
+ && planConflictCount === 0
478
+ && !projectIndexVersionNeedsInject;
453
479
 
454
480
  if (isUpgradeNoopAtPlanTime) {
455
481
  printCard(version, "continuity ready", "o.o");
@@ -467,6 +493,23 @@ async function runInstall(command, root, options, version) {
467
493
  return;
468
494
  }
469
495
 
496
+ // R-031.3 v0.3.3+: For upgrade scenarios, capture pre-upgrade root template version
497
+ // before the create/merge/inject loops mutate PROJECT_INDEX. This snapshot is later
498
+ // passed to printWhatsnew so the version range narrative reflects the actual user
499
+ // journey (v{pre-upgrade} → v{current CLI}), not the post-inject state which would
500
+ // make printWhatsnew see fromVersion == toVersion and skip the summary entirely.
501
+ let preUpgradeRootVersion = null;
502
+ if (command === "upgrade") {
503
+ try {
504
+ const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
505
+ const text = await readFile(indexPath, "utf8");
506
+ const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
507
+ if (m) preUpgradeRootVersion = m[1];
508
+ } catch {
509
+ // ignore
510
+ }
511
+ }
512
+
470
513
  printPlan(command, root, mode, plan, version);
471
514
 
472
515
  if (options.dryRun) {
@@ -498,12 +541,25 @@ async function runInstall(command, root, options, version) {
498
541
  created.push(item.targetRel);
499
542
  }
500
543
 
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")) {
544
+ for (const item of plan) {
545
+ if (item.action !== "merge") continue;
546
+ const backupPath = path.join(backupDir, item.targetRel);
547
+ await mkdir(path.dirname(backupPath), { recursive: true });
548
+ await copyFile(item.targetAbs, backupPath);
549
+ await writeFile(item.targetAbs, item.mergedText, "utf8");
550
+ merged.push(item.targetRel);
551
+ }
552
+
553
+ // R-031.3 v0.3.4+: Inject current CLI version into PROJECT_INDEX template version
554
+ // metadata row — placed AFTER the merge loop to avoid the ordering bug where merge
555
+ // overwrites inject. Merge writes item.mergedText computed at plan-build phase
556
+ // (which contains the pre-inject stale version row); if inject ran before merge,
557
+ // merge would silently revert it. R-016 still protected: only the metadata row
558
+ // mutates, user content rows (External Sources / Fact Base etc.) preserved.
559
+ // The captured metadataUpdated object is passed to writeMigrationReport so the
560
+ // audit trail records this mutation alongside file create/merge operations.
561
+ let metadataUpdated = null;
562
+ if (command === "upgrade" || created.includes("dev/PROJECT_INDEX.md")) {
507
563
  const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
508
564
  try {
509
565
  const text = await readFile(indexPath, "utf8");
@@ -514,38 +570,39 @@ async function runInstall(command, root, options, version) {
514
570
  `| Agent Handoff Kit template version | ${version} |`
515
571
  );
516
572
  await writeFile(indexPath, updated, "utf8");
573
+ metadataUpdated = {
574
+ file: "dev/PROJECT_INDEX.md",
575
+ field: "Agent Handoff Kit template version",
576
+ from: m[1],
577
+ to: version
578
+ };
517
579
  }
518
580
  } 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.
581
+ // ignore — doctor anchor (R-016) only checks row existence, not specific value.
521
582
  }
522
583
  }
523
584
 
524
- for (const item of plan) {
525
- if (item.action !== "merge") continue;
526
- const backupPath = path.join(backupDir, item.targetRel);
527
- await mkdir(path.dirname(backupPath), { recursive: true });
528
- await copyFile(item.targetAbs, backupPath);
529
- await writeFile(item.targetAbs, item.mergedText, "utf8");
530
- merged.push(item.targetRel);
531
- }
532
-
533
585
  const skippedCount = plan.filter((item) => item.action === "skip").length;
534
586
 
535
587
  // R-031 v0.3.1+: scenario branching. Upgrade no-op (零改動) short-circuits — skip
536
588
  // migration report, self-check doctor, install banner, onboarding canonical phrase.
537
589
  // Prevents misleading "安裝完成" framing when user is just verifying they are latest.
590
+ // R-031.3 v0.3.4+: also short-circuit only when metadata is current. If only the
591
+ // metadata row was stale (counts 0/0/0 but metadataUpdated truthy), user just
592
+ // received a substantive upgrade — proceed through full ceremony so doctor
593
+ // self-check confirms the inject result.
538
594
  const isUpgradeNoop = command === "upgrade"
539
595
  && created.length === 0
540
596
  && merged.length === 0
541
- && conflicts.length === 0;
597
+ && conflicts.length === 0
598
+ && !metadataUpdated;
542
599
 
543
600
  if (isUpgradeNoop) {
544
601
  printUpgradeNoopShortCircuit(version);
545
602
  return;
546
603
  }
547
604
 
548
- const report = await writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir);
605
+ const report = await writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir, metadataUpdated);
549
606
  printInstallSummary(version, command, mode, root, {
550
607
  created: created.length,
551
608
  merged: merged.length,
@@ -555,12 +612,12 @@ async function runInstall(command, root, options, version) {
555
612
  reportRel: path.relative(root, report)
556
613
  });
557
614
 
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).
615
+ // R-031 v0.3.1+: install vs upgrade narrative split.
616
+ // R-031.2 v0.3.2+: printUpgradeNextSteps async (awaits inline whatsnew print).
617
+ // R-031.3 v0.3.3+: pass preUpgradeRootVersion so whatsnew narrative reflects the
618
+ // actual user journey (v{pre-upgrade} → v{current}), not the post-inject state.
562
619
  if (command === "upgrade") {
563
- await printUpgradeNextSteps(root, conflicts.length, version);
620
+ await printUpgradeNextSteps(root, conflicts.length, version, preUpgradeRootVersion);
564
621
  } else {
565
622
  printInstallNextSteps(root, conflicts.length);
566
623
  }
@@ -1441,7 +1498,7 @@ async function confirmWrite() {
1441
1498
  }
1442
1499
  }
1443
1500
 
1444
- async function writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir) {
1501
+ async function writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir, metadataUpdated = null) {
1445
1502
  const reportPath = path.join(migrationDir, "migration-report.md");
1446
1503
  await mkdir(migrationDir, { recursive: true });
1447
1504
  const skipped = plan.filter((item) => item.action === "skip").map((item) => item.targetRel);
@@ -1465,12 +1522,22 @@ async function writeMigrationReport(root, command, mode, plan, created, merged,
1465
1522
  "## Conflicts",
1466
1523
  ...listOrNone(conflicts.map((item) => `${item.targetRel} - ${item.reason}`)),
1467
1524
  "",
1525
+ // R-031.3 v0.3.4+: metadata updates are tracked separately from file create/merge
1526
+ // because they mutate specific rows inside an otherwise user-owned file rather
1527
+ // than replacing or merging the file as a whole. Audit trail completeness
1528
+ // requires this section even when create/merge/conflict counts are all 0.
1529
+ "## Metadata Updates",
1530
+ metadataUpdated
1531
+ ? `- ${metadataUpdated.file}: ${metadataUpdated.field} ${metadataUpdated.from} → ${metadataUpdated.to}`
1532
+ : "- none",
1533
+ "",
1468
1534
  "## Backup",
1469
1535
  merged.length > 0 ? `- ${path.relative(root, backupDir)}` : "- none",
1470
1536
  "",
1471
1537
  "## Notes",
1472
1538
  "- Existing files are preserved unless the installer can perform a bounded merge.",
1473
- "- Files that cannot be safely merged are reported as conflicts and are not overwritten."
1539
+ "- Files that cannot be safely merged are reported as conflicts and are not overwritten.",
1540
+ "- Metadata Updates section tracks row-level mutations (R-031.3) distinct from file-level changes."
1474
1541
  ].join("\n");
1475
1542
  await writeFile(reportPath, `${text}\n`, "utf8");
1476
1543
  return reportPath;
@@ -1623,7 +1690,7 @@ function printInstallNextSteps(root, conflictCount) {
1623
1690
  // R-031 v0.3.1+: Upgrade substantive next-step block. Distinct from install
1624
1691
  // (`printInstallNextSteps`) because the user is not first-time; pushing them through
1625
1692
  // the onboarding canonical phrase resets context they already have.
1626
- async function printUpgradeNextSteps(root, conflictCount, version) {
1693
+ async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRootVersion) {
1627
1694
  console.log("");
1628
1695
  console.log("============================================================");
1629
1696
  console.log("✅ 升級完成:管治架構檔案已更新到最新版本");
@@ -1635,10 +1702,11 @@ async function printUpgradeNextSteps(root, conflictCount, version) {
1635
1702
  console.log("");
1636
1703
  }
1637
1704
  // 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);
1705
+ // version (and any intermediate versions the user skipped).
1706
+ // R-031.3 v0.3.3+: fromVersion now uses pre-upgrade snapshot (captured before
1707
+ // inject mutated PROJECT_INDEX), so the range narrative reflects actual user
1708
+ // journey instead of degenerate v{current} → v{current}.
1709
+ await printWhatsnew(root, version, preUpgradeRootVersion);
1642
1710
  console.log("📋 如你正在進行中的工作 session 已熟悉 Agent Handoff Kit,繼續使用原本的開工方式即可,無需重新做新手引導。");
1643
1711
  console.log("");
1644
1712
  console.log("💡 如想了解本版本新加了甚麼功能,可選用以下開工句(非強制):");
@@ -1655,15 +1723,20 @@ async function printUpgradeNextSteps(root, conflictCount, version) {
1655
1723
  // upgrade; R-016 preserves this row so it still reflects the prior state after
1656
1724
  // upgrade finishes). toVersion = current CLI version. Range is exclusive-fromVersion
1657
1725
  // 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;
1726
+ async function printWhatsnew(root, toVersion, fromVersionOverride) {
1727
+ // R-031.3 v0.3.3+: fromVersion sourced from explicit override (pre-upgrade snapshot)
1728
+ // when called from upgrade flow; falls back to reading current PROJECT_INDEX
1729
+ // template version row otherwise.
1730
+ let fromVersion = fromVersionOverride ?? null;
1731
+ if (!fromVersion) {
1732
+ const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
1733
+ try {
1734
+ const text = await readFile(indexPath, "utf8");
1735
+ const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
1736
+ if (m) fromVersion = m[1];
1737
+ } catch {
1738
+ return;
1739
+ }
1667
1740
  }
1668
1741
  if (!fromVersion || !isStableSemver(fromVersion) || compareSemver(fromVersion, toVersion) >= 0) {
1669
1742
  return;
@@ -1692,7 +1765,23 @@ async function printWhatsnew(root, toVersion) {
1692
1765
  return;
1693
1766
  }
1694
1767
 
1695
- console.log(`📰 本次升級(v${fromVersion} → v${toVersion})涵蓋 ${relevant.length} 個版本嘅 release notes:`);
1768
+ // R-031.3 v0.3.3+: Deep range narrative — if fromVersion considerably older than
1769
+ // the oldest available whatsnew, explicitly tell user this is a multi-version
1770
+ // upgrade where older changelog only lives on GitHub Release (not shipped).
1771
+ // Heuristic: deep range if fromVersion's major < oldest's major, or same major
1772
+ // but minor differs by ≥ 1 (i.e. fromVersion is at least one minor release older
1773
+ // than the oldest available whatsnew).
1774
+ const oldestAvailable = relevant[0];
1775
+ const [fromMajor, fromMinor] = fromVersion.split(".").map((n) => Number.parseInt(n, 10));
1776
+ const [oldMajor, oldMinor] = oldestAvailable.split(".").map((n) => Number.parseInt(n, 10));
1777
+ const isDeepRange = (fromMajor < oldMajor) || (fromMajor === oldMajor && fromMinor < oldMinor);
1778
+ if (isDeepRange) {
1779
+ console.log(`💡 注意:本次升級 v${fromVersion} → v${toVersion} 跨度較大;本工具 release notes 庫只 cover 由 v${oldestAvailable} 起嘅 ${relevant.length} 個版本。較舊版本(v${fromVersion} 至 v${oldestAvailable} 之前)嘅完整變更見:`);
1780
+ console.log(` https://github.com/Adamchanadam/agent-handoff-kit/releases`);
1781
+ console.log("");
1782
+ }
1783
+
1784
+ console.log(`📰 本次升級涵蓋 ${relevant.length} 個版本嘅 release notes(${isDeepRange ? `由 v${oldestAvailable} 起` : `v${fromVersion} → v${toVersion}`}):`);
1696
1785
  console.log("");
1697
1786
 
1698
1787
  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 健康即可。
@@ -0,0 +1,17 @@
1
+ # v0.3.4
2
+
3
+ ## 本版新加咗咩
4
+
5
+ 本版修補升級後版本敘事不一致的問題。既有專案執行 `upgrade` 後,`dev/PROJECT_INDEX.md` 內的「Agent Handoff Kit template version」資料列會在合併完成後再更新為目前 CLI 版本,避免先更新、後又被舊合併結果覆蓋。
6
+
7
+ 升級工具也會辨認「只有版本資料列過期」的情況。即使沒有新增檔案、沒有合併檔案、沒有衝突,只要這一列仍是舊版本,就不會誤報「已經是最新版本,沒有檔案需要建立或合併」。
8
+
9
+ ## 對你已有檔案嘅影響
10
+
11
+ 本版只會更新 `dev/PROJECT_INDEX.md` 的 template version metadata。這一列屬工具維護的模板資料,不是你填寫的項目內容。你在 External Sources、Fact Base、Workspace Identity 等表格中填過的內容仍會保留。
12
+
13
+ 升級紀錄也新增 metadata section,會寫明這次是否更新了版本資料列,方便日後追溯。
14
+
15
+ ## 建議下一步
16
+
17
+ 執行 `upgrade` 後再執行 `doctor`。若 `doctor` 顯示 `status: passed`,並且項目狀態速覽不再提示 root 落後 CLI,即代表這次熱修已生效。
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.4",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {