@adamchanadam/agent-handoff-kit 0.3.50 → 0.3.52

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.
@@ -4,9 +4,9 @@ import path from "node:path";
4
4
  import { installedFileContracts, upgradeStateFileContracts, INSTALLED_FILE_CONTRACT_SCHEMA } from "./installed-file-contract.mjs";
5
5
  import { loadOfficialOriginCatalog } from "./official-origin-catalog.mjs";
6
6
 
7
- export const UPGRADE_INVENTORY_SCHEMA = 1;
8
- export const GATE5_FROZEN_SET_SCHEMA = 2;
9
- export const GATE5_ROOT_SOURCE_INVENTORY_SCHEMA = 1;
7
+ export const UPGRADE_INVENTORY_SCHEMA = 1;
8
+ export const GATE5_FROZEN_SET_SCHEMA = 2;
9
+ export const GATE5_ROOT_SOURCE_INVENTORY_SCHEMA = 1;
10
10
 
11
11
  const formalEntryTargets = Object.freeze([
12
12
  "AGENTS.md",
@@ -15,11 +15,20 @@ const formalEntryTargets = Object.freeze([
15
15
  "START_NEXT_SESSION_PROMPT.txt"
16
16
  ]);
17
17
 
18
- const dynamicDirectories = Object.freeze([
19
- { relative: "dev/governance_migrations", classification: "transaction-state" },
20
- { relative: "dev/SESSION_LOG_archive", classification: "session-log-archive" },
21
- { relative: "dev/session_log_archive", classification: "legacy-session-log-archive" }
22
- ]);
18
+ const dynamicDirectories = Object.freeze([
19
+ { relative: "dev/governance_migrations", classification: "transaction-state" },
20
+ { relative: "dev/SESSION_LOG_archive", classification: "session-log-archive" },
21
+ { relative: "dev/session_log_archive", classification: "legacy-session-log-archive" }
22
+ ]);
23
+
24
+ export function gate5ItemRequiresSourceConservation(item) {
25
+ return Boolean(item && Array.isArray(item.classifications)
26
+ && item.classifications.some((classification) => classification !== "root-source"));
27
+ }
28
+
29
+ export function gate5SourceConservationItems(frozen) {
30
+ return Object.freeze((frozen?.items ?? []).filter(gate5ItemRequiresSourceConservation));
31
+ }
23
32
 
24
33
  /**
25
34
  * Builds a read-only, hash-bound description of the Kit data that an upgrade
@@ -421,10 +430,13 @@ export async function freezeGate5Set({ root, contracts = installedFileContracts,
421
430
  const unresolvedContractTargets = contractCoverage
422
431
  .filter((item) => item.sourceStatus === "unresolved-missing-installed-source")
423
432
  .map((item) => Object.freeze({ sourcePath: item.targetRel, reason: "installed package target is missing from the root-source set" }));
424
- const bridgePaths = ["CLAUDE.md", "GEMINI.md"];
425
- const body = {
426
- schemaVersion: GATE5_FROZEN_SET_SCHEMA,
427
- operationAuthority: "none",
433
+ const bridgePaths = ["CLAUDE.md", "GEMINI.md"];
434
+ const sourceConservationPaths = items
435
+ .filter(gate5ItemRequiresSourceConservation)
436
+ .map((item) => item.sourcePath);
437
+ const body = {
438
+ schemaVersion: GATE5_FROZEN_SET_SCHEMA,
439
+ operationAuthority: "none",
428
440
  activationStatus: "not-authorized",
429
441
  inventory: Object.freeze({ schemaVersion: inventory.schemaVersion, sha256: inventory.inventorySha256 }),
430
442
  rootSourceInventory: Object.freeze({
@@ -448,18 +460,23 @@ export async function freezeGate5Set({ root, contracts = installedFileContracts,
448
460
  packageIntegrity: release?.source?.npm?.integrity ?? null,
449
461
  status: release ? "bound-to-installed-catalog-identity" : "unresolved-no-catalog-release-for-installed-version"
450
462
  }),
451
- formalSurfaces: Object.freeze({
452
- entry: binding(entryByPath, "AGENTS.md"),
453
- bridges: Object.freeze(bridgePaths.map((targetRel) => binding(entryByPath, targetRel))),
454
- router: binding(entryByPath, "dev/USER_RULES.md"),
463
+ formalSurfaces: Object.freeze({
464
+ entry: binding(entryByPath, "AGENTS.md"),
465
+ bridges: Object.freeze(bridgePaths.map((targetRel) => binding(entryByPath, targetRel))),
466
+ router: binding(entryByPath, "dev/USER_RULES.md"),
455
467
  transactionRegistry: Object.freeze({
456
468
  root: "dev/governance_migrations",
457
- entries: Object.freeze(items.filter((item) => item.classifications.includes("transaction-state")).map((item) => item.sourcePath))
458
- })
459
- }),
460
- items: Object.freeze(items),
461
- unresolved: Object.freeze([...unresolvedItems, ...unresolvedContractTargets]
462
- .sort((left, right) => `${left.sourcePath}\0${left.reason}`.localeCompare(`${right.sourcePath}\0${right.reason}`)))
469
+ entries: Object.freeze(items.filter((item) => item.classifications.includes("transaction-state")).map((item) => item.sourcePath))
470
+ })
471
+ }),
472
+ sourceConservation: Object.freeze({
473
+ selection: "known-kit-reachability",
474
+ protectedEntryCount: sourceConservationPaths.length,
475
+ sourcePaths: Object.freeze(sourceConservationPaths)
476
+ }),
477
+ items: Object.freeze(items),
478
+ unresolved: Object.freeze([...unresolvedItems, ...unresolvedContractTargets]
479
+ .sort((left, right) => `${left.sourcePath}\0${left.reason}`.localeCompare(`${right.sourcePath}\0${right.reason}`)))
463
480
  };
464
481
  return Object.freeze({ ...body, frozenSetSha256: sha256(Buffer.from(`${JSON.stringify(body)}\n`, "utf8")) });
465
482
  }
@@ -475,12 +492,17 @@ export function assertGate5FrozenSet(frozen) {
475
492
  || !Array.isArray(frozen.rootSourceInventory.exclusions)) {
476
493
  throw new Error("Gate 5 frozen set does not bind a complete root-source inventory");
477
494
  }
478
- if (!frozen.packageContract || !Array.isArray(frozen.packageContract.coverage)) {
479
- throw new Error("Gate 5 frozen set does not bind package-contract coverage");
480
- }
481
- const paths = new Set();
482
- const orderedPaths = [];
483
- for (const item of frozen.items) {
495
+ if (!frozen.packageContract || !Array.isArray(frozen.packageContract.coverage)) {
496
+ throw new Error("Gate 5 frozen set does not bind package-contract coverage");
497
+ }
498
+ if (!frozen.sourceConservation || frozen.sourceConservation.selection !== "known-kit-reachability"
499
+ || !Number.isInteger(frozen.sourceConservation.protectedEntryCount)
500
+ || !Array.isArray(frozen.sourceConservation.sourcePaths)) {
501
+ throw new Error("Gate 5 frozen set does not define its current-state source-conservation selection");
502
+ }
503
+ const paths = new Set();
504
+ const orderedPaths = [];
505
+ for (const item of frozen.items) {
484
506
  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");
485
507
  paths.add(item.sourcePath);
486
508
  orderedPaths.push(item.sourcePath);
@@ -503,12 +525,19 @@ export function assertGate5FrozenSet(frozen) {
503
525
  throw new Error("Gate 5 frozen set package-contract coverage is invalid");
504
526
  }
505
527
  if (coverage.sourceStatus === "unresolved-missing-installed-source") {
506
- expectedUnresolved.push(`${coverage.targetRel}\0installed package target is missing from the root-source set`);
507
- }
508
- }
509
- if (JSON.stringify(orderedPaths) !== JSON.stringify([...orderedPaths].sort((left, right) => left.localeCompare(right)))) {
510
- throw new Error("Gate 5 frozen set items are not in canonical source-path order");
511
- }
528
+ expectedUnresolved.push(`${coverage.targetRel}\0installed package target is missing from the root-source set`);
529
+ }
530
+ }
531
+ const expectedSourceConservationPaths = frozen.items
532
+ .filter(gate5ItemRequiresSourceConservation)
533
+ .map((item) => item.sourcePath);
534
+ if (frozen.sourceConservation.protectedEntryCount !== expectedSourceConservationPaths.length
535
+ || JSON.stringify(frozen.sourceConservation.sourcePaths) !== JSON.stringify(expectedSourceConservationPaths)) {
536
+ throw new Error("Gate 5 frozen set source-conservation selection does not match known Kit reachability");
537
+ }
538
+ if (JSON.stringify(orderedPaths) !== JSON.stringify([...orderedPaths].sort((left, right) => left.localeCompare(right)))) {
539
+ throw new Error("Gate 5 frozen set items are not in canonical source-path order");
540
+ }
512
541
  if (JSON.stringify(actualUnresolved) !== JSON.stringify([...actualUnresolved].sort((left, right) => left.localeCompare(right)))) {
513
542
  throw new Error("Gate 5 frozen set unresolved list is not in canonical order");
514
543
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.50",
3
+ "version": "0.3.52",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -11,13 +11,15 @@ Do not read `dev/SESSION_LOG.md` during ordinary startup; it is trace-back evide
11
11
  Route intent in this order:
12
12
 
13
13
  1. Clear closeout intent routes directly to `dev/rules/closeout.md`.
14
- 2. Clear continuity intent such as "開工", "Start Agent Handoff", "開始接力", or "continue handoff" resumes the minimum current state from the handoff. A plain continuity message with no same-message task or explicit long-run instruction authorizes only that recovery, 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, writes, network access, or opt-out wording such as "unless you object I will start". A concrete objective found only in loaded state is not authority to complete it. A same-message task may begin normally. An explicit instruction such as "開工,繼續做到下一個 blocker" or "開工,繼續完成目前目標" may continue under the normal task and safety rules.
14
+ 2. Clear continuity intent such as "開工", "Start Agent Handoff", "開始接力", or "continue handoff" resumes the minimum current state from the handoff. A plain continuity message with no same-message task or explicit long-run instruction authorizes only that recovery, one optional display-only title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out wording such as "unless you object I will start". A concrete objective found only in loaded state is not authority to complete it. A same-message task may begin normally. An explicit instruction such as "開工,繼續做到下一個 blocker" or "開工,繼續完成目前目標" may continue under the normal task and safety rules.
15
15
  3. A direct ordinary task begins without a startup card or onboarding ceremony. Read only the sources and packs required by that task.
16
16
  4. Explicit guidance requests such as "I'm new", "teach me", "help me start", "新手", "教我用", or "點開始" may load `dev/rules/onboarding.md`. A fresh install or short message only makes guidance available; it never overrides a concrete objective. If no executable objective remains after state reading, ask one concise question or offer guided onboarding.
17
17
 
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
-
20
- 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.
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
+
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.
21
+
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.
21
23
 
22
24
  If 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.
23
25
 
@@ -156,5 +156,5 @@ Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Tr
156
156
 
157
157
  If the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.
158
158
 
159
- Resume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, 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, writes, network access, or opt-out execution wording. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading.
159
+ Resume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, one optional display-only title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out execution wording. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading.
160
160
  ```
@@ -2,4 +2,4 @@ Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Tr
2
2
 
3
3
  If the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.
4
4
 
5
- Resume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, 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, writes, network access, or opt-out execution wording. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading.
5
+ Resume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, one optional display-only title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out execution wording. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading.