@shanepadgett/tau-agent 0.33.1 → 0.35.0

package/extensions/context/README.md

@@ -1,12 +1,12 @@
 # Context
 
-Context stores reusable repository work scopes in `.pi/contexts`. Folder names become selector tabs, TOML files become concepts, and TOML sections become selectable entries.
+Context stores reusable repository work scopes in `.pi/contexts`. Domain folders use `NN_slug` (`01_extensions`, `02_core`, …) so `/context` can order tabs; the UI shows the slug only. 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 set active entries for the current session branch. Tau stores only the selected entry IDs. Before each model call it rebuilds one ephemeral projection from current files, so repeated selections do not accumulate snapshots in conversation history. Open `/context`, press `Ctrl+C`, then confirm to clear active context.
+Use `/context` to inject entries into the conversation. Selecting entries reads `read` paths in full, resolves `show` targets to current declaration slices, outlines `outline` paths, and adds one hidden note listing `references` and instructing the agent to treat the injected material as current. Injection happens once, immediately, before your next prompt; nothing is rebuilt on later model calls. Prefer complete reads for bounded work files; use `show` for thin contracts from larger neighbors; reserve `outline` for large or noisy files.
 
-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.
+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 as **work packs** (job-shaped entries an agent can start from), not bare path indexes. 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>`; the command replaces the editor with a status panel (Escape / Ctrl+C cancel). It uses normal repo tools, walks domain → concept → entry → start-pack modes, and prefers `patch` under `.pi/contexts`. The harness verifies catalog coverage afterward. Optional nudge text soft-steers judgment (including quality rewrites of weak bags) without skipping the ladder or coverage.
 
 Sync surface is configurable:
 
@@ -37,15 +37,19 @@ description = "Player-owned gameplay systems"
 
 [input]
 description = "Input mapping and command handling"
-read = []
-outline = ["src/player/input.ts"]
+read = ["src/player/input.ts"]
+show = []
+outline = []
 references = []
 
 [movement]
 description = "Player locomotion and collision"
-read = []
-outline = ["src/player/movement.ts"]
+read = ["src/player/movement.ts"]
+show = [
+  { path = "src/runtime/fetch-handler.ts", name = "handleFetch" },
+]
+outline = []
 references = ["src/runtime/fetch-handler.ts"]
 ```
 
-Every entry must declare all three loading arrays. `read` supplies exact complete contents, `outline` asks Explore for current structural outlines, and `references` lists unloaded paths. If selected entries classify the same path differently, precedence is `read`, then `outline`, then `references`.
+Every entry must declare all four loading arrays. `read` supplies exact complete contents, `show` resolves path+name declaration slices, `outline` asks Explore for structural outlines, and `references` lists unloaded paths. If selected entries classify the same path differently, precedence is `read`, then `show`, then `outline`, then `references`.

package/extensions/context/definitions.ts

@@ -4,6 +4,14 @@ import { basename, dirname, extname, join, relative, resolve, sep } from "node:p
 import { parse } from "smol-toml";
 import { matchGlob } from "../../shared/glob.ts";
 
+export type ContextShowView = "signature" | "signatureWithDocs" | "declaration" | "declarationWithImports";
+
+export interface ContextShowTarget {
+	path: string;
+	name: string;
+	view: ContextShowView;
+}
+
 export interface ContextEntry {
 	id: string;
 	tab: string;
@@ -13,6 +21,7 @@ export interface ContextEntry {
 	name: string;
 	description: string;
 	read: string[];
+	show: ContextShowTarget[];
 	outline: string[];
 	references: string[];
 	path: string;
@@ -38,7 +47,14 @@ const CONTEXT_IGNORED_FILENAMES = new Set([
 	"uv.lock",
 	"yarn.lock",
 ]);
-const CONTEXT_ENTRY_FIELDS = new Set(["description", "read", "outline", "references"]);
+const CONTEXT_ENTRY_FIELDS = new Set(["description", "read", "show", "outline", "references"]);
+const CONTEXT_SHOW_VIEWS = new Set<ContextShowView>([
+	"signature",
+	"signatureWithDocs",
+	"declaration",
+	"declarationWithImports",
+]);
+const CONTEXT_SHOW_TARGET_FIELDS = new Set(["path", "name", "view"]);
 
 export function isContextEligiblePath(path: string, ignoreGlobs: readonly string[] = []): boolean {
 	return (
@@ -84,12 +100,48 @@ export async function findProjectRoot(cwd: string): Promise<string> {
 	return gitRoot ?? resolve(cwd);
 }
 
+const TAB_FOLDER_PATTERN = /^(\d{2})_([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+
 function validSlug(value: string, label: string): string {
 	const slug = value.trim();
 	if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) throw new Error(`${label} must use lowercase kebab-case: ${value}`);
 	return slug;
 }
 
+/** Domain folder: `01_extensions` → order 1, tab slug `extensions` (id/label). */
+function parseContextTabFolder(name: string): { order: number; slug: string; folder: string } {
+	const match = TAB_FOLDER_PATTERN.exec(name);
+	const digits = match?.[1];
+	const slug = match?.[2];
+	if (!match || digits === undefined || slug === undefined) {
+		throw new Error(
+			`Context tab folder must be NN_kebab-slug with a two-digit order starting at 01 (e.g. 01_extensions): ${name}`,
+		);
+	}
+	const order = Number(digits);
+	if (!Number.isInteger(order) || order < 1 || order > 99) {
+		throw new Error(`Context tab order must be an integer from 01 to 99: ${name}`);
+	}
+	return { order, slug, folder: name };
+}
+
+function assertContiguousTabOrders(tabs: readonly { order: number; slug: string; folder: string }[]): void {
+	const byOrder = [...tabs].sort((left, right) => left.order - right.order);
+	const seenSlugs = new Set<string>();
+	for (let index = 0; index < byOrder.length; index++) {
+		const tab = byOrder[index];
+		if (!tab) continue;
+		const expected = index + 1;
+		if (tab.order !== expected) {
+			throw new Error(
+				`Context tab orders must be contiguous from 01 (expected ${String(expected).padStart(2, "0")}_…, found ${tab.folder})`,
+			);
+		}
+		if (seenSlugs.has(tab.slug)) throw new Error(`Duplicate context tab slug: ${tab.slug}`);
+		seenSlugs.add(tab.slug);
+	}
+}
+
 function normalizeProjectPath(root: string, input: string): string {
 	const absolute = resolve(root, input.trim().replace(/^@/, ""));
 	const path = relative(root, absolute).split(sep).join("/");
@@ -102,8 +154,126 @@ function sortedUnique(values: readonly string[]): string[] {
 	return [...new Set(values)].sort((a, b) => a.localeCompare(b));
 }
 
-export function contextEntryPaths(entry: Pick<ContextEntry, "read" | "outline" | "references">): string[] {
-	return sortedUnique([...entry.read, ...entry.outline, ...entry.references]);
+export function contextEntryPaths(entry: Pick<ContextEntry, "read" | "show" | "outline" | "references">): string[] {
+	return sortedUnique([
+		...entry.read,
+		...entry.show.map((target) => target.path),
+		...entry.outline,
+		...entry.references,
+	]);
+}
+
+function parseOneShowTarget(root: string, catalogPath: string, entryName: string, item: unknown): ContextShowTarget {
+	const record = item as Record<string, unknown>;
+	const unknownField = Object.keys(record).find((field) => !CONTEXT_SHOW_TARGET_FIELDS.has(field));
+	if (unknownField) throw new Error(`Invalid context show field: ${catalogPath} [${entryName}] ${unknownField}`);
+	if (typeof record.path !== "string" || !record.path.trim() || typeof record.name !== "string" || !record.name.trim())
+		throw new Error(`Invalid context show target: ${catalogPath} [${entryName}]`);
+	let view: ContextShowView = "declaration";
+	if (record.view !== undefined) {
+		if (typeof record.view !== "string" || !CONTEXT_SHOW_VIEWS.has(record.view as ContextShowView))
+			throw new Error(`Invalid context show view: ${catalogPath} [${entryName}] ${String(record.view)}`);
+		view = record.view as ContextShowView;
+	}
+	return {
+		path: normalizeProjectPath(root, record.path),
+		name: record.name.trim(),
+		view,
+	};
+}
+
+function dedupeShowTargets(catalogPath: string, entryName: string, targets: ContextShowTarget[]): ContextShowTarget[] {
+	const seen = new Map<string, ContextShowTarget>();
+	for (const target of targets) {
+		const key = `${target.path}\0${target.name}`;
+		const existing = seen.get(key);
+		if (existing && existing.view !== target.view)
+			throw new Error(
+				`Context show target has multiple views: ${catalogPath} [${entryName}] ${target.path} ${target.name}`,
+			);
+		if (!existing) seen.set(key, target);
+	}
+	return [...seen.values()].sort(
+		(left, right) => left.path.localeCompare(right.path) || left.name.localeCompare(right.name),
+	);
+}
+
+function parseShowTargets(root: string, catalogPath: string, entryName: string, raw: unknown): ContextShowTarget[] {
+	if (!Array.isArray(raw) || raw.some((item) => !item || typeof item !== "object" || Array.isArray(item)))
+		throw new Error(`Invalid context entry show list: ${catalogPath} [${entryName}]`);
+	return dedupeShowTargets(
+		catalogPath,
+		entryName,
+		raw.map((item) => parseOneShowTarget(root, catalogPath, entryName, item)),
+	);
+}
+
+function parseContextEntryRecord(
+	root: string,
+	path: string,
+	tab: string,
+	concept: string,
+	conceptName: string,
+	conceptDescription: string,
+	name: string,
+	value: unknown,
+): ContextEntry {
+	if (!value || typeof value !== "object" || Array.isArray(value))
+		throw new Error(`Invalid context entry: ${path} [${name}]`);
+	const record = value as Record<string, unknown>;
+	const unknownField = Object.keys(record).find((field) => !CONTEXT_ENTRY_FIELDS.has(field));
+	if (unknownField) throw new Error(`Invalid context entry field: ${path} [${name}] ${unknownField}`);
+	if (
+		typeof record.description !== "string" ||
+		!record.description.trim() ||
+		!Array.isArray(record.read) ||
+		record.read.some((item) => typeof item !== "string") ||
+		!Array.isArray(record.outline) ||
+		record.outline.some((item) => typeof item !== "string") ||
+		!Array.isArray(record.references) ||
+		record.references.some((item) => typeof item !== "string")
+	)
+		throw new Error(`Invalid context entry: ${path} [${name}]`);
+	const entry = validSlug(name, "Context entry");
+	const entryRead = sortedUnique((record.read as string[]).map((item) => normalizeProjectPath(root, item)));
+	const entryShow = parseShowTargets(root, path, name, record.show ?? []);
+	const entryOutline = sortedUnique((record.outline as string[]).map((item) => normalizeProjectPath(root, item)));
+	const entryReferences = sortedUnique(
+		(record.references as string[]).map((item) => normalizeProjectPath(root, item)),
+	);
+	if (entryRead.length === 0 && entryShow.length === 0 && entryOutline.length === 0 && entryReferences.length === 0)
+		throw new Error(`Invalid context entry: ${path} [${name}]`);
+	const classified = [...entryRead, ...entryOutline, ...entryReferences];
+	const overlap = classified.find((item, index) => classified.indexOf(item) !== index);
+	if (overlap) throw new Error(`Context path has multiple loading modes: ${path} [${name}] ${overlap}`);
+	return {
+		id: `${tab}/${concept}/${entry}`,
+		tab,
+		concept,
+		conceptName,
+		conceptDescription,
+		name: entry,
+		description: record.description.trim(),
+		read: entryRead,
+		show: entryShow,
+		outline: entryOutline,
+		references: entryReferences,
+		path,
+	};
+}
+
+async function loadConceptFile(root: string, tab: string, folder: string, fileName: string): Promise<ContextEntry[]> {
+	const path = join(root, ".pi", "contexts", folder, fileName);
+	const concept = validSlug(basename(fileName, ".toml"), "Context concept");
+	const raw = parse(await readFile(path, "utf8")) as Record<string, unknown>;
+	const conceptName = typeof raw.name === "string" && raw.name.trim() ? raw.name.trim() : concept;
+	const conceptDescription = typeof raw.description === "string" ? raw.description.trim() : "";
+	const entries: ContextEntry[] = [];
+	for (const [name, value] of Object.entries(raw)) {
+		if (name === "name" || name === "description") continue;
+		entries.push(parseContextEntryRecord(root, path, tab, concept, conceptName, conceptDescription, name, value));
+	}
+	return entries;
 }
 
 export async function loadContextEntries(root: string): Promise<ContextEntry[]> {
@@ -111,63 +281,16 @@ export async function loadContextEntries(root: string): Promise<ContextEntry[]>
 	if (!(await pathExists(contextsRoot))) return [];
 	const tabs = (await readdir(contextsRoot, { withFileTypes: true }))
 		.filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
-		.sort((a, b) => a.name.localeCompare(b.name));
+		.map((entry) => parseContextTabFolder(entry.name));
+	assertContiguousTabOrders(tabs);
+	tabs.sort((left, right) => left.order - right.order);
 	const result: ContextEntry[] = [];
 	for (const tabEntry of tabs) {
-		const tab = validSlug(tabEntry.name, "Context tab");
-		const files = (await readdir(join(contextsRoot, tab), { withFileTypes: true }))
+		const files = (await readdir(join(contextsRoot, tabEntry.folder), { withFileTypes: true }))
 			.filter((entry) => entry.isFile() && extname(entry.name) === ".toml")
 			.sort((a, b) => a.name.localeCompare(b.name));
 		for (const file of files) {
-			const path = join(contextsRoot, tab, file.name);
-			const concept = validSlug(basename(file.name, ".toml"), "Context concept");
-			const raw = parse(await readFile(path, "utf8")) as Record<string, unknown>;
-			const conceptName = typeof raw.name === "string" && raw.name.trim() ? raw.name.trim() : concept;
-			const conceptDescription = typeof raw.description === "string" ? raw.description.trim() : "";
-			for (const [name, value] of Object.entries(raw)) {
-				if (name === "name" || name === "description") continue;
-				if (!value || typeof value !== "object" || Array.isArray(value))
-					throw new Error(`Invalid context entry: ${path} [${name}]`);
-				const record = value as Record<string, unknown>;
-				const unknownField = Object.keys(record).find((field) => !CONTEXT_ENTRY_FIELDS.has(field));
-				if (unknownField) throw new Error(`Invalid context entry field: ${path} [${name}] ${unknownField}`);
-				if (
-					typeof record.description !== "string" ||
-					!record.description.trim() ||
-					!Array.isArray(record.read) ||
-					record.read.some((item) => typeof item !== "string") ||
-					!Array.isArray(record.outline) ||
-					record.outline.some((item) => typeof item !== "string") ||
-					!Array.isArray(record.references) ||
-					record.references.some((item) => typeof item !== "string") ||
-					(record.read.length === 0 && record.outline.length === 0 && record.references.length === 0)
-				)
-					throw new Error(`Invalid context entry: ${path} [${name}]`);
-				const entry = validSlug(name, "Context entry");
-				const entryRead = sortedUnique((record.read as string[]).map((item) => normalizeProjectPath(root, item)));
-				const entryOutline = sortedUnique(
-					(record.outline as string[]).map((item) => normalizeProjectPath(root, item)),
-				);
-				const entryReferences = sortedUnique(
-					(record.references as string[]).map((item) => normalizeProjectPath(root, item)),
-				);
-				const classified = [...entryRead, ...entryOutline, ...entryReferences];
-				const overlap = classified.find((item, index) => classified.indexOf(item) !== index);
-				if (overlap) throw new Error(`Context path has multiple loading modes: ${path} [${name}] ${overlap}`);
-				result.push({
-					id: `${tab}/${concept}/${entry}`,
-					tab,
-					concept,
-					conceptName,
-					conceptDescription,
-					name: entry,
-					description: record.description.trim(),
-					read: entryRead,
-					outline: entryOutline,
-					references: entryReferences,
-					path,
-				});
-			}
+			result.push(...(await loadConceptFile(root, tabEntry.slug, tabEntry.folder, file.name)));
 		}
 	}
 	return result;