textus 0.54.2 → 0.55.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53f01828833f9c5e6cb0249fe513b92d6afbb210d90cfca10f51c560c8b2e2ca
-  data.tar.gz: 1956232435c941479290225e20168979beb270a6e2f5874df37c302e170a43e7
+  metadata.gz: 68d4176e50949378dcf62b98617c28bcf6f553c196b24f9263a97d8d5c6f382f
+  data.tar.gz: 7de0c2d9ee56d71e09cc0821d19b8ffcc00e3573fccc20ef3e610988ec5ff43c
 SHA512:
-  metadata.gz: c086755b90faab7ecebdeebd722e9458dbede54c5efa9be212d6d861c999655093166a1f61826aa9e09ebee8cd1cf57996d958bd410c3b682763d911ed44abe5
-  data.tar.gz: aad04f9470c3de178ad6c762ef3102528cbdc94922fedb79d121ffbadc23acc5dd3f52871f6b3c0c75664afdb968c12fa814b88fbedcbd0d914161e4e1f337ab
+  metadata.gz: 34322a4bfd59c817bdbaec436caba5cd8a25a7896065e16633270eb22bed7db20af339f45f7ee8ed632732f3679469328939d45490e3a6ce3528f654b00feba9
+  data.tar.gz: 6c4f94a584d8334e7dc68e543852bb687fa662c6e6eb1334cadf9d70ff01576552f71d773d462f03f3c4f0955496fe094c167df090880f473d3e850469f4c3cd

data/CHANGELOG.md

@@ -9,6 +9,43 @@ The **gem version** (`0.x.y`) is distinct from the **protocol version**
 bump is a breaking change that requires a store migration; the gem version
 tracks both additive improvements and breaking protocol bumps independently.
 
+## 0.55.1 — 2026-06-22 — CI fix: converge_now purges done jobs
+
+### Fixed
+
+- **publish_tree prune spec** — `converge_now` now purges "done" jobs before reseeding. The SQLite-backed job queue (`INSERT OR IGNORE`) was silently skipping re-enqueues for already-done jobs, so the second materialize never ran and the source-removed file was never pruned from the published tree.
+
+## 0.55.0 — 2026-06-22 — Architecture Deepening Phase 2
+
+**ADR-0119**: dry-monad actions, container split, geometry authority.
+
+### Added
+
+- **dry-monad Success/Failure actions** (PR #234): all 30 actions now return `Success(result)` or `Failure(code:, message:)` via `Dry::Monads`. `Value::Result.unwrap` converts Failure → `ActionError`. `be_success`/`be_failure` RSpec matchers replace `spec/unit/` tests.
+- **`Container::Infrastructure` / `Container::Coordination`** (PR #234): single `LazyContainer` replaced by two `Data.define` records — Infrastructure owns manifest, file_store, geometry; Coordination owns gate, compositor, workflows, audit_log. Wired at boot via `wire_gate!`.
+- **`Geometry` as sole path authority** (PR #234): `root`, `schemas_dir`, `hooks_dir`, `store_db_path` delegated to `Geometry`. Removed `root` from Infrastructure. High-value `File.join` callers converted (data_mv, ingest, base, loader, etag, schema/tools, 6 doctor checks).
+- **`bin/db` helper**: sqlite3 wrapper for `.textus/.state/store.db` — `bin/db "SELECT * FROM jobs"` or just `bin/db` for interactive shell.
+- **Centralized SQLite index** (PR #228, #233): `Store::Index::Builder` manages entries FTS index in `store.db`.
+
+### Changed
+
+- **Gate reads `Action::VERBS` directly** (PR #234): `Gate::VERB_ACTIONS` deleted. Gate dispatches via `Action::VERBS[cmd.verb]`.
+- **Composite actions** (PR #232): `Accept`, `Propose`, `Reject` separated as composite verbs with declarative `chain` steps, never instantiating sibling action classes directly.
+- **`knowledge.decisions` → keyless nested mode**: decision files no longer enumerate in `list`; accessible via `get` with full key.
+
+### Fixed
+
+- **CLI `--args` JSON parsing** (PR #233): `Runner.coerce` now `JSON.parse(raw)` for `Hash`-typed args — fixes `textus enqueue --args='{"key":"..."}'` which previously passed the raw JSON string to `Queue::Job`.
+- **adr-log workflow convention drift** (PR #233): `Get.new(key:).call(...)` → `Get.call(key: k, ...)` — the old pattern raised silently since actions became class-method-only.
+- **RuboCop `Lint/NoReturnInBeginEndBlocks`**: enqueue action restructured with method-level `rescue`.
+
+### Removed
+
+- `Gate::VERB_ACTIONS` constant (replaced by `Action::VERBS`)
+- `LazyContainer` (replaced by `Container::Infrastructure`/`Coordination`)
+- `spec/unit/` directory + `spec/support/spec_layout.rb` (378 examples removed)
+- Orphaned `.textus/.state/jobs.sqlite3` database file
+
 ## 0.54.2 — 2026-06-18 — ingest dedup, .run → .state rename
 
 ### Added
@@ -867,7 +904,7 @@ Protocol remains `textus/3`.
   `refresh`, `refresh_stale`, `schema`, `rules`). Session state (cursor,
   role, manifest_etag) held server-side. Manifest drift surfaces as
   `ContractDrift` (-32001); cursor expiry as `CursorExpired` (-32002).
-  See [`docs/reference/mcp.md`](docs/reference/mcp.md) and [ADR 0015](docs/architecture/decisions/0015-agent-gate-mcp.md).
+  See [ADR 0015](docs/architecture/decisions/0015-agent-gate-mcp.md).
 - `examples/claude-plugin/.mcp.json` and migrated skills/commands/agents —
   zero `textus <verb>` shell strings remain in plugin markdown.
 

data/README.md

@@ -1,4 +1,5 @@
-<!-- Generated from .textus/data/knowledge/readme.md — edit there, then run `textus drain`. Do not hand-edit README.md (it is clobbered on drain and flagged by doctor). ADR 0103. -->
+<!-- Generated from knowledge.readme.* fragments by the artifacts.docs.readme workflow. Edit the fragments under .textus/data/knowledge/readme/ and run `textus drain`. -->
+<!-- This is a fragment of the README. Edit here; the README is composed from fragments by a workflow. -->
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="assets/branding/wordmark-dark.png">
@@ -18,6 +19,8 @@
 
 *textus* is Latin for "the fabric a text is woven from" — same root as *context*, from *con-texere*, "to weave together."
 
+
+<!-- This is a fragment of the README. Edit here; the README is composed from fragments by a workflow. -->
 ## The idea
 
 Three actors write to your repo today:
@@ -36,7 +39,7 @@ flowchart LR
     end
 
     human -->|author| knowledge["knowledge<br/>(canon)"]
-    agent -->|keep| notebook["notebook<br/>(workspace)"]
+    agent -->|keep| scratchpad["scratchpad<br/>(workspace)"]
     agent -->|propose| proposals["proposals<br/>(queue)"]
     automation -->|drain| artifacts["artifacts<br/>(machine)"]
     human -->|ingest| raw["raw<br/>(intake)"]
@@ -65,7 +68,7 @@ The point of those lanes is to **build context you can trust**. Place each lane
                        LOW TRUST                     HIGH TRUST
                       (unreviewed)                (authoritative)
               ┌──────────────────────────┬───────────────────────────────┐
-DURABLE       │  notebook                │  knowledge  ★ the goal        │
+DURABLE       │  scratchpad                │  knowledge  ★ the goal        │
 (kept)        │  agent's working truth   │  canon — a human authors      │
               │  durable, but low-trust  │  here · the context you ship  │
               ├──────────────────────────┼───────────────────────────────┤
@@ -81,15 +84,17 @@ Without coordination, they overwrite each other and nothing remembers why. textu
 
 ```
 knowledge/   author only            — who you are, what you decide, how you sound
-notebook/    keep only              — agent's own durable lane (bytes climb to knowledge only via propose→accept)
+scratchpad/    keep only              — agent's own durable lane (bytes climb to knowledge only via propose→accept)
 proposals/   propose (agent+human) — proposals waiting on a human accept
 artifacts/   converge only         — machine-maintained: computed outputs + external inputs
 ```
 
-An agent that tries to write directly into `knowledge/` gets `write_forbidden`. It writes to `proposals/` (to change authoritative content) or its own `notebook/` (for working memory). You accept the good proposals; textus promotes them, records the move, and audits both halves. Stable per-entry `uid:` means a reorganization doesn't break references. A monotonic audit cursor (`textus pulse --since=N`) means the next session — possibly a different agent, possibly a different model — picks up exactly where the last one left off.
+An agent that tries to write directly into `knowledge/` gets `write_forbidden`. It writes to `proposals/` (to change authoritative content) or its own `scratchpad/` (for working memory). You accept the good proposals; textus promotes them, records the move, and audits both halves. Stable per-entry `uid:` means a reorganization doesn't break references. A monotonic audit cursor (`textus pulse --since=N`) means the next session — possibly a different agent, possibly a different model — picks up exactly where the last one left off.
 
 That's the load-bearing claim: **coordination is a protocol invariant, not a library convenience.**
 
+
+<!-- This is a fragment of the README. Edit here; the README is composed from fragments by a workflow. -->
 ## See it in four commands
 
 ```sh
@@ -151,7 +156,7 @@ roles:
 
 lanes:
   - { name: knowledge, kind: canon }      # author   — canonical truth
-  - { name: notebook,  kind: workspace }  # keep     — agent's own durable lane
+  - { name: scratchpad,  kind: workspace }  # keep     — agent's own durable lane
   - { name: proposals, kind: queue }      # propose  — proposals awaiting accept
   - { name: artifacts, kind: machine }    # converge — computed outputs + external inputs
 ```
@@ -165,7 +170,7 @@ lanes:
   .gitignore             # generated — ignores .state/ and any tracked:false entries
   data/                  # one dir per lane; kinds + capabilities are in the manifest above
     knowledge/           # e.g. identity (knowledge.identity.*), voice, decisions, notes
-    notebook/
+    scratchpad/
     proposals/
     artifacts/           # machine lane: computed outputs + external inputs
   .state/                  # disposable runtime state — gitignored, safe to delete (ADR 0038)
@@ -202,7 +207,7 @@ For a worked store — knowledge entries, a staged proposal, schemas, ERB templa
 - **Agent loop.** `textus boot` orients a fresh session; `textus pulse --since=N` is the per-turn heartbeat (changed entries, pending proposals, index etag for catalog drift detection). ([docs/how-to/agents-mcp.md](docs/how-to/agents-mcp.md))
 - **MCP surface.** The official `mcp` Ruby SDK drives the stdio JSON-RPC server; protocol version auto-negotiated up to `2025-11-25`. Wire textus into Claude Code, Cursor, or any MCP host in one config block.
 - **`textus doctor`.** Health checks across schemas, workflow registrations, keys, sentinels, and the audit log.
-- **`raw` lane and `ingest` verb.** Write-once intake lane for external URL bookmarks, files, and binary assets. Three source kinds (`url`/`file`/`asset`); daily key derivation; notebook stub per ingest. See "Intake and ingest" section below.
+- **`raw` lane and `ingest` verb.** Write-once intake lane for external URL bookmarks, files, and binary assets. Three source kinds (`url`/`file`/`asset`); daily key derivation; scratchpad stub per ingest. See "Intake and ingest" section below.
 
 ## CLI and lanes
 
@@ -276,8 +281,8 @@ textus ingest url agentskills-io-brainstorming \
 # see what landed in the raw lane
 textus list --lane=raw
 
-# a notebook stub was created alongside — annotate it
-textus get notebook.notes.raw
+# a scratchpad stub was created alongside — annotate it
+textus get scratchpad.notes.raw
 ```
 
 Stale produced entries are re-materialised by `drain`, not by reads — `get` is a pure read (ADR 0089).
@@ -316,3 +321,5 @@ Lefthook hooks (`brew bundle install` then `lefthook install`) run rubocop on `p
 ## License
 
 [MIT](LICENSE)
+
+

data/SPEC.md

@@ -57,7 +57,7 @@ You **shape your own memory structure** inside `.textus/`. The protocol manages
 textus/4 names its concepts along six axes. Reviewers who internalize these can map any part of the spec to the right category:
 
 - **Actor** — who is interacting: roles such as `human`, `agent`, `automation`, each holding a set of capabilities (`propose`, `author`, `keep`, `converge`).
-- **Place** — where data lives: lanes such as `knowledge`, `notebook`, `raw`, `proposals`, `artifacts`.
+- **Place** — where data lives: lanes such as `knowledge`, `scratchpad`, `raw`, `proposals`, `artifacts`.
 - **Thing** — what is stored: entries, fields, keys.
 - **Operation** — how you act on things: RPC and CLI verbs (`get`, `put`, `drain`, `serve`, `ingest`, …).
 - **Event** — what gets fired after an operation: pub-sub events (`:entry_written`, `:entry_produced`, `:entry_published`, …).
@@ -111,7 +111,7 @@ The root is `.textus/` at the project working directory. A typical tree:
     sentinels/           # byte-copied publish bookkeeping (see §5.3)
   data/                  # ALL user content lives here
     knowledge/           # lane: knowledge (kind: canon — author-holders write)
-    notebook/            # lane: notebook (kind: workspace — keep-holders write; agent's own durable lane)
+    scratchpad/            # lane: scratchpad (kind: workspace — keep-holders write; agent's own durable lane)
     proposals/           # lane: proposals (kind: queue — propose-holders write)
     artifacts/           # lane: artifacts (kind: machine — converge-holders write)
     raw/                 # lane: raw (kind: raw — ingest-holders write; write-once)
@@ -149,7 +149,7 @@ roles:
 lanes:
   - name: knowledge
     kind: canon
-  - name: notebook
+  - name: scratchpad
     kind: workspace
     owner: agent              # optional, informational — agent's own lane
     desc: "agent's durable working memory; bytes climb to knowledge only via propose→accept"
@@ -241,7 +241,7 @@ Default scaffold — Setup-1 (roles `human=[author, propose, ingest]`, `agent=[p
 | Lane | `kind` | Required capability | Writable by (default) | Use case |
 |---|---|---|---|---|
 | `knowledge` | `canon` | `author` | `human` | Authored truth: identity, voice, decisions, network. |
-| `notebook` | `workspace` | `keep` | `agent` | Agent's own durable working memory. Bytes climb to `knowledge` only via propose→accept. |
+| `scratchpad` | `workspace` | `keep` | `agent` | Agent's own durable working memory. Bytes climb to `knowledge` only via propose→accept. |
 | `proposals` | `queue` | `propose` | `agent`, `human` | Proposals awaiting human review via `textus accept`. |
 | `artifacts` | `machine` | `converge` | `automation` | Computed outputs produced by `drain` via the workflow DSL. |
 | `raw` | `raw` | `ingest` | `human`, `agent`, `automation` | Write-once external source material: URL bookmarks, files, binary assets. |
@@ -284,7 +284,7 @@ Every successful write records the resolved role and a wall-clock timestamp in `
 
 #### 5.1.1 Capabilities
 
-Roles declare **capabilities** — verbs from a closed four-element set. A
+Roles declare **capabilities** — verbs from a closed five-element set. A
 manifest declares a `roles:` block mapping each role name to the capabilities
 it holds via `can:`:
 
@@ -296,7 +296,7 @@ roles:
   - { name: keeper,   can: [keep] }
 ```
 
-Capability allow-list: `propose`, `author`, `keep`, `converge`. The mapping from
+Capability allow-list: `propose`, `author`, `keep`, `converge`, `ingest`. The mapping from
 lane-kind to its required capability is a **bijection** (ADR 0091, which folded
 the former `quarantine` + `derived` kinds back into one `machine` kind — undoing
 the two-kind split of ADR 0090): each capability authorizes exactly one
@@ -308,8 +308,9 @@ lane-kind:
 | `keep` | `workspace` |
 | `propose` | `queue` |
 | `converge` | `machine` |
+| `ingest` | `raw` |
 
-A manifest naming a folded capability — `ingest` or `build`, or the pre-0088
+A manifest naming a folded capability — `build` or the pre-0088
 spelling `fetch` — in a `can:` list is rejected at load with a hint pointing to
 `converge` (ADR 0090, 0091, 0111).
 
@@ -425,7 +426,7 @@ The `raw` lane (`kind: raw`) is a write-once intake lane for external source mat
 
 **`access` field** — entries MAY carry `source.access: public | private` (field is `maintained_by: human`). Set `private` for sources not safe to reproduce publicly.
 
-**Notebook stub** — every ingest creates a `notebook.notes` stub with a backlink (`Ingested from raw.<key>`) so the agent or human can annotate the ingested material without touching the write-once record.
+**Notebook stub** — every ingest creates a `scratchpad.notes` stub with a backlink (`Ingested from raw.<key>`) so the agent or human can annotate the ingested material without touching the write-once record.
 
 **Example — URL bookmark:**
 
@@ -438,6 +439,22 @@ textus ingest url agentskills-io-brainstorming \
 
 A `get` on a raw entry is a pure read — it returns the entry as stored and never re-fetches (ADR 0089).
 
+**Raw entry shape.** Every raw-lane entry has a set of required fields
+enforced by the format layer on write:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `ingested_at` | yes | ISO-8601 timestamp of ingestion |
+| `content_hash` | yes | `sha256:<hex>` of the source content |
+| `source.kind` | yes | One of `url`, `file`, `asset` |
+| `source.url` | conditional | Required when `kind=url` |
+| `source.label` | no | Human-readable label |
+| `body` | no | Present only for `kind=file` |
+| `asset` | no | Present only for `kind=asset` |
+
+Tombstone entries (carrying `superseded_by:`) are exempt from shape
+validation — they are stripped-down records pointing to the live entry.
+
 ### 5.5 Pending / accept workflow
 
 Proposal entries are full patches authored into the `proposals` queue lane (writable by `propose`-holders: `agent` and `human` by default) — `proposals` in the default scaffold (Setup-1) — typically by agents. The entry's frontmatter describes the patch it proposes against another lane:
@@ -646,6 +663,13 @@ The frontmatter `name:` field, when present, must match the file's basename (wit
 - Existing files without a uid continue to work. The envelope shows `"uid": null` until a put mints one.
 - `text` entries have no metadata channel and therefore no uid; their envelope always shows `"uid": null`.
 
+**`sources:` (Source references).** Entries MAY carry a `sources` array in
+their frontmatter to declare external provenance. Each element is a raw-lane
+key string (starting with `raw.`). The array is preserved on write —
+existing sources carry forward if no new `sources` are provided. The
+envelope returns `sources` as a top-level array when non-empty; omitted
+when absent.
+
 Entries in a `produced` lane SHOULD additionally carry the `generated:` block defined in §5.2. Implementations MUST treat unknown frontmatter fields as warnings, not errors, so build tooling can extend the metadata without breaking conformance.
 
 ## 8. Envelope (the wire format)
@@ -665,6 +689,9 @@ Every successful CLI response (`--output=json`) is a single JSON envelope:
   "etag": "sha256:8f3c…",
   "schema_ref": "person",
   "uid": "a1b2c3d4e5f60718",
+  "sources": [
+    { "key": "raw.2026.06.20.url-mcp-spec", "etag": "sha256:1a2b…", "suspended": false }
+  ],
   "stale": false,
   "stale_reason": null,
   "fetching": false
@@ -674,7 +701,7 @@ Every successful CLI response (`--output=json`) is a single JSON envelope:
 **Field rules:**
 - `protocol` MUST be the exact string `textus/4`.
 - `key` MUST be the canonical resolved key.
-- `lane` MUST be one of the lanes declared in the manifest (`knowledge`, `notebook`, `feeds`, `proposals`, `artifacts` in the default Setup-1 scaffold).
+- `lane` MUST be one of the lanes declared in the manifest (`knowledge`, `scratchpad`, `proposals`, `artifacts`, `raw` in the default Setup-1 scaffold).
 - `path` MUST be an absolute filesystem path.
 - `format` MUST be one of `markdown`, `json`, `yaml`, `text` (§5.12). Absent envelopes are treated as `markdown` for back-compat.
 - `body` is the raw on-disk bytes as a UTF-8 string for every format.
@@ -682,6 +709,7 @@ Every successful CLI response (`--output=json`) is a single JSON envelope:
 - `etag` MUST be `sha256:<hex>` of the raw file bytes, computed identically for every format.
 - `schema_ref` MAY be `null` for entries in subtrees with `schema: null`.
 - `uid` is the stable Textus UID (§7) if the entry carries one, else `null`. Always present in the envelope.
+- `sources` is an array of source objects. Each object has `key` (the referenced entry's key), `etag` (sha256 snapshot taken at write time, or absent when no snapshot exists), and `suspended` (`true` when the referenced entry's current on-disk etag differs from the stored snapshot — the source changed after this entry was last written). Present only when non-empty.
 - `stale` is `true` when the entry's `source.ttl` has elapsed and the entry has not yet been re-materialised; `false` otherwise. Only populated for produced entries with a declared `ttl`; always `false` for other entries.
 - `stale_reason` is a short human-readable string describing why the entry is stale (e.g. `"ttl_exceeded"`, `"never_fetched"`), or `null` when `stale` is `false`.
 - `fetching` is `true` when a background re-pull is in flight for this entry; `false` otherwise. Callers observing `stale: true, fetching: true` SHOULD retry after a short delay.
@@ -764,7 +792,7 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 
 `read_verbs` is derived from the MCP verb catalog — the verbs the agent can actually call over its transport — so it lists the read/discovery verbs (`schema_show` for an entry's field shape, `rule_explain` for its retention/guard policy, and the graph reads `where`/`deps`/`rdeps`, ADR 0060) and never the CLI-only `audit`/`doctor`, nor `freshness` (the Ruby-only internal lifecycle scan, ADR 0085) (ADR 0056). An agent learns an entry's `_meta` shape by calling the `schema_show` verb before a `put`/`propose`, not by shelling out to a CLI. The graph reads `deps`/`rdeps` return a structured `{key, deps}`/`{key, rdeps}` envelope on every surface (CLI, Ruby, MCP) — a hash, not a bare array, consistent with the other structured read responses such as `where` (ADR 0060 amendment).
 
-The agent's MCP write surface includes the single-key `key_delete` and `key_mv` tools alongside their bulk `key_delete_prefix`/`key_mv_prefix` cousins (ADR 0060 amendment; the single-key tools were renamed from `delete`/`mv` to share the `key_` family stem in ADR 0082, which also removed the `migrate` YAML-plan orchestrator — its `zone_mv`/`key_mv_prefix`/`key_delete_prefix` ops remain individually callable). All of these apply by default; `dry_run: true` is a uniform opt-in preview that returns a Plan without mutating (ADR 0071 — verbs are actions, dry-run is opt-in on every surface). Single-key `key_delete` additionally accepts an optional `if_etag` optimistic-concurrency check. The blast-radius reads (`where`/`deps`/`rdeps`) remain on MCP so an agent can look before it leaps. The promotion verbs `accept` and `reject` are also on MCP (ADR 0072): they are gated by the `author_held` capability floor, not by transport absence — a default-`agent` connection is refused, while a connection launched as a role holding `author` (`--as`/`TEXTUS_ROLE`/`.textus/role`, resolved once at launch per ADR 0040) can promote, closing the propose→accept loop over one transport. `drain` is also on MCP (ADR 0076, ADR 0087, ADR 0110): it is caller-agnostic and its produce jobs self-elevate — materialization always runs as the manifest's `converge`-capable actor regardless of the calling role, granting no authority over content (materialization is a pure, idempotent function of already-accepted canon, ADR 0070); the destructive retention sweep runs as the caller. Each produce job self-acquires the single-writer build lock, so a concurrent CLI, reactive, or background pass cannot collide with an MCP-triggered one — a held lock is a graceful soft-miss (ADR 0110).
+The agent's MCP write surface includes the single-key `key_delete` and `key_mv` tools alongside their bulk `key_delete_prefix`/`key_mv_prefix` cousins (ADR 0060 amendment; the single-key tools were renamed from `delete`/`mv` to share the `key_` family stem in ADR 0082, which also removed the `migrate` YAML-plan orchestrator — its `data_mv`/`key_mv_prefix`/`key_delete_prefix` ops remain individually callable). The structural mutation verbs (`key_mv`, `key_mv_prefix`, `key_delete_prefix`, `data_mv`) accept `dry_run: true` as an opt-in preview that returns a Plan without mutating (ADR 0071). `drain` does not support `dry_run` (it is async-only, ADR 0110). Single-key `key_delete` additionally accepts an optional `if_etag` optimistic-concurrency check. The blast-radius reads (`where`/`deps`/`rdeps`) remain on MCP so an agent can look before it leaps. The promotion verbs `accept` and `reject` are also on MCP (ADR 0072): they are gated by the `author_held` capability floor, not by transport absence — a default-`agent` connection is refused, while a connection launched as a role holding `author` (`--as`/`TEXTUS_ROLE`/`.textus/role`, resolved once at launch per ADR 0040) can promote, closing the propose→accept loop over one transport. `drain` is also on MCP (ADR 0076, ADR 0087, ADR 0110): it is caller-agnostic and its produce jobs self-elevate — materialization always runs as the manifest's `converge`-capable actor regardless of the calling role, granting no authority over content (materialization is a pure, idempotent function of already-accepted canon, ADR 0070); the destructive retention sweep runs as the caller. Each produce job self-acquires the single-writer build lock, so a concurrent CLI, reactive, or background pass cannot collide with an MCP-triggered one — a held lock is a graceful soft-miss (ADR 0110).
 
 `latest_seq` is the current high-water mark of the audit log; agents should use it as the starting cursor for `pulse`.
 
@@ -792,7 +820,7 @@ The agent's MCP write surface includes the single-key `key_delete` and `key_mv`
 
 `if_etag` is optional on both `put` and `key_delete`. When provided, the write fails with `etag_mismatch` if the on-disk file's etag differs. When omitted, the write is unconditional (last-writer-wins).
 
-The lifecycle scan behind `pulse.stale`/`pulse.next_due_at` reports, per entry, one verdict (`fresh`, `expired`, or `no_policy`) against each intake entry's `source.ttl`. ADR 0085 removed the standalone `freshness` verb that used to render these rows; the scan is now Ruby-only (consumed by `pulse` and the hook context), and human drill-down into a single entry's verdict is `textus get KEY` (carries `stale`/`stale_reason`) plus `textus rule_explain KEY` (the `source.ttl` and retention policy). `textus drain` enqueues the convergence jobs — produce every in-scope derived entry, re-pull every stale intake entry, and a retention sweep — then drains the queue to empty (§5.11). Convergence is async-only (ADR 0110): there is no `--dry-run`.
+The lifecycle scan runs per-entry at `get` time — each `get` response carries `stale`/`stale_reason` when the entry has a TTL rule. ADR 0085 removed the standalone `freshness` verb; human drill-down into a single entry's verdict is `textus get KEY` (carries `stale`/`stale_reason`) plus `textus rule_explain KEY` (the `source.ttl` and retention policy). `pulse` does not include a `stale` list. `textus drain` enqueues the convergence jobs — produce every in-scope derived entry, re-pull every stale intake entry, and a retention sweep — then drains the queue to empty (§5.11). Convergence is async-only (ADR 0110): there is no `--dry-run`.
 
 `textus accept K --as=human` promotes a pending entry into its target lane: it copies the patch body into the target key, deletes the pending entry, and writes one audit line per side (§audit). Only a role holding the `author` capability (the trust anchor — `human` by default) may invoke `accept`.
 

data/docs/architecture/README.md

@@ -6,7 +6,8 @@
 ```mermaid
 flowchart TD
     surfaces["Surfaces — CLI · MCP · RoleScope"]
-    contract["Contract — per-verb DSL (source of truth for public interfaces)"]
+    contract["Contract — per-verb DSL (Arg, Spec, DSL)"]
+    dispatch["Dispatch — Binder · Around · CommandBuilder · Dispatcher"]
     gate["Gate — routing (VERB_COMMAND) · Auth"]
     action["Actions — per-verb use cases (action/)"]
     jobs["Jobs — Worker · Planner · Materialize · Retention · Sweep"]
@@ -15,8 +16,10 @@ flowchart TD
     manifest["Manifest — declarative config, no IO (policy/, schema/, entry/)"]
     core["Core — pure value types (Freshness, Retention, Duration, Sentinel)"]
     ports["Ports — IO adapters (FileStore, AuditLog, JobStore, Publisher…)"]
-    surfaces --> contract
-    contract --> gate
+    surfaces --> dispatch
+    surfaces -.->|declare| contract
+    contract --> dispatch
+    dispatch --> gate
     gate --> action
     action --> jobs
     action --> produce
@@ -27,7 +30,7 @@ flowchart TD
     jobs --> produce
 ```
 
-*Dependency rule: inward only.* Surfaces → Contract → Gate → Actions → inner layers. Actions never reference surfaces.
+*Dependency rule: inward only.* Surfaces → Dispatch → Gate → Actions → inner layers. Actions never reference surfaces.
 
 ### What lives in each layer
 
@@ -35,18 +38,27 @@ flowchart TD
 
 ```
 surfaces/cli/     CLI command generation from contracts
+  sources.rb      CLI-only input acquisition (stdin parsing, file sourcing, coercion)
 surfaces/mcp/     MCP server — stdio JSON-RPC 2.0, tools derived from contracts
 surfaces/role_scope.rb
-                  (Store#as(role)) — holds (container, role, dry_run, correlation_id);
+                  (Store#with_role(role)) — holds (container, role, dry_run, correlation_id);
                   all verb methods injected via define_method in textus.rb
 ```
 
-**Contract**
+**Contract + Dispatch**
 
 ```
-contract/         Per-verb DSL — verb, summary, surfaces, arg, view.
-                  Contract::Binder.inputs_from_ordered splits the uniform inputs hash
-                  into positional/keyword args for every surface.
+contract/         Per-verb DSL — verb, summary, surfaces, arg, view, around.
+                  Pure declaration: Spec and DSL only.
+
+dispatch/         Runtime machinery consumed by every surface.
+  binder.rb       Binder — validates required args, resolves session/literal defaults.
+  around.rb       Around — registry of stateful wrappers (cursor, build_lock).
+  view.rb         View.render(spec, surface, result, inputs) — output shaping.
+  command_builder.rb
+                  CommandBuilder — command construction + role injection.
+  dispatcher.rb   Dispatcher — unified pipeline: Around → Binder → Command → Gate.
+  resources/      Around resource implementations (Cursor, BuildLock).
 ```
 
 **Gate + Auth**
@@ -202,7 +214,7 @@ Both are built from a `Container` via named constructors — `Writer.from(contai
 
 `Action::Get` is a **pure read** — it resolves the path, reads bytes, parses the envelope, and annotates a freshness verdict. It never ingests and never mutates.
 
-1. CLI/MCP surface calls `store.as(role).get(key)`.
+1. CLI/MCP surface calls `store.with_role(role).get(key)`.
 2. `Gate#dispatch` runs Auth → `Action::Get#call`.
 3. `Get` resolves path via `manifest.resolver`, reads bytes via `file_store`, parses the envelope, annotates `freshness` based on retention-rule TTL (if any).
 
@@ -210,7 +222,7 @@ Staleness is age-based (retention-rule TTL vs file mtime). A stale entry is retu
 
 ## Write path (`store.put(key, ...)`)
 
-1. CLI/MCP surface calls `store.as(role).put(key, meta:, body:)`.
+1. CLI/MCP surface calls `store.with_role(role).put(key, meta:, body:)`.
 2. `Gate#dispatch` runs Auth → `Action::Put#call`.
 3. `Put` validates, resolves manifest entry, delegates to `Envelope::Writer#put` (serialize → schema-validate → etag-check → FileStore#write → AuditLog#append).
 4. `WriteVerb#cascade_to_rdeps` enqueues `materialize` jobs for any entries with publish_tree that depend on the written key.

data/docs/reference/conventions.md

@@ -24,7 +24,7 @@ Recommended top-level layout — the spec allows alternatives, but this is what
   templates/      # ERB templates for publish rendering
   data/
     knowledge/    # authored truth: identity, voice, decisions — author-holders write
-    notebook/     # agent's own durable lane (workspace) — keep-holders write
+    scratchpad/     # agent's own durable lane (workspace) — keep-holders write
     proposals/    # AI proposals awaiting accept (propose)
     artifacts/    # computed outputs produced by drain — never edit by hand
     raw/          # write-once external source material (ingest)
@@ -126,7 +126,10 @@ For multi-writer environments, **always pass `if_etag`** on `put`. The gem treat
 The application layer is organised around three shapes — `Manifest` as a composition record, a single `Container` capability record handed to every use case, and a split envelope reader/writer. See [ADR 0018](../architecture/decisions/0018-manifest-carving.md), [ADR 0017](../architecture/decisions/0017-envelope-io-split.md), [ADR 0022](../architecture/decisions/0022-container-call-dispatcher.md), and [ADR 0023](../architecture/decisions/0023-uniform-use-case-shape.md).
 
 - **`Manifest` is a composition record** (`Data.define(:data, :resolver, :policy, :rules)`). Reach individual concerns through the field accessors: `manifest.data.entries`, `manifest.policy.permission_for(lane)`, `manifest.resolver.resolve(key)`, `manifest.rules.for(key)`.
-- **Use cases are plain `(container:, call:)` classes.** Each is a single class under `lib/textus/{read,write,maintenance}/` with `def initialize(container:, call:)` and a `#call(...)` method; verbs are looked up in the static `Textus::Dispatcher::VERBS` table. `Container` is a `Data.define` record bundling the wired ports + manifest (`manifest`, `file_store`, `schemas`, `root`, `audit_log`, `events`, `rpc`); `Call` is the immutable per-invocation value (`role`, `correlation_id`, `now`, `dry_run`). A use case that emits events derives its `Hooks::Context` from `(container, call)` — nothing is injected. Use cases pull only what they need into ivars; nobody passes the raw `Store` around the application layer. `store.as(role)` returns a `RoleScope` that forwards verbs to the dispatcher.
+- **`Store` is the single dispatch module.** `Store` holds the `Container`, the active role, session state (cursor, propose_lane, contract_etag), and dispatches verbs through `method_missing`. Each verb call (`store.get(key: ...)`, `store.put(key:, meta:, body:)`) goes through `VerbRegistry`, binds inputs via `Dispatch::Binder`, routes through `Dispatch::Pipeline` (middleware chain: auth, cascade, audit), and reaches the handler. `Store#with_role(role)` returns a new `Store` bound to that role.
+- **`Container` is a `Data.define` composition** of `Infrastructure` (`file_store`, `schemas`, `audit_log`, `job_store`, `geometry`) and `Coordination` (`manifest`, `workflows`, `pipeline`). Built in a single pass — no circular dependencies or lazy proxies.
+- **Dispatch lives in `lib/textus/dispatch/`**: `Dispatch.dispatch` orchestrates verb dispatch, `Dispatch::Pipeline` runs middleware then invokes the handler, `Dispatch::Binder` handles input binding (wire format, CLI flags, session defaults). Auth predicates moved to `Manifest::Policy::Predicates`.
+- **Handlers receive `container:`** and access I/O via `@container.pipeline.read/write/delete/move` and manifest config via `@container.manifest`.
 - **Write path is split**: `Envelope::IO::Reader` owns read/parse (existing-uid lookup, raw read, parse), and `Envelope::IO::Writer` owns put/delete/move + the audit-append invariant (every public method's final action is `@audit_log.append(...)`).
 
 The user-facing CLI surface, the wire envelope shape, and the protocol version (`textus/4`) are unchanged.

data/exe/textus

@@ -1,4 +1,4 @@
 #!/usr/bin/env ruby
 $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 require "textus"
-exit Textus::Surfaces::CLI.run(ARGV)
+exit Textus::Surface::CLI.run(ARGV)