blun-king-cli 9.1.536 → 9.1.550

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

@@ -1,183 +0,0 @@
-# Architecture
-
-AgentSpine is a read-only overlay around existing agent context. It separates discovery, provenance, selection, delivery, and future learning so that no convenience layer becomes an accidental authority system.
-
-## Runtime topology
-
-```mermaid
-flowchart TB
-    subgraph Sources["Existing local sources"]
-      C["Constitution"]
-      S["Soul"]
-      M["Memory + references"]
-    end
-    subgraph Core["AgentSpine core"]
-      D["Discovery + SHA-256"]
-      R["Host-aware resolver"]
-      G["Context-only graph + attention + learning + continuity + tasks + shared quarantine"]
-      B["Scoped byte-budgeted session briefing"]
-      H["Provider-neutral native lifecycle adapter"]
-      P["Separate default-deny delegation policy"]
-      E["Exact local execution policy"]
-      J["Leased job + atomic checkpoint"]
-      A["Visible receipt-bound acceptance"]
-    end
-    subgraph Hosts["Agent hosts"]
-      X["Codex"]
-      L["Claude Code"]
-    end
-    C --> D
-    S --> D
-    M --> D
-    D --> R
-    G --> B
-    P --> G
-    E --> J
-    J --> H
-    R --> B
-    B --> H
-    H --> A
-    H --> X
-    H --> L
-```
-
-Source files are never copied into a canonical replacement. The catalog contains metadata and provenance. Claude project memory uses `MEMORY.md` as its only live index, opens only directly indexed relevant files through race-safe handles, and reuses integrity-checked snapshots from private external state when file identity is unchanged.
-
-## Context resolution
-
-```mermaid
-sequenceDiagram
-    participant H as Host
-    participant A as AgentSpine
-    participant F as Local files
-    H->>A: resolve_context(root, cwd, host)
-    A->>F: discover read-only
-    F-->>A: paths, links, bytes
-    A->>A: apply native hierarchy
-    A->>A: follow explicit links
-    A-->>H: ordered sources + budget map
-    H->>A: read_document(range)
-    A-->>H: exact content + SHA-256
-```
-
-Selection is intentionally conservative. Native host files are selected according to directory scope. Filename and folder classifications are only initial hints. Agents interpret the actual content and can add reasoned, confidence-scored annotations and links to a separate overlay graph. Explicit Markdown links and agent-created graph edges are followed without rewriting their source. Unrelated documents remain cataloged but do not consume context.
-
-## Session assembly
-
-```mermaid
-sequenceDiagram
-    participant H as Host
-    participant B as Session briefing
-    participant C as Constrained context readers
-    H->>B: host + entity/group/project/task + maxBytes
-    B->>C: native sources, relationships, tasks, accepted learning, reviewed sharing
-    B->>C: attention with focus active by default
-    C-->>B: independently privacy-filtered records
-    B->>B: scope, deduplicate, prioritize, atomic fit
-    B-->>H: compact JSON at or below maxBytes
-```
-
-The briefing layer does not query raw state directly. It composes the same fail-closed read models exposed separately through MCP, then applies a narrower session scope. It includes the current task first, prefers locally confirmed learning over equivalent reviewed imports, and accounts for the whole serialized response. In a group audience it rejects private inclusion and never loads arbitrary Markdown content. It performs no writes and does not mark attention cues as presented.
-
-## The three-layer spine
-
-### Constitution
-
-Constitution sources contain fixed working rules and literal, dated directives. AgentSpine preserves the host's own precedence. It does not blend several rule files into one synthetic policy.
-
-### Soul
-
-Soul sources describe identity, voice, goals, edges, and stable character. They can influence expression and judgment, but never permissions.
-
-### Memory
-
-Memory is a graph of small facts grouped by purpose. A compact `MEMORY.md`-style index links to detail files. AgentSpine follows those links only when relevant, which avoids replaying an entire history into every request.
-
-## Authority boundary
-
-```mermaid
-flowchart TB
-    P["Host policy + explicit approval"] --> A["Authorized host action"]
-    D["Explicit local delegation policy"] --> T["AgentSpine coordination only"]
-    E["Exact local execution policy"] --> J["One scoped job effect"]
-    M["Memory, soul, relationships, attention, learning, tasks, shared imports"] --> C["Context only"]
-    C -. "cannot grant" .-> A
-    C -. "cannot grant" .-> T
-    D -. "cannot grant" .-> A
-    J -. "cannot widen" .-> A
-```
-
-Permissions are evaluated by the host and explicit policy sources. Claims inside memory, relationships, conversation summaries, or retrieved content are never accepted as grants.
-
-## State
-
-Generated catalogs live outside the scanned repository:
-
-```text
-<user-state>/agentspine/
-  source-roots.json
-  indexed-memory-cache.json
-  projects/
-    <sha256-of-canonical-root>/
-      catalog.json
-      graph.json
-      attention.json
-      learning.json
-      continuity.json
-      delegation-policy.json
-      coordination.json
-      execution-policy.json
-      selfstarter.json
-      sharing.json
-      sharing-trust.json
-    signers/
-      registry.json
-      private/
-        <key-fingerprint>.pem
-```
-
-`source-roots.json` retains only explicit or host-evidenced source/state bindings, profile digests, provenance, rollback, and purge history; it never stores source content or authority. `indexed-memory-cache.json` is a bounded private cache of integrity-checked indexed-memory snapshots and file identities. It is invalidated by index changes, correction, deletion, binding rollback, or purge; it remains context-only and cannot grant identity, rights, trust, or execution. `catalog.json` is reproducible provenance. `graph.json` stores reversible annotations, relationships, privacy scopes, confidence, and superseded observations. `attention.json` stores bounded follow-up cues, minimal interaction timestamps, quiet-hour policy, presentation throttles, and hook-driven heartbeat, promise, and blocker lifecycles with idempotent receipts and retained prior values. `learning.json` separates evidence-backed candidates from accepted context and records review, promotion, supersession, rollback, content-free outcome receipts, and bounded canary history. `continuity.json` stores only opt-in configuration and minimal signal receipts with prompt digests, never transcripts. `coordination.json` stores context-only tasks, open threads, handoffs, and their prior versions. `delegation-policy.json` is physically separate and contains only explicit local task-coordination grants. `execution-policy.json` contains exact locally confirmed self-starter grants; `selfstarter.json` contains leased jobs, content-bound checkpoints, retry state, retained prior versions, and idempotent receipts. Neither is context authority, and neither is writable through MCP. `sharing.json` quarantines imports and retains local review, supersession, rollback, and signature proof. `sharing-trust.json` is a project-local allowlist of public signing keys; the installation-wide signer registry keeps private keys separate. Policy, trust, keys, and adapter administration are not writable through MCP. All are private user state. This gives uninstall a simple, auditable property: removing AgentSpine state cannot remove or alter original agent files.
-
-Task mutations read and validate policy while holding the policy lock, then write coordination state under a second lock. This lock order prevents a policy revocation from racing a new assignment. Invalid or malformed policy and coordination state fails closed and is never automatically overwritten.
-
-Self-starter mutations use the same fixed ordering: execution policy first, then job state. A host session holds at most one expiring job lease. `PreToolUse` records one pending effect only after the current exact grant and content-bound workspace digest pass; `PostToolUse` advances the checkpoint once. A crash can resume only when the workspace still equals the pending effect's pre-write digest. See [rights-bound self-starter](selfstarter.md).
-
-## Acceptance boundary
-
-The visible acceptance runner is an observer of the production lifecycle adapter, not a parallel implementation. It creates only synthetic project and state directories, invokes Claude Code and Codex event equivalents directly, and emits receipt-bound results after the same scope, privacy, authority, lease, checkpoint, purge, and audit checks pass. No MCP tool is selected. The runner deletes its temporary state and never treats a receipt as host trust or execution authority. See [visible cross-host acceptance](acceptance.md).
-
-## Transport boundary
-
-```mermaid
-flowchart LR
-    D["Signed directory exchange"] --> S["Immutable HTTPS snapshot"]
-    S --> P["Create-only content-addressed PUT"]
-    P --> H["Operator-controlled HTTPS object"]
-    H --> F["Signed ETag feed + local continuity receipt"]
-    H --> P2["Live challenge-response over owner-selected stdio carrier"]
-    D --> DB["Append-only local SQLite revisions"]
-    DB --> V
-    S --> H
-    H --> V["TLS + DNS + size + schema + signature validation"]
-    V --> Q["Local pending quarantine"]
-    Q --> R["Second local review"]
-    R --> C["Context-only shared memory"]
-    H -. "never grants" .-> A["Host or delegation authority"]
-```
-
-HTTPS snapshots are temporary transport artifacts, not canonical memory. The object publisher derives an immutable URL from the snapshot digest, requires create-only semantics, and verifies a hardened read-back. A signed feed may reference successive immutable objects through an ETag compare-and-swap pointer and a bounded digest chain. Receivers keep an external receipt so rollback, equivocation, signer replacement, and continuity gaps fail closed. The pull client materializes a validated snapshot in an operating-system temporary directory, invokes the same signed directory importer, and deletes the temporary files on success or failure. Endpoint configuration and bearer values are not written to AgentSpine state.
-
-A peer pull uses the same snapshot validator and quarantine importer without introducing an AgentSpine network listener. The receiver spawns one explicitly selected carrier with the shell disabled, sends a fresh random challenge, and accepts one signed bounded response. The live-response key must match both local trust and the snapshot-manifest key. AgentSpine does not persist the carrier command or protocol frames, and transport success remains context-only.
-
-The optional SQLite transport stores complete validated signed snapshots in an external local file. One immutable manifest binding anchors the adapter identity; append-only revisions form a digest chain and an atomic head advances in the same `BEGIN IMMEDIATE` transaction. Reads validate the exact application schema, database integrity, every retained snapshot, the full chain, and the head before reusing the signed quarantine importer. Database paths and administration remain CLI-only and outside the scanned project.
-
-## Extension points
-
-Future modules plug in behind the core boundary:
-
-- hosted database transports implementing the provider-neutral signed-envelope and shared-event contracts;
-- additional host resolvers.
-
-Each extension consumes read-only provenance and emits separate state. None receives permission authority.
-
-The reference directory, static HTTPS snapshot, immutable HTTPS object, signed feed, and one-shot peer adapters are optional external transports, not canonical storage. They export only owner-selected accepted learning, while a receiving installation keeps every import outside active context until a second local review. In signed mode, Ed25519 proves that an envelope matches a locally trusted public key; it does not make the payload authoritative. See [shared memory adapters](shared-memory.md), [HTTPS snapshots](https-transport.md), [immutable HTTPS objects](object-transport.md), [signed mutable feeds](feed-transport.md), and [peer transport](peer-transport.md).

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

@@ -1,121 +0,0 @@
-# Sparse attention
-
-AgentSpine attention helps an agent notice a small number of relevant follow-ups without turning relationships into surveillance or interruption. Version `0.3.0` also connects minimal heartbeat, promise, and blocker events to the installed Claude Code and Codex lifecycle hooks. It operates entirely in local external state and never sends a message, assigns a task, or invokes another tool.
-
-## What becomes a cue
-
-| Kind | Example purpose | Base ranking |
-|---|---|---:|
-| `unanswered-question` | A question still needs a response | Highest |
-| `promise` | A promised hand-off or follow-up is due | High |
-| `meaningful-change` | A material change may deserve acknowledgement | Medium |
-| `check-in` | A natural, non-urgent check-in may be useful | Low |
-
-The relationship graph can also suggest a check-in when a known person or agent connected by a team relation has no recent activity timestamp. AgentSpine records only that an interaction happened, not its conversation text.
-
-```mermaid
-flowchart TB
-    S["Open cues + relationship silence"] --> P["Privacy and due-time filter"]
-    H["Native hook lifecycle events"] --> E["Exact actor · group · project · task scope"]
-    E --> P
-    P --> G["Focus · quiet hours · throttle"]
-    G --> R["Sparse ranked suggestions"]
-    R --> H["Host decides whether to surface"]
-```
-
-## Hard restraints
-
-1. A cue is always `context-only`; it cannot grant permissions or delegation authority.
-2. `focusActive` suppresses unrelated cues. Only an active blocker, due promise, or stale heartbeat for the exact current task may remain visible.
-3. Quiet hours suppress every cue, including overnight ranges.
-4. Private cues and cues for private entities require `includePrivate: true`.
-5. Group cues require a known group entity and an exact matching `groupId` audience; entity-specific cues also require a visible `member-of` edge.
-6. `maxItems` limits a result to a small set; the default is three.
-7. `minIntervalHours` prevents a surfaced cue from repeating too soon.
-8. Lifecycle hooks inject the actual byte-budgeted, privacy-filtered briefing. Event summaries appear only for the exact actor, group, project, and task audience.
-9. No network, messaging, notification, or scheduling action occurs automatically.
-
-## Native lifecycle events
-
-The provider-neutral adapter writes three event kinds without waiting for the model to select an MCP tool:
-
-| Kind | Created or transitioned at | Active presentation |
-|---|---|---|
-| `heartbeat` | `PostToolUse`, then `Stop` or `SubagentStop` | Only after the configured stale interval and only for the exact current task |
-| `promise` | A direct opted-in prompt or a minimal host event envelope | While open and due |
-| `blocker` | A direct opted-in prompt or a minimal host event envelope | While open |
-
-Every event has a stable ID, immutable scope, privacy, status, occurrence count, hook name, host, timestamp, receipt ID, and SHA-256 provenance digest. Re-delivery of the same host receipt is idempotent; automatic heartbeats within the same minute and scope share one receipt to prevent tool-heavy sessions from flooding history. A status change preserves the prior value in append-only history. The stored record contains no prompt, transcript, tool arguments, tool output, credential, or permission claim.
-
-Prompt-derived promises and blockers require the existing local continuity opt-in. They are accepted only for a known person or agent, known project, and existing task. Group-conversation content, secrets, identity claims, and authority or access claims are rejected. Heartbeats are operational lifecycle receipts rather than learned preferences and require the same exact known scope.
-
-## CLI walkthrough
-
-Create a shared promise, inspect it, and mark it presented only when it reaches the user:
-
-```bash
-agentspine attention-add signal:handoff \
-  --kind promise \
-  --summary "Review the synthetic hand-off." \
-  --privacy shared \
-  --due 2027-01-15T09:00:00Z
-
-agentspine attention . --mark-presented --json
-agentspine attention-resolve signal:handoff --status completed
-```
-
-Record minimal interaction recency for an existing relationship entity:
-
-```bash
-agentspine attention-touch agent:builder --kind interaction --privacy private
-```
-
-For group-scoped state, create or discover the group entity first and pass the same ID while writing and reading:
-
-```bash
-agentspine attention-add signal:group-check \
-  --kind check-in \
-  --summary "Ask whether the group needs anything else." \
-  --privacy group \
-  --group group:alpha
-
-agentspine attention . --group group:alpha --mark-presented --json
-```
-
-Configure a sparse policy. Hours are interpreted using the explicit UTC offset, avoiding hidden locale assumptions:
-
-```bash
-agentspine attention-config . \
-  --max-items 2 \
-  --min-interval-hours 48 \
-  --silence-days 21 \
-  --heartbeat-stale-minutes 30 \
-  --quiet-start 22 \
-  --quiet-end 7 \
-  --utc-offset 120
-```
-
-Disable attention without deleting its state:
-
-```bash
-agentspine attention-config . --enabled false
-```
-
-Delete one cue and its retained attention history, or purge all attention data associated with an entity:
-
-```bash
-agentspine attention-delete signal:handoff
-agentspine attention-events . --include-history --json
-agentspine attention-event-delete event:blocker:alpha
-agentspine attention-purge agent:builder
-```
-
-## History and deletion
-
-Updating or resolving a cue or lifecycle event first retains its previous value in private attention history. This preserves how relevance changed without rewriting source Markdown. Permanent event deletion removes the active event, its receipts, retained versions, and presentation timestamp. Entity purge additionally removes matching events, receipts, activity timestamps, and relationship-silence presentation state.
-
-## Concurrency and limits
-
-Attention mutations use an external per-project lock and atomic file replacement so concurrent local agents do not silently overwrite one another. A stale lock is recoverable after 15 seconds. State is capped at 5 MiB; reaching the limit stops new writes instead of discarding old observations.
-
-The attention layer does not infer emotion, wellbeing, crisis, relationship status, or personal life facts. Those require conversation-appropriate judgment and separate safety behavior; silence alone is never evidence that something is wrong.

package/agent-spine-plugin/docs/automatic-continuity.md

@@ -1,79 +0,0 @@
-# Automatic continuity
-
-AgentSpine `0.8.0` connects the portal-neutral memory, briefing, attention, and exactly authorized job-checkpoint layers to installed Claude Code and Codex lifecycle hooks. Host-native source-root resolution keeps user continuity available across repositories while indexed lazy memory keeps project, group, task, and private state exact. The result is real host context, durable scoped attention state, and an optional rights-bound resume path at lifecycle boundaries—not a counter or a suggestion that the model should call an MCP tool later.
-
-## One-time setup
-
-The host first asks the user to trust the executable plugin components. AgentSpine cannot and must not approve itself. Conversation learning then needs one separate local privacy opt-in:
-
-```bash
-agentspine entity person:me --kind person --name "Me" --privacy shared
-agentspine continuity-config /path/to/project \
-  --enabled true \
-  --entity person:me \
-  --confirm-local-opt-in
-```
-
-The selected identity must already exist in the relationship graph. A direct session may use this default. A bridge serving multiple people or groups must pass exact `entity_id`, `group_id`, `project_id`, and `task_id` scope values in each native hook payload; AgentSpine does not merge identities by name.
-
-## Lifecycle
-
-```mermaid
-sequenceDiagram
-    participant H as Claude Code or Codex
-    participant L as Lifecycle adapter
-    participant S as External AgentSpine state
-    participant M as Model context
-    H->>L: SessionStart / Resume / PostCompact
-    L->>S: scan + privacy-scoped reads
-    S-->>L: accepted sources, relationships, learning, tasks, sharing, attention
-    L->>L: current request > stops > task > rules > older context
-    L-->>M: complete byte-budgeted session_briefing
-    H->>L: UserPromptSubmit
-    L->>S: optional minimal safe learning + promise/blocker event
-    L-->>M: refreshed scoped briefing
-    H->>L: PostToolUse / Stop / SubagentStop
-    L->>S: idempotent heartbeat or explicit status transition
-```
-
-The model does not need to call `scan`, `context`, or `session_briefing`. Those tools remain available for explicit inspection only.
-
-## What can be learned automatically
-
-Only direct, high-confidence, locally opted-in signals are eligible. An explicit style request, no-go, or correction is itself a user confirmation; project facts and references require the configured number of distinct observations (two by default):
-
-- response style and preferences;
-- explicit no-gos and corrections;
-- project facts;
-- references.
-
-Each retained signal has a stable digest, exact subject/project scope, time, kind, confidence, directness, provenance receipt, deduplication key, and context-only authority. The full prompt is never stored. Repeated hook delivery is idempotent. Accepted records use the existing learning history, rollback, and purge paths.
-
-The following are always rejected from automatic acceptance:
-
-- secrets, credentials, tokens, or access material;
-- sensitive personal facts;
-- identity merging or alias claims;
-- any private group or private-chat content;
-- rights, roles, delegation, approval, tool, file, network, database, production, payment, or policy claims.
-
-Conversation, memory, Markdown, relationships, signatures, and learned context can never create host or AgentSpine coordination rights.
-
-## Failure and deletion
-
-Corrupt continuity or dependent state yields a visible `failedClosed` hook packet. The adapter says recall was not loaded and continues under current host rules; it never fabricates a successful briefing.
-
-```bash
-agentspine continuity-status /path/to/project --json
-agentspine continuity-config /path/to/project --enabled false
-agentspine continuity-purge person:me --root /path/to/project --confirm-local-purge
-agentspine audit /path/to/project --json
-```
-
-Generated state remains in the operating system's private user-state directory. `SOUL.md`, `AGENTS.md`, `CLAUDE.md`, and every other existing Markdown source remain byte-for-byte unchanged during learning, rollback, purge, upgrade, and uninstall.
-
-Existing opted-in user continuity can be made repository-independent only through the explicit, reversible `source-bind --scope state-user` flow. No state is blindly copied between root hashes. See [host-native source roots](source-roots.md).
-
-## Deliberate boundary
-
-Promises, blockers, and heartbeats persist through automatic lifecycle events with exact actor, group, project, and task scope. A waiting job can start or resume only through the separate rights-bound self-starter and only while a current exact local host/owner grant passes again before every effect. Learning, attention, and briefing content never satisfy that grant. The full path is reproducible through the [visible cross-host acceptance](acceptance.md).

package/agent-spine-plugin/docs/channel-runtime.md

@@ -1,92 +0,0 @@
-# Authenticated channel wake runtime
-
-AgentSpine can accept one authenticated provider event, bind it to one exact agent lane, and inject it through the installed Claude Code or Codex `SessionStart` hook. This closes the failure mode where a Telegram or another portal message exists but the selected agent starts without the message, recipient, chat, thread, project, or group context.
-
-The runtime is provider-neutral. The optional `agentspine-worker` supplies the reference gateway for Telegram: polling, exact host-run handoff, and origin-bound delivery. AgentSpine owns the durable scope, authentication, replay protection, lease, and host-context handoff. It does not open a network port and does not infer a route from message text.
-
-```mermaid
-flowchart TB
-    P["Provider adapter"] --> I["Authenticated ingress"]
-    I --> Q["Durable exact-scope queue"]
-    Q --> H["Claude or Codex SessionStart"]
-    H --> B["Channel event + voice brief"]
-    B --> R["Provider adapter reply"]
-```
-
-## Exact binding
-
-A binding is created only through the local CLI and only with `--confirm-local-channel`:
-
-```bash
-agentspine channel-bind channel-binding:franz \
-  --provider telegram \
-  --tenant tenant:blun \
-  --account bot:franz \
-  --chat chat:team \
-  --thread topic:engineering \
-  --senders user:mayk \
-  --agent agent:franz \
-  --project project:blun \
-  --group group:engineering \
-  --session agent:franz:telegram:engineering \
-  --secret-env AGENTSPINE_TELEGRAM_INGRESS_SECRET \
-  --outbound-secret-env AGENTSPINE_TELEGRAM_TOKEN \
-  --capabilities receive,reply \
-  --confirm-local-channel
-```
-
-Provider, tenant, account, chat, optional thread, sender, agent, project, optional group, and session are exact stable IDs. Wildcards are rejected. An exact group binding additionally requires a visible `member-of` edge between the selected agent and that group. A second active binding cannot claim the same route.
-
-The binding stores only environment-variable names. The HMAC key and optional outbound provider token remain in the adapter environment; the HMAC key must contain at least 32 bytes. Policy administration is absent from MCP, hooks, memory, learning, relationships, and prompt content.
-
-## Ingress contract
-
-The adapter normalizes an incoming provider update to `agentspine.channel-event/v1`:
-
-```json
-{
-  "schema": "agentspine.channel-event/v1",
-  "eventId": "telegram:update:1001",
-  "provider": "telegram",
-  "tenantId": "tenant:blun",
-  "accountId": "bot:franz",
-  "chatId": "chat:team",
-  "threadId": "topic:engineering",
-  "senderId": "user:mayk",
-  "replyTo": "telegram:message:900",
-  "observedAt": "2032-01-01T00:00:01.000Z",
-  "privacy": "group",
-  "text": "Bitte prüfe den aktuellen Auftrag."
-}
-```
-
-It computes `HMAC-SHA256` over `channelEventSigningPayload(event)` and supplies the signature as `sha256=<64 lowercase hex characters>`. AgentSpine verifies the exact route, allowed sender, receive capability, signature, schema, size, and secret filter before writing anything. The signature and key are never persisted.
-
-Repeated delivery of the same event ID and payload is idempotent. Reuse of an event ID with different bytes or a different binding fails closed. State lives in the external per-project AgentSpine directory and uses one multi-process lock plus atomic replacement.
-
-## Wake and lease
-
-After successful ingress, the adapter starts the exact host lane and includes only this reference in the native start payload:
-
-```json
-{
-  "agent_spine_channel_event": {
-    "event_id": "telegram:update:1001",
-    "provider": "telegram"
-  }
-}
-```
-
-The start must also carry the exact agent, project, optional group, and host session IDs. The lifecycle hook atomically leases the event to that host session and injects its authenticated message and route alongside the normal session briefing. Competing workers cannot lease the same event. An expired lease becomes pending again with retained history and a receipt.
-
-Completion requires the exact current worker lease and a still-active binding. Revocation immediately rejects new ingress and cancels every pending or leased event for that binding. Current objects, retained versions, payload digests, and receipts are replayed by the audit; malformed or forged state disables the runtime.
-
-## Voice bridge
-
-Every session briefing also contains a bounded `agentspine.voice-brief/v1`. It draws only from the exact visible entity, persona-layer source descriptors, accepted preferences, corrections, no-gos, the current task, and active promise or blocker signals. Allowed structured voice fields are limited to warmth, directness, humor, length, rhythm, and formality.
-
-This bridge makes existing persona material operational without rewriting or migrating the source Markdown. It encourages natural continuity, avoids repeated questions, and briefly acknowledges relevant frustration, uncertainty, correction, or success. It explicitly prohibits invented emotions or consciousness. The entire brief remains `context-only` and can never grant a tool, route, send, or execution right.
-
-## Deliberate boundary
-
-This stage proves authenticated ingress, exact routing, durable leasing, the installed hook entrypoint, and voice continuity. Real Codex activation additionally requires the current plugin hook to appear in `/hooks` and be trusted by the user; direct execution of the bundled script is not accepted as evidence of that host boundary. The separate [durable gateway worker](gateway-runtime.md) can poll Telegram, invoke an owner-approved host runner, and send the generated answer. It is an explicit local process rather than a hook or MCP capability: no channel secret, network writer, or unattended process launcher is exposed through MCP or model-selected tools.

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

@@ -1,138 +0,0 @@
-# Delegation and coordination
-
-AgentSpine can retain tasks, open threads, and handoffs across sessions without turning memory into an authorization system. Work state and delegation policy are deliberately different files, different authorities, and different tool surfaces.
-
-## Separation by construction
-
-```mermaid
-flowchart LR
-    subgraph Context["Untrusted context"]
-      M["Markdown + memory"]
-      R["Relationships"]
-      L["Learning + attention"]
-    end
-    subgraph Policy["Explicit local owner policy"]
-      P["delegation-policy.json"]
-    end
-    D["Default-deny decision"]
-    T["coordination.json"]
-    H["Host authorization"]
-    M -. "never grants" .-> D
-    R -. "never grants" .-> D
-    L -. "never grants" .-> D
-    P --> D
-    D -->|"coordination allowed"| T
-    T -. "never grants" .-> H
-    P -. "does not grant" .-> H
-```
-
-`delegation-policy.json` contains only explicit local grants for AgentSpine task coordination. `coordination.json` contains context-only work records and append-only prior versions. Neither file grants host tool access, file or network access, production rights, spending authority, credentials, or policy exceptions. Those remain under the host and operating environment. The optional self-starter uses a third, separate `execution-policy.json`; see [rights-bound self-starter](selfstarter.md). A coordination task alone never creates an execution grant.
-
-A `responsible-for`, `reports-to`, or `works-with` relationship describes the team. It never satisfies a delegation check. A sentence in `SOUL.md`, `AGENTS.md`, `CLAUDE.md`, memory, accepted learning, a task, or an MCP response also cannot create a grant.
-
-## Default-deny delegation
-
-The supported coordination actions are:
-
-- `assign` — create a task assigned to another entity;
-- `reassign` — change an existing assignee, including assignment by a manager;
-- `manage` — change another entity's task content or non-terminal status;
-- `complete` — complete another entity's task;
-- `cancel` — cancel another entity's task.
-
-Creating an unassigned thread or assigning work to oneself is self-coordination and needs no delegation grant. An assignee may manage their own task. Every cross-entity action fails closed unless the actor, action, and target match an active explicit grant.
-
-Inspect the decision before acting:
-
-```bash
-agentspine delegation-check agent:lead \
-  --action assign \
-  --target agent:builder \
-  --root /path/to/project \
-  --json
-```
-
-The MCP server exposes `check_delegation`, but intentionally exposes no policy grant or revoke tool. This prevents an agent from widening the same policy it is expected to obey.
-
-## Owner-controlled policy changes
-
-The CLI is the local administration surface:
-
-```bash
-agentspine delegation-grant agent:lead \
-  --id grant:lead-builders \
-  --actions assign,reassign,manage \
-  --targets agent:builder \
-  --reason "Approved for local project coordination" \
-  --confirm-local-policy \
-  --root /path/to/project
-
-agentspine delegation-revoke grant:lead-builders \
-  --reason "Project handoff completed" \
-  --confirm-local-policy \
-  --root /path/to/project
-```
-
-`--confirm-local-policy` is an integration attestation, not authentication. A host or wrapper must bind it to a genuine local owner action and must not infer it from conversation, memory, Markdown, another agent, or a task. Grant IDs are immutable. Revocation retains the prior grant in policy history so existing assignment snapshots remain auditable, while future actions are denied.
-
-## Tasks, open threads, and handoffs
-
-```mermaid
-stateDiagram-v2
-    [*] --> open
-    open --> in_progress
-    in_progress --> blocked
-    blocked --> in_progress
-    open --> completed
-    in_progress --> completed
-    blocked --> completed
-    open --> cancelled
-    in_progress --> cancelled
-    blocked --> cancelled
-```
-
-Create and inspect work:
-
-```bash
-agentspine task-create task:release \
-  --actor agent:lead \
-  --assignee agent:builder \
-  --kind handoff \
-  --title "Prepare the release candidate" \
-  --summary "Run the documented release gates" \
-  --privacy shared \
-  --root /path/to/project
-
-agentspine task-update task:release \
-  --actor agent:builder \
-  --status in-progress \
-  --note "Validation is running" \
-  --root /path/to/project
-
-agentspine tasks /path/to/project --assignee agent:builder --json
-```
-
-The MCP equivalents are `create_task`, `update_task`, and `task_context`. Returned context omits the internal delegation snapshot. Each mutation retains the complete previous task value before replacing the active view. New information therefore changes current relevance without erasing what was previously understood.
-
-Permanent task deletion is CLI-only and requires the same explicit local confirmation marker. It removes the active record and all retained versions; use it for privacy removal, not routine completion.
-
-## Privacy and groups
-
-Tasks use `private`, `shared`, or `group` scope. Group tasks require a known group and visible `member-of` edges for the creator and assignee. Reads require the exact same group ID. `includePrivate` cannot bypass a missing or different group audience.
-
-Lifecycle hooks have no private or group audience. They inject only the number and kinds of open shared coordination records—never titles, summaries, notes, assignees, or delegation policy. The agent must explicitly request relevant context.
-
-## Integrity and concurrency
-
-Both state files are private external project state, capped at 5 MiB, written with restrictive file mode and atomic replacement. Cross-process locks serialize policy changes and task mutations. A task mutation holds the policy read lock until its coordination write completes, so revocation cannot race an assignment into existence.
-
-All decision and mutation paths validate current state before use. Unknown entities, secrets, forged provenance, invalid assignment snapshots, malformed JSON, or inconsistent policy cause a fail-closed error. Damaged files are reported by `agentspine audit` and are never overwritten automatically.
-
-## Deliberate limits
-
-- AgentSpine coordinates records without execution authority. The optional self-starter is the sole narrow exception and requires a separate current exact execution grant for every lifecycle effect.
-- It does not send Telegram, email, chat, or notification messages.
-- It does not authenticate the human operating a shell.
-- It does not synchronize policy or tasks across machines.
-- It does not treat organizational relationships as an access-control list.
-- It does not replace host approvals, operating-system permissions, or an external policy engine.