@adamchanadam/agent-handoff-kit 0.3.3 → 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.3` 已正式發佈到 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");
@@ -515,14 +541,24 @@ async function runInstall(command, root, options, version) {
515
541
  created.push(item.targetRel);
516
542
  }
517
543
 
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.
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;
526
562
  if (command === "upgrade" || created.includes("dev/PROJECT_INDEX.md")) {
527
563
  const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
528
564
  try {
@@ -534,37 +570,39 @@ async function runInstall(command, root, options, version) {
534
570
  `| Agent Handoff Kit template version | ${version} |`
535
571
  );
536
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
+ };
537
579
  }
538
580
  } catch {
539
581
  // ignore — doctor anchor (R-016) only checks row existence, not specific value.
540
582
  }
541
583
  }
542
584
 
543
- for (const item of plan) {
544
- if (item.action !== "merge") continue;
545
- const backupPath = path.join(backupDir, item.targetRel);
546
- await mkdir(path.dirname(backupPath), { recursive: true });
547
- await copyFile(item.targetAbs, backupPath);
548
- await writeFile(item.targetAbs, item.mergedText, "utf8");
549
- merged.push(item.targetRel);
550
- }
551
-
552
585
  const skippedCount = plan.filter((item) => item.action === "skip").length;
553
586
 
554
587
  // R-031 v0.3.1+: scenario branching. Upgrade no-op (零改動) short-circuits — skip
555
588
  // migration report, self-check doctor, install banner, onboarding canonical phrase.
556
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.
557
594
  const isUpgradeNoop = command === "upgrade"
558
595
  && created.length === 0
559
596
  && merged.length === 0
560
- && conflicts.length === 0;
597
+ && conflicts.length === 0
598
+ && !metadataUpdated;
561
599
 
562
600
  if (isUpgradeNoop) {
563
601
  printUpgradeNoopShortCircuit(version);
564
602
  return;
565
603
  }
566
604
 
567
- 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);
568
606
  printInstallSummary(version, command, mode, root, {
569
607
  created: created.length,
570
608
  merged: merged.length,
@@ -1460,7 +1498,7 @@ async function confirmWrite() {
1460
1498
  }
1461
1499
  }
1462
1500
 
1463
- 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) {
1464
1502
  const reportPath = path.join(migrationDir, "migration-report.md");
1465
1503
  await mkdir(migrationDir, { recursive: true });
1466
1504
  const skipped = plan.filter((item) => item.action === "skip").map((item) => item.targetRel);
@@ -1484,12 +1522,22 @@ async function writeMigrationReport(root, command, mode, plan, created, merged,
1484
1522
  "## Conflicts",
1485
1523
  ...listOrNone(conflicts.map((item) => `${item.targetRel} - ${item.reason}`)),
1486
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
+ "",
1487
1534
  "## Backup",
1488
1535
  merged.length > 0 ? `- ${path.relative(root, backupDir)}` : "- none",
1489
1536
  "",
1490
1537
  "## Notes",
1491
1538
  "- Existing files are preserved unless the installer can perform a bounded merge.",
1492
- "- 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."
1493
1541
  ].join("\n");
1494
1542
  await writeFile(reportPath, `${text}\n`, "utf8");
1495
1543
  return reportPath;
@@ -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.3",
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": {