@adamchanadam/agent-handoff-kit 0.3.7 → 0.3.8

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.8`。這是早期可用版本,仍在持續完善中。
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,7 +248,7 @@ Agent Handoff Kit 同 [Adam-AI-Instructions](https://github.com/prompt-templates
248
248
 
249
249
  ## 目前限制
250
250
 
251
- - 目前版本為 `v0.3.7`。
251
+ - 目前版本為 `v0.3.8`。
252
252
  - 這是早期可用版本,仍在持續完善中。
253
253
  - 升級合併屬窄範圍策略,不是完整的複雜合併工具。
254
254
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
@@ -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,37 @@ 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 (isUnresolvedLifecycleFieldValue(fieldValue)) {
892
893
  return { ok: false, reason: "lifecycle field is explicitly unresolved" };
893
894
  }
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
- }
895
+ if (isPlaceholderLifecycleFieldValue(fieldValue) && hasSubstantiveHandoffState(text)) {
896
+ return { ok: false, reason: "lifecycle field is still placeholder after handoff content changed" };
910
897
  }
911
-
912
898
  return { ok: true, reason: "" };
913
899
  }
914
900
 
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];
901
+ function isUnresolvedLifecycleFieldValue(value) {
902
+ return /\b(no|blocked|uncertain)\b|否|阻擋|不確定/i.test(value || "");
923
903
  }
924
904
 
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;
905
+ function isPlaceholderLifecycleFieldValue(value) {
906
+ return !value || /\b(TBD|todo|pending|unverified|unknown|needs-review)\b|待核對|待確認|未核對|未確認/i.test(value);
907
+ }
908
+
909
+ function hasSubstantiveHandoffState(text) {
910
+ const sections = [
911
+ extractSectionText(text, "completed-this-session", "Completed This Session"),
912
+ extractSectionText(text, "validation-qc", "Validation / QC")
913
+ ].join("\n");
914
+ const body = sections.replace(/```[\s\S]*?```/g, "");
915
+ return body.split(/\r?\n/).some((line) => {
916
+ const trimmed = line.trim();
917
+ if (!trimmed || trimmed.startsWith("##") || trimmed.startsWith("<!--")) return false;
918
+ if (/^Record only work actually completed/i.test(trimmed)) return false;
919
+ if (/\bTBD\b|待定|待核對|未適用/i.test(trimmed)) return false;
920
+ const normalized = trimmed.replace(/^[\d.*\-)\s]+/, "").replace(/[`\s#|:\-*/()[\].,;,。;、]/g, "");
921
+ return normalized.length > 20;
922
+ });
940
923
  }
941
924
 
942
925
  function fieldValueAfterMarker(text, fieldId) {
@@ -2008,14 +1991,31 @@ async function printWhatsnew(root, toVersion, fromVersionOverride) {
2008
1991
  // short factual message and return. Saves disk (no migration report) + reduces noise
2009
1992
  // (no self-check doctor) + avoids misleading "安裝完成" framing for an idempotent
2010
1993
  // operation where nothing changed.
2011
- function printUpgradeNoopShortCircuit(version) {
2012
- console.log("");
2013
- console.log(`📦 版本:v${version}`);
2014
- console.log("🛠️ 模式:upgrade-existing");
1994
+ async function assessUpgradeNoopHealth(root) {
1995
+ try {
1996
+ const handoffText = await readFile(path.join(root, "dev/SESSION_HANDOFF.md"), "utf8");
1997
+ return { handoffLifecycle: assessHandoffLifecycleConsistency(handoffText) };
1998
+ } catch {
1999
+ return { handoffLifecycle: { ok: false, reason: "dev/SESSION_HANDOFF.md unreadable" } };
2000
+ }
2001
+ }
2002
+
2003
+ function printUpgradeNoopShortCircuit(version, health = { handoffLifecycle: { ok: true } }) {
2004
+ console.log("");
2005
+ console.log(`📦 版本:v${version}`);
2006
+ console.log("🛠️ 模式:upgrade-existing");
2015
2007
  console.log("🔎 剛完成:檢查所有 Kit 檔案的狀態(含 AGENTS.md、dev/SESSION_HANDOFF.md、dev/PROJECT_INDEX.md 等)。");
2016
- console.log("✅ 結果:你已經是最新版本,沒有檔案需要建立或合併;用戶填寫的內容全部保留現狀。");
2008
+ if (health.handoffLifecycle?.ok) {
2009
+ console.log("✅ 結果:你已經是最新版本,沒有檔案需要建立或合併;用戶填寫的內容全部保留現狀。");
2010
+ console.log("");
2011
+ console.log("🚀 下一步:繼續日常使用即可。如要檢查健康狀態,可執行:");
2012
+ console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
2013
+ console.log("");
2014
+ return;
2015
+ }
2016
+ console.log("⚠️ 結果:Kit 檔案已是最新版本,沒有檔案需要建立或合併;但交接狀態仍需 AI closeout 核對。");
2017
2017
  console.log("");
2018
- console.log("🚀 下一步:繼續日常使用即可。如要檢查健康狀態,可執行:");
2018
+ console.log("🚀 下一步:先跑 doctor 取得待修項,再把輸出貼給 AI;不要重裝或覆寫用戶內容。");
2019
2019
  console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
2020
2020
  console.log("");
2021
2021
  }
@@ -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 狀態核對,不要重裝或覆寫項目文件。
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.8",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {