@adamchanadam/agent-handoff-kit 0.3.49 → 0.3.51
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 +1 -1
- package/README.md +1 -1
- package/bin/agent-handoff-kit.mjs +366 -37
- package/bin/migration-baselines/official-origin-catalog.json +376 -1
- package/bin/upgrade-inventory.mjs +63 -34
- package/package.json +1 -1
- package/packs/closeout.md +5 -3
- package/packs/integrations.md +7 -4
- package/packs/knowledge.md +1 -1
- package/runtime-core/AGENTS.core.md +2 -2
|
@@ -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
|
|
426
|
-
|
|
427
|
-
|
|
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
|
-
|
|
461
|
-
|
|
462
|
-
.
|
|
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
|
-
|
|
482
|
-
|
|
483
|
-
|
|
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
|
-
|
|
510
|
-
|
|
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
package/packs/closeout.md
CHANGED
|
@@ -22,9 +22,11 @@ Use Kit markers as machine boundaries: `ack:section:*`, `ack:field:*`, `ack:log-
|
|
|
22
22
|
|
|
23
23
|
Do not copy the full opening message into `dev/SESSION_LOG.md` or any third current governance file. The log records that the mirror was regenerated and verified, plus an evidence reference when useful.
|
|
24
24
|
|
|
25
|
-
## Full Closeout
|
|
26
|
-
|
|
27
|
-
|
|
25
|
+
## Full Closeout
|
|
26
|
+
|
|
27
|
+
Full closeout is differential. Reuse a completed task check only when its recorded root, task input, tool identity, commit / artifact identity, and required file hashes still match the current state. Do not rerun task QA that is already bound to unchanged identity. Do rerun checks affected by closeout writes, gates that are incomplete or indeterminate, closeout-specific checks, and the final `closeout-status` read-back. If a closeout attempt is interrupted, stopped, aborted, times out, or hits a spawn / transport error, resume at the first incomplete or indeterminate gate; do not restart from the beginning unless the root, input, tool identity, commit, artifact, or relevant hash changed.
|
|
28
|
+
|
|
29
|
+
1. Reconcile `dev/SESSION_HANDOFF.md`; never append a new current-state snapshot beneath an old one. Verify durable anchors, then rewrite or explicitly confirm every closeout-reconciled section.
|
|
28
30
|
2. Reconcile lifecycle state across `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. Completed or verified work cannot remain unresolved unless explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with its missing evidence or trigger.
|
|
29
31
|
The bundled doctor is a mechanical floor for obvious overlap and unresolved fields; it cannot prove that renamed or paraphrased work is semantically consistent. Read all five sections as a whole before marking the lifecycle field resolved. For governance, release, or another project-defined high-risk completion, use the project's independent semantic review gate in addition to doctor.
|
|
30
32
|
3. Make `Next Priorities` name one recommended next action and a short reason unless blocked or a real user decision is required.
|
package/packs/integrations.md
CHANGED
|
@@ -190,14 +190,15 @@ Integration declarations are project-level; they do not guarantee every AI runti
|
|
|
190
190
|
2. **External Tool Usage Verification Gate**: verify current runtime schema, official docs, official types/samples, or registered tool operation references before invoking or retrying external tools.
|
|
191
191
|
3. **Declaration before use**: read `dev/PROJECT_INDEX.md` `## Installed Integrations` and `## Tool Operation References` before external-tool or runtime-controlled tool-operation work. If absent, ask about integration status rather than assuming none exists.
|
|
192
192
|
4. **Connector-first default**: when a declared integration is functional, prefer the verified direct tool call. Manual paste is fallback, not default.
|
|
193
|
-
5. **Write operations require read-back verification**: read back every external write before claiming success.
|
|
193
|
+
5. **Write operations require read-back verification**: read back every external write before claiming success.
|
|
194
194
|
6. **No auto-fix credential / auth issues**: surface auth failures to the user and point to the runtime settings or tool owner.
|
|
195
195
|
7. **Cross-tool capability awareness**: verify availability immediately before use, when the current objective declares the integration as a dependency, or when the user requests a health check.
|
|
196
196
|
8. **Do not cross source-of-truth layers**: follow the role and write direction declared in `PROJECT_INDEX`.
|
|
197
197
|
9. **Drift event mandatory recording**: record integration drift in `PROJECT_INDEX`, `SESSION_LOG`, and `SESSION_HANDOFF` when it affects future work.
|
|
198
198
|
10. **Plugin / Skill subordination**: plugin and skill instructions coexist with rule packs; safety, governance, and closeout rules take precedence on conflict.
|
|
199
199
|
11. **External tool resource lifecycle**: after external-tool use, classify resources by ownership. Task-owned / agent-managed resources may be closed or cleaned automatically; shared, user-owned, system-level, other-agent-owned, or unknown resources require evidence reporting and user confirmation before remediation.
|
|
200
|
-
12. **Local HTML / app validation fallback**: if `file://` browser access is blocked, do not bypass the policy and do not stop on that single surface failure. Use a registered operation reference or a short-lived loopback localhost service for actual browser / DevTools / Playwright validation, then close the task-owned service and record the evidence.
|
|
200
|
+
12. **Local HTML / app validation fallback**: if `file://` browser access is blocked, do not bypass the policy and do not stop on that single surface failure. Use a registered operation reference or a short-lived loopback localhost service for actual browser / DevTools / Playwright validation, then close the task-owned service and record the evidence.
|
|
201
|
+
13. **Terminal-state contract**: a tool operation succeeds only when the runtime returns an explicit successful terminal state and any required read-back passes. Stopped, aborted, timeout, spawn / transport error, signal, missing final result, or partial stdout before termination makes the affected operation indeterminate or failed, not successful. It does not make unrelated already-verified task evidence permanently invalid. For read-only operations, verify the state and rerun only the affected operation when still needed. For any operation that may have written externally or to disk, read back the actual target state before retrying, recovery, or success claims.
|
|
201
202
|
|
|
202
203
|
## Checks
|
|
203
204
|
|
|
@@ -210,7 +211,8 @@ Integration declarations are project-level; they do not guarantee every AI runti
|
|
|
210
211
|
- Before closeout, update `Last Verified` for integrations touched this session.
|
|
211
212
|
- Self-check credential leakage before writing `PROJECT_INDEX`, `SESSION_HANDOFF`, or `SESSION_LOG`.
|
|
212
213
|
- Verify that `PROJECT_INDEX` External Sources `via` references match declared Installed Integrations entries.
|
|
213
|
-
- For local HTML / app validation, verify that a rejected `file://` attempt is followed by a registered operation reference or short-lived localhost fallback before declaring `blocked`.
|
|
214
|
+
- For local HTML / app validation, verify that a rejected `file://` attempt is followed by a registered operation reference or short-lived localhost fallback before declaring `blocked`.
|
|
215
|
+
- Treat stopped, aborted, timeout, spawn / transport error, signal, and missing final result as operation-level indeterminate / failed states. Never count partial stdout, a wrapper exit code, or an outer command's success as terminal success without the expected final state and read-back.
|
|
214
216
|
|
|
215
217
|
## Closeout
|
|
216
218
|
|
|
@@ -235,7 +237,8 @@ Integration declarations are project-level; they do not guarantee every AI runti
|
|
|
235
237
|
| Auto-fixing auth or re-auth flows | Auth belongs to the user and the runtime/tool boundary. | Surface the failure and point to the runtime or tool settings. |
|
|
236
238
|
| Claiming an external write succeeded without read-back | External writes may fail silently or partially. | Read back and compare before claiming success. |
|
|
237
239
|
| Crossing source-of-truth layers | It can corrupt truth, mirrors, or working drafts. | Follow the declared layer role and write direction in `PROJECT_INDEX`. |
|
|
238
|
-
| Skipping
|
|
240
|
+
| Skipping current availability verification because an old handoff said the tool worked | Tokens expire, runtimes change, and tools can be removed. | Probe availability in the current runtime before using the integration. |
|
|
241
|
+
| Treating stopped, aborted, timeout, spawn / transport error, signal, missing final result, or partial PASS output as success | Tool output can be partial, wrappers can hide inner failure, and external writes may be unknown. | Mark the affected operation indeterminate or failed; read back any possible write target before retrying or claiming success. |
|
|
239
242
|
| Leaving task-owned MCP / browser / helper processes running after the task | Turns one-off tool use into a long-lived resource leak and can slow the host. | Use graceful close or task-owned process cleanup automatically; switch to user confirmation only when ownership is unclear. |
|
|
240
243
|
| Broadly killing by process name such as `node.exe`, `python`, or `chrome` | A generic process name does not prove ownership and may terminate user work, another project, or another AI agent's active tools. | Classify by tool family, process ID, start time, parent chain, and task-created path; treat unknown ownership as shared. |
|
|
241
244
|
| Automatically cleaning global caches, marketplace caches, OS temp roots, or browser profiles | May remove shared state, login state, or data other tools still need. | Automatically clean only task-owned / agent-managed bounded paths; report evidence and wait for confirmation otherwise. |
|
package/packs/knowledge.md
CHANGED
|
@@ -17,7 +17,7 @@ Use for external notes, knowledge bases, Notion, Obsidian, Drive, docs repositor
|
|
|
17
17
|
4. Do not perform destructive external writes without explicit confirmation.
|
|
18
18
|
5. Connector-first default for external read/write (R-030 Integration governance discipline; works together with `dev/rules/integrations.md`):
|
|
19
19
|
(a) Before reading or writing external knowledge, check `dev/PROJECT_INDEX.md` `## Installed Integrations` for declared tool availability.
|
|
20
|
-
(b) If a declared Integration is functional in the current session (verified
|
|
20
|
+
(b) If a declared Integration is functional in the current session (verified under the task-triggered availability probe in `runtime-core/AGENTS.core.md` Section 1): use only the active runtime tool calls whose current name, description, and input schema have been inspected under the External Tool Usage Verification Gate. Do not invent `mcp__*` names or arguments from examples or memory.
|
|
21
21
|
(c) If a declared Integration is unavailable in the current session (different AI tool / Connector not configured / auth expired): degrade to manual paste packet workflow + flag drift in the mid-task summary + update `Last Verified` cell at closeout.
|
|
22
22
|
(d) If no declaration exists in `## Installed Integrations` but the task references an external tool: ask the user about Integration status before proceeding (do not silently assume paste fallback). Backward-compat: existing v0.2.x projects with no Installed Integrations section follow path (d) — the section template auto-appends on upgrade but content stays empty until user declares; AI behavior degrades gracefully to ask-user fallback.
|
|
23
23
|
6. When writing to an external mirror or index, read back the written record before claiming sync success.
|
|
@@ -59,8 +59,8 @@ In every user-facing reply, lead with ordinary language: state the result and it
|
|
|
59
59
|
Choose exactly one tier after a task:
|
|
60
60
|
|
|
61
61
|
1. No persistence: no durable fact was produced. One-off answers, transient output, active unapproved drafts, and routine rerunnable checks normally use this tier.
|
|
62
|
-
2. Lightweight checkpoint: a durable fact affects future action while the session continues or may be interrupted. Write only its smallest correct home; do not regenerate the startup mirror or perform full closeout.
|
|
63
|
-
3. Full closeout: explicit end-of-session / handoff intent, a
|
|
62
|
+
2. Lightweight checkpoint: a durable fact affects future action while the session continues or may be interrupted. This is the default for ongoing sessions. Write only its smallest correct home; do not regenerate the startup mirror or perform full closeout.
|
|
63
|
+
3. 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.
|
|
64
64
|
|
|
65
65
|
Route 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.
|
|
66
66
|
|