@nseng-ai/branch-context 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nseng-ai/branch-context",
-	"version": "0.1.1",
+	"version": "0.1.2",
 	"type": "module",
 	"files": [
 		"src"
@@ -29,12 +29,12 @@
 	},
 	"dependencies": {
 		"@earendil-works/pi-tui": "0.79.1",
-		"@nseng-ai/brmem": "0.1.1",
-		"@nseng-ai/capability-kit": "0.1.1",
-		"@nseng-ai/clinkr": "0.1.1",
-		"@nseng-ai/foundation": "0.1.1",
-		"@nseng-ai/ns": "0.1.1",
-		"@nseng-ai/plans": "0.1.1",
+		"@nseng-ai/brmem": "0.1.2",
+		"@nseng-ai/capability-kit": "0.1.2",
+		"@nseng-ai/clinkr": "0.1.2",
+		"@nseng-ai/foundation": "0.1.2",
+		"@nseng-ai/kernel": "0.1.2",
+		"@nseng-ai/plans": "0.1.2",
 		"zod": "^4.4.3"
 	},
 	"peerDependencies": {

package/src/api/index.ts

@@ -4,11 +4,15 @@ export {
 	buildBranchContextPlanKey,
 	createBranchContextFromFile,
 	deriveTargetBranch,
+	selectBranchContextCreateOperationTarget,
 	formatBranchContextEvidence,
 	formatBranchContextCreateFailure,
 	formatBranchContextCreatePreview,
+	formatBranchSelectionLines,
 	describeBranchContextGraphiteCreationSteps,
 	resolveBranchContextCreatePreviewContext,
+	type BranchContextBranchSelection,
+	type BranchContextBranchSelectionCollision,
 	type BranchContextCreateOperation,
 	type BranchContextEvidence,
 	type BranchCreationMethod,

package/src/core/branch-context-creation.ts

@@ -1,5 +1,6 @@
 import type { BranchContextAttachData } from "./branch-memory.ts";
-import { assertBrmemEntryAbsent, attachBranchContext, AttachBranchContextError } from "./attach.ts";
+import { attachBranchContext, AttachBranchContextError } from "./attach.ts";
+import { checkBranchContextEntryPresence, throwBranchContextBrmemError } from "./branch-memory.ts";
 import { BRANCH_CONTEXT_NAMESPACE, buildBranchContextPlanKey } from "./constants.ts";
 import type { BrmemGateway } from "@nseng-ai/brmem";
 import type { GraphiteBranchGateway } from "@nseng-ai/capability-kit/graphite/branch";
@@ -35,6 +36,22 @@ export interface CreateBranchContextFromFileOptions {
 	signal?: AbortSignal;
 }
 
+export interface BranchContextBranchSelectionCollision {
+	branch: string;
+	isLocalBranch: boolean;
+	hasAttachedPlan: boolean;
+}
+
+interface BranchContextBranchSelectionBase {
+	requestedBranch: string;
+	selectedBranch: string;
+	collisions: BranchContextBranchSelectionCollision[];
+}
+
+export type BranchContextBranchSelection =
+	| (BranchContextBranchSelectionBase & { type: "exact" })
+	| (BranchContextBranchSelectionBase & { type: "auto-suffixed" });
+
 export interface BranchContextEvidence {
 	slug: string;
 	branch: string;
@@ -45,6 +62,7 @@ export interface BranchContextEvidence {
 	refName: string;
 	commit: string;
 	sourceFile: string;
+	branchSelection?: BranchContextBranchSelection;
 	summary?: string;
 }
 
@@ -56,6 +74,7 @@ export interface BranchContextCreateOperation {
 	namespace: string;
 	key: string;
 	params: CreateBranchContextFromFileParams;
+	branchSelection: BranchContextBranchSelection;
 	summary?: string;
 }
 
@@ -64,16 +83,19 @@ export interface BranchContextCreatePreviewContext {
 	graphiteParentBranch?: string;
 }
 
-export interface CreateBranchContextFromResolvedSourceOptions {
+interface BranchContextRepoAccess {
 	cwd: string;
-	operation: BranchContextCreateOperation;
-	sourceFile: string;
 	git: GitGateway;
 	brmem: BrmemGateway;
-	graphite: GraphiteBranchGateway;
 	signal?: AbortSignal;
 }
 
+export interface CreateBranchContextFromResolvedSourceOptions extends BranchContextRepoAccess {
+	operation: BranchContextCreateOperation;
+	sourceFile: string;
+	graphite: GraphiteBranchGateway;
+}
+
 export async function createBranchContextFromFile(
 	pi: CommandExecApi,
 	params: CreateBranchContextFromFileParams,
@@ -82,15 +104,23 @@ export async function createBranchContextFromFile(
 	const operation = buildBranchContextCreateOperation(params);
 	const { git, brmem, graphite } = options.context;
 	await checkBranchRefFormat(git, options.cwd, operation.branch, options.signal);
+	const selectedOperation = await selectBranchContextCreateOperationTarget({
+		cwd: options.cwd,
+		operation,
+		git,
+		brmem,
+		isExplicitTargetBranch: params.branchName !== undefined,
+		...optionalEntry("signal", options.signal),
+	});
 	const sourceFile = await resolvePlanSourceFile(pi, {
 		cwd: options.cwd,
-		rawFilePath: operation.filePath,
+		rawFilePath: selectedOperation.filePath,
 		...optionalEntry("signal", options.signal),
 		git,
 	});
 	return createBranchContextFromResolvedSource({
 		cwd: options.cwd,
-		operation,
+		operation: selectedOperation,
 		sourceFile,
 		git,
 		brmem,
@@ -103,10 +133,7 @@ export async function createBranchContextFromResolvedSource(
 	options: CreateBranchContextFromResolvedSourceOptions,
 ): Promise<BranchContextEvidence> {
 	const startPoint = await resolveStartPoint(options.git, options.cwd, options.signal);
-	await assertLocalBranchAbsent(options.git, options.cwd, options.operation.branch, options.signal);
-	await assertBrmemEntryAbsent(options.brmem, options.operation.branch, options.operation.key, {
-		formatPresentMessage: formatStaleTargetBranchMemoryMessage,
-	});
+	await assertSelectedTargetBranchStillAvailable(options);
 	await createBranchContext(options.git, options.graphite, {
 		cwd: options.cwd,
 		method: options.operation.branchCreation,
@@ -141,6 +168,7 @@ export async function createBranchContextFromResolvedSource(
 		slug: options.operation.slug,
 		branchCreation: options.operation.branchCreation,
 		startPoint,
+		branchSelection: options.operation.branchSelection,
 		summary: options.operation.summary,
 	});
 }
@@ -172,6 +200,7 @@ export function buildBranchContextCreateOperation(
 		namespace: BRANCH_CONTEXT_NAMESPACE,
 		key: buildBranchContextPlanKey(slug),
 		params: operationParams,
+		branchSelection: exactBranchSelection(branch),
 	};
 	if (summary === undefined) {
 		return operation;
@@ -195,6 +224,7 @@ export function formatBranchContextCreatePreview(
 		"Target:",
 		`Branch: ${operation.branch}`,
 		`Branch creation: ${operation.branchCreation}`,
+		...formatBranchSelectionLines(operation.branchSelection),
 		`Start point: ${context.startPoint}`,
 		`Branch Memory namespace: ${operation.namespace}`,
 		`Branch Memory key: ${operation.key}`,
@@ -233,6 +263,7 @@ export function formatBranchContextEvidence(evidence: BranchContextEvidence): st
 		"Created branch context and attached plan.",
 		`Branch: ${evidence.branch}`,
 		`Branch creation: ${evidence.branchCreation}`,
+		...formatBranchSelectionLines(evidence.branchSelection),
 		`Start point: ${evidence.startPoint}`,
 		`Namespace: ${evidence.namespace}`,
 		`Key: ${evidence.key}`,
@@ -254,6 +285,7 @@ export function formatBranchContextCreateFailure(
 	return [
 		"Failed to create branch context and attach plan.",
 		`Branch: ${operation.branch}`,
+		...formatBranchSelectionLines(operation.branchSelection),
 		`Branch creation: ${operation.branchCreation}`,
 		`Namespace: ${operation.namespace}`,
 		`Key: ${operation.key}`,
@@ -268,6 +300,54 @@ export function deriveTargetBranch(branchName: string | undefined, slug: string)
 	return trimmedBranchName && trimmedBranchName.length > 0 ? trimmedBranchName : slug;
 }
 
+export async function selectBranchContextCreateOperationTarget(
+	options: BranchContextRepoAccess & {
+		operation: BranchContextCreateOperation;
+		isExplicitTargetBranch: boolean;
+	},
+): Promise<BranchContextCreateOperation> {
+	const maxAttempts = 100;
+	const requestedBranch = options.operation.branch;
+	if (options.isExplicitTargetBranch) {
+		return withBranchSelection(options.operation, exactBranchSelection(requestedBranch));
+	}
+
+	const collisions: BranchContextBranchSelectionCollision[] = [];
+	for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+		const candidate = attempt === 1 ? requestedBranch : `${requestedBranch}-${attempt}`;
+		const occupancy = await checkTargetBranchOccupancy({
+			cwd: options.cwd,
+			git: options.git,
+			brmem: options.brmem,
+			branch: candidate,
+			key: options.operation.key,
+			...optionalEntry("signal", options.signal),
+		});
+		if (!occupancy.collision.isLocalBranch && !occupancy.collision.hasAttachedPlan) {
+			const selection =
+				collisions.length === 0
+					? exactBranchSelection(candidate)
+					: {
+							type: "auto-suffixed" as const,
+							requestedBranch,
+							selectedBranch: candidate,
+							collisions,
+						};
+			return withBranchSelection(options.operation, selection);
+		}
+		collisions.push({ branch: candidate, ...occupancy.collision });
+	}
+
+	throw new Error(
+		[
+			"Could not find an available default target branch for branch context creation.",
+			`Base branch: ${requestedBranch}`,
+			`Attempts: ${maxAttempts}`,
+			`Last attempted branch: ${requestedBranch}-${maxAttempts}`,
+		].join("\n"),
+	);
+}
+
 async function checkBranchRefFormat(
 	git: GitGateway,
 	cwd: string,
@@ -292,27 +372,134 @@ async function resolveStartPoint(
 	return head.value;
 }
 
-async function assertLocalBranchAbsent(
-	git: GitGateway,
-	cwd: string,
-	targetBranch: string,
-	signal: AbortSignal | undefined,
+interface SelectedBranchAvailabilityOptions extends BranchContextRepoAccess {
+	operation: BranchContextCreateOperation;
+}
+
+async function assertSelectedTargetBranchStillAvailable(
+	options: SelectedBranchAvailabilityOptions,
 ): Promise<void> {
-	const check = await git.localBranchPresence({ cwd, branch: targetBranch, signal });
-	if (check.type === "absent") {
-		return;
-	}
-	if (check.type === "present") {
+	const occupancy = await checkTargetBranchOccupancy({
+		cwd: options.cwd,
+		git: options.git,
+		brmem: options.brmem,
+		branch: options.operation.branch,
+		key: options.operation.key,
+		stopAfterLocalBranch: true,
+		...optionalEntry("signal", options.signal),
+	});
+	if (occupancy.localBranch !== undefined) {
 		throw new Error(
 			[
 				"Target branch already exists; refusing to overwrite.",
-				`Branch: ${targetBranch}`,
-				`Ref: ${check.refName}`,
-				`Command: ${check.displayCommand}`,
+				`Branch: ${options.operation.branch}`,
+				`Ref: ${occupancy.localBranch.refName}`,
+				`Command: ${occupancy.localBranch.displayCommand}`,
 			].join("\n"),
 		);
 	}
-	throw new Error(check.error.message);
+	if (occupancy.collision.hasAttachedPlan) {
+		throw new Error(
+			formatStaleTargetBranchMemoryMessage({
+				targetBranch: options.operation.branch,
+				key: options.operation.key,
+			}),
+		);
+	}
+}
+
+interface CheckTargetBranchOccupancyOptions extends BranchContextRepoAccess {
+	branch: string;
+	key: string;
+	stopAfterLocalBranch?: boolean;
+}
+
+interface TargetBranchOccupancy {
+	collision: Omit<BranchContextBranchSelectionCollision, "branch">;
+	localBranch?: LocalBranchPresence;
+}
+
+interface LocalBranchPresence {
+	refName: string;
+	displayCommand: string;
+}
+
+async function checkTargetBranchOccupancy(
+	options: CheckTargetBranchOccupancyOptions,
+): Promise<TargetBranchOccupancy> {
+	const localBranch = await checkLocalBranchPresence(options);
+	if (localBranch !== undefined && options.stopAfterLocalBranch === true) {
+		return {
+			collision: { isLocalBranch: true, hasAttachedPlan: false },
+			localBranch,
+		};
+	}
+	const hasAttachedPlan = await checkAttachedPlanPresence(
+		options.brmem,
+		options.branch,
+		options.key,
+	);
+	return {
+		collision: {
+			isLocalBranch: localBranch !== undefined,
+			hasAttachedPlan,
+		},
+		...optionalEntry("localBranch", localBranch),
+	};
+}
+
+async function checkLocalBranchPresence(
+	options: Pick<CheckTargetBranchOccupancyOptions, "cwd" | "git" | "branch" | "signal">,
+): Promise<LocalBranchPresence | undefined> {
+	const localBranch = await options.git.localBranchPresence({
+		cwd: options.cwd,
+		branch: options.branch,
+		...optionalEntry("signal", options.signal),
+	});
+	if (localBranch.type === "error") {
+		throw new Error(localBranch.error.message);
+	}
+	if (localBranch.type === "absent") {
+		return undefined;
+	}
+	return { refName: localBranch.refName, displayCommand: localBranch.displayCommand };
+}
+
+async function checkAttachedPlanPresence(
+	brmem: BrmemGateway,
+	branch: string,
+	key: string,
+): Promise<boolean> {
+	const attachedPlan = await checkBranchContextEntryPresence(brmem, { branch, key });
+	if (attachedPlan.type === "error") {
+		throwBranchContextBrmemError(attachedPlan.error);
+	}
+	return attachedPlan.type === "present";
+}
+
+function exactBranchSelection(branch: string): BranchContextBranchSelection {
+	return { type: "exact", requestedBranch: branch, selectedBranch: branch, collisions: [] };
+}
+
+function withBranchSelection(
+	operation: BranchContextCreateOperation,
+	branchSelection: BranchContextBranchSelection,
+): BranchContextCreateOperation {
+	const branch = branchSelection.selectedBranch;
+	return { ...operation, branch, branchSelection };
+}
+
+export function formatBranchSelectionLines(
+	selection: BranchContextBranchSelection | undefined,
+): string[] {
+	if (selection === undefined || selection.type === "exact") {
+		return [];
+	}
+	return [
+		`Default branch: ${selection.requestedBranch}`,
+		`Selected target branch: ${selection.selectedBranch}`,
+		`Default branch ${selection.requestedBranch} already exists or has an attached plan; selected ${selection.selectedBranch}.`,
+	];
 }
 
 function formatStaleTargetBranchMemoryMessage(context: {
@@ -437,6 +624,7 @@ function buildEvidence(input: {
 	slug: string;
 	branchCreation: BranchCreationMethod;
 	startPoint: string;
+	branchSelection: BranchContextBranchSelection;
 	summary: string | undefined;
 }): BranchContextEvidence {
 	const evidence = {
@@ -449,6 +637,7 @@ function buildEvidence(input: {
 		refName: input.data.refName,
 		commit: input.data.commit,
 		sourceFile: input.data.sourceFile,
+		branchSelection: input.branchSelection,
 	};
 
 	if (input.summary === undefined) {

package/src/core/context.ts

@@ -17,6 +17,7 @@ export interface BranchContextContext {
 
 export interface BranchContextContextOptions {
 	cwd?: string;
+	brmemCommands?: StdinCapableCommandExecApi;
 }
 
 export type BranchContextContextFactory<Args extends unknown[]> = (
@@ -24,12 +25,14 @@ export type BranchContextContextFactory<Args extends unknown[]> = (
 ) => BranchContextContext;
 
 export function createBranchContextContext(
-	commands: StdinCapableCommandExecApi,
+	commands: CommandExecApi,
 	options: BranchContextContextOptions = {},
 ): BranchContextContext {
 	const cwd = options.cwd ?? process.cwd();
 	const git = new RealGitGateway(commands);
-	const brmem = new RealGitBrmemGateway({ cwd, commands, git });
+	const brmemCommands = options.brmemCommands ?? new NodeCommandExecApi();
+	const brmemGit = brmemCommands === commands ? git : new RealGitGateway(brmemCommands);
+	const brmem = new RealGitBrmemGateway({ cwd, commands: brmemCommands, git: brmemGit });
 	return {
 		commands,
 		git,

package/src/core/operations.ts

@@ -97,13 +97,25 @@ export type AttachRequest = z.infer<typeof attachRequestSchema>;
 export type ListRequest = z.infer<typeof listRequestSchema>;
 export type KeyRequest = z.infer<typeof keyRequestSchema>;
 
-export type BranchContextData = ReturnType<typeof branchContextJson>;
+export type BranchContextData = z.infer<typeof branchContextResultSchema>;
 export type LoadPlanData = ReturnType<typeof loadedPlanJson>;
 export type AttachData = ReturnType<typeof attachJson>;
 export type ListData = ReturnType<typeof listJson>;
 export type CheckData = ReturnType<typeof checkJson>;
 export type DeleteData = ReturnType<typeof deleteJson>;
 
+const branchSelectionCollisionSchema = z.object({
+	branch: z.string(),
+	isLocalBranch: z.boolean(),
+	hasAttachedPlan: z.boolean(),
+});
+
+const branchSelectionBaseSchema = z.object({
+	requestedBranch: z.string(),
+	selectedBranch: z.string(),
+	collisions: z.array(branchSelectionCollisionSchema),
+});
+
 export const branchContextResultSchema = z.object({
 	slug: z.string(),
 	branch: z.string(),
@@ -114,6 +126,10 @@ export const branchContextResultSchema = z.object({
 	refName: z.string(),
 	commit: z.string(),
 	sourceFile: z.string(),
+	branchSelection: z.union([
+		branchSelectionBaseSchema.extend({ type: z.literal("exact") }),
+		branchSelectionBaseSchema.extend({ type: z.literal("auto-suffixed") }),
+	]),
 	summary: z.string().optional(),
 });
 
@@ -464,8 +480,15 @@ function branchContextJson(evidence: BranchContextEvidence): {
 	refName: string;
 	commit: string;
 	sourceFile: string;
+	branchSelection: NonNullable<BranchContextEvidence["branchSelection"]>;
 	summary?: string;
 } {
+	const branchSelection = evidence.branchSelection ?? {
+		type: "exact" as const,
+		requestedBranch: evidence.branch,
+		selectedBranch: evidence.branch,
+		collisions: [],
+	};
 	return {
 		slug: evidence.slug,
 		branch: evidence.branch,
@@ -476,6 +499,7 @@ function branchContextJson(evidence: BranchContextEvidence): {
 		refName: evidence.refName,
 		commit: evidence.commit,
 		sourceFile: evidence.sourceFile,
+		branchSelection,
 		...(evidence.summary === undefined ? {} : { summary: evidence.summary }),
 	};
 }

package/src/core/plan-content-slug.ts

@@ -4,8 +4,8 @@ import type { CommandExecApi } from "@nseng-ai/foundation/exec";
 import {
 	buildContentSlugPrompt,
 	deriveContentSlug,
-	type ContentSlugDerivationVariant,
 	type ContentSlugEvidence,
+	type PlanContentSlugVariantSeed,
 } from "@nseng-ai/plans";
 
 export type PlanContentSlugEvidence = ContentSlugEvidence;
@@ -17,7 +17,7 @@ export interface DerivePlanContentSlugInput {
 	readTextFile?: (path: string) => Promise<string>;
 }
 
-const PLAN_CONTENT_SLUG_VARIANT: ContentSlugDerivationVariant = {
+const PLAN_CONTENT_SLUG_VARIANT: PlanContentSlugVariantSeed = {
 	slugKind: "branch-context slug",
 	promptIntroLines: [
 		"Generate the branch-context slug for the Markdown implementation plan content below.",

package/src/ns/command.ts

@@ -3,7 +3,7 @@ import {
 	type NsDomainCommandOptions,
 } from "@nseng-ai/capability-kit/ns-command";
 import { optionalEntry } from "@nseng-ai/foundation/primitives";
-import type { NsCommand, NsCommandSchema, NsExtensionApi } from "@nseng-ai/ns/kernel/sdk";
+import type { NsCommand, NsCommandSchema, NsExtensionApi } from "@nseng-ai/kernel/sdk";
 
 import {
 	createRealBranchContextCliContext,

package/src/ns/commands/attach.ts

@@ -1,4 +1,4 @@
-import { defineExtension } from "@nseng-ai/ns/kernel/sdk";
+import { defineExtension } from "@nseng-ai/kernel/sdk";
 
 import { branchContextCommand } from "../command.ts";
 import { attachRequestSchema, attachResultSchema, handleAttach } from "../../core/operations.ts";

package/src/ns/commands/check.ts

@@ -1,4 +1,4 @@
-import { defineExtension } from "@nseng-ai/ns/kernel/sdk";
+import { defineExtension } from "@nseng-ai/kernel/sdk";
 
 import { branchContextCommand } from "../command.ts";
 import { checkResultSchema, handleCheck, keyRequestSchema } from "../../core/operations.ts";

package/src/ns/commands/delete.ts

@@ -1,4 +1,4 @@
-import { defineExtension } from "@nseng-ai/ns/kernel/sdk";
+import { defineExtension } from "@nseng-ai/kernel/sdk";
 
 import { branchContextCommand } from "../command.ts";
 import { deleteResultSchema, handleDelete, keyRequestSchema } from "../../core/operations.ts";

package/src/ns/commands/from-plan.ts

@@ -1,4 +1,4 @@
-import { defineExtension } from "@nseng-ai/ns/kernel/sdk";
+import { defineExtension } from "@nseng-ai/kernel/sdk";
 
 import { branchContextCommand } from "../command.ts";
 import {

package/src/ns/commands/list.ts

@@ -1,4 +1,4 @@
-import { defineExtension } from "@nseng-ai/ns/kernel/sdk";
+import { defineExtension } from "@nseng-ai/kernel/sdk";
 
 import { branchContextCommand } from "../command.ts";
 import { handleList, listRequestSchema, listResultSchema } from "../../core/operations.ts";

package/src/ns/commands/load.ts

@@ -1,4 +1,4 @@
-import { defineExtension } from "@nseng-ai/ns/kernel/sdk";
+import { defineExtension } from "@nseng-ai/kernel/sdk";
 
 import { branchContextCommand } from "../command.ts";
 import { handleLoad, loadPlanResultSchema, loadRequestSchema } from "../../core/operations.ts";

package/src/ns/repo-local-ns-extension.ts

@@ -1,7 +1,7 @@
 import {
 	defineRepoLocalNsExtensionDescriptor,
 	repoLocalNsCommandDescriptor,
-} from "@nseng-ai/ns/kernel/sdk";
+} from "@nseng-ai/kernel/sdk";
 
 import { branchContextAttachNsCommand } from "./commands/attach.ts";
 import { branchContextCheckNsCommand } from "./commands/check.ts";

package/src/pi/enriched-plan-save.ts

@@ -1,8 +1,6 @@
 import { registerCommandWithImmediateAck } from "@nseng-ai/pi/commands/ack";
-import type { Stats } from "node:fs";
+import { readFileSync, type Stats } from "node:fs";
 import { lstat, readFile } from "node:fs/promises";
-import { join } from "node:path";
-
 import { Text } from "@earendil-works/pi-tui";
 import { piExecApiToCommandExecApi } from "@nseng-ai/foundation/command";
 import { RealGitGateway } from "@nseng-ai/capability-kit/git";
@@ -13,6 +11,12 @@ import {
 	optionalEntry,
 } from "@nseng-ai/foundation/primitives";
 import type { ScheduledTimer } from "@nseng-ai/foundation/timers";
+import {
+	loadPointCatalog,
+	nodeProjectConfigGateway,
+	resolvePromptPointPath,
+	resolvePromptPointSource,
+} from "@nseng-ai/kernel/project-config/points";
 import { systemTimerScheduler } from "@nseng-ai/foundation/time";
 import { WRITE_GRILLED_PLAN_COMMAND_NAME, WRITE_PLAN_COMMAND_NAME } from "./surfaces.ts";
 import { sendCommandProgressOrNotify } from "@nseng-ai/pi/commands/ack";
@@ -56,71 +60,12 @@ interface WriteSavedPlanFileProgressDetails {
 	elapsedSeconds?: number;
 }
 
-const WRITE_PLAN_PROMPT_NAME = "plans-write";
-
-export const DEFAULT_WRITE_PLAN_PROMPT_BODY = `Plan audience and context contract:
-- Treat the saved Markdown plan as the only planning context available to a completely fresh downstream implementation session.
-- Make the plan self-contained. Do not rely on this conversation, hidden context, tool transcripts, or "as discussed" references.
-- Embed all relevant context discovered during planning, including user goals, constraints, current behavior, important files/symbols/tests/docs, decisions made, rationale, rejected alternatives, assumptions, risks, and proportional validation guidance.
-- Prefer concrete file paths, symbol names, command names, expected outcomes, and implementation order over vague instructions.
-- If you inspected evidence during planning, summarize the discovered facts in the plan so the downstream agent does not need to rediscover them unless verification is required.
+const WRITE_PLAN_POINT_ID = "branch-context.plans-write";
 
-External research/context contract:
-- If planning used anything outside the repository — web searches, external docs, GitHub issues/PRs, API docs, CLIs hitting remote services, local files outside the repo, or other non-repo resources — include the relevant findings inline in the saved plan.
-- Do not merely link to external resources. Summarize the concrete facts, constraints, examples, decisions, and caveats the downstream agent needs.
-- Include source/provenance where useful: URL, command, document name, issue/PR number, accessed date/time if known, and why it mattered.
-- If external findings may become stale, mark what should be revalidated during implementation.
-- Do not include secrets, credentials, private tokens, or unnecessary sensitive data.
-
-<!-- PLAN-VERIFICATION-WORKSTREAM:START refactor-execution-strategy-guidance -->
-Refactor execution strategy:
-- If the implementation includes same-shape edits across multiple files, explicitly choose an execution mode in the plan.
-- Apply the canonical guidance in \`skills/enriched-plan-save/references/refactor-execution-strategy.md\`, including the final stale-terminology grep/equivalent check when changing names or concepts.
-<!-- PLAN-VERIFICATION-WORKSTREAM:END refactor-execution-strategy-guidance -->
-
-Recommended saved plan sections:
-- Goal and user-visible outcome.
-- Planning context and discovered facts, including relevant repository state.
-- External/off-repo research context, or a note that none was used when that helps remove ambiguity.
-- Files, symbols, commands, and tests likely to change.
-- Step-by-step implementation approach.
-- Validation guidance and expected results. Do not over-specify routine test/check scope as a planning decision; leave ordinary validation coverage to the implementing agent's project policy and changed-file judgment.
-- Risks, assumptions, edge cases, and open questions.
-
-Workflow:
-1. Inspect the repository, documentation, and current conversation context as needed for the requested work.
-2. Produce a detailed Markdown implementation plan.
-3. Review the final Markdown plan content for completeness.
-4. Call write_saved_plan_file with the full Markdown content and optional one-sentence summary; do not generate or pass a slug.
-5. Report the saved plan evidence: file path, repo key, repo root, repo identity source, source branch, branch path segment, slug, slug model, and summary when present.
-6. Stop after reporting the saved plan evidence. Do not create a branch, write Branch Memory, or call any branch-context command/tool.
-
-Local plan store contract:
-- Canonical path convention: $XDG_STATE_HOME/ns/enriched-plan/<repo>/<encoded-source-branch>/<slug>.md, defaulting to $HOME/.local/state/ns/enriched-plan/<repo>/<encoded-source-branch>/<slug>.md. No fallback path is read or written; only $HOME/.local/state/ns/enriched-plan/<repo>/<encoded-source-branch>/<slug>.md is used.
-- <repo>: for github.com origins, gh--<owner>--<repo> from sanitized GitHub owner and repo path segments; for non-GitHub or origin-less repos, one sanitized path segment from the normalized remote.origin.url or real repo root path
-- <encoded-source-branch>: current branch at plan-file creation time encoded as one filesystem-safe path segment; branch slashes become --- (for example, branch-contexts/add-widget becomes branch-contexts---add-widget)
-- <slug>: semantic kebab-case saved-plan filename slug without .md; this is a local plan-store locator, not necessarily the later implementation branch slug
-- Existing saved plan file: write_saved_plan_file refuses to overwrite it; do not manually choose a replacement slug.
-- Working-tree behavior: no checked-in plan file is created.
-
-Saved-plan filename slug rules:
-- write_saved_plan_file derives the final saved-plan filename slug from the final plan content through the Codex-backed slug model.
-- Do not generate, guess, or pass a slug yourself.
-- The derived slug is kebab-case, 3–7 words, specific to the work described by the final plan, and rejects dates, random IDs, and generic-only slugs.
-
-When the plan is ready, call write_saved_plan_file with:
-- content: the complete reviewed Markdown plan content
-- summary: optional one-sentence summary of the plan
-
-Exact tool call shape:
-\`\`\`json
-{
-  "content": "# Plan\\n...",
-  "summary": "One-sentence summary of the plan."
-}
-\`\`\`
-
-If summary is not useful, omit it from the tool call rather than passing an empty string. Do not create target branches or write Branch Memory in this workflow.`;
+export const DEFAULT_WRITE_PLAN_PROMPT_BODY = readFileSync(
+	new URL("./prompts/plans-write-default.md", import.meta.url),
+	"utf8",
+).trimEnd();
 
 type WritePlanPromptBodyResolution =
 	| { type: "resolved"; body: string }
@@ -181,10 +126,10 @@ async function resolveWritePlanPromptBody(
 	}
 
 	try {
-		return await readRepoWritePlanPromptBody(repoRoot.path);
+		return await readWritePlanPromptBody(repoRoot.path);
 	} catch (error) {
 		return fallbackWritePlanPromptBody(
-			`repo prompt ${repoPromptPath(repoRoot.path)} could not be read: ${formatErrorMessage(error)}`,
+			`prompt point ${WRITE_PLAN_POINT_ID} could not be read: ${formatErrorMessage(error)}`,
 		);
 	}
 }
@@ -208,28 +153,25 @@ async function resolveGitRoot(
 	return { type: "resolved", path: result.value };
 }
 
-async function readRepoWritePlanPromptBody(
-	repoRoot: string,
-): Promise<WritePlanPromptBodyResolution> {
-	const nsPath = join(repoRoot, ".ns");
-	const promptDir = join(nsPath, "prompts");
-	const promptPath = repoPromptPath(repoRoot);
-	await assertSafeDirectory(nsPath, ".ns");
-	await assertSafeDirectory(promptDir, ".ns/prompts");
-	await assertSafeFile(promptPath, `.ns/prompts/${WRITE_PLAN_PROMPT_NAME}.md`);
-
-	const content = await readFile(promptPath, "utf8");
-	if (content.trim().length === 0) {
-		return fallbackWritePlanPromptBody(`repo prompt ${promptPath} is empty`);
+async function readWritePlanPromptBody(repoRoot: string): Promise<WritePlanPromptBodyResolution> {
+	const catalog = loadPointCatalog({ repoRoot, gateway: nodeProjectConfigGateway });
+	const source = resolvePromptPointSource(catalog, WRITE_PLAN_POINT_ID);
+	if (source.type === "env") {
+		return fallbackWritePlanPromptBody(
+			`prompt point ${WRITE_PLAN_POINT_ID} has unsupported env source`,
+		);
 	}
-	return { type: "resolved", body: content };
-}
+	const promptPath = resolvePromptPointPath(repoRoot, source);
+	if (promptPath === undefined) {
+		return fallbackWritePlanPromptBody(`prompt point ${WRITE_PLAN_POINT_ID} has no default`);
+	}
+	await assertSafeFile(promptPath.path, promptPath.label);
 
-async function assertSafeDirectory(targetPath: string, label: string): Promise<void> {
-	const stats = await assertNotSymlink(targetPath, label);
-	if (!stats.isDirectory()) {
-		throw new Error(`${label} is not a directory`);
+	const content = await readFile(promptPath.path, "utf8");
+	if (content.trim().length === 0) {
+		return fallbackWritePlanPromptBody(`${promptPath.label} is empty`);
 	}
+	return { type: "resolved", body: content };
 }
 
 async function assertSafeFile(targetPath: string, label: string): Promise<void> {
@@ -247,10 +189,6 @@ async function assertNotSymlink(targetPath: string, label: string): Promise<Stat
 	return stats;
 }
 
-function repoPromptPath(repoRoot: string): string {
-	return join(repoRoot, ".ns", "prompts", `${WRITE_PLAN_PROMPT_NAME}.md`);
-}
-
 export async function handleWritePlanCommand(
 	pi: ExtensionAPI,
 	args: string,

package/src/pi/from-plan-commands.ts

@@ -9,6 +9,7 @@ import {
 	formatBranchContextGtUpstackImplFollowUpFlow,
 	runBranchContextGtUpstackImplLaunch,
 } from "./gt/upstack-impl-launch.ts";
+import { createGtUpstackImplGitGateway } from "./gt/git-gateway.ts";
 import {
 	BRANCH_CONTEXT_FROM_PLAN_COMMAND_NAME,
 	BRANCH_CONTEXT_UPSTACK_IMPL_FROM_PLAN_COMMAND_NAME,
@@ -21,14 +22,19 @@ import {
 	buildBranchContextOutputMessage,
 	buildBranchContextPlanKey,
 	buildImplBranchContextPrompt,
+	createBranchContextContext,
 	createRealBranchContextContext,
 	derivePlanContentSlug,
 	deriveTargetBranch,
 	formatBranchContextEvidence,
 	describeBranchContextGraphiteCreationSteps,
+	formatBranchSelectionLines,
+	selectBranchContextCreateOperationTarget,
+	buildBranchContextCreateOperation,
 	formatExistingBranchContextReuse,
 	formatLoadedAttachedPlanEvidence,
 	resolveExistingBranchContextReuse,
+	type BranchContextBranchSelection,
 	type BranchContextEvidence,
 	type BranchContextOutputDetails,
 	type BranchCreationMethod,
@@ -71,14 +77,14 @@ const GRAPHITE_BRANCH_CREATION_HELP =
 
 export const CREATE_BRANCH_CONTEXT_USAGE = `Usage: /${CREATE_BRANCH_CONTEXT_COMMAND_NAME} [options] [absolute-or-home-plan-file.md]
 
-Create a branch context from a saved plan. The branch slug is derived from the plan content by a tiny Pi model, then the plan is attached to the branch in Branch Memory as <content-derived-slug>.md.
+Create a branch context from a saved plan. The branch slug is derived from the plan content by a tiny Pi model, default target branches auto-suffix on collisions, then the plan is attached to the branch in Branch Memory as <content-derived-slug>.md.
 
 Options:
   --dry-run          Show the selected plan and target branch without mutating.
   --yes, -y          Compatibility no-op; resolved branch contexts create without confirmation.
   --graphite         Create with the branch-context Graphite method.
   --plain-git        Create with plain Git only; no Graphite tracking.
-  --branch <name>    Use an explicit target branch name.
+  --branch <name>    Use an explicit target branch name; explicit branches do not auto-suffix.
   --help, -h         Show this help.
 
 ${GRAPHITE_BRANCH_CREATION_HELP}
@@ -96,7 +102,7 @@ Options:
   --yes, -y          Compatibility no-op; resolved branch contexts create without confirmation.
   --graphite         Default: create with the branch-context Graphite method.
   --plain-git        Escape hatch: create with plain Git only; no Graphite tracking, so the branch will not be part of a stack.
-  --branch <name>    Use an explicit target branch name.
+  --branch <name>    Use an explicit target branch name; explicit branches do not auto-suffix.
   --help, -h         Show this help.
 
 ${GRAPHITE_BRANCH_CREATION_HELP}
@@ -166,9 +172,12 @@ interface CreateBranchContextPreviewBase {
 	filePath: string;
 	fileName: string;
 	planKey: string;
+	requestedBranch?: string;
 	targetBranch: string;
 	branchNameForCreation?: string;
 	isExplicitTargetBranch: boolean;
+	/** Display-only preview evidence; creation re-runs core target selection authoritatively. */
+	branchSelection?: BranchContextBranchSelection;
 	slugEvidence: PlanContentSlugEvidence;
 	branchCreation: BranchCreationMethod;
 	summary?: string;
@@ -238,12 +247,27 @@ class CreateBranchContextUsageError extends Error {
 	}
 }
 
+function shouldResolveTargetBranchInPreview(options: BranchContextExtensionOptions): boolean {
+	return (
+		options.shouldResolveTargetBranchInPreview ?? options.branchContextOperations === undefined
+	);
+}
+
 function resolveBranchContextContext(
 	pi: ExtensionAPI,
 	cwd: string,
 	options: BranchContextExtensionOptions,
 ) {
-	return options.createBranchContextContext?.(pi, cwd) ?? createRealBranchContextContext({ cwd });
+	if (options.createBranchContextContext !== undefined) {
+		return options.createBranchContextContext(pi, cwd);
+	}
+	if (pi.exec !== undefined) {
+		return createBranchContextContext(
+			{ exec: (command, args, execOptions) => pi.exec(command, args, execOptions) },
+			{ cwd },
+		);
+	}
+	return createRealBranchContextContext({ cwd });
 }
 
 export function parseCreateBranchContextArgs(rawArgs: string): CreateBranchContextArgs {
@@ -394,17 +418,34 @@ export async function deriveCreateBranchContextPreview(
 	const branchCreation = args.branchCreation ?? resolveBranchContextDefaultCreation(options);
 	const target = deriveBranchContextTargetBranch(args, slugEvidence.slug, options);
 	const planKey = buildBranchContextPlanKey(slugEvidence.slug);
+	const requestedOperation = buildBranchContextCreateOperation({
+		slug: slugEvidence.slug,
+		filePath: selectedFile.filePath,
+		branchCreation,
+		...optionalEntry("branchName", target.branchNameForCreation),
+	});
+	let selectedOperation = requestedOperation;
+	if (shouldResolveTargetBranchInPreview(options)) {
+		const context = resolveBranchContextContext(pi, ctx.cwd, options);
+		selectedOperation = await selectBranchContextCreateOperationTarget({
+			cwd: ctx.cwd,
+			operation: requestedOperation,
+			git: context.git,
+			brmem: context.brmem,
+			isExplicitTargetBranch: target.isExplicitTargetBranch,
+		});
+	}
 	const base = {
 		slug: slugEvidence.slug,
 		savedPlanFileStem: selected.savedPlanFileStem,
 		filePath: selectedFile.filePath,
 		fileName: selectedFile.fileName,
 		planKey,
-		targetBranch: target.targetBranch,
-		...(target.branchNameForCreation === undefined
-			? {}
-			: { branchNameForCreation: target.branchNameForCreation }),
+		requestedBranch: target.targetBranch,
+		targetBranch: selectedOperation.branch,
+		...optionalEntry("branchNameForCreation", target.branchNameForCreation),
 		isExplicitTargetBranch: target.isExplicitTargetBranch,
+		branchSelection: selectedOperation.branchSelection,
 		branchCreation,
 		slugEvidence,
 	};
@@ -448,6 +489,7 @@ export function formatCreateBranchContextPreview(preview: CreateBranchContextPre
 	lines.push("Target:");
 	lines.push(`Branch: ${preview.targetBranch}`);
 	lines.push(`Branch creation: ${preview.branchCreation}`);
+	lines.push(...formatBranchSelectionLines(preview.branchSelection));
 	lines.push("Attach plan as:");
 	lines.push(`Branch Memory namespace: ${BRANCH_CONTEXT_NAMESPACE}`);
 	lines.push(`Branch Memory key: ${preview.planKey}`);
@@ -991,7 +1033,7 @@ async function runGtUpstackImplLaunchTail(options: GtUpstackImplLaunchTailOption
 	presentBranchContextMessage(pi, ctx, options.successBody, options.outputDetails, "info");
 
 	const launchResult = await runBranchContextGtUpstackImplLaunch({
-		host: pi,
+		git: createGtUpstackImplGitGateway(pi),
 		ctx,
 		statusKey: GT_UPSTACK_IMPL_STATUS_KEY,
 		target,

package/src/pi/gt/git-gateway.ts

@@ -0,0 +1,11 @@
+import { piExecApiToCommandExecApi } from "@nseng-ai/foundation/command";
+import { RealGitGateway, type GitGateway } from "@nseng-ai/capability-kit/git";
+import type { ExtensionAPI } from "../host-types.ts";
+
+export const GT_UPSTACK_IMPL_CHECKOUT_TIMEOUT_MS = 30_000;
+
+export function createGtUpstackImplGitGateway(pi: ExtensionAPI): GitGateway {
+	return new RealGitGateway(piExecApiToCommandExecApi(pi), {
+		timeoutMs: GT_UPSTACK_IMPL_CHECKOUT_TIMEOUT_MS,
+	});
+}

package/src/pi/gt/upstack-impl-launch.ts

@@ -1,10 +1,8 @@
 import { type BranchContextEvidence } from "@nseng-ai/branch-context/api";
 import { formatImplBranchContextCommand } from "../surfaces.ts";
-import type { ExecResult } from "@nseng-ai/foundation/command";
 import { setRuntimeStatus } from "@nseng-ai/pi/runtime/status";
-import type { ExtensionAPI, NewSessionOptions, NewSessionResult } from "../host-types.ts";
-
-export type BranchContextGtUpstackImplHost = Pick<ExtensionAPI, "exec">;
+import type { GitGateway } from "@nseng-ai/capability-kit/git";
+import type { NewSessionOptions, NewSessionResult } from "../host-types.ts";
 
 export type BranchContextGtUpstackImplNewSessionOptions = NewSessionOptions;
 export type BranchContextGtUpstackImplNewSessionResult = NewSessionResult;
@@ -26,7 +24,7 @@ export interface BranchContextGtUpstackImplContext {
 }
 
 export interface BranchContextGtUpstackImplLaunchOptions {
-	host: BranchContextGtUpstackImplHost;
+	git: Pick<GitGateway, "checkout">;
 	ctx: BranchContextGtUpstackImplContext;
 	statusKey: string;
 	target: Pick<BranchContextEvidence, "branch" | "key">;
@@ -47,8 +45,6 @@ export type BranchContextGtUpstackImplLaunchResult =
 			parentSession?: string;
 	  };
 
-const CHECKOUT_TIMEOUT_MS = 30_000;
-
 export async function runBranchContextGtUpstackImplLaunch(
 	options: BranchContextGtUpstackImplLaunchOptions,
 ): Promise<BranchContextGtUpstackImplLaunchResult> {
@@ -60,7 +56,7 @@ export async function runBranchContextGtUpstackImplLaunch(
 	try {
 		setRuntimeStatus(options.ctx, options.statusKey, "checking out branch context…");
 		const checkout = await checkoutBranchContext({
-			host: options.host,
+			git: options.git,
 			cwd: options.ctx.cwd,
 			targetBranch: branch,
 			signal: options.signal,
@@ -118,7 +114,7 @@ export function formatBranchContextGtUpstackImplFollowUpFlow(
 type CheckoutResult = { type: "ok" } | { type: "failed"; message: string };
 
 interface CheckoutBranchContextOptions {
-	host: BranchContextGtUpstackImplHost;
+	git: Pick<GitGateway, "checkout">;
 	cwd: string;
 	targetBranch: string;
 	signal: AbortSignal | undefined;
@@ -127,28 +123,17 @@ interface CheckoutBranchContextOptions {
 async function checkoutBranchContext(
 	options: CheckoutBranchContextOptions,
 ): Promise<CheckoutResult> {
-	const result = await options.host.exec("git", ["checkout", options.targetBranch], {
+	const result = await options.git.checkout({
 		cwd: options.cwd,
-		timeout: CHECKOUT_TIMEOUT_MS,
+		branch: options.targetBranch,
 		...(options.signal === undefined ? {} : { signal: options.signal }),
 	});
-	if (result.code === 0) {
+	if (result.ok) {
 		return { type: "ok" };
 	}
 
-	const output = formatCheckoutFailureOutput(result);
 	return {
 		type: "failed",
-		message: `git checkout ${options.targetBranch} failed with exit code ${result.code}: ${output}`,
+		message: result.error.message,
 	};
 }
-
-function formatCheckoutFailureOutput(result: ExecResult): string {
-	if (result.stderr.length > 0) {
-		return result.stderr;
-	}
-	if (result.stdout.length > 0) {
-		return result.stdout;
-	}
-	return "(no output)";
-}

package/src/pi/host-types.ts

@@ -69,6 +69,7 @@ export interface BranchContextExtensionOptions {
 	branchContextPrefix?: string;
 	planStoreRoot?: string;
 	branchContextOperations?: BranchContextOperations;
+	shouldResolveTargetBranchInPreview?: boolean;
 	createBranchContextContext?: BranchContextContextFactory<[pi: ExtensionAPI, cwd: string]>;
 }
 

package/src/pi/prompts/plans-write-default.md

@@ -0,0 +1,73 @@
+Plan audience and context contract:
+
+- Treat the saved Markdown plan as the only planning context available to a completely fresh downstream implementation session.
+- Make the plan self-contained. Do not rely on this conversation, hidden context, tool transcripts, or "as discussed" references.
+- Embed all relevant context discovered during planning, including user goals, constraints, current behavior, important files/symbols/tests/docs, decisions made, rationale, rejected alternatives, assumptions, risks, and proportional validation guidance.
+- Prefer concrete file paths, symbol names, command names, expected outcomes, and implementation order over vague instructions.
+- If you inspected evidence during planning, summarize the discovered facts in the plan so the downstream agent does not need to rediscover them unless verification is required.
+
+External research/context contract:
+
+- If planning used anything outside the repository — web searches, external docs, GitHub issues/PRs, API docs, CLIs hitting remote services, local files outside the repo, or other non-repo resources — include the relevant findings inline in the saved plan.
+- Do not merely link to external resources. Summarize the concrete facts, constraints, examples, decisions, and caveats the downstream agent needs.
+- Include source/provenance where useful: URL, command, document name, issue/PR number, accessed date/time if known, and why it mattered.
+- If external findings may become stale, mark what should be revalidated during implementation.
+- Do not include secrets, credentials, private tokens, or unnecessary sensitive data.
+
+<!-- PLAN-VERIFICATION-WORKSTREAM:START refactor-execution-strategy-guidance -->
+
+Refactor execution strategy:
+
+- If the implementation includes same-shape edits across multiple files, explicitly choose an execution mode in the plan.
+- Apply the canonical guidance in \`skills/enriched-plan-save/references/refactor-execution-strategy.md\`, including the final stale-terminology grep/equivalent check when changing names or concepts.
+
+<!-- PLAN-VERIFICATION-WORKSTREAM:END refactor-execution-strategy-guidance -->
+
+Recommended saved plan sections:
+
+- Goal and user-visible outcome.
+- Planning context and discovered facts, including relevant repository state.
+- External/off-repo research context, or a note that none was used when that helps remove ambiguity.
+- Files, symbols, commands, and tests likely to change.
+- Step-by-step implementation approach.
+- Validation guidance and expected results. Do not over-specify routine test/check scope as a planning decision; leave ordinary validation coverage to the implementing agent's project policy and changed-file judgment.
+- Risks, assumptions, edge cases, and open questions.
+
+Workflow:
+
+1. Inspect the repository, documentation, and current conversation context as needed for the requested work.
+2. Produce a detailed Markdown implementation plan.
+3. Review the final Markdown plan content for completeness.
+4. Call write_saved_plan_file with the full Markdown content and optional one-sentence summary; do not generate or pass a slug.
+5. Report the saved plan evidence: file path, repo key, repo root, repo identity source, source branch, branch path segment, slug, slug model, and summary when present.
+6. Stop after reporting the saved plan evidence. Do not create a branch, write Branch Memory, or call any branch-context command/tool.
+
+Local plan store contract:
+
+- Canonical path convention: $XDG_STATE_HOME/ns/enriched-plan/<repo>/<encoded-source-branch>/<slug>.md, defaulting to $HOME/.local/state/ns/enriched-plan/<repo>/<encoded-source-branch>/<slug>.md. No fallback path is read or written; only $HOME/.local/state/ns/enriched-plan/<repo>/<encoded-source-branch>/<slug>.md is used.
+- <repo>: for github.com origins, gh--<owner>--<repo> from sanitized GitHub owner and repo path segments; for non-GitHub or origin-less repos, one sanitized path segment from the normalized remote.origin.url or real repo root path
+- <encoded-source-branch>: current branch at plan-file creation time encoded as one filesystem-safe path segment; branch slashes become --- (for example, branch-contexts/add-widget becomes branch-contexts---add-widget)
+- <slug>: semantic kebab-case saved-plan filename slug without .md; this is a local plan-store locator, not necessarily the later implementation branch slug
+- Existing saved plan file: write_saved_plan_file refuses to overwrite it; do not manually choose a replacement slug.
+- Working-tree behavior: no checked-in plan file is created.
+
+Saved-plan filename slug rules:
+
+- write_saved_plan_file derives the final saved-plan filename slug from the final plan content through the Codex-backed slug model.
+- Do not generate, guess, or pass a slug yourself.
+- The derived slug is kebab-case, 3–7 words, specific to the work described by the final plan, and rejects dates, random IDs, and generic-only slugs.
+
+When the plan is ready, call write_saved_plan_file with:
+
+- content: the complete reviewed Markdown plan content
+- summary: optional one-sentence summary of the plan
+
+Exact tool call shape:
+\`\`\`json
+{
+"content": "# Plan\\n...",
+"summary": "One-sentence summary of the plan."
+}
+\`\`\`
+
+If summary is not useful, omit it from the tool call rather than passing an empty string. Do not create target branches or write Branch Memory in this workflow.