@adamchanadam/agent-handoff-kit 0.3.5 → 0.3.6
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 +170 -38
- package/docs/whatsnew/v0.3.6.md +19 -0
- package/package.json +1 -1
- package/runtime-core/AGENTS.core.md +8 -8
- package/runtime-core/SESSION_HANDOFF.md +12 -8
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
狀態:目前版本為 `v0.3.
|
|
3
|
+
狀態:目前版本為 `v0.3.6`。這是早期可用版本,仍在持續完善中。
|
|
4
4
|
|
|
5
5
|

|
|
6
6
|
|
|
@@ -239,7 +239,7 @@ Agent Handoff Kit 同 [Adam-AI-Instructions](https://github.com/prompt-templates
|
|
|
239
239
|
|
|
240
240
|
## 目前限制
|
|
241
241
|
|
|
242
|
-
- 目前版本為 `v0.3.
|
|
242
|
+
- 目前版本為 `v0.3.6`。
|
|
243
243
|
- 這是早期可用版本,仍在持續完善中。
|
|
244
244
|
- 升級合併屬窄範圍策略,不是完整的複雜合併工具。
|
|
245
245
|
- `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
|
|
@@ -71,11 +71,12 @@ const requiredAnchors = [
|
|
|
71
71
|
"fenced `text` code block",
|
|
72
72
|
"handoff saved",
|
|
73
73
|
"📋 Next session: copy and paste the whole block below",
|
|
74
|
-
"State Reconciliation Check",
|
|
75
|
-
"
|
|
76
|
-
"
|
|
77
|
-
|
|
78
|
-
|
|
74
|
+
"State Reconciliation Check",
|
|
75
|
+
"handoff lifecycle consistency",
|
|
76
|
+
"Do not append a new state snapshot",
|
|
77
|
+
"START_NEXT_SESSION_PROMPT.txt"
|
|
78
|
+
]
|
|
79
|
+
},
|
|
79
80
|
{
|
|
80
81
|
target: "START_NEXT_SESSION_PROMPT.txt",
|
|
81
82
|
label: "next-session prompt convenience copy",
|
|
@@ -101,11 +102,12 @@ const requiredAnchors = [
|
|
|
101
102
|
"ack:section:workspace-identity",
|
|
102
103
|
"ack:section:sync-status",
|
|
103
104
|
"ack:section:next-task-required-reading",
|
|
104
|
-
"ack:section:state-reconciliation-check",
|
|
105
|
-
"ack:section:next-session-opening-message",
|
|
106
|
-
"
|
|
107
|
-
"
|
|
108
|
-
"
|
|
105
|
+
"ack:section:state-reconciliation-check",
|
|
106
|
+
"ack:section:next-session-opening-message",
|
|
107
|
+
"ack:field:lifecycle-conflicts-resolved",
|
|
108
|
+
"📋 Next session: copy and paste the whole block below",
|
|
109
|
+
"```text",
|
|
110
|
+
"Read in order:",
|
|
109
111
|
"dev/DOC_SYNC_REGISTRY.md"
|
|
110
112
|
]
|
|
111
113
|
},
|
|
@@ -247,10 +249,11 @@ const schemaChecks = [
|
|
|
247
249
|
section("state-reconciliation-check", "State Reconciliation Check"),
|
|
248
250
|
section("handoff-sufficiency-check", "Handoff Sufficiency Check"),
|
|
249
251
|
section("next-session-opening-message", "Next Session Opening Message"),
|
|
250
|
-
marker("field", "stale-snapshots-left", "Stale snapshots left in this handoff"),
|
|
251
|
-
marker("field", "
|
|
252
|
-
marker("field", "
|
|
253
|
-
marker("field", "
|
|
252
|
+
marker("field", "stale-snapshots-left", "Stale snapshots left in this handoff"),
|
|
253
|
+
marker("field", "lifecycle-conflicts-resolved", "Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified"),
|
|
254
|
+
marker("field", "opening-message-matches-current-state", "Opening message matches current state"),
|
|
255
|
+
marker("field", "state-sections-rewritten-or-confirmed", "State sections rewritten or confirmed current"),
|
|
256
|
+
marker("field", "user-intent", "User intent:"),
|
|
254
257
|
marker("field", "task-essence", "Task essence:"),
|
|
255
258
|
marker("field", "success-criteria", "Success criteria:")
|
|
256
259
|
]
|
|
@@ -263,12 +266,22 @@ const schemaChecks = [
|
|
|
263
266
|
includes("```text"),
|
|
264
267
|
includes("Work in "),
|
|
265
268
|
includes("Read in order:"),
|
|
266
|
-
includes("If this root does not match the expected project root")
|
|
267
|
-
]
|
|
268
|
-
},
|
|
269
|
-
{
|
|
270
|
-
target: "dev/
|
|
271
|
-
label: "
|
|
269
|
+
includes("If this root does not match the expected project root")
|
|
270
|
+
]
|
|
271
|
+
},
|
|
272
|
+
{
|
|
273
|
+
target: "dev/SESSION_HANDOFF.md",
|
|
274
|
+
label: "handoff lifecycle consistency",
|
|
275
|
+
checks: [
|
|
276
|
+
{
|
|
277
|
+
label: "completed work is not carried forward as unresolved next work",
|
|
278
|
+
test: (text) => assessHandoffLifecycleConsistency(text).ok
|
|
279
|
+
}
|
|
280
|
+
]
|
|
281
|
+
},
|
|
282
|
+
{
|
|
283
|
+
target: "dev/SESSION_LOG.md",
|
|
284
|
+
label: "session log entry fields",
|
|
272
285
|
checks: [
|
|
273
286
|
heading("Entry Template"),
|
|
274
287
|
includes("- **ID:**"),
|
|
@@ -869,13 +882,97 @@ function extractOpeningMessage(text) {
|
|
|
869
882
|
return text.slice(contentStart + 1, fenceEnd).trim();
|
|
870
883
|
}
|
|
871
884
|
|
|
872
|
-
function normalizePrompt(text) {
|
|
873
|
-
return text.replace(/\r\n/g, "\n").trim();
|
|
874
|
-
}
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
const
|
|
878
|
-
|
|
885
|
+
function normalizePrompt(text) {
|
|
886
|
+
return text.replace(/\r\n/g, "\n").trim();
|
|
887
|
+
}
|
|
888
|
+
|
|
889
|
+
function assessHandoffLifecycleConsistency(text) {
|
|
890
|
+
const fieldValue = fieldValueAfterMarker(text, "lifecycle-conflicts-resolved");
|
|
891
|
+
if (fieldValue && /\b(no|blocked|uncertain)\b|否|阻擋|不確定/i.test(fieldValue)) {
|
|
892
|
+
return { ok: false, reason: "lifecycle field is explicitly unresolved" };
|
|
893
|
+
}
|
|
894
|
+
|
|
895
|
+
const evidenceText = [
|
|
896
|
+
extractSectionText(text, "completed-this-session", "Completed This Session"),
|
|
897
|
+
extractSectionText(text, "validation-qc", "Validation / QC")
|
|
898
|
+
].join("\n");
|
|
899
|
+
const targetText = [
|
|
900
|
+
extractSectionText(text, "next-priorities", "Next Priorities"),
|
|
901
|
+
extractSectionText(text, "risks-blockers", "Risks / Blockers"),
|
|
902
|
+
extractSectionText(text, "next-session-opening-message", "Next Session Opening Message")
|
|
903
|
+
].join("\n");
|
|
904
|
+
|
|
905
|
+
const topics = extractLifecycleTopics(evidenceText);
|
|
906
|
+
for (const topic of topics) {
|
|
907
|
+
if (hasUnresolvedCarryForward(targetText, topic)) {
|
|
908
|
+
return { ok: false, reason: `completed topic carried forward unresolved: ${topic}` };
|
|
909
|
+
}
|
|
910
|
+
}
|
|
911
|
+
|
|
912
|
+
return { ok: true, reason: "" };
|
|
913
|
+
}
|
|
914
|
+
|
|
915
|
+
function extractLifecycleTopics(text) {
|
|
916
|
+
const topics = new Set();
|
|
917
|
+
for (const match of text.matchAll(/`([^`\n]{2,80})`/g)) {
|
|
918
|
+
const topic = match[1].trim();
|
|
919
|
+
if (!topic || /^dev\/|^docs\/|\.md$|\.txt$|\.json$|^AGENTS\.md$/.test(topic)) continue;
|
|
920
|
+
topics.add(topic);
|
|
921
|
+
}
|
|
922
|
+
return [...topics];
|
|
923
|
+
}
|
|
924
|
+
|
|
925
|
+
function hasUnresolvedCarryForward(text, topic) {
|
|
926
|
+
const escaped = escapeRegExp(topic);
|
|
927
|
+
const pattern = new RegExp(escaped, "ig");
|
|
928
|
+
for (const match of text.matchAll(pattern)) {
|
|
929
|
+
const start = Math.max(0, match.index - 180);
|
|
930
|
+
const end = Math.min(text.length, match.index + topic.length + 180);
|
|
931
|
+
const context = text.slice(start, end);
|
|
932
|
+
if (/\b(monitor-only|follow-up scope|blocked|reopened|re-opened|if new evidence|conditional|no-op)\b|只監察|監察|後續範圍|跟進範圍|阻擋|已重開|明確重開|新證據/i.test(context)) {
|
|
933
|
+
continue;
|
|
934
|
+
}
|
|
935
|
+
if (/\b(investigate|reproduce|pending|todo|unresolved|must start|start with read-only|reliability concern remains open|needs investigation)\b|調查|重查|未解|待辦|仍需|未完成|開始.{0,20}核查|先.{0,20}調查/i.test(context)) {
|
|
936
|
+
return true;
|
|
937
|
+
}
|
|
938
|
+
}
|
|
939
|
+
return false;
|
|
940
|
+
}
|
|
941
|
+
|
|
942
|
+
function fieldValueAfterMarker(text, fieldId) {
|
|
943
|
+
const markerText = `ack:field:${fieldId}`;
|
|
944
|
+
const markerIndex = text.indexOf(markerText);
|
|
945
|
+
if (markerIndex >= 0) {
|
|
946
|
+
const after = text.slice(markerIndex).split(/\r?\n/).slice(1);
|
|
947
|
+
const line = after.find((candidate) => candidate.trim().startsWith("- "));
|
|
948
|
+
if (!line) return "";
|
|
949
|
+
const colonIndex = line.indexOf(":");
|
|
950
|
+
return colonIndex >= 0 ? line.slice(colonIndex + 1).trim() : line.trim();
|
|
951
|
+
}
|
|
952
|
+
const fallback = text.match(/Completed \/ pending \/ risk \/ opening-message lifecycle conflicts resolved or explicitly reclassified:\s*([^\n]+)/i);
|
|
953
|
+
return fallback ? fallback[1].trim() : "";
|
|
954
|
+
}
|
|
955
|
+
|
|
956
|
+
function extractSectionText(text, markerId, headingTitle) {
|
|
957
|
+
const markerText = `ack:section:${markerId}`;
|
|
958
|
+
const markerIndex = text.indexOf(markerText);
|
|
959
|
+
if (markerIndex >= 0) {
|
|
960
|
+
const start = text.indexOf("\n", markerIndex);
|
|
961
|
+
if (start < 0) return "";
|
|
962
|
+
const nextMarker = text.indexOf("<!-- ack:section:", start + 1);
|
|
963
|
+
return text.slice(start + 1, nextMarker >= 0 ? nextMarker : text.length);
|
|
964
|
+
}
|
|
965
|
+
|
|
966
|
+
const headingMatch = new RegExp(`^## ${escapeRegExp(headingTitle)}\\s*$`, "m").exec(text);
|
|
967
|
+
if (!headingMatch) return "";
|
|
968
|
+
const start = headingMatch.index + headingMatch[0].length;
|
|
969
|
+
const nextHeading = /\n##\s+/.exec(text.slice(start));
|
|
970
|
+
return text.slice(start, nextHeading ? start + nextHeading.index : text.length);
|
|
971
|
+
}
|
|
972
|
+
|
|
973
|
+
async function checkRequiredAnchors(root) {
|
|
974
|
+
const rows = [];
|
|
975
|
+
for (const rule of requiredAnchors) {
|
|
879
976
|
const filePath = path.join(root, rule.target);
|
|
880
977
|
let text = "";
|
|
881
978
|
try {
|
|
@@ -1072,24 +1169,59 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
|
|
|
1072
1169
|
// content and any user customization preserved. Step 1 micro-question additions to Scenarios A-E
|
|
1073
1170
|
// are NOT auto-migrated (user-customizable inline sample wording, not anchor-enforced); users get
|
|
1074
1171
|
// those on fresh install only or can manually patch following CHANGELOG migration guidance.
|
|
1075
|
-
if (targetRel === "dev/rules/onboarding.md" && command === "upgrade" && !targetText.includes("Scenario F. 審視已裝外部工具")) {
|
|
1076
|
-
const sourceScenarioFMatch = sourceText.match(/(### Scenario F\. 審視已裝外部工具[\s\S]*?)(?=## Cross-reference to guide\.html)/);
|
|
1077
|
-
if (sourceScenarioFMatch && targetText.includes("## Cross-reference to guide.html")) {
|
|
1078
|
-
const scenarioFBlock = sourceScenarioFMatch[1];
|
|
1079
|
-
return {
|
|
1172
|
+
if (targetRel === "dev/rules/onboarding.md" && command === "upgrade" && !targetText.includes("Scenario F. 審視已裝外部工具")) {
|
|
1173
|
+
const sourceScenarioFMatch = sourceText.match(/(### Scenario F\. 審視已裝外部工具[\s\S]*?)(?=## Cross-reference to guide\.html)/);
|
|
1174
|
+
if (sourceScenarioFMatch && targetText.includes("## Cross-reference to guide.html")) {
|
|
1175
|
+
const scenarioFBlock = sourceScenarioFMatch[1];
|
|
1176
|
+
return {
|
|
1080
1177
|
...base,
|
|
1081
1178
|
action: "merge",
|
|
1082
1179
|
reason: "insert ### Scenario F block before ## Cross-reference to guide.html (R-030 onboarding pack migration; existing Scenarios A-E content preserved non-destructively)",
|
|
1083
1180
|
mergedText: targetText.replace("## Cross-reference to guide.html", scenarioFBlock + "## Cross-reference to guide.html")
|
|
1084
|
-
};
|
|
1085
|
-
}
|
|
1086
|
-
}
|
|
1087
|
-
|
|
1088
|
-
|
|
1089
|
-
|
|
1181
|
+
};
|
|
1182
|
+
}
|
|
1183
|
+
}
|
|
1184
|
+
// v0.3.6+: SESSION_HANDOFF.md gains a non-destructive lifecycle consistency
|
|
1185
|
+
// field. Existing handoff content stays intact; only the missing field and
|
|
1186
|
+
// rule note are inserted around stable ack markers.
|
|
1187
|
+
if (targetRel === "dev/SESSION_HANDOFF.md" && command === "upgrade" && !targetText.includes("ack:field:lifecycle-conflicts-resolved")) {
|
|
1188
|
+
const mergedHandoff = mergeHandoffLifecycleField(targetText);
|
|
1189
|
+
if (!mergedHandoff) {
|
|
1190
|
+
return { ...base, action: "conflict", reason: "SESSION_HANDOFF.md state reconciliation markers were changed; manual merge required to add lifecycle consistency field" };
|
|
1191
|
+
}
|
|
1192
|
+
return {
|
|
1193
|
+
...base,
|
|
1194
|
+
action: "merge",
|
|
1195
|
+
reason: "insert lifecycle consistency field into State Reconciliation Check (completed work must not carry forward as unresolved next work)",
|
|
1196
|
+
mergedText: mergedHandoff
|
|
1197
|
+
};
|
|
1198
|
+
}
|
|
1199
|
+
if ((targetRel === "CLAUDE.md" || targetRel === "GEMINI.md") && !targetText.includes("AGENTS.md")) {
|
|
1200
|
+
return { ...base, action: "conflict", reason: "existing bridge does not route to AGENTS.md" };
|
|
1201
|
+
}
|
|
1090
1202
|
return { ...base, action: "skip", reason: "preserve existing file" };
|
|
1091
1203
|
}
|
|
1092
1204
|
|
|
1205
|
+
function mergeHandoffLifecycleField(targetText) {
|
|
1206
|
+
const openingMarker = "<!-- ack:field:opening-message-matches-current-state -->";
|
|
1207
|
+
if (!targetText.includes(openingMarker)) return null;
|
|
1208
|
+
|
|
1209
|
+
const fieldBlock = "<!-- ack:field:lifecycle-conflicts-resolved -->\n- Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD\n";
|
|
1210
|
+
let merged = targetText.replace(openingMarker, `${fieldBlock}${openingMarker}`);
|
|
1211
|
+
|
|
1212
|
+
if (!merged.includes("Lifecycle consistency rule: compare `Completed This Session`")) {
|
|
1213
|
+
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";
|
|
1214
|
+
const sufficiencyMarker = "<!-- ack:section:handoff-sufficiency-check -->";
|
|
1215
|
+
if (merged.includes(sufficiencyMarker)) {
|
|
1216
|
+
merged = merged.replace(sufficiencyMarker, `${ruleBlock}${sufficiencyMarker}`);
|
|
1217
|
+
} else {
|
|
1218
|
+
merged = `${merged.trimEnd()}\n\n${ruleBlock}`;
|
|
1219
|
+
}
|
|
1220
|
+
}
|
|
1221
|
+
|
|
1222
|
+
return merged;
|
|
1223
|
+
}
|
|
1224
|
+
|
|
1093
1225
|
function mergeRulePacksRows(targetText, sourceText) {
|
|
1094
1226
|
const requiredPacks = [
|
|
1095
1227
|
"dev/rules/onboarding.md",
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# v0.3.6
|
|
2
|
+
|
|
3
|
+
## 本版新加了甚麼
|
|
4
|
+
|
|
5
|
+
- `doctor` 新增交接生命週期一致性檢查:已完成或已驗證的事項,不應又以未解待辦、風險或下一次開工指令交給下一輪 AI。
|
|
6
|
+
- `dev/SESSION_HANDOFF.md` 的 `State Reconciliation Check` 新增一個欄位,要求 closeout 時明確確認完成/待辦/風險/開工訊息之間沒有矛盾,或已清楚重新分類。
|
|
7
|
+
- 發佈級 QA 新增反例驗收,覆蓋「`doctor` / `upgrade` 已完成,但 opening message 又要求下一輪重新調查」這類交接漂移。
|
|
8
|
+
|
|
9
|
+
## 對你已有檔案的影響
|
|
10
|
+
|
|
11
|
+
- 既有用戶內容應保留。
|
|
12
|
+
- 升級後,`dev/SESSION_HANDOFF.md` 會補上新的交接對賬欄位。
|
|
13
|
+
- 若舊 handoff 同時寫着某件事已完成、又把同一件事列為未解調查,`doctor` 會提示先修 handoff,不會把這種矛盾視為健康狀態。
|
|
14
|
+
|
|
15
|
+
## 建議下一步
|
|
16
|
+
|
|
17
|
+
- 已安裝舊版的專案,先執行 `npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run`。
|
|
18
|
+
- 預演結果沒有衝突後,再執行 `npx @adamchanadam/agent-handoff-kit@latest upgrade`。
|
|
19
|
+
- 升級後執行 `npx @adamchanadam/agent-handoff-kit@latest doctor`,確認交接狀態與下一步一致。
|
package/package.json
CHANGED
|
@@ -88,14 +88,14 @@ At full closeout:
|
|
|
88
88
|
3. Update `dev/PROJECT_INDEX.md` if files, stack, commands, entry points, workspace identity, or durable document map changed.
|
|
89
89
|
4. Check `dev/DOC_SYNC_REGISTRY.md` and record required sync status.
|
|
90
90
|
5. Record unresolved drift risk, active worktree, parallel workspace, uncommitted changes, or blocked verification.
|
|
91
|
-
6. Complete the `State Reconciliation Check`: it must state when reconciliation happened, which state sections were rewritten or confirmed current, whether stale snapshots remain, and whether the opening message matches current state.
|
|
92
|
-
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.
|
|
93
|
-
8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
|
|
94
|
-
9. Show a short closeout card, then provide a copy-paste-ready next-session opening message inside a fenced `text` code block, so the user can clearly copy and paste it into the next session.
|
|
95
|
-
10. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the fenced opening message in `dev/SESSION_HANDOFF.md`. `dev/SESSION_HANDOFF.md` is authoritative; `START_NEXT_SESSION_PROMPT.txt` is only a convenience copy for the user to paste at the next startup.
|
|
96
|
-
11. Advance the SESSION_LOG N-rule (R-010 SESSION_LOG handoff-role discipline). After prepending the new closeout entry, count `## YYYY-MM-DD` H2 entries in `dev/SESSION_LOG.md`. Any entry now at position N ≥ 11 (oldest end) must be moved into `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` with raw content preserved. Maintain `dev/SESSION_LOG_archive/INDEX.md` (master index of all archive batches; create on first archive). Entries at N=4–10 whose core facts are already absorbed into HANDOFF / PROJECT_INDEX / requirements / decision records collapse to a short-index line using structural anchors, not line numbers. Entries with unique narrative not yet absorbed must first be ported into the relevant durable source, then collapsed. This is mandatory; do not skip. Handoff capability rests on `dev/SESSION_HANDOFF.md`; `dev/SESSION_LOG.md` is trace-back / audit trail and does not carry handoff responsibility.
|
|
97
|
-
|
|
98
|
-
12. Maintain `dev/PROJECT_DECISIONS.md` per R-028 project narrative discipline. Each closeout must run the following checks with equal mechanical rigor as the SESSION_LOG N-rule (step 11):
|
|
91
|
+
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.
|
|
92
|
+
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.
|
|
93
|
+
8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
|
|
94
|
+
9. Show a short closeout card, then provide a copy-paste-ready next-session opening message inside a fenced `text` code block, so the user can clearly copy and paste it into the next session.
|
|
95
|
+
10. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the fenced opening message in `dev/SESSION_HANDOFF.md`. `dev/SESSION_HANDOFF.md` is authoritative; `START_NEXT_SESSION_PROMPT.txt` is only a convenience copy for the user to paste at the next startup.
|
|
96
|
+
11. Advance the SESSION_LOG N-rule (R-010 SESSION_LOG handoff-role discipline). After prepending the new closeout entry, count `## YYYY-MM-DD` H2 entries in `dev/SESSION_LOG.md`. Any entry now at position N ≥ 11 (oldest end) must be moved into `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` with raw content preserved. Maintain `dev/SESSION_LOG_archive/INDEX.md` (master index of all archive batches; create on first archive). Entries at N=4–10 whose core facts are already absorbed into HANDOFF / PROJECT_INDEX / requirements / decision records collapse to a short-index line using structural anchors, not line numbers. Entries with unique narrative not yet absorbed must first be ported into the relevant durable source, then collapsed. This is mandatory; do not skip. Handoff capability rests on `dev/SESSION_HANDOFF.md`; `dev/SESSION_LOG.md` is trace-back / audit trail and does not carry handoff responsibility.
|
|
97
|
+
|
|
98
|
+
12. Maintain `dev/PROJECT_DECISIONS.md` per R-028 project narrative discipline. Each closeout must run the following checks with equal mechanical rigor as the SESSION_LOG N-rule (step 11):
|
|
99
99
|
|
|
100
100
|
(a) Decisions split check: If `dev/SESSION_HANDOFF.md` contains a decisions-like H2 section (e.g. `## Confirmed Decisions`, `## Decisions`, `## 已定案決策`) with a numbered list of ≥ 30 entries, AI must split the oldest entries (retaining the most recent 8–22 in the handoff hot tier) into `dev/PROJECT_DECISIONS.md` `## Decisions Archive`, newest first. If no such section exists in the handoff, this check is no-op (default for short single-task projects).
|
|
101
101
|
|
|
@@ -107,14 +107,18 @@ At full closeout, complete this check after updating the state sections above.
|
|
|
107
107
|
- Reconciled at: TBD
|
|
108
108
|
<!-- ack:field:state-sections-rewritten-or-confirmed -->
|
|
109
109
|
- State sections rewritten or confirmed current: TBD
|
|
110
|
-
<!-- ack:field:stale-snapshots-left -->
|
|
111
|
-
- Stale snapshots left in this handoff: TBD
|
|
112
|
-
<!-- ack:field:
|
|
113
|
-
-
|
|
114
|
-
<!-- ack:field:
|
|
115
|
-
-
|
|
116
|
-
|
|
117
|
-
|
|
110
|
+
<!-- ack:field:stale-snapshots-left -->
|
|
111
|
+
- Stale snapshots left in this handoff: TBD
|
|
112
|
+
<!-- ack:field:lifecycle-conflicts-resolved -->
|
|
113
|
+
- Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD
|
|
114
|
+
<!-- ack:field:opening-message-matches-current-state -->
|
|
115
|
+
- Opening message matches current state: TBD
|
|
116
|
+
<!-- ack:field:next-ai-can-continue -->
|
|
117
|
+
- Next AI can continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history: TBD
|
|
118
|
+
|
|
119
|
+
If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready.
|
|
120
|
+
|
|
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.
|
|
118
122
|
|
|
119
123
|
<!-- ack:section:handoff-sufficiency-check -->
|
|
120
124
|
## Handoff Sufficiency Check
|