@adamchanadam/agent-handoff-kit 0.1.6 → 0.1.7

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.1.6` 已正式發佈到 GitHub 與 npm。這是早期可用版本,尚未宣稱所有需求已完成。
3
+ 狀態:`v0.1.7` 已正式發佈到 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
 
@@ -201,7 +201,7 @@ GitHub Pages 上的新手介紹頁 `agent-handoff-kit-intro.html` 由原始碼
201
201
 
202
202
  ## 目前限制
203
203
 
204
- - `v0.1.6` 是 GitHub 與 npm 同步發佈版本。
204
+ - `v0.1.7` 是 GitHub 與 npm 同步發佈版本。
205
205
  - 這是早期可用版本,尚未宣稱完整穩定。
206
206
  - 升級合併仍是窄範圍策略,不是完整的複雜合併工具。
207
207
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
@@ -167,16 +167,8 @@ const schemaChecks = [
167
167
  label: "core runtime uniqueness",
168
168
  checks: [
169
169
  {
170
- label: "exactly one Agent Handoff Kit Core Runtime heading",
171
- test: (text) => countOccurrences(text, "# Agent Handoff Kit Core Runtime") === 1
172
- },
173
- {
174
- label: "managed core markers are paired and not duplicated",
175
- test: (text) => {
176
- const starts = countOccurrences(text, managedCoreStart);
177
- const ends = countOccurrences(text, managedCoreEnd);
178
- return starts === ends && starts <= 1;
179
- }
170
+ label: "AGENTS.md health state is clean (single managed core, no unmarked dup, paired markers)",
171
+ test: (text) => assessAgentsMdHealth(text).state === "clean"
180
172
  }
181
173
  ]
182
174
  },
@@ -374,18 +366,38 @@ async function runInstall(command, root, options, version) {
374
366
  }
375
367
 
376
368
  const report = await writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir);
377
- console.log(`\n✅ created: ${created.length}`);
378
- console.log(`🔀 merged: ${merged.length}`);
379
- console.log(`⏭️ skipped existing: ${plan.filter((item) => item.action === "skip").length}`);
380
- console.log(`${conflicts.length > 0 ? "⚠️ " : "✅ "}conflict: ${conflicts.length}`);
381
- if (merged.length > 0) console.log(`💾 backup: ${path.relative(root, backupDir)}`);
382
- console.log(`📄 migration report: ${path.relative(root, report)}`);
369
+ const skippedCount = plan.filter((item) => item.action === "skip").length;
370
+ printInstallSummary(version, command, mode, root, {
371
+ created: created.length,
372
+ merged: merged.length,
373
+ skipped: skippedCount,
374
+ conflicts: conflicts.length,
375
+ backupRel: merged.length > 0 ? path.relative(root, backupDir) : null,
376
+ reportRel: path.relative(root, report)
377
+ });
383
378
  printInstallNextSteps(root, conflicts.length);
379
+
380
+ // R-024 upgrade.done self-check: after upgrade writes, run doctor automatically.
381
+ // The user must see whether the merged state actually reaches a clean health state.
382
+ if (command === "upgrade" && conflicts.length === 0) {
383
+ console.log("");
384
+ console.log("------------------------------------------------------------");
385
+ console.log("🩺 upgrade self-check: running doctor against the upgraded root");
386
+ console.log("------------------------------------------------------------");
387
+ const doctorStatus = await runDoctor(root, version, { silentCard: true });
388
+ if (doctorStatus !== "passed") {
389
+ console.log("");
390
+ console.log("⚠️ upgrade self-check did not pass; see doctor output above.");
391
+ console.log("📋 下一步:把上面 doctor 輸出貼給 AI,請它先按提示修補後再宣稱 upgrade 完成。");
392
+ process.exitCode = 1;
393
+ }
394
+ }
395
+
384
396
  if (conflicts.length > 0) process.exitCode = 1;
385
397
  }
386
398
 
387
- async function runDoctor(root, version) {
388
- printCard(version, "doctor ready", "o.o");
399
+ async function runDoctor(root, version, options = {}) {
400
+ if (!options.silentCard) printCard(version, "doctor ready", "o.o");
389
401
  const rows = [];
390
402
  for (const target of requiredTargets) {
391
403
  rows.push({ target, ok: await exists(path.join(root, target)) });
@@ -399,11 +411,14 @@ async function runDoctor(root, version) {
399
411
  }
400
412
 
401
413
  if (missing.length > 0) {
402
- console.log(`\nstatus: failed (${missing.length} missing)`);
403
- console.log("⚠️ 檢查未通過:有必要檔案不存在。");
404
- console.log("下一步:先確認你是否在正確專案資料夾;如是,執行 init 或 upgrade 補回缺少檔案。");
414
+ printDoctorSummary(version, root, "needs-fix", {
415
+ checked: rows.length,
416
+ failedKind: "missing files",
417
+ failedCount: missing.length,
418
+ nextStep: "先確認你是否在正確專案資料夾;如是,執行 init 或 upgrade 補回缺少檔案。"
419
+ });
405
420
  process.exitCode = 1;
406
- return;
421
+ return "failed";
407
422
  }
408
423
 
409
424
  const anchorRows = await checkRequiredAnchors(root);
@@ -414,11 +429,14 @@ async function runDoctor(root, version) {
414
429
  }
415
430
 
416
431
  if (anchorFailures.length > 0) {
417
- console.log(`\nstatus: failed (${anchorFailures.length} anchor checks failed)`);
418
- console.log("⚠️ 檢查未通過:有檔案存在,但內容缺少必要段落。");
419
- console.log("下一步:執行 upgrade --dry-run 查看可否安全補齊;不要手動覆寫既有檔案。");
432
+ printDoctorSummary(version, root, "needs-fix", {
433
+ checked: rows.length + anchorRows.length,
434
+ failedKind: "anchor checks",
435
+ failedCount: anchorFailures.length,
436
+ nextStep: "執行 upgrade --dry-run 查看可否安全補齊;不要手動覆寫既有檔案。"
437
+ });
420
438
  process.exitCode = 1;
421
- return;
439
+ return "failed";
422
440
  }
423
441
 
424
442
  const schemaRows = await checkSchema(root);
@@ -432,11 +450,14 @@ async function runDoctor(root, version) {
432
450
  }
433
451
 
434
452
  if (schemaFailures.length > 0) {
435
- console.log(`\nstatus: failed (${schemaFailures.length} schema checks failed)`);
436
- console.log("⚠️ 檢查未通過:交接或索引文件結構不完整。");
437
- console.log("下一步:把這段 doctor 輸出貼給 AI,請它先修交接結構,不要直接重裝覆蓋。");
453
+ printDoctorSummary(version, root, "needs-fix", {
454
+ checked: rows.length + anchorRows.length + schemaRows.length,
455
+ failedKind: "schema checks",
456
+ failedCount: schemaFailures.length,
457
+ nextStep: "把這段 doctor 輸出貼給 AI,請它先修交接結構,不要直接重裝覆蓋。"
458
+ });
438
459
  process.exitCode = 1;
439
- return;
460
+ return "failed";
440
461
  }
441
462
 
442
463
  const mirrorRows = await checkPromptMirror(root);
@@ -448,15 +469,40 @@ async function runDoctor(root, version) {
448
469
  }
449
470
 
450
471
  if (mirrorFailures.length > 0) {
451
- console.log(`\nstatus: failed (${mirrorFailures.length} prompt mirror checks failed)`);
452
- console.log("⚠️ 檢查未通過:下次開工提示副本與 handoff 真源不同。");
453
- console.log("下一步:以 dev/SESSION_HANDOFF.md 的 Next Session Opening Message 為準,重生 START_NEXT_SESSION_PROMPT.txt。");
472
+ printDoctorSummary(version, root, "needs-fix", {
473
+ checked: rows.length + anchorRows.length + schemaRows.length + mirrorRows.length,
474
+ failedKind: "prompt mirror checks",
475
+ failedCount: mirrorFailures.length,
476
+ nextStep: "以 dev/SESSION_HANDOFF.md 的 Next Session Opening Message 為準,重生 START_NEXT_SESSION_PROMPT.txt。"
477
+ });
454
478
  process.exitCode = 1;
455
- return;
479
+ return "failed";
456
480
  }
457
481
 
458
- console.log("\nstatus: passed");
459
- console.log("✅ 檢查通過:必要文件存在,基本結構完整,下次開工提示副本也與 handoff 一致。");
482
+ printDoctorSummary(version, root, "healthy", {
483
+ checked: rows.length + anchorRows.length + schemaRows.length + mirrorRows.length,
484
+ failedKind: null,
485
+ failedCount: 0,
486
+ nextStep: "繼續日常使用;如要升級到較新版,執行 npx @adamchanadam/agent-handoff-kit@latest upgrade。"
487
+ });
488
+ return "passed";
489
+ }
490
+
491
+ // R-026 CLI Output Contract: doctor 完成必含四項(版本/模式/剛做咗乜/下一步)。
492
+ function printDoctorSummary(version, root, mode, details) {
493
+ console.log("");
494
+ if (mode === "healthy") {
495
+ console.log("status: passed");
496
+ console.log("✅ 檢查通過:必要文件存在,基本結構完整,下次開工提示副本也與 handoff 一致。");
497
+ } else {
498
+ console.log(`status: failed (${details.failedCount} ${details.failedKind} failed)`);
499
+ console.log(`⚠️ 檢查未通過:${details.failedKind === "missing files" ? "有必要檔案不存在。" : details.failedKind === "anchor checks" ? "有檔案存在,但內容缺少必要段落。" : details.failedKind === "schema checks" ? "交接或索引文件結構不完整。" : "下次開工提示副本與 handoff 真源不同。"}`);
500
+ }
501
+ console.log("");
502
+ console.log(`📦 版本:v${version}`);
503
+ console.log(`🩺 模式:${mode}`);
504
+ console.log(`🔎 剛做咗:檢查 ${details.checked} 項;${mode === "healthy" ? "全部通過" : `${details.failedCount} 項未通過(${details.failedKind})`}。`);
505
+ console.log(`🚀 下一步:${details.nextStep}`);
460
506
  }
461
507
 
462
508
  async function checkPromptMirror(root) {
@@ -608,11 +654,42 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
608
654
  if (targetText === sourceText) return { ...base, action: "skip", reason: "already current" };
609
655
  if (command !== "upgrade") return { ...base, action: "skip", reason: "init preserves existing files" };
610
656
  if (targetRel === "AGENTS.md") {
611
- if (hasRequiredAnchor(targetRel, targetText)) return { ...base, action: "skip", reason: "required anchors already present" };
657
+ const health = assessAgentsMdHealth(targetText);
658
+ if (health.state === "conflict") {
659
+ return {
660
+ ...base,
661
+ action: "conflict",
662
+ reason: `AGENTS.md managed-core markers are unpaired or duplicated (starts=${health.evidence.managedStart}, ends=${health.evidence.managedEnd})`
663
+ };
664
+ }
665
+ if (health.state === "needs-merge") {
666
+ return {
667
+ ...base,
668
+ action: "merge",
669
+ reason: health.evidence.reason === "sandwich: managed marker + unmarked stale core"
670
+ ? "replace sandwich dup core (managed marker + unmarked stale core present)"
671
+ : health.evidence.reason === "legacy duplicate cores"
672
+ ? "replace duplicated legacy Agent Handoff Kit cores"
673
+ : "add managed core while preserving existing AGENTS.md content",
674
+ mergedText: mergeManagedBlock(targetText, sourceText)
675
+ };
676
+ }
677
+ // state === "clean": may still need legacy-core replacement or anchor catch-up
678
+ if (health.evidence?.upgradeable === "legacy-core") {
679
+ return {
680
+ ...base,
681
+ action: "merge",
682
+ reason: "replace unmarked legacy Agent Handoff Kit core with managed-marker block",
683
+ mergedText: mergeManagedBlock(targetText, sourceText)
684
+ };
685
+ }
686
+ if (hasRequiredAnchor(targetRel, targetText)) {
687
+ return { ...base, action: "skip", reason: "managed core clean and required anchors present" };
688
+ }
612
689
  return {
613
690
  ...base,
614
691
  action: "merge",
615
- reason: "replace stale Agent Handoff Kit core or add managed core while preserving existing AGENTS.md content",
692
+ reason: "add managed core while preserving existing AGENTS.md content",
616
693
  mergedText: mergeManagedBlock(targetText, sourceText)
617
694
  };
618
695
  }
@@ -622,27 +699,167 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
622
699
  return { ...base, action: "skip", reason: "preserve existing file" };
623
700
  }
624
701
 
625
- function mergeManagedBlock(targetText, sourceText) {
626
- const block = `${managedCoreStart}\n${sourceText.trim()}\n${managedCoreEnd}`;
627
- const existingBlock = new RegExp(`${escapeRegExp(managedCoreStart)}[\\s\\S]*?${escapeRegExp(managedCoreEnd)}`);
628
- if (existingBlock.test(targetText)) return `${targetText.replace(existingBlock, block).trimEnd()}\n`;
629
- const unmarkedCore = findUnmarkedCoreRange(targetText);
630
- if (unmarkedCore) {
631
- return `${targetText.slice(0, unmarkedCore.start).trimEnd()}${targetText.slice(0, unmarkedCore.start).trimEnd() ? "\n\n" : ""}${block}${targetText.slice(unmarkedCore.end).trimStart() ? `\n\n${targetText.slice(unmarkedCore.end).trimStart()}` : ""}\n`;
702
+ // R-024 唯一真源:AGENTS.md 健康判斷合三為一函數。
703
+ // Returns { state, evidence } where state ∈ { clean, needs-merge, conflict }.
704
+ // - clean: structurally healthy
705
+ // * exactly one paired managed-core marker block with no unmarked title outside it, OR
706
+ // * no managed marker and exactly one core title (fresh-init legacy form)
707
+ // - needs-merge: stale state that upgrade must replace
708
+ // * managed marker pair plus unmarked title outside it (sandwich), or
709
+ // * no managed marker with two or more title duplicates, or
710
+ // * no managed marker and no title at all (file exists but Kit core absent)
711
+ // - conflict: structural breakage
712
+ // * managed-core markers unpaired or duplicated
713
+ function assessAgentsMdHealth(text) {
714
+ const managedStartCount = countOccurrences(text, managedCoreStart);
715
+ const managedEndCount = countOccurrences(text, managedCoreEnd);
716
+
717
+ if (managedStartCount !== managedEndCount || managedStartCount > 1) {
718
+ return {
719
+ state: "conflict",
720
+ evidence: {
721
+ managedStart: managedStartCount,
722
+ managedEnd: managedEndCount,
723
+ reason: "managed-core markers unpaired or duplicated"
724
+ }
725
+ };
726
+ }
727
+
728
+ let managedRange = null;
729
+ if (managedStartCount === 1) {
730
+ const start = text.indexOf(managedCoreStart);
731
+ const endStart = text.indexOf(managedCoreEnd, start);
732
+ if (endStart < 0 || endStart < start) {
733
+ return {
734
+ state: "conflict",
735
+ evidence: {
736
+ managedStart: managedStartCount,
737
+ managedEnd: managedEndCount,
738
+ reason: "managed-core end marker missing or before start"
739
+ }
740
+ };
741
+ }
742
+ managedRange = { start, end: endStart + managedCoreEnd.length };
743
+ }
744
+
745
+ // Only count real top-level headings (line-anchored), not inline mentions inside backticks.
746
+ const titlePositions = locateCoreTitlePositions(text);
747
+
748
+ const titlesOutsideManaged = titlePositions.filter((pos) =>
749
+ !managedRange || pos < managedRange.start || pos >= managedRange.end
750
+ );
751
+
752
+ // Case A: managed marker pair present
753
+ if (managedStartCount === 1) {
754
+ if (titlesOutsideManaged.length > 0) {
755
+ const unmarkedRange = computeUnmarkedRange(text, titlesOutsideManaged[0], managedRange);
756
+ return {
757
+ state: "needs-merge",
758
+ evidence: {
759
+ managedStart: 1,
760
+ titleCount: titlePositions.length,
761
+ unmarkedTitleCount: titlesOutsideManaged.length,
762
+ unmarkedRange,
763
+ reason: "sandwich: managed marker + unmarked stale core"
764
+ }
765
+ };
766
+ }
767
+ return {
768
+ state: "clean",
769
+ evidence: {
770
+ managedStart: 1,
771
+ titleCount: titlePositions.length,
772
+ reason: "single managed core, no unmarked dup"
773
+ }
774
+ };
775
+ }
776
+
777
+ // Case B: no managed marker
778
+ if (titlePositions.length === 1) {
779
+ // Structurally healthy (single heading, no dup), but upgrade should still replace
780
+ // this legacy core form with a managed-marker block. doctor passes; upgrade merges.
781
+ return {
782
+ state: "clean",
783
+ evidence: {
784
+ managedStart: 0,
785
+ titleCount: 1,
786
+ upgradeable: "legacy-core",
787
+ legacyRange: computeUnmarkedRange(text, titlePositions[0], null),
788
+ reason: "single legacy core, no managed marker"
789
+ }
790
+ };
632
791
  }
633
- return `${targetText.trimEnd()}\n\n${block}\n`;
792
+ if (titlePositions.length > 1) {
793
+ return {
794
+ state: "needs-merge",
795
+ evidence: {
796
+ managedStart: 0,
797
+ titleCount: titlePositions.length,
798
+ unmarkedTitleCount: titlePositions.length,
799
+ unmarkedRange: computeUnmarkedRange(text, titlePositions[0], null),
800
+ reason: "legacy duplicate cores"
801
+ }
802
+ };
803
+ }
804
+ return {
805
+ state: "needs-merge",
806
+ evidence: {
807
+ managedStart: 0,
808
+ titleCount: 0,
809
+ reason: "no Kit core present"
810
+ }
811
+ };
634
812
  }
635
813
 
636
- function findUnmarkedCoreRange(text) {
637
- const start = text.indexOf("# Agent Handoff Kit Core Runtime");
638
- if (start < 0) return null;
814
+ // Locate Kit core titles that are real top-level headings (line-anchored).
815
+ // This intentionally excludes inline mentions like `# Agent Handoff Kit Core Runtime`
816
+ // inside backticks or prose, so the assess function only reacts to real duplicate headings.
817
+ function locateCoreTitlePositions(text) {
818
+ const regex = /(^|\n)# Agent Handoff Kit Core Runtime(?=\r?\n|$)/g;
819
+ const positions = [];
820
+ let match;
821
+ while ((match = regex.exec(text)) !== null) {
822
+ const headingStart = match.index + (match[1] === "\n" ? 1 : 0);
823
+ positions.push(headingStart);
824
+ }
825
+ return positions;
826
+ }
827
+
828
+ function computeUnmarkedRange(text, titleStart, managedRange) {
829
+ const titleNeedle = "# Agent Handoff Kit Core Runtime";
639
830
  const terminal = "keep the core within budget.";
640
- const terminalIndex = text.indexOf(terminal, start);
641
- if (terminalIndex >= 0) return { start, end: terminalIndex + terminal.length };
642
- const afterTitle = start + "# Agent Handoff Kit Core Runtime".length;
643
- const nextTopLevel = text.slice(afterTitle).search(/\n# (?!Agent Handoff Kit Core Runtime\b)/);
644
- if (nextTopLevel < 0) return { start, end: text.length };
645
- return { start, end: afterTitle + nextTopLevel + 1 };
831
+ const terminalIndex = text.indexOf(terminal, titleStart);
832
+ if (terminalIndex >= 0 && (!managedRange || terminalIndex < managedRange.start || terminalIndex >= managedRange.end)) {
833
+ return { start: titleStart, end: terminalIndex + terminal.length };
834
+ }
835
+ const afterTitle = titleStart + titleNeedle.length;
836
+ const remainder = text.slice(afterTitle);
837
+ // Find next real top-level heading that is NOT another Kit core heading.
838
+ const nextTopLevel = remainder.search(/\n# (?!Agent Handoff Kit Core Runtime(?=\r?\n|$))/);
839
+ if (nextTopLevel < 0) return { start: titleStart, end: text.length };
840
+ return { start: titleStart, end: afterTitle + nextTopLevel + 1 };
841
+ }
842
+
843
+ function mergeManagedBlock(targetText, sourceText) {
844
+ const block = `${managedCoreStart}\n${sourceText.trim()}\n${managedCoreEnd}`;
845
+
846
+ // Strip every unmarked / legacy core range first; iterate to handle multiple legacy stacks.
847
+ let working = targetText;
848
+ for (let i = 0; i < 5; i += 1) {
849
+ const probe = assessAgentsMdHealth(working);
850
+ const range = probe.evidence?.unmarkedRange ?? probe.evidence?.legacyRange;
851
+ if (!range) break;
852
+ const before = working.slice(0, range.start).trimEnd();
853
+ const after = working.slice(range.end).trimStart();
854
+ working = before + (before && after ? "\n\n" : before ? "\n" : "") + after;
855
+ }
856
+
857
+ const existingBlock = new RegExp(`${escapeRegExp(managedCoreStart)}[\\s\\S]*?${escapeRegExp(managedCoreEnd)}`);
858
+ if (existingBlock.test(working)) {
859
+ return `${working.replace(existingBlock, block).trimEnd()}\n`;
860
+ }
861
+ if (working.trim().length === 0) return `${block}\n`;
862
+ return `${working.trimEnd()}\n\n${block}\n`;
646
863
  }
647
864
 
648
865
  function countOccurrences(text, needle) {
@@ -679,7 +896,7 @@ function printPlan(command, root, mode, plan, version) {
679
896
  console.log(`selected root: ${root}`);
680
897
  console.log(`mode: ${mode}`);
681
898
  console.log("");
682
- console.log("📋 人話解讀:下面只是計劃。create 會新增缺少檔案,merge 會在備份後安全合併,skip 會保留既有檔案,conflict 代表工具停手等你確認。");
899
+ console.log("📋 計劃預覽:以下未執行。create 新增缺少檔案;merge 在備份後合併;skip 保留既有檔案;conflict 代表工具停手等你確認。");
683
900
  console.log("");
684
901
  for (const action of ["create", "merge", "skip", "conflict"]) {
685
902
  const items = plan.filter((item) => item.action === action);
@@ -689,6 +906,27 @@ function printPlan(command, root, mode, plan, version) {
689
906
  console.log(`\nbackup: ${plan.filter((item) => item.action === "merge").length}`);
690
907
  }
691
908
 
909
+ // R-026 CLI Output Contract: install/upgrade 完成必含四項(版本/模式/剛做咗乜/下一步)。
910
+ function printInstallSummary(version, command, mode, root, counts) {
911
+ console.log(`\n✅ created: ${counts.created}`);
912
+ console.log(`🔀 merged: ${counts.merged}`);
913
+ console.log(`⏭️ skipped existing: ${counts.skipped}`);
914
+ console.log(`${counts.conflicts > 0 ? "⚠️ " : "✅ "}conflict: ${counts.conflicts}`);
915
+ if (counts.backupRel) console.log(`💾 backup: ${counts.backupRel}`);
916
+ if (counts.reportRel) console.log(`📄 migration report: ${counts.reportRel}`);
917
+ console.log("");
918
+ console.log(`📦 版本:v${version}`);
919
+ console.log(`🛠️ 模式:${mode}`);
920
+ console.log(`🔎 剛做咗:${command} 命令;create ${counts.created} / merge ${counts.merged} / skip ${counts.skipped} / conflict ${counts.conflicts}。`);
921
+ if (counts.conflicts > 0) {
922
+ console.log("🚀 下一步:把 migration report 或這段輸出貼給 AI,請它判斷 conflict 點處理;工具已停手,沒有覆寫 conflict 檔案。");
923
+ } else if (command === "upgrade") {
924
+ console.log("🚀 下一步:留意下方 upgrade self-check(自動跑 doctor);若全綠即升級完成。");
925
+ } else {
926
+ console.log("🚀 下一步:開新 AI 對話,按下方提示貼入 Work in <root> 一句後描述任務。");
927
+ }
928
+ }
929
+
692
930
  function printDryRunExplanation(plan) {
693
931
  const conflicts = plan.filter((item) => item.action === "conflict");
694
932
  console.log("✅ 這次沒有改動任何檔案。");
@@ -912,4 +1150,7 @@ After install:
912
1150
  Open your AI tool, start a new chat, paste the shown Work in ... message,
913
1151
  then describe your task in normal language.
914
1152
  `);
1153
+ console.log(`📦 版本:v${version}`);
1154
+ console.log(`🛠️ 模式:help ready`);
1155
+ console.log(`🚀 下一步:第一次使用先跑 init;既有專案升級用 upgrade --dry-run;要檢查現狀用 doctor。`);
915
1156
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.1.6",
3
+ "version": "0.1.7",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -19,10 +19,11 @@
19
19
  "qa:prototype": "node scripts/check-public-prototype.mjs",
20
20
  "qa:packs": "node scripts/check-pack-scenarios.mjs",
21
21
  "qa:upgrade": "node scripts/check-upgrade-safety.mjs",
22
- "qa:release": "node scripts/check-release-readiness.mjs"
22
+ "qa:release": "node scripts/check-release-readiness.mjs",
23
+ "qa:fixtures": "node scripts/generate-upgrade-fixtures.mjs"
23
24
  },
24
25
  "engines": {
25
26
  "node": ">=18"
26
27
  },
27
28
  "license": "MIT"
28
- }
29
+ }
@@ -48,6 +48,16 @@ External skill flows, subagents, task plans, or another tool's "finish" step do
48
48
 
49
49
  For high-risk work, pause after PLAN. High-risk means destructive operations, ambiguous target, external systems, release/publish, or broad multi-file change.
50
50
 
51
+ ## 2.1 Upgrade Done Contract
52
+
53
+ `agent-handoff-kit upgrade` is considered complete only when all of the following hold. The CLI enforces this contract; do not declare upgrade success without it.
54
+
55
+ 1. `AGENTS.md` health state is `clean`: exactly one `# Agent Handoff Kit Core Runtime` heading, exactly one paired managed-core marker block, and no unmarked stale core ranges. Sandwich states (managed marker plus an unmarked stale core) are not clean; the installer must replace the stale ranges, not skip.
56
+ 2. The CLI runs `doctor` automatically against the upgraded root after writes complete. `doctor` must report `status: passed` across required files, anchors, schema checks, and prompt mirror checks.
57
+ 3. The migration report records every action taken, with backup paths for merged files.
58
+
59
+ If any check fails, the upgrade did not finish; resolve the failure (or hand the failure output to the user) before reporting completion. This contract is the single source of truth for upgrade success; downstream QA scripts and release-grade QA derive their assertions from it.
60
+
51
61
  ## 3. Safety Boundaries
52
62
 
53
63
  Do not delete, reset, overwrite, bulk-move, or publish without explicit user approval.
@@ -112,4 +122,4 @@ If a pack, skill, subagent plan, demo workspace, or external workflow produces i
112
122
 
113
123
  ## Core Complexity Rule
114
124
 
115
- New default-core rules are allowed only when they apply to most sessions, protect safety or continuity, cannot live in a pack or registry, and keep the core within budget.
125
+ New default-core rules are allowed only when they apply to most sessions, protect safety or continuity, cannot live in a pack or registry, and keep the core within budget.
@@ -6,7 +6,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
6
6
 
7
7
  | Field | Value | Last verified |
8
8
  |---|---|---|
9
- | Agent Handoff Kit template version | 0.1.6 | package prototype |
9
+ | Agent Handoff Kit template version | 0.1.7 | package prototype |
10
10
  | Runtime | TBD | TBD |
11
11
  | Framework | TBD | TBD |
12
12
  | Package manager | TBD | TBD |