textus 0.10.5 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79987029ce43500b025495ef26cefc285f7a748cdcd43388aff2fefafdf4c0ca
-  data.tar.gz: 44a9d40720a84e4e942a1c4fde9e0ed9e7773126f443b247f6d8cb27d630c204
+  metadata.gz: e14d58006851be5feba9ffa7016f5860b0ea380cef09cbf324a897d24ae56ee8
+  data.tar.gz: f928e250b5c3bc6e072c1ffc1928e68fdf61d2965d1746c121657ad4bd07ac75
 SHA512:
-  metadata.gz: a539030b1d406226bbe3d3fad03b3daee59094d3d8db351d97c9c5adc445ca8c188a7d13a16cdfaaae0c933091e6a8858c14a91362f461f25a1dce52aa04a60f
-  data.tar.gz: 83667dab7c91d4c2e9def3c2a2d605cf45d84f3fdf89bf0e6d8d25ff2b8fe668d6b71ceae0488e7ffe24970bf80e0f5eeeb13c308b2d16c9d11fc41633160dd6
+  metadata.gz: 6eb5690e16fc78f71b42a5f4308d7698684b5aa9f43a92534f73edca5fc36494be65bfab6df2d8d0832f788e7fe7496638ad23f83ee6f69f5a9950b419237745
+  data.tar.gz: aa3b5903ff1fb44dcc5d1bb3f0676bffb9d8cce99c6e6237f2d947b3486e3d0cfce53271fcf282b927ea1b2e9b1164e721ed0800ddd5ffde1644f85dd660339a

data/CHANGELOG.md

@@ -5,10 +5,111 @@ 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.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,27 @@
 
 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`. Stable; breaking changes require `textus/4`.
+- **Gem version:** semver, currently `0.11.0`. The gem version is 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.
 
+### Upgrading from textus/2
+
+textus 0.12.0 does not include a built-in migrator. If you are upgrading from
+a textus/2 store (gem versions ≤ 0.10.x), first install textus 0.11.x and run:
+
+    textus migrate --to=textus/3
+
+Then upgrade to 0.12.0. Pre-0.11.0 audit-log rows with `role: ai|script|build`
+are tolerated verbatim by the reader — no rewrite step required.
+
 ## Install
 
 ```sh
@@ -49,10 +59,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 +75,41 @@ 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.
 - **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 +117,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 +135,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 +143,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