@adamchanadam/agent-handoff-kit 0.3.22 → 0.3.23

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.22`。這是早期可用版本,仍在持續完善中。
3
+ 狀態:目前版本為 `v0.3.23`。這是早期可用版本,仍在持續完善中。
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
 
@@ -283,7 +283,7 @@ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templa
283
283
 
284
284
  ## 目前限制
285
285
 
286
- - 目前版本為 `v0.3.22`;正式安裝請以 npm registry `latest` 顯示為準。
286
+ - 目前版本為 `v0.3.23`;正式安裝請以 npm registry `latest` 顯示為準。
287
287
  - 這是早期可用版本,仍在持續完善中。
288
288
  - 升級合併屬窄範圍策略,不是完整的複雜合併工具。
289
289
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
@@ -46,8 +46,10 @@ const requiredAnchors = [
46
46
  "dev/SESSION_HANDOFF.md",
47
47
  "dev/SESSION_LOG.md",
48
48
  "dev/PROJECT_INDEX.md",
49
- "dev/RULE_PACKS.md",
49
+ "dev/RULE_PACKS.md",
50
50
  "Agent Handoff Kit v<version>",
51
+ "Display version rule",
52
+ "Agent Handoff Kit template version",
51
53
  "continuity ready",
52
54
  "Start Agent Handoff",
53
55
  "Ambiguous startup phrases",
@@ -75,6 +77,8 @@ const requiredAnchors = [
75
77
  "next-session opening message",
76
78
  "fenced `text` code block",
77
79
  "handoff saved",
80
+ "Use the same display version rule as startup",
81
+ "Never print the literal placeholder `v<version>`",
78
82
  "next-session startup entry",
79
83
  "State Reconciliation Check",
80
84
  "handoff lifecycle consistency",
@@ -97,9 +101,10 @@ const requiredAnchors = [
97
101
  "ack:section:workspace-identity",
98
102
  "ack:section:sync-status",
99
103
  "ack:section:next-task-required-reading",
100
- "ack:section:state-reconciliation-check",
104
+ "ack:section:state-reconciliation-check",
101
105
  "ack:section:next-session-opening-message",
102
106
  "ack:field:lifecycle-conflicts-resolved",
107
+ "ack:field:persistence-routing-checked",
103
108
  "📋 Next session:",
104
109
  "```text",
105
110
  "Read in order:",
@@ -176,12 +181,14 @@ const requiredAnchors = [
176
181
  snippets: [
177
182
  "Project Decisions Log",
178
183
  "warm 資料層",
179
- "AI 開工",
180
- "不需要讀",
181
- "AI 在收工時自動 update",
182
- "Evolution Timeline",
183
- "Decisions Archive",
184
- "Architecture Choices",
184
+ "AI 開工",
185
+ "不需要讀",
186
+ "AI 在收工時自動 update",
187
+ "Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.",
188
+ "This file does not store raw build / upload / QC evidence",
189
+ "Evolution Timeline",
190
+ "Decisions Archive",
191
+ "Architecture Choices",
185
192
  "Insights & Learnings"
186
193
  ]
187
194
  },
@@ -252,10 +259,11 @@ const schemaChecks = [
252
259
  section("state-reconciliation-check", "State Reconciliation Check"),
253
260
  section("handoff-sufficiency-check", "Handoff Sufficiency Check"),
254
261
  section("next-session-opening-message", "Next Session Opening Message"),
255
- marker("field", "stale-snapshots-left", "Stale snapshots left in this handoff"),
256
- marker("field", "lifecycle-conflicts-resolved", "Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified"),
257
- marker("field", "opening-message-matches-current-state", "Opening message matches current state"),
258
- marker("field", "state-sections-rewritten-or-confirmed", "State sections rewritten or confirmed current"),
262
+ marker("field", "stale-snapshots-left", "Stale snapshots left in this handoff"),
263
+ marker("field", "lifecycle-conflicts-resolved", "Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified"),
264
+ marker("field", "persistence-routing-checked", "Persistence routing checked"),
265
+ marker("field", "opening-message-matches-current-state", "Opening message matches current state"),
266
+ marker("field", "state-sections-rewritten-or-confirmed", "State sections rewritten or confirmed current"),
259
267
  marker("field", "user-intent", "User intent:"),
260
268
  marker("field", "task-essence", "Task essence:"),
261
269
  marker("field", "success-criteria", "Success criteria:")
@@ -290,9 +298,10 @@ const schemaChecks = [
290
298
  includes("- **ID:**"),
291
299
  includes("- **Summary:**"),
292
300
  includes("- **Changed:**"),
293
- includes("- **Done:**"),
294
- includes("- **QC:**"),
295
- includes("- **Sync:**"),
301
+ includes("- **Done:**"),
302
+ includes("- **QC:**"),
303
+ includes("- **Evidence disposition:**"),
304
+ includes("- **Sync:**"),
296
305
  includes("- **Pending:**"),
297
306
  includes("- **Risks:**"),
298
307
  includes("- **Log maintenance:**")
@@ -361,17 +370,18 @@ const schemaChecks = [
361
370
  includes("dev/rules/integrations.md")
362
371
  ]
363
372
  },
364
- {
365
- target: "dev/PROJECT_DECISIONS.md",
366
- label: "project decisions log structure",
367
- checks: [
368
- heading("Evolution Timeline"),
369
- heading("Decisions Archive"),
370
- heading("Architecture Choices"),
371
- heading("Insights & Learnings"),
372
- includes("(empty)")
373
- ]
374
- },
373
+ {
374
+ target: "dev/PROJECT_DECISIONS.md",
375
+ label: "project decisions log structure",
376
+ checks: [
377
+ heading("Evolution Timeline"),
378
+ heading("Decisions Archive"),
379
+ heading("Architecture Choices"),
380
+ heading("Insights & Learnings"),
381
+ includes("Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>."),
382
+ includes("(empty)")
383
+ ]
384
+ },
375
385
  {
376
386
  target: "dev/rules/onboarding.md",
377
387
  label: "onboarding pack structure (新手引導包)",
@@ -702,18 +712,52 @@ async function runDoctor(root, version, options = {}) {
702
712
  }
703
713
  }
704
714
 
705
- if (schemaFailures.length > 0) {
706
- printDoctorSummary(version, root, "needs-fix", {
707
- checked: rows.length + anchorRows.length + schemaRows.length,
708
- failedKind: "schema checks",
715
+ if (schemaFailures.length > 0) {
716
+ printDoctorSummary(version, root, "needs-fix", {
717
+ checked: rows.length + anchorRows.length + schemaRows.length,
718
+ failedKind: "schema checks",
709
719
  failedCount: schemaFailures.length,
710
720
  nextStep: "把這段 doctor 輸出貼給 AI,請它先修交接結構,不要直接重裝覆蓋。"
711
721
  });
712
722
  process.exitCode = 1;
713
- return "failed";
714
- }
715
-
716
- const mirrorRows = await checkPromptMirror(root);
723
+ return "failed";
724
+ }
725
+
726
+ const researchTraceResult = await checkResearchDecisionTrace(root);
727
+ console.log(`\nresearch decision trace checks: ${researchTraceResult.checked}`);
728
+ console.log(`${researchTraceResult.ok ? "ok" : "missing"} dev/PROJECT_DECISIONS.md (research-derived decision evidence chains)`);
729
+ if (!researchTraceResult.ok) {
730
+ for (const finding of researchTraceResult.findings) {
731
+ console.log(` missing: ${finding}`);
732
+ }
733
+ printDoctorSummary(version, root, "needs-fix", {
734
+ checked: rows.length + anchorRows.length + schemaRows.length + researchTraceResult.checked,
735
+ failedKind: "research decision trace checks",
736
+ failedCount: researchTraceResult.findings.length,
737
+ nextStep: "把 research-derived decision 的 Evidence chain 補齊,並確認 Source=source:<id> token 已登記在 dev/PROJECT_INDEX.md 的 Fact Base 或 External Sources。"
738
+ });
739
+ process.exitCode = 1;
740
+ return "failed";
741
+ }
742
+
743
+ const temperatureResult = await checkHandoffTemperatureBoundary(root);
744
+ console.log(`\nhandoff temperature boundary checks: ${temperatureResult.checked}`);
745
+ console.log(`${temperatureResult.ok ? "ok" : "missing"} dev/SESSION_HANDOFF.md / START_NEXT_SESSION_PROMPT.txt (current-state evidence boundary)`);
746
+ if (!temperatureResult.ok) {
747
+ for (const finding of temperatureResult.findings) {
748
+ console.log(` missing: ${finding}`);
749
+ }
750
+ printDoctorSummary(version, root, "needs-fix", {
751
+ checked: rows.length + anchorRows.length + schemaRows.length + researchTraceResult.checked + temperatureResult.checked,
752
+ failedKind: "handoff temperature boundary checks",
753
+ failedCount: temperatureResult.findings.length,
754
+ nextStep: "把一次性驗收證據、舊版本狀態、source token 或 Evidence chain 從 Durable Anchors / Next Priorities / opening message 移回 SESSION_LOG、PROJECT_INDEX 或 PROJECT_DECISIONS。"
755
+ });
756
+ process.exitCode = 1;
757
+ return "failed";
758
+ }
759
+
760
+ const mirrorRows = await checkPromptMirror(root);
717
761
  const mirrorBlockingFailures = mirrorRows.filter((row) => !row.ok && row.reason !== "convenience copy differs from dev/SESSION_HANDOFF.md");
718
762
  const mirrorWarnings = mirrorRows.filter((row) => !row.ok && row.reason === "convenience copy differs from dev/SESSION_HANDOFF.md");
719
763
  console.log(`\nprompt mirror checks: ${mirrorRows.length}`);
@@ -769,9 +813,9 @@ async function runDoctor(root, version, options = {}) {
769
813
  ? "檢查已通過。START_NEXT_SESSION_PROMPT.txt 只是下次開工便利副本;session 進行中不用手動重生,收工 closeout 時 AI 會從 dev/SESSION_HANDOFF.md 重生。"
770
814
  : null;
771
815
 
772
- const overallHealthy = credentialResult.ok;
773
- printDoctorSummary(version, root, overallHealthy ? "healthy" : "needs-attention", {
774
- checked: rows.length + anchorRows.length + schemaRows.length + mirrorRows.length + 2,
816
+ const overallHealthy = credentialResult.ok;
817
+ printDoctorSummary(version, root, overallHealthy ? "healthy" : "needs-attention", {
818
+ checked: rows.length + anchorRows.length + schemaRows.length + researchTraceResult.checked + temperatureResult.checked + mirrorRows.length + 2,
775
819
  failedKind: !credentialResult.ok ? "credential leak" : null,
776
820
  failedCount: !credentialResult.ok ? credentialResult.findings.length : 0,
777
821
  warningKind: mirrorWarnings.length > 0 ? "prompt mirror warning" : null,
@@ -782,9 +826,140 @@ async function runDoctor(root, version, options = {}) {
782
826
  ? versionNextStep ?? promptMirrorNextStep ?? onboardingNextStep ?? "檢查已通過。繼續使用你原本的 AI 開工方式;如剛完成一個任務,記得在 AI 對話輸入「收工」保存交接。"
783
827
  : "繼續使用;下次 closeout 時 AI 應自動執行 SESSION_LOG N 規則推進(見上面 warn 行)。如未動請要求 AI 重做 closeout。"
784
828
  });
785
- return overallHealthy ? "passed" : "failed";
786
- }
787
-
829
+ return overallHealthy ? "passed" : "failed";
830
+ }
831
+
832
+ async function checkResearchDecisionTrace(root) {
833
+ const decisionsPath = path.join(root, "dev/PROJECT_DECISIONS.md");
834
+ const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
835
+ let decisionsText = "";
836
+ let indexText = "";
837
+ try {
838
+ decisionsText = await readFile(decisionsPath, "utf8");
839
+ indexText = await readFile(indexPath, "utf8");
840
+ } catch {
841
+ return { ok: false, checked: 1, findings: ["dev/PROJECT_DECISIONS.md or dev/PROJECT_INDEX.md unreadable"] };
842
+ }
843
+
844
+ const findings = [];
845
+ const sourceTokenPattern = /\bsource:[A-Za-z0-9._-]+\b/g;
846
+ const blocks = markdownListBlocks(stripFencedCodeBlocks(decisionsText));
847
+ const researchBlocks = blocks.filter((block) => /\bresearch-derived\b/i.test(block) || /Evidence chain:/i.test(block));
848
+
849
+ researchBlocks.forEach((block, index) => {
850
+ const label = `research-derived decision #${index + 1}`;
851
+ if (!/Evidence chain:/i.test(block)) {
852
+ findings.push(`${label} missing Evidence chain`);
853
+ }
854
+ const tokens = [...block.matchAll(sourceTokenPattern)].map((match) => match[0]);
855
+ if (tokens.length === 0) {
856
+ findings.push(`${label} missing source:<id> token`);
857
+ }
858
+ for (const token of tokens) {
859
+ if (!indexText.includes(token)) {
860
+ findings.push(`${label} references ${token}, but dev/PROJECT_INDEX.md does not contain that token`);
861
+ }
862
+ }
863
+ });
864
+
865
+ return { ok: findings.length === 0, checked: 1, findings };
866
+ }
867
+
868
+ function stripFencedCodeBlocks(text) {
869
+ return text.replace(/```[\s\S]*?```/g, "");
870
+ }
871
+
872
+ function markdownListBlocks(text) {
873
+ const blocks = [];
874
+ let current = [];
875
+ for (const line of text.split(/\r?\n/)) {
876
+ if (/^\s*[-*]\s+/.test(line)) {
877
+ if (current.length > 0) blocks.push(current.join("\n"));
878
+ current = [line];
879
+ } else if (current.length > 0 && (/^\s{2,}\S/.test(line) || /^\s*$/.test(line))) {
880
+ current.push(line);
881
+ } else if (current.length > 0) {
882
+ blocks.push(current.join("\n"));
883
+ current = [];
884
+ }
885
+ }
886
+ if (current.length > 0) blocks.push(current.join("\n"));
887
+ return blocks;
888
+ }
889
+
890
+ async function checkHandoffTemperatureBoundary(root) {
891
+ const findings = [];
892
+ const sections = [];
893
+ let handoffText = "";
894
+
895
+ try {
896
+ handoffText = await readFile(path.join(root, "dev/SESSION_HANDOFF.md"), "utf8");
897
+ } catch {
898
+ return { ok: false, checked: 1, findings: ["dev/SESSION_HANDOFF.md unreadable"] };
899
+ }
900
+
901
+ sections.push(
902
+ { label: "Durable Anchors", text: extractHandoffSectionText(handoffText, "durable-anchors", "Durable Anchors") },
903
+ { label: "Next Priorities", text: extractHandoffSectionText(handoffText, "next-priorities", "Next Priorities") },
904
+ { label: "Next Session Opening Message", text: extractHandoffSectionText(handoffText, "next-session-opening-message", "Next Session Opening Message") }
905
+ );
906
+
907
+ const requiredReading = extractHandoffSectionText(handoffText, "next-task-required-reading", "Next Task Required Reading");
908
+ sections.push({ label: "Next Task Required Reading", text: requiredReading, allowSourceTokens: true });
909
+
910
+ try {
911
+ const promptText = await readFile(path.join(root, "START_NEXT_SESSION_PROMPT.txt"), "utf8");
912
+ sections.push({ label: "START_NEXT_SESSION_PROMPT.txt", text: promptText });
913
+ } catch {
914
+ // Missing prompt mirror is handled by prompt mirror checks; do not duplicate the failure here.
915
+ }
916
+
917
+ const evidencePatterns = [
918
+ { pattern: /post-publish artifact smoke/i, label: "post-publish artifact smoke evidence" },
919
+ { pattern: /PASS\s+7\/7/i, label: "historical PASS count" },
920
+ { pattern: /\bfileCount\b/i, label: "published artifact fileCount evidence" },
921
+ { pattern: /\brelease source\b/i, label: "release source evidence" },
922
+ { pattern: /Cross-mind evidence/i, label: "cross-agent review evidence" },
923
+ { pattern: /Evidence chain:/i, label: "research evidence chain" },
924
+ { pattern: /\bnpm latest\s+(?:is|=|v?\d)/i, label: "historical npm latest state" },
925
+ { pattern: /GitHub Release\s+(?:metadata|published|view|`?v?\d)/i, label: "historical GitHub Release state" }
926
+ ];
927
+ const sourceTokenPattern = /\bsource:[A-Za-z0-9._-]+\b/;
928
+
929
+ for (const section of sections) {
930
+ if (!section.text) continue;
931
+ for (const rule of evidencePatterns) {
932
+ if (rule.pattern.test(section.text)) {
933
+ findings.push(`${section.label} contains ${rule.label}; keep it in trace evidence unless it still affects the next action`);
934
+ }
935
+ }
936
+ if (!section.allowSourceTokens && sourceTokenPattern.test(section.text)) {
937
+ findings.push(`${section.label} contains source:<id>; keep source tokens in PROJECT_INDEX / PROJECT_DECISIONS, not hot startup state`);
938
+ }
939
+ }
940
+
941
+ return { ok: findings.length === 0, checked: 1, findings };
942
+ }
943
+
944
+ function extractHandoffSectionText(text, id, headingText) {
945
+ const marker = `<!-- ack:section:${id} -->`;
946
+ const markerStart = text.indexOf(marker);
947
+ if (markerStart >= 0) {
948
+ const afterMarker = markerStart + marker.length;
949
+ const nextMarker = text.indexOf("<!-- ack:section:", afterMarker);
950
+ return text.slice(afterMarker, nextMarker >= 0 ? nextMarker : text.length);
951
+ }
952
+
953
+ const headingPattern = new RegExp(`^##\\s+${escapeRegExp(headingText)}\\s*$`, "m");
954
+ const headingMatch = headingPattern.exec(text);
955
+ if (!headingMatch) return "";
956
+ const start = headingMatch.index + headingMatch[0].length;
957
+ const nextHeading = /\n##\s+/g;
958
+ nextHeading.lastIndex = start;
959
+ const nextMatch = nextHeading.exec(text);
960
+ return text.slice(start, nextMatch ? nextMatch.index : text.length);
961
+ }
962
+
788
963
  function getFirstUseNextStep(root, lastCloseout) {
789
964
  if (lastCloseout.date) return null;
790
965
  return `檢查已通過。下一步不要再留在終端機;打開能讀寫此資料夾的 AI agent。若 AI 已在此資料夾內,輸入 Start Agent Handoff 或「開工」;若 AI 還未指向此資料夾,才貼:${startupPathBootstrapPrompt(root)}`;
@@ -846,10 +1021,10 @@ function printDoctorSummary(version, root, mode, details) {
846
1021
  } else {
847
1022
  console.log("✅ 檢查通過:必要文件存在,基本結構完整,下次開工提示副本已與 handoff 一致。");
848
1023
  }
849
- } else {
850
- console.log(`status: failed (${details.failedCount} ${details.failedKind} failed)`);
851
- console.log(`⚠️ 檢查未通過:${details.failedKind === "missing files" ? "有必要檔案不存在。" : details.failedKind === "anchor checks" ? "有檔案存在,但內容缺少必要段落。" : details.failedKind === "schema checks" ? "交接或索引文件結構不完整。" : "下次開工提示副本與 handoff 真源不同。"}`);
852
- }
1024
+ } else {
1025
+ console.log(`status: failed (${details.failedCount} ${details.failedKind} failed)`);
1026
+ console.log(`⚠️ 檢查未通過:${details.failedKind === "missing files" ? "有必要檔案不存在。" : details.failedKind === "anchor checks" ? "有檔案存在,但內容缺少必要段落。" : details.failedKind === "schema checks" ? "交接或索引文件結構不完整。" : details.failedKind === "research decision trace checks" ? "研究導向決策缺少可追溯來源鏈。" : details.failedKind === "handoff temperature boundary checks" ? "當前交接內容混入一次性或歷史證據。" : "下次開工提示副本與 handoff 真源不同。"}`);
1027
+ }
853
1028
  console.log("");
854
1029
  console.log(`📦 版本:v${version}`);
855
1030
  console.log(`🩺 模式:${mode}`);
@@ -1256,9 +1431,9 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1256
1431
  // v0.3.6+: SESSION_HANDOFF.md gains a non-destructive lifecycle consistency
1257
1432
  // field. Existing handoff content stays intact; only the missing field and
1258
1433
  // rule note are inserted around stable ack markers.
1259
- if (targetRel === "dev/SESSION_HANDOFF.md" && command === "upgrade" && !targetText.includes("ack:field:lifecycle-conflicts-resolved")) {
1260
- const mergedHandoff = mergeHandoffLifecycleField(targetText);
1261
- if (!mergedHandoff) {
1434
+ if (targetRel === "dev/SESSION_HANDOFF.md" && command === "upgrade" && !targetText.includes("ack:field:lifecycle-conflicts-resolved")) {
1435
+ const mergedHandoff = mergeHandoffLifecycleField(targetText);
1436
+ if (!mergedHandoff) {
1262
1437
  return { ...base, action: "conflict", reason: "SESSION_HANDOFF.md state reconciliation markers were changed; manual merge required to add lifecycle consistency field" };
1263
1438
  }
1264
1439
  return {
@@ -1268,6 +1443,18 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1268
1443
  mergedText: mergedHandoff
1269
1444
  };
1270
1445
  }
1446
+ if (targetRel === "dev/SESSION_HANDOFF.md" && command === "upgrade" && !targetText.includes("ack:field:persistence-routing-checked")) {
1447
+ const mergedHandoff = mergeHandoffPersistenceRoutingField(targetText);
1448
+ if (!mergedHandoff) {
1449
+ return { ...base, action: "conflict", reason: "SESSION_HANDOFF.md state reconciliation markers were changed; manual merge required to add persistence routing field" };
1450
+ }
1451
+ return {
1452
+ ...base,
1453
+ action: "merge",
1454
+ reason: "insert persistence routing field into State Reconciliation Check (one-time evidence must not drive next-session state)",
1455
+ mergedText: mergedHandoff
1456
+ };
1457
+ }
1271
1458
  if (targetRel === "dev/SESSION_HANDOFF.md" && command === "upgrade" && isUpgradeFromOlderTemplate(context)) {
1272
1459
  const lifecycleValue = fieldValueAfterMarker(targetText, "lifecycle-conflicts-resolved");
1273
1460
  if (isPlaceholderLifecycleFieldValue(lifecycleValue) && hasSubstantiveHandoffState(targetText)) {
@@ -1295,6 +1482,18 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1295
1482
  mergedText: mergedHandoff
1296
1483
  };
1297
1484
  }
1485
+ if (targetRel === "dev/SESSION_LOG.md" && command === "upgrade" && !targetText.includes("- **Evidence disposition:**")) {
1486
+ const mergedLog = mergeSessionLogEvidenceDispositionField(targetText);
1487
+ if (!mergedLog) {
1488
+ return { ...base, action: "conflict", reason: "SESSION_LOG.md entry template markers were changed; manual merge required to add evidence disposition field" };
1489
+ }
1490
+ return {
1491
+ ...base,
1492
+ action: "merge",
1493
+ reason: "insert SESSION_LOG evidence disposition field into Entry Template",
1494
+ mergedText: mergedLog
1495
+ };
1496
+ }
1298
1497
  if (command === "upgrade" && hasAnchorRepairMarkerDrift(targetText)) {
1299
1498
  return { ...base, action: "conflict", reason: "legacy anchor repair block markers are incomplete or obsolete; manual semantic cleanup required before upgrade can safely continue" };
1300
1499
  }
@@ -1460,7 +1659,9 @@ function projectDecisionsAnchorPlacement(snippet, text) {
1460
1659
  "warm 資料層",
1461
1660
  "AI 開工",
1462
1661
  "不需要讀",
1463
- "AI 在收工時自動 update"
1662
+ "AI 在收工時自動 update",
1663
+ "Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.",
1664
+ "This file does not store raw build / upload / QC evidence"
1464
1665
  ];
1465
1666
  if (preamble.includes(snippet)) return snippetAppearsBeforeHeading(text, snippet, "## Evolution Timeline");
1466
1667
  return true;
@@ -1534,8 +1735,8 @@ const semanticAnchorRepairStrategies = {
1534
1735
  mergedText: mergedLog
1535
1736
  } : null;
1536
1737
  },
1537
- "dev/PROJECT_DECISIONS.md": (targetText, sourceText) => {
1538
- const mergedDecisions = insertSourcePreambleBeforeHeading(targetText, sourceText, "## Evolution Timeline");
1738
+ "dev/PROJECT_DECISIONS.md": (targetText, sourceText, missing) => {
1739
+ const mergedDecisions = mergeProjectDecisionsPreamble(targetText, sourceText, missing);
1539
1740
  return mergedDecisions ? {
1540
1741
  action: "merge",
1541
1742
  reason: "restore PROJECT_DECISIONS onboarding preamble before ## Evolution Timeline",
@@ -1578,6 +1779,33 @@ function insertSourcePreambleBeforeHeading(targetText, sourceText, headingText)
1578
1779
  return `${targetBefore}\n\n${sourcePreamble}\n\n${targetAfter}`;
1579
1780
  }
1580
1781
 
1782
+ function mergeProjectDecisionsPreamble(targetText, sourceText, missing) {
1783
+ const evidenceSnippet = "Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.";
1784
+ const boundarySnippet = "This file does not store raw build / upload / QC evidence";
1785
+ const targetIndex = targetText.indexOf("## Evolution Timeline");
1786
+ const sourceIndex = sourceText.indexOf("## Evolution Timeline");
1787
+ if (targetIndex < 0 || sourceIndex < 0) return null;
1788
+ if (targetText.includes("Project Decisions Log")) {
1789
+ const sourcePreamble = sourceText.slice(0, sourceIndex).trim();
1790
+ const blocks = [];
1791
+ if (missing.includes(evidenceSnippet)) {
1792
+ const researchBlock = sourcePreamble.match(/Research-derived decisions use[\s\S]*?source map\./)?.[0];
1793
+ if (!researchBlock) return null;
1794
+ if (!targetText.includes(researchBlock)) blocks.push(researchBlock);
1795
+ }
1796
+ if (missing.includes(boundarySnippet)) {
1797
+ const boundaryBlock = sourcePreamble.match(/This file does not store raw build \/ upload \/ QC evidence[^\r\n]*/)?.[0];
1798
+ if (!boundaryBlock) return null;
1799
+ if (!targetText.includes(boundaryBlock)) blocks.push(boundaryBlock);
1800
+ }
1801
+ if (blocks.length > 0) {
1802
+ return `${targetText.slice(0, targetIndex).trimEnd()}\n\n${blocks.join("\n\n")}\n\n${targetText.slice(targetIndex)}`;
1803
+ }
1804
+ if (missing.includes(evidenceSnippet) || missing.includes(boundarySnippet)) return targetText;
1805
+ }
1806
+ return insertSourcePreambleBeforeHeading(targetText, sourceText, "## Evolution Timeline");
1807
+ }
1808
+
1581
1809
  function mergeProjectIndexTemplateVersionRow(targetText, sourceText) {
1582
1810
  if (projectIndexTemplateVersion(targetText)) return targetText;
1583
1811
  const sourceRow = sourceText.match(/^\| Agent Handoff Kit template version \| [\d.]+ \| [^|\n]+ \|$/m)?.[0];
@@ -1752,21 +1980,10 @@ function projectIndexTemplateVersion(text) {
1752
1980
  function mergeHandoffLifecycleField(targetText) {
1753
1981
  const openingMarker = "<!-- ack:field:opening-message-matches-current-state -->";
1754
1982
  if (!targetText.includes(openingMarker)) return null;
1755
-
1756
- const fieldBlock = "<!-- ack:field:lifecycle-conflicts-resolved -->\n- Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: Reclassified at upgrade: field added by v0.3.6+ migration; pre-existing handoff state predates it; reconcile at next closeout.\n";
1757
- let merged = targetText.replace(openingMarker, `${fieldBlock}${openingMarker}`);
1758
-
1759
- if (!merged.includes("Lifecycle consistency rule: compare `Completed This Session`")) {
1760
- 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";
1761
- const sufficiencyMarker = "<!-- ack:section:handoff-sufficiency-check -->";
1762
- if (merged.includes(sufficiencyMarker)) {
1763
- merged = merged.replace(sufficiencyMarker, `${ruleBlock}${sufficiencyMarker}`);
1764
- } else {
1765
- merged = `${merged.trimEnd()}\n\n${ruleBlock}`;
1766
- }
1767
- }
1768
1983
 
1769
- return merged;
1984
+ const fieldBlock = "<!-- ack:field:lifecycle-conflicts-resolved -->\n- Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: Reclassified at upgrade: field added by v0.3.6+ migration; pre-existing handoff state predates it; reconcile at next closeout.\n";
1985
+ let merged = targetText.replace(openingMarker, `${fieldBlock}${openingMarker}`);
1986
+ return ensureHandoffStateReconciliationRules(ensureHandoffPersistenceRoutingField(merged));
1770
1987
  }
1771
1988
 
1772
1989
  function reclassifyExistingHandoffLifecyclePlaceholder(targetText) {
@@ -1784,18 +2001,46 @@ function reclassifyExistingHandoffLifecyclePlaceholder(targetText) {
1784
2001
  if (colonIndex < 0) return null;
1785
2002
  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.`;
1786
2003
 
1787
- let merged = lines.join("\n");
1788
- if (!merged.includes("Lifecycle consistency rule: compare `Completed This Session`")) {
1789
- 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";
1790
- const sufficiencyMarker = "<!-- ack:section:handoff-sufficiency-check -->";
1791
- if (merged.includes(sufficiencyMarker)) {
1792
- merged = merged.replace(sufficiencyMarker, `${ruleBlock}${sufficiencyMarker}`);
1793
- } else {
1794
- merged = `${merged.trimEnd()}\n\n${ruleBlock}`;
1795
- }
2004
+ return ensureHandoffStateReconciliationRules(lines.join("\n"));
2005
+ }
2006
+
2007
+ function mergeHandoffPersistenceRoutingField(targetText) {
2008
+ const merged = ensureHandoffPersistenceRoutingField(targetText);
2009
+ if (!merged || merged === targetText) return null;
2010
+ return ensureHandoffStateReconciliationRules(merged);
2011
+ }
2012
+
2013
+ function ensureHandoffPersistenceRoutingField(targetText) {
2014
+ if (targetText.includes("ack:field:persistence-routing-checked")) return targetText;
2015
+ const openingMarker = "<!-- ack:field:opening-message-matches-current-state -->";
2016
+ if (!targetText.includes(openingMarker)) return null;
2017
+ const fieldBlock = "<!-- ack:field:persistence-routing-checked -->\n- Persistence routing checked: Reclassified at upgrade: field added by template migration; pre-existing handoff state predates it; reconcile at next closeout.\n";
2018
+ return targetText.replace(openingMarker, `${fieldBlock}${openingMarker}`);
2019
+ }
2020
+
2021
+ function ensureHandoffStateReconciliationRules(targetText) {
2022
+ if (!targetText) return null;
2023
+ const rules = [];
2024
+ if (!targetText.includes("Lifecycle consistency rule: compare `Completed This Session`")) {
2025
+ rules.push("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.");
2026
+ }
2027
+ if (!targetText.includes("Persistence routing rule: one-time delivery instructions")) {
2028
+ rules.push("Persistence routing rule: one-time delivery instructions, historical validation evidence, old hashes, old version facts, and incident notes must stay in trace evidence unless they still affect the next action.");
1796
2029
  }
2030
+ if (rules.length === 0) return targetText;
2031
+ const ruleBlock = `${rules.join("\n")}\n\n`;
2032
+ const sufficiencyMarker = "<!-- ack:section:handoff-sufficiency-check -->";
2033
+ if (targetText.includes(sufficiencyMarker)) {
2034
+ return targetText.replace(sufficiencyMarker, `${ruleBlock}${sufficiencyMarker}`);
2035
+ }
2036
+ return `${targetText.trimEnd()}\n\n${ruleBlock}`;
2037
+ }
1797
2038
 
1798
- return merged;
2039
+ function mergeSessionLogEvidenceDispositionField(targetText) {
2040
+ if (targetText.includes("- **Evidence disposition:**")) return targetText;
2041
+ const qcField = "- **QC:**";
2042
+ if (!targetText.includes(qcField)) return null;
2043
+ return targetText.replace(qcField, `${qcField}\n- **Evidence disposition:** <one-time only / kept as recent trace evidence / absorbed into handoff / indexed in PROJECT_INDEX / promoted to PROJECT_DECISIONS / promoted to rule pack>`);
1799
2044
  }
1800
2045
 
1801
2046
  function mergeHandoffArchiveContinuityRule(targetText, sourceText) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.22",
3
+ "version": "0.3.23",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
package/packs/research.md CHANGED
@@ -26,3 +26,5 @@ Use for source gathering, evidence comparison, fact synthesis, recommendations,
26
26
  ## Closeout
27
27
 
28
28
  Record sources used, conclusions, uncertainty, and any facts that should be persisted into project files.
29
+
30
+ If research changes a long-term decision, public claim, strategy, governance rule, or material selection, persist a research-derived decision entry using the `dev/PROJECT_DECISIONS.md` evidence-chain format. One-time fact checks do not need this extra structure.
@@ -34,6 +34,8 @@ After reading `dev/PROJECT_INDEX.md`, if `## Installed Integrations` is non-empt
34
34
 
35
35
  After startup reads are complete, show one short startup card. If onboarding is loaded, combine this card and the onboarding choice list into one first response. Do not print any standalone startup card before the onboarding rule has been read. Do not print a partial card. Do not print the cat banner twice. If you started drafting a card and then discovered onboarding applies, discard the draft and output only the final combined response.
36
36
 
37
+ Display version rule: after reading `dev/PROJECT_INDEX.md`, take the card version from the `## Stack` row `Agent Handoff Kit template version`. Print it as `vX.Y.Z`. If that row is missing, unreadable, or not a version, print `version unverified`. Never print the literal placeholder `v<version>` in user-facing startup or closeout output.
38
+
37
39
  ```text
38
40
  /\_/\ Agent Handoff Kit v<version>
39
41
  ( o.o ) continuity ready
@@ -45,7 +47,7 @@ After startup reads are complete, show one short startup card. If onboarding is
45
47
  🚀 下一步:<next action>
46
48
  ```
47
49
 
48
- Keep the card short. Use plain Traditional Chinese labels in user-facing output. Use the full product name, not an abbreviation. If the installed template or CLI version is unknown, write `version unverified` instead of guessing.
50
+ Keep the card short. Use plain Traditional Chinese labels in user-facing output. Use the full product name, not an abbreviation.
49
51
 
50
52
  ## 2. Work Loop
51
53
 
@@ -55,7 +57,7 @@ Use this loop for every task:
55
57
  2. READ: inspect relevant files from `PROJECT_INDEX.md` and search for related definitions before editing.
56
58
  3. CHANGE: make focused changes only.
57
59
  4. QC: run available checks or state why they cannot run.
58
- 5. PERSIST: classify durable facts before writing them. Current state belongs in handoff, chronological evidence in log, file / command / reference maps in project index, sync obligations in doc sync registry, and reusable operating procedure in the relevant rule pack or registered reference. Do not store reusable procedure knowledge only in handoff or log.
60
+ 5. PERSIST: classify durable facts before writing them. Current state belongs in handoff, chronological evidence in log, file / command / reference maps in project index, sync obligations in doc sync registry, and reusable operating procedure in the relevant rule pack or registered reference. Do not persist one-time delivery instructions, historical validation evidence, old hashes, old version facts, or incident notes as current state, next priorities, durable anchors, or startup instructions. Do not store reusable procedure knowledge only in handoff or log.
59
61
 
60
62
  External skill flows, subagents, task plans, or another tool's "finish" step do not replace this loop. If you use any of them, the PLAN must include a final Agent Handoff Kit persistence step for the active project root, and completion cannot be claimed until that root's `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, and `dev/DOC_SYNC_REGISTRY.md` have been inspected and updated or explicitly marked not applicable.
61
63
 
@@ -94,7 +96,7 @@ At full closeout:
94
96
  3. Update `dev/PROJECT_INDEX.md` if files, stack, commands, entry points, workspace identity, or durable document map changed.
95
97
  4. Check `dev/DOC_SYNC_REGISTRY.md` and record required sync status.
96
98
  5. Record unresolved drift risk, active worktree, parallel workspace, uncommitted changes, or blocked verification.
97
- 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.
99
+ 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 the `Persistence routing checked` field is complete, 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.
98
100
  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.
99
101
  8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
100
102
  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 the stateful startup prompt that the next local agent must read. 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.
@@ -103,11 +105,11 @@ At full closeout:
103
105
 
104
106
  Hard triggers:
105
107
 
106
- (a) Advance the SESSION_LOG N-rule (R-010 SESSION_LOG handoff-role discipline) when `dev/SESSION_LOG.md` reaches N ≥ 11 entries, or when the main log exceeds 1500 lines. If triggered, move N ≥ 11 entries into `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` with raw content preserved, maintain `dev/SESSION_LOG_archive/INDEX.md`, collapse absorbed N=4–10 entries to short-index lines, and port any unique narrative into the relevant durable source before collapsing it. Handoff capability rests on `dev/SESSION_HANDOFF.md`; `dev/SESSION_LOG.md` is trace-back / audit trail and does not carry handoff responsibility.
108
+ (a) Advance the SESSION_LOG N-rule (R-010 SESSION_LOG handoff-role discipline) when `dev/SESSION_LOG.md` reaches N ≥ 11 entries, or when the main log exceeds 1500 lines. If triggered, move N ≥ 11 entries into `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` with raw content preserved, maintain `dev/SESSION_LOG_archive/INDEX.md`, collapse absorbed N=4–10 entries to short-index lines, and port any unique narrative into the relevant durable source before collapsing it. If a research trail affected a long-term decision, public claim, strategy, governance rule, or material selection, port its evidence chain into `dev/PROJECT_DECISIONS.md` using that file's research-derived decision format before collapsing the log. Handoff capability rests on `dev/SESSION_HANDOFF.md`; `dev/SESSION_LOG.md` is trace-back / audit trail and does not carry handoff responsibility.
107
109
 
108
110
  (b) Maintain `dev/PROJECT_DECISIONS.md` per R-028 project narrative discipline when `dev/SESSION_HANDOFF.md` contains a decisions-like H2 section (e.g. `## Confirmed Decisions`, `## Decisions`, `## 已定案決策`) with a numbered list of ≥ 30 entries. If triggered, split the oldest entries, retaining the most recent 8–22 in the handoff hot tier, into `dev/PROJECT_DECISIONS.md` `## Decisions Archive`, newest first.
109
111
 
110
- (c) Append to `dev/PROJECT_DECISIONS.md` immediately, or at closeout, when the current session includes substantive task evolution, a multi-option architectural trade-off with recorded rationale, a cross-session accumulated pattern, or a user retrospective question. Use `## Evolution Timeline`, `## Architecture Choices`, or `## Insights & Learnings` as appropriate.
112
+ (c) Append to `dev/PROJECT_DECISIONS.md` immediately, or at closeout, when the current session includes substantive task evolution, a multi-option architectural trade-off with recorded rationale, a cross-session accumulated pattern, or a user retrospective question. Use `## Evolution Timeline`, `## Architecture Choices`, or `## Insights & Learnings` as appropriate. If the decision is research-derived, use that file's evidence-chain format so the source, summary, inference, decision impact, and uncertainty survive future compression.
111
113
 
112
114
  (d) Run a full long-term maintenance pass every 10 closeouts as a backstop, even if no trigger seems obvious. Count closeouts from the main `dev/SESSION_LOG.md` entries plus archive index entry counts when an archive exists; if the count cannot be determined confidently, treat the current N=10 boundary as the backstop trigger.
113
115
 
@@ -115,10 +117,12 @@ At full closeout:
115
117
 
116
118
  Installed handoff templates use English headings by default for cross-tool stability, but project teams may translate `dev/SESSION_HANDOFF.md` section headings and visible field labels into the project's working language. Keep the `ack:section:*` and `ack:field:*` semantic markers intact; `doctor` validates those markers so localized handoff notes remain supported.
117
119
 
118
- Use this closeout card:
119
-
120
- ```text
121
- /\_/\ Agent Handoff Kit v<version>
120
+ Use this closeout card:
121
+
122
+ Use the same display version rule as startup: take the version from `dev/PROJECT_INDEX.md` `## Stack` row `Agent Handoff Kit template version`, print it as `vX.Y.Z`, and fall back to `version unverified` only when it cannot be verified. Never print the literal placeholder `v<version>`.
123
+
124
+ ```text
125
+ /\_/\ Agent Handoff Kit v<version>
122
126
  ( -.- ) handoff saved
123
127
  > ^ <
124
128
 
@@ -146,7 +150,7 @@ A pack may add task-specific requirements. A pack cannot weaken core safety. If
146
150
 
147
151
  When a task references external tools (Notion / Google Drive / Slack / Linear / GitHub / Dropbox / HubSpot / Atlassian / etc.) or `dev/PROJECT_INDEX.md` `## Installed Integrations` is non-empty, load `dev/rules/integrations.md` together with the relevant domain pack. The integrations pack covers Connector-first defaults, credential separation, multi-layer source-of-truth architecture, and cross-session resilience for declared integrations.
148
152
 
149
- After the task, persist durable facts into the correct home: handoff for current state, log for trace evidence, project index for file / command / reference maps, doc sync registry for sync obligations, and rule packs or registered references for reusable operating procedures. Do not assume the next session remembers pack context unless it is recorded, and do not treat handoff/log persistence as sufficient for reusable procedure knowledge.
153
+ After the task, persist durable facts into the correct home: handoff for current state, log for trace evidence, project index for file / command / reference maps, doc sync registry for sync obligations, project decisions for long-term decisions or research-derived rationale, and rule packs or registered references for reusable operating procedures. Do not assume the next session remembers pack context unless it is recorded, and do not treat handoff/log persistence as sufficient for reusable procedure knowledge.
150
154
 
151
155
  If a pack, skill, subagent plan, demo workspace, or external workflow produces its own closeout, treat it as subordinate evidence. The active project root still needs Agent Handoff Kit persistence before the task is complete.
152
156
 
@@ -7,6 +7,16 @@
7
7
 
8
8
  不需要你手動寫 —— AI 在收工時自動 update;重大決策可在發生時即時記錄,不必等到最後才回想。
9
9
 
10
+ Research-derived decisions use this compact evidence-chain format inside the relevant section, without creating a new section:
11
+
12
+ ```text
13
+ - YYYY-MM-DD [research-derived] Decision summary. Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.
14
+ ```
15
+
16
+ The `source:<id>` token must also appear in `dev/PROJECT_INDEX.md` under `Fact Base` or `External Sources`, so later sessions can trace the decision back to its source map.
17
+
18
+ This file does not store raw build / upload / QC evidence, current next actions, one-time task results, or reusable operating procedures. Keep those in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or the relevant rule pack / registered reference.
19
+
10
20
  ---
11
21
 
12
22
  ## Evolution Timeline
@@ -111,6 +111,8 @@ At full closeout, complete this check after updating the state sections above.
111
111
  - Stale snapshots left in this handoff: TBD
112
112
  <!-- ack:field:lifecycle-conflicts-resolved -->
113
113
  - Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD
114
+ <!-- ack:field:persistence-routing-checked -->
115
+ - Persistence routing checked: TBD
114
116
  <!-- ack:field:opening-message-matches-current-state -->
115
117
  - Opening message matches current state: TBD
116
118
  <!-- ack:field:next-ai-can-continue -->
@@ -118,7 +120,7 @@ At full closeout, complete this check after updating the state sections above.
118
120
 
119
121
  If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready.
120
122
 
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.
123
+ 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. Persistence routing rule: one-time delivery instructions, historical validation evidence, old hashes, old version facts, and incident notes must stay in trace evidence unless they still affect the next action.
122
124
 
123
125
  <!-- ack:section:handoff-sufficiency-check -->
124
126
  ## Handoff Sufficiency Check
@@ -20,6 +20,7 @@ Before closeout, record whether older log detail was kept, summarized, or archiv
20
20
  - **Changed:** <files changed, or none>
21
21
  - **Done:** <work completed this session>
22
22
  - **QC:** <checks run and results, or why not run>
23
+ - **Evidence disposition:** <one-time only / kept as recent trace evidence / absorbed into handoff / indexed in PROJECT_INDEX / promoted to PROJECT_DECISIONS / promoted to rule pack>
23
24
  - **Sync:** <doc/external sync status>
24
25
  - **Pending:** <next work>
25
26
  - **Risks:** <known risks or none>