@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 +2 -2
- package/bin/agent-handoff-kit.mjs +319 -74
- package/package.json +1 -1
- package/packs/research.md +2 -0
- package/runtime-core/AGENTS.core.md +14 -10
- package/runtime-core/PROJECT_DECISIONS.md +10 -0
- package/runtime-core/SESSION_HANDOFF.md +3 -1
- package/runtime-core/SESSION_LOG.md +1 -0
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
狀態:目前版本為 `v0.3.
|
|
3
|
+
狀態:目前版本為 `v0.3.23`。這是早期可用版本,仍在持續完善中。
|
|
4
4
|
|
|
5
5
|

|
|
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.
|
|
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
|
-
"
|
|
183
|
-
"
|
|
184
|
-
"
|
|
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", "
|
|
258
|
-
marker("field", "
|
|
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("- **
|
|
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("
|
|
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
|
|
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 =
|
|
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
|
-
|
|
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
|
-
|
|
1788
|
-
|
|
1789
|
-
|
|
1790
|
-
|
|
1791
|
-
|
|
1792
|
-
|
|
1793
|
-
|
|
1794
|
-
|
|
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
|
-
|
|
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
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.
|
|
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
|
-
|
|
121
|
-
|
|
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>
|