@adamchanadam/agent-handoff-kit 0.3.7 → 0.3.9

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.7`。這是早期可用版本,仍在持續完善中。
3
+ 狀態:目前版本為 `v0.3.9`。這是早期可用版本,仍在持續完善中。
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
 
@@ -248,8 +248,8 @@ Agent Handoff Kit 同 [Adam-AI-Instructions](https://github.com/prompt-templates
248
248
 
249
249
  ## 目前限制
250
250
 
251
- - 目前版本為 `v0.3.7`。
251
+ - 目前版本為 `v0.3.9`。
252
252
  - 這是早期可用版本,仍在持續完善中。
253
253
  - 升級合併屬窄範圍策略,不是完整的複雜合併工具。
254
254
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
255
- - 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
255
+ - 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
@@ -490,21 +490,22 @@ async function runInstall(command, root, options, version) {
490
490
  && planConflictCount === 0
491
491
  && !projectIndexVersionNeedsInject;
492
492
 
493
- if (isUpgradeNoopAtPlanTime) {
494
- printCard(version, "continuity ready", "o.o");
495
- console.log(`command: ${command}`);
496
- console.log(`current directory: ${process.cwd()}`);
497
- console.log(`selected root: ${root}`);
498
- console.log(`mode: ${mode}`);
493
+ if (isUpgradeNoopAtPlanTime) {
494
+ const noOpHealth = await assessUpgradeNoopHealth(root);
495
+ printCard(version, "continuity ready", "o.o");
496
+ console.log(`command: ${command}`);
497
+ console.log(`current directory: ${process.cwd()}`);
498
+ console.log(`selected root: ${root}`);
499
+ console.log(`mode: ${mode}`);
499
500
  console.log("");
500
501
  console.log(`📋 計劃預覽:create 0 / merge 0 / skip ${planSkipCount} / conflict 0 — 沒有檔案需要建立或合併。`);
501
502
  if (options.dryRun) {
502
- console.log("");
503
- console.log("dry-run: no files written");
504
- }
505
- printUpgradeNoopShortCircuit(version);
506
- return;
507
- }
503
+ console.log("");
504
+ console.log("dry-run: no files written");
505
+ }
506
+ printUpgradeNoopShortCircuit(version, noOpHealth);
507
+ return;
508
+ }
508
509
 
509
510
  // R-031.3 v0.3.3+: For upgrade scenarios, capture pre-upgrade root template version
510
511
  // before the create/merge/inject loops mutate PROJECT_INDEX. This snapshot is later
@@ -888,55 +889,45 @@ function normalizePrompt(text) {
888
889
 
889
890
  function assessHandoffLifecycleConsistency(text) {
890
891
  const fieldValue = fieldValueAfterMarker(text, "lifecycle-conflicts-resolved");
891
- if (fieldValue && /\b(no|blocked|uncertain)\b|否|阻擋|不確定/i.test(fieldValue)) {
892
+ if (isAffirmativeLifecycleFieldValue(fieldValue)) {
893
+ return { ok: true, reason: "" };
894
+ }
895
+ if (isUnresolvedLifecycleFieldValue(fieldValue)) {
892
896
  return { ok: false, reason: "lifecycle field is explicitly unresolved" };
893
897
  }
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
- }
898
+ if (isPlaceholderLifecycleFieldValue(fieldValue) && hasSubstantiveHandoffState(text)) {
899
+ return { ok: false, reason: "lifecycle field is still placeholder after handoff content changed" };
910
900
  }
911
-
912
901
  return { ok: true, reason: "" };
913
902
  }
914
903
 
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];
904
+ function isAffirmativeLifecycleFieldValue(value) {
905
+ const trimmed = (value || "").trim();
906
+ return /^(yes|resolved|confirmed|complete|completed|ok|passed|all clear)\b|^(是|已|完成|已完成|已解決|已核對|已確認|通過)\b/i.test(trimmed);
923
907
  }
924
908
 
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;
909
+ function isUnresolvedLifecycleFieldValue(value) {
910
+ return /\b(no|blocked|uncertain)\b|否|阻擋|不確定/i.test(value || "");
911
+ }
912
+
913
+ function isPlaceholderLifecycleFieldValue(value) {
914
+ return !value || /\b(TBD|todo|pending|unverified|unknown|needs-review)\b|待核對|待確認|未核對|未確認/i.test(value);
915
+ }
916
+
917
+ function hasSubstantiveHandoffState(text) {
918
+ const sections = [
919
+ extractSectionText(text, "completed-this-session", "Completed This Session"),
920
+ extractSectionText(text, "validation-qc", "Validation / QC")
921
+ ].join("\n");
922
+ const body = sections.replace(/```[\s\S]*?```/g, "");
923
+ return body.split(/\r?\n/).some((line) => {
924
+ const trimmed = line.trim();
925
+ if (!trimmed || trimmed.startsWith("##") || trimmed.startsWith("<!--")) return false;
926
+ if (/^Record only work actually completed/i.test(trimmed)) return false;
927
+ if (/\bTBD\b|待定|待核對|未適用/i.test(trimmed)) return false;
928
+ const normalized = trimmed.replace(/^[\d.*\-)\s]+/, "").replace(/[`\s#|:\-*/()[\].,;,。;、]/g, "");
929
+ return normalized.length > 20;
930
+ });
940
931
  }
941
932
 
942
933
  function fieldValueAfterMarker(text, fieldId) {
@@ -2008,14 +1999,31 @@ async function printWhatsnew(root, toVersion, fromVersionOverride) {
2008
1999
  // short factual message and return. Saves disk (no migration report) + reduces noise
2009
2000
  // (no self-check doctor) + avoids misleading "安裝完成" framing for an idempotent
2010
2001
  // operation where nothing changed.
2011
- function printUpgradeNoopShortCircuit(version) {
2012
- console.log("");
2013
- console.log(`📦 版本:v${version}`);
2014
- console.log("🛠️ 模式:upgrade-existing");
2002
+ async function assessUpgradeNoopHealth(root) {
2003
+ try {
2004
+ const handoffText = await readFile(path.join(root, "dev/SESSION_HANDOFF.md"), "utf8");
2005
+ return { handoffLifecycle: assessHandoffLifecycleConsistency(handoffText) };
2006
+ } catch {
2007
+ return { handoffLifecycle: { ok: false, reason: "dev/SESSION_HANDOFF.md unreadable" } };
2008
+ }
2009
+ }
2010
+
2011
+ function printUpgradeNoopShortCircuit(version, health = { handoffLifecycle: { ok: true } }) {
2012
+ console.log("");
2013
+ console.log(`📦 版本:v${version}`);
2014
+ console.log("🛠️ 模式:upgrade-existing");
2015
2015
  console.log("🔎 剛完成:檢查所有 Kit 檔案的狀態(含 AGENTS.md、dev/SESSION_HANDOFF.md、dev/PROJECT_INDEX.md 等)。");
2016
- console.log("✅ 結果:你已經是最新版本,沒有檔案需要建立或合併;用戶填寫的內容全部保留現狀。");
2016
+ if (health.handoffLifecycle?.ok) {
2017
+ console.log("✅ 結果:你已經是最新版本,沒有檔案需要建立或合併;用戶填寫的內容全部保留現狀。");
2018
+ console.log("");
2019
+ console.log("🚀 下一步:繼續日常使用即可。如要檢查健康狀態,可執行:");
2020
+ console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
2021
+ console.log("");
2022
+ return;
2023
+ }
2024
+ console.log("⚠️ 結果:Kit 檔案已是最新版本,沒有檔案需要建立或合併;但交接狀態仍需 AI closeout 核對。");
2017
2025
  console.log("");
2018
- console.log("🚀 下一步:繼續日常使用即可。如要檢查健康狀態,可執行:");
2026
+ console.log("🚀 下一步:先跑 doctor 取得待修項,再把輸出貼給 AI;不要重裝或覆寫用戶內容。");
2019
2027
  console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
2020
2028
  console.log("");
2021
2029
  }
@@ -0,0 +1,19 @@
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 狀態核對,不要重裝或覆寫項目文件。
@@ -0,0 +1,19 @@
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,先修交接狀態,不要重裝覆蓋項目文件。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.7",
3
+ "version": "0.3.9",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {