blun-king-cli 9.1.567 → 9.1.569

package/agent-spine-plugin/README.md

@@ -92,7 +92,27 @@ claude --plugin-dir .
 
 Claude Code discovers the bundled skill, hooks, and MCP server. Review and trust executable components when the host asks.
 
-Version `0.59.1` keeps every lifecycle hook available when a bounded filesystem scan encounters an inaccessible directory. Scanner-tagged failures and raw `EPERM` or `EACCES` directory-enumeration errors return success from `PreToolUse`, `PostToolUse`, `Stop`, and `SubagentStop`, while recording the event, phase, code, and path locally. Security decisions remain fail closed. Starting at the exact Claude, Codex, or BLUN profile root also suppresses project and self-starter recursion through that profile; a real nested project is still scanned normally.
+Version `0.73.0` keeps the managed common Codex skill, stable reader verification, assignment continuation and structured completion from `0.72.2`–`0.72.7`, and adds bounded long-session evidence recall without duplicating a host transcript. Claude, Codex, and King use separate deny-by-default source/format adapters; matching tool names never substitute for native provider evidence. A verified `UserPromptSubmit` creates an opaque receipt; only a local owner can consume it with `timeline-enroll --receipt … --confirm-local-timeline` for one immutable private snapshot. Groups stay excluded. After compaction, an agent asks only for one exact UTC time or at least two concrete terms through `session_timeline_search`; `includePriorSessions` can select an already indexed immutable snapshot from the exact same private task after restart. The sidecar is ranked before at most one source is opened, and every returned card carries stable session/message references. A matching real `PreToolUse` provides the one-use binding, so raw MCP, reuse, changed scope, or a changed source returns no history. Redacted results are untrusted context and grant no authority. See [bounded session timeline](docs/session-timeline.md).
+
+The current structured world view also supports a bounded normal-task continuation checkpoint. It restores the exact confirmed objective, last verified step, open questions and next step after restart or compaction, with source references and without loading transcript history. Proposed, conflicting, foreign and completed work is never presented as resumable. See [provenance-bound world model](docs/world-model.md).
+
+Version `0.72.0` keeps the durable provenance-bound world model and decomposes the complete outcome-bound learning runtime into bounded contract domains. The current unreleased world view additionally separates facts, user preferences, decisions with rationale, task state, and error lessons. Every typed entry retains evidence, time, scope and optional session/message references; model suggestions remain assumptions, conflicts withhold facts, and explicit corrections preserve superseded history without bloating briefing.
+
+Version `0.69.0` splits the CLI into seven bounded domains while preserving all 114 commands and behavior.
+
+Version `0.68.0` decomposes the gateway runtime and its regression suite along explicit contract, planning, state, control, run-lifecycle, delivery, inspection and behavioral-test boundaries. The stable `gateway-runtime.js` entrypoint retains the exact public export surface, while every resulting gateway production and test file is governed by the ordinary 500-line budget. Persisted schemas, security gates, atomic state-pair recovery, goal planning, team handoff, resource serialization, tool strategy selection, reflection, exploration and outcome-bound learning remain behaviorally unchanged.
+
+Version `0.67.0` makes real AgentSpine use part of every writing delivery contract. Before the first mutation, the hook now requires three ordered, auditable MCP calls bound to the exact session and active goal step: `session_briefing`, `delivery_knowledge_query` for affected targets, contracts and recent errors, then `record_delivery_premortem`. Text claims, foreign-session or foreign-step evidence, and consumed receipts do not count. Missing stages are named precisely at the first write and at completion, while read-only work and verified parser or filesystem uncertainty retain their fail-open behavior. The new knowledge query returns bounded target fingerprints and contract matches as untrusted, context-only evidence; none of these calls grants permissions, tools, delegation or external effects.
+
+Version `0.66.1` requires a session- and goal-step-bound premortem before the first direct mutation or any of the recognized common shell-mediated mutations. Exactly three failure checks cover the baseline, contract/tests and delivery path; `Stop` accepts a written delivery only when all three results are closed against both the original premortem digest and the latest observed mutation digest. A later mutation invalidates an earlier closure. Read-only work remains free, technical state uncertainty is audited and fail-open, and closed checks are attached to goal checkpoints and outcome receipts without granting permissions. Large project trees no longer disable the hook when optional Markdown discovery reaches its file, entry or time budget: AgentSpine keeps required sources, skips the remainder deterministically and reports an incomplete-context warning.
+
+Version `0.65.0` makes the JavaScript undeclared-call guard differential: existing findings remain visible as exact non-blocking warnings, while only names introduced by the current write block. The comparison uses explicit original edit content, an exact PreToolUse snapshot or the last local audited state; a new file starts from an empty set, and scanner uncertainty remains fail-open.
+
+Version `0.64.0` splits the host hook into bounded lifecycle-context and protection modules while preserving the installed hook entrypoint, public exports, event ordering, fail-open scan behavior and fail-closed safety gates. The former 865-line entrypoint is now below the ordinary 500-line budget, and the legacy budget exception has been removed. The same release verifies stated snapshot baselines before direct writes, reports undeclared JavaScript calls after writes, and validates explicitly claimed exchange artifacts after the existing post-write test gate. Unreadable or unparseable evidence is audited without inventing a mismatch.
+
+Version `0.63.0` prevents an agent from delivering a changed workspace as finished until a successful supported test command has run after its latest write. The hook records only digest-bound tool evidence outside the repository, carries task-scoped verification across restart, rejects masked or reordered tests, and blocks corrupted evidence cleanly. A waiting self-starter job remains resumable. The same release turns the bounded 16-item self-help ceiling into an explicit plan blocker instead of an exception that kills the worker tick.
+
+Version `0.62.0` lets bounded self-help escalate a genuinely unresolved primary-source conflict into exactly one durable owner decision. The runner must first bind repository evidence plus two fresh sources from independent public origins, identify their two conflicting SHA-256 digests, and provide 2-8 distinct options. Without that proof it cannot ask; after local resolution, restart restores exactly one continuation. External content and the answer remain context only and cannot grant authority.
 
 Version `0.59.0` adds bounded, outcome-driven exploration to durable plan execution. An owner-confirmed step can freeze two to four attempts; after an objectively measured non-blocking failure, AgentSpine tries exactly one remaining sufficient strategy from the same minimum-risk class. The host receives an immutable attempt number, strategy, budget and previous-outcome digest. Missing or reused evidence, a blocking defect, budget exhaustion and any attempt to enter a higher-risk class stop fail closed. Exploration remains context only and cannot grant tools, permissions or policy exceptions.
 
@@ -175,11 +195,11 @@ Source discovery is independent of the installation `cwd`: Claude uses `CLAUDE_C
 
 ## Install for Codex
 
-AgentSpine ships a native `.codex-plugin/plugin.json`. Add the repository to a configured marketplace, open the Codex plugin browser with `/plugins`, install AgentSpine, and start a fresh session. For development, the CLI and MCP server can be used directly:
+AgentSpine ships a native `.codex-plugin/plugin.json` that selects the Codex-only lifecycle adapter. Add the repository to a configured marketplace, open the Codex plugin browser with `/plugins`, install AgentSpine, review the current hook definition with `/hooks`, and start a fresh session. A direct npm/package installation can register both the common user skill and the stable MCP reader with one locally confirmed command:
 
 ```bash
 npm link
-agentspine-mcp
+agentspine host-install codex --confirm-local-host-install --json
 ```
 
 See [host integration](docs/host-integration.md) for exact component paths and trust behavior.
@@ -327,12 +347,17 @@ flowchart LR
 - `propose_learning`, `add_learning_evidence`, `review_learning`, `learning_context`, `learning_outcome_status`, `evaluate_learning`, `rollback_learning`, `configure_learning`, and `delete_learning` keep observations separate from accepted context and preserve every relevance change. Outcome writes remain local runtime/CLI operations; MCP receives only their read-only status.
 - `check_delegation`, `create_task`, `update_task`, and `task_context` coordinate work under a separate default-deny policy. MCP intentionally has no policy grant, revoke, or permanent task-delete tool.
 - `shared_context` reads only locally reviewed shared memory. MCP intentionally cannot initialize adapters, publish, pull, inspect the pending inbox, review imports, roll back, or delete.
+- `record_delivery_premortem` records the exact three context-only failure checks for one hook-issued requirement before mutation. Its sealed receipt is bound to the session and active goal step and grants no permissions or tool access.
+- `record_world_assertion` stores one immutable measured, explicitly user-confirmed, or model-proposed assertion outside source files; optional typed knowledge distinguishes facts, user preferences, decisions, task state, and error lessons. `world_context` returns only unexpired, non-conflicting established facts while exposing assumptions, stale evidence, contradictions, and opt-in correction history separately. An exact resumable task adds at most six matching confirmed entries with source references.
+- `session_timeline_index` and `session_timeline_search` provide explicitly enrolled, scope-bound bounded indexing and time-or-two-term recall of redacted structured transcript evidence. An explicit same-task prior-session query ranks only the signed sidecar before verifying one immutable source and returns stable session/message references. The tools never register arbitrary paths, return raw transcript bytes, or add authority. See [bounded session timeline](docs/session-timeline.md).
 - `audit` runs the same ten gates available through the CLI.
 
 Relationship updates supersede the active view but retain the previous observation in append-only graph history. Permission-like and credential-like attributes are rejected recursively. See [relationships and learning](docs/relationships.md).
 
 Attention is deliberately restrained: installed hooks retain minimal heartbeats, promises, and blockers without storing transcripts; each event requires an exact known actor/project/task scope; private and group visibility stays exact; and quiet hours, focus, throttling, lifecycle transitions, deletion, and purge remain enforceable. Events are context only—they send no messages, start no work, and grant no authority. See [attention](docs/attention.md).
 
+Configurable autonomy is enforced per explicitly registered project and exact tenant/group scope. Four cumulative levels separate bounded observation, proactive advice, reversible local execution and publication. Execute/publish decisions also require a current exact execution grant; publish needs a separate local confirmation. The project portfolio scans only enrolled non-symlinked roots, classifies evidence, deduplicates findings and exposes at most one rate-limited context notice. It never discovers sibling projects or creates authority. See [configurable autonomy](docs/autonomy.md).
+
 Safe learning is evidence-first: general candidates remain invisible until reviewed. Low-risk behavior candidates additionally require a locally confirmed immutable evaluation contract and independent fixed-task measurements before and after an exact-scope Canary. After-results count only when they bind to that unchanged contract, distinct preflight-bound projection receipts and exact-session model-stop delivery receipts. The contract freezes completion deadlines before the first trial; missing delivery or outcome evidence becomes a blocking receipt and automatic rollback. Model self-evaluation cannot promote a lesson, later configuration cannot lower frozen thresholds, and no average can hide a blocking defect. A separate default-off continuity opt-in can automatically accept only direct, high-confidence style, preference, no-go, correction, project-fact, and reference signals. Sensitive personal facts, secrets, identity merges, private group content, and operational or authority claims are always rejected. See [automatic continuity](docs/automatic-continuity.md) and [safe learning](docs/learning.md).
 
 Delegation is intentionally narrower than authority: a relationship such as `responsible-for` never permits assignment. Cross-entity task actions require an explicit local actor/action/target grant, while tasks, open threads, and handoffs remain context-only. See [delegation and coordination](docs/coordination.md).
@@ -356,7 +381,7 @@ New agents that do not have identity files yet can start with the included [`spi
 | Conduct | Working behavior and verification habits | On explicit feedback |
 | Grown history | Dated experience and corrections | Append-only |
 
-The manual [`skill/SKILL.md`](skill/SKILL.md) can scaffold and audit this optional layout. It is only for an agent with no existing spine. AgentSpine never migrates an established agent into the example, and the normal plugin resolver continues to discover and preserve whatever files already exist.
+The common [`skills/agent-spine/SKILL.md`](skills/agent-spine/SKILL.md) documents the bounded readiness and delivery workflow. It does not grant tools or permissions. AgentSpine never migrates an established agent into the example, and the normal plugin resolver continues to discover and preserve whatever files already exist.
 
 ## Design principles
 
@@ -384,6 +409,7 @@ AgentSpine is in active early development. `v0.8` adds authenticated persona syn
 | Reproduce the complete host behavior | [Visible cross-host acceptance](docs/acceptance.md) |
 | Enable automatic continuity | [Automatic continuity](docs/automatic-continuity.md) |
 | Load one compact session packet | [Session briefing](docs/session-briefing.md) |
+| Persist measured facts and visible uncertainty | [Provenance-bound world model](docs/world-model.md) |
 | Resume one exactly authorized job | [Rights-bound self-starter](docs/selfstarter.md) |
 | Understand relationships and history | [Relationships](docs/relationships.md) |
 | Configure sparse follow-ups | [Attention](docs/attention.md) |

package/agent-spine-plugin/blun.plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-spine",
-  "version": "0.59.1",
+  "version": "0.73.0",
   "description": "A non-destructive identity and memory spine for BLUN King agents.",
   "license": "Apache-2.0",
   "author": {
@@ -15,9 +15,9 @@
     }
   },
   "hooks": [
-    { "event": "SessionStart", "command": "node \"./src/hook.js\"", "timeout": 180 },
+    { "event": "SessionStart", "command": "node \"./src/hook.js\"", "timeout": 15 },
     { "event": "UserPromptSubmit", "command": "node \"./src/hook.js\"", "timeout": 15 },
-    { "event": "PreToolUse", "matcher": "Edit|Write|apply_patch|Bash|exec_command", "command": "node \"./src/hook.js\"", "timeout": 15 },
+    { "event": "PreToolUse", "matcher": "^(?:Edit|Write|apply_patch|Bash|PowerShell|exec_command|mcp__(?:agent-spine|plugin-agent-spine_agent-spine)__session_timeline_(?:index|search))$", "command": "node \"./src/hook.js\"", "timeout": 15 },
     { "event": "PostToolUse", "command": "node \"./src/hook.js\" --silent-oversize-post-tool-use", "timeout": 15 },
     { "event": "PreCompact", "command": "node \"./src/hook.js\"", "timeout": 15 },
     { "event": "PostCompact", "command": "node \"./src/hook.js\"", "timeout": 15 },

package/agent-spine-plugin/docs/acceptance.md

@@ -0,0 +1,61 @@
+# Visible cross-host acceptance
+
+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.
+
+```bash
+agentspine acceptance
+agentspine acceptance --json
+npm run acceptance
+```
+
+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.
+
+## What the run proves
+
+```mermaid
+sequenceDiagram
+    participant C as Claude lifecycle
+    participant A as AgentSpine hooks
+    participant S as External state
+    participant X as Codex lifecycle
+    C->>A: Swedish prompt and SessionStart
+    A->>S: scoped learning, attention, and checkpoint receipts
+    S-->>C: exact byte-budgeted briefing
+    X->>A: Spanish prompt and PostCompact
+    S-->>X: separately scoped briefing
+    C->>A: authorized effect, Stop, new SessionStart
+    A->>S: current-rights checks and atomic checkpoint
+    S-->>C: resume checkpoint
+    Note over C,X: zero model-side MCP calls
+```
+
+The human-readable report contains these gates:
+
+| Gate | Evidence |
+|---|---|
+| Canonical identities | Freja Åström and Lucía Ortega, their groups, projects, and tasks have separate stable IDs |
+| Multilingual style continuity | Direct Swedish and Spanish style requests are minimally captured after opt-in |
+| Attention lifecycle | Heartbeat, promise, and blocker events retain scope, provenance, and deduplication |
+| Real restart | Claude receives the correct style and promise on a new `SessionStart` |
+| Real compaction boundary | Codex receives the correct Spanish context on `PostCompact` |
+| Person and group isolation | The other person and group cannot see foreign private or group context |
+| Correction and history | A Swedish correction becomes active without replacing prior history |
+| Atomic rollback | Rollback removes the correction and restores the earlier accepted style |
+| Authorized resume | An exact local grant starts and resumes one job on its durable checkpoint |
+| Denied foreign effect | A different actor cannot use the active lease or known task |
+| Durable checkpointing | Effect, result, stop, and resume retain idempotent external receipts |
+| Complete person purge | Later Codex startup cannot recall the purged person's context |
+| Byte preservation | `AGENTS.md`, `CLAUDE.md`, and `SOUL.md` hashes remain identical |
+| Final audit | All ten preservation and safety gates pass |
+
+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.
+
+## Installation proof
+
+`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.
+
+## Deliberate trust boundaries
+
+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.
+
+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.

package/agent-spine-plugin/docs/assignment-continuation.md

@@ -0,0 +1,48 @@
+# Assignment continuation and new-file preflight
+
+AgentSpine 0.72.3 distinguishes a host-explicit continuation from a new delivery.
+This is context-only bookkeeping, never authorization to write, use a tool or skip a test.
+
+## Host contract
+
+- A `UserPromptSubmit` without `assignment_id` / `assignmentId` starts a new assignment.
+- For a supplementary message belonging to the unfinished delivery, the host carries the exact active identifier returned by the preceding hook response. Both aliases, if supplied, must agree.
+- Host, session, project, entity, group and task must match, including absent fields. Goal, step, queue, attempt and plan digest must also match for a goal-bound delivery.
+- A continuation reads the current requirement under the assignment lock. It does not rotate the pointer, rewrite registrations, clear tests, close writes or create a replacement requirement.
+- A completed or consumed requirement cannot be continued. Starting another delivery still requires its own briefing, knowledge and premortem calls.
+- `PostCompact` and later tool hooks retain their existing behavior. Prompt text such as “continue” is never interpreted as a trusted assignment selector.
+
+The host must decide whether input is a new delivery or a supplement. Merely mentioning an identifier in chat or a skill is insufficient. Hosts that do not carry this structured field still create a new assignment on each prompt; this release does not claim they have native continuation support.
+
+Existing 0.72.2 records are not rewritten. Ordinary legacy assignment bindings remain readable. If an old goal assignment lacks the exact goal-binding metadata needed for explicit continuation, this selector cannot authorize that continuation; the existing goal lifecycle and its gates remain unchanged.
+
+## New files
+
+`delivery_knowledge_query` accepts a project-relative target that does not yet exist.
+It returns `state: "absent"`, `bytes: 0`, `sha256: null` and the nearest verified existing parent, rather than inventing a digest or creating the target. Each existing parent must be a regular directory, not a symlink, inside the canonical project boundary. Parents and absence are rechecked before returning.
+
+Existing regular files retain their byte count and SHA-256 snapshot. Symlinked targets or parents, path escapes, non-directory parents, permission errors and observed races fail the query and produce no successful knowledge receipt. Only `ENOENT` means absent. This is a point-in-time observation; native write authorization and subsequent verification still apply.
+
+## Reproducible evidence
+
+Run `node --test test/assignment-continuation.test.js test/assignment-continuation-boundaries.test.js test/delivery-target.test.js test/assignment-recovery.test.js`.
+
+The original 0.72.2 reader fails two positive assertions: a supplementary prompt changes the requirement despite an explicit assignment identifier; a new target fails its MCP query with `ENOENT`. The new reader keeps one obligation through multiple turns, a supplementary prompt after writing, compaction and a separate MCP process. The second assignment cannot close using the first write's test. In 0.72.4, the child artifact tests additionally clear inherited `NODE_TEST_CONTEXT` and require TAP evidence of an executed assertion. The original positive child exit alone could include a skipped recursive runner and was insufficient evidence that its assertion ran; see [the corrected evidence](structured-completion.md).
+
+Continuation adds no tree traversal. A nine-sample local comparison measured 6.91 ms median for fresh preparation and 2.42 ms for continuation before the final full regression; the test reports current measurements, not a universal latency promise. Crash recovery kills a process inside the state read and waits for the real 15-second lock lease; it never edits the lock timestamp or historical state to force recovery.
+
+CI run 143 exposed a Windows-only defect in the new fault-injection test: its literal forward-slash comparison did not match native paths, so the intended permission exception never occurred. The corrected probe uses native path joining and explicitly asserts both permission injection and parent replacement. No production protection or timeout was relaxed; the initial red CI is not counted as a successful validation.
+
+CI run 144 exposed a macOS cleanup race after an unsuccessful knowledge query. A deterministic MCP probe confirmed that an invalid target could produce its error response while a sibling target read was still suspended. Knowledge queries now settle every started bounded target, contract and briefing operation before returning an error, preserve the original rejection and produce no success receipt. The delayed-read regression observes the response boundary; it does not retry or suppress cleanup errors.
+
+Separate Windows failures remain under investigation: an installed-hook timeout (run 143), a pre-existing aggregate audit assertion (run 144), and an installed Codex denial-shape assertion (run 145). The synthetic installation check now reports its actual decision, reason and protocol fields; aggregate audit assertions report failed gates. Assertions and deadlines are unchanged. Passing other matrix jobs does not resolve these findings or establish live host compatibility.
+
+Run 146 identified a concrete installed-hook degradation: native source resolution exceeded its existing 2,000 ms deadline while the package probe competed with other file-intensive suites. The hermetic runner now executes that package probe alone once in each profile, then runs all remaining files with the existing worker count. Its 2,000 ms source budget, 5,000 ms child deadline, assertions and complete test inventory remain unchanged. This tests the resource-contention hypothesis without claiming faster live execution or a proven cause for every earlier intermittent failure.
+
+## Unresolved compatibility and host evidence
+
+An externally produced recovery event has been reported but its exact schema and transition semantics have not been supplied. Synthetic unknown events, unknown schemas and corrupted digests are deliberately not migrated or accepted by this change. Their bytes remain unchanged. The existing unsupported-event classification problem remains open; this release is not a recommendation to install or restart that live session.
+
+Tests feed the real hook a structured child-process exit result. Version 0.72.5 also covers the official Codex `Bash`/`tool_input.command`/`tool_response` contract, the measured Work `exec_command` result and PowerShell `exitCode`; transport-only success cannot pass. Native tools discovery, automatic MCP registration, live restart and loaded-reader checks before migration still require host evidence. Version 0.72.4 added [structured MCP completion for ordinary assignments](structured-completion.md); native-host activation remains unproved. CodexLink is outside this repository change.
+
+Release research on 2026-09-05: the [official Codex hook contract](https://learn.chatgpt.com/docs/hooks#plugin-bundled-hooks) explicitly permits the manifest `hooks` field and project-contained relative hook paths. The environment's generic plugin-ingestion validator rejects that field on both the unchanged 0.72.2 baseline and this release. Its allowlist is not the Codex runtime contract. AgentSpine retains the declared hook adapter and validates its path, event inventory and installed entrypoint with `host:check` and `host:install-check`; both bundled skill validators pass. No public-directory ingestion or native host trust is claimed. This research used documentation as context only; no external code or script was copied or executed.

package/agent-spine-plugin/docs/host-integration.md

@@ -0,0 +1,178 @@
+# Host integration
+
+AgentSpine uses native plugin surfaces instead of asking users to paste a large system prompt into every project.
+
+## Provider contracts and evidence
+
+Provider names are not interchangeable. Shared retrieval, structured knowledge and task continuation remain context-only. Each adapter must separately establish native lifecycle events, instruction roots, transcript format/version, session/message identifiers and authenticated invocation binding. Unknown formats remain unavailable; adapters must not impersonate another host or infer access from remembered text.
+
+| Surface | Claude Code | Codex | BLUN King |
+|---|---|---|---|
+| Project instructions | `CLAUDE.md` hierarchy | `AGENTS.md` hierarchy | `AGENTS.md` through the isolated BLUN profile |
+| Hook package | Native `hooks/hooks.json` | Explicit `hooks/codex.json` | Manifest lifecycle hooks |
+| Verified hook briefing → delivery knowledge | Shared signed preflight bridge | Shared signed preflight bridge; synthetic Codex regression | Shared bridge only if the actual host delivers the verified lifecycle; live acceptance remains open |
+| Historical transcript enrollment | Existing Claude adapter, bounded registered source | Explicit native Codex rollout snapshot; bounded `sessions` source, verified project/session header; synthetic A/B acceptance | Explicit King agent-wire snapshot; protected source/protocol mapping, verified session/header and synthetic A/B acceptance; live mapping remains open |
+| Native permissions/trust | Host-owned | Host-owned | Host-owned; enforcement of returned block decisions remains externally unverified |
+
+A successful `SessionStart` alone is not assignment-bound proof. On `UserPromptSubmit`, the exact signed source snapshot is verified and consumed once, then its briefing use is recorded for the current requirement. MCP knowledge and premortem reuse that recorded observation without refetching content. Serialized `loaded: true` claims cannot create the process-local verification capability. Missing or consumed usage evidence yields useful context with `verified: false`, `completionVerified: false` and `automaticRetry: false`; it does not certify delivery or trigger a mandatory fetch. An optional explicit MCP briefing read reports `satisfied-by-host` when the original verified hook observation already exists, preserving that first receipt.
+
+Adapter acceptance must use synthetic sessions A/B, a bounded registered project root, exact source bytes and stable provenance, and cover restart, changed sources, foreign project/tenant/group, private-source exclusion and service failure. Report repository tests separately from the installed provider version and live-host observations. Never claim cross-provider history support from package validation, matching tool names or another provider's passing test.
+
+## Claude Code
+
+| Component | Path | Purpose |
+|---|---|---|
+| Manifest | `.claude-plugin/plugin.json` | Package identity and version |
+| Marketplace | `.claude-plugin/marketplace.json` | GitHub installation and updates |
+| Skill | `skills/agent-spine/SKILL.md` | Context rules and preservation invariants |
+| MCP | `.mcp.json` | Read-only source tools plus external overlay workflows |
+| Hooks | `hooks/hooks.json` | Automatic briefing, attention, protected-source guard, and rights-bound checkpoints |
+
+Install from GitHub:
+
+```bash
+claude plugin marketplace add Maykbiletti/AgentSpine
+claude plugin install agent-spine@agent-spine
+```
+
+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.
+
+Version `0.73.0` keeps the `0.72.7` managed common Codex skill, stable launcher, loaded-reader verification, assignment continuation and structured completion contracts, and adds bounded post-compaction session-evidence recall. It leaves host transcripts in place, never injects their full content, and exposes only explicit, scope-bound redacted cards. A verified `UserPromptSubmit` creates an opaque receipt; a direct Claude session stays excluded until the local owner runs `timeline-receipt --root …` and `timeline-enroll --root … --receipt asthr_… --confirm-local-timeline`. Groups stay excluded. Writing deliveries can reuse the verified hook briefing for `delivery_knowledge_query` and `record_delivery_premortem` with the exact hook-issued requirement. These are advisory preparation; missing proof never blocks ordinary authorized work.
+
+Ordinary assignments may now call [`complete_delivery`](structured-completion.md) after observed tests to store the three completion checks and use a normal final summary. Stop still checks the latest write and current test evidence. Goal and queue deliveries retain their existing completion route. This repository operation does not itself register MCP in a native host or validate a live update.
+
+A contradictory retry is rejected and stored separately without changing the first valid registration. A legacy 0.72 conflict can be preserved and moved to a fresh requirement through either `recover_delivery_premortem` or `agentspine premortem-recover <predecessor-requirement> --root <project>`. The returned requirement must perform all three preflight calls again; recovery never deletes evidence or grants authority.
+
+Version `0.39.0` replaces the `0.38.0` plugin cache identity.
+
+Version `0.38.0` replaces the `0.37.0` plugin cache identity.
+
+Version `0.36.0` replaces the `0.35.0` plugin cache identity.
+
+The Claude manifest explicitly references `./.mcp.json`. The hook bundle remains at Claude Code's native auto-discovery path `hooks/hooks.json`; it is deliberately not registered a second time through the manifest. Codex selects its host-specific `hooks/codex.json` adapter through `.codex-plugin/plugin.json`. Version `0.35.0` replaces the `0.34.0` plugin cache identity. The hook definitions contain only portable documented fields; `hooks/version.json` carries the separately validated bundle release and preflight contract. The repository checks resolve installed-root variables, perform a real MCP `initialize` handshake, validate exactly one native hook command per event, and exercise staged clean install, previous-version cache rejection, upgrade, host-native source resolution, indexed and lazy Claude memory, automatic multilingual briefing, pre-answer recall, authenticated persona graph reconciliation, attention, exact job start, tool checkpoint, new-session resume, purge, and uninstall preservation:
+
+```bash
+npm run host:check
+npm run host:install-check
+npm run acceptance
+```
+
+### Claude MCP troubleshooting
+
+If the plugin is listed but `agent-spine` is missing from `/mcp`, update the marketplace cache and reinstall before starting a new session:
+
+```bash
+claude plugin marketplace update agent-spine
+claude plugin uninstall agent-spine@agent-spine
+claude plugin install agent-spine@agent-spine
+claude plugin list
+claude mcp list
+```
+
+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.
+
+## Codex
+
+History uses the native Codex adapter described in [session timeline](session-timeline.md#codex-native-rollout-contract). It does not use Claude enrollment or a Claude-shaped transcript. Installed-host acceptance remains separate from the repository fixtures.
+
+| Component | Path | Purpose |
+|---|---|---|
+| Manifest | `.codex-plugin/plugin.json` | Package identity plus explicit skill and MCP registration |
+| Skill | `skills/agent-spine/SKILL.md` | Context rules and preservation invariants |
+| MCP | Manifest `mcpServers` | Read-only source tools plus external overlay workflows |
+| Hooks | `hooks/codex.json` | Manifest-selected lifecycle guardrails |
+
+Open `/plugins` in Codex CLI after configuring a marketplace that contains AgentSpine, then start a new session. Review the installed hook source and trust state with `/hooks`; Codex also presents a startup warning when a new or changed hook definition needs trust. Codex records trust against the exact hook-definition hash, so an installed, updated, or previously untrusted bundle is skipped until that current definition is reviewed and trusted. This follows the official [Codex hooks trust and plugin discovery contract](https://developers.openai.com/codex/hooks).
+
+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:
+
+```bash
+agentspine host-install codex --confirm-local-host-install --json
+```
+
+Use `--codex-home /absolute/profile` and `--skills-root /absolute/user-skills` only for non-default or synthetic roots. The default skill destination is `$HOME/.agents/skills/agent-spine/SKILL.md`, one of Codex's documented [user skill discovery locations](https://developers.openai.com/codex/build-skills). AgentSpine refuses an existing unowned directory at that name, serializes parallel updates and recovers only recognizable sealed partial states. The stable launcher lives below the Codex profile and points through an atomically replaced, digest-sealed registration; `config.toml` does not need a versioned cache path. Start a new Codex process after a successful update. During MCP `initialize`, the launcher checks the canonical package root, exact package/runtime version and required tools before it forwards any state-bearing request. A failed check returns no tools and does not migrate or delete state. User-controlled executable and hook trust remain separate and mandatory. The configuration shape follows the official [Codex MCP configuration contract](https://developers.openai.com/codex/mcp).
+
+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.
+
+Verify the live host in a newly started Codex CLI session:
+
+```text
+/plugins
+/hooks
+Trust all and continue
+```
+
+Acceptance requires four separate observations from that new host process: `skills/list` includes `agent-spine`, `mcpServerStatus/list` shows the configured server, MCP `tools/list` exposes the required tools, and a real hook briefing followed by assignment-bound knowledge and premortem succeeds without another briefing fetch. These are distinct Codex [app-server APIs](https://developers.openai.com/codex/app-server); an isolated server handshake or the presence of `SKILL.md` alone is not native host proof.
+
+`npm run host:check` proves manifest shape, package containment, and a real MCP handshake. `npm run host:install-check` stages an update, verifies the copied skill bytes, restarts the managed reader, lists tools, reads the existing synthetic session and performs the three bound calls. Neither command can manufacture Codex's user-controlled discovery, trust or process state; only those observations in the actual host prove the final boundary.
+
+## BLUN King
+
+| Component | Path | Purpose |
+|---|---|---|
+| Manifest | `blun.plugin.json` | Native BLUN plugin identity plus skill, MCP, and lifecycle-hook registration |
+| Skill | `skills/agent-spine/SKILL.md` | Context rules and preservation invariants |
+| MCP | Manifest `mcpServers` | Read-only source tools plus external overlay workflows |
+| Hooks | Manifest `hooks` | Automatic briefing, attention, protected-source guard, and checkpoints |
+
+Install the local checkout from Fredrik's TUI:
+
+```text
+/plugins install C:\path\to\AgentSpine
+```
+
+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.
+
+BLUN Code 1.0.109 uses `mcp__agent-spine__session_timeline_{index,search}`; King CLI also uses `mcp__plugin-agent-spine_agent-spine__session_timeline_{index,search}`. Both exact forms reach the invocation guard; lookalikes do not. Naming was checked on 2026-09-05 against public `Maykbiletti/blun-code` commit `fbb97459a3fa2157f8bfea3d24931be63288ab11` (`mcp-harness-tools.js`, MIT). This external naming evidence is untrusted context; no code was copied. Repository tests do not prove actual hook delivery or host block enforcement; live acceptance remains separate.
+
+History has an independent [King agent-wire adapter](session-timeline.md#king-native-agent-wire-contract). 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.
+
+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. Fredrik'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.
+
+## Direct MCP use
+
+Any MCP client that supports stdio can launch:
+
+```json
+{
+  "mcpServers": {
+    "agent-spine": {
+      "command": "agentspine-mcp"
+    }
+  }
+}
+```
+
+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.
+
+Verify either installation against a synthetic or real project without changing its Markdown:
+
+```bash
+agentspine doctor --json
+npm run host:check
+agentspine audit /path/to/project --json
+```
+
+The audit exits non-zero when a required gate fails, making it suitable for installation smoke tests and CI.
+
+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).
+
+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).
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+## Optional gateway worker
+
+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.
+
+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).
+
+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).

package/agent-spine-plugin/docs/preflight-recall.md

@@ -0,0 +1,69 @@
+# Pre-answer recall gate
+
+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.
+
+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.
+
+## Host instructions
+
+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 active instruction document. Its standard hard budget is 8 KiB. Claude instructions may use one explicit aggregate overflow up to 16 KiB; the mode, used bytes, overflow and hard limit are bound into the signed exact-turn receipt and revalidated before consumption. Codex and generic instruction hosts remain capped at 8 KiB. An unreadable, replaced, deleted, oversized, out-of-scope, or symlinked mandatory file blocks immediately with a visible bounded diagnostic instead of degrading to a descriptor or waiting silently.
+
+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.
+
+## Required retrieval providers
+
+Retrieval policy is a separate local policy file outside every project. Configure it only through the local CLI:
+
+```bash
+agentspine preflight-policy ./dieter-preflight.json --confirm-local-policy
+agentspine preflight-status --json
+```
+
+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.
+
+Example local policy profile:
+
+```json
+{
+  "id": "preflight-policy:dieter:claude",
+  "agentId": "agent:dieter",
+  "host": "claude",
+  "profileId": "profile:dieter",
+  "tenantId": "tenant:company",
+  "enabled": true,
+  "providers": [
+    {
+      "schema": "agentspine.retrieval-provider/v1",
+      "id": "mnemo:primary",
+      "adapter": "mnemo-command/v1",
+      "required": true,
+      "failClosed": true,
+      "timeoutMs": 5000,
+      "command": "/absolute/path/to/mnemo-adapter",
+      "args": [],
+      "credentialEnv": ["MNEMO_TOKEN"]
+    }
+  ]
+}
+```
+
+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.
+
+## Must-Remember
+
+Conversation wording such as “Merk dir das” may create only a pending candidate. Activation requires a separate explicit local user confirmation:
+
+```bash
+agentspine remember-propose --claim "Keine halbfertigen Commits veröffentlichen." --user person:papa --tenant tenant:company --project project:agent-spine
+agentspine remember-confirm remember-candidate:… --confirm-local-user
+```
+
+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.
+
+## Enforcement modes and host limits
+
+`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.
+
+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.
+
+Host hierarchy and lifecycle behavior were checked on 2026-08-30 against the official [Claude Code hook reference](https://code.claude.com/docs/en/hooks) and [Codex AGENTS.md reference](https://developers.openai.com/codex/agent-configuration/agents-md).

package/agent-spine-plugin/docs/preservation-contract.md

@@ -0,0 +1,53 @@
+# Preservation contract
+
+The preservation contract is AgentSpine's primary compatibility promise.
+
+## Guaranteed
+
+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.
+
+The scanner:
+
+- opens source Markdown read-only;
+- never renames, moves, merges, normalizes, truncates, or rewrites it;
+- does not follow filesystem symlinks;
+- writes catalogs, graph overlays, attention, learning, delegation policy, coordination, imported sharing state, trust, and private signing keys only to the user state directory;
+- writes an explicitly requested HTTPS snapshot only to a new path outside the scanned project and never uploads or overwrites one;
+- uses an atomic temporary-file replacement for its own catalog;
+- keeps every discovered document visible even when another file has higher precedence.
+
+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.
+
+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.
+
+## Protected sources
+
+A source is protected from agent write tools when it is any of the following:
+
+- a native host instruction file;
+- a soul or persona file;
+- a memory index or a Markdown file below a memory directory;
+- a Markdown file explicitly linked from a protected source.
+
+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.
+
+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.
+
+## Conflicts and precedence
+
+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.
+
+## Uninstall
+
+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.
+
+## Not guaranteed
+
+AgentSpine cannot prevent:
+
+- direct user edits;
+- writes from programs outside the hooked host;
+- writes from host tool paths that do not participate in lifecycle hooks;
+- changes made while AgentSpine is not running.
+
+`agentspine verify` detects those changes relative to the last saved scan. It reports them and never restores files automatically.

package/agent-spine-plugin/docs/quality-gates.md

@@ -0,0 +1,50 @@
+# Ten quality gates
+
+`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.
+
+```bash
+agentspine audit /path/to/project
+agentspine audit /path/to/project --json
+```
+
+| Gate | Proof | Failure meaning |
+|---:|---|---|
+| 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 |
+| 2 | Catalog schema and discovery | Sources could not be represented deterministically |
+| 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 |
+| 4 | Native hierarchy mapping | A recognized host source lacks host mapping |
+| 5 | Markdown link integrity | An indexed local `.md` link has no target |
+| 6 | Conflict visibility | Precedence and competing candidates are surfaced for review |
+| 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 |
+| 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 |
+| 9 | Context budget | Resolved source bytes or the complete compact session briefing exceed the requested ceiling |
+| 10 | Byte preservation | A source hash changed during the audit or differs from the saved scan |
+
+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.
+
+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.
+
+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.
+
+## CI and troubleshooting
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+## Visible lifecycle acceptance
+
+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:
+
+```bash
+agentspine acceptance
+agentspine acceptance --json
+```
+
+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).