@adamchanadam/agent-handoff-kit 0.4.7 → 0.4.8

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 CHANGED
@@ -4,9 +4,14 @@
4
4
 
5
5
  **Your session relay baton.** Context engineering at its core: keep progress, key decisions, file locations and unfinished tasks in your project folder, so supported AI tools can pick up where the last one left off.
6
6
 
7
- Code version covered: `v0.4.7`. This guide includes updates that have not been released yet. Features available to download depend on the published version.
7
+ Code version covered: `v0.4.8`. This guide includes updates that have not been released yet. Features available to download depend on the published version.
8
8
 
9
- [![Agent Handoff Kit introduction video](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-promo-30s.gif)](https://youtu.be/RopbfBiSw1I)
9
+ [![Agent Handoff Kit introduction video](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-promo-30s.gif)](https://youtu.be/pjarJTP6nY4)
10
+
11
+ 🎬 Introduction videos (in Chinese):
12
+
13
+ - [Agent Handoff Kit: stable cross-session handoff for long-running agentic AI work](https://youtu.be/pjarJTP6nY4) (about 1 minute)
14
+ - [AI has memory, so why does it still need a handoff log?](https://youtu.be/8GtcDDTk6RI) (about 12 minutes)
10
15
 
11
16
  ## How this tool helps your project
12
17
 
package/README.md CHANGED
@@ -4,9 +4,14 @@
4
4
 
5
5
  **Session 接力棒**。以 context engineering(為 AI 準備它需要知道的背景資料)為核心,把進度、重要決定、文件位置和未完事項留在專案資料夾,讓支援的 AI 工具接手繼續工作。
6
6
 
7
- 文件對應程式版本:`v0.4.7`。這份說明包含尚未發布的更新;正式下載可用的功能,以已發布版本為準。
7
+ 文件對應程式版本:`v0.4.8`。這份說明包含尚未發布的更新;正式下載可用的功能,以已發布版本為準。
8
8
 
9
- [![Agent Handoff Kit 宣傳動畫](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-promo-30s.gif)](https://youtu.be/RopbfBiSw1I)
9
+ [![Agent Handoff Kit 宣傳動畫](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-promo-30s.gif)](https://youtu.be/pjarJTP6nY4)
10
+
11
+ 🎬 介紹影片:
12
+
13
+ - [\[開源\] Agent Handoff Kit - 令 Agentic AI 跨 Session 穩定地交接,長任務開發專用 (For Claude Code , Codex & more)](https://youtu.be/pjarJTP6nY4)(約 1 分鐘)
14
+ - [(Agent Handoff Kit) AI 有記憶,點解仲要交接簿?|嘆 AI 頻道 (03)](https://youtu.be/8GtcDDTk6RI)(約 12 分鐘)
10
15
 
11
16
  ## 這套工具怎樣幫你
12
17
 
@@ -1,5 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
 
3
+ import { runFootprintSupervised, formatFootprintLine } from "./footprint.mjs";
3
4
  import { spawnSync } from "node:child_process";
4
5
  import { createInterface } from "node:readline/promises";
5
6
  import { stdin as input, stdout as output } from "node:process";
@@ -665,11 +666,17 @@ async function main() {
665
666
  }
666
667
 
667
668
  async function runCloseoutStatus(root, version) {
669
+ let footprint;
670
+ const measure = async (worktrees) => {
671
+ try { footprint = await runFootprintSupervised(root); return formatFootprintLine(footprint, { worktrees }); }
672
+ catch { return "📦 Footprint: unavailable"; }
673
+ };
668
674
  let handoffText = "";
669
675
  try {
670
676
  handoffText = await readFile(path.join(root, "dev", "SESSION_HANDOFF.md"), "utf8");
671
677
  } catch {
672
- printCloseoutStatusCard(version, { ok: false, findings: ["current handoff is unreadable"] });
678
+ const footprintLine = await measure();
679
+ printCloseoutStatusCard(version, { ok: false, findings: ["current handoff is unreadable"], footprintLine });
673
680
  process.exitCode = 1;
674
681
  return;
675
682
  }
@@ -720,7 +727,8 @@ async function runCloseoutStatus(root, version) {
720
727
  ok: findings.length === 0,
721
728
  findings,
722
729
  details,
723
- maintenanceWarnings: discipline.ok ? [] : discipline.warnings
730
+ maintenanceWarnings: discipline.ok ? [] : discipline.warnings,
731
+ footprintLine: await measure(workspaceHealth.git === "yes" ? (workspaceHealth.worktreesVerified ? workspaceHealth.worktreeCount : "unverified") : undefined)
724
732
  };
725
733
  printCloseoutStatusCard(version, result);
726
734
  if (!result.ok) process.exitCode = 1;
@@ -1336,6 +1344,7 @@ function printCloseoutStatusCard(version, result) {
1336
1344
  console.log("🔎 QC: fresh doctor and opening-message mirror passed");
1337
1345
  console.log("📌 Handoff: opening message ready; next-session reception and recovery still required");
1338
1346
  console.log("⚠️ Boundary: none");
1347
+ if (result.footprintLine) console.log(result.footprintLine);
1339
1348
  for (const warning of result.maintenanceWarnings ?? []) console.log(`⚠️ Maintenance reminder: ${warning}`);
1340
1349
  return;
1341
1350
  }
@@ -1345,6 +1354,7 @@ function printCloseoutStatusCard(version, result) {
1345
1354
  console.log("status: blocked");
1346
1355
  console.log(`⚠️ Blocker: ${result.findings.join("; ")}`);
1347
1356
  for (const detail of result.details ?? []) console.log(` ${detail}`);
1357
+ if (result.footprintLine) console.log(result.footprintLine);
1348
1358
  for (const warning of result.maintenanceWarnings ?? []) console.log(`⚠️ Maintenance reminder: ${warning}`);
1349
1359
  console.log("💬 說明:這不是失敗;只是還有事未保存、未提交、未驗證或需要處理。先照 Blocker 行處理,不要把本輪當作已完成交接。");
1350
1360
  console.log("📌 Handoff: keep the current state resumable; do not call this closeout complete");
@@ -0,0 +1,280 @@
1
+ import * as defaultFs from 'node:fs/promises';
2
+ import path from 'node:path';
3
+ import { performance } from 'node:perf_hooks';
4
+ import { spawn } from 'node:child_process';
5
+ import { fileURLToPath } from 'node:url';
6
+
7
+ export const DEFAULT_FOOTPRINT_BUDGET_MS = 4000;
8
+
9
+ // A host that forbids child processes (for example a sandbox) reports EPERM or EACCES.
10
+ export const spawnFailureReason = error => ['EPERM', 'EACCES'].includes(error?.code) ? 'spawn-denied' : 'spawn-failed';
11
+
12
+ export async function collectFootprint(root, options = {}) {
13
+ const started = performance.now();
14
+ const result = { status: 'complete', files: 0, bytes: 0n, linksSkipped: 0, otherFilesystems: 0, unreadable: 0, changed: 0, identityUnchecked: 0, abandonedInFlight: 0, elapsedMs: 0, top: [] };
15
+ let active = 0, stopped = false, timedOut = false, limited = false, internal = false;
16
+ let limitReason;
17
+ const handles = new Set();
18
+ let wake = () => {};
19
+ let timer;
20
+ const tops = new Map();
21
+ try {
22
+ const fs = options.fs ?? defaultFs;
23
+ const budget = Number.isFinite(options.budgetMs) ? Math.max(0, options.budgetMs) : DEFAULT_FOOTPRINT_BUDGET_MS;
24
+ const limit = Number.isFinite(options.maxInFlight) ? Math.max(1, Math.floor(options.maxInFlight)) : 32;
25
+ const queueLimit = Number.isFinite(options.maxQueuedDirs) ? Math.max(0, Math.floor(options.maxQueuedDirs)) : 100000;
26
+ const deadline = started + budget;
27
+ const signal = () => { const fn = wake; wake = () => {}; fn(); };
28
+ const closing = new Set();
29
+ const close = dir => {
30
+ if (closing.has(dir)) return;
31
+ handles.add(dir); closing.add(dir); active++;
32
+ let promise;
33
+ try { promise = dir.close(); } catch { promise = Promise.reject(); }
34
+ Promise.resolve(promise).catch(() => {}).finally(() => { handles.delete(dir); closing.delete(dir); active--; signal(); });
35
+ };
36
+ const finishDeadline = () => { if (!stopped) { timedOut = true; stopped = true; signal(); } };
37
+ timer = setTimeout(finishDeadline, Math.max(0, deadline - performance.now()));
38
+ const expired = () => { if (performance.now() >= deadline) finishDeadline(); return stopped; };
39
+ // Synchronous throws indicate an invalid implementation, while promise rejections
40
+ // are ordinary filesystem errors. Every call, including realpath, is bounded.
41
+ const start = (method, args, done) => {
42
+ if (expired()) return false;
43
+ let promise;
44
+ try { promise = fs[method](...args); } catch { internal = true; stopped = true; signal(); return false; }
45
+ active++;
46
+ Promise.resolve(promise).then(value => {
47
+ if (!stopped && !expired()) done(null, value);
48
+ else if (method === 'opendir') close(value);
49
+ }, error => {
50
+ if (!stopped && !expired()) done(error);
51
+ }).catch(() => { if (!stopped) { internal = true; stopped = true; } }).finally(() => { active--; signal(); });
52
+ return true;
53
+ };
54
+ const wait = () => new Promise(resolve => { wake = resolve; });
55
+ const one = async (method, args) => {
56
+ let settled = false, error, value;
57
+ start(method, args, (e, v) => { error = e; value = v; settled = true; });
58
+ while (!settled && !stopped) await wait();
59
+ return { error, value };
60
+ };
61
+ const rootPath = path.resolve(root);
62
+ const rootStat = await one('lstat', [rootPath, { bigint: true }]);
63
+ if (!stopped) {
64
+ if (rootStat.error) {
65
+ if (rootStat.error.code === 'ENOENT') { result.status = 'skipped'; result.reason = 'root-missing'; }
66
+ else { result.status = 'skipped'; result.reason = 'root-unreadable'; }
67
+ } else if (rootStat.value.isSymbolicLink()) { result.status = 'skipped'; result.reason = 'root-link'; }
68
+ else if (!rootStat.value.isDirectory()) { result.status = 'skipped'; result.reason = 'root-not-directory'; }
69
+ else {
70
+ const real = await one('realpath', [rootPath]);
71
+ if (!stopped) {
72
+ if (real.error) { result.status = 'skipped'; result.reason = real.error.code === 'ENOENT' ? 'root-missing' : 'root-unreadable'; }
73
+ else {
74
+ const norm = p => process.platform === 'win32' ? path.resolve(p).toLowerCase() : path.resolve(p);
75
+ if (norm(real.value) !== norm(rootPath)) { result.status = 'skipped'; result.reason = 'root-alias'; }
76
+ else {
77
+ const lock = await one('lstat', [path.join(rootPath, 'dev', 'governance_migrations', '.upgrade.lock'), { bigint: true }]);
78
+ if (stopped) { /* deadline or internal error */ }
79
+ else if (!lock.error || lock.error.code !== 'ENOENT') {
80
+ result.status = 'skipped';
81
+ result.reason = lock.error ? 'upgrade-lock-unknown' : 'upgrade-lock';
82
+ } else {
83
+ const dirs = queueLimit ? [{ path: rootPath, top: null, dev: rootStat.value.dev, ino: rootStat.value.ino }] : [];
84
+ if (!queueLimit) { limited = true; limitReason = 'queue-limit'; stopped = true; }
85
+ const listings = [];
86
+ const errorEntry = e => { if (e?.code === 'ENOENT') result.changed++; else result.unreadable++; };
87
+ const stopLimit = reason => { limited = true; limitReason = reason; stopped = true; signal(); };
88
+ const addDir = item => { if (dirs.length >= queueLimit) stopLimit('queue-limit'); else dirs.push(item); };
89
+ // Each pending directory and listing occupies one slot; pending file stats use the rest.
90
+ while (!stopped) {
91
+ let progressed = false;
92
+ while (!stopped && active < limit) {
93
+ if (expired()) break;
94
+ let ready;
95
+ for (let i = listings.length - 1; i >= 0; i--) if (!listings[i].busy) { ready = listings[i]; break; }
96
+ if (dirs.length && handles.size + listings.filter(x => x.opening).length < limit) {
97
+ const dir = dirs.pop();
98
+ const slot = { ...dir, opening: true, busy: true }; listings.push(slot);
99
+ // Path APIs retain a check-to-open window; this is neither race-free containment nor a consistent snapshot.
100
+ start('lstat', [dir.path, { bigint: true }], (error, stat) => {
101
+ if (error) { listings.splice(listings.indexOf(slot), 1); errorEntry(error); return; }
102
+ if (!stat.isDirectory() || stat.isSymbolicLink()) { listings.splice(listings.indexOf(slot), 1); result.changed++; return; }
103
+ if (dir.dev !== stat.dev) { listings.splice(listings.indexOf(slot), 1); result.changed++; return; }
104
+ if (dir.ino === 0n && stat.ino === 0n) result.identityUnchecked++;
105
+ else if (dir.ino !== stat.ino) { listings.splice(listings.indexOf(slot), 1); result.changed++; return; }
106
+ const open = () => start('opendir', [dir.path, { bufferSize: 256 }], (e, handle) => {
107
+ if (e) { listings.splice(listings.indexOf(slot), 1); errorEntry(e); return; }
108
+ handles.add(handle); slot.handle = handle; slot.opening = false; slot.busy = false;
109
+ });
110
+ if (dir.path === rootPath) open();
111
+ else start('realpath', [dir.path], (e, actual) => {
112
+ if (e) { listings.splice(listings.indexOf(slot), 1); errorEntry(e); return; }
113
+ const expected = path.join(real.value, path.relative(rootPath, dir.path));
114
+ if (norm(actual) !== norm(expected)) { listings.splice(listings.indexOf(slot), 1); result.changed++; return; }
115
+ open();
116
+ });
117
+ });
118
+ progressed = true;
119
+ } else if (ready) {
120
+ ready.busy = true;
121
+ // Wrap handle operations as injected calls for the same deadline and accounting.
122
+ let promise;
123
+ try { promise = ready.handle.read(); } catch { internal = true; stopped = true; signal(); break; }
124
+ active++;
125
+ Promise.resolve(promise).then(entry => {
126
+ if (stopped || expired()) return;
127
+ ready.busy = false;
128
+ if (!entry) { listings.splice(listings.indexOf(ready), 1); close(ready.handle); return; }
129
+ if (entry.isSymbolicLink()) { result.linksSkipped++; return; }
130
+ if (!entry.isDirectory() && !entry.isFile()) return;
131
+ const entryPath = path.join(ready.path, entry.name);
132
+ const top = ready.top ?? (entry.isFile() ? '(root files)' : entry.name);
133
+ if (!tops.has(top)) {
134
+ if (tops.size >= 10000) { stopLimit('top-limit'); return; }
135
+ tops.set(top, { name: top, bytes: 0n, files: 0 });
136
+ }
137
+ start('lstat', [entryPath, { bigint: true }], (error, stat) => {
138
+ if (error) return errorEntry(error);
139
+ if (entry.isDirectory()) {
140
+ if (!stat.isDirectory() || stat.isSymbolicLink()) { result.changed++; return; }
141
+ // A directory on another device is a mount (for example a volume or network share), not project data.
142
+ if (stat.dev !== rootStat.value.dev) { result.otherFilesystems++; return; }
143
+ addDir({ path: entryPath, top, dev: stat.dev, ino: stat.ino });
144
+ } else {
145
+ if (!stat.isFile() || stat.isSymbolicLink()) { result.changed++; return; }
146
+ const item = tops.get(top); item.bytes += stat.size; item.files++;
147
+ result.bytes += stat.size; result.files++;
148
+ }
149
+ });
150
+ }, error => {
151
+ if (!stopped && !expired()) { listings.splice(listings.indexOf(ready), 1); close(ready.handle); errorEntry(error); }
152
+ }).catch(() => { if (!stopped) { internal = true; stopped = true; signal(); } }).finally(() => { active--; signal(); });
153
+ progressed = true;
154
+ } else break;
155
+ }
156
+ if (stopped || (!active && !dirs.length && !listings.length)) break;
157
+ if (!progressed || active) await wait();
158
+ }
159
+ for (const handle of handles) close(handle);
160
+ }
161
+ }
162
+ }
163
+ }
164
+ }
165
+ }
166
+ if (internal) { stopped = true; return { status: 'unavailable', abandonedInFlight: active }; }
167
+ if (timedOut) result.status = 'partial';
168
+ else if (limited || result.unreadable || result.changed) result.status = 'incomplete';
169
+ if (limited) result.reason = limitReason;
170
+ result.abandonedInFlight = active;
171
+ result.top = Array.from(tops.values()).filter(x => x.files > 0);
172
+ result.elapsedMs = performance.now() - started;
173
+ stopped = true;
174
+ return result;
175
+ } catch {
176
+ stopped = true;
177
+ return { status: 'unavailable', abandonedInFlight: active };
178
+ } finally { stopped = true; clearTimeout(timer); }
179
+ }
180
+
181
+ function safeName(value) {
182
+ const name = String(value);
183
+ if (/(?:[A-Fa-f0-9]{32,}|[A-Za-z0-9]{32,})/.test(name) || /^(?:sk-|ghp_|gho_|github_pat_|xox|AKIA|AIza|glpat-|npm_|eyJ)/i.test(name)) return '<redacted>';
184
+ const clean = name.replace(/[\p{Cc}\p{Cf}`]/gu, '?').replace(/~{3,}/g, '?').replace(/\s+/gu, ' ').trim();
185
+ return Array.from(clean).length > 40 ? Array.from(clean).slice(0, 39).join('') + '…' : clean;
186
+ }
187
+
188
+ export function formatFootprintLine(result, { worktrees } = {}) {
189
+ try {
190
+ const suffix = worktrees === 'unverified' || (Number.isInteger(worktrees) && worktrees >= 0) ? `; registered Git worktrees: ${worktrees}` : '';
191
+ const bounded = line => line.length + suffix.length > 300 ? line.slice(0, 299 - suffix.length).replace(/[\uD800-\uDBFF]$/, '') + '…' + suffix : line + suffix;
192
+ if (result.status === 'unavailable') return bounded(result.reason === 'spawn-denied' ? '📦 Footprint: unavailable (helper process not permitted)' : '📦 Footprint: unavailable');
193
+ if (result.status === 'skipped') {
194
+ const reasons = { 'root-unreadable': 'root is unreadable', 'root-link': 'root is a link', 'root-missing': 'root is missing', 'root-not-directory': 'root is not a directory', 'root-alias': 'root is an alias', 'upgrade-lock': 'upgrade lock present', 'upgrade-lock-unknown': 'upgrade lock state unknown' };
195
+ return bounded(`📦 Footprint: skipped (${reasons[result.reason] ?? 'unknown reason'})`);
196
+ }
197
+ const gib = (bytes, floor) => {
198
+ const scaled = BigInt(bytes) * 100n;
199
+ const divisor = 1073741824n;
200
+ const hundredths = floor ? scaled / divisor : (scaled + divisor / 2n) / divisor;
201
+ return `${hundredths / 100n}.${String(hundredths % 100n).padStart(2, '0')}`;
202
+ };
203
+ const files = Number(result.files).toLocaleString('en-US');
204
+ let line;
205
+ if (result.status === 'complete') {
206
+ const top = [...result.top].sort((a, b) => a.bytes === b.bytes ? String(a.name).localeCompare(String(b.name), 'en') : a.bytes > b.bytes ? -1 : 1).slice(0, 3);
207
+ const completeLine = () => `📦 Footprint (apparent): ${gib(result.bytes, false)} GiB / ${files} files` + (top.length ? `; largest: ${top.map(x => `${safeName(x.name)} ${gib(x.bytes, false)} GiB`).join(', ')}` : '');
208
+ line = completeLine();
209
+ const counters = [['linksSkipped', 'links skipped'], ['otherFilesystems', 'other filesystems skipped'], ['unreadable', 'unreadable'], ['changed', 'changed']].filter(([key]) => result[key]).map(([key, label]) => `; ${label}: ${result[key]}`).join('');
210
+ while (line.length + counters.length + suffix.length > 300 && top.length) { top.pop(); line = completeLine(); }
211
+ line += counters;
212
+ } else {
213
+ const reason = result.status === 'partial' ? 'scan stopped at the time limit' : result.reason === 'top-limit' ? 'too many top-level entries' : result.reason === 'queue-limit' ? 'queue limit reached' : result.unreadable ? 'some entries unreadable' : 'entries changed during scan';
214
+ line = `📦 Footprint (apparent): observed at least ${gib(result.bytes, true)} GiB / ${files} files; ${reason}`;
215
+ for (const [key, label] of [['linksSkipped', 'links skipped'], ['otherFilesystems', 'other filesystems skipped'], ['unreadable', 'unreadable'], ['changed', 'changed']]) if (result[key]) line += `; ${label}: ${result[key]}`;
216
+ }
217
+ return bounded(line);
218
+ } catch { return '📦 Footprint: unavailable'; }
219
+ }
220
+
221
+ const modulePath = fileURLToPath(import.meta.url);
222
+ const orderedTop = top => [...top].sort((a, b) => a.bytes === b.bytes ? String(a.name).localeCompare(String(b.name), 'en') : a.bytes > b.bytes ? -1 : 1).slice(0, 3);
223
+
224
+ export async function runFootprintSupervised(root, { budgetMs = DEFAULT_FOOTPRINT_BUDGET_MS, graceMs = 750, maxOutputBytes = 16384, execPath = process.execPath, childScript = modulePath, childArgs, onSpawn } = {}) {
225
+ return new Promise(resolve => {
226
+ let child, timer, settled = false, output = Buffer.alloc(0);
227
+ const done = value => {
228
+ if (settled) return;
229
+ settled = true; clearTimeout(timer);
230
+ if (child) {
231
+ child.removeListener('close', onExit);
232
+ child.stdout?.removeListener('data', onData);
233
+ child.stdout?.destroy();
234
+ try { child.kill('SIGKILL'); } catch {}
235
+ child.unref();
236
+ }
237
+ resolve(value);
238
+ };
239
+ const fail = reason => done({ status: 'unavailable', reason });
240
+ const onExit = () => fail('child-failed');
241
+ const onData = chunk => {
242
+ output = Buffer.concat([output, chunk]);
243
+ if (output.length > maxOutputBytes) return fail('output-too-large');
244
+ const end = output.indexOf(10);
245
+ if (end < 0) return;
246
+ try {
247
+ const value = JSON.parse(output.subarray(0, end).toString('utf8'));
248
+ const count = x => Number.isSafeInteger(x) && x >= 0;
249
+ const decimal = x => typeof x === 'string' && /^\d+$/.test(x);
250
+ if (!value || typeof value !== 'object' || !['complete', 'partial', 'incomplete', 'skipped', 'unavailable'].includes(value.status) ||
251
+ (value.reason !== undefined && typeof value.reason !== 'string') || !count(value.files) || !decimal(value.bytes) ||
252
+ !count(value.linksSkipped) || !count(value.otherFilesystems) || !count(value.unreadable) || !count(value.changed) ||
253
+ (value.status === 'complete' && (!Array.isArray(value.top) || value.top.length > 3 || !value.top.every(x => x && typeof x.name === 'string' && decimal(x.bytes) && count(x.files)))) ||
254
+ (value.status !== 'complete' && value.top !== undefined)) return fail('invalid-output');
255
+ value.bytes = BigInt(value.bytes);
256
+ if (value.top) value.top = value.top.map(x => ({ ...x, bytes: BigInt(x.bytes) }));
257
+ done(value);
258
+ } catch { fail('invalid-output'); }
259
+ };
260
+ try {
261
+ child = spawn(execPath, childArgs ?? [childScript, '--footprint-child', root, String(budgetMs)], { stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
262
+ child.on('error', error => fail(spawnFailureReason(error)));
263
+ onSpawn?.(child);
264
+ child.on('close', onExit);
265
+ child.stdout.on('data', onData);
266
+ child.stdout.on('error', () => fail('child-failed'));
267
+ timer = setTimeout(() => fail('timeout'), Math.max(0, budgetMs + graceMs));
268
+ } catch (error) { fail(spawnFailureReason(error)); }
269
+ });
270
+ }
271
+
272
+ const direct = process.argv[1] && (process.platform === 'win32'
273
+ ? path.resolve(process.argv[1]).toLowerCase() === path.resolve(modulePath).toLowerCase()
274
+ : path.resolve(process.argv[1]) === path.resolve(modulePath));
275
+ if (direct && process.argv[2] === '--footprint-child') {
276
+ const result = await collectFootprint(process.argv[3], { budgetMs: Number(process.argv[4]) });
277
+ const compact = { status: result.status, ...(result.reason ? { reason: result.reason } : {}), files: result.files ?? 0, bytes: String(result.bytes ?? 0n), linksSkipped: result.linksSkipped ?? 0, otherFilesystems: result.otherFilesystems ?? 0, unreadable: result.unreadable ?? 0, changed: result.changed ?? 0 };
278
+ if (result.status === 'complete') compact.top = orderedTop(result.top).map(x => ({ name: safeName(x.name), bytes: String(x.bytes), files: x.files }));
279
+ process.stdout.write(JSON.stringify(compact) + '\n');
280
+ }
@@ -8,7 +8,7 @@ import { commands, commandFiles } from './commands.mjs';
8
8
  // Source-to-delivery routing. Unknown new shipped modules must receive an owner.
9
9
  // QA stages/evidence are defined by the existing assurance gate, not runtime doctor.
10
10
  export const deliveredFeatureContracts = Object.freeze([
11
- {id:'installer',sources:['package.json','bin/agent-handoff-kit.mjs','bin/installed-file-contract.mjs','bin/official-origin-catalog.mjs','bin/migration-baselines/','bin/upgrade-inventory.mjs','bin/user-rules-router.mjs']},
11
+ {id:'installer',sources:['package.json','bin/agent-handoff-kit.mjs','bin/footprint.mjs','bin/installed-file-contract.mjs','bin/official-origin-catalog.mjs','bin/migration-baselines/','bin/upgrade-inventory.mjs','bin/user-rules-router.mjs']},
12
12
  {id:'shortcuts',sources:['bin/commands.mjs'],hosts:['claude','gemini','codex','antigravity'],nativeAcceptanceHosts:['codex'],nativeInvocationEntries:commands.map(({name})=>name)},
13
13
  {id:'dashboard',sources:['bin/progress/']},
14
14
  {id:'continuity',sources:['runtime-core/','bin/handoff-read.mjs','bin/prompt-mirror-core.mjs']},
@@ -18,7 +18,7 @@ export const deliveredFeatureContracts = Object.freeze([
18
18
  // These are delivery dependencies, not runtime ownership. They decide whether
19
19
  // a historical shortcut raw case can still describe the current package.
20
20
  export const packageInstallDependencyRoots=Object.freeze([
21
- 'package.json','bin/agent-handoff-kit.mjs','bin/commands.mjs','bin/installed-file-contract.mjs',
21
+ 'package.json','bin/agent-handoff-kit.mjs','bin/footprint.mjs','bin/commands.mjs','bin/installed-file-contract.mjs',
22
22
  'bin/official-origin-catalog.mjs','bin/migration-baselines/','bin/upgrade-inventory.mjs','bin/user-rules-router.mjs',
23
23
  'bin/handoff-read.mjs','bin/prompt-mirror-core.mjs','bin/progress/','runtime-core/','packs/'
24
24
  ]);
@@ -46,7 +46,7 @@ export function shortcutEntryDependencyRoots(entry){
46
46
  const sharedNativeShortcutRoots=Object.freeze(['bin/commands.mjs','runtime-core/','bin/installed-file-contract.mjs']);
47
47
  const shortcutEntryNativeRoots=Object.freeze({
48
48
  'handoff-kit-start':Object.freeze(['bin/handoff-read.mjs','packs/onboarding.md']),
49
- 'handoff-kit-close':Object.freeze(['bin/agent-handoff-kit.mjs','bin/prompt-mirror-core.mjs','packs/closeout.md','packs/safety.md']),
49
+ 'handoff-kit-close':Object.freeze(['bin/agent-handoff-kit.mjs','bin/footprint.mjs','bin/prompt-mirror-core.mjs','packs/closeout.md','packs/safety.md']),
50
50
  'handoff-kit-progress':Object.freeze(['bin/progress/']),
51
51
  'handoff-kit-align':Object.freeze(['packs/agent-governance.md']),
52
52
  'handoff-kit-onboard':Object.freeze(['packs/onboarding.md']),
@@ -15176,6 +15176,181 @@
15176
15176
  "canonicalSha256": "04602a68a6a0e54ceb244bb71fc026ed73f08c7e7b0c764561cbad2ec19692f5"
15177
15177
  }
15178
15178
  }
15179
+ },
15180
+ "0.4.7": {
15181
+ "source": {
15182
+ "npm": {
15183
+ "spec": "@adamchanadam/agent-handoff-kit@0.4.7",
15184
+ "shasum": "1aeaca37531fb67842b8853ea16c1eb18fa2f858",
15185
+ "integrity": "sha512-HKxpIiljNuBtfZe6MIREbvFluZeREQomwUod1dnlY9jcy1wSYJZ2j4UV5GLS/bvlZ81kx9pFYrzgVQmzoKhmFg==",
15186
+ "entryCount": 52,
15187
+ "gitHead": null
15188
+ },
15189
+ "git": {
15190
+ "tag": "v0.4.7",
15191
+ "directObject": "4ed2ddc37b5f07eb92b21aa7082d1b81052a190a",
15192
+ "peeledCommit": "11d6552afd31aa0897989674bec1e62d62041d5a",
15193
+ "commit": "11d6552afd31aa0897989674bec1e62d62041d5a"
15194
+ },
15195
+ "githubRelease": {
15196
+ "tag": "v0.4.7",
15197
+ "publishedAt": "2026-11-15T20:07:33Z"
15198
+ },
15199
+ "sourceDivergence": {
15200
+ "status": "npm-gitHead-unavailable",
15201
+ "npmGitHead": null,
15202
+ "remoteTagCommit": "11d6552afd31aa0897989674bec1e62d62041d5a"
15203
+ }
15204
+ },
15205
+ "manifest": {
15206
+ "AGENTS.md": {
15207
+ "state": "present",
15208
+ "contentId": "30ef7a1231e33c4114083d0bdcd2bbf9f6c837193ef992599ac906dd8d255af9",
15209
+ "rawSha256": "e210982b35b63bb6c9c76637760e2edaacd3584bf4bf84a32d40f96d0bd824a3",
15210
+ "normalizedSha256": "2deb8124f33377b16c07c71beb525e9e2523891be7d2386a948787c1f4a1b09a",
15211
+ "canonicalSha256": "2deb8124f33377b16c07c71beb525e9e2523891be7d2386a948787c1f4a1b09a"
15212
+ },
15213
+ "CLAUDE.md": {
15214
+ "state": "present",
15215
+ "contentId": "7a2cf08a1171762ebcb53f43036a2170655379416945258b9c85d4b189ecaecf",
15216
+ "rawSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad",
15217
+ "normalizedSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad",
15218
+ "canonicalSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad"
15219
+ },
15220
+ "GEMINI.md": {
15221
+ "state": "present",
15222
+ "contentId": "36da47034bb2ce6c760ddbbbbd49dccc1d17665dbb18bec56ffa3b26bac1c135",
15223
+ "rawSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986",
15224
+ "normalizedSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986",
15225
+ "canonicalSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986"
15226
+ },
15227
+ "START_NEXT_SESSION_PROMPT.txt": {
15228
+ "state": "present",
15229
+ "contentId": "9902b70a395688d6602b34f9e8085b32b5538e72c9009e28b4258e1fd30b77cc",
15230
+ "rawSha256": "781ee0161704582fc2aa653bf7eea0245eb4151fd9389fadf14a798cf50179eb",
15231
+ "normalizedSha256": "781ee0161704582fc2aa653bf7eea0245eb4151fd9389fadf14a798cf50179eb",
15232
+ "canonicalSha256": "9896feb18fe71a4f3500e2d89cea6991ca1788aebc6c6ead9848f5551750a1c0"
15233
+ },
15234
+ "dev/SESSION_HANDOFF.md": {
15235
+ "state": "present",
15236
+ "contentId": "73afc36c2bcfc236bc694af6ed5183637cef1e1089c80a0dc2c1a1a7214ca5c2",
15237
+ "rawSha256": "205d635f9ea8ab137ca0a448a58c80b7fe064a46ab141de8c06b2a911dc6a5c6",
15238
+ "normalizedSha256": "205d635f9ea8ab137ca0a448a58c80b7fe064a46ab141de8c06b2a911dc6a5c6",
15239
+ "canonicalSha256": "882588e529835a84071fbbdddab70324392c9bcbb206d9dc2c804ac01108197f"
15240
+ },
15241
+ "dev/SESSION_LOG.md": {
15242
+ "state": "present",
15243
+ "contentId": "fa77d46a61f58e2fabc537b5c6ff31c33eb4413088797e87bf1b442ddec291c5",
15244
+ "rawSha256": "8da41cb8b8e766f40e8ab4365c32e9b6be6cc9265dc22d18bbbe75e8ad771cbd",
15245
+ "normalizedSha256": "8da41cb8b8e766f40e8ab4365c32e9b6be6cc9265dc22d18bbbe75e8ad771cbd",
15246
+ "canonicalSha256": "8da41cb8b8e766f40e8ab4365c32e9b6be6cc9265dc22d18bbbe75e8ad771cbd"
15247
+ },
15248
+ "dev/PROJECT_INDEX.md": {
15249
+ "state": "present",
15250
+ "contentId": "c4c0db7c6e7a19796cd7ca1ed2a666461aa49a0b0d087a99deca43853ffdb468",
15251
+ "rawSha256": "0ae48fff9297a2fe2ea2641925066c8dc95bfe517d85af8b3aeb866292bb8b72",
15252
+ "normalizedSha256": "a12063c0ffbb96e25e0e317a1f50705cf1a4655f240e49e75cfa42fb9d87230f",
15253
+ "canonicalSha256": "d13af58d29f15710e54469e929847a611a066f286198feeebada13192404141c"
15254
+ },
15255
+ "dev/DOC_SYNC_REGISTRY.md": {
15256
+ "state": "present",
15257
+ "contentId": "4c9f768eda712b65a04372059ea937864da01083346d007808cd935cc4825829",
15258
+ "rawSha256": "d32534a19c1247705c05431a30d1d294222faf372c0b777cfc087a7a52fb98ac",
15259
+ "normalizedSha256": "d32534a19c1247705c05431a30d1d294222faf372c0b777cfc087a7a52fb98ac",
15260
+ "canonicalSha256": "d32534a19c1247705c05431a30d1d294222faf372c0b777cfc087a7a52fb98ac"
15261
+ },
15262
+ "dev/RULE_PACKS.md": {
15263
+ "state": "present",
15264
+ "contentId": "1b91985b9c6460b7bf4293cc6119097df9b426c3a46199a0a4f1de1712d02faa",
15265
+ "rawSha256": "383842f3d2f995a6f0917bb4a7bc6bfa5fd6e3c33ec8aa2cd073ce1695812df4",
15266
+ "normalizedSha256": "383842f3d2f995a6f0917bb4a7bc6bfa5fd6e3c33ec8aa2cd073ce1695812df4",
15267
+ "canonicalSha256": "383842f3d2f995a6f0917bb4a7bc6bfa5fd6e3c33ec8aa2cd073ce1695812df4"
15268
+ },
15269
+ "dev/PROJECT_DECISIONS.md": {
15270
+ "state": "present",
15271
+ "contentId": "23daf5c72689add04511e62f8d7c354706b7c302a0188c7d0cf2e8cbcfc301d3",
15272
+ "rawSha256": "6d41cfe8799cad57587d75458b086434abb842ac91b72274b432454c710546b5",
15273
+ "normalizedSha256": "6d41cfe8799cad57587d75458b086434abb842ac91b72274b432454c710546b5",
15274
+ "canonicalSha256": "6d41cfe8799cad57587d75458b086434abb842ac91b72274b432454c710546b5"
15275
+ },
15276
+ "dev/rules/safety.md": {
15277
+ "state": "present",
15278
+ "contentId": "7fff6b3893d37bb1b8e1a6321048722de29919b5e75725258cfe119f1f77b1a0",
15279
+ "rawSha256": "8faf7411fc5d4c699f06f4bbf00fae105ad8a5a624371ff15f95d7c0c14128c9",
15280
+ "normalizedSha256": "8faf7411fc5d4c699f06f4bbf00fae105ad8a5a624371ff15f95d7c0c14128c9",
15281
+ "canonicalSha256": "8faf7411fc5d4c699f06f4bbf00fae105ad8a5a624371ff15f95d7c0c14128c9"
15282
+ },
15283
+ "dev/rules/coding.md": {
15284
+ "state": "present",
15285
+ "contentId": "199f77f66ca752ff9bc0750b7230657a05a9bd6e2cb70a299c42171016bc2738",
15286
+ "rawSha256": "0bb2ee2940f778710b5df15f4151ee571438c1100f7198c74886eaefdb3fd50d",
15287
+ "normalizedSha256": "0bb2ee2940f778710b5df15f4151ee571438c1100f7198c74886eaefdb3fd50d",
15288
+ "canonicalSha256": "0bb2ee2940f778710b5df15f4151ee571438c1100f7198c74886eaefdb3fd50d"
15289
+ },
15290
+ "dev/rules/writing.md": {
15291
+ "state": "present",
15292
+ "contentId": "ceee5412520ba860e6b40de46bb164e2ce3919d2197d5fadb926198eb7dddd3b",
15293
+ "rawSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593",
15294
+ "normalizedSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593",
15295
+ "canonicalSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593"
15296
+ },
15297
+ "dev/rules/research.md": {
15298
+ "state": "present",
15299
+ "contentId": "4414f9c82c6d04ad49d7446f4b0740055242f425ef5b00391d9c8c78c96c0f66",
15300
+ "rawSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104",
15301
+ "normalizedSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104",
15302
+ "canonicalSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104"
15303
+ },
15304
+ "dev/rules/agent-governance.md": {
15305
+ "state": "present",
15306
+ "contentId": "c0d63d30bd1be62f11ceb5146c4716a8b8eb61dd5d9aa34518196de528333cea",
15307
+ "rawSha256": "882780d38aae36d1693f65ba24ecfe6a3c7ee000d2875e2abb2508a13f4f7679",
15308
+ "normalizedSha256": "882780d38aae36d1693f65ba24ecfe6a3c7ee000d2875e2abb2508a13f4f7679",
15309
+ "canonicalSha256": "882780d38aae36d1693f65ba24ecfe6a3c7ee000d2875e2abb2508a13f4f7679"
15310
+ },
15311
+ "dev/rules/release.md": {
15312
+ "state": "present",
15313
+ "contentId": "b0a0c9dea88016185f4093f9be4ce3c0e29904222e21dd1fa1735fcc1bb7e744",
15314
+ "rawSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7",
15315
+ "normalizedSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7",
15316
+ "canonicalSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7"
15317
+ },
15318
+ "dev/rules/knowledge.md": {
15319
+ "state": "present",
15320
+ "contentId": "44d90de2a8a9230ee761934ff02a9ba91eb5dff4e649031cf1eb2d6e99d907af",
15321
+ "rawSha256": "401027a04c28e05d816005c63bfd0114ad470ac3f831182c1352fc833a3ad30f",
15322
+ "normalizedSha256": "401027a04c28e05d816005c63bfd0114ad470ac3f831182c1352fc833a3ad30f",
15323
+ "canonicalSha256": "401027a04c28e05d816005c63bfd0114ad470ac3f831182c1352fc833a3ad30f"
15324
+ },
15325
+ "dev/rules/communication.md": {
15326
+ "state": "present",
15327
+ "contentId": "34fd0034cbc75dad43f789b86a414763f01916dda4d59876db9c4d8d92ae6a87",
15328
+ "rawSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591",
15329
+ "normalizedSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591",
15330
+ "canonicalSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591"
15331
+ },
15332
+ "dev/rules/closeout.md": {
15333
+ "state": "present",
15334
+ "contentId": "f5b2c1e170be714bd4f5a0debef7ec04f74daba9ab57d88525db1e6da2ba1881",
15335
+ "rawSha256": "854c6480f632d22df435455f782bf96760693362ff394bf8aa1d321e7a7512e4",
15336
+ "normalizedSha256": "854c6480f632d22df435455f782bf96760693362ff394bf8aa1d321e7a7512e4",
15337
+ "canonicalSha256": "854c6480f632d22df435455f782bf96760693362ff394bf8aa1d321e7a7512e4"
15338
+ },
15339
+ "dev/rules/onboarding.md": {
15340
+ "state": "present",
15341
+ "contentId": "ce2b623d5f0d79ed1a471abd788da11c043f15bb823a9a40c7e1e79079db649d",
15342
+ "rawSha256": "8c5f81d3a15a79310a82c63ed62ae4a4113db2ce7d70e4e247bfa784fa6f6927",
15343
+ "normalizedSha256": "8c5f81d3a15a79310a82c63ed62ae4a4113db2ce7d70e4e247bfa784fa6f6927",
15344
+ "canonicalSha256": "8c5f81d3a15a79310a82c63ed62ae4a4113db2ce7d70e4e247bfa784fa6f6927"
15345
+ },
15346
+ "dev/rules/integrations.md": {
15347
+ "state": "present",
15348
+ "contentId": "600c2dc327a7435ce83f420292aa2d63e5a4ef6d8e777d24c218dc269c06aa3c",
15349
+ "rawSha256": "04602a68a6a0e54ceb244bb71fc026ed73f08c7e7b0c764561cbad2ec19692f5",
15350
+ "normalizedSha256": "04602a68a6a0e54ceb244bb71fc026ed73f08c7e7b0c764561cbad2ec19692f5",
15351
+ "canonicalSha256": "04602a68a6a0e54ceb244bb71fc026ed73f08c7e7b0c764561cbad2ec19692f5"
15352
+ }
15353
+ }
15179
15354
  }
15180
15355
  },
15181
15356
  "contents": {
@@ -16288,6 +16463,11 @@
16288
16463
  "targetRel": "AGENTS.md",
16289
16464
  "canonicalSha256": "870a89f1e09a11a9e058ab0bf04dd99dfc87d5ec5f62f69ff0dfa424649e06fe",
16290
16465
  "text": "<!-- BEGIN Agent Handoff Kit managed core -->\n# Agent Handoff Kit Core Runtime\n\n## 1. Intent And Startup\n\n### Upgrade lock guard\n\nBefore any handoff, user-rule router, pack, or other project-state read, use the verified project root to probe `dev/governance_migrations/.upgrade.lock`. A present lock, or inability to establish its absence, stops ordinary work and all further project-state reads and searches. Do not search for recovery instructions or edit or delete the lock. Before that explanation, render this fenced brand card:\n\n```text\n /\\_/\\ Agent Handoff Kit\n ( x.x ) continuity unavailable\n > ^ <\n```\n\nIt must not claim loaded, healthy, saved, or version-verified state. Explain that continuity is unavailable and give the supported recovery command `agent-handoff-kit upgrade --yes --root <verified-project-root>`. Bare startup never runs this command automatically. If the existence probe is unreadable, report continuity unavailable without claiming a lock is present and do not auto-recover. When the visible user request explicitly authorizes update, upgrade or recovery, only the official CLI performs transaction recovery; resume ordinary state loading only after that CLI succeeds and a new probe establishes lock absence.\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\nWhen resuming, recover the parent outcome, current step, resume point, remaining acceptance and source coverage from the fully received handoff under the checkpoint below. Preserve decision-changing user corrections, rejected approaches and their reasons, reusable work and permission boundaries. Surface missing critical context in the startup warning and recommend the specific clarification/read; do not infer parent completion from a finished child or treat previous-session reading as your own. Bare startup remains status-only, with no extra source reads or writes.\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, the display-only current-thread naming checkpoint 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.\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 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.\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\n### Handoff reception and recovery checkpoint\n\nBefore claiming `loaded`, `resumed` or `continuity ready`, complete both gates below. A successful closeout, read command, exit code, digest, section list or summary does not establish reception or understanding.\n\n1. **Receive the whole packet.** Read all of `dev/SESSION_HANDOFF.md`, including its middle and end, from one unchanged file version. A full-file command is only a request: inspect the actual tool result. If output is truncated, omitted, paginated or uncertain, use smaller bounded reads and track contiguous ranges from the start through EOF, with no gaps or mixed versions. Check the entire returned body, not just its header/footer; a tool can retain both ends while omitting the middle. Reread any uncertain range. If the file changes during reading, restart coverage for the new version. Native file tools are valid; compare file identity before/after the read sequence. When an already-available local Kit CLI supports it, `handoff-read --root <root>` offers bounded Unicode ranges; continue with its `nextOffset` as `--offset` and the same `--sha256`, reducing `--max-chars` on truncation. Verify its canonical `root` matches the intended workspace; a root alias is not permission to read an unexpected location. Links below that root are rejected. This helper serves content only. Do not download, install, probe integrations or write a receipt for bare startup. Missing/unreadable content stays incomplete.\n2. **Recover the work.** From that packet, reconcile the user's outcome and consumer, current task's relation to it, completed work and reusable evidence, decision reasons and rejected approaches, remaining obligations/acceptance, exact bounded next action, required fresh sources, and authorization/stop boundaries. Preserve corrections and distinguish historical state from current truth. Use existing section locations as internal evidence; do not create another summary file or dump the packet into the reply. Missing or contradictory facts that prevent safe recovery make the checkpoint incomplete; identify their effect and the smallest clarification/read. A packet that honestly describes blocked work can still be sufficient: show its dependency blocker without inventing completion or requiring every linked source at startup. Eligible first-use TBD state still routes to onboarding; it is not a failed task handoff.\n\nUntil both gates pass, replace the card's `continuity ready` with `continuity incomplete`, use `incomplete` for its handoff status, and name the unread/conflicting scope. Do not begin dependent task work. Complete safe same-file supplementary reads before giving up; elapsed time or a green CLI is not acceptance. Full reception does not prove every historical fact or linked source; follow the normal required-reading gate before an authorized action. Bare startup still ends after its card. With explicit continuation, check the recovered input, output, downstream use and acceptance against the current request, read the necessary sources, and continue within the authorized scope, including multiple steps when completion or the next blocker was explicitly requested; neither the packet nor this checkpoint grants new permissions. These gates also apply after interrupted reads or context compaction when coverage cannot be recovered from actual evidence.\n\n### Current-thread naming checkpoint\n\nDuring explicit continuity startup, naming is a required presentation checkpoint when safe current-thread title control is available, not an optional task. After the minimum authorized startup reads, derive the current objective, boundary and recommended next action; resolve this checkpoint before emitting the final startup card or beginning any same-message authorized task work. Do not defer the tool call until after the final response or until the task is finished. If interrupted before the checkpoint resolves, handle it on the next user-authorized turn using current facts; do not schedule a background rename.\n\nUse `<project name>|<primary action>` from already-loaded facts: the concrete current user task first, then an unresolved current objective, then a concrete recommended action. Do not revive a completed child task from historical handoff text. When the project is known but no concrete action remains, use the project name alone. If the project name is unknown, skip without guessing or extra source reads. `Start Agent Handoff`, `開工`, `開始交接工作` and `開始工作交接` are not primary actions. Titles must not contain progress, completion, status, task/session IDs, absolute paths, secrets or unverified facts.\n\nUse the current runtime's exposed tool schema. If a safe current-thread title tool is already available, call it directly; otherwise use a bounded runtime tool-discovery mechanism once with a narrow title/rename/current-thread query, when available. Never invent a tool name. Current-title readback is useful when available, but is not required when the tool safely targets the calling/current thread. Replace a generic or stale title; keep an informative title when readback proves it is already relevant, and preserve an explicitly user-chosen title unless the user asks to change it. When the current title cannot be read, use one safe current-thread set call with the derived title. Omit the target identifier only when the schema documents current-thread targeting; otherwise require a verified current-thread identifier. Do not list or inspect unrelated threads solely for naming, and do not create, fork, navigate, message, archive, pin or otherwise manage tasks for this checkpoint.\n\nBefore the final response, resolve the checkpoint as applied (successful tool result confirms the title), kept (relevant or user-chosen title), unavailable (no safe capability), skipped (project unknown), or failed/unverified (error or no confirmation). Use a targeted current-thread readback when available; an ambiguous write requires readback before any retry. Only a verified mismatch permits one safe corrective call; never loop or overwrite a later user rename. Do not assume a universal timing window or automatic-title overwrite across AI apps. An unavailable capability does not block startup; skip silently. A failed/unverified attempted rename gets a brief startup warning, not a success claim. Once resolved, return the card and stop for bare startup. On a later user-authorized turn, revisit naming when the primary task becomes concrete or changes, or a generic/stale title is observed; do not rename for tests, reviews or small substeps.\n\nThe title is display-only; it is not project state, permission, progress, completion evidence, a health result, or a source of truth. This checkpoint permits only the bounded title calls above; it does not authorize project/file writes, network research, external task work, extra startup reads 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. Render the startup card in a fenced `text` block and preserve spacing so the ASCII status marker remains aligned. 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.\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 / incomplete>\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- For failures spanning steps or recurring, trace relevant inputs, processing, saved state and actual consumers until evidence explains the cause and direct impact. Then stop expanding the investigation and repair the affected locations with that cause within the authorized scope; do not turn a simple local fix into a whole-system audit.\n- When repeated attempts produce no improved result, unblocked dependency or new evidence, reassess the cause and method before retrying; preserve useful results. Necessary waits and experiments that yield new evidence are not stagnation. Existing safety and retry limits still apply.\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- Task-first governance locality: when the user supplied a concrete, actionable, authorized task plan and no safety / source-truth / permission blocker prevents it, follow the plan's main acceptance path before governance side work. Governance may become the main path only when the task itself is governance, the user explicitly asks for governance bridge or long-term governance, the content semantically requires cross-session force, or deferring it would create a safety, continuity, source-of-truth, or discoverability blocker. Otherwise, keep governance to the smallest classification, indexing, sync, or Persistence Gate decision that does not change the main deliverable path; do not start governance bridge, long-term-governance routing, repo-wide scans, handoff writes, or closeout solely because the task mentions Markdown, README, docs, specs, plans, checklists, or generated outputs.\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- Ordinary document edits normally use local read-back and task-specific checks only. If the edited document itself is the target authority and the task does not touch Kit-managed files, migrations, release / closeout gates, external effects, cross-source conflicts, or blockers for safe continuation, do not run `agent-handoff-kit doctor`, write handoff / log state, or regenerate the startup mirror solely because a document changed.\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 perform full closeout. Apply the bounded opening/mirror consistency rule below only when this checkpoint changes actionable state repeated there.\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\nPre-closeout checkpoint guard: before writing `dev/SESSION_HANDOFF.md` or `dev/SESSION_LOG.md` without explicit closeout / checkpoint intent, identify the durable fact, why the edited target authority or user-visible answer is insufficient, and why that file is the smallest correct home. Do not write either file merely because the next AI might misread stale state, or because a target-authority document changed. If the gate selects a checkpoint, update only the named current-state field(s) or one concise log entry; preserve unrelated / historical handoff sections byte-stable where practical. Without the opening-consistency condition below, do not regenerate `START_NEXT_SESSION_PROMPT.txt`.\n\nCheckpoint opening consistency: when an authorized checkpoint changes actionable facts repeated in the `Next Session Opening Message`, reconcile only those affected current facts in that same checkpoint. Derive `START_NEXT_SESSION_PROMPT.txt` from the sole marked opening block only if normalized content differs, then verify the block/mirror and the changed objective, next action and completion boundary agree. Do not merely label an authoritative opening historical while leaving instructions to redo completed work. Preserve unrelated opening text and cold evidence; this condition does not authorize full closeout, new task work, extra source scans or persistence after an ordinary document edit.\n\nDuring an ongoing task, between Persistence Gate decisions, `dev/SESSION_HANDOFF.md` may legitimately trail the read-back target authority. Treat that as expected lag, not drift, and do not update handoff merely to mirror each intermediate step. Still apply the gate when a durable or startup-needed fact must survive interruption, the handoff is the smallest correct home, Kit-managed / release / closeout / external-effect state changed, or full closeout 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\nBefore first running new or changed code, including tests and helper scripts, and even when the exact command comes from the user, a document or another agent, read the code's usage and what it deletes or overwrites as a separate step, then follow `dev/rules/coding.md` rules 6–7.\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. A real permission or lock refusal stops the affected operation; it is not permission to elevate, switch provider or mode, or use a riskier command. Normal platform approval and another already-authorized safe method remain available only after their actual scope and safety are verified.\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. Workspace identity is a last-verified snapshot. Live root / Git / worktree truth belongs to `agent-handoff-kit workspace-health --root <project root>` or equivalent read-only Git probes, not to stale prose.\n5. Closeout is not complete until required files are written, read back, and the available closeout checks pass.\n6. 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.\n7. 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. Read the applicable packs, including their project supplements and required references, before deciding how to act; an index, title or remembered summary is not the rule itself. Apply them within the user's actual objective and instruction priority: do not invent a replacement goal, acceptance standard or competing rule system. Missing or conflicting requirements must be resolved from their owners, not filled by an invented policy. 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. 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. Follow its `Governance Write Boundary` before choosing a writable location: installed official core and pack bodies are not project-editable rule homes. 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's project supplement 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=b6b1da70e9038d6adae676ce6dab76a5d120c6c376d3343dcd8c17f86ad3825d -->\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\nThe core `Upgrade lock guard` applies first when it stops ordinary work.\n"
16466
+ },
16467
+ "30ef7a1231e33c4114083d0bdcd2bbf9f6c837193ef992599ac906dd8d255af9": {
16468
+ "targetRel": "AGENTS.md",
16469
+ "canonicalSha256": "2deb8124f33377b16c07c71beb525e9e2523891be7d2386a948787c1f4a1b09a",
16470
+ "text": "<!-- BEGIN Agent Handoff Kit managed core -->\n# Agent Handoff Kit Core Runtime\n\n## 1. Intent And Startup\n\n### Upgrade lock guard\n\nBefore any handoff, user-rule router, pack, or other project-state read, use the verified project root to probe `dev/governance_migrations/.upgrade.lock`. A present lock, or inability to establish its absence, stops ordinary work and all further project-state reads and searches. Do not search for recovery instructions or edit or delete the lock. Before that explanation, render this fenced brand card:\n\n```text\n /\\_/\\ Agent Handoff Kit\n ( x.x ) continuity unavailable\n > ^ <\n```\n\nIt must not claim loaded, healthy, saved, or version-verified state. Explain that continuity is unavailable and give the supported recovery command `agent-handoff-kit upgrade --yes --root <verified-project-root>`. Bare startup never runs this command automatically. If the existence probe is unreadable, report continuity unavailable without claiming a lock is present and do not auto-recover. When the visible user request explicitly authorizes update, upgrade or recovery, only the official CLI performs transaction recovery; resume ordinary state loading only after that CLI succeeds and a new probe establishes lock absence.\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\nWhen resuming, recover the parent outcome, current step, resume point, remaining acceptance and source coverage from the fully received handoff under the checkpoint below. Preserve decision-changing user corrections, rejected approaches and their reasons, reusable work and permission boundaries. Surface missing critical context in the startup warning and recommend the specific clarification/read; do not infer parent completion from a finished child or treat previous-session reading as your own. Bare startup remains status-only, with no extra source reads or writes.\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, the display-only current-thread naming checkpoint 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.\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 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.\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\n### Handoff reception and recovery checkpoint\n\nBefore claiming `loaded`, `resumed` or `continuity ready`, complete both gates below. A successful closeout, read command, exit code, digest, section list or summary does not establish reception or understanding.\n\n1. **Receive the whole packet.** Read all of `dev/SESSION_HANDOFF.md`, including its middle and end, from one unchanged file version. A full-file command is only a request: inspect the actual tool result. If output is truncated, omitted, paginated or uncertain, use smaller bounded reads and track contiguous ranges from the start through EOF, with no gaps or mixed versions. Check the entire returned body, not just its header/footer; a tool can retain both ends while omitting the middle. Reread any uncertain range. If the file changes during reading, restart coverage for the new version. Native file tools are valid; compare file identity before/after the read sequence. When an already-available local Kit CLI supports it, `handoff-read --root <root>` offers bounded Unicode ranges; continue with its `nextOffset` as `--offset` and the same `--sha256`, reducing `--max-chars` on truncation. Verify its canonical `root` matches the intended workspace; a root alias is not permission to read an unexpected location. Links below that root are rejected. This helper serves content only. Do not download, install, probe integrations or write a receipt for bare startup. Missing/unreadable content stays incomplete.\n2. **Recover the work.** From that packet, reconcile the user's outcome and consumer, current task's relation to it, completed work and reusable evidence, decision reasons and rejected approaches, remaining obligations/acceptance, exact bounded next action, required fresh sources, and authorization/stop boundaries. Preserve corrections and distinguish historical state from current truth. Use existing section locations as internal evidence; do not create another summary file or dump the packet into the reply. Missing or contradictory facts that prevent safe recovery make the checkpoint incomplete; identify their effect and the smallest clarification/read. A packet that honestly describes blocked work can still be sufficient: show its dependency blocker without inventing completion or requiring every linked source at startup. Eligible first-use TBD state still routes to onboarding; it is not a failed task handoff.\n\nUntil both gates pass, replace the card's `continuity ready` with `continuity incomplete`, use `incomplete` for its handoff status, and name the unread/conflicting scope. Do not begin dependent task work. Complete safe same-file supplementary reads before giving up; elapsed time or a green CLI is not acceptance. Full reception does not prove every historical fact or linked source; follow the normal required-reading gate before an authorized action. Bare startup still ends after its card. With explicit continuation, check the recovered input, output, downstream use and acceptance against the current request, read the necessary sources, and continue within the authorized scope, including multiple steps when completion or the next blocker was explicitly requested; neither the packet nor this checkpoint grants new permissions. These gates also apply after interrupted reads or context compaction when coverage cannot be recovered from actual evidence.\n\n### Current-thread naming checkpoint\n\nDuring explicit continuity startup, naming is a required presentation checkpoint when safe current-thread title control is available, not an optional task. After the minimum authorized startup reads, derive the current objective, boundary and recommended next action; resolve this checkpoint before emitting the final startup card or beginning any same-message authorized task work. Do not defer the tool call until after the final response or until the task is finished. If interrupted before the checkpoint resolves, handle it on the next user-authorized turn using current facts; do not schedule a background rename.\n\nUse `<project name>|<primary action>` from already-loaded facts: the concrete current user task first, then an unresolved current objective, then a concrete recommended action. Do not revive a completed child task from historical handoff text. When the project is known but no concrete action remains, use the project name alone. If the project name is unknown, skip without guessing or extra source reads. `Start Agent Handoff`, `開工`, `開始交接工作` and `開始工作交接` are not primary actions. Titles must not contain progress, completion, status, task/session IDs, absolute paths, secrets or unverified facts.\n\nUse the current runtime's exposed tool schema. If a safe current-thread title tool is already available, call it directly; otherwise use a bounded runtime tool-discovery mechanism once with a narrow title/rename/current-thread query, when available. Never invent a tool name. Current-title readback is useful when available, but is not required when the tool safely targets the calling/current thread. Replace a generic or stale title; keep an informative title when readback proves it is already relevant, and preserve an explicitly user-chosen title unless the user asks to change it. When the current title cannot be read, use one safe current-thread set call with the derived title. Omit the target identifier only when the schema documents current-thread targeting; otherwise require a verified current-thread identifier. Do not list or inspect unrelated threads solely for naming, and do not create, fork, navigate, message, archive, pin or otherwise manage tasks for this checkpoint.\n\nBefore the final response, resolve the checkpoint as applied (successful tool result confirms the title), kept (relevant or user-chosen title), unavailable (no safe capability), skipped (project unknown), or failed/unverified (error or no confirmation). Use a targeted current-thread readback when available; an ambiguous write requires readback before any retry. Only a verified mismatch permits one safe corrective call; never loop or overwrite a later user rename. Do not assume a universal timing window or automatic-title overwrite across AI apps. An unavailable capability does not block startup; skip silently. A failed/unverified attempted rename gets a brief startup warning, not a success claim. Once resolved, return the card and stop for bare startup. On a later user-authorized turn, revisit naming when the primary task becomes concrete or changes, or a generic/stale title is observed; do not rename for tests, reviews or small substeps.\n\nThe title is display-only; it is not project state, permission, progress, completion evidence, a health result, or a source of truth. This checkpoint permits only the bounded title calls above; it does not authorize project/file writes, network research, external task work, extra startup reads 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. Render the startup card in a fenced `text` block and preserve spacing so the ASCII status marker remains aligned. 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.\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 / incomplete>\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- For failures spanning steps or recurring, trace relevant inputs, processing, saved state and actual consumers until evidence explains the cause and direct impact. Then stop expanding the investigation and repair the affected locations with that cause within the authorized scope; do not turn a simple local fix into a whole-system audit.\n- When repeated attempts produce no improved result, unblocked dependency or new evidence, reassess the cause and method before retrying; preserve useful results. Necessary waits and experiments that yield new evidence are not stagnation. Existing safety and retry limits still apply.\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- Task-first governance locality: when the user supplied a concrete, actionable, authorized task plan and no safety / source-truth / permission blocker prevents it, follow the plan's main acceptance path before governance side work. Governance may become the main path only when the task itself is governance, the user explicitly asks for governance bridge or long-term governance, the content semantically requires cross-session force, or deferring it would create a safety, continuity, source-of-truth, or discoverability blocker. Otherwise, keep governance to the smallest classification, indexing, sync, or Persistence Gate decision that does not change the main deliverable path; do not start governance bridge, long-term-governance routing, repo-wide scans, handoff writes, or closeout solely because the task mentions Markdown, README, docs, specs, plans, checklists, or generated outputs.\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- Ordinary document edits normally use local read-back and task-specific checks only. If the edited document itself is the target authority and the task does not touch Kit-managed files, migrations, release / closeout gates, external effects, cross-source conflicts, or blockers for safe continuation, do not run `agent-handoff-kit doctor`, write handoff / log state, or regenerate the startup mirror solely because a document changed.\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 perform full closeout. Apply the bounded opening/mirror consistency rule below only when this checkpoint changes actionable state repeated there.\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\nPre-closeout checkpoint guard: before writing `dev/SESSION_HANDOFF.md` or `dev/SESSION_LOG.md` without explicit closeout / checkpoint intent, identify the durable fact, why the edited target authority or user-visible answer is insufficient, and why that file is the smallest correct home. Do not write either file merely because the next AI might misread stale state, or because a target-authority document changed. If the gate selects a checkpoint, update only the named current-state field(s) or one concise log entry; preserve unrelated / historical handoff sections byte-stable where practical. Without the opening-consistency condition below, do not regenerate `START_NEXT_SESSION_PROMPT.txt`.\n\nCheckpoint opening consistency: when an authorized checkpoint changes actionable facts repeated in the `Next Session Opening Message`, reconcile only those affected current facts in that same checkpoint. Derive `START_NEXT_SESSION_PROMPT.txt` from the sole marked opening block only if normalized content differs, then verify the block/mirror and the changed objective, next action and completion boundary agree. Do not merely label an authoritative opening historical while leaving instructions to redo completed work. Preserve unrelated opening text and cold evidence; this condition does not authorize full closeout, new task work, extra source scans or persistence after an ordinary document edit.\n\nDuring an ongoing task, between Persistence Gate decisions, `dev/SESSION_HANDOFF.md` may legitimately trail the read-back target authority. Treat that as expected lag, not drift, and do not update handoff merely to mirror each intermediate step. Still apply the gate when a durable or startup-needed fact must survive interruption, the handoff is the smallest correct home, Kit-managed / release / closeout / external-effect state changed, or full closeout 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\nDo not terminate, delete, disable, uninstall or reset a process, broad cache, browser profile, app session, notebook kernel, shared tool server or configuration that is not clearly task-owned or agent-managed unless the user confirms the exact target; a process name alone is not ownership evidence, and `dev/rules/safety.md` rule 14 sets the full boundary.\n\nNever run `rm -rf`, `sudo rm -rf`, `Remove-Item -Recurse -Force`, `git clean -fdx`, `git reset --hard`, or an obfuscated or wrapped equivalent; use a narrower reversible operation or give the user a manual action list.\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\nBefore first running new or changed code, including tests and helper scripts, and even when the exact command comes from the user, a document or another agent, read the code's usage and what it deletes or overwrites as a separate step, then follow `dev/rules/coding.md` rules 6–7.\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. A real permission or lock refusal stops the affected operation; it is not permission to elevate, switch provider or mode, or use a riskier command. Normal platform approval and another already-authorized safe method remain available only after their actual scope and safety are verified.\n\nNever request a credential value or persist one in any project file; if a value matching a known credential prefix appears in the conversation, redact it in your output and warn the user to rotate it; `dev/rules/safety.md` rules 11–12 set the full boundary, including auth-failure handling.\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. Workspace identity is a last-verified snapshot. Live root / Git / worktree truth belongs to `agent-handoff-kit workspace-health --root <project root>` or equivalent read-only Git probes, not to stale prose.\n5. Closeout is not complete until required files are written, read back, and the available closeout checks pass.\n6. 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.\n7. 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. Read the applicable packs, including their project supplements and required references, before deciding how to act; an index, title or remembered summary is not the rule itself. Apply them within the user's actual objective and instruction priority: do not invent a replacement goal, acceptance standard or competing rule system. Missing or conflicting requirements must be resolved from their owners, not filled by an invented policy. 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. 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. Follow its `Governance Write Boundary` before choosing a writable location: installed official core and pack bodies are not project-editable rule homes. 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's project supplement 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=a820da554c4745c5a3b241d6b0ac731857b8ccd0954c1bb1b7125f0bc065fc40 -->\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\nThe core `Upgrade lock guard` applies first when it stops ordinary work.\n"
16291
16471
  }
16292
16472
  },
16293
16473
  "generatedShortcuts": {
@@ -16649,7 +16829,61 @@
16649
16829
  "dev/handoff-kit/project-version.mjs": "8814c81f7053147e6b6816dc356790330257fddae53404d88a5d2b7c01a6ebcb",
16650
16830
  "dev/handoff-kit/assets.mjs": "a6374fa85da7450437a94a0a2372c692a5b2fc592860316b7447c59a194cc550"
16651
16831
  }
16832
+ },
16833
+ "0.4.7": {
16834
+ "npm": {
16835
+ "spec": "@adamchanadam/agent-handoff-kit@0.4.7",
16836
+ "shasum": "1aeaca37531fb67842b8853ea16c1eb18fa2f858",
16837
+ "integrity": "sha512-HKxpIiljNuBtfZe6MIREbvFluZeREQomwUod1dnlY9jcy1wSYJZ2j4UV5GLS/bvlZ81kx9pFYrzgVQmzoKhmFg==",
16838
+ "tarballSha256": "2eea6ef8d7a54ee00a599ff4d081060d30522807d2ca880f68df51d9e3afd4d9"
16839
+ },
16840
+ "generatorSha256": "34432388f0e6de9120a40e38d29ef5ee1483795cae64e4d47bbde68413a9d5d3",
16841
+ "files": {
16842
+ ".claude/skills/handoff-kit-start/SKILL.md": "9e0e4312fe9bc8e6801c5e0ea32026144a10ba364118b61058470aef2cf12cdf",
16843
+ ".agents/skills/handoff-kit-start/SKILL.md": "9e0e4312fe9bc8e6801c5e0ea32026144a10ba364118b61058470aef2cf12cdf",
16844
+ ".agents/skills/handoff-kit-start/agents/openai.yaml": "a294dd1815bef68434d4fbf93261d5192abdc6f3570e6b6030d19f2bf657a984",
16845
+ ".gemini/commands/handoff-kit-start.toml": "23c0da1953e98d18a1d9a1f725af5174a4e16a2b41fb69f7fd650af1efaf24ce",
16846
+ ".claude/skills/handoff-kit-close/SKILL.md": "46d999d993a282092ad93bb69d2848749d0b448eb71fe7a3394a3caa7e68e8ab",
16847
+ ".agents/skills/handoff-kit-close/SKILL.md": "46d999d993a282092ad93bb69d2848749d0b448eb71fe7a3394a3caa7e68e8ab",
16848
+ ".agents/skills/handoff-kit-close/agents/openai.yaml": "7ff3064232dfa62d9b0a75c5cc743afb77a1c6986e8c423618cc37cf0031501d",
16849
+ ".gemini/commands/handoff-kit-close.toml": "98898d53857b14d46ba2a19bf06397c2ee221f68e5ff877cf3a4f2ee2cf8142d",
16850
+ ".claude/skills/handoff-kit-progress/SKILL.md": "ee2a16a983cfb612099271adc5ff4ad628003cfc56963c71e4e853288d03f0b4",
16851
+ ".agents/skills/handoff-kit-progress/SKILL.md": "ee2a16a983cfb612099271adc5ff4ad628003cfc56963c71e4e853288d03f0b4",
16852
+ ".agents/skills/handoff-kit-progress/agents/openai.yaml": "cbb31a137fe249e7ec563ea70759c7bd7792d0b72dd912d38ef25226667902c4",
16853
+ ".gemini/commands/handoff-kit-progress.toml": "b0ec3e0f3773d6de8df241ca79f143b0781f7fc1034ec4a0fc9464966c752918",
16854
+ ".claude/skills/handoff-kit-align/SKILL.md": "7a8e1d22043e36dc1c74b8ec262f292e574cdb1f3dce0264370e5134fe52ebba",
16855
+ ".agents/skills/handoff-kit-align/SKILL.md": "7a8e1d22043e36dc1c74b8ec262f292e574cdb1f3dce0264370e5134fe52ebba",
16856
+ ".agents/skills/handoff-kit-align/agents/openai.yaml": "4001a19fc73b01be44de48b44db2d5c361e38c637a1b4ffa1b215dd5615bca5d",
16857
+ ".gemini/commands/handoff-kit-align.toml": "5077dad5129d5219ceb7cb3c87c09f169c53c062d51edf7b415ca8aba50f7bb0",
16858
+ ".claude/skills/handoff-kit-onboard/SKILL.md": "161f6fc817e0c03ec8093c574d066bf1d5e7716ae47870a9cb8683311f4dd7b7",
16859
+ ".agents/skills/handoff-kit-onboard/SKILL.md": "161f6fc817e0c03ec8093c574d066bf1d5e7716ae47870a9cb8683311f4dd7b7",
16860
+ ".agents/skills/handoff-kit-onboard/agents/openai.yaml": "5ef6ac65e96d20a71287c5f44abad14dc4f7b91d4fefd5b4ec7f672273917265",
16861
+ ".gemini/commands/handoff-kit-onboard.toml": "915c92a522a9995f201e85521d9f40f6cf499f52988dfac04cf22585f72dfbe7",
16862
+ ".claude/skills/handoff-kit-remember/SKILL.md": "14b6f9906ab816bfe1d02ec5fdb822ad3c3981346040bcf3bcad7ae85fb52ce8",
16863
+ ".agents/skills/handoff-kit-remember/SKILL.md": "14b6f9906ab816bfe1d02ec5fdb822ad3c3981346040bcf3bcad7ae85fb52ce8",
16864
+ ".agents/skills/handoff-kit-remember/agents/openai.yaml": "9bed15e27ee9725e2a31b57d10687349a5754dcfcae55aca167c763f6f1e0e80",
16865
+ ".gemini/commands/handoff-kit-remember.toml": "c577c8af5430dbc0e1a5b4a2d1f74a19ef279f695572ca8b5de3b4aeb35e7892",
16866
+ ".claude/skills/handoff-kit-check/SKILL.md": "6948d45ff7d95f5dd66930d02dba6b99aadbc51d6e220a32b9a1ffdbe99d7bae",
16867
+ ".agents/skills/handoff-kit-check/SKILL.md": "6948d45ff7d95f5dd66930d02dba6b99aadbc51d6e220a32b9a1ffdbe99d7bae",
16868
+ ".agents/skills/handoff-kit-check/agents/openai.yaml": "666d4b602e019e06a7dd70742fc459cd2afab2a442bce038c87dfce09d429bb2",
16869
+ ".gemini/commands/handoff-kit-check.toml": "f8985c17fe064f2902e941369b5a761fe27a4ba897a0e88e9cc67d7170ad9136",
16870
+ ".claude/skills/handoff-kit-update/SKILL.md": "b8cf133ae63068257e1a8b570ce2cba8ef29d5438465ca5caaaca093095416a7",
16871
+ ".agents/skills/handoff-kit-update/SKILL.md": "b8cf133ae63068257e1a8b570ce2cba8ef29d5438465ca5caaaca093095416a7",
16872
+ ".agents/skills/handoff-kit-update/agents/openai.yaml": "12177a56d5a3573cb079506de78375f83ccb06f8fa7e1828a3d7c237de82e7bf",
16873
+ ".gemini/commands/handoff-kit-update.toml": "baad57bb779e91f4be1b6b9b7570bb36e5238c23e5e750d9bbc3ef6c7e98bd9b",
16874
+ ".claude/skills/handoff-kit-help/SKILL.md": "d3b0d4fe6505b28284d7bc93b6124b5bd84898356b57ff0c217a74e63d00100d",
16875
+ ".agents/skills/handoff-kit-help/SKILL.md": "d3b0d4fe6505b28284d7bc93b6124b5bd84898356b57ff0c217a74e63d00100d",
16876
+ ".agents/skills/handoff-kit-help/agents/openai.yaml": "a87a82d80551abfe32588d6b66b44b21c45aa636ef0392cc886dfb5cc65a609a",
16877
+ ".gemini/commands/handoff-kit-help.toml": "880e88bd61747f82bf54fe274ab00d368374904a102ee34ffe5341c03c513f56",
16878
+ "dev/handoff-kit/launch.mjs": "d0bcbf596f08f722c9af84c7779e1b3ef77b49234e840e97d78bf2296b9dca2c",
16879
+ "dev/handoff-kit/open.mjs": "7725ff1ee0da9b1753d5d8648c73272b6b0948b9ca567c1e89734e2b1275f28d",
16880
+ "dev/handoff-kit/server.mjs": "52fb563cac05d08a934c759f6157035767eabf3de977085a7b811bde78177cbf",
16881
+ "dev/handoff-kit/projection.mjs": "06429ecdffab697acd88f3327c00e17d92cfa1d3629edf35afea6a51d1288ce7",
16882
+ "dev/handoff-kit/dashboard.mjs": "73a50e69886d00d706677ef925ac74bed6d7d7ba299642d7880c25d05885ca61",
16883
+ "dev/handoff-kit/project-version.mjs": "8814c81f7053147e6b6816dc356790330257fddae53404d88a5d2b7c01a6ebcb",
16884
+ "dev/handoff-kit/assets.mjs": "48240476e554138f5c2df456b6b62466bd71a0d0fd2679ae68b13438680eec22"
16885
+ }
16652
16886
  }
16653
16887
  },
16654
- "catalogDigestSha256": "10a3406316e93a0f2f2e534898343500baeb3ab61c7370a9447464033e51da7a"
16888
+ "catalogDigestSha256": "d984564d24ee4ce4b5f13d80c1ac0e60dab7c0b17f2533977ff30c92d6eefa2f"
16655
16889
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.4.7",
3
+ "version": "0.4.8",
4
4
  "description": "Your session relay baton for agentic AI — context engineering at its core, so supported AI tools can pick up where the last one left off.",
5
5
  "type": "module",
6
6
  "bin": {
package/packs/closeout.md CHANGED
@@ -37,12 +37,12 @@ Handoff cold zones are historical / evidence sections, old validation records, c
37
37
  5. Add one concise log entry only for current work, risk, actual maintenance, or another durable fact that a later agent needs. Record evidence disposition and the prompt-mirror verification result when an entry is needed; omit the full opening message by design. A no-op closeout must not create a false work record.
38
38
  6. Update the project index only when affected complete mappings, rules, or supplements changed. Classify every applicable sync-registry target as `confirmed`, `unverified`, `pending`, `blocked`, or `not_applicable`.
39
39
  7. Run `agent-handoff-kit workspace-health --root <project root>` or equivalent read-only Git probes, then record only the last-verified root, Git root, branch, commit, worktrees / parallel workspaces, uncommitted changes, and unresolved drift. Do not clean or change them without separate authorization. Do not treat `dev/PROJECT_INDEX.md` or old handoff prose as the live worktree truth.
40
- 8. 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.
40
+ 8. If the session used external tools or helper processes, or ran tools, tests or scripts that can leave disposable by-products, 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.
41
41
  9. Run the short maintenance assessment below. Record only actual maintenance work or a current risk; do not create a log entry solely to report a size advisory.
42
42
  10. 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`.
43
43
  11. Verify `START_NEXT_SESSION_PROMPT.txt` against the sole fenced handoff opening-message block first. Regenerate it only when normalized content differs, then 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.
44
44
  12. Run available project-specific closeout checks. Do not run a separate bundled `doctor`; step 13 performs it. Do not treat an external update-check failure as local closeout failure. Fix state or mirror failures before claiming handoff ready.
45
- 13. 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 plus a read-only workspace-health comparison against the handoff snapshot, and its output is the only final card source. A nonzero result means the closeout is blocked; do not replace it with a success summary.
45
+ 13. 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 plus a read-only workspace-health comparison against the handoff snapshot, and its output is the only final card source. A nonzero result means the closeout is blocked; do not replace it with a success summary. The card also shows a time-bounded, metadata-only footprint line (apparent size, file count, largest top-level folders) that is informational only, is not a cleanup list, and never changes the closeout status.
46
46
 
47
47
  ## Packet-Only Reconstruction Check
48
48
 
@@ -82,6 +82,7 @@ status: complete
82
82
  🔎 QC: <validation summary>
83
83
  📌 Handoff: opening message ready
84
84
  ⚠️ Boundary: <important boundary or none>
85
+ 📦 Footprint (apparent): <size> GiB / <files> files; largest: <top folders>
85
86
  ```
86
87
 
87
88
  For `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.
package/packs/coding.md CHANGED
@@ -18,6 +18,7 @@ Use for code changes, tests, builds, package managers, SDKs, CLIs, APIs, or deve
18
18
  5. Preserve unrelated user changes.
19
19
  6. Before first running new or changed code, including your own tests and helper scripts, read its usage text or header comment as a separate step before composing the command, noting how it uses arguments, environment variables, deletion and overwrite. If it can delete or overwrite anything outside a temporary location it created, first confirm the work is already recoverable (committed, backed up, or run against an isolated copy). This rule does not authorize a commit or backup; if the work is not recoverable, ask the user.
20
20
  7. Tests, fixtures and helper scripts you write that delete or clear must verify the target is a temporary location they created (resolved path, expected name prefix, not the project or working directory or any ancestor of them); otherwise they must stop and report failure, never pass. Product features that delete by design follow `dev/rules/safety.md`.
21
+ 8. Create disposable by-products of tests, fixtures and helper scripts (such as browser profiles, caches, snapshots and temporary copies) in a temporary location the tool owns, never in evidence or deliverable folders. Remove them on success and safely on a best-effort basis on failure. When failure evidence must be kept for diagnosis, keep only what is needed and report its path, purpose and condition for later removal. Any removal still follows rule 7 and the safety and integrations ownership rules; this rule grants no new deletion authority.
21
22
 
22
23
  ## Checks
23
24
 
@@ -150,7 +150,7 @@ If any answer is no, blocked, or uncertain, fix this handoff before declaring ha
150
150
 
151
151
  Lifecycle 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.
152
152
 
153
- Closeout-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.
153
+ Closeout-card rule: `closeout-status` reads only these existing handoff fields plus fresh doctor / mirror results and an informational, metadata-only footprint measurement; 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.
154
154
 
155
155
  <!-- ack:section:handoff-sufficiency-check -->
156
156
  ## Handoff Sufficiency Check