@adamchanadam/agent-handoff-kit 0.3.56 → 0.3.58
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.en.md +2 -2
- package/README.md +2 -2
- package/bin/agent-handoff-kit.mjs +214 -23
- package/bin/migration-baselines/official-origin-catalog.json +376 -1
- package/package.json +1 -1
- package/packs/agent-governance.md +1 -0
- package/packs/onboarding.md +4 -4
- package/runtime-core/AGENTS.core.md +4 -4
- package/runtime-core/PROJECT_INDEX.md +1 -1
- package/runtime-core/RULE_PACKS.md +1 -1
- package/runtime-core/SESSION_HANDOFF.md +1 -1
- package/runtime-core/START_NEXT_SESSION_PROMPT.txt +1 -1
package/README.en.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[繁體中文](README.md) · [Getting started](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.en.html) · [Practical guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html) · [AI install page](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.en.html)
|
|
4
4
|
|
|
5
|
-
Source package version: `v0.3.
|
|
5
|
+
Source package version: `v0.3.58`. npm `@latest` and GitHub Release are verified by post-publish readback.
|
|
6
6
|
|
|
7
7
|
<p align="center">
|
|
8
8
|
<img src="https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-promo-30s.gif" alt="Agent Handoff Kit overview animation" width="720">
|
|
@@ -97,7 +97,7 @@ If the AI is not yet pointed at the project folder, use the path-bearing startup
|
|
|
97
97
|
Work in <your project folder>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.
|
|
98
98
|
```
|
|
99
99
|
|
|
100
|
-
A first installation
|
|
100
|
+
A first installation marks onboarding as pending. If you only say `Start Agent Handoff` or `開工` after installing, and you do not provide a clear task in the same message, the AI should show the startup card and enter a short first-use welcome. Upgrades of existing projects do not reset that flow. When your goal and the available facts are clear, the AI may give a brief first-use frame and then begin the first safe task action.
|
|
101
101
|
|
|
102
102
|
For ordinary daily startup, the AI reads `dev/SESSION_HANDOFF.md` first. Inside the same folder it does not reread `START_NEXT_SESSION_PROMPT.txt` or `dev/SESSION_LOG.md` during normal startup. The prompt copy is only for an AI that has not yet been pointed at the project folder.
|
|
103
103
|
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
English: [README.en.md](README.en.md) · [Getting started](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.en.html) · [Practical guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html) · [AI install page](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.en.html)
|
|
4
4
|
|
|
5
|
-
原始碼套件版本:`v0.3.
|
|
5
|
+
原始碼套件版本:`v0.3.58`。npm `@latest` 與 GitHub Release 以發佈後讀回為準。
|
|
6
6
|
|
|
7
7
|
<p align="center">
|
|
8
8
|
<img src="https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-promo-30s.gif" alt="Agent Handoff Kit 功能簡介動畫" width="720">
|
|
@@ -97,7 +97,7 @@ Start Agent Handoff
|
|
|
97
97
|
Work in <你的專案資料夾>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.
|
|
98
98
|
```
|
|
99
99
|
|
|
100
|
-
|
|
100
|
+
第一次安裝會把新手引導標記為待使用。若你安裝後只說 `Start Agent Handoff` 或「開工」,而沒有同句給出清楚任務,AI 應顯示開工卡並進入簡短新手歡迎引導;升級既有項目則不會重置這個流程。你已清楚描述目標和現有資料時,AI 可先用很短的新手框架說明工作節奏,再開始第一個安全步驟。日常「開工」先讀 `dev/SESSION_HANDOFF.md`;同一資料夾內不會再重讀 `START_NEXT_SESSION_PROMPT.txt` 或 `dev/SESSION_LOG.md`。提示副本只供尚未指向專案資料夾的 AI 接入。
|
|
101
101
|
|
|
102
102
|
「開工,繼續 <任務>」、「<項目> 開工」或 `Start Agent Handoff and continue <task>` 會直接接力。只有語句明顯可能指現實世界的開業、輪班或其他無關事件時,AI 才作一次簡短確認。
|
|
103
103
|
|
|
@@ -70,7 +70,7 @@ const requiredAnchors = [
|
|
|
70
70
|
"continuity ready",
|
|
71
71
|
"推薦下一步",
|
|
72
72
|
"Start Agent Handoff",
|
|
73
|
-
"
|
|
73
|
+
"First-use exception: when `dev/SESSION_HANDOFF.md` says `First-use guidance state: eligible`",
|
|
74
74
|
"Direct ordinary tasks do not show the card",
|
|
75
75
|
"Reachable is not the same as ingested",
|
|
76
76
|
"Proportionate Work Loop",
|
|
@@ -619,13 +619,58 @@ async function runCloseoutStatus(root, version) {
|
|
|
619
619
|
// A closeout card needs a fresh local health readback, not a version-notice
|
|
620
620
|
// network request. The caller has already completed the closeout workflow.
|
|
621
621
|
const doctor = await assessUpgradeNoopHealth(root, version, { skipVersionRegistryLookup: true });
|
|
622
|
-
if (!doctor.ok)
|
|
622
|
+
if (!doctor.ok) {
|
|
623
|
+
findings.push("fresh doctor read-back did not pass");
|
|
624
|
+
details.push(...closeoutDoctorFailureDetails(doctor));
|
|
625
|
+
}
|
|
623
626
|
|
|
624
627
|
const result = { ok: findings.length === 0, findings, details };
|
|
625
628
|
printCloseoutStatusCard(version, result);
|
|
626
629
|
if (!result.ok) process.exitCode = 1;
|
|
627
630
|
}
|
|
628
631
|
|
|
632
|
+
function closeoutDoctorFailureDetails(doctor) {
|
|
633
|
+
const output = [doctor.stdout, doctor.stderr, doctor.error ? `error: ${doctor.error}` : ""]
|
|
634
|
+
.filter(Boolean)
|
|
635
|
+
.join("\n");
|
|
636
|
+
const lines = output.split(/\r?\n/u).map((line) => line.trimEnd()).filter(Boolean);
|
|
637
|
+
const details = [];
|
|
638
|
+
const seen = new Set();
|
|
639
|
+
const add = (label, value) => {
|
|
640
|
+
const safe = safeCloseoutDoctorLine(value);
|
|
641
|
+
if (!safe) return;
|
|
642
|
+
const detail = `${label}${safe}`;
|
|
643
|
+
if (seen.has(detail)) return;
|
|
644
|
+
seen.add(detail);
|
|
645
|
+
details.push(detail);
|
|
646
|
+
};
|
|
647
|
+
|
|
648
|
+
add("Doctor: ", lines.find((line) => /^status:\s*failed\b/iu.test(line)));
|
|
649
|
+
const firstProblemIndex = lines.findIndex((line) => /^(missing|warn|failed)\s{2,}\S/iu.test(line.trim()));
|
|
650
|
+
if (firstProblemIndex >= 0) {
|
|
651
|
+
add("Doctor first problem: ", lines[firstProblemIndex].trim());
|
|
652
|
+
for (let offset = 1; offset <= 3 && firstProblemIndex + offset < lines.length; offset += 1) {
|
|
653
|
+
const line = lines[firstProblemIndex + offset].trim();
|
|
654
|
+
if (/^(missing|reason|error|warning|blocked|缺|missing anchor text):/iu.test(line)) {
|
|
655
|
+
add("Doctor detail: ", line);
|
|
656
|
+
}
|
|
657
|
+
}
|
|
658
|
+
}
|
|
659
|
+
add("Doctor next step: ", lines.find((line) => /^🚀\s*下一步:/u.test(line)));
|
|
660
|
+
if (details.length === 0 && doctor.error) add("Doctor error: ", `error: ${doctor.error}`);
|
|
661
|
+
if (details.length === 0) add("Doctor: ", "fresh doctor failed before producing a readable blocker");
|
|
662
|
+
return details.slice(0, 6);
|
|
663
|
+
}
|
|
664
|
+
|
|
665
|
+
function safeCloseoutDoctorLine(value) {
|
|
666
|
+
if (!value) return "";
|
|
667
|
+
let line = String(value).replace(/\s+/gu, " ").trim();
|
|
668
|
+
for (const { pattern, label } of credentialLeakPatterns) {
|
|
669
|
+
line = line.replace(pattern, `<REDACTED:${label}>`);
|
|
670
|
+
}
|
|
671
|
+
return line.slice(0, 500);
|
|
672
|
+
}
|
|
673
|
+
|
|
629
674
|
function closeoutOutcome(value) {
|
|
630
675
|
return /^(complete|completed)\b/i.test((value ?? "").trim()) ? "complete" : "blocked";
|
|
631
676
|
}
|
|
@@ -695,7 +740,11 @@ async function runInstall(command, root, options, version) {
|
|
|
695
740
|
await validateTransactionRoot(root, [], { createMissingRoot: false });
|
|
696
741
|
if (options.dryRun) await assertDryRunHasNoPendingTransaction(root);
|
|
697
742
|
else {
|
|
698
|
-
await
|
|
743
|
+
if (await isIgnorableCompletedCreateOnlyInitLock(root)) {
|
|
744
|
+
console.log("⚠️ stale completed init lock ignored: current files match the create-only install journal; lock remains as historical evidence.");
|
|
745
|
+
} else {
|
|
746
|
+
await recoverInterruptedTransaction(root);
|
|
747
|
+
}
|
|
699
748
|
if (command === "upgrade" && process.env.AGENT_HANDOFF_KIT_QA_RECOVER_ONLY === "1") {
|
|
700
749
|
console.log("QA recovery-only path completed; no new upgrade transaction was started.");
|
|
701
750
|
return;
|
|
@@ -828,6 +877,10 @@ async function executeInstallTransaction(command, root, mode, plan, version, can
|
|
|
828
877
|
// The user has confirmed writes. Create and revalidate a missing root only
|
|
829
878
|
// now, immediately before transaction artifacts are prepared.
|
|
830
879
|
await validateTransactionRoot(root, plan, { createMissingRoot: true });
|
|
880
|
+
if (isDirectNoClobberCreateInstall(command, plan, outputs, preflight.archiveMigrations)) {
|
|
881
|
+
await executeDirectNoClobberCreateInstall(command, root, mode, plan, version, outputs);
|
|
882
|
+
return;
|
|
883
|
+
}
|
|
831
884
|
const transaction = await prepareTransaction(root, command, version, outputs, mode, plan, preflight.archiveMigrations);
|
|
832
885
|
try {
|
|
833
886
|
await injectBeforeLockRevalidationDrift(root, transaction.journal);
|
|
@@ -959,6 +1012,52 @@ async function executeInstallTransaction(command, root, mode, plan, version, can
|
|
|
959
1012
|
}
|
|
960
1013
|
}
|
|
961
1014
|
|
|
1015
|
+
function isDirectNoClobberCreateInstall(command, plan, outputs, archiveMigrations = []) {
|
|
1016
|
+
return ["init", "upgrade"].includes(command)
|
|
1017
|
+
&& archiveMigrations.length === 0
|
|
1018
|
+
&& outputs.length > 0
|
|
1019
|
+
&& outputs.every((output) => !output.before && output.beforeHash === null)
|
|
1020
|
+
&& plan.every((item) => item.action === "create" || item.action === "skip");
|
|
1021
|
+
}
|
|
1022
|
+
|
|
1023
|
+
async function executeDirectNoClobberCreateInstall(command, root, mode, plan, version, outputs) {
|
|
1024
|
+
for (const output of outputs) {
|
|
1025
|
+
const current = await readOptionalBuffer(output.targetAbs);
|
|
1026
|
+
if (current) throw new Error(`${output.targetRel}: target appeared before create-only install write; no overwrite attempted`);
|
|
1027
|
+
}
|
|
1028
|
+
|
|
1029
|
+
for (const output of outputs) {
|
|
1030
|
+
await mkdir(path.dirname(output.targetAbs), { recursive: true });
|
|
1031
|
+
await writeFile(output.targetAbs, output.after, { mode: 0o600, flag: "wx" });
|
|
1032
|
+
const written = await readOptionalBuffer(output.targetAbs);
|
|
1033
|
+
if (!written || sha256(written) !== output.afterHash) {
|
|
1034
|
+
throw new Error(`${output.targetRel}: create-only install readback failed`);
|
|
1035
|
+
}
|
|
1036
|
+
}
|
|
1037
|
+
|
|
1038
|
+
const doctorStatus = await runDoctor(root, version, {
|
|
1039
|
+
silentCard: true,
|
|
1040
|
+
context: "post-fresh-install-project-health",
|
|
1041
|
+
skipVersionRegistryLookup: true
|
|
1042
|
+
});
|
|
1043
|
+
if (doctorStatus !== "passed") {
|
|
1044
|
+
throw new Error("post-install doctor failed; create-only install is incomplete");
|
|
1045
|
+
}
|
|
1046
|
+
|
|
1047
|
+
const created = outputs.map((item) => item.targetRel);
|
|
1048
|
+
printCard(version, "continuity ready", "o.o");
|
|
1049
|
+
printInstallSummary(version, command, mode, root, {
|
|
1050
|
+
created: created.length,
|
|
1051
|
+
merged: 0,
|
|
1052
|
+
skipped: plan.filter((item) => item.action === "skip").length,
|
|
1053
|
+
conflicts: 0,
|
|
1054
|
+
directCreateOnly: true
|
|
1055
|
+
});
|
|
1056
|
+
console.log("✅ create-only install:只建立缺少檔案,沒有覆寫既有內容,也沒有建立 migration transaction。");
|
|
1057
|
+
console.log("✅ project health: passed");
|
|
1058
|
+
printInstallNextSteps(root, 0, mode, plan.filter((item) => item.action === "skip").length, { directCreateOnly: true });
|
|
1059
|
+
}
|
|
1060
|
+
|
|
962
1061
|
async function buildInstallTransactionPreflight(command, root, plan, version, options = {}) {
|
|
963
1062
|
const outputs = options.candidateOutputs ?? await buildTransactionOutputs(command, root, plan, version, {
|
|
964
1063
|
allowActiveTransaction: options.allowActiveTransaction === true
|
|
@@ -1216,11 +1315,12 @@ async function synchronizeFormalUserRulesTransactionState(command, root, byTarge
|
|
|
1216
1315
|
if (!routerOutput) return;
|
|
1217
1316
|
|
|
1218
1317
|
let prior = null;
|
|
1219
|
-
if (command === "upgrade") {
|
|
1318
|
+
if (command === "upgrade" && routerOutput.before) {
|
|
1220
1319
|
// The old formal reader is the sole authority for whether a prior router
|
|
1221
1320
|
// is eligible for transition. A path, title, or directory never grants
|
|
1222
1321
|
// this authority.
|
|
1223
|
-
|
|
1322
|
+
const allowActiveTransaction = options.allowActiveTransaction === true || await isIgnorableCompletedCreateOnlyInitLock(root);
|
|
1323
|
+
prior = await readFormalUserRules({ root, allowActiveTransaction });
|
|
1224
1324
|
}
|
|
1225
1325
|
|
|
1226
1326
|
let agentOutput = byTarget.get("AGENTS.md");
|
|
@@ -2373,6 +2473,44 @@ function processIsAlive(pid) {
|
|
|
2373
2473
|
try { process.kill(pid, 0); return true; } catch { return false; }
|
|
2374
2474
|
}
|
|
2375
2475
|
|
|
2476
|
+
async function isIgnorableCompletedCreateOnlyInitLock(root) {
|
|
2477
|
+
const lockPath = path.join(root, "dev", "governance_migrations", ".upgrade.lock");
|
|
2478
|
+
let lock;
|
|
2479
|
+
try {
|
|
2480
|
+
lock = JSON.parse(await readFile(lockPath, "utf8"));
|
|
2481
|
+
} catch {
|
|
2482
|
+
return false;
|
|
2483
|
+
}
|
|
2484
|
+
if (!lock || typeof lock !== "object" || Array.isArray(lock) || typeof lock.id !== "string" || typeof lock.journal !== "string"
|
|
2485
|
+
|| lock.command !== "init" || typeof lock.host !== "string" || !Number.isInteger(lock.pid) || lock.pid <= 0) {
|
|
2486
|
+
return false;
|
|
2487
|
+
}
|
|
2488
|
+
if (lock.host !== hostname() || processIsAlive(lock.pid)) return false;
|
|
2489
|
+
const journalPath = path.resolve(root, lock.journal);
|
|
2490
|
+
if (!isInside(root, journalPath)) return false;
|
|
2491
|
+
let journal;
|
|
2492
|
+
try {
|
|
2493
|
+
journal = JSON.parse(await readFile(journalPath, "utf8"));
|
|
2494
|
+
} catch {
|
|
2495
|
+
return false;
|
|
2496
|
+
}
|
|
2497
|
+
if (journal.command !== "init" || !["prepared", "committing", "committed"].includes(journal.state)) return false;
|
|
2498
|
+
if ((journal.archiveMigrations ?? []).length > 0) return false;
|
|
2499
|
+
let validated;
|
|
2500
|
+
try {
|
|
2501
|
+
validated = await validateRecoveryJournal(root, journal, journalPath, lock.id);
|
|
2502
|
+
} catch {
|
|
2503
|
+
return false;
|
|
2504
|
+
}
|
|
2505
|
+
if (validated.length === 0) return false;
|
|
2506
|
+
if (!validated.every(({ entry }) => entry.existed === false && entry.beforeHash === null && entry.backupRel === null)) return false;
|
|
2507
|
+
for (const { entry, targetAbs } of validated) {
|
|
2508
|
+
const current = await readOptionalBuffer(targetAbs);
|
|
2509
|
+
if (!current || sha256(current) !== entry.afterHash) return false;
|
|
2510
|
+
}
|
|
2511
|
+
return true;
|
|
2512
|
+
}
|
|
2513
|
+
|
|
2376
2514
|
async function assertDryRunHasNoPendingTransaction(root) {
|
|
2377
2515
|
const lockPath = path.join(root, "dev", "governance_migrations", ".upgrade.lock");
|
|
2378
2516
|
try {
|
|
@@ -2381,6 +2519,7 @@ async function assertDryRunHasNoPendingTransaction(root) {
|
|
|
2381
2519
|
if (error?.code === "ENOENT") return;
|
|
2382
2520
|
throw error;
|
|
2383
2521
|
}
|
|
2522
|
+
if (await isIgnorableCompletedCreateOnlyInitLock(root)) return;
|
|
2384
2523
|
throw new Error("dry-run blocked: an unresolved transaction requires a non-dry-run recovery; no files written");
|
|
2385
2524
|
}
|
|
2386
2525
|
|
|
@@ -2709,7 +2848,7 @@ function byteWitness(bytes) {
|
|
|
2709
2848
|
async function hasActiveTransactionLock(root) {
|
|
2710
2849
|
try {
|
|
2711
2850
|
await lstat(path.join(root, "dev", "governance_migrations", ".upgrade.lock"));
|
|
2712
|
-
return
|
|
2851
|
+
return !(await isIgnorableCompletedCreateOnlyInitLock(root));
|
|
2713
2852
|
} catch (error) {
|
|
2714
2853
|
if (error?.code === "ENOENT") return false;
|
|
2715
2854
|
throw error;
|
|
@@ -2724,7 +2863,8 @@ async function checkFormalUserRules(root, options = {}) {
|
|
|
2724
2863
|
return { ok: true, checked: 0, finding: null };
|
|
2725
2864
|
}
|
|
2726
2865
|
try {
|
|
2727
|
-
const
|
|
2866
|
+
const allowActiveTransaction = options.allowActiveTransaction === true || await isIgnorableCompletedCreateOnlyInitLock(root);
|
|
2867
|
+
const state = await readFormalUserRules({ root, allowActiveTransaction });
|
|
2728
2868
|
if (options.expectedFormalUserRules) assertFormalUserRulesReadback(state, options.expectedFormalUserRules);
|
|
2729
2869
|
if (typeof options.captureFormalUserRules === "function") options.captureFormalUserRules(state);
|
|
2730
2870
|
return { ok: true, checked: 1, finding: null, state };
|
|
@@ -3140,7 +3280,9 @@ function handoffStateLines(text, markerId, headingTitle) {
|
|
|
3140
3280
|
function isOwnedOpeningLifecycleBoilerplate(line) {
|
|
3141
3281
|
return /^Resume the current objective\. A plain `Start Agent Handoff` \/ `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery/i.test(line)
|
|
3142
3282
|
|| /^A fresh install only makes guidance available; it does not force onboarding\./i.test(line)
|
|
3143
|
-
|| /^
|
|
3283
|
+
|| /^First-use exception: when this handoff says `First-use guidance state: eligible`/i.test(line)
|
|
3284
|
+
|| /^Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading\./i.test(line)
|
|
3285
|
+
|| /^Upgrade never resets consumed \/ not_applicable first-use state back to eligible\./i.test(line);
|
|
3144
3286
|
}
|
|
3145
3287
|
|
|
3146
3288
|
function stripResolvedNegatedActionClauses(line) {
|
|
@@ -3201,8 +3343,10 @@ function isExplicitLifecycleReclassification(line) {
|
|
|
3201
3343
|
|
|
3202
3344
|
const labelled = normalized.match(/(?:\bcondition|\btrigger|\bmissing evidence|條件|觸發條件|缺少證據|證據|原因|\breason)\s*[::-]\s*([^;;\n]+)/i);
|
|
3203
3345
|
if (labelled) return isSubstantiveLifecycleCondition(labelled[1]);
|
|
3204
|
-
const temporal = normalized.match(/(?:\bwhen|\buntil|待)(?:\s+|:|:)([^;;\n]+)/i);
|
|
3205
|
-
|
|
3346
|
+
const temporal = normalized.match(/(?:\bwhen|\buntil|\bif|待)(?:\s+|:|:)([^;;\n]+)/i);
|
|
3347
|
+
if (temporal) return isSubstantiveLifecycleCondition(temporal[1]);
|
|
3348
|
+
const chineseConditional = normalized.match(/(?:如有|若有|如果|若|一旦|當|只在|只有|除非)([^;;\n]+)/i);
|
|
3349
|
+
return chineseConditional ? isSubstantiveLifecycleCondition(chineseConditional[1]) : false;
|
|
3206
3350
|
}
|
|
3207
3351
|
|
|
3208
3352
|
function isSubstantiveLifecycleCondition(value) {
|
|
@@ -3213,6 +3357,31 @@ function isSubstantiveLifecycleCondition(value) {
|
|
|
3213
3357
|
return true;
|
|
3214
3358
|
}
|
|
3215
3359
|
|
|
3360
|
+
function isResolvedCarryForwardStatement(line) {
|
|
3361
|
+
const normalized = line.trim();
|
|
3362
|
+
if (/(?:\b(?:but|however|except|unless|still)\b|但|不過|除非|仍需|仍然需要)/i.test(normalized)) return false;
|
|
3363
|
+
return /\bno\s+(?:known\s+)?(?:active\s+)?(?:blockers?|risks?|unresolved|pending|open items?)\b.{0,80}\b(?:remain|remains|remaining|left|known|active)?/i.test(normalized)
|
|
3364
|
+
|| /\b(?:blockers?|risks?|unresolved|pending|open items?)\b.{0,80}\b(?:none|not required|no longer|resolved|cleared|complete)\b/i.test(normalized)
|
|
3365
|
+
|| /(?:無|沒有|未有)(?:已知|現有|active|明確)?(?:阻擋|阻塞|blocker|風險|未解|待辦|未完成)/i.test(normalized)
|
|
3366
|
+
|| /(?:阻擋|阻塞|blocker|風險|未解|待辦|未完成).{0,30}(?:無|沒有|未有|已清除|已解決|不再|不用|無需)/i.test(normalized);
|
|
3367
|
+
}
|
|
3368
|
+
|
|
3369
|
+
function openingLifecycleDirectiveText(line) {
|
|
3370
|
+
return line
|
|
3371
|
+
.replace(/^recommended next step\s*[::-]\s*/i, "")
|
|
3372
|
+
.replace(/^(?:next action|next step|current objective|objective)\s*[::-]\s*/i, "")
|
|
3373
|
+
.replace(/^(?:下一步|目前目標|當前目標)\s*[::-]\s*/i, "")
|
|
3374
|
+
.trim();
|
|
3375
|
+
}
|
|
3376
|
+
|
|
3377
|
+
function isOpeningLifecycleCarryForwardLine(line) {
|
|
3378
|
+
const normalized = openingLifecycleDirectiveText(line);
|
|
3379
|
+
if (!normalized || isResolvedCarryForwardStatement(normalized) || isExplicitLifecycleReclassification(normalized)) return false;
|
|
3380
|
+
if (/^(?:completed|finished|verified|passed|done|resolved)\b|^(?:已完成|完成|已驗證|已核對|通過|已處理|已解決)/i.test(normalized)) return false;
|
|
3381
|
+
if (/^(?:continue|resume|finish|complete|fix|repair|run|update|write|review|prepare|implement|publish|release|push|tag|deploy|deliver|import|read|authorize|decide|go to)\b/i.test(normalized)) return true;
|
|
3382
|
+
return /^(?:繼續|續|處理|修補|修正|修復|完成|執行|跑|更新|撰寫|寫|審閱|核對|驗證|發佈|發布|提交|推送|匯入|讀取|前往|去|授權|決定|先|請|要|需要|仍需|尚需|待)/i.test(normalized);
|
|
3383
|
+
}
|
|
3384
|
+
|
|
3216
3385
|
function findHandoffLifecycleContradictions(text) {
|
|
3217
3386
|
const resolved = [
|
|
3218
3387
|
...handoffStateLines(text, "completed-this-session", "Completed This Session")
|
|
@@ -3227,11 +3396,12 @@ function findHandoffLifecycleContradictions(text) {
|
|
|
3227
3396
|
...handoffStateLines(text, "risks-blockers", "Risks / Blockers")
|
|
3228
3397
|
.map((line) => ({ section: "Risks / Blockers", line })),
|
|
3229
3398
|
...handoffStateLines(text, "next-session-opening-message", "Next Session Opening Message")
|
|
3399
|
+
.filter((line) => isOpeningLifecycleCarryForwardLine(line))
|
|
3230
3400
|
.map((line) => ({ section: "Next Session Opening Message", line }))
|
|
3231
3401
|
];
|
|
3232
3402
|
const findings = [];
|
|
3233
3403
|
for (const pending of carryForward) {
|
|
3234
|
-
if (isExplicitLifecycleReclassification(pending.line)) continue;
|
|
3404
|
+
if (isResolvedCarryForwardStatement(pending.line) || isExplicitLifecycleReclassification(pending.line)) continue;
|
|
3235
3405
|
for (const done of resolved) {
|
|
3236
3406
|
if (lifecycleTopicsOverlap(done.line, pending.line)) findings.push({ resolved: done, carryForward: pending });
|
|
3237
3407
|
}
|
|
@@ -3464,6 +3634,15 @@ async function buildPlan(root, command, version = null) {
|
|
|
3464
3634
|
action: "skip",
|
|
3465
3635
|
reason: "no pre-existing formal user-rules state; router path does not imply legacy ownership"
|
|
3466
3636
|
});
|
|
3637
|
+
} else if (!routerText && declaresFormalEntry && await canCreateMissingFormalUserRulesRouter(root, agentsText)) {
|
|
3638
|
+
plan.push({
|
|
3639
|
+
sourceRel,
|
|
3640
|
+
targetRel,
|
|
3641
|
+
sourceAbs,
|
|
3642
|
+
targetAbs,
|
|
3643
|
+
action: "create",
|
|
3644
|
+
reason: "complete interrupted first-install formal user-rules router without inferring user-rule ownership"
|
|
3645
|
+
});
|
|
3467
3646
|
} else if (!routerText || !declaresFormalEntry) {
|
|
3468
3647
|
plan.push({
|
|
3469
3648
|
sourceRel,
|
|
@@ -3510,6 +3689,13 @@ async function buildPlan(root, command, version = null) {
|
|
|
3510
3689
|
return plan;
|
|
3511
3690
|
}
|
|
3512
3691
|
|
|
3692
|
+
async function canCreateMissingFormalUserRulesRouter(root, agentsText) {
|
|
3693
|
+
if (!agentsText || countText(agentsText, FORMAL_USER_RULES_ENTRY_ANCHOR) !== 1) return false;
|
|
3694
|
+
if (await exists(path.join(root, "dev", "user_rules"))) return false;
|
|
3695
|
+
const health = assessAgentsMdHealth(agentsText);
|
|
3696
|
+
return health.state === "clean" && hasRequiredAnchor("AGENTS.md", agentsText);
|
|
3697
|
+
}
|
|
3698
|
+
|
|
3513
3699
|
async function readTemplateSource(command, sourceRel, targetRel, sourceAbs) {
|
|
3514
3700
|
return readFile(sourceAbs, "utf8");
|
|
3515
3701
|
}
|
|
@@ -3870,7 +4056,7 @@ function mergeOnboardingScenarioALabel(targetText) {
|
|
|
3870
4056
|
|
|
3871
4057
|
function mergeOnboardingDecisionFirstPolicy(targetText, sourceText) {
|
|
3872
4058
|
const legacySignalLine = "- equivalent Chinese user phrases such as \"新手\", \"教我用\", \"我剛安裝\", \"點開始\", \"開工\", \"能力\", or \"能做甚麼\"";
|
|
3873
|
-
const currentSignalBoundary = "- equivalent Chinese user phrases such as \"新手\", \"教我用\", \"我剛安裝\", \"點開始\", \"能力\", or \"能做甚麼\"\n\n### Continuity startup boundary\n\n`Start Agent Handoff` / \"開工\" starts continuity and reads the minimum current handoff state; it is not an onboarding signal. A plain startup stops after its status card and recommended next action; a loaded objective alone does not authorize work. A same-message concrete task may begin normally. Only when no executable objective remains after state reading should the AI ask one concise question or offer the guided onboarding path. Explicit requests such as \"新手,教我用\" enter onboarding directly.";
|
|
4059
|
+
const currentSignalBoundary = "- equivalent Chinese user phrases such as \"新手\", \"教我用\", \"我剛安裝\", \"點開始\", \"能力\", or \"能做甚麼\"\n\n### Continuity startup boundary\n\n`Start Agent Handoff` / \"開工\" starts continuity and reads the minimum current handoff state; it is not an onboarding signal by itself. A plain startup normally stops after its status card and recommended next action; a loaded objective alone does not authorize work. First-use eligible plain startup is the exception: when the handoff says `First-use guidance state: eligible`, the active objective is empty / `TBD`, and the user did not provide a same-message concrete task, enter onboarding instead of ending status-only. A same-message concrete task may begin normally. Only when no executable objective remains after state reading should the AI ask one concise question or offer the guided onboarding path. Explicit requests such as \"新手,教我用\" enter onboarding directly.";
|
|
3874
4060
|
let working = targetText;
|
|
3875
4061
|
let startupBoundaryChanged = false;
|
|
3876
4062
|
if (working.includes(legacySignalLine) && !working.includes("### Continuity startup boundary")) {
|
|
@@ -3902,7 +4088,7 @@ function mergeOnboardingDecisionFirstPolicy(targetText, sourceText) {
|
|
|
3902
4088
|
const replacements = [
|
|
3903
4089
|
[
|
|
3904
4090
|
"Use this transient pack for first-time Agent Handoff Kit users, vague first messages, or fresh-install sessions where the user has not yet chosen a working scenario.",
|
|
3905
|
-
"Use this transient pack for first-time Agent Handoff Kit users who request guidance, or when the user's first-task intent remains genuinely unresolved after reading the available project state."
|
|
4091
|
+
"Use this transient pack for first-time Agent Handoff Kit users after a fresh install, users who request guidance, or when the user's first-task intent remains genuinely unresolved after reading the available project state."
|
|
3906
4092
|
],
|
|
3907
4093
|
[
|
|
3908
4094
|
"- The first user message is short and vague.",
|
|
@@ -5231,9 +5417,10 @@ function printLastCloseout(result) {
|
|
|
5231
5417
|
}
|
|
5232
5418
|
}
|
|
5233
5419
|
|
|
5234
|
-
// R-031.2 v0.3.2+: Project age assessment. Reads the oldest
|
|
5235
|
-
//
|
|
5236
|
-
//
|
|
5420
|
+
// R-031.2 v0.3.2+: Project age assessment. Reads the oldest historical migration
|
|
5421
|
+
// folder timestamp when one exists. Fresh installs intentionally do not create
|
|
5422
|
+
// migration artifacts, so project age can be unknown. Read-only; doctor remains
|
|
5423
|
+
// side-effect-free (no new write logic).
|
|
5237
5424
|
async function assessProjectAge(root) {
|
|
5238
5425
|
const migrationsDir = path.join(root, "dev/governance_migrations");
|
|
5239
5426
|
try {
|
|
@@ -5254,7 +5441,7 @@ function parseMigrationDirectoryDate(name) {
|
|
|
5254
5441
|
|
|
5255
5442
|
function printProjectAge(result) {
|
|
5256
5443
|
if (!result.firstInstall) {
|
|
5257
|
-
console.log(" 🌱 項目首次安裝距今:未知(
|
|
5444
|
+
console.log(" 🌱 項目首次安裝距今:未知(fresh install 不建立 migration 交易目錄;升級後才會有 timestamp)");
|
|
5258
5445
|
return;
|
|
5259
5446
|
}
|
|
5260
5447
|
const today = new Date();
|
|
@@ -5558,6 +5745,8 @@ function printInstallSummary(version, command, mode, root, counts) {
|
|
|
5558
5745
|
console.log(`🔎 剛完成:${command} 命令;create ${counts.created} / merge ${counts.merged} / skip ${counts.skipped} / conflict ${counts.conflicts}。`);
|
|
5559
5746
|
if (counts.conflicts > 0) {
|
|
5560
5747
|
console.log(conflictRepairNextStepLine("🚀", "工具已停手,沒有覆寫 conflict 檔案。"));
|
|
5748
|
+
} else if (counts.directCreateOnly) {
|
|
5749
|
+
console.log("🚀 下一步:本次只補齊缺少檔案並已通過 doctor;不用做 migration 清理。");
|
|
5561
5750
|
} else if (command === "upgrade") {
|
|
5562
5751
|
console.log("🚀 下一步:本次提交已先經同一輪正式 doctor 讀回;請留意下方提交與健康結果。");
|
|
5563
5752
|
} else if (counts.skipped > 0) {
|
|
@@ -5708,10 +5897,11 @@ function printCard(version, status, eyes) {
|
|
|
5708
5897
|
console.log("");
|
|
5709
5898
|
}
|
|
5710
5899
|
|
|
5711
|
-
function printInstallNextSteps(root, conflictCount, mode = "first-install", skippedCount = 0) {
|
|
5900
|
+
function printInstallNextSteps(root, conflictCount, mode = "first-install", skippedCount = 0, options = {}) {
|
|
5712
5901
|
console.log("");
|
|
5713
5902
|
console.log("============================================================");
|
|
5714
|
-
|
|
5903
|
+
const needsPartialRepairStep = skippedCount > 0 && options.directCreateOnly !== true;
|
|
5904
|
+
if (needsPartialRepairStep) {
|
|
5715
5905
|
console.log("⚠️ 已補齊缺少檔案,但仍要檢查入口連接");
|
|
5716
5906
|
} else {
|
|
5717
5907
|
console.log("✅ 安裝完成:下一步請在 AI 對話中操作");
|
|
@@ -5723,7 +5913,7 @@ function printInstallNextSteps(root, conflictCount, mode = "first-install", skip
|
|
|
5723
5913
|
console.log(conflictRepairNextStepLine());
|
|
5724
5914
|
console.log("");
|
|
5725
5915
|
}
|
|
5726
|
-
if (
|
|
5916
|
+
if (needsPartialRepairStep) {
|
|
5727
5917
|
console.log("你原本已有部分 AI 記憶檔,工具已保留它們,沒有覆寫。");
|
|
5728
5918
|
console.log("下一步先不要開始新任務;請在終端機執行以下預演,讓工具檢查能否安全補入口連接:");
|
|
5729
5919
|
console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run");
|
|
@@ -5735,7 +5925,7 @@ function printInstallNextSteps(root, conflictCount, mode = "first-install", skip
|
|
|
5735
5925
|
}
|
|
5736
5926
|
console.log("------------------------------------------------------------");
|
|
5737
5927
|
console.log("⚠️ 下面這句不是終端機指令。");
|
|
5738
|
-
console.log("📋
|
|
5928
|
+
console.log("📋 不用再留在終端機;請打開能讀寫此資料夾的 AI agent。若 AI 已在此資料夾內,新增對話後輸入:");
|
|
5739
5929
|
console.log(" 例如 Claude Code、OpenAI Codex、Gemini CLI、Google Antigravity。");
|
|
5740
5930
|
console.log(" 普通 web chat AI 若不能讀寫本機資料夾,並不適合使用本工具。");
|
|
5741
5931
|
console.log("------------------------------------------------------------");
|
|
@@ -5747,7 +5937,8 @@ function printInstallNextSteps(root, conflictCount, mode = "first-install", skip
|
|
|
5747
5937
|
console.log("------------------------------------------------------------");
|
|
5748
5938
|
console.log("");
|
|
5749
5939
|
console.log("🚀 AI 會依 AGENTS.md 先讀取權威交接狀態。START_NEXT_SESSION_PROMPT.txt 只是給尚未指向此資料夾的 AI 使用的生成鏡像。");
|
|
5750
|
-
console.log("
|
|
5940
|
+
console.log(" 首次安裝後,若你只說 Start Agent Handoff 或「開工」,AI 會顯示開工卡並進入簡短新手歡迎引導;升級不會重置新手流程。");
|
|
5941
|
+
console.log(" 若同一句已給出明確任務,AI 可先用很短的新手框架說明工作節奏,再開始第一個安全步驟。");
|
|
5751
5942
|
console.log(" 收工可說「Wrap up Agent Handoff」/「收工」;「開工,繼續 <任務>」會直接接力。");
|
|
5752
5943
|
console.log("============================================================");
|
|
5753
5944
|
}
|
|
@@ -5885,7 +6076,7 @@ Commands:
|
|
|
5885
6076
|
例如 Claude Code、OpenAI Codex、Gemini CLI、Google Antigravity。
|
|
5886
6077
|
普通 web chat AI 若不能讀寫本機資料夾,並不適合使用本工具。
|
|
5887
6078
|
AI 已在項目根目錄時,依 AGENTS.md 判斷意圖;只有接力、收工或依賴既有狀態的任務才讀交接狀態,
|
|
5888
|
-
不會再重讀 START_NEXT_SESSION_PROMPT.txt
|
|
6079
|
+
不會再重讀 START_NEXT_SESSION_PROMPT.txt。第一次安裝會把新手引導標記為待使用;若只說 Start Agent Handoff 或「開工」且沒有同句明確任務,AI 會進入簡短新手歡迎;升級不會重置。
|
|
5889
6080
|
用「Wrap up Agent Handoff」/「收工」保存交接;「<項目名> 開工」是明確接力。
|
|
5890
6081
|
只有語句確實可能指現實工作、活動或其他語境時,AI 才問一條精簡確認問題。
|
|
5891
6082
|
|
|
@@ -11851,6 +11851,356 @@
|
|
|
11851
11851
|
"canonicalSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef"
|
|
11852
11852
|
}
|
|
11853
11853
|
}
|
|
11854
|
+
},
|
|
11855
|
+
"0.3.56": {
|
|
11856
|
+
"source": {
|
|
11857
|
+
"npm": {
|
|
11858
|
+
"spec": "@adamchanadam/agent-handoff-kit@0.3.56",
|
|
11859
|
+
"shasum": "880365fe0301600d0cd3f840fd5dc93c8044f76e",
|
|
11860
|
+
"integrity": "sha512-ub3WE4wkmQMBGytoFSGiefRiyEEwaFVbsEyv610o+w2v5BwWk81PVPqP5kwujUoCPTCSTbUTSQWP+i1ce/qonA==",
|
|
11861
|
+
"entryCount": 34,
|
|
11862
|
+
"gitHead": "a13ad3fcf6c629545630471fce6280043ffeb014"
|
|
11863
|
+
},
|
|
11864
|
+
"git": {
|
|
11865
|
+
"tag": "v0.3.56",
|
|
11866
|
+
"directObject": "a13ad3fcf6c629545630471fce6280043ffeb014",
|
|
11867
|
+
"peeledCommit": null,
|
|
11868
|
+
"commit": "a13ad3fcf6c629545630471fce6280043ffeb014"
|
|
11869
|
+
},
|
|
11870
|
+
"githubRelease": {
|
|
11871
|
+
"tag": "v0.3.56",
|
|
11872
|
+
"publishedAt": "2026-07-31T11:22:10Z"
|
|
11873
|
+
},
|
|
11874
|
+
"sourceDivergence": {
|
|
11875
|
+
"status": "same-commit",
|
|
11876
|
+
"npmGitHead": "a13ad3fcf6c629545630471fce6280043ffeb014",
|
|
11877
|
+
"remoteTagCommit": "a13ad3fcf6c629545630471fce6280043ffeb014"
|
|
11878
|
+
}
|
|
11879
|
+
},
|
|
11880
|
+
"manifest": {
|
|
11881
|
+
"AGENTS.md": {
|
|
11882
|
+
"state": "present",
|
|
11883
|
+
"contentId": "d62e4367e60fd2926a1507e0f4ffae7e51791f851d9642e94d092d56d2a467af",
|
|
11884
|
+
"rawSha256": "06bd460f50506a88745b5f534382083172a89aecaba4948058a91d1aa0302387",
|
|
11885
|
+
"normalizedSha256": "06bd460f50506a88745b5f534382083172a89aecaba4948058a91d1aa0302387",
|
|
11886
|
+
"canonicalSha256": "06bd460f50506a88745b5f534382083172a89aecaba4948058a91d1aa0302387"
|
|
11887
|
+
},
|
|
11888
|
+
"CLAUDE.md": {
|
|
11889
|
+
"state": "present",
|
|
11890
|
+
"contentId": "7a2cf08a1171762ebcb53f43036a2170655379416945258b9c85d4b189ecaecf",
|
|
11891
|
+
"rawSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad",
|
|
11892
|
+
"normalizedSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad",
|
|
11893
|
+
"canonicalSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad"
|
|
11894
|
+
},
|
|
11895
|
+
"GEMINI.md": {
|
|
11896
|
+
"state": "present",
|
|
11897
|
+
"contentId": "36da47034bb2ce6c760ddbbbbd49dccc1d17665dbb18bec56ffa3b26bac1c135",
|
|
11898
|
+
"rawSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986",
|
|
11899
|
+
"normalizedSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986",
|
|
11900
|
+
"canonicalSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986"
|
|
11901
|
+
},
|
|
11902
|
+
"START_NEXT_SESSION_PROMPT.txt": {
|
|
11903
|
+
"state": "present",
|
|
11904
|
+
"contentId": "44b4f01258bdf76c1478e5dc0b1e9d88d196bbb3ae790edd07497f0cca26b8bd",
|
|
11905
|
+
"rawSha256": "dc62969f9302420e85f2c08a59e3929daa4129347ca8970f9aec82c20fe5aa9c",
|
|
11906
|
+
"normalizedSha256": "dc62969f9302420e85f2c08a59e3929daa4129347ca8970f9aec82c20fe5aa9c",
|
|
11907
|
+
"canonicalSha256": "ab27d779af955d419c0f4290bd85d9d842182be04570ffffb0a725331a6cf409"
|
|
11908
|
+
},
|
|
11909
|
+
"dev/SESSION_HANDOFF.md": {
|
|
11910
|
+
"state": "present",
|
|
11911
|
+
"contentId": "7a273d19af7f2e13fcf514f54d04815bba7cdaf2265af3ce80da168faeec84f7",
|
|
11912
|
+
"rawSha256": "88935679dd7d0042de3e2a336d2e4ba0f87ef51c674718af47620c8f4144d934",
|
|
11913
|
+
"normalizedSha256": "88935679dd7d0042de3e2a336d2e4ba0f87ef51c674718af47620c8f4144d934",
|
|
11914
|
+
"canonicalSha256": "96b45a24a5eb0f39086e199a8eb36a5794f9595fe9253138e7a3c2eb99278178"
|
|
11915
|
+
},
|
|
11916
|
+
"dev/SESSION_LOG.md": {
|
|
11917
|
+
"state": "present",
|
|
11918
|
+
"contentId": "7b6184ee4dabe89f504a894c3d4803f012d962c7af53c7f29801a8fb28d9d51c",
|
|
11919
|
+
"rawSha256": "fb6bfd7026a15f87a54cfa64fbd69f032538b0c3193372876a3722fb997a3a47",
|
|
11920
|
+
"normalizedSha256": "fb6bfd7026a15f87a54cfa64fbd69f032538b0c3193372876a3722fb997a3a47",
|
|
11921
|
+
"canonicalSha256": "fb6bfd7026a15f87a54cfa64fbd69f032538b0c3193372876a3722fb997a3a47"
|
|
11922
|
+
},
|
|
11923
|
+
"dev/PROJECT_INDEX.md": {
|
|
11924
|
+
"state": "present",
|
|
11925
|
+
"contentId": "c2ff51ecd87013f6301a0697d9bc2937eac218cf684ae39341a282250ec46897",
|
|
11926
|
+
"rawSha256": "321aa83eb34720836266a6d5cc9fc612a5e202d4aa1f5780098e6923cd8517c4",
|
|
11927
|
+
"normalizedSha256": "321aa83eb34720836266a6d5cc9fc612a5e202d4aa1f5780098e6923cd8517c4",
|
|
11928
|
+
"canonicalSha256": "8fd316fca77004a94404582a5152c2bbdcf89610b52e7c0fdbfb0076c5cdd759"
|
|
11929
|
+
},
|
|
11930
|
+
"dev/DOC_SYNC_REGISTRY.md": {
|
|
11931
|
+
"state": "present",
|
|
11932
|
+
"contentId": "f6545b524dc440d3563041e04a05caff4229863f6cae2a39127f85a29a120249",
|
|
11933
|
+
"rawSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6",
|
|
11934
|
+
"normalizedSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6",
|
|
11935
|
+
"canonicalSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6"
|
|
11936
|
+
},
|
|
11937
|
+
"dev/RULE_PACKS.md": {
|
|
11938
|
+
"state": "present",
|
|
11939
|
+
"contentId": "a92986fcb4f7630e533bacf114d096e8e655973de297ff972a1bf1de5610af4b",
|
|
11940
|
+
"rawSha256": "a3e433884fc6bf26448acfa79ba106acaaafe5b4bdb212cb8ce6dc4aaea2faaf",
|
|
11941
|
+
"normalizedSha256": "a3e433884fc6bf26448acfa79ba106acaaafe5b4bdb212cb8ce6dc4aaea2faaf",
|
|
11942
|
+
"canonicalSha256": "a3e433884fc6bf26448acfa79ba106acaaafe5b4bdb212cb8ce6dc4aaea2faaf"
|
|
11943
|
+
},
|
|
11944
|
+
"dev/PROJECT_DECISIONS.md": {
|
|
11945
|
+
"state": "present",
|
|
11946
|
+
"contentId": "3aae993bd5b85bf6b1d1d458f1bcf82c7d3105c843f053ffa13553bb5931b8c4",
|
|
11947
|
+
"rawSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e",
|
|
11948
|
+
"normalizedSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e",
|
|
11949
|
+
"canonicalSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e"
|
|
11950
|
+
},
|
|
11951
|
+
"dev/rules/safety.md": {
|
|
11952
|
+
"state": "present",
|
|
11953
|
+
"contentId": "dd6bcf74722d038f76d202e2044a6583a6e6ad107fbb010520e513eec799ff4a",
|
|
11954
|
+
"rawSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0",
|
|
11955
|
+
"normalizedSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0",
|
|
11956
|
+
"canonicalSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0"
|
|
11957
|
+
},
|
|
11958
|
+
"dev/rules/coding.md": {
|
|
11959
|
+
"state": "present",
|
|
11960
|
+
"contentId": "1c6deb9a5a281c13e97b0ac96079e9e1beccbd1ff106186e7a6ac78c0eeb75c2",
|
|
11961
|
+
"rawSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4",
|
|
11962
|
+
"normalizedSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4",
|
|
11963
|
+
"canonicalSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4"
|
|
11964
|
+
},
|
|
11965
|
+
"dev/rules/writing.md": {
|
|
11966
|
+
"state": "present",
|
|
11967
|
+
"contentId": "ceee5412520ba860e6b40de46bb164e2ce3919d2197d5fadb926198eb7dddd3b",
|
|
11968
|
+
"rawSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593",
|
|
11969
|
+
"normalizedSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593",
|
|
11970
|
+
"canonicalSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593"
|
|
11971
|
+
},
|
|
11972
|
+
"dev/rules/research.md": {
|
|
11973
|
+
"state": "present",
|
|
11974
|
+
"contentId": "4414f9c82c6d04ad49d7446f4b0740055242f425ef5b00391d9c8c78c96c0f66",
|
|
11975
|
+
"rawSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104",
|
|
11976
|
+
"normalizedSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104",
|
|
11977
|
+
"canonicalSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104"
|
|
11978
|
+
},
|
|
11979
|
+
"dev/rules/agent-governance.md": {
|
|
11980
|
+
"state": "present",
|
|
11981
|
+
"contentId": "107acfbfc85910c97a369e043edd6d467f85bdf3cf560d07ee844d27cf01bcc9",
|
|
11982
|
+
"rawSha256": "9693c7eee22536b3b90e47a1e8b7e669292b9896b6e05266ea36f7e0dd366845",
|
|
11983
|
+
"normalizedSha256": "9693c7eee22536b3b90e47a1e8b7e669292b9896b6e05266ea36f7e0dd366845",
|
|
11984
|
+
"canonicalSha256": "9693c7eee22536b3b90e47a1e8b7e669292b9896b6e05266ea36f7e0dd366845"
|
|
11985
|
+
},
|
|
11986
|
+
"dev/rules/release.md": {
|
|
11987
|
+
"state": "present",
|
|
11988
|
+
"contentId": "b0a0c9dea88016185f4093f9be4ce3c0e29904222e21dd1fa1735fcc1bb7e744",
|
|
11989
|
+
"rawSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7",
|
|
11990
|
+
"normalizedSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7",
|
|
11991
|
+
"canonicalSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7"
|
|
11992
|
+
},
|
|
11993
|
+
"dev/rules/knowledge.md": {
|
|
11994
|
+
"state": "present",
|
|
11995
|
+
"contentId": "e6f5795c7ebaba7b05f04d971b2942b5a0394a3babb44f64a1cc591c9a08cb86",
|
|
11996
|
+
"rawSha256": "efeed5a4eef59f2ce59852832dddcd0447b2308a76fd01dd7a44ee6a16abb74c",
|
|
11997
|
+
"normalizedSha256": "efeed5a4eef59f2ce59852832dddcd0447b2308a76fd01dd7a44ee6a16abb74c",
|
|
11998
|
+
"canonicalSha256": "efeed5a4eef59f2ce59852832dddcd0447b2308a76fd01dd7a44ee6a16abb74c"
|
|
11999
|
+
},
|
|
12000
|
+
"dev/rules/communication.md": {
|
|
12001
|
+
"state": "present",
|
|
12002
|
+
"contentId": "34fd0034cbc75dad43f789b86a414763f01916dda4d59876db9c4d8d92ae6a87",
|
|
12003
|
+
"rawSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591",
|
|
12004
|
+
"normalizedSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591",
|
|
12005
|
+
"canonicalSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591"
|
|
12006
|
+
},
|
|
12007
|
+
"dev/rules/closeout.md": {
|
|
12008
|
+
"state": "present",
|
|
12009
|
+
"contentId": "0d0c85ac4318670d9ffba85e46cc709ee3b0a9bcb0ad7586079859f98e0a1c72",
|
|
12010
|
+
"rawSha256": "45b8019de97dd730380af9c211da92b541580797a66694b9b4188bed49e999b6",
|
|
12011
|
+
"normalizedSha256": "45b8019de97dd730380af9c211da92b541580797a66694b9b4188bed49e999b6",
|
|
12012
|
+
"canonicalSha256": "45b8019de97dd730380af9c211da92b541580797a66694b9b4188bed49e999b6"
|
|
12013
|
+
},
|
|
12014
|
+
"dev/rules/onboarding.md": {
|
|
12015
|
+
"state": "present",
|
|
12016
|
+
"contentId": "e67b34ca3eb5e3aac6e36aa3a3929daae0c881e803badb6d22d5837fc37588ab",
|
|
12017
|
+
"rawSha256": "ae0ab942b86e216e29e8996f17947442d7568910b84899b6df2b836b1fcdbed3",
|
|
12018
|
+
"normalizedSha256": "ae0ab942b86e216e29e8996f17947442d7568910b84899b6df2b836b1fcdbed3",
|
|
12019
|
+
"canonicalSha256": "ae0ab942b86e216e29e8996f17947442d7568910b84899b6df2b836b1fcdbed3"
|
|
12020
|
+
},
|
|
12021
|
+
"dev/rules/integrations.md": {
|
|
12022
|
+
"state": "present",
|
|
12023
|
+
"contentId": "a8fc1099da28f511bf9fed5eaf629ca10fb409299b0aed4d233a45fc7701f284",
|
|
12024
|
+
"rawSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef",
|
|
12025
|
+
"normalizedSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef",
|
|
12026
|
+
"canonicalSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef"
|
|
12027
|
+
}
|
|
12028
|
+
}
|
|
12029
|
+
},
|
|
12030
|
+
"0.3.57": {
|
|
12031
|
+
"source": {
|
|
12032
|
+
"npm": {
|
|
12033
|
+
"spec": "@adamchanadam/agent-handoff-kit@0.3.57",
|
|
12034
|
+
"shasum": "dbc736542999277dc6f73a4f5f23d88587d23bfd",
|
|
12035
|
+
"integrity": "sha512-8VRGpNlfpFR5LPsxm81/RGvFcIpSCXIteGo18ix0UeCZYOs2DIwT9ZYHPTF+MJln/0um9oNuS5EjXAGg6V7O8w==",
|
|
12036
|
+
"entryCount": 34,
|
|
12037
|
+
"gitHead": "1233909c0746287ab26222f9b76dd216ce659424"
|
|
12038
|
+
},
|
|
12039
|
+
"git": {
|
|
12040
|
+
"tag": "v0.3.57",
|
|
12041
|
+
"directObject": "1233909c0746287ab26222f9b76dd216ce659424",
|
|
12042
|
+
"peeledCommit": null,
|
|
12043
|
+
"commit": "1233909c0746287ab26222f9b76dd216ce659424"
|
|
12044
|
+
},
|
|
12045
|
+
"githubRelease": {
|
|
12046
|
+
"tag": "v0.3.57",
|
|
12047
|
+
"publishedAt": "2026-08-04T12:50:14Z"
|
|
12048
|
+
},
|
|
12049
|
+
"sourceDivergence": {
|
|
12050
|
+
"status": "same-commit",
|
|
12051
|
+
"npmGitHead": "1233909c0746287ab26222f9b76dd216ce659424",
|
|
12052
|
+
"remoteTagCommit": "1233909c0746287ab26222f9b76dd216ce659424"
|
|
12053
|
+
}
|
|
12054
|
+
},
|
|
12055
|
+
"manifest": {
|
|
12056
|
+
"AGENTS.md": {
|
|
12057
|
+
"state": "present",
|
|
12058
|
+
"contentId": "effc2b7606f098d48cf46f0c1fcbd2f312f9dd2d804b194106bb421acbe89915",
|
|
12059
|
+
"rawSha256": "1f1d11ab484adefc8388bee2796720abb64adc708561bb4dbbf9860d366c9a9e",
|
|
12060
|
+
"normalizedSha256": "1f1d11ab484adefc8388bee2796720abb64adc708561bb4dbbf9860d366c9a9e",
|
|
12061
|
+
"canonicalSha256": "1f1d11ab484adefc8388bee2796720abb64adc708561bb4dbbf9860d366c9a9e"
|
|
12062
|
+
},
|
|
12063
|
+
"CLAUDE.md": {
|
|
12064
|
+
"state": "present",
|
|
12065
|
+
"contentId": "7a2cf08a1171762ebcb53f43036a2170655379416945258b9c85d4b189ecaecf",
|
|
12066
|
+
"rawSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad",
|
|
12067
|
+
"normalizedSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad",
|
|
12068
|
+
"canonicalSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad"
|
|
12069
|
+
},
|
|
12070
|
+
"GEMINI.md": {
|
|
12071
|
+
"state": "present",
|
|
12072
|
+
"contentId": "36da47034bb2ce6c760ddbbbbd49dccc1d17665dbb18bec56ffa3b26bac1c135",
|
|
12073
|
+
"rawSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986",
|
|
12074
|
+
"normalizedSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986",
|
|
12075
|
+
"canonicalSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986"
|
|
12076
|
+
},
|
|
12077
|
+
"START_NEXT_SESSION_PROMPT.txt": {
|
|
12078
|
+
"state": "present",
|
|
12079
|
+
"contentId": "44b4f01258bdf76c1478e5dc0b1e9d88d196bbb3ae790edd07497f0cca26b8bd",
|
|
12080
|
+
"rawSha256": "d49b3d79b2eaf00ed60970c633eaea60ec6ee288ec135303a5e215cc6cb08bde",
|
|
12081
|
+
"normalizedSha256": "d49b3d79b2eaf00ed60970c633eaea60ec6ee288ec135303a5e215cc6cb08bde",
|
|
12082
|
+
"canonicalSha256": "ab27d779af955d419c0f4290bd85d9d842182be04570ffffb0a725331a6cf409"
|
|
12083
|
+
},
|
|
12084
|
+
"dev/SESSION_HANDOFF.md": {
|
|
12085
|
+
"state": "present",
|
|
12086
|
+
"contentId": "7a273d19af7f2e13fcf514f54d04815bba7cdaf2265af3ce80da168faeec84f7",
|
|
12087
|
+
"rawSha256": "c9dc59b5c6f8ec315bbc7443957540d5b29991b4e9dfebe1fd767403f8926000",
|
|
12088
|
+
"normalizedSha256": "c9dc59b5c6f8ec315bbc7443957540d5b29991b4e9dfebe1fd767403f8926000",
|
|
12089
|
+
"canonicalSha256": "96b45a24a5eb0f39086e199a8eb36a5794f9595fe9253138e7a3c2eb99278178"
|
|
12090
|
+
},
|
|
12091
|
+
"dev/SESSION_LOG.md": {
|
|
12092
|
+
"state": "present",
|
|
12093
|
+
"contentId": "7b6184ee4dabe89f504a894c3d4803f012d962c7af53c7f29801a8fb28d9d51c",
|
|
12094
|
+
"rawSha256": "fb6bfd7026a15f87a54cfa64fbd69f032538b0c3193372876a3722fb997a3a47",
|
|
12095
|
+
"normalizedSha256": "fb6bfd7026a15f87a54cfa64fbd69f032538b0c3193372876a3722fb997a3a47",
|
|
12096
|
+
"canonicalSha256": "fb6bfd7026a15f87a54cfa64fbd69f032538b0c3193372876a3722fb997a3a47"
|
|
12097
|
+
},
|
|
12098
|
+
"dev/PROJECT_INDEX.md": {
|
|
12099
|
+
"state": "present",
|
|
12100
|
+
"contentId": "c2ff51ecd87013f6301a0697d9bc2937eac218cf684ae39341a282250ec46897",
|
|
12101
|
+
"rawSha256": "d477f13e0b633090b278e1c7f222eee99eaedeca16a957ee326c6a425340f65e",
|
|
12102
|
+
"normalizedSha256": "8bb613b640ae1d00b4ae3b0b9d9cd6cf6e7c12ae1c29fe5513af0abae4250b50",
|
|
12103
|
+
"canonicalSha256": "8fd316fca77004a94404582a5152c2bbdcf89610b52e7c0fdbfb0076c5cdd759"
|
|
12104
|
+
},
|
|
12105
|
+
"dev/DOC_SYNC_REGISTRY.md": {
|
|
12106
|
+
"state": "present",
|
|
12107
|
+
"contentId": "f6545b524dc440d3563041e04a05caff4229863f6cae2a39127f85a29a120249",
|
|
12108
|
+
"rawSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6",
|
|
12109
|
+
"normalizedSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6",
|
|
12110
|
+
"canonicalSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6"
|
|
12111
|
+
},
|
|
12112
|
+
"dev/RULE_PACKS.md": {
|
|
12113
|
+
"state": "present",
|
|
12114
|
+
"contentId": "a92986fcb4f7630e533bacf114d096e8e655973de297ff972a1bf1de5610af4b",
|
|
12115
|
+
"rawSha256": "a3e433884fc6bf26448acfa79ba106acaaafe5b4bdb212cb8ce6dc4aaea2faaf",
|
|
12116
|
+
"normalizedSha256": "a3e433884fc6bf26448acfa79ba106acaaafe5b4bdb212cb8ce6dc4aaea2faaf",
|
|
12117
|
+
"canonicalSha256": "a3e433884fc6bf26448acfa79ba106acaaafe5b4bdb212cb8ce6dc4aaea2faaf"
|
|
12118
|
+
},
|
|
12119
|
+
"dev/PROJECT_DECISIONS.md": {
|
|
12120
|
+
"state": "present",
|
|
12121
|
+
"contentId": "3aae993bd5b85bf6b1d1d458f1bcf82c7d3105c843f053ffa13553bb5931b8c4",
|
|
12122
|
+
"rawSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e",
|
|
12123
|
+
"normalizedSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e",
|
|
12124
|
+
"canonicalSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e"
|
|
12125
|
+
},
|
|
12126
|
+
"dev/rules/safety.md": {
|
|
12127
|
+
"state": "present",
|
|
12128
|
+
"contentId": "dd6bcf74722d038f76d202e2044a6583a6e6ad107fbb010520e513eec799ff4a",
|
|
12129
|
+
"rawSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0",
|
|
12130
|
+
"normalizedSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0",
|
|
12131
|
+
"canonicalSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0"
|
|
12132
|
+
},
|
|
12133
|
+
"dev/rules/coding.md": {
|
|
12134
|
+
"state": "present",
|
|
12135
|
+
"contentId": "1c6deb9a5a281c13e97b0ac96079e9e1beccbd1ff106186e7a6ac78c0eeb75c2",
|
|
12136
|
+
"rawSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4",
|
|
12137
|
+
"normalizedSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4",
|
|
12138
|
+
"canonicalSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4"
|
|
12139
|
+
},
|
|
12140
|
+
"dev/rules/writing.md": {
|
|
12141
|
+
"state": "present",
|
|
12142
|
+
"contentId": "ceee5412520ba860e6b40de46bb164e2ce3919d2197d5fadb926198eb7dddd3b",
|
|
12143
|
+
"rawSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593",
|
|
12144
|
+
"normalizedSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593",
|
|
12145
|
+
"canonicalSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593"
|
|
12146
|
+
},
|
|
12147
|
+
"dev/rules/research.md": {
|
|
12148
|
+
"state": "present",
|
|
12149
|
+
"contentId": "4414f9c82c6d04ad49d7446f4b0740055242f425ef5b00391d9c8c78c96c0f66",
|
|
12150
|
+
"rawSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104",
|
|
12151
|
+
"normalizedSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104",
|
|
12152
|
+
"canonicalSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104"
|
|
12153
|
+
},
|
|
12154
|
+
"dev/rules/agent-governance.md": {
|
|
12155
|
+
"state": "present",
|
|
12156
|
+
"contentId": "107acfbfc85910c97a369e043edd6d467f85bdf3cf560d07ee844d27cf01bcc9",
|
|
12157
|
+
"rawSha256": "9693c7eee22536b3b90e47a1e8b7e669292b9896b6e05266ea36f7e0dd366845",
|
|
12158
|
+
"normalizedSha256": "9693c7eee22536b3b90e47a1e8b7e669292b9896b6e05266ea36f7e0dd366845",
|
|
12159
|
+
"canonicalSha256": "9693c7eee22536b3b90e47a1e8b7e669292b9896b6e05266ea36f7e0dd366845"
|
|
12160
|
+
},
|
|
12161
|
+
"dev/rules/release.md": {
|
|
12162
|
+
"state": "present",
|
|
12163
|
+
"contentId": "b0a0c9dea88016185f4093f9be4ce3c0e29904222e21dd1fa1735fcc1bb7e744",
|
|
12164
|
+
"rawSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7",
|
|
12165
|
+
"normalizedSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7",
|
|
12166
|
+
"canonicalSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7"
|
|
12167
|
+
},
|
|
12168
|
+
"dev/rules/knowledge.md": {
|
|
12169
|
+
"state": "present",
|
|
12170
|
+
"contentId": "e6f5795c7ebaba7b05f04d971b2942b5a0394a3babb44f64a1cc591c9a08cb86",
|
|
12171
|
+
"rawSha256": "efeed5a4eef59f2ce59852832dddcd0447b2308a76fd01dd7a44ee6a16abb74c",
|
|
12172
|
+
"normalizedSha256": "efeed5a4eef59f2ce59852832dddcd0447b2308a76fd01dd7a44ee6a16abb74c",
|
|
12173
|
+
"canonicalSha256": "efeed5a4eef59f2ce59852832dddcd0447b2308a76fd01dd7a44ee6a16abb74c"
|
|
12174
|
+
},
|
|
12175
|
+
"dev/rules/communication.md": {
|
|
12176
|
+
"state": "present",
|
|
12177
|
+
"contentId": "34fd0034cbc75dad43f789b86a414763f01916dda4d59876db9c4d8d92ae6a87",
|
|
12178
|
+
"rawSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591",
|
|
12179
|
+
"normalizedSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591",
|
|
12180
|
+
"canonicalSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591"
|
|
12181
|
+
},
|
|
12182
|
+
"dev/rules/closeout.md": {
|
|
12183
|
+
"state": "present",
|
|
12184
|
+
"contentId": "0d0c85ac4318670d9ffba85e46cc709ee3b0a9bcb0ad7586079859f98e0a1c72",
|
|
12185
|
+
"rawSha256": "45b8019de97dd730380af9c211da92b541580797a66694b9b4188bed49e999b6",
|
|
12186
|
+
"normalizedSha256": "45b8019de97dd730380af9c211da92b541580797a66694b9b4188bed49e999b6",
|
|
12187
|
+
"canonicalSha256": "45b8019de97dd730380af9c211da92b541580797a66694b9b4188bed49e999b6"
|
|
12188
|
+
},
|
|
12189
|
+
"dev/rules/onboarding.md": {
|
|
12190
|
+
"state": "present",
|
|
12191
|
+
"contentId": "e67b34ca3eb5e3aac6e36aa3a3929daae0c881e803badb6d22d5837fc37588ab",
|
|
12192
|
+
"rawSha256": "ae0ab942b86e216e29e8996f17947442d7568910b84899b6df2b836b1fcdbed3",
|
|
12193
|
+
"normalizedSha256": "ae0ab942b86e216e29e8996f17947442d7568910b84899b6df2b836b1fcdbed3",
|
|
12194
|
+
"canonicalSha256": "ae0ab942b86e216e29e8996f17947442d7568910b84899b6df2b836b1fcdbed3"
|
|
12195
|
+
},
|
|
12196
|
+
"dev/rules/integrations.md": {
|
|
12197
|
+
"state": "present",
|
|
12198
|
+
"contentId": "a8fc1099da28f511bf9fed5eaf629ca10fb409299b0aed4d233a45fc7701f284",
|
|
12199
|
+
"rawSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef",
|
|
12200
|
+
"normalizedSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef",
|
|
12201
|
+
"canonicalSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef"
|
|
12202
|
+
}
|
|
12203
|
+
}
|
|
11854
12204
|
}
|
|
11855
12205
|
},
|
|
11856
12206
|
"contents": {
|
|
@@ -12638,7 +12988,32 @@
|
|
|
12638
12988
|
"targetRel": "AGENTS.md",
|
|
12639
12989
|
"canonicalSha256": "3a5cd4e7dd779da791e0a16a51a45a7b8f12f3d396122ee6b05ab2288f512fcd",
|
|
12640
12990
|
"text": "<!-- BEGIN Agent Handoff Kit managed core -->\n# Agent Handoff Kit Core Runtime\n\nThis is the small always-read contract. Detailed task and closeout procedures live in routed packs.\n\n## 1. Intent And Startup\n\nClassify the user's visible intent before loading project state. For explicit continuity, closeout, or a task whose next action depends on persisted project state, read `dev/SESSION_HANDOFF.md` first; it is the current-state authority. A direct ordinary or stateless task does not read the handoff merely because the project root is known. If the message is genuinely unresolved and the handoff can resolve it, read the handoff before asking the user.\n\nDo not read `dev/SESSION_LOG.md` during ordinary startup; it is trace-back evidence only. Do not read `START_NEXT_SESSION_PROMPT.txt` in addition to the handoff when already operating in the project root; that file is a portable generated mirror for an agent that has not yet been pointed at the root.\n\nRoute intent in this order:\n\n1. Clear closeout intent routes directly to `dev/rules/closeout.md`.\n2. Clear continuity intent such as \"開工\", \"Start Agent Handoff\", \"開始接力\", or \"continue handoff\" resumes the minimum current state from the handoff. A plain continuity message with no same-message task or explicit long-run instruction authorizes only that recovery, one optional display-only title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out wording such as \"unless you object I will start\". A concrete objective found only in loaded state is not authority to complete it. A same-message task may begin normally. An explicit instruction such as \"開工,繼續做到下一個 blocker\" or \"開工,繼續完成目前目標\" may continue under the normal task and safety rules.\n3. A direct ordinary task begins without a startup card or onboarding ceremony. Read only the sources and packs required by that task.\n4. Explicit guidance requests such as \"I'm new\", \"teach me\", \"help me start\", \"新手\", \"教我用\", or \"點開始\" may load `dev/rules/onboarding.md`. A fresh install or short message only makes guidance available; it never overrides a concrete objective. If no executable objective remains after state reading, ask one concise question or offer guided onboarding.\n\nTreat a phrase as ambiguous only when its ordinary meaning may genuinely refer to a real-world shift, event, or unrelated context. `開工,繼續 <task>`, `<project> 開工`, and `Start Agent Handoff and continue <task>` are continuity commands, not ambiguous phrases.\n\nDuring explicit continuity startup, the only optional presentation effect beyond state recovery and card/status is a user-visible task/conversation title update, when the active runtime safely supports current-title readback and title control. Derive the startup card's current objective and recommended next action first; only then, immediately before showing the card, choose and apply any title update. Replace only a generic or stale title, or update once when the main objective clearly changes; keep an informative title and do not rename for tests, reviews, or small substeps. Use `<project name>|<primary action>` from facts already loaded for startup: a concrete same-message task first, otherwise the loaded current objective plus recommended next action. Within those facts, select one concrete primary action in this order: the same-message task; the loaded current objective; the recommended next action. The continuity trigger itself and generic phrases such as `Start Agent Handoff`, `開工`, or `開始工作交接` are not primary actions. If the loaded facts do not provide both a concrete project name and a concrete primary action, skip the title update. Do not read `dev/PROJECT_INDEX.md`, files, network, or other state solely to name the title. The title must not contain progress, completion, status, task/session IDs, absolute paths, secrets, or unverified facts. If safe title control/readback is unavailable, skip silently. The title is display-only; it is not project state, permission, progress, completion evidence, a health result, or a source of truth, and it does not authorize project/file writes, network activity, external task work, or continuation beyond the startup boundary.\n\nRead `dev/PROJECT_INDEX.md` when the task needs its file, command, integration, workspace, or source map. Read `dev/RULE_PACKS.md` when a task pack must be selected. Read `dev/DOC_SYNC_REGISTRY.md` before durable cross-file or external synchronization and during closeout. Pack loading is normally silent; explain it only when it changes risk, requires a user decision, or materially affects the next action.\n\nIf the user supplies the portable startup prompt, use it to locate the root, then trust the handoff over the mirror. If the root is unclear or mismatched, stop and ask for the intended root before reading or editing project state. Missing required governance files are a repair condition, not permission to invent a parallel structure.\n\nBefore a non-trivial task, identify and read the required local and external truth sources or mark them blocked. Reachable is not the same as ingested. Search hits, truncated output, summaries, and status claims do not replace the relevant source content.\n\nProbe an integration only immediately before a task uses it, when the handoff explicitly identifies it as a dependency for the current objective, or when the user requests an integration health check. `TBD`, examples, blank rows, and undeclared placeholders are not installed integrations. Record `Last Verified` only after a real probe and through the normal persistence gate. Never write integration status merely because a session started.\n\nShow the startup card only for explicit continuity startup. For a plain continuity message, show the card after the minimum state recovery and end the turn; its recommended next action is advice, not permission to act. An explicit same-message task or long-run continuation may combine the card with its first useful action. Direct ordinary tasks do not show the card. If onboarding is explicitly requested, combine any card and guidance in one response.\n\nFor explicit bare continuity startup, after the handoff is read, the startup card may read only the bounded version evidence from `dev/PROJECT_INDEX.md`: the unique stable-semver `| Agent Handoff Kit template version | X.Y.Z | ... |` row inside the unique real `## Stack` section. Do not route on, summarize, or load any other Project Index content for startup, title, permissions, packs, health, or task work. Missing, unreadable, malformed, duplicate, prerelease, or out-of-Stack-only version evidence prints `version unverified`; the turn remains status-only with zero writes. A direct ordinary or stateless task does not read the handoff or Project Index merely to fill a card or version.\n\n```text\n /\\_/\\ Agent Handoff Kit v<version>\n ( o.o ) continuity ready\n > ^ <\n\n🔎 交接狀態:<loaded / new install / resumed>\n📌 目前目標:<current objective>\n⚠️ 注意事項:<important boundary or none>\n🚀 推薦下一步:<one action + reason>\n```\n\nUse the full product name, plain user language, and one recommended next action. Never print the literal placeholder `v<version>`.\n\n## 2. Proportionate Work Loop\n\nApply PLAN → READ → CHANGE → QC internally and in proportion to task state and risk. Do not make the user watch governance ceremony that does not help the task.\n\nIn every user-facing reply, lead with ordinary language: state the result and its practical effect, then the next action when one helps. Put exact commands, errors, hashes, and detailed evidence after that; brevity must not hide uncertainty or safety risk.\n\n- Simple answers, pure conversation or creation with no durable state, and low-risk tasks with an obvious target may proceed directly with proportionate reading and checking.\n- Non-trivial work reads relevant sources before changing them.\n- High-risk work states scope, impact, acceptance, and required confirmation before writes.\n- External skill flows, subagents, task plans, demo workspaces, and another tool's finish step do not replace the active root's persistence decision.\n- Materially changed Markdown governance artifacts must be indexed, synchronized, consolidated into their authoritative home, or explicitly classified as temporary / one-time evidence. Other durable formats follow the same human governance rule, but the bundled doctor does not claim to scan them.\n\n## 2.1 Persistence Gate\n\nChoose exactly one tier after a task:\n\n1. No persistence: no durable fact was produced. One-off answers, transient output, active unapproved drafts, and routine rerunnable checks normally use this tier.\n2. Lightweight checkpoint: a durable fact affects future action while the session continues or may be interrupted. This is the default for ongoing sessions. Write only its smallest correct home; do not regenerate the startup mirror or perform full closeout.\n3. Full closeout: explicit end-of-session / handoff intent, a real day / tool-session boundary, or a state where the current agent cannot continue and the next agent must take over. Ordinary external-tool use, a completed release / governance subtask, or a durable note during an ongoing session is not by itself a full closeout trigger. Load `dev/rules/closeout.md` only when this tier is selected.\n\nRoute current objective, next action, active risk, blocker, and startup-needed facts to `dev/SESSION_HANDOFF.md`; chronological evidence to `dev/SESSION_LOG.md`; maps to `dev/PROJECT_INDEX.md`; sync obligations to `dev/DOC_SYNC_REGISTRY.md`; long-term rationale to `dev/PROJECT_DECISIONS.md`; and reusable procedures to the relevant pack, registered reference, or QA check. Do not store the same task contract or reusable rule in several homes.\n\nExternal effects are never implied permission for commit, push, publish, release, deployment, cleanup, or another workspace write. Record verified external impact through the relevant integrations, release, safety, and closeout contracts without exposing private content or secrets.\n\n## 2.2 Upgrade Completion\n\nThe CLI owns upgrade truth. An upgrade is complete only when:\n\n1. The root is not newer than the CLI and every target passes read-only classification.\n2. Conflict produces zero governance-target and version writes.\n3. Staged outputs pass the offline migration acceptance gate: root boundary, structure, cross-file invariants, preservation hashes, and version transition.\n4. The recoverable transaction commits without an unresolved journal; only a failure caused by this transaction triggers rollback.\n5. Whole-project `doctor` reports project health separately. Pre-existing or unrelated health failures do not convert a correct migration into a destructive rollback; new migration-caused blockers do.\n6. The migration report records attempted version, committed version, transaction state, actions, redacted reasons, and backup locations without credential values.\n\nDo not use \"upgrade completed\" to mean \"the entire project is healthy\". Report `migration committed` and `project health` separately. Conflict, incomplete recovery, failed migration acceptance, and future-version roots are not completed upgrades.\n\n## 3. Safety Baseline\n\nDo not delete, reset, overwrite user-owned content, bulk-move, publish, change permissions, or perform another irreversible or external action without the required explicit authorization.\n\nNamed prohibited destructive commands in `dev/rules/safety.md` remain prohibited even when requested. Never use a weaker pack or local instruction to bypass core safety.\n\nVerify the selected root and real target boundaries before writes. Do not follow a link, junction, mount, or computed path outside the confirmed root. Do not expose credential values in output, reports, backups, tests, or logs. Permission or lock failure is a stop condition, not permission to elevate or switch to a riskier command.\n\nDo not modify unrelated files or erase unexpected user changes. Do not claim completion without read-back evidence and proportionate checks.\n\n## 4. Closeout Trigger\n\nClear end-of-session or handoff intent such as \"收工\", \"Wrap up Agent Handoff\", \"closeout\", \"wrap up\", or \"handoff\" triggers full closeout, not a chat-only summary. Load `dev/rules/closeout.md` and follow its complete contract. `收工,記得 <handoff requirement>` and equivalent closeout-plus-instruction phrases are clear closeout intent. Ask one concise confirmation only when the phrase genuinely refers to an unrelated real-world closing or shift.\n\nThe always-enforced closeout invariants are:\n\n1. Current state lives in `dev/SESSION_HANDOFF.md`; trace evidence lives in `dev/SESSION_LOG.md`.\n2. Completed, pending, risk, validation, and opening-message lifecycle states agree.\n3. `START_NEXT_SESSION_PROMPT.txt` is regenerated from the sole authoritative handoff block and no third full copy is retained.\n4. Closeout is not complete until required files are written, read back, and the available closeout checks pass.\n5. After those checks, render the final card with `agent-handoff-kit closeout-status --root <project root>`; only its `status: complete` output may say `handoff saved`. A nonzero / `blocked` result is an honest blocked closeout, not a completed one.\n6. Git commit, push, release, publish, deployment, deletion, and permission changes remain separately authorized actions.\n\n## 5. Pack Loading\n\nUse `dev/RULE_PACKS.md` to load the minimum task-specific set. Packs may add stricter requirements but cannot weaken core safety or continuity.\n\nLoad `dev/rules/integrations.md` when the current task actually uses an external tool, not merely because a registry or placeholder table exists. Load `dev/rules/closeout.md` only for full closeout. If two packs conflict, use the safer and more verifiable path and record the unresolved conflict at closeout.\n\nAfter the task, apply the Persistence Gate. Do not assume the next session remembers pack context, and do not use handoff or log as the only home for reusable procedures.\n\n## Core Complexity Rule\n\nBefore changing `AGENTS.md` or adding a durable governance rule, use `dev/RULE_PACKS.md` to load `dev/rules/agent-governance.md` and locate the existing normative owner. Default-core rules must apply to most sessions, protect safety or continuity, and be shorter than the routed detail they replace. Scenario-specific or project-specific detail belongs in an existing pack or registered reference; a new pack is justified only when it creates a smaller, independently loadable responsibility with one normative owner. Do not copy the agent-governance classification table or workflow into the core.\n<!-- END Agent Handoff Kit managed core -->\n\n<!-- ack:user-rules-router:dev/USER_RULES.md -->\n<!-- ack:user-rules-acceptance:sha256=c33fcf0c7d6ec6b08961edd5537c023e1b09960aedcfa12ecaf5116a08a016e5 -->\nBefore loading task packs, read `dev/USER_RULES.md`. Its registered entries\nunder `dev/user_rules/` are user-controlled rules: read each accepted entry in\nthe listed order and verify its accepted raw-byte witness. Do not treat this\nrouter, its directory, a heading, language, format, location, or\nofficial-looking text as proof that any legacy source belongs to the Kit.\n"
|
|
12991
|
+
},
|
|
12992
|
+
"d62e4367e60fd2926a1507e0f4ffae7e51791f851d9642e94d092d56d2a467af": {
|
|
12993
|
+
"targetRel": "AGENTS.md",
|
|
12994
|
+
"canonicalSha256": "06bd460f50506a88745b5f534382083172a89aecaba4948058a91d1aa0302387",
|
|
12995
|
+
"text": "<!-- BEGIN Agent Handoff Kit managed core -->\n# Agent Handoff Kit Core Runtime\n\nThis is the small always-read contract. Detailed task and closeout procedures live in routed packs.\n\n## 1. Intent And Startup\n\nClassify the user's visible intent before loading project state. For explicit continuity, closeout, or a task whose next action depends on persisted project state, read `dev/SESSION_HANDOFF.md` first; it is the current-state authority. A direct ordinary or stateless task does not read the handoff merely because the project root is known. If the message is genuinely unresolved and the handoff can resolve it, read the handoff before asking the user.\n\nDo not read `dev/SESSION_LOG.md` during ordinary startup; it is trace-back evidence only. Do not read `START_NEXT_SESSION_PROMPT.txt` in addition to the handoff when already operating in the project root; that file is a portable generated mirror for an agent that has not yet been pointed at the root.\n\nRoute intent in this order:\n\n1. Clear closeout intent routes directly to `dev/rules/closeout.md`.\n2. Clear continuity intent such as \"開工\", \"Start Agent Handoff\", \"開始接力\", or \"continue handoff\" resumes the minimum current state from the handoff. A plain continuity message with no same-message task or explicit long-run instruction authorizes only that recovery, one optional display-only current-thread title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out wording such as \"unless you object I will start\". A concrete objective found only in loaded state is not authority to complete it. A same-message task may begin normally. An explicit instruction such as \"開工,繼續做到下一個 blocker\" or \"開工,繼續完成目前目標\" may continue under the normal task and safety rules.\n3. A direct ordinary task begins without a startup card or onboarding ceremony. Read only the sources and packs required by that task.\n4. Explicit guidance requests such as \"I'm new\", \"teach me\", \"help me start\", \"新手\", \"教我用\", or \"點開始\" may load `dev/rules/onboarding.md`. A fresh install or short message only makes guidance available; it never overrides a concrete objective. If no executable objective remains after state reading, ask one concise question or offer guided onboarding.\n\nTreat a phrase as ambiguous only when its ordinary meaning may genuinely refer to a real-world shift, event, or unrelated context. `開工,繼續 <task>`, `<project> 開工`, and `Start Agent Handoff and continue <task>` are continuity commands, not ambiguous phrases.\n\nDuring explicit continuity startup, the only optional presentation effect beyond state recovery and card/status is a user-visible task/conversation title update, when the active runtime safely supports current-thread title control. Current-title readback is useful when available to avoid overwriting an already informative title, but it is not required when the tool safely targets the calling/current thread. Do not title from the raw continuity trigger or before handoff-derived startup facts are final. First derive the startup card's current objective, risk/boundary, and recommended next action; then choose and apply any title update as the last presentation side effect before returning the startup response. Replace only a generic or stale title, or update once when the main objective clearly changes; keep an informative title when readback proves it is already relevant, and do not rename for tests, reviews, or small substeps. Use `<project name>|<primary action>` from facts already loaded for startup: a concrete same-message task first, otherwise the loaded current objective plus recommended next action. Within those facts, select one concrete primary action in this order: the same-message task; the loaded current objective; the recommended next action. The continuity trigger itself and generic phrases such as `Start Agent Handoff`, `開工`, `開始交接工作`, or `開始工作交接` are not primary actions. If the loaded facts do not provide both a concrete project name and a concrete primary action, skip the title update. Do not read `dev/PROJECT_INDEX.md`, files, network, or other state solely to name the title. The title must not contain progress, completion, status, task/session IDs, absolute paths, secrets, or unverified facts. If safe current-thread title control is unavailable, skip silently. The title is display-only; it is not project state, permission, progress, completion evidence, a health result, or a source of truth, and it does not authorize project/file writes, network activity, external task work, or continuation beyond the startup boundary.\n\nRead `dev/PROJECT_INDEX.md` when the task needs its file, command, integration, workspace, or source map. Read `dev/RULE_PACKS.md` when a task pack must be selected. Read `dev/DOC_SYNC_REGISTRY.md` before durable cross-file or external synchronization and during closeout. Pack loading is normally silent; explain it only when it changes risk, requires a user decision, or materially affects the next action.\n\nIf the user supplies the portable startup prompt, use it to locate the root, then trust the handoff over the mirror. If the root is unclear or mismatched, stop and ask for the intended root before reading or editing project state. Missing required governance files are a repair condition, not permission to invent a parallel structure.\n\nBefore a non-trivial task, identify and read the required local and external truth sources or mark them blocked. Reachable is not the same as ingested. Search hits, truncated output, summaries, and status claims do not replace the relevant source content.\n\nProbe an integration only immediately before a task uses it, when the handoff explicitly identifies it as a dependency for the current objective, or when the user requests an integration health check. `TBD`, examples, blank rows, and undeclared placeholders are not installed integrations. Record `Last Verified` only after a real probe and through the normal persistence gate. Never write integration status merely because a session started.\n\nShow the startup card only for explicit continuity startup. For a plain continuity message, show the card after the minimum state recovery and end the turn; its recommended next action is advice, not permission to act. An explicit same-message task or long-run continuation may combine the card with its first useful action. Direct ordinary tasks do not show the card. If onboarding is explicitly requested, combine any card and guidance in one response.\n\nFor explicit bare continuity startup, after the handoff is read, the startup card may read only the bounded version evidence from `dev/PROJECT_INDEX.md`: the unique stable-semver `| Agent Handoff Kit template version | X.Y.Z | ... |` row inside the unique real `## Stack` section. Do not route on, summarize, or load any other Project Index content for startup, title, permissions, packs, health, or task work. Missing, unreadable, malformed, duplicate, prerelease, or out-of-Stack-only version evidence prints `version unverified`; the turn remains status-only with zero writes. A direct ordinary or stateless task does not read the handoff or Project Index merely to fill a card or version.\n\n```text\n /\\_/\\ Agent Handoff Kit v<version>\n ( o.o ) continuity ready\n > ^ <\n\n🔎 交接狀態:<loaded / new install / resumed>\n📌 目前目標:<current objective>\n⚠️ 注意事項:<important boundary or none>\n🚀 推薦下一步:<one action + reason>\n```\n\nUse the full product name, plain user language, and one recommended next action. Never print the literal placeholder `v<version>`.\n\n## 2. Proportionate Work Loop\n\nApply PLAN → READ → CHANGE → QC internally and in proportion to task state and risk. Do not make the user watch governance ceremony that does not help the task.\n\nIn every user-facing reply, lead with ordinary language: state the result and its practical effect, then the next action when one helps. Put exact commands, errors, hashes, and detailed evidence after that; brevity must not hide uncertainty or safety risk.\n\n- Simple answers, pure conversation or creation with no durable state, and low-risk tasks with an obvious target may proceed directly with proportionate reading and checking.\n- Non-trivial work reads relevant sources before changing them.\n- High-risk work states scope, impact, acceptance, and required confirmation before writes.\n- External skill flows, subagents, task plans, demo workspaces, and another tool's finish step do not replace the active root's persistence decision.\n- Materially changed Markdown governance artifacts must be indexed, synchronized, consolidated into their authoritative home, or explicitly classified as temporary / one-time evidence. Other durable formats follow the same human governance rule, but the bundled doctor does not claim to scan them.\n\n## 2.1 Persistence Gate\n\nChoose exactly one tier after a task:\n\n1. No persistence: no durable fact was produced. One-off answers, transient output, active unapproved drafts, and routine rerunnable checks normally use this tier.\n2. Lightweight checkpoint: a durable fact affects future action while the session continues or may be interrupted. This is the default for ongoing sessions. Write only its smallest correct home; do not regenerate the startup mirror or perform full closeout.\n3. Full closeout: explicit end-of-session / handoff intent, a real day / tool-session boundary, or a state where the current agent cannot continue and the next agent must take over. Ordinary external-tool use, a completed release / governance subtask, or a durable note during an ongoing session is not by itself a full closeout trigger. Load `dev/rules/closeout.md` only when this tier is selected.\n\nRoute current objective, next action, active risk, blocker, and startup-needed facts to `dev/SESSION_HANDOFF.md`; chronological evidence to `dev/SESSION_LOG.md`; maps to `dev/PROJECT_INDEX.md`; sync obligations to `dev/DOC_SYNC_REGISTRY.md`; long-term rationale to `dev/PROJECT_DECISIONS.md`; and reusable procedures to the relevant pack, registered reference, or QA check. Do not store the same task contract or reusable rule in several homes.\n\nExternal effects are never implied permission for commit, push, publish, release, deployment, cleanup, or another workspace write. Record verified external impact through the relevant integrations, release, safety, and closeout contracts without exposing private content or secrets.\n\n## 2.2 Upgrade Completion\n\nThe CLI owns upgrade truth. An upgrade is complete only when:\n\n1. The root is not newer than the CLI and every target passes read-only classification.\n2. Conflict produces zero governance-target and version writes.\n3. Staged outputs pass the offline migration acceptance gate: root boundary, structure, cross-file invariants, preservation hashes, and version transition.\n4. The recoverable transaction commits without an unresolved journal; only a failure caused by this transaction triggers rollback.\n5. Whole-project `doctor` reports project health separately. Pre-existing or unrelated health failures do not convert a correct migration into a destructive rollback; new migration-caused blockers do.\n6. The migration report records attempted version, committed version, transaction state, actions, redacted reasons, and backup locations without credential values.\n\nDo not use \"upgrade completed\" to mean \"the entire project is healthy\". Report `migration committed` and `project health` separately. Conflict, incomplete recovery, failed migration acceptance, and future-version roots are not completed upgrades.\n\n## 3. Safety Baseline\n\nDo not delete, reset, overwrite user-owned content, bulk-move, publish, change permissions, or perform another irreversible or external action without the required explicit authorization.\n\nNamed prohibited destructive commands in `dev/rules/safety.md` remain prohibited even when requested. Never use a weaker pack or local instruction to bypass core safety.\n\nVerify the selected root and real target boundaries before writes. Do not follow a link, junction, mount, or computed path outside the confirmed root. Do not expose credential values in output, reports, backups, tests, or logs. Permission or lock failure is a stop condition, not permission to elevate or switch to a riskier command.\n\nDo not modify unrelated files or erase unexpected user changes. Do not claim completion without read-back evidence and proportionate checks.\n\n## 4. Closeout Trigger\n\nClear end-of-session or handoff intent such as \"收工\", \"Wrap up Agent Handoff\", \"closeout\", \"wrap up\", or \"handoff\" triggers full closeout, not a chat-only summary. Load `dev/rules/closeout.md` and follow its complete contract. `收工,記得 <handoff requirement>` and equivalent closeout-plus-instruction phrases are clear closeout intent. Ask one concise confirmation only when the phrase genuinely refers to an unrelated real-world closing or shift.\n\nThe always-enforced closeout invariants are:\n\n1. Current state lives in `dev/SESSION_HANDOFF.md`; trace evidence lives in `dev/SESSION_LOG.md`.\n2. Completed, pending, risk, validation, and opening-message lifecycle states agree.\n3. `START_NEXT_SESSION_PROMPT.txt` is regenerated from the sole authoritative handoff block and no third full copy is retained.\n4. Closeout is not complete until required files are written, read back, and the available closeout checks pass.\n5. After those checks, render the final card with `agent-handoff-kit closeout-status --root <project root>`; only its `status: complete` output may say `handoff saved`. A nonzero / `blocked` result is an honest blocked closeout, not a completed one.\n6. Git commit, push, release, publish, deployment, deletion, and permission changes remain separately authorized actions.\n\n## 5. Pack Loading\n\nUse `dev/RULE_PACKS.md` to load the minimum task-specific set. Packs may add stricter requirements but cannot weaken core safety or continuity.\n\nLoad `dev/rules/integrations.md` when the current task actually uses an external tool, not merely because a registry or placeholder table exists. Load `dev/rules/closeout.md` only for full closeout. If two packs conflict, use the safer and more verifiable path and record the unresolved conflict at closeout.\n\nAfter the task, apply the Persistence Gate. Do not assume the next session remembers pack context, and do not use handoff or log as the only home for reusable procedures.\n\n## Core Complexity Rule\n\nBefore changing `AGENTS.md` or adding a durable governance rule, use `dev/RULE_PACKS.md` to load `dev/rules/agent-governance.md` and locate the existing normative owner. Default-core rules must apply to most sessions, protect safety or continuity, and be shorter than the routed detail they replace. Scenario-specific or project-specific detail belongs in an existing pack or registered reference; a new pack is justified only when it creates a smaller, independently loadable responsibility with one normative owner. Do not copy the agent-governance classification table or workflow into the core.\n<!-- END Agent Handoff Kit managed core -->\n\n<!-- ack:user-rules-router:dev/USER_RULES.md -->\n<!-- ack:user-rules-acceptance:sha256=2abc4397c5dd83236fb9f77dad0a66414ffba8f188490e4ccd381abef07bbb3e -->\nBefore loading task packs, read `dev/USER_RULES.md`. Its registered entries\nunder `dev/user_rules/` are user-controlled rules: read each accepted entry in\nthe listed order and verify its accepted raw-byte witness. Do not treat this\nrouter, its directory, a heading, language, format, location, or\nofficial-looking text as proof that any legacy source belongs to the Kit.\n"
|
|
12996
|
+
},
|
|
12997
|
+
"44b4f01258bdf76c1478e5dc0b1e9d88d196bbb3ae790edd07497f0cca26b8bd": {
|
|
12998
|
+
"targetRel": "START_NEXT_SESSION_PROMPT.txt",
|
|
12999
|
+
"canonicalSha256": "ab27d779af955d419c0f4290bd85d9d842182be04570ffffb0a725331a6cf409",
|
|
13000
|
+
"text": "Work in <ROOT>.\n\nIf the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.\n\nResume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, one optional display-only current-thread title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out execution wording. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading."
|
|
13001
|
+
},
|
|
13002
|
+
"7a273d19af7f2e13fcf514f54d04815bba7cdaf2265af3ce80da168faeec84f7": {
|
|
13003
|
+
"targetRel": "dev/SESSION_HANDOFF.md",
|
|
13004
|
+
"canonicalSha256": "96b45a24a5eb0f39086e199a8eb36a5794f9595fe9253138e7a3c2eb99278178",
|
|
13005
|
+
"text": "# Session Handoff\n\nLast Updated: TBD\n\n<!-- ack:section:durable-anchors -->\n## Durable Anchors\n\nStable facts that should survive across sessions. Update only when they change, but verify they still match reality at closeout.\n\n1. Project root and boundary: TBD\n2. Product/system identity: TBD\n3. Governance model: TBD\n4. Source-of-truth ownership: TBD\n5. Release / publish boundary: TBD\n6. Installed Integrations registry: `dev/PROJECT_INDEX.md` `## Installed Integrations` is the declaration source. Probe only immediately before actual use, when the current objective names an integration dependency, or when the user asks for a health check. Credential values never appear in `dev/*`; record references only.\n\n<!-- ack:section:closeout-reconciled-state -->\n## Closeout-Reconciled State\n\nThis is the current-state area. At every full closeout, rewrite or explicitly confirm every section below. Do not append a new state snapshot under an old one.\n\n<!-- ack:section:current-baseline -->\n## Current Baseline\n\n1. Project root: TBD\n2. Product/system state: TBD\n3. Governance state: TBD\n4. Source-of-truth notes: TBD\n<!-- ack:field:first-use-guidance-state -->\n5. First-use guidance state: eligible\n\n<!-- ack:section:task-understanding-summary -->\n## Task Understanding Summary\n\n<!-- ack:field:user-intent -->\n- User intent: TBD\n<!-- ack:field:task-essence -->\n- Task essence: TBD\n- User value: TBD\n<!-- ack:field:success-criteria -->\n- Success criteria: TBD\n- Key background already read: TBD\n- Background still unread or blocked: TBD\n- Non-goals / boundaries: TBD\n\n<!-- ack:section:active-objective -->\n## Active Objective\n\nTBD\n\n<!-- ack:section:completed-this-session -->\n## Completed This Session\n\nRecord only work actually completed in the current session.\n\n1. TBD\n\n<!-- ack:section:next-priorities -->\n## Next Priorities\n\nRecommended next step: TBD — reason: TBD\n\n1. TBD\n\n<!-- ack:section:next-task-required-reading -->\n## Next Task Required Reading\n\nBefore acting on the next task, read or mark blocked:\n\n| Source | Why required | Status |\n|---|---|---|\n| TBD | TBD | pending |\n\n<!-- ack:section:risks-blockers -->\n## Risks / Blockers\n\n1. TBD\n\n<!-- ack:section:validation-qc -->\n## Validation / QC\n\n- Checks run this session: TBD\n- Checks not run and why: TBD\n- Handoff evidence location: TBD\n\n<!-- ack:section:workspace-identity -->\n## Workspace Identity\n\nExpected project root: TBD\nGit root: TBD\nBranch: TBD\nCommit: TBD\nWorktree / parallel workspace status: TBD\nUncommitted changes summary: TBD\n\n<!-- ack:section:sync-status -->\n## Sync Status\n\nUse statuses from `dev/DOC_SYNC_REGISTRY.md`: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.\n\n- Project index: TBD\n- Doc sync registry: TBD\n- Public docs / README: TBD\n- External knowledge tools: TBD\n\n<!-- ack:section:state-reconciliation-check -->\n## State Reconciliation Check\n\nAt full closeout, complete this check after updating the state sections above.\n\n- Reconciled at: TBD\n<!-- ack:field:state-sections-rewritten-or-confirmed -->\n- State sections rewritten or confirmed current: TBD\n<!-- ack:field:stale-snapshots-left -->\n- Stale snapshots left in this handoff: TBD\n<!-- ack:field:lifecycle-conflicts-resolved -->\n- Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD\n<!-- ack:field:persistence-routing-checked -->\n- Persistence routing checked: TBD\n<!-- ack:field:closeout-outcome -->\n- Closeout outcome: not_started — full closeout has not yet been assessed.\n<!-- ack:field:project-required-persistence -->\n- Project-required persistence: not_assessed — state whether this project's required Git or other persistence completed, is not required, or is blocked.\n<!-- ack:field:recommended-next-step-explicit -->\n- Recommended next step is explicit and reasoned: TBD\n<!-- ack:field:opening-message-matches-current-state -->\n- Opening message matches current state: TBD\n<!-- ack:field:next-ai-can-continue -->\n- Next AI can continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history: TBD\n\nIf any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready. `Closeout outcome: complete` is allowed only when required writes, read-backs and project-required persistence are complete. If project-required persistence is blocked, use `Closeout outcome: blocked` and state the blocker; it is not a completed closeout.\n\nLifecycle consistency rule: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message` as full content, including renamed or paraphrased work. 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. Doctor catches only mechanical contradictions and unresolved fields; its green result is not semantic proof. Recommended next-step rule: `Next Priorities` must name the single recommended next action and a short reason before listing additional options, unless the next action is blocked or genuinely requires a user decision. Persistence routing rule: one-time delivery instructions, historical validation evidence, old hashes, old version facts, and incident notes must stay in trace evidence unless they still affect the next action.\n\nCloseout-card rule: `closeout-status` reads only these existing handoff fields plus fresh doctor / mirror results; it does not create another persistence authority. Its `complete` card is the only permitted source for the user-facing `handoff saved` wording. A nonzero / `blocked` result must be shown as blocked, never summarized as completed.\n\n<!-- ack:section:handoff-sufficiency-check -->\n## Handoff Sufficiency Check\n\nCan the next AI continue from `AGENTS.md`, this handoff, and only the project index / rule packs required by the next task, without searching old log history?\n\nAnswer: TBD\nIf no, update this handoff before closeout.\n\nContinuity rule: this file carries current state and next action. `dev/SESSION_LOG.md` carries recent evidence only. Archive old detail only when needed; do not create an archive directory by default.\n\n<!-- ack:section:next-session-opening-message -->\n## Next Session Opening Message\n\nThis fenced block is the authoritative agent-managed startup content. At closeout, regenerate `START_NEXT_SESSION_PROMPT.txt` from this block. If the two differ, trust this block and rewrite the convenience copy. User-facing closeout output should show `Start Agent Handoff` / `開工` as the primary next-session entry, plus the path-bearing fallback when the next AI is not yet pointed at this project root; do not hand-write a separate stateful prompt in the final response.\n\n📋 Next session: agent-managed startup content below\n\n```text\nWork in <ROOT>.\n\nIf the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.\n\nResume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, one optional display-only current-thread title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out execution wording. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading.\n```\n"
|
|
13006
|
+
},
|
|
13007
|
+
"0d0c85ac4318670d9ffba85e46cc709ee3b0a9bcb0ad7586079859f98e0a1c72": {
|
|
13008
|
+
"targetRel": "dev/rules/closeout.md",
|
|
13009
|
+
"canonicalSha256": "45b8019de97dd730380af9c211da92b541580797a66694b9b4188bed49e999b6",
|
|
13010
|
+
"text": "# Closeout Pack\n\n## Scope\n\nThis pack is the single detailed contract for full Agent Handoff Kit closeout. Load it only for clear end-of-session or handoff intent. It does not authorize Git, release, publish, deployment, deletion, permission, or cleanup actions.\n\n## Required Reads\n\nRead the current `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, and `dev/DOC_SYNC_REGISTRY.md`. Read `dev/PROJECT_DECISIONS.md`, integration rules, or another pack only when its closeout trigger or the session's actual work requires it.\n\n## Write Contract\n\nUse Kit markers as machine boundaries: `ack:section:*`, `ack:field:*`, `ack:log-entry:start/end`, and managed-core BEGIN/END. Human headings may be localized; markers may not be removed or translated.\n\n- Current state, objective, recommended next action, active risk, blocker, required reading, workspace identity, and sync status belong in `dev/SESSION_HANDOFF.md`.\n- Chronological work and evidence disposition belong in `dev/SESSION_LOG.md`.\n- File / command / source / capability maps belong in `dev/PROJECT_INDEX.md`.\n- Recurring sync obligations belong in `dev/DOC_SYNC_REGISTRY.md`.\n- Long-term evolution, architectural rationale, and accumulated learning belong in `dev/PROJECT_DECISIONS.md` when triggered.\n- Reusable procedures belong in the relevant pack, registered reference, or QA check.\n- `START_NEXT_SESSION_PROMPT.txt` is generated only from the handoff opening-message block.\n\nDo not copy the full opening message into `dev/SESSION_LOG.md` or any third current governance file. The log records that the mirror was regenerated and verified, plus an evidence reference when useful.\n\n## Full Closeout\n\nFull closeout is differential. Reuse a completed task check only when its recorded root, task input, tool identity, commit / artifact identity, and required file hashes still match the current state. Do not rerun task QA that is already bound to unchanged identity. Do rerun checks affected by closeout writes, gates that are incomplete or indeterminate, closeout-specific checks, and the final `closeout-status` read-back. If a closeout attempt is interrupted, stopped, aborted, times out, or hits a spawn / transport error, resume at the first incomplete or indeterminate gate; do not restart from the beginning unless the root, input, tool identity, commit, artifact, or relevant hash changed.\n\n1. Reconcile `dev/SESSION_HANDOFF.md`; never append a new current-state snapshot beneath an old one. Verify durable anchors, then rewrite or explicitly confirm every closeout-reconciled section.\n2. Reconcile lifecycle state across `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. Completed or verified work cannot remain unresolved unless explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with its missing evidence or trigger.\n The bundled doctor is a mechanical floor for required lifecycle markers and readable sections only. The semantic lifecycle gate is `agent-handoff-kit closeout-status`; when it blocks, use its first `Resolved [...]` / `Carry-forward [...]` pair to repair the handoff, not a separate project workaround, repeated doctor runs, or a broader governance rewrite. Read all five sections as a whole before marking the lifecycle field resolved. For governance, release, or another project-defined high-risk completion, use the project's independent semantic review gate in addition to `closeout-status`.\n3. Make `Next Priorities` name one recommended next action and a short reason unless blocked or a real user decision is required.\n4. Complete the persistence-routing, handoff-sufficiency, `Closeout outcome`, and `Project-required persistence` fields. The next agent must be able to continue from `AGENTS.md`, the handoff, the project index when needed, and routed packs without searching old log history. `complete` is allowed only when all required writes/read-backs and any project-required persistence succeeded; use `not_required` only when that persistence is genuinely not required. If a required commit, push, release record, or equivalent persistence is blocked or not authorized, set both fields to `blocked` with the exact boundary.\n5. Add one concise log entry for work actually performed. Record evidence disposition and the prompt-mirror verification result; omit the full opening message by design.\n6. Update the project index and sync registry only when their owned maps or obligations changed. Record each applicable sync target as `confirmed`, `unverified`, `pending`, `blocked`, or `not_applicable`.\n7. Record the actual root, Git root, branch, commit, worktrees / parallel workspaces, uncommitted changes, and unresolved drift. Do not clean or change them without separate authorization.\n8. If the session used external tools or helper processes, apply the integrations and safety ownership rules. Close only task-owned resources. Retain shared, user-owned, other-agent-owned, system, or ambiguous resources unless separately authorized; state visibility limits.\n9. Run the short maintenance trigger check below and record its result in the log.\n10. Mark first-use guidance `consumed` after the first successfully completed task or first full closeout. Upgrade must never reset `consumed` or `not_applicable` to `eligible`.\n11. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the sole fenced handoff opening-message block. Run the project's fixed prompt-mirror checker or perform an equivalent anchored read-back that verifies marker, heading, fence, full-copy uniqueness, and normalized content equality.\n12. Run available project-specific closeout checks. Do not run a separate bundled `doctor`: the `closeout-status` command below performs the one required fresh doctor read-back. Do not treat an external update-check failure as local closeout failure. Fix state or mirror failures before claiming handoff ready.\n13. Run `agent-handoff-kit closeout-status --root <project root>` after the handoff and prompt read-back. It performs the one required fresh doctor read-back and its output is the only final card source: copy its status faithfully. A nonzero result means the closeout is blocked; do not replace it with a success summary.\n\n## Maintenance Trigger Check\n\nEvery full closeout runs this short check; full maintenance runs only when triggered.\n\n- SESSION_LOG: trigger when the main log reaches at least 11 entries, exceeds 1500 lines, or the 10-closeout backstop is due. Keep recent safety-buffer entries; collapse only content already absorbed by an authoritative home. Archive older raw entries to `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` and maintain `INDEX.md`. Port unique narrative before collapsing it.\n- PROJECT_DECISIONS: trigger when a decisions-like handoff section has at least 30 entries; retain the newest 8–22 in the hot tier and move older decisions into the decisions archive. Also write substantive task evolution, a multi-option architectural choice with rationale, or a cross-session learning when observed.\n- Backstop: every 10 closeouts, run the full long-term maintenance pass even when no semantic trigger is obvious. If the count cannot be determined confidently at the boundary, treat the backstop as due.\n\nIf no trigger applies, record one no-op reason. Handoff carries continuity; log and project decisions carry trace and long-term narrative.\n\n## Opening Message And Card\n\nThe handoff opening-message block is authoritative. It must name the absolute root, route the agent through `AGENTS.md` and the handoff, state the current objective and boundary, and avoid instructing the next agent to redo completed work. It must not require SESSION_LOG as an ordinary startup read.\n\nUse `agent-handoff-kit closeout-status --root <project root>` after the required read-backs. It renders the verified version when available and otherwise `version unverified`; never print the literal placeholder `v<version>`, hand-compose a substitute card, or use `handoff saved` unless the command reports `status: complete`.\n\n```text\n /\\_/\\ Agent Handoff Kit v<version>\n ( -.- ) handoff saved\n > ^ <\n\nstatus: complete\n✅ Done: <completed summary>\n🔎 QC: <validation summary>\n📌 Handoff: opening message ready\n⚠️ Boundary: <important boundary or none>\n```\n\nFor `status: blocked`, the command instead says `handoff blocked`; retain that status, blocker reason, and human explanation: `這不是失敗;只是還有事未保存、未提交、未驗證或需要處理。先照 Blocker 行處理,不要把本輪當作已完成交接。` Then give the short local-root entry `Start Agent Handoff` / `開工` and the path-bearing fallback for an agent not yet pointed at the root. Do not hand-compose a third stateful prompt in the final response.\n\n## Stop Conditions\n\nDo not claim closeout complete when any required write or read-back failed, lifecycle state conflicts remain, the mirror is stale or duplicated, the root is uncertain, mandatory sync is unclassified, `closeout-status` is nonzero, or required Git persistence was explicitly part of the project's closeout contract but did not succeed. State the exact blocker and leave the project in an honest resumable state.\n"
|
|
13011
|
+
},
|
|
13012
|
+
"effc2b7606f098d48cf46f0c1fcbd2f312f9dd2d804b194106bb421acbe89915": {
|
|
13013
|
+
"targetRel": "AGENTS.md",
|
|
13014
|
+
"canonicalSha256": "1f1d11ab484adefc8388bee2796720abb64adc708561bb4dbbf9860d366c9a9e",
|
|
13015
|
+
"text": "<!-- BEGIN Agent Handoff Kit managed core -->\n# Agent Handoff Kit Core Runtime\n\nThis is the small always-read contract. Detailed task and closeout procedures live in routed packs.\n\n## 1. Intent And Startup\n\nClassify the user's visible intent before loading project state. For explicit continuity, closeout, or a task whose next action depends on persisted project state, read `dev/SESSION_HANDOFF.md` first; it is the current-state authority. A direct ordinary or stateless task does not read the handoff merely because the project root is known. If the message is genuinely unresolved and the handoff can resolve it, read the handoff before asking the user.\n\nDo not read `dev/SESSION_LOG.md` during ordinary startup; it is trace-back evidence only. Do not read `START_NEXT_SESSION_PROMPT.txt` in addition to the handoff when already operating in the project root; that file is a portable generated mirror for an agent that has not yet been pointed at the root.\n\nRoute intent in this order:\n\n1. Clear closeout intent routes directly to `dev/rules/closeout.md`.\n2. Clear continuity intent such as \"開工\", \"Start Agent Handoff\", \"開始接力\", or \"continue handoff\" resumes the minimum current state from the handoff. A plain continuity message with no same-message task or explicit long-run instruction authorizes only that recovery, one optional display-only current-thread title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out wording such as \"unless you object I will start\". A concrete objective found only in loaded state is not authority to complete it. A same-message task may begin normally. An explicit instruction such as \"開工,繼續做到下一個 blocker\" or \"開工,繼續完成目前目標\" may continue under the normal task and safety rules.\n3. A direct ordinary task begins without a startup card or onboarding ceremony. Read only the sources and packs required by that task.\n4. Explicit guidance requests such as \"I'm new\", \"teach me\", \"help me start\", \"新手\", \"教我用\", or \"點開始\" may load `dev/rules/onboarding.md`. A fresh install or short message only makes guidance available; it never overrides a concrete objective. If no executable objective remains after state reading, ask one concise question or offer guided onboarding.\n\nTreat a phrase as ambiguous only when its ordinary meaning may genuinely refer to a real-world shift, event, or unrelated context. `開工,繼續 <task>`, `<project> 開工`, and `Start Agent Handoff and continue <task>` are continuity commands, not ambiguous phrases.\n\nDuring explicit continuity startup, the only optional presentation effect beyond state recovery and card/status is a user-visible task/conversation title update, when the active runtime safely supports current-thread title control. Current-title readback is useful when available to avoid overwriting an already informative title, but it is not required when the tool safely targets the calling/current thread. If title control is exposed only through a bounded runtime tool-discovery mechanism, use that discovery once with a narrow title/rename/current-thread query before deciding the control is unavailable; then call only the discovered safe current-thread title tool. Do not list or inspect unrelated threads solely for naming, and do not create, fork, navigate, message, archive, pin, or otherwise manage tasks as part of startup title naming. Do not title from the raw continuity trigger or before handoff-derived startup facts are final. First derive the startup card's current objective, risk/boundary, and recommended next action; then choose and apply any title update as the last presentation side effect before returning the startup response. Replace only a generic or stale title, or update once when the main objective clearly changes; keep an informative title when readback proves it is already relevant, and do not rename for tests, reviews, or small substeps. Use `<project name>|<primary action>` from facts already loaded for startup: a concrete same-message task first, otherwise the loaded current objective plus recommended next action. Within those facts, select one concrete primary action in this order: the same-message task; the loaded current objective; the recommended next action. The continuity trigger itself and generic phrases such as `Start Agent Handoff`, `開工`, `開始交接工作`, or `開始工作交接` are not primary actions. If the loaded facts do not provide both a concrete project name and a concrete primary action, skip the title update. Do not read `dev/PROJECT_INDEX.md`, files, network, or other state solely to name the title. The title must not contain progress, completion, status, task/session IDs, absolute paths, secrets, or unverified facts. If safe current-thread title control is unavailable after the bounded discovery above, skip silently. The title is display-only; it is not project state, permission, progress, completion evidence, a health result, or a source of truth, and it does not authorize project/file writes, network activity, external task work, or continuation beyond the startup boundary.\n\nRead `dev/PROJECT_INDEX.md` when the task needs its file, command, integration, workspace, or source map. Read `dev/RULE_PACKS.md` when a task pack must be selected. Read `dev/DOC_SYNC_REGISTRY.md` before durable cross-file or external synchronization and during closeout. Pack loading is normally silent; explain it only when it changes risk, requires a user decision, or materially affects the next action.\n\nIf the user supplies the portable startup prompt, use it to locate the root, then trust the handoff over the mirror. If the root is unclear or mismatched, stop and ask for the intended root before reading or editing project state. Missing required governance files are a repair condition, not permission to invent a parallel structure.\n\nBefore a non-trivial task, identify and read the required local and external truth sources or mark them blocked. Reachable is not the same as ingested. Search hits, truncated output, summaries, and status claims do not replace the relevant source content.\n\nProbe an integration only immediately before a task uses it, when the handoff explicitly identifies it as a dependency for the current objective, or when the user requests an integration health check. `TBD`, examples, blank rows, and undeclared placeholders are not installed integrations. Record `Last Verified` only after a real probe and through the normal persistence gate. Never write integration status merely because a session started.\n\nShow the startup card only for explicit continuity startup. For a plain continuity message, show the card after the minimum state recovery and end the turn; its recommended next action is advice, not permission to act. An explicit same-message task or long-run continuation may combine the card with its first useful action. Direct ordinary tasks do not show the card. If onboarding is explicitly requested, combine any card and guidance in one response.\n\nFor explicit bare continuity startup, after the handoff is read, the startup card may read only the bounded version evidence from `dev/PROJECT_INDEX.md`: the unique stable-semver `| Agent Handoff Kit template version | X.Y.Z | ... |` row inside the unique real `## Stack` section. Do not route on, summarize, or load any other Project Index content for startup, title, permissions, packs, health, or task work. Missing, unreadable, malformed, duplicate, prerelease, or out-of-Stack-only version evidence prints `version unverified`; the turn remains status-only with zero writes. A direct ordinary or stateless task does not read the handoff or Project Index merely to fill a card or version.\n\n```text\n /\\_/\\ Agent Handoff Kit v<version>\n ( o.o ) continuity ready\n > ^ <\n\n🔎 交接狀態:<loaded / new install / resumed>\n📌 目前目標:<current objective>\n⚠️ 注意事項:<important boundary or none>\n🚀 推薦下一步:<one action + reason>\n```\n\nUse the full product name, plain user language, and one recommended next action. Never print the literal placeholder `v<version>`.\n\n## 2. Proportionate Work Loop\n\nApply PLAN → READ → CHANGE → QC internally and in proportion to task state and risk. Do not make the user watch governance ceremony that does not help the task.\n\nIn every user-facing reply, lead with ordinary language: state the result and its practical effect, then the next action when one helps. Put exact commands, errors, hashes, and detailed evidence after that; brevity must not hide uncertainty or safety risk.\n\n- Simple answers, pure conversation or creation with no durable state, and low-risk tasks with an obvious target may proceed directly with proportionate reading and checking.\n- Non-trivial work reads relevant sources before changing them.\n- High-risk work states scope, impact, acceptance, and required confirmation before writes.\n- External skill flows, subagents, task plans, demo workspaces, and another tool's finish step do not replace the active root's persistence decision.\n- Materially changed Markdown governance artifacts must be indexed, synchronized, consolidated into their authoritative home, or explicitly classified as temporary / one-time evidence. Other durable formats follow the same human governance rule, but the bundled doctor does not claim to scan them.\n\n## 2.1 Persistence Gate\n\nChoose exactly one tier after a task:\n\n1. No persistence: no durable fact was produced. One-off answers, transient output, active unapproved drafts, and routine rerunnable checks normally use this tier.\n2. Lightweight checkpoint: a durable fact affects future action while the session continues or may be interrupted. This is the default for ongoing sessions. Write only its smallest correct home; do not regenerate the startup mirror or perform full closeout.\n3. Full closeout: explicit end-of-session / handoff intent, a real day / tool-session boundary, or a state where the current agent cannot continue and the next agent must take over. Ordinary external-tool use, a completed release / governance subtask, or a durable note during an ongoing session is not by itself a full closeout trigger. Load `dev/rules/closeout.md` only when this tier is selected.\n\nRoute current objective, next action, active risk, blocker, and startup-needed facts to `dev/SESSION_HANDOFF.md`; chronological evidence to `dev/SESSION_LOG.md`; maps to `dev/PROJECT_INDEX.md`; sync obligations to `dev/DOC_SYNC_REGISTRY.md`; long-term rationale to `dev/PROJECT_DECISIONS.md`; and reusable procedures to the relevant pack, registered reference, or QA check. Do not store the same task contract or reusable rule in several homes.\n\nExternal effects are never implied permission for commit, push, publish, release, deployment, cleanup, or another workspace write. Record verified external impact through the relevant integrations, release, safety, and closeout contracts without exposing private content or secrets.\n\n## 2.2 Upgrade Completion\n\nThe CLI owns upgrade truth. An upgrade is complete only when:\n\n1. The root is not newer than the CLI and every target passes read-only classification.\n2. Conflict produces zero governance-target and version writes.\n3. Staged outputs pass the offline migration acceptance gate: root boundary, structure, cross-file invariants, preservation hashes, and version transition.\n4. The recoverable transaction commits without an unresolved journal; only a failure caused by this transaction triggers rollback.\n5. Whole-project `doctor` reports project health separately. Pre-existing or unrelated health failures do not convert a correct migration into a destructive rollback; new migration-caused blockers do.\n6. The migration report records attempted version, committed version, transaction state, actions, redacted reasons, and backup locations without credential values.\n\nDo not use \"upgrade completed\" to mean \"the entire project is healthy\". Report `migration committed` and `project health` separately. Conflict, incomplete recovery, failed migration acceptance, and future-version roots are not completed upgrades.\n\n## 3. Safety Baseline\n\nDo not delete, reset, overwrite user-owned content, bulk-move, publish, change permissions, or perform another irreversible or external action without the required explicit authorization.\n\nNamed prohibited destructive commands in `dev/rules/safety.md` remain prohibited even when requested. Never use a weaker pack or local instruction to bypass core safety.\n\nVerify the selected root and real target boundaries before writes. Do not follow a link, junction, mount, or computed path outside the confirmed root. Do not expose credential values in output, reports, backups, tests, or logs. Permission or lock failure is a stop condition, not permission to elevate or switch to a riskier command.\n\nDo not modify unrelated files or erase unexpected user changes. Do not claim completion without read-back evidence and proportionate checks.\n\n## 4. Closeout Trigger\n\nClear end-of-session or handoff intent such as \"收工\", \"Wrap up Agent Handoff\", \"closeout\", \"wrap up\", or \"handoff\" triggers full closeout, not a chat-only summary. Load `dev/rules/closeout.md` and follow its complete contract. `收工,記得 <handoff requirement>` and equivalent closeout-plus-instruction phrases are clear closeout intent. Ask one concise confirmation only when the phrase genuinely refers to an unrelated real-world closing or shift.\n\nThe always-enforced closeout invariants are:\n\n1. Current state lives in `dev/SESSION_HANDOFF.md`; trace evidence lives in `dev/SESSION_LOG.md`.\n2. Completed, pending, risk, validation, and opening-message lifecycle states agree.\n3. `START_NEXT_SESSION_PROMPT.txt` is regenerated from the sole authoritative handoff block and no third full copy is retained.\n4. Closeout is not complete until required files are written, read back, and the available closeout checks pass.\n5. After those checks, render the final card with `agent-handoff-kit closeout-status --root <project root>`; only its `status: complete` output may say `handoff saved`. A nonzero / `blocked` result is an honest blocked closeout, not a completed one.\n6. Git commit, push, release, publish, deployment, deletion, and permission changes remain separately authorized actions.\n\n## 5. Pack Loading\n\nUse `dev/RULE_PACKS.md` to load the minimum task-specific set. Packs may add stricter requirements but cannot weaken core safety or continuity.\n\nLoad `dev/rules/integrations.md` when the current task actually uses an external tool, not merely because a registry or placeholder table exists. Load `dev/rules/closeout.md` only for full closeout. If two packs conflict, use the safer and more verifiable path and record the unresolved conflict at closeout.\n\nAfter the task, apply the Persistence Gate. Do not assume the next session remembers pack context, and do not use handoff or log as the only home for reusable procedures.\n\n## Core Complexity Rule\n\nBefore changing `AGENTS.md` or adding a durable governance rule, use `dev/RULE_PACKS.md` to load `dev/rules/agent-governance.md` and locate the existing normative owner. Default-core rules must apply to most sessions, protect safety or continuity, and be shorter than the routed detail they replace. Scenario-specific or project-specific detail belongs in an existing pack or registered reference; a new pack is justified only when it creates a smaller, independently loadable responsibility with one normative owner. Do not copy the agent-governance classification table or workflow into the core.\n<!-- END Agent Handoff Kit managed core -->\n\n<!-- ack:user-rules-router:dev/USER_RULES.md -->\n<!-- ack:user-rules-acceptance:sha256=526c61feaebd0e7fc43ae7e8ae658c081e7ef0dbd0d737a09ec908602d9e0aa6 -->\nBefore loading task packs, read `dev/USER_RULES.md`. Its registered entries\nunder `dev/user_rules/` are user-controlled rules: read each accepted entry in\nthe listed order and verify its accepted raw-byte witness. Do not treat this\nrouter, its directory, a heading, language, format, location, or\nofficial-looking text as proof that any legacy source belongs to the Kit.\n"
|
|
12641
13016
|
}
|
|
12642
13017
|
},
|
|
12643
|
-
"catalogDigestSha256": "
|
|
13018
|
+
"catalogDigestSha256": "34fabc6c379ddae9c06e85049722bb40f9be966895332962a8bd55057704d222"
|
|
12644
13019
|
}
|
package/package.json
CHANGED
|
@@ -95,6 +95,7 @@ Use this workflow when the user asks to write something into long-term governanc
|
|
|
95
95
|
- Confirm reusable operating procedure knowledge is not stored only in `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, or a decision narrative when it belongs in a pack or registered reference.
|
|
96
96
|
- Confirm long-term governance knowledge is promoted out of `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, and `START_NEXT_SESSION_PROMPT.txt` when it should survive log archive or prompt regeneration.
|
|
97
97
|
- For governance bridge work, confirm the target file, project index, sync registry, related workflow, handoff/log role split, and duplicate-source risk were all checked or explicitly marked not applicable.
|
|
98
|
+
- For governance bridge work, run bounded searches for the target path/name and the relevant artifact class or sync-change type across the project index, sync registry, related workflows, and current rule owners. If the target is tied to generated outputs, also inspect the workflow or production guide that creates those outputs. Search evidence is a check, not a second source of truth.
|
|
98
99
|
- Before claiming completion, apply the active root's core persistence gate and record the result only when that gate selects a checkpoint or full closeout; do not assume child or demo workspaces cover the parent/root workspace.
|
|
99
100
|
- For long-running projects, confirm `dev/PROJECT_DECISIONS.md` retains its four H2 sections in order (Evolution Timeline / Decisions Archive / Architecture Choices / Insights & Learnings) and that the closeout maintenance trigger check was recorded, with full maintenance applied where its trigger conditions were met.
|
|
100
101
|
|
package/packs/onboarding.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
## Scope
|
|
4
4
|
|
|
5
|
-
Use this transient pack for first-time Agent Handoff Kit users who request guidance, or when the user's first-task intent remains genuinely unresolved after reading the available project state.
|
|
5
|
+
Use this transient pack for first-time Agent Handoff Kit users after a fresh install, users who request guidance, or when the user's first-task intent remains genuinely unresolved after reading the available project state.
|
|
6
6
|
|
|
7
7
|
The goal is to help the user complete a small first task without requiring them to read README, guide pages, `AGENTS.md`, or internal Kit rules first. After the onboarding walk-through finishes, unload this pack and continue with the regular scenario pack such as coding, research, writing, knowledge, or integrations.
|
|
8
8
|
|
|
@@ -20,16 +20,16 @@ Load this pack when the user message contains an onboarding signal such as:
|
|
|
20
20
|
- vague project intent such as "I want to do a project"
|
|
21
21
|
- equivalent Chinese user phrases such as "新手", "教我用", "點開始", "能力", or "能做甚麼"
|
|
22
22
|
|
|
23
|
-
`I just installed` / "我剛安裝"
|
|
23
|
+
`I just installed` / "我剛安裝" is a first-use signal. When `SESSION_HANDOFF` says `First-use guidance state: eligible` and no executable objective remains, load this pack and give the first-use welcome. It does not override a same-message concrete task with enough material facts.
|
|
24
24
|
|
|
25
25
|
### Continuity startup boundary
|
|
26
26
|
|
|
27
|
-
`Start Agent Handoff` / "開工" starts continuity and reads the minimum current handoff state; it is not an onboarding signal. A plain startup stops after its status card and recommended next action; a loaded objective alone does not authorize work. A same-message concrete task may begin normally. Only when no executable objective remains after state reading should the AI ask one concise question or offer the guided onboarding path. Explicit requests such as "新手,教我用" enter onboarding directly.
|
|
27
|
+
`Start Agent Handoff` / "開工" starts continuity and reads the minimum current handoff state; it is not an onboarding signal by itself. A plain startup normally stops after its status card and recommended next action; a loaded objective alone does not authorize work. First-use eligible plain startup is the exception: when the handoff says `First-use guidance state: eligible`, the active objective is empty / `TBD`, and the user did not provide a same-message concrete task, enter onboarding instead of ending status-only. A same-message concrete task may begin normally. Only when no executable objective remains after state reading should the AI ask one concise question or offer the guided onboarding path. Explicit requests such as "新手,教我用" enter onboarding directly.
|
|
28
28
|
|
|
29
29
|
### Implicit signals
|
|
30
30
|
|
|
31
31
|
- The first user message is short and still genuinely vague after available project state is read.
|
|
32
|
-
- `SESSION_HANDOFF` first-use guidance state is `eligible`, Active Objective is empty
|
|
32
|
+
- `SESSION_HANDOFF` first-use guidance state is `eligible`, Active Objective is empty / `TBD`, and the user has not supplied a concrete objective with enough material facts. This is the fresh-install welcome path and should not be skipped as an ordinary status-only startup.
|
|
33
33
|
- The user asks a generic capability question instead of giving a concrete task.
|
|
34
34
|
- The user appears unfamiliar with the workflow, for example asking what the AI should do rather than giving an objective.
|
|
35
35
|
|
|
@@ -11,13 +11,13 @@ Do not read `dev/SESSION_LOG.md` during ordinary startup; it is trace-back evide
|
|
|
11
11
|
Route intent in this order:
|
|
12
12
|
|
|
13
13
|
1. Clear closeout intent routes directly to `dev/rules/closeout.md`.
|
|
14
|
-
2. Clear continuity intent such as "開工", "Start Agent Handoff", "開始接力", or "continue handoff" resumes the minimum current state from the handoff. A plain continuity message with no same-message task or explicit long-run instruction authorizes only that recovery, one optional display-only current-thread title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out wording such as "unless you object I will start". A concrete objective found only in loaded state is not authority to complete it. A same-message task may begin normally. An explicit instruction such as "開工,繼續做到下一個 blocker" or "開工,繼續完成目前目標" may continue under the normal task and safety rules.
|
|
14
|
+
2. Clear continuity intent such as "開工", "Start Agent Handoff", "開始接力", or "continue handoff" resumes the minimum current state from the handoff. A plain continuity message with no same-message task or explicit long-run instruction authorizes only that recovery, one optional display-only current-thread title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out wording such as "unless you object I will start". First-use exception: when `dev/SESSION_HANDOFF.md` says `First-use guidance state: eligible`, the active objective is empty / `TBD`, and there is no same-message concrete task, load `dev/rules/onboarding.md` and include a short first-use welcome plus the most relevant guided choices in the same response instead of ending status-only. A concrete objective found only in loaded state is not authority to complete it. A same-message task may begin normally. An explicit instruction such as "開工,繼續做到下一個 blocker" or "開工,繼續完成目前目標" may continue under the normal task and safety rules.
|
|
15
15
|
3. A direct ordinary task begins without a startup card or onboarding ceremony. Read only the sources and packs required by that task.
|
|
16
|
-
4. Explicit guidance requests such as "I'm new", "teach me", "help me start", "新手", "教我用", or "點開始" may load `dev/rules/onboarding.md`. A fresh install or short message only makes guidance available; it never overrides a concrete objective. If no executable objective remains after state reading, ask one concise question or offer guided onboarding.
|
|
16
|
+
4. Explicit guidance requests such as "I'm new", "teach me", "help me start", "新手", "教我用", or "點開始" may load `dev/rules/onboarding.md`. A fresh install marks first-use guidance as `eligible`, so the first unresolved startup must enter onboarding; upgrade must not reset `consumed` or `not_applicable` back to `eligible`. A short message in a non-eligible root only makes guidance available; it never overrides a concrete objective. If no executable objective remains after state reading, ask one concise question or offer guided onboarding.
|
|
17
17
|
|
|
18
18
|
Treat a phrase as ambiguous only when its ordinary meaning may genuinely refer to a real-world shift, event, or unrelated context. `開工,繼續 <task>`, `<project> 開工`, and `Start Agent Handoff and continue <task>` are continuity commands, not ambiguous phrases.
|
|
19
19
|
|
|
20
|
-
During explicit continuity startup, the only optional presentation effect beyond state recovery and card/status is a user-visible task/conversation title update, when the active runtime safely supports current-thread title control. Current-title readback is useful when available to avoid overwriting an already informative title, but it is not required when the tool safely targets the calling/current thread. Do not title from the raw continuity trigger or before handoff-derived startup facts are final. First derive the startup card's current objective, risk/boundary, and recommended next action; then choose and apply any title update as the last presentation side effect before returning the startup response. Replace only a generic or stale title, or update once when the main objective clearly changes; keep an informative title when readback proves it is already relevant, and do not rename for tests, reviews, or small substeps. Use `<project name>|<primary action>` from facts already loaded for startup: a concrete same-message task first, otherwise the loaded current objective plus recommended next action. Within those facts, select one concrete primary action in this order: the same-message task; the loaded current objective; the recommended next action. The continuity trigger itself and generic phrases such as `Start Agent Handoff`, `開工`, `開始交接工作`, or `開始工作交接` are not primary actions. If the loaded facts do not provide both a concrete project name and a concrete primary action, skip the title update. Do not read `dev/PROJECT_INDEX.md`, files, network, or other state solely to name the title. The title must not contain progress, completion, status, task/session IDs, absolute paths, secrets, or unverified facts. If safe current-thread title control is unavailable, skip silently. The title is display-only; it is not project state, permission, progress, completion evidence, a health result, or a source of truth, and it does not authorize project/file writes, network activity, external task work, or continuation beyond the startup boundary.
|
|
20
|
+
During explicit continuity startup, the only optional presentation effect beyond state recovery and card/status is a user-visible task/conversation title update, when the active runtime safely supports current-thread title control. Current-title readback is useful when available to avoid overwriting an already informative title, but it is not required when the tool safely targets the calling/current thread. If title control is exposed only through a bounded runtime tool-discovery mechanism, use that discovery once with a narrow title/rename/current-thread query before deciding the control is unavailable; then call only the discovered safe current-thread title tool. Do not list or inspect unrelated threads solely for naming, and do not create, fork, navigate, message, archive, pin, or otherwise manage tasks as part of startup title naming. Do not title from the raw continuity trigger or before handoff-derived startup facts are final. First derive the startup card's current objective, risk/boundary, and recommended next action; then choose and apply any title update as the last presentation side effect before returning the startup response. Replace only a generic or stale title, or update once when the main objective clearly changes; keep an informative title when readback proves it is already relevant, and do not rename for tests, reviews, or small substeps. Use `<project name>|<primary action>` from facts already loaded for startup: a concrete same-message task first, otherwise the loaded current objective plus recommended next action. Within those facts, select one concrete primary action in this order: the same-message task; the loaded current objective; the recommended next action. The continuity trigger itself and generic phrases such as `Start Agent Handoff`, `開工`, `開始交接工作`, or `開始工作交接` are not primary actions. If the loaded facts do not provide both a concrete project name and a concrete primary action, skip the title update. Do not read `dev/PROJECT_INDEX.md`, files, network, or other state solely to name the title. The title must not contain progress, completion, status, task/session IDs, absolute paths, secrets, or unverified facts. If safe current-thread title control is unavailable after the bounded discovery above, skip silently. The title is display-only; it is not project state, permission, progress, completion evidence, a health result, or a source of truth, and it does not authorize project/file writes, network activity, external task work, or continuation beyond the startup boundary.
|
|
21
21
|
|
|
22
22
|
Read `dev/PROJECT_INDEX.md` when the task needs its file, command, integration, workspace, or source map. Read `dev/RULE_PACKS.md` when a task pack must be selected. Read `dev/DOC_SYNC_REGISTRY.md` before durable cross-file or external synchronization and during closeout. Pack loading is normally silent; explain it only when it changes risk, requires a user decision, or materially affects the next action.
|
|
23
23
|
|
|
@@ -27,7 +27,7 @@ Before a non-trivial task, identify and read the required local and external tru
|
|
|
27
27
|
|
|
28
28
|
Probe an integration only immediately before a task uses it, when the handoff explicitly identifies it as a dependency for the current objective, or when the user requests an integration health check. `TBD`, examples, blank rows, and undeclared placeholders are not installed integrations. Record `Last Verified` only after a real probe and through the normal persistence gate. Never write integration status merely because a session started.
|
|
29
29
|
|
|
30
|
-
Show the startup card only for explicit continuity startup. For a plain continuity message, show the card after the minimum state recovery and end the turn; its recommended next action is advice, not permission to act. An explicit same-message task or long-run continuation may combine the card with its first useful action. Direct ordinary tasks do not show the card. If onboarding is explicitly requested, combine any card and guidance in one response.
|
|
30
|
+
Show the startup card only for explicit continuity startup. For a plain continuity message, show the card after the minimum state recovery and end the turn; its recommended next action is advice, not permission to act. The first-use exception above replaces that status-only stop with onboarding only when the handoff state is `eligible`, the objective is empty / `TBD`, and there is no same-message concrete task. An explicit same-message task or long-run continuation may combine the card with its first useful action. Direct ordinary tasks do not show the card. If onboarding is explicitly requested or first-use onboarding is triggered, combine any card and guidance in one response.
|
|
31
31
|
|
|
32
32
|
For explicit bare continuity startup, after the handoff is read, the startup card may read only the bounded version evidence from `dev/PROJECT_INDEX.md`: the unique stable-semver `| Agent Handoff Kit template version | X.Y.Z | ... |` row inside the unique real `## Stack` section. Do not route on, summarize, or load any other Project Index content for startup, title, permissions, packs, health, or task work. Missing, unreadable, malformed, duplicate, prerelease, or out-of-Stack-only version evidence prints `version unverified`; the turn remains status-only with zero writes. A direct ordinary or stateless task does not read the handoff or Project Index merely to fill a card or version.
|
|
33
33
|
|
|
@@ -6,7 +6,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
|
|
|
6
6
|
|
|
7
7
|
| Field | Value | Last verified |
|
|
8
8
|
|---|---|---|
|
|
9
|
-
| Agent Handoff Kit template version | 0.3.
|
|
9
|
+
| Agent Handoff Kit template version | 0.3.58 | current template version |
|
|
10
10
|
| Runtime | TBD | TBD |
|
|
11
11
|
| Framework | TBD | TBD |
|
|
12
12
|
| Package manager | TBD | TBD |
|
|
@@ -5,7 +5,7 @@ Read only the packs needed for the current task.
|
|
|
5
5
|
| Task signal | Pack | Purpose |
|
|
6
6
|
|---|---|---|
|
|
7
7
|
| Clear end-of-session or handoff intent: "收工" / "wrap up" / "closeout" / "handoff" / "Wrap up Agent Handoff", including closeout plus a handoff instruction | `dev/rules/closeout.md` | <!-- ack:route:closeout --> full closeout, lifecycle reconciliation, maintenance triggers, prompt regeneration, read-back, and honest stop conditions |
|
|
8
|
-
| Explicit onboarding requests: "I'm new" / "new user" / "teach me" / "help me start" / "how do I start" / "show me how" / "getting started" / "what can agent handoff kit do"; or genuinely unresolved intent after current state has been read. Also recognize equivalent Chinese phrases such as "新手", "教我用", "點開始", and "能力". A fresh install
|
|
8
|
+
| Explicit onboarding requests: "I'm new" / "new user" / "teach me" / "help me start" / "how do I start" / "show me how" / "getting started" / "what can agent handoff kit do"; or genuinely unresolved intent after current state has been read. Also recognize equivalent Chinese phrases such as "新手", "教我用", "點開始", and "能力". A fresh install with `First-use guidance state: eligible` enters onboarding when no executable objective remains; upgrade never resets consumed / not_applicable first-use state. `Start Agent Handoff` / "開工" is continuity. | `dev/rules/onboarding.md` | <!-- ack:route:onboarding --> infer when sufficient and begin a concrete task directly; ask one concise question or offer guided scenarios only when the user requests guidance or first-use state is eligible with no executable objective |
|
|
9
9
|
| Destructive file operations, shell writes, Git state changes, package managers, installers, deploy, release, cloud tools, external APIs, credentials, locked files, permission errors | `dev/rules/safety.md` | safety checks for data loss, external systems, secrets, and high-risk operations |
|
|
10
10
|
| Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |
|
|
11
11
|
| Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |
|
|
@@ -156,5 +156,5 @@ Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Tr
|
|
|
156
156
|
|
|
157
157
|
If the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.
|
|
158
158
|
|
|
159
|
-
Resume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, one optional display-only current-thread title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out execution wording. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules.
|
|
159
|
+
Resume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, one optional display-only current-thread title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out execution wording. First-use exception: when this handoff says `First-use guidance state: eligible`, the current objective is empty / `TBD`, and there is no same-message concrete task, load onboarding and include a short first-use welcome plus the most relevant guided choices in the same response instead of ending status-only. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. Upgrade never resets consumed / not_applicable first-use state back to eligible.
|
|
160
160
|
```
|
|
@@ -2,4 +2,4 @@ Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Tr
|
|
|
2
2
|
|
|
3
3
|
If the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.
|
|
4
4
|
|
|
5
|
-
Resume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, one optional display-only current-thread title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out execution wording. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules.
|
|
5
|
+
Resume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, one optional display-only current-thread title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out execution wording. First-use exception: when this handoff says `First-use guidance state: eligible`, the current objective is empty / `TBD`, and there is no same-message concrete task, load onboarding and include a short first-use welcome plus the most relevant guided choices in the same response instead of ending status-only. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. Upgrade never resets consumed / not_applicable first-use state back to eligible.
|