pi-crew 0.11.0 → 0.11.2

package/src/worktree/worktree-manager.ts

@@ -21,6 +21,19 @@ export interface PreparedTaskWorkspace {
 	syntheticPaths?: string[];
 }
 
+/**
+ * Options for prepareTaskWorkspace / prepareTaskWorkspaceAsync (RR-010).
+ */
+export interface PrepareTaskWorkspaceOptions {
+	/**
+	 * RR-010 / AGENTS.md rule 40: allow discarding a dirty reused worktree EVEN
+	 * WHEN the recovery snapshot is incomplete (truncated/skipped entries, failed
+	 * tracked diff). Explicit per-call escape hatch — deliberately NOT a global
+	 * config flag, so approval cannot silently become permanent.
+	 */
+	force?: boolean;
+}
+
 const execFileAsync = promisify(execFile);
 
 export interface WorktreeDiffStat {
@@ -657,14 +670,140 @@ export function overlaySeedPaths(repoRoot: string, worktreePath: string, seedPat
 	}
 }
 
+/**
+ * Per-file byte cap for the recovery-snapshot PREVIEW (ST-1, kept at 256 KiB so
+ * the artifact stays readable). RR-010 (F01): the cap now ALSO bounds how many
+ * bytes are read (allocation bound) and marks over-cap entries as an
+ * INCOMPLETE backup — completeness, not preview size, gates the destructive
+ * reuse cleanup (AGENTS.md rule 40).
+ */
+export const SNAPSHOT_MAX_FILE_BYTES = 256 * 1024;
+
+/** Entry whose backup was cut at SNAPSHOT_MAX_FILE_BYTES (partial capture). */
+export interface WorktreeSnapshotTruncatedEntry {
+	/** Repo-relative path of the entry. */
+	path: string;
+	/** On-disk size in bytes BEFORE truncation (not the truncated size). */
+	originalSize: number;
+}
+
+/** Entry that could not be backed up at all — absent from the artifact content. */
+export interface WorktreeSnapshotSkippedEntry {
+	/** Repo-relative path of the entry. */
+	path: string;
+	/** Why the entry was skipped (unreadable, unstat-able, missing, directory...). */
+	reason: string;
+}
+
+/**
+ * Structured result of a dirty-worktree recovery snapshot (RR-010 / F01).
+ *
+ * A bare boolean could not distinguish "artifact written" from "backup
+ * complete": truncation at the cap, unreadable entries and a failed tracked
+ * diff all used to return `true`, so the reuse path ran `git checkout -- .` +
+ * `git clean -fd` and destroyed data the artifact never contained. `complete`
+ * is the invariant `truncated/skipped empty && no diff/write error` — callers
+ * must gate the destructive cleanup on it via shouldDiscardDirtyWorktree.
+ */
+export interface WorktreeSnapshotResult {
+	/** True ONLY when every dirty entry was fully backed up and the tracked diff (if any) was captured. */
+	complete: boolean;
+	/** Entries backed up only partially (cut at the preview cap). */
+	truncated: WorktreeSnapshotTruncatedEntry[];
+	/** Entries that could not be backed up at all. */
+	skipped: WorktreeSnapshotSkippedEntry[];
+	/** Set when `git diff HEAD --binary` failed — tracked changes may be lost. */
+	trackedDiffError?: string;
+	/** Set when writing the recovery artifact itself failed (the old `false`). */
+	writeError?: string;
+}
+
+/**
+ * Pure, git-free gate for the destructive reuse cleanup (RR-010 AC4): discard
+ * dirty worktree content ONLY when the snapshot is complete, or when the caller
+ * explicitly set `force` (AGENTS.md rule 40). Fail CLOSED — when in doubt,
+ * preserve the worktree.
+ */
+export function shouldDiscardDirtyWorktree(result: WorktreeSnapshotResult, force: boolean): boolean {
+	return force || result.complete;
+}
+
+/**
+ * Allocation-bounded file read for the recovery snapshot (RR-010 AC5).
+ * Opens the file and reads at most `cap` bytes — `readFileSync` would allocate
+ * the WHOLE file in memory just to truncate it afterwards, so a multi-GiB
+ * untracked file could OOM the snapshot path. A short read (file shrank
+ * mid-read) is reported as truncated so it can never count as a complete
+ * backup (fail closed).
+ */
+export function readFileCappedForSnapshot(abs: string, cap: number): { data: Buffer; originalSize: number; truncated: boolean } {
+	const fd = fs.openSync(abs, "r");
+	try {
+		const originalSize = fs.fstatSync(fd).size;
+		const want = Math.min(originalSize, cap);
+		const data = Buffer.alloc(want);
+		let read = 0;
+		while (read < want) {
+			const n = fs.readSync(fd, data, read, want - read, read);
+			if (n <= 0) break;
+			read += n;
+		}
+		return {
+			data: read === want ? data : data.subarray(0, read),
+			originalSize,
+			truncated: read < want || originalSize > cap,
+		};
+	} finally {
+		fs.closeSync(fd);
+	}
+}
+
+/** Human-readable incompleteness summary for the dirtyPreserved log (RR-010). */
+function describeIncompleteSnapshot(result: WorktreeSnapshotResult): string {
+	const reasons: string[] = [];
+	if (result.writeError !== undefined) reasons.push(`snapshot write failed: ${result.writeError}`);
+	if (result.trackedDiffError !== undefined) reasons.push(`tracked diff capture failed: ${result.trackedDiffError}`);
+	if (result.truncated.length > 0)
+		reasons.push(
+			`${result.truncated.length} file(s) exceeded the ${SNAPSHOT_MAX_FILE_BYTES}-byte cap: ${result.truncated
+				.map((e) => `${e.path} (${e.originalSize} bytes)`)
+				.join(", ")}`,
+		);
+	if (result.skipped.length > 0)
+		reasons.push(
+			`${result.skipped.length} unreadable/unstat-able entries: ${result.skipped.map((e) => `${e.path} (${e.reason})`).join(", ")}`,
+		);
+	return reasons.length > 0 ? ` — ${reasons.join("; ")}` : "";
+}
+
 /**
  * Snapshot uncommitted work in a reused worktree to a recovery artifact BEFORE
  * discarding it, so the data is never silently lost. Captures tracked changes
  * (git diff HEAD) and inlines untracked file contents so the work can be
- * recovered via `git apply` / manual restore. Best-effort: a snapshot failure
- * only logs (it must not block the clean-slate reuse flow).
+ * recovered via `git apply` / manual restore.
+ *
+ * RR-010 (F01) — returns a structured WorktreeSnapshotResult. An artifact that
+ * was written is NOT proof the backup is complete: truncated (over-cap /
+ * short-read) entries, unreadable entries and a failed tracked diff all surface
+ * in the result so callers can refuse the destructive cleanup
+ * (shouldDiscardDirtyWorktree). Design choice (RR-010 design.md §3–§4):
+ * structured result + pure predicate over raising the cap (moves the boundary,
+ * does not remove it), louder warnings (violates AGENTS.md rule 40), full
+ * base64 (artifact size explodes), dropping cleanup entirely (breaks
+ * clean-slate reuse; `force` stays as the escape hatch) and `git stash` (also a
+ * destructive git op with no artifact trail). The 256 KiB PREVIEW cap is kept
+ * on purpose — backup completeness, not preview size, gates cleanup.
  */
-export function snapshotDirtyWorktree(manifest: TeamRunManifest, task: TeamTaskState, worktreePath: string, dirtyStatus: string): boolean {
+export function snapshotDirtyWorktree(
+	manifest: TeamRunManifest,
+	task: TeamTaskState,
+	worktreePath: string,
+	dirtyStatus: string,
+): WorktreeSnapshotResult {
+	const truncated: WorktreeSnapshotTruncatedEntry[] = [];
+	const skipped: WorktreeSnapshotSkippedEntry[] = [];
+	let trackedDiffError: string | undefined;
+	let writeError: string | undefined;
 	try {
 		const parts: string[] = [
 			`# Worktree recovery snapshot`,
@@ -676,14 +815,16 @@ export function snapshotDirtyWorktree(manifest: TeamRunManifest, task: TeamTaskS
 		let trackedDiff = "";
 		try {
 			trackedDiff = git(worktreePath, ["diff", "HEAD", "--binary"]);
-		} catch {
+		} catch (err) {
+			// RR-010: "" stays reserved for the legitimate "no tracked changes" outcome —
+			// a FAILED diff is an incomplete backup (tracked edits would be destroyed by
+			// `git checkout -- .` with no copy anywhere).
 			trackedDiff = "";
+			trackedDiffError = err instanceof Error ? err.message : String(err);
 		}
 		if (trackedDiff.trim()) {
 			parts.push("## Tracked changes (`git diff HEAD --binary`)", "```diff", trackedDiff, "```", "");
 		}
-		// ST-1: per-file byte cap — skip/truncate larger files with a note to avoid OOM.
-		const MAX_FILE_BYTES = 256 * 1024;
 		for (const line of dirtyStatus.split("\n")) {
 			if (!line.startsWith("?? ")) continue;
 			// Strip the "?? " prefix and surrounding git quotes.
@@ -691,15 +832,24 @@ export function snapshotDirtyWorktree(manifest: TeamRunManifest, task: TeamTaskS
 			if (!rel) continue;
 			try {
 				const abs = path.join(worktreePath, rel);
-				if (!fs.existsSync(abs) || fs.statSync(abs).isDirectory()) continue;
+				if (!fs.existsSync(abs)) {
+					// RR-010: record instead of silently `continue` — a vanished entry is
+					// unexplained and must fail CLOSED (preserve, do not clean).
+					skipped.push({ path: rel, reason: "not found (deleted between status and snapshot?)" });
+					continue;
+				}
+				if (fs.statSync(abs).isDirectory()) {
+					skipped.push({ path: rel, reason: "directory entry — individual files must be captured instead" });
+					continue;
+				}
 				// ST-1: read raw bytes (not utf-8) so binary files are not corrupted.
-				const buf = fs.readFileSync(abs);
-				const originalSize = buf.byteLength;
-				let data: Buffer = buf;
+				// RR-010: bounded read — never allocate more than the cap for a file that
+				// is only going to be truncated anyway (AC5).
+				const { data, originalSize, truncated: overCap } = readFileCappedForSnapshot(abs, SNAPSHOT_MAX_FILE_BYTES);
 				let note = "";
-				if (originalSize > MAX_FILE_BYTES) {
-					data = buf.subarray(0, MAX_FILE_BYTES);
-					note = ` (truncated: ${originalSize} → ${MAX_FILE_BYTES} bytes)`;
+				if (overCap) {
+					truncated.push({ path: rel, originalSize });
+					note = ` (truncated: ${originalSize} → ${data.byteLength} bytes)`;
 				}
 				// ST-1: detect non-UTF-8 via fatal TextDecoder; base64-encode binary files.
 				let isUtf8 = true;
@@ -713,10 +863,22 @@ export function snapshotDirtyWorktree(manifest: TeamRunManifest, task: TeamTaskS
 				} else {
 					parts.push(`## Untracked file: ${rel}${note} (base64-encoded binary)`, "```base64", data.toString("base64"), "```", "");
 				}
-			} catch {
-				/* skip unreadable/unstat-able entry */
+			} catch (err) {
+				// RR-010: unreadable/unstat-able entries are recorded (and named in the
+				// artifact below) instead of being silently dropped — they used to be
+				// destroyed by `git clean -fd` with ZERO recovery.
+				skipped.push({ path: rel, reason: err instanceof Error ? err.message : String(err) });
 			}
 		}
+		// RR-010 (AC3): skipped entries MUST be named in the artifact so operators
+		// can see exactly which files were NOT backed up before deciding to force a
+		// cleanup — an artifact silent about them is false evidence.
+		if (skipped.length > 0) {
+			parts.push("## Skipped entries (NOT backed up)", ...skipped.map((s) => `- ${s.path} — ${s.reason}`), "");
+		}
+		if (trackedDiffError !== undefined) {
+			parts.push("## Tracked diff capture FAILED — tracked modifications are NOT backed up", "```", trackedDiffError, "```", "");
+		}
 		writeArtifact(manifest.artifactsRoot, {
 			kind: "diff",
 			relativePath: `worktree-recovery/${task.id}-${Date.now()}.md`,
@@ -724,15 +886,16 @@ export function snapshotDirtyWorktree(manifest: TeamRunManifest, task: TeamTaskS
 			producer: "worktree-manager.snapshotDirtyWorktree",
 			retention: "run",
 		});
-		return true;
 	} catch (err) {
 		logInternalError(
 			"worktree.recovery.snapshotFailed",
 			err instanceof Error ? err : new Error(String(err)),
 			`runId=${manifest.runId}, taskId=${task.id}`,
 		);
-		return false;
+		writeError = err instanceof Error ? err.message : String(err);
 	}
+	const complete = truncated.length === 0 && skipped.length === 0 && trackedDiffError === undefined && writeError === undefined;
+	return { complete, truncated, skipped, trackedDiffError, writeError };
 }
 
 /**
@@ -775,7 +938,12 @@ async function cleanupCreatedWorktreeAsync(repoRoot: string, worktreePath: strin
 	}
 }
 
-export function prepareTaskWorkspace(manifest: TeamRunManifest, task: TeamTaskState, stepSeedPaths?: string[]): PreparedTaskWorkspace {
+export function prepareTaskWorkspace(
+	manifest: TeamRunManifest,
+	task: TeamTaskState,
+	stepSeedPaths?: string[],
+	options?: PrepareTaskWorkspaceOptions,
+): PreparedTaskWorkspace {
 	if (manifest.workspaceMode !== "worktree") return { cwd: task.cwd };
 	const repoRoot = findGitRoot(manifest.cwd);
 	const loadedConfig = loadConfig(manifest.cwd);
@@ -852,11 +1020,17 @@ export function prepareTaskWorkspace(manifest: TeamRunManifest, task: TeamTaskSt
 		if (dirtyStatus.trim()) {
 			// Snapshot uncommitted work to a recovery artifact BEFORE discarding, so the
 			// previous run's changes are never silently destroyed on reuse.
-			const snapshotOk = snapshotDirtyWorktree(manifest, task, worktreePath, dirtyStatus);
-			if (snapshotOk) {
+			// RR-010 (F01): discard only when the snapshot is COMPLETE (or the caller
+			// explicitly forced it) — AGENTS.md rule 40. An artifact that was written
+			// is not proof the backup is complete; fail CLOSED and preserve.
+			const snapshotResult = snapshotDirtyWorktree(manifest, task, worktreePath, dirtyStatus);
+			if (shouldDiscardDirtyWorktree(snapshotResult, options?.force === true)) {
 				logInternalError(
 					"worktree.reused.dirty",
-					new Error(`Discarding uncommitted changes in reused worktree at ${worktreePath} (snapshot saved to artifacts)`),
+					new Error(
+						`Discarding uncommitted changes in reused worktree at ${worktreePath} (snapshot saved to artifacts)` +
+							(snapshotResult.complete ? "" : " — SNAPSHOT INCOMPLETE, discarded because caller set force=true"),
+					),
 					`runId=${manifest.runId}, taskId=${task.id}, dirtyStatus=${dirtyStatus.trim()}`,
 				);
 				git(worktreePath, ["checkout", "--", "."]);
@@ -865,7 +1039,7 @@ export function prepareTaskWorkspace(manifest: TeamRunManifest, task: TeamTaskSt
 				logInternalError(
 					"worktree.reused.dirtyPreserved",
 					new Error(
-						`Snapshot failed — preserving dirty worktree at ${worktreePath} (skipping git checkout/clean to prevent data loss)`,
+						`Snapshot incomplete — preserving dirty worktree at ${worktreePath} (skipping git checkout/clean to prevent data loss)${describeIncompleteSnapshot(snapshotResult)}`,
 					),
 					`runId=${manifest.runId}, taskId=${task.id}, dirtyStatus=${dirtyStatus.trim()}`,
 				);
@@ -948,6 +1122,7 @@ export async function prepareTaskWorkspaceAsync(
 	manifest: TeamRunManifest,
 	task: TeamTaskState,
 	stepSeedPaths?: string[],
+	options?: PrepareTaskWorkspaceOptions,
 ): Promise<PreparedTaskWorkspace> {
 	if (manifest.workspaceMode !== "worktree") return { cwd: task.cwd };
 	const repoRoot = await findGitRootAsync(manifest.cwd);
@@ -1012,11 +1187,16 @@ export async function prepareTaskWorkspaceAsync(
 		// ST-1: use -uall so untracked directories are expanded to individual files.
 		const dirtyStatus = await gitAsync(worktreePath, ["-c", "core.quotePath=false", "status", "--porcelain", "-uall"]);
 		if (dirtyStatus.trim()) {
-			const snapshotOk = snapshotDirtyWorktree(manifest, task, worktreePath, dirtyStatus);
-			if (snapshotOk) {
+			// RR-010 (F01): mirror of the sync gate — discard only when the snapshot is
+			// COMPLETE (or explicitly forced). AGENTS.md rule 40. Fail CLOSED.
+			const snapshotResult = snapshotDirtyWorktree(manifest, task, worktreePath, dirtyStatus);
+			if (shouldDiscardDirtyWorktree(snapshotResult, options?.force === true)) {
 				logInternalError(
 					"worktree.reused.dirty",
-					new Error(`Discarding uncommitted changes in reused worktree at ${worktreePath} (snapshot saved to artifacts)`),
+					new Error(
+						`Discarding uncommitted changes in reused worktree at ${worktreePath} (snapshot saved to artifacts)` +
+							(snapshotResult.complete ? "" : " — SNAPSHOT INCOMPLETE, discarded because caller set force=true"),
+					),
 					`runId=${manifest.runId}, taskId=${task.id}, dirtyStatus=${dirtyStatus.trim()}`,
 				);
 				await gitAsync(worktreePath, ["checkout", "--", "."]);
@@ -1025,7 +1205,7 @@ export async function prepareTaskWorkspaceAsync(
 				logInternalError(
 					"worktree.reused.dirtyPreserved",
 					new Error(
-						`Snapshot failed — preserving dirty worktree at ${worktreePath} (skipping git checkout/clean to prevent data loss)`,
+						`Snapshot incomplete — preserving dirty worktree at ${worktreePath} (skipping git checkout/clean to prevent data loss)${describeIncompleteSnapshot(snapshotResult)}`,
 					),
 					`runId=${manifest.runId}, taskId=${task.id}, dirtyStatus=${dirtyStatus.trim()}`,
 				);

package/workflows/distill.workflow.md

@@ -144,7 +144,7 @@ output: apply-plan.md
 - **HOW to apply**: AGENTS.md edit, lint rule add, src/ pattern adopt, CONTRIBUTING.md update, scripts/ operational script, or skill in target's skills/ dir
 - **Exact file:line target** in the target project
 - **Tier priority**: Tier 1 (high V3, low V4 cost) → Tier 2 (high V3, medium V4 cost) → Tier 3 (high V3, high V4 cost — pilot first)
-- **Verification gate per item**: `npm run test:critical` + `npm run typecheck` + `npm run build:bundle` must pass after each apply; bundle MD5 must match or be updated; if tests fail → rollback
+- **Verification gate per item**: `npm run test:critical` + `npm run typecheck` + `npm run build:bundle` must pass after each apply; bundle MD5 must match or be updated; if tests fail → rollback. (If the TARGET project is not this repo or lacks these scripts, use its fastest documented check gate instead — never run a full suite per item.)
 
 Write to `references/apply-plan.md`. This is the input for the executor in Phase 4.
 
@@ -157,7 +157,7 @@ output: applied-changes.md
 
 Per-item protocol:
 1. Edit the target file(s) as specified in apply-plan.md
-2. Run verification gate: `npm run test:critical` (or equivalent) + `npm run typecheck` + `npm run build:bundle`
+2. Run verification gate: `npm run test:critical` (or the target's fastest documented check) + `npm run typecheck` + `npm run build:bundle`
 3. Capture before/after diff + bundle MD5 (before/after)
 4. If any gate fails → rollback the change (git checkout the file), log REJECTED in APPLY-LOG, continue with next item
 5. If passes → log APPLIED in APPLY-LOG with file:line
@@ -173,7 +173,7 @@ verify: true
 
 **Phase 5 (new — Darwin ratchet).** The output of a distillation is NOT "has skill" — it's "target improved." Read `applied-changes.md` + the target project's git diff. For each APPLIED item, re-verify:
 - Does the change actually improve the target? (concrete, measurable — e.g. "new helper reduces 18 sites to 1 import"; not vibes)
-- Do the tests still pass? (`npm run test:critical`)
+- Do the tests still pass? (`npm run test:critical` — or the target's fastest documented check; never the full suite per item)
 - Did the bundle MD5 change as expected? (intentional change OK; unexpected change → flag)
 - Is the change consistent with target's existing style/conventions? (no foreign code injected)
 

package/workflows/fast-fix.workflow.md

@@ -21,4 +21,4 @@ dependsOn: execute
 verify: true
 
 Verify the fix with available evidence.
-Run FAST checks ONCE (cache output to .crew/cache/): `npm run test:critical && npx tsc --noEmit` (completes in <60s). Do NOT run `npm run test:unit` or `npm test` — too slow (642 files, >4 min). Cross-reference cached output with the fix. Do NOT re-run tests. Give PASS or FAIL with specific test evidence.
+Run FAST checks ONCE and cache output WITH provenance to `.crew/cache/` (per `agents/verifier.md`: unique per-attempt filename, `set -o pipefail` so the recorded exit code is the command's — not `tee`'s — and a sibling `.meta` recording command, git revision, tree fingerprint): `npm run test:critical && npx tsc --noEmit` (completes in <60s; if this repo lacks these scripts, use its fastest documented check instead). Do NOT run `npm run test:unit` or `npm test` — too slow (642 files, >4 min). Cross-reference cached output with the fix — reuse a cached log only when its provenance matches. Do NOT re-run tests. Give PASS or FAIL with specific test evidence.

package/workflows/plan-execute.workflow.md

@@ -27,4 +27,4 @@ dependsOn: execute
 verify: true
 
 Verify completion for: {goal}
-Run FAST checks ONCE (cache output to .crew/cache/): `npm run test:critical && npx tsc --noEmit` (completes in <60s). Do NOT run `npm run test:unit` or `npm test` — too slow (642 files, >4 min). Cross-reference cached output with the changes. Do NOT re-run tests. Give PASS or FAIL with specific test evidence.
+Run FAST checks ONCE and cache output WITH provenance to `.crew/cache/` (per `agents/verifier.md`: unique per-attempt filename, `set -o pipefail` so the recorded exit code is the command's — not `tee`'s — and a sibling `.meta` recording command, git revision, tree fingerprint): `npm run test:critical && npx tsc --noEmit` (completes in <60s; if this repo lacks these scripts, use its fastest documented check instead). Do NOT run `npm run test:unit` or `npm test` — too slow (642 files, >4 min). Cross-reference cached output with the changes — reuse a cached log only when its provenance matches. Do NOT re-run tests. Give PASS or FAIL with specific test evidence.

package/workflows/review.workflow.md

@@ -28,4 +28,4 @@ role: verifier
 dependsOn: code-review, security-review
 verify: true
 
-Run FAST checks ONCE (cache output to .crew/cache/): `npm run test:critical && npx tsc --noEmit` (completes in <60s). Do NOT run `npm run test:unit` or `npm test` — too slow (642 files, >4 min). Cross-reference cached output with reviewer and security-reviewer findings. Confirm each finding against real test output. Give PASS if findings match evidence, FAIL if critical findings are false positives or tests reveal new issues.
+Run FAST checks ONCE and cache output WITH provenance to `.crew/cache/` (per `agents/verifier.md`: unique per-attempt filename, `set -o pipefail` so the recorded exit code is the command's — not `tee`'s — and a sibling `.meta` recording command, git revision, tree fingerprint): `npm run test:critical && npx tsc --noEmit` (completes in <60s; if this repo lacks these scripts, use its fastest documented check instead). Do NOT run `npm run test:unit` or `npm test` — too slow (642 files, >4 min). Cross-reference cached output with reviewer and security-reviewer findings — reuse a cached log only when its provenance matches. Confirm each finding against real test output. Give PASS if findings match evidence, FAIL if critical findings are false positives or tests reveal new issues.

package/workflows/strict-fast-fix.workflow.md

@@ -23,4 +23,4 @@ dependsOn: execute
 verify: true
 
 Verify the fix with available evidence, AND cross-reference the SPEC-EVIDENCE footer from explore+execute against the spec's requirements (machine-check the citations vs the spec id set).
-Run FAST checks ONCE (cache output to .crew/cache/): `npm run test:critical && npx tsc --noEmit` (completes in <60s). Do NOT run `npm run test:unit` or `npm test` — too slow (642 files, >4 min). Cross-reference cached output with the fix. Do NOT re-run tests. Give PASS or FAIL with specific test evidence + spec gate verdict.
+Run FAST checks ONCE and cache output WITH provenance to `.crew/cache/` (per `agents/verifier.md`: unique per-attempt filename, `set -o pipefail` so the recorded exit code is the command's — not `tee`'s — and a sibling `.meta` recording command, git revision, tree fingerprint): `npm run test:critical && npx tsc --noEmit` (completes in <60s; if this repo lacks these scripts, use its fastest documented check instead). Do NOT run `npm run test:unit` or `npm test` — too slow (642 files, >4 min). Cross-reference cached output with the fix — reuse a cached log only when its provenance matches. Do NOT re-run tests. Give PASS or FAIL with specific test evidence + spec gate verdict.

package/docs/migration-v0.4-v0.5.md

@@ -1,208 +0,0 @@
-# pi-crew Migration Guide: v0.4 → v0.5
-
-**Author:** pi-crew team  
-**Date:** 2026-06-01  
-**Version:** 0.5.5 *(covers v0.4→v0.5 migration; later v0.5.x versions are drop-in replacements)*
-
----
-
-## Overview
-
-This guide covers breaking changes and new features introduced in v0.5.x.
-
----
-
-## v0.5.5 Highlights (June 2026)
-
-v0.5.5 closes 13 rounds of code review. The user-facing changes are:
-
-- **Linear-time secret redaction** at all event/mailbox/artifact boundaries.
-- **v8.deserialize hardened** with `BINARY_MAGIC` headers — old binaries are auto-discarded.
-- **Adaptive implementation workflow** now has a single `assess` step; the planner picks the smallest effective crew.
-- **Async-notifier debounce** of 30 s — completion notifications can be delayed by up to 30 s.
-- **Mailbox delivery state capped at 10000 messages** — older entries are pruned FIFO.
-- **Anchors cap at 50 with 100 handoffs each** — older handoffs are pruned FIFO.
-
-No new public API is required for any of these changes. If you pinned a `BINARY_MAGIC`-guarded binary from a previous session, delete `~/.pi/agent/pi-crew/.cache/active-run-index.bin` once.
-
-## v0.5.4 → v0.5.5 Migration
-
-No breaking changes. Drop-in replacement.
-
-## Breaking Changes
-
-### 1. Environment Variable Allowlist (Security)
-
-**Before (v0.4):**
-```typescript
-// Child Pi workers received ALL matching secrets
-"*_API_KEY",
-"*_TOKEN", 
-"*_SECRET",
-```
-
-**After (v0.5):**
-```typescript
-// Only explicit provider keys
-"ANTHROPIC_API_KEY",
-"OPENAI_API_KEY",
-"GOOGLE_API_KEY",
-// ...
-```
-
-**Action Required:** If your workflows rely on custom environment variables with `*_API_KEY` patterns, you must now explicitly list them:
-```json
-{
-  "piCrew": {
-    "runtime": {
-      "envAllowlist": ["MY_CUSTOM_API_KEY", "MY_OTHER_KEY"]
-    }
-  }
-}
-```
-
----
-
-### 2. Mock Mode Requires Dual Environment Variables
-
-**Before (v0.4):**
-```bash
-PI_TEAMS_MOCK_CHILD_PI=success  # Works silently
-```
-
-**After (v0.5):**
-```bash
-PI_TEAMS_MOCK_CHILD_PI=success
-PI_CREW_ALLOW_MOCK=1  # Required for security
-```
-
-**Action Required:** Update CI/CD and test scripts that use mock mode.
-
----
-
-### 3. Skill Frontmatter Format
-
-**Before (v0.4):**
-```yaml
----
-name: my-skill
-description: "My skill description"
----
-```
-
-**After (v0.5):**
-```yaml
----
-name: my-skill
-description: "My skill description"
-triggers:
-  - "trigger phrase 1"
-  - "trigger phrase 2"
----
-```
-
-**Action Required:** Run `node scripts/check-all-skills.ts` to identify skills needing `triggers` field.
-
----
-
-## New Features in v0.5
-
-### 1. Enhanced Security
-
-- **Secure env allowlist**: Only explicit API keys passed to child processes
-- **Mock mode protection**: Requires `PI_CREW_ALLOW_MOCK=1` alongside `PI_TEAMS_MOCK_CHILD_PI`
-- **Worktree hook hardening**: Safer execution on Windows
-
-### 2. Improved Reliability
-
-- **Terminal event durability**: Critical events (task.completed, task.failed) now bypass event buffering
-- **Race condition fixes**: Foreground interrupt requests are now properly serialized
-- **File descriptor cleanup**: Background runner properly closes log file descriptors
-
-### 3. Better Observability
-
-- **Reduced cache TTL**: Manifest cache now expires in 30s instead of 5min for faster state updates
-- **Decision ledger integrity**: Ledger entries are preserved during promote/decay operations
-
-### 4. Skill System
-
-- **Standardized triggers**: All 35 built-in skills now have explicit trigger phrases
-- **Enforcement gates**: Skills include checklist-based enforcement sections
-- **Anti-patterns**: Most skills include anti-pattern documentation
-
----
-
-## Configuration Changes
-
-### New Config Keys
-
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `limits.heartbeatStaleMs` | number | 30000 | Stale heartbeat threshold |
-| `runtime.effectivenessGuard` | string | "off" | Effectiveness guard level |
-| `runtime.completionMutationGuard` | string | "off" | Mutation guard level |
-
-### Deprecated Config Keys
-
-None in v0.5.
-
----
-
-## Workflow Migration
-
-### Updating Custom Agents
-
-1. Ensure agent files have `triggers` in frontmatter:
-```yaml
----
-name: my-agent
-triggers:
-  - "my trigger"
----
-```
-
-2. Verify agent is discovered:
-```bash
-team action=list agent=my-agent
-```
-
-### Updating Custom Teams
-
-1. Validate team config:
-```bash
-team action=validate resource=team name=my-team
-```
-
-2. Check for breaking changes in role/task definitions.
-
----
-
-## Testing Checklist
-
-After upgrading to v0.5:
-
-- [ ] Run `team action=doctor` to verify configuration
-- [ ] Run `node scripts/check-all-skills.ts` to verify skills
-- [ ] Test mock mode with both env vars set
-- [ ] Verify environment variables are properly filtered in child processes
-- [ ] Test foreground interrupt (cancel) behavior
-- [ ] Verify terminal events are properly logged
-
----
-
-## Rollback
-
-If issues occur after upgrade:
-
-```bash
-# Revert to v0.4.x
-pi install npm:pi-crew@0.4.x
-```
-
----
-
-## Support
-
-- **Issues**: https://github.com/baphuongna/pi-crew/issues
-- **Documentation**: [docs/](docs/)
-- **Changelog**: [CHANGELOG.md](CHANGELOG.md)