@adamchanadam/agent-handoff-kit 0.1.5 → 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.5` 已正式發佈到 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.5` 是 GitHub 與 npm 同步發佈版本。
204
+ - `v0.1.7` 是 GitHub 與 npm 同步發佈版本。
205
205
  - 這是早期可用版本,尚未宣稱完整穩定。
206
206
  - 升級合併仍是窄範圍策略,不是完整的複雜合併工具。
207
207
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
@@ -162,6 +162,16 @@ const requiredAnchors = [
162
162
  ];
163
163
 
164
164
  const schemaChecks = [
165
+ {
166
+ target: "AGENTS.md",
167
+ label: "core runtime uniqueness",
168
+ checks: [
169
+ {
170
+ label: "AGENTS.md health state is clean (single managed core, no unmarked dup, paired markers)",
171
+ test: (text) => assessAgentsMdHealth(text).state === "clean"
172
+ }
173
+ ]
174
+ },
165
175
  {
166
176
  target: "dev/SESSION_HANDOFF.md",
167
177
  label: "handoff required sections",
@@ -356,18 +366,38 @@ async function runInstall(command, root, options, version) {
356
366
  }
357
367
 
358
368
  const report = await writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir);
359
- console.log(`\n✅ created: ${created.length}`);
360
- console.log(`🔀 merged: ${merged.length}`);
361
- console.log(`⏭️ skipped existing: ${plan.filter((item) => item.action === "skip").length}`);
362
- console.log(`${conflicts.length > 0 ? "⚠️ " : "✅ "}conflict: ${conflicts.length}`);
363
- if (merged.length > 0) console.log(`💾 backup: ${path.relative(root, backupDir)}`);
364
- 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
+ });
365
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
+
366
396
  if (conflicts.length > 0) process.exitCode = 1;
367
397
  }
368
398
 
369
- async function runDoctor(root, version) {
370
- printCard(version, "doctor ready", "o.o");
399
+ async function runDoctor(root, version, options = {}) {
400
+ if (!options.silentCard) printCard(version, "doctor ready", "o.o");
371
401
  const rows = [];
372
402
  for (const target of requiredTargets) {
373
403
  rows.push({ target, ok: await exists(path.join(root, target)) });
@@ -381,11 +411,14 @@ async function runDoctor(root, version) {
381
411
  }
382
412
 
383
413
  if (missing.length > 0) {
384
- console.log(`\nstatus: failed (${missing.length} missing)`);
385
- console.log("⚠️ 檢查未通過:有必要檔案不存在。");
386
- 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
+ });
387
420
  process.exitCode = 1;
388
- return;
421
+ return "failed";
389
422
  }
390
423
 
391
424
  const anchorRows = await checkRequiredAnchors(root);
@@ -396,11 +429,14 @@ async function runDoctor(root, version) {
396
429
  }
397
430
 
398
431
  if (anchorFailures.length > 0) {
399
- console.log(`\nstatus: failed (${anchorFailures.length} anchor checks failed)`);
400
- console.log("⚠️ 檢查未通過:有檔案存在,但內容缺少必要段落。");
401
- 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
+ });
402
438
  process.exitCode = 1;
403
- return;
439
+ return "failed";
404
440
  }
405
441
 
406
442
  const schemaRows = await checkSchema(root);
@@ -414,11 +450,14 @@ async function runDoctor(root, version) {
414
450
  }
415
451
 
416
452
  if (schemaFailures.length > 0) {
417
- console.log(`\nstatus: failed (${schemaFailures.length} schema checks failed)`);
418
- console.log("⚠️ 檢查未通過:交接或索引文件結構不完整。");
419
- 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
+ });
420
459
  process.exitCode = 1;
421
- return;
460
+ return "failed";
422
461
  }
423
462
 
424
463
  const mirrorRows = await checkPromptMirror(root);
@@ -430,15 +469,40 @@ async function runDoctor(root, version) {
430
469
  }
431
470
 
432
471
  if (mirrorFailures.length > 0) {
433
- console.log(`\nstatus: failed (${mirrorFailures.length} prompt mirror checks failed)`);
434
- console.log("⚠️ 檢查未通過:下次開工提示副本與 handoff 真源不同。");
435
- 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
+ });
436
478
  process.exitCode = 1;
437
- return;
479
+ return "failed";
438
480
  }
439
481
 
440
- console.log("\nstatus: passed");
441
- 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}`);
442
506
  }
443
507
 
444
508
  async function checkPromptMirror(root) {
@@ -590,11 +654,42 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
590
654
  if (targetText === sourceText) return { ...base, action: "skip", reason: "already current" };
591
655
  if (command !== "upgrade") return { ...base, action: "skip", reason: "init preserves existing files" };
592
656
  if (targetRel === "AGENTS.md") {
593
- 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
+ }
594
689
  return {
595
690
  ...base,
596
691
  action: "merge",
597
- reason: "append managed core while preserving existing AGENTS.md content",
692
+ reason: "add managed core while preserving existing AGENTS.md content",
598
693
  mergedText: mergeManagedBlock(targetText, sourceText)
599
694
  };
600
695
  }
@@ -604,11 +699,171 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
604
699
  return { ...base, action: "skip", reason: "preserve existing file" };
605
700
  }
606
701
 
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
+ };
791
+ }
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
+ };
812
+ }
813
+
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";
830
+ const terminal = "keep the core within budget.";
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
+
607
843
  function mergeManagedBlock(targetText, sourceText) {
608
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
+
609
857
  const existingBlock = new RegExp(`${escapeRegExp(managedCoreStart)}[\\s\\S]*?${escapeRegExp(managedCoreEnd)}`);
610
- if (existingBlock.test(targetText)) return `${targetText.replace(existingBlock, block).trimEnd()}\n`;
611
- return `${targetText.trimEnd()}\n\n${block}\n`;
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`;
863
+ }
864
+
865
+ function countOccurrences(text, needle) {
866
+ return text.split(needle).length - 1;
612
867
  }
613
868
 
614
869
  function escapeRegExp(text) {
@@ -641,7 +896,7 @@ function printPlan(command, root, mode, plan, version) {
641
896
  console.log(`selected root: ${root}`);
642
897
  console.log(`mode: ${mode}`);
643
898
  console.log("");
644
- console.log("📋 人話解讀:下面只是計劃。create 會新增缺少檔案,merge 會在備份後安全合併,skip 會保留既有檔案,conflict 代表工具停手等你確認。");
899
+ console.log("📋 計劃預覽:以下未執行。create 新增缺少檔案;merge 在備份後合併;skip 保留既有檔案;conflict 代表工具停手等你確認。");
645
900
  console.log("");
646
901
  for (const action of ["create", "merge", "skip", "conflict"]) {
647
902
  const items = plan.filter((item) => item.action === action);
@@ -651,6 +906,27 @@ function printPlan(command, root, mode, plan, version) {
651
906
  console.log(`\nbackup: ${plan.filter((item) => item.action === "merge").length}`);
652
907
  }
653
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
+
654
930
  function printDryRunExplanation(plan) {
655
931
  const conflicts = plan.filter((item) => item.action === "conflict");
656
932
  console.log("✅ 這次沒有改動任何檔案。");
@@ -874,4 +1150,7 @@ After install:
874
1150
  Open your AI tool, start a new chat, paste the shown Work in ... message,
875
1151
  then describe your task in normal language.
876
1152
  `);
1153
+ console.log(`📦 版本:v${version}`);
1154
+ console.log(`🛠️ 模式:help ready`);
1155
+ console.log(`🚀 下一步:第一次使用先跑 init;既有專案升級用 upgrade --dry-run;要檢查現狀用 doctor。`);
877
1156
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.1.5",
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.5 | 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 |