@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.
- package/README.en.md +1 -1
- package/README.md +1 -1
- package/bin/agent-handoff-kit.mjs +3885 -6845
- package/bin/installed-file-contract.mjs +11 -11
- package/bin/migration-baselines/official-origin-catalog.json +371 -1
- package/bin/upgrade-inventory.mjs +7 -358
- package/package.json +20 -20
- package/runtime-core/AGENTS.core.md +5 -5
- package/runtime-core/PROJECT_INDEX.md +1 -1
|
@@ -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
|
|
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
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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.
|
|
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.
|
|
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 |
|