textus 0.53.0 → 0.54.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7df129e69143765baa5302608a7813c0666d3c9d91266e0a47a4ece61a4f9f6
-  data.tar.gz: 2362c085078165a6da46e55dac29b75346d0f14527de514898f1f5136b094b21
+  metadata.gz: '08d1e232ff648999588cfcfe0cccafd7954a020805f3e344aabdbbb2798b51af'
+  data.tar.gz: 4b8545d90d8aa990d63565f1d2caaff7e3e519d7504ae22a04dad68507c90949
 SHA512:
-  metadata.gz: a120d5d78f679fb9019817bf8491e00abe1145416c95faf6f80d5f62d078dbe8a054d15e5ec080ff5544eb3b2e02466130617db2d7d4fbf32dab05d3d8295fe1
-  data.tar.gz: a4dd565844225f88ae27683e37b6f508a3e64a6828a4b09ee472b815576b57eb9fd1ccf86d4cea91ecd92dde7ca59f0288ac01abf786afb9cce4833c28bb088c
+  metadata.gz: 28b8de7a9e84208008c7082cd597d6905b743fe035b0344953cc82d5581f8a6ce98abf4bae40e5f1040780a1874743e7403695831709a539ea2cd4fd7dbc4c79
+  data.tar.gz: 9be159077a4f4e17e0118b3efea9085d3e5f6f463d7f558d6fcfdc45912c07cde6fe0824de213171806245cbca3b38f689f6b6922a2f7ddf9fd4dcb0c0bdc2a7

data/CHANGELOG.md

@@ -9,6 +9,58 @@ 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
+
+- **Workflow system** (PR #218): Ruby DSL files in `.textus/workflows/` replace the `step/` extension model. `Workflow::Registry` (loaded from `.textus/workflows/**/*.rb`) is resolved by `Produce::Engine` at produce time; `Workflow::Runner` threads data through each named step and persists. Core components: `Workflow::Context`, `Workflow::Pattern` (glob matching), `Workflow::DSL`, `Workflow::Collector`, `Workflow::Registry`, `Workflow::Loader`, `Workflow::Runner`.
+- **`artifacts.index` produced workflow**: pre-computed full-store catalog (`artifacts.index`) served as a produced artifact — enumerates every manifest entry with its key, lane, format, etag, and `generated_at` timestamp.
+- **MCP `resources/list` and `resources/read`** (PR #221): machine-lane `produced` entries are now exposed as MCP resources at `textus://<key>` URIs with correct MIME types. Clients discover them via the `resources` capability advertised in the `initialize` handshake.
+- **Raw ingest pipeline** (PR #219, [ADR 0114](docs/architecture/decisions/0114-foundation-refactor.md), [ADR 0116](docs/architecture/decisions/0116-raw-lane-and-ingest-verb.md)): new `raw` zone-kind with a `write-once` gate and an `ingest` capability/verb (`Action::Ingest`). Doctor checks and an asset sentinel guard the lane. The `raw` bijection entry maps `raw → ingest`.
+
+### Changed
+
+- **`artifacts.derived.*` → `artifacts.*`**: the `derived` key segment is dropped — all machine-lane entries flatten to `artifacts.<name>` in both the manifest and the on-disk store. Workflows, boot, and all other callers updated.
+- **`boot` reads from `artifacts.index`**: inline computation removed from the boot action; the pre-computed catalog drives the response. `--lean` flag removed (PR #220).
+- **`pulse` slimmed**: `stale`, `doctor`, and `next_due_at` removed from the pulse envelope; `index_etag` added so clients can cheaply detect catalog drift without a full list.
+- **`ContractDrift` moved to core** (PR #220): `Textus::ContractDrift` extracted from the MCP surface into the core library so it is reusable across surfaces.
+- **MCP `Server` refactored per Sandi Metz rules** (PR #220): routing extracted to `Routing` module; methods decomposed to ≤ 5 lines each.
+- **Plugin manifest wiring** (PR #220): `claude_plugin` uses the installed `textus` binary (external use); `mcp_config` keeps `bundle exec` (dev environment). `--lean` references removed from the plugin manifest spec.
+- **Namespace renames** (PR #218, internal): `entry/` → `format/`, `envelope/io/` → `envelope/`, `Ports::Queue` → `Ports::JobStore`, `background/` → `jobs/`, `pipeline/` → `produce/`.
+- **Workflows reorganised**: workflow files split into `artifacts/` and `config/` subdirectories under `.textus/workflows/`.
+
+### Removed
+
+- **Step system** (PR #218): entire `lib/textus/step/` directory deleted along with all step-related specs, `container.steps`, dead `hooks.rb` doctor check, and `ports/audit_subscriber.rb`. **Migration:** rewrite step files as `.textus/workflows/*.rb` using the Workflow DSL.
+- **`Jobs::Refresh`** ([ADR 0115](docs/architecture/decisions/0115-role-trust-model.md)): workflow-based periodic re-derivation replaces the background refresh job.
+- **`handler_permit` manifest field** (PR #218): doctor-only field with no runtime enforcement deleted along with its policy class and schema key.
+- **Dead guards and constants**: `derived_write?` no-op guard from `WriteVerb#cascade_to_rdeps`; `publish_each` runtime guard from `Entry::Publish`; duplicate inline `check_action!` from `put`/`key_delete`/`reject`; `BURN = :sync` constant; cross-lane notebook side-effect from `Action::Ingest`.
+- **`source.from: fetch` and `source.from: derive`** narrowed to `external` only — fetch/derive methods removed from `Produced`; freshness/pulse use retention rules; boot drops intake/derived keys.
+
+### Fixed
+
+- **MCP `resources` capability missing from `initialize` handshake** (PR #221): the server only advertised `tools`, so MCP clients never called `resources/list`. Adding `"resources" => {}` makes all 9 produced artifacts discoverable as resources.
+- **`adr_log` workflow**: `include_keyless: true` added for tree-publish of `knowledge.decisions`.
+- **SpecLayout violations** (PR #221): `workflow_index_spec` and `workflow/errors_spec` (string-described) moved to `spec/conformance/workflow/`.
+
 ## 0.53.0 — 2026-06-15 — Auth consolidation and code quality
 
 ### 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/SPEC.md

@@ -899,16 +899,13 @@ The agent's MCP write surface includes the single-key `key_delete` and `key_mv`
 {
   "cursor":         1845,
   "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 },
   "contract_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": "..." } ]
+  "index_etag":     "sha256:8f3c…"
 }
 ```
 
-`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`) — it lists intake entries past their `source.ttl`. `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`.
+`cursor` is the new high-water mark; pass it as `--since` on the next call. `changed` is sourced from `audit --seq-since`. `pending_review` lists all keys in the queue zone. `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. `index_etag` is the etag of the `artifacts.index` catalog file, or `null` when it does not exist — agents use this to detect when the catalog has been rebuilt. 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):