textus 0.10.5 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79987029ce43500b025495ef26cefc285f7a748cdcd43388aff2fefafdf4c0ca
-  data.tar.gz: 44a9d40720a84e4e942a1c4fde9e0ed9e7773126f443b247f6d8cb27d630c204
+  metadata.gz: 24eda2a2cfec1884eb3c675189493827b6c0f43d5765922dbee06b70fbdc9685
+  data.tar.gz: 84e3850666541900f4c3b99f71c59b73dd142c7001f80fa9e8233d38f984719e
 SHA512:
-  metadata.gz: a539030b1d406226bbe3d3fad03b3daee59094d3d8db351d97c9c5adc445ca8c188a7d13a16cdfaaae0c933091e6a8858c14a91362f461f25a1dce52aa04a60f
-  data.tar.gz: 83667dab7c91d4c2e9def3c2a2d605cf45d84f3fdf89bf0e6d8d25ff2b8fe668d6b71ceae0488e7ffe24970bf80e0f5eeeb13c308b2d16c9d11fc41633160dd6
+  metadata.gz: d68ad56bc7891aefda10e47234f1bbd1efbfd75b576f7981c3374641efbd306dc66947b382b74c70da24bc58122090c3e0789c33b1a8291aa1005b9e6c952e2e
+  data.tar.gz: fd1c1cefad648636b4fb5aeba100d81c66472f8e1b50d07ba2239607c19179842902abf0b76925786c66868049acfd507a9a76bd07e39026dd2aa0d261ebfdad

data/ARCHITECTURE.md

@@ -2,73 +2,93 @@
 
 ```
 ┌─ Interface ────────────────────────────────────────────────┐
-│  CLI verbs:  ctx = Composition.context(store, role:)       │
-│              Composition.<use_case>(ctx).call(...)         │
+│  CLI verbs:  ops = Operations.for(store, role:)            │
+│              ops.reads.<name>.call(...)                    │
+│              ops.writes.<name>.call(...)                   │
+│              ops.refresh.<name>.call(...)                  │
 └──────────────────────┬─────────────────────────────────────┘
                        │
 ┌─ Application ────────▼─────────────────────────────────────┐
 │  Context          (per-request: store, role, correlation,  │
-│                    clock, dry_run; can_read?/can_write?)   │
-│  Composition      (factory module)                         │
+│                    clock, dry_run; can_read?/can_write?;   │
+│                    Context.system(store) for infra path)   │
+│  Operations       (facade with .reads/.writes/.refresh)    │
 │                                                            │
-│  reads/get.rb              writes/put.rb                   │
-│  refresh/worker.rb         writes/delete.rb                │
-│  refresh/orchestrator.rb   writes/build.rb                 │
-│  refresh/all.rb            writes/accept.rb                │
-│                            writes/publish.rb               │
+│  reads/{get,list,where,uid,schema_envelope,deps,rdeps,     │
+│         published,stale,validate_all,freshness,audit,      │
+│         blame,policy_explain}.rb                           │
+│  writes/{put,delete,mv,accept,reject,build,publish}.rb     │
+│  refresh/{worker,orchestrator,all}.rb                      │
 └──────────┬───────────────────────────────┬─────────────────┘
            │ uses domain                   │ uses ports
 ┌─ Domain ─▼─────────────────────────────────────────────────┐
-│  Permission             ← NEW: predicate, not Action       │
-│  Freshness::Policy      Freshness::Verdict                 │
-│  Freshness::Evaluator   Action  Outcome                    │
+│  Permission         (write/read predicate per zone)        │
+│  Freshness::{Policy,Verdict,Evaluator}                     │
+│  Action  Outcome                                           │
+│  Policy::Promotion (proposal accept gates)                 │
 └──────────────────────────────────────────┬─────────────────┘
                                            │ implements
 ┌─ Infrastructure ─────────────────────────▼─────────────────┐
-│  Store              (pure adapter — exposes ports only)    │
-│    Reader#read_envelope         Writer#write_envelope_…    │
-│    AuditLog, Staleness, Validator, Mover                   │
-│  Manifest           (incl. permission_for)                 │
-│  Hooks::Registry    EventBus     Clock                     │
-│  Refresh::Lock      Refresh::Detached                      │
-│  Infra::Publisher   (file copy + sentinel)                 │
+│  Store              (pure adapter — filesystem + hooks)    │
+│    Reader#{get,list,where,uid,deps,rdeps,published,        │
+│            stale,validate_all,read_raw_envelope,           │
+│            schema_envelope}                                │
+│    Writer#{write_envelope_to_disk,delete_envelope_from_    │
+│            disk,existing_uid_for,ensure_uid,               │
+│            enforce_name_match!,serialize_for_put}          │
+│    AuditLog, Staleness, Validator, Sentinel                │
+│  Manifest           (Entry, Rules, Schema, permission_for) │
+│  Hooks::{Registry,Dispatcher,Loader,Dsl,Builtin}           │
+│  Infra::{Publisher,EventBus,Clock,Refresh::Lock,           │
+│          Refresh::Detached}                                │
+│  Entry::{Markdown,Json,Yaml,Text}  (format strategies)     │
 └────────────────────────────────────────────────────────────┘
 
    Dependency rule: arrows point DOWN. Domain has zero outbound
    imports. Application imports Domain + Infra (via ports).
 ```
 
-## Read path (`store.get`)
+## Read path (`ops.reads.get.call(key)`)
 
-1. CLI verb (or any caller) invokes `store.get(key, as:)`.
-2. `Store#get` constructs `Reads::Get(store, orchestrator)` and calls `.call(key, as:)`.
-3. `Reads::Get#call` reads the envelope from disk via `store.reader.read_raw_envelope(key)`.
-4. Resolves `Manifest::Entry#policy` — a `Domain::Freshness::Policy` value.
+1. CLI verb (or any external caller) builds `ops = Textus::Operations.for(store, role:)` then `ops.reads.get.call(key)`.
+2. `Operations::Reads#get` returns an `Application::Reads::Get.new(ctx:, orchestrator:)` instance bound to the request context.
+3. `Reads::Get#call(key)` reads the bare envelope from disk via `@ctx.store.reader.read_raw_envelope(key)`.
+4. Resolves the manifest rules for the key via `@ctx.store.manifest.rules_for(key)` and extracts the `refresh` policy.
 5. `Domain::Freshness::Evaluator.call(policy, envelope, now:)` returns a `Verdict`.
 6. If fresh → annotate envelope (`stale: false`, `refreshing: false`) and return.
 7. Otherwise `policy.decide(verdict) → Action` (data, not behavior).
-8. `Orchestrator.execute(action, key, as)` interprets the Action:
+8. `Refresh::Orchestrator#execute(action, key:)` interprets the `Action`:
    - `Action::Return` → `Outcome::Skipped`
-   - `Action::RefreshSync` → run Worker inline → `Refreshed | Failed`
-   - `Action::RefreshTimed(budget_ms:)` → race Worker thread vs budget; on timeout, kill thread, fire `:refresh_detached`, fork+detach child, return `Outcome::Detached`
+   - `Action::RefreshSync` → run `Refresh::Worker` inline → `Refreshed | Failed`
+   - `Action::RefreshTimed(budget_ms:)` → race Worker thread vs budget; on timeout, kill thread, fire `:refresh_backgrounded`, fork+detach child, return `Outcome::Detached`
 9. Map outcome → envelope annotations (`stale`, `refreshing`, `refresh_error`) and return.
 
-## Write path (`store.put`)
+## Write path (`ops.writes.put.call(key, ...)`)
 
-1. CLI verb calls `ctx = Composition.context(store, role:)` then `Composition.writes_put(ctx).call(key, ...)`.
-2. `Writes::Put#call` checks `ctx.can_write?(zone)` — raises `write_forbidden` if denied.
-3. Delegates pure I/O to `Store::Writer#write_envelope_to_disk(key, ...)`.
-4. On success, fires `:put` event via the injected `Infra::EventBus`, including `correlation_id` from the Context.
+1. CLI verb calls `ops = Operations.for(store, role:)` then `ops.writes.put.call(key, meta:, body:, content:, if_etag:, suppress_events:)`.
+2. `Writes::Put#call` validates the key, resolves the manifest entry, and checks `@ctx.can_write?(mentry.zone)` — raises `WriteForbidden` if denied.
+3. Delegates raw I/O to `Store::Writer#write_envelope_to_disk(key, mentry:, payload:, ctx:, if_etag:)`, which:
+   - Resolves the path via `Manifest#resolve`
+   - Serializes via `Entry.for_format(...).serialize(...)`
+   - Validates against schema if declared
+   - Etag-checks if `if_etag:` provided (raises `EtagMismatch` on conflict)
+   - Writes to disk via `File.binwrite`
+   - Appends the audit row
+4. On success, publishes `:entry_put` via the bus, with `store: @ctx.with_role(@ctx.role)`, `key:`, `envelope:`, `correlation_id:`.
 
-The same pattern applies to `Writes::Delete`, `Writes::Build`, `Writes::Accept`, and `Writes::Publish`: each takes a `Context`, checks permissions at the use-case layer, then delegates raw I/O to the corresponding `Store::Writer` or `Infra::Publisher` primitive.
+The same pattern applies to `Writes::{Delete,Mv,Accept,Reject,Build,Publish}`: each takes a `Context`, checks permissions at the use-case layer, delegates raw I/O to `Store::Writer` or `Infra::Publisher`, and fires the matching event.
 
-## Refresh path (`textus refresh KEY`)
+## Refresh path (`ops.refresh.worker.run(key)`)
 
-1. CLI `Verb::Refresh` calls `Textus::Refresh.call(store, key, as:)`.
-2. That shim instantiates `Application::Refresh::Worker` and runs it.
-3. `Worker#run`:
-   - Resolves the manifest entry, looks up the `:intake` handler.
-   - Publishes `:refresh_began` via the injected `Infra::EventBus`.
+1. CLI `Verb::Refresh` builds `ops = Operations.for(store, role: "runner")` then calls `ops.refresh.worker.run(key)`.
+2. `Refresh::Worker#run(key)`:
+   - Resolves the manifest entry, looks up the intake handler via `store.registry.rpc_callable(:resolve_intake, mentry.intake_handler)`.
+   - Publishes `:refresh_started` via the bus.
    - Invokes the handler under a 30s `Timeout.timeout` budget.
    - On any error: publishes `:refresh_failed`, then re-raises (or wraps in `UsageError`).
-   - On success: normalizes the return shape, persists via `store.put`, publishes `:refreshed` (unless the etag is unchanged).
+   - On success: normalizes the return shape, persists via `Application::Writes::Put` with `suppress_events: true`, publishes `:entry_refreshed` (unless the etag is unchanged).
+3. The batch entry point is `Application::Refresh::All.call(ctx, prefix:, zone:)` which lists stale entries via `Application::Reads::Stale`, then runs `Worker#run` per entry, returning a summary envelope `{ refreshed: [...], failed: [...], skipped: [...] }`.
+
+## Infrastructure-side hook dispatch
+
+The hook bus needs an `Application::Context` even when fired from inside `Store#initialize` or other infrastructure-side code paths. `Application::Context.system(store)` returns a Context with `role: "human"` and a fresh correlation_id, designed for exactly this case — see `lib/textus/store.rb` (the `:store_loaded` publish), `lib/textus/doctor.rb` (the doctor-check view), and `lib/textus/projection.rb` (the transform_rows view).

data/CHANGELOG.md

@@ -5,10 +5,325 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 The **gem version** (`0.x.y`) is distinct from the **protocol version**
-(currently `textus/2`, embedded in every envelope as `protocol`). The protocol
-is additive within a major; a new major would change the wire string.
+(currently `textus/3`, embedded in every envelope as `protocol`). A protocol
+bump is a breaking change that requires a store migration; the gem version
+tracks both additive improvements and breaking protocol bumps independently.
 
-## [Unreleased]
+## 0.14.0 — 2026-05-26
+
+### Breaking (Ruby API only — CLI JSON output unchanged)
+
+- `Operations.reads.get.call(...)` and every other use case that returned
+  an envelope Hash now returns `Textus::Envelope` (a `Data.define`
+  instance). Call `envelope.to_h_for_wire` to recover the previous Hash
+  shape for JSON serialization. The Hash shape itself is byte-identical.
+- `Operations.writes.build.call(...)` return shape no longer includes
+  `published_leaves`. Call `Operations.writes.publish.call(...)`
+  separately for that. The CLI verb `textus build` runs both
+  automatically, so CLI users see no change.
+
+### Added
+
+- `Textus::Application::Writes::Publish` — new use case that copies
+  nested-leaf files to their `publish_each` targets. Fires
+  `:file_published`.
+- `Operations.writes.publish` — factory exposing the new use case.
+- `Textus::Envelope` (now a class, was a module) — typed accessors for
+  `protocol`, `key`, `zone`, `owner`, `path`, `format`, `uid`, `etag`,
+  `schema_ref`, `meta`, `body`, `content`, `freshness`. Methods:
+  `to_h_for_wire`, `stale?`, `refreshing?`.
+
+### Internal
+
+- `Application::Writes::Build` trimmed from 116 LOC to ~50 LOC; now
+  only materializes generator-zone entries.
+- All ~17 internal `env["..."]` call sites migrated to typed access.
+- `Envelope.build` no longer carries `# rubocop:disable
+  Metrics/ParameterLists` (the `Data.define` member list serves the
+  same role more clearly).
+
+### Reference
+
+- See [ADR 0007](docs/architecture/decisions/0007-envelope-data-class.md).
+
+## 0.13.1 — 2026-05-26
+
+### Internal
+
+- `Manifest::Entry` (260 LOC, 11 responsibilities) decomposed into:
+  - `Manifest::Entry::Parser` — raw hash → Entry value object.
+  - `Manifest::Entry::Validators::*` — one file per validation rule
+    (events, publish_each, inject_intro, index_filename, format_matrix).
+  - `Manifest::Entry` (~50 LOC) — value object with attr readers,
+    zone-kind predicates, and `publish_target_for`.
+- Each validation rule is now independently testable. Adding a new
+  rule is one new file under `lib/textus/manifest/entry/validators/`
+  plus one line in `Validators::REGISTERED`.
+- Pattern matches the existing `doctor/check/*` (~15 files, same
+  shape).
+
+### Compatibility
+
+- `Manifest::Entry` keeps all public attribute readers, predicates,
+  and `publish_target_for`. External callers consuming `Entry`
+  instances see no change. Embedders who subclassed `Entry` may
+  need adjustment.
+
+## 0.13.0 — 2026-05-26
+
+### Added
+
+- `Textus::Entry::Base` grows 7 abstract class methods that concrete
+  strategies must implement: `nested_glob`, `inject_uid`,
+  `enforce_name_match!`, `rewrite_name`, `serialize_for_put`,
+  `validate_path_extension`.
+- `Textus::Entry.infer_from_extension(ext)` — registry method
+  replacing the deleted `Manifest::EXT_TO_FORMAT` constant.
+
+### Changed
+
+- Format-specific branches in `Manifest#nested_glob`,
+  `Manifest::Entry#{validate_format_matrix!,resolve_format!,
+  validate_index_filename!}`, `Store::Writer#{ensure_uid,
+  enforce_name_match!,serialize_for_put}`, and
+  `Application::Writes::Mv#rewrite_name_for_mv!` all collapse to
+  single-line delegations to `Entry.for_format(fmt).<method>(...)`.
+- The 3 rubocop `Metrics/*` disable comments in
+  `Manifest::Entry#validate_format_matrix!` are removed; the method
+  is now 3 lines.
+
+### Removed
+
+- `Textus::Manifest::EXT_TO_FORMAT` constant. Use
+  `Textus::Entry.infer_from_extension(ext)` instead.
+
+### Reference
+
+- See [ADR 0006](docs/architecture/decisions/0006-format-strategy-extraction.md).
+
+## 0.12.6 — 2026-05-26
+
+### Examples
+
+- New `examples/project/` — demonstrates textus as the context store
+  for your own project (identity + runbooks + ADR proposal flow,
+  projecting `CLAUDE.md` and `AGENTS.md` at the repo root). Staged as
+  a fictional Rails service (`ledger`) so the entries read like a real
+  codebase, and the pre-staged ADR proposal is `accept`-runnable
+  end-to-end (carries a valid `frontmatter:` payload for its target).
+- Refined `examples/claude-plugin/` — reduced to one entry of each kind
+  (one agent, one skill, one command, one identity entry, one output,
+  one intake recipe). Removed `bin/`, `Rakefile`, `lefthook.yml`, the
+  duplicate `github_folder.rb` recipe, and the per-recipe README.
+- Fixed `examples/claude-plugin/recipes/skill_fanout.rb` — the recipe
+  routed inner writes through `store.list/put/delete`, which were
+  removed in v0.12.2. Now uses `Operations.writes.{put,delete}` against
+  the `Application::Context` that hooks actually receive.
+- Updated `spec/examples/skill_fanout_hook_spec.rb` to test the recipe
+  against a Context-like duck type, matching the runtime contract.
+
+## 0.12.5 — 2026-05-26
+
+### Documentation
+
+- Rewrote `docs/events.md` to use the textus/3 event names from
+  `Hooks::Registry::EVENTS` (`:entry_put`, `:entry_deleted`,
+  `:build_completed`, `:entry_renamed`, `:proposal_accepted`,
+  `:proposal_rejected`, `:file_published`, `:store_loaded`,
+  `:entry_refreshed`, `:refresh_started`, `:refresh_failed`,
+  `:refresh_backgrounded`). All hook examples now register against
+  events that actually exist.
+- Rewrote `docs/zones.md` to use textus/3 vocabulary (`intake` not
+  `inbox`, `write_policy:` not `writable_by:`, `rules:` not
+  `policies:`, `runner` role not `script`). Manifest fixtures bump
+  to `version: textus/3`.
+- Rewrote `ARCHITECTURE.md` to match the v0.12.4 layering:
+  `Operations` facade replaces `Composition`, `Application::Reads/Writes`
+  use cases replace direct `Store#get/#put` calls, `Store` is pure
+  infrastructure.
+- `SPEC.md` Composition → Operations sweep; removed references to
+  deleted Store delegators.
+- `docs/recipe-github-skill-bundle.md` updated to use the
+  `Operations.writes.{put,delete}` inner-write surface.
+
+## [0.12.4] — 2026-05-26
+
+### Breaking
+
+- Removed `Textus::Store#list`, `#where`, `#deps`, `#rdeps`, `#published`,
+  `#stale`, `#validate_all`, `#uid`, `#schema_envelope`, and `#fire_event`.
+  Use `Textus::Operations.for(store).reads.<name>.call(...)` instead.
+- Removed `Textus::Store::Writer#delete`, `#accept`, `#reject`. Use
+  `Textus::Operations.for(store, role:).writes.<verb>.call(...)`.
+- Removed `Textus::Store::Mover`. The mv use case lives entirely in
+  `Textus::Application::Writes::Mv` now.
+
+### Added
+
+- `Textus::Application::Reads::{List,Where,Uid,SchemaEnvelope,Deps,Rdeps,Published,Stale,ValidateAll}`.
+- `Textus::Application::Writes::Reject`.
+- `Textus::Application::Context.system(store)` for infrastructure-side
+  hook dispatch.
+
+### Internal
+
+- Internal call sites (`Projection`, `Schema::Tools`, `Application::Refresh::All`,
+  `Doctor::Check::SchemaViolations`) now route reads through `Operations`.
+
+See [ADR 0005](docs/architecture/decisions/0005-store-facade-final-removal.md).
+
+## [0.12.3] — 2026-05-26
+
+### Added
+- `textus intro` output now includes an `agent_protocol` block: envelope shape, role-resolution rules, and four canonical recipes (`read`, `write`, `propose`, `refresh`). One `textus intro` call is sufficient orientation for a fresh AI agent to operate the store without consulting `SPEC.md`.
+
+### Compatibility
+- Fully additive. All pre-0.12.3 fields on `Textus::Intro.run` retain their existing keys, types, and shapes. The wire `"protocol"` field continues to hold the string `"textus/3"`.
+
+### Examples
+- `examples/claude-plugin/.textus/templates/claude-root.mustache` now projects the new `agent_protocol` recipes into the rendered `CLAUDE.md` via the existing `inject_intro:` mechanism. A plugin's CLAUDE.md auto-projects the four recipes alongside zone authority — agents reading CLAUDE.md get full orientation without a separate `textus intro` call. This is the canonical pattern for plugin authors who want recipes inline.
+- `examples/claude-plugin/` trimmed to one of each surface (one agent, one skill, one command, one identity entry, one JSON output). Removed: the duplicate `fact-checker` variants, the `marketplace.json` projection (the JSON-output lesson is already shown by `plugin.json`), the degenerate `local_file` intake demo (pulled a file from the same store), and unused demo hooks (`rank_by_recency`, `build-stamp`). File count drops from 51 to 33; manifest from 142 to 99 lines.
+
+## [0.12.2] — 2026-05-26
+
+### Breaking changes
+
+- **Removed `Textus::Composition`.** All call sites now go through
+  `Textus::Operations.for(store, role:)`. The new facade groups use-cases
+  by kind: `ops.writes.put`, `ops.reads.get`, `ops.refresh.worker`, etc.
+  No alias, no deprecation warning — internal callers update on upgrade.
+- **Removed `Store#put / #get / #delete / #accept / #reject / #mv`.** These
+  were thin shims over `Composition`. Use `Operations` directly.
+- **Removed `Writer#put`** (the explicit "Backward-compat shim").
+
+### Internal
+
+- Added `Application::Writes::Mv` use-case wrapping `Store::Mover`.
+- Internal Application callers (Accept, Build, Refresh::Worker, Refresh::All,
+  Reads::Blame) no longer re-enter via the top-level facade.
+- Audited `spec/` and removed redundant examples (~-48 LOC; most redundancy
+  was already absorbed by call-site migration in earlier tasks).
+
+See [ADR 0004](docs/architecture/decisions/0004-operations-rename-and-store-facade-removal.md).
+
+### Migration
+
+There is no migration path for `Composition` and the Store facade methods —
+they were internal. External consumers (hooks, custom verbs, gem embedders)
+that referenced these symbols must update:
+
+```ruby
+# Before
+ctx = Textus::Composition.context(store, role: "agent")
+Textus::Composition.writes_put(ctx).call(key, body: "...")
+# or:
+store.put(key, body: "...", as: "agent")
+
+# After
+Textus::Operations.for(store, role: "agent").writes.put.call(key, body: "...")
+```
+
+## 0.12.1 — textus/2 hint fix (2026-05-26)
+
+### Fixed
+- Manifest parser now points textus/2 stores at the 0.11.x stepping-stone
+  migrator instead of the misleading "check YAML frontmatter for syntax errors"
+  hint. The protocol_version doctor check carried the correct hint already, but
+  was unreachable on textus/2 stores because `Store.discover` → `Manifest.load`
+  raises before doctor checks run. Surfaced by v0.12.0 release smoke testing.
+
+## 0.12.0 — legacy sweep (2026-05-25)
+
+### Removed (breaking)
+- `Role::LEGACY_RENAMES` (`ai`/`script`/`build` → friendly error). Legacy role
+  names now fail with the generic `InvalidRole` error.
+- `Manifest::LEGACY_ZONE_RENAMES` (`inbox` → friendly error).
+- `Hooks::Registry::LEGACY_EVENT_RENAMES` (14 legacy event names → friendly
+  error). Legacy events now fail with `unknown event: <name>`.
+- `CLI::LEGACY_VERB_RENAMES` / `CLI::LEGACY_GROUP_RENAMES` and the
+  `CommandRenamed` error class.
+- `textus migrate --to=textus/3` verb and `lib/textus/migration/**` (eight
+  files, ~924 lines).
+- Eight ad-hoc legacy-key guards in `manifest.rb` / `manifest/entry.rb` /
+  `manifest/rules.rb`.
+
+### Added
+- `Manifest::Schema.validate!` — strict-unknown-keys parser. Manifests with
+  any unrecognized key fail uniformly with `unknown key 'X' at '<jsonpath>'`.
+- ADR 0003 documenting the sweep and the 0.11.x stepping-stone path.
+
+### Changed
+- `Doctor::Check::ProtocolVersion` hint no longer suggests `textus migrate`
+  (the verb is gone); points at 0.11.x docs instead.
+- Test suite consolidated: five batches of disciplined deletions/merges
+  (−4 files, −134 LOC from the post-P6 peak). Net effect across the release:
+  test suite grew +8.2% LOC to cover new behavior (schema walker, permissive
+  audit-log tolerance).
+
+### Migration
+- **From textus/2 (gem ≤0.10.x):** install textus 0.11.x first; run
+  `textus migrate --to=textus/3`; then upgrade to 0.12.0.
+- **From 0.11.x:** drop-in upgrade.
+
+## 0.11.0 — textus/3 vocabulary redesign (2026-05-25)
+
+**BREAKING:** Protocol bumps to `textus/3`. Stores authored on 0.10.x must run `textus migrate --to=textus/3` before installing 0.11.0. `textus doctor` refuses to operate on un-migrated stores.
+
+### Renamed — actors
+
+- `ai` → `agent`, `script` → `runner`, `build` → `builder`. `Role.resolve` rejects legacy names with a one-line migration hint pointing at `--as=<new>`.
+
+### Renamed — zone
+
+- `inbox` → `intake`. Directory rename + key prefix update + manifest field handled by the migrator.
+
+### Renamed — manifest schema
+
+- `writable_by:` → `write_policy:`; new explicit `read_policy:` on zones (default `[all]`).
+- `policies:` (top-level) → `rules:`. Class rename: `Manifest::Policies` → `Manifest::Rules`.
+- `projection:` and `generator:` unified under `compute: { kind: projection|external, ... }`.
+- `reduce:` (inside compute/projection) → `transform:`.
+- `handler_allowlist:` → `intake_handler_allowlist:`.
+- `promote_requires:` (reserved in textus/2) → `promotion: { requires: [...] }` and is now **enforced** during `textus accept`.
+
+### Renamed — hook events
+
+- RPC: `:intake` → `:resolve_intake`, `:reduce` → `:transform_rows`, `:check` → `:validate`.
+- Pub-sub (object_pasttense): `:put` → `:entry_put`, `:deleted` → `:entry_deleted`, `:built` → `:build_completed`, `:mv` → `:entry_renamed`, `:accepted` → `:proposal_accepted`, `:reject` → `:proposal_rejected`, `:published` → `:file_published`, `:loaded` → `:store_loaded`, `:refreshed` → `:entry_refreshed`, `:refresh_began` → `:refresh_started`, `:refresh_detached` → `:refresh_backgrounded`. `:refresh_failed` kept.
+- DSL: single `Textus.on(event, name, **opts) { ... }`. Sugar methods (`Textus.intake`, `Textus.reduce`, `Textus.check`, etc.) and the generic `Textus.hook(...)` form removed.
+
+### Renamed — CLI
+
+- Namespaced: `textus key mv`, `textus key normalize` (was `key migrate`), `textus rule list` (was `policy list`), `textus rule explain` (was `policy explain`), `textus refresh stale` (was `refresh-stale`).
+- Top-level mutator `textus mv` removed (use `textus key mv`).
+- Envelope-render flag `--format=json` → `--output=json`. Entry-level `format:` in the manifest is unchanged.
+- Legacy spellings emit a `CommandRenamed` envelope (`code: "command_renamed"`); legacy flags emit `FlagRenamed`.
+
+### Added
+
+- `textus migrate --to=textus/3`: idempotent one-shot migrator (manifest YAML rewrite, zone directory rename `inbox` → `intake`, frontmatter owner sweep across `.md`/`.json`/`.yaml`, audit-log marker, hook DSL scanner that reports old call sites).
+- `textus doctor` check `protocol_version`: refuses textus/2 stores.
+- `promotion.requires` predicates: `schema_valid`, `human_accept`. Enforced by `textus accept` for matching rules.
+
+### Internal
+
+- `Manifest::Policies` → `Manifest::Rules` (class + file + accessor + doctor check).
+- New errors: `Textus::BadManifest`, `Textus::CommandRenamed`, `Textus::FlagRenamed`.
+- Two new domain classes under `Textus::Domain::Policy::Predicates::` for promotion gating.
+- Migration toolkit under `Textus::Migration::V3::`.
+
+### Migration notes for 0.10.x users
+
+1. Update `Gemfile`: `gem "textus", "~> 0.11"`.
+2. `bundle update textus`.
+3. `cd` to each textus store and run `textus migrate --to=textus/3`.
+4. Review the hook-scanner findings printed at the end of the migrate output. For each call site, replace `Textus.X(:name) { ... }` with the canonical `Textus.on(:Y, :name) { ... }` per the event rename table above.
+5. Run `textus doctor` — should report `ok: true`.
+6. Commit the rewritten `.textus/` directory (manifest, audit marker, possibly renamed zone dir).
+
+### Fixed
+
+- **`Doctor::Check::IllegalKeys` now honors `index_filename:`.** Previously the doctor walked every file and directory under a nested entry and flagged any whose basename failed the `[a-z0-9][a-z0-9-]*` segment regex — including `SKILL.md` itself and unrelated siblings like `references/foo.md`. With this fix, when an entry declares `index_filename:`, only the parent-directory segments leading to each matching index file are validated; sibling files and unrelated subtrees are not enumerated and are not flagged. `manifest.enumerate` already filtered correctly via the new glob; this brings the doctor check into parity. Two new specs in `spec/doctor_spec.rb` cover (a) `SKILL.md` is not flagged, (b) sibling `references/` files are not flagged. The pre-existing illegal-parent-segment case (e.g. `Bad_Name/SKILL.md`) still reports `key.illegal`.
 
 ## 0.10.5 — tech-debt cleanup + `index_filename:` + docs polish (2026-05-25)
 

data/README.md

@@ -7,17 +7,19 @@
 
 A context store for codebases that humans and AI agents both have to read and write. Dotted keys, schema-validated entries, role-gated writes, byte-copy publish, an audit log of every change. Built so an agent landing in your repo can run one command (`textus intro`) and know what to read, what to write, and what's off-limits.
 
-Reference implementation in Ruby. Wire format `textus/2`. SPEC: [`SPEC.md`](SPEC.md). Implementation notes: [`docs/`](docs/).
+Reference implementation in Ruby. Wire format `textus/3`. SPEC: [`SPEC.md`](SPEC.md). Implementation notes: [`docs/`](docs/).
 
 ## Versioning
 
 Two versions, deliberately independent:
 
-- **Protocol wire string:** `textus/2`. Stable; breaking changes require `textus/3`.
-- **Gem version:** semver, currently `0.10.3`. The gem version is decoupled from the protocol string — internal refactors bump the gem; only wire-format changes bump the protocol.
+- **Protocol wire string:** `textus/3`. Breaking changes require `textus/4`.
+- **Gem version:** semver, currently `0.14.0`. Decoupled from the protocol string — internal refactors bump the gem; only wire-format changes bump the protocol.
 
 Envelope payloads carry the `protocol` field. The gem version is irrelevant to the wire format.
 
+See [CHANGELOG.md](CHANGELOG.md) for per-release notes.
+
 ## Install
 
 ```sh
@@ -49,10 +51,10 @@ You get `.textus/` with all five zone directories, baseline schemas, an empty au
   sentinels/          # publish bookkeeping
   zones/
     identity/         # human-only — identity, voice, decisions
-    working/          # human / ai / script — day-to-day catalog
-    inbox/            # script — declared external inputs (actions)
-    review/           # ai + human — proposals awaiting accept
-    output/           # build only — computed outputs
+    working/          # human / agent / runner — day-to-day catalog
+    intake/           # runner — declared external inputs (actions)
+    review/           # agent + human — proposals awaiting accept
+    output/           # builder only — computed outputs
 ```
 
 Manifest `path:` fields are relative to `.textus/zones/`. So `working.network.org.jane` lives at `.textus/zones/working/network/org/jane.md`.
@@ -65,38 +67,43 @@ textus list --zone=working
 echo '{"_meta":{"name":"bob","org":"acme"},"body":"hi\n"}' \
   | textus put working.network.org.bob --as=human --stdin
 textus freshness --zone=output       # per-entry fresh/stale/never_refreshed/no_policy
-textus policy list                   # show every policy block
+textus rule list                     # show every rule block
 textus audit --limit=20              # query the audit log
 ```
 
-(All verbs return JSON envelopes by default; pass `--format=json` explicitly if you prefer.)
+(All verbs return JSON envelopes by default; pass `--output=json` explicitly if you prefer.)
 
 For the full shape — Claude plugin with agents, skills, commands, pending walkthrough, intake action — see [`examples/claude-plugin/`](examples/claude-plugin/).
 
 ## What ships today
 
-- **Per-entry formats.** `format: markdown | json | yaml | text` on a manifest entry. `cat .textus/zones/output/marketplace.json | jq .` works without going through textus — the in-store file *is* the consumer-shaped artifact. Structured outputs carry `_meta` at the top level (`generated_at`, `from`, `template`, `reducer`).
+- **Per-entry formats.** `format: markdown | json | yaml | text` on a manifest entry. `cat .textus/zones/output/marketplace.json | jq .` works without going through textus — the in-store file *is* the consumer-shaped artifact. Structured outputs carry `_meta` at the top level (`generated_at`, `from`, `template`, `transform`).
 - **Per-leaf publishing.** Nested entries declare `publish_each: "skills/{basename}/SKILL.md"`. Every leaf byte-copies to its consumer location on `textus build`. No more hand-mirrored `agents/` / `skills/` / `commands/` directories.
+- **Split build/publish (v0.14.0).** `Application::Writes::Build` materializes generator-zone entries; `Application::Writes::Publish` copies nested leaves to `publish_each` targets. The `textus build` CLI verb calls both and merges results, so wire output is unchanged.
+- **Typed envelopes (v0.14.0).** `Textus::Envelope` is a `Data.define` value object with typed accessors (`.meta`, `.body`, `.etag`, `.uid`, `.freshness`, …). Ruby API callers get IDE help and `NoMethodError` on typos. The CLI JSON wire format is preserved byte-for-byte via `envelope.to_h_for_wire`.
 - **Stable identity (`uid:`).** 16-char hex, auto-minted on first `put`, preserved across writes and moves. `textus key mv old.key new.key` renames in place — uid survives, audit row records `from_key`, `to_key`, `uid`. Reorganising a tree no longer breaks references.
-- **Strict key grammar.** `/^[a-z0-9][a-z0-9-]*$/`, max 8 segments × 64 chars. `textus key migrate --dry-run|--write` rewrites existing stores with illegal segments deterministically.
+- **Strict key grammar.** `/^[a-z0-9][a-z0-9-]*$/`, max 8 segments × 64 chars. `textus key normalize --dry-run|--write` rewrites existing stores with illegal segments deterministically.
 - **`textus intro`.** One-shot store orientation: zones with writers + purposes, entry families with schemas and publish targets, loaded hooks, write flows per role, the full CLI verb table. The boot signal for any agent — one tool call and it knows your store.
 - **`textus doctor`.** Health check across 9 categories: missing schemas/templates, broken hooks, illegal nested keys, sentinel drift, audit log readability, unowned schema fields, schema violations, and missing manifest files. Returns `ok: true` only when nothing is wrong; warnings and info don't flip the bit.
 - **Actionable hints on every error.** `UnknownKey` carries ranked "did you mean" suggestions. `WriteForbidden` names the role that *would* be allowed. `BadFrontmatter` tells you exactly what to rename. Printed to stderr alongside the JSON envelope on stdout.
+- **Compute.** Derived entries declare `compute: { kind: projection, ... }` (declarative rows + template) or `compute: { kind: external, ... }` (build runner produces the file; textus tracks sources for staleness). Inside projection computes, `transform:` names the row-shaping hook.
 
 Symlink-mode publish was removed; publish is `FileUtils.cp` + sentinel. Sentinels for published files live under `.textus/sentinels/<target_rel>.textus-managed.json` so consumer directories stay clean. Legacy sibling sentinels auto-migrate on next publish.
 
 ## CLI and zones
 
-All verbs accept `--format=json` and return the envelope defined in [SPEC §8](SPEC.md). Write verbs require `--as=<role>` (role resolution: `--as` → `TEXTUS_ROLE` env → `.textus/role` file → default `human`).
+All verbs accept `--output=json` and return the envelope defined in [SPEC §8](SPEC.md). Write verbs require `--as=<role>` (role resolution: `--as` → `TEXTUS_ROLE` env → `.textus/role` file → default `human`). Recognized roles: `human`, `agent`, `runner`, `builder`.
 
 - Full verb table — read, write, health, scaffolding — is in [SPEC §9](SPEC.md).
-- Zone semantics and the role/`writable_by` mapping live in [SPEC §5](SPEC.md), with a tutorial expansion in [`docs/zones.md`](docs/zones.md).
+- Zone semantics and the role/`write_policy` mapping live in [SPEC §5](SPEC.md), with a tutorial expansion in [`docs/zones.md`](docs/zones.md).
 
 `textus intro` 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.
 
 ## Compute and publish
 
-Derived entries declare a `projection:` (`select`, `pluck`, `sort_by`, `limit`, optional `reducer`) and either a template under `.textus/templates/` (markdown/text) or a templateless path that lets a reducer 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.
+Derived entries declare `compute: { kind: projection, select: ..., pluck: ..., sort_by: ..., limit: ..., transform: name }` and either 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.
+
+For externally-generated entries, declare `compute: { kind: external, sources: [...] }` — textus tracks the declared sources for staleness; the build runner produces the file.
 
 `publish_to: [path]` byte-copies a single derived file to one target. `publish_each: "template/{basename}.md"` on a nested entry byte-copies every leaf to its templated target — substitutes `{leaf}`, `{basename}`, `{key}`, `{ext}`. Sentinels for every published file live under `.textus/sentinels/`. See SPEC §5.2, §5.3, §5.12.
 
@@ -104,15 +111,15 @@ Derived entries declare a `projection:` (`select`, `pluck`, `sort_by`, `limit`,
 
 textus exposes a hook DSL. Drop `.rb` files into `.textus/hooks/` (subdirectories are fine; files load alphabetically by full path). Events:
 
-- `:intake` — bring bytes in from elsewhere (returns `{_meta:, body:}`)
-- `:reduce` — transform rows during projection (returns rows)
-- `:check` — custom doctor check (returns issues)
-- `:put`, `:deleted`, `:refreshed`, `:built`, `:accepted`, `:published`, `:mv`, `:reject`, `:loaded` — react to lifecycle events
-- `:refresh_began`, `:refresh_failed`, `:refresh_detached` — background-refresh lifecycle
+- `:resolve_intake` — bring bytes in from elsewhere (returns `{_meta:, body:}`)
+- `:transform_rows` — transform rows during projection (returns rows)
+- `:validate` — custom doctor check (returns issues)
+- `:entry_put`, `:entry_deleted`, `:entry_refreshed`, `:build_completed`, `:proposal_accepted`, `:file_published`, `:entry_renamed`, `:proposal_rejected`, `:store_loaded` — react to lifecycle events
+- `:refresh_started`, `:refresh_failed`, `:refresh_backgrounded` — background-refresh lifecycle
 
 ```ruby
 # Inside .textus/hooks/local_file.rb
-Textus.intake(:local_file) do |config:, args:, **|
+Textus.on(:resolve_intake, :local_file) do |config:, args:, **|
   path = config["path"] or raise "local-file requires intake.config.path"
   {
     _meta: { "last_refreshed_at" => Time.now.utc.iso8601, "source_path" => path },
@@ -122,7 +129,7 @@ end
 ```
 
 ```ruby
-Textus.reduce(:rank_by_recency) do |rows:, **|
+Textus.on(:transform_rows, :rank_by_recency) do |rows:, **|
   rows.sort_by { |r| r["updated_at"].to_s }.reverse
 end
 ```
@@ -130,18 +137,18 @@ end
 To keep a batch of stale intake entries current in one shot:
 
 ```sh
-textus refresh-stale --prefix=working --zone=inbox --as=script
-# or just refresh everything stale in the inbox zone:
-textus refresh-stale --zone=inbox --as=script
+textus refresh stale --prefix=working --zone=intake --as=runner
+# or just refresh everything stale in the intake zone:
+textus refresh stale --zone=intake --as=runner
 ```
 
-The primitive `Textus.hook(event, name, **opts) { ... }` is also supported. See SPEC.md §5.10 for the full contract.
+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.
 
 ## Examples
 
-[`examples/claude-plugin/`](examples/claude-plugin/) — a Claude Code plugin (`voice-tools`) whose entire content surface — agents, skills, commands, `CLAUDE.md`, `plugin.json`, `marketplace.json` — is textus-managed. Demonstrates per-entry formats, `publish_each`, intake actions, in-process reducers and hooks, the AI-propose / human-accept loop, and the `inject_intro:` flag that puts an orientation preamble at the top of `CLAUDE.md`.
+[`examples/claude-plugin/`](examples/claude-plugin/) — a Claude Code plugin (`voice-tools`) whose entire content surface — agents, skills, commands, `CLAUDE.md`, `plugin.json`, `marketplace.json` — is textus-managed. Demonstrates per-entry formats, `publish_each`, intake actions, in-process transforms and hooks, the agent-propose / human-accept loop, and the `inject_intro:` flag that puts an orientation preamble at the top of `CLAUDE.md`.
 
 ## Tests
 
@@ -149,7 +156,7 @@ Schemas (`.textus/schemas/<name>.yaml`) declare field shapes, per-field `maintai
 bundle exec rspec
 ```
 
-~490 examples; includes conformance fixtures A–I from SPEC §12.
+~637 examples; includes conformance fixtures A–I from SPEC §12.
 
 ## Code quality