textus 0.52.0 → 0.53.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2095b69b4e135e71a1ae786759d299c8df4e78a0164a142411d0df72ce63aa4e
-  data.tar.gz: fb01669c8458fbfa0db50cff6314d30c9033abc02632998e431b2d11cb7e893c
+  metadata.gz: c7df129e69143765baa5302608a7813c0666d3c9d91266e0a47a4ece61a4f9f6
+  data.tar.gz: 2362c085078165a6da46e55dac29b75346d0f14527de514898f1f5136b094b21
 SHA512:
-  metadata.gz: 728c7e305b878cb68bf10af0bd93d9ca93b8b1a2be07a7ec7333de73f127415d4aeae112863bc9fa4d1cec67f51a0da25e2ad984b7b4283f4724c878241ff0c0
-  data.tar.gz: 7019ce011bf7297d430c2de9f8da591bc951d863e6834ba40c928eeca1bb0082626e2a0814c8bb6412288fb60659faedc5807e77258fbbcf3b3099672ddb19f4
+  metadata.gz: a120d5d78f679fb9019817bf8491e00abe1145416c95faf6f80d5f62d078dbe8a054d15e5ec080ff5544eb3b2e02466130617db2d7d4fbf32dab05d3d8295fe1
+  data.tar.gz: a4dd565844225f88ae27683e37b6f508a3e64a6828a4b09ee472b815576b57eb9fd1ccf86d4cea91ecd92dde7ca59f0288ac01abf786afb9cce4833c28bb088c

data/CHANGELOG.md

@@ -9,6 +9,31 @@ 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.53.0 — 2026-06-15 — Auth consolidation and code quality
+
+### Added
+
+- **`bin/dev`**: local script for syncing skills from GitHub during development.
+
+### Changed
+
+- **Gate dispatch consolidated** (PR #215): removed redundant `container:` param from `Gate#dispatch` (always `@container`); removed dead `Textus::Dispatch` module; removed double auth call in `Accept`; removed dead `else` branch and `role_filter` from `RoleScope` verb dispatch.
+- **`Background::Planner::Planner` renamed** to `Planner::Plan` to resolve the double-name antipattern.
+- **`Writer#put` decomposed** (38→12 lines): extracted into 8 single-purpose sub-methods (resolve, uid, serialize, schema-validate, etag-check, persist, envelope, audit).
+- **`Gate::Auth#check!` / `check_action!` deduplicated**: shared predicate-evaluation logic extracted into `evaluate_predicates`.
+- **`Init.run` split** (30→10 lines): 8 focused class methods (`check_target!`, `create_directories`, `write_steps_readme`, `write_manifest`, `scaffold_agent`, `setup_state_dirs`, `write_gitignore`, `build_result`).
+- **`auth`/`writer`/`reader` helpers pulled into `WriteVerb`**: removed 4-file duplication from `Put`, `KeyMv`, `KeyDelete`, `Reject`.
+- **`Action::Base#args` auto-generated** from `initialize` params: ~115 lines of boilerplate removed across 25 action classes.
+- **`AuditLog#verify_integrity`**: per-line checking extracted into `check_line_integrity` + `iterate_with_prev_seq`.
+- **`Error#initialize`**: 5-param constructor replaced with `ErrorInfo` parameter object (backward-compatible).
+- **`EventBus#invoke`**: replaced `Thread.new`/`kill` with `Timeout.timeout`.
+- **Hand-rolled Mustache replaced** with `mustache` gem: 117 lines of template engine deleted.
+- **RuboCop formatting** applied across the codebase.
+
+### Changed (breaking)
+
+- **The proposal payload key `frontmatter` → `_meta`** ([ADR 0113](docs/architecture/decisions/0113-proposal-block-meta-key.md)). A proposal entry's proposed metadata moved from the top-level `frontmatter:` key to `_meta:`, so a proposal now carries the exact `{ _meta, body }` envelope shape `accept` replays — retiring the only place the on-disk word "frontmatter" appeared as a runtime data key. `accept` reads `env.meta["_meta"]` and the `schema_valid` special case shrinks to a dig-with-fallback. No shim (house style): a proposal authored with the old key accepts with empty metadata and fails schema validation loudly. **Migration:** re-author any in-flight proposal with `_meta:` instead of `frontmatter:` — proposals are transient `queue` entries, not durable canon.
+
 ## 0.52.0 — 2026-06-09 — The authority model is a produced reference doc (ADR 0112)
 
 The "who may write what" tables stop being hand-copied across the canon docs and become a fourth generated reference doc, projected from the source of truth on every `drain`.

data/README.md

@@ -1,4 +1,4 @@
-<!-- Generated from .textus/zones/knowledge/readme.md — edit there, then run `textus drain`. Do not hand-edit README.md (it is clobbered on drain and flagged by doctor). ADR 0103. -->
+<!-- Generated from .textus/data/knowledge/readme.md — edit there, then run `textus drain`. Do not hand-edit README.md (it is clobbered on drain and flagged by doctor). ADR 0103. -->
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="assets/branding/wordmark-dark.png">
@@ -73,7 +73,7 @@ TRANSIENT     │  artifacts.feeds.*       │  proposals  (queue)           │
 
 *(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** — called a **zone** in the manifest and CLI, the term used everywhere technical from here on — routes everything they can't write directly through a **proposals queue**, and writes every successful change to an **append-only audit log**. The lanes are enforced at the protocol level, not by convention.
+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)
@@ -90,7 +90,7 @@ That's the load-bearing claim: **coordination is a protocol invariant, not a lib
 
 ```sh
 gem install textus
-textus init                          # creates .textus/ with zones + schemas
+textus init                          # creates .textus/ with lanes + schemas
 
 # an agent proposes a change — it targets a knowledge entry, but lands in proposals/
 textus propose notes.oncall --as=agent --stdin <<'JSON'
@@ -109,12 +109,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: [`examples/project/`](examples/project/)
+- **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/)
 - **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/zone 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/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.
 
 - Specification: [`SPEC.md`](SPEC.md)
 - Architecture: [`docs/architecture/README.md`](docs/architecture/README.md)
@@ -137,7 +137,7 @@ bundle exec exe/textus --help
 
 ## What `textus init` gives you
 
-You get `.textus/` with all four zone directories, baseline schemas, a starter manifest, and a gitignored `.run/` for disposable runtime state (the audit log, per-role cursors, produce locks). Roles declare capabilities; each zone declares a `kind:`, and write authority is derived from the role's capabilities crossed with the zone's kind:
+You get `.textus/` with all four lane directories under `data/`, baseline schemas, a starter manifest, and a gitignored `.run/` for disposable runtime state (the audit log, per-role cursors, produce locks). Roles declare capabilities; each lane declares a `kind:`, and write authority is derived from the role's capabilities crossed with the lane's kind:
 
 ```yaml
 roles:
@@ -145,7 +145,7 @@ roles:
   - { name: agent,      can: [propose, keep] }
   - { name: automation, can: [converge] }
 
-zones:
+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
@@ -154,12 +154,12 @@ zones:
 
 ```
 .textus/
-  manifest.yaml          # role capabilities + zone kinds + key-to-path mapping
+  manifest.yaml          # role capabilities + lane kinds + key-to-path mapping
   schemas/               # YAML field shapes per entry family
   templates/             # mustache templates for derived entries
-  hooks/                 # one .rb per hook
+  steps/                 # step subclasses: fetch/, transform/, validate/, observe/
   .gitignore             # generated — ignores .run/ and any tracked:false entries
-  zones/                 # one dir per zone; kinds + capabilities are in the manifest above
+  data/                  # one dir per lane; kinds + capabilities are in the manifest above
     knowledge/           # e.g. identity (knowledge.identity.*), voice, decisions, notes
     notebook/
     proposals/
@@ -171,13 +171,13 @@ zones:
     sentinels/           # publish bookkeeping (target sha) — regenerated on drain (ADR 0070)
 ```
 
-Manifest `path:` fields are relative to `.textus/zones/`. So `knowledge.notes.org.jane` lives at `.textus/zones/knowledge/notes/org/jane.md`.
+Manifest `path:` fields are relative to `.textus/data/`. So `knowledge.notes.org.jane` lives at `.textus/data/knowledge/notes/org/jane.md`.
 
 Read and write:
 
 ```sh
 textus get knowledge.notes.org.jane
-textus list --zone=knowledge
+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
@@ -187,80 +187,90 @@ textus audit --limit=20              # query the audit log
 
 (All verbs return JSON envelopes; `--output=json` is the default and the only format in v1.)
 
-For a worked store — knowledge entries, a staged proposal, schemas, a template, and a `drain` that publishes `CLAUDE.md` / `AGENTS.md` — see [`examples/project/`](examples/project/).
+For a worked store — knowledge entries, a staged proposal, schemas, a template, 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 × 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`, `machine`→`converge`, `queue`→`propose`). The wrong role gets `write_forbidden` naming the capability needed and the roles that hold it. ([SPEC §5](SPEC.md))
+- **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, hooks, keys, sentinels, and the audit log.
+- **`textus doctor`.** Health checks across schemas, step registrations, keys, sentinels, and the audit log.
 
-## CLI and zones
+## CLI and lanes
 
 Every command operates on one store, located in this order: `--root <path>` flag → **`TEXTUS_ROOT`** env → walk up from the working directory for a `.textus/` ([SPEC §3.1](SPEC.md)). Write verbs require `--as=<role>`, resolved as: `--as` flag → **`TEXTUS_ROLE`** env → `.textus/role` file → default `human` ([SPEC §5.1](SPEC.md)). Default roles: `human`, `agent`, `automation` (rename or add your own in the manifest's `roles:` block). All verbs accept `--output=json` and return the envelope defined in [SPEC §8](SPEC.md).
 
 - Full verb table — read, write, health, scaffolding — is in [SPEC §9](SPEC.md).
-- Zone semantics and the capability × zone-kind mapping live in [SPEC §5](SPEC.md), with the reference in [`docs/reference/zones.md`](docs/reference/zones.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: zones, entry families with schemas, registered hooks, 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 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.
 
 ## Produce and publish
 
 Produced entries (`kind: produced`) declare how they're acquired in one `source:` block (ADR 0093/0094); `drain` materialises them:
 
-- **`source: { from: project, select: [...], pluck:, sort_by:, limit:, transform: name }`** — a *projection*: textus computes the entry's 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: handler, handler: name, ttl: 1h, config: {...} }`** — *intake*: an RPC handler pulls external bytes on a `ttl` cadence; `drain` re-pulls when the entry goes stale.
-- **`source: { from: command, sources: [...] }`** — *externally generated*: an out-of-band command writes the file; textus tracks the declared `sources` for staleness.
+- **`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.
 
 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.
 
 ## Extension points
 
-textus exposes a hook DSL. Drop `.rb` files into `.textus/hooks/` (subdirectories are fine; files load alphabetically by full path). There are two kinds:
+textus extends through **steps** — subclass the right base, place the file in `.textus/steps/<kind>/`, and `drain` discovers it. Three kinds:
 
-**RPC hooks** — one handler, the framework uses what you return:
+**`Step::Fetch`** — acquires bytes for an intake entry (`from: fetch`). One class per named handler; `drain` invokes it when the entry is stale.
 
-| Event | Fires when | You return |
-|---|---|---|
-| `:resolve_handler` | an intake needs bytes | `{_meta:, body:}` |
-| `:transform_rows` | a projection builds | the reshaped rows |
-| `:validate` | `textus doctor` runs | doctor issues (or none) |
-
-**Pub-sub hooks** — 0..N handlers, fire-and-react (no return value):
+```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
+  end
+end
+```
 
-| Event(s) | Fires when |
-|---|---|
-| `:entry_written` · `:entry_deleted` · `:entry_renamed` | a write lands |
-| `:entry_fetched` | an intake-driven write lands |
-| `:entry_produced` | a produced entry materializes |
-| `:entry_published` | a produced file is copied to its target |
-| `:proposal_accepted` · `:proposal_rejected` | a proposal is resolved |
-| `:entry_fetch_started` · `:entry_fetch_failed` · `:produce_failed` | produce lifecycle |
-| `:store_loaded` · `:session_opened` | the store loads · a role connects |
+**`Step::Transform`** — reshapes projected rows for a `from: derive` entry.
 
 ```ruby
-# Inside .textus/hooks/local_file.rb
-Textus.hook do |reg|
-  reg.on(:resolve_handler, :local_file) do |config:, args:, **|
-    path = config["path"] or raise "local-file requires source.config.path"
-    {
-      _meta: { "last_fetched_at" => Time.now.utc.iso8601, "source_path" => path },
-      body: File.read(File.expand_path(path)),
-    }
+# .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
 ```
 
+**`Step::Observe`** — reacts to lifecycle events (fire-and-forget, 0..N per event):
+
 ```ruby
-Textus.hook do |reg|
-  reg.on(:transform_rows, :rank_by_recency) do |rows:, **|
-    rows.sort_by { |r| r["updated_at"].to_s }.reverse
+# .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
   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:
@@ -268,18 +278,16 @@ 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 artifacts.feeds --as=automation  # scope to one prefix
-textus get artifacts.feeds.calendar.events         # a pure read; carries a freshness verdict
+textus get artifacts.feeds.calendar.events    # a pure read; carries a freshness verdict
 ```
 
-See SPEC.md §5.10 for the full hook contract.
-
 Schemas (`.textus/schemas/<name>.yaml`) declare field shapes, per-field `maintained_by:` ownership, and an `evolution:` block (`added_in`, `deprecated_at`, `migrate_from`). Full contract in SPEC §5.8.
 
 See [`docs/how-to/agents-mcp.md`](docs/how-to/agents-mcp.md) for the agent boot → pulse loop.
 
 ## Examples
 
-[`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 `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 (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.
 
 ## Tests