@adamchanadam/agent-handoff-kit 0.3.14 → 0.3.15

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.14`。這是早期可用版本,仍在持續完善中。
3
+ 狀態:目前版本為 `v0.3.15`。這是早期可用版本,仍在持續完善中。
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.14`。
264
+ - 目前版本為 `v0.3.15`。
265
265
  - 這是早期可用版本,仍在持續完善中。
266
266
  - 升級合併屬窄範圍策略,不是完整的複雜合併工具。
267
267
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
@@ -457,9 +457,9 @@ async function needsProjectIndexVersionInject(root, command, version) {
457
457
  return false;
458
458
  }
459
459
 
460
- async function runInstall(command, root, options, version) {
461
- const mode = await detectMode(root);
462
- const plan = await buildPlan(root, command);
460
+ async function runInstall(command, root, options, version) {
461
+ const mode = await detectMode(root);
462
+ const plan = await buildPlan(root, command, version);
463
463
 
464
464
  // R-031 v0.3.1+: plan-time upgrade no-op detection. When upgrade has zero
465
465
  // create/merge/conflict actions (skip-only), skip the full plan listing +
@@ -1105,17 +1105,21 @@ function tableHeader(...cells) {
1105
1105
  };
1106
1106
  }
1107
1107
 
1108
- async function buildPlan(root, command) {
1109
- const plan = [];
1110
- for (const [sourceRel, targetRel] of mappings) {
1111
- const sourceAbs = path.join(packageRoot, sourceRel);
1112
- const targetAbs = path.join(root, targetRel);
1113
- const sourceText = await readFile(sourceAbs, "utf8");
1114
- if (await exists(targetAbs)) {
1115
- const targetText = await readFile(targetAbs, "utf8");
1116
- plan.push(classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAbs, sourceText, targetText));
1117
- continue;
1118
- }
1108
+ async function buildPlan(root, command, version = null) {
1109
+ const plan = [];
1110
+ const context = {
1111
+ currentVersion: version,
1112
+ rootTemplateVersion: command === "upgrade" ? await readRootTemplateVersion(root) : null
1113
+ };
1114
+ for (const [sourceRel, targetRel] of mappings) {
1115
+ const sourceAbs = path.join(packageRoot, sourceRel);
1116
+ const targetAbs = path.join(root, targetRel);
1117
+ const sourceText = await readFile(sourceAbs, "utf8");
1118
+ if (await exists(targetAbs)) {
1119
+ const targetText = await readFile(targetAbs, "utf8");
1120
+ plan.push(classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAbs, sourceText, targetText, context));
1121
+ continue;
1122
+ }
1119
1123
  plan.push({
1120
1124
  sourceRel,
1121
1125
  targetRel,
@@ -1123,12 +1127,23 @@ async function buildPlan(root, command) {
1123
1127
  targetAbs,
1124
1128
  action: "create"
1125
1129
  });
1126
- }
1127
- return plan;
1128
- }
1129
-
1130
- function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAbs, sourceText, targetText) {
1131
- const base = { sourceRel, targetRel, sourceAbs, targetAbs };
1130
+ }
1131
+ return plan;
1132
+ }
1133
+
1134
+ async function readRootTemplateVersion(root) {
1135
+ try {
1136
+ const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
1137
+ const text = await readFile(indexPath, "utf8");
1138
+ const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
1139
+ return m?.[1] ?? null;
1140
+ } catch {
1141
+ return null;
1142
+ }
1143
+ }
1144
+
1145
+ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAbs, sourceText, targetText, context = {}) {
1146
+ const base = { sourceRel, targetRel, sourceAbs, targetAbs };
1132
1147
  if (targetText === sourceText) return { ...base, action: "skip", reason: "already current" };
1133
1148
  if (command !== "upgrade") return { ...base, action: "skip", reason: "init preserves existing files" };
1134
1149
  if (targetRel === "AGENTS.md") {
@@ -1256,10 +1271,25 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1256
1271
  ...base,
1257
1272
  action: "merge",
1258
1273
  reason: "insert lifecycle consistency field into State Reconciliation Check (completed work must not carry forward as unresolved next work)",
1259
- mergedText: mergedHandoff
1260
- };
1261
- }
1262
- if (targetRel === "CLAUDE.md" || targetRel === "GEMINI.md") {
1274
+ mergedText: mergedHandoff
1275
+ };
1276
+ }
1277
+ if (targetRel === "dev/SESSION_HANDOFF.md" && command === "upgrade" && isUpgradeFromOlderTemplate(context)) {
1278
+ const lifecycleValue = fieldValueAfterMarker(targetText, "lifecycle-conflicts-resolved");
1279
+ if (isPlaceholderLifecycleFieldValue(lifecycleValue) && hasSubstantiveHandoffState(targetText)) {
1280
+ const mergedHandoff = reclassifyExistingHandoffLifecyclePlaceholder(targetText);
1281
+ if (!mergedHandoff) {
1282
+ return { ...base, action: "conflict", reason: "SESSION_HANDOFF.md lifecycle field exists but could not be safely reclassified; manual closeout required" };
1283
+ }
1284
+ return {
1285
+ ...base,
1286
+ action: "merge",
1287
+ reason: "reclassify stale lifecycle placeholder from earlier template version so upgrade self-check can validate pre-existing handoff content",
1288
+ mergedText: mergedHandoff
1289
+ };
1290
+ }
1291
+ }
1292
+ if (targetRel === "CLAUDE.md" || targetRel === "GEMINI.md") {
1263
1293
  if (!targetText.includes("AGENTS.md")) {
1264
1294
  return { ...base, action: "conflict", reason: "existing bridge does not route to AGENTS.md" };
1265
1295
  }
@@ -1272,8 +1302,15 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1272
1302
  };
1273
1303
  }
1274
1304
  }
1275
- return { ...base, action: "skip", reason: "preserve existing file" };
1276
- }
1305
+ return { ...base, action: "skip", reason: "preserve existing file" };
1306
+ }
1307
+
1308
+ function isUpgradeFromOlderTemplate(context) {
1309
+ const { rootTemplateVersion, currentVersion } = context;
1310
+ return isStableSemver(rootTemplateVersion)
1311
+ && isStableSemver(currentVersion)
1312
+ && compareSemver(rootTemplateVersion, currentVersion) < 0;
1313
+ }
1277
1314
 
1278
1315
  function looksLikeExpandedKitBridge(targetRel, text) {
1279
1316
  if (text.includes("This file is a bridge only")) return false;
@@ -1304,7 +1341,7 @@ function mergeOnboardingScenarioALabel(targetText) {
1304
1341
  return merged;
1305
1342
  }
1306
1343
 
1307
- function mergeHandoffLifecycleField(targetText) {
1344
+ function mergeHandoffLifecycleField(targetText) {
1308
1345
  const openingMarker = "<!-- ack:field:opening-message-matches-current-state -->";
1309
1346
  if (!targetText.includes(openingMarker)) return null;
1310
1347
 
@@ -1320,9 +1357,38 @@ function mergeHandoffLifecycleField(targetText) {
1320
1357
  merged = `${merged.trimEnd()}\n\n${ruleBlock}`;
1321
1358
  }
1322
1359
  }
1323
-
1324
- return merged;
1325
- }
1360
+
1361
+ return merged;
1362
+ }
1363
+
1364
+ function reclassifyExistingHandoffLifecyclePlaceholder(targetText) {
1365
+ const marker = "ack:field:lifecycle-conflicts-resolved";
1366
+ const lines = targetText.split(/\r?\n/);
1367
+ const markerIndex = lines.findIndex((line) => line.includes(marker));
1368
+ if (markerIndex < 0) return null;
1369
+
1370
+ const nextMarkerIndex = lines.findIndex((line, index) => index > markerIndex && line.includes("<!-- ack:"));
1371
+ const searchEnd = nextMarkerIndex < 0 ? lines.length : nextMarkerIndex;
1372
+ const fieldIndex = lines.findIndex((line, index) => index > markerIndex && index < searchEnd && line.trim().startsWith("- "));
1373
+ if (fieldIndex < 0) return null;
1374
+
1375
+ const colonIndex = lines[fieldIndex].indexOf(":");
1376
+ if (colonIndex < 0) return null;
1377
+ lines[fieldIndex] = `${lines[fieldIndex].slice(0, colonIndex + 1)} Reclassified at upgrade: existing lifecycle placeholder predates this version; pre-existing handoff state predates this check; reconcile at next closeout.`;
1378
+
1379
+ let merged = lines.join("\n");
1380
+ if (!merged.includes("Lifecycle consistency rule: compare `Completed This Session`")) {
1381
+ 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";
1382
+ const sufficiencyMarker = "<!-- ack:section:handoff-sufficiency-check -->";
1383
+ if (merged.includes(sufficiencyMarker)) {
1384
+ merged = merged.replace(sufficiencyMarker, `${ruleBlock}${sufficiencyMarker}`);
1385
+ } else {
1386
+ merged = `${merged.trimEnd()}\n\n${ruleBlock}`;
1387
+ }
1388
+ }
1389
+
1390
+ return merged;
1391
+ }
1326
1392
 
1327
1393
  function mergeRulePacksRows(targetText, sourceText) {
1328
1394
  const requiredPacks = [
@@ -0,0 +1,27 @@
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 修補,不要用重裝覆寫既有內容。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.14",
3
+ "version": "0.3.15",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {