textus 0.45.1 → 0.46.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfb215839c07335a72f604bbcb830d6027a118f500be30243a592cc9c5b07cf0
-  data.tar.gz: dd0103470acbdfb747077bc6d0fafbc08700edfe5a24d09416723d47517871df
+  metadata.gz: cd3d64e647d112827056119d45576eda3b7f6ba95446f7a08522d674fb496d2c
+  data.tar.gz: b8c7c4d86eccd1469bdd024732dc0321fb64d837f59451efe1280fd7ae8d96e2
 SHA512:
-  metadata.gz: 310065adbf501efcd2b793b896770a9cc7e5a38e41c23852c12b18dfca5cc93cea7af1545bac5e306a667aeac959995c9cf08468a3d86869facec42d11c1501f
-  data.tar.gz: 938e0ed014c543d2cba7190ab6de0440a36670268b4207af19444934fb28560cda382452c0cb1db26e4c31bfe78b89031c52fbdb0196fc7d67eb360013d58d5f
+  metadata.gz: 10096cbffbd633d18a915744ddc4e70b7324ad955525a76fc9fb4b95b32ab8b0781d566e10d1fc6695dd5a795b4721926859030e4c86e661bdef1728304b62aa
+  data.tar.gz: d393eee10185c057a7fe727dbb9abb572761e12bcec4b5253cda9a5367d5cd3684850e87432079cd71296f2ff917bd4e1a3e1be5b6484cc7be5ff3c33b4611a0

data/CHANGELOG.md

@@ -9,6 +9,19 @@ 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.46.0 — 2026-06-03 — Container is the single source of truth
+
+No `textus/3` wire-format change. Internal refactor of the composition root. The 7-field capability set (`manifest, file_store, schemas, root, audit_log, events, rpc`) was previously spelled out four times — `Container`'s `Data.define`, `Store`'s ivar assignments, `Store`'s `attr_reader`s, and `Container.from_store`. It now lives in exactly one place.
+
+### Changed
+
+- **`Store` builds its `Container` once and derives its readers from it.** `Store#initialize` constructs the `Container` directly (`build_container`); the public accessors (`store.manifest`, `store.root`, …) are generated from `Container.members`, so adding a capability to the `Data.define` auto-exposes it on `Store`. Hook wiring is extracted into `bootstrap_hooks`.
+- **`Store.discover` decomposed.** The upward directory walk is extracted into `ascend_for_store`, and the duplicated `.textus`/`manifest.yaml` existence check into a shared `store_dir?` predicate.
+
+### Breaking (pre-1.0)
+
+- **`Container.from_store` is removed.** It built a fresh `Container` by copying the seven accessors off a `Store`. Use `store.container` instead (built once, memoized). Specs that swapped the event bus post-construction via `store.instance_variable_set(:@events, …)` now inject explicitly through the immutable `Container`'s `#with` (e.g. `container.with(events: probe)`). Retires the `from_store` idiom described in [ADR 0016](docs/architecture/decisions/0016-application-ports-value.md) and [ADR 0020](docs/architecture/decisions/0020-capability-records.md).
+
 ## 0.45.1 — 2026-06-03 — Single-path lifecycle: kill the last dual-paths ([ADR 0069](docs/architecture/decisions/0069-single-path-lifecycle.md))
 
 No `textus/3` wire-format change. Finishes the 0.45.0 lifecycle (ADRs 0066–0068): the request path was single-path in shape but still carried four residual dual-paths. This removes all four so the lifecycle — `normalize → bind (always validate) → dispatch (+around) → view (self-shaping)` — is single-path in fact on every surface. Three breaking (pre-1.0) changes, all accepted.

data/README.md

@@ -72,6 +72,8 @@ TRANSIENT     │  feeds                   │  proposals  (queue)           │
                 raw material ──── propose ────► a human accept lifts it to canon
 ```
 
+*(The fifth lane, `artifacts`, isn't on this grid — it's a derived **output**, computed from the lanes rather than an input climbing toward trust.)*
+
 Without coordination, they overwrite each other and nothing remembers why. textus gives each actor a **lane** — called a **zone** in the manifest and CLI, the term used everywhere technical from here on — routes everything they can't write directly through a **proposals queue**, and writes every successful change to an **append-only audit log**. The lanes are enforced at the protocol level, not by convention.
 
 ```
@@ -91,9 +93,16 @@ That's the load-bearing claim: **coordination is a protocol invariant, not a lib
 ```sh
 gem install textus
 textus init                          # creates .textus/ with zones + schemas
-# agent proposes a change to proposals/
-printf '%s' '{"_meta":{"name":"oncall","proposal":{"target_key":"knowledge.notes.oncall","action":"put"}},"body":"Patrick on call.\n"}' \
-  | textus put proposals.notes.oncall --as=agent --stdin
+
+# an agent proposes a change — it targets a knowledge entry, but lands in proposals/
+textus propose notes.oncall --as=agent --stdin <<'JSON'
+{
+  "_meta": { "name": "oncall",
+             "proposal": { "target_key": "knowledge.notes.oncall", "action": "put" } },
+  "body": "Patrick on call.\n"
+}
+JSON
+
 # you accept it — textus promotes to knowledge/ and audits the move
 textus accept proposals.notes.oncall --as=human
 ```
@@ -130,7 +139,7 @@ bundle exec exe/textus --help
 
 ## What `textus init` gives you
 
-You get `.textus/` with all five zone directories, baseline schemas, an empty audit log, and a starter manifest. Roles declare capabilities; each zone declares a `kind:`, and write authority is derived from the role's capabilities crossed with the zone's kind:
+You get `.textus/` with all five zone directories, baseline schemas, a starter manifest, and a gitignored `.run/` for disposable runtime state (the audit log, per-role cursors, fetch/build locks). Roles declare capabilities; each zone declares a `kind:`, and write authority is derived from the role's capabilities crossed with the zone's kind:
 
 ```yaml
 roles:
@@ -148,18 +157,22 @@ zones:
 
 ```
 .textus/
-  manifest.yaml       # role capabilities + zone kinds + key-to-path mapping
-  audit.log           # append-only NDJSON, every write
-  schemas/            # YAML field shapes per entry family
-  templates/          # mustache templates for derived entries
-  hooks/              # one .rb per hook
-  sentinels/          # publish bookkeeping
-  zones/
-    knowledge/        # author — identity (knowledge.identity.*), voice, decisions, notes
-    notebook/         # keep — agent's own durable lane (agents keep theirs)
-    feeds/            # fetch — declared external inputs (actions)
-    proposals/        # propose (agent + human) — proposals awaiting accept
-    artifacts/        # build — computed outputs
+  manifest.yaml          # role capabilities + zone kinds + key-to-path mapping
+  schemas/               # YAML field shapes per entry family
+  templates/             # mustache templates for derived entries
+  hooks/                 # one .rb per hook
+  .gitignore             # generated — ignores .run/ and any tracked:false entries
+  zones/                 # one dir per zone; kinds + capabilities are in the manifest above
+    knowledge/           # e.g. identity (knowledge.identity.*), voice, decisions, notes
+    notebook/
+    feeds/
+    proposals/
+    artifacts/
+  .run/                  # disposable runtime state — gitignored, safe to delete (ADR 0038)
+    audit/audit.log      # append-only NDJSON event ledger, every write (rotates at ~50 MB)
+    state/cursor.<role>  # per-role pulse cursor — where `pulse --since` resumes
+    locks/  build.lock   # per-key fetch locks + the build mutex
+    sentinels/           # publish bookkeeping (target sha) — regenerated on build (ADR 0070)
 ```
 
 Manifest `path:` fields are relative to `.textus/zones/`. So `knowledge.notes.org.jane` lives at `.textus/zones/knowledge/notes/org/jane.md`.
@@ -176,7 +189,7 @@ textus rule list                     # show every rule block
 textus audit --limit=20              # query the audit log
 ```
 
-(All verbs return JSON envelopes by default; pass `--output=json` explicitly if you prefer.)
+(All verbs return JSON envelopes; `--output=json` is the default and the only format in v1.)
 
 For a worked store — knowledge entries, a staged proposal, schemas, a template, and a build that publishes `CLAUDE.md` / `AGENTS.md` — see [`examples/project/`](examples/project/).
 
@@ -190,7 +203,7 @@ For a worked store — knowledge entries, a staged proposal, schemas, a template
 
 ## CLI and zones
 
-All verbs accept `--output=json` and return the envelope defined in [SPEC §8](SPEC.md). Write verbs require `--as=<role>` (role resolution: `--as` → `TEXTUS_ROLE` env → `.textus/role` file → default `human`). Default roles: `human`, `agent`, `automation` (rename or add your own in the manifest's `roles:` block).
+Every command operates on one store, located in this order: `--root <path>` flag → **`TEXTUS_ROOT`** env → walk up from the working directory for a `.textus/` ([SPEC §3.1](SPEC.md)). Write verbs require `--as=<role>`, resolved as: `--as` flag → **`TEXTUS_ROLE`** env → `.textus/role` file → default `human` ([SPEC §5.1](SPEC.md)). Default roles: `human`, `agent`, `automation` (rename or add your own in the manifest's `roles:` block). All verbs accept `--output=json` and return the envelope defined in [SPEC §8](SPEC.md).
 
 - Full verb table — read, write, health, scaffolding — is in [SPEC §9](SPEC.md).
 - Zone semantics and the capability × zone-kind mapping live in [SPEC §5](SPEC.md), with the reference in [`docs/reference/zones.md`](docs/reference/zones.md).
@@ -203,17 +216,31 @@ 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.
 
-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.
+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/.run/sentinels/` (git-ignored runtime state, regenerated on build — ADR 0070). See SPEC §5.2, §5.3, §5.12.
 
 ## Extension points
 
-textus exposes a hook DSL. Drop `.rb` files into `.textus/hooks/` (subdirectories are fine; files load alphabetically by full path). Events:
+textus exposes a hook DSL. Drop `.rb` files into `.textus/hooks/` (subdirectories are fine; files load alphabetically by full path). There are two kinds:
+
+**RPC hooks** — one handler, the framework uses what you return:
+
+| Event | Fires when | You return |
+|---|---|---|
+| `:resolve_intake` | a fetch needs bytes | `{_meta:, body:}` |
+| `:transform_rows` | a projection builds | the reshaped rows |
+| `:validate` | `textus doctor` runs | doctor issues (or none) |
+
+**Pub-sub hooks** — 0..N handlers, fire-and-react (no return value):
 
-- `:resolve_intake` — bring bytes in from elsewhere (returns `{_meta:, body:}`)
-- `:transform_rows` — transform rows during projection (returns rows)
-- `:validate` — custom doctor check (returns issues)
-- `:entry_put`, `:entry_deleted`, `:entry_fetched`, `:build_completed`, `:proposal_accepted`, `:file_published`, `:entry_renamed`, `:proposal_rejected`, `:store_loaded` — react to lifecycle events
-- `:fetch_started`, `:fetch_failed`, `:fetch_backgrounded` — background-fetch lifecycle
+| Event(s) | Fires when |
+|---|---|
+| `:entry_put` · `:entry_deleted` · `:entry_renamed` | a write lands |
+| `:entry_fetched` | a fetch-driven write lands |
+| `:build_completed` | a derived entry materializes |
+| `:file_published` | a derived file is copied to its target |
+| `:proposal_accepted` · `:proposal_rejected` | a proposal is resolved |
+| `:fetch_started` · `:fetch_failed` · `:fetch_backgrounded` | background-fetch lifecycle |
+| `:store_loaded` | the store finishes loading |
 
 ```ruby
 # Inside .textus/hooks/local_file.rb
@@ -273,4 +300,4 @@ Lefthook hooks (`brew bundle install` then `lefthook install`) run rubocop on `p
 
 ## License
 
-[MIT](LICENSE).
+[MIT](LICENSE)

data/SPEC.md

@@ -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/.run/sentinels/<target-rel-path>.textus-managed.json` (git-ignored runtime state) 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
@@ -135,7 +135,7 @@ The root is `.textus/` at the project working directory. A typical tree:
   schemas/               # internal: YAML schema files
   templates/             # internal: Mustache templates referenced by derived entries
   hooks/                 # internal: one Ruby file per hook
-  sentinels/             # internal: bookkeeping for byte-copied publish targets (see §5.3)
+  .run/sentinels/        # runtime (git-ignored): byte-copied publish bookkeeping, regenerated on build (see §5.3)
   zones/                 # ALL user content lives here
     knowledge/           # zone: knowledge (kind: canon — author-holders write; knowledge.identity.* is the identity convention)
     notebook/            # zone: notebook (kind: workspace — keep-holders write; agent's own durable lane)
@@ -144,7 +144,7 @@ The root is `.textus/` at the project working directory. A typical tree:
     artifacts/           # zone: artifacts (kind: derived — build-holders write)
 ```
 
-Textus internals (`manifest.yaml`, `audit.log`, `schemas/`, `templates/`, `hooks/`, `sentinels/`) live directly under `.textus/`. **All user content lives under `.textus/zones/`.** Manifest `path:` fields are relative to `.textus/zones/` — they do **not** include the `zones/` prefix. Implementations MUST prepend `zones/` to every `path:` when resolving a key to a filesystem location.
+Textus internals (`manifest.yaml`, `schemas/`, `templates/`, `hooks/`) live directly under `.textus/`; disposable runtime state (the audit log, publish `sentinels/`, fetch/build locks, pulse cursors) lives under `.textus/.run/` (git-ignored, ADR 0038/0070). **All user content lives under `.textus/zones/`.** Manifest `path:` fields are relative to `.textus/zones/` — they do **not** include the `zones/` prefix. Implementations MUST prepend `zones/` to every `path:` when resolving a key to a filesystem location.
 
 Zone directories under `zones/` are conventional; their write semantics are derived from the zone's declared `kind:` (and the capabilities roles hold), not the directory name.
 
@@ -450,9 +450,9 @@ publish:
 
 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.
+A sentinel is written for each published file at `<store_root>/.run/sentinels/<target-relative-to-repo>.textus-managed.json` (git-ignored runtime state — ADR 0070), recording `source`, `target`, the target's sha256, and `mode: "copy"`. Sentinels live under the store's runtime tree rather than beside the consumer file so target directories stay clean, and are regenerated by the next build (via content-identical adoption) rather than committed. 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: "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).
+**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>/.run/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)
 
@@ -735,10 +735,10 @@ An entry's `format:` selects a storage strategy. All strategies expose the same
 **`_meta` convention.** Derived structured entries (json, yaml) embed a `_meta` hash as the first top-level key. Builder-injected keys appear in a fixed order for etag stability:
 
 ```
-generated_at, from, template, transform
+from, template, transform
 ```
 
-Keys with `nil` values are omitted. User-shaped content (or the reducer's hash) follows `_meta`. The etag (§10) is the sha256 of the on-disk bytes regardless of format; key ordering MUST therefore be deterministic, which Ruby's `Hash` and `JSON.generate` / `YAML.dump` honor via insertion order.
+Keys with `nil` values are omitted. The builder injects only **deterministic** provenance: it does **not** stamp a `generated_at` build timestamp into the artifact (ADR 0070). A built artifact is content-addressed — rebuilding unchanged sources reproduces it byte-for-byte, so a rebuild is a no-op and a `git` revert never drifts. (The `generated.at` of §5.2 is a separate convention written by *external* build tools, not by textus's own builder.) User-shaped content (or the reducer's hash) follows `_meta`. The etag (§10) is the sha256 of the on-disk bytes regardless of format; key ordering MUST therefore be deterministic, which Ruby's `Hash` and `JSON.generate` / `YAML.dump` honor via insertion order.
 
 ## 6. Schemas
 
@@ -899,7 +899,7 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 {
   "agent_quickstart": {
     "read_verbs":     ["get", "list", "pulse", "schema_show", "boot", "rule_explain", "where", "deps", "rdeps"],
-    "write_verbs":    ["delete", "fetch", "fetch_all", "mv", "propose", "put"],
+    "write_verbs":    ["accept", "delete", "fetch", "fetch_all", "mv", "propose", "put", "reject"],
     "writable_zones": ["proposals"],
     "propose_zone":   "proposals",
     "latest_seq":     1842
@@ -909,7 +909,7 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 
 `read_verbs` is derived from the MCP verb catalog — the verbs the agent can actually call over its transport — so it lists the read/discovery verbs (`schema_show` for an entry's field shape, `rule_explain` for its freshness/guard policy, and the graph reads `where`/`deps`/`rdeps`, ADR 0060) and never the CLI-only `audit`/`freshness`/`doctor` (ADR 0056). An agent learns an entry's `_meta` shape by calling the `schema_show` verb before a `put`/`propose`, not by shelling out to a CLI. The graph reads `deps`/`rdeps` return a structured `{key, deps}`/`{key, rdeps}` envelope on every surface (CLI, Ruby, MCP) — a hash, not a bare array, consistent with the other structured read responses such as `where` (ADR 0060 amendment).
 
-The agent's MCP write surface includes the single-key `delete` and `mv` tools alongside their bulk `key_delete_prefix`/`key_mv_prefix` cousins (ADR 0060 amendment); safety scales with blast radius — the bulk `*_prefix` ops default to a dry-run Plan, single-key `delete` executes under an optional `if_etag`, and single-key `mv` applies immediately but exposes an optional `dry_run`.
+The agent's MCP write surface includes the single-key `delete` and `mv` tools alongside their bulk `key_delete_prefix`/`key_mv_prefix` cousins (ADR 0060 amendment). All of these apply by default; `dry_run: true` is a uniform opt-in preview that returns a Plan without mutating (ADR 0071 — verbs are actions, dry-run is opt-in on every surface). Single-key `delete` additionally accepts an optional `if_etag` optimistic-concurrency check. The blast-radius reads (`where`/`deps`/`rdeps`) remain on MCP so an agent can look before it leaps. The promotion verbs `accept` and `reject` are also on MCP (ADR 0072): they are gated by the `author_held` capability floor, not by transport absence — a default-`agent` connection is refused, while a connection launched as a role holding `author` (`--as`/`TEXTUS_ROLE`/`.textus/role`, resolved once at launch per ADR 0040) can promote, closing the propose→accept loop over one transport.
 
 `latest_seq` is the current high-water mark of the audit log; agents should use it as the starting cursor for `pulse`.
 
@@ -1010,13 +1010,13 @@ Given the `person` schema and a `put` whose frontmatter omits `relationship`, th
 Given a manifest entry `intake.notes` matched by a `rules: [{ match: intake.notes, fetch: { ttl: 1h } }]` block and an envelope on disk whose `_meta.last_fetched_at` is older than `now - ttl`, `textus freshness --output=json` includes a row for `intake.notes` with `status: "stale"`. Calling `textus freshness` does NOT trigger a fetch.
 
 **Fixture E — Projection build:**
-Given a manifest entry `derived.catalogs.skills` whose `compute: { kind: projection }` clause selects fields from `working.projects` entries, `textus build derived.catalogs.skills` materializes the derived entry on disk with frontmatter and body matching the projected shape, and updates `generated.at` to the build timestamp.
+Given a manifest entry `derived.catalogs.skills` whose `compute: { kind: projection }` clause selects fields from `working.projects` entries, `textus build derived.catalogs.skills` materializes the derived entry on disk with frontmatter and body matching the projected shape. The output is content-addressed (no `generated_at` timestamp, ADR 0070), so rebuilding with unchanged sources reproduces it byte-for-byte and writes nothing.
 
 **Fixture F — Mustache render:**
 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/.run/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/architecture/README.md

@@ -245,31 +245,12 @@ The agent loop (cadence guide in [`agents-mcp.md`](../how-to/agents-mcp.md)):
 
 1. **Session start:** `boot()` → contract envelope (zones, entries, schemas, write_flows, agent_quickstart with `latest_seq`).
 2. **Per turn:** `pulse(since=cursor)` → `{cursor, changed, stale, pending_review, doctor}`.
-3. **On demand:** `get`, `put`, `propose`, `fetch`, `schema`, `rules`.
+3. **On demand:** `get`, `put`, `propose`, `fetch`, `schema_show`, `rule_explain`.
 
 Manifest drift surfaces as `ContractDrift` (manifest_etag mismatch); audit cursor falls off the keep window as `CursorExpired`. Both signal "call `boot` again."
 
 ## Hooks event catalog
 
-`Hooks::Signature` is the single home of callable keyword-introspection — both `EventBus` (pub-sub dispatch) and `RpcRegistry` (RPC dispatch) delegate to it for `accepts_keyrest?`, `declared_keys`, `missing`, and `filter` rather than each maintaining a hand-rolled copy (ADR 0027).
-
-RPC (single handler, declares `caps:`):
-- `resolve_intake(caps:, config:, args:)` — intake fetch handler.
-- `transform_rows(caps:, rows:, config:)` — row transform for intakes.
-- `validate(caps:)` — custom doctor validator.
-
-Pub-sub (0..N handlers, declare `ctx:`):
-- `entry_put(ctx:, key:, envelope:)`
-- `entry_deleted(ctx:, key:)`
-- `entry_fetched(ctx:, key:, envelope:, change:)`
-- `entry_renamed(ctx:, key:, from_key:, to_key:, envelope:)`
-- `build_completed(ctx:, key:, envelope:, sources:)`
-- `proposal_accepted(ctx:, key:, target_key:)`
-- `proposal_rejected(ctx:, key:, target_key:)`
-- `file_published(ctx:, key:, envelope:, source:, target:)`
-- `store_loaded(ctx:)`
-- `fetch_started(ctx:, key:, mode:)`
-- `fetch_failed(ctx:, key:, error_class:, error_message:)`
-- `fetch_backgrounded(ctx:, key:, started_at:, budget_ms:)`
-
-Authoritative source: `lib/textus/hooks/catalog.rb` (`Catalog::RPC` and `Catalog::PUBSUB`).
+`Hooks::Signature` is the single home of callable keyword-introspection — both `EventBus` (pub-sub dispatch) and `RpcRegistry` (RPC dispatch) delegate to it for `accepts_keyrest?`, `declared_keys`, `missing`, and `filter` rather than each maintaining a hand-rolled copy (ADR 0027). RPC handlers declare `caps:` (single handler); pub-sub handlers declare `ctx:` (0..N handlers).
+
+The event names, payloads, and per-verb firing order are documented once in [`reference/events.md`](../reference/events.md) (the friendly SSoT); the authoritative source is `lib/textus/hooks/catalog.rb` (`Catalog::RPC` and `Catalog::PUBSUB`).

data/lib/textus/boot.rb

@@ -95,6 +95,7 @@ module Textus
       { "name" => "doctor",   "summary" => "health-check the store (missing schemas, illegal keys, sentinel drift, etc.)" },
       { "name" => "hook",     "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
       { "name" => "pulse" },
+      { "name" => "capabilities" },
     ].freeze
 
     # Build the CLI verb catalog by deriving each summary from the corresponding

data/lib/textus/builder/pipeline.rb

@@ -5,8 +5,12 @@ module Textus
   module Builder
     module InjectMeta
       # Returns a new hash with _meta as the first key, per SPEC §6 ordering.
+      # Carries only deterministic provenance (`from`/`reduce`/`template`) — the
+      # volatile `generated_at` is deliberately NOT stamped, so the built
+      # artifact is content-addressed and a rebuild is a byte-for-byte no-op
+      # (ADR 0070). Build time lives out of the tracked artifact.
       def self.call(content_hash, mentry)
-        meta = { "generated_at" => Time.now.utc.iso8601 }
+        meta = {}
         if mentry.is_a?(Textus::Manifest::Entry::Derived)
           src = mentry.source
           if src.is_a?(Textus::Manifest::Entry::Derived::Projection)
@@ -23,35 +27,6 @@ module Textus
       end
     end
 
-    # Replaces the freshly-stamped timestamp inside `new_bytes` with the
-    # timestamp pulled from `old_bytes` (same format). Returns the rewritten
-    # bytes, or nil if either side lacks a parseable timestamp.
-    module IdempotentWrite
-      def self.rewrite_with_prior_timestamp(new_bytes:, old_bytes:, format:)
-        prior = extract_timestamp(old_bytes, format)
-        fresh = extract_timestamp(new_bytes, format)
-        return nil unless prior && fresh
-        return new_bytes if prior == fresh
-
-        new_bytes.sub(fresh, prior)
-      end
-
-      def self.extract_timestamp(bytes, format)
-        case format
-        when "markdown"
-          parsed = Entry.for_format("markdown").parse(bytes)
-          parsed.dig("_meta", "generated", "at")
-        when "json", "yaml"
-          parsed = Entry.for_format(format).parse(bytes)
-          parsed.dig("_meta", "generated_at")
-        else # rubocop:disable Style/EmptyElse
-          nil
-        end
-      rescue Textus::BadFrontmatter
-        nil
-      end
-    end
-
     module Pipeline
       Deps = Data.define(
         :manifest, :reader, :lister, :rpc, :template_loader, :transform_context, :inject_boot
@@ -95,18 +70,12 @@ module Textus
         target_path
       end
 
-      def self.write_if_changed(target_path, bytes, format)
-        if File.exist?(target_path)
-          old_bytes = File.binread(target_path)
-          if format == "text"
-            return if old_bytes == bytes
-          else
-            rewritten = IdempotentWrite.rewrite_with_prior_timestamp(
-              new_bytes: bytes, old_bytes: old_bytes, format: format,
-            )
-            return if rewritten && rewritten == old_bytes
-          end
-        end
+      # Built artifacts are content-addressed (no volatile timestamp, ADR 0070),
+      # so identity is plain byte-equality: skip the write when nothing changed.
+      # `format` is retained for signature stability across renderers.
+      def self.write_if_changed(target_path, bytes, _format)
+        return if File.exist?(target_path) && File.binread(target_path) == bytes
+
         File.binwrite(target_path, bytes)
       end
     end

data/lib/textus/builder/renderer/markdown.rb

@@ -1,5 +1,3 @@
-require "time"
-
 module Textus
   module Builder
     class Renderer
@@ -14,12 +12,10 @@ module Textus
                  else
                    []
                  end
-          frontmatter = {
-            "generated" => {
-              "at" => Time.now.utc.iso8601,
-              "from" => from,
-            },
-          }
+          # Deterministic frontmatter only — `from` (the source keys), never a
+          # volatile `generated.at` (ADR 0070): the artifact is content-addressed
+          # so a rebuild is a byte-for-byte no-op and a revert never drifts.
+          frontmatter = { "generated" => { "from" => from } }
           Entry.for_format("markdown").serialize(meta: frontmatter, body: body)
         end
       end

data/lib/textus/cli.rb

@@ -33,13 +33,21 @@ module Textus
     end
 
     def run(argv)
+      # `--root` is a global, position-agnostic option: pull it out of argv
+      # wherever it appears so it works uniformly before OR after any verb or
+      # group (e.g. both `textus --root=X hook list` and
+      # `textus hook list --root=X`). Without this, `order!` below only sees
+      # options before the first verb token, so a trailing `--root` reached the
+      # verb's own parser and raised InvalidOption (#161 F5). TEXTUS_ROOT already
+      # works everywhere via Store.discover, so this brings the flag to parity.
+      @root_arg = extract_root!(argv)
+
       # Define --version/--help ourselves so OptionParser doesn't intercept them
       # with its built-in handlers (which print "version unknown" and a bare usage
       # line, then exit before we ever reach the verb dispatch below).
       show_version = false
       show_help = false
       OptionParser.new do |o|
-        o.on("--root=PATH") { |v| @root_arg = v }
         o.on("--version", "-v") { show_version = true }
         o.on("--help", "-h") { show_help = true }
       end.order!(argv)
@@ -58,6 +66,26 @@ module Textus
 
     private
 
+    # Remove the first `--root=PATH` or `--root PATH` token from argv (anywhere)
+    # and return its value, or nil if absent. Mutates argv in place.
+    def extract_root!(argv)
+      i = argv.index { |a| a == "--root" || a.start_with?("--root=") }
+      return nil unless i
+
+      tok = argv[i]
+      if tok.start_with?("--root=")
+        argv.delete_at(i)
+        tok.delete_prefix("--root=")
+      else
+        val = argv[i + 1]
+        raise UsageError.new("--root requires a PATH") if val.nil? || val.start_with?("-")
+
+        argv.delete_at(i + 1)
+        argv.delete_at(i)
+        val
+      end
+    end
+
     def coerce_exit_code(value)
       case value
       when Integer then value

data/lib/textus/container.rb

@@ -1,22 +1,10 @@
 module Textus
   # Single capability record handed to every use case. Replaces the
-  # ReadCaps/WriteCaps/HookCaps trio from 0.26.x. Built once per Store.
+  # ReadCaps/WriteCaps/HookCaps trio from 0.26.x. Built once per Store
+  # (see Store#initialize); Store delegates its readers to this record,
+  # so this `Data.define` is the single source of truth for the field set.
   Container = Data.define(
     :manifest, :file_store, :schemas, :root,
     :audit_log, :events, :rpc
   )
-
-  class Container
-    def self.from_store(store)
-      new(
-        manifest: store.manifest,
-        file_store: store.file_store,
-        schemas: store.schemas,
-        root: store.root,
-        audit_log: store.audit_log,
-        events: store.events,
-        rpc: store.rpc,
-      )
-    end
-  end
 end

data/lib/textus/dispatcher.rb

@@ -36,6 +36,7 @@ module Textus
       doctor: Textus::Read::Doctor,
       boot: Textus::Read::Boot,
       retainable: Textus::Read::Retainable,
+      capabilities: Textus::Read::Capabilities,
 
       # Maintenance
       migrate: Textus::Maintenance::Migrate,

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

@@ -8,7 +8,7 @@ module Textus
       # that drift without making `build` scan globally.
       class OrphanedPublishTargets < Check
         def call
-          sdir = File.join(root, Textus::Ports::SentinelStore::DIR)
+          sdir = Textus::Layout.sentinels(root)
           return [] unless File.directory?(sdir)
 
           repo_root = File.dirname(root)

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

@@ -5,7 +5,7 @@ module Textus
         def call
           store      = Textus::Ports::SentinelStore.new
           file_stat  = Textus::Ports::Storage::FileStat.new
-          dir        = File.join(root, "sentinels")
+          dir        = Textus::Layout.sentinels(root)
           return [] unless file_stat.directory?(dir)
 
           repo_root = File.dirname(root)

data/lib/textus/domain/policy/predicates/fresh_within.rb

@@ -35,13 +35,14 @@ module Textus
           private
 
           # Domain-pure: reads the stored write timestamp from the envelope's
-          # freshness (checked_at) or meta (last_fetched_at/generated_at) and
-          # parses the stored ISO-8601 string. Parsing a stored string is not
-          # I/O (allowed in domain, ADR 0024).
+          # freshness (checked_at) or meta (last_fetched_at) and parses the
+          # stored ISO-8601 string. Parsing a stored string is not I/O (allowed
+          # in domain, ADR 0024). `generated_at` is intentionally NOT consulted:
+          # build-generation time is no longer carried in the artifact (ADR
+          # 0070), and fetch-freshness is a fetch concept, not a build one.
           def written_at(envelope)
             raw = envelope.freshness&.checked_at ||
-                  envelope.meta&.dig("last_fetched_at") ||
-                  envelope.meta&.dig("generated_at")
+                  envelope.meta&.dig("last_fetched_at")
             return raw if raw.is_a?(Time)
             return nil if raw.nil?
 

data/lib/textus/envelope/io/writer.rb

@@ -82,6 +82,7 @@ module Textus
           raise EtagMismatch.new(key, if_etag, etag_before) if if_etag && if_etag != etag_before
 
           @file_store.delete(path)
+          prune_empty_parents(path)
           @audit_log.append(
             role: @call.role, verb: "delete", key: key,
             etag_before: etag_before, etag_after: nil,
@@ -99,6 +100,7 @@ module Textus
 
           FileUtils.mkdir_p(File.dirname(to_path))
           FileUtils.mv(from_path, to_path)
+          prune_empty_parents(from_path)
           basename = to_key.split(".").last
           Entry.for_format(new_mentry.format).rewrite_name(to_path, basename)
           etag_after = Etag.for_file(to_path)
@@ -129,6 +131,38 @@ module Textus
 
         private
 
+        # After a file leaves a directory (delete or move-source), remove any
+        # now-empty parent dirs so bulk move/delete doesn't accrue orphan dirs
+        # (F3 of #161). Floored at the entry's *zone directory* — a zone is a
+        # declared, first-class container, so its own dir is preserved even when
+        # momentarily empty; only the sub-dirs the bulk op carved out are
+        # pruned. Stops at the first non-empty ancestor, so a dir holding a
+        # `.gitkeep` or sibling entries survives. Best-effort: a lost race or a
+        # non-empty dir is silently fine, never fatal to the write.
+        def prune_empty_parents(path)
+          floor = zone_floor(path)
+          return unless floor
+
+          dir = File.dirname(path)
+          while dir.start_with?("#{floor}/") && Dir.empty?(dir)
+            Dir.rmdir(dir)
+            dir = File.dirname(dir)
+          end
+        rescue SystemCallError
+          nil
+        end
+
+        # The zone directory under which `path` lives (`<root>/zones/<zone>`),
+        # or nil if `path` is not under the store's zones tree.
+        def zone_floor(path)
+          zones_root = File.join(@manifest.data.root, "zones")
+          prefix = "#{zones_root}/"
+          return nil unless path.start_with?(prefix)
+
+          zone_seg = path.delete_prefix(prefix).split("/").first
+          zone_seg && File.join(zones_root, zone_seg)
+        end
+
         def ensure_uid(format, meta, content, existing_uid)
           Textus::Entry.for_format(format).inject_uid(meta, content, existing_uid)
         end

data/lib/textus/layout.rb

@@ -29,6 +29,14 @@ module Textus
       File.join(run(root), "audit")
     end
 
+    # Sentinels are machine-generated (the published target's sha), not authored
+    # source, so they live on the runtime side under `.run/` — git-ignored,
+    # regenerated by the next build via content-identical adoption (ADR 0070,
+    # superseding ADR 0038's `:config` classification).
+    def self.sentinels(root)
+      File.join(run(root), "sentinels")
+    end
+
     def self.audit_log(root)
       File.join(audit_dir(root), "audit.log")
     end