textus 0.42.0 → 0.43.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36d711f8c5947548e8f2431cfded1a514596af239b4eb6e91a3d3d0a6f20c83e
-  data.tar.gz: 33496ad8d0d862655cddbc47c36fd4c3ccf01f7e1b37dea06ee1fc24062be51c
+  metadata.gz: 8c2c92f27b720b90f0dfa268174cf9d9ea775b37f92bb38ed90cd9719d7b2626
+  data.tar.gz: f5018ecfd8d72666d48236d42395e44819766659088bc98b1c69ad4fccf2fce8
 SHA512:
-  metadata.gz: 6b5b84af6db5f692db3b27f3b029348ab80d7bc9e05d2ebf74d32b9fc9b29d497fb275b508725b8437549f75bc69c1de01818ccc2d1eee4dc2af79cfa292e6dc
-  data.tar.gz: 99f9c63b92f629bd37956a79a303fcc081997d81afe96a85d804d806831388f9d6821b66c449299f82c7f27422e97ada2759518be6062061a45acb8db043d7c9
+  metadata.gz: 758b3a9da98edb000100e9b6d1665829d94333f53e38f3a68104d33a4aefd831947e235ecb3048e16b388e0256239dfe6f66708d1253b7bfcbb56360a74350bc
+  data.tar.gz: d72be31709261f1aff37f00a9b213e03d8121758f61e781bfdd1626eb16122d994d64491f4c37be4c851031e8bd122d9df8d8abd682228e2693162d3861c865d

data/CHANGELOG.md

@@ -9,6 +9,24 @@ The **gem version** (`0.x.y`) is distinct from the **protocol version**
 bump is a breaking change that requires a store migration; the gem version
 tracks both additive improvements and breaking protocol bumps independently.
 
+## 0.43.0 — 2026-06-02 — Typed `publish:` block + remove `index_filename` ([ADR 0052](docs/architecture/decisions/0052-typed-publish-block.md), [0053](docs/architecture/decisions/0053-remove-index-filename.md))
+
+No `textus/3` wire-format change. Two breaking (pre-1.0) changes on the publish/enumeration surface: the two top-level publish keys become one typed `publish:` block, and the unused `index_filename:` enumeration feature is removed. Both fail at load with a migration-pointing message.
+
+### Changed
+
+- **BREAKING (pre-1.0): `publish_to:`/`publish_tree:` folded into one typed `publish:` block ([ADR 0052](docs/architecture/decisions/0052-typed-publish-block.md)).** Publishing is now configured by `publish: { to: [...] }` (file fan-out) **xor** `publish: { tree: "dir" }` (subtree mirror), mirroring the ADR 0049 internal sum type at the manifest layer and giving a future third mode a namespace instead of a third top-level key. Surface-only — the `Publish::*` modes, `:file_published` event, and build envelope are unchanged. A manifest using the flat `publish_to:`/`publish_tree:` keys **fails at load** with the replacement (`use publish: { to: [...] }` / `{ tree: "..." }`). This is grouping/extensibility, not a new invariant: a block with both `to:` and `tree:` is still caught by the one exclusivity guard in `Publish.resolve`.
+
+### Removed
+
+- **BREAKING (pre-1.0): the `index_filename:` enumeration feature is removed ([ADR 0053](docs/architecture/decisions/0053-remove-index-filename.md)).** `index_filename:` let a nested entry enumerate *directories* as addressable keys via a fixed index file (e.g. `SKILL.md`). It had zero real usage, its only motivating consumer (`EachDir` per-leaf publish) was removed in 0.42.0, and it could not compose with `publish_tree` (mutually exclusive). A nested entry now always enumerates each file under its tree as a key (key segments derived from the path, extension stripped). A manifest declaring `index_filename:` **fails at load** with a migration message; to mirror a directory of files to a consumer path without enumerating them as keys, use `publish: { tree: "..." }`. Native skill authoring (ADR 0050) is unaffected — it rides `publish_tree`, which never enumerated an index. The shallowest-index-wins claiming logic (ADR 0046 D5) and the `index_filename ⊥ publish_tree` guard go with it.
+
+No `textus/3` wire-format change — repo-local publish behaviour only.
+
+### Fixed
+
+- **`publish_tree` files are now opaque in *every* path, not just the Publisher ([ADR 0047](docs/architecture/decisions/0047-publish-tree-keyless-subtree-mirror.md)).** A keyless subtree mirror carrying non-key-legal filenames (uppercase `SKILL.md`, `README`) tripped `doctor`'s `key.illegal` and red-gated commits, even though publish itself mirrored the files correctly — `doctor`'s `IllegalKeys` and `Resolver#enumerate_nested` still key-walked them, contradicting ADR 0047's "no keys" contract. The resolved publish mode now answers `Publish::Mode#keyless?` (true only for `Tree`); both paths consult it and skip enumerating a keyless mirror's files. A `publish_tree` subtree with uppercase filenames stays `doctor`-green and still mirrors; a non-publish nested entry still flags illegal segments as before.
+
 ## 0.42.0 — 2026-06-02 — Remove `publish_each`: collapse publish to two modes ([ADR 0051](docs/architecture/decisions/0051-remove-publish-each.md))
 
 No `textus/3` wire-format change. **Breaking (pre-1.0):** the `publish_each:` manifest key is removed; a manifest declaring it now fails at load. The publish surface collapses to two modes — `publish_to:` (fixed paths) and `publish_tree:` (whole-subtree mirror) — plus `None`.

data/README.md

@@ -182,7 +182,7 @@ For a worked store — knowledge entries, a staged proposal, schemas, a template
 
 ## What's shipped
 
-- **Per-entry formats & publish.** `format: markdown|json|yaml|text` per entry; `publish_to:`/`publish_tree:` byte-copy derived files (or a whole subtree) to their consumer paths. ([SPEC §5.2–5.3](SPEC.md))
+- **Per-entry formats & publish.** `format: markdown|json|yaml|text` per entry; a typed `publish:` block (`to:` for file fan-out, `tree:` for a whole-subtree mirror) byte-copies derived files to their consumer paths. ([SPEC §5.2–5.3](SPEC.md))
 - **Stable identity.** Auto-minted `uid:` survives writes and `textus key mv`; reorganising never breaks references.
 - **Capability × zone-kind gate.** Writes carry `--as=<role>`; a role may write a zone iff it holds the capability the zone's `kind:` requires (`canon`→`author`, `workspace`→`keep`, `quarantine`→`fetch`, `queue`→`propose`, `derived`→`build`). The wrong role gets `write_forbidden` naming the capability needed and the roles that hold it. ([SPEC §5](SPEC.md))
 - **Agent loop.** `textus boot` orients a fresh session; `textus pulse --since=N` is the per-turn heartbeat (changed entries, stale keys, pending proposals). ([docs/how-to/agents-mcp.md](docs/how-to/agents-mcp.md))
@@ -203,7 +203,7 @@ Derived entries declare `compute: { kind: projection, select: ..., pluck: ..., s
 
 For externally-generated entries, declare `compute: { kind: external, sources: [...] }` — textus tracks the declared sources for staleness; the build automation produces the file.
 
-`publish_to: [path]` byte-copies a single derived file to one or more targets. `publish_tree: "dir"` on a nested entry mirrors its whole stored subtree to one target directory, preserving layout (path-driven — no keys or template variables). Sentinels for every published file live under `.textus/sentinels/`. See SPEC §5.2, §5.3, §5.12.
+Publishing is one typed `publish:` block (ADR 0052). `publish: { to: [path, ...] }` byte-copies a single derived file to one or more targets. `publish: { tree: "dir" }` on a nested entry mirrors its whole stored subtree to one target directory, preserving layout (path-driven — no keys or template variables). Sentinels for every published file live under `.textus/sentinels/`. See SPEC §5.2, §5.3, §5.12.
 
 ## Extension points
 

data/SPEC.md

@@ -24,7 +24,7 @@
   - [5.2 Compute layer (derived entries)](#52-compute-layer-derived-entries)
     - [5.2.1 Projection compute](#521-projection-compute-kind-projection)
     - [5.2.2 External compute](#522-external-compute-kind-external)
-  - [5.3 Publish layer](#53-publish-layer-publish_to)
+  - [5.3 Publish layer](#53-publish-layer-publish)
   - [5.4 Intake](#54-intake-declared-fetched-via-registered-intake-handler)
   - [5.5 Pending / accept workflow](#55-pending--accept-workflow)
   - [5.6 Audit log](#56-audit-log)
@@ -100,7 +100,7 @@ textus is organized as five composable layers. Each layer has a single responsib
 | 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 (the `feeds` zone in the default scaffold; any `quarantine` zone, writable by a role with `fetch`): URLs, files, feeds with declared parsers and TTLs. textus *describes* sources; external automation fetches and pipes 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"`. |
+| 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. |
 
 ## 2. Goals and non-goals
@@ -228,21 +228,11 @@ Zone names are conventional — write authority comes from each zone's declared
 | `yaml`     | `.yaml` or `.yml` required  | optional (escape hatch) | optional (top-level keys) |
 | `text`     | `.txt` or no extension      | required for derived | MUST be null |
 
-For `nested: true`, the recursive glob matches the format's extension (markdown→`**/*.md`, json→`**/*.json`, yaml→`**/*.{yaml,yml}`, text→`**/*.txt`). All files under one nested entry share one format and one schema.
+For `nested: true`, the recursive glob matches the format's extension (markdown→`**/*.md`, json→`**/*.json`, yaml→`**/*.{yaml,yml}`, text→`**/*.txt`). All files under one nested entry share one format and one schema. Each matching file is enumerated as its own key, with the key segments derived from the path relative to the entry (extension stripped). A nested entry that instead mirrors a whole directory of files to a consumer path — without enumerating any of them as keys — uses `publish: { tree: }` (below); its files are opaque payload. (The former `index_filename:` directory-keyed enumeration was removed in 0.43.0 — ADR 0053.)
 
-**Per-entry `index_filename:`.** A nested entry MAY declare `index_filename:` to surface a single fixed basename (e.g. `SKILL.md`) per directory as the row, with the row's key segments derived from the directory path. Sibling files are not enumerated. The basename's extension MUST match the entry's `format:`. This lets entries project spec-mandated filenames whose casing would otherwise be rejected by the key-segment grammar. Example:
+**The `publish:` block (ADR 0052).** Publishing is configured by one typed `publish:` block with exactly one of two sub-keys — `publish: { to: [...] }` (file fan-out, §5.3) **xor** `publish: { tree: "dir" }` (subtree mirror, below). Setting both is an error. The legacy top-level `publish_to:` / `publish_tree:` keys are rejected at load with a migration message.
 
-```yaml
-- key: skills
-  path: skills
-  zone: skills
-  nested: true
-  index_filename: SKILL.md
-```
-
-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). `index_filename:` is a pure *enumeration* feature — it selects which file is the addressable row per directory and is independent of publishing (ADR 0051).
-
-**Subtree mirror (`publish_tree:`).** A nested manifest entry MAY declare `publish_tree:` to mirror its entire stored subtree (`zones/<path>/**`) to a single target directory, preserving relative layout (case and extension preserved). It is **path-driven, not key-driven**: no keys are enumerated, no template variables are interpreted, and the mirrored files are opaque payload (never addressable). The entry's `ignore:` globs (§4, ADR 0042) filter the walk; each mirrored file gets its own sentinel; and on every build the whole target directory is pruned of textus-managed files the current source no longer produces (unmanaged files are never touched). `publish_tree:` is mutually exclusive with `publish_to:`, and incompatible with `index_filename:`. When a `publish_tree:` target directory overlaps a `derived` entry's `publish_to:` (e.g. a derived `SKILL.md` written into the mirrored dir), the `publish_tree:` entry **must** `ignore:` that filename or prune will delete it — `doctor` flags this as `publish.tree_index_overlap`. See ADR 0047.
+**Subtree mirror (`publish: { tree: }`).** A nested manifest entry MAY declare `publish: { tree: "dir" }` to mirror its entire stored subtree (`zones/<path>/**`) to a single target directory, preserving relative layout (case and extension preserved). It is **path-driven, not key-driven**: no keys are enumerated, no template variables are interpreted, and the mirrored files are opaque payload (never addressable). The entry's `ignore:` globs (§4, ADR 0042) filter the walk; each mirrored file gets its own sentinel; and on every build the whole target directory is pruned of textus-managed files the current source no longer produces (unmanaged files are never touched). When a `publish.tree` target directory overlaps a `derived` entry's `publish.to` (e.g. a derived `SKILL.md` written into the mirrored dir), the mirroring entry **must** `ignore:` that filename or prune will delete it — `doctor` flags this as `publish.tree_index_overlap`. See ADR 0047.
 
 ```yaml
 - key: working.skills
@@ -250,7 +240,8 @@ A file at `.textus/zones/skills/ask/SKILL.md` enumerates as `skills.ask`; `.text
   zone: working
   schema: skill
   nested: true
-  publish_tree: "skills"
+  publish:
+    tree: "skills"
   ignore: ["*.tmp", ".DS_Store"]
 ```
 
@@ -444,21 +435,24 @@ generated:
 
 `kind: external` and `kind: projection` are alternatives — exactly one per entry. Templates are not required for `kind: external`: the external automation produces the bytes directly.
 
-### 5.3 Publish layer (`publish_to:`)
+### 5.3 Publish layer (`publish:`)
+
+Publishing is configured by one typed `publish:` block with exactly one sub-key (ADR 0052): `to:` (file fan-out) **xor** `tree:` (subtree mirror). Setting both is an error; the legacy top-level `publish_to:` / `publish_tree:` keys are rejected at load with a migration message.
 
-A derived entry MAY declare `publish_to:` in its frontmatter, listing one or more destination paths relative to the project root:
+A derived entry MAY declare `publish: { to: [...] }`, listing one or more destination paths relative to the project root:
 
 ```yaml
-publish_to:
-  - CLAUDE.md
-  - .ai/instructions.md
+publish:
+  to:
+    - CLAUDE.md
+    - .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/<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, marked as managed, or **byte-identical to the source being published**. An identical destination is *adopted*: its sentinel is written and management proceeds (the copy is a content no-op), so an artifact tree already on disk onboards without a manual delete. An unmanaged destination whose content **differs**, or any unmanaged symlink, is still refused (ADR 0050). Legacy sibling sentinels (`<target>.textus-managed.json`) are still recognised as managed and are migrated to the new location on the next publish.
 
-**Subtree mirror.** A nested entry MAY declare `publish_tree:` instead of `publish_to:` (see §4). On every build, textus walks the entry's full stored subtree (`zones/<path>/**`), applies the entry's `ignore:` filter, and byte-copies each file to the target directory, preserving relative layout — one sentinel per file under `<store_root>/sentinels/`. The mirror is path-driven: no keys are enumerated, no template variables are interpreted, and mirrored files are opaque payload (never addressable). On rebuild, the entire target directory is pruned of textus-managed files the current source no longer produces; unmanaged files are never touched. The build envelope grows a `published_leaves` array — one row per mirrored file, with `key`, `source`, and `target` — alongside the existing `built` array, plus a `pruned` array listing any orphaned managed files removed on this build. `publish_tree:` is mutually exclusive with `publish_to:`, and incompatible with `index_filename:`. Targets that would resolve outside the repo root are refused. When a `publish_tree:` target overlaps a `derived` entry's `publish_to:` (e.g. a derived `SKILL.md` written into the mirrored dir), the `publish_tree:` entry must `ignore:` that filename or prune will delete it — `doctor` flags this as `publish.tree_index_overlap` (ADR 0047).
+**Subtree mirror.** A nested entry MAY declare `publish: { tree: "dir" }` instead of `to:` (see §4). On every build, textus walks the entry's full stored subtree (`zones/<path>/**`), applies the entry's `ignore:` filter, and byte-copies each file to the target directory, preserving relative layout — one sentinel per file under `<store_root>/sentinels/`. The mirror is path-driven: no keys are enumerated, no template variables are interpreted, and mirrored files are opaque payload (never addressable). On rebuild, the entire target directory is pruned of textus-managed files the current source no longer produces; unmanaged files are never touched. The build envelope grows a `published_leaves` array — one row per mirrored 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. When a `publish.tree` target overlaps a `derived` entry's `publish.to` (e.g. a derived `SKILL.md` written into the mirrored dir), the mirroring entry must `ignore:` that filename or prune will delete it — `doctor` flags this as `publish.tree_index_overlap` (ADR 0047).
 
 ### 5.4 Intake (declared, fetched via registered intake handler)
 
@@ -1018,7 +1012,7 @@ Given a manifest entry `derived.catalogs.skills` whose `compute: { kind: project
 Given a derived entry with a `template` clause referencing a `.mustache` file and inputs drawn from other keys, `textus build` produces a body whose contents match the expected rendered output byte-for-byte (after trailing-newline normalization).
 
 **Fixture G — Copy publish:**
-Given a manifest entry with `publish_to: <path>`, a successful `textus build` for that entry leaves a plain file at `<path>` whose contents are byte-identical to the in-store artifact at `.textus/zones/<...>`, accompanied by a sentinel at `.textus/sentinels/<path>.textus-managed.json` recording `source`, `target`, `sha256`, and `mode: "copy"`. Re-running `build` is idempotent.
+Given a manifest entry with `publish: { to: [<path>] }`, a successful `textus build` for that entry leaves a plain file at `<path>` whose contents are byte-identical to the in-store artifact at `.textus/zones/<...>`, accompanied by a sentinel at `.textus/sentinels/<path>.textus-managed.json` recording `source`, `target`, `sha256`, and `mode: "copy"`. Re-running `build` is idempotent.
 
 **Fixture H — Audit log format:**
 Every successful write verb (`put`, `delete`, `build`, `accept`, `schema migrate`) appends exactly one line per affected key to the audit log, in the canonical format defined in §audit (timestamp, actor role, verb, key, etag-before, etag-after). No write produces zero or multiple lines per key.

data/docs/reference/conventions.md

@@ -65,7 +65,8 @@ A derived entry declares a `compute:` block with a `kind:` discriminator. Two ki
     pluck:  [name, relationship, org]
     sort_by: name
   template: people.mustache         # under .textus/templates/
-  publish_to: [docs/people.md]      # optional repo-relative byte-copy targets
+  publish:
+    to: [docs/people.md]            # optional repo-relative byte-copy targets
 ```
 
 **`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`).
@@ -83,7 +84,7 @@ A derived entry declares a `compute:` block with a `kind:` discriminator. Two ki
 
 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.1 and §5.2.2](../../SPEC.md). Transforms (`compute.transform:`) and subtree publishing (`publish_tree:`) 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 subtree publishing (`publish: { tree: }`) are also covered there.
 
 ## Intake and freshness
 

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

@@ -6,12 +6,12 @@ module Textus
           out = []
           manifest.data.entries.each do |entry|
             next unless entry.nested?
+            next if entry.publish_mode.keyless? # publish_tree files are opaque payload, never keys (ADR 0047)
 
             base = File.join(root, "zones", entry.path)
             next unless File.directory?(base)
 
-            index_fn = entry.respond_to?(:index_filename) ? entry.index_filename : nil
-            index_fn ? check_index_paths(entry, index_fn, base, out) : check_all_paths(entry, base, out)
+            check_all_paths(entry, base, out)
           end
           out
         end
@@ -31,24 +31,6 @@ module Textus
           end
         end
 
-        # When the entry uses `index_filename:`, only the parent-directory
-        # segments leading to each index file participate in keys. Sibling
-        # files and unrelated subtrees are not enumerated and must not be
-        # flagged. Each illegal segment is reported once per path. Paths under
-        # an ignored subtree (ADR 0042) are excluded before any segment check.
-        def check_index_paths(entry, index_fn, base, out)
-          Dir.glob(File.join(base, "**", index_fn)).each do |fp|
-            rel = fp.sub(%r{\A#{Regexp.escape(base)}/?}, "")
-            next if entry.ignored?(rel)
-
-            File.dirname(rel).split("/").reject { |s| s.empty? || s == "." }.each do |seg|
-              next if seg.match?(Key::Grammar::SEGMENT)
-
-              out << issue(fp, seg)
-            end
-          end
-        end
-
         def issue(abs_path, stem)
           {
             "code" => "key.illegal",

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

@@ -44,7 +44,6 @@ module Textus
         def inject_boot    = false # rubocop:disable Naming/PredicateMethod
         def events         = {}
         def publish_tree   = nil
-        def index_filename = nil
         def ignore         = []
 
         # Per-entry ignore (ADR 0042). Base entries enumerate no tree, so

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

@@ -6,11 +6,10 @@ module Textus
       # Entry::Publish::* — Nested is just the value (attributes + ignore
       # predicate) those modes read.
       class Nested < Base
-        attr_reader :index_filename, :publish_tree, :ignore
+        attr_reader :publish_tree, :ignore
 
-        def initialize(index_filename: nil, publish_tree: nil, ignore: nil, **rest)
+        def initialize(publish_tree: nil, ignore: nil, **rest)
           super(**rest)
-          @index_filename = index_filename
           @publish_tree = publish_tree
           @ignore = Array(ignore)
         end
@@ -26,8 +25,7 @@ module Textus
 
         def self.from_raw(common, raw)
           new(
-            index_filename: raw["index_filename"],
-            publish_tree: raw["publish_tree"],
+            publish_tree: raw.dig("publish", "tree"), # ADR 0052: typed publish block
             ignore: raw["ignore"],
             **common,
           )

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

@@ -18,7 +18,10 @@ module Textus
             key: key, path: path, zone: zone,
             schema: raw["schema"], owner: raw["owner"],
             format: format,
-            publish_to: raw["publish_to"]
+            # ADR 0052: publish config is one typed block; the internal
+            # publish_to/publish_tree readers (the ADR 0049 modes) are sourced
+            # from it (publish_to <- publish.to, publish_tree <- publish.tree).
+            publish_to: raw.dig("publish", "to")
           }
 
           klass = Entry::REGISTRY[kind] or

data/lib/textus/manifest/entry/publish/mode.rb

@@ -17,6 +17,12 @@ module Textus
           # No shape rules by default — ToPaths/None publish without templating.
           def validate!; end
 
+          # Whether this entry's subtree files are opaque payload that must
+          # never be enumerated as keys. Only Tree (publish_tree, ADR 0047)
+          # overrides to true; doctor's IllegalKeys and the resolver consult
+          # this so they stop key-walking a keyless mirror's files.
+          def keyless? = false
+
           private
 
           # Expand `rel` under repo_root and confirm it stays inside it.

data/lib/textus/manifest/entry/publish/to_paths.rb

@@ -2,8 +2,8 @@ module Textus
   class Manifest
     class Entry
       module Publish
-        # publish_to: copy the entry's one stored file to each fixed repo path.
-        # The default behaviour of any entry that declares `publish_to:`.
+        # publish.to: copy the entry's one stored file to each fixed repo path.
+        # The behaviour of any entry that declares `publish: { to: [...] }`.
         class ToPaths < Mode
           def publish(pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument
             targets = Array(entry.publish_to)

data/lib/textus/manifest/entry/publish/tree.rb

@@ -8,6 +8,9 @@ module Textus
         # (e.g. a SKILL.md written by a separate entry into the same dir)
         # survives the whole-target prune (ADR 0047 D4).
         class Tree < Mode
+          # Mirrored files are opaque payload, never addressable keys (ADR 0047).
+          def keyless? = true
+
           def publish(pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument
             target_rel = entry.publish_tree
             target_dir = repo_abs(pctx, target_rel)
@@ -30,20 +33,13 @@ module Textus
 
           def validate!
             publish_tree = entry.publish_tree
-            raise UsageError.new("entry '#{entry.key}': publish_tree must be a string") unless publish_tree.is_a?(String)
-
-            unless entry.index_filename.nil?
-              raise UsageError.new(
-                "entry '#{entry.key}': index_filename and publish_tree are mutually exclusive — " \
-                "publish_tree mirrors a whole subtree by path and never enumerates an index.",
-              )
-            end
+            raise UsageError.new("entry '#{entry.key}': publish.tree must be a string") unless publish_tree.is_a?(String)
 
             used_vars = publish_tree.scan(Template::VAR_RE).flatten
             return if used_vars.empty?
 
             raise UsageError.new(
-              "entry '#{entry.key}': publish_tree names a single directory and takes no template variable(s) " \
+              "entry '#{entry.key}': publish.tree names a single directory and takes no template variable(s) " \
               "#{used_vars.map { |v| "{#{v}}" }.join(", ")} — it mirrors the whole subtree to one target dir.",
             )
           end

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

@@ -5,26 +5,28 @@ module Textus
       # realized as one resolved sum type. Each directory entry resolves, once,
       # to one Publish::* mode that owns its publish algorithm — no nil-cascade,
       # no pairwise exclusivity guards, one shared subtree mirror. ADR 0051
-      # removed `publish_each` (both leaf modes); the surface is now two modes:
+      # removed `publish_each` (both leaf modes); ADR 0052 folded the two surviving
+      # keys into one `publish:` block (`to:` xor `tree:`). The surface is two modes:
       #
-      #   None      — nothing to publish
-      #   ToPaths   — publish_to: 1 stored file -> N fixed repo paths
-      #   Tree      — publish_tree: whole entry subtree -> 1 dir, no keys
+      #   None      — nothing to publish (no publish: block)
+      #   ToPaths   — publish: { to: [...] }  — 1 stored file -> N fixed repo paths
+      #   Tree      — publish: { tree: "dir" } — whole entry subtree -> 1 dir, no keys
       module Publish
-        # Resolve an entry to its single publish mode. Raises one UsageError if
-        # both publish_to and publish_tree are set — exclusivity is structural
-        # here, not scattered pairwise guards. A removed `publish_each:` key is
-        # rejected loudly with its replacement (ADR 0051).
+        # Resolve an entry to its single publish mode. The publish config is the
+        # ADR 0052 `publish:` block, sourced into entry.publish_to/publish_tree.
+        # Raises one UsageError if both `publish.to` and `publish.tree` are set —
+        # the block groups the two but does not make exclusivity structural, so
+        # this stays the one enforcement point (ADR 0052 D2).
         def self.resolve(entry)
           reject_removed_publish_each(entry)
 
           set = []
-          set << "publish_to"   unless Array(entry.publish_to).empty?
-          set << "publish_tree" unless entry.publish_tree.nil?
+          set << "publish.to"   unless Array(entry.publish_to).empty?
+          set << "publish.tree" unless entry.publish_tree.nil?
 
           if set.length > 1
             raise Textus::UsageError.new(
-              "entry '#{entry.key}': #{set.join(", ")} are mutually exclusive — an entry publishes exactly one way",
+              "entry '#{entry.key}': #{set.join(" and ")} are mutually exclusive — an entry publishes exactly one way",
             )
           end
 
@@ -36,15 +38,15 @@ module Textus
 
           raise Textus::UsageError.new(
             "entry '#{entry.key}': publish_each was removed in 0.42.0 (ADR 0051) — " \
-            "mirror the subtree with publish_tree (and index_filename to keep the index addressable).",
+            "mirror the subtree with `publish: { tree: \"...\" }`.",
           )
         end
         private_class_method :reject_removed_publish_each
 
         def self.mode_for(entry, key)
           case key
-          when "publish_to"   then ToPaths.new(entry)
-          when "publish_tree" then Tree.new(entry)
+          when "publish.to"   then ToPaths.new(entry)
+          when "publish.tree" then Tree.new(entry)
           else None.new(entry)
           end
         end

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

@@ -8,11 +8,13 @@ module Textus
         # the scattered pairwise "not-both" guards of the old PublishEach +
         # PublishTree validators. Misuse on a non-nested entry is still caught
         # here from raw, since the typed attrs stub nil on Base. (publish_each was
-        # removed in 0.42.0 — ADR 0051; Schema rejects it at load.)
+        # removed in 0.42.0 — ADR 0051; the publish_to/publish_tree keys were folded
+        # into the `publish:` block in 0.43.0 — ADR 0052; Schema rejects the retired
+        # flat keys at load.)
         module Publish
           def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
             unless entry.nested?
-              raise UsageError.new("entry '#{entry.key}': publish_tree requires nested: true") if entry.raw["publish_tree"]
+              raise UsageError.new("entry '#{entry.key}': publish.tree requires nested: true") if entry.raw.dig("publish", "tree")
 
               return
             end

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

@@ -6,7 +6,6 @@ module Textus
           Events,
           Publish,
           InjectBoot,
-          IndexFilename,
           Ignore,
           FormatMatrix,
         ].freeze

data/lib/textus/manifest/resolver.rb

@@ -51,13 +51,8 @@ module Textus
         else
           raise UnknownKey.new(key, suggestions: suggestions_for(key)) unless nested_entry?(entry)
 
-          index_fn = entry.index_filename
-          path = if index_fn
-                   File.join(@data.root, "zones", entry.path, *remaining, index_fn)
-                 else
-                   primary_ext = Textus::Entry.for_format(entry.format).extensions.first
-                   File.join(@data.root, "zones", entry.path, *remaining) + primary_ext
-                 end
+          primary_ext = Textus::Entry.for_format(entry.format).extensions.first
+          path = File.join(@data.root, "zones", entry.path, *remaining) + primary_ext
           Resolution.new(entry: entry, path: path, remaining: remaining)
         end
       end
@@ -68,33 +63,22 @@ module Textus
       end
 
       def enumerate_nested(entry)
+        # publish_tree mirrors opaque payload by path — its files are never
+        # enumerated as keys (ADR 0047). Ask the resolved mode, not the path.
+        return [] if entry.publish_mode.keyless?
+
         base = File.join(@data.root, "zones", entry.path)
         return [] unless File.directory?(base)
 
-        entry_index_filename = entry.index_filename
-        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
+        Dir.glob(File.join(base, nested_glob(entry.format)))
+           .filter_map { |path| nested_row_for(entry, base, path) }
       end
 
       def nested_row_for(entry, base, path)
         rel = path.sub(%r{\A#{Regexp.escape(base)}/?}, "")
         return nil if entry.ignored?(rel)
 
-        entry_if = entry.index_filename
-        stripped = entry_if ? File.dirname(rel) : rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "")
+        stripped = rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "")
         segs = stripped.split("/").reject { |s| s.empty? || s == "." }
         return nil if segs.empty?
 

data/lib/textus/manifest/schema.rb

@@ -24,9 +24,12 @@ module Textus
       KIND_REQUIRES_VERB = LANES
       ENTRY_KEYS = %w[
         key path zone kind schema owner nested format
-        compute template publish_to publish_tree
-        intake events inject_boot index_filename ignore tracked
+        compute template publish
+        intake events inject_boot ignore tracked
       ].freeze
+      # ADR 0052: the typed publish block — `publish: { to: [...] }` (file
+      # fan-out) xor `publish: { tree: "dir" }` (subtree mirror).
+      PUBLISH_KEYS = %w[to tree].freeze
       COMPUTE_KEYS = %w[kind select pluck sort_by limit transform command sources].freeze
       INTAKE_KEYS  = %w[handler config].freeze
       RULE_KEYS    = %w[match fetch intake_handler_allowlist guard retention].freeze
@@ -73,25 +76,62 @@ module Textus
       def self.validate_entries!(entries)
         Array(entries).each_with_index do |e, i|
           path = "$.entries[#{i}]"
-          reject_removed_publish_each!(e, path)
+          reject_retired_publish_keys!(e, path)
           walk(e, ENTRY_KEYS, path)
+          validate_publish_block!(e, path)
           walk(e["compute"], COMPUTE_KEYS, "#{path}.compute") if e["compute"].is_a?(Hash)
           walk(e["intake"], INTAKE_KEYS, "#{path}.intake") if e["intake"].is_a?(Hash)
         end
       end
 
-      # publish_each was removed in 0.42.0 (ADR 0051). It is no longer an allowed
-      # entry key, so `walk` would reject it as merely "unknown"; intercept it
-      # first with the migration path so a pre-0.42 manifest gets a useful error.
-      def self.reject_removed_publish_each!(entry, path)
-        return unless entry.is_a?(Hash) && entry.key?("publish_each")
+      # Retired keys are no longer allowed, so `walk` would reject them as merely
+      # "unknown"; intercept first with the migration path so a pre-0.43 manifest
+      # gets a useful error. `publish_each` was removed (ADR 0051); `publish_to`/
+      # `publish_tree` were folded into the `publish:` block (ADR 0052);
+      # `index_filename` was removed (ADR 0053).
+      def self.reject_retired_publish_keys!(entry, path)
+        return unless entry.is_a?(Hash)
+
+        if entry.key?("publish_each")
+          raise BadManifest.new(
+            "publish_each was removed in 0.42.0 (ADR 0051) at '#{path}' — " \
+            "mirror the subtree with `publish: { tree: \"...\" }`.",
+          )
+        end
+
+        if entry.key?("publish_to")
+          raise BadManifest.new(
+            "publish_to was replaced by the publish: block in 0.43.0 (ADR 0052) at '#{path}' — " \
+            "use `publish: { to: [...] }`.",
+          )
+        end
+
+        if entry.key?("publish_tree")
+          raise BadManifest.new(
+            "publish_tree was replaced by the publish: block in 0.43.0 (ADR 0052) at '#{path}' — " \
+            "use `publish: { tree: \"...\" }`.",
+          )
+        end
+
+        return unless entry.key?("index_filename")
 
         raise BadManifest.new(
-          "publish_each was removed in 0.42.0 (ADR 0051) at '#{path}' — " \
-          "mirror the subtree with publish_tree (and index_filename to keep the index addressable).",
+          "index_filename was removed in 0.43.0 (ADR 0053) at '#{path}' — a nested entry now enumerates " \
+          "each file as a key; to mirror a directory of files to a consumer path use `publish: { tree: \"...\" }`.",
         )
       end
 
+      # Shape of the ADR 0052 publish block: a Hash whose only keys are to/tree.
+      # Exclusivity (both set) and per-mode rules stay in Publish.resolve (ADR 0049).
+      def self.validate_publish_block!(entry, path)
+        return unless entry.is_a?(Hash) && entry.key?("publish")
+
+        block = entry["publish"]
+        raise BadManifest.new("publish: must be a mapping with `to:` or `tree:` at '#{path}.publish'") unless block.is_a?(Hash)
+
+        walk(block, PUBLISH_KEYS, "#{path}.publish")
+      end
+
       def self.validate_rules!(rules)
         Array(rules).each_with_index do |r, i|
           path = "$.rules[#{i}]"

data/lib/textus/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.42.0
+  version: 0.43.0
 platform: ruby
 authors:
 - Patrick
@@ -271,7 +271,6 @@ files:
 - lib/textus/manifest/entry/validators/events.rb
 - lib/textus/manifest/entry/validators/format_matrix.rb
 - lib/textus/manifest/entry/validators/ignore.rb
-- lib/textus/manifest/entry/validators/index_filename.rb
 - lib/textus/manifest/entry/validators/inject_boot.rb
 - lib/textus/manifest/entry/validators/publish.rb
 - lib/textus/manifest/policy.rb

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

@@ -1,47 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      module Validators
-        module IndexFilename
-          def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
-            # Use raw to detect misuse on non-nested entries (typed attr stubs nil on Base).
-            index_filename = entry.nested? ? entry.index_filename : entry.raw["index_filename"]
-            return if index_filename.nil?
-
-            check_shape!(entry, index_filename)
-            check_extension!(entry, index_filename)
-          end
-
-          def self.check_shape!(entry, index_filename)
-            raise UsageError.new("entry '#{entry.key}': index_filename requires nested: true") unless entry.nested?
-
-            unless index_filename.is_a?(String) && !index_filename.empty?
-              raise UsageError.new("entry '#{entry.key}': index_filename must be a non-empty string")
-            end
-
-            return unless index_filename.include?("/") || File.basename(index_filename) != index_filename
-
-            raise UsageError.new("entry '#{entry.key}': index_filename must be a bare basename (no slashes)")
-          end
-
-          def self.check_extension!(entry, index_filename)
-            ext = File.extname(index_filename)
-            inferred = Textus::Entry.infer_from_extension(ext)
-
-            if inferred.nil?
-              raise UsageError.new(
-                "entry '#{entry.key}': index_filename #{index_filename.inspect} has unknown extension #{ext.inspect}",
-              )
-            end
-            return if inferred == entry.format
-
-            raise UsageError.new(
-              "entry '#{entry.key}': index_filename extension #{ext.inspect} implies format #{inferred.inspect}, " \
-              "but entry format is #{entry.format.inspect}",
-            )
-          end
-        end
-      end
-    end
-  end
-end