textus 0.10.0 → 0.10.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 198dc9a4561b79bf4da22a2f890caa5da2764b8d82b1665b506d6c4c8c0e3fe3
-  data.tar.gz: dc5333c3605b7b05174f4b290fcb63260aad7ea089da900f0b3325cf3823d83c
+  metadata.gz: 37ec398fd3e4bc171cdd4de0452b16de423d899103b1b66c31411bc296260115
+  data.tar.gz: 47f2a2f213698adfa9f7ba8019d05b80d704aaf1de7ac6cf2a96ceb33642b966
 SHA512:
-  metadata.gz: f9e08a7a3fc46732dcd9458114765a54e3f8d2aca08b3ead6b70ecfc2782c0e9fec5eec38fc933cef9582c5943db52973c8bb06e544c02afec468dc50bbc8797
-  data.tar.gz: 9cb891ae4ce1d7583af7546e16e1f1a23d8d88af105430d31c2eb3fd4e25af6df2a60c5677c810a3d11f01582d7500a18d681b8996e9f2f5da1948e32ec2a39f
+  metadata.gz: 4cccb93db3f1e94f75a12ff4513c51d6c95177e2f530b94a8ba9220cefc9e0bce949acc187f5546a6c8c68a6ebf70e3d79a890ebe32e8c2e66831e10309ee4b0
+  data.tar.gz: af03c10214acc105d2d7a0921c486d926446b3f7d2763172ab6199c54322682d1a40aced0966054899067840686fedbe52cbf3e9d3714dbabae8693893149467

data/ARCHITECTURE.md

@@ -0,0 +1,74 @@
+# Textus architecture
+
+```
+┌─ Interface ────────────────────────────────────────────────┐
+│  CLI verbs:  ctx = Composition.context(store, role:)       │
+│              Composition.<use_case>(ctx).call(...)         │
+└──────────────────────┬─────────────────────────────────────┘
+                       │
+┌─ Application ────────▼─────────────────────────────────────┐
+│  Context          (per-request: store, role, correlation,  │
+│                    clock, dry_run; can_read?/can_write?)   │
+│  Composition      (factory module)                         │
+│                                                            │
+│  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               │
+└──────────┬───────────────────────────────┬─────────────────┘
+           │ uses domain                   │ uses ports
+┌─ Domain ─▼─────────────────────────────────────────────────┐
+│  Permission             ← NEW: predicate, not Action       │
+│  Freshness::Policy      Freshness::Verdict                 │
+│  Freshness::Evaluator   Action  Outcome                    │
+└──────────────────────────────────────────┬─────────────────┘
+                                           │ 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)                 │
+└────────────────────────────────────────────────────────────┘
+
+   Dependency rule: arrows point DOWN. Domain has zero outbound
+   imports. Application imports Domain + Infra (via ports).
+```
+
+## Read path (`store.get`)
+
+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.
+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:
+   - `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`
+9. Map outcome → envelope annotations (`stale`, `refreshing`, `refresh_error`) and return.
+
+## Write path (`store.put`)
+
+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.
+
+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.
+
+## Refresh path (`textus refresh 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`.
+   - 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).

data/CHANGELOG.md

@@ -8,6 +8,48 @@ 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.
 
+## 0.10.2 — Doctor and store cleanup (2026-05-23)
+
+Patch release. Internal cleanup: extracts `Store::Sentinel`, moves audit-log integrity into `Store::AuditLog`, surfaces previously-swallowed schema parse errors, and tidies two doctor checks. No CLI, wire-protocol, or behavioral changes for plugin authors. Sentinel JSON shape changes (repo-relative paths) are forward-compatible; legacy absolute paths are still read correctly.
+
+### Added
+
+- `Textus::Store::Sentinel` value object owning the sentinel JSON shape (`source`/`target`/`sha256`/`mode`) and the on-disk path layout. Repo-relative paths on write; legacy absolute paths still accepted on read.
+- `Textus::Store::AuditLog#verify_integrity` returns line-by-line integrity violations as `{lineno, reason, detail}` hashes.
+- `Textus::Schema#unowned_fields` returns field names whose spec lacks `maintained_by`.
+- New doctor check `schema_parse_error` (error level) surfaces YAML parse failures on `schemas/*.yaml`. Previously these were silently rescued in `UnownedSchemaFields`, leaving operators with no signal.
+
+### Changed
+
+- `Infra::Publisher` delegates sentinel I/O to `Store::Sentinel`. The sentinel JSON now stores repo-relative `source`/`target` so example trees can be committed without leaking author paths.
+- `Doctor::Check::Sentinels` delegates parse/orphan/drift detection to `Store::Sentinel`. Drops `rubocop:disable Metrics/BlockLength`.
+- `Doctor::Check::AuditLog` delegates parsing to `Store::AuditLog#verify_integrity`. Drops `rubocop:disable Metrics/BlockLength`.
+- `Doctor::Check::ManifestFiles` uses `Textus::Key::Path.resolve` instead of reimplementing leaf-path math.
+- `Doctor::Check::UnownedSchemaFields` uses `Schema#unowned_fields` instead of reaching into `schema.fields` and the raw `maintained_by` Hash key.
+- `examples/claude-plugin/.gitignore` no longer excludes `.textus/sentinels/`. The example's sentinels are now committed with repo-relative paths.
+
+### Documentation
+
+- `SPEC.md` builtin doctor-check list updated to include `schema_parse_error`, and brings the prose up to date with three checks shipped in 0.9.x/0.10.0 that were missing from the list (`policy_ambiguity`, `handler_allowlist`, `legacy_intake_fields`).
+
+## 0.10.1 — Documentation refresh and spec hygiene (2026-05-22)
+
+Lightweight maintenance release: documentation refresh plus spec-suite hygiene. No `lib/` changes; no CLI, wire-protocol, or behavioral changes.
+
+### Changed
+
+- `docs/architecture.md` deleted. `ARCHITECTURE.md` is now the single source of truth for the layered architecture. Inbound links in `docs/zones.md`, `docs/events.md`, and `textus.gemspec` updated.
+- `SPEC.md` examples and CLI snippets refer to the post-0.9.2 default zone names (`identity` / `inbox` / `review` / `output`) instead of the pre-rename `canon` / `intake` / `pending` / `derived`. Prose that explicitly explains the 0.9.2 rename — including the v0.1 back-compat manifest example and the zone-rename table — is preserved.
+- `README.md` `refresh-stale` examples switched to `--zone=inbox`; the `cat .textus/zones/...` example points at the `output` zone.
+- `ARCHITECTURE.md` layer diagram references `Infra::Publisher` instead of bare `Publisher`.
+- `docs/zones.md` references `Textus::Infra::Publisher` instead of bare `Publisher`.
+
+### Testing
+
+- Deleted redundant `spec/proposal_spec.rb` (the same `"2026-05-19-add-bob"` fixture is covered more thoroughly by `spec/application/writes/accept_spec.rb`, the canonical post-0.9.1 home for Application-layer write tests).
+- Extracted `shared_context "textus_store_fixture"` into `spec/support/fixtures.rb`; 28 specs adopt it, replacing the repeated `let(:tmp)` / `let(:root)` / `after { FileUtils.remove_entry(tmp) }` triplet. `spec/spec_helper.rb` now autoloads `spec/support/**/*.rb`.
+- Fixed an `instance_variable_set(:@intake_handler, nil)` anti-pattern in `spec/refresh_spec.rb` — the "no intake declared" case now uses a manifest entry that was never given an intake handler, instead of mutating a private ivar after construction.
+
 ## 0.10.0 — Shim removal, signal-based zone detection, Builder extraction (2026-05-22)
 
 ### Breaking — Ruby API

data/README.md

@@ -77,7 +77,7 @@ For the full shape — Claude plugin with agents, skills, commands, pending walk
 
 ## What ships today
 
-- **Per-entry formats.** `format: markdown | json | yaml | text` on a manifest entry. `cat .textus/zones/derived/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`, `reducer`).
 - **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.
@@ -186,9 +186,9 @@ end
 To keep a batch of stale intake entries current in one shot:
 
 ```sh
-textus refresh-stale --prefix=working --zone=intake --as=script
-# or just refresh everything stale in the intake zone:
-textus refresh-stale --zone=intake --as=script
+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
 ```
 
 The primitive `Textus.hook(event, name, **opts) { ... }` is also supported. See SPEC.md §5.10 for the full contract.

data/SPEC.md

@@ -23,7 +23,7 @@ textus is organized as five composable layers. Each layer has a single responsib
 | Layer | Name | Responsibility |
 |---|---|---|
 | L1 | **Store** | Plain-file backend: `.textus/zones/<zone>/...` with YAML frontmatter + Markdown body, addressed by dotted keys, schema-validated, etag-versioned. |
-| L2 | **Sources** | Declared external inputs (`intake` zone): URLs, files, feeds with declared parsers and TTLs. textus *describes* sources; external runners fetch and pipe results through `textus put`. |
+| L2 | **Sources** | Declared external inputs (the `inbox` zone in the default scaffold; any zone writable by `script`): URLs, files, feeds with declared parsers and TTLs. textus *describes* sources; external runners fetch and pipe results through `textus put`. |
 | L3 | **Compute** | Pure transforms from store entries to derived entries. Projections (select/pluck/sort/limit/format) plus a vendored Mustache template subset. No shell execution. |
 | L4 | **Publish** | Byte-for-byte file copy from derived entries to repo-relative paths declared via `publish_to:`. The in-store artifact is the consumer-shaped output; the published file is an identical copy. A sentinel under `.textus/sentinels/<target-rel-path>.textus-managed.json` records the source, sha256, and `mode: "copy"`. |
 | L5 | **Consumers** | Anything that reads the published files or calls the CLI — editors, LLM tools, MCP servers, CI jobs, dashboards. textus is agnostic about who consumes; the envelope is the contract. |
@@ -213,11 +213,11 @@ Every successful write records the resolved role and a wall-clock timestamp in `
 
 ### 5.2 Compute layer (derived entries)
 
-Derived entries live in the `derived` zone. They are not authored by hand; their body is produced by projecting over other entries. A derived entry's frontmatter declares a `projection` block:
+Derived entries live in a zone whose `writable_by:` list includes `build` — `output` in the default scaffold. They are not authored by hand; their body is produced by projecting over other entries. A derived entry's frontmatter declares a `projection` block:
 
 ```yaml
-- key: derived.catalogs.people
-  zone: derived
+- key: output.catalogs.people
+  zone: output
   projection:
     select: working.network.org    # prefix OR [list of prefixes]
     pluck:  [name, relationship, org]
@@ -250,7 +250,7 @@ publish_to:
   - .ai/instructions.md
 ```
 
-When the entry is recomputed, textus copies the in-store file byte-for-byte to each destination. The in-store artifact under `.textus/zones/derived/…` is already the consumer-shaped output (per the format strategy — see §5.x), so publish is a verbatim file copy with no parsing or stripping.
+When the entry is recomputed, textus copies the in-store file byte-for-byte to each destination. The in-store artifact under `.textus/zones/<output-zone>/…` is already the consumer-shaped output (per the format strategy — see §5.x), so publish is a verbatim file copy with no parsing or stripping.
 
 A sentinel is written for each published file at `<store_root>/sentinels/<target-relative-to-repo>.textus-managed.json`, recording `source`, `target`, the target's sha256, and `mode: "copy"`. Sentinels live under the store rather than beside the consumer file so target directories stay clean. The sentinel exists so out-of-band edits can be detected on the next publish — textus refuses to clobber a destination that is not either missing or marked as managed. Legacy sibling sentinels (`<target>.textus-managed.json`) are still recognised as managed and are migrated to the new location on the next publish.
 
@@ -301,13 +301,13 @@ In intake mode the handler MUST return one of three shapes, all normalized by th
 **Refresh paths.** Two are supported:
 
 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.
+2. **External runner** — a cron job or agent harness reads `textus list --zone=inbox --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 `: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
 
-Pending entries are full proposal patches authored into the `pending` zone, typically by agents or scripts. A pending entry's frontmatter describes the patch it proposes against another zone:
+Proposal entries are full patches authored into a zone whose `writable_by:` list includes `ai` — `review` in the default scaffold — typically by agents or scripts. The entry's frontmatter describes the patch it proposes against another zone:
 
 ```yaml
 ---
@@ -324,7 +324,7 @@ Proposed body content.
 
 `proposal.target_key` names the entry the patch would create or modify, and `proposal.action` is `put` or `delete`. The remaining frontmatter and body are the proposed new content.
 
-`textus accept <pending-key>` is **human-only**: the resolved role must be `human`. It copies the patch into the target zone, records provenance (originating pending key, original role, original timestamp) in the audit log, and removes the pending entry. Agents and scripts can propose but cannot accept.
+`textus accept <proposal-key>` is **human-only**: the resolved role must be `human`. It copies the patch into the target zone, records provenance (originating proposal key, original role, original timestamp) in the audit log, and removes the proposal entry. Agents and scripts can propose but cannot accept.
 
 ### 5.6 Audit log
 
@@ -693,7 +693,7 @@ Every `Textus::Error` exposes `code`, `message`, and an optional `hint:`. The hi
 
 ## 10.2 `textus doctor`
 
-`textus doctor` returns a health-check envelope: `{ "protocol": "textus/2", "ok": bool, "issues": [...], "summary": {error, warning, info} }`. Each issue carries `code`, `level` (`error|warning|info`), `subject`, `message`, and optionally `fix`. `ok` is true iff no error-level issues are present; warnings and info do not flip the bit. Builtin checks: `manifest_files`, `schemas`, `templates`, `hooks`, `illegal_keys`, `sentinels`, `audit_log`, `unowned_schema_fields`, `schema_violations`. Additional registered `:check` hooks (§5.10) run after the builtin set. Exit code is 0 on `ok`, 1 otherwise.
+`textus doctor` returns a health-check envelope: `{ "protocol": "textus/2", "ok": bool, "issues": [...], "summary": {error, warning, info} }`. Each issue carries `code`, `level` (`error|warning|info`), `subject`, `message`, and optionally `fix`. `ok` is true iff no error-level issues are present; warnings and info do not flip the bit. Builtin checks: `manifest_files`, `schemas`, `schema_parse_error`, `templates`, `hooks`, `illegal_keys`, `sentinels`, `audit_log`, `unowned_schema_fields`, `schema_violations`, `policy_ambiguity`, `handler_allowlist`, `legacy_intake_fields`. Additional registered `:check` hooks (§5.10) run after the builtin set. Exit code is 0 on `ok`, 1 otherwise.
 
 ## 11. Versioning
 

data/docs/conventions.md

@@ -18,7 +18,7 @@ Recommended top-level layout — the spec allows alternatives, but this is what
   manifest.yaml
   schemas/        # YAML schema definitions
   zones/
-    identity/     # identity, voice, canon — humans only
+    identity/     # identity, voice, slow-changing facts — humans only
     working/      # agent-writable working memory
     inbox/        # script-fed external inputs
     review/       # AI proposals awaiting accept

data/lib/textus/doctor/check/audit_log.rb

@@ -1,48 +1,32 @@
-require "json"
-
 module Textus
   module Doctor
     class Check
       class AuditLog < Check
         def call
-          out = []
           path = File.join(store.root, "audit.log")
-          return out unless File.exist?(path)
-
-          File.foreach(path).with_index(1) do |line, lineno| # rubocop:disable Metrics/BlockLength
-            stripped = line.chomp
-            next if stripped.empty?
+          Textus::Store::AuditLog.new(store.root).verify_integrity.map do |v|
+            {
+              "code" => "audit.parse_error",
+              "level" => "warning",
+              "subject" => "#{path}:#{v["lineno"]}",
+              "message" => violation_message(v),
+              "fix" => "inspect #{path} at line #{v["lineno"]} and remove the corrupted row",
+            }
+          end
+        end
 
-            if stripped.start_with?("{")
-              begin
-                JSON.parse(stripped)
-              rescue JSON::ParserError => e
-                out << {
-                  "code" => "audit.parse_error",
-                  "level" => "warning",
-                  "subject" => "#{path}:#{lineno}",
-                  "message" => "audit log line #{lineno} is invalid JSON: #{e.message}",
-                  "fix" => "inspect #{path} at line #{lineno} and remove the corrupted row",
-                }
-              end
-            else
-              # Legacy TSV (pre-0.5): read-only support retained for on-disk logs
-              # written by older textus versions. Never written by current code.
-              # Minimum 6 fields.
-              fields = stripped.split("\t")
-              next if fields.length >= 6
+        private
 
-              out << {
-                "code" => "audit.parse_error",
-                "level" => "warning",
-                "subject" => "#{path}:#{lineno}",
-                "message" => "audit log line #{lineno} has #{fields.length} fields " \
-                             "(expected >=6 for legacy TSV; consider migrating to NDJSON)",
-                "fix" => "inspect #{path} at line #{lineno} and remove the corrupted row",
-              }
-            end
+        def violation_message(v)
+          case v["reason"]
+          when "invalid_json"
+            "audit log line #{v["lineno"]} is invalid JSON: #{v["detail"]}"
+          when "short_tsv"
+            "audit log line #{v["lineno"]} #{v["detail"]} " \
+            "(consider migrating to NDJSON)"
+          else
+            v["detail"]
           end
-          out
         end
       end
     end

data/lib/textus/doctor/check/manifest_files.rb

@@ -3,11 +3,10 @@ module Textus
     class Check
       class ManifestFiles < Check
         def call
-          out = []
-          store.manifest.entries.each do |entry|
+          store.manifest.entries.each_with_object([]) do |entry, out|
             next if entry.nested
 
-            path = leaf_path_for(entry)
+            path = Textus::Key::Path.resolve(store.manifest, entry)
             next if File.exist?(path)
 
             out << {
@@ -19,18 +18,6 @@ module Textus
                        "(or leave empty if not yet authored)",
             }
           end
-          out
-        end
-
-        private
-
-        def leaf_path_for(entry)
-          primary_ext = Entry.for_format(entry.format).extensions.first
-          if File.extname(entry.path) == ""
-            File.join(store.root, "zones", entry.path + primary_ext)
-          else
-            File.join(store.root, "zones", entry.path)
-          end
         end
       end
     end

data/lib/textus/doctor/check/schema_parse_error.rb

@@ -0,0 +1,28 @@
+module Textus
+  module Doctor
+    class Check
+      # Surfaces YAML parse failures for files in <store>/schemas/. Without
+      # this check, malformed schemas are silently skipped by other doctor
+      # checks (UnownedSchemaFields rescues, Schemas only checks filenames),
+      # leaving the operator with no signal that a schema is broken.
+      class SchemaParseError < Check
+        def call
+          dir = File.join(store.root, "schemas")
+          return [] unless File.directory?(dir)
+
+          Dir.glob(File.join(dir, "*.yaml")).each_with_object([]) do |path, out|
+            Schema.load(path)
+          rescue StandardError => e
+            out << {
+              "code" => "schema.parse_error",
+              "level" => "error",
+              "subject" => path,
+              "message" => "schema failed to parse: #{e.class}: #{e.message}",
+              "fix" => "fix the YAML at #{path} (check indentation, quoted scalars, and aliases)",
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/sentinels.rb

@@ -1,55 +1,56 @@
-require "digest"
-require "json"
-
 module Textus
   module Doctor
     class Check
       class Sentinels < Check
         def call
-          out = []
           dir = File.join(store.root, "sentinels")
-          return out unless File.directory?(dir)
+          return [] unless File.directory?(dir)
 
-          Dir.glob(File.join(dir, "**", "*.textus-managed.json")).each do |sp| # rubocop:disable Metrics/BlockLength
-            begin
-              data = JSON.parse(File.read(sp))
-            rescue JSON::ParserError => e
-              out << {
-                "code" => "sentinel.parse_error",
-                "level" => "warning",
-                "subject" => sp,
-                "message" => "sentinel is not valid JSON: #{e.message}",
-                "fix" => "delete #{sp} and re-run 'textus build' to regenerate",
-              }
-              next
-            end
+          repo_root = File.dirname(store.root)
+          Dir.glob(File.join(dir, "**", "*#{Textus::Store::Sentinel::SUFFIX}")).flat_map do |sentinel_path|
+            inspect_sentinel(sentinel_path, repo_root)
+          end
+        end
 
-            target = data["target"]
-            recorded_sha = data["sha256"]
+        private
 
-            if target.nil? || !File.exist?(target)
-              out << {
-                "code" => "sentinel.orphan",
-                "level" => "warning",
-                "subject" => sp,
-                "message" => "sentinel target #{target.inspect} no longer exists",
-                "fix" => "delete #{sp} (the published file is gone) or restore the target",
-              }
-              next
-            end
+        def inspect_sentinel(sentinel_path, repo_root)
+          sentinel = Textus::Store::Sentinel.load(sentinel_path, repo_root)
+          return [parse_error_issue(sentinel_path)] if sentinel.nil?
+          return [orphan_issue(sentinel_path, sentinel)] if sentinel.orphan?
+          return [drift_issue(sentinel)] if sentinel.drift?
 
-            current_sha = Digest::SHA256.hexdigest(File.binread(target))
-            next if recorded_sha.nil? || current_sha == recorded_sha
+          []
+        end
 
-            out << {
-              "code" => "sentinel.drift",
-              "level" => "warning",
-              "subject" => target,
-              "message" => "published file at #{target} was modified out-of-band",
-              "fix" => "re-run 'textus build' to overwrite, or copy the manual edit back into the store source",
-            }
-          end
-          out
+        def parse_error_issue(sentinel_path)
+          {
+            "code" => "sentinel.parse_error",
+            "level" => "warning",
+            "subject" => sentinel_path,
+            "message" => "sentinel is not valid JSON",
+            "fix" => "delete #{sentinel_path} and re-run 'textus build' to regenerate",
+          }
+        end
+
+        def orphan_issue(sentinel_path, sentinel)
+          {
+            "code" => "sentinel.orphan",
+            "level" => "warning",
+            "subject" => sentinel_path,
+            "message" => "sentinel target #{sentinel.target.inspect} no longer exists",
+            "fix" => "delete #{sentinel_path} (the published file is gone) or restore the target",
+          }
+        end
+
+        def drift_issue(sentinel)
+          {
+            "code" => "sentinel.drift",
+            "level" => "warning",
+            "subject" => sentinel.target,
+            "message" => "published file at #{sentinel.target} was modified out-of-band",
+            "fix" => "re-run 'textus build' to overwrite, or copy the manual edit back into the store source",
+          }
         end
       end
     end

data/lib/textus/doctor/check/unowned_schema_fields.rb

@@ -3,30 +3,36 @@ module Textus
     class Check
       class UnownedSchemaFields < Check
         def call
-          out = []
           dir = File.join(store.root, "schemas")
-          return out unless File.directory?(dir)
+          return [] unless File.directory?(dir)
 
-          Dir.glob(File.join(dir, "*.yaml")).sort.each do |sp| # rubocop:disable Lint/RedundantDirGlobSort
-            schema = begin
-              Schema.load(sp)
-            rescue StandardError
-              next
-            end
-            unowned = schema.fields.each_with_object([]) do |(name, spec), acc|
-              acc << name if spec.is_a?(Hash) && spec["maintained_by"].nil?
-            end
-            next if unowned.empty?
-
-            out << {
-              "code" => "schema.unowned_fields",
-              "level" => "info",
-              "subject" => schema.name || File.basename(sp, ".yaml"),
-              "message" => "schema has fields without maintained_by: #{unowned.join(", ")}",
-              "fix" => "add 'maintained_by: <role>' to each field in #{sp} (optional but recommended)",
-            }
+          Dir.glob(File.join(dir, "*.yaml")).flat_map do |path|
+            issues_for(path)
           end
-          out
+        end
+
+        private
+
+        def issues_for(path)
+          schema = safe_load(path)
+          return [] if schema.nil?
+
+          unowned = schema.unowned_fields
+          return [] if unowned.empty?
+
+          [{
+            "code" => "schema.unowned_fields",
+            "level" => "info",
+            "subject" => schema.name || File.basename(path, ".yaml"),
+            "message" => "schema has fields without maintained_by: #{unowned.join(", ")}",
+            "fix" => "add 'maintained_by: <role>' to each field in #{path} (optional but recommended)",
+          }]
+        end
+
+        def safe_load(path)
+          Schema.load(path)
+        rescue StandardError
+          nil
         end
       end
     end

data/lib/textus/doctor.rb

@@ -11,6 +11,7 @@ module Textus
     CHECKS = [
       Check::ManifestFiles,
       Check::Schemas,
+      Check::SchemaParseError,
       Check::Templates,
       Check::Hooks,
       Check::IntakeRegistration,

data/lib/textus/infra/publisher.rb

@@ -1,24 +1,21 @@
-require "json"
-require "digest"
 require "fileutils"
 
 module Textus
   module Infra
     # Publishes built artifacts from the store to repo-relative consumer paths.
     # Publish = copy + sentinel. The in-store file is already the consumer-shaped
-    # artifact; no parsing or stripping. Sentinels live under
+    # artifact; no parsing or stripping.
+    #
+    # Sentinel I/O is delegated to Store::Sentinel. Sentinels live under
     # `<store_root>/sentinels/` and mirror the target's repo-relative layout so
     # consumer directories aren't polluted with `.textus-managed.json` siblings.
     module Publisher
-      SENTINEL_SUFFIX = ".textus-managed.json".freeze
-      SENTINEL_DIR    = "sentinels".freeze
-
       def self.publish(source:, target:, store_root:)
         FileUtils.mkdir_p(File.dirname(target))
         refuse_if_unmanaged(target, store_root)
         File.delete(target) if File.symlink?(target)
         FileUtils.cp(source, target)
-        write_sentinel(target, store_root: store_root, source: source)
+        Store::Sentinel.write!(target: target, source: source, store_root: store_root)
         cleanup_legacy_sentinel(target)
       end
 
@@ -30,43 +27,12 @@ module Textus
       end
 
       def self.managed?(target, store_root)
-        File.exist?(sentinel_path(target, store_root)) || File.exist?(legacy_sentinel_path(target))
-      end
-
-      def self.write_sentinel(target, store_root:, source:)
-        path = sentinel_path(target, store_root)
-        FileUtils.mkdir_p(File.dirname(path))
-        File.write(path, JSON.generate(
-                           "source" => source,
-                           "target" => target,
-                           "sha256" => Digest::SHA256.hexdigest(File.binread(target)),
-                           "mode" => "copy",
-                         ))
-      end
-
-      # Sentinel layout: <store_root>/sentinels/<target_rel_to_repo>.textus-managed.json
-      # The full target extension is preserved so a marketplace.json and
-      # marketplace.yaml don't collide.
-      def self.sentinel_path(target, store_root)
-        repo_root = File.dirname(store_root)
-        rel = relative_to(target, repo_root) || File.basename(target)
-        File.join(store_root, SENTINEL_DIR, rel + SENTINEL_SUFFIX)
-      end
-
-      def self.legacy_sentinel_path(target)
-        target + SENTINEL_SUFFIX
+        File.exist?(Store::Sentinel.sentinel_path(target, store_root)) ||
+          File.exist?(Store::Sentinel.legacy_path(target))
       end
 
       def self.cleanup_legacy_sentinel(target)
-        FileUtils.rm_f(legacy_sentinel_path(target))
-      end
-
-      def self.relative_to(path, base)
-        path = File.expand_path(path)
-        base = File.expand_path(base)
-        return nil unless path.start_with?(base + File::SEPARATOR)
-
-        path[(base.length + 1)..]
+        FileUtils.rm_f(Store::Sentinel.legacy_path(target))
       end
     end
   end

data/lib/textus/schema.rb

@@ -26,6 +26,16 @@ module Textus
       meta["maintained_by"]
     end
 
+    # Returns the list of field names whose spec is a Hash but lacks the
+    # 'maintained_by' key. Used by Doctor::Check::UnownedSchemaFields.
+    def unowned_fields
+      @fields.each_with_object([]) do |(name, spec), acc|
+        next unless spec.is_a?(Hash)
+
+        acc << name if spec["maintained_by"].nil?
+      end
+    end
+
     def evolution
       raw = @raw["evolution"] || {}
       raw.each_with_object({}) do |(k, v), h|

data/lib/textus/store/audit_log.rb

@@ -47,6 +47,20 @@ module Textus
         end
       end
 
+      # Returns an array of integrity-violation descriptors for the on-disk log.
+      # Each entry is { "lineno" => Integer, "reason" => String, "detail" => String }.
+      # Empty array means the log is well-formed (or doesn't exist yet).
+      def verify_integrity
+        return [] unless File.exist?(@path)
+
+        out = []
+        File.foreach(@path).with_index(1) do |line, lineno|
+          violation = check_line(line.chomp, lineno)
+          out << violation if violation
+        end
+        out
+      end
+
       private
 
       def parse_row(line)
@@ -66,6 +80,30 @@ module Textus
       rescue JSON::ParserError
         nil
       end
+
+      def check_line(stripped, lineno)
+        return nil if stripped.empty?
+
+        if stripped.start_with?("{")
+          begin
+            JSON.parse(stripped)
+            nil
+          rescue JSON::ParserError => e
+            { "lineno" => lineno, "reason" => "invalid_json", "detail" => e.message }
+          end
+        else
+          # parse_row accepts >= 4 fields for read-compat; integrity requires
+          # all 6 data columns of the legacy TSV format.
+          fields = stripped.split("\t")
+          return nil if fields.length >= 6
+
+          {
+            "lineno" => lineno,
+            "reason" => "short_tsv",
+            "detail" => "legacy TSV row has #{fields.length} fields (expected >= 6)",
+          }
+        end
+      end
     end
   end
 end

data/lib/textus/store/sentinel.rb

@@ -0,0 +1,93 @@
+require "json"
+require "digest"
+require "fileutils"
+
+module Textus
+  class Store
+    # Value object for sentinel files written by Infra::Publisher and inspected
+    # by Doctor::Check::Sentinels. Owns the JSON shape ({source, target,
+    # sha256, mode}) and the on-disk path layout (<store_root>/sentinels/
+    # <target-rel-to-repo>.textus-managed.json).
+    #
+    # Repo-relative target/source on write so example trees can be committed
+    # without leaking the author's absolute filesystem paths. Legacy absolute
+    # paths are still accepted on read.
+    class Sentinel
+      SUFFIX = ".textus-managed.json".freeze
+      DIR    = "sentinels".freeze
+
+      attr_reader :target, :source, :sha256, :mode
+
+      def self.write!(target:, source:, store_root:)
+        path = sentinel_path(target, store_root)
+        FileUtils.mkdir_p(File.dirname(path))
+        repo_root = File.dirname(store_root)
+        File.write(path, JSON.generate(
+                           "source" => rel_or_abs(source, repo_root),
+                           "target" => rel_or_abs(target, repo_root),
+                           "sha256" => Digest::SHA256.hexdigest(File.binread(target)),
+                           "mode" => "copy",
+                         ))
+      end
+
+      def self.load(path, repo_root)
+        raw = JSON.parse(File.read(path))
+        new(
+          target: absolutize(raw["target"], repo_root),
+          source: absolutize(raw["source"], repo_root),
+          sha256: raw["sha256"],
+          mode: raw["mode"],
+        )
+      rescue JSON::ParserError, Errno::ENOENT
+        nil
+      end
+
+      def self.sentinel_path(target, store_root)
+        repo_root = File.dirname(store_root)
+        rel = relative_to(target, repo_root) || File.basename(target)
+        File.join(store_root, DIR, rel + SUFFIX)
+      end
+
+      def self.legacy_path(target)
+        target + SUFFIX
+      end
+
+      def self.rel_or_abs(path, repo_root)
+        relative_to(path, repo_root) || File.expand_path(path)
+      end
+
+      def self.relative_to(path, repo_root)
+        path = File.expand_path(path)
+        base = File.expand_path(repo_root)
+        return nil unless path.start_with?(base + File::SEPARATOR)
+
+        path[(base.length + 1)..]
+      end
+
+      def self.absolutize(path, repo_root)
+        return path if path.nil?
+        return path if File.absolute_path?(path)
+
+        File.expand_path(path, repo_root)
+      end
+
+      def initialize(target:, source:, sha256:, mode:)
+        @target = target
+        @source = source
+        @sha256 = sha256
+        @mode = mode
+      end
+
+      def orphan?
+        @target.nil? || !File.exist?(@target)
+      end
+
+      def drift?
+        return false if orphan?
+        return false if @sha256.nil?
+
+        Digest::SHA256.hexdigest(File.binread(@target)) != @sha256
+      end
+    end
+  end
+end

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.10.0"
+  VERSION = "0.10.2"
   PROTOCOL = "textus/2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.10.2
 platform: ruby
 authors:
 - Patrick
@@ -102,10 +102,10 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ARCHITECTURE.md
 - CHANGELOG.md
 - README.md
 - SPEC.md
-- docs/architecture.md
 - docs/conventions.md
 - exe/textus
 - lib/textus.rb
@@ -178,6 +178,7 @@ files:
 - lib/textus/doctor/check/legacy_intake_fields.rb
 - lib/textus/doctor/check/manifest_files.rb
 - lib/textus/doctor/check/policy_ambiguity.rb
+- lib/textus/doctor/check/schema_parse_error.rb
 - lib/textus/doctor/check/schema_violations.rb
 - lib/textus/doctor/check/schemas.rb
 - lib/textus/doctor/check/sentinels.rb
@@ -233,6 +234,7 @@ files:
 - lib/textus/store/audit_log.rb
 - lib/textus/store/mover.rb
 - lib/textus/store/reader.rb
+- lib/textus/store/sentinel.rb
 - lib/textus/store/staleness.rb
 - lib/textus/store/validator.rb
 - lib/textus/store/writer.rb

data/docs/architecture.md

@@ -1,129 +0,0 @@
-# Architecture
-
-How the reference Ruby implementation is organized. The wire protocol itself lives in [`../SPEC.md`](../SPEC.md); this document covers *how* the gem implements that spec.
-
-The codebase is a flat graph of small modules under one CLI dispatcher, not a strict pyramid. The clusters below describe what each module exists for and which other modules it talks to.
-
-## At a glance
-
-```
-exe/textus  →  Textus::CLI  ──┬──►  Store          (facade — delegates to Reader/Writer/Mover)
-                              │       ├──►  Store::Reader  (get/list/where/uid/deps/published/stale/validate_all)
-                              │       ├──►  Store::Writer  (put/delete/accept)
-                              │       ├──►  Store::Mover   (mv)
-                              │       └──►  Hooks::Dispatcher  (lifecycle publish/subscribe)
-                              ├──►  Builder        (build verb — Pipeline + per-format renderers)
-                              ├──►  Refresh        (refresh verb)
-                              ├──►  Doctor         (doctor verb)
-                              ├──►  Init           (init verb)
-                              ├──►  Intro          (intro verb)
-                              ├──►  MigrateKeys    (key migrate, key mv verbs)
-                              ├──►  Schema::Tools  (schema init/diff/migrate verbs)
-                              ├──►  Store::View    (read-only projection over Store::Reader)
-                              └──►  Role           (role gate)
-```
-
-CLI is the single entry point. It parses argv and dispatches each verb to whichever module owns that capability — there is no single mediator below CLI.
-
-## Module clusters
-
-### 1. Request path — core read/write verbs
-
-`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`, `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` / `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:
-
-- **`Textus::Key::Path`** — `Key::Path.resolve(manifest, mentry)` returns the absolute leaf path for a manifest entry. Single source for zone-path construction; used by `Manifest`, `Staleness`, `Builder`, and Writer.
-- **`Textus::Envelope`** — `Envelope.build(...)` returns the canonical envelope hash (protocol, key, zone, owner, path, format, `_meta`, body, etag, schema_ref, uid, optional content). Single source for envelope shape across `get` and `put`.
-- **`Manifest`** — parses `.textus/manifest.yaml`; resolves a dotted key to a path via longest-prefix match. `nested: true` entries treat unmatched suffix segments as `/`-joined subdirs, with `.md` appended. Resolution is path-only; existence is the verb's concern.
-- **`Schema`** — loads YAML schema files; validates frontmatter shape and surfaces unknown-key warnings (the §6 forward-compat rule).
-- **`Entry`** + format adapters (`entry/markdown.rb`, `entry/text.rb`, `entry/json.rb`, `entry/yaml.rb`) — splits raw bytes on `---\n`, feeds the YAML chunk to `YAML.safe_load` (no aliases, restricted classes). The frontmatter `name:` field is enforced against the file basename in Reader/Writer (on read and on write) — mismatch raises `bad_frontmatter`.
-- **`Etag`** — `sha256:<hex>` over raw file bytes. `put` accepts optional `if_etag:`; mismatch raises `etag_mismatch`. No locking, no temp-file-and-rename — v1 leaves stronger guarantees to v1.x.
-- **`Role`** — agent-vs-human gate. Writer checks `Manifest::Entry#zone_writers` before doing anything else; otherwise raises `write_forbidden`.
-- **`Store::AuditLog`** — append-only NDJSON; every successful write emits one line.
-- **`Proposal`** — `accept` verb flow for promoting a pending entry into its target zone.
-- **`Dependencies`** — `deps`/`rdeps`/`published` verb backing; walks manifest declarations.
-
-### 2. Build / publish pipeline
-
-Separate from the request path. Owns derived-entry materialization and byte-copy publish. `Builder` orchestrates per-entry materialization through `Builder::Pipeline`, which runs an ordered step list and dispatches the rendering step to one of four format-specific renderers. Adding a new output format is a single-file change under `lib/textus/builder/renderer/`.
-
-```
-Builder ──► Pipeline ──► LoadSources ──► Project ──► Render (per-format) ──► Write ──► Publisher ──► (sentinel)
-                                                          │
-                                                          └──► Renderer::{Markdown, Text, Json, Yaml}
-```
-
-- **`Builder`** — iterates `zone: derived` entries, hands each to `Pipeline.run`, then handles `Publisher` copy-out and fires the `:build` event. Holds no format-specific logic.
-- **`Builder::Pipeline`** — `Pipeline.run(store:, mentry:, template_loader:)` is the orchestrator: runs the projection, merges `intro` if `inject_intro: true`, dispatches to the matching renderer, writes the bytes to the derived path.
-- **`Builder::InjectMeta`** — builds the `_meta` block (`generated_at`, `from`, `template`, `reduce`) and threads it onto JSON/YAML content as the first key per SPEC §6 ordering.
-- **`Builder::Renderer::{Markdown,Text,Json,Yaml}`** — one class per format, inheriting `Builder::Renderer`. Receives a template-loader lambda and `(mentry:, data:)`; returns rendered bytes. Markdown/Text always require a template; JSON/YAML optionally accept one (otherwise default-shape the projection rows).
-- **`Projection`** — collects rows from manifest-declared source keys, applies optional reducer, sorts and positions. Pure data shaping.
-- **`Mustache`** — minimal mustache renderer for templates in `.textus/templates/`.
-- **`Publisher`** — byte-copy from store path to external target path. Refuses to overwrite unmanaged targets; writes a sentinel in `.textus/sentinels/` to track managed targets.
-
-### 3. Extension surface
-
-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`, `: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.
-
-### 4. Operational tooling
-
-First-class CLI verbs that don't fit the read/write/build axes. Read-mostly; side modules off CLI.
-
-- **`Doctor`** — `doctor` verb: orchestrator that runs 9 builtin checks under `Doctor::Check::*`. Talks to Manifest/Schema/Entry/Hooks::Registry directly.
-- **`Doctor::Check`** — explicit base class for doctor checks. Each of the 9 builtin checks is its own file under `lib/textus/doctor/check/`.
-- **`MigrateKeys`** — `key migrate` and `key mv` verbs; computes renames against the manifest.
-- **`Schema::Tools`** — `schema init`, `schema diff`, `schema migrate` verbs.
-- **`Init`** — `init` verb: scaffolds `.textus/` with the five zone directories, baseline schemas, empty audit log, starter manifest.
-- **`Intro`** — `intro` verb: emits the human/agent-facing onboarding payload.
-- **`Store::View`** — read-only projection over `Store::Reader` for hook code that should not mutate.
-- **`Key::Distance`** — Levenshtein-ish suggestion for `did-you-mean` on unknown keys.
-
-### 5. Primitives
-
-- **`Errors`** — `Textus::Error` subclasses, each carrying a stable `code`, a `details` hash, and an `exit_code`. `CLI` catches them at the top level and emits the §8 error envelope on stdout. In `--format=json` mode, errors are **never** written to stderr — agents read stdout.
-- **`version`** — gem semver string (independent of the wire protocol `textus/2`).
-
-## Invariants
-
-- **CLI is the only entry point.** No public API surface guarantees outside the verbs CLI exposes.
-- **Manifest is pure.** Reads at load, no mutation.
-- **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.
-- **`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
-
-- **No process spawning.** Even `stale` does not execute. Build runners do that.
-- **No transport.** No HTTP server, no socket, no MCP server in this gem. Those are downstream wrappers (see [`./conventions.md`](./conventions.md)).
-- **No indexes.** Listing walks the filesystem each time. Premature optimisation for v1.
-- **No locking.** Etag is advisory; concurrent writers can still race. Left to v1.x (§14 open question).