blun-king-cli 9.1.536 → 9.1.550

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

@@ -1,133 +0,0 @@
-# Safe learning
-
-AgentSpine separates an observation from a fact that may enter future context. An agent can propose a candidate and append evidence, but the candidate remains invisible to `learning_context` until it passes an explicit review or the narrowly scoped, default-off automatic policy. Version 0.11 adds an outcome-bound path for low-risk behavior: a lesson is useful only when fixed, externally measured tasks improve after a limited canary application.
-
-```mermaid
-flowchart LR
-    O["Observation"] --> C["Candidate"]
-    C --> E["Append-only evidence"]
-    E --> R{"Review gate"}
-    R -->|"explicit user confirmation"| A["Accepted context"]
-    R -->|"reject"| X["Rejected history"]
-    R -->|"opt-in fact policy"| A
-    E --> M["Independent before receipts"]
-    M --> K["Scoped canary"]
-    K --> N["Independent after receipts"]
-    N -->|"measured improvement"| A
-    N -->|"regression or blocking defect"| B["Automatic rollback"]
-    A --> S["Supersede without erasing"]
-    S --> B["Rollback restores prior fact"]
-```
-
-## Candidate kinds
-
-| Kind | Normal review path | Automatic eligibility |
-|---|---|---|
-| `preference` | Explicit confirmation | Never |
-| `no-go` | Explicit confirmation | Never |
-| `goal` | Explicit confirmation | Never |
-| `correction` | Explicit confirmation | Never |
-| `personal-fact` | Explicit confirmation | Never |
-| `project-fact` | Explicit confirmation | Opt-in, evidence-gated |
-| `reference` | Explicit confirmation | Opt-in, evidence-gated |
-| `behavior` | Explicit confirmation | Opt-in, outcome-gated canary |
-
-Every candidate and evidence record carries `authority: context-only`. Accepted learning can improve relevance and consistency, but it cannot grant permissions, delegation, production access, spending rights, policy exceptions, or instructions to act.
-
-## Evidence and provenance
-
-Evidence is append-only while a candidate is awaiting review. Supported evidence types are `user-statement`, `document`, `interaction`, and `test`. Document evidence must reference a discovered Markdown source; AgentSpine records that source's SHA-256 at observation time without editing it.
-
-Adding evidence stores the previous candidate version in history before recalculating confidence. Distinct evidence IDs or source fingerprints are counted for automatic evaluation. Secret-shaped content is rejected before it reaches learning state.
-
-## Explicit review
-
-Acceptance requires the `confirmedByUser` marker and a review reason. The marker is an integration attestation, not identity proof: a host adapter should set it only after an actual user gesture or unambiguous user instruction. AgentSpine never infers confirmation from another memory, Markdown sentence, candidate, agent message, or relationship edge.
-
-```bash
-agentspine learn-propose learning:concise \
-  --kind preference \
-  --claim "The preferred output is concise." \
-  --evidence "The user explicitly requested concise output." \
-  --privacy private
-
-agentspine learn-review learning:concise \
-  --decision accept \
-  --reason "Explicitly confirmed by the user." \
-  --confirmed-by-user
-
-agentspine learn-context . --include-private --json
-```
-
-Candidates never appear in learned context before acceptance. Native lifecycle hooks inject only accepted, exactly scoped learning inside the byte-budgeted session briefing. They never inject unreviewed candidates.
-
-## Optional automatic promotion
-
-Automatic promotion is disabled by default. When deliberately enabled, it applies only to `project-fact` and `reference`, and only when both confidence and distinct-evidence thresholds pass.
-
-```bash
-agentspine learn-config . \
-  --auto-promote true \
-  --min-confidence 0.9 \
-  --min-evidence 2
-
-agentspine learn-evaluate . --json
-```
-
-The accepted record stores the policy thresholds, evidence count, and evaluation time used for that decision. The audit rejects an accepted record with no valid manual-review proof or automatic-promotion snapshot. Personal facts, preferences, goals, corrections, and no-gos are never automatically promoted by this general evaluator.
-
-This evaluator is separate from [automatic continuity](automatic-continuity.md). After its own local privacy opt-in, the lifecycle adapter may accept only direct, high-confidence style preferences, no-gos, corrections, project facts, and references with a recorded threshold proof. Personal facts, group conversation content, identity claims, secrets, authority, access, and operational permissions are never eligible. The continuity path is not exposed through MCP.
-
-## Measured behavior loop
-
-`behavior` candidates use `agentspine.learning-outcome/v1` receipts. A receipt stores no prompt, answer, transcript, credential, or source content. It binds a normalized metric to one exact persona, user, tenant, project, group, task, evaluator, phase, and time. Metric values are normalized to `0..1`; the direction states whether higher or lower is better. Objective measurements, explicit user feedback, and model suggestions remain separate. Model suggestions are retained for diagnosis but never count toward automatic promotion or validation.
-
-Before promotion, the candidate needs the configured number of independent, fresh, non-model receipts for the same metric and exact scope, including at least one objective evaluator. It also needs the normal distinct-evidence and confidence thresholds. A conflicting active candidate blocks automatic promotion. Security, safety, identity, authentication, authorization, credential, policy, production, deployment, payment, and access lessons are marked for local review and can never enter this automatic path. Successful evaluation creates a time-limited canary rather than a final unmeasured claim. Only that exact scope receives the canary in its next briefing.
-
-```bash
-agentspine learn-propose learning:check-invariant \
-  --kind behavior \
-  --claim "Check the fixed invariant before answering." \
-  --evidence "Two fixture runs missed the invariant." \
-  --privacy shared \
-  --persona agent:synthetic --user user:synthetic --tenant tenant:synthetic \
-  --project project:synthetic --task task:synthetic
-
-agentspine learn-outcome learning:check-invariant \
-  --phase before --metric fixed-task-success --direction higher --value 0.40 \
-  --measurement objective --evaluator evaluator:test-a \
-  --persona agent:synthetic --user user:synthetic --tenant tenant:synthetic \
-  --project project:synthetic --task task:synthetic
-
-agentspine learn-evaluate . --json
-agentspine learn-status . --json
-```
-
-After canary use, the host records `after` receipts for the same metric and scope. Independent receipts meeting `minImprovement` validate the lesson. Any blocking defect rolls it back immediately; a regression beyond `regressionTolerance`, insufficient measured improvement, or expiry before validation also rolls it back. A superseded lesson is restored atomically. No average score can override a blocking defect.
-
-Outcome recording and policy changes are local CLI/runtime operations. MCP exposes only the read-only `learning_outcome_status` view for this loop; model-side MCP cannot manufacture outcome evidence. `learning_context` returns only active, unexpired or validated, exact-scope behavior lessons and reports stale canaries as degraded instead of silently projecting them.
-
-## Supersession and rollback
-
-New information does not overwrite an accepted fact. Propose a new candidate with `--supersedes` and the same kind, subject, and privacy scope. Acceptance marks the prior record `superseded` and retains both versions. Rollback deactivates the replacement and restores the prior accepted record atomically.
-
-```bash
-agentspine learn-propose learning:new-goal \
-  --kind goal \
-  --claim "The current goal is the new synthetic milestone." \
-  --evidence "The user changed the goal." \
-  --supersedes learning:old-goal
-
-agentspine learn-rollback learning:new-goal \
-  --reason "The change was recorded incorrectly."
-```
-
-Permanent deletion removes one candidate and its learning history. An accepted superseding record must be rolled back before deletion so its predecessor is not stranded.
-
-## Privacy and groups
-
-Private learning requires an explicit `includePrivate` read. Group learning requires a known group entity, an exact `groupId`, and—when a subject is present—a visible `member-of` edge. `includePrivate` does not bypass a different or missing group audience. Session hooks have no group audience and therefore expose no group learning.
-
-## Storage and concurrency
-
-`learning.json` lives in the same external per-project state directory as the catalog, graph, and attention state. Mutations use a per-project lock and atomic replacement, so concurrent agents cannot silently discard evidence. State is capped at 5 MiB and original Markdown remains byte-for-byte unchanged.

package/agent-spine-plugin/docs/object-transport.md

@@ -1,93 +0,0 @@
-# Immutable HTTPS object transport
-
-AgentSpine can publish a signed snapshot directly to any HTTPS service that implements a tiny create-only object contract. The protocol is provider-neutral: it needs no cloud SDK, account-specific URL format, database driver, or agent vendor.
-
-```mermaid
-sequenceDiagram
-    participant C as Local owner CLI
-    participant D as Signed directory adapter
-    participant O as HTTPS object service
-    C->>D: validate signed manifest and events
-    C->>C: build snapshot and SHA-256 address
-    C->>O: PUT /objects/{digest}.json<br/>If-None-Match: *
-    alt new object
-        O-->>C: 201 or 204
-    else object already exists
-        O-->>C: 412
-    end
-    C->>O: GET the exact object URL
-    O-->>C: bounded signed JSON snapshot
-    C->>C: verify bundle digest and every envelope
-```
-
-There is no overwrite, delete, listing, mutable latest pointer, or remote administration operation. A publish counts as successful only after AgentSpine reads the object back through the hardened HTTPS client and verifies the exact snapshot digest plus every nested Ed25519 envelope.
-
-## Publish
-
-Start with an authenticated directory adapter as described in [shared memory](shared-memory.md), then run:
-
-```bash
-export AGENTSPINE_OBJECT_TOKEN='deployment-supplied-value'
-
-agentspine share-https-publish /srv/agent-memory/team-alpha \
-  --root /path/to/publisher-project \
-  --base https://memory.example.org/agentspine/team-alpha \
-  --id snapshot:team-alpha-2026-08-28 \
-  --token-env AGENTSPINE_OBJECT_TOKEN \
-  --confirm-local-share
-```
-
-AgentSpine derives the immutable object URL:
-
-```text
-https://memory.example.org/agentspine/team-alpha/objects/{snapshot-sha256}.json
-```
-
-The token value is read only from the named environment variable. It is never accepted in the URL, persisted, returned, added to hooks, or exposed through MCP. Publishing always requires the explicit local confirmation flag, including public endpoints.
-
-## Server contract
-
-The service receives one request:
-
-```http
-PUT /agentspine/team-alpha/objects/{64-lowercase-hex-digest}.json
-Content-Type: application/vnd.agentspine.snapshot+json
-Content-Length: {exact bytes}
-If-None-Match: *
-X-AgentSpine-Digest: sha256:{same digest}
-Authorization: Bearer {optional deployment token}
-```
-
-It must atomically create the resource and return `201` or `204`. If that exact path already exists, it must leave the object untouched and return `412`. AgentSpine deliberately rejects a generic `200` response because it cannot distinguish creation from replacement. The service must then serve the exact bytes at the same URL with the response rules documented in [HTTPS snapshots](https-transport.md).
-
-The digest in the path is a routing and integrity aid, not authorization. Servers should independently compute it, enforce create-only semantics, authenticate writers, rate-limit requests, bound body size to 21 MiB, and retain audit logs that do not record bearer values or bodies.
-
-## Idempotency and failures
-
-- `201` or `204` followed by an exact verified read-back returns `created: true`.
-- `412` followed by the exact verified object is a safe idempotent retry and returns `alreadyExisted: true`.
-- A different, missing, malformed, unsigned, untrusted, or unreadable object fails the operation.
-- Redirects, DNS rebinding to disallowed addresses, TLS errors, oversized responses, compression, ambiguous URLs, timeouts, and unexpected status codes fail closed.
-- A failed upload may have reached the server. Retrying the same snapshot is safe because the object address is immutable and the read-back decides the result.
-
-## Private networks
-
-Private, loopback, link-local, reserved, multicast, carrier-grade NAT, and documentation ranges are rejected by default. A deliberately internal service needs both flags:
-
-```bash
-agentspine share-https-publish /srv/agent-memory/team-alpha \
-  --root /path/to/project \
-  --base https://memory.internal.example/agentspine/team-alpha \
-  --allow-private-network \
-  --confirm-local-share
-```
-
-The hostname is resolved and every answer is vetted before the socket is pinned to one approved address. TLS verification remains enabled.
-
-## Trust boundary
-
-Publishing transports only context that already passed the local sharing exporter. It cannot publish source Markdown, evidence text, private learning, relationships, attention, tasks, delegation policy, credentials, or signer private keys. The receiver still uses `share-https-pull`, imports into quarantine, trusts configured public keys, and performs a second local review before any claim reaches context.
-
-The object service never becomes an authority provider. Successful upload, bearer authentication, TLS, digests, and valid signatures grant no permissions, delegation, production access, spending rights, or policy exceptions.
-
-The transport is intentionally absent from MCP and lifecycle hooks. An agent can use reviewed shared context, but it cannot select an endpoint, read a token, publish, overwrite, or opt into a private network through AgentSpine's agent-controlled surfaces.

package/agent-spine-plugin/docs/peer-transport.md

@@ -1,88 +0,0 @@
-# Challenge-response peer transport
-
-AgentSpine can pull a fresh signed snapshot from another installation through any owner-selected executable that provides stdin and stdout. Typical carriers are SSH, container exec, a local process supervisor, or an organization-specific transport wrapper. AgentSpine itself opens no listening socket, selects no network, invokes no shell, and contains no vendor SDK.
-
-```mermaid
-sequenceDiagram
-    participant O as Receiving owner CLI
-    participant C as Chosen carrier process
-    participant P as Peer AgentSpine
-    O->>O: Generate 256-bit random challenge
-    O->>C: Spawn exact executable + argument array<br/>shell disabled, minimal environment
-    O->>P: One bounded JSON request on stdin
-    P->>P: Build signed immutable snapshot
-    P->>P: Bind challenge + snapshot to live Ed25519 signature
-    P-->>O: One bounded JSON response on stdout
-    O->>O: Verify challenge, outer key, manifest key,<br/>snapshot digest, nested signatures, and local trust
-    O->>O: Import claims only into quarantine
-```
-
-The random challenge proves that the remote peer holding the configured private key answered this request. A captured response cannot be replayed under a later challenge. This authenticates the peer and transport content; it does not make any claim authoritative.
-
-## Remote peer
-
-The serving side is deliberately one-shot. It reads one request, writes one response, and exits:
-
-```bash
-agentspine share-peer-serve /srv/agent-memory/team-alpha \
-  --root /srv/agent-project \
-  --signer signer:team-alpha \
-  --timeout-ms 10000 \
-  --confirm-local-share
-```
-
-The directory must be an authenticated shared-memory adapter. The selected signer must be the same Ed25519 key that signed its manifest. Starting the server requires explicit local owner confirmation; it does not become a background daemon or open a port.
-
-## Receiver
-
-Trust the peer's exported public identity first. Then provide an exact JSON argument array for the carrier:
-
-```bash
-agentspine share-peer-pull \
-  --root /path/to/receiver-project \
-  --command-json '["ssh","memory.example.org","agentspine","share-peer-serve","/srv/agent-memory/team-alpha","--root","/srv/agent-project","--signer","signer:team-alpha","--confirm-local-share"]' \
-  --timeout-ms 10000 \
-  --confirm-local-share
-```
-
-AgentSpine passes the first array item as the executable and every remaining item as a literal argument with Node's shell option disabled. The carrier itself may have additional semantics: for example, an SSH server commonly invokes a remote login shell. Configure and quote carrier-specific remote commands defensively, or use a fixed server-side wrapper that exposes only `share-peer-serve` with predetermined paths and signer.
-
-Both confirmations are intentional. The receiver confirms execution of the chosen local carrier. The peer confirms one export from its selected adapter. Neither confirmation approves imported claims for context.
-
-## Wire protocol
-
-The receiver sends one newline-terminated `agentspine.peer-request/v1` JSON object containing:
-
-- a random request ID;
-- a cryptographically random 32-byte lowercase-hex challenge;
-- the maximum accepted response bytes;
-- `authority: context-only`.
-
-The peer returns one newline-terminated Ed25519 `manifest` envelope. Its `agentspine.peer-response/v1` payload binds the exact request ID and challenge to a validated signed snapshot, creation time, digest, and `context-only` authority. The outer live-response signer must equal the snapshot-manifest signer. The receiving project must already trust that exact public key, and the nested snapshot importer independently revalidates the manifest and every event.
-
-Requests are limited to 4 KiB. Responses are limited to a receiver-selected value from 1 MiB through 22 MiB, with 22 MiB as the default and the existing snapshot limit still enforced. Only the first complete JSON frame is considered. Timeouts range from one to thirty seconds.
-
-## Process boundary
-
-Executing any program is a privileged local action. A malicious carrier executable can act with the user's operating-system permissions before AgentSpine sees a response. Use an absolute path or a trusted `PATH`, verify the executable, constrain SSH identities and remote commands, and apply normal operating-system sandboxing where appropriate.
-
-AgentSpine reduces accidental exposure by:
-
-- requiring explicit local confirmation;
-- never invoking a shell itself;
-- accepting only a bounded JSON array of bounded strings;
-- passing a minimal cross-platform environment containing path, home, temporary-directory, locale, SSH-agent, AgentSpine-state, and platform runtime variables;
-- omitting unrelated environment variables, including application tokens;
-- bounding and discarding stderr rather than returning it as agent context;
-- killing timed-out, noisy, invalid, or completed carrier processes;
-- never persisting the executable, arguments, request, challenge, or response.
-
-The SSH agent socket is included so SSH remains usable. Possession of that socket is powerful; operators who do not want agent forwarding should remove it from the invoking environment or use a carrier wrapper with narrower credentials.
-
-## Trust and authority boundary
-
-Successful challenge-response, process exit, SSH authentication, signatures, and digests create no permissions, delegation, production access, spending rights, or policy exceptions. The received snapshot enters the normal shared-memory quarantine. A second local user review remains mandatory before any imported claim can appear in context.
-
-Peer serving, carrier execution, pulls, process arguments, stdin/stdout frames, and signer selection are absent from MCP and lifecycle hooks. Agents may read already reviewed shared context, but they cannot start a peer, select an executable, export data, or approve a received claim through AgentSpine's agent-controlled surfaces.
-
-Only explicitly published accepted, non-private shared events enter the snapshot. Existing `AGENTS.md`, `CLAUDE.md`, `SOUL.md`, `MEMORY.md`, and every other discovered Markdown source remain in place and byte-for-byte unchanged.

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

@@ -1,69 +0,0 @@
-# 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 the documented blocking status and exit code 2 for controlled failures. 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

@@ -1,53 +0,0 @@
-# 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

@@ -1,50 +0,0 @@
-# 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 14 visible gates cover canonical identities, 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).

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

@@ -1,73 +0,0 @@
-# Relationships and learning
-
-AgentSpine keeps social context in the external overlay graph. It never writes learned facts into `SOUL.md`, `AGENTS.md`, `CLAUDE.md`, memory files, or any other project Markdown.
-
-## Data model
-
-```mermaid
-flowchart TB
-    E["Entity · person, agent, group, channel, project"]
-    R["Relationship · type, confidence, privacy"]
-    H["Superseded observation history"]
-    C["Privacy-filtered context"]
-    E --> R
-    R --> C
-    E --> H
-    R --> H
-```
-
-Entities have stable IDs, a kind, optional display name and aliases, attributes, provenance, confidence, and privacy. Relationships connect two known IDs with a typed relation. Name similarity never merges identities.
-
-Authenticated persona roster synchronization reconciles active `person`, `agent`, and `bot` identities into this graph. An exact roster `groupId` creates a missing group-scoped entity and an authenticated `member-of` edge. Replaying an unchanged roster repairs missing graph records without rewriting source Markdown or appending duplicate persona events.
-
-Supported privacy scopes are:
-
-| Scope | Default visibility |
-|---|---|
-| `private` | Returned only when private context is explicitly requested |
-| `shared` | Available to normal relationship-context reads |
-| `group` | Marked for group-specific context selection |
-
-Privacy is a context filter, not an access-control system. The host must still authorize who may invoke the tool and see its output.
-
-## Learning without erasure
-
-An upsert changes the active view. If the same entity, document annotation, or same typed edge already exists, AgentSpine first copies the previous record into append-only `history`. The old observation therefore remains inspectable with its original confidence, reason, and timestamp.
-
-```mermaid
-stateDiagram-v2
-    [*] --> Observed
-    Observed --> Active: first record
-    Active --> Historical: newer observation
-    Historical --> Active: previous value retained
-```
-
-This is supersession in relevance, not deletion or a claim that the newest statement is automatically true. Agents should use evidence, calibrated confidence, and explicit source documents where available.
-
-## Authority boundary
-
-Every entity, relationship, annotation, and history entry carries `authority: context-only`. Permission-like and credential-like attribute keys are rejected recursively. Responsibilities such as `responsible-for` describe the team; they do not authorize task assignment, tool use, access, delegation, billing, deployment, or data disclosure. Cross-entity task coordination uses the separate default-deny policy described in [delegation and coordination](coordination.md); no relationship edge can satisfy that policy.
-
-## CLI example
-
-Use synthetic IDs in shared examples and stable application IDs in real systems:
-
-```bash
-agentspine entity agent:builder --kind agent --name Builder --privacy shared
-agentspine entity project:site --kind project --name Site --privacy shared
-agentspine relate agent:builder project:site --relation responsible-for --privacy shared
-agentspine relationships agent:builder --json
-```
-
-The MCP tools expose additional attributes, aliases, source-document provenance, confidence, and explicit private reads.
-
-With an exact `groupId`, a relationship read returns the requested entity's direct visible edges plus current visible co-members of that group. This is a bounded team neighborhood, not an inferred friendship graph. Another group's members, inactive roster personas and private records remain excluded. Without an exact group audience, group-private peers are not returned.
-
-## Limits
-
-- The graph is local user state and is not synchronized automatically.
-- Authenticated roster state is synchronized only when an owner-configured roster or native manifest scope is active; chat names never create entities.
-- Relationship reads bypass project discovery, abort the graph read after a five-second local deadline, and return a visible `degraded` status without aborting the turn.
-- A 5 MiB graph ceiling stops unbounded growth instead of discarding history.
-- Attribute-key rejection cannot determine whether innocent-looking prose contains a secret.
-- Group-specific recipient policy and notification delivery are not implemented.