@adamchanadam/agent-handoff-kit 0.3.13 → 0.3.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -2
- package/bin/agent-handoff-kit.mjs +110 -58
- package/bin/prompt-mirror-core.mjs +110 -0
- package/docs/whatsnew/v0.3.14.md +29 -0
- package/docs/whatsnew/v0.3.15.md +27 -0
- package/package.json +6 -5
- package/packs/safety.md +11 -5
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
狀態:目前版本為 `v0.3.
|
|
3
|
+
狀態:目前版本為 `v0.3.15`。這是早期可用版本,仍在持續完善中。
|
|
4
4
|
|
|
5
5
|

|
|
6
6
|
|
|
@@ -261,7 +261,7 @@ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templa
|
|
|
261
261
|
|
|
262
262
|
## 目前限制
|
|
263
263
|
|
|
264
|
-
- 目前版本為 `v0.3.
|
|
264
|
+
- 目前版本為 `v0.3.15`。
|
|
265
265
|
- 這是早期可用版本,仍在持續完善中。
|
|
266
266
|
- 升級合併屬窄範圍策略,不是完整的複雜合併工具。
|
|
267
267
|
- `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
|
|
@@ -2,9 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
import { createInterface } from "node:readline/promises";
|
|
4
4
|
import { stdin as input, stdout as output } from "node:process";
|
|
5
|
-
import { copyFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
|
|
6
|
-
import path from "node:path";
|
|
7
|
-
import { fileURLToPath } from "node:url";
|
|
5
|
+
import { copyFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
|
|
6
|
+
import path from "node:path";
|
|
7
|
+
import { fileURLToPath } from "node:url";
|
|
8
|
+
import { assessPromptMirrorTexts } from "./prompt-mirror-core.mjs";
|
|
8
9
|
|
|
9
10
|
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
10
11
|
const packageRoot = path.resolve(__dirname, "..");
|
|
@@ -456,9 +457,9 @@ async function needsProjectIndexVersionInject(root, command, version) {
|
|
|
456
457
|
return false;
|
|
457
458
|
}
|
|
458
459
|
|
|
459
|
-
async function runInstall(command, root, options, version) {
|
|
460
|
-
const mode = await detectMode(root);
|
|
461
|
-
const plan = await buildPlan(root, command);
|
|
460
|
+
async function runInstall(command, root, options, version) {
|
|
461
|
+
const mode = await detectMode(root);
|
|
462
|
+
const plan = await buildPlan(root, command, version);
|
|
462
463
|
|
|
463
464
|
// R-031 v0.3.1+: plan-time upgrade no-op detection. When upgrade has zero
|
|
464
465
|
// create/merge/conflict actions (skip-only), skip the full plan listing +
|
|
@@ -918,7 +919,7 @@ async function hydrateInitialOpeningPrompt(root, created) {
|
|
|
918
919
|
}
|
|
919
920
|
}
|
|
920
921
|
|
|
921
|
-
async function checkPromptMirror(root) {
|
|
922
|
+
async function checkPromptMirror(root) {
|
|
922
923
|
const handoffPath = path.join(root, "dev/SESSION_HANDOFF.md");
|
|
923
924
|
const promptPath = path.join(root, "START_NEXT_SESSION_PROMPT.txt");
|
|
924
925
|
let handoffText = "";
|
|
@@ -933,29 +934,14 @@ async function checkPromptMirror(root) {
|
|
|
933
934
|
} catch {
|
|
934
935
|
return [{ target: "START_NEXT_SESSION_PROMPT.txt", label: "matches handoff opening message", ok: false, reason: "prompt copy unreadable" }];
|
|
935
936
|
}
|
|
936
|
-
const
|
|
937
|
-
|
|
938
|
-
|
|
939
|
-
|
|
940
|
-
|
|
941
|
-
|
|
942
|
-
}
|
|
943
|
-
|
|
944
|
-
function extractOpeningMessage(text) {
|
|
945
|
-
const marker = "📋 Next session: copy and paste the whole block below";
|
|
946
|
-
const markerIndex = text.indexOf(marker);
|
|
947
|
-
if (markerIndex < 0) return null;
|
|
948
|
-
const fenceStart = text.indexOf("```text", markerIndex);
|
|
949
|
-
if (fenceStart < 0) return null;
|
|
950
|
-
const contentStart = text.indexOf("\n", fenceStart);
|
|
951
|
-
const fenceEnd = text.indexOf("```", contentStart + 1);
|
|
952
|
-
if (contentStart < 0 || fenceEnd < 0) return null;
|
|
953
|
-
return text.slice(contentStart + 1, fenceEnd).trim();
|
|
954
|
-
}
|
|
955
|
-
|
|
956
|
-
function normalizePrompt(text) {
|
|
957
|
-
return text.replace(/\r\n/g, "\n").trim();
|
|
958
|
-
}
|
|
937
|
+
const mirror = assessPromptMirrorTexts(handoffText, promptText);
|
|
938
|
+
return [{
|
|
939
|
+
target: "START_NEXT_SESSION_PROMPT.txt",
|
|
940
|
+
label: "matches handoff opening message",
|
|
941
|
+
ok: mirror.ok,
|
|
942
|
+
reason: mirror.ok ? "" : mirror.reason
|
|
943
|
+
}];
|
|
944
|
+
}
|
|
959
945
|
|
|
960
946
|
function assessHandoffLifecycleConsistency(text) {
|
|
961
947
|
const fieldValue = fieldValueAfterMarker(text, "lifecycle-conflicts-resolved");
|
|
@@ -1119,17 +1105,21 @@ function tableHeader(...cells) {
|
|
|
1119
1105
|
};
|
|
1120
1106
|
}
|
|
1121
1107
|
|
|
1122
|
-
async function buildPlan(root, command) {
|
|
1123
|
-
const plan = [];
|
|
1124
|
-
|
|
1125
|
-
|
|
1126
|
-
|
|
1127
|
-
|
|
1128
|
-
|
|
1129
|
-
|
|
1130
|
-
|
|
1131
|
-
|
|
1132
|
-
|
|
1108
|
+
async function buildPlan(root, command, version = null) {
|
|
1109
|
+
const plan = [];
|
|
1110
|
+
const context = {
|
|
1111
|
+
currentVersion: version,
|
|
1112
|
+
rootTemplateVersion: command === "upgrade" ? await readRootTemplateVersion(root) : null
|
|
1113
|
+
};
|
|
1114
|
+
for (const [sourceRel, targetRel] of mappings) {
|
|
1115
|
+
const sourceAbs = path.join(packageRoot, sourceRel);
|
|
1116
|
+
const targetAbs = path.join(root, targetRel);
|
|
1117
|
+
const sourceText = await readFile(sourceAbs, "utf8");
|
|
1118
|
+
if (await exists(targetAbs)) {
|
|
1119
|
+
const targetText = await readFile(targetAbs, "utf8");
|
|
1120
|
+
plan.push(classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAbs, sourceText, targetText, context));
|
|
1121
|
+
continue;
|
|
1122
|
+
}
|
|
1133
1123
|
plan.push({
|
|
1134
1124
|
sourceRel,
|
|
1135
1125
|
targetRel,
|
|
@@ -1137,12 +1127,23 @@ async function buildPlan(root, command) {
|
|
|
1137
1127
|
targetAbs,
|
|
1138
1128
|
action: "create"
|
|
1139
1129
|
});
|
|
1140
|
-
}
|
|
1141
|
-
return plan;
|
|
1142
|
-
}
|
|
1143
|
-
|
|
1144
|
-
function
|
|
1145
|
-
|
|
1130
|
+
}
|
|
1131
|
+
return plan;
|
|
1132
|
+
}
|
|
1133
|
+
|
|
1134
|
+
async function readRootTemplateVersion(root) {
|
|
1135
|
+
try {
|
|
1136
|
+
const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
|
|
1137
|
+
const text = await readFile(indexPath, "utf8");
|
|
1138
|
+
const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
|
|
1139
|
+
return m?.[1] ?? null;
|
|
1140
|
+
} catch {
|
|
1141
|
+
return null;
|
|
1142
|
+
}
|
|
1143
|
+
}
|
|
1144
|
+
|
|
1145
|
+
function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAbs, sourceText, targetText, context = {}) {
|
|
1146
|
+
const base = { sourceRel, targetRel, sourceAbs, targetAbs };
|
|
1146
1147
|
if (targetText === sourceText) return { ...base, action: "skip", reason: "already current" };
|
|
1147
1148
|
if (command !== "upgrade") return { ...base, action: "skip", reason: "init preserves existing files" };
|
|
1148
1149
|
if (targetRel === "AGENTS.md") {
|
|
@@ -1270,10 +1271,25 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
|
|
|
1270
1271
|
...base,
|
|
1271
1272
|
action: "merge",
|
|
1272
1273
|
reason: "insert lifecycle consistency field into State Reconciliation Check (completed work must not carry forward as unresolved next work)",
|
|
1273
|
-
mergedText: mergedHandoff
|
|
1274
|
-
};
|
|
1275
|
-
}
|
|
1276
|
-
if (targetRel === "
|
|
1274
|
+
mergedText: mergedHandoff
|
|
1275
|
+
};
|
|
1276
|
+
}
|
|
1277
|
+
if (targetRel === "dev/SESSION_HANDOFF.md" && command === "upgrade" && isUpgradeFromOlderTemplate(context)) {
|
|
1278
|
+
const lifecycleValue = fieldValueAfterMarker(targetText, "lifecycle-conflicts-resolved");
|
|
1279
|
+
if (isPlaceholderLifecycleFieldValue(lifecycleValue) && hasSubstantiveHandoffState(targetText)) {
|
|
1280
|
+
const mergedHandoff = reclassifyExistingHandoffLifecyclePlaceholder(targetText);
|
|
1281
|
+
if (!mergedHandoff) {
|
|
1282
|
+
return { ...base, action: "conflict", reason: "SESSION_HANDOFF.md lifecycle field exists but could not be safely reclassified; manual closeout required" };
|
|
1283
|
+
}
|
|
1284
|
+
return {
|
|
1285
|
+
...base,
|
|
1286
|
+
action: "merge",
|
|
1287
|
+
reason: "reclassify stale lifecycle placeholder from earlier template version so upgrade self-check can validate pre-existing handoff content",
|
|
1288
|
+
mergedText: mergedHandoff
|
|
1289
|
+
};
|
|
1290
|
+
}
|
|
1291
|
+
}
|
|
1292
|
+
if (targetRel === "CLAUDE.md" || targetRel === "GEMINI.md") {
|
|
1277
1293
|
if (!targetText.includes("AGENTS.md")) {
|
|
1278
1294
|
return { ...base, action: "conflict", reason: "existing bridge does not route to AGENTS.md" };
|
|
1279
1295
|
}
|
|
@@ -1286,8 +1302,15 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
|
|
|
1286
1302
|
};
|
|
1287
1303
|
}
|
|
1288
1304
|
}
|
|
1289
|
-
return { ...base, action: "skip", reason: "preserve existing file" };
|
|
1290
|
-
}
|
|
1305
|
+
return { ...base, action: "skip", reason: "preserve existing file" };
|
|
1306
|
+
}
|
|
1307
|
+
|
|
1308
|
+
function isUpgradeFromOlderTemplate(context) {
|
|
1309
|
+
const { rootTemplateVersion, currentVersion } = context;
|
|
1310
|
+
return isStableSemver(rootTemplateVersion)
|
|
1311
|
+
&& isStableSemver(currentVersion)
|
|
1312
|
+
&& compareSemver(rootTemplateVersion, currentVersion) < 0;
|
|
1313
|
+
}
|
|
1291
1314
|
|
|
1292
1315
|
function looksLikeExpandedKitBridge(targetRel, text) {
|
|
1293
1316
|
if (text.includes("This file is a bridge only")) return false;
|
|
@@ -1318,11 +1341,11 @@ function mergeOnboardingScenarioALabel(targetText) {
|
|
|
1318
1341
|
return merged;
|
|
1319
1342
|
}
|
|
1320
1343
|
|
|
1321
|
-
function mergeHandoffLifecycleField(targetText) {
|
|
1344
|
+
function mergeHandoffLifecycleField(targetText) {
|
|
1322
1345
|
const openingMarker = "<!-- ack:field:opening-message-matches-current-state -->";
|
|
1323
1346
|
if (!targetText.includes(openingMarker)) return null;
|
|
1324
1347
|
|
|
1325
|
-
const fieldBlock = "<!-- ack:field:lifecycle-conflicts-resolved -->\n- Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified:
|
|
1348
|
+
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";
|
|
1326
1349
|
let merged = targetText.replace(openingMarker, `${fieldBlock}${openingMarker}`);
|
|
1327
1350
|
|
|
1328
1351
|
if (!merged.includes("Lifecycle consistency rule: compare `Completed This Session`")) {
|
|
@@ -1334,9 +1357,38 @@ function mergeHandoffLifecycleField(targetText) {
|
|
|
1334
1357
|
merged = `${merged.trimEnd()}\n\n${ruleBlock}`;
|
|
1335
1358
|
}
|
|
1336
1359
|
}
|
|
1337
|
-
|
|
1338
|
-
return merged;
|
|
1339
|
-
}
|
|
1360
|
+
|
|
1361
|
+
return merged;
|
|
1362
|
+
}
|
|
1363
|
+
|
|
1364
|
+
function reclassifyExistingHandoffLifecyclePlaceholder(targetText) {
|
|
1365
|
+
const marker = "ack:field:lifecycle-conflicts-resolved";
|
|
1366
|
+
const lines = targetText.split(/\r?\n/);
|
|
1367
|
+
const markerIndex = lines.findIndex((line) => line.includes(marker));
|
|
1368
|
+
if (markerIndex < 0) return null;
|
|
1369
|
+
|
|
1370
|
+
const nextMarkerIndex = lines.findIndex((line, index) => index > markerIndex && line.includes("<!-- ack:"));
|
|
1371
|
+
const searchEnd = nextMarkerIndex < 0 ? lines.length : nextMarkerIndex;
|
|
1372
|
+
const fieldIndex = lines.findIndex((line, index) => index > markerIndex && index < searchEnd && line.trim().startsWith("- "));
|
|
1373
|
+
if (fieldIndex < 0) return null;
|
|
1374
|
+
|
|
1375
|
+
const colonIndex = lines[fieldIndex].indexOf(":");
|
|
1376
|
+
if (colonIndex < 0) return null;
|
|
1377
|
+
lines[fieldIndex] = `${lines[fieldIndex].slice(0, colonIndex + 1)} Reclassified at upgrade: existing lifecycle placeholder predates this version; pre-existing handoff state predates this check; reconcile at next closeout.`;
|
|
1378
|
+
|
|
1379
|
+
let merged = lines.join("\n");
|
|
1380
|
+
if (!merged.includes("Lifecycle consistency rule: compare `Completed This Session`")) {
|
|
1381
|
+
const ruleBlock = "Lifecycle consistency rule: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. A completed or verified item must not remain as an unresolved next priority, active risk, or startup instruction unless it is explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with the missing evidence or trigger condition stated.\n\n";
|
|
1382
|
+
const sufficiencyMarker = "<!-- ack:section:handoff-sufficiency-check -->";
|
|
1383
|
+
if (merged.includes(sufficiencyMarker)) {
|
|
1384
|
+
merged = merged.replace(sufficiencyMarker, `${ruleBlock}${sufficiencyMarker}`);
|
|
1385
|
+
} else {
|
|
1386
|
+
merged = `${merged.trimEnd()}\n\n${ruleBlock}`;
|
|
1387
|
+
}
|
|
1388
|
+
}
|
|
1389
|
+
|
|
1390
|
+
return merged;
|
|
1391
|
+
}
|
|
1340
1392
|
|
|
1341
1393
|
function mergeRulePacksRows(targetText, sourceText) {
|
|
1342
1394
|
const requiredPacks = [
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import { readFileSync } from "node:fs";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
|
|
4
|
+
const openingSectionMarker = "<!-- ack:section:next-session-opening-message -->";
|
|
5
|
+
const openingHeadingPattern = /^##\s+Next Session Opening Message\s*$/m;
|
|
6
|
+
const copyMarker = "📋 Next session: copy and paste the whole block below";
|
|
7
|
+
|
|
8
|
+
export function assessPromptMirrorRoot(root) {
|
|
9
|
+
const handoffPath = path.join(root, "dev", "SESSION_HANDOFF.md");
|
|
10
|
+
const promptPath = path.join(root, "START_NEXT_SESSION_PROMPT.txt");
|
|
11
|
+
let handoffText = "";
|
|
12
|
+
let promptText = "";
|
|
13
|
+
|
|
14
|
+
try {
|
|
15
|
+
handoffText = readFileSync(handoffPath, "utf8");
|
|
16
|
+
} catch {
|
|
17
|
+
return { status: "missing", ok: false, reason: "handoff unreadable" };
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
try {
|
|
21
|
+
promptText = readFileSync(promptPath, "utf8");
|
|
22
|
+
} catch {
|
|
23
|
+
return { status: "missing", ok: false, reason: "prompt copy unreadable" };
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
return assessPromptMirrorTexts(handoffText, promptText);
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
export function assessPromptMirrorTexts(handoffText, promptText) {
|
|
30
|
+
const openingMessage = extractOpeningMessage(handoffText);
|
|
31
|
+
if (openingMessage == null) {
|
|
32
|
+
return {
|
|
33
|
+
status: "missing",
|
|
34
|
+
ok: false,
|
|
35
|
+
reason: "handoff opening message missing"
|
|
36
|
+
};
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
if (openingMessage === promptText) {
|
|
40
|
+
return {
|
|
41
|
+
status: "match",
|
|
42
|
+
ok: true,
|
|
43
|
+
reason: "",
|
|
44
|
+
openingMessage,
|
|
45
|
+
firstDiff: null
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
const normalizedOpening = normalizePrompt(openingMessage);
|
|
50
|
+
const normalizedPrompt = normalizePrompt(promptText);
|
|
51
|
+
if (normalizedOpening === normalizedPrompt) {
|
|
52
|
+
return {
|
|
53
|
+
status: "newline-only",
|
|
54
|
+
ok: true,
|
|
55
|
+
reason: "only newline style or final newline differs",
|
|
56
|
+
openingMessage,
|
|
57
|
+
firstDiff: null
|
|
58
|
+
};
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
return {
|
|
62
|
+
status: "mismatch",
|
|
63
|
+
ok: false,
|
|
64
|
+
reason: "convenience copy differs from dev/SESSION_HANDOFF.md",
|
|
65
|
+
openingMessage,
|
|
66
|
+
firstDiff: firstDiff(normalizedOpening, normalizedPrompt)
|
|
67
|
+
};
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
export function extractOpeningMessage(text) {
|
|
71
|
+
const sectionStart = findOpeningSectionStart(text);
|
|
72
|
+
if (sectionStart < 0) return null;
|
|
73
|
+
|
|
74
|
+
const sectionText = text.slice(sectionStart);
|
|
75
|
+
const markerIndex = sectionText.indexOf(copyMarker);
|
|
76
|
+
if (markerIndex < 0) return null;
|
|
77
|
+
|
|
78
|
+
const afterMarker = sectionText.slice(markerIndex + copyMarker.length);
|
|
79
|
+
const fenceMatch = /```text[^\r\n]*(?:\r\n?|\n)([\s\S]*?)(?:\r\n?|\n)```/.exec(afterMarker);
|
|
80
|
+
if (!fenceMatch) return null;
|
|
81
|
+
return fenceMatch[1];
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export function normalizePrompt(text) {
|
|
85
|
+
return text.replace(/\r\n?/g, "\n").replace(/\n+$/g, "");
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
function findOpeningSectionStart(text) {
|
|
89
|
+
const markerIndex = text.indexOf(openingSectionMarker);
|
|
90
|
+
if (markerIndex >= 0) return markerIndex;
|
|
91
|
+
|
|
92
|
+
const headingMatch = openingHeadingPattern.exec(text);
|
|
93
|
+
return headingMatch ? headingMatch.index : -1;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
function firstDiff(left, right) {
|
|
97
|
+
const leftLines = left.split("\n");
|
|
98
|
+
const rightLines = right.split("\n");
|
|
99
|
+
const count = Math.max(leftLines.length, rightLines.length);
|
|
100
|
+
for (let index = 0; index < count; index += 1) {
|
|
101
|
+
if ((leftLines[index] ?? "") !== (rightLines[index] ?? "")) {
|
|
102
|
+
return {
|
|
103
|
+
line: index + 1,
|
|
104
|
+
handoff: leftLines[index] ?? "",
|
|
105
|
+
prompt: rightLines[index] ?? ""
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
return null;
|
|
110
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# v0.3.14
|
|
2
|
+
|
|
3
|
+
## 本版新加了甚麼
|
|
4
|
+
|
|
5
|
+
本版修正舊版項目跨版本升級時的交接狀態誤判。部分由很早期版本升級的項目,`upgrade` 會補入新的 lifecycle 欄位;舊工具曾把欄位填成 `TBD`,然後同一次升級後自動 `doctor` 又把這個 `TBD` 判定為失敗。
|
|
6
|
+
|
|
7
|
+
現在升級工具會把這類欄位明確標記為「由升級重新分類,下一次 closeout 再核對」,避免工具自己寫入一個會被自己拒絕的值。
|
|
8
|
+
|
|
9
|
+
同時,本版把 rules / packs 路由與可重用程序入庫範圍加入發佈前全面檢,確認自然語言任務能導向相應 pack,而不是隨意新建治理文件或只寫在 handoff / log。
|
|
10
|
+
|
|
11
|
+
另外,本版把 `START_NEXT_SESSION_PROMPT.txt` 與 handoff opening message 的比對方法收斂到固定檢查器。檢查器會先錨定真正的下一次開工訊息,再正規化 CRLF / LF 換行符,避免只因換行風格不同就誤報內容不一致。
|
|
12
|
+
|
|
13
|
+
## 對你已有檔案的影響
|
|
14
|
+
|
|
15
|
+
既有項目不用重裝。若你是由舊版 Kit 升級,工具可能會在 `dev/SESSION_HANDOFF.md` 補入 lifecycle consistency 欄位;這是為了讓下一次 closeout 能核對「已完成的事是否仍被帶成未解待辦」。
|
|
16
|
+
|
|
17
|
+
工具仍會保留既有交接內容,不會用新版模板覆寫你的工作紀錄。若 `doctor` 指出其他真實缺失,仍應把完整輸出交給 AI 非破壞性修補。
|
|
18
|
+
|
|
19
|
+
若只出現 prompt convenience copy 的換行符差異,這不是內容損壞;正常 `doctor` 不會因此阻擋你繼續工作。
|
|
20
|
+
|
|
21
|
+
## 建議下一步
|
|
22
|
+
|
|
23
|
+
已安裝舊版的項目可先預演:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
如果預演沒有 conflict,再執行正式升級。升級後若自動 `doctor` 通過,即可繼續使用;若仍有缺失,請把完整檢查輸出交給 AI 修補,不要用重裝覆寫既有內容。
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# v0.3.15
|
|
2
|
+
|
|
3
|
+
## 本版新加了甚麼
|
|
4
|
+
|
|
5
|
+
本版修正一個真實舊項目升級後仍會被自動檢查擋住的情況。
|
|
6
|
+
|
|
7
|
+
如果項目已經有新版 lifecycle 欄位,但欄位值仍是舊模板留下的 TBD,而 `Completed This Session` 或 `Validation / QC` 已經有實際內容,舊版升級流程可能只更新版本 metadata,沒有修正這個舊 placeholder。結果是工具先顯示升級完成,隨後同一次自動 `doctor` 又判定 handoff lifecycle consistency 缺失。
|
|
8
|
+
|
|
9
|
+
現在 upgrade 會在確認項目記錄版本落後於目前 CLI 時,安全地把這類舊 placeholder 重新分類為 upgrade migration 狀態,並保留原有交接內容。這令升級後自動檢查能通過,同時仍要求下一次 closeout 正常核對已完成工作、下一步和風險是否一致。
|
|
10
|
+
|
|
11
|
+
本版同時把這個真實路徑加入發佈前自動場景檢查,作為 `qa:release` scenario 3c;未來候選版本若再出現相同組合,會在 publish 前被擋下。
|
|
12
|
+
|
|
13
|
+
## 對你已有檔案的影響
|
|
14
|
+
|
|
15
|
+
既有項目不用重裝。若你的項目本來已經有 lifecycle 欄位,但欄位仍是 TBD,upgrade 可能會把該欄位改成 `Reclassified at upgrade` 說明。這是工具對舊模板狀態的安全遷移,不會覆寫你的 Completed、Validation、Next Priorities 或其他工作紀錄。
|
|
16
|
+
|
|
17
|
+
若 handoff 本身真的仍有完成事項與待辦事項互相矛盾,下一次 closeout 仍應由 AI 正常整理;本版只處理舊 placeholder 造成的升級自撞,不把 AI 對專案內容的判斷交給 installer 猜測。
|
|
18
|
+
|
|
19
|
+
## 建議下一步
|
|
20
|
+
|
|
21
|
+
已安裝舊版的項目可先預演:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
如果預演沒有 conflict,再執行正式升級。升級後若自動 doctor 通過,即可繼續使用;若仍有缺失,請把完整檢查輸出交給 AI 修補,不要用重裝覆寫既有內容。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@adamchanadam/agent-handoff-kit",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.15",
|
|
4
4
|
"description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -18,10 +18,11 @@
|
|
|
18
18
|
"doctor": "node bin/agent-handoff-kit.mjs doctor --root .",
|
|
19
19
|
"dry-run": "node bin/agent-handoff-kit.mjs init --dry-run --root .",
|
|
20
20
|
"qa:prototype": "node scripts/check-public-prototype.mjs",
|
|
21
|
-
"qa:packs": "node scripts/check-pack-scenarios.mjs",
|
|
22
|
-
"qa:upgrade": "node scripts/check-upgrade-safety.mjs",
|
|
23
|
-
"qa:release": "node scripts/check-release-readiness.mjs",
|
|
24
|
-
"qa:
|
|
21
|
+
"qa:packs": "node scripts/check-pack-scenarios.mjs",
|
|
22
|
+
"qa:upgrade": "node scripts/check-upgrade-safety.mjs",
|
|
23
|
+
"qa:release": "node scripts/check-release-readiness.mjs",
|
|
24
|
+
"qa:prompt-mirror": "node scripts/check-prompt-mirror.mjs",
|
|
25
|
+
"qa:fixtures": "node scripts/generate-upgrade-fixtures.mjs"
|
|
25
26
|
},
|
|
26
27
|
"engines": {
|
|
27
28
|
"node": ">=18"
|
package/packs/safety.md
CHANGED
|
@@ -1,10 +1,16 @@
|
|
|
1
1
|
# Safety Pack
|
|
2
2
|
|
|
3
|
-
## Scope
|
|
4
|
-
|
|
5
|
-
Use for file operations, shell commands, Git changes, package managers, installers, deploy tools, release tools, cloud tools, external APIs, locked files, permission errors, sandbox restrictions, or any task that could affect data loss, credentials, public release state, or external systems.
|
|
6
|
-
|
|
7
|
-
##
|
|
3
|
+
## Scope
|
|
4
|
+
|
|
5
|
+
Use for file operations, shell commands, Git changes, package managers, installers, deploy tools, release tools, cloud tools, external APIs, locked files, permission errors, sandbox restrictions, or any task that could affect data loss, credentials, public release state, or external systems.
|
|
6
|
+
|
|
7
|
+
## Load When
|
|
8
|
+
|
|
9
|
+
- User requests deletion, overwrite, move, rename, cleanup, Git history changes, package installation, publish, deploy, release, cloud writes, external API calls, or credential handling.
|
|
10
|
+
- A task touches filesystem paths, shell commands, permissions, sandbox limits, locks, secrets, external systems, or public release state.
|
|
11
|
+
- Another pack is loaded but the task includes data-loss, credential, permission, external-system, or irreversible-operation risk.
|
|
12
|
+
|
|
13
|
+
## Rules
|
|
8
14
|
|
|
9
15
|
1. Before deleting, overwriting, moving, renaming, cleaning, resetting, publishing, or running destructive tool operations, list the exact target paths, expected scope, impact, and required confirmation.
|
|
10
16
|
2. Preserve user-provided source files by default. Create renamed outputs instead of in-place overwrites unless overwrite is explicitly requested.
|