textus 0.30.0 → 0.35.1

data/docs/conventions.md

@@ -1,6 +1,9 @@
 # Conventions
 
-Guidelines for shaping a `.textus/` tree, naming keys, organising schemas, and integrating with build runners. The spec ([`../SPEC.md`](../SPEC.md)) defines what's enforceable; this document captures what's *idiomatic*.
+> **Reference** · for integrators · **read when** you're shaping a `.textus/` tree and want the idiomatic choices
+> **SSoT for** idiomatic key naming, schema design, and automation integration · **reviewed** 2026-05 (v0.31)
+
+Guidelines for shaping a `.textus/` tree, naming keys, organising schemas, and integrating with build automation. The spec ([`../SPEC.md`](../SPEC.md)) defines what's enforceable; this document captures what's *idiomatic*.
 
 ## Key naming
 
@@ -18,14 +21,14 @@ Recommended top-level layout — the spec allows alternatives, but this is what
   manifest.yaml
   schemas/        # YAML schema definitions
   zones/
-    identity/     # identity, voice, slow-changing facts — humans only
-    working/      # agent-writable working memory
-    intake/       # runner-fed external inputs
-    review/       # AI proposals awaiting accept
-    output/       # generated by build runners — never edit by hand
+    knowledge/    # authored truth: identity, voice, decisions — author-holders write
+    notebook/     # agent's own durable lane (workspace) — keep-holders write
+    feeds/        # automation-fed external inputs (fetch)
+    proposals/    # AI proposals awaiting accept (propose)
+    artifacts/    # generated by build automation — never edit by hand
 ```
 
-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.
+Inside `knowledge/`, group by **domain** (identity, people, projects, decisions, runbooks), not by file type or date. `knowledge.identity.*` is the convention for slow-changing identity facts. Inside `artifacts/`, group by **producer** (`artifacts/catalogs/`, `artifacts/indexes/`) so it's clear which build job owns what.
 
 ## Schema design
 
@@ -46,75 +49,77 @@ Tooling around `git blame` or audit logs may filter on owner; the gem itself onl
 
 ## Derived entries
 
-textus supports two shapes for derived entries:
+A derived entry declares a `compute:` block with a `kind:` discriminator. Two kinds:
 
-**`projection:`** — textus computes the entry on `textus build` from other store entries. Declarative; nothing shells out.
+**`compute: { kind: projection }`** — textus computes the entry on `textus build` from other store entries. Declarative; nothing shells out.
 
 ```yaml
-- key: output.catalogs.people
-  path: output/catalogs/people.md
-  zone: output
+- key: artifacts.catalogs.people
+  path: artifacts/catalogs/people.md
+  zone: artifacts
   schema: null
   owner: build:catalog-people
-  projection:
-    select: working.network.org   # prefix or list of prefixes
+  compute:
+    kind: projection
+    select: knowledge.network.org   # prefix or list of prefixes
     pluck:  [name, relationship, org]
     sort_by: name
-  template: people.mustache       # under .textus/templates/
-  publish_to: [docs/people.md]    # optional repo-relative byte-copy targets
+  template: people.mustache         # under .textus/templates/
+  publish_to: [docs/people.md]      # optional repo-relative byte-copy targets
 ```
 
-**`generator:`** — an external build tool (rake, just, a shell script) produces the file. textus never executes the `command:`; it only tracks `sources:` so `textus freshness` can compare source mtimes against the file's `_meta.generated.at`.
+**`compute: { kind: external }`** — an external build tool (rake, just, a shell script) produces the file. textus never executes the `command:`; it only tracks `sources:` so `textus freshness` can compare source mtimes against the file's `_meta.generated.at`. The role running the build must hold `build` (default: `automation`).
 
 ```yaml
-- key: output.catalogs.skills
-  path: output/catalogs/skills.md
-  zone: output
+- key: artifacts.catalogs.skills
+  path: artifacts/catalogs/skills.md
+  zone: artifacts
   owner: build:catalog-skills
-  generator:
-    command: "rake catalog:skills"   # informational; the runner invokes it
-    sources: [working.projects, working.network]
+  compute:
+    kind: external
+    command: "rake catalog:skills"   # informational; the automation invokes it
+    sources: [knowledge.projects, knowledge.network]
 ```
 
-The build runner is responsible for writing the `generated:` frontmatter block (`by`, `at`, `from`) when it produces the file. `generated.from` SHOULD match `generator.sources` — same list, recorded twice so a diff proves what was consumed.
+The build automation is responsible for writing the `generated:` frontmatter block (`by`, `at`, `from`) when it produces the file. `generated.from` SHOULD match `compute.sources` — same list, recorded twice so a diff proves what was consumed.
 
-Full contract for both shapes is in [`../SPEC.md` §5.2 and §5.2.1](../SPEC.md). Reducers (`projection.reduce:`) and per-leaf publishing (`publish_each:`) are also covered there.
+Full contract for both shapes is in [`../SPEC.md` §5.2.1 and §5.2.2](../SPEC.md). Transforms (`compute.transform:`) and per-leaf publishing (`publish_each:`) are also covered there.
 
 ## Intake and freshness
 
-External inputs land via `:resolve_intake` hooks, not shell commands. Each intake entry names a registered handler; refresh is on demand:
+External inputs land via `:resolve_intake` hooks, not shell commands. Each intake entry names a registered handler; fetch is on demand:
 
 ```sh
-textus refresh intake.notion.roadmap --as=runner
-textus refresh-stale --zone=intake --as=runner   # everything past its TTL
+textus fetch feeds.notion.roadmap --as=automation
+textus fetch stale --zone=feeds --as=automation   # everything past its TTL
 ```
 
 Freshness budgets live in the top-level `rules:` block, matched by glob:
 
 ```yaml
 rules:
-  - match: intake.notion.**
-    refresh: { ttl: 6h, on_stale: warn }   # warn | sync | timed_sync
+  - match: feeds.notion.**
+    fetch: { ttl: 6h, on_stale: warn }   # warn | sync | timed_sync
 ```
 
-A typical scheduled-refresh integration shells the `refresh-stale` sweep itself:
+A typical scheduled-fetch integration shells the `fetch stale` sweep itself:
 
 ```sh
-textus refresh-stale --zone=intake --as=runner   # in cron / CI
+textus fetch stale --zone=intake --as=automation   # in cron / CI
 ```
 
 See [`./zones.md` §6](zones.md) for the full intake contract and [`./events.md`](events.md) for writing custom handlers.
 
-### Read vs. refresh
+### Read vs. fetch
 
 There are two read operations, and the difference matters in custom code:
 
-| Operation | Triggers refresh? | Use for |
-|-----------|-------------------|---------|
+| Operation | Triggers fetch? | Use for |
+|-----------|-----------------|---------|
 | `ops.get` | No — pure read of on-disk envelope + freshness verdict | build / materialization paths, schema tooling, any context where a side-effecting read would surprise the caller |
-| `ops.get_or_refresh` | Yes — composes `get` with the orchestrator per the rule's `on_stale` policy | interactive reads (`textus get`, dashboards) where the caller wants the freshest envelope obtainable |
+| `ops.get_or_fetch` | Yes — composes `get` with the orchestrator per the rule's `on_stale` policy | interactive reads (`textus get`, dashboards) where the caller wants the freshest envelope obtainable |
 
-Build always uses the pure path; injecting refresh into materialization caused the cascading-staleness incident behind issue #59. Pick `get_or_refresh` only when you genuinely want side effects on read.
+Build always uses the pure path; injecting fetch into materialization caused the cascading-staleness incident behind issue #59. Pick `get_or_fetch` only when you genuinely want side effects on read.
 
 ## Body content
 

data/lib/textus/boot.rb

@@ -8,46 +8,56 @@ module Textus
   module Boot
     PROTOCOL_ID = PROTOCOL
 
-    # Conventional zone purposes. Unknown zones (declared in the manifest
-    # but not listed here) get no `purpose` field.
-    ZONE_PURPOSES = {
-      "identity" => "slow-changing identity; human-only writes",
-      "working" => "active project state; humans, AI, and scripts share this surface",
-      "intake" => "declared external inputs; script-refreshed via actions",
-      "review" => "AI proposals awaiting human accept",
-      "output" => "build-computed outputs; never hand-edited",
-    }.freeze
-
-    # Per-kind write-flow templates. Each lambda receives the user-facing role
-    # name and returns a guidance string for that role. Roles whose kind has
-    # no template (e.g. unknown future kinds) are omitted from write_flows.
+    # Per-capability write-flow templates. Each lambda receives the user-facing
+    # role name and the manifest, and returns guidance for that verb with the
+    # live zone named by kind (ADR 0034). A role holding multiple verbs gets one
+    # joined string; roles whose verbs have no template are omitted.
     WRITE_FLOW_TEMPLATES = {
-      accept_authority: lambda do |name, _manifest|
-        "edit files in identity/working zones, then 'textus put KEY --as=#{name}'"
+      author: lambda do |name, manifest|
+        "edit files in #{zone_label(manifest, :canon, "your canon zone")}, " \
+          "then 'textus put KEY --as=#{name}'"
       end,
-      proposer: lambda do |name, manifest|
-        authority = manifest.policy.roles_with_kind(:accept_authority).first || "accept_authority"
-        "propose changes by writing review.* entries with --as=#{name} and a 'proposal:' frontmatter block; " \
-          "the #{authority} role runs 'textus accept' to apply"
+      keep: lambda do |name, manifest|
+        "keep durable notes in #{zone_label(manifest, :workspace, "your workspace")}: " \
+          "'textus put KEY --as=#{name}' (no accept needed)"
       end,
-      runner: lambda do |name, _manifest|
-        "refresh intake entries with 'textus refresh KEY --as=#{name}' (uses the entry's declared action)"
+      propose: lambda do |name, manifest|
+        authority = manifest.policy.roles_with_capability("author").first || "the author-holder"
+        "propose changes by writing #{manifest.policy.queue_zone}.* entries with --as=#{name} " \
+          "and a 'proposal:' frontmatter block; the #{authority} role runs 'textus accept' to apply"
       end,
-      generator: lambda do |_name, _manifest|
-        "'textus build' computes output entries from projections; output files are never hand-edited"
+      fetch: lambda do |name, manifest|
+        "fetch #{zone_label(manifest, :quarantine, "quarantine")} entries with " \
+          "'textus fetch KEY --as=#{name}' (uses the entry's declared action)"
+      end,
+      build: lambda do |_name, manifest|
+        derived = zone_label(manifest, :derived, "derived")
+        "'textus build' computes #{derived} entries from projections; " \
+          "#{derived} files are never hand-edited"
       end,
     }.freeze
 
     def self.write_flows_for(manifest)
-      manifest.policy.role_mapping.each_with_object({}) do |(name, kind), acc|
-        tmpl = WRITE_FLOW_TEMPLATES[kind]
-        acc[name] = tmpl.call(name, manifest) if tmpl
+      manifest.data.role_caps.each_with_object({}) do |(name, caps), acc|
+        flows = caps.filter_map do |verb|
+          tmpl = WRITE_FLOW_TEMPLATES[verb.to_sym]
+          tmpl&.call(name, manifest)
+        end
+        acc[name] = flows.join(" / ") unless flows.empty?
       end
     end
 
+    # Human-readable name(s) for the live zone(s) of a given kind, or `fallback`
+    # when the manifest declares none. Lets write-flow guidance name the live
+    # zone by kind instead of a hardcoded instance name (ADR 0034).
+    def self.zone_label(manifest, kind, fallback)
+      zones = manifest.policy.zones_of_kind(kind)
+      zones.empty? ? fallback : zones.join(", ")
+    end
+
     # Static, store-independent parts of the agent-facing protocol. The
-    # `role_resolution` block is derived per-manifest in agent_protocol(...)
-    # because role names are user-configurable.
+    # `recipes` and `role_resolution` blocks are derived per-manifest in
+    # agent_protocol(...) because zone and role names are user-configurable.
     AGENT_PROTOCOL_TEMPLATE = {
       "envelope_shape" => {
         "summary" => "every read/write payload is a JSON envelope with _meta, body, uid, and etag",
@@ -59,39 +69,6 @@ module Textus
         },
         "ref" => "SPEC.md §8",
       },
-      "recipes" => {
-        "read" => {
-          "purpose" => "find and read an entry",
-          "steps" => [
-            "textus list --zone=ZONE --prefix=PREFIX  # discover keys",
-            "textus get KEY                            # returns envelope JSON",
-          ],
-        },
-        "write" => {
-          "purpose" => "create or update an entry",
-          "steps" => [
-            "textus schema get FAMILY                  # learn the _meta field shape",
-            "build an envelope JSON: {_meta: {...}, body: \"...\"}",
-            "echo ENVELOPE | textus put KEY --as=ROLE --stdin",
-          ],
-        },
-        "propose" => {
-          "purpose" => "agent suggests a change for human review",
-          "agent_steps" => [
-            "echo ENVELOPE | textus put review.KEY --as=agent --stdin",
-          ],
-          "human_steps" => [
-            "textus accept review.KEY --as=human       # promotes the proposal to its target zone",
-          ],
-        },
-        "refresh" => {
-          "purpose" => "rebuild stale intake-zone caches from their declared actions",
-          "steps" => [
-            "textus freshness --zone=intake            # report fresh/stale per entry",
-            "textus refresh stale --zone=intake --as=runner",
-          ],
-        },
-      },
     }.freeze
 
     # The CLI verb catalog. Truth lives here; do not derive dynamically.
@@ -104,11 +81,11 @@ module Textus
       { "name" => "where",    "summary" => "resolve a key to its zone and path without reading" },
       { "name" => "schema",   "summary" => "field shape for a key family" },
       { "name" => "put",      "summary" => "write an entry; --as=<role>, --stdin payload" },
-      { "name" => "accept",   "summary" => "apply a review.* proposal; --as=human only" },
+      { "name" => "accept",   "summary" => "apply a queued proposal to its target zone; requires the author capability" },
       { "name" => "key",      "summary" => "key operations: 'key mv', 'key uid'" },
       { "name" => "delete",   "summary" => "delete an entry; --as=<role>" },
-      { "name" => "build",    "summary" => "materialize output entries; publish_to and publish_each fan out copies" },
-      { "name" => "refresh",  "summary" => "run an action for an intake entry" },
+      { "name" => "build",    "summary" => "materialize derived entries; publish_to and publish_each fan out copies" },
+      { "name" => "fetch", "summary" => "run an action for a quarantine entry" },
       { "name" => "freshness", "summary" => "per-entry freshness report (status, age, ttl, on_stale)" },
       { "name" => "audit", "summary" => "query .textus/audit.log with filters (key, role, since, correlation-id, ...)" },
       { "name" => "blame", "summary" => "audit rows for one key joined with git commit metadata" },
@@ -117,15 +94,14 @@ module Textus
       { "name" => "hook",
         "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
       { "name" => "pulse",
-        "summary" => "delta since cursor — changed entries, stale, pending review, doctor summary" },
+        "summary" => "delta since cursor — changed entries, stale, pending proposals, doctor summary" },
     ].freeze
 
     def self.agent_quickstart(manifest, audit_log)
-      proposer_roles = manifest.policy.roles_with_kind(:proposer)
-      agent_role = proposer_roles.first
+      agent_role = manifest.policy.proposer_role
 
-      writable_zones = manifest.data.zones.each_with_object([]) do |(zname, writers), acc|
-        acc << zname if agent_role && writers.include?(agent_role)
+      writable_zones = manifest.data.declared_zone_kinds.keys.each_with_object([]) do |zname, acc|
+        acc << zname if agent_role && manifest.policy.zone_writers(zname).include?(agent_role)
       end
 
       propose_zone = manifest.policy.propose_zone_for(agent_role)
@@ -139,12 +115,51 @@ module Textus
       }
     end
 
+    def self.recipes(manifest)
+      queue = manifest.policy.queue_zone
+      feeds = zone_label(manifest, :quarantine, "the quarantine zone")
+      {
+        "read" => {
+          "purpose" => "find and read an entry",
+          "steps" => [
+            "textus list --zone=ZONE --prefix=PREFIX  # discover keys",
+            "textus get KEY                            # returns envelope JSON",
+          ],
+        },
+        "write" => {
+          "purpose" => "create or update an entry",
+          "steps" => [
+            "textus schema get FAMILY                  # learn the _meta field shape",
+            "build an envelope JSON: {_meta: {...}, body: \"...\"}",
+            "echo ENVELOPE | textus put KEY --as=ROLE --stdin",
+          ],
+        },
+        "propose" => {
+          "purpose" => "agent suggests a change for human review",
+          "agent_steps" => [
+            "echo ENVELOPE | textus put #{queue}.KEY --as=agent --stdin",
+          ],
+          "human_steps" => [
+            "textus accept #{queue}.KEY --as=human       # promotes the proposal to its target zone",
+          ],
+        },
+        "fetch" => {
+          "purpose" => "rebuild stale quarantine-zone caches from their declared actions",
+          "steps" => [
+            "textus freshness --zone=#{feeds}            # report fresh/stale per entry",
+            "textus fetch stale --zone=#{feeds} --as=automation",
+          ],
+        },
+      }
+    end
+
     def self.agent_protocol(manifest)
       AGENT_PROTOCOL_TEMPLATE.merge(
+        "recipes" => recipes(manifest),
         "role_resolution" => {
           "summary" => "write role is resolved in order: --as flag, TEXTUS_ROLE env var, .textus/role file, " \
                        "default 'human'",
-          "roles" => manifest.policy.role_mapping.keys,
+          "roles" => manifest.data.role_caps.keys,
           "ref" => "SPEC.md §5",
         },
       )
@@ -167,12 +182,12 @@ module Textus
     end
 
     def self.zones_for(manifest)
-      manifest.data.zones.map do |name, writers|
-        row = { "name" => name, "writers" => Array(writers) }
+      manifest.data.declared_zone_kinds.keys.map do |name|
+        row = { "name" => name, "writers" => manifest.policy.zone_writers(name) }
         kind = manifest.policy.declared_kind(name)
         row["kind"] = kind.to_s if kind
-        purpose = ZONE_PURPOSES[name]
-        row["purpose"] = purpose if purpose
+        purpose = manifest.data.zone_descs[name]
+        row["purpose"] = purpose if purpose && !purpose.empty?
         row
       end
     end

data/lib/textus/cli/group/{refresh.rb → fetch.rb}

@@ -1,15 +1,15 @@
 module Textus
   class CLI
     class Group
-      class Refresh < Group
-        command_name "refresh"
+      class Fetch < Group
+        command_name "fetch"
 
         def parse(argv)
           if argv.first == "stale"
             argv.shift
-            @sub_klass = Verb::RefreshStale
+            @sub_klass = Verb::FetchStale
           else
-            @sub_klass = Verb::Refresh
+            @sub_klass = Verb::Fetch
           end
           @sub = @sub_klass.new(stdin: @stdin, stdout: @stdout, stderr: @stderr, cwd: @cwd)
           @sub.parse(argv)

data/lib/textus/cli/verb/build.rb

@@ -8,7 +8,7 @@ module Textus
 
         def call(store)
           Textus::Ports::BuildLock.with(root: store.root) do
-            role = store.manifest.policy.roles_with_kind(:generator).first || "builder"
+            role = store.manifest.policy.roles_with_capability("build").first || "automation"
             ops = store.as(role)
             result = ops.publish(prefix: prefix)
             emit(result)

data/lib/textus/cli/verb/fetch.rb

@@ -0,0 +1,14 @@
+module Textus
+  class CLI
+    class Verb
+      class Fetch < Verb
+        option :as_flag, "--as=ROLE"
+
+        def call(store)
+          key = positional.shift or raise UsageError.new("fetch requires a key")
+          emit(session_for(store).fetch(key).to_h_for_wire)
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/{refresh_stale.rb → fetch_stale.rb}

@@ -1,16 +1,16 @@
 module Textus
   class CLI
     class Verb
-      class RefreshStale < Verb
+      class FetchStale < Verb
         command_name "stale"
-        parent_group Group::Refresh
+        parent_group Group::Fetch
 
         option :prefix, "--prefix=KEY"
         option :zone, "--zone=Z"
         option :as_flag, "--as=ROLE"
 
         def call(store)
-          result = session_for(store).refresh_all(prefix: prefix, zone: zone)
+          result = session_for(store).fetch_all(prefix: prefix, zone: zone)
           emit(result)
           result["ok"] ? 0 : 1
         end

data/lib/textus/cli/verb/get.rb

@@ -8,7 +8,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("get requires a key")
-          result = session_for(store).get_or_refresh(key)
+          result = session_for(store).get_or_fetch(key)
           raise Textus::UnknownKey.new(key, suggestions: store.manifest.resolver.suggestions_for(key)) if result.nil?
 
           emit(result.to_h_for_wire)

data/lib/textus/cli/verb/hooks.rb

@@ -35,7 +35,7 @@ module Textus
 
                 rows << {
                   "event" => evt.to_s, "mode" => "manifest", "exec" => defn["exec"],
-                  "key" => e.key, "as" => defn["as"] || "runner"
+                  "key" => e.key, "as" => defn["as"] || "automation"
                 }
               end
             end

data/lib/textus/cli/verb/put.rb

@@ -25,7 +25,7 @@ module Textus
               {
                 "_meta" => {
                   "name" => basename,
-                  "last_refreshed_at" => Time.now.utc.iso8601,
+                  "last_fetched_at" => Time.now.utc.iso8601,
                   "fetched_with" => fetch_name,
                 }.merge(result[:_meta] || result["_meta"] || {}),
                 "body" => result[:body] || result["body"] || "",

data/lib/textus/cli/verb/rule_list.rb

@@ -8,16 +8,16 @@ module Textus
         def call(store)
           policies = store.manifest.rules.blocks.map do |b|
             row = { "match" => b.match }
-            if b.refresh
-              row["refresh"] = {
-                "ttl_seconds" => b.refresh.ttl_seconds,
-                "on_stale" => b.refresh.on_stale,
-                "sync_budget_ms" => b.refresh.sync_budget_ms,
-                "fetch_timeout_seconds" => b.refresh.fetch_timeout_seconds,
+            if b.fetch
+              row["fetch"] = {
+                "ttl_seconds" => b.fetch.ttl_seconds,
+                "on_stale" => b.fetch.on_stale,
+                "sync_budget_ms" => b.fetch.sync_budget_ms,
+                "fetch_timeout_seconds" => b.fetch.fetch_timeout_seconds,
               }
             end
             row["handler_allowlist"] = b.handler_allowlist.handlers if b.handler_allowlist
-            row["promotion"] = { "requires" => b.promote.requires } if b.promote
+            row["guard"] = b.guard if b.guard
             row["retention"] = { "expire_after" => b.retention.expire_after, "archive_after" => b.retention.archive_after } if b.retention
             row
           end

data/lib/textus/cli.rb

@@ -90,8 +90,8 @@ module Textus
           textus get KEY
           textus put KEY --stdin [--fetch=NAME] --as=ROLE
           textus freshness [--prefix=KEY] [--zone=Z]
-          textus refresh KEY
-          textus refresh stale [--prefix=KEY] [--zone=Z]
+          textus fetch KEY
+          textus fetch stale [--prefix=KEY] [--zone=Z]
           textus audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]
           textus blame KEY [--limit=N]
           textus doctor

data/lib/textus/container.rb

@@ -3,7 +3,7 @@ module Textus
   # ReadCaps/WriteCaps/HookCaps trio from 0.26.x. Built once per Store.
   Container = Data.define(
     :manifest, :file_store, :schemas, :root,
-    :audit_log, :events, :rpc, :authorizer
+    :audit_log, :events, :rpc
   )
 
   class Container
@@ -16,7 +16,6 @@ module Textus
         audit_log: store.audit_log,
         events: store.events,
         rpc: store.rpc,
-        authorizer: Textus::Domain::Authorizer.new(manifest: store.manifest),
       )
     end
   end

data/lib/textus/dispatcher.rb

@@ -11,13 +11,13 @@ module Textus
       accept: Textus::Write::Accept,
       reject: Textus::Write::Reject,
       publish: Textus::Write::Publish,
-      refresh: Textus::Write::RefreshWorker,
-      refresh_all: Textus::Write::RefreshAll,
+      fetch: Textus::Write::FetchWorker,
+      fetch_all: Textus::Write::FetchAll,
       retention_sweep: Textus::Write::RetentionSweep,
 
       # Read
       get: Textus::Read::Get,
-      get_or_refresh: Textus::Read::GetOrRefresh,
+      get_or_fetch: Textus::Read::GetOrFetch,
       list: Textus::Read::List,
       where: Textus::Read::Where,
       uid: Textus::Read::Uid,

data/lib/textus/doctor/check/{refresh_locks.rb → fetch_locks.rb}

@@ -1,13 +1,13 @@
 module Textus
   module Doctor
     class Check
-      # Lists per-key refresh lock files under <root>/.locks/ whose
+      # Lists per-key fetch lock files under <root>/.locks/ whose
       # recorded PID is no longer running. These are forensic artifacts only:
-      # Refresh::Lock uses flock(2), which the kernel releases on process
+      # Fetch::Lock uses flock(2), which the kernel releases on process
       # death, so stale files do not block subsequent acquires. The check
       # exists to let users clean up clutter and notice unexpected accumulation
-      # (e.g. a refresh path that crashes repeatedly).
-      class RefreshLocks < Check
+      # (e.g. a fetch path that crashes repeatedly).
+      class FetchLocks < Check
         def call
           dir = File.join(root, ".locks")
           return [] unless File.directory?(dir)
@@ -23,11 +23,11 @@ module Textus
           return nil if pid_alive?(pid)
 
           {
-            "code" => "refresh_lock.stale",
+            "code" => "fetch_lock.stale",
             "level" => "info",
             "subject" => path,
-            "message" => "refresh lock file at #{path} records dead PID #{pid} " \
-                         "(does not block refresh; flock is kernel-released on exit)",
+            "message" => "fetch lock file at #{path} records dead PID #{pid} " \
+                         "(does not block fetch; flock is kernel-released on exit)",
             "fix" => "safe to delete: rm #{path}",
           }
         rescue Errno::ENOENT

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

@@ -0,0 +1,45 @@
+module Textus
+  module Doctor
+    class Check
+      # Flags pending proposals whose `proposal.target_key` cannot ever be
+      # accepted: it points at a non-canon zone or resolves to no declared
+      # entry (ADR 0035). Reads the live queue zone; silent when there is no
+      # queue zone. Warnings, not errors — they are stale junk, not store
+      # corruption (the accept gate already refuses them).
+      class ProposalTargets < Check
+        def call
+          queue = manifest.policy.queue_zone
+          return [] unless queue
+
+          dispatch(:list, zone: queue).filter_map { |row| issue_for(row["key"]) }
+        end
+
+        private
+
+        def issue_for(key)
+          target = dispatch(:get, key).meta&.dig("proposal", "target_key")
+          return nil if target.nil? # not a proposal entry — skip
+
+          zone = manifest.resolver.resolve(target).entry.zone
+          return nil if manifest.policy.declared_kind(zone.to_s) == :canon
+
+          {
+            "code" => "proposal.target_not_canon",
+            "level" => "warning",
+            "subject" => key,
+            "message" => "proposal '#{key}' targets '#{target}' in zone '#{zone}' (not canon); it can never be accepted",
+            "fix" => "delete the proposal, or repoint target_key at a canon zone",
+          }
+        rescue Textus::UnknownKey
+          {
+            "code" => "proposal.target_unresolved",
+            "level" => "warning",
+            "subject" => key,
+            "message" => "proposal '#{key}' targets '#{target}', which resolves to no declared entry",
+            "fix" => "delete the proposal, or fix target_key",
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -2,11 +2,11 @@ module Textus
   module Doctor
     class Check
       # Flags entries whose key is matched by two or more rule blocks of the
-      # SAME specificity in the same slot (refresh / handler_allowlist /
-      # promote). Ties are non-deterministic in the parser's pick step, so
+      # SAME specificity in the same slot (fetch / handler_allowlist /
+      # guard). Ties are non-deterministic in the parser's pick step, so
       # they're a configuration smell — surface them.
       class RuleAmbiguity < Check
-        SLOTS = %i[refresh handler_allowlist promote].freeze
+        SLOTS = %i[fetch handler_allowlist guard].freeze
 
         def call
           out = []