textus 0.10.1 → 0.10.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da7bc5c1fbc90ea76df8adb279491b3a94b4b093f014281ca28c317366539cad
-  data.tar.gz: 92b35dab2a95f81d93e45a467652ee840ed06617a3df587d66a170884b99b81f
+  metadata.gz: c38f76b221f200d4af26262a94de566a9f43949282c0a060472ed85974657ac5
+  data.tar.gz: 86231d26523777d9b6751e33c09138efb921bc36ed446c32ae4537371515e7dd
 SHA512:
-  metadata.gz: f84bf665d8aa002bfac744ada1e43b6993d9209f8997cafdfc441f74c758edb8ef28b5b3d45e70f8ccb58cc3c82c05a3238a40940142a35d25fd1807ed237324
-  data.tar.gz: cd2326ee626d90217aaf9f9e91b10441d6b397af3bf3bb8c54dde00e5bfa37eca56ca7011175f58168a1b0365a484de76e9ebac3022f035833974442a73e9f1e
+  metadata.gz: bc9c2677e749237c9bc78a3b4005e4cddd1228f95044e60afc04a2ac3323dd266aa02bffff9173d7b70d5c0cb33d04a08375ecefbf0ad0b852b43a294443fcf8
+  data.tar.gz: df18177f6df9bbcc9bb8467b2f4736e0d71f2a78a0f7dfed74865ad0f7e8b84028c0c75690357367bde106a5c5d779b03fee4f6d5e73b8e245c7e14c104d9c30

data/CHANGELOG.md

@@ -8,6 +8,59 @@ The **gem version** (`0.x.y`) is distinct from the **protocol version**
 (currently `textus/2`, embedded in every envelope as `protocol`). The protocol
 is additive within a major; a new major would change the wire string.
 
+## 0.10.3 — Documentation refresh and legacy-code removal (2026-05-23)
+
+Patch release. Two pieces of work: (1) docs describe current state only — every reference to pre-0.9.2 zone names, pre-0.10.2 sentinel layout, pre-0.5 audit-log format, and other version-history annotations is stripped from user-facing docs; (2) the corresponding backward-compatibility code paths are deleted from `lib/`. The wire protocol stays `textus/2`. Callers conforming to the current SPEC are unaffected; callers carrying obsolete config now hit silent drops or parse failures instead of helpful migration messages.
+
+### Removed
+
+- **`Doctor::Check::LegacyIntakeFields`** — deleted. Manifest parsing already rejected these fields at load; the doctor check was redundant.
+- **TSV audit-log reader** in `Store::AuditLog#parse_row` and `#check_line` — pre-0.5 audit logs are no longer transparently read. Non-JSON lines surface as `invalid_json` integrity violations.
+- **Legacy sibling sentinel migration** in `Infra::Publisher` and `Store::Sentinel.legacy_path` — pre-0.10.2 stores with sibling `<target>.textus-managed.json` files are no longer recognized as managed. Fix: `rm <target>.textus-managed.json && textus build`.
+- **Manifest rename-migration rejections** — entries containing `source:`, `intake.fetch`, `intake.{ttl,on_stale,sync_budget_ms}`, or `projection.reducer` no longer raise migration hints. These obsolete fields are silently ignored by the parser.
+- **`textus/1` helpful-message branch** in `Manifest.load` — unsupported versions now produce a single generic error.
+- **`textus stale` CLI stub** — removed; calling it now returns `unknown verb: stale` like any other typo.
+- **`Manifest::Entry#derived?`** alias — both internal callers now invoke `in_generator_zone?` directly.
+- **Stale CLI help text** — `textus migrate {zones,policies}` (reverted in 0.9.2) and "`--format=json` accepted for back-compat" wording removed from `textus --help`.
+
+### Documentation
+
+- **`docs/plans/`** is now signposted in `CONTRIBUTING.md` as design history, not current documentation.
+- **README, SPEC, ARCHITECTURE, docs/zones, docs/events, docs/conventions, examples/claude-plugin/README** — stripped `(0.8.2+)`, `(0.9.0+)`, `(0.9.2)`, `(v1.0)`, `(v1.1)`, `(v1.2)`, `(v0.3)` annotations from headings, parentheticals, and inline notes. Removed "Renamed in 0.9.2" / "Pre-0.9.2 stores" / "New in 0.9.0" / "Backward compatibility (v0.5)" callouts. Example code that used pre-0.9.2 zone names (`canon`, `intake`, `pending`, `derived`) now uses current names (`identity`, `inbox`, `review`, `output`).
+- **`docs/events.md`** — header count corrected to "15 events: 3 RPC and 12 pub-sub" (previously read "12 events", with refresh\_\* mentioned in subtext); stale Linear manifest example updated to use top-level `policies:` block.
+- **SPEC.md §10.2** — removed `legacy_intake_fields` from the builtin doctor-check list.
+- **SPEC.md §11** — dropped `textus/1` back-compat acceptance from the implementation checklist; the spec no longer mentions the legacy v0.1 zone-synthesis fallback.
+- **CHANGELOG entries for past releases are unchanged** — historical record stays intact.
+
+### Tests
+
+- Removed `spec/doctor/check/legacy_intake_fields_spec.rb`.
+- Removed 4 manifest-intake migration-rejection specs and 3 publisher/audit-log legacy-format specs.
+
+## 0.10.2 — Doctor and store cleanup (2026-05-23)
+
+Patch release. Internal cleanup: extracts `Store::Sentinel`, moves audit-log integrity into `Store::AuditLog`, surfaces previously-swallowed schema parse errors, and tidies two doctor checks. No CLI, wire-protocol, or behavioral changes for plugin authors. Sentinel JSON shape changes (repo-relative paths) are forward-compatible; legacy absolute paths are still read correctly.
+
+### Added
+
+- `Textus::Store::Sentinel` value object owning the sentinel JSON shape (`source`/`target`/`sha256`/`mode`) and the on-disk path layout. Repo-relative paths on write; legacy absolute paths still accepted on read.
+- `Textus::Store::AuditLog#verify_integrity` returns line-by-line integrity violations as `{lineno, reason, detail}` hashes.
+- `Textus::Schema#unowned_fields` returns field names whose spec lacks `maintained_by`.
+- New doctor check `schema_parse_error` (error level) surfaces YAML parse failures on `schemas/*.yaml`. Previously these were silently rescued in `UnownedSchemaFields`, leaving operators with no signal.
+
+### Changed
+
+- `Infra::Publisher` delegates sentinel I/O to `Store::Sentinel`. The sentinel JSON now stores repo-relative `source`/`target` so example trees can be committed without leaking author paths.
+- `Doctor::Check::Sentinels` delegates parse/orphan/drift detection to `Store::Sentinel`. Drops `rubocop:disable Metrics/BlockLength`.
+- `Doctor::Check::AuditLog` delegates parsing to `Store::AuditLog#verify_integrity`. Drops `rubocop:disable Metrics/BlockLength`.
+- `Doctor::Check::ManifestFiles` uses `Textus::Key::Path.resolve` instead of reimplementing leaf-path math.
+- `Doctor::Check::UnownedSchemaFields` uses `Schema#unowned_fields` instead of reaching into `schema.fields` and the raw `maintained_by` Hash key.
+- `examples/claude-plugin/.gitignore` no longer excludes `.textus/sentinels/`. The example's sentinels are now committed with repo-relative paths.
+
+### Documentation
+
+- `SPEC.md` builtin doctor-check list updated to include `schema_parse_error`, and brings the prose up to date with three checks shipped in 0.9.x/0.10.0 that were missing from the list (`policy_ambiguity`, `handler_allowlist`, `legacy_intake_fields`).
+
 ## 0.10.1 — Documentation refresh and spec hygiene (2026-05-22)
 
 Lightweight maintenance release: documentation refresh plus spec-suite hygiene. No `lib/` changes; no CLI, wire-protocol, or behavioral changes.

data/README.md

@@ -14,7 +14,7 @@ Reference implementation in Ruby. Wire format `textus/2`. SPEC: [`SPEC.md`](SPEC
 Two versions, deliberately independent:
 
 - **Protocol wire string:** `textus/2`. Stable; breaking changes require `textus/3`.
-- **Gem version:** semver, currently `0.9.2`. The gem version is decoupled from the protocol string — internal refactors bump the gem; only wire-format changes bump the protocol.
+- **Gem version:** semver, currently `0.10.3`. The gem version is decoupled from the protocol string — internal refactors bump the gem; only wire-format changes bump the protocol.
 
 Envelope payloads carry the `protocol` field. The gem version is irrelevant to the wire format.
 
@@ -57,8 +57,6 @@ You get `.textus/` with all five zone directories, baseline schemas, an empty au
 
 Manifest `path:` fields are relative to `.textus/zones/`. So `working.network.org.jane` lives at `.textus/zones/working/network/org/jane.md`.
 
-> **Renamed in 0.9.2.** Pre-0.9.2 defaults were `canon`, `intake`, `pending`, `derived`. `working` is unchanged. Upgrading a 0.9.1 store is a hand-edit (see CHANGELOG migration recipe).
-
 Read and write:
 
 ```sh
@@ -164,7 +162,7 @@ textus exposes a hook DSL. Drop `.rb` files into `.textus/hooks/` (subdirectorie
 - `:reduce` — transform rows during projection (returns rows)
 - `:check` — custom doctor check (returns issues)
 - `:put`, `:deleted`, `:refreshed`, `:built`, `:accepted`, `:published`, `:mv`, `:reject`, `:loaded` — react to lifecycle events
-- `:refresh_began`, `:refresh_failed`, `:refresh_detached` — background-refresh lifecycle (0.9.0+)
+- `:refresh_began`, `:refresh_failed`, `:refresh_detached` — background-refresh lifecycle
 
 ```ruby
 # Inside .textus/hooks/local_file.rb
@@ -205,7 +203,7 @@ Schemas (`.textus/schemas/<name>.yaml`) declare field shapes, per-field `maintai
 bundle exec rspec
 ```
 
-240 examples; includes conformance fixtures A–I from SPEC §12.
+~490 examples; includes conformance fixtures A–I from SPEC §12.
 
 ## Code quality
 

data/SPEC.md

@@ -1,6 +1,6 @@
 # textus/2 — Specification
 
-**Status:** Draft v2.0 (2026-05-22, updated for 0.9.2)
+**Status:** Draft v2.0
 **Protocol identifier:** `textus/2`
 **Reference implementation:** Ruby gem `textus`
 
@@ -51,7 +51,7 @@ textus is organized as five composable layers. Each layer has a single responsib
 
 ## 3. Storage layout
 
-The root is `.textus/` at the project working directory. A typical v1.0 tree:
+The root is `.textus/` at the project working directory. A typical tree:
 
 ```
 .textus/
@@ -75,7 +75,7 @@ Zone directories under `zones/` are conventional; their write semantics are decl
 
 `.textus/audit.log` is an append-only NDJSON file written under a file lock by every successful `put`, `delete`, `accept`, and `build`. `.textus/role` (one line containing a role name) is optional and participates in the role-resolution order (§5).
 
-### 3.1 Store location precedence (v0.3)
+### 3.1 Store location precedence
 
 Implementations MUST resolve the store root in this order; the first match wins:
 
@@ -129,25 +129,11 @@ policies:
     refresh: { ttl: 6h, on_stale: warn }
 ```
 
-**Note (0.9.2):** the default zone names were renamed from `canon|intake|pending|derived` to `identity|inbox|review|output` to align with one lifecycle axis. `working` is unchanged. Existing stores migrate by hand-editing the manifest and `mv`-ing the zone directories (see CHANGELOG). The names are conventional — the manifest is the source of truth for write permissions; rename freely.
+Zone names are conventional — the manifest is the source of truth for write permissions; rename freely.
 
-**Backward compatibility.** If the manifest omits the `zones:` block, the legacy v0.1 three-zone model is synthesized:
+**Key grammar:** dotted segments matching `/^[a-z0-9][a-z0-9-]*$/`. Segments are joined by `.`. A key has at most 8 segments; each segment is at most 64 characters. Segments MUST NOT contain dots, slashes, uppercase letters, or underscores. Example: `working.projects.acme.dashboard`. Enforcement points: manifest load (rejects illegal `key:` declarations and illegal nested file/directory names), `put` (rejects illegal keys before any write), `enumerate` (filters and warns on illegal filenames).
 
-```yaml
-zones:
-  - name: fixed
-    writable_by: [human]
-  - name: state
-    writable_by: [human, ai, script]
-  - name: derived
-    writable_by: [build]
-```
-
-Old manifests written against textus/1 draft v0.1 therefore parse without modification, and any tooling expecting `fixed`/`state`/`derived` continues to work.
-
-**Key grammar (enforced from v1.2):** dotted segments matching `/^[a-z0-9][a-z0-9-]*$/`. Segments are joined by `.`. A key has at most 8 segments; each segment is at most 64 characters. Segments MUST NOT contain dots, slashes, uppercase letters, or underscores. Example: `working.projects.acme.dashboard`. Enforcement points: manifest load (rejects illegal `key:` declarations and illegal nested file/directory names), `put` (rejects illegal keys before any write), `enumerate` (filters and warns on illegal filenames so existing trees still load with a clear migration message). Run-once migration: `textus key migrate --dry-run` then `--write` (see §audit).
-
-**Per-entry `format:` (enforced from v1.2):** an entry MAY declare `format:` to be one of `markdown` (default), `json`, `yaml`, or `text`. The `format` controls the on-disk shape and which path extension is required:
+**Per-entry `format:`** an entry MAY declare `format:` to be one of `markdown` (default), `json`, `yaml`, or `text`. The `format` controls the on-disk shape and which path extension is required:
 
 | `format`   | Path extension              | `template:`           | `schema:` |
 |------------|-----------------------------|------------------------|-----------|
@@ -158,7 +144,7 @@ Old manifests written against textus/1 draft v0.1 therefore parse without modifi
 
 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.
 
-**Per-leaf publishing (`publish_each:`, v1.2).** A nested manifest entry MAY declare `publish_each:` to byte-copy every leaf to a templated repo-relative path. `publish_each:` and `publish_to:` are mutually exclusive on the same entry, and `publish_each:` requires `nested: true`. The template substitutes these variables (using `{name}` syntax):
+**Per-leaf publishing (`publish_each:`).** A nested manifest entry MAY declare `publish_each:` to byte-copy every leaf to a templated repo-relative path. `publish_each:` and `publish_to:` are mutually exclusive on the same entry, and `publish_each:` requires `nested: true`. The template substitutes these variables (using `{name}` syntax):
 
 | Variable     | Value                                                                                  |
 |--------------|----------------------------------------------------------------------------------------|
@@ -180,7 +166,7 @@ Validation at manifest load: any unknown variable raises `UsageError`; the templ
 
 A leaf at `working.skills.writing.voice-writer` (authored at `.textus/zones/working/skills/writing/voice-writer.md`) publishes to `skills/voice-writer/SKILL.md`.
 
-**`inject_intro:` (v1.1).** A derived entry with a `template:` MAY declare `inject_intro: true`. When the builder materializes the entry, it merges the `textus intro` envelope (§9) into the projection data under the key `intro`, so the template can render orientation content (zones, write flows, CLI catalog) alongside its projected rows. The flag is rejected at manifest load on (a) non-derived entries or (b) derived entries without a `template:` — agents reading the rendered file should be able to trust the preamble was produced by the same source of truth `textus intro` exposes.
+**`inject_intro:`.** A derived entry with a `template:` MAY declare `inject_intro: true`. When the builder materializes the entry, it merges the `textus intro` envelope (§9) into the projection data under the key `intro`, so the template can render orientation content (zones, write flows, CLI catalog) alongside its projected rows. The flag is rejected at manifest load on (a) non-derived entries or (b) derived entries without a `template:` — agents reading the rendered file should be able to trust the preamble was produced by the same source of truth `textus intro` exposes.
 
 **Lookup rule:** to resolve a key, find the entry with the longest `key:` prefix that matches. If that entry has `nested: true`, the remaining segments map to subdirectories under its `path`. Otherwise the key must equal an entry exactly. The resolved filesystem path is `<.textus root>/zones/<entry.path>[/<remaining>...].md` — implementations MUST prepend `zones/` to the manifest `path:` when constructing the filesystem location.
 
@@ -190,11 +176,11 @@ Each zone declares which **roles** may write to it via `writable_by:` in the man
 
 | Zone | `writable_by` | Use case |
 |---|---|---|
-| `identity` | `[human]` | Identity, voice, immutable principles — things only a human edits. (`canon` pre-0.9.2.) |
+| `identity` | `[human]` | Identity, voice, immutable principles — things only a human edits. |
 | `working` | `[human, ai, script]` | Active project state: notes, decisions, network — what humans and agents update day-to-day. |
-| `inbox` | `[script]` | Declared external inputs (calendar, feeds, scraped pages). Refreshed by external runner scripts; never by humans or AI directly. (`intake` pre-0.9.2.) |
-| `review` | `[ai, human]` | AI-generated proposals awaiting human review via `textus accept`. Lets agents stage changes without touching `working`. (`pending` pre-0.9.2.) |
-| `output` | `[build]` | Computed outputs (catalogs, indexes, published context). Written only by the build runner via `textus build`. (`derived` pre-0.9.2.) |
+| `inbox` | `[script]` | Declared external inputs (calendar, feeds, scraped pages). Refreshed by external runner scripts; never by humans or AI directly. |
+| `review` | `[ai, human]` | AI-generated proposals awaiting human review via `textus accept`. Lets agents stage changes without touching `working`. |
+| `output` | `[build]` | Computed outputs (catalogs, indexes, published context). Written only by the build runner via `textus build`. |
 
 A write is gated by the caller's **role**, supplied via `--as=<role>`. If the role is not in the target zone's `writable_by` list, the write returns `write_forbidden`.
 
@@ -207,7 +193,7 @@ The effective role for any CLI invocation is resolved in this order; the first m
 3. `.textus/role` file (one line, role name) at the project root.
 4. Default: `human`.
 
-Recognized roles in v1.0: `human`, `ai`, `script`, `build`. Unknown roles are rejected with `invalid_role`. The roles list is intentionally open-ended: a future minor revision MAY introduce additional roles without breaking the wire string.
+Recognized roles: `human`, `ai`, `script`, `build`. Unknown roles are rejected with `invalid_role`. The roles list is intentionally open-ended: a future minor revision MAY introduce additional roles without breaking the wire string.
 
 Every successful write records the resolved role and a wall-clock timestamp in `.textus/audit.log`, so reviewers can later distinguish a human edit from an agent edit even though both live in the same file.
 
@@ -276,11 +262,11 @@ policies:
       sync_budget_ms: 500       # only used when on_stale: timed_sync (default: 500)
 ```
 
-`handler` names a registered `:intake` hook (see §5.10 for the hook contract); `config` is an opaque hash handed to the handler. The freshness budget (`ttl`, `on_stale`, `sync_budget_ms`) lives in a top-level **`policies:`** block matched by key glob (§5.11). Implementations MUST reject legacy `intake.ttl` / `intake.on_stale` / `intake.sync_budget_ms` at manifest load with a clear migration message pointing at the top-level `policies:` block (see the 0.9.2 CHANGELOG for a hand-edit recipe). Implementations MUST also reject legacy `source.from`, `source.parse`, `source.fetcher`, `source.action`, and `source.fetch` with a usage error pointing at the `intake:` key.
+`handler` names a registered `:intake` hook (see §5.10 for the hook contract); `config` is an opaque hash handed to the handler. The freshness budget (`ttl`, `on_stale`, `sync_budget_ms`) lives in a top-level **`policies:`** block matched by key glob (§5.11).
 
 #### `on_stale:` semantics
 
-`on_stale:` declares what happens when `textus get` (or any read path that annotates freshness) encounters a stale intake entry. The value lives on the matching policy block, not on the entry. Vocabulary unchanged across 0.9.x: `warn | sync | timed_sync`.
+`on_stale:` declares what happens when `textus get` (or any read path that annotates freshness) encounters a stale intake entry. The value lives on the matching policy block, not on the entry. Vocabulary: `warn | sync | timed_sync`.
 
 | Value | Behaviour |
 |---|---|
@@ -288,7 +274,7 @@ policies:
 | `sync` | Block the `get` call, run the intake handler in-process, write the refreshed result, then return the fresh envelope. The caller waits. |
 | `timed_sync` | Like `sync`, but with a `sync_budget_ms` deadline (default 500 ms). If the handler finishes within the budget the fresh envelope is returned. If it does not finish in time, return the stale envelope (with `stale: true`, `refreshing: true`) and let the refresh complete in the background. Fires `:refresh_detached` when the deadline is exceeded. |
 
-> **Note:** `list`/`where` paths do **not** annotate freshness in 0.9.0 — only `get` does. Known limitation; full `list` freshness annotation is planned for 0.10.
+> **Note:** `list`/`where` paths do **not** annotate freshness — only `get` does.
 
 In intake mode the handler MUST return one of three shapes, all normalized by the store into its internal `{_meta, body, content}` representation (§5.12):
 
@@ -340,8 +326,6 @@ Schema (one JSON object per line, no interior whitespace):
 
 For `mv`, the structural fields `from_key`, `to_key`, and `uid` appear at the top level of the JSON object. Remaining verb-specific data (e.g. `from_path`, `to_path`) is nested under an `extras` key. The `extras` key is omitted entirely when empty.
 
-**Backward compatibility (v0.5):** files written by v0.4 and earlier contain TSV rows. Readers MUST accept mixed-format files: lines starting with `{` are parsed as JSON; other lines are treated as legacy TSV (`ts\trole\tverb\tkey\tetag_before\tetag_after[\tjson_extras]`). TSV write support is removed in v0.6.
-
 ### 5.7 Security bounds
 
 textus enforces fixed bounds to keep behavior predictable under hostile or buggy input:
@@ -352,9 +336,9 @@ textus enforces fixed bounds to keep behavior predictable under hostile or buggy
 - **Entry size:** 1 MB.
 - **Audit log:** unbounded; rotation is the user's problem.
 
-### 5.8 Schema evolution (v1.1)
+### 5.8 Schema evolution
 
-Schemas may declare per-field ownership and version history. These keys are additive: a schema may omit both `fields:` and `evolution:` and still parse as in v1.0.
+Schemas may declare per-field ownership and version history. The `fields:` and `evolution:` blocks are both optional; a schema may omit them and still parse.
 
 **`fields:` block** — keyed by field name. Each entry is an object with at least `type`, plus optional `maintained_by` and any vendor extensions:
 
@@ -379,11 +363,11 @@ evolution:
 
 `textus schema migrate NAME` consults `evolution.migrate_from` when invoked without `--rename=OLD:NEW`, applying every declared rename across affected entries in one pass. An explicit `--rename` flag overrides the schema-declared map for that invocation.
 
-**Backwards compat:** v1.0 schemas (no `fields:`, no `evolution:`) continue to parse and behave identically. `schema.maintained_by(field)` returns `nil` for every field; `schema.evolution` returns `{}`.
+**Defaults:** when `fields:` and `evolution:` are absent, `schema.maintained_by(field)` returns `nil` for every field and `schema.evolution` returns `{}`.
 
 **Override rule:** the role `human` is permitted to write any `maintained_by` field, regardless of declared owner. This preserves human authority over AI/script-managed data — humans curating canon over AI-written embeddings is a feature, not a bug. All other role mismatches are reported by `doctor --check=schema_violations` with code `role_authority`, including fields `key`, `field`, `expected`, and `last_writer`.
 
-### 5.9 Reducers (v1.2)
+### 5.9 Reducers
 
 Reducers are RPC hooks on the `:reduce` event. See §5.10.
 
@@ -393,7 +377,7 @@ textus has a single hook verb: `Textus.hook(event, name, **opts) { ... }`. The E
 
 The subdirectory layout under `hooks/` is organizational only; the registered event and name come from the DSL call, not the file path. Files are loaded in alphabetical order by full path.
 
-#### Sugar surface (0.8.2+)
+#### Sugar surface
 
 Per-event methods are provided for ergonomics. They delegate to the same registry as `Textus.hook`.
 
@@ -425,7 +409,7 @@ The primitive `Textus.hook(:event, :name, &blk)` remains supported and is the au
 | :refresh_failed     | pubsub  | store:, key:, error_class:, error_message:                | (discarded)           | logged        |
 | :refresh_detached   | pubsub  | store:, key:, started_at:, budget_ms:                     | (discarded)           | logged        |
 
-**New in 0.9.0:** `:intake` replaces `:fetch` as the RPC event name for intake handlers. `:deleted`, `:refreshed`, `:built`, `:accepted`, `:published` replace `:delete`, `:refresh`, `:build`, `:accept`, `:publish` respectively for all pub-sub callers. The three `:refresh_*` lifecycle events report the progress and failures of background (timed_sync) refreshes.
+The three `:refresh_*` lifecycle events report the progress and failures of background (timed_sync) refreshes.
 
 **`:refresh_began`** fires immediately before an intake handler is invoked. `mode:` is one of `"sync"` or `"timed_sync"`.
 
@@ -443,7 +427,7 @@ The `store:` argument is always a read-only store proxy. Write attempts raise `U
 
 Each handler runs under `Timeout.timeout(2)`.
 
-### 5.11 Policies (v0.9.2)
+### 5.11 Policies
 
 A manifest MAY declare a top-level `policies:` block — a list of rule blocks matched against entry keys by glob. Each block carries one or more slots:
 
@@ -464,7 +448,7 @@ policies:
 
 | Slot | Type | Meaning |
 |---|---|---|
-| `refresh` | `{ ttl, on_stale, sync_budget_ms }` | Freshness budget for intake entries (formerly `intake.ttl` / `intake.on_stale` / `intake.sync_budget_ms`). `on_stale` is `warn` (default), `sync`, or `timed_sync`. |
+| `refresh` | `{ ttl, on_stale, sync_budget_ms }` | Freshness budget for intake entries. `on_stale` is `warn` (default), `sync`, or `timed_sync`. |
 | `handler_allowlist` | list of strings | Constrains which `intake.handler:` names may be used by entries matched by this block. Enforced by `textus doctor`. |
 | `promote_requires` | list of strings | Predicates a `review` entry must satisfy before `textus accept` will promote it. Implementations MAY use a built-in or hook-resolved predicate. Reserved for future enforcement; recorded today. |
 | `retention` | (reserved) | Slot reserved for future retention policy (cap by age / count). Implementations parse it but otherwise ignore. |
@@ -475,9 +459,7 @@ policies:
 
 **Read surface.** `textus policy list` dumps every block. `textus policy explain KEY` shows the resolved `PolicySet` for one key plus which block won each slot.
 
-**Migration.** No migrator ships in 0.9.2 — the gem is pre-1.0 with no known outside upgraders. Existing 0.9.1 stores hand-edit the manifest to move each entry's legacy `intake.ttl` / `intake.on_stale` / `intake.sync_budget_ms` into a top-level `policies:` block matched by the entry's exact key. See the 0.9.2 CHANGELOG for the recipe.
-
-### 5.12 Storage formats (v1.2)
+### 5.12 Storage formats
 
 An entry's `format:` selects a storage strategy. All strategies expose the same `parse(bytes) → {_meta, body, content}` and `serialize(meta:, body:, content:) → bytes` contract. The store, audit, etag, and projection layers operate on the parsed shape; only (de)serialization differs.
 
@@ -573,7 +555,7 @@ Every successful CLI response (`--format=json`) is a single JSON envelope:
 **Field rules:**
 - `protocol` MUST be the exact string `textus/2`.
 - `key` MUST be the canonical resolved key.
-- `zone` MUST be one of the zones declared in the manifest (`identity`, `working`, `inbox`, `review`, `output` for the default 0.9.2 model; legacy v0.1 manifests synthesize `fixed`, `state`, `derived` per §4).
+- `zone` MUST be one of the zones declared in the manifest (`identity`, `working`, `inbox`, `review`, `output` in the default scaffold).
 - `path` MUST be an absolute filesystem path.
 - `format` MUST be one of `markdown`, `json`, `yaml`, `text` (§5.12). Absent envelopes are treated as `markdown` for back-compat.
 - `body` is the raw on-disk bytes as a UTF-8 string for every format.
@@ -581,11 +563,11 @@ Every successful CLI response (`--format=json`) is a single JSON envelope:
 - `etag` MUST be `sha256:<hex>` of the raw file bytes, computed identically for every format.
 - `schema_ref` MAY be `null` for entries in subtrees with `schema: null`.
 - `uid` is the stable Textus UID (§7) if the entry carries one, else `null`. Always present in the envelope.
-- `stale` is `true` when the entry's TTL has elapsed and the data has not yet been refreshed; `false` otherwise. Only populated for entries matched by a `refresh:` policy slot (typically `inbox` zone); always `false` elsewhere. (0.9.0+; resolves through `policies:` since 0.9.2.)
-- `stale_reason` is a short human-readable string describing why the entry is stale (e.g. `"ttl_exceeded"`, `"never_refreshed"`), or `null` when `stale` is `false`. (0.9.0+)
-- `refreshing` is `true` when a `timed_sync` background refresh is in flight for this entry; `false` otherwise. Callers observing `stale: true, refreshing: true` SHOULD retry after a short delay. (0.9.0+)
+- `stale` is `true` when the entry's TTL has elapsed and the data has not yet been refreshed; `false` otherwise. Only populated for entries matched by a `refresh:` policy slot (typically `inbox` zone); always `false` elsewhere.
+- `stale_reason` is a short human-readable string describing why the entry is stale (e.g. `"ttl_exceeded"`, `"never_refreshed"`), or `null` when `stale` is `false`.
+- `refreshing` is `true` when a `timed_sync` background refresh is in flight for this entry; `false` otherwise. Callers observing `stale: true, refreshing: true` SHOULD retry after a short delay.
 
-> **Note:** `list`/`where` envelopes do **not** include `stale`, `stale_reason`, or `refreshing` in 0.9.0 — freshness annotation is only provided by `get`. This is a known limitation.
+> **Note:** `list`/`where` envelopes do **not** include `stale`, `stale_reason`, or `refreshing` — freshness annotation is only provided by `get`.
 
 Errors use a distinct envelope:
 
@@ -594,8 +576,8 @@ Errors use a distinct envelope:
   "protocol": "textus/2",
   "ok": false,
   "code": "write_forbidden",
-  "message": "zone 'canon' is not writable by role 'ai' for key 'canon.identity'",
-  "details": { "key": "canon.identity", "zone": "canon", "role": "ai" }
+  "message": "zone 'identity' is not writable by role 'ai' for key 'identity.self'",
+  "details": { "key": "identity.self", "zone": "identity", "role": "ai" }
 }
 ```
 
@@ -645,8 +627,6 @@ All verbs accept `--format=json` and emit a canonical envelope (success or error
 | `key uid K` | read | any |
 | `hook run NAME` | write | any |
 
-**0.9.2 breaking:** `textus stale` was removed; use `textus freshness` (same input, slightly richer output shape — see below).
-
 **`put` input** (read from stdin when `--stdin` is given):
 
 ```json
@@ -675,7 +655,7 @@ All verbs accept `--format=json` and emit a canonical envelope (success or error
 }
 ```
 
-`textus freshness` replaced `textus stale` in 0.9.2. Each row reports one entry's verdict (`fresh`, `stale`, `never_refreshed`, or `no_policy`) against its matched `refresh:` policy. `textus build` consumes its own staleness signal and executes derived entries' projections under the `build` role; `--dry-run` prints the plan without executing.
+Each row reports one entry's verdict (`fresh`, `stale`, `never_refreshed`, or `no_policy`) against its matched `refresh:` policy. `textus build` consumes its own staleness signal and executes derived entries' projections under the `build` role; `--dry-run` prints the plan without executing.
 
 `textus accept K --as=human` promotes a pending entry into its target zone: it copies the patch body into the target key, deletes the pending entry, and writes one audit line per side (§audit). Only the `human` role may invoke `accept`.
 
@@ -693,17 +673,16 @@ Every `Textus::Error` exposes `code`, `message`, and an optional `hint:`. The hi
 
 ## 10.2 `textus doctor`
 
-`textus doctor` returns a health-check envelope: `{ "protocol": "textus/2", "ok": bool, "issues": [...], "summary": {error, warning, info} }`. Each issue carries `code`, `level` (`error|warning|info`), `subject`, `message`, and optionally `fix`. `ok` is true iff no error-level issues are present; warnings and info do not flip the bit. Builtin checks: `manifest_files`, `schemas`, `templates`, `hooks`, `illegal_keys`, `sentinels`, `audit_log`, `unowned_schema_fields`, `schema_violations`. Additional registered `:check` hooks (§5.10) run after the builtin set. Exit code is 0 on `ok`, 1 otherwise.
+`textus doctor` returns a health-check envelope: `{ "protocol": "textus/2", "ok": bool, "issues": [...], "summary": {error, warning, info} }`. Each issue carries `code`, `level` (`error|warning|info`), `subject`, `message`, and optionally `fix`. `ok` is true iff no error-level issues are present; warnings and info do not flip the bit. Builtin checks: `manifest_files`, `schemas`, `schema_parse_error`, `templates`, `hooks`, `illegal_keys`, `sentinels`, `audit_log`, `unowned_schema_fields`, `schema_violations`, `policy_ambiguity`, `handler_allowlist`. Additional registered `:check` hooks (§5.10) run after the builtin set. Exit code is 0 on `ok`, 1 otherwise.
 
 ## 11. Versioning
 
-- The current wire string is `textus/2`. It was introduced in gem v0.5, which unified the `_meta` block across all storage formats (markdown, json, yaml, text) and replaced the legacy TSV audit-log write path with NDJSON.
-- `textus/1` was the original protocol (gem ≤ v0.4). Manifests declaring `version: textus/1` are still accepted for backward compatibility (§4).
+- The current wire string is `textus/2`.
 - Backward-compatible additions (new fields, new error codes, new schema types) MAY be made under `textus/2`.
 - Breaking changes (renamed/removed envelope fields, zone semantics, key grammar) require a new wire string `textus/3`.
 - Implementations MUST reject envelopes whose `protocol` they do not recognize.
 
-The reference Ruby gem follows semver independently. The current gem version is `0.9.2`, which speaks `textus/2`.
+The reference Ruby gem follows semver independently and speaks `textus/2`.
 
 ## 12. Conformance fixtures
 
@@ -734,7 +713,7 @@ Given a manifest entry with `publish_to: <path>`, a successful `textus build` fo
 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.
 
 **Fixture I — Pending → accept:**
-Given a pending entry `pending.canon.identity.patch` proposing a change to `canon.identity`, `textus accept canon.identity --as=human` copies the patch body into `canon.identity`, deletes the pending entry, and appends two audit lines (one for the canon write, one for the pending delete) in that order.
+Given a review entry `review.identity.self.patch` proposing a change to `identity.self`, `textus accept identity.self --as=human` copies the patch body into `identity.self`, deletes the review entry, and appends two audit lines (one for the identity write, one for the review delete) in that order.
 
 ## 13. Why not X?
 
@@ -752,7 +731,7 @@ Given a pending entry `pending.canon.identity.patch` proposing a change to `cano
 
 - **Why not vector embeddings?** Different problem. textus is for facts agents act on deterministically; embeddings are for fuzzy retrieval. They compose — index a textus tree into a vector store if you need both.
 
-## 13.1 Layered architecture (internal, 0.9.0+)
+## 13.1 Layered architecture (internal)
 
 Textus internals are organized into four layers. The dependency rule is one-way — each layer may only import from the layer beneath it.
 
@@ -765,7 +744,7 @@ The `lib/textus/store/`, `lib/textus/manifest/`, `lib/textus/hooks/` namespaces
 
 Plugin authors interact only with the Hook DSL (`Textus.intake`, `Textus.refreshed`, etc.) and the manifest YAML schema. The layering is internal and may evolve.
 
-As of 0.9.1, the write path mirrors the read path:
+Both read and write paths flow through the application layer:
 
 - **Reads** flow through `Application::Reads::Get`, which takes a `Context` and dispatches refresh via `Application::Refresh::Orchestrator`.
 - **Writes** flow through `Application::Writes::{Put,Delete,Build,Accept,Publish}`, each taking a `Context`. Permission checks happen at the use-case layer (via `Context#can_write?`); I/O happens at `Store::Writer#write_envelope_to_disk` (pure).
@@ -777,7 +756,7 @@ See `ARCHITECTURE.md` for an ASCII diagram and the full read-path walkthrough.
 ## 14. Open questions (v2.x scope)
 
 - **Locking on `put`:** the reference impl uses sha256 etags. Should the spec also define a file-lock fallback for systems where read-before-write is racy?
-- **Schema imports:** can one schema reference another (`type: $ref: person`)? Defer to v1.1.
+- **Schema imports:** can one schema reference another (`type: $ref: person`)?
 - **Internationalization:** non-ASCII in keys? Spec currently restricts segments to `[a-z0-9_-]`. Revisit if community wants Unicode.
 - **Generated content in `derived/`:** the spec says `schema: null` is allowed, but should there be a separate marker (`generated: true`) for clarity?
 
@@ -785,7 +764,7 @@ See `ARCHITECTURE.md` for an ASCII diagram and the full read-path walkthrough.
 
 A `textus/2` implementation MUST:
 
-- [ ] Parse `.textus/manifest.yaml` and accept `version: textus/2` (and `textus/1` for backward compat per §11).
+- [ ] Parse `.textus/manifest.yaml` and accept `version: textus/2`.
 - [ ] Resolve keys via longest-prefix match against manifest entries.
 - [ ] Read `_meta` + body from `.md` files; validate against the named schema.
 - [ ] Read `_meta` from the top-level `_meta` hash in `.json` / `.yaml` files; validate against the named schema.

data/docs/conventions.md

@@ -27,8 +27,6 @@ Recommended top-level layout — the spec allows alternatives, but this is what
 
 Inside `working/`, group by **domain** (people, projects, decisions, runbooks), not by file type or date. Inside `output/`, group by **producer** (`output/catalogs/`, `output/indexes/`) so it's clear which build job owns what.
 
-> **0.9.2 rename.** Default zone names moved off historical artifact terms (`canon/intake/pending/derived`) to one lifecycle axis (`identity/inbox/review/output`); `working` is unchanged. Upgrade existing stores by hand-editing the manifest and `mv`-ing the zone directories (see 0.9.2 CHANGELOG).
-
 ## Schema design
 
 - **One schema per entry type, not per directory.** `person.yaml`, `project.yaml`, `decision.yaml` — applied across multiple subtrees if the shape matches.
@@ -79,7 +77,7 @@ textus freshness --format=json \
 
 - **Bodies are Markdown.** Headings, lists, code fences — whatever a human or agent finds useful.
 - **The schema does not validate the body.** If a field belongs in structured data, put it in frontmatter, not the body.
-- **Keep entries short.** If a project entry hits 500 lines, it probably wants to be split into sub-entries (e.g. `state.projects.acme.dashboard` + `state.projects.acme.api`) rather than one mega-document.
+- **Keep entries short.** If a project entry hits 500 lines, it probably wants to be split into sub-entries (e.g. `working.projects.acme.dashboard` + `working.projects.acme.api`) rather than one mega-document.
 
 ## Concurrency
 

data/lib/textus/cli.rb

@@ -53,10 +53,6 @@ module Textus
                                   0
       when "--help", "-h"    then print_help
                                   0
-      when "stale"
-        raise UsageError.new(
-          "textus stale was removed in 0.9.2 — use `textus freshness` instead",
-        )
       else
         klass = VERBS[verb] or raise UsageError.new("unknown verb: #{verb}")
         dispatch(klass, argv)
@@ -88,7 +84,7 @@ module Textus
       @stdout.puts <<~HELP
         textus #{VERSION} — reference implementation of #{PROTOCOL}
 
-        Usage (json output is the default; --format=json accepted for back-compat):
+        Usage (json output is the default):
           textus list [--prefix=KEY] [--zone=Z]
           textus where KEY
           textus get KEY
@@ -104,7 +100,6 @@ module Textus
           textus schema {show,init,diff,migrate}
           textus hook {list,run}
           textus policy {list,explain}
-          textus migrate {zones,policies}
       HELP
     end
   end

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

@@ -1,48 +1,32 @@
-require "json"
-
 module Textus
   module Doctor
     class Check
       class AuditLog < Check
         def call
-          out = []
           path = File.join(store.root, "audit.log")
-          return out unless File.exist?(path)
-
-          File.foreach(path).with_index(1) do |line, lineno| # rubocop:disable Metrics/BlockLength
-            stripped = line.chomp
-            next if stripped.empty?
+          Textus::Store::AuditLog.new(store.root).verify_integrity.map do |v|
+            {
+              "code" => "audit.parse_error",
+              "level" => "warning",
+              "subject" => "#{path}:#{v["lineno"]}",
+              "message" => violation_message(v),
+              "fix" => "inspect #{path} at line #{v["lineno"]} and remove the corrupted row",
+            }
+          end
+        end
 
-            if stripped.start_with?("{")
-              begin
-                JSON.parse(stripped)
-              rescue JSON::ParserError => e
-                out << {
-                  "code" => "audit.parse_error",
-                  "level" => "warning",
-                  "subject" => "#{path}:#{lineno}",
-                  "message" => "audit log line #{lineno} is invalid JSON: #{e.message}",
-                  "fix" => "inspect #{path} at line #{lineno} and remove the corrupted row",
-                }
-              end
-            else
-              # Legacy TSV (pre-0.5): read-only support retained for on-disk logs
-              # written by older textus versions. Never written by current code.
-              # Minimum 6 fields.
-              fields = stripped.split("\t")
-              next if fields.length >= 6
+        private
 
-              out << {
-                "code" => "audit.parse_error",
-                "level" => "warning",
-                "subject" => "#{path}:#{lineno}",
-                "message" => "audit log line #{lineno} has #{fields.length} fields " \
-                             "(expected >=6 for legacy TSV; consider migrating to NDJSON)",
-                "fix" => "inspect #{path} at line #{lineno} and remove the corrupted row",
-              }
-            end
+        def violation_message(v)
+          case v["reason"]
+          when "invalid_json"
+            "audit log line #{v["lineno"]} is invalid JSON: #{v["detail"]}"
+          when "short_tsv"
+            "audit log line #{v["lineno"]} #{v["detail"]} " \
+            "(consider migrating to NDJSON)"
+          else
+            v["detail"]
           end
-          out
         end
       end
     end

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

@@ -3,11 +3,10 @@ module Textus
     class Check
       class ManifestFiles < Check
         def call
-          out = []
-          store.manifest.entries.each do |entry|
+          store.manifest.entries.each_with_object([]) do |entry, out|
             next if entry.nested
 
-            path = leaf_path_for(entry)
+            path = Textus::Key::Path.resolve(store.manifest, entry)
             next if File.exist?(path)
 
             out << {
@@ -19,18 +18,6 @@ module Textus
                        "(or leave empty if not yet authored)",
             }
           end
-          out
-        end
-
-        private
-
-        def leaf_path_for(entry)
-          primary_ext = Entry.for_format(entry.format).extensions.first
-          if File.extname(entry.path) == ""
-            File.join(store.root, "zones", entry.path + primary_ext)
-          else
-            File.join(store.root, "zones", entry.path)
-          end
         end
       end
     end

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

@@ -0,0 +1,28 @@
+module Textus
+  module Doctor
+    class Check
+      # Surfaces YAML parse failures for files in <store>/schemas/. Without
+      # this check, malformed schemas are silently skipped by other doctor
+      # checks (UnownedSchemaFields rescues, Schemas only checks filenames),
+      # leaving the operator with no signal that a schema is broken.
+      class SchemaParseError < Check
+        def call
+          dir = File.join(store.root, "schemas")
+          return [] unless File.directory?(dir)
+
+          Dir.glob(File.join(dir, "*.yaml")).each_with_object([]) do |path, out|
+            Schema.load(path)
+          rescue StandardError => e
+            out << {
+              "code" => "schema.parse_error",
+              "level" => "error",
+              "subject" => path,
+              "message" => "schema failed to parse: #{e.class}: #{e.message}",
+              "fix" => "fix the YAML at #{path} (check indentation, quoted scalars, and aliases)",
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,55 +1,56 @@
-require "digest"
-require "json"
-
 module Textus
   module Doctor
     class Check
       class Sentinels < Check
         def call
-          out = []
           dir = File.join(store.root, "sentinels")
-          return out unless File.directory?(dir)
+          return [] unless File.directory?(dir)
 
-          Dir.glob(File.join(dir, "**", "*.textus-managed.json")).each do |sp| # rubocop:disable Metrics/BlockLength
-            begin
-              data = JSON.parse(File.read(sp))
-            rescue JSON::ParserError => e
-              out << {
-                "code" => "sentinel.parse_error",
-                "level" => "warning",
-                "subject" => sp,
-                "message" => "sentinel is not valid JSON: #{e.message}",
-                "fix" => "delete #{sp} and re-run 'textus build' to regenerate",
-              }
-              next
-            end
+          repo_root = File.dirname(store.root)
+          Dir.glob(File.join(dir, "**", "*#{Textus::Store::Sentinel::SUFFIX}")).flat_map do |sentinel_path|
+            inspect_sentinel(sentinel_path, repo_root)
+          end
+        end
 
-            target = data["target"]
-            recorded_sha = data["sha256"]
+        private
 
-            if target.nil? || !File.exist?(target)
-              out << {
-                "code" => "sentinel.orphan",
-                "level" => "warning",
-                "subject" => sp,
-                "message" => "sentinel target #{target.inspect} no longer exists",
-                "fix" => "delete #{sp} (the published file is gone) or restore the target",
-              }
-              next
-            end
+        def inspect_sentinel(sentinel_path, repo_root)
+          sentinel = Textus::Store::Sentinel.load(sentinel_path, repo_root)
+          return [parse_error_issue(sentinel_path)] if sentinel.nil?
+          return [orphan_issue(sentinel_path, sentinel)] if sentinel.orphan?
+          return [drift_issue(sentinel)] if sentinel.drift?
 
-            current_sha = Digest::SHA256.hexdigest(File.binread(target))
-            next if recorded_sha.nil? || current_sha == recorded_sha
+          []
+        end
 
-            out << {
-              "code" => "sentinel.drift",
-              "level" => "warning",
-              "subject" => target,
-              "message" => "published file at #{target} was modified out-of-band",
-              "fix" => "re-run 'textus build' to overwrite, or copy the manual edit back into the store source",
-            }
-          end
-          out
+        def parse_error_issue(sentinel_path)
+          {
+            "code" => "sentinel.parse_error",
+            "level" => "warning",
+            "subject" => sentinel_path,
+            "message" => "sentinel is not valid JSON",
+            "fix" => "delete #{sentinel_path} and re-run 'textus build' to regenerate",
+          }
+        end
+
+        def orphan_issue(sentinel_path, sentinel)
+          {
+            "code" => "sentinel.orphan",
+            "level" => "warning",
+            "subject" => sentinel_path,
+            "message" => "sentinel target #{sentinel.target.inspect} no longer exists",
+            "fix" => "delete #{sentinel_path} (the published file is gone) or restore the target",
+          }
+        end
+
+        def drift_issue(sentinel)
+          {
+            "code" => "sentinel.drift",
+            "level" => "warning",
+            "subject" => sentinel.target,
+            "message" => "published file at #{sentinel.target} was modified out-of-band",
+            "fix" => "re-run 'textus build' to overwrite, or copy the manual edit back into the store source",
+          }
         end
       end
     end

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

@@ -3,30 +3,36 @@ module Textus
     class Check
       class UnownedSchemaFields < Check
         def call
-          out = []
           dir = File.join(store.root, "schemas")
-          return out unless File.directory?(dir)
+          return [] unless File.directory?(dir)
 
-          Dir.glob(File.join(dir, "*.yaml")).sort.each do |sp| # rubocop:disable Lint/RedundantDirGlobSort
-            schema = begin
-              Schema.load(sp)
-            rescue StandardError
-              next
-            end
-            unowned = schema.fields.each_with_object([]) do |(name, spec), acc|
-              acc << name if spec.is_a?(Hash) && spec["maintained_by"].nil?
-            end
-            next if unowned.empty?
-
-            out << {
-              "code" => "schema.unowned_fields",
-              "level" => "info",
-              "subject" => schema.name || File.basename(sp, ".yaml"),
-              "message" => "schema has fields without maintained_by: #{unowned.join(", ")}",
-              "fix" => "add 'maintained_by: <role>' to each field in #{sp} (optional but recommended)",
-            }
+          Dir.glob(File.join(dir, "*.yaml")).flat_map do |path|
+            issues_for(path)
           end
-          out
+        end
+
+        private
+
+        def issues_for(path)
+          schema = safe_load(path)
+          return [] if schema.nil?
+
+          unowned = schema.unowned_fields
+          return [] if unowned.empty?
+
+          [{
+            "code" => "schema.unowned_fields",
+            "level" => "info",
+            "subject" => schema.name || File.basename(path, ".yaml"),
+            "message" => "schema has fields without maintained_by: #{unowned.join(", ")}",
+            "fix" => "add 'maintained_by: <role>' to each field in #{path} (optional but recommended)",
+          }]
+        end
+
+        def safe_load(path)
+          Schema.load(path)
+        rescue StandardError
+          nil
         end
       end
     end

data/lib/textus/doctor.rb

@@ -11,6 +11,7 @@ module Textus
     CHECKS = [
       Check::ManifestFiles,
       Check::Schemas,
+      Check::SchemaParseError,
       Check::Templates,
       Check::Hooks,
       Check::IntakeRegistration,
@@ -21,7 +22,6 @@ module Textus
       Check::SchemaViolations,
       Check::PolicyAmbiguity,
       Check::HandlerAllowlist,
-      Check::LegacyIntakeFields,
     ].freeze
 
     ALL_CHECKS = CHECKS.map(&:name_key).freeze

data/lib/textus/infra/publisher.rb

@@ -1,25 +1,21 @@
-require "json"
-require "digest"
 require "fileutils"
 
 module Textus
   module Infra
     # Publishes built artifacts from the store to repo-relative consumer paths.
     # Publish = copy + sentinel. The in-store file is already the consumer-shaped
-    # artifact; no parsing or stripping. Sentinels live under
+    # artifact; no parsing or stripping.
+    #
+    # Sentinel I/O is delegated to Store::Sentinel. Sentinels live under
     # `<store_root>/sentinels/` and mirror the target's repo-relative layout so
     # consumer directories aren't polluted with `.textus-managed.json` siblings.
     module Publisher
-      SENTINEL_SUFFIX = ".textus-managed.json".freeze
-      SENTINEL_DIR    = "sentinels".freeze
-
       def self.publish(source:, target:, store_root:)
         FileUtils.mkdir_p(File.dirname(target))
         refuse_if_unmanaged(target, store_root)
         File.delete(target) if File.symlink?(target)
         FileUtils.cp(source, target)
-        write_sentinel(target, store_root: store_root, source: source)
-        cleanup_legacy_sentinel(target)
+        Store::Sentinel.write!(target: target, source: source, store_root: store_root)
       end
 
       def self.refuse_if_unmanaged(target, store_root)
@@ -30,43 +26,7 @@ module Textus
       end
 
       def self.managed?(target, store_root)
-        File.exist?(sentinel_path(target, store_root)) || File.exist?(legacy_sentinel_path(target))
-      end
-
-      def self.write_sentinel(target, store_root:, source:)
-        path = sentinel_path(target, store_root)
-        FileUtils.mkdir_p(File.dirname(path))
-        File.write(path, JSON.generate(
-                           "source" => source,
-                           "target" => target,
-                           "sha256" => Digest::SHA256.hexdigest(File.binread(target)),
-                           "mode" => "copy",
-                         ))
-      end
-
-      # Sentinel layout: <store_root>/sentinels/<target_rel_to_repo>.textus-managed.json
-      # The full target extension is preserved so a marketplace.json and
-      # marketplace.yaml don't collide.
-      def self.sentinel_path(target, store_root)
-        repo_root = File.dirname(store_root)
-        rel = relative_to(target, repo_root) || File.basename(target)
-        File.join(store_root, SENTINEL_DIR, rel + SENTINEL_SUFFIX)
-      end
-
-      def self.legacy_sentinel_path(target)
-        target + SENTINEL_SUFFIX
-      end
-
-      def self.cleanup_legacy_sentinel(target)
-        FileUtils.rm_f(legacy_sentinel_path(target))
-      end
-
-      def self.relative_to(path, base)
-        path = File.expand_path(path)
-        base = File.expand_path(base)
-        return nil unless path.start_with?(base + File::SEPARATOR)
-
-        path[(base.length + 1)..]
+        File.exist?(Store::Sentinel.sentinel_path(target, store_root))
       end
     end
   end

data/lib/textus/manifest/entry.rb

@@ -28,10 +28,7 @@ module Textus
         @format = resolve_format!(raw["format"])
 
         validate_events!
-        raise UsageError.new("entry '#{@key}': 'source:' key renamed to 'intake:' in 0.9") if raw.key?("source")
-
         parse_intake!(raw["intake"])
-        reject_legacy_projection_keys!
         validate_format_matrix!
         validate_publish_each!
         validate_inject_intro!
@@ -57,9 +54,8 @@ module Textus
       end
 
       # Signal-based zone-kind predicates: derive the "kind" of a zone from its
-      # writable_by signals rather than its literal name. This keeps detection
-      # working when users rename the default zones (canon/intake/pending/derived
-      # → identity/inbox/review/output, etc.).
+      # writable_by signals rather than its literal name, so detection keeps
+      # working when users rename the default zones.
       def in_generator_zone?
         zone_writers.include?("build")
       end
@@ -68,12 +64,6 @@ module Textus
         zone_writers.include?("ai")
       end
 
-      # Legacy alias for in_generator_zone?. Retained because internal validation
-      # callers (and external tools) read more naturally as `derived?`.
-      def derived?
-        in_generator_zone?
-      end
-
       private
 
       def zone_writers
@@ -85,7 +75,7 @@ module Textus
       def validate_inject_intro!
         return unless @inject_intro
 
-        unless derived?
+        unless in_generator_zone?
           raise UsageError.new(
             "entry '#{@key}': inject_intro: is only valid on derived entries",
           )
@@ -181,7 +171,7 @@ module Textus
 
         # Template-required-for-derived rules. Skipped for entries materialized by an
         # external generator: command (those produce the bytes themselves).
-        if derived? && @template.nil? && @generator.nil? &&
+        if in_generator_zone? && @template.nil? && @generator.nil? &&
            (@format == "markdown" || @format == "text") && !@nested
           raise UsageError.new("entry '#{@key}': derived #{@format} entries require a template")
         end
@@ -189,26 +179,11 @@ module Textus
       # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
       def parse_intake!(src)
-        raise UsageError.new("entry '#{@key}': source.fetch renamed to intake.handler in 0.9") if src.is_a?(Hash) && src.key?("fetch")
-
-        if src.is_a?(Hash) && (src.key?("ttl") || src.key?("on_stale") || src.key?("sync_budget_ms"))
-          raise UsageError.new(
-            "entry '#{@key}': intake.ttl/intake.on_stale/intake.sync_budget_ms removed in 0.9.2 — " \
-            "move into a top-level policies: block (see CHANGELOG migration recipe).",
-          )
-        end
-
         src ||= {}
         @intake_handler = src["handler"]
         @intake_config  = src["config"] || {}
       end
 
-      def reject_legacy_projection_keys!
-        return unless @projection.is_a?(Hash) && @projection.key?("reducer")
-
-        raise UsageError.new("entry '#{@key}': projection.reducer renamed to projection.reduce in 0.6")
-      end
-
       def validate_events!
         pubsub_events = Hooks::Registry::EVENTS.select { |_, s| s[:mode] == :pubsub }.keys
         @events.each_key do |evt|

data/lib/textus/manifest.rb

@@ -34,12 +34,7 @@ module Textus
 
       raw = YAML.safe_load_file(manifest_path, aliases: false)
       unless raw["version"] == PROTOCOL
-        msg = if raw["version"] == "textus/1"
-                "manifest is textus/1; edit manifest.yaml: change 'version: textus/1' to 'version: #{PROTOCOL}'"
-              else
-                "unsupported manifest version #{raw["version"].inspect}"
-              end
-        raise BadFrontmatter.new(manifest_path, msg)
+        raise BadFrontmatter.new(manifest_path, "unsupported manifest version #{raw["version"].inspect}; expected #{PROTOCOL.inspect}")
       end
 
       new(root, raw)
@@ -50,7 +45,6 @@ module Textus
       @raw = raw
       raise BadFrontmatter.new(File.join(root, "manifest.yaml"), "manifest must declare zones:") if Array(raw["zones"]).empty?
 
-      reject_legacy_entry_intake_policy!(Array(raw["entries"]))
       @entries = Array(raw["entries"]).map { |e| Manifest::Entry.new(self, e) }
       validate_declared_keys!
     end
@@ -155,19 +149,6 @@ module Textus
       @entries.each { |e| validate_key!(e.key) }
     end
 
-    def reject_legacy_entry_intake_policy!(raw_entries)
-      raw_entries.each do |re|
-        intake = re["intake"]
-        next unless intake.is_a?(Hash)
-        next unless intake.key?("ttl") || intake.key?("on_stale") || intake.key?("sync_budget_ms")
-
-        raise UsageError.new(
-          "entry '#{re["key"]}': intake.ttl/intake.on_stale/intake.sync_budget_ms removed in 0.9.2 — " \
-          "move into a top-level policies: block (see CHANGELOG migration recipe).",
-        )
-      end
-    end
-
     def resolve_leaf_path(entry)
       Textus::Key::Path.resolve(self, entry)
     end

data/lib/textus/schema.rb

@@ -26,6 +26,16 @@ module Textus
       meta["maintained_by"]
     end
 
+    # Returns the list of field names whose spec is a Hash but lacks the
+    # 'maintained_by' key. Used by Doctor::Check::UnownedSchemaFields.
+    def unowned_fields
+      @fields.each_with_object([]) do |(name, spec), acc|
+        next unless spec.is_a?(Hash)
+
+        acc << name if spec["maintained_by"].nil?
+      end
+    end
+
     def evolution
       raw = @raw["evolution"] || {}
       raw.each_with_object({}) do |(k, v), h|

data/lib/textus/store/audit_log.rb

@@ -47,25 +47,38 @@ module Textus
         end
       end
 
+      # Returns an array of integrity-violation descriptors for the on-disk log.
+      # Each entry is { "lineno" => Integer, "reason" => String, "detail" => String }.
+      # Empty array means the log is well-formed (or doesn't exist yet).
+      def verify_integrity
+        return [] unless File.exist?(@path)
+
+        out = []
+        File.foreach(@path).with_index(1) do |line, lineno|
+          violation = check_line(line.chomp, lineno)
+          out << violation if violation
+        end
+        out
+      end
+
       private
 
       def parse_row(line)
         return nil if line.empty?
 
-        if line.start_with?("{")
-          JSON.parse(line)
-        else
-          # Legacy TSV (pre-0.5): read-only support retained for on-disk logs
-          # written by older textus versions. Never written by current code.
-          # Format: ts, role, verb, key, etag_before, etag_after [, json_extras]
-          fields = line.split("\t")
-          return nil if fields.length < 4
-
-          { "ts" => fields[0], "role" => fields[1], "verb" => fields[2], "key" => fields[3] }
-        end
+        JSON.parse(line)
       rescue JSON::ParserError
         nil
       end
+
+      def check_line(stripped, lineno)
+        return nil if stripped.empty?
+
+        JSON.parse(stripped)
+        nil
+      rescue JSON::ParserError => e
+        { "lineno" => lineno, "reason" => "invalid_json", "detail" => e.message }
+      end
     end
   end
 end

data/lib/textus/store/sentinel.rb

@@ -0,0 +1,86 @@
+require "json"
+require "digest"
+require "fileutils"
+
+module Textus
+  class Store
+    # Value object for sentinel files written by Infra::Publisher and inspected
+    # by Doctor::Check::Sentinels. Owns the JSON shape ({source, target,
+    # sha256, mode}) and the on-disk path layout (<store_root>/sentinels/
+    # <target-rel-to-repo>.textus-managed.json). Target/source are repo-relative
+    # when the published file is under the repo root, absolute otherwise.
+    class Sentinel
+      SUFFIX = ".textus-managed.json".freeze
+      DIR    = "sentinels".freeze
+
+      attr_reader :target, :source, :sha256, :mode
+
+      def self.write!(target:, source:, store_root:)
+        path = sentinel_path(target, store_root)
+        FileUtils.mkdir_p(File.dirname(path))
+        repo_root = File.dirname(store_root)
+        File.write(path, JSON.generate(
+                           "source" => rel_or_abs(source, repo_root),
+                           "target" => rel_or_abs(target, repo_root),
+                           "sha256" => Digest::SHA256.hexdigest(File.binread(target)),
+                           "mode" => "copy",
+                         ))
+      end
+
+      def self.load(path, repo_root)
+        raw = JSON.parse(File.read(path))
+        new(
+          target: absolutize(raw["target"], repo_root),
+          source: absolutize(raw["source"], repo_root),
+          sha256: raw["sha256"],
+          mode: raw["mode"],
+        )
+      rescue JSON::ParserError, Errno::ENOENT
+        nil
+      end
+
+      def self.sentinel_path(target, store_root)
+        repo_root = File.dirname(store_root)
+        rel = relative_to(target, repo_root) || File.basename(target)
+        File.join(store_root, DIR, rel + SUFFIX)
+      end
+
+      def self.rel_or_abs(path, repo_root)
+        relative_to(path, repo_root) || File.expand_path(path)
+      end
+
+      def self.relative_to(path, repo_root)
+        path = File.expand_path(path)
+        base = File.expand_path(repo_root)
+        return nil unless path.start_with?(base + File::SEPARATOR)
+
+        path[(base.length + 1)..]
+      end
+
+      def self.absolutize(path, repo_root)
+        return path if path.nil?
+        return path if File.absolute_path?(path)
+
+        File.expand_path(path, repo_root)
+      end
+
+      def initialize(target:, source:, sha256:, mode:)
+        @target = target
+        @source = source
+        @sha256 = sha256
+        @mode = mode
+      end
+
+      def orphan?
+        @target.nil? || !File.exist?(@target)
+      end
+
+      def drift?
+        return false if orphan?
+        return false if @sha256.nil?
+
+        Digest::SHA256.hexdigest(File.binread(@target)) != @sha256
+      end
+    end
+  end
+end

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.10.1"
+  VERSION = "0.10.3"
   PROTOCOL = "textus/2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: 0.10.3
 platform: ruby
 authors:
 - Patrick
@@ -175,9 +175,9 @@ files:
 - lib/textus/doctor/check/hooks.rb
 - lib/textus/doctor/check/illegal_keys.rb
 - lib/textus/doctor/check/intake_registration.rb
-- lib/textus/doctor/check/legacy_intake_fields.rb
 - lib/textus/doctor/check/manifest_files.rb
 - lib/textus/doctor/check/policy_ambiguity.rb
+- lib/textus/doctor/check/schema_parse_error.rb
 - lib/textus/doctor/check/schema_violations.rb
 - lib/textus/doctor/check/schemas.rb
 - lib/textus/doctor/check/sentinels.rb
@@ -233,6 +233,7 @@ files:
 - lib/textus/store/audit_log.rb
 - lib/textus/store/mover.rb
 - lib/textus/store/reader.rb
+- lib/textus/store/sentinel.rb
 - lib/textus/store/staleness.rb
 - lib/textus/store/validator.rb
 - lib/textus/store/writer.rb

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

@@ -1,57 +0,0 @@
-require "yaml"
-
-module Textus
-  module Doctor
-    class Check
-      # Scans the raw manifest YAML for entry-level intake.ttl /
-      # intake.on_stale / intake.sync_budget_ms keys. Manifest parsing
-      # already raises on these in 0.9.2 — this check exists for the case
-      # where doctor is run against a problem manifest separately (e.g. CI
-      # lint or an exploration session that loads the YAML directly).
-      class LegacyIntakeFields < Check
-        LEGACY_KEYS = %w[ttl on_stale sync_budget_ms].freeze
-
-        def call
-          out = []
-          path = File.join(store.root, "manifest.yaml")
-          return out unless File.exist?(path)
-
-          raw = safe_load(path)
-          return out unless raw.is_a?(Hash)
-
-          Array(raw["entries"]).each do |entry|
-            next unless entry.is_a?(Hash)
-
-            intake = entry["intake"]
-            next unless intake.is_a?(Hash)
-
-            offending = LEGACY_KEYS.select { |k| intake.key?(k) }
-            next if offending.empty?
-
-            out << issue_for(entry["key"], offending)
-          end
-          out
-        end
-
-        private
-
-        def safe_load(path)
-          YAML.load_file(path)
-        rescue StandardError
-          nil
-        end
-
-        def issue_for(key, fields)
-          {
-            "code" => "manifest.legacy_intake_fields",
-            "level" => "error",
-            "subject" => key.to_s,
-            "message" => "entry '#{key}' carries legacy intake.#{fields.join(", intake.")} " \
-                         "(removed in 0.9.2 — freshness lives in top-level policies:)",
-            "fix" => "hand-edit these into a top-level policies: block (see CHANGELOG migration recipe)",
-          }
-        end
-      end
-    end
-  end
-end