textus 0.43.0 → 0.43.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c2c92f27b720b90f0dfa268174cf9d9ea775b37f92bb38ed90cd9719d7b2626
-  data.tar.gz: f5018ecfd8d72666d48236d42395e44819766659088bc98b1c69ad4fccf2fce8
+  metadata.gz: 2c26661afb6c59f813ccdb737e56666be242a14e3315a100348dd8514a41e78a
+  data.tar.gz: 26ff3e7e8cd94a545cdcabe964c6e8c7311fe0179a24a13b0ab298eab7f2bf34
 SHA512:
-  metadata.gz: 758b3a9da98edb000100e9b6d1665829d94333f53e38f3a68104d33a4aefd831947e235ecb3048e16b388e0256239dfe6f66708d1253b7bfcbb56360a74350bc
-  data.tar.gz: d72be31709261f1aff37f00a9b213e03d8121758f61e781bfdd1626eb16122d994d64491f4c37be4c851031e8bd122d9df8d8abd682228e2693162d3861c865d
+  metadata.gz: db6b8047ba7d7c79ad78a653944709d7cc7cfd5c22a4baae116e97c8d6fea48c409788c835e1c1f83c7684a58da089b08a0525a44791de92875d1d2bb0c26a76
+  data.tar.gz: 26e9d74398110f4d34dd59c837901170e5d80a847268f5edee45010f4793c51e1f47737d5d3c85b0098fa06b1334e00bf1038330a12a1061c9957d045e07638c

data/CHANGELOG.md

@@ -9,6 +9,22 @@ 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.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.
+
+### Fixed
+
+- **`boot.agent_quickstart.read_verbs` had drifted from the MCP catalog ([ADR 0056](docs/architecture/decisions/0056-boot-quickstart-speaks-the-mcp-catalog.md)).** It was a hand-maintained list that advertised CLI-only read verbs an MCP agent cannot call (`audit`, `freshness`, `doctor`) while omitting the ones it can and needs (`schema`, `rules`). It now **derives** from `MCP::Catalog` (`get list pulse schema boot rules`) and is reconciled by a guard spec, so it can no longer advertise an uncallable verb or omit a callable one. This is what led downstream skills to shell out to a CLI for schema discovery instead of calling the `schema` verb.
+
+### Changed
+
+- **`boot.agent_protocol.recipes` reference verbs, not CLI strings ([ADR 0056](docs/architecture/decisions/0056-boot-quickstart-speaks-the-mcp-catalog.md)).** Each recipe step names a verb (`get KEY`, `schema KEY`, `put KEY`, `propose KEY`, `fetch_all`) or a plain build step, instead of a `textus …` / `echo … | textus …` shell line — each transport frames the verb itself (CLI vs MCP tool). Keeps shell syntax out of the surface an MCP agent reads. `human_steps` still name `accept` (the author-only transition, not an MCP tool, by design).
+
+### Added
+
+- **ADR 0054 (Proposed, no implementation): entry-level `desc`.** Records the decision to add an optional one-line `desc:` to manifest entries — surfaced in `boot.entries`/`list` — turning the manifest into a navigable index so an agent finds the right data without a caller hardcoding the key. Pre-registers ADR 0055 (a `find`/search verb) as the evidence-triggered follow-up. Documentation only in this release.
+
 ## 0.43.0 — 2026-06-02 — Typed `publish:` block + remove `index_filename` ([ADR 0052](docs/architecture/decisions/0052-typed-publish-block.md), [0053](docs/architecture/decisions/0053-remove-index-filename.md))
 
 No `textus/3` wire-format change. Two breaking (pre-1.0) changes on the publish/enumeration surface: the two top-level publish keys become one typed `publish:` block, and the unused `index_filename:` enumeration feature is removed. Both fail at load with a migration-pointing message.

data/SPEC.md

@@ -197,14 +197,14 @@ entries:
     path: knowledge/network/org
     zone: knowledge
     schema: person
-    owner: textus:network
+    owner: human:network
     nested: true
 
   - key: artifacts.catalogs.people
     path: artifacts/catalogs/people.md
     zone: artifacts
     schema: null
-    owner: textus:build
+    owner: automation:build
 
 rules:
   - match: feeds.**
@@ -404,7 +404,7 @@ A derived entry that is produced by a build tool *outside* textus — `rake`, `j
 - key: output.catalogs.skills
   path: output/catalogs/skills.md
   zone: output
-  owner: build:catalog-skills
+  owner: automation:catalog-skills
   compute:
     kind: external
     command: "rake catalog:skills"   # informational; external automation invokes it
@@ -800,7 +800,7 @@ Every successful CLI response (`--output=json`) is a single JSON envelope:
   "protocol": "textus/3",
   "key": "knowledge.network.org.jane",
   "zone": "knowledge",
-  "owner": "textus:network",
+  "owner": "human:network",
   "path": "/absolute/path/to/.textus/zones/knowledge/network/org/jane.md",
   "format": "markdown",
   "_meta": { "name": "jane", "relationship": "peer", "org": "acme" },
@@ -898,7 +898,7 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 ```json
 {
   "agent_quickstart": {
-    "read_verbs":     ["boot", "get", "list", "audit", "pulse", "freshness", "doctor"],
+    "read_verbs":     ["get", "list", "pulse", "schema", "boot", "rules"],
     "write_verbs":    ["put KEY --as=agent --stdin"],
     "writable_zones": ["proposals"],
     "propose_zone":   "proposals",
@@ -907,6 +907,8 @@ 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.
+
 `latest_seq` is the current high-water mark of the audit log; agents should use it as the starting cursor for `pulse`.
 
 **`textus pulse` output shape:**

data/docs/architecture/README.md

@@ -1,7 +1,7 @@
 # Textus architecture
 
 > **Explanation** · for contributors · **read this first** for orientation before SPEC
-> **SSoT for** the Ruby implementation layout (layers, container, ports, read/write/fetch paths) · **reviewed** 2026-05 (v0.35)
+> **SSoT for** the Ruby implementation layout (layers, container, ports, read/write/fetch paths) · **reviewed** 2026-06 (v0.43)
 
 ```mermaid
 flowchart TD

data/docs/reference/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.35)
+> **SSoT for** idiomatic key naming, schema design, and automation integration · **reviewed** 2026-06 (v0.43)
 
 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*.
 
@@ -39,11 +39,11 @@ Inside `knowledge/`, group by **domain** (identity, people, projects, decisions,
 
 ## Owner strings
 
-The `owner:` field in the manifest is **advisory metadata**, not an ACL. Use it to label *who's expected to write here*:
+The `owner:` field in the manifest is **advisory metadata**, not an ACL. Use it to label *who's expected to write here*. The form is `<archetype>` or `<archetype>:<subject>`; the archetype must be one of `human`, `agent`, `automation` (validated at load — ADR 0045), and the subject is free-form:
 
-- `textus:network` — humans curate
+- `human:network` — humans curate
 - `agent:planner` — a specific named agent
-- `build:catalog-skills` — a specific build job
+- `automation:catalog-skills` — a specific build job
 
 Tooling around `git blame` or audit logs may filter on owner; the gem itself only echoes it back in envelopes.
 
@@ -58,7 +58,7 @@ A derived entry declares a `compute:` block with a `kind:` discriminator. Two ki
   path: artifacts/catalogs/people.md
   zone: artifacts
   schema: null
-  owner: build:catalog-people
+  owner: automation:catalog-people
   compute:
     kind: projection
     select: knowledge.network.org   # prefix or list of prefixes
@@ -75,7 +75,7 @@ A derived entry declares a `compute:` block with a `kind:` discriminator. Two ki
 - key: artifacts.catalogs.skills
   path: artifacts/catalogs/skills.md
   zone: artifacts
-  owner: build:catalog-skills
+  owner: automation:catalog-skills
   compute:
     kind: external
     command: "rake catalog:skills"   # informational; the automation invokes it
@@ -106,7 +106,7 @@ rules:
 A typical scheduled-fetch integration shells the `fetch stale` sweep itself:
 
 ```sh
-textus fetch stale --zone=intake --as=automation   # in cron / CI
+textus fetch stale --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.
@@ -137,7 +137,7 @@ For multi-writer environments, **always pass `if_etag`** on `put`. The gem treat
 The application layer is organised around three shapes — `Manifest` as a composition record, a single `Container` capability record handed to every use case, and a split envelope reader/writer. See [ADR 0018](../architecture/decisions/0018-manifest-carving.md), [ADR 0017](../architecture/decisions/0017-envelope-io-split.md), [ADR 0022](../architecture/decisions/0022-container-call-dispatcher.md), and [ADR 0023](../architecture/decisions/0023-uniform-use-case-shape.md).
 
 - **`Manifest` is a composition record** (`Data.define(:data, :resolver, :policy, :rules)`). Reach individual concerns through the field accessors: `manifest.data.entries`, `manifest.policy.permission_for(zone)`, `manifest.resolver.resolve(key)`, `manifest.rules.for(key)`.
-- **Use cases are plain `(container:, call:)` classes.** Each is a single class under `lib/textus/{read,write,maintenance}/` with `def initialize(container:, call:)` and a `#call(...)` method; verbs are looked up in the static `Textus::Dispatcher::VERBS` table. `Container` is a `Data.define` record bundling the wired ports + manifest (`manifest`, `file_store`, `schemas`, `root`, `audit_log`, `events`, `rpc`, `authorizer`); `Call` is the immutable per-invocation value (`role`, `correlation_id`, `now`, `dry_run`). A use case that emits events derives its `Hooks::Context` from `(container, call)` — nothing is injected. Use cases pull only what they need into ivars; nobody passes the raw `Store` around the application layer. `store.as(role)` returns a `RoleScope` that forwards verbs to the dispatcher.
+- **Use cases are plain `(container:, call:)` classes.** Each is a single class under `lib/textus/{read,write,maintenance}/` with `def initialize(container:, call:)` and a `#call(...)` method; verbs are looked up in the static `Textus::Dispatcher::VERBS` table. `Container` is a `Data.define` record bundling the wired ports + manifest (`manifest`, `file_store`, `schemas`, `root`, `audit_log`, `events`, `rpc`); `Call` is the immutable per-invocation value (`role`, `correlation_id`, `now`, `dry_run`). A use case that emits events derives its `Hooks::Context` from `(container, call)` — nothing is injected. Use cases pull only what they need into ivars; nobody passes the raw `Store` around the application layer. `store.as(role)` returns a `RoleScope` that forwards verbs to the dispatcher.
 - **Write path is split**: `Envelope::IO::Reader` owns read/parse (existing-uid lookup, raw read, parse), and `Envelope::IO::Writer` owns put/delete/move + the audit-append invariant (every public method's final action is `@audit_log.append(...)`).
 
 The user-facing CLI surface, the wire envelope shape, and the protocol version (`textus/3`) are unchanged.

data/lib/textus/boot.rb

@@ -127,7 +127,10 @@ module Textus
       propose_zone = manifest.policy.propose_zone_for(agent_role)
 
       {
-        "read_verbs" => %w[boot get list audit pulse freshness doctor],
+        # 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).
+        "read_verbs" => Textus::MCP::Catalog.read_verbs,
         "write_verbs" => agent_role ? ["put KEY --as=#{agent_role} --stdin"] : [],
         "writable_zones" => writable_zones,
         "propose_zone" => propose_zone,
@@ -135,6 +138,10 @@ module Textus
       }
     end
 
+    # Recipes reference verbs, not a transport's CLI strings (ADR 0056): every
+    # step names a verb the agent can call (each transport frames it — CLI as
+    # `textus get KEY`, MCP as the `get` tool) or is a plain build step. This
+    # keeps shell lines out of the surface an MCP agent reads.
     def self.recipes(manifest)
       queue = manifest.policy.queue_zone
       feeds = zone_label(manifest, :quarantine, "the quarantine zone")
@@ -142,32 +149,32 @@ module Textus
         "read" => {
           "purpose" => "find and read an entry",
           "steps" => [
-            "textus list --zone=ZONE --prefix=PREFIX  # discover keys",
-            "textus get KEY                            # returns envelope JSON",
+            "list (zone:, prefix:) — discover keys without reading bodies",
+            "get KEY — returns the entry envelope",
           ],
         },
         "write" => {
           "purpose" => "create or update an entry",
           "steps" => [
-            "textus schema get FAMILY                  # learn the _meta field shape",
-            "build an envelope JSON: {_meta: {...}, body: \"...\"}",
-            "echo ENVELOPE | textus put KEY --as=ROLE --stdin",
+            "schema KEY — learn the _meta field shape (required, optional, field types) before writing",
+            "assemble an envelope: { _meta: {…}, body: \"…\" }",
+            "put KEY — persist it (role-gated); pass if_etag to guard a concurrent edit",
           ],
         },
         "propose" => {
           "purpose" => "agent suggests a change for human review",
           "agent_steps" => [
-            "echo ENVELOPE | textus put #{queue}.KEY --as=agent --stdin",
+            "propose KEY — writes the change into the #{queue} zone for review",
           ],
           "human_steps" => [
-            "textus accept #{queue}.KEY --as=human       # promotes the proposal to its target zone",
+            "accept #{queue}.KEY — promotes the proposal into its target zone",
           ],
         },
         "fetch" => {
-          "purpose" => "rebuild stale quarantine-zone caches from their declared actions",
+          "purpose" => "refresh stale quarantine-zone caches from their declared intake",
           "steps" => [
-            "textus freshness --zone=#{feeds}            # report fresh/stale per entry",
-            "textus fetch stale --zone=#{feeds} --as=automation",
+            "pulse — its `stale` list names entries past their ttl",
+            "fetch_all (zone: #{feeds}) — re-pull the stale entries",
           ],
         },
       }

data/lib/textus/mcp/catalog.rb

@@ -11,7 +11,7 @@ module Textus
       # Contracts of every MCP-surfaced verb, in Dispatcher order.
       def specs
         Textus::Dispatcher::VERBS.values
-                                 .select { |k| k.respond_to?(:contract?) && k.contract? && k.contract.mcp? }
+                                 .select { |k| mcp_surfaced?(k) }
                                  .map(&:contract)
       end
 
@@ -25,9 +25,23 @@ module Textus
         specs.map { |s| s.verb.to_s }
       end
 
+      # MCP-surfaced read verbs, by Dispatcher class namespace — the agent's
+      # real read/discovery surface. `boot.agent_quickstart.read_verbs` derives
+      # from this so it can never advertise a verb the agent cannot call, nor
+      # omit one it can (ADR 0056). Excludes Write/Maintenance.
+      def read_verbs
+        Textus::Dispatcher::VERBS
+          .select { |_verb, klass| mcp_surfaced?(klass) && klass.name.start_with?("Textus::Read::") }
+          .keys.map(&:to_s)
+      end
+
+      def mcp_surfaced?(klass)
+        klass.respond_to?(:contract?) && klass.contract? && klass.contract.mcp?
+      end
+
       def call(name, session:, store:, args:)
         klass = Textus::Dispatcher::VERBS[name.to_sym]
-        raise ToolError.new("unknown tool: #{name}") unless klass.respond_to?(:contract?) && klass.contract? && klass.contract.mcp?
+        raise ToolError.new("unknown tool: #{name}") unless klass && mcp_surfaced?(klass)
 
         spec = klass.contract
         pos, kw = map_args(spec, args || {}, session)

data/lib/textus/version.rb

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

metadata

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