textus 0.49.0 → 0.50.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29a370d0ed895357e5a2e70d5f9b41542b0a4e5036472aa6f728f7a0bc459838
-  data.tar.gz: 87bf64e383226fad74ca8534fca9f8b8de707f1e01bc910c05ad1266e5de032a
+  metadata.gz: 721213d52e7efc2f5bd46abf386bd099ac1d4bd3cec33d956d8a3c43b4d76018
+  data.tar.gz: 25695c008eb417926488b6881ad44f5867c7f56b72b721bd8b7b2d21a34eeb9e
 SHA512:
-  metadata.gz: d3f2279c8660c754b64defe04aeac05e198095ef056b7a4aee534d3bd290baac7bf13d206999872a82c6bc61f723771f852bbfde2594fbaa17f80a19082df877
-  data.tar.gz: e11ce9e704b3ea33ef94012d8425624dd3391152869d1ecb6b00e5422042a50d4c3c75612227ddd61f9ed8c10720e6f254c818e1492056a2ca3d00751500554b
+  metadata.gz: b6cbf56a3c352f9715dffafd74c0c39459766181efb97624e4aabed8cf3a32f744ea6f5fa7d620a5a61ad7e9050543bfb86d20e2d5b272e10578a5018a7ddc76
+  data.tar.gz: 95be6f8590727b6cc64aa52b84d456dac78c035f279af6819184a698ee75400b6a54c336008b47f93985efee42e4d9bac1909d40d5c53edfd16843f2de367cab

data/CHANGELOG.md

@@ -9,6 +9,25 @@ 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.50.0 — 2026-06-04 — Observability on two axes + boot lifecycle (ADR 0083, 0084, 0085)
+
+`freshness` collapses into `pulse`, the contract-drift guard stops deadlocking, and `boot` gains a lean session-start projection shipped via a plugin.
+
+### Added
+
+- **`boot --lean`** (ADR 0084) — a compact orientation projection (`protocol`, `store_root`, `zones`, `agent_quickstart`, `contract_etag`) for cheap session-start injection. The full `boot` envelope now also carries `contract_etag`. `--lean` is a contract arg, so it threads to every surface (CLI flag, MCP `lean` tool arg, Ruby kwarg).
+- **textus ships as a Claude Code plugin** (ADR 0084) — a single self-contained `.claude-plugin/plugin.json` with an **inline** `SessionStart` hook (`startup`/`clear`/`compact`) that runs `boot --lean`, so enabling the plugin auto-orients each session. The agent-invokable `boot` tool is unchanged; the hook is additive. Plugin data is kept inside `.claude-plugin/` (a separate concern from the gem), not a top-level `hooks/` dir.
+- **Agent-integration config is textus-managed, projected from canon** (ADR 0086). This repo's `.mcp.json` and `.claude-plugin/plugin.json` are now **build artifacts** — `textus build` projects them from `knowledge.project` + `Textus::VERSION` (so the plugin version can never drift off the gem) the same way it projects `CLAUDE.md`. The plugin manifest also gains an inline `mcpServers` stanza (enable the plugin → MCP server *and* orientation hook in one). A new `provenance: false` derived-entry flag lets the JSON renderer emit config without a `_meta` block. Downstream consumers are unaffected — `init --with-agent` still scaffolds a write-once `.mcp.json` (a build must never clobber a user's config).
+
+### Changed
+
+- **The contract-drift guard applies to mutating verbs only; `boot` self-heals** (ADR 0083). A mid-session manifest/hook/schema edit no longer deadlocks every MCP verb behind "re-run boot": pure reads and `boot` bypass the guard, `boot` re-arms the session's cached `contract_etag`, and only mutating verbs (the `Write::` family + the destructive `Maintenance::` verbs `tend`/`zone_mv`/`key_mv_prefix`/`key_delete_prefix`) enforce it. "Re-run boot" now actually recovers instead of looping. Refines ADR 0074.
+- **`tend` returns a health summary, not full `issues[]`** (ADR 0085) — matching `pulse`; `doctor` stays the sole owner of detailed health output.
+
+### Removed (breaking)
+
+- **The public `freshness` verb** (ADR 0085). Observability is now two verbs on orthogonal axes — `pulse` (transient/temporal: `changed` + `stale` + `next_due_at`) and `doctor` (structural correctness). The lifecycle scan that backed `freshness` becomes a Ruby-only internal (empty `surfaces`, ADR 0073) consumed by `pulse` and the hook context; per-entry detail is reconstructable from `get` (carries `stale`/`last_fetched_at`) + `rule_explain` (the `lifecycle:` ttl + `on_expire`). **Migration:** replace `textus freshness` with `textus pulse` (for the `stale` list / `next_due_at`) or `get` + `rule_explain` (for one entry's verdict). SPEC's generator-drift attribution is corrected to `doctor`'s `generator_drift` check.
+
 ## 0.49.0 — 2026-06-04 — Normalize the key-verb family + remove `migrate` (ADR 0082)
 
 The single-key mutation verbs gain the `key_` family stem, and the `migrate` orchestrator is removed.

data/SPEC.md

@@ -398,7 +398,7 @@ No partials. No lambdas. No HTML escaping (output is raw text, intended for Mark
 
 #### 5.2.2 External compute (`kind: external`)
 
-A derived entry that is produced by a build tool *outside* textus — `rake`, `just`, a shell script, anything — declares `compute: { kind: external, ... }`. textus does **not** execute the command (consistent with §2); the external automation is responsible for writing the file. textus records `sources:` so `textus freshness` can compare source mtimes against the derived file's `_meta.generated.at` and report staleness.
+A derived entry that is produced by a build tool *outside* textus — `rake`, `just`, a shell script, anything — declares `compute: { kind: external, ... }`. textus does **not** execute the command (consistent with §2); the external automation is responsible for writing the file. textus records `sources:` so `doctor`'s `generator_drift` check can compare source mtimes against the derived file's `_meta.generated.at` and report staleness. (Generator/build drift is dependency-based, not age-based; ADR 0079 keeps it out of the `lifecycle:` unification and ADR 0085 keeps it out of the internal `freshness` scan — it is a `doctor` health check.)
 
 ```yaml
 - key: output.catalogs.skills
@@ -415,9 +415,9 @@ A derived entry that is produced by a build tool *outside* textus — `rake`, `j
 
 **`sources:`** is a list. Each element is either a dotted key prefix (matched against manifest entries) or a filesystem path (relative to the repo root, or absolute). For each key prefix, every matching entry's file mtime is checked. For each path, file or directory mtime is checked.
 
-**`command:`** is recorded in the staleness row's `generator` field but never executed. It exists so `textus freshness` output can carry a hint about how to fetch.
+**`command:`** is recorded in the staleness row's `generator` field but never executed. It exists so `doctor`'s `generator_drift` output can carry a hint about how to regenerate.
 
-**Freshness contract.** An entry with `compute: { kind: external }` is reported by `textus freshness` as `stale` when:
+**Generator-drift contract.** An entry with `compute: { kind: external }` is reported by `doctor`'s `generator_drift` check as drifted when:
 - The derived file does not exist, OR
 - `_meta.generated.at` is missing or unparseable, OR
 - Any `sources:` element has been modified after `_meta.generated.at`.
@@ -498,7 +498,7 @@ In intake mode the handler MUST return one of three shapes, all normalized by th
 **Refresh paths.** Two are supported:
 
 1. **In-process** — a read-through `textus get KEY --as=automation` on a stale entry whose rule says `on_expire: refresh` 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 freshness --zone=intake --output=json`, fetches sources reported `expired` out of band, and pipes bytes back through `textus put KEY --as=automation --stdin`.
+2. **External automation** — a cron job or agent harness reads the `stale` list from `textus pulse` (the soonest deadline is `next_due_at`), fetches the sources of the keys reported stale out of band, and pipes bytes back through `textus put KEY --as=automation --stdin`. (`pulse` derives `stale`/`next_due_at` from the internal lifecycle scan; ADR 0085 removed the standalone `freshness` verb. For per-entry detail — ttl, age, on_expire action — read `textus get KEY` and `textus rule_explain KEY`.)
 
 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.
 
@@ -668,7 +668,7 @@ The three `:fetch_*` lifecycle events report the progress and failures of backgr
 **Signature invariant** — hooks receive a capability handle as their first keyword argument; the name depends on the mode:
 
 - **RPC hooks** (`rpc` mode) receive `caps:` — a `Textus::Container`. Event-specific kwargs (`config:`, `args:`, `rows:`) follow in the stable order shown in the table above.
-- **Pub-sub hooks** (`pubsub` mode) receive `ctx:` — a `Textus::Hooks::Context` that exposes a narrow surface: `get`, `list`, `deps`, `freshness` (reads), `put`, `delete`, `audit` (authorized writes), `publish_followup`, plus `role` and `correlation_id`. The raw `Store` is not handed out.
+- **Pub-sub hooks** (`pubsub` mode) receive `ctx:` — a `Textus::Hooks::Context` that exposes a narrow surface: `get`, `list`, `deps`, `freshness` (reads — `freshness` is the Ruby-only internal lifecycle scan, ADR 0085, not a public verb), `put`, `delete`, `audit` (authorized writes), `publish_followup`, plus `role` and `correlation_id`. The raw `Store` is not handed out.
 
 Declaring `store:` instead of `caps:` in an RPC callable will pass registration but raise `UsageError` at call time (`Hooks::RpcRegistry#invoke` rejects `store:` — there is no shim).
 
@@ -865,7 +865,6 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 | `where K` | read | any |
 | `get K [--no-fetch]` | read (read-through by default: refresh-on-stale per the entry's `lifecycle` rule when `on_expire: refresh`, 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 |
 | `blame KEY` | read | any |
 | `rule list` / `rule explain KEY` | read | any |
@@ -902,7 +901,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 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).
+`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 lifecycle/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. `build` is also on MCP (ADR 0076): it is caller-agnostic and self-elevating — it always runs as the manifest's `build`-capable actor regardless of the calling role, grants no authority over content (build is a pure, idempotent function of already-accepted canon, ADR 0070), and is serialized by a shared single-writer lock across all transports so a concurrent CLI or background build cannot collide with an MCP-triggered one.
 
@@ -923,7 +922,7 @@ The agent's MCP write surface includes the single-key `key_delete` and `key_mv`
 }
 ```
 
-`cursor` is the new high-water mark; pass it as `--since` on the next call. `changed` is sourced from `audit --seq-since`. `stale` is sourced from `freshness`. `pending_review` lists all keys in the queue zone. `doctor` is an `{ok, warn, fail}` count summary. `contract_etag` is the `sha256:`-prefixed composite content hash of the contract — the manifest plus hooks and schemas (ADR 0074, via ADR 0025) — for cheap change-detection. `next_due_at` is the soonest upcoming freshness deadline across entries (ISO-8601, or `null` if none). `hook_errors` lists hook failures recorded since the cursor. When `--since` is below the oldest available seq (due to audit log rotation), pulse returns `CursorExpired`.
+`cursor` is the new high-water mark; pass it as `--since` on the next call. `changed` is sourced from `audit --seq-since`. `stale` is computed by the internal lifecycle scan (the former `freshness` verb, now Ruby-only — ADR 0085 folded its agent-facing output into `pulse`). `pending_review` lists all keys in the queue zone. `doctor` is an `{ok, warn, fail}` count summary. `contract_etag` is the `sha256:`-prefixed composite content hash of the contract — the manifest plus hooks and schemas (ADR 0074, via ADR 0025) — for cheap change-detection. `next_due_at` is the soonest upcoming lifecycle deadline across entries (ISO-8601, or `null` if none). `hook_errors` lists hook failures recorded since the cursor. When `--since` is below the oldest available seq (due to audit log rotation), pulse returns `CursorExpired`.
 
 **`put` input** (read from stdin when `--stdin` is given):
 
@@ -935,25 +934,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).
 
-**`textus freshness` output shape:**
-
-```json
-{
-  "verb": "freshness",
-  "rows": [
-    { "key": "feeds.upstream.notes",
-      "zone": "feeds",
-      "last_fetched_at": "2026-05-21T13:21:17Z",
-      "age_seconds": 65000,
-      "ttl_seconds": 43200,
-      "on_expire": "warn",
-      "status": "expired",
-      "next_due_at": "2026-05-22T01:21:17Z" }
-  ]
-}
-```
-
-Each row reports one entry's verdict (`fresh`, `expired`, or `no_policy`) plus the matched rule's `on_expire` action, against its matched `lifecycle:` rule. `textus build` consumes its own staleness signal and executes derived entries' projections under a `build`-holding role (`automation` by default); `--dry-run` prints the plan without executing.
+The lifecycle scan behind `pulse.stale`/`pulse.next_due_at` reports, per entry, one verdict (`fresh`, `expired`, or `no_policy`) plus the matched rule's `on_expire` action, against its matched `lifecycle:` rule. 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 `lifecycle:` ttl + `on_expire`). `textus build` consumes its own staleness signal and executes derived entries' projections under a `build`-holding role (`automation` by default); `--dry-run` prints the plan without executing.
 
 `textus accept K --as=human` promotes a pending entry into its target zone: 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`.
 
@@ -1002,7 +983,7 @@ Given a manifest entry where `key: identity.self` lives in the `identity` zone (
 Given the `person` schema and a `put` whose frontmatter omits `relationship`, the result is the error envelope with `code: "schema_violation"`, `details.missing: ["relationship"]`, and exit code 1.
 
 **Fixture D — Staleness detection:**
-Given a manifest entry `intake.notes` matched by a `rules: [{ match: intake.notes, lifecycle: { ttl: 1h, on_expire: warn } }]` block and an envelope on disk whose `_meta.last_fetched_at` is older than `now - ttl`, `textus freshness --output=json` includes a row for `intake.notes` with `status: "expired"`. Calling `textus freshness` does NOT trigger a refresh.
+Given a manifest entry `intake.notes` matched by a `rules: [{ match: intake.notes, lifecycle: { ttl: 1h, on_expire: warn } }]` block and an envelope on disk whose `_meta.last_fetched_at` is older than `now - ttl`, `textus pulse --output=json` lists `intake.notes` in its `stale` array (the lifecycle scan classifies it `expired`). The scan is pure: producing this verdict does NOT trigger a refresh.
 
 **Fixture E — Projection build:**
 Given a manifest entry `derived.catalogs.skills` whose `compute: { kind: projection }` clause selects fields from `working.projects` entries, `textus build derived.catalogs.skills` materializes the derived entry on disk with frontmatter and body matching the projected shape. The output is content-addressed (no `generated_at` timestamp, ADR 0070), so rebuilding with unchanged sources reproduces it byte-for-byte and writes nothing.
@@ -1060,7 +1041,7 @@ A `textus/3` implementation MUST:
 - [ ] Refuse writes whose resolved role lacks the capability the target zone-kind requires with `write_forbidden`.
 - [ ] Return envelopes matching the shape in §8 exactly (with `_meta`, not `frontmatter`).
 - [ ] Use the error codes in §8 and the exit-code table.
-- [ ] Implement `textus freshness` per §5.1 and §9, walking each entry, matching it against the top-level `rules:` block, and reporting `fresh|expired|no_policy` (plus the `on_expire` action) without invoking any refresh.
+- [ ] Implement the lifecycle scan behind `pulse` (`stale`/`next_due_at`) and the hook context per §5.11 and §9, walking each entry, matching it against the top-level `rules:` block, and reporting `fresh|expired|no_policy` (plus the `on_expire` action) without invoking any refresh. (ADR 0085: a Ruby-only internal scan — there is no public `freshness` verb.)
 - [ ] Pass the conformance fixtures A–I in §12.
 
 A `textus/3` implementation MAY:

data/docs/reference/conventions.md

@@ -69,7 +69,7 @@ A derived entry declares a `compute:` block with a `kind:` discriminator. Two ki
     to: [docs/people.md]            # optional repo-relative byte-copy targets
 ```
 
-**`compute: { kind: external }`** — an external build tool (rake, just, a shell script) produces the file. textus never executes the `command:`; it only tracks `sources:` so `textus freshness` can compare source mtimes against the file's `_meta.generated.at`. The role running the build must hold `build` (default: `automation`).
+**`compute: { kind: external }`** — an external build tool (rake, just, a shell script) produces the file. textus never executes the `command:`; it only tracks `sources:` so `doctor`'s `generator_drift` check can compare source mtimes against the file's `_meta.generated.at`. The role running the build must hold `build` (default: `automation`).
 
 ```yaml
 - key: artifacts.catalogs.skills
@@ -92,7 +92,7 @@ External inputs land via `:resolve_intake` hooks, not shell commands. Each intak
 
 ```sh
 textus get feeds.notion.roadmap --as=automation        # refreshes if stale
-textus freshness --zone=feeds --output=json            # which entries are expired
+textus pulse --output=json                             # `stale` lists expired entries; `next_due_at` is the soonest deadline
 ```
 
 Lifecycle budgets live in the top-level `rules:` block, matched by glob:
@@ -146,4 +146,4 @@ The user-facing CLI surface, the wire envelope shape, and the protocol version (
 
 - **MCP servers**: a thin server that exposes `textus get` and `textus put` as tools is the recommended way to give Claude/agents access. Don't bake MCP into this gem.
 - **Vector stores**: index `body` content into a vector store if you want fuzzy retrieval. `frontmatter` stays in textus as the source of truth for deterministic facts.
-- **CI**: run `textus freshness` (or `textus list` + schema validation) in CI to catch drift between derived entries and their sources.
+- **CI**: run `textus doctor` (the `generator_drift` check) or `textus pulse` (the `stale` list) in CI to catch drift between derived entries and their sources.

data/lib/textus/boot.rb

@@ -71,49 +71,50 @@ module Textus
       },
     }.freeze
 
-    # Curated agent-facing verb catalog. For verbs that have a Dispatcher contract,
-    # the summary is derived from `contract.summary` at load time (ADR 0039). The
-    # editorial strings below are the fallback for CLI-only verbs without contracts.
-    # CLI_VERBS itself is assigned in textus.rb after Zeitwerk eager_load so that
-    # all contract-declaring files are loaded before derivation runs.
+    # Curated agent-facing verb catalog. This declares which verbs the operator
+    # CLI surfaces and in what order — the editorial presentation. The summary of
+    # each verb is a fact, not presentation: it is derived from `contract.summary`
+    # at load time (ADR 0039). A literal "summary" survives here only for grouped
+    # CLI tokens (schema/key/rule/hook) that aggregate several sub-contracts and so
+    # have no single contract to derive from. CLI_VERBS itself is assigned in
+    # textus.rb after Zeitwerk eager_load so all contract files are present.
     CURATED_CLI_VERBS = [
       { "name" => "boot" },
       { "name" => "list" },
       { "name" => "get" },
-      { "name" => "where", "summary" => "resolve a key to its zone and path without reading" },
+      { "name" => "where" },
       { "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 delete', 'key mv', 'key uid'" },
-      { "name" => "build",    "summary" => "materialize derived entries; publish_to and publish_tree fan out copies" },
+      { "name" => "accept" },
+      { "name" => "key", "summary" => "key operations: 'key delete', 'key mv', 'key uid'" },
+      { "name" => "build" },
       { "name" => "tend" },
-      { "name" => "freshness", "summary" => "per-entry lifecycle report (status, age, ttl, on_expire action)" },
-      { "name" => "audit",    "summary" => "query .textus/audit.log with filters (key, role, since, correlation-id, ...)" },
-      { "name" => "blame",    "summary" => "audit rows for one key joined with git commit metadata" },
-      { "name" => "rule",     "summary" => "inspect effective rules: 'rule list', 'rule explain KEY'" },
-      { "name" => "doctor",   "summary" => "health-check the store (missing schemas, illegal keys, sentinel drift, etc.)" },
-      { "name" => "hook",     "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
+      { "name" => "audit" },
+      { "name" => "blame" },
+      { "name" => "rule", "summary" => "inspect effective rules: 'rule list', 'rule explain KEY'" },
+      { "name" => "doctor" },
+      { "name" => "hook", "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
       { "name" => "pulse" },
       { "name" => "capabilities" },
     ].freeze
 
-    # Build the CLI verb catalog by deriving each summary from the corresponding
-    # Dispatcher contract when one exists, falling back to the editorial string for
-    # CLI-only verbs without a contract (e.g. accept, build, where). Called once
-    # from textus.rb after eager_load so all contract files are present.
-    def self.build_cli_verbs
-      by_contract = Dispatcher::VERBS.values
-                                     .select { |k| k.respond_to?(:contract?) && k.contract? }
-                                     .to_h { |k| [k.contract.verb.to_s, k.contract.summary] }
+    # verb token => contract.summary, for every Dispatcher verb that carries a
+    # contract. The single source for a verb's one-line summary (ADR 0039).
+    def self.contract_summaries
+      Dispatcher::VERBS.values
+                       .select { |k| k.respond_to?(:contract?) && k.contract? }
+                       .to_h { |k| [k.contract.verb.to_s, k.contract.summary] }
+    end
 
+    # Build the CLI verb catalog: each summary is derived from its contract when
+    # one exists, falling back to the curated editorial string for grouped tokens
+    # (schema/key/rule/hook). Called once from textus.rb after eager_load.
+    def self.build_cli_verbs
+      summaries = contract_summaries
       CURATED_CLI_VERBS.map do |entry|
-        derived = by_contract[entry["name"]]
-        if derived
-          entry.merge("summary" => derived)
-        else
-          entry
-        end
+        derived = summaries[entry["name"]]
+        derived ? entry.merge("summary" => derived) : entry
       end
     end
 
@@ -130,7 +131,8 @@ module Textus
         # 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
+        # cannot call (audit/doctor are CLI-only; freshness is a Ruby-only
+        # internal scan, ADR 0085) 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.
@@ -196,8 +198,20 @@ module Textus
       )
     end
 
-    def self.build(container:)
+    def self.build(container:, lean: false)
       manifest = container.manifest
+      etag = Textus::Etag.for_contract(container.root)
+
+      if lean
+        return {
+          "protocol" => PROTOCOL_ID,
+          "store_root" => container.root,
+          "zones" => zones_for(manifest),
+          "agent_quickstart" => agent_quickstart(manifest, container.audit_log),
+          "contract_etag" => etag,
+        }
+      end
+
       {
         "protocol" => PROTOCOL_ID,
         "store_root" => container.root,
@@ -208,6 +222,7 @@ module Textus
         "cli_verbs" => CLI_VERBS.map(&:dup),
         "agent_protocol" => agent_protocol(manifest),
         "agent_quickstart" => agent_quickstart(manifest, container.audit_log),
+        "contract_etag" => etag,
         "docs" => { "spec" => "SPEC.md", "example" => "examples/project/" },
       }
     end

data/lib/textus/builder/renderer/json.rb

@@ -6,7 +6,7 @@ module Textus
       class Json < Renderer
         def call(mentry:, data:)
           content = mentry.template ? parse_rendered_template!(mentry, data) : default_shape(mentry, data)
-          final = InjectMeta.call(content, mentry)
+          final = mentry.provenance ? InjectMeta.call(content, mentry) : content
           Entry.for_format("json").serialize(meta: {}, body: "", content: final)
         end
 

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

@@ -3,9 +3,10 @@ module Textus
     class Verb
       class Boot < Verb
         command_name "boot"
+        option :lean, "--lean"
 
         def call(store)
-          emit(store.boot)
+          emit(store.boot(lean: !!lean))
         end
       end
     end

data/lib/textus/cli.rb

@@ -123,7 +123,6 @@ module Textus
           textus where KEY
           textus get KEY
           textus put KEY --stdin [--fetch=NAME] --as=ROLE
-          textus freshness [--prefix=KEY] [--zone=Z]
           textus fetch KEY
           textus fetch all [--prefix=KEY] [--zone=Z]
           textus audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]

data/lib/textus/manifest/entry/base.rb

@@ -42,6 +42,7 @@ module Textus
         # without `respond_to?` guards.
         def template       = nil
         def inject_boot    = false # rubocop:disable Naming/PredicateMethod
+        def provenance     = true  # rubocop:disable Naming/PredicateMethod
         def events         = {}
         def publish_tree   = nil
         def ignore         = []

data/lib/textus/manifest/entry/derived.rb

@@ -5,13 +5,14 @@ module Textus
         Projection = ::Data.define(:select, :pluck, :sort_by, :transform)
         External   = ::Data.define(:sources, :command)
 
-        attr_reader :source, :template, :inject_boot, :events
+        attr_reader :source, :template, :inject_boot, :provenance, :events
 
-        def initialize(source:, template: nil, inject_boot: false, events: {}, **rest)
+        def initialize(source:, template: nil, inject_boot: false, provenance: true, events: {}, **rest)
           super(**rest)
           @source = source
           @template = template
           @inject_boot = inject_boot
+          @provenance = provenance
           @events = events || {}
         end
 
@@ -53,6 +54,7 @@ module Textus
             source: source,
             template: raw["template"],
             inject_boot: raw["inject_boot"] == true,
+            provenance: raw.fetch("provenance", true) != false,
             events: raw["events"] || {},
             **common,
           )

data/lib/textus/manifest/schema.rb

@@ -25,7 +25,7 @@ module Textus
       ENTRY_KEYS = %w[
         key path zone kind schema owner nested format
         compute template publish
-        intake events inject_boot ignore tracked
+        intake events inject_boot provenance ignore tracked
       ].freeze
       # ADR 0052: the typed publish block — `publish: { to: [...] }` (file
       # fan-out) xor `publish: { tree: "dir" }` (subtree mirror).

data/lib/textus/mcp/server.rb

@@ -89,12 +89,19 @@ module Textus
           return
         end
 
-        @session.check_etag!(contract_etag)
-
         name = params["name"]
         args = params["arguments"] || {}
+
+        # ADR 0083: the contract-drift guard gates mutating verbs — every MCP
+        # verb that is NOT a pure read (Write:: + the destructive Maintenance::
+        # verbs tend/zone_mv/key_*_prefix). Reads and boot bypass it (a stale
+        # read returns on-disk truth; boot re-orients). Keying on read_verbs
+        # (not write_verbs) keeps the destructive Maintenance:: verbs gated.
+        @session.check_etag!(contract_etag) unless Catalog.read_verbs.include?(name)
+
         result = Catalog.call(name, session: @session, store: @store, args: args)
         @session = @session.advance_cursor(@store.audit_log.latest_seq) if name == "pulse"
+        @session = @session.with(contract_etag: contract_etag) if name == "boot"
 
         emit_result(rid, {
                       "content" => [{ "type" => "text", "text" => JSON.dump(result) }],

data/lib/textus/read/boot.rb

@@ -10,14 +10,16 @@ module Textus
       verb     :boot
       summary  "Return the orientation contract: zones, entries, schemas, write_flows, agent_quickstart."
       surfaces :cli, :mcp
+      arg :lean, :boolean,
+          description: "return only orientation essentials (zones, agent_quickstart, contract_etag) for cheap session-start injection"
 
       def initialize(container:, call:)
         @container = container
         @call      = call
       end
 
-      def call
-        Textus::Boot.build(container: @container)
+      def call(lean: false)
+        Textus::Boot.build(container: @container, lean: lean)
       end
     end
   end

data/lib/textus/read/freshness.rb

@@ -2,20 +2,24 @@ require "time"
 
 module Textus
   module Read
-    # Per-entry lifecycle report (ADR 0079). Walks every entry declared in the
-    # manifest, consults `rules.for(key)` for a `lifecycle:` policy, and reports
-    # the unified verdict. Status is one of :fresh, :expired, or :no_policy; the
-    # row also carries the policy's :action (on_expire).
+    # Per-entry lifecycle scan (ADR 0079, 0085). Walks every entry declared in
+    # the manifest, consults `rules.for(key)` for a `lifecycle:` policy, and
+    # reports the unified verdict. Status is one of :fresh, :expired, or
+    # :no_policy; the row also carries the policy's :action (on_expire).
+    #
+    # ADR 0085 removed the public `freshness` verb: there is no `:cli`/`:mcp`
+    # surface. This is now a Ruby-only internal scan (empty `surfaces`, the
+    # honest home reserved by ADR 0073) consumed by `pulse` (which derives
+    # `stale` + `next_due_at` from it) and the hook `Context`. Humans drill
+    # into per-entry lifecycle detail via `get` (last_fetched_at) + `rule_explain`
+    # (the ttl / on_expire policy) instead of a dedicated verb.
     class Freshness
       extend Textus::Contract::DSL
 
       verb     :freshness
-      summary  "Report the fetch-freshness status of every entry with a fetch policy."
-      surfaces :cli
-      cli      "freshness"
+      summary  "Internal per-entry lifecycle scan (status, age, ttl, on_expire); backs pulse + hook context. No public surface (ADR 0085)."
       arg :prefix, String, required: false, description: "filter to keys with this prefix"
       arg :zone,   String, required: false, description: "filter to entries in this zone"
-      view(:cli) { |rows| { "verb" => "freshness", "rows" => rows } }
 
       def initialize(container:, call:)
         @container  = container

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.49.0"
+  VERSION = "0.50.0"
   PROTOCOL = "textus/3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.49.0
+  version: 0.50.0
 platform: ruby
 authors:
 - Patrick