@adamchanadam/agent-handoff-kit 0.4.2 → 0.4.3

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.
Files changed (46) hide show
  1. package/LICENSE +21 -21
  2. package/README.en.md +1 -1
  3. package/README.md +1 -1
  4. package/bin/agent-handoff-kit.mjs +7107 -7047
  5. package/bin/commands.mjs +134 -134
  6. package/bin/handoff-read.mjs +88 -88
  7. package/bin/installed-file-contract.mjs +154 -90
  8. package/bin/migration-baselines/official-origin-catalog.json +280 -1
  9. package/bin/official-origin-catalog.mjs +294 -294
  10. package/bin/progress/ICON-LICENSE.txt +21 -21
  11. package/bin/progress/assets.mjs +6 -6
  12. package/bin/progress/dashboard.mjs +134 -134
  13. package/bin/progress/icons.svg +36 -36
  14. package/bin/progress/index.html +31 -31
  15. package/bin/progress/launch.mjs +40 -40
  16. package/bin/progress/open.mjs +43 -43
  17. package/bin/progress/project-version.mjs +121 -121
  18. package/bin/progress/projection.mjs +144 -144
  19. package/bin/progress/renderer.js +152 -152
  20. package/bin/progress/server.mjs +78 -78
  21. package/bin/progress/styles.css +31 -31
  22. package/bin/prompt-mirror-core.mjs +84 -84
  23. package/bin/upgrade-inventory.mjs +243 -243
  24. package/bin/user-rules-router.mjs +4 -4
  25. package/docs/commands.md +2 -2
  26. package/docs/progress.md +73 -73
  27. package/package.json +22 -22
  28. package/packs/agent-governance.md +120 -120
  29. package/packs/closeout.md +91 -91
  30. package/packs/coding.md +28 -28
  31. package/packs/integrations.md +19 -19
  32. package/packs/knowledge.md +3 -3
  33. package/packs/onboarding.md +45 -45
  34. package/packs/research.md +30 -30
  35. package/packs/safety.md +2 -2
  36. package/runtime-core/AGENTS.core.md +161 -161
  37. package/runtime-core/CLAUDE.md +13 -13
  38. package/runtime-core/DOC_SYNC_REGISTRY.md +24 -24
  39. package/runtime-core/GEMINI.md +17 -17
  40. package/runtime-core/PROJECT_DECISIONS.md +43 -43
  41. package/runtime-core/PROJECT_INDEX.md +16 -16
  42. package/runtime-core/RULE_PACKS.md +1 -1
  43. package/runtime-core/SESSION_HANDOFF.md +180 -180
  44. package/runtime-core/SESSION_LOG.md +37 -37
  45. package/runtime-core/START_NEXT_SESSION_PROMPT.txt +1 -1
  46. package/runtime-core/USER_RULES_ENTRY.md +5 -5
@@ -1,90 +1,154 @@
1
- // Single source of truth for the current file lifecycle Agent Handoff Kit
2
- // installs and upgrades. Fresh-only files are declared separately so their
3
- // path cannot silently become current lifecycle authority before that route is
4
- // explicitly present.
5
-
6
- import { commands, commandFiles } from './commands.mjs';
7
-
8
- // Source-to-delivery routing. Unknown new shipped modules must receive an owner.
9
- // QA stages/evidence are defined by the existing assurance gate, not runtime doctor.
10
- export const deliveredFeatureContracts = Object.freeze([
11
- {id:'installer',sources:['package.json','bin/agent-handoff-kit.mjs','bin/installed-file-contract.mjs','bin/official-origin-catalog.mjs','bin/migration-baselines/','bin/upgrade-inventory.mjs','bin/user-rules-router.mjs']},
12
- {id:'shortcuts',sources:['bin/commands.mjs'],requiredForFull:true,hosts:['claude','gemini','codex','antigravity'],nativeAcceptanceHosts:['codex'],nativeInvocationEntries:commands.map(({name})=>name)},
13
- {id:'dashboard',sources:['bin/progress/']},
14
- {id:'continuity',sources:['runtime-core/','bin/handoff-read.mjs','bin/prompt-mirror-core.mjs']},
15
- {id:'task-packs',sources:['packs/']}
16
- ].map(x=>Object.freeze(x)));
17
-
18
- export const INSTALLED_FILE_CONTRACT_SCHEMA = 1;
19
- // Generated project entries share one content owner. Only these exact paths
20
- // enter installer recovery; platform directories are never blanket-owned.
21
- export const SHORTCUT_INSTALL_CONTRACT = 1;
22
- export const requiredShortcutTargets = Object.freeze(commandFiles().map(({file})=>file));
23
-
24
- export const installedFileContracts = Object.freeze([
25
- contract("runtime-core/AGENTS.core.md", "AGENTS.md", "managed-core"),
26
- contract("runtime-core/CLAUDE.md", "CLAUDE.md", "strict-bridge"),
27
- contract("runtime-core/GEMINI.md", "GEMINI.md", "strict-bridge"),
28
- contract("runtime-core/START_NEXT_SESSION_PROMPT.txt", "START_NEXT_SESSION_PROMPT.txt", "generated-state"),
29
- contract("runtime-core/SESSION_HANDOFF.md", "dev/SESSION_HANDOFF.md", "stateful-handoff"),
30
- contract("runtime-core/SESSION_LOG.md", "dev/SESSION_LOG.md", "stateful-log"),
31
- contract("runtime-core/PROJECT_INDEX.md", "dev/PROJECT_INDEX.md", "stateful-index"),
32
- contract("runtime-core/DOC_SYNC_REGISTRY.md", "dev/DOC_SYNC_REGISTRY.md", "stateful-registry"),
33
- contract("runtime-core/RULE_PACKS.md", "dev/RULE_PACKS.md", "marked-routing-table"),
34
- contract("runtime-core/PROJECT_DECISIONS.md", "dev/PROJECT_DECISIONS.md", "stateful-decisions"),
35
- contract("packs/safety.md", "dev/rules/safety.md", "rule-pack"),
36
- contract("packs/coding.md", "dev/rules/coding.md", "rule-pack"),
37
- contract("packs/writing.md", "dev/rules/writing.md", "rule-pack"),
38
- contract("packs/research.md", "dev/rules/research.md", "rule-pack"),
39
- contract("packs/agent-governance.md", "dev/rules/agent-governance.md", "rule-pack"),
40
- contract("packs/release.md", "dev/rules/release.md", "rule-pack"),
41
- contract("packs/knowledge.md", "dev/rules/knowledge.md", "rule-pack"),
42
- contract("packs/communication.md", "dev/rules/communication.md", "rule-pack"),
43
- contract("packs/closeout.md", "dev/rules/closeout.md", "rule-pack"),
44
- contract("packs/onboarding.md", "dev/rules/onboarding.md", "rule-pack"),
45
- contract("packs/integrations.md", "dev/rules/integrations.md", "rule-pack")
46
- ]);
47
-
48
- export const installedMappings = Object.freeze(
49
- installedFileContracts.map(({ sourceRel, targetRel }) => Object.freeze([sourceRel, targetRel]))
50
- );
51
-
52
- // The router is installed on fresh roots, but is not evidence that an arbitrary
53
- // mixed file is Kit-managed. Its upgrade treatment lives in a separate current
54
- // transition contract below rather than broad path ownership.
55
- export const freshInstallFileContracts = Object.freeze([
56
- ...installedFileContracts,
57
- contract("runtime-core/USER_RULES.md", "dev/USER_RULES.md", "fresh-user-router")
58
- ]);
59
-
60
- export const freshInstallMappings = Object.freeze(
61
- freshInstallFileContracts.map(({ sourceRel, targetRel }) => Object.freeze([sourceRel, targetRel]))
62
- );
63
-
64
- // Formal user-rule state is part of an upgrade only when the existing AGENTS.md
65
- // entry and router form one verifiable current formal state. This separate
66
- // contract deliberately does not reclassify a path, title, or directory as Kit
67
- // authority.
68
- export const upgradeStateFileContracts = Object.freeze([
69
- contract("runtime-core/USER_RULES.md", "dev/USER_RULES.md", "accepted-user-rules-router")
70
- ]);
71
-
72
- export const upgradeStateMappings = Object.freeze(
73
- upgradeStateFileContracts.map(({ sourceRel, targetRel }) => Object.freeze([sourceRel, targetRel]))
74
- );
75
-
76
- export const upgradeStateTargets = Object.freeze(
77
- upgradeStateFileContracts.map(({ targetRel }) => targetRel)
78
- );
79
-
80
- export const requiredInstalledTargets = Object.freeze(
81
- installedFileContracts.map(({ targetRel }) => targetRel)
82
- );
83
-
84
- export function installedFileContract(targetRel) {
85
- return installedFileContracts.find((item) => item.targetRel === targetRel) ?? null;
86
- }
87
-
88
- function contract(sourceRel, targetRel, strategy) {
89
- return Object.freeze({ sourceRel, targetRel, strategy });
90
- }
1
+ // Single source of truth for the current file lifecycle Agent Handoff Kit
2
+ // installs and upgrades. Fresh-only files are declared separately so their
3
+ // path cannot silently become current lifecycle authority before that route is
4
+ // explicitly present.
5
+
6
+ import { commands, commandFiles } from './commands.mjs';
7
+
8
+ // Source-to-delivery routing. Unknown new shipped modules must receive an owner.
9
+ // QA stages/evidence are defined by the existing assurance gate, not runtime doctor.
10
+ export const deliveredFeatureContracts = Object.freeze([
11
+ {id:'installer',sources:['package.json','bin/agent-handoff-kit.mjs','bin/installed-file-contract.mjs','bin/official-origin-catalog.mjs','bin/migration-baselines/','bin/upgrade-inventory.mjs','bin/user-rules-router.mjs']},
12
+ {id:'shortcuts',sources:['bin/commands.mjs'],hosts:['claude','gemini','codex','antigravity'],nativeAcceptanceHosts:['codex'],nativeInvocationEntries:commands.map(({name})=>name)},
13
+ {id:'dashboard',sources:['bin/progress/']},
14
+ {id:'continuity',sources:['runtime-core/','bin/handoff-read.mjs','bin/prompt-mirror-core.mjs']},
15
+ {id:'task-packs',sources:['packs/']}
16
+ ].map(x=>Object.freeze(x)));
17
+
18
+ // These are delivery dependencies, not runtime ownership. They decide whether
19
+ // a historical shortcut raw case can still describe the current package.
20
+ export const packageInstallDependencyRoots=Object.freeze([
21
+ 'package.json','bin/agent-handoff-kit.mjs','bin/commands.mjs','bin/installed-file-contract.mjs',
22
+ 'bin/official-origin-catalog.mjs','bin/migration-baselines/','bin/upgrade-inventory.mjs','bin/user-rules-router.mjs',
23
+ 'bin/handoff-read.mjs','bin/prompt-mirror-core.mjs','bin/progress/','runtime-core/','packs/'
24
+ ]);
25
+ const sharedShortcutDependencyRoots=Object.freeze(['bin/commands.mjs','runtime-core/']);
26
+ const shortcutEntrySpecificDependencyRoots=Object.freeze({
27
+ 'handoff-kit-start':Object.freeze(['bin/agent-handoff-kit.mjs','bin/handoff-read.mjs','packs/onboarding.md']),
28
+ 'handoff-kit-close':Object.freeze([...packageInstallDependencyRoots,'packs/closeout.md','packs/safety.md']),
29
+ 'handoff-kit-progress':Object.freeze(['package.json','bin/progress/']),
30
+ 'handoff-kit-align':Object.freeze(['packs/agent-governance.md']),
31
+ 'handoff-kit-onboard':Object.freeze(['packs/onboarding.md']),
32
+ 'handoff-kit-remember':Object.freeze(['packs/agent-governance.md']),
33
+ 'handoff-kit-check':packageInstallDependencyRoots,
34
+ 'handoff-kit-update':packageInstallDependencyRoots,
35
+ 'handoff-kit-help':Object.freeze([])
36
+ });
37
+ export function dependencyRootMatches(file,root){return root.endsWith('/')?file.startsWith(root):file===root;}
38
+ export function shortcutEntryDependencyRoots(entry){
39
+ if(!Object.hasOwn(shortcutEntrySpecificDependencyRoots,entry))throw Error(`Unknown shortcut delivery dependency entry: ${entry}`);
40
+ return Object.freeze([...new Set([...sharedShortcutDependencyRoots,...shortcutEntrySpecificDependencyRoots[entry]])]);
41
+ }
42
+
43
+ // Native acceptance scope is narrower than reuse scope. Reuse stays
44
+ // conservative because it decides whether old evidence remains applicable;
45
+ // this map decides which *new* real user journey can change in the diff.
46
+ const sharedNativeShortcutRoots=Object.freeze(['bin/commands.mjs','runtime-core/','bin/installed-file-contract.mjs']);
47
+ const shortcutEntryNativeRoots=Object.freeze({
48
+ 'handoff-kit-start':Object.freeze(['bin/handoff-read.mjs','packs/onboarding.md']),
49
+ 'handoff-kit-close':Object.freeze(['bin/agent-handoff-kit.mjs','bin/prompt-mirror-core.mjs','packs/closeout.md','packs/safety.md']),
50
+ 'handoff-kit-progress':Object.freeze(['bin/progress/']),
51
+ 'handoff-kit-align':Object.freeze(['packs/agent-governance.md']),
52
+ 'handoff-kit-onboard':Object.freeze(['packs/onboarding.md']),
53
+ 'handoff-kit-remember':Object.freeze(['packs/agent-governance.md','packs/coding.md','packs/writing.md','packs/research.md','packs/release.md','packs/knowledge.md','packs/communication.md','packs/integrations.md','packs/safety.md','packs/closeout.md','packs/onboarding.md']),
54
+ 'handoff-kit-check':Object.freeze(['bin/agent-handoff-kit.mjs','bin/official-origin-catalog.mjs','bin/migration-baselines/','bin/upgrade-inventory.mjs','bin/user-rules-router.mjs']),
55
+ 'handoff-kit-update':Object.freeze(['bin/agent-handoff-kit.mjs','bin/official-origin-catalog.mjs','bin/migration-baselines/','bin/upgrade-inventory.mjs','bin/user-rules-router.mjs']),
56
+ 'handoff-kit-help':Object.freeze([])
57
+ });
58
+ const shippedDocumentation=Object.freeze(['README.md','docs/commands.md','docs/progress.md','LICENSE']);
59
+ function isShippedRuntimeSource(file){return file==='package.json'||file.startsWith('bin/')||file.startsWith('runtime-core/')||file.startsWith('packs/');}
60
+ export function shortcutEntryNativeRootsFor(entry){
61
+ if(!Object.hasOwn(shortcutEntryNativeRoots,entry))throw Error(`Unknown shortcut native entry: ${entry}`);
62
+ return Object.freeze([...new Set([...sharedNativeShortcutRoots,...shortcutEntryNativeRoots[entry]])]);
63
+ }
64
+ export function selectDeliveryEvidence(changedFiles){
65
+ if(!Array.isArray(changedFiles))throw Error('Changed delivery files must be an array');
66
+ const featureIds=new Set(),nativeEntries=[];
67
+ for(const file of changedFiles){
68
+ if(typeof file!=='string'||!file)throw Error('Changed delivery file path is invalid');
69
+ const owners=deliveredFeatureContracts.filter(contract=>contract.sources.some(source=>dependencyRootMatches(file,source)));
70
+ if(isShippedRuntimeSource(file)&&!owners.length)throw Error(`Unmapped shipped feature source: ${file}`);
71
+ for(const owner of owners)featureIds.add(owner.id);
72
+ if(packageInstallDependencyRoots.some(root=>dependencyRootMatches(file,root)))featureIds.add('installer');
73
+ if(!isShippedRuntimeSource(file)&&!shippedDocumentation.includes(file))continue;
74
+ }
75
+ for(const entry of commands.map(({name})=>name)){
76
+ if(shortcutEntryNativeRootsFor(entry).some(root=>changedFiles.some(file=>dependencyRootMatches(file,root))))nativeEntries.push(entry);
77
+ }
78
+ if(nativeEntries.length)featureIds.add('shortcuts');
79
+ return Object.freeze({featureIds:Object.freeze([...featureIds].sort()),nativeEntries:Object.freeze(nativeEntries)});
80
+ }
81
+
82
+ export const INSTALLED_FILE_CONTRACT_SCHEMA = 1;
83
+ // Generated project entries share one content owner. Only these exact paths
84
+ // enter installer recovery; platform directories are never blanket-owned.
85
+ export const SHORTCUT_INSTALL_CONTRACT = 1;
86
+ export const requiredShortcutTargets = Object.freeze(commandFiles().map(({file})=>file));
87
+
88
+ export const installedFileContracts = Object.freeze([
89
+ contract("runtime-core/AGENTS.core.md", "AGENTS.md", "managed-core"),
90
+ contract("runtime-core/CLAUDE.md", "CLAUDE.md", "strict-bridge"),
91
+ contract("runtime-core/GEMINI.md", "GEMINI.md", "strict-bridge"),
92
+ contract("runtime-core/START_NEXT_SESSION_PROMPT.txt", "START_NEXT_SESSION_PROMPT.txt", "generated-state"),
93
+ contract("runtime-core/SESSION_HANDOFF.md", "dev/SESSION_HANDOFF.md", "stateful-handoff"),
94
+ contract("runtime-core/SESSION_LOG.md", "dev/SESSION_LOG.md", "stateful-log"),
95
+ contract("runtime-core/PROJECT_INDEX.md", "dev/PROJECT_INDEX.md", "stateful-index"),
96
+ contract("runtime-core/DOC_SYNC_REGISTRY.md", "dev/DOC_SYNC_REGISTRY.md", "stateful-registry"),
97
+ contract("runtime-core/RULE_PACKS.md", "dev/RULE_PACKS.md", "marked-routing-table"),
98
+ contract("runtime-core/PROJECT_DECISIONS.md", "dev/PROJECT_DECISIONS.md", "stateful-decisions"),
99
+ contract("packs/safety.md", "dev/rules/safety.md", "rule-pack"),
100
+ contract("packs/coding.md", "dev/rules/coding.md", "rule-pack"),
101
+ contract("packs/writing.md", "dev/rules/writing.md", "rule-pack"),
102
+ contract("packs/research.md", "dev/rules/research.md", "rule-pack"),
103
+ contract("packs/agent-governance.md", "dev/rules/agent-governance.md", "rule-pack"),
104
+ contract("packs/release.md", "dev/rules/release.md", "rule-pack"),
105
+ contract("packs/knowledge.md", "dev/rules/knowledge.md", "rule-pack"),
106
+ contract("packs/communication.md", "dev/rules/communication.md", "rule-pack"),
107
+ contract("packs/closeout.md", "dev/rules/closeout.md", "rule-pack"),
108
+ contract("packs/onboarding.md", "dev/rules/onboarding.md", "rule-pack"),
109
+ contract("packs/integrations.md", "dev/rules/integrations.md", "rule-pack")
110
+ ]);
111
+
112
+ export const installedMappings = Object.freeze(
113
+ installedFileContracts.map(({ sourceRel, targetRel }) => Object.freeze([sourceRel, targetRel]))
114
+ );
115
+
116
+ // The router is installed on fresh roots, but is not evidence that an arbitrary
117
+ // mixed file is Kit-managed. Its upgrade treatment lives in a separate current
118
+ // transition contract below rather than broad path ownership.
119
+ export const freshInstallFileContracts = Object.freeze([
120
+ ...installedFileContracts,
121
+ contract("runtime-core/USER_RULES.md", "dev/USER_RULES.md", "fresh-user-router")
122
+ ]);
123
+
124
+ export const freshInstallMappings = Object.freeze(
125
+ freshInstallFileContracts.map(({ sourceRel, targetRel }) => Object.freeze([sourceRel, targetRel]))
126
+ );
127
+
128
+ // Formal user-rule state is part of an upgrade only when the existing AGENTS.md
129
+ // entry and router form one verifiable current formal state. This separate
130
+ // contract deliberately does not reclassify a path, title, or directory as Kit
131
+ // authority.
132
+ export const upgradeStateFileContracts = Object.freeze([
133
+ contract("runtime-core/USER_RULES.md", "dev/USER_RULES.md", "accepted-user-rules-router")
134
+ ]);
135
+
136
+ export const upgradeStateMappings = Object.freeze(
137
+ upgradeStateFileContracts.map(({ sourceRel, targetRel }) => Object.freeze([sourceRel, targetRel]))
138
+ );
139
+
140
+ export const upgradeStateTargets = Object.freeze(
141
+ upgradeStateFileContracts.map(({ targetRel }) => targetRel)
142
+ );
143
+
144
+ export const requiredInstalledTargets = Object.freeze(
145
+ installedFileContracts.map(({ targetRel }) => targetRel)
146
+ );
147
+
148
+ export function installedFileContract(targetRel) {
149
+ return installedFileContracts.find((item) => item.targetRel === targetRel) ?? null;
150
+ }
151
+
152
+ function contract(sourceRel, targetRel, strategy) {
153
+ return Object.freeze({ sourceRel, targetRel, strategy });
154
+ }