textus 0.8.1 → 0.9.2

data/SPEC.md

@@ -1,6 +1,6 @@
 # textus/2 — Specification
 
-**Status:** Draft v2.0 (2026-05-19)
+**Status:** Draft v2.0 (2026-05-22, updated for 0.9.2)
 **Protocol identifier:** `textus/2`
 **Reference implementation:** Ruby gem `textus`
 
@@ -62,11 +62,11 @@ The root is `.textus/` at the project working directory. A typical v1.0 tree:
   templates/             # internal: Mustache templates referenced by derived entries
   parsers/               # internal: project-local parser extensions
   zones/                 # ALL user content lives here
-    canon/               # zone: canon (human-only)
+    identity/            # zone: identity (human-only)
     working/             # zone: working (human, ai, script)
-    intake/              # zone: intake (script — declared external inputs)
-    pending/             # zone: pending (ai proposals awaiting accept)
-    derived/             # zone: derived (build only — computed outputs)
+    inbox/               # zone: inbox (script — declared external inputs)
+    review/              # zone: review (ai/human — proposals awaiting accept)
+    output/              # zone: output (build only — computed outputs)
 ```
 
 Textus internals (`manifest.yaml`, `audit.log`, `role`, `schemas/`, `templates/`, `parsers/`) live directly under `.textus/`. **All user content lives under `.textus/zones/`.** Manifest `path:` fields are relative to `.textus/zones/` — they do **not** include the `zones/` prefix. Implementations MUST prepend `zones/` to every `path:` when resolving a key to a filesystem location.
@@ -94,21 +94,21 @@ The manifest declares: (a) which zones exist and which roles may write to each,
 version: textus/2
 
 zones:
-  - name: canon
+  - name: identity
     writable_by: [human]
   - name: working
     writable_by: [human, ai, script]
-  - name: intake
+  - name: inbox
     writable_by: [script]
-  - name: pending
-    writable_by: [ai]
-  - name: derived
+  - name: review
+    writable_by: [ai, human]
+  - name: output
     writable_by: [build]
 
 entries:
-  - key: canon.identity
-    path: canon/identity.md
-    zone: canon
+  - key: identity.self
+    path: identity/self.md
+    zone: identity
     schema: identity
 
   - key: working.network.org
@@ -118,13 +118,19 @@ entries:
     owner: textus:network
     nested: true
 
-  - key: derived.catalogs.people
-    path: derived/catalogs/people.md
-    zone: derived
+  - key: output.catalogs.people
+    path: output/catalogs/people.md
+    zone: output
     schema: null
     owner: textus:build
+
+policies:
+  - match: inbox.**
+    refresh: { ttl: 6h, on_stale: warn }
 ```
 
+**Note (0.9.2):** the default zone names were renamed from `canon|intake|pending|derived` to `identity|inbox|review|output` to align with one lifecycle axis. `working` is unchanged. Existing stores migrate by hand-editing the manifest and `mv`-ing the zone directories (see CHANGELOG). The names are conventional — the manifest is the source of truth for write permissions; rename freely.
+
 **Backward compatibility.** If the manifest omits the `zones:` block, the legacy v0.1 three-zone model is synthesized:
 
 ```yaml
@@ -184,11 +190,11 @@ Each zone declares which **roles** may write to it via `writable_by:` in the man
 
 | Zone | `writable_by` | Use case |
 |---|---|---|
-| `canon` | `[human]` | Identity, voice, immutable principles — things only a human edits. |
+| `identity` | `[human]` | Identity, voice, immutable principles — things only a human edits. (`canon` pre-0.9.2.) |
 | `working` | `[human, ai, script]` | Active project state: notes, decisions, network — what humans and agents update day-to-day. |
-| `intake` | `[script]` | Declared external inputs (calendar, feeds, scraped pages). Refreshed by external runner scripts; never by humans or AI directly. |
-| `pending` | `[ai]` | AI-generated proposals awaiting human review via `textus accept`. Lets agents stage changes without touching `working`. |
-| `derived` | `[build]` | Computed outputs (catalogs, indexes, published context). Written only by the build runner via `textus build`. |
+| `inbox` | `[script]` | Declared external inputs (calendar, feeds, scraped pages). Refreshed by external runner scripts; never by humans or AI directly. (`intake` pre-0.9.2.) |
+| `review` | `[ai, human]` | AI-generated proposals awaiting human review via `textus accept`. Lets agents stage changes without touching `working`. (`pending` pre-0.9.2.) |
+| `output` | `[build]` | Computed outputs (catalogs, indexes, published context). Written only by the build runner via `textus build`. (`derived` pre-0.9.2.) |
 
 A write is gated by the caller's **role**, supplied via `--as=<role>`. If the role is not in the target zone's `writable_by` list, the write returns `write_forbidden`.
 
@@ -250,36 +256,54 @@ A sentinel is written for each published file at `<store_root>/sentinels/<target
 
 **Per-leaf publishing.** A nested entry MAY declare `publish_each:` instead of `publish_to:` (see §4). When the build runs, every leaf reachable under the nested entry is byte-copied to the path produced by substituting `{leaf}` / `{basename}` / `{key}` / `{ext}` in the template, with a sentinel written under `<store_root>/sentinels/` at the mirrored target path. The build envelope grows a `published_leaves` array — one row per leaf, with `key`, `source`, and `target` — alongside the existing `built` array. Targets that would resolve outside the repo root are refused.
 
-### 5.4 Intake (declared, refreshed via registered fetch hook)
+### 5.4 Intake (declared, refreshed via registered intake handler)
 
-Intake entries declare an external source by naming a **fetch hook** — a registered, named function that pulls data into the entry. textus itself still makes no implicit network calls: a fetch hook only runs in intake mode when explicitly invoked by `textus refresh KEY --as=script`. The declaration is data only:
+Intake entries declare an external source by naming an **intake handler** — a registered, named function that pulls data into the entry. textus itself still makes no implicit network calls: an intake handler only runs when explicitly invoked by `textus refresh KEY --as=script` (or by `textus refresh-stale`). The declaration is data only:
 
 ```yaml
-- key: intake.calendar.events
-  zone: intake
-  source:
-    fetch: ical-events
+- key: inbox.calendar.events
+  zone: inbox
+  intake:
+    handler: ical-events
     config:
       url: "https://calendar.google.com/.../basic.ics"
-    ttl: 6h
+
+policies:
+  - match: inbox.calendar.**
+    refresh:
+      ttl: 6h
+      on_stale: warn            # warn | sync | timed_sync (default: warn)
+      sync_budget_ms: 500       # only used when on_stale: timed_sync (default: 500)
 ```
 
-`fetch` names a registered `:fetch` hook (see §5.10 for the hook contract); `config` is an opaque hash handed to the hook; `ttl` is the staleness budget. Implementations MUST reject legacy `source.from`, `source.parse`, `source.fetcher`, and `source.action` with a clear usage error.
+`handler` names a registered `:intake` hook (see §5.10 for the hook contract); `config` is an opaque hash handed to the handler. The freshness budget (`ttl`, `on_stale`, `sync_budget_ms`) lives in a top-level **`policies:`** block matched by key glob (§5.11). Implementations MUST reject legacy `intake.ttl` / `intake.on_stale` / `intake.sync_budget_ms` at manifest load with a clear migration message pointing at the top-level `policies:` block (see the 0.9.2 CHANGELOG for a hand-edit recipe). Implementations MUST also reject legacy `source.from`, `source.parse`, `source.fetcher`, `source.action`, and `source.fetch` with a usage error pointing at the `intake:` key.
+
+#### `on_stale:` semantics
+
+`on_stale:` declares what happens when `textus get` (or any read path that annotates freshness) encounters a stale intake entry. The value lives on the matching policy block, not on the entry. Vocabulary unchanged across 0.9.x: `warn | sync | timed_sync`.
 
-In intake mode the hook MUST return one of three shapes, all normalized by the store into its internal `{_meta, body, content}` representation (§5.12):
+| Value | Behaviour |
+|---|---|
+| `warn` (default) | Return the entry immediately with `stale: true`, `stale_reason:` populated, and `refreshing: false`. No blocking. |
+| `sync` | Block the `get` call, run the intake handler in-process, write the refreshed result, then return the fresh envelope. The caller waits. |
+| `timed_sync` | Like `sync`, but with a `sync_budget_ms` deadline (default 500 ms). If the handler finishes within the budget the fresh envelope is returned. If it does not finish in time, return the stale envelope (with `stale: true`, `refreshing: true`) and let the refresh complete in the background. Fires `:refresh_detached` when the deadline is exceeded. |
+
+> **Note:** `list`/`where` paths do **not** annotate freshness in 0.9.0 — only `get` does. Known limitation; full `list` freshness annotation is planned for 0.10.
+
+In intake mode the handler MUST return one of three shapes, all normalized by the store into its internal `{_meta, body, content}` representation (§5.12):
 
 - `{ _meta:, body: }` — markdown-friendly; `_meta` becomes the entry's parsed metadata hash.
 - `{ content: }` — for `format: json|yaml` entries; the parsed object becomes the entry's content.
 - `{ body: }` — raw bytes for `text` or for any format that prefers verbatim writes; the store re-parses and validates per `format:`.
 
-**Built-in fetch hooks.** `json`, `csv`, `markdown-links`, `ical-events`, `rss` are always available. They expect raw bytes in `config["bytes"]` and produce structured `_meta`/body. Built-ins do not perform I/O themselves — the caller (or an outer hook) is responsible for supplying bytes.
+**Built-in intake handlers.** `json`, `csv`, `markdown-links`, `ical-events`, `rss` are always available. They expect raw bytes in `config["bytes"]` and produce structured `_meta`/body. Built-ins do not perform I/O themselves — the caller (or an outer hook) is responsible for supplying bytes.
 
 **Refresh paths.** Two are supported:
 
-1. **In-process** — `textus refresh KEY --as=script` resolves the entry's `source.fetch`, invokes the registered `:fetch` hook with `(config:, store:, args: {})`, and writes the result under role `script`.
-2. **External runner** — a cron job or agent harness reads `textus list --zone=intake --stale --format=json`, fetches the source out of band, and pipes bytes back through `textus put KEY --as=script --stdin`.
+1. **In-process** — `textus refresh KEY --as=script` resolves the entry's `intake.handler`, invokes the registered `:intake` hook with `(config:, store:, args: {})`, and writes the result under role `script`.
+2. **External runner** — a cron job or agent harness reads `textus list --zone=intake --stale --format=json`, fetches the source out of band, and pipes bytes back through `textus put KEY --as=script --stdin`. The CLI verb `textus refresh-stale [--prefix=K] [--zone=Z]` drives this loop in one shot.
 
-Both paths share the same role gate, audit-log entry, and `:refresh` event. User-supplied hooks live in `.textus/hooks/*.rb` and auto-load at `Store#initialize` — see §5.10 for the full hook contract.
+Both paths share the same role gate, audit-log entry, and `:refreshed` event. User-supplied hooks live in `.textus/hooks/**/*.rb` and auto-load at `Store#initialize` — see §5.10 for the full hook contract.
 
 ### 5.5 Pending / accept workflow
 
@@ -365,22 +389,53 @@ Reducers are RPC hooks on the `:reduce` event. See §5.10.
 
 ### 5.10 Hooks
 
-textus has a single hook verb: `Textus.hook(event, name, **opts) { ... }`. The EVENTS table below defines every extension point. Files in `.textus/hooks/*.rb` are `load`ed at `Store#initialize` in lexical order.
+textus has a single hook verb: `Textus.hook(event, name, **opts) { ... }`. The EVENTS table below defines every extension point. Files in `.textus/hooks/**/*.rb` are `load`ed at `Store#initialize` in alphabetical order by full path.
+
+The subdirectory layout under `hooks/` is organizational only; the registered event and name come from the DSL call, not the file path. Files are loaded in alphabetical order by full path.
+
+#### Sugar surface (0.8.2+)
+
+Per-event methods are provided for ergonomics. They delegate to the same registry as `Textus.hook`.
 
-| Event    | Mode    | Args                              | Return        | Failure |
-|----------|---------|-----------------------------------|---------------|---------|
-| :fetch   | rpc     | store:, config:, args:            | {_meta:, body:}       | aborts op |
-| :reduce  | rpc     | store:, rows:, config:            | rows array            | aborts op |
-| :check   | rpc     | store:                            | issues array          | aborts doctor |
-| :put     | pubsub  | store:, key:, envelope:           | (discarded)           | logged   |
-| :delete  | pubsub  | store:, key:                      | (discarded)           | logged   |
-| :refresh | pubsub  | store:, key:, envelope:, change:  | (discarded)           | logged   |
-| :build   | pubsub  | store:, key:, envelope:, sources: | (discarded)           | logged   |
-| :accept  | pubsub  | store:, key:, target_key:         | (discarded)           | logged   |
+```ruby
+Textus.intake(:my_source)        { |config:, args:, **|  … }
+Textus.reduce(:rank_by_recency)  { |rows:, **|            … }
+Textus.check(:storage_writable)  { |store:|               … }
+Textus.put(:audit, keys: ["working.*"]) { |key:, envelope:, **| … }
+Textus.published(:git_add, keys: ["derived.*"]) { |target:, **| `git add #{target.shellescape}` }
+```
+
+The primitive `Textus.hook(:event, :name, &blk)` remains supported and is the authoritative entry point; sugar methods are thin wrappers.
+
+| Event               | Mode    | Args                                                      | Return                | Failure       |
+|---------------------|---------|-----------------------------------------------------------|-----------------------|---------------|
+| :intake             | rpc     | store:, config:, args:                                    | {_meta:, body:}       | aborts op     |
+| :reduce             | rpc     | store:, rows:, config:                                    | rows array            | aborts op     |
+| :check              | rpc     | store:                                                    | issues array          | aborts doctor |
+| :put                | pubsub  | store:, key:, envelope:                                   | (discarded)           | logged        |
+| :deleted            | pubsub  | store:, key:                                              | (discarded)           | logged        |
+| :refreshed          | pubsub  | store:, key:, envelope:, change:                          | (discarded)           | logged        |
+| :built              | pubsub  | store:, key:, envelope:, sources:                         | (discarded)           | logged        |
+| :accepted           | pubsub  | store:, key:, target_key:                                 | (discarded)           | logged        |
+| :published          | pubsub  | store:, key:, envelope:, source:, target:                 | (discarded)           | logged        |
+| :mv                 | pubsub  | store:, key:, from_key:, to_key:, envelope:               | (discarded)           | logged        |
+| :reject             | pubsub  | store:, key:, target_key:                                 | (discarded)           | logged        |
+| :loaded             | pubsub  | store:                                                    | (discarded)           | logged        |
+| :refresh_began    | pubsub  | store:, key:, mode:                                       | (discarded)           | logged        |
+| :refresh_failed     | pubsub  | store:, key:, error_class:, error_message:                | (discarded)           | logged        |
+| :refresh_detached   | pubsub  | store:, key:, started_at:, budget_ms:                     | (discarded)           | logged        |
+
+**New in 0.9.0:** `:intake` replaces `:fetch` as the RPC event name for intake handlers. `:deleted`, `:refreshed`, `:built`, `:accepted`, `:published` replace `:delete`, `:refresh`, `:build`, `:accept`, `:publish` respectively for all pub-sub callers. The three `:refresh_*` lifecycle events report the progress and failures of background (timed_sync) refreshes.
+
+**`:refresh_began`** fires immediately before an intake handler is invoked. `mode:` is one of `"sync"` or `"timed_sync"`.
+
+**`:refresh_failed`** fires when an intake handler raises. `error_class:` is the exception class name string; `error_message:` is `e.message`.
 
-**Signature invariant** — every hook receives `store:` as its first keyword argument. Event-specific kwargs follow in stable left-to-right order. The primary entity is always `key:` (for `:accept`, `key:` is the pending key being accepted and `target_key:` is the destination).
+**`:refresh_detached`** fires when a `timed_sync` refresh exceeds its budget and is handed off to a background thread. `started_at:` is an ISO-8601 UTC string; `budget_ms:` is the configured deadline as an integer.
 
-**RPC mode** — exactly one handler per (event, name). The manifest references the handler by name (`source.fetch: NAME`, `projection.reduce: NAME`). Failure or timeout aborts the calling operation.
+**Signature invariant** — every hook receives `store:` as its first keyword argument. Event-specific kwargs follow in stable left-to-right order. The primary entity is always `key:` (for `:accepted`, `key:` is the pending key being accepted and `target_key:` is the destination). For `:mv`, `key:` is present and equals `to_key:` — it is the entry's post-move home, present so `keys:` glob filters route correctly; `from_key:` is the prior key. For `:reject`, `key:` is the pending key being rejected. For `:loaded`, no key — the event observes store readiness, not an entry.
+
+**RPC mode** — exactly one handler per (event, name). The manifest references the handler by name (`intake.handler: NAME`, `projection.reduce: NAME`). Failure or timeout aborts the calling operation.
 
 **Pub-sub mode** — zero or more handlers per event. All matching handlers fire. The `keys:` option restricts a handler to keys matching one of the given globs (`File.fnmatch?` rules). Absence of `keys:` fires on every event of that type. Handler failures and 2s timeouts are logged to `audit.log` as `event_error` rows; they NEVER abort the triggering operation.
 
@@ -388,6 +443,40 @@ The `store:` argument is always a read-only store proxy. Write attempts raise `U
 
 Each handler runs under `Timeout.timeout(2)`.
 
+### 5.11 Policies (v0.9.2)
+
+A manifest MAY declare a top-level `policies:` block — a list of rule blocks matched against entry keys by glob. Each block carries one or more slots:
+
+```yaml
+policies:
+  - match: inbox.**
+    refresh: { ttl: 6h, on_stale: warn }
+
+  - match: inbox.calendar.**
+    refresh: { ttl: 30m, on_stale: timed_sync, sync_budget_ms: 800 }
+    handler_allowlist: [ical-events]
+
+  - match: review.**
+    promote_requires: [human-review]
+```
+
+**Slots (all optional within a block):**
+
+| Slot | Type | Meaning |
+|---|---|---|
+| `refresh` | `{ ttl, on_stale, sync_budget_ms }` | Freshness budget for intake entries (formerly `intake.ttl` / `intake.on_stale` / `intake.sync_budget_ms`). `on_stale` is `warn` (default), `sync`, or `timed_sync`. |
+| `handler_allowlist` | list of strings | Constrains which `intake.handler:` names may be used by entries matched by this block. Enforced by `textus doctor`. |
+| `promote_requires` | list of strings | Predicates a `review` entry must satisfy before `textus accept` will promote it. Implementations MAY use a built-in or hook-resolved predicate. Reserved for future enforcement; recorded today. |
+| `retention` | (reserved) | Slot reserved for future retention policy (cap by age / count). Implementations parse it but otherwise ignore. |
+
+**Match grammar.** `match:` is a single glob using `*` (single segment) and `**` (any depth). A literal segment ranks more specifically than `*`; `*` ranks more specifically than `**`.
+
+**Resolution.** For each key textus computes a `PolicySet { refresh, handler_allowlist, promote, retention }` by walking every block whose `match` matches the key, ranked by specificity. **Per slot, the most specific block wins.** Two blocks of equal specificity that match the same key and fill the same slot is a manifest error reported by `textus doctor` (`policy_ambiguity`).
+
+**Read surface.** `textus policy list` dumps every block. `textus policy explain KEY` shows the resolved `PolicySet` for one key plus which block won each slot.
+
+**Migration.** No migrator ships in 0.9.2 — the gem is pre-1.0 with no known outside upgraders. Existing 0.9.1 stores hand-edit the manifest to move each entry's legacy `intake.ttl` / `intake.on_stale` / `intake.sync_budget_ms` into a top-level `policies:` block matched by the entry's exact key. See the 0.9.2 CHANGELOG for the recipe.
+
 ### 5.12 Storage formats (v1.2)
 
 An entry's `format:` selects a storage strategy. All strategies expose the same `parse(bytes) → {_meta, body, content}` and `serialize(meta:, body:, content:) → bytes` contract. The store, audit, etag, and projection layers operate on the parsed shape; only (de)serialization differs.
@@ -474,14 +563,17 @@ Every successful CLI response (`--format=json`) is a single JSON envelope:
   "body": "Short body in Markdown.\n",
   "etag": "sha256:8f3c…",
   "schema_ref": "person",
-  "uid": "a1b2c3d4e5f60718"
+  "uid": "a1b2c3d4e5f60718",
+  "stale": false,
+  "stale_reason": null,
+  "refreshing": false
 }
 ```
 
 **Field rules:**
 - `protocol` MUST be the exact string `textus/2`.
 - `key` MUST be the canonical resolved key.
-- `zone` MUST be one of the zones declared in the manifest (`canon`, `working`, `intake`, `pending`, `derived` for the default v1.0 model; legacy v0.1 manifests synthesize `fixed`, `state`, `derived` per §4).
+- `zone` MUST be one of the zones declared in the manifest (`identity`, `working`, `inbox`, `review`, `output` for the default 0.9.2 model; legacy v0.1 manifests synthesize `fixed`, `state`, `derived` per §4).
 - `path` MUST be an absolute filesystem path.
 - `format` MUST be one of `markdown`, `json`, `yaml`, `text` (§5.12). Absent envelopes are treated as `markdown` for back-compat.
 - `body` is the raw on-disk bytes as a UTF-8 string for every format.
@@ -489,6 +581,11 @@ Every successful CLI response (`--format=json`) is a single JSON envelope:
 - `etag` MUST be `sha256:<hex>` of the raw file bytes, computed identically for every format.
 - `schema_ref` MAY be `null` for entries in subtrees with `schema: null`.
 - `uid` is the stable Textus UID (§7) if the entry carries one, else `null`. Always present in the envelope.
+- `stale` is `true` when the entry's TTL has elapsed and the data has not yet been refreshed; `false` otherwise. Only populated for entries matched by a `refresh:` policy slot (typically `inbox` zone); always `false` elsewhere. (0.9.0+; resolves through `policies:` since 0.9.2.)
+- `stale_reason` is a short human-readable string describing why the entry is stale (e.g. `"ttl_exceeded"`, `"never_refreshed"`), or `null` when `stale` is `false`. (0.9.0+)
+- `refreshing` is `true` when a `timed_sync` background refresh is in flight for this entry; `false` otherwise. Callers observing `stale: true, refreshing: true` SHOULD retry after a short delay. (0.9.0+)
+
+> **Note:** `list`/`where` envelopes do **not** include `stale`, `stale_reason`, or `refreshing` in 0.9.0 — freshness annotation is only provided by `get`. This is a known limitation.
 
 Errors use a distinct envelope:
 
@@ -522,11 +619,14 @@ All verbs accept `--format=json` and emit a canonical envelope (success or error
 
 | Verb | Reads / writes | Role required |
 |---|---|---|
-| `list [--prefix=K] [--zone=Z] [--stale]` | read | any |
+| `list [--prefix=K] [--zone=Z]` | read | any |
 | `where K` | read | any |
 | `get K` | read | any |
 | `schema show K` | read | any |
-| `stale [--prefix=K] [--strict]` | read | any |
+| `freshness [--prefix=K] [--zone=Z]` | read | any |
+| `audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]` | read | any |
+| `blame KEY` | read | any |
+| `policy list` / `policy explain KEY` | read | any |
 | `deps K` / `rdeps K` | read | any |
 | `published` | read | any |
 | `hook list` | read | any |
@@ -535,6 +635,7 @@ All verbs accept `--format=json` and emit a canonical envelope (success or error
 | `put K --stdin --as=R [--fetch=NAME]` | write | per zone |
 | `delete K --if-etag=E --as=R` | write | per zone |
 | `refresh K --as=script` | write | per zone (typically `script`) |
+| `refresh-stale [--prefix=K] [--zone=Z] [--as=script]` | write | per zone (typically `script`) |
 | `build [--prefix=K] [--dry-run]` | write | `build` (default) |
 | `accept K --as=human` | write | `human` |
 | `init` | write | `human` |
@@ -544,6 +645,8 @@ All verbs accept `--format=json` and emit a canonical envelope (success or error
 | `key uid K` | read | any |
 | `hook run NAME` | write | any |
 
+**0.9.2 breaking:** `textus stale` was removed; use `textus freshness` (same input, slightly richer output shape — see below).
+
 **`put` input** (read from stdin when `--stdin` is given):
 
 ```json
@@ -554,19 +657,25 @@ All verbs accept `--format=json` and emit a canonical envelope (success or error
 
 `if_etag` is optional on `put`, required on `delete`. When provided, the write fails with `etag_mismatch` if the on-disk file's etag differs. When omitted on `put`, the write is unconditional (last-writer-wins).
 
-**`textus stale` output shape:**
+**`textus freshness` output shape:**
 
 ```json
-[
-  { "key": "derived.catalogs.skills",
-    "path": "/abs/.textus/zones/derived/catalogs/skills.md",
-    "generator": { "command": "rake catalog:skills",
-                   "sources": ["working.projects", "working.network"] },
-    "reason": "source 'working.projects' modified after generated.at" }
-]
+{
+  "verb": "freshness",
+  "rows": [
+    { "key": "inbox.upstream.notes",
+      "zone": "inbox",
+      "last_refreshed_at": "2026-05-21T13:21:17Z",
+      "age_seconds": 65000,
+      "ttl_seconds": 43200,
+      "on_stale": "warn",
+      "status": "stale",
+      "next_due_at": "2026-05-22T01:21:17Z" }
+  ]
+}
 ```
 
-`textus build` consumes the stale list and executes each `generator.command` itself, writing results back through `put` under the `build` role. `--dry-run` prints the plan without executing.
+`textus freshness` replaced `textus stale` in 0.9.2. Each row reports one entry's verdict (`fresh`, `stale`, `never_refreshed`, or `no_policy`) against its matched `refresh:` policy. `textus build` consumes its own staleness signal and executes derived entries' projections under the `build` role; `--dry-run` prints the plan without executing.
 
 `textus accept K --as=human` promotes a pending entry into its target zone: it copies the patch body into the target key, deletes the pending entry, and writes one audit line per side (§audit). Only the `human` role may invoke `accept`.
 
@@ -594,7 +703,7 @@ Every `Textus::Error` exposes `code`, `message`, and an optional `hint:`. The hi
 - Breaking changes (renamed/removed envelope fields, zone semantics, key grammar) require a new wire string `textus/3`.
 - Implementations MUST reject envelopes whose `protocol` they do not recognize.
 
-The reference Ruby gem follows semver independently. The current gem version is `0.8.0`, which speaks `textus/2`.
+The reference Ruby gem follows semver independently. The current gem version is `0.9.2`, which speaks `textus/2`.
 
 ## 12. Conformance fixtures
 
@@ -604,13 +713,13 @@ A conformant implementation MUST pass these fixtures (the reference test suite s
 Given a manifest with `working.network.org` → `working/network/org` (nested), schema `person`, and a file `.textus/zones/working/network/org/jane.md` with valid frontmatter, `textus get working.network.org.jane --format=json` returns the canonical envelope with `etag` matching the file's sha256.
 
 **Fixture B — Role gate on write:**
-Given a manifest entry where `key: canon.identity` lives in the `canon` zone (human-only), `textus put canon.identity --stdin --as=ai` (with any valid input) returns the error envelope with `code: "write_forbidden"` and exit code 1.
+Given a manifest entry where `key: identity.self` lives in the `identity` zone (human-only), `textus put identity.self --stdin --as=ai` (with any valid input) returns the error envelope with `code: "write_forbidden"` and exit code 1.
 
 **Fixture C — Schema violation:**
 Given the `person` schema and a `put` whose frontmatter omits `relationship`, the result is the error envelope with `code: "schema_violation"`, `details.missing: ["relationship"]`, and exit code 1.
 
 **Fixture D — Staleness detection:**
-Given a manifest entry `derived.catalogs.skills` with `generator.sources: [working.projects]`, and a working-zone entry under `working.projects` whose file mtime is newer than the derived entry's `generated.at` frontmatter timestamp, `textus stale --format=json` includes the derived entry with its declared `generator.command` and a `reason` field naming the stale source. Calling `textus stale` does NOT execute the command.
+Given a manifest entry `inbox.notes` matched by a `policies: [{ match: inbox.notes, refresh: { ttl: 1h } }]` block and an envelope on disk whose `_meta.last_refreshed_at` is older than `now - ttl`, `textus freshness --format=json` includes a row for `inbox.notes` with `status: "stale"`. Calling `textus freshness` does NOT trigger a refresh.
 
 **Fixture E — Projection build:**
 Given a manifest entry `derived.catalogs.skills` whose `projection` clause selects fields from `working.projects` entries, `textus build derived.catalogs.skills` materializes the derived entry on disk with frontmatter and body matching the projected shape, and updates `generated.at` to the build timestamp.
@@ -643,6 +752,28 @@ Given a pending entry `pending.canon.identity.patch` proposing a change to `cano
 
 - **Why not vector embeddings?** Different problem. textus is for facts agents act on deterministically; embeddings are for fuzzy retrieval. They compose — index a textus tree into a vector store if you need both.
 
+## 13.1 Layered architecture (internal, 0.9.0+)
+
+Textus internals are organized into four layers. The dependency rule is one-way — each layer may only import from the layer beneath it.
+
+- **Interface** (`lib/textus/cli/`) — CLI verbs. Parses flags, calls a use case, formats JSON.
+- **Application** (`lib/textus/application/`) — Use cases: `Reads::Get`, `Refresh::Worker`, `Refresh::Orchestrator`, `Refresh::All`. Orchestrate domain + infra; no business rules.
+- **Domain** (`lib/textus/domain/`) — Pure values: `Freshness::Policy`, `Action`, `Outcome`, `Freshness::Verdict`, `Freshness::Evaluator`. No I/O, no globals, testable without disk.
+- **Infrastructure** (`lib/textus/infra/`) — Adapters: `EventBus`, `Clock`, `Refresh::Lock`, `Refresh::Detached`. Wrap OS / library primitives.
+
+The `lib/textus/store/`, `lib/textus/manifest/`, `lib/textus/hooks/` namespaces are infrastructure adapters that predate this split and remain at their existing paths for backward-compat with the plugin DSL.
+
+Plugin authors interact only with the Hook DSL (`Textus.intake`, `Textus.refreshed`, etc.) and the manifest YAML schema. The layering is internal and may evolve.
+
+As of 0.9.1, the write path mirrors the read path:
+
+- **Reads** flow through `Application::Reads::Get`, which takes a `Context` and dispatches refresh via `Application::Refresh::Orchestrator`.
+- **Writes** flow through `Application::Writes::{Put,Delete,Build,Accept,Publish}`, each taking a `Context`. Permission checks happen at the use-case layer (via `Context#can_write?`); I/O happens at `Store::Writer#write_envelope_to_disk` (pure).
+- `Application::Context` is the universal request object: it carries `store`, `role`, `correlation_id`, `clock`, and `dry_run`. Use cases never thread these as separate kwargs.
+- `Textus::Composition` is the factory module CLI verbs (and future MCP server / HTTP shim) use to construct Contexts and use cases.
+
+See `ARCHITECTURE.md` for an ASCII diagram and the full read-path walkthrough.
+
 ## 14. Open questions (v2.x scope)
 
 - **Locking on `put`:** the reference impl uses sha256 etags. Should the spec also define a file-lock fallback for systems where read-before-write is racy?
@@ -662,7 +793,7 @@ A `textus/2` implementation MUST:
 - [ ] Refuse writes whose resolved role is not in the target zone's `writable_by` list with `write_forbidden`.
 - [ ] Return envelopes matching the shape in §8 exactly (with `_meta`, not `frontmatter`).
 - [ ] Use the error codes in §8 and the exit-code table.
-- [ ] Implement `textus stale` per §5.1 and §9, comparing each derived entry's `generator.sources` against its `generated.at` timestamp without invoking any commands.
+- [ ] Implement `textus freshness` per §5.1 and §9, walking each entry, matching it against the top-level `policies:` block, and reporting `fresh|stale|never_refreshed|no_policy` without invoking any refresh.
 - [ ] Pass the conformance fixtures A–I in §12.
 
 A `textus/2` implementation MAY:

data/docs/architecture.md

@@ -31,10 +31,10 @@ CLI is the single entry point. It parses argv and dispatches each verb to whiche
 
 `Store` is a thin facade (~110 LOC) that holds `Manifest`, `Hooks::Registry`, `Hooks::Dispatcher`, and the lazy `Store::AuditLog`, then delegates verbs to a small set of focused collaborators:
 
-- **`Store::Reader`** — owns `get`, `list`, `where`, `uid`, `deps`, `rdeps`, `published`, `schema_envelope`, `stale`, `validate_all`. The only module that reads working-store entry files.
+- **`Store::Reader`** — owns `get`, `list`, `where`, `uid`, `deps`, `rdeps`, `published`, `schema_envelope`, `validate_all`. The only module that reads working-store entry files. (`freshness` lives in `Application::Reads::Freshness` since 0.9.2; the legacy `stale` shim was removed.)
 - **`Store::Writer`** — owns `put`, `delete`, `accept`. Handles serialization, uid minting, etag check, role gate, audit append, and event publication. The only module that writes working-store entry files.
 - **`Store::Mover`** — owns `mv` (same-zone rename) with uid preservation and one audit row.
-- **`Store::Validator`** / **`Store::Staleness`** — back the `validate_all` / `stale` reads. Take explicit collaborators (`reader:`, `manifest:`, `audit_log:`, `schema_for:`) instead of the full store.
+- **`Store::Validator`** / **`Store::Staleness`** — back the `validate_all` / `freshness` reads. Take explicit collaborators (`reader:`, `manifest:`, `audit_log:`, `schema_for:`) instead of the full store.
 
 Shared value modules and primitives consumed by Reader/Writer/Mover:
 
@@ -72,7 +72,7 @@ Builder ──► Pipeline ──► LoadSources ──► Project ──► Ren
 Declared in the manifest, loaded on demand, dispatched by `Store` and `Refresh`.
 
 - **`Hooks::Registry`** — loads one `.rb` per hook from `.textus/hooks/`, registers callables under their `(event, name)`. Single source of truth via the `EVENTS` table (rpc vs pubsub, arg shape, failure semantics). For pub-sub events it also forwards registrations to the `Hooks::Dispatcher`.
-- **`Hooks::Dispatcher`** — first-class pub/sub for lifecycle events (`:put`, `:delete`, `:refresh`, `:build`, `:accept`). Owns the 2-second per-handler timeout and the audit-on-failure middleware (raising handlers do not abort the write; they produce an `event_error` audit row). Embedded callers can `store.dispatcher.subscribe(:put, :name) { ... }` outside `.textus/hooks/`.
+- **`Hooks::Dispatcher`** — first-class pub/sub for lifecycle events (`:put`, `:delete`, `:refresh`, `:build`, `:accept`, `:publish`, `:mv`, `:reject`, `:loaded`). Owns the 2-second per-handler timeout and the audit-on-failure middleware (raising handlers do not abort the write; they produce an `event_error` audit row). Embedded callers can `store.dispatcher.subscribe(:put, :name) { ... }` outside `.textus/hooks/`.
 - **`Hooks::Builtin`** — ships built-in `:fetch` hooks (e.g. json, csv, ical-events, rss) available without user-supplied hooks.
 - **`Refresh`** — `refresh` verb: looks up the `:fetch` hook for a key, invokes it, normalizes the result by declared format, writes through `Store::Writer` with an etag check.
 
@@ -101,7 +101,25 @@ First-class CLI verbs that don't fit the read/write/build axes. Read-mostly; sid
 - **Store::Writer is the only module that writes to working-store entry files.** Reader reads them; Mover moves them within a zone. Init, MigrateKeys, Publisher, Builder, AuditLog write to **other** parts of `.textus/` (scaffolding, sentinels, audit log, derived targets) — they do not edit existing entry files behind the Store facade's back.
 - **`name:` frontmatter matches file basename.** Enforced on read and write.
 - **Zone semantics live in the manifest, not in directory names.** A project may rename `state/` to anything; the manifest declares which zone each entry belongs to.
-- **`stale` does not execute anything.** It walks `zone: derived` entries with a `generator:` block, compares `generated.at` against source mtimes, and returns offenders **plus their declared `command`**. Build runners execute. This is the §5.1 "dataflow oracle, not executor" boundary.
+- **`freshness` does not execute anything.** It walks every entry, matches it against the top-level `policies:` block, and returns each entry's verdict (`fresh|stale|never_refreshed|no_policy`). Build runners execute. This is the §5.1 "dataflow oracle, not executor" boundary.
+
+## Policy resolution
+
+Top-level `policies:` are parsed into a `Manifest::Policies` collection. Resolution is by key, slot-aware, most-specific-wins:
+
+```
+Manifest#policies_for(key)
+   └─► Manifest::Policies#for(key)
+          ├─► Policy::Matcher (specificity ranking)
+          └─► returns PolicySet { refresh, handler_allowlist, promote, retention }
+                                 │
+                                 ▼
+                       consumers: Refresh::Worker
+                                  Doctor checks
+                                  Reads::PolicyExplain
+```
+
+Two blocks at the same specificity filling the same slot for the same key is a manifest error reported by `doctor` (`policy_ambiguity`). Custom-named zones see no special handling — policies match against the full key.
 
 ## What this implementation deliberately leaves out
 

data/docs/conventions.md

@@ -5,9 +5,9 @@ Guidelines for shaping a `.textus/` tree, naming keys, organising schemas, and i
 ## Key naming
 
 - **Segments are lowercase, kebab- or snake-case.** The grammar `^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$` is the hard limit. Prefer `acme-dashboard` over `acmedashboard` when there's a natural word break.
-- **Lead with the zone in the key path.** `state.projects.acme.dashboard`, not `projects.acme.dashboard`. The zone prefix makes it obvious from the key alone whether a write will be accepted.
-- **Mirror the directory structure.** If `state.projects.acme.dashboard` resolves to `state/projects/acme/dashboard.md`, do not invent shortcuts that diverge.
-- **Don't pluralise the leaf.** `state.network.org.jane`, not `state.network.org.janes`. Pluralise the container, not the entry.
+- **Lead with the zone in the key path.** `working.projects.acme.dashboard`, not `projects.acme.dashboard`. The zone prefix makes it obvious from the key alone whether a write will be accepted.
+- **Mirror the directory structure.** If `working.projects.acme.dashboard` resolves to `working/projects/acme/dashboard.md`, do not invent shortcuts that diverge.
+- **Don't pluralise the leaf.** `working.network.org.jane`, not `working.network.org.janes`. Pluralise the container, not the entry.
 
 ## Zone layout
 
@@ -17,12 +17,17 @@ Recommended top-level layout — the spec allows alternatives, but this is what
 .textus/
   manifest.yaml
   schemas/        # YAML schema definitions
-  fixed/          # identity, voice, canon — humans only
-  state/          # agent-writable working memory
-  derived/        # generated by build runners — never edit by hand
+  zones/
+    identity/     # identity, voice, canon — humans only
+    working/      # agent-writable working memory
+    inbox/        # script-fed external inputs
+    review/       # AI proposals awaiting accept
+    output/       # generated by build runners — never edit by hand
 ```
 
-Inside `state/`, group by **domain** (people, projects, decisions, runbooks), not by file type or date. Inside `derived/`, group by **producer** (`derived/catalogs/`, `derived/indexes/`) so it's clear which build job owns what.
+Inside `working/`, group by **domain** (people, projects, decisions, runbooks), not by file type or date. Inside `output/`, group by **producer** (`output/catalogs/`, `output/indexes/`) so it's clear which build job owns what.
+
+> **0.9.2 rename.** Default zone names moved off historical artifact terms (`canon/intake/pending/derived`) to one lifecycle axis (`identity/inbox/review/output`); `working` is unchanged. Upgrade existing stores by hand-editing the manifest and `mv`-ing the zone directories (see 0.9.2 CHANGELOG).
 
 ## Schema design
 
@@ -43,27 +48,29 @@ Tooling around `git blame` or audit logs may filter on owner; the gem itself onl
 
 ## Derived entries and build runners
 
-**Always** declare `generator:` on derived entries that participate in any build pipeline. Without it, `textus stale` cannot help — the entry is just an opaque file.
+**Always** declare `generator:` on derived entries that participate in any build pipeline. Without it, `textus freshness` cannot help — the entry is just an opaque file.
 
 ```yaml
-- key: derived.catalogs.skills
-  path: derived/catalogs/skills
-  zone: derived
+- key: output.catalogs.skills
+  path: output/catalogs/skills
+  zone: output
   schema: null
   owner: build:catalog-skills
   generator:
     command: "rake catalog:skills"
     sources:
-      - state.projects
-      - state.network
+      - working.projects
+      - working.network
 ```
 
 **The build runner is responsible for writing the `generated:` frontmatter block** when it regenerates. The gem will never synthesize it. A typical lefthook / rake / just integration looks like:
 
 ```sh
-textus stale --format=json | jq -r '.[] | .generator.command' | sort -u | while read cmd; do
-  eval "$cmd"
-done
+textus freshness --format=json \
+  | jq -r '.rows[] | select(.status == "stale") | .key' \
+  | while read key; do
+      textus refresh "$key" --as=script
+    done
 ```
 
 `generated.from` SHOULD match `generator.sources` from the manifest — they're the same list, recorded in two places so a diffable file proves what was actually consumed.
@@ -82,4 +89,4 @@ For multi-writer environments, **always pass `if_etag`** on `put`. The gem treat
 
 - **MCP servers**: a thin server that exposes `textus get` and `textus put` as tools is the recommended way to give Claude/agents access. Don't bake MCP into this gem.
 - **Vector stores**: index `body` content into a vector store if you want fuzzy retrieval. `frontmatter` stays in textus as the source of truth for deterministic facts.
-- **CI**: run `textus stale` (or `textus list` + schema validation) in CI to catch drift between derived entries and their sources.
+- **CI**: run `textus freshness` (or `textus list` + schema validation) in CI to catch drift between derived entries and their sources.