@linimin/pi-letscook 0.1.53 → 0.1.55

package/extensions/completion/role-runner.ts

@@ -7,17 +7,11 @@ import { DynamicBorder, parseFrontmatter } from "@mariozechner/pi-coding-agent";
 import { Container, Text } from "@mariozechner/pi-tui";
 import {
 	buildContextProposalAnalystPromptFromEntries,
-	extractJsonObjectFromText,
 	parseContextProposalAnalystOutput,
-	serializeRecentDiscussionEntries,
 	type ContextProposal,
 	type RecentDiscussionEntry,
 } from "./proposal";
-import {
-	buildCookTriggerClassifierPrompt,
-	contextProposalAnalystProgressLines,
-	maybeWriteCookTriggerClassifierSnapshot,
-} from "./prompt-surfaces";
+import { contextProposalAnalystProgressLines } from "./prompt-surfaces";
 import {
 	applyLiveRoleEvent,
 	buildInlineRunningLines,
@@ -29,15 +23,9 @@ import {
 	refreshCompletionStatus,
 	type RoleMessage,
 } from "./status-surface";
-import { completionRootKey, findCompletionRoot, findRepoRoot, loadCompletionDataForReminder } from "./state-store";
+import { completionRootKey, findCompletionRoot, findRepoRoot } from "./state-store";
 import { parseReportFields, transcribeRoleOutput, type TranscriptionResult } from "./transcription";
-import type {
-	AgentDefinition,
-	CompletionRole,
-	CookTriggerClassification,
-	JsonRecord,
-	LiveRoleActivity,
-} from "./types";
+import type { AgentDefinition, CompletionRole, JsonRecord, LiveRoleActivity } from "./types";
 
 export type RunCompletionRoleParams = {
 	root: string;
@@ -79,21 +67,6 @@ export type AnalyzeContextProposalWithAgentParams = {
 	getCtxUi: <T extends { ui: any }>(ctx: T) => any | undefined;
 };
 
-export type ClassifyCookTriggerIntentWithAgentParams = {
-	ctx: { cwd: string; hasUI: boolean; ui: any; model?: any };
-	projectName: string;
-	inputText: string;
-	recentEntries: RecentDiscussionEntry[];
-	workflowContextLines?: string[];
-};
-
-export type CookTriggerClassifierResult = {
-	status: "classified" | "timeout" | "invalid_output" | "error";
-	classification?: CookTriggerClassification;
-	rawOutput?: string;
-	errorMessage?: string;
-};
-
 const AGENT_HOME = path.join(os.homedir(), ".pi", "agent");
 const EXTENSION_DIR = typeof __dirname === "string" ? __dirname : process.cwd();
 const PACKAGE_ROOT_CANDIDATE = path.resolve(EXTENSION_DIR, "..", "..");
@@ -106,7 +79,7 @@ const CONTEXT_PROPOSAL_ANALYST_SYSTEM_PROMPT = [
 	"You may additionally include optional keys alternate_missions, completed_topics, and negated_topics when they are clearly supported by the discussion and canonical workflow context.",
 	"mission must be a concise implementation mission anchor sentence.",
 	"Prefer the latest clear user implementation intent over older background context when they differ.",
-	"If canonical workflow context includes a /cook hint, treat it as a high-priority disambiguation signal, but do not let it bypass clear contradictory repo truth or approval-only confirmation.",
+	"Use recent user/custom discussion plus canonical workflow context only; do not infer startup intent from slash-command arguments or let planning-only artifacts bypass approval-only confirmation.",
 	"Do not reopen work that the canonical workflow context says is done, completed, historical, or already covered unless the latest discussion clearly asks to revisit it.",
 	"Treat stale, weakly related, or explicitly negated topics as noise instead of mission scope.",
 	"scope must contain only work items that directly support the mission.",
@@ -120,28 +93,6 @@ const CONTEXT_PROPOSAL_ANALYST_SYSTEM_PROMPT = [
 ].join(" ");
 const STARTUP_ANALYST_ROLE = "cook-proposal-analyst";
 const ANALYST_HEARTBEAT_MS = 5_000;
-const COOK_TRIGGER_CLASSIFIER_SYSTEM_PROMPT = [
-	"You classify whether the latest user input should stay in the main chat or be intercepted by the workflow-aware router into the canonical /cook workflow before the primary agent starts implementation work.",
-	"Assume router mode reviews every non-bypass normal user turn. Do not require short trigger phrases or explicit /cook text before choosing offer_workflow.",
-	"Do not emit markdown, code fences, or commentary.",
-	"Return exactly one JSON object with keys: decision, confidence, workflow_bias, reason, evidence, riskFlags, focusHint. You may also include optional keys requires_clarification, clarification_slots, and adopted_artifact when clearly supported.",
-	"decision must be exactly one of offer_workflow, normal_prompt, or unclear.",
-	"Use offer_workflow when the latest input is directly asking to start, resume, refocus, or continue workflow-worthy repo work through the completion boundary, or explicitly asking to let /cook take over.",
-	"Use normal_prompt for ordinary questions, explanations, analysis-only requests, or direct requests that should stay with the primary agent.",
-	"Use unclear for ambiguous approvals, acknowledgements, or mixed signals where false-positive routing risk is material.",
-	"workflow_bias must be exactly one of startup, resume, refocus, next_round, or unknown.",
-	"Use startup when there is no active workflow yet, resume when the user is clearly continuing the current workflow, refocus when the user is clearly switching the active workflow to a different goal, and next_round when the previous workflow is done and the user is starting a new round.",
-	"When decision is not offer_workflow, prefer workflow_bias=unknown unless a stronger routing hint would still aid debugging.",
-	"confidence must be a number from 0 to 1.",
-	"reason must be a single concise sentence.",
-	"evidence must be an array of short grounded strings.",
-	"riskFlags must be an array of short machine-readable strings such as ambiguous-approval, possible-normal-agent-request, or active-workflow-refocus-risk.",
-	"focusHint is optional, must stay short, and must never rewrite the workflow mission or invent scope.",
-	"When explicit user adoption of a recent plan or repo markdown artifact is evident, adopted_artifact may describe it with kind recent_plan|repo_markdown, path when known, and basis explicit_user_adoption.",
-	"requires_clarification may be true when chooser-style disambiguation is safer than guessing, and clarification_slots may list short needs such as goal, scope, or non_goal.",
-	"Short acknowledgements like 好, 可以, ok, sure, or 那就這樣 should usually be unclear unless the surrounding context makes the handoff explicit.",
-].join(" ");
-const COOK_TRIGGER_CLASSIFIER_TIMEOUT_MS = 10_000;
 
 class StartupAnalystOverlay extends Container {
 	private readonly border: DynamicBorder;
@@ -373,263 +324,6 @@ export async function analyzeContextProposalWithAgent(params: AnalyzeContextProp
 	}
 }
 
-function uniqueStrings(items: string[]): string[] {
-	const seen = new Set<string>();
-	const result: string[] = [];
-	for (const item of items) {
-		const normalized = item.trim();
-		if (!normalized) continue;
-		const key = normalized.toLowerCase();
-		if (seen.has(key)) continue;
-		seen.add(key);
-		result.push(normalized);
-	}
-	return result;
-}
-
-function localAsStringArray(value: unknown): string[] {
-	return Array.isArray(value)
-		? uniqueStrings(value.filter((item): item is string => typeof item === "string" && item.trim().length > 0))
-		: [];
-}
-
-function confidenceFromUnknown(value: unknown): number {
-	const parsed =
-		typeof value === "number"
-			? value
-			: typeof value === "string" && value.trim().length > 0
-				? Number.parseFloat(value)
-				: Number.NaN;
-	if (!Number.isFinite(parsed)) return 0;
-	return Math.min(1, Math.max(0, parsed));
-}
-
-function parseCookTriggerClassification(raw: string): CookTriggerClassification | undefined {
-	const jsonText = extractJsonObjectFromText(raw);
-	if (!jsonText) return undefined;
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(jsonText);
-	} catch {
-		return undefined;
-	}
-	if (!isRecord(parsed)) return undefined;
-	const rawDecision = asString(parsed.decision ?? parsed.intent);
-	const decision =
-		rawDecision === "offer_workflow" || rawDecision === "normal_prompt" || rawDecision === "unclear"
-			? rawDecision
-			: rawDecision === "route_to_cook"
-				? "offer_workflow"
-				: undefined;
-	if (!decision) return undefined;
-	const rawWorkflowBias = asString(parsed.workflow_bias ?? parsed.workflowBias ?? parsed.routing_bias ?? parsed.routingBias);
-	const workflowBias =
-		rawWorkflowBias === "startup" ||
-		rawWorkflowBias === "resume" ||
-		rawWorkflowBias === "refocus" ||
-		rawWorkflowBias === "next_round" ||
-		rawWorkflowBias === "unknown"
-			? rawWorkflowBias
-			: decision === "offer_workflow" && rawDecision === "route_to_cook"
-				? "unknown"
-				: "unknown";
-	const evidence = localAsStringArray(parsed.evidence);
-	const riskFlags = localAsStringArray(parsed.riskFlags ?? parsed.risk_flags);
-	const reason = asString(parsed.reason) ?? asString(parsed.rationale) ?? evidence[0] ?? `Classifier returned ${decision}.`;
-	const focusHint = asString(parsed.focusHint ?? parsed.focus_hint);
-	return {
-		decision,
-		confidence: confidenceFromUnknown(parsed.confidence),
-		workflowBias,
-		reason,
-		focusHint,
-		evidence: evidence.length > 0 ? evidence : [reason],
-		riskFlags,
-	};
-}
-
-function triggerClassifierFailureModeFromEnv(): "timeout" | "error" | "invalid_output" | undefined {
-	const raw = asString(process.env.PI_COMPLETION_TEST_TRIGGER_CLASSIFIER_FAILURE)?.toLowerCase();
-	return raw === "timeout" || raw === "error" || raw === "invalid_output" ? raw : undefined;
-}
-
-function triggerClassifierSnapshotPath(): string | undefined {
-	return asString(process.env.PI_COMPLETION_TEST_TRIGGER_CLASSIFIER_SNAPSHOT_PATH);
-}
-
-async function runCookTriggerClassifierSubprocess(
-	params: ClassifyCookTriggerIntentWithAgentParams & { prompt: string },
-): Promise<CookTriggerClassifierResult> {
-	const cwd = params.ctx.cwd;
-	const runCwd = findCompletionRoot(cwd) ?? findRepoRoot(cwd) ?? cwd;
-	const modelArg = contextProposalAnalystModelArg(params.ctx.model);
-	const systemPromptTemp = await writeTempFile(runCwd, "pi-cook-trigger-classifier-", COOK_TRIGGER_CLASSIFIER_SYSTEM_PROMPT);
-	const args: string[] = ["--mode", "json", "-p", "--no-session", "--no-extensions", "--append-system-prompt", systemPromptTemp.filePath];
-	if (modelArg) args.push("--model", modelArg);
-	args.push(params.prompt);
-	const invocation = getPiInvocation(args);
-	const liveActivity = createLiveRoleActivity("cook-trigger-classifier");
-	const messages: RoleMessage[] = [];
-	let stderr = "";
-	let timedOut = false;
-	try {
-		const rawOutput = await new Promise<string | undefined>((resolve) => {
-			const proc = spawn(invocation.command, invocation.args, {
-				cwd: runCwd,
-				env: process.env,
-				stdio: ["ignore", "pipe", "pipe"],
-				shell: false,
-			});
-			let settled = false;
-			let buffer = "";
-			const resolveOnce = (value: string | undefined) => {
-				if (settled) return;
-				settled = true;
-				resolve(value);
-			};
-			const timeoutHandle = setTimeout(() => {
-				timedOut = true;
-				proc.kill("SIGTERM");
-				resolveOnce(undefined);
-			}, COOK_TRIGGER_CLASSIFIER_TIMEOUT_MS);
-			const processLine = (line: string) => {
-				if (!line.trim()) return;
-				try {
-					const event = JSON.parse(line) as JsonRecord;
-					applyLiveRoleEvent(liveActivity, event, messages);
-				} catch {
-					// ignore malformed lines from the subprocess event stream
-				}
-			};
-			proc.stdout.on("data", (chunk) => {
-				buffer += chunk.toString();
-				const lines = buffer.split("\n");
-				buffer = lines.pop() ?? "";
-				for (const line of lines) processLine(line);
-			});
-			proc.stderr.on("data", (chunk) => {
-				stderr += chunk.toString();
-			});
-			proc.on("close", (code) => {
-				clearTimeout(timeoutHandle);
-				if (buffer.trim()) processLine(buffer);
-				if (timedOut) return;
-				resolveOnce(code === 0 ? liveActivity.lastAssistantText?.trim() || undefined : undefined);
-			});
-			proc.on("error", () => {
-				clearTimeout(timeoutHandle);
-				resolveOnce(undefined);
-			});
-		});
-		if (!rawOutput) {
-			if (timedOut) {
-				return {
-					status: "timeout",
-					errorMessage: `Trigger classifier timed out after ${COOK_TRIGGER_CLASSIFIER_TIMEOUT_MS}ms.`,
-				};
-			}
-			return { status: "error", errorMessage: stderr.trim() || "Trigger classifier produced no assistant output." };
-		}
-		const classification = parseCookTriggerClassification(rawOutput);
-		if (!classification) {
-			return {
-				status: "invalid_output",
-				rawOutput,
-				errorMessage: "Trigger classifier returned invalid JSON output.",
-			};
-		}
-		return { status: "classified", classification, rawOutput };
-	} finally {
-		await fsp.rm(systemPromptTemp.dir, { recursive: true, force: true });
-	}
-}
-
-export async function classifyCookTriggerIntentWithAgent(
-	params: ClassifyCookTriggerIntentWithAgentParams,
-): Promise<CookTriggerClassifierResult> {
-	const recentDiscussion = serializeRecentDiscussionEntries(params.recentEntries);
-	const prompt = buildCookTriggerClassifierPrompt({
-		projectName: params.projectName,
-		inputText: params.inputText,
-		recentDiscussion,
-		workflowContextLines: params.workflowContextLines,
-	});
-	const snapshotPath = triggerClassifierSnapshotPath();
-	const testFailureMode = triggerClassifierFailureModeFromEnv();
-	if (testFailureMode) {
-		const result: CookTriggerClassifierResult = {
-			status: testFailureMode,
-			errorMessage: `Forced trigger classifier ${testFailureMode} for deterministic tests.`,
-		};
-		maybeWriteCookTriggerClassifierSnapshot(
-			{
-				projectName: params.projectName,
-				inputText: params.inputText,
-				recentEntries: params.recentEntries,
-				workflowContextLines: params.workflowContextLines ?? [],
-				prompt,
-				result,
-			},
-			snapshotPath,
-		);
-		return result;
-	}
-	const testOutput = asString(process.env.PI_COMPLETION_TEST_TRIGGER_CLASSIFIER_OUTPUT);
-	if (testOutput) {
-		const classification = parseCookTriggerClassification(testOutput);
-		const result: CookTriggerClassifierResult = classification
-			? { status: "classified", classification, rawOutput: testOutput }
-			: {
-				status: "invalid_output",
-				rawOutput: testOutput,
-				errorMessage: "Trigger classifier test override did not match the required JSON schema.",
-			};
-		maybeWriteCookTriggerClassifierSnapshot(
-			{
-				projectName: params.projectName,
-				inputText: params.inputText,
-				recentEntries: params.recentEntries,
-				workflowContextLines: params.workflowContextLines ?? [],
-				prompt,
-				result,
-			},
-			snapshotPath,
-		);
-		return result;
-	}
-	try {
-		const result = await runCookTriggerClassifierSubprocess({ ...params, prompt });
-		maybeWriteCookTriggerClassifierSnapshot(
-			{
-				projectName: params.projectName,
-				inputText: params.inputText,
-				recentEntries: params.recentEntries,
-				workflowContextLines: params.workflowContextLines ?? [],
-				prompt,
-				result,
-			},
-			snapshotPath,
-		);
-		return result;
-	} catch (error) {
-		const result: CookTriggerClassifierResult = {
-			status: "error",
-			errorMessage: error instanceof Error ? error.message : String(error),
-		};
-		maybeWriteCookTriggerClassifierSnapshot(
-			{
-				projectName: params.projectName,
-				inputText: params.inputText,
-				recentEntries: params.recentEntries,
-				workflowContextLines: params.workflowContextLines ?? [],
-				prompt,
-				result,
-			},
-			snapshotPath,
-		);
-		return result;
-	}
-}
 
 export async function loadAgentDefinition(cwd: string, role: CompletionRole): Promise<AgentDefinition> {
 	const projectAgent = walkUpForDir(cwd, [".pi", "agents", `${role}.md`]);
@@ -683,7 +377,6 @@ export function getPiInvocation(args: string[]): { command: string; args: string
 
 export async function runCompletionRole(params: RunCompletionRoleParams): Promise<RunCompletionRoleResult> {
 	const agent = await loadAgentDefinition(params.root, params.role);
-	await loadCompletionDataForReminder(params.root);
 	const systemPromptTemp = await writeTempFile(params.root, "pi-completion-role-", agent.systemPrompt);
 	const taskLines = [...params.systemPromptPreamble];
 	if (params.evaluationContextLines?.length) taskLines.push("", ...params.evaluationContextLines);

package/extensions/completion/state-store.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { spawnSync } from "node:child_process";
 import { promises as fsp } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -7,6 +8,13 @@ import type { CompletionStateSnapshot, JsonRecord } from "./types";
 const PROTOCOL_ID = "completion";
 const DEFAULT_TASK_TYPE = "completion-workflow";
 const DEFAULT_EVALUATION_PROFILE = "completion-rubric-v1";
+const TRACKED_CONTRACT_FILES = [
+	".agent/README.md",
+	".agent/mission.md",
+	".agent/profile.json",
+	".agent/verify_completion_stop.sh",
+	".agent/verify_completion_control_plane.sh",
+] as const;
 
 function isRecord(value: unknown): value is JsonRecord {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -223,10 +231,12 @@ export function buildProfileRecord(args: {
 export function defaultState(
 	missionAnchor: string,
 	routing?: { taskType?: string; evaluationProfile?: string; continuationReason?: string },
+	advisoryStartupBrief?: JsonRecord,
 ): JsonRecord {
 	return {
 		schema_version: 1,
 		mission_anchor: missionAnchor,
+		advisory_startup_brief: advisoryStartupBrief ?? null,
 		current_phase: "reground",
 		continuation_policy: "continue",
 		continuation_reason: routing?.continuationReason ?? "Fresh completion bootstrap requires canonical re-ground",
@@ -330,8 +340,18 @@ export function buildVerifyControlPlaneScript(): string {
 	if (fs.existsSync(trackedScriptPath)) {
 		return fs.readFileSync(trackedScriptPath, "utf8");
 	}
-	return `#!/usr/bin/env node
+	return `#!/usr/bin/env bash
+':' //; exec node "$0" "$@"
 const fs = require('node:fs');
+const { spawnSync } = require('node:child_process');
+
+const REQUIRED_TRACKED_CONTRACT_FILES = [
+  '.agent/README.md',
+  '.agent/mission.md',
+  '.agent/profile.json',
+  '.agent/verify_completion_stop.sh',
+  '.agent/verify_completion_control_plane.sh',
+];
 
 function fail(message) {
   console.error(message);
@@ -346,8 +366,182 @@ function readJson(file) {
   }
 }
 
-for (const file of ['.agent/profile.json', '.agent/state.json', '.agent/plan.json', '.agent/active-slice.json', '.agent/verification-evidence.json']) {
-  readJson(file);
+function asString(value) {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function asNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function asStringArray(value) {
+  return Array.isArray(value)
+    ? value.filter((item) => typeof item === 'string' && item.trim().length > 0)
+    : [];
+}
+
+function sameStringArrays(left, right) {
+  return left.length === right.length && left.every((item, index) => item === right[index]);
+}
+
+function runGit(args, options = {}) {
+  const result = spawnSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  if (!options.allowFailure && result.status !== 0) {
+    const stderr = asString(result.stderr) ?? 'git command failed';
+    fail(\`git \${args.join(' ')} failed: \${stderr}\`);
+  }
+  return result;
+}
+
+function gitHeadSha() {
+  const result = runGit(['rev-parse', 'HEAD'], { allowFailure: true });
+  return result.status === 0 ? asString(result.stdout) : undefined;
+}
+
+function ensureTrackedContractFiles() {
+  for (const file of REQUIRED_TRACKED_CONTRACT_FILES) {
+    const result = runGit(['ls-files', '--error-unmatch', file], { allowFailure: true });
+    if (result.status !== 0) {
+      fail(\`Required tracked completion contract file is missing from git index: \${file}\`);
+    }
+  }
+}
+
+function ensureCommitExists(commitish, label) {
+  const result = runGit(['rev-parse', '--verify', \`\${commitish}^{commit}\`], { allowFailure: true });
+  if (result.status !== 0) {
+    fail(\`\${label} must resolve to an existing commit: \${commitish}\`);
+  }
+}
+
+function trackedDiffFiles(fromCommit, toCommit) {
+  const result = runGit(['diff', '--name-only', '--diff-filter=ACMR', \`\${fromCommit}..\${toCommit}\`]);
+  return result.stdout
+    .split(/\\r?\\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+const profile = readJson('.agent/profile.json');
+const state = readJson('.agent/state.json');
+const plan = readJson('.agent/plan.json');
+const active = readJson('.agent/active-slice.json');
+const evidence = readJson('.agent/verification-evidence.json');
+
+ensureTrackedContractFiles();
+
+for (const [file, record] of [
+  ['.agent/profile.json', profile],
+  ['.agent/state.json', state],
+  ['.agent/plan.json', plan],
+  ['.agent/active-slice.json', active],
+]) {
+  if (!asString(record.task_type)) fail(file + ' is missing task_type');
+  if (!asString(record.evaluation_profile)) fail(file + ' is missing evaluation_profile');
+}
+
+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(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(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(evidence.artifact_type) !== 'completion-verification-evidence') {
+  fail('.agent/verification-evidence.json artifact_type must be completion-verification-evidence');
+}
+
+const exactStatuses = new Set(['selected', 'in_progress', 'committed', 'done']);
+const activeStatus = asString(active.status);
+const exactHandoff = exactStatuses.has(activeStatus || '');
+const planSlices = Array.isArray(plan.candidate_slices) ? plan.candidate_slices : [];
+const activeSliceId = asString(active.slice_id);
+const planSlice = activeSliceId ? planSlices.find((slice) => asString(slice && slice.slice_id) === activeSliceId) : undefined;
+
+if (exactHandoff && !planSlice) {
+  fail('slice_id must match a slice in .agent/plan.json when status carries an exact handoff');
+}
+
+if (exactHandoff) {
+  const requiredStringFields = ['goal', 'why_now', 'basis_commit'];
+  for (const field of requiredStringFields) {
+    if (!asString(active[field])) fail('.agent/active-slice.json is missing ' + field + ' when status carries an exact handoff');
+  }
+  const requiredArrayFields = ['contract_ids', 'acceptance_criteria', 'blocked_on', 'locked_notes', 'must_fix_findings', 'implementation_surfaces', 'verification_commands', 'remaining_contract_ids_before'];
+  for (const field of requiredArrayFields) {
+    if (!Array.isArray(active[field])) fail('.agent/active-slice.json is missing ' + field + ' when status carries an exact handoff');
+  }
+  const requiredNumberFields = ['priority', 'release_blocker_count_before', 'high_value_gap_count_before'];
+  for (const field of requiredNumberFields) {
+    if (asNumber(active[field]) === undefined) fail('.agent/active-slice.json is missing ' + field + ' when status carries an exact handoff');
+  }
+
+  const mismatchFields = [];
+  if (asString(planSlice.slice_id) !== activeSliceId) mismatchFields.push('slice_id');
+  if (asString(planSlice.goal) !== asString(active.goal)) mismatchFields.push('goal');
+  if (!sameStringArrays(asStringArray(planSlice.contract_ids), asStringArray(active.contract_ids))) mismatchFields.push('contract_ids');
+  if (!sameStringArrays(asStringArray(planSlice.acceptance_criteria), asStringArray(active.acceptance_criteria))) mismatchFields.push('acceptance_criteria');
+  if (!sameStringArrays(asStringArray(planSlice.blocked_on), asStringArray(active.blocked_on))) mismatchFields.push('blocked_on');
+  if (asNumber(planSlice.priority) !== asNumber(active.priority)) mismatchFields.push('priority');
+  if (asString(planSlice.why_now) !== asString(active.why_now)) mismatchFields.push('why_now');
+  const planMirrorFields = ['locked_notes', 'must_fix_findings', 'implementation_surfaces', 'verification_commands', 'basis_commit', 'remaining_contract_ids_before', 'release_blocker_count_before', 'high_value_gap_count_before'];
+  for (const field of planMirrorFields) {
+    const planValue = planSlice[field];
+    const activeValue = active[field];
+    if (Array.isArray(planValue) || Array.isArray(activeValue)) {
+      if (!sameStringArrays(asStringArray(planValue), asStringArray(activeValue))) mismatchFields.push(field);
+      continue;
+    }
+    if (typeof planValue === 'number' || typeof activeValue === 'number') {
+      if (asNumber(planValue) !== asNumber(activeValue)) mismatchFields.push(field);
+      continue;
+    }
+    if (asString(planValue) !== asString(activeValue)) mismatchFields.push(field);
+  }
+  if (mismatchFields.length > 0) {
+    fail('.agent/active-slice.json must match the selected .agent/plan.json slice across: ' + mismatchFields.join(', '));
+  }
+
+  if (asString(evidence.subject_type) !== 'selected_slice') {
+    fail('subject_type must be selected_slice when active slice exact handoff requires verification evidence');
+  }
+  if (asString(evidence.slice_id) !== activeSliceId) fail('.agent/verification-evidence.json slice_id must match .agent/active-slice.json slice_id');
+  if (asString(evidence.goal) !== asString(active.goal)) fail('.agent/verification-evidence.json goal must match .agent/active-slice.json goal');
+  if (!sameStringArrays(asStringArray(evidence.contract_ids), asStringArray(active.contract_ids))) fail('.agent/verification-evidence.json contract_ids must match .agent/active-slice.json contract_ids');
+  if (asString(evidence.basis_commit) !== asString(active.basis_commit)) fail('.agent/verification-evidence.json basis_commit must match .agent/active-slice.json basis_commit');
+  if (!sameStringArrays(asStringArray(evidence.verification_commands), asStringArray(active.verification_commands))) {
+    fail('.agent/verification-evidence.json verification_commands must match .agent/active-slice.json verification_commands');
+  }
+  if (!asString(evidence.recorded_at)) fail('.agent/verification-evidence.json recorded_at must be present for selected-slice evidence');
+  if (asString(evidence.outcome) === 'not_recorded') fail('.agent/verification-evidence.json outcome must not be not_recorded for selected-slice evidence');
+  const headSha = gitHeadSha();
+  if (headSha && asString(evidence.head_sha) !== headSha) {
+    fail('.agent/verification-evidence.json head_sha must match current HEAD');
+  }
+
+  const basisCommit = asString(active.basis_commit);
+  if (basisCommit && headSha) {
+    ensureCommitExists(basisCommit, '.agent/active-slice.json basis_commit');
+    const ancestorCheck = runGit(['merge-base', '--is-ancestor', basisCommit, headSha], { allowFailure: true });
+    if (ancestorCheck.status !== 0) {
+      fail(\`.agent/active-slice.json basis_commit must be an ancestor of current HEAD: \${basisCommit} -> \${headSha}\`);
+    }
+    const changedFiles = trackedDiffFiles(basisCommit, headSha);
+    const implementationSurfaces = new Set(asStringArray(active.implementation_surfaces));
+    const missingSurfaces = changedFiles.filter((file) => !implementationSurfaces.has(file));
+    if (missingSurfaces.length > 0) {
+      fail('.agent/active-slice.json implementation_surfaces must cover every tracked file changed from basis_commit to current HEAD; missing: ' + missingSurfaces.join(', '));
+    }
+  }
+} else {
+  const subjectType = asString(evidence.subject_type);
+  if (subjectType === 'none') {
+    if (asString(evidence.outcome) && asString(evidence.outcome) !== 'not_recorded') {
+      fail('.agent/verification-evidence.json outcome must stay not_recorded when subject_type=none');
+    }
+  }
 }
 `;
 }
@@ -379,6 +573,18 @@ async function ensureGitignore(root: string): Promise<boolean> {
 	return true;
 }
 
+async function stageTrackedContractFiles(root: string): Promise<void> {
+	if (!(await pathExists(path.join(root, ".git")))) return;
+	const result = spawnSync("git", ["-C", root, "add", "--", ...TRACKED_CONTRACT_FILES], {
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "pipe"],
+	});
+	if (result.status !== 0) {
+		const stderr = asString(result.stderr) ?? "git add failed while staging completion contract files";
+		throw new Error(stderr);
+	}
+}
+
 export type ScaffoldResult = {
 	root: string;
 	created: string[];
@@ -389,7 +595,7 @@ export type ScaffoldResult = {
 export async function scaffoldCompletionFiles(
 	root: string,
 	missionAnchor: string,
-	options?: { analysis?: { taskType?: string; evaluationProfile?: string }; continuationReason?: string },
+	options?: { analysis?: { taskType?: string; evaluationProfile?: string }; continuationReason?: string; advisoryStartupBrief?: JsonRecord },
 ): Promise<ScaffoldResult> {
 	const files = resolveFiles(root);
 	const created: string[] = [];
@@ -410,7 +616,7 @@ export async function scaffoldCompletionFiles(
 		{ path: path.join(files.agentDir, "verify_completion_control_plane.sh"), content: buildVerifyControlPlaneScript(), executable: true },
 		{
 			path: files.statePath,
-			content: `${JSON.stringify(defaultState(missionAnchor, { taskType: options?.analysis?.taskType, evaluationProfile: options?.analysis?.evaluationProfile, continuationReason: options?.continuationReason }), null, 2)}\n`,
+			content: `${JSON.stringify(defaultState(missionAnchor, { taskType: options?.analysis?.taskType, evaluationProfile: options?.analysis?.evaluationProfile, continuationReason: options?.continuationReason }, options?.advisoryStartupBrief), null, 2)}\n`,
 		},
 		{ path: files.planPath, content: `${JSON.stringify(defaultPlan(missionAnchor, { taskType: options?.analysis?.taskType, evaluationProfile: options?.analysis?.evaluationProfile }), null, 2)}\n` },
 		{ path: files.activePath, content: `${JSON.stringify(defaultActiveSlice(missionAnchor, { taskType: options?.analysis?.taskType, evaluationProfile: options?.analysis?.evaluationProfile }), null, 2)}\n` },
@@ -425,6 +631,7 @@ export async function scaffoldCompletionFiles(
 		created.push(path.relative(root, file.path));
 	}
 	if (await ensureGitignore(root)) updated.push(".gitignore");
+	await stageTrackedContractFiles(root);
 	return { root, created, updated, missionAnchor };
 }
 

package/extensions/completion/transcription.ts

@@ -17,14 +17,6 @@ export function parseReportFields(text: string): Record<string, string> {
 	return roleReporting.parseReportFields(text);
 }
 
-export function parseYesNo(value: string | undefined): boolean | undefined {
-	return roleReporting.parseYesNo(value);
-}
-
-export function parseFirstNumber(value: string | undefined): number | undefined {
-	return roleReporting.parseFirstNumber(value);
-}
-
 async function gitHeadSha(cwd: string): Promise<string | undefined> {
 	return await new Promise((resolve) => {
 		const proc = spawn("git", ["rev-parse", "HEAD"], { cwd, stdio: ["ignore", "pipe", "ignore"] });