@adamchanadam/agent-handoff-kit 0.3.5 → 0.3.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.3.5`。這是早期可用版本,仍在持續完善中。
3
+ 狀態:目前版本為 `v0.3.7`。這是早期可用版本,仍在持續完善中。
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
 
@@ -18,7 +18,7 @@ Agent Handoff Kit 是 **AI Session 之間的接力棒**。
18
18
  >
19
19
  > AI 會自動引導你選擇使用情境(寫代碼 / 寫報告 / 整理知識庫 / 學寫代碼 / 其他),然後一步一步帶你做第一個任務。本 README 與下方介紹頁是參考對照,不是必讀。
20
20
 
21
- 想先看非技術版介紹,可打開 GitHub Pages 上的 [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html) —— 新手 60 秒入門。看完想看實際操作示範,可開 [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html) —— 兩個日常情境(整理電腦下載目錄、開咖啡店市場調查)的完整流程示範。本 README 則保留安裝、日常使用與限制。
21
+ 想先看非技術版介紹,可打開 GitHub Pages 上的 [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html) —— 新手 60 秒入門。看完想看實際操作示範,可開 [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html) —— 三個日常情境(整理電腦下載目錄、開咖啡店市場調查、長期 AI 項目演進)的完整流程示範。本 README 則保留安裝、日常使用與限制。
22
22
 
23
23
  ## 它解決甚麼問題
24
24
 
@@ -40,11 +40,20 @@ Agent Handoff Kit 是 **AI Session 之間的接力棒**。
40
40
  在你的專案資料夾打開 Terminal,執行:
41
41
 
42
42
  ```bash
43
- npx @adamchanadam/agent-handoff-kit init
43
+ npx --yes @adamchanadam/agent-handoff-kit@latest init
44
44
  ```
45
45
 
46
46
  出現確認問題時,輸入 `yes`。
47
47
 
48
+ 這是本工具建議的正式 `npx` 寫法。不要省略 `--yes` 與 `@latest`;裸寫不帶 `--yes` / `@latest` 的 `npx doctor` 雖然可能由 npm 執行,但不是本工具的建議用戶路徑,容易先出現 npm 自己的安裝提示,造成誤解。
49
+
50
+ 這裡的 `--yes` 只用來回答 npm「是否先下載這個執行工具」的提示;它不是把 Handoff Kit 文件靜默寫入你的項目。真正會建立項目文件的是 `init`,而且工具仍會顯示計劃與確認步驟。
51
+
52
+ 請分清兩層「安裝」:
53
+
54
+ - **項目內的 Kit 文件**:`AGENTS.md`、`dev/SESSION_HANDOFF.md`、`dev/rules/*.md` 等,這些是 `init` 或正式 `upgrade` 管理的交接文件。
55
+ - **電腦用來執行指令的 npm 工具**:`npx` 需要先取得 `@adamchanadam/agent-handoff-kit` 這個執行工具,才有辦法跑 `init`、`upgrade` 或 `doctor`。即使目前資料夾已安裝舊版 Kit 文件,`npx` 仍可能因本機沒有可執行工具而顯示「Need to install the following packages」。判斷點不是資料夾有沒有 `AGENTS.md` 或 `dev/`,而是當下是否已有可執行的 npm 工具。那只是 npm 取得執行工具,不等於 `doctor` 正在安裝或改動你的項目。
56
+
48
57
  安裝完成後,你會看到一段 `Work in ...` 文字。請特別留意:那一段不是給 Terminal 的指令,而是要貼到 AI 對話。
49
58
 
50
59
  ### 二、開工
@@ -95,12 +104,12 @@ START_NEXT_SESSION_PROMPT.txt
95
104
  如要檢查安裝是否完整,可在 Terminal 執行:
96
105
 
97
106
  ```bash
98
- npx @adamchanadam/agent-handoff-kit doctor
107
+ npx --yes @adamchanadam/agent-handoff-kit@latest doctor
99
108
  ```
100
109
 
101
110
  看到 `status: passed`,代表必要文件、基本結構與下次開工提示副本的一致性都通過檢查。
102
111
 
103
- 這個檢查只能確認文件結構,不代表 AI 已理解你的專案。真正開始工作前,仍應要求 AI 先讀入口文件並說明目前狀態。
112
+ `doctor` 只檢查,不會建立或修改項目文件。若你不用 `--yes`,npm 可能先問是否下載 `@adamchanadam/agent-handoff-kit` 來執行指令;那是取得檢查工具,不是安裝 Kit 到目前資料夾。這個檢查只能確認文件結構,不代表 AI 已理解你的專案。真正開始工作前,仍應要求 AI 先讀入口文件並說明目前狀態。
104
113
 
105
114
  ## 會安裝甚麼
106
115
 
@@ -205,13 +214,13 @@ dev/rules/*.md
205
214
  如果你的專案已經裝過舊版 Agent Handoff Kit,或本來已有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 等 AI 記憶文件,可先用最新版安裝工具預演會發生甚麼:
206
215
 
207
216
  ```bash
208
- npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
217
+ npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
209
218
  ```
210
219
 
211
220
  確認沒有問題後,再執行:
212
221
 
213
222
  ```bash
214
- npx @adamchanadam/agent-handoff-kit@latest upgrade
223
+ npx --yes @adamchanadam/agent-handoff-kit@latest upgrade
215
224
  ```
216
225
 
217
226
  `@latest` 代表使用 npm 上最新版本的 Agent Handoff Kit。`upgrade` 則負責把專案內已安裝的文件、規則與檢查結構安全更新。升級工具會保留既有檔案;能安全合併時才合併,不能安全合併時會回報衝突,不會靜默覆寫。
@@ -235,11 +244,11 @@ Agent Handoff Kit 同 [Adam-AI-Instructions](https://github.com/prompt-templates
235
244
  - **Adam-AI-Instructions** 負責 AI 在**單一對話**內的做事規矩:語氣、做事優先序、回覆骨架、計算紀律、用語紀律、安全護欄、輸出層分工。屬「AI 應該怎樣答你」的持久基準。
236
245
  - **Agent Handoff Kit** 負責 AI 在**對話之間**的接力:當前狀態、下一步、檔案登記、收工同下次開工。屬「AI 在對話之間怎樣記住你的項目」的持久基準。
237
246
 
238
- 到該 repo 的「五、Prompt 索引」選擇適合你 AI 工具的版本(Claude Cowork、Claude Code、OpenAI Codex、ChatGPT 等),複製對應子目錄的 `prompt.md` 全文,貼入 AI 工具的設定區(例如 Claude Cowork 的 Global Instructions、Claude Code 的 `~/.claude/CLAUDE.md`、ChatGPT 的 Custom Instructions)。然後再在項目資料夾執行 `npx @adamchanadam/agent-handoff-kit init` 安裝本工具。兩者配合就能涵蓋「單次對話質素」加「跨對話接力」兩個維度。
247
+ 到該 repo 的「五、Prompt 索引」選擇適合你 AI 工具的版本(Claude Cowork、Claude Code、OpenAI Codex、ChatGPT 等),複製對應子目錄的 `prompt.md` 全文,貼入 AI 工具的設定區(例如 Claude Cowork 的 Global Instructions、Claude Code 的 `~/.claude/CLAUDE.md`、ChatGPT 的 Custom Instructions)。然後再在項目資料夾執行 `npx --yes @adamchanadam/agent-handoff-kit@latest init` 安裝本工具。兩者配合就能涵蓋「單次對話質素」加「跨對話接力」兩個維度。
239
248
 
240
249
  ## 目前限制
241
250
 
242
- - 目前版本為 `v0.3.5`。
251
+ - 目前版本為 `v0.3.7`。
243
252
  - 這是早期可用版本,仍在持續完善中。
244
253
  - 升級合併屬窄範圍策略,不是完整的複雜合併工具。
245
254
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
@@ -71,11 +71,12 @@ const requiredAnchors = [
71
71
  "fenced `text` code block",
72
72
  "handoff saved",
73
73
  "📋 Next session: copy and paste the whole block below",
74
- "State Reconciliation Check",
75
- "Do not append a new state snapshot",
76
- "START_NEXT_SESSION_PROMPT.txt"
77
- ]
78
- },
74
+ "State Reconciliation Check",
75
+ "handoff lifecycle consistency",
76
+ "Do not append a new state snapshot",
77
+ "START_NEXT_SESSION_PROMPT.txt"
78
+ ]
79
+ },
79
80
  {
80
81
  target: "START_NEXT_SESSION_PROMPT.txt",
81
82
  label: "next-session prompt convenience copy",
@@ -101,11 +102,12 @@ const requiredAnchors = [
101
102
  "ack:section:workspace-identity",
102
103
  "ack:section:sync-status",
103
104
  "ack:section:next-task-required-reading",
104
- "ack:section:state-reconciliation-check",
105
- "ack:section:next-session-opening-message",
106
- "📋 Next session: copy and paste the whole block below",
107
- "```text",
108
- "Read in order:",
105
+ "ack:section:state-reconciliation-check",
106
+ "ack:section:next-session-opening-message",
107
+ "ack:field:lifecycle-conflicts-resolved",
108
+ "📋 Next session: copy and paste the whole block below",
109
+ "```text",
110
+ "Read in order:",
109
111
  "dev/DOC_SYNC_REGISTRY.md"
110
112
  ]
111
113
  },
@@ -247,10 +249,11 @@ const schemaChecks = [
247
249
  section("state-reconciliation-check", "State Reconciliation Check"),
248
250
  section("handoff-sufficiency-check", "Handoff Sufficiency Check"),
249
251
  section("next-session-opening-message", "Next Session Opening Message"),
250
- marker("field", "stale-snapshots-left", "Stale snapshots left in this handoff"),
251
- marker("field", "opening-message-matches-current-state", "Opening message matches current state"),
252
- marker("field", "state-sections-rewritten-or-confirmed", "State sections rewritten or confirmed current"),
253
- marker("field", "user-intent", "User intent:"),
252
+ marker("field", "stale-snapshots-left", "Stale snapshots left in this handoff"),
253
+ marker("field", "lifecycle-conflicts-resolved", "Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified"),
254
+ marker("field", "opening-message-matches-current-state", "Opening message matches current state"),
255
+ marker("field", "state-sections-rewritten-or-confirmed", "State sections rewritten or confirmed current"),
256
+ marker("field", "user-intent", "User intent:"),
254
257
  marker("field", "task-essence", "Task essence:"),
255
258
  marker("field", "success-criteria", "Success criteria:")
256
259
  ]
@@ -263,12 +266,22 @@ const schemaChecks = [
263
266
  includes("```text"),
264
267
  includes("Work in "),
265
268
  includes("Read in order:"),
266
- includes("If this root does not match the expected project root")
267
- ]
268
- },
269
- {
270
- target: "dev/SESSION_LOG.md",
271
- label: "session log entry fields",
269
+ includes("If this root does not match the expected project root")
270
+ ]
271
+ },
272
+ {
273
+ target: "dev/SESSION_HANDOFF.md",
274
+ label: "handoff lifecycle consistency",
275
+ checks: [
276
+ {
277
+ label: "completed work is not carried forward as unresolved next work",
278
+ test: (text) => assessHandoffLifecycleConsistency(text).ok
279
+ }
280
+ ]
281
+ },
282
+ {
283
+ target: "dev/SESSION_LOG.md",
284
+ label: "session log entry fields",
272
285
  checks: [
273
286
  heading("Entry Template"),
274
287
  includes("- **ID:**"),
@@ -869,13 +882,97 @@ function extractOpeningMessage(text) {
869
882
  return text.slice(contentStart + 1, fenceEnd).trim();
870
883
  }
871
884
 
872
- function normalizePrompt(text) {
873
- return text.replace(/\r\n/g, "\n").trim();
874
- }
875
-
876
- async function checkRequiredAnchors(root) {
877
- const rows = [];
878
- for (const rule of requiredAnchors) {
885
+ function normalizePrompt(text) {
886
+ return text.replace(/\r\n/g, "\n").trim();
887
+ }
888
+
889
+ function assessHandoffLifecycleConsistency(text) {
890
+ const fieldValue = fieldValueAfterMarker(text, "lifecycle-conflicts-resolved");
891
+ if (fieldValue && /\b(no|blocked|uncertain)\b|否|阻擋|不確定/i.test(fieldValue)) {
892
+ return { ok: false, reason: "lifecycle field is explicitly unresolved" };
893
+ }
894
+
895
+ const evidenceText = [
896
+ extractSectionText(text, "completed-this-session", "Completed This Session"),
897
+ extractSectionText(text, "validation-qc", "Validation / QC")
898
+ ].join("\n");
899
+ const targetText = [
900
+ extractSectionText(text, "next-priorities", "Next Priorities"),
901
+ extractSectionText(text, "risks-blockers", "Risks / Blockers"),
902
+ extractSectionText(text, "next-session-opening-message", "Next Session Opening Message")
903
+ ].join("\n");
904
+
905
+ const topics = extractLifecycleTopics(evidenceText);
906
+ for (const topic of topics) {
907
+ if (hasUnresolvedCarryForward(targetText, topic)) {
908
+ return { ok: false, reason: `completed topic carried forward unresolved: ${topic}` };
909
+ }
910
+ }
911
+
912
+ return { ok: true, reason: "" };
913
+ }
914
+
915
+ function extractLifecycleTopics(text) {
916
+ const topics = new Set();
917
+ for (const match of text.matchAll(/`([^`\n]{2,80})`/g)) {
918
+ const topic = match[1].trim();
919
+ if (!topic || /^dev\/|^docs\/|\.md$|\.txt$|\.json$|^AGENTS\.md$/.test(topic)) continue;
920
+ topics.add(topic);
921
+ }
922
+ return [...topics];
923
+ }
924
+
925
+ function hasUnresolvedCarryForward(text, topic) {
926
+ const escaped = escapeRegExp(topic);
927
+ const pattern = new RegExp(escaped, "ig");
928
+ for (const match of text.matchAll(pattern)) {
929
+ const start = Math.max(0, match.index - 180);
930
+ const end = Math.min(text.length, match.index + topic.length + 180);
931
+ const context = text.slice(start, end);
932
+ if (/\b(monitor-only|follow-up scope|blocked|reopened|re-opened|if new evidence|conditional|no-op)\b|只監察|監察|後續範圍|跟進範圍|阻擋|已重開|明確重開|新證據/i.test(context)) {
933
+ continue;
934
+ }
935
+ if (/\b(investigate|reproduce|pending|todo|unresolved|must start|start with read-only|reliability concern remains open|needs investigation)\b|調查|重查|未解|待辦|仍需|未完成|開始.{0,20}核查|先.{0,20}調查/i.test(context)) {
936
+ return true;
937
+ }
938
+ }
939
+ return false;
940
+ }
941
+
942
+ function fieldValueAfterMarker(text, fieldId) {
943
+ const markerText = `ack:field:${fieldId}`;
944
+ const markerIndex = text.indexOf(markerText);
945
+ if (markerIndex >= 0) {
946
+ const after = text.slice(markerIndex).split(/\r?\n/).slice(1);
947
+ const line = after.find((candidate) => candidate.trim().startsWith("- "));
948
+ if (!line) return "";
949
+ const colonIndex = line.indexOf(":");
950
+ return colonIndex >= 0 ? line.slice(colonIndex + 1).trim() : line.trim();
951
+ }
952
+ const fallback = text.match(/Completed \/ pending \/ risk \/ opening-message lifecycle conflicts resolved or explicitly reclassified:\s*([^\n]+)/i);
953
+ return fallback ? fallback[1].trim() : "";
954
+ }
955
+
956
+ function extractSectionText(text, markerId, headingTitle) {
957
+ const markerText = `ack:section:${markerId}`;
958
+ const markerIndex = text.indexOf(markerText);
959
+ if (markerIndex >= 0) {
960
+ const start = text.indexOf("\n", markerIndex);
961
+ if (start < 0) return "";
962
+ const nextMarker = text.indexOf("<!-- ack:section:", start + 1);
963
+ return text.slice(start + 1, nextMarker >= 0 ? nextMarker : text.length);
964
+ }
965
+
966
+ const headingMatch = new RegExp(`^## ${escapeRegExp(headingTitle)}\\s*$`, "m").exec(text);
967
+ if (!headingMatch) return "";
968
+ const start = headingMatch.index + headingMatch[0].length;
969
+ const nextHeading = /\n##\s+/.exec(text.slice(start));
970
+ return text.slice(start, nextHeading ? start + nextHeading.index : text.length);
971
+ }
972
+
973
+ async function checkRequiredAnchors(root) {
974
+ const rows = [];
975
+ for (const rule of requiredAnchors) {
879
976
  const filePath = path.join(root, rule.target);
880
977
  let text = "";
881
978
  try {
@@ -1072,24 +1169,59 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1072
1169
  // content and any user customization preserved. Step 1 micro-question additions to Scenarios A-E
1073
1170
  // are NOT auto-migrated (user-customizable inline sample wording, not anchor-enforced); users get
1074
1171
  // those on fresh install only or can manually patch following CHANGELOG migration guidance.
1075
- if (targetRel === "dev/rules/onboarding.md" && command === "upgrade" && !targetText.includes("Scenario F. 審視已裝外部工具")) {
1076
- const sourceScenarioFMatch = sourceText.match(/(### Scenario F\. 審視已裝外部工具[\s\S]*?)(?=## Cross-reference to guide\.html)/);
1077
- if (sourceScenarioFMatch && targetText.includes("## Cross-reference to guide.html")) {
1078
- const scenarioFBlock = sourceScenarioFMatch[1];
1079
- return {
1172
+ if (targetRel === "dev/rules/onboarding.md" && command === "upgrade" && !targetText.includes("Scenario F. 審視已裝外部工具")) {
1173
+ const sourceScenarioFMatch = sourceText.match(/(### Scenario F\. 審視已裝外部工具[\s\S]*?)(?=## Cross-reference to guide\.html)/);
1174
+ if (sourceScenarioFMatch && targetText.includes("## Cross-reference to guide.html")) {
1175
+ const scenarioFBlock = sourceScenarioFMatch[1];
1176
+ return {
1080
1177
  ...base,
1081
1178
  action: "merge",
1082
1179
  reason: "insert ### Scenario F block before ## Cross-reference to guide.html (R-030 onboarding pack migration; existing Scenarios A-E content preserved non-destructively)",
1083
1180
  mergedText: targetText.replace("## Cross-reference to guide.html", scenarioFBlock + "## Cross-reference to guide.html")
1084
- };
1085
- }
1086
- }
1087
- if ((targetRel === "CLAUDE.md" || targetRel === "GEMINI.md") && !targetText.includes("AGENTS.md")) {
1088
- return { ...base, action: "conflict", reason: "existing bridge does not route to AGENTS.md" };
1089
- }
1181
+ };
1182
+ }
1183
+ }
1184
+ // v0.3.6+: SESSION_HANDOFF.md gains a non-destructive lifecycle consistency
1185
+ // field. Existing handoff content stays intact; only the missing field and
1186
+ // rule note are inserted around stable ack markers.
1187
+ if (targetRel === "dev/SESSION_HANDOFF.md" && command === "upgrade" && !targetText.includes("ack:field:lifecycle-conflicts-resolved")) {
1188
+ const mergedHandoff = mergeHandoffLifecycleField(targetText);
1189
+ if (!mergedHandoff) {
1190
+ return { ...base, action: "conflict", reason: "SESSION_HANDOFF.md state reconciliation markers were changed; manual merge required to add lifecycle consistency field" };
1191
+ }
1192
+ return {
1193
+ ...base,
1194
+ action: "merge",
1195
+ reason: "insert lifecycle consistency field into State Reconciliation Check (completed work must not carry forward as unresolved next work)",
1196
+ mergedText: mergedHandoff
1197
+ };
1198
+ }
1199
+ if ((targetRel === "CLAUDE.md" || targetRel === "GEMINI.md") && !targetText.includes("AGENTS.md")) {
1200
+ return { ...base, action: "conflict", reason: "existing bridge does not route to AGENTS.md" };
1201
+ }
1090
1202
  return { ...base, action: "skip", reason: "preserve existing file" };
1091
1203
  }
1092
1204
 
1205
+ function mergeHandoffLifecycleField(targetText) {
1206
+ const openingMarker = "<!-- ack:field:opening-message-matches-current-state -->";
1207
+ if (!targetText.includes(openingMarker)) return null;
1208
+
1209
+ const fieldBlock = "<!-- ack:field:lifecycle-conflicts-resolved -->\n- Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD\n";
1210
+ let merged = targetText.replace(openingMarker, `${fieldBlock}${openingMarker}`);
1211
+
1212
+ if (!merged.includes("Lifecycle consistency rule: compare `Completed This Session`")) {
1213
+ const ruleBlock = "Lifecycle consistency rule: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. A completed or verified item must not remain as an unresolved next priority, active risk, or startup instruction unless it is explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with the missing evidence or trigger condition stated.\n\n";
1214
+ const sufficiencyMarker = "<!-- ack:section:handoff-sufficiency-check -->";
1215
+ if (merged.includes(sufficiencyMarker)) {
1216
+ merged = merged.replace(sufficiencyMarker, `${ruleBlock}${sufficiencyMarker}`);
1217
+ } else {
1218
+ merged = `${merged.trimEnd()}\n\n${ruleBlock}`;
1219
+ }
1220
+ }
1221
+
1222
+ return merged;
1223
+ }
1224
+
1093
1225
  function mergeRulePacksRows(targetText, sourceText) {
1094
1226
  const requiredPacks = [
1095
1227
  "dev/rules/onboarding.md",
@@ -1169,10 +1301,10 @@ function printVersionAlignment(result) {
1169
1301
  }
1170
1302
  console.log(` 📦 版本:工具 v${cliVersion} / 項目記錄 v${rootVersion} / npm latest v${npmLatest}`);
1171
1303
  if (npmLatest && compareSemver(npmLatest, cliVersion) > 0) {
1172
- console.log(` npm 有新版(v${npmLatest});doctor 只檢查不修改。要升級時先執行:npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run`);
1304
+ console.log(` npm 有新版(v${npmLatest});doctor 只檢查不修改。要升級時先執行:npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run`);
1173
1305
  console.log(" --dry-run 只預覽、不寫入;確認計劃沒問題後,再去掉 --dry-run 正式升級。");
1174
1306
  } else if (cliVersion !== rootVersion) {
1175
- console.log(" 項目內記錄的 Kit 版本與目前工具版本不同;doctor 只檢查不修改。要對齊時先執行:npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run");
1307
+ console.log(" 項目內記錄的 Kit 版本與目前工具版本不同;doctor 只檢查不修改。要對齊時先執行:npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run");
1176
1308
  console.log(" --dry-run 只預覽、不寫入;確認計劃沒問題後,再去掉 --dry-run 正式升級。");
1177
1309
  }
1178
1310
  }
@@ -1180,13 +1312,13 @@ function printVersionAlignment(result) {
1180
1312
  function getVersionAlignmentNextStep(result) {
1181
1313
  const { cliVersion, rootVersion, npmLatest } = result;
1182
1314
  if (npmLatest && compareSemver(npmLatest, cliVersion) > 0) {
1183
- return `檢查已通過,但 npm 有新版 v${npmLatest}。doctor 沒有修改檔案;建議先執行 npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run。--dry-run 只預覽、不寫入;確認計劃沒問題後,再去掉 --dry-run 正式升級。`;
1315
+ return `檢查已通過,但 npm 有新版 v${npmLatest}。doctor 沒有修改檔案;建議先執行 npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run。--dry-run 只預覽、不寫入;確認計劃沒問題後,再去掉 --dry-run 正式升級。`;
1184
1316
  }
1185
1317
  if (rootVersion === null) {
1186
- return "檢查已通過,但項目版本記錄缺失。doctor 沒有修改檔案;建議先執行 npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run。--dry-run 只預覽、不寫入;確認只會補齊工具維護的版本記錄後,再去掉 --dry-run 正式升級。";
1318
+ return "檢查已通過,但項目版本記錄缺失。doctor 沒有修改檔案;建議先執行 npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run。--dry-run 只預覽、不寫入;確認只會補齊工具維護的版本記錄後,再去掉 --dry-run 正式升級。";
1187
1319
  }
1188
1320
  if (cliVersion !== rootVersion) {
1189
- return "檢查已通過,但項目版本記錄未與目前工具對齊。doctor 沒有修改檔案;建議先執行 npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run。--dry-run 只預覽、不寫入;確認後再去掉 --dry-run 正式升級。";
1321
+ return "檢查已通過,但項目版本記錄未與目前工具對齊。doctor 沒有修改檔案;建議先執行 npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run。--dry-run 只預覽、不寫入;確認後再去掉 --dry-run 正式升級。";
1190
1322
  }
1191
1323
  return null;
1192
1324
  }
@@ -1676,14 +1808,15 @@ function compareSemver(left, right) {
1676
1808
  return 0;
1677
1809
  }
1678
1810
 
1679
- function printUpdateNotice(currentVersion, latestVersion) {
1680
- const releaseUrl = "https://github.com/Adamchanadam/agent-handoff-kit/releases/latest";
1681
- const command = "npx @adamchanadam/agent-handoff-kit@latest <command>";
1682
- const lines = [
1683
- `✨ 有新版可用:${currentVersion} -> ${latestVersion}`,
1684
- `如要使用最新版,執行:${command}`,
1685
- "",
1686
- "如果你是全域安裝:",
1811
+ function printUpdateNotice(currentVersion, latestVersion) {
1812
+ const releaseUrl = "https://github.com/Adamchanadam/agent-handoff-kit/releases/latest";
1813
+ const command = "npx --yes @adamchanadam/agent-handoff-kit@latest <command>";
1814
+ const lines = [
1815
+ `✨ 有新版可用:${currentVersion} -> ${latestVersion}`,
1816
+ `如要使用最新版,執行:${command}`,
1817
+ "這只讓 npm 取得執行工具;doctor 只檢查,不會安裝項目文件。",
1818
+ "",
1819
+ "如果你是全域安裝:",
1687
1820
  "npm install -g @adamchanadam/agent-handoff-kit",
1688
1821
  "",
1689
1822
  "完整 release notes:",
@@ -1724,13 +1857,14 @@ function printInstallNextSteps(root, conflictCount) {
1724
1857
  // question: "is this installed and what do I do next?"
1725
1858
  console.log("📋 如何確認安裝完成:");
1726
1859
  console.log("");
1727
- console.log(" 1. 在 Terminal 執行 npx @adamchanadam/agent-handoff-kit doctor,應該見到「status: passed」");
1860
+ console.log(" 1. 在 Terminal 執行 npx --yes @adamchanadam/agent-handoff-kit@latest doctor,應該見到「status: passed」");
1728
1861
  console.log(" 2. 你的 dev/ 資料夾應該有規則、交接與工作紀錄等檔案");
1729
1862
  console.log(" 3. 在你使用的 AI 工具(Claude Code / Codex / Gemini)開新對話,貼下面起步句");
1730
1863
  console.log("");
1731
1864
  console.log("⚠️ 注意:Agent Handoff Kit 是放在項目資料夾內的一組交接檔案。");
1732
1865
  console.log(" 它沒有圖形介面,不會啟動伺服器,也不會自動替你做事;你需要在 AI 對話中使用它。");
1733
- console.log("");
1866
+ console.log(" `npx --yes ...` 只是讓 npm 取得執行工具;不代表 doctor 會安裝或修改項目文件。");
1867
+ console.log("");
1734
1868
  console.log("------------------------------------------------------------");
1735
1869
  console.log("⚠️ 請注意:下面文字不是 Terminal 指令。");
1736
1870
  console.log("📋 請打開你要使用的 AI 工具,新增一段對話,貼上下面一句:");
@@ -1743,11 +1877,11 @@ function printInstallNextSteps(root, conflictCount) {
1743
1877
  console.log("");
1744
1878
  console.log("💡 之後你熟悉流程後,可改用更直接的開工句:");
1745
1879
  console.log(` Work in ${root}. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.`);
1746
- console.log("");
1747
- console.log("🩺 如要檢查安裝是否完整,可在 Terminal 執行:");
1748
- console.log(" npx @adamchanadam/agent-handoff-kit doctor");
1749
- console.log("============================================================");
1750
- }
1880
+ console.log("");
1881
+ console.log("🩺 如要檢查安裝是否完整,可在 Terminal 執行:");
1882
+ console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
1883
+ console.log("============================================================");
1884
+ }
1751
1885
 
1752
1886
  // R-031 v0.3.1+: Upgrade substantive next-step block. Distinct from install
1753
1887
  // (`printInstallNextSteps`) because the user is not first-time; pushing them through
@@ -1880,11 +2014,11 @@ function printUpgradeNoopShortCircuit(version) {
1880
2014
  console.log("🛠️ 模式:upgrade-existing");
1881
2015
  console.log("🔎 剛完成:檢查所有 Kit 檔案的狀態(含 AGENTS.md、dev/SESSION_HANDOFF.md、dev/PROJECT_INDEX.md 等)。");
1882
2016
  console.log("✅ 結果:你已經是最新版本,沒有檔案需要建立或合併;用戶填寫的內容全部保留現狀。");
1883
- console.log("");
1884
- console.log("🚀 下一步:繼續日常使用即可。如要檢查健康狀態,可執行:");
1885
- console.log(" npx @adamchanadam/agent-handoff-kit doctor");
1886
- console.log("");
1887
- }
2017
+ console.log("");
2018
+ console.log("🚀 下一步:繼續日常使用即可。如要檢查健康狀態,可執行:");
2019
+ console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
2020
+ console.log("");
2021
+ }
1888
2022
 
1889
2023
  function listOrNone(items) {
1890
2024
  if (items.length === 0) return ["- none"];
@@ -1919,14 +2053,27 @@ Commands:
1919
2053
  🔄 upgrade 升級既有 Kit 文件;先用 --dry-run 預演。
1920
2054
  🩺 doctor 檢查必要文件與交接結構是否完整。
1921
2055
 
1922
- After install:
1923
- Do not type the shown "Work in ..." message into Terminal.
1924
- Open your AI tool, start a new chat, and paste it there.
1925
- The default post-install prompt triggers the onboarding pack — AI
1926
- will guide you through scenario selection (coding / research / knowledge /
1927
- learning / other / integrations governance) and walk you through your first task.
1928
- `);
1929
- console.log(`📦 版本:v${version}`);
1930
- console.log(`🛠️ 模式:help ready`);
1931
- console.log(`🚀 下一步:第一次使用先跑 init;既有專案升級用 upgrade --dry-run;要檢查現狀用 doctor。`);
1932
- }
2056
+ After install:
2057
+ Do not type the shown "Work in ..." message into Terminal.
2058
+ Open your AI tool, start a new chat, and paste it there.
2059
+ The default post-install prompt triggers the onboarding pack — AI
2060
+ will guide you through scenario selection (coding / research / knowledge /
2061
+ learning / other / integrations governance) and walk you through your first task.
2062
+
2063
+ Terminal 範例:
2064
+ npx --yes @adamchanadam/agent-handoff-kit@latest init
2065
+ npx --yes @adamchanadam/agent-handoff-kit@latest doctor
2066
+ npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
2067
+
2068
+ 以上才是建議的 npx 用戶路徑。裸寫不帶 --yes / @latest 的 npx doctor
2069
+ 不是本工具的建議用戶路徑,容易先出現 npm 自己的安裝提示。
2070
+
2071
+ 放在 package 名稱前的 --yes 只讓 npm 取得執行工具,避免額外出現
2072
+ "Need to install" 提示。這不會令 doctor 安裝或修改項目文件;
2073
+ doctor 只檢查目前的 Kit 文件。即使資料夾已有 AGENTS.md 或 dev/,
2074
+ npx 仍可能只是先取得 npm 執行工具。
2075
+ `);
2076
+ console.log(`📦 版本:v${version}`);
2077
+ console.log(`🛠️ 模式:help ready`);
2078
+ console.log(`🚀 下一步:第一次使用先跑 npx --yes ... init;既有專案升級用 npx --yes ... upgrade --dry-run;要檢查現狀用 npx --yes ... doctor。`);
2079
+ }
@@ -0,0 +1,19 @@
1
+ # v0.3.6
2
+
3
+ ## 本版新加了甚麼
4
+
5
+ - `doctor` 新增交接生命週期一致性檢查:已完成或已驗證的事項,不應又以未解待辦、風險或下一次開工指令交給下一輪 AI。
6
+ - `dev/SESSION_HANDOFF.md` 的 `State Reconciliation Check` 新增一個欄位,要求 closeout 時明確確認完成/待辦/風險/開工訊息之間沒有矛盾,或已清楚重新分類。
7
+ - 發佈級 QA 新增反例驗收,覆蓋「`doctor` / `upgrade` 已完成,但 opening message 又要求下一輪重新調查」這類交接漂移。
8
+
9
+ ## 對你已有檔案的影響
10
+
11
+ - 既有用戶內容應保留。
12
+ - 升級後,`dev/SESSION_HANDOFF.md` 會補上新的交接對賬欄位。
13
+ - 若舊 handoff 同時寫着某件事已完成、又把同一件事列為未解調查,`doctor` 會提示先修 handoff,不會把這種矛盾視為健康狀態。
14
+
15
+ ## 建議下一步
16
+
17
+ - 已安裝舊版的專案,先執行 `npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run`。
18
+ - 預演結果沒有衝突後,再執行 `npx @adamchanadam/agent-handoff-kit@latest upgrade`。
19
+ - 升級後執行 `npx @adamchanadam/agent-handoff-kit@latest doctor`,確認交接狀態與下一步一致。
@@ -0,0 +1,19 @@
1
+ # v0.3.7
2
+
3
+ ## 本版新加了甚麼
4
+
5
+ 修正舊項目執行 `doctor` 時容易誤會的 `npx` 路徑說明。官方示範統一改用 `npx --yes @adamchanadam/agent-handoff-kit@latest ...`,讓 npm 先取得執行工具的提示不再被誤解成 `doctor` 正在安裝或修改項目。
6
+
7
+ ## 對你已有檔案的影響
8
+
9
+ 本版不改動已安裝項目的交接文件結構。`doctor` 仍只做檢查,不會建立或修改項目文件。README、CLI help、新手介紹頁與操作指南會更清楚分開兩件事:項目內的 Kit 文件,以及電腦用來執行命令的 npm 工具。
10
+
11
+ ## 建議下一步
12
+
13
+ 日常檢查請使用:
14
+
15
+ ```bash
16
+ npx --yes @adamchanadam/agent-handoff-kit@latest doctor
17
+ ```
18
+
19
+ 如你已經有舊版 Kit 文件,先跑 `upgrade --dry-run` 預覽,再決定是否正式升級。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.5",
3
+ "version": "0.3.7",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -88,14 +88,14 @@ At full closeout:
88
88
  3. Update `dev/PROJECT_INDEX.md` if files, stack, commands, entry points, workspace identity, or durable document map changed.
89
89
  4. Check `dev/DOC_SYNC_REGISTRY.md` and record required sync status.
90
90
  5. Record unresolved drift risk, active worktree, parallel workspace, uncommitted changes, or blocked verification.
91
- 6. Complete the `State Reconciliation Check`: it must state when reconciliation happened, which state sections were rewritten or confirmed current, whether stale snapshots remain, and whether the opening message matches current state.
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
- 8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
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.
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
-
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):
91
+ 6. Complete the `State Reconciliation Check`: it must state when reconciliation happened, which state sections were rewritten or confirmed current, whether stale snapshots remain, whether completed / pending / risk / opening-message lifecycle conflicts were resolved, and whether the opening message matches current state. In the same step, run the handoff lifecycle consistency check before declaring handoff ready: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. A completed or verified item must not remain as an unresolved next priority, active risk, or startup instruction unless it is explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with the missing evidence or trigger condition stated.
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
+ 8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
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.
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
+
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):
99
99
 
100
100
  (a) Decisions split check: If `dev/SESSION_HANDOFF.md` contains a decisions-like H2 section (e.g. `## Confirmed Decisions`, `## Decisions`, `## 已定案決策`) with a numbered list of ≥ 30 entries, AI must split the oldest entries (retaining the most recent 8–22 in the handoff hot tier) into `dev/PROJECT_DECISIONS.md` `## Decisions Archive`, newest first. If no such section exists in the handoff, this check is no-op (default for short single-task projects).
101
101
 
@@ -107,14 +107,18 @@ At full closeout, complete this check after updating the state sections above.
107
107
  - Reconciled at: TBD
108
108
  <!-- ack:field:state-sections-rewritten-or-confirmed -->
109
109
  - State sections rewritten or confirmed current: TBD
110
- <!-- ack:field:stale-snapshots-left -->
111
- - Stale snapshots left in this handoff: TBD
112
- <!-- ack:field:opening-message-matches-current-state -->
113
- - Opening message matches current state: TBD
114
- <!-- ack:field:next-ai-can-continue -->
115
- - Next AI can continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history: TBD
116
-
117
- If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready.
110
+ <!-- ack:field:stale-snapshots-left -->
111
+ - Stale snapshots left in this handoff: TBD
112
+ <!-- ack:field:lifecycle-conflicts-resolved -->
113
+ - Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD
114
+ <!-- ack:field:opening-message-matches-current-state -->
115
+ - Opening message matches current state: TBD
116
+ <!-- ack:field:next-ai-can-continue -->
117
+ - Next AI can continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history: TBD
118
+
119
+ If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready.
120
+
121
+ Lifecycle consistency rule: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. A completed or verified item must not remain as an unresolved next priority, active risk, or startup instruction unless it is explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with the missing evidence or trigger condition stated.
118
122
 
119
123
  <!-- ack:section:handoff-sufficiency-check -->
120
124
  ## Handoff Sufficiency Check