@adamchanadam/agent-handoff-kit 0.3.11 → 0.3.12

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.11`。這是早期可用版本,仍在持續完善中。
3
+ 狀態:目前版本為 `v0.3.12`。這是早期可用版本,仍在持續完善中。
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
 
@@ -35,6 +35,10 @@ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
35
35
 
36
36
  ## 三步上手
37
37
 
38
+ ![Agent Handoff Kit 新手流程](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-new-user-flow.png)
39
+
40
+ 這張圖是給第一次使用的人看的流程摘要:先在專案資料夾安裝,然後在 AI 對話中說「教我用」或 `help me start`,完成工作時說「收工」,讓 AI 留下下一次能接上的交接。
41
+
38
42
  ### 一、安裝
39
43
 
40
44
  在你的專案資料夾打開終端機,執行:
@@ -116,7 +120,7 @@ START_NEXT_SESSION_PROMPT.txt
116
120
  npx --yes @adamchanadam/agent-handoff-kit@latest doctor
117
121
  ```
118
122
 
119
- 看到「檢查通過」代表必要文件、基本結構與下次開工提示副本的一致性都通過檢查。
123
+ 看到「檢查通過」代表必要文件與基本結構通過檢查。若 `START_NEXT_SESSION_PROMPT.txt` 落後於 `dev/SESSION_HANDOFF.md`,`doctor` 只會提醒;這個便利副本應在收工 closeout 時由 AI 重新生成,不需要在 session 中途手動更新。
120
124
 
121
125
  `doctor` 只檢查,不會建立或修改項目文件。這個檢查只能確認文件齊不齊、格式是否正常,不代表 AI 已理解你的專案。真正開始工作前,仍應把 `Work in ...` 起步句貼到 AI 對話,讓 AI 讀入口文件並說明目前狀態。
122
126
 
@@ -257,7 +261,7 @@ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templa
257
261
 
258
262
  ## 目前限制
259
263
 
260
- - 目前版本為 `v0.3.11`。
264
+ - 目前版本為 `v0.3.12`。
261
265
  - 這是早期可用版本,仍在持續完善中。
262
266
  - 升級合併屬窄範圍策略,不是完整的複雜合併工具。
263
267
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
@@ -726,23 +726,25 @@ async function runDoctor(root, version, options = {}) {
726
726
  return "failed";
727
727
  }
728
728
 
729
- const mirrorRows = await checkPromptMirror(root);
730
- const mirrorFailures = mirrorRows.filter((row) => !row.ok);
731
- console.log(`\nprompt mirror checks: ${mirrorRows.length}`);
732
- for (const row of mirrorRows) {
733
- console.log(`${row.ok ? "ok" : "missing"} ${row.target} (${row.label})`);
734
- if (!row.ok && row.reason) console.log(` reason: ${row.reason}`);
735
- }
736
-
737
- if (mirrorFailures.length > 0) {
738
- printDoctorSummary(version, root, "needs-fix", {
739
- checked: rows.length + anchorRows.length + schemaRows.length + mirrorRows.length,
740
- failedKind: "prompt mirror checks",
741
- failedCount: mirrorFailures.length,
742
- nextStep: "以 dev/SESSION_HANDOFF.md 的 Next Session Opening Message 為準,重生 START_NEXT_SESSION_PROMPT.txt。"
743
- });
744
- process.exitCode = 1;
745
- return "failed";
729
+ const mirrorRows = await checkPromptMirror(root);
730
+ const mirrorBlockingFailures = mirrorRows.filter((row) => !row.ok && row.reason !== "convenience copy differs from dev/SESSION_HANDOFF.md");
731
+ const mirrorWarnings = mirrorRows.filter((row) => !row.ok && row.reason === "convenience copy differs from dev/SESSION_HANDOFF.md");
732
+ console.log(`\nprompt mirror checks: ${mirrorRows.length}`);
733
+ for (const row of mirrorRows) {
734
+ const status = row.ok ? "ok" : row.reason === "convenience copy differs from dev/SESSION_HANDOFF.md" ? "warn" : "missing";
735
+ console.log(`${status} ${row.target} (${row.label})`);
736
+ if (!row.ok && row.reason) console.log(` reason: ${row.reason}`);
737
+ }
738
+
739
+ if (mirrorBlockingFailures.length > 0) {
740
+ printDoctorSummary(version, root, "needs-fix", {
741
+ checked: rows.length + anchorRows.length + schemaRows.length + mirrorRows.length,
742
+ failedKind: "prompt mirror checks",
743
+ failedCount: mirrorBlockingFailures.length,
744
+ nextStep: "以 dev/SESSION_HANDOFF.md 的 Next Session Opening Message 為準,重生 START_NEXT_SESSION_PROMPT.txt。"
745
+ });
746
+ process.exitCode = 1;
747
+ return "failed";
746
748
  }
747
749
 
748
750
  // R-010 SESSION_LOG handoff-role discipline check (warn-only; does not change mode or exit).
@@ -776,16 +778,21 @@ async function runDoctor(root, version, options = {}) {
776
778
  const projectAge = await assessProjectAge(root);
777
779
  printProjectAge(projectAge);
778
780
  const onboardingNextStep = options.context === "upgrade-self-check" ? null : getFirstUseNextStep(root, lastCloseout);
779
-
780
- const overallHealthy = credentialResult.ok;
781
- printDoctorSummary(version, root, overallHealthy ? "healthy" : "needs-attention", {
782
- checked: rows.length + anchorRows.length + schemaRows.length + mirrorRows.length + 2,
783
- failedKind: !credentialResult.ok ? "credential leak" : null,
784
- failedCount: !credentialResult.ok ? credentialResult.findings.length : 0,
785
- nextStep: !credentialResult.ok
781
+ const promptMirrorNextStep = mirrorWarnings.length > 0
782
+ ? "檢查已通過。START_NEXT_SESSION_PROMPT.txt 只是下次開工便利副本;session 進行中不用手動重生,收工 closeout 時 AI 會從 dev/SESSION_HANDOFF.md 重生。"
783
+ : null;
784
+
785
+ const overallHealthy = credentialResult.ok;
786
+ printDoctorSummary(version, root, overallHealthy ? "healthy" : "needs-attention", {
787
+ checked: rows.length + anchorRows.length + schemaRows.length + mirrorRows.length + 2,
788
+ failedKind: !credentialResult.ok ? "credential leak" : null,
789
+ failedCount: !credentialResult.ok ? credentialResult.findings.length : 0,
790
+ warningKind: mirrorWarnings.length > 0 ? "prompt mirror warning" : null,
791
+ warningCount: mirrorWarnings.length,
792
+ nextStep: !credentialResult.ok
786
793
  ? "立即從相關檔案 redact credential value + rotate 已泄露 token;credential 應該由 AI 工具自身 secure storage 管理,永不寫入 dev/* 任何檔。"
787
794
  : disciplineResult.ok
788
- ? versionNextStep ?? onboardingNextStep ?? "檢查已通過。繼續使用你原本的 AI 開工方式;如剛完成一個任務,記得在 AI 對話輸入「收工」保存交接。"
795
+ ? versionNextStep ?? promptMirrorNextStep ?? onboardingNextStep ?? "檢查已通過。繼續使用你原本的 AI 開工方式;如剛完成一個任務,記得在 AI 對話輸入「收工」保存交接。"
789
796
  : "繼續使用;下次 closeout 時 AI 應自動執行 SESSION_LOG N 規則推進(見上面 warn 行)。如未動請要求 AI 重做 closeout。"
790
797
  });
791
798
  return overallHealthy ? "passed" : "failed";
@@ -843,18 +850,23 @@ async function checkInstalledIntegrationsCredentialLeak(root) {
843
850
 
844
851
  // R-026 CLI Output Contract: doctor 完成必含四項(版本/模式/剛完成/下一步)。
845
852
  function printDoctorSummary(version, root, mode, details) {
846
- console.log("");
847
- if (mode === "healthy") {
848
- console.log("status: passed");
849
- console.log("✅ 檢查通過:必要文件存在,基本結構完整,下次開工提示副本也與 handoff 一致。");
850
- } else {
851
- console.log(`status: failed (${details.failedCount} ${details.failedKind} failed)`);
852
- console.log(`⚠️ 檢查未通過:${details.failedKind === "missing files" ? "有必要檔案不存在。" : details.failedKind === "anchor checks" ? "有檔案存在,但內容缺少必要段落。" : details.failedKind === "schema checks" ? "交接或索引文件結構不完整。" : "下次開工提示副本與 handoff 真源不同。"}`);
853
- }
853
+ console.log("");
854
+ if (mode === "healthy") {
855
+ console.log("status: passed");
856
+ if (details.warningCount > 0) {
857
+ console.log("✅ 檢查通過:必要文件存在,基本結構完整。");
858
+ console.log("⚠️ 提醒:下次開工提示便利副本目前落後於 handoff;這只需要在收工 closeout 時重生。");
859
+ } else {
860
+ console.log("✅ 檢查通過:必要文件存在,基本結構完整,下次開工提示副本已與 handoff 一致。");
861
+ }
862
+ } else {
863
+ console.log(`status: failed (${details.failedCount} ${details.failedKind} failed)`);
864
+ console.log(`⚠️ 檢查未通過:${details.failedKind === "missing files" ? "有必要檔案不存在。" : details.failedKind === "anchor checks" ? "有檔案存在,但內容缺少必要段落。" : details.failedKind === "schema checks" ? "交接或索引文件結構不完整。" : "下次開工提示副本與 handoff 真源不同。"}`);
865
+ }
854
866
  console.log("");
855
867
  console.log(`📦 版本:v${version}`);
856
868
  console.log(`🩺 模式:${mode}`);
857
- console.log(`🔎 剛完成:檢查 ${details.checked} 項;${mode === "healthy" ? "全部通過" : `${details.failedCount} 項未通過(${details.failedKind})`}。`);
869
+ console.log(`🔎 剛完成:檢查 ${details.checked} 項;${mode === "healthy" ? (details.warningCount > 0 ? `0 項未通過;${details.warningCount} 項提醒(${details.warningKind})` : "全部通過") : `${details.failedCount} 項未通過(${details.failedKind})`}。`);
858
870
  console.log(`🚀 下一步:${details.nextStep}`);
859
871
  }
860
872
 
@@ -867,7 +879,7 @@ async function hydrateInitialOpeningPrompt(root, created) {
867
879
  if (!text.includes("<absolute project root>")) continue;
868
880
  await writeFile(filePath, text.replaceAll("<absolute project root>", root), "utf8");
869
881
  } catch {
870
- // Leave template untouched; doctor will surface prompt mirror problems if any.
882
+ // Leave template untouched; doctor will warn about convenience-copy drift if any.
871
883
  }
872
884
  }
873
885
  }
@@ -0,0 +1,19 @@
1
+ # v0.3.12
2
+
3
+ ## 本版新加了甚麼
4
+
5
+ 本版修正 `doctor` 對下次開工提示便利副本的判斷。`dev/SESSION_HANDOFF.md` 仍是權威;`START_NEXT_SESSION_PROMPT.txt` 只是給你下次開工複製用的副本,應在收工 closeout 時重新產生。
6
+
7
+ ## 對你已有檔案的影響
8
+
9
+ 既有項目不用重裝。若你在一個 session 中途更新了 handoff,但還未收工,`doctor` 不會再因便利副本暫時落後而判定項目失敗。它會提醒你:完成任務後請 AI 執行 closeout,屆時再重生便利副本。
10
+
11
+ ## 建議下一步
12
+
13
+ 升級前可先預演:
14
+
15
+ ```bash
16
+ npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
17
+ ```
18
+
19
+ 如果預演沒有 conflict,再執行正式升級。升級後可用 `doctor` 檢查;若只有便利副本提醒,繼續工作即可,收工時再讓 AI 保存交接。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.11",
3
+ "version": "0.3.12",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -62,7 +62,7 @@ For high-risk work, pause after PLAN. High-risk means destructive operations, am
62
62
  `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.
63
63
 
64
64
  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.
65
- 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.
65
+ 2. The CLI runs `doctor` automatically against the upgraded root after writes complete. `doctor` must report `status: passed` across required files, anchors, schema checks, handoff lifecycle checks, and credential separation checks. A `START_NEXT_SESSION_PROMPT.txt` convenience-copy warning does not block upgrade health; that file is regenerated at full closeout.
66
66
  3. The migration report records every action taken, with backup paths for merged files.
67
67
 
68
68
  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.
@@ -92,7 +92,7 @@ At full closeout:
92
92
  7. Run the handoff sufficiency check: the next AI should be able to continue from `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history.
93
93
  8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
94
94
  9. Show a short closeout card, then provide a copy-paste-ready next-session opening message inside a fenced `text` code block, so the user can clearly copy and paste it into the next session.
95
- 10. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the fenced opening message in `dev/SESSION_HANDOFF.md`. `dev/SESSION_HANDOFF.md` is authoritative; `START_NEXT_SESSION_PROMPT.txt` is only a convenience copy for the user to paste at the next startup.
95
+ 10. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the fenced opening message in `dev/SESSION_HANDOFF.md`. `dev/SESSION_HANDOFF.md` is authoritative; `START_NEXT_SESSION_PROMPT.txt` is only a convenience copy for the user to paste at the next startup. During an active session, do not regenerate it just to silence `doctor`; normal `doctor` may warn about drift, but closeout must make the copy match before handoff is declared ready.
96
96
  11. Advance the SESSION_LOG N-rule (R-010 SESSION_LOG handoff-role discipline). After prepending the new closeout entry, count `## YYYY-MM-DD` H2 entries in `dev/SESSION_LOG.md`. Any entry now at position N ≥ 11 (oldest end) must be moved into `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` with raw content preserved. Maintain `dev/SESSION_LOG_archive/INDEX.md` (master index of all archive batches; create on first archive). Entries at N=4–10 whose core facts are already absorbed into HANDOFF / PROJECT_INDEX / requirements / decision records collapse to a short-index line using structural anchors, not line numbers. Entries with unique narrative not yet absorbed must first be ported into the relevant durable source, then collapsed. This is mandatory; do not skip. Handoff capability rests on `dev/SESSION_HANDOFF.md`; `dev/SESSION_LOG.md` is trace-back / audit trail and does not carry handoff responsibility.
97
97
 
98
98
  12. Maintain `dev/PROJECT_DECISIONS.md` per R-028 project narrative discipline. Each closeout must run the following checks with equal mechanical rigor as the SESSION_LOG N-rule (step 11):
@@ -123,7 +123,7 @@ Record this at closeout so the next AI can detect wrong-root or workspace drift.
123
123
  | UI behavior | TBD | build + visual/manual check |
124
124
  | Data model | TBD | migration/checks |
125
125
  | Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
126
- | Closeout/startup contract | `AGENTS.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | opening message present + prompt convenience copy matches handoff + workspace identity current |
126
+ | Closeout/startup contract | `AGENTS.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | opening message present + workspace identity current + prompt convenience copy regenerated from handoff at closeout |
127
127
 
128
128
  ## External Services
129
129