@henryqw/pi-session-recall 2.0.0 → 2.1.0

package/README.md

@@ -4,7 +4,7 @@ Find decisions and context in past Pi sessions through a local FTS5 index.
 
 Saved transcripts are not injected on every turn. The active tool registration still adds standing prompt cost through its schema, descriptions, and guideline. Returned content enters active model context.
 
-The bundled `pi-session-pattern-miner` skill finds repeated work that may deserve automation.
+The bundled `pi-session-pattern-miner` skill prepares one bounded sample. The model then finds repeated work that may deserve automation.
 
 ## Install
 
@@ -22,7 +22,19 @@ Start discovery with a distinctive query:
 
 `session_search` returns ranked sessions. The top result includes nearby messages and session bookends.
 
-Use IDs from that result to ask for more context:
+Prepare a repository-scoped pattern-mining sample with one call:
+
+```json
+{
+  "operation": "prepare-pattern-miner",
+  "scope": "repository",
+  "limit": 10
+}
+```
+
+Use `scope:"all"` for cross-repository work. It still returns the corpus when repository inventory is unavailable.
+
+Use IDs from a discovery result to ask for more context:
 
 ```json
 {
@@ -36,13 +48,14 @@ The follow-up returns up to ten messages before and after that anchor on the sel
 
 | Surface | Type | Purpose |
 | --- | --- | --- |
-| `session_search` | tool | Search past sessions or inspect one. |
+| `session_search` | tool | Search, inspect, or prepare a bounded mining corpus from past sessions. |
 | `pi-session-pattern-miner` | skill | Find repeated work and choose the smallest useful automation. |
 
 BM25 is a text-ranking method. Hydrated results include messages read from saved session files.
 
 | Mode | Call | Result |
 | --- | --- | --- |
+| Pattern preparation | `operation:"prepare-pattern-miner"` + `scope:"repository"` or `scope:"all"` | Up to ten recent lineage-unique sessions plus repository inventory. The default limit is 10. Repository scope includes exact and descendant `cwd` values, filters before the limit, and excludes the current session file. |
 | Discovery | `query` | BM25-ranked top sessions. Adaptive retrieval uses user and assistant text for windows, bookends, anchors, and counts. It omits tool-result messages and sets `toolResultsOmitted:true` when it removes one. Lower hits still include their indexed anchor. Use `detail:"full"` to hydrate every hit with tool-result messages included. |
 | Scroll | `sessionId` + `aroundMessageId` | Raw message roles, including tool results, within ±`window` ([1,20]) of the anchor. Re-anchor on the last or first message ID to scroll. Across forks, pass the previous response's `branchTip`; `aroundMessageId` only centers the window and must lie on that branch. |
 | Read | `sessionId` | Raw message roles, including tool results, from the session. Large sessions return head 20 + tail 10. Oversized content is bounded to 50k characters and marked with `contentTruncated`. |
@@ -52,7 +65,36 @@ In the interactive TUI, the collapsed tool block shows the last five visual line
 
 ### Skills
 
-Run `/skill:pi-session-pattern-miner` to find repeated workflows in past sessions. It requires evidence from two independent sessions and checks for existing automation. It prefers a fixed script when model judgment is not needed.
+Run `/skill:pi-session-pattern-miner` to find repeated workflows in past sessions. The skill makes one preparation call before interpretation.
+
+It treats one lineage as one source. It requires two independent examples before recommending automation. A requested topic gets a focused confirmation search even when the prepared sample does not contain it.
+
+After clustering, the skill always checks current candidate-relevant package manifests, scripts, skills, and instructions. It abstains if it cannot check them safely.
+
+### Repository inventory
+
+Repository inventory contains discovery hints. It is never proof that a file owns a workflow. It does not verify the current worktree.
+
+Package scripts, executable paths, and instruction paths come from stage-0 entries in the Git index. Package content comes from indexed blobs. Git reads the objects locally in one check batch and one content batch. Lazy object fetching and replacement refs are disabled. Inventory never opens working-tree package paths.
+
+Executables need index mode `100755`. Instructions need a recognized name and a regular-file index mode.
+
+Skills come from Pi's effective command registry. Their canonical source paths must stay inside the repository.
+
+Available inventory includes this provenance:
+
+```json
+{
+  "packageScripts": "git-index",
+  "executableScripts": "git-index",
+  "agentInstructions": "git-index",
+  "skills": "pi-effective-registry"
+}
+```
+
+It also sets `worktreeVerified:false`. Staged adds, changes, and deletes affect the snapshot. Unstaged changes, deletions, mode changes, symlinks, and untracked files do not.
+
+Inspect the current candidate files before assigning ownership. Abstain if targeted current-file checks cannot be done safely.
 
 ## Flow
 
@@ -70,12 +112,16 @@ Search makes no model calls.
 
 Hits inside the current session's live context are suppressed. Compacted-away or inactive-branch history stays discoverable. Forked sessions collapse into their parent when both match.
 
-Before browse or discovery, the extension lazily syncs the index from the session tree.
+Before browse, discovery, or pattern preparation, the extension lazily syncs the index from the session tree.
+
+Pattern preparation reports `sync.walkComplete`, `sync.backlogRemaining`, and `sync.complete`. `sync.complete` is true only after a complete walk with no backlog.
 
 ### Retrieval safety
 
 Adaptive discovery leaves tool-result messages out of returned context. Use `detail:"full"`, READ, or SCROLL when you explicitly need them.
 
+Pattern preparation returns only non-empty user and assistant text. It never returns thinking blocks or tool-result content. Each session keeps citation and lineage metadata even when its hydration fails.
+
 Historical tool output may contain secrets or other sensitive data. Raw retrieval places that output in active model context.
 
 ## State and storage
@@ -91,7 +137,7 @@ The index and transcript reads stay local. Transcripts are read in place. Return
 Pin the previous release:
 
 ```bash
-pi install npm:@henryqw/pi-session-recall@1.0.3
+pi install npm:@henryqw/pi-session-recall@2.0.0
 ```
 
 No index migration or cleanup is needed.
@@ -109,3 +155,19 @@ Session directories whose encoded path starts with `--tmp-` or `--private-tmp-`
 Session files over 32 MiB are excluded from indexing and hydration. Discovery cannot newly find them.
 
 READ and SCROLL return an explicit size error. A stale discovery hit from before a file grew returns metadata with empty messages and that error.
+
+Pattern preparation runs one sync pass. A positive backlog or incomplete walk limits the sample and sets `sync.complete:false`. A total sync or required repository-inventory failure returns an explicit tool error.
+
+Repository scope fails outside Git or when repository inventory fails. All scope still returns its corpus in both cases.
+
+Outside Git, all scope sets `inventory.available:false` with `reason:"not-a-git-repository"`. On a repository inventory error, it uses `reason:"inventory-failed"`. Cancellation always aborts the call instead of returning unavailable inventory.
+
+Preparation rejects `query`, session cursors, `window`, or `detail` in the same call. It also rejects `scope` without the operation.
+
+Preparation output stays within 50,000 serialized characters. Inventory uses at most 10,000 characters. Its `omittedCounts` report only omitted collection entries, and `inventory.truncated` reports those omissions.
+
+Inventory fails if the Git root output exceeds 4 KiB or the raw index listing exceeds 8 MiB. It also fails on malformed index data, invalid UTF-8, conflict entries, unsupported package modes, Git errors, unexpected Git stderr, or bounded stream overflow.
+
+Inventory accepts at most 512 package manifests. Each indexed manifest can be at most 1 MiB, and their declared sizes can total at most 16 MiB. One bounded batch checks all blob sizes before one bounded batch reads their content. Blob order, type, size, UTF-8, and exact output framing are checked before manifest data is parsed.
+
+Session and top-level `contentTruncated` report transcript budget trimming only. Session `truncated` reports omitted middle messages.

package/extensions/hydrate.ts

@@ -25,6 +25,13 @@ export interface ReadResult {
 	messages: WindowMessage[];
 	totalMessages: number;
 	truncated: boolean;
+	/** Resolved leaf branch, or null when no selected message can be hydrated. */
+	branchTip: string | null;
+}
+
+export interface ReadOptions {
+	/** Preparation view: retain only non-empty user/assistant text. */
+	userAssistantTextOnly?: boolean;
 }
 
 interface Entry {
@@ -249,18 +256,24 @@ export function readSession(
 	sessionPath: string,
 	head = 20,
 	tail = 10,
+	opts?: ReadOptions,
 ): ReadResult {
 	const entries = parseSessionEntries(sessionPath);
 	const entriesById = new Map(entries.map((e) => [e.id, e]));
 	const leaf = leafId(entriesById, entries);
-	if (!leaf) return { messages: [], totalMessages: 0, truncated: false };
-	const msgs = branchMessages(entriesById, leaf);
+	if (!leaf) return { messages: [], totalMessages: 0, truncated: false, branchTip: null };
+	const rawMessages = branchMessages(entriesById, leaf);
+	const msgs = opts?.userAssistantTextOnly
+		? rawMessages.filter((m) => (m.role === "user" || m.role === "assistant") && m.content.trim().length > 0)
+		: rawMessages;
+	const branchTip = msgs.length > 0 ? leaf : null;
 	if (msgs.length > head + tail) {
 		return {
 			messages: [...msgs.slice(0, head), ...msgs.slice(-tail)],
 			totalMessages: msgs.length,
 			truncated: true,
+			branchTip,
 		};
 	}
-	return { messages: msgs, totalMessages: msgs.length, truncated: false };
+	return { messages: msgs, totalMessages: msgs.length, truncated: false, branchTip };
 }

package/extensions/repository-inventory.ts

@@ -0,0 +1,515 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export const MAX_MANIFEST_BYTES = 1024 * 1024;
+export const MAX_PACKAGE_MANIFESTS = 512;
+export const MAX_TOTAL_MANIFEST_BYTES = 16 * 1024 * 1024;
+export const REPOSITORY_UNAVAILABLE_REASON = "not-a-git-repository";
+export const REPOSITORY_INVENTORY_FAILED_REASON = "inventory-failed";
+
+const ROOT_STDOUT_BYTES = 4 * 1024;
+const INDEX_STDOUT_BYTES = 8 * 1024 * 1024;
+const GIT_STDERR_BYTES = 4 * 1024;
+const BATCH_RECORD_BYTES = 128;
+const BATCH_CHECK_STDOUT_BYTES = BATCH_RECORD_BYTES * MAX_PACKAGE_MANIFESTS;
+const CONTENT_BATCH_STDOUT_BYTES = MAX_TOTAL_MANIFEST_BYTES + BATCH_RECORD_BYTES * MAX_PACKAGE_MANIFESTS;
+const BATCH_STDIN_BYTES = (64 + 1) * MAX_PACKAGE_MANIFESTS;
+const INSTRUCTION_NAMES = new Set(["AGENTS.md", "AGENTS.override.md", "CLAUDE.md"]);
+const REGULAR_MODES = new Set(["100644", "100755"]);
+const INDEX_MODES = new Set(["100644", "100755", "120000", "160000"]);
+const PROVENANCE = {
+	packageScripts: "git-index",
+	executableScripts: "git-index",
+	agentInstructions: "git-index",
+	skills: "pi-effective-registry",
+} as const;
+
+export type RepositoryInventoryMode = "required" | "optional";
+
+export interface PackageScript {
+	path: string;
+	name: string;
+	command: string;
+}
+
+export interface RepositorySkill {
+	name: string;
+	description: string;
+	sourcePath: string;
+}
+
+interface RepositoryInventoryCollections {
+	packageScripts: PackageScript[];
+	executableScripts: string[];
+	skills: RepositorySkill[];
+	agentInstructions: string[];
+	worktreeVerified: false;
+}
+
+export type RepositoryInventory = RepositoryInventoryCollections & ({
+	available: true;
+	gitRoot: string;
+	provenance: typeof PROVENANCE;
+	reason?: never;
+} | {
+	available: false;
+	reason: typeof REPOSITORY_UNAVAILABLE_REASON | typeof REPOSITORY_INVENTORY_FAILED_REASON;
+	gitRoot?: never;
+	provenance?: never;
+});
+
+type InventoryPi = Pick<ExtensionAPI, "getCommands">;
+type InventoryContext = Pick<ExtensionContext, "cwd" | "signal">;
+
+interface GitResult {
+	stdout: Buffer;
+	code: number;
+}
+
+interface IndexEntry {
+	mode: string;
+	oid: string;
+	path: string;
+}
+
+function compare(left: string, right: string): number {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function toPosixPath(value: string): string {
+	return value.split(path.sep).join("/");
+}
+
+function isWithin(root: string, target: string, allowRoot = true): boolean {
+	const relative = path.relative(root, target);
+	return (allowRoot && relative === "") ||
+		(relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function boundedPath(value: string): string {
+	const bounded = value.length <= 240 ? value : `${value.slice(0, 239)}…`;
+	return JSON.stringify(bounded);
+}
+
+function malformedManifest(relativePath: string): Error {
+	return new Error(`Malformed repository manifest: ${boundedPath(relativePath)}`);
+}
+
+function unsupportedManifestMode(relativePath: string): Error {
+	return new Error(`Unsupported repository manifest mode: ${boundedPath(relativePath)}`);
+}
+
+function oversizedManifest(relativePath: string): Error {
+	return new Error(`Oversized repository manifest (1 MiB limit): ${boundedPath(relativePath)}`);
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+	if (signal?.aborted) throw new Error("Repository inventory cancelled.");
+}
+
+/** Spawn one bounded process and never expose child output through failures. */
+function runGit(
+	cwd: string,
+	args: string[],
+	signal: AbortSignal | undefined,
+	stdoutCap: number,
+	options: { allowNonzero?: boolean; allowStderrOnNonzero?: boolean; stdin?: Buffer } = {},
+): Promise<GitResult> {
+	throwIfAborted(signal);
+	if (options.stdin !== undefined && options.stdin.length > BATCH_STDIN_BYTES) {
+		throw new Error("Repository inventory Git stdin exceeded its limit.");
+	}
+	return new Promise((resolve, reject) => {
+		let child: ReturnType<typeof spawn>;
+		try {
+			child = spawn("git", args, {
+				cwd,
+				env: { ...process.env, GIT_NO_LAZY_FETCH: "1" },
+				shell: false,
+				stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+			});
+		} catch {
+			reject(new Error("Repository inventory could not start Git."));
+			return;
+		}
+
+		const childStdout = child.stdout;
+		const childStderr = child.stderr;
+		const childStdin = child.stdin;
+		if (!childStdout || !childStderr || (options.stdin !== undefined && !childStdin)) {
+			child.kill("SIGKILL");
+			reject(new Error("Repository inventory could not start Git."));
+			return;
+		}
+		const stdout: Buffer[] = [];
+		let stdoutBytes = 0;
+		let stderrBytes = 0;
+		let failure: Error | undefined;
+		let settled = false;
+
+		const fail = (error: Error) => {
+			if (failure) return;
+			failure = error;
+			child.kill("SIGKILL");
+		};
+		const finish = (error?: Error, result?: GitResult) => {
+			if (settled) return;
+			settled = true;
+			signal?.removeEventListener("abort", onAbort);
+			if (error) reject(error);
+			else resolve(result!);
+		};
+		const onAbort = () => fail(new Error("Repository inventory cancelled."));
+
+		childStdout.on("data", (chunk: Buffer) => {
+			stdoutBytes += chunk.length;
+			if (stdoutBytes > stdoutCap) {
+				fail(new Error("Repository inventory Git stdout exceeded its limit."));
+				return;
+			}
+			stdout.push(chunk);
+		});
+		childStderr.on("data", (chunk: Buffer) => {
+			stderrBytes += chunk.length;
+			if (stderrBytes > GIT_STDERR_BYTES) {
+				fail(new Error("Repository inventory Git stderr exceeded its limit."));
+			} else if (!options.allowStderrOnNonzero) {
+				fail(new Error("Repository inventory Git wrote unexpected stderr."));
+			}
+		});
+		childStdin?.once("error", () => fail(new Error("Repository inventory could not write Git input.")));
+		child.once("error", () => finish(new Error("Repository inventory could not start Git.")));
+		child.once("close", (code) => {
+			if (failure) {
+				finish(failure);
+				return;
+			}
+			if (signal?.aborted) {
+				finish(new Error("Repository inventory cancelled."));
+				return;
+			}
+			if (code === null || (code !== 0 && !options.allowNonzero)) {
+				finish(new Error("Repository inventory Git command failed."));
+				return;
+			}
+			if (stderrBytes > 0 && !(code !== 0 && options.allowStderrOnNonzero)) {
+				finish(new Error("Repository inventory Git wrote unexpected stderr."));
+				return;
+			}
+			finish(undefined, { stdout: Buffer.concat(stdout, stdoutBytes), code });
+		});
+		signal?.addEventListener("abort", onAbort, { once: true });
+		if (signal?.aborted) onAbort();
+		if (options.stdin !== undefined && !failure) {
+			try {
+				childStdin!.end(options.stdin);
+			} catch {
+				fail(new Error("Repository inventory could not write Git input."));
+			}
+		}
+	});
+}
+
+function decodeUtf8(value: Buffer, error: () => Error): string {
+	let decoded: string;
+	try {
+		decoded = new TextDecoder("utf-8", { fatal: true }).decode(value);
+	} catch {
+		throw error();
+	}
+	if (decoded.includes("�")) throw error();
+	return decoded;
+}
+
+function decodeAscii(value: Buffer, error: () => Error): string {
+	if (value.some((byte) => byte > 0x7f)) throw error();
+	return value.toString("ascii");
+}
+
+function canonicalDirectory(value: string): string {
+	try {
+		const canonical = fs.realpathSync(value);
+		if (!fs.statSync(canonical).isDirectory()) throw new Error("not a directory");
+		return canonical;
+	} catch {
+		throw new Error("Repository inventory could not resolve the Git root.");
+	}
+}
+
+function gitRootFromOutput(stdout: Buffer): string {
+	const invalid = () => new Error("Repository inventory could not resolve the Git root.");
+	const decoded = decodeUtf8(stdout, invalid);
+	const root = decoded.endsWith("\r\n") ? decoded.slice(0, -2) : decoded.endsWith("\n") ? decoded.slice(0, -1) : decoded;
+	if (!root || root.includes("\r") || root.includes("\n") || (!path.isAbsolute(root) && !path.win32.isAbsolute(root))) {
+		throw invalid();
+	}
+	return canonicalDirectory(root);
+}
+
+async function resolveGitRoot(ctx: InventoryContext): Promise<string | undefined> {
+	const cwd = canonicalDirectory(ctx.cwd);
+	const result = await runGit(cwd, ["rev-parse", "--show-toplevel"], ctx.signal, ROOT_STDOUT_BYTES, {
+		allowNonzero: true,
+		allowStderrOnNonzero: true,
+	});
+	return result.code === 0 ? gitRootFromOutput(result.stdout) : undefined;
+}
+
+function looksLikePackageJson(value: string): boolean {
+	return value === "package.json" || value.endsWith("/package.json");
+}
+
+function normalizeRepositoryPath(value: string): string {
+	const segments = value.split("/");
+	if (
+		!value ||
+		value.includes("�") ||
+		value.includes("\\") ||
+		path.isAbsolute(value) ||
+		path.win32.isAbsolute(value) ||
+		segments.some((segment) => !segment || segment === "." || segment === "..")
+	) {
+		throw new Error("Repository inventory received an invalid repository path.");
+	}
+	return value;
+}
+
+function parseIndex(stdout: Buffer): IndexEntry[] {
+	if (stdout.length === 0) return [];
+	if (stdout.at(-1) !== 0) throw new Error("Repository inventory received an invalid Git index listing.");
+	const entries: IndexEntry[] = [];
+	const paths = new Set<string>();
+	let start = 0;
+	while (start < stdout.length) {
+		const end = stdout.indexOf(0, start);
+		if (end < 0) throw new Error("Repository inventory received an invalid Git index listing.");
+		const record = stdout.subarray(start, end);
+		start = end + 1;
+		const tab = record.indexOf(0x09);
+		if (tab < 0) throw new Error("Repository inventory received an invalid Git index listing.");
+		const invalid = () => new Error("Repository inventory received an invalid Git index listing.");
+		const metadata = decodeAscii(record.subarray(0, tab), invalid);
+		const match = /^([0-7]{6}) ([0-9a-fA-F]{40}|[0-9a-fA-F]{64}) ([0-3])$/.exec(metadata);
+		if (!match) throw invalid();
+		const relativePath = normalizeRepositoryPath(decodeUtf8(record.subarray(tab + 1), invalid));
+		const [, mode, oid, stage] = match;
+		if (stage !== "0") throw new Error("Repository inventory does not accept conflicted Git index entries.");
+		if (paths.has(relativePath)) throw new Error("Repository inventory received duplicate Git index entries.");
+		paths.add(relativePath);
+		if (looksLikePackageJson(relativePath) && !REGULAR_MODES.has(mode)) throw unsupportedManifestMode(relativePath);
+		if (!INDEX_MODES.has(mode)) throw invalid();
+		entries.push({ mode, oid, path: relativePath });
+	}
+	return entries.sort((left, right) => compare(left.path, right.path));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function scriptsFromManifest(source: string, relativePath: string): PackageScript[] {
+	let manifest: unknown;
+	try {
+		manifest = JSON.parse(source);
+	} catch {
+		throw malformedManifest(relativePath);
+	}
+	if (!isRecord(manifest)) throw malformedManifest(relativePath);
+	const scripts = manifest.scripts;
+	if (scripts === undefined) return [];
+	if (!isRecord(scripts)) throw malformedManifest(relativePath);
+	const result: PackageScript[] = [];
+	for (const [name, command] of Object.entries(scripts)) {
+		if (typeof command !== "string") throw malformedManifest(relativePath);
+		result.push({ path: relativePath, name, command });
+	}
+	return result.sort((left, right) => compare(left.name, right.name));
+}
+
+interface SizedIndexEntry extends IndexEntry {
+	size: number;
+}
+
+function invalidBatchOutput(): Error {
+	return new Error("Repository inventory received invalid Git batch output.");
+}
+
+function missingIndexedObject(relativePath: string): Error {
+	return new Error(`Repository inventory is missing an indexed Git object: ${boundedPath(relativePath)}`);
+}
+
+function decimalSize(value: string): number {
+	if (!/^(0|[1-9][0-9]*)$/.test(value)) throw invalidBatchOutput();
+	const size = BigInt(value);
+	if (size > BigInt(Number.MAX_SAFE_INTEGER)) throw invalidBatchOutput();
+	return Number(size);
+}
+
+function parseBatchCheck(stdout: Buffer, packages: IndexEntry[]): SizedIndexEntry[] {
+	if (stdout.at(-1) !== 0x0a) throw invalidBatchOutput();
+	const records = decodeAscii(stdout, invalidBatchOutput).slice(0, -1).split("\n");
+	if (records.length !== packages.length) throw invalidBatchOutput();
+
+	const sized: SizedIndexEntry[] = [];
+	let totalBytes = 0;
+	for (let index = 0; index < packages.length; index++) {
+		const entry = packages[index]!;
+		const record = records[index]!;
+		if (record === `${entry.oid} missing`) throw missingIndexedObject(entry.path);
+		const match = /^([0-9a-fA-F]{40}|[0-9a-fA-F]{64}) ([a-z]+) (0|[1-9][0-9]*)$/.exec(record);
+		if (!match) throw invalidBatchOutput();
+		const [, oid, type, rawSize] = match;
+		if (oid !== entry.oid) throw new Error("Repository inventory received Git objects out of order.");
+		if (type !== "blob") throw new Error("Repository inventory expected an indexed Git blob.");
+		const size = decimalSize(rawSize);
+		if (size > MAX_MANIFEST_BYTES) throw oversizedManifest(entry.path);
+		if (totalBytes > MAX_TOTAL_MANIFEST_BYTES - size) {
+			throw new Error("Repository inventory exceeds the 16 MiB total manifest limit.");
+		}
+		totalBytes += size;
+		sized.push({ ...entry, size });
+	}
+	return sized;
+}
+
+function parseContentBatch(stdout: Buffer, packages: SizedIndexEntry[]): PackageScript[] {
+	const scripts: PackageScript[] = [];
+	let offset = 0;
+	for (const entry of packages) {
+		const headerEnd = stdout.indexOf(0x0a, offset);
+		if (headerEnd < 0) throw invalidBatchOutput();
+		const header = decodeAscii(stdout.subarray(offset, headerEnd), invalidBatchOutput);
+		if (header === `${entry.oid} missing`) throw missingIndexedObject(entry.path);
+		const match = /^([0-9a-fA-F]{40}|[0-9a-fA-F]{64}) ([a-z]+) (0|[1-9][0-9]*)$/.exec(header);
+		if (!match) throw invalidBatchOutput();
+		const [, oid, type, rawSize] = match;
+		if (oid !== entry.oid) throw new Error("Repository inventory received Git objects out of order.");
+		if (type !== "blob") throw new Error("Repository inventory expected an indexed Git blob.");
+		const size = decimalSize(rawSize);
+		if (size !== entry.size) throw new Error("Repository inventory received an incorrect Git blob size.");
+
+		const contentStart = headerEnd + 1;
+		const contentEnd = contentStart + size;
+		if (contentEnd >= stdout.length || stdout[contentEnd] !== 0x0a) throw invalidBatchOutput();
+		const invalid = () => malformedManifest(entry.path);
+		scripts.push(...scriptsFromManifest(decodeUtf8(stdout.subarray(contentStart, contentEnd), invalid), entry.path));
+		offset = contentEnd + 1;
+	}
+	if (offset !== stdout.length) throw invalidBatchOutput();
+	return scripts;
+}
+
+async function packageScriptsFromIndex(
+	root: string,
+	entries: IndexEntry[],
+	signal: AbortSignal | undefined,
+): Promise<PackageScript[]> {
+	const packages = entries.filter((entry) => looksLikePackageJson(entry.path));
+	if (packages.length > MAX_PACKAGE_MANIFESTS) {
+		throw new Error("Repository inventory exceeds the 512 package manifest limit.");
+	}
+	if (packages.length === 0) return [];
+
+	const stdin = Buffer.from(packages.map((entry) => `${entry.oid}\n`).join(""), "ascii");
+	const checked = await runGit(
+		root,
+		["--no-replace-objects", "cat-file", "--batch-check=%(objectname) %(objecttype) %(objectsize)"],
+		signal,
+		BATCH_CHECK_STDOUT_BYTES,
+		{ stdin },
+	);
+	const sized = parseBatchCheck(checked.stdout, packages);
+	const content = await runGit(
+		root,
+		["--no-replace-objects", "cat-file", "--batch"],
+		signal,
+		CONTENT_BATCH_STDOUT_BYTES,
+		{ stdin },
+	);
+	return parseContentBatch(content.stdout, sized);
+}
+
+function effectiveSkills(pi: InventoryPi, root: string): RepositorySkill[] {
+	let commands: ReturnType<InventoryPi["getCommands"]>;
+	try {
+		commands = pi.getCommands();
+	} catch {
+		throw new Error("Repository inventory could not read effective skills.");
+	}
+	const skills: RepositorySkill[] = [];
+	for (const command of commands) {
+		if (command.source !== "skill" || typeof command.name !== "string" || typeof command.sourceInfo?.path !== "string") continue;
+		let sourcePath: string;
+		try {
+			sourcePath = fs.realpathSync(command.sourceInfo.path);
+		} catch {
+			continue;
+		}
+		if (!isWithin(root, sourcePath, false)) continue;
+		skills.push({
+			name: command.name,
+			description: typeof command.description === "string" ? command.description : "",
+			sourcePath: toPosixPath(path.relative(root, sourcePath)),
+		});
+	}
+	return skills.sort((left, right) =>
+		compare(left.name, right.name) ||
+		compare(left.sourcePath, right.sourcePath) ||
+		compare(left.description, right.description),
+	);
+}
+
+function unavailableInventory(
+	reason: typeof REPOSITORY_UNAVAILABLE_REASON | typeof REPOSITORY_INVENTORY_FAILED_REASON,
+): RepositoryInventory {
+	return {
+		available: false,
+		reason,
+		packageScripts: [],
+		executableScripts: [],
+		skills: [],
+		agentInstructions: [],
+		worktreeVerified: false,
+	};
+}
+
+/** Return bounded discovery hints from the Git index and Pi's effective skill registry. */
+export async function inventoryRepository(
+	pi: InventoryPi,
+	ctx: InventoryContext,
+	mode: RepositoryInventoryMode = "required",
+): Promise<RepositoryInventory> {
+	if (mode !== "required" && mode !== "optional") throw new Error("Invalid repository inventory mode.");
+	throwIfAborted(ctx.signal);
+	const gitRoot = await resolveGitRoot(ctx);
+	throwIfAborted(ctx.signal);
+	if (!gitRoot) {
+		if (mode === "optional") return unavailableInventory(REPOSITORY_UNAVAILABLE_REASON);
+		throw new Error("Repository inventory requires a Git repository.");
+	}
+
+	try {
+		const index = parseIndex((await runGit(gitRoot, ["--no-replace-objects", "ls-files", "--stage", "-z"], ctx.signal, INDEX_STDOUT_BYTES)).stdout);
+		const packageScripts = await packageScriptsFromIndex(gitRoot, index, ctx.signal);
+		const skills = effectiveSkills(pi, gitRoot);
+		throwIfAborted(ctx.signal);
+		return {
+			available: true,
+			gitRoot,
+			packageScripts,
+			executableScripts: index.filter((entry) => entry.mode === "100755").map((entry) => entry.path),
+			skills,
+			agentInstructions: index
+				.filter((entry) => REGULAR_MODES.has(entry.mode) && INSTRUCTION_NAMES.has(path.posix.basename(entry.path)))
+				.map((entry) => entry.path),
+			provenance: PROVENANCE,
+			worktreeVerified: false,
+		};
+	} catch (error) {
+		throwIfAborted(ctx.signal);
+		if (mode === "optional") return unavailableInventory(REPOSITORY_INVENTORY_FAILED_REASON);
+		throw error;
+	}
+}

package/extensions/search-core.ts

@@ -9,7 +9,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { buildFtsQueryPlan, buildLikeQueryPlan, foldCase, nearLike } from "./query.ts";
 import { MAX_SESSION_FILE_BYTES, readTranscriptEntries } from "./transcript.ts";
-import type { SearchHit, SessionRow, SyncResult } from "./types.ts";
+import type { PreparationSessionRow, SearchHit, SessionRow, SyncResult } from "./types.ts";
 export const DEFAULT_SYNC_CAP = 50;
 /** Hard ceiling for the internal/test `opts.cap` work bound of syncSessions. */
 const MAX_SYNC_CAP = DEFAULT_SYNC_CAP * 10;
@@ -692,7 +692,76 @@ export function searchIndex(
 	}
 }
 
-// --- Browse ---
+// --- Preparation / browse ---
+
+export interface PreparationRowOptions {
+	limit: number;
+	/** Canonical repository root. Omit to sample all indexed sessions. */
+	repositoryRoot?: string;
+	currentSessionPath?: string;
+}
+
+/** Select deterministic, repository-scoped pattern-miner candidates from the
+ * existing index. Scope, current-session exclusion, and one-hop lineage
+ * collapse all happen before the sample limit. */
+export function getPreparationRows(
+	dbPath: string,
+	opts: PreparationRowOptions,
+): PreparationSessionRow[] {
+	const clauses: string[] = [];
+	const params: string[] = [];
+	if (opts.repositoryRoot !== undefined) {
+		const prefix = opts.repositoryRoot.endsWith(path.sep)
+			? opts.repositoryRoot
+			: opts.repositoryRoot + path.sep;
+		clauses.push("(s.cwd = ? OR substr(s.cwd, 1, length(?)) = ?)");
+		params.push(opts.repositoryRoot, prefix, prefix);
+	}
+	if (opts.currentSessionPath !== undefined) {
+		clauses.push("s.path <> ?");
+		params.push(opts.currentSessionPath);
+	}
+	const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+	const db = openDb(dbPath);
+	try {
+		const rows = db.prepare(`
+			WITH eligible AS (
+				SELECT s.path, s.cwd, s.name, s.started_at, s.preview,
+					CASE
+						WHEN s.parent_session IS NULL THEN s.path
+						WHEN parent.path <> s.path AND parent.parent_session = s.path
+							THEN min(s.path, parent.path)
+						ELSE s.parent_session
+					END AS lineage_id
+				FROM sessions s
+				LEFT JOIN sessions parent ON parent.path = s.parent_session
+				${where}
+			), ranked AS (
+				SELECT *, ROW_NUMBER() OVER (
+					PARTITION BY lineage_id
+					ORDER BY CASE WHEN path = lineage_id THEN 0 ELSE 1 END,
+						started_at DESC, path
+				) AS rn
+				FROM eligible
+			)
+			SELECT path, cwd, name, started_at, preview, lineage_id
+			FROM ranked
+			WHERE rn = 1
+			ORDER BY started_at DESC, path
+			LIMIT ?
+		`).all(...params, opts.limit) as any[];
+		return rows.map((r) => ({
+			path: r.path,
+			cwd: r.cwd ?? "",
+			name: r.name ?? undefined,
+			startedAt: r.started_at ?? undefined,
+			preview: r.preview ?? undefined,
+			lineageId: r.lineage_id,
+		}));
+	} finally {
+		db.close();
+	}
+}
 
 export function getSessionRows(dbPath: string, limit: number): SessionRow[] {
 	const db = openDb(dbPath);

package/extensions/session-recall.ts

@@ -9,15 +9,18 @@ import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { realpathSync } from "node:fs";
 import { join, sep } from "node:path";
-import { getSessionRows, searchIndex, syncSessions } from "./search-core.ts";
+import { getPreparationRows, getSessionRows, searchIndex, syncSessions } from "./search-core.ts";
 import { getWindow, readSession } from "./hydrate.ts";
 import { MAX_QUERY_CHARS } from "./query.ts";
-import type { WindowMessage } from "./types.ts";
+import { inventoryRepository, type RepositoryInventory } from "./repository-inventory.ts";
+import type { PreparationSessionRow, WindowMessage } from "./types.ts";
 
 const dbPath = () => join(extensionConfigDir("pi-session-recall"), "index.db");
 const sessionsDir = () => join(getAgentDir(), "sessions");
 
 const OUTPUT_CHAR_BUDGET = 50_000;
+const INVENTORY_CHAR_BUDGET = 10_000;
+const ERROR_MESSAGE_CHARS = 512;
 
 function clamp(n: number | undefined, min: number, max: number, dflt: number): number {
 	if (typeof n !== "number" || !Number.isFinite(n)) return dflt;
@@ -78,7 +81,185 @@ function boundContent(
 	return cap === null ? build(null) : { ...build(cap), contentTruncated: true };
 }
 
+type InventoryCollection = "packageScripts" | "executableScripts" | "skills" | "agentInstructions";
+const INVENTORY_COLLECTIONS: InventoryCollection[] = ["packageScripts", "executableScripts", "skills", "agentInstructions"];
+
+function inventoryShape(
+	source: RepositoryInventory,
+	kept: Record<InventoryCollection, unknown[]>,
+): Record<string, unknown> {
+	const omittedCounts = {
+		packageScripts: source.packageScripts.length - kept.packageScripts.length,
+		executableScripts: source.executableScripts.length - kept.executableScripts.length,
+		skills: source.skills.length - kept.skills.length,
+		agentInstructions: source.agentInstructions.length - kept.agentInstructions.length,
+	};
+	return {
+		available: source.available,
+		...(source.reason ? { reason: source.reason } : {}),
+		...(source.provenance ? { provenance: source.provenance } : {}),
+		worktreeVerified: source.worktreeVerified,
+		packageScripts: kept.packageScripts,
+		executableScripts: kept.executableScripts,
+		skills: kept.skills,
+		agentInstructions: kept.agentInstructions,
+		truncated: Object.values(omittedCounts).some((count) => count > 0),
+		omittedCounts,
+	};
+}
+
+/** Keep stable prefixes from every inventory collection within one bounded,
+ * round-robin allocation so a large first collection cannot starve the rest. */
+function boundInventory(source: RepositoryInventory, maxChars: number): Record<string, unknown> {
+	const all: Record<InventoryCollection, unknown[]> = {
+		packageScripts: source.packageScripts,
+		executableScripts: source.executableScripts,
+		skills: source.skills,
+		agentInstructions: source.agentInstructions,
+	};
+	const full = inventoryShape(source, all);
+	if (JSON.stringify(full).length <= maxChars) return full;
+
+	const kept: Record<InventoryCollection, unknown[]> = {
+		packageScripts: [],
+		executableScripts: [],
+		skills: [],
+		agentInstructions: [],
+	};
+	const blocked = new Set<InventoryCollection>();
+	for (;;) {
+		let advanced = false;
+		for (const key of INVENTORY_COLLECTIONS) {
+			if (blocked.has(key) || kept[key].length >= all[key].length) continue;
+			const candidate = { ...kept, [key]: [...kept[key], all[key][kept[key].length]] };
+			if (JSON.stringify(inventoryShape(source, candidate)).length <= maxChars) {
+				kept[key] = candidate[key];
+				advanced = true;
+			} else {
+				blocked.add(key);
+			}
+		}
+		if (!advanced) break;
+	}
+	return inventoryShape(source, kept);
+}
+
+interface PreparedSession {
+	metadata: Record<string, unknown>;
+	messages: WindowMessage[];
+}
+
+function hydrationError(error: unknown): { kind: "missing" | "oversized" | "unreadable"; message: string } {
+	const message = (error instanceof Error ? error.message : String(error)).slice(0, ERROR_MESSAGE_CHARS);
+	const code = (error as NodeJS.ErrnoException)?.code;
+	return {
+		kind: code === "ENOENT" ? "missing" : message.includes("exceeds 32 MiB snapshot limit") ? "oversized" : "unreadable",
+		message,
+	};
+}
+
+function hydratePreparationSession(row: PreparationSessionRow): PreparedSession {
+	const indexed = {
+		path: row.path,
+		cwd: row.cwd,
+		name: row.name ?? null,
+		startedAt: row.startedAt ?? null,
+		lineageId: row.lineageId,
+	};
+	try {
+		const hydrated = readSession(row.path, 20, 10, { userAssistantTextOnly: true });
+		return {
+			metadata: {
+				...indexed,
+				branchTip: hydrated.branchTip,
+				totalMessages: hydrated.totalMessages,
+				truncated: hydrated.truncated,
+				contentTruncated: false,
+				messages: [],
+			},
+			messages: hydrated.messages,
+		};
+	} catch (error) {
+		return {
+			metadata: {
+				...indexed,
+				branchTip: null,
+				totalMessages: null,
+				truncated: false,
+				contentTruncated: false,
+				messages: [],
+				error: hydrationError(error),
+			},
+			messages: [],
+		};
+	}
+}
+
+function allocatePreparationMessages(session: PreparedSession, budget: number): Record<string, unknown> {
+	if (session.messages.length === 0) return session.metadata;
+	if (JSON.stringify(session.messages).length - 2 <= budget) {
+		return { ...session.metadata, messages: session.messages };
+	}
+	const maxLen = Math.max(...session.messages.map((message) => message.content.length), 0);
+	const cap = maxFittingCap(maxLen, budget + 2, (value) => truncateContent(session.messages, value));
+	return {
+		...session.metadata,
+		contentTruncated: true,
+		messages: cap === null ? [] : truncateContent(session.messages, cap),
+	};
+}
+
+function buildPreparationResult(
+	kind: "repository" | "all",
+	requestedLimit: number,
+	gitRoot: string | undefined,
+	syncResult: ReturnType<typeof syncSessions>,
+	rows: PreparationSessionRow[],
+	repositoryInventory: RepositoryInventory,
+): Record<string, unknown> {
+	const sync = {
+		walkComplete: syncResult.walkComplete,
+		backlogRemaining: syncResult.backlogRemaining,
+		complete: syncResult.walkComplete && syncResult.backlogRemaining === 0,
+	};
+	const sessions = rows.map(hydratePreparationSession);
+	const emptyCollections: Record<InventoryCollection, unknown[]> = {
+		packageScripts: [],
+		executableScripts: [],
+		skills: [],
+		agentInstructions: [],
+	};
+	const minimumInventory = inventoryShape(repositoryInventory, emptyCollections);
+	const build = (
+		preparedSessions: Record<string, unknown>[],
+		inventory: Record<string, unknown>,
+		contentTruncated: boolean,
+	) => ({
+		mode: "prepare-pattern-miner",
+		scope: { kind, gitRoot: gitRoot ?? null, requestedLimit, sampledCount: preparedSessions.length },
+		sync,
+		sessions: preparedSessions,
+		inventory,
+		contentTruncated,
+	});
+
+	const metadataOnlyLength = JSON.stringify(build(sessions.map((session) => session.metadata), minimumInventory, false)).length;
+	if (metadataOnlyLength > OUTPUT_CHAR_BUDGET) throw new Error("Pattern-miner preparation metadata exceeds output budget.");
+	const inventoryBudget = Math.min(
+		INVENTORY_CHAR_BUDGET,
+		JSON.stringify(minimumInventory).length + OUTPUT_CHAR_BUDGET - metadataOnlyLength,
+	);
+	const inventory = boundInventory(repositoryInventory, inventoryBudget);
+	const baseLength = JSON.stringify(build(sessions.map((session) => session.metadata), inventory, false)).length;
+	const perSessionBudget = sessions.length === 0 ? 0 : Math.floor((OUTPUT_CHAR_BUDGET - baseLength) / sessions.length);
+	const allocated = sessions.map((session) => allocatePreparationMessages(session, perSessionBudget));
+	const contentTruncated = allocated.some((session) => session.contentTruncated === true);
+	return build(allocated, inventory, contentTruncated);
+}
+
 interface ToolParams {
+	operation?: "prepare-pattern-miner";
+	scope?: "repository" | "all";
 	query?: string;
 	sessionId?: string;
 	aroundMessageId?: string;
@@ -90,6 +271,7 @@ interface ToolParams {
 
 const DESCRIPTION = `Search past Pi sessions locally with FTS5; returns stored messages.
 
+- \`operation: "prepare-pattern-miner"\` + \`scope\`: prepare one bounded corpus and repository inventory.
 - \`query\`: discover matches. Prefer distinctive identifiers or uncommon terms; multi-word queries are AND. Use \`OR\`/\`NOT\` for Boolean queries and quotes only when exact wording is known.
 - \`sessionId\` + \`aroundMessageId\`: scroll ±\`window\`; retain \`branchTip\` across forks.
 - \`sessionId\` alone: read; no args: browse recent sessions.
@@ -117,12 +299,14 @@ export default function (pi: ExtensionAPI): void {
 			"Use session_search only when the user explicitly asks about past Pi sessions, historical decisions, or repeated work not available in the current conversation. Do not use it for current-session continuation or ordinary repository inspection.",
 		],
 		parameters: Type.Object({
+			operation: Type.Optional(StringEnum(["prepare-pattern-miner"] as const)),
+			scope: Type.Optional(StringEnum(["repository", "all"] as const)),
 			query: Type.Optional(Type.String({ description: "Search query (discovery). FTS5 syntax supported." })),
 			sessionId: Type.Optional(Type.String({ description: "Absolute path of the session file." })),
 			aroundMessageId: Type.Optional(Type.String({ description: "Anchor entry id for scroll mode — centers the window (with sessionId)." })),
 			branchTip: Type.Optional(Type.String({ description: "Branch tip entry id from a previous response — selects which branch of a forked session to scroll; aroundMessageId must lie on it." })),
 			window: Type.Optional(Type.Number({ description: "Scroll window radius, [1,20], default 5." })),
-			limit: Type.Optional(Type.Number({ description: "Max results, [1,10], default 3." })),
+			limit: Type.Optional(Type.Number({ description: "Max results, [1,10]. Defaults to 10 for preparation and 3 otherwise." })),
 			detail: Type.Optional(StringEnum(["adaptive", "full"] as const)),
 		}),
 		renderResult(result, { expanded }, theme) {
@@ -140,8 +324,39 @@ export default function (pi: ExtensionAPI): void {
 				invalidate() {},
 			};
 		},
-		async execute(_toolCallId, rawParams: ToolParams, _signal, _onUpdate, ctx) {
+		async execute(_toolCallId, rawParams: ToolParams, signal, _onUpdate, ctx) {
 			try {
+				if (rawParams.operation !== undefined && rawParams.operation !== "prepare-pattern-miner") {
+					throw new Error("Unsupported session_search operation.");
+				}
+				if (rawParams.scope !== undefined && rawParams.operation === undefined) {
+					throw new Error("scope requires operation: prepare-pattern-miner.");
+				}
+				if (rawParams.operation === "prepare-pattern-miner") {
+					const incompatible = (["query", "sessionId", "aroundMessageId", "branchTip", "window", "detail"] as const)
+						.filter((key) => rawParams[key] !== undefined);
+					if (incompatible.length > 0) {
+						throw new Error(`prepare-pattern-miner does not accept: ${incompatible.join(", ")}.`);
+					}
+					if (rawParams.scope !== "repository" && rawParams.scope !== "all") {
+						throw new Error("prepare-pattern-miner requires scope: repository or all.");
+					}
+					const limit = clamp(rawParams.limit, 1, 10, 10);
+					const inventory = await inventoryRepository(
+						pi,
+						{ cwd: ctx.cwd, signal },
+						rawParams.scope === "repository" ? "required" : "optional",
+					);
+					const sync = syncSessions(sessionsDir(), dbPath());
+					const currentSessionPath = ctx.sessionManager.getSessionFile() ?? undefined;
+					const rows = getPreparationRows(dbPath(), {
+						limit,
+						...(rawParams.scope === "repository" ? { repositoryRoot: inventory.gitRoot! } : {}),
+						currentSessionPath,
+					});
+					return textResult(buildPreparationResult(rawParams.scope, limit, inventory.gitRoot, sync, rows, inventory));
+				}
+
 				// LLMs sometimes send numeric ids/queries despite the string schema.
 				const params: ToolParams = {
 					query: rawParams.query != null ? String(rawParams.query) : undefined,
@@ -199,6 +414,7 @@ export default function (pi: ExtensionAPI): void {
 							(cap) => ({
 								mode: "read",
 								sessionId,
+								branchTip: r.branchTip,
 								totalMessages: r.totalMessages,
 								truncated: r.truncated,
 								messages: cap === null ? [] : truncateContent(r.messages, cap),

package/extensions/types.ts

@@ -22,6 +22,12 @@ export interface SessionRow {
 	preview?: string;
 }
 
+/** Indexed metadata selected for pattern-miner preparation. */
+export interface PreparationSessionRow extends SessionRow {
+	/** Stable one-hop fork identity used to avoid duplicate evidence. */
+	lineageId: string;
+}
+
 /** One FTS discovery hit before hydration. */
 export interface SearchHit {
 	path: string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@henryqw/pi-session-recall",
-	"version": "2.0.0",
+	"version": "2.1.0",
 	"description": "Local FTS5 search over past Pi sessions plus a skill for turning recurring work into deterministic automation.",
 	"keywords": [
 		"pi-package",

package/skills/pi-session-pattern-miner/SKILL.md

@@ -5,22 +5,60 @@ description: Mine repeated work, corrections, and manual procedures from past Pi
 
 # Pi Session Pattern Miner
 
-Find repeated work in past Pi sessions and turn the best-supported pattern into an automation candidate. Use `session_search` for session history; do not scan Pi session files directly. The current model mines the evidence once; the resulting automation should remove model judgment from recurring execution wherever the workflow permits it.
+Find repeated work in past Pi sessions. Turn the best-supported pattern into the smallest useful automation.
 
-## Scope
+Use `session_search` for session history. Do not scan Pi session files directly.
 
-Use the scope or topic in the request. Otherwise sample recent sessions. If the user specifies the current repository, use the current Git root and session `cwd` metadata to filter where possible; search distinctive repository or package names to find related sessions from other worktrees.
+## Prepare once
 
-State the sampled scope and its limits. `session_search` browse returns at most ten recent sessions, discovery is query-driven, and current live-context matches are suppressed. Its messages contain user/assistant text, not hidden thinking or tool output. Never claim exhaustive coverage or invent commands that are absent from the evidence.
+Choose the requested scope. Use `repository` for the current Git repository. Use `all` for a cross-repository request or work outside Git.
+
+Before interpretation, call `session_search` exactly once with:
+
+```json
+{
+  "operation": "prepare-pattern-miner",
+  "scope": "repository",
+  "limit": 10
+}
+```
+
+Change only `scope` when needed. Do not run manual browse, read, scroll, or inventory rounds during preparation.
+
+State the returned scope and sample count. If `sync.complete` is false, report the incomplete walk or positive backlog as a sample limitation.
+
+The prepared corpus is recent and bounded. A truncated session can omit middle episodes. Never claim exhaustive coverage.
 
 ## Mine
 
-1. Call `session_search` with only `limit: 10` to seed the sample.
-2. Read each in-scope session by `sessionId`. For a truncated session, inspect only relevant gaps with `sessionId`, `aroundMessageId`, and `window: 20`; retain `branchTip` while scrolling a fork.
-3. Extract candidate episodes: repeated user intents, corrections, manual procedures, avoidable retries, and agent-authored steps that recur. Ignore generic coding work such as inspect/edit/test unless the same concrete procedure repeats.
-4. Cluster by underlying job, not wording. A pattern needs evidence from at least two independent sessions; do not count forks, retries, or continuations of one task as separate evidence.
-5. Confirm each candidate with one or more distinctive `query` searches using `limit: 10` and `detail: "full"`. Record session path, date or name, relevant entry id, and a short paraphrase. Do not copy secrets or unnecessary transcript text.
-6. Inspect the current repository's commands, package scripts, executable scripts, skills, and agent instructions before proposing anything. Reuse or repair an existing automation when it already owns the workflow.
+The model performs these steps. Do not replace them with mechanical keyword rules.
+
+1. Identify semantic episodes, including repeated intents, corrections, retries, manual procedures, and recurring agent-authored steps.
+2. Ignore generic inspect, edit, and test work unless the same concrete procedure repeats.
+3. Cluster episodes by their underlying job, not their wording.
+4. Treat sessions with equal `lineageId` values as one source.
+5. Choose the owning automation surface from the prepared inventory and targeted repository evidence.
+6. Write the recommendation and implementation contract.
+
+A user-supplied topic is already a candidate. Run a focused confirmation search even when that topic is absent from the prepared sample.
+
+For other work, create a candidate from the prepared corpus before running optional searches. Do not search speculatively when no topic or candidate exists.
+
+Confirm a candidate with one or more distinctive `query` calls. Use `limit: 10`. Record the session path, date or name, relevant entry ID, and a short paraphrase.
+
+Do not copy secrets or unnecessary transcript text. Do not count forks, retries, or continuations of one task as independent evidence.
+
+## Verify ownership
+
+After clustering, use the inventory only to find likely owners. It is not ownership proof and does not verify the current worktree.
+
+Always inspect the current candidate-relevant package manifests, executable scripts, skill files, and instruction files before assigning ownership. Do this even when the inventory is available and complete.
+
+Reuse or repair existing automation when it already owns the workflow. If targeted current-file verification cannot be performed safely, abstain.
+
+## Evidence gate
+
+A recommendation requires two independent examples. This gate is mandatory.
 
 Stop with “not enough repeated evidence” when fewer than two independent sessions support a pattern. Do not manufacture a recommendation from one occurrence.
 
@@ -29,12 +67,14 @@ Stop with “not enough repeated evidence” when fewer than two independent ses
 Stop at the first option that fully handles the pattern:
 
 1. **Existing command or skill** — document, fix, or invoke it instead of adding another path.
-2. **Script** — choose when inputs, decisions, outputs, and failures can be specified without model judgment. Prefer a repository command or standard-library script over a new dependency.
-3. **Script plus thin skill** — choose when an agent must gather inputs or explain results, but the repeated operation itself can be deterministic. The skill must call the script rather than restate its algorithm.
-4. **Skill only** — choose only when the reusable work inherently requires judgment, repository inspection, or user decisions.
-5. **Product change** — choose when the root cause belongs in an extension, API, CI check, or other code rather than agent instructions.
+2. **Script** — use when inputs, decisions, outputs, and failures need no model judgment.
+3. **Script plus thin skill** — use when an agent gathers inputs, but a script performs the repeated operation.
+4. **Skill only** — use only when the reusable work inherently requires judgment, repository inspection, or user decisions.
+5. **Product change** — use when the root cause belongs in an extension, API, CI check, or other code.
 
-A deterministic candidate must define its trigger, inputs, outputs, side effects, failure behavior, and one runnable check. If those cannot be defined from session evidence plus the current codebase, recommend a focused investigation instead of automation.
+Prefer a repository command or standard-library script. Add no dependency without evidence that existing tools cannot handle the job.
+
+A deterministic candidate must define its trigger, inputs, outputs, side effects, failure behavior, and one runnable check. Recommend investigation when evidence cannot define these details.
 
 ## Report
 
@@ -43,7 +83,9 @@ Return at most three ranked patterns:
 | Pattern | Independent sessions | Repeated cost or failure | Existing coverage | Smallest automation |
 | --- | ---: | --- | --- | --- |
 
-For each pattern, cite the session paths and entry ids, explain why the proposed owning surface fits, and state what model work it removes. Then give the highest-confidence candidate a minimal implementation contract:
+For each pattern, cite session paths and entry IDs. Explain why the owning surface fits and what model work it removes.
+
+Give the highest-confidence candidate a minimal implementation contract:
 
 - **Trigger and inputs**
 - **Deterministic steps**