textus 0.54.0 → 0.54.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f98dbc5f461b8cffaa4cf8fb17c8b79cf51f4c5f78af62527e0abe27d84d828
-  data.tar.gz: 0bfd928765a9797078f7534aecbf89321de754a4d56ee71986c00fb6a3a7b255
+  metadata.gz: '08d1e232ff648999588cfcfe0cccafd7954a020805f3e344aabdbbb2798b51af'
+  data.tar.gz: 4b8545d90d8aa990d63565f1d2caaff7e3e519d7504ae22a04dad68507c90949
 SHA512:
-  metadata.gz: 32fd23741a0f3e69368dfde1fb8733381190b17eb592c459079020a692c98c181a689ab5a83af6b3bf2d16c37ab2b52e40faf6a47ce876e4bafc0709e082ebed
-  data.tar.gz: daadc9db41cf87e2a348ddf9b4472fc515a48b4f5e7ca77d9c00a6c95ed736d26c59b3ad1ec799a42e3eba940052236dc77e5ee3edaf4737150e8f030a5fbcaa
+  metadata.gz: 28b8de7a9e84208008c7082cd597d6905b743fe035b0344953cc82d5581f8a6ce98abf4bae40e5f1040780a1874743e7403695831709a539ea2cd4fd7dbc4c79
+  data.tar.gz: 9be159077a4f4e17e0118b3efea9085d3e5f6f463d7f558d6fcfdc45912c07cde6fe0824de213171806245cbca3b38f689f6b6922a2f7ddf9fd4dcb0c0bdc2a7

data/CHANGELOG.md

@@ -9,6 +9,24 @@ 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.54.1 — 2026-06-17 — MCP SDK, dry ecosystem, ERB templates
+
+### Added
+
+- **`Textus::Types` module**: shared `dry-types` constrained types (`RoleName`, `Cursor`, `FormatName`) used across all dry-struct structs.
+
+### Changed
+
+- **MCP surface → official `mcp` SDK** (PR #223): the hand-rolled JSON-RPC 2.0 stdio loop is replaced by the official `mcp` gem (`~> 0.20`). Protocol version auto-negotiates up to `2025-11-25` (was hardcoded `2024-11-05`). `Catalog.build_tools` generates `MCP::Tool` instances from verb contracts; `Server` manages session lifecycle and delegates dispatch. `routing.rb`, the `MCP::Session` alias, and `ToolSchemas` are deleted.
+- **`Session`, `Envelope`, `Container` → `Dry::Struct`** (PR #223): `Data.define` replaced with `Dry::Struct` for typed, loudly-failing construction at object creation time. `Session` enforces `RoleName` and non-negative `Cursor`; `Envelope` enforces known `FormatName`; `Container` has typed port references.
+- **Manifest validator → dry-schema + Semantics** (PR #223): the 318-line programmatic validator is split into `contract.rb` (dry-schema structural contract) and `semantics.rb` (cross-field rules, `walk`-based unknown-key detection, ADR migration hints). Public interface `Validator.validate!` unchanged.
+- **Mustache → ERB** (PR #223): `mustache` gem removed; all 8 `.mustache` templates converted to `.erb` using `ERB#result_with_hash`. `Produce::Render` now uses `ERB.new(template, trim_mode: "-").result_with_hash(ctx)`.
+
+### Removed
+
+- `mustache` runtime dependency (replaced by Ruby stdlib ERB).
+- `MCP::Routing` module, `MCP::Session` alias, `MCP::ToolSchemas` module — superseded by the SDK.
+
 ## 0.54.0 — 2026-06-16 — Workflow system, raw ingest pipeline, MCP resources
 
 ### Added

data/README.md

@@ -64,22 +64,20 @@ DURABLE       │  notebook                │  knowledge  ★ the goal
 (kept)        │  agent's working truth   │  canon — a human authors      │
               │  durable, but low-trust  │  here · the context you ship  │
               ├──────────────────────────┼───────────────────────────────┤
-TRANSIENT     │  artifacts.feeds.*       │  proposals  (queue)           │
-(staging)     │  raw external input,     │  a candidate, in review       │
-              │  unverified (machine)    │  ▲ climbs via human accept    │
+TRANSIENT     │  artifacts.*             │  proposals  (queue)           │
+(staging)     │  computed outputs and    │  a candidate, in review       │
+              │  external inputs         │  ▲ climbs via human accept    │
               └──────────────────────────┴───────────────────────────────┘
                 raw material ──── propose ────► a human accept lifts it to canon
 ```
 
-*(The `machine` lane's other half, `artifacts.derived.*`, isn't on this grid — it's a computed **output** projected from the lanes, not an input climbing toward trust.)*
-
 Without coordination, they overwrite each other and nothing remembers why. textus gives each actor a **lane** — enforced at the protocol level, not by convention — routes everything they can't write directly through a **proposals queue**, and writes every successful change to an **append-only audit log**.
 
 ```
-knowledge/   author only        — who you are, what you decide, how you sound (knowledge.identity.* for identity facts)
-notebook/    keep only          — agent's own durable lane (agents keep theirs; bytes climb to knowledge only via propose→accept)
-proposals/   propose (agent + human) — proposals waiting on a human accept
-artifacts/   converge only     — machine-maintained: external inputs (artifacts.feeds.*) + computed outputs (artifacts.derived.*)
+knowledge/   author only            — who you are, what you decide, how you sound
+notebook/    keep only              — agent's own durable lane (bytes climb to knowledge only via propose→accept)
+proposals/   propose (agent+human) — proposals waiting on a human accept
+artifacts/   converge only         — machine-maintained: computed outputs + external inputs
 ```
 
 An agent that tries to write directly into `knowledge/` gets `write_forbidden`. It writes to `proposals/` (to change authoritative content) or its own `notebook/` (for working memory). You accept the good proposals; textus promotes them, records the move, and audits both halves. Stable per-entry `uid:` means a reorganization doesn't break references. A monotonic audit cursor (`textus pulse --since=N`) means the next session — possibly a different agent, possibly a different model — picks up exactly where the last one left off.
@@ -109,12 +107,12 @@ Try the gate the other way (`textus put knowledge.notes.X --as=agent`) and you g
 
 ## Try it
 
-- **Worked end-to-end store** — the role gate (propose → accept), drain/publish (`CLAUDE.md` / `AGENTS.md` generated from knowledge entries), schemas, templates, and a hook: [`.textus/`](.textus/)
+- **Worked end-to-end store** — the role gate (propose → accept), drain/publish (`CLAUDE.md` / `AGENTS.md` generated from knowledge entries), schemas, ERB templates, and workflows: [`.textus/`](.textus/)
 - **Wire textus into Claude Code via MCP** — 4 steps, ~5 minutes: [`docs/how-to/agents-mcp.md`](docs/how-to/agents-mcp.md)
 
 ## Protocol, not just a gem
 
-This Ruby gem is the reference implementation of **`textus/3`** — a wire format and storage convention any language can speak. The protocol owns the envelope shape, the role/lane gate, the audit log format, and the key grammar. The gem version (semver, see badge) and the protocol version (`textus/3`) move independently; envelopes carry the `protocol` field so consumers can pin to the contract, not the implementation.
+This Ruby gem is the reference implementation of **`textus/4`** — a wire format and storage convention any language can speak. The protocol owns the envelope shape, the role/lane gate, the audit log format, and the key grammar. The gem version (semver, see badge) and the protocol version (`textus/4`) move independently; envelopes carry the `protocol` field so consumers can pin to the contract, not the implementation.
 
 - Specification: [`SPEC.md`](SPEC.md)
 - Architecture: [`docs/architecture/README.md`](docs/architecture/README.md)
@@ -146,26 +144,26 @@ roles:
   - { name: automation, can: [converge] }
 
 lanes:
-  - { name: knowledge, kind: canon }      # author    — canonical truth
-  - { name: notebook,  kind: workspace }  # keep      — agent's own durable lane
-  - { name: proposals, kind: queue }      # propose   — proposals awaiting accept
-  - { name: artifacts, kind: machine }    # converge — external inputs (artifacts.feeds.*) + computed outputs (artifacts.derived.*)
+  - { name: knowledge, kind: canon }      # author   — canonical truth
+  - { name: notebook,  kind: workspace }  # keep     — agent's own durable lane
+  - { name: proposals, kind: queue }      # propose  — proposals awaiting accept
+  - { name: artifacts, kind: machine }    # converge — computed outputs + external inputs
 ```
 
 ```
 .textus/
   manifest.yaml          # role capabilities + lane kinds + key-to-path mapping
   schemas/               # YAML field shapes per entry family
-  templates/             # mustache templates for derived entries
-  steps/                 # step subclasses: fetch/, transform/, validate/, observe/
+  templates/             # ERB templates for produced entries
+  workflows/             # Ruby workflow files (Textus.workflow DSL) for data acquisition
   .gitignore             # generated — ignores .run/ and any tracked:false entries
   data/                  # one dir per lane; kinds + capabilities are in the manifest above
     knowledge/           # e.g. identity (knowledge.identity.*), voice, decisions, notes
     notebook/
     proposals/
-    artifacts/           # machine lane: feeds/ (external inputs) + derived/ (computed outputs)
+    artifacts/           # machine lane: computed outputs + external inputs
   .run/                  # disposable runtime state — gitignored, safe to delete (ADR 0038)
-    audit/audit.log      # append-only NDJSON event ledger, every write (rotates at ~50 MB)
+    audit/audit.log      # append-only NDJSON event ledger, every write (rotates at ~10 MB)
     state/cursor.<role>  # per-role pulse cursor — where `pulse --since` resumes
     locks/               # per-key produce locks + the produce mutex
     sentinels/           # publish bookkeeping (target sha) — regenerated on drain (ADR 0070)
@@ -181,21 +179,23 @@ textus list --lane=knowledge
 printf '%s' '{"_meta":{"name":"bob","org":"acme"},"body":"hi\n"}' \
   | textus put knowledge.notes.bob --as=human --stdin
 textus drain --as=automation     # re-pull stale inputs + recompute derived outputs
-textus rule list                     # show every rule block
-textus audit --limit=20              # query the audit log
+textus rule list                  # show every rule block
+textus audit --limit=20           # query the audit log
 ```
 
-(All verbs return JSON envelopes; `--output=json` is the default and the only format in v1.)
+(All verbs return JSON envelopes; `--output=json` is the default and the only format.)
 
-For a worked store — knowledge entries, a staged proposal, schemas, a template, and a `drain` that publishes `CLAUDE.md` / `AGENTS.md` — see [`.textus/`](.textus/).
+For a worked store — knowledge entries, a staged proposal, schemas, ERB templates, and a `drain` that publishes `CLAUDE.md` / `AGENTS.md` — see [`.textus/`](.textus/).
 
 ## What's shipped
 
 - **Per-entry formats & publish.** `format: markdown|json|yaml|text` per entry; a typed `publish:` block (`to:` for file fan-out, `tree:` for a whole-subtree mirror) byte-copies derived files to their consumer paths. ([SPEC §5.2–5.3](SPEC.md))
 - **Stable identity.** Auto-minted `uid:` survives writes and `textus key mv`; reorganising never breaks references.
 - **Capability × lane-kind gate.** Writes carry `--as=<role>`; a role may write a lane iff it holds the capability the lane's `kind:` requires (`canon`→`author`, `workspace`→`keep`, `machine`→`converge`, `queue`→`propose`). 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/how-to/agents-mcp.md](docs/how-to/agents-mcp.md))
-- **`textus doctor`.** Health checks across schemas, step registrations, keys, sentinels, and the audit log.
+- **Agent loop.** `textus boot` orients a fresh session; `textus pulse --since=N` is the per-turn heartbeat (changed entries, pending proposals, index etag for catalog drift detection). ([docs/how-to/agents-mcp.md](docs/how-to/agents-mcp.md))
+- **MCP surface.** The official `mcp` Ruby SDK drives the stdio JSON-RPC server; protocol version auto-negotiated up to `2025-11-25`. Wire textus into Claude Code, Cursor, or any MCP host in one config block.
+- **`textus doctor`.** Health checks across schemas, workflow registrations, keys, sentinels, and the audit log.
+- **`raw` lane kind.** A write-once intake lane for external data that hasn't been reviewed yet; carries the `ingest` capability.
 
 ## CLI and lanes
 
@@ -204,79 +204,59 @@ Every command operates on one store, located in this order: `--root <path>` flag
 - Full verb table — read, write, health, scaffolding — is in [SPEC §9](SPEC.md).
 - Lane semantics and the capability × lane-kind mapping live in [SPEC §5](SPEC.md), with the reference in [`docs/reference/zones.md`](docs/reference/zones.md).
 
-`textus boot` prints the same information for the current store: lanes, entry families with schemas, registered steps, write flows, and the verb catalog. Run it inside a store and you get the live picture; reach for the SPEC when you want the contract.
+`textus boot` prints the same information for the current store: lanes, entry families with schemas, registered workflows, write flows, and the verb catalog. Run it inside a store and you get the live picture; reach for the SPEC when you want the contract.
 
 ## Produce and publish
 
-Produced entries (`kind: produced`) declare how they're acquired in one `source:` block (ADR 0093/0094); `drain` materialises them:
+Produced entries (`kind: produced`) declare how they're acquired in one `source:` block; `drain` materialises them. Two built-in modes, plus workflows for custom data acquisition:
 
-- **`source: { from: derive, select: [...], pluck:, sort_by:, limit:, transform: name }`** — a *derived* entry: textus computes its data from other entries, then renders it through a template under `.textus/templates/` (markdown/text) or a templateless path that lets a transform hook shape the output directly (json/yaml). Projections cap at 1000 rows; the vendored Mustache subset caps at depth 8. No partials, no lambdas, no HTML escaping.
-- **`source: { from: fetch, handler: name, ttl: 1h, config: {...} }`** — *intake*: a Step::Fetch handler pulls external bytes on a `ttl` cadence; `drain` re-pulls when the entry goes stale.
-- **`source: { from: external, sources: [...] }`** — *externally managed*: an out-of-band command writes the file; textus tracks the declared `sources` for staleness.
+- **`source: { from: external, command: "...", sources: [...] }`** — *externally managed*: an out-of-band command or workflow writes the file; textus tracks staleness via declared `sources`.
+- **`source: { from: external, command: "true", sources: [] }` + a workflow** — *workflow-driven*: a `Textus.workflow` block (in `.textus/workflows/`) acquires and shapes the data on `drain`.
 
-Publishing is one typed `publish:` block (ADR 0052). `publish: { to: [path, ...] }` byte-copies a single produced file to one or more targets. `publish: { tree: "dir" }` on a nested entry mirrors its whole stored subtree to one target directory, preserving layout (path-driven — no keys or template variables). Sentinels for every published file live under `.textus/.run/sentinels/` (git-ignored runtime state, regenerated on drain — ADR 0070). See SPEC §5.2, §5.3, §5.12.
+Publishing is one typed `publish:` block (ADR 0052/0094). Each target is either `{ to: path, template?: name }` for a single file (optionally rendered through an ERB template) or `{ tree: "dir" }` to mirror a whole stored subtree. Sentinels for every published file live under `.textus/.run/sentinels/` (git-ignored, regenerated on drain). See SPEC §5.2, §5.3, §5.12.
 
-## Extension points
+Templates live in `.textus/templates/` as ERB files (`.erb`). The template receives the entry's `content` hash as local variables via `ERB#result_with_hash`. If `inject_boot: true`, a `boot` variable is also available with the live orientation context.
 
-textus extends through **steps** — subclass the right base, place the file in `.textus/steps/<kind>/`, and `drain` discovers it. Three kinds:
+## Workflows
 
-**`Step::Fetch`** — acquires bytes for an intake entry (`from: fetch`). One class per named handler; `drain` invokes it when the entry is stale.
+textus extends through **workflows** — a `Textus.workflow` block placed in `.textus/workflows/**/*.rb`. Each workflow matches a produced entry by key glob, then runs one or more named steps to acquire its data:
 
 ```ruby
-# .textus/steps/fetch/local_file.rb
-module Textus
-  module Step
-    class LocalFileFetch < Fetch
-      def call(config:, args:, **)
-        path = config["path"] or raise "local-file requires source.config.path"
-        { "_meta" => { "last_fetched_at" => Time.now.utc.iso8601 },
-          "body"  => File.read(File.expand_path(path)) }
-      end
-    end
+# .textus/workflows/artifacts/my_report.rb
+Textus.workflow "my_report" do
+  match "artifacts.my-report"
+
+  step :build do |_, ctx|
+    # read from knowledge, fetch external data, compute anything
+    rows = ctx.container.manifest.resolver
+              .enumerate(prefix: "knowledge.notes")
+              .map { |r| { "key" => r[:key], "title" => r[:entry].schema } }
+    { "content" => { "entries" => rows } }
   end
 end
 ```
 
-**`Step::Transform`** — reshapes projected rows for a `from: derive` entry.
+`drain` discovers all workflow files, matches them against produced entries, and runs the steps. The result is written back to the entry's data path; `publish:` then copies it to its consumer paths.
 
-```ruby
-# .textus/steps/transform/rank_by_recency.rb
-module Textus
-  module Step
-    class RankByRecencyTransform < Transform
-      def call(rows:, config:, **)
-        rows.sort_by { |r| r["updated_at"].to_s }.reverse
-      end
-    end
-  end
-end
-```
+## Hooks
 
-**`Step::Observe`** — reacts to lifecycle events (fire-and-forget, 0..N per event):
+Out-of-band event reactions use the hook DSL. Drop a file anywhere in `.textus/workflows/` and use `Textus.hook`:
 
 ```ruby
-# .textus/steps/observe/log_writes.rb
-module Textus
-  module Step
-    class LogWritesObserve < Observe
-      on :entry_written
-
-      def call(key:, envelope:, **)
-        $textus_event_log << [key, envelope.etag]
-      end
-    end
+Textus.hook do |reg|
+  reg.on(:entry_written) do |key:, envelope:, **|
+    # fire-and-forget — runs after every successful write
+    $stderr.puts "wrote #{key} (etag #{envelope.etag[0, 8]})"
   end
 end
 ```
 
 Observable events: `:entry_written`, `:entry_deleted`, `:entry_fetched`, `:entry_renamed`, `:entry_produced`, `:entry_published`, `:produce_failed`, `:proposal_accepted`, `:proposal_rejected`, `:store_loaded`, `:session_opened`, `:entry_fetch_started`, `:entry_fetch_failed`.
 
-Stale intake entries are re-pulled by `drain`, not by reads — `get` is a pure
-read that annotates the returned envelope with a freshness verdict (ADR 0089).
-`drain` re-pulls anything past its `source.ttl` and recomputes derived outputs:
+Stale produced entries are re-materialised by `drain`, not by reads — `get` is a pure read that annotates the returned envelope with a freshness verdict (ADR 0089).
 
 ```sh
-textus drain --as=automation                  # re-pull every stale intake + recompute derived
+textus drain --as=automation                  # re-materialise every stale produced entry
 textus drain artifacts.feeds --as=automation  # scope to one prefix
 textus get artifacts.feeds.calendar.events    # a pure read; carries a freshness verdict
 ```
@@ -287,7 +267,7 @@ See [`docs/how-to/agents-mcp.md`](docs/how-to/agents-mcp.md) for the agent boot
 
 ## Examples
 
-[`.textus/`](.textus/) — 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 `Step::Transform` step, and a `drain` that publishes the `artifacts.derived.orientation` projection to `CLAUDE.md` and `AGENTS.md`. Includes a copy-paste adoption recipe for your own repo.
+[`.textus/`](.textus/) — textus as a project's own context store. Human-authored `knowledge/` (project facts, runbooks, ADRs), a staged proposal showing the agent-propose / human-accept loop, schemas validating each family, ERB templates and workflows, and a `drain` that publishes the orientation artifact to `CLAUDE.md` and `AGENTS.md`. Includes a copy-paste adoption recipe for your own repo.
 
 ## Tests
 

data/lib/textus/boot.rb

@@ -160,7 +160,7 @@ module Textus
         "agent_quickstart" => agent_quickstart(manifest, container.audit_log),
         "orientation" => read_artifact_content(container, "artifacts.orientation"),
         "context" => read_boot_context(container),
-        "index_key" => "artifacts.index",
+        "index_key" => index_key_if_present(container),
         "agent_protocol" => agent_protocol(manifest),
       }.compact
     end
@@ -188,6 +188,13 @@ module Textus
       nil
     end
 
+    def self.index_key_if_present(container)
+      res = container.manifest.resolver.resolve("artifacts.index")
+      res.path && File.exist?(res.path) ? "artifacts.index" : nil
+    rescue Textus::Error
+      nil
+    end
+
     def self.lanes_for(manifest)
       manifest.data.declared_lane_kinds.keys.map do |name|
         verb = manifest.policy.verb_for_lane(name)

data/lib/textus/container.rb

@@ -1,10 +1,26 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
 module Textus
   # Single capability record handed to every use case. Replaces the
   # ReadCaps/WriteCaps/HookCaps trio from 0.26.x. Built once per Store
   # (see Store#initialize); Store delegates its readers to this record,
-  # so this `Data.define` is the single source of truth for the field set.
-  Container = Data.define(
-    :manifest, :file_store, :schemas, :root,
-    :audit_log, :workflows, :gate
-  )
+  # so this struct is the single source of truth for the field set.
+  class Container < Dry::Struct
+    attribute :manifest,   Types::Any
+    attribute :file_store, Types::Any
+    attribute :schemas,    Types::Any
+    attribute :root,       Types::String
+    attribute :audit_log,  Types::Any
+    attribute :workflows,  Types::Any
+    attribute :gate,       Types::Any
+
+    def with(**attrs) = self.class.new(to_h.merge(attrs))
+
+    def initialize(*)
+      super
+      freeze
+    end
+  end
 end

data/lib/textus/core/freshness/verdict.rb

@@ -9,7 +9,7 @@ module Textus
       # Note on wire format: `#to_h_for_wire` is intentionally narrower than the
       # full field set. It emits the legacy keys ("stale", "stale_reason",
       # "fetching", and "fetch_error" when present) so the CLI JSON wire stays
-      # byte-identical with textus/3. The gem-side fields `checked_at` and
+      # byte-identical with textus/4. The gem-side fields `checked_at` and
       # `ttl_remaining_ms` are NOT emitted on the wire.
       Verdict = Data.define(
         :stale, :fetching, :reason, :fetch_error, :checked_at, :ttl_remaining_ms

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

@@ -13,13 +13,13 @@ module Textus
 
           doc = YAML.safe_load_file(path, aliases: false) || {}
           version = doc["version"]
-          return [] if version == "textus/3"
+          return [] if version == "textus/4"
 
           [{
             "code" => "protocol_mismatch",
             "severity" => "error",
-            "message" => "Store reports version=#{version.inspect}; this gem expects textus/3.",
-            "hint" => "Upgrade the store's manifest version to textus/3 (see CHANGELOG for breaking changes).",
+            "message" => "Store reports version=#{version.inspect}; this gem expects textus/4.",
+            "hint" => "Upgrade the store's manifest version to textus/4 (see CHANGELOG for breaking changes).",
           }]
         end
 
@@ -31,14 +31,14 @@ module Textus
 
           doc = YAML.safe_load_file(path, aliases: false) || {}
           version = doc["version"]
-          return [] if version == "textus/3"
+          return [] if version == "textus/4"
 
           [{
             "code" => "protocol_mismatch",
             "level" => "error",
             "subject" => path,
-            "message" => "Store reports version=#{version.inspect}; this gem expects textus/3.",
-            "fix" => "Upgrade the store's manifest version to textus/3 (see CHANGELOG for breaking changes).",
+            "message" => "Store reports version=#{version.inspect}; this gem expects textus/4.",
+            "fix" => "Upgrade the store's manifest version to textus/4 (see CHANGELOG for breaking changes).",
           }]
         end
       end

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

@@ -0,0 +1,54 @@
+module Textus
+  module Doctor
+    class Check
+      # Warns when a knowledge-lane doc's `**reviewed** YYYY-MM (vX.Y)` stamp
+      # is more than MINOR_THRESHOLD minor versions behind Textus::VERSION.
+      # The stamp is the human staleness signal declared in docs conventions
+      # (knowledge.docs-index); this check makes it machine-enforced.
+      class StaleReviewedStamp < Check
+        STAMP_RE = /\*\*reviewed\*\*\s+\d{4}-\d{2}\s+\(v(\d+\.\d+(?:\.\d+)?)\)/
+        MINOR_THRESHOLD = 5
+
+        def call
+          current_minor = parse_minor(Textus::VERSION)
+          issues = []
+
+          manifest.resolver.enumerate.each do |row|
+            next unless row[:key].to_s.start_with?("knowledge.")
+            next unless row[:path] && File.file?(row[:path])
+
+            body = File.read(row[:path])
+            m = body.match(STAMP_RE)
+            next unless m
+
+            reviewed_minor = parse_minor(m[1])
+            behind = current_minor - reviewed_minor
+            next unless behind > MINOR_THRESHOLD
+
+            issues << stale_issue(row[:key], m[1], behind)
+          end
+
+          issues
+        end
+
+        private
+
+        def parse_minor(version_str)
+          version_str.sub(/\Av/, "").split(".").map(&:to_i)[1] || 0
+        end
+
+        def stale_issue(key, stamp_version, behind)
+          current_short = Textus::VERSION[/\A\d+\.\d+/]
+          {
+            "code" => "stale_reviewed_stamp",
+            "level" => "warning",
+            "subject" => key.to_s,
+            "message" => "reviewed at v#{stamp_version}; current is v#{Textus::VERSION} " \
+                         "(#{behind} minor versions behind, threshold is #{MINOR_THRESHOLD})",
+            "fix" => "review the doc and update the stamp to: **reviewed** YYYY-MM (v#{current_short})",
+          }
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor.rb

@@ -23,6 +23,7 @@ module Textus
       Check::GeneratorDrift,
       Check::RawAssetPaths,
       Check::NotebookSources,
+      Check::StaleReviewedStamp,
     ].freeze
 
     ALL_CHECKS = CHECKS.map(&:name_key).freeze

data/lib/textus/envelope.rb

@@ -1,10 +1,23 @@
 # frozen_string_literal: true
 
+require "dry-struct"
+
 module Textus
-  Envelope = Data.define(
-    :protocol, :key, :lane, :owner, :path, :format,
-    :uid, :etag, :schema_ref, :meta, :body, :content, :freshness
-  ) do
+  class Envelope < Dry::Struct
+    attribute :protocol,   Types::String
+    attribute :key,        Types::String
+    attribute :lane,       Types::String
+    attribute :owner,      Types::String.optional
+    attribute :path,       Types::String
+    attribute :format,     Types::FormatName
+    attribute :etag,       Types::String
+    attribute :uid,        Types::String.optional
+    attribute :schema_ref, Types::String.optional
+    attribute :meta,       Types::Hash.default({}.freeze)
+    attribute :body,       Types::String.optional
+    attribute :content,    Types::Any.optional
+    attribute :freshness,  Types::Any.optional
+
     # rubocop:disable Metrics/ParameterLists
     def self.build(key:, mentry:, path:, meta:, body:, etag:, content: nil, freshness: nil)
       # rubocop:enable Metrics/ParameterLists
@@ -30,6 +43,8 @@ module Textus
       v.is_a?(String) ? v : nil
     end
 
+    def with(**attrs) = self.class.new(to_h.merge(attrs))
+
     def to_h_for_wire
       h = {
         "protocol" => protocol,
@@ -49,8 +64,6 @@ module Textus
       h
     end
 
-    alias_method :zone, :lane
-
     def stale?
       return false if freshness.nil?
 

data/lib/textus/errors.rb

@@ -217,7 +217,7 @@ module Textus
     def initialize(old_flag, new_flag)
       super(
         "flag_renamed",
-        "#{old_flag} was renamed in textus/3 — use #{new_flag}",
+        "#{old_flag} was renamed in textus/4 — use #{new_flag}",
         details: { "old" => old_flag, "new" => new_flag },
         hint: "Use #{new_flag} instead.",
         exit_code: 2,

data/lib/textus/init.rb

@@ -6,7 +6,7 @@ module Textus
     ZONES = %w[knowledge notebook proposals artifacts raw].freeze
 
     DEFAULT_MANIFEST = <<~YAML
-      version: textus/3
+      version: textus/4
       roles:
         - { name: human,      can: [author, propose] }
         - { name: agent,      can: [propose, keep] }
@@ -42,8 +42,8 @@ module Textus
         path: data/artifacts/derived/orientation.json
         lane: artifacts
         publish:
-        - { to: CLAUDE.md, template: orientation.mustache, inject_boot: true }
-        - { to: AGENTS.md, template: orientation.mustache, inject_boot: true }
+        - { to: CLAUDE.md, template: orientation.erb, inject_boot: true }
+        - { to: AGENTS.md, template: orientation.erb, inject_boot: true }
         kind: produced
     YAML
 
@@ -121,7 +121,7 @@ module Textus
       {
         "project.schema.yaml" => File.join("schemas", "project.yaml"),
         "runbook.schema.yaml" => File.join("schemas", "runbook.yaml"),
-        "orientation.mustache" => File.join("templates", "orientation.mustache"),
+        "orientation.erb" => File.join("templates", "orientation.erb"),
       }.each do |src, dest|
         File.write(File.join(target_root, dest), File.read(File.join(scaffold_dir, src)))
       end

data/lib/textus/manifest/schema/contract.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "dry/schema"
+
+module Textus
+  class Manifest
+    module Schema
+      # rubocop:disable Metrics/BlockLength
+      Contract = Dry::Schema.JSON do
+        required(:lanes).value(:array).each do
+          hash do
+            required(:name).value(:string)
+            required(:kind).value(included_in?: Vocabulary::LANE_KINDS)
+            optional(:owner).value(:string)
+            optional(:desc).value(:string)
+          end
+        end
+
+        optional(:roles).value(:array).each do
+          hash do
+            required(:name).value(:string)
+            optional(:can).value(:array).each(:string)
+          end
+        end
+
+        optional(:entries).value(:array).each do
+          hash do
+            required(:key).value(:string)
+            required(:lane).value(:string)
+            optional(:path).value(:string)
+            optional(:owner).value(:string)
+            optional(:format).value(:string)
+            optional(:schema).maybe(:string)
+            optional(:kind).value(:string)
+            optional(:nested).value(:bool)
+            optional(:tracked).value(:bool)
+            optional(:ignore)
+            optional(:source)
+            optional(:publish).value(:array)
+          end
+        end
+
+        optional(:rules).value(:array).each do
+          hash do
+            optional(:match).value(:string)
+            optional(:guard)
+            optional(:retention)
+            optional(:react)
+          end
+        end
+
+        optional(:audit).hash do
+          optional(:max_size).value(:integer)
+          optional(:keep).value(:integer)
+        end
+        optional(:version).value(:string)
+      end
+      # rubocop:enable Metrics/BlockLength
+    end
+  end
+end