textus 0.43.1 → 0.45.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c26661afb6c59f813ccdb737e56666be242a14e3315a100348dd8514a41e78a
-  data.tar.gz: 26ff3e7e8cd94a545cdcabe964c6e8c7311fe0179a24a13b0ab298eab7f2bf34
+  metadata.gz: dfb215839c07335a72f604bbcb830d6027a118f500be30243a592cc9c5b07cf0
+  data.tar.gz: dd0103470acbdfb747077bc6d0fafbc08700edfe5a24d09416723d47517871df
 SHA512:
-  metadata.gz: db6b8047ba7d7c79ad78a653944709d7cc7cfd5c22a4baae116e97c8d6fea48c409788c835e1c1f83c7684a58da089b08a0525a44791de92875d1d2bb0c26a76
-  data.tar.gz: 26e9d74398110f4d34dd59c837901170e5d80a847268f5edee45010f4793c51e1f47737d5d3c85b0098fa06b1334e00bf1038330a12a1061c9957d045e07638c
+  metadata.gz: 310065adbf501efcd2b793b896770a9cc7e5a38e41c23852c12b18dfca5cc93cea7af1545bac5e306a667aeac959995c9cf08468a3d86869facec42d11c1501f
+  data.tar.gz: 938e0ed014c543d2cba7190ab6de0440a36670268b4207af19444934fb28560cda382452c0cb1db26e4c31bfe78b89031c52fbdb0196fc7d67eb360013d58d5f

data/CHANGELOG.md

@@ -9,6 +9,76 @@ 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.45.1 — 2026-06-03 — Single-path lifecycle: kill the last dual-paths ([ADR 0069](docs/architecture/decisions/0069-single-path-lifecycle.md))
+
+No `textus/3` wire-format change. Finishes the 0.45.0 lifecycle (ADRs 0066–0068): the request path was single-path in shape but still carried four residual dual-paths. This removes all four so the lifecycle — `normalize → bind (always validate) → dispatch (+around) → view (self-shaping)` — is single-path in fact on every surface. Three breaking (pre-1.0) changes, all accepted.
+
+### Changed
+
+- **Views self-shape on every surface.** The CLI runner's `result.to_h_for_wire` pre-wire is deleted, so every `view` receives the raw use-case result on every surface (the pattern `get`/`zone_mv`/`migrate` already used). `propose` collapses its two views into one `view { |env, _i| env.to_h_for_wire }`.
+- **One normalizer home.** MCP's inline by-wire-name normalizer is lifted into `Contract::Binder.inputs_from_wire`, beside `inputs_from_ordered`; the binder now owns both. `MCP::Catalog#call` calls it.
+- **Validation is unconditional; `required:` is an honest invariant.** The `validate:` keyword is dropped from `Binder.bind`, `RoleScope#dispatch_bound`, and `Maintenance::Migrate`. Bind always validates — no opt-out, so the `validate: false`-by-default footgun cannot exist. `required:` now means "required on every surface," not an agent-wire policy (retiring the [ADR 0066](docs/architecture/decisions/0066-one-binder-required-is-a-surface-policy.md) `validate:` fork).
+- **The hand-authored CLI taxonomy is named and guarded.** `HAND_AUTHORED_VERBS` splits into `BEHAVIORAL_HATCHES` (`get`, `put`, `build` — genuine `< Runner::Base` overrides) and `NON_PROJECTED_CLI` (`fetch`, `fetch_all`, `boot`, `doctor` — plain `< Verb` commands), with the union derived. A new guard spec asserts each member's CLI class matches its category.
+
+### Breaking (pre-1.0)
+
+- **`Binder.bind` / `RoleScope#dispatch_bound` drop the `validate:` keyword.** Callers passing it must remove it; validation is always on.
+- **`put`/`propose` `meta` is now `required: false`.** A missing `_meta` no longer returns a pre-dispatch `missing _meta` error — it binds with `meta` absent and flows to schema validation downstream (where an *invalid* `_meta` fails, and an absent-but-schema-permitted `_meta` succeeds). `meta`'s real requiredness lives in schema validation.
+- **MCP/Ruby `propose` returns the full wire envelope.** The single self-shaping view emits `env.to_h_for_wire` on every surface — a superset of the old `{uid, etag, key}`.
+
+## 0.45.0 — 2026-06-03 — The contract owns the request lifecycle ([ADRs 0066–0068](docs/architecture/decisions/))
+
+No `textus/3` wire-format change. The `Contract` now owns the entire request lifecycle — `acquire → bind → invoke → render` — so the three surfaces (MCP, CLI, Ruby) project from it with no re-implemented argument-mapping, no dual response/cli_response shaping, and no behavioral escape-hatch classes that exist only because the contract couldn't express I/O acquisition, a stateful wrapper, or a coercion. The escape-hatch population shrinks from 18 to the irreducible behavioral floor of 7. Several breaking (pre-1.0) DSL and signature changes; one operator-visible CLI change (`key delete-prefix` / `key mv-prefix`).
+
+### Changed
+
+- **One argument binder; `required:` is a surface policy ([ADR 0066](docs/architecture/decisions/0066-one-binder-required-is-a-surface-policy.md)).** `MCP::Catalog.map_args`, `CLI::Runner.call_args`, and `RoleScope`'s default-injection loop collapse into one `Contract::Binder.bind` over a uniform by-name `inputs` hash. Every surface dispatches through one site, `RoleScope#dispatch_bound`, so bind fires exactly once. The agent surfaces validate required args (`validate: true`); the Ruby API binds leniently and trusts the use-case's own keyword defaults — `required:` is an agent-wire policy, not a contract invariant.
+- **BREAKING (pre-1.0): per-surface `view`s replace `response`/`cli_response` ([ADR 0067](docs/architecture/decisions/0067-per-surface-views.md)).** One `views` map keyed by surface: `view { … }` (MCP/Ruby) and `view(:cli) { … }`. Every view is called uniformly as `(result, inputs)`, retiring the `Proc#arity == 2` sniff. `Contract::View.render` is the single shaping entry point.
+- **Declarative facets dissolve the acquisition & wrapper hatches ([ADR 0068](docs/architecture/decisions/0068-declarative-facets-dissolve-escape-hatches.md)).** `arg … source: :file` (read a path → contents), `arg … coerce: callable`, `cli_stdin :json` (stdin envelope), `around :name` (stateful wrappers via `Contract::Around`), and `arg … cli_default:` (a CLI default diverging from the agent default, driving both the value and boolean flag polarity). `propose`, `migrate`, `rule_lint`, `audit`, `zone_mv`, `pulse`, `key_delete`, and `mv` lose their hand-authored CLI classes and generate. `HAND_AUTHORED_VERBS` shrinks 18 → 7 (`get`, `put`, `build`, `fetch`, `fetch_all`, `boot`, `doctor`) — the behavioral floor. `zone_mv`/`migrate`/`key_*_prefix` apply by default on the CLI and plan by default for agents (ADR 0060), now legible in the contract rather than hidden in a hand class.
+- **BREAKING (pre-1.0): `key delete --prefix P` → `key delete-prefix P`; `key mv --prefix F T` → `key mv-prefix F T`.** The two `--prefix` overloads split into first-class generated commands, each dispatching the verb its own contract names.
+- **BREAKING (pre-1.0): positional `#call` signatures.** `zone_mv` (`from`/`to`), `migrate` (`plan_yaml`), `key_mv_prefix` (`from_prefix`/`to_prefix`), and `key_delete_prefix` (`prefix`) take their declared-positional args positionally, matching the CLI and the binder.
+
+### Fixed
+
+- **`Runner.coerce` now coerces `Integer`-typed flags.** A `case … when Integer` used `===` (instance-of), so `Integer`-typed flags (`audit --limit`/`--seq-since`) silently stayed strings; now compared by equality.
+- **The CLI reconciliation guards are seed-independent.** `CLI.verbs` and the contract-reconciliation check ignore anonymous (`name.nil?`) test-fixture `Verb` subclasses that previously leaked into the registry under some RSpec seeds.
+
+## 0.44.1 — 2026-06-03 — Finish the CLI contract projection ([ADR 0065](docs/architecture/decisions/0065-finish-cli-response-shrink-escape-hatches.md))
+
+No `textus/3` wire-format change. The `cli_response` facet can now receive the call's resolved inputs, so the two output-only escape hatches become generated verbs. No operator-visible change to CLI commands, flags, or output.
+
+### Changed
+
+- **`cli_response` may see the call inputs; `uid` and `blame` are now generated ([ADR 0065](docs/architecture/decisions/0065-finish-cli-response-shrink-escape-hatches.md)).** An arity-2 `cli_response` lambda receives `(result, inputs)` (inputs keyed by arg name), letting an envelope echo an input such as the key. `Read::Uid` and `Read::Blame` declare their CLI envelopes in their contracts and drop their hand-authored `Runner::Base` subclasses — the escape-hatch population shrinks from 13 to 11. `zone_mv` (CLI applies by default, agents plan by default — ADR 0060) and `audit` (a one-off `since` coercion) deliberately stay hand-authored.
+- **BREAKING (pre-1.0): `Read::Blame#call` takes the key positionally.** `store.as(role).blame(key:)` becomes `store.as(role).blame(key)` to match the CLI's positional `blame KEY` and the generated arg-mapping. The CLI command and the MCP surface (blame is not MCP-surfaced) are unchanged.
+
+## 0.44.0 — 2026-06-03 — One verb name across surfaces; the CLI is a contract projection ([ADRs 0058–0064](docs/architecture/decisions/))
+
+No `textus/3` wire-format change. This release makes a verb's *name* singular across the MCP tool, the CLI command, and the use-case method; widens and hardens the agent surface; unifies `get` on read-through; and makes the CLI a derived projection of the per-verb contract so a command can no longer dispatch a differently-named verb. Several breaking (pre-1.0) renames on the MCP/CLI surfaces; no operator-visible change to CLI commands, flags, or output.
+
+### Changed
+
+- **BREAKING (pre-1.0): one verb name across surfaces ([ADR 0058](docs/architecture/decisions/0058-one-verb-name-across-surfaces.md)).** MCP `schema`→`schema_show`; CLI `fetch stale`→`fetch all` (the label now matches what it does); `retention_sweep`→`retain`; the redundant top-level `delete` folds into `key delete` (which gains `--if-etag`).
+- **One rule verb, two depths ([ADR 0059](docs/architecture/decisions/0059-one-rule-verb-two-depths.md)).** MCP `rules` and CLI `rule explain` merge into `rule_explain` — lean `{fetch, guard}` by default, the full matched-blocks explanation under `--detail`/`detail: true`. `rule list` gains a use-case (`Read::RuleList`). Fixes a latent `to_h` crash on any key with a fetch rule.
+- **Agent safety: eyes + safe defaults ([ADR 0060](docs/architecture/decisions/0060-agent-safety-graph-reads-and-default-dry-run.md)).** `deps`/`rdeps`/`where` are surfaced to MCP (the catalog grows 15→20 tools, including single-key `delete`/`mv`); the four bulk-destructive verbs (`zone_mv`, `key_mv_prefix`, `key_delete_prefix`, `migrate`) now default `dry_run: true` — an agent that omits the flag gets a Plan, not a mutation. `deps`/`rdeps` return a structured `{key, deps}`/`{key, rdeps}` on every surface.
+- **BREAKING (pre-1.0): `build` is the verb, `publish` is the output-destination noun ([ADR 0061](docs/architecture/decisions/0061-build-publish-vocabulary.md)).** `Write::Publish`→`Write::Build`; the dispatcher verb, `RoleScope#build`, the capability, the `derived` zone-kind's required verb, the lock, and the error all read `build`. `publish` is kept only for the ADR-0052 output-destination concept (the `publish:` block, `publish_to`/`publish_tree`, `Ports::Publisher`). Ruby callers using `store.as(role).publish` must call `.build`; the MCP surface is unaffected (the verb was never surfaced).
+- **BREAKING (pre-1.0): one `get`, read-through everywhere ([ADR 0062](docs/architecture/decisions/0062-one-get-read-through.md)).** The public `get` is read-through on every surface (fetch-on-stale per the entry's rule, degrading to a pure read when there is no fetch rule), via a single `Read::Get#call(key, fetch:)` class; the CLI's secret `get_or_fetch` upgrade and the verb itself are removed. `get --no-fetch` (MCP `{fetch: false}`) forces a pure on-disk read. The agent's `get` now returns the freshest obtainable envelope (superseding ADR 0060's pure-read stance for `get`).
+- **The CLI is a projection of the contract ([ADR 0063](docs/architecture/decisions/0063-cli-is-a-projection-of-the-contract.md)).** A generic `CLI::Runner` (the operator mirror of `MCP::Catalog`) generates each command from its contract via two new facets — `cli` (the command path) and `cli_response` (a CLI-specific return shape, where the operator envelope differs from the agent return). Twelve verbs are now generated with no hand-class; behavioral verbs subclass `Runner::Base` and override `#invoke` only, so the verb *name* is always contract-derived. A total reconciliation spec makes name/dispatch drift — the bug behind the 0058/0059/0061 renames — unrepresentable. No operator-visible change: the set of CLI commands, flags, and output is identical.
+- **Derive the CLI command name; guard the dispatcher key ([ADR 0064](docs/architecture/decisions/0064-derive-command-name-and-guard-dispatcher-key.md)).** Tightens ADR 0063's projection: `CLI::Runner::Base` now derives `command_name` from the contract's `cli_leaf`, so the 13 escape-hatch classes drop their literal `command_name "…"` (the verb name is authored once, in the use-case). A new guard asserts every `Dispatcher::VERBS` key equals its use-case's own `contract.verb` — the last identity link no spec checked. No operator-visible change; the set of CLI commands, flags, and output is identical.
+
+## 0.43.2 — 2026-06-02 — Agent-legible MCP contracts ([ADR 0057](docs/architecture/decisions/0057-agent-legible-mcp-contracts.md))
+
+No `textus/3` wire-format change. One breaking (pre-1.0) change on the MCP transport — `put`/`propose` take frontmatter under `_meta` (was `meta`) — plus per-argument descriptions on every MCP tool and a fully catalog-derived agent verb surface.
+
+### Changed
+
+- **BREAKING (pre-1.0): MCP `put`/`propose` take frontmatter under `_meta`, not `meta` ([ADR 0057](docs/architecture/decisions/0057-agent-legible-mcp-contracts.md)).** Every *read* returns the envelope under `_meta` (`get`, SPEC §8), and the CLI `--stdin` envelope already speaks `_meta` — only the MCP `put`/`propose` argument diverged as `meta`, breaking the natural read → edit → write round-trip. The contract gains a `wire_name` primitive so the wire speaks `_meta` while the use-case keeps its `meta:` kwarg (the ADR 0039 signature guard still reconciles). An MCP client that hardcoded the `meta` argument renames one key. The Ruby API (`store.put(meta:)`) and the CLI `--stdin` envelope are unchanged.
+- **`boot.agent_quickstart.write_verbs` derives from the MCP catalog ([ADR 0057](docs/architecture/decisions/0057-agent-legible-mcp-contracts.md)).** It now returns bare verb names (`put propose fetch fetch_all`) like `read_verbs`, instead of the CLI string `"put KEY --as=agent --stdin"` (`--as`/`--stdin` are meaningless on an MCP connection — role is connection-resolved, ADR 0040). Closes the de-CLI follow-up named in ADR 0056; a symmetric guard spec fails the build if a CLI string creeps back.
+
+### Added
+
+- **Per-argument descriptions on every MCP tool ([ADR 0057](docs/architecture/decisions/0057-agent-legible-mcp-contracts.md)).** All MCP-surfaced verb arguments now carry a one-line `description:` in their `tools/list` `inputSchema` (was 2 of ~30) — including `put`'s `body`/`content` mutual-exclusivity and the maintenance `dry_run` "default false applies immediately" gotcha. They ship once in `tools/list` at no per-call cost, so an agent can form a valid call from the schema alone.
+
 ## 0.43.1 — 2026-06-02 — `boot` agent surface derives from the MCP catalog ([ADR 0056](docs/architecture/decisions/0056-boot-quickstart-speaks-the-mcp-catalog.md))
 
 No `textus/3` wire-format change — `boot`'s agent-orientation fields are corrected to match the verbs an MCP agent can actually call.

data/README.md

@@ -239,9 +239,9 @@ end
 To keep a batch of stale intake entries current in one shot:
 
 ```sh
-textus fetch stale --prefix=feeds --zone=feeds --as=automation
-# or just fetch everything stale in the feeds zone:
-textus fetch stale --zone=feeds --as=automation
+textus fetch all --prefix=feeds --zone=feeds --as=automation
+# or just fetch everything past its TTL in the feeds zone:
+textus fetch all --zone=feeds --as=automation
 ```
 
 See SPEC.md §5.10 for the full hook contract.

data/SPEC.md

@@ -456,7 +456,7 @@ A sentinel is written for each published file at `<store_root>/sentinels/<target
 
 ### 5.4 Intake (declared, fetched via registered intake handler)
 
-Intake entries declare an external source by naming an **intake handler** — a registered, named function that pulls data into the entry. textus itself still makes no implicit network calls: an intake handler only runs when explicitly invoked by `textus fetch KEY --as=automation` (or by `textus fetch stale`). The declaration is data only:
+Intake entries declare an external source by naming an **intake handler** — a registered, named function that pulls data into the entry. textus itself still makes no implicit network calls: an intake handler only runs when explicitly invoked by `textus fetch KEY --as=automation` (or by `textus fetch all`). The declaration is data only:
 
 ```yaml
 - key: feeds.calendar.events
@@ -478,7 +478,7 @@ rules:
 
 #### `on_stale:` semantics
 
-`on_stale:` declares what happens when `textus get` (or any read path that annotates freshness) encounters a stale intake entry. The value lives on the matching policy block, not on the entry. Vocabulary: `warn | sync | timed_sync`.
+`on_stale:` declares what happens when `get` encounters a stale intake entry. `get` is **read-through on every surface** (CLI, Ruby, MCP): it returns the freshest obtainable envelope, fetching on a stale verdict per the entry's fetch rule and degrading to a pure on-disk read for keys with no fetch rule (ADR 0062). The value lives on the matching policy block, not on the entry. Vocabulary: `warn | sync | timed_sync`.
 
 | Value | Behaviour |
 |---|---|
@@ -499,7 +499,7 @@ In intake mode the handler MUST return one of three shapes, all normalized by th
 **Fetch paths.** Two are supported:
 
 1. **In-process** — `textus fetch KEY --as=automation` resolves the entry's `intake.handler`, invokes the registered `:resolve_intake` hook with `(caps:, config:, args: {})`, and writes the result under a role holding `fetch` (`automation` by default).
-2. **External automation** — a cron job or agent harness reads `textus list --zone=intake --stale --output=json`, fetches the source out of band, and pipes bytes back through `textus put KEY --as=automation --stdin`. The CLI verb `textus fetch stale [--prefix=K] [--zone=Z]` drives this loop in one shot.
+2. **External automation** — a cron job or agent harness reads `textus list --zone=intake --stale --output=json`, fetches the source out of band, and pipes bytes back through `textus put KEY --as=automation --stdin`. The CLI verb `textus fetch all [--prefix=K] [--zone=Z]` drives this loop in one shot.
 
 Both paths share the same write gate, audit-log entry, and `:entry_fetched` event. User-supplied hooks live in `.textus/hooks/**/*.rb` and auto-load at `Store#initialize` — see §5.10 for the full hook contract.
 
@@ -719,7 +719,7 @@ than aborting the run.
 
 **Resolution.** For each key textus computes a `RuleSet { fetch, intake_handler_allowlist, guard, retention }` by walking every block whose `match` matches the key, ranked by specificity. **Per slot, the most specific block wins.** Two blocks of equal specificity that match the same key and fill the same slot is a manifest error reported by `textus doctor` (`rule_ambiguity`).
 
-**Read surface.** `textus rule list` dumps every block. `textus rule explain KEY` shows the resolved `RuleSet` for one key plus the effective guard predicate names for every write transition.
+**Read surface.** `textus rule list` dumps every block. `textus rule explain KEY` shows the resolved `RuleSet` for one key — lean effective `{fetch, guard}` by default; `--detail` adds every matched block and the effective guard predicate names for every write transition (ADR 0059).
 
 ### 5.12 Storage formats
 
@@ -866,7 +866,7 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 |---|---|---|
 | `list [--prefix=K] [--zone=Z]` | read | any |
 | `where K` | read | any |
-| `get K` | read | any |
+| `get K [--no-fetch]` | read (read-through by default: fetch-on-stale per the entry's fetch rule, degrades to a pure read; `--no-fetch` / `{fetch:false}` for an explicit pure on-disk read) | any |
 | `schema show K` | read | any |
 | `freshness [--prefix=K] [--zone=Z]` | read | any |
 | `audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]` | read | any |
@@ -881,9 +881,9 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 | `pulse [--since=N]` | read | any |
 | `put K --stdin --as=R [--fetch=NAME]` | write | per zone |
 | `propose K --stdin --as=R` | write | `propose`-holder (auto-prefixes propose_zone) |
-| `delete K --if-etag=E --as=R` | write | per zone |
+| `key delete K --if-etag=E --as=R` | write | per zone |
 | `fetch KEY --as=automation` | write | `fetch`-holder (typically `automation`) |
-| `fetch stale [--prefix=K] [--zone=Z] [--as=automation]` | write | `fetch`-holder (typically `automation`) |
+| `fetch all [--prefix=K] [--zone=Z] [--as=automation]` | write | `fetch`-holder (typically `automation`) |
 | `build [--prefix=K] [--dry-run]` | write | `build`-holder (typically `automation`) |
 | `retain [--prefix=K] [--zone=Z] --as=ROLE` | write | per zone (role must write the matched zone) |
 | `accept K --as=human` | write | `author`-holder (typically `human`) |
@@ -898,8 +898,8 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 ```json
 {
   "agent_quickstart": {
-    "read_verbs":     ["get", "list", "pulse", "schema", "boot", "rules"],
-    "write_verbs":    ["put KEY --as=agent --stdin"],
+    "read_verbs":     ["get", "list", "pulse", "schema_show", "boot", "rule_explain", "where", "deps", "rdeps"],
+    "write_verbs":    ["delete", "fetch", "fetch_all", "mv", "propose", "put"],
     "writable_zones": ["proposals"],
     "propose_zone":   "proposals",
     "latest_seq":     1842
@@ -907,7 +907,9 @@ 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` for an entry's field shape, `rules` for its freshness/guard policy) and never the CLI-only `audit`/`freshness`/`doctor` (ADR 0056). An agent learns an entry's `_meta` shape by calling the `schema` verb before a `put`/`propose`, not by shelling out to a CLI.
+`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 freshness/guard policy, and the graph reads `where`/`deps`/`rdeps`, ADR 0060) and never the CLI-only `audit`/`freshness`/`doctor` (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 `delete` and `mv` tools alongside their bulk `key_delete_prefix`/`key_mv_prefix` cousins (ADR 0060 amendment); safety scales with blast radius — the bulk `*_prefix` ops default to a dry-run Plan, single-key `delete` executes under an optional `if_etag`, and single-key `mv` applies immediately but exposes an optional `dry_run`.
 
 `latest_seq` is the current high-water mark of the audit log; agents should use it as the starting cursor for `pulse`.
 
@@ -936,7 +938,7 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
   "if_etag": "sha256:8f3c…" }
 ```
 
-`if_etag` is optional on `put`, required on `delete`. When provided, the write fails with `etag_mismatch` if the on-disk file's etag differs. When omitted on `put`, the write is unconditional (last-writer-wins).
+`if_etag` is optional on both `put` and `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).
 
 **`textus freshness` output shape:**
 
@@ -1109,7 +1111,7 @@ textus does not ship a built-in textus/2 → textus/3 migrator. The historical u
 | Compute field | `projection.reduce:` | `compute.transform:` |
 | `_meta` key | `reducer` | `transform` |
 | CLI flag | `--format=json` (envelope) | `--output=json` |
-| CLI verb | `refresh-stale` | `fetch stale` |
+| CLI verb | `refresh-stale` | `fetch all` |
 | CLI verb | `policy list/explain` | `rule list/explain` |
 
 **Hook migration.** Legacy event names / DSL methods must be renamed to the textus/3 forms above before a hook will load; see `CHANGELOG.md` §0.11.0 for the full event-rename detail.
@@ -1124,7 +1126,7 @@ textus does not ship a built-in textus/2 → textus/3 migrator. The historical u
 | `roles[*].kind:` (`accept_authority`/`generator`/`proposer`/`runner`) | `roles[*].can:` (subset of `propose`, `author`, `fetch`, `build`) |
 | Actors `runner`, `builder` | `automation` (`can: [fetch, build]`) by default |
 | `rules[*].refresh:` slot | `rules[*].fetch:` slot |
-| CLI `textus refresh` / `refresh stale` | `textus fetch` / `fetch stale` |
+| CLI `textus refresh` / `refresh stale` | `textus fetch` / `fetch all` |
 | `_meta.last_refreshed_at` | `_meta.last_fetched_at` |
 | Promotion predicate `:human_accept` / `:accept_authority_signed` | `:author_signed` |
 | Envelope `refreshing` | `fetching` |

data/docs/architecture/README.md

@@ -28,6 +28,23 @@ CLI verbs:  store.<verb>(..., role:)
 MCP gate:   textus mcp serve — same use cases, JSON-RPC.
 ```
 
+The CLI is a **projection of the per-verb `Contract`** (ADR 0063), the operator
+mirror of `MCP::Catalog`. The contract now owns the whole request lifecycle —
+`acquire → bind → invoke → render` (ADRs 0066–0068): one `Contract::Binder.bind`
+splits the uniform by-name `inputs` hash into the use-case's positional/keyword
+args for every surface; per-surface `view`s shape the output (`view` for
+MCP/Ruby, `view(:cli)` for the operator envelope); declarative `source:`/
+`coerce:`/`cli_stdin` populate inputs from files and stdin; `around:` resources
+wrap the single dispatch site (`RoleScope#dispatch_bound`) for stateful verbs;
+and `cli_default:` declares a CLI default that diverges from the agent default.
+`CLI::Runner` generates a command per `:cli` contract, dispatching `contract.verb`
+by construction. Only verbs with genuine *behavior* — `put` (fetch
+orchestration), `get` (UnknownKey + resolver suggestions, CLI-only), `build`
+(actor-role resolution + BuildLock), the `fetch`/`fetch_all` workers, and the
+`boot`/`doctor` composite reports — stay hand-authored, plus commands with no
+dispatcher verb (`init`, `hook`, `mcp serve`, `schema diff/init`). Total
+reconciliation specs make name/dispatch/facet drift unrepresentable.
+
 **Application**
 
 ```
@@ -37,10 +54,10 @@ Container        (single record — wired ports + manifest)
 Dispatcher       (static VERBS table: verb → use-case)
 RoleScope        (Store#as(role) — forwards verb calls)
 
-read/{get,get_or_fetch,list,where,uid,schema_envelope,
+read/{get,list,where,uid,schema_envelope,
       deps,rdeps,published,stale,validate_all,boot,doctor,
-      freshness,audit,blame,policy_explain,pulse}.rb
-write/{put,delete,mv,accept,reject,publish,
+      freshness,audit,blame,rule_explain,rule_list,pulse}.rb
+write/{put,delete,mv,accept,reject,build,
        materializer,intake_fetch,retention_sweep,
        fetch_worker,fetch_orchestrator,fetch_all}
 maintenance/{migrate,key_mv_prefix,key_delete_prefix,
@@ -171,13 +188,15 @@ The four members are wired in `Manifest.build` (`lib/textus/manifest.rb`). `Mani
 
 ## Read path (`store.get(key)`)
 
+`Read::Get` is the single public read verb (ADR 0062). It is read-through by default: it returns the freshest obtainable envelope, fetching on a stale verdict per the entry's fetch rule, and degrading to a pure on-disk result when the key has no fetch rule. An optional `fetch: false` flag (CLI `--no-fetch`, MCP `{fetch:false}`) forces a pure on-disk read.
+
 1. CLI verb (or MCP tool) calls `store.get(key, role:)` (or `store.as(role).get(key)`).
-2. `Store#get` looks up `Dispatcher::VERBS[:get] → Read::Get`, builds a `Call`, instantiates `Read::Get.new(container:, call:).call(key)`.
-3. `Read::Get#call` resolves the path through `container.manifest`, reads bytes via `container.file_store`, parses the envelope.
-4. Looks up the fetch policy via `container.manifest.rules.for(key)`. If absent, returns the envelope annotated fresh.
-5. Otherwise `Domain::Freshness::Evaluator.call(policy, envelope, now:)` returns a `Verdict`; the envelope is annotated with `stale`, `reason`, `fetching: false`.
+2. `Store#get` looks up `Dispatcher::VERBS[:get] → Read::Get`, builds a `Call`, instantiates `Read::Get.new(container:, call:).call(key)`. The contract declares `arg :fetch, default: true`, injected by `Contract::Binder.bind` at the single verb-dispatch chokepoint (`RoleScope#dispatch_bound`) for every surface — so the public verb is always read-through unless the caller explicitly passes `fetch: false`.
+3. `Read::Get#call(key, fetch: false)` runs the pure read sub-step inline: resolves the path through `container.manifest`, reads bytes via `container.file_store`, parses the envelope, and annotates a freshness verdict (`stale`, `reason`, `fetching: false`). When the key has no fetch rule, the envelope is annotated fresh and returned immediately — no orchestrator is involved.
+4. If `fetch: true` and the verdict is stale and the entry's fetch rule demands action, `Read::Get` hands off to `Write::FetchOrchestrator` (built lazily — a pure `fetch: false` call never touches the orchestrator). The orchestrator executes the fetch policy's `Action` (`sync`, `timed_sync`, `detached`, …) and returns an `Outcome`.
+5. The outcome is mapped back to an envelope: `Fetched` → fresh envelope from the write; `Detached` → original envelope with `fetching: true`; `Failed` → original envelope with `fetch_error` set; `Skipped` → original envelope unchanged.
 
-`store.get_or_fetch(key)` composes `Read::Get` with `Write::FetchOrchestrator` to optionally fetch on stale.
+The pure read is `Read::Get#call(key, fetch: false)` — it is the safe default for direct in-process callers (accept/reject/publish, materializer, uid, validate_all/validator, schema/tools, hooks/context) that must never trigger a fetch. They construct `Read::Get` directly, bypassing the dispatch injection that sets `fetch: true`. The prior separate read-through path `get_or_fetch` and the separate pure class `Read::GetEntry` were both unified into the one `Read::Get` class (ADR 0062 amendment).
 
 ## Write path (`store.put(key, ...)`)
 
@@ -186,7 +205,7 @@ The four members are wired in `Manifest.build` (`lib/textus/manifest.rb`). `Mani
 3. Delegates persistence to `Envelope::IO::Writer#put`, which serializes, schema-validates, etag-checks (raises `EtagMismatch` on conflict), writes via the `FileStore` port, and appends the audit row.
 4. Publishes `:entry_put` via `container.events` with `ctx: <Hooks::Context>`, `key:`, `envelope:`.
 
-`Write::{Delete,Mv,Accept,Reject,Publish}` follow the same shape: explicit container, the unified `Guard` for authz (built per transition via `GuardFactory`), `Envelope::IO::Writer` for persistence (where applicable), event published with the `Hooks::Context` handle.
+`Write::{Delete,Mv,Accept,Reject,Build}` follow the same shape: explicit container, the unified `Guard` for authz (built per transition via `GuardFactory`), `Envelope::IO::Writer` for persistence (where applicable), event published with the `Hooks::Context` handle.
 
 `Write::Mv` delegates the file-move + audit to `Envelope::IO::Writer#move`, then publishes `:entry_renamed` itself. UID injection (when the source lacks one) goes through `Envelope::IO::Writer#write` directly — no `Put` bypass.
 

data/docs/reference/conventions.md

@@ -92,7 +92,7 @@ External inputs land via `:resolve_intake` hooks, not shell commands. Each intak
 
 ```sh
 textus fetch feeds.notion.roadmap --as=automation
-textus fetch stale --zone=feeds --as=automation   # everything past its TTL
+textus fetch all --zone=feeds --as=automation   # everything past its TTL
 ```
 
 Freshness budgets live in the top-level `rules:` block, matched by glob:
@@ -103,24 +103,23 @@ rules:
     fetch: { ttl: 6h, on_stale: warn }   # warn | sync | timed_sync
 ```
 
-A typical scheduled-fetch integration shells the `fetch stale` sweep itself:
+A typical scheduled-fetch integration shells the `fetch all` sweep itself:
 
 ```sh
-textus fetch stale --zone=feeds --as=automation   # in cron / CI
+textus fetch all --zone=feeds --as=automation   # in cron / CI
 ```
 
 See [`./zones.md` §6](zones.md) for the full intake contract and [`../how-to/writing-hooks.md`](../how-to/writing-hooks.md) for writing custom handlers.
 
 ### Read vs. fetch
 
-There are two read operations, and the difference matters in custom code:
+There is one public read operation (ADR 0062):
 
-| Operation | Triggers fetch? | Use for |
-|-----------|-----------------|---------|
-| `ops.get` | No — pure read of on-disk envelope + freshness verdict | build / materialization paths, schema tooling, any context where a side-effecting read would surprise the caller |
-| `ops.get_or_fetch` | Yes — composes `get` with the orchestrator per the rule's `on_stale` policy | interactive reads (`textus get`, dashboards) where the caller wants the freshest envelope obtainable |
+| Operation | Behaviour | Use for |
+|-----------|-----------|---------|
+| `ops.get` | Read-through by default — fetches on stale per the entry's fetch rule; degrades to a pure on-disk read when the key has no fetch rule. Pass `fetch: false` (CLI `--no-fetch`, MCP `{fetch:false}`) for an explicit pure read | all callers, including interactive reads, dashboards, and scripts that want the freshest obtainable envelope |
 
-Build always uses the pure path; injecting fetch into materialization caused the cascading-staleness incident behind issue #59. Pick `get_or_fetch` only when you genuinely want side effects on read.
+Build pipelines and other internal callers that must never trigger a fetch (materializer, projection, schema tooling, accept/reject/publish, uid, validator) construct `Read::Get` directly with the method default `fetch: false` — a pure, orchestrator-free read. They bypass the verb-dispatch injection that sets `fetch: true`, so they always get pure reads without any extra argument.
 
 ## Body content
 

data/lib/textus/boot.rb

@@ -81,12 +81,11 @@ module Textus
       { "name" => "list" },
       { "name" => "get" },
       { "name" => "where", "summary" => "resolve a key to its zone and path without reading" },
-      { "name" => "schema" },
+      { "name" => "schema", "summary" => "schema operations: 'schema show KEY', 'schema diff', 'schema init', 'schema migrate'" },
       { "name" => "put" },
       { "name" => "propose" },
       { "name" => "accept",   "summary" => "apply a queued proposal to its target zone; requires the author capability" },
-      { "name" => "key",      "summary" => "key operations: 'key mv', 'key uid'" },
-      { "name" => "delete",   "summary" => "delete an entry; --as=<role>" },
+      { "name" => "key",      "summary" => "key operations: 'key delete', 'key mv', 'key uid'" },
       { "name" => "build",    "summary" => "materialize derived entries; publish_to and publish_tree fan out copies" },
       { "name" => "fetch" },
       { "name" => "freshness", "summary" => "per-entry freshness report (status, age, ttl, on_stale)" },
@@ -127,11 +126,15 @@ module Textus
       propose_zone = manifest.policy.propose_zone_for(agent_role)
 
       {
-        # Derived from the MCP catalog (ADR 0056): the agent's real read surface,
-        # so the quickstart can neither advertise a verb the agent cannot call
-        # (audit/freshness/doctor are CLI-only) nor omit one it can (schema/rules).
+        # Both verb lists derive from the MCP catalog (ADR 0056, ADR 0057): the
+        # agent's real read and write surface, named as verbs the agent calls —
+        # not CLI strings. read_verbs can neither advertise a verb the agent
+        # cannot call (audit/freshness/doctor are CLI-only) nor omit one it can
+        # (schema_show/rules); write_verbs drops the old `put KEY --as=… --stdin` CLI
+        # framing (role is connection-resolved over MCP; there is no stdin).
+        # writable_zones / propose_zone below carry the agent's write authority.
         "read_verbs" => Textus::MCP::Catalog.read_verbs,
-        "write_verbs" => agent_role ? ["put KEY --as=#{agent_role} --stdin"] : [],
+        "write_verbs" => agent_role ? Textus::MCP::Catalog.write_verbs : [],
         "writable_zones" => writable_zones,
         "propose_zone" => propose_zone,
         "latest_seq" => audit_log.latest_seq,

data/lib/textus/cli/group/fetch.rb

@@ -5,9 +5,9 @@ module Textus
         command_name "fetch"
 
         def parse(argv)
-          if argv.first == "stale"
+          if argv.first == "all"
             argv.shift
-            @sub_klass = Verb::FetchStale
+            @sub_klass = Verb::FetchAll
           else
             @sub_klass = Verb::Fetch
           end

data/lib/textus/cli/group.rb

@@ -6,6 +6,7 @@ module Textus
         # `parent_group` is this group counts as a subcommand. Sorted
         # alphabetically by command_name for stable help output.
         def subcommands
+          Textus::CLI::Runner.install!
           Verb.descendants
               .select { |k| k.parent_group == self && k.command_name }
               .sort_by(&:command_name)

data/lib/textus/cli/runner.rb

@@ -0,0 +1,187 @@
+module Textus
+  class CLI
+    # Generates CLI::Verb (and CLI::Group) subclasses from per-verb contracts,
+    # so the CLI surface is a projection of the contract — the operator-facing
+    # mirror of MCP::Catalog (ADR 0063).
+    module Runner
+      # Subclassable base for contract-projected verbs. Carries the verb's
+      # contract (class attr `spec`) and the generic dispatch, exposing one
+      # overridable seam, #invoke, that defaults to the generic projection.
+      # Escape-hatch verbs subclass this and override #invoke to add behavior
+      # (suggestions, --stdin, BuildLock, multi-dispatch) WITHOUT restating the
+      # verb name — `spec.verb` remains the single source of dispatch.
+      class Base < Verb
+        class << self
+          attr_accessor :spec
+
+          # ADR 0064: derive the CLI command name from the contract's cli_leaf
+          # when not set explicitly, so an escape-hatch class never restates its
+          # own name. The reconciliation spec proves command_name == cli_leaf for
+          # every such class, so this is an equivalence, not a behavior change.
+          def command_name(name = nil)
+            return super if name
+
+            super() || spec&.cli_leaf
+          end
+        end
+
+        def spec = self.class.spec
+
+        def call(store)
+          invoke(store)
+        end
+
+        # Default: pure contract projection. Override in subclasses for behavior.
+        def invoke(store)
+          Runner.dispatch(self, store, spec)
+        end
+
+        def flag_values(s = spec)
+          s.args.reject(&:positional).each_with_object({}) do |a, h|
+            raw = respond_to?(a.name) ? public_send(a.name) : nil
+            next if raw.nil?
+
+            h[a.name] = Runner.coerce(a, raw)
+          end
+        end
+      end
+
+      module_function
+
+      # Normalize parsed CLI input into the uniform by-name inputs hash and
+      # dispatch through RoleScope's single bind+invoke site. A missing required
+      # arg becomes a UsageError phrased in the operator's command path (parity
+      # with the hand-written verbs).
+      def dispatch(verb_instance, store, spec)
+        inputs = Textus::Contract::Binder.inputs_from_ordered(
+          spec, verb_instance.positional, verb_instance.flag_values(spec)
+        )
+        inputs = inputs.merge(Textus::Contract::Sources.from_stdin(spec, verb_instance.stdin)) if spec.cli_stdin
+        inputs = Textus::Contract::Sources.acquire(spec, inputs)
+        inputs = apply_cli_defaults(spec, inputs)
+        scope = verb_instance.session_for(store)
+        begin
+          result = scope.dispatch_bound(spec.verb, inputs)
+        rescue Textus::Contract::MissingArgs => e
+          raise UsageError.new("#{spec.cli_path} requires #{e.missing.first.wire}")
+        end
+        verb_instance.emit(shape(spec, result, inputs))
+      end
+
+      # Fill CLI-specific defaults (cli_default:) for args the operator did not
+      # pass, where the CLI default diverges from the contract default the agent
+      # surfaces use — e.g. migrate/zone_mv apply by default on the CLI but plan
+      # by default for agents (ADR 0068). The divergence is legible in the
+      # contract, not hidden in a hand class.
+      def apply_cli_defaults(spec, inputs)
+        spec.args.each_with_object(inputs.dup) do |a, h|
+          next if a.cli_default == :__unset || h.key?(a.name)
+
+          h[a.name] = a.cli_default
+        end
+      end
+
+      # Shape the use-case result for the CLI wire via the verb's :cli view
+      # (falling back to the default view). The view is called uniformly as
+      # (result, inputs); an inputs-aware view echoes an input such as the key
+      # (ADR 0067).
+      def shape(spec, result, inputs)
+        Textus::Contract::View.render(spec, :cli, result, inputs)
+      end
+
+      # The default the CLI flag is generated against — `cli_default:` when the
+      # operator-facing default diverges from the contract default the agent
+      # surfaces use, else the contract `default`. This drives boolean flag
+      # polarity so a verb that applies-by-default on the CLI but plans-by-default
+      # for agents (migrate, zone_mv) gets a `--dry-run` flag, not `--no-dry-run`.
+      def effective_default(arg)
+        arg.cli_default == :__unset ? arg.default : arg.cli_default
+      end
+
+      def flagspec_for(arg)
+        wire = arg.wire.to_s.tr("_", "-")
+        if arg.type == :boolean
+          effective_default(arg) == true ? "--no-#{wire}" : "--#{wire}"
+        else
+          "--#{wire}=VALUE"
+        end
+      end
+
+      # NB: compare arg.type by equality, not `case`/`===` — `Integer === arg.type`
+      # is false when arg.type is the Integer *class* (it tests instance-of), so a
+      # `when Integer` branch would silently never coerce.
+      def coerce(arg, raw)
+        return effective_default(arg) != true if arg.type == :boolean
+        return Integer(raw) if arg.type == Integer
+
+        raw
+      end
+
+      def ensure_group(name)
+        const = name.split("_").map(&:capitalize).join
+        return Group.const_get(const, false) if Group.const_defined?(const, false)
+
+        g = Class.new(Group) { command_name name }
+        Group.const_set(const, g)
+        g
+      end
+
+      # Contract verbs whose CLI behavior is a genuine `< Runner::Base` override
+      # — behavior the generic projection cannot express (ADR 0068/0069):
+      #   get   — raises UnknownKey with resolver suggestions (a CLI-only
+      #           affordance; the agent surface deliberately returns nil)
+      #   put   — IntakeFetch read-through orchestration on --fetch
+      #   build — auto-resolves the build-capability actor role (not --as) and
+      #           serializes under BuildLock; the role resolution is policy, not
+      #           a projection (around: covers only the lock)
+      BEHAVIORAL_HATCHES = %i[get put build].freeze
+
+      # Contract verbs whose CLI is a plain `< Verb` command, not a projection at
+      # all — worker verbs and composite reports assembled outside the contract:
+      #   fetch, fetch_all — background intake workers (not request/response)
+      #   boot, doctor     — composite reports
+      NON_PROJECTED_CLI = %i[fetch fetch_all boot doctor].freeze
+
+      # The installer skips generation for either category.
+      HAND_AUTHORED_VERBS = (BEHAVIORAL_HATCHES + NON_PROJECTED_CLI).freeze
+
+      def hand_authored?(verb) = HAND_AUTHORED_VERBS.include?(verb)
+
+      def install!
+        @installed ||= {}
+        Textus::Dispatcher::VERBS.each_value do |klass|
+          next unless klass.respond_to?(:contract?) && klass.contract?
+
+          spec = klass.contract
+          next unless spec.cli?
+          next if hand_authored?(spec.verb)
+          next if @installed[spec.verb]
+
+          install_for(spec)
+          @installed[spec.verb] = true
+        end
+      end
+
+      def install_for(spec)
+        group = spec.cli_group ? ensure_group(spec.cli_group) : nil
+        leaf  = spec.cli_leaf
+        non_positional = spec.args.reject(&:positional)
+
+        klass = Class.new(Base)
+        klass.spec = spec
+        klass.command_name leaf
+        klass.parent_group group if group
+        klass.option :as_flag, "--as=ROLE"
+        klass.option :use_stdin, "--stdin" if spec.cli_stdin
+        non_positional.each { |a| klass.option a.name, Runner.flagspec_for(a) }
+
+        # Anchor the anonymous class to a constant so descendants discovery is
+        # stable. Name it after the verb under a Generated namespace.
+        const_name = spec.verb.to_s.split("_").map(&:capitalize).join
+        gen = "Gen#{const_name}"
+        Verb.const_set(gen, klass) unless Verb.const_defined?(gen, false)
+        klass
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/build.rb

@@ -1,12 +1,12 @@
 module Textus
   class CLI
     class Verb
-      class Build < Verb
-        command_name "build"
+      class Build < Runner::Base
+        self.spec = Textus::Write::Build.contract
 
         option :prefix, "--prefix=K"
 
-        def call(store)
+        def invoke(store)
           role = store.manifest.policy.actor_for("build") or
             raise UsageError.new(
               "no role holds the 'build' capability",
@@ -14,7 +14,7 @@ module Textus
             )
           Textus::Ports::BuildLock.with(root: store.root) do
             ops = store.as(role)
-            result = ops.publish(prefix: prefix)
+            result = ops.build(prefix: prefix)
             emit(result)
           end
         end

data/lib/textus/cli/verb/{fetch_stale.rb → fetch_all.rb}

@@ -1,8 +1,8 @@
 module Textus
   class CLI
     class Verb
-      class FetchStale < Verb
-        command_name "stale"
+      class FetchAll < Verb
+        command_name "all"
         parent_group Group::Fetch
 
         option :prefix, "--prefix=KEY"