blun-king-cli 9.1.643 → 9.1.645

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 (268) hide show
  1. package/CHANGELOG.md +19 -123
  2. package/LIESMICH.txt +17 -45
  3. package/README.md +15 -76
  4. package/RELEASE-9.1.645.md +29 -0
  5. package/bin/blun.js +3 -3
  6. package/bin/king.js +3 -3
  7. package/bin/launcher-mode.js +125 -126
  8. package/bin/launcher-runtime.js +603 -616
  9. package/bin/plugin-bootstrap.js +339 -405
  10. package/bin/rename-private-staging.cjs +2 -2
  11. package/bin/retired-bundled-plugins.cjs +84 -0
  12. package/bin/startup-security-host.cjs +105 -0
  13. package/bin/startup-security.cjs +9 -105
  14. package/bin/startup-warning-policy.cjs +22 -0
  15. package/bin/update-lease-installer.cjs +125 -0
  16. package/bin/update-lease-sockets.cjs +228 -0
  17. package/bin/update-lease.js +22 -327
  18. package/bin/verify-bundled-agent-sources.cjs +2 -4
  19. package/blun.mjs +77 -180
  20. package/bundled-agent-sources.json +1 -552
  21. package/package.json +3 -6
  22. package/tool-liveness642/receipt.json +1 -1
  23. package/worker-host.mjs +62 -120
  24. package/agent-spine-plugin/.claude-plugin/marketplace.json +0 -20
  25. package/agent-spine-plugin/.claude-plugin/plugin.json +0 -14
  26. package/agent-spine-plugin/.codex-plugin/plugin.json +0 -47
  27. package/agent-spine-plugin/.mcp.json +0 -8
  28. package/agent-spine-plugin/CHANGELOG.md +0 -1614
  29. package/agent-spine-plugin/LICENSE +0 -186
  30. package/agent-spine-plugin/README.md +0 -432
  31. package/agent-spine-plugin/assets/agentspine-banner.svg +0 -32
  32. package/agent-spine-plugin/bin/agentspine-mcp.js +0 -4
  33. package/agent-spine-plugin/bin/agentspine.js +0 -7
  34. package/agent-spine-plugin/blun.plugin.json +0 -68
  35. package/agent-spine-plugin/docs/acceptance.md +0 -61
  36. package/agent-spine-plugin/docs/artifact-evaluation.md +0 -93
  37. package/agent-spine-plugin/docs/host-integration.md +0 -193
  38. package/agent-spine-plugin/docs/preflight-recall.md +0 -71
  39. package/agent-spine-plugin/docs/preservation-contract.md +0 -53
  40. package/agent-spine-plugin/docs/quality-gates.md +0 -50
  41. package/agent-spine-plugin/docs/session-timeline.md +0 -112
  42. package/agent-spine-plugin/docs/source-roots.md +0 -113
  43. package/agent-spine-plugin/docs/world-model.md +0 -119
  44. package/agent-spine-plugin/hooks/codex.json +0 -47
  45. package/agent-spine-plugin/hooks/hooks.json +0 -106
  46. package/agent-spine-plugin/hooks/version.json +0 -5
  47. package/agent-spine-plugin/package.json +0 -77
  48. package/agent-spine-plugin/scripts/check-codex-install.js +0 -226
  49. package/agent-spine-plugin/scripts/check-hosts.js +0 -208
  50. package/agent-spine-plugin/scripts/check-install-hook.js +0 -227
  51. package/agent-spine-plugin/scripts/check-install-selfstarter.js +0 -154
  52. package/agent-spine-plugin/scripts/check-install.js +0 -478
  53. package/agent-spine-plugin/scripts/check-line-budget.js +0 -58
  54. package/agent-spine-plugin/scripts/check-syntax.js +0 -29
  55. package/agent-spine-plugin/scripts/github-actions.js +0 -11
  56. package/agent-spine-plugin/scripts/hermetic-process.js +0 -191
  57. package/agent-spine-plugin/scripts/release-check.js +0 -150
  58. package/agent-spine-plugin/scripts/run-acceptance.js +0 -19
  59. package/agent-spine-plugin/scripts/run-checks.js +0 -50
  60. package/agent-spine-plugin/scripts/run-tests-hermetic.js +0 -112
  61. package/agent-spine-plugin/skills/agent-spine/SKILL.md +0 -99
  62. package/agent-spine-plugin/spine-example/1-identity.md +0 -12
  63. package/agent-spine-plugin/spine-example/2-voice.md +0 -6
  64. package/agent-spine-plugin/spine-example/3-conduct.md +0 -8
  65. package/agent-spine-plugin/spine-example/4-history.md +0 -4
  66. package/agent-spine-plugin/src/cli-agent.js +0 -315
  67. package/agent-spine-plugin/src/cli-attention.js +0 -95
  68. package/agent-spine-plugin/src/cli-autonomy.js +0 -36
  69. package/agent-spine-plugin/src/cli-common.js +0 -71
  70. package/agent-spine-plugin/src/cli-continuity.js +0 -116
  71. package/agent-spine-plugin/src/cli-core.js +0 -128
  72. package/agent-spine-plugin/src/cli-diagnostics.js +0 -291
  73. package/agent-spine-plugin/src/cli-host.js +0 -21
  74. package/agent-spine-plugin/src/cli-learning.js +0 -320
  75. package/agent-spine-plugin/src/cli-premortem.js +0 -16
  76. package/agent-spine-plugin/src/cli-sharing.js +0 -230
  77. package/agent-spine-plugin/src/cli.js +0 -181
  78. package/agent-spine-plugin/src/codex-reader-launcher.js +0 -182
  79. package/agent-spine-plugin/src/hook.js +0 -500
  80. package/agent-spine-plugin/src/index.js +0 -108
  81. package/agent-spine-plugin/src/lib/acceptance.js +0 -435
  82. package/agent-spine-plugin/src/lib/action-lesson-recall.js +0 -118
  83. package/agent-spine-plugin/src/lib/attention-context.js +0 -167
  84. package/agent-spine-plugin/src/lib/attention-events.js +0 -113
  85. package/agent-spine-plugin/src/lib/attention-privacy.js +0 -72
  86. package/agent-spine-plugin/src/lib/attention-schema.js +0 -164
  87. package/agent-spine-plugin/src/lib/attention-storage.js +0 -93
  88. package/agent-spine-plugin/src/lib/attention.js +0 -164
  89. package/agent-spine-plugin/src/lib/audit-premortem.js +0 -223
  90. package/agent-spine-plugin/src/lib/audit.js +0 -401
  91. package/agent-spine-plugin/src/lib/authentication.js +0 -515
  92. package/agent-spine-plugin/src/lib/autonomy-policy.js +0 -110
  93. package/agent-spine-plugin/src/lib/autonomy-store.js +0 -202
  94. package/agent-spine-plugin/src/lib/autonomy.js +0 -8
  95. package/agent-spine-plugin/src/lib/briefing.js +0 -493
  96. package/agent-spine-plugin/src/lib/catalog-document-read.js +0 -51
  97. package/agent-spine-plugin/src/lib/catalog.js +0 -167
  98. package/agent-spine-plugin/src/lib/channel-continuity.js +0 -19
  99. package/agent-spine-plugin/src/lib/channel-runtime.js +0 -665
  100. package/agent-spine-plugin/src/lib/codex-installation.js +0 -231
  101. package/agent-spine-plugin/src/lib/codex-skill-installation.js +0 -211
  102. package/agent-spine-plugin/src/lib/context.js +0 -156
  103. package/agent-spine-plugin/src/lib/continuity.js +0 -338
  104. package/agent-spine-plugin/src/lib/coordination.js +0 -577
  105. package/agent-spine-plugin/src/lib/delivery-agent-usage.js +0 -231
  106. package/agent-spine-plugin/src/lib/delivery-assignment.js +0 -220
  107. package/agent-spine-plugin/src/lib/delivery-command-actions.js +0 -462
  108. package/agent-spine-plugin/src/lib/delivery-knowledge.js +0 -78
  109. package/agent-spine-plugin/src/lib/delivery-premortem-binding.js +0 -107
  110. package/agent-spine-plugin/src/lib/delivery-premortem-closure.js +0 -171
  111. package/agent-spine-plugin/src/lib/delivery-premortem-codec.js +0 -45
  112. package/agent-spine-plugin/src/lib/delivery-premortem-correction.js +0 -101
  113. package/agent-spine-plugin/src/lib/delivery-premortem-file.js +0 -21
  114. package/agent-spine-plugin/src/lib/delivery-premortem-index.js +0 -493
  115. package/agent-spine-plugin/src/lib/delivery-premortem-inspection.js +0 -37
  116. package/agent-spine-plugin/src/lib/delivery-premortem-recovery.js +0 -120
  117. package/agent-spine-plugin/src/lib/delivery-premortem-rejection.js +0 -65
  118. package/agent-spine-plugin/src/lib/delivery-premortem-results.js +0 -28
  119. package/agent-spine-plugin/src/lib/delivery-premortem-session-guard.js +0 -46
  120. package/agent-spine-plugin/src/lib/delivery-premortem-write-ledger.js +0 -285
  121. package/agent-spine-plugin/src/lib/delivery-premortem.js +0 -499
  122. package/agent-spine-plugin/src/lib/delivery-shell-heredoc.js +0 -115
  123. package/agent-spine-plugin/src/lib/delivery-shell-substitutions.js +0 -111
  124. package/agent-spine-plugin/src/lib/delivery-shell-wrapper.js +0 -64
  125. package/agent-spine-plugin/src/lib/delivery-target.js +0 -73
  126. package/agent-spine-plugin/src/lib/delivery-verification.js +0 -445
  127. package/agent-spine-plugin/src/lib/documents.js +0 -239
  128. package/agent-spine-plugin/src/lib/feed-transport.js +0 -499
  129. package/agent-spine-plugin/src/lib/filesystem-retry.js +0 -34
  130. package/agent-spine-plugin/src/lib/gateway-common.js +0 -68
  131. package/agent-spine-plugin/src/lib/gateway-control.js +0 -370
  132. package/agent-spine-plugin/src/lib/gateway-delivery.js +0 -103
  133. package/agent-spine-plugin/src/lib/gateway-execution.js +0 -350
  134. package/agent-spine-plugin/src/lib/gateway-group-response.js +0 -128
  135. package/agent-spine-plugin/src/lib/gateway-host-fencing.js +0 -92
  136. package/agent-spine-plugin/src/lib/gateway-host-lifecycle.js +0 -193
  137. package/agent-spine-plugin/src/lib/gateway-inspection.js +0 -85
  138. package/agent-spine-plugin/src/lib/gateway-knowledge.js +0 -129
  139. package/agent-spine-plugin/src/lib/gateway-policy-provenance.js +0 -197
  140. package/agent-spine-plugin/src/lib/gateway-premortem-disposition.js +0 -82
  141. package/agent-spine-plugin/src/lib/gateway-premortem.js +0 -363
  142. package/agent-spine-plugin/src/lib/gateway-prepared-host.js +0 -28
  143. package/agent-spine-plugin/src/lib/gateway-runs.js +0 -345
  144. package/agent-spine-plugin/src/lib/gateway-runtime-identity.js +0 -31
  145. package/agent-spine-plugin/src/lib/gateway-runtime-records.js +0 -21
  146. package/agent-spine-plugin/src/lib/gateway-runtime.js +0 -18
  147. package/agent-spine-plugin/src/lib/gateway-state-transaction.js +0 -356
  148. package/agent-spine-plugin/src/lib/gateway-state.js +0 -344
  149. package/agent-spine-plugin/src/lib/graph.js +0 -337
  150. package/agent-spine-plugin/src/lib/hook-artifact-guards.js +0 -356
  151. package/agent-spine-plugin/src/lib/hook-audit.js +0 -43
  152. package/agent-spine-plugin/src/lib/hook-briefing-use.js +0 -78
  153. package/agent-spine-plugin/src/lib/hook-context.js +0 -441
  154. package/agent-spine-plugin/src/lib/hook-final-message.js +0 -26
  155. package/agent-spine-plugin/src/lib/hook-input.js +0 -27
  156. package/agent-spine-plugin/src/lib/hook-output.js +0 -284
  157. package/agent-spine-plugin/src/lib/hook-premortem.js +0 -257
  158. package/agent-spine-plugin/src/lib/hook-process-advisory.js +0 -36
  159. package/agent-spine-plugin/src/lib/hook-protection.js +0 -95
  160. package/agent-spine-plugin/src/lib/hook-stop-verification.js +0 -84
  161. package/agent-spine-plugin/src/lib/hook-timeline.js +0 -102
  162. package/agent-spine-plugin/src/lib/host-instruction-budget.js +0 -11
  163. package/agent-spine-plugin/src/lib/https-transport.js +0 -392
  164. package/agent-spine-plugin/src/lib/identifier-analysis.js +0 -446
  165. package/agent-spine-plugin/src/lib/indexed-memory-offline.js +0 -40
  166. package/agent-spine-plugin/src/lib/indexed-memory.js +0 -298
  167. package/agent-spine-plugin/src/lib/knowledge-evidence.js +0 -431
  168. package/agent-spine-plugin/src/lib/learning-applications.js +0 -441
  169. package/agent-spine-plugin/src/lib/learning-artifact-evaluator.js +0 -114
  170. package/agent-spine-plugin/src/lib/learning-candidates.js +0 -274
  171. package/agent-spine-plugin/src/lib/learning-context.js +0 -137
  172. package/agent-spine-plugin/src/lib/learning-delivery-contracts.js +0 -310
  173. package/agent-spine-plugin/src/lib/learning-evaluation-contracts.js +0 -350
  174. package/agent-spine-plugin/src/lib/learning-evaluation-registration.js +0 -372
  175. package/agent-spine-plugin/src/lib/learning-evaluation-revocation.js +0 -292
  176. package/agent-spine-plugin/src/lib/learning-evidence-contracts.js +0 -321
  177. package/agent-spine-plugin/src/lib/learning-findings.js +0 -458
  178. package/agent-spine-plugin/src/lib/learning-measurement-contracts.js +0 -285
  179. package/agent-spine-plugin/src/lib/learning-measurements.js +0 -265
  180. package/agent-spine-plugin/src/lib/learning-outcome-contracts.js +0 -165
  181. package/agent-spine-plugin/src/lib/learning-outcomes.js +0 -343
  182. package/agent-spine-plugin/src/lib/learning-reconciliation.js +0 -290
  183. package/agent-spine-plugin/src/lib/learning-retry-contracts.js +0 -188
  184. package/agent-spine-plugin/src/lib/learning-schema.js +0 -229
  185. package/agent-spine-plugin/src/lib/learning-scope-targets.js +0 -424
  186. package/agent-spine-plugin/src/lib/learning-state-upgrade.js +0 -477
  187. package/agent-spine-plugin/src/lib/learning-status-configuration.js +0 -476
  188. package/agent-spine-plugin/src/lib/learning-storage.js +0 -203
  189. package/agent-spine-plugin/src/lib/learning-trial-recovery.js +0 -218
  190. package/agent-spine-plugin/src/lib/learning-validation-contracts.js +0 -375
  191. package/agent-spine-plugin/src/lib/learning-validation-renewal.js +0 -298
  192. package/agent-spine-plugin/src/lib/learning-validation-runtime.js +0 -234
  193. package/agent-spine-plugin/src/lib/learning.js +0 -36
  194. package/agent-spine-plugin/src/lib/lesson-recall-session.js +0 -172
  195. package/agent-spine-plugin/src/lib/mcp-autonomy-tools.js +0 -37
  196. package/agent-spine-plugin/src/lib/mcp-delivery-completion.js +0 -124
  197. package/agent-spine-plugin/src/lib/mcp-delivery-tools.js +0 -45
  198. package/agent-spine-plugin/src/lib/mcp-premortem.js +0 -68
  199. package/agent-spine-plugin/src/lib/mcp-runtime.js +0 -355
  200. package/agent-spine-plugin/src/lib/mcp-source-context.js +0 -61
  201. package/agent-spine-plugin/src/lib/mcp-timeline-tools.js +0 -240
  202. package/agent-spine-plugin/src/lib/mcp-world-tools.js +0 -52
  203. package/agent-spine-plugin/src/lib/object-transport.js +0 -206
  204. package/agent-spine-plugin/src/lib/owned-file-lock.js +0 -182
  205. package/agent-spine-plugin/src/lib/paths.js +0 -109
  206. package/agent-spine-plugin/src/lib/peer-transport.js +0 -283
  207. package/agent-spine-plugin/src/lib/persona-runtime.js +0 -581
  208. package/agent-spine-plugin/src/lib/pre-answer-timeline-recall.js +0 -104
  209. package/agent-spine-plugin/src/lib/preflight-delivery-id.js +0 -27
  210. package/agent-spine-plugin/src/lib/preflight.js +0 -688
  211. package/agent-spine-plugin/src/lib/project-portfolio.js +0 -176
  212. package/agent-spine-plugin/src/lib/runtime.js +0 -13
  213. package/agent-spine-plugin/src/lib/selfstarter-core.js +0 -382
  214. package/agent-spine-plugin/src/lib/selfstarter-jobs.js +0 -149
  215. package/agent-spine-plugin/src/lib/selfstarter-lease.js +0 -204
  216. package/agent-spine-plugin/src/lib/selfstarter-policy.js +0 -90
  217. package/agent-spine-plugin/src/lib/selfstarter-workspace.js +0 -111
  218. package/agent-spine-plugin/src/lib/selfstarter.js +0 -11
  219. package/agent-spine-plugin/src/lib/session-timeline-auth.js +0 -316
  220. package/agent-spine-plugin/src/lib/session-timeline-codex.js +0 -69
  221. package/agent-spine-plugin/src/lib/session-timeline-contract.js +0 -56
  222. package/agent-spine-plugin/src/lib/session-timeline-enrollment-source.js +0 -38
  223. package/agent-spine-plugin/src/lib/session-timeline-enrollment-storage.js +0 -128
  224. package/agent-spine-plugin/src/lib/session-timeline-enrollment-transport.js +0 -15
  225. package/agent-spine-plugin/src/lib/session-timeline-enrollment.js +0 -478
  226. package/agent-spine-plugin/src/lib/session-timeline-event-extract.js +0 -186
  227. package/agent-spine-plugin/src/lib/session-timeline-host-origin.js +0 -73
  228. package/agent-spine-plugin/src/lib/session-timeline-host-receipt.js +0 -117
  229. package/agent-spine-plugin/src/lib/session-timeline-invocation.js +0 -201
  230. package/agent-spine-plugin/src/lib/session-timeline-king.js +0 -93
  231. package/agent-spine-plugin/src/lib/session-timeline-prior.js +0 -57
  232. package/agent-spine-plugin/src/lib/session-timeline-provider.js +0 -36
  233. package/agent-spine-plugin/src/lib/session-timeline-query.js +0 -56
  234. package/agent-spine-plugin/src/lib/session-timeline-results.js +0 -56
  235. package/agent-spine-plugin/src/lib/session-timeline-root.js +0 -11
  236. package/agent-spine-plugin/src/lib/session-timeline-search.js +0 -82
  237. package/agent-spine-plugin/src/lib/session-timeline-sid-acl.js +0 -213
  238. package/agent-spine-plugin/src/lib/session-timeline-source-open.js +0 -30
  239. package/agent-spine-plugin/src/lib/session-timeline-source.js +0 -80
  240. package/agent-spine-plugin/src/lib/session-timeline-state.js +0 -45
  241. package/agent-spine-plugin/src/lib/session-timeline-transport.js +0 -42
  242. package/agent-spine-plugin/src/lib/session-timeline-windows-acl.js +0 -145
  243. package/agent-spine-plugin/src/lib/session-timeline.js +0 -462
  244. package/agent-spine-plugin/src/lib/sharing.js +0 -969
  245. package/agent-spine-plugin/src/lib/source-roots.js +0 -475
  246. package/agent-spine-plugin/src/lib/source-tree-scan.js +0 -178
  247. package/agent-spine-plugin/src/lib/sqlite-transport.js +0 -501
  248. package/agent-spine-plugin/src/lib/task-knowledge-context.js +0 -99
  249. package/agent-spine-plugin/src/lib/telegram-adapter.js +0 -119
  250. package/agent-spine-plugin/src/lib/timeline-continuation-update.js +0 -100
  251. package/agent-spine-plugin/src/lib/timeline-tool-guard.js +0 -225
  252. package/agent-spine-plugin/src/lib/timeline-user-feedback.js +0 -216
  253. package/agent-spine-plugin/src/lib/timeline-world-capture.js +0 -233
  254. package/agent-spine-plugin/src/lib/voice-runtime.js +0 -39
  255. package/agent-spine-plugin/src/lib/world-knowledge.js +0 -306
  256. package/agent-spine-plugin/src/lib/world-model.js +0 -333
  257. package/agent-spine-plugin/src/mcp.js +0 -456
  258. package/agent-spine-plugin/src/version.js +0 -1
  259. package/agent-spine-plugin/src/worker.js +0 -257
  260. package/bin/agentspine-king-goal-inbox.mjs +0 -127
  261. package/bin/agentspine-king-goal-intake.mjs +0 -106
  262. package/bin/agentspine-king-host-runner.mjs +0 -109
  263. package/bin/agentspine-king-snapshot-policy.cjs +0 -80
  264. package/bin/agentspine-king-status-policy.mjs +0 -226
  265. package/bin/agentspine-king-worker-host.mjs +0 -160
  266. package/bin/managed-plugin-selection.cjs +0 -141
  267. package/bin/verify-agent-behavior.cjs +0 -122
  268. package/bin/verify-agent-components.cjs +0 -104
@@ -1,61 +0,0 @@
1
- # Visible cross-host acceptance
2
-
3
- AgentSpine `0.73.0` runs a visible, reproducible 15-gate acceptance scenario for the lifecycle adapter, including complete mandatory host instructions, required provider recall, the three-stage writing-delivery preflight and a fail-closed missing-provider probe. Staged installed-entrypoint source-root and indexed-memory scaling smoke tests execute the same bundled adapter used by Claude Code and Codex, but they do not substitute for the hosts' own plugin discovery and hook-trust UI.
4
-
5
- ```bash
6
- agentspine acceptance
7
- agentspine acceptance --json
8
- npm run acceptance
9
- ```
10
-
11
- The runner creates a temporary synthetic project and a separate temporary AgentSpine state directory. It uses new fictional identities, groups, projects, tasks, and fixed event times. It neither reads real user context nor stores a conversation transcript. Both temporary directories are removed after success or failure.
12
-
13
- ## What the run proves
14
-
15
- ```mermaid
16
- sequenceDiagram
17
- participant C as Claude lifecycle
18
- participant A as AgentSpine hooks
19
- participant S as External state
20
- participant X as Codex lifecycle
21
- C->>A: Swedish prompt and SessionStart
22
- A->>S: scoped learning, attention, and checkpoint receipts
23
- S-->>C: exact byte-budgeted briefing
24
- X->>A: Spanish prompt and PostCompact
25
- S-->>X: separately scoped briefing
26
- C->>A: authorized effect, Stop, new SessionStart
27
- A->>S: current-rights checks and atomic checkpoint
28
- S-->>C: resume checkpoint
29
- Note over C,X: zero model-side MCP calls
30
- ```
31
-
32
- The human-readable report contains these gates:
33
-
34
- | Gate | Evidence |
35
- |---|---|
36
- | Canonical identities | Freja Åström and Lucía Ortega, their groups, projects, and tasks have separate stable IDs |
37
- | Multilingual style continuity | Direct Swedish and Spanish style requests are minimally captured after opt-in |
38
- | Attention lifecycle | Heartbeat, promise, and blocker events retain scope, provenance, and deduplication |
39
- | Real restart | Claude receives the correct style and promise on a new `SessionStart` |
40
- | Real compaction boundary | Codex receives the correct Spanish context on `PostCompact` |
41
- | Person and group isolation | The other person and group cannot see foreign private or group context |
42
- | Correction and history | A Swedish correction becomes active without replacing prior history |
43
- | Atomic rollback | Rollback removes the correction and restores the earlier accepted style |
44
- | Authorized resume | An exact local grant starts and resumes one job on its durable checkpoint |
45
- | Denied foreign effect | A different actor cannot use the active lease or known task |
46
- | Durable checkpointing | Effect, result, stop, and resume retain idempotent external receipts |
47
- | Complete person purge | Later Codex startup cannot recall the purged person's context |
48
- | Byte preservation | `AGENTS.md`, `CLAUDE.md`, and `SOUL.md` hashes remain identical |
49
- | Final audit | All ten preservation and safety gates pass |
50
-
51
- Every line includes a SHA-256 receipt derived from the acceptance schema, gate ID, and bounded evidence. The final digest binds the ordered gate receipts. JSON output uses `agentspine.acceptance/v1` and is suitable for CI without exposing source content.
52
-
53
- ## Installation proof
54
-
55
- `npm run host:install-check` stages both a fresh installation and an upgrade from a coherent synthetic `0.65.0` cache to the current package version. Every prior-version surface agrees before that cache fails specifically because it lacks the current Codex hook-selection contract; each upgraded bundle must then contain exactly one MCP server, one hook set, and one worker entrypoint and pass the complete visible acceptance run with `mcpCalls: 0`. The check directly invokes the packaged hook entrypoint from an AgentSpine checkout and a foreign `cwd` with sources only in a custom Claude profile, and repeats the Codex-shaped event path with a custom home, two Git projects, a fallback name, and a nested override. Uninstall removes only staged plugin and generated state; all synthetic source hashes remain unchanged. A real Codex session must separately show the plugin in `/plugins`, accept the current hook-definition hash through the startup warning or `/hooks`, and inject the briefing after a new session starts.
56
-
57
- ## Deliberate trust boundaries
58
-
59
- The acceptance runner proves software behavior; it does not simulate or bypass host trust. A real Claude Code or Codex installation still asks once before executable plugin components become active. Automatic conversation learning additionally requires the separate local privacy opt-in.
60
-
61
- The self-starter demonstration uses a synthetic owner-confirmed grant created inside the isolated scenario. In a real installation, execution grants and job registration remain explicit local owner operations. Memory, Markdown, conversation, relationships, attention, signatures, tasks, acceptance receipts, and prior approvals can never create or widen rights.
@@ -1,93 +0,0 @@
1
- # Objective artifact evaluation
2
-
3
- The learning ledger already validates external measurement bindings. It does not
4
- execute the benchmark or prove that caller-supplied scores describe a real task.
5
- `learn-artifact-measure` adds a narrow local evaluator: it reads explicitly named
6
- project files, checks their SHA-256 digests or absence, computes the pass rate and
7
- blocking-defect count itself, and registers the result through the existing
8
- measurement API. It never executes commands, discovers files or calls a provider.
9
-
10
- ## Precommit the experiment
11
-
12
- Prepare an `agentspine.artifact-checks/v1` specification with one to sixteen checks:
13
-
14
- ```json
15
- {
16
- "schema": "agentspine.artifact-checks/v1",
17
- "checks": [
18
- {"path": "artifacts/unwanted.txt", "sha256": null, "blocking": true}
19
- ]
20
- }
21
- ```
22
-
23
- `null` means the file must be absent. A SHA-256 means the regular file must have
24
- exactly that content. `blocking` is explicit for every check; any failed blocking
25
- check is counted separately and cannot be averaged away. File contents are never
26
- included in the report. Only paths, digests, byte counts and result flags appear.
27
-
28
- Run `agentspine learn-artifact-plan --checks '<JSON>' --json` before the experiment.
29
- The result supplies `datasetDigest`, `protocolDigest`, `minCases`, the fixed metric
30
- `artifact-check-pass-rate` / `higher`, and `principalDigest`. Use these with the
31
- existing locally confirmed evaluator and evaluation registration commands. The
32
- task digest still belongs to the externally declared task. The plan command does
33
- not register anything or supply authority.
34
-
35
- One implementation has one fixed principal digest across every name, project and
36
- specification. Two aliases of this evaluator cannot satisfy the existing distinct
37
- principal requirement. Another independently registered evaluator is still needed
38
- for a complete learning experiment; assigning a second name is insufficient.
39
- The principal is an implementation identifier, not a signature or proof of an
40
- independent organization.
41
-
42
- ## Measure, then consume through the existing contract
43
-
44
- Use `learn-artifact-measure <measurement-id>` with `--root`, `--checks`, `--learning`,
45
- `--evaluation`, `--phase before|after`, `--evaluator`, the precommitted `--run`, exact
46
- `--persona`, `--user`, `--tenant`, `--project`, optional `--task` / `--group`,
47
- `--confirm-local-measurement` and `--json`. The root must be canonical. This is a
48
- local runtime/CLI operation, not an MCP tool or new host permission.
49
-
50
- The evaluator accepts neither a model score nor a model claim of having loaded or
51
- verified data. It validates the frozen specification, protocol, case count, metric,
52
- principal and exact scope before target reads. The ordinary measurement writer
53
- rechecks lifecycle, registry, expiry, immutable cohort, delivery and replay bindings
54
- at commit. After measurements require the existing prompt-bound application and
55
- Stop-bound delivery. Missing binding remains unverified, without creating an
56
- automatic retry or blocking normal host work.
57
-
58
- Each explicit file is limited to 2 MiB and checked using the existing parent/path
59
- and source-byte reader. The whole bounded cohort is read twice; observed drift,
60
- symlinks, path escapes, oversized files and read errors abort without registering a
61
- partial score. This is a bounded point-in-time observation, not a filesystem-wide
62
- transaction or proof that no change ever happened between reads. No source is
63
- written. The final measurement uses the existing atomic ledger and replay lineage;
64
- crash before registration leaves no successful measurement, crash afterward cannot
65
- permit a replacement run. Initial-trial deadlines remain unchanged.
66
-
67
- Capture the returned `report` with external experiment records: its JSON digest is
68
- the receipt's `measurement.sourceDigest`. The normal ledger stores the metric and
69
- digest, not a new transcript or artifact database. Repeated/concurrent measurements
70
- cannot replace the first committed trial. Revalidation and arbitrary evaluator
71
- programs remain on the existing external measurement path, not this adapter.
72
-
73
- The returned `completionVerified: false` and `automaticRetry: false` distinguish a
74
- file-state measurement from a verified delivery. Use existing `learn-outcome` to
75
- consume the receipt with its application/delivery bindings. Existing promotion,
76
- canary validation, supersession, revocation and rollback rules are unchanged.
77
-
78
- ## Scope of the comparison
79
-
80
- The isolated archive task really creates a migrated artifact. Without the selected
81
- backup strategy, two of three predefined file checks pass. After bounded learned
82
- context is selected and the synthetic worker creates the backup, three of three
83
- pass. A separate byte-comparison fixture supplies the other synthetic evaluator;
84
- both outcomes are computed from files rather than fixed score constants. Fresh
85
- CLI-process measurement, real Claude/Codex prompt and Stop hooks, compaction,
86
- scope/criteria/principal rejection, concurrency, replay and a blocking-defect
87
- rollback are covered by `test/learning-artifact-evaluator.test.js`.
88
-
89
- This proves the local artifact-to-learning connection for a deterministic synthetic
90
- worker, not improved LLM reasoning, genuine provider execution, independent AGI
91
- evaluation or ExampleOperator/ExampleAgent live acceptance. Runtime and inspected bytes are reported;
92
- tokens and unnecessary questions are not measured by this evaluator. It creates no
93
- live installation, host configuration, production action or new authority.
@@ -1,193 +0,0 @@
1
- # Host integration
2
-
3
- AgentSpine uses native plugin surfaces instead of asking users to paste a large system prompt into every project.
4
-
5
- ## Provider contracts and evidence
6
-
7
- Provider evidence is not interchangeable. Each adapter separately binds its lifecycle, instruction root, transcript version, session/message IDs and invocation. Portal tasks also require the gateway-issued `AGENTSPINE_PORTAL_REF`/`AGENTSPINE_THREAD_REF` pair from `agentspine.gateway-start/v1`; hooks and MCP may match but never invent it. Direct sessions omit it. All recalled state is context-only, and repository checks do not prove a live launcher forwards it.
8
-
9
- | Surface | Claude Code | Codex | BLUN King |
10
- |---|---|---|---|
11
- | Project instructions | `CLAUDE.md` hierarchy | `AGENTS.md` hierarchy | `AGENTS.md` through the isolated BLUN profile |
12
- | Hook package | Native `hooks/hooks.json` | Explicit `hooks/codex.json` | Manifest lifecycle hooks |
13
- | Verified hook briefing → delivery knowledge | Native `additionalContext` handoff receipt | Native `additionalContext` handoff receipt | Native bounded `message` handoff receipt; live acceptance open |
14
- | Historical transcript enrollment | Bounded registered Claude source | Bounded Codex `sessions` source with verified headers | Protected King agent-wire mapping; live mapping open |
15
- | Cross-provider evidence handoff | Explicit opt-in; Claude provenance retained | Explicit opt-in; Codex provenance retained | Same contract; live launcher unverified |
16
- | Native permissions/trust | Host-owned | Host-owned | Host-owned; enforcement of returned block decisions remains externally unverified |
17
-
18
- `UserPromptSubmit` consumes the exact signed snapshot once. Only after stdout accepts the native output does AgentSpine store `agentspine.host-context-handoff/v1`, bound to provider, field, byte count and digest. In-process returns, serialized claims and legacy `verified-host-preflight` receipts do not prove handoff. MCP knowledge may reuse a valid receipt; missing, stale or consumed evidence remains non-blocking and explicitly unverified. The receipt proves transport, not model use or delivery.
19
-
20
- Adapter acceptance uses bounded synthetic A/B sessions and covers restart, source mutation, foreign scope, private exclusion and service failure. Cross-provider recall still needs local opt-in plus `includePriorProviders: true` with `includePriorSessions: true`. Report repository, installed-host and model observations separately.
21
-
22
- ## Claude Code
23
-
24
- | Component | Path | Purpose |
25
- |---|---|---|
26
- | Manifest | `.claude-plugin/plugin.json` | Package identity and version |
27
- | Marketplace | `.claude-plugin/marketplace.json` | GitHub installation and updates |
28
- | Skill | `skills/agent-spine/SKILL.md` | Context rules and preservation invariants |
29
- | MCP | `.mcp.json` | Read-only source tools plus external overlay workflows |
30
- | Hooks | `hooks/hooks.json` | Automatic briefing, attention, protected-source guard, and rights-bound checkpoints |
31
-
32
- Install from GitHub:
33
-
34
- ```bash
35
- claude plugin marketplace add Maykbiletti/AgentSpine
36
- claude plugin install agent-spine@agent-spine
37
- ```
38
-
39
- Use `claude plugin validate .` in a checkout to validate the manifest and marketplace. Claude Code asks the user to approve executable plugin components according to its trust model.
40
-
41
- Version `0.73.0` preserves the managed skill/launcher, task continuation, structured completion, and bounded post-compaction evidence recall. Direct transcript recall stays excluded until the owner creates and enrolls a verified timeline receipt. Groups stay excluded. Writing deliveries may reuse the exact hook-issued briefing requirement for advisory knowledge and premortem calls; missing proof does not block ordinary authorized work.
42
-
43
- The Claude manifest references `.mcp.json` and uses only its native `hooks/hooks.json`; Codex selects `hooks/codex.json` from its own manifest. Repository checks validate portable manifests, installed-root expansion, one command per event, a real MCP handshake, clean install/upgrade, source isolation, briefing, continuation, compaction, and uninstall preservation:
44
-
45
- ```bash
46
- npm run host:check
47
- npm run host:install-check
48
- npm run acceptance
49
- ```
50
-
51
- ### Claude MCP troubleshooting
52
-
53
- If the plugin is listed but `agent-spine` is missing from `/mcp`, update the marketplace cache and reinstall before starting a new session:
54
-
55
- ```bash
56
- claude plugin marketplace update agent-spine
57
- claude plugin uninstall agent-spine@agent-spine
58
- claude plugin install agent-spine@agent-spine
59
- claude plugin list
60
- claude mcp list
61
- ```
62
-
63
- Open `/mcp` in the new interactive session and approve or reconnect `agent-spine`. `Pending approval` means discovery succeeded but Claude Code still needs the user's trust decision. A missing entry after reinstall should be diagnosed from `claude plugin validate .`, `npm run host:check`, and Claude Code's plugin diagnostics; AgentSpine does not write to Claude's user configuration or silently approve itself.
64
-
65
- ## Codex
66
-
67
- History uses the native Codex adapter described in [session timeline](session-timeline.md#integrity-and-provider-formats). It does not use Claude enrollment or a Claude-shaped transcript. Installed-host acceptance remains separate from the repository fixtures.
68
-
69
- | Component | Path | Purpose |
70
- |---|---|---|
71
- | Manifest | `.codex-plugin/plugin.json` | Package identity plus explicit skill and MCP registration |
72
- | Skill | `skills/agent-spine/SKILL.md` | Context rules and preservation invariants |
73
- | MCP | Manifest `mcpServers` | Read-only source tools plus external overlay workflows |
74
- | Hooks | `hooks/codex.json` | Manifest-selected lifecycle guardrails |
75
-
76
- Open `/plugins` in Codex CLI, then start a new session and review `/hooks`. New or changed hook definitions are skipped until the user trusts their exact hash, following the official [Codex hook contract](https://developers.openai.com/codex/hooks).
77
-
78
- For a direct npm/package installation, register or update the common user skill and MCP reader together. The command writes only its sealed skill directory and a marked AgentSpine configuration block, refuses unmanaged conflicts, and requires a local confirmation flag:
79
-
80
- ```bash
81
- agentspine host-install codex --confirm-local-host-install --json
82
- ```
83
-
84
- Non-default or synthetic roots may use `--codex-home` and `--skills-root`. The default skill path is `$HOME/.agents/skills/agent-spine/SKILL.md`, a documented [Codex skill location](https://developers.openai.com/codex/build-skills). AgentSpine refuses unowned conflicts and atomically updates sealed state. The launcher verifies package/runtime identity and tools during MCP initialization; failure returns no tools or migration. User trust remains separate. Configuration follows the official [Codex MCP contract](https://developers.openai.com/codex/mcp).
85
-
86
- Codex loads `hooks/codex.json` through the explicit plugin-manifest entry. It contains only Codex-documented lifecycle events; Claude Code's additional `InstructionsLoaded` event remains confined to `hooks/hooks.json`. Both files deliberately contain only the documented top-level `description` and `hooks` fields. Cache identity remains in `.codex-plugin/plugin.json`, while Codex records hook trust against the current definition hash. The Codex hook and MCP registrations use the host-native `PLUGIN_ROOT` expansion.
87
-
88
- Verify the live host in a newly started Codex CLI session:
89
-
90
- ```text
91
- /plugins
92
- /hooks
93
- Trust all and continue
94
- ```
95
-
96
- Native Codex acceptance separately observes `skills/list`, `mcpServerStatus/list`, MCP `tools/list`, the hook handoff and subsequent bound knowledge/premortem. These are distinct [app-server APIs](https://developers.openai.com/codex/app-server); a handshake or `SKILL.md` alone is insufficient. Repository host checks validate manifests, package bytes and an isolated MCP/install lifecycle, but cannot prove user trust, live discovery or model application.
97
-
98
- ## BLUN King
99
-
100
- | Component | Path | Purpose |
101
- |---|---|---|
102
- | Manifest | `blun.plugin.json` | Native BLUN plugin identity plus skill, MCP, and lifecycle-hook registration |
103
- | Skill | `skills/agent-spine/SKILL.md` | Context rules and preservation invariants |
104
- | MCP | Manifest `mcpServers` | Read-only source tools plus external overlay workflows |
105
- | Hooks | Manifest `hooks` | Automatic briefing, attention, protected-source guard, and checkpoints |
106
-
107
- Install the local checkout from ExampleAgent's TUI:
108
-
109
- ```text
110
- /plugins install C:\path\to\AgentSpine
111
- ```
112
-
113
- BLUN asks the user to trust a third-party plugin before installation because its MCP server and hooks execute local code. Accept that visible install decision, then use `/reload` or `/new`; BLUN has no separate `/hooks` command. The BLUN adapter maps its isolated `BLUN_HOME` to AgentSpine's Codex-compatible `AGENTS.md` source hierarchy, so user state remains under the BLUN app home instead of leaking into `.codex` or a scanned project.
114
-
115
- BLUN Code 1.0.109 constructs MCP tool names as `mcp__<server-name>__<tool-name>`. With AgentSpine's exact manifest server name, its timeline calls are therefore `mcp__agent-spine__session_timeline_index`, `mcp__agent-spine__session_timeline_search`, and `mcp__agent-spine__session_timeline_capture`; the BLUN hook matcher admits only those three exact names. This contract was checked on 2026-09-05 against public `Maykbiletti/blun-code` commit `fbb97459a3fa2157f8bfea3d24931be63288ab11` (`mcp-harness-tools.js`, package license `MIT`). The external source is naming evidence only and is treated as untrusted context; no implementation was copied. Repository checks do not prove that an installed King forwards the hook payload or enforces AgentSpine's returned block decision, and they do not replace a live host acceptance test.
116
-
117
- History has an independent [King agent-wire adapter](session-timeline.md#integrity-and-provider-formats). The local launcher must bind the current source and measured wire version through `AGENTSPINE_KING_TIMELINE_SOURCE` and `AGENTSPINE_KING_WIRE_PROTOCOL_VERSION`; AgentSpine neither searches `BLUN_HOME` nor infers either value. Project instructions still resolve through the Codex-compatible hierarchy, while history is enrolled as provider `king` and reads only the explicitly mapped `agents/main/wire.jsonl`. Correct MCP names, a passing Codex adapter, or a model-supplied path do not satisfy this contract.
118
-
119
- Repository fixtures verify the reviewed BLUN Code `1.0.109` / King SDK `0.12.1` record shape, objective `tool.result` recall across session restart and compaction, source-byte preservation, and denial for wrong protocol, foreign scope, replay, mutation, and unknown records. ExampleAgent's actual launcher mapping, installed wire version, live A/B recall, and King's enforcement of returned block decisions are still unverified and must be reported separately. No installation or trust configuration is changed by the repository tests.
120
-
121
- ## Direct MCP use
122
-
123
- Any MCP client that supports stdio can launch:
124
-
125
- ```json
126
- {
127
- "mcpServers": {
128
- "agent-spine": {
129
- "command": "agentspine-mcp"
130
- }
131
- }
132
- }
133
- ```
134
-
135
- The server implements `initialize`, `ping`, `tools/list`, and `tools/call`. It has no network dependency and exposes no source-file, delegation-policy, signer, trust, or shared-adapter administration tool. Overlay tools write only private AgentSpine context state outside the scanned project. Explicit delegation grants, key generation and rotation, trust changes, adapter connections, publication, HTTPS snapshot export, object upload or pulls, SQLite paths or operations, import review, and destructive sharing operations remain on the local CLI surface. MCP can only read already reviewed `shared_context`; its authentication summary contains no signature or public-key material. `session_briefing` is a read-only aggregator over these already constrained read paths and cannot widen them.
136
-
137
- Verify either installation against a synthetic or real project without changing its Markdown:
138
-
139
- ```bash
140
- agentspine doctor --json
141
- npm run host:check
142
- agentspine audit /path/to/project --json
143
- ```
144
-
145
- The audit exits non-zero when a required gate fails, making it suitable for installation smoke tests and CI.
146
-
147
- Use `agentspine doctor --host claude|codex --cwd /active/project --json` or `agentspine source-status --host claude|codex --cwd /active/project --json` to see the checked scope counts and a concrete empty/fail-closed reason. The lifecycle adapter never substitutes the installation directory for the active host hierarchy. Details and official host references are in [host-native source roots](source-roots.md).
148
-
149
- The provider-neutral lifecycle adapter covers `SessionStart` (including resume and compact starts), `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `PostCompact`, `Stop`, and `SubagentStop`. Claude Code additionally registers its documented `InstructionsLoaded` observability event; Codex does not. `UserPromptSubmit` is the blocking boundary. Before a prompt can proceed, `agentspine.preflight/v2` loads complete mandatory host instructions, confirmed Must-Remember entries and every locally required retrieval provider, then consumes one exact-turn receipt. Start and compaction boundaries retain the scoped `session_briefing`; no model-side MCP selection is required. Full behavior and the documented command-hook timeout limitation are in [pre-answer recall gate](preflight-recall.md).
150
-
151
- PostToolUse can contain an image or another tool result larger than the adapter's 64 KiB input boundary. Version 0.40 gives only that optional host registration an explicit silent-oversize lane: the adapter drains the payload, exits successfully, emits no stdout or stderr and writes no partial state. Session, prompt, compaction, stop and PreToolUse registrations do not receive that lane and remain fail-closed at the same bound.
152
-
153
- When an exact locally registered job is waiting, `SessionStart` acquires its lease and injects its real checkpoint automatically. Subsequent tool and stop hooks resolve that job from the native host session; the model does not need to repeat a job envelope. `PreToolUse` first retains the protected-source guard, then rechecks the current execution grant, assignment, scope, capability, lease, and workspace. `PostToolUse` checkpoints exactly one matching result. A new session resumes only after the same checks. Grant and job administration remain local CLI operations and are absent from MCP. No hook creates permissions.
154
-
155
- Identity and audience come from explicit hook scope fields or the locally configured default direct-person/project scope. Group content requires an exact group ID and never enters automatic learning. Missing scope produces no inferred identity; corrupt state returns a visible `failedClosed` packet and must never be reported as successful recall.
156
-
157
- Hook stdin is JSON-only and limited to 64 KiB. State transitions use external atomic files and locks. Hook stdout contains only host protocol JSON; diagnostics are bounded to stderr by the host process. Hooks do not expose transport, key, trust, database, network, message, payment, production, delegation, or policy administration.
158
-
159
- The first executable-component trust approval remains mandatory. AgentSpine cannot approve itself. After approval and the one-time continuity opt-in, read-only briefing and recall require no per-session enablement or voluntary tool call. A writing delivery must still make the hook-issued `record_delivery_premortem` registration before its first mutation.
160
-
161
- ## Optional gateway worker
162
-
163
- The package also registers exactly one `agentspine-worker` entrypoint. It is separate from MCP and lifecycle hooks. When an owner runs it under a service manager, it synchronizes the configured authenticated persona roster, polls current Telegram bindings, prepares exact Claude/Codex start data, invokes only the absolute executable in `AGENTSPINE_HOST_RUNNER` without a shell, and returns one idempotent reply to the bound origin.
164
-
165
- The host runner is responsible for starting the selected host with the supplied scope and `agent_spine_channel_event` fields. Codex skips an untrusted hook definition until the user accepts its current hash in the startup warning or `/hooks`; the worker cannot bypass or manufacture that trust. Setup and the stdin/stdout contract are documented in [durable gateway worker](gateway-runtime.md).
166
-
167
- The visible acceptance runner invokes the same production lifecycle adapter with new synthetic people, separated groups, Swedish and Spanish prompts, restarts, compaction, correction, rollback, purge, current-rights checks, and durable checkpoints. It prints one reproducible receipt per gate and proves `mcpCalls: 0`. See [visible cross-host acceptance](acceptance.md).
168
- # Group participation in the gateway worker
169
-
170
- `agentspine.run-request/v1` carries an internal `groupResponseContract`. Without
171
- a direct request, remain silent except for a relevant idea, concrete error, or
172
- useful improvement. Never emit status, echo bots, change identity/language, or
173
- present suggestions as measured facts. Silence is:
174
-
175
- ```json
176
- {"groupResponse":{"schema":"agentspine.group-response/v1","kind":"silence"}}
177
- ```
178
-
179
- `answer` needs text and no subject; other contribution kinds need text plus a
180
- stable subject. `silence` forbids text/skip markers. Unknown shapes fail.
181
- Identity, capability, privacy, and output gates still apply; no rights arise.
182
-
183
- Silence/duplicates consume the lease without an outbox; delivery/completion stay
184
- false. Receipts record disposition and recover crashes. Deduplication binds
185
- normalized text/subject to the full route except event ID; outbox recovery
186
- handles uncertainty. It is not semantic.
187
-
188
- Legacy text-only results remain compatible. Ingress cannot authenticate direct
189
- address (`directAddressVerified:false`), so the host must adopt and enforce this
190
- contract. Installation proves no live behavior. Group silence is not private;
191
- no broad filter/live change is included. Synthetic tests cover response kinds,
192
- replay, crash, mutation, source bytes, limits, and deadlines; model relevance,
193
- questions, tokens, and Telegram remain unverified.
@@ -1,71 +0,0 @@
1
- # Pre-answer recall gate
2
-
3
- AgentSpine 0.9 adds `agentspine.preflight/v2`, a provider-neutral pre-answer contract. On `UserPromptSubmit`, the lifecycle adapter resolves and race-safely rereads the active host instruction hierarchy, loads confirmed Must-Remember context, runs every locally required retrieval provider, creates a short-lived HMAC receipt bound to the exact turn, consumes it once, and only then injects the resulting context. The model does not call MCP for any part of this path.
4
-
5
- The receipt binds agent and optional persona, user, tenant, host, instruction host, profile, session, project, task, group, working-directory digest, hook delivery, prompt digest, every mandatory instruction file and file identity, the current local policy revision and profile digest, active Must-Remember checksums, provider query status, loaded item IDs and revisions, rejection count, briefing digest, creation time, and expiry. A different prompt, session, scope, working directory, source set, policy, critical-memory revision, hook delivery, or second consumption is rejected. Receipts contain no prompt text, source content, retrieval claims, credentials, or full transcripts.
6
-
7
- ## Host instructions
8
-
9
- Claude Code uses its resolved user and project `CLAUDE.md` hierarchy. Codex uses the corresponding `AGENTS.override.md`/`AGENTS.md` hierarchy. A generic host must explicitly bind `instruction_host` to `claude` or `codex`; AgentSpine does not guess. The mandatory preflight section contains the complete bytes of every loaded instruction document. The standard budget is 8 KiB, with aggregate overflow up to 16 KiB for Claude or 32 KiB for Codex. King uses its own profile and bounded source-reader resources; a rule outside that resource budget remains explicitly unverified without blocking the native-host turn. Loaded bytes, overflow and hard limit are bound into the signed exact-turn receipt and revalidated before consumption. Unreadable, replaced, deleted, out-of-scope or symlinked mandatory files still fail closed.
10
-
11
- Claude Code's `InstructionsLoaded` lifecycle event is registered as an additional observability signal, while `UserPromptSubmit` remains the blocking and injection boundary. Codex uses its own manifest-selected hook set without that unsupported Claude-only event. The preflight does not rely on the model remembering to read a file or call a tool.
12
-
13
- Codex `UserPromptSubmit` binds the receipt to the native string `turn_id`; if an exact event ID is also present, both IDs are digest-bound. Claude's supported `UserPromptSubmit` input has no turn ID, so the adapter issues a process-local invocation capability that only the parsed hook-input object can consume. This lets two legitimate identical prompts run separately while a copied object cannot reconstruct the receipt binding. Numeric or otherwise unsupported turn identifiers are rejected rather than treated as King/BLUN lifecycle evidence.
14
-
15
- ## Required retrieval providers
16
-
17
- Retrieval policy is a separate local policy file outside every project. Configure it only through the local CLI:
18
-
19
- ```bash
20
- agentspine preflight-policy ./dieter-preflight.json --confirm-local-policy
21
- agentspine preflight-status --json
22
- ```
23
-
24
- The initial reference adapter is `mnemo-command/v1`: an absolute, regular executable receives one `agentspine.retrieval-query/v1` JSON object on stdin and must return one `agentspine.retrieval-result/v1` object on stdout. It may talk to a local or remote Mnemo deployment. Credentials are passed only through environment-variable names explicitly listed in local policy; values never enter repository files, state, context, receipts, logs, or MCP. Required providers must be fail-closed. A successful query with no matches produces status `empty`; a missing invocation, timeout, invalid scope, malformed response, or adapter failure blocks the turn.
25
-
26
- Example local policy profile:
27
-
28
- ```json
29
- {
30
- "id": "preflight-policy:dieter:claude",
31
- "agentId": "agent:dieter",
32
- "host": "claude",
33
- "profileId": "profile:dieter",
34
- "tenantId": "tenant:company",
35
- "enabled": true,
36
- "providers": [
37
- {
38
- "schema": "agentspine.retrieval-provider/v1",
39
- "id": "mnemo:primary",
40
- "adapter": "mnemo-command/v1",
41
- "required": true,
42
- "failClosed": true,
43
- "timeoutMs": 5000,
44
- "command": "/absolute/path/to/mnemo-adapter",
45
- "args": [],
46
- "credentialEnv": ["EXAMPLE_PROVIDER_TOKEN"]
47
- }
48
- ]
49
- }
50
- ```
51
-
52
- Policy, identity and authorization remain independent. Prompt, Markdown, memory, persona, team metadata and provider output cannot configure a provider, relax fail-closed behavior, grant a capability, or authorize an action.
53
-
54
- ## Must-Remember
55
-
56
- Conversation wording such as “Merk dir das” may create only a pending candidate. Activation requires a separate explicit local user confirmation:
57
-
58
- ```bash
59
- agentspine remember-propose --claim "Keine halbfertigen Commits veröffentlichen." --user person:papa --tenant tenant:company --project project:agent-spine
60
- agentspine remember-confirm remember-candidate:… --confirm-local-user
61
- ```
62
-
63
- Confirmed entries are scoped, checksummed, append-only and versioned. A new version supersedes rather than overwrites; rollback is explicit. Permanent deletion requires `remember-purge … --confirm-local-purge`. Secret-shaped and authority-shaped claims are rejected. Must-Remember remains context-only.
64
-
65
- ## Enforcement modes and host limits
66
-
67
- `preflight-status` and Doctor distinguish `instructions-only-no-required-provider`, `wrapper-hard-required`, the last provider result (`loaded`, verified `empty`, or failure), a consumed receipt, and a blocked turn with a privacy-safe failure code. Host inventory reports hook trust as unverified until the real host confirms it. The bundled command hook returns each host's documented structured blocking response for a verified mismatch; malformed lifecycle input that cannot produce a protocol-safe response exits with code 2. Host trust remains a one-time user decision. A prepared turn that aborts before model injection is invalidated and may retry; a consumed delivery remains replay-blocked.
68
-
69
- Claude Code documents that a command hook killed by the host timeout is fail-open, even though an explicit exit code 2 blocks. Therefore an absolute guarantee against process termination requires the host or TUI to invoke the same preflight contract as a wrapper-hard gate immediately before its model API call. AgentSpine does not mislabel a merely installed command hook as proof against host-enforced timeout. A release is only live-proven after the target host shows fresh consumed receipts across consecutive turns, restart, and compaction.
70
-
71
- Host hierarchy and lifecycle behavior were checked on 2026-09-09 against the official [Claude Code hook reference](https://code.claude.com/docs/en/hooks) and [Codex hook reference](https://learn.chatgpt.com/docs/hooks).
@@ -1,53 +0,0 @@
1
- # Preservation contract
2
-
3
- The preservation contract is AgentSpine's primary compatibility promise.
4
-
5
- ## Guaranteed
6
-
7
- For every discovered source document, AgentSpine records its canonical path, repository-relative path, byte count, modification time, semantic layer, host relevance, explicit links, and SHA-256 digest.
8
-
9
- The scanner:
10
-
11
- - opens source Markdown read-only;
12
- - never renames, moves, merges, normalizes, truncates, or rewrites it;
13
- - does not follow filesystem symlinks;
14
- - writes catalogs, graph overlays, attention, learning, delegation policy, coordination, imported sharing state, trust, and private signing keys only to the user state directory;
15
- - writes an explicitly requested HTTPS snapshot only to a new path outside the scanned project and never uploads or overwrites one;
16
- - uses an atomic temporary-file replacement for its own catalog;
17
- - keeps every discovered document visible even when another file has higher precedence.
18
-
19
- The resolver may omit content from an individual response when its configured byte budget is exhausted. Omission is explicit. The session briefing also measures its complete compact JSON result and includes only whole records; it never shortens source or state values to make them fit. The original remains retrievable through a ranged read with its SHA-256 digest. Ranged reads include both UTF-8 text and base64 bytes so callers can verify exact data even when a boundary splits a multibyte character.
20
-
21
- Filename and path classification is a hint. An agent may add a context-only overlay annotation, but cannot promote an arbitrary source into the constitution layer. Only filenames understood by the native host adapter are instruction candidates.
22
-
23
- ## Protected sources
24
-
25
- A source is protected from agent write tools when it is any of the following:
26
-
27
- - a native host instruction file;
28
- - a soul or persona file;
29
- - a memory index or a Markdown file below a memory directory;
30
- - a Markdown file explicitly linked from a protected source.
31
-
32
- Protection is a host hook guardrail, not an operating-system security boundary. Users retain full control of their files. Specialized tools that bypass host hooks may also bypass the guardrail.
33
-
34
- The bundled guard recognizes direct Edit/Write/apply-patch targets and common mutating shell forms that name a protected source. Shell syntax is too broad to prove safe by pattern matching; operating-system permissions, host approvals, and version control remain the hard controls.
35
-
36
- ## Conflicts and precedence
37
-
38
- AgentSpine does not resolve semantic disagreement by editing content. It exposes every source and follows native host ordering. A higher-precedence source may control the active context, but lower-precedence sources remain cataloged with their original hashes.
39
-
40
- ## Uninstall
41
-
42
- Uninstall removes the plugin and its generated state only. It never touches scanned projects. Acceptance tests snapshot source bytes before scanning, resolving, session briefing, reading, attention mutation, heartbeat/promise/blocker lifecycle transitions, learning proposal/review/rollback, delegation and task workflows, exact execution-policy registration, hook-driven start/checkpoint/stop/resume, signing, trust, shared adapter publication/import/review, HTTPS snapshot export/import, verifying, and hook execution, then compare the source tree afterward.
43
-
44
- ## Not guaranteed
45
-
46
- AgentSpine cannot prevent:
47
-
48
- - direct user edits;
49
- - writes from programs outside the hooked host;
50
- - writes from host tool paths that do not participate in lifecycle hooks;
51
- - changes made while AgentSpine is not running.
52
-
53
- `agentspine verify` detects those changes relative to the last saved scan. It reports them and never restores files automatically.
@@ -1,50 +0,0 @@
1
- # Ten quality gates
2
-
3
- `agentspine audit` is the executable Definition of Done for an installed project. It scans twice, resolves context, validates overlay state, verifies the saved catalog, and compares source hashes. It never repairs or rewrites source Markdown.
4
-
5
- ```bash
6
- agentspine audit /path/to/project
7
- agentspine audit /path/to/project --json
8
- ```
9
-
10
- | Gate | Proof | Failure meaning |
11
- |---:|---|---|
12
- | 1 | Supported Node.js runtime and installed host inventory | Runtime is below Node 20, or the MCP/hook set is missing, duplicated, disabled, or stale |
13
- | 2 | Catalog schema and discovery | Sources could not be represented deterministically |
14
- | 3 | External generated state | Catalog, graph, attention, learning, delegation policy, coordination, execution policy, job checkpoint, channel, persona, gateway, sharing, trust, or signer state landed inside the scanned project |
15
- | 4 | Native hierarchy mapping | A recognized host source lacks host mapping |
16
- | 5 | Markdown link integrity | An indexed local `.md` link has no target |
17
- | 6 | Conflict visibility | Precedence and competing candidates are surfaced for review |
18
- | 7 | Authority boundary | Context or shared state claims authority; a delegation, execution, channel, persona, or goal policy lacks explicit local provenance; or a task/job/channel/gateway snapshot has no valid policy binding |
19
- | 8 | Context privacy | Graph, attention, learning candidate, outcome receipt, canary scope, coordination, self-starter, channel, persona, gateway queue/lane/checkpoint/delivery, sharing, signer, trust, signature, group binding, local-review proof, or safety boundary is invalid |
20
- | 9 | Context budget | Resolved source bytes or the complete compact session briefing exceed the requested ceiling |
21
- | 10 | Byte preservation | A source hash changed during the audit or differs from the saved scan |
22
-
23
- Gate 6 is informational when findings are represented correctly; AgentSpine exposes conflicts rather than pretending to solve them. Every other failed gate makes the command exit non-zero.
24
-
25
- With `--host claude` or `--host codex`, Gate 2 uses the production source-root resolver instead of recursively scanning the supplied path. It fails when the host profile and active project scopes are empty, conflicting, damaged, or stale, and reports scope counts plus the concrete fail-closed reason. This mode never falls back to scanning the home directory.
26
-
27
- For Claude project memory, Gate 2 also reports indexed, relevant, loaded, cache-hit, cache-miss, missing, scope-rejected, path-rejected, symlink-rejected, size-rejected, and race-rejected counts. The live hook never enumerates the memory directory. Orphan counting is available only through the explicit offline diagnostic `agentspine doctor --host claude --offline-memory-orphans`; it reads no orphan content and cannot affect recall or authority.
28
-
29
- ## CI and troubleshooting
30
-
31
- The repository test matrix covers Linux, macOS, and Windows on supported Node.js release lines. Every test file runs once with an empty synthetic host profile and once with a populated synthetic profile, so real `~/.claude`, `~/.codex`, and AgentSpine state cannot change an assertion. Package integrity runs separately. For an integration project, run the JSON form and retain only the audit result—never upload source content, the private graph, attention state, learning state, delegation policy, coordination state, persona roster, gateway state, sharing inbox, or adapter events as CI evidence.
32
-
33
- Broken links are reported with source and target in the catalog. Competing constitution candidates record either native host precedence or `agent-review-required`. Fix the project only through its normal owner workflow; AgentSpine deliberately has no auto-fix mode.
34
-
35
- Gate 8 validates attention lifecycle schema, provenance, event and receipt identity, exact group binding, execution-policy/job binding, leases, pending effects, checkpoints, retry state, authenticated channel payload and retained-history digests, persona identity events and receipts, gateway queue IDs, per-agent lanes, focused goals, checkpoints, outbox idempotency and delivery receipts, exact channel routes and senders, the local sharing quarantine, accepted imports, review proof, transport event integrity, trusted public keys, private/public key matches, private-key file safety, and retained signatures. `agentspine audit` does not start or resume jobs, poll Telegram, claim gateway work, deliver a message, or crawl remote URLs. Directory manifests and events are validated with strict file, size, schema, digest, signature, trust, and collision checks whenever used. HTTPS snapshots add endpoint, DNS, TLS, redirect, media-type, compression, response-size, bundle-integrity, and signed-document checks before they enter that same importer. The object-transport suite additionally proves create-only headers, exact body length, status handling, idempotent collision verification, mandatory read-back, secret exclusion, private-network confirmation, and source preservation. CI uses synthetic responses and identities only; it never depends on an external service or secret.
36
-
37
- The optional SQLite suite runs where `node:sqlite` is available and proves external-path enforcement, signed-manifest binding, strict schema and integrity validation, append-only revision continuity, atomic-head validation, idempotency, tamper rejection, quarantined pull, CLI integration, agent-surface exclusion, and source preservation. Older supported Node.js jobs load the package without activating this optional transport.
38
-
39
- Gate 9 also assembles a read-only generic `session_briefing`, verifies its reported compact UTF-8 JSON byte count, and confirms it remains inside the configured packet ceiling. Focus is active and private context is excluded during this audit read.
40
-
41
- ## Visible lifecycle acceptance
42
-
43
- The ten-gate audit validates one installed project's invariants. The complementary `agentspine acceptance` command proves the entire automatic cross-host behavior in an isolated synthetic environment:
44
-
45
- ```bash
46
- agentspine acceptance
47
- agentspine acceptance --json
48
- ```
49
-
50
- Its 15 visible gates cover canonical identities, mandatory pre-answer recall, Swedish and Spanish continuity, heartbeat/promise/blocker persistence, Claude restart, Codex compaction, person and group isolation, correction history, rollback, authorized resume, denied foreign effect, durable checkpointing, person purge, source-byte preservation, and the final audit. Every gate prints a deterministic SHA-256 receipt, and the machine report explicitly records zero MCP calls. Fresh-install and upgrade validation run this same acceptance entry point from the staged installed bundle. See [visible cross-host acceptance](acceptance.md).