@linimin/pi-letscook 0.1.66 → 0.1.68

package/.agent/README.md

@@ -13,6 +13,8 @@ This repository uses the `completion` workflow for long-running coding tasks.
 ## Ignored canonical execution state
 
 - `.agent/state.json`
+- `.agent/startup-plan.json`
+- `.agent/startup-plan.md`
 - `.agent/plan.json`
 - `.agent/active-slice.json`
 - `.agent/slice-history.jsonl`
@@ -21,6 +23,8 @@ This repository uses the `completion` workflow for long-running coding tasks.
 - `.agent/*.log`
 - `.agent/tmp/`
 
+`.agent/startup-plan.json` plus `.agent/startup-plan.md` preserve the approved workflow startup plan captured at `/cook`. `completion-regrounder` consumes that plan as planning input, then derives canonical slices in `.agent/plan.json` from current repo truth.
+
 `.agent/verification-evidence.json` is the durable canonical record of deterministic verification for the selected slice or current HEAD. Recovery, review, audit, and stop-check reminder surfaces consume it instead of temp-only artifacts or conversational summaries when it is populated.
 
 The source of truth for long-running completion work is canonical `.agent/**` state plus current repo truth.

package/.agent/verify_completion_control_plane.sh

@@ -82,15 +82,23 @@ function trackedDiffFiles(fromCommit, toCommit) {
 
 const profile = readJson('.agent/profile.json');
 const state = readJson('.agent/state.json');
+const startupPlan = readJson('.agent/startup-plan.json');
 const plan = readJson('.agent/plan.json');
 const active = readJson('.agent/active-slice.json');
 const evidence = readJson('.agent/verification-evidence.json');
+let startupPlanMarkdown = '';
+try {
+  startupPlanMarkdown = fs.readFileSync('.agent/startup-plan.md', 'utf8');
+} catch (error) {
+  fail('.agent/startup-plan.md must be present and readable: ' + error.message);
+}
 
 ensureTrackedContractFiles();
 
 for (const [file, record] of [
   ['.agent/profile.json', profile],
   ['.agent/state.json', state],
+  ['.agent/startup-plan.json', startupPlan],
   ['.agent/plan.json', plan],
   ['.agent/active-slice.json', active],
 ]) {
@@ -101,12 +109,38 @@ for (const [file, record] of [
 const taskType = asString(profile.task_type);
 const evaluationProfile = asString(profile.evaluation_profile);
 if (asString(state.task_type) !== taskType) fail('.agent/state.json task_type must match .agent/profile.json task_type');
+if (asString(startupPlan.task_type) !== taskType) fail('.agent/startup-plan.json task_type must match .agent/profile.json task_type');
 if (asString(plan.task_type) !== taskType) fail('.agent/plan.json task_type must match .agent/profile.json task_type');
 if (asString(active.task_type) !== taskType) fail('.agent/active-slice.json task_type must match .agent/profile.json task_type');
 if (asString(state.evaluation_profile) !== evaluationProfile) fail('.agent/state.json evaluation_profile must match .agent/profile.json evaluation_profile');
+if (asString(startupPlan.evaluation_profile) !== evaluationProfile) fail('.agent/startup-plan.json evaluation_profile must match .agent/profile.json evaluation_profile');
 if (asString(plan.evaluation_profile) !== evaluationProfile) fail('.agent/plan.json evaluation_profile must match .agent/profile.json evaluation_profile');
 if (asString(active.evaluation_profile) !== evaluationProfile) fail('.agent/active-slice.json evaluation_profile must match .agent/profile.json evaluation_profile');
 
+if (asString(startupPlan.artifact_type) !== 'completion-startup-plan') {
+  fail('.agent/startup-plan.json artifact_type must be completion-startup-plan');
+}
+if (asString(startupPlan.status) !== 'approved') {
+  fail('.agent/startup-plan.json status must be approved');
+}
+const startupPlanMissionAnchor = asString(startupPlan.mission_anchor);
+if (!startupPlanMissionAnchor) fail('.agent/startup-plan.json mission_anchor must be present');
+if (startupPlanMissionAnchor !== asString(state.mission_anchor)) fail('.agent/startup-plan.json mission_anchor must match .agent/state.json mission_anchor');
+if (startupPlanMissionAnchor !== asString(plan.mission_anchor)) fail('.agent/startup-plan.json mission_anchor must match .agent/plan.json mission_anchor');
+if (startupPlanMissionAnchor !== asString(active.mission_anchor)) fail('.agent/startup-plan.json mission_anchor must match .agent/active-slice.json mission_anchor');
+if (!asString(startupPlan.goal_text)) fail('.agent/startup-plan.json goal_text must be present');
+for (const field of ['scope', 'constraints', 'acceptance', 'risks', 'notes', 'planned_surfaces', 'verification_intent', 'sequencing_hints']) {
+  if (!Array.isArray(startupPlan[field])) fail('.agent/startup-plan.json is missing ' + field);
+}
+if (startupPlanMarkdown.trim().length === 0) fail('.agent/startup-plan.md must not be empty');
+if (startupPlanMissionAnchor && !startupPlanMarkdown.includes(startupPlanMissionAnchor)) {
+  fail('.agent/startup-plan.md must mention the startup-plan mission_anchor');
+}
+const startupPlanGoalText = asString(startupPlan.goal_text);
+if (startupPlanGoalText && !startupPlanMarkdown.includes(startupPlanGoalText)) {
+  fail('.agent/startup-plan.md must render the startup-plan goal_text');
+}
+
 if (asString(evidence.artifact_type) !== 'completion-verification-evidence') {
   fail('.agent/verification-evidence.json artifact_type must be completion-verification-evidence');
 }

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.68
+
+### Changed
+
+- simplified `/cook` startup sourcing so workflow proposals now come only from same-entry primary-agent startup-plan synthesis
+- stopped `/cook` from directly adopting old preview capsules or falling back to transcript-derived startup proposals
+- kept preview capsules advisory-only for humans while active-workflow replacement and next-round startup now depend on same-entry primary-agent synthesis from current task context
+
+## 0.1.67
+
+### Changed
+
+- rewrote `/cook` startup around an approved startup plan that is captured under `.agent/startup-plan.json` / `.agent/startup-plan.md` after Start instead of leaving startup intent only as advisory intake in `state.json`
+- kept `/cook` confirm-first while handing the approved startup plan to `completion-regrounder`, which now derives canonical slices from repo truth instead of treating startup intake like an implementation-ready first-slice contract
+- relaxed primary-agent `/cook` preview requirements so explicit startup plans may carry optional sequencing hints (`first_slice_goal`, `implementation_surfaces`, `verification_commands`) without requiring them before workflow startup can begin
+- updated workflow reminders, recovery capsules, regrounder/bootstrapper instructions, and public docs so canonical startup-plan persistence and regrounder-owned slice derivation stay truthful
+
 ## 0.1.66
 
 ### Changed

package/README.md

@@ -34,8 +34,9 @@ Then run `/reload` in Pi.
 2. Run `/reload` in Pi.
 3. In the main chat, either implement directly with the agent or refine the concrete repo change you want.
 4. When you want workflow mode, run `/cook`.
-5. Review the startup brief and choose **Start** or **Cancel**.
-6. Later, run `/cook` again to resume from canonical state or confirm a replacement or next-round handoff.
+5. Review the startup plan and choose **Start** or **Cancel**.
+6. After **Start**, `/cook` records the approved startup plan under `.agent/` and hands the workflow to `completion-regrounder` to split canonical slices.
+7. Later, run `/cook` again to resume from canonical state or confirm a replacement or next-round startup plan.
 
 ```text
 /cook
@@ -52,16 +53,15 @@ Then run `/reload` in Pi.
 
 ## What `/cook` expects
 
-- enough current task context for a primary-agent handoff synthesis step to produce a concrete workflow startup handoff
-- a mission and first slice concrete enough for the primary-agent handoff step to author a truthful implementation-startable handoff
-- acceptance and verification intent that can support a truthful first workflow round
+- enough current task context for a primary-agent startup-plan synthesis step to produce a concrete workflow startup plan
+- a mission, scope, acceptance, and verification intent concrete enough for `completion-regrounder` to derive truthful slices after startup
 - README/CHANGELOG updates still count as concrete repo changes
-- assistant-produced summaries and plan/spec/design-doc/proposal-only artifacts still do not count unless the primary-agent handoff step turns them into a concrete `cook_handoff` capsule
-- `/cook` first prefers a fresh explicit `cook_handoff` capsule when one already exists, but otherwise calls the primary-agent handoff synthesis step in the same `/cook` entry
+- assistant-produced summaries and plan/spec/design-doc/proposal-only artifacts still do not count unless the primary-agent startup-plan step turns them into concrete startup intake for `/cook`
+- `/cook` always runs a same-entry primary-agent startup-plan synthesis step from the current task context instead of directly adopting an old preview or transcript-derived proposal
 
-If the primary-agent handoff step still cannot prepare a concrete handoff, `/cook` fails closed, leaves canonical `.agent/**` state unchanged, and tells you to refine the mission, first slice, or verification intent in the main chat before rerunning `/cook`.
+If the startup-plan step still cannot prepare a concrete startup plan, `/cook` fails closed, leaves canonical `.agent/**` state unchanged, and tells you to refine the mission, scope, acceptance, or verification intent in the main chat before rerunning `/cook`.
 
-If a fresh explicit handoff exists but is still workflow-worthy rather than implementation-startable, `/cook` also fails closed instead of silently treating that capsule as planning support or canonical workflow state.
+If the same-entry synthesized startup plan is still too vague or planning-only to seed workflow planning, `/cook` also fails closed instead of silently treating that output as canonical workflow state.
 
 If you pass inline arguments to `/cook`, it also fails closed and tells you to move that intent into the main chat before rerunning bare `/cook`.
 
@@ -69,16 +69,17 @@ If you pass inline arguments to `/cook`, it also fails closed and tells you to m
 
 Only explicit `/cook` enters workflow mode. Ordinary prompts stay in the main chat and go straight to the primary agent.
 
-Ordinary chat can still directly implement repo changes. `/cook` is for the cases where you want workflow control rather than just implementation help, and the primary agent should prepare the handoff before you run it.
+Ordinary chat can still directly implement repo changes. `/cook` is for the cases where you want workflow control rather than just implementation help, and the primary agent should prepare the startup plan before workflow begins.
 
-When you explicitly run `/cook`, it first checks for a fresh explicit primary-agent handoff. If one is missing, it calls a same-entry primary-agent handoff synthesis step from the current task context, then asks you to **Start** or **Cancel** before rewriting canonical workflow state.
+When you explicitly run `/cook`, it always calls a same-entry primary-agent startup-plan synthesis step from the current task context, then asks you to **Start** or **Cancel** before rewriting canonical workflow state.
 
-Explicit `/cook` capsules are still valid startup intake, but they are no longer the only path because `/cook` can synthesize the primary-agent handoff in the same entry when needed.
+Optional preview capsules in ordinary chat are advisory only. `/cook` does not directly consume them as approval-ready workflow state; it synthesizes a fresh startup plan in the `/cook` entry.
 
 Important behavior:
 - `/cook` is an optional workflow boundary and manual entry point
-- startup and next-round entry stay confirm-first, using explicit primary-agent handoff data when present and otherwise running the primary-agent handoff synthesis step in the same `/cook` entry
-- active workflows resume from canonical `.agent/**` state unless a concrete replacement handoff is available or synthesized in the same `/cook` entry
+- startup and next-round entry stay confirm-first, always using same-entry primary-agent startup-plan synthesis from the current task context
+- after **Start**, `/cook` records the approved startup plan under `.agent/startup-plan.json` / `.agent/startup-plan.md`, then `completion-regrounder` derives canonical slices from repo truth
+- active workflows resume from canonical `.agent/**` state unless same-entry primary-agent startup-plan synthesis produces a concrete replacement mission
 - explicit slash commands other than `/cook` continue normally in the main chat
 - ordinary main-chat discussion may clarify, propose, or directly implement repo changes without entering workflow mode
 
@@ -94,13 +95,13 @@ I want to add login redirect handling and tests.
 
 ## What happens when you run `/cook`
 
-`/cook` first checks for a fresh explicit primary-agent handoff capsule. New-workflow entry and done-workflow next-round entry use that handoff when it already exists; otherwise `/cook` calls a same-entry primary-agent handoff synthesis step, then immediately continues to Start / Cancel if the generated handoff is concrete enough. Active workflows still resume canonical state by default unless a concrete replacement handoff is available or synthesized in the same `/cook` entry. None of this prevents ordinary-chat implementation when you choose not to enter workflow mode.
+`/cook` always runs a same-entry primary-agent startup-plan synthesis step from the current task context. If that synthesized plan is concrete enough, `/cook` continues to Start / Cancel confirmation. After **Start**, the approved startup plan is written into `.agent/startup-plan.json` / `.agent/startup-plan.md`, and `completion-regrounder` uses it to derive canonical slices from current repo truth. Active workflows still resume canonical state by default unless same-entry synthesis produces a concrete replacement mission. None of this prevents ordinary-chat implementation when you choose not to enter workflow mode.
 
 | Repo state | What you'll see |
 |---|---|
-| No workflow yet | `/cook` consumes a fresh explicit primary-agent handoff when one already exists, or synthesizes one from the primary-agent view in the same entry, then asks you to choose **Start** or **Cancel**. Stale, planning-only, or non-startable handoffs still fail closed. |
-| Active workflow exists | Usually a resume of the current workflow from canonical `.agent/**` state. If a concrete replacement handoff exists already or is synthesized in the same `/cook` entry and points to a different mission, `/cook` shows a chooser first and only rewrites canonical state after you confirm the replacement. Ambiguous or missing replacement handoff stays conservative. |
-| Previous workflow is `done` | `/cook` can start the next implementation round from a fresh explicit primary-agent handoff or from the same-entry primary-agent handoff synthesis step behind **Start** or **Cancel**. Weak or planning-only next-round handoffs still fail closed. |
+| No workflow yet | `/cook` synthesizes a primary-agent startup plan in the same entry, then asks you to choose **Start** or **Cancel**. After **Start**, the approved startup plan is persisted under `.agent/` and `completion-regrounder` derives canonical slices. Weak, planning-only, or non-startable synthesized plans still fail closed. |
+| Active workflow exists | Usually a resume of the current workflow from canonical `.agent/**` state. If same-entry primary-agent startup-plan synthesis produces a concrete replacement mission, `/cook` shows a chooser first and only rewrites canonical state after you confirm the replacement. Ambiguous, missing, or non-startable synthesized replacement plans stay conservative. |
+| Previous workflow is `done` | `/cook` can start the next implementation round from a same-entry primary-agent startup-plan synthesis step behind **Start** or **Cancel**. Weak or planning-only synthesized next-round startup plans still fail closed. |
 
 ## Confirmation and fail-closed behavior
 
@@ -114,9 +115,9 @@ I want to add login redirect handling and tests.
 
 When you accept startup or refocus, `/cook` persists the chosen workflow state in canonical `.agent/**` files before the re-ground round begins.
 
-The confirmed startup brief is also preserved there as advisory intake for later re-grounding. It does not replace `.agent/plan.json` or `.agent/active-slice.json`, which remain under regrounder authority.
+The confirmed startup plan is preserved under `.agent/startup-plan.json` / `.agent/startup-plan.md` and summarized in `state.json` as advisory intake for later re-grounding. It does not replace `.agent/plan.json` or `.agent/active-slice.json`, which remain under regrounder authority.
 
-The pre-`/cook` handoff capsule itself is not canonical workflow state. It is only startup intake for `/cook`.
+The pre-`/cook` preview capsule itself is not canonical workflow state. It is only an advisory preview for the human; `/cook` still synthesizes a fresh startup plan in the entry where workflow actually begins.
 
 ## Observability
 
@@ -202,6 +203,8 @@ This package stores canonical workflow state under:
   verify_completion_stop.sh
   verify_completion_control_plane.sh
   state.json
+  startup-plan.json
+  startup-plan.md
   plan.json
   active-slice.json
   slice-history.jsonl
@@ -228,6 +231,8 @@ Tracked repo-contract files:
 Ignored execution-state files:
 
 - `.agent/state.json`
+- `.agent/startup-plan.json`
+- `.agent/startup-plan.md`
 - `.agent/plan.json`
 - `.agent/active-slice.json`
 - `.agent/slice-history.jsonl`
@@ -239,7 +244,7 @@ Ignored execution-state files:
 In short:
 
 - tracked `.agent` files define the repo-level workflow contract
-- ignored `.agent` files are the local control-plane state for the current run
+- ignored `.agent` files are the local control-plane state for the current run, including the approved startup plan captured at `/cook`
 
 ## Package layout
 

package/agents/completion-bootstrapper.md

@@ -14,6 +14,7 @@ You are an onboarding-only control-plane role. You may:
 - create or repair tracked completion contract files under `.agent/**`
 - update `.gitignore` so tracked contract files remain tracked while execution artifacts remain ignored
 - initialize missing or invalid canonical execution-state files only when repair is required for a truthful handoff
+- preserve any approved startup plan already recorded in `.agent/startup-plan.json`
 - return the exact handoff payload for `completion-regrounder`
 
 You must not:
@@ -40,7 +41,7 @@ These lines are for workflow observability, not hidden reasoning. Keep them brie
 3. If repo intent or validation entrypoint is ambiguous, ask one short clarifying question.
 4. Create or repair `.agent/README.md`, `.agent/mission.md`, `.agent/profile.json`, `.agent/verify_completion_stop.sh`, and `.agent/verify_completion_control_plane.sh`, keeping them truthful to current repo reality.
 5. Update `.gitignore` so `.agent/*` remains ignored except the tracked repo-contract files, and keep `.agent/tmp/` ignored as scratch space.
-6. Initialize `.agent/state.json`, `.agent/plan.json`, and `.agent/active-slice.json` only when they are missing, unreadable, or structurally invalid. Preserve any existing truthful execution state.
+6. Initialize `.agent/state.json`, `.agent/startup-plan.json`, `.agent/startup-plan.md`, `.agent/plan.json`, and `.agent/active-slice.json` only when they are missing, unreadable, or structurally invalid. Preserve any existing truthful execution state.
 7. Stop after canonical bootstrap or repair is truthful and return the handoff to `completion-regrounder`.
 
 Return exactly this fixed report format:

package/agents/completion-regrounder.md

@@ -12,6 +12,7 @@ You are the canonical reconciliation role. You may:
 
 - read current repo truth and canonical `.agent` state
 - write canonical `.agent` state and `.gitignore`
+- read the approved startup plan in `.agent/startup-plan.json` and `.agent/startup-plan.md`
 - rebuild or reconcile `.agent/plan.json`
 - confirm or update `.agent/active-slice.json` and `.agent/state.json`
 - reopen slices whose acceptance criteria no longer hold
@@ -36,25 +37,30 @@ These lines are for workflow observability, not hidden reasoning. Keep them brie
 
 1. Read canonical `.agent` inputs before changing canonical state.
 2. Read current git status, recent git history, and repo surfaces relevant to the locked or remaining contract IDs.
-3. Reconcile `.agent/plan.json` against current repo truth.
-4. Revalidate every slice's `acceptance_criteria` against current repo truth and update `status` plus `evidence` accordingly.
-5. Reopen any previously `done` slice whose acceptance criteria no longer hold.
-6. Keep `.agent/state.json` and `.agent/active-slice.json` truthful, including `current_phase`, `continuation_policy`, `continuation_reason`, `next_mandatory_role`, and any exact implementer handoff snapshot fields.
-7. Reconcile canonical state after review, audit, and final stop verification waves when required.
-8. If the latest committed slice leaves the tracked and unignored worktree dirty, treat that dirty state as a blocker, reopen or continue that latest slice for reconciliation, set `Next role to invoke` to `completion-implementer`, and do not select or hand off any different next slice until it is reconciled.
-9. When reconciling after review, audit, or dirty-worktree follow-up for the latest committed slice, emit an explicit reconciliation record decision:
+3. Read `.agent/startup-plan.json` / `.agent/startup-plan.md` and extract the approved mission, scope, acceptance, risks, planned surfaces, verification intent, and any sequencing hints.
+4. Treat that startup plan as planning input only, then derive the smallest truthful canonical slices from current repo truth instead of copying startup-plan structure blindly into `.agent/plan.json`.
+5. If current repo truth contradicts, narrows, or broadens the approved startup plan, preserve the startup-plan record as historical intake, explain the deviation explicitly, and reconcile `.agent/plan.json` / `.agent/state.json` to the newer truth.
+6. Emit an explicit startup-plan reconciliation outcome in your report so the workflow driver can see whether canonical slices adopted the startup plan as-is or deviated from it.
+7. Revalidate every slice's `acceptance_criteria` against current repo truth and update `status` plus `evidence` accordingly.
+8. Reopen any previously `done` slice whose acceptance criteria no longer hold.
+9. Keep `.agent/state.json` and `.agent/active-slice.json` truthful, including `current_phase`, `continuation_policy`, `continuation_reason`, `next_mandatory_role`, and any exact implementer handoff snapshot fields.
+10. Reconcile canonical state after review, audit, and final stop verification waves when required.
+11. If the latest committed slice leaves the tracked and unignored worktree dirty, treat that dirty state as a blocker, reopen or continue that latest slice for reconciliation, set `Next role to invoke` to `completion-implementer`, and do not select or hand off any different next slice until it is reconciled.
+12. When reconciling after review, audit, or dirty-worktree follow-up for the latest committed slice, emit an explicit reconciliation record decision:
    - `accepted` only when the latest committed slice is truthfully accepted as-is
    - `reopened` only when the latest committed slice must be reopened for follow-up work
    - `none` when this re-ground was not a post-commit reconciliation decision
-10. If you emit `accepted` or `reopened`, also emit the exact reconciled slice id in the report.
-11. If a slice is already selected, ensure `.agent/active-slice.json` contains the exact implementer handoff snapshot and return that exact handoff payload for `completion-implementer` instead of implementing it yourself.
-12. If no slice is selected, return the exact next recommended slice and why.
+13. If you emit `accepted` or `reopened`, also emit the exact reconciled slice id in the report.
+14. If a slice is already selected, ensure `.agent/active-slice.json` contains the exact implementer handoff snapshot and return that exact handoff payload for `completion-implementer` instead of implementing it yourself.
+15. If no slice is selected, return the exact next recommended slice and why.
 
 Output format:
 
 - `MISSION ANCHOR: ...`
 - `Remaining contract IDs: ...`
 - `Canonical re-ground applied: yes/no - ...`
+- `Startup plan adopted as-is: yes/no - ...`
+- `Startup-plan deviations from repo truth: ...`
 - `Acceptance criteria revalidated: yes/no - ...`
 - `Tracked and unignored worktree is clean: yes/no`
 - `Reopened slices: ...`

package/extensions/completion/driver.ts

@@ -16,7 +16,7 @@ import {
 	loadCompletionSnapshot,
 	writeJsonFile,
 } from "./state-store";
-import { buildAdvisoryStartupBrief } from "./prompt-surfaces";
+import { buildAdvisoryStartupBrief, buildApprovedStartupPlan, buildApprovedStartupPlanMarkdown } from "./prompt-surfaces";
 import type { CompletionStateSnapshot } from "./types";
 
 type ContextProposalAnalysis = {
@@ -38,7 +38,7 @@ type ContextProposalAlternate = {
 	analysis: ContextProposalAnalysis;
 	goalText: string;
 	basisPreview: string;
-	source: "session" | "analyst" | "handoff_capsule";
+	source: "session" | "analyst" | "handoff_capsule" | "deferred_primary_agent_handoff";
 };
 
 type ContextProposal = ContextProposalAlternate & {
@@ -71,10 +71,10 @@ type ActiveWorkflowProposalAssessment = {
 	proposal?: ContextProposal;
 	blockedFailureMessage?: string;
 	reason:
-		| "matching_mission"
-		| "missing_explicit_handoff"
-		| "fresh_explicit_handoff"
-		| "fresh_explicit_handoff_not_startable";
+		| "matching_generated_startup_plan"
+		| "no_generated_startup_plan"
+		| "generated_replacement_startup_plan"
+		| "generated_startup_plan_not_startable";
 };
 
 type ExistingWorkflowChooserOptions = {
@@ -126,7 +126,6 @@ export type CompletionDriverDeps = {
 	) => string;
 	completionResumePrompt: (taskType: string, evaluationProfile: string) => string;
 	deriveCookContextProposal: (ctx: DriverContext, projectName: string) => Promise<CookContextProposalResult>;
-	deriveCookStartupProposal: (ctx: DriverContext, projectName: string) => Promise<CookContextProposalResult>;
 	confirmContextProposal: (
 		ctx: { hasUI: boolean; ui: any },
 		proposal: ContextProposal,
@@ -137,7 +136,12 @@ export type CompletionDriverDeps = {
 	scaffoldCompletionFiles: (
 		root: string,
 		missionAnchor: string,
-		options?: { analysis?: ContextProposalAnalysis; continuationReason?: string; advisoryStartupBrief?: Record<string, unknown> },
+		options?: {
+			analysis?: ContextProposalAnalysis;
+			continuationReason?: string;
+			advisoryStartupBrief?: Record<string, unknown>;
+			approvedStartupPlan?: Record<string, unknown>;
+		},
 	) => Promise<{ root: string; created: string[] }>;
 	maybeWriteActiveWorkflowRoutingSnapshot: (assessment: ActiveWorkflowProposalAssessment) => void;
 	missionAnchorsLikelyEquivalent: (left: string, right: string) => boolean;
@@ -327,7 +331,7 @@ async function assessActiveWorkflowProposalRouting(
 			action: "blocked",
 			currentMissionAnchor: currentMission,
 			blockedFailureMessage: proposalResult.blockedFailureMessage,
-			reason: "fresh_explicit_handoff_not_startable",
+			reason: "generated_startup_plan_not_startable",
 		};
 		deps.maybeWriteActiveWorkflowRoutingSnapshot(assessment);
 		return assessment;
@@ -337,7 +341,7 @@ async function assessActiveWorkflowProposalRouting(
 		const assessment: ActiveWorkflowProposalAssessment = {
 			action: "continue",
 			currentMissionAnchor: currentMission,
-			reason: "missing_explicit_handoff",
+			reason: "no_generated_startup_plan",
 		};
 		deps.maybeWriteActiveWorkflowRoutingSnapshot(assessment);
 		return assessment;
@@ -347,7 +351,7 @@ async function assessActiveWorkflowProposalRouting(
 			action: "continue",
 			currentMissionAnchor: currentMission,
 			proposal,
-			reason: "matching_mission",
+			reason: "matching_generated_startup_plan",
 		};
 		deps.maybeWriteActiveWorkflowRoutingSnapshot(assessment);
 		return assessment;
@@ -356,7 +360,7 @@ async function assessActiveWorkflowProposalRouting(
 		action: "refocus",
 		currentMissionAnchor: currentMission,
 		proposal,
-		reason: "fresh_explicit_handoff",
+		reason: "generated_replacement_startup_plan",
 	};
 	deps.maybeWriteActiveWorkflowRoutingSnapshot(assessment);
 	return assessment;
@@ -419,8 +423,8 @@ async function confirmExistingWorkflowProposal(
 	const continueChoice = "Continue current workflow\n\nKeep the current mission and treat the new goal as extra direction only.";
 	const buildRefocusChoice = (candidate: ContextProposalAlternate, variant: "primary" | "alternate") =>
 		variant === "primary"
-			? `${options.refocusChoiceLabel ?? "Start new workflow from recent discussion\n\nReview the proposed replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state."}\n\n${summarizeProposalForChoice(candidate)}`
-			: `${options.alternateChoiceLabel ?? "Start alternate workflow from recent discussion\n\nReview this alternate replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state."}\n\n${summarizeProposalForChoice(candidate)}`;
+			? `${options.refocusChoiceLabel ?? "Start new workflow from synthesized startup plan\n\nReview the proposed replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state."}\n\n${summarizeProposalForChoice(candidate)}`
+			: `${options.alternateChoiceLabel ?? "Start alternate workflow from synthesized startup plan\n\nReview this alternate replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state."}\n\n${summarizeProposalForChoice(candidate)}`;
 	const refocusChoices = candidateProposals.map((candidate, index) => buildRefocusChoice(candidate, index === 0 ? "primary" : "alternate"));
 	const cancelChoice = `Cancel\n\nKeep the current workflow unchanged. ${deps.mainChatRerunGuidance}`;
 	deps.maybeWriteTestSnapshot(
@@ -479,6 +483,7 @@ async function refocusCompletionMission(
 	analysis: ContextProposalAnalysis | undefined,
 	deps: CompletionDriverDeps,
 	advisoryStartupBrief?: Record<string, unknown>,
+	approvedStartupPlan?: Record<string, unknown>,
 ): Promise<void> {
 	const requiredStopJudges = asNumber(snapshot.profile?.required_stop_judges) ?? 3;
 	const root = snapshot.files.root;
@@ -506,10 +511,32 @@ async function refocusCompletionMission(
 		plan_basis: "user_refocus",
 	};
 	const nextActive = defaultActiveSlice(missionAnchor, { taskType: routing.taskType, evaluationProfile: routing.evaluationProfile });
+	const nextStartupPlan =
+		approvedStartupPlan ?? {
+			artifact_type: "completion-startup-plan",
+			schema_version: 1,
+			status: "approved",
+			source: "recent_discussion",
+			captured_at: null,
+			mission_anchor: missionAnchor,
+			goal_text: rawGoal,
+			task_type: routing.taskType,
+			evaluation_profile: routing.evaluationProfile,
+			scope: [],
+			constraints: [],
+			acceptance: [],
+			risks: [],
+			notes: ["No approved startup plan summary is available for this refocused workflow."],
+			planned_surfaces: [],
+			verification_intent: [],
+			sequencing_hints: [],
+		};
 	await Promise.all([
 		fsp.writeFile(path.join(snapshot.files.agentDir, "mission.md"), buildMission(path.basename(root), missionAnchor), "utf8"),
 		writeJsonFile(snapshot.files.profilePath, nextProfile),
 		writeJsonFile(snapshot.files.statePath, nextState),
+		writeJsonFile(snapshot.files.startupPlanPath, nextStartupPlan),
+		fsp.writeFile(snapshot.files.startupPlanMarkdownPath, buildApprovedStartupPlanMarkdown(nextStartupPlan as any), "utf8"),
 		writeJsonFile(snapshot.files.planPath, nextPlan),
 		writeJsonFile(snapshot.files.activePath, nextActive),
 		writeJsonFile(snapshot.files.verificationEvidencePath, defaultVerificationEvidence()),
@@ -547,16 +574,22 @@ export async function runCookEntry(
 			return;
 		}
 		const decision = await deps.confirmContextProposal(ctx, proposal, {
-			title: "Start a completion workflow from this startup brief?",
+			title: "Start a completion workflow from this startup plan?",
 		});
 		if (!decision) {
-			deps.emitCommandText(ctx, buildCookCancellationMessage("Cancelled recent-discussion workflow proposal", deps), "info");
+			deps.emitCommandText(ctx, buildCookCancellationMessage("Cancelled synthesized startup plan", deps), "info");
 			return;
 		}
 		goal = decision.goalText;
 		kickoffMissionAnchor = decision.missionAnchor;
 		kickoffAnalysis = decision.analysis;
 		const startupRouting = deps.finalizeContextProposalAnalysis(kickoffAnalysis, [goal ?? kickoffMissionAnchor ?? projectName]);
+		const advisoryStartupBrief = buildAdvisoryStartupBrief({ proposal, analysis: decision.analysis });
+		const approvedStartupPlan = buildApprovedStartupPlan({
+			proposal,
+			analysis: decision.analysis,
+			missionAnchor: kickoffMissionAnchor ?? projectName,
+		});
 		const created = await deps.scaffoldCompletionFiles(root, kickoffMissionAnchor ?? projectName, {
 			analysis: startupRouting,
 			continuationReason: deps.buildContextProposalContinuationReason(
@@ -564,11 +597,12 @@ export async function runCookEntry(
 				goal ?? kickoffMissionAnchor ?? projectName,
 				startupRouting,
 			),
-			advisoryStartupBrief: buildAdvisoryStartupBrief({ proposal, analysis: decision.analysis }),
+			advisoryStartupBrief,
+			approvedStartupPlan,
 		});
 		deps.emitCommandText(
 			ctx,
-			`Initialized completion control plane in ${created.root}${created.created.length > 0 ? ` (${created.created.length} files created)` : ""}`,
+			`Initialized completion control plane in ${created.root}${created.created.length > 0 ? ` (${created.created.length} files created)` : ""} and recorded the approved startup plan under .agent/startup-plan.json`,
 			"info",
 		);
 		snapshot = await loadCompletionSnapshot(root);
@@ -592,7 +626,7 @@ export async function runCookEntry(
 				return;
 			}
 			const decision = await deps.confirmContextProposal(ctx, proposal, {
-				title: "The previous completion workflow is done. Start the next workflow round from this startup brief?",
+				title: "The previous completion workflow is done. Start the next workflow round from this startup plan?",
 			});
 			if (!decision) {
 				deps.emitCommandText(ctx, buildCookCancellationMessage("Cancelled next workflow round proposal", deps), "info");
@@ -601,16 +635,23 @@ export async function runCookEntry(
 			goal = decision.goalText;
 			kickoffIntent = "refocus";
 			kickoffMissionAnchor = decision.missionAnchor;
+			const advisoryStartupBrief = buildAdvisoryStartupBrief({ proposal, analysis: decision.analysis });
+			const approvedStartupPlan = buildApprovedStartupPlan({
+				proposal,
+				analysis: decision.analysis,
+				missionAnchor: decision.missionAnchor,
+			});
 			await refocusCompletionMission(
 				snapshot,
 				decision.missionAnchor,
 				decision.goalText,
 				decision.analysis,
 				deps,
-				buildAdvisoryStartupBrief({ proposal, analysis: decision.analysis }),
+				advisoryStartupBrief,
+				approvedStartupPlan,
 			);
 			snapshot = (await loadCompletionSnapshot(snapshot.files.root)) ?? snapshot;
-			deps.emitCommandText(ctx, `Started a new completion workflow round from explicit primary-agent handoff: ${decision.missionAnchor}`, "info");
+			deps.emitCommandText(ctx, `Started a new completion workflow round and recorded the approved startup plan: ${decision.missionAnchor}`, "info");
 		} else {
 			const assessment = await assessActiveWorkflowProposalRouting(ctx, snapshot, deps);
 			if (assessment.action === "blocked") {
@@ -621,19 +662,19 @@ export async function runCookEntry(
 				await resumeActiveWorkflowFromCanonicalState(pi, ctx, snapshot, deps);
 				return;
 			}
-			const explicitReplacement = assessment.reason === "fresh_explicit_handoff";
+			const generatedReplacement = assessment.reason === "generated_replacement_startup_plan";
 			const decision = await confirmExistingWorkflowProposal(ctx, snapshot, assessment.proposal, deps, {
-				intro: explicitReplacement
-					? "A fresh explicit primary-agent handoff proposes replacing the current workflow. Choose how /cook should proceed:"
+				intro: generatedReplacement
+					? "A same-entry primary-agent startup plan proposes replacing the current workflow. Choose how /cook should proceed:"
 					: "A replacement workflow is ready. Choose how /cook should proceed:",
-				proposedMissionLabel: explicitReplacement
-					? "Proposed mission from explicit primary-agent handoff"
+				proposedMissionLabel: generatedReplacement
+					? "Proposed mission from same-entry primary-agent startup plan"
 					: "Proposed mission",
-				refocusChoiceLabel: explicitReplacement
-					? "Start new workflow from explicit primary-agent handoff\n\nReview the proposed replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state."
+				refocusChoiceLabel: generatedReplacement
+					? "Start new workflow from same-entry primary-agent startup plan\n\nReview the proposed replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state."
 					: "Start new workflow\n\nReview the proposed replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state.",
-				alternateChoiceLabel: explicitReplacement
-					? "Start alternate workflow from explicit primary-agent handoff\n\nReview this alternate replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state."
+				alternateChoiceLabel: generatedReplacement
+					? "Start alternate workflow from same-entry primary-agent startup plan\n\nReview this alternate replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state."
 					: undefined,
 				comparison: "strict",
 			});
@@ -647,9 +688,9 @@ export async function runCookEntry(
 			}
 			const selectedProposal = decision.proposal;
 			const proposalDecision = await deps.confirmContextProposal(ctx, selectedProposal, {
-				title: assessment.reason === "fresh_explicit_handoff"
-					? "Start the replacement workflow from this explicit startup brief?"
-					: "Start the replacement workflow from this startup brief?",
+				title: assessment.reason === "generated_replacement_startup_plan"
+					? "Start the replacement workflow from this synthesized startup plan?"
+					: "Start the replacement workflow from this startup plan?",
 			});
 			if (!proposalDecision) {
 				deps.emitCommandText(ctx, buildCookCancellationMessage("Cancelled replacement workflow proposal", deps), "info");
@@ -658,20 +699,27 @@ export async function runCookEntry(
 			goal = proposalDecision.goalText;
 			kickoffIntent = "refocus";
 			kickoffMissionAnchor = proposalDecision.missionAnchor;
+			const advisoryStartupBrief = buildAdvisoryStartupBrief({ proposal: selectedProposal, analysis: proposalDecision.analysis });
+			const approvedStartupPlan = buildApprovedStartupPlan({
+				proposal: selectedProposal,
+				analysis: proposalDecision.analysis,
+				missionAnchor: proposalDecision.missionAnchor,
+			});
 			await refocusCompletionMission(
 				snapshot,
 				proposalDecision.missionAnchor,
 				proposalDecision.goalText,
 				proposalDecision.analysis,
 				deps,
-				buildAdvisoryStartupBrief({ proposal: selectedProposal, analysis: proposalDecision.analysis }),
+				advisoryStartupBrief,
+				approvedStartupPlan,
 			);
 			snapshot = (await loadCompletionSnapshot(snapshot.files.root)) ?? snapshot;
 			deps.emitCommandText(
 				ctx,
-				assessment.reason === "fresh_explicit_handoff"
-					? `Refocused completion mission from explicit primary-agent handoff to: ${proposalDecision.missionAnchor}`
-					: `Refocused completion mission to: ${proposalDecision.missionAnchor}`,
+				assessment.reason === "generated_replacement_startup_plan"
+					? `Refocused completion mission from same-entry primary-agent startup plan and rewrote the approved startup plan to: ${proposalDecision.missionAnchor}`
+					: `Refocused completion mission and rewrote the approved startup plan to: ${proposalDecision.missionAnchor}`,
 				"info",
 			);
 		}