@shanepadgett/tau-agent 0.17.0 → 0.18.1

package/README.md

@@ -25,6 +25,7 @@ pi -e .
 
 ## Docs
 
+- [Context management](./docs/context.md) — repository context structure and taxonomy
 - [Extending Tau Agent](./docs/extending-tau-agent.md) — public events and integration
 - [Subagents](./docs/subagents.md) — custom agent definitions
 - [TUI](./docs/tui.md) — shared UI components

package/docs/context.md

@@ -0,0 +1,62 @@
+# Context management
+
+Tau uses `.pi/contexts` as a reusable map of the repository. A selected context gives an agent the primary files for a work scope and points it toward related files without loading everything.
+
+## Structure
+
+The catalog has three levels:
+
+```text
+.pi/contexts/<domain>/<concept>.toml
+                         └── [entry]
+```
+
+- **Domain**: a stable top-level area of the repository, such as `commerce`, `platform`, or `documentation`. Domains become tabs in `/context`.
+- **Concept**: a coherent subsystem or capability inside a domain. Each concept is one TOML file.
+- **Entry**: a selectable work scope inside that concept. Each TOML section defines one entry.
+
+Domain folders, concept filenames, and entry section names use lowercase kebab-case.
+
+```toml
+name = "Checkout"
+description = "Checkout calculation and order submission"
+
+[orchestration]
+description = "Building and submitting a checkout order"
+files = ["src/checkout/order.ts", "src/checkout/service.ts"]
+anchors = ["test/checkout/service.test.ts", "src/payments/client.ts"]
+
+[discounts]
+description = "Applying coupons and account discounts"
+files = ["src/checkout/discounts.ts"]
+anchors = ["test/checkout/discounts.test.ts"]
+```
+
+Saved as `.pi/contexts/commerce/checkout.toml`, these entries have the IDs `commerce/checkout/orchestration` and `commerce/checkout/discounts`.
+
+## Build a useful taxonomy
+
+A good entry gives the agent enough primary code to start one recurring kind of work without flooding its context window. Classify each scope from the top down:
+
+1. **Domain:** Which stable product or technical area owns this work?
+2. **Concept:** Which subsystem inside that area has a clear shared purpose?
+3. **Entry:** Which files are commonly needed together for one task?
+
+Reuse existing terms when they still describe the code honestly. Create, move, split, or merge taxonomy when ownership or subsystem boundaries change. Directory layout can inform the decision, though domains and concepts should describe responsibility rather than copy the source tree.
+
+Keep entries focused. Names such as `misc`, `shared`, and `other` hide missing boundaries. A broad `all` entry can support deliberate subsystem-wide work, but focused entries should remain available for normal tasks. If an entry keeps collecting unrelated paths, split it by work scope. If several tiny entries are always selected together, merge them.
+
+Catalog durable code, configuration, tests, standards, and long-lived documentation. Leave scratch files, working plans, interviews, generated output, and rough ideas out of the catalog.
+
+## Choose files and anchors
+
+- `files` are eagerly read when the entry is selected. Include primary files that are usually required for that scope.
+- `anchors` are shown to the agent as unloaded navigation paths. Use them for related tests, callers, shared dependencies, or documentation that is useful only for some tasks.
+
+Keep the eager set small enough to read on every selection. Keep each path's loading class consistent across the catalog. If selected entries classify the same path differently, eager loading wins.
+
+## Maintain the map
+
+Inspect the existing catalog before placing new paths. Re-evaluate domain, concept, and entry boundaries after moves, ownership changes, or a coherent batch of new work; avoid stuffing paths into the nearest existing bucket.
+
+Run `/context-sync` to update the catalog from uncommitted repository changes. Tau can also delegate to the `context-sync` subagent when automation is enabled. Context sync checks every eligible changed file for membership, removes stale paths, and re-evaluates the taxonomy before editing `.pi/contexts`.

package/extensions/context/README.md

@@ -2,9 +2,11 @@
 
 Context stores reusable repository work scopes in `.pi/contexts`. Folder names become selector tabs, TOML files become concepts, and TOML sections become selectable entries.
 
+See [Context management](../../docs/context.md) for catalog structure and taxonomy guidance.
+
 Use `/context` to select entries. Entry `files` are injected through Tau autoread. Entry `anchors` supply lazy navigation paths that the agent can grep or read in ranges when needed.
 
-After meaningful uncommitted work (new/moved ownership, not trivial already-covered polish), the coding agent should run the `context-sync` subagent so `.pi/contexts` stays aligned. Humans can also run `/context-sync` or `/context-sync <nudge>` and press Escape to cancel a running sync. It walks domain → concept → entry → membership, edits only `.pi/contexts` with `patch`, and the harness verifies write scope plus catalog invariants afterward. Out-of-scope writes are restored and the run fails. Optional nudge text soft-steers judgment without skipping evidence.
+After meaningful uncommitted work (new/moved ownership, not trivial already-covered polish), the coding agent should run the `context-sync` subagent so `.pi/contexts` stays aligned. Context sync catalogs durable code and long-lived documentation. Scratch pads, working plans, interviews, rough ideas, and other temporary artifacts should stay out; add recurring transient paths to `validation.ignoreGlobs`. Humans can also run `/context-sync` or `/context-sync <nudge>` and press Escape to cancel a running sync. It walks domain → concept → entry → membership, edits only `.pi/contexts` with `patch`, and the harness verifies write scope plus catalog invariants afterward. Out-of-scope writes are restored and the run fails. Optional nudge text soft-steers judgment without skipping evidence.
 
 Sync surface is configurable:
 

package/extensions/subagent/agents/context-sync.md

@@ -1,7 +1,8 @@
 ---
 name: context-sync
 description: >-
-  Map meaningful uncommitted work into `.pi/contexts` (domains/concepts/entries).
+  Map durable uncommitted code and long-lived documentation into `.pi/contexts` (domains/concepts/entries).
+  Skip scratch pads, working plans, interviews, rough ideas, and other temporary artifacts; ensure recurring transient paths are excluded by `extensions.context.validation.ignoreGlobs` before calling.
   Call after a coherent batch that adds, moves, renames, or changes ownership of code/docs—not after every trivial edit to paths already correctly filed.
   Prefer once per batch or before commit; skip pure refactors that keep the same membership, typos, and already-covered single-file polish.
   Task may include a short human/steer note. Harness may also auto-run this when context validation is enabled.
@@ -54,6 +55,12 @@ Forbidden with bash:
 
 Catalog file mutations go through `patch` under `.pi/contexts` only. The harness restores out-of-scope writes and fails the run.
 
+## Durability gate
+
+Catalog durable repository material: code, configuration, tests, standards, and documentation expected to remain useful after the current work finishes.
+
+Do not catalog scratch pads, working plans, interview notes, rough ideas, or other temporary artifacts. Recurring transient paths belong in the parent project's `extensions.context.validation.ignoreGlobs`. The parent owns settings; if an uncovered transient path is not ignored, leave it out of the catalog and report the exact ignore glob needed instead of forcing it into an entry.
+
 ## Forced ladder
 
 Before placing any path, answer out loud in order:

package/extensions/tau-help/help.md

@@ -28,7 +28,7 @@ Adds `/commit` for semantic commit grouping, review, and committing selected rep
 
 ## context
 
-Adds `/context` to select reusable repository work scopes from `.pi/contexts`, and `/context-sync` or `/context-sync <nudge>` for human-driven catalog sync (optional nudge). Escape cancels a running manual sync. When `sync.automation` is on, the coding agent can also run the `context-sync` subagent after meaningful uncommitted work. `sync.enabled` is the master switch for command, automation, and validation auto-run. Entry `files` are autoread; entry `anchors` are unloaded navigation paths. Context validation is off by default; when on (and sync enabled), Tau auto-runs context-sync on failure. Folder names are tabs, TOML files are concepts, and TOML sections are selectable entries.
+Adds `/context` to select reusable repository work scopes from `.pi/contexts`, and `/context-sync` or `/context-sync <nudge>` for human-driven catalog sync (optional nudge). Escape cancels a running manual sync. When `sync.automation` is on, the coding agent can also run the `context-sync` subagent after meaningful uncommitted work. Sync catalogs durable code and long-lived documentation; recurring scratch, planning, interview, and rough-idea paths belong in `validation.ignoreGlobs`. `sync.enabled` is the master switch for command, automation, and validation auto-run. Entry `files` are autoread; entry `anchors` are unloaded navigation paths. Context validation is off by default; when on (and sync enabled), Tau auto-runs context-sync on failure. Folder names are tabs, TOML files are concepts, and TOML sections are selectable entries.
 
 ## context-pruning
 

package/extensions/tau-help/index.ts

@@ -7,7 +7,7 @@ import { Markdown, type Component, visibleWidth } from "@earendil-works/pi-tui";
 const TAU_DOCS_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "docs");
 const TAU_DOCS_GUIDANCE = `Tau Agent documentation (read only when the user asks about Tau Agent, Rok, Tau extensions, Tau event APIs, harness behavior, or extending Tau Agent):
 - Tau Agent docs: ${TAU_DOCS_PATH}
-- When asked about: public events / external integration (docs/extending-tau-agent.md), custom subagents (docs/subagents.md), Tau TUI components (docs/tui.md)
+- When asked about: context management / .pi/contexts taxonomy (docs/context.md), public events / external integration (docs/extending-tau-agent.md), custom subagents (docs/subagents.md), Tau TUI components (docs/tui.md)
 - Resolve Tau docs/... under Tau Agent docs, not the current working directory
 - When working on Tau topics, read the docs and follow .md cross-references before implementing
 - Do not read Tau Agent docs for normal coding tasks`;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shanepadgett/tau-agent",
-	"version": "0.17.0",
+	"version": "0.18.1",
 	"description": "Tau is a custom agentic harness built with pi extensions",
 	"type": "module",
 	"license": "MIT",
@@ -28,7 +28,7 @@
 		"README.md"
 	],
 	"dependencies": {
-		"@shanepadgett/tau-tui": "0.17.0",
+		"@shanepadgett/tau-tui": "0.18.1",
 		"@toon-format/toon": "2.3.0",
 		"smol-toml": "1.7.0"
 	},