textus 0.39.1 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af15d8a77f0d71c3fab21dc246545b3a7b84242361c518b1d901c491c63e55c4
-  data.tar.gz: 4644479ed6df331a6973806fed302b29446d3806d1793d8ea9d9fa661000e986
+  metadata.gz: 96c684d8a670835fb687a321abb85838ec831e95e8672b7f03453266e2224b65
+  data.tar.gz: d9332836814f977824413a7bc379666cfd830f182d2c44a9ed5a71d1e7336513
 SHA512:
-  metadata.gz: ee1cf4024e3583c1e59791b279a2fd0f8c00e426f05391267db0239d1a7d2909c521b94bc27caf62d549d902b0dc7f62847178f0ea17973e14b26689a981302a
-  data.tar.gz: 775daa6d3992b0b93d2a57c230fbfc5705b50fec592327356f4fa6ccc4dc39aaacdcbd1c24d2dd878a1b6612fd5e9c3416ede0b42d9ba90978dc8f8461c6d014
+  metadata.gz: cbfdd6527a26f2e8fb97cdde2cc99c5df4d36839af1f426bf52156335187d4b48ecbe45af1b271031861bc225d100676522082da6f74c171555bd5cf7bd0b227
+  data.tar.gz: 38ac5fff2e9209c8bbbc15745a1ddbd840736ddcc23363c6a61099926b79807a9ccb49630a98b69f6ed41cf2a15d3272bd586f6bc749ea381e4d24158eeb597a

data/CHANGELOG.md

@@ -11,6 +11,29 @@ tracks both additive improvements and breaking protocol bumps independently.
 
 ## Unreleased
 
+## 0.40.0 — 2026-06-02 — `publish_each` owns multi-file leaf subtrees ([ADR 0046](docs/architecture/decisions/0046-publish-leaf-subtrees.md))
+
+No `textus/3` wire-format change — publish is repo-local materialization. The
+publish *unit* is derived from the entry's existing `index_filename`, not a new
+manifest key (SPEC §4, §5.3).
+
+### Added
+
+- **`publish_each` copies a leaf's whole subtree when the entry declares `index_filename` ([ADR 0046](docs/architecture/decisions/0046-publish-leaf-subtrees.md)).** textus can now own a prose-heavy, multi-file artifact (e.g. a Claude Code Agent Skill: `SKILL.md` + `commands.md` + `references/*`) as a single addressable unit. An entry *without* `index_filename` still publishes one file per leaf (unchanged); an entry *with* `index_filename` treats each leaf as a directory and copies the whole subtree — ignore-filtered (ADR 0042), preserving in-leaf layout, one sentinel per file. Siblings ride along at publish time only: they are never enumerated, addressable, or proposable (the key↔path bijection is preserved). On rebuild, managed orphans under a leaf are pruned (file + sentinel); **unmanaged files are never deleted**. The build envelope grows a `pruned` array.
+- **`doctor` flags orphaned publish targets.** A new `orphaned_publish_targets` check reports a published file whose recorded source no longer exists in the store (a renamed or removed whole leaf) — drift that per-entry `build` won't revisit.
+
+### Changed
+
+- **BREAKING (pre-1.0): directory-leaf `publish_each` semantics ([ADR 0046](docs/architecture/decisions/0046-publish-leaf-subtrees.md)).** An entry with `index_filename` + `publish_each` whose leaf directories contain siblings previously published *only the index file*; it now publishes the whole subtree. This breaks no correct usage — it is either the dropped-siblings defect this fixes, or a template that named a file rather than a directory, which the validator now **rejects loudly** at manifest load. **Migration:** a directory-leaf `publish_each` template must name the target *directory* — drop a trailing index filename (`.../{leaf}/SKILL.md` → `.../{leaf}`) or any file extension (`.../{leaf}.md` → `.../{leaf}`), and use `{leaf}` or `{key}` (not `{basename}`/`{ext}`, which are file-only).
+- **Role names are now a closed set `{human, agent, automation}` ([ADR 0045](docs/architecture/decisions/0045-close-role-name-set.md)).** A manifest declaring any other role name is rejected at load with `unknown role name '<x>' (allowed: human, agent, automation)`. `Role::NAMES` is the single source of truth; each role's `can:` capabilities remain fully tunable. Principal multiplicity moves to the `owner:` field (`owner: human:patrick`). Stricter `textus/3` validation in `Schema.validate_roles!` — no protocol bump; all shipped manifests already comply.
+- **Hook event tables consolidated into `Textus::Hooks::Catalog` (single source
+  of truth).** `EventBus` and `RpcRegistry` no longer keep their own event
+  tables; both registries, the Loader DSL router, and internal consumers read
+  `Catalog::PUBSUB` / `Catalog::RPC` directly. This removes the drift-prone
+  `EventBus::RPC_EVENTS` literal that could silently fall out of sync with
+  `RpcRegistry`'s events and weaken the cross-registry guards. Internal
+  refactor — no `textus/3` wire-format change.
+
 ## 0.39.1 — 2026-06-01 — Feed ergonomics: `feeds.machine` env snapshot + intake cookbook ([ADR 0043](docs/architecture/decisions/0043-feed-ergonomics-without-breaking-core-purity.md))
 
 No `textus/3` wire-format change. `textus init` scaffolds an additional

data/SPEC.md

@@ -242,7 +242,7 @@ For `nested: true`, the recursive glob matches the format's extension (markdown
 
 A file at `.textus/zones/skills/ask/SKILL.md` enumerates as `skills.ask`; `.textus/zones/skills/ask/references/algorithm.md` is not enumerated. Resolving `skills.ask` returns the `SKILL.md` path. `index_filename:` requires `nested: true`; the value must be a bare basename (no slashes).
 
-**Per-leaf publishing (`publish_each:`).** A nested manifest entry MAY declare `publish_each:` to byte-copy every leaf to a templated repo-relative path. `publish_each:` and `publish_to:` are mutually exclusive on the same entry, and `publish_each:` requires `nested: true`. The template substitutes these variables (using `{name}` syntax):
+**Per-leaf publishing (`publish_each:`).** A nested manifest entry MAY declare `publish_each:` to copy every leaf to a templated repo-relative path. `publish_each:` and `publish_to:` are mutually exclusive on the same entry, and `publish_each:` requires `nested: true`. The template substitutes these variables (using `{name}` syntax):
 
 | Variable     | Value                                                                                  |
 |--------------|----------------------------------------------------------------------------------------|
@@ -251,7 +251,15 @@ A file at `.textus/zones/skills/ask/SKILL.md` enumerates as `skills.ask`; `.text
 | `{key}`      | Full dotted key.                                                                       |
 | `{ext}`      | Primary extension for the entry's format, without the leading dot (`md`/`json`/`yaml`/`txt`). |
 
-Validation at manifest load: any unknown variable raises `UsageError`; the template MUST reference at least one of `{leaf}`, `{basename}`, `{key}` (otherwise every leaf would clobber the same target). A computed target outside the repo root is refused at build time with `PublishError`. Example:
+The publish *unit* is derived from the entry's shape, which `index_filename:` already declares (ADR 0046) — there is no separate tree-vs-file key:
+
+- **Entry *without* `index_filename`** — a leaf is a *file*. `publish_each:` names a file target and one file is byte-copied per leaf.
+- **Entry *with* `index_filename`** — a leaf is a *directory*. `publish_each:` names a directory target, and the **whole leaf subtree** is copied: every file under the leaf directory (the index plus its siblings) is byte-copied to `<target_dir>/<path-relative-to-leaf>`, preserving in-leaf layout. Siblings are opaque payload — they are never enumerated, addressable, or proposable; only the index is a key. The entry's `ignore:` globs (§4, ADR 0042) filter the copied set. Each copied file gets its own sentinel. On rebuild, files under the target that are textus-managed but no longer produced by the current source are **pruned** (file + sentinel); files with no sentinel are never deleted.
+
+Validation at manifest load: any unknown variable raises `UsageError`; a computed target outside the repo root is refused at build time with `PublishError`. The discriminator requirement depends on the leaf shape:
+
+- **File-leaf** templates MUST reference at least one of `{leaf}`, `{basename}`, `{key}` (otherwise every leaf would clobber the same target).
+- **Directory-leaf** templates (entry has `index_filename`) MUST reference `{leaf}` or `{key}`, and MUST NOT use `{basename}` or `{ext}` (file-only). Because the target is a directory, the template's final segment MUST NOT be the `index_filename` (the `.../{leaf}/SKILL.md` footgun — it would copy the subtree into a directory literally named `SKILL.md/`) and MUST NOT carry a file extension (e.g. `.../{leaf}.md`); both are rejected at load with a fix-the-template message.
 
 ```yaml
 - key: working.skills
@@ -259,10 +267,12 @@ Validation at manifest load: any unknown variable raises `UsageError`; the templ
   zone: working
   schema: skill
   nested: true
-  publish_each: "skills/{basename}/SKILL.md"
+  index_filename: SKILL.md
+  publish_each: "skills/{leaf}"
+  ignore: ["*.tmp", ".DS_Store"]
 ```
 
-A leaf at `working.skills.writing.voice-writer` (authored at `.textus/zones/working/skills/writing/voice-writer.md`) publishes to `skills/voice-writer/SKILL.md`.
+A leaf at `working.skills.voice-writer` (a directory `.textus/zones/working/skills/voice-writer/` containing `SKILL.md`, `commands.md`, and `references/*`) publishes its whole subtree under `skills/voice-writer/`, preserving layout.
 
 **`inject_boot:`.** A derived entry with a `template:` MAY declare `inject_boot: true`. When `textus build` materializes the entry, it merges the `textus boot` envelope (§9) into the projection data under the key `boot`, so the template can render orientation content (zones, write flows, CLI catalog) alongside its projected rows. The flag is rejected at manifest load on (a) non-derived entries or (b) derived entries without a `template:` — agents reading the rendered file should be able to trust the preamble was produced by the same source of truth `textus boot` exposes.
 
@@ -468,7 +478,7 @@ When the entry is recomputed, textus copies the in-store file byte-for-byte to e
 
 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.
 
-**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.
+**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 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 publish unit follows the entry's `index_filename` (ADR 0046): a file-leaf entry byte-copies one file per leaf; a directory-leaf entry (with `index_filename`) byte-copies the leaf's whole subtree — one row and one sentinel **per file** — applying the entry's `ignore:` filter, and prunes textus-managed files under the target that the current source no longer produces (never touching unmanaged files). The build envelope grows a `published_leaves` array — one row per published file, with `key`, `source`, and `target` — alongside the existing `built` array, plus a `pruned` array listing any orphaned managed files removed on this build. Targets that would resolve outside the repo root are refused.
 
 ### 5.4 Intake (declared, fetched via registered intake handler)
 

data/lib/textus/boot.rb

@@ -236,10 +236,10 @@ module Textus
 
     def self.hooks_for_container_internal(rpc:, events:)
       sections = {}
-      Hooks::RpcRegistry::EVENTS.each_key do |event|
+      Hooks::Catalog::RPC.each_key do |event|
         sections[event.to_s] = rpc.names(event).map(&:to_s).sort
       end
-      Hooks::EventBus::EVENTS.each_key do |event|
+      Hooks::Catalog::PUBSUB.each_key do |event|
         sections[event.to_s] = events.pubsub_handlers(event).map { |h| h[:name].to_s }.sort
       end
       sections

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

@@ -7,8 +7,12 @@ module Textus
         option :prefix, "--prefix=K"
 
         def call(store)
+          role = store.manifest.policy.actor_for("build") or
+            raise UsageError.new(
+              "no role holds the 'build' capability",
+              hint: "declare a role with `can: [build]` in .textus/manifest.yaml",
+            )
           Textus::Ports::BuildLock.with(root: store.root) do
-            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/hooks.rb

@@ -16,12 +16,12 @@ module Textus
           end
 
           rows = []
-          Textus::Hooks::RpcRegistry::EVENTS.each_key do |event|
+          Textus::Hooks::Catalog::RPC.each_key do |event|
             store.rpc.names(event).each do |name|
               rows << { "event" => event.to_s, "mode" => "rpc", "name" => name.to_s }
             end
           end
-          Textus::Hooks::EventBus::EVENTS.each_key do |event|
+          Textus::Hooks::Catalog::PUBSUB.each_key do |event|
             store.events.pubsub_handlers(event).each do |h|
               row = { "event" => event.to_s, "mode" => "pubsub", "name" => h[:name].to_s }
               row["keys"] = Array(h[:keys]) if h[:keys]
@@ -35,7 +35,7 @@ module Textus
 
                 rows << {
                   "event" => evt.to_s, "mode" => "manifest", "exec" => defn["exec"],
-                  "key" => e.key, "as" => defn["as"] || "automation"
+                  "key" => e.key, "as" => defn["as"] || Textus::Role::AUTOMATION
                 }
               end
             end

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

@@ -0,0 +1,35 @@
+module Textus
+  module Doctor
+    class Check
+      # Flags published files whose recorded source no longer exists in the
+      # store. Per-leaf prune (ADR 0046) reconciles within a still-present
+      # leaf; a renamed or removed *whole* leaf orphans its entire target
+      # directory, which a per-entry build won't revisit. This check catches
+      # that drift without making `build` scan globally.
+      class OrphanedPublishTargets < Check
+        def call
+          sdir = File.join(root, Textus::Ports::SentinelStore::DIR)
+          return [] unless File.directory?(sdir)
+
+          repo_root = File.dirname(root)
+          store = Textus::Ports::SentinelStore.new
+          glob = File.join(sdir, "**", "*#{Textus::Ports::SentinelStore::SUFFIX}")
+          Dir.glob(glob).filter_map do |spath|
+            sentinel = store.load(spath, repo_root)
+            next nil if sentinel.nil? || sentinel.source.nil?
+            next nil if File.exist?(sentinel.source)
+
+            {
+              "code" => "publish.orphaned_target",
+              "level" => "warning",
+              "subject" => sentinel.target,
+              "message" => "published file #{sentinel.target} has no source in the store " \
+                           "(recorded source #{sentinel.source} is gone) — likely a renamed or removed leaf",
+              "fix" => "remove the stale copy and its sentinel: rm '#{sentinel.target}' '#{spath}'",
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor.rb

@@ -24,6 +24,7 @@ module Textus
       Check::RuleAmbiguity,
       Check::HandlerAllowlist,
       Check::FetchLocks,
+      Check::OrphanedPublishTargets,
       Check::ProposalTargets,
     ].freeze
 

data/lib/textus/hooks/catalog.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Textus
+  module Hooks
+    # The single source of truth for hook event names and their required
+    # kwargs. EventBus, RpcRegistry, and the Loader DSL router all read these
+    # tables directly — the registries do not keep their own copies. Catalog
+    # references no other constant, so it has no load-order cycle, which is
+    # what removed the previous drift hazard (EventBus held a hard-coded
+    # `RPC_EVENTS` list that could fall out of sync with RpcRegistry's table).
+    module Catalog
+      # Pub-sub events: 0..N handlers, fire-and-forget, receive `ctx:`.
+      PUBSUB = {
+        entry_put: %i[ctx key envelope],
+        entry_deleted: %i[ctx key],
+        entry_fetched: %i[ctx key envelope change],
+        entry_renamed: %i[ctx key from_key to_key envelope],
+        build_completed: %i[ctx key envelope sources],
+        proposal_accepted: %i[ctx key target_key],
+        proposal_rejected: %i[ctx key target_key],
+        file_published: %i[ctx key envelope source target],
+        store_loaded: %i[ctx],
+        fetch_started: %i[ctx key mode],
+        fetch_failed: %i[ctx key error_class error_message],
+        fetch_backgrounded: %i[ctx key started_at budget_ms],
+      }.freeze
+
+      # RPC events: single handler, return value matters, receive `caps:`.
+      RPC = {
+        resolve_intake: %i[caps config args],
+        transform_rows: %i[caps rows config],
+        validate: %i[caps],
+      }.freeze
+    end
+  end
+end

data/lib/textus/hooks/event_bus.rb

@@ -7,23 +7,6 @@ module Textus
 
       class HookTimeout < StandardError; end
 
-      EVENTS = {
-        entry_put: %i[ctx key envelope],
-        entry_deleted: %i[ctx key],
-        entry_fetched: %i[ctx key envelope change],
-        entry_renamed: %i[ctx key from_key to_key envelope],
-        build_completed: %i[ctx key envelope sources],
-        proposal_accepted: %i[ctx key target_key],
-        proposal_rejected: %i[ctx key target_key],
-        file_published: %i[ctx key envelope source target],
-        store_loaded: %i[ctx],
-        fetch_started: %i[ctx key mode],
-        fetch_failed: %i[ctx key error_class error_message],
-        fetch_backgrounded: %i[ctx key started_at budget_ms],
-      }.freeze
-
-      RPC_EVENTS = %i[resolve_intake transform_rows validate].freeze
-
       def initialize(error_log: ErrorLog.new)
         @pubsub = Hash.new { |h, k| h[k] = [] }
         @error_handlers = []
@@ -36,9 +19,9 @@ module Textus
 
       def register(event, name, keys: nil, &blk)
         event_sym = event.to_sym
-        raise UsageError.new("#{event_sym} is an RPC event; register on RpcRegistry") if RPC_EVENTS.include?(event_sym)
+        raise UsageError.new("#{event_sym} is an RPC event; register on RpcRegistry") if Catalog::RPC.key?(event_sym)
 
-        required = EVENTS[event_sym] or raise UsageError.new("unknown event: #{event}")
+        required = Catalog::PUBSUB[event_sym] or raise UsageError.new("unknown event: #{event}")
         sig = Signature.new(blk)
         missing = sig.missing(required)
         if missing.any?

data/lib/textus/hooks/loader.rb

@@ -12,7 +12,7 @@ module Textus
         # Pubsub registration — delegates to EventBus.
         # Also handles RPC event names by delegating to RpcRegistry.
         def on(event, name, keys: nil, &)
-          if Hooks::RpcRegistry::EVENTS.key?(event.to_sym)
+          if Hooks::Catalog::RPC.key?(event.to_sym)
             @rpc.register(event, name, &)
           else
             @events.register(event, name, keys: keys, &)

data/lib/textus/hooks/rpc_registry.rb

@@ -3,23 +3,15 @@
 module Textus
   module Hooks
     class RpcRegistry
-      EVENTS = {
-        resolve_intake: %i[caps config args],
-        transform_rows: %i[caps rows config],
-        validate: %i[caps],
-      }.freeze
-
-      PUBSUB_EVENTS = EventBus::EVENTS.keys.freeze
-
       def initialize
         @table = Hash.new { |h, k| h[k] = {} }
       end
 
       def register(event, name, &blk)
         event_sym = event.to_sym
-        raise UsageError.new("#{event_sym} is a pubsub event; register on EventBus") if PUBSUB_EVENTS.include?(event_sym)
+        raise UsageError.new("#{event_sym} is a pubsub event; register on EventBus") if Catalog::PUBSUB.key?(event_sym)
 
-        required = EVENTS[event_sym] or raise UsageError.new("unknown RPC event: #{event}")
+        required = Catalog::RPC[event_sym] or raise UsageError.new("unknown RPC event: #{event}")
         sig = Signature.new(blk)
         missing = sig.missing(required)
         raise UsageError.new("#{event_sym} RPC must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})") if missing.any?
@@ -38,7 +30,7 @@ module Textus
 
       # Invoke a registered callable, injecting `caps:` only if the callable
       # declares it (or accepts keyrest). Mis-named kwargs (e.g. the legacy
-      # `caps:`-alternative) are rejected at registration time, not here.
+      # `store:`) are rejected at registration time, not here.
       def invoke(event, name, caps:, **other)
         blk = callable(event, name)
         sig = Signature.new(blk)

data/lib/textus/manifest/capabilities.rb

@@ -11,9 +11,9 @@ module Textus
       # declares a `kind: workspace` zone is therefore rejected at load (no
       # `keep`-holder); declare `roles:` to opt into a workspace lane (ADR 0033).
       DEFAULT_MAPPING = {
-        "human" => %w[author propose].freeze,
-        "agent" => %w[propose].freeze,
-        "automation" => %w[fetch build].freeze,
+        Textus::Role::HUMAN => %w[author propose].freeze,
+        Textus::Role::AGENT => %w[propose].freeze,
+        Textus::Role::AUTOMATION => %w[fetch build].freeze,
       }.freeze
 
       # Returns { role_name => [verbs] }. When `roles:` is declared we use

data/lib/textus/manifest/entry/nested.rb

@@ -41,6 +41,7 @@ module Textus
           return nil if @publish_each.nil?
 
           leaves = []
+          pruned = [] # accumulates orphans removed by prune_orphans below
           pctx.manifest.resolver.enumerate(prefix: @key).each do |row|
             next unless row[:manifest_entry].equal?(self)
             next if prefix && !row[:key].start_with?(prefix) && row[:key] != prefix
@@ -53,18 +54,57 @@ module Textus
               )
             end
 
-            Textus::Ports::Publisher.publish(source: row[:path], target: target_abs, store_root: pctx.root)
-            pctx.emit(:file_published,
-                      key: row[:key],
-                      envelope: pctx.reader.call(row[:key]),
-                      source: row[:path],
-                      target: target_abs)
-            leaves << { "key" => row[:key], "source" => row[:path], "target" => target_abs }
+            written = @index_filename ? publish_subtree(row, target_abs, pctx) : [publish_one(row, target_abs, pctx)]
+            pruned.concat(prune_orphans(target_abs, written, pctx)) if @index_filename
+            written.each { |w| leaves << { "key" => row[:key], "source" => w["source"], "target" => w["target"] } }
           end
 
-          { kind: :leaves, value: leaves }
+          { kind: :leaves, value: leaves, pruned: pruned }
         end
 
+        def publish_one(row, target_abs, pctx)
+          Textus::Ports::Publisher.publish(source: row[:path], target: target_abs, store_root: pctx.root)
+          pctx.emit(:file_published, key: row[:key], envelope: pctx.reader.call(row[:key]),
+                                     source: row[:path], target: target_abs)
+          { "source" => row[:path], "target" => target_abs }
+        end
+
+        def publish_subtree(row, target_dir, pctx)
+          base = File.join(pctx.root, "zones", path)
+          leaf_dir = File.dirname(row[:path])
+          # FNM_DOTMATCH includes dotfiles; File.file? below skips dirs (and symlinks-to-dirs). Leaf trees are authored content, not arbitrary symlink graphs.
+          Dir.glob(File.join(leaf_dir, "**", "*"), File::FNM_DOTMATCH).sort.filter_map do |src|
+            next nil unless File.file?(src)
+
+            rel_to_base = src.sub(%r{\A#{Regexp.escape(base)}/}, "")
+            next nil if ignored?(rel_to_base)
+
+            rel_to_leaf = src.sub(%r{\A#{Regexp.escape(leaf_dir)}/}, "")
+            dst = File.join(target_dir, rel_to_leaf)
+            Textus::Ports::Publisher.publish(source: src, target: dst, store_root: pctx.root)
+            pctx.emit(:file_published, key: row[:key], envelope: pctx.reader.call(row[:key]),
+                                       source: src, target: dst)
+            { "source" => src, "target" => dst }
+          end
+        end
+
+        # Scoped to this leaf's target_dir only. Safe across leaves because ADR 0046
+        # Decision 5 (shallowest-index-wins) keeps leaf dirs non-nesting, so {leaf}-derived
+        # target dirs never nest and targets_under can't reach another leaf's sentinels.
+        def prune_orphans(target_dir, written, pctx)
+          kept = written.map { |w| File.expand_path(w["target"]) }
+          store = Textus::Ports::SentinelStore.new
+          store.targets_under(target_dir, pctx.root).filter_map do |managed|
+            next nil if kept.include?(File.expand_path(managed))
+
+            Textus::Ports::Publisher.unpublish(target: managed, store_root: pctx.root)
+            managed
+          end
+        end
+
+        # Helpers are private; KIND / self.from_raw / REGISTRY below are intentionally public.
+        private :publish_one, :publish_subtree, :prune_orphans
+
         KIND = :nested
 
         def self.from_raw(common, raw)

data/lib/textus/manifest/entry/validators/events.rb

@@ -4,7 +4,7 @@ module Textus
       module Validators
         module Events
           def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
-            pubsub_events = Textus::Hooks::EventBus::EVENTS.keys
+            pubsub_events = Textus::Hooks::Catalog::PUBSUB.keys
             events = entry.events
             events.each_key do |evt|
               next if pubsub_events.include?(evt.to_sym)

data/lib/textus/manifest/entry/validators/publish_each.rb

@@ -27,13 +27,51 @@ module Textus
               )
             end
 
-            return if used_vars.any? { |v| REQUIRED_DISCRIMINATOR_VARS.include?(v) }
+            validate_discriminator(entry, used_vars, publish_each)
+          end
+
+          def self.validate_discriminator(entry, used_vars, publish_each)
+            if entry.index_filename
+              forbidden = used_vars & %w[basename ext]
+              unless forbidden.empty?
+                raise UsageError.new(
+                  "entry '#{entry.key}': publish_each names a directory " \
+                  "(index_filename: '#{entry.index_filename}'); {basename}/{ext} are file-only — " \
+                  "use {leaf} or {key}.",
+                )
+              end
+              last_segment = publish_each.sub(%r{/\z}, "").split("/").last
+              if last_segment == entry.index_filename
+                raise UsageError.new(
+                  "entry '#{entry.key}': directory-leaf publish_each must name the target DIRECTORY, " \
+                  "not the index file — drop the trailing '/#{entry.index_filename}' " \
+                  "(the whole leaf subtree is copied into the named directory).",
+                )
+              end
+              ext = File.extname(last_segment)
+              unless ext.empty?
+                raise UsageError.new(
+                  "entry '#{entry.key}': directory-leaf publish_each names a DIRECTORY target, but its " \
+                  "final segment '#{last_segment}' looks like a file (extension '#{ext}') — " \
+                  "drop the extension (the whole leaf subtree is copied into the named directory).",
+                )
+              end
+              return if used_vars.intersect?(%w[leaf key])
+
+              raise UsageError.new(
+                "entry '#{entry.key}': directory-leaf publish_each must reference {leaf} or {key} " \
+                "(else every leaf would clobber the same directory).",
+              )
+            end
+
+            return if used_vars.intersect?(REQUIRED_DISCRIMINATOR_VARS)
 
             raise UsageError.new(
               "entry '#{entry.key}': publish_each must reference at least one of {leaf}, {basename}, or {key} " \
               "(else every leaf would clobber the same target).",
             )
           end
+          private_class_method :validate_discriminator
         end
       end
     end

data/lib/textus/manifest/policy.rb

@@ -34,6 +34,13 @@ module Textus
         (proposers - roles_with_capability("author")).first || proposers.first
       end
 
+      # The role textus acts AS for a system-initiated operation requiring
+      # `verb` (no human passed --as). Capability-derived — a role name that
+      # exists in the manifest, or nil. Never a hardcoded literal (ADR 0044).
+      def actor_for(verb)
+        roles_with_capability(verb).first
+      end
+
       # The roles authorized to write `zone_name`: those holding the verb its
       # kind requires. Raises on an undeclared zone.
       def zone_writers(zone_name)

data/lib/textus/manifest/resolver.rb

@@ -72,8 +72,21 @@ module Textus
         return [] unless File.directory?(base)
 
         entry_index_filename = entry.index_filename
-        glob_pattern = entry_index_filename ? "**/#{entry_index_filename}" : nested_glob(entry.format)
-        Dir.glob(File.join(base, glob_pattern)).filter_map { |path| nested_row_for(entry, base, path) }
+        unless entry_index_filename
+          return Dir.glob(File.join(base, nested_glob(entry.format)))
+                    .filter_map { |path| nested_row_for(entry, base, path) }
+        end
+
+        claimed = []
+        Dir.glob(File.join(base, "**", entry_index_filename))
+           .sort_by { |path| path.count("/") }
+           .filter_map do |path|
+          leaf_dir = File.dirname(path)
+          next nil if claimed.any? { |d| leaf_dir.start_with?("#{d}/") }
+
+          claimed << leaf_dir
+          nested_row_for(entry, base, path)
+        end
       end
 
       def nested_row_for(entry, base, path)

data/lib/textus/manifest/schema.rb

@@ -35,6 +35,13 @@ module Textus
       RETENTION_KEYS = %w[expire_after archive_after].freeze
       AUDIT_KEYS = %w[max_size keep].freeze
 
+      # Syntactic shape of an `owner:` subject token (the `patrick` in
+      # `human:patrick`) — the subject half of the owner-validation rule below.
+      # Role supplies the archetype set (Role::NAMES); this pattern is the
+      # owner-specific part, so it lives with the rule that composes them
+      # (ADR 0045 D1). Acting-role *names* are gated by Role::NAMES, not a regex.
+      OWNER_SUBJECT_PATTERN = /\A[a-z][a-z0-9_-]*\z/
+
       def self.validate!(raw)
         raise BadManifest.new("manifest must be a hash") unless raw.is_a?(Hash)
 
@@ -42,6 +49,7 @@ module Textus
         validate_roles!(raw["roles"])
         validate_zones!(raw["zones"])
         validate_entries!(raw["entries"])
+        validate_owners!(raw["zones"], raw["entries"])
         validate_rules!(raw["rules"])
         walk(raw["audit"], AUDIT_KEYS, "$.audit") if raw["audit"].is_a?(Hash)
         validate_single_queue!(raw)
@@ -91,6 +99,12 @@ module Textus
           path = "$.roles[#{i}]"
           walk(r, ROLE_KEYS, path)
           name = r["name"] or raise BadManifest.new("role at '#{path}' missing name")
+          unless Textus::Role::NAMES.include?(name)
+            raise BadManifest.new(
+              "unknown role name '#{name}' at '#{path}' " \
+              "(allowed: #{Textus::Role::NAMES.join(", ")})",
+            )
+          end
           Array(r["can"]).each do |verb|
             next if CAPABILITIES.include?(verb)
 
@@ -109,6 +123,47 @@ module Textus
         )
       end
 
+      # Owners are validated against the SAME closed archetype set as role names
+      # (ADR 0045 D1) so attribution can't bypass the closed-name guarantee.
+      # Applies to both zone owners and entry owners; owner is optional, so a
+      # nil owner is not an error.
+      def self.validate_owners!(zones, entries)
+        Array(zones).each_with_index do |z, i|
+          check_owner!(z["owner"], "$.zones[#{i}]")
+        end
+        Array(entries).each_with_index do |e, i|
+          check_owner!(e["owner"], "$.entries[#{i}]")
+        end
+      end
+
+      def self.check_owner!(owner, path)
+        return if owner.nil?
+        return if valid_owner?(owner)
+
+        raise BadManifest.new(
+          "invalid owner '#{owner}' at '#{path}' " \
+          "(expected <archetype> or <archetype>:<subject>, " \
+          "archetype one of: #{Textus::Role::NAMES.join(", ")})",
+        )
+      end
+
+      # The owner-validation rule: an `owner:` token is either a bare archetype
+      # (`agent`) or `<archetype>:<subject>` (`human:patrick`). The archetype is
+      # gated against the closed Role::NAMES set (so attribution can't smuggle in
+      # a name the role side rejects, ADR 0045 D1); the subject is the free-form
+      # principal, validated by OWNER_SUBJECT_PATTERN. Split on the FIRST ':'
+      # only — a subject may not itself contain ':' (the pattern excludes it), so
+      # `human:a:b` is rejected.
+      def self.valid_owner?(token)
+        return false unless token.is_a?(String) && !token.empty?
+
+        archetype, subject = token.split(":", 2)
+        return false unless Textus::Role::NAMES.include?(archetype)
+        return true if subject.nil?
+
+        OWNER_SUBJECT_PATTERN.match?(subject)
+      end
+
       def self.validate_fetch_timeout!(value, path)
         return if value.nil?
         return if value.is_a?(Integer) && value.positive? && value <= FETCH_TIMEOUT_SECONDS_CEILING

data/lib/textus/ports/audit_subscriber.rb

@@ -33,7 +33,7 @@ module Textus
         extras["target_key"]  = kwargs[:target_key]  if kwargs.key?(:target_key)
         extras["pending_key"] = kwargs[:pending_key] if kwargs.key?(:pending_key)
         @audit_log.append(
-          role: "automation", verb: "event_error", key: key,
+          role: Textus::Role::AUTOMATION, verb: "event_error", key: key,
           etag_before: nil, etag_after: nil, extras: extras
         )
       end

data/lib/textus/ports/fetch/detached.rb

@@ -8,6 +8,10 @@ module Textus
           Process.respond_to?(:fork)
         end
 
+        def acting_role(store)
+          store.manifest.policy.actor_for("fetch")
+        end
+
         def spawn(store_root:, key:)
           return nil unless supported?
 
@@ -21,7 +25,13 @@ module Textus
 
             begin
               store = Textus::Store.new(store_root)
-              store.as("automation").fetch(key)
+              # No fetch-holder configured — exit the child cleanly. In practice
+              # this is unreachable: the background fork only happens after a
+              # foreground fetch was already authorized (so a fetch-holder
+              # exists). Config-time detection is doctor's job (ADR 0044 Q2).
+              role = acting_role(store)
+              exit(0) unless role
+              store.as(role).fetch(key)
             rescue StandardError
               # Already logged via :fetch_failed; exit cleanly.
             ensure

data/lib/textus/ports/publisher.rb

@@ -18,6 +18,16 @@ module Textus
         Textus::Ports::SentinelStore.new.write!(target: target, source: source, store_root: store_root)
       end
 
+      # Removes a previously-published file and its sentinel. No-op unless the
+      # target is textus-managed — never deletes an unmanaged file.
+      def self.unpublish(target:, store_root:)
+        return unless managed?(target, store_root)
+
+        FileUtils.rm_f(target)
+        sentinel = Textus::Ports::SentinelStore.new.sentinel_path(target, store_root)
+        FileUtils.rm_f(sentinel)
+      end
+
       def self.refuse_if_unmanaged(target, store_root)
         return unless File.exist?(target) || File.symlink?(target)
         return if managed?(target, store_root)

data/lib/textus/ports/sentinel_store.rb

@@ -42,6 +42,21 @@ module Textus
         File.join(store_root, DIR, rel + SUFFIX)
       end
 
+      # Absolute target paths of every sentinel recorded under `target_dir`.
+      def targets_under(target_dir, store_root)
+        repo_root = File.dirname(store_root)
+        rel = relative_to(target_dir, repo_root) or return []
+        sdir = File.join(store_root, DIR, rel)
+        return [] unless File.directory?(sdir)
+
+        prefix = File.join(store_root, DIR) + "/"
+        Dir.glob(File.join(sdir, "**", "*#{SUFFIX}")).map do |spath|
+          # strip the sentinel-store prefix and the .textus-managed.json suffix to recover the repo-relative target path
+          trel = spath.delete_prefix(prefix).delete_suffix(SUFFIX)
+          File.join(repo_root, trel)
+        end
+      end
+
       private
 
       def rel_or_abs(path, repo_root)

data/lib/textus/role.rb

@@ -1,15 +1,26 @@
 module Textus
   module Role
-    PATTERN = /\A[a-z][a-z0-9_-]*\z/
-    DEFAULT = "human".freeze
-    # The default acting identity for the MCP transport (ADR 0040): an agent
-    # over stdio proposes; it does not inherit the human's authority. CLI
-    # callers keep the `human` DEFAULT.
-    AGENT = "agent".freeze
+    # The three role archetypes, each string sourced exactly once: human curates
+    # canon, agent proposes, automation fetches/builds (explanation/concepts.md).
+    # Reference these constants instead of bare literals (ADR 0044).
+    HUMAN      = "human".freeze
+    AGENT      = "agent".freeze
+    AUTOMATION = "automation".freeze
+
+    # The closed set of legal role names (ADR 0045), built FROM the archetypes
+    # above so it stays the single source of truth — a manifest declaring any
+    # other name is rejected at load, and DEFAULT ∈ NAMES holds structurally.
+    # Capabilities (`can:`) remain freely tunable per role.
+    NAMES = [HUMAN, AGENT, AUTOMATION].freeze
+
+    # Default acting identity (ADR 0040): a *choice* over the vocabulary, not a
+    # new name. CLI callers act as the human; an agent over stdio proposes and
+    # does not inherit the human's authority (it defaults to AGENT per transport).
+    DEFAULT = HUMAN
 
     def self.resolve(root:, flag: nil, env: ENV, default: DEFAULT)
       candidate = flag || env["TEXTUS_ROLE"] || read_file(root) || default
-      raise InvalidRole.new(candidate) unless candidate.match?(PATTERN)
+      raise InvalidRole.new(candidate) unless NAMES.include?(candidate)
 
       candidate
     end

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.39.1"
+  VERSION = "0.40.0"
   PROTOCOL = "textus/3"
 end

data/lib/textus/write/publish.rb

@@ -18,6 +18,7 @@ module Textus
       def call(prefix: nil)
         built  = []
         leaves = []
+        pruned = []
         context = build_context
 
         @manifest.data.entries.each do |mentry|
@@ -27,12 +28,14 @@ module Textus
           next if result.nil?
 
           case result[:kind]
-          when :built  then built << result[:value]
-          when :leaves then leaves.concat(result[:value])
+          when :built then built << result[:value]
+          when :leaves
+            leaves.concat(result[:value])
+            pruned.concat(result[:pruned]) if result[:pruned]
           end
         end
 
-        { "protocol" => Textus::PROTOCOL, "built" => built, "published_leaves" => leaves }
+        { "protocol" => Textus::PROTOCOL, "built" => built, "published_leaves" => leaves, "pruned" => pruned }
       end
 
       private

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.39.1
+  version: 0.40.0
 platform: ruby
 authors:
 - Patrick
@@ -176,6 +176,7 @@ files:
 - lib/textus/doctor/check/illegal_keys.rb
 - lib/textus/doctor/check/intake_registration.rb
 - lib/textus/doctor/check/manifest_files.rb
+- lib/textus/doctor/check/orphaned_publish_targets.rb
 - lib/textus/doctor/check/proposal_targets.rb
 - lib/textus/doctor/check/protocol_version.rb
 - lib/textus/doctor/check/rule_ambiguity.rb
@@ -225,6 +226,7 @@ files:
 - lib/textus/errors.rb
 - lib/textus/etag.rb
 - lib/textus/hooks/builtin.rb
+- lib/textus/hooks/catalog.rb
 - lib/textus/hooks/context.rb
 - lib/textus/hooks/error_log.rb
 - lib/textus/hooks/event_bus.rb