@os-eco/overstory-cli 0.6.4 → 0.6.6

package/src/agents/hooks-deployer.ts

@@ -106,6 +106,7 @@ const DANGEROUS_BASH_PATTERNS = [
  * This whitelist is checked BEFORE the blocklist.
  */
 const SAFE_BASH_PREFIXES = [
+	"ov ",
 	"overstory ",
 	"bd ",
 	"sd ",
@@ -205,6 +206,20 @@ export function getPathBoundaryGuards(): HookEntry[] {
 	];
 }
 
+/**
+ * Escape a string for use inside a single-quoted POSIX shell string.
+ *
+ * POSIX single-quoted strings cannot contain single quotes at all.
+ * The standard technique is to end the single-quoted segment, emit an escaped
+ * single quote using $'\'', then start a new single-quoted segment:
+ *   'it'\''s fine'  →  it's fine
+ *
+ * Exported so tests can verify escaping directly.
+ */
+export function escapeForSingleQuotedShell(str: string): string {
+	return str.replace(/'/g, "'\\''");
+}
+
 /**
  * Build a PreToolUse guard that blocks a specific tool.
  *
@@ -218,7 +233,7 @@ function blockGuard(toolName: string, reason: string): HookEntry {
 		hooks: [
 			{
 				type: "command",
-				command: `${ENV_GUARD} echo '${response}'`,
+				command: `${ENV_GUARD} echo '${escapeForSingleQuotedShell(response)}'`,
 			},
 		],
 	};
@@ -242,7 +257,7 @@ function buildBashGuardScript(agentName: string): string {
 		'CMD=$(echo "$INPUT" | sed \'s/.*"command": *"\\([^"]*\\)".*/\\1/\');',
 		// Check 1: Block all git push — agents must never push to remote
 		"if echo \"$CMD\" | grep -qE '\\bgit\\s+push\\b'; then",
-		'  echo \'{"decision":"block","reason":"git push is blocked — use overstory merge to integrate changes, push manually when ready"}\';',
+		'  echo \'{"decision":"block","reason":"git push is blocked — use ov merge to integrate changes, push manually when ready"}\';',
 		"  exit 0;",
 		"fi;",
 		// Check 2: Block git reset --hard
@@ -447,7 +462,7 @@ export function getCapabilityGuards(capability: string): HookEntry[] {
 	const teamToolGuards = NATIVE_TEAM_TOOLS.map((tool) =>
 		blockGuard(
 			tool,
-			`Overstory agents must use 'overstory sling' for delegation — ${tool} is not allowed`,
+			`Overstory agents must use 'ov sling' for delegation — ${tool} is not allowed`,
 		),
 	);
 	guards.push(...teamToolGuards);
@@ -458,7 +473,7 @@ export function getCapabilityGuards(capability: string): HookEntry[] {
 	const interactiveGuards = INTERACTIVE_TOOLS.map((tool) =>
 		blockGuard(
 			tool,
-			`${tool} requires human interaction -- agents run non-interactively. Use overstory mail (--type question) to escalate`,
+			`${tool} requires human interaction -- agents run non-interactively. Use ov mail (--type question) to escalate`,
 		),
 	);
 	guards.push(...interactiveGuards);
@@ -495,13 +510,16 @@ export function getCapabilityGuards(capability: string): HookEntry[] {
 /**
  * Check whether a hook entry is overstory-managed.
  *
- * Overstory hook commands always reference either `overstory` (CLI commands)
+ * Overstory hook commands always reference either `ov ` / `overstory` (CLI commands)
  * or `OVERSTORY_` (env var guards like OVERSTORY_AGENT_NAME, OVERSTORY_WORKTREE_PATH).
  * User hooks will not contain these patterns.
  */
 export function isOverstoryHookEntry(entry: HookEntry): boolean {
 	return entry.hooks.some(
-		(h) => h.command.includes("overstory") || h.command.includes("OVERSTORY_"),
+		(h) =>
+			h.command.includes("ov ") ||
+			h.command.includes("overstory") ||
+			h.command.includes("OVERSTORY_"),
 	);
 }
 

package/src/agents/identity.test.ts

@@ -72,12 +72,12 @@ describe("identity", () => {
 				expertiseDomains: [],
 				recentTasks: [
 					{
-						beadId: "beads-001",
+						taskId: "beads-001",
 						summary: "Fixed authentication bug",
 						completedAt: "2024-01-15T12:00:00Z",
 					},
 					{
-						beadId: "beads-002",
+						taskId: "beads-002",
 						summary: "Added user profile page",
 						completedAt: "2024-01-16T14:30:00Z",
 					},
@@ -89,10 +89,10 @@ describe("identity", () => {
 			const filePath = join(tempDir, "test-agent", "identity.yaml");
 			const content = await Bun.file(filePath).text();
 			expect(content).toContain("recentTasks:");
-			expect(content).toContain("\t- beadId: beads-001");
+			expect(content).toContain("\t- taskId: beads-001");
 			expect(content).toContain("\t\tsummary: Fixed authentication bug");
 			expect(content).toContain('\t\tcompletedAt: "2024-01-15T12:00:00Z"');
-			expect(content).toContain("\t- beadId: beads-002");
+			expect(content).toContain("\t- taskId: beads-002");
 			expect(content).toContain("\t\tsummary: Added user profile page");
 			expect(content).toContain('\t\tcompletedAt: "2024-01-16T14:30:00Z"');
 		});
@@ -106,7 +106,7 @@ describe("identity", () => {
 				expertiseDomains: ["domain: with colon", "domain#with hash", " leading space"],
 				recentTasks: [
 					{
-						beadId: "beads-001",
+						taskId: "beads-001",
 						summary: 'Fixed bug: "memory leak"',
 						completedAt: "2024-01-15T12:00:00Z",
 					},
@@ -198,7 +198,7 @@ describe("identity", () => {
 				expertiseDomains: ["typescript", "testing"],
 				recentTasks: [
 					{
-						beadId: "beads-001",
+						taskId: "beads-001",
 						summary: "Fixed bug",
 						completedAt: "2024-01-15T12:00:00Z",
 					},
@@ -216,7 +216,7 @@ describe("identity", () => {
 			expect(loaded?.sessionsCompleted).toBe(7);
 			expect(loaded?.expertiseDomains).toEqual(["typescript", "testing"]);
 			expect(loaded?.recentTasks).toHaveLength(1);
-			expect(loaded?.recentTasks[0]?.beadId).toBe("beads-001");
+			expect(loaded?.recentTasks[0]?.taskId).toBe("beads-001");
 			expect(loaded?.recentTasks[0]?.summary).toBe("Fixed bug");
 			expect(loaded?.recentTasks[0]?.completedAt).toBe("2024-01-15T12:00:00Z");
 		});
@@ -252,17 +252,17 @@ describe("identity", () => {
 				expertiseDomains: [],
 				recentTasks: [
 					{
-						beadId: "beads-001",
+						taskId: "beads-001",
 						summary: "Task 1",
 						completedAt: "2024-01-15T12:00:00Z",
 					},
 					{
-						beadId: "beads-002",
+						taskId: "beads-002",
 						summary: "Task 2",
 						completedAt: "2024-01-16T12:00:00Z",
 					},
 					{
-						beadId: "beads-003",
+						taskId: "beads-003",
 						summary: "Task 3",
 						completedAt: "2024-01-17T12:00:00Z",
 					},
@@ -273,9 +273,9 @@ describe("identity", () => {
 			const loaded = await loadIdentity(tempDir, "test-agent");
 
 			expect(loaded?.recentTasks).toHaveLength(3);
-			expect(loaded?.recentTasks[0]?.beadId).toBe("beads-001");
-			expect(loaded?.recentTasks[1]?.beadId).toBe("beads-002");
-			expect(loaded?.recentTasks[2]?.beadId).toBe("beads-003");
+			expect(loaded?.recentTasks[0]?.taskId).toBe("beads-001");
+			expect(loaded?.recentTasks[1]?.taskId).toBe("beads-002");
+			expect(loaded?.recentTasks[2]?.taskId).toBe("beads-003");
 		});
 
 		test("handles quoted strings with special characters", async () => {
@@ -287,7 +287,7 @@ describe("identity", () => {
 				expertiseDomains: ["domain: with colon", "domain#with hash"],
 				recentTasks: [
 					{
-						beadId: "beads-001",
+						taskId: "beads-001",
 						summary: 'Fixed bug: "memory leak"',
 						completedAt: "2024-01-15T12:00:00Z",
 					},
@@ -311,7 +311,7 @@ describe("identity", () => {
 				expertiseDomains: [],
 				recentTasks: [
 					{
-						beadId: "beads-001",
+						taskId: "beads-001",
 						summary: "Path: C:\\Users\\test\\file.txt",
 						completedAt: "2024-01-15T12:00:00Z",
 					},
@@ -435,14 +435,14 @@ recentTasks: []
 			const beforeUpdate = Date.now();
 			const updated = await updateIdentity(tempDir, "test-agent", {
 				completedTask: {
-					beadId: "beads-001",
+					taskId: "beads-001",
 					summary: "Fixed authentication bug",
 				},
 			});
 			const afterUpdate = Date.now();
 
 			expect(updated.recentTasks).toHaveLength(1);
-			expect(updated.recentTasks[0]?.beadId).toBe("beads-001");
+			expect(updated.recentTasks[0]?.taskId).toBe("beads-001");
 			expect(updated.recentTasks[0]?.summary).toBe("Fixed authentication bug");
 
 			// Verify timestamp is within the update window
@@ -454,7 +454,7 @@ recentTasks: []
 		test("caps recentTasks at 20 entries, dropping oldest", async () => {
 			// Create identity with 19 tasks
 			const existingTasks = Array.from({ length: 19 }, (_, i) => ({
-				beadId: `beads-${i.toString().padStart(3, "0")}`,
+				taskId: `beads-${i.toString().padStart(3, "0")}`,
 				summary: `Task ${i}`,
 				completedAt: `2024-01-${(i + 1).toString().padStart(2, "0")}T12:00:00Z`,
 			}));
@@ -472,20 +472,20 @@ recentTasks: []
 
 			// Add two more tasks (total would be 21)
 			let updated = await updateIdentity(tempDir, "test-agent", {
-				completedTask: { beadId: "beads-019", summary: "Task 19" },
+				completedTask: { taskId: "beads-019", summary: "Task 19" },
 			});
 
 			expect(updated.recentTasks).toHaveLength(20);
-			expect(updated.recentTasks[0]?.beadId).toBe("beads-000");
+			expect(updated.recentTasks[0]?.taskId).toBe("beads-000");
 
 			updated = await updateIdentity(tempDir, "test-agent", {
-				completedTask: { beadId: "beads-020", summary: "Task 20" },
+				completedTask: { taskId: "beads-020", summary: "Task 20" },
 			});
 
 			expect(updated.recentTasks).toHaveLength(20);
 			// Oldest task (beads-000) should be dropped
-			expect(updated.recentTasks[0]?.beadId).toBe("beads-001");
-			expect(updated.recentTasks[19]?.beadId).toBe("beads-020");
+			expect(updated.recentTasks[0]?.taskId).toBe("beads-001");
+			expect(updated.recentTasks[19]?.taskId).toBe("beads-020");
 		});
 
 		test("applies multiple updates simultaneously", async () => {
@@ -503,7 +503,7 @@ recentTasks: []
 				sessionsCompleted: 2,
 				expertiseDomains: ["testing", "architecture"],
 				completedTask: {
-					beadId: "beads-001",
+					taskId: "beads-001",
 					summary: "Completed task",
 				},
 			});
@@ -554,12 +554,12 @@ recentTasks: []
 				expertiseDomains: ["typescript", "testing", "architecture"],
 				recentTasks: [
 					{
-						beadId: "beads-001",
+						taskId: "beads-001",
 						summary: "Implemented feature X",
 						completedAt: "2024-01-15T12:00:00Z",
 					},
 					{
-						beadId: "beads-002",
+						taskId: "beads-002",
 						summary: "Fixed bug in module Y",
 						completedAt: "2024-01-16T14:30:00Z",
 					},
@@ -587,7 +587,7 @@ recentTasks: []
 				],
 				recentTasks: [
 					{
-						beadId: "beads-001",
+						taskId: "beads-001",
 						summary: 'Summary with "quotes" and: colons',
 						completedAt: "2024-01-15T12:00:00Z",
 					},

package/src/agents/identity.ts

@@ -39,7 +39,7 @@ function serializeIdentityYaml(identity: AgentIdentity): string {
 	} else {
 		lines.push("recentTasks:");
 		for (const task of identity.recentTasks) {
-			lines.push(`\t- beadId: ${quoteIfNeeded(task.beadId)}`);
+			lines.push(`\t- taskId: ${quoteIfNeeded(task.taskId)}`);
 			lines.push(`\t\tsummary: ${quoteIfNeeded(task.summary)}`);
 			lines.push(`\t\tcompletedAt: ${quoteIfNeeded(task.completedAt)}`);
 		}
@@ -82,7 +82,7 @@ function quoteIfNeeded(value: string): string {
  * This is a purpose-built parser for the identity YAML format. It handles:
  * - Simple key: value pairs (strings, numbers)
  * - Arrays of scalars (expertiseDomains)
- * - Arrays of objects (recentTasks with beadId, summary, completedAt)
+ * - Arrays of objects (recentTasks with taskId, summary, completedAt)
  * - Empty arrays (`[]`)
  * - Quoted strings
  * - Tab indentation
@@ -95,10 +95,10 @@ function parseIdentityYaml(text: string): AgentIdentity {
 	let created = "";
 	let sessionsCompleted = 0;
 	const expertiseDomains: string[] = [];
-	const recentTasks: Array<{ beadId: string; summary: string; completedAt: string }> = [];
+	const recentTasks: Array<{ taskId: string; summary: string; completedAt: string }> = [];
 
 	let currentSection: "none" | "expertiseDomains" | "recentTasks" = "none";
-	let currentTask: { beadId: string; summary: string; completedAt: string } | null = null;
+	let currentTask: { taskId: string; summary: string; completedAt: string } | null = null;
 
 	for (const rawLine of lines) {
 		const trimmed = rawLine.trim();
@@ -169,7 +169,7 @@ function parseIdentityYaml(text: string): AgentIdentity {
 				if (currentTask !== null) {
 					recentTasks.push(currentTask);
 				}
-				currentTask = { beadId: "", summary: "", completedAt: "" };
+				currentTask = { taskId: "", summary: "", completedAt: "" };
 
 				// Parse the key-value on the same line as the dash
 				const itemContent = trimmed.slice(2).trim();
@@ -210,13 +210,13 @@ function parseIdentityYaml(text: string): AgentIdentity {
  * Assign a parsed field value to a task object by key name.
  */
 function assignTaskField(
-	task: { beadId: string; summary: string; completedAt: string },
+	task: { taskId: string; summary: string; completedAt: string },
 	key: string,
 	value: string,
 ): void {
 	switch (key) {
-		case "beadId":
-			task.beadId = value;
+		case "taskId":
+			task.taskId = value;
 			break;
 		case "summary":
 			task.summary = value;
@@ -336,7 +336,7 @@ export async function updateIdentity(
 	baseDir: string,
 	name: string,
 	update: Partial<Pick<AgentIdentity, "sessionsCompleted" | "expertiseDomains">> & {
-		completedTask?: { beadId: string; summary: string };
+		completedTask?: { taskId: string; summary: string };
 	},
 ): Promise<AgentIdentity> {
 	const identity = await loadIdentity(baseDir, name);
@@ -364,7 +364,7 @@ export async function updateIdentity(
 	// Append completed task
 	if (update.completedTask !== undefined) {
 		identity.recentTasks.push({
-			beadId: update.completedTask.beadId,
+			taskId: update.completedTask.taskId,
 			summary: update.completedTask.summary,
 			completedAt: new Date().toISOString(),
 		});

package/src/agents/lifecycle.test.ts

@@ -23,7 +23,7 @@ describe("lifecycle", () => {
 			agentsDir,
 			agentName: "builder-1",
 			sessionId: "session-100",
-			beadId: "overstory-xyz1",
+			taskId: "overstory-xyz1",
 			reason: "compaction",
 			progressSummary: "Built the widget",
 			pendingWork: "Tests remain",
@@ -56,7 +56,7 @@ describe("lifecycle", () => {
 			agentsDir,
 			agentName: "builder-2",
 			sessionId: "session-200",
-			beadId: "overstory-abc2",
+			taskId: "overstory-abc2",
 			reason: "crash",
 			progressSummary: "Halfway done",
 			pendingWork: "Finish implementation",
@@ -82,7 +82,7 @@ describe("lifecycle", () => {
 			agentsDir,
 			agentName: "builder-3",
 			sessionId: "session-300",
-			beadId: "overstory-def3",
+			taskId: "overstory-def3",
 			reason: "manual",
 			progressSummary: "Done with phase 1",
 			pendingWork: "Phase 2",
@@ -116,7 +116,7 @@ describe("lifecycle", () => {
 			agentsDir,
 			agentName: "builder-4",
 			sessionId: "session-400",
-			beadId: "overstory-ghi4",
+			taskId: "overstory-ghi4",
 			reason: "compaction",
 			progressSummary: "First session work",
 			pendingWork: "Continue",
@@ -137,7 +137,7 @@ describe("lifecycle", () => {
 			agentsDir,
 			agentName: "builder-4",
 			sessionId: "session-401",
-			beadId: "overstory-ghi4",
+			taskId: "overstory-ghi4",
 			reason: "timeout",
 			progressSummary: "Second session work",
 			pendingWork: "Finish up",
@@ -172,7 +172,7 @@ describe("lifecycle", () => {
 			agentsDir,
 			agentName: "builder-5",
 			sessionId: "session-500",
-			beadId: "overstory-jkl5",
+			taskId: "overstory-jkl5",
 			reason: "compaction",
 			progressSummary: "Done",
 			pendingWork: "Nothing",

package/src/agents/lifecycle.ts

@@ -73,7 +73,7 @@ export async function initiateHandoff(options: {
 	agentsDir: string;
 	agentName: string;
 	sessionId: string;
-	beadId: string;
+	taskId: string;
 	reason: SessionHandoff["reason"];
 	progressSummary: string;
 	pendingWork: string;
@@ -83,7 +83,7 @@ export async function initiateHandoff(options: {
 }): Promise<SessionHandoff> {
 	const checkpoint: SessionCheckpoint = {
 		agentName: options.agentName,
-		beadId: options.beadId,
+		taskId: options.taskId,
 		sessionId: options.sessionId,
 		timestamp: new Date().toISOString(),
 		progressSummary: options.progressSummary,

package/src/agents/overlay.test.ts

@@ -25,7 +25,7 @@ Read your assignment. Execute immediately.
 function makeConfig(overrides?: Partial<OverlayConfig>): OverlayConfig {
 	return {
 		agentName: "test-builder",
-		beadId: "overstory-abc",
+		taskId: "overstory-abc",
 		specPath: ".overstory/specs/overstory-abc.md",
 		branchName: "agent/test-builder/overstory-abc",
 		worktreePath: "/tmp/test-project/.overstory/worktrees/test-builder",
@@ -48,8 +48,8 @@ describe("generateOverlay", () => {
 		expect(output).toContain("my-scout");
 	});
 
-	test("output contains bead ID", async () => {
-		const config = makeConfig({ beadId: "overstory-xyz" });
+	test("output contains task ID", async () => {
+		const config = makeConfig({ taskId: "overstory-xyz" });
 		const output = await generateOverlay(config);
 
 		expect(output).toContain("overstory-xyz");
@@ -134,7 +134,7 @@ describe("generateOverlay", () => {
 		const config = makeConfig({ mulchDomains: ["typescript", "testing"] });
 		const output = await generateOverlay(config);
 
-		expect(output).toContain("mulch prime typescript testing");
+		expect(output).toContain("ml prime typescript testing");
 	});
 
 	test("empty mulch domains shows fallback text", async () => {
@@ -159,7 +159,7 @@ describe("generateOverlay", () => {
 		});
 		const output = await generateOverlay(config);
 
-		expect(output).toContain("overstory sling");
+		expect(output).toContain("ov sling");
 		expect(output).toContain("--parent lead-alpha");
 		expect(output).toContain("--depth 2");
 	});
@@ -261,13 +261,13 @@ describe("generateOverlay", () => {
 		const config = makeConfig({
 			capability: "scout",
 			agentName: "recon-1",
-			beadId: "overstory-task1",
+			taskId: "overstory-task1",
 			parentAgent: "lead-alpha",
 		});
 		const output = await generateOverlay(config);
 
 		expect(output).toContain("bd close overstory-task1");
-		expect(output).toContain("overstory mail send --to lead-alpha");
+		expect(output).toContain("ov mail send --to lead-alpha");
 	});
 
 	test("reviewer completion section uses coordinator when no parent", async () => {
@@ -284,8 +284,8 @@ describe("generateOverlay", () => {
 		const config = makeConfig({ agentName: "worker-42" });
 		const output = await generateOverlay(config);
 
-		expect(output).toContain("overstory mail check --agent worker-42");
-		expect(output).toContain("overstory mail send --to");
+		expect(output).toContain("ov mail check --agent worker-42");
+		expect(output).toContain("ov mail send --to");
 	});
 
 	test("output includes base agent definition content (Layer 1)", async () => {
@@ -419,7 +419,7 @@ describe("generateOverlay", () => {
 	});
 
 	test("default trackerCli renders as bd in quality gates", async () => {
-		const config = makeConfig({ capability: "builder", beadId: "overstory-task1" });
+		const config = makeConfig({ capability: "builder", taskId: "overstory-task1" });
 		const output = await generateOverlay(config);
 
 		expect(output).toContain("bd close overstory-task1");
@@ -429,7 +429,7 @@ describe("generateOverlay", () => {
 		const config = makeConfig({
 			capability: "builder",
 			trackerCli: "sd",
-			beadId: "overstory-test1",
+			taskId: "overstory-test1",
 		});
 		const output = await generateOverlay(config);
 
@@ -451,7 +451,7 @@ describe("generateOverlay", () => {
 		const config = makeConfig({
 			capability: "scout",
 			trackerCli: "sd",
-			beadId: "overstory-test2",
+			taskId: "overstory-test2",
 		});
 		const output = await generateOverlay(config);
 
@@ -482,7 +482,7 @@ describe("generateOverlay", () => {
 	});
 
 	test("defaults backward-compatible: no trackerCli/trackerName produces bd/beads", async () => {
-		const config = makeConfig({ capability: "builder", beadId: "overstory-back" });
+		const config = makeConfig({ capability: "builder", taskId: "overstory-back" });
 		const output = await generateOverlay(config);
 
 		expect(output).toContain("bd close overstory-back");
@@ -521,7 +521,7 @@ describe("writeOverlay", () => {
 		const outputPath = join(worktreePath, ".claude", "CLAUDE.md");
 		const content = await Bun.file(outputPath).text();
 		expect(content).toContain("file-writer-test");
-		expect(content).toContain(config.beadId);
+		expect(content).toContain(config.taskId);
 		expect(content).toContain(config.branchName);
 	});
 

package/src/agents/overlay.ts

@@ -24,14 +24,14 @@ function formatFileScope(fileScope: readonly string[]): string {
 }
 
 /**
- * Format mulch domains as a `mulch prime` command.
+ * Format mulch domains as a `ml prime` command.
  * Returns a human-readable fallback if no domains are configured.
  */
 function formatMulchDomains(domains: readonly string[]): string {
 	if (domains.length === 0) {
 		return "No specific expertise domains configured";
 	}
-	return `\`\`\`bash\nmulch prime ${domains.join(" ")}\n\`\`\``;
+	return `\`\`\`bash\nml prime ${domains.join(" ")}\n\`\`\``;
 }
 
 /**
@@ -90,9 +90,9 @@ function formatQualityGates(config: OverlayConfig): string {
 			"",
 			"Before reporting completion:",
 			"",
-			`1. **Record mulch learnings:** \`mulch record <domain> --type <convention|pattern|reference> --description "..."\` — capture reusable knowledge from your work`,
-			`2. **Close issue:** \`${config.trackerCli ?? "bd"} close ${config.beadId} --reason "summary of findings"\``,
-			`3. **Send results:** \`overstory mail send --to ${config.parentAgent ?? "coordinator"} --subject "done" --body "Summary" --type result --agent ${config.agentName}\``,
+			`1. **Record mulch learnings:** \`ml record <domain> --type <convention|pattern|reference> --description "..."\` — capture reusable knowledge from your work`,
+			`2. **Close issue:** \`${config.trackerCli ?? "bd"} close ${config.taskId} --reason "summary of findings"\``,
+			`3. **Send results:** \`ov mail send --to ${config.parentAgent ?? "coordinator"} --subject "done" --body "Summary" --type result --agent ${config.agentName}\``,
 			"",
 			"You are a read-only agent. Do NOT commit, modify files, or run quality gates.",
 		].join("\n");
@@ -112,12 +112,12 @@ function formatQualityGates(config: OverlayConfig): string {
 		"",
 		...gateLines,
 		`${gateLines.length + 1}. **Commit:** all changes committed to your branch (${config.branchName})`,
-		`${gateLines.length + 2}. **Record mulch learnings:** \`mulch record <domain> --type <convention|pattern|failure|decision> --description "..." --outcome-status success --outcome-agent ${config.agentName}\` — capture insights from your work`,
-		`${gateLines.length + 3}. **Signal completion:** send \`worker_done\` mail to ${config.parentAgent ?? "coordinator"}: \`overstory mail send --to ${config.parentAgent ?? "coordinator"} --subject "Worker done: ${config.beadId}" --body "Quality gates passed." --type worker_done --agent ${config.agentName}\``,
-		`${gateLines.length + 4}. **Close issue:** \`${config.trackerCli ?? "bd"} close ${config.beadId} --reason "summary of changes"\``,
+		`${gateLines.length + 2}. **Record mulch learnings:** \`ml record <domain> --type <convention|pattern|failure|decision> --description "..." --outcome-status success --outcome-agent ${config.agentName}\` — capture insights from your work`,
+		`${gateLines.length + 3}. **Signal completion:** send \`worker_done\` mail to ${config.parentAgent ?? "coordinator"}: \`ov mail send --to ${config.parentAgent ?? "coordinator"} --subject "Worker done: ${config.taskId}" --body "Quality gates passed." --type worker_done --agent ${config.agentName}\``,
+		`${gateLines.length + 4}. **Close issue:** \`${config.trackerCli ?? "bd"} close ${config.taskId} --reason "summary of changes"\``,
 		"",
 		"Do NOT push to the canonical branch. Your work will be merged by the",
-		"coordinator via `overstory merge`.",
+		"coordinator via `ov merge`.",
 	].join("\n");
 }
 
@@ -132,7 +132,7 @@ function formatConstraints(config: OverlayConfig): string {
 			"",
 			"- You are **read-only**: do NOT modify, create, or delete any files",
 			"- Do NOT commit, push, or make any git state changes",
-			`- Report completion via \`${config.trackerCli ?? "bd"} close\` AND \`overstory mail send --type result\``,
+			`- Report completion via \`${config.trackerCli ?? "bd"} close\` AND \`ov mail send --type result\``,
 			"- If you encounter a blocking issue, send mail with `--priority urgent --type error`",
 		].join("\n");
 	}
@@ -145,7 +145,7 @@ function formatConstraints(config: OverlayConfig): string {
 		"- Only modify files in your File Scope",
 		`- Commit only to your branch: ${config.branchName}`,
 		"- Never push to the canonical branch",
-		`- Report completion via \`${config.trackerCli ?? "bd"} close\` AND \`overstory mail send --type result\``,
+		`- Report completion via \`${config.trackerCli ?? "bd"} close\` AND \`ov mail send --type result\``,
 		"- If you encounter a blocking issue, send mail with `--priority urgent --type error`",
 	].join("\n");
 }
@@ -159,10 +159,10 @@ function formatCanSpawn(config: OverlayConfig): string {
 		return "You may NOT spawn sub-workers.";
 	}
 	return [
-		"You may spawn sub-workers using `overstory sling`. Example:",
+		"You may spawn sub-workers using `ov sling`. Example:",
 		"",
 		"```bash",
-		"overstory sling <task-id> --capability builder --name <worker-name> \\",
+		"ov sling <task-id> --capability builder --name <worker-name> \\",
 		`  --parent ${config.agentName} --depth ${config.depth + 1}`,
 		"```",
 	].join("\n");
@@ -205,7 +205,7 @@ export async function generateOverlay(config: OverlayConfig): Promise<string> {
 
 	const replacements: Record<string, string> = {
 		"{{AGENT_NAME}}": config.agentName,
-		"{{BEAD_ID}}": config.beadId,
+		"{{BEAD_ID}}": config.taskId,
 		"{{SPEC_PATH}}": config.specPath ?? "No spec file provided",
 		"{{BRANCH_NAME}}": config.branchName,
 		"{{WORKTREE_PATH}}": config.worktreePath,

package/src/commands/agents.test.ts

@@ -97,7 +97,7 @@ describe("discoverAgents", () => {
 			capability: "builder",
 			worktreePath: join(tempDir, ".overstory", "worktrees", "builder-test"),
 			branchName: "overstory/builder-test/task-123",
-			beadId: "task-123",
+			taskId: "task-123",
 			tmuxSession: "overstory-test-builder",
 			state: "working",
 			pid: 12345,
@@ -129,7 +129,7 @@ describe("discoverAgents", () => {
 			capability: "builder",
 			worktreePath: join(tempDir, ".overstory", "worktrees", "builder-test"),
 			branchName: "overstory/builder-test/task-123",
-			beadId: "task-123",
+			taskId: "task-123",
 			tmuxSession: "overstory-test-builder",
 			state: "working",
 			pid: 12345,
@@ -148,7 +148,7 @@ describe("discoverAgents", () => {
 			capability: "scout",
 			worktreePath: join(tempDir, ".overstory", "worktrees", "scout-test"),
 			branchName: "overstory/scout-test/task-456",
-			beadId: "task-456",
+			taskId: "task-456",
 			tmuxSession: "overstory-test-scout",
 			state: "working",
 			pid: 12346,
@@ -180,7 +180,7 @@ describe("discoverAgents", () => {
 			capability: "builder",
 			worktreePath: join(tempDir, ".overstory", "worktrees", "builder-working"),
 			branchName: "overstory/builder-working/task-123",
-			beadId: "task-123",
+			taskId: "task-123",
 			tmuxSession: "overstory-test-working",
 			state: "working",
 			pid: 12345,
@@ -199,7 +199,7 @@ describe("discoverAgents", () => {
 			capability: "builder",
 			worktreePath: join(tempDir, ".overstory", "worktrees", "builder-completed"),
 			branchName: "overstory/builder-completed/task-456",
-			beadId: "task-456",
+			taskId: "task-456",
 			tmuxSession: "overstory-test-completed",
 			state: "completed",
 			pid: null,