textus 0.45.1 → 0.47.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfb215839c07335a72f604bbcb830d6027a118f500be30243a592cc9c5b07cf0
-  data.tar.gz: dd0103470acbdfb747077bc6d0fafbc08700edfe5a24d09416723d47517871df
+  metadata.gz: c87fe067b0988d187beac617c4540e1563d0f006a08d6090b2b483c699555d46
+  data.tar.gz: 4f0503119ebf3eeff28d7a16aee8dc8c62673e6b41912e85bc3453e596075e65
 SHA512:
-  metadata.gz: 310065adbf501efcd2b793b896770a9cc7e5a38e41c23852c12b18dfca5cc93cea7af1545bac5e306a667aeac959995c9cf08468a3d86869facec42d11c1501f
-  data.tar.gz: 938e0ed014c543d2cba7190ab6de0440a36670268b4207af19444934fb28560cda382452c0cb1db26e4c31bfe78b89031c52fbdb0196fc7d67eb360013d58d5f
+  metadata.gz: fde04b0339e798e545c98699462afaf2767a772f1e76811c4f8833b561b69d02b172e4879cf17ffaea1dd51f1930846007abf4523a801ccfb5525c53e1365b7f
+  data.tar.gz: 10a4343781cb2251ba8f91121c0a89b1fe211702e7c5057693fce27357eee55c3abe6bfe7a88009ffc89f5fcc49ad6c44fcf258f532f5ac9d69d960857e833c6

data/CHANGELOG.md

@@ -9,6 +9,35 @@ 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.47.0 — 2026-06-04 — Close the agent loop over MCP
+
+The edit→accept→rebuild loop now closes over a single MCP transport: `build` is surfaced to MCP, `init --with-agent` scaffolds a connectable agent setup, and connection-lifecycle hardening (whole-contract drift fingerprint + a connect-time event carrying the resolved role) underpins it.
+
+### Changed (breaking)
+
+- **Drift guard now fingerprints the whole contract.** `Session#manifest_etag` is renamed `contract_etag` and now digests `manifest.yaml` + `hooks/**/*.rb` + `schemas/**/*` ([ADR 0074](docs/architecture/decisions/0074-contract-etag-drift-guard.md)). A mid-session edit to any hook or schema raises `contract_drift` on the next MCP `tools/call`, where previously only a manifest edit did. The composite digest lives as `Etag.for_contract`.
+  - **Wire:** the `pulse` envelope key `manifest_etag` is renamed `contract_etag`.
+  - **Ruby:** `Textus::Session#manifest_etag` / `Textus::MCP::Session#manifest_etag` is renamed `contract_etag`. Embedders constructing a `Session` must pass `contract_etag:`.
+
+### Added
+
+- **`build` is surfaced to MCP** ([ADR 0076](docs/architecture/decisions/0076-build-gates-by-capability-actor-surface-to-mcp.md)) — previously CLI-only. `build` is transport-uniform, caller-agnostic, and self-elevating: it always runs as the manifest's `build`-capable actor (not the caller) and grants no authority over content, since it only recomputes the deterministic, content-addressed projection of already-accepted canon. Actor-resolution and the `BuildLock` moved out of the CLI verb into the shared `Write::Build` use-case (an `around :build_lock` resource), so single-writer serialization now spans **every** transport — closing a latent gap where the Ruby API path skipped the lock. The MCP catalog derives the new tool; `boot` auto-advertises it.
+- **`textus init --with-agent`** ([ADR 0077](docs/architecture/decisions/0077-init-with-agent-profile.md)) — an opt-in profile that scaffolds a connectable agent setup on top of the neutral store: `knowledge.project` + `knowledge.runbooks` entries (with their schemas), an `artifacts.orientation` derived entry that projects them to `CLAUDE.md`/`AGENTS.md`, and a write-once starter `.mcp.json` at the project root. The default `init` (no flag) is unchanged and stays vendor-neutral; under the flag, `init` writes exactly one file outside `.textus/` (`.mcp.json`, never clobbered if present). Paired with `build` over MCP, an agent can edit `knowledge.*` and rebuild its own orientation without leaving the conversation.
+- **`:session_opened` hook event** ([ADR 0075](docs/architecture/decisions/0075-session-opened-connect-event.md)) — fires once per MCP connection at `initialize` with `ctx:, role:, cursor:` (the resolved connection role). Use it for connect-time, role-keyed behavior (session logging, context priming). Distinct from `:store_loaded` (process-time, default role).
+
+## 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)
 
@@ -653,6 +653,7 @@ end
 | `:entry_renamed`        | pubsub  | ctx:, key:, from_key:, to_key:, envelope:                 | (discarded)           | logged        |
 | `:proposal_rejected`    | pubsub  | ctx:, key:, target_key:                                   | (discarded)           | logged        |
 | `:store_loaded`         | pubsub  | ctx:                                                      | (discarded)           | logged        |
+| `:session_opened`       | pubsub  | ctx:, role:, cursor:                                     | (discarded)           | logged        |
 | `:fetch_started`        | pubsub  | ctx:, key:, mode:                                         | (discarded)           | logged        |
 | `:fetch_failed`         | pubsub  | ctx:, key:, error_class:, error_message:                  | (discarded)           | logged        |
 | `:fetch_backgrounded`   | pubsub  | ctx:, key:, started_at:, budget_ms:                       | (discarded)           | logged        |
@@ -672,7 +673,7 @@ The three `:fetch_*` lifecycle events report the progress and failures of backgr
 
 Declaring `store:` instead of `caps:` in an RPC callable will pass registration but raise `UsageError` at call time (`Hooks::RpcRegistry#invoke` rejects `store:` — there is no shim).
 
-The primary entity is always `key:` (for `:proposal_accepted`, `key:` is the pending key being accepted and `target_key:` is the destination). For `:entry_renamed`, `key:` is present and equals `to_key:` — it is the entry's post-move home, present so `keys:` glob filters route correctly; `from_key:` is the prior key. For `:proposal_rejected`, `key:` is the pending key being rejected. For `:store_loaded`, no key — the event observes store readiness, not an entry.
+The primary entity is always `key:` (for `:proposal_accepted`, `key:` is the pending key being accepted and `target_key:` is the destination). For `:entry_renamed`, `key:` is present and equals `to_key:` — it is the entry's post-move home, present so `keys:` glob filters route correctly; `from_key:` is the prior key. For `:proposal_rejected`, `key:` is the pending key being rejected. For `:store_loaded`, no key — the event observes store readiness, not an entry. For `:session_opened`, no key — it fires once per MCP connection at `initialize` with the connection's resolved `role:` and boot `cursor:` (ADR 0075); distinct from `:store_loaded`, which fires once per process at `Store#initialize` under the default role.
 
 **RPC mode** — exactly one handler per (event, name). The manifest references the handler by name (`intake.handler: NAME`, `compute.transform: NAME`). Failure or timeout aborts the calling operation.
 
@@ -735,10 +736,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 +900,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 +910,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. `build` is also on MCP (ADR 0076): it is caller-agnostic and self-elevating — it always runs as the manifest's `build`-capable actor regardless of the calling role, grants no authority over content (build is a pure, idempotent function of already-accepted canon, ADR 0070), and is serialized by a shared single-writer lock across all transports so a concurrent CLI or background build cannot collide with an MCP-triggered one.
 
 `latest_seq` is the current high-water mark of the audit log; agents should use it as the starting cursor for `pulse`.
 
@@ -922,13 +923,13 @@ The agent's MCP write surface includes the single-key `delete` and `mv` tools al
   "stale":          [ "artifacts.marketplace" ],
   "pending_review": [ "proposals.proposal.123" ],
   "doctor":         { "ok": true, "warn": 0, "fail": 0 },
-  "manifest_etag":  "sha256:1f3a…",
+  "contract_etag":  "sha256:1f3a…",
   "next_due_at":    "2026-06-01T09:00:00Z",
   "hook_errors":    [ { "seq": 1844, "event": "after_put", "hook": "notify", "key": "knowledge.notes.x", "error_class": "Timeout::Error", "error_message": "…", "at": "..." } ]
 }
 ```
 
-`cursor` is the new high-water mark; pass it as `--since` on the next call. `changed` is sourced from `audit --seq-since`. `stale` is sourced from `freshness`. `pending_review` lists all keys in the queue zone. `doctor` is an `{ok, warn, fail}` count summary. `manifest_etag` is the `sha256:`-prefixed content hash of the manifest (ADR 0025), for cheap change-detection. `next_due_at` is the soonest upcoming freshness deadline across entries (ISO-8601, or `null` if none). `hook_errors` lists hook failures recorded since the cursor. When `--since` is below the oldest available seq (due to audit log rotation), pulse returns `CursorExpired`.
+`cursor` is the new high-water mark; pass it as `--since` on the next call. `changed` is sourced from `audit --seq-since`. `stale` is sourced from `freshness`. `pending_review` lists all keys in the queue zone. `doctor` is an `{ok, warn, fail}` count summary. `contract_etag` is the `sha256:`-prefixed composite content hash of the contract — the manifest plus hooks and schemas (ADR 0074, via ADR 0025) — for cheap change-detection. `next_due_at` is the soonest upcoming freshness deadline across entries (ISO-8601, or `null` if none). `hook_errors` lists hook failures recorded since the cursor. When `--since` is below the oldest available seq (due to audit log rotation), pulse returns `CursorExpired`.
 
 **`put` input** (read from stdin when `--stdin` is given):
 
@@ -1010,13 +1011,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

@@ -237,7 +237,7 @@ soul (skill/agent)  ──▶  gate (CLI | MCP)  ──▶  Store  ──▶  me
 Two transports, one façade:
 
 - **CLI** — human/script surface. `textus boot`, `textus pulse --since=N`, `textus get/put/...`.
-- **MCP** — agent surface. `textus mcp serve` runs a stdio JSON-RPC 2.0 server speaking MCP draft 2024-11-05. Tools are auto-derived from the manifest. Session state (cursor, role, manifest_etag) is server-side.
+- **MCP** — agent surface. `textus mcp serve` runs a stdio JSON-RPC 2.0 server speaking MCP draft 2024-11-05. Tools are auto-derived from the manifest. Session state (cursor, role, contract_etag) is server-side.
 
 Both transports call `store.<verb>(..., role:)` (or `store.as(role).<verb>(...)`). No duplicate logic.
 
@@ -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."
+Contract drift surfaces as `ContractDrift` (contract_etag mismatch — a change to the manifest, hooks, or schemas; ADR 0074); 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/verb/build.rb

@@ -7,16 +7,7 @@ module Textus
         option :prefix, "--prefix=K"
 
         def invoke(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
-            ops = store.as(role)
-            result = ops.build(prefix: prefix)
-            emit(result)
-          end
+          emit(store.as(resolved_role(store)).build(prefix: prefix))
         end
       end
     end

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

@@ -4,11 +4,13 @@ module Textus
       class Init < Verb
         command_name "init"
 
+        option :with_agent, "--with-agent"
+
         def self.needs_store? = false
 
         def call(_store)
           target = File.join(@cwd, ".textus")
-          emit(Textus::Init.run(target))
+          emit(Textus::Init.run(target, with_agent: !!with_agent))
         end
       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/contract/resources/build_lock.rb

@@ -0,0 +1,17 @@
+module Textus
+  module Contract
+    module Resources
+      # Serializes builds across every surface (CLI, MCP, Ruby). Previously the
+      # CLI verb wrapped each build in a BuildLock by hand; lifting it into the
+      # contract means the MCP surface inherits the single-writer guarantee and
+      # cannot collide with a concurrent CLI or background build.
+      class BuildLock
+        def wrap(scope:, inputs:, session: nil) # rubocop:disable Lint/UnusedMethodArgument
+          Textus::Ports::BuildLock.with(root: scope.container.root) { yield(inputs) }
+        end
+      end
+    end
+  end
+end
+
+Textus::Contract::Around.register(:build_lock, Textus::Contract::Resources::BuildLock.new)

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,