@adamchanadam/agent-handoff-kit 0.3.53 → 0.3.55

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.
@@ -1,13 +1,10 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import { lstat, readdir, readFile, realpath } from "node:fs/promises";
3
3
  import path from "node:path";
4
- import { installedFileContracts, upgradeStateFileContracts, INSTALLED_FILE_CONTRACT_SCHEMA } from "./installed-file-contract.mjs";
5
- import { loadOfficialOriginCatalog } from "./official-origin-catalog.mjs";
4
+ import { installedFileContracts } from "./installed-file-contract.mjs";
6
5
  import { FORMAL_USER_RULES_ENTRY_ANCHOR, readFormalUserRules } from "./user-rules-router.mjs";
7
6
 
8
- export const UPGRADE_INVENTORY_SCHEMA = 1;
9
- export const GATE5_FROZEN_SET_SCHEMA = 2;
10
- export const GATE5_ROOT_SOURCE_INVENTORY_SCHEMA = 1;
7
+ export const UPGRADE_INVENTORY_SCHEMA = 1;
11
8
 
12
9
  const formalEntryTargets = Object.freeze([
13
10
  "AGENTS.md",
@@ -16,28 +13,16 @@ const formalEntryTargets = Object.freeze([
16
13
  "START_NEXT_SESSION_PROMPT.txt"
17
14
  ]);
18
15
 
19
- const transactionRegistryRoot = "dev/governance_migrations";
20
-
21
16
  const archiveDirectories = Object.freeze([
22
17
  { relative: "dev/SESSION_LOG_archive", classification: "session-log-archive" },
23
18
  { relative: "dev/session_log_archive", classification: "legacy-session-log-archive" }
24
19
  ]);
25
20
 
26
- export function gate5ItemRequiresSourceConservation(item) {
27
- return Boolean(item && Array.isArray(item.classifications)
28
- && item.classifications.some((classification) => classification !== "root-source"));
29
- }
30
-
31
- export function gate5SourceConservationItems(frozen) {
32
- return Object.freeze((frozen?.items ?? []).filter(gate5ItemRequiresSourceConservation));
33
- }
34
-
35
- /**
36
- * Builds a read-only, hash-bound description of the Kit data that an upgrade
37
- * can reach. It deliberately records whole source files before any semantic
38
- * candidate tries to divide or merge their contents: a heading, language, or
39
- * layout is never treated as ownership evidence.
40
- */
21
+ /**
22
+ * Builds a read-only, hash-bound description of the Kit data that an upgrade
23
+ * can reach now. Ordinary workspace files, generic Markdown references, and
24
+ * committed historical transaction receipts are not current upgrade authority.
25
+ */
41
26
  export async function buildUpgradeInventory({ root, contracts = installedFileContracts } = {}) {
42
27
  if (!root) throw new Error("upgrade inventory requires a project root");
43
28
  const rootPath = path.resolve(root);
@@ -114,8 +99,6 @@ export async function buildUpgradeInventory({ root, contracts = installedFileCon
114
99
  );
115
100
  }
116
101
 
117
- await addTransactionRegistry(transactionRegistryRoot);
118
-
119
102
  for (const directory of archiveDirectories) {
120
103
  await addTree(directory.relative, directory.classification);
121
104
  }
@@ -159,49 +142,6 @@ export async function buildUpgradeInventory({ root, contracts = installedFileCon
159
142
  formalEntryTargets: formalEntryTargets.filter((target) => entries.has(target))
160
143
  });
161
144
 
162
- async function addTransactionRegistry(relativeDirectory) {
163
- const normalized = normalizeProjectRelative(relativeDirectory);
164
- if (!normalized) {
165
- addBlocker(String(relativeDirectory), "transaction registry escapes the selected project root");
166
- return;
167
- }
168
- const absolute = path.resolve(rootPath, normalized);
169
- const stats = await lstat(absolute).catch((error) => {
170
- if (error?.code === "ENOENT") return null;
171
- throw error;
172
- });
173
- if (!stats) return;
174
- if (!stats.isDirectory() || stats.isSymbolicLink()) {
175
- addBlocker(normalized, "transaction registry is not a safe real directory");
176
- return;
177
- }
178
- const resolved = await realpath(absolute);
179
- if (!isInside(realRoot, resolved)) {
180
- addBlocker(normalized, "transaction registry resolves outside the selected project root");
181
- return;
182
- }
183
- for (const item of await readdir(absolute, { withFileTypes: true })) {
184
- const child = `${normalized}/${item.name}`;
185
- const childAbsolute = path.join(absolute, item.name);
186
- const childStats = await lstat(childAbsolute).catch((error) => {
187
- if (error?.code === "ENOENT") return null;
188
- throw error;
189
- });
190
- if (!childStats) continue;
191
- if (childStats.isFile()) continue;
192
- if (childStats.isSymbolicLink() || !childStats.isDirectory()) {
193
- addBlocker(child, "transaction registry child is not a safe real directory");
194
- continue;
195
- }
196
- const childResolved = await realpath(childAbsolute);
197
- if (!isInside(realRoot, childResolved)) {
198
- addBlocker(child, "transaction registry child resolves outside the selected project root");
199
- continue;
200
- }
201
- await addFile(`${child}/transaction.json`, "transaction-state", { from: "transaction-registry", via: normalized });
202
- }
203
- }
204
-
205
145
  async function addTree(relativeDirectory, classification) {
206
146
  const normalized = normalizeProjectRelative(relativeDirectory);
207
147
  if (!normalized) {
@@ -244,297 +184,6 @@ export async function buildUpgradeInventory({ root, contracts = installedFileCon
244
184
  }
245
185
  }
246
186
 
247
- /**
248
- * Gate 5 current scope is the typed reachable inventory. It deliberately does
249
- * not walk the project root: ordinary files outside installed/runtime/formal
250
- * user-rule/transaction/archive contracts are outside machine authority.
251
- */
252
- export async function buildGate5RootSourceInventory({ root, reachableInventory } = {}) {
253
- if (!root) throw new Error("Gate 5 root-source inventory requires a project root");
254
- if (!reachableInventory || reachableInventory.schemaVersion !== UPGRADE_INVENTORY_SCHEMA) {
255
- throw new Error("Gate 5 root-source inventory requires the current reachable inventory");
256
- }
257
- const rootPath = path.resolve(root);
258
- const rootStats = await lstat(rootPath).catch((error) => {
259
- if (error?.code === "ENOENT") return null;
260
- throw error;
261
- });
262
- if (!rootStats?.isDirectory() || rootStats.isSymbolicLink()) {
263
- throw new Error("Gate 5 root-source inventory root must be a real directory");
264
- }
265
- const entries = new Map();
266
- const blockers = [...reachableInventory.blockers];
267
-
268
- for (const reachable of reachableInventory.entries) {
269
- const classifications = reachable.classifications ?? [];
270
- const reachability = reachable.reachability ?? [];
271
- entries.set(reachable.path, Object.freeze({
272
- path: reachable.path,
273
- sha256: reachable.sha256,
274
- bytes: reachable.bytes,
275
- classifications: Object.freeze(["root-source", ...classifications].sort()),
276
- reachability: Object.freeze([...reachability]
277
- .sort((left, right) => `${left.from}\0${left.via}`.localeCompare(`${right.from}\0${right.via}`)))
278
- }));
279
- }
280
- const frozenEntries = [...entries.values()].sort((left, right) => left.path.localeCompare(right.path));
281
- const sortedBlockers = blockers.sort((left, right) => `${left.path}\0${left.reason}`.localeCompare(`${right.path}\0${right.reason}`));
282
- const body = {
283
- schemaVersion: GATE5_ROOT_SOURCE_INVENTORY_SCHEMA,
284
- entries: frozenEntries,
285
- blockers: sortedBlockers
286
- };
287
- return Object.freeze({
288
- ...body,
289
- status: sortedBlockers.length === 0 ? "ready" : "blocked",
290
- rootSourceSha256: sha256(Buffer.from(`${JSON.stringify(body)}\n`, "utf8"))
291
- });
292
- }
293
-
294
- /**
295
- * Freezes the complete set that a Gate 5 upgrade may reason about before any
296
- * candidate, transaction, or semantic disposition is attempted. This is not
297
- * an activation record and grants no write authority: it binds every reached
298
- * project source's raw bytes to the installed package contract, formal
299
- * historical source, transaction/registry surface, bridges, router, and
300
- * formal entry.
301
- */
302
- export async function freezeGate5Set({ root, contracts = installedFileContracts, transitionContracts = upgradeStateFileContracts, catalog = null } = {}) {
303
- const inventory = await buildUpgradeInventory({ root, contracts });
304
- if (inventory.status !== "ready") throw new Error("Gate 5 frozen set requires a ready reachable inventory");
305
- const rootSourceInventory = await buildGate5RootSourceInventory({ root, reachableInventory: inventory });
306
- if (rootSourceInventory.status !== "ready") throw new Error("Gate 5 frozen set requires a complete safe root-source inventory");
307
- const rootPath = path.resolve(root);
308
- const officialCatalog = catalog ?? await loadOfficialOriginCatalog();
309
- const packageContracts = normalizeContracts(contracts, transitionContracts);
310
- const contractByTarget = new Map(packageContracts.map((contract) => [contract.targetRel, contract]));
311
- const contractBody = {
312
- schemaVersion: INSTALLED_FILE_CONTRACT_SCHEMA,
313
- installed: contracts.map(({ sourceRel, targetRel, strategy }) => ({ sourceRel, targetRel, strategy })),
314
- transition: transitionContracts.map(({ sourceRel, targetRel, strategy }) => ({ sourceRel, targetRel, strategy }))
315
- };
316
- const contractDigestSha256 = sha256(Buffer.from(`${JSON.stringify(contractBody)}\n`, "utf8"));
317
- const installedTemplateVersion = await readProjectIndexTemplateVersion(rootPath);
318
- const release = installedTemplateVersion ? officialCatalog.releases?.[installedTemplateVersion] : null;
319
- const entryByPath = new Map(rootSourceInventory.entries.map((entry) => [entry.path, entry]));
320
- const items = rootSourceInventory.entries.map((entry) => {
321
- const contract = contractByTarget.get(entry.path) ?? null;
322
- const historicalEntry = contract && release?.manifest?.[entry.path]?.state === "present"
323
- ? release.manifest[entry.path]
324
- : null;
325
- const exactPackageBytes = Boolean(historicalEntry && entry.sha256 === historicalEntry.rawSha256);
326
- const discoveredReachability = entry.reachability.map(({ from, via }) => ({ reader: from, via }));
327
- const readers = discoveredReachability.filter(({ reader }) => isFormalReader(reader));
328
- const kitReachable = entry.classifications.some((classification) => classification !== "root-source");
329
- const unresolvedReason = !kitReachable
330
- ? null
331
- : !exactPackageBytes
332
- ? "non-exact-or-unknown bytes require a verified preserve destination or remain unresolved"
333
- : readers.length === 0
334
- ? "no verified existing reader; priority and effect remain unresolved"
335
- : "reader is recorded, but priority/conflict and runtime effect remain unresolved before a per-item transaction proof";
336
- return Object.freeze({
337
- sourcePath: entry.path,
338
- sourceIdentity: Object.freeze({ sha256: entry.sha256, bytes: entry.bytes }),
339
- classifications: Object.freeze([...entry.classifications]),
340
- existingReaders: Object.freeze(readers),
341
- discoveredReachability: Object.freeze(discoveredReachability),
342
- priorityConflict: Object.freeze({
343
- status: kitReachable ? "unresolved-before-runtime-validation" : "not-applicable-outside-known-kit-reachability",
344
- relation: !kitReachable ? "outside-known-kit-reachability" : readers.length > 0 ? "reader-reachable-priority-not-proven" : "no-verified-reader"
345
- }),
346
- effect: Object.freeze({
347
- status: kitReachable ? "unresolved-before-runtime-validation" : "not-applicable-outside-known-kit-reachability",
348
- decision: !kitReachable ? "outside-known-kit-reachability" : readers.length > 0 ? "preserve-existing-route-or-stop" : "unresolved"
349
- }),
350
- packageContract: contract
351
- ? Object.freeze({ sourceRel: contract.sourceRel, targetRel: contract.targetRel, strategy: contract.strategy, scope: contract.scope })
352
- : null,
353
- historicalOrigin: historicalEntry
354
- ? Object.freeze({
355
- packageIdentity: release.source.npm.spec,
356
- installedTemplateVersion,
357
- rawSha256: historicalEntry.rawSha256,
358
- exactPackageBytes,
359
- catalogDigestSha256: officialCatalog.catalogDigestSha256
360
- })
361
- : null,
362
- ownership: exactPackageBytes && contract?.scope === "installed"
363
- ? "kit-managed-exact"
364
- : "user-or-unknown",
365
- unresolvedReason
366
- });
367
- });
368
- const contractCoverage = packageContracts.map((contract) => {
369
- const source = entryByPath.get(contract.targetRel) ?? null;
370
- const historicalState = release?.manifest?.[contract.targetRel]?.state ?? "unavailable";
371
- const status = source
372
- ? "source-frozen"
373
- : historicalState === "absent"
374
- ? "not-present-in-historical-package"
375
- : contract.scope === "transition"
376
- ? "not-present-no-formal-transition-state"
377
- : "unresolved-missing-installed-source";
378
- return Object.freeze({
379
- sourceRel: contract.sourceRel,
380
- targetRel: contract.targetRel,
381
- strategy: contract.strategy,
382
- scope: contract.scope,
383
- sourceStatus: status,
384
- sourceIdentity: source ? Object.freeze({ sha256: source.sha256, bytes: source.bytes }) : null,
385
- historicalState
386
- });
387
- });
388
- const unresolvedItems = items
389
- .filter((item) => item.unresolvedReason)
390
- .map((item) => Object.freeze({ sourcePath: item.sourcePath, reason: item.unresolvedReason }));
391
- const unresolvedContractTargets = contractCoverage
392
- .filter((item) => item.sourceStatus === "unresolved-missing-installed-source")
393
- .map((item) => Object.freeze({ sourcePath: item.targetRel, reason: "installed package target is missing from the root-source set" }));
394
- const bridgePaths = ["CLAUDE.md", "GEMINI.md"];
395
- const sourceConservationPaths = items
396
- .filter(gate5ItemRequiresSourceConservation)
397
- .map((item) => item.sourcePath);
398
- const body = {
399
- schemaVersion: GATE5_FROZEN_SET_SCHEMA,
400
- operationAuthority: "none",
401
- activationStatus: "not-authorized",
402
- inventory: Object.freeze({ schemaVersion: inventory.schemaVersion, sha256: inventory.inventorySha256 }),
403
- rootSourceInventory: Object.freeze({
404
- schemaVersion: rootSourceInventory.schemaVersion,
405
- sha256: rootSourceInventory.rootSourceSha256,
406
- entryCount: rootSourceInventory.entries.length
407
- }),
408
- packageContract: Object.freeze({
409
- schemaVersion: INSTALLED_FILE_CONTRACT_SCHEMA,
410
- digestSha256: contractDigestSha256,
411
- installedTargets: Object.freeze(contracts.map(({ targetRel }) => targetRel)),
412
- transitionTargets: Object.freeze(transitionContracts.map(({ targetRel }) => targetRel)),
413
- coverage: Object.freeze(contractCoverage)
414
- }),
415
- historicalSource: Object.freeze({
416
- catalogSchemaVersion: officialCatalog.schemaVersion,
417
- catalogDigestSha256: officialCatalog.catalogDigestSha256,
418
- installedTemplateVersion,
419
- packageIdentity: release?.source?.npm?.spec ?? null,
420
- packageIntegrity: release?.source?.npm?.integrity ?? null,
421
- status: release ? "bound-to-installed-catalog-identity" : "unresolved-no-catalog-release-for-installed-version"
422
- }),
423
- formalSurfaces: Object.freeze({
424
- entry: binding(entryByPath, "AGENTS.md"),
425
- bridges: Object.freeze(bridgePaths.map((targetRel) => binding(entryByPath, targetRel))),
426
- router: binding(entryByPath, "dev/USER_RULES.md"),
427
- transactionRegistry: Object.freeze({
428
- root: "dev/governance_migrations",
429
- entries: Object.freeze(items.filter((item) => item.classifications.includes("transaction-state")).map((item) => item.sourcePath))
430
- })
431
- }),
432
- sourceConservation: Object.freeze({
433
- selection: "known-kit-reachability",
434
- protectedEntryCount: sourceConservationPaths.length,
435
- sourcePaths: Object.freeze(sourceConservationPaths)
436
- }),
437
- items: Object.freeze(items),
438
- unresolved: Object.freeze([...unresolvedItems, ...unresolvedContractTargets]
439
- .sort((left, right) => `${left.sourcePath}\0${left.reason}`.localeCompare(`${right.sourcePath}\0${right.reason}`)))
440
- };
441
- return Object.freeze({ ...body, frozenSetSha256: sha256(Buffer.from(`${JSON.stringify(body)}\n`, "utf8")) });
442
- }
443
-
444
- export function assertGate5FrozenSet(frozen) {
445
- if (!frozen || typeof frozen !== "object" || Array.isArray(frozen)) throw new Error("Gate 5 frozen set is required");
446
- if (frozen.schemaVersion !== GATE5_FROZEN_SET_SCHEMA) throw new Error("unsupported Gate 5 frozen-set schema");
447
- if (frozen.operationAuthority !== "none" || frozen.activationStatus !== "not-authorized") throw new Error("Gate 5 frozen set must not claim operation authority");
448
- if (!Array.isArray(frozen.items) || frozen.items.length === 0) throw new Error("Gate 5 frozen set has no items");
449
- if (!frozen.rootSourceInventory || frozen.rootSourceInventory.schemaVersion !== GATE5_ROOT_SOURCE_INVENTORY_SCHEMA
450
- || !/^[0-9a-f]{64}$/.test(frozen.rootSourceInventory.sha256)
451
- || !Number.isInteger(frozen.rootSourceInventory.entryCount) || frozen.rootSourceInventory.entryCount !== frozen.items.length) {
452
- throw new Error("Gate 5 frozen set does not bind its scoped typed source inventory");
453
- }
454
- if (!frozen.packageContract || !Array.isArray(frozen.packageContract.coverage)) {
455
- throw new Error("Gate 5 frozen set does not bind package-contract coverage");
456
- }
457
- if (!frozen.sourceConservation || frozen.sourceConservation.selection !== "known-kit-reachability"
458
- || !Number.isInteger(frozen.sourceConservation.protectedEntryCount)
459
- || !Array.isArray(frozen.sourceConservation.sourcePaths)) {
460
- throw new Error("Gate 5 frozen set does not define its current-state source-conservation selection");
461
- }
462
- const paths = new Set();
463
- const orderedPaths = [];
464
- for (const item of frozen.items) {
465
- if (!item || typeof item !== "object" || typeof item.sourcePath !== "string" || paths.has(item.sourcePath)) throw new Error("Gate 5 frozen set has duplicate or invalid source paths");
466
- paths.add(item.sourcePath);
467
- orderedPaths.push(item.sourcePath);
468
- if (!/^[0-9a-f]{64}$/.test(item.sourceIdentity?.sha256) || !Number.isInteger(item.sourceIdentity?.bytes) || item.sourceIdentity.bytes < 0) throw new Error(`Gate 5 frozen set source identity is invalid: ${item.sourcePath}`);
469
- if (!Array.isArray(item.classifications) || !item.classifications.includes("root-source")
470
- || !Array.isArray(item.existingReaders) || !item.priorityConflict?.status || !item.effect?.status
471
- || !(item.unresolvedReason === null || typeof item.unresolvedReason === "string")) {
472
- throw new Error(`Gate 5 frozen set omits root-source, reader, priority/conflict, or effect record: ${item.sourcePath}`);
473
- }
474
- if (!item.historicalOrigin && item.ownership !== "user-or-unknown") throw new Error(`Gate 5 frozen set assigns ownership without historical evidence: ${item.sourcePath}`);
475
- if (item.historicalOrigin?.exactPackageBytes && item.packageContract?.scope === "installed" && item.ownership !== "kit-managed-exact") throw new Error(`Gate 5 frozen set rejects exact managed ownership: ${item.sourcePath}`);
476
- if (item.historicalOrigin && !item.historicalOrigin.exactPackageBytes && item.ownership !== "user-or-unknown") throw new Error(`Gate 5 frozen set accepts non-exact package bytes: ${item.sourcePath}`);
477
- }
478
- const expectedUnresolved = frozen.items
479
- .filter((item) => item.unresolvedReason)
480
- .map((item) => `${item.sourcePath}\0${item.unresolvedReason}`);
481
- const actualUnresolved = frozen.unresolved?.map((item) => `${item.sourcePath}\0${item.reason}`) ?? [];
482
- for (const coverage of frozen.packageContract.coverage) {
483
- if (!coverage || typeof coverage.targetRel !== "string" || typeof coverage.sourceStatus !== "string") {
484
- throw new Error("Gate 5 frozen set package-contract coverage is invalid");
485
- }
486
- if (coverage.sourceStatus === "unresolved-missing-installed-source") {
487
- expectedUnresolved.push(`${coverage.targetRel}\0installed package target is missing from the root-source set`);
488
- }
489
- }
490
- const expectedSourceConservationPaths = frozen.items
491
- .filter(gate5ItemRequiresSourceConservation)
492
- .map((item) => item.sourcePath);
493
- if (frozen.sourceConservation.protectedEntryCount !== expectedSourceConservationPaths.length
494
- || JSON.stringify(frozen.sourceConservation.sourcePaths) !== JSON.stringify(expectedSourceConservationPaths)) {
495
- throw new Error("Gate 5 frozen set source-conservation selection does not match known Kit reachability");
496
- }
497
- if (JSON.stringify(orderedPaths) !== JSON.stringify([...orderedPaths].sort((left, right) => left.localeCompare(right)))) {
498
- throw new Error("Gate 5 frozen set items are not in canonical source-path order");
499
- }
500
- if (JSON.stringify(actualUnresolved) !== JSON.stringify([...actualUnresolved].sort((left, right) => left.localeCompare(right)))) {
501
- throw new Error("Gate 5 frozen set unresolved list is not in canonical order");
502
- }
503
- if (JSON.stringify(actualUnresolved) !== JSON.stringify([...expectedUnresolved].sort((left, right) => left.localeCompare(right)))) {
504
- throw new Error("Gate 5 frozen set unresolved list does not exactly match item states");
505
- }
506
- const { frozenSetSha256, ...body } = frozen;
507
- if (frozenSetSha256 !== sha256(Buffer.from(`${JSON.stringify(body)}\n`, "utf8"))) throw new Error("Gate 5 frozen-set digest does not match its contents");
508
- return true;
509
- }
510
-
511
- function normalizeContracts(contracts, transitionContracts) {
512
- const seen = new Set();
513
- const all = [];
514
- for (const [scope, source] of [["installed", contracts], ["transition", transitionContracts]]) {
515
- for (const contract of source) {
516
- if (seen.has(contract.targetRel)) continue;
517
- seen.add(contract.targetRel);
518
- all.push(Object.freeze({ ...contract, scope }));
519
- }
520
- }
521
- return all;
522
- }
523
-
524
- function binding(entryByPath, targetRel) {
525
- const entry = entryByPath.get(targetRel);
526
- return Object.freeze({
527
- path: targetRel,
528
- present: Boolean(entry),
529
- sourceIdentity: entry ? Object.freeze({ sha256: entry.sha256, bytes: entry.bytes }) : null,
530
- readers: entry ? Object.freeze(entry.reachability.map(({ from, via }) => ({ reader: from, via })).filter(({ reader }) => isFormalReader(reader))) : Object.freeze([])
531
- });
532
- }
533
-
534
- function isFormalReader(reader) {
535
- return reader === "formal-entry" || !["managed-contract", "legacy-location", "dynamic-state"].includes(reader);
536
- }
537
-
538
187
  export async function readProjectIndexTemplateVersion(root) {
539
188
  const bytes = await readFile(path.join(root, "dev", "PROJECT_INDEX.md")).catch((error) => {
540
189
  if (error?.code === "ENOENT") return null;
package/package.json CHANGED
@@ -1,20 +1,20 @@
1
- {
2
- "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.53",
4
- "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
- "type": "module",
6
- "bin": {
7
- "agent-handoff-kit": "bin/agent-handoff-kit.mjs"
8
- },
9
- "files": [
10
- "bin/",
11
- "runtime-core/",
12
- "packs/",
13
- "README.md",
14
- "LICENSE"
15
- ],
16
- "engines": {
17
- "node": ">=18"
18
- },
19
- "license": "MIT"
20
- }
1
+ {
2
+ "name": "@adamchanadam/agent-handoff-kit",
3
+ "version": "0.3.55",
4
+ "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
+ "type": "module",
6
+ "bin": {
7
+ "agent-handoff-kit": "bin/agent-handoff-kit.mjs"
8
+ },
9
+ "files": [
10
+ "bin/",
11
+ "runtime-core/",
12
+ "packs/",
13
+ "README.md",
14
+ "LICENSE"
15
+ ],
16
+ "engines": {
17
+ "node": ">=18"
18
+ },
19
+ "license": "MIT"
20
+ }
@@ -17,7 +17,7 @@ Route intent in this order:
17
17
 
18
18
  Treat a phrase as ambiguous only when its ordinary meaning may genuinely refer to a real-world shift, event, or unrelated context. `開工,繼續 <task>`, `<project> 開工`, and `Start Agent Handoff and continue <task>` are continuity commands, not ambiguous phrases.
19
19
 
20
- During explicit continuity startup, the only optional presentation effect beyond state recovery and card/status is a user-visible task/conversation title update, when the active runtime safely supports current-title readback and title control. Replace only a generic or stale title, or update once when the main objective clearly changes; keep an informative title and do not rename for tests, reviews, or small substeps. Use `<project name>|<primary action>` from facts already loaded for startup: a concrete same-message task first, otherwise the loaded current objective plus recommended next action. Do not read `dev/PROJECT_INDEX.md`, files, network, or other state solely to name the title. The title must not contain progress, completion, status, task/session IDs, absolute paths, secrets, or unverified facts. If safe title control/readback is unavailable, skip silently. The title is display-only; it is not project state, permission, progress, completion evidence, a health result, or a source of truth, and it does not authorize project/file writes, network activity, external task work, or continuation beyond the startup boundary.
20
+ During explicit continuity startup, the only optional presentation effect beyond state recovery and card/status is a user-visible task/conversation title update, when the active runtime safely supports current-title readback and title control. Derive the startup card's current objective and recommended next action first; only then, immediately before showing the card, choose and apply any title update. Replace only a generic or stale title, or update once when the main objective clearly changes; keep an informative title and do not rename for tests, reviews, or small substeps. Use `<project name>|<primary action>` from facts already loaded for startup: a concrete same-message task first, otherwise the loaded current objective plus recommended next action. Within those facts, select one concrete primary action in this order: the same-message task; the loaded current objective; the recommended next action. The continuity trigger itself and generic phrases such as `Start Agent Handoff`, `開工`, or `開始工作交接` are not primary actions. If the loaded facts do not provide both a concrete project name and a concrete primary action, skip the title update. Do not read `dev/PROJECT_INDEX.md`, files, network, or other state solely to name the title. The title must not contain progress, completion, status, task/session IDs, absolute paths, secrets, or unverified facts. If safe title control/readback is unavailable, skip silently. The title is display-only; it is not project state, permission, progress, completion evidence, a health result, or a source of truth, and it does not authorize project/file writes, network activity, external task work, or continuation beyond the startup boundary.
21
21
 
22
22
  Read `dev/PROJECT_INDEX.md` when the task needs its file, command, integration, workspace, or source map. Read `dev/RULE_PACKS.md` when a task pack must be selected. Read `dev/DOC_SYNC_REGISTRY.md` before durable cross-file or external synchronization and during closeout. Pack loading is normally silent; explain it only when it changes risk, requires a user decision, or materially affects the next action.
23
23
 
@@ -29,7 +29,7 @@ Probe an integration only immediately before a task uses it, when the handoff ex
29
29
 
30
30
  Show the startup card only for explicit continuity startup. For a plain continuity message, show the card after the minimum state recovery and end the turn; its recommended next action is advice, not permission to act. An explicit same-message task or long-run continuation may combine the card with its first useful action. Direct ordinary tasks do not show the card. If onboarding is explicitly requested, combine any card and guidance in one response.
31
31
 
32
- For explicit bare continuity startup, after the handoff is read, the startup card may read only the bounded version evidence from `dev/PROJECT_INDEX.md`: the unique stable-semver `| Agent Handoff Kit template version | X.Y.Z | ... |` row inside the unique real `## Stack` section. Do not route on, summarize, or load any other Project Index content for startup, title, permissions, packs, health, or task work. Missing, unreadable, malformed, duplicate, prerelease, or out-of-Stack-only version evidence prints `version unverified`; the turn remains status-only with zero writes. A direct ordinary or stateless task does not read the handoff or Project Index merely to fill a card or version.
32
+ For explicit bare continuity startup, after the handoff is read, the startup card may read only the bounded version evidence from `dev/PROJECT_INDEX.md`: the unique stable-semver `| Agent Handoff Kit template version | X.Y.Z | ... |` row inside the unique real `## Stack` section. Do not route on, summarize, or load any other Project Index content for startup, title, permissions, packs, health, or task work. Missing, unreadable, malformed, duplicate, prerelease, or out-of-Stack-only version evidence prints `version unverified`; the turn remains status-only with zero writes. A direct ordinary or stateless task does not read the handoff or Project Index merely to fill a card or version.
33
33
 
34
34
  ```text
35
35
  /\_/\ Agent Handoff Kit v<version>
@@ -112,6 +112,6 @@ Load `dev/rules/integrations.md` when the current task actually uses an external
112
112
 
113
113
  After 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.
114
114
 
115
- ## Core Complexity Rule
116
-
117
- Before changing `AGENTS.md` or adding a durable governance rule, use `dev/RULE_PACKS.md` to load `dev/rules/agent-governance.md` and locate the existing normative owner. Default-core rules must apply to most sessions, protect safety or continuity, and be shorter than the routed detail they replace. Scenario-specific or project-specific detail belongs in an existing pack or registered reference; a new pack is justified only when it creates a smaller, independently loadable responsibility with one normative owner. Do not copy the agent-governance classification table or workflow into the core.
115
+ ## Core Complexity Rule
116
+
117
+ Before changing `AGENTS.md` or adding a durable governance rule, use `dev/RULE_PACKS.md` to load `dev/rules/agent-governance.md` and locate the existing normative owner. Default-core rules must apply to most sessions, protect safety or continuity, and be shorter than the routed detail they replace. Scenario-specific or project-specific detail belongs in an existing pack or registered reference; a new pack is justified only when it creates a smaller, independently loadable responsibility with one normative owner. Do not copy the agent-governance classification table or workflow into the core.
@@ -6,7 +6,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
6
6
 
7
7
  | Field | Value | Last verified |
8
8
  |---|---|---|
9
- | Agent Handoff Kit template version | 0.3.47 | current template version |
9
+ | Agent Handoff Kit template version | 0.3.55 | current template version |
10
10
  | Runtime | TBD | TBD |
11
11
  | Framework | TBD | TBD |
12
12
  | Package manager | TBD | TBD |