@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.
- package/README.en.md +4 -2
- package/README.md +4 -2
- package/bin/agent-handoff-kit.mjs +922 -131
- package/bin/migration-baselines/official-origin-catalog.json +376 -1
- package/bin/upgrade-inventory.mjs +63 -34
- package/package.json +1 -1
- package/runtime-core/AGENTS.core.md +6 -4
- package/runtime-core/SESSION_HANDOFF.md +1 -1
- package/runtime-core/START_NEXT_SESSION_PROMPT.txt +1 -1
|
@@ -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
|
@@ -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
|
-
|
|
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.
|