@adamchanadam/agent-handoff-kit 0.3.15 → 0.3.17

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.15`。這是早期可用版本,仍在持續完善中。
3
+ 狀態:目前版本為 `v0.3.17` 候選準備。這是早期可用版本,仍在持續完善中。
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
 
@@ -261,7 +261,7 @@ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templa
261
261
 
262
262
  ## 目前限制
263
263
 
264
- - 目前版本為 `v0.3.15`。
264
+ - 目前版本為 `v0.3.17` 候選準備;npm 已正式發佈版本仍以 registry `latest` 為準。
265
265
  - 這是早期可用版本,仍在持續完善中。
266
266
  - 升級合併屬窄範圍策略,不是完整的複雜合併工具。
267
267
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
@@ -498,23 +498,6 @@ async function runInstall(command, root, options, version) {
498
498
  return;
499
499
  }
500
500
 
501
- // R-031.3 v0.3.3+: For upgrade scenarios, capture pre-upgrade root template version
502
- // before the create/merge/inject loops mutate PROJECT_INDEX. This snapshot is later
503
- // passed to printWhatsnew so the version range narrative reflects the actual user
504
- // journey (v{pre-upgrade} → v{current CLI}), not the post-inject state which would
505
- // make printWhatsnew see fromVersion == toVersion and skip the summary entirely.
506
- let preUpgradeRootVersion = null;
507
- if (command === "upgrade") {
508
- try {
509
- const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
510
- const text = await readFile(indexPath, "utf8");
511
- const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
512
- if (m) preUpgradeRootVersion = m[1];
513
- } catch {
514
- // ignore
515
- }
516
- }
517
-
518
501
  printPlan(command, root, mode, plan, version, options.dryRun);
519
502
 
520
503
  if (options.dryRun) {
@@ -619,15 +602,12 @@ async function runInstall(command, root, options, version) {
619
602
  reportRel: path.relative(root, report)
620
603
  });
621
604
 
622
- // R-031 v0.3.1+: install vs upgrade narrative split.
623
- // R-031.2 v0.3.2+: printUpgradeNextSteps async (awaits inline whatsnew print).
624
- // R-031.3 v0.3.3+: pass preUpgradeRootVersion so whatsnew narrative reflects the
625
- // actual user journey (v{pre-upgrade} → v{current}), not the post-inject state.
626
- if (command === "upgrade") {
627
- await printUpgradeNextSteps(root, conflicts.length, version, preUpgradeRootVersion);
628
- } else {
629
- printInstallNextSteps(root, conflicts.length, mode, skippedCount);
630
- }
605
+ // R-031 v0.3.1+: install vs upgrade narrative split.
606
+ if (command === "upgrade") {
607
+ printUpgradeNextSteps(root, conflicts.length);
608
+ } else {
609
+ printInstallNextSteps(root, conflicts.length, mode, skippedCount);
610
+ }
631
611
 
632
612
  // R-024 upgrade.done self-check: after substantive upgrade writes, run doctor automatically.
633
613
  // The user must see whether the merged state actually reaches a clean health state.
@@ -2074,7 +2054,7 @@ function printInstallNextSteps(root, conflictCount, mode = "first-install", skip
2074
2054
  // R-031 v0.3.1+: Upgrade substantive next-step block. Distinct from install
2075
2055
  // (`printInstallNextSteps`) because the user is not first-time; pushing them through
2076
2056
  // the onboarding canonical phrase resets context they already have.
2077
- async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRootVersion) {
2057
+ function printUpgradeNextSteps(root, conflictCount) {
2078
2058
  console.log("");
2079
2059
  console.log("============================================================");
2080
2060
  if (conflictCount > 0) {
@@ -2086,113 +2066,16 @@ async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRoo
2086
2066
  console.log("============================================================");
2087
2067
  return;
2088
2068
  }
2089
- console.log("✅ 升級完成:Kit 檔案已更新到最新版本");
2090
- console.log("============================================================");
2091
- // R-031.2 v0.3.2+: Inline whatsnew summary — directly surface what changed in this
2092
- // version (and any intermediate versions the user skipped).
2093
- // R-031.3 v0.3.3+: fromVersion now uses pre-upgrade snapshot (captured before
2094
- // inject mutated PROJECT_INDEX), so the range narrative reflects actual user
2095
- // journey instead of degenerate v{current} → v{current}.
2096
- await printWhatsnew(root, version, preUpgradeRootVersion);
2097
- console.log("📋 如你正在進行中的工作對話已熟悉 Agent Handoff Kit,繼續使用原本的開工方式即可,無需重新做新手引導。");
2098
- console.log("");
2099
- console.log("💡 如想了解本版本新加了甚麼功能,可選用以下開工句(非強制):");
2100
- console.log("------------------------------------------------------------");
2101
- console.log(`Work in ${root}. I just upgraded agent-handoff-kit. Brief me on what changed in this version and what I should pay attention to.`);
2102
- console.log("------------------------------------------------------------");
2103
- console.log("");
2104
- console.log("🩺 升級驗收會在下方自動執行 doctor;若全綠即升級完成。");
2105
- console.log("============================================================");
2106
- }
2107
-
2108
- // R-031.2 v0.3.2+: Print whatsnew summaries for the version range crossed by this
2109
- // upgrade. fromVersion = user root template metadata version (the state before
2110
- // upgrade; R-016 preserves this row so it still reflects the prior state after
2111
- // upgrade finishes). toVersion = current CLI version. Range is exclusive-fromVersion
2112
- // inclusive-toVersion. Limit to first + last when crossing > 3 versions (elide middle).
2113
- async function printWhatsnew(root, toVersion, fromVersionOverride) {
2114
- // R-031.3 v0.3.3+: fromVersion sourced from explicit override (pre-upgrade snapshot)
2115
- // when called from upgrade flow; falls back to reading current PROJECT_INDEX
2116
- // template version row otherwise.
2117
- let fromVersion = fromVersionOverride ?? null;
2118
- if (!fromVersion) {
2119
- const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
2120
- try {
2121
- const text = await readFile(indexPath, "utf8");
2122
- const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
2123
- if (m) fromVersion = m[1];
2124
- } catch {
2125
- return;
2126
- }
2127
- }
2128
- if (!fromVersion || !isStableSemver(fromVersion) || compareSemver(fromVersion, toVersion) >= 0) {
2129
- return;
2130
- }
2131
-
2132
- const whatsnewDir = path.join(packageRoot, "docs/whatsnew");
2133
- let entries = [];
2134
- try {
2135
- entries = await readdir(whatsnewDir);
2136
- } catch {
2137
- console.log(`💡 本版 release notes:https://github.com/Adamchanadam/agent-handoff-kit/releases/tag/v${toVersion}`);
2138
- console.log("");
2139
- return;
2140
- }
2141
-
2142
- const relevant = entries
2143
- .filter((name) => /^v\d+\.\d+\.\d+\.md$/.test(name))
2144
- .map((name) => name.replace(/^v/, "").replace(/\.md$/, ""))
2145
- .filter((v) => compareSemver(v, fromVersion) > 0 && compareSemver(v, toVersion) <= 0)
2146
- .sort((a, b) => compareSemver(a, b));
2147
-
2148
- if (relevant.length === 0) {
2149
- console.log(`💡 本版 release notes:https://github.com/Adamchanadam/agent-handoff-kit/releases`);
2150
- console.log(` (v${fromVersion} → v${toVersion} 跨版本的完整變更見 GitHub Release 全列表)`);
2151
- console.log("");
2152
- return;
2153
- }
2154
-
2155
- // R-031.3 v0.3.3+: Deep range narrative — if fromVersion considerably older than
2156
- // the oldest available whatsnew, explicitly tell user this is a multi-version
2157
- // upgrade where older changelog only lives on GitHub Release (not shipped).
2158
- // Heuristic: deep range if fromVersion's major < oldest's major, or same major
2159
- // but minor differs by ≥ 1 (i.e. fromVersion is at least one minor release older
2160
- // than the oldest available whatsnew).
2161
- const oldestAvailable = relevant[0];
2162
- const [fromMajor, fromMinor] = fromVersion.split(".").map((n) => Number.parseInt(n, 10));
2163
- const [oldMajor, oldMinor] = oldestAvailable.split(".").map((n) => Number.parseInt(n, 10));
2164
- const isDeepRange = (fromMajor < oldMajor) || (fromMajor === oldMajor && fromMinor < oldMinor);
2165
- if (isDeepRange) {
2166
- console.log(`💡 注意:本次升級 v${fromVersion} → v${toVersion} 跨度較大;本工具的版本說明只涵蓋由 v${oldestAvailable} 起的 ${relevant.length} 個版本。較舊版本(v${fromVersion} 至 v${oldestAvailable} 之前)的完整變更見:`);
2167
- console.log(` https://github.com/Adamchanadam/agent-handoff-kit/releases`);
2168
- console.log("");
2169
- }
2170
-
2171
- console.log(`📰 本次升級涵蓋 ${relevant.length} 個版本的版本說明(${isDeepRange ? `由 v${oldestAvailable} 起` : `v${fromVersion} → v${toVersion}`}):`);
2172
- console.log("");
2173
-
2174
- const toShow = relevant.length <= 3 ? relevant : [relevant[0], relevant[relevant.length - 1]];
2175
- const elidedCount = relevant.length > 3 ? relevant.length - 2 : 0;
2176
-
2177
- for (let i = 0; i < toShow.length; i += 1) {
2178
- const v = toShow[i];
2179
- const filePath = path.join(whatsnewDir, `v${v}.md`);
2180
- try {
2181
- const content = await readFile(filePath, "utf8");
2182
- console.log(content.trimEnd());
2183
- console.log("");
2184
- if (i === 0 && elidedCount > 0) {
2185
- console.log(` ⋯ 中間 ${elidedCount} 個版本的版本說明略;完整列表見 https://github.com/Adamchanadam/agent-handoff-kit/releases ⋯`);
2186
- console.log("");
2187
- }
2188
- } catch {
2189
- console.log(`(v${v} release notes 檔缺失,見 https://github.com/Adamchanadam/agent-handoff-kit/releases/tag/v${v})`);
2190
- console.log("");
2191
- }
2192
- }
2193
- console.log("------------------------------------------------------------");
2194
- console.log("");
2195
- }
2069
+ console.log("✅ 升級完成:Kit 檔案已更新到最新版本");
2070
+ console.log("============================================================");
2071
+ console.log("📋 如你正在進行中的工作對話已熟悉 Agent Handoff Kit,繼續使用原本的開工方式即可,無需重新做新手引導。");
2072
+ console.log("");
2073
+ console.log("💡 版本詳情不在升級流程內展開;如需要,可稍後查看 GitHub Release:");
2074
+ console.log(" https://github.com/Adamchanadam/agent-handoff-kit/releases/latest");
2075
+ console.log("");
2076
+ console.log("🩺 升級驗收會在下方自動執行 doctor;若全綠即升級完成。");
2077
+ console.log("============================================================");
2078
+ }
2196
2079
 
2197
2080
  // R-031 v0.3.1+: Upgrade no-op short-circuit. When the user runs upgrade on a root
2198
2081
  // already at latest version (skip all / create 0 / merge 0 / conflict 0), print a
package/package.json CHANGED
@@ -1,17 +1,16 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.15",
3
+ "version": "0.3.17",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "agent-handoff-kit": "bin/agent-handoff-kit.mjs"
8
8
  },
9
9
  "files": [
10
- "bin/",
11
- "runtime-core/",
12
- "packs/",
13
- "docs/whatsnew/",
14
- "README.md",
10
+ "bin/",
11
+ "runtime-core/",
12
+ "packs/",
13
+ "README.md",
15
14
  "LICENSE"
16
15
  ],
17
16
  "scripts": {
@@ -91,8 +91,8 @@ At full closeout:
91
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
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
- 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. 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.
94
+ 9. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the fenced opening message in `dev/SESSION_HANDOFF.md`, then read it back or run the project's prompt mirror check before declaring closeout ready. `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.
95
+ 10. Show a short closeout card, then provide the copy-paste-ready next-session opening message by pasting the read-back `START_NEXT_SESSION_PROMPT.txt` content inside a fenced `text` code block. Do not compose a separate final-response prompt; the final response is a display of the persisted prompt, not a third source of truth.
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):
@@ -1,13 +0,0 @@
1
- # v0.3.1
2
-
3
- ## 本版新加了甚麼
4
-
5
- 改善升級流程的提示文字。完成升級、再次執行 `upgrade`、或沒有任何檔案需要更新時,工具會顯示不同提示,避免把「已經是最新版本」誤說成「安裝完成」。
6
-
7
- ## 對你已有檔案的影響
8
-
9
- 本版只調整工具輸出文字,不會改動既有項目內容,也不會改變已安裝的 Kit 文件結構。
10
-
11
- ## 建議下一步
12
-
13
- 執行 `doctor` 檢查項目健康即可。
@@ -1,19 +0,0 @@
1
- # v0.3.10
2
-
3
- ## 本版新加了甚麼
4
-
5
- 改善第一次安裝後的實際使用流程。終端機完成安裝後,提示會更清楚地把「終端機動作」與「AI 對話下一步」分開;新手引導會用 5 步幫用戶選情境、問背景、收斂第一個小任務,再等用戶確認後才開始正式工作。
6
-
7
- ## 對你已有檔案的影響
8
-
9
- 本版會保留既有項目內容。升級時若發現 `CLAUDE.md` 被 AI 改成一份很長的規則文件,工具會把它恢復為短橋接檔,避免 Claude Code 把橋接檔當成第二套規則來源。`GEMINI.md` 也同步說明 Antigravity CLI 與 Gemini CLI 遷移期的入口關係。
10
-
11
- ## 建議下一步
12
-
13
- 升級前可先預演:
14
-
15
- ```bash
16
- npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
17
- ```
18
-
19
- 確認沒有衝突後再升級。升級完成後,如你是第一次使用這個項目,請把工具顯示的完整起步句貼到 AI 對話,而不是留在終端機繼續操作;舊項目升級用戶則照原本開工方式繼續即可。
@@ -1,19 +0,0 @@
1
- # v0.3.11
2
-
3
- ## 本版新加了甚麼
4
-
5
- 本版把 v0.3.10 發佈後留下的用戶旅程檢查補成長期守門。重點不是增加新功能,而是把已驗證的首次安裝、升級、衝突停手與公開文件一致性,轉成每次發佈前都會跑的檢查。
6
-
7
- ## 對你已有檔案的影響
8
-
9
- 既有項目不用重裝。升級時若沒有需要合併的內容,工具不會假裝完成一件大事;若遇到不能安全判斷的衝突,會清楚停手並提示先處理衝突。舊版本升上來時,工具也會保留既有資料與本地規則。
10
-
11
- ## 建議下一步
12
-
13
- 升級前可先預演:
14
-
15
- ```bash
16
- npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
17
- ```
18
-
19
- 如果預演沒有 conflict,再執行正式升級。升級後可用 `doctor` 檢查項目是否完整;第一次使用的新項目,仍按安裝後顯示的起步句進入 AI 對話。
@@ -1,19 +0,0 @@
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 保存交接。
@@ -1,23 +0,0 @@
1
- # v0.3.13
2
-
3
- ## 本版新加了甚麼
4
-
5
- 本版修正升級後自動檢查失敗時的下一步提示。若 `upgrade` 已經執行,但自動 `doctor` 發現某個保留檔案真的缺少必要段落,CLI 會列出缺失檔案、檢查名稱與缺少文字,並給出交給 AI 非破壞性修補的步驟;不再只叫新手回頭跑 `upgrade --dry-run`。
6
-
7
- 同時,本版把可重用操作程序的歸位規則收斂到既有 `agent-governance` pack:長期操作方法應進入相關 rule pack 或已登記 reference,不應只寫入 handoff / log 當作完成。
8
-
9
- ## 對你已有檔案的影響
10
-
11
- 既有項目不用重裝。`START_NEXT_SESSION_PROMPT.txt` 仍只是 closeout 便利副本;若它只是落後於 `dev/SESSION_HANDOFF.md`,普通 `doctor` 只會提醒,不會把項目判定為失敗。
12
-
13
- 若升級後看到 anchor 缺失,代表某個保留檔案缺少 Kit 需要的固定段落。工具不會覆寫你的內容;你應把完整 `doctor` 輸出交給 AI,請它按缺失文字補回對應段落。
14
-
15
- ## 建議下一步
16
-
17
- 升級前可先預演:
18
-
19
- ```bash
20
- npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
21
- ```
22
-
23
- 如果預演沒有 conflict,再執行正式升級。正式升級後若自動檢查失敗,請按 CLI 顯示的「怎樣修」步驟交給 AI 修補;不要把 `upgrade --dry-run` 當成修補動作。
@@ -1,29 +0,0 @@
1
- # v0.3.14
2
-
3
- ## 本版新加了甚麼
4
-
5
- 本版修正舊版項目跨版本升級時的交接狀態誤判。部分由很早期版本升級的項目,`upgrade` 會補入新的 lifecycle 欄位;舊工具曾把欄位填成 `TBD`,然後同一次升級後自動 `doctor` 又把這個 `TBD` 判定為失敗。
6
-
7
- 現在升級工具會把這類欄位明確標記為「由升級重新分類,下一次 closeout 再核對」,避免工具自己寫入一個會被自己拒絕的值。
8
-
9
- 同時,本版把 rules / packs 路由與可重用程序入庫範圍加入發佈前全面檢,確認自然語言任務能導向相應 pack,而不是隨意新建治理文件或只寫在 handoff / log。
10
-
11
- 另外,本版把 `START_NEXT_SESSION_PROMPT.txt` 與 handoff opening message 的比對方法收斂到固定檢查器。檢查器會先錨定真正的下一次開工訊息,再正規化 CRLF / LF 換行符,避免只因換行風格不同就誤報內容不一致。
12
-
13
- ## 對你已有檔案的影響
14
-
15
- 既有項目不用重裝。若你是由舊版 Kit 升級,工具可能會在 `dev/SESSION_HANDOFF.md` 補入 lifecycle consistency 欄位;這是為了讓下一次 closeout 能核對「已完成的事是否仍被帶成未解待辦」。
16
-
17
- 工具仍會保留既有交接內容,不會用新版模板覆寫你的工作紀錄。若 `doctor` 指出其他真實缺失,仍應把完整輸出交給 AI 非破壞性修補。
18
-
19
- 若只出現 prompt convenience copy 的換行符差異,這不是內容損壞;正常 `doctor` 不會因此阻擋你繼續工作。
20
-
21
- ## 建議下一步
22
-
23
- 已安裝舊版的項目可先預演:
24
-
25
- ```bash
26
- npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
27
- ```
28
-
29
- 如果預演沒有 conflict,再執行正式升級。升級後若自動 `doctor` 通過,即可繼續使用;若仍有缺失,請把完整檢查輸出交給 AI 修補,不要用重裝覆寫既有內容。
@@ -1,27 +0,0 @@
1
- # v0.3.15
2
-
3
- ## 本版新加了甚麼
4
-
5
- 本版修正一個真實舊項目升級後仍會被自動檢查擋住的情況。
6
-
7
- 如果項目已經有新版 lifecycle 欄位,但欄位值仍是舊模板留下的 TBD,而 `Completed This Session` 或 `Validation / QC` 已經有實際內容,舊版升級流程可能只更新版本 metadata,沒有修正這個舊 placeholder。結果是工具先顯示升級完成,隨後同一次自動 `doctor` 又判定 handoff lifecycle consistency 缺失。
8
-
9
- 現在 upgrade 會在確認項目記錄版本落後於目前 CLI 時,安全地把這類舊 placeholder 重新分類為 upgrade migration 狀態,並保留原有交接內容。這令升級後自動檢查能通過,同時仍要求下一次 closeout 正常核對已完成工作、下一步和風險是否一致。
10
-
11
- 本版同時把這個真實路徑加入發佈前自動場景檢查,作為 `qa:release` scenario 3c;未來候選版本若再出現相同組合,會在 publish 前被擋下。
12
-
13
- ## 對你已有檔案的影響
14
-
15
- 既有項目不用重裝。若你的項目本來已經有 lifecycle 欄位,但欄位仍是 TBD,upgrade 可能會把該欄位改成 `Reclassified at upgrade` 說明。這是工具對舊模板狀態的安全遷移,不會覆寫你的 Completed、Validation、Next Priorities 或其他工作紀錄。
16
-
17
- 若 handoff 本身真的仍有完成事項與待辦事項互相矛盾,下一次 closeout 仍應由 AI 正常整理;本版只處理舊 placeholder 造成的升級自撞,不把 AI 對專案內容的判斷交給 installer 猜測。
18
-
19
- ## 建議下一步
20
-
21
- 已安裝舊版的項目可先預演:
22
-
23
- ```bash
24
- npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
25
- ```
26
-
27
- 如果預演沒有 conflict,再執行正式升級。升級後若自動 doctor 通過,即可繼續使用;若仍有缺失,請把完整檢查輸出交給 AI 修補,不要用重裝覆寫既有內容。
@@ -1,13 +0,0 @@
1
- # v0.3.2
2
-
3
- ## 本版新加了甚麼
4
-
5
- `doctor` 和 `init` 會顯示「項目狀態速覽」,包括工具版本、項目記錄版本、npm 最新版本、上次收工時間,以及項目首次安裝距今多久。`upgrade` 完成後也會直接顯示本版重點,讓使用者不必再另外查找更新說明。
6
-
7
- ## 對你已有檔案的影響
8
-
9
- 本版只改善工具提示與狀態顯示,不會改動既有項目內容,也不會改變已安裝的 Kit 文件結構。
10
-
11
- ## 建議下一步
12
-
13
- 執行 `doctor` 檢查項目健康,並留意輸出中的「項目狀態速覽」。
@@ -1,13 +0,0 @@
1
- # v0.3.3
2
-
3
- ## 本版新加了甚麼
4
-
5
- 修正升級後的版本提示矛盾。完成 `upgrade` 後,`doctor` 不應再說項目版本落後於目前工具版本。若使用者從較舊版本直接升級到本版,工具也會提示這次跨度較大,並引導使用者查看 GitHub Release 的完整歷史說明。
6
-
7
- ## 對你已有檔案的影響
8
-
9
- 本版不會改動使用者填寫的項目內容。`upgrade` 後,`dev/PROJECT_INDEX.md` 內的「Agent Handoff Kit template version」資料列會更新為目前版本;其他由使用者填寫的資料列會保留。
10
-
11
- ## 建議下一步
12
-
13
- 執行 `doctor` 檢查項目健康即可。
@@ -1,17 +0,0 @@
1
- # v0.3.4
2
-
3
- ## 本版新加了甚麼
4
-
5
- 本版修補升級後版本敘事不一致的問題。既有專案執行 `upgrade` 後,`dev/PROJECT_INDEX.md` 內的「Agent Handoff Kit template version」資料列會在合併完成後再更新為目前 CLI 版本,避免先更新、後又被舊合併結果覆蓋。
6
-
7
- 升級工具也會辨認「只有版本資料列過期」的情況。即使沒有新增檔案、沒有合併檔案、沒有衝突,只要這一列仍是舊版本,就不會誤報「已經是最新版本,沒有檔案需要建立或合併」。
8
-
9
- ## 對你已有檔案的影響
10
-
11
- 本版只會更新 `dev/PROJECT_INDEX.md` 的 template version metadata。這一列屬工具維護的模板資料,不是你填寫的項目內容。你在 External Sources、Fact Base、Workspace Identity 等表格中填過的內容仍會保留。
12
-
13
- 升級紀錄也新增 metadata section,會寫明這次是否更新了版本資料列,方便日後追溯。
14
-
15
- ## 建議下一步
16
-
17
- 執行 `upgrade` 後再執行 `doctor`。若 `doctor` 顯示 `status: passed`,並且項目狀態速覽不再提示 root 落後 CLI,即代表這次熱修已生效。
@@ -1,20 +0,0 @@
1
- # v0.3.5
2
-
3
- ## 本版新加了甚麼
4
-
5
- - `upgrade` 補齊 `dev/RULE_PACKS.md` 時會保留用戶自訂 rows,不再用整份模板覆寫。
6
- - 如 `dev/RULE_PACKS.md` 的 routing table 表頭已被改動,工具會回報衝突並停手,不會猜測合併。
7
- - `doctor` 明確說明自己只檢查、不修改;版本不齊時會先建議 `upgrade --dry-run`。
8
- - `init` / `upgrade` / `doctor` 的提示文字更清楚,方便非技術新手分清 Terminal 檢查與 AI 對話下一步。
9
-
10
- ## 對你已有檔案的影響
11
-
12
- - 既有用戶內容應保留。
13
- - `dev/RULE_PACKS.md` 只會補 Kit 需要的 routing rows;你自己新增的任務路由 rows 應保留。
14
- - 如果你手動改過 routing table 表頭,升級可能會停在衝突狀態,等你或 AI 判斷怎樣合併。
15
-
16
- ## 建議下一步
17
-
18
- - 已安裝舊版的專案,先執行 `npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run`。
19
- - 預演結果沒有衝突後,再執行 `npx @adamchanadam/agent-handoff-kit@latest upgrade`。
20
- - 升級後執行 `npx @adamchanadam/agent-handoff-kit@latest doctor`,確認狀態通過。
@@ -1,19 +0,0 @@
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`,確認交接狀態與下一步一致。
@@ -1,19 +0,0 @@
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` 預覽,再決定是否正式升級。
@@ -1,19 +0,0 @@
1
- # v0.3.8
2
-
3
- ## 本版新加了甚麼
4
-
5
- 修正舊項目升級時的狀態提示:如果 Kit 檔案已是最新版,但交接文件仍有待核對的 closeout 欄位,`upgrade` 不再說可以繼續日常使用,而會提示先請 AI 修正交接狀態。
6
-
7
- ## 對你已有檔案的影響
8
-
9
- 本版不會自動覆寫你的 handoff 內容,也不會替你假裝已完成 closeout。`doctor` 會繼續指出需要修的交接結構;`upgrade` 只負責把「檔案已最新」與「交接狀態仍需核對」分清楚。
10
-
11
- ## 建議下一步
12
-
13
- 升級後如看到交接狀態提示,請執行:
14
-
15
- ```bash
16
- npx --yes @adamchanadam/agent-handoff-kit@latest doctor
17
- ```
18
-
19
- 然後把輸出貼給 AI,請它先做 closeout 狀態核對,不要重裝或覆寫項目文件。
@@ -1,19 +0,0 @@
1
- # v0.3.9
2
-
3
- ## 本版新加了甚麼
4
-
5
- 修正交接狀態檢查的一個誤判:如果 handoff 已明確寫出「已解決」,但同一句同時提到仍有下一步要做,`doctor` 不應把它當成未完成。
6
-
7
- ## 對你已有檔案的影響
8
-
9
- 本版不會覆寫你的 handoff 內容。它只令 `doctor` 更準確:真正未收口的交接仍會被指出;已明確收口但保留後續待辦的文字,不應再被誤殺。
10
-
11
- ## 建議下一步
12
-
13
- 升級後照常執行:
14
-
15
- ```bash
16
- npx --yes @adamchanadam/agent-handoff-kit@latest doctor
17
- ```
18
-
19
- 如果 `doctor` 通過,就可以繼續日常使用。如果它指出 handoff 需要修補,請把輸出貼給 AI,先修交接狀態,不要重裝覆蓋項目文件。