textus 0.35.1 → 0.39.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.35.1
+  version: 0.39.0
 platform: ruby
 authors:
 - Patrick
@@ -93,8 +93,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
-description: Storage convention and JSON wire protocol for agent-readable project
-  memory.
+description: A coordination space for humans, AI, and automation. Durable, multi-writer
+  project memory where each actor writes into its own lane, proposals cross a review
+  queue, and every change is audited.
 email:
 - patrick204nqh@gmail.com
 executables:
@@ -106,7 +107,6 @@ files:
 - CHANGELOG.md
 - README.md
 - SPEC.md
-- docs/conventions.md
 - exe/textus
 - lib/textus.rb
 - lib/textus/boot.rb
@@ -147,6 +147,7 @@ files:
 - lib/textus/cli/verb/mcp_serve.rb
 - lib/textus/cli/verb/migrate.rb
 - lib/textus/cli/verb/mv.rb
+- lib/textus/cli/verb/propose.rb
 - lib/textus/cli/verb/published.rb
 - lib/textus/cli/verb/pulse.rb
 - lib/textus/cli/verb/put.rb
@@ -164,6 +165,8 @@ files:
 - lib/textus/cli/verb/where.rb
 - lib/textus/cli/verb/zone_mv.rb
 - lib/textus/container.rb
+- lib/textus/contract.rb
+- lib/textus/cursor_store.rb
 - lib/textus/dispatcher.rb
 - lib/textus/doctor.rb
 - lib/textus/doctor/check.rb
@@ -234,6 +237,7 @@ files:
 - lib/textus/key/distance.rb
 - lib/textus/key/grammar.rb
 - lib/textus/key/path.rb
+- lib/textus/layout.rb
 - lib/textus/maintenance.rb
 - lib/textus/maintenance/key_delete_prefix.rb
 - lib/textus/maintenance/key_mv_prefix.rb
@@ -246,6 +250,7 @@ files:
 - lib/textus/manifest/entry.rb
 - lib/textus/manifest/entry/base.rb
 - lib/textus/manifest/entry/derived.rb
+- lib/textus/manifest/entry/ignore_matcher.rb
 - lib/textus/manifest/entry/intake.rb
 - lib/textus/manifest/entry/leaf.rb
 - lib/textus/manifest/entry/nested.rb
@@ -253,6 +258,7 @@ files:
 - lib/textus/manifest/entry/validators.rb
 - lib/textus/manifest/entry/validators/events.rb
 - lib/textus/manifest/entry/validators/format_matrix.rb
+- lib/textus/manifest/entry/validators/ignore.rb
 - lib/textus/manifest/entry/validators/index_filename.rb
 - lib/textus/manifest/entry/validators/inject_boot.rb
 - lib/textus/manifest/entry/validators/publish_each.rb
@@ -261,6 +267,7 @@ files:
 - lib/textus/manifest/rules.rb
 - lib/textus/manifest/schema.rb
 - lib/textus/mcp.rb
+- lib/textus/mcp/catalog.rb
 - lib/textus/mcp/errors.rb
 - lib/textus/mcp/server.rb
 - lib/textus/mcp/session.rb
@@ -292,6 +299,7 @@ files:
 - lib/textus/read/pulse.rb
 - lib/textus/read/rdeps.rb
 - lib/textus/read/retainable.rb
+- lib/textus/read/rules.rb
 - lib/textus/read/schema_envelope.rb
 - lib/textus/read/stale.rb
 - lib/textus/read/uid.rb
@@ -303,6 +311,7 @@ files:
 - lib/textus/schema.rb
 - lib/textus/schema/tools.rb
 - lib/textus/schemas.rb
+- lib/textus/session.rb
 - lib/textus/store.rb
 - lib/textus/uid.rb
 - lib/textus/version.rb
@@ -314,6 +323,7 @@ files:
 - lib/textus/write/intake_fetch.rb
 - lib/textus/write/materializer.rb
 - lib/textus/write/mv.rb
+- lib/textus/write/propose.rb
 - lib/textus/write/publish.rb
 - lib/textus/write/put.rb
 - lib/textus/write/reject.rb
@@ -344,5 +354,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Reference implementation of the textus/1 protocol.
+summary: Reference implementation of the textus/3 protocol.
 test_files: []

data/docs/conventions.md

@@ -1,148 +0,0 @@
-# Conventions
-
-> **Reference** · for integrators · **read when** you're shaping a `.textus/` tree and want the idiomatic choices
-> **SSoT for** idiomatic key naming, schema design, and automation integration · **reviewed** 2026-05 (v0.31)
-
-Guidelines for shaping a `.textus/` tree, naming keys, organising schemas, and integrating with build automation. The spec ([`../SPEC.md`](../SPEC.md)) defines what's enforceable; this document captures what's *idiomatic*.
-
-## Key naming
-
-- **Segments are lowercase, kebab- or snake-case.** The grammar `^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$` is the hard limit. Prefer `acme-dashboard` over `acmedashboard` when there's a natural word break.
-- **Lead with the zone in the key path.** `working.projects.acme.dashboard`, not `projects.acme.dashboard`. The zone prefix makes it obvious from the key alone whether a write will be accepted.
-- **Mirror the directory structure.** If `working.projects.acme.dashboard` resolves to `working/projects/acme/dashboard.md`, do not invent shortcuts that diverge.
-- **Don't pluralise the leaf.** `working.network.org.jane`, not `working.network.org.janes`. Pluralise the container, not the entry.
-
-## Zone layout
-
-Recommended top-level layout — the spec allows alternatives, but this is what tooling will default to:
-
-```
-.textus/
-  manifest.yaml
-  schemas/        # YAML schema definitions
-  zones/
-    knowledge/    # authored truth: identity, voice, decisions — author-holders write
-    notebook/     # agent's own durable lane (workspace) — keep-holders write
-    feeds/        # automation-fed external inputs (fetch)
-    proposals/    # AI proposals awaiting accept (propose)
-    artifacts/    # generated by build automation — never edit by hand
-```
-
-Inside `knowledge/`, group by **domain** (identity, people, projects, decisions, runbooks), not by file type or date. `knowledge.identity.*` is the convention for slow-changing identity facts. Inside `artifacts/`, group by **producer** (`artifacts/catalogs/`, `artifacts/indexes/`) so it's clear which build job owns what.
-
-## Schema design
-
-- **One schema per entry type, not per directory.** `person.yaml`, `project.yaml`, `decision.yaml` — applied across multiple subtrees if the shape matches.
-- **Required = "this entry is meaningless without it."** Everything else is `optional`. Resist the urge to mark organisational metadata (like `tags`) required.
-- **Prefer `enum` over free-text** for low-cardinality fields (relationship type, status, severity). Agents are far better at picking from a list than at producing exact strings.
-- **Cap string lengths** with `max:` where the field has a natural bound (names, summaries). Skip for prose body — bodies are not schema-validated, only frontmatter is.
-
-## Owner strings
-
-The `owner:` field in the manifest is **advisory metadata**, not an ACL. Use it to label *who's expected to write here*:
-
-- `textus:network` — humans curate
-- `agent:planner` — a specific named agent
-- `build:catalog-skills` — a specific build job
-
-Tooling around `git blame` or audit logs may filter on owner; the gem itself only echoes it back in envelopes.
-
-## Derived entries
-
-A derived entry declares a `compute:` block with a `kind:` discriminator. Two kinds:
-
-**`compute: { kind: projection }`** — textus computes the entry on `textus build` from other store entries. Declarative; nothing shells out.
-
-```yaml
-- key: artifacts.catalogs.people
-  path: artifacts/catalogs/people.md
-  zone: artifacts
-  schema: null
-  owner: build:catalog-people
-  compute:
-    kind: projection
-    select: knowledge.network.org   # prefix or list of prefixes
-    pluck:  [name, relationship, org]
-    sort_by: name
-  template: people.mustache         # under .textus/templates/
-  publish_to: [docs/people.md]      # optional repo-relative byte-copy targets
-```
-
-**`compute: { kind: external }`** — an external build tool (rake, just, a shell script) produces the file. textus never executes the `command:`; it only tracks `sources:` so `textus freshness` can compare source mtimes against the file's `_meta.generated.at`. The role running the build must hold `build` (default: `automation`).
-
-```yaml
-- key: artifacts.catalogs.skills
-  path: artifacts/catalogs/skills.md
-  zone: artifacts
-  owner: build:catalog-skills
-  compute:
-    kind: external
-    command: "rake catalog:skills"   # informational; the automation invokes it
-    sources: [knowledge.projects, knowledge.network]
-```
-
-The build automation is responsible for writing the `generated:` frontmatter block (`by`, `at`, `from`) when it produces the file. `generated.from` SHOULD match `compute.sources` — same list, recorded twice so a diff proves what was consumed.
-
-Full contract for both shapes is in [`../SPEC.md` §5.2.1 and §5.2.2](../SPEC.md). Transforms (`compute.transform:`) and per-leaf publishing (`publish_each:`) are also covered there.
-
-## Intake and freshness
-
-External inputs land via `:resolve_intake` hooks, not shell commands. Each intake entry names a registered handler; fetch is on demand:
-
-```sh
-textus fetch feeds.notion.roadmap --as=automation
-textus fetch stale --zone=feeds --as=automation   # everything past its TTL
-```
-
-Freshness budgets live in the top-level `rules:` block, matched by glob:
-
-```yaml
-rules:
-  - match: feeds.notion.**
-    fetch: { ttl: 6h, on_stale: warn }   # warn | sync | timed_sync
-```
-
-A typical scheduled-fetch integration shells the `fetch stale` sweep itself:
-
-```sh
-textus fetch stale --zone=intake --as=automation   # in cron / CI
-```
-
-See [`./zones.md` §6](zones.md) for the full intake contract and [`./events.md`](events.md) for writing custom handlers.
-
-### Read vs. fetch
-
-There are two read operations, and the difference matters in custom code:
-
-| Operation | Triggers fetch? | Use for |
-|-----------|-----------------|---------|
-| `ops.get` | No — pure read of on-disk envelope + freshness verdict | build / materialization paths, schema tooling, any context where a side-effecting read would surprise the caller |
-| `ops.get_or_fetch` | Yes — composes `get` with the orchestrator per the rule's `on_stale` policy | interactive reads (`textus get`, dashboards) where the caller wants the freshest envelope obtainable |
-
-Build always uses the pure path; injecting fetch into materialization caused the cascading-staleness incident behind issue #59. Pick `get_or_fetch` only when you genuinely want side effects on read.
-
-## Body content
-
-- **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. `working.projects.acme.dashboard` + `working.projects.acme.api`) rather than one mega-document.
-
-## Concurrency
-
-For multi-writer environments, **always pass `if_etag`** on `put`. The gem treats etag-less writes as last-writer-wins on purpose (single-writer scripts, fresh-file creation), but anything resembling a daemon or a long-running agent should round-trip the etag.
-
-## Application layering
-
-The application layer is organised around three shapes — `Manifest` as a composition record, a single `Container` capability record handed to every use case, and a split envelope reader/writer. See [ADR 0018](architecture/decisions/0018-manifest-carving.md), [ADR 0017](architecture/decisions/0017-envelope-io-split.md), [ADR 0022](architecture/decisions/0022-container-call-dispatcher.md), and [ADR 0023](architecture/decisions/0023-uniform-use-case-shape.md).
-
-- **`Manifest` is a composition record** (`Data.define(:data, :resolver, :policy, :rules)`). Reach individual concerns through the field accessors: `manifest.data.entries`, `manifest.policy.permission_for(zone)`, `manifest.resolver.resolve(key)`, `manifest.rules.for(key)`.
-- **Use cases are plain `(container:, call:)` classes.** Each is a single class under `lib/textus/{read,write,maintenance}/` with `def initialize(container:, call:)` and a `#call(...)` method; verbs are looked up in the static `Textus::Dispatcher::VERBS` table. `Container` is a `Data.define` record bundling the wired ports + manifest (`manifest`, `file_store`, `schemas`, `root`, `audit_log`, `events`, `rpc`, `authorizer`); `Call` is the immutable per-invocation value (`role`, `correlation_id`, `now`, `dry_run`). A use case that emits events derives its `Hooks::Context` from `(container, call)` — nothing is injected. Use cases pull only what they need into ivars; nobody passes the raw `Store` around the application layer. `store.as(role)` returns a `RoleScope` that forwards verbs to the dispatcher.
-- **Write path is split**: `Envelope::IO::Reader` owns read/parse (existing-uid lookup, raw read, parse), and `Envelope::IO::Writer` owns put/delete/move + the audit-append invariant (every public method's final action is `@audit_log.append(...)`).
-
-The user-facing CLI surface, the wire envelope shape, and the protocol version (`textus/3`) are unchanged.
-
-## Pairing with other tools
-
-- **MCP servers**: a thin server that exposes `textus get` and `textus put` as tools is the recommended way to give Claude/agents access. Don't bake MCP into this gem.
-- **Vector stores**: index `body` content into a vector store if you want fuzzy retrieval. `frontmatter` stays in textus as the source of truth for deterministic facts.
-- **CI**: run `textus freshness` (or `textus list` + schema validation) in CI to catch drift between derived entries and their sources.