textus 0.35.1 → 0.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3e6ac596658c63369ce977d194a2c43d0a789cdfa97b04d100b70e572165e63
-  data.tar.gz: c3ed7085fa38777fdc6e8a38e8c4c8f4a51ce113065f24b42f596aa220acb9f3
+  metadata.gz: 020c9cf77e098bd7099a5cd0871801b40d7be8266b2942c8ddb6cfed60c85af0
+  data.tar.gz: d4bfacdf7f6049df88e37b53e24ff4927f4bfd20f3d0ff55d5ed4d54ecbfb1fd
 SHA512:
-  metadata.gz: a95c23aaf19216505f272f0262b66e1e7a3e01b3e78a2b8062ab827a3c8109a6d085348b3e1b1e664a41f0bbdeaf46cf736b47fe211495905445c9ae283c88fa
-  data.tar.gz: 453327b6cea08e0102e76dd22723d6f77a69d10f8d6810427e23934956d5a332b5f9d33b81d568bf7529cf8ab83bdfb6b323b447d2d9dead6d06c2b703e66ac4
+  metadata.gz: aefe80bba5a38c4db29fe663cf3f41c77229075cc5b02b95b9fac0c8df62b81aed936bef95dd610becb6c700238936ddd8dd528762dae576747552ab4e9acbac
+  data.tar.gz: 6d342cad8cb4dd0d3f320990c45ca0c4a996e5499dafd9c90f72b53731d53294f57b8dea2b4c625d96e43245da2138f3df8971d9ba416940cdc59a390754f577

data/CHANGELOG.md

@@ -9,7 +9,115 @@ 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.35.1 — 2026-05-31 — RSpec foundation consolidation (test-only)
+## Unreleased
+
+## 0.38.0 — 2026-05-31 — MCP serve acts as agent by default ([ADR 0040](docs/architecture/decisions/0040-mcp-connection-role-and-two-channels.md))
+
+No `textus/3` wire-format change; no manifest-schema change.
+
+### Changed
+
+- **The MCP connection acts as the `agent` role by default (ADR 0040).**
+  `textus mcp serve` now resolves its acting role through the standard chain
+  (`--as` → `TEXTUS_ROLE` → `.textus/role`) with an `agent` transport default,
+  instead of silently inheriting the global `human` default. The agent channel
+  proposes; human authority (accept/reject, direct writes) is exercised through
+  the human's own CLI.
+
+### Breaking
+
+- **MCP writes that relied on human authority now require `propose` + `accept`,
+  or an explicit `--as=human`.** A connection that previously `put` straight into
+  `working/`/`identity/` over MCP will get `write_forbidden`. Launch
+  `textus mcp serve --as=human` (or set `TEXTUS_ROLE`/`.textus/role`) to restore
+  the old behavior knowingly; the gate is then advisory.
+
+## 0.37.0 — 2026-05-31 — MCP catalog derive-or-guard ([ADR 0039](docs/architecture/decisions/0039-mcp-catalog-derive-or-guard.md))
+
+No `textus/3` wire-format change; no manifest-schema change.
+
+### Changed
+
+- **MCP catalog is now derived from one per-verb contract (ADR 0039).** Each
+  use-case declares its interface once (`verb`/`summary`/`surfaces`/`arg`/`response`);
+  the MCP `tools/list` schemas and `tools/call` dispatch are generated from it.
+  The hand-written `Tools::REGISTRY` and `ToolSchemas` array are gone — a core
+  interface change can no longer leave MCP silently stale (it is derived, or a
+  guard spec fails the build).
+
+### Added
+
+- **`propose` and `rules` are first-class verbs** (Ruby/MCP; `propose` also CLI),
+  no longer MCP-only composed tools. MCP is now a pure projection of the core
+  verb set filtered by `surfaces(:mcp)`.
+
+### Removed
+
+- **Examples consolidated to a single reference.** Removed `examples/hello/` and
+  `examples/claude-plugin/`, keeping `examples/project/` as the one worked example —
+  the role gate (propose → accept), build/publish to `CLAUDE.md`/`AGENTS.md`, schemas,
+  a template, and a `:transform_rows` hook in one place. The `skill_fanout` recipe
+  sidecar, its spec, and the `docs/recipes/` page that existed only to document it are
+  removed alongside. All living docs and `boot`'s `docs.example` now point at
+  `examples/project/`.
+
+### Breaking
+
+- **MCP `schema` tool is keyed by entry `key`, not `family`.** It routes through
+  the `schema` (SchemaEnvelope) verb. Callers passing `{ "family": "..." }` must
+  pass `{ "key": "..." }` instead.
+- **The dispatcher verb `schema_envelope` is renamed `schema`.** Ruby callers
+  using `store.as(role).schema_envelope(key)` must use `store.as(role).schema(key)`.
+
+## 0.36.0 — 2026-05-31 — Transports as pure framings: one verb vocabulary, one session, lifted to core ([ADR 0036](docs/architecture/decisions/0036-transports-as-pure-framings.md))
+
+No `textus/3` wire-format change; no manifest-schema change.
+
+### Changed (BREAKING)
+
+- **MCP tool names aligned with the CLI/Ruby verb vocabulary.** The five renamed tools adopt
+  the canonical core names: `tick`→`pulse`, `find`→`list`, `read`→`get`, `write`→`put`,
+  `fetch_stale`→`fetch_all`. The `textus/3` wire format is unchanged; agents that discover
+  tools via `tools/list` (the documented pattern) adapt automatically. Hardcoded tool names
+  in `.mcp.json` files, prompts, or scripts must be updated.
+
+### Added
+
+- **First-class CLI `propose` verb** — `textus propose KEY --as=ROLE [--stdin]` auto-prefixes
+  the manifest's `propose_zone`, matching what the MCP `propose` tool has always done. The
+  previous workaround (`textus put proposals.KEY --as=ROLE`) still works but the caller no
+  longer needs to know the queue zone name.
+- **Stateful `textus pulse` (no `--since`)** — when `--since` is omitted, `pulse` reads and
+  updates a per-role cursor from `.textus/.state/cursor.<role>` (gitignored). Successive
+  invocations see only what changed since the last look, without hand-tracking a sequence
+  number. `--since=N` remains the explicit, stateless override.
+- **`Textus::Session`** — the agent session (role + cursor + propose_zone + manifest_etag,
+  with cursor-advance, `ContractDrift` / `CursorExpired` detection) is now a core value
+  object, not MCP-internal state. `MCP::Session` is now an alias to it.
+- **`Store#session(role:)`** — returns a `Textus::Session` for Ruby embedders; the
+  documented Ruby agent loop uses it instead of hand-tracking `since:`.
+
+## 0.35.2 — 2026-05-31 — Evaluation field rename + Container doc fix (internal)
+
+No `textus/3` wire-format change; no manifest-schema change; no library behavior
+change. Internal refactor and documentation correction only.
+
+### Changed
+
+- `Domain::Policy::Evaluation` now names its manifest member `manifest` directly
+  instead of declaring it `snapshot` and exposing it through a `def manifest =
+  snapshot` alias. Every predicate already read `eval.manifest`; the field now
+  matches its only call name.
+- Dropped the unused `def role = actor` alias on `Evaluation` (zero readers; the
+  real field `actor` is used everywhere).
+
+### Fixed
+
+- Architecture doc (`docs/architecture/README.md`) listed an `:authorizer` member
+  on `Container` that the code does not have. Removed it so the doc matches
+  `lib/textus/container.rb` (7 fields).
+
+
 
 No `textus/3` wire-format change; no manifest-schema change; no library behavior change.
 Test-suite maintenance only.

data/README.md

@@ -8,6 +8,7 @@
 <p align="center">
   <a href="https://github.com/patrick204nqh/textus/actions/workflows/ci.yml"><img src="https://github.com/patrick204nqh/textus/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://rubygems.org/gems/textus"><img src="https://img.shields.io/gem/v/textus.svg" alt="Gem Version"></a>
+  <a href="https://rubygems.org/gems/textus"><img src="https://img.shields.io/gem/dt/textus.svg" alt="Gem Downloads"></a>
   <a href="https://www.ruby-lang.org/"><img src="https://img.shields.io/badge/ruby-%E2%89%A53.3-CC342D.svg" alt="Ruby"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
 </p>
@@ -66,10 +67,8 @@ Try the gate the other way (`textus put knowledge.notes.X --as=agent`) and you g
 
 ## Try it
 
-- **5-command worked demo** — single terminal scroll, no MCP, no schemas: [`examples/hello/`](examples/hello/)
+- **Worked end-to-end store** — the role gate (propose → accept), build/publish (`CLAUDE.md` / `AGENTS.md` generated from knowledge entries), schemas, templates, and a hook: [`examples/project/`](examples/project/)
 - **Wire textus into Claude Code via MCP** — 4 steps, ~5 minutes: [`docs/agents-mcp.md`](docs/agents-mcp.md)
-- **Use textus as your own project's context store**: [`examples/project/`](examples/project/)
-- **Use textus to author a Claude plugin** (textus is the source-of-truth, build publishes to `agents/`, `skills/`, `commands/`): [`examples/claude-plugin/`](examples/claude-plugin/)
 
 ## Protocol, not just a gem
 
@@ -144,7 +143,7 @@ textus audit --limit=20              # query the audit log
 
 (All verbs return JSON envelopes by default; pass `--output=json` explicitly if you prefer.)
 
-For the full shape — Claude plugin with agents, skills, commands, pending walkthrough, intake action — see [`examples/claude-plugin/`](examples/claude-plugin/).
+For a worked store — knowledge entries, a staged proposal, schemas, a template, and a build that publishes `CLAUDE.md` / `AGENTS.md` — see [`examples/project/`](examples/project/).
 
 ## What's shipped
 
@@ -152,7 +151,7 @@ For the full shape — Claude plugin with agents, skills, commands, pending walk
 - **Stable identity.** Auto-minted `uid:` survives writes and `textus key mv`; reorganising never breaks references.
 - **Capability × zone-kind gate.** Writes carry `--as=<role>`; a role may write a zone iff it holds the capability the zone's `kind:` requires (`canon`→`author`, `workspace`→`keep`, `quarantine`→`fetch`, `queue`→`propose`, `derived`→`build`). The wrong role gets `write_forbidden` naming the capability needed and the roles that hold it. ([SPEC §5](SPEC.md))
 - **Agent loop.** `textus boot` orients a fresh session; `textus pulse --since=N` is the per-turn heartbeat (changed entries, stale keys, pending proposals). ([docs/agents-mcp.md](docs/agents-mcp.md))
-- **`textus doctor`.** 15 health checks across schemas, hooks, keys, sentinels, and the audit log.
+- **`textus doctor`.** Health checks across schemas, hooks, keys, sentinels, and the audit log.
 
 ## CLI and zones
 
@@ -218,7 +217,7 @@ See [`docs/agents-mcp.md`](docs/agents-mcp.md) for the agent boot → pulse loop
 
 ## Examples
 
-[`examples/claude-plugin/`](examples/claude-plugin/) — a Claude Code plugin (`voice-tools`) whose entire content surface — agents, skills, commands, `CLAUDE.md`, `plugin.json`, `marketplace.json` — is textus-managed. Demonstrates per-entry formats, `publish_each`, intake actions, in-process transforms and hooks, the agent-propose / human-accept loop, and the `inject_boot:` flag that puts an orientation preamble at the top of `CLAUDE.md`.
+[`examples/project/`](examples/project/) — textus as a project's own context store (a fictional Rails service, `ledger`). Human-authored `knowledge/` (project facts, runbooks), a staged ADR in `proposals/` showing the agent-propose / human-accept loop, schemas validating each family, a mustache template plus a `:transform_rows` hook, and a `build` that publishes the `artifacts/orientation` projection to `CLAUDE.md` and `AGENTS.md`. Includes a copy-paste adoption recipe for your own repo.
 
 ## Tests
 
@@ -226,7 +225,7 @@ See [`docs/agents-mcp.md`](docs/agents-mcp.md) for the agent boot → pulse loop
 bundle exec rspec
 ```
 
-~920 examples; includes conformance fixtures A–I from SPEC §12.
+Includes conformance fixtures A–I from SPEC §12.
 
 ## Code quality
 
@@ -239,4 +238,4 @@ Lefthook hooks (`brew bundle install` then `lefthook install`) run rubocop on `p
 
 ## License
 
-MIT.
+[MIT](LICENSE).

data/SPEC.md

@@ -896,11 +896,14 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 | `boot [--output=json]` | read | any |
 | `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 |
 | `fetch KEY --as=automation` | write | `fetch`-holder (typically `automation`) |
 | `fetch stale [--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`) |
+| `reject K --as=human` | write | `author`-holder (typically `human`) |
 | `init` | write | `human` |
 | `schema {show,init,diff,migrate}` | read/write | `human` for writes |
 | `key mv OLD NEW [--as=R] [--dry-run]` | write | per zone (same-zone only) |
@@ -930,11 +933,14 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
   "changed":        [ { "seq": 1843, "key": "knowledge.notes.x", "verb": "put", "role": "human", "ts": "..." } ],
   "stale":          [ "artifacts.marketplace" ],
   "pending_review": [ "proposals.proposal.123" ],
-  "doctor":         { "ok": true, "warn": 0, "fail": 0 }
+  "doctor":         { "ok": true, "warn": 0, "fail": 0 },
+  "manifest_etag":  "sha256:1f3a…",
+  "next_due_at":    "2026-06-01T09:00:00Z",
+  "hook_errors":    [ { "seq": 1844, "event": "after_put", "hook": "notify", "key": "knowledge.notes.x", "error_class": "Timeout::Error", "error_message": "…", "at": "..." } ]
 }
 ```
 
-`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. 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 sourced from `freshness`. `pending_review` lists all keys in the queue zone. `doctor` is an `{ok, warn, fail}` count summary. `manifest_etag` is the `sha256:`-prefixed content hash of the manifest (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`.
 
 **`put` input** (read from stdin when `--stdin` is given):
 

data/docs/conventions.md

@@ -1,7 +1,7 @@
 # Conventions
 
 > **Reference** · for integrators · **read when** you're shaping a `.textus/` tree and want the idiomatic choices
-> **SSoT for** idiomatic key naming, schema design, and automation integration · **reviewed** 2026-05 (v0.31)
+> **SSoT for** idiomatic key naming, schema design, and automation integration · **reviewed** 2026-05 (v0.35)
 
 Guidelines for shaping a `.textus/` tree, naming keys, organising schemas, and integrating with build automation. The spec ([`../SPEC.md`](../SPEC.md)) defines what's enforceable; this document captures what's *idiomatic*.
 

data/lib/textus/boot.rb

@@ -71,32 +71,52 @@ module Textus
       },
     }.freeze
 
-    # The CLI verb catalog. Truth lives here; do not derive dynamically.
-    # Agents that read boot should see a stable shape regardless of how
-    # verb implementations evolve.
-    CLI_VERBS = [
-      { "name" => "boot",     "summary" => "this output — orientation for agents and tools" },
-      { "name" => "list",     "summary" => "enumerate keys (optional --prefix)" },
-      { "name" => "get",      "summary" => "read an entry; envelope with _meta, body, uid, etag" },
-      { "name" => "where",    "summary" => "resolve a key to its zone and path without reading" },
-      { "name" => "schema",   "summary" => "field shape for a key family" },
-      { "name" => "put",      "summary" => "write an entry; --as=<role>, --stdin payload" },
+    # 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_CLI_VERBS = [
+      { "name" => "boot" },
+      { "name" => "list" },
+      { "name" => "get" },
+      { "name" => "where", "summary" => "resolve a key to its zone and path without reading" },
+      { "name" => "schema" },
+      { "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" => "build",    "summary" => "materialize derived entries; publish_to and publish_each fan out copies" },
-      { "name" => "fetch", "summary" => "run an action for a quarantine entry" },
+      { "name" => "fetch" },
       { "name" => "freshness", "summary" => "per-entry freshness report (status, age, ttl, on_stale)" },
-      { "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" => "pulse",
-        "summary" => "delta since cursor — changed entries, stale, pending proposals, doctor summary" },
+      { "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" => "pulse" },
     ].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] }
+
+      CURATED_CLI_VERBS.map do |entry|
+        derived = by_contract[entry["name"]]
+        if derived
+          entry.merge("summary" => derived)
+        else
+          entry
+        end
+      end
+    end
+
     def self.agent_quickstart(manifest, audit_log)
       agent_role = manifest.policy.proposer_role
 
@@ -158,7 +178,7 @@ module Textus
         "recipes" => recipes(manifest),
         "role_resolution" => {
           "summary" => "write role is resolved in order: --as flag, TEXTUS_ROLE env var, .textus/role file, " \
-                       "default 'human'",
+                       "then a transport default ('human' for CLI, 'agent' for MCP)",
           "roles" => manifest.data.role_caps.keys,
           "ref" => "SPEC.md §5",
         },
@@ -177,7 +197,7 @@ module Textus
         "cli_verbs" => CLI_VERBS.map(&:dup),
         "agent_protocol" => agent_protocol(manifest),
         "agent_quickstart" => agent_quickstart(manifest, container.audit_log),
-        "docs" => { "spec" => "SPEC.md", "example" => "examples/claude-plugin/" },
+        "docs" => { "spec" => "SPEC.md", "example" => "examples/project/" },
       }
     end
 

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

@@ -1,14 +1,19 @@
 module Textus
   class CLI
     class Verb
-      # Launches the MCP stdio server in the current process. Blocks on
-      # stdin; never returns until stdin closes.
+      # Launches the MCP stdio server in the current process. Blocks on stdin;
+      # never returns until stdin closes. The connection acts as the `agent`
+      # role by default (ADR 0040): the agent channel proposes, it does not
+      # inherit the human's authority. Override per connection with --as, or
+      # TEXTUS_ROLE / .textus/role (same chain as every other verb).
       class MCPServe < Verb
         command_name "serve"
         parent_group Group::MCP
+        option :as_flag, "--as=ROLE"
 
         def call(store)
-          Textus::MCP::Server.new(store: store, stdin: @stdin, stdout: @stdout).run
+          role = resolved_role(store, default: Textus::Role::AGENT)
+          Textus::MCP::Server.new(store: store, stdin: @stdin, stdout: @stdout, role: role).run
           0
         end
       end

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

@@ -0,0 +1,28 @@
+module Textus
+  class CLI
+    class Verb
+      # Queue a proposal. Mirrors the MCP `propose` tool: resolves the
+      # manifest's propose_zone and prefixes the key, so the author does not
+      # need to know the queue zone's name. ADR 0036.
+      class Propose < Verb
+        command_name "propose"
+
+        option :as_flag, "--as=ROLE"
+        option :use_stdin, "--stdin"
+
+        def call(store)
+          rel = positional.shift or raise UsageError.new("propose requires a key")
+          raise UsageError.new("propose requires --stdin") unless use_stdin
+
+          payload = JSON.parse(@stdin.read)
+          env = store.as(resolved_role(store)).propose(
+            rel,
+            meta: payload["_meta"] || {},
+            body: payload["body"] || "",
+          )
+          emit(env.to_h_for_wire)
+        end
+      end
+    end
+  end
+end

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

@@ -4,12 +4,21 @@ module Textus
       class Pulse < Verb
         command_name "pulse"
 
+        option :as_flag, "--as=ROLE"
         option :since, "--since=N"
 
         def call(store)
-          ops = session_for(store)
-          since_n = (since || "0").to_i
-          emit(ops.pulse(since: since_n))
+          role = resolved_role(store)
+          ops = store.as(role)
+
+          if since
+            emit(ops.pulse(since: since.to_i))
+          else
+            cursors = Textus::CursorStore.new(root: store.root, role: role)
+            result = ops.pulse(since: cursors.read)
+            cursors.write(result["cursor"])
+            emit(result)
+          end
         end
       end
     end

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

@@ -7,7 +7,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("schema requires a key")
-          emit(session_for(store).schema_envelope(key))
+          emit(session_for(store).schema(key))
         end
       end
     end

data/lib/textus/cli/verb.rb

@@ -91,9 +91,10 @@ module Textus
 
       # Resolves the active role for this invocation. Honors the verb's
       # `--as` flag if declared, then TEXTUS_ROLE, then the project default.
-      def resolved_role(store)
+      # Pass `default:` to override the fallback (e.g. MCPServe uses AGENT).
+      def resolved_role(store, default: Role::DEFAULT)
         flag = respond_to?(:as_flag) ? as_flag : nil
-        Role.resolve(flag: flag, env: ENV, root: store.root)
+        Role.resolve(flag: flag, env: ENV, root: store.root, default: default)
       end
 
       # Returns a Call value bound to the resolved role. Convenience for

data/lib/textus/contract.rb

@@ -0,0 +1,106 @@
+module Textus
+  # Declarative, co-located interface contract for a verb. One source of truth
+  # for the agent-facing summary, the argument schema, which transports expose
+  # the verb, and how the return value is shaped for the wire. CLI/Ruby/MCP and
+  # boot project from this; the MCP catalog is fully derived from it (ADR 0039).
+  module Contract
+    # One argument of a verb. `positional: true` means it is passed to the
+    # use-case as a positional (e.g. `get(key)`); otherwise as a keyword.
+    # `session_default` names a zero-arg method on `Textus::Session` (Symbol)
+    # that supplies the value when the wire arg is absent; `nil` means no default.
+    Arg = Data.define(:name, :type, :required, :positional, :session_default, :description)
+
+    JSON_TYPES = {
+      String => "string", Integer => "integer", Hash => "object",
+      Array => "array", :boolean => "boolean"
+    }.freeze
+
+    def self.json_type(type)
+      JSON_TYPES.fetch(type) { raise ArgumentError.new("no JSON type mapping for #{type.inspect}") }
+    end
+
+    Spec = Data.define(:verb, :summary, :args, :surfaces, :response) do
+      def mcp? = surfaces.include?(:mcp)
+
+      def required_args = args.select(&:required)
+
+      # JSON-Schema object for MCP tools/list inputSchema.
+      # Outer keys (:type, :properties, :required) are symbols; inner property
+      # keys are strings — matches the MCP/JSON wire shape expected by clients.
+      def input_schema
+        props = args.to_h do |a|
+          h = { "type" => Contract.json_type(a.type) }
+          h["description"] = a.description if a.description
+          [a.name.to_s, h]
+        end
+        { type: "object", properties: props, required: required_args.map { |a| a.name.to_s } }
+      end
+    end
+
+    # Mixed onto a use-case class via `extend`. Calls accumulate into ivars,
+    # frozen into a Spec on first read of `.contract`.
+    module DSL
+      def verb(name = nil)
+        if name
+          raise "contract already built; declare verb before reading .contract" if defined?(@__contract) && @__contract
+
+          @__verb = name
+        else
+          @__verb
+        end
+      end
+
+      def summary(text = nil)
+        if text
+          raise "contract already built; declare summary before reading .contract" if defined?(@__contract) && @__contract
+
+          @__summary = text
+        else
+          @__summary
+        end
+      end
+
+      def surfaces(*list)
+        if list.empty?
+          @__surfaces ||= []
+        else
+          raise "contract already built; declare surfaces before reading .contract" if defined?(@__contract) && @__contract
+
+          @__surfaces = list
+        end
+      end
+
+      def arg(name, type, required: false, positional: false, session_default: nil, description: nil)
+        raise "contract already built; declare args before reading .contract" if defined?(@__contract) && @__contract
+
+        (@__args ||= []) << Arg.new(
+          name: name, type: type, required: required,
+          positional: positional, session_default: session_default, description: description
+        )
+      end
+
+      def response(&blk)
+        @__response = blk if blk
+        @__response || ->(v) { v }
+      end
+
+      def contract?
+        !@__verb.nil?
+      end
+
+      # rubocop:disable Naming/MemoizedInstanceVariableName
+      # @__contract uses double-underscore to match the other accumulator ivars
+      # (@__verb, @__args, etc.) and avoid name collision with user-defined `@contract`.
+      def contract
+        @__contract ||= Spec.new(
+          verb: @__verb,
+          summary: @__summary,
+          args: (@__args || []).freeze,
+          surfaces: (@__surfaces || []).freeze,
+          response: response,
+        )
+      end
+      # rubocop:enable Naming/MemoizedInstanceVariableName
+    end
+  end
+end

data/lib/textus/cursor_store.rb

@@ -0,0 +1,24 @@
+require "fileutils"
+
+module Textus
+  # Per-role cursor cache under <root>/.run/state/cursor.<role>. A convenience so
+  # `textus pulse` (no --since) means "since I last looked". Gitignored;
+  # losing it just re-emits recent deltas, never corrupts the store. ADR 0036/0038.
+  class CursorStore
+    def initialize(root:, role:)
+      @path = Textus::Layout.cursor(root, role)
+    end
+
+    def read
+      Integer(File.read(@path).strip)
+    rescue Errno::ENOENT, ArgumentError
+      0
+    end
+
+    def write(seq)
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.write(@path, seq.to_s)
+      seq
+    end
+  end
+end

data/lib/textus/dispatcher.rb

@@ -6,6 +6,7 @@ module Textus
     VERBS = {
       # Write
       put: Textus::Write::Put,
+      propose: Textus::Write::Propose,
       delete: Textus::Write::Delete,
       mv: Textus::Write::Mv,
       accept: Textus::Write::Accept,
@@ -30,11 +31,12 @@ module Textus
       pulse: Textus::Read::Pulse,
       policy_explain: Textus::Read::PolicyExplain,
       published: Textus::Read::Published,
-      schema_envelope: Textus::Read::SchemaEnvelope,
+      schema: Textus::Read::SchemaEnvelope,
       validate_all: Textus::Read::ValidateAll,
       doctor: Textus::Read::Doctor,
       boot: Textus::Read::Boot,
       retainable: Textus::Read::Retainable,
+      rules: Textus::Read::Rules,
 
       # Maintenance
       migrate: Textus::Maintenance::Migrate,

data/lib/textus/doctor/check/audit_log.rb

@@ -3,7 +3,7 @@ module Textus
     class Check
       class AuditLog < Check
         def call
-          path = File.join(root, "audit.log")
+          path = Textus::Layout.audit_log(root)
           Textus::Ports::AuditLog.new(root).verify_integrity.map do |v|
             {
               "code" => "audit.parse_error",

data/lib/textus/doctor/check/fetch_locks.rb

@@ -1,7 +1,7 @@
 module Textus
   module Doctor
     class Check
-      # Lists per-key fetch lock files under <root>/.locks/ whose
+      # Lists per-key fetch lock files under <root>/.run/locks/ whose
       # recorded PID is no longer running. These are forensic artifacts only:
       # Fetch::Lock uses flock(2), which the kernel releases on process
       # death, so stale files do not block subsequent acquires. The check
@@ -9,7 +9,7 @@ module Textus
       # (e.g. a fetch path that crashes repeatedly).
       class FetchLocks < Check
         def call
-          dir = File.join(root, ".locks")
+          dir = Textus::Layout.locks(root)
           return [] unless File.directory?(dir)
 
           Dir.glob(File.join(dir, "*.lock")).filter_map { |path| inspect_lock(path) }

data/lib/textus/domain/policy/evaluation.rb

@@ -3,16 +3,13 @@
 module Textus
   module Domain
     module Policy
-      # Immutable context handed to every predicate. `snapshot` is the
+      # Immutable context handed to every predicate. `manifest` is the
       # manifest (pure, no I/O); `envelope` is the entry under evaluation
       # (nil when no bytes exist yet, e.g. a fresh put). `origin`/`target`
       # are dotted keys; `transition` is the verb symbol.
       Evaluation = Data.define(
-        :actor, :transition, :origin, :target, :envelope, :snapshot
-      ) do
-        def manifest = snapshot
-        def role     = actor
-      end
+        :actor, :transition, :origin, :target, :envelope, :manifest
+      )
     end
   end
 end

data/lib/textus/init.rb

@@ -92,6 +92,10 @@ module Textus
       end
       File.write(File.join(target_root, "hooks", "README.md"), HOOKS_README)
       File.write(File.join(target_root, "manifest.yaml"), DEFAULT_MANIFEST)
+      FileUtils.mkdir_p(Textus::Layout.audit_dir(target_root))
+      FileUtils.mkdir_p(Textus::Layout.state(target_root))
+      FileUtils.mkdir_p(Textus::Layout.locks(target_root))
+      File.write(File.join(target_root, ".gitignore"), Textus::Layout::GITIGNORE)
       { "protocol" => PROTOCOL, "initialized" => target_root }
     end
   end