@adamchanadam/agent-handoff-kit 0.3.4 → 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 +337 -143
- package/docs/whatsnew/v0.3.5.md +20 -0
- 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
|
-
|
|
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:**"),
|
|
@@ -510,7 +523,7 @@ async function runInstall(command, root, options, version) {
|
|
|
510
523
|
}
|
|
511
524
|
}
|
|
512
525
|
|
|
513
|
-
printPlan(command, root, mode, plan, version);
|
|
526
|
+
printPlan(command, root, mode, plan, version, options.dryRun);
|
|
514
527
|
|
|
515
528
|
if (options.dryRun) {
|
|
516
529
|
console.log("\ndry-run: no files written");
|
|
@@ -627,16 +640,19 @@ async function runInstall(command, root, options, version) {
|
|
|
627
640
|
if (command === "upgrade" && conflicts.length === 0) {
|
|
628
641
|
console.log("");
|
|
629
642
|
console.log("------------------------------------------------------------");
|
|
630
|
-
console.log("🩺 upgrade self-check: running doctor against the upgraded root");
|
|
643
|
+
console.log("🩺 upgrade self-check: running doctor against the upgraded root");
|
|
631
644
|
console.log("------------------------------------------------------------");
|
|
632
645
|
const doctorStatus = await runDoctor(root, version, { silentCard: true });
|
|
633
|
-
if (doctorStatus !== "passed") {
|
|
634
|
-
console.log("");
|
|
635
|
-
console.log("⚠️ upgrade self-check did not pass; see doctor output above.");
|
|
636
|
-
console.log("📋 下一步:把上面 doctor 輸出貼給 AI,請它先按提示修補後再宣稱 upgrade 完成。");
|
|
637
|
-
process.exitCode = 1;
|
|
638
|
-
}
|
|
639
|
-
|
|
646
|
+
if (doctorStatus !== "passed") {
|
|
647
|
+
console.log("");
|
|
648
|
+
console.log("⚠️ upgrade self-check did not pass; see doctor output above.");
|
|
649
|
+
console.log("📋 下一步:把上面 doctor 輸出貼給 AI,請它先按提示修補後再宣稱 upgrade 完成。");
|
|
650
|
+
process.exitCode = 1;
|
|
651
|
+
} else {
|
|
652
|
+
console.log("");
|
|
653
|
+
console.log("✅ 升級驗收完成:doctor 已通過;可以繼續使用這個項目。");
|
|
654
|
+
}
|
|
655
|
+
}
|
|
640
656
|
|
|
641
657
|
if (conflicts.length > 0) process.exitCode = 1;
|
|
642
658
|
}
|
|
@@ -747,9 +763,10 @@ async function runDoctor(root, version, options = {}) {
|
|
|
747
763
|
// suspect drift / curious about version / continuity awareness),唔等用戶 ask AI。
|
|
748
764
|
console.log("");
|
|
749
765
|
console.log("項目狀態速覽:");
|
|
750
|
-
const versionAlignment = await assessVersionAlignment(root, version);
|
|
751
|
-
printVersionAlignment(versionAlignment);
|
|
752
|
-
const
|
|
766
|
+
const versionAlignment = await assessVersionAlignment(root, version);
|
|
767
|
+
printVersionAlignment(versionAlignment);
|
|
768
|
+
const versionNextStep = getVersionAlignmentNextStep(versionAlignment);
|
|
769
|
+
const lastCloseout = await assessLastCloseout(root);
|
|
753
770
|
printLastCloseout(lastCloseout);
|
|
754
771
|
const projectAge = await assessProjectAge(root);
|
|
755
772
|
printProjectAge(projectAge);
|
|
@@ -760,11 +777,11 @@ async function runDoctor(root, version, options = {}) {
|
|
|
760
777
|
failedKind: !credentialResult.ok ? "credential leak" : null,
|
|
761
778
|
failedCount: !credentialResult.ok ? credentialResult.findings.length : 0,
|
|
762
779
|
nextStep: !credentialResult.ok
|
|
763
|
-
? "立即從相關檔案 redact credential value + rotate 已泄露 token;credential 應該由 AI 工具自身 secure storage 管理,永不寫入 dev/* 任何檔。"
|
|
764
|
-
: disciplineResult.ok
|
|
765
|
-
? "繼續日常使用即可。如有新版本發佈,啟動本工具時會自動顯示升級通知。"
|
|
766
|
-
: "繼續使用;下次 closeout 時 AI 應自動執行 SESSION_LOG N 規則推進(見上面 warn 行)。如未動請要求 AI 重做 closeout。"
|
|
767
|
-
});
|
|
780
|
+
? "立即從相關檔案 redact credential value + rotate 已泄露 token;credential 應該由 AI 工具自身 secure storage 管理,永不寫入 dev/* 任何檔。"
|
|
781
|
+
: disciplineResult.ok
|
|
782
|
+
? versionNextStep ?? "繼續日常使用即可。如有新版本發佈,啟動本工具時會自動顯示升級通知。"
|
|
783
|
+
: "繼續使用;下次 closeout 時 AI 應自動執行 SESSION_LOG N 規則推進(見上面 warn 行)。如未動請要求 AI 重做 closeout。"
|
|
784
|
+
});
|
|
768
785
|
return overallHealthy ? "passed" : "failed";
|
|
769
786
|
}
|
|
770
787
|
|
|
@@ -813,8 +830,8 @@ async function checkInstalledIntegrationsCredentialLeak(root) {
|
|
|
813
830
|
return { ok: findings.length === 0, findings };
|
|
814
831
|
}
|
|
815
832
|
|
|
816
|
-
// R-026 CLI Output Contract: doctor
|
|
817
|
-
function printDoctorSummary(version, root, mode, details) {
|
|
833
|
+
// R-026 CLI Output Contract: doctor 完成必含四項(版本/模式/剛完成/下一步)。
|
|
834
|
+
function printDoctorSummary(version, root, mode, details) {
|
|
818
835
|
console.log("");
|
|
819
836
|
if (mode === "healthy") {
|
|
820
837
|
console.log("status: passed");
|
|
@@ -823,12 +840,12 @@ function printDoctorSummary(version, root, mode, details) {
|
|
|
823
840
|
console.log(`status: failed (${details.failedCount} ${details.failedKind} failed)`);
|
|
824
841
|
console.log(`⚠️ 檢查未通過:${details.failedKind === "missing files" ? "有必要檔案不存在。" : details.failedKind === "anchor checks" ? "有檔案存在,但內容缺少必要段落。" : details.failedKind === "schema checks" ? "交接或索引文件結構不完整。" : "下次開工提示副本與 handoff 真源不同。"}`);
|
|
825
842
|
}
|
|
826
|
-
console.log("");
|
|
827
|
-
console.log(`📦 版本:v${version}`);
|
|
828
|
-
console.log(`🩺 模式:${mode}`);
|
|
829
|
-
console.log(`🔎
|
|
830
|
-
console.log(`🚀 下一步:${details.nextStep}`);
|
|
831
|
-
}
|
|
843
|
+
console.log("");
|
|
844
|
+
console.log(`📦 版本:v${version}`);
|
|
845
|
+
console.log(`🩺 模式:${mode}`);
|
|
846
|
+
console.log(`🔎 剛完成:檢查 ${details.checked} 項;${mode === "healthy" ? "全部通過" : `${details.failedCount} 項未通過(${details.failedKind})`}。`);
|
|
847
|
+
console.log(`🚀 下一步:${details.nextStep}`);
|
|
848
|
+
}
|
|
832
849
|
|
|
833
850
|
async function checkPromptMirror(root) {
|
|
834
851
|
const handoffPath = path.join(root, "dev/SESSION_HANDOFF.md");
|
|
@@ -865,13 +882,97 @@ function extractOpeningMessage(text) {
|
|
|
865
882
|
return text.slice(contentStart + 1, fenceEnd).trim();
|
|
866
883
|
}
|
|
867
884
|
|
|
868
|
-
function normalizePrompt(text) {
|
|
869
|
-
return text.replace(/\r\n/g, "\n").trim();
|
|
870
|
-
}
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
const
|
|
874
|
-
|
|
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) {
|
|
875
976
|
const filePath = path.join(root, rule.target);
|
|
876
977
|
let text = "";
|
|
877
978
|
try {
|
|
@@ -974,7 +1075,7 @@ async function buildPlan(root, command) {
|
|
|
974
1075
|
return plan;
|
|
975
1076
|
}
|
|
976
1077
|
|
|
977
|
-
function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAbs, sourceText, targetText) {
|
|
1078
|
+
function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAbs, sourceText, targetText) {
|
|
978
1079
|
const base = { sourceRel, targetRel, sourceAbs, targetAbs };
|
|
979
1080
|
if (targetText === sourceText) return { ...base, action: "skip", reason: "already current" };
|
|
980
1081
|
if (command !== "upgrade") return { ...base, action: "skip", reason: "init preserves existing files" };
|
|
@@ -1018,30 +1119,34 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
|
|
|
1018
1119
|
mergedText: mergeManagedBlock(targetText, sourceText)
|
|
1019
1120
|
};
|
|
1020
1121
|
}
|
|
1021
|
-
// R-029
|
|
1022
|
-
//
|
|
1023
|
-
//
|
|
1024
|
-
|
|
1025
|
-
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
|
-
|
|
1029
|
-
return {
|
|
1030
|
-
...base,
|
|
1031
|
-
action: "merge",
|
|
1032
|
-
reason: "
|
|
1033
|
-
mergedText:
|
|
1034
|
-
};
|
|
1035
|
-
}
|
|
1036
|
-
// R-030 v0.3.0+: dev/RULE_PACKS.md must also include integrations pack routing row.
|
|
1037
|
-
if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("
|
|
1038
|
-
|
|
1039
|
-
|
|
1040
|
-
action: "merge"
|
|
1041
|
-
|
|
1042
|
-
|
|
1043
|
-
|
|
1044
|
-
|
|
1122
|
+
// R-029/R-030: RULE_PACKS.md is a routing table, but upgrade still preserves
|
|
1123
|
+
// user-added rows. Missing maintainer rows are merged into the existing table
|
|
1124
|
+
// instead of replacing the whole file.
|
|
1125
|
+
if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("First-time user signals")) {
|
|
1126
|
+
const mergedRulePacks = mergeRulePacksRows(targetText, sourceText);
|
|
1127
|
+
if (!mergedRulePacks) {
|
|
1128
|
+
return { ...base, action: "conflict", reason: "RULE_PACKS.md routing table header was changed; manual merge required to preserve custom rows" };
|
|
1129
|
+
}
|
|
1130
|
+
return {
|
|
1131
|
+
...base,
|
|
1132
|
+
action: "merge",
|
|
1133
|
+
reason: "merge missing v0.2.0+ routing rows while preserving existing custom rows (新手引導 signal routing)",
|
|
1134
|
+
mergedText: mergedRulePacks
|
|
1135
|
+
};
|
|
1136
|
+
}
|
|
1137
|
+
// R-030 v0.3.0+: dev/RULE_PACKS.md must also include integrations pack routing row.
|
|
1138
|
+
if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("External tool integrations")) {
|
|
1139
|
+
const mergedRulePacks = mergeRulePacksRows(targetText, sourceText);
|
|
1140
|
+
if (!mergedRulePacks) {
|
|
1141
|
+
return { ...base, action: "conflict", reason: "RULE_PACKS.md routing table header was changed; manual merge required to preserve custom rows" };
|
|
1142
|
+
}
|
|
1143
|
+
return {
|
|
1144
|
+
...base,
|
|
1145
|
+
action: "merge",
|
|
1146
|
+
reason: "merge missing v0.3.0+ routing rows while preserving existing custom rows (Integration governance routing)",
|
|
1147
|
+
mergedText: mergedRulePacks
|
|
1148
|
+
};
|
|
1149
|
+
}
|
|
1045
1150
|
// R-030 v0.3.0+: dev/PROJECT_INDEX.md gets ## Installed Integrations section auto-inserted before
|
|
1046
1151
|
// ## Local QC Commands on upgrade if missing. NON-DESTRUCTIVE: existing ## External Sources content
|
|
1047
1152
|
// is fully preserved (including any user-filled rows). User can later manually add the `via` column
|
|
@@ -1064,25 +1169,96 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
|
|
|
1064
1169
|
// content and any user customization preserved. Step 1 micro-question additions to Scenarios A-E
|
|
1065
1170
|
// are NOT auto-migrated (user-customizable inline sample wording, not anchor-enforced); users get
|
|
1066
1171
|
// those on fresh install only or can manually patch following CHANGELOG migration guidance.
|
|
1067
|
-
if (targetRel === "dev/rules/onboarding.md" && command === "upgrade" && !targetText.includes("Scenario F. 審視已裝外部工具")) {
|
|
1068
|
-
const sourceScenarioFMatch = sourceText.match(/(### Scenario F\. 審視已裝外部工具[\s\S]*?)(?=## Cross-reference to guide\.html)/);
|
|
1069
|
-
if (sourceScenarioFMatch && targetText.includes("## Cross-reference to guide.html")) {
|
|
1070
|
-
const scenarioFBlock = sourceScenarioFMatch[1];
|
|
1071
|
-
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 {
|
|
1072
1177
|
...base,
|
|
1073
1178
|
action: "merge",
|
|
1074
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)",
|
|
1075
1180
|
mergedText: targetText.replace("## Cross-reference to guide.html", scenarioFBlock + "## Cross-reference to guide.html")
|
|
1076
|
-
};
|
|
1077
|
-
}
|
|
1078
|
-
}
|
|
1079
|
-
|
|
1080
|
-
|
|
1081
|
-
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
|
-
|
|
1085
|
-
|
|
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
|
+
}
|
|
1202
|
+
return { ...base, action: "skip", reason: "preserve existing file" };
|
|
1203
|
+
}
|
|
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
|
+
|
|
1225
|
+
function mergeRulePacksRows(targetText, sourceText) {
|
|
1226
|
+
const requiredPacks = [
|
|
1227
|
+
"dev/rules/onboarding.md",
|
|
1228
|
+
"dev/rules/integrations.md"
|
|
1229
|
+
];
|
|
1230
|
+
const sourceRows = sourceText
|
|
1231
|
+
.split(/\r?\n/)
|
|
1232
|
+
.filter((line) => line.startsWith("|") && requiredPacks.some((pack) => line.includes(pack)));
|
|
1233
|
+
if (sourceRows.length === 0) return targetText;
|
|
1234
|
+
|
|
1235
|
+
const lines = targetText.split(/\r?\n/);
|
|
1236
|
+
const tableStart = lines.findIndex((line) => line.trim() === "| Task signal | Pack | Purpose |");
|
|
1237
|
+
if (tableStart < 0) return null;
|
|
1238
|
+
|
|
1239
|
+
let tableEnd = tableStart;
|
|
1240
|
+
while (tableEnd < lines.length && lines[tableEnd].startsWith("|")) tableEnd++;
|
|
1241
|
+
|
|
1242
|
+
const before = lines.slice(0, tableStart);
|
|
1243
|
+
const table = lines.slice(tableStart, tableEnd);
|
|
1244
|
+
const after = lines.slice(tableEnd);
|
|
1245
|
+
const sourceRowsToApply = sourceRows.filter((row) => {
|
|
1246
|
+
if (row.includes("dev/rules/onboarding.md")) return !targetText.includes("First-time user signals");
|
|
1247
|
+
if (row.includes("dev/rules/integrations.md")) return !targetText.includes("External tool integrations");
|
|
1248
|
+
return false;
|
|
1249
|
+
});
|
|
1250
|
+
if (sourceRowsToApply.length === 0) return targetText;
|
|
1251
|
+
|
|
1252
|
+
const merged = [
|
|
1253
|
+
...before,
|
|
1254
|
+
...table,
|
|
1255
|
+
...sourceRowsToApply,
|
|
1256
|
+
...after
|
|
1257
|
+
];
|
|
1258
|
+
return merged.join("\n");
|
|
1259
|
+
}
|
|
1260
|
+
|
|
1261
|
+
// R-031.2 v0.3.2+: Version alignment assessment for doctor "項目狀態速覽".
|
|
1086
1262
|
// Compares CLI version (running), root template metadata version (in dev/PROJECT_INDEX.md),
|
|
1087
1263
|
// and npm latest. Surfaces drift awareness because previous design relied on startup
|
|
1088
1264
|
// maybePrintUpdateNotice which silently fails when npx auto-fetches latest (CLI version
|
|
@@ -1108,29 +1284,45 @@ async function assessVersionAlignment(root, cliVersion) {
|
|
|
1108
1284
|
return { cliVersion, rootVersion, npmLatest };
|
|
1109
1285
|
}
|
|
1110
1286
|
|
|
1111
|
-
function printVersionAlignment(result) {
|
|
1112
|
-
const { cliVersion, rootVersion, npmLatest } = result;
|
|
1113
|
-
if (rootVersion === null) {
|
|
1114
|
-
console.log(` 📦
|
|
1115
|
-
return;
|
|
1116
|
-
}
|
|
1117
|
-
if (npmLatest === null) {
|
|
1118
|
-
console.log(` 📦
|
|
1119
|
-
return;
|
|
1120
|
-
}
|
|
1121
|
-
const aligned = cliVersion === rootVersion && rootVersion === npmLatest;
|
|
1122
|
-
if (aligned) {
|
|
1123
|
-
console.log(` 📦
|
|
1124
|
-
return;
|
|
1125
|
-
}
|
|
1126
|
-
console.log(` 📦
|
|
1127
|
-
if (npmLatest && compareSemver(npmLatest, cliVersion) > 0) {
|
|
1128
|
-
console.log(` npm 有新版(v${npmLatest}
|
|
1129
|
-
|
|
1130
|
-
|
|
1131
|
-
|
|
1132
|
-
|
|
1133
|
-
|
|
1287
|
+
function printVersionAlignment(result) {
|
|
1288
|
+
const { cliVersion, rootVersion, npmLatest } = result;
|
|
1289
|
+
if (rootVersion === null) {
|
|
1290
|
+
console.log(` 📦 版本:工具 v${cliVersion} / 項目版本記錄缺失(可能曾經手動編輯)/ npm latest ${npmLatest ? "v" + npmLatest : "無法查詢"}`);
|
|
1291
|
+
return;
|
|
1292
|
+
}
|
|
1293
|
+
if (npmLatest === null) {
|
|
1294
|
+
console.log(` 📦 版本:工具 v${cliVersion} / 項目記錄 v${rootVersion} / npm latest 無法查詢(網絡可能不通)`);
|
|
1295
|
+
return;
|
|
1296
|
+
}
|
|
1297
|
+
const aligned = cliVersion === rootVersion && rootVersion === npmLatest;
|
|
1298
|
+
if (aligned) {
|
|
1299
|
+
console.log(` 📦 版本:工具 / 項目記錄 / npm latest 三向對齊 v${cliVersion} ✅`);
|
|
1300
|
+
return;
|
|
1301
|
+
}
|
|
1302
|
+
console.log(` 📦 版本:工具 v${cliVersion} / 項目記錄 v${rootVersion} / npm latest v${npmLatest}`);
|
|
1303
|
+
if (npmLatest && compareSemver(npmLatest, cliVersion) > 0) {
|
|
1304
|
+
console.log(` npm 有新版(v${npmLatest});doctor 只檢查不修改。要升級時先執行:npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run`);
|
|
1305
|
+
console.log(" --dry-run 只預覽、不寫入;確認計劃沒問題後,再去掉 --dry-run 正式升級。");
|
|
1306
|
+
} else if (cliVersion !== rootVersion) {
|
|
1307
|
+
console.log(" 項目內記錄的 Kit 版本與目前工具版本不同;doctor 只檢查不修改。要對齊時先執行:npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run");
|
|
1308
|
+
console.log(" --dry-run 只預覽、不寫入;確認計劃沒問題後,再去掉 --dry-run 正式升級。");
|
|
1309
|
+
}
|
|
1310
|
+
}
|
|
1311
|
+
|
|
1312
|
+
function getVersionAlignmentNextStep(result) {
|
|
1313
|
+
const { cliVersion, rootVersion, npmLatest } = result;
|
|
1314
|
+
if (npmLatest && compareSemver(npmLatest, cliVersion) > 0) {
|
|
1315
|
+
return `檢查已通過,但 npm 有新版 v${npmLatest}。doctor 沒有修改檔案;建議先執行 npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run。--dry-run 只預覽、不寫入;確認計劃沒問題後,再去掉 --dry-run 正式升級。`;
|
|
1316
|
+
}
|
|
1317
|
+
if (rootVersion === null) {
|
|
1318
|
+
return "檢查已通過,但項目版本記錄缺失。doctor 沒有修改檔案;建議先執行 npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run。--dry-run 只預覽、不寫入;確認只會補齊工具維護的版本記錄後,再去掉 --dry-run 正式升級。";
|
|
1319
|
+
}
|
|
1320
|
+
if (cliVersion !== rootVersion) {
|
|
1321
|
+
return "檢查已通過,但項目版本記錄未與目前工具對齊。doctor 沒有修改檔案;建議先執行 npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run。--dry-run 只預覽、不寫入;確認後再去掉 --dry-run 正式升級。";
|
|
1322
|
+
}
|
|
1323
|
+
return null;
|
|
1324
|
+
}
|
|
1325
|
+
|
|
1134
1326
|
// R-031.2 v0.3.2+: Last closeout assessment. Reads dev/SESSION_HANDOFF.md "Last Updated:"
|
|
1135
1327
|
// line (strict format, reliable). Falls back to dev/SESSION_LOG.md first H2 date if
|
|
1136
1328
|
// HANDOFF missing or unparseable.
|
|
@@ -1438,14 +1630,17 @@ async function detectMode(root) {
|
|
|
1438
1630
|
return "partial";
|
|
1439
1631
|
}
|
|
1440
1632
|
|
|
1441
|
-
function printPlan(command, root, mode, plan, version) {
|
|
1633
|
+
function printPlan(command, root, mode, plan, version, isDryRun = false) {
|
|
1442
1634
|
printCard(version, "continuity ready", "o.o");
|
|
1443
1635
|
console.log(`command: ${command}`);
|
|
1444
1636
|
console.log(`current directory: ${process.cwd()}`);
|
|
1445
1637
|
console.log(`selected root: ${root}`);
|
|
1446
1638
|
console.log(`mode: ${mode}`);
|
|
1447
1639
|
console.log("");
|
|
1448
|
-
|
|
1640
|
+
const planIntro = isDryRun
|
|
1641
|
+
? "📋 計劃預覽:以下未執行。create 新增缺少檔案;merge 在備份後合併;skip 保留既有檔案;conflict 代表工具停手等你確認。"
|
|
1642
|
+
: "📋 即將執行:以下是本次寫入計劃。create 新增缺少檔案;merge 會先備份再合併;skip 保留既有檔案;conflict 代表工具停手等你確認。";
|
|
1643
|
+
console.log(planIntro);
|
|
1449
1644
|
console.log("");
|
|
1450
1645
|
for (const action of ["create", "merge", "skip", "conflict"]) {
|
|
1451
1646
|
const items = plan.filter((item) => item.action === action);
|
|
@@ -1455,20 +1650,20 @@ function printPlan(command, root, mode, plan, version) {
|
|
|
1455
1650
|
console.log(`\nbackup: ${plan.filter((item) => item.action === "merge").length}`);
|
|
1456
1651
|
}
|
|
1457
1652
|
|
|
1458
|
-
// R-026 CLI Output Contract: install/upgrade
|
|
1459
|
-
function printInstallSummary(version, command, mode, root, counts) {
|
|
1653
|
+
// R-026 CLI Output Contract: install/upgrade 完成必含四項(版本/模式/剛完成/下一步)。
|
|
1654
|
+
function printInstallSummary(version, command, mode, root, counts) {
|
|
1460
1655
|
console.log(`\n✅ created: ${counts.created}`);
|
|
1461
1656
|
console.log(`🔀 merged: ${counts.merged}`);
|
|
1462
1657
|
console.log(`⏭️ skipped existing: ${counts.skipped}`);
|
|
1463
1658
|
console.log(`${counts.conflicts > 0 ? "⚠️ " : "✅ "}conflict: ${counts.conflicts}`);
|
|
1464
1659
|
if (counts.backupRel) console.log(`💾 backup: ${counts.backupRel}`);
|
|
1465
1660
|
if (counts.reportRel) console.log(`📄 migration report: ${counts.reportRel}`);
|
|
1466
|
-
console.log("");
|
|
1467
|
-
console.log(`📦 版本:v${version}`);
|
|
1468
|
-
console.log(`🛠️ 模式:${mode}`);
|
|
1469
|
-
console.log(`🔎
|
|
1661
|
+
console.log("");
|
|
1662
|
+
console.log(`📦 版本:v${version}`);
|
|
1663
|
+
console.log(`🛠️ 模式:${mode}`);
|
|
1664
|
+
console.log(`🔎 剛完成:${command} 命令;create ${counts.created} / merge ${counts.merged} / skip ${counts.skipped} / conflict ${counts.conflicts}。`);
|
|
1470
1665
|
if (counts.conflicts > 0) {
|
|
1471
|
-
console.log("🚀 下一步:把 migration report 或這段輸出貼給 AI
|
|
1666
|
+
console.log("🚀 下一步:把 migration report 或這段輸出貼給 AI,請它判斷衝突檔案怎樣處理;工具已停手,沒有覆寫 conflict 檔案。");
|
|
1472
1667
|
} else if (command === "upgrade") {
|
|
1473
1668
|
console.log("🚀 下一步:留意下方 upgrade self-check(自動跑 doctor);若全綠即升級完成。");
|
|
1474
1669
|
} else {
|
|
@@ -1657,17 +1852,16 @@ function printInstallNextSteps(root, conflictCount) {
|
|
|
1657
1852
|
console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
|
|
1658
1853
|
console.log("");
|
|
1659
1854
|
}
|
|
1660
|
-
// R-031.2 v0.3.2+:
|
|
1661
|
-
//
|
|
1662
|
-
|
|
1663
|
-
console.log("
|
|
1664
|
-
console.log("");
|
|
1665
|
-
console.log("
|
|
1666
|
-
console.log("
|
|
1667
|
-
console.log("
|
|
1668
|
-
console.log("");
|
|
1669
|
-
console.log("
|
|
1670
|
-
console.log(" 冇 GUI、唔 run server、唔自動做嘢。你需要連住至少一個 AI tool 嘅對話,AI 先會讀依啲檔案做正事。");
|
|
1855
|
+
// R-031.2 v0.3.2+: first-install checklist. It answers the user's first
|
|
1856
|
+
// question: "is this installed and what do I do next?"
|
|
1857
|
+
console.log("📋 如何確認安裝完成:");
|
|
1858
|
+
console.log("");
|
|
1859
|
+
console.log(" 1. 在 Terminal 執行 npx @adamchanadam/agent-handoff-kit doctor,應該見到「status: passed」");
|
|
1860
|
+
console.log(" 2. 你的 dev/ 資料夾應該有規則、交接與工作紀錄等檔案");
|
|
1861
|
+
console.log(" 3. 在你使用的 AI 工具(Claude Code / Codex / Gemini)開新對話,貼下面起步句");
|
|
1862
|
+
console.log("");
|
|
1863
|
+
console.log("⚠️ 注意:Agent Handoff Kit 是放在項目資料夾內的一組交接檔案。");
|
|
1864
|
+
console.log(" 它沒有圖形介面,不會啟動伺服器,也不會自動替你做事;你需要在 AI 對話中使用它。");
|
|
1671
1865
|
console.log("");
|
|
1672
1866
|
console.log("------------------------------------------------------------");
|
|
1673
1867
|
console.log("⚠️ 請注意:下面文字不是 Terminal 指令。");
|
|
@@ -1679,7 +1873,7 @@ function printInstallNextSteps(root, conflictCount) {
|
|
|
1679
1873
|
console.log("🚀 AI 會主動引導你選擇情景(寫代碼 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),");
|
|
1680
1874
|
console.log(" 一步一步帶你做第一個任務(由新手引導包主動接管)。");
|
|
1681
1875
|
console.log("");
|
|
1682
|
-
console.log("💡
|
|
1876
|
+
console.log("💡 之後你熟悉流程後,可改用更直接的開工句:");
|
|
1683
1877
|
console.log(` Work in ${root}. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.`);
|
|
1684
1878
|
console.log("");
|
|
1685
1879
|
console.log("🩺 如要檢查安裝是否完整,可在 Terminal 執行:");
|
|
@@ -1693,7 +1887,7 @@ function printInstallNextSteps(root, conflictCount) {
|
|
|
1693
1887
|
async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRootVersion) {
|
|
1694
1888
|
console.log("");
|
|
1695
1889
|
console.log("============================================================");
|
|
1696
|
-
console.log("✅
|
|
1890
|
+
console.log("✅ 升級完成:Kit 檔案已更新到最新版本");
|
|
1697
1891
|
console.log("============================================================");
|
|
1698
1892
|
if (conflictCount > 0) {
|
|
1699
1893
|
console.log("⚠️ 狀態:有既有檔案需要人工確認,詳情見 migration report。");
|
|
@@ -1707,7 +1901,7 @@ async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRoo
|
|
|
1707
1901
|
// inject mutated PROJECT_INDEX), so the range narrative reflects actual user
|
|
1708
1902
|
// journey instead of degenerate v{current} → v{current}.
|
|
1709
1903
|
await printWhatsnew(root, version, preUpgradeRootVersion);
|
|
1710
|
-
console.log("📋
|
|
1904
|
+
console.log("📋 如你正在進行中的工作對話已熟悉 Agent Handoff Kit,繼續使用原本的開工方式即可,無需重新做新手引導。");
|
|
1711
1905
|
console.log("");
|
|
1712
1906
|
console.log("💡 如想了解本版本新加了甚麼功能,可選用以下開工句(非強制):");
|
|
1713
1907
|
console.log("------------------------------------------------------------");
|
|
@@ -1760,7 +1954,7 @@ async function printWhatsnew(root, toVersion, fromVersionOverride) {
|
|
|
1760
1954
|
|
|
1761
1955
|
if (relevant.length === 0) {
|
|
1762
1956
|
console.log(`💡 本版 release notes:https://github.com/Adamchanadam/agent-handoff-kit/releases`);
|
|
1763
|
-
console.log(` (v${fromVersion} → v${toVersion}
|
|
1957
|
+
console.log(` (v${fromVersion} → v${toVersion} 跨版本的完整變更見 GitHub Release 全列表)`);
|
|
1764
1958
|
console.log("");
|
|
1765
1959
|
return;
|
|
1766
1960
|
}
|
|
@@ -1776,12 +1970,12 @@ async function printWhatsnew(root, toVersion, fromVersionOverride) {
|
|
|
1776
1970
|
const [oldMajor, oldMinor] = oldestAvailable.split(".").map((n) => Number.parseInt(n, 10));
|
|
1777
1971
|
const isDeepRange = (fromMajor < oldMajor) || (fromMajor === oldMajor && fromMinor < oldMinor);
|
|
1778
1972
|
if (isDeepRange) {
|
|
1779
|
-
console.log(`💡 注意:本次升級 v${fromVersion} → v${toVersion}
|
|
1973
|
+
console.log(`💡 注意:本次升級 v${fromVersion} → v${toVersion} 跨度較大;本工具的版本說明只涵蓋由 v${oldestAvailable} 起的 ${relevant.length} 個版本。較舊版本(v${fromVersion} 至 v${oldestAvailable} 之前)的完整變更見:`);
|
|
1780
1974
|
console.log(` https://github.com/Adamchanadam/agent-handoff-kit/releases`);
|
|
1781
1975
|
console.log("");
|
|
1782
1976
|
}
|
|
1783
1977
|
|
|
1784
|
-
console.log(`📰 本次升級涵蓋 ${relevant.length}
|
|
1978
|
+
console.log(`📰 本次升級涵蓋 ${relevant.length} 個版本的版本說明(${isDeepRange ? `由 v${oldestAvailable} 起` : `v${fromVersion} → v${toVersion}`}):`);
|
|
1785
1979
|
console.log("");
|
|
1786
1980
|
|
|
1787
1981
|
const toShow = relevant.length <= 3 ? relevant : [relevant[0], relevant[relevant.length - 1]];
|
|
@@ -1795,7 +1989,7 @@ async function printWhatsnew(root, toVersion, fromVersionOverride) {
|
|
|
1795
1989
|
console.log(content.trimEnd());
|
|
1796
1990
|
console.log("");
|
|
1797
1991
|
if (i === 0 && elidedCount > 0) {
|
|
1798
|
-
console.log(` ⋯ 中間 ${elidedCount}
|
|
1992
|
+
console.log(` ⋯ 中間 ${elidedCount} 個版本的版本說明略;完整列表見 https://github.com/Adamchanadam/agent-handoff-kit/releases ⋯`);
|
|
1799
1993
|
console.log("");
|
|
1800
1994
|
}
|
|
1801
1995
|
} catch {
|
|
@@ -1816,7 +2010,7 @@ function printUpgradeNoopShortCircuit(version) {
|
|
|
1816
2010
|
console.log("");
|
|
1817
2011
|
console.log(`📦 版本:v${version}`);
|
|
1818
2012
|
console.log("🛠️ 模式:upgrade-existing");
|
|
1819
|
-
console.log("🔎
|
|
2013
|
+
console.log("🔎 剛完成:檢查所有 Kit 檔案的狀態(含 AGENTS.md、dev/SESSION_HANDOFF.md、dev/PROJECT_INDEX.md 等)。");
|
|
1820
2014
|
console.log("✅ 結果:你已經是最新版本,沒有檔案需要建立或合併;用戶填寫的內容全部保留現狀。");
|
|
1821
2015
|
console.log("");
|
|
1822
2016
|
console.log("🚀 下一步:繼續日常使用即可。如要檢查健康狀態,可執行:");
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# v0.3.5
|
|
2
|
+
|
|
3
|
+
## 本版新加了甚麼
|
|
4
|
+
|
|
5
|
+
- `upgrade` 補齊 `dev/RULE_PACKS.md` 時會保留用戶自訂 rows,不再用整份模板覆寫。
|
|
6
|
+
- 如 `dev/RULE_PACKS.md` 的 routing table 表頭已被改動,工具會回報衝突並停手,不會猜測合併。
|
|
7
|
+
- `doctor` 明確說明自己只檢查、不修改;版本不齊時會先建議 `upgrade --dry-run`。
|
|
8
|
+
- `init` / `upgrade` / `doctor` 的提示文字更清楚,方便非技術新手分清 Terminal 檢查與 AI 對話下一步。
|
|
9
|
+
|
|
10
|
+
## 對你已有檔案的影響
|
|
11
|
+
|
|
12
|
+
- 既有用戶內容應保留。
|
|
13
|
+
- `dev/RULE_PACKS.md` 只會補 Kit 需要的 routing rows;你自己新增的任務路由 rows 應保留。
|
|
14
|
+
- 如果你手動改過 routing table 表頭,升級可能會停在衝突狀態,等你或 AI 判斷怎樣合併。
|
|
15
|
+
|
|
16
|
+
## 建議下一步
|
|
17
|
+
|
|
18
|
+
- 已安裝舊版的專案,先執行 `npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run`。
|
|
19
|
+
- 預演結果沒有衝突後,再執行 `npx @adamchanadam/agent-handoff-kit@latest upgrade`。
|
|
20
|
+
- 升級後執行 `npx @adamchanadam/agent-handoff-kit@latest doctor`,確認狀態通過。
|
|
@@ -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
|